@visa/cli 4.1.0-rc.11 → 4.1.0-rc.13

package/dist/checkout-engine/vgs-gateway/fetch-credential.mjs

@@ -0,0 +1,240 @@
+// Real credential fetch — NO mocks. Calls the live VGS agentic gateway to mint a
+// fresh, intent-scoped payment credential (DPAN + expiry + the 3-digit DAVV) and
+// returns it in memory. Same wire calls the enrollment harness (../server-e2e.mjs)
+// uses; this just returns the FULL values (for the form-filler) instead of masking.
+//
+// Nothing here persists or logs the credential — it is returned to the caller
+// (fillCheckout), and must never be written to disk or passed through an
+// LLM/agent context.
+//
+// Requires env: VGS_USERNAME, VGS_PASSWORD (the VGS service-account client id/secret),
+// and either VGS_ENVIRONMENT=live (+ optional VGS_GATEWAY_URL) or sandbox.
+
+const TOKEN_URL = 'https://auth.verygoodsecurity.com/auth/realms/vgs/protocol/openid-connect/token'
+
+function gatewayBase(env = process.env) {
+  if (env.VGS_GATEWAY_URL) return env.VGS_GATEWAY_URL.replace(/\/$/, '')
+  return env.VGS_ENVIRONMENT === 'live'
+    ? 'https://gw-01-live.vgsapi.com'
+    : 'https://gw-01-sandbox.vgsapi.com'
+}
+
+async function mintOauthToken(env = process.env) {
+  const clientId = env.VGS_USERNAME
+  const clientSecret = env.VGS_PASSWORD
+  if (!clientId || !clientSecret) {
+    throw new Error('Set VGS_USERNAME and VGS_PASSWORD (the VGS service-account client id/secret).')
+  }
+  const body = new URLSearchParams({
+    client_id: clientId,
+    client_secret: clientSecret,
+    grant_type: 'client_credentials',
+  })
+  const r = await fetch(TOKEN_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body,
+  })
+  if (!r.ok) throw new Error(`VGS token grant failed (${r.status}).`)
+  return (await r.json()).access_token
+}
+
+async function postJsonApi(url, type, attributes, env = process.env) {
+  const token = await mintOauthToken(env)
+  const r = await fetch(url, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/vnd.api+json',
+    },
+    body: JSON.stringify({ data: { ...(type ? { type } : {}), attributes } }),
+  })
+  const text = await r.text()
+  let doc = {}
+  try {
+    doc = JSON.parse(text)
+  } catch {
+    /* non-json error body */
+  }
+  // Support trace handles VGS asked for on the #5713 decline thread: trace_id
+  // keys the request on VGS's side, network_correlation_id on the Visa network
+  // side. Routing metadata only — never credential material — and logged even
+  // on error responses so any run stays traceable after the fact.
+  const obs = doc?.meta?.observability
+  if (obs && typeof obs === 'object') {
+    console.info(
+      JSON.stringify({
+        op: 'vgs_observability',
+        type,
+        status: r.status,
+        trace_id: obs.trace_id,
+        vault_id: obs.vault_id,
+        network_correlation_id: obs.network_correlation_id,
+      })
+    )
+  }
+  if (!r.ok) {
+    // Never echo the full body (can carry ids); surface status + a short detail.
+    const detail = doc?.errors?.[0]?.detail || doc?.errors?.[0]?.title || ''
+    throw new Error(`VGS ${type} POST failed (${r.status})${detail ? `: ${detail}` : ''}.`)
+  }
+  return doc
+}
+
+const txnData = (t) => [
+  {
+    merchant_name: t.merchantName,
+    merchant_url: t.merchantUrl,
+    merchant_country_code: t.merchantCountryCode,
+    transaction_amount: {
+      transaction_amount: t.transactionAmount,
+      transaction_currency_code: t.transactionCurrencyCode,
+    },
+  },
+]
+
+/**
+ * Create a fresh intent scoped to `transaction`, bound to the passkey assurance.
+ * Needs `assuranceData` from a device-binding passkey ceremony run for THIS
+ * purchase (merchant + amount + currency aligned) — replaying enrollment-time
+ * assurance mints an intent that 201s but whose cryptogram never completes
+ * (#5709, confirmed live 2026-07-17).
+ * @returns {Promise<{intentId: string, status: string | null}>} the fresh
+ * intent id plus the creation-time status attribute (null when VGS omits it) —
+ * callers surface the status when a later cryptogram fails, since HTTP 201
+ * alone does not mean the intent is authorized.
+ */
+export async function createIntent({ tokenId, assuranceData, transaction }, env = process.env) {
+  const effectiveUntil = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString()
+  const cap = Math.max(Math.ceil(Number(transaction.transactionAmount) || 0) + 10, 25)
+  const doc = await postJsonApi(
+    `${gatewayBase(env)}/agentic-tokens/${encodeURIComponent(tokenId)}/intents`,
+    'intents',
+    {
+      consumer_prompt: `Buy an item from ${transaction.merchantName} for ${transaction.transactionCurrencyCode} ${transaction.transactionAmount}`,
+      assurance_data: assuranceData,
+      mandates: [
+        {
+          description: `Purchase at ${transaction.merchantName}`,
+          decline_threshold: { amount: cap, currency_code: transaction.transactionCurrencyCode },
+          effective_until: effectiveUntil,
+          merchant_category: 'Retail',
+          merchant_category_code: '5999',
+          preferred_merchant_name: transaction.merchantName,
+          quantity: 1,
+        },
+      ],
+    },
+    env
+  )
+  const intentId = doc.data?.id
+  if (!intentId) throw new Error('createIntent: response missing data.id')
+  const status = doc.data?.attributes?.status
+  return { intentId, status: typeof status === 'string' && status ? status : null }
+}
+
+/**
+ * Mint the FULL payment credential for an existing intent. Real VGS call — the
+ * DAVV is single-use and expires in hours, so call this immediately before fill.
+ * @returns {Promise<{networkToken,expMonth,expYear,cryptogramType,cryptogramValue}>}
+ */
+export async function fetchCryptogram({ tokenId, intentId, transaction }, env = process.env) {
+  // Intent approval can be asynchronous on live: creation returns PENDING and
+  // the first cryptogram answer can be PENDING too (observed 2026-07-17,
+  // donate.stripe.com run). Poll briefly on PENDING only — every other
+  // non-COMPLETED status still fails fast on the first answer. Both knobs are
+  // env-tunable (and injectable for tests, which must not sleep wall-clock).
+  const PENDING_ATTEMPTS = Math.max(1, Number(env.VGS_CRYPTOGRAM_PENDING_ATTEMPTS) || 4)
+  const PENDING_WAIT_MS = Number.isFinite(Number(env.VGS_CRYPTOGRAM_PENDING_WAIT_MS))
+    ? Number(env.VGS_CRYPTOGRAM_PENDING_WAIT_MS)
+    : 5000
+  let a = {}
+  for (let attempt = 1; ; attempt++) {
+    const doc = await postJsonApi(
+      `${gatewayBase(env)}/agentic-tokens/${encodeURIComponent(tokenId)}/intents/${encodeURIComponent(intentId)}/cryptograms`,
+      'cryptograms',
+      { transaction_data: txnData(transaction) },
+      env
+    )
+    a = doc.data?.attributes ?? {}
+    const s = typeof a.status === 'string' ? a.status.toUpperCase() : ''
+    if (s !== 'PENDING' || attempt >= PENDING_ATTEMPTS) break
+    console.info(
+      JSON.stringify({ op: 'cryptogram_pending_retry', attempt, waitMs: PENDING_WAIT_MS })
+    )
+    await new Promise((resolve) => setTimeout(resolve, PENDING_WAIT_MS))
+  }
+  // A network_token can come back while the cryptogram is still pending/failed —
+  // mirror lib/server/vgs.ts and reject anything not COMPLETED, so we never key a
+  // not-yet-valid credential (which would decline and read as a fill bug).
+  const status = a.status
+  if (typeof status === 'string' && status && status.toUpperCase() !== 'COMPLETED') {
+    throw new Error(`cryptogram not completed (status ${status})`)
+  }
+  const networkToken = a.network_token
+  const value = a.cryptogram?.value
+  if (typeof networkToken !== 'string' || !networkToken) {
+    throw new Error('cryptogram response missing network_token')
+  }
+  if (typeof value !== 'string' || !value) {
+    throw new Error('cryptogram response missing cryptogram value')
+  }
+  return {
+    networkToken,
+    expMonth: typeof a.exp_month === 'number' ? a.exp_month : Number(a.exp_month) || 0,
+    expYear: typeof a.exp_year === 'number' ? a.exp_year : Number(a.exp_year) || 0,
+    cryptogramType: a.cryptogram?.type ?? '',
+    cryptogramValue: value,
+    cryptogramExpiresAt:
+      typeof a.cryptogram?.expires_at === 'string' ? a.cryptogram.expires_at : undefined,
+  }
+}
+
+/**
+ * Full path: create the intent (needs fresh passkey assurance) then mint the
+ * credential. Use fetchCryptogram directly if you already have an intentId.
+ */
+export async function getCredential({ tokenId, assuranceData, transaction }, env = process.env) {
+  const { intentId, status } = await createIntent({ tokenId, assuranceData, transaction }, env)
+  try {
+    return await fetchCryptogram({ tokenId, intentId, transaction }, env)
+  } catch (err) {
+    // HTTP 201 on intent creation does not mean the intent was authorized —
+    // surface its creation-time status so a not-completed cryptogram is
+    // diagnosable (#5709) instead of an opaque failure.
+    throw new Error(`${err.message} (intent status at creation: ${status ?? 'unknown'})`)
+  }
+}
+
+/**
+ * Report the observed merchant outcome back to VIC for a consumed intent.
+ * Mirrors lib/server/vgs.ts postConfirmation exactly: same endpoint, same
+ * JSON:API envelope, and the guide's quoted Unix-epoch-seconds timestamp
+ * (callers pass ISO 8601; converted here).
+ */
+export async function postConfirmation(
+  { tokenId, intentId, transactionStatus, transactionType, transactionTimestamp, transaction },
+  env = process.env
+) {
+  await postJsonApi(
+    `${gatewayBase(env)}/agentic-tokens/${encodeURIComponent(tokenId)}/intents/${encodeURIComponent(intentId)}/confirmations`,
+    'confirmations',
+    {
+      confirmation_data: [
+        {
+          payment_confirmation_data: {
+            transaction_status: transactionStatus,
+            transaction_type: transactionType,
+            transaction_timestamp: String(Math.floor(Date.parse(transactionTimestamp) / 1000)),
+            transaction_amount: {
+              transaction_amount: transaction.transactionAmount,
+              transaction_currency_code: transaction.transactionCurrencyCode,
+            },
+          },
+        },
+      ],
+    },
+    env
+  )
+  return { ok: true }
+}

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

@@ -0,0 +1,141 @@
+import type { CardCredential, Instrument, InstrumentContext } from './instrument.js';
+export type VgsCheckoutReference = {
+    tokenId: string;
+    intentId: string;
+    merchantName: string;
+    merchantUrl: string;
+    merchantCountryCode: string;
+    transactionAmount: string;
+    transactionCurrencyCode: string;
+};
+export type VgsCheckoutTarget = Omit<VgsCheckoutReference, 'tokenId' | 'intentId'>;
+export type CliAgentCredential = {
+    tokenId: string;
+    /** Present only in artifacts claimed by older CLI versions — never read
+     * here: enrollment-time assurance is not purchase authorization (#5709),
+     * and current CLIs no longer persist it at all. */
+    assuranceData?: unknown;
+    name?: string;
+    agentJkt?: string;
+    claimedAt?: string;
+    source?: string;
+};
+/**
+ * Fresh, purchase-scoped assurance from a device-binding passkey ceremony run
+ * for THIS purchase. Issue #5709 (confirmed live 2026-07-17): VGS accepts an
+ * intent minted from the enrollment-time assurance — and even from a fresh
+ * assurance scoped to a DIFFERENT merchant — but the cryptogram then
+ * deterministically never completes. Only a ceremony scoped to the actual
+ * merchant + amount + currency yields a payable credential, so the declared
+ * scope here is validated against the checkout target before any intent is
+ * minted, and the enrollment artifact's stored assurance is never used as
+ * purchase authorization.
+ */
+export type PurchaseAssurance = {
+    /** Opaque VgsAgenticAuth output — never inspected, only forwarded. */
+    assuranceData: unknown;
+    /** ISO 8601 completion time of the ceremony this assurance came from. */
+    mintedAt: string;
+    /** Host of the merchant checkout URL the ceremony was scoped to. */
+    merchantHost: string;
+    /** Decimal major-unit amount the ceremony was scoped to. */
+    transactionAmount: string;
+    /** ISO 4217 currency the ceremony was scoped to. */
+    transactionCurrencyCode: string;
+};
+/**
+ * Our fail-closed freshness bound, matching the runner's 15-minute checkout
+ * review window — NOT a claim about VGS's actual assurance TTL (unpublished).
+ * The only proven-working configuration mints the intent right after the
+ * ceremony; anything older is refused before an intent is created.
+ */
+export declare const PURCHASE_ASSURANCE_MAX_AGE_MS: number;
+export type VgsPaymentCredential = {
+    networkToken: string;
+    expMonth: number;
+    expYear: number;
+    cryptogramType: string;
+    cryptogramValue: string;
+    cryptogramExpiresAt?: string;
+};
+export type FetchVgsPaymentCredential = (input: {
+    tokenId: string;
+    intentId: string;
+    transaction: {
+        merchantName: string;
+        merchantUrl: string;
+        merchantCountryCode: string;
+        transactionAmount: string;
+        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;
+    intentId: string;
+};
+export declare function decimalToMinor(value: unknown): number | null;
+/**
+ * Refuse to mint an intent unless the assurance is fresh and its declared
+ * scope matches the checkout target exactly. `now` is injectable so the
+ * freshness rules are testable with a pinned clock (same pattern as
+ * validateCredential).
+ */
+export declare function validatePurchaseAssurance(value: PurchaseAssurance, target: VgsCheckoutTarget, now?: Date): void;
+export declare function validateCredential(value: VgsPaymentCredential, now?: Date): void;
+/**
+ * Mints the full DPAN + short DAVV only after the executor revalidates the
+ * reviewed merchant, amount, and currency. The payment credential remains in
+ * memory, is never returned to the caller, and can be requested only once.
+ */
+export declare class VgsLiveInstrument implements Instrument {
+    private readonly reference;
+    private readonly cardholderName;
+    private readonly fetchCredential;
+    readonly kind: "agentic-token";
+    private used;
+    private minted;
+    constructor(reference: VgsCheckoutReference, cardholderName: string, fetchCredential: FetchVgsPaymentCredential);
+    /**
+     * Non-null once VGS has actually issued a credential (the intent is consumed
+     * from that moment, even if local validation later rejects the credential) —
+     * exactly the population a VIC confirmation can be owed for.
+     */
+    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

@@ -0,0 +1,252 @@
+/**
+ * Our fail-closed freshness bound, matching the runner's 15-minute checkout
+ * review window — NOT a claim about VGS's actual assurance TTL (unpublished).
+ * The only proven-working configuration mints the intent right after the
+ * ceremony; anything older is refused before an intent is created.
+ */
+export const PURCHASE_ASSURANCE_MAX_AGE_MS = 15 * 60 * 1000;
+/** Tolerated forward clock skew on `mintedAt` before it is treated as invalid. */
+const PURCHASE_ASSURANCE_MAX_SKEW_MS = 2 * 60 * 1000;
+export function decimalToMinor(value) {
+    // JSON files routinely carry a number where the contract says decimal string
+    // ("transactionAmount": 5): refuse non-strings HERE so every caller surfaces
+    // its scoped invalid/mismatch remedy instead of a raw TypeError crash.
+    if (typeof value !== 'string')
+        return null;
+    if (!/^\d+(\.\d{1,2})?$/.test(value))
+        return null;
+    const [whole, fraction = ''] = value.split('.');
+    const minor = Number(whole) * 100 + Number(fraction.padEnd(2, '0'));
+    return Number.isSafeInteger(minor) ? minor : null;
+}
+function validateTarget(reference, ctx) {
+    if (typeof reference.merchantName !== 'string' ||
+        typeof reference.merchantCountryCode !== 'string' ||
+        !reference.merchantName.trim() ||
+        !/^[A-Z]{2}$/.test(reference.merchantCountryCode)) {
+        throw new Error('VGS checkout reference merchant name/country is invalid');
+    }
+    let referenceHost;
+    try {
+        referenceHost = new URL(reference.merchantUrl).hostname;
+    }
+    catch {
+        throw new Error('VGS checkout reference merchant URL is invalid');
+    }
+    if (referenceHost !== ctx.merchantHost) {
+        throw new Error(`VGS credential merchant mismatch: ${referenceHost} vs ${ctx.merchantHost}`);
+    }
+    const amountMinor = decimalToMinor(reference.transactionAmount);
+    if (amountMinor === null)
+        throw new Error('VGS checkout reference amount is invalid');
+    if (amountMinor !== ctx.amountMinor) {
+        throw new Error(`VGS credential amount mismatch: ${amountMinor} vs ${ctx.amountMinor} minor units`);
+    }
+    // String() so a JSON-number currency (840) mismatches with a readable
+    // message instead of crashing on .toUpperCase().
+    const currency = String(reference.transactionCurrencyCode).toUpperCase();
+    if (currency !== ctx.currency) {
+        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
+ * freshness rules are testable with a pinned clock (same pattern as
+ * validateCredential).
+ */
+export function validatePurchaseAssurance(value, target, now = new Date()) {
+    const remedy = 'run a fresh device-binding ceremony scoped to this exact merchant, amount, and ' +
+        'currency, and pass its output via --purchase-assurance-file (#5709)';
+    if (value == null || typeof value !== 'object') {
+        throw new Error(`purchase assurance is missing — ${remedy}`);
+    }
+    if (value.assuranceData == null) {
+        throw new Error(`purchase assurance requires assuranceData — ${remedy}`);
+    }
+    const mintedAtMs = typeof value.mintedAt === 'string' ? Date.parse(value.mintedAt) : NaN;
+    if (!Number.isFinite(mintedAtMs)) {
+        throw new Error(`purchase assurance requires an ISO 8601 mintedAt — ${remedy}`);
+    }
+    const age = now.getTime() - mintedAtMs;
+    if (age < -PURCHASE_ASSURANCE_MAX_SKEW_MS) {
+        throw new Error(`purchase assurance mintedAt is in the future — ${remedy}`);
+    }
+    if (age > PURCHASE_ASSURANCE_MAX_AGE_MS) {
+        throw new Error(`purchase assurance is stale (minted ${value.mintedAt}, limit ` +
+            `${PURCHASE_ASSURANCE_MAX_AGE_MS / 60000} minutes) — ${remedy}`);
+    }
+    let targetHost;
+    try {
+        targetHost = new URL(target.merchantUrl).hostname;
+    }
+    catch {
+        throw new Error('VGS checkout reference merchant URL is invalid');
+    }
+    if (value.merchantHost !== targetHost) {
+        throw new Error(`purchase assurance merchant mismatch: ${value.merchantHost} vs ${targetHost} — ${remedy}`);
+    }
+    const assuranceMinor = decimalToMinor(value.transactionAmount);
+    const targetMinor = decimalToMinor(target.transactionAmount);
+    if (assuranceMinor === null || assuranceMinor !== targetMinor) {
+        throw new Error(`purchase assurance amount mismatch: ${value.transactionAmount} vs ` +
+            `${target.transactionAmount} — ${remedy}`);
+    }
+    if (typeof value.transactionCurrencyCode !== 'string' ||
+        value.transactionCurrencyCode.toUpperCase() !==
+            String(target.transactionCurrencyCode).toUpperCase()) {
+        throw new Error(`purchase assurance currency mismatch: ${value.transactionCurrencyCode} vs ` +
+            `${target.transactionCurrencyCode} — ${remedy}`);
+    }
+}
+// `now` is injectable so expiry rules are testable with a pinned clock.
+export function validateCredential(value, now = new Date()) {
+    if (!/^\d{12,19}$/.test(value.networkToken)) {
+        throw new Error('VGS credential network token must contain 12-19 digits');
+    }
+    if (!/^\d{3,4}$/.test(value.cryptogramValue)) {
+        throw new Error('VGS credential short DAVV must contain 3-4 digits');
+    }
+    if (typeof value.cryptogramType !== 'string' || value.cryptogramType.toUpperCase() !== 'DAVV') {
+        throw new Error(`VGS credential type ${value.cryptogramType || '<missing>'} is not DAVV`);
+    }
+    if (!Number.isInteger(value.expMonth) || value.expMonth < 1 || value.expMonth > 12) {
+        throw new Error('VGS credential expiration month is invalid');
+    }
+    if (!Number.isInteger(value.expYear) ||
+        value.expYear < now.getFullYear() ||
+        (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');
+        }
+    }
+}
+/**
+ * Mints the full DPAN + short DAVV only after the executor revalidates the
+ * reviewed merchant, amount, and currency. The payment credential remains in
+ * memory, is never returned to the caller, and can be requested only once.
+ */
+export class VgsLiveInstrument {
+    reference;
+    cardholderName;
+    fetchCredential;
+    kind = 'agentic-token';
+    used = false;
+    minted = null;
+    constructor(reference, cardholderName, fetchCredential) {
+        this.reference = reference;
+        this.cardholderName = cardholderName;
+        this.fetchCredential = fetchCredential;
+    }
+    /**
+     * Non-null once VGS has actually issued a credential (the intent is consumed
+     * from that moment, even if local validation later rejects the credential) —
+     * exactly the population a VIC confirmation can be owed for.
+     */
+    confirmationTarget() {
+        return this.minted;
+    }
+    async getCredential(ctx) {
+        if (this.used)
+            throw new Error('VGS live credential instrument is single-use');
+        this.used = true;
+        validateTarget(this.reference, ctx);
+        if (!this.reference.tokenId || !this.reference.intentId) {
+            throw new Error('VGS checkout reference requires tokenId and intentId');
+        }
+        if (!this.cardholderName.trim())
+            throw new Error('cardholder name is required');
+        const { tokenId, intentId, ...transaction } = this.reference;
+        const value = await this.fetchCredential({ tokenId, intentId, transaction });
+        this.minted = { tokenId, intentId };
+        try {
+            validateCredential(value);
+        }
+        catch (err) {
+            // VGS already issued a cryptogram for this intent even though we refuse
+            // to fill it; "correct inputs and retry" would silently reuse a consumed
+            // intent, so steer the operator to a fresh one.
+            throw new Error(`${err.message} — a credential was issued by VGS but rejected locally; obtain a fresh intent before retrying`);
+        }
+        return {
+            pan: value.networkToken,
+            expMonth: value.expMonth,
+            expYear: value.expYear,
+            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 } : {}),
+        };
+    }
+}

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

@@ -0,0 +1,34 @@
+import type { CheckoutOutcome } from './executor.js';
+import type { VicConfirmationTarget } from './vgs-live-instrument.js';
+export type VicTransactionStatus = 'APPROVED' | 'DECLINED';
+export type PostVicConfirmation = (input: {
+    tokenId: string;
+    intentId: string;
+    transactionStatus: VicTransactionStatus;
+    transactionType: 'PURCHASE';
+    transactionTimestamp: string;
+    transaction: {
+        transactionAmount: string;
+        transactionCurrencyCode: string;
+    };
+}) => Promise<unknown>;
+export type VicConfirmationReport = {
+    posted: true;
+    transactionStatus: VicTransactionStatus;
+} | {
+    posted: false;
+    reason: string;
+};
+/** Definitive merchant answers map to a status; everything else maps to none. */
+export declare function outcomeToTransactionStatus(outcome: CheckoutOutcome): VicTransactionStatus | null;
+export declare function reportVicOutcome(input: {
+    target: VicConfirmationTarget | null;
+    outcome: CheckoutOutcome;
+    transaction: {
+        transactionAmount: string;
+        transactionCurrencyCode: string;
+    };
+    post: PostVicConfirmation;
+    /** Injectable for tests; defaults to now. */
+    timestamp?: Date;
+}): Promise<VicConfirmationReport>;