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

package/dist/checkout-engine/mandate.js

@@ -0,0 +1,100 @@
+// Mandate gate. The mandate is the user's pre-authorization for a purchase:
+// how much, in what currency, at which merchant, until when. The gate is
+// fail-closed: anything missing, expired, over cap, or mismatched refuses.
+//
+// The gate runs in two phases:
+//   pre-fill  (checkMandatePreFill) — every fact knowable BEFORE a credential
+//             is minted: structure, expiry, merchant host, and the caller's
+//             asserted currency if any. No credential leaves the instrument
+//             and no field is filled without this passing. This is the
+//             boundary that matters once instruments mint live credentials:
+//             merchant JS sees field values on input, so filling first and
+//             gating at submit would already have exposed the credential.
+//   pre-submit (checkMandate) — the full check including the transaction
+//             amount and resolved currency, which are only known after the
+//             page total is read. No submit ever happens without this passing.
+//
+// All amounts are integer minor units (e.g. cents for USD). There is no
+// floating-point money here on purpose; the executor reads a minor-unit total
+// and compares integers.
+function isInteger(n) {
+    return typeof n === 'number' && Number.isInteger(n);
+}
+// Pre-fill gate: everything knowable before a credential is minted.
+export function checkMandatePreFill(mandate, ctx) {
+    if (!mandate) {
+        return { ok: false, reason: 'no mandate provided' };
+    }
+    // Structural validation: a malformed mandate must never authorize a spend.
+    if (!isInteger(mandate.maxAmountMinor) || mandate.maxAmountMinor <= 0) {
+        return { ok: false, reason: 'mandate maxAmountMinor must be a positive integer (minor units)' };
+    }
+    if (!mandate.currency) {
+        return { ok: false, reason: 'mandate is missing a currency' };
+    }
+    if (!mandate.expiresAt) {
+        return { ok: false, reason: 'mandate is missing an expiry' };
+    }
+    const expiry = new Date(mandate.expiresAt);
+    if (Number.isNaN(expiry.getTime())) {
+        return { ok: false, reason: `mandate expiry is not a valid date: ${mandate.expiresAt}` };
+    }
+    const now = ctx.now ?? new Date();
+    if (expiry.getTime() <= now.getTime()) {
+        return { ok: false, reason: `mandate expired at ${mandate.expiresAt}` };
+    }
+    if (ctx.currency && mandate.currency.toUpperCase() !== ctx.currency.toUpperCase()) {
+        return {
+            ok: false,
+            reason: `currency mismatch: mandate ${mandate.currency} vs transaction ${ctx.currency}`,
+        };
+    }
+    if (mandate.merchantHost &&
+        normalizeHost(mandate.merchantHost) !== normalizeHost(ctx.merchantHost)) {
+        return {
+            ok: false,
+            reason: `merchant host mismatch: mandate ${mandate.merchantHost} vs checkout ${ctx.merchantHost}`,
+        };
+    }
+    return { ok: true };
+}
+// Full (pre-submit) gate: the pre-fill checks plus amount and the resolved
+// transaction currency.
+export function checkMandate(mandate, ctx) {
+    const pre = checkMandatePreFill(mandate, ctx);
+    if (!pre.ok)
+        return pre;
+    if (!mandate)
+        return { ok: false, reason: 'no mandate provided' };
+    // The pre-fill phase skips the currency check when none is asserted yet;
+    // here the resolved currency is mandatory.
+    if (!ctx.currency) {
+        return { ok: false, reason: 'transaction currency could not be determined' };
+    }
+    // Transaction amount must be a clean integer minor-unit value.
+    if (!isInteger(ctx.amountMinor) || ctx.amountMinor < 0) {
+        return { ok: false, reason: 'transaction amount is not a non-negative integer (minor units)' };
+    }
+    if (ctx.amountMinor > mandate.maxAmountMinor) {
+        return {
+            ok: false,
+            reason: `amount ${ctx.amountMinor} exceeds mandate cap ${mandate.maxAmountMinor} (minor units)`,
+        };
+    }
+    return { ok: true };
+}
+function normalizeHost(host) {
+    // Reduce a scheme/path/port-bearing host to its bare hostname for the
+    // mandate-vs-checkout equality gate. Uses a linear `split('/')` to drop the
+    // path segment instead of a greedy `/\/.*$/` replace: on a merchant-supplied
+    // host with many leading slashes the greedy variant is a polynomial-ReDoS
+    // vector (CodeQL js/polynomial-redos), and `split` is exact-equivalent here —
+    // "everything before the first '/'". The remaining regexes are start/end
+    // anchored, so they backtrack linearly.
+    const noScheme = host
+        .trim()
+        .toLowerCase()
+        .replace(/^https?:\/\//, '');
+    const noPath = noScheme.split('/', 1)[0];
+    return noPath.replace(/:\d+$/, '');
+}

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

@@ -0,0 +1,30 @@
+import type { Page } from 'playwright-core';
+export type OutcomeStatus = 'confirmed' | 'declined' | 'action-required' | 'verification-required' | 'processing' | 'unknown';
+export type OutcomeClassification = {
+    status: OutcomeStatus;
+    /** The named pattern that decided the status, e.g. "body:card-declined". */
+    signal: string | null;
+};
+/** Pure classification of one page state (case-insensitive on all inputs). */
+export declare function classifyOutcomePage(url: string, bodyText: string, frameUrls?: readonly string[]): OutcomeClassification;
+export type ObservedOutcome = {
+    status: 'confirmed' | 'declined' | 'action-required' | 'verification-required' | 'unknown';
+    signal: string | null;
+    /** Last non-final classification when the deadline expired ('processing' | 'unknown'). */
+    lastSeen: OutcomeStatus;
+    attempts: number;
+    elapsedMs: number;
+};
+/**
+ * Watch the page until a definitive outcome or the deadline. Polling (rather
+ * than waiting for one navigation) is deliberate: declines often render in
+ * place with NO navigation, while confirmations may arrive after several
+ * redirects — both resolve here the moment their signal appears. A detected
+ * issuer challenge is equally final for this observer: it will not resolve
+ * itself, so waiting out the deadline would only misreport it as unknown.
+ */
+export declare function observeOutcome(page: Page, opts?: {
+    deadlineMs?: number;
+    pollMs?: number;
+    holdThroughChallenge?: boolean;
+}): Promise<ObservedOutcome>;

package/dist/checkout-engine/outcome.js

@@ -0,0 +1,225 @@
+// Definitive merchant/processor "no". Kept high-precision: every phrase here
+// means the charge did NOT succeed — never "maybe".
+const DECLINED_BODY = [
+    { name: 'body:card-declined', re: /\bdeclined\b/ },
+    { name: 'body:payment-failed', re: /payment (?:has )?failed/ },
+    { name: 'body:do-not-honor', re: /do not honou?r/ },
+    { name: 'body:insufficient-funds', re: /insufficient funds/ },
+    // Shopify's stock copy for a rejected card.
+    { name: 'body:not-verified', re: /payment details couldn.t be verified/ },
+    { name: 'body:not-authorized', re: /transaction (?:was )?not authori[sz]ed/ },
+];
+// Where checkouts land after success. Matched against the parsed PATHNAME
+// only — never the hostname or query string — and anchored to terminal
+// segments, so `?next=/thank-you`, a host like thankyou-boutique.example,
+// `/no-thank-you`, or a pre-payment review step at `/checkout/confirm` can
+// never fabricate a confirmed verdict (Sentinel finding on #5704). A missed
+// real confirmation degrades to 'unknown' + operator verification — the safe
+// direction; a false 'confirmed' would report a charge that never happened.
+// `thank-you` covers Shopify's legacy (/checkouts/<token>/thank_you) and
+// extensibility (/checkouts/cn/<token>/thank-you) endings.
+const CONFIRMED_URL = [
+    { name: 'url:thank-you', re: /\/thank[-_]?you\/?$/ },
+    { name: 'url:order-confirmation', re: /\/order-confirmation\b/ },
+    { name: 'url:orders-page', re: /\/orders\/[a-z0-9]/ },
+    { name: 'url:success', re: /\/success\/?$/ },
+    { name: 'url:confirmation', re: /\/confirmation\/?$/ },
+];
+const CONFIRMED_BODY = [
+    { name: 'body:order-confirmed', re: /order (?:is )?(?:confirmed|placed)/ },
+    { name: 'body:thank-you-order', re: /thank(?:s| you) for your (?:order|purchase|donation)/ },
+    // Stripe payment-link success copy: "A payment to X will appear on your
+    // statement." Live run c2eda9f6 confirmed on-screen but classified unknown.
+    { name: 'body:on-your-statement', re: /payment to .{1,80} will appear on your statement/ },
+    { name: 'body:payment-ok', re: /payment (?:successful|approved)/ },
+    { name: 'body:order-received', re: /(?:order received|we.ve received your order)/ },
+    { name: 'body:order-ref', re: /order #/ },
+];
+// Issuer / 3-D Secure verification surfaces. 3DS runs BEFORE authorization,
+// so a detected challenge is its own definitive verdict: "a human must verify
+// — no charge exists until the challenge completes", and the page will never
+// resolve to confirmed or declined on its own. Signals are precision-first
+// heuristics: the two vendor hosts are documented 3DS infrastructure
+// (Cardinal Commerce is Visa's 3DS provider; Stripe serves its challenge
+// frames from hooks.stripe.com/3d_secure), and the generic pattern requires a
+// 3DS path segment FOLLOWED by a challenge-flow segment, so an unrelated
+// `/acs/…` route or a marketing `/3d/` page can never match. A missed
+// challenge degrades to 'unknown' + operator verification — the safe
+// direction, and exactly the pre-detection behavior.
+const ACTION_REQUIRED_FRAME = [
+    { name: 'frame:cardinal-3ds', re: /(?:^|\.)cardinalcommerce\.com\// },
+    { name: 'frame:stripe-3ds', re: /hooks\.stripe\.com\/3d_secure/ },
+    {
+        name: 'frame:3ds-challenge',
+        re: /\/(?:3ds2?|3d[-_]?secure|threeds2?|acs)\/(?:challenge|browser|method|auth)\b/,
+    },
+];
+// Full-page ACS redirect flows (no iframe): matched on the pathname only.
+const ACTION_REQUIRED_URL = [
+    { name: 'url:3ds-redirect', re: /\/(?:3ds2?|3d[-_]?secure|threeds2?)\b/ },
+];
+// Challenge copy on the merchant's own page. Kept tight: each phrase is an
+// instruction to authenticate, not a generic mention of security.
+// 'body:link-wallet' must stay FIRST: the Stripe Link login modal is NOT an
+// issuer challenge (completing it pays with an old saved card, not the minted
+// credential) but its copy also says "Enter the code sent to …", which would
+// otherwise match body:code-sent and misreport it as 3DS. Its own copy is
+// distinctive: "to use your saved information" / "Logging in as <email>".
+// The Stripe Link login modal. Checked BEFORE every other body pattern
+// (including the email-OTP split below): completing it pays with an old saved
+// card, not the minted credential, so it must stay action-required (human) and
+// must never be mistaken for an agent-resolvable email code. See #5879.
+const LINK_WALLET_BODY = [
+    {
+        name: 'body:link-wallet',
+        re: /use your saved information|logging in as .{1,60}?\. your device will be remembered/,
+    },
+];
+// Agent-RESOLVABLE email OTP: a code the MERCHANT emailed to the agent's own
+// inbox, which wallet_mail_await_otp can retrieve. Kept deliberately narrow —
+// it requires an EMAIL indicator (email / inbox / @) so an SMS "code sent to
+// your phone" or an issuer 3DS challenge (both un-retrievable by the agent)
+// stay action-required and fall to a human. This is the ONLY status the OTP
+// subroutine will try to auto-complete.
+const VERIFICATION_REQUIRED_BODY = [
+    // "a code was sent / e-mailed to your email / inbox" (code-first order).
+    {
+        name: 'body:email-code-sent',
+        re: /(?:code|passcode).{0,40}(?:sent|e-?mailed).{0,40}(?:e-?mail|inbox|@)/,
+    },
+    // "we e-mailed you a … code" (email-verb-first order).
+    { name: 'body:email-code-sent', re: /e-?mailed\b.{0,40}(?:code|passcode)/ },
+    // "check your email / inbox for a … code".
+    { name: 'body:check-email-code', re: /check your (?:e-?mail|inbox).{0,40}(?:code|verif)/ },
+];
+const ACTION_REQUIRED_BODY = [
+    { name: 'body:3d-secure', re: /3-?d secure/ },
+    { name: 'body:verify-identity', re: /verify your identity/ },
+    { name: 'body:one-time-code', re: /enter (?:the )?(?:one[- ]?time|verification|security) code/ },
+    { name: 'body:code-sent', re: /(?:code|passcode) (?:has been |was )?sent to/ },
+];
+// Interstitial states that mean "no verdict yet — keep watching".
+const PROCESSING = [
+    { name: 'body:processing', re: /processing (?:your )?(?:payment|order)/ },
+    { name: 'body:please-wait', re: /please wait|do not (?:refresh|close)/ },
+    { name: 'url:processing', re: /\/processing\b/ },
+];
+function match(patterns, text) {
+    for (const p of patterns)
+        if (p.re.test(text))
+            return p.name;
+    return null;
+}
+// URL signals only ever see the pathname: hostname and query/hash must not be
+// able to satisfy a confirmation pattern. Falls back to a manual query/hash
+// strip for non-absolute inputs (page.url() is always absolute in practice).
+function pathnameOf(url) {
+    try {
+        return new URL(url).pathname.toLowerCase();
+    }
+    catch {
+        return url.split(/[?#]/)[0].toLowerCase();
+    }
+}
+// Frame signals see host + pathname only — the same #5704 lesson as
+// confirmation URLs: a query string like `?next=https://x.cardinalcommerce.com/`
+// must never satisfy an infrastructure-host pattern.
+function hostAndPathOf(url) {
+    try {
+        const u = new URL(url);
+        return `${u.hostname}${u.pathname}`.toLowerCase();
+    }
+    catch {
+        return url.split(/[?#]/)[0].toLowerCase();
+    }
+}
+/** Pure classification of one page state (case-insensitive on all inputs). */
+export function classifyOutcomePage(url, bodyText, frameUrls = []) {
+    const u = pathnameOf(url);
+    const b = bodyText.toLowerCase();
+    const declined = match(DECLINED_BODY, b);
+    if (declined)
+        return { status: 'declined', signal: declined };
+    for (const frameUrl of frameUrls) {
+        const frame = match(ACTION_REQUIRED_FRAME, hostAndPathOf(frameUrl));
+        if (frame)
+            return { status: 'action-required', signal: frame };
+    }
+    // Stripe Link modal first — it must never fall through to the email-OTP split.
+    const linkWallet = match(LINK_WALLET_BODY, b);
+    if (linkWallet)
+        return { status: 'action-required', signal: linkWallet };
+    // Agent-resolvable email OTP: its own verdict, so the executor can retrieve
+    // the code rather than stopping for a human.
+    const emailVerify = match(VERIFICATION_REQUIRED_BODY, b);
+    if (emailVerify)
+        return { status: 'verification-required', signal: emailVerify };
+    const challengeUrl = match(ACTION_REQUIRED_URL, u);
+    if (challengeUrl)
+        return { status: 'action-required', signal: challengeUrl };
+    const challengeBody = match(ACTION_REQUIRED_BODY, b);
+    if (challengeBody)
+        return { status: 'action-required', signal: challengeBody };
+    const confirmedUrl = match(CONFIRMED_URL, u);
+    if (confirmedUrl)
+        return { status: 'confirmed', signal: confirmedUrl };
+    const confirmedBody = match(CONFIRMED_BODY, b);
+    if (confirmedBody)
+        return { status: 'confirmed', signal: confirmedBody };
+    const processing = match(PROCESSING, b) ?? match(PROCESSING, u);
+    if (processing)
+        return { status: 'processing', signal: processing };
+    return { status: 'unknown', signal: null };
+}
+/**
+ * Watch the page until a definitive outcome or the deadline. Polling (rather
+ * than waiting for one navigation) is deliberate: declines often render in
+ * place with NO navigation, while confirmations may arrive after several
+ * redirects — both resolve here the moment their signal appears. A detected
+ * issuer challenge is equally final for this observer: it will not resolve
+ * itself, so waiting out the deadline would only misreport it as unknown.
+ */
+export async function observeOutcome(page, opts = {}) {
+    const deadlineMs = opts.deadlineMs ?? 20_000;
+    const pollMs = opts.pollMs ?? 500;
+    const startedAt = Date.now();
+    let attempts = 0;
+    for (;;) {
+        attempts++;
+        // Visible text only (innerText, never textContent): Stripe payment links
+        // embed their entire client-side error catalog — including "your card was
+        // declined" — in non-rendered DOM, so a hidden-inclusive read classifies a
+        // fresh page as declined before any authorization has run.
+        const body = (await page.evaluate(() => document.body?.innerText ?? '').catch(() => '')) || '';
+        const frameUrls = page.frames().map((f) => f.url());
+        const seen = classifyOutcomePage(page.url(), body, frameUrls);
+        // An active challenge is normally final for the automated observer (it
+        // will not resolve itself). holdThroughChallenge inverts that for the
+        // human-in-the-loop hold: the challenge stays "pending" and observation
+        // continues until the post-challenge confirmed/declined signal appears.
+        if (seen.status === 'confirmed' ||
+            seen.status === 'declined' ||
+            // Email OTP won't self-resolve either — return it so the executor's
+            // single-use OTP subroutine can retrieve the code (or a human is asked).
+            seen.status === 'verification-required' ||
+            (seen.status === 'action-required' && !opts.holdThroughChallenge)) {
+            return {
+                status: seen.status,
+                signal: seen.signal,
+                lastSeen: seen.status,
+                attempts,
+                elapsedMs: Date.now() - startedAt,
+            };
+        }
+        if (Date.now() - startedAt >= deadlineMs) {
+            return {
+                status: 'unknown',
+                signal: seen.signal,
+                lastSeen: seen.status,
+                attempts,
+                elapsedMs: Date.now() - startedAt,
+            };
+        }
+        await page.waitForTimeout(pollMs);
+    }
+}

package/dist/checkout-engine/owner-only-file.d.ts

@@ -0,0 +1,19 @@
+/**
+ * lstat-only guard for operator-supplied secret-bearing files: must be a
+ * regular file (never a symlink), owner-only (chmod 600), and size-bounded.
+ * Reads NOTHING — safe to run as a preflight before the point where the
+ * file's contents are allowed to be consumed (the assurance-mode agent
+ * credential is only read after the operator approves the checkout review).
+ */
+export declare function assertOwnerOnlyFile(path: string, label: string, maxBytes?: number): Promise<void>;
+/** The same guard, then parse — contents are read only after the guard passes. */
+export declare function readOwnerOnlyJson<T>(path: string, label: string, maxBytes?: number): Promise<T>;
+/**
+ * Atomically write an owner-only (chmod 600) JSON artifact: serialize to a
+ * sibling temp file created 0600, then rename over the target so a reader never
+ * observes a half-written ledger (and a crash mid-write leaves the prior file
+ * intact). The parent directory is created if absent (matching ~/.visa-mcp).
+ * Used by the card-mandate ledger — the same owner-only posture as
+ * agent-credential.json / contact.json.
+ */
+export declare function writeOwnerOnlyJson(path: string, value: unknown): Promise<void>;

package/dist/checkout-engine/owner-only-file.js

@@ -0,0 +1,41 @@
+import { randomBytes } from 'node:crypto';
+import { chmod, lstat, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/**
+ * lstat-only guard for operator-supplied secret-bearing files: must be a
+ * regular file (never a symlink), owner-only (chmod 600), and size-bounded.
+ * Reads NOTHING — safe to run as a preflight before the point where the
+ * file's contents are allowed to be consumed (the assurance-mode agent
+ * credential is only read after the operator approves the checkout review).
+ */
+export async function assertOwnerOnlyFile(path, label, maxBytes = 16 * 1024) {
+    const info = await lstat(path);
+    if (!info.isFile() || info.isSymbolicLink())
+        throw new Error(`${label} must be a regular file`);
+    if ((info.mode & 0o077) !== 0)
+        throw new Error(`${label} must be owner-only (chmod 600)`);
+    if (info.size > maxBytes)
+        throw new Error(`${label} is unexpectedly large`);
+}
+/** The same guard, then parse — contents are read only after the guard passes. */
+export async function readOwnerOnlyJson(path, label, maxBytes = 16 * 1024) {
+    await assertOwnerOnlyFile(path, label, maxBytes);
+    return JSON.parse(await readFile(path, 'utf8'));
+}
+/**
+ * Atomically write an owner-only (chmod 600) JSON artifact: serialize to a
+ * sibling temp file created 0600, then rename over the target so a reader never
+ * observes a half-written ledger (and a crash mid-write leaves the prior file
+ * intact). The parent directory is created if absent (matching ~/.visa-mcp).
+ * Used by the card-mandate ledger — the same owner-only posture as
+ * agent-credential.json / contact.json.
+ */
+export async function writeOwnerOnlyJson(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${randomBytes(6).toString('hex')}`;
+    await writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    // writeFile's mode only applies on create; chmod defensively in case the temp
+    // name somehow pre-existed with looser bits.
+    await chmod(tmp, 0o600);
+    await rename(tmp, path);
+}

package/dist/checkout-engine/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/checkout-engine/receipt-dir.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Where this device's checkout receipts live. Owned by its own module so the
+ * writer (cli-engine.ts) and the reader (confirmed-merchants.ts) can never
+ * drift onto two paths.
+ */
+export declare const RECEIPT_DIR: string;

package/dist/checkout-engine/receipt-dir.js

@@ -0,0 +1,8 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Where this device's checkout receipts live. Owned by its own module so the
+ * writer (cli-engine.ts) and the reader (confirmed-merchants.ts) can never
+ * drift onto two paths.
+ */
+export const RECEIPT_DIR = join(homedir(), '.visa-mcp', 'checkout-receipts');

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

@@ -0,0 +1,121 @@
+import type { EvidenceStep } from './evidence.js';
+import type { CheckoutMode, CheckoutOutcome, CheckoutResult, CredentialLifecycle, CredentialTiming } from './executor.js';
+import type { VicConfirmationReport } from './vic-confirmation.js';
+/** Published v1 artifact shape. Retained so patch releases remain readable/typable. */
+export type CheckoutReceiptV1 = {
+    schema: 'checkout-agent-receipt/v1';
+    recordedAt: string;
+    mode: CheckoutMode;
+    reviewId: string | null;
+    merchant: {
+        name: string;
+        host: string;
+    };
+    transaction: {
+        amount: string;
+        amountMinor: number;
+        currency: string;
+    };
+    outcome: CheckoutOutcome;
+    detail: string | null;
+    confirmationRef: string | null;
+    vicConfirmation: VicConfirmationReport | null;
+    credentialLifecycle: CredentialLifecycle;
+    credentialTiming: CredentialTiming;
+    detectedRoles: string[];
+    requiresAdapter: string[];
+    reconciliation: {
+        required: boolean;
+        reasons: string[];
+    };
+    evidence: {
+        steps: EvidenceStep[];
+        snapshotSummary: string | null;
+    };
+};
+export type CheckoutReceiptV2 = {
+    schema: 'checkout-agent-receipt/v2';
+    recordedAt: string;
+    merchant: {
+        name: string;
+        host: string;
+        checkoutUrl: string | null;
+    };
+    transaction: {
+        amount: string;
+        amountMinor: number;
+        currency: string;
+    };
+    outcome: CheckoutOutcome;
+    agent: {
+        name: string;
+    } | null;
+    rail: {
+        type: 'card';
+        cardLast4: string | null;
+    };
+    network: {
+        confirmation: 'APPROVED' | 'DECLINED' | null;
+    };
+    /** Local reviewed-attempt identifier. Keeps filenames stable across schema versions. */
+    receiptId: string | null;
+    /** Merchant confirmation reference only; never substituted with an internal review id. */
+    reference: string | null;
+    recovery: {
+        required: boolean;
+        retrySafe: boolean;
+        action: string;
+        actions: string[];
+    };
+};
+export type CheckoutReceipt = CheckoutReceiptV1 | CheckoutReceiptV2;
+export type ReceiptWriteReport = {
+    written: true;
+    path: string;
+    panRedactions: number;
+} | {
+    written: false;
+    reason: string;
+};
+export declare function buildReceipt(input: {
+    mode: CheckoutMode;
+    reviewId: string | null;
+    merchant: {
+        name: string;
+        host: string;
+        url?: string;
+    };
+    transaction: {
+        amount: string;
+        amountMinor: number;
+        currency: string;
+    };
+    result: CheckoutResult;
+    vicConfirmation: VicConfirmationReport | null;
+    agentName?: string;
+    cardLast4?: string;
+    /** Injectable for tests; defaults to now. */
+    recordedAt?: Date;
+}): CheckoutReceiptV2;
+/**
+ * Defense-in-depth scrub before anything touches disk: any standalone
+ * 12–19-digit run that passes Luhn is replaced — contiguous OR separated by
+ * single spaces/hyphens between digit groups, the way merchant card-preview
+ * widgets render a typed number ("4242 4242 4242 4242") into page text that
+ * can reach the snapshot summary. Upstream masking means a hit should be
+ * impossible; the count surfaces so the runner can flag a leak.
+ */
+export declare function redactPanLikeDigits(text: string): {
+    text: string;
+    redactions: number;
+};
+export declare function serializeReceipt(receipt: CheckoutReceipt): {
+    json: string;
+    panRedactions: number;
+};
+export declare function receiptFileName(receipt: CheckoutReceipt): string;
+/**
+ * Persist one receipt as an owner-only file (0600) in an owner-only directory
+ * (0700). Refuses to overwrite an existing file (`wx`). Never throws.
+ */
+export declare function writeReceipt(dir: string, receipt: CheckoutReceipt): Promise<ReceiptWriteReport>;