mppx 0.8.14 → 0.8.17

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,
   )

package/src/attestation/Attestation.integration.test.ts

@@ -0,0 +1,208 @@
+import type { RequestListener } from 'node:http'
+
+import { Constants as MppConstants, Credential, Method, Receipt, z } from 'mppx'
+import * as Attestation from 'mppx/attestation'
+import * as Tap from 'mppx/attestation/tap'
+import * as WebBotAuth from 'mppx/attestation/web-bot-auth'
+import { Mppx as ClientMppx } from 'mppx/client'
+import { Mppx, Request as ServerRequest } from 'mppx/server'
+import { expect, test } from 'vp/test'
+import { jwkThumbprint, keyPair } from '~test/Attestation.js'
+import * as Http from '~test/Http.js'
+
+const method = Method.from({
+  name: 'test',
+  intent: 'charge',
+  schema: {
+    credential: { payload: z.object({ token: z.string() }) },
+    request: z.object({ amount: z.string(), currency: z.string(), recipient: z.string() }),
+  },
+})
+
+const clientMethod = Method.toClient(method, {
+  async createCredential({ challenge }) {
+    return Credential.serialize({ challenge, payload: { token: 'paid' } })
+  },
+})
+
+const serverMethod = Method.toServer(method, {
+  async verify({ credential }) {
+    if (credential.payload.token !== 'paid') throw new Error('Payment credential is invalid.')
+    return Receipt.from({
+      method: 'test',
+      reference: 'test-payment',
+      status: 'success',
+      timestamp: new Date().toISOString(),
+    })
+  },
+})
+
+const charge = {
+  amount: '1',
+  currency: 'USD',
+  expires: new Date(Date.now() + 60_000).toISOString(),
+  recipient: 'merchant',
+} as const
+
+test('composes TAP and the Web Bot Auth directory profile across an MPP payment retry', async () => {
+  const tapKeys = await keyPair()
+  const webBotAuthKeys = await keyPair()
+  const webBotAuthKeyId = await jwkThumbprint(webBotAuthKeys.publicKey)
+  const signatureAgent = 'https://agent.example'
+  const nonceStore = Attestation.Store.memory()
+  const verifiers = {
+    tap: Tap.Server.verifier({
+      keyResolver: ({ keyId }) => (keyId === 'tap-agent' ? tapKeys.publicKey : undefined),
+      nonceStore,
+    }),
+    webBotAuth: WebBotAuth.Server.verifier({
+      keyResolver: ({ keyId, signatureAgent: advertisedAgent }) =>
+        keyId === webBotAuthKeyId && advertisedAgent === signatureAgent
+          ? webBotAuthKeys.publicKey
+          : undefined,
+      maxAge: 60,
+      nonceStore,
+    }),
+  }
+  const seen = await createServer(verifiers, async (request, payments) => {
+    const result = await payments.charge(charge)(request)
+    return result.status === 402 ? result.challenge : result.withReceipt(new Response('paid'))
+  })
+
+  try {
+    const client = ClientMppx.create({
+      attestation: {
+        tap: Tap.Client.signer({
+          intent: Tap.Constants.intents.payment,
+          key: tapKeys.privateKey,
+          keyId: 'tap-agent',
+        }),
+        webBotAuth: WebBotAuth.Client.signer({
+          key: webBotAuthKeys.privateKey,
+          keyId: webBotAuthKeyId,
+          signatureAgent,
+        }),
+      },
+      methods: [clientMethod],
+      polyfill: false,
+    })
+
+    const response = await client.fetch(seen.server.url)
+    expect(response.status).toBe(200)
+    expect(await response.text()).toBe('paid')
+    expect(seen.requests).toEqual([false, true])
+
+    const attemptNonces = seen.signatureInputs.map((input) =>
+      [...input.matchAll(/nonce="([^"]+)"/g)].map((match) => match[1]),
+    )
+    expect(attemptNonces).toHaveLength(2)
+    for (const nonces of attemptNonces) {
+      expect(nonces).toHaveLength(2)
+      expect(new Set(nonces).size).toBe(1)
+      expect(nonces[0]).toMatch(/^[A-Za-z0-9_-]{86}$/)
+    }
+    expect(attemptNonces[0]![0]).not.toBe(attemptNonces[1]![0])
+  } finally {
+    seen.server.close()
+  }
+})
+
+test('requires every configured server attestation', async () => {
+  const keys = await keyPair()
+  const seen = await createServer(
+    {
+      tap: Tap.Server.verifier({
+        keyResolver: () => keys.publicKey,
+        nonceStore: Attestation.Store.memory(),
+      }),
+    },
+    async (request, payments) => {
+      const result = await payments.charge(charge)(request)
+      return result.status === 402 ? result.challenge : result.withReceipt(new Response('paid'))
+    },
+  )
+
+  try {
+    const response = await fetch(seen.server.url)
+    expect(response.status).toBe(403)
+    expect(await response.text()).toMatch(/tap.*required/)
+  } finally {
+    seen.server.close()
+  }
+})
+
+test('rejects an invalid server attestation before creating a payment challenge', async () => {
+  const trustedKeys = await keyPair()
+  const untrustedKeys = await keyPair()
+  const seen = await createServer(
+    {
+      tap: Tap.Server.verifier({
+        keyResolver: () => trustedKeys.publicKey,
+        nonceStore: Attestation.Store.memory(),
+      }),
+    },
+    async (request, payments) => {
+      const result = await payments.charge(charge)(request)
+      return result.status === 402 ? result.challenge : result.withReceipt(new Response('paid'))
+    },
+  )
+
+  try {
+    const signer = Tap.Client.signer({
+      intent: Tap.Constants.intents.payment,
+      key: untrustedKeys.privateKey,
+      keyId: 'tap-agent',
+    })
+    const request = await signer.sign(new Request(seen.server.url))
+    const response = await fetch(request)
+    expect(response.status).toBe(401)
+    expect(await response.text()).toMatch(/tap.*invalid/)
+    expect(seen.requests).toEqual([false])
+  } finally {
+    seen.server.close()
+  }
+})
+
+test('rejects empty client and server attestation maps', () => {
+  expect(() =>
+    ClientMppx.create({
+      attestation: {},
+      methods: [clientMethod],
+      polyfill: false,
+    }),
+  ).toThrow('Mppx client attestation must configure at least one signer.')
+  expect(() =>
+    Mppx.create({
+      attestation: {},
+      methods: [serverMethod],
+      realm: 'localhost',
+      secretKey: 'test-secret-key-test-secret-key-32',
+    }),
+  ).toThrow('Mppx server attestation must configure at least one verifier.')
+})
+
+async function createServer(
+  verifiers: Attestation.VerifierMap,
+  handler: (request: Request, payments: ReturnType<typeof createPayments>) => Promise<Response>,
+) {
+  const payments = createPayments(verifiers)
+  const requests: boolean[] = []
+  const signatureInputs: string[] = []
+  const listener = ServerRequest.toNodeListener(async (request) => {
+    requests.push(request.headers.has(MppConstants.Headers.authorization))
+    signatureInputs.push(request.headers.get(Attestation.Headers.signatureInput) ?? '')
+    return handler(request, payments)
+  })
+  const server = await Http.createServer(((request, response) =>
+    listener(request, response)) as RequestListener)
+  return { requests, server, signatureInputs }
+}
+
+function createPayments(attestation: Attestation.VerifierMap) {
+  return Mppx.create({
+    attestation,
+    methods: [serverMethod],
+    realm: 'localhost',
+    secretKey: 'test-secret-key-test-secret-key-32',
+  })
+}