Merge branch 'master' into refactor_files_app_commands

Signed-off-by: Faraz Samapoor <f.samapoor@gmail.com>

.drone.yml

@@ -1,3 +1,4 @@
+---
 kind: pipeline
 name: checkers
 
@@ -1995,3 +1996,6 @@ trigger:
   event:
     - pull_request
     - push
+---
+kind: signature
+hmac: a5c0c1e40125b53ff88c617699710f3dc9685d80f06fd8f560b2662ccb1c3497

.github/CODEOWNERS

@@ -31,9 +31,9 @@
 
 # Two-Factor Authentication
 # https://github.com/nextcloud/wg-two-factor-authentication#members
-/apps/twofactor_backupcodes         @ChristophWurst @miaulalala @nickvergessen
-*/TwoFactorAuth/*                   @ChristophWurst @miaulalala @nickvergessen
-/core/templates/twofactor*          @ChristophWurst @miaulalala @nickvergessen
+**/TwoFactorAuth                    @ChristophWurst @miaulalala @nickvergessen @st3iny
+/apps/twofactor_backupcodes         @ChristophWurst @miaulalala @nickvergessen @st3iny
+/core/templates/twofactor*          @ChristophWurst @miaulalala @nickvergessen @st3iny
 
 # Personal interest
 */Activity/*                        @nickvergessen

apps/admin_audit/l10n/hi_IN.js

@@ -0,0 +1,7 @@
+OC.L10N.register(
+    "admin_audit",
+    {
+    "Auditing / Logging" : "ऑडिटिंग/लॉगिंग",
+    "Provides logging abilities for Nextcloud such as logging file accesses or otherwise sensitive actions." : "नेक्स्टक्लाउड के लिए लॉगिंग क्षमताएं प्रदान करता है जैसे फ़ाइल एक्सेस या अन्यथा संवेदनशील कार्यों को लॉग करना।"
+},
+"nplurals=2; plural=(n != 1);");

apps/admin_audit/l10n/hi_IN.json

@@ -0,0 +1,5 @@
+{ "translations": {
+    "Auditing / Logging" : "ऑडिटिंग/लॉगिंग",
+    "Provides logging abilities for Nextcloud such as logging file accesses or otherwise sensitive actions." : "नेक्स्टक्लाउड के लिए लॉगिंग क्षमताएं प्रदान करता है जैसे फ़ाइल एक्सेस या अन्यथा संवेदनशील कार्यों को लॉग करना।"
+},"pluralForm" :"nplurals=2; plural=(n != 1);"
+}

apps/cloud_federation_api/composer/composer/autoload_classmap.php

@@ -11,4 +11,5 @@
     '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\\ResponseDefinitions' => $baseDir . '/../lib/ResponseDefinitions.php',
 );

apps/cloud_federation_api/composer/composer/autoload_static.php

@@ -26,6 +26,7 @@ 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\\ResponseDefinitions' => __DIR__ . '/..' . '/../lib/ResponseDefinitions.php',
     );
 
     public static function getInitializer(ClassLoader $loader)

apps/cloud_federation_api/l10n/es_EC.js

@@ -0,0 +1,8 @@
+OC.L10N.register(
+    "cloud_federation_api",
+    {
+    "Cloud Federation API" : "API de Federación en la Nube",
+    "Enable clouds to communicate with each other and exchange data" : "Permitir que las nubes se comuniquen entre sí e intercambien datos",
+    "The Cloud Federation API enables various Nextcloud instances to communicate with each other and to exchange data." : "La API de Federación de Nubes permite que varias instancias de Nextcloud se comuniquen entre sí y intercambien datos."
+},
+"nplurals=3; plural=n == 1 ? 0 : n != 0 && n % 1000000 == 0 ? 1 : 2;");

apps/cloud_federation_api/l10n/es_EC.json

@@ -0,0 +1,6 @@
+{ "translations": {
+    "Cloud Federation API" : "API de Federación en la Nube",
+    "Enable clouds to communicate with each other and exchange data" : "Permitir que las nubes se comuniquen entre sí e intercambien datos",
+    "The Cloud Federation API enables various Nextcloud instances to communicate with each other and to exchange data." : "La API de Federación de Nubes permite que varias instancias de Nextcloud se comuniquen entre sí y intercambien datos."
+},"pluralForm" :"nplurals=3; plural=n == 1 ? 0 : n != 0 && n % 1000000 == 0 ? 1 : 2;"
+}

apps/cloud_federation_api/l10n/uk.js

@@ -3,6 +3,6 @@ OC.L10N.register(
     {
     "Cloud Federation API" : "Cloud Federation API",
     "Enable clouds to communicate with each other and exchange data" : "Увімкніть хмари аби спілкуватися один з одним і обмінюватися даними",
-    "The Cloud Federation API enables various Nextcloud instances to communicate with each other and to exchange data." : "Cloud Federation API дозволяє різним екземплярам Nextcloud спілкуватися між собою та обмінюватися даними."
+    "The Cloud Federation API enables various Nextcloud instances to communicate with each other and to exchange data." : "Cloud Federation API дозволяє різним примірникам серверу хмари Nextcloud спілкуватися між собою та обмінюватися даними."
 },
 "nplurals=4; plural=(n % 1 == 0 && n % 10 == 1 && n % 100 != 11 ? 0 : n % 1 == 0 && n % 10 >= 2 && n % 10 <= 4 && (n % 100 < 12 || n % 100 > 14) ? 1 : n % 1 == 0 && (n % 10 ==0 || (n % 10 >=5 && n % 10 <=9) || (n % 100 >=11 && n % 100 <=14 )) ? 2: 3);");

apps/cloud_federation_api/l10n/uk.json

@@ -1,6 +1,6 @@
 { "translations": {
     "Cloud Federation API" : "Cloud Federation API",
     "Enable clouds to communicate with each other and exchange data" : "Увімкніть хмари аби спілкуватися один з одним і обмінюватися даними",
-    "The Cloud Federation API enables various Nextcloud instances to communicate with each other and to exchange data." : "Cloud Federation API дозволяє різним екземплярам Nextcloud спілкуватися між собою та обмінюватися даними."
+    "The Cloud Federation API enables various Nextcloud instances to communicate with each other and to exchange data." : "Cloud Federation API дозволяє різним примірникам серверу хмари Nextcloud спілкуватися між собою та обмінюватися даними."
 },"pluralForm" :"nplurals=4; plural=(n % 1 == 0 && n % 10 == 1 && n % 100 != 11 ? 0 : n % 1 == 0 && n % 10 >= 2 && n % 10 <= 4 && (n % 100 < 12 || n % 100 > 14) ? 1 : n % 1 == 0 && (n % 10 ==0 || (n % 10 >=5 && n % 10 <=9) || (n % 100 >=11 && n % 100 <=14 )) ? 2: 3);"
 }

apps/cloud_federation_api/lib/Capabilities.php

@@ -3,6 +3,7 @@
  * @copyright Copyright (c) 2017 Bjoern Schiessle <bjoern@schiessle.org>
  *
  * @author Bjoern Schiessle <bjoern@schiessle.org>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -36,6 +37,21 @@ public function __construct(IURLGenerator $urlGenerator) {
 
 	/**
 	 * Function an app uses to return the capabilities
+	 *
+	 * @return array{
+	 *     ocm: array{
+	 *         enabled: bool,
+	 *         apiVersion: string,
+	 *         endPoint: string,
+	 *         resourceTypes: array{
+	 *             name: string,
+	 *             shareTypes: string[],
+	 *             protocols: array{
+	 *                 webdav: string,
+	 *	           },
+	 *	       }[],
+	 *	   },
+	 * }
 	 */
 	public function getCapabilities() {
 		$url = $this->urlGenerator->linkToRouteAbsolute('cloud_federation_api.requesthandlercontroller.addShare');

apps/cloud_federation_api/lib/Controller/RequestHandlerController.php

@@ -5,6 +5,7 @@
  * @author Bjoern Schiessle <bjoern@schiessle.org>
  * @author Christoph Wurst <christoph@winzerhof-wurst.at>
  * @author Roeland Jago Douma <roeland@famdouma.nl>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -25,6 +26,7 @@
 namespace OCA\CloudFederationAPI\Controller;
 
 use OCA\CloudFederationAPI\Config;
+use OCA\CloudFederationAPI\ResponseDefinitions;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\JSONResponse;
@@ -44,11 +46,13 @@
 use Psr\Log\LoggerInterface;
 
 /**
- * Class RequestHandlerController
- *
- * handle API between different Cloud instances
+ * Open-Cloud-Mesh-API
  *
  * @package OCA\CloudFederationAPI\Controller
+ *
+ * @psalm-import-type CloudFederationApiAddShare from ResponseDefinitions
+ * @psalm-import-type CloudFederationApiValidationError from ResponseDefinitions
+ * @psalm-import-type CloudFederationApiError from ResponseDefinitions
  */
 class RequestHandlerController extends Controller {
 
@@ -100,26 +104,28 @@ public function __construct($appName,
 	}
 
 	/**
-	 * add share
+	 * Add share
 	 *
 	 * @NoCSRFRequired
 	 * @PublicPage
 	 * @BruteForceProtection(action=receiveFederatedShare)
 	 *
-	 * @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 array $protocol (e,.g. ['name' => 'webdav', 'options' => ['username' => 'john', 'permissions' => 31]])
-	 * @param string $shareType ('group' or 'user' share)
-	 * @param $resourceType ('file', 'calendar',...)
-	 * @return Http\DataResponse|JSONResponse
+	 * @param string $shareWith The user who the share will be shared with
+	 * @param string $name The resource name (e.g. document.odt)
+	 * @param string|null $description Share description
+	 * @param string $providerId Resource UID on the provider side
+	 * @param string $owner Provider specific UID of the user who owns the resource
+	 * @param string|null $ownerDisplayName Display name of the user who shared the item
+	 * @param string|null $sharedBy Provider specific UID of the user who shared the resource
+	 * @param string|null $sharedByDisplayName Display name of the user who shared the resource
+	 * @param array{name: string[], options: array<string, mixed>} $protocol e,.g. ['name' => 'webdav', 'options' => ['username' => 'john', 'permissions' => 31]]
+	 * @param string $shareType 'group' or 'user' share
+	 * @param string $resourceType 'file', 'calendar',...
 	 *
-	 * Example: curl -H "Content-Type: application/json" -X POST -d '{"shareWith":"admin1@serve1","name":"welcome server2.txt","description":"desc","providerId":"2","owner":"admin2@http://localhost/server2","ownerDisplayName":"admin2 display","shareType":"user","resourceType":"file","protocol":{"name":"webdav","options":{"sharedSecret":"secret","permissions":"webdav-property"}}}' http://localhost/server/index.php/ocm/shares
+	 * @return JSONResponse<Http::STATUS_CREATED, CloudFederationApiAddShare, array{}>|JSONResponse<Http::STATUS_BAD_REQUEST, CloudFederationApiValidationError, array{}>|JSONResponse<Http::STATUS_NOT_IMPLEMENTED, CloudFederationApiError, array{}>
+	 * 201: The notification was successfully received. The display name of the recipient might be returned in the body
+	 * 400: Bad request due to invalid parameters, e.g. when `shareWith` is not found or required properties are missing
+	 * 501: Share type or the resource type is not supported
 	 */
 	public function addShare($shareWith, $name, $description, $providerId, $owner, $ownerDisplayName, $sharedBy, $sharedByDisplayName, $protocol, $shareType, $resourceType) {
 
@@ -137,7 +143,10 @@ public function addShare($shareWith, $name, $description, $providerId, $owner, $
 			!isset($protocol['options']['sharedSecret'])
 		) {
 			return new JSONResponse(
-				['message' => 'Missing arguments'],
+				[
+					'message' => 'Missing arguments',
+					'validationErrors' => [],
+				],
 				Http::STATUS_BAD_REQUEST
 			);
 		}
@@ -158,7 +167,10 @@ public function addShare($shareWith, $name, $description, $providerId, $owner, $
 
 			if (!$this->userManager->userExists($shareWith)) {
 				$response = new JSONResponse(
-					['message' => 'User "' . $shareWith . '" does not exists at ' . $this->urlGenerator->getBaseUrl()],
+					[
+						'message' => 'User "' . $shareWith . '" does not exists at ' . $this->urlGenerator->getBaseUrl(),
+						'validationErrors' => [],
+					],
 					Http::STATUS_BAD_REQUEST
 				);
 				$response->throttle();
@@ -169,7 +181,10 @@ public function addShare($shareWith, $name, $description, $providerId, $owner, $
 		if ($shareType === 'group') {
 			if (!$this->groupManager->groupExists($shareWith)) {
 				$response = new JSONResponse(
-					['message' => 'Group "' . $shareWith . '" does not exists at ' . $this->urlGenerator->getBaseUrl()],
+					[
+						'message' => 'Group "' . $shareWith . '" does not exists at ' . $this->urlGenerator->getBaseUrl(),
+						'validationErrors' => [],
+					],
 					Http::STATUS_BAD_REQUEST
 				);
 				$response->throttle();
@@ -192,20 +207,18 @@ public function addShare($shareWith, $name, $description, $providerId, $owner, $
 			$share = $this->factory->getCloudFederationShare($shareWith, $name, $description, $providerId, $owner, $ownerDisplayName, $sharedBy, $sharedByDisplayName, '', $shareType, $resourceType);
 			$share->setProtocol($protocol);
 			$provider->shareReceived($share);
-		} catch (ProviderDoesNotExistsException $e) {
+		} catch (ProviderDoesNotExistsException|ProviderCouldNotAddShareException $e) {
 			return new JSONResponse(
 				['message' => $e->getMessage()],
 				Http::STATUS_NOT_IMPLEMENTED
 			);
-		} catch (ProviderCouldNotAddShareException $e) {
-			return new JSONResponse(
-				['message' => $e->getMessage()],
-				$e->getCode()
-			);
 		} catch (\Exception $e) {
 			$this->logger->error($e->getMessage(), ['exception' => $e]);
 			return new JSONResponse(
-				['message' => 'Internal error at ' . $this->urlGenerator->getBaseUrl()],
+				[
+					'message' => 'Internal error at ' . $this->urlGenerator->getBaseUrl(),
+					'validationErrors' => [],
+				],
 				Http::STATUS_BAD_REQUEST
 			);
 		}
@@ -222,19 +235,24 @@ public function addShare($shareWith, $name, $description, $providerId, $owner, $
 	}
 
 	/**
-	 * receive notification about existing share
+	 * Send a notification about an existing share
 	 *
 	 * @NoCSRFRequired
 	 * @PublicPage
 	 * @BruteForceProtection(action=receiveFederatedShareNotification)
 	 *
-	 * @param string $notificationType (notification type, e.g. SHARE_ACCEPTED)
-	 * @param string $resourceType (calendar, file, contact,...)
-	 * @param string $providerId id of the share
-	 * @param array $notification the actual payload of the notification
-	 * @return JSONResponse
+	 * @param string $notificationType Notification type, e.g. SHARE_ACCEPTED
+	 * @param string $resourceType calendar, file, contact,...
+	 * @param string|null $providerId ID of the share
+	 * @param array<string, mixed>|null $notification The actual payload of the notification
+	 *
+	 * @return JSONResponse<Http::STATUS_CREATED, array<string, mixed>, array{}>|JSONResponse<Http::STATUS_BAD_REQUEST, CloudFederationApiValidationError, array{}>|JSONResponse<Http::STATUS_FORBIDDEN|Http::STATUS_NOT_IMPLEMENTED, CloudFederationApiError, array{}>
+	 * 201: The notification was successfully received
+	 * 400: Bad request due to invalid parameters, e.g. when `type` is invalid or missing
+	 * 403: Getting resource is not allowed
+	 * 501: The resource type is not supported
 	 */
-	public function receiveNotification($notificationType, $resourceType, $providerId, array $notification) {
+	public function receiveNotification($notificationType, $resourceType, $providerId, ?array $notification) {
 
 		// check if all required parameters are set
 		if ($notificationType === null ||
@@ -243,7 +261,10 @@ public function receiveNotification($notificationType, $resourceType, $providerI
 			!is_array($notification)
 		) {
 			return new JSONResponse(
-				['message' => 'Missing arguments'],
+				[
+					'message' => 'Missing arguments',
+					'validationErrors' => [],
+				],
 				Http::STATUS_BAD_REQUEST
 			);
 		}
@@ -253,12 +274,18 @@ public function receiveNotification($notificationType, $resourceType, $providerI
 			$result = $provider->notificationReceived($notificationType, $providerId, $notification);
 		} catch (ProviderDoesNotExistsException $e) {
 			return new JSONResponse(
-				['message' => $e->getMessage()],
+				[
+					'message' => $e->getMessage(),
+					'validationErrors' => [],
+				],
 				Http::STATUS_BAD_REQUEST
 			);
 		} catch (ShareNotFound $e) {
 			$response = new JSONResponse(
-				['message' => $e->getMessage()],
+				[
+					'message' => $e->getMessage(),
+					'validationErrors' => [],
+				],
 				Http::STATUS_BAD_REQUEST
 			);
 			$response->throttle();
@@ -276,7 +303,10 @@ public function receiveNotification($notificationType, $resourceType, $providerI
 			return $response;
 		} catch (\Exception $e) {
 			return new JSONResponse(
-				['message' => 'Internal error at ' . $this->urlGenerator->getBaseUrl()],
+				[
+					'message' => 'Internal error at ' . $this->urlGenerator->getBaseUrl(),
+					'validationErrors' => [],
+				],
 				Http::STATUS_BAD_REQUEST
 			);
 		}

apps/cloud_federation_api/lib/ResponseDefinitions.php

@@ -0,0 +1,45 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2023 Kate Döen <kate.doeen@nextcloud.com>
+ *
+ * @author Kate Döen <kate.doeen@nextcloud.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCA\CloudFederationAPI;
+
+/**
+ * @psalm-type CloudFederationApiAddShare = array{
+ *     recipientDisplayName: string,
+ * }
+ *
+ * @psalm-type CloudFederationApiError = array{
+ *     message: string,
+ * }
+ *
+ * @psalm-type CloudFederationApiValidationError = CloudFederationApiError&array{
+ *     validationErrors: array{
+ *          name: string,
+ *          message: string|null,
+ *     }[],
+ * }
+ */
+class ResponseDefinitions {
+}