mppx 0.17.0 → 0.17.3

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/sse.d.ts

@@ -0,0 +1,21 @@
+/** An event dispatched from a `text/event-stream` body. */
+export type Event = {
+    /** The event's data: its `data` field values joined by `\n`. */
+    data: string;
+    /** The event's type: its last `event` field value, or `'message'` when it has none. */
+    event: string;
+};
+/**
+ * Creates an incremental parser for a `text/event-stream` body, as the WHATWG HTML
+ * spec interprets one. Feed it decoded text chunks split anywhere; it calls `onEvent`
+ * for each event a blank line ends. Lines end in `\n`, `\r\n` or `\r`; comments (`:`),
+ * `id`, `retry` and unknown fields are ignored, and an event that never ends is not
+ * dispatched.
+ *
+ * @see https://html.spec.whatwg.org/multipage/server-sent-events.html#event-stream-interpretation
+ */
+export declare function createParser(onEvent: (event: Event) => void): {
+    /** Parses the next chunk of the stream. */
+    feed(chunk: string): void;
+};
+//# sourceMappingURL=sse.d.ts.map

package/dist/internal/sse.js

@@ -0,0 +1,65 @@
+/**
+ * Creates an incremental parser for a `text/event-stream` body, as the WHATWG HTML
+ * spec interprets one. Feed it decoded text chunks split anywhere; it calls `onEvent`
+ * for each event a blank line ends. Lines end in `\n`, `\r\n` or `\r`; comments (`:`),
+ * `id`, `retry` and unknown fields are ignored, and an event that never ends is not
+ * dispatched.
+ *
+ * @see https://html.spec.whatwg.org/multipage/server-sent-events.html#event-stream-interpretation
+ */
+export function createParser(onEvent) {
+    let buffer = '';
+    let started = false;
+    let skipLineFeed = false;
+    let data;
+    let event = '';
+    function parseLine(line) {
+        if (line === '') {
+            if (data !== undefined)
+                onEvent({ data, event: event || 'message' });
+            data = undefined;
+            event = '';
+            return;
+        }
+        if (line.startsWith(':'))
+            return;
+        const colon = line.indexOf(':');
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? '' : line.slice(colon + 1);
+        if (value.startsWith(' '))
+            value = value.slice(1);
+        if (field === 'data')
+            data = data === undefined ? value : `${data}\n${value}`;
+        else if (field === 'event')
+            event = value;
+    }
+    return {
+        /** Parses the next chunk of the stream. */
+        feed(chunk) {
+            if (!started && chunk) {
+                started = true;
+                if (chunk.startsWith('\uFEFF'))
+                    chunk = chunk.slice(1);
+            }
+            // A `\r` ending the last chunk may be the first half of a `\r\n`.
+            if (skipLineFeed && chunk) {
+                skipLineFeed = false;
+                if (chunk.startsWith('\n'))
+                    chunk = chunk.slice(1);
+            }
+            buffer += chunk;
+            if (!/[\r\n]/.test(chunk))
+                return;
+            let start = 0;
+            const terminator = /\r\n?|\n/g;
+            for (let match = terminator.exec(buffer); match; match = terminator.exec(buffer)) {
+                parseLine(buffer.slice(start, match.index));
+                start = terminator.lastIndex;
+                if (match[0] === '\r' && start === buffer.length)
+                    skipLineFeed = true;
+            }
+            buffer = buffer.slice(start);
+        },
+    };
+}
+//# sourceMappingURL=sse.js.map

package/dist/internal/version.d.ts

@@ -1,5 +1,5 @@
 /** Current mppx package version. */
-export declare const version = "0.17.0";
+export declare const version = "0.17.3";
 /** Canonical SDK identifier for this mppx release. */
-export declare const sdkIdentifier = "mppx/0.17.0";
+export declare const sdkIdentifier = "mppx/0.17.3";
 //# 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.17.0';
+export const version = '0.17.3';
 /** Canonical SDK identifier for this mppx release. */
 export const sdkIdentifier = `mppx/${version}`;
 //# sourceMappingURL=version.js.map

package/dist/mcp/client/McpClient.d.ts

@@ -70,8 +70,8 @@ export declare namespace wrap {
         /** Array of methods to use. Accepts individual clients or tuples (e.g. from `tempo()`). */
         methods: methods;
         /**
-         * Realms allowed to request zero-amount Tempo proofs. An MCP server has no origin that could
-         * own a realm, so these proofs are refused unless their realm is listed here.
+         * Realms allowed to request zero-amount Tempo proofs or session payments. An MCP server has no origin that could
+         * own a realm, so these signatures are refused unless their realm is listed here.
          */
         trustedTempoProofRealms?: readonly string[] | undefined;
     };

package/dist/mcp/client/McpClient.js

@@ -1,5 +1,6 @@
 import * as Challenge from '../../Challenge.js';
 import * as ProofRealm from '../../client/internal/ProofRealm.js';
+import { adapterPaymentMetaKey } from '../../client/internal/protocols/Mcp.js';
 import * as Credential from '../../Credential.js';
 import * as Expires from '../../Expires.js';
 import * as AcceptPayment from '../../internal/AcceptPayment.js';
@@ -57,9 +58,11 @@ export function wrap(client, config) {
         enumerable: false,
         value: (params, resultSchema, options) => {
             const { context, onPaymentRequired, ...requestOptions } = options ?? {};
-            return callTool(params, {
+            return callTool({ ...params, _meta: { ...params._meta, [adapterPaymentMetaKey]: true } }, {
                 context,
-                onPaymentRequired: onPaymentRequired === null ? undefined : (onPaymentRequired ?? config.onPaymentRequired),
+                onPaymentRequired: onPaymentRequired === null
+                    ? undefined
+                    : (onPaymentRequired ?? config.onPaymentRequired),
                 requestOptions: Object.keys(requestOptions).length
                     ? requestOptions
                     : undefined,
@@ -100,7 +103,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. */
@@ -46,8 +49,22 @@ export declare namespace create {
         docs?: Service.Docs | undefined;
         /** Custom `fetch` implementation. Defaults to `globalThis.fetch`. */
         fetch?: typeof globalThis.fetch | undefined;
+        /** Maximum request body bytes on every route, including free routes. Defaults to 10 MiB. */
+        maxRequestBodySize?: number | 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`. */

package/dist/proxy/Proxy.js

@@ -4,6 +4,7 @@ import * as Scope from '../server/internal/scope.js';
 import * as Mppx from '../server/Mppx.js';
 import * as Request from '../server/Request.js';
 import * as Headers from './internal/Headers.js';
+import * as Replay from './internal/Replay.js';
 import * as Route from './internal/Route.js';
 import * as Service from './Service.js';
 /**
@@ -33,7 +34,11 @@ import * as Service from './Service.js';
  * ```
  */
 export function create(config) {
+    const maxRequestBodySize = config.maxRequestBodySize ?? 10 * 1024 * 1024;
+    if (!Number.isSafeInteger(maxRequestBodySize) || maxRequestBodySize < 0)
+        throw new RangeError('maxRequestBodySize must be a non-negative safe integer');
     const fetchImpl = config.fetch ?? globalThis.fetch;
+    const replay = config.replay ? Replay.resolve(config.replay) : undefined;
     const services = new Map(config.services.map((s) => {
         const proxy = createFetchProxy(s.baseUrl, { fetch: fetchImpl });
         return [s.id, { service: s, proxy }];
@@ -98,8 +103,22 @@ export function create(config) {
         if (!matched)
             return new Response('Not Found', { status: 404 });
         const endpoint = matched.value;
-        const ctx = { request, service, upstreamPath };
         const handler = Service.getHandler(endpoint);
+        const declaredLength = Number(request.headers.get('content-length'));
+        if (Number.isFinite(declaredLength) && declaredLength > maxRequestBodySize)
+            return new Response('Payload Too Large', { status: 413 });
+        const paymentCredential = handler
+            ? Replay.credentialOf(request, credentialHeaders(handler))
+            : undefined;
+        let boundedBody;
+        if ((!handler || paymentCredential) && request.body) {
+            const body = await Replay.readBody(request, maxRequestBodySize);
+            if (!body)
+                return new Response('Payload Too Large', { status: 413 });
+            boundedBody = body;
+            request = Replay.withBody(request, body);
+        }
+        const ctx = { request, service, upstreamPath };
         if (!handler)
             return proxyUpstream({
                 request,
@@ -108,13 +127,60 @@ export function create(config) {
                 proxy,
                 onUpstreamError: service.onUpstreamError ?? config.onUpstreamError,
             });
+        // With replay, a paid request whose credential already paid for this exact
+        // request collects its recorded delivery instead of paying again.
+        let paidRequest = request;
+        let replayBody;
+        let replayKey;
+        // Routes with identity verifiers keep paying normally: a replay would skip them.
+        const credential = replay && !fallbackMatch && !requiresIdentity(handler) ? paymentCredential : undefined;
+        if (replay && credential) {
+            const body = boundedBody ??
+                (await Replay.readBody(request, Math.min(maxRequestBodySize, replay.maxRequestBodySize)));
+            if (body && body.length > replay.maxRequestBodySize)
+                return new Response('Payload Too Large', { status: 413 });
+            if (!body)
+                return new Response('Payload Too Large', { status: 413 });
+            replayBody = body;
+            paidRequest = Replay.withBody(request, body);
+            replayKey = Replay.key({
+                body,
+                credential,
+                method: request.method,
+                target: url.origin + url.pathname + url.search,
+            });
+            const found = await Replay.lookup(replay, replayKey);
+            if (found.type === 'respond')
+                return found.response;
+            if (found.type === 'retry') {
+                const options = Service.getOptions(endpoint);
+                return Replay.deliver({
+                    applyReceipt: (response) => Replay.withReceiptHeader(response, found.receipt),
+                    attempts: found.attempts,
+                    replay,
+                    replayKey,
+                    requestHeaders: found.requestHeaders,
+                    run: (signal) => {
+                        // Send the headers of the request that was paid for, not the retry's.
+                        const upstream = Replay.withBody(paidRequest, body, signal, found.requestHeaders);
+                        return proxyUpstream({
+                            request: upstream,
+                            service,
+                            ctx: { ...ctx, request: upstream, ...options },
+                            proxy,
+                            onUpstreamError: service.onUpstreamError ?? config.onUpstreamError,
+                        });
+                    },
+                });
+            }
+        }
         const scope = getConfiguredScope(handler) ??
             deriveRouteScope({
                 basePath: config.basePath,
                 routeKey: matched.key,
                 serviceId,
             });
-        const result = await handler(getConfiguredScope(handler) ? request : Scope.attach(request, scope));
+        const result = await handler(getConfiguredScope(handler) ? paidRequest : Scope.attach(paidRequest, scope));
         if (result.status === 402)
             return result.challenge;
         const managementResponse = (() => {
@@ -131,7 +197,34 @@ export function create(config) {
             return managementResponse;
         if (fallbackMatch)
             return new Response('Method Not Allowed', { status: 405 });
+        if (!boundedBody && !replayBody && request.body) {
+            const body = await Replay.readBody(request, maxRequestBodySize);
+            if (!body)
+                return result.withReceipt(new Response('Payload Too Large', { status: 413 }));
+            request = Replay.withBody(request, body);
+            ctx.request = request;
+        }
         const options = Service.getOptions(endpoint);
+        if (replay && replayKey && replayBody) {
+            const body = replayBody;
+            return Replay.deliver({
+                applyReceipt: (response) => result.withReceipt(response),
+                attempts: 1,
+                replay,
+                replayKey,
+                requestHeaders: [...Headers.scrub(paidRequest.headers).entries()],
+                run: (signal) => {
+                    const upstream = Replay.withBody(paidRequest, body, signal);
+                    return proxyUpstream({
+                        request: upstream,
+                        service,
+                        ctx: { ...ctx, request: upstream, ...options },
+                        proxy,
+                        onUpstreamError: service.onUpstreamError ?? config.onUpstreamError,
+                    });
+                },
+            });
+        }
         const upstreamRes = await proxyUpstream({
             request,
             service,
@@ -143,7 +236,7 @@ export function create(config) {
     }
     return {
         fetch: handle,
-        listener: Request.toNodeListener(handle),
+        listener: Request.toNodeListener(handle, { maxBodySize: maxRequestBodySize }),
     };
 }
 /** @internal */
@@ -284,6 +377,26 @@ function buildDiscoveryRoutes(services) {
         };
     }));
 }
+/** Headers the handler reads Payment credentials from, lowercased (Authorization by default). */
+function credentialHeaders(handler) {
+    const internal = ('_internal' in handler ? handler._internal : undefined);
+    const headers = internal?.offers
+        ? internal.offers.flatMap((offer) => offer.credentialHeaders ?? [])
+        : (internal?.credentialHeaders ?? []);
+    const names = [...new Set(headers.map((header) => header.toLowerCase()))];
+    return names.length > 0 ? names : ['authorization'];
+}
+/** Whether a paid handler, or any offer of a composed one, requires identity verifiers. */
+function requiresIdentity(handler) {
+    if (!('_internal' in handler))
+        return false;
+    const internal = handler._internal;
+    if (!internal)
+        return false;
+    if (internal.offers)
+        return internal.offers.some((offer) => offer._identity);
+    return internal._identity === true;
+}
 function getConfiguredScope(handler) {
     if (!('_internal' in handler))
         return undefined;

package/dist/proxy/internal/Replay.d.ts

@@ -0,0 +1,105 @@
+import type * as Store from '../../Store.js';
+/** Options for replaying paid proxy deliveries. */
+export type Options = {
+    /**
+     * Upstream attempts per credential, including the first, before a retry gets `502`.
+     * A retry after a failed delivery (an upstream error, a 5xx or a body that broke
+     * off) sends the paid request upstream again without charging, so a
+     * non-idempotent upstream may run the operation twice; set `1` to only ever
+     * replay a recorded response. @default 3
+     */
+    maxAttempts?: number | undefined;
+    /** Largest response body, in bytes, kept for replay. Larger or streamed bodies are delivered but not kept. @default 1_048_576 */
+    maxBodySize?: number | undefined;
+    /** Largest request body, in bytes, a paid request may carry; larger ones get `413`. @default 1_048_576 */
+    maxRequestBodySize?: number | undefined;
+    /** `Retry-After` seconds returned while a delivery is still in flight. @default 5 */
+    retryAfter?: number | undefined;
+    /** Atomic store shared by every proxy instance that may receive a retry. */
+    store: Store.AtomicStore;
+    /**
+     * How long to wait for the upstream to start responding, and how long its outcome is kept after it is
+     * recorded, in milliseconds. Expired records are removed when they are next
+     * looked up, as with mppx's replay markers; give the backing store its own
+     * key expiry to reclaim records nobody retries. @default 900_000
+     */
+    ttl?: number | undefined;
+    /** Keeps background work alive after the response returns, such as Cloudflare's `ctx.waitUntil`. */
+    waitUntil?: ((promise: Promise<unknown>) => void) | undefined;
+};
+/** Replay options with defaults applied. */
+export type Resolved = {
+    maxAttempts: number;
+    maxBodySize: number;
+    maxRequestBodySize: number;
+    retryAfter: number;
+    store: Store.AtomicStore;
+    ttl: number;
+    waitUntil: ((promise: Promise<unknown>) => void) | undefined;
+};
+/** A delivery record, keyed by credential and request. */
+export type Record = {
+    attempts: number;
+    expires: number;
+    receipt: string | null;
+    requestHeaders: [string, string][];
+    status: 'pending';
+} | {
+    attempts: number;
+    expires: number;
+    receipt: string | null;
+    requestHeaders: [string, string][];
+    status: 'failed';
+} | {
+    expires: number;
+    status: 'delivered';
+} | {
+    body: string;
+    expires: number;
+    headers: [string, string][];
+    responseStatus: number;
+    status: 'complete';
+    statusText: string;
+};
+/** Applies defaults to replay options. */
+export declare function resolve(options: Options): Resolved;
+/** Returns the request's Payment credential header value, if it carries one. */
+export declare function credentialOf(request: Request, headerNames?: readonly string[]): string | undefined;
+/** Reads a request body, or returns null when it is larger than maxRequestBodySize. */
+export declare function readBody(request: Request, maxRequestBodySize: number): Promise<Uint8Array<ArrayBuffer> | null>;
+/** Derives the replay key from the credential and the exact request (origin, path, query, method, body) it paid for. */
+export declare function key(parameters: {
+    body: Uint8Array;
+    credential: string;
+    method: string;
+    target: string;
+}): string;
+/** Rebuilds a request around an already-read body, optionally with another abort signal. */
+export declare function withBody(request: Request, body: Uint8Array, signal?: AbortSignal, headers?: HeadersInit): Request;
+/** What a request with a known credential should do. */
+export type Lookup = {
+    type: 'none';
+} | {
+    response: Response;
+    type: 'respond';
+} | {
+    attempts: number;
+    receipt: string | null;
+    requestHeaders: [string, string][];
+    type: 'retry';
+};
+/** Looks up a delivery and, for a failed one, claims the next upstream attempt. */
+export declare function lookup(replay: Resolved, replayKey: string): Promise<Lookup>;
+/** Runs a paid upstream delivery detached from the client and records its outcome. */
+export declare function deliver(parameters: {
+    applyReceipt: (response: Response) => Response | Promise<Response>;
+    attempts: number;
+    replay: Resolved;
+    replayKey: string;
+    /** The upstream headers of the paid request; a retried delivery reuses them. */
+    requestHeaders: [string, string][];
+    run: (signal: AbortSignal) => Promise<Response>;
+}): Promise<Response>;
+/** Adds a stored receipt to a response built for a retried delivery. */
+export declare function withReceiptHeader(response: Response, receipt: string | null): Response;
+//# sourceMappingURL=Replay.d.ts.map