mppx 0.16.0 → 0.17.1

package/dist/cli/sessions/store.js

@@ -33,6 +33,7 @@ export class SessionBusyError extends Error {
     }
 }
 const storedChannelSchema = z.object({
+    origin: z.optional(z.string()),
     channelId: z.hash(),
     cumulativeAmount: z.string(),
     deposit: z.string(),
@@ -183,6 +184,11 @@ export function createSessionRegistry(options = {}) {
         const previous = previousValue === undefined ? undefined : parseStoredSession(previousValue, file);
         if (previous)
             assertSameSession(previous, input, file);
+        const origin = previous?.channel.origin ?? channel.origin;
+        if (previous?.channel.origin && channel.origin && previous.channel.origin !== channel.origin)
+            throw stateError(file, 'Session payment origin mismatch.');
+        if (origin !== undefined && new URL(origin).origin !== origin)
+            throw stateError(file, 'Session payment origin must be a normalized origin.');
         const challenge = parseSessionChallenge(input.challenge, file);
         assertChallengeMatchesChannel(challenge, channel, file);
         const receipt = input.receipt
@@ -193,7 +199,7 @@ export function createSessionRegistry(options = {}) {
         const spent = maxBigInt(input.spent ?? 0n, receipt ? BigInt(receipt.spent) : 0n, previous ? BigInt(previous.spent) : 0n);
         if (spent > cumulativeAmount)
             throw stateError(file, 'Session spend exceeds the locally authorized cumulative amount.');
-        const storedChannel = sanitizeStoredChannel(serializeEntry({ ...channel, cumulativeAmount }), file);
+        const storedChannel = sanitizeStoredChannel(serializeEntry({ ...channel, cumulativeAmount, ...(origin !== undefined && { origin }) }), file);
         const timestamp = monotonicTimestamp(previous?.updatedAt, now(), file);
         const latestReceipt = selectLatestReceipt(previous?.receipt, receipt);
         const account = sanitizeAccount(input.account, file);

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

@@ -37,7 +37,7 @@ export type Counts = {
     skipped: number;
 };
 export declare function printResults(results: CheckResult[], counts: Counts): void;
-/** Fetches the validation target without allowing it to redirect probes elsewhere. */
+/** Fetches a validation target without automatic payments or redirected probes. */
 export declare function fetchWithTimeout(url: RequestInfo | URL, init: RequestInit, timeoutMs?: number): Promise<Response>;
 export declare function formatBytes(bytes: number): string;
 export declare const HTTP_METHODS: Set<string>;

package/dist/cli/validate/helpers.js

@@ -1,3 +1,4 @@
+import { identityOf, skipPayment, unwrapFetch } from '../../client/internal/Fetch.js';
 import { pc } from '../utils.js';
 export function check(label, detail) {
     return detail ? { label, detail, severity: 'pass' } : { label, severity: 'pass' };
@@ -57,12 +58,23 @@ export function printResults(results, counts) {
             counts.skipped++;
     }
 }
-/** Fetches the validation target without allowing it to redirect probes elsewhere. */
+/** Fetches a validation target without automatic payments or redirected probes. */
 export async function fetchWithTimeout(url, init, timeoutMs = 15_000) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
     try {
-        return await fetch(url, { ...init, redirect: 'error', signal: controller.signal });
+        const fetch = globalThis.fetch;
+        const base = unwrapFetch(fetch);
+        const identity = identityOf(fetch);
+        const options = {
+            [skipPayment]: true,
+            ...init,
+            redirect: 'error',
+            signal: controller.signal,
+        };
+        return identity
+            ? (await identity.send((input, init) => base(input, { ...init, [skipPayment]: true }), new Request(url, options))).response
+            : await base(url, options);
     }
     finally {
         clearTimeout(timeout);

package/dist/cli/validate/payment.js

@@ -740,33 +740,57 @@ export function captureEventStream(fetch) {
             const response = await fetch(input, init);
             if (!response.body ||
                 !isEventStream(response) ||
-                response.headers.has(Constants.Headers.paymentReceipt))
+                response.headers.get(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 = '';
+            // Normalized pieces of the current partial event, joined only when the event ends, so a
+            // long event costs linear time. A CR that may start a CRLF is held apart.
+            let parts = [];
+            let size = 0;
+            let heldCr = false;
             // 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)) {
+                let chunk = heldCr ? `\r${text}` : text;
+                heldCr = !done && chunk.endsWith('\r');
+                if (heldCr)
+                    chunk = chunk.slice(0, -1);
+                let rest = chunk.replace(/\r\n|\r/g, '\n');
+                const events = [];
+                // A boundary split across chunks: the partial event ends in a newline and this text starts with one.
+                if (rest.startsWith('\n') && parts.at(-1)?.endsWith('\n')) {
+                    events.push(parts.join('').slice(0, -1));
+                    parts = [];
+                    size = 0;
+                    rest = rest.slice(1);
+                }
+                for (let index = rest.indexOf('\n\n'); index !== -1; index = rest.indexOf('\n\n')) {
+                    events.push(parts.join('') + rest.slice(0, index));
+                    parts = [];
+                    size = 0;
+                    rest = rest.slice(index + 2);
+                }
+                if (rest) {
+                    parts.push(rest);
+                    size += rest.length;
+                }
+                if (done) {
+                    events.push(parts.join(''));
+                    parts = [];
+                    size = 0;
+                }
+                if (skipping && events.length > 0) {
                     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] ?? '';
+                if (size > maxPendingEventBytes) {
+                    // Keep a trailing newline: it may be the first half of the event's boundary.
+                    parts = parts.at(-1)?.endsWith('\n') ? ['\n'] : [];
+                    size = parts.length;
                     skipping = true;
                 }
                 for (const raw of events) {

package/dist/client/Mppx.js

@@ -71,7 +71,10 @@ export function create(config) {
     function onPaymentResponse(handler) {
         return events.on('payment.response', handler);
     }
-    async function preparePayment(response, options) {
+    async function preparePayment(response, options, 
+    // Credential context known before selection, such as an explicit session close passed to
+    // `createCredential`, so methods can accept offers they would otherwise skip.
+    selectionContext) {
         const eventResponse = snapshotResponse(response);
         const challenges = await transport.getChallenges(response, options?.request);
         const challengeSnapshots = Object.freeze(challenges.map((candidate) => snapshotValue(candidate)));
@@ -79,7 +82,12 @@ export function create(config) {
         let challenge;
         let mi;
         try {
-            const candidates = AcceptPayment.selectChallengeCandidates(challenges, methods, preferences);
+            let candidates = AcceptPayment.selectChallengeCandidates(challenges, methods, preferences, selectionContext);
+            // Without a context yet, as in `preparePayment(response).createCredential(context)`, fall back
+            // to offers a method skips only by policy: an explicit close may still use them, and the
+            // method enforces the policy for anything else when the credential is created.
+            if (candidates.length === 0 && selectionContext === undefined)
+                candidates = AcceptPayment.selectChallengeCandidates(challenges, methods, preferences, AcceptPayment.deferredContext);
             const orderedCandidates = await resolveChallengeOrder(candidates, options?.orderChallenges ?? orderChallenges);
             const selected = orderedCandidates[0];
             if (!selected)
@@ -237,7 +245,7 @@ export function create(config) {
         preparePayment,
         prepareRequest: prepareRequest,
         async createCredential(response, context, options) {
-            const prepared = await preparePayment(response, options);
+            const prepared = await preparePayment(response, options, context);
             return prepared.createCredential(context);
         },
     };

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

@@ -6,6 +6,8 @@ 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';
+/** Per-request payment opt-out preserved by forwarding fetch layers. @internal */
+export declare const skipPayment: unique symbol;
 export type ClientEventMap<methods extends readonly Method.AnyClient[] = readonly Method.AnyClient[], response = Response> = {
     'challenge.received': ChallengeReceivedPayload<methods, response>;
     'credential.created': CredentialCreatedPayload<methods, response>;

package/dist/client/internal/Fetch.js

@@ -14,6 +14,8 @@ import * as ProofRealm from './ProofRealm.js';
 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');
+/** Per-request payment opt-out preserved by forwarding fetch layers. @internal */
+export const skipPayment = Symbol.for('mppx.fetch.skipPayment');
 const defaultMaxPaymentRetries = 3;
 const maxErrorBodyBytes = 64 * 1024;
 const errorBodyTimeoutMs = 2_000;
@@ -125,6 +127,8 @@ export function from(config) {
         const initialRequest = prepareInitialRequest(input, init, callerHeaders, paymentPreferences.header, hasExplicitAcceptPayment, acceptPaymentPolicy);
         let response = await send(cloneRequestInput(initialRequest.input), initialRequest.init);
         const transportRequest = withCapturedBody(initialRequest.init, await capturedBody);
+        if (init?.[skipPayment])
+            return response;
         if (!(await transport.isPaymentRequired(response, transportRequest)))
             return response;
         // Only extract context for payment handling after confirming 402.
@@ -139,7 +143,7 @@ export function from(config) {
         try {
             for (let retry = 0; retry < maxPaymentRetries; retry++) {
                 challenges = await transport.getChallenges(response, transportRequest);
-                const candidates = AcceptPayment.selectChallengeCandidates(challenges, methods, paymentPreferences.entries);
+                const candidates = AcceptPayment.selectChallengeCandidates(challenges, methods, paymentPreferences.entries, context);
                 const orderedCandidates = await resolveChallengeOrder(candidates, requestOrderChallenges ??
                     orderChallenges);
                 const selected = orderedCandidates[0];
@@ -161,7 +165,7 @@ export function from(config) {
                 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);
+                const paymentInput = await resolvePaymentRetryInput(response, initialRequest.input, initialRequest.input, fetchInit);
                 ProofRealm.assert(selectedChallenge, () => resolveRequestUrl(paymentInput), trustedTempoProofRealms);
                 const previousCredential = preparedCredential;
                 const key = Challenge.serialize(selectedChallenge);
@@ -184,6 +188,8 @@ export function from(config) {
                         await settleAttempt(previousCredential, { status: 'rejected' });
                         preparedCredential = undefined;
                     }
+                    // A new payment must not start for a request the caller already aborted.
+                    resolveRequestSignal(input, init)?.throwIfAborted();
                     const credentialContext = overrideContext ?? context;
                     if (!MethodChallenge.has(selected.method))
                         return resolveCredential(selectedChallenge, selected.method, credentialContext);
@@ -807,7 +813,21 @@ function resolveRequestUrl(input) {
         return new URL(input.url);
     return new URL(input, isBrowser() ? globalThis.location.href : undefined);
 }
-function resolvePaymentRetryInput(response, fallback, initialInput) {
+/** Rejects Request modes whose paid retry cannot carry a credential to the server. */
+function assertPayableRequest(input, init) {
+    const request = input instanceof Request ? input : undefined;
+    const mode = init.mode ?? request?.mode;
+    // Fetch strips the Authorization header from no-cors requests.
+    if (mode === 'no-cors')
+        throw new Error('Cannot automatically pay a no-cors request: it cannot carry a credential.');
+    const cache = init.cache ?? request?.cache;
+    // A cache-only retry never reaches the server.
+    if (cache === 'only-if-cached')
+        throw new Error('Cannot automatically pay an only-if-cached request: its retry cannot reach the server.');
+}
+/** Retains Request state while targeting the same-origin challenge response URL. */
+async function resolvePaymentRetryInput(response, fallback, initialInput, init) {
+    assertPayableRequest(fallback, init);
     if (!response.url)
         return fallback;
     const responseUrl = new URL(response.url);
@@ -815,6 +835,42 @@ function resolvePaymentRetryInput(response, fallback, initialInput) {
     if (responseUrl.origin !== initialUrl.origin) {
         throw new Error(`Refusing to send payment credential across redirect from ${initialUrl.origin} to ${responseUrl.origin}`);
     }
+    const method = (init.method ?? (fallback instanceof Request ? fallback.method : 'GET')).toUpperCase();
+    // Fetch does not expose the redirect chain, so a non-GET/HEAD request may
+    // have become a GET before reaching the challenge (301/302/303).
+    if (response.redirected && method !== 'GET' && method !== 'HEAD')
+        throw new Error(`Cannot automatically pay a redirected ${method} request. Use prepareRequest() to preserve redirect semantics.`);
+    if (fallback instanceof Request) {
+        // A replacement body makes a consumed or locked original body irrelevant.
+        // Otherwise retain the original body for any later payment challenges.
+        const source = init.body != null ? fallback : fallback.clone();
+        // User-created requests cannot use navigate mode; retry a navigation as same-origin.
+        const request = new Request(source, fallback.mode === 'navigate' && init.mode === undefined
+            ? { ...init, mode: 'same-origin' }
+            : init);
+        // Fetch never sends a URL fragment, and the response URL has none.
+        if (request.url.split('#')[0] === response.url)
+            return request;
+        if (request.body) {
+            // Retargeting would turn the body into a stream without a length (and keepalive rejects
+            // streams). Retarget a buffered copy so the paid retry keeps its Content-Length.
+            return new Request(response.url, {
+                body: await request.arrayBuffer(),
+                cache: request.cache,
+                credentials: request.credentials,
+                headers: request.headers,
+                integrity: request.integrity,
+                keepalive: request.keepalive,
+                method: request.method,
+                mode: request.mode,
+                redirect: request.redirect,
+                referrer: request.referrer,
+                referrerPolicy: request.referrerPolicy,
+                signal: request.signal,
+            });
+        }
+        return new Request(response.url, request);
+    }
     return response.url;
 }
 //# sourceMappingURL=Fetch.js.map

package/dist/client/internal/protocols/Mpp.js

@@ -5,8 +5,11 @@ import { paymentRequiredStatus, setCredentialHeader } from './Shared.js';
 export function mpp() {
     return {
         getChallenges(response) {
+            const header = response.headers.get(Constants.Headers.wwwAuthenticate);
+            // A 402 without a Payment challenge (such as `WWW-Authenticate: X402`) is left to other protocols.
             if (response.status !== paymentRequiredStatus ||
-                !response.headers.has(Constants.Headers.wwwAuthenticate))
+                !header ||
+                !Challenge.hasPaymentScheme(header))
                 return [];
             return Challenge.fromResponseList(response);
         },

package/dist/identity/Client.js

@@ -57,7 +57,7 @@ export function from(provers) {
                     continue;
                 const copy = response.clone();
                 copies.push(copy);
-                if (await prover.retry(copy, context))
+                if (await prover.retry(copy))
                     retry = true;
             }
             if (!retry) {
@@ -69,11 +69,11 @@ export function from(provers) {
         },
         async challenge(response, context, url) {
             for (const prover of inScope(url)) {
-                if (!prover.retry)
+                if (!prover.prepare)
                     continue;
                 const copy = response.clone();
                 try {
-                    await prover.retry(copy, context);
+                    await prover.prepare(copy, context);
                 }
                 finally {
                     release([copy]);

package/dist/identity/Server.d.ts

@@ -35,6 +35,19 @@ export type Outcome = {
  * when several handlers evaluate the same request.
  */
 export declare function verify(request: Request, verifiers: readonly Types.Verifier[], context?: Types.Context): Promise<Outcome>;
+/**
+ * Collects the challenge headers of payment-stage verifiers for one 402.
+ *
+ * Each verifier's hook runs at most once per request and nonce, so every offer
+ * in a composed 402 carries the same challenge. @internal
+ */
+export declare function challenge(request: Request, verifiers: readonly Types.Verifier[], nonce: string): Promise<Headers>;
+/**
+ * Returns the identity nonce for every 402 issued on one request.
+ *
+ * Composed routes call each offer with the same request, so all offers share it. @internal
+ */
+export declare function nonceFor(request: Request, create: () => string): string;
 /** Builds the rejection response for a failed request-stage outcome. @internal */
 export declare function toResponse(outcome: Exclude<Outcome, {
     status: 'valid';

package/dist/identity/Server.js

@@ -90,6 +90,48 @@ export async function verify(request, verifiers, context = {}) {
         reason: missing.reason ?? 'Identity verification is required.',
     };
 }
+/**
+ * Collects the challenge headers of payment-stage verifiers for one 402.
+ *
+ * Each verifier's hook runs at most once per request and nonce, so every offer
+ * in a composed 402 carries the same challenge. @internal
+ */
+export async function challenge(request, verifiers, nonce) {
+    const headers = new Headers();
+    for (const verifier of verifiers) {
+        for (const member of leaves(verifier)) {
+            if (!member.challenge)
+                continue;
+            let byVerifier = challenges.get(request);
+            if (!byVerifier)
+                challenges.set(request, (byVerifier = new Map()));
+            let byNonce = byVerifier.get(member);
+            if (!byNonce)
+                byVerifier.set(member, (byNonce = new Map()));
+            let result = byNonce.get(nonce);
+            if (!result) {
+                result = Promise.resolve(member.challenge(request, { nonce }));
+                byNonce.set(nonce, result);
+            }
+            const init = await result;
+            if (init)
+                for (const [name, value] of new Headers(init))
+                    headers.append(name, value);
+        }
+    }
+    return headers;
+}
+/**
+ * Returns the identity nonce for every 402 issued on one request.
+ *
+ * Composed routes call each offer with the same request, so all offers share it. @internal
+ */
+export function nonceFor(request, create) {
+    let nonce = nonces.get(request);
+    if (!nonce)
+        nonces.set(request, (nonce = create()));
+    return nonce;
+}
 /** Builds the rejection response for a failed request-stage outcome. @internal */
 export function toResponse(outcome) {
     const headers = new Headers(outcome.headers);
@@ -112,6 +154,13 @@ export function stageOf(verifier) {
         throw new TypeError(`Unknown identity verifier stage "${String(stage)}".`);
     return stage;
 }
+/** Returns a verifier and, through `anyOf`, every member it wraps. */
+function leaves(verifier) {
+    const nested = verifier[members];
+    return nested ? nested.flatMap(leaves) : [verifier];
+}
+const nonces = new WeakMap();
+const challenges = new WeakMap();
 const cache = new WeakMap();
 function run(verifier, request, context) {
     let byVerifier = cache.get(request);
@@ -121,7 +170,7 @@ function run(verifier, request, context) {
     if (!byContext)
         byVerifier.set(verifier, (byContext = new Map()));
     // Decisions can depend on the credential, so each credential object gets its own entry.
-    const key = context.challenge?.id ?? '';
+    const key = `${context.challenge?.id ?? ''}|${context.nonce ?? ''}`;
     let byCredential = byContext.get(key);
     if (!byCredential)
         byContext.set(key, (byCredential = new Map()));

package/dist/identity/Types.d.ts

@@ -5,23 +5,34 @@ import type { MaybePromise } from '../internal/types.js';
  * When a verifier runs on the server.
  *
  * `request` verifiers run before any payment challenge is issued and reject
- * the request with their own status code. `payment` verifiers run when a
- * challenge is issued (to add their own challenge headers to the 402) and
- * again on the paid retry, before the credential is settled.
+ * the request with their own status code. `payment` verifiers add their own
+ * challenge headers to the 402 (through `challenge`) and run on the paid
+ * retry, before the credential is settled.
  */
 export type Stage = 'request' | 'payment';
 /**
  * Payment state passed to verifiers and provers.
  *
  * Request-stage verifiers receive an empty context. Payment-stage verifiers
- * receive the challenge being issued, or the challenge and credential being
- * answered on the paid retry.
+ * receive the answered challenge, its credential and the 402's identity nonce.
  */
 export type Context = {
-    /** The MPP challenge being issued or answered. */
+    /** The MPP challenge being answered (or, for provers, selected). */
     challenge?: Challenge.Challenge | undefined;
     /** The payment credential submitted with the request. */
     credential?: Credential.Credential | undefined;
+    /**
+     * The identity nonce of the 402 being answered.
+     *
+     * Every payment offer in one 402 carries the same HMAC-bound nonce, so a proof
+     * bound to it is bound to that 402 whichever offer the client pays.
+     */
+    nonce?: string | undefined;
+};
+/** Context passed to a payment-stage verifier's `challenge` hook. */
+export type ChallengeContext = {
+    /** The identity nonce shared by every payment offer in the 402. Bind the proof request to it. */
+    nonce: string;
 };
 /**
  * The outcome of one identity verifier.
@@ -54,6 +65,12 @@ export type Verification<value = unknown> = {
 export type Verifier<value = unknown> = {
     /** When the verifier runs. @default 'request' */
     stage?: Stage | undefined;
+    /**
+     * Returns the protocol's challenge headers to add to a 402, such as a proof request.
+     *
+     * Payment stage only. Runs once per 402, however many payment offers it carries.
+     */
+    challenge?: ((request: Request, context: ChallengeContext) => MaybePromise<HeadersInit | undefined>) | undefined;
     /** Returns the protocol's verification outcome for the request. */
     verify: (request: Request, context: Context) => MaybePromise<Verification<value>>;
 };
@@ -80,11 +97,16 @@ export type Prover = {
     /** Returns a new request carrying the protocol's identity material. */
     prove: (request: Request, context: ProveContext) => MaybePromise<Request>;
     /**
-     * Inspects a rejected or 402 response and prepares a proof for the next attempt.
+     * Prepares a proof from a 402 before the payment retry, such as answering its proof request.
      *
-     * Return `true` to resend a rejected (non-402) request once. On a 402 the
-     * context carries the selected challenge and the payment retry always follows.
+     * The context carries the selected challenge; `prove` receives the same challenge
+     * on the paid retry.
+     */
+    prepare?: ((response: Response, context: Context) => MaybePromise<void>) | undefined;
+    /**
+     * Inspects a rejected (non-402) response. Return `true` to prove and resend the
+     * request once. Paid attempts are never resent.
      */
-    retry?: ((response: Response, context: Context) => MaybePromise<boolean | undefined>) | undefined;
+    retry?: ((response: Response) => MaybePromise<boolean | undefined>) | undefined;
 };
 //# sourceMappingURL=Types.d.ts.map

package/dist/internal/AcceptPayment.d.ts

@@ -3,10 +3,17 @@ import type { MaybePromise } from './types.js';
 type MethodLike = {
     canHandleChallenge?: ((parameters: {
         challenge: Challenge.Challenge;
+        context?: unknown;
     }) => boolean) | undefined;
     intent: string;
     name: string;
 };
+/**
+ * Selection context for flows that receive the credential context only after an offer is chosen,
+ * such as `preparePayment()`. Methods may accept offers they would otherwise skip by policy and
+ * enforce that policy when the credential is created.
+ */
+export declare const deferredContext: unique symbol;
 /** Supported challenge paired with the configured client method that can sign it. */
 export type ChallengeCandidate<method extends MethodLike = MethodLike> = method extends MethodLike ? {
     challenge: Challenge.Challenge<Record<string, unknown>, method['intent'], method['name']>;
@@ -79,8 +86,11 @@ export declare function selectChallenge<const methods extends readonly MethodLik
     challenge: Challenge.Challenge;
     method: methods[number];
 } | undefined;
-/** Returns supported challenge candidates ordered by client payment preferences. */
-export declare function selectChallengeCandidates<const methods extends readonly MethodLike[]>(challenges: readonly Challenge.Challenge[], methods: methods, preferences: readonly Entry[]): ChallengeCandidate<methods[number]>[];
+/**
+ * Returns supported challenge candidates ordered by client payment preferences.
+ * `context` is the caller's credential context, when known before selection.
+ */
+export declare function selectChallengeCandidates<const methods extends readonly MethodLike[]>(challenges: readonly Challenge.Challenge[], methods: methods, preferences: readonly Entry[], context?: unknown): ChallengeCandidate<methods[number]>[];
 /** Returns the canonical `method/intent` key for a method or challenge-like value. */
 export declare function keyOf(value: {
     intent: string;

package/dist/internal/AcceptPayment.js

@@ -1,4 +1,10 @@
 import * as x402_ChallengeBrand from '../x402/internal/ChallengeBrand.js';
+/**
+ * Selection context for flows that receive the credential context only after an offer is chosen,
+ * such as `preparePayment()`. Methods may accept offers they would otherwise skip by policy and
+ * enforce that policy when the credential is created.
+ */
+export const deferredContext = Symbol('mppx.deferredContext');
 /** Builds the typed key tree used by callback-style preference config. */
 export function buildKeys(methods) {
     const keys = {};
@@ -70,8 +76,11 @@ export function selectChallenge(challenges, methods, preferences) {
         method: candidate.method,
     };
 }
-/** Returns supported challenge candidates ordered by client payment preferences. */
-export function selectChallengeCandidates(challenges, methods, preferences) {
+/**
+ * Returns supported challenge candidates ordered by client payment preferences.
+ * `context` is the caller's credential context, when known before selection.
+ */
+export function selectChallengeCandidates(challenges, methods, preferences, context) {
     const methodsByKey = new Map();
     for (const method of methods) {
         const key = keyOf(method);
@@ -90,7 +99,7 @@ export function selectChallengeCandidates(challenges, methods, preferences) {
         if (!match || match.q <= 0)
             return [];
         return matchingMethods
-            .filter((method) => method.canHandleChallenge?.({ challenge }) ?? true)
+            .filter((method) => method.canHandleChallenge?.(context === undefined ? { challenge } : { challenge, context }) ?? true)
             .map((method) => ({
             challenge,
             index,

package/dist/internal/version.d.ts

@@ -1,5 +1,5 @@
 /** Current mppx package version. */
-export declare const version = "0.16.0";
+export declare const version = "0.17.1";
 /** Canonical SDK identifier for this mppx release. */
-export declare const sdkIdentifier = "mppx/0.16.0";
+export declare const sdkIdentifier = "mppx/0.17.1";
 //# sourceMappingURL=version.d.ts.map

package/dist/internal/version.js

@@ -1,6 +1,6 @@
 // Generated by scripts/sync-version.ts.
 /** Current mppx package version. */
-export const version = '0.16.0';
+export const version = '0.17.1';
 /** Canonical SDK identifier for this mppx release. */
 export const sdkIdentifier = `mppx/${version}`;
 //# sourceMappingURL=version.js.map

package/dist/mcp/client/McpClient.js

@@ -100,7 +100,7 @@ function createPaymentAwareCallTool(callTool, config) {
     const paymentPreferences = AcceptPayment.resolve(methods, config.paymentPreferences);
     const retryWithPayment = async (params, call, paymentRequired, cause, attemptsRemaining = maxPaymentAttempts) => {
         const challenges = paymentRequired.challenges;
-        const candidates = AcceptPayment.selectChallengeCandidates(challenges, methods, paymentPreferences.entries);
+        const candidates = AcceptPayment.selectChallengeCandidates(challenges, methods, paymentPreferences.entries, call.context);
         const orderedCandidates = config.orderChallenges
             ? await config.orderChallenges(candidates)
             : candidates;

package/dist/proxy/Proxy.d.ts

@@ -1,5 +1,8 @@
 import type * as http from 'node:http';
+import * as Replay from './internal/Replay.js';
 import * as Service from './Service.js';
+/** Options for {@link create.Config.replay}. */
+export type ReplayOptions = Replay.Options;
 /** A paid API proxy that gates upstream services behind the mppx 402 protocol. */
 export type Proxy = {
     /** Fetch API handler. Works with Bun, Deno, Next.js, Hono, Elysia, SvelteKit, etc. */
@@ -48,6 +51,18 @@ export declare namespace create {
         fetch?: typeof globalThis.fetch | undefined;
         /** Default handler for failed upstream attempts. Services may override it. */
         onUpstreamError?: Service.UpstreamErrorHandler | undefined;
+        /**
+         * Lets a payer collect a paid response after losing the connection.
+         *
+         * The paid upstream request runs detached from the client (its response must
+         * start within `ttl`), and its outcome is recorded under a key derived from the
+         * credential and the request's method, target and body. A retry with the
+         * same credential and request never pays again: it gets the stored
+         * response, `202` while the delivery runs, or, after a failed delivery, a
+         * new upstream attempt up to `maxAttempts`. Streamed (`text/event-stream`)
+         * and oversized responses are delivered but not stored. Off by default.
+         */
+        replay?: ReplayOptions | undefined;
         /** Services to proxy. Each service is mounted at `/{serviceId}/`. */
         services: Service.Service[];
         /** Human-readable title for the proxy shown in `llms.txt`. */