@visa/cli 4.1.0-rc.21 → 4.1.0-rc.210

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

@@ -0,0 +1,174 @@
+export declare const CARD_MANDATE_LEDGER_VERSION: 1;
+export type CardMandateReservation = {
+    reservationId: string;
+    amountMinor: number;
+    reservedAt: string;
+};
+export type CardMandateDraw = {
+    drawId: string;
+    reservationId: string;
+    amountMinor: number;
+    intentId: string;
+    status: 'committed' | 'released';
+    at: string;
+};
+export type CardMandateRecord = {
+    version: typeof CARD_MANDATE_LEDGER_VERSION;
+    /** == the VGS intentId the ceiling approval created. */
+    mandateId: string;
+    /** Exact runtime request key this budget was issued to. Absent on legacy rows. */
+    agentJkt?: string;
+    tokenId: string;
+    ceilingMinor: number;
+    /** Permanently committed (drawn) spend, integer minor units. */
+    spentMinor: number;
+    /** In-flight reservations (reserved but not yet committed/released). */
+    reservations: CardMandateReservation[];
+    currencyCode: string;
+    merchantName: string;
+    merchantUrl: string;
+    merchantHost: string;
+    merchantCountryCode: string;
+    /** verify-web origin the ceiling intent was minted against. */
+    approvalBaseUrl: string;
+    /** @deprecated Read-migration only. New writers never persist this bearer. */
+    mintToken?: string;
+    expiresAt: string;
+    /** Network purchase-count cap disclosed at approval. Absent on legacy rows. */
+    maxDraws?: number;
+    createdAt: string;
+    draws: CardMandateDraw[];
+    /**
+     * Set when the network DECLINED a tap-free draw against this mandate (a
+     * ceiling-scoped assurance the acquirer would not honor for a sub-amount
+     * draw). Distinct from a reservation `status`: it disables the whole mandate.
+     * Once set, findCovering() SKIPS this mandate so the caller's next
+     * pay_merchant surfaces the no-covering-mandate refusal (#7348) instead of
+     * re-selecting the same failing mandate forever. ISO 8601.
+     */
+    unhonoredAt?: string;
+    /**
+     * Set when the delegated-draw register handshake FAILED at mandate-start (the
+     * server-side `card_mandate_spend` row was never created), so a later
+     * delegated (verdict-signed) draw would 404 `no_mandate`. Like `unhonoredAt`,
+     * findCovering() SKIPS a register-failed mandate so the next checkout
+     * surfaces the no-covering-mandate refusal (#7348) instead of a confusing
+     * `no_mandate`. Mandate-start requires delegated card authority, so every
+     * created record attempted registration. ISO 8601.
+     */
+    registerFailedAt?: string;
+    /**
+     * Set after an authenticated owner-scoped server read proves this mandate was
+     * revoked. The local file is only an execution cache; server revocation is
+     * canonical and permanently retires the cached mandate from selection while
+     * retaining its receipt history for the owner.
+     */
+    serverRevokedAt?: string;
+    /**
+     * A cross-host retail budget, not scoped to one `merchantHost`. The local
+     * selector may attempt it at any host, while the provider/network still
+     * applies the approved Retail/5999 category plus amount/count/time controls.
+     * `crossMerchant` is retained as the version-1 persisted field name.
+     */
+    crossMerchant?: boolean;
+};
+export type CardMandateLedgerFile = {
+    version: typeof CARD_MANDATE_LEDGER_VERSION;
+    mandates: CardMandateRecord[];
+};
+export type CoverQuery = {
+    merchantHost: string;
+    currencyCode: string;
+    amountMinor: number;
+    /** Exact selected request key; omitted means legacy unbound mandates only. */
+    agentJkt?: string;
+    now?: Date;
+};
+/** Available headroom = ceiling - committed - reserved. Integer minor units. */
+export declare function remainingMinor(record: CardMandateRecord): number;
+/**
+ * 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 declare class MandateLedger {
+    private readonly path;
+    private chain;
+    constructor(path?: string);
+    /** Serialize a read-modify-write so concurrent draws can't race the file. */
+    private run;
+    private load;
+    private save;
+    /**
+     * 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: CardMandateRecord, now?: Date): Promise<CardMandateRecord>;
+    /** Read a single mandate (no lock — a snapshot copy). */
+    get(mandateId: string): Promise<CardMandateRecord | 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).
+     */
+    findCovering(query: CoverQuery): Promise<CardMandateRecord | 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: string, now?: Date): Promise<CardMandateRecord>;
+    /**
+     * 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: string, now?: Date): Promise<CardMandateRecord>;
+    /**
+     * 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: string, revokedAt: string): Promise<CardMandateRecord>;
+    /**
+     * 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: string, approvedCeilingMinor: number): Promise<CardMandateRecord>;
+    /**
+     * 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: string, amountMinor: number, now?: Date): Promise<string>;
+    /** Commit a reservation to permanent spend and record the payable draw. */
+    commit(mandateId: string, reservationId: string, meta: {
+        intentId: string;
+    }, now?: Date): Promise<CardMandateRecord>;
+    /** Release a reservation back to availability (draw failed / not payable). */
+    release(mandateId: string, reservationId: string, now?: Date): Promise<CardMandateRecord>;
+}
+export declare function defaultLedgerPath(): string;

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,