mppx 0.5.11 → 0.5.13

package/src/server/Mppx.test.ts

@@ -127,6 +127,50 @@ describe('request handler', () => {
     expect(body.detail).not.toContain('rpc.example.com')
   })
 
+  test('returns 402 when challenge ID mismatch', async () => {
+    const wrongChallenge = Challenge.from({
+      id: 'wrong-id',
+      intent: 'charge',
+      method: 'tempo',
+      realm,
+      request: { amount: '1000', currency: asset, recipient: accounts[0].address },
+    })
+    const credential = Credential.from({
+      challenge: wrongChallenge,
+      payload: { signature: '0x123', type: 'transaction' },
+    })
+
+    const request = new Request('https://example.com/resource', {
+      headers: { Authorization: Credential.serialize(credential) },
+    })
+
+    const result = await Mppx.create({ methods: [method], realm, secretKey }).charge({
+      amount: '1000',
+      currency: asset,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: accounts[0].address,
+    })(request)
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    const body = (await result.challenge.json()) as object
+    expect({
+      ...body,
+      challengeId: '[challengeId]',
+      instance: '[instance]',
+    }).toMatchInlineSnapshot(`
+      {
+        "challengeId": "[challengeId]",
+        "detail": "Challenge "wrong-id" is invalid: challenge was not issued by this server.",
+        "instance": "[instance]",
+        "status": 402,
+        "title": "Invalid Challenge",
+        "type": "https://paymentauth.org/problems/invalid-challenge",
+      }
+    `)
+  })
+
   test('captures each transport request once and threads the verified envelope additively', async () => {
     const requestMethod = Method.from({
       name: 'mock',
@@ -232,50 +276,6 @@ describe('request handler', () => {
     expect(receiptEnvelope?.challenge.id).toBe(credential.challenge.id)
   })
 
-  test('returns 402 when challenge ID mismatch', async () => {
-    const wrongChallenge = Challenge.from({
-      id: 'wrong-id',
-      intent: 'charge',
-      method: 'tempo',
-      realm,
-      request: { amount: '1000', currency: asset, recipient: accounts[0].address },
-    })
-    const credential = Credential.from({
-      challenge: wrongChallenge,
-      payload: { signature: '0x123', type: 'transaction' },
-    })
-
-    const request = new Request('https://example.com/resource', {
-      headers: { Authorization: Credential.serialize(credential) },
-    })
-
-    const result = await Mppx.create({ methods: [method], realm, secretKey }).charge({
-      amount: '1000',
-      currency: asset,
-      expires: new Date(Date.now() + 60_000).toISOString(),
-      recipient: accounts[0].address,
-    })(request)
-
-    expect(result.status).toBe(402)
-    if (result.status !== 402) throw new Error()
-
-    const body = (await result.challenge.json()) as object
-    expect({
-      ...body,
-      challengeId: '[challengeId]',
-      instance: '[instance]',
-    }).toMatchInlineSnapshot(`
-      {
-        "challengeId": "[challengeId]",
-        "detail": "Challenge "wrong-id" is invalid: challenge was not issued by this server.",
-        "instance": "[instance]",
-        "status": 402,
-        "title": "Invalid Challenge",
-        "type": "https://paymentauth.org/problems/invalid-challenge",
-      }
-    `)
-  })
-
   test('returns 402 when credential is from a different route (cross-route scope confusion)', async () => {
     const handler = Mppx.create({ methods: [method], realm, secretKey })
 
@@ -982,6 +982,103 @@ describe('compose', () => {
     expect(wwwAuth).toContain('method="beta"')
   })
 
+  test('filters compose challenges using Accept-Payment', async () => {
+    const mppx = Mppx.create({ methods: [alphaMethod, betaMethod], realm, secretKey })
+
+    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()
+
+    const challenges = Challenge.fromResponseList(result.challenge)
+    expect(challenges).toHaveLength(1)
+    expect(challenges[0]?.method).toBe('beta')
+  })
+
+  test('orders compose challenges by Accept-Payment q-value', async () => {
+    const mppx = Mppx.create({ methods: [alphaMethod, betaMethod], realm, secretKey })
+
+    const result = await mppx.compose(
+      [alphaMethod, challengeOpts],
+      [betaMethod, challengeOpts],
+    )(
+      new Request('https://example.com/resource', {
+        headers: { 'Accept-Payment': 'beta/charge;q=0.9, alpha/charge;q=0.3' },
+      }),
+    )
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    const challenges = Challenge.fromResponseList(result.challenge)
+    expect(challenges.map((challenge) => challenge.method)).toEqual(['beta', 'alpha'])
+  })
+
+  test('applies a specific Accept-Payment opt-out before broader wildcards', async () => {
+    const mppx = Mppx.create({ methods: [alphaMethod, betaMethod], realm, secretKey })
+
+    const result = await mppx.compose(
+      [alphaMethod, challengeOpts],
+      [betaMethod, challengeOpts],
+    )(
+      new Request('https://example.com/resource', {
+        headers: { 'Accept-Payment': 'alpha/*;q=1, alpha/charge;q=0, beta/*;q=0.5' },
+      }),
+    )
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    const challenges = Challenge.fromResponseList(result.challenge)
+    expect(challenges).toHaveLength(1)
+    expect(challenges[0]?.method).toBe('beta')
+  })
+
+  test('falls back to all compose challenges when Accept-Payment has no matches', async () => {
+    const mppx = Mppx.create({ methods: [alphaMethod, betaMethod], realm, secretKey })
+
+    const result = await mppx.compose(
+      [alphaMethod, challengeOpts],
+      [betaMethod, challengeOpts],
+    )(
+      new Request('https://example.com/resource', {
+        headers: { 'Accept-Payment': 'gamma/charge' },
+      }),
+    )
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    const challenges = Challenge.fromResponseList(result.challenge)
+    expect(challenges.map((challenge) => challenge.method)).toEqual(['alpha', 'beta'])
+  })
+
+  test('falls back to all compose challenges when Accept-Payment is invalid', async () => {
+    const mppx = Mppx.create({ methods: [alphaMethod, betaMethod], realm, secretKey })
+
+    const result = await mppx.compose(
+      [alphaMethod, challengeOpts],
+      [betaMethod, challengeOpts],
+    )(
+      new Request('https://example.com/resource', {
+        headers: { 'Accept-Payment': 'not a valid header' },
+      }),
+    )
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    const challenges = Challenge.fromResponseList(result.challenge)
+    expect(challenges.map((challenge) => challenge.method)).toEqual(['alpha', 'beta'])
+  })
+
   test('dispatches to matching handler when credential matches alpha', async () => {
     const mppx = Mppx.create({ methods: [alphaMethod, betaMethod], realm, secretKey })
 

package/src/server/Mppx.ts

@@ -5,8 +5,9 @@ import * as Challenge from '../Challenge.js'
 import * as Credential from '../Credential.js'
 import * as Errors from '../Errors.js'
 import * as Expires from '../Expires.js'
+import * as AcceptPayment from '../internal/AcceptPayment.js'
 import * as Env from '../internal/env.js'
-import * as Method from '../Method.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'
@@ -447,22 +448,22 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
           withReceipt<response>(response?: response) {
             if (managementResponse) {
               return transport.respondReceipt({
+                challengeId: credential.challenge.id,
                 credential,
                 envelope,
                 input,
                 receipt: receiptData,
                 response: managementResponse as never,
-                challengeId: credential.challenge.id,
               }) 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,
-              challengeId: credential.challenge.id,
             }) as response
           },
         }
@@ -883,38 +884,58 @@ export function compose(
     // No credential — call all handlers and merge 402 challenges.
     const results = await Promise.all(handlers.map((h) => h(input)))
 
-    // Merge WWW-Authenticate headers from all 402 responses.
-    const mergedHeaders = new Headers()
-    mergedHeaders.set('Cache-Control', 'no-store')
-
-    for (const result of results) {
-      if (result.status !== 402) continue
-      const response = result.challenge as Response
-      const wwwAuth = response.headers.get('WWW-Authenticate')
-      if (wwwAuth) mergedHeaders.append('WWW-Authenticate', wwwAuth)
-    }
-
-    // Collect html-enabled handlers and their challenges
-    const htmlEntries = (() => {
+    const challengeEntries = (() => {
       const entries: {
         handler: ConfiguredHandler
         challenge: Challenge.Challenge
+        result: Extract<MethodFn.Response<Transport.Http>, { status: 402 }>
       }[] = []
+
       for (let i = 0; i < handlers.length; i++) {
-        const meta = (handlers[i] as ConfiguredHandler)._internal
-        if (!meta?.html) continue
         const result = results[i]
         if (result?.status !== 402) continue
-        const wwwAuth = result.challenge.headers.get('WWW-Authenticate')
+
+        const response = result.challenge as Response
+        const wwwAuth = response.headers.get('WWW-Authenticate')
         if (!wwwAuth) continue
+
         entries.push({
           handler: handlers[i] as ConfiguredHandler,
           challenge: Challenge.deserialize(wwwAuth),
+          result,
         })
       }
-      return entries
+
+      const acceptPayment = input.headers.get('Accept-Payment')
+      if (!acceptPayment) return entries
+
+      try {
+        const ranked = AcceptPayment.rank(
+          entries.map((entry) => entry.challenge),
+          AcceptPayment.parse(acceptPayment),
+        )
+        if (ranked.length === 0) return entries
+
+        const entriesById = new Map(entries.map((entry) => [entry.challenge.id, entry] as const))
+        return ranked.map((challenge) => entriesById.get(challenge.id)!)
+      } catch {
+        return entries
+      }
     })()
 
+    // Merge WWW-Authenticate headers from all 402 responses.
+    const mergedHeaders = new Headers()
+    mergedHeaders.set('Cache-Control', 'no-store')
+
+    for (const entry of challengeEntries) {
+      const response = entry.result.challenge as Response
+      const wwwAuth = response.headers.get('WWW-Authenticate')
+      if (wwwAuth) mergedHeaders.append('WWW-Authenticate', wwwAuth)
+    }
+
+    // Collect html-enabled handlers and their challenges
+    const htmlEntries = challengeEntries.filter((entry) => entry.handler._internal?.html)
+
     const wantsHtml = input.headers.get('Accept')?.includes('text/html')
     if (wantsHtml && htmlEntries.length > 0) {
       const { theme, text } = Html.resolveOptions(
@@ -962,10 +983,9 @@ export function compose(
 
     // Non-HTML fallback: use first handler's body
     let body: string | null = null
-    for (const result of results) {
-      if (result.status !== 402) continue
+    for (const entry of challengeEntries) {
       if (!body) {
-        const response = result.challenge as Response
+        const response = entry.result.challenge as Response
         const contentType = response.headers.get('Content-Type')
         if (contentType) mergedHeaders.set('Content-Type', contentType)
         body = await response.text()

package/src/server/Transport.test.ts

@@ -269,6 +269,26 @@ describe('http', () => {
       expect(body).toContain('Gotta Pay')
     })
 
+    test('uses paymentRequired as the title when title is omitted', async () => {
+      const transport = Transport.http()
+      const request = new Request('https://example.com', {
+        headers: { Accept: 'text/html' },
+      })
+
+      const response = await transport.respondChallenge({
+        challenge,
+        input: request,
+        html: {
+          ...htmlOptions,
+          text: { paymentRequired: 'Gotta Pay' },
+        },
+      })
+
+      const body = await response.text()
+      expect(body).toContain('<title>Gotta Pay</title>')
+      expect(body).toContain('<span>Gotta Pay</span>')
+    })
+
     test('applies custom theme logo', async () => {
       const transport = Transport.http()
       const request = new Request('https://example.com', {

package/src/server/internal/html/config.ts

@@ -172,7 +172,15 @@ export function resolveOptions(options: Options): {
     },
     (options.theme as never) ?? {},
   )
-  const text = sanitizeRecord(mergeDefined(defaultText, (options.text as never) ?? {}))
+  const textOverrides = (options.text as Text | undefined) ?? undefined
+  const mergedText = mergeDefined(defaultText, (textOverrides as never) ?? {})
+  const text = sanitizeRecord({
+    ...mergedText,
+    title:
+      typeof textOverrides?.title === 'string' && textOverrides.title.length > 0
+        ? mergedText.title
+        : mergedText.paymentRequired,
+  })
   return { theme, text }
 }
 

package/src/stripe/internal/constants.ts

@@ -0,0 +1,7 @@
+/**
+ * Stripe API version with `.preview` suffix.
+ *
+ * Required for `shared_payment_granted_token` (SPTs are in private preview).
+ * Bump this when upgrading to a newer Stripe API version.
+ */
+export const stripePreviewVersion = '2026-02-25.preview'

package/src/stripe/server/Charge.ts

@@ -5,6 +5,7 @@ import type { LooseOmit, OneOf } from '../../internal/types.js'
 import * as Method from '../../Method.js'
 import type * as Html from '../../server/internal/html/config.ts'
 import type * as z from '../../zod.js'
+import { stripePreviewVersion } from '../internal/constants.js'
 import type {
   StripeClient,
   CreatePaymentMethodFromElements,
@@ -202,13 +203,16 @@ async function createWithClient(parameters: {
         // `shared_payment_granted_token` is not yet in the Stripe SDK types (SPTs are in private preview).
         shared_payment_granted_token: spt,
       } as any,
-      { idempotencyKey: `mppx_${challenge.id}_${spt}` },
+      { idempotencyKey: `mppx_${challenge.id}_${spt}`, apiVersion: stripePreviewVersion },
     )
     // https://docs.stripe.com/error-low-level#idempotency
     const replayed = result.lastResponse?.headers?.['idempotent-replayed'] === 'true'
     return { id: result.id, status: result.status, replayed }
-  } catch {
-    throw new VerificationFailedError({ reason: 'Stripe PaymentIntent failed' })
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    throw new VerificationFailedError({
+      reason: `Stripe PaymentIntent failed: ${detail}`,
+    })
   }
 }
 
@@ -240,11 +244,25 @@ async function createWithSecretKey(parameters: {
       Authorization: `Basic ${btoa(`${secretKey}:`)}`,
       'Content-Type': 'application/x-www-form-urlencoded',
       'Idempotency-Key': `mppx_${challenge.id}_${spt}`,
+      'Stripe-Version': stripePreviewVersion,
     },
     body,
   })
 
-  if (!response.ok) throw new VerificationFailedError({ reason: 'Stripe PaymentIntent failed' })
+  if (!response.ok) {
+    const body = await response.text().catch(() => '')
+    const detail = (() => {
+      try {
+        const parsed = JSON.parse(body) as { error?: { message?: string } }
+        return parsed.error?.message ?? body
+      } catch {
+        return body
+      }
+    })()
+    throw new VerificationFailedError({
+      reason: `Stripe PaymentIntent failed: ${detail}`,
+    })
+  }
   // https://docs.stripe.com/error-low-level#idempotency
   const replayed = response.headers.get('idempotent-replayed') === 'true'
   const result = (await response.json()) as { id: string; status: string }

package/src/tempo/Methods.test.ts

@@ -39,6 +39,31 @@ describe('charge', () => {
     expect(result.success).toBe(true)
   })
 
+  test('schema: validates request with supportedModes', () => {
+    const result = Methods.charge.schema.request.safeParse({
+      amount: '1',
+      currency: '0x20c0000000000000000000000000000000000001',
+      decimals: 6,
+      recipient: '0x1234567890abcdef1234567890abcdef12345678',
+      supportedModes: ['pull'],
+    })
+    expect(result.success).toBe(true)
+    if (!result.success) return
+
+    expect(result.data.methodDetails?.supportedModes).toEqual(['pull'])
+  })
+
+  test('schema: rejects empty supportedModes', () => {
+    const result = Methods.charge.schema.request.safeParse({
+      amount: '1',
+      currency: '0x20c0000000000000000000000000000000000001',
+      decimals: 6,
+      recipient: '0x1234567890abcdef1234567890abcdef12345678',
+      supportedModes: [],
+    })
+    expect(result.success).toBe(false)
+  })
+
   test('schema: validates request with memo', () => {
     const result = Methods.charge.schema.request.safeParse({
       amount: '1',

package/src/tempo/Methods.ts

@@ -4,6 +4,9 @@ import { parseUnits } from 'viem'
 import * as Method from '../Method.js'
 import * as z from '../zod.js'
 
+export const chargeModes = ['push', 'pull'] as const
+export type ChargeMode = (typeof chargeModes)[number]
+
 const split = z.object({
   amount: z.amount(),
   memo: z.optional(z.hash()),
@@ -47,6 +50,7 @@ export const charge = Method.from({
           memo: z.optional(z.hash()),
           recipient: z.optional(z.string()),
           splits: z.optional(z.array(split).check(z.minLength(1), z.maxLength(10))),
+          supportedModes: z.optional(z.array(z.enum(chargeModes)).check(z.minLength(1))),
         })
         .check(
           z.refine(({ amount, decimals, splits }) => {
@@ -64,28 +68,32 @@ export const charge = Method.from({
             )
           }, 'Invalid splits'),
         ),
-      z.transform(({ amount, chainId, decimals, feePayer, memo, splits, ...rest }) => ({
-        ...rest,
-        amount: parseUnits(amount, decimals).toString(),
-        ...(chainId !== undefined ||
-        feePayer !== undefined ||
-        memo !== undefined ||
-        splits !== undefined
-          ? {
-              methodDetails: {
-                ...(chainId !== undefined && { chainId }),
-                ...(feePayer !== undefined && { feePayer }),
-                ...(memo !== undefined && { memo }),
-                ...(splits !== undefined && {
-                  splits: splits.map((split) => ({
-                    ...split,
-                    amount: parseUnits(split.amount, decimals).toString(),
-                  })),
-                }),
-              },
-            }
-          : {}),
-      })),
+      z.transform(
+        ({ amount, chainId, decimals, feePayer, memo, splits, supportedModes, ...rest }) => ({
+          ...rest,
+          amount: parseUnits(amount, decimals).toString(),
+          ...(chainId !== undefined ||
+          feePayer !== undefined ||
+          memo !== undefined ||
+          splits !== undefined ||
+          supportedModes !== undefined
+            ? {
+                methodDetails: {
+                  ...(chainId !== undefined && { chainId }),
+                  ...(feePayer !== undefined && { feePayer }),
+                  ...(memo !== undefined && { memo }),
+                  ...(splits !== undefined && {
+                    splits: splits.map((split) => ({
+                      ...split,
+                      amount: parseUnits(split.amount, decimals).toString(),
+                    })),
+                  }),
+                  ...(supportedModes !== undefined && { supportedModes }),
+                },
+              }
+            : {}),
+        }),
+      ),
     ),
   },
 })

package/src/tempo/Proof.test-d.ts

@@ -0,0 +1,13 @@
+import { expectTypeOf, test } from 'vp/test'
+
+import { Proof } from './index.js'
+
+test('Proof exports public proof source helpers', () => {
+  expectTypeOf(Proof.proofSource).toEqualTypeOf<
+    (parameters: { address: string; chainId: number }) => string
+  >()
+
+  expectTypeOf(Proof.parseProofSource).toEqualTypeOf<
+    (source: string) => { address: `0x${string}`; chainId: number } | null
+  >()
+})

package/src/tempo/Proof.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from 'vp/test'
+
+import * as tempo from './index.js'
+
+describe('tempo.Proof', () => {
+  test('proofSource constructs a did:pkh:eip155 source', () => {
+    expect(
+      tempo.Proof.proofSource({
+        address: '0xAbCdEf1234567890AbCdEf1234567890AbCdEf12',
+        chainId: 42431,
+      }),
+    ).toBe('did:pkh:eip155:42431:0xAbCdEf1234567890AbCdEf1234567890AbCdEf12')
+  })
+
+  test('parseProofSource parses a valid did:pkh:eip155 source', () => {
+    expect(
+      tempo.Proof.parseProofSource(
+        'did:pkh:eip155:42431:0xa5cc3c03994db5b0d9ba5e4f6d2efbd9f213b141',
+      ),
+    ).toEqual({
+      address: '0xa5cc3c03994db5b0d9ba5e4f6d2efbd9f213b141',
+      chainId: 42431,
+    })
+  })
+
+  test('parseProofSource rejects invalid source values', () => {
+    expect(
+      tempo.Proof.parseProofSource('did:pkh:eip155:01:0xa5cc3c03994db5b0d9ba5e4f6d2efbd9f213b141'),
+    ).toBe(null)
+  })
+})

package/src/tempo/Proof.ts

@@ -0,0 +1,13 @@
+import type { Address } from 'viem'
+
+import * as Proof_internal from './internal/proof.js'
+
+/** Constructs the canonical `did:pkh:eip155` source DID for Tempo proof credentials. */
+export function proofSource(parameters: { address: string; chainId: number }): string {
+  return Proof_internal.proofSource(parameters)
+}
+
+/** Parses a Tempo proof credential source DID into its chain ID and wallet address. */
+export function parseProofSource(source: string): { address: Address; chainId: number } | null {
+  return Proof_internal.parseProofSource(source)
+}

package/src/tempo/client/Charge.ts

@@ -47,7 +47,7 @@ export function charge(parameters: charge.Parameters = {}) {
     context: z.object({
       account: z.optional(z.custom<Account.getResolver.Parameters['account']>()),
       autoSwap: z.optional(z.custom<charge.AutoSwap>()),
-      mode: z.optional(z.enum(['push', 'pull'])),
+      mode: z.optional(z.enum(Methods.chargeModes)),
     }),
 
     async createCredential({ challenge, context }) {
@@ -74,11 +74,7 @@ export function charge(parameters: charge.Parameters = {}) {
         })
       }
 
-      const mode =
-        context?.mode ?? parameters.mode ?? (account.type === 'json-rpc' ? 'push' : 'pull')
-
       const currency = request.currency as Address
-
       if (parameters.expectedRecipients) {
         const allowed = new Set(parameters.expectedRecipients.map((a) => a.toLowerCase()))
         const splits = methodDetails?.splits as readonly { recipient: string }[] | undefined
@@ -89,6 +85,21 @@ export function charge(parameters: charge.Parameters = {}) {
           }
         }
       }
+      const supportedModes = (methodDetails?.supportedModes as
+        | readonly Methods.ChargeMode[]
+        | undefined) ?? ['pull', 'push']
+      const mode = (() => {
+        const explicitMode = context?.mode ?? parameters.mode
+        if (explicitMode) {
+          if (!supportedModes.includes(explicitMode))
+            throw new Error(`Challenge does not support ${explicitMode} mode.`)
+          return explicitMode
+        }
+
+        const preferredMode = account.type === 'json-rpc' ? 'push' : 'pull'
+        if (supportedModes.includes(preferredMode)) return preferredMode
+        return supportedModes[0]!
+      })()
 
       const memo = methodDetails?.memo
         ? (methodDetails.memo as Hex.Hex)
@@ -193,9 +204,12 @@ export declare namespace charge {
      * - `'push'`: Client broadcasts the transaction and sends the tx hash to the server.
      * - `'pull'`: Client signs the transaction and sends the serialized tx to the server for broadcast.
      *
+     * If the server advertises `supportedModes`, this setting must be one of
+     * the supported values for the challenge.
+     *
      * @default `'push'` for JSON-RPC accounts, `'pull'` for local accounts.
      */
-    mode?: 'push' | 'pull' | undefined
+    mode?: Methods.ChargeMode | undefined
   } & Account.getResolver.Parameters &
     Client.getResolver.Parameters
 }