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

package/dist/checkout-engine/mandate/mandate-ledger.js

@@ -0,0 +1,410 @@
+// Owner-only persisted ledger for card mandates (budgets). One passkey approval
+// creates one VGS intent with a CEILING decline threshold; this ledger tracks
+// the cumulative budget the agent may draw against that intent without a fresh
+// tap. It deliberately MIRRORS csmoove530's standing-mandate ledger (#5600 /
+// #5724) so the two reconcile later rather than competing:
+//
+//   - owner-only (chmod 600) JSON artifact under ~/.visa-mcp/, atomic write;
+//   - integer minor-unit accounting only — no floating-point money;
+//   - atomic reserve -> commit | release around every draw, so approved plus
+//     in-flight spend can never exceed the authenticated ceiling.
+//
+// VGS's decline_threshold is a per-transaction NETWORK control; this ledger is
+// the SEPARATE cumulative budget control. The file holds identifiers and
+// accounting state only — never a bootstrap mint token, PAN, DPAN, CVC, or
+// cryptogram values. Cross-process concurrency is NOT solved by a file
+// (same caveat csmoove notes); the in-process mutex below serializes draws
+// within one CLI process, which is the live-spike target.
+//
+// SELF-HEALING: a reservation is persisted the instant it is taken and is only
+// removed by commit() or release(). A crash BETWEEN reserve and commit/release
+// would otherwise strand the reservation forever, permanently shrinking
+// `remaining`. The headroom-deciding paths (reserve() and findCovering()) run a
+// stale-reservation sweep on load: any reservation older than
+// STALE_RESERVATION_MS (a draw cannot legitimately stay in-flight that long) is
+// dropped, returning its headroom, so a stranded reservation can never block a
+// legitimate draw. reserve()'s save() persists the prune; findCovering() heals
+// its in-memory view. The sweep uses the caller's clock (michaelyang1 L1).
+import { randomBytes } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readOwnerOnlyJson, writeOwnerOnlyJson } from '../owner-only-file.js';
+export const CARD_MANDATE_LEDGER_VERSION = 1;
+// A ledger with a long draw history is larger than a single credential; cap
+// generously but still bounded (owner-only-file's default 16 KB is too small).
+const LEDGER_MAX_BYTES = 512 * 1024;
+// A tap-free draw's reserve -> commit/release cycle completes in one network
+// round-trip; a reservation older than this window can only be the debris of a
+// crash between reserve and commit/release, so load() sweeps it (L1 self-heal).
+// Must match the server-authoritative TTL (CARD_MANDATE_RESERVATION_TTL_SECONDS
+// in apps/auth/src/server.ts, default 15 min) to avoid a window where the local
+// ledger over-reports available headroom.
+const STALE_RESERVATION_MS = 15 * 60 * 1000;
+// Mandates expired longer ago than this are pruned on the next create(). Generous
+// (a week) so a recently-expired mandate is still visible in `mandate list`, but
+// bounded so a long-lived heavy user cannot grow the owner-only ledger file into
+// its size cap — which would otherwise brick EVERY ledger op (create/reserve/
+// findCovering/commit/release all load the file first).
+const EXPIRED_PRUNE_GRACE_MS = 7 * 24 * 60 * 60 * 1000;
+function reservedTotal(record) {
+    return record.reservations.reduce((sum, r) => sum + r.amountMinor, 0);
+}
+/**
+ * Drop reservations older than STALE_RESERVATION_MS across every mandate — the
+ * debris of a crash between reserve and commit/release. Mutates in place and
+ * returns true if anything was swept (so the caller can decide to persist).
+ * A reservation with an unparseable `reservedAt` is treated as stale.
+ */
+function sweepStaleReservations(file, nowMs) {
+    let swept = false;
+    for (const m of file.mandates) {
+        const kept = m.reservations.filter((r) => {
+            const reservedMs = Date.parse(r.reservedAt);
+            const stale = !Number.isFinite(reservedMs) || nowMs - reservedMs > STALE_RESERVATION_MS;
+            if (stale)
+                swept = true;
+            return !stale;
+        });
+        if (kept.length !== m.reservations.length)
+            m.reservations = kept;
+    }
+    return swept;
+}
+/** Available headroom = ceiling - committed - reserved. Integer minor units. */
+export function remainingMinor(record) {
+    return record.ceilingMinor - record.spentMinor - reservedTotal(record);
+}
+function isExpired(record, now) {
+    const end = Date.parse(record.expiresAt);
+    return !Number.isFinite(end) || end <= now.getTime();
+}
+function committedDrawCount(record) {
+    return record.draws.filter((draw) => draw.status === 'committed').length;
+}
+function hasDrawCountHeadroom(record) {
+    return (record.maxDraws === undefined ||
+        committedDrawCount(record) + record.reservations.length < record.maxDraws);
+}
+function assertPositiveInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`${label} must be a positive integer (minor units)`);
+    }
+}
+/**
+ * The persisted card-mandate ledger. All mutating operations are serialized on
+ * an in-process promise chain so two concurrent draws cannot both observe the
+ * same remaining balance (the read-modify-write is atomic within the process).
+ */
+export class MandateLedger {
+    path;
+    chain = Promise.resolve();
+    constructor(path = defaultLedgerPath()) {
+        this.path = path;
+    }
+    /** Serialize a read-modify-write so concurrent draws can't race the file. */
+    run(fn) {
+        const next = this.chain.then(fn, fn);
+        // Keep the chain alive even if this op rejects; swallow only the chain copy.
+        this.chain = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    // `nowMs` is the caller's clock for the stale-reservation sweep. The sweep
+    // deliberately runs only on the headroom-DECIDING loads — reserve() and
+    // findCovering() — which are the paths that must not be blocked by
+    // crash-stranded reservation debris. commit(), release(), and markUnhonored()
+    // pass NO clock on purpose: sweeping while finalizing a reservation could drop
+    // the very reservation being committed/released. Pure snapshot reads (get) and
+    // create() are likewise clock-independent.
+    async load(nowMs) {
+        try {
+            const doc = await readOwnerOnlyJson(this.path, 'card mandate ledger', LEDGER_MAX_BYTES);
+            if (!doc || !Array.isArray(doc.mandates)) {
+                return { version: CARD_MANDATE_LEDGER_VERSION, mandates: [] };
+            }
+            // One-time migration for pre-hardening ledgers. The budget mint is a
+            // bootstrap bearer used only during create/register and must not survive
+            // process exit. Scrub it eagerly on read, not merely on the next mutation.
+            let scrubbedBootstrapToken = false;
+            for (const mandate of doc.mandates) {
+                if (Object.prototype.hasOwnProperty.call(mandate, 'mintToken')) {
+                    delete mandate.mintToken;
+                    scrubbedBootstrapToken = true;
+                }
+            }
+            if (scrubbedBootstrapToken)
+                await writeOwnerOnlyJson(this.path, doc);
+            // Self-heal: prune reservations stranded by a crash before commit/release
+            // so `remaining` reflects reality. In-memory here; a mutating caller then
+            // persists the pruned state via save().
+            if (nowMs !== undefined)
+                sweepStaleReservations(doc, nowMs);
+            return doc;
+        }
+        catch (err) {
+            // A missing ledger is the normal first-run state.
+            if (err.code === 'ENOENT') {
+                return { version: CARD_MANDATE_LEDGER_VERSION, mandates: [] };
+            }
+            throw err;
+        }
+    }
+    async save(file) {
+        await writeOwnerOnlyJson(this.path, file);
+    }
+    /**
+     * Append a freshly-created mandate record. `now` drives the expired-mandate
+     * prune below; it defaults to the wall clock but is injectable so callers (and
+     * tests) can pin it — every other mutating method takes the same clock, and a
+     * real `new Date()` here would otherwise make the prune non-deterministic
+     * against fixtures dated relative to a fixed reference time.
+     */
+    create(record, now = new Date()) {
+        return this.run(async () => {
+            const file = await this.load();
+            if (file.mandates.some((m) => m.mandateId === record.mandateId)) {
+                throw new Error(`mandate ${record.mandateId} already exists in the ledger`);
+            }
+            // Bound ledger growth: drop mandates expired beyond the grace window. They
+            // are already invisible to `mandate list` and unselectable by findCovering,
+            // so nothing references them. A mandate with an unparseable expiry is kept
+            // (fail-safe — never prune what we cannot date).
+            const pruneBefore = now.getTime() - EXPIRED_PRUNE_GRACE_MS;
+            file.mandates = file.mandates.filter((m) => {
+                const exp = Date.parse(m.expiresAt);
+                return !Number.isFinite(exp) || exp >= pruneBefore;
+            });
+            // Even an older caller that still supplies the deprecated field cannot
+            // persist the bootstrap bearer.
+            const { mintToken: _discardedBootstrapToken, ...safeRecord } = record;
+            file.mandates.push(safeRecord);
+            await this.save(file);
+            return safeRecord;
+        });
+    }
+    /** Read a single mandate (no lock — a snapshot copy). */
+    async get(mandateId) {
+        const file = await this.load();
+        return file.mandates.find((m) => m.mandateId === mandateId) ?? null;
+    }
+    /**
+     * First ACTIVE mandate (not expired) whose merchant + currency match and whose
+     * remaining headroom covers amountMinor. Used by pay_merchant to decide the
+     * tap-free draw path vs the no-covering-mandate refusal (#7348).
+     */
+    async findCovering(query) {
+        const now = query.now ?? new Date();
+        const file = await this.load(now.getTime());
+        // Multiple mandates can now cover one merchant: a merchant-scoped mandate for
+        // this host AND any crossMerchant (budget) mandate both qualify (#6003). A
+        // mandate the network refused is skipped via `!m.unhonoredAt` so it can never
+        // be re-selected. A register-failed mandate is skipped the same way
+        // (`!m.registerFailedAt`): it has no server row, so a delegated draw would 404
+        // `no_mandate` — better to surface the no-covering refusal (#7348).
+        // Selection order among covering candidates:
+        //   1. Prefer a merchant-SCOPED mandate over a crossMerchant budget one —
+        //      spend the dedicated grant for this merchant first and keep the broader
+        //      broader retail budget for merchants that have no scoped mandate. Draining
+        //      the budget for a purchase a scoped mandate already covers both wastes
+        //      the general headroom and can later force a fresh tap at another merchant.
+        //   2. Then the MOST headroom, then the latest expiry — never let a near-empty
+        //      or near-expiry mandate get selected over a fuller, longer-lived sibling
+        //      and then fail a draw the sibling would have covered.
+        const candidates = file.mandates.filter((m) => 
+        // A crossMerchant retail budget is locally cross-host; a merchant-scoped
+        // one only matches its own host. Network Retail/5999 eligibility is
+        // enforced downstream and is not inferred from a website hostname.
+        (m.crossMerchant || m.merchantHost === query.merchantHost) &&
+            m.agentJkt === query.agentJkt &&
+            m.currencyCode.toUpperCase() === query.currencyCode.toUpperCase() &&
+            !m.unhonoredAt &&
+            !m.registerFailedAt &&
+            !m.serverRevokedAt &&
+            !isExpired(m, now) &&
+            hasDrawCountHeadroom(m) &&
+            remainingMinor(m) >= query.amountMinor);
+        candidates.sort((a, b) => 
+        // A scoped mandate (crossMerchant falsy → 0) sorts before a budget one (1).
+        (a.crossMerchant ? 1 : 0) - (b.crossMerchant ? 1 : 0) ||
+            remainingMinor(b) - remainingMinor(a) ||
+            Date.parse(b.expiresAt) - Date.parse(a.expiresAt));
+        return candidates[0] ?? null;
+    }
+    /**
+     * Mark a mandate as unhonored — the network declined a ceiling-scoped draw
+     * against it, so it must never be selected again. Atomic, owner-only write on
+     * the same serialized chain as every other mutation. Idempotent: a second
+     * call keeps the first timestamp. Throws only if the mandate is unknown.
+     */
+    markUnhonored(mandateId, now = new Date()) {
+        return this.run(async () => {
+            const file = await this.load();
+            const record = file.mandates.find((m) => m.mandateId === mandateId);
+            if (!record)
+                throw new Error(`no such mandate ${mandateId}`);
+            if (!record.unhonoredAt) {
+                record.unhonoredAt = now.toISOString();
+                await this.save(file);
+            }
+            return record;
+        });
+    }
+    /**
+     * Mark a mandate as register-failed — the delegated-draw register handshake
+     * did not create the server row at mandate-start, so it must never be selected
+     * for a (delegated) draw. Atomic, owner-only write on the same serialized chain
+     * as every other mutation. Idempotent: a second call keeps the first timestamp.
+     * Throws only if the mandate is unknown.
+     */
+    markRegisterFailed(mandateId, now = new Date()) {
+        return this.run(async () => {
+            const file = await this.load();
+            const record = file.mandates.find((m) => m.mandateId === mandateId);
+            if (!record)
+                throw new Error(`no such mandate ${mandateId}`);
+            if (!record.registerFailedAt) {
+                record.registerFailedAt = now.toISOString();
+                await this.save(file);
+            }
+            return record;
+        });
+    }
+    /**
+     * Retire a locally cached mandate after the authenticated account API proves
+     * it was revoked. This is idempotent and monotonic: an owner revocation can
+     * never be undone by a later stale/local read.
+     */
+    markServerRevoked(mandateId, revokedAt) {
+        return this.run(async () => {
+            const parsed = new Date(revokedAt);
+            if (Number.isNaN(parsed.getTime()))
+                throw new Error('server revocation timestamp is invalid');
+            const file = await this.load();
+            const record = file.mandates.find((m) => m.mandateId === mandateId);
+            if (!record)
+                throw new Error(`no such mandate ${mandateId}`);
+            if (!record.serverRevokedAt) {
+                record.serverRevokedAt = parsed.toISOString();
+                await this.save(file);
+            }
+            return record;
+        });
+    }
+    /**
+     * ONE SPENDING LIMIT: adopt the ceiling the SERVER actually approved.
+     *
+     * The requested ceiling is only a request. At register, auth clamps it to the
+     * owner's live card-grant cap (`min(requested, grant daily limit)`) and writes
+     * that. The local record used to keep the requested figure, so a runtime whose
+     * request exceeded the grant reported — and selected against — a budget the
+     * owner never approved. The draw still failed closed at auth's verdict, so it
+     * was never over-spend; it was the runtime lying about its own headroom and
+     * then hitting a decline it could not explain.
+     *
+     * LOWERS ONLY. A value at or above the current ceiling is ignored, not
+     * written: the server clamps downward, so a higher number means an unexpected
+     * response, and honouring it would let a client-observed value hand a runtime
+     * headroom no human approved. Cap authority stays server-side either way —
+     * this only stops the local copy from overstating it.
+     *
+     * Atomic and idempotent on the same serialized chain as every other mutation.
+     * Throws only if the mandate is unknown.
+     */
+    applyApprovedCeiling(mandateId, approvedCeilingMinor) {
+        return this.run(async () => {
+            assertPositiveInteger(approvedCeilingMinor, 'approved mandate ceiling');
+            const file = await this.load();
+            const record = file.mandates.find((m) => m.mandateId === mandateId);
+            if (!record)
+                throw new Error(`no such mandate ${mandateId}`);
+            if (approvedCeilingMinor >= record.ceilingMinor)
+                return record;
+            record.ceilingMinor = approvedCeilingMinor;
+            await this.save(file);
+            return record;
+        });
+    }
+    /**
+     * Atomically reserve headroom for a draw. Fail-closed: refuses when the
+     * mandate is unknown, expired, or the amount exceeds remaining headroom. The
+     * reservation counts against availability immediately, closing the window in
+     * which two concurrent draws both see the same remaining balance.
+     */
+    reserve(mandateId, amountMinor, now = new Date()) {
+        return this.run(async () => {
+            assertPositiveInteger(amountMinor, 'draw amount');
+            // Sweep with the draw's clock so a crash-stranded reservation cannot block
+            // a legitimate draw; the save() below persists the pruned state.
+            const file = await this.load(now.getTime());
+            const record = file.mandates.find((m) => m.mandateId === mandateId);
+            if (!record)
+                throw new Error(`no such mandate ${mandateId}`);
+            if (isExpired(record, now)) {
+                throw new Error(`mandate ${mandateId} expired at ${record.expiresAt}`);
+            }
+            if (amountMinor > remainingMinor(record)) {
+                throw new Error(`draw ${amountMinor} exceeds remaining budget ${remainingMinor(record)} (minor units)`);
+            }
+            if (!hasDrawCountHeadroom(record)) {
+                throw new Error(`mandate ${mandateId} reached its approved purchase-count limit`);
+            }
+            const reservationId = `rsv_${randomBytes(9).toString('base64url')}`;
+            record.reservations.push({ reservationId, amountMinor, reservedAt: now.toISOString() });
+            await this.save(file);
+            return reservationId;
+        });
+    }
+    /** Commit a reservation to permanent spend and record the payable draw. */
+    commit(mandateId, reservationId, meta, now = new Date()) {
+        return this.run(async () => {
+            const file = await this.load();
+            const record = file.mandates.find((m) => m.mandateId === mandateId);
+            if (!record)
+                throw new Error(`no such mandate ${mandateId}`);
+            const idx = record.reservations.findIndex((r) => r.reservationId === reservationId);
+            if (idx === -1) {
+                throw new Error(`reservation ${reservationId} is not open (already committed or released)`);
+            }
+            const [reservation] = record.reservations.splice(idx, 1);
+            record.spentMinor += reservation.amountMinor;
+            record.draws.push({
+                drawId: `drw_${randomBytes(9).toString('base64url')}`,
+                reservationId,
+                amountMinor: reservation.amountMinor,
+                intentId: meta.intentId,
+                status: 'committed',
+                at: now.toISOString(),
+            });
+            await this.save(file);
+            return record;
+        });
+    }
+    /** Release a reservation back to availability (draw failed / not payable). */
+    release(mandateId, reservationId, now = new Date()) {
+        return this.run(async () => {
+            const file = await this.load();
+            const record = file.mandates.find((m) => m.mandateId === mandateId);
+            if (!record)
+                throw new Error(`no such mandate ${mandateId}`);
+            const idx = record.reservations.findIndex((r) => r.reservationId === reservationId);
+            if (idx === -1) {
+                // Idempotent by refusal: a committed/released reservation cannot be
+                // released again, but a redundant release must not corrupt state.
+                return record;
+            }
+            const [reservation] = record.reservations.splice(idx, 1);
+            record.draws.push({
+                drawId: `drw_${randomBytes(9).toString('base64url')}`,
+                reservationId,
+                amountMinor: reservation.amountMinor,
+                intentId: record.mandateId,
+                status: 'released',
+                at: now.toISOString(),
+            });
+            await this.save(file);
+            return record;
+        });
+    }
+}
+export function defaultLedgerPath() {
+    return (process.env.VISA_CARD_MANDATE_LEDGER_FILE ?? join(homedir(), '.visa-mcp', 'card-mandates.json'));
+}

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

@@ -1,5 +1,5 @@
 import type { Page } from 'playwright-core';
-export type OutcomeStatus = 'confirmed' | 'declined' | 'action-required' | 'processing' | 'unknown';
+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". */
@@ -8,7 +8,7 @@ export type OutcomeClassification = {
 /** 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' | 'unknown';
+    status: 'confirmed' | 'declined' | 'action-required' | 'verification-required' | 'unknown';
     signal: string | null;
     /** Last non-final classification when the deadline expired ('processing' | 'unknown'). */
     lastSeen: OutcomeStatus;

package/dist/checkout-engine/outcome.js

@@ -65,11 +65,34 @@ const ACTION_REQUIRED_URL = [
 // 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>".
-const ACTION_REQUIRED_BODY = [
+// 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/ },
@@ -122,6 +145,15 @@ export function classifyOutcomePage(url, bodyText, frameUrls = []) {
         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 };
@@ -167,6 +199,9 @@ export async function observeOutcome(page, opts = {}) {
         // 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,

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

@@ -8,3 +8,12 @@
 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

@@ -1,4 +1,6 @@
-import { lstat, readFile } from 'node:fs/promises';
+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.
@@ -20,3 +22,20 @@ 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/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

@@ -1,7 +1,8 @@
 import type { EvidenceStep } from './evidence.js';
 import type { CheckoutMode, CheckoutOutcome, CheckoutResult, CredentialLifecycle, CredentialTiming } from './executor.js';
 import type { VicConfirmationReport } from './vic-confirmation.js';
-export type CheckoutReceipt = {
+/** Published v1 artifact shape. Retained so patch releases remain readable/typable. */
+export type CheckoutReceiptV1 = {
     schema: 'checkout-agent-receipt/v1';
     recordedAt: string;
     mode: CheckoutMode;
@@ -32,6 +33,55 @@ export type CheckoutReceipt = {
         snapshotSummary: string | null;
     };
 };
+export type CheckoutReceiptV2 = {
+    schema: 'checkout-agent-receipt/v2';
+    recordedAt: string;
+    /** Correlates terminal pre-review observations that have no reviewId yet. */
+    observationId?: string;
+    /** Explicitly distinguishes pre-submit review observations from payment attempts. */
+    phase?: 'review';
+    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;
+    };
+    /**
+     * Capability evidence for unsuccessful checkout surfaces. Optional so
+     * previously published v2 receipt producers remain source-compatible.
+     */
+    capability?: {
+        failureCode: string | null;
+        detectedRoles: string[];
+        requiresAdapter: string[];
+    };
+    /** 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;
@@ -43,9 +93,11 @@ export type ReceiptWriteReport = {
 export declare function buildReceipt(input: {
     mode: CheckoutMode;
     reviewId: string | null;
+    observationId?: string;
     merchant: {
         name: string;
         host: string;
+        url?: string;
     };
     transaction: {
         amount: string;
@@ -54,9 +106,11 @@ export declare function buildReceipt(input: {
     };
     result: CheckoutResult;
     vicConfirmation: VicConfirmationReport | null;
+    agentName?: string;
+    cardLast4?: string;
     /** Injectable for tests; defaults to now. */
     recordedAt?: Date;
-}): CheckoutReceipt;
+}): CheckoutReceiptV2;
 /**
  * Defense-in-depth scrub before anything touches disk: any standalone
  * 12–19-digit run that passes Luhn is replaced — contiguous OR separated by