mppx 0.14.1 → 0.16.0

package/dist/cli/validate/payment.d.ts

@@ -1,3 +1,4 @@
+import { type SessionReceipt } from '../../tempo/session/precompile/Protocol.js';
 import type { CheckResult, EndpointSpec } from './helpers.js';
 export declare function validatePaymentFlow(baseUrl: string, endpoint: EndpointSpec, verbose: boolean, options: {
     body?: string | undefined;
@@ -8,4 +9,15 @@ export declare function validatePaymentFlow(baseUrl: string, endpoint: EndpointS
     interactive?: boolean | undefined;
     onResults?: (results: CheckResult[]) => void;
 }): Promise<CheckResult[]>;
+/**
+ * Wraps a fetch so in-stream session receipts are seen as the session client reads them: the
+ * client consumes `payment-receipt` events before the caller sees the body. Event-stream
+ * responses without a `Payment-Receipt` header pass through a scanner that keeps only the
+ * current partial event, so nothing is buffered or left unread.
+ */
+/** @internal */
+export declare function captureEventStream(fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>): {
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    receipt: () => SessionReceipt | null | undefined;
+};
 //# sourceMappingURL=payment.d.ts.map

package/dist/cli/validate/payment.js

@@ -6,12 +6,14 @@ import * as viemChains from 'viem/chains';
 import { Actions } from 'viem/tempo';
 import { tempoModerato, tempo as tempoMainnetChain } from 'viem/tempo/chains';
 import * as Challenge from '../../Challenge.js';
+import * as ProofRealm from '../../client/internal/ProofRealm.js';
 import * as Mppx from '../../client/Mppx.js';
 import * as Constants from '../../Constants.js';
 import * as Receipt from '../../Receipt.js';
 import { tempo as tempoMethods } from '../../tempo/client/index.js';
 import { chainId as tempoChainIds } from '../../tempo/internal/defaults.js';
 import { isTempoSessionChallenge } from '../../tempo/session/client/Transports.js';
+import { isEventStream, parseEvent, } from '../../tempo/session/precompile/Protocol.js';
 import { resolveAccount, resolveAccountName } from '../account.js';
 import { assertSamePaymentRequest, flattenConfigMethods, loadConfig, preparePayment, resolvePlugin, } from '../internal.js';
 import { fetchTokenInfo, confirm, pc } from '../utils.js';
@@ -189,6 +191,7 @@ export async function validatePaymentFlow(baseUrl, endpoint, verbose, options) {
         const provisioned = await provisionAndPayTestnet(tempoTestnetChallenge, verbose, options.silent);
         if (provisioned) {
             try {
+                const raw = captureEventStream((input, init) => fetchWithTimeout(input, init ?? {}, 30_000));
                 const mppx = Mppx.create({
                     methods: provisioned.methods,
                     polyfill: false,
@@ -199,14 +202,14 @@ export async function validatePaymentFlow(baseUrl, endpoint, verbose, options) {
                         results.push(check('Payment: submitted', 'ephemeral testnet wallet'));
                         return credential;
                     },
-                    fetch: (input, init) => fetchWithTimeout(input, init ?? {}, 30_000),
+                    fetch: raw.fetch,
                 });
                 const response = await mppx.fetch(url, {
                     method: endpoint.method,
                     headers: fetchHeaders,
                     body: fetchBody ?? null,
                 });
-                await validatePaymentResponse(results, response, verbose, tempoModerato);
+                await validatePaymentResponse(results, response, verbose, tempoModerato, isTempoSessionChallenge(tempoTestnetChallenge), raw.receipt);
             }
             catch (error) {
                 results.push(fail('Payment: create credential', error.message));
@@ -408,6 +411,7 @@ async function attemptCryptoPayment(challenge, tag, ctx) {
     }
     if (directMethod && isTempoSessionChallenge(challenge)) {
         let initial = true;
+        const raw = captureEventStream((input, init) => fetchWithTimeout(input, init ?? {}, 30_000));
         const mppx = Mppx.create({
             methods: [directMethod],
             polyfill: false,
@@ -428,7 +432,7 @@ async function attemptCryptoPayment(challenge, tag, ctx) {
                         },
                     });
                 }
-                return fetchWithTimeout(input, init ?? {}, 30_000);
+                return raw.fetch(input, init);
             },
         });
         try {
@@ -437,18 +441,18 @@ async function attemptCryptoPayment(challenge, tag, ctx) {
                 headers: fetchHeaders,
                 body: fetchBody ?? null,
             });
-            await validatePaymentResponse(results, response, verbose, paymentChain);
+            await validatePaymentResponse(results, response, verbose, paymentChain, true, raw.receipt);
         }
         catch (error) {
             results.push(fail(tag, error.message));
         }
         return;
     }
-    const credential = await createAndSend(challenge, methods, createCredentialFn, tag, results, loaded?.config.extensions, credentialContext);
+    const credential = await createAndSend(challenge, methods, createCredentialFn, tag, results, loaded?.config.extensions, credentialContext, url);
     if (!credential)
         return;
     plugin?.prepareCredentialRequest?.({ challenge, credential, headers: fetchHeaders });
-    await sendAndValidateResponse(results, url, endpoint, credential, fetchHeaders, fetchBody, verbose, paymentChain, Challenge.credentialHeader(challenge));
+    await sendAndValidateResponse(results, url, endpoint, credential, fetchHeaders, fetchBody, verbose, paymentChain, Challenge.credentialHeader(challenge), isTempoSessionChallenge(challenge));
 }
 async function attemptStripePayment(challenge, tag, ctx) {
     const { results, url, endpoint, fetchHeaders, fetchBody, verbose, loaded, options, stripeKey } = ctx;
@@ -511,7 +515,7 @@ async function attemptStripePayment(challenge, tag, ctx) {
     else {
         methods = [directMethod];
     }
-    const credential = await createAndSend(challenge, methods, createCredentialFn, tag, results, loaded?.config.extensions, credentialContext);
+    const credential = await createAndSend(challenge, methods, createCredentialFn, tag, results, loaded?.config.extensions, credentialContext, url);
     if (!credential)
         return;
     plugin?.prepareCredentialRequest?.({ challenge, credential, headers: fetchHeaders });
@@ -532,12 +536,14 @@ async function attemptStripePayment(challenge, tag, ctx) {
     }
     await sendAndValidateResponse(results, url, endpoint, credential, fetchHeaders, fetchBody, verbose, undefined, Challenge.credentialHeader(challenge));
 }
-async function createAndSend(challenge, methods, createCredentialFn, tag, results, extensions, initialCredentialContext) {
+async function createAndSend(challenge, methods, createCredentialFn, tag, results, extensions, initialCredentialContext, url) {
     const fakeResponse = new Response(null, {
         status: 402,
         headers: { [Constants.Headers.wwwAuthenticate]: Challenge.serialize(challenge) },
     });
     try {
+        // The credential goes to url, so only sign a zero-amount proof for a realm its server owns.
+        ProofRealm.assert(challenge, new URL(url), undefined);
         const credentialContext = await preparePayment(challenge, extensions, initialCredentialContext);
         let credential;
         if (createCredentialFn) {
@@ -561,7 +567,7 @@ async function createAndSend(challenge, methods, createCredentialFn, tag, result
         return undefined;
     }
 }
-async function sendAndValidateResponse(results, url, endpoint, credential, baseHeaders, fetchBody, verbose, explorerChain, credentialHeader = Constants.Headers.authorization) {
+async function sendAndValidateResponse(results, url, endpoint, credential, baseHeaders, fetchBody, verbose, explorerChain, credentialHeader = Constants.Headers.authorization, session = false) {
     let paymentResponse;
     try {
         paymentResponse = await fetchWithTimeout(url, {
@@ -574,9 +580,9 @@ async function sendAndValidateResponse(results, url, endpoint, credential, baseH
         results.push(fail('Payment: send credential', error.message));
         return results;
     }
-    return validatePaymentResponse(results, paymentResponse, verbose, explorerChain);
+    return validatePaymentResponse(results, paymentResponse, verbose, explorerChain, session);
 }
-async function validatePaymentResponse(results, paymentResponse, verbose, explorerChain) {
+async function validatePaymentResponse(results, paymentResponse, verbose, explorerChain, session = false, streamReceipt) {
     if (paymentResponse.status === 402) {
         const body = await paymentResponse.text().catch(() => '');
         let detail = 'Payment rejected';
@@ -599,8 +605,22 @@ async function validatePaymentResponse(results, paymentResponse, verbose, explor
         results.push(check('Payment: successful', `HTTP ${paymentResponse.status}`));
     }
     // Validate receipt
+    const contentType = paymentResponse.headers.get('content-type') ?? '';
     const receiptHeader = paymentResponse.headers.get(Constants.Headers.paymentReceipt);
-    if (!receiptHeader) {
+    const stream = !receiptHeader && session && isEventStream(paymentResponse);
+    const body = await paymentResponse.text().catch(() => '');
+    if (stream) {
+        // SSE sessions deliver the receipt as a final payment-receipt event instead of a header.
+        // The session client consumes that event, so it is captured from the server's stream as
+        // the client reads it; a stream read directly is parsed here.
+        const captured = streamReceipt?.();
+        const receipt = captured === undefined ? findReceipt(body) : (captured ?? undefined);
+        if (receipt)
+            results.push(check('Payment receipt in event stream', receipt.reference));
+        else
+            results.push(fail('Payment receipt in event stream', undefined, 'SSE session responses without a Payment-Receipt header must end with an "event: payment-receipt" carrying the session receipt.'));
+    }
+    else if (!receiptHeader) {
         results.push(fail('Payment-Receipt header present', undefined, 'After accepting payment, include a Payment-Receipt header with a base64url-encoded JSON object containing: method, reference, status ("success"), and timestamp (ISO 8601).'));
     }
     else {
@@ -646,8 +666,6 @@ async function validatePaymentResponse(results, paymentResponse, verbose, explor
         }
     }
     // Validate response body
-    const contentType = paymentResponse.headers.get('content-type') ?? '';
-    const body = await paymentResponse.text().catch(() => '');
     if (body.length > 0) {
         results.push(check('Response body non-empty', `${contentType.split(';')[0]}, ${formatBytes(body.length)}`));
     }
@@ -696,4 +714,85 @@ async function validatePaymentResponse(results, paymentResponse, verbose, explor
     }
     return results;
 }
+/** Returns the first session receipt in an event-stream body. */
+function findReceipt(body) {
+    for (const raw of body.replace(/\r\n|\r/g, '\n').split('\n\n')) {
+        const event = parseEvent(raw);
+        if (event?.type === 'payment-receipt')
+            return event.data;
+    }
+    return undefined;
+}
+/** Longest partial event kept while scanning; a receipt event is far smaller. */
+const maxPendingEventBytes = 1024 * 1024;
+/**
+ * Wraps a fetch so in-stream session receipts are seen as the session client reads them: the
+ * client consumes `payment-receipt` events before the caller sees the body. Event-stream
+ * responses without a `Payment-Receipt` header pass through a scanner that keeps only the
+ * current partial event, so nothing is buffered or left unread.
+ */
+/** @internal */
+export function captureEventStream(fetch) {
+    // `undefined`: no stream scanned; `null`: scanned without a receipt.
+    let receipt;
+    return {
+        async fetch(input, init) {
+            const response = await fetch(input, init);
+            if (!response.body ||
+                !isEventStream(response) ||
+                response.headers.has(Constants.Headers.paymentReceipt))
+                return response;
+            // Session management requests (such as mid-stream voucher posts) share this fetch, so a
+            // later stream without a receipt must not discard one already seen.
+            receipt ??= null;
+            const decoder = new TextDecoder();
+            let pending = '';
+            // Set after an oversized event is dropped, until its end, so its remaining lines are
+            // never parsed as an event of their own.
+            let skipping = false;
+            const scan = (text, done) => {
+                pending += text;
+                // Keep a trailing CR: the next chunk may complete a CRLF.
+                const end = done || !pending.endsWith('\r') ? pending.length : pending.length - 1;
+                const events = pending
+                    .slice(0, end)
+                    .replace(/\r\n|\r/g, '\n')
+                    .split('\n\n');
+                const rest = done ? '' : (events.pop() ?? '');
+                if (skipping && (events.length > 0 || done)) {
+                    events.shift();
+                    skipping = false;
+                }
+                pending = rest + pending.slice(end);
+                if (pending.length > maxPendingEventBytes) {
+                    // Keep a trailing line ending: it may be the first half of the event's boundary.
+                    pending = /[\r\n]*$/.exec(pending)?.[0] ?? '';
+                    skipping = true;
+                }
+                for (const raw of events) {
+                    const event = parseEvent(raw);
+                    if (event?.type === 'payment-receipt' && !receipt)
+                        receipt = event.data;
+                }
+            };
+            const body = response.body.pipeThrough(new TransformStream({
+                transform(chunk, controller) {
+                    scan(decoder.decode(chunk, { stream: true }), false);
+                    controller.enqueue(chunk);
+                },
+                flush() {
+                    scan(decoder.decode(), true);
+                },
+            }));
+            const scanned = new Response(body, {
+                headers: response.headers,
+                status: response.status,
+                statusText: response.statusText,
+            });
+            Object.defineProperty(scanned, 'url', { value: response.url });
+            return scanned;
+        },
+        receipt: () => receipt,
+    };
+}
 //# sourceMappingURL=payment.js.map

package/dist/client/Mppx.d.ts

@@ -1,5 +1,5 @@
-import type * as Attestation from '../attestation/Types.js';
 import type * as Challenge from '../Challenge.js';
+import type * as Identity from '../identity/Types.js';
 import * as AcceptPayment from '../internal/AcceptPayment.js';
 import type * as Method from '../Method.js';
 import type * as z from '../zod.js';
@@ -163,8 +163,11 @@ export declare namespace createCredential {
 export declare function restore(): void;
 export declare namespace create {
     type Config<methods extends Methods = Methods, transport extends Transport.AnyTransport = Transport.Transport> = {
-        /** Request-attestation signers applied to every outbound HTTP attempt. */
-        attestation?: transport extends Transport.Transport<RequestInit, Response> ? Attestation.SignerMap | undefined : never;
+        /**
+         * Identity provers applied to every in-scope HTTP attempt, in order.
+         * List request signers last so they cover headers added by earlier provers.
+         */
+        identity?: transport extends Transport.Transport<RequestInit, Response> ? readonly Identity.Prover[] | undefined : never;
         /** Controls when `Accept-Payment` is injected. */
         acceptPaymentPolicy?: Fetch.from.Config['acceptPaymentPolicy'] | undefined;
         /** Custom fetch function to wrap. Defaults to `globalThis.fetch`. */
@@ -185,6 +188,13 @@ export declare namespace create {
         polyfill?: boolean | undefined;
         /** Transport to use (defaults to HTTP). */
         transport?: transport | undefined;
+        /**
+         * Server origins allowed to request zero-amount Tempo proofs for a realm other than their
+         * hostname, mapped to that realm, such as `{ 'https://api.example.com': 'MPP Payment' }`.
+         * With `Transport.mcp()`, which has no origin, only realms listed here are trusted,
+         * whatever their origin.
+         */
+        trustedTempoProofRealms?: Fetch.from.Config['trustedTempoProofRealms'] | undefined;
     };
 }
 /**

package/dist/client/Mppx.js

@@ -1,9 +1,10 @@
-import * as AttestationClient from '../attestation/Client.js';
 import * as Constants from '../Constants.js';
 import * as Expires from '../Expires.js';
+import * as IdentityClient from '../identity/Client.js';
 import * as AcceptPayment from '../internal/AcceptPayment.js';
 import * as Fetch from './internal/Fetch.js';
 import * as MethodChallenge from './internal/MethodChallenge.js';
+import * as ProofRealm from './internal/ProofRealm.js';
 import * as Transport from './Transport.js';
 const preparedPaymentMethods = new WeakMap();
 /**
@@ -28,16 +29,16 @@ const preparedPaymentMethods = new WeakMap();
  * ```
  */
 export function create(config) {
-    const { attestation, maxPaymentRetries, onChallenge, orderChallenges, polyfill = true, acceptPaymentPolicy = polyfill && typeof globalThis.location !== 'undefined'
+    const { identity, maxPaymentRetries, onChallenge, orderChallenges, polyfill = true, acceptPaymentPolicy = polyfill && typeof globalThis.location !== 'undefined'
         ? 'same-origin'
-        : 'always', transport = Transport.http(), } = config;
+        : 'always', transport = Transport.http(), trustedTempoProofRealms, } = config;
+    if ('attestation' in config)
+        throw new TypeError('Mppx client `attestation` was replaced by `identity: [prover]`.');
     const rawFetch = Fetch.unwrapFetch(config.fetch ?? globalThis.fetch);
-    const attestationSigner = attestation
-        ? createAttestationSigner(attestation)
-        : undefined;
-    const attestedFetch = attestationSigner
-        ? AttestationClient.wrapFetch(rawFetch, attestationSigner)
-        : rawFetch;
+    // Rewrapping an mppx fetch keeps its identity provers unless new ones are configured.
+    const identityClient = identity
+        ? IdentityClient.from(identity)
+        : config.fetch && Fetch.identityOf(config.fetch);
     const methods = config.methods.flat();
     const acceptPayment = AcceptPayment.resolve(methods, config.paymentPreferences);
     const events = Fetch.createEventDispatcher();
@@ -45,13 +46,15 @@ export function create(config) {
     const config_fetch = {
         acceptPayment,
         acceptPaymentPolicy,
-        ...((config.fetch || attestation) && { fetch: attestedFetch }),
+        ...(config.fetch && { fetch: rawFetch }),
+        ...(identityClient && { identity: identityClient }),
         eventDispatcher: events,
         ...(maxPaymentRetries !== undefined && { maxPaymentRetries }),
         ...(resolvedOnChallenge && { onChallenge: resolvedOnChallenge }),
         ...(orderChallenges && { orderChallenges }),
         methods,
         transport,
+        ...(trustedTempoProofRealms && { trustedTempoProofRealms }),
     };
     const fetch = Fetch.from(config_fetch);
     if (polyfill)
@@ -88,6 +91,13 @@ export function create(config) {
             mi = selected.method;
             if (challenge.expires)
                 Expires.assert(challenge.expires, challenge.id);
+            const responseUrl = resolveResponseUrl(response);
+            if (responseUrl)
+                ProofRealm.assert(challenge, responseUrl, trustedTempoProofRealms);
+            // The MCP transport has no origin that could own the realm. Custom transports, such as the
+            // CLI's, check the realm against their own target.
+            else if (transport.name === 'mcp')
+                ProofRealm.assertWithoutOrigin(challenge, trustedTempoProofRealms && Object.values(trustedTempoProofRealms));
             const selectedChallenge = challenge;
             const selectedMethod = mi;
             const createPreparedCredential = memoizeCreateCredential(async (context) => {
@@ -156,7 +166,7 @@ export function create(config) {
             init,
             input,
             maxRedirects,
-            signer: attestationSigner,
+            identity: identityClient,
         });
         const requestInit = requestToInit(preparedHttp.replayRequest, preparedHttp.body);
         if (!(await transport.isPaymentRequired(preparedHttp.response, requestInit))) {
@@ -173,13 +183,17 @@ export function create(config) {
             ...paymentOptions,
             request: requestInit,
         }));
+        ProofRealm.assert(payment.challenge, new URL(preparedHttp.replayRequest.url), trustedTempoProofRealms);
         const paymentMethod = preparedPaymentMethods.get(payment) ?? payment.method;
         const createRequestCredential = memoizeCreateCredential(async (context) => {
+            await identityClient?.challenge(preparedHttp.response, { challenge: payment.challenge }, preparedHttp.replayRequest.url);
             if (MethodChallenge.has(paymentMethod))
                 await MethodChallenge.handle(paymentMethod, {
                     challenge: payment.challenge,
                     context,
-                    fetch: attestedFetch,
+                    fetch: identityClient
+                        ? IdentityClient.wrapFetch(rawFetch, identityClient, { challenge: payment.challenge })
+                        : rawFetch,
                     input: preparedHttp.replayRequest,
                     signal: preparedHttp.replayRequest.signal,
                 });
@@ -191,10 +205,16 @@ export function create(config) {
             async pay(context) {
                 const credential = await createRequestCredential(context);
                 const paidInit = payment.setCredential(requestToInit(preparedHttp.replayRequest, preparedHttp.body), credential);
-                return attestedFetch(preparedHttp.replayRequest.url, {
+                const paidRequest = new Request(preparedHttp.replayRequest.url, {
                     ...paidInit,
                     redirect: 'manual',
                 });
+                if (!identityClient)
+                    return rawFetch(paidRequest);
+                const { response } = await identityClient.send(rawFetch, paidRequest, {
+                    challenge: payment.challenge,
+                });
+                return response;
             },
         });
         return Object.freeze({
@@ -239,12 +259,6 @@ export function create(config) {
 export function restore() {
     Fetch.restore();
 }
-function createAttestationSigner(signers) {
-    const values = Object.values(signers);
-    if (values.length === 0)
-        throw new TypeError('Mppx client attestation must configure at least one signer.');
-    return AttestationClient.composeSigners(...values);
-}
 const redirectStatuses = new Set([301, 302, 303, 307, 308]);
 const bodyHeaders = [
     'content-encoding',
@@ -265,7 +279,7 @@ const crossOriginHeaders = [
     'x-payment',
 ];
 async function prepareHttpRequest(parameters) {
-    const { acceptPayment, acceptPaymentPolicy, fetch, init, input, maxRedirects, signer } = parameters;
+    const { acceptPayment, acceptPaymentPolicy, fetch, identity, init, input, maxRedirects } = parameters;
     if (!Number.isInteger(maxRedirects) || maxRedirects < 0)
         throw new TypeError('maxRedirects must be a non-negative integer.');
     let request = new Request(input, { ...init, redirect: 'manual' });
@@ -274,8 +288,13 @@ async function prepareHttpRequest(parameters) {
     const redirects = [];
     for (;;) {
         request = withAcceptPayment(request, acceptPayment, explicitAcceptPayment, acceptPaymentPolicy);
-        const sentRequest = signer ? await signer.sign(request.clone()) : request.clone();
-        const response = await fetch(sentRequest);
+        const { request: sentRequest, response } = await (async () => {
+            // `request` stays unread for replay; the reported request is the one actually sent.
+            if (identity)
+                return identity.send(fetch, request.clone());
+            const sent = request.clone();
+            return { request: sent, response: await fetch(sent) };
+        })();
         if (response.type === 'opaqueredirect' || response.status === 0)
             throw new Error('prepareRequest requires a runtime that exposes manual redirect responses.');
         if (!redirectStatuses.has(response.status))
@@ -459,4 +478,10 @@ async function createCredentialForMethod(challenge, mi, context) {
     const parsedContext = mi.context && context !== undefined ? mi.context.parse(context) : undefined;
     return mi.createCredential(parsedContext !== undefined ? { challenge, context: parsedContext } : { challenge });
 }
+/** Returns the URL of the HTTP server that sent `response`, or `undefined` when it has none. */
+function resolveResponseUrl(response) {
+    if (typeof Response !== 'undefined' && response instanceof Response && response.url)
+        return new URL(response.url);
+    return undefined;
+}
 //# sourceMappingURL=Mppx.js.map

package/dist/client/internal/Fetch.d.ts

@@ -1,9 +1,11 @@
 import * as Challenge from '../../Challenge.js';
+import * as IdentityClient from '../../identity/Client.js';
 import * as AcceptPayment from '../../internal/AcceptPayment.js';
 import type { MaybePromise } from '../../internal/types.js';
 import type * as Method from '../../Method.js';
 import type * as z from '../../zod.js';
 import * as Transport from '../Transport.js';
+import * as ProofRealm from './ProofRealm.js';
 export type ClientEventMap<methods extends readonly Method.AnyClient[] = readonly Method.AnyClient[], response = Response> = {
     'challenge.received': ChallengeReceivedPayload<methods, response>;
     'credential.created': CredentialCreatedPayload<methods, response>;
@@ -95,6 +97,8 @@ export declare namespace from {
         } | undefined;
         /** Custom fetch function to wrap. Defaults to `globalThis.fetch`. */
         fetch?: typeof globalThis.fetch;
+        /** Identity provers applied to every in-scope HTTP attempt. */
+        identity?: IdentityClient.Client | undefined;
         /** Advanced shared event dispatcher. `challenge.received` handlers run before `onChallenge`; the first non-empty credential returned by a handler skips `onChallenge`. */
         eventDispatcher?: ClientEventDispatcher<methods, any> | undefined;
         /** Maximum number of payment challenge retries after the initial response. @default 3 */
@@ -109,6 +113,11 @@ export declare namespace from {
         orderChallenges?: AcceptPayment.OrderChallenges<methods> | undefined;
         /** Transport to use for challenge extraction and credential attachment. */
         transport?: Transport.AnyTransport | undefined;
+        /**
+         * Server origins allowed to request zero-amount Tempo proofs for a realm other than their
+         * hostname, mapped to that realm, such as `{ 'https://api.example.com': 'MPP Payment' }`.
+         */
+        trustedTempoProofRealms?: ProofRealm.TrustedRealms | undefined;
     };
     type Fetch<methods extends readonly Method.AnyClient[] = readonly Method.AnyClient[]> = (input: RequestInfo | URL, init?: RequestInit<methods>) => Promise<Response>;
     type RequestInit<methods extends readonly Method.AnyClient[] = readonly Method.AnyClient[]> = globalThis.RequestInit & {
@@ -168,6 +177,8 @@ export declare function normalizeHeaders(headers: unknown): Record<string, strin
  */
 export declare function createEventDispatcher<methods extends readonly Method.AnyClient[] = readonly Method.AnyClient[], response = Response>(): ClientEventDispatcher<methods, response>;
 /** @internal */
+/** Returns the identity runner of an mppx fetch wrapper, if it has one. @internal */
+export declare function identityOf(fetch: typeof globalThis.fetch): IdentityClient.Client | undefined;
 /** @internal */
 export declare function unwrapFetch(fetch: typeof globalThis.fetch): typeof globalThis.fetch;
 /** @internal */

package/dist/client/internal/Fetch.js

@@ -2,14 +2,18 @@ import * as Challenge from '../../Challenge.js';
 import * as Constants from '../../Constants.js';
 import { PaymentOutcomeUnknownError } from '../../Errors.js';
 import * as Expires from '../../Expires.js';
+import * as IdentityClient from '../../identity/Client.js';
 import * as AcceptPayment from '../../internal/AcceptPayment.js';
 import * as Transport from '../Transport.js';
 import * as MethodChallenge from './MethodChallenge.js';
 import * as MethodResponse from './MethodResponse.js';
+import * as ProofRealm from './ProofRealm.js';
 // We tag wrappers with a global symbol so we can recognize wrappers created by mppx,
 // even across multiple module instances/bundles. This lets restore() avoid clobbering
 // an unrelated fetch installed by user code or another library.
 const MPPX_FETCH_WRAPPER = Symbol.for('mppx.fetch.wrapper');
+/** Identity runner of an mppx fetch wrapper, inherited when that wrapper is wrapped again. */
+const MPPX_FETCH_IDENTITY = Symbol.for('mppx.fetch.identity');
 const defaultMaxPaymentRetries = 3;
 const maxErrorBodyBytes = 64 * 1024;
 const errorBodyTimeoutMs = 2_000;
@@ -101,19 +105,25 @@ async function settleAttempt(prepared, outcome) {
  *
  */
 export function from(config) {
-    const { acceptPayment, acceptPaymentPolicy = 'always', fetch = globalThis.fetch, maxPaymentRetries = defaultMaxPaymentRetries, methods, onChallenge, orderChallenges, transport = Transport.http(), } = config;
+    const { acceptPayment, acceptPaymentPolicy = 'always', fetch = globalThis.fetch, maxPaymentRetries = defaultMaxPaymentRetries, methods, onChallenge, orderChallenges, transport = Transport.http(), trustedTempoProofRealms, } = config;
+    // Rewrapping an mppx fetch keeps its identity provers unless new ones are configured.
+    // Only an explicitly passed mppx fetch hands down its provers; the global fetch never does.
+    const identity = config.identity ?? (config.fetch && identityOf(config.fetch));
     const events = config.eventDispatcher ?? createEventDispatcher();
     const resolvedAcceptPayment = acceptPayment ?? AcceptPayment.resolve(methods);
     // Always operate on the true underlying fetch to avoid wrapper-on-wrapper stacking,
     // which can duplicate retries and make restore semantics fragile.
     const baseFetch = unwrapFetch(fetch);
+    const send = async (input, init, context) => identity
+        ? (await identity.send(baseFetch, new Request(input, init), context)).response
+        : baseFetch(input, init);
     const request = async (input, init, canRefetch) => {
         const callerHeaders = getCallerHeaders(input, init?.headers);
         const hasExplicitAcceptPayment = callerHeaders.has(Constants.Headers.acceptPayment);
         const paymentPreferences = resolvePaymentPreferences(callerHeaders, resolvedAcceptPayment);
         const capturedBody = captureRequestBody(input, init, callerHeaders);
         const initialRequest = prepareInitialRequest(input, init, callerHeaders, paymentPreferences.header, hasExplicitAcceptPayment, acceptPaymentPolicy);
-        let response = await baseFetch(cloneRequestInput(initialRequest.input), initialRequest.init);
+        let response = await send(cloneRequestInput(initialRequest.input), initialRequest.init);
         const transportRequest = withCapturedBody(initialRequest.init, await capturedBody);
         if (!(await transport.isPaymentRequired(response, transportRequest)))
             return response;
@@ -150,7 +160,9 @@ export function from(config) {
                 mi = selected.method;
                 if (challenge.expires)
                     Expires.assert(challenge.expires, challenge.id);
+                await identity?.challenge(response, { challenge: selectedChallenge }, resolveRequestUrl(initialRequest.input).href);
                 const paymentInput = resolvePaymentRetryInput(response, initialRequest.input, initialRequest.input);
+                ProofRealm.assert(selectedChallenge, () => resolveRequestUrl(paymentInput), trustedTempoProofRealms);
                 const previousCredential = preparedCredential;
                 const key = Challenge.serialize(selectedChallenge);
                 const sameAttempt = previousCredential?.method === selected.method && previousCredential?.key === key;
@@ -179,7 +191,12 @@ export function from(config) {
                         prepare: () => MethodChallenge.handle(selected.method, {
                             challenge: selectedChallenge,
                             context: credentialContext,
-                            fetch: baseFetch,
+                            // Management requests (e.g. session top-ups) carry the same identity proofs.
+                            fetch: identity
+                                ? IdentityClient.wrapFetch(baseFetch, identity, {
+                                    challenge: selectedChallenge,
+                                })
+                                : baseFetch,
                             input: paymentInput,
                             signal: resolveRequestSignal(input, init),
                         }),
@@ -232,14 +249,14 @@ export function from(config) {
                     transactionHash: MethodResponse.getTransactionHash(selected.method, credential),
                 });
                 try {
-                    response = await baseFetch(paymentInput, {
+                    response = await send(paymentInput, {
                         ...transport.setCredential({
                             ...fetchInit,
                             headers: initialRequest.headers,
                         }, credential, { challenge: selectedChallenge }),
                         // Runtimes do not strip custom payment headers on cross-origin redirects.
                         redirect: 'manual',
-                    });
+                    }, { challenge: selectedChallenge });
                 }
                 catch (cause) {
                     outcomeUnknown = unknownOutcome(cause);
@@ -347,6 +364,8 @@ export function from(config) {
     };
     const wrappedFetch = (input, init) => request(input, init, true);
     wrappedFetch[MPPX_FETCH_WRAPPER] = baseFetch;
+    if (identity)
+        wrappedFetch[MPPX_FETCH_IDENTITY] = identity;
     return wrappedFetch;
 }
 /**
@@ -380,7 +399,8 @@ export function polyfill(config) {
     globalThis.fetch = from({
         ...config,
         acceptPaymentPolicy: config.acceptPaymentPolicy ?? (isBrowser() ? 'same-origin' : 'always'),
-        fetch: globalThis.fetch,
+        // Unwrapped so a previous polyfill's identity provers are not inherited.
+        fetch: unwrapFetch(globalThis.fetch),
     });
 }
 /**
@@ -586,8 +606,22 @@ function snapshotMethod(method) {
     return freezeSnapshot(Object.assign({}, method));
 }
 function snapshotResponse(response) {
-    if (response instanceof Response)
-        return response.clone();
+    if (response instanceof Response) {
+        try {
+            return response.clone();
+        }
+        catch {
+            // Consumed or locked bodies cannot be cloned; retain isolated status, headers and URL.
+            const snapshot = new Response(null, {
+                headers: response.headers,
+                status: response.status,
+                statusText: response.statusText,
+            });
+            for (const key of ['redirected', 'type', 'url'])
+                Object.defineProperty(snapshot, key, { value: response[key] });
+            return snapshot;
+        }
+    }
     return snapshotValue(response);
 }
 function snapshotValue(value) {
@@ -667,6 +701,10 @@ function getCallerHeaders(input, headers) {
     return new Headers(input instanceof Request ? input.headers : undefined);
 }
 /** @internal */
+/** Returns the identity runner of an mppx fetch wrapper, if it has one. @internal */
+export function identityOf(fetch) {
+    return fetch[MPPX_FETCH_IDENTITY];
+}
 /** @internal */
 export function unwrapFetch(fetch) {
     let current = fetch;