mppx 0.5.1 → 0.5.3

package/src/proxy/internal/Route.ts

@@ -42,13 +42,16 @@ export function matchPath(
   path: string,
   filter?: (value: unknown) => boolean,
 ): { key: string; value: unknown } | null {
+  let match: { key: string; value: unknown } | null = null
   for (const [key, value] of Object.entries(routes)) {
     if (filter && !filter(value)) continue
     const { pattern } = parseRouteKey(key)
     const urlPattern = new URLPattern({ pathname: pattern })
-    if (urlPattern.test({ pathname: path })) return { key, value }
+    if (!urlPattern.test({ pathname: path })) continue
+    if (match) return null
+    match = { key, value }
   }
-  return null
+  return match
 }
 
 function parseRouteKey(key: string): { method: string | undefined; pattern: string } {

package/src/server/Mppx.test.ts

@@ -95,6 +95,36 @@ describe('request handler', () => {
     `)
   })
 
+  test('returns sanitized malformed credential error for unexpected transport failures', async () => {
+    const baseTransport = Transport.http()
+    const transport = Transport.from({
+      ...baseTransport,
+      name: 'leaking-http',
+      getCredential() {
+        throw new Error('request to https://rpc.example.com/?key=secret-key failed')
+      },
+    })
+
+    const result = await Mppx.create({ methods: [method], realm, secretKey, transport }).charge({
+      amount: '1000',
+      currency: asset,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: accounts[0].address,
+    })(
+      new Request('https://example.com/resource', {
+        headers: { Authorization: 'Payment invalid' },
+      }),
+    )
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    const body = (await result.challenge.json()) as { detail: string }
+    expect(body.detail).toBe('Credential is malformed.')
+    expect(body.detail).not.toContain('secret-key')
+    expect(body.detail).not.toContain('rpc.example.com')
+  })
+
   test('returns 402 when challenge ID mismatch', async () => {
     const wrongChallenge = Challenge.from({
       id: 'wrong-id',
@@ -181,7 +211,7 @@ describe('request handler', () => {
     expect(body.detail).toContain('does not match')
   })
 
-  test('topUp credential bypasses cross-route amount validation', async () => {
+  test('topUp credential is rejected when replayed across routes with different amounts', async () => {
     // Use a session method whose schema defines action: 'topUp'
     const sessionMethod = Method.from({
       name: 'mock',
@@ -231,7 +261,7 @@ describe('request handler', () => {
       payload: { action: 'topUp', token: 'valid' },
     })
 
-    // Present it at the "expensive" route — topUp should bypass amount check
+    // Present it at the "expensive" route — topUp must still match scope.
     const expensiveHandle = handler['mock/session']({
       amount: '1000000',
       currency: asset,
@@ -244,16 +274,13 @@ describe('request handler', () => {
       }),
     )
 
-    // Should NOT get 402 for amount mismatch — topUp bypasses the check.
-    // It will fail at a later stage (payload validation), but not with
-    // "does not match this route's requirements".
-    if (result.status === 402) {
-      const body = (await result.challenge.json()) as { detail?: string }
-      expect(body.detail).not.toContain('does not match')
-    }
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+    const body = (await result.challenge.json()) as { detail?: string }
+    expect(body.detail).toContain('does not match')
   })
 
-  test('voucher credential bypasses cross-route amount validation', async () => {
+  test('voucher credential is rejected when replayed across routes with different amounts', async () => {
     const sessionMethod = Method.from({
       name: 'mock',
       intent: 'session',
@@ -307,8 +334,8 @@ describe('request handler', () => {
       payload: { action: 'voucher', cumulativeAmount: '500', signature: '0xabc' },
     })
 
-    // Present it at the same route but with a higher price — voucher should
-    // bypass the cross-route amount check just like topUp does
+    // Present it at the same route but with a higher price — voucher must
+    // still match the original priced scope.
     const expensiveHandle = handler['mock/session']({
       amount: '1000000',
       currency: asset,
@@ -321,11 +348,10 @@ describe('request handler', () => {
       }),
     )
 
-    // Should NOT get 402 for amount mismatch — voucher bypasses the check.
-    if (result.status === 402) {
-      const body = (await result.challenge.json()) as { detail?: string }
-      expect(body.detail).not.toContain('does not match')
-    }
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+    const body = (await result.challenge.json()) as { detail?: string }
+    expect(body.detail).toContain('does not match')
   })
 
   test('rejects charge credential with injected action: topUp (cross-route bypass attempt)', async () => {
@@ -552,7 +578,63 @@ describe('request handler', () => {
         "type": "https://paymentauth.org/problems/invalid-payload",
       }
     `)
-    expect(body.detail).toContain('Credential payload is invalid')
+    expect(body.detail).toBe('Credential payload is invalid.')
+    expect(body.detail).not.toContain('invalidField')
+  })
+
+  test('returns sanitized verification error for unexpected verifier failures', async () => {
+    const leakingMethod = Method.toServer(
+      Method.from({
+        name: 'mock',
+        intent: 'charge',
+        schema: {
+          credential: {
+            payload: z.object({ token: z.string() }),
+          },
+          request: z.object({
+            amount: z.string(),
+            currency: z.string(),
+            recipient: z.string(),
+          }),
+        },
+      }),
+      {
+        async verify() {
+          throw new Error('request to https://mainnet.infura.io/v3/secret-key failed')
+        },
+      },
+    )
+
+    const handle = Mppx.create({ methods: [leakingMethod], realm, secretKey })['mock/charge']({
+      amount: '1000',
+      currency: asset,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: accounts[0].address,
+    })
+
+    const firstResult = await handle(new Request('https://example.com/resource'))
+    expect(firstResult.status).toBe(402)
+    if (firstResult.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(firstResult.challenge)
+    const credential = Credential.from({
+      challenge,
+      payload: { token: 'valid' },
+    })
+
+    const result = await handle(
+      new Request('https://example.com/resource', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    const body = (await result.challenge.json()) as { detail: string }
+    expect(body.detail).toBe('Payment verification failed.')
+    expect(body.detail).not.toContain('infura')
+    expect(body.detail).not.toContain('secret-key')
   })
 })
 
@@ -1724,6 +1806,77 @@ describe('cross-route credential replay via scope binding flaw', () => {
 
     expect(result.status).toBe(402)
   })
+
+  test('compose dispatch includes methodDetails memo/splits binding', async () => {
+    const splitsMethod = Method.from({
+      name: 'mock',
+      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(),
+            splits: z.optional(z.array(z.object({ amount: z.string(), recipient: z.string() }))),
+          }),
+          z.transform(({ amount, currency, decimals, recipient, splits }) => ({
+            methodDetails: {
+              amount: String(Number(amount) * 10 ** decimals),
+              currency,
+              recipient,
+              ...(splits && { splits }),
+            },
+          })),
+        ),
+      },
+    })
+
+    const splitsServerMethod = Method.toServer(splitsMethod, {
+      async verify() {
+        return mockReceipt()
+      },
+    })
+
+    const handler = Mppx.create({ methods: [splitsServerMethod], realm, secretKey })
+
+    const noSplitsHandle = handler.charge({
+      amount: '1',
+      currency: '0x0000000000000000000000000000000000000001',
+      decimals: 6,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: '0x0000000000000000000000000000000000000002',
+    })
+    const splitsHandle = handler.charge({
+      amount: '1',
+      currency: '0x0000000000000000000000000000000000000001',
+      decimals: 6,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: '0x0000000000000000000000000000000000000002',
+      splits: [{ amount: '0.2', recipient: '0x0000000000000000000000000000000000000003' }],
+    })
+
+    const composed = Mppx.compose(noSplitsHandle, splitsHandle)
+    const firstResult = await composed(new Request('https://example.com/resource'))
+    expect(firstResult.status).toBe(402)
+    if (firstResult.status !== 402) throw new Error()
+
+    const challenges = Challenge.fromResponseList(firstResult.challenge)
+    const noSplitsChallenge = challenges[0]!
+    const credential = Credential.from({
+      challenge: noSplitsChallenge,
+      payload: { token: 'valid' },
+    })
+
+    const result = await composed(
+      new Request('https://example.com/resource', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+
+    expect(result.status).toBe(200)
+  })
 })
 
 describe('withReceipt', () => {

package/src/server/Mppx.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage, ServerResponse } from 'node:http'
+import { isDeepStrictEqual } from 'node:util'
 
 import * as Challenge from '../Challenge.js'
 import * as Credential from '../Credential.js'
@@ -300,10 +301,12 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
 
         // Credential was provided but malformed
         if (credentialError) {
+          const reason = getSafeCredentialReason(credentialError)
           const response = await transport.respondChallenge({
             challenge,
             input,
-            error: new Errors.MalformedCredentialError({ reason: credentialError.message }),
+            error: new Errors.MalformedCredentialError(reason ? { reason } : {}),
+            html: method.html,
           })
           return { challenge: response, status: 402 }
         }
@@ -314,6 +317,7 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
             challenge,
             input,
             error: new Errors.PaymentRequiredError({ description }),
+            html: method.html,
           })
           return { challenge: response, status: 402 }
         }
@@ -328,6 +332,7 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
               id: credential.challenge.id,
               reason: 'challenge was not issued by this server',
             }),
+            html: method.html,
           })
           return { challenge: response, status: 402 }
         }
@@ -339,13 +344,6 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
         // Note: we compare specific payment parameters rather than the full
         // request because the `request` hook may produce credential-dependent
         // output (e.g. `feePayer` differs between 402 and credential calls).
-        //
-        // Skip this check for topUp and voucher actions: the route's
-        // `request` hook may produce a different amount because these
-        // requests carry no application body (e.g. no model field for
-        // dynamic pricing). The credential echoes a challenge obtained
-        // from the original request which had the correct amount; the
-        // on-chain voucher signature is the real validation.
         {
           for (const field of ['method', 'intent', 'realm'] as const) {
             if (credential.challenge[field] !== challenge[field]) {
@@ -356,65 +354,26 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
                   id: credential.challenge.id,
                   reason: `credential ${field} does not match this route's requirements`,
                 }),
+                html: method.html,
               })
               return { challenge: response, status: 402 }
             }
           }
 
-          // Use safeParse (not raw payload) so only methods whose schema
-          // defines `action` can trigger the skip. Without this, a client
-          // could inject `action: 'topUp'` on a charge credential to bypass
-          // the amount check. Zod strips unknown keys, so charge payloads
-          // (which don't define `action`) will have it removed.
-          const parsed = method.schema.credential.payload.safeParse(credential.payload)
-          const action = parsed.success
-            ? (parsed.data as Record<string, unknown>)?.action
-            : undefined
-          if (action !== 'topUp' && action !== 'voucher') {
-            const routeReq = challenge.request as Record<string, unknown>
-            const echoedReq = credential.challenge.request as Record<string, unknown>
-            const routeDetails = (routeReq.methodDetails ?? {}) as Record<string, unknown>
-            const echoedDetails = (echoedReq.methodDetails ?? {}) as Record<string, unknown>
-            for (const field of ['amount', 'currency', 'recipient'] as const) {
-              const routeVal = routeReq[field] ?? routeDetails[field]
-              if (
-                routeVal !== undefined &&
-                String(routeVal) !== String(echoedReq[field] ?? echoedDetails[field])
-              ) {
-                const response = await transport.respondChallenge({
-                  challenge,
-                  input,
-                  error: new Errors.InvalidChallengeError({
-                    id: credential.challenge.id,
-                    reason: `credential ${field} does not match this route's requirements`,
-                  }),
-                })
-                return { challenge: response, status: 402 }
-              }
-            }
-
-            // Compare payment-relevant methodDetails fields (memo, splits).
-            // These are excluded from the top-level field check above but
-            // affect verification semantics — a credential issued for a
-            // no-splits route must not be accepted on a splits route.
-            for (const field of ['memo', 'splits'] as const) {
-              const routeVal = routeDetails[field]
-              const echoedVal = echoedDetails[field]
-              if (
-                routeVal !== undefined &&
-                JSON.stringify(routeVal) !== JSON.stringify(echoedVal)
-              ) {
-                const response = await transport.respondChallenge({
-                  challenge,
-                  input,
-                  error: new Errors.InvalidChallengeError({
-                    id: credential.challenge.id,
-                    reason: `credential ${field} does not match this route's requirements`,
-                  }),
-                })
-                return { challenge: response, status: 402 }
-              }
-            }
+          const mismatch = getRequestBindingMismatch(
+            challenge.request as Record<string, unknown>,
+            credential.challenge.request as Record<string, unknown>,
+          )
+          if (mismatch) {
+            const response = await transport.respondChallenge({
+              challenge,
+              input,
+              error: new Errors.InvalidChallengeError({
+                id: credential.challenge.id,
+                reason: `credential ${mismatch} does not match this route's requirements`,
+              }),
+            })
+            return { challenge: response, status: 402 }
           }
         }
 
@@ -432,11 +391,11 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
         // Validate payload structure against method schema
         try {
           method.schema.credential.payload.parse(credential.payload)
-        } catch (e) {
+        } catch {
           const response = await transport.respondChallenge({
             challenge,
             input,
-            error: new Errors.InvalidPayloadError({ reason: (e as Error).message }),
+            error: new Errors.InvalidPayloadError(),
           })
           return { challenge: response, status: 402 }
         }
@@ -447,10 +406,9 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
         try {
           receiptData = await verify({ credential, request } as never)
         } catch (e) {
-          const error =
-            e instanceof Errors.PaymentError
-              ? e
-              : new Errors.VerificationFailedError({ reason: (e as Error).message })
+          if (!(e instanceof Errors.PaymentError))
+            console.error('mppx: internal verification error', e)
+          const error = e instanceof Errors.PaymentError ? e : new Errors.VerificationFailedError()
           const response = await transport.respondChallenge({
             challenge,
             input,
@@ -473,6 +431,8 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
           withReceipt<response>(response?: response) {
             if (managementResponse) {
               return transport.respondReceipt({
+                credential,
+                input,
                 receipt: receiptData,
                 response: managementResponse as never,
                 challengeId: credential.challenge.id,
@@ -480,6 +440,8 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
             }
             if (!response) throw new Error('withReceipt() requires a response argument')
             return transport.respondReceipt({
+              credential,
+              input,
               receipt: receiptData,
               response: response as never,
               challengeId: credential.challenge.id,
@@ -501,6 +463,13 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
   }
 }
 
+function getSafeCredentialReason(error: unknown): string | undefined {
+  if (error instanceof Credential.InvalidCredentialEncodingError) return error.message
+  if (error instanceof Credential.MissingAuthorizationHeaderError) return error.message
+  if (error instanceof Credential.MissingPaymentSchemeError) return error.message
+  return undefined
+}
+
 declare namespace createMethodFn {
   type Parameters<
     method extends Method.Method = Method.Method,
@@ -552,6 +521,88 @@ function resolveRealmFromRequest(input: unknown): string {
   return defaultRealm
 }
 
+type RequestBindingField = 'amount' | 'currency' | 'recipient' | 'chainId' | 'memo' | 'splits'
+
+const requestBindingFields = [
+  'amount',
+  'currency',
+  'recipient',
+  'chainId',
+  'memo',
+  'splits',
+] as const satisfies readonly RequestBindingField[]
+
+type RequestBinding = Partial<Record<RequestBindingField, unknown>>
+
+function getRequestBindingMismatch(
+  expectedRequest: Record<string, unknown>,
+  actualRequest: Record<string, unknown>,
+): RequestBindingField | undefined {
+  const expected = getRequestBinding(expectedRequest)
+  const actual = getRequestBinding(actualRequest)
+
+  return requestBindingFields.find(
+    (field) => !requestBindingValuesMatch(field, expected[field], actual[field]),
+  )
+}
+
+function getRequestBinding(request: Record<string, unknown>): RequestBinding {
+  const methodDetails = (request.methodDetails ?? {}) as Record<string, unknown>
+
+  return {
+    amount: request.amount ?? methodDetails.amount,
+    currency: request.currency ?? methodDetails.currency,
+    recipient: request.recipient ?? methodDetails.recipient,
+    chainId: request.chainId ?? methodDetails.chainId,
+    memo: methodDetails.memo,
+    splits: methodDetails.splits,
+  }
+}
+
+function requestBindingValuesMatch(
+  field: RequestBindingField,
+  expected: unknown,
+  actual: unknown,
+): boolean {
+  return isDeepStrictEqual(
+    normalizeRequestBindingValue(field, expected),
+    normalizeRequestBindingValue(field, actual),
+  )
+}
+
+function normalizeRequestBindingValue(field: RequestBindingField, value: unknown): unknown {
+  switch (field) {
+    case 'memo':
+      return normalizeHex(value)
+    case 'splits':
+      return normalizeComparable(value)
+    default:
+      return normalizeScalar(value)
+  }
+}
+
+function normalizeScalar(value: unknown): string | undefined {
+  return value === undefined ? undefined : String(value)
+}
+
+function normalizeHex(value: unknown): unknown {
+  return typeof value === 'string' && value.startsWith('0x') ? value.toLowerCase() : value
+}
+
+function normalizeComparable(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(normalizeComparable)
+
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, nested]) => [key, normalizeComparable(nested)]),
+    )
+  }
+
+  return normalizeHex(value)
+}
+
 export type MethodFn<
   method extends Method.Method,
   transport extends Transport.AnyTransport,
@@ -668,7 +719,6 @@ export function compose(
       if (credential) {
         const { method: credMethod, intent: credIntent } = credential.challenge
         const credReq = credential.challenge.request as Record<string, unknown>
-        const credDetails = (credReq.methodDetails ?? {}) as Record<string, unknown>
 
         // Filter by name+intent, then narrow by comparing stable request fields
         // from the echoed challenge against each handler's canonical request.
@@ -680,16 +730,7 @@ export function compose(
           if (!meta || meta.name !== credMethod || meta.intent !== credIntent) return false
           const canonical = meta._canonicalRequest
           if (!canonical) return true
-          const canonicalDetails = (canonical.methodDetails ?? {}) as Record<string, unknown>
-          for (const field of ['amount', 'currency', 'recipient', 'chainId'] as const) {
-            const canonicalVal = canonical[field] ?? canonicalDetails[field]
-            if (
-              canonicalVal !== undefined &&
-              String(canonicalVal) !== String(credReq[field] ?? credDetails[field])
-            )
-              return false
-          }
-          return true
+          return !getRequestBindingMismatch(canonical, credReq)
         })
 
         const match =

package/src/server/Transport.test.ts

@@ -135,6 +135,8 @@ describe('http', () => {
       const originalResponse = new Response('OK', { status: 200 })
 
       const response = transport.respondReceipt({
+        credential,
+        input: new Request('https://example.com'),
         receipt,
         response: originalResponse,
         challengeId: challenge.id,
@@ -252,7 +254,13 @@ describe('mcp', () => {
       }
 
       expect(
-        transport.respondReceipt({ receipt, response: successResponse, challengeId: challenge.id }),
+        transport.respondReceipt({
+          credential,
+          input: mcpRequest,
+          receipt,
+          response: successResponse,
+          challengeId: challenge.id,
+        }),
       ).toMatchInlineSnapshot(`
         {
           "id": 1,
@@ -285,7 +293,13 @@ describe('mcp', () => {
       }
 
       expect(
-        transport.respondReceipt({ receipt, response: errorResponse, challengeId: challenge.id }),
+        transport.respondReceipt({
+          credential,
+          input: mcpRequest,
+          receipt,
+          response: errorResponse,
+          challengeId: challenge.id,
+        }),
       ).toBe(errorResponse)
     })
   })