@agent-cards/checkout 0.15.1 → 0.15.2

package/dist/cdp.d.ts

@@ -67,11 +67,40 @@ export declare function withCorsHeaders(headers: Record<string, string>, cors: R
 /**
  * Browser-level, session-aware CDP connection. A page-scoped Playwright or
  * Puppeteer CDPSession is NOT this interface; use attachToPlaywright for those.
+ *
+ * Forward commands and events over a browser WebSocket with flattened sessions.
+ * An omitted sessionId means the browser root, never a default page session.
+ * Attachment requires Target.getTargetInfo on the supplied page session, then
+ * Target.setDiscoverTargets and Target.getTargets at the browser root. Forward
+ * root Target.targetCreated/targetInfoChanged events with no sessionId, and
+ * preserve the sessionId on child attachment, Fetch, and Network events.
+ * Page/iframe sessions must support Page, Fetch, Network, and Target; dedicated
+ * workers require Network, Target, and Runtime.runIfWaitingForDebugger.
+ * Unsupported or incomplete discovery fails with CheckoutAttachmentError
+ * before fetch_armed. TypeScript describes forwarding; attachment verifies
+ * the browser's runtime capabilities and returned metadata.
  */
 export interface CdpLike {
+    /** Read the merchant target on the page session; returns { targetInfo: CdpTargetInfo }. */
+    send(method: 'Target.getTargetInfo', params: Record<string, never>, sessionId: string): Promise<any>;
+    /** Enable root discovery events, including targets outside the page tree. */
+    send(method: 'Target.setDiscoverTargets', params: {
+        discover: boolean;
+    }, sessionId?: undefined): Promise<any>;
+    /** Read { targetInfos: CdpTargetInfo[] }; missing sessionId must remain browser-scoped. */
+    send(method: 'Target.getTargets', params?: Record<string, never>, sessionId?: undefined): Promise<any>;
+    /** Forward other CDP commands unchanged; unsupported commands must reject. */
     send(method: string, params?: any, sessionId?: string): Promise<any>;
+    /** Deliver browser-root events as well as events from flattened child sessions. */
     on(handler: (method: string, params: any, sessionId?: string) => void): void;
 }
+/** Browser Target metadata used to establish which checkout owns a worker. */
+export interface CdpTargetInfo {
+    targetId: string;
+    type: string;
+    /** Absent for the default browser context. */
+    browserContextId?: string;
+}
 export interface AttachOptions extends LifecycleOptions, ExecutionMetadata {
     /** Explicit native hosted Stripe Checkout TEST integration; requires an Autopilot grant. */
     stripeCheckout?: StripeCheckoutOptions;
@@ -104,7 +133,7 @@ export interface AttachOptions extends LifecycleOptions, ExecutionMetadata {
     } | undefined>;
     cardId?: string;
     timeoutMs?: number;
-    /** Browser interception setup deadline, separate from approval. Defaults to 30000 ms; maximum 300000 ms. */
+    /** Interception setup and request ownership deadline, separate from approval. Defaults to 30000 ms; maximum 300000 ms. */
     attachmentTimeoutMs?: number;
     /** Explicit payment endpoints to block if the registry cannot handle their method/format. Unlisted traffic is untouched. */
     paymentEndpoints?: readonly PaymentEndpointGuard[];

package/dist/cdp.js

@@ -35,6 +35,27 @@ 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';
+function targetRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function contextId(value) {
+    return typeof value === 'string' && value.length > 0 && value.length <= 256 && !/[\u0000-\u0020\u007f]/.test(value);
+}
+/** Dedicated worker requests use their owning frame's Fetch interception.
+ * Shared/service workers do not have that ownership guarantee. Refuse their
+ * browser context, including newly discovered targets, before approving a card.
+ * A different, explicitly identified context belongs to another checkout.
+ */
+function assertContextTarget(target, merchantContext) {
+    if (!targetRecord(target))
+        throw new CheckoutAttachmentError('unavailable');
+    if (contextId(target.browserContextId) && target.browserContextId !== merchantContext)
+        return;
+    if (!['page', 'iframe', 'worker', 'browser_ui'].includes(target.type)
+        || (target.browserContextId !== undefined && !contextId(target.browserContextId))) {
+        throw new CheckoutAttachmentError('unavailable');
+    }
+}
 /**
  * How long to stop asking after a person declines or ignores an approval.
  *
@@ -373,13 +394,18 @@ function failureSummary(error) {
 /** 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');
+    let reason = 'merchant_request_aborted';
+    const error = () => new PaymentOutcomeUnknownError(lifecycle.getState().authorizationId, reason);
     return {
         signal: controller.signal,
-        stop() {
+        stop(cause = 'merchant_request_aborted') {
             if (controller.signal.aborted)
                 return;
-            lifecycle.merchantRequestAborted();
+            reason = cause;
+            if (cause === 'merchant_request_aborted')
+                lifecycle.merchantRequestAborted();
+            else
+                lifecycle.failed(error());
             controller.abort(error());
         },
         assertLive() { if (controller.signal.aborted)
@@ -409,6 +435,56 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     const setupStop = new AbortController();
     let attachmentReady = false;
     let setupFailureReported = false;
+    const ownedSessions = new Set([pageSessionId]);
+    const sessionTypes = new Map([[pageSessionId, 'page']]);
+    const sessionParents = new Map();
+    const detachedSessions = new Set();
+    const workerOwners = new Map();
+    const ownersWithWorkers = new Set();
+    // Network IDs are scoped to their emitting session. Retired records are
+    // separate from live requests, but still disqualify an indistinguishable
+    // delayed Fetch event; deleting that evidence could approve a lost request.
+    const requestSources = new Map();
+    const retiredSources = new Map();
+    const retiredCounts = new Map();
+    // Keep exact evidence for the first 1,024 failures per owner. Later failures
+    // enter a fixed 256 KiB Bloom filter with seven positions: a membership hit
+    // refuses that Network ID, never the whole frame merely for reaching a cap.
+    // Fetch lacks the emitter session, so compact evidence uses owner + Network
+    // ID; exact records below still use session + ID. False positives may refuse
+    // a request, but a failed identity is never forgotten or treated as live.
+    // The filters are controller-local and monotonic. They are not rotated or
+    // cleared on worker detach; arbitrary late Network/Fetch delivery is allowed.
+    // A sufficiently long history can saturate a filter and reduce availability.
+    const retiredSummaries = new Map();
+    const summaryBytes = 256 * 1024;
+    const summaryPositions = (id) => {
+        const positions = [];
+        for (let seed = 1; seed <= 7; seed++) {
+            let hash = 0x811c9dc5 ^ Math.imul(seed, 0x9e3779b9);
+            for (let i = 0; i < id.length; i++)
+                hash = Math.imul(hash ^ id.charCodeAt(i), 0x01000193);
+            hash = Math.imul(hash ^ (hash >>> 16), 0x85ebca6b);
+            hash = Math.imul(hash ^ (hash >>> 13), 0xc2b2ae35);
+            positions.push((hash ^ (hash >>> 16)) & (summaryBytes * 8 - 1));
+        }
+        return positions;
+    };
+    const hasRetiredSummary = (owner, id) => {
+        const bits = retiredSummaries.get(owner);
+        return !!bits && summaryPositions(id).every(bit => (bits[bit >>> 3] & (1 << (bit & 7))) !== 0);
+    };
+    const requestKey = (sessionId, id) => JSON.stringify([sessionId, id]);
+    const sessionDetached = (sessionId) => {
+        while (sessionId) {
+            if (detachedSessions.has(sessionId))
+                return true;
+            sessionId = sessionParents.get(sessionId);
+        }
+        return false;
+    };
+    let merchantContext;
+    let targetContextKnown = false;
     const lifecycle = new CheckoutLifecycle(opts);
     const stripeCheckout = new StripeCheckoutGate(opts);
     const mercadoCheckout = new MercadoCheckoutGate();
@@ -432,13 +508,125 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     // One outstanding approval at a time; see the note above isApprovalOutcome.
     let awaitingApproval = false;
     let activeRequest = null;
+    const sourceOwner = (source) => workerOwners.get(source.sessionId) ?? source.sessionId;
+    const retireSource = (source) => {
+        const owner = sourceOwner(source), key = requestKey(source.sessionId, source.networkId);
+        const count = (retiredCounts.get(owner) ?? 0) + (retiredSources.has(key) ? 0 : 1);
+        // Compact overflow without dropping failed identities or turning unrelated
+        // background failures into a permanent refusal of every request in a frame.
+        if (count > 1024) {
+            let bits = retiredSummaries.get(owner);
+            if (!bits) {
+                bits = new Uint8Array(summaryBytes);
+                retiredSummaries.set(owner, bits);
+            }
+            for (const bit of summaryPositions(source.networkId))
+                bits[bit >>> 3] |= 1 << (bit & 7);
+            if (activeRequest?.sessionId === owner && hasRetiredSummary(owner, activeRequest.networkId)) {
+                activeRequest.attempt.stop('browser_interception_unavailable');
+            }
+            return;
+        }
+        retiredCounts.set(owner, count);
+        retiredSources.set(key, source);
+    };
+    const identifyRequest = (request) => {
+        if (request.sessionId && hasRetiredSummary(request.sessionId, request.networkId)) {
+            request.attempt.stop('browser_interception_unavailable');
+            request.attempt.assertLive();
+        }
+        const matches = (source) => {
+            const metadata = source.request;
+            return sourceOwner(source) === request.sessionId
+                && source.networkId === request.networkId && (!metadata
+                || (metadata.url === request.request.url && metadata.method === request.request.method
+                    // A missing body is unknown, not evidence of a different request.
+                    && !(typeof metadata.postData === 'string' && typeof request.request.postData === 'string'
+                        && metadata.postData !== request.request.postData)));
+        };
+        const candidates = [...requestSources.values(), ...retiredSources.values()].filter(matches);
+        if (!candidates.length)
+            return false;
+        // A failure can arrive before its Network request description. Do not
+        // ignore that possible source and assign its Fetch to a live sibling.
+        if (candidates.some(source => !source.request)) {
+            if (request.sourceSessionId) {
+                request.attempt.stop('browser_interception_unavailable');
+                request.attempt.assertLive();
+            }
+            return false;
+        }
+        if (candidates.length !== 1) {
+            request.attempt.stop('browser_interception_unavailable');
+            request.attempt.assertLive();
+        }
+        const source = candidates[0];
+        if (request.sourceSessionId && request.sourceSessionId !== source.sessionId) {
+            request.attempt.stop('browser_interception_unavailable');
+        }
+        request.sourceSessionId = source.sessionId;
+        if (sessionDetached(source.sessionId) || retiredSources.has(requestKey(source.sessionId, source.networkId)))
+            request.attempt.stop();
+        request.attempt.assertLive();
+        return true;
+    };
+    /** A frame's Fetch event does not identify which dedicated worker sent it.
+     * Require the exact Network event before asking the Vault whenever that frame
+     * has had workers. A sibling's detach proves nothing about an unknown request;
+     * missing attribution instead expires without releasing any card or token.
+     * Keep detached ancestry so a late event cannot revive a lost worker request.
+     */
+    const awaitRequestSource = async (request) => {
+        if (identifyRequest(request))
+            return;
+        if (!request.sessionId || !ownersWithWorkers.has(request.sessionId)) {
+            if (request.sessionId && retiredSources.has(requestKey(request.sessionId, request.networkId))) {
+                request.attempt.stop();
+                request.attempt.assertLive();
+            }
+            request.sourceSessionId = request.sessionId;
+            return;
+        }
+        let timer;
+        let changed = () => { };
+        const signals = [request.attempt.signal, lifecycle.abort.signal, setupStop.signal];
+        try {
+            await new Promise((resolve, reject) => {
+                changed = () => {
+                    try {
+                        request.attempt.assertLive();
+                        if (lifecycle.isCancelled())
+                            throw new Error('checkout cancelled locally before approval');
+                        if (setupStop.signal.aborted)
+                            throw new PaymentOutcomeUnknownError(null, 'browser_interception_unavailable');
+                        if (identifyRequest(request))
+                            resolve();
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                };
+                request.attributionChanged = changed;
+                for (const signal of signals)
+                    signal.addEventListener('abort', changed, { once: true });
+                timer = setTimeout(() => reject(new PaymentOutcomeUnknownError(null, 'browser_interception_unavailable')), setupTimeoutMs);
+                changed();
+            });
+        }
+        finally {
+            clearTimeout(timer);
+            for (const signal of signals)
+                signal.removeEventListener('abort', changed);
+            delete request.attributionChanged;
+        }
+    };
     // 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 = [...new Set([...(derived.length > 0 ? derived : FALLBACK_CARD_PATTERNS), ...guards.patterns,
             ...(stripeCheckout.isEnabled() ? ['https://api.stripe.com/*'] : []), MERCADO_CHECKOUT_PATTERN])];
-    const arm = async (sessionId, resume = false) => {
+    const arm = async (sessionId, resume = false, worker = false) => {
         const key = sessionId ?? '__root__';
         if (armed.has(key))
             return;
@@ -446,15 +634,26 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             return arming.get(key);
         // 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.
-        const pending = withinAttachmentDeadline(async (assertActive) => {
+        const pending = withinAttachmentDeadline(async (assertDeadline) => {
+            const assertActive = () => {
+                assertDeadline();
+                if (sessionId && detachedSessions.has(sessionId))
+                    throw new CheckoutAttachmentError('closed');
+            };
             await cdp.send('Network.enable', {}, sessionId);
             assertActive();
-            await cdp.send('Page.enable', {}, sessionId).catch(() => { });
-            assertActive();
-            await cdp.send('Fetch.enable', {
-                patterns: urlPatterns.map((urlPattern) => ({ urlPattern, requestStage: 'Request' })),
-            }, sessionId);
-            assertActive();
+            // Worker Fetch does not exist in Chrome. Its requests pause on the owning
+            // frame, but its abort/finish events arrive on the worker Network session.
+            // Keep that session attached and paused until Network is listening, then
+            // resume it only after its nested workers can be attached recursively.
+            if (!worker) {
+                await cdp.send('Page.enable', {}, sessionId).catch(() => { });
+                assertActive();
+                await cdp.send('Fetch.enable', {
+                    patterns: urlPatterns.map((urlPattern) => ({ urlPattern, requestStage: 'Request' })),
+                }, sessionId);
+                assertActive();
+            }
             // Descend into this target's own children (iframes inside iframes).
             await cdp.send('Target.setAutoAttach', {
                 autoAttach: true, waitForDebuggerOnStart: true, flatten: true,
@@ -481,7 +680,33 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             arming.delete(key);
         }
     };
+    const failInterception = (error) => {
+        if (setupFailureReported)
+            return;
+        setupFailureReported = true;
+        setupStop.abort(attachmentFailure(error));
+        terminal = new Error('browser_interception_unavailable');
+        // A new target changes future interception, not the result of an earlier
+        // attempt. Preserve a settled result or handoff while still refusing new
+        // requests. Approval/preparation in progress must instead be retired.
+        const status = lifecycle.getState().status;
+        if (status === 'completed' || (!activeRequest && !['idle', 'awaiting_approval', 'ready_to_submit'].includes(status)))
+            return;
+        activeRequest?.attempt.stop();
+        preparationGate.invalidate('browser_interception_unavailable');
+        lifecycle.failed(new PaymentOutcomeUnknownError(lifecycle.getState().authorizationId, 'browser_interception_unavailable'));
+        opts.onEvent?.({ type: 'failed', detail: 'browser_interception_unavailable' });
+    };
     cdp.on(async (method, params, sessionId) => {
+        if ((method === 'Target.targetCreated' || method === 'Target.targetInfoChanged') && targetContextKnown) {
+            try {
+                assertContextTarget(params?.targetInfo, merchantContext);
+            }
+            catch (error) {
+                failInterception(error);
+            }
+            return;
+        }
         if (((method === 'Page.frameNavigated' && !params.frame?.parentId) || (method === 'Page.navigatedWithinDocument' && preparationFrameId && params.frameId === preparationFrameId)) && sessionId === pageSessionId) {
             preparationGate.invalidate('merchant_document_changed');
             mercadoCheckout.invalidate();
@@ -495,6 +720,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         }
         if ((method === 'Inspector.detached' && sessionId === pageSessionId)
             || (method === 'Target.detachedFromTarget' && params.sessionId === pageSessionId)) {
+            detachedSessions.add(pageSessionId);
             setupStop.abort(new CheckoutAttachmentError('closed'));
             preparationGate.invalidate('merchant_document_closed');
             stripeCheckout.invalidate();
@@ -502,9 +728,52 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             // The root page owns every attached OOPIF; its loss ends child requests too.
             activeRequest?.attempt.stop();
         }
+        // The transport is browser-scoped. A second tab's request or child target
+        // must never be authorized with this page's merchant, amount or preparation.
+        if (!sessionId || !ownedSessions.has(sessionId))
+            return;
+        if (method === 'Network.requestWillBeSent') {
+            const owner = workerOwners.get(sessionId) ?? sessionId;
+            const matchesActive = activeRequest?.sessionId === owner && activeRequest.networkId === params.requestId;
+            // Only identification may consume a late event from a detached target.
+            // Its Fetch events, children and commands remain permanently ignored.
+            if (sessionDetached(sessionId) && !matchesActive)
+                return;
+            const key = requestKey(sessionId, params.requestId);
+            const record = { sessionId, networkId: params.requestId, request: params.request };
+            if (sessionDetached(sessionId) || retiredSources.has(key) || hasRetiredSummary(owner, params.requestId))
+                retireSource(record);
+            else
+                requestSources.set(key, record);
+            if (matchesActive) {
+                try {
+                    identifyRequest(activeRequest);
+                }
+                catch { /* stop already retires the exact attempt */ }
+                activeRequest.attributionChanged?.();
+            }
+            return;
+        }
+        if (sessionDetached(sessionId))
+            return;
+        if (method === 'Network.loadingFinished') {
+            requestSources.delete(requestKey(sessionId, params.requestId));
+            return;
+        }
         if (method === 'Network.loadingFailed') {
-            if (activeRequest && activeRequest.networkId === params.requestId && activeRequest.sessionId === sessionId)
+            if (activeRequest && activeRequest.networkId === params.requestId
+                && activeRequest.sourceSessionId === sessionId)
                 activeRequest.attempt.stop();
+            const key = requestKey(sessionId, params.requestId);
+            retireSource(requestSources.get(key) ?? { sessionId, networkId: params.requestId });
+            requestSources.delete(key);
+            if (activeRequest?.sessionId === (workerOwners.get(sessionId) ?? sessionId) && activeRequest.networkId === params.requestId) {
+                try {
+                    identifyRequest(activeRequest);
+                }
+                catch { /* its exact origin is unavailable */ }
+                activeRequest.attributionChanged?.();
+            }
             return;
         }
         if (method === 'Target.detachedFromTarget' || method === 'Inspector.detached' || method === 'Page.frameDetached') {
@@ -512,6 +781,23 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 : method === 'Inspector.detached' ? activeRequest.sessionId === sessionId
                     : activeRequest.sessionId === sessionId && activeRequest.frameId === params.frameId))
                 activeRequest.attempt.stop();
+            if (method !== 'Page.frameDetached') {
+                const detached = method === 'Target.detachedFromTarget' ? params.sessionId : sessionId;
+                detachedSessions.add(detached);
+                if (arming.has(detached))
+                    failInterception(new CheckoutAttachmentError('closed'));
+                // Terminating a worker need not emit loadingFailed. Its nested workers
+                // also lose their request. An unknown request waits for attribution;
+                // detaching an unrelated sibling must never cancel the card approval.
+                const source = activeRequest?.sourceSessionId;
+                if (activeRequest && (sessionDetached(activeRequest.sessionId) || (source && sessionDetached(source))))
+                    activeRequest.attempt.stop();
+                for (const [key, record] of requestSources)
+                    if (sessionDetached(record.sessionId)) {
+                        retireSource(record);
+                        requestSources.delete(key);
+                    }
+            }
             return;
         }
         if (method === 'Target.attachedToTarget') {
@@ -519,18 +805,27 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 return;
             const child = params.sessionId;
             try {
-                await arm(child, true);
+                if (typeof child !== 'string' || !child || !['page', 'iframe', 'worker'].includes(params.targetInfo?.type)) {
+                    throw new CheckoutAttachmentError('unavailable');
+                }
+                if (child === pageSessionId || detachedSessions.has(child) || (ownedSessions.has(child)
+                    && (sessionParents.get(child) !== sessionId || sessionTypes.get(child) !== params.targetInfo.type))) {
+                    throw new CheckoutAttachmentError('unavailable');
+                }
+                ownedSessions.add(child);
+                sessionTypes.set(child, params.targetInfo.type);
+                sessionParents.set(child, sessionId);
+                if (params.targetInfo.type === 'worker') {
+                    const owner = workerOwners.get(sessionId) ?? sessionId;
+                    workerOwners.set(child, owner);
+                    ownersWithWorkers.add(owner);
+                }
+                await arm(child, true, params.targetInfo.type === 'worker');
             }
             catch (error) {
                 // Shared child setup and sibling cancellation can reject several
                 // handlers together. Publish the terminal setup failure only once.
-                if (setupFailureReported)
-                    return;
-                setupFailureReported = true;
-                setupStop.abort(attachmentFailure(error));
-                terminal = new Error('browser_interception_unavailable');
-                lifecycle.failed(new PaymentOutcomeUnknownError(lifecycle.getState().authorizationId, 'browser_interception_unavailable'));
-                opts.onEvent?.({ type: 'failed', detail: 'browser_interception_unavailable' });
+                failInterception(error);
                 // Leave this target paused: resuming an unarmed card frame would silently bypass the vault.
                 return;
             }
@@ -692,7 +987,8 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 attempt.stop();
                 attempt.assertLive();
             }
-            activeRequest = { attempt, networkId, sessionId, frameId };
+            activeRequest = { attempt, networkId, sessionId, frameId, request };
+            await awaitRequestSource(activeRequest);
             if (preparation)
                 await preparationGate.assertDocument();
             const pageOrigin = await pageOriginOf(readDocumentUrl, attempt.signal);
@@ -799,7 +1095,17 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             // Ignore the failure event caused by our own safe decline/error abort.
             if (activeRequest?.attempt === attempt)
                 activeRequest = null;
-            lifecycle.failed(err, handoffStarted);
+            // Vault clients may normalize a merchantSignal abort. Preserve the
+            // adapter's more precise cause when ownership became ambiguous.
+            try {
+                attempt.assertLive();
+            }
+            catch (stopped) {
+                err = stopped;
+            }
+            // stop() already published the terminal state before aborting the Vault.
+            if (!attempt.signal.aborted)
+                lifecycle.failed(err, handoffStarted);
             if (isTerminal(err))
                 terminal = err;
             else if (isApprovalOutcome(err))
@@ -817,7 +1123,31 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         }
     });
     try {
-        await arm(pageSessionId);
+        await withinAttachmentDeadline(async (assertActive) => {
+            const { targetInfo } = await cdp.send('Target.getTargetInfo', {}, pageSessionId);
+            assertActive();
+            if (!targetRecord(targetInfo) || targetInfo.type !== 'page'
+                || (targetInfo.browserContextId !== undefined && !contextId(targetInfo.browserContextId))) {
+                throw new CheckoutAttachmentError('unavailable');
+            }
+            merchantContext = targetInfo.browserContextId;
+            targetContextKnown = true;
+            await cdp.send('Target.setDiscoverTargets', { discover: true });
+            assertActive();
+            const { targetInfos } = await cdp.send('Target.getTargets');
+            assertActive();
+            if (!Array.isArray(targetInfos))
+                throw new CheckoutAttachmentError('unavailable');
+            for (const target of targetInfos)
+                assertContextTarget(target, merchantContext);
+            await arm(pageSessionId);
+            // Existing OOPIFs report attachment before the parent's acknowledgement,
+            // but their Fetch setup finishes later. Do not invite the caller to press
+            // Pay while one of those already-running frames is still unprotected.
+            while (arming.size)
+                await Promise.all(arming.values());
+            assertActive();
+        }, setupTimeoutMs, setupStop.signal);
         if (setupStop.signal.aborted)
             throw attachmentFailure(setupStop.signal.reason);
         attachmentReady = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/checkout",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "description": "Let browser agents pay with the user's own card, without your infrastructure ever touching card data.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,8 +27,8 @@
     "_comment_build": "The public SDK keeps zero runtime dependencies. Its build vendors deterministic metadata and substitution artifacts from the internal payment core; TypeScript remains pinned.",
     "build": "node ../payment-core/scripts/build.mjs && node scripts/generate-payment-core.mjs && npx -y -p typescript@5.9.3 tsc && node scripts/generate-preflight-contract.mjs",
     "prepublishOnly": "pnpm build",
-    "test": "node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs braintree.test.mjs autopilot.test.mjs stripe-checkout.test.mjs payment-core.test.mjs prepared-processor.test.mjs minimum-delay.test.mjs paysafe.test.mjs attachment.test.mjs mercado-checkout.test.mjs mercado-polling.test.mjs && node --test preflight-package.test.mjs preflight-collector.test.mjs && node --test kernel-native-qualification.test.mjs && node --test ../vault/scripts/recurly-validation/watch-duty-sdk-result.test.mjs",
-    "test:browser": "node browser.test.mjs && node stripe-browser.test.mjs && node preparation-browser.test.mjs && node owned-shop-browser.test.mjs && node spreedly-browser.test.mjs",
+    "test": "node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs braintree.test.mjs autopilot.test.mjs stripe-checkout.test.mjs payment-core.test.mjs prepared-processor.test.mjs minimum-delay.test.mjs paysafe.test.mjs attachment.test.mjs worker-targets.test.mjs mercado-checkout.test.mjs mercado-polling.test.mjs && node --test preflight-package.test.mjs preflight-collector.test.mjs && node --test kernel-native-qualification.test.mjs && node --test ../vault/scripts/recurly-validation/watch-duty-sdk-result.test.mjs",
+    "test:browser": "node browser.test.mjs && node stripe-browser.test.mjs && node preparation-browser.test.mjs && node owned-shop-browser.test.mjs && node spreedly-browser.test.mjs && node worker-browser.test.mjs",
     "check:payment-core": "node scripts/generate-payment-core.mjs --check",
     "test:preflight": "node --test preflight-package.test.mjs preflight-collector.test.mjs kernel-native-qualification.test.mjs",
     "test:preflight:browser": "node preflight-browser.test.mjs",