@visa/cli 4.1.0-rc.8 → 4.1.0-rc.81

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

@@ -0,0 +1,64 @@
+import type { PurchaseAssurance, VgsCheckoutTarget } from './vgs-live-instrument.js';
+/** ISO-4217 numeric codes for the consent screen — mirrors the dev-harness map. */
+export declare const CURRENCY_NUMERIC: Record<string, string>;
+export declare function currencyNumeric(code: string): string | null;
+/**
+ * Build the runner-side PurchaseAssurance from a completed ceremony. Scope
+ * fields come verbatim from the checkout target, so the instrument's
+ * scope-alignment validation (#5709) is satisfied by construction; `now` is
+ * injectable for tests.
+ */
+export declare function assuranceFromCeremony(target: VgsCheckoutTarget, assuranceData: unknown, now?: Date): PurchaseAssurance;
+export type CeremonyPageConfig = {
+    tokenId: string;
+    environment: 'live' | 'sandbox';
+    consumerEmail: string;
+    merchantName: string;
+    /** Decimal major-unit amount, e.g. "1.00" — drives the consent screen. */
+    amount: string;
+    /** Display currency, e.g. "USD". */
+    currency: string;
+    /** ISO-4217 numeric code for the SDK, e.g. "840". */
+    currencyNumericCode: string;
+};
+/**
+ * The single-purpose approval page. Pure string builder so tests can assert
+ * the config embed is intact and escape-safe. The config is embedded as JSON
+ * with `<` escaped, so a hostile merchant name cannot break out of the script
+ * element.
+ */
+export declare function ceremonyPageHtml(cfg: CeremonyPageConfig): string;
+export type RunCeremonyOptions = {
+    page: CeremonyPageConfig;
+    target: VgsCheckoutTarget;
+    /** Contents of the vendored VgsAgenticAuth module, served to the page. */
+    vendorSdkJs: string;
+    /** Short-lived VGS bearer for the ceremony SDK (client-credentials mint). */
+    mintAccessToken: () => Promise<string>;
+    /**
+     * TLS material for the loopback server. The Visa device-binding iframe
+     * requires an HTTPS parent page, so real callers must pass this; `null`
+     * serves plain HTTP and exists ONLY so tests can exercise the server
+     * without certificates.
+     */
+    tls: {
+        key: string | Buffer;
+        cert: string | Buffer;
+    } | null;
+    /** Default 4400 — the origin the operator's browser already trusts. */
+    port?: number;
+    /** Overall wait for the human to complete the ceremony. Default 4 minutes. */
+    timeoutMs?: number;
+    /** Open the approval page in the operator's browser. Default: macOS `open`. */
+    openUrl?: (url: string) => void;
+    /** Status output. Default: stderr. */
+    log?: (line: string) => void;
+};
+export declare const CEREMONY_DEFAULT_PORT = 4400;
+export declare const CEREMONY_DEFAULT_TIMEOUT_MS: number;
+/**
+ * Serve the approval page on loopback, open it in the operator's browser, and
+ * resolve with the fresh PurchaseAssurance once the passkey completes. Rejects
+ * on timeout, port conflict, or server failure; the server is always closed.
+ */
+export declare function runInteractiveCeremony(opts: RunCeremonyOptions): Promise<PurchaseAssurance>;

package/dist/checkout-engine/ceremony.js

@@ -0,0 +1,261 @@
+import http from 'node:http';
+import https from 'node:https';
+import { exec } from 'node:child_process';
+// In-run device-binding ceremony — replaces the manual dev-harness tab and the
+// exported assurance file. After the operator types the approval phrase, the
+// runner serves a single-purpose loopback page, opens it in the operator's
+// normal browser (where their passkey, popup allowance, and cert exception
+// already live), and receives the ceremony's assuranceData back in-process.
+// The assurance is therefore seconds old at intent mint (the only
+// proven-reliable configuration — see the 2026-07-17 PENDING-intent runs) and
+// never touches disk.
+//
+// Security posture (same as the dev-harness, contained tighter):
+//   - The server binds 127.0.0.1 ONLY. /api/token hands the page a short-lived
+//     VGS bearer, so the server must never be reachable from another machine.
+//   - assuranceData exists in process memory only; nothing is persisted.
+//   - The page carries no card data and no service-account secret.
+/** ISO-4217 numeric codes for the consent screen — mirrors the dev-harness map. */
+export const CURRENCY_NUMERIC = {
+    USD: '840',
+    CAD: '124',
+    EUR: '978',
+    GBP: '826',
+    AUD: '036',
+};
+export function currencyNumeric(code) {
+    return CURRENCY_NUMERIC[code.toUpperCase()] ?? null;
+}
+/**
+ * Build the runner-side PurchaseAssurance from a completed ceremony. Scope
+ * fields come verbatim from the checkout target, so the instrument's
+ * scope-alignment validation (#5709) is satisfied by construction; `now` is
+ * injectable for tests.
+ */
+export function assuranceFromCeremony(target, assuranceData, now = new Date()) {
+    return {
+        assuranceData,
+        mintedAt: now.toISOString(),
+        merchantHost: new URL(target.merchantUrl).hostname,
+        transactionAmount: target.transactionAmount,
+        transactionCurrencyCode: target.transactionCurrencyCode,
+    };
+}
+/**
+ * The single-purpose approval page. Pure string builder so tests can assert
+ * the config embed is intact and escape-safe. The config is embedded as JSON
+ * with `<` escaped, so a hostile merchant name cannot break out of the script
+ * element.
+ */
+export function ceremonyPageHtml(cfg) {
+    const esc = (s) => s.replace(/[&<>"']/g, (ch) => {
+        const map = {
+            '&': '&amp;',
+            '<': '&lt;',
+            '>': '&gt;',
+            '"': '&quot;',
+            "'": '&#39;',
+        };
+        return map[ch];
+    });
+    const json = JSON.stringify(cfg).replace(/</g, '\\u003c');
+    return `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Approve purchase — Visa</title>
+<style>
+  body { font: 15px/1.5 Menlo, 'SF Mono', monospace; max-width: 640px; margin: 40px auto; padding: 0 16px; color: #1a1a1a; background: #fff; }
+  h1 { font-size: 16px; }
+  .facts { border: 1px solid #e5e5e5; border-radius: 12px; padding: 14px; margin: 14px 0; background: #fafafa; }
+  .facts b { font-size: 18px; }
+  button { font: inherit; padding: 10px 16px; margin: 6px 6px 6px 0; border: 1px solid #111; background: #111; color: #fff; border-radius: 8px; cursor: pointer; }
+  button:disabled { opacity: .4; cursor: default; }
+  button.ghost { background: #fff; color: #111; }
+  input { font: inherit; padding: 8px; border: 1px solid #d4d4d4; border-radius: 8px; }
+  #iframeBox { border: 2px dashed #d4d4d4; border-radius: 12px; min-height: 90px; padding: 8px; margin: 12px 0; }
+  #log { color: #666; font-size: 12.5px; white-space: pre-wrap; }
+  #otpBox { display: none; margin: 10px 0; }
+  .ok { color: #16a34a } .err { color: #be123c }
+</style>
+</head>
+<body>
+<h1>Approve this purchase with your passkey</h1>
+<div class="facts">${esc(cfg.merchantName)}<br /><b>${esc(cfg.currency)} ${esc(cfg.amount)}</b></div>
+<button id="go">Start approval</button>
+<button id="tap" disabled>Approve with passkey</button>
+<div id="otpBox"><span id="otpMethods"></span> <input id="otpCode" placeholder="code" style="width:120px" /> <button id="otpSubmit" class="ghost">Submit code</button></div>
+<div id="iframeBox"></div>
+<div id="log">The agent is waiting in the terminal. Complete the approval here, then return to it.</div>
+<script type="application/json" id="cfg">${json}</script>
+<script type="module">
+import { VgsAgenticAuth } from './vgs-agentic-auth.js'
+const cfg = JSON.parse(document.getElementById('cfg').textContent)
+const log = (m, c = '') => { const el = document.getElementById('log'); el.className = c; el.textContent = m }
+let session = null
+document.getElementById('go').onclick = async () => {
+  const go = document.getElementById('go')
+  go.disabled = true
+  try {
+    log('starting the Visa session…')
+    const { access_token, error } = await (await fetch('/api/token')).json()
+    if (error) throw new Error(error)
+    const flow = new VgsAgenticAuth({
+      tokenId: cfg.tokenId, environment: cfg.environment, consumerEmail: cfg.consumerEmail,
+      accessToken: access_token, timeout: 180000,
+      authenticationAmount: cfg.amount, currencyCode: cfg.currencyNumericCode, merchantName: cfg.merchantName,
+    })
+    const box = document.getElementById('iframeBox'); box.innerHTML = ''
+    session = await flow.startSession(box)
+    if (session.needsOtp) {
+      const b = document.getElementById('otpBox'), d = document.getElementById('otpMethods')
+      b.style.display = 'block'; d.innerHTML = ''
+      log('your bank wants a one-time code first — pick a delivery method.')
+      for (const m of session.otpMethods || []) {
+        const btn = document.createElement('button'); btn.className = 'ghost'
+        btn.textContent = 'Send via ' + (m.method || m.identifier)
+        btn.onclick = async () => { try { await session.requestOtp(m); log('code sent — type it and submit.') } catch (e) { log('sending the code failed: ' + e.message, 'err') } }
+        d.appendChild(btn)
+      }
+    } else {
+      log('ready — click "Approve with passkey".', 'ok')
+      document.getElementById('tap').disabled = false
+    }
+  } catch (e) {
+    log('could not start: ' + (e && e.message || e) + ' — click "Start approval" to retry.', 'err')
+    try { session && session.destroy && session.destroy() } catch {}
+    session = null
+    go.disabled = false
+  }
+}
+document.getElementById('otpSubmit').onclick = async () => {
+  try {
+    await session.submitOtp(document.getElementById('otpCode').value.trim())
+    document.getElementById('otpBox').style.display = 'none'
+    log('code accepted — click "Approve with passkey".', 'ok')
+    document.getElementById('tap').disabled = false
+  } catch (e) { log('code rejected: ' + (e && e.message || e), 'err') }
+}
+document.getElementById('tap').onclick = async () => {
+  const tap = document.getElementById('tap')
+  tap.disabled = true
+  try {
+    log('waiting for your passkey…')
+    const assuranceData = await session.authenticate()
+    try { session.destroy && session.destroy() } catch {}
+    const r = await (await fetch('/api/assurance', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ assuranceData }) })).json()
+    if (r.error) throw new Error(r.error)
+    document.getElementById('go').disabled = true
+    log('approved — return to the terminal. You can close this tab.', 'ok')
+  } catch (e) {
+    log('passkey failed: ' + (e && e.message || e) + ' — click "Start approval" to retry.', 'err')
+    try { session && session.destroy && session.destroy() } catch {}
+    session = null
+    document.getElementById('go').disabled = false
+  }
+}
+</script>
+</body>
+</html>
+`;
+}
+export const CEREMONY_DEFAULT_PORT = 4400;
+export const CEREMONY_DEFAULT_TIMEOUT_MS = 4 * 60 * 1000;
+/**
+ * Serve the approval page on loopback, open it in the operator's browser, and
+ * resolve with the fresh PurchaseAssurance once the passkey completes. Rejects
+ * on timeout, port conflict, or server failure; the server is always closed.
+ */
+export function runInteractiveCeremony(opts) {
+    const port = opts.port ?? CEREMONY_DEFAULT_PORT;
+    const timeoutMs = opts.timeoutMs ?? CEREMONY_DEFAULT_TIMEOUT_MS;
+    const log = opts.log ?? ((line) => process.stderr.write(`${line}\n`));
+    const openUrl = opts.openUrl ??
+        ((url) => {
+            // macOS `open`; on failure the operator still has the printed URL.
+            exec(`open ${JSON.stringify(url)}`, () => { });
+        });
+    const html = ceremonyPageHtml(opts.page);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const handler = async (req, res) => {
+            const send = (code, body, type = 'application/json') => {
+                res.writeHead(code, { 'Content-Type': type, 'Cache-Control': 'no-store' });
+                res.end(body);
+            };
+            try {
+                const path = new URL(req.url ?? '/', 'http://localhost').pathname;
+                if (path === '/')
+                    return send(200, html, 'text/html');
+                if (path === '/vgs-agentic-auth.js')
+                    return send(200, opts.vendorSdkJs, 'text/javascript');
+                if (path === '/api/token') {
+                    const access_token = await opts.mintAccessToken();
+                    return send(200, JSON.stringify({ access_token }));
+                }
+                if (path === '/api/assurance' && req.method === 'POST') {
+                    const chunks = [];
+                    for await (const chunk of req)
+                        chunks.push(chunk);
+                    let body = {};
+                    try {
+                        body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+                    }
+                    catch {
+                        return send(400, JSON.stringify({ error: 'invalid JSON' }));
+                    }
+                    if (body.assuranceData == null) {
+                        return send(400, JSON.stringify({ error: 'assuranceData required' }));
+                    }
+                    // Flush { ok: true } BEFORE teardown: finish() drops every
+                    // connection, and destroying the in-flight socket first would show
+                    // the operator a failed approval while the runner proceeds — the
+                    // end() callback fires once the response has been handed to the OS.
+                    const assurance = assuranceFromCeremony(opts.target, body.assuranceData);
+                    res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+                    res.end(JSON.stringify({ ok: true }), () => finish(null, assurance));
+                    return;
+                }
+                return send(404, JSON.stringify({ error: 'not found' }));
+            }
+            catch (err) {
+                return send(500, JSON.stringify({ error: err.message }));
+            }
+        };
+        const server = opts.tls ? https.createServer(opts.tls, handler) : http.createServer(handler);
+        const timer = setTimeout(() => {
+            finish(new Error(`no passkey approval within ${Math.round(timeoutMs / 1000)}s — ` +
+                'the checkout was not touched; rerun when ready'));
+        }, timeoutMs);
+        timer.unref();
+        function finish(err, assurance) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            server.closeAllConnections?.();
+            server.close(() => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(assurance);
+            });
+        }
+        server.on('error', (err) => {
+            finish(err.code === 'EADDRINUSE'
+                ? new Error(`port ${port} is already in use (is the dev harness still running?) — ` +
+                    'stop it and rerun')
+                : err);
+        });
+        // Loopback ONLY: /api/token hands the page a live VGS bearer.
+        server.listen(port, '127.0.0.1', () => {
+            const address = server.address();
+            const boundPort = typeof address === 'object' && address ? address.port : port;
+            const scheme = opts.tls ? 'https' : 'http';
+            const pageUrl = `${scheme}://localhost:${boundPort}`;
+            log(`Visa approval page: ${pageUrl} — complete the passkey there.`);
+            openUrl(pageUrl);
+        });
+    });
+}

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

@@ -0,0 +1,214 @@
+import { type Browser } from 'playwright-core';
+import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, type PreparedCheckoutSessionStore } from './executor.js';
+import { runHostedApproval as realRunHostedApproval } from './hosted-approval.js';
+import { type VgsCheckoutTarget } from './vgs-live-instrument.js';
+import { serverFetchCryptogram, serverPostConfirmation } from './vgs-gateway/server-mint-client.js';
+import { type CardMandateFacts } from './mandate/card-mandate.js';
+import { MandateLedger } from './mandate/mandate-ledger.js';
+import { writeReceipt as realWriteReceipt } from './receipt.js';
+import { reportVicOutcome as realReportVicOutcome, type VicConfirmationReport } from './vic-confirmation.js';
+import type { Contact, OtpResolver } from './types.js';
+/**
+ * A card-mandate draw failed transiently (retryable) rather than definitively.
+ * Gateway 5xx, "server cryptogram not completed / try again", and network
+ * reset/timeout errors are transient: the mandate stays healthy and must NOT be
+ * disabled. Walks the error's cause chain so a wrapped MandateDrawDeclinedError
+ * is classified by its underlying gateway error. Exported for tests.
+ */
+export declare function isTransientDrawFailure(err: unknown): boolean;
+export type CliReviewInput = {
+    url: string;
+    amount: string;
+    currency: string;
+    credentialPath: string;
+    /** See {@link CardInstrumentSource}. */
+    cardTokenId?: string;
+    contact: Contact;
+    approvalBaseUrl: string;
+    merchantName?: string;
+    merchantCountryCode?: string;
+};
+export type CliReviewFacts = {
+    reviewId: string;
+    merchantHost: string;
+    amountMinor: number;
+    currency: string;
+    submitTargetFingerprint: string;
+    detectedRoles: string[];
+};
+export type CliPayInput = CliReviewInput & {
+    reviewId: string;
+    submit: boolean;
+    /**
+     * Headless handoff for this payment attempt. The MCP layer uses it to return
+     * the hosted passkey URL to a messaging surface while the engine continues
+     * waiting in-process.
+     */
+    onApprovalUrl?: (url: string) => void;
+};
+export type CliReceiptFacts = {
+    outcome: string;
+    confirmationRef: string | null;
+    receiptPath: string | null;
+    detail: string | null;
+    vicConfirmation: VicConfirmationReport | null;
+    /**
+     * Which credential path actually ran: `mandate` = tap-free draw against an
+     * existing card mandate; `fresh-tap` = today's 1:1 hosted-passkey mint; `null`
+     * = neither ran (a pre-flight refusal, e.g. no prepared review). Transparency,
+     * never magic — the caller can always see whether a passkey was skipped.
+     */
+    source: 'mandate' | 'fresh-tap' | null;
+    /** Remaining mandate budget (minor units) after a mandate draw; else null. */
+    remainingMinor: number | null;
+};
+export type CliStartMandateInput = {
+    /** Optional local card-capability selector (legacy name or exact request-key JKT). */
+    agentRef?: string;
+    ceiling: string;
+    currency: string;
+    credentialPath: string;
+    /** See {@link CardInstrumentSource}. */
+    cardTokenId?: string;
+    contact: Contact;
+    approvalBaseUrl: string;
+    /**
+     * Per-purchase cap (decimal string, > 0 and <= ceiling). Registered with the
+     * approval context so the operator reads it as a worst-case term, and carried
+     * onto the budget mint token so it is enforced at draw time.
+     */
+    perTransaction?: string;
+    /**
+     * Agent-supplied one-liner shown on the approval page in a labeled
+     * "written by the agent" block — provenance for the human, never trusted.
+     */
+    intent?: string;
+};
+export type CliMandateFacts = CardMandateFacts & {
+    merchantHost: string;
+    /**
+     * True when the mandate minted its ceiling intent but the #5942 register
+     * handshake failed, so `findCovering` will SKIP it and no tap-free draw is
+     * possible. The mandate exists but is not usable — the caller must surface
+     * this (not report a plain success). Absent/false means registration succeeded;
+     * mandate-start now refuses before approval when no capability can register.
+     */
+    registerFailed?: boolean;
+    /**
+     * The server's refusal reason when {@link registerFailed} is true, verbatim.
+     * Carried out so the CLI can distinguish causes that need DIFFERENT operator
+     * actions — notably `token_mismatch`, which means the on-device grant record's
+     * cached token no longer matches the owner's live agentic token (they
+     * re-enrolled a card after the grant) and is fixed by re-running `grant-card`,
+     * not by retrying `mandate start`. Without the reason every failure reads as
+     * "the auth server was unreachable", which sends the operator in a loop.
+     */
+    registerFailureReason?: string;
+};
+type Session = {
+    browser: Browser;
+    target: VgsCheckoutTarget;
+    amountMinor: number;
+    currency: string;
+    contact: Contact;
+    cleanupTimer: ReturnType<typeof setTimeout>;
+};
+export interface CardDrawVerdictDraw {
+    tokenId: string;
+    amount: string;
+    currency: string;
+    merchantName: string;
+    merchantUrl: string;
+    merchantCountryCode: string;
+}
+export interface CardDrawVerdictCapability {
+    /** Opaque to the engine — passed straight back to {@link CardDrawVerdictSeam.fetchVerdict}. */
+    agentKey: unknown;
+    agentJkt: string;
+    /** Auth origin that minted the binding and hosts the /v4/card/draw* routes. */
+    authBaseUrl: string;
+}
+export interface CardDrawVerdictSeam {
+    loadCapability: (agentRef?: string) => CardDrawVerdictCapability | null;
+    fetchVerdict: (input: {
+        authBaseUrl: string;
+        agentKey: unknown;
+        mandateId: string;
+        drawId: string;
+        draw: CardDrawVerdictDraw;
+    }) => Promise<{
+        verdict: string;
+        remainingCents: number;
+    }>;
+}
+export interface CardMandateRegisterSeam {
+    loadCapability: (agentRef?: string) => {
+        agentKey: unknown;
+        agentJkt: string;
+        authBaseUrl: string;
+    } | null;
+    register: (input: {
+        authBaseUrl: string;
+        agentKey: unknown;
+        mandateId: string;
+        mintToken: string;
+        ceiling: string;
+        currency: string;
+    }) => Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+}
+export type CliEngineDeps = {
+    launchBrowser?: () => Promise<Browser>;
+    prepareCheckout?: typeof realPrepareCheckout;
+    submitApprovedCheckout?: typeof realSubmitApprovedCheckout;
+    runHostedApproval?: typeof realRunHostedApproval;
+    /**
+     * Relay the hosted-approval URL to the caller as DATA the moment it is known,
+     * before the (up-to-timeout) poll wait. A headless agent surface wires this to
+     * hand the URL to its operator; the raw CLI leaves it unset (the URL prints to
+     * stderr and best-effort opens a browser).
+     */
+    onApprovalUrl?: (url: string) => void;
+    reportVicOutcome?: typeof realReportVicOutcome;
+    writeReceipt?: typeof realWriteReceipt;
+    store?: PreparedCheckoutSessionStore;
+    sessions?: Map<string, Session>;
+    ttlMs?: number;
+    /** Owner-only card-mandate ledger — defaults to the ~/.visa-mcp singleton. */
+    ledger?: MandateLedger;
+    /** Injectable clock for mandate expiry decisions (tests pin it). */
+    now?: () => Date;
+    /**
+     * Cryptogram transport for the TAP-FREE mandate draw — defaults to the real
+     * server-side mint route. Injectable so a test can drive the draw-reject ->
+     * markUnhonored path with no network.
+     */
+    serverFetchCryptogram?: typeof serverFetchCryptogram;
+    /** Injectable confirmation transport; defaults to verify-web. */
+    serverPostConfirmation?: typeof serverPostConfirmation;
+    /**
+     * #5923 delegated card-draw verdict seam (see {@link CardDrawVerdictSeam}).
+     * Injected by the CLI when the runtime holds separately provisioned card
+     * authority. When absent, a covering-mandate draw fails before cryptogram mint.
+     */
+    cardDrawVerdict?: CardDrawVerdictSeam;
+    /**
+     * #5942 delegated card-mandate register seam (see {@link CardMandateRegisterSeam}).
+     * Required by mandate-start. When absent, the ceremony is refused before
+     * passkey approval because a budget token cannot act as draw authority.
+     */
+    cardMandateRegister?: CardMandateRegisterSeam;
+    /**
+     * Canonical mailbox OTP reader supplied by the runtime. The checkout engine
+     * owns no mailbox credential and never imports an email provider package.
+     */
+    resolveEmailOtp?: OtpResolver;
+};
+export declare function createCliCheckoutEngine(deps?: CliEngineDeps): {
+    startCardMandate(input: CliStartMandateInput): Promise<CliMandateFacts>;
+    review(input: CliReviewInput): Promise<CliReviewFacts>;
+    pay(input: CliPayInput): Promise<CliReceiptFacts>;
+};
+export {};