feat(ocm): event on ocm discovery and ocm request

ArtificialOwl · ArtificialOwl · commit 26227f5b29dc · 2025-12-09T17:18:00.000-01:00
Signed-off-by: Maxence Lange &lt;maxence@artificial-owl.com&gt;
diff --git a/apps/cloud_federation_api/appinfo/routes.php b/apps/cloud_federation_api/appinfo/routes.php
@@ -25,6 +25,15 @@
 			'url' => '/invite-accepted',
 			'verb' => 'POST',
 			'root' => '/ocm',
-		]
+		],
+
+		// needs to be kept at the bottom of the list
+		[
+			'name' => 'OCMRequest#manageOCMRequests',
+			'url' => '/{ocmPath}',
+			'requirements' => ['ocmPath' => '.*'],
+			'verb' =>  ['GET', 'POST', 'PUT', 'DELETE'],
+			'root' => '/ocm',
+		],
 	],
 ];
diff --git a/apps/cloud_federation_api/composer/composer/autoload_classmap.php b/apps/cloud_federation_api/composer/composer/autoload_classmap.php
@@ -10,6 +10,7 @@
     'OCA\\CloudFederationAPI\\AppInfo\\Application' => $baseDir . '/../lib/AppInfo/Application.php',
     'OCA\\CloudFederationAPI\\Capabilities' => $baseDir . '/../lib/Capabilities.php',
     'OCA\\CloudFederationAPI\\Config' => $baseDir . '/../lib/Config.php',
+	'OCA\\CloudFederationAPI\\Controller\\OCMRequestController' => $baseDir . '/../lib/Controller/OCMRequestController.php',
     'OCA\\CloudFederationAPI\\Controller\\RequestHandlerController' => $baseDir . '/../lib/Controller/RequestHandlerController.php',
     'OCA\\CloudFederationAPI\\Db\\FederatedInvite' => $baseDir . '/../lib/Db/FederatedInvite.php',
     'OCA\\CloudFederationAPI\\Db\\FederatedInviteMapper' => $baseDir . '/../lib/Db/FederatedInviteMapper.php',
diff --git a/apps/cloud_federation_api/composer/composer/autoload_static.php b/apps/cloud_federation_api/composer/composer/autoload_static.php
@@ -25,6 +25,7 @@ class ComposerStaticInitCloudFederationAPI
         'OCA\\CloudFederationAPI\\AppInfo\\Application' => __DIR__ . '/..' . '/../lib/AppInfo/Application.php',
         'OCA\\CloudFederationAPI\\Capabilities' => __DIR__ . '/..' . '/../lib/Capabilities.php',
         'OCA\\CloudFederationAPI\\Config' => __DIR__ . '/..' . '/../lib/Config.php',
+        'OCA\\CloudFederationAPI\\Controller\\OCMRequestController' => __DIR__ . '/..' . '/../lib/Controller/OCMRequestController.php',
         'OCA\\CloudFederationAPI\\Controller\\RequestHandlerController' => __DIR__ . '/..' . '/../lib/Controller/RequestHandlerController.php',
         'OCA\\CloudFederationAPI\\Db\\FederatedInvite' => __DIR__ . '/..' . '/../lib/Db/FederatedInvite.php',
         'OCA\\CloudFederationAPI\\Db\\FederatedInviteMapper' => __DIR__ . '/..' . '/../lib/Db/FederatedInviteMapper.php',
diff --git a/apps/cloud_federation_api/lib/Controller/OCMRequestController.php b/apps/cloud_federation_api/lib/Controller/OCMRequestController.php
@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\CloudFederationAPI\Controller;
+
+use JsonException;
+use NCU\Security\Signature\Exceptions\IncomingRequestException;
+use OCP\AppFramework\Http;
+use OCP\AppFramework\Controller;
+use OCP\AppFramework\Http\Attribute\BruteForceProtection;
+use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
+use OCP\AppFramework\Http\Attribute\PublicPage;
+use OCP\AppFramework\Http\DataResponse;
+use OCP\AppFramework\Http\JSONResponse;
+use OCP\AppFramework\Http\Response;
+use OCP\EventDispatcher\IEventDispatcher;
+use OCP\IRequest;
+use OCP\OCM\Events\OCMEndpointRequestEvent;
+use OCP\OCM\Exceptions\OCMArgumentException;
+use Psr\Log\LoggerInterface;
+
+#[OpenAPI(scope: OpenAPI::SCOPE_FEDERATION)]
+class OCMRequestController extends Controller {
+	public function __construct(
+		string $appName,
+		IRequest $request,
+		private readonly IEventDispatcher $eventDispatcher,
+		private readonly LoggerInterface $logger,
+	) {
+		parent::__construct($appName, $request);
+	}
+
+	#[NoCSRFRequired]
+	#[PublicPage]
+	#[BruteForceProtection(action: 'receiveOcmRequest')]
+	public function manageOCMRequests(string $ocmPath): Response {
+		try {
+			json_encode($ocmPath, JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES);
+		} catch (JsonException) {
+			throw new OCMArgumentException('path is not UTF-8');
+		}
+
+		// TODO: check signature and update $remote
+		$remote = null;
+		$event = new OCMEndpointRequestEvent($this->request->getMethod(), str_replace('//', '/', $ocmPath), $payload, $remote);
+		$this->eventDispatcher->dispatchTyped($event);
+
+		if ($event->getResponse() === null) {
+			return new DataResponse('', Http::STATUS_NOT_FOUND);
+		}
+
+		return $event->getResponse();
+	}
+}
diff --git a/apps/cloud_federation_api/lib/Service/SignatureService.php b/apps/cloud_federation_api/lib/Service/SignatureService.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCA\CloudFederationAPI\AppInfo;
+
+use NCU\Security\Signature\ISignatureManager;
+use Psr\Log\LoggerInterface;
+
+class SignatureService {
+
+	public function __construct(
+		private readonly ISignatureManager $signatureManager,
+		private readonly LoggerInterface $logger,
+	) {
+	}
+}
diff --git a/lib/composer/composer/autoload_classmap.php b/lib/composer/composer/autoload_classmap.php
@@ -714,6 +714,7 @@
     'OCP\\Notification\\InvalidValueException' => $baseDir . '/lib/public/Notification/InvalidValueException.php',
     'OCP\\Notification\\NotificationPreloadReason' => $baseDir . '/lib/public/Notification/NotificationPreloadReason.php',
     'OCP\\Notification\\UnknownNotificationException' => $baseDir . '/lib/public/Notification/UnknownNotificationException.php',
+    'OCP\\OCM\\Events\\LocalOCMDiscoveryEvent' => $baseDir . '/lib/public/OCM/Events/LocalOCMDiscoveryEvent.php',
     'OCP\\OCM\\Events\\ResourceTypeRegisterEvent' => $baseDir . '/lib/public/OCM/Events/ResourceTypeRegisterEvent.php',
     'OCP\\OCM\\Exceptions\\OCMArgumentException' => $baseDir . '/lib/public/OCM/Exceptions/OCMArgumentException.php',
     'OCP\\OCM\\Exceptions\\OCMProviderException' => $baseDir . '/lib/public/OCM/Exceptions/OCMProviderException.php',
diff --git a/lib/composer/composer/autoload_static.php b/lib/composer/composer/autoload_static.php
@@ -755,6 +755,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OCP\\Notification\\InvalidValueException' => __DIR__ . '/../../..' . '/lib/public/Notification/InvalidValueException.php',
         'OCP\\Notification\\NotificationPreloadReason' => __DIR__ . '/../../..' . '/lib/public/Notification/NotificationPreloadReason.php',
         'OCP\\Notification\\UnknownNotificationException' => __DIR__ . '/../../..' . '/lib/public/Notification/UnknownNotificationException.php',
+        'OCP\\OCM\\Events\\LocalOCMDiscoveryEvent' => __DIR__ . '/../../..' . '/lib/public/OCM/Events/LocalOCMDiscoveryEvent.php',
         'OCP\\OCM\\Events\\ResourceTypeRegisterEvent' => __DIR__ . '/../../..' . '/lib/public/OCM/Events/ResourceTypeRegisterEvent.php',
         'OCP\\OCM\\Exceptions\\OCMArgumentException' => __DIR__ . '/../../..' . '/lib/public/OCM/Exceptions/OCMArgumentException.php',
         'OCP\\OCM\\Exceptions\\OCMProviderException' => __DIR__ . '/../../..' . '/lib/public/OCM/Exceptions/OCMProviderException.php',
diff --git a/lib/private/AppFramework/Routing/RouteParser.php b/lib/private/AppFramework/Routing/RouteParser.php
@@ -75,7 +75,6 @@ private function processRoute(array $route, string $appName, string $routeNamePr
 		$root = $this->buildRootPrefix($route, $appName, $routeNamePrefix);
 
 		$url = $root . '/' . ltrim($route['url'], '/');
-		$verb = strtoupper($route['verb'] ?? 'GET');
 
 		$split = explode('#', $name, 3);
 		if (count($split) !== 2) {
@@ -95,7 +94,7 @@ private function processRoute(array $route, string $appName, string $routeNamePr
 		$routeName = strtolower($routeNamePrefix . $appName . '.' . $controller . '.' . $action . $postfix);
 
 		$routeObject = new Route($url);
-		$routeObject->method($verb);
+		$routeObject->method((array) ($route['verb'] ?? ['GET']));
 
 		// optionally register requirements for route. This is used to
 		// tell the route parser how url parameters should be matched
@@ -174,7 +173,6 @@ private function processResources(array $resources, string $appName, string $rou
 				$url = $root . '/' . ltrim($config['url'], '/');
 				$method = $action['name'];
 
-				$verb = strtoupper($action['verb'] ?? 'GET');
 				$collectionAction = $action['on-collection'] ?? false;
 				if (!$collectionAction) {
 					$url .= '/{id}';
@@ -188,7 +186,7 @@ private function processResources(array $resources, string $appName, string $rou
 				$routeName = $routeNamePrefix . $appName . '.' . strtolower($resource) . '.' . $method;
 
 				$route = new Route($url);
-				$route->method($verb);
+				$route->method((array) ($action['verb'] ?? ['GET']));
 
 				$route->defaults(['caller' => [$appName, $controllerName, $actionName]]);
 
diff --git a/lib/private/OCM/Model/OCMProvider.php b/lib/private/OCM/Model/OCMProvider.php
@@ -12,13 +12,13 @@
 use NCU\Security\Signature\Model\Signatory;
 use OCP\OCM\Exceptions\OCMArgumentException;
 use OCP\OCM\Exceptions\OCMProviderException;
-use OCP\OCM\ICapabilityAwareOCMProvider;
+use OCP\OCM\IOCMProvider;
 use OCP\OCM\IOCMResource;
 
 /**
  * @since 28.0.0
  */
-class OCMProvider implements ICapabilityAwareOCMProvider {
+class OCMProvider implements IOCMProvider {
 	private bool $enabled = false;
 	private string $apiVersion = '';
 	private string $inviteAcceptDialog = '';
@@ -124,12 +124,12 @@ public function getProvider(): string {
 	 * @return $this
 	 */
 	public function setCapabilities(array $capabilities): static {
-		foreach ($capabilities as $value) {
-			if (!in_array($value, $this->capabilities)) {
-				array_push($this->capabilities, $value);
-			}
-		}
+		// since ocm 1.2, removing slashes from capabilities
+		$capabilities = array_map(static function (string $capability): string {
+			return ltrim($capability, '/');
+		}, $capabilities);
 
+		$this->capabilities = array_unique(array_merge($this->capabilities, $capabilities));
 		return $this;
 	}
 
@@ -139,6 +139,7 @@ public function setCapabilities(array $capabilities): static {
 	public function getCapabilities(): array {
 		return $this->capabilities;
 	}
+
 	/**
 	 * create a new resource to later add it with {@see IOCMProvider::addResourceType()}
 	 * @return IOCMResource
diff --git a/lib/private/OCM/OCMDiscoveryService.php b/lib/private/OCM/OCMDiscoveryService.php
@@ -23,10 +23,11 @@
 use OCP\ICacheFactory;
 use OCP\IConfig;
 use OCP\IURLGenerator;
+use OCP\OCM\Events\LocalOCMDiscoveryEvent;
 use OCP\OCM\Events\ResourceTypeRegisterEvent;
 use OCP\OCM\Exceptions\OCMProviderException;
-use OCP\OCM\ICapabilityAwareOCMProvider;
 use OCP\OCM\IOCMDiscoveryService;
+use OCP\OCM\IOCMProvider;
 use Psr\Log\LoggerInterface;
 
 /**
@@ -36,8 +37,8 @@ class OCMDiscoveryService implements IOCMDiscoveryService {
 	private ICache $cache;
 	public const API_VERSION = '1.1.0';
 
-	private ?ICapabilityAwareOCMProvider $localProvider = null;
-	/** @var array<string, ICapabilityAwareOCMProvider> */
+	private ?IOCMProvider $localProvider = null;
+	/** @var array<string, IOCMProvider> */
 	private array $remoteProviders = [];
 
 	public function __construct(
@@ -57,10 +58,10 @@ public function __construct(
 	 * @param string $remote
 	 * @param bool $skipCache
 	 *
-	 * @return ICapabilityAwareOCMProvider
+	 * @return IOCMProvider
 	 * @throws OCMProviderException
 	 */
-	public function discover(string $remote, bool $skipCache = false): ICapabilityAwareOCMProvider {
+	public function discover(string $remote, bool $skipCache = false): IOCMProvider {
 		$remote = rtrim($remote, '/');
 		if (!str_starts_with($remote, 'http://') && !str_starts_with($remote, 'https://')) {
 			// if scheme not specified, we test both;
@@ -154,9 +155,13 @@ public function discover(string $remote, bool $skipCache = false): ICapabilityAw
 	}
 
 	/**
-	 * @return ICapabilityAwareOCMProvider
+	 * return discovery data about local instance.
+	 * will generate an event to that 3rd party can define new resources.
+	 *
+	 * @param bool $fullDetails complete details, include public key. Set to FALSE for client (capabilities) purpose.
+	 * @return IOCMProvider
 	 */
-	public function getLocalOCMProvider(bool $fullDetails = true): ICapabilityAwareOCMProvider {
+	public function getLocalOCMProvider(bool $fullDetails = true): IOCMProvider {
 		if ($this->localProvider !== null) {
 			return $this->localProvider;
 		}
@@ -176,7 +181,7 @@ public function getLocalOCMProvider(bool $fullDetails = true): ICapabilityAwareO
 		$provider->setEnabled(true);
 		$provider->setApiVersion(self::API_VERSION);
 		$provider->setEndPoint(substr($url, 0, $pos));
-		$provider->setCapabilities(['/invite-accepted', '/notifications', '/shares']);
+		$provider->setCapabilities(['invite-accepted', 'notifications', 'shares']);
 
 		// The inviteAcceptDialog is available from the contacts app, if this config value is set
 		$inviteAcceptDialog = $this->appConfig->getValueString('core', ConfigLexicon::OCM_INVITE_ACCEPT_DIALOG);
@@ -207,6 +212,10 @@ public function getLocalOCMProvider(bool $fullDetails = true): ICapabilityAwareO
 			}
 		}
 
+		$event = new LocalOCMDiscoveryEvent($provider);
+		$this->eventDispatcher->dispatchTyped($event);
+
+		// deprecated since 33.0.0
 		$event = new ResourceTypeRegisterEvent($provider);
 		$this->eventDispatcher->dispatchTyped($event);
 
diff --git a/lib/private/Route/Route.php b/lib/private/Route/Route.php
@@ -14,7 +14,7 @@ class Route extends SymfonyRoute implements IRoute {
 	/**
 	 * Specify the method when this route is to be used
 	 *
-	 * @param string $method HTTP method (uppercase)
+	 * @param string|array $method HTTP method
 	 * @return \OC\Route\Route
 	 */
 	public function method($method) {
diff --git a/lib/private/Server.php b/lib/private/Server.php
@@ -205,9 +205,7 @@
 use OCP\Log\ILogFactory;
 use OCP\Mail\IEmailValidator;
 use OCP\Mail\IMailer;
-use OCP\OCM\ICapabilityAwareOCMProvider;
 use OCP\OCM\IOCMDiscoveryService;
-use OCP\OCM\IOCMProvider;
 use OCP\Preview\IMimeIconProvider;
 use OCP\Profile\IProfileManager;
 use OCP\Profiler\IProfiler;
@@ -1244,9 +1242,9 @@ public function __construct($webRoot, \OC\Config $config) {
 
 		$this->registerAlias(IPhoneNumberUtil::class, PhoneNumberUtil::class);
 
-		// there is no reason for having OCMProvider as a Service
-		$this->registerDeprecatedAlias(ICapabilityAwareOCMProvider::class, OCMProvider::class);
-		$this->registerDeprecatedAlias(IOCMProvider::class, OCMProvider::class);
+		// there is no reason for having OCMProvider as a Service (masked as deprecated since 32.0.0)
+		$this->registerDeprecatedAlias(\OCP\OCM\ICapabilityAwareOCMProvider::class, OCMProvider::class);
+		$this->registerDeprecatedAlias(\OCP\OCM\IOCMProvider::class, OCMProvider::class);
 
 		$this->registerAlias(ISetupCheckManager::class, SetupCheckManager::class);
 
diff --git a/lib/public/OCM/Enum/ParamType.php b/lib/public/OCM/Enum/ParamType.php
@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\OCM\Enum;
+
+use OCP\AppFramework\Attribute\Consumable;
+
+/**
+ * Expected type for each argument contained in the ocm path
+ *
+ * @since 33.0.0
+ */
+#[Consumable(since: '33.0.0')]
+enum ParamType: string {
+	case STRING = 'string';
+	case INT = 'int';
+	case FLOAT = 'float';
+	case BOOL = 'bool';
+}
diff --git a/lib/public/OCM/Events/LocalOCMDiscoveryEvent.php b/lib/public/OCM/Events/LocalOCMDiscoveryEvent.php
@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\OCM\Events;
+
+use OCP\AppFramework\Attribute\Listenable;
+use OCP\EventDispatcher\Event;
+use OCP\OCM\IOCMProvider;
+
+/**
+ * Use this event to register additional resources before the API returns
+ * them in the OCM provider list and capability
+ *
+ * @since 33.0.0
+ *
+ */
+#[Listenable(since: '33.0.0')]
+class LocalOCMDiscoveryEvent extends Event {
+	/**
+	 * @param IOCMProvider $provider
+	 * @since 33.0.0
+	 */
+	public function __construct(
+		private readonly IOCMProvider $provider,
+	) {
+		parent::__construct();
+	}
+
+	/**
+	 * Add a new OCM capability to the discovery data of local instance
+	 *
+	 * @since 33.0.0
+	 */
+	public function addCapability(string $capability): void {
+		$this->provider->setCapabilities([$capability]);
+	}
+
+	/**
+	 * @param string $name
+	 * @param list<string> $shareTypes List of supported share recipients, e.g. 'user', 'group', …
+	 * @param array<string, string> $protocols List of supported protocols and their location,
+	 *                                         e.g. ['webdav' => '/remote.php/webdav/']
+	 * @since 33.0.0
+	 */
+	public function registerResourceType(string $name, array $shareTypes, array $protocols): void {
+		$resourceType = $this->provider->createNewResourceType();
+		$resourceType->setName($name)
+			->setShareTypes($shareTypes)
+			->setProtocols($protocols);
+		$this->provider->addResourceType($resourceType);
+	}
+}
diff --git a/lib/public/OCM/Events/OCMEndpointRequestEvent.php b/lib/public/OCM/Events/OCMEndpointRequestEvent.php
diff --git a/lib/public/OCM/Events/ResourceTypeRegisterEvent.php b/lib/public/OCM/Events/ResourceTypeRegisterEvent.php
diff --git a/lib/public/OCM/ICapabilityAwareOCMProvider.php b/lib/public/OCM/ICapabilityAwareOCMProvider.php
diff --git a/lib/public/OCM/IOCMDiscoveryService.php b/lib/public/OCM/IOCMDiscoveryService.php
diff --git a/lib/public/OCM/IOCMProvider.php b/lib/public/OCM/IOCMProvider.php
