Merge pull request #2737 from nextcloud/feat/shareEditPermission

feat: add form locking mechanism and share `edit` permission

Author: Chartman123

docs/API_v3.md

@@ -92,7 +92,9 @@ Returns condensed objects of all Forms beeing owned by the authenticated user.
       "submit"
     ],
     "partial": true,
-    "state": 0
+    "state": 0,
+    "lockedBy": null,
+    "lockedUntil": null
   },
   {
     "id": 3,
@@ -105,7 +107,9 @@ Returns condensed objects of all Forms beeing owned by the authenticated user.
       "submit"
     ],
     "partial": true,
-    "state": 0
+    "state": 0,
+    "lockedBy": "someUser"
+    "lockedUntil": 123456789
   }
 ]
 ```
@@ -169,6 +173,8 @@ Returns the full-depth object of the requested form (without submissions).
   "showExpiration": false,
   "canSubmit": true,
   "state": 0,
+  "lockedBy": null,
+  "lockedUntil": null,
   "permissions": [
     "edit",
     "results",

docs/DataStructure.md

@@ -26,6 +26,8 @@ This document describes the Object-Structure, that is used within the Forms App
 | expires              | unix-timestamp                       |                                         | When the form should expire. Timestamp `0` indicates _never_                                                                     |
 | isAnonymous          | Boolean                              |                                         | If Answers will be stored anonymously                                                                                            |
 | state                | Integer                              | [Form state](#form-state)               | The state of the form                                                                                                            |
+| lockedBy             | String                               |                                         | The user ID for who has exclusive edit access at the moment                                                                      |
+| lockedUntil          | unix timestamp                       |                                         | When the form lock will expire                                                                                                   |
 | submitMultiple       | Boolean                              |                                         | If users are allowed to submit multiple times to the form                                                                        |
 | allowEditSubmissions | Boolean                              |                                         | If users are allowed to edit or delete their response                                                                            |
 | showExpiration       | Boolean                              |                                         | If the expiration date will be shown on the form                                                                                 |
@@ -59,6 +61,8 @@ This document describes the Object-Structure, that is used within the Forms App
   ],
   "questions": [],
   "state": 0,
+  "lockedBy": null,
+  "lockedUntil": null,
   "shares": []
   "submissions": [],
   "submissionCount": 0,

img/lock_open.svg

@@ -104,6 +104,12 @@ public function newShare(int $formId, int $shareType, string $shareWith = '', ar
 			'permissions' => $permissions,
 		]);
 
+		$form = $this->formsService->getFormIfAllowed($formId);
+		if ($this->formsService->isFormArchived($form)) {
+			$this->logger->debug('This form is archived and can not be modified');
+			throw new OCSForbiddenException('This form is archived and can not be modified');
+		}
+
 		// Only accept usable shareTypes
 		if (array_search($shareType, Constants::SHARE_TYPES_USED) === false) {
 			$this->logger->debug('Invalid shareType');
@@ -116,24 +122,6 @@ public function newShare(int $formId, int $shareType, string $shareWith = '', ar
 			throw new OCSForbiddenException('Link share not allowed.');
 		}
 
-		try {
-			$form = $this->formMapper->findById($formId);
-		} catch (IMapperException $e) {
-			$this->logger->debug('Could not find form', ['exception' => $e]);
-			throw new OCSNotFoundException('Could not find form');
-		}
-
-		if ($this->formsService->isFormArchived($form)) {
-			$this->logger->debug('This form is archived and can not be modified');
-			throw new OCSForbiddenException('This form is archived and can not be modified');
-		}
-
-		// Check for permission to share form
-		if ($form->getOwnerId() !== $this->currentUser->getUID()) {
-			$this->logger->debug('This form is not owned by the current user');
-			throw new OCSForbiddenException('This form is not owned by the current user');
-		}
-
 		if (!$this->validatePermissions($permissions, $shareType)) {
 			throw new OCSBadRequestException('Invalid permission given');
 		}
@@ -194,6 +182,8 @@ public function newShare(int $formId, int $shareType, string $shareWith = '', ar
 				throw new OCSBadRequestException('Unknown shareType.');
 		}
 
+		$this->formsService->obtainFormLock($form);
+
 		$share = new Share();
 		$share->setFormId($formId);
 		$share->setShareType($shareType);
@@ -240,29 +230,24 @@ public function updateShare(int $formId, int $shareId, array $keyValuePairs): Da
 			'keyValuePairs' => $keyValuePairs
 		]);
 
+		$form = $this->formsService->getFormIfAllowed($formId);
+		if ($this->formsService->isFormArchived($form)) {
+			$this->logger->debug('This form is archived and can not be modified');
+			throw new OCSForbiddenException('This form is archived and can not be modified');
+		}
+
 		try {
 			$formShare = $this->shareMapper->findById($shareId);
-			$form = $this->formMapper->findById($formId);
 		} catch (IMapperException $e) {
 			$this->logger->debug('Could not find share', ['exception' => $e]);
 			throw new OCSNotFoundException('Could not find share');
 		}
 
-		if ($this->formsService->isFormArchived($form)) {
-			$this->logger->debug('This form is archived and can not be modified');
-			throw new OCSForbiddenException('This form is archived and can not be modified');
-		}
-
 		if ($formId !== $formShare->getFormId()) {
 			$this->logger->debug('This share doesn\'t belong to the given Form');
 			throw new OCSBadRequestException('Share doesn\'t belong to given Form');
 		}
 
-		if ($form->getOwnerId() !== $this->currentUser->getUID()) {
-			$this->logger->debug('This form is not owned by the current user');
-			throw new OCSForbiddenException('This form is not owned by the current user');
-		}
-
 		// Don't allow empty array
 		if (sizeof($keyValuePairs) === 0) {
 			$this->logger->info('Empty keyValuePairs, will not update.');
@@ -279,6 +264,8 @@ public function updateShare(int $formId, int $shareId, array $keyValuePairs): Da
 			throw new OCSBadRequestException('Invalid permission given');
 		}
 
+		$this->formsService->obtainFormLock($form);
+
 		$formShare->setPermissions($keyValuePairs['permissions']);
 		$formShare = $this->shareMapper->update($formShare);
 
@@ -338,28 +325,25 @@ public function deleteShare(int $formId, int $shareId): DataResponse {
 			'shareId' => $shareId,
 		]);
 
+		$form = $this->formsService->getFormIfAllowed($formId);
+		if ($this->formsService->isFormArchived($form)) {
+			$this->logger->debug('This form is archived and can not be modified');
+			throw new OCSForbiddenException('This form is archived and can not be modified');
+		}
+
 		try {
 			$share = $this->shareMapper->findById($shareId);
-			$form = $this->formMapper->findById($formId);
 		} catch (IMapperException $e) {
 			$this->logger->debug('Could not find share', ['exception' => $e]);
 			throw new OCSNotFoundException('Could not find share');
 		}
 
-		if ($this->formsService->isFormArchived($form)) {
-			$this->logger->debug('This form is archived and can not be modified');
-			throw new OCSForbiddenException('This form is archived and can not be modified');
-		}
-
 		if ($formId !== $share->getFormId()) {
 			$this->logger->debug('This share doesn\'t belong to the given Form');
 			throw new OCSBadRequestException('Share doesn\'t belong to given Form');
 		}
 
-		if ($form->getOwnerId() !== $this->currentUser->getUID()) {
-			$this->logger->debug('This form is not owned by the current user');
-			throw new OCSForbiddenException('This form is not owned by the current user');
-		}
+		$this->formsService->obtainFormLock($form);
 
 		$this->shareMapper->delete($share);
 		$this->formMapper->update($form);

lib/Controller/ApiController.php

@@ -47,6 +47,10 @@
  * @psalm-method 0|1|2 getState()
  * @method void setState(int|null $value)
  * @psalm-method void setState(0|1|2|null $value)
+ * @method string getLockedBy()
+ * @method void setLockedBy(string|null $value)
+ * @method int getLockedUntil()
+ * @method void setLockedUntil(int|null $value)
  */
 class Form extends Entity {
 	protected $hash;
@@ -65,6 +69,8 @@ class Form extends Entity {
 	protected $submissionMessage;
 	protected $lastUpdated;
 	protected $state;
+	protected $lockedBy;
+	protected $lockedUntil;
 
 	/**
 	 * Form constructor.
@@ -78,6 +84,8 @@ public function __construct() {
 		$this->addType('showExpiration', 'boolean');
 		$this->addType('lastUpdated', 'integer');
 		$this->addType('state', 'integer');
+		$this->addType('lockedBy', 'string');
+		$this->addType('lockedUntil', 'integer');
 	}
 
 	// JSON-Decoding of access-column.
@@ -149,6 +157,8 @@ public function setAccess(array $access): void {
 	 *   lastUpdated: int,
 	 *   submissionMessage: ?string,
 	 *   state: 0|1|2,
+	 *   lockedBy: ?string,
+	 *   lockedUntil: ?int,
 	 *  }
 	 */
 	public function read() {
@@ -170,6 +180,8 @@ public function read() {
 			'lastUpdated' => (int)$this->getLastUpdated(),
 			'submissionMessage' => $this->getSubmissionMessage(),
 			'state' => $this->getState(),
+			'lockedBy' => $this->getLockedBy(),
+			'lockedUntil' => $this->getLockedUntil(),
 		];
 	}
 }

lib/Controller/ShareApiController.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Forms\Migration;
+
+use Closure;
+use OCP\DB\ISchemaWrapper;
+use OCP\DB\Types;
+use OCP\Migration\IOutput;
+use OCP\Migration\SimpleMigrationStep;
+
+class Version050200Date20250512004000 extends SimpleMigrationStep {
+
+	/**
+	 * @param IOutput $output
+	 * @param Closure $schemaClosure The `\Closure` returns a `ISchemaWrapper`
+	 * @param array $options
+	 * @return null|ISchemaWrapper
+	 */
+	public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper {
+		/** @var ISchemaWrapper $schema */
+		$schema = $schemaClosure();
+		$table = $schema->getTable('forms_v2_forms');
+
+		if (!$table->hasColumn('locked_by')) {
+			$table->addColumn('locked_by', Types::STRING, [
+				'notnull' => false,
+				'default' => null,
+			]);
+		}
+
+		if (!$table->hascolumn('locked_until')) {
+			$table->addColumn('locked_until', Types::INTEGER, [
+				'notnull' => false,
+				'default' => null,
+				'comment' => 'unix-timestamp',
+			]);
+		}
+
+		return $schema;
+	}
+}

lib/Db/Form.php

@@ -104,7 +104,9 @@
  *   expires: int,
  *   permissions: list<FormsPermission>,
  *   partial: true,
- *   state: int
+ *   state: int,
+ *   lockedBy: ?string,
+ *   lockedUntil: ?int,
  * }
  *
  * @psalm-type FormsForm = array{
@@ -128,6 +130,8 @@
  *   permissions: list<FormsPermission>,
  *   questions: list<FormsQuestion>,
  *   state: 0|1|2,
+ *   lockedBy: ?string,
+ *   lockedUntil: ?int,
  *   shares: list<FormsShare>,
  *   submissionCount?: int,
  *   submissionMessage: ?string,