mppx 0.8.19 → 0.9.1

package/dist/integrations/x402/Negotiator.js

@@ -0,0 +1,165 @@
+import { decodePaymentRequiredHeader } from '@x402/core/http';
+import { getFacilitatorResponseError, x402HTTPResourceServer } from '@x402/core/server';
+import * as Constants from '../../Constants.js';
+import * as Credential from '../../Credential.js';
+import * as SecretKey from '../../server/internal/SecretKey.js';
+import * as Types from '../../x402/Types.js';
+import * as Evm from './Evm.js';
+/** Creates the native MPP side of an x402 compatibility integration. */
+export function create(config) {
+    SecretKey.assert(config.secretKey);
+    const httpServer = new x402HTTPResourceServer(config.server, config.routes);
+    let initialization;
+    async function initialize() {
+        initialization ??= httpServer.initialize().catch((error) => {
+            initialization = undefined;
+            throw error;
+        });
+        await initialization;
+    }
+    async function negotiate(request, context) {
+        if (!httpServer.requiresPayment(context))
+            return { status: 'unprotected' };
+        if (hasMppCredential(request) && getX402Credential(request))
+            return {
+                response: Response.json({ error: 'Send either an MPP credential or an x402 payment signature, not both.' }, { status: 400 }),
+                status: 'handled',
+            };
+        try {
+            await initialize();
+            if (getX402Credential(request))
+                return { status: 'x402' };
+            const result = await httpServer.processHTTPRequest(withoutX402Credential(context), config.paywallConfig);
+            if (result.type === 'no-payment-required')
+                return { status: 'unprotected' };
+            if (result.type !== 'payment-error')
+                throw new Error(`Expected x402 payment response, received ${result.type}.`);
+            const x402Response = responseFromInstructions(result.response);
+            const paymentRequired = getPaymentRequired(result);
+            const handler = paymentRequired
+                ? Evm.createHandler({ config, context, paymentRequired })
+                : undefined;
+            if (!handler)
+                return { response: x402Response, status: 'handled' };
+            const { payment, skipHandlerResponse } = await handler(request);
+            if (payment.status !== 402)
+                return skipHandlerResponse
+                    ? { response: payment.withReceipt(skipHandlerResponse), status: 'handled' }
+                    : { status: 'paid', withReceipt: payment.withReceipt };
+            const response = mergeChallenge(payment.challenge, x402Response);
+            return { response, status: 'handled' };
+        }
+        catch (error) {
+            const facilitatorError = getFacilitatorResponseError(error);
+            if (!facilitatorError)
+                throw error;
+            return {
+                response: Response.json({ error: facilitatorError.message }, { status: 502 }),
+                status: 'handled',
+            };
+        }
+    }
+    return { httpServer, negotiate };
+}
+/** Reads a current or legacy x402 payment credential. */
+export function getX402Credential(request) {
+    return (request.headers.get(Types.paymentSignatureHeader) ??
+        request.headers.get(Types.legacyPaymentSignatureHeader) ??
+        undefined);
+}
+/** Converts a Fetch request to the context consumed by x402 core. */
+export function createContext(request, body) {
+    const paymentHeader = getX402Credential(request);
+    return {
+        adapter: new FetchAdapter(request, body),
+        method: request.method,
+        path: new URL(request.url).pathname,
+        ...(paymentHeader ? { paymentHeader } : {}),
+    };
+}
+function hasMppCredential(request) {
+    const authorization = request.headers.get(Constants.Headers.authorization);
+    return authorization ? Credential.extractPaymentScheme(authorization) !== null : false;
+}
+function withoutX402Credential(context) {
+    const { paymentHeader: _, ...withoutCredential } = context;
+    return withoutCredential;
+}
+function getPaymentRequired(result) {
+    if (result.type !== 'payment-error')
+        return undefined;
+    const target = Types.paymentRequiredHeader.toLowerCase();
+    const encoded = Object.entries(result.response.headers).find(([name]) => name.toLowerCase() === target)?.[1];
+    return encoded ? decodePaymentRequiredHeader(encoded) : undefined;
+}
+function responseFromInstructions(instructions) {
+    const headers = new Headers(instructions.headers);
+    let body = null;
+    if (instructions.body !== undefined) {
+        if (instructions.isHtml || typeof instructions.body === 'string')
+            body = String(instructions.body);
+        else {
+            body = JSON.stringify(instructions.body);
+            if (!headers.has('Content-Type'))
+                headers.set('Content-Type', 'application/json');
+        }
+    }
+    return new Response(body, { headers, status: instructions.status });
+}
+function mergeChallenge(mpp, x402) {
+    const headers = new Headers(x402.headers);
+    const challenge = mpp.headers.get('WWW-Authenticate');
+    if (challenge)
+        headers.append('WWW-Authenticate', challenge);
+    headers.set('Cache-Control', 'no-store');
+    return new Response(x402.body, {
+        headers,
+        status: x402.status,
+        statusText: x402.statusText,
+    });
+}
+/** Fetch implementation used only by the MCP compatibility wrapper. */
+class FetchAdapter {
+    request;
+    body;
+    constructor(request, body) {
+        this.request = request;
+        this.body = body;
+    }
+    getAcceptHeader() {
+        return this.request.headers.get('Accept') ?? '';
+    }
+    getHeader(name) {
+        return this.request.headers.get(name) ?? undefined;
+    }
+    getBody() {
+        return this.body;
+    }
+    getMethod() {
+        return this.request.method;
+    }
+    getPath() {
+        return new URL(this.request.url).pathname;
+    }
+    getQueryParam(name) {
+        const values = new URL(this.request.url).searchParams.getAll(name);
+        if (values.length === 0)
+            return undefined;
+        return values.length === 1 ? values[0] : values;
+    }
+    getQueryParams() {
+        const parameters = {};
+        for (const key of new URL(this.request.url).searchParams.keys()) {
+            const values = new URL(this.request.url).searchParams.getAll(key);
+            parameters[key] = values.length === 1 ? values[0] : values;
+        }
+        return parameters;
+    }
+    getUrl() {
+        return this.request.url;
+    }
+    getUserAgent() {
+        return this.request.headers.get('User-Agent') ?? '';
+    }
+}
+//# sourceMappingURL=Negotiator.js.map

package/dist/mcp/client/McpClient.js

@@ -5,6 +5,7 @@ import * as AcceptPayment from '../../internal/AcceptPayment.js';
 import * as core_Mcp from '../../Mcp.js';
 import * as z from '../../zod.js';
 const MPPX_MCP_CLIENT_WRAPPER = Symbol.for('mppx.mcp.client.wrapper');
+const maxPaymentAttempts = 3;
 /**
  * Adds automatic payment handling to an MCP SDK client.
  *
@@ -80,7 +81,8 @@ export function isPaymentRequiredError(error) {
         return false;
     if (!('code' in error) || !('message' in error))
         return false;
-    if (error.code !== core_Mcp.paymentRequiredCode)
+    const code = error.code;
+    if (code !== core_Mcp.paymentRequiredCode && code !== core_Mcp.paymentVerificationFailedCode)
         return false;
     return isPaymentRequiredData(error.data);
 }
@@ -98,7 +100,7 @@ async function createCredential(challenge, config) {
 function createPaymentAwareCallTool(callTool, config) {
     const methods = config.methods.flat();
     const paymentPreferences = AcceptPayment.resolve(methods, config.paymentPreferences);
-    const retryWithPayment = async (params, call, paymentRequired, cause) => {
+    const retryWithPayment = async (params, call, paymentRequired, cause, attemptsRemaining = maxPaymentAttempts) => {
         const challenges = paymentRequired.challenges;
         const candidates = AcceptPayment.selectChallengeCandidates(challenges, methods, paymentPreferences.entries);
         const orderedCandidates = config.orderChallenges
@@ -122,14 +124,24 @@ function createPaymentAwareCallTool(callTool, config) {
             methods,
         });
         const parsed = Credential.deserialize(credential);
-        const retryResult = await callTool({
-            ...params,
-            _meta: {
-                ...params._meta,
-                [core_Mcp.credentialMetaKey]: parsed,
-            },
-        }, call.resultSchema, call.requestOptions);
-        return withReceipt(retryResult);
+        try {
+            const retryResult = await callTool({
+                ...params,
+                _meta: {
+                    ...params._meta,
+                    [core_Mcp.credentialMetaKey]: parsed,
+                },
+            }, call.resultSchema, call.requestOptions);
+            const nextPaymentRequired = getPaymentRequiredMeta(retryResult);
+            if (nextPaymentRequired && attemptsRemaining > 1)
+                return retryWithPayment(params, call, nextPaymentRequired, retryResult, attemptsRemaining - 1);
+            return withReceipt(retryResult);
+        }
+        catch (error) {
+            if (!isPaymentRequiredError(error) || attemptsRemaining <= 1)
+                throw error;
+            return retryWithPayment(params, call, error.data, error, attemptsRemaining - 1);
+        }
     };
     return async (params, call) => {
         try {

package/dist/mcp/internal/Credential.d.ts

@@ -0,0 +1,9 @@
+import * as Credential from '../../Credential.js';
+/** Parsed MCP credential and its canonical HTTP Authorization value. */
+export type Parsed = {
+    header: string;
+    value: Credential.Credential;
+};
+/** Validates an MCP metadata credential through the canonical wire serializer. */
+export declare function parse(value: unknown): Parsed | undefined;
+//# sourceMappingURL=Credential.d.ts.map

package/dist/mcp/internal/Credential.js

@@ -0,0 +1,16 @@
+import * as Credential from '../../Credential.js';
+/** Validates an MCP metadata credential through the canonical wire serializer. */
+export function parse(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    if (!('challenge' in value) || !('payload' in value))
+        return undefined;
+    try {
+        const header = Credential.serialize(value);
+        return { header, value: Credential.deserialize(header) };
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=Credential.js.map

package/dist/mcp/server/Transport.d.ts

@@ -1,5 +1,5 @@
 import type { CallToolResult, McpError } from '@modelcontextprotocol/sdk/types.js';
-import type * as Credential from '../../Credential.js';
+import * as Credential from '../../Credential.js';
 import * as core_Mcp from '../../Mcp.js';
 import * as Transport from '../../server/Transport.js';
 /**
@@ -18,7 +18,7 @@ export type McpSdk = Transport.Transport<Extra, McpError, CallToolResult>;
  * MCP SDK transport for server-side payment handling with `@modelcontextprotocol/sdk`.
  *
  * - Reads credentials from `_meta["org.paymentauth/credential"]`
- * - Issues challenges as `McpError` with code `-32042` and challenge in `error.data`
+ * - Maps payment errors to their specification-defined JSON-RPC codes
  * - Attaches receipts via `_meta["org.paymentauth/receipt"]` on tool results
  *
  * @example

package/dist/mcp/server/Transport.js

@@ -1,10 +1,12 @@
+import * as Credential from '../../Credential.js';
 import * as core_Mcp from '../../Mcp.js';
 import * as Transport from '../../server/Transport.js';
+import * as McpCredential from '../internal/Credential.js';
 /**
  * MCP SDK transport for server-side payment handling with `@modelcontextprotocol/sdk`.
  *
  * - Reads credentials from `_meta["org.paymentauth/credential"]`
- * - Issues challenges as `McpError` with code `-32042` and challenge in `error.data`
+ * - Maps payment errors to their specification-defined JSON-RPC codes
  * - Attaches receipts via `_meta["org.paymentauth/receipt"]` on tool results
  *
  * @example
@@ -40,10 +42,13 @@ export function mcpSdk() {
             };
         },
         getCredential(extra) {
-            const credential = extra._meta?.[core_Mcp.credentialMetaKey];
-            if (!credential)
+            const value = extra._meta?.[core_Mcp.credentialMetaKey];
+            if (value === undefined)
                 return null;
-            return credential;
+            const parsed = McpCredential.parse(value);
+            if (!parsed)
+                throw new Credential.InvalidCredentialEncodingError();
+            return parsed.value;
         },
         async respondChallenge({ challenge, error }) {
             if (!McpErrorClass) {
@@ -57,8 +62,8 @@ export function mcpSdk() {
                     throw err;
                 }
             }
-            return new McpErrorClass(core_Mcp.paymentRequiredCode, error?.message ?? 'Payment Required', {
-                httpStatus: 402,
+            return new McpErrorClass(core_Mcp.errorCode(error), error?.message ?? 'Payment Required', {
+                httpStatus: error?.status ?? 402,
                 challenges: [challenge],
                 ...(error && { problem: error.toProblemDetails(challenge.id) }),
             });

package/dist/middlewares/express.js

@@ -1,5 +1,6 @@
 import { generate } from '../discovery/OpenApi.js';
 import * as Mppx_core from '../server/Mppx.js';
+import * as ExpressAdapter from './internal/express.js';
 import * as Mppx_internal from './internal/mppx.js';
 export * from '../server/Methods.js';
 export var Mppx;
@@ -48,17 +49,11 @@ export var Mppx;
  */
 export function payment(intent, options) {
     return async (req, res, next) => {
-        const request = new Request(`${req.protocol}://${req.hostname}${req.originalUrl}`, {
-            method: req.method,
-            headers: req.headers,
-        });
+        const request = ExpressAdapter.toRequest(req);
         const result = await intent(options)(request);
         if (result.status === 402) {
             const challenge = result.challenge;
-            res.status(challenge.status);
-            for (const [key, value] of challenge.headers)
-                res.setHeader(key, value);
-            res.send(await challenge.text());
+            await ExpressAdapter.sendResponse(res, challenge);
             return;
         }
         const managementResponse = (() => {
@@ -73,8 +68,7 @@ export function payment(intent, options) {
         })();
         if (managementResponse) {
             res.status(managementResponse.status);
-            for (const [key, value] of managementResponse.headers)
-                res.setHeader(key, value);
+            ExpressAdapter.copyHeaders(res, managementResponse.headers);
             if (managementResponse.body === null) {
                 res.end();
                 return;
@@ -85,8 +79,7 @@ export function payment(intent, options) {
         const originalJson = res.json.bind(res);
         res.json = (body) => {
             const wrapped = result.withReceipt(Response.json(body));
-            for (const [key, value] of wrapped.headers)
-                res.setHeader(key, value);
+            ExpressAdapter.copyHeaders(res, wrapped.headers);
             return originalJson(body);
         };
         next();

package/dist/middlewares/internal/express.d.ts

@@ -0,0 +1,8 @@
+import type { Request as ExpressRequest, Response as ExpressResponse } from 'express';
+/** Copies Fetch response headers to an Express response. */
+export declare function copyHeaders(response: ExpressResponse, headers: Headers): void;
+/** Sends a Fetch response through Express without changing its status, headers, or bytes. */
+export declare function sendResponse(response: ExpressResponse, fetchResponse: Response): Promise<ExpressResponse<any, Record<string, any>>>;
+/** Converts an Express parsed request into the Fetch request consumed by mppx core. */
+export declare function toRequest(request: ExpressRequest): Request;
+//# sourceMappingURL=express.d.ts.map

package/dist/middlewares/internal/express.js

@@ -0,0 +1,24 @@
+import * as NodeRequest from './node.js';
+/** Copies Fetch response headers to an Express response. */
+export function copyHeaders(response, headers) {
+    for (const [name, value] of headers)
+        response.setHeader(name, value);
+}
+/** Sends a Fetch response through Express without changing its status, headers, or bytes. */
+export async function sendResponse(response, fetchResponse) {
+    copyHeaders(response, fetchResponse.headers);
+    response.status(fetchResponse.status);
+    if (fetchResponse.body === null)
+        return response.end();
+    return response.send(Buffer.from(await fetchResponse.arrayBuffer()));
+}
+/** Converts an Express parsed request into the Fetch request consumed by mppx core. */
+export function toRequest(request) {
+    return NodeRequest.toRequest({
+        body: request.body,
+        headers: request.headers,
+        method: request.method,
+        url: `${request.protocol}://${request.get('host')}${request.originalUrl}`,
+    });
+}
+//# sourceMappingURL=express.js.map

package/dist/middlewares/internal/node.d.ts

@@ -0,0 +1,10 @@
+/** Parsed Node framework request fields needed to construct a Fetch request. */
+export type ParsedRequest = {
+    body?: unknown;
+    headers: Record<string, string | string[] | undefined>;
+    method: string;
+    url: string;
+};
+/** Converts a parsed Node framework request into the Fetch request consumed by mppx core. */
+export declare function toRequest(request: ParsedRequest): Request;
+//# sourceMappingURL=node.d.ts.map

package/dist/middlewares/internal/node.js

@@ -0,0 +1,34 @@
+/** Converts a parsed Node framework request into the Fetch request consumed by mppx core. */
+export function toRequest(request) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(request.headers)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value))
+            for (const entry of value)
+                headers.append(name, entry);
+        else
+            headers.set(name, value);
+    }
+    const body = request.method === 'GET' || request.method === 'HEAD' || request.body === undefined
+        ? undefined
+        : toBody(request.body);
+    return new Request(request.url, {
+        ...(body === undefined ? {} : { body }),
+        headers,
+        method: request.method,
+    });
+}
+/** Preserves Fetch-compatible bodies and serializes parsed JSON values. */
+function toBody(body) {
+    if (typeof body === 'string' ||
+        body instanceof ArrayBuffer ||
+        ArrayBuffer.isView(body) ||
+        body instanceof Blob ||
+        body instanceof FormData ||
+        body instanceof URLSearchParams ||
+        body instanceof ReadableStream)
+        return body;
+    return JSON.stringify(body);
+}
+//# sourceMappingURL=node.js.map

package/dist/proxy/Proxy.js

@@ -310,16 +310,22 @@ function withBasePath(basePath, path) {
     return `${trimmed}${path}`;
 }
 function getPaymentBinding(request) {
-    try {
-        const credential = Credential.fromRequest(request);
-        return {
-            intent: credential.challenge.intent,
-            method: credential.challenge.method,
-        };
-    }
-    catch {
-        return null;
+    for (const [, value] of request.headers) {
+        const payment = Credential.extractPaymentScheme(value);
+        if (!payment)
+            continue;
+        try {
+            const credential = Credential.deserialize(payment);
+            return {
+                intent: credential.challenge.intent,
+                method: credential.challenge.method,
+            };
+        }
+        catch {
+            // A malformed payment header is handled by the selected route.
+        }
     }
+    return null;
 }
 function matchesPaymentBinding(endpoint, binding) {
     if (endpoint === true)

package/dist/server/Mppx.d.ts

@@ -99,7 +99,13 @@ export type PaymentSuccessContext<method extends Method.Method = Method.Method,
     input?: Transport.InputOf<transport> | undefined;
     method: ServerMethodDescriptor<method>;
     receipt: Receipt.Receipt;
+    /** Canonical request represented by the challenge. */
     request: z.output<method['schema']['request']>;
+    /**
+     * Resolved method input before request-schema output transforms. Absent during
+     * standalone credential verification when no route options are supplied.
+     */
+    requestInput?: z.input<method['schema']['request']> | undefined;
 }>;
 /** Options for standalone credential verification. */
 export type VerifyCredentialOptions = {
@@ -315,6 +321,8 @@ export declare namespace create {
         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. */
+        requiresAuth?: transport extends Transport.Http ? boolean | undefined : never;
         /** Server realm (e.g., hostname). Resolution order: explicit value > env vars (`MPP_REALM`, `FLY_APP_NAME`, `VERCEL_URL`, etc.) > request URL hostname > `"MPP Payment"`. */
         realm?: string | undefined;
         /** Secret key for HMAC-bound challenge IDs for stateless verification. Must be at least 32 bytes. Auto-detected from `MPP_SECRET_KEY` environment variable. */