@agent-cards/checkout 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.4.0
+
+- Add `controller.prepare({ psp: 'square', environment: 'production' | 'sandbox' })` to both browser adapters. The caller awaits cardholder consent and unlock before starting its first native Pay action. This requires the matching preparation API and Vault deployment.
+- Bind one fresh request to the selected card, declared merchant, merchant origin, amount, currency and Square environment. Readiness expires after at most 30 seconds; preparation failure, expiry, cancellation, navigation and reuse fail closed. Binding creates no second approval link or SMS. Square token amounts remain display-only.
+- Preserve native request deadlines and merchant-abort protections. The SDK never clicks Pay, changes Square timers or retries an abandoned prepared checkout. The post-submit relay and token handoff must still fit Square's native deadline; a disconnected or slow cardholder device can miss it.
+- Recover a lost bind acknowledgement through preparation metadata for cancellation and reconciliation only. Started replay or unconfirmed cleanup remains unknown. A parent CDP page disconnect now also stops a pending request in a child iframe.
+- Add preparation lifecycle tests and an isolated Chromium fixture that waits more than ten seconds before any card request, then permits one fresh request. These fixtures use no real processor and do not establish native Square or production checkout acceptance.
+
+## 0.3.1
+
+- Detect a merchant request abort or owning frame/page closure while approval is pending. The attachment holds an unknown outcome and blocks automatic retries; an expired request is never reported as an authorized handoff.
+- Retire pending authorizations through the org-scoped cancellation endpoint when the merchant request disappears. Cancellation can win only before the processor-send boundary; started or completed replay remains unknown to this operation. A late creation response is drained so its authorization ID can be cancelled without exposing another approval link.
+- Square token mode uses the vault's verified browser TLS relay. The relay keeps TLS termination and card plaintext on the cardholder device and Square. SDK 0.2.1 can complete a prompt approval but does not contain the native-timeout lifecycle fixes; upgrade to 0.3.1 for Square checkout.
+- Square's native tokenization request still expires after about 10 seconds, including approval and token handoff. Delayed approval cannot complete that checkout; a later SCA challenge has its own lifetime after handoff. This release does not extend the deadline or retry a payment after timeout. Reconcile the merchant outcome and explicitly begin another checkout when required.
+
 ## 0.3.0
 
 ### Browser checkout lifecycle

package/README.md

@@ -30,7 +30,7 @@ your agent ──drives──> merchant checkout
 npm i @agent-cards/checkout
 ```
 
-Upgrading from 0.2.x? Read the [0.3.0 migration notes](./CHANGELOG.md), especially
+Upgrading from 0.2.x? Read the [migration notes](./CHANGELOG.md), especially
 the unknown-outcome, cancellation and browser-context requirements.
 
 ## Use it
@@ -79,8 +79,11 @@ Stripe's minor units, so the approval screen, the notifications and every
 read show one amount. Tokenization requests carry no amount, so there the
 pair is shown and reported (`amountAuthority: 'display_only'`), not enforced.
 
-Then let your agent click "Pay" like it always does. `attachToCdp` holds the
-request open until the cardholder approves, so the checkout simply continues.
+Then let your agent click "Pay" like it always does. `attachToCdp` pauses the
+request for approval and resumes it only while the merchant request remains
+live. Merchant timeouts still apply: Square's observed tokenization deadline
+is about 10 seconds for approval and token handoff. For human approval, use
+`controller.prepare()` before the first Pay action as shown below.
 
 Playwright:
 
@@ -389,6 +392,29 @@ do not reuse that token in a new attachment as a workaround. Configuration and
 unsupported-mode failures require fixing the integration. Bank flows requiring
 another confirmation and other stored-token chains remain unverified.
 
+Square's observed native tokenization request expires after about 10 seconds. SDK 0.4.0 adds approval before submission, requiring the matching preparation API and Vault deployment. Start human approval before the caller's first Pay action:
+
+```ts
+const checkout = await attachToPlaywright(page, {
+  vault, user: 'your-user-id', merchant: 'Example merchant',
+  amountCents: 100, currency: 'USD',
+  onApprovalUrl: deliverPrivatelyToCardholder,
+});
+const preparation = await checkout.prepare({
+  psp: 'square',
+  environment: 'production', // explicit; use 'sandbox' for Square Sandbox
+});
+// The cardholder has consented and unlocked the same approval document.
+// No processor request or payment has started.
+await page.getByRole('button', { name: 'Pay', exact: true }).click();
+```
+
+`prepare()` is available on both Playwright and raw CDP controllers. It requires `amountCents` and `currency`, must precede the first recognized card request, and returns only when the cardholder's device is ready. It delivers the preparation URL through `onApprovalUrl` and `onUserAction`; binding the subsequent authorization sends no second approval link or SMS. The phone page must stay open. Its selected card, merchant origin, declared merchant, amount, currency and Square environment bind one fresh request. The amount remains `display_only`; a Square token does not enforce the merchant's eventual charge amount.
+
+Readiness lasts up to 30 seconds (`preparation.expiresAt`) and appears as `ready_to_submit`, with `paymentStatus: 'not_started'`. Trigger the caller-owned Pay action immediately after the promise resolves. Expiry, navigation, cancellation, an early request or a changed checkout fails closed. A preparation and its attachment are single use; reconcile any bound authorization before creating a new attachment. The SDK never clicks Pay, reuses a stale request, pauses Square timers, or automatically retries a failed prepared checkout.
+
+After Pay, Square's native deadline still covers fresh authorization binding, device replay, relay and token handoff. A disconnected/backgrounded phone or slow transport can still miss it. A subsequent SCA challenge has its own lifetime after token handoff. If the merchant request aborts or its frame closes, the attachment blocks further requests and tries to retire the pre-replay authorization; a started replay or unconfirmed cancellation remains unknown. Without `prepare()`, approval loading and human interaction still share the native deadline, so delayed approval cannot finish that request.
+
 Lost authorization polling, local approval timeouts, or interrupted browser
 handoffs produce `outcome_unknown` and block automatic retry. The thrown
 `PaymentOutcomeUnknownError` carries `authorizationId` when creation was
@@ -434,8 +460,11 @@ pnpm test:browser
 The browser fixtures never contact a payment service. The general suite uses
 `psp.invalid`; the Stripe continuation suite forces `api.stripe.com` through an
 allowlisted loopback proxy and a temporary self-signed TLS stub (requires the
-`openssl` CLI). All other proxy destinations are rejected. Both suites use an
-in-process Agentcard API fixture and loopback merchant pages. It proves nested-frame pause/resume, agent control during approval,
+`openssl` CLI). All other proxy destinations are rejected. These suites use an
+in-process Agentcard API fixture and loopback merchant pages. The preparation
+fixture denies all external traffic, waits more than ten seconds before any
+card request, and then checks one fresh request with an unchanged ten-second
+fixture abort timer. It exercises SDK ordering, not the native Square SDK. It proves nested-frame pause/resume, agent control during approval,
 post-payment tasks in the same page, decline/expiry/cancel, unknown-outcome retry
 blocking, explicit unsupported endpoint behavior, and blocking an immediate real-browser
 Stripe token-to-intent fetch chain, including unrelated first intents, changed

package/dist/cdp.js

@@ -1,5 +1,6 @@
 import { BUILTIN_REGISTRY, cardUrlPatterns } from './registry.js';
 import { ApprovalDeclinedError, ApprovalTimeoutError, CardEncryptedError, CheckoutApiError, PaymentOutcomeUnknownError, UnsupportedModeError, redactUrl, } from './client.js';
+import { PreparationGate } from './preparation.js';
 import { substituteEncryptedFields } from './substitute.js';
 import { hostedFormSubmittedPage } from './hosted-form.js';
 import { CheckoutLifecycle, paymentEndpointGuards } from './lifecycle.js';
@@ -284,6 +285,22 @@ function failureSummary(error) {
         return `${error.name}: ${error.code ?? `http_${error.status}`}`;
     return error instanceof Error ? error.name : 'CheckoutError';
 }
+/** Separate from explicit cancellation: the client can drain a late create ID. */
+function merchantAttempt(lifecycle) {
+    const controller = new AbortController();
+    const error = () => new PaymentOutcomeUnknownError(lifecycle.getState().authorizationId, 'merchant_request_aborted');
+    return {
+        signal: controller.signal,
+        stop() {
+            if (controller.signal.aborted)
+                return;
+            lifecycle.merchantRequestAborted();
+            controller.abort(error());
+        },
+        assertLive() { if (controller.signal.aborted)
+            throw error(); },
+    };
+}
 /**
  * Take over card tokenization for a page.
  *
@@ -304,6 +321,14 @@ function failureSummary(error) {
 export async function attachToCdp(cdp, pageSessionId, opts) {
     opts = safeOptions(opts);
     const lifecycle = new CheckoutLifecycle(opts);
+    let preparationFrameId;
+    const preparationGate = new PreparationGate(opts, lifecycle, async () => {
+        const tree = await cdp.send('Page.getFrameTree', {}, pageSessionId);
+        if (typeof tree?.frameTree?.frame?.url !== 'string')
+            throw new Error('merchant_document_unavailable');
+        preparationFrameId = tree.frameTree.frame.id;
+        return tree.frameTree.frame.url;
+    });
     const guards = paymentEndpointGuards(opts.paymentEndpoints);
     const armed = new Set();
     // Set once a failure proves that retrying cannot help; see isTerminal.
@@ -313,6 +338,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     let quietUntil = 0;
     // One outstanding approval at a time; see the note above isApprovalOutcome.
     let awaitingApproval = false;
+    let activeRequest = null;
     // The hosted form the cardholder already submitted; see HOSTED_FORM_REPEAT_QUIET_MS.
     const repeatQuietMs = opts.hostedFormRepeatQuietMs ?? HOSTED_FORM_REPEAT_QUIET_MS;
     let lastSubmitted = null;
@@ -323,6 +349,10 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         const key = sessionId ?? '__root__';
         if (armed.has(key))
             return;
+        // Fetch's interception ID differs from Network's ID. Enable failure events
+        // before intercepting and bind each attempt to both its ID and CDP session.
+        await cdp.send('Network.enable', {}, sessionId);
+        await cdp.send('Page.enable', {}, sessionId).catch(() => { });
         await cdp.send('Fetch.enable', {
             patterns: urlPatterns.map((urlPattern) => ({ urlPattern, requestStage: 'Request' })),
         }, sessionId);
@@ -333,6 +363,30 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         armed.add(key);
     };
     cdp.on(async (method, params, sessionId) => {
+        if (((method === 'Page.frameNavigated' && !params.frame?.parentId) || (method === 'Page.navigatedWithinDocument' && preparationFrameId && params.frameId === preparationFrameId)) && sessionId === pageSessionId) {
+            preparationGate.invalidate('merchant_document_changed');
+            if (preparationGate.isEngaged())
+                activeRequest?.attempt.stop();
+            return;
+        }
+        if ((method === 'Inspector.detached' && sessionId === pageSessionId)
+            || (method === 'Target.detachedFromTarget' && params.sessionId === pageSessionId)) {
+            preparationGate.invalidate('merchant_document_closed');
+            // The root page owns every attached OOPIF; its loss ends child requests too.
+            activeRequest?.attempt.stop();
+        }
+        if (method === 'Network.loadingFailed') {
+            if (activeRequest && activeRequest.networkId === params.requestId && activeRequest.sessionId === sessionId)
+                activeRequest.attempt.stop();
+            return;
+        }
+        if (method === 'Target.detachedFromTarget' || method === 'Inspector.detached' || method === 'Page.frameDetached') {
+            if (activeRequest && (method === 'Target.detachedFromTarget' ? activeRequest.sessionId === params.sessionId
+                : method === 'Inspector.detached' ? activeRequest.sessionId === sessionId
+                    : activeRequest.sessionId === sessionId && activeRequest.frameId === params.frameId))
+                activeRequest.attempt.stop();
+            return;
+        }
         if (method === 'Target.attachedToTarget') {
             const child = params.sessionId;
             try {
@@ -351,9 +405,10 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         }
         if (method !== 'Fetch.requestPaused')
             return;
-        const { requestId, request, resourceType } = params;
+        const { requestId, request, resourceType, networkId, frameId } = params;
         if (!opts.vault.isCardRequest(request.url, request.method)) {
             if (guards.matches(request.url, request.method)) {
+                preparationGate.invalidate('unsupported_checkout');
                 lifecycle.unsupported();
                 opts.onEvent?.({ type: 'unsupported_checkout', detail: { url: redactUrl(request.url), method: request.method } });
                 await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
@@ -362,11 +417,22 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             await cdp.send('Fetch.continueRequest', { requestId }, sessionId).catch(() => { });
             return;
         }
+        let preparation;
+        try {
+            preparation = preparationGate.claim(request.url);
+        }
+        catch (error) {
+            opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
+            await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
+            return;
+        }
         // Same stop condition as the Playwright adapter: once a failure proves
         // retrying is pointless, fail the request without calling the API again.
         if (terminal || lifecycle.isBlocked() || awaitingApproval || Date.now() < quietUntil) {
             const why = terminal ?? (lifecycle.isBlocked() ? lifecycle.getState().status : awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
             opts.onEvent?.({ type: 'blocked', detail: why instanceof Error ? failureSummary(why) : String(why) });
+            if (preparation)
+                preparationGate.retireUnboundClaim();
             await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
             return;
         }
@@ -374,6 +440,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         // requests can never both clear the check above and raise two prompts for
         // one checkout.
         awaitingApproval = true;
+        const attempt = merchantAttempt(lifecycle);
         let handoffStarted = false;
         try {
             const body = pausedBody(request);
@@ -395,19 +462,33 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             }
             opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url), ...(resourceType ? { resourceType } : {}) } });
             lifecycle.begin();
+            if (typeof networkId !== 'string' || !networkId) {
+                attempt.stop();
+                attempt.assertLive();
+            }
+            activeRequest = { attempt, networkId, sessionId, frameId };
+            if (preparation)
+                await preparationGate.assertDocument();
+            attempt.assertLive();
             const replay = await opts.vault.authorize({
                 user: opts.user,
                 merchant: opts.merchant,
                 amount: opts.amount,
                 amountCents: opts.amountCents,
                 currency: opts.currency,
-                cardId: opts.cardId,
+                cardId: preparation?.cardId ?? opts.cardId,
+                preparation,
                 timeoutMs: opts.timeoutMs,
                 signal: lifecycle.abort.signal,
+                merchantSignal: attempt.signal,
                 onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
-                onApprovalUrl: (url) => { lifecycle.approvalUrl(url); return opts.onApprovalUrl?.(url); },
+                onApprovalUrl: (url) => { if (!preparation && !attempt.signal.aborted) {
+                    lifecycle.approvalUrl(url);
+                    return opts.onApprovalUrl?.(url);
+                } },
                 request: { url: request.url, method: request.method, headers: request.headers, body },
             });
+            attempt.assertLive();
             if (lifecycle.isCancelled())
                 throw new Error('checkout cancelled locally after approval');
             lifecycle.prepareHandoff(replay, request.url);
@@ -427,6 +508,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                     responseHeaders: headerEntries(withCorsHeaders(page.headers, corsHeadersFor(request.url, request.headers))),
                     body: Buffer.from(page.body).toString('base64'),
                 }, sessionId);
+                attempt.assertLive();
                 lastSubmitted = { url: request.url, body, at: Date.now() };
                 // Named for what it is: a device-attested submission with no
                 // processor evidence, never an `authorized` event.
@@ -444,6 +526,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                     requestId,
                     postData,
                 }, sessionId);
+                attempt.assertLive();
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
             }
             else {
@@ -460,11 +543,15 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                     responseHeaders: headerEntries(withCorsHeaders(replay.headers, cors.headers)),
                     body: Buffer.from(replay.body).toString('base64'),
                 }, sessionId);
+                attempt.assertLive();
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
             }
             lifecycle.handedOff(replay);
         }
         catch (err) {
+            // Ignore the failure event caused by our own safe decline/error abort.
+            if (activeRequest?.attempt === attempt)
+                activeRequest = null;
             lifecycle.failed(err, handoffStarted);
             if (isTerminal(err))
                 terminal = err;
@@ -474,8 +561,12 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
         }
         finally {
+            if (activeRequest?.attempt === attempt)
+                activeRequest = null;
             awaitingApproval = false;
             lifecycle.end();
+            if (preparation)
+                preparationGate.retireUnboundClaim();
         }
     });
     await arm(pageSessionId);
@@ -500,6 +591,11 @@ export async function attachToPlaywright(page, opts) {
         throw new Error('Service workers are active; use a checkout context created with serviceWorkers: "block".');
     }
     const lifecycle = new CheckoutLifecycle(opts);
+    const preparationGate = new PreparationGate(opts, lifecycle, async () => {
+        if (page.isClosed?.() || typeof page.url !== 'function')
+            throw new Error('merchant_document_unavailable');
+        return page.url();
+    });
     const guards = paymentEndpointGuards(opts.paymentEndpoints);
     // Playwright's own routing, NOT a hand-rolled CDP session.
     //
@@ -520,6 +616,24 @@ export async function attachToPlaywright(page, opts) {
     let quietUntil = 0;
     // One outstanding approval at a time; see the note above isApprovalOutcome.
     let awaitingApproval = false;
+    let activeRequest = null;
+    page.on?.('requestfailed', (request) => {
+        if (activeRequest && activeRequest.request === request)
+            activeRequest.attempt.stop();
+    });
+    page.on?.('close', () => { preparationGate.invalidate('merchant_document_closed'); activeRequest?.attempt.stop(); });
+    page.on?.('crash', () => { preparationGate.invalidate('merchant_document_closed'); activeRequest?.attempt.stop(); });
+    page.on?.('framenavigated', (frame) => {
+        if (frame === page.mainFrame?.()) {
+            preparationGate.invalidate('merchant_document_changed');
+            if (preparationGate.isEngaged())
+                activeRequest?.attempt.stop();
+        }
+    });
+    page.on?.('framedetached', (frame) => {
+        if (activeRequest?.frames.includes(frame))
+            activeRequest.attempt.stop();
+    });
     // The hosted form the cardholder already submitted; see HOSTED_FORM_REPEAT_QUIET_MS.
     const repeatQuietMs = opts.hostedFormRepeatQuietMs ?? HOSTED_FORM_REPEAT_QUIET_MS;
     let lastSubmitted = null;
@@ -529,12 +643,21 @@ export async function attachToPlaywright(page, opts) {
         // untouched or the browser's CORS check fails on our synthetic answer.
         if (!opts.vault.isCardRequest(request.url(), request.method())) {
             if (guards.matches(request.url(), request.method())) {
+                preparationGate.invalidate('unsupported_checkout');
                 lifecycle.unsupported();
                 opts.onEvent?.({ type: 'unsupported_checkout', detail: { url: redactUrl(request.url()), method: request.method() } });
                 return route.abort('aborted');
             }
             return route.fallback();
         }
+        let preparation;
+        try {
+            preparation = preparationGate.claim(request.url());
+        }
+        catch (error) {
+            opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
+            return route.abort('aborted');
+        }
         // Fail closed and stay quiet: no card may reach the PSP, but neither may
         // the page's retry loop turn into a stream of doomed API calls. Every
         // abort in this adapter is 'aborted' (ERR_ABORTED), the same code the
@@ -543,10 +666,24 @@ export async function attachToPlaywright(page, opts) {
         if (terminal || lifecycle.isBlocked() || awaitingApproval || Date.now() < quietUntil) {
             const why = terminal ?? (lifecycle.isBlocked() ? lifecycle.getState().status : awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
             opts.onEvent?.({ type: 'blocked', detail: why instanceof Error ? failureSummary(why) : String(why) });
+            if (preparation)
+                preparationGate.retireUnboundClaim();
             return route.abort('aborted');
         }
         // Reserved before anything that could yield, matching attachToCdp.
         awaitingApproval = true;
+        const attempt = merchantAttempt(lifecycle);
+        const frames = [];
+        try {
+            for (let frame = request.frame?.(); frame; frame = frame.parentFrame?.())
+                frames.push(frame);
+        }
+        catch { /* requestfailed/page close still cover unavailable frame metadata */ }
+        const assertRequestLive = () => {
+            if (request.failure?.() || page.isClosed?.() || frames.some(frame => frame.isDetached?.()))
+                attempt.stop();
+            attempt.assertLive();
+        };
         let handoffStarted = false;
         try {
             const body = request.postData() ?? '';
@@ -556,19 +693,29 @@ export async function attachToPlaywright(page, opts) {
             }
             opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url()) } });
             lifecycle.begin();
+            activeRequest = { request, frames, attempt };
+            if (preparation)
+                await preparationGate.assertDocument();
+            assertRequestLive();
             const replay = await opts.vault.authorize({
                 user: opts.user,
                 merchant: opts.merchant,
                 amount: opts.amount,
                 amountCents: opts.amountCents,
                 currency: opts.currency,
-                cardId: opts.cardId,
+                cardId: preparation?.cardId ?? opts.cardId,
+                preparation,
                 timeoutMs: opts.timeoutMs,
                 signal: lifecycle.abort.signal,
+                merchantSignal: attempt.signal,
                 onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
-                onApprovalUrl: (url) => { lifecycle.approvalUrl(url); return opts.onApprovalUrl?.(url); },
+                onApprovalUrl: (url) => { if (!preparation && !attempt.signal.aborted) {
+                    lifecycle.approvalUrl(url);
+                    return opts.onApprovalUrl?.(url);
+                } },
                 request: { url: request.url(), method: request.method(), headers: request.headers(), body },
             });
+            assertRequestLive();
             if (lifecycle.isCancelled())
                 throw new Error('checkout cancelled locally after approval');
             lifecycle.prepareHandoff(replay, request.url());
@@ -579,6 +726,7 @@ export async function attachToPlaywright(page, opts) {
                 const synthetic = hostedFormSubmittedPage({ authorizationId: replay.authorizationId, merchant: opts.merchant, submittedAt: replay.submittedAt });
                 // Inert on a navigation (never CORS-checked); one path for every fulfill.
                 await route.fulfill({ status: synthetic.status, headers: withCorsHeaders(synthetic.headers, corsHeadersFor(request.url(), request.headers())), body: synthetic.body });
+                assertRequestLive();
                 lastSubmitted = { url: request.url(), body, at: Date.now() };
                 opts.onEvent?.({ type: 'submitted_on_device', detail: { authorizationId: replay.authorizationId, submittedAt: replay.submittedAt, outcome: replay.outcome } });
             }
@@ -589,6 +737,7 @@ export async function attachToPlaywright(page, opts) {
                 const postData = cseBody(body, replay);
                 handoffStarted = true;
                 await route.continue({ postData });
+                assertRequestLive();
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
             }
             else {
@@ -597,22 +746,29 @@ export async function attachToPlaywright(page, opts) {
                 // cross-origin answer is the same whichever adapter ran.
                 const cors = corsDecision(request.url(), request.headers());
                 await route.fulfill({ status: replay.status, headers: withCorsHeaders(replay.headers, cors.headers), body: replay.body });
+                assertRequestLive();
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
             }
             lifecycle.handedOff(replay);
         }
         catch (err) {
+            if (activeRequest?.attempt === attempt)
+                activeRequest = null;
             lifecycle.failed(err, handoffStarted);
             if (isTerminal(err))
                 terminal = err;
             else if (isApprovalOutcome(err))
                 quietUntil = Date.now() + cooldownMs;
             opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
-            await route.abort('aborted');
+            await route.abort('aborted').catch(() => { });
         }
         finally {
+            if (activeRequest?.attempt === attempt)
+                activeRequest = null;
             awaitingApproval = false;
             lifecycle.end();
+            if (preparation)
+                preparationGate.retireUnboundClaim();
         }
     });
     return lifecycle;

package/dist/client.d.ts

@@ -98,6 +98,46 @@ export interface HostedFormReplay {
 }
 /** What authorize() resolves with; branch on `mode` (absent means token). */
 export type ReplayResponse = TokenReplay | CseReplay | HostedFormReplay;
+export interface PrepareCheckoutOptions {
+    psp: 'square';
+    /** The processor environment, independent of your Agentcard client's mode. */
+    environment: 'production' | 'sandbox';
+    signal?: AbortSignal;
+}
+export interface PrepareCheckoutInput extends PrepareCheckoutOptions {
+    user: string;
+    merchant: string;
+    amountCents: number;
+    currency: string;
+    cardId?: string;
+    merchantOrigin: string;
+    checkoutKey: string;
+    timeoutMs?: number;
+    onPreparationCreated?: (id: string) => void;
+    onApprovalUrl?: (url: string) => void;
+}
+/** Real user consent and an unlocked device; no processor request or payment yet. */
+export interface PreparedCheckout {
+    readonly id: string;
+    readonly status: 'ready';
+    readonly psp: 'square';
+    readonly environment: 'production' | 'sandbox';
+    readonly expiresAt: string;
+    readonly cardId: string;
+    readonly user: string;
+    readonly merchant: string;
+    readonly amountCents: number;
+    readonly currency: string;
+    readonly merchantOrigin: string;
+    readonly checkoutKey: string;
+    readonly paymentStatus: 'not_started';
+    readonly amountAuthority: 'display_only';
+}
+export declare class CheckoutPreparationError extends Error {
+    preparationId: string | null;
+    reason: string;
+    constructor(preparationId: string | null, reason: string);
+}
 export interface AuthorizeInput {
     /** Your identifier for the person whose card should pay. */
     user: string;
@@ -135,10 +175,14 @@ export interface AuthorizeInput {
     timeoutMs?: number;
     /** Stops local polling; it does not revoke a pending approval or undo a payment. */
     signal?: AbortSignal;
+    /** Adapter-owned merchant request lifetime. A failed request retires a pending approval before replay when possible. */
+    merchantSignal?: AbortSignal;
     /** Called before onApprovalUrl; lets a runtime reconcile an interrupted authorization. */
     onAuthorizationCreated?: (authorizationId: string) => void;
     /** Called once with the URL to surface to the user, if you deliver it yourself. */
     onApprovalUrl?: (url: string) => void;
+    /** One-use preparation returned by this client. Never resumes an older request. */
+    preparation?: PreparedCheckout;
 }
 export declare class CardEncryptedError extends Error {
     psp: string;
@@ -313,6 +357,8 @@ export declare class VaultClient {
     private readonly pollIntervalMs;
     private readonly unverifiableRetryDelaysMs;
     private registry;
+    private readonly preparations;
+    private readonly usedPreparations;
     constructor(opts: VaultClientOptions);
     /** Refresh recognizers from the API so new PSPs work without a redeploy. */
     syncRegistry(): Promise<void>;
@@ -330,12 +376,26 @@ export declare class VaultClient {
      * these patterns pause.
      */
     cardUrlPatterns(): string[];
+    /** Wait for real device approval before the caller starts native tokenization. */
+    prepareCheckout(input: PrepareCheckoutInput): Promise<PreparedCheckout>;
+    /** Cancel only an unconsumed preparation; a bound request is reconciled separately. */
+    cancelPreparation(id: string): Promise<void>;
     /**
      * Hand us a paused tokenization request. We ask the cardholder to approve,
      * their device supplies the card and calls the merchant, and you get back the
      * response to replay into the browser. Your process never sees a card.
      */
     authorize(input: AuthorizeInput): Promise<ReplayResponse>;
+    /** A lost bind acknowledgement must never resume the request. Recover metadata only for safe cleanup. */
+    private retireUncertainPreparation;
+    /** Retire only a pre-replay authorization. A 409 or missing response remains unknown. */
+    cancelAuthorization(authorizationId: string): Promise<{
+        id: string;
+        status: 'declined';
+        reason: 'merchant_request_aborted';
+        cancelled: true;
+        processor_request_started: false;
+    }>;
     /**
      * POST the create, with two typed twists: a 502 `amount_unverifiable`
      * (Stripe did not answer the read-back) is retried on a short backoff