mppx 0.12.0 → 0.13.1

package/dist/middlewares/elysia.js

@@ -1,5 +1,7 @@
 import { Elysia } from 'elysia';
+import { mapResponse as mapElysiaResponse } from 'elysia/adapter/web-standard/handler';
 import { generate } from '../discovery/OpenApi.js';
+import * as Scope from '../server/internal/scope.js';
 import * as Mppx_core from '../server/Mppx.js';
 import * as Mppx_internal from './internal/mppx.js';
 export * from '../server/Methods.js';
@@ -7,10 +9,10 @@ export var Mppx;
 (function (Mppx) {
     /**
      * Creates an Elysia-aware payment handler where each intent
-     * returns an Elysia `beforeHandle` hook.
+     * returns Elysia lifecycle hooks.
      *
-     * Use with `.guard()` to scope payment to specific routes,
-     * or `.onBeforeHandle()` to apply globally.
+     * Use with `.guard()` so both verification and response wrapping are scoped
+     * to the same routes.
      *
      * @example
      * ```ts
@@ -21,7 +23,7 @@ export var Mppx;
      *
      * const app = new Elysia()
      *   .guard(
-     *     { beforeHandle: mppx.charge({ amount: '1' }) },
+     *     mppx.charge({ amount: '1' }),
      *     (app) => app.get('/premium', () => ({ data: 'paid content' })),
      *   )
      * ```
@@ -32,7 +34,7 @@ export var Mppx;
     Mppx.create = create;
 })(Mppx || (Mppx = {}));
 /**
- * Elysia `beforeHandle` hook that gates a route behind a payment intent.
+ * Elysia lifecycle hooks that gate a route behind a payment intent.
  *
  * Returns a 402 challenge if no valid credential is provided.
  *
@@ -46,27 +48,78 @@ export var Mppx;
  *
  * const app = new Elysia()
  *   .guard(
- *     { beforeHandle: payment(mppx.charge, { amount: '1' }) },
+ *     payment(mppx.charge, { amount: '1' }),
  *     (app) => app.get('/premium', () => ({ data: 'paid content' })),
  *   )
  * ```
  */
 export function payment(intent, options) {
-    return async ({ request, set }) => {
-        const result = await intent(options)(request);
+    const pending = new WeakMap();
+    const runBeforeHandle = async ({ request, route, set }, legacyRegistration) => {
+        const scopedRequest = options.scope === undefined && Scope.read(options.meta) === undefined
+            ? Scope.attach(request, `${request.method.toUpperCase()} ${route || new URL(request.url).pathname}`)
+            : request;
+        const result = await intent(options)(scopedRequest);
         if (result.status === 402)
             return result.challenge;
-        const managementResponse = getManagementResponse(result);
+        const managementResponse = await getManagementResponse(result);
         if (managementResponse)
             return managementResponse;
-        const receipt = result.withReceipt(new Response());
-        for (const [key, value] of receipt.headers)
-            set.headers[key] = value;
+        const supportsStreamingReceipts = Mppx_core.supportsStreamingReceipts(result);
+        if (legacyRegistration) {
+            if (supportsStreamingReceipts)
+                return new Response('Streaming payment hooks require paired beforeHandle and afterHandle registration.', { status: 500 });
+            const receiptResponse = await result.withReceipt(new Response(null, { status: 204 }));
+            if (!receiptResponse.ok)
+                return receiptResponse;
+            copyHeaders(receiptResponse, set.headers);
+            return undefined;
+        }
+        pending.set(request, { result, supportsStreamingReceipts });
+        return undefined;
+    };
+    const beforeHandle = (context) => runBeforeHandle(context, false);
+    const legacyBeforeHandle = (context) => runBeforeHandle(context, true);
+    const afterHandle = async ({ request, responseValue, set }) => {
+        const entry = pending.get(request);
+        if (!entry)
+            return;
+        const { result, supportsStreamingReceipts } = entry;
+        if (isAsyncIterableResponse(responseValue)) {
+            if (supportsStreamingReceipts) {
+                const response = await result.withReceipt(responseValue);
+                pending.delete(request);
+                return response;
+            }
+            const receiptResponse = await result.withReceipt(new Response(null, { status: 204 }));
+            pending.delete(request);
+            if (!receiptResponse.ok)
+                return receiptResponse;
+            copyHeaders(receiptResponse, set.headers);
+            return responseValue;
+        }
+        const response = await mapElysiaResponse(responseValue, set, request);
+        const wrapped = await result.withReceipt(response);
+        pending.delete(request);
+        return wrapped;
     };
+    return Object.assign(legacyBeforeHandle, { afterHandle, beforeHandle });
+}
+function isAsyncIterableResponse(response) {
+    if (typeof response === 'function')
+        return true;
+    return (typeof response === 'object' &&
+        response !== null &&
+        Symbol.asyncIterator in response &&
+        typeof response[Symbol.asyncIterator] === 'function');
+}
+function copyHeaders(response, headers) {
+    for (const [key, value] of response.headers)
+        headers[key] = value;
 }
-function getManagementResponse(result) {
+async function getManagementResponse(result) {
     try {
-        return result.withReceipt();
+        return await result.withReceipt();
     }
     catch (error) {
         if (Mppx_core.isMissingReceiptResponseError(error)) {

package/dist/middlewares/express.js

@@ -1,4 +1,5 @@
 import { generate } from '../discovery/OpenApi.js';
+import * as Scope from '../server/internal/scope.js';
 import * as Mppx_core from '../server/Mppx.js';
 import * as ExpressAdapter from './internal/express.js';
 import * as Mppx_internal from './internal/mppx.js';
@@ -49,16 +50,20 @@ export var Mppx;
  */
 export function payment(intent, options) {
     return async (req, res, next) => {
-        const request = ExpressAdapter.toRequest(req);
+        const rawRequest = ExpressAdapter.toRequest(req);
+        const routePath = typeof req.route?.path === 'string' ? req.route.path : req.path;
+        const request = options.scope === undefined && Scope.read(options.meta) === undefined
+            ? Scope.attach(rawRequest, `${req.method.toUpperCase()} ${req.baseUrl}${routePath}`)
+            : rawRequest;
         const result = await intent(options)(request);
         if (result.status === 402) {
             const challenge = result.challenge;
             await ExpressAdapter.sendResponse(res, challenge);
             return;
         }
-        const managementResponse = (() => {
+        const managementResponse = await (async () => {
             try {
-                return result.withReceipt();
+                return await result.withReceipt();
             }
             catch (error) {
                 if (Mppx_core.isMissingReceiptResponseError(error))
@@ -78,9 +83,11 @@ export function payment(intent, options) {
         }
         const originalJson = res.json.bind(res);
         res.json = (body) => {
-            const wrapped = result.withReceipt(Response.json(body));
-            ExpressAdapter.copyHeaders(res, wrapped.headers);
-            return originalJson(body);
+            void Promise.resolve(result.withReceipt(Response.json(body))).then((wrapped) => {
+                ExpressAdapter.copyHeaders(res, wrapped.headers);
+                originalJson(body);
+            }, next);
+            return res;
         };
         next();
     };

package/dist/middlewares/hono.js

@@ -55,16 +55,16 @@ export function payment(intent, options) {
         const result = await intent(options)(request);
         if (result.status === 402)
             return result.challenge;
-        const managementResponse = getManagementResponse(result);
+        const managementResponse = await getManagementResponse(result);
         if (managementResponse)
             return managementResponse;
         await next();
-        c.res = result.withReceipt(c.res);
+        c.res = await result.withReceipt(c.res);
     };
 }
-function getManagementResponse(result) {
+async function getManagementResponse(result) {
     try {
-        return result.withReceipt();
+        return await result.withReceipt();
     }
     catch (error) {
         if (Mppx_core.isMissingReceiptResponseError(error)) {

package/dist/middlewares/nextjs.js

@@ -1,4 +1,5 @@
 import { generate } from '../discovery/OpenApi.js';
+import * as Scope from '../server/internal/scope.js';
 import * as Mppx_core from '../server/Mppx.js';
 import * as Mppx_internal from './internal/mppx.js';
 export * from '../server/Methods.js';
@@ -48,19 +49,22 @@ export var Mppx;
  */
 export function payment(intent, options, handler) {
     return async (request) => {
-        const result = await intent(options)(request);
+        const scopedRequest = options.scope === undefined && Scope.read(options.meta) === undefined
+            ? Scope.attach(request, `${request.method.toUpperCase()} ${new URL(request.url).pathname}`)
+            : request;
+        const result = await intent(options)(scopedRequest);
         if (result.status === 402)
             return result.challenge;
-        const managementResponse = getManagementResponse(result);
+        const managementResponse = await getManagementResponse(result);
         if (managementResponse)
             return managementResponse;
         const response = await handler(request);
-        return result.withReceipt(response);
+        return await result.withReceipt(response);
     };
 }
-function getManagementResponse(result) {
+async function getManagementResponse(result) {
     try {
-        return result.withReceipt();
+        return await result.withReceipt();
     }
     catch (error) {
         if (Mppx_core.isMissingReceiptResponseError(error)) {

package/dist/proxy/internal/Headers.js

@@ -12,9 +12,12 @@ const hopByHopHeaders = new Set([
 const paymentHeaders = new Set([
     'accept-payment',
     'authorization',
+    'payment-authorization',
     'payment-receipt',
     'payment-required',
     'payment-response',
+    'payment-session',
+    'payment-session-snapshot',
     'payment-signature',
     'www-authenticate',
 ]);
@@ -57,10 +60,72 @@ export function scrubResponse(response) {
     headers.delete('content-encoding');
     headers.delete('content-length');
     headers.delete('set-cookie');
+    for (const name of paymentHeaders) {
+        if (name !== 'authorization' && name !== 'www-authenticate')
+            headers.delete(name);
+    }
+    headers.delete('payment-authorization');
+    const authorization = headers.get('authorization');
+    if (authorization && /^\s*Payment(?:\s|$)/i.test(authorization))
+        headers.delete('authorization');
+    const authenticate = headers.get('www-authenticate');
+    if (authenticate) {
+        const remaining = removePaymentChallenges(authenticate);
+        if (remaining)
+            headers.set('www-authenticate', remaining);
+        else
+            headers.delete('www-authenticate');
+    }
     return new Response(response.body, {
         status: response.status,
         statusText: response.statusText,
         headers,
     });
 }
+/** Removes Payment authentication challenges while preserving other schemes. */
+function removePaymentChallenges(value) {
+    const starts = [];
+    let inQuotes = false;
+    let escaped = false;
+    for (let index = 0; index < value.length; index++) {
+        const character = value[index];
+        if (inQuotes) {
+            if (escaped)
+                escaped = false;
+            else if (character === '\\')
+                escaped = true;
+            else if (character === '"')
+                inQuotes = false;
+            continue;
+        }
+        if (character === '"') {
+            inQuotes = true;
+            continue;
+        }
+        const previous = value.slice(0, index).trimEnd().at(-1);
+        if (index !== 0 && previous !== ',')
+            continue;
+        const match = value.slice(index).match(/^\s*([!#$%&'*+.^_`|~0-9A-Za-z-]+)(?=\s|,|$)/);
+        if (!match)
+            continue;
+        const start = index + match[0].length - match[0].trimStart().length;
+        const afterScheme = start + match[1].length;
+        let next = afterScheme;
+        while (/\s/.test(value[next] ?? ''))
+            next++;
+        if (value[next] === '=')
+            continue;
+        starts.push({ index: start, scheme: match[1].toLowerCase() });
+        index = afterScheme - 1;
+    }
+    return starts
+        .filter(({ scheme }) => scheme !== 'payment')
+        .map(({ index }) => {
+        const originalPosition = starts.findIndex((start) => start.index === index);
+        const end = starts[originalPosition + 1]?.index ?? value.length;
+        return value.slice(index, end).replace(/,\s*$/, '').trim();
+    })
+        .filter(Boolean)
+        .join(', ');
+}
 //# sourceMappingURL=Headers.js.map

package/dist/proxy/services/stripe.js

@@ -30,6 +30,7 @@ export function stripe(config) {
         rewriteRequest(request, ctx) {
             const apiKey = ctx.apiKey ?? config.apiKey;
             request.headers.delete('Stripe-Account');
+            request.headers.delete('Stripe-Context');
             request.headers.set('Authorization', `Basic ${btoa(`${apiKey}:`)}`);
             return request;
         },

package/dist/server/Mppx.d.ts

@@ -8,8 +8,14 @@ import * as Method from '../Method.js';
 import type * as Receipt from '../Receipt.js';
 import * as z from '../zod.js';
 import * as Html from './internal/html/config.js';
+import * as Request from './Request.js';
 import * as Transport from './Transport.js';
 export type Methods = readonly (Method.AnyServer | readonly Method.AnyServer[])[];
+type ReceiptWrapper = (response?: unknown) => unknown;
+/** Returns whether a successful payment result accepts streaming receipt responses. @internal */
+export declare function supportsStreamingReceipts(result: {
+    withReceipt: ReceiptWrapper;
+}): boolean;
 export type ServerEventMap<methods extends readonly Method.Method[] = readonly Method.Method[], transport extends Transport.AnyTransport = Transport.AnyTransport> = {
     'challenge.created': ChallengeContext<methods[number], transport>;
     'payment.failed': PaymentFailedContext<methods[number], transport>;
@@ -374,10 +380,12 @@ type ConfiguredHandler<transport extends Transport.AnyTransport = Transport.Http
         name: string;
         intent: string;
         html: Html.Options | undefined;
+        credentialHeaders?: readonly string[] | undefined;
         meta?: Record<string, string> | undefined;
         scope?: string | undefined;
         _canonicalRequest: Record<string, unknown>;
         _stableBinding?: Method.StableBindingFn<Method.Method> | undefined;
+        _transport: Transport.AnyTransport;
     };
 };
 type ComposedHandler<transport extends Transport.AnyTransport = Transport.Http> = ((input: Transport.InputOf<transport>) => Promise<MethodFn.Response<transport>>) & {
@@ -413,6 +421,9 @@ export declare function compose(...args: readonly unknown[]): ComposedHandler;
  * On 402: writes the challenge response and ends the connection.
  * On 200: sets the Payment-Receipt header; caller should write response body.
  *
+ * @param handler - Payment handler to adapt.
+ * @param options - Node request conversion and body-size options.
+ *
  * @example
  * ```ts
  * import * as http from 'node:http'
@@ -431,7 +442,8 @@ export declare function compose(...args: readonly unknown[]): ComposedHandler;
  * })
  * ```
  */
-export declare function toNodeListener(handler: (input: globalThis.Request) => Promise<MethodFn.Response<Transport.Http>>): (req: IncomingMessage, res: ServerResponse) => Promise<MethodFn.Response<Transport.Http>>;
+export declare function toNodeListener(handler: (input: globalThis.Request) => Promise<MethodFn.Response<Transport.Http>>, options?: Request.NodeConversionOptions | undefined): (req: IncomingMessage, res: ServerResponse) => Promise<MethodFn.Response<Transport.Http>>;
+export declare function toNodeListener(handler: (input: globalThis.Request) => Promise<MethodFn.Response<Transport.Sse>>, options?: Request.NodeConversionOptions | undefined): (req: IncomingMessage, res: ServerResponse) => Promise<MethodFn.Response<Transport.Sse>>;
 /**
  * Flattens a methods config tuple, preserving positional types.
  * @internal

package/dist/server/Mppx.js

@@ -19,6 +19,11 @@ import * as SecretKey from './internal/SecretKey.js';
 import * as NodeListener from './NodeListener.js';
 import * as Request from './Request.js';
 import * as Transport from './Transport.js';
+const streamingReceiptWrappers = new WeakSet();
+/** Returns whether a successful payment result accepts streaming receipt responses. @internal */
+export function supportsStreamingReceipts(result) {
+    return streamingReceiptWrappers.has(result.withReceipt);
+}
 const reservedMppxKeyValues = [
     'challenge',
     'compose',
@@ -306,6 +311,7 @@ export function create(config) {
         return prepared.method.validate({
             credential: prepared.parsedCredential,
             envelope: prepared.envelope,
+            operation: 'validate',
             request: prepared.request,
         });
     }
@@ -327,7 +333,12 @@ export function create(config) {
         let receipt;
         try {
             if (mi.broadcast && mi.validate)
-                await mi.validate({ credential: parsedCredential, envelope, request });
+                await mi.validate({
+                    credential: parsedCredential,
+                    envelope,
+                    operation: 'broadcast',
+                    request,
+                });
             const broadcast = mi.broadcast ?? mi.verify;
             receipt = await broadcast({ credential: parsedCredential, envelope, request });
         }
@@ -429,8 +440,15 @@ function createMethodFn(parameters) {
             name: method.name,
             intent: method.intent,
             html: method.html,
+            credentialHeaders: [
+                ...new Set([
+                    credentialHeader ?? Constants.Headers.authorization,
+                    ...(transport.credentialHeaders ?? []),
+                ]),
+            ],
             _canonicalRequest: PaymentRequest.fromMethod(method, { ...defaults, ...rest }),
             _stableBinding: stableBinding,
+            _transport: transport,
         };
         Object.defineProperty(internal, '_method', { value: method });
         const handler = async (input) => {
@@ -608,7 +626,7 @@ function createMethodFn(parameters) {
             }
             const success = (receiptData, options = {}) => {
                 const { challengeId = challenge.id, credentialForReceipt = { challenge, payload: {} }, envelopeForReceipt, managementResponse, } = options;
-                return {
+                const result = {
                     status: 200,
                     withReceipt(response) {
                         if (managementResponse) {
@@ -633,6 +651,9 @@ function createMethodFn(parameters) {
                         });
                     },
                 };
+                if (transport.supportsStreamingReceipts)
+                    streamingReceiptWrappers.add(result.withReceipt);
+                return result;
             };
             // No credential provided—issue challenge
             if (!credential) {
@@ -644,15 +665,6 @@ function createMethodFn(parameters) {
                             request: challenge.request,
                         });
                         if (authorized) {
-                            await events.emit('payment.success', createPaymentSuccessContext({
-                                capturedRequest,
-                                challenge,
-                                input,
-                                method,
-                                receipt: authorized.receipt,
-                                request: parsedRequest,
-                                requestInput: request,
-                            }), method);
                             return success(authorized.receipt, {
                                 managementResponse: authorized.response,
                             });
@@ -823,7 +835,12 @@ function createMethodFn(parameters) {
             let receiptData;
             try {
                 if (broadcast && validate)
-                    await validate({ credential: parsedCredential, envelope, request });
+                    await validate({
+                        credential: parsedCredential,
+                        envelope,
+                        operation: 'broadcast',
+                        request,
+                    });
                 const broadcastCredential = broadcast ?? verify;
                 receiptData = await broadcastCredential({
                     credential: parsedCredential,
@@ -1555,7 +1572,10 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
         // Try to extract a Payment credential to decide whether to dispatch or challenge.
         // Only gate on the Payment scheme — other auth schemes (Bearer, Basic, etc.)
         // should fall through to the merged-402 path so all offers are presented.
-        const paymentHeader = Array.from(input.headers.values())
+        const credentialHeaders = new Set(handlers.flatMap((handler) => getConfiguredOffers(handler).flatMap((internal) => internal.credentialHeaders ?? [])));
+        const paymentHeader = Array.from(credentialHeaders)
+            .map((header) => input.headers.get(header))
+            .filter((value) => value !== null)
             .map((value) => Credential.extractPaymentScheme(value))
             .find((value) => value !== null);
         if (paymentHeader) {
@@ -1594,6 +1614,24 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
             // Unrecognized or malformed credentials still use the currently eligible
             // offer set before the first handler issues its rejection challenge.
         }
+        const transportResults = new Map();
+        for (const handler of handlers) {
+            for (const internal of getConfiguredOffers(handler)) {
+                const matchCredential = internal._transport.matchCredential;
+                if (!matchCredential)
+                    continue;
+                try {
+                    if (await matchCredential({ input, request: internal._canonicalRequest })) {
+                        const result = await handler(input);
+                        transportResults.set(handler, result);
+                        if (result.status === 200)
+                            return result;
+                        break;
+                    }
+                }
+                catch { }
+            }
+        }
         const selectedHandlers = hasOfferPolicy
             ? await selectOfferHandlers({
                 entries: offerEntries,
@@ -1601,11 +1639,19 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
                 selectOffers: offerSelector,
             })
             : handlers;
+        const transportCredentialHandler = selectedHandlers.find((handler) => getConfiguredOffers(handler).some((internal) => internal.credentialHeaders?.some((header) => {
+            const value = input.headers.get(header);
+            return (header.toLowerCase() !== Constants.Headers.authorization.toLowerCase() &&
+                value !== null &&
+                Credential.extractPaymentScheme(value) === null);
+        })));
+        if (transportCredentialHandler)
+            return transportCredentialHandler(input);
         // No credential — evaluate handlers sequentially so authorize()/renewal hooks
         // can safely claim the request without racing each other.
         const results = [];
         for (const handler of selectedHandlers) {
-            const result = await handler(input);
+            const result = transportResults.get(handler) ?? (await handler(input));
             if (result.status === 200)
                 return result;
             if (result.challenge.status !== 402)
@@ -1920,52 +1966,47 @@ function mergeX402PaymentRequiredHeaders(values) {
         }),
     ];
 }
-/**
- * Wraps a payment handler to create a Node.js HTTP listener.
- *
- * On 402: writes the challenge response and ends the connection.
- * On 200: sets the Payment-Receipt header; caller should write response body.
- *
- * @example
- * ```ts
- * import * as http from 'node:http'
- * import { Mppx } from 'mppx/server'
- *
- * const payment = Mppx.create({ ... })
- *
- * http.createServer(async (req, res) => {
- *   const result = await Mppx.toNodeListener(
- *     payment.charge({
- *       amount: '1', currency: '...', recipient: '0x...',
- *     }),
- *   )(req, res)
- *   if (result.status === 402) return
- *   res.end('OK')
- * })
- * ```
- */
-export function toNodeListener(handler) {
+export function toNodeListener(handler, options) {
     return async (req, res) => {
-        const result = await handler(Request.fromNodeListener(req, res));
+        let result;
+        try {
+            const request = Request.fromNodeListener(req, res, options);
+            await Request.waitForBody(request);
+            result = await handler(request);
+        }
+        catch (error) {
+            if (!(error instanceof Request.RequestBodyTooLargeError))
+                throw error;
+            const response = new globalThis.Response('Payload Too Large', {
+                status: 413,
+                headers: { 'Content-Type': 'text/plain' },
+            });
+            await NodeListener.sendResponse(res, response);
+            return { challenge: response, status: 402 };
+        }
         if (result.status === 402) {
             await NodeListener.sendResponse(res, result.challenge);
         }
         else {
-            const managementResponse = getManagementResponse(result);
+            const managementResponse = await getManagementResponse(result);
             if (managementResponse) {
                 await NodeListener.sendResponse(res, managementResponse);
                 return { challenge: managementResponse, status: 402 };
             }
-            const wrapped = result.withReceipt(new globalThis.Response());
+            const wrapped = await result.withReceipt(new globalThis.Response(null, { status: 204 }));
+            if (wrapped.status === 402) {
+                await NodeListener.sendResponse(res, wrapped);
+                return { challenge: wrapped, status: 402 };
+            }
             for (const [name, value] of wrapped.headers)
                 res.setHeader(name, value);
         }
         return result;
     };
 }
-function getManagementResponse(result) {
+async function getManagementResponse(result) {
     try {
-        return result.withReceipt();
+        return await result.withReceipt();
     }
     catch (error) {
         if (isMissingReceiptResponseError(error)) {