@visa/cli 4.1.0-rc.3 → 4.1.0-rc.30

package/dist/checkout-engine/hosted-approval.d.ts

@@ -0,0 +1,135 @@
+import type { PurchaseAssurance, VgsCheckoutTarget } from './vgs-live-instrument.js';
+/**
+ * Hosted purchase approval — the deployed-site replacement for the loopback
+ * ceremony page (ceremony.ts). The passkey tap happens on the verify-web
+ * deployment's /approve page instead of a 127.0.0.1 tab; this module is the
+ * runner's side of that relay (PKCE / device-code shape, mirroring the app's
+ * lib/server/agent-approval.ts):
+ *
+ *   1. Mint a 32-byte VERIFIER in process memory (never on disk — an approval
+ *      lives and dies inside one run), derive challenge = sha256(verifier).
+ *   2. Register the purchase context under the challenge, then open
+ *      <baseUrl>/approve?req=<challenge> in the operator's browser.
+ *   3. Poll the claim route with the verifier: `pending` while the operator
+ *      signs in and taps the passkey; `completed` returns the assuranceData
+ *      ONCE and the entry is gone.
+ *
+ * The URL only ever carries the challenge — useless without the verifier —
+ * and the verifier only ever travels to an HTTPS (or explicit-loopback)
+ * origin. The claim response echoes the context the approval was COMPLETED
+ * against; it is verified field-by-field against this run's checkout target
+ * before the assuranceData is accepted, so relay corruption or a divergent
+ * registration can never smuggle in an assurance scoped to something else
+ * (#5709 would reject it at cryptogram time anyway — this fails minutes
+ * earlier, with the divergent field named). Every network wait is bounded by
+ * the remaining deadline via AbortController — a stalled connection cannot
+ * hang the runner past the advertised timeout.
+ */
+export type HostedApprovalOptions = {
+    /** The enrollment web deployment origin (apps/web), e.g. https://web-….up.railway.app */
+    baseUrl: string;
+    /** Durable agentic token id from the CLI agent credential. */
+    tokenId: string;
+    target: VgsCheckoutTarget;
+    /** Prefills the approval page's enrollment-email field (optional). */
+    consumerEmail?: string;
+    /**
+     * BUDGET/mandate approval: `target.transactionAmount` is the approved spend
+     * CEILING (not one charge), so the server mints a BUDGET mint token that later
+     * accepts many sub-ceiling draws tap-free. Omit for a single-purchase approval.
+     */
+    budget?: boolean;
+    /** Advisory max draws the ceiling intent may fulfil — carried onto the token. */
+    maxDraws?: number;
+    /**
+     * Per-purchase cap (decimal string, <= the ceiling) on a BUDGET approval —
+     * shown on the approval page as a worst-case term and carried onto the mint
+     * token so the displayed cap is the enforced cap. Budget mode only.
+     */
+    perTransaction?: string;
+    /**
+     * Agent-supplied one-liner describing what this approval is for. Sanitized
+     * here (control chars stripped, trimmed, capped) and rendered by the approval
+     * page in a clearly-labeled "written by the agent" block — provenance for the
+     * human to cross-check, never a trusted field.
+     */
+    intent?: string;
+    log?: (line: string) => void;
+    /**
+     * Called once with the approval URL as DATA (not a log line) the instant it is
+     * known — before any polling. A headless agent (OpenClaw/Hermes) has no browser
+     * and no passkey; its whole job is to relay this URL to its human operator, so
+     * the URL must be capturable as a value, not just printed. The interactive CLI
+     * leaves this unset and relies on `log` + `openUrl`.
+     */
+    onApprovalUrl?: (url: string) => void;
+    /** Injectable for tests; default opens the operator's default browser, best-effort. */
+    openUrl?: (url: string) => void;
+    fetchImpl?: typeof fetch;
+    /** Injectable for tests — never wall-clock-sleep in a unit test. */
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+};
+/** One short sentence — must match the relay's cap (agent-approval.ts). */
+export declare const APPROVAL_INTENT_MAX_CHARS = 200;
+/**
+ * Sanitize an agent-supplied intent to what the relay will accept and the page
+ * will display: control chars (and JS line separators) stripped, trimmed,
+ * TRUNCATED to the cap (the runner is the agent's own side, so truncating here
+ * beats a failed registration; the server still rejects an over-cap value).
+ * Returns undefined when nothing displayable remains.
+ */
+export declare function sanitizeApprovalIntent(value: string | undefined): string | undefined;
+/**
+ * The operator saw the request and said NO. Terminal and non-retryable: the
+ * relay entry is consumed, re-running would only re-ask a human who already
+ * refused. Callers must not classify this as transient.
+ */
+export declare class HostedApprovalDeclinedError extends Error {
+    constructor();
+}
+export declare const HOSTED_APPROVAL_TIMEOUT_MS: number;
+export declare const HOSTED_APPROVAL_POLL_MS = 3000;
+/** Emit a "still waiting" heartbeat roughly every this-many ms during the poll. */
+export declare const HOSTED_APPROVAL_HEARTBEAT_MS = 30000;
+/**
+ * Resolve the approval timeout: `CHECKOUT_APPROVAL_TIMEOUT_MS` (seconds*1000, an
+ * integer ms) overrides the default when it parses to a positive integer.
+ * Lets an operator widen the window for separate-device / headless approval
+ * without threading a flag through every caller. Invalid values fall back.
+ */
+export declare function resolveApprovalTimeoutMs(): number;
+/**
+ * The staging apps/web deploy (which now hosts the /agent/enroll/approve page
+ * after the v4-verify-web GA graduation) — hosted approval is the NORMAL path
+ * (no local certs, no vendored SDK, no localhost anywhere), so its origin is a
+ * built-in default rather than per-machine config. Not a secret: it's the
+ * public page the operator's browser opens anyway.
+ */
+export declare const DEFAULT_APPROVAL_BASE_URL = "https://web-visa-code-preview.up.railway.app";
+/**
+ * Flag > environment > built-in default. An explicitly EMPTY value
+ * (CHECKOUT_APPROVAL_BASE_URL='') opts out of hosted approval entirely —
+ * that is the loopback-ceremony escape hatch, so the default must not
+ * resurrect over it (?? not ||).
+ */
+export declare function resolveApprovalBaseUrl(flagValue: string | undefined, env?: Record<string, string | undefined>): string;
+/**
+ * Validate the approval-page origin: HTTPS everywhere except explicit
+ * loopback hosts — the SAME policy the loader applies to the checkout URL.
+ * The claim call sends the verifier (the credential that releases the
+ * assurance), so a cleartext remote origin is never acceptable.
+ */
+export declare function assertApprovalBaseUrl(value: string): string;
+/**
+ * The claim also releases the scoped MINT TOKEN (server-side mint, Phase 1) —
+ * bound to this exact approved purchase — so the runner can call the gateway
+ * mint routes without the VGS secret. Absent when the deployment ran the
+ * dev-auth stub (it mints no token); the caller then surfaces a clear error
+ * rather than falling back to a client-held secret.
+ */
+export declare function runHostedApproval(opts: HostedApprovalOptions): Promise<PurchaseAssurance & {
+    mintToken?: string;
+}>;

package/dist/checkout-engine/hosted-approval.js

@@ -0,0 +1,311 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { exec } from 'node:child_process';
+import { assuranceFromCeremony } from './ceremony.js';
+/** One short sentence — must match the relay's cap (agent-approval.ts). */
+export const APPROVAL_INTENT_MAX_CHARS = 200;
+/**
+ * Sanitize an agent-supplied intent to what the relay will accept and the page
+ * will display: control chars (and JS line separators) stripped, trimmed,
+ * TRUNCATED to the cap (the runner is the agent's own side, so truncating here
+ * beats a failed registration; the server still rejects an over-cap value).
+ * Returns undefined when nothing displayable remains.
+ */
+export function sanitizeApprovalIntent(value) {
+    if (value === undefined)
+        return undefined;
+    const cleaned = value
+        .replace(/[\p{Cc}\u2028\u2029]/gu, '')
+        .trim()
+        .slice(0, APPROVAL_INTENT_MAX_CHARS)
+        .trim();
+    return cleaned.length > 0 ? cleaned : undefined;
+}
+/**
+ * The operator saw the request and said NO. Terminal and non-retryable: the
+ * relay entry is consumed, re-running would only re-ask a human who already
+ * refused. Callers must not classify this as transient.
+ */
+export class HostedApprovalDeclinedError extends Error {
+    constructor() {
+        super('The approver declined this request — the checkout was cancelled and nothing was charged');
+        this.name = 'HostedApprovalDeclinedError';
+    }
+}
+export const HOSTED_APPROVAL_TIMEOUT_MS = 4 * 60 * 1000;
+export const HOSTED_APPROVAL_POLL_MS = 3_000;
+/** Emit a "still waiting" heartbeat roughly every this-many ms during the poll. */
+export const HOSTED_APPROVAL_HEARTBEAT_MS = 30_000;
+/**
+ * Resolve the approval timeout: `CHECKOUT_APPROVAL_TIMEOUT_MS` (seconds*1000, an
+ * integer ms) overrides the default when it parses to a positive integer.
+ * Lets an operator widen the window for separate-device / headless approval
+ * without threading a flag through every caller. Invalid values fall back.
+ */
+export function resolveApprovalTimeoutMs() {
+    const raw = process.env.CHECKOUT_APPROVAL_TIMEOUT_MS;
+    if (raw !== undefined) {
+        const n = Number(raw);
+        if (Number.isSafeInteger(n) && n > 0)
+            return n;
+    }
+    return HOSTED_APPROVAL_TIMEOUT_MS;
+}
+/** Unref'd so a raced-and-abandoned deadline timer can never hold the process open. */
+const defaultSleep = (ms) => new Promise((r) => {
+    const t = setTimeout(r, ms);
+    t.unref?.();
+});
+function defaultOpenUrl(url) {
+    // Best-effort convenience only — the URL is always surfaced via `log`/
+    // `onApprovalUrl`, so this must never throw or hang if there is no browser.
+    // `CHECKOUT_SKIP_BROWSER_OPEN=1` disables it (headless/agent hosts where
+    // launching a browser on the WRONG machine is pointless or noisy).
+    if (process.env.CHECKOUT_SKIP_BROWSER_OPEN === '1')
+        return;
+    // Platform-appropriate opener; unknown platforms just skip (the URL is logged).
+    const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start ""' : 'xdg-open';
+    if (process.platform !== 'darwin' && process.platform !== 'win32' && process.platform !== 'linux')
+        return;
+    const quoted = `'${url.replaceAll("'", "'\\''")}'`;
+    try {
+        // exec is async and fire-and-forget; swallow the callback error so a missing
+        // opener binary (common on headless Linux) can never surface as a failure.
+        exec(`${opener} ${quoted}`, () => { });
+    }
+    catch {
+        // Spawn failure (no shell, sandboxed) — ignore; the printed URL is the path.
+    }
+}
+/**
+ * The staging apps/web deploy (which now hosts the /agent/enroll/approve page
+ * after the v4-verify-web GA graduation) — hosted approval is the NORMAL path
+ * (no local certs, no vendored SDK, no localhost anywhere), so its origin is a
+ * built-in default rather than per-machine config. Not a secret: it's the
+ * public page the operator's browser opens anyway.
+ */
+export const DEFAULT_APPROVAL_BASE_URL = 'https://web-visa-code-preview.up.railway.app';
+/**
+ * Flag > environment > built-in default. An explicitly EMPTY value
+ * (CHECKOUT_APPROVAL_BASE_URL='') opts out of hosted approval entirely —
+ * that is the loopback-ceremony escape hatch, so the default must not
+ * resurrect over it (?? not ||).
+ */
+export function resolveApprovalBaseUrl(flagValue, env = process.env) {
+    return (flagValue ?? env.CHECKOUT_APPROVAL_BASE_URL ?? DEFAULT_APPROVAL_BASE_URL).trim();
+}
+/**
+ * Validate the approval-page origin: HTTPS everywhere except explicit
+ * loopback hosts — the SAME policy the loader applies to the checkout URL.
+ * The claim call sends the verifier (the credential that releases the
+ * assurance), so a cleartext remote origin is never acceptable.
+ */
+export function assertApprovalBaseUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error('--approval-base-url must be a valid http(s) origin');
+    }
+    const loopback = url.hostname === 'localhost' || url.hostname === '127.0.0.1';
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
+        throw new Error('--approval-base-url must use HTTPS (localhost is allowed for local testing) — ' +
+            'the approval claim carries a credential and never travels cleartext');
+    }
+    return value;
+}
+function stripTrailingSlashes(value) {
+    let out = value;
+    while (out.endsWith('/'))
+        out = out.slice(0, -1);
+    return out;
+}
+/**
+ * The claim also releases the scoped MINT TOKEN (server-side mint, Phase 1) —
+ * bound to this exact approved purchase — so the runner can call the gateway
+ * mint routes without the VGS secret. Absent when the deployment ran the
+ * dev-auth stub (it mints no token); the caller then surfaces a clear error
+ * rather than falling back to a client-held secret.
+ */
+export async function runHostedApproval(opts) {
+    const { baseUrl, tokenId, target, consumerEmail, budget, maxDraws, perTransaction, intent, 
+    // Default to stderr, NOT a no-op: the approval URL is the one thing a remote /
+    // SSH / headless-terminal human needs to proceed, and swallowing it (the old
+    // `() => {}` default) left it emitted nowhere readable. Tests inject their own.
+    log = (line) => void process.stderr.write(`${line}\n`), onApprovalUrl, openUrl = defaultOpenUrl, fetchImpl = fetch, sleep = defaultSleep, now = Date.now, pollIntervalMs = HOSTED_APPROVAL_POLL_MS, 
+    // A human approving on a SEPARATE device (open the link, sign in, tap the
+    // passkey) needs more than the interactive 4-minute window; allow an env
+    // override without threading a flag through every caller.
+    timeoutMs = resolveApprovalTimeoutMs(), } = opts;
+    const base = stripTrailingSlashes(assertApprovalBaseUrl(baseUrl));
+    // The server's currency map is uppercase ISO 4217; the loader normalizes the
+    // target once, but normalize here too so a direct caller with a lowercase
+    // code registers (and verifies) the same value the relay stores.
+    const currency = target.transactionCurrencyCode.toUpperCase();
+    // Sanitize once, register + verify the SAME value: the relay stores the
+    // sanitized form, so equality below must compare against it, not the raw input.
+    const intentSanitized = sanitizeApprovalIntent(intent);
+    const verifier = randomBytes(32).toString('base64url');
+    const challenge = createHash('sha256').update(verifier, 'utf8').digest('base64url');
+    const deadline = now() + timeoutMs;
+    const timeoutError = () => new Error(`no passkey approval within ${Math.round(timeoutMs / 1000)}s — ` +
+        'the checkout was cancelled; run again to retry');
+    // Bound EVERY request by the remaining deadline: race the fetch against the
+    // (injectable) sleep and abort the request when the deadline wins, so a
+    // stalled connection can never hang the runner past the advertised timeout.
+    const TIMED_OUT = Symbol('timed-out');
+    async function fetchWithDeadline(url, init) {
+        const remaining = deadline - now();
+        if (remaining <= 0)
+            throw timeoutError();
+        const controller = new AbortController();
+        const winner = await Promise.race([
+            fetchImpl(url, { ...init, signal: controller.signal }),
+            sleep(remaining).then(() => TIMED_OUT),
+        ]);
+        if (typeof winner === 'symbol') {
+            controller.abort();
+            throw timeoutError();
+        }
+        return winner;
+    }
+    const registerRes = await fetchWithDeadline(`${base}/api/vgs/agent-approval`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            challenge,
+            context: {
+                tokenId,
+                merchantName: target.merchantName,
+                merchantUrl: target.merchantUrl,
+                merchantCountryCode: target.merchantCountryCode,
+                amount: target.transactionAmount,
+                currency,
+                ...(consumerEmail ? { consumerEmail } : {}),
+                ...(budget ? { budget: true } : {}),
+                ...(budget && maxDraws !== undefined ? { maxDraws } : {}),
+                ...(budget && perTransaction !== undefined ? { perTransaction } : {}),
+                ...(intentSanitized !== undefined ? { intent: intentSanitized } : {}),
+            },
+        }),
+    });
+    if (!registerRes.ok) {
+        const body = (await registerRes.json().catch(() => ({})));
+        throw new Error(`could not register the hosted approval (${registerRes.status})` +
+            (body.error ? `: ${body.error}` : ''));
+    }
+    // GA graduation: the approval page moved into apps/web under /agent/enroll
+    // (the /api/vgs/** routes above kept their paths verbatim).
+    const approveUrl = `${base}/agent/enroll/approve?req=${challenge}`;
+    // Surface the URL as DATA first (headless relay), then as a log line + best-
+    // effort browser open for the interactive case.
+    onApprovalUrl?.(approveUrl);
+    log(`approve the purchase in your browser: ${approveUrl}`);
+    openUrl(approveUrl);
+    let lastHeartbeat = now();
+    // Keep the event loop alive for the whole poll wait. `defaultSleep` unref()'s
+    // its timer (so the deadline race can't hang the process past the timeout), but
+    // that means the ONLY pending work between polls is an unref'd timer — in a bare
+    // CLI invocation (no stdin/other handles) node would exit 0 mid-poll, after the
+    // first `pending` claim and before the operator finishes the passkey, so the
+    // minted token is parked but never claimed. A ref'd keepalive, cleared on every
+    // exit, holds the process open until the poll loop returns/throws.
+    const keepAlive = setInterval(() => { }, 60_000);
+    try {
+        for (;;) {
+            const res = await fetchWithDeadline(`${base}/api/vgs/agent-approval/claim`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ verifier }),
+            });
+            if (res.ok) {
+                const doc = (await res.json().catch(() => null));
+                // The operator refused — terminal and immediate. Exit the wait now
+                // rather than polling out the timeout; retrying cannot help.
+                if (doc?.status === 'declined')
+                    throw new HostedApprovalDeclinedError();
+                if (doc?.status === 'completed') {
+                    if (doc.assuranceData === undefined || doc.assuranceData === null) {
+                        throw new Error('hosted approval completed but carried no assuranceData');
+                    }
+                    // The context the approval was COMPLETED against must be exactly this
+                    // run's checkout target — a divergent field means the relay entry was
+                    // not ours (corruption, or a mutated registration) and the assurance
+                    // is scoped to something else. Fail naming the field; no secrets here
+                    // (merchant facts only).
+                    const expected = {
+                        tokenId,
+                        merchantName: target.merchantName,
+                        merchantUrl: target.merchantUrl,
+                        merchantCountryCode: target.merchantCountryCode,
+                        amount: target.transactionAmount,
+                        currency,
+                    };
+                    for (const [field, want] of Object.entries(expected)) {
+                        if (doc.context?.[field] !== want) {
+                            throw new Error(`hosted approval context mismatch on ${field} — the approval was not for this ` +
+                                'exact purchase; run the checkout again for a fresh link');
+                        }
+                    }
+                    // A budget approval must complete AS a budget approval — a relay that
+                    // dropped the flag would mint a single-purchase token that then rejects
+                    // the first sub-ceiling draw. Compare the boolean explicitly (it is not a
+                    // string, so it lives outside the string-map loop above).
+                    if (Boolean(doc.context?.budget) !== Boolean(budget)) {
+                        throw new Error('hosted approval context mismatch on budget — the approval was not for this ' +
+                            'exact purchase; run the checkout again for a fresh link');
+                    }
+                    // The advisory draw ceiling must survive the relay intact too — a relay
+                    // that dropped or altered maxDraws would mint a budget token whose draw
+                    // count no longer matches what the operator approved. Only the budget
+                    // path registers maxDraws, so only enforce it there; compare exactly,
+                    // the omitted/undefined case included, so a silently dropped value is
+                    // caught the same as a mutated one.
+                    if (budget && doc.context?.maxDraws !== maxDraws) {
+                        throw new Error('hosted approval context mismatch on maxDraws — the approval was not for this ' +
+                            'exact purchase; run the checkout again for a fresh link');
+                    }
+                    // Same drop-or-mutate rule for the per-purchase cap: the term the
+                    // operator read must be the term the token enforces.
+                    if (budget && doc.context?.perTransaction !== perTransaction) {
+                        throw new Error('hosted approval context mismatch on perTransaction — the approval was not for ' +
+                            'this exact purchase; run the checkout again for a fresh link');
+                    }
+                    // The intent is display-only, but a relay that altered it showed the
+                    // operator different words than the agent sent — refuse, either way.
+                    if (doc.context?.intent !== intentSanitized) {
+                        throw new Error('hosted approval context mismatch on intent — the approval was not for this ' +
+                            'exact purchase; run the checkout again for a fresh link');
+                    }
+                    log('passkey approval received from the hosted page.');
+                    return {
+                        ...assuranceFromCeremony(target, doc.assuranceData),
+                        ...(typeof doc.mintToken === 'string' && doc.mintToken
+                            ? { mintToken: doc.mintToken }
+                            : {}),
+                    };
+                }
+                // status 'pending' — the operator is still signing in / tapping.
+            }
+            else if (res.status === 404) {
+                // Registered moments ago, so absent now means expired or already claimed.
+                throw new Error('the hosted approval expired or was already used — run the checkout again for a fresh link');
+            }
+            // Any other status (429 rate bucket, transient 5xx) polls through.
+            if (now() >= deadline)
+                throw timeoutError();
+            // Heartbeat so a human staring at a terminal (or an agent tailing logs)
+            // knows the wait is live and where to approve — the loop is otherwise silent
+            // for up to the full timeout between the open and the completed claim.
+            if (now() - lastHeartbeat >= HOSTED_APPROVAL_HEARTBEAT_MS) {
+                lastHeartbeat = now();
+                const leftS = Math.max(0, Math.round((deadline - now()) / 1000));
+                log(`still waiting for approval (~${leftS}s left) — approve at ${approveUrl}`);
+            }
+            await sleep(pollIntervalMs);
+        }
+    }
+    finally {
+        clearInterval(keepAlive);
+    }
+}

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

@@ -0,0 +1,6 @@
+export { createCliCheckoutEngine, type CliReviewInput, type CliReviewFacts, type CliPayInput, type CliReceiptFacts, type CliStartMandateInput, type CliMandateFacts, type CliEngineDeps, } from './cli-engine.js';
+export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
+export type { CheckoutResult, CheckoutReview, CheckoutOutcome } from './executor.js';
+export { HostedApprovalDeclinedError, sanitizeApprovalIntent, APPROVAL_INTENT_MAX_CHARS, } from './hosted-approval.js';
+export { createCardMandate, drawFromMandate, MandateDrawDeclinedError, DEFAULT_MANDATE_MAX_DRAWS, type CreateCardMandateInput, type CreateCardMandateDeps, type CardMandateFacts, type DrawFromMandateInput, type DrawFromMandateDeps, type DrawResult, type CardMandateMerchant, } from './mandate/card-mandate.js';
+export { MandateLedger, remainingMinor, defaultLedgerPath, CARD_MANDATE_LEDGER_VERSION, type CardMandateRecord, type CardMandateLedgerFile, type CardMandateDraw, type CardMandateReservation, } from './mandate/mandate-ledger.js';

package/dist/checkout-engine/index.js

@@ -0,0 +1,8 @@
+// Public API of @visa/checkout-engine. The pay_merchant tool in @visa/cli
+// consumes createCliCheckoutEngine() through a structural seam; the core engine
+// primitives are re-exported for direct/embedded use.
+export { createCliCheckoutEngine, } from './cli-engine.js';
+export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
+export { HostedApprovalDeclinedError, sanitizeApprovalIntent, APPROVAL_INTENT_MAX_CHARS, } from './hosted-approval.js';
+export { createCardMandate, drawFromMandate, MandateDrawDeclinedError, DEFAULT_MANDATE_MAX_DRAWS, } from './mandate/card-mandate.js';
+export { MandateLedger, remainingMinor, defaultLedgerPath, CARD_MANDATE_LEDGER_VERSION, } from './mandate/mandate-ledger.js';

package/dist/checkout-engine/inline-target.d.ts

@@ -0,0 +1,13 @@
+import type { VgsCheckoutTarget } from './vgs-live-instrument.js';
+/**
+ * Build a checkout target from inline CLI flags (`--merchant-url` +
+ * `--amount`, with optional `--merchant-name` / `--country` / `--currency`)
+ * so any merchant can be paid without authoring a checkout JSON file first.
+ *
+ * Returns null when neither driving flag is present (file mode). Shape-only:
+ * the returned target flows through run-live-fill's existing validation block
+ * (positive-decimal amount, ISO codes, HTTPS), which stays the single source
+ * of truth — nothing is double-validated here except the URL parse, which
+ * must happen early because the merchant-name default derives from it.
+ */
+export declare function inlineTargetFromFlags(input: Map<string, string>): VgsCheckoutTarget | null;

package/dist/checkout-engine/inline-target.js

@@ -0,0 +1,37 @@
+/**
+ * Build a checkout target from inline CLI flags (`--merchant-url` +
+ * `--amount`, with optional `--merchant-name` / `--country` / `--currency`)
+ * so any merchant can be paid without authoring a checkout JSON file first.
+ *
+ * Returns null when neither driving flag is present (file mode). Shape-only:
+ * the returned target flows through run-live-fill's existing validation block
+ * (positive-decimal amount, ISO codes, HTTPS), which stays the single source
+ * of truth — nothing is double-validated here except the URL parse, which
+ * must happen early because the merchant-name default derives from it.
+ */
+export function inlineTargetFromFlags(input) {
+    const merchantUrl = input.get('--merchant-url');
+    const amount = input.get('--amount');
+    if (merchantUrl === undefined && amount === undefined)
+        return null;
+    if (!merchantUrl || !amount) {
+        throw new Error('inline checkout needs both --merchant-url and --amount');
+    }
+    let host;
+    try {
+        host = new URL(merchantUrl).hostname;
+    }
+    catch {
+        throw new Error('--merchant-url must be a valid URL');
+    }
+    if (!host) {
+        throw new Error('--merchant-url must have a hostname');
+    }
+    return {
+        merchantName: input.get('--merchant-name') ?? host,
+        merchantUrl,
+        merchantCountryCode: input.get('--country') ?? 'US',
+        transactionAmount: amount,
+        transactionCurrencyCode: input.get('--currency') ?? 'USD',
+    };
+}

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

@@ -0,0 +1,55 @@
+export type CardCredential = {
+    pan: string;
+    expMonth: number;
+    expYear: number;
+    cvc: string;
+    cardholderName: string;
+    /** Dynamic payment credential expiry, distinct from the card expiration. */
+    credentialExpiresAt?: string;
+};
+export type InstrumentContext = {
+    merchantHost: string;
+    amountMinor: number;
+    currency: string;
+};
+export type InstrumentKind = 'test-card' | 'vgs-alias' | 'agentic-token';
+export interface Instrument {
+    kind: InstrumentKind;
+    getCredential(ctx: InstrumentContext): Promise<CardCredential>;
+}
+export declare const OFFICIAL_TEST_PANS: {
+    readonly visa: "4242424242424242";
+    readonly visaAlt: "4111111111111111";
+    readonly visaDecline: "4000000000000002";
+    readonly visaSlowConfirm: "4000000000000069";
+    readonly visaUnknownOutcome: "4000000000000044";
+    readonly visaChallenge: "4000000000000010";
+    readonly visaEmailOtp: "4000000000000077";
+};
+export type TestCardOptions = {
+    pan?: string;
+    cardholderName?: string;
+    cvc?: string;
+    expMonth?: number;
+    expYear?: number;
+};
+export declare class TestCardInstrument implements Instrument {
+    readonly kind: "test-card";
+    private readonly credential;
+    constructor(opts?: TestCardOptions);
+    getCredential(_ctx: InstrumentContext): Promise<CardCredential>;
+}
+export declare class VgsAliasInstrument implements Instrument {
+    private readonly _alias;
+    readonly kind: "vgs-alias";
+    constructor(_alias: string);
+    getCredential(_ctx: InstrumentContext): Promise<CardCredential>;
+}
+export declare class AgenticTokenInstrument implements Instrument {
+    private readonly tokenRef;
+    private readonly mintCredential?;
+    readonly kind: "agentic-token";
+    private used;
+    constructor(tokenRef: string, mintCredential?: ((ctx: InstrumentContext) => Promise<CardCredential>) | undefined);
+    getCredential(ctx: InstrumentContext): Promise<CardCredential>;
+}

package/dist/checkout-engine/instrument.js

@@ -0,0 +1,87 @@
+// Instrument abstraction: the checkout engine is deliberately blind to WHERE
+// card credentials come from. Official test PANs, callback-backed agentic
+// credentials, and owner-only VIC harness files are enabled; VGS aliases stay
+// stubbed until a reveal seam exists. The executor remains unchanged across
+// every instrument.
+// Official public test PANs only. These are the sanctioned Visa/network test
+// numbers used against local fixtures; they carry no funds and pass Luhn.
+export const OFFICIAL_TEST_PANS = {
+    visa: '4242424242424242',
+    visaAlt: '4111111111111111',
+    // PAN whose last four are 0002 is treated as a forced decline by the
+    // fixture acquirer, for exercising the declined outcome path.
+    visaDecline: '4000000000000002',
+    // Ending 0069: the fixture acquirer shows a processing interstitial, then
+    // JS-redirects to a Shopify-style thank-you URL with no confirmation text —
+    // exercises the outcome observer's late, URL-signal confirmation path.
+    visaSlowConfirm: '4000000000000069',
+    // Ending 0044: the fixture acquirer returns a neutral page with neither a
+    // confirmation nor a decline signal — exercises the unknown-outcome deadline.
+    visaUnknownOutcome: '4000000000000044',
+    // Ending 0010: the fixture acquirer answers with a 3DS-style verification
+    // page embedding an ACS challenge iframe that never completes — exercises
+    // the observer's action-required (issuer challenge) path.
+    visaChallenge: '4000000000000010',
+    // Ending 0077: the fixture acquirer emails a one-time code to the agent
+    // inbox and shows a 'check your email for a code' page with a one-time-code
+    // field — exercises the executor's agent-resolvable email-OTP subroutine.
+    visaEmailOtp: '4000000000000077',
+};
+function futureExpiry() {
+    const now = new Date();
+    return { expMonth: 12, expYear: now.getFullYear() + 3 };
+}
+export class TestCardInstrument {
+    kind = 'test-card';
+    credential;
+    constructor(opts = {}) {
+        const exp = futureExpiry();
+        this.credential = {
+            pan: opts.pan ?? OFFICIAL_TEST_PANS.visa,
+            expMonth: opts.expMonth ?? exp.expMonth,
+            expYear: opts.expYear ?? exp.expYear,
+            cvc: opts.cvc ?? '123',
+            cardholderName: opts.cardholderName ?? 'Test Agent',
+        };
+    }
+    async getCredential(_ctx) {
+        return this.credential;
+    }
+}
+const NOT_ENABLED = 'not enabled: pending VGS alias reveal support';
+// Stub. Once VGS enablement lands, this resolves a network token / alias into a
+// fillable credential (a virtual PAN plus its verification value).
+export class VgsAliasInstrument {
+    _alias;
+    kind = 'vgs-alias';
+    constructor(_alias) {
+        this._alias = _alias;
+    }
+    async getCredential(_ctx) {
+        throw new Error(`${NOT_ENABLED}. VgsAliasInstrument cannot resolve alias "${this._alias}" ` +
+            'to a fillable PAN until VGS exposes the reveal seam for this spike.');
+    }
+}
+// A server-side provider mints the transaction-bound credential whose pan
+// carries the DPAN and whose cvc carries the short DAVV. Omitting the provider
+// preserves a clear fail-closed result for callers that have only a token ref.
+export class AgenticTokenInstrument {
+    tokenRef;
+    mintCredential;
+    kind = 'agentic-token';
+    used = false;
+    constructor(tokenRef, mintCredential) {
+        this.tokenRef = tokenRef;
+        this.mintCredential = mintCredential;
+    }
+    async getCredential(ctx) {
+        if (!this.mintCredential) {
+            throw new Error('not enabled: no agentic credential provider configured. ' +
+                `Token ${this.tokenRef} needs a server-side VGS credential provider.`);
+        }
+        if (this.used)
+            throw new Error('agentic credential instrument is single-use');
+        this.used = true;
+        return this.mintCredential(ctx);
+    }
+}