Add public share token editing

Signed-off-by: Alexander Rebello <me@alexander-rebello.de>

Author: alexander-rebello

docs/API_v3.md

@@ -653,6 +653,30 @@ Update a single or all properties of an option-object
 "data": 5
 ```
 
+### Update a Public Share Token
+
+- Endpoint: `/api/v3/forms/{formId}/shares/{shareId}/token`
+- Method: `PATCH`
+- Url-Parameters:
+  | Parameter | Type | Description |
+  |-----------|---------|-------------|
+  | _formId_ | Integer | ID of the form containing the share |
+  | _shareId_ | Integer | ID of the public link share to update |
+- Parameters:
+  | Parameter | Type | Description |
+  |-----------|---------|-------------|
+  | _token_ | String | New token for the public share link |
+- Restrictions:
+  - Only available when the admin setting _allowCustomPublicShareTokens_ is enabled.
+  - Only link shares can be updated.
+  - Token must be unique among link shares and only contain alphanumeric characters.
+  - Token length must be between 8 and 256 characters.
+- Response: **Status-Code OK**, as well as the id of the updated share.
+
+```
+"data": 5
+```
+
 ## Submission Endpoints
 
 ### Get Form Submissions

lib/Controller/PageController.php

@@ -40,6 +40,7 @@
 #[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class PageController extends Controller {
 	private const TEMPLATE_MAIN = 'main';
+	private const PUBLIC_SHARE_HASH_REQUIREMENT = '[a-zA-Z0-9]{8,256}';
 
 	public function __construct(
 		string $appName,
@@ -145,7 +146,7 @@ public function internalLinkView(string $hash): Response {
 	#[NoAdminRequired()]
 	#[NoCSRFRequired()]
 	#[PublicPage()]
-	#[FrontpageRoute(verb: 'GET', url: '/s/{hash}', requirements: ['hash' => '[a-zA-Z0-9]{24,}'])]
+	#[FrontpageRoute(verb: 'GET', url: '/s/{hash}', requirements: ['hash' => self::PUBLIC_SHARE_HASH_REQUIREMENT])]
 	public function publicLinkView(string $hash): Response {
 		try {
 			$share = $this->shareMapper->findPublicShareByHash($hash);

lib/Controller/ShareApiController.php

@@ -301,6 +301,85 @@ public function updateShare(int $formId, int $shareId, array $keyValuePairs): Da
 		return new DataResponse($formShare->getId());
 	}
 
+	/**
+	 * Update token/hash of a public link share
+	 *
+	 * @param int $formId of the form
+	 * @param int $shareId of the share to update
+	 * @param string $token The new share token
+	 * @return DataResponse<Http::STATUS_OK, int, array{}>
+	 * @throws OCSBadRequestException Share doesn't belong to given Form
+	 * @throws OCSBadRequestException Invalid share token
+	 * @throws OCSBadRequestException Share hash exists, please retry
+	 * @throws OCSForbiddenException Custom public share tokens are not allowed
+	 * @throws OCSForbiddenException Not allowed to update token on non-link share
+	 * @throws OCSForbiddenException This form is not owned by the current user
+	 * @throws OCSNotFoundException Could not find share
+	 *
+	 * 200: the id of the updated share
+	 */
+	#[CORS()]
+	#[NoAdminRequired()]
+	#[ApiRoute(verb: 'PATCH', url: '/api/v3/forms/{formId}/shares/{shareId}/token')]
+	public function updateShareToken(int $formId, int $shareId, string $token): DataResponse {
+		$this->logger->debug('Updating share token: {shareId} of form {formId}', [
+			'formId' => $formId,
+			'shareId' => $shareId,
+		]);
+
+		if (!$this->configService->getAllowCustomPublicToken()) {
+			$this->logger->debug('Custom public share tokens are not allowed.');
+			throw new OCSForbiddenException('Custom public share tokens are not allowed.');
+		}
+
+		$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);
+		} catch (IMapperException $e) {
+			$this->logger->debug('Could not find share', ['exception' => $e]);
+			throw new OCSNotFoundException('Could not find share');
+		}
+
+		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 ($formShare->getShareType() !== IShare::TYPE_LINK) {
+			$this->logger->debug('Not allowed to update token on non-link share');
+			throw new OCSForbiddenException('Not allowed to update token on non-link share');
+		}
+
+		if ($token === $formShare->getShareWith()) {
+			return new DataResponse($formShare->getId());
+		}
+
+		$this->validatePublicShareToken($token);
+
+		try {
+			$existingShare = $this->shareMapper->findPublicShareByHash($token);
+			if ($existingShare->getId() !== $formShare->getId()) {
+				$this->logger->debug('Share hash already exists.');
+				throw new OCSBadRequestException('Share hash exists, please retry.');
+			}
+		} catch (DoesNotExistException $e) {
+			// Just continue, this is what we expect to happen (share hash not existing yet).
+		}
+
+		$this->formsService->obtainFormLock($form);
+
+		$formShare->setShareWith($token);
+		$formShare = $this->shareMapper->update($formShare);
+		$this->formMapper->update($form);
+
+		return new DataResponse($formShare->getId());
+	}
+
 	/**
 	 * Delete a share
 	 *
@@ -421,4 +500,22 @@ private function validatePermissions(array $permissions, int $shareType): bool {
 		}
 		return true;
 	}
+
+	/**
+	 * @throws OCSBadRequestException If token does not satisfy basic safety checks
+	 */
+	private function validatePublicShareToken(string $token): void {
+		if ($token !== trim($token)) {
+			throw new OCSBadRequestException('Invalid share token');
+		}
+
+		$tokenLength = strlen($token);
+		if ($tokenLength < Constants::PUBLIC_SHARE_TOKEN_MIN_LENGTH || $tokenLength > Constants::PUBLIC_SHARE_TOKEN_MAX_LENGTH) {
+			throw new OCSBadRequestException('Invalid share token');
+		}
+
+		if (preg_match('/^[a-zA-Z0-9]+$/', $token) !== 1) {
+			throw new OCSBadRequestException('Invalid share token');
+		}
+	}
 }

tests/Unit/Controller/ShareApiControllerTest.php

@@ -952,4 +952,155 @@ public function testUpdateShare_NotExistingForm() {
 		$this->expectException(NoSuchFormException::class);
 		$this->shareApiController->updateShare(7331, 1337, [Constants::PERMISSION_SUBMIT]);
 	}
+
+	public function testUpdateShareToken() {
+		$form = new Form();
+		$form->setId('5');
+		$form->setOwnerId('currentUser');
+
+		$this->configService->expects($this->once())
+			->method('getAllowCustomPublicToken')
+			->willReturn(true);
+
+		$this->formsService->expects($this->once())
+			->method('getFormIfAllowed')
+			->with(5)
+			->willReturn($form);
+
+		$share = new Share();
+		$share->setId(8);
+		$share->setFormId(5);
+		$share->setShareType(IShare::TYPE_LINK);
+		$share->setShareWith('abcdefgh');
+		$share->setPermissions([Constants::PERMISSION_SUBMIT]);
+
+		$this->shareMapper->expects($this->once())
+			->method('findById')
+			->with(8)
+			->willReturn($share);
+
+		$this->shareMapper->expects($this->once())
+			->method('findPublicShareByHash')
+			->with('tokenabcd')
+			->willThrowException(new DoesNotExistException('Not found'));
+
+		$this->shareMapper->expects($this->once())
+			->method('update')
+			->willReturnCallback(function (Share $updatedShare) {
+				$this->assertSame('tokenabcd', $updatedShare->getShareWith());
+				return $updatedShare;
+			});
+
+		$this->assertEquals(new DataResponse(8), $this->shareApiController->updateShareToken(5, 8, 'tokenabcd'));
+	}
+
+	public function testUpdateShareToken_CustomTokensDisabled() {
+		$this->configService->expects($this->once())
+			->method('getAllowCustomPublicToken')
+			->willReturn(false);
+
+		$this->expectException(OCSForbiddenException::class);
+		$this->shareApiController->updateShareToken(5, 8, 'tokenabcd');
+	}
+
+	public function testUpdateShareToken_ForbiddenForNonLinkShare() {
+		$form = new Form();
+		$form->setId('5');
+		$form->setOwnerId('currentUser');
+
+		$this->configService->expects($this->once())
+			->method('getAllowCustomPublicToken')
+			->willReturn(true);
+
+		$this->formsService->expects($this->once())
+			->method('getFormIfAllowed')
+			->with(5)
+			->willReturn($form);
+
+		$share = new Share();
+		$share->setId(8);
+		$share->setFormId(5);
+		$share->setShareType(IShare::TYPE_USER);
+		$share->setShareWith('user1');
+
+		$this->shareMapper->expects($this->once())
+			->method('findById')
+			->with(8)
+			->willReturn($share);
+
+		$this->expectException(OCSForbiddenException::class);
+		$this->shareApiController->updateShareToken(5, 8, 'tokenabcd');
+	}
+
+	public function testUpdateShareToken_DuplicateHash() {
+		$form = new Form();
+		$form->setId('5');
+		$form->setOwnerId('currentUser');
+
+		$this->configService->expects($this->once())
+			->method('getAllowCustomPublicToken')
+			->willReturn(true);
+
+		$this->formsService->expects($this->once())
+			->method('getFormIfAllowed')
+			->with(5)
+			->willReturn($form);
+
+		$currentShare = new Share();
+		$currentShare->setId(8);
+		$currentShare->setFormId(5);
+		$currentShare->setShareType(IShare::TYPE_LINK);
+		$currentShare->setShareWith('abcdefgh');
+
+		$existingShare = new Share();
+		$existingShare->setId(9);
+		$existingShare->setFormId(5);
+		$existingShare->setShareType(IShare::TYPE_LINK);
+		$existingShare->setShareWith('tokenabcd');
+
+		$this->shareMapper->expects($this->once())
+			->method('findById')
+			->with(8)
+			->willReturn($currentShare);
+
+		$this->shareMapper->expects($this->once())
+			->method('findPublicShareByHash')
+			->with('tokenabcd')
+			->willReturn($existingShare);
+
+		$this->expectException(OCSBadRequestException::class);
+		$this->shareApiController->updateShareToken(5, 8, 'tokenabcd');
+	}
+
+	public function testUpdateShareToken_InvalidToken() {
+		$form = new Form();
+		$form->setId('5');
+		$form->setOwnerId('currentUser');
+
+		$this->configService->expects($this->once())
+			->method('getAllowCustomPublicToken')
+			->willReturn(true);
+
+		$this->formsService->expects($this->once())
+			->method('getFormIfAllowed')
+			->with(5)
+			->willReturn($form);
+
+		$share = new Share();
+		$share->setId(8);
+		$share->setFormId(5);
+		$share->setShareType(IShare::TYPE_LINK);
+		$share->setShareWith('abcdefgh');
+
+		$this->shareMapper->expects($this->once())
+			->method('findById')
+			->with(8)
+			->willReturn($share);
+
+		$this->shareMapper->expects($this->never())
+			->method('update');
+
+		$this->expectException(OCSBadRequestException::class);
+		$this->shareApiController->updateShareToken(5, 8, 'invalid-token');
+	}
 }