11 files changed, 797 insertions, 0 deletions
diff --git a/lib/public/SystemTag/ISystemTag.php b/lib/public/SystemTag/ISystemTag.php
new file mode 100644
index 00000000000..4fd93831955
--- /dev/null
+++ b/lib/public/SystemTag/ISystemTag.php
@@ -0,0 +1,99 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\SystemTag;
+
+/**
+ * Public interface for a system-wide tag.
+ *
+ * @since 9.0.0
+ */
+interface ISystemTag {
+	/**
+	 * @since 22.0.0
+	 */
+	public const ACCESS_LEVEL_PUBLIC = 0;
+	/**
+	 * @since 22.0.0
+	 */
+	public const ACCESS_LEVEL_RESTRICTED = 1;
+	/**
+	 * @since 22.0.0
+	 */
+	public const ACCESS_LEVEL_INVISIBLE = 2;
+
+	/**
+	 * @since 22.0.0
+	 */
+	public const ACCESS_LEVEL_LOOKUP = [
+		ISystemTag::ACCESS_LEVEL_PUBLIC => 'public',
+		ISystemTag::ACCESS_LEVEL_RESTRICTED => 'restricted',
+		ISystemTag::ACCESS_LEVEL_INVISIBLE => 'invisible',
+	];
+
+	/**
+	 * Returns the tag id
+	 *
+	 * @return string id
+	 *
+	 * @since 9.0.0
+	 */
+	public function getId(): string;
+
+	/**
+	 * Returns the tag display name
+	 *
+	 * @return string tag display name
+	 *
+	 * @since 9.0.0
+	 */
+	public function getName(): string;
+
+	/**
+	 * Returns whether the tag is visible for regular users
+	 *
+	 * @return bool true if visible, false otherwise
+	 *
+	 * @since 9.0.0
+	 */
+	public function isUserVisible(): bool;
+
+	/**
+	 * Returns whether the tag can be assigned to objects by regular users
+	 *
+	 * @return bool true if assignable, false otherwise
+	 *
+	 * @since 9.0.0
+	 */
+	public function isUserAssignable(): bool;
+
+	/**
+	 * Returns a term summarizing the access control flags
+	 *
+	 * @return int the level of access control
+	 *
+	 * @since 22.0.0
+	 */
+	public function getAccessLevel(): int;
+
+	/**
+	 * Returns the ETag of the tag
+	 * The ETag is a unique identifier for the tag and should change whenever the tag changes
+	 * or whenever elements gets added or removed from the tag.
+	 *
+	 * @since 31.0.0
+	 */
+	public function getETag(): ?string;
+
+	/**
+	 * Returns the color of the tag
+	 *
+	 * @since 31.0.0
+	 */
+	public function getColor(): ?string;
+}
diff --git a/lib/public/SystemTag/ISystemTagManager.php b/lib/public/SystemTag/ISystemTagManager.php
new file mode 100644
index 00000000000..96e775d6401
--- /dev/null
+++ b/lib/public/SystemTag/ISystemTagManager.php
@@ -0,0 +1,175 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\SystemTag;
+
+use OCP\IUser;
+
+/**
+ * Public interface to access and manage system-wide tags.
+ *
+ * @since 9.0.0
+ */
+interface ISystemTagManager {
+	/**
+	 * Returns the tag objects matching the given tag ids.
+	 *
+	 * @param array|string $tagIds id or array of unique ids of the tag to retrieve
+	 * @param ?IUser $user optional user to run a visibility check against for each tag
+	 *
+	 * @return ISystemTag[] array of system tags with tag id as key
+	 *
+	 * @throws \InvalidArgumentException if at least one given tag ids is invalid (string instead of integer, etc.)
+	 * @throws TagNotFoundException if at least one given tag ids did no exist
+	 *                              The message contains a json_encoded array of the ids that could not be found
+	 *
+	 * @since 9.0.0, optional parameter $user added in 28.0.0
+	 */
+	public function getTagsByIds($tagIds, ?IUser $user = null): array;
+
+	/**
+	 * Returns the tag object matching the given attributes.
+	 *
+	 * @param string $tagName tag name
+	 * @param bool $userVisible whether the tag is visible by users
+	 * @param bool $userAssignable whether the tag is assignable by users
+	 *
+	 * @return ISystemTag system tag
+	 *
+	 * @throws TagNotFoundException if tag does not exist
+	 *
+	 * @since 9.0.0
+	 */
+	public function getTag(string $tagName, bool $userVisible, bool $userAssignable): ISystemTag;
+
+	/**
+	 * Creates the tag object using the given attributes.
+	 *
+	 * @param string $tagName tag name
+	 * @param bool $userVisible whether the tag is visible by users
+	 * @param bool $userAssignable whether the tag is assignable by users
+	 *
+	 * @return ISystemTag system tag
+	 *
+	 * @throws TagAlreadyExistsException if tag already exists
+	 * @throws TagCreationForbiddenException if user doesn't have the right to create a new tag
+	 *
+	 * @since 9.0.0
+	 * @since 31.0.0 Can throw TagCreationForbiddenExceptionif user doesn't have the right to create a new tag
+	 */
+	public function createTag(string $tagName, bool $userVisible, bool $userAssignable): ISystemTag;
+
+	/**
+	 * Returns all known tags, optionally filtered by visibility.
+	 *
+	 * @param bool|null $visibilityFilter filter by visibility if non-null
+	 * @param string $nameSearchPattern optional search pattern for the tag name
+	 *
+	 * @return ISystemTag[] array of system tags or empty array if none found
+	 *
+	 * @since 9.0.0
+	 */
+	public function getAllTags($visibilityFilter = null, $nameSearchPattern = null): array;
+
+	/**
+	 * Updates the given tag
+	 *
+	 * @param string $tagId tag id
+	 * @param string $newName the new tag name
+	 * @param bool $userVisible whether the tag is visible by users
+	 * @param bool $userAssignable whether the tag is assignable by users
+	 * @param string $color color
+	 *
+	 * @throws TagNotFoundException if tag with the given id does not exist
+	 * @throws TagAlreadyExistsException if there is already another tag
+	 *                                   with the same attributes
+	 *
+	 * @since 9.0.0
+	 * @since 31.0.0 `$color` parameter added
+	 */
+	public function updateTag(string $tagId, string $newName, bool $userVisible, bool $userAssignable, ?string $color);
+
+	/**
+	 * Delete the given tags from the database and all their relationships.
+	 *
+	 * @param string|array $tagIds array of tag ids
+	 *
+	 * @throws TagNotFoundException if at least one tag did not exist
+	 *
+	 * @since 9.0.0
+	 */
+	public function deleteTags($tagIds);
+
+	/**
+	 * Checks whether the given user is allowed to assign/unassign the tag with the
+	 * given id.
+	 *
+	 * @param ISystemTag $tag tag to check permission for
+	 * @param IUser|null $user user to check permission for
+	 *
+	 * @return bool true if the user is allowed to assign/unassign the tag, false otherwise
+	 *
+	 * @since 9.1.0
+	 * @since 31.0.0 `$user` can be null to check anonymous permissions
+	 */
+	public function canUserAssignTag(ISystemTag $tag, ?IUser $user): bool;
+
+	/**
+	 * Checks whether the given user is allowed to create new tags
+	 *
+	 * @param IUser|null $user user to check permission for
+	 * @return bool true if the user is allowed to create a new tag, false otherwise
+	 *
+	 * @since 31.0.0
+	 */
+	public function canUserCreateTag(?IUser $user): bool;
+
+	/**
+	 * Checks whether the given user is allowed to update tags
+	 *
+	 * @param IUser|null $user user to check permission for
+	 * @return bool true if the user is allowed to update a tag, false otherwise
+	 *
+	 * @since 31.0.0
+	 */
+	public function canUserUpdateTag(?IUser $user): bool;
+
+	/**
+	 * Checks whether the given user is allowed to see the tag with the given id.
+	 *
+	 * @param ISystemTag $tag tag to check permission for
+	 * @param IUser|null $user user to check permission for
+	 *
+	 * @return bool true if the user can see the tag, false otherwise
+	 *
+	 * @since 9.1.0
+	 * @since 31.0.0 `$user` can be null to check anonymous permissions
+	 */
+	public function canUserSeeTag(ISystemTag $tag, ?IUser $user): bool;
+
+	/**
+	 * Set groups that can assign a given tag.
+	 *
+	 * @param ISystemTag $tag tag for group assignment
+	 * @param string[] $groupIds group ids of groups that can assign/unassign the tag
+	 *
+	 * @since 9.1.0
+	 */
+	public function setTagGroups(ISystemTag $tag, array $groupIds);
+
+	/**
+	 * Get groups that can assign a given tag.
+	 *
+	 * @param ISystemTag $tag tag for group assignment
+	 *
+	 * @return string[] group ids of groups that can assign/unassign the tag
+	 *
+	 * @since 9.1.0
+	 */
+	public function getTagGroups(ISystemTag $tag): array;
+}
diff --git a/lib/public/SystemTag/ISystemTagManagerFactory.php b/lib/public/SystemTag/ISystemTagManagerFactory.php
new file mode 100644
index 00000000000..e6c10568d16
--- /dev/null
+++ b/lib/public/SystemTag/ISystemTagManagerFactory.php
@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\SystemTag;
+
+use OCP\IServerContainer;
+
+/**
+ * Interface ISystemTagManagerFactory
+ *
+ * Factory interface for system tag managers
+ *
+ * @since 9.0.0
+ */
+interface ISystemTagManagerFactory {
+	/**
+	 * Constructor for the system tag manager factory
+	 *
+	 * @param IServerContainer $serverContainer server container
+	 * @since 9.0.0
+	 */
+	public function __construct(IServerContainer $serverContainer);
+
+	/**
+	 * creates and returns an instance of the system tag manager
+	 *
+	 * @return ISystemTagManager
+	 * @since 9.0.0
+	 */
+	public function getManager(): ISystemTagManager;
+
+	/**
+	 * creates and returns an instance of the system tag object
+	 * mapper
+	 *
+	 * @return ISystemTagObjectMapper
+	 * @since 9.0.0
+	 */
+	public function getObjectMapper(): ISystemTagObjectMapper;
+}
diff --git a/lib/public/SystemTag/ISystemTagObjectMapper.php b/lib/public/SystemTag/ISystemTagObjectMapper.php
new file mode 100644
index 00000000000..c604fa93c58
--- /dev/null
+++ b/lib/public/SystemTag/ISystemTagObjectMapper.php
@@ -0,0 +1,137 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\SystemTag;
+
+/**
+ * Public interface to access and manage system-wide tags.
+ *
+ * @since 9.0.0
+ */
+interface ISystemTagObjectMapper {
+	/**
+	 * Get a list of tag ids for the given object ids.
+	 *
+	 * This returns an array that maps object id to tag ids
+	 * [
+	 *   1 => array('id1', 'id2'),
+	 *   2 => array('id3', 'id2'),
+	 *   3 => array('id5'),
+	 *   4 => array()
+	 * ]
+	 *
+	 * Untagged objects will have an empty array associated.
+	 *
+	 * @param string|array $objIds object ids
+	 * @param string $objectType object type
+	 *
+	 * @return array with object id as key and an array
+	 *               of tag ids as value
+	 *
+	 * @since 9.0.0
+	 */
+	public function getTagIdsForObjects($objIds, string $objectType): array;
+
+	/**
+	 * Get a list of objects tagged with $tagIds.
+	 *
+	 * @param string|array $tagIds Tag id or array of tag ids.
+	 * @param string $objectType object type
+	 * @param int $limit Count of object ids you want to get
+	 * @param string $offset The last object id you already received
+	 *
+	 * @return string[] array of object ids or empty array if none found
+	 *
+	 * @throws TagNotFoundException if at least one of the
+	 *                              given tags does not exist
+	 * @throws \InvalidArgumentException When a limit is specified together with
+	 *                                   multiple tag ids
+	 *
+	 * @since 9.0.0
+	 */
+	public function getObjectIdsForTags($tagIds, string $objectType, int $limit = 0, string $offset = ''): array;
+
+	/**
+	 * Assign the given tags to the given object.
+	 *
+	 * If at least one of the given tag ids doesn't exist, none of the tags
+	 * will be assigned.
+	 *
+	 * If the relationship already existed, fail silently.
+	 *
+	 * @param string $objId object id
+	 * @param string $objectType object type
+	 * @param string|array $tagIds tag id or array of tag ids to assign
+	 *
+	 * @throws TagNotFoundException if at least one of the
+	 *                              given tags does not exist
+	 *
+	 * @since 9.0.0
+	 */
+	public function assignTags(string $objId, string $objectType, $tagIds);
+
+	/**
+	 * Unassign the given tags from the given object.
+	 *
+	 * If at least one of the given tag ids doesn't exist, none of the tags
+	 * will be unassigned.
+	 *
+	 * If the relationship did not exist in the first place, fail silently.
+	 *
+	 * @param string $objId object id
+	 * @param string $objectType object type
+	 * @param string|array $tagIds tag id or array of tag ids to unassign
+	 *
+	 * @throws TagNotFoundException if at least one of the
+	 *                              given tags does not exist
+	 *
+	 * @since 9.0.0
+	 */
+	public function unassignTags(string $objId, string $objectType, $tagIds);
+
+	/**
+	 * Checks whether the given objects have the given tag.
+	 *
+	 * @param string|array $objIds object ids
+	 * @param string $objectType object type
+	 * @param string $tagId tag id to check
+	 * @param bool $all true to check that ALL objects have the tag assigned,
+	 *                  false to check that at least ONE object has the tag.
+	 *
+	 * @return bool true if the condition set by $all is matched, false
+	 *              otherwise
+	 *
+	 * @throws TagNotFoundException if the tag does not exist
+	 *
+	 * @since 9.0.0
+	 */
+	public function haveTag($objIds, string $objectType, string $tagId, bool $all = true): bool;
+
+
+	/**
+	 * Get the list of object types that have objects assigned to them.
+	 *
+	 * @return string[] list of object types
+	 *
+	 * @since 31.0.0
+	 */
+	public function getAvailableObjectTypes(): array;
+
+	/**
+	 * Set the list of object ids for the given tag.
+	 * This will replace the current list of object ids.
+	 *
+	 * @param string $tagId tag id
+	 * @param string $objectType object type
+	 * @param string[] $objectIds list of object ids
+	 *
+	 * @throws TagNotFoundException if the tag does not exist
+	 * @since 31.0.0
+	 */
+	public function setObjectIdsForTag(string $tagId, string $objectType, array $objectIds): void;
+}
diff --git a/lib/public/SystemTag/ManagerEvent.php b/lib/public/SystemTag/ManagerEvent.php
new file mode 100644
index 00000000000..adfe64f8658
--- /dev/null
+++ b/lib/public/SystemTag/ManagerEvent.php
@@ -0,0 +1,85 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\SystemTag;
+
+use OCP\EventDispatcher\Event;
+
+/**
+ * Class ManagerEvent
+ *
+ * @since 9.0.0
+ */
+class ManagerEvent extends Event {
+	/**
+	 * @since 9.0.0
+	 * @deprecated 22.0.0
+	 */
+	public const EVENT_CREATE = 'OCP\SystemTag\ISystemTagManager::createTag';
+
+	/**
+	 * @since 9.0.0
+	 * @deprecated 22.0.0
+	 */
+	public const EVENT_UPDATE = 'OCP\SystemTag\ISystemTagManager::updateTag';
+
+	/**
+	 * @since 9.0.0
+	 * @deprecated 22.0.0
+	 */
+	public const EVENT_DELETE = 'OCP\SystemTag\ISystemTagManager::deleteTag';
+
+	/** @var string */
+	protected $event;
+	/** @var ISystemTag */
+	protected $tag;
+	/** @var ISystemTag */
+	protected $beforeTag;
+
+	/**
+	 * DispatcherEvent constructor.
+	 *
+	 * @param string $event
+	 * @param ISystemTag $tag
+	 * @param ISystemTag|null $beforeTag
+	 * @since 9.0.0
+	 */
+	public function __construct(string $event, ISystemTag $tag, ?ISystemTag $beforeTag = null) {
+		$this->event = $event;
+		$this->tag = $tag;
+		$this->beforeTag = $beforeTag;
+	}
+
+	/**
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getEvent(): string {
+		return $this->event;
+	}
+
+	/**
+	 * @return ISystemTag
+	 * @since 9.0.0
+	 */
+	public function getTag(): ISystemTag {
+		return $this->tag;
+	}
+
+	/**
+	 * @return ISystemTag
+	 * @since 9.0.0
+	 * @throws \BadMethodCallException
+	 */
+	public function getTagBefore(): ISystemTag {
+		if ($this->event !== self::EVENT_UPDATE) {
+			throw new \BadMethodCallException('getTagBefore is only available on the update Event');
+		}
+		return $this->beforeTag;
+	}
+}
diff --git a/lib/public/SystemTag/MapperEvent.php b/lib/public/SystemTag/MapperEvent.php
new file mode 100644
index 00000000000..821d1b5dc5e
--- /dev/null
+++ b/lib/public/SystemTag/MapperEvent.php
@@ -0,0 +1,101 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\SystemTag;
+
+use OCP\EventDispatcher\Event;
+use OCP\EventDispatcher\IWebhookCompatibleEvent;
+
+/**
+ * Class MapperEvent
+ *
+ * @since 9.0.0
+ */
+class MapperEvent extends Event implements IWebhookCompatibleEvent {
+	/**
+	 * @since 9.0.0
+	 * @deprecated 22.0.0
+	 */
+	public const EVENT_ASSIGN = 'OCP\SystemTag\ISystemTagObjectMapper::assignTags';
+
+	/**
+	 * @since 9.0.0
+	 * @deprecated 22.0.0
+	 */
+	public const EVENT_UNASSIGN = 'OCP\SystemTag\ISystemTagObjectMapper::unassignTags';
+
+	/** @var string */
+	protected $event;
+	/** @var string */
+	protected $objectType;
+	/** @var string */
+	protected $objectId;
+	/** @var int[] */
+	protected $tags;
+
+	/**
+	 * DispatcherEvent constructor.
+	 *
+	 * @param string $event
+	 * @param string $objectType
+	 * @param string $objectId
+	 * @param int[] $tags
+	 * @since 9.0.0
+	 */
+	public function __construct(string $event, string $objectType, string $objectId, array $tags) {
+		$this->event = $event;
+		$this->objectType = $objectType;
+		$this->objectId = $objectId;
+		$this->tags = $tags;
+	}
+
+	/**
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getEvent(): string {
+		return $this->event;
+	}
+
+	/**
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getObjectType(): string {
+		return $this->objectType;
+	}
+
+	/**
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getObjectId(): string {
+		return $this->objectId;
+	}
+
+	/**
+	 * @return int[]
+	 * @since 9.0.0
+	 */
+	public function getTags(): array {
+		return $this->tags;
+	}
+
+	/**
+	 * @return array
+	 * @since 32.0.0
+	 */
+	public function getWebhookSerializable(): array {
+		return [
+			'eventType' => $this->getEvent(),
+			'objectType' => $this->getObjectType(),
+			'objectId' => $this->getObjectId(),
+			'tagIds' => $this->getTags(),
+		];
+	}
+}
diff --git a/lib/public/SystemTag/SystemTagsEntityEvent.php b/lib/public/SystemTag/SystemTagsEntityEvent.php
new file mode 100644
index 00000000000..d8f391d0dba
--- /dev/null
+++ b/lib/public/SystemTag/SystemTagsEntityEvent.php
@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\SystemTag;
+
+use OCP\EventDispatcher\Event;
+
+/**
+ * Class SystemTagsEntityEvent
+ *
+ * @since 9.1.0
+ * @since 28.0.0 Dispatched as a typed event
+ */
+class SystemTagsEntityEvent extends Event {
+	/**
+	 * @since 9.1.0
+	 * @deprecated 22.0.0 Listen to the typed event instead
+	 */
+	public const EVENT_ENTITY = 'OCP\SystemTag\ISystemTagManager::registerEntity';
+
+	/** @var \Closure[] */
+	protected $collections;
+
+	/**
+	 * @since 9.1.0
+	 */
+	public function __construct() {
+		parent::__construct();
+		$this->collections = [];
+	}
+
+	/**
+	 * @param string $name
+	 * @param \Closure $entityExistsFunction The closure should take one
+	 *                                       argument, which is the id of the entity, that tags
+	 *                                       should be handled for. The return should then be bool,
+	 *                                       depending on whether tags are allowed (true) or not.
+	 * @throws \OutOfBoundsException when the entity name is already taken
+	 * @since 9.1.0
+	 */
+	public function addEntityCollection(string $name, \Closure $entityExistsFunction) {
+		if (isset($this->collections[$name])) {
+			throw new \OutOfBoundsException('Duplicate entity name "' . $name . '"');
+		}
+
+		$this->collections[$name] = $entityExistsFunction;
+	}
+
+	/**
+	 * @return \Closure[]
+	 * @since 9.1.0
+	 */
+	public function getEntityCollections(): array {
+		return $this->collections;
+	}
+}
diff --git a/lib/public/SystemTag/TagAlreadyExistsException.php b/lib/public/SystemTag/TagAlreadyExistsException.php
new file mode 100644
index 00000000000..9db94bc4124
--- /dev/null
+++ b/lib/public/SystemTag/TagAlreadyExistsException.php
@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\SystemTag;
+
+/**
+ * Exception when a tag already exists.
+ *
+ * @since 9.0.0
+ */
+class TagAlreadyExistsException extends \RuntimeException {
+}
diff --git a/lib/public/SystemTag/TagCreationForbiddenException.php b/lib/public/SystemTag/TagCreationForbiddenException.php
new file mode 100644
index 00000000000..eeae38e31f7
--- /dev/null
+++ b/lib/public/SystemTag/TagCreationForbiddenException.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+namespace OCP\SystemTag;
+
+/**
+ * Exception when a user doesn't have the right to create a tag
+ *
+ * @since 31.0.0
+ */
+class TagCreationForbiddenException extends \RuntimeException {
+}
diff --git a/lib/public/SystemTag/TagNotFoundException.php b/lib/public/SystemTag/TagNotFoundException.php
new file mode 100644
index 00000000000..8a143422fff
--- /dev/null
+++ b/lib/public/SystemTag/TagNotFoundException.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\SystemTag;
+
+/**
+ * Exception when a tag was not found.
+ *
+ * @since 9.0.0
+ */
+class TagNotFoundException extends \RuntimeException {
+	/** @var string[] */
+	protected $tags;
+
+	/**
+	 * TagNotFoundException constructor.
+	 *
+	 * @param string $message
+	 * @param int $code
+	 * @param \Exception|null $previous
+	 * @param string[] $tags
+	 * @since 9.0.0
+	 */
+	public function __construct(string $message = '', int $code = 0, ?\Exception $previous = null, array $tags = []) {
+		parent::__construct($message, $code, $previous);
+		$this->tags = $tags;
+	}
+
+	/**
+	 * @return string[]
+	 * @since 9.0.0
+	 */
+	public function getMissingTags(): array {
+		return $this->tags;
+	}
+}
diff --git a/lib/public/SystemTag/TagUpdateForbiddenException.php b/lib/public/SystemTag/TagUpdateForbiddenException.php
new file mode 100644
index 00000000000..e5c1e76f6fe
--- /dev/null
+++ b/lib/public/SystemTag/TagUpdateForbiddenException.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+namespace OCP\SystemTag;
+
+/**
+ * Exception when a user doesn't have the right to create a tag
+ *
+ * @since 31.0.1
+ */
+class TagUpdateForbiddenException extends \RuntimeException {
+}