mppx 0.8.15 → 0.8.17

package/src/Challenge.ts

@@ -366,35 +366,12 @@ export function deserialize<const methods extends readonly Method.Method[] | und
 /** @internal Extracts the `Payment` scheme from a WWW-Authenticate value that may contain multiple schemes. */
 function extractPaymentAuthParams(header: string): string | null {
   const token = Constants.Schemes.payment
-  let inQuotes = false
-  let escaped = false
-
-  for (let i = 0; i < header.length; i++) {
-    const char = header[i]
-
-    if (inQuotes) {
-      if (escaped) escaped = false
-      else if (char === '\\') escaped = true
-      else if (char === '"') inQuotes = false
-      continue
-    }
-
-    if (char === '"') {
-      inQuotes = true
-      continue
-    }
-
-    if (!startsWithSchemeToken(header, i, token)) continue
-
-    const prefix = header.slice(0, i)
-    if (prefix.trim() && !prefix.trimEnd().endsWith(',')) continue
+  const [start] = findSchemeStarts(header, token)
+  if (start === undefined) return null
 
-    let paramsStart = i + token.length
-    while (paramsStart < header.length && /\s/.test(header[paramsStart] ?? '')) paramsStart++
-    return header.slice(paramsStart)
-  }
-
-  return null
+  let paramsStart = start + token.length
+  while (paramsStart < header.length && /\s/.test(header[paramsStart] ?? '')) paramsStart++
+  return header.slice(paramsStart)
 }
 
 /** @internal Parses auth-params with support for escaped quoted-string values. */
@@ -481,11 +458,43 @@ function readQuotedAuthParamValue(
 
 /** @internal */
 function startsWithSchemeToken(value: string, index: number, token: string): boolean {
-  if (!value.slice(index).toLowerCase().startsWith(token.toLowerCase())) return false
+  if (value.slice(index, index + token.length).toLowerCase() !== token.toLowerCase()) return false
   const next = value[index + token.length]
   return Boolean(next && /\s/.test(next))
 }
 
+/** @internal Finds auth scheme boundaries while ignoring quoted-string contents. */
+function findSchemeStarts(value: string, token: string): number[] {
+  const starts: number[] = []
+  let inQuotes = false
+  let escaped = false
+
+  for (let i = 0; i < value.length; i++) {
+    const char = value[i]
+
+    if (inQuotes) {
+      if (escaped) escaped = false
+      else if (char === '\\') escaped = true
+      else if (char === '"') inQuotes = false
+      continue
+    }
+
+    if (char === '"') {
+      inQuotes = true
+      continue
+    }
+
+    if (!startsWithSchemeToken(value, i, token)) continue
+
+    let boundary = i - 1
+    while (boundary >= 0 && /\s/.test(value[boundary] ?? '')) boundary--
+    if (boundary >= 0 && value[boundary] !== ',') continue
+    starts.push(i)
+  }
+
+  return starts
+}
+
 /**
  * Extracts the challenge from a Headers object.
  *
@@ -594,12 +603,7 @@ export function fromHeadersList<
 export function deserializeList<
   const methods extends readonly Method.Method[] | undefined = undefined,
 >(value: string, options?: from.Options<methods>): from.ReturnType<from.Parameters, methods>[] {
-  // Find the start index of each `Payment ` scheme prefix.
-  const starts: number[] = []
-  const schemePattern = new RegExp(`${Constants.Schemes.payment}\\s+`, 'gi')
-  for (const match of value.matchAll(schemePattern)) {
-    starts.push(match.index!)
-  }
+  const starts = findSchemeStarts(value, Constants.Schemes.payment)
   if (starts.length === 0) throw new Error('No Payment schemes found.')
 
   // Slice each scheme from its `Payment ` prefix up to the next scheme boundary,

package/src/Method.ts

@@ -1,9 +1,8 @@
 import type * as Challenge from './Challenge.js'
-import * as Constants from './Constants.js'
 import * as Credential from './Credential.js'
 import * as Errors from './Errors.js'
 import * as Expires from './Expires.js'
-import type { ExactPartial, LooseOmit, MaybePromise } from './internal/types.js'
+import type { DeepReadonly, ExactPartial, LooseOmit, MaybePromise } from './internal/types.js'
 import type * as Receipt from './Receipt.js'
 import type * as Html from './server/internal/html/config.js'
 import type * as Transport from './server/Transport.js'
@@ -195,28 +194,64 @@ export type Server<
   transportOverride = undefined,
   extensions extends object = {},
   alias extends string | undefined = string | undefined,
-> = method & {
-  alias?: alias | undefined
-  authorize?: AuthorizeFn<method> | undefined
-  defaults?: defaults | undefined
-  extensions?: extensions | undefined
-  html?: Html.Options | undefined
-  preflight?: PreflightFn<method> | undefined
-  request?: RequestFn<method> | undefined
-  respond?: RespondFn<method> | undefined
-  broadcast?: BroadcastFn<method> | undefined
-  stableBinding?: StableBindingFn<method> | undefined
-  transport?: transportOverride | undefined
-  validate?: ValidateFn<method> | undefined
-  /**
-   * @deprecated Use `validate` for the non-mutating pre-check and `broadcast`
-   * for settlement. `verify` combines both operations and may consume payment
-   * state, so it cannot support a safe pre-check endpoint.
-   */
-  verify: VerifyFn<method>
-}
+> = method &
+  ComposableHooks<method> & {
+    alias?: alias | undefined
+    authorize?: AuthorizeFn<method> | undefined
+    defaults?: defaults | undefined
+    extensions?: extensions | undefined
+    html?: Html.Options | undefined
+    preflight?: PreflightFn<method> | undefined
+    request?: RequestFn<method> | undefined
+    respond?: RespondFn<method> | undefined
+    broadcast?: BroadcastFn<method> | undefined
+    stableBinding?: StableBindingFn<method> | undefined
+    transport?: transportOverride | undefined
+    validate?: ValidateFn<method> | undefined
+    /**
+     * @deprecated Use `validate` for the non-mutating pre-check and `broadcast`
+     * for settlement. `verify` combines both operations and may consume payment
+     * state, so it cannot support a safe pre-check endpoint.
+     */
+    verify: VerifyFn<method>
+  }
 export type AnyServer = Server<any, any, any, any, any>
 
+/**
+ * Decides whether a configured method offer is available for an HTTP request.
+ *
+ * Called once per configured offer during composition. The payment request is
+ * schema-normalized and deeply immutable. `input` is cloned so its body can be
+ * safely inspected unless the upstream body was already consumed or locked, in
+ * which case the clone preserves request metadata without a body. Returning
+ * `false` removes only this method's offer. Successfully matched credential
+ * dispatch does not invoke this hook.
+ */
+export type CanOfferFn<method extends Method> = (parameters: {
+  input: globalThis.Request
+  request: DeepReadonly<z.output<method['schema']['request']>>
+}) => MaybePromise<boolean>
+
+/** Hooks supported by every composable server method constructor. */
+/**
+ * Optional per-method hook invoked after a payment succeeds.
+ *
+ * Called after verification completes successfully. Use this for side-effects
+ * like recording the payment in an external system.
+ */
+export type OnPaymentSuccessFn<method extends Method> = (parameters: {
+  input?: globalThis.Request
+  receipt: DeepReadonly<Receipt.Receipt>
+  request: DeepReadonly<z.output<method['schema']['request']>>
+}) => MaybePromise<void>
+
+export type ComposableHooks<method extends Method> = {
+  /** Decides whether this method's configured offer is available for an HTTP request. */
+  canOffer?: CanOfferFn<method> | undefined
+  /** Invoked after a successful payment on this method. */
+  onPaymentSuccess?: OnPaymentSuccessFn<method> | undefined
+}
+
 /** Credential creation function for a single method. */
 export type CreateCredentialFn<method extends Method, context = unknown> = (
   parameters: {
@@ -363,11 +398,9 @@ export async function broadcastCredential<const methods extends readonly AnyServ
 /**
  * Parses a submitted credential into the inputs required for method execution.
  *
- * Dispatch is based on the challenge method and intent. When more than one
- * server method handles the same wire identity, session protocol details select
- * the appropriate implementation. The helper then asserts challenge expiry and
- * parses the method-specific credential payload before returning the selected
- * method and the unmodified challenge request.
+ * Dispatch is based on the challenge method and intent. The helper then asserts
+ * challenge expiry and parses the method-specific credential payload before
+ * returning the selected method and the unmodified challenge request.
  *
  * This intentionally does not verify that the challenge was issued by a
  * particular host, authorize the caller or requested resource, validate the
@@ -387,7 +420,7 @@ function prepareCredential(
     (method) =>
       method.name === credential.challenge.method && method.intent === credential.challenge.intent,
   )
-  const method = selectServerMethod(candidates, credential.challenge)
+  const method = candidates[0]
   if (!method)
     throw new Errors.InvalidChallengeError({
       id: credential.challenge.id,
@@ -410,29 +443,6 @@ function prepareCredential(
   }
 }
 
-/** @internal */
-export function selectServerMethod(
-  methods: readonly AnyServer[],
-  challenge: Challenge.Challenge,
-): AnyServer | undefined {
-  if (methods.length <= 1) return methods[0]
-  if (
-    challenge.method !== Constants.Methods.tempo ||
-    challenge.intent !== Constants.Intents.session
-  )
-    return methods[0]
-
-  const sessionProtocol = Constants.getMethodDetail(
-    challenge.request.methodDetails,
-    Constants.MethodDetailKeys.sessionProtocol,
-  )
-  if (sessionProtocol === undefined || sessionProtocol === Constants.SessionProtocols.v1)
-    return methods.find((method) => method.alias === 'sessionLegacy') ?? methods[0]
-  if (sessionProtocol === Constants.SessionProtocols.v2)
-    return methods.find((method) => method.alias === undefined) ?? methods[0]
-  return undefined
-}
-
 /**
  * Optional respond function for a server-side method.
  *
@@ -537,9 +547,11 @@ export function toServer<
   const {
     alias,
     authorize,
+    canOffer,
     defaults,
     extensions,
     html,
+    onPaymentSuccess,
     preflight,
     request,
     respond,
@@ -563,9 +575,11 @@ export function toServer<
     ...method,
     alias,
     authorize,
+    canOffer,
     defaults,
     extensions,
     html,
+    onPaymentSuccess,
     preflight,
     request,
     respond,
@@ -586,7 +600,7 @@ export declare namespace toServer {
     transportOverride extends Transport.AnyTransport | undefined = undefined,
     extensions extends object = {},
     alias extends string | undefined = undefined,
-  > = {
+  > = ComposableHooks<method> & {
     alias?: alias | undefined
     authorize?: AuthorizeFn<method> | undefined
     defaults?: defaults | undefined
@@ -598,20 +612,20 @@ export declare namespace toServer {
     stableBinding?: StableBindingFn<method> | undefined
     transport?: transportOverride | Transport.AnyTransport | undefined
   } & (
-    | {
-        broadcast: BroadcastFn<method>
-        validate?: ValidateFn<method> | undefined
-        verify?: undefined
-      }
-    | {
-        broadcast?: undefined
-        validate?: undefined
-        /**
-         * @deprecated Use `validate` and `broadcast` for new methods. This
-         * combined hook may mutate payment state and cannot power a safe
-         * validation-only endpoint.
-         */
-        verify: VerifyFn<method>
-      }
-  )
+      | {
+          broadcast: BroadcastFn<method>
+          validate?: ValidateFn<method> | undefined
+          verify?: undefined
+        }
+      | {
+          broadcast?: undefined
+          validate?: undefined
+          /**
+           * @deprecated Use `validate` and `broadcast` for new methods. This
+           * combined hook may mutate payment state and cannot power a safe
+           * validation-only endpoint.
+           */
+          verify: VerifyFn<method>
+        }
+    )
 }

package/src/Store.test-d.ts

@@ -20,6 +20,11 @@ test('default AtomicStore accepts any string key on update', () => {
   expectTypeOf(store.update).parameter(0).toBeString()
 })
 
+test('default AtomicStore accepts any string key on tryClaim', () => {
+  const store = {} as Store.AtomicStore
+  expectTypeOf<NonNullable<typeof store.tryClaim>>().parameter(0).toBeString()
+})
+
 test('memory returns AtomicStore', () => {
   const store = Store.memory()
   expectTypeOf(store).toEqualTypeOf<Store.AtomicStore>()
@@ -110,6 +115,17 @@ test('typed AtomicStore constrains keys on update', () => {
   expectTypeOf(store.update).parameter(0).toEqualTypeOf<`mppx:charge:${string}`>()
 })
 
+test('typed tryClaim constrains keys', () => {
+  type ItemMap = { [key: `mppx:charge:${string}`]: number }
+  const store = {} as Store.AtomicStore<ItemMap>
+
+  expectTypeOf(Store.tryClaim(store, 'mppx:charge:0x123', 1)).toEqualTypeOf<
+    boolean | Promise<boolean>
+  >()
+  // @ts-expect-error — key must match the item map
+  Store.tryClaim(store, 'other:0x123', 1)
+})
+
 test('typed Store infers value from key', async () => {
   type ItemMap = { [key: `mppx:charge:${string}`]: number }
   const store = {} as Store.Store<ItemMap>

package/src/Store.test.ts

@@ -140,6 +140,17 @@ describe('keyPrefix', () => {
     expect(await backing.get('k')).toBeNull()
   })
 
+  test('scopes optimized tryClaim to prefixed backing keys', async () => {
+    const backing = Store.memory()
+    const store = Store.from(backing, { keyPrefix: 'tenant:' })
+    const expires = Date.now() + 60_000
+
+    expect(await Store.tryClaim(store, 'k', expires)).toBe(true)
+    expect(await Store.tryClaim(store, 'k', expires)).toBe(false)
+    expect(await backing.get('tenant:k')).toEqual({ expires, type: 'mppx:replay' })
+    expect(await backing.get('k')).toBeNull()
+  })
+
   test('returns the original store when keyPrefix is empty', () => {
     const backing = Store.memory()
     expect(Store.from(backing, { keyPrefix: '' })).toBe(backing)
@@ -189,6 +200,45 @@ describe('keyPrefix', () => {
   })
 })
 
+describe('tryClaim', () => {
+  test('uses an adapter fast path when available', async () => {
+    const backing = Store.memory()
+    const optimized = backing.tryClaim!
+    let calls = 0
+    const store = {
+      ...backing,
+      tryClaim(key: string, expires: number) {
+        calls++
+        return optimized(key, expires)
+      },
+    }
+    const expires = Date.now() + 60_000
+
+    expect(await Store.tryClaim(store, 'k', expires)).toBe(true)
+    expect(await Store.tryClaim(store, 'k', expires)).toBe(false)
+    expect(await store.get('k')).toEqual({ expires, type: 'mppx:replay' })
+    expect(calls).toBe(2)
+  })
+
+  test('falls back to atomic update and replaces expired claims', async () => {
+    const store = Store.cloudflare(fakeStringKv())
+    expect(store.tryClaim).toBeUndefined()
+    const expires = Date.now() + 60_000
+
+    expect(await Store.tryClaim(store, 'k', Date.now() - 1)).toBe(true)
+    expect(await Store.tryClaim(store, 'k', expires)).toBe(true)
+    expect(await Store.tryClaim(store, 'k', expires)).toBe(false)
+    expect(await store.get('k')).toEqual({ expires, type: 'mppx:replay' })
+  })
+
+  test('preserves legacy replay markers as consumed', async () => {
+    const store = Store.memory()
+    await store.put('k', Date.now() - 60_000)
+
+    expect(await Store.tryClaim(store, 'k', Date.now() + 60_000)).toBe(false)
+  })
+})
+
 describe('json roundtrip behavior', () => {
   test('cloudflare json-roundtrips nested objects', async () => {
     const store = Store.cloudflare(fakeStringKv())

package/src/Store.ts

@@ -16,6 +16,8 @@
  */
 import { Json } from 'ox'
 
+import type { MaybePromise } from './internal/types.js'
+
 export type StoreItemMap = Record<string, unknown>
 
 /**
@@ -47,6 +49,20 @@ export type Update<itemMap extends StoreItemMap = StoreItemMap> = <
   fn: (current: itemMap[key] | null) => Change<itemMap[key], result>,
 ) => Promise<result>
 
+/** Attempts to atomically record first use of a replay key through its expiry. */
+export type TryClaim<itemMap extends StoreItemMap = StoreItemMap> = <
+  key extends keyof itemMap & string,
+>(
+  key: key,
+  expires: number,
+) => MaybePromise<boolean>
+
+/** Persisted marker used by the {@link tryClaim} fallback. */
+export type ReplayMarker = {
+  expires: number
+  type: 'mppx:replay'
+}
+
 /** Base key-value actions available on every {@link Store}. */
 export type StoreActions<itemMap extends StoreItemMap = StoreItemMap> = {
   get: <key extends keyof itemMap & string>(key: key) => Promise<itemMap[key] | null>
@@ -57,6 +73,8 @@ export type StoreActions<itemMap extends StoreItemMap = StoreItemMap> = {
 /** Atomic actions that can be provided via the `extended` slot. */
 export type AtomicActions<itemMap extends StoreItemMap = StoreItemMap> = {
   update: Update<itemMap>
+  /** Optional single-operation fast path for recording expiring replay keys. */
+  tryClaim?: TryClaim<itemMap> | undefined
 }
 
 /**
@@ -84,6 +102,42 @@ export type AtomicStore<itemMap extends StoreItemMap = StoreItemMap> = Store<
   AtomicActions<itemMap>
 >
 
+/**
+ * Attempts to atomically record first use of a replay key through its expiry.
+ *
+ * Returns `true` when this call recorded the key and `false` when it was already
+ * recorded and unexpired. `expires` is a Unix timestamp in milliseconds.
+ * Uses the adapter's optimized primitive when available and otherwise falls
+ * back to {@link AtomicStore.update}.
+ */
+export function tryClaim<itemMap extends StoreItemMap, key extends keyof itemMap & string>(
+  store: AtomicStore<itemMap>,
+  key: key,
+  expires: number,
+): MaybePromise<boolean> {
+  if (store.tryClaim) return store.tryClaim(key, expires)
+  return store.update(key, (current) => {
+    if (current !== null && (!isReplayMarker(current) || current.expires > Date.now()))
+      return { op: 'noop', result: false }
+    return {
+      op: 'set',
+      value: { expires, type: 'mppx:replay' } as itemMap[key],
+      result: true,
+    }
+  })
+}
+
+function isReplayMarker(value: unknown): value is ReplayMarker {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'expires' in value &&
+    typeof value.expires === 'number' &&
+    'type' in value &&
+    value.type === 'mppx:replay'
+  )
+}
+
 /** Options shared by store constructors. */
 export type Options = {
   /** Prefix prepended to every backing store key. */
@@ -127,6 +181,13 @@ function withKeyPrefix(store: Store | AtomicStore, keyPrefix = ''): Store | Atom
           },
         }
       : {}),
+    ...('tryClaim' in store && typeof store.tryClaim === 'function'
+      ? {
+          tryClaim(key: string, expires: number) {
+            return store.tryClaim!(prefixedKey(key), expires)
+          },
+        }
+      : {}),
   } satisfies Store | AtomicStore)
 
   const cachedByPrefix = keyPrefixCache.get(store) ?? new Map<string, Store | AtomicStore>()
@@ -226,6 +287,13 @@ export function memory(options?: memory.Options): AtomicStore {
         if (change.op === 'delete') store.delete(key)
         return change.result
       },
+      tryClaim(key: string, expires: number) {
+        const current = store.has(key) ? Json.parse(store.get(key)!) : null
+        if (current !== null && (!isReplayMarker(current) || current.expires > Date.now()))
+          return false
+        store.set(key, Json.stringify({ expires, type: 'mppx:replay' }))
+        return true
+      },
     },
     options,
   )