mppx 0.5.1 → 0.5.4

package/src/proxy/Proxy.test.ts

@@ -1,4 +1,4 @@
-import { Receipt } from 'mppx'
+import { Challenge, Credential, Method, Receipt, z } from 'mppx'
 import { Mppx as Mppx_client, tempo as tempo_client } from 'mppx/client'
 import { Mppx as Mppx_server, tempo as tempo_server } from 'mppx/server'
 import { afterEach, describe, expect, test } from 'vp/test'
@@ -439,6 +439,193 @@ describe('create', () => {
     expect(res.status).toBe(402)
   })
 
+  test('behavior: management POST uses credential method binding to disambiguate same-path paid routes', async () => {
+    const alpha = Method.from({
+      name: 'alpha',
+      intent: 'charge',
+      schema: {
+        credential: { payload: z.object({ token: z.string() }) },
+        request: z.object({ amount: z.string() }),
+      },
+    })
+    const beta = Method.from({
+      name: 'beta',
+      intent: 'charge',
+      schema: {
+        credential: { payload: z.object({ token: z.string() }) },
+        request: z.object({ amount: z.string() }),
+      },
+    })
+
+    const handler = Mppx_server.create({
+      methods: [
+        Method.toServer(alpha, {
+          async verify() {
+            return Receipt.from({
+              method: 'alpha',
+              status: 'success',
+              timestamp: new Date().toISOString(),
+              reference: 'alpha-reference',
+            })
+          },
+          respond() {
+            return new Response(null, { status: 204 })
+          },
+        }),
+        Method.toServer(beta, {
+          async verify() {
+            return Receipt.from({
+              method: 'beta',
+              status: 'success',
+              timestamp: new Date().toISOString(),
+              reference: 'beta-reference',
+            })
+          },
+          respond() {
+            return new Response(null, { status: 205 })
+          },
+        }),
+      ],
+      secretKey,
+    })
+
+    const proxy = ApiProxy.create({
+      services: [
+        Service.from('api', {
+          baseUrl: 'https://example.com',
+          routes: {
+            'GET /v1/stream': handler['alpha/charge']({ amount: '1' }),
+            'PATCH /v1/stream': handler['beta/charge']({ amount: '1' }),
+          },
+        }),
+      ],
+    })
+    proxyServer = await Http.createServer(proxy.listener)
+
+    const challengeResponse = await fetch(`${proxyServer.url}/api/v1/stream`)
+    expect(challengeResponse.status).toBe(402)
+
+    const challenge = Challenge.fromResponse(challengeResponse)
+    const authorization = Credential.serialize(
+      Credential.from({
+        challenge,
+        payload: { token: 'ok' },
+      }),
+    )
+
+    const res = await fetch(`${proxyServer.url}/api/v1/stream`, {
+      method: 'POST',
+      headers: { Authorization: authorization },
+    })
+
+    expect(res.status).toBe(204)
+  })
+
+  test('behavior: exact-match management POST does not forward upstream', async () => {
+    let upstreamRequests = 0
+    upstream = await createUpstream(() => {
+      upstreamRequests += 1
+      return Response.json({ ok: true })
+    })
+
+    const method = Method.from({
+      name: 'mock',
+      intent: 'charge',
+      schema: {
+        credential: { payload: z.object({ token: z.string() }) },
+        request: z.object({ amount: z.string() }),
+      },
+    })
+    const handler = Mppx_server.create({
+      methods: [
+        Method.toServer(method, {
+          async verify() {
+            return Receipt.from({
+              method: 'mock',
+              status: 'success',
+              timestamp: new Date().toISOString(),
+              reference: 'mock-reference',
+            })
+          },
+          respond() {
+            return new Response(null, { status: 204 })
+          },
+        }),
+      ],
+      secretKey,
+    })
+
+    const proxy = ApiProxy.create({
+      services: [
+        Service.from('api', {
+          baseUrl: upstream.url,
+          routes: {
+            'POST /v1/stream': handler['mock/charge']({ amount: '1' }),
+          },
+        }),
+      ],
+    })
+    proxyServer = await Http.createServer(proxy.listener)
+
+    const challengeResponse = await fetch(`${proxyServer.url}/api/v1/stream`, { method: 'POST' })
+    expect(challengeResponse.status).toBe(402)
+
+    const challenge = Challenge.fromResponse(challengeResponse)
+    const authorization = Credential.serialize(
+      Credential.from({
+        challenge,
+        payload: { token: 'ok' },
+      }),
+    )
+    const res = await fetch(`${proxyServer.url}/api/v1/stream`, {
+      method: 'POST',
+      headers: { Authorization: authorization },
+    })
+
+    expect(res.status).toBe(204)
+    expect(upstreamRequests).toBe(0)
+  })
+
+  test('behavior: paid GET fallback does not forward POST upstream', async () => {
+    let upstreamRequests = 0
+    upstream = await createUpstream(async (req) => {
+      upstreamRequests += 1
+      return Response.json({
+        body: await req.json(),
+        method: req.method,
+      })
+    })
+
+    const proxy = ApiProxy.create({
+      services: [
+        Service.from('api', {
+          baseUrl: upstream.url,
+          bearer: 'sk-upstream-key',
+          routes: { 'GET /v1/messages': mppx_server.charge({ amount: '1', decimals: 6 }) },
+        }),
+      ],
+    })
+    proxyServer = await Http.createServer(proxy.listener)
+
+    const challengeResponse = await fetch(`${proxyServer.url}/api/v1/messages`)
+    expect(challengeResponse.status).toBe(402)
+
+    const authorization = await mppx_client.createCredential(challengeResponse)
+    expect(Credential.extractPaymentScheme(authorization)).toBeTruthy()
+
+    const res = await fetch(`${proxyServer.url}/api/v1/messages`, {
+      method: 'POST',
+      headers: {
+        Authorization: authorization,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ prompt: 'hello' }),
+    })
+
+    expect(res.status).toBe(405)
+    expect(upstreamRequests).toBe(0)
+  })
+
   test('behavior: POST to unregistered method does not fall back to free GET route', async () => {
     upstream = await createUpstream(() => Response.json({ ok: true }))
     const proxy = ApiProxy.create({

package/src/proxy/Proxy.ts

@@ -2,6 +2,7 @@ import type * as http from 'node:http'
 
 import { createFetchProxy } from '@remix-run/fetch-proxy'
 
+import * as Credential from '../Credential.js'
 import { generateProxy } from '../discovery/OpenApi.js'
 import * as Request from '../server/Request.js'
 import * as Headers from './internal/Headers.js'
@@ -106,19 +107,26 @@ export function create(config: create.Config): Proxy {
 
     const { service, proxy } = entry
 
-    const matched =
-      Route.match(service.routes, request.method, upstreamPath) ??
-      // Management POSTs (e.g. session close) may target a path whose route
-      // is registered for a different HTTP method (e.g. GET). Fall back to
-      // path-only matching so the payment handler can process the action.
-      (request.method === 'POST' && request.headers.has('authorization')
-        ? Route.matchPath(
+    const exactMatch = Route.match(service.routes, request.method, upstreamPath)
+    const fallbackBinding =
+      !exactMatch && request.method === 'POST' && request.headers.has('authorization')
+        ? getPaymentBinding(request)
+        : null
+    const fallbackMatch =
+      !exactMatch && request.method === 'POST' && request.headers.has('authorization')
+        ? // Management POSTs (e.g. session close) may target a path whose route
+          // is registered for a different HTTP method (e.g. GET). Fall back to
+          // path-only matching so the payment handler can process the action.
+          // When the credential parses cleanly, also bind on payment method+intent
+          // so same-path paid routes can coexist without sharing credentials.
+          Route.matchPath(
             service.routes,
             upstreamPath,
             // skip free routes (e.g. `'GET /foo/bar': true`)
-            (endpoint) => endpoint !== true,
+            (endpoint) => endpoint !== true && matchesPaymentBinding(endpoint, fallbackBinding),
           )
-        : null)
+        : null
+    const matched = exactMatch ?? fallbackMatch
     if (!matched) return new Response('Not Found', { status: 404 })
 
     const endpoint = matched.value as Service.Endpoint
@@ -130,6 +138,22 @@ export function create(config: create.Config): Proxy {
     const result = await handler(request)
     if (result.status === 402) return result.challenge
 
+    const managementResponse = (() => {
+      try {
+        return (result.withReceipt as () => Response)()
+      } catch (error) {
+        if (
+          error instanceof Error &&
+          error.message === 'withReceipt() requires a response argument'
+        )
+          return null
+        throw error
+      }
+    })()
+
+    if (managementResponse) return managementResponse
+    if (fallbackMatch) return new Response('Method Not Allowed', { status: 405 })
+
     const options = Service.getOptions(endpoint)
     const upstreamRes = await proxyUpstream({
       request,
@@ -246,3 +270,28 @@ function withBasePath(basePath: string | undefined, path: string) {
   const trimmed = normalized.endsWith('/') ? normalized.slice(0, -1) : normalized
   return `${trimmed}${path}`
 }
+
+type PaymentBinding = {
+  intent: string
+  method: string
+}
+
+function getPaymentBinding(request: Request): PaymentBinding | null {
+  try {
+    const credential = Credential.fromRequest(request)
+    return {
+      intent: credential.challenge.intent,
+      method: credential.challenge.method,
+    }
+  } catch {
+    return null
+  }
+}
+
+function matchesPaymentBinding(endpoint: unknown, binding: PaymentBinding | null): boolean {
+  if (endpoint === true) return false
+  if (!binding) return true
+  const payment = Service.paymentOf(endpoint as Exclude<Service.Endpoint, true>)
+  if (!payment) return true
+  return payment.method === binding.method && payment.intent === binding.intent
+}

package/src/proxy/internal/Route.test.ts

@@ -193,6 +193,15 @@ describe('matchPath', () => {
     expect(result).toMatchObject({ key: 'POST /v1/*' })
   })
 
+  // TODO (brendanryan): Relax this if `matchPath()` gains method-aware disambiguation.
+  test('error: returns null when multiple paid routes share the same path', () => {
+    const routes = {
+      'GET /v1/stream': { pay: () => {} },
+      'POST /v1/stream': { pay: () => {} },
+    }
+    expect(Route.matchPath(routes, '/v1/stream', paidOnly)).toBeNull()
+  })
+
   test('error: returns null when all routes are free', () => {
     const routes = {
       'GET /v1/models': true,

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', () => {