mppx 0.6.19 → 0.6.21

package/dist/server/Mppx.js

@@ -6,12 +6,27 @@ import * as Expires from '../Expires.js';
 import * as AcceptPayment from '../internal/AcceptPayment.js';
 import * as Env from '../internal/env.js';
 import * as PaymentRequest from '../PaymentRequest.js';
+import * as z from '../zod.js';
 import * as Html from './internal/html/config.js';
 import { serviceWorker } from './internal/html/serviceWorker.gen.js';
 import * as Scope from './internal/scope.js';
 import * as NodeListener from './NodeListener.js';
 import * as Request from './Request.js';
 import * as Transport from './Transport.js';
+const reservedMppxKeyValues = [
+    'challenge',
+    'compose',
+    'methods',
+    'on',
+    'onChallengeCreated',
+    'onPaymentFailed',
+    'onPaymentSuccess',
+    'realm',
+    'transport',
+    'verifyCredential',
+];
+/** Public instance keys that payment method names and shorthand intents cannot shadow. */
+export const reservedMppxKeys = new Set(reservedMppxKeyValues);
 /**
  * Creates a server-side payment handler from methods.
  *
@@ -34,17 +49,24 @@ export function create(config) {
         throw new Error('Missing secret key. Set the MPP_SECRET_KEY environment variable or pass `secretKey` to Mppx.create().');
     }
     const methods = config.methods.flat();
+    const serverEvents = createServerEventDispatcher();
     const handlers = {};
     const intentCount = {};
     for (const mi of methods) {
         intentCount[mi.intent] = (intentCount[mi.intent] ?? 0) + 1;
+    }
+    assertNoReservedMppxKeys(methods);
+    for (const mi of methods) {
         handlers[`${mi.name}/${mi.intent}`] = createMethodFn({
+            authorize: mi.authorize,
             defaults: mi.defaults,
             method: mi,
             realm,
+            events: serverEvents,
             request: mi.request,
             respond: mi.respond,
             secretKey,
+            stableBinding: mi.stableBinding,
             transport: (mi.transport ?? transport),
             verify: mi.verify,
         });
@@ -78,30 +100,94 @@ export function create(config) {
     // verifyCredential: single-call end-to-end verification
     async function verifyCredentialFn(input, options) {
         const credential = hydrateCredentialMeta(typeof input === 'string' ? Credential.deserialize(input) : input);
-        // HMAC provenance check (secretKey is guaranteed non-null by the guard at the top of create())
-        if (!Challenge.verify(credential.challenge, { secretKey: secretKey }))
-            throw new Errors.InvalidChallengeError({
-                id: credential.challenge.id,
-                reason: 'challenge was not issued by this server',
-            });
-        // Expiry check
-        Expires.assert(credential.challenge.expires, credential.challenge.id);
         // Find matching method by name + intent
         const { method: credMethod, intent: credIntent } = credential.challenge;
         const mi = methods.find((m) => m.name === credMethod && m.intent === credIntent);
-        if (!mi)
-            throw new Errors.InvalidChallengeError({
+        const eventMethod = mi ?? { intent: credIntent, name: credMethod };
+        const emitStandalonePaymentFailed = async (parameters) => {
+            await serverEvents.emit('payment.failed', createPaymentFailedContext({
+                capturedRequest: options?.capturedRequest,
+                challenge: parameters.challenge,
+                credential: parameters.credential,
+                error: parameters.error,
+                method: eventMethod,
+                request: parameters.request,
+                submittedChallenge: parameters.submittedChallenge,
+            }));
+        };
+        if (!mi) {
+            const error = new Errors.InvalidChallengeError({
                 id: credential.challenge.id,
                 reason: `no registered method for ${credMethod}/${credIntent}`,
             });
+            await emitStandalonePaymentFailed({
+                challenge: credential.challenge,
+                credential,
+                error,
+                request: credential.challenge.request,
+                submittedChallenge: credential.challenge,
+            });
+            throw error;
+        }
+        // HMAC provenance check (secretKey is guaranteed non-null by the guard at the top of create())
+        if (!Challenge.verify(credential.challenge, { secretKey: secretKey })) {
+            const error = new Errors.InvalidChallengeError({
+                id: credential.challenge.id,
+                reason: 'challenge was not issued by this server',
+            });
+            await emitStandalonePaymentFailed({
+                challenge: credential.challenge,
+                credential,
+                error,
+                request: credential.challenge.request,
+                submittedChallenge: credential.challenge,
+            });
+            throw error;
+        }
+        // Expiry check
+        try {
+            Expires.assert(credential.challenge.expires, credential.challenge.id);
+        }
+        catch (e) {
+            if (e instanceof Errors.PaymentError)
+                await emitStandalonePaymentFailed({
+                    challenge: credential.challenge,
+                    credential,
+                    error: e,
+                    request: credential.challenge.request,
+                    submittedChallenge: credential.challenge,
+                });
+            throw e;
+        }
         // Validate payload against method schema
-        mi.schema.credential.payload.parse(credential.payload);
+        let parsedCredential;
+        try {
+            parsedCredential = withParsedCredentialPayload(credential, mi.schema.credential.payload.parse(credential.payload));
+        }
+        catch (e) {
+            await emitStandalonePaymentFailed({
+                challenge: credential.challenge,
+                credential,
+                error: new Errors.InvalidPayloadError(),
+                request: credential.challenge.request,
+                submittedChallenge: credential.challenge,
+            });
+            throw e;
+        }
         const expectedMeta = Scope.merge({ meta: options?.meta, scope: options?.scope });
         if (options?.scope !== undefined && Scope.read(credential.challenge.meta) !== options.scope) {
-            throw new Errors.InvalidChallengeError({
+            const error = new Errors.InvalidChallengeError({
                 id: credential.challenge.id,
                 reason: "credential scope does not match this route's requirements",
             });
+            await emitStandalonePaymentFailed({
+                challenge: credential.challenge,
+                credential: parsedCredential,
+                error,
+                request: credential.challenge.request,
+                submittedChallenge: credential.challenge,
+            });
+            throw error;
         }
         const shouldValidateRoute = options?.capturedRequest !== undefined ||
             options?.meta !== undefined ||
@@ -110,37 +196,77 @@ export function create(config) {
         const expectedRealm = options?.realm ??
             realm ??
             (options?.capturedRequest === undefined ? credential.challenge.realm : undefined);
-        const request = shouldValidateRoute
-            ? await resolveRouteChallenge({
-                capturedRequest: options?.capturedRequest,
-                credential,
-                defaults: mi.defaults,
-                expires: credential.challenge.expires,
-                meta: expectedMeta,
-                method: mi,
-                realm: expectedRealm,
-                request: mi.request,
-                routeRequest: options?.request ?? {},
-                secretKey: secretKey,
-            }).then((resolved) => {
-                const mismatch = getPinnedChallengeMismatch(resolved.challenge, credential.challenge);
-                if (mismatch)
-                    throw new Errors.InvalidChallengeError({
-                        id: credential.challenge.id,
-                        reason: `credential ${mismatch} does not match this route's requirements`,
-                    });
-                return resolved.request;
-            })
-            : credential.challenge.request;
+        let parsedRequest = credential.challenge.request;
+        let request;
+        try {
+            request = shouldValidateRoute
+                ? await resolveRouteChallenge({
+                    capturedRequest: options?.capturedRequest,
+                    credential: parsedCredential,
+                    defaults: mi.defaults,
+                    expires: credential.challenge.expires,
+                    meta: expectedMeta,
+                    method: mi,
+                    realm: expectedRealm,
+                    request: mi.request,
+                    routeRequest: options?.request ?? {},
+                    secretKey: secretKey,
+                }).then((resolved) => {
+                    const mismatch = getChallengeBindingMismatch(resolved.challenge, credential.challenge, mi.stableBinding);
+                    if (mismatch)
+                        throw new Errors.InvalidChallengeError({
+                            id: credential.challenge.id,
+                            reason: `credential ${mismatch} does not match this route's requirements`,
+                        });
+                    parsedRequest = resolved.parsedRequest;
+                    return resolved.request;
+                })
+                : credential.challenge.request;
+        }
+        catch (e) {
+            if (e instanceof Errors.PaymentError)
+                await emitStandalonePaymentFailed({
+                    challenge: credential.challenge,
+                    credential: parsedCredential,
+                    error: e,
+                    request: credential.challenge.request,
+                    submittedChallenge: credential.challenge,
+                });
+            throw e;
+        }
         const envelope = options?.capturedRequest
             ? {
                 capturedRequest: options.capturedRequest,
                 challenge: credential.challenge,
-                credential,
-                request,
+                credential: parsedCredential,
+                request: parsedRequest,
             }
             : undefined;
-        return mi.verify({ credential, envelope, request });
+        let receipt;
+        try {
+            receipt = await mi.verify({ credential: parsedCredential, envelope, request });
+        }
+        catch (e) {
+            const error = e instanceof Errors.PaymentError ? e : new Errors.VerificationFailedError();
+            await emitStandalonePaymentFailed({
+                challenge: credential.challenge,
+                credential: parsedCredential,
+                error,
+                request: parsedRequest,
+                submittedChallenge: credential.challenge,
+            });
+            throw e;
+        }
+        await serverEvents.emit('payment.success', createPaymentSuccessContext({
+            capturedRequest: options?.capturedRequest,
+            challenge: credential.challenge,
+            credential: parsedCredential,
+            envelope,
+            method: mi,
+            receipt,
+            request: parsedRequest,
+        }));
+        return receipt;
     }
     function composeFn(...entries) {
         if (transport.name !== 'http')
@@ -160,10 +286,23 @@ export function create(config) {
         });
         return compose(...configured);
     }
+    function onChallengeCreated(handler) {
+        return serverEvents.on('challenge.created', handler);
+    }
+    function onPaymentFailed(handler) {
+        return serverEvents.on('payment.failed', handler);
+    }
+    function onPaymentSuccess(handler) {
+        return serverEvents.on('payment.success', handler);
+    }
     return {
         methods,
         challenge: challengeHandlers,
         compose: composeFn,
+        on: serverEvents.on,
+        onChallengeCreated,
+        onPaymentFailed,
+        onPaymentSuccess,
         realm: realm,
         transport,
         verifyCredential: verifyCredentialFn,
@@ -172,12 +311,19 @@ export function create(config) {
 }
 // biome-ignore lint/correctness/noUnusedVariables: _
 function createMethodFn(parameters) {
-    const { defaults, method, realm, respond, secretKey, transport, verify } = parameters;
+    const { authorize, defaults, events, method, realm, respond, secretKey, stableBinding, transport, verify, } = parameters;
     return (options) => {
         const { description, meta, scope, ...rest } = options;
         const staticMeta = Scope.merge({ meta, scope });
         return Object.assign(async (input) => {
-            const expires = 'expires' in options ? options.expires : Expires.minutes(5);
+            if (method.html && isServiceWorkerRequest(input))
+                return {
+                    status: 402,
+                    challenge: createServiceWorkerResponse(),
+                };
+            const expires = 'expires' in options
+                ? normalizeExpires(options.expires)
+                : Expires.minutes(5);
             const capturedRequest = await captureRequest(transport, input);
             const effectiveMeta = scope === undefined && input instanceof globalThis.Request
                 ? Scope.merge({ meta: staticMeta, scope: Scope.get(input) })
@@ -192,7 +338,39 @@ function createMethodFn(parameters) {
                     return [null, e];
                 }
             })();
-            const { challenge, request } = await resolveRouteChallenge({
+            const emitChallenge = async (parameters) => {
+                const response = await transport.respondChallenge({
+                    challenge: parameters.challenge,
+                    input,
+                    ...(parameters.error && { error: parameters.error }),
+                    ...(parameters.html && { html: parameters.html }),
+                });
+                if (isIssuedChallengeResponse(response))
+                    await events.emit('challenge.created', createChallengeContext({
+                        capturedRequest,
+                        challenge: parameters.challenge,
+                        credential: parameters.credential,
+                        error: parameters.error,
+                        input,
+                        method,
+                        request: parameters.request,
+                    }));
+                return response;
+            };
+            const emitPaymentFailed = async (parameters) => {
+                await events.emit('payment.failed', createPaymentFailedContext({
+                    capturedRequest,
+                    challenge: parameters.challenge,
+                    credential: parameters.credential,
+                    error: parameters.error,
+                    input,
+                    method,
+                    request: parameters.request,
+                    retryChallenge: parameters.retryChallenge,
+                    submittedChallenge: parameters.submittedChallenge,
+                }));
+            };
+            const routeChallenge = await resolveRouteChallenge({
                 capturedRequest,
                 credential,
                 defaults,
@@ -204,24 +382,138 @@ function createMethodFn(parameters) {
                 request: parameters.request,
                 routeRequest: rest,
                 secretKey,
+            }).catch(async (e) => {
+                if (!(e instanceof Errors.PaymentError))
+                    throw e;
+                const challenge = createFallbackChallenge({
+                    capturedRequest,
+                    defaults: defaults ?? {},
+                    description,
+                    expires,
+                    meta: effectiveMeta,
+                    method,
+                    realm,
+                    routeRequest: rest,
+                    secretKey,
+                });
+                if (credential)
+                    await emitPaymentFailed({
+                        challenge,
+                        credential,
+                        error: e,
+                        request: challenge.request,
+                        retryChallenge: challenge,
+                        submittedChallenge: credential.challenge,
+                    });
+                const response = await emitChallenge({
+                    challenge,
+                    credential,
+                    request: challenge.request,
+                    error: e,
+                    html: method.html,
+                });
+                return { response };
             });
+            if ('response' in routeChallenge)
+                return { challenge: routeChallenge.response, status: 402 };
+            const { challenge, parsedRequest, request } = routeChallenge;
             // Credential was provided but malformed
             if (credentialError) {
                 const reason = getSafeCredentialReason(credentialError);
-                const response = await transport.respondChallenge({
+                const error = new Errors.MalformedCredentialError(reason ? { reason } : {});
+                await emitPaymentFailed({
                     challenge,
-                    input,
-                    error: new Errors.MalformedCredentialError(reason ? { reason } : {}),
+                    credential: null,
+                    error,
+                    request: parsedRequest,
+                    retryChallenge: challenge,
+                });
+                const response = await emitChallenge({
+                    challenge,
+                    credential: null,
+                    request: parsedRequest,
+                    error,
                     html: method.html,
                 });
                 return { challenge: response, status: 402 };
             }
+            const success = (receiptData, options = {}) => {
+                const { challengeId = challenge.id, credentialForReceipt = { challenge, payload: {} }, envelopeForReceipt, managementResponse, } = options;
+                return {
+                    status: 200,
+                    withReceipt(response) {
+                        if (managementResponse) {
+                            return transport.respondReceipt({
+                                challengeId,
+                                credential: credentialForReceipt,
+                                ...(envelopeForReceipt ? { envelope: envelopeForReceipt } : {}),
+                                input,
+                                receipt: receiptData,
+                                response: managementResponse,
+                            });
+                        }
+                        if (!response)
+                            throw new MissingReceiptResponseError();
+                        return transport.respondReceipt({
+                            challengeId,
+                            credential: credentialForReceipt,
+                            ...(envelopeForReceipt ? { envelope: envelopeForReceipt } : {}),
+                            input,
+                            receipt: receiptData,
+                            response: response,
+                        });
+                    },
+                };
+            };
             // No credential provided—issue challenge
             if (!credential) {
-                const response = await transport.respondChallenge({
+                if (authorize && input instanceof globalThis.Request) {
+                    try {
+                        const authorized = await authorize({
+                            challenge,
+                            input,
+                            request: challenge.request,
+                        });
+                        if (authorized) {
+                            await events.emit('payment.success', createPaymentSuccessContext({
+                                capturedRequest,
+                                challenge,
+                                input,
+                                method,
+                                receipt: authorized.receipt,
+                                request: parsedRequest,
+                            }));
+                            return success(authorized.receipt, {
+                                managementResponse: authorized.response,
+                            });
+                        }
+                    }
+                    catch (e) {
+                        if (!(e instanceof Errors.PaymentError))
+                            console.error('mppx: internal authorization error', e);
+                        const error = e instanceof Errors.PaymentError ? e : new Errors.VerificationFailedError();
+                        await emitPaymentFailed({
+                            challenge,
+                            credential: null,
+                            error,
+                            request: parsedRequest,
+                            retryChallenge: challenge,
+                        });
+                        const response = await emitChallenge({
+                            challenge,
+                            request: parsedRequest,
+                            error,
+                            html: method.html,
+                        });
+                        return { challenge: response, status: 402 };
+                    }
+                }
+                const error = new Errors.PaymentRequiredError({ description });
+                const response = await emitChallenge({
                     challenge,
-                    input,
-                    error: new Errors.PaymentRequiredError({ description }),
+                    credential: null,
+                    request: parsedRequest,
+                    error,
                     html: method.html,
                 });
                 return { challenge: response, status: 402 };
@@ -238,13 +530,23 @@ function createMethodFn(parameters) {
             // (https://paymentauth.org/draft-httpauth-payment-00.html#section-5.1.2.1.1).
             // No database lookup is needed; the HMAC is stateless verification.
             if (!Challenge.verify(credential.challenge, { secretKey })) {
-                const response = await transport.respondChallenge({
+                const error = new Errors.InvalidChallengeError({
+                    id: credential.challenge.id,
+                    reason: 'challenge was not issued by this server',
+                });
+                await emitPaymentFailed({
                     challenge,
-                    input,
-                    error: new Errors.InvalidChallengeError({
-                        id: credential.challenge.id,
-                        reason: 'challenge was not issued by this server',
-                    }),
+                    credential,
+                    error,
+                    request: parsedRequest,
+                    retryChallenge: challenge,
+                    submittedChallenge: credential.challenge,
+                });
+                const response = await emitChallenge({
+                    challenge,
+                    credential,
+                    request: parsedRequest,
+                    error,
                     html: method.html,
                 });
                 return { challenge: response, status: 402 };
@@ -272,15 +574,25 @@ function createMethodFn(parameters) {
             // `expires` still is not pinned here because its default is generated
             // per invocation, and `digest` is already bound by the echoed HMAC.
             {
-                const mismatch = getPinnedChallengeMismatch(challenge, credential.challenge);
+                const mismatch = getChallengeBindingMismatch(challenge, credential.challenge, stableBinding);
                 if (mismatch) {
-                    const response = await transport.respondChallenge({
+                    const error = new Errors.InvalidChallengeError({
+                        id: credential.challenge.id,
+                        reason: `credential ${mismatch} does not match this route's requirements`,
+                    });
+                    await emitPaymentFailed({
                         challenge,
-                        input,
-                        error: new Errors.InvalidChallengeError({
-                            id: credential.challenge.id,
-                            reason: `credential ${mismatch} does not match this route's requirements`,
-                        }),
+                        credential,
+                        error,
+                        request: parsedRequest,
+                        retryChallenge: challenge,
+                        submittedChallenge: credential.challenge,
+                    });
+                    const response = await emitChallenge({
+                        challenge,
+                        credential,
+                        request: parsedRequest,
+                        error,
                         html: method.html,
                     });
                     return { challenge: response, status: 402 };
@@ -291,44 +603,73 @@ function createMethodFn(parameters) {
                 Expires.assert(credential.challenge.expires, credential.challenge.id);
             }
             catch (error) {
-                const response = await transport.respondChallenge({
+                await emitPaymentFailed({
                     challenge,
-                    input,
+                    credential,
+                    error: error,
+                    request: parsedRequest,
+                    retryChallenge: challenge,
+                    submittedChallenge: credential.challenge,
+                });
+                const response = await emitChallenge({
+                    challenge,
+                    credential,
+                    request: parsedRequest,
                     error: error,
                 });
                 return { challenge: response, status: 402 };
             }
             // Validate payload structure against method schema
+            let parsedCredential;
             try {
-                method.schema.credential.payload.parse(credential.payload);
+                parsedCredential = withParsedCredentialPayload(credential, method.schema.credential.payload.parse(credential.payload));
             }
             catch {
-                const response = await transport.respondChallenge({
+                const error = new Errors.InvalidPayloadError();
+                await emitPaymentFailed({
                     challenge,
-                    input,
-                    error: new Errors.InvalidPayloadError(),
+                    credential,
+                    error,
+                    request: parsedRequest,
+                    retryChallenge: challenge,
+                    submittedChallenge: credential.challenge,
+                });
+                const response = await emitChallenge({
+                    challenge,
+                    credential,
+                    request: parsedRequest,
+                    error,
                 });
                 return { challenge: response, status: 402 };
             }
             const envelope = Object.freeze({
                 capturedRequest,
                 challenge: credential.challenge,
-                credential,
-                request,
+                credential: parsedCredential,
+                request: parsedRequest,
             });
             // User-provided verification (e.g., check signature, submit tx, verify payment).
             // If verification fails, re-issue the challenge so the client can retry.
             let receiptData;
             try {
-                receiptData = await verify({ credential, envelope, request });
+                receiptData = await verify({ credential: parsedCredential, envelope, request });
             }
             catch (e) {
                 if (!(e instanceof Errors.PaymentError))
                     console.error('mppx: internal verification error', e);
                 const error = e instanceof Errors.PaymentError ? e : new Errors.VerificationFailedError();
-                const response = await transport.respondChallenge({
+                await emitPaymentFailed({
                     challenge,
-                    input,
+                    credential: parsedCredential,
+                    error,
+                    request: parsedRequest,
+                    retryChallenge: challenge,
+                    submittedChallenge: credential.challenge,
+                });
+                const response = await emitChallenge({
+                    challenge,
+                    credential: parsedCredential,
+                    request: parsedRequest,
                     error,
                 });
                 return { challenge: response, status: 402 };
@@ -339,33 +680,30 @@ function createMethodFn(parameters) {
             // return the management response directly. If undefined, `withReceipt()`
             // expects the caller to pass the user handler's response instead.
             const managementResponse = respond
-                ? await respond({ credential, envelope, input, receipt: receiptData, request })
+                ? await respond({
+                    credential: parsedCredential,
+                    envelope,
+                    input,
+                    receipt: receiptData,
+                    request,
+                })
                 : undefined;
-            return {
-                status: 200,
-                withReceipt(response) {
-                    if (managementResponse) {
-                        return transport.respondReceipt({
-                            challengeId: credential.challenge.id,
-                            credential,
-                            envelope,
-                            input,
-                            receipt: receiptData,
-                            response: managementResponse,
-                        });
-                    }
-                    if (!response)
-                        throw new Error('withReceipt() requires a response argument');
-                    return transport.respondReceipt({
-                        challengeId: credential.challenge.id,
-                        credential,
-                        envelope,
-                        input,
-                        receipt: receiptData,
-                        response: response,
-                    });
-                },
-            };
+            await events.emit('payment.success', createPaymentSuccessContext({
+                capturedRequest,
+                challenge: credential.challenge,
+                credential: parsedCredential,
+                envelope,
+                input,
+                method,
+                receipt: receiptData,
+                request: parsedRequest,
+            }));
+            return success(receiptData, {
+                challengeId: credential.challenge.id,
+                credentialForReceipt: parsedCredential,
+                envelopeForReceipt: envelope,
+                managementResponse,
+            });
         }, {
             _internal: {
                 ...method,
@@ -375,6 +713,7 @@ function createMethodFn(parameters) {
                 name: method.name,
                 intent: method.intent,
                 _canonicalRequest: PaymentRequest.fromMethod(method, { ...defaults, ...rest }),
+                _stableBinding: stableBinding,
             },
         });
     };
@@ -389,7 +728,9 @@ function createChallengeFn(parameters) {
     return async (options) => {
         const { description, meta, scope, ...rest } = options;
         const effectiveMeta = Scope.merge({ meta, scope });
-        const expires = 'expires' in options ? options.expires : Expires.minutes(5);
+        const expires = 'expires' in options
+            ? normalizeExpires(options.expires)
+            : Expires.minutes(5);
         return resolveRouteChallenge({
             defaults,
             description,
@@ -403,6 +744,197 @@ function createChallengeFn(parameters) {
         }).then((resolved) => resolved.challenge);
     };
 }
+function createServerEventDispatcher() {
+    const handlers = {
+        '*': new Set(),
+        'challenge.created': new Set(),
+        'payment.failed': new Set(),
+        'payment.success': new Set(),
+    };
+    const on = (name, handler) => {
+        switch (name) {
+            case '*':
+            case 'challenge.created':
+            case 'payment.failed':
+            case 'payment.success':
+                handlers[name].add(handler);
+                return () => handlers[name].delete(handler);
+            default:
+                throw new Error(`Unknown server event "${String(name)}".`);
+        }
+    };
+    return {
+        async emit(name, context) {
+            await emitServerEventHandlers(handlers[name], context);
+            await emitServerEventHandlers(handlers['*'], toServerEventEnvelope(name, context));
+        },
+        on,
+    };
+}
+function toServerEventEnvelope(name, payload) {
+    return Object.freeze({ name, payload });
+}
+async function emitServerEventHandlers(handlers, context) {
+    for (const handler of handlers) {
+        try {
+            await handler(context);
+        }
+        catch {
+            // Errors are isolated, but handlers are still awaited inline.
+        }
+    }
+}
+function assertNoReservedMppxKeys(methods) {
+    for (const method of methods) {
+        if (reservedMppxKeys.has(method.name))
+            throw new Error(`Method name "${method.name}" conflicts with a reserved Mppx property.`);
+        if (reservedMppxKeys.has(method.intent))
+            throw new Error(`Method intent "${method.intent}" conflicts with a reserved Mppx property.`);
+    }
+}
+function createChallengeContext(parameters) {
+    return Object.freeze({
+        ...(parameters.capturedRequest
+            ? { capturedRequest: snapshotCapturedRequest(parameters.capturedRequest) }
+            : {}),
+        challenge: snapshotValue(parameters.challenge),
+        credential: parameters.credential === undefined
+            ? undefined
+            : snapshotNullableValue(parameters.credential),
+        error: snapshotError(parameters.error),
+        ...snapshotInputProperty(parameters.input),
+        method: snapshotMethod(parameters.method),
+        request: snapshotValue(parameters.request),
+    });
+}
+function createPaymentFailedContext(parameters) {
+    return Object.freeze({
+        ...(parameters.capturedRequest
+            ? { capturedRequest: snapshotCapturedRequest(parameters.capturedRequest) }
+            : {}),
+        challenge: snapshotValue(parameters.challenge),
+        credential: snapshotNullableValue(parameters.credential),
+        error: snapshotError(parameters.error),
+        ...snapshotInputProperty(parameters.input),
+        method: snapshotMethod(parameters.method),
+        request: snapshotValue(parameters.request),
+        ...(parameters.retryChallenge
+            ? { retryChallenge: snapshotValue(parameters.retryChallenge) }
+            : {}),
+        ...(parameters.submittedChallenge
+            ? { submittedChallenge: snapshotValue(parameters.submittedChallenge) }
+            : {}),
+    });
+}
+function createPaymentSuccessContext(parameters) {
+    return Object.freeze({
+        ...(parameters.capturedRequest
+            ? { capturedRequest: snapshotCapturedRequest(parameters.capturedRequest) }
+            : {}),
+        challenge: snapshotValue(parameters.challenge),
+        ...(parameters.credential ? { credential: snapshotValue(parameters.credential) } : {}),
+        ...(parameters.envelope ? { envelope: snapshotVerifiedEnvelope(parameters.envelope) } : {}),
+        ...snapshotInputProperty(parameters.input),
+        method: snapshotMethod(parameters.method),
+        receipt: snapshotValue(parameters.receipt),
+        request: snapshotValue(parameters.request),
+    });
+}
+function snapshotMethod(method) {
+    return Object.freeze({
+        intent: method.intent,
+        name: method.name,
+    });
+}
+function snapshotError(error) {
+    if (!error)
+        return error;
+    const snapshot = Object.assign(Object.create(Object.getPrototypeOf(error)), error);
+    Object.defineProperties(snapshot, {
+        message: { value: error.message, enumerable: false },
+        name: { value: error.name, enumerable: false },
+    });
+    return Object.freeze(snapshot);
+}
+function snapshotVerifiedEnvelope(envelope) {
+    return Object.freeze({
+        capturedRequest: snapshotCapturedRequest(envelope.capturedRequest),
+        challenge: snapshotValue(envelope.challenge),
+        credential: snapshotValue(envelope.credential),
+        request: snapshotValue(envelope.request),
+    });
+}
+function snapshotCapturedRequest(capturedRequest) {
+    return Object.freeze({
+        headers: new Headers(capturedRequest.headers),
+        hasBody: capturedRequest.hasBody,
+        method: capturedRequest.method,
+        url: new URL(capturedRequest.url),
+    });
+}
+function snapshotNullableValue(value) {
+    if (value === null)
+        return null;
+    return snapshotValue(value);
+}
+function snapshotValue(value) {
+    try {
+        return freezeSnapshot(structuredClone(value));
+    }
+    catch {
+        return freezeSnapshot(value);
+    }
+}
+function snapshotInputProperty(input) {
+    if (input === undefined)
+        return {};
+    const snapshot = snapshotTransportInput(input);
+    return snapshot === undefined ? {} : { input: snapshot };
+}
+function snapshotTransportInput(input) {
+    if (input instanceof globalThis.Request) {
+        try {
+            return new globalThis.Request(input.url, {
+                headers: new Headers(input.headers),
+                method: input.method,
+            });
+        }
+        catch {
+            return undefined;
+        }
+    }
+    try {
+        return freezeSnapshot(structuredClone(input));
+    }
+    catch {
+        warnOnce(Warnings.transportInputSnapshot, 'Could not clone server event input; omitting `context.input`. Use `capturedRequest` for request correlation.');
+        return undefined;
+    }
+}
+// Event payloads are cloned before listeners see them; shallow freezing keeps
+// the guard simple while preventing top-level mutation of receipts/challenges.
+function freezeSnapshot(value) {
+    if (!value || typeof value !== 'object' || Object.isFrozen(value))
+        return value;
+    Object.freeze(value);
+    return value;
+}
+function isServiceWorkerRequest(input) {
+    return (input instanceof globalThis.Request &&
+        new URL(input.url).searchParams.has(Html.params.serviceWorker));
+}
+function createServiceWorkerResponse() {
+    return new Response(serviceWorker, {
+        status: 200,
+        headers: {
+            'Content-Type': 'application/javascript',
+            'Cache-Control': 'no-store',
+        },
+    });
+}
+function isIssuedChallengeResponse(response) {
+    return !(response instanceof globalThis.Response) || response.status === 402;
+}
 function getSafeCredentialReason(error) {
     if (error instanceof Credential.InvalidCredentialEncodingError)
         return error.message;
@@ -415,7 +947,30 @@ function getSafeCredentialReason(error) {
 const defaultRealm = 'MPP Payment';
 const Warnings = {
     realmFallback: 'realm-fallback',
+    transportInputSnapshot: 'transport-input-snapshot',
 };
+const missingReceiptResponseErrorName = 'MissingReceiptResponseError';
+const missingReceiptResponseErrorMessage = 'withReceipt() requires a response argument';
+/** Error thrown when `withReceipt()` needs a response but none was provided. */
+export class MissingReceiptResponseError extends Error {
+    name = missingReceiptResponseErrorName;
+    constructor() {
+        super(missingReceiptResponseErrorMessage);
+    }
+}
+/** Returns true when an error is the typed `withReceipt()` no-response sentinel. */
+export function isMissingReceiptResponseError(error) {
+    if (error instanceof MissingReceiptResponseError)
+        return true;
+    if (!error || typeof error !== 'object')
+        return false;
+    const value = error;
+    return (value.name === missingReceiptResponseErrorName &&
+        value.message === missingReceiptResponseErrorMessage);
+}
+function normalizeExpires(expires) {
+    return expires === undefined ? undefined : z.toDatetimeString(expires);
+}
 const _warned = new Set();
 function warnOnce(key, message) {
     if (_warned.has(key))
@@ -452,18 +1007,33 @@ async function resolveRouteChallenge(parameters) {
         (parameters.capturedRequest
             ? resolveRealmFromCapturedRequest(parameters.capturedRequest)
             : defaultRealm);
+    const challenge = Challenge.fromMethod(parameters.method, {
+        description: parameters.description,
+        expires: parameters.expires,
+        meta: parameters.meta,
+        realm: effectiveRealm,
+        request: request,
+        secretKey: parameters.secretKey,
+    });
     return {
-        challenge: Challenge.fromMethod(parameters.method, {
-            description: parameters.description,
-            expires: parameters.expires,
-            meta: parameters.meta,
-            realm: effectiveRealm,
-            request: request,
-            secretKey: parameters.secretKey,
-        }),
+        challenge,
+        parsedRequest: challenge.request,
         request,
     };
 }
+function createFallbackChallenge(parameters) {
+    return Challenge.fromMethod(parameters.method, {
+        description: parameters.description,
+        expires: parameters.expires,
+        meta: parameters.meta,
+        realm: parameters.realm ??
+            (parameters.capturedRequest
+                ? resolveRealmFromCapturedRequest(parameters.capturedRequest)
+                : defaultRealm),
+        request: { ...parameters.defaults, ...parameters.routeRequest },
+        secretKey: parameters.secretKey,
+    });
+}
 /**
  * Captures the transport request into a frozen snapshot at the start of the
  * verification flow. This snapshot is threaded through request() → verify() →
@@ -473,7 +1043,7 @@ async function resolveRouteChallenge(parameters) {
  *
  * Note: Object.freeze is shallow — it prevents reassigning top-level properties
  * but does not deep-freeze mutable class instances like Headers or URL. This is
- * an accidental-mutation guard for trusted server hooks, not a security boundary.
+ * an accidental-mutation guard for trusted server events, not a security boundary.
  */
 async function captureRequest(transport, input) {
     const capturedRequest = transport.captureRequest
@@ -493,6 +1063,17 @@ function captureRequestFromInput(input) {
 const coreBindingFields = ['amount', 'currency', 'recipient'];
 const methodBindingFields = ['chainId', 'memo', 'splits', 'unitType'];
 const pinnedRequestBindingFields = [...coreBindingFields, ...methodBindingFields];
+function getChallengeBindingMismatch(expectedChallenge, actualChallenge, stableBinding) {
+    if (!stableBinding)
+        return getPinnedChallengeMismatch(expectedChallenge, actualChallenge);
+    for (const field of ['method', 'intent', 'realm']) {
+        if (actualChallenge[field] !== expectedChallenge[field])
+            return field;
+    }
+    if (!opaqueValuesMatch(expectedChallenge.meta, actualChallenge.meta))
+        return 'opaque';
+    return getRequestBindingMismatch(getStableBinding(expectedChallenge.request, stableBinding), getStableBinding(actualChallenge.request, stableBinding));
+}
 /**
  * Compares only the fields that MUST be stable across request-hook transforms.
  *
@@ -548,6 +1129,16 @@ function getPinnedRequestBinding(request) {
         },
     };
 }
+function getRequestBindingMismatch(expected, actual) {
+    const fields = [
+        ...Object.keys(expected),
+        ...Object.keys(actual).filter((key) => !(key in expected)),
+    ];
+    return fields.find((field) => !isDeepStrictEqual(normalizeComparable(expected[field]), normalizeComparable(actual[field])));
+}
+function getStableBinding(request, stableBinding) {
+    return stableBinding(request);
+}
 function normalizeScalar(value) {
     return value === undefined ? undefined : String(value);
 }
@@ -584,6 +1175,12 @@ function hydrateCredentialMeta(credential) {
         },
     };
 }
+function withParsedCredentialPayload(credential, payload) {
+    return {
+        ...credential,
+        payload,
+    };
+}
 export function compose(...args) {
     // Extract optional html options from last argument
     const last = args[args.length - 1];
@@ -642,14 +1239,18 @@ export function compose(...args) {
                 // transformed fields (e.g. amount with decimals) match correctly.
                 // Also checks inside methodDetails for fields moved there by transforms.
                 const candidates = handlers.filter((h) => {
-                    const internal = h._internal;
-                    if (!internal || internal.name !== credMethod || internal.intent !== credIntent)
+                    try {
+                        const internal = h._internal;
+                        if (!internal || internal.name !== credMethod || internal.intent !== credIntent)
+                            return false;
+                        const mismatch = internal._stableBinding
+                            ? getRequestBindingMismatch(getStableBinding(internal._canonicalRequest, internal._stableBinding), getStableBinding(credReq, internal._stableBinding))
+                            : getPinnedRequestBindingMismatch(internal._canonicalRequest, credReq);
+                        return !mismatch && opaqueValuesMatch(internal.meta, credential.challenge.meta);
+                    }
+                    catch {
                         return false;
-                    const canonical = internal._canonicalRequest;
-                    if (!canonical)
-                        return true;
-                    return (!getPinnedRequestBindingMismatch(canonical, credReq) &&
-                        opaqueValuesMatch(internal.meta, credential.challenge.meta));
+                    }
                 });
                 const match = candidates[0] ??
                     handlers.find((h) => {
@@ -663,8 +1264,15 @@ export function compose(...args) {
             // handler which will reject with an appropriate error (invalid challenge, etc.).
             return handlers[0](input);
         }
-        // No credential — call all handlers and merge 402 challenges.
-        const results = await Promise.all(handlers.map((h) => h(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 handlers) {
+            const result = await handler(input);
+            if (result.status === 200)
+                return result;
+            results.push(result);
+        }
         const challengeEntries = (() => {
             const entries = [];
             for (let i = 0; i < handlers.length; i++) {
@@ -792,10 +1400,26 @@ export function toNodeListener(handler) {
             await NodeListener.sendResponse(res, result.challenge);
         }
         else {
+            const managementResponse = getManagementResponse(result);
+            if (managementResponse) {
+                await NodeListener.sendResponse(res, managementResponse);
+                return { challenge: managementResponse, status: 402 };
+            }
             const wrapped = result.withReceipt(new globalThis.Response());
             res.setHeader('Payment-Receipt', wrapped.headers.get('Payment-Receipt'));
         }
         return result;
     };
 }
+function getManagementResponse(result) {
+    try {
+        return result.withReceipt();
+    }
+    catch (error) {
+        if (isMissingReceiptResponseError(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
 //# sourceMappingURL=Mppx.js.map