@verana-labs/credo-ts-didcomm-vt-flow 2.0.0-dev.7 → 2.0.0-dev.70

package/build/services/VtFlowService.d.ts

@@ -1,15 +1,18 @@
 import type { AgentContext, Logger, Query, QueryOptions } from '@credo-ts/core';
 import type { DidCommConnectionRecord, DidCommCredentialExchangeRecord, DidCommInboundMessageContext } from '@credo-ts/didcomm';
 import { EventEmitter } from '@credo-ts/core';
-import { VtFlowModuleConfig } from '../VtFlowModuleConfig';
+import { VtFlowModuleConfig, type VtFlowRequestPurpose } from '../VtFlowModuleConfig';
 import { type BuildVtFlowProblemReportOptions, VtFlowErrorCode, buildVtFlowProblemReport } from '../errors';
-import { CredentialStateChangeMessage, type CredentialStateChangeMessageOptions, IssuanceRequestMessage, OnboardingRequestMessage, OobLinkMessage, type OobLinkMessageOptions, ValidatingMessage, type ValidatingMessageOptions } from '../messages';
+import { CredentialStateChangeMessage, type CredentialStateChangeMessageOptions, IssuanceRequestMessage, OnboardingRequestMessage, OobLinkMessage, type OobLinkMessageOptions, VtFlowProblemReportMessage, ValidatingMessage, type ValidatingMessageOptions } from '../messages';
 import { VtFlowRecord, VtFlowRepository } from '../repository';
-import { VtFlowState } from '../types';
+import { type VtFlowMessage, type VtFlowValidation, VtFlowState } from '../types';
 export interface CreateOnboardingRequestParams {
     connectionId: string;
     participantSessionId: string;
-    participantId: string;
+    applicantParticipantId: string;
+    applicantParticipantRole?: number;
+    validatorParticipantId?: string;
+    schemaId?: string;
     agentParticipantId: string;
     walletAgentParticipantId: string;
     claims?: Record<string, unknown>;
@@ -50,20 +53,34 @@ export declare class VtFlowService {
         message: IssuanceRequestMessage;
         record: VtFlowRecord;
     }>;
+    reattachOnboardingProcessRecord(agentContext: AgentContext, params: {
+        vtFlowRecordId: string;
+        connectionId: string;
+    }): Promise<{
+        message: OnboardingRequestMessage;
+        record: VtFlowRecord;
+    }>;
+    private releaseCredentialExchange;
     /** Validator-side OnboardingProcess: create or re-attach (by `participant_session_id`) a record in `AWAITING_OR` from an inbound `onboarding-request`. */
     processReceiveOnboardingRequest(messageContext: DidCommInboundMessageContext<OnboardingRequestMessage>): Promise<VtFlowRecord>;
     /** Validator-side DirectIssuance counterpart of `processReceiveOnboardingRequest`, landing the record in `AWAITING_IR`. */
     processReceiveIssuanceRequest(messageContext: DidCommInboundMessageContext<IssuanceRequestMessage>): Promise<VtFlowRecord>;
-    /** 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`. */
     processReceiveOobLink(messageContext: DidCommInboundMessageContext<OobLinkMessage>): Promise<VtFlowRecord>;
-    /** Applicant-side inbound `validating`; OnboardingProcess applicant transitions `OR_SENT => VALIDATING`. */
+    /** Applicant-side inbound `validating`; `OR_SENT`, `IR_SENT` or `OOB_PENDING` => `VALIDATING`. */
     processReceiveValidating(messageContext: DidCommInboundMessageContext<ValidatingMessage>): Promise<VtFlowRecord>;
     /** Applicant-side inbound `credential-state-change`; v1.0 handles `REVOKED` only. */
     processReceiveCredentialStateChange(messageContext: DidCommInboundMessageContext<CredentialStateChangeMessage>): Promise<VtFlowRecord | null>;
     /** `AWAITING_OR => VALIDATING`; caller is expected to have verified participant/agent/wallet IDs on-chain. */
-    acceptOnboardingRequest(agentContext: AgentContext, recordId: string): Promise<VtFlowRecord>;
+    acceptOnboardingRequest(agentContext: AgentContext, recordId: string): Promise<{
+        record: VtFlowRecord;
+        message: ValidatingMessage;
+    }>;
     /** DirectIssuance: `AWAITING_IR => VALIDATING`; transient before `CRED_OFFERED`. */
-    acceptIssuanceRequest(agentContext: AgentContext, recordId: string): Promise<VtFlowRecord>;
+    acceptIssuanceRequest(agentContext: AgentContext, recordId: string): Promise<{
+        record: VtFlowRecord;
+        message: ValidatingMessage;
+    }>;
     /** Reject with a problem-report; transitions to `TERMINATED_BY_{role}` and marks the connection as `TERMINATED`. */
     rejectRequest(agentContext: AgentContext, recordId: string, params: RejectRequestParams): Promise<{
         record: VtFlowRecord;
@@ -88,20 +105,33 @@ export declare class VtFlowService {
         record: VtFlowRecord;
         problemReport: ReturnType<typeof buildVtFlowProblemReport>;
     }>;
-    /** 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`. */
     sendOobLinkForSession(agentContext: AgentContext, recordId: string, params: SendOobLinkParams): Promise<{
         record: VtFlowRecord;
         message: OobLinkMessage;
     }>;
-    /** 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. */
     sendValidatingForSession(agentContext: AgentContext, recordId: string, params?: SendValidatingParams): Promise<{
         record: VtFlowRecord;
         message: ValidatingMessage;
     }>;
-    /** `VALIDATING => VALIDATED`; call after `SetParticipantOPtoValidated` lands on-chain. */
+    /** Record the validation decision or its transaction outcome, moving the flow when `state` is given. */
+    recordValidation(agentContext: AgentContext, recordId: string, validation: VtFlowValidation, state?: VtFlowState): Promise<VtFlowRecord>;
+    /** Validator-side states preceding `VALIDATED` => `VALIDATED`; call after `SetParticipantOPtoValidated` lands on-chain. */
     markValidated(agentContext: AgentContext, recordId: string): Promise<VtFlowRecord>;
+    /**
+     * 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.
+     */
+    markCompleted(agentContext: AgentContext, recordId: string): Promise<VtFlowRecord>;
+    /** Validator states that an `offer-credential` moves to `CRED_OFFERED`; from `COMPLETED` it starts a new subprotocol run. */
+    assertCanOfferCredential(record: VtFlowRecord): void;
     /** Link a Credo exchange record to the session and transition to `CRED_OFFERED`. */
     attachCredentialExchangeRecord(agentContext: AgentContext, recordId: string, credentialExchangeRecord: DidCommCredentialExchangeRecord, credentialDigest?: string, issuerParticipantId?: number): Promise<VtFlowRecord>;
+    setEcsSchemaKey(agentContext: AgentContext, recordId: string, ecsSchemaKey: string): Promise<VtFlowRecord>;
     setCredentialDigest(agentContext: AgentContext, recordId: string, credentialDigest: string): Promise<VtFlowRecord>;
     /** Validator-side `credential-state-change`; `COMPLETED => CRED_REVOKED`, re-notify allowed from `CRED_REVOKED`. */
     notifyCredentialStateChange(agentContext: AgentContext, recordId: string, params: NotifyCredentialStateChangeParams): Promise<{
@@ -119,6 +149,16 @@ export declare class VtFlowService {
     findAllByQuery(agentContext: AgentContext, query: Query<VtFlowRecord>, queryOptions?: QueryOptions): Promise<VtFlowRecord[]>;
     /** Transition the record, persist it, and emit `VtFlowStateChanged`. */
     updateState(agentContext: AgentContext, record: VtFlowRecord, newState: VtFlowState): Promise<void>;
+    /**
+     * 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.
+     */
+    processReceiveProblemReport(messageContext: DidCommInboundMessageContext<VtFlowProblemReportMessage>): Promise<VtFlowRecord | undefined>;
+    /** `terminated-by-sender` is the peer's termination, so the receiver lands in the state named after the sender. */
+    private resolveErrorFlowState;
+    /** Append to `messages[]`, which a validator fills with what it sent and an applicant with what it received. */
+    appendMessage(record: VtFlowRecord, message: VtFlowMessage): void;
     /** Persist record changes without state-transition semantics (no event emitted). */
     updateRecord(agentContext: AgentContext, record: VtFlowRecord): Promise<void>;
     /** participant_session_ids are public on-chain, so only the original peer may re-attach a flow with one. */
@@ -126,7 +166,8 @@ export declare class VtFlowService {
     private emitStateChanged;
     getModuleConfig(): VtFlowModuleConfig;
     getLogger(): Logger;
-    buildProblemReport(options: BuildVtFlowProblemReportOptions): import("@credo-ts/didcomm").DidCommProblemReportMessage;
-    /** 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. */
-    checkIsVerifiableService(agentContext: AgentContext, connection: DidCommConnectionRecord): Promise<void>;
+    buildProblemReport(options: BuildVtFlowProblemReportOptions): VtFlowProblemReportMessage;
+    /** 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. */
+    checkIsVerifiableService(agentContext: AgentContext, connection: DidCommConnectionRecord, purpose?: VtFlowRequestPurpose): Promise<void>;
+    private isExemptFromVsConnVs;
 }

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,
@@ -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,28 +96,79 @@ 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;
+    }
     /** 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);
+        await this.checkIsVerifiableService(agentContext, connection, { participantId: message.participantId });
         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`);
             }
+            if (existing.applicantParticipantId !== message.participantId) {
+                throw new core_1.CredoError(`vt-flow: participant_id '${message.participantId}' 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 (message.claims)
-                existing.claims = message.claims;
-            if (message.proofsAttach)
-                existing.proofsAttach = message.proofsAttach;
+            if (existing.threadId !== message.threadId) {
+                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) {
                 // 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;
                 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);
             }
@@ -128,7 +183,7 @@ let VtFlowService = class VtFlowService {
             variant: types_1.VtFlowVariant.OnboardingProcess,
             agentParticipantId: message.agentParticipantId,
             walletAgentParticipantId: message.walletAgentParticipantId,
-            participantId: message.participantId,
+            applicantParticipantId: message.participantId,
             claims: message.claims,
             proofsAttach: message.proofsAttach,
         });
@@ -140,16 +195,25 @@ let VtFlowService = class VtFlowService {
     async processReceiveIssuanceRequest(messageContext) {
         const { message, agentContext } = messageContext;
         const connection = messageContext.assertReadyConnection();
-        await this.checkIsVerifiableService(agentContext, connection);
+        await this.checkIsVerifiableService(agentContext, connection, { schemaId: message.schemaId });
         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`);
             }
+            if (existing.variant !== types_1.VtFlowVariant.DirectIssuance || existing.schemaId !== message.schemaId) {
+                throw new core_1.CredoError(`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;
-            await this.repository.update(agentContext, existing);
+            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;
         }
         const record = new repository_1.VtFlowRecord({
@@ -168,25 +232,51 @@ let VtFlowService = class VtFlowService {
         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;
         messageContext.assertReadyConnection();
         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 && message.comment) {
+            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 &&
-            record.variant === types_1.VtFlowVariant.OnboardingProcess &&
-            record.state === types_1.VtFlowState.OrSent) {
+            [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;
@@ -215,7 +305,7 @@ let VtFlowService = class VtFlowService {
         record.assertState(types_1.VtFlowState.AwaitingOr);
         record.assertVariant(types_1.VtFlowVariant.OnboardingProcess);
         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,7 +314,7 @@ 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`. */
     async rejectRequest(agentContext, recordId, params) {
@@ -264,6 +354,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 fails, until verana-labs/vs-agent#738
+            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,
@@ -288,61 +389,104 @@ 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,
         });
+        if (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;
+    }
+    /** 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) {
+        const record = await this.repository.getById(agentContext, recordId);
+        this.assertCanOfferCredential(record);
         record.credentialExchangeRecordId = credentialExchangeRecord.id;
         if (credentialDigest)
             record.credentialDigest = credentialDigest;
@@ -352,6 +496,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 +531,7 @@ 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.Validating, types_1.VtFlowState.CredRevoked]);
         record.claims = claims;
         await this.updateRecord(agentContext, record);
         return record;
@@ -448,12 +599,69 @@ 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);
@@ -489,25 +697,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) {
-            throw new core_1.CredoError(`vt-flow.not-a-verifiable-service: peer '${peerDid}' failed VS-CONN-VS check`);
+        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 core_1.CredoError(`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 });
+        }
+        catch (error) {
+            this.logger.warn(`[vt-flow] VS-CONN-VS exemption check failed for peer '${peerDid}': ${error.message}`);
+            return false;
         }
     }
 };