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

package/dist/checkout-engine/receipt.js

@@ -0,0 +1,138 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { KNOWN_MERCHANT_IDENTITIES } from './known-merchants.js';
+import { submitClickedWithoutConfirmation } from './live-fill-approval.js';
+/**
+ * What the operator still owes after this run. Empty for a clean dry-run fill
+ * and for a definitive submit outcome whose VIC confirmation posted.
+ */
+function reconciliationFor(result, vicConfirmation) {
+    const reasons = [];
+    if (submitClickedWithoutConfirmation(result)) {
+        reasons.push('the pay control was clicked but no definitive outcome was observed — ' +
+            'verify the charge with the merchant dashboard before any retry');
+    }
+    if ((result.outcome === 'confirmed' || result.outcome === 'declined') &&
+        vicConfirmation &&
+        !vicConfirmation.posted) {
+        reasons.push(`the VIC confirmation was not posted (${vicConfirmation.reason}) — ` +
+            'retry it for this intent out-of-band');
+    }
+    if (result.outcome === 'confirmed' && !result.confirmationRef) {
+        reasons.push('confirmed without a merchant confirmation reference — ' +
+            'record the order number from the merchant dashboard');
+    }
+    if (result.outcome === 'action-required') {
+        reasons.push('an issuer verification challenge was shown and not completed — ' +
+            'finish the purchase manually if still wanted, or confirm with the merchant that no order exists');
+    }
+    return { required: reasons.length > 0, reasons };
+}
+export function buildReceipt(input) {
+    const { result } = input;
+    const reconciliation = reconciliationFor(result, input.vicConfirmation);
+    const fallbackAction = input.mode === 'dry-run'
+        ? 'Dry run only — nothing was submitted; safe to run again.'
+        : result.outcome === 'confirmed'
+            ? 'No action needed.'
+            : result.outcome === 'declined'
+                ? 'Review the decline before trying again.'
+                : result.outcome === 'unverified'
+                    ? // Defensive: reconciliationFor() already pushes the richer
+                        // submit-clicked reason for this outcome, so this line is only
+                        // reached if that ever stops firing. It must still not invite a
+                        // retry.
+                        'The charge may have gone through. Confirm with the merchant before retrying.'
+                    : result.outcome === 'partial-fill'
+                        ? // A v2 receipt carries no evidence log, so this line is the only
+                            // place the CAUSE survives — which field refused and why. An
+                            // operator opening this a week later can act on it; "could not
+                            // be filled" alone means reproducing a live merchant to learn
+                            // anything.
+                            `${result.detail ?? 'Nothing was submitted and nothing was charged.'} Safe to try again once the checkout can be filled.`
+                        : 'Review this outcome before retrying.';
+    const recoveryActions = reconciliation.reasons.length > 0 ? reconciliation.reasons : [fallbackAction];
+    const cardLast4 = input.cardLast4 && /^\d{4}$/.test(input.cardLast4) ? input.cardLast4 : null;
+    const checkoutUrl = input.merchant.url && KNOWN_MERCHANT_IDENTITIES[input.merchant.url] ? input.merchant.url : null;
+    const networkConfirmation = input.vicConfirmation?.posted === true ? input.vicConfirmation.transactionStatus : null;
+    return {
+        schema: 'checkout-agent-receipt/v2',
+        recordedAt: (input.recordedAt ?? new Date()).toISOString(),
+        merchant: { name: input.merchant.name, host: input.merchant.host, checkoutUrl },
+        transaction: input.transaction,
+        outcome: result.outcome,
+        agent: input.agentName ? { name: input.agentName } : null,
+        rail: { type: 'card', cardLast4 },
+        network: { confirmation: networkConfirmation },
+        receiptId: input.reviewId,
+        reference: result.confirmationRef ?? null,
+        recovery: {
+            required: reconciliation.required,
+            // A clean dry-run did not submit anything, so repeating inspection is
+            // safe. Every submit outcome requires either no retry or owner review.
+            retrySafe: input.mode === 'dry-run' && !reconciliation.required,
+            action: recoveryActions[0],
+            actions: recoveryActions,
+        },
+    };
+}
+function luhnValid(digits) {
+    let sum = 0;
+    let double = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let d = digits.charCodeAt(i) - 48;
+        if (double) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+        double = !double;
+    }
+    return sum % 10 === 0;
+}
+/**
+ * Defense-in-depth scrub before anything touches disk: any standalone
+ * 12–19-digit run that passes Luhn is replaced — contiguous OR separated by
+ * single spaces/hyphens between digit groups, the way merchant card-preview
+ * widgets render a typed number ("4242 4242 4242 4242") into page text that
+ * can reach the snapshot summary. Upstream masking means a hit should be
+ * impossible; the count surfaces so the runner can flag a leak.
+ */
+export function redactPanLikeDigits(text) {
+    let redactions = 0;
+    const scrubbed = text.replace(/(?<!\d)(?<!\d[\s-])\d(?:[\s-]?\d){11,18}(?![\s-]?\d)/g, (run) => {
+        const digits = run.replace(/[\s-]/g, '');
+        if (digits.length < 12 || digits.length > 19 || !luhnValid(digits))
+            return run;
+        redactions++;
+        return '<redacted:pan-like>';
+    });
+    return { text: scrubbed, redactions };
+}
+export function serializeReceipt(receipt) {
+    const { text, redactions } = redactPanLikeDigits(`${JSON.stringify(receipt, null, 2)}\n`);
+    return { json: text, panRedactions: redactions };
+}
+export function receiptFileName(receipt) {
+    const ts = receipt.recordedAt.replace(/[:.]/g, '-');
+    const receiptId = receipt.schema === 'checkout-agent-receipt/v1' ? receipt.reviewId : receipt.receiptId;
+    const review = (receiptId ?? 'no-review').replace(/[^A-Za-z0-9-]/g, '');
+    return `receipt-${ts}-${review || 'no-review'}.json`;
+}
+/**
+ * Persist one receipt as an owner-only file (0600) in an owner-only directory
+ * (0700). Refuses to overwrite an existing file (`wx`). Never throws.
+ */
+export async function writeReceipt(dir, receipt) {
+    try {
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+        const path = join(dir, receiptFileName(receipt));
+        const { json, panRedactions } = serializeReceipt(receipt);
+        await writeFile(path, json, { mode: 0o600, flag: 'wx' });
+        return { written: true, path, panRedactions };
+    }
+    catch (err) {
+        return { written: false, reason: err.message };
+    }
+}

package/dist/checkout-engine/trace-handles.d.ts

@@ -0,0 +1,8 @@
+export declare function safeTraceHandle(value: unknown): string | undefined;
+export declare function traceHandleFields(value: {
+    vgsTraceId?: unknown;
+    networkCorrelationId?: unknown;
+}): {
+    vgsTraceId?: string;
+    networkCorrelationId?: string;
+};

package/dist/checkout-engine/trace-handles.js

@@ -0,0 +1,12 @@
+const SAFE_TRACE_HANDLE_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+export function safeTraceHandle(value) {
+    return typeof value === 'string' && SAFE_TRACE_HANDLE_RE.test(value) ? value : undefined;
+}
+export function traceHandleFields(value) {
+    const vgsTraceId = safeTraceHandle(value.vgsTraceId);
+    const networkCorrelationId = safeTraceHandle(value.networkCorrelationId);
+    return {
+        ...(vgsTraceId ? { vgsTraceId } : {}),
+        ...(networkCorrelationId ? { networkCorrelationId } : {}),
+    };
+}

package/dist/checkout-engine/types.d.ts

@@ -0,0 +1,52 @@
+export type PostalAddress = {
+    firstName?: string;
+    lastName?: string;
+    fullName?: string;
+    addressLine1?: string;
+    addressLine2?: string;
+    city?: string;
+    state?: string;
+    postalCode?: string;
+    country?: string;
+};
+export type Contact = PostalAddress & {
+    email?: string;
+    phone?: string;
+    billingAddress?: PostalAddress;
+};
+export type FilledField = {
+    role: string;
+    locator: string;
+    confidence: number;
+    source: string;
+    frame?: string;
+    value: string;
+    ok: boolean;
+    error?: string;
+    /**
+     * The detected node was gone by the time this field's turn came (the merchant
+     * re-mounted that part of the form mid-fill) and a fresh detection pass was
+     * used to find it again. Worth surfacing: a merchant that re-mounts is a
+     * merchant whose fills are order-sensitive, which is the first thing to know
+     * when one of them later refuses.
+     */
+    relocated?: boolean;
+};
+export type FillResult = {
+    ok: boolean;
+    filled: FilledField[];
+    detail?: string;
+};
+export type OtpRequest = {
+    /** ISO watermark captured BEFORE the click that triggers the OTP email. */
+    after: string;
+    /** The merchant hostname; the sender's registrable domain must match it. */
+    merchantHost: string;
+};
+export type OtpResolution = {
+    /** The single-use code. The executor fills it exactly once; never retried. */
+    code: string;
+    /** The sender's registrable domain — a trust signal, safe to log (no PII). */
+    fromDomain: string;
+};
+export type OtpResolver = (req: OtpRequest) => Promise<OtpResolution | null>;

package/dist/checkout-engine/types.js

@@ -0,0 +1,2 @@
+// Shared value types used across the engine.
+export {};

package/dist/checkout-engine/unresolved-charges.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Outcomes whose receipt cannot rule out a charge.
+ *
+ * Both of these record a run where the pay control was clicked and no
+ * definitive answer came back:
+ *   - `unverified`      — no confirmation or decline observed before the deadline
+ *   - `action-required` — an issuer challenge appeared, which happens AFTER the
+ *                         click, so the authorization may already exist
+ *
+ * Everything else is either definitive (`confirmed`, `declined`) or provably
+ * pre-click (`reviewed-dry-run`, `partial-fill`, `failed`, ...). Widening this
+ * set blocks legitimate retries; narrowing it lets a double charge through, so
+ * an outcome earns a place here only by being genuinely post-click.
+ */
+export declare const MAY_HAVE_CHARGED_OUTCOMES: ReadonlySet<string>;
+/** One local attempt that may have taken money and was never resolved. */
+export type UnresolvedCharge = {
+    recordedAt: string;
+    host: string;
+    amount: string;
+    amountMinor: number;
+    currency: string;
+    outcome: string;
+    /** Receipt file basename, so a caller can name the evidence a human must check. */
+    receiptFile: string;
+};
+/**
+ * Local attempts that may have charged, newest first.
+ *
+ * Never throws: a missing directory (nothing has ever been checked out here)
+ * and an unreadable one both read as "no unresolved charges". The caller
+ * decides what an empty answer means — see the fail-open note at its call site.
+ */
+export declare function readUnresolvedCharges(receiptDir?: string): Promise<UnresolvedCharge[]>;

package/dist/checkout-engine/unresolved-charges.js

@@ -0,0 +1,125 @@
+// "Did this device already submit this exact purchase?", read back from the
+// checkout receipts on disk.
+//
+// The engine now reports a submitted-but-unobserved checkout as `unverified`
+// instead of `failed`, and pay_merchant tells the caller not to retry it. This
+// module is the belt to that suspenders: even a caller that ignores the words
+// can be stopped, because the previous attempt left a receipt.
+//
+// It answers one question — which local receipts record an attempt that MAY
+// HAVE CHARGED and was never resolved — and deliberately answers nothing else.
+// The matching (same merchant, same amount, recent enough) lives in the caller,
+// which owns the policy; this side owns only the read.
+//
+// Sibling of confirmed-merchants.ts and loaded through the same seam: it
+// imports node built-ins and types only, so reading receipts never pulls
+// playwright into the CLI process.
+//
+// Reading is best-effort by construction. The receipts directory is an operator
+// artifact that anything on the box can touch, so an unreadable or malformed
+// file is skipped rather than failing the whole read.
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { RECEIPT_DIR } from './receipt-dir.js';
+/**
+ * Outcomes whose receipt cannot rule out a charge.
+ *
+ * Both of these record a run where the pay control was clicked and no
+ * definitive answer came back:
+ *   - `unverified`      — no confirmation or decline observed before the deadline
+ *   - `action-required` — an issuer challenge appeared, which happens AFTER the
+ *                         click, so the authorization may already exist
+ *
+ * Everything else is either definitive (`confirmed`, `declined`) or provably
+ * pre-click (`reviewed-dry-run`, `partial-fill`, `failed`, ...). Widening this
+ * set blocks legitimate retries; narrowing it lets a double charge through, so
+ * an outcome earns a place here only by being genuinely post-click.
+ */
+export const MAY_HAVE_CHARGED_OUTCOMES = new Set([
+    'unverified',
+    'action-required',
+]);
+/**
+ * Every field this module reads, validated. Deliberately permissive about
+ * everything else: older and newer engines only have to carry these.
+ *
+ * Both receipt schemas expose all of them at the same paths, so unlike
+ * confirmed-merchants.ts there is nothing here that needs a per-schema branch.
+ */
+function parseUnresolved(json, receiptFile) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const receipt = parsed;
+    if (receipt.schema !== 'checkout-agent-receipt/v1' &&
+        receipt.schema !== 'checkout-agent-receipt/v2') {
+        return null;
+    }
+    if (typeof receipt.outcome !== 'string' || !MAY_HAVE_CHARGED_OUTCOMES.has(receipt.outcome)) {
+        return null;
+    }
+    if (typeof receipt.recordedAt !== 'string' || Number.isNaN(Date.parse(receipt.recordedAt))) {
+        return null;
+    }
+    const host = receipt.merchant?.host;
+    if (typeof host !== 'string' || host.length === 0)
+        return null;
+    const transaction = receipt.transaction;
+    if (typeof transaction?.amount !== 'string')
+        return null;
+    if (typeof transaction.currency !== 'string')
+        return null;
+    // A receipt whose amount cannot be compared cannot gate a retry on amount, and
+    // a guard that silently matched every amount would be worse than none.
+    if (typeof transaction.amountMinor !== 'number' || !Number.isFinite(transaction.amountMinor)) {
+        return null;
+    }
+    return {
+        recordedAt: receipt.recordedAt,
+        host,
+        amount: transaction.amount,
+        amountMinor: transaction.amountMinor,
+        currency: transaction.currency,
+        outcome: receipt.outcome,
+        receiptFile,
+    };
+}
+/**
+ * Local attempts that may have charged, newest first.
+ *
+ * Never throws: a missing directory (nothing has ever been checked out here)
+ * and an unreadable one both read as "no unresolved charges". The caller
+ * decides what an empty answer means — see the fail-open note at its call site.
+ */
+export async function readUnresolvedCharges(receiptDir = RECEIPT_DIR) {
+    let names;
+    try {
+        names = await readdir(receiptDir);
+    }
+    catch {
+        return [];
+    }
+    const charges = [];
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        let raw;
+        try {
+            raw = await readFile(join(receiptDir, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const charge = parseUnresolved(raw, name);
+        if (charge)
+            charges.push(charge);
+    }
+    charges.sort((left, right) => (left.recordedAt < right.recordedAt ? 1 : -1));
+    return charges;
+}

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

@@ -0,0 +1,101 @@
+import type { VgsCheckoutTarget, VgsPaymentCredential } from '../vgs-live-instrument.js';
+export type ServerMintDeps = {
+    /** Injectable for tests — defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Injectable for tests — never wall-clock-sleep in a unit test. */
+    sleep?: (ms: number) => Promise<void>;
+    env?: NodeJS.ProcessEnv;
+};
+/**
+ * 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 declare function merchantOrigin(url: string): string;
+/**
+ * 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 declare class ServerCryptogramRefusedError extends Error {
+    readonly status: number;
+    readonly terminal: true;
+    constructor(status: number, detail: string);
+}
+/**
+ * Optional mandate override for serverCreateIntent. Absent → the default
+ * intent shape (cap = ceil(amount)+10 min 25, quantity 1, 30-day window).
+ * Present → the card-mandate (budget) layer sets a CEILING decline threshold
+ * and a multi-draw quantity so one passkey approves a spend ceiling and later
+ * draws pull cryptograms under it without a fresh tap. Whether the network
+ * honors a ceiling-scoped assurance across multiple sub-amount draws is
+ * UNPROVEN — see packages/checkout-engine/src/mandate/.
+ */
+export type ServerIntentMandateOverride = {
+    /** Wire decline-threshold amount (major-unit decimal string), e.g. "500.00". */
+    declineThresholdAmount?: string;
+    /** Number of draws the intent may fulfil (VGS mandate `quantity`). */
+    quantity?: number;
+    /** ISO 8601 mandate validity end. */
+    effectiveUntil?: string;
+    /** Human-readable consumer prompt describing the ceiling grant. */
+    consumerPrompt?: string;
+};
+/**
+ * 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 declare function serverCreateIntent(base: string, mintToken: string, input: {
+    tokenId: string;
+    assuranceData: unknown;
+    transaction: VgsCheckoutTarget;
+    mandate?: ServerIntentMandateOverride;
+}, deps?: ServerMintDeps): Promise<{
+    intentId: string;
+    status: string | 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 declare function serverFetchCryptogram(base: string, mintToken: string, input: {
+    tokenId: string;
+    intentId: string;
+    transaction: VgsCheckoutTarget;
+}, deps?: ServerMintDeps): Promise<VgsPaymentCredential>;
+/** Report the observed merchant outcome via POST {base}/api/vgs/confirmation. */
+export declare function serverPostConfirmation(base: string, mintToken: string, input: {
+    tokenId: string;
+    intentId: string;
+    transactionStatus: string;
+    transactionType: string;
+    transactionTimestamp: string;
+    transaction: {
+        transactionAmount: string;
+        transactionCurrencyCode: string;
+    };
+}, deps?: ServerMintDeps): Promise<{
+    ok: true;
+}>;