@visa/cli 4.1.0-rc.2 → 4.1.0-rc.200

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

@@ -0,0 +1,218 @@
+// 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
+// service-account secret (the gateway client id/secret) on the machine.
+//
+// The mint token is issued at approval time (agent-approval/complete, which is
+// session + internal-tester + token-ownership gated) and released to this
+// runner by the claim leg. It is bound to the exact approved purchase, so these
+// calls can only mint the credential the human approved.
+//
+// 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?.();
+});
+function stripTrailingSlashes(value) {
+    let out = value;
+    while (out.endsWith('/'))
+        out = out.slice(0, -1);
+    return out;
+}
+/**
+ * The merchant ORIGIN (scheme + host) — not the full checkout URL. A merchant's
+ * identity is its origin; a real checkout URL can carry hundreds of chars of
+ * campaign/tracking query params. Confirmed live: an oversized `merchantUrl`
+ * (a ~280-char Wikimedia donation URL) makes the cryptogram mint fail downstream
+ * with a vague `502 "card network could not complete"`, while the same merchant
+ * with a trimmed URL mints fine. Sending the origin is both correct (that IS the
+ * merchant) and safely bounded. Falls back to the raw value if it does not parse
+ * — the mint must never throw here.
+ */
+export function merchantOrigin(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * 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;
+    }
+}
+/** Read a stable, non-secret error message from a route's JSON body. */
+async function routeError(res) {
+    const doc = (await res.json().catch(() => null));
+    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;
+}
+function bearer(mintToken) {
+    return { 'content-type': 'application/json', authorization: `Bearer ${mintToken}` };
+}
+/**
+ * Create a fresh intent via POST {base}/api/vgs/intent. The server holds the VGS
+ * credential and calls the gateway; we send the same mandate shape the local
+ * path built (cap = ceil(amount)+10, min 25; merchant category Retail/5999) —
+ * unless `input.mandate` overrides the threshold/quantity/window for the
+ * card-mandate (budget) layer.
+ */
+export async function serverCreateIntent(base, mintToken, input, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const { tokenId, assuranceData, transaction: t } = input;
+    const override = input.mandate ?? {};
+    const defaultCap = Math.max(Math.ceil(Number(t.transactionAmount) || 0) + 10, 25);
+    const declineThresholdAmount = override.declineThresholdAmount ?? String(defaultCap);
+    const quantity = override.quantity ?? 1;
+    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,
+                },
+            ],
+        }),
+    });
+    if (!res.ok)
+        throw new Error(`server intent failed (${res.status}): ${await routeError(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 };
+}
+/**
+ * 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
+ * (e.g. PENDING) cryptogram, but live intent approval is asynchronous and the
+ * first cryptogram answer can be PENDING (#5709). So we retry the route on any
+ * non-2xx up to PENDING_ATTEMPTS, matching fetch-credential.mjs's cadence
+ * exactly — a genuinely hard failure just surfaces after the same bounded wait.
+ * Re-POSTing for the same intentId is idempotent (mirrors the old client loop).
+ */
+export async function serverFetchCryptogram(base, mintToken, input, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const sleep = deps.sleep ?? defaultSleep;
+    const env = deps.env ?? process.env;
+    const attempts = Math.max(1, Number(env.VGS_CRYPTOGRAM_PENDING_ATTEMPTS) || 4);
+    const waitMs = Number.isFinite(Number(env.VGS_CRYPTOGRAM_PENDING_WAIT_MS))
+        ? Number(env.VGS_CRYPTOGRAM_PENDING_WAIT_MS)
+        : 5000;
+    const { tokenId, intentId, transaction: t } = input;
+    const body = JSON.stringify({
+        tokenId,
+        intentId,
+        transaction: {
+            merchantName: t.merchantName,
+            // Send the merchant ORIGIN, not the full (possibly huge) checkout URL — an
+            // oversized merchantUrl makes the downstream cryptogram mint 502 (proven live).
+            merchantUrl: merchantOrigin(t.merchantUrl),
+            merchantCountryCode: t.merchantCountryCode,
+            transactionAmount: t.transactionAmount,
+            transactionCurrencyCode: t.transactionCurrencyCode.toUpperCase(),
+        },
+    });
+    let lastError = 'unknown';
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        const res = await fetchImpl(`${stripTrailingSlashes(base)}/api/vgs/payment-cryptogram`, {
+            method: 'POST',
+            headers: bearer(mintToken),
+            body,
+        });
+        if (res.ok) {
+            const c = (await res.json().catch(() => null));
+            if (!c || typeof c.networkToken !== 'string' || typeof c.cryptogramValue !== 'string') {
+                throw new Error('server cryptogram response missing credential fields');
+            }
+            return {
+                networkToken: c.networkToken,
+                expMonth: Number(c.expMonth) || 0,
+                expYear: Number(c.expYear) || 0,
+                cryptogramType: c.cryptogramType ?? '',
+                cryptogramValue: c.cryptogramValue,
+                ...(typeof c.cryptogramExpiresAt === 'string'
+                    ? { cryptogramExpiresAt: c.cryptogramExpiresAt }
+                    : {}),
+                ...traceHandleFields(c),
+            };
+        }
+        // A 4xx (bad request / binding refusal / auth) is terminal — never retry it.
+        // 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)
+            await sleep(waitMs);
+    }
+    throw new Error(`server cryptogram not completed after ${attempts} attempts (last: ${lastError})`);
+}
+/** Report the observed merchant outcome via POST {base}/api/vgs/confirmation. */
+export async function serverPostConfirmation(base, mintToken, input, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const res = await fetchImpl(`${stripTrailingSlashes(base)}/api/vgs/confirmation`, {
+        method: 'POST',
+        headers: bearer(mintToken),
+        body: JSON.stringify({
+            tokenId: input.tokenId,
+            intentId: input.intentId,
+            transactionStatus: input.transactionStatus,
+            transactionType: input.transactionType,
+            transactionTimestamp: input.transactionTimestamp,
+            transactionAmount: input.transaction.transactionAmount,
+            transactionCurrencyCode: input.transaction.transactionCurrencyCode.toUpperCase(),
+        }),
+    });
+    if (!res.ok)
+        throw new Error(`server confirmation failed (${res.status}): ${await routeError(res)}`);
+    return { ok: true };
+}

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

@@ -0,0 +1,144 @@
+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;
+    /**
+     * 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
+ * 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;
+    vgsTraceId?: string;
+    networkCorrelationId?: string;
+};
+export type FetchVgsPaymentCredential = (input: {
+    tokenId: string;
+    intentId: string;
+    transaction: {
+        merchantName: string;
+        merchantUrl: string;
+        merchantCountryCode: string;
+        transactionAmount: string;
+        transactionCurrencyCode: string;
+    };
+}) => Promise<VgsPaymentCredential>;
+/** 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;
+/**
+ * Currencies whose minor unit is 1/100 of the major unit (2 decimal places).
+ * minorToDecimal's /100 + pad-to-2 rendering is ONLY correct for these. The
+ * card mandate path accepts any 3-letter ISO code, so a 0- or 3-decimal
+ * currency (JPY, BHD, …) would otherwise be emitted with a wrong wire amount.
+ * We only support USD/USDC today; extend deliberately (and fix the exponent)
+ * before adding any non-2-decimal currency.
+ *
+ * NOTE (scanner FP pre-empt): this is a CLIENT-SIDE currency-exponent lookup for
+ * rendering a wire amount in @visa/checkout-engine — it is NOT the cross-store
+ * `PAYMENT_CURRENCIES` enum governed by apps/auth/src/shared-validators.ts, and
+ * this package cannot import from apps/auth (no dependency edge). It intentionally
+ * does not mirror that enum's membership; do not "reconcile" the two.
+ */
+export declare const TWO_DECIMAL_CURRENCIES: Set<string>;
+/**
+ * Inverse of decimalToMinor: render integer minor units as a major-unit decimal
+ * string ("D.DD") for the VGS wire (e.g. a ceiling of 50000 minor → "500.00").
+ * Integer-only; never floating-point money. Throws on a non-integer/negative so
+ * a bad accounting value cannot silently reach the network.
+ *
+ * The /100 + pad-to-2 rendering assumes a 2-decimal (exponent-2) currency. Pass
+ * `currencyCode` on any path that accepts arbitrary currencies (the mandate
+ * path) and it REFUSES a non-2-decimal currency rather than emit a wrong wire
+ * amount. Omit it only where the currency is already known to be USD/USDC.
+ */
+export declare function minorToDecimal(minor: number, currencyCode?: string): string;
+/**
+ * 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>;
+}

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

@@ -0,0 +1,229 @@
+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).
+ * 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;
+}
+/**
+ * Currencies whose minor unit is 1/100 of the major unit (2 decimal places).
+ * minorToDecimal's /100 + pad-to-2 rendering is ONLY correct for these. The
+ * card mandate path accepts any 3-letter ISO code, so a 0- or 3-decimal
+ * currency (JPY, BHD, …) would otherwise be emitted with a wrong wire amount.
+ * We only support USD/USDC today; extend deliberately (and fix the exponent)
+ * before adding any non-2-decimal currency.
+ *
+ * NOTE (scanner FP pre-empt): this is a CLIENT-SIDE currency-exponent lookup for
+ * rendering a wire amount in @visa/checkout-engine — it is NOT the cross-store
+ * `PAYMENT_CURRENCIES` enum governed by apps/auth/src/shared-validators.ts, and
+ * this package cannot import from apps/auth (no dependency edge). It intentionally
+ * does not mirror that enum's membership; do not "reconcile" the two.
+ */
+export const TWO_DECIMAL_CURRENCIES = new Set(['USD', 'USDC']);
+/**
+ * Inverse of decimalToMinor: render integer minor units as a major-unit decimal
+ * string ("D.DD") for the VGS wire (e.g. a ceiling of 50000 minor → "500.00").
+ * Integer-only; never floating-point money. Throws on a non-integer/negative so
+ * a bad accounting value cannot silently reach the network.
+ *
+ * The /100 + pad-to-2 rendering assumes a 2-decimal (exponent-2) currency. Pass
+ * `currencyCode` on any path that accepts arbitrary currencies (the mandate
+ * path) and it REFUSES a non-2-decimal currency rather than emit a wrong wire
+ * amount. Omit it only where the currency is already known to be USD/USDC.
+ */
+export function minorToDecimal(minor, currencyCode) {
+    if (!Number.isSafeInteger(minor) || minor < 0) {
+        throw new Error('minor units must be a non-negative safe integer');
+    }
+    if (currencyCode !== undefined && !TWO_DECIMAL_CURRENCIES.has(currencyCode.toUpperCase())) {
+        throw new Error(`minorToDecimal only supports 2-decimal currencies (${[...TWO_DECIMAL_CURRENCIES].join('/')}); refusing to emit a wire amount for ${currencyCode}`);
+    }
+    const whole = Math.floor(minor / 100);
+    const fraction = minor % 100;
+    return `${whole}.${String(fraction).padStart(2, '0')}`;
+}
+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}`);
+    }
+}
+/**
+ * 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}`);
+    }
+    // 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;
+    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) {
+        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');
+    }
+}
+/**
+ * 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 } : {}),
+            ...traceHandleFields(value),
+        };
+    }
+}

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

@@ -0,0 +1,52 @@
+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>;
+/**
+ * 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. */
+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>;