@wildo-ai/saas-backend-lib 1.1.12 → 1.1.13

package/dist/esm/compliance/electronic-signatures/signature-requests.backend.service.js

@@ -41,7 +41,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
  * unique slot is owed when a caller can race (the send trigger, #2925).
  */
 import { createHash, randomBytes } from 'node:crypto';
-import { injectable, inject, optional } from 'inversify';
+import { injectable, inject, optional, unmanaged } from 'inversify';
 import { ApprovalSealStatus, CoreAuditableEventType, CoreResourceType, ErrorCustomMessageReference, ErrorType, HumanDecision_Outcome, SignatureRequest_CancellationReason, SignatureRequest_Event, SignatureRequest_RereadCause, SignatureRequest_State, SignatureRequest_TransitionOutcome, SIGNATURE_REQUEST_TERMINAL_STATES, SortOrder, UserStatus, advanceSignatureRequestState, } from '@wildo-ai/saas-models';
 import { ElectronicSignature_CancellationOutcome, ElectronicSignature_VendorRequestStatus, } from '@wildo-ai/external-connectors-models';
 import { SAAS_SERVICE_TYPES } from '../../inject/models/service-types.js';
@@ -49,7 +49,7 @@ import { ElectronicSignatureSendOutcome } from '../../external-providers/service
 import { describeCaughtError } from '../../errors/utils/error-log-level-classification.backend.utils.js';
 import { isUniqueConstraintConflict } from '../../errors/utils/unique-conflict-classification.backend.utils.js';
 import { SignedDocumentVerdict } from './signed-document-validation.backend.js';
-import { SignatureRequestEvidenceField } from './signature-request-evidence-files.backend.js';
+import { SIGNATURE_EVIDENCE_LINK_RETRIED, SignatureRequestEvidenceField, SignatureRequestEvidenceLinkOutcome, } from './signature-request-evidence-files.backend.js';
 /** Why a deliverable was not sent. */
 export var SignatureRequestSendRefusal;
 (function (SignatureRequestSendRefusal) {
@@ -72,6 +72,36 @@ export var SignatureRequestSendRefusal;
     /** The vendor accepted the request and the record could not be written; the request was cancelled at the vendor. */
     SignatureRequestSendRefusal["RECORD_NOT_WRITTEN"] = "record_not_written";
 })(SignatureRequestSendRefusal || (SignatureRequestSendRefusal = {}));
+/**
+ * Why a request the vendor reported complete was not made SIGNED by its evidence: the label of
+ * `signature_request_evidence_refused_total`, and what the re-read's reason explains in words.
+ */
+export var SignatureRequestEvidenceFailure;
+(function (SignatureRequestEvidenceFailure) {
+    /** No signed-document validator is bound in this runtime. */
+    SignatureRequestEvidenceFailure["NO_VALIDATOR"] = "no_validator";
+    /** The vendor split the request into several documents; one signed document per request is kept. */
+    SignatureRequestEvidenceFailure["SPLIT_REQUEST"] = "split_request";
+    /** The provider declares no evidence policy (trust anchors). */
+    SignatureRequestEvidenceFailure["NO_EVIDENCE_POLICY"] = "no_evidence_policy";
+    /** The signed document could not be downloaded. */
+    SignatureRequestEvidenceFailure["DOWNLOAD_FAILED"] = "download_failed";
+    /** The document did not validate (tampered, updated after signing, untrusted chain, refused algorithm, revocation). */
+    SignatureRequestEvidenceFailure["REJECTED"] = "rejected";
+    /** The document validated and proves another signer or a lower level than required: the request FAILS. */
+    SignatureRequestEvidenceFailure["MISMATCHED"] = "mismatched";
+    /** The document validated and its evidence could not be written: the request stays open and is read again. */
+    SignatureRequestEvidenceFailure["NOT_KEPT"] = "not_kept";
+})(SignatureRequestEvidenceFailure || (SignatureRequestEvidenceFailure = {}));
+/**
+ * How long after a request became SIGNED the poll keeps linking its evidence files (#2293). Longer than the files
+ * cleanup waits before it removes an unlinked file (a day after its scan ended, its default `unlinkedThresholdMs`), so a
+ * scan that ends late is still linked; a file the cleanup removed first is reported lost.
+ */
+export const SIGNATURE_EVIDENCE_LINK_WINDOW_MS = 48 * 3_600_000;
+/** The SIGNED requests one poll reads, a page at a time, to link their evidence. */
+const SIGNATURE_EVIDENCE_LINK_SCAN_LIMIT = 2_000;
+const SIGNATURE_EVIDENCE_LINK_SCAN_PAGE = 100;
 /** Why a re-read did not reach the transition function, or did and could not write. */
 export var SignatureRequestRefreshStop;
 (function (SignatureRequestRefreshStop) {
@@ -97,7 +127,8 @@ let SignatureRequestsBackendService = class SignatureRequestsBackendService {
     errorBuilder;
     evidenceFiles;
     auditLogs;
-    constructor(logger, repositories, executionContextCreator, transport, files, validator, errorBuilder, evidenceFiles, auditLogs) {
+    metrics;
+    constructor(logger, repositories, executionContextCreator, transport, files, validator, errorBuilder, evidenceFiles, auditLogs, metrics, clock) {
         this.logger = logger;
         this.repositories = repositories;
         this.executionContextCreator = executionContextCreator;
@@ -107,7 +138,12 @@ let SignatureRequestsBackendService = class SignatureRequestsBackendService {
         this.errorBuilder = errorBuilder;
         this.evidenceFiles = evidenceFiles;
         this.auditLogs = auditLogs;
+        this.metrics = metrics;
+        this.clock = clock ?? (() => new Date());
     }
+    clock;
+    /** Evidence files already reported lost by this process, so a lost file is logged once rather than every poll. */
+    reportedLostEvidence = new Set();
     /**
      * The removal effect of `signatureRequests` (#2293), registered at startup with the evidence teardown: before the rows of
      * requests whose record goes are destroyed, every OPEN one is cancelled at its vendor, and deleted there where its
@@ -157,6 +193,11 @@ let SignatureRequestsBackendService = class SignatureRequestsBackendService {
      * for the seal's bind check, so the sealed-deliverable gate is marked as that check is.)
      */
     async sendForSignature(input) {
+        const result = await this.sendOnce(input);
+        this.metrics?.recordSignatureRequestSent({ outcome: 'refusal' in result ? result.refusal : ElectronicSignatureSendOutcome.SENT, requiredLevel: input.requiredLevel });
+        return result;
+    }
+    async sendOnce(input) {
         const refuse = (refusal, reason, retryable = false, signatureRequestId) => ({ sent: false, refusal, reason, retryable, ...(signatureRequestId ? { signatureRequestId } : {}) });
         const context = await this.executionContextCreator.createForInternalSystemOperation();
         // 1. The sealed approval, and the file it binds.
@@ -369,8 +410,10 @@ let SignatureRequestsBackendService = class SignatureRequestsBackendService {
         const statuses = [];
         for (const reference of references) {
             const read = await this.transport.read(providerRef, reference);
-            if (read.read === false)
+            if (read.read === false) {
+                this.metrics?.recordSignatureRequestVendorNotRead({ providerRef });
                 return { signatureRequestId, outcome: SignatureRequestRefreshStop.NOT_READ, reason: read.reason };
+            }
             statuses.push(read.reading.status);
         }
         let event = eventOfVendorStatuses(statuses);
@@ -381,6 +424,8 @@ let SignatureRequestsBackendService = class SignatureRequestsBackendService {
             event = evidence.event;
             reason = evidence.reason;
             validated = evidence.validated;
+            if (evidence.failure)
+                this.metrics?.recordSignatureRequestEvidenceRefused({ providerRef, failure: evidence.failure });
         }
         if (event === undefined)
             return { signatureRequestId, outcome: SignatureRequest_TransitionOutcome.UNCHANGED, state: current, reason };
@@ -391,8 +436,10 @@ let SignatureRequestsBackendService = class SignatureRequestsBackendService {
         let kept;
         if (transition.state === SignatureRequest_State.SIGNED) {
             const keeping = await this.keepEvidence(row, validated);
-            if ('reason' in keeping)
+            if ('reason' in keeping) {
+                this.metrics?.recordSignatureRequestEvidenceRefused({ providerRef, failure: SignatureRequestEvidenceFailure.NOT_KEPT });
                 return { signatureRequestId, outcome: SignatureRequest_TransitionOutcome.UNCHANGED, state: current, event, reason: keeping.reason };
+            }
             kept = keeping;
         }
         const now = new Date();
@@ -414,10 +461,12 @@ let SignatureRequestsBackendService = class SignatureRequestsBackendService {
             return { signatureRequestId, outcome: SignatureRequestRefreshStop.LOST_RACE, reason: 'Another re-read moved the request first.' };
         }
         if (kept) {
-            await this.evidenceFiles?.link(kept.signedDocumentFileId, row, SignatureRequestEvidenceField.SIGNED_DOCUMENT);
-            await this.evidenceFiles?.link(kept.validationEvidenceFileId, row, SignatureRequestEvidenceField.VALIDATION_EVIDENCE);
+            // A file not linkable yet (its scan is in flight) is linked by a later poll (`linkPendingEvidence`), never dropped.
+            await this.linkEvidenceFile(kept.signedDocumentFileId, row, SignatureRequestEvidenceField.SIGNED_DOCUMENT);
+            await this.linkEvidenceFile(kept.validationEvidenceFileId, row, SignatureRequestEvidenceField.VALIDATION_EVIDENCE);
         }
         this.logger.info('[signature-requests] A signature request moved', { signatureRequestId, from: current, to: transition.state, event });
+        this.metrics?.recordSignatureRequestMoved({ providerRef, to: transition.state });
         await this.record({
             eventType: CoreAuditableEventType.SIGNATURE_REQUEST_MOVED, ...signatureRequestEventFieldsOf(row), from: current, to: transition.state, event,
             ...(reason ? { reason } : {}),
@@ -440,17 +489,18 @@ let SignatureRequestsBackendService = class SignatureRequestsBackendService {
      * several references cannot keep its evidence in the request's own fields and is left open (stated, never guessed).
      */
     async validateEvidence(row, context) {
+        const F = SignatureRequestEvidenceFailure;
         if (!this.validator) {
-            return { event: SignatureRequest_Event.EVIDENCE_REJECTED, reason: 'The vendor reports the request complete and no signed-document validator is bound: it stays open.' };
+            return { event: SignatureRequest_Event.EVIDENCE_REJECTED, failure: F.NO_VALIDATOR, reason: 'The vendor reports the request complete and no signed-document validator is bound: it stays open.' };
         }
         const providerRef = String(row.providerRef);
         const references = row.vendorReferences;
         if (references.length !== 1) {
-            return { event: SignatureRequest_Event.EVIDENCE_REJECTED, reason: `The vendor split the request into ${references.length} documents; one signed document per request is kept, so it stays open.` };
+            return { event: SignatureRequest_Event.EVIDENCE_REJECTED, failure: F.SPLIT_REQUEST, reason: `The vendor split the request into ${references.length} documents; one signed document per request is kept, so it stays open.` };
         }
         const evidencePolicy = this.transport.evidencePolicyOf?.(providerRef);
         if (!evidencePolicy)
-            return { event: SignatureRequest_Event.EVIDENCE_REJECTED, reason: `Provider "${providerRef}" declares no evidence policy (trust anchors): it stays open.` };
+            return { event: SignatureRequest_Event.EVIDENCE_REJECTED, failure: F.NO_EVIDENCE_POLICY, reason: `Provider "${providerRef}" declares no evidence policy (trust anchors): it stays open.` };
         const signers = await this.repositories.findManyForInfrastructure(CoreResourceType.SIGNATURE_REQUEST_SIGNERS, { signatureRequestId: row._id }, context);
         const expectedSigners = [];
         for (const signer of signers) {
@@ -465,7 +515,7 @@ let SignatureRequestsBackendService = class SignatureRequestsBackendService {
         }
         const download = await this.transport.downloadSignedDocument(providerRef, references[0]);
         if (download.downloaded === false)
-            return { event: SignatureRequest_Event.EVIDENCE_REJECTED, reason: download.reason };
+            return { event: SignatureRequest_Event.EVIDENCE_REJECTED, failure: F.DOWNLOAD_FAILED, reason: download.reason };
         const verdict = await this.validator.validate({
             signedDocument: download.bytes, originalContentSha256: String(row.originalContentSha256), requiredLevel: row.requiredLevel,
             providerRef, vendorEnvironment: this.transport.vendorEnvironmentOf?.(providerRef), evidencePolicy,
@@ -473,9 +523,9 @@ let SignatureRequestsBackendService = class SignatureRequestsBackendService {
             expectedSigners,
         });
         if (verdict.verdict === SignedDocumentVerdict.MISMATCHED)
-            return { event: SignatureRequest_Event.EVIDENCE_MISMATCHED, reason: verdict.reason };
+            return { event: SignatureRequest_Event.EVIDENCE_MISMATCHED, failure: F.MISMATCHED, reason: verdict.reason };
         if (verdict.verdict !== SignedDocumentVerdict.VALID)
-            return { event: SignatureRequest_Event.EVIDENCE_REJECTED, reason: verdict.reason };
+            return { event: SignatureRequest_Event.EVIDENCE_REJECTED, failure: F.REJECTED, reason: verdict.reason };
         // The signers the evidence PROVED: those a validated certificate names. At SIMPLE a vendor's own seal names nobody.
         const provedEmails = new Set(verdict.evidence.signatures.flatMap((signature) => (signature.signerEmail ? [signature.signerEmail] : [])));
         return {
@@ -486,6 +536,100 @@ let SignatureRequestsBackendService = class SignatureRequestsBackendService {
             },
         };
     }
+    /**
+     * Link the evidence files of the requests that became SIGNED in the last {@link SIGNATURE_EVIDENCE_LINK_WINDOW_MS} and
+     * are not linked yet (#2293). Run by the poll. A file whose scan has not ended is linked by a later run; one that can
+     * never be linked is reported lost, once. Without this, a signed document scanned on write was never linked (its link
+     * is refused while it is SCANNING) and the files cleanup removed it a day later. Never throws for one request.
+     *
+     * Read cost, stated: each run reads every SIGNED request of the window and each of its two files once, a primary-key read
+     * per file, up to {@link SIGNATURE_EVIDENCE_LINK_SCAN_LIMIT} requests.
+     */
+    async linkPendingEvidence() {
+        const report = { examined: 0, linked: 0, pending: 0, lost: 0 };
+        if (!this.evidenceFiles)
+            return report;
+        const context = await this.executionContextCreator.createForInternalSystemOperation();
+        for await (const row of this.signedInLinkWindow(context)) {
+            report.examined += 1;
+            for (const field of [SignatureRequestEvidenceField.SIGNED_DOCUMENT, SignatureRequestEvidenceField.VALIDATION_EVIDENCE]) {
+                const fileId = row[field]?.fileId;
+                if (typeof fileId !== 'string')
+                    continue;
+                let outcome;
+                try {
+                    outcome = await this.linkEvidenceFile(fileId, row, field);
+                }
+                catch (error) {
+                    this.logger.warn('[signature-requests] An evidence file could not be linked; the next poll tries again', { signatureRequestId: String(row._id), fileId, error: describeCaughtError(error) });
+                    report.pending += 1;
+                    continue;
+                }
+                if (outcome === SignatureRequestEvidenceLinkOutcome.LINKED)
+                    report.linked += 1;
+                else if (SIGNATURE_EVIDENCE_LINK_RETRIED.has(outcome))
+                    report.pending += 1;
+                else if (outcome === SignatureRequestEvidenceLinkOutcome.LOST)
+                    report.lost += 1;
+            }
+        }
+        return report;
+    }
+    /**
+     * Link one evidence file and say what happened: a lost file at error (once per process, with its metric), a link left
+     * for a later poll at info. Never throws; the port never does.
+     */
+    async linkEvidenceFile(fileId, row, field) {
+        if (!this.evidenceFiles)
+            return SignatureRequestEvidenceLinkOutcome.FAILED;
+        const outcome = await this.evidenceFiles.link(fileId, row, field);
+        if (outcome === SignatureRequestEvidenceLinkOutcome.ALREADY_LINKED)
+            return outcome;
+        if (outcome === SignatureRequestEvidenceLinkOutcome.LOST) {
+            if (this.reportedLostEvidence.has(fileId))
+                return outcome;
+            if (this.reportedLostEvidence.size < 10_000)
+                this.reportedLostEvidence.add(fileId);
+            this.logger.error('[signature-requests] A SIGNED request names an evidence file that can never be linked to it (gone, infected, quarantined, failed, or linked elsewhere); its evidence is not kept', {
+                signatureRequestId: String(row._id), fileId, field,
+            });
+        }
+        else if (SIGNATURE_EVIDENCE_LINK_RETRIED.has(outcome)) {
+            this.logger.info('[signature-requests] An evidence file is not linkable yet (its scan has not ended, or the store did not answer); the poll links it later', {
+                signatureRequestId: String(row._id), fileId, field, outcome,
+            });
+        }
+        this.metrics?.recordSignatureRequestEvidenceLink({ outcome });
+        return outcome;
+    }
+    /**
+     * The SIGNED requests validated in the link window, oldest first, a page at a time. Pages advance on `validatedAt`, ids
+     * already seen skipped, so requests validated in the same instant are not lost between pages (the trigger's paging).
+     */
+    async *signedInLinkWindow(context) {
+        let from = new Date(this.clock().getTime() - SIGNATURE_EVIDENCE_LINK_WINDOW_MS);
+        const seen = new Set();
+        let pageSize = SIGNATURE_EVIDENCE_LINK_SCAN_PAGE;
+        for (let scanned = 0; scanned < SIGNATURE_EVIDENCE_LINK_SCAN_LIMIT;) {
+            const page = await this.repositories.findManyForInfrastructure(CoreResourceType.SIGNATURE_REQUESTS, { state: SignatureRequest_State.SIGNED, validatedAt: { $gte: from } }, context, undefined, { sort: [{ field: 'validatedAt', order: SortOrder.ASC }, { field: '_id', order: SortOrder.ASC }], limit: pageSize });
+            const fresh = page.filter((row) => !seen.has(String(row._id)));
+            if (fresh.length === 0) {
+                if (page.length < pageSize || pageSize >= SIGNATURE_EVIDENCE_LINK_SCAN_LIMIT)
+                    return;
+                pageSize = Math.min(pageSize * 2, SIGNATURE_EVIDENCE_LINK_SCAN_LIMIT);
+                continue;
+            }
+            for (const row of fresh) {
+                seen.add(String(row._id));
+                scanned += 1;
+                yield row;
+            }
+            if (page.length < pageSize)
+                return;
+            const last = page[page.length - 1].validatedAt;
+            from = last instanceof Date ? last : new Date(String(last));
+        }
+    }
     /** Write the request's two evidence files, unlinked. A reason when they cannot be kept: the request then stays open. */
     async keepEvidence(row, validated) {
         if (!validated)
@@ -538,7 +682,10 @@ SignatureRequestsBackendService = __decorate([
     __param(7, optional()),
     __param(8, inject(SAAS_SERVICE_TYPES.AuditLogsService)),
     __param(8, optional()),
-    __metadata("design:paramtypes", [Function, Object, Object, Object, Object, Object, Object, Object, Object])
+    __param(9, inject(SAAS_SERVICE_TYPES.MetricsService)),
+    __param(9, optional()),
+    __param(10, unmanaged()),
+    __metadata("design:paramtypes", [Function, Object, Object, Object, Object, Object, Object, Object, Object, Object, Function])
 ], SignatureRequestsBackendService);
 export { SignatureRequestsBackendService };
 /** The fields every signature request event names, read from the request row. */