mppx 0.6.18 → 0.6.20

package/src/server/Mppx.ts

@@ -10,7 +10,7 @@ import * as Env from '../internal/env.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'
@@ -53,6 +53,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 +107,9 @@ 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.
+     *
      * @example
      * ```ts
      * const receipt = await mppx.verifyCredential('eyJjaGFsbGVuZ2...')
@@ -237,12 +242,14 @@ export function create<
   for (const mi of methods) {
     intentCount[mi.intent] = (intentCount[mi.intent] ?? 0) + 1
     handlers[`${mi.name}/${mi.intent}`] = createMethodFn({
+      authorize: mi.authorize as never,
       defaults: mi.defaults,
       method: mi,
       realm,
       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,
     })
@@ -339,7 +346,11 @@ export function create<
           routeRequest: options?.request ?? {},
           secretKey: secretKey!,
         }).then((resolved) => {
-          const mismatch = getPinnedChallengeMismatch(resolved.challenge, credential.challenge)
+          const mismatch = getChallengeBindingMismatch(
+            resolved.challenge,
+            credential.challenge,
+            mi.stableBinding as never,
+          )
           if (mismatch)
             throw new Errors.InvalidChallengeError({
               id: credential.challenge.id,
@@ -421,7 +432,17 @@ 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,
+    method,
+    realm,
+    respond,
+    secretKey,
+    stableBinding,
+    transport,
+    verify,
+  } = parameters
 
   return (options) => {
     const { description, meta, scope, ...rest } = options
@@ -430,7 +451,9 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
     return Object.assign(
       async (input: Transport.InputOf): Promise<MethodFn.Response> => {
         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 +469,7 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
             return [null, e as Error] as const
           }
         })()
-        const { challenge, request } = await resolveRouteChallenge({
+        const routeChallenge = await resolveRouteChallenge({
           capturedRequest,
           credential,
           defaults,
@@ -458,7 +481,29 @@ 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,
+          })
+          const response = await transport.respondChallenge({
+            challenge,
+            input,
+            error: e,
+            html: method.html,
+          })
+          return { response }
         })
+        if ('response' in routeChallenge) return { challenge: routeChallenge.response, status: 402 }
+        const { challenge, request } = routeChallenge
 
         // Credential was provided but malformed
         if (credentialError) {
@@ -472,8 +517,77 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
           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) {
+          if (authorize && input instanceof globalThis.Request) {
+            try {
+              const authorized = await authorize({
+                challenge,
+                input,
+                request: challenge.request,
+              } as never)
+              if (authorized) {
+                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()
+              const response = await transport.respondChallenge({
+                challenge,
+                input,
+                error,
+                html: method.html,
+              })
+              return { challenge: response, status: 402 }
+            }
+          }
+
           const response = await transport.respondChallenge({
             challenge,
             input,
@@ -530,7 +644,11 @@ 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({
               challenge,
@@ -601,30 +719,12 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
           ? 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,
-              envelope,
-              input,
-              receipt: receiptData,
-              response: response as never,
-            }) as response
-          },
-        }
+        return success(receiptData, {
+          challengeId: credential.challenge.id,
+          credentialForReceipt: credential,
+          envelopeForReceipt: envelope,
+          managementResponse,
+        })
       },
       {
         _internal: {
@@ -635,6 +735,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 +759,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,
@@ -694,12 +797,14 @@ declare namespace createMethodFn {
     transport extends Transport.AnyTransport = Transport.Http,
     defaults extends Record<string, unknown> = Record<string, unknown>,
   > = {
+    authorize?: Method.AuthorizeFn<method>
     defaults?: defaults
     method: method
     realm: string | undefined
     request?: Method.RequestFn<method>
     respond?: Method.RespondFn<method>
     secretKey: string
+    stableBinding?: Method.StableBindingFn<method>
     transport: transport
     verify: Method.VerifyFn<method>
   }
@@ -715,6 +820,34 @@ const defaultRealm = 'MPP Payment'
 const Warnings = {
   realmFallback: 'realm-fallback',
 } 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) {
@@ -785,6 +918,31 @@ async function resolveRouteChallenge(parameters: {
   }
 }
 
+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() →
@@ -831,6 +989,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 +1089,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)
 }
@@ -957,20 +1173,6 @@ function hydrateCredentialMeta<payload>(
     },
   }
 }
-
-type CoreBinding = {
-  [field in CoreBindingField]?: string
-}
-
-type MethodBinding = {
-  [field in MethodBindingField]?: unknown
-}
-
-type PinnedRequestBinding = {
-  coreBinding: CoreBinding
-  methodBinding: MethodBinding
-}
-
 export type MethodFn<
   method extends Method.Method,
   transport extends Transport.AnyTransport,
@@ -991,8 +1193,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 +1221,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 +1342,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 +1372,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 +1530,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 +1544,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

package/src/stripe/server/internal/html/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@stripe/stripe-js": "9.3.1",
+    "@stripe/stripe-js": "9.4.0",
     "mppx": "workspace:*"
   }
 }