feat(governance): add API to read and change the labels of resources

lib/composer/composer/autoload_classmap.php

@@ -18,6 +18,17 @@
     'NCU\\Config\\Lexicon\\Preset' => $baseDir . '/lib/unstable/Config/Lexicon/Preset.php',
     'NCU\\Config\\ValueType' => $baseDir . '/lib/unstable/Config/ValueType.php',
     'NCU\\Federation\\ISignedCloudFederationProvider' => $baseDir . '/lib/unstable/Federation/ISignedCloudFederationProvider.php',
+    'NCU\\Governance\\Events\\LabelAssignedEvent' => $baseDir . '/lib/unstable/Governance/Events/LabelAssignedEvent.php',
+    'NCU\\Governance\\Events\\LabelRemovedEvent' => $baseDir . '/lib/unstable/Governance/Events/LabelRemovedEvent.php',
+    'NCU\\Governance\\Exception\\GovernanceException' => $baseDir . '/lib/unstable/Governance/Exception/GovernanceException.php',
+    'NCU\\Governance\\Exception\\GovernanceUnavailableException' => $baseDir . '/lib/unstable/Governance/Exception/GovernanceUnavailableException.php',
+    'NCU\\Governance\\Exception\\LabelNotFoundException' => $baseDir . '/lib/unstable/Governance/Exception/LabelNotFoundException.php',
+    'NCU\\Governance\\Exception\\LabelPermissionException' => $baseDir . '/lib/unstable/Governance/Exception/LabelPermissionException.php',
+    'NCU\\Governance\\Exception\\ResourceNotFoundException' => $baseDir . '/lib/unstable/Governance/Exception/ResourceNotFoundException.php',
+    'NCU\\Governance\\ILabelManager' => $baseDir . '/lib/unstable/Governance/ILabelManager.php',
+    'NCU\\Governance\\LabelModification' => $baseDir . '/lib/unstable/Governance/LabelModification.php',
+    'NCU\\Governance\\LabelType' => $baseDir . '/lib/unstable/Governance/LabelType.php',
+    'NCU\\Governance\\ResourceLabel' => $baseDir . '/lib/unstable/Governance/ResourceLabel.php',
     'NCU\\Resource\\IResourceType' => $baseDir . '/lib/unstable/Resource/IResourceType.php',
     'NCU\\Resource\\Permission\\APermission' => $baseDir . '/lib/unstable/Resource/Permission/APermission.php',
     'NCU\\Resource\\Permission\\AccessEntry' => $baseDir . '/lib/unstable/Resource/Permission/AccessEntry.php',
@@ -2069,6 +2080,7 @@
     'OC\\FullTextSearch\\Model\\SearchRequestSimpleQuery' => $baseDir . '/lib/private/FullTextSearch/Model/SearchRequestSimpleQuery.php',
     'OC\\FullTextSearch\\Model\\SearchTemplate' => $baseDir . '/lib/private/FullTextSearch/Model/SearchTemplate.php',
     'OC\\GlobalScale\\Config' => $baseDir . '/lib/private/GlobalScale/Config.php',
+    'OC\\Governance\\LabelManager' => $baseDir . '/lib/private/Governance/LabelManager.php',
     'OC\\Group\\Backend' => $baseDir . '/lib/private/Group/Backend.php',
     'OC\\Group\\Database' => $baseDir . '/lib/private/Group/Database.php',
     'OC\\Group\\DisplayNameCache' => $baseDir . '/lib/private/Group/DisplayNameCache.php',

lib/composer/composer/autoload_static.php

@@ -59,6 +59,17 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'NCU\\Config\\Lexicon\\Preset' => __DIR__ . '/../../..' . '/lib/unstable/Config/Lexicon/Preset.php',
         'NCU\\Config\\ValueType' => __DIR__ . '/../../..' . '/lib/unstable/Config/ValueType.php',
         'NCU\\Federation\\ISignedCloudFederationProvider' => __DIR__ . '/../../..' . '/lib/unstable/Federation/ISignedCloudFederationProvider.php',
+        'NCU\\Governance\\Events\\LabelAssignedEvent' => __DIR__ . '/../../..' . '/lib/unstable/Governance/Events/LabelAssignedEvent.php',
+        'NCU\\Governance\\Events\\LabelRemovedEvent' => __DIR__ . '/../../..' . '/lib/unstable/Governance/Events/LabelRemovedEvent.php',
+        'NCU\\Governance\\Exception\\GovernanceException' => __DIR__ . '/../../..' . '/lib/unstable/Governance/Exception/GovernanceException.php',
+        'NCU\\Governance\\Exception\\GovernanceUnavailableException' => __DIR__ . '/../../..' . '/lib/unstable/Governance/Exception/GovernanceUnavailableException.php',
+        'NCU\\Governance\\Exception\\LabelNotFoundException' => __DIR__ . '/../../..' . '/lib/unstable/Governance/Exception/LabelNotFoundException.php',
+        'NCU\\Governance\\Exception\\LabelPermissionException' => __DIR__ . '/../../..' . '/lib/unstable/Governance/Exception/LabelPermissionException.php',
+        'NCU\\Governance\\Exception\\ResourceNotFoundException' => __DIR__ . '/../../..' . '/lib/unstable/Governance/Exception/ResourceNotFoundException.php',
+        'NCU\\Governance\\ILabelManager' => __DIR__ . '/../../..' . '/lib/unstable/Governance/ILabelManager.php',
+        'NCU\\Governance\\LabelModification' => __DIR__ . '/../../..' . '/lib/unstable/Governance/LabelModification.php',
+        'NCU\\Governance\\LabelType' => __DIR__ . '/../../..' . '/lib/unstable/Governance/LabelType.php',
+        'NCU\\Governance\\ResourceLabel' => __DIR__ . '/../../..' . '/lib/unstable/Governance/ResourceLabel.php',
         'NCU\\Resource\\IResourceType' => __DIR__ . '/../../..' . '/lib/unstable/Resource/IResourceType.php',
         'NCU\\Resource\\Permission\\APermission' => __DIR__ . '/../../..' . '/lib/unstable/Resource/Permission/APermission.php',
         'NCU\\Resource\\Permission\\AccessEntry' => __DIR__ . '/../../..' . '/lib/unstable/Resource/Permission/AccessEntry.php',
@@ -2110,6 +2121,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OC\\FullTextSearch\\Model\\SearchRequestSimpleQuery' => __DIR__ . '/../../..' . '/lib/private/FullTextSearch/Model/SearchRequestSimpleQuery.php',
         'OC\\FullTextSearch\\Model\\SearchTemplate' => __DIR__ . '/../../..' . '/lib/private/FullTextSearch/Model/SearchTemplate.php',
         'OC\\GlobalScale\\Config' => __DIR__ . '/../../..' . '/lib/private/GlobalScale/Config.php',
+        'OC\\Governance\\LabelManager' => __DIR__ . '/../../..' . '/lib/private/Governance/LabelManager.php',
         'OC\\Group\\Backend' => __DIR__ . '/../../..' . '/lib/private/Group/Backend.php',
         'OC\\Group\\Database' => __DIR__ . '/../../..' . '/lib/private/Group/Database.php',
         'OC\\Group\\DisplayNameCache' => __DIR__ . '/../../..' . '/lib/private/Group/DisplayNameCache.php',

lib/private/Governance/LabelManager.php

@@ -0,0 +1,135 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OC\Governance;
+
+use InvalidArgumentException;
+use NCU\Governance\Exception\GovernanceUnavailableException;
+use NCU\Governance\ILabelManager;
+use NCU\Governance\LabelType;
+use NCU\Resource\Permission\IPermissionManager;
+use NCU\Resource\ResourceReference;
+use OCP\Actor\Actor;
+use OCP\App\IAppManager;
+use Psr\Container\ContainerInterface;
+use Psr\Log\LoggerInterface;
+use Throwable;
+
+/**
+ * Passes everything on to the governance app, which decides who may see and change a label.
+ */
+final class LabelManager implements ILabelManager {
+	public const string APP_ID = 'governance';
+	public const string BACKEND = 'OCA\\Governance\\Service\\LabelManager';
+
+	private ?ILabelManager $backend = null;
+
+	public function __construct(
+		private readonly IAppManager $appManager,
+		private readonly ContainerInterface $container,
+		private readonly IPermissionManager $permissionManager,
+		private readonly LoggerInterface $logger,
+	) {
+	}
+
+	#[\Override]
+	public function isAvailable(): bool {
+		return $this->getBackend()?->isAvailable() ?? false;
+	}
+
+	#[\Override]
+	public function getAssignedLabelsForResources(Actor $actor, array $resources): array {
+		$this->assertRegistered($resources);
+
+		$labels = [];
+		foreach ($resources as $resource) {
+			$labels[$resource->key()] = [];
+		}
+
+		$backend = $this->getBackend();
+		if ($backend === null || $resources === []) {
+			return $labels;
+		}
+
+		foreach ($backend->getAssignedLabelsForResources($actor, $resources) as $resourceKey => $resourceLabels) {
+			if (isset($labels[$resourceKey])) {
+				$labels[$resourceKey] = array_values($resourceLabels);
+			}
+		}
+
+		return $labels;
+	}
+
+	#[\Override]
+	public function getAssignedLabels(Actor $actor, ResourceReference $resource): array {
+		return $this->getAssignedLabelsForResources($actor, [$resource])[$resource->key()];
+	}
+
+	#[\Override]
+	public function getAssignableLabels(Actor $actor, ResourceReference $resource, ?LabelType $type = null): array {
+		$this->assertRegistered([$resource]);
+
+		return $this->getBackend()?->getAssignableLabels($actor, $resource, $type) ?? [];
+	}
+
+	#[\Override]
+	public function assignLabel(Actor $actor, ResourceReference $resource, string $labelId, ?string $reason = null): void {
+		$this->assertRegistered([$resource]);
+		$this->getBackendOrThrow()->assignLabel($actor, $resource, $labelId, $reason);
+	}
+
+	#[\Override]
+	public function removeLabel(Actor $actor, ResourceReference $resource, string $labelId, ?string $reason = null): void {
+		$this->assertRegistered([$resource]);
+		$this->getBackendOrThrow()->removeLabel($actor, $resource, $labelId, $reason);
+	}
+
+	/**
+	 * @param list<ResourceReference> $resources
+	 * @throws InvalidArgumentException if a resource type is not registered
+	 */
+	private function assertRegistered(array $resources): void {
+		foreach ($resources as $resource) {
+			if ($this->permissionManager->getResourceType($resource->type) === null) {
+				throw new InvalidArgumentException('The resource type ' . $resource->type . ' is not registered');
+			}
+		}
+	}
+
+	/**
+	 * @throws GovernanceUnavailableException
+	 */
+	private function getBackendOrThrow(): ILabelManager {
+		return $this->getBackend() ?? throw new GovernanceUnavailableException('The governance app is not enabled');
+	}
+
+	private function getBackend(): ?ILabelManager {
+		if ($this->backend !== null) {
+			return $this->backend;
+		}
+		if (!$this->appManager->isEnabledForAnyone(self::APP_ID)) {
+			return null;
+		}
+
+		try {
+			$backend = $this->container->get(self::BACKEND);
+		} catch (Throwable $e) {
+			$this->logger->error('Could not load the label manager of the governance app', ['exception' => $e]);
+			return null;
+		}
+		if (!$backend instanceof ILabelManager) {
+			$this->logger->error('{class} does not implement {interface}', ['class' => self::BACKEND, 'interface' => ILabelManager::class]);
+			return null;
+		}
+
+		$this->backend = $backend;
+
+		return $backend;
+	}
+}

lib/private/Server.php

@@ -1119,6 +1119,7 @@ public function runInitialRegistrations(): void {
 
 		$this->registerAlias(\NCU\Resource\Permission\IPermissionManager::class, \OC\Resource\Permission\PermissionManager::class);
 		$this->registerAlias(\NCU\Resource\Permission\IAccessManager::class, \OC\Resource\Permission\AccessManager::class);
+		$this->registerAlias(\NCU\Governance\ILabelManager::class, \OC\Governance\LabelManager::class);
 
 		$this->registerService(IGlobalScaleService::class, static function (ContainerInterface $c): IGlobalScaleService {
 			/** @var Coordinator $coordinator */

lib/unstable/Governance/Events/LabelAssignedEvent.php

@@ -0,0 +1,39 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace NCU\Governance\Events;
+
+use NCU\Governance\LabelType;
+use NCU\Resource\ResourceReference;
+use OCP\Actor\Actor;
+use OCP\AppFramework\Attribute\ExceptionalImplementable;
+use OCP\AppFramework\Attribute\Listenable;
+use OCP\EventDispatcher\Event;
+
+/**
+ * Dispatched by the governance app after a label was assigned to a resource.
+ *
+ * @experimental 36.0.0
+ */
+#[Listenable(since: '36.0.0')]
+#[ExceptionalImplementable(app: 'governance')]
+final class LabelAssignedEvent extends Event {
+	/**
+	 * @param non-empty-string $labelId
+	 * @experimental 36.0.0
+	 */
+	public function __construct(
+		public readonly Actor $actor,
+		public readonly ResourceReference $resource,
+		public readonly string $labelId,
+		public readonly LabelType $labelType,
+	) {
+		parent::__construct();
+	}
+}

lib/unstable/Governance/Events/LabelRemovedEvent.php

@@ -0,0 +1,40 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace NCU\Governance\Events;
+
+use NCU\Governance\LabelType;
+use NCU\Resource\ResourceReference;
+use OCP\Actor\Actor;
+use OCP\AppFramework\Attribute\ExceptionalImplementable;
+use OCP\AppFramework\Attribute\Listenable;
+use OCP\EventDispatcher\Event;
+
+/**
+ * Dispatched by the governance app after a label was removed from a resource, also when another label replaced it.
+ * It is not dispatched when the label or the resource is deleted.
+ *
+ * @experimental 36.0.0
+ */
+#[Listenable(since: '36.0.0')]
+#[ExceptionalImplementable(app: 'governance')]
+final class LabelRemovedEvent extends Event {
+	/**
+	 * @param non-empty-string $labelId
+	 * @experimental 36.0.0
+	 */
+	public function __construct(
+		public readonly Actor $actor,
+		public readonly ResourceReference $resource,
+		public readonly string $labelId,
+		public readonly LabelType $labelType,
+	) {
+		parent::__construct();
+	}
+}

lib/unstable/Governance/Exception/GovernanceException.php

@@ -0,0 +1,23 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace NCU\Governance\Exception;
+
+use OCP\AppFramework\Attribute\Catchable;
+use OCP\AppFramework\Attribute\ExceptionalImplementable;
+
+/**
+ * Base of the exceptions thrown when changing the labels of a resource.
+ *
+ * @experimental 36.0.0
+ */
+#[Catchable(since: '36.0.0')]
+#[ExceptionalImplementable(app: 'governance')]
+class GovernanceException extends \Exception {
+}

lib/unstable/Governance/Exception/GovernanceUnavailableException.php

@@ -0,0 +1,23 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace NCU\Governance\Exception;
+
+use OCP\AppFramework\Attribute\Catchable;
+use OCP\AppFramework\Attribute\ExceptionalImplementable;
+
+/**
+ * Labels cannot be changed because the governance app is not enabled.
+ *
+ * @experimental 36.0.0
+ */
+#[Catchable(since: '36.0.0')]
+#[ExceptionalImplementable(app: 'governance')]
+final class GovernanceUnavailableException extends GovernanceException {
+}

lib/unstable/Governance/Exception/LabelNotFoundException.php

@@ -0,0 +1,23 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace NCU\Governance\Exception;
+
+use OCP\AppFramework\Attribute\Catchable;
+use OCP\AppFramework\Attribute\ExceptionalImplementable;
+
+/**
+ * The label does not exist or does not apply to the resource.
+ *
+ * @experimental 36.0.0
+ */
+#[Catchable(since: '36.0.0')]
+#[ExceptionalImplementable(app: 'governance')]
+final class LabelNotFoundException extends GovernanceException {
+}

lib/unstable/Governance/Exception/LabelPermissionException.php

@@ -0,0 +1,23 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace NCU\Governance\Exception;
+
+use OCP\AppFramework\Attribute\Catchable;
+use OCP\AppFramework\Attribute\ExceptionalImplementable;
+
+/**
+ * The actor is not allowed to assign or remove the label, or a required reason is missing.
+ *
+ * @experimental 36.0.0
+ */
+#[Catchable(since: '36.0.0')]
+#[ExceptionalImplementable(app: 'governance')]
+final class LabelPermissionException extends GovernanceException {
+}

lib/unstable/Governance/Exception/ResourceNotFoundException.php

@@ -0,0 +1,23 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace NCU\Governance\Exception;
+
+use OCP\AppFramework\Attribute\Catchable;
+use OCP\AppFramework\Attribute\ExceptionalImplementable;
+
+/**
+ * The resource does not exist or the actor may not label it for lack of access.
+ *
+ * @experimental 36.0.0
+ */
+#[Catchable(since: '36.0.0')]
+#[ExceptionalImplementable(app: 'governance')]
+final class ResourceNotFoundException extends GovernanceException {
+}