Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
1650c77
feat: expose signer and workflow transitions as native webhooks
vitormattos Nov 9, 2026
75a368c
feat: publish persisted notification channel outcomes via webhook
vitormattos Nov 9, 2026
2b7705b
test: verify notification outcome event follows persisted submission
vitormattos Nov 9, 2026
f95997c
refactor: isolate persisted notification webhook publishing
vitormattos Nov 9, 2026
569f720
fix: publish ready workflow events after signer persistence
vitormattos Nov 9, 2026
1dd4f1d
refactor: narrow rejection error handling and isolate event failures
vitormattos Nov 9, 2026
1f04265
test: verify notification outcomes through persisted ledger
vitormattos Nov 10, 2026
2a14994
test: keep notification workflow fixture UUID within SQL schema
vitormattos Nov 10, 2026
0db6c0e
fix: isolate native signed events from legacy listener failures
vitormattos Nov 10, 2026
ff9311f
refactor: publish ready events after atomic signer persistence
vitormattos Nov 10, 2026
bee9ff8
test: verify committed notification outcomes and preserve signed even…
vitormattos Nov 10, 2026
8d968b0
fix: sanitize unexpected rejection errors in public API
vitormattos Nov 10, 2026
2c42406
fix: isolate native webhook listener failures from committed workflows
vitormattos Nov 10, 2026
2dcc2e9
refactor: centralize native webhook publishing and simplify lifecycle…
vitormattos Nov 11, 2026
f7f997b
refactor: narrow webhook preparation failures and reuse committed roo…
vitormattos Nov 11, 2026
a25288b
refactor: clarify webhook publication boundaries and observable tests
vitormattos Nov 11, 2026
74ac021
refactor: decouple signature rejection rules, persistence and notific…
vitormattos Nov 11, 2026
a481992
refactor: remove redundant rejection listener comment
vitormattos Nov 11, 2026
0df9b43
fix: address native webhook lifecycle review regressions
vitormattos Nov 11, 2026
b77f330
fix: keep ready transition metadata out of public responses
vitormattos Nov 11, 2026
449b65b
fix: clean up failed request storage and improve rejection diagnostics
vitormattos Nov 11, 2026
e58986d
test: align new request mocks with file lookup contract
vitormattos Nov 11, 2026
7bb6149
style: normalize PHPUnit test spacing
vitormattos Nov 11, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion lib/Controller/SignFileController.php
Original file line number Diff line number Diff line change
Expand Up @@ -386,9 +386,20 @@ private function reject(
$comment,
$privateComment,
);
} catch (LibresignException $e) {
return new DataResponse(
['message' => $e->getMessage()],
Http::STATUS_UNPROCESSABLE_ENTITY,
);
} catch (\Throwable $th) {
$this->logger->error('Unable to process signature rejection', [
'errorType' => get_debug_type($th),
'errorFile' => $th->getFile(),
'errorLine' => $th->getLine(),
]);
return new DataResponse(
['message' => $th->getMessage()],
// TRANSLATORS Error shown when a signature rejection fails unexpectedly.
['message' => $this->l10n->t('Unable to process signature rejection.')],
Http::STATUS_UNPROCESSABLE_ENTITY,
);
}
Expand Down
13 changes: 13 additions & 0 deletions lib/Db/FileMapper.php
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,19 @@ public function update(Entity $entity): File {
return parent::update($entity);
}

#[\Override]
public function invalidateCachedEntity(Entity $entity): void {
parent::invalidateCachedEntity($entity);
if ($entity instanceof File) {
if ($entity->getNodeId() !== null) {
$this->cacheRemove('node_id:' . $entity->getNodeId());
}
if ($entity->getUuid() !== '') {
$this->cacheRemove('uuid:' . $entity->getUuid());
}
}
}

#[\Override]
protected function cacheEntity(Entity $entity): void {
parent::cacheEntity($entity);
Expand Down
65 changes: 65 additions & 0 deletions lib/Events/NotificationDeliveryStatusChangedEvent.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
<?php

declare(strict_types=1);
/**
* SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
* SPDX-License-Identifier: AGPL-3.0-or-later
*/

namespace OCA\Libresign\Events;

use OCA\Libresign\Db\File as FileEntity;
use OCA\Libresign\Db\NotificationDelivery;
use OCA\Libresign\Enum\NotificationDeliveryState;
use OCP\EventDispatcher\Event;
use OCP\EventDispatcher\IWebhookCompatibleEvent;

/** Result of one persisted channel-submission attempt, NOT recipient delivery. */
final class NotificationDeliveryStatusChangedEvent extends Event implements IWebhookCompatibleEvent {
public const CONTRACT_VERSION = 1;

private function __construct(
private readonly string $requestUuid,
private readonly string $requestType,
private readonly int $deliveryId,
private readonly string $channel,
private readonly string $state,
private readonly int $attempt,
private readonly string $eventId,
) {
parent::__construct();
}

public static function fromPersistedDelivery(FileEntity $root, NotificationDelivery $delivery): ?self {
$state = NotificationDeliveryState::tryFrom($delivery->getState());
if ($root->getUuid() === '' || $delivery->getId() === null || $delivery->getAttemptCount() < 1
|| $state === null
|| in_array($state, [NotificationDeliveryState::PENDING, NotificationDeliveryState::SENDING], true)) {
return null;
}

return new self(
$root->getUuid(),
$root->isEnvelope() ? 'envelope' : 'document',
$delivery->getId(),
$delivery->getChannel(),
$state->value,
$delivery->getAttemptCount(),
'libresign.notification.delivery.v1:' . $delivery->getId() . ':' . $delivery->getAttemptCount() . ':' . $state->value,
);
}

#[\Override]
public function getWebhookSerializable(): array {
return [
'contractVersion' => self::CONTRACT_VERSION,
'eventId' => $this->eventId,
'requestUuid' => $this->requestUuid,
'requestType' => $this->requestType,
'deliveryId' => $this->deliveryId,
'channel' => $this->channel,
'state' => $this->state,
'attempt' => $this->attempt,
];
}
}
64 changes: 64 additions & 0 deletions lib/Events/SignerRejectedWebhookEvent.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
<?php

declare(strict_types=1);
/**
* SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
* SPDX-License-Identifier: AGPL-3.0-or-later
*/

namespace OCA\Libresign\Events;

use OCA\Libresign\Db\File as FileEntity;
use OCA\Libresign\Db\SignRequest;
use OCA\Libresign\Enum\SignRequestStatus;
use OCP\EventDispatcher\Event;
use OCP\EventDispatcher\IWebhookCompatibleEvent;

/** One committed business rejection, independent of identification-method count. */
final class SignerRejectedWebhookEvent extends Event implements IWebhookCompatibleEvent {
public const CONTRACT_VERSION = 1;

private function __construct(
private readonly string $requestUuid,
private readonly string $requestType,
private readonly string $documentUuid,
private readonly int $signerId,
private readonly bool $workflowCanceled,
private readonly string $eventId,
) {
parent::__construct();
}

public static function afterRejection(FileEntity $root, FileEntity $document, SignRequest $signer, bool $workflowCanceled): ?self {
if ($root->getUuid() === '' || $document->getUuid() === ''
|| $signer->getId() === null
|| $signer->getStatusEnum() !== SignRequestStatus::REJECTED
|| $signer->getRejectedAt() === null) {
return null;
}

$identity = implode(':', [$root->getUuid(), $document->getUuid(), $signer->getId(), $signer->getRejectedAt()->format('U.u')]);
return new self(
$root->getUuid(),
$root->isEnvelope() ? 'envelope' : 'document',
$document->getUuid(),
$signer->getId(),
$workflowCanceled,
'libresign.signer.rejected.v1:' . hash('sha256', $identity),
);
}

#[\Override]
public function getWebhookSerializable(): array {
return [
'contractVersion' => self::CONTRACT_VERSION,
'eventId' => $this->eventId,
'requestUuid' => $this->requestUuid,
'requestType' => $this->requestType,
'documentUuid' => $this->documentUuid,
'signerId' => $this->signerId,
'status' => 'rejected',
'workflowCanceled' => $this->workflowCanceled,
];
}
}
62 changes: 62 additions & 0 deletions lib/Events/SignerSignedWebhookEvent.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
<?php

declare(strict_types=1);
/**
* SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
* SPDX-License-Identifier: AGPL-3.0-or-later
*/

namespace OCA\Libresign\Events;

use OCA\Libresign\Db\File as FileEntity;
use OCA\Libresign\Db\SignRequest;
use OCP\EventDispatcher\Event;
use OCP\EventDispatcher\IWebhookCompatibleEvent;

/**
* An individual document-level signer action, including envelope children.
* The secret signing invitation UUID is never exposed.
*/
final class SignerSignedWebhookEvent extends Event implements IWebhookCompatibleEvent {
public const CONTRACT_VERSION = 1;

private function __construct(
private readonly string $requestUuid,
private readonly string $requestType,
private readonly string $documentUuid,
private readonly int $signerId,
private readonly string $eventId,
) {
parent::__construct();
}

public static function afterSigning(FileEntity $root, FileEntity $document, SignRequest $signer): ?self {
if ($root->getUuid() === '' || $document->getUuid() === ''
|| $signer->getId() === null || $signer->getSigned() === null
|| !is_string($signer->getSignedHash()) || $signer->getSignedHash() === '') {
return null;
}

$identity = implode(':', [$root->getUuid(), $document->getUuid(), $signer->getId(), $signer->getSignedHash()]);
return new self(
$root->getUuid(),
$root->isEnvelope() ? 'envelope' : 'document',
$document->getUuid(),
$signer->getId(),
'libresign.signer.signed.v1:' . hash('sha256', $identity),
);
}

#[\Override]
public function getWebhookSerializable(): array {
return [
'contractVersion' => self::CONTRACT_VERSION,
'eventId' => $this->eventId,
'requestUuid' => $this->requestUuid,
'requestType' => $this->requestType,
'documentUuid' => $this->documentUuid,
'signerId' => $this->signerId,
'status' => 'signed',
];
}
}
48 changes: 48 additions & 0 deletions lib/Events/SigningRequestCanceledEvent.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
<?php

declare(strict_types=1);
/**
* SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
* SPDX-License-Identifier: AGPL-3.0-or-later
*/

namespace OCA\Libresign\Events;

use OCA\Libresign\Db\File as FileEntity;
use OCA\Libresign\Enum\FileStatus;
use OCP\EventDispatcher\Event;
use OCP\EventDispatcher\IWebhookCompatibleEvent;

/** Aggregate workflow cancellation; unrelated to signer-removal notices. */
final class SigningRequestCanceledEvent extends Event implements IWebhookCompatibleEvent {
public const CONTRACT_VERSION = 1;

private function __construct(
private readonly string $requestUuid,
private readonly string $requestType,
) {
parent::__construct();
}

public static function fromTransition(FileEntity $file, int $previousStatus): ?self {
if ($file->hasParent()
|| $previousStatus === FileStatus::CANCELED->value
|| $file->getStatus() !== FileStatus::CANCELED->value
|| $file->getUuid() === '') {
return null;
}

return new self($file->getUuid(), $file->isEnvelope() ? 'envelope' : 'document');
}

#[\Override]
public function getWebhookSerializable(): array {
return [
'contractVersion' => self::CONTRACT_VERSION,
'eventId' => 'libresign.workflow.canceled.v1:' . $this->requestUuid,
'requestUuid' => $this->requestUuid,
'requestType' => $this->requestType,
'status' => 'canceled',
];
}
}
55 changes: 55 additions & 0 deletions lib/Events/SigningRequestReadyEvent.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
<?php

declare(strict_types=1);
/**
* SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
* SPDX-License-Identifier: AGPL-3.0-or-later
*/

namespace OCA\Libresign\Events;

use OCA\Libresign\Db\File as FileEntity;
use OCA\Libresign\Enum\FileStatus;
use OCA\Libresign\Service\FileStatusService;
use OCP\EventDispatcher\Event;
use OCP\EventDispatcher\IWebhookCompatibleEvent;

/** Public event for a workflow transitioning from draft to ready to sign. */
final class SigningRequestReadyEvent extends Event implements IWebhookCompatibleEvent {
public const CONTRACT_VERSION = 1;

private function __construct(
private readonly string $requestUuid,
private readonly string $requestType,
private readonly string $eventId,
) {
parent::__construct();
}

public static function fromTransition(FileEntity $file, int $previousStatus): ?self {
if ($file->hasParent()
|| $previousStatus !== FileStatus::DRAFT->value
|| $file->getStatus() !== FileStatus::ABLE_TO_SIGN->value
|| $file->getUuid() === '') {
return null;
}

$transitionId = ($file->getMetadata() ?? [])[FileStatusService::READY_EVENT_ID_METADATA_KEY] ?? null;
$eventId = 'libresign.workflow.ready.v1:' . $file->getUuid();
if (is_string($transitionId) && $transitionId !== '') {
$eventId .= ':' . $transitionId;
}
return new self($file->getUuid(), $file->isEnvelope() ? 'envelope' : 'document', $eventId);
}

#[\Override]
public function getWebhookSerializable(): array {
return [
'contractVersion' => self::CONTRACT_VERSION,
'eventId' => $this->eventId,
'requestUuid' => $this->requestUuid,
'requestType' => $this->requestType,
'status' => 'ready_to_sign',
];
}
}
15 changes: 11 additions & 4 deletions lib/Service/File/FileListService.php
Original file line number Diff line number Diff line change
Expand Up @@ -262,7 +262,7 @@ private function formatSingleFileData(
'uuid' => $fileEntity->getUuid(),
'name' => $fileEntity->getName(),
'status' => $fileEntity->getStatus(),
'metadata' => $fileEntity->getMetadata() ?? [],
'metadata' => self::publicMetadata($fileEntity),
'docmdpLevel' => $fileEntity->getDocmdpLevel(),
'createdAt' => $fileEntity->getCreatedAt(),
'userId' => $fileEntity->getUserId(),
Expand Down Expand Up @@ -353,7 +353,7 @@ private function formatSingleFileSummary(
IUser $user,
?File $envelope = null,
): array {
$metadata = $fileEntity->getMetadata() ?? [];
$metadata = self::publicMetadata($fileEntity);
$nodeType = $fileEntity->getNodeType();
$filesCount = $nodeType === 'envelope'
? max(0, (int)($metadata['filesCount'] ?? 0))
Expand Down Expand Up @@ -831,7 +831,7 @@ private function isCurrentUserSigner(array $identifyMethodsOfSigner, IUser $user
* @psalm-suppress MoreSpecificReturnType
*/
public function formatFileWithChildren(File $mainEntity, array $childFiles, ?IUser $user = null): array {
$metadata = $mainEntity->getMetadata() ?? [];
$metadata = self::publicMetadata($mainEntity);

$signRequestEntities = $this->signRequestMapper->getByFileId($mainEntity->getId());
$identifyMethods = $this->signRequestMapper->getIdentifyMethodsFromSigners($signRequestEntities);
Expand Down Expand Up @@ -1094,7 +1094,7 @@ private function formatChildFilesResponse(

return array_values(array_map(function (File $file) use ($signersByFileId, $identifyMethods, $user, $meSignRequestId) {
$signers = $signersByFileId[$file->getId()] ?? [];
$metadata = $file->getMetadata() ?? [];
$metadata = self::publicMetadata($file);
$size = $this->getFileSize($file);
$rejectionViewer = $this->rejectionViewer($file, $signers, $identifyMethods, $user, $meSignRequestId);
$hiddenRejection = $this->signatureRejectionVisibilityService->hasHiddenRejection($file, $signers, $rejectionViewer);
Expand Down Expand Up @@ -1148,6 +1148,13 @@ private function formatChildFilesResponse(
}, $files));
}

/** @return array<string, mixed> */
private static function publicMetadata(File $file): array {
$metadata = $file->getMetadata() ?? [];
unset($metadata[FileStatusService::READY_EVENT_ID_METADATA_KEY]);
return $metadata;
}

private function getFileSize(File $file): int {
$nodeId = $file->getSignedNodeId() ?: $file->getNodeId();
if ($nodeId === null || $file->getUserId() === '') {
Expand Down
2 changes: 1 addition & 1 deletion lib/Service/File/ValidationMetadataNormalizer.php
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ final class ValidationMetadataNormalizer {
public static function normalize(array $metadata, string $fileName, int $totalPages): array {
$normalized = $metadata;
// Internal lifecycle marker, not part of the validation metadata.
unset($normalized[FileStatusService::POLICY_SNAPSHOT_FROZEN_AT]);
unset($normalized[FileStatusService::POLICY_SNAPSHOT_FROZEN_AT], $normalized[FileStatusService::READY_EVENT_ID_METADATA_KEY]);
$normalized['p'] = self::normalizePageCount($totalPages);
$normalized['extension'] = self::normalizeExtension($normalized, $fileName);

Expand Down
Loading
Loading