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

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

@@ -1,78 +0,0 @@
-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 verify-web deployment origin, e.g. https://v4-verify-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;
-    log?: (line: string) => void;
-    /** Injectable for tests; default opens the operator's default browser (macOS). */
-    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;
-};
-export declare const HOSTED_APPROVAL_TIMEOUT_MS: number;
-export declare const HOSTED_APPROVAL_POLL_MS = 3000;
-/**
- * The one deployed verify site — 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://v4-verify-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

@@ -1,171 +0,0 @@
-import { createHash, randomBytes } from 'node:crypto';
-import { exec } from 'node:child_process';
-import { assuranceFromCeremony } from './ceremony.js';
-export const HOSTED_APPROVAL_TIMEOUT_MS = 4 * 60 * 1000;
-export const HOSTED_APPROVAL_POLL_MS = 3_000;
-/** 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) {
-    // Quoting: the URL is server-origin + our own base64url challenge — no
-    // shell-hostile characters — but single-quote anyway.
-    exec(`open '${url.replaceAll("'", "'\\''")}'`);
-}
-/**
- * The one deployed verify site — 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://v4-verify-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, log = () => { }, openUrl = defaultOpenUrl, fetchImpl = fetch, sleep = defaultSleep, now = Date.now, pollIntervalMs = HOSTED_APPROVAL_POLL_MS, timeoutMs = HOSTED_APPROVAL_TIMEOUT_MS, } = 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();
-    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 } : {}),
-            },
-        }),
-    });
-    if (!registerRes.ok) {
-        const body = (await registerRes.json().catch(() => ({})));
-        throw new Error(`could not register the hosted approval (${registerRes.status})` +
-            (body.error ? `: ${body.error}` : ''));
-    }
-    const approveUrl = `${base}/approve?req=${challenge}`;
-    log(`approve the purchase in your browser: ${approveUrl}`);
-    openUrl(approveUrl);
-    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));
-            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');
-                    }
-                }
-                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();
-        await sleep(pollIntervalMs);
-    }
-}

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

@@ -1,3 +0,0 @@
-export { createCliCheckoutEngine, type CliReviewInput, type CliReviewFacts, type CliPayInput, type CliReceiptFacts, } from './cli-engine.js';
-export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
-export type { CheckoutResult, CheckoutReview, CheckoutOutcome } from './executor.js';

package/dist/checkout-engine/index.js

@@ -1,5 +0,0 @@
-// 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';

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

@@ -1,13 +0,0 @@
-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

@@ -1,37 +0,0 @@
-/**
- * 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

@@ -1,54 +0,0 @@
-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";
-};
-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

@@ -1,83 +0,0 @@
-// 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',
-};
-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);
-    }
-}

package/dist/checkout-engine/live-fill-approval.d.ts

@@ -1,52 +0,0 @@
-import type { CheckoutMode, CheckoutOutcome, CheckoutResult } from './executor.js';
-export declare const SUBMIT_ENV_FLAG = "CHECKOUT_AGENT_ALLOW_SUBMIT";
-export declare const MODE_ENV_FLAG = "CHECKOUT_AGENT_MODE";
-/**
- * `--mode` values map 1:1 onto CheckoutMode; an absent flag falls back to the
- * CHECKOUT_AGENT_MODE environment default, then to the safe dry-run default.
- */
-export declare function parseCheckoutMode(value: string | undefined, env?: Record<string, string | undefined>): CheckoutMode;
-/**
- * Fail fast (before any file read or browser launch) when submit lacks an
- * enablement. The env arm exists to stop AUTOMATION from reaching a live
- * charge by accident — so it is required only when stdin is not a real TTY
- * (scripts, agents, pipes). An interactive human needs no standing config:
- * their per-run consent is the typed PAY phrase plus the passkey tap, both of
- * which a non-interactive caller cannot fake (the phrase names the exact
- * review id; the passkey is a FIDO ceremony on the verify site).
- */
-export declare function assertSubmitAllowed(mode: CheckoutMode, env?: Record<string, string | undefined>, isInteractive?: boolean): void;
-export declare const LEGACY_REFERENCE_ENV_FLAG = "CHECKOUT_AGENT_ALLOW_LEGACY_REFERENCE";
-/**
- * The legacy --reference-file path replays a PRE-CREATED intent, so the
- * purchase-assurance gate (#5709) cannot vet the ceremony that backed it —
- * scope/freshness problems surface only as the opaque cryptogram failure the
- * gate exists to prevent. Default-off escape hatch, same shape as the submit
- * gate: fail fast before any file is read.
- */
-export declare function assertLegacyReferenceAllowed(usingReferenceFile: boolean, env?: Record<string, string | undefined>): void;
-/** Distinct phrases per mode so dry-run muscle memory can never authorize a payment. */
-export declare function approvalPhrase(mode: CheckoutMode, reviewId: string): string;
-/** Integer-only minor→display formatting (two-decimal currencies, the same assumption as decimalToMinor). */
-export declare function formatAmountMinor(amountMinor: number, currency: string): string;
-/** The operator question. In submit mode it names the exact charge — amount and merchant. */
-export declare function approvalQuestion(mode: CheckoutMode, review: {
-    merchantHost: string;
-    amountMinor: number;
-    currency: string;
-}, phrase: string): string;
-/** The one outcome each mode may exit 0 with. */
-export declare function isRunSuccess(mode: CheckoutMode, outcome: CheckoutOutcome): boolean;
-/**
- * True when the pay control was actually clicked but the run ended with an
- * UNKNOWN outcome — neither 'confirmed' nor 'declined' (e.g. a slow redirect
- * or confirmation copy the heuristics don't recognize). The charge may still
- * have gone through; the operator must verify with the merchant before any
- * retry, because a blind rerun risks a double charge. A 'declined' outcome is
- * a definitive negative from the merchant, so it does not warn. Neither does
- * 'action-required': a 3-D Secure challenge intercepts BEFORE authorization,
- * so no charge can exist until it is completed — the double-charge warning
- * would misdirect the operator, and the runner prints the challenge-specific
- * notice instead.
- */
-export declare function submitClickedWithoutConfirmation(result: CheckoutResult): boolean;

package/dist/checkout-engine/live-fill-approval.js

@@ -1,107 +0,0 @@
-// Deliberate-enablement seam for run-live-fill's submit mode. A real submit
-// moves real money, so it requires:
-//   1. an interactive human at a real TTY — or, for scripted/agent runs,
-//      the explicit CHECKOUT_AGENT_ALLOW_SUBMIT=1 environment arm,
-//   2. the invocation opts in (--mode submit, or the CHECKOUT_AGENT_MODE
-//      environment default for operators who always run one mode),
-//   3. the operator types the PAY phrase against the exact review id (and a
-//      hosted run additionally requires the passkey tap on the verify site).
-// The env arm is an anti-automation gate, not a human ritual: a TTY human's
-// consent is act 3 — the PAY phrase differs from dry-run's FILL phrase, so a
-// muscle-memory rerun of the dry-run procedure still cannot drift into
-// charging a card — while a non-interactive caller (script, agent, pipe) can
-// fake neither the phrase's review id nor the FIDO ceremony and must also be
-// explicitly armed. Fresh checkouts therefore need ZERO persisted config.
-export const SUBMIT_ENV_FLAG = 'CHECKOUT_AGENT_ALLOW_SUBMIT';
-export const MODE_ENV_FLAG = 'CHECKOUT_AGENT_MODE';
-/**
- * `--mode` values map 1:1 onto CheckoutMode; an absent flag falls back to the
- * CHECKOUT_AGENT_MODE environment default, then to the safe dry-run default.
- */
-export function parseCheckoutMode(value, env = process.env) {
-    const effective = value ?? env[MODE_ENV_FLAG];
-    if (effective === undefined || effective === 'dry-run')
-        return 'dry-run';
-    if (effective === 'submit')
-        return 'submit';
-    throw new Error(`--mode (or ${MODE_ENV_FLAG}) must be dry-run or submit (got ${JSON.stringify(effective)})`);
-}
-/**
- * Fail fast (before any file read or browser launch) when submit lacks an
- * enablement. The env arm exists to stop AUTOMATION from reaching a live
- * charge by accident — so it is required only when stdin is not a real TTY
- * (scripts, agents, pipes). An interactive human needs no standing config:
- * their per-run consent is the typed PAY phrase plus the passkey tap, both of
- * which a non-interactive caller cannot fake (the phrase names the exact
- * review id; the passkey is a FIDO ceremony on the verify site).
- */
-export function assertSubmitAllowed(mode, env = process.env, isInteractive = process.stdin.isTTY === true) {
-    if (mode !== 'submit')
-        return;
-    if (env[SUBMIT_ENV_FLAG] === '1')
-        return;
-    if (isInteractive)
-        return;
-    throw new Error(`--mode submit refused: this is not an interactive terminal, and scripted submits ` +
-        `require ${SUBMIT_ENV_FLAG}=1. The gate is default-off so automation cannot ` +
-        'reach a live charge by accident.');
-}
-export const LEGACY_REFERENCE_ENV_FLAG = 'CHECKOUT_AGENT_ALLOW_LEGACY_REFERENCE';
-/**
- * The legacy --reference-file path replays a PRE-CREATED intent, so the
- * purchase-assurance gate (#5709) cannot vet the ceremony that backed it —
- * scope/freshness problems surface only as the opaque cryptogram failure the
- * gate exists to prevent. Default-off escape hatch, same shape as the submit
- * gate: fail fast before any file is read.
- */
-export function assertLegacyReferenceAllowed(usingReferenceFile, env = process.env) {
-    if (!usingReferenceFile)
-        return;
-    if (env[LEGACY_REFERENCE_ENV_FLAG] !== '1') {
-        throw new Error(`--reference-file refused: this legacy path bypasses purchase-assurance validation ` +
-            `(#5709) — prefer --checkout-file with --purchase-assurance-file. Set ` +
-            `${LEGACY_REFERENCE_ENV_FLAG}=1 to proceed anyway.`);
-    }
-}
-/** Distinct phrases per mode so dry-run muscle memory can never authorize a payment. */
-export function approvalPhrase(mode, reviewId) {
-    return `${mode === 'submit' ? 'PAY' : 'FILL'} ${reviewId}`;
-}
-/** Integer-only minor→display formatting (two-decimal currencies, the same assumption as decimalToMinor). */
-export function formatAmountMinor(amountMinor, currency) {
-    return `${Math.floor(amountMinor / 100)}.${String(amountMinor % 100).padStart(2, '0')} ${currency}`;
-}
-/** The operator question. In submit mode it names the exact charge — amount and merchant. */
-export function approvalQuestion(mode, review, phrase) {
-    if (mode === 'submit') {
-        return (`Inspect the visible checkout. This WILL charge ` +
-            `${formatAmountMinor(review.amountMinor, review.currency)} at ${review.merchantHost}. ` +
-            `Type ${JSON.stringify(phrase)} to disclose the credential AND submit the order: `);
-    }
-    return (`Inspect the visible checkout. Type ${JSON.stringify(phrase)} ` +
-        `to disclose the credential to this page without submitting: `);
-}
-/** The one outcome each mode may exit 0 with. */
-export function isRunSuccess(mode, outcome) {
-    return outcome === (mode === 'submit' ? 'confirmed' : 'filled-dry-run');
-}
-/**
- * True when the pay control was actually clicked but the run ended with an
- * UNKNOWN outcome — neither 'confirmed' nor 'declined' (e.g. a slow redirect
- * or confirmation copy the heuristics don't recognize). The charge may still
- * have gone through; the operator must verify with the merchant before any
- * retry, because a blind rerun risks a double charge. A 'declined' outcome is
- * a definitive negative from the merchant, so it does not warn. Neither does
- * 'action-required': a 3-D Secure challenge intercepts BEFORE authorization,
- * so no charge can exist until it is completed — the double-charge warning
- * would misdirect the operator, and the runner prints the challenge-specific
- * notice instead.
- */
-export function submitClickedWithoutConfirmation(result) {
-    if (result.outcome === 'confirmed' ||
-        result.outcome === 'declined' ||
-        result.outcome === 'action-required') {
-        return false;
-    }
-    return result.evidence.getSteps().some((s) => s.type === 'submit' && s.data.clicked === true);
-}

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

@@ -1,25 +0,0 @@
-export type Mandate = {
-    maxAmountMinor: number;
-    currency: string;
-    merchantHost?: string;
-    expiresAt: string;
-};
-export type MandateContext = {
-    merchantHost: string;
-    amountMinor: number;
-    currency: string;
-    now?: Date;
-};
-export type MandatePreFillContext = {
-    merchantHost: string;
-    currency?: string | null;
-    now?: Date;
-};
-export type MandateVerdict = {
-    ok: true;
-} | {
-    ok: false;
-    reason: string;
-};
-export declare function checkMandatePreFill(mandate: Mandate | null | undefined, ctx: MandatePreFillContext): MandateVerdict;
-export declare function checkMandate(mandate: Mandate | null | undefined, ctx: MandateContext): MandateVerdict;