diff options
Diffstat (limited to 'lib/public/Federation')
15 files changed, 917 insertions, 0 deletions
diff --git a/lib/public/Federation/Events/TrustedServerRemovedEvent.php b/lib/public/Federation/Events/TrustedServerRemovedEvent.php new file mode 100644 index 00000000000..41899d67a88 --- /dev/null +++ b/lib/public/Federation/Events/TrustedServerRemovedEvent.php @@ -0,0 +1,33 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Federation\Events; + +use OCP\EventDispatcher\Event; + +/** + * @since 25.0.0 + */ +class TrustedServerRemovedEvent extends Event { + private string $urlHash; + + /** + * @since 25.0.0 + */ + public function __construct(string $urlHash) { + parent::__construct(); + $this->urlHash = $urlHash; + } + + /** + * @since 25.0.0 + */ + public function getUrlHash(): string { + return $this->urlHash; + } +} diff --git a/lib/public/Federation/Exceptions/ActionNotSupportedException.php b/lib/public/Federation/Exceptions/ActionNotSupportedException.php new file mode 100644 index 00000000000..7f0e0f46907 --- /dev/null +++ b/lib/public/Federation/Exceptions/ActionNotSupportedException.php @@ -0,0 +1,30 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Federation\Exceptions; + +use OCP\HintException; + +/** + * Class ActionNotSupportedException + * + * + * @since 14.0.0 + */ +class ActionNotSupportedException extends HintException { + /** + * ActionNotSupportedException constructor. + * + * @since 14.0.0 + * + */ + public function __construct($action) { + $l = \OCP\Util::getL10N('federation'); + $message = 'Action "' . $action . '" not supported or implemented.'; + $hint = $l->t('Action "%s" not supported or implemented.', [$action]); + parent::__construct($message, $hint); + } +} diff --git a/lib/public/Federation/Exceptions/AuthenticationFailedException.php b/lib/public/Federation/Exceptions/AuthenticationFailedException.php new file mode 100644 index 00000000000..6ce5314844e --- /dev/null +++ b/lib/public/Federation/Exceptions/AuthenticationFailedException.php @@ -0,0 +1,30 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Federation\Exceptions; + +use OCP\HintException; + +/** + * Class AuthenticationFailedException + * + * + * @since 14.0.0 + */ +class AuthenticationFailedException extends HintException { + /** + * BadRequestException constructor. + * + * @since 14.0.0 + * + */ + public function __construct() { + $l = \OCP\Util::getL10N('federation'); + $message = 'Authentication failed, wrong token or provider ID given'; + $hint = $l->t('Authentication failed, wrong token or provider ID given'); + parent::__construct($message, $hint); + } +} diff --git a/lib/public/Federation/Exceptions/BadRequestException.php b/lib/public/Federation/Exceptions/BadRequestException.php new file mode 100644 index 00000000000..0210437a8d5 --- /dev/null +++ b/lib/public/Federation/Exceptions/BadRequestException.php @@ -0,0 +1,62 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Federation\Exceptions; + +use OCP\HintException; + +/** + * Class BadRequestException + * + * + * @since 14.0.0 + */ +class BadRequestException extends HintException { + /** + * @var string[] $parameterList + */ + private $parameterList; + + /** + * BadRequestException constructor. + * + * @since 14.0.0 + * + * @param array $missingParameters + */ + public function __construct(array $missingParameters) { + $l = \OCP\Util::getL10N('federation'); + $this->parameterList = $missingParameters; + $parameterList = implode(',', $missingParameters); + $message = 'Parameters missing in order to complete the request. Missing Parameters: ' . $parameterList; + $hint = $l->t('Parameters missing in order to complete the request. Missing Parameters: "%s"', [$parameterList]); + parent::__construct($message, $hint); + } + + /** + * get array with the return message as defined in the OCM API + * + * @since 14.0.0 + * + * @return array{message: string, validationErrors: array{message: string, name: string}[]} + */ + public function getReturnMessage() { + $result = [ + 'message' => 'RESOURCE_NOT_FOUND', + 'validationErrors' => [ + ] + ]; + + foreach ($this->parameterList as $missingParameter) { + $result['validationErrors'][] = [ + 'name' => $missingParameter, + 'message' => 'NOT_FOUND' + ]; + } + + return $result; + } +} diff --git a/lib/public/Federation/Exceptions/ProviderAlreadyExistsException.php b/lib/public/Federation/Exceptions/ProviderAlreadyExistsException.php new file mode 100644 index 00000000000..f753f5f3326 --- /dev/null +++ b/lib/public/Federation/Exceptions/ProviderAlreadyExistsException.php @@ -0,0 +1,32 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Federation\Exceptions; + +use OCP\HintException; + +/** + * Class ProviderAlreadyExistsException + * + * + * @since 14.0.0 + */ +class ProviderAlreadyExistsException extends HintException { + /** + * ProviderAlreadyExistsException constructor. + * + * @since 14.0.0 + * + * @param string $newProviderId cloud federation provider ID of the new provider + * @param string $existingProviderName name of cloud federation provider which already use the same ID + */ + public function __construct($newProviderId, $existingProviderName) { + $l = \OCP\Util::getL10N('federation'); + $message = 'ID "' . $newProviderId . '" already used by cloud federation provider "' . $existingProviderName . '"'; + $hint = $l->t('ID "%1$s" already used by cloud federation provider "%2$s"', [$newProviderId, $existingProviderName]); + parent::__construct($message, $hint); + } +} diff --git a/lib/public/Federation/Exceptions/ProviderCouldNotAddShareException.php b/lib/public/Federation/Exceptions/ProviderCouldNotAddShareException.php new file mode 100644 index 00000000000..168eb2b8aeb --- /dev/null +++ b/lib/public/Federation/Exceptions/ProviderCouldNotAddShareException.php @@ -0,0 +1,32 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Federation\Exceptions; + +use OCP\AppFramework\Http; +use OCP\HintException; + +/** + * Class ProviderCouldNotAddShareException + * + * + * @since 14.0.0 + */ +class ProviderCouldNotAddShareException extends HintException { + /** + * ProviderCouldNotAddShareException constructor. + * + * @since 14.0.0 + * + * @param string $message + * @param string $hint + * @param int $code + * @param \Exception|null $previous + */ + public function __construct($message, $hint = '', $code = Http::STATUS_BAD_REQUEST, ?\Exception $previous = null) { + parent::__construct($message, $hint, $code, $previous); + } +} diff --git a/lib/public/Federation/Exceptions/ProviderDoesNotExistsException.php b/lib/public/Federation/Exceptions/ProviderDoesNotExistsException.php new file mode 100644 index 00000000000..64dfcf0f856 --- /dev/null +++ b/lib/public/Federation/Exceptions/ProviderDoesNotExistsException.php @@ -0,0 +1,31 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Federation\Exceptions; + +use OCP\HintException; + +/** + * Class ProviderDoesNotExistsException + * + * + * @since 14.0.0 + */ +class ProviderDoesNotExistsException extends HintException { + /** + * ProviderDoesNotExistsException constructor. + * + * @since 14.0.0 + * + * @param string $providerId cloud federation provider ID + */ + public function __construct($providerId) { + $l = \OCP\Util::getL10N('federation'); + $message = 'Cloud Federation Provider with ID: "' . $providerId . '" does not exist.'; + $hint = $l->t('Cloud Federation Provider with ID: "%s" does not exist.', [$providerId]); + parent::__construct($message, $hint); + } +} diff --git a/lib/public/Federation/ICloudFederationFactory.php b/lib/public/Federation/ICloudFederationFactory.php new file mode 100644 index 00000000000..5238188b4fa --- /dev/null +++ b/lib/public/Federation/ICloudFederationFactory.php @@ -0,0 +1,45 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Federation; + +/** + * Interface ICloudFederationFactory + * + * + * @since 14.0.0 + */ +interface ICloudFederationFactory { + /** + * get a CloudFederationShare Object to prepare a share you want to send + * + * @param string $shareWith + * @param string $name resource name (e.g. document.odt) + * @param string $description share description (optional) + * @param string $providerId resource UID on the provider side + * @param string $owner provider specific UID of the user who owns the resource + * @param string $ownerDisplayName display name of the user who shared the item + * @param string $sharedBy provider specific UID of the user who shared the resource + * @param string $sharedByDisplayName display name of the user who shared the resource + * @param string $sharedSecret used to authenticate requests across servers + * @param string $shareType ('group' or 'user' share) + * @param $resourceType ('file', 'calendar',...) + * @return ICloudFederationShare + * + * @since 14.0.0 + */ + public function getCloudFederationShare($shareWith, $name, $description, $providerId, $owner, $ownerDisplayName, $sharedBy, $sharedByDisplayName, $sharedSecret, $shareType, $resourceType); + + /** + * get a Cloud FederationNotification object to prepare a notification you + * want to send + * + * @return ICloudFederationNotification + * + * @since 14.0.0 + */ + public function getCloudFederationNotification(); +} diff --git a/lib/public/Federation/ICloudFederationNotification.php b/lib/public/Federation/ICloudFederationNotification.php new file mode 100644 index 00000000000..c550a936927 --- /dev/null +++ b/lib/public/Federation/ICloudFederationNotification.php @@ -0,0 +1,36 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Federation; + +/** + * Interface ICloudFederationNotification + * + * + * @since 14.0.0 + */ +interface ICloudFederationNotification { + /** + * add a message to the notification + * + * @param string $notificationType (e.g. SHARE_ACCEPTED) + * @param string $resourceType (e.g. file, calendar, contact,...) + * @param string $providerId id of the share + * @param array $notification payload of the notification + * + * @since 14.0.0 + */ + public function setMessage($notificationType, $resourceType, $providerId, array $notification); + + /** + * get message, ready to send out + * + * @return array + * + * @since 14.0.0 + */ + public function getMessage(); +} diff --git a/lib/public/Federation/ICloudFederationProvider.php b/lib/public/Federation/ICloudFederationProvider.php new file mode 100644 index 00000000000..b30041f81d6 --- /dev/null +++ b/lib/public/Federation/ICloudFederationProvider.php @@ -0,0 +1,71 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Federation; + +use OCP\Federation\Exceptions\ActionNotSupportedException; +use OCP\Federation\Exceptions\AuthenticationFailedException; +use OCP\Federation\Exceptions\BadRequestException; +use OCP\Federation\Exceptions\ProviderCouldNotAddShareException; +use OCP\Share\Exceptions\ShareNotFound; + +/** + * Interface ICloudFederationProvider + * + * Enable apps to create their own cloud federation provider + * + * @since 14.0.0 + * + */ + +interface ICloudFederationProvider { + /** + * get the name of the share type, handled by this provider + * + * @return string + * + * @since 14.0.0 + */ + public function getShareType(); + + /** + * share received from another server + * + * @param ICloudFederationShare $share + * @return string provider specific unique ID of the share + * + * @throws ProviderCouldNotAddShareException + * + * @since 14.0.0 + */ + public function shareReceived(ICloudFederationShare $share); + + /** + * notification received from another server + * + * @param string $notificationType (e.g SHARE_ACCEPTED) + * @param string $providerId share ID + * @param array $notification provider specific notification + * @return array<string> $data send back to sender + * + * @throws ShareNotFound + * @throws ActionNotSupportedException + * @throws BadRequestException + * @throws AuthenticationFailedException + * + * @since 14.0.0 + */ + public function notificationReceived($notificationType, $providerId, array $notification); + + /** + * get the supported share types, e.g. "user", "group", etc. + * + * @return array + * + * @since 14.0.0 + */ + public function getSupportedShareTypes(); +} diff --git a/lib/public/Federation/ICloudFederationProviderManager.php b/lib/public/Federation/ICloudFederationProviderManager.php new file mode 100644 index 00000000000..68adb4b4da7 --- /dev/null +++ b/lib/public/Federation/ICloudFederationProviderManager.php @@ -0,0 +1,110 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Federation; + +use OCP\Http\Client\IResponse; +use OCP\OCM\Exceptions\OCMProviderException; + +/** + * Class ICloudFederationProviderManager + * + * Manage cloud federation providers + * + * @since 14.0.0 + * + */ +interface ICloudFederationProviderManager { + /** + * Registers an callback function which must return an cloud federation provider + * + * @param string $resourceType which resource type does the provider handles + * @param string $displayName user facing name of the federated share provider + * @param callable $callback + * @throws Exceptions\ProviderAlreadyExistsException + * + * @since 14.0.0 + */ + public function addCloudFederationProvider($resourceType, $displayName, callable $callback); + + /** + * remove cloud federation provider + * + * @param string $resourceType + * + * @since 14.0.0 + */ + public function removeCloudFederationProvider($resourceType); + + /** + * get a list of all cloudFederationProviders + * + * @return array [resourceType => ['resourceType' => $resourceType, 'displayName' => $displayName, 'callback' => callback]] + * + * @since 14.0.0 + */ + public function getAllCloudFederationProviders(); + + /** + * get a specific cloud federation provider + * + * @param string $resourceType + * @return ICloudFederationProvider + * @throws Exceptions\ProviderDoesNotExistsException + * + * @since 14.0.0 + */ + public function getCloudFederationProvider($resourceType); + + /** + * send federated share + * + * @param ICloudFederationShare $share + * @return mixed + * + * @since 14.0.0 + * @deprecated 29.0.0 - Use {@see sendCloudShare()} instead and handle errors manually + */ + public function sendShare(ICloudFederationShare $share); + + /** + * @param ICloudFederationShare $share + * @return IResponse + * @throws OCMProviderException + * @since 29.0.0 + */ + public function sendCloudShare(ICloudFederationShare $share): IResponse; + + /** + * send notification about existing share + * + * @param string $url + * @param ICloudFederationNotification $notification + * @return array|false + * + * @since 14.0.0 + * @deprecated 29.0.0 - Use {@see sendCloudNotification()} instead and handle errors manually + */ + public function sendNotification($url, ICloudFederationNotification $notification); + + /** + * @param string $url + * @param ICloudFederationNotification $notification + * @return IResponse + * @throws OCMProviderException + * @since 29.0.0 + */ + public function sendCloudNotification(string $url, ICloudFederationNotification $notification): IResponse; + + /** + * check if the new cloud federation API is ready to be used + * + * @return bool + * + * @since 14.0.0 + */ + public function isReady(); +} diff --git a/lib/public/Federation/ICloudFederationShare.php b/lib/public/Federation/ICloudFederationShare.php new file mode 100644 index 00000000000..0b67bbfadee --- /dev/null +++ b/lib/public/Federation/ICloudFederationShare.php @@ -0,0 +1,232 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Federation; + +/** + * Interface ICloudFederationShare + * + * + * @since 14.0.0 + */ +interface ICloudFederationShare { + /** + * set uid of the recipient + * + * @param string $user + * + * @since 14.0.0 + */ + public function setShareWith($user); + + /** + * set resource name (e.g. file, calendar, contact,...) + * + * @param string $name + * + * @since 14.0.0 + */ + public function setResourceName($name); + + /** + * set resource type (e.g. file, calendar, contact,...) + * + * @param string $resourceType + * + * @since 14.0.0 + */ + public function setResourceType($resourceType); + + /** + * set resource description (optional) + * + * @param string $description + * + * @since 14.0.0 + */ + public function setDescription($description); + + /** + * set provider ID (e.g. file ID) + * + * @param string $providerId + * + * @since 14.0.0 + */ + public function setProviderId($providerId); + + /** + * set owner UID + * + * @param string $owner + * + * @since 14.0.0 + */ + public function setOwner($owner); + + /** + * set owner display name + * + * @param string $ownerDisplayName + * + * @since 14.0.0 + */ + public function setOwnerDisplayName($ownerDisplayName); + + /** + * set UID of the user who sends the share + * + * @param string $sharedBy + * + * @since 14.0.0 + */ + public function setSharedBy($sharedBy); + + /** + * set display name of the user who sends the share + * + * @param $sharedByDisplayName + * + * @since 14.0.0 + */ + public function setSharedByDisplayName($sharedByDisplayName); + + /** + * set protocol specification + * + * @param array $protocol + * + * @since 14.0.0 + */ + public function setProtocol(array $protocol); + + /** + * share type (group or user) + * + * @param string $shareType + * + * @since 14.0.0 + */ + public function setShareType($shareType); + + /** + * get the whole share, ready to send out + * + * @return array + * + * @since 14.0.0 + */ + public function getShare(); + + /** + * get uid of the recipient + * + * @return string + * + * @since 14.0.0 + */ + public function getShareWith(); + + /** + * get resource name (e.g. file, calendar, contact,...) + * + * @return string + * + * @since 14.0.0 + */ + public function getResourceName(); + + /** + * get resource type (e.g. file, calendar, contact,...) + * + * @return string + * + * @since 14.0.0 + */ + public function getResourceType(); + + /** + * get resource description (optional) + * + * @return string + * + * @since 14.0.0 + */ + public function getDescription(); + + /** + * get provider ID (e.g. file ID) + * + * @return string + * + * @since 14.0.0 + */ + public function getProviderId(); + + /** + * get owner UID + * + * @return string + * + * @since 14.0.0 + */ + public function getOwner(); + + /** + * get owner display name + * + * @return string + * + * @since 14.0.0 + */ + public function getOwnerDisplayName(); + + /** + * get UID of the user who sends the share + * + * @return string + * + * @since 14.0.0 + */ + public function getSharedBy(); + + /** + * get display name of the user who sends the share + * + * @return string + * + * @since 14.0.0 + */ + public function getSharedByDisplayName(); + + /** + * get share type (group or user) + * + * @return string + * + * @since 14.0.0 + */ + public function getShareType(); + + /** + * get share Secret + * + * @return string + * + * @since 14.0.0 + */ + public function getShareSecret(); + + + /** + * get protocol specification + * + * @return array + * + * @since 14.0.0 + */ + public function getProtocol(); +} diff --git a/lib/public/Federation/ICloudId.php b/lib/public/Federation/ICloudId.php new file mode 100644 index 00000000000..44b653e327e --- /dev/null +++ b/lib/public/Federation/ICloudId.php @@ -0,0 +1,48 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Federation; + +/** + * Parsed federated cloud id + * + * @since 12.0.0 + */ +interface ICloudId { + /** + * The remote cloud id + * + * @return string + * @since 12.0.0 + */ + public function getId(): string; + + /** + * Get a clean representation of the cloud id for display + * + * @return string + * @since 12.0.0 + */ + public function getDisplayId(): string; + + /** + * The username on the remote server + * + * @return string + * @since 12.0.0 + */ + public function getUser(): string; + + /** + * The base address of the remote server + * + * @return string + * @since 12.0.0 + */ + public function getRemote(): string; +} diff --git a/lib/public/Federation/ICloudIdManager.php b/lib/public/Federation/ICloudIdManager.php new file mode 100644 index 00000000000..29e261ab3af --- /dev/null +++ b/lib/public/Federation/ICloudIdManager.php @@ -0,0 +1,85 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Federation; + +use OCP\AppFramework\Attribute\Consumable; + +/** + * Interface for resolving federated cloud ids + * + * @since 12.0.0 + */ +#[Consumable(since: '12.0.0')] +interface ICloudIdManager { + /** + * @param string $cloudId + * @return ICloudId + * @throws \InvalidArgumentException + * + * @since 12.0.0 + */ + public function resolveCloudId(string $cloudId): ICloudId; + + /** + * Get the cloud id for a remote user + * + * @param string $user + * @param string|null $remote (optional since 23.0.0 for local users) + * @return ICloudId + * + * @since 12.0.0 + */ + public function getCloudId(string $user, ?string $remote): ICloudId; + + /** + * Check if the input is a correctly formatted cloud id + * + * @param string $cloudId + * @return bool + * + * @since 12.0.0 + */ + public function isValidCloudId(string $cloudId): bool; + + /** + * remove scheme/protocol from an url + * + * @param string $url + * @param bool $httpsOnly + * + * @return string + * @since 28.0.0 + * @since 30.0.0 - Optional parameter $httpsOnly was added + */ + public function removeProtocolFromUrl(string $url, bool $httpsOnly = false): string; + + /** + * @param string $id The remote cloud id + * @param string $user The user id on the remote server + * @param string $remote The base address of the remote server + * @param ?string $displayName The displayname of the remote user + * + * @since 32.0.0 + */ + public function createCloudId(string $id, string $user, string $remote, ?string $displayName = null): ICloudId; + + /** + * @param $resolver The cloud id resolver to register + * + * @since 32.0.0 + */ + public function registerCloudIdResolver(ICloudIdResolver $resolver): void; + + /** + * @param $resolver The cloud id resolver to unregister + * + * @since 32.0.0 + */ + public function unregisterCloudIdResolver(ICloudIdResolver $resolver): void; +} diff --git a/lib/public/Federation/ICloudIdResolver.php b/lib/public/Federation/ICloudIdResolver.php new file mode 100644 index 00000000000..79f9ed11dd7 --- /dev/null +++ b/lib/public/Federation/ICloudIdResolver.php @@ -0,0 +1,40 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-only + */ +namespace OCP\Federation; + +use OCP\AppFramework\Attribute\Consumable; +use OCP\AppFramework\Attribute\Implementable; + +/** + * Interface for resolving federated cloud ids + * + * @since 32.0.0 + */ +#[Consumable(since: '32.0.0')] +#[Implementable(since: '32.0.0')] +interface ICloudIdResolver { + /** + * @param string $cloudId + * @return ICloudId + * @throws \InvalidArgumentException + * + * @since 32.0.0 + */ + public function resolveCloudId(string $cloudId): ICloudId; + + /** + * Check if the input is a correctly formatted cloud id + * + * @param string $cloudId + * @return bool + * + * @since 32.0.0 + */ + public function isValidCloudId(string $cloudId): bool; +} |