mppx 0.6.19 → 0.6.21

package/src/server/Mppx.ts

@@ -7,10 +7,11 @@ import * as Errors from '../Errors.js'
 import * as Expires from '../Expires.js'
 import * as AcceptPayment from '../internal/AcceptPayment.js'
 import * as Env from '../internal/env.js'
+import type { MaybePromise } from '../internal/types.js'
 import type * as Method from '../Method.js'
 import * as PaymentRequest from '../PaymentRequest.js'
 import type * as Receipt from '../Receipt.js'
-import type * as z from '../zod.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'
@@ -20,6 +21,125 @@ import * as Transport from './Transport.js'
 
 export type Methods = readonly (Method.AnyServer | readonly Method.AnyServer[])[]
 
+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>
+  'payment.success': PaymentSuccessContext<methods[number], transport>
+}
+
+export type ServerEventName<
+  methods extends readonly Method.Method[] = readonly Method.Method[],
+  transport extends Transport.AnyTransport = Transport.AnyTransport,
+> = keyof ServerEventMap<methods, transport> | '*'
+
+export type ServerEventEnvelope<
+  methods extends readonly Method.Method[] = readonly Method.Method[],
+  transport extends Transport.AnyTransport = Transport.AnyTransport,
+> = {
+  [name in keyof ServerEventMap<methods, transport>]: Readonly<{
+    name: name
+    payload: ServerEventMap<methods, transport>[name]
+  }>
+}[keyof ServerEventMap<methods, transport>]
+
+export type ServerEventPayload<
+  methods extends readonly Method.Method[] = readonly Method.Method[],
+  transport extends Transport.AnyTransport = Transport.AnyTransport,
+  name extends ServerEventName<methods, transport> = ServerEventName<methods, transport>,
+> = name extends '*'
+  ? ServerEventEnvelope<methods, transport>
+  : name extends keyof ServerEventMap<methods, transport>
+    ? ServerEventMap<methods, transport>[name]
+    : never
+
+/**
+ * Server event handler.
+ *
+ * Handlers are awaited inline and sequentially on the payment request path.
+ * Errors are swallowed so observers cannot change payment control flow, but
+ * slow handlers still delay the response.
+ */
+export type ServerEventHandler<
+  methods extends readonly Method.Method[] = readonly Method.Method[],
+  transport extends Transport.AnyTransport = Transport.AnyTransport,
+  name extends ServerEventName<methods, transport> = ServerEventName<methods, transport>,
+> = (context: ServerEventPayload<methods, transport, name>) => MaybePromise<void>
+
+/** Removes a registered server event handler. */
+export type Unsubscribe = () => void
+
+/** Inert method descriptor exposed to server event handlers. */
+export type ServerMethodDescriptor<
+  method extends Pick<Method.Method, 'intent' | 'name'> = Method.Method,
+> = Readonly<{
+  intent: method['intent']
+  name: method['name']
+}>
+
+/** Context passed to `onChallengeCreated`. */
+export type ChallengeContext<
+  method extends Method.Method = Method.Method,
+  transport extends Transport.AnyTransport = Transport.AnyTransport,
+> = Readonly<{
+  capturedRequest?: Method.CapturedRequest | undefined
+  challenge: Challenge.Challenge
+  credential?: Credential.Credential | null | undefined
+  error?: Errors.PaymentError | undefined
+  input?: Transport.InputOf<transport> | undefined
+  method: ServerMethodDescriptor<method>
+  request: z.output<method['schema']['request']>
+}>
+
+/** Context passed to `onPaymentFailed`. */
+export type PaymentFailedContext<
+  method extends Method.Method = Method.Method,
+  transport extends Transport.AnyTransport = Transport.AnyTransport,
+> = Readonly<{
+  capturedRequest?: Method.CapturedRequest | undefined
+  challenge: Challenge.Challenge
+  credential: Credential.Credential | null
+  error: Errors.PaymentError
+  input?: Transport.InputOf<transport> | undefined
+  method: ServerMethodDescriptor<method>
+  request: z.output<method['schema']['request']>
+  retryChallenge?: Challenge.Challenge | undefined
+  submittedChallenge?: Challenge.Challenge | undefined
+}>
+
+/** Context passed to `onPaymentSuccess`. */
+export type PaymentSuccessContext<
+  method extends Method.Method = Method.Method,
+  transport extends Transport.AnyTransport = Transport.AnyTransport,
+> = Readonly<{
+  capturedRequest?: Method.CapturedRequest | undefined
+  challenge: Challenge.Challenge<
+    z.output<method['schema']['request']>,
+    method['intent'],
+    method['name']
+  >
+  credential?:
+    | Credential.Credential<
+        z.output<method['schema']['credential']['payload']>,
+        Challenge.Challenge<z.output<method['schema']['request']>, method['intent'], method['name']>
+      >
+    | undefined
+  envelope?:
+    | Method.VerifiedChallengeEnvelope<
+        z.output<method['schema']['request']>,
+        z.output<method['schema']['credential']['payload']>,
+        method['intent'],
+        method['name']
+      >
+    | undefined
+  input?: Transport.InputOf<transport> | undefined
+  method: ServerMethodDescriptor<method>
+  receipt: Receipt.Receipt
+  request: z.output<method['schema']['request']>
+}>
+
 /** Options for standalone credential verification. */
 export type VerifyCredentialOptions = {
   capturedRequest?: Method.CapturedRequest | undefined
@@ -43,6 +163,23 @@ export type Mppx<
   realm: string
   /** The transport used. */
   transport: transport
+  /** Register a server event handler by canonical event name. */
+  on<name extends ServerEventName<FlattenMethods<methods>, transport>>(
+    name: name,
+    handler: ServerEventHandler<FlattenMethods<methods>, transport, name>,
+  ): Unsubscribe
+  /** Register a handler for issued payment challenges. */
+  onChallengeCreated(
+    handler: ServerEventHandler<FlattenMethods<methods>, transport, 'challenge.created'>,
+  ): Unsubscribe
+  /** Register a handler for failed submitted payment credentials. */
+  onPaymentFailed(
+    handler: ServerEventHandler<FlattenMethods<methods>, transport, 'payment.failed'>,
+  ): Unsubscribe
+  /** Register a handler for successful verified payments. */
+  onPaymentSuccess(
+    handler: ServerEventHandler<FlattenMethods<methods>, transport, 'payment.success'>,
+  ): Unsubscribe
 } & (transport extends Transport.Http
   ? {
       /**
@@ -53,6 +190,8 @@ export type Mppx<
        * server methods passed to `Mppx.create()`, looked up by `name`+`intent`.
        *
        * Only available on HTTP transports.
+       * No-credential authorize hooks run in entry order; the first 200 response
+       * wins, and earlier hooks may have already run side effects.
        *
        * @example
        * ```ts
@@ -105,6 +244,12 @@ export type Mppx<
      * HMAC-check, match to a registered method, validate payload schema,
      * check expiry, and call the method's verify function.
      *
+     * Method verification can settle payments and persist state. For example,
+     * subscription credentials may activate or renew a subscription. Failed
+     * standalone verification emits `payment.failed` once a credential challenge
+     * can be parsed; strings that cannot be deserialized have no challenge
+     * context to report.
+     *
      * @example
      * ```ts
      * const receipt = await mppx.verifyCredential('eyJjaGFsbGVuZ2...')
@@ -132,6 +277,25 @@ type EffectiveTransportOf<mi, defaultTransport extends Transport.AnyTransport> =
   ? defaultTransport
   : TransportOverrideOf<mi>
 
+const reservedMppxKeyValues = [
+  'challenge',
+  'compose',
+  'methods',
+  'on',
+  'onChallengeCreated',
+  'onPaymentFailed',
+  'onPaymentSuccess',
+  'realm',
+  'transport',
+  'verifyCredential',
+] as const
+
+/** Public instance keys that payment method names and shorthand intents cannot shadow. */
+export type ReservedKey = (typeof reservedMppxKeyValues)[number]
+
+/** Public instance keys that payment method names and shorthand intents cannot shadow. */
+export const reservedMppxKeys: ReadonlySet<ReservedKey> = new Set(reservedMppxKeyValues)
+
 /** True when exactly one method has the given intent (no name collision). */
 type IsUniqueIntent<methods extends readonly Method.AnyServer[], intent extends string> =
   Extract<methods[number], { intent: intent }> extends infer M
@@ -148,7 +312,9 @@ type UniqueIntentHandlers<
   transport extends Transport.AnyTransport,
 > = {
   [method_name in methods[number]['intent'] as IsUniqueIntent<methods, method_name> extends true
-    ? method_name
+    ? method_name extends ReservedKey
+      ? never
+      : method_name
     : never]: MethodFn<
     Extract<methods[number], { intent: method_name }>,
     EffectiveTransportOf<Extract<methods[number], { intent: method_name }>, transport>,
@@ -161,7 +327,7 @@ type NestedHandlers<
   methods extends readonly Method.AnyServer[],
   transport extends Transport.AnyTransport,
 > = {
-  [name in methods[number]['name']]: {
+  [name in methods[number]['name'] as name extends ReservedKey ? never : name]: {
     [mi in Extract<methods[number], { name: name }> as mi['intent']]: MethodFn<
       mi,
       EffectiveTransportOf<mi, transport>,
@@ -230,19 +396,27 @@ export function create<
   }
 
   const methods = config.methods.flat() as unknown as FlattenMethods<methods>
+  const serverEvents = createServerEventDispatcher<FlattenMethods<methods>, transport>()
 
   const handlers: Record<string, unknown> = {}
   const intentCount: Record<string, number> = {}
 
   for (const mi of methods) {
     intentCount[mi.intent] = (intentCount[mi.intent] ?? 0) + 1
+  }
+  assertNoReservedMppxKeys(methods as readonly Method.AnyServer[])
+
+  for (const mi of methods) {
     handlers[`${mi.name}/${mi.intent}`] = createMethodFn({
+      authorize: mi.authorize as never,
       defaults: mi.defaults,
       method: mi,
       realm,
+      events: serverEvents as never,
       request: mi.request as never,
       respond: mi.respond as never,
       secretKey,
+      stableBinding: mi.stableBinding as never,
       transport: (mi.transport ?? transport) as never,
       verify: mi.verify as never,
     })
@@ -283,37 +457,114 @@ export function create<
       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 as readonly Method.AnyServer[]).find(
       (m) => m.name === credMethod && m.intent === credIntent,
     )
-    if (!mi)
-      throw new Errors.InvalidChallengeError({
+    const eventMethod =
+      mi ?? ({ intent: credIntent, name: credMethod } satisfies ServerMethodDescriptor)
+
+    const emitStandalonePaymentFailed = async (parameters: {
+      challenge: Challenge.Challenge
+      credential: Credential.Credential | null
+      error: Errors.PaymentError
+      request: Record<string, unknown>
+      submittedChallenge?: Challenge.Challenge | undefined
+    }) => {
+      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,
+        }) as never,
+      )
+    }
+
+    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 as Record<string, unknown>,
+        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 as Record<string, unknown>,
+        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 as Record<string, unknown>,
+          submittedChallenge: credential.challenge,
+        })
+      throw e
+    }
 
     // Validate payload against method schema
-    mi.schema.credential.payload.parse(credential.payload)
+    let parsedCredential: Credential.Credential
+    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 as Record<string, unknown>,
+        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 as Record<string, unknown>,
+        submittedChallenge: credential.challenge,
+      })
+      throw error
     }
 
     const shouldValidateRoute =
@@ -326,40 +577,87 @@ export function create<
       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 as never,
-          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`,
-            })
+    let parsedRequest = credential.challenge.request as Record<string, unknown>
+    let request: z.input<typeof mi.schema.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 as never,
+            routeRequest: options?.request ?? {},
+            secretKey: secretKey!,
+          }).then((resolved) => {
+            const mismatch = getChallengeBindingMismatch(
+              resolved.challenge,
+              credential.challenge,
+              mi.stableBinding as never,
+            )
+            if (mismatch)
+              throw new Errors.InvalidChallengeError({
+                id: credential.challenge.id,
+                reason: `credential ${mismatch} does not match this route's requirements`,
+              })
 
-          return resolved.request as z.input<typeof mi.schema.request>
+            parsedRequest = resolved.parsedRequest
+            return resolved.request as z.input<typeof mi.schema.request>
+          })
+        : (credential.challenge.request as z.input<typeof mi.schema.request>)
+    } catch (e) {
+      if (e instanceof Errors.PaymentError)
+        await emitStandalonePaymentFailed({
+          challenge: credential.challenge,
+          credential: parsedCredential,
+          error: e,
+          request: credential.challenge.request as Record<string, unknown>,
+          submittedChallenge: credential.challenge,
         })
-      : (credential.challenge.request as z.input<typeof mi.schema.request>)
+      throw e
+    }
 
     const envelope = options?.capturedRequest
       ? ({
           capturedRequest: options.capturedRequest,
           challenge: credential.challenge,
-          credential,
-          request,
+          credential: parsedCredential,
+          request: parsedRequest,
         } as Method.VerifiedChallengeEnvelope)
       : undefined
 
-    return mi.verify({ credential, envelope, request } as never)
+    let receipt: Receipt.Receipt
+    try {
+      receipt = await mi.verify({ credential: parsedCredential, envelope, request } as never)
+    } 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,
+      }) as never,
+    )
+
+    return receipt
   }
 
   function composeFn(
@@ -385,10 +683,32 @@ export function create<
     return compose(...(configured as ConfiguredHandler[]))
   }
 
+  function onChallengeCreated(
+    handler: ServerEventHandler<FlattenMethods<methods>, transport, 'challenge.created'>,
+  ) {
+    return serverEvents.on('challenge.created', handler)
+  }
+
+  function onPaymentFailed(
+    handler: ServerEventHandler<FlattenMethods<methods>, transport, 'payment.failed'>,
+  ) {
+    return serverEvents.on('payment.failed', handler)
+  }
+
+  function onPaymentSuccess(
+    handler: ServerEventHandler<FlattenMethods<methods>, transport, 'payment.success'>,
+  ) {
+    return serverEvents.on('payment.success', handler)
+  }
+
   return {
     methods,
     challenge: challengeHandlers,
     compose: composeFn,
+    on: serverEvents.on,
+    onChallengeCreated,
+    onPaymentFailed,
+    onPaymentSuccess,
     realm: realm as string | undefined,
     transport,
     verifyCredential: verifyCredentialFn,
@@ -421,7 +741,18 @@ function createMethodFn<
 ): createMethodFn.ReturnType<method, transport, defaults>
 // biome-ignore lint/correctness/noUnusedVariables: _
 function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.ReturnType {
-  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
@@ -429,8 +760,16 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
 
     return Object.assign(
       async (input: Transport.InputOf): Promise<MethodFn.Response> => {
+        if (method.html && isServiceWorkerRequest(input))
+          return {
+            status: 402,
+            challenge: createServiceWorkerResponse(),
+          } as MethodFn.Response<Transport.Http>
+
         const expires =
-          'expires' in options ? (options.expires as string | undefined) : Expires.minutes(5)
+          'expires' in options
+            ? normalizeExpires(options.expires as z.DatetimeInput | undefined)
+            : Expires.minutes(5)
         const capturedRequest = await captureRequest(transport, input)
         const effectiveMeta =
           scope === undefined && input instanceof globalThis.Request
@@ -446,7 +785,61 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
             return [null, e as Error] as const
           }
         })()
-        const { challenge, request } = await resolveRouteChallenge({
+
+        const emitChallenge = async (parameters: {
+          challenge: Challenge.Challenge
+          credential?: Credential.Credential | null | undefined
+          error?: Errors.PaymentError | undefined
+          html?: Method.Method['html'] | undefined
+          request: Record<string, unknown>
+        }) => {
+          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,
+              }) as never,
+            )
+          return response
+        }
+
+        const emitPaymentFailed = async (parameters: {
+          challenge: Challenge.Challenge
+          credential: Credential.Credential | null
+          error: Errors.PaymentError
+          request: Record<string, unknown>
+          retryChallenge?: Challenge.Challenge | undefined
+          submittedChallenge?: Challenge.Challenge | undefined
+        }) => {
+          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,
+            }) as never,
+          )
+        }
+
+        const routeChallenge = await resolveRouteChallenge({
           capturedRequest,
           credential,
           defaults,
@@ -458,26 +851,156 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
           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: Receipt.Receipt,
+          options: {
+            challengeId?: string | undefined
+            credentialForReceipt?: Credential.Credential | undefined
+            envelopeForReceipt?: Method.VerifiedChallengeEnvelope | undefined
+            managementResponse?: globalThis.Response | undefined
+          } = {},
+        ): MethodFn.Response => {
+          const {
+            challengeId = challenge.id,
+            credentialForReceipt = { challenge, payload: {} } as Credential.Credential,
+            envelopeForReceipt,
+            managementResponse,
+          } = options
+
+          return {
+            status: 200,
+            withReceipt<response>(response?: response) {
+              if (managementResponse) {
+                return transport.respondReceipt({
+                  challengeId,
+                  credential: credentialForReceipt,
+                  ...(envelopeForReceipt ? { envelope: envelopeForReceipt } : {}),
+                  input,
+                  receipt: receiptData,
+                  response: managementResponse as never,
+                }) as response
+              }
+              if (!response) throw new MissingReceiptResponseError()
+              return transport.respondReceipt({
+                challengeId,
+                credential: credentialForReceipt,
+                ...(envelopeForReceipt ? { envelope: envelopeForReceipt } : {}),
+                input,
+                receipt: receiptData,
+                response: response as never,
+              }) as 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,
+              } as never)
+              if (authorized) {
+                await events.emit(
+                  'payment.success',
+                  createPaymentSuccessContext({
+                    capturedRequest,
+                    challenge,
+                    input,
+                    method,
+                    receipt: authorized.receipt,
+                    request: parsedRequest,
+                  }) as never,
+                )
+                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 }
@@ -495,13 +1018,23 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
         // (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 }
@@ -530,15 +1063,29 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
         // `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 as never,
+          )
           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 }
@@ -549,21 +1096,44 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
         try {
           Expires.assert(credential.challenge.expires, credential.challenge.id)
         } catch (error) {
-          const response = await transport.respondChallenge({
+          await emitPaymentFailed({
             challenge,
-            input,
+            credential,
+            error: error as Errors.PaymentError,
+            request: parsedRequest,
+            retryChallenge: challenge,
+            submittedChallenge: credential.challenge,
+          })
+          const response = await emitChallenge({
+            challenge,
+            credential,
+            request: parsedRequest,
             error: error as Errors.PaymentError,
           })
           return { challenge: response, status: 402 }
         }
         // Validate payload structure against method schema
+        let parsedCredential: Credential.Credential
         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 }
         }
@@ -571,22 +1141,31 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
         const envelope: Method.VerifiedChallengeEnvelope = 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: Receipt.Receipt
         try {
-          receiptData = await verify({ credential, envelope, request } as never)
+          receiptData = await verify({ credential: parsedCredential, envelope, request } as never)
         } 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 }
@@ -598,33 +1177,35 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
         // 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 } as never)
-          : undefined
-
-        return {
-          status: 200,
-          withReceipt<response>(response?: response) {
-            if (managementResponse) {
-              return transport.respondReceipt({
-                challengeId: credential.challenge.id,
-                credential,
-                envelope,
-                input,
-                receipt: receiptData,
-                response: managementResponse as never,
-              }) as response
-            }
-            if (!response) throw new Error('withReceipt() requires a response argument')
-            return transport.respondReceipt({
-              challengeId: credential.challenge.id,
-              credential,
+          ? await respond({
+              credential: parsedCredential,
               envelope,
               input,
               receipt: receiptData,
-              response: response as never,
-            }) as response
-          },
-        }
+              request,
+            } as never)
+          : undefined
+
+        await events.emit(
+          'payment.success',
+          createPaymentSuccessContext({
+            capturedRequest,
+            challenge: credential.challenge,
+            credential: parsedCredential,
+            envelope,
+            input,
+            method,
+            receipt: receiptData,
+            request: parsedRequest,
+          }) as never,
+        )
+
+        return success(receiptData, {
+          challengeId: credential.challenge.id,
+          credentialForReceipt: parsedCredential,
+          envelopeForReceipt: envelope,
+          managementResponse,
+        })
       },
       {
         _internal: {
@@ -635,6 +1216,7 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
           name: method.name,
           intent: method.intent,
           _canonicalRequest: PaymentRequest.fromMethod(method, { ...defaults, ...rest }),
+          _stableBinding: stableBinding as never,
         },
       },
     )
@@ -658,14 +1240,16 @@ function createChallengeFn(parameters: {
   return async (options) => {
     const { description, meta, scope, ...rest } = options as {
       description?: string
-      expires?: string
+      expires?: z.DatetimeInput
       meta?: Record<string, string>
       scope?: string
       [key: string]: unknown
     }
     const effectiveMeta = Scope.merge({ meta, scope })
     const expires =
-      'expires' in options ? (options.expires as string | undefined) : Expires.minutes(5)
+      'expires' in options
+        ? normalizeExpires(options.expires as z.DatetimeInput | undefined)
+        : Expires.minutes(5)
 
     return resolveRouteChallenge({
       defaults,
@@ -681,25 +1265,21 @@ function createChallengeFn(parameters: {
   }
 }
 
-function getSafeCredentialReason(error: unknown): string | undefined {
-  if (error instanceof Credential.InvalidCredentialEncodingError) return error.message
-  if (error instanceof Credential.MissingAuthorizationHeaderError) return error.message
-  if (error instanceof Credential.MissingPaymentSchemeError) return error.message
-  return undefined
-}
-
 declare namespace createMethodFn {
   type Parameters<
     method extends Method.Method = Method.Method,
     transport extends Transport.AnyTransport = Transport.Http,
     defaults extends Record<string, unknown> = Record<string, unknown>,
   > = {
+    authorize?: Method.AuthorizeFn<method>
     defaults?: defaults
     method: method
+    events: ServerEventDispatcher<readonly [method], transport>
     realm: string | undefined
     request?: Method.RequestFn<method>
     respond?: Method.RespondFn<method>
     secretKey: string
+    stableBinding?: Method.StableBindingFn<method>
     transport: transport
     verify: Method.VerifyFn<method>
   }
@@ -711,10 +1291,314 @@ declare namespace createMethodFn {
   > = MethodFn<method, transport, defaults>
 }
 
+type ServerEventDispatcher<
+  methods extends readonly Method.Method[],
+  transport extends Transport.AnyTransport,
+> = {
+  emit<name extends keyof ServerEventMap<methods, transport>>(
+    name: name,
+    context: ServerEventMap<methods, transport>[name],
+  ): Promise<void>
+  on<name extends ServerEventName<methods, transport>>(
+    name: name,
+    handler: ServerEventHandler<methods, transport, name>,
+  ): Unsubscribe
+}
+
+function createServerEventDispatcher<
+  methods extends readonly Method.Method[],
+  transport extends Transport.AnyTransport,
+>(): ServerEventDispatcher<methods, transport> {
+  const handlers = {
+    '*': new Set<ServerEventHandler<methods, transport, '*'>>(),
+    'challenge.created': new Set<ServerEventHandler<methods, transport, 'challenge.created'>>(),
+    'payment.failed': new Set<ServerEventHandler<methods, transport, 'payment.failed'>>(),
+    'payment.success': new Set<ServerEventHandler<methods, transport, 'payment.success'>>(),
+  }
+
+  const on: ServerEventDispatcher<methods, transport>['on'] = (name, handler) => {
+    switch (name) {
+      case '*':
+      case 'challenge.created':
+      case 'payment.failed':
+      case 'payment.success':
+        handlers[name].add(handler as never)
+        return () => handlers[name].delete(handler as never)
+      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<
+  methods extends readonly Method.Method[],
+  transport extends Transport.AnyTransport,
+  name extends keyof ServerEventMap<methods, transport>,
+>(
+  name: name,
+  payload: ServerEventMap<methods, transport>[name],
+): ServerEventPayload<methods, transport, '*'> {
+  return Object.freeze({ name, payload }) as ServerEventPayload<methods, transport, '*'>
+}
+
+async function emitServerEventHandlers(
+  handlers: ReadonlySet<(context: never) => MaybePromise<void>>,
+  context: unknown,
+): Promise<void> {
+  for (const handler of handlers) {
+    try {
+      await handler(context as never)
+    } catch {
+      // Errors are isolated, but handlers are still awaited inline.
+    }
+  }
+}
+
+function assertNoReservedMppxKeys(methods: readonly Method.AnyServer[]) {
+  for (const method of methods) {
+    if (reservedMppxKeys.has(method.name as ReservedKey))
+      throw new Error(`Method name "${method.name}" conflicts with a reserved Mppx property.`)
+    if (reservedMppxKeys.has(method.intent as ReservedKey))
+      throw new Error(`Method intent "${method.intent}" conflicts with a reserved Mppx property.`)
+  }
+}
+
+function createChallengeContext(parameters: {
+  capturedRequest?: Method.CapturedRequest | undefined
+  challenge: Challenge.Challenge
+  credential?: Credential.Credential | null | undefined
+  error?: Errors.PaymentError | undefined
+  input?: unknown
+  method: Method.Method | ServerMethodDescriptor
+  request: Record<string, unknown>
+}): ChallengeContext {
+  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),
+  }) as never
+}
+
+function createPaymentFailedContext(parameters: {
+  capturedRequest?: Method.CapturedRequest | undefined
+  challenge: Challenge.Challenge
+  credential: Credential.Credential | null
+  error: Errors.PaymentError
+  input?: unknown
+  method: Method.Method | ServerMethodDescriptor
+  request: Record<string, unknown>
+  retryChallenge?: Challenge.Challenge | undefined
+  submittedChallenge?: Challenge.Challenge | undefined
+}): PaymentFailedContext {
+  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) }
+      : {}),
+  }) as never
+}
+
+function createPaymentSuccessContext(parameters: {
+  capturedRequest?: Method.CapturedRequest | undefined
+  challenge: Challenge.Challenge
+  credential?: Credential.Credential | undefined
+  envelope?: Method.VerifiedChallengeEnvelope | undefined
+  input?: unknown
+  method: Method.Method | ServerMethodDescriptor
+  receipt: Receipt.Receipt
+  request: Record<string, unknown>
+}): PaymentSuccessContext {
+  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),
+  }) as never
+}
+
+function snapshotMethod<method extends Pick<Method.Method, 'intent' | 'name'>>(
+  method: method,
+): ServerMethodDescriptor<method> {
+  return Object.freeze({
+    intent: method.intent,
+    name: method.name,
+  }) as ServerMethodDescriptor<method>
+}
+
+function snapshotError<error extends Errors.PaymentError | undefined>(error: error): 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) as error
+}
+
+function snapshotVerifiedEnvelope(
+  envelope: Method.VerifiedChallengeEnvelope,
+): Method.VerifiedChallengeEnvelope {
+  return Object.freeze({
+    capturedRequest: snapshotCapturedRequest(envelope.capturedRequest),
+    challenge: snapshotValue(envelope.challenge),
+    credential: snapshotValue(envelope.credential),
+    request: snapshotValue(envelope.request),
+  }) as Method.VerifiedChallengeEnvelope
+}
+
+function snapshotCapturedRequest(capturedRequest: Method.CapturedRequest): Method.CapturedRequest {
+  return Object.freeze({
+    headers: new Headers(capturedRequest.headers),
+    hasBody: capturedRequest.hasBody,
+    method: capturedRequest.method,
+    url: new URL(capturedRequest.url),
+  })
+}
+
+function snapshotNullableValue<value>(value: value | null): value | null {
+  if (value === null) return null
+  return snapshotValue(value)
+}
+
+function snapshotValue<value>(value: value): value {
+  try {
+    return freezeSnapshot(structuredClone(value))
+  } catch {
+    return freezeSnapshot(value)
+  }
+}
+
+function snapshotInputProperty(input: unknown): { input: unknown } | {} {
+  if (input === undefined) return {}
+  const snapshot = snapshotTransportInput(input)
+  return snapshot === undefined ? {} : { input: snapshot }
+}
+
+function snapshotTransportInput<input>(input: input): input | undefined {
+  if (input instanceof globalThis.Request) {
+    try {
+      return new globalThis.Request(input.url, {
+        headers: new Headers(input.headers),
+        method: input.method,
+      }) as input
+    } 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>(value: value): value {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value
+  Object.freeze(value)
+  return value
+}
+
+function isServiceWorkerRequest(input: unknown): input is Request {
+  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: unknown): boolean {
+  return !(response instanceof globalThis.Response) || response.status === 402
+}
+
+function getSafeCredentialReason(error: unknown): string | undefined {
+  if (error instanceof Credential.InvalidCredentialEncodingError) return error.message
+  if (error instanceof Credential.MissingAuthorizationHeaderError) return error.message
+  if (error instanceof Credential.MissingPaymentSchemeError) return error.message
+  return undefined
+}
+
 const defaultRealm = 'MPP Payment'
 const Warnings = {
   realmFallback: 'realm-fallback',
+  transportInputSnapshot: 'transport-input-snapshot',
 } as const
+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 {
+  override name = missingReceiptResponseErrorName
+
+  constructor() {
+    super(missingReceiptResponseErrorMessage)
+  }
+}
+
+/** Returns true when an error is the typed `withReceipt()` no-response sentinel. */
+export function isMissingReceiptResponseError(
+  error: unknown,
+): error is MissingReceiptResponseError {
+  if (error instanceof MissingReceiptResponseError) return true
+  if (!error || typeof error !== 'object') return false
+  const value = error as { message?: unknown; name?: unknown }
+  return (
+    value.name === missingReceiptResponseErrorName &&
+    value.message === missingReceiptResponseErrorMessage
+  )
+}
+
+function normalizeExpires(expires: z.DatetimeInput | undefined): string | undefined {
+  return expires === undefined ? undefined : z.toDatetimeString(expires)
+}
 
 const _warned = new Set<string>()
 function warnOnce(key: string, message: string) {
@@ -750,6 +1634,7 @@ async function resolveRouteChallenge(parameters: {
   secretKey: string
 }): Promise<{
   challenge: Challenge.Challenge
+  parsedRequest: Record<string, unknown>
   request: Record<string, unknown>
 }> {
   // Resolve the route's canonical request exactly as the handler path does:
@@ -772,19 +1657,47 @@ async function resolveRouteChallenge(parameters: {
       ? resolveRealmFromCapturedRequest(parameters.capturedRequest)
       : defaultRealm)
 
+  const challenge = Challenge.fromMethod(parameters.method, {
+    description: parameters.description,
+    expires: parameters.expires,
+    meta: parameters.meta,
+    realm: effectiveRealm,
+    request: request as never,
+    secretKey: parameters.secretKey,
+  })
+
   return {
-    challenge: Challenge.fromMethod(parameters.method, {
-      description: parameters.description,
-      expires: parameters.expires,
-      meta: parameters.meta,
-      realm: effectiveRealm,
-      request: request as never,
-      secretKey: parameters.secretKey,
-    }),
+    challenge,
+    parsedRequest: challenge.request as Record<string, unknown>,
     request,
   }
 }
 
+function createFallbackChallenge(parameters: {
+  capturedRequest?: Method.CapturedRequest | undefined
+  defaults: Record<string, unknown>
+  description?: string | undefined
+  expires?: string | undefined
+  meta?: Record<string, string> | undefined
+  method: Method.Method
+  realm?: string | undefined
+  routeRequest: Record<string, unknown>
+  secretKey: string
+}) {
+  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 } as never,
+    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() →
@@ -794,7 +1707,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: Transport.AnyTransport,
@@ -831,6 +1744,26 @@ type CoreBindingField = (typeof coreBindingFields)[number]
 type MethodBindingField = (typeof methodBindingFields)[number]
 type PinnedRequestBindingField = (typeof pinnedRequestBindingFields)[number]
 type PinnedChallengeField = 'method' | 'intent' | 'realm' | 'opaque' | PinnedRequestBindingField
+type StableBinding = Record<string, unknown>
+
+function getChallengeBindingMismatch(
+  expectedChallenge: Challenge.Challenge,
+  actualChallenge: Challenge.Challenge,
+  stableBinding?: Method.StableBindingFn<Method.Method> | undefined,
+): string | undefined {
+  if (!stableBinding) return getPinnedChallengeMismatch(expectedChallenge, actualChallenge)
+
+  for (const field of ['method', 'intent', 'realm'] as const) {
+    if (actualChallenge[field] !== expectedChallenge[field]) return field
+  }
+
+  if (!opaqueValuesMatch(expectedChallenge.meta, actualChallenge.meta)) return 'opaque'
+
+  return getRequestBindingMismatch(
+    getStableBinding(expectedChallenge.request as Record<string, unknown>, stableBinding),
+    getStableBinding(actualChallenge.request as Record<string, unknown>, stableBinding),
+  )
+}
 
 /**
  * Compares only the fields that MUST be stable across request-hook transforms.
@@ -911,6 +1844,44 @@ function getPinnedRequestBinding(request: Record<string, unknown>): PinnedReques
   }
 }
 
+function getRequestBindingMismatch(
+  expected: StableBinding,
+  actual: StableBinding,
+): string | undefined {
+  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: Record<string, unknown>,
+  stableBinding: Method.StableBindingFn<Method.Method>,
+): StableBinding {
+  return stableBinding(request as never)
+}
+
+/** Top-level economic fields that should never drift after challenge issuance. */
+type CoreBinding = {
+  [field in CoreBindingField]?: string
+}
+
+/** Method-specific fields that are pinned by the fallback binding check. */
+type MethodBinding = {
+  [field in MethodBindingField]?: unknown
+}
+
+/** Normalized request subset used when a method does not provide a custom stable binding. */
+type PinnedRequestBinding = {
+  coreBinding: CoreBinding
+  methodBinding: MethodBinding
+}
+
 function normalizeScalar(value: unknown): string | undefined {
   return value === undefined ? undefined : String(value)
 }
@@ -958,19 +1929,15 @@ function hydrateCredentialMeta<payload>(
   }
 }
 
-type CoreBinding = {
-  [field in CoreBindingField]?: string
-}
-
-type MethodBinding = {
-  [field in MethodBindingField]?: unknown
-}
-
-type PinnedRequestBinding = {
-  coreBinding: CoreBinding
-  methodBinding: MethodBinding
+function withParsedCredentialPayload<payload>(
+  credential: Credential.Credential,
+  payload: payload,
+): Credential.Credential<payload> {
+  return {
+    ...credential,
+    payload,
+  }
 }
-
 export type MethodFn<
   method extends Method.Method,
   transport extends Transport.AnyTransport,
@@ -991,8 +1958,8 @@ declare namespace MethodFn {
   > = {
     /** Optional human-readable description of the payment. */
     description?: string | undefined
-    /** Optional challenge expiration timestamp (ISO 8601). */
-    expires?: string | undefined
+    /** Optional challenge expiration timestamp (ISO 8601) or Date. */
+    expires?: z.DatetimeInput | undefined
     /** Optional server-defined correlation data (serialized as `opaque` in the request). Flat string-to-string map; clients MUST NOT modify. */
     meta?: Record<string, string> | undefined
     /** Optional route/resource scope bound via reserved challenge metadata. */
@@ -1019,6 +1986,7 @@ type ConfiguredHandler = ((input: Request) => Promise<MethodFn.Response<Transpor
     meta?: Record<string, string> | undefined
     scope?: string | undefined
     _canonicalRequest: Record<string, unknown>
+    _stableBinding?: Method.StableBindingFn<Method.Method> | undefined
   }
 }
 
@@ -1139,15 +2107,20 @@ export function compose(
         // 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 as ConfiguredHandler)._internal
-          if (!internal || internal.name !== credMethod || internal.intent !== credIntent)
+          try {
+            const internal = (h as ConfiguredHandler)._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 =
@@ -1164,8 +2137,14 @@ export function compose(
       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: MethodFn.Response<Transport.Http>[] = []
+    for (const handler of handlers) {
+      const result = await handler(input)
+      if (result.status === 200) return result
+      results.push(result)
+    }
 
     const challengeEntries = (() => {
       const entries: {
@@ -1316,6 +2295,12 @@ export function toNodeListener(
     if (result.status === 402) {
       await NodeListener.sendResponse(res, result.challenge as globalThis.Response)
     } else {
+      const managementResponse = getManagementResponse(result)
+      if (managementResponse) {
+        await NodeListener.sendResponse(res, managementResponse)
+        return { challenge: managementResponse, status: 402 }
+      }
+
       const wrapped = result.withReceipt(new globalThis.Response()) as globalThis.Response
       res.setHeader('Payment-Receipt', wrapped.headers.get('Payment-Receipt')!)
     }
@@ -1324,6 +2309,19 @@ export function toNodeListener(
   }
 }
 
+function getManagementResponse(
+  result: Extract<MethodFn.Response<Transport.Http>, { status: 200 }>,
+): globalThis.Response | null {
+  try {
+    return (result.withReceipt as () => globalThis.Response)()
+  } catch (error) {
+    if (isMissingReceiptResponseError(error)) {
+      return null
+    }
+    throw error
+  }
+}
+
 /**
  * Flattens a methods config tuple, preserving positional types.
  * @internal