@visa/cli 4.1.0-rc.9 → 4.1.0-rc.91

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

@@ -0,0 +1,227 @@
+// Card mandate (budget) layer — the split the north-star card flow needs:
+//
+//   BUDGET  = start_card_mandate: approve a CEILING once with the passkey. This
+//             mints ONE VGS intent whose decline threshold is the ceiling (not
+//             amount+10) and whose quantity permits many draws. The passkey
+//             assurance is scoped to the ceiling + merchant, not one charge.
+//   DRAW    = pay_merchant (tap-free): pull a cryptogram against that intent for
+//             an in-budget purchase, WITHOUT a fresh tap, and decrement the
+//             cumulative budget in the owner-only ledger.
+//
+// This mirrors x402's start_session -> wallet_pay shape on the card rail.
+//
+// PROVEN (live probe 2026-07-23): VGS honors a ceiling-scoped assurance across
+// multiple sub-amount cryptogram draws against one intent, AND enforces the
+// decline threshold as a CUMULATIVE cap — draws summing to the ceiling are
+// payable, the next draw over the cumulative ceiling is declined. So the total
+// the network authorizes is the ceiling, not maxDraws × ceiling. drawFromMandate
+// stays FAIL-CLEAN as defense-in-depth: the budget is decremented only after a
+// payable cryptogram returns; a network rejection leaves the budget untouched.
+// The caller (cli-engine) then marks the mandate unhonored so the NEXT
+// pay_merchant skips it and takes a fresh per-purchase tap — the same call is
+// not retried in-flight. Never fail-open.
+import { decimalToMinor, minorToDecimal, validateCredential, } from '../vgs-live-instrument.js';
+import { CARD_MANDATE_LEDGER_VERSION, remainingMinor, } from './mandate-ledger.js';
+/**
+ * Default number of draws a ceiling intent may fulfil (VGS mandate quantity).
+ * This is a purchase-COUNT cap, NOT the exposure bound: VGS enforces the
+ * declineThreshold as a CUMULATIVE cap across draws (live-verified 2026-07-23),
+ * so the total the network will authorize is the ceiling REGARDLESS of how many
+ * draws it is spread across — maxDraws only limits the number of separate
+ * purchases, it does not multiply the exposure. Kept SMALL as a sensible default
+ * purchase count (the owner-side client ledger also caps cumulative spend at ONE
+ * ceiling). This is the single default; callers that don't set maxDraws inherit
+ * it (do not re-duplicate it upstream).
+ */
+export const DEFAULT_MANDATE_MAX_DRAWS = 3;
+function assertPositiveInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`${label} must be a positive integer (minor units)`);
+    }
+}
+function merchantHost(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        throw new Error(`mandate merchant URL is invalid: ${url}`);
+    }
+}
+/**
+ * Create a card mandate: approve a spend CEILING once (the passkey assurance
+ * passed here was scoped to the ceiling + merchant), mint one VGS intent with
+ * that ceiling as its decline threshold, and record the cumulative-budget
+ * ledger entry. Integer minor units only.
+ */
+export async function createCardMandate(input, deps) {
+    assertPositiveInteger(input.ceilingMinor, 'mandate ceiling');
+    const currencyCode = String(input.currencyCode).toUpperCase();
+    if (!/^[A-Z]{3}$/.test(currencyCode)) {
+        throw new Error('mandate currency must be a 3-letter ISO 4217 code');
+    }
+    if (!input.tokenId?.trim())
+        throw new Error('mandate requires a tokenId');
+    if (!/^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/.test(input.agentJkt)) {
+        throw new Error('mandate requires a canonical agent request-key JKT');
+    }
+    const now = (deps.now ?? (() => new Date()))();
+    const expiryMs = Date.parse(input.expiresAt);
+    if (!Number.isFinite(expiryMs))
+        throw new Error('mandate expiresAt must be ISO 8601');
+    if (expiryMs <= now.getTime())
+        throw new Error('mandate expiresAt is already in the past');
+    const host = merchantHost(input.merchant.url);
+    const maxDraws = input.maxDraws ?? DEFAULT_MANDATE_MAX_DRAWS;
+    if (!Number.isSafeInteger(maxDraws) || maxDraws < 1) {
+        throw new Error('mandate maxDraws must be a positive integer');
+    }
+    // Pass the currency so a non-2-decimal currency is REFUSED here rather than
+    // silently rendered with a wrong wire amount (minorToDecimal assumes /100).
+    const ceilingDecimal = minorToDecimal(input.ceilingMinor, currencyCode);
+    // The passkey prompt must state the REAL grant. VGS enforces the
+    // declineThreshold as a CUMULATIVE cap across draws (live-verified 2026-07-23),
+    // so the total this single approval can authorize is the CEILING — not
+    // maxDraws × ceiling. maxDraws only caps how many separate purchases the intent
+    // may fulfil. The prompt therefore names the ceiling as the total and maxDraws
+    // as the purchase-count limit (H1: consent must match the true grant).
+    // The intent transaction is scoped to the CEILING itself: the decline
+    // threshold IS the ceiling (not the historical ceil(amount)+10), and quantity
+    // permits multiple draws.
+    const ceilingTarget = {
+        merchantName: input.merchant.name,
+        merchantUrl: input.merchant.url,
+        merchantCountryCode: input.merchant.countryCode.toUpperCase(),
+        transactionAmount: ceilingDecimal,
+        transactionCurrencyCode: currencyCode,
+    };
+    const { intentId } = await deps.createIntent({
+        tokenId: input.tokenId,
+        assuranceData: input.assuranceData,
+        transaction: ceilingTarget,
+        mandate: {
+            declineThresholdAmount: ceilingDecimal,
+            quantity: maxDraws,
+            effectiveUntil: new Date(expiryMs).toISOString(),
+            consumerPrompt: `Approve up to ${ceilingDecimal} ${currencyCode} total (across up to ` +
+                `${maxDraws} purchase${maxDraws === 1 ? '' : 's'}) at ${input.merchant.name} ` +
+                `for my Visa agent`,
+        },
+    });
+    if (!intentId?.trim())
+        throw new Error('mandate intent creation returned no intentId');
+    const record = {
+        version: CARD_MANDATE_LEDGER_VERSION,
+        mandateId: intentId,
+        agentJkt: input.agentJkt,
+        tokenId: input.tokenId,
+        ceilingMinor: input.ceilingMinor,
+        spentMinor: 0,
+        reservations: [],
+        currencyCode,
+        merchantName: input.merchant.name,
+        merchantUrl: input.merchant.url,
+        merchantHost: host,
+        merchantCountryCode: input.merchant.countryCode.toUpperCase(),
+        approvalBaseUrl: deps.approvalBaseUrl,
+        ...(deps.mintToken ? { mintToken: deps.mintToken } : {}),
+        expiresAt: new Date(expiryMs).toISOString(),
+        maxDraws,
+        createdAt: now.toISOString(),
+        draws: [],
+        ...(input.crossMerchant ? { crossMerchant: true } : {}),
+    };
+    await deps.ledger.create(record, now);
+    return {
+        mandateId: record.mandateId,
+        ceilingMinor: record.ceilingMinor,
+        remainingMinor: remainingMinor(record),
+        currencyCode,
+        merchant: input.merchant,
+        expiresAt: record.expiresAt,
+        maxDraws,
+    };
+}
+const DRAW_REMEDY = 'the card-mandate draw did not complete — a ceiling-scoped assurance may not be honored ' +
+    'for this sub-amount draw. The budget is untouched. If this was a transient network error ' +
+    '(gateway 5xx / try again), retry — the mandate stays active; a persistent decline disables ' +
+    'the mandate and your next pay_merchant uses a fresh per-purchase tap';
+/**
+ * Thrown ONLY for the post-reservation network/validation rejection class — the
+ * cryptogram fetch failed or returned a non-payable credential (the DRAW_REMEDY
+ * path). This is the sole draw failure that should DISABLE the mandate: it means
+ * the acquirer would not honor a ceiling-scoped assurance for a sub-amount draw.
+ *
+ * Pre-network failures — a fail-closed `reserve()` (concurrent over-budget race
+ * or expiry) or a `commit()` file-I/O error — throw a plain Error instead, so
+ * the caller (cli-engine) can rethrow them WITHOUT marking a HEALTHY mandate
+ * unhonored. Discriminating on this type is what keeps a transient race from
+ * permanently disabling a good mandate (michaelyang1 M1).
+ */
+export class MandateDrawDeclinedError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = 'MandateDrawDeclinedError';
+        this.cause = cause;
+    }
+}
+/**
+ * Draw a cryptogram against an existing card mandate with NO fresh tap. The
+ * reservation is atomic and the budget is decremented ONLY after a payable
+ * cryptogram returns; any rejection releases the reservation so remaining is
+ * unchanged. Validates merchant + currency + amount against the mandate first.
+ */
+export async function drawFromMandate(input, deps) {
+    assertPositiveInteger(input.amountMinor, 'draw amount');
+    const validate = deps.validate ?? validateCredential;
+    const now = (deps.now ?? (() => new Date()))();
+    const record = await deps.ledger.get(input.mandateId);
+    if (!record)
+        throw new Error(`no such mandate ${input.mandateId}`);
+    // The wire amount and the accounting amount MUST agree — a mismatch would
+    // draw one figure while reserving another. Fail before any reservation.
+    const wireMinor = decimalToMinor(input.transaction.transactionAmount);
+    if (wireMinor === null || wireMinor !== input.amountMinor) {
+        throw new Error(`draw amount ${input.amountMinor} disagrees with transaction amount ` +
+            `${JSON.stringify(input.transaction.transactionAmount)} (minor units)`);
+    }
+    // Currency must always match; merchant must match UNLESS this is a budget
+    // (crossMerchant) mandate the owner approved for eligible retail merchants. The network
+    // honors a ceiling-scoped cryptogram cross-merchant, so a budget mandate is
+    // deliberately not host-restricted — the ceiling + per-transaction limit still
+    // bound it.
+    const targetHost = merchantHost(input.transaction.merchantUrl);
+    if (!record.crossMerchant && targetHost !== record.merchantHost) {
+        throw new Error(`draw merchant ${targetHost} does not match mandate merchant ${record.merchantHost}`);
+    }
+    if (String(input.transaction.transactionCurrencyCode).toUpperCase() !==
+        record.currencyCode.toUpperCase()) {
+        throw new Error(`draw currency ${input.transaction.transactionCurrencyCode} does not match mandate ` +
+            `currency ${record.currencyCode}`);
+    }
+    // Atomic reserve — throws (fail-closed) if expired or over remaining budget.
+    const reservationId = await deps.ledger.reserve(input.mandateId, input.amountMinor, now);
+    let payment;
+    try {
+        payment = await deps.fetchCryptogram({
+            tokenId: record.tokenId,
+            intentId: record.mandateId,
+            transaction: input.transaction,
+        });
+        // A 2xx that is not actually a payable DAVV must NOT decrement the budget.
+        validate(payment);
+    }
+    catch (err) {
+        await deps.ledger.release(input.mandateId, reservationId, now);
+        // Typed so the caller disables the mandate ONLY for this post-reservation
+        // network/validation decline — never for a pre-network reserve()/commit()
+        // failure, which throws a plain Error above/below this try.
+        throw new MandateDrawDeclinedError(`${DRAW_REMEDY}: ${err.message}`, err);
+    }
+    const committed = await deps.ledger.commit(input.mandateId, reservationId, { intentId: record.mandateId }, now);
+    return {
+        payment,
+        intentId: record.mandateId,
+        remainingMinor: remainingMinor(committed),
+    };
+}

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

@@ -0,0 +1,142 @@
+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;
+    /**
+     * Scoped token released by the ceiling approval. It bootstraps the one intent
+     * + register ceremony only. Each cryptogram AND its outcome confirmation use
+     * the exact per-draw verdict instead. Owner-only (0600).
+     */
+    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 falls through to a fresh per-purchase tap 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 falls
+     * through to a fresh per-purchase tap instead of surfacing a confusing
+     * `no_mandate`. Mandate-start requires delegated card authority, so every
+     * created record attempted registration. ISO 8601.
+     */
+    registerFailedAt?: 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;
+    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 a fresh per-purchase tap.
+     */
+    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>;
+    /**
+     * 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;