feat: add observer participant role for signature requests

appinfo/info.xml

@@ -27,7 +27,7 @@ If your organization uses LibreSign, support its development:
 For enterprise support, contact LibreCode:
 https://libresign.coop
 	]]></description>
-	<version>16.0.0-dev.1</version>
+	<version>16.0.0-dev.2</version>
 	<licence>agpl</licence>
 	<author mail="contact@librecode.coop" homepage="https://librecode.coop">LibreCode</author>
 	<types>

lib/Activity/Listener.php

@@ -222,12 +222,20 @@ protected function generateCanceledActivity(
 	 * @return array{type: 'file', id: string, name: string, path: string, link: string}
 	 */
 	protected function getFileParameter(SignRequest $signRequest, FileEntity $libreSignFile): array {
+		if ($signRequest->isObserver()) {
+			$link = $this->url->linkToRouteAbsolute('libresign.page.validationFilePublic', [
+				'uuid' => $libreSignFile->getUuid(),
+			]);
+		} else {
+			$link = $this->url->linkToRouteAbsolute('libresign.page.sign', ['uuid' => $signRequest->getUuid()]);
+		}
+
 		return [
 			'type' => 'file',
 			'id' => (string)$libreSignFile->getNodeId(),
 			'name' => $libreSignFile->getName(),
 			'path' => $libreSignFile->getName(),
-			'link' => $this->url->linkToRouteAbsolute('libresign.page.sign', ['uuid' => $signRequest->getUuid()]),
+			'link' => $link,
 		];
 	}
 

lib/Db/SignRequest.php

@@ -8,6 +8,7 @@
 
 namespace OCA\Libresign\Db;
 
+use OCA\Libresign\Enum\ParticipantRole;
 use OCA\Libresign\Enum\SignRequestStatus;
 use OCP\AppFramework\Db\Entity;
 use OCP\DB\Types;
@@ -37,6 +38,8 @@
  * @method int getSigningOrder()
  * @method void setStatus(int $status)
  * @method int getStatus()
+ * @method void setParticipantRole(string $participantRole)
+ * @method string getParticipantRole()
  */
 class SignRequest extends Entity {
 	protected ?int $fileId = null;
@@ -50,6 +53,7 @@ class SignRequest extends Entity {
 	protected int $docmdpLevel = 0;
 	protected int $signingOrder = 1;
 	protected int $status = 0;
+	protected string $participantRole = 'signer';
 
 	public function __construct() {
 		$this->addType('id', Types::INTEGER);
@@ -64,6 +68,19 @@ public function __construct() {
 		$this->addType('docmdpLevel', Types::SMALLINT);
 		$this->addType('signingOrder', Types::INTEGER);
 		$this->addType('status', Types::SMALLINT);
+		$this->addType('participantRole', Types::STRING);
+	}
+
+	public function getParticipantRoleEnum(): ParticipantRole {
+		return ParticipantRole::fromNullable($this->participantRole);
+	}
+
+	public function setParticipantRoleEnum(ParticipantRole $role): void {
+		$this->setParticipantRole($role->value);
+	}
+
+	public function isObserver(): bool {
+		return $this->getParticipantRoleEnum() === ParticipantRole::OBSERVER;
 	}
 
 	public function getStatusEnum(): SignRequestStatus {

lib/Enum/ParticipantRole.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Libresign\Enum;
+
+use OCP\IL10N;
+
+enum ParticipantRole: string {
+	case SIGNER = 'signer';
+	case OBSERVER = 'observer';
+
+	public function canSign(): bool {
+		return $this === self::SIGNER;
+	}
+
+	public function getLabel(IL10N $l10n): string {
+		return match ($this) {
+			// TRANSLATORS Participant role label for someone who must digitally sign the document.
+			self::SIGNER => $l10n->t('Signer'),
+			// TRANSLATORS Participant role label for someone who can only view the document and track progress.
+			self::OBSERVER => $l10n->t('Observer'),
+		};
+	}
+
+	/**
+	 * @throws \ValueError When $value is not empty and is not a known participant role
+	 */
+	public static function fromNullable(?string $value): self {
+		if ($value === null || $value === '') {
+			return self::SIGNER;
+		}
+
+		return self::from($value);
+	}
+}

lib/Enum/SignRequestStatus.php

@@ -15,6 +15,7 @@ enum SignRequestStatus: int {
 	case DRAFT = 0;
 	case ABLE_TO_SIGN = 1;
 	case SIGNED = 2;
+	case OBSERVING = 3;
 
 	public function getLabel(IL10N $l10n): string {
 		return match($this) {
@@ -24,6 +25,8 @@ public function getLabel(IL10N $l10n): string {
 			self::ABLE_TO_SIGN => $l10n->t('Ready to sign'),
 			// TRANSLATORS Signer workflow status shown after this signer has successfully signed the document.
 			self::SIGNED => $l10n->t('Signed'),
+			// TRANSLATORS Workflow status shown when an observer can view the document but cannot sign it.
+			self::OBSERVING => $l10n->t('Observing'),
 		};
 	}
 }

lib/Helper/ValidateHelper.php

@@ -21,13 +21,15 @@
 use OCA\Libresign\Db\SignRequestMapper;
 use OCA\Libresign\Db\UserElementMapper;
 use OCA\Libresign\Enum\FileStatus;
+use OCA\Libresign\Enum\ParticipantRole;
 use OCA\Libresign\Exception\LibresignException;
 use OCA\Libresign\Service\DocMdp\Validator as DocMdpValidator;
 use OCA\Libresign\Service\FileService;
 use OCA\Libresign\Service\IdDocsPolicyService;
 use OCA\Libresign\Service\IdentifyMethod\IIdentifyMethod;
 use OCA\Libresign\Service\IdentifyMethod\RuntimeRequirementValidator;
 use OCA\Libresign\Service\IdentifyMethodService;
+use OCA\Libresign\Service\Policy\Provider\ObserverProfile\ObserverProfilePolicyService;
 use OCA\Libresign\Service\Policy\RequestSignAuthorizationService;
 use OCA\Libresign\Service\SequentialSigningService;
 use OCA\Libresign\Service\SignerElementsService;
@@ -71,6 +73,7 @@ public function __construct(
 		private DocMdpValidator $docMdpValidator,
 		private RequestSignAuthorizationService $requestSignAuthorizationService,
 		private RuntimeRequirementValidator $runtimeRequirementValidator,
+		private ObserverProfilePolicyService $observerProfilePolicyService,
 	) {
 	}
 
@@ -607,29 +610,88 @@ public function validateIdentifySigners(array $data): void {
 		}
 
 		$this->validateSignersDataStructure($data);
+		$this->validateSigningParticipantsRequired($data);
 		$this->docMdpValidator->validateSignersCount($data);
 		$this->validateDocMdpPdfRestrictions($data);
 
 		foreach ($data['signers'] as $signer) {
-			$this->validateSignerData($signer);
+			$this->validateSignerData($signer, $data);
 		}
 	}
 
+	private function validateSigningParticipantsRequired(array $data): void {
+		if (($data['status'] ?? FileStatus::DRAFT->value) === FileStatus::DRAFT->value) {
+			return;
+		}
+
+		if (!is_array($data['signers'])) {
+			return;
+		}
+
+		foreach ($data['signers'] as $signer) {
+			if (!is_array($signer)) {
+				continue;
+			}
+
+			$role = ParticipantRole::fromNullable($signer['participantRole'] ?? null);
+			if ($role->canSign()) {
+				return;
+			}
+		}
+
+		// TRANSLATORS Validation error when requesting signatures without any signing participants.
+		throw new LibresignException($this->l10n->t('At least one signer is required'));
+	}
+
 	private function validateSignersDataStructure(array $data): void {
 		if (empty($data) || !array_key_exists('signers', $data) || !is_array($data['signers']) || empty($data['signers'])) {
 			// TRANSLATORS Validation error when a signature request is submitted without any signers.
 			throw new LibresignException($this->l10n->t('No signers'));
 		}
 	}
 
-	private function validateSignerData(mixed $signer): void {
+	private function validateSignerData(mixed $signer, array $data): void {
 		if (!is_array($signer) || empty($signer)) {
 			// TRANSLATORS Validation error when a signature request is submitted without any signers.
 			throw new LibresignException($this->l10n->t('No signers'));
 		}
 
 		$this->validateSignerDisplayName($signer);
 		$this->validateSignerIdentifyMethods($signer);
+		$this->validateParticipantRole($signer, $data);
+	}
+
+	private function validateParticipantRole(array $signer, array $data): void {
+		$roleValue = $signer['participantRole'] ?? ParticipantRole::SIGNER->value;
+		if (!is_string($roleValue)) {
+			throw new LibresignException('Invalid participant role');
+		}
+
+		try {
+			$role = ParticipantRole::from($roleValue);
+		} catch (\ValueError) {
+			throw new LibresignException('Invalid participant role');
+		}
+
+		if ($role === ParticipantRole::OBSERVER
+			&& !$this->observerProfilePolicyService->isEnabled($this->getExistingRequestFile($data))
+		) {
+			// TRANSLATORS Validation error when observer participants are submitted while the feature is disabled by policy.
+			throw new LibresignException($this->l10n->t('Observer participants are not enabled'));
+		}
+	}
+
+	private function getExistingRequestFile(array $data): ?File {
+		$uuid = $data['uuid'] ?? null;
+		if (!is_string($uuid) || $uuid === '') {
+			return null;
+		}
+
+		try {
+			return $this->fileMapper->getByUuid($uuid);
+		} catch (DoesNotExistException) {
+			return null;
+		}
 	}
 
 	private function validateSignerDisplayName(array $signer): void {
@@ -788,6 +850,15 @@ public function validateSignerUuid(string $uuid): void {
 	 */
 	private function validateSignerStatus(string $uuid): void {
 		$signRequest = $this->signRequestMapper->getByUuid($uuid);
+
+		if (!$signRequest->getParticipantRoleEnum()->canSign()) {
+			throw new LibresignException(json_encode([
+				'action' => JSActions::ACTION_DO_NOTHING,
+				// TRANSLATORS Validation error when an observer tries to sign a document.
+				'errors' => [['message' => $this->l10n->t('Observers cannot sign this document')]],
+			]));
+		}
+
 		$status = $signRequest->getStatusEnum();
 
 		$file = $this->fileMapper->getById($signRequest->getFileId());

lib/Listener/NotificationListener.php

@@ -213,12 +213,20 @@ private function sendCanceledNotification(
 	 * @psalm-return array{type: 'file', id: string, name: string, path: string, link: string}
 	 */
 	protected function getFileParameter(SignRequest $signRequest, FileEntity $libreSignFile): array {
+		if ($signRequest->isObserver()) {
+			$link = $this->url->linkToRouteAbsolute('libresign.page.validationFilePublic', [
+				'uuid' => $libreSignFile->getUuid(),
+			]);
+		} else {
+			$link = $this->url->linkToRouteAbsolute('libresign.page.signFPath', ['uuid' => $signRequest->getUuid(), 'path' => 'pdf']);
+		}
+
 		return [
 			'type' => 'file',
 			'id' => (string)$libreSignFile->getNodeId(),
 			'name' => $libreSignFile->getName(),
 			'path' => $libreSignFile->getName(),
-			'link' => $this->url->linkToRouteAbsolute('libresign.page.signFPath', ['uuid' => $signRequest->getUuid(), 'path' => 'pdf']),
+			'link' => $link,
 		];
 	}
 

lib/Middleware/InjectionMiddleware.php

@@ -340,7 +340,7 @@ private function redirectSignedToValidationIfNeeded(RequireSignRequestUuid $requ
 
 		try {
 			$signRequest = $this->signRequestMapper->getByUuid($uuid);
-			if ($signRequest->getStatusEnum() !== SignRequestStatus::SIGNED) {
+			if ($signRequest->getStatusEnum() !== SignRequestStatus::SIGNED && !$signRequest->isObserver()) {
 				return;
 			}
 			$file = $this->fileMapper->getById($signRequest->getFileId());

lib/Migration/Version19000Date20260830200000.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Libresign\Migration;
+
+use Closure;
+use OCP\DB\ISchemaWrapper;
+use OCP\DB\Types;
+use OCP\Migration\IOutput;
+use OCP\Migration\SimpleMigrationStep;
+
+class Version19000Date20260830200000 extends SimpleMigrationStep {
+	/**
+	 * @param Closure(): ISchemaWrapper $schemaClosure
+	 */
+	#[\Override]
+	public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper {
+		/** @var ISchemaWrapper $schema */
+		$schema = $schemaClosure();
+
+		if (!$schema->hasTable('libresign_sign_request')) {
+			return null;
+		}
+
+		$table = $schema->getTable('libresign_sign_request');
+		if ($table->hasColumn('participant_role')) {
+			return null;
+		}
+
+		$table->addColumn('participant_role', Types::STRING, [
+			'notnull' => true,
+			'length' => 32,
+			'default' => 'signer',
+		]);
+
+		return $schema;
+	}
+}

lib/ResponseDefinitions.php

@@ -47,6 +47,7 @@
  *     },
  *     envelopeFolderId?: int,
  * }
+ * @psalm-type LibresignParticipantRole = 'signer'|'observer'
  * @psalm-type LibresignGeolocationCollectionStatus = 'collected'|'denied'|'unavailable'|'skipped'
  * @psalm-type LibresignSignerGeolocationPolicyMode = 'disabled'|'optional'|'required'
  * @psalm-type LibresignGeolocationRequirement = 'disabled'|'required'
@@ -68,6 +69,7 @@
  *     notify?: non-negative-int,
  *     signingOrder?: non-negative-int,
  *     status?: int,
+ *     participantRole?: LibresignParticipantRole,
  *     geolocationRequired?: bool,
  * }
  * @psalm-type LibresignNewFile = array{
@@ -206,8 +208,9 @@
  *     email?: ?string,
  *     identifyMethods?: LibresignIdentifyMethod[],
  *     signed: ?string,
- *     status: 0|1|2,
+ *     status: 0|1|2|3,
  *     statusText: string,
+ *     participantRole?: LibresignParticipantRole,
  * }
  * @psalm-type LibresignSignerDetail = LibresignSignerSummary&array{
  *     description: ?string,
@@ -505,6 +508,10 @@
  *     effectiveValue: int,
  *     sourceScope: string,
  * }
+ * @psalm-type LibresignPolicySnapshotBooleanEntry = array{
+ *     effectiveValue: bool,
+ *     sourceScope: string,
+ * }
  * @psalm-type LibresignPolicySnapshotIdentificationDocumentsValue = array{
  *     enabled: bool,
  *     approvers: list<string>,
@@ -541,6 +548,7 @@
  *     identification_documents?: LibresignPolicySnapshotIdentificationDocumentsEntry,
  *     identify_methods?: LibresignPolicySnapshotIdentifyMethodsEntry,
  *     signer_geolocation?: LibresignPolicySnapshotSignerGeolocationEntry,
+ *     enable_observer_profile?: LibresignPolicySnapshotBooleanEntry,
  * }
  * @psalm-type LibresignValidateMetadata = array{
  *     extension: string,