mppx 0.8.14 → 0.8.17

package/src/server/Mppx.test.ts

@@ -3,7 +3,7 @@ import * as http from 'node:http'
 import { Challenge, Credential, Errors, Method, Receipt, z } from 'mppx'
 import {
   Mppx as Mppx_client,
-  sessionLegacy as tempo_session_client,
+  session as tempo_session_client,
   tempo as tempo_client,
 } from 'mppx/client'
 import { Types as evm_Types } from 'mppx/evm'
@@ -12,7 +12,6 @@ import { Header as x402_Header, Types as x402_Types, type PaymentPayload } from
 import { getTransactionReceipt } from 'viem/actions'
 import { describe, expect, test, vi } from 'vp/test'
 import * as Http from '~test/Http.js'
-import { deployEscrow } from '~test/tempo/legacy/session.js'
 import { accounts, asset, client } from '~test/tempo/viem.js'
 
 import type { SessionReceipt } from '../tempo/session/precompile/Protocol.js'
@@ -60,6 +59,82 @@ describe('create', () => {
   })
 })
 
+describe('multi-method intent handler', () => {
+  test('composes all methods sharing an intent into a single handler', async () => {
+    const schema = {
+      credential: { payload: z.object({ sig: z.string() }) },
+      request: z.object({ amount: z.string(), currency: z.string() }),
+    }
+
+    const method1 = Method.toServer(Method.from({ name: 'foo', intent: 'charge', schema }), {
+      defaults: { currency: 'usd' },
+      verify: async () => ({
+        method: 'foo',
+        status: 'success' as const,
+        reference: '0x1',
+        timestamp: new Date().toISOString(),
+      }),
+    })
+    const method2 = Method.toServer(Method.from({ name: 'bar', intent: 'charge', schema }), {
+      defaults: { currency: 'eur' },
+      verify: async () => ({
+        method: 'bar',
+        status: 'success' as const,
+        reference: '0x2',
+        timestamp: new Date().toISOString(),
+      }),
+    })
+
+    const mppx = Mppx.create({ methods: [method1, method2], secretKey, realm })
+
+    expect(typeof mppx.charge).toBe('function')
+
+    const result = await (mppx as any).charge({ amount: '100' })(new Request('http://localhost'))
+    expect(result.status).toBe(402)
+
+    const wwwAuth = result.challenge.headers.get('www-authenticate')
+    expect(wwwAuth).toContain('method="foo"')
+    expect(wwwAuth).toContain('method="bar"')
+  })
+
+  test('single method with unique intent gets direct handler', async () => {
+    const schema = {
+      credential: { payload: z.object({ sig: z.string() }) },
+      request: z.object({ amount: z.string(), currency: z.string() }),
+    }
+
+    const method1 = Method.toServer(Method.from({ name: 'foo', intent: 'charge', schema }), {
+      defaults: { currency: 'usd' },
+      verify: async () => ({
+        method: 'foo',
+        status: 'success' as const,
+        reference: '0x1',
+        timestamp: new Date().toISOString(),
+      }),
+    })
+    const method2 = Method.toServer(Method.from({ name: 'bar', intent: 'session', schema }), {
+      defaults: { currency: 'usd' },
+      verify: async () => ({
+        method: 'bar',
+        status: 'success' as const,
+        reference: '0x2',
+        timestamp: new Date().toISOString(),
+      }),
+    })
+
+    const mppx = Mppx.create({ methods: [method1, method2], secretKey, realm })
+
+    const result = await (mppx as any).charge({ amount: '100', currency: 'usd' })(
+      new Request('http://localhost'),
+    )
+    expect(result.status).toBe(402)
+
+    const wwwAuth = result.challenge.headers.get('www-authenticate')
+    expect(wwwAuth).toContain('method="foo"')
+    expect(wwwAuth).not.toContain('method="bar"')
+  })
+})
+
 describe('request handler', () => {
   test('returns 402 when no Authorization header', async () => {
     const handler = Mppx.create({ methods: [method], realm, secretKey })
@@ -1466,6 +1541,131 @@ describe('server events', () => {
     expect(events).toEqual(['success:tx-standalone:undefined:/standalone'])
   })
 
+  test('per-method onPaymentSuccess hook fires on successful payment', async () => {
+    const calls: string[] = []
+    const serverMethod = Method.toServer(eventCharge, {
+      onPaymentSuccess: async ({ receipt }) => {
+        calls.push(receipt.reference)
+      },
+      async verify() {
+        return receipt('tx-hook')
+      },
+    })
+    const handler = Mppx.create({ methods: [serverMethod], realm, secretKey })
+
+    const challenge = await handler.charge(options())(new Request('https://example.com/resource'))
+    if (challenge.status !== 402) throw new Error()
+    await handler.verifyCredential(
+      Credential.from({
+        challenge: Challenge.fromResponse(challenge.challenge),
+        payload: { token: 'valid' },
+      }),
+      { request: options() },
+    )
+
+    expect(calls).toEqual(['tx-hook'])
+  })
+
+  test('onPaymentSuccess does not fire for a different method name', async () => {
+    const hookCalls: string[] = []
+
+    const methodWithHook = Method.toServer(eventCharge, {
+      onPaymentSuccess: async ({ receipt }) => {
+        hookCalls.push(receipt.reference)
+      },
+      async verify() {
+        return receipt('tx-a')
+      },
+    })
+    const otherName = Method.from({ name: 'other', intent: 'charge', schema: eventCharge.schema })
+    const methodWithoutHook = Method.toServer(otherName, {
+      async verify() {
+        return receipt('tx-b')
+      },
+    })
+
+    const handler = Mppx.create({ methods: [methodWithHook, methodWithoutHook], realm, secretKey })
+
+    // Pay the method WITHOUT the hook
+    const challenge = await handler.compose(['other/charge', options()])(
+      new Request('https://example.com'),
+    )
+    if (challenge.status !== 402) throw new Error()
+    await handler.verifyCredential(
+      Credential.from({
+        challenge: Challenge.fromResponse(challenge.challenge),
+        payload: { token: 'valid' },
+      }),
+      { request: options() },
+    )
+
+    expect(hookCalls).toEqual([])
+  })
+
+  test('onPaymentSuccess does not fire for a different intent', async () => {
+    const hookCalls: string[] = []
+
+    const chargeMethod = Method.toServer(eventCharge, {
+      onPaymentSuccess: async ({ receipt }) => {
+        hookCalls.push(receipt.reference)
+      },
+      async verify() {
+        return receipt('tx-charge')
+      },
+    })
+    const sessionSchema = Method.from({
+      name: 'mock',
+      intent: 'session',
+      schema: eventCharge.schema,
+    })
+    const sessionMethod = Method.toServer(sessionSchema, {
+      async verify() {
+        return receipt('tx-session')
+      },
+    })
+
+    const handler = Mppx.create({ methods: [chargeMethod, sessionMethod], realm, secretKey })
+
+    // Pay the session method - charge hook should NOT fire
+    const challenge = await handler.session(options())(new Request('https://example.com'))
+    if (challenge.status !== 402) throw new Error()
+    await handler.verifyCredential(
+      Credential.from({
+        challenge: Challenge.fromResponse(challenge.challenge),
+        payload: { token: 'valid' },
+      }),
+      { request: options() },
+    )
+
+    expect(hookCalls).toEqual([])
+  })
+
+  test('per-method onPaymentSuccess hook errors do not propagate', async () => {
+    const serverMethod = Method.toServer(eventCharge, {
+      onPaymentSuccess: async () => {
+        throw new Error('hook failure')
+      },
+      async verify() {
+        return receipt('tx-error')
+      },
+    })
+    const handler = Mppx.create({ methods: [serverMethod], realm, secretKey })
+
+    const first = await handler.charge(options())(new Request('https://example.com/resource'))
+    expect(first.status).toBe(402)
+    if (first.status !== 402) throw new Error()
+
+    const result = await handler.verifyCredential(
+      Credential.from({
+        challenge: Challenge.fromResponse(first.challenge),
+        payload: { token: 'valid' },
+      }),
+      { request: options() },
+    )
+
+    expect(result.reference).toBe('tx-error')
+  })
+
   test('emits payment failure from standalone verifyCredential failures', async () => {
     const events: string[] = []
     const capturedRequest = {
@@ -1901,10 +2101,10 @@ describe('compose', () => {
     },
   })
 
-  const legacySessionMethod = Method.toServer(mockSession, {
-    alias: 'sessionLegacy',
+  const alternateSessionMethod = Method.toServer(mockSession, {
+    alias: 'alternateSession',
     async verify() {
-      return mockReceipt('v1')
+      return mockReceipt('alternate')
     },
   })
 
@@ -1947,9 +2147,9 @@ describe('compose', () => {
     unitType: 'request',
   }
 
-  const legacySessionChallengeOpts = {
+  const alternateSessionChallengeOpts = {
     ...sessionChallengeOpts,
-    methodDetails: { sessionProtocol: 'v1' },
+    methodDetails: { sessionProtocol: 'alternate' },
   }
 
   test('returns 402 with multiple WWW-Authenticate headers when no credential', async () => {
@@ -1968,165 +2168,694 @@ describe('compose', () => {
     expect(wwwAuth).toContain('method="beta"')
   })
 
-  test('broadcasts duplicate tempo/session variants in compose order', async () => {
+  test('selectOffers filters by method, configured request, and incoming request', async () => {
+    const challenged: string[] = []
+    const input = new Request('https://example.com/resource?cards=disabled', {
+      body: 'request body',
+      method: 'POST',
+    })
     const mppx = Mppx.create({
-      methods: [tip1034SessionMethod, legacySessionMethod],
+      methods: [alphaMethod, betaMethod],
       realm,
       secretKey,
+      async selectOffers(offers, { request }) {
+        expect(request).not.toBe(input)
+        expect(await request.text()).toBe('request body')
+        expect(offers).toMatchObject([
+          {
+            key: 'alpha/charge',
+            method: { intent: 'charge', name: 'alpha' },
+            request: { amount: challengeOpts.amount },
+          },
+          {
+            key: 'beta/charge',
+            method: { intent: 'charge', name: 'beta' },
+            request: { amount: '50' },
+          },
+        ])
+
+        if (new URL(request.url).searchParams.get('cards') === 'disabled')
+          return offers.filter(
+            (offer) => offer.method.name !== 'beta' || BigInt(offer.request.amount) >= 100n,
+          )
+        return offers
+      },
+    })
+    mppx.onChallengeCreated(({ method }) => {
+      challenged.push(method.name)
     })
 
     const result = await mppx.compose(
-      [mppx.tempo.session, sessionChallengeOpts],
-      [mppx.tempo.sessionLegacy, legacySessionChallengeOpts],
-    )(new Request('https://example.com/resource'))
+      [alphaMethod, challengeOpts],
+      [betaMethod, { ...challengeOpts, amount: '50' }],
+    )(input)
 
     expect(result.status).toBe(402)
     if (result.status !== 402) throw new Error()
+    expect(
+      Challenge.fromResponseList(result.challenge).map((challenge) => challenge.method),
+    ).toEqual(['alpha'])
+    expect(challenged).toEqual(['alpha'])
+    expect(input.bodyUsed).toBe(false)
+  })
+
+  test('offer selectors receive deeply immutable method and request snapshots', async () => {
+    const guardedSession = Method.toServer(mockSession, {
+      canOffer({ request }) {
+        expect(Object.isFrozen(request)).toBe(true)
+        expect(Object.isFrozen(request.methodDetails)).toBe(true)
+        expect(Reflect.set(request.methodDetails, 'sessionProtocol', 'changed')).toBe(false)
+        return true
+      },
+      async verify() {
+        return mockReceipt('v2')
+      },
+    })
+    const mppx = Mppx.create({
+      methods: [guardedSession],
+      realm,
+      secretKey,
+      selectOffers(offers) {
+        const offer = offers[0]!
+        expect(Object.isFrozen(offers)).toBe(true)
+        expect(Object.isFrozen(offer)).toBe(true)
+        expect(Object.isFrozen(offer.method)).toBe(true)
+        expect(Object.keys(offer.method)).toEqual(['intent', 'name'])
+        expect(Object.isFrozen(offer.request)).toBe(true)
+        expect(Object.isFrozen(offer.request.methodDetails)).toBe(true)
+        expect(Reflect.set(offer.method, 'name', 'changed')).toBe(false)
+        expect(Reflect.set(offer.request.methodDetails, 'sessionProtocol', 'changed')).toBe(false)
+        return offers
+      },
+    })
+    const handler = mppx.compose([guardedSession, sessionChallengeOpts])
 
-    const challenges = Challenge.fromResponseList(result.challenge)
-    expect(challenges.map((challenge) => challenge.request.methodDetails)).toEqual([
-      { sessionProtocol: 'v2' },
-      { sessionProtocol: 'v1' },
-    ])
+    for (let call = 0; call < 2; call++) {
+      const result = await handler(new Request('https://example.com/resource'))
+      expect(result.status).toBe(402)
+      if (result.status !== 402) throw new Error()
+      const challenge = Challenge.fromResponse(result.challenge)
+      expect(challenge.method).toBe('tempo')
+      expect(challenge.request.methodDetails).toEqual({ sessionProtocol: 'v2' })
+    }
   })
 
-  test('keeps duplicate tempo/session variants when Accept-Payment allows tempo/session', async () => {
+  test.each(['consumed', 'locked'] as const)(
+    'offer hooks preserve request metadata when the upstream body is $state',
+    async (state) => {
+      const hookInputs: Request[] = []
+      const guardedBeta = Method.toServer(mockChargeB, {
+        async canOffer({ input }) {
+          hookInputs.push(input)
+          expect(await input.text()).toBe('')
+          return true
+        },
+        async verify() {
+          return mockReceipt('beta')
+        },
+      })
+      const input = new Request('https://example.com/resource?source=upstream', {
+        body: 'request body',
+        headers: { 'X-Request-Id': 'request-1' },
+        method: 'POST',
+      })
+      const reader = state === 'locked' ? input.body!.getReader() : undefined
+      if (state === 'consumed') await input.text()
+      const mppx = Mppx.create({
+        methods: [guardedBeta],
+        realm,
+        secretKey,
+        async selectOffers(offers, { request }) {
+          hookInputs.push(request)
+          expect(await request.text()).toBe('')
+          return offers
+        },
+      })
+
+      try {
+        const result = await mppx.compose([guardedBeta, challengeOpts])(input)
+        expect(result.status).toBe(402)
+      } finally {
+        reader?.releaseLock()
+      }
+
+      expect(hookInputs).toHaveLength(2)
+      for (const hookInput of hookInputs) {
+        expect(hookInput).not.toBe(input)
+        expect(hookInput.method).toBe('POST')
+        expect(hookInput.headers.get('X-Request-Id')).toBe('request-1')
+        expect(new URL(hookInput.url).searchParams.get('source')).toBe('upstream')
+      }
+    },
+  )
+
+  test('method canOffer runs before selectOffers with offer and upstream request context', async () => {
+    const calls: string[] = []
+    const guardedBeta = Method.toServer(mockChargeB, {
+      async canOffer({ input, request }) {
+        calls.push('canOffer')
+        expect(input).not.toBe(upstreamRequest)
+        expect(await input.text()).toBe('request body')
+        expect(request).toEqual({
+          amount: '50',
+          currency: challengeOpts.currency,
+          decimals: challengeOpts.decimals,
+          recipient: challengeOpts.recipient,
+        })
+        return BigInt(request.amount) >= 100n
+      },
+      async verify() {
+        return mockReceipt('beta')
+      },
+    })
+    const upstreamRequest = new Request('https://example.com/resource', {
+      body: 'request body',
+      method: 'POST',
+    })
     const mppx = Mppx.create({
-      methods: [tip1034SessionMethod, legacySessionMethod],
+      methods: [alphaMethod, guardedBeta],
       realm,
       secretKey,
+      selectOffers(offers) {
+        calls.push('selectOffers')
+        expect(offers.map((offer) => offer.method.name)).toEqual(['alpha'])
+        return offers
+      },
     })
 
     const result = await mppx.compose(
-      [mppx.tempo.session, sessionChallengeOpts],
-      [mppx.tempo.sessionLegacy, legacySessionChallengeOpts],
-    )(
-      new Request('https://example.com/resource', {
-        headers: { 'Accept-Payment': 'tempo/session' },
-      }),
-    )
+      [alphaMethod, challengeOpts],
+      [guardedBeta, { ...challengeOpts, amount: '50' }],
+    )(upstreamRequest)
 
     expect(result.status).toBe(402)
     if (result.status !== 402) throw new Error()
+    expect(
+      Challenge.fromResponseList(result.challenge).map((challenge) => challenge.method),
+    ).toEqual(['alpha'])
+    expect(calls).toEqual(['canOffer', 'selectOffers'])
+    expect(upstreamRequest.bodyUsed).toBe(false)
+  })
+
+  test('method canOffer evaluates each configured offer without selectOffers', async () => {
+    const amounts: string[] = []
+    const guardedBeta = Method.toServer(mockChargeB, {
+      canOffer({ request }) {
+        amounts.push(request.amount)
+        return BigInt(request.amount) >= 100n
+      },
+      async verify() {
+        return mockReceipt('beta')
+      },
+    })
+    const mppx = Mppx.create({ methods: [guardedBeta], realm, secretKey })
 
-    expect(Challenge.fromResponseList(result.challenge)).toHaveLength(2)
+    const handler = mppx.compose(
+      [guardedBeta, { ...challengeOpts, amount: '50' }],
+      [guardedBeta, { ...challengeOpts, amount: '100' }],
+    )
+    expect(handler._internal?.offers).toHaveLength(2)
+
+    const result = await handler(new Request('https://example.com/resource'))
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+    expect(amounts).toEqual(['50', '100'])
+    expect(
+      Challenge.fromResponseList(result.challenge).map((challenge) => challenge.request.amount),
+    ).toEqual(['100'])
   })
 
-  test('uses TIP-1034 as the bare tempo/session handler regardless of registration order', async () => {
-    const mppx = Mppx.create({
-      methods: [legacySessionMethod, tip1034SessionMethod],
-      realm,
-      secretKey,
+  test('static compose applies method canOffer', async () => {
+    const guardedBeta = Method.toServer(mockChargeB, {
+      canOffer: () => false,
+      async verify() {
+        return mockReceipt('beta')
+      },
     })
+    const mppx = Mppx.create({ methods: [alphaMethod, guardedBeta], realm, secretKey })
 
-    const result = await mppx.compose([mppx.tempo.session, sessionChallengeOpts])(
-      new Request('https://example.com/resource'),
-    )
+    const result = await Mppx.compose(
+      mppx.alpha.charge(challengeOpts),
+      mppx.beta.charge(challengeOpts),
+    )(new Request('https://example.com/resource'))
 
     expect(result.status).toBe(402)
     if (result.status !== 402) throw new Error()
-    expect(Challenge.fromResponse(result.challenge).request.methodDetails).toEqual({
-      sessionProtocol: 'v2',
-    })
+    expect(
+      Challenge.fromResponseList(result.challenge).map((challenge) => challenge.method),
+    ).toEqual(['alpha'])
   })
 
-  test('rejects cross-protocol tempo/session credential replay', async () => {
-    const mppx = Mppx.create({
-      methods: [tip1034SessionMethod, legacySessionMethod],
-      realm,
-      secretKey,
+  test('method canOffer does not gate a direct method handler', async () => {
+    const canOffer = vi.fn(() => false)
+    const guardedAlpha = Method.toServer(mockChargeA, {
+      canOffer,
+      async verify() {
+        return mockReceipt('alpha')
+      },
     })
-    const tip1034ChallengeResponse = await mppx.compose([mppx.tempo.session, sessionChallengeOpts])(
-      new Request('https://example.com/resource'),
-    )
-    expect(tip1034ChallengeResponse.status).toBe(402)
-    if (tip1034ChallengeResponse.status !== 402) throw new Error()
-    const tip1034Challenge = Challenge.fromResponse(tip1034ChallengeResponse.challenge)
+    const mppx = Mppx.create({ methods: [guardedAlpha], realm, secretKey })
 
-    const credential = Credential.serialize({
-      challenge: tip1034Challenge,
-      payload: { token: 'valid' },
-    })
-    const legacyResult = await mppx.compose([mppx.tempo.sessionLegacy, legacySessionChallengeOpts])(
-      new Request('https://example.com/resource', {
-        headers: { Authorization: credential },
-      }),
+    const result = await mppx.alpha.charge(challengeOpts)(
+      new Request('https://example.com/resource'),
     )
 
-    expect(legacyResult.status).toBe(402)
+    expect(result.status).toBe(402)
+    expect(canOffer).not.toHaveBeenCalled()
   })
 
-  test('verifyCredential dispatches duplicate tempo/session variants by sessionProtocol', async () => {
-    const mppx = Mppx.create({
-      methods: [tip1034SessionMethod, legacySessionMethod],
-      realm,
-      secretKey,
+  test('method canOffer filters before preflight and authorize hooks', async () => {
+    const authorize = vi.fn()
+    const preflight = vi.fn()
+    const guardedBeta = Method.toServer(mockChargeB, {
+      async authorize() {
+        authorize()
+        return undefined
+      },
+      canOffer: () => false,
+      async preflight() {
+        preflight()
+        return undefined
+      },
+      async verify() {
+        return mockReceipt('beta')
+      },
     })
-    const tip1034Challenge = await mppx.challenge.tempo.session(sessionChallengeOpts)
-    const legacyChallenge = await mppx.challenge.tempo.sessionLegacy(legacySessionChallengeOpts)
+    const mppx = Mppx.create({ methods: [alphaMethod, guardedBeta], realm, secretKey })
 
-    const tip1034Receipt = await mppx.verifyCredential(
-      Credential.serialize({
-        challenge: tip1034Challenge,
-        payload: { token: 'valid' },
-      }),
-    )
-    const legacyReceipt = await mppx.verifyCredential(
-      Credential.serialize({
-        challenge: legacyChallenge,
-        payload: { token: 'valid' },
-      }),
-    )
+    const result = await mppx.compose(
+      [alphaMethod, challengeOpts],
+      [guardedBeta, challengeOpts],
+    )(new Request('https://example.com/resource'))
 
-    expect(tip1034Receipt.reference).toBe('tx-v2')
-    expect(legacyReceipt.reference).toBe('tx-v1')
+    expect(result.status).toBe(402)
+    expect(preflight).not.toHaveBeenCalled()
+    expect(authorize).not.toHaveBeenCalled()
   })
 
-  test('verifyCredential routes unmarked tempo/session challenges to legacy v1', async () => {
-    const mppx = Mppx.create({
-      methods: [legacySessionMethod, tip1034SessionMethod],
-      realm,
-      secretKey,
-    })
-    const unmarkedLegacyChallenge = await mppx.challenge.tempo.sessionLegacy({
-      ...legacySessionChallengeOpts,
-      methodDetails: {},
+  test.each([
+    {
+      canOffer: () => 'yes',
+      expected: 'canOffer() must return a boolean',
+      name: 'non-boolean result',
+    },
+    {
+      canOffer: () => false,
+      expected: 'No payment offers are available for this request',
+      name: 'no eligible offers',
+    },
+  ])('rejects invalid method offer availability: $name', async ({ canOffer, expected }) => {
+    const guardedAlpha = Method.toServer(mockChargeA, {
+      canOffer: canOffer as never,
+      async verify() {
+        return mockReceipt('alpha')
+      },
     })
+    const mppx = Mppx.create({ methods: [guardedAlpha], realm, secretKey })
 
     await expect(
-      mppx.verifyCredential(
-        Credential.serialize({
-          challenge: unmarkedLegacyChallenge,
-          payload: { token: 'valid' },
-        }),
-      ),
-    ).resolves.toMatchObject({ reference: 'tx-v1' })
+      mppx.compose([guardedAlpha, challengeOpts])(new Request('https://example.com/resource')),
+    ).rejects.toThrow(expected)
   })
 
-  test('verifyCredential rejects unknown tempo/session protocol markers', async () => {
-    const mppx = Mppx.create({
-      methods: [legacySessionMethod, tip1034SessionMethod],
-      realm,
-      secretKey,
-    })
-    const challenge = await mppx.challenge.tempo.session({
-      ...sessionChallengeOpts,
-      methodDetails: { sessionProtocol: 'future' },
+  test('propagates method canOffer rejections', async () => {
+    const error = new Error('method offer selection failed')
+    const guardedAlpha = Method.toServer(mockChargeA, {
+      async canOffer() {
+        throw error
+      },
+      async verify() {
+        return mockReceipt('alpha')
+      },
     })
+    const mppx = Mppx.create({ methods: [guardedAlpha], realm, secretKey })
 
     await expect(
-      mppx.verifyCredential(Credential.serialize({ challenge, payload: { token: 'valid' } })),
-    ).rejects.toThrow('no registered method for tempo/session')
+      mppx.compose([guardedAlpha, challengeOpts])(new Request('https://example.com/resource')),
+    ).rejects.toBe(error)
   })
 
-  test('returns composed x402 challenge headers when no credential', async () => {
-    const mppx = Mppx.create({ methods: [x402Method], realm, secretKey })
+  test('method canOffer does not prevent redemption of an issued offer', async () => {
+    const canOffer = vi.fn(() => false)
+    const guardedBeta = Method.toServer(mockChargeB, {
+      canOffer,
+      async verify() {
+        return mockReceipt('beta')
+      },
+    })
+    const mppx = Mppx.create({ methods: [guardedBeta], realm, secretKey })
+    const challenge = await mppx.challenge.beta.charge(challengeOpts)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
 
-    const result = await mppx.compose(['evm/charge', { amount: '0.01' }])(
-      new Request('https://example.com/resource'),
+    const result = await mppx.compose([guardedBeta, challengeOpts])(
+      new Request('https://example.com/resource', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
     )
 
-    expect(result.status).toBe(402)
+    expect(result.status).toBe(200)
+    expect(canOffer).not.toHaveBeenCalled()
+  })
+
+  test('selectOffers does not prevent redemption of a previously issued offer', async () => {
+    let selectionCount = 0
+    const mppx = Mppx.create({
+      methods: [alphaMethod, betaMethod],
+      realm,
+      secretKey,
+      selectOffers(offers, { request }) {
+        selectionCount++
+        return request.headers.has('X-Hide-Beta')
+          ? offers.filter((offer) => offer.method.name !== 'beta')
+          : offers
+      },
+    })
+    const handler = mppx.compose([alphaMethod, challengeOpts], [betaMethod, challengeOpts])
+    const challengeResult = await handler(new Request('https://example.com/resource'))
+    expect(challengeResult.status).toBe(402)
+    if (challengeResult.status !== 402) throw new Error()
+    const betaChallenge = Challenge.fromResponseList(challengeResult.challenge).find(
+      (challenge) => challenge.method === 'beta',
+    )!
+    const credential = Credential.from({
+      challenge: betaChallenge,
+      payload: { token: 'valid' },
+    })
+
+    const result = await handler(
+      new Request('https://example.com/resource', {
+        headers: {
+          Authorization: Credential.serialize(credential),
+          'X-Hide-Beta': 'true',
+        },
+      }),
+    )
+
+    expect(result.status).toBe(200)
+    expect(selectionCount).toBe(1)
+  })
+
+  test.each(['malformed', 'unmatched'] as const)(
+    'applies selectOffers before rejecting a $kind payment credential',
+    async (kind) => {
+      let selectionCount = 0
+      const mppx = Mppx.create({
+        methods: [alphaMethod, betaMethod],
+        realm,
+        secretKey,
+        selectOffers(offers) {
+          selectionCount++
+          return offers.filter((offer) => offer.method.name === 'beta')
+        },
+      })
+      const authorization =
+        kind === 'malformed'
+          ? 'Payment invalid'
+          : Credential.serialize(
+              Credential.from({
+                challenge: {
+                  ...(await mppx.challenge.alpha.charge(challengeOpts)),
+                  method: 'unknown',
+                },
+                payload: { token: 'invalid' },
+              }),
+            )
+
+      const result = await mppx.compose(
+        [alphaMethod, challengeOpts],
+        [betaMethod, challengeOpts],
+      )(
+        new Request('https://example.com/resource', {
+          headers: { Authorization: authorization },
+        }),
+      )
+
+      expect(result.status).toBe(402)
+      if (result.status !== 402) throw new Error()
+      expect(Challenge.fromResponse(result.challenge).method).toBe('beta')
+      expect(selectionCount).toBe(1)
+    },
+  )
+
+  test.each([
+    {
+      expected: 'return an array',
+      name: 'non-array result',
+      select: () => null,
+    },
+    {
+      expected: 'select at least one offer',
+      name: 'empty selection',
+      select: (offers: readonly unknown[]) => offers.slice(0, 0),
+    },
+    {
+      expected: 'only offers from its input array',
+      name: 'copied offer',
+      select: (offers: readonly unknown[]) => [{ ...(offers[0] as object) }],
+    },
+    {
+      expected: 'preserve offer order',
+      name: 'duplicate offer',
+      select: (offers: readonly unknown[]) => [offers[0], offers[0]],
+    },
+    {
+      expected: 'preserve offer order',
+      name: 'reordered offers',
+      select: (offers: readonly unknown[]) => [offers[1], offers[0]],
+    },
+  ])('rejects invalid selectOffers result: $name', async ({ expected, select }) => {
+    const mppx = Mppx.create({
+      methods: [alphaMethod, betaMethod],
+      realm,
+      secretKey,
+      selectOffers: select as never,
+    })
+    const handler = mppx.compose([alphaMethod, challengeOpts], [betaMethod, challengeOpts])
+
+    await expect(handler(new Request('https://example.com/resource'))).rejects.toThrow(expected)
+  })
+
+  test('retains all configured offers as discovery metadata when selectOffers is dynamic', () => {
+    const mppx = Mppx.create({
+      methods: [alphaMethod, betaMethod],
+      realm,
+      secretKey,
+      selectOffers: (offers) => offers.slice(0, 1),
+    })
+    const configured = mppx.compose([alphaMethod, challengeOpts], [betaMethod, challengeOpts])
+
+    expect(configured._internal?.offers).toMatchObject([
+      {
+        _canonicalRequest: {
+          amount: challengeOpts.amount,
+          currency: challengeOpts.currency,
+          recipient: challengeOpts.recipient,
+        },
+        intent: 'charge',
+        name: 'alpha',
+      },
+      {
+        _canonicalRequest: {
+          amount: challengeOpts.amount,
+          currency: challengeOpts.currency,
+          recipient: challengeOpts.recipient,
+        },
+        intent: 'charge',
+        name: 'beta',
+      },
+    ])
+
+    const custom = async () =>
+      ({
+        status: 402,
+        challenge: new Response(null, { status: 402 }),
+      }) as const
+    const composed = Mppx.compose(mppx.alpha.charge(challengeOpts), custom)
+    expect(composed._internal?.offers).toMatchObject([{ intent: 'charge', name: 'alpha' }])
+  })
+
+  test('does not run preflight or authorize hooks for filtered offers', async () => {
+    const authorize = vi.fn()
+    const preflight = vi.fn()
+    const filteredMethod = Method.toServer(mockChargeB, {
+      async authorize() {
+        authorize()
+        return undefined
+      },
+      async preflight() {
+        preflight()
+        return undefined
+      },
+      async verify() {
+        return mockReceipt('beta')
+      },
+    })
+    const mppx = Mppx.create({
+      methods: [alphaMethod, filteredMethod],
+      realm,
+      secretKey,
+      selectOffers: (offers) => offers.filter((offer) => offer.method.name !== 'beta'),
+    })
+
+    const result = await mppx.compose(
+      [alphaMethod, challengeOpts],
+      [filteredMethod, challengeOpts],
+    )(new Request('https://example.com/resource'))
+
+    expect(result.status).toBe(402)
+    expect(preflight).not.toHaveBeenCalled()
+    expect(authorize).not.toHaveBeenCalled()
+  })
+
+  test('selectOffers distinguishes aliased methods that share a canonical key', async () => {
+    const mppx = Mppx.create({
+      methods: [tip1034SessionMethod, alternateSessionMethod],
+      realm,
+      secretKey,
+      selectOffers(offers) {
+        expect(offers.map((offer) => offer.key)).toEqual(['tempo/session', 'tempo/session'])
+        expect(offers.map((offer) => offer.method.alias)).toEqual([undefined, 'alternateSession'])
+        expect(offers.map((offer) => offer.request.methodDetails)).toEqual([
+          { sessionProtocol: 'v2' },
+          { sessionProtocol: 'alternate' },
+        ])
+        return offers.filter((offer) => offer.method.alias === 'alternateSession')
+      },
+    })
+
+    const result = await mppx.compose(
+      [mppx.tempo.session, sessionChallengeOpts],
+      [mppx.tempo.alternateSession, alternateSessionChallengeOpts],
+    )(new Request('https://example.com/resource'))
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+    expect(Challenge.fromResponse(result.challenge).request.methodDetails).toEqual({
+      sessionProtocol: 'alternate',
+    })
+  })
+
+  test('selectOffers receives schema-transformed request values', async () => {
+    const transformedCharge = Method.from({
+      name: 'transformed',
+      intent: 'charge',
+      schema: {
+        credential: {
+          payload: z.object({ token: z.string() }),
+        },
+        request: z.pipe(
+          z.object({
+            amount: z.string(),
+            currency: z.string(),
+            decimals: z.number(),
+            recipient: z.string(),
+          }),
+          z.transform(({ amount, currency, decimals, recipient }) => ({
+            amount: String(Number(amount) * 10 ** decimals),
+            currency,
+            methodDetails: { decimals },
+            recipient,
+          })),
+        ),
+      },
+    })
+    const transformedMethod = Method.toServer(transformedCharge, {
+      async verify() {
+        return mockReceipt('transformed')
+      },
+    })
+    const mppx = Mppx.create({
+      methods: [transformedMethod],
+      realm,
+      secretKey,
+      selectOffers(offers) {
+        expect(offers[0]?.request).toEqual({
+          amount: '125',
+          currency: challengeOpts.currency,
+          methodDetails: { decimals: 2 },
+          recipient: challengeOpts.recipient,
+        })
+        return offers
+      },
+    })
+
+    const result = await mppx.compose([
+      transformedMethod,
+      { ...challengeOpts, amount: '1.25', decimals: 2 },
+    ])(new Request('https://example.com/resource'))
+
+    expect(result.status).toBe(402)
+  })
+
+  test('propagates selectOffers rejections', async () => {
+    const error = new Error('offer selection failed')
+    const mppx = Mppx.create({
+      methods: [alphaMethod],
+      realm,
+      secretKey,
+      async selectOffers() {
+        throw error
+      },
+    })
+
+    await expect(
+      mppx.compose([alphaMethod, challengeOpts])(new Request('https://example.com/resource')),
+    ).rejects.toBe(error)
+  })
+
+  test('broadcasts duplicate tempo/session variants in compose order', async () => {
+    const mppx = Mppx.create({
+      methods: [tip1034SessionMethod, alternateSessionMethod],
+      realm,
+      secretKey,
+    })
+
+    const result = await mppx.compose(
+      [mppx.tempo.session, sessionChallengeOpts],
+      [mppx.tempo.alternateSession, alternateSessionChallengeOpts],
+    )(new Request('https://example.com/resource'))
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    const challenges = Challenge.fromResponseList(result.challenge)
+    expect(challenges.map((challenge) => challenge.request.methodDetails)).toEqual([
+      { sessionProtocol: 'v2' },
+      { sessionProtocol: 'alternate' },
+    ])
+  })
+
+  test('keeps duplicate tempo/session variants when Accept-Payment allows tempo/session', async () => {
+    const mppx = Mppx.create({
+      methods: [tip1034SessionMethod, alternateSessionMethod],
+      realm,
+      secretKey,
+    })
+
+    const result = await mppx.compose(
+      [mppx.tempo.session, sessionChallengeOpts],
+      [mppx.tempo.alternateSession, alternateSessionChallengeOpts],
+    )(
+      new Request('https://example.com/resource', {
+        headers: { 'Accept-Payment': 'tempo/session' },
+      }),
+    )
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    expect(Challenge.fromResponseList(result.challenge)).toHaveLength(2)
+  })
+
+  test('returns composed x402 challenge headers when no credential', async () => {
+    const mppx = Mppx.create({ methods: [x402Method], realm, secretKey })
+
+    const result = await mppx.compose(['evm/charge', { amount: '0.01' }])(
+      new Request('https://example.com/resource'),
+    )
+
+    expect(result.status).toBe(402)
     if (result.status !== 402) throw new Error()
 
     expect(result.challenge.headers.get('WWW-Authenticate')).toContain('method="evm"')
@@ -2164,6 +2893,44 @@ describe('compose', () => {
     expect(paymentRequired.accepts.map((accepted) => accepted.amount)).toEqual(['10000'])
   })
 
+  test('selectOffers filters x402 challenge headers', async () => {
+    const mppx = Mppx.create({
+      methods: [alphaMethod, x402Method],
+      realm,
+      secretKey,
+      selectOffers: (offers) => offers.filter((offer) => offer.method.name !== 'evm'),
+    })
+
+    const result = await mppx.compose(
+      [alphaMethod, challengeOpts],
+      ['evm/charge', { amount: '0.01' }],
+    )(new Request('https://example.com/resource'))
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+    expect(
+      Challenge.fromResponseList(result.challenge).map((challenge) => challenge.method),
+    ).toEqual(['alpha'])
+    expect(result.challenge.headers.get(x402_Types.paymentRequiredHeader)).toBeNull()
+  })
+
+  test('method canOffer filters x402 challenge headers', async () => {
+    const guardedX402 = { ...x402Method, canOffer: () => false }
+    const mppx = Mppx.create({ methods: [alphaMethod, guardedX402], realm, secretKey })
+
+    const result = await mppx.compose(
+      [alphaMethod, challengeOpts],
+      [guardedX402, { amount: '0.01' }],
+    )(new Request('https://example.com/resource'))
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+    expect(
+      Challenge.fromResponseList(result.challenge).map((challenge) => challenge.method),
+    ).toEqual(['alpha'])
+    expect(result.challenge.headers.get(x402_Types.paymentRequiredHeader)).toBeNull()
+  })
+
   test('keeps pure x402 challenge headers when Payment auth challenges are present', async () => {
     const mppx = Mppx.create({ methods: [alphaMethod], realm, secretKey })
     const pureX402 = async () =>
@@ -2275,6 +3042,55 @@ describe('compose', () => {
     expect(challenges[0]?.method).toBe('beta')
   })
 
+  test('applies selectOffers before Accept-Payment negotiation', async () => {
+    const mppx = Mppx.create({
+      methods: [alphaMethod, betaMethod],
+      realm,
+      secretKey,
+      selectOffers: (offers) => offers.filter((offer) => offer.method.name !== 'beta'),
+    })
+
+    const result = await mppx.compose(
+      [alphaMethod, challengeOpts],
+      [betaMethod, challengeOpts],
+    )(
+      new Request('https://example.com/resource', {
+        headers: { 'Accept-Payment': 'beta/charge' },
+      }),
+    )
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+    expect(
+      Challenge.fromResponseList(result.challenge).map((challenge) => challenge.method),
+    ).toEqual(['alpha'])
+  })
+
+  test('applies method canOffer before Accept-Payment negotiation', async () => {
+    const guardedBeta = Method.toServer(mockChargeB, {
+      canOffer: () => false,
+      async verify() {
+        return mockReceipt('beta')
+      },
+    })
+    const mppx = Mppx.create({ methods: [alphaMethod, guardedBeta], realm, secretKey })
+
+    const result = await mppx.compose(
+      [alphaMethod, challengeOpts],
+      [guardedBeta, challengeOpts],
+    )(
+      new Request('https://example.com/resource', {
+        headers: { 'Accept-Payment': 'beta/charge' },
+      }),
+    )
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+    expect(
+      Challenge.fromResponseList(result.challenge).map((challenge) => challenge.method),
+    ).toEqual(['alpha'])
+  })
+
   test('filters compose x402 challenge headers using Accept-Payment', async () => {
     const mppx = Mppx.create({ methods: [alphaMethod, x402Method], realm, secretKey })
 
@@ -2429,6 +3245,34 @@ describe('compose', () => {
     expect(result.status).toBe(200)
   })
 
+  test('dispatches credentials to a nested composed handler', async () => {
+    const mppx = Mppx.create({ methods: [alphaMethod, betaMethod], realm, secretKey })
+    const handle = Mppx.compose(
+      mppx.alpha.charge(challengeOpts),
+      Mppx.compose(mppx.beta.charge(challengeOpts)),
+    )
+
+    const firstResult = await handle(new Request('https://example.com/resource'))
+    expect(firstResult.status).toBe(402)
+    if (firstResult.status !== 402) throw new Error()
+
+    const betaChallenge = Challenge.fromResponseList(firstResult.challenge).find(
+      (challenge) => challenge.method === 'beta',
+    )!
+    const credential = Credential.from({
+      challenge: betaChallenge,
+      payload: { token: 'valid' },
+    })
+
+    const result = await handle(
+      new Request('https://example.com/resource', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+
+    expect(result.status).toBe(200)
+  })
+
   test('returns 402 when credential method does not match any handler', async () => {
     const mppx = Mppx.create({ methods: [alphaMethod], realm, secretKey })
 
@@ -2797,6 +3641,64 @@ describe('compose', () => {
       expect(dataValues[1]!.config).toEqual({ providerB: true })
     })
 
+    test('selectOffers filters html payment options', async () => {
+      const mppx = Mppx.create({
+        methods: [alphaWithHtml, betaWithHtml],
+        realm,
+        secretKey,
+        selectOffers: (offers) => offers.filter((offer) => offer.method.name !== 'beta'),
+      })
+
+      const result = await mppx.compose(
+        [alphaWithHtml, challengeOpts],
+        [betaWithHtml, challengeOpts],
+      )(
+        new Request('https://example.com/resource', {
+          headers: { Accept: 'text/html' },
+        }),
+      )
+
+      expect(result.status).toBe(402)
+      if (result.status !== 402) throw new Error()
+      const body = await result.challenge.text()
+      expect(body).toContain('/alpha-bundle.js')
+      expect(body).not.toContain('/beta-bundle.js')
+      expect(body).not.toContain('role="tablist"')
+
+      const dataMatch = body.match(
+        /<script[^>]*id="__MPPX_DATA__"[^>]*type="application\/json"[^>]*>\s*([\s\S]*?)\s*<\/script>/s,
+      )
+      const dataMap = JSON.parse(dataMatch![1]!.replace(/\\u003c/g, '<'))
+      expect(Object.values(dataMap)).toMatchObject([{ label: 'alpha' }])
+    })
+
+    test('method canOffer filters html payment options', async () => {
+      const guardedBeta = Method.toServer(mockChargeB, {
+        canOffer: () => false,
+        html: htmlOptionsB,
+        async verify() {
+          return mockReceipt('beta')
+        },
+      })
+      const mppx = Mppx.create({ methods: [alphaWithHtml, guardedBeta], realm, secretKey })
+
+      const result = await mppx.compose(
+        [alphaWithHtml, challengeOpts],
+        [guardedBeta, challengeOpts],
+      )(
+        new Request('https://example.com/resource', {
+          headers: { Accept: 'text/html' },
+        }),
+      )
+
+      expect(result.status).toBe(402)
+      if (result.status !== 402) throw new Error()
+      const body = await result.challenge.text()
+      expect(body).toContain('/alpha-bundle.js')
+      expect(body).not.toContain('/beta-bundle.js')
+      expect(body).not.toContain('role="tablist"')
+    })
+
     test('returns html without tabs when single method has html', async () => {
       const mppx = Mppx.create({
         methods: [alphaWithHtml, betaMethod],
@@ -5594,15 +6496,13 @@ describe('verifyCredential', () => {
   })
 
   test('verifies real session open and voucher credentials created from 402 responses', async () => {
-    const escrowContract = await deployEscrow()
     const server = Mppx.create({
       methods: [
-        tempo.sessionLegacy({
+        tempo.session({
           store: Store.memory(),
           getClient: () => client,
           account: accounts[0],
           currency: asset,
-          escrowContract,
           chainId: client.chain!.id,
         }),
       ],
@@ -5622,7 +6522,7 @@ describe('verifyCredential', () => {
 
     const httpServer = await Http.createServer(async (req, res) => {
       const result = await Mppx.toNodeListener(
-        server.session({ amount: '1', unitType: 'request' }),
+        server.session({ amount: '1', suggestedDeposit: '10', unitType: 'request' }),
       )(req, res)
       if (result.status === 402) return
       res.end('OK')
@@ -5657,22 +6557,20 @@ describe('verifyCredential', () => {
   })
 
   test('verifyCredential charges repeated session voucher content requests when capturedRequest is provided', async () => {
-    const escrowContract = await deployEscrow()
     const server = Mppx.create({
       methods: [
-        tempo.sessionLegacy({
+        tempo.session({
           store: Store.memory(),
           getClient: () => client,
           account: accounts[0],
           currency: asset,
-          escrowContract,
           chainId: client.chain!.id,
         }),
       ],
       realm,
       secretKey,
     })
-    const route = server.session({ amount: '1', unitType: 'request' })
+    const route = server.session({ amount: '1', suggestedDeposit: '10', unitType: 'request' })
     const clientMppx = Mppx_client.create({
       polyfill: false,
       methods: [