mppx 0.3.9 → 0.3.11

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,
+  })
+}

package/src/tempo/server/Charge.test.ts

@@ -524,6 +524,68 @@ describe('tempo', () => {
     })
   })
 
+  describe('intent: charge; type: transaction; waitForConfirmation: false', () => {
+    test('returns receipt without waiting for confirmation', async () => {
+      const serverNoWait = Mppx_server.create({
+        methods: [
+          tempo_server.charge({
+            getClient() {
+              return client
+            },
+            currency: asset,
+            account: accounts[0],
+            waitForConfirmation: false,
+          }),
+        ],
+        realm,
+        secretKey,
+      })
+
+      const mppx = Mppx_client.create({
+        polyfill: false,
+        methods: [
+          tempo_client({
+            account: accounts[1],
+            getClient() {
+              return client
+            },
+          }),
+        ],
+      })
+
+      const httpServer = await Http.createServer(async (req, res) => {
+        const result = await Mppx_server.toNodeListener(
+          serverNoWait.charge({
+            amount: '1',
+            currency: asset,
+            recipient: accounts[0].address,
+          }),
+        )(req, res)
+        if (result.status === 402) return
+        res.end('OK')
+      })
+
+      const response = await fetch(httpServer.url)
+      expect(response.status).toBe(402)
+
+      const credential = await mppx.createCredential(response)
+
+      {
+        const response = await fetch(httpServer.url, {
+          headers: { Authorization: credential },
+        })
+        expect(response.status).toBe(200)
+
+        const receipt = Receipt.fromResponse(response)
+        expect(receipt.status).toBe('success')
+        expect(receipt.method).toBe('tempo')
+        expect(receipt.reference).toBeDefined()
+      }
+
+      httpServer.close()
+    })
+  })
+
   describe('intent: unknown', () => {
     test('behavior: returns 402 for invalid payload schema', async () => {
       const httpServer = await Http.createServer(async (req, res) => {

package/src/tempo/server/Charge.ts

@@ -5,7 +5,12 @@ import {
   type TransactionReceipt,
   toFunctionSelector,
 } from 'viem'
-import { getTransactionReceipt, sendRawTransactionSync, signTransaction } from 'viem/actions'
+import {
+  getTransactionReceipt,
+  sendRawTransaction,
+  sendRawTransactionSync,
+  signTransaction,
+} from 'viem/actions'
 import { tempo as tempo_chain } from 'viem/chains'
 import { Abis, Transaction } from 'viem/tempo'
 import { PaymentExpiredError } from '../../Errors.js'
@@ -14,6 +19,7 @@ import * as Method from '../../Method.js'
 import * as Client from '../../viem/Client.js'
 import * as Account from '../internal/account.js'
 import * as defaults from '../internal/defaults.js'
+import { simulateTransaction } from '../internal/simulate.js'
 import type * as types from '../internal/types.js'
 import * as Methods from '../Methods.js'
 
@@ -45,6 +51,7 @@ export function charge<const parameters extends charge.Parameters>(
     description,
     externalId,
     memo,
+    waitForConfirmation = true,
   } = parameters
 
   const { recipient, feePayer } = Account.resolve(parameters)
@@ -250,11 +257,30 @@ export function charge<const parameters extends charge.Parameters>(
             return serializedTransaction
           })()
 
-          const receipt = await sendRawTransactionSync(client, {
-            serializedTransaction: serializedTransaction_final,
-          })
-
-          return toReceipt(receipt)
+          if (waitForConfirmation) {
+            const receipt = await sendRawTransactionSync(client, {
+              serializedTransaction: serializedTransaction_final,
+            })
+            return toReceipt(receipt)
+          } else {
+            // Optimistic path: simulate to catch obvious reverts, then broadcast
+            // without waiting for on-chain confirmation. The returned receipt
+            // assumes success — callers opt into this risk via waitForConfirmation: false.
+            await simulateTransaction(client, {
+              ...transaction,
+              from: transaction.from as `0x${string}`,
+              calls,
+            })
+            const hash = await sendRawTransaction(client, {
+              serializedTransaction: serializedTransaction_final,
+            })
+            return {
+              method: 'tempo',
+              status: 'success',
+              timestamp: new Date().toISOString(),
+              reference: hash,
+            } as const
+          }
         }
 
         default:
@@ -270,6 +296,18 @@ export declare namespace charge {
   type Parameters = {
     /** Testnet mode. */
     testnet?: boolean | undefined
+    /**
+     * Whether to wait for the charge transaction to confirm on-chain before
+     * responding. @default true
+     *
+     * When `false`, the transaction is simulated via `eth_estimateGas` and
+     * broadcast without waiting for inclusion. The receipt will optimistically
+     * report `status: 'success'` based on simulation alone — if the
+     * transaction reverts on-chain after broadcast (e.g. due to a state
+     * change between simulation and inclusion), the receipt will not reflect
+     * the failure.
+     */
+    waitForConfirmation?: boolean | undefined
   } & Client.getResolver.Parameters &
     Account.resolve.Parameters &
     Defaults