mppx 0.3.8 → 0.3.11

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mppx",
   "type": "module",
-  "version": "0.3.8",
+  "version": "0.3.11",
   "main": "./dist/index.js",
   "license": "MIT",
   "files": [

package/src/Challenge.ts

@@ -336,6 +336,8 @@ export function deserialize<const methods extends readonly Method.Method[] | und
 
   const { request, opaque, ...rest } = result
   if (!request) throw new Error('Missing request parameter.')
+  if (rest.method && !/^[a-z][a-z0-9:_-]*$/.test(rest.method))
+    throw new Error(`Invalid method: "${rest.method}". Must be lowercase per spec.`)
 
   return from(
     {

package/src/Errors.test.ts

@@ -10,6 +10,7 @@ import {
   InvalidPayloadError,
   InvalidSignatureError,
   MalformedCredentialError,
+  PaymentActionRequiredError,
   PaymentExpiredError,
   PaymentInsufficientError,
   PaymentMethodUnsupportedError,
@@ -165,27 +166,12 @@ describe('PaymentRequiredError', () => {
     `)
   })
 
-  test('with realm', () => {
+  test('with description', () => {
     expect(
-      errorSnapshot(new PaymentRequiredError({ realm: 'api.example.com' })),
+      errorSnapshot(new PaymentRequiredError({ description: 'API access fee' })),
     ).toMatchInlineSnapshot(`
         {
-          "message": "Payment is required for "api.example.com".",
-          "name": "PaymentRequiredError",
-          "status": 402,
-          "type": "https://paymentauth.org/problems/payment-required",
-        }
-      `)
-  })
-
-  test('with realm and description', () => {
-    expect(
-      errorSnapshot(
-        new PaymentRequiredError({ realm: 'api.example.com', description: 'API access fee' }),
-      ),
-    ).toMatchInlineSnapshot(`
-        {
-          "message": "Payment is required for "api.example.com" (API access fee).",
+          "message": "Payment is required (API access fee).",
           "name": "PaymentRequiredError",
           "status": 402,
           "type": "https://paymentauth.org/problems/payment-required",
@@ -428,6 +414,45 @@ describe('ChannelClosedError', () => {
   })
 })
 
+describe('PaymentActionRequiredError', () => {
+  test('default', () => {
+    expect(errorSnapshot(new PaymentActionRequiredError())).toMatchInlineSnapshot(`
+      {
+        "message": "Payment requires action.",
+        "name": "PaymentActionRequiredError",
+        "status": 402,
+        "type": "https://paymentauth.org/problems/payment-action-required",
+      }
+    `)
+  })
+
+  test('with reason', () => {
+    expect(
+      errorSnapshot(new PaymentActionRequiredError({ reason: 'requires_action' })),
+    ).toMatchInlineSnapshot(`
+        {
+          "message": "Payment requires action: requires_action.",
+          "name": "PaymentActionRequiredError",
+          "status": 402,
+          "type": "https://paymentauth.org/problems/payment-action-required",
+        }
+      `)
+  })
+
+  test('toProblemDetails', () => {
+    const error = new PaymentActionRequiredError({ reason: 'Stripe PaymentIntent requires action' })
+    expect(error.toProblemDetails('ch_123')).toMatchInlineSnapshot(`
+      {
+        "challengeId": "ch_123",
+        "detail": "Payment requires action: Stripe PaymentIntent requires action.",
+        "status": 402,
+        "title": "Payment Action Required",
+        "type": "https://paymentauth.org/problems/payment-action-required",
+      }
+    `)
+  })
+})
+
 describe('toProblemDetails', () => {
   test('without challengeId', () => {
     const error = new MalformedCredentialError({ reason: 'invalid JSON' })

package/src/Errors.ts

@@ -158,9 +158,8 @@ export class PaymentRequiredError extends PaymentError {
   readonly type = 'https://paymentauth.org/problems/payment-required'
 
   constructor(options: PaymentRequiredError.Options = {}) {
-    const { description, realm } = options
+    const { description } = options
     const parts = ['Payment is required']
-    if (realm) parts.push(`for "${realm}"`)
     if (description) parts.push(`(${description})`)
     super(`${parts.join(' ')}.`)
   }
@@ -170,8 +169,6 @@ export declare namespace PaymentRequiredError {
   type Options = {
     /** Human-readable description of the payment. */
     description?: string | undefined
-    /** Server realm (e.g., hostname). */
-    realm?: string | undefined
   }
 }
 

package/src/client/Mppx.test.ts

@@ -295,6 +295,7 @@ const server = Mppx_server.create({
       recipient: accounts[0].address,
     }),
   ],
+  secretKey,
 })
 
 describe('fetch', () => {

package/src/internal/constantTimeEqual.ts

@@ -1,7 +1,8 @@
+import { createHash, timingSafeEqual } from 'node:crypto'
+
 /** Constant-time string comparison to prevent timing attacks. */
 export function constantTimeEqual(a: string, b: string): boolean {
-  if (a.length !== b.length) return false
-  let result = 0
-  for (let i = 0; i < a.length; i++) result |= a.charCodeAt(i) ^ b.charCodeAt(i)
-  return result === 0
+  const hashA = createHash('sha256').update(a).digest()
+  const hashB = createHash('sha256').update(b).digest()
+  return timingSafeEqual(hashA, hashB)
 }

package/src/internal/env.test.ts

@@ -9,8 +9,8 @@ describe('Env.get', () => {
     expect(Env.get('realm')).toBe('MPP Payment')
   })
 
-  test('returns default secretKey when MPP_SECRET_KEY is not set', () => {
-    expect(Env.get('secretKey')).toBe('tmp')
+  test('returns undefined when MPP_SECRET_KEY is not set', () => {
+    expect(Env.get('secretKey')).toBeUndefined()
   })
 
   test('returns MPP_SECRET_KEY when set', () => {

package/src/internal/env.ts

@@ -17,13 +17,12 @@ const variables = {
 /** Fallback values when no environment variable is set. */
 const defaults = {
   realm: 'MPP Payment',
-  secretKey: 'tmp',
-} as const satisfies Record<keyof typeof variables, string>
+} as const satisfies Partial<Record<keyof typeof variables, string>>
 
 /**
  * Resolves a configuration value from environment variables.
  *
- * Checks platform-specific env vars in order, falling back to a default.
+ * Checks platform-specific env vars in order, falling back to a default if one exists.
  *
  * @example
  * ```ts
@@ -31,12 +30,12 @@ const defaults = {
  * Env.get('secretKey') // e.g. value of MPP_SECRET_KEY
  * ```
  */
-export function get(key: keyof typeof variables): string {
+export function get(key: keyof typeof variables): string | undefined {
   for (const name of variables[key]) {
     const value = read(name)
     if (value) return value
   }
-  return defaults[key]
+  return (defaults as Record<string, string | undefined>)[key]
 }
 
 /** Reads a single environment variable, probing available runtime APIs. */

package/src/middlewares/express.test.ts

@@ -21,6 +21,8 @@ function createServer(app: express.Express) {
   })
 }
 
+const secretKey = 'test-secret-key'
+
 describe('charge', () => {
   const mppx = Mppx.create({
     methods: [
@@ -30,6 +32,7 @@ describe('charge', () => {
         recipient: accounts[0].address,
       }),
     ],
+    secretKey,
   })
 
   const { fetch } = Mppx_client.create({
@@ -99,6 +102,7 @@ describe('session', () => {
           escrowContract,
         }),
       ],
+      secretKey,
     })
 
     const app = express()
@@ -125,6 +129,7 @@ describe('session', () => {
           feePayer: accounts[0],
         }),
       ],
+      secretKey,
     })
 
     const { fetch } = Mppx_client.create({

package/src/middlewares/hono.test.ts

@@ -21,6 +21,8 @@ function createServer(app: Hono) {
   })
 }
 
+const secretKey = 'test-secret-key'
+
 describe('charge', () => {
   const mppx = Mppx.create({
     methods: [
@@ -30,6 +32,7 @@ describe('charge', () => {
         recipient: accounts[0].address,
       }),
     ],
+    secretKey,
   })
 
   const { fetch } = Mppx_client.create({
@@ -92,6 +95,7 @@ describe('session', () => {
           escrowContract,
         }),
       ],
+      secretKey,
     })
 
     const app = new Hono()
@@ -118,6 +122,7 @@ describe('session', () => {
           feePayer: accounts[0],
         }),
       ],
+      secretKey,
     })
 
     const { fetch } = Mppx_client.create({

package/src/middlewares/internal/mppx.ts

@@ -23,8 +23,11 @@ export function wrap<mppx extends Mppx.Mppx<any, any>, handler>(
 ): Wrap<mppx, handler> {
   const result: Record<string, unknown> = { ...mppx }
   for (const mi of mppx.methods as readonly Method.AnyServer[]) {
-    const methodFn = (mppx as any)[mi.intent]
-    result[mi.intent] = (options: any) => wrapper(methodFn, options)
+    const key = `${mi.name}/${mi.intent}`
+    const methodFn = (mppx as any)[key]
+    result[key] = (options: any) => wrapper(methodFn, options)
+    // Also set shorthand intent key if Mppx registered it (no collision)
+    if ((mppx as any)[mi.intent]) result[mi.intent] = (options: any) => wrapper(methodFn, options)
   }
   return result as never
 }

package/src/middlewares/nextjs.test.ts

@@ -33,6 +33,8 @@ function createServer(handler: (request: Request) => Promise<Response> | Respons
   })
 }
 
+const secretKey = 'test-secret-key'
+
 describe('charge', () => {
   const mppx = Mppx.create({
     methods: [
@@ -42,6 +44,7 @@ describe('charge', () => {
         recipient: accounts[0].address,
       }),
     ],
+    secretKey,
   })
 
   const { fetch } = Mppx_client.create({
@@ -106,6 +109,7 @@ describe('session', () => {
           escrowContract,
         }),
       ],
+      secretKey,
     })
 
     const handler = mppx.session({ amount: '1', unitType: 'token' })(() =>
@@ -131,6 +135,7 @@ describe('session', () => {
           feePayer: accounts[0],
         }),
       ],
+      secretKey,
     })
 
     const { fetch } = Mppx_client.create({

package/src/proxy/Proxy.test.ts

@@ -9,6 +9,8 @@ import * as Service from './Service.js'
 import { anthropic } from './services/anthropic.js'
 import { openai } from './services/openai.js'
 
+const secretKey = 'test-secret-key'
+
 const mppx_server = Mppx_server.create({
   methods: [
     tempo_server({
@@ -18,6 +20,7 @@ const mppx_server = Mppx_server.create({
       feePayer: true,
     }),
   ],
+  secretKey,
 })
 
 const mppx_client = Mppx_client.create({

package/src/proxy/services/openai.test.ts

@@ -10,6 +10,8 @@ import { openai } from './openai.js'
 const apiKey = process.env.VITE_OPENAI_API_KEY
 if (!apiKey) console.warn('OPENAI_API_KEY not set — openai proxy tests will be skipped')
 
+const secretKey = 'test-secret-key'
+
 const mppx_server = Mppx_server.create({
   methods: [
     tempo_server({
@@ -18,6 +20,7 @@ const mppx_server = Mppx_server.create({
       getClient: () => client,
     }),
   ],
+  secretKey,
 })
 
 const mppx_client = Mppx_client.create({

package/src/server/Mppx.test.ts

@@ -53,7 +53,7 @@ describe('request handler', () => {
     }).toMatchInlineSnapshot(`
       {
         "challengeId": "[challengeId]",
-        "detail": "Payment is required for "api.example.com".",
+        "detail": "Payment is required.",
         "instance": "[instance]",
         "status": 402,
         "title": "Payment Required",
@@ -138,6 +138,97 @@ describe('request handler', () => {
     `)
   })
 
+  test('returns 402 when credential is from a different route (cross-route scope confusion)', async () => {
+    const handler = Mppx.create({ methods: [method], realm, secretKey })
+
+    // Get a challenge from the "cheap" route
+    const cheapHandle = handler.charge({
+      amount: '1',
+      currency: asset,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: accounts[0].address,
+    })
+    const cheapResult = await cheapHandle(new Request('https://example.com/cheap'))
+    expect(cheapResult.status).toBe(402)
+    if (cheapResult.status !== 402) throw new Error()
+
+    const cheapChallenge = Challenge.fromResponse(cheapResult.challenge)
+
+    // Build a credential from the cheap challenge
+    const credential = Credential.from({
+      challenge: cheapChallenge,
+      payload: { signature: '0x123', type: 'transaction' },
+    })
+
+    // Present it at the "expensive" route
+    const expensiveHandle = handler.charge({
+      amount: '1000000',
+      currency: asset,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: accounts[0].address,
+    })
+    const result = await expensiveHandle(
+      new Request('https://example.com/expensive', {
+        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).toContain('does not match')
+  })
+
+  test('returns 402 when credential challenge is expired', async () => {
+    const pastExpires = new Date(Date.now() - 60_000).toISOString()
+
+    const handle = Mppx.create({ methods: [method], realm, secretKey }).charge({
+      amount: '1000',
+      currency: asset,
+      expires: pastExpires,
+      recipient: accounts[0].address,
+    })
+
+    // Get a fresh challenge (which has the expired timestamp baked in)
+    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: { signature: '0x123', type: 'transaction' },
+    })
+
+    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 object
+    expect({
+      ...body,
+      challengeId: '[challengeId]',
+      detail: '[detail]',
+      instance: '[instance]',
+    }).toMatchInlineSnapshot(`
+      {
+        "challengeId": "[challengeId]",
+        "detail": "[detail]",
+        "instance": "[instance]",
+        "status": 402,
+        "title": "Payment Expired",
+        "type": "https://paymentauth.org/problems/payment-expired",
+      }
+    `)
+    expect((body as { detail: string }).detail).toContain('Payment expired at')
+  })
   test('returns 402 when payload schema validation fails', async () => {
     const handle = Mppx.create({ methods: [method], realm, secretKey }).charge({
       amount: '1000',
@@ -215,7 +306,7 @@ describe('request handler (node)', () => {
     }).toMatchInlineSnapshot(`
       {
         "challengeId": "[challengeId]",
-        "detail": "Payment is required for "api.example.com".",
+        "detail": "Payment is required.",
         "instance": "[instance]",
         "status": 402,
         "title": "Payment Required",

package/src/server/Mppx.ts

@@ -41,17 +41,43 @@ type EffectiveTransportOf<mi, defaultTransport extends Transport.AnyTransport> =
   ? defaultTransport
   : TransportOverrideOf<mi>
 
-type Handlers<
+/** True when exactly one method has the given intent (no name collision). */
+type IsUniqueIntent<methods extends readonly Method.AnyServer[], intent extends string> = Extract<
+  methods[number],
+  { intent: intent }
+> extends infer M
+  ? M extends M
+    ? [Exclude<Extract<methods[number], { intent: intent }>, M>] extends [never]
+      ? true
+      : false
+    : never
+  : never
+
+/** Only includes shorthand intent keys when the intent is unique across methods. */
+type UniqueIntentHandlers<
   methods extends readonly Method.AnyServer[],
   transport extends Transport.AnyTransport,
 > = {
-  [method_name in methods[number]['intent']]: MethodFn<
+  [method_name in methods[number]['intent'] as IsUniqueIntent<methods, method_name> extends true
+    ? method_name
+    : never]: MethodFn<
     Extract<methods[number], { intent: method_name }>,
     EffectiveTransportOf<Extract<methods[number], { intent: method_name }>, transport>,
     NonNullable<Extract<methods[number], { intent: method_name }>['defaults']>
   >
 }
 
+type Handlers<
+  methods extends readonly Method.AnyServer[],
+  transport extends Transport.AnyTransport,
+> = {
+  [mi in methods[number] as `${mi['name']}/${mi['intent']}`]: MethodFn<
+    mi,
+    EffectiveTransportOf<mi, transport>,
+    NonNullable<mi['defaults']>
+  >
+} & UniqueIntentHandlers<methods, transport>
+
 /**
  * Creates a server-side payment handler from methods.
  *
@@ -73,17 +99,25 @@ export function create<
   const transport extends Transport.AnyTransport = Transport.Http,
 >(config: create.Config<methods, transport>): Mppx<methods, transport> {
   const {
-    realm = Env.get('realm'),
+    realm = Env.get('realm') ?? 'MPP Payment',
     secretKey = Env.get('secretKey'),
     transport = Transport.http() as transport,
   } = config
 
+  if (!secretKey) {
+    throw new Error(
+      'Missing secret key. Set the MPP_SECRET_KEY environment variable or pass `secretKey` to Mppx.create().',
+    )
+  }
+
   const methods = config.methods.flat() as unknown as FlattenMethods<methods>
 
   const handlers: Record<string, unknown> = {}
+  const intentCount: Record<string, number> = {}
 
   for (const mi of methods) {
-    handlers[mi.intent] = createMethodFn({
+    intentCount[mi.intent] = (intentCount[mi.intent] ?? 0) + 1
+    handlers[`${mi.name}/${mi.intent}`] = createMethodFn({
       defaults: mi.defaults,
       method: mi,
       realm,
@@ -95,6 +129,11 @@ export function create<
     })
   }
 
+  // Also set shorthand intent key when there's no collision
+  for (const mi of methods) {
+    if (intentCount[mi.intent] === 1) handlers[mi.intent] = handlers[`${mi.name}/${mi.intent}`]
+  }
+
   return { methods, realm: realm as string, transport, ...handlers } as never
 }
 
@@ -107,7 +146,7 @@ export declare namespace create {
     methods: methods
     /** Server realm (e.g., hostname). Auto-detected from environment variables (`MPP_REALM`, `VERCEL_URL`, `RAILWAY_PUBLIC_DOMAIN`, `RENDER_EXTERNAL_HOSTNAME`, `HOST`, `HOSTNAME`), falling back to `"localhost"`. */
     realm?: string | undefined
-    /** Secret key for HMAC-bound challenge IDs for stateless verification. Auto-detected from `MPP_SECRET_KEY` environment variable, falling back to a random key. */
+    /** Secret key for HMAC-bound challenge IDs for stateless verification. Auto-detected from `MPP_SECRET_KEY` environment variable. Throws if neither provided nor set. */
     secretKey?: string | undefined
     /** Transport to use. @default Transport.http() */
     transport?: transport | undefined
@@ -185,7 +224,7 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
           const response = await transport.respondChallenge({
             challenge,
             input,
-            error: new Errors.PaymentRequiredError({ realm, description }),
+            error: new Errors.PaymentRequiredError({ description }),
           })
           return { challenge: response, status: 402 }
         }
@@ -204,6 +243,42 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
           return { challenge: response, status: 402 }
         }
 
+        // Verify the credential's challenge matches this route's configured
+        // request. Prevents cross-route scope confusion where a credential
+        // issued for a cheap route is presented at an expensive route.
+        {
+          const routeReq = challenge.request as Record<string, unknown>
+          const echoedReq = credential.challenge.request as Record<string, unknown>
+          for (const field of ['amount', 'currency', 'recipient'] as const) {
+            if (
+              routeReq[field] !== undefined &&
+              echoedReq[field] !== undefined &&
+              String(routeReq[field]) !== String(echoedReq[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 }
+            }
+          }
+        }
+
+        // Reject expired credentials
+        if (credential.challenge.expires && new Date(credential.challenge.expires) < new Date()) {
+          const response = await transport.respondChallenge({
+            challenge,
+            input,
+            error: new Errors.PaymentExpiredError({
+              expires: credential.challenge.expires,
+            }),
+          })
+          return { challenge: response, status: 402 }
+        }
         // Validate payload structure against method schema
         try {
           method.schema.credential.payload.parse(credential.payload)

package/src/tempo/internal/simulate.ts

@@ -0,0 +1,49 @@
+import type { Address, Client } from 'viem'
+
+/**
+ * Simulate a Tempo transaction via `eth_estimateGas` to catch reverts
+ * (e.g. insufficient balance, invalid calls) before broadcasting.
+ */
+export async function simulateTransaction(
+  client: Client,
+  transaction: {
+    from: Address
+    chainId: number
+    nonce?: number | bigint | undefined
+    maxFeePerGas?: bigint | undefined
+    maxPriorityFeePerGas?: bigint | undefined
+    feeToken?: string | bigint | undefined
+    nonceKey?: bigint | undefined
+    validBefore?: number | undefined
+    calls?: readonly {
+      to?: string | undefined
+      value?: bigint | undefined
+      data?: string | undefined
+    }[]
+  },
+): Promise<void> {
+  const simCalls = (transaction.calls ?? []).map((c) => ({
+    to: c.to,
+    value: c.value ? `0x${c.value.toString(16)}` : '0x0',
+    input: c.data ?? '0x',
+  }))
+  await client.request({
+    method: 'eth_estimateGas' as never,
+    params: [
+      {
+        from: transaction.from,
+        chainId: `0x${transaction.chainId.toString(16)}`,
+        nonce: `0x${BigInt(transaction.nonce ?? 0).toString(16)}`,
+        gas: '0x2dc6c0', // 3M cap
+        maxFeePerGas: `0x${(transaction.maxFeePerGas ?? 0n).toString(16)}`,
+        maxPriorityFeePerGas: `0x${(transaction.maxPriorityFeePerGas ?? 0n).toString(16)}`,
+        feeToken: transaction.feeToken,
+        nonceKey: `0x${(transaction.nonceKey ?? 0n).toString(16)}`,
+        calls: simCalls,
+        ...(transaction.validBefore
+          ? { validBefore: `0x${transaction.validBefore.toString(16)}` }
+          : {}),
+      },
+    ] as never,
+  })
+}