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

package/dist/checkout-engine/browser-launch.js

@@ -0,0 +1,81 @@
+/**
+ * Browser provisioning for the checkout engine.
+ *
+ * @purpose The engine depends on `playwright-core` (NOT `playwright`) so that
+ * installing @visa/cli never triggers a postinstall Chromium download. A real
+ * browser is resolved lazily, on the first checkout, in this order:
+ *
+ *   1. VISA_CHECKOUT_BROWSER  — explicit executable path override (deterministic
+ *      for CI / pinned environments; wins over everything). If it is set but
+ *      FAILS to launch, we ABORT loudly rather than fall through — a pinned
+ *      money flow must not run in a browser the operator did not choose.
+ *   2. channel: 'chrome'      — a system-installed Google Chrome (no download).
+ *   3. channel: 'msedge'      — a system-installed Microsoft Edge (no download).
+ *   4. default chromium       — a playwright-managed browser, IF one was already
+ *      installed via `npx playwright-core install chromium` (still no download
+ *      here — it only USES an existing one; launch throws if absent).
+ *
+ * If none launch, we throw one actionable error listing every attempt and the
+ * three ways to fix it. We never silently download hundreds of MB mid-command;
+ * provisioning stays an explicit user choice (install Chrome, run the documented
+ * `playwright-core install`, or point VISA_CHECKOUT_BROWSER at a binary).
+ *
+ * The install command is `playwright-core`, NOT `playwright`: this package no
+ * longer depends on the full `playwright`, so `npx playwright …` would fetch an
+ * unrelated latest `playwright` and can install a browser revision that does not
+ * match the pinned `playwright-core` — the very launch this is meant to fix.
+ * `npx playwright-core install` uses the installed, version-matched package.
+ */
+import { chromium } from 'playwright-core';
+const HEADFUL = { headless: false };
+/** Build the ordered launch attempts for the current environment. Exported for
+ *  unit testing the resolution order without launching anything. */
+export function buildLaunchAttempts(env) {
+    const attempts = [];
+    const override = env.VISA_CHECKOUT_BROWSER?.trim();
+    if (override) {
+        attempts.push({
+            label: `VISA_CHECKOUT_BROWSER (${override})`,
+            opts: { ...HEADFUL, executablePath: override },
+            override: true,
+        });
+    }
+    attempts.push({
+        label: 'system Chrome (channel=chrome)',
+        opts: { ...HEADFUL, channel: 'chrome' },
+    });
+    attempts.push({ label: 'system Edge (channel=msedge)', opts: { ...HEADFUL, channel: 'msedge' } });
+    attempts.push({ label: 'playwright-managed chromium', opts: { ...HEADFUL } });
+    return attempts;
+}
+export async function launchCheckoutBrowser(deps = {}) {
+    const env = deps.env ?? process.env;
+    const launch = deps.launch ?? ((opts) => chromium.launch(opts));
+    const log = deps.log ?? (() => { });
+    const errors = [];
+    for (const attempt of buildLaunchAttempts(env)) {
+        try {
+            const browser = await launch(attempt.opts);
+            log(`checkout browser: launched via ${attempt.label}`);
+            return browser;
+        }
+        catch (err) {
+            const first = err.message.split('\n')[0];
+            if (attempt.override) {
+                // An explicit VISA_CHECKOUT_BROWSER is a deterministic, pinned choice
+                // (CI / a locked-down operator env). If it fails to launch, ABORT loudly
+                // rather than silently substituting a system browser the operator did
+                // not pin — this is a money flow. Unsetting the var opts back into the
+                // system-browser fallback below.
+                throw new Error(`VISA_CHECKOUT_BROWSER="${env.VISA_CHECKOUT_BROWSER?.trim()}" failed to launch: ${first}. ` +
+                    'Fix the path/binary, or unset VISA_CHECKOUT_BROWSER to allow a system-browser ' +
+                    'fallback — refusing to substitute an unpinned browser for a checkout.');
+            }
+            errors.push(`${attempt.label}: ${first}`);
+        }
+    }
+    throw new Error('Could not launch a browser for checkout. Tried — ' +
+        errors.join(' | ') +
+        '. Install Google Chrome, or run `npx playwright-core install chromium` ' +
+        '(matches the pinned version), or set VISA_CHECKOUT_BROWSER to a browser executable path.');
+}

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);
+        });
+    });
+}