feat(OCM-invites): Implementation of invitation flow for OCM 1.1.0

apps/cloud_federation_api/appinfo/info.xml

@@ -9,7 +9,7 @@
 	<name>Cloud Federation API</name>
 	<summary>Enable clouds to communicate with each other and exchange data</summary>
 	<description>The Cloud Federation API enables various Nextcloud instances to communicate with each other and to exchange data.</description>
-	<version>1.15.0</version>
+	<version>1.16.0</version>
 	<licence>agpl</licence>
 	<author>Bjoern Schiessle</author>
 	<namespace>CloudFederationAPI</namespace>

apps/cloud_federation_api/appinfo/routes.php

@@ -20,11 +20,11 @@
 			'verb' => 'POST',
 			'root' => '/ocm',
 		],
-		//		[
-		//			'name' => 'RequestHandler#inviteAccepted',
-		//			'url' => '/invite-accepted',
-		//			'verb' => 'POST',
-		//			'root' => '/ocm',
-		//		]
+		[
+			'name' => 'RequestHandler#inviteAccepted',
+			'url' => '/invite-accepted',
+			'verb' => 'POST',
+			'root' => '/ocm',
+		]
 	],
 ];

apps/cloud_federation_api/composer/composer/autoload_classmap.php

@@ -11,5 +11,9 @@
     'OCA\\CloudFederationAPI\\Capabilities' => $baseDir . '/../lib/Capabilities.php',
     'OCA\\CloudFederationAPI\\Config' => $baseDir . '/../lib/Config.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',
+    'OCA\\CloudFederationAPI\\Events\\FederatedInviteAcceptedEvent' => $baseDir . '/../lib/Events/FederatedInviteAcceptedEvent.php',
+    'OCA\\CloudFederationAPI\\Migration\\Version1016Date202502262004' => $baseDir . '/../lib/Migration/Version1016Date202502262004.php',
     'OCA\\CloudFederationAPI\\ResponseDefinitions' => $baseDir . '/../lib/ResponseDefinitions.php',
 );

apps/cloud_federation_api/composer/composer/autoload_static.php

@@ -26,6 +26,10 @@ class ComposerStaticInitCloudFederationAPI
         'OCA\\CloudFederationAPI\\Capabilities' => __DIR__ . '/..' . '/../lib/Capabilities.php',
         'OCA\\CloudFederationAPI\\Config' => __DIR__ . '/..' . '/../lib/Config.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',
+        'OCA\\CloudFederationAPI\\Events\\FederatedInviteAcceptedEvent' => __DIR__ . '/..' . '/../lib/Events/FederatedInviteAcceptedEvent.php',
+        'OCA\\CloudFederationAPI\\Migration\\Version1016Date202502262004' => __DIR__ . '/..' . '/../lib/Migration/Version1016Date202502262004.php',
         'OCA\\CloudFederationAPI\\ResponseDefinitions' => __DIR__ . '/..' . '/../lib/ResponseDefinitions.php',
     );
 

apps/cloud_federation_api/lib/Capabilities.php

@@ -6,6 +6,7 @@
  * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
+
 namespace OCA\CloudFederationAPI;
 
 use NCU\Security\Signature\Exceptions\IdentityNotFoundException;
@@ -16,16 +17,16 @@
 use OCP\IAppConfig;
 use OCP\IURLGenerator;
 use OCP\OCM\Exceptions\OCMArgumentException;
-use OCP\OCM\IOCMProvider;
+use OCP\OCM\ICapabilityAwareOCMProvider;
 use Psr\Log\LoggerInterface;
 
 class Capabilities implements ICapability, IInitialStateExcludedCapability {
-	public const API_VERSION = '1.1'; // informative, real version.
+	public const API_VERSION = '1.1.0';
 
 	public function __construct(
 		private IURLGenerator $urlGenerator,
 		private IAppConfig $appConfig,
-		private IOCMProvider $provider,
+		private ICapabilityAwareOCMProvider $provider,
 		private readonly OCMSignatoryManager $ocmSignatoryManager,
 		private readonly LoggerInterface $logger,
 	) {
@@ -34,23 +35,7 @@ public function __construct(
 	/**
 	 * Function an app uses to return the capabilities
 	 *
-	 * @return array{
-	 *     ocm: array{
-	 *     	   apiVersion: '1.0-proposal1',
-	 *         enabled: bool,
-	 *         endPoint: string,
-	 *         publicKey?: array{
-	 *             keyId: string,
-	 *             publicKeyPem: string,
-	 *         },
-	 *         resourceTypes: list<array{
-	 *             name: string,
-	 *             shareTypes: list<string>,
-	 *             protocols: array<string, string>
-	 *         }>,
-	 *         version: string
-	 *     }
-	 * }
+	 * @return array<string, array<string, mixed>>
 	 * @throws OCMArgumentException
 	 */
 	public function getCapabilities() {
@@ -62,6 +47,8 @@ public function getCapabilities() {
 
 		$this->provider->setEnabled(true);
 		$this->provider->setApiVersion(self::API_VERSION);
+		$this->provider->setCapabilities(['/invite-accepted', '/notifications', '/shares']);
+
 		$this->provider->setEndPoint(substr($url, 0, $pos));
 
 		$resource = $this->provider->createNewResourceType();

apps/cloud_federation_api/lib/Controller/RequestHandlerController.php

@@ -1,8 +1,10 @@
 <?php
+
 /**
  * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
+
 namespace OCA\CloudFederationAPI\Controller;
 
 use NCU\Federation\ISignedCloudFederationProvider;
@@ -15,15 +17,20 @@
 use NCU\Security\Signature\ISignatureManager;
 use OC\OCM\OCMSignatoryManager;
 use OCA\CloudFederationAPI\Config;
+use OCA\CloudFederationAPI\Db\FederatedInviteMapper;
+use OCA\CloudFederationAPI\Events\FederatedInviteAcceptedEvent;
 use OCA\CloudFederationAPI\ResponseDefinitions;
 use OCA\FederatedFileSharing\AddressHandler;
 use OCP\AppFramework\Controller;
+use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\AppFramework\Http;
 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\JSONResponse;
+use OCP\AppFramework\Utility\ITimeFactory;
+use OCP\EventDispatcher\IEventDispatcher;
 use OCP\Federation\Exceptions\ActionNotSupportedException;
 use OCP\Federation\Exceptions\AuthenticationFailedException;
 use OCP\Federation\Exceptions\BadRequestException;
@@ -61,12 +68,15 @@ public function __construct(
 		private IURLGenerator $urlGenerator,
 		private ICloudFederationProviderManager $cloudFederationProviderManager,
 		private Config $config,
+		private IEventDispatcher $dispatcher,
+		private FederatedInviteMapper $federatedInviteMapper,
 		private readonly AddressHandler $addressHandler,
 		private readonly IAppConfig $appConfig,
 		private ICloudFederationFactory $factory,
 		private ICloudIdManager $cloudIdManager,
 		private readonly ISignatureManager $signatureManager,
 		private readonly OCMSignatoryManager $signatoryManager,
+		private ITimeFactory $timeFactory,
 	) {
 		parent::__construct($appName, $request);
 	}
@@ -107,7 +117,8 @@ public function addShare($shareWith, $name, $description, $providerId, $owner, $
 		}
 
 		// check if all required parameters are set
-		if ($shareWith === null ||
+		if (
+			$shareWith === null ||
 			$name === null ||
 			$providerId === null ||
 			$resourceType === null ||
@@ -213,6 +224,101 @@ public function addShare($shareWith, $name, $description, $providerId, $owner, $
 		return new JSONResponse($responseData, Http::STATUS_CREATED);
 	}
 
+	/**
+	 * Inform the sender that an invitation was accepted to start sharing
+	 *
+	 * Inform about an accepted invitation so the user on the sender provider's side
+	 * can initiate the OCM share creation. To protect the identity of the parties,
+	 * for shares created following an OCM invitation, the user id MAY be hashed,
+	 * and recipients implementing the OCM invitation workflow MAY refuse to process
+	 * shares coming from unknown parties.
+	 * @link https://cs3org.github.io/OCM-API/docs.html?branch=v1.1.0&repo=OCM-API&user=cs3org#/paths/~1invite-accepted/post
+	 *
+	 * @param string $recipientProvider The address of the recipent's provider
+	 * @param string $token The token used for the invitation
+	 * @param string $userId The userId of the recipient at the recipient's provider
+	 * @param string $email The email address of the recipient
+	 * @param string $name The display name of the recipient
+	 *
+	 * @return JSONResponse<Http::STATUS_OK, array{userID: string, email: string, name: string}, array{}>|JSONResponse<Http::STATUS_FORBIDDEN|Http::STATUS_BAD_REQUEST|Http::STATUS_CONFLICT, array{message: string, error: true}, array{}>
+	 *
+	 * Note: Not implementing 404 Invitation token does not exist, instead using 400
+	 * 200: Invitation accepted
+	 * 400: Invalid token
+	 * 403: Invitation token does not exist
+	 * 409: User is already known by the OCM provider
+	 */
+	#[PublicPage]
+	#[NoCSRFRequired]
+	#[BruteForceProtection(action: 'inviteAccepted')]
+	public function inviteAccepted(string $recipientProvider, string $token, string $userId, string $email, string $name): JSONResponse {
+		$this->logger->debug('Processing share invitation for ' . $userId . ' with token ' . $token . ' and email ' . $email . ' and name ' . $name);
+
+		$updated = $this->timeFactory->getTime();
+
+		if ($token === '') {
+			$response = new JSONResponse(['message' => 'Invalid or non existing token', 'error' => true], Http::STATUS_BAD_REQUEST);
+			$response->throttle();
+			return $response;
+		}
+
+		try {
+			$invitation = $this->federatedInviteMapper->findByToken($token);
+		} catch (DoesNotExistException) {
+			$response = ['message' => 'Invalid or non existing token', 'error' => true];
+			$status = Http::STATUS_BAD_REQUEST;
+			$response = new JSONResponse($response, $status);
+			$response->throttle();
+			return $response;
+		}
+
+		if ($invitation->isAccepted() === true) {
+			$response = ['message' => 'Invite already accepted', 'error' => true];
+			$status = Http::STATUS_CONFLICT;
+			return new JSONResponse($response, $status);
+		}
+
+		if ($invitation->getExpiredAt() !== null && $updated > $invitation->getExpiredAt()) {
+			$response = ['message' => 'Invitation expired', 'error' => true];
+			$status = Http::STATUS_BAD_REQUEST;
+			return new JSONResponse($response, $status);
+		}
+		$localUser = $this->userManager->get($invitation->getUserId());
+		if ($localUser === null) {
+			$response = ['message' => 'Invalid or non existing token', 'error' => true];
+			$status = Http::STATUS_BAD_REQUEST;
+			$response = new JSONResponse($response, $status);
+			$response->throttle();
+			return $response;
+		}
+
+		$sharedFromEmail = $localUser->getPrimaryEMailAddress();
+		if ($sharedFromEmail === null) {
+			$response = ['message' => 'Invalid or non existing token', 'error' => true];
+			$status = Http::STATUS_BAD_REQUEST;
+			$response = new JSONResponse($response, $status);
+			$response->throttle();
+			return $response;
+		}
+		$sharedFromDisplayName = $localUser->getDisplayName();
+
+		$response = ['userID' => $localUser->getUID(), 'email' => $sharedFromEmail, 'name' => $sharedFromDisplayName];
+		$status = Http::STATUS_OK;
+
+		$invitation->setAccepted(true);
+		$invitation->setRecipientEmail($email);
+		$invitation->setRecipientName($name);
+		$invitation->setRecipientProvider($recipientProvider);
+		$invitation->setRecipientUserId($userId);
+		$invitation->setAcceptedAt($updated);
+		$invitation = $this->federatedInviteMapper->update($invitation);
+
+		$event = new FederatedInviteAcceptedEvent($invitation);
+		$this->dispatcher->dispatchTyped($event);
+
+		return new JSONResponse($response, $status);
+	}
+
 	/**
 	 * Send a notification about an existing share
 	 *
@@ -233,7 +339,8 @@ public function addShare($shareWith, $name, $description, $providerId, $owner, $
 	#[BruteForceProtection(action: 'receiveFederatedShareNotification')]
 	public function receiveNotification($notificationType, $resourceType, $providerId, ?array $notification) {
 		// check if all required parameters are set
-		if ($notificationType === null ||
+		if (
+			$notificationType === null ||
 			$resourceType === null ||
 			$providerId === null ||
 			!is_array($notification)

apps/cloud_federation_api/lib/Db/FederatedInvite.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\CloudFederationAPI\Db;
+
+use OCP\AppFramework\Db\Entity;
+use OCP\DB\Types;
+
+/**
+ * @method bool isAccepted()
+ * @method void setAccepted(bool $accepted)
+ * @method int|null getAcceptedAt()
+ * @method void setAcceptedAt(int $acceptedAt)
+ * @method int|null getCreatedAt()
+ * @method void setCreatedAt(int $createdAt)
+ * @method int|null getExpiredAt()
+ * @method void setExpiredAt(int $expiredAt)
+ * @method string|null getRecipientEmail()
+ * @method void setRecipientEmail(string $recipientEmail)
+ * @method string|null getRecipientName()
+ * @method void setRecipientName(string $recipientName)
+ * @method string|null getRecipientProvider()
+ * @method void setRecipientProvider(string $recipientProvider)
+ * @method string|null getRecipientUserId()
+ * @method void setRecipientUserId(string $recipientUserId)
+ * @method string getToken()
+ * @method void setToken(string $token)
+ * @method string|null getUserId()
+ * @method void setUserId(string $userId)
+ */
+
+class FederatedInvite extends Entity {
+	protected bool $accepted = false;
+	protected ?int $acceptedAt = 0;
+	protected int $createdAt = 0;
+	protected ?int $expiredAt = 0;
+	protected ?string $recipientEmail = null;
+	protected ?string $recipientName = null;
+	protected ?string $recipientProvider = null;
+	protected ?string $recipientUserId = null;
+	protected string $token = '';
+	protected string $userId = '';
+
+	public function __construct() {
+		$this->addType('accepted', Types::BOOLEAN);
+		$this->addType('acceptedAt', Types::BIGINT);
+		$this->addType('createdAt', Types::BIGINT);
+		$this->addType('expiredAt', Types::BIGINT);
+		$this->addType('recipientEmail', Types::STRING);
+		$this->addType('recipientName', Types::STRING);
+		$this->addType('recipientProvider', Types::STRING);
+		$this->addType('recipientUserId', Types::STRING);
+		$this->addType('token', Types::STRING);
+		$this->addType('userId', Types::STRING);
+	}
+}

apps/cloud_federation_api/lib/Db/FederatedInviteMapper.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\CloudFederationAPI\Db;
+
+use OCP\AppFramework\Db\QBMapper;
+use OCP\IDBConnection;
+
+/**
+ * @template-extends QBMapper<FederatedInvite>
+ */
+class FederatedInviteMapper extends QBMapper {
+	public const TABLE_NAME = 'federated_invites';
+
+	public function __construct(IDBConnection $db) {
+		parent::__construct($db, self::TABLE_NAME);
+	}
+
+	public function findByToken(string $token): FederatedInvite {
+		$qb = $this->db->getQueryBuilder();
+		$qb->select('*')
+			->from('federated_invites')
+			->where($qb->expr()->eq('token', $qb->createNamedParameter($token)));
+		return $this->findEntity($qb);
+	}
+
+}