@visa/cli 4.1.0-rc.107 → 4.1.0-rc.109

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

@@ -177,6 +177,12 @@ export interface CardMandateRegisterSeam {
     }) => Promise<{
         ok: boolean;
         reason?: string;
+        /**
+         * The ceiling the server committed — `min(requested, the owner's live card
+         * grant cap)`. Omitted by an older auth that does not report it, in which
+         * case the requested ceiling stands.
+         */
+        approvedCeilingMinor?: number;
     }>;
 }
 export type CliEngineDeps = {

package/dist/checkout-engine/cli-engine.js

@@ -16,7 +16,7 @@ import { readFile } from 'node:fs/promises';
 import { launchCheckoutBrowser } from './browser-launch.js';
 import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
 import { claimMandatePickup as realClaimMandatePickup, runHostedApproval as realRunHostedApproval, } from './hosted-approval.js';
-import { VgsAssuranceInstrument, VgsLiveInstrument, decimalToMinor, } from './vgs-live-instrument.js';
+import { VgsAssuranceInstrument, VgsLiveInstrument, decimalToMinor, minorToDecimal, } from './vgs-live-instrument.js';
 import { serverCreateIntent, serverFetchCryptogram, serverPostConfirmation, } from './vgs-gateway/server-mint-client.js';
 import { createCardMandate, DEFAULT_MANDATE_MAX_DRAWS, drawFromMandate, MandateDrawDeclinedError, } from './mandate/card-mandate.js';
 import { MandateLedger } from './mandate/mandate-ledger.js';
@@ -140,6 +140,21 @@ export function createCliCheckoutEngine(deps = {}) {
             transactionCurrencyCode: input.currency,
         };
     }
+    /**
+     * Restate the facts at the ceiling the SERVER approved, when it lowered the
+     * one that was requested. Nothing has been spent or reserved on a mandate this
+     * new, so its remaining headroom IS its ceiling — see `createCardMandate`,
+     * which records `spentMinor: 0` with no reservations.
+     *
+     * Only ever lowers, mirroring `applyApprovedCeiling`: the server clamps
+     * downward, so a higher number means an unexpected response and is ignored
+     * rather than reported as headroom no human approved.
+     */
+    function approvedCeilingFacts(facts, approvedCeilingMinor) {
+        if (approvedCeilingMinor === undefined || approvedCeilingMinor >= facts.ceilingMinor)
+            return {};
+        return { ceilingMinor: approvedCeilingMinor, remainingMinor: approvedCeilingMinor };
+    }
     // Seed the one server-authoritative cumulative store keyed by the VGS intent
     // ID (#5942). On failure the local record is marked register-failed so
     // findCovering() SKIPS it — the mandate exists but is never drawn tap-free —
@@ -162,8 +177,50 @@ export function createCliCheckoutEngine(deps = {}) {
             ok: false,
             reason: err instanceof Error ? err.message : String(err),
         }));
-        if (reg.ok)
-            return { registerFailed: false };
+        if (reg.ok) {
+            // ONE SPENDING LIMIT: auth just clamped the requested ceiling to the
+            // owner's live grant cap and told us what it committed. Adopt it, so the
+            // local record — which findCovering() selects on and `mandate list`
+            // prints — states the budget the owner actually approved. Best-effort:
+            // the mandate is registered and drawable either way, and auth's verdict
+            // remains the enforcing cap, so a failed local write must not abort the
+            // ceremony. It leaves the record overstating headroom, which is exactly
+            // the pre-existing behaviour.
+            //
+            // If that write fails the returned facts still carry the approved figure —
+            // telling the human the truth beats echoing a ceiling their grant refused,
+            // and the ledger is left exactly as overstated as it was before this
+            // existed. But the two then disagree, so say so out loud rather than let
+            // `mandate list` quietly contradict what `mandate start` just printed.
+            // Same posture as the mark-failed escalation below.
+            if (reg.approvedCeilingMinor !== undefined) {
+                const applied = await ledger
+                    .applyApprovedCeiling(args.mandateId, reg.approvedCeilingMinor)
+                    .then(() => true)
+                    .catch(() => false);
+                if (!applied) {
+                    // Rendered through minorToDecimal, never raw /100 — and only when the
+                    // value is a sane integer, because THIS branch is also where an
+                    // unusable value lands (applyApprovedCeiling rejects it). A warning
+                    // must not throw on its way out. The currency is omitted deliberately:
+                    // both mandate paths refuse anything but USD long before register, so
+                    // it is known, and passing it would let a non-2-decimal code throw here.
+                    const approved = Number.isSafeInteger(reg.approvedCeilingMinor) && reg.approvedCeilingMinor > 0
+                        ? ` (${args.currency} ${minorToDecimal(reg.approvedCeilingMinor)})`
+                        : '';
+                    process.stderr.write(`warning: your owner's approved limit for this budget${approved} could NOT be saved ` +
+                        `locally — 'mandate list' will overstate the remaining balance until you re-run ` +
+                        `'mandate start'. Spending is still capped at the approved limit; a draw over it ` +
+                        `is refused. mandateId=${args.mandateId}\n`);
+                }
+            }
+            return {
+                registerFailed: false,
+                ...(reg.approvedCeilingMinor !== undefined
+                    ? { approvedCeilingMinor: reg.approvedCeilingMinor }
+                    : {}),
+            };
+        }
         // Register failed: the server `card_mandate_spend` row was never created, so
         // a delegated draw against this mandate would 404 `no_mandate`. Mark it
         // register-failed so findCovering() SKIPS it and the owner's next checkout
@@ -176,8 +233,8 @@ export function createCliCheckoutEngine(deps = {}) {
             .catch(() => false);
         process.stderr.write(marked
             ? `warning: card-mandate register failed (${reg.reason ?? 'unknown'}) — this mandate ` +
-                `will NOT be used for tap-free draws; your next checkout will use a fresh ` +
-                `per-purchase passkey tap. Re-run 'mandate start' to try again.\n`
+                `will NOT be used for tap-free draws; your next checkout will interrupt the owner ` +
+                `for a fresh per-purchase approval. Re-run 'mandate start' to try again.\n`
             : // Escalate: the mark write ALSO failed, so the mandate is persisted but
                 // NOT disabled — findCovering could still select an undrawable mandate.
                 // Tell the owner loudly not to rely on it and how to recover.
@@ -293,6 +350,7 @@ export function createCliCheckoutEngine(deps = {}) {
             });
             return {
                 ...facts,
+                ...approvedCeilingFacts(facts, registered.approvedCeilingMinor),
                 merchantHost: new URL(merchant.url).hostname,
                 registerFailed: registered.registerFailed,
                 ...(registered.registerFailureReason !== undefined
@@ -353,6 +411,7 @@ export function createCliCheckoutEngine(deps = {}) {
             });
             return {
                 ...facts,
+                ...approvedCeilingFacts(facts, registered.approvedCeilingMinor),
                 merchantHost: new URL(claim.merchant.url).hostname,
                 registerFailed: registered.registerFailed,
                 ...(registered.registerFailureReason !== undefined
@@ -564,7 +623,7 @@ export function createCliCheckoutEngine(deps = {}) {
                             confirmationRef: null,
                             receiptPath: null,
                             detail: 'this mandate cannot draw because its delegated card authority is unavailable; ' +
-                                'restore the runtime binding or use a fresh per-purchase passkey approval',
+                                'restore the runtime binding or use a fresh per-purchase approval',
                             vicConfirmation: null,
                             source,
                             remainingMinor: null,
@@ -662,7 +721,7 @@ export function createCliCheckoutEngine(deps = {}) {
                                     }
                                     throw new Error(verdictFailure.transient
                                         ? `the card-mandate draw could not be authorized right now (${verdictFailure.reasons.join(', ') || 'temporary error'}) — retry shortly`
-                                        : `this card mandate can no longer be drawn (${verdictFailure.reasons.join(', ') || 'refused'}); it has been disabled — retry the checkout to use a fresh per-purchase passkey tap`, { cause: err });
+                                        : `this card mandate can no longer be drawn (${verdictFailure.reasons.join(', ') || 'refused'}); it has been disabled — retry the checkout to use a fresh per-purchase approval`, { cause: err });
                                 }
                                 if (!isTransientDrawFailure(err.cause ?? err)) {
                                     await ledger.markUnhonored(mandateId, now());

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

@@ -93,6 +93,7 @@ export type SubmitApprovedCheckoutOptions = {
     onChallengeHold?: (signal: string | null) => void;
     resolveEmailOtp?: OtpResolver;
 };
+export declare function snapshotOrigin(rawUrl: string): string;
 export type PreparedCheckoutSession = {
     checkout: PreparedCheckout;
     context: BrowserContext;

package/dist/checkout-engine/executor.js

@@ -145,6 +145,19 @@ async function findSubmit(page) {
     }
     return null;
 }
+// The diagnostic snapshot records the page ORIGIN only, never the full URL: a
+// payment-session path/query (e.g. a live Stripe `cs_live_...` checkout-session
+// id) must not be retained in the local receipt, which elsewhere promises
+// "hostname only" (#7101). Falls back to the raw value only if it does not parse
+// as a URL (never a real page.url()).
+export function snapshotOrigin(rawUrl) {
+    try {
+        return new URL(rawUrl).origin;
+    }
+    catch {
+        return '';
+    }
+}
 async function snapshotSummary(page) {
     const info = await page
         .evaluate(() => {
@@ -153,7 +166,7 @@ async function snapshotSummary(page) {
         return { title: document.title, heading: heading?.textContent?.trim() || '', body };
     })
         .catch(() => ({ title: '', heading: '', body: '' }));
-    return `url=${page.url()} title="${info.title}" heading="${info.heading}" body="${info.body}"`;
+    return `url=${snapshotOrigin(page.url())} title="${info.title}" heading="${info.heading}" body="${info.body}"`;
 }
 async function readConfirmationRef(page) {
     const ref = await page

package/dist/checkout-engine/hosted-approval.js

@@ -155,7 +155,12 @@ export async function runHostedApproval(opts) {
     const verifier = randomBytes(32).toString('base64url');
     const challenge = createHash('sha256').update(verifier, 'utf8').digest('base64url');
     const deadline = now() + timeoutMs;
-    const timeoutError = () => new Error(`no passkey approval within ${Math.round(timeoutMs / 1000)}s — ` +
+    // Verification-neutral: what the page asks the human for is a per-card
+    // property (passkey ceremony, issuer one-time code, or nothing beyond the
+    // signed-in approval) that this runner never learns. Naming a passkey here
+    // told operators on code-verified cards to wait for a device prompt that was
+    // never coming, and then blamed the timeout on the step they never saw.
+    const timeoutError = () => new Error(`no approval within ${Math.round(timeoutMs / 1000)}s — ` +
         'the checkout was cancelled; run again to retry');
     // Bound EVERY request by the remaining deadline: race the fetch against the
     // (injectable) sleep and abort the request when the deadline wins, so a
@@ -312,7 +317,7 @@ export async function runHostedApproval(opts) {
                     }
                     log(assuranceExempt
                         ? 'approval received from the hosted page (code-verified card, no passkey).'
-                        : 'passkey approval received from the hosted page.');
+                        : 'approval received from the hosted page (passkey-verified card).');
                     return {
                         ...assuranceFromCeremony(target, doc.assuranceData ?? null),
                         ...(assuranceExempt ? { assuranceExempt: true } : {}),

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

@@ -127,6 +127,27 @@ export declare class MandateLedger {
      * Throws only if the mandate is unknown.
      */
     markRegisterFailed(mandateId: string, now?: Date): 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

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

@@ -252,6 +252,40 @@ export class MandateLedger {
             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