@verana-labs/credo-ts-didcomm-vt-flow 2.0.0-dev.8 → 2.0.0-dev.81

package/build/services/VtFlowService.js

@@ -19,6 +19,7 @@ const VtFlowModuleConfig_1 = require("../VtFlowModuleConfig");
 const errors_1 = require("../errors");
 const messages_1 = require("../messages");
 const repository_1 = require("../repository");
+const utils_1 = require("../utils");
 const types_1 = require("../types");
 /** Core state machine for vt-flow; each method performs one transition and returns the wire message without dispatching (dispatch lives in `VtFlowApi`). */
 let VtFlowService = class VtFlowService {
@@ -31,7 +32,7 @@ let VtFlowService = class VtFlowService {
     /** Applicant-side OnboardingProcess: build the outbound `onboarding-request` and persist a record in `OR_SENT`. */
     async createOnboardingProcessRecord(agentContext, params) {
         const message = new messages_1.OnboardingRequestMessage({
-            participantId: params.participantId,
+            participantId: params.applicantParticipantId,
             participantSessionId: params.participantSessionId,
             agentParticipantId: params.agentParticipantId,
             walletAgentParticipantId: params.walletAgentParticipantId,
@@ -40,7 +41,7 @@ let VtFlowService = class VtFlowService {
         message.setThread({ threadId: message.id });
         const existing = await this.repository.findByParticipantSessionId(agentContext, params.participantSessionId, types_1.VtFlowRole.Applicant);
         if (existing) {
-            if (existing.state !== types_1.VtFlowState.Completed && existing.state !== types_1.VtFlowState.CredRevoked) {
+            if (!(0, types_1.isVtFlowRenewable)(existing)) {
                 throw new core_1.CredoError(`vt-flow: participant_session_id '${params.participantSessionId}' already belongs to a flow in state ${existing.state}; use a new session id`);
             }
             existing.connectionId = params.connectionId;
@@ -59,7 +60,10 @@ let VtFlowService = class VtFlowService {
             variant: types_1.VtFlowVariant.OnboardingProcess,
             agentParticipantId: params.agentParticipantId,
             walletAgentParticipantId: params.walletAgentParticipantId,
-            participantId: params.participantId,
+            applicantParticipantId: params.applicantParticipantId,
+            applicantParticipantRole: params.applicantParticipantRole,
+            validatorParticipantId: params.validatorParticipantId,
+            schemaId: params.schemaId,
             claims: params.claims,
         });
         await this.repository.save(agentContext, record);
@@ -92,46 +96,109 @@ let VtFlowService = class VtFlowService {
         this.emitStateChanged(agentContext, record, null);
         return { message, record };
     }
+    async reattachOnboardingProcessRecord(agentContext, params) {
+        const record = await this.repository.getById(agentContext, params.vtFlowRecordId);
+        record.assertRole(types_1.VtFlowRole.Applicant);
+        record.assertVariant(types_1.VtFlowVariant.OnboardingProcess);
+        if ((0, types_1.isVtFlowTerminalState)(record.state) ||
+            record.state === types_1.VtFlowState.Completed ||
+            record.state === types_1.VtFlowState.CredRevoked) {
+            throw new core_1.CredoError(`vt-flow: flow '${record.id}' in state ${record.state} cannot be re-attached`);
+        }
+        if (!record.applicantParticipantId)
+            throw new core_1.CredoError(`vt-flow: flow '${record.id}' has no participant_id`);
+        const message = new messages_1.OnboardingRequestMessage({
+            participantId: record.applicantParticipantId,
+            participantSessionId: record.participantSessionId,
+            agentParticipantId: record.agentParticipantId,
+            walletAgentParticipantId: record.walletAgentParticipantId,
+            claims: record.claims,
+            proofsAttach: record.proofsAttach,
+        });
+        message.setThread({ threadId: record.threadId });
+        record.connectionId = params.connectionId;
+        if (record.state === types_1.VtFlowState.CredOffered) {
+            await this.releaseCredentialExchange(agentContext, record);
+            await this.updateState(agentContext, record, types_1.VtFlowState.Validating);
+        }
+        else {
+            await this.repository.update(agentContext, record);
+        }
+        return { message, record };
+    }
+    async releaseCredentialExchange(agentContext, record) {
+        if (record.credentialExchangeRecordId) {
+            const exchanges = agentContext.dependencyManager.resolve(didcomm_1.DidCommCredentialExchangeRepository);
+            const stale = await exchanges.findById(agentContext, record.credentialExchangeRecordId);
+            if (stale) {
+                stale.parentThreadId = undefined;
+                await exchanges.update(agentContext, stale);
+            }
+        }
+        record.credentialExchangeRecordId = undefined;
+        record.subprotocolThid = undefined;
+        record.issuance = undefined;
+    }
     /** Validator-side OnboardingProcess: create or re-attach (by `participant_session_id`) a record in `AWAITING_OR` from an inbound `onboarding-request`. */
     async processReceiveOnboardingRequest(messageContext) {
         const { message, agentContext } = messageContext;
         const connection = messageContext.assertReadyConnection();
-        await this.checkIsVerifiableService(agentContext, connection);
         const existing = await this.repository.findByParticipantSessionId(agentContext, message.participantSessionId, types_1.VtFlowRole.Validator);
+        const record = existing !== null && existing !== void 0 ? existing : new repository_1.VtFlowRecord({
+            threadId: message.threadId,
+            participantSessionId: message.participantSessionId,
+            connectionId: connection.id,
+            role: types_1.VtFlowRole.Validator,
+            state: types_1.VtFlowState.AwaitingOr,
+            variant: types_1.VtFlowVariant.OnboardingProcess,
+            agentParticipantId: message.agentParticipantId,
+            walletAgentParticipantId: message.walletAgentParticipantId,
+            applicantParticipantId: message.participantId,
+            claims: message.claims,
+            proofsAttach: message.proofsAttach,
+        });
+        await this.checkRequestFromVerifiableService(agentContext, connection, record, !existing, {
+            participantId: message.participantId,
+        });
         if (existing) {
             if ((0, types_1.isVtFlowTerminalState)(existing.state)) {
-                throw new core_1.CredoError(`vt-flow: participant_session_id '${message.participantSessionId}' collides with a terminated flow`);
+                throw new errors_1.VtFlowError(errors_1.VtFlowErrorCode.InvalidParticipantSessionId, `vt-flow: participant_session_id '${message.participantSessionId}' collides with a terminated flow`);
+            }
+            if (existing.applicantParticipantId !== message.participantId) {
+                throw new errors_1.VtFlowError(errors_1.VtFlowErrorCode.InvalidParticipantSessionId, `vt-flow: participant_id '${message.participantId}' does not match the flow of participant_session_id '${message.participantSessionId}'`);
             }
             await this.assertSamePeer(agentContext, existing, connection);
+            const reconnected = existing.connectionTerminated;
             existing.connectionId = connection.id;
-            existing.threadId = message.threadId;
-            if (message.claims)
-                existing.claims = message.claims;
-            if (message.proofsAttach)
-                existing.proofsAttach = message.proofsAttach;
-            if (existing.state === types_1.VtFlowState.Completed || existing.state === types_1.VtFlowState.CredRevoked) {
+            existing.connectionTerminated = undefined;
+            if (existing.threadId !== message.threadId) {
+                existing.threadId = message.threadId;
+                if (message.claims)
+                    existing.claims = message.claims;
+                if (message.proofsAttach)
+                    existing.proofsAttach = message.proofsAttach;
+            }
+            if ((0, types_1.isVtFlowRenewable)(existing)) {
                 // A finished flow re-entered with a new OR is a renewal (VSA-VTI-FLOW-OP-RENEW): re-run it.
-                existing.oobLinkUrl = undefined;
+                existing.oobLink = undefined;
+                existing.validation = undefined;
+                existing.issuance = undefined;
                 await this.updateState(agentContext, existing, types_1.VtFlowState.AwaitingOr);
             }
+            else if (existing.state === types_1.VtFlowState.CredOffered) {
+                await this.releaseCredentialExchange(agentContext, existing);
+                await this.updateState(agentContext, existing, types_1.VtFlowState.Validated);
+            }
             else {
                 await this.repository.update(agentContext, existing);
+                // [VSA-VTI-FLOW-OP-OR] checks every request, and [VSA-ADM-VT-FL-REJECT-2] issuance waits for this reconnection
+                if (existing.state === types_1.VtFlowState.AwaitingOr ||
+                    (reconnected && existing.state === types_1.VtFlowState.Validated)) {
+                    this.emitStateChanged(agentContext, existing, existing.state);
+                }
             }
             return existing;
         }
-        const record = new repository_1.VtFlowRecord({
-            threadId: message.threadId,
-            participantSessionId: message.participantSessionId,
-            connectionId: connection.id,
-            role: types_1.VtFlowRole.Validator,
-            state: types_1.VtFlowState.AwaitingOr,
-            variant: types_1.VtFlowVariant.OnboardingProcess,
-            agentParticipantId: message.agentParticipantId,
-            walletAgentParticipantId: message.walletAgentParticipantId,
-            participantId: message.participantId,
-            claims: message.claims,
-            proofsAttach: message.proofsAttach,
-        });
         await this.repository.save(agentContext, record);
         this.emitStateChanged(agentContext, record, null);
         return record;
@@ -140,19 +207,8 @@ let VtFlowService = class VtFlowService {
     async processReceiveIssuanceRequest(messageContext) {
         const { message, agentContext } = messageContext;
         const connection = messageContext.assertReadyConnection();
-        await this.checkIsVerifiableService(agentContext, connection);
         const existing = await this.repository.findByParticipantSessionId(agentContext, message.participantSessionId, types_1.VtFlowRole.Validator);
-        if (existing) {
-            if ((0, types_1.isVtFlowTerminalState)(existing.state)) {
-                throw new core_1.CredoError(`vt-flow: participant_session_id '${message.participantSessionId}' collides with a terminated flow`);
-            }
-            await this.assertSamePeer(agentContext, existing, connection);
-            existing.connectionId = connection.id;
-            existing.threadId = message.threadId;
-            await this.repository.update(agentContext, existing);
-            return existing;
-        }
-        const record = new repository_1.VtFlowRecord({
+        const record = existing !== null && existing !== void 0 ? existing : new repository_1.VtFlowRecord({
             threadId: message.threadId,
             participantSessionId: message.participantSessionId,
             connectionId: connection.id,
@@ -164,20 +220,61 @@ let VtFlowService = class VtFlowService {
             schemaId: message.schemaId,
             claims: message.claims,
         });
+        await this.checkRequestFromVerifiableService(agentContext, connection, record, !existing, {
+            schemaId: message.schemaId,
+        });
+        if (existing) {
+            if ((0, types_1.isVtFlowTerminalState)(existing.state)) {
+                throw new errors_1.VtFlowError(errors_1.VtFlowErrorCode.InvalidParticipantSessionId, `vt-flow: participant_session_id '${message.participantSessionId}' collides with a terminated flow`);
+            }
+            if (existing.variant !== types_1.VtFlowVariant.DirectIssuance || existing.schemaId !== message.schemaId) {
+                throw new errors_1.VtFlowError(errors_1.VtFlowErrorCode.InvalidParticipantSessionId, `vt-flow: schema_id '${message.schemaId}' does not match the flow of participant_session_id '${message.participantSessionId}'`);
+            }
+            await this.assertSamePeer(agentContext, existing, connection);
+            existing.connectionId = connection.id;
+            existing.threadId = message.threadId;
+            if (existing.state === types_1.VtFlowState.CredOffered) {
+                await this.releaseCredentialExchange(agentContext, existing);
+                await this.updateState(agentContext, existing, types_1.VtFlowState.Validating);
+            }
+            else {
+                await this.repository.update(agentContext, existing);
+            }
+            return existing;
+        }
         await this.repository.save(agentContext, record);
         this.emitStateChanged(agentContext, record, null);
         return record;
     }
-    /** Applicant-side inbound `oob-link`; transitions the session to `OOB_PENDING`. */
+    /** Applicant-side inbound `oob-link`; `OR_SENT`, `IR_SENT`, `VALIDATING` or `OOB_PENDING` => `OOB_PENDING`. */
     async processReceiveOobLink(messageContext) {
+        var _a;
         const { message, agentContext } = messageContext;
         messageContext.assertReadyConnection();
         const record = await this.getByThreadId(agentContext, message.threadId);
         record.assertRole(types_1.VtFlowRole.Applicant);
+        record.assertState([
+            types_1.VtFlowState.OrSent,
+            types_1.VtFlowState.IrSent,
+            types_1.VtFlowState.Validating,
+            types_1.VtFlowState.OobPending,
+        ]);
+        record.oobLink = {
+            url: message.url,
+            description: message.description,
+            expiresAt: (_a = message.expiresTime) === null || _a === void 0 ? void 0 : _a.toISOString(),
+            at: new Date().toISOString(),
+        };
+        this.appendMessage(record, {
+            type: types_1.VtFlowMessageType.OobLink,
+            text: message.description,
+            at: record.oobLink.at,
+            url: message.url,
+        });
         await this.updateState(agentContext, record, types_1.VtFlowState.OobPending);
         return record;
     }
-    /** Applicant-side inbound `validating`; OnboardingProcess applicant transitions `OR_SENT => VALIDATING`. */
+    /** Applicant-side inbound `validating`; `OR_SENT`, `IR_SENT` or `OOB_PENDING` => `VALIDATING`. */
     async processReceiveValidating(messageContext) {
         var _a;
         const { message, agentContext } = messageContext;
@@ -185,8 +282,16 @@ let VtFlowService = class VtFlowService {
         const record = await this.getByThreadId(agentContext, message.threadId);
         this.logger.debug(`[vt-flow] validating received for session ${record.threadId}: ${(_a = message.comment) !== null && _a !== void 0 ? _a : '(no comment)'}`);
         if (record.role === types_1.VtFlowRole.Applicant &&
-            record.variant === types_1.VtFlowVariant.OnboardingProcess &&
-            record.state === types_1.VtFlowState.OrSent) {
+            (message.comment || record.state === types_1.VtFlowState.OobPending)) {
+            this.appendMessage(record, {
+                type: types_1.VtFlowMessageType.Validating,
+                text: message.comment,
+                at: new Date().toISOString(),
+            });
+            await this.updateRecord(agentContext, record);
+        }
+        if (record.role === types_1.VtFlowRole.Applicant &&
+            [types_1.VtFlowState.OrSent, types_1.VtFlowState.IrSent, types_1.VtFlowState.OobPending].includes(record.state)) {
             await this.updateState(agentContext, record, types_1.VtFlowState.Validating);
         }
         return record;
@@ -208,14 +313,26 @@ let VtFlowService = class VtFlowService {
         }
         return record;
     }
-    /** `AWAITING_OR => VALIDATING`; caller is expected to have verified participant/agent/wallet IDs on-chain. */
+    /** `AWAITING_OR => VALIDATING` once the `checkParticipantId` hook accepts the `participant_id`, with no transition and no message once it reports the request settled by a `VALIDATED` entry; caller is expected to have verified agent/wallet IDs on-chain. */
     async acceptOnboardingRequest(agentContext, recordId) {
-        const record = await this.repository.getById(agentContext, recordId);
+        let record = await this.repository.getById(agentContext, recordId);
         record.assertRole(types_1.VtFlowRole.Validator);
         record.assertState(types_1.VtFlowState.AwaitingOr);
         record.assertVariant(types_1.VtFlowVariant.OnboardingProcess);
+        const { checkParticipantId } = this.config;
+        if (checkParticipantId) {
+            const checked = await checkParticipantId({ agentContext, record });
+            if (!checked) {
+                throw new errors_1.VtFlowError(errors_1.VtFlowErrorCode.InvalidParticipantId, `vt-flow: participant_id '${record.applicantParticipantId}' is not a PENDING entry that names this agent as its validator`);
+            }
+            // the check can wait for the indexer while the flow moves on
+            record = await this.repository.getById(agentContext, recordId);
+            if (checked === 'validated')
+                return { record };
+            record.assertState(types_1.VtFlowState.AwaitingOr);
+        }
         await this.updateState(agentContext, record, types_1.VtFlowState.Validating);
-        return record;
+        return { record, message: new messages_1.ValidatingMessage({ threadId: record.threadId }) };
     }
     /** DirectIssuance: `AWAITING_IR => VALIDATING`; transient before `CRED_OFFERED`. */
     async acceptIssuanceRequest(agentContext, recordId) {
@@ -224,23 +341,44 @@ let VtFlowService = class VtFlowService {
         record.assertState(types_1.VtFlowState.AwaitingIr);
         record.assertVariant(types_1.VtFlowVariant.DirectIssuance);
         await this.updateState(agentContext, record, types_1.VtFlowState.Validating);
-        return record;
+        return { record, message: new messages_1.ValidatingMessage({ threadId: record.threadId }) };
     }
-    /** Reject with a problem-report; transitions to `TERMINATED_BY_{role}` and marks the connection as `TERMINATED`. */
+    /** Reject with a problem-report; a fatal code moves the sender to the Error Codes state, a retryable one returns a validator to `AWAITING_OR` or `AWAITING_IR`. */
     async rejectRequest(agentContext, recordId, params) {
         var _a;
         const record = await this.repository.getById(agentContext, recordId);
+        if ((0, types_1.isVtFlowTerminalState)(record.state)) {
+            throw new core_1.CredoError(`vt-flow: flow '${record.id}' in state ${record.state} cannot be rejected`);
+        }
         const problemReport = (0, errors_1.buildVtFlowProblemReport)({
             code: params.code,
             threadId: record.threadId,
             enDescription: params.enDescription,
             fixHintEn: params.fixHintEn,
         });
-        const nextState = record.role === types_1.VtFlowRole.Validator
-            ? types_1.VtFlowState.TerminatedByValidator
-            : types_1.VtFlowState.TerminatedByApplicant;
-        record.errorMessage = (_a = params.enDescription) !== null && _a !== void 0 ? _a : params.code;
-        await this.updateState(agentContext, record, nextState);
+        const info = errors_1.VT_FLOW_ERROR_INFO[params.code];
+        const receiverRole = record.role === types_1.VtFlowRole.Validator ? types_1.VtFlowRole.Applicant : types_1.VtFlowRole.Validator;
+        // a fatal code lands both parties in the state the table gives the receiver
+        const fatalState = this.resolveErrorFlowState(info.flowState, receiverRole, errors_1.whoRetriesMap[info.whoRetries]);
+        const retryState = record.variant === types_1.VtFlowVariant.OnboardingProcess ? types_1.VtFlowState.AwaitingOr : types_1.VtFlowState.AwaitingIr;
+        if (!fatalState && record.role === types_1.VtFlowRole.Validator) {
+            record.assertState([
+                types_1.VtFlowState.AwaitingOr,
+                types_1.VtFlowState.AwaitingIr,
+                types_1.VtFlowState.Validating,
+                types_1.VtFlowState.OobPending,
+            ]);
+        }
+        if (record.role === types_1.VtFlowRole.Validator) {
+            this.appendMessage(record, {
+                type: types_1.VtFlowMessageType.ProblemReport,
+                text: problemReport.description.en,
+                at: new Date().toISOString(),
+            });
+        }
+        if (fatalState)
+            record.errorMessage = (_a = params.enDescription) !== null && _a !== void 0 ? _a : params.code;
+        await this.updateState(agentContext, record, fatalState !== null && fatalState !== void 0 ? fatalState : (record.role === types_1.VtFlowRole.Validator ? retryState : record.state));
         return { record, problemReport };
     }
     /** Applicant-side termination producing a problem-report and landing in `TERMINATED_BY_APPLICANT`. */
@@ -264,6 +402,17 @@ let VtFlowService = class VtFlowService {
         var _a, _b;
         const record = await this.repository.getById(agentContext, recordId);
         record.assertRole(types_1.VtFlowRole.Validator);
+        record.assertState([
+            types_1.VtFlowState.AwaitingOr,
+            types_1.VtFlowState.AwaitingIr,
+            types_1.VtFlowState.Validating,
+            types_1.VtFlowState.OobPending,
+            types_1.VtFlowState.AwaitingValidationTx,
+            types_1.VtFlowState.ValidationTxFailed,
+            // VtFlowModule ends the flow here when auto-issue throws. A failed anchoring stays in CRED_OFFERED instead
+            types_1.VtFlowState.CredOffered,
+            types_1.VtFlowState.Completed,
+        ]);
         const code = (_a = params.code) !== null && _a !== void 0 ? _a : errors_1.VtFlowErrorCode.SessionTerminated;
         const problemReport = (0, errors_1.buildVtFlowProblemReport)({
             code,
@@ -272,6 +421,12 @@ let VtFlowService = class VtFlowService {
             fixHintEn: params.fixHintEn,
         });
         record.errorMessage = (_b = params.enDescription) !== null && _b !== void 0 ? _b : code;
+        this.appendMessage(record, {
+            type: types_1.VtFlowMessageType.ProblemReport,
+            text: problemReport.description.en,
+            at: new Date().toISOString(),
+        });
+        record.connectionTerminated = true;
         await this.updateState(agentContext, record, types_1.VtFlowState.TerminatedByValidator);
         return { record, problemReport };
     }
@@ -288,62 +443,120 @@ let VtFlowService = class VtFlowService {
         await this.updateState(agentContext, record, params.state);
         return { record, problemReport };
     }
-    /** Build an `oob-link`; non-terminal records transition to `OOB_PENDING`. */
+    /** Build an `oob-link` from `VALIDATING` or `OOB_PENDING`; the flow moves to or stays in `OOB_PENDING`. */
     async sendOobLinkForSession(agentContext, recordId, params) {
+        var _a;
         const record = await this.repository.getById(agentContext, recordId);
         record.assertRole(types_1.VtFlowRole.Validator);
-        record.assertState([
-            types_1.VtFlowState.AwaitingOr,
-            types_1.VtFlowState.AwaitingIr,
-            types_1.VtFlowState.Validating,
-            types_1.VtFlowState.OobPending,
-            types_1.VtFlowState.Completed,
-        ]);
+        record.assertState([types_1.VtFlowState.Validating, types_1.VtFlowState.OobPending]);
         const message = new messages_1.OobLinkMessage({
             threadId: record.threadId,
             url: params.url,
             description: params.description,
             expiresTime: params.expiresTime,
         });
-        record.oobLinkUrl = params.url;
-        if (record.state !== types_1.VtFlowState.Completed) {
-            await this.updateState(agentContext, record, types_1.VtFlowState.OobPending);
-        }
-        else {
-            await this.updateRecord(agentContext, record);
-        }
+        record.oobLink = {
+            url: params.url,
+            description: params.description,
+            expiresAt: (_a = params.expiresTime) === null || _a === void 0 ? void 0 : _a.toISOString(),
+            at: new Date().toISOString(),
+        };
+        this.appendMessage(record, {
+            type: types_1.VtFlowMessageType.OobLink,
+            text: params.description,
+            at: record.oobLink.at,
+            url: params.url,
+        });
+        await this.updateState(agentContext, record, types_1.VtFlowState.OobPending);
         return { record, message };
     }
-    /** Build a `validating` informational message; no state change on the Validator side. */
+    /** `OOB_PENDING` => `VALIDATING`, with the `validating` that tells the applicant its out-of-band step is done. */
     async sendValidatingForSession(agentContext, recordId, params = {}) {
         const record = await this.repository.getById(agentContext, recordId);
         record.assertRole(types_1.VtFlowRole.Validator);
+        record.assertState(types_1.VtFlowState.OobPending);
         const message = new messages_1.ValidatingMessage({
             threadId: record.threadId,
             comment: params.comment,
         });
+        this.appendMessage(record, {
+            type: types_1.VtFlowMessageType.Validating,
+            text: params.comment,
+            at: new Date().toISOString(),
+        });
+        await this.updateState(agentContext, record, types_1.VtFlowState.Validating);
         return { record, message };
     }
-    /** `VALIDATING => VALIDATED`; call after `SetParticipantOPtoValidated` lands on-chain. */
+    /** Record the validation decision or its transaction outcome, moving the flow when `state` is given. */
+    async recordValidation(agentContext, recordId, validation, state) {
+        const record = await this.repository.getById(agentContext, recordId);
+        record.assertRole(types_1.VtFlowRole.Validator);
+        record.validation = validation;
+        if (state)
+            await this.updateState(agentContext, record, state);
+        else
+            await this.updateRecord(agentContext, record);
+        return record;
+    }
+    /** Record the outcome of the `CreateOrUpdateParticipantSession` transaction that anchors the issued credential. */
+    async recordIssuance(agentContext, recordId, issuance) {
+        const record = await this.repository.getById(agentContext, recordId);
+        record.assertRole(types_1.VtFlowRole.Validator);
+        record.issuance = issuance;
+        await this.updateRecord(agentContext, record);
+        return record;
+    }
+    /** `VALIDATED` => `VALIDATED_PENDING_CLAIMS`, when the claims fail the schema at offer time ([VSA-VTI-FLOW-OP-ISSUE-4]). */
+    async markPendingClaims(agentContext, recordId) {
+        const record = await this.repository.getById(agentContext, recordId);
+        record.assertRole(types_1.VtFlowRole.Validator);
+        record.assertState(types_1.VtFlowState.Validated);
+        await this.updateState(agentContext, record, types_1.VtFlowState.ValidatedPendingClaims);
+        return record;
+    }
+    /** Validator-side states preceding `VALIDATED` => `VALIDATED`; call after `SetParticipantOPtoValidated` lands on-chain. */
     async markValidated(agentContext, recordId) {
         const record = await this.repository.getById(agentContext, recordId);
         record.assertRole(types_1.VtFlowRole.Validator);
-        record.assertState([types_1.VtFlowState.Validating, types_1.VtFlowState.OobPending]);
+        record.assertState([...types_1.VtFlowValidatedFromStates]);
         record.assertVariant(types_1.VtFlowVariant.OnboardingProcess);
         await this.updateState(agentContext, record, types_1.VtFlowState.Validated);
         return record;
     }
-    /** Link a Credo exchange record to the session and transition to `CRED_OFFERED`. */
-    async attachCredentialExchangeRecord(agentContext, recordId, credentialExchangeRecord, credentialDigest, issuerParticipantId) {
+    /**
+     * Close an onboarding process that carries no credential exchange. Only a HOLDER receives a
+     * credential; for every other role the chain records the outcome with
+     * SetParticipantOPToValidated, and nothing else follows. Both sides use this, so it asserts no
+     * role: the validator calls it after it validates, and the applicant reaches it from the chain
+     * event.
+     */
+    async markCompleted(agentContext, recordId) {
         const record = await this.repository.getById(agentContext, recordId);
+        record.assertVariant(types_1.VtFlowVariant.OnboardingProcess);
+        if (record.state === types_1.VtFlowState.Completed)
+            return record;
+        if ((0, types_1.isVtFlowTerminalState)(record.state)) {
+            throw new core_1.CredoError(`VtFlow record is in terminal state '${record.state}'; cannot complete it.`);
+        }
+        await this.updateState(agentContext, record, types_1.VtFlowState.Completed);
+        return record;
+    }
+    /** Validator states that an `offer-credential` moves to `CRED_OFFERED`; from `COMPLETED` it starts a new subprotocol run. */
+    assertCanOfferCredential(record) {
         record.assertRole(types_1.VtFlowRole.Validator);
         record.assertState([
             types_1.VtFlowState.Validated,
-            types_1.VtFlowState.Validating,
-            types_1.VtFlowState.OobPending,
+            types_1.VtFlowState.ValidatedPendingClaims,
             types_1.VtFlowState.Completed,
+            ...(record.variant === types_1.VtFlowVariant.DirectIssuance ? [types_1.VtFlowState.Validating] : []),
         ]);
+    }
+    /** Link a Credo exchange record to the session and transition to `CRED_OFFERED`. */
+    async attachCredentialExchangeRecord(agentContext, recordId, credentialExchangeRecord, credentialDigest, issuerParticipantId, credentialId) {
+        const record = await this.repository.getById(agentContext, recordId);
+        this.assertCanOfferCredential(record);
         record.credentialExchangeRecordId = credentialExchangeRecord.id;
+        record.credentialId = credentialId;
         if (credentialDigest)
             record.credentialDigest = credentialDigest;
         if (issuerParticipantId !== undefined)
@@ -352,6 +565,13 @@ let VtFlowService = class VtFlowService {
         await this.updateState(agentContext, record, types_1.VtFlowState.CredOffered);
         return record;
     }
+    async setEcsSchemaKey(agentContext, recordId, ecsSchemaKey) {
+        const record = await this.repository.getById(agentContext, recordId);
+        record.assertRole(types_1.VtFlowRole.Applicant);
+        record.ecsSchemaKey = ecsSchemaKey;
+        await this.repository.update(agentContext, record);
+        return record;
+    }
     async setCredentialDigest(agentContext, recordId, credentialDigest) {
         const record = await this.repository.getById(agentContext, recordId);
         record.assertRole(types_1.VtFlowRole.Validator);
@@ -380,7 +600,16 @@ let VtFlowService = class VtFlowService {
     async updateClaims(agentContext, recordId, claims) {
         const record = await this.repository.getById(agentContext, recordId);
         record.assertRole(types_1.VtFlowRole.Validator);
-        record.assertState([types_1.VtFlowState.Validating, types_1.VtFlowState.CredRevoked]);
+        record.assertState([
+            types_1.VtFlowState.AwaitingOr,
+            types_1.VtFlowState.OobPending,
+            types_1.VtFlowState.Validating,
+            types_1.VtFlowState.AwaitingValidationTx,
+            types_1.VtFlowState.ValidationTxSubmitted,
+            types_1.VtFlowState.ValidationTxFailed,
+            types_1.VtFlowState.ValidatedPendingClaims,
+            types_1.VtFlowState.CredRevoked,
+        ]);
         record.claims = claims;
         await this.updateRecord(agentContext, record);
         return record;
@@ -401,6 +630,11 @@ let VtFlowService = class VtFlowService {
                 }
                 break;
             case didcomm_1.DidCommCredentialState.OfferReceived:
+                // the offer can beat the chain notification, and an Onboarding Process offers only from VALIDATED
+                if (record.variant === types_1.VtFlowVariant.OnboardingProcess &&
+                    [types_1.VtFlowState.OrSent, types_1.VtFlowState.Validating, types_1.VtFlowState.OobPending].includes(record.state)) {
+                    await this.updateState(agentContext, record, types_1.VtFlowState.Validated);
+                }
                 if (record.state !== types_1.VtFlowState.CredOffered) {
                     await this.updateState(agentContext, record, types_1.VtFlowState.CredOffered);
                 }
@@ -414,6 +648,7 @@ let VtFlowService = class VtFlowService {
                 }
                 break;
             case didcomm_1.DidCommCredentialState.Abandoned:
+            case didcomm_1.DidCommCredentialState.Declined:
                 if (record.state !== types_1.VtFlowState.Error) {
                     record.errorMessage = (_a = record.errorMessage) !== null && _a !== void 0 ? _a : 'Subprotocol abandoned';
                     await this.updateState(agentContext, record, types_1.VtFlowState.Error);
@@ -448,24 +683,111 @@ let VtFlowService = class VtFlowService {
     /** Transition the record, persist it, and emit `VtFlowStateChanged`. */
     async updateState(agentContext, record, newState) {
         const previousState = record.state;
-        if (previousState === newState)
+        if (previousState === newState) {
+            await this.repository.update(agentContext, record);
             return;
+        }
+        if (previousState === types_1.VtFlowState.OobPending)
+            record.oobLink = undefined;
         record.state = newState;
         await this.repository.update(agentContext, record);
         this.emitStateChanged(agentContext, record, previousState);
     }
+    /**
+     * Inbound adopted `problem-report`. The Error Codes table gives the state the receiving party
+     * moves to, so both sides run this same mapping. A retryable code records the message and leaves
+     * the flow where it is.
+     */
+    async processReceiveProblemReport(messageContext) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        const { message, agentContext } = messageContext;
+        const record = await this.repository.findByThreadId(agentContext, message.threadId);
+        if (!record)
+            return undefined;
+        if ((0, types_1.isVtFlowTerminalState)(record.state))
+            return record;
+        const code = (_a = message.description) === null || _a === void 0 ? void 0 : _a.code;
+        const info = code && (0, errors_1.isVtFlowErrorCode)(code) ? errors_1.VT_FLOW_ERROR_INFO[code] : undefined;
+        if (record.role === types_1.VtFlowRole.Applicant) {
+            this.appendMessage(record, {
+                type: types_1.VtFlowMessageType.ProblemReport,
+                text: (_d = (_c = (_b = message.description) === null || _b === void 0 ? void 0 : _b.en) !== null && _c !== void 0 ? _c : code) !== null && _d !== void 0 ? _d : 'problem-report',
+                at: new Date().toISOString(),
+            });
+        }
+        const target = info &&
+            this.resolveErrorFlowState(info.flowState, record.role, (_e = message.whoRetries) !== null && _e !== void 0 ? _e : errors_1.whoRetriesMap[info.whoRetries]);
+        if (!target) {
+            await this.updateRecord(agentContext, record);
+            return record;
+        }
+        record.errorMessage = (_g = (_f = message.description) === null || _f === void 0 ? void 0 : _f.en) !== null && _g !== void 0 ? _g : code;
+        await this.updateState(agentContext, record, target);
+        return record;
+    }
+    /** `terminated-by-sender` is the peer's termination, so the receiver lands in the state named after the sender. */
+    resolveErrorFlowState(flowState, receiverRole, whoRetries) {
+        if (flowState === 'unchanged')
+            return undefined;
+        if (flowState === 'unchanged-when-you') {
+            return whoRetries === didcomm_1.WhoRetriesStatus.You ? undefined : types_1.VtFlowState.Error;
+        }
+        if (flowState === 'error-when-fatal') {
+            return whoRetries === didcomm_1.WhoRetriesStatus.None ? types_1.VtFlowState.Error : undefined;
+        }
+        if (flowState !== 'terminated-by-sender')
+            return flowState;
+        return receiverRole === types_1.VtFlowRole.Applicant
+            ? types_1.VtFlowState.TerminatedByValidator
+            : types_1.VtFlowState.TerminatedByApplicant;
+    }
+    /** Append to `messages[]`, which a validator fills with what it sent and an applicant with what it received. */
+    appendMessage(record, message) {
+        var _a;
+        record.messages = [...((_a = record.messages) !== null && _a !== void 0 ? _a : []), message];
+    }
     /** Persist record changes without state-transition semantics (no event emitted). */
     async updateRecord(agentContext, record) {
         await this.repository.update(agentContext, record);
     }
     /** participant_session_ids are public on-chain, so only the original peer may re-attach a flow with one. */
-    async assertSamePeer(agentContext, record, connection) {
+    async isSamePeer(agentContext, record, connection) {
         if (record.connectionId === connection.id)
-            return;
+            return true;
         const connectionRepository = agentContext.dependencyManager.resolve(didcomm_1.DidCommConnectionRepository);
         const previous = await connectionRepository.findById(agentContext, record.connectionId);
-        if ((previous === null || previous === void 0 ? void 0 : previous.theirDid) && connection.theirDid && previous.theirDid !== connection.theirDid) {
-            throw new core_1.CredoError(`vt-flow: connection '${connection.id}' peer does not match the original connection of participant_session_id '${record.participantSessionId}'`);
+        return !((previous === null || previous === void 0 ? void 0 : previous.theirDid) && connection.theirDid && previous.theirDid !== connection.theirDid);
+    }
+    async assertSamePeer(agentContext, record, connection) {
+        if (!(await this.isSamePeer(agentContext, record, connection))) {
+            throw new errors_1.VtFlowError(errors_1.VtFlowErrorCode.InvalidParticipantSessionId, `vt-flow: connection '${connection.id}' peer does not match the original connection of participant_session_id '${record.participantSessionId}'`);
+        }
+    }
+    /** VS-CONN-VS failure is fatal, so it ends the flow of the request in ERROR unless that flow has ended or belongs to another peer. */
+    async checkRequestFromVerifiableService(agentContext, connection, record, isNew, purpose) {
+        try {
+            await this.checkIsVerifiableService(agentContext, connection, purpose);
+        }
+        catch (error) {
+            if (error instanceof errors_1.VtFlowError &&
+                (isNew ||
+                    (!(0, types_1.isVtFlowTerminalState)(record.state) && (await this.isSamePeer(agentContext, record, connection))))) {
+                record.errorMessage = error.message;
+                this.appendMessage(record, {
+                    type: types_1.VtFlowMessageType.ProblemReport,
+                    text: (0, errors_1.defaultEnglishDescription)(error.code),
+                    at: new Date().toISOString(),
+                });
+                if (isNew) {
+                    record.state = types_1.VtFlowState.Error;
+                    await this.repository.save(agentContext, record);
+                    this.emitStateChanged(agentContext, record, null);
+                }
+                else {
+                    await this.updateState(agentContext, record, types_1.VtFlowState.Error);
+                }
+            }
+            throw error;
         }
     }
     emitStateChanged(agentContext, record, previousState) {
@@ -489,25 +811,47 @@ let VtFlowService = class VtFlowService {
     buildProblemReport(options) {
         return (0, errors_1.buildVtFlowProblemReport)(options);
     }
-    /** Spec Verifiable Service Identity Check: invokes the caller-provided VS-CONN-VS hook. Throws `vt-flow.not-a-verifiable-service` when the peer fails the check. When no hook is configured, logs a warning and permits. */
-    async checkIsVerifiableService(agentContext, connection) {
-        const peerDid = connection.theirDid;
-        if (!peerDid)
+    /** Spec Verifiable Service Identity Check: invokes the caller-provided VS-CONN-VS hook. Throws `vt-flow.not-a-verifiable-service` when the peer fails the check. When no hook is configured, logs a warning and permits. A `purpose` is passed on the Validator side only, and lets a rejected peer through the ECS issuance exemption. */
+    async checkIsVerifiableService(agentContext, connection, purpose) {
+        const peerDid = (0, utils_1.peerAnchorDid)(connection);
+        if (!connection.theirDid || !peerDid) {
             throw new core_1.CredoError(`vt-flow: ready connection '${connection.id}' has no theirDid`);
+        }
         const hook = this.config.assertVerifiableService;
         if (!hook) {
             this.logger.warn(`[vt-flow] assertVerifiableService hook not configured; skipping VS-CONN-VS check for peer '${peerDid}'. Configure VtFlowModuleConfig.assertVerifiableService for spec-conformant trust resolution.`);
             return;
         }
         let permitted = false;
+        let failure;
         try {
-            permitted = await hook({ agentContext, peerDid, connectionId: connection.id });
+            permitted = await hook({
+                agentContext,
+                peerDid,
+                connectionId: connection.id,
+            });
         }
         catch (error) {
-            throw new core_1.CredoError(`vt-flow.not-a-verifiable-service: peer '${peerDid}' failed VS-CONN-VS check (${error.message})`);
+            failure = error.message;
+        }
+        if (permitted)
+            return;
+        if (purpose && (await this.isExemptFromVsConnVs(agentContext, connection, peerDid, purpose))) {
+            this.logger.info(`[vt-flow] peer '${peerDid}' is not (yet) a Verifiable Service, but the request qualifies for the VS-CONN-VS ECS issuance exemption`);
+            return;
+        }
+        throw new errors_1.VtFlowError(errors_1.VtFlowErrorCode.NotAVerifiableService, `vt-flow.not-a-verifiable-service: peer '${peerDid}' failed VS-CONN-VS check${failure ? ` (${failure})` : ''}`);
+    }
+    async isExemptFromVsConnVs(agentContext, connection, peerDid, purpose) {
+        const exemption = this.config.checkEcsIssuanceExemption;
+        if (!exemption)
+            return false;
+        try {
+            return await exemption({ agentContext, peerDid, connectionId: connection.id, purpose });
         }
-        if (!permitted) {
-            throw new core_1.CredoError(`vt-flow.not-a-verifiable-service: peer '${peerDid}' failed VS-CONN-VS check`);
+        catch (error) {
+            this.logger.warn(`[vt-flow] VS-CONN-VS exemption check failed for peer '${peerDid}': ${error.message}`);
+            return false;
         }
     }
 };