mppx 0.6.20 → 0.6.22

package/dist/server/Mppx.js

@@ -13,6 +13,20 @@ 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.
  *
@@ -35,15 +49,20 @@ 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,
@@ -81,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 ||
@@ -113,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 = 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`,
-                    });
-                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')
@@ -163,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,
@@ -175,11 +311,16 @@ export function create(config) {
 }
 // biome-ignore lint/correctness/noUnusedVariables: _
 function createMethodFn(parameters) {
-    const { authorize, defaults, method, realm, respond, secretKey, stableBinding, 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) => {
+            if (method.html && isServiceWorkerRequest(input))
+                return {
+                    status: 402,
+                    challenge: createServiceWorkerResponse(),
+                };
             const expires = 'expires' in options
                 ? normalizeExpires(options.expires)
                 : Expires.minutes(5);
@@ -197,6 +338,38 @@ function createMethodFn(parameters) {
                     return [null, e];
                 }
             })();
+            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,
@@ -223,9 +396,19 @@ function createMethodFn(parameters) {
                     routeRequest: rest,
                     secretKey,
                 });
-                const response = await transport.respondChallenge({
+                if (credential)
+                    await emitPaymentFailed({
+                        challenge,
+                        credential,
+                        error: e,
+                        request: challenge.request,
+                        retryChallenge: challenge,
+                        submittedChallenge: credential.challenge,
+                    });
+                const response = await emitChallenge({
                     challenge,
-                    input,
+                    credential,
+                    request: challenge.request,
                     error: e,
                     html: method.html,
                 });
@@ -233,14 +416,23 @@ function createMethodFn(parameters) {
             });
             if ('response' in routeChallenge)
                 return { challenge: routeChallenge.response, status: 402 };
-            const { challenge, request } = routeChallenge;
+            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 };
@@ -283,6 +475,14 @@ function createMethodFn(parameters) {
                             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,
                             });
@@ -292,19 +492,28 @@ function createMethodFn(parameters) {
                         if (!(e instanceof Errors.PaymentError))
                             console.error('mppx: internal authorization error', e);
                         const error = e instanceof Errors.PaymentError ? e : new Errors.VerificationFailedError();
-                        const response = await transport.respondChallenge({
+                        await emitPaymentFailed({
                             challenge,
-                            input,
+                            credential: null,
+                            error,
+                            request: parsedRequest,
+                            retryChallenge: challenge,
+                        });
+                        const response = await emitChallenge({
+                            challenge,
+                            request: parsedRequest,
                             error,
                             html: method.html,
                         });
                         return { challenge: response, status: 402 };
                     }
                 }
-                const response = await transport.respondChallenge({
+                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 };
@@ -321,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 };
@@ -357,13 +576,23 @@ function createMethodFn(parameters) {
             {
                 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 };
@@ -374,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 };
@@ -422,11 +680,27 @@ 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;
+            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: credential,
+                credentialForReceipt: parsedCredential,
                 envelopeForReceipt: envelope,
                 managementResponse,
             });
@@ -470,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;
@@ -482,6 +947,7 @@ 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';
@@ -541,15 +1007,17 @@ 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,
     };
 }
@@ -575,7 +1043,7 @@ function createFallbackChallenge(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
@@ -707,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];