Merge pull request #6071 from LibreSign/backport/6069/stable32

[stable32] feat: sequential signing

Author: vitormattos

lib/Controller/AdminController.php

@@ -895,6 +895,47 @@ public function footerTemplatePreviewPdf(string $template = '', int $width = 595
 		}
 	}
 
+	/**
+	 * Set signature flow configuration
+	 *
+	 * @param string $mode Signature flow mode: 'parallel' or 'ordered_numeric'
+	 * @return DataResponse<Http::STATUS_OK, array{message: string}, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR, array{error: string}, array{}>
+	 *
+	 * 200: Configuration saved successfully
+	 * 400: Invalid signature flow mode provided
+	 * 500: Internal server error
+	 */
+	#[ApiRoute(verb: 'POST', url: '/api/{apiVersion}/admin/signature-flow/config', requirements: ['apiVersion' => '(v1)'])]
+	public function setSignatureFlowConfig(string $mode): DataResponse {
+		try {
+			$signatureFlow = \OCA\Libresign\Service\SignatureFlow::from($mode);
+		} catch (\ValueError) {
+			return new DataResponse([
+				'error' => $this->l10n->t('Invalid signature flow mode. Use "parallel" or "ordered_numeric".'),
+			], Http::STATUS_BAD_REQUEST);
+		}
+
+		try {
+			if ($signatureFlow === \OCA\Libresign\Service\SignatureFlow::PARALLEL) {
+				$this->appConfig->deleteKey(Application::APP_ID, 'signature_flow');
+			} else {
+				$this->appConfig->setValueString(
+					Application::APP_ID,
+					'signature_flow',
+					$signatureFlow->value
+				);
+			}
+
+			return new DataResponse([
+				'message' => $this->l10n->t('Settings saved'),
+			]);
+		} catch (\Exception $e) {
+			return new DataResponse([
+				'error' => $e->getMessage(),
+			], Http::STATUS_INTERNAL_SERVER_ERROR);
+		}
+	}
+
 	/**
 	 * Set DocMDP configuration
 	 *

lib/Controller/PageController.php

@@ -95,6 +95,7 @@ public function index(): TemplateResponse {
 
 		$this->provideSignerSignatues();
 		$this->initialState->provideInitialState('identify_methods', $this->identifyMethodService->getIdentifyMethodsSettings());
+		$this->initialState->provideInitialState('signature_flow', $this->appConfig->getValueString(Application::APP_ID, 'signature_flow', \OCA\Libresign\Service\SignatureFlow::PARALLEL->value));
 		$this->initialState->provideInitialState('legal_information', $this->appConfig->getValueString(Application::APP_ID, 'legal_information'));
 
 		Util::addScript(Application::APP_ID, 'libresign-main');

lib/Controller/RequestSignatureController.php

@@ -47,10 +47,12 @@ public function __construct(
 	/**
 	 * Request signature
 	 *
-	 * Request that a file be signed by a group of people
+	 * Request that a file be signed by a group of people.
+	 * Each user in the users array can optionally include a 'signing_order' field
+	 * to control the order of signatures when ordered signing flow is enabled.
 	 *
 	 * @param LibresignNewFile $file File object.
-	 * @param LibresignNewSigner[] $users Collection of users who must sign the document
+	 * @param LibresignNewSigner[] $users Collection of users who must sign the document. Each user can have: identify, displayName, description, notify, signing_order
 	 * @param string $name The name of file to sign
 	 * @param string|null $callback URL that will receive a POST after the document is signed
 	 * @param integer|null $status Numeric code of status * 0 - no signers * 1 - signed * 2 - pending

lib/Db/SignRequest.php

@@ -32,6 +32,10 @@
  * @method ?array getMetadata()
  * @method void setDocmdpLevel(int $docmdpLevel)
  * @method int getDocmdpLevel()
+ * @method void setSigningOrder(int $signingOrder)
+ * @method int getSigningOrder()
+ * @method void setStatus(int $status)
+ * @method int getStatus()
  */
 class SignRequest extends Entity {
 	protected ?int $fileId = null;
@@ -43,6 +47,9 @@ class SignRequest extends Entity {
 	protected ?string $signedHash = null;
 	protected ?array $metadata = null;
 	protected int $docmdpLevel = 0;
+	protected int $signingOrder = 1;
+	protected int $status = 0;
+
 	public function __construct() {
 		$this->addType('id', Types::INTEGER);
 		$this->addType('fileId', Types::INTEGER);
@@ -54,5 +61,15 @@ public function __construct() {
 		$this->addType('signedHash', Types::STRING);
 		$this->addType('metadata', Types::JSON);
 		$this->addType('docmdpLevel', Types::SMALLINT);
+		$this->addType('signingOrder', Types::INTEGER);
+		$this->addType('status', Types::SMALLINT);
+	}
+
+	public function getStatusEnum(): SignRequestStatus {
+		return SignRequestStatus::from($this->status);
+	}
+
+	public function setStatusEnum(SignRequestStatus $status): void {
+		$this->setStatus($status->value);
 	}
 }

lib/Db/SignRequestStatus.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2025 LibreCode coop and contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Libresign\Db;
+
+enum SignRequestStatus: int {
+	case DRAFT = 0;
+	case ABLE_TO_SIGN = 1;
+	case SIGNED = 2;
+}

lib/Files/TemplateLoader.php

@@ -9,6 +9,7 @@
 namespace OCA\Libresign\Files;
 
 use OCA\Files\Event\LoadSidebar;
+use OCA\Libresign\AppInfo\Application;
 use OCA\Libresign\Exception\LibresignException;
 use OCA\Libresign\Handler\CertificateEngine\CertificateEngineFactory;
 use OCA\Libresign\Helper\ValidateHelper;
@@ -18,6 +19,7 @@
 use OCP\EventDispatcher\Event;
 use OCP\EventDispatcher\IEventDispatcher;
 use OCP\EventDispatcher\IEventListener;
+use OCP\IAppConfig;
 use OCP\IRequest;
 use OCP\IUserSession;
 
@@ -33,6 +35,7 @@ public function __construct(
 		private ValidateHelper $validateHelper,
 		private IdentifyMethodService $identifyMethodService,
 		private CertificateEngineFactory $certificateEngineFactory,
+		private IAppConfig $appConfig,
 	) {
 	}
 
@@ -54,6 +57,11 @@ public function handle(Event $event): void {
 			$this->identifyMethodService->getIdentifyMethodsSettings()
 		);
 
+		$this->initialState->provideInitialState(
+			'signature_flow',
+			$this->appConfig->getValueString(Application::APP_ID, 'signature_flow', \OCA\Libresign\Service\SignatureFlow::PARALLEL->value)
+		);
+
 		try {
 			$this->validateHelper->canRequestSign($this->userSession->getUser());
 			$this->initialState->provideInitialState('can_request_sign', true);

lib/Helper/ValidateHelper.php

@@ -709,9 +709,32 @@ public function validateFileUuid(array $data): void {
 
 	public function validateSigner(string $uuid, ?IUser $user = null): void {
 		$this->validateSignerUuidExists($uuid);
+		$this->validateSignerStatus($uuid);
 		$this->validateIdentifyMethod($uuid, $user);
 	}
 
+	/**
+	 * @throws LibresignException
+	 */
+	private function validateSignerStatus(string $uuid): void {
+		$signRequest = $this->signRequestMapper->getByUuid($uuid);
+		$status = $signRequest->getStatusEnum();
+
+		if ($status === \OCA\Libresign\Db\SignRequestStatus::DRAFT) {
+			throw new LibresignException(json_encode([
+				'action' => JSActions::ACTION_DO_NOTHING,
+				'errors' => [['message' => $this->l10n->t('You are not allowed to sign this document yet')]],
+			]));
+		}
+
+		if ($status === \OCA\Libresign\Db\SignRequestStatus::SIGNED) {
+			throw new LibresignException(json_encode([
+				'action' => JSActions::ACTION_DO_NOTHING,
+				'errors' => [['message' => $this->l10n->t('Document already signed')]],
+			]));
+		}
+	}
+
 	public function validateRenewSigner(string $uuid, ?IUser $user = null): void {
 		$this->validateSignerUuidExists($uuid);
 		$signRequest = $this->signRequestMapper->getByUuid($uuid);

lib/Migration/Version15000Date20251209000000.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2025 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;
+
+/**
+ * Add sequential signing support
+ * - Adds 'signing_order', 'status', and 'released_at' columns to libresign_sign_request table
+ */
+class Version15000Date20251209000000 extends SimpleMigrationStep {
+	/**
+	 * @param IOutput $output
+	 * @param Closure(): ISchemaWrapper $schemaClosure
+	 * @param array $options
+	 * @return null|ISchemaWrapper
+	 */
+	#[\Override]
+	public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper {
+		/** @var ISchemaWrapper $schema */
+		$schema = $schemaClosure();
+
+		// Add signing order, status, and released_at to SignRequest table
+		if ($schema->hasTable('libresign_sign_request')) {
+			$tableSignRequest = $schema->getTable('libresign_sign_request');
+			if (!$tableSignRequest->hasColumn('signing_order')) {
+				$tableSignRequest->addColumn('signing_order', Types::INTEGER, [
+					'notnull' => true,
+					'default' => 1,
+					'comment' => 'Numeric order/stage for sequential signing (e.g., 1, 2, 3)',
+				]);
+			}
+			if (!$tableSignRequest->hasColumn('status')) {
+				$tableSignRequest->addColumn('status', Types::SMALLINT, [
+					'notnull' => true,
+					'default' => 0,
+					'comment' => 'Status: 0=draft, 1=able_to_sign, 2=signed',
+				]);
+			}
+		}
+
+		return $schema;
+	}
+}

lib/ResponseDefinitions.php

@@ -28,6 +28,7 @@
  *         email?: string,
  *         account?: string,
  *     },
+ *     signingOrder?: non-negative-int,
  * }
  * @psalm-type LibresignNewFile = array{
  *     base64?: string,
@@ -172,6 +173,7 @@
  *     hash_algorithm?: string,
  *     me: bool,
  *     signRequestId: non-negative-int,
+ *     signingOrder?: non-negative-int,
  *     identifyMethods?: LibresignIdentifyMethod[],
  *     visibleElements?: LibresignVisibleElement[],
  *     signatureMethods?: LibresignSignatureMethods,

lib/Service/FileService.php

@@ -387,6 +387,7 @@ private function loadLibreSignSigners(): void {
 			$this->fileData->signers[$index]['me'] = false;
 			$this->fileData->signers[$index]['signRequestId'] = $signer->getId();
 			$this->fileData->signers[$index]['description'] = $signer->getDescription();
+			$this->fileData->signers[$index]['signingOrder'] = $signer->getSigningOrder();
 			$this->fileData->signers[$index]['visibleElements'] = $this->getVisibleElements($signer->getId());
 			$this->fileData->signers[$index]['request_sign_date'] = $signer->getCreatedAt()->format(DateTimeInterface::ATOM);
 			if (empty($this->fileData->signers[$index]['signed'])) {
@@ -468,6 +469,18 @@ private function loadLibreSignSigners(): void {
 			}, []);
 			ksort($this->fileData->signers[$index]);
 		}
+
+		usort($this->fileData->signers, function ($a, $b) {
+			$orderA = $a['signingOrder'] ?? PHP_INT_MAX;
+			$orderB = $b['signingOrder'] ?? PHP_INT_MAX;
+
+			if ($orderA !== $orderB) {
+				return $orderA <=> $orderB;
+			}
+
+			return ($a['signRequestId'] ?? 0) <=> ($b['signRequestId'] ?? 0);
+		});
+
 		$this->signersLibreSignLoaded = true;
 	}
 
@@ -821,6 +834,7 @@ private function associateAllAndFormat(IUser $user, array $files, array $signers
 						'request_sign_date' => $signer->getCreatedAt()->format(DateTimeInterface::ATOM),
 						'signed' => null,
 						'signRequestId' => $signer->getId(),
+						'signingOrder' => $signer->getSigningOrder(),
 						'me' => array_reduce($identifyMethodsOfSigner, function (bool $carry, IdentifyMethod $identifyMethod) use ($user): bool {
 							if ($identifyMethod->getIdentifierKey() === IdentifyMethodService::IDENTIFY_ACCOUNT) {
 								if ($user->getUID() === $identifyMethod->getIdentifierValue()) {
@@ -888,6 +902,17 @@ private function associateAllAndFormat(IUser $user, array $files, array $signers
 				$files[$key]['signers'] = [];
 				$files[$key]['statusText'] = $this->l10n->t('no signers');
 			} else {
+				usort($files[$key]['signers'], function ($a, $b) {
+					$orderA = $a['signingOrder'] ?? PHP_INT_MAX;
+					$orderB = $b['signingOrder'] ?? PHP_INT_MAX;
+
+					if ($orderA !== $orderB) {
+						return $orderA <=> $orderB;
+					}
+
+					return ($a['signRequestId'] ?? 0) <=> ($b['signRequestId'] ?? 0);
+				});
+
 				$files[$key]['statusText'] = $this->fileMapper->getTextOfStatus((int)$files[$key]['status']);
 			}
 			unset($files[$key]['id']);