@visa/cli 4.1.0-rc.112 → 4.1.0-rc.114

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

@@ -98,6 +98,12 @@ export type CliClaimMandateInput = {
     agentRef?: string;
     /** Single-use pickup code the owner handed over from the panel. */
     pickupCode: string;
+    /**
+     * The agent handoff this runtime just redeemed, when the pickup code rode
+     * inside its claim code. A dialog-minted budget pins that handoff instead of
+     * a key — there was no key yet — so this is what the pin is checked against.
+     */
+    expectedHandoffId?: string;
     credentialPath: string;
     /** See {@link CardInstrumentSource}. */
     cardTokenId?: string;

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

@@ -374,6 +374,7 @@ export function createCliCheckoutEngine(deps = {}) {
                 baseUrl: input.approvalBaseUrl,
                 pickupCode: input.pickupCode,
                 agentJkt: registerCap.agentJkt,
+                ...(input.expectedHandoffId ? { expectedHandoffId: input.expectedHandoffId } : {}),
                 tokenId: credential.tokenId,
             });
             const ceilingMinor = decimalToMinor(claim.ceiling);

package/dist/checkout-engine/hosted-approval.d.ts

@@ -174,6 +174,13 @@ export type ClaimMandatePickupOptions = {
     pickupCode: string;
     /** This runtime's exact current request-key JKT — the only key the code may fund. */
     agentJkt: string;
+    /**
+     * The agent handoff this runtime just redeemed, when the code came from one.
+     * A budget minted in the Add-agent dialog exists before the agent does, so it
+     * pins the handoff rather than a key; this is the value that pin is compared
+     * against. Absent for the panel flow, whose budgets pin a key instead.
+     */
+    expectedHandoffId?: string;
     /** The card token id this runtime's card authority points at. */
     tokenId: string;
     fetchImpl?: typeof fetch;

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

@@ -358,7 +358,7 @@ function pickupMismatch(field, detail) {
         'mandate in the panel for this agent');
 }
 export async function claimMandatePickup(opts) {
-    const { baseUrl, pickupCode, agentJkt, tokenId, fetchImpl = fetch, sleep = defaultSleep, now = Date.now, attempts = 3, retryDelayMs = 1_000, } = opts;
+    const { baseUrl, pickupCode, agentJkt, expectedHandoffId, tokenId, fetchImpl = fetch, sleep = defaultSleep, now = Date.now, attempts = 3, retryDelayMs = 1_000, } = opts;
     // Both producers (runHostedApproval and the panel initiate route) mint the
     // verifier as randomBytes(32).base64url = 43 chars; refuse anything else
     // before it travels.
@@ -412,7 +412,34 @@ export async function claimMandatePickup(opts) {
     if (ctx.budget !== true) {
         throw pickupMismatch('budget', 'the approval is a one-purchase approval, not a spend budget');
     }
-    if (ctx.agentJkt !== agentJkt) {
+    // A budget names exactly ONE agent, by one of two pins.
+    //
+    //  - `agentJkt` — the panel flow: the owner picked an agent that already
+    //    existed, so the approval names its key and this runtime compares keys.
+    //  - `handoffId` — the Add-agent dialog: the budget was minted before any
+    //    agent existed, so it names the handoff the agent would go on to redeem.
+    //    This runtime redeemed one moments ago and knows which, so the comparison
+    //    is just as concrete — it is simply a different identifier.
+    //
+    // EXACTLY one, enforced before either is compared. Neither pin is an unbound
+    // budget, and "no pin" must never be the quiet way past a binding check.
+    // BOTH pins is worse: it names two agents, and checking whichever one happens
+    // to match would let the weaker claim decide. The signer refuses to mint such
+    // a context and the approval store refuses to hold one, so this is the third
+    // and last place to say it — the one that runs on material already in hand.
+    const hasHandoffPin = typeof ctx.handoffId === 'string';
+    const hasAgentPin = typeof ctx.agentJkt === 'string';
+    if (hasHandoffPin === hasAgentPin) {
+        throw pickupMismatch('agentJkt', hasHandoffPin
+            ? 'this budget names two different agents at once — it binds to a handoff or to a key, never both'
+            : 'this budget names no agent at all, so nothing can prove it belongs to this runtime');
+    }
+    if (hasHandoffPin) {
+        if (!expectedHandoffId || ctx.handoffId !== expectedHandoffId) {
+            throw pickupMismatch('handoffId', 'this budget belongs to a different agent handoff than the one this runtime just claimed');
+        }
+    }
+    else if (ctx.agentJkt !== agentJkt) {
         throw pickupMismatch('agentJkt', 'the owner approved this mandate for a different agent key than this runtime holds');
     }
     if (ctx.tokenId !== tokenId) {