mppx 0.3.9 → 0.3.12

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/client/Charge.ts

@@ -1,4 +1,5 @@
 import type * as Hex from 'ox/Hex'
+import type { Address } from 'viem'
 import { prepareTransactionRequest, signTransaction } from 'viem/actions'
 import { tempo as tempo_chain } from 'viem/chains'
 import { Actions } from 'viem/tempo'
@@ -8,6 +9,7 @@ import * as Account from '../../viem/Account.js'
 import * as Client from '../../viem/Client.js'
 import * as z from '../../zod.js'
 import * as Attribution from '../Attribution.js'
+import * as AutoSwap from '../internal/auto-swap.js'
 import * as defaults from '../internal/defaults.js'
 import * as Methods from '../Methods.js'
 
@@ -36,6 +38,7 @@ export function charge(parameters: charge.Parameters = {}) {
   return Method.toClient(Methods.charge, {
     context: z.object({
       account: z.optional(z.custom<Account.getResolver.Parameters['account']>()),
+      autoSwap: z.optional(z.custom<charge.AutoSwap>()),
     }),
 
     async createCredential({ challenge, context }) {
@@ -44,22 +47,41 @@ export function charge(parameters: charge.Parameters = {}) {
       const account = getAccount(client, context)
 
       const { request } = challenge
-      const { amount, currency, recipient, methodDetails } = request
+      const { amount, methodDetails } = request
+      const currency = request.currency as Address
+      const recipient = request.recipient as Address
 
       const memo = methodDetails?.memo
         ? (methodDetails.memo as Hex.Hex)
         : Attribution.encode({ serverId: challenge.realm, clientId })
 
+      const transferCall = Actions.token.transfer.call({
+        amount: BigInt(amount),
+        memo,
+        to: recipient,
+        token: currency,
+      })
+
+      const autoSwap = AutoSwap.resolve(
+        context?.autoSwap ?? parameters.autoSwap,
+        AutoSwap.defaultCurrencies,
+      )
+
+      const swapCalls = autoSwap
+        ? await AutoSwap.findCalls(client, {
+            account: account.address,
+            amountOut: BigInt(amount),
+            tokenOut: currency,
+            tokenIn: autoSwap.tokenIn,
+            slippage: autoSwap.slippage,
+          })
+        : undefined
+
+      const calls = [...(swapCalls ?? []), transferCall]
+
       const prepared = await prepareTransactionRequest(client, {
         account,
-        calls: [
-          Actions.token.transfer.call({
-            amount: BigInt(amount),
-            memo,
-            to: recipient as Hex.Hex,
-            token: currency as Hex.Hex,
-          }),
-        ],
+        calls,
         ...(methodDetails?.feePayer && { feePayer: true }),
         nonceKey: 'expiring',
       } as never)
@@ -77,7 +99,16 @@ export function charge(parameters: charge.Parameters = {}) {
 }
 
 export declare namespace charge {
+  type AutoSwap = AutoSwap.resolve.Value
+
   type Parameters = {
+    /**
+     * Automatically swap from a fallback currency (pathUsd, USDC.e) via the
+     * Tempo DEX when the user lacks sufficient balance of the target currency.
+     *
+     * @default false
+     */
+    autoSwap?: AutoSwap | undefined
     /** Client identifier used to derive the client fingerprint in attribution memos. */
     clientId?: string | undefined
   } & Account.getResolver.Parameters &

package/src/tempo/internal/auto-swap.test.ts

@@ -0,0 +1,113 @@
+import type { Address } from 'viem'
+import { describe, expect, test } from 'vitest'
+import { defaultCurrencies, InsufficientFundsError, resolve } from './auto-swap.js'
+
+describe('defaultCurrencies', () => {
+  test('default', () => {
+    expect(defaultCurrencies).toMatchInlineSnapshot(`
+      [
+        "0x20c0000000000000000000000000000000000000",
+        "0x20C000000000000000000000b9537d11c60E8b50",
+      ]
+    `)
+  })
+})
+
+describe('resolve', () => {
+  const defaults = defaultCurrencies
+
+  test('returns false for undefined', () => {
+    expect(resolve(undefined, defaults)).toMatchInlineSnapshot(`false`)
+  })
+
+  test('returns false for false', () => {
+    expect(resolve(false, defaults)).toMatchInlineSnapshot(`false`)
+  })
+
+  test('true resolves to defaults with 1% slippage', () => {
+    expect(resolve(true, defaults)).toMatchInlineSnapshot(`
+      {
+        "slippage": 1,
+        "tokenIn": [
+          "0x20c0000000000000000000000000000000000000",
+          "0x20C000000000000000000000b9537d11c60E8b50",
+        ],
+      }
+    `)
+  })
+
+  test('empty options resolves to defaults with 1% slippage', () => {
+    expect(resolve({}, defaults)).toMatchInlineSnapshot(`
+      {
+        "slippage": 1,
+        "tokenIn": [
+          "0x20c0000000000000000000000000000000000000",
+          "0x20C000000000000000000000b9537d11c60E8b50",
+        ],
+      }
+    `)
+  })
+
+  test('custom slippage', () => {
+    expect(resolve({ slippage: 5 }, defaults)).toMatchInlineSnapshot(`
+      {
+        "slippage": 5,
+        "tokenIn": [
+          "0x20c0000000000000000000000000000000000000",
+          "0x20C000000000000000000000b9537d11c60E8b50",
+        ],
+      }
+    `)
+  })
+
+  test('custom tokenIn prepends to defaults', () => {
+    const custom = '0x0000000000000000000000000000000000000099' as Address
+    expect(resolve({ tokenIn: [custom] }, defaults)).toMatchInlineSnapshot(`
+      {
+        "slippage": 1,
+        "tokenIn": [
+          "0x0000000000000000000000000000000000000099",
+          "0x20c0000000000000000000000000000000000000",
+          "0x20C000000000000000000000b9537d11c60E8b50",
+        ],
+      }
+    `)
+  })
+
+  test('custom tokenIn deduplicates against defaults', () => {
+    expect(resolve({ tokenIn: [defaults[0]!] }, defaults)).toMatchInlineSnapshot(`
+      {
+        "slippage": 1,
+        "tokenIn": [
+          "0x20c0000000000000000000000000000000000000",
+          "0x20C000000000000000000000b9537d11c60E8b50",
+        ],
+      }
+    `)
+  })
+
+  test('custom tokenIn + custom slippage', () => {
+    const custom = '0x0000000000000000000000000000000000000099' as Address
+    expect(resolve({ tokenIn: [custom], slippage: 3 }, defaults)).toMatchInlineSnapshot(`
+      {
+        "slippage": 3,
+        "tokenIn": [
+          "0x0000000000000000000000000000000000000099",
+          "0x20c0000000000000000000000000000000000000",
+          "0x20C000000000000000000000b9537d11c60E8b50",
+        ],
+      }
+    `)
+  })
+})
+
+describe('InsufficientFundsError', () => {
+  test('default', () => {
+    const error = new InsufficientFundsError({
+      currency: '0x0000000000000000000000000000000000000001',
+    })
+    expect(error).toMatchInlineSnapshot(
+      `[InsufficientFundsError: Insufficient funds: no balance in 0x0000000000000000000000000000000000000001 and no viable swap route from fallback currencies.]`,
+    )
+  })
+})

package/src/tempo/internal/auto-swap.ts

@@ -0,0 +1,141 @@
+import type { Address, Client } from 'viem'
+import { isAddressEqual } from 'viem'
+import { readContract } from 'viem/actions'
+import { Actions, Addresses } from 'viem/tempo'
+import * as defaults from './defaults.js'
+
+/** Basis-point denominator (100% = 10 000 bps). */
+const bps = 10_000n
+
+/** Default fallback currencies for auto-swap, in priority order. */
+export const defaultCurrencies: readonly Address[] = [
+  defaults.tokens.pathUsd as Address,
+  defaults.tokens.usdc as Address,
+]
+
+/**
+ * Finds the optimal swap calls to acquire `amountOut` of `tokenOut`,
+ * returning an approve + buy call sequence if a viable route is found.
+ *
+ * Returns `undefined` if the account already holds enough of `tokenOut`
+ * or no viable swap route exists from the given input tokens.
+ */
+export async function findCalls(
+  client: Client,
+  parameters: findCalls.Parameters,
+): Promise<findCalls.ReturnType> {
+  const { account, amountOut, tokenOut, tokenIn, slippage } = parameters
+
+  const candidates = tokenIn.filter((t) => !isAddressEqual(t, tokenOut))
+
+  const balanceResults = await Promise.allSettled([
+    readContract(client, Actions.token.getBalance.call({ account, token: tokenOut }) as never),
+    ...candidates.map((t) =>
+      readContract(client, Actions.token.getBalance.call({ account, token: t }) as never),
+    ),
+  ])
+
+  // If the account already has enough of the target token, no swap needed.
+  const targetBalance = balanceResults[0]!
+  if (targetBalance.status === 'fulfilled' && (targetBalance.value as bigint) >= amountOut)
+    return undefined
+
+  // Find first candidate with enough balance to cover a swap.
+  for (let i = 0; i < candidates.length; i++) {
+    const result = balanceResults[i + 1]!
+    if (result.status !== 'fulfilled') continue
+
+    const balance = result.value as bigint
+    if (balance <= 0n) continue
+
+    const tokenIn = candidates[i]!
+
+    try {
+      const quotedAmountIn = await Actions.dex.getBuyQuote(client as never, {
+        tokenIn,
+        tokenOut,
+        amountOut,
+      })
+
+      if (balance >= quotedAmountIn) {
+        const maxAmountIn =
+          quotedAmountIn + (quotedAmountIn * BigInt(Math.round(slippage * 100))) / bps
+        return [
+          Actions.token.approve.call({
+            token: tokenIn,
+            spender: Addresses.stablecoinDex,
+            amount: maxAmountIn,
+          }),
+          Actions.dex.buy.call({
+            tokenIn,
+            tokenOut,
+            amountOut,
+            maxAmountIn,
+          }),
+        ]
+      }
+    } catch {}
+  }
+
+  throw new InsufficientFundsError({ currency: tokenOut })
+}
+
+export declare namespace findCalls {
+  type Parameters = {
+    /** Address of the account to check balances for. */
+    account: Address
+    /** Amount of the target token needed. */
+    amountOut: bigint
+    /** Candidate input tokens to swap from, in priority order. */
+    tokenIn: readonly Address[]
+    /** Max slippage tolerance as a percentage (e.g. `1` = 1%). */
+    slippage: number
+    /** Address of the target token to acquire. */
+    tokenOut: Address
+  }
+
+  /** `undefined` when no swap is needed (account has sufficient balance). */
+  type ReturnType = readonly object[] | undefined
+}
+
+/** Resolves an auto-swap configuration value into concrete currencies and slippage. */
+export function resolve(
+  value: resolve.Value | undefined,
+  defaultCurrencies: readonly Address[],
+): resolve.Resolved | false {
+  if (!value) return false
+  if (value === true) return { tokenIn: defaultCurrencies, slippage: 1 }
+  const tokenIn = value.tokenIn
+    ? [
+        ...value.tokenIn,
+        ...defaultCurrencies.filter((d) => !value.tokenIn!.some((c) => isAddressEqual(c, d))),
+      ]
+    : defaultCurrencies
+  return {
+    tokenIn,
+    slippage: value.slippage ?? 1,
+  }
+}
+
+export declare namespace resolve {
+  type Options = {
+    /** Fallback tokens to try swapping from, in priority order. */
+    tokenIn?: Address[] | undefined
+    /** Max slippage tolerance as a percentage (e.g. `1` = 1%). @default 1 */
+    slippage?: number | undefined
+  }
+
+  type Value = boolean | Options
+
+  type Resolved = { tokenIn: readonly Address[]; slippage: number }
+}
+
+export class InsufficientFundsError extends Error {
+  override readonly name = 'InsufficientFundsError'
+
+  constructor({ currency }: { currency: Address }) {
+    super(
+      `Insufficient funds: no balance in ${currency} and no viable swap route from fallback currencies.`,
+    )
+  }
+}