mppx 0.15.0 → 0.17.0

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

@@ -69,6 +69,11 @@ export declare namespace wrap {
         paymentPreferences?: AcceptPayment.Config<FlattenMethods<methods>> | undefined;
         /** 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.
+         */
+        trustedTempoProofRealms?: readonly string[] | undefined;
     };
     type McpClient<client extends Pick<Client, 'callTool'> = Pick<Client, 'callTool'>, methods extends Methods = DefaultMethods> = Omit<client, 'callTool'> & {
         /** Call a tool with automatic payment handling. Preserves the MCP SDK signature. */

package/dist/mcp/client/McpClient.js

@@ -1,4 +1,5 @@
 import * as Challenge from '../../Challenge.js';
+import * as ProofRealm from '../../client/internal/ProofRealm.js';
 import * as Credential from '../../Credential.js';
 import * as Expires from '../../Expires.js';
 import * as AcceptPayment from '../../internal/AcceptPayment.js';
@@ -111,6 +112,7 @@ function createPaymentAwareCallTool(callTool, config) {
         }
         if (selected.challenge.expires)
             Expires.assert(selected.challenge.expires, selected.challenge.id);
+        ProofRealm.assertWithoutOrigin(selected.challenge, config.trustedTempoProofRealms);
         if (call.onPaymentRequired) {
             const approved = await call.onPaymentRequired(selected.challenge);
             if (!approved)

package/dist/proxy/Proxy.js

@@ -91,22 +91,23 @@ export function create(config) {
                 // so same-path paid routes can coexist without sharing credentials.
                 Route.matchPath(service.routes, upstreamPath, 
                 // skip free routes (e.g. `'GET /foo/bar': true`)
-                (endpoint) => endpoint !== true && matchesPaymentBinding(endpoint, fallbackBinding))
+                (endpoint) => Service.getHandler(endpoint) !== undefined &&
+                    matchesPaymentBinding(endpoint, fallbackBinding))
             : null;
         const matched = exactMatch ?? fallbackMatch;
         if (!matched)
             return new Response('Not Found', { status: 404 });
         const endpoint = matched.value;
         const ctx = { request, service, upstreamPath };
-        if (endpoint === true)
+        const handler = Service.getHandler(endpoint);
+        if (!handler)
             return proxyUpstream({
                 request,
                 service,
-                ctx,
+                ctx: { ...ctx, ...Service.getOptions(endpoint) },
                 proxy,
                 onUpstreamError: service.onUpstreamError ?? config.onUpstreamError,
             });
-        const handler = typeof endpoint === 'function' ? endpoint : endpoint.pay;
         const scope = getConfiguredScope(handler) ??
             deriveRouteScope({
                 basePath: config.basePath,
@@ -276,6 +277,10 @@ function buildDiscoveryRoutes(services) {
             method: hasMethod ? tokens[0] : 'GET',
             path: `/${service.id}${path}`,
             payment: endpoint ? Service.paymentOf(endpoint) : null,
+            ...(typeof endpoint === 'object' && endpoint?.requestBody
+                ? { requestBody: endpoint.requestBody }
+                : {}),
+            ...(typeof endpoint === 'object' && endpoint?.summary ? { summary: endpoint.summary } : {}),
         };
     }));
 }
@@ -328,7 +333,7 @@ function getPaymentBinding(request) {
     return null;
 }
 function matchesPaymentBinding(endpoint, binding) {
-    if (endpoint === true)
+    if (!Service.getHandler(endpoint))
         return false;
     if (!binding)
         return true;

package/dist/proxy/Service.d.ts

@@ -30,13 +30,45 @@ export type Docs = {
  * An endpoint definition.
  *
  * - `IntentHandler` — payment required, calls the handler to issue a 402 challenge or verify payment.
- * - `{ pay, options }` — payment required with per-endpoint config overrides.
+ * - `EndpointConfig` — `{ pay, options, summary, requestBody }` (paid) or `{ free: true, options, summary, requestBody }` (free).
  * - `true` — free passthrough, no payment required, rewriteRequest is applied.
  */
-export type Endpoint = IntentHandler | {
+export type Endpoint = IntentHandler | EndpointConfig | true;
+/**
+ * An endpoint definition with per-endpoint config overrides and discovery metadata.
+ *
+ * @example
+ * ```ts
+ * routes: {
+ *   'POST /v1/search': {
+ *     pay: mppx.charge({ amount: '0.01' }),
+ *     summary: 'Search the web',
+ *     requestBody: {
+ *       content: { 'application/json': { schema: { type: 'object' } } },
+ *     },
+ *   },
+ *   'GET /v1/status': { free: true, summary: 'Service status' },
+ * }
+ * ```
+ */
+export type EndpointConfig = EndpointMetadata & ({
+    /** Payment handler. */
     pay: IntentHandler;
-    options: EndpointOptions;
-} | true;
+    free?: undefined;
+} | {
+    /** Free passthrough route, declared explicitly so a missing handler never means free. */
+    free: true;
+    pay?: undefined;
+});
+/** Per-endpoint config and discovery metadata shared by paid and free endpoint objects. */
+export type EndpointMetadata = {
+    /** Per-endpoint config overrides passed to request hooks via `ctx`. */
+    options?: EndpointOptions | undefined;
+    /** OpenAPI request body object emitted in `/openapi.json`. */
+    requestBody?: Record<string, unknown> | undefined;
+    /** Short summary emitted in `/openapi.json`. */
+    summary?: string | undefined;
+};
 /** Map of `"METHOD /pattern"` keys to endpoint definitions. */
 export type EndpointMap<routes extends string = string> = Partial<Record<routes, Endpoint>> & Record<string & {}, Endpoint>;
 /** Per-endpoint configuration overrides (e.g. `{ apiKey: 'sk-...' }`). */
@@ -149,6 +181,12 @@ export declare function toLlmsTxt(services: Service[], options?: {
 }): string;
 /** Extracts per-endpoint options from an endpoint definition. */
 export declare function getOptions(endpoint: Endpoint): EndpointOptions | undefined;
+/**
+ * Returns the payment handler of an endpoint, or `undefined` for a route declared free (`true` or
+ * `{ free: true }`). Throws for anything else, such as `{ pay: undefined }`, so a missing handler
+ * fails closed instead of proxying for free with the service's credentials.
+ */
+export declare function getHandler(endpoint: Endpoint): IntentHandler | undefined;
 /** Derives discovery payment metadata from an explicitly priced endpoint handler. */
 export declare function paymentOf(endpoint: Endpoint): Record<string, unknown> | null;
 //# sourceMappingURL=Service.d.ts.map

package/dist/proxy/Service.js

@@ -86,16 +86,32 @@ export function toLlmsTxt(services, options) {
 }
 /** Extracts per-endpoint options from an endpoint definition. */
 export function getOptions(endpoint) {
-    if (typeof endpoint === 'object' && endpoint !== null && 'options' in endpoint)
+    if (typeof endpoint === 'object' && endpoint !== null)
         return endpoint.options;
     return undefined;
 }
+/**
+ * Returns the payment handler of an endpoint, or `undefined` for a route declared free (`true` or
+ * `{ free: true }`). Throws for anything else, such as `{ pay: undefined }`, so a missing handler
+ * fails closed instead of proxying for free with the service's credentials.
+ */
+export function getHandler(endpoint) {
+    if (typeof endpoint === 'function')
+        return endpoint;
+    if (endpoint === true)
+        return undefined;
+    if (typeof endpoint === 'object' && endpoint !== null) {
+        if (typeof endpoint.pay === 'function')
+            return endpoint.pay;
+        if (endpoint.free === true && endpoint.pay === undefined)
+            return undefined;
+    }
+    throw new Error('Invalid proxy endpoint: expected a payment handler, `true` or `{ free: true }`.');
+}
 /** Derives discovery payment metadata from an explicitly priced endpoint handler. */
 export function paymentOf(endpoint) {
-    if (endpoint === true)
-        return null;
-    const handler = typeof endpoint === 'function' ? endpoint : endpoint.pay;
-    if (!('_internal' in handler))
+    const handler = getHandler(endpoint);
+    if (!handler || !('_internal' in handler))
         return null;
     const metadata = handler._internal;
     if (!metadata)

package/dist/server/Mppx.d.ts

@@ -1,8 +1,8 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import type * as Attestation from '../attestation/Types.js';
 import * as Challenge from '../Challenge.js';
 import * as Credential from '../Credential.js';
 import * as Errors from '../Errors.js';
+import type * as Identity from '../identity/Types.js';
 import type { DeepReadonly, MaybePromise } from '../internal/types.js';
 import * as Method from '../Method.js';
 import type * as Receipt from '../Receipt.js';
@@ -277,8 +277,25 @@ type IntentHandlers<methods extends readonly Method.AnyServer[], transport exten
         intent: intent;
     }>, transport>;
 };
+/**
+ * Route identity option. HTTP routes accept identity verifiers, all of which must be valid;
+ * use `Identity.anyOf` to accept one of several protocols. Other transports reject it.
+ */
+type RouteIdentity<transport extends Transport.AnyTransport> = Transport.InputOf<transport> extends Request ? Transport.ChallengeOutputOf<transport> extends Response ? {
+    identity?: readonly Identity.Verifier[] | undefined;
+} : {
+    identity?: never;
+} : {
+    identity?: never;
+};
 /** Handler for an intent with multiple methods - takes the intersection of all methods' options. */
-type MultiMethodFn<methods extends Method.AnyServer, transport extends Transport.AnyTransport> = (options: UnionToIntersection<MultiMethodFnDistribute<methods>>) => (input: Transport.InputOf<transport>) => Promise<MethodFn.Response<transport>>;
+type MultiMethodFn<methods extends Method.AnyServer, transport extends Transport.AnyTransport> = (options: MultiMethodOptions<methods> & RouteIdentity<transport>) => (input: Transport.InputOf<transport>) => Promise<MethodFn.Response<transport>>;
+/**
+ * Intersected options of every method for an intent. When a method's options can't be inferred,
+ * the intersection is `unknown`; fall back to any object (interfaces included) so `RouteIdentity`
+ * doesn't turn it into an object that rejects every option but `identity`.
+ */
+type MultiMethodOptions<methods extends Method.AnyServer> = UnionToIntersection<MultiMethodFnDistribute<methods>> extends infer options ? unknown extends options ? Record<string, any> : options : never;
 type MultiMethodFnDistribute<M> = M extends Method.Server<infer method, infer defaults, any, any, any> ? MethodFn.Options<method, NonNullable<defaults>> : never;
 type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
 /** Nested handlers: `mppx.tempo.charge(...)`, grouped by method name then intent. */
@@ -334,8 +351,6 @@ type ChallengeFn<method extends Method.Method, defaults extends Record<string, u
 export declare function create<const methods extends Methods, const transport extends Transport.AnyTransport = Transport.Http>(config: create.Config<methods, transport>): Mppx<methods, transport>;
 export declare namespace create {
     type Config<methods extends Methods = Methods, transport extends Transport.AnyTransport = Transport.Http> = {
-        /** Request-attestation verifiers required before handling an HTTP payment request. */
-        attestation?: transport extends Transport.Http ? Attestation.VerifierMap | undefined : never;
         /** Array of configured methods. @example [tempo()] */
         methods: methods;
         /** Uses `Payment-Authorization` for Payment credentials so `Authorization` remains available for application authentication. */
@@ -357,7 +372,7 @@ export declare class MissingReceiptResponseError extends Error {
 }
 /** Returns true when an error is the typed `withReceipt()` no-response sentinel. */
 export declare function isMissingReceiptResponseError(error: unknown): error is MissingReceiptResponseError;
-export type MethodFn<method extends Method.Method, transport extends Transport.AnyTransport, defaults extends Record<string, unknown>> = (options: MethodFn.Options<method, defaults>) => (input: Transport.InputOf<transport>) => Promise<MethodFn.Response<transport>>;
+export type MethodFn<method extends Method.Method, transport extends Transport.AnyTransport, defaults extends Record<string, unknown>> = (options: MethodFn.Options<method, defaults> & RouteIdentity<transport>) => (input: Transport.InputOf<transport>) => Promise<MethodFn.Response<transport>>;
 /** @internal */
 export type AnyMethodFn = (options: any) => (input: any) => Promise<any>;
 /** @internal */
@@ -379,6 +394,8 @@ declare namespace MethodFn {
         status: 200;
         /** Canonical challenge resolved from the selected route's terms, when available. */
         challenge?: Challenge.Challenge | undefined;
+        /** Verified identity values for the route's verifiers. */
+        identity?: Identity.Results | undefined;
         withReceipt: Transport.WithReceipt<transport>;
     };
 }
@@ -395,6 +412,8 @@ type ConfiguredHandler<transport extends Transport.AnyTransport = Transport.Http
         scope?: string | undefined;
         _canonicalRequest: Record<string, unknown>;
         _stableBinding?: Method.StableBindingFn<Method.Method> | undefined;
+        /** The offer's payment-stage identity verifiers, if any. */
+        _paymentIdentity?: readonly Identity.Verifier[] | undefined;
         _transport: Transport.AnyTransport;
     };
 };
@@ -409,19 +428,19 @@ type ComposedHandler<transport extends Transport.AnyTransport = Transport.Http>
 type ComposeEntry<methods extends readonly Method.AnyServer[]> = {
     [i in keyof methods]: readonly [
         methods[i],
-        MethodFn.Options<methods[i], NonNullable<methods[i]['defaults']>>
+        MethodFn.Options<methods[i], NonNullable<methods[i]['defaults']>> & RouteIdentity<Transport.Http>
     ];
 }[number] | {
     [i in keyof methods]: readonly [
         `${methods[i]['name']}/${methods[i]['intent']}`,
-        MethodFn.Options<methods[i], NonNullable<methods[i]['defaults']>>
+        MethodFn.Options<methods[i], NonNullable<methods[i]['defaults']>> & RouteIdentity<Transport.Http>
     ];
 }[number] | {
     [i in keyof methods]: readonly [
         MethodFn<methods[i], any, any> & {
             _method: methods[i];
         },
-        MethodFn.Options<methods[i], NonNullable<methods[i]['defaults']>>
+        MethodFn.Options<methods[i], NonNullable<methods[i]['defaults']>> & RouteIdentity<Transport.Http>
     ];
 }[number];
 export declare function compose(...args: readonly unknown[]): ComposedHandler;