@visa/cli 4.1.0-rc.29 → 4.1.0-rc.291

package/dist/checkout-engine/vgs-gateway/server-mint-client.js

@@ -1,3 +1,4 @@
+import { createDecipheriv, createHash, verify, createPublicKey, diffieHellman, hkdfSync, } from 'node:crypto';
 // Server-side mint client (Phase 1) — the checkout runner mints the payment
 // credential by calling the verify-web deployment's gateway routes with a
 // short-lived, purpose-scoped MINT TOKEN, instead of holding the shared VGS
@@ -11,6 +12,7 @@
 // Request derivation here mirrors ../fetch-credential.mjs EXACTLY (mandate cap,
 // consumer prompt, PENDING retry cadence) — the only change is the transport:
 // verify-web routes + Bearer mint token, never the VGS gateway + VGS secret.
+import { traceHandleFields } from '../trace-handles.js';
 const defaultSleep = (ms) => new Promise((r) => {
     const t = setTimeout(r, ms);
     t.unref?.();
@@ -39,10 +41,100 @@ export function merchantOrigin(url) {
         return url;
     }
 }
-/** Read a stable, non-secret error message from a route's JSON body. */
+/**
+ * A definitive refusal from the cryptogram mint route — the request will not
+ * succeed if retried unchanged.
+ *
+ * `terminal` is the load-bearing field. Draw terminality used to be decided by
+ * regex over the error MESSAGE, which made it hostage to text nobody controls:
+ * this client now interpolates the provider's own `upstream_codes` into the
+ * message for diagnosability, and a provider identifier such as
+ * `request_timeout` would match the transient matcher's unanchored
+ * `tim(e|ed)-out` alternative — flipping a permanent 422 back to "transient",
+ * skipping markUnhonored, and stranding the mandate in the exact retry-forever
+ * loop this whole change exists to kill. Terminality is therefore carried
+ * structurally, and consumers must consult it BEFORE any message matching.
+ */
+export class ServerCryptogramRefusedError extends Error {
+    status;
+    terminal = true;
+    constructor(status, detail) {
+        super(`server cryptogram refused (${status}): ${detail}`);
+        this.name = 'ServerCryptogramRefusedError';
+        this.status = status;
+    }
+}
+async function readRouteErrorDoc(res) {
+    return (await res.json().catch(() => null));
+}
+function routeErrorMessage(res, doc) {
+    const base = doc?.error || doc?.error_code || `HTTP ${res.status}`;
+    // Carry the provider's own status and rejected-attribute identifiers into the
+    // message when the route reflected them. Without this the operator sees only
+    // our status and has to go log-diving to learn WHICH field the gateway
+    // objected to — the gap that left a live create_intent 422 undiagnosable.
+    const parts = [];
+    if (typeof doc?.upstream_status === 'number')
+        parts.push(`upstream_status=${doc.upstream_status}`);
+    if (Array.isArray(doc?.upstream_codes) && doc.upstream_codes.length > 0) {
+        parts.push(`upstream_codes=${doc.upstream_codes.join(',')}`);
+    }
+    return parts.length > 0 ? `${base} [${parts.join(' ')}]` : base;
+}
 async function routeError(res) {
-    const doc = (await res.json().catch(() => null));
-    return doc?.error || doc?.error_code || `HTTP ${res.status}`;
+    return routeErrorMessage(res, await readRouteErrorDoc(res));
+}
+const BOOTSTRAP_STATES = new Set([
+    'none',
+    'pending',
+    'created',
+    'ambiguous',
+    'conflict',
+    'unknown',
+]);
+function bootstrapStateOf(value) {
+    return typeof value === 'string' && BOOTSTRAP_STATES.has(value)
+        ? value
+        : 'unknown';
+}
+const SAFE_REQUEST_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+function requestIdOf(res, doc) {
+    const candidate = res?.headers.get('x-request-id') ?? doc?.request_id ?? null;
+    return typeof candidate === 'string' && SAFE_REQUEST_ID.test(candidate) ? candidate : null;
+}
+/**
+ * The budget-intent route's failure, kept structured (#8470). `status` 0 means
+ * the request never produced an HTTP response (network failure or abort), which
+ * is outcome-uncertain exactly like a 5xx: the server may have dispatched.
+ */
+export class ServerIntentError extends Error {
+    facts;
+    code = 'SERVER_INTENT_FAILED';
+    constructor(message, facts) {
+        super(message);
+        this.facts = facts;
+        this.name = 'ServerIntentError';
+    }
+}
+function serverIntentErrorFrom(res, doc) {
+    const errorCode = typeof doc?.error_code === 'string'
+        ? doc.error_code
+        : typeof doc?.error === 'string' && /^[a-z0-9_]{1,64}$/.test(doc.error)
+            ? doc.error
+            : null;
+    const outcome = doc?.outcome === 'uncertain' || doc?.outcome === 'not_created'
+        ? doc.outcome
+        : res.status >= 500 || res.status === 0
+            ? 'uncertain'
+            : 'not_created';
+    return new ServerIntentError(`server intent failed (${res.status}): ${routeErrorMessage(res, doc)}`, {
+        status: res.status,
+        errorCode,
+        retryable: doc?.retryable === true,
+        requestId: requestIdOf(res, doc),
+        bootstrapState: bootstrapStateOf(doc?.bootstrap_state),
+        outcome,
+    });
 }
 function bearer(mintToken) {
     return { 'content-type': 'application/json', authorization: `Bearer ${mintToken}` };
@@ -64,34 +156,92 @@ export async function serverCreateIntent(base, mintToken, input, deps = {}) {
     const effectiveUntil = override.effectiveUntil ?? new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString();
     const consumerPrompt = override.consumerPrompt ??
         `Buy an item from ${t.merchantName} for ${t.transactionCurrencyCode.toUpperCase()} ${t.transactionAmount}`;
-    const res = await fetchImpl(`${stripTrailingSlashes(base)}/api/vgs/intent`, {
-        method: 'POST',
-        headers: bearer(mintToken),
-        body: JSON.stringify({
-            tokenId,
-            consumerPrompt,
-            assuranceData,
-            mandates: [
-                {
-                    description: `Purchase at ${t.merchantName}`,
-                    declineThresholdAmount,
-                    declineThresholdCurrencyCode: t.transactionCurrencyCode.toUpperCase(),
-                    effectiveUntil,
-                    merchantCategory: 'Retail',
-                    merchantCategoryCode: '5999',
-                    preferredMerchantName: t.merchantName,
-                    quantity,
-                },
-            ],
-        }),
-    });
+    let res;
+    try {
+        res = await fetchImpl(`${stripTrailingSlashes(base)}/api/vgs/intent`, {
+            method: 'POST',
+            headers: bearer(mintToken),
+            body: JSON.stringify({
+                tokenId,
+                consumerPrompt,
+                assuranceData,
+                mandates: [
+                    {
+                        description: `Purchase at ${t.merchantName}`,
+                        declineThresholdAmount,
+                        declineThresholdCurrencyCode: t.transactionCurrencyCode.toUpperCase(),
+                        effectiveUntil,
+                        merchantCategory: 'Retail',
+                        merchantCategoryCode: '5999',
+                        preferredMerchantName: t.merchantName,
+                        quantity,
+                    },
+                ],
+            }),
+        });
+    }
+    catch (err) {
+        // No HTTP response at all: the request may or may not have reached the
+        // server, so this is outcome-uncertain, never a proven non-creation.
+        throw new ServerIntentError(`server intent failed (0): ${err instanceof Error ? err.message : String(err)}`, {
+            status: 0,
+            errorCode: null,
+            retryable: false,
+            requestId: null,
+            bootstrapState: 'unknown',
+            outcome: 'uncertain',
+        });
+    }
     if (!res.ok)
-        throw new Error(`server intent failed (${res.status}): ${await routeError(res)}`);
+        throw serverIntentErrorFrom(res, await readRouteErrorDoc(res));
     const doc = (await res.json().catch(() => null));
     if (!doc?.intentId)
         throw new Error('server intent response missing intentId');
     return { intentId: doc.intentId, status: typeof doc.status === 'string' ? doc.status : null };
 }
+/**
+ * Read the durable budget-bootstrap state for a budget mint token via
+ * GET {base}/api/vgs/intent (#8470). A `created` answer carries the intent the
+ * server already minted under this token, so the runner registers it instead
+ * of dispatching again; `pending` and `ambiguous` are never redispatched.
+ */
+export async function serverReadIntentBootstrap(base, mintToken, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    let res;
+    try {
+        res = await fetchImpl(`${stripTrailingSlashes(base)}/api/vgs/intent`, {
+            method: 'GET',
+            headers: bearer(mintToken),
+        });
+    }
+    catch (err) {
+        throw new ServerIntentError(`server intent status failed (0): ${err instanceof Error ? err.message : String(err)}`, {
+            status: 0,
+            errorCode: null,
+            retryable: true,
+            requestId: null,
+            bootstrapState: 'unknown',
+            outcome: 'unknown',
+        });
+    }
+    const doc = (await res.json().catch(() => null));
+    if (!res.ok) {
+        const error = serverIntentErrorFrom(res, doc);
+        throw new ServerIntentError(error.message.replace('server intent failed', 'server intent status failed'), {
+            ...error.facts,
+            retryable: error.facts.retryable || res.status === 503,
+            outcome: 'unknown',
+        });
+    }
+    const state = bootstrapStateOf(doc?.bootstrap_state);
+    const intentId = typeof doc?.intent?.intentId === 'string' && doc.intent.intentId ? doc.intent.intentId : null;
+    return {
+        state: state === 'created' && !intentId ? 'unknown' : state,
+        intentId,
+        intentStatus: typeof doc?.intent?.status === 'string' ? doc.intent.status : null,
+        requestId: requestIdOf(res, doc),
+    };
+}
 /**
  * Mint the FULL payment credential via POST {base}/api/vgs/payment-cryptogram.
  * The server's route does a SINGLE gateway call and 502s on a not-COMPLETED
@@ -144,11 +294,16 @@ export async function serverFetchCryptogram(base, mintToken, input, deps = {}) {
                 ...(typeof c.cryptogramExpiresAt === 'string'
                     ? { cryptogramExpiresAt: c.cryptogramExpiresAt }
                     : {}),
+                ...traceHandleFields(c),
             };
         }
         // A 4xx (bad request / binding refusal / auth) is terminal — never retry it.
-        if (res.status >= 400 && res.status < 500) {
-            throw new Error(`server cryptogram refused (${res.status}): ${await routeError(res)}`);
+        // 429 is the sole exception: it is an explicitly retryable 4xx, and treating
+        // it as terminal would let a transient rate limit permanently disable a
+        // healthy mandate. The route maps upstream rate limits to 503 today, so this
+        // is a guard against a future emitter, not a live path.
+        if (res.status >= 400 && res.status < 500 && res.status !== 429) {
+            throw new ServerCryptogramRefusedError(res.status, await routeError(res));
         }
         lastError = `${res.status}: ${await routeError(res)}`;
         if (attempt < attempts)
@@ -176,3 +331,163 @@ export async function serverPostConfirmation(base, mintToken, input, deps = {})
         throw new Error(`server confirmation failed (${res.status}): ${await routeError(res)}`);
     return { ok: true };
 }
+function cardEvidence(token, key, typ, fields) {
+    const fail = () => {
+        throw new Error('protected_card_evidence_invalid');
+    };
+    if (key.type !== 'public' ||
+        key.asymmetricKeyType !== 'ed25519' ||
+        typeof token !== 'string' ||
+        token.length > 16384)
+        return fail();
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return fail();
+    const jwk = key.export({ format: 'jwk' });
+    const kid = createHash('sha256')
+        .update(JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x }))
+        .digest('base64url');
+    const header = JSON.parse(Buffer.from(parts[0], 'base64url').toString());
+    const claims = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+    if (!header ||
+        Object.keys(header).sort().join(',') !== 'alg,kid,typ' ||
+        header.alg !== 'EdDSA' ||
+        header.typ !== typ ||
+        header.kid !== kid ||
+        !claims ||
+        Object.keys(claims).sort().join(',') !== fields.sort().join(',') ||
+        claims.v !== 1 ||
+        typeof claims.jti !== 'string' ||
+        !claims.jti ||
+        !Number.isSafeInteger(claims.iat) ||
+        !verify(null, Buffer.from(parts.slice(0, 2).join('.')), key, Buffer.from(parts[2], 'base64url')))
+        return fail();
+    return claims;
+}
+export async function serverFetchProtectedCryptogram(base, input, deps = {}) {
+    const hash = Buffer.from(input.requestHash, 'base64url');
+    if (hash.length !== 32 ||
+        hash.toString('base64url') !== input.requestHash ||
+        input.deliveryKey.type !== 'private' ||
+        input.deliveryKey.asymmetricKeyType !== 'x25519')
+        throw new Error('protected_card_delivery_key_invalid');
+    const response = await (deps.fetchImpl ?? fetch)(`${stripTrailingSlashes(base)}/api/vgs/payment-cryptogram`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-visa-card-protected': 'v1' },
+        body: JSON.stringify({
+            financialAdmission: input.financialAdmission,
+            request: input.request,
+        }),
+        redirect: 'error',
+    });
+    if (response.status === 202)
+        throw new Error('protected_card_recovery_pending');
+    if (!response.ok)
+        throw new Error(`protected_card_refused_${response.status}`);
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error('protected_card_response_invalid');
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const part = await reader.read();
+            if (part.done)
+                break;
+            size += part.value.byteLength;
+            if (size > 65536) {
+                await reader.cancel();
+                throw new Error('protected_card_response_invalid');
+            }
+            chunks.push(part.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const envelope = JSON.parse(Buffer.concat(chunks).toString());
+    if (!envelope ||
+        Object.keys(envelope).sort().join(',') !==
+            'acknowledgement,ciphertext,ephemeralPublicJwk,iv,outcome,tag,v' ||
+        envelope.v !== 1)
+        throw new Error('protected_card_response_invalid');
+    const coordinates = [
+        'v',
+        'aud',
+        'jti',
+        'attemptId',
+        'requestHash',
+        'admissionId',
+        'issuanceGeneration',
+        'iat',
+    ];
+    const outcome = cardEvidence(envelope.outcome, input.pins.executor, 'visa-card-delivery-outcome+jwt', [...coordinates, 'outcome', 'providerRef', 'credentialSha256']);
+    const ack = cardEvidence(envelope.acknowledgement, input.pins.issuer, 'visa-card-delivery-state+jwt', [...coordinates, 'action', 'outcomeHash', 'exp']);
+    const permit = JSON.parse(Buffer.from(input.financialAdmission.split('.')[1], 'base64url').toString());
+    const now = Math.floor(Date.now() / 1000);
+    if (outcome.aud !== 'urn:visa:authority:card-outcome' ||
+        outcome.outcome !== 'credential_observed' ||
+        outcome.requestHash !== input.requestHash ||
+        outcome.attemptId !== permit.attemptId ||
+        outcome.admissionId !== permit.jti ||
+        outcome.issuanceGeneration !== permit.issuanceGeneration ||
+        ack.aud !== 'urn:visa:executor:card-vic' ||
+        ack.action !== 'recover_only' ||
+        ack.requestHash !== outcome.requestHash ||
+        ack.attemptId !== outcome.attemptId ||
+        ack.admissionId !== outcome.admissionId ||
+        ack.issuanceGeneration !== outcome.issuanceGeneration ||
+        !Number.isSafeInteger(ack.exp) ||
+        ack.exp <= now ||
+        ack.iat > now + 5 ||
+        ack.exp <= ack.iat ||
+        ack.exp - ack.iat > 60 ||
+        ack.outcomeHash !== createHash('sha256').update(envelope.outcome).digest('base64url'))
+        throw new Error('protected_card_evidence_invalid');
+    const jwk = envelope.ephemeralPublicJwk;
+    if (!jwk ||
+        Object.keys(jwk).sort().join(',') !== 'crv,kty,x' ||
+        jwk.kty !== 'OKP' ||
+        jwk.crv !== 'X25519')
+        throw new Error('protected_card_response_invalid');
+    const decode = (value, size) => {
+        if (typeof value !== 'string')
+            throw new Error('protected_card_response_invalid');
+        const decoded = Buffer.from(value, 'base64url');
+        if (decoded.toString('base64url') !== value || (size !== undefined && decoded.length !== size))
+            throw new Error('protected_card_response_invalid');
+        return decoded;
+    };
+    decode(jwk.x, 32);
+    const shared = diffieHellman({
+        privateKey: input.deliveryKey,
+        publicKey: createPublicKey({ key: jwk, format: 'jwk' }),
+    });
+    const key = Buffer.from(hkdfSync('sha256', shared, hash, 'visa-card-delivery-v1', 32));
+    shared.fill(0);
+    let clear;
+    try {
+        const decipher = createDecipheriv('aes-256-gcm', key, decode(envelope.iv, 12));
+        decipher.setAAD(Buffer.from(input.requestHash));
+        decipher.setAuthTag(decode(envelope.tag, 16));
+        clear = Buffer.concat([decipher.update(decode(envelope.ciphertext)), decipher.final()]);
+        if (createHash('sha256').update(clear).digest('base64url') !== outcome.credentialSha256)
+            throw new Error('protected_card_credential_invalid');
+        const credential = JSON.parse(clear.toString());
+        if (!credential ||
+            typeof credential.networkToken !== 'string' ||
+            typeof credential.cryptogramValue !== 'string' ||
+            !Number.isInteger(credential.expMonth) ||
+            credential.expMonth < 1 ||
+            credential.expMonth > 12 ||
+            !Number.isInteger(credential.expYear) ||
+            credential.expYear < 2000 ||
+            typeof credential.cryptogramType !== 'string')
+            throw new Error('protected_card_credential_invalid');
+        return credential;
+    }
+    finally {
+        key.fill(0);
+        clear?.fill(0);
+    }
+}

package/dist/checkout-engine/vgs-live-instrument.d.ts

@@ -42,6 +42,15 @@ export type PurchaseAssurance = {
     transactionAmount: string;
     /** ISO 4217 currency the ceremony was scoped to. */
     transactionCurrencyCode: string;
+    /**
+     * True iff the approval server marked this token passkey-exempt ('otp'
+     * cardholder ID&V / 'none' — verified against the owner's account card
+     * record at complete-time): no ceremony ran, `assuranceData` is null by
+     * design, and the intent is minted without it (the signed mint token
+     * carries the same exemption for the server's own check). Absent/false →
+     * assuranceData is REQUIRED, exactly the historical contract.
+     */
+    assuranceExempt?: boolean;
 };
 /**
  * Our fail-closed freshness bound, matching the runner's 15-minute checkout
@@ -57,6 +66,8 @@ export type VgsPaymentCredential = {
     cryptogramType: string;
     cryptogramValue: string;
     cryptogramExpiresAt?: string;
+    vgsTraceId?: string;
+    networkCorrelationId?: string;
 };
 export type FetchVgsPaymentCredential = (input: {
     tokenId: string;
@@ -69,14 +80,6 @@ export type FetchVgsPaymentCredential = (input: {
         transactionCurrencyCode: string;
     };
 }) => Promise<VgsPaymentCredential>;
-export type MintFreshVgsPaymentCredential = (input: {
-    tokenId: string;
-    assuranceData: unknown;
-    transaction: VgsCheckoutTarget;
-}) => Promise<{
-    payment: VgsPaymentCredential;
-    intentId: string;
-}>;
 /** The (token, intent) pair a VIC confirmation is posted against. */
 export type VicConfirmationTarget = {
     tokenId: string;
@@ -139,30 +142,3 @@ export declare class VgsLiveInstrument implements Instrument {
     confirmationTarget(): VicConfirmationTarget | null;
     getCredential(ctx: InstrumentContext): Promise<CardCredential>;
 }
-/**
- * Consumes #5614's claimed CLI enrollment artifact (for the tokenId) plus a
- * FRESH purchase-scoped assurance, and creates a fresh, transaction-scoped VIC
- * intent + credential after checkout approval. This is the production-shaped
- * bridge; unlike VgsLiveInstrument it never needs a pre-created intent ID.
- *
- * The enrollment artifact's stored assuranceData is deliberately never sent:
- * replaying it makes intent creation succeed (HTTP 201) while the cryptogram
- * deterministically never completes — the #5709 dead end. Purchase
- * authorization is the fresh, merchant+amount+currency-scoped assurance,
- * validated against the checkout target BEFORE any intent is minted so a
- * doomed intent is never created.
- */
-export declare class VgsAssuranceInstrument implements Instrument {
-    private readonly enrollment;
-    private readonly purchase;
-    private readonly target;
-    private readonly cardholderName;
-    private readonly mintCredential;
-    readonly kind: "agentic-token";
-    private used;
-    private minted;
-    constructor(enrollment: CliAgentCredential, purchase: PurchaseAssurance, target: VgsCheckoutTarget, cardholderName: string, mintCredential: MintFreshVgsPaymentCredential);
-    /** See VgsLiveInstrument.confirmationTarget — same contract. */
-    confirmationTarget(): VicConfirmationTarget | null;
-    getCredential(ctx: InstrumentContext): Promise<CardCredential>;
-}

package/dist/checkout-engine/vgs-live-instrument.js

@@ -1,3 +1,4 @@
+import { traceHandleFields } from './trace-handles.js';
 /**
  * Our fail-closed freshness bound, matching the runner's 15-minute checkout
  * review window — NOT a claim about VGS's actual assurance TTL (unpublished).
@@ -86,13 +87,6 @@ function validateTarget(reference, ctx) {
         throw new Error(`VGS credential currency mismatch: ${currency} vs ${ctx.currency}`);
     }
 }
-function validateCliCredential(value) {
-    if (typeof value.tokenId !== 'string' || !value.tokenId.trim()) {
-        throw new Error('CLI agent credential requires tokenId');
-    }
-    // Deliberately no assuranceData requirement: the artifact's enrollment-time
-    // assurance is identity/enrollment material and is never read here (#5709).
-}
 /**
  * Refuse to mint an intent unless the assurance is fresh and its declared
  * scope matches the checkout target exactly. `now` is injectable so the
@@ -105,7 +99,10 @@ export function validatePurchaseAssurance(value, target, now = new Date()) {
     if (value == null || typeof value !== 'object') {
         throw new Error(`purchase assurance is missing — ${remedy}`);
     }
-    if (value.assuranceData == null) {
+    // A passkey-exempt approval (marked by the approval SERVER, never assumed
+    // locally) carries no assurance by design — every scope/freshness check
+    // below still applies to it unchanged.
+    if (value.assuranceData == null && value.assuranceExempt !== true) {
         throw new Error(`purchase assurance requires assuranceData — ${remedy}`);
     }
     const mintedAtMs = typeof value.mintedAt === 'string' ? Date.parse(value.mintedAt) : NaN;
@@ -162,13 +159,14 @@ export function validateCredential(value, now = new Date()) {
         (value.expYear === now.getFullYear() && value.expMonth < now.getMonth() + 1)) {
         throw new Error('VGS credential is expired');
     }
-    if (value.cryptogramExpiresAt !== undefined) {
-        const expiresAtMs = Date.parse(value.cryptogramExpiresAt);
-        if (!Number.isFinite(expiresAtMs))
-            throw new Error('VGS credential expiry is invalid');
-        if (expiresAtMs - now.getTime() < 60_000) {
-            throw new Error('VGS credential has less than 60 seconds of validity remaining');
-        }
+    if (value.cryptogramExpiresAt === undefined) {
+        throw new Error('VGS credential expiry is missing');
+    }
+    const expiresAtMs = Date.parse(value.cryptogramExpiresAt);
+    if (!Number.isFinite(expiresAtMs))
+        throw new Error('VGS credential expiry is invalid');
+    if (expiresAtMs - now.getTime() < 60_000) {
+        throw new Error('VGS credential has less than 60 seconds of validity remaining');
     }
 }
 /**
@@ -225,65 +223,7 @@ export class VgsLiveInstrument {
             cvc: value.cryptogramValue,
             cardholderName: this.cardholderName.trim(),
             ...(value.cryptogramExpiresAt ? { credentialExpiresAt: value.cryptogramExpiresAt } : {}),
-        };
-    }
-}
-/**
- * Consumes #5614's claimed CLI enrollment artifact (for the tokenId) plus a
- * FRESH purchase-scoped assurance, and creates a fresh, transaction-scoped VIC
- * intent + credential after checkout approval. This is the production-shaped
- * bridge; unlike VgsLiveInstrument it never needs a pre-created intent ID.
- *
- * The enrollment artifact's stored assuranceData is deliberately never sent:
- * replaying it makes intent creation succeed (HTTP 201) while the cryptogram
- * deterministically never completes — the #5709 dead end. Purchase
- * authorization is the fresh, merchant+amount+currency-scoped assurance,
- * validated against the checkout target BEFORE any intent is minted so a
- * doomed intent is never created.
- */
-export class VgsAssuranceInstrument {
-    enrollment;
-    purchase;
-    target;
-    cardholderName;
-    mintCredential;
-    kind = 'agentic-token';
-    used = false;
-    minted = null;
-    constructor(enrollment, purchase, target, cardholderName, mintCredential) {
-        this.enrollment = enrollment;
-        this.purchase = purchase;
-        this.target = target;
-        this.cardholderName = cardholderName;
-        this.mintCredential = mintCredential;
-    }
-    /** See VgsLiveInstrument.confirmationTarget — same contract. */
-    confirmationTarget() {
-        return this.minted;
-    }
-    async getCredential(ctx) {
-        if (this.used)
-            throw new Error('VGS assurance instrument is single-use');
-        this.used = true;
-        validateCliCredential(this.enrollment);
-        validateTarget(this.target, ctx);
-        validatePurchaseAssurance(this.purchase, this.target);
-        if (!this.cardholderName.trim())
-            throw new Error('cardholder name is required');
-        const { payment: value, intentId } = await this.mintCredential({
-            tokenId: this.enrollment.tokenId,
-            assuranceData: this.purchase.assuranceData,
-            transaction: this.target,
-        });
-        this.minted = { tokenId: this.enrollment.tokenId, intentId };
-        validateCredential(value);
-        return {
-            pan: value.networkToken,
-            expMonth: value.expMonth,
-            expYear: value.expYear,
-            cvc: value.cryptogramValue,
-            cardholderName: this.cardholderName.trim(),
-            ...(value.cryptogramExpiresAt ? { credentialExpiresAt: value.cryptogramExpiresAt } : {}),
+            ...traceHandleFields(value),
         };
     }
 }

package/dist/checkout-engine/vic-confirmation.d.ts

@@ -12,11 +12,29 @@ export type PostVicConfirmation = (input: {
         transactionCurrencyCode: string;
     };
 }) => Promise<unknown>;
+/**
+ * Why a confirmation was not posted, as a BOUNDED value rather than prose.
+ *
+ * `reason` below is a human sentence built for the local receipt; it embeds
+ * upstream error text and is useless as an aggregate. These three codes are the
+ * whole space, and they mean very different things:
+ *
+ *  - `outcome_not_definitive` — the merchant never gave a definitive answer, so
+ *    there is nothing truthful to report. Expected, not a fault.
+ *  - `no_credential_minted` — no VIC credential existed for this run, so there
+ *    is no intent to confirm against. Expected, not a fault.
+ *  - `post_failed` — we HAD a definitive outcome and an intent to report it
+ *    against, and the POST did not land. This one is a fault: the processor
+ *    lifecycle row is never written, so the purchase can never rank above the
+ *    platform's own record no matter how well it actually went.
+ */
+export type VicConfirmationSkipCode = 'outcome_not_definitive' | 'no_credential_minted' | 'post_failed';
 export type VicConfirmationReport = {
     posted: true;
     transactionStatus: VicTransactionStatus;
 } | {
     posted: false;
+    code: VicConfirmationSkipCode;
     reason: string;
 };
 /** Definitive merchant answers map to a status; everything else maps to none. */

package/dist/checkout-engine/vic-confirmation.js

@@ -11,12 +11,17 @@ export async function reportVicOutcome(input) {
     if (!transactionStatus) {
         return {
             posted: false,
+            code: 'outcome_not_definitive',
             reason: `outcome '${input.outcome}' is not a definitive merchant answer — ` +
                 'resolve it with the merchant, then post the confirmation manually',
         };
     }
     if (!input.target) {
-        return { posted: false, reason: 'no VIC credential was minted in this run' };
+        return {
+            posted: false,
+            code: 'no_credential_minted',
+            reason: 'no VIC credential was minted in this run',
+        };
     }
     try {
         await input.post({
@@ -32,8 +37,9 @@ export async function reportVicOutcome(input) {
     catch (err) {
         return {
             posted: false,
-            reason: `confirmation POST failed: ${err.message} — the merchant outcome stands; ` +
-                'retry the confirmation for this intent out-of-band',
+            code: 'post_failed',
+            reason: `confirmation POST failed: ${err.message} — the merchant-reported outcome ` +
+                'remains unverified; retry the confirmation for this intent out-of-band',
         };
     }
 }