@agent-cards/checkout 0.1.0 → 0.2.0

package/README.md

@@ -42,15 +42,40 @@ const vault = new VaultClient({
   clientSecret: process.env.AGENTCARD_CLIENT_SECRET!,
 });
 
+// Pull the current processor list. attachToCdp arms the browser from it, so
+// without this you only intercept the processors built into your installed
+// version. Safe to call on every run: a failed fetch keeps the built-ins.
+await vault.syncRegistry();
+
 await attachToCdp(cdp, pageSessionId, {
   vault,
   user: 'usr_123',                 // whose card should pay
   merchant: 'vanman.shop',
-  amount: '$5.83',
+  amountCents: 583,                // what the user approves, smallest currency unit
+  currency: 'usd',                 // "$5.83" is derived for the approval screen
   onApprovalUrl: (url) => sendToUser(url),   // iMessage, SMS, push, your call
 });
 ```
 
+`amount: '$5.83'` (a display string) still works on its own. Pass
+`amountCents` + `currency` when you want the amount enforced: on a Stripe
+PaymentIntent confirm, Agentcard reads the intent back from Stripe at create
+and again right before the cardholder's device replays, a different amount is
+refused with nothing charged, and after the replay the charge is reconciled
+against the approval (`ReplayResponse.amountVerified`, with
+`chargedAmountCents` and `chargedKind`: `captured` for a succeeded intent's
+`amount_received`, `authorized` for a manual-capture intent's
+`amount_capturable`, `none` when nothing is collected yet; plus the
+`checkout_authorization.amount_mismatch` webhook to your server when it
+disagrees). Amounts are Stripe minor units up to 2^53-1. `onEvent` payloads
+name URLs by origin and path only, so a client secret in a paused request's
+query string never reaches your telemetry. When you pass the pair, any
+`amount` string you also pass is
+ignored: Agentcard derives the display string from the number, following
+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.
 
@@ -101,18 +126,147 @@ Merchants inherit their processor, so one entry covers every store on it.
 | Stripe | supported, verified end to end |
 | Braintree / PayPal | supported, verified end to end |
 | Checkout.com | supported |
-| Adyen | not yet — the card is encrypted in-page, so a paused request carries a blob. Throws `CardEncryptedError` |
+| Adyen | supported (mode `cse`): the vault encrypts the card for Adyen on the cardholder's device and your browser sends it |
+| Tranzila | supported (mode `hosted_form`): the cardholder finishes on Tranzila's own page; the paused form navigation resolves to a synthetic page, and you poll the merchant's order state |
 
 The recognizer list is fetched from the API at runtime (`vault.syncRegistry()`),
-so new processors work without you shipping a release.
+so new processors work without you shipping a release. `attachToCdp` derives the
+`Fetch.enable` url patterns from that same list rather than a constant, which is
+why the sync call belongs before the attach. `vault.cardUrlPatterns()` returns
+those patterns if you arm a CDP connection yourself. Call
+`GET /v2/checkout/recognizers?modes=token,cse,hosted_form` for the list that is
+live right now.
+
+## Modes
+
+Each recognizer carries a `mode` (absent means `token`), and every authorization
+carries the mode it was handled in. The adapters do the right thing for all
+three; the difference matters if you drive `authorize()` yourself.
+`ReplayResponse` is a union, so branch on `mode`.
+
+- **`token`** (every processor but Adyen). The cardholder's device calls the
+  processor and reports its answer; `authorize()` resolves with `status`,
+  `headers` and `body` to fulfill the paused request with.
+- **`cse`** (Adyen). Adyen's own page SDK encrypts the card before the request
+  leaves the browser, so the paused body carries ciphertext. The cardholder's
+  device produces the same ciphertext under the merchant's Adyen public key
+  (fetched by Agentcard from Adyen's host when the request is parked) and
+  `authorize()` resolves with `substitutions: { encoding: 'json', at, fields,
+  remove }`. Write them into the paused body with
+  `substituteEncryptedFields(body, substitutions)` and CONTINUE the request
+  from the same browser (`Fetch.continueRequest` with the rewritten
+  `postData`, or Playwright's `route.continue({ postData })`): its session
+  data, risk data and cookies must stay its own. Only the four encrypted
+  fields change, and the siblings named in `remove` are dropped (Adyen's
+  `brand`, which adyen-web derived from the dummy digits the agent typed:
+  left in place it names the wrong card and Adyen refuses the mismatch;
+  absent, Adyen reads the brand off the card it decrypts). A body that lacks
+  the fields throws `SubstitutionError`, which is not terminal. Adyen answers the browser,
+  so `charged_kind` is null on the approval and the merchant's order state is
+  the outcome to poll.
+- **`hosted_form`** (Tranzila). The processor's hosted card form submits the
+  card as a TOP-LEVEL form post, so the paused request is a page navigation
+  (the adapters arm `Fetch.enable` with no resource-type filter and attach the
+  processor's iframe, which is how a Document request on `direct.tranzila.com`
+  gets paused at all). The cardholder's device rebuilds that form with the
+  real card and submits it itself; the processor answers the device, and
+  `authorize()` resolves with `{ mode: 'hosted_form', kind:
+  'submitted_on_device', outcome: 'unverified', submittedAt }` once the
+  device reports the form left. **This is not an approved payment.** The
+  stamp is the cardholder's device attesting that the form left it;
+  Agentcard holds no processor evidence on this mode and cannot obtain any,
+  so the API finishes the authorization as `submitted_on_device` (never
+  `approved`) and sends your server `checkout_authorization.submitted`
+  (never `.approved`). Treat it as "the person paid, or tried to, on their
+  own device" and confirm the order with the merchant before you count it.
+  There is no response to replay: FULFIL the paused navigation with
+  `hostedFormSubmittedPage({ authorizationId, merchant, submittedAt })` (200,
+  `text/html`, `x-agentcard-checkout: submitted_on_device`, a `<meta
+  name="agentcard-checkout">` and an inert JSON block saying "submitted on
+  the cardholder's device, payment unverified, do not resubmit"), the way
+  the adapters do. Do not abort it: an aborted navigation renders nothing,
+  the iframe silently keeps its dummy-card form, and the agent's next move is
+  to click Pay again. Do not fake the processor's result page either: this
+  SDK does not know the outcome. The adapters emit `submitted_on_device` (not
+  `authorized`), refuse a byte-identical re-post of the same form for 15
+  minutes (`hostedFormRepeatQuietMs`), and the API answers a regenerated one
+  with `409 duplicate_submission`, which the adapters quiet the way they quiet
+  a decline (`approvalCooldownMs`): the page's immediate re-posts are refused
+  without a round trip, and once the prior authorization is declined or
+  expired the same form is a new question. Confirm the order with the
+  merchant, which learns the outcome from the processor.
+
+`syncRegistry()` asks the API for `SUPPORTED_MODES` only
+(`token,cse,hosted_form`), so a processor whose flow this build cannot finish
+is never paused; the API serves `hosted_form` entries only to callers that ask.
+An approval in some other mode throws `UnsupportedModeError`, which is
+terminal for that page (upgrade the SDK). The `authorized` event's detail names
+the `mode`, the `authorizationId` and, for `cse`, the `fields` that were
+substituted; it never carries ciphertext. The `submitted_on_device` event's
+detail names the `authorizationId`, `submittedAt` and `outcome:
+'unverified'`; it is not an `authorized` event and must not be counted as
+one. `amountAuthority` on every replay is `stripe_payment_intent`,
+`hosted_form_sum` (the form's own amount) or `display_only`.
 
 ## Errors worth handling
 
 - `ApprovalTimeoutError` — the user never approved. Default window is 15 minutes;
   we have completed checkouts after a 5.5 minute approval delay.
 - `ApprovalDeclinedError` — the user said no.
-- `CardEncryptedError` — this processor needs vault-side crypto; route the
-  purchase to an Agentcard-issued card instead.
+- `AmountMismatchError`: the processor's amount did not match the amount the
+  user was (or would have been) asked to approve. Nothing was charged. An
+  `ApprovalDeclinedError` with `expectedCents`, `actualCents`, `currency`,
+  `code: 'amount_mismatch'` and `stage`: `'pre_replay'` (checked right before
+  the device would have sent the card; `authorizationId` names the declined
+  authorization) or `'create'` (the intent already disagreed when the request
+  was parked; no authorization exists, `authorizationId` is null). Per
+  request, not per page: a merchant can still update an intent's amount
+  until it is confirmed, so the adapters quiet the page's immediate retry
+  and judge the next request afresh instead of latching.
+- `IntentNotConfirmableError`: the PaymentIntent was already charged, is
+  processing, or is authorized and on hold (or canceled), so Agentcard
+  refused to replay a confirm at it. An `ApprovalDeclinedError` with
+  `code: 'intent_not_confirmable'`. Deliberately not "nothing was charged":
+  check the intent at Stripe before retrying.
+- `ProcessorRefusedError`: the cardholder's device sent the card and the
+  processor refused it outright (`pspErrorCode` is the processor's own code,
+  such as Stripe's `card_declined`). Nothing was charged. An
+  `ApprovalDeclinedError` with `code: 'processor_refused'`; the page's next
+  attempt raises a fresh approval where the person can pick another card.
+- `CheckoutApiError` with `code === 'amount_unverifiable'`: Stripe could not
+  be asked (502; the SDK retries twice, 500ms then 1500ms, before throwing)
+  or the paused request lacked its client secret or publishable key (400).
+  `code === 'intent_not_confirmable'` at create (409) means the intent was
+  already used; the adapters stop intercepting for that page.
+  `code === 'cse_key_unavailable'` (502) means Adyen did not answer the
+  public-key fetch and is retried the same way; `cse_client_key_unknown`
+  (400) means Adyen does not know the merchant's `clientKey`, and
+  `cse_template_unsupported` (400) means the paused body carries no
+  encrypted card fields to fill (a stored card, a wallet, a single-blob
+  `encryptedCard`); both are terminal for that page.
+  `hosted_form_template_incomplete` (400) means the paused form lacks a
+  field the device fills or the processor requires, `hosted_form_gated`
+  (400) means it carries a live captcha token the device could never
+  re-submit, and `hosted_form_field_refused` (400, with `field` and a
+  `reason` of `stored_credential`, `not_a_sale` or `callback_host`) means
+  the form asks the processor for something other than one plain sale
+  reporting to the merchant you named (a reusable token in or out, a sale
+  mode that is not a sale, a callback URL off the merchant's host: name the
+  merchant by its hostname when the form carries callback URLs); all three
+  are terminal for that page. `duplicate_submission` (409,
+  with `prior_authorization_id` and `prior_status`) means this exact
+  submission already has, or already had, its prompt: the adapters quiet the
+  page's re-posts for `approvalCooldownMs` (no second notification for one
+  payment) and judge the next request afresh, since the prior authorization
+  declines or expires and the same form is then a new question.
+- `CardEncryptedError`: this processor encrypts the card in-page and its
+  registry entry does not (yet) say the vault can produce that ciphertext;
+  route the purchase to an Agentcard-issued card instead.
+- `UnsupportedModeError`: the approval came back in a mode this build of the
+  SDK cannot finish. Terminal for the page; upgrade.
+- `SubstitutionError`: a `cse` approval could not be written into the paused
+  body (the four encrypted fields were not there). The request is failed and
+  the next one is judged afresh.
 
 ## Building this package
 
@@ -122,5 +276,5 @@ be installed here without regenerating the lockfile, and a full regen drifts
 unrelated transitive versions). Build it with the workspace TypeScript:
 
 ```bash
-pnpm --filter backend exec tsc -p packages/checkout/tsconfig.json
+cd packages/checkout && pnpm build && pnpm test
 ```

package/dist/cdp.d.ts

@@ -1,4 +1,4 @@
-import type { VaultClient } from './client.js';
+import { type VaultClient } from './client.js';
 /**
  * Minimal shape of a CDP connection. Works with a raw websocket client, a
  * Puppeteer CDPSession, or Playwright's CDPSession.
@@ -11,12 +11,25 @@ export interface AttachOptions {
     vault: VaultClient;
     user: string;
     merchant: string;
-    amount: string;
+    /** Display string for the approval screen. Optional when amountCents + currency are given. */
+    amount?: string;
+    /**
+     * The amount as a number (smallest currency unit) with its ISO 4217 code.
+     * See AuthorizeInput.amountCents: on a Stripe PaymentIntent confirm this
+     * binds the approval to the intent's amount, checked at create and again
+     * right before replay, so a larger charge is refused with nothing charged.
+     */
+    amountCents?: number;
+    currency?: string;
     onApprovalUrl?: (url: string) => void;
     onEvent?: (e: {
         type: string;
         detail?: unknown;
     }) => void;
+    /** Silence after a decline or timeout. Defaults to APPROVAL_COOLDOWN_MS. */
+    approvalCooldownMs?: number;
+    /** How long a hosted form the device already submitted stays refused on a re-post. Defaults to HOSTED_FORM_REPEAT_QUIET_MS. */
+    hostedFormRepeatQuietMs?: number;
 }
 /**
  * Take over card tokenization for a page.
@@ -25,6 +38,15 @@ export interface AttachOptions {
  * targets. Enabling Fetch on the page session alone will never see the
  * tokenization request. This attaches recursively so every nested target is
  * armed, which is the whole reason this adapter exists.
+ *
+ * The patterns armed here come from the REGISTRY, not from a constant, so a PSP
+ * the API knows about is paused without an SDK release — call
+ * `vault.syncRegistry()` before attaching and every recognizer the server
+ * serves is covered. They are a coarse pre-filter and are deliberately wider
+ * than the recognizers (see cardUrlPatterns): each paused request is re-checked
+ * with `isCardRequest` below and continued untouched unless it is an exact
+ * match. Patterns are resolved once, at attach, so every nested target ends up
+ * armed identically.
  */
 export declare function attachToCdp(cdp: CdpLike, pageSessionId: string, opts: AttachOptions): Promise<void>;
 /**

package/dist/cdp.js

@@ -1,11 +1,153 @@
-const CARD_PATTERNS = [
-    '*pci.shopifyinc.com/sessions*',
-    '*shopifycs.com/sessions*',
-    '*api.stripe.com/v1/payment_methods*',
-    '*api.stripe.com/v1/tokens*',
-    '*braintree-api.com/graphql*',
-    '*checkout.com/tokens*',
-];
+import { BUILTIN_REGISTRY, cardUrlPatterns } from './registry.js';
+import { ApprovalDeclinedError, ApprovalTimeoutError, CardEncryptedError, CheckoutApiError, UnsupportedModeError, redactUrl, } from './client.js';
+import { substituteEncryptedFields } from './substitute.js';
+import { hostedFormSubmittedPage } from './hosted-form.js';
+// Every URL that leaves this module through onEvent is redacted to origin +
+// path first. A paused PaymentIntent confirm can carry the client secret in
+// its query string (Stripe.js puts it in the body; hand-rolled runtimes and
+// some SDKs put it in the URL), and onEvent is ordinary integrator telemetry:
+// logs, dashboards, crash reporters. None of those may receive a secret.
+/**
+ * How long a hosted form that the cardholder already submitted stays refused
+ * when the page posts it again.
+ *
+ * A hosted_form approval resolves the paused navigation with a synthetic page
+ * (hostedFormSubmittedPage), and the merchant page may still carry the same
+ * card form: an agent that clicks Pay again would pause an identical
+ * navigation and, without this, raise a second prompt on the household's
+ * phone for a payment that already left it. The API's duplicate guard covers
+ * a body the form regenerated (same supplier, session and amount inside 15
+ * minutes: 409 duplicate_submission, which the adapters quiet the way they
+ * quiet a decline, see isApprovalOutcome); this latch covers the
+ * byte-identical re-post without a round trip. Same window as the
+ * authorization's own TTL. Overridable per attach via `hostedFormRepeatQuietMs`.
+ */
+const HOSTED_FORM_REPEAT_QUIET_MS = 15 * 60_000;
+/** The same form the device already submitted, posted again inside the quiet window. */
+function isRepeatOfSubmitted(last, url, body, quietMs) {
+    return !!last && last.url === url && last.body === body && Date.now() - last.at < quietMs;
+}
+const HOSTED_FORM_REPEAT_REASON = 'already submitted on the cardholder\'s device';
+/**
+ * How long to stop asking after a person declines or ignores an approval.
+ *
+ * This exists because the two failure shapes look identical at the route
+ * handler and need opposite answers. A merchant page re-issues an aborted
+ * tokenization within milliseconds, and re-prompting on each of those turns
+ * one decline into a queue of notifications on someone's phone. A genuinely
+ * later checkout also arrives as a paused request, and that one deserves a
+ * fresh prompt, so a permanent latch is wrong too.
+ *
+ * Elapsed time is what separates them, and nothing else available here does:
+ * body, nonce and authorization id all differ between an automatic retry and a
+ * new checkout. So a decline buys a short silence, not a closed door.
+ *
+ * Kept deliberately SHORT. A page's automatic retry lands in milliseconds — the
+ * storm this exists for ran at roughly ten a second — so a few seconds absorbs
+ * a burst with room to spare, while leaving almost no window in which a person
+ * could start a genuinely new checkout and be turned away. Raise it only with
+ * evidence of a slower retry loop; every second added is a second a real
+ * checkout can be refused. Overridable per attach via `approvalCooldownMs`.
+ */
+const APPROVAL_COOLDOWN_MS = 5_000;
+/**
+ * One approval at a time, per attachment.
+ *
+ * The cooldown only arms once a failure RESOLVES, so two requests paused
+ * before the first authorize() returns both sail past it and each raise their
+ * own prompt. A checkout with several card iframes does exactly that. Nobody
+ * should get two notifications asking them to approve the same purchase, so a
+ * request arriving while one is outstanding is failed rather than queued: the
+ * page's own retry brings it back, and by then there is an answer.
+ */
+/**
+ * This one authorization was answered; see APPROVAL_COOLDOWN_MS. An
+ * AmountMismatchError is an ApprovalDeclinedError, so both amount checks land
+ * here: the pre-replay one (the row IS declined) and the create-time one (no
+ * row; the intent already disagreed). Either way the paused request is
+ * aborted with nothing charged and the page's retry is quieted, NOT latched:
+ * Stripe lets the merchant update an intent's amount until it is confirmed,
+ * so the next request on this page is a new question and is judged afresh.
+ * IntentNotConfirmableError lands here too (the row is declined).
+ *
+ * A 409 duplicate_submission is an answer of the same kind: the household
+ * already has, or already answered, the prompt for this exact submission (a
+ * hosted form the page posted again with a fresh nonce). Quieting the page's
+ * re-post is right; latching the whole attachment is not, because the prior
+ * row declines or expires and the same form is then a new question. The
+ * quiet window absorbs the burst; the next request past it is judged afresh.
+ */
+function isApprovalOutcome(err) {
+    if (err instanceof CheckoutApiError)
+        return err.code === 'duplicate_submission';
+    return err instanceof ApprovalDeclinedError || err instanceof ApprovalTimeoutError;
+}
+/**
+ * Should this failure stop us intercepting for the rest of the page's life?
+ *
+ * It matters because a failed tokenization does not end the checkout: the
+ * merchant's own page retries, we pause the retry, we fail it again, and the
+ * loop runs as fast as the page will go. A real run against Shopify with a
+ * stale user id produced ~10 authorization calls a SECOND for fifteen minutes
+ * until the agent's host killed it, every one of them a request to our API that
+ * could never have succeeded.
+ *
+ * Terminal means "will answer identically next time no matter who does what":
+ * a misconfiguration or an unsupported PSP. Nothing a person does changes
+ * those, so asking again is pure waste.
+ *
+ * Everything else stays retryable. A 5xx or a 429 clears on its own, and a
+ * decline or a timeout is answered by the cooldown above rather than by
+ * killing the page: the person said no to one authorization, not to every
+ * checkout they will ever make in this session. A 409 duplicate_submission
+ * is not `permanent` on the error itself (see CheckoutApiError) and lands in
+ * the cooldown too.
+ */
+function isTerminal(err) {
+    if (err instanceof CheckoutApiError)
+        return err.permanent;
+    return err instanceof CardEncryptedError || err instanceof UnsupportedModeError;
+}
+/**
+ * The cse continuation: the paused body with the vault's ciphertext in place
+ * of the dummy blobs. It is sent as postData ALONE. Chromium recomputes
+ * Content-Length for a continued request itself and refuses a header override
+ * that names it (Fetch.continueRequest answers -32602 "Unsafe header"), and
+ * that refusal would land after the cardholder approved, failing a paid-for
+ * request. Leaving `headers` off the command keeps every other header the
+ * browser's own, untouched, which is the point of continuing rather than
+ * fulfilling.
+ */
+function cseBody(body, replay) {
+    return substituteEncryptedFields(body, replay.substitutions);
+}
+/**
+ * The paused request's body, or null when Chromium says there is one and did
+ * not hand it over. `postData` is set only for a text body; a binary or a
+ * large one arrives as base64 `postDataEntries` instead, concatenated here
+ * byte for byte (an entry without `bytes` is a file the browser streams, which
+ * no runtime can read back). There is no CDP command to fetch it later:
+ * `Fetch.getRequestPostData` does not exist (Chrome answers -32601), so a
+ * body that is not on the event is a body this adapter cannot see.
+ */
+function pausedBody(request) {
+    if (typeof request.postData === 'string' && request.postData !== '')
+        return request.postData;
+    if (!request.hasPostData)
+        return request.postData ?? '';
+    const entries = request.postDataEntries ?? [];
+    if (!entries.length || entries.some((e) => typeof e.bytes !== 'string'))
+        return null;
+    return Buffer.concat(entries.map((e) => Buffer.from(e.bytes, 'base64'))).toString('utf8');
+}
+const BODY_UNREADABLE_REASON = 'the paused request\'s body could not be read (no postData and no postDataEntries)';
+/**
+ * Last-resort patterns: the built-in recognizers' hosts, derived the same way
+ * as everything else. Used only when the vault hands back nothing at all (a
+ * duck-typed client from an older SDK, or an empty registry) — a hardcoded list
+ * that drifts from the registry is exactly the bug this adapter used to have.
+ */
+const FALLBACK_CARD_PATTERNS = cardUrlPatterns(BUILTIN_REGISTRY);
 /**
  * Take over card tokenization for a page.
  *
@@ -13,16 +155,38 @@ const CARD_PATTERNS = [
  * targets. Enabling Fetch on the page session alone will never see the
  * tokenization request. This attaches recursively so every nested target is
  * armed, which is the whole reason this adapter exists.
+ *
+ * The patterns armed here come from the REGISTRY, not from a constant, so a PSP
+ * the API knows about is paused without an SDK release — call
+ * `vault.syncRegistry()` before attaching and every recognizer the server
+ * serves is covered. They are a coarse pre-filter and are deliberately wider
+ * than the recognizers (see cardUrlPatterns): each paused request is re-checked
+ * with `isCardRequest` below and continued untouched unless it is an exact
+ * match. Patterns are resolved once, at attach, so every nested target ends up
+ * armed identically.
  */
 export async function attachToCdp(cdp, pageSessionId, opts) {
     const armed = new Set();
+    // Set once a failure proves that retrying cannot help; see isTerminal.
+    let terminal = null;
+    // Silence window after a person declined or ignored one; see APPROVAL_COOLDOWN_MS.
+    const cooldownMs = opts.approvalCooldownMs ?? APPROVAL_COOLDOWN_MS;
+    let quietUntil = 0;
+    // One outstanding approval at a time; see the note above isApprovalOutcome.
+    let awaitingApproval = false;
+    // 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;
+    const derived = typeof opts.vault?.cardUrlPatterns === 'function' ? opts.vault.cardUrlPatterns() : [];
+    const urlPatterns = derived.length > 0 ? derived : FALLBACK_CARD_PATTERNS;
+    opts.onEvent?.({ type: 'fetch_armed', detail: { patterns: urlPatterns } });
     const arm = async (sessionId) => {
         const key = sessionId ?? '__root__';
         if (armed.has(key))
             return;
         armed.add(key);
         await cdp.send('Fetch.enable', {
-            patterns: CARD_PATTERNS.map((urlPattern) => ({ urlPattern, requestStage: 'Request' })),
+            patterns: urlPatterns.map((urlPattern) => ({ urlPattern, requestStage: 'Request' })),
         }, sessionId).catch(() => { });
         // Descend into this target's own children (iframes inside iframes).
         await cdp.send('Target.setAutoAttach', {
@@ -39,36 +203,102 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         }
         if (method !== 'Fetch.requestPaused')
             return;
-        const { requestId, request } = params;
+        const { requestId, request, resourceType } = params;
         if (!opts.vault.isCardRequest(request.url, request.method)) {
             await cdp.send('Fetch.continueRequest', { requestId }, sessionId).catch(() => { });
             return;
         }
-        let body = request.postData ?? '';
-        if (!body && request.hasPostData) {
-            body = (await cdp.send('Fetch.getRequestPostData', { requestId }, sessionId).catch(() => ({ postData: '' }))).postData ?? '';
+        // Same stop condition as the Playwright adapter: once a failure proves
+        // retrying is pointless, fail the request without calling the API again.
+        if (terminal || awaitingApproval || Date.now() < quietUntil) {
+            const why = terminal ?? (awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
+            opts.onEvent?.({ type: 'blocked', detail: String(why) });
+            await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
+            return;
         }
-        opts.onEvent?.({ type: 'card_request_paused', detail: { url: request.url } });
+        // Reserve BEFORE the first await (the authorize call below yields), so two
+        // requests can never both clear the check above and raise two prompts for
+        // one checkout.
+        awaitingApproval = true;
         try {
+            const body = pausedBody(request);
+            if (body === null) {
+                // Fail closed, but only THIS request: an unreadable body says nothing
+                // about the page's configuration, so the next request is judged
+                // afresh (no latch, no cooldown).
+                opts.onEvent?.({ type: 'failed', detail: BODY_UNREADABLE_REASON });
+                await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
+                return;
+            }
+            // The body is needed to tell a re-post of the form the cardholder
+            // already submitted from a new one, so this check sits after the read
+            // and before any API call: no second prompt, no round trip.
+            if (isRepeatOfSubmitted(lastSubmitted, request.url, body, repeatQuietMs)) {
+                opts.onEvent?.({ type: 'blocked', detail: HOSTED_FORM_REPEAT_REASON });
+                await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
+                return;
+            }
+            opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url), ...(resourceType ? { resourceType } : {}) } });
             const replay = await opts.vault.authorize({
                 user: opts.user,
                 merchant: opts.merchant,
                 amount: opts.amount,
+                amountCents: opts.amountCents,
+                currency: opts.currency,
                 onApprovalUrl: opts.onApprovalUrl,
                 request: { url: request.url, method: request.method, headers: request.headers, body },
             });
-            await cdp.send('Fetch.fulfillRequest', {
-                requestId,
-                responseCode: replay.status,
-                responseHeaders: Object.entries(replay.headers).map(([name, value]) => ({ name, value: String(value) })),
-                body: Buffer.from(replay.body).toString('base64'),
-            }, sessionId);
-            opts.onEvent?.({ type: 'authorized' });
+            if (replay.mode === 'hosted_form') {
+                // The device submitted the processor's own form; the processor
+                // answered the device. The paused NAVIGATION is fulfilled with a page
+                // that says exactly that (see hosted-form.ts for why not an abort and
+                // why not a fake result page), and the same form is refused if the
+                // page posts it again.
+                const page = hostedFormSubmittedPage({ authorizationId: replay.authorizationId, merchant: opts.merchant, submittedAt: replay.submittedAt });
+                await cdp.send('Fetch.fulfillRequest', {
+                    requestId,
+                    responseCode: page.status,
+                    responseHeaders: Object.entries(page.headers).map(([name, value]) => ({ name, value })),
+                    body: Buffer.from(page.body).toString('base64'),
+                }, sessionId);
+                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.
+                opts.onEvent?.({ type: 'submitted_on_device', detail: { authorizationId: replay.authorizationId, submittedAt: replay.submittedAt, outcome: replay.outcome } });
+            }
+            else if (replay.mode === 'cse') {
+                // The device encrypted the card for the processor; the request itself
+                // still goes out from THIS browser, with its own session, risk data
+                // and cookies, and only the four ciphertext fields swapped in. Only
+                // postData rides on the command: no header override, ever (see
+                // cseBody for why a recomputed Content-Length is refused by Chromium).
+                await cdp.send('Fetch.continueRequest', {
+                    requestId,
+                    postData: Buffer.from(cseBody(body, replay)).toString('base64'),
+                }, sessionId);
+                opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
+            }
+            else {
+                await cdp.send('Fetch.fulfillRequest', {
+                    requestId,
+                    responseCode: replay.status,
+                    responseHeaders: Object.entries(replay.headers).map(([name, value]) => ({ name, value: String(value) })),
+                    body: Buffer.from(replay.body).toString('base64'),
+                }, sessionId);
+                opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null } });
+            }
         }
         catch (err) {
+            if (isTerminal(err))
+                terminal = err;
+            else if (isApprovalOutcome(err))
+                quietUntil = Date.now() + cooldownMs;
             opts.onEvent?.({ type: 'failed', detail: String(err) });
             await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
         }
+        finally {
+            awaitingApproval = false;
+        }
     });
     await arm(pageSessionId);
 }
@@ -95,6 +325,17 @@ export async function attachToPlaywright(page, opts) {
     //
     // page.route already spans subframes, so Playwright does the target
     // bookkeeping that attachToCdp has to do by hand for a raw connection.
+    // Set once a failure proves that retrying cannot help. The page is free to
+    // keep retrying; we simply stop asking the API and fail the request outright.
+    let terminal = null;
+    // Silence window after a person declined or ignored one; see APPROVAL_COOLDOWN_MS.
+    const cooldownMs = opts.approvalCooldownMs ?? APPROVAL_COOLDOWN_MS;
+    let quietUntil = 0;
+    // One outstanding approval at a time; see the note above isApprovalOutcome.
+    let awaitingApproval = false;
+    // 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;
     await page.route((url) => opts.vault.isCardRequest(url.toString()), async (route) => {
         const request = route.request();
         // The matcher only sees the URL; a preflight or a GET must pass through
@@ -102,22 +343,64 @@ export async function attachToPlaywright(page, opts) {
         if (!opts.vault.isCardRequest(request.url(), request.method())) {
             return route.fallback();
         }
-        const body = request.postData() ?? '';
-        opts.onEvent?.({ type: 'card_request_paused', detail: { url: request.url() } });
+        // 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
+        // CDP adapter's Fetch.failRequest uses, so a refused navigation
+        // resolves identically whichever adapter is attached.
+        if (terminal || awaitingApproval || Date.now() < quietUntil) {
+            const why = terminal ?? (awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
+            opts.onEvent?.({ type: 'blocked', detail: String(why) });
+            return route.abort('aborted');
+        }
+        // Reserved before anything that could yield, matching attachToCdp.
+        awaitingApproval = true;
         try {
+            const body = request.postData() ?? '';
+            if (isRepeatOfSubmitted(lastSubmitted, request.url(), body, repeatQuietMs)) {
+                opts.onEvent?.({ type: 'blocked', detail: HOSTED_FORM_REPEAT_REASON });
+                return await route.abort('aborted');
+            }
+            opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url()) } });
             const replay = await opts.vault.authorize({
                 user: opts.user,
                 merchant: opts.merchant,
                 amount: opts.amount,
+                amountCents: opts.amountCents,
+                currency: opts.currency,
                 onApprovalUrl: opts.onApprovalUrl,
                 request: { url: request.url(), method: request.method(), headers: request.headers(), body },
             });
-            await route.fulfill({ status: replay.status, headers: replay.headers, body: replay.body });
-            opts.onEvent?.({ type: 'authorized' });
+            if (replay.mode === 'hosted_form') {
+                // Same as the CDP path: the paused navigation resolves to the
+                // synthetic page, and a re-post of this form is refused.
+                const synthetic = hostedFormSubmittedPage({ authorizationId: replay.authorizationId, merchant: opts.merchant, submittedAt: replay.submittedAt });
+                await route.fulfill({ status: synthetic.status, headers: synthetic.headers, body: synthetic.body });
+                lastSubmitted = { url: request.url(), body, at: Date.now() };
+                opts.onEvent?.({ type: 'submitted_on_device', detail: { authorizationId: replay.authorizationId, submittedAt: replay.submittedAt, outcome: replay.outcome } });
+            }
+            else if (replay.mode === 'cse') {
+                // Same as the CDP path: the request continues from this browser
+                // with the ciphertext swapped in and no header override; Playwright
+                // recomputes the length itself.
+                await route.continue({ postData: cseBody(body, replay) });
+                opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
+            }
+            else {
+                await route.fulfill({ status: replay.status, headers: replay.headers, body: replay.body });
+                opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null } });
+            }
         }
         catch (err) {
+            if (isTerminal(err))
+                terminal = err;
+            else if (isApprovalOutcome(err))
+                quietUntil = Date.now() + cooldownMs;
             opts.onEvent?.({ type: 'failed', detail: String(err) });
-            await route.abort();
+            await route.abort('aborted');
+        }
+        finally {
+            awaitingApproval = false;
         }
     });
 }