feat(forms): add submission email verification

Signed-off-by: Robert <61327381+QuiteBitter@users.noreply.github.com>

Author: QuiteBitter

docs/API_v3.md

@@ -439,6 +439,7 @@ Update a single or multiple properties of a question-object.
 - Restrictions:
     - It is **not allowed** to update one of the following key-value pairs: _id, formId, order_.
     - `extraSettings.confirmationRecipient` can only be enabled for short questions with `extraSettings.validationType` set to `email`.
+    - `extraSettings.requireEmailVerification` can only be enabled for short questions with `extraSettings.validationType` set to `email` and `extraSettings.confirmationRecipient` set to `true`.
 - Response: **Status-Code OK**, as well as the id of the updated question.
 
 ```
@@ -904,6 +905,7 @@ Store Submission to Database
     - For Question-Types with pre-defined answers (`multiple`, `multiple_unique`, `dropdown`), the array contains the corresponding option-IDs.
     - For File-Uploads, the array contains the objects with key `uploadedFileId` (value from Upload a file endpoint).
     - To send a respondent confirmation email, set the corresponding short question to `validationType = email` and `confirmationRecipient = true`.
+    - If the same question also sets `requireEmailVerification = true`, the submission stays pending until the recipient visits the verification link, and the confirmation email is only sent after verification succeeds.
 
 ```
   {

docs/DataStructure.md

@@ -148,6 +148,7 @@ A submission-object describes a single submission by a user to a form.
 | formId | Integer | | The id of the form, the submission belongs to |
 | userId | String | | The nextcloud userId of the submitting user. If submission is anonymous, this contains `anon-user-<hash>` |
 | timestamp | unix timestamp | | When the user submitted |
+| isVerified | Boolean | | Whether the submission has completed email-address verification, if required |
 | answers | Array of [Answers](#answer) | | Array of the actual user answers, belonging to this submission.
 | userDisplayName | String | | Display name of the nextcloud-user, derived from `userId`. Contains `Anonymous user` if submitted anonymously. Not stored in DB.
 
@@ -157,6 +158,7 @@ A submission-object describes a single submission by a user to a form.
   "formId": 3,
   "userId": "jonas",
   "timestamp": 1611274433,
+  "isVerified": true,
   "answers": [],
   "userDisplayName": "jonas"
 }
@@ -241,6 +243,7 @@ Optional extra settings for some [Question Types](#question-types)
 | `validationType`        | `short`                               | string           | `null, 'phone', 'email', 'regex', 'number'` | Custom validation for checking a submission                                 |
 | `validationRegex`       | `short`                               | string           | regular expression                          | if `validationType` is 'regex' this defines the regular expression to apply |
 | `confirmationRecipient` | `short`                               | Boolean          | `true/false`                                | Marks an email question as recipient for respondent confirmation emails      |
+| `requireEmailVerification` | `short`                            | Boolean          | `true/false`                                | Requires respondents to verify the confirmation-recipient email before the submission is treated as verified                    |
 | `allowedFileTypes`      | `file`                                | Array of strings | `'image', 'x-office/document'`              | Allowed file types for file upload                                          |
 | `allowedFileExtensions` | `file`                                | Array of strings | `'jpg', 'png'`                              | Allowed file extensions for file upload                                     |
 | `maxAllowedFilesCount`  | `file`                                | Integer          | -                                           | Maximum number of files that can be uploaded, 0 means no limit              |

lib/AppInfo/Application.php

@@ -15,6 +15,7 @@
 use OCA\Forms\FormsMigrator;
 use OCA\Forms\Listener\AnalyticsDatasourceListener;
 use OCA\Forms\Listener\ConfirmationEmailListener;
+use OCA\Forms\Listener\SubmissionVerificationListener;
 use OCA\Forms\Listener\UserDeletedListener;
 use OCA\Forms\Middleware\ThrottleFormAccessMiddleware;
 use OCA\Forms\Search\SearchProvider;
@@ -45,6 +46,7 @@ public function register(IRegistrationContext $context): void {
 
 		$context->registerCapability(Capabilities::class);
 		$context->registerEventListener(UserDeletedEvent::class, UserDeletedListener::class);
+		$context->registerEventListener(FormSubmittedEvent::class, SubmissionVerificationListener::class);
 		$context->registerEventListener(FormSubmittedEvent::class, ConfirmationEmailListener::class);
 		$context->registerEventListener(DatasourceEvent::class, AnalyticsDatasourceListener::class);
 		$context->registerMiddleware(ThrottleFormAccessMiddleware::class);

lib/Constants.php

@@ -150,6 +150,7 @@ class Constants {
 		'validationType' => ['string'],
 		'validationRegex' => ['string'],
 		'confirmationRecipient' => ['boolean'],
+		'requireEmailVerification' => ['boolean'],
 	];
 
 	public const EXTRA_SETTINGS_FILE = [

lib/Controller/ApiController.php

@@ -550,6 +550,9 @@ public function newQuestion(int $formId, ?string $type = null, ?string $subtype
 			if (is_array($questionData['extraSettings'] ?? null)
 				&& ($questionData['extraSettings']['confirmationRecipient'] ?? false) === true) {
 				$questionData['extraSettings']['confirmationRecipient'] = false;
+				if (($questionData['extraSettings']['requireEmailVerification'] ?? false) === true) {
+					$questionData['extraSettings']['requireEmailVerification'] = false;
+				}
 			}
 
 			$newQuestion = Question::fromParams($questionData);
@@ -1371,6 +1374,7 @@ public function newSubmission(int $formId, array $answers, string $shareHash = '
 		$submission = new Submission();
 		$submission->setFormId($formId);
 		$submission->setTimestamp(time());
+		$submission->setIsVerified(true);
 
 		// If not logged in, anonymous, or embedded use anonID
 		if (!$this->currentUser || $form->getIsAnonymous()) {

lib/Controller/PageController.php

@@ -14,6 +14,7 @@
 use OCA\Forms\Db\SubmissionMapper;
 use OCA\Forms\Service\ConfigService;
 use OCA\Forms\Service\FormsService;
+use OCA\Forms\Service\SubmissionVerificationService;
 
 use OCP\Accounts\IAccountManager;
 use OCP\AppFramework\Controller;
@@ -49,6 +50,7 @@ public function __construct(
 		private SubmissionMapper $submissionMapper,
 		private ConfigService $configService,
 		private FormsService $formsService,
+		private SubmissionVerificationService $submissionVerificationService,
 		private IAccountManager $accountManager,
 		private IInitialState $initialState,
 		private IL10N $l10n,
@@ -118,6 +120,27 @@ public function submitViewWithSubmission(string $hash, int $submissionId): Templ
 		return $this->formMapper->findByHash($hash)->getAllowEditSubmissions() ? $this->index($hash, $submissionId) : $this->index($hash);
 	}
 
+	#[NoAdminRequired()]
+	#[NoCSRFRequired()]
+	#[PublicPage()]
+	#[FrontpageRoute(verb: 'GET', url: '/verify/{token}', requirements: ['token' => '[a-f0-9]{48}'])]
+	public function verifySubmissionEmail(string $token): PublicTemplateResponse {
+		$isVerified = $this->submissionVerificationService->verifyToken($token);
+
+		$response = new PublicTemplateResponse($this->appName, 'verify', [
+			'verified' => $isVerified,
+			'headline' => $isVerified
+				? $this->l10n->t('Email address verified')
+				: $this->l10n->t('Email verification failed'),
+			'message' => $isVerified
+				? $this->l10n->t('Your email address has been verified successfully. You can close this page now.')
+				: $this->l10n->t('The verification link is invalid or expired.'),
+		]);
+		$response->setHeaderTitle($this->l10n->t('Forms'));
+
+		return $response;
+	}
+
 	/**
 	 * @param string $hash
 	 * @return RedirectResponse|TemplateResponse Redirect to login or internal view.

lib/Db/Submission.php

@@ -18,18 +18,22 @@
  * @method void setUserId(string $value)
  * @method int getTimestamp()
  * @method void setTimestamp(integer $value)
+ * @method bool getIsVerified()
+ * @method void setIsVerified(bool $value)
  */
 class Submission extends Entity {
 	protected $formId;
 	protected $userId;
 	protected $timestamp;
+	protected $isVerified;
 
 	/**
 	 * Submission constructor.
 	 */
 	public function __construct() {
 		$this->addType('formId', 'integer');
 		$this->addType('timestamp', 'integer');
+		$this->addType('isVerified', 'boolean');
 	}
 
 	/**
@@ -38,6 +42,7 @@ public function __construct() {
 	 *     formId: int,
 	 *     userId: string,
 	 *     timestamp: int,
+	 *     isVerified: bool,
 	 * }
 	 */
 	public function read(): array {
@@ -46,6 +51,7 @@ public function read(): array {
 			'formId' => $this->getFormId(),
 			'userId' => $this->getUserId(),
 			'timestamp' => $this->getTimestamp(),
+			'isVerified' => (bool)$this->getIsVerified(),
 		];
 	}
 }

lib/Db/SubmissionVerification.php

@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Forms\Db;
+
+use OCP\AppFramework\Db\Entity;
+
+/**
+ * @method int getSubmissionId()
+ * @method void setSubmissionId(int $value)
+ * @method string getRecipientEmailHash()
+ * @method void setRecipientEmailHash(string $value)
+ * @method string getTokenHash()
+ * @method void setTokenHash(string $value)
+ * @method int getExpires()
+ * @method void setExpires(int $value)
+ * @method int|null getUsed()
+ * @method void setUsed(?int $value)
+ */
+class SubmissionVerification extends Entity {
+	protected $submissionId;
+	protected $recipientEmailHash;
+	protected $tokenHash;
+	protected $expires;
+	protected $used;
+
+	public function __construct() {
+		$this->addType('submissionId', 'integer');
+		$this->addType('expires', 'integer');
+		$this->addType('used', 'integer');
+	}
+
+	/**
+	 * @return array{
+	 *   id: int,
+	 *   submissionId: int,
+	 *   recipientEmailHash: string,
+	 *   tokenHash: string,
+	 *   expires: int,
+	 *   used: int|null,
+	 * }
+	 */
+	public function read(): array {
+		return [
+			'id' => $this->getId(),
+			'submissionId' => $this->getSubmissionId(),
+			'recipientEmailHash' => $this->getRecipientEmailHash(),
+			'tokenHash' => $this->getTokenHash(),
+			'expires' => $this->getExpires(),
+			'used' => $this->getUsed(),
+		];
+	}
+}

lib/Db/SubmissionVerificationMapper.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Forms\Db;
+
+use OCP\AppFramework\Db\QBMapper;
+use OCP\DB\QueryBuilder\IQueryBuilder;
+use OCP\IDBConnection;
+
+/**
+ * @extends QBMapper<SubmissionVerification>
+ */
+class SubmissionVerificationMapper extends QBMapper {
+	public function __construct(IDBConnection $db) {
+		parent::__construct($db, 'forms_v2_submission_verify', SubmissionVerification::class);
+	}
+
+	/**
+	 * @throws \OCP\AppFramework\Db\DoesNotExistException
+	 * @throws \OCP\AppFramework\Db\MultipleObjectsReturnedException
+	 */
+	public function findBySubmissionId(int $submissionId): SubmissionVerification {
+		$qb = $this->db->getQueryBuilder();
+
+		$qb->select('*')
+			->from($this->getTableName())
+			->where(
+				$qb->expr()->eq('submission_id', $qb->createNamedParameter($submissionId, IQueryBuilder::PARAM_INT))
+			);
+
+		return $this->findEntity($qb);
+	}
+
+	/**
+	 * @throws \OCP\AppFramework\Db\DoesNotExistException
+	 * @throws \OCP\AppFramework\Db\MultipleObjectsReturnedException
+	 */
+	public function findByTokenHash(string $tokenHash): SubmissionVerification {
+		$qb = $this->db->getQueryBuilder();
+
+		$qb->select('*')
+			->from($this->getTableName())
+			->where(
+				$qb->expr()->eq('token_hash', $qb->createNamedParameter($tokenHash, IQueryBuilder::PARAM_STR))
+			);
+
+		return $this->findEntity($qb);
+	}
+}

lib/Events/FormSubmittedEvent.php

@@ -13,6 +13,7 @@
 class FormSubmittedEvent extends AbstractFormEvent {
 	public const TRIGGER_CREATED = 'created';
 	public const TRIGGER_UPDATED = 'updated';
+	public const TRIGGER_VERIFIED = 'verified';
 
 	public function __construct(
 		Form $form,