mppx 0.3.5 → 0.3.6

package/src/proxy/internal/Route.ts

@@ -1,5 +1,6 @@
 const httpMethods = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'])
 
+/** Extracts the pathname from a URL, stripping the optional `basePath` prefix. Returns `null` if the path doesn't match. */
 export function pathname(url: URL, basePath?: string): string | null {
   let pathname = url.pathname
   if (basePath) {
@@ -10,6 +11,7 @@ export function pathname(url: URL, basePath?: string): string | null {
   return pathname
 }
 
+/** Splits a `/{serviceId}/rest/of/path` pathname into its service ID and upstream path. */
 export function parse(pathname: string): { serviceId: string; upstreamPath: string } | null {
   const segments = pathname.split('/').filter(Boolean)
   const serviceId = segments[0]
@@ -19,6 +21,7 @@ export function parse(pathname: string): { serviceId: string; upstreamPath: stri
   return { serviceId, upstreamPath }
 }
 
+/** Finds the first route matching both the HTTP method and path (via `URLPattern`). */
 export function match(
   routes: Record<string, unknown>,
   method: string,
@@ -33,6 +36,7 @@ export function match(
   return null
 }
 
+/** Finds the first route matching just the path, ignoring the HTTP method. Used for management POST fallback. */
 export function matchPath(
   routes: Record<string, unknown>,
   path: string,

package/src/server/NodeListener.ts

@@ -1,3 +1,9 @@
 import * as FetchServer from '@remix-run/node-fetch-server'
 
+/**
+ * Writes a Fetch API `Response` to a Node.js `ServerResponse`.
+ *
+ * Delegates to `@remix-run/node-fetch-server`. Useful when bridging
+ * Fetch API handlers with Node.js HTTP servers.
+ */
 export const sendResponse = FetchServer.sendResponse

package/src/server/Response.ts

@@ -1,6 +1,23 @@
 import * as Challenge from '../Challenge.js'
 import type * as Errors from '../Errors.js'
 
+/**
+ * Creates a 402 Payment Required response with a `WWW-Authenticate: Payment` header.
+ *
+ * Optionally includes RFC 9457 Problem Details in the response body when an error is provided.
+ *
+ * @param parameters - The challenge and optional error.
+ * @returns A 402 Response suitable for returning from a route handler.
+ *
+ * @example
+ * ```ts
+ * import { Challenge } from 'mppx'
+ * import { Response } from 'mppx/server'
+ *
+ * const challenge = Challenge.from({ id: '...', realm: 'api.example.com', method: 'tempo', intent: 'charge', request: { ... } })
+ * return Response.requirePayment({ challenge })
+ * ```
+ */
 export function requirePayment(parameters: requirePayment.Parameters): Response {
   const { challenge, error } = parameters
 

package/src/tempo/client/ChannelOps.ts

@@ -47,7 +47,7 @@ export function resolveEscrow(
   const escrow =
     challengeEscrow ??
     escrowContractOverride ??
-    ((defaults.escrowContract as Record<number, string>)[chainId] as Address | undefined)
+    defaults.escrowContract[chainId as keyof typeof defaults.escrowContract]
   if (!escrow)
     throw new Error(
       'No `escrowContract` available. Provide it in parameters or ensure the server challenge includes it.',

package/src/tempo/internal/defaults.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from 'vitest'
+import {
+  chainId,
+  currency,
+  decimals,
+  escrowContract,
+  resolveCurrency,
+  rpcUrl,
+  tokens,
+} from './defaults.js'
+
+describe('chain ID constants', () => {
+  test('mainnet is 4217', () => {
+    expect(chainId.mainnet).toBe(4217)
+  })
+
+  test('testnet is 42431', () => {
+    expect(chainId.testnet).toBe(42431)
+  })
+})
+
+describe('token address constants', () => {
+  test('usdc address', () => {
+    expect(tokens.usdc).toBe('0x20C000000000000000000000b9537d11c60E8b50')
+  })
+
+  test('pathUsd address', () => {
+    expect(tokens.pathUsd).toBe('0x20c0000000000000000000000000000000000000')
+  })
+
+  test('usdc and pathUsd are different addresses', () => {
+    expect(tokens.usdc).not.toBe(tokens.pathUsd)
+  })
+
+  test('decimals is 6', () => {
+    expect(decimals).toBe(6)
+  })
+})
+
+describe('rpcUrl', () => {
+  test('mainnet RPC URL', () => {
+    expect(rpcUrl[chainId.mainnet]).toBe('https://rpc.tempo.xyz')
+  })
+
+  test('testnet RPC URL', () => {
+    expect(rpcUrl[chainId.testnet]).toBe('https://rpc.moderato.tempo.xyz')
+  })
+})
+
+describe('escrowContract', () => {
+  test('mainnet escrow contract', () => {
+    expect(escrowContract[chainId.mainnet]).toBe('0x0901aED692C755b870F9605E56BAA66C35BEfF69')
+  })
+
+  test('testnet escrow contract', () => {
+    expect(escrowContract[chainId.testnet]).toBe('0x542831e3E4Ace07559b7C8787395f4Fb99F70787')
+  })
+})
+
+describe('currency', () => {
+  test('mainnet (4217) returns USDC', () => {
+    expect(currency[chainId.mainnet]).toBe(tokens.usdc)
+  })
+
+  test('testnet (42431) returns pathUSD', () => {
+    expect(currency[chainId.testnet]).toBe(tokens.pathUsd)
+  })
+
+  test('mainnet and testnet return different currencies', () => {
+    expect(currency[chainId.mainnet]).not.toBe(currency[chainId.testnet])
+  })
+})
+
+describe('resolveCurrency', () => {
+  test('defaults to USDC (mainnet)', () => {
+    expect(resolveCurrency({})).toBe(tokens.usdc)
+  })
+
+  test('testnet: true returns pathUSD', () => {
+    expect(resolveCurrency({ testnet: true })).toBe(tokens.pathUsd)
+  })
+
+  test('testnet: false returns USDC', () => {
+    expect(resolveCurrency({ testnet: false })).toBe(tokens.usdc)
+  })
+
+  test('chainId takes precedence over testnet', () => {
+    expect(resolveCurrency({ chainId: chainId.testnet, testnet: false })).toBe(tokens.pathUsd)
+  })
+
+  test('unknown chainId falls back to pathUSD', () => {
+    expect(resolveCurrency({ chainId: 999999 })).toBe(tokens.pathUsd)
+  })
+})

package/src/tempo/internal/defaults.ts

@@ -1,20 +1,53 @@
-export const rpcUrl = {
-  4217: 'https://rpc.tempo.xyz',
-  42431: 'https://rpc.moderato.tempo.xyz',
+import type { ValueOf } from '../../internal/types.js'
+
+export const chainId = {
+  mainnet: 4217,
+  testnet: 42431,
 } as const
+export type ChainId = ValueOf<typeof chainId>
 
-export const escrowContract = {
-  4217: '0x0901aED692C755b870F9605E56BAA66C35BEfF69',
-  42431: '0x542831e3E4Ace07559b7C8787395f4Fb99F70787',
+/** Token addresses. */
+export const tokens = {
+  /** USDC (USDC.e) token address. */
+  usdc: '0x20C000000000000000000000b9537d11c60E8b50',
+  /** pathUSD token address. */
+  pathUsd: '0x20c0000000000000000000000000000000000000',
 } as const
 
-export const testnetChainId = 42431
+/** Chain ID → default currency. */
+export const currency = {
+  [chainId.mainnet]: tokens.usdc,
+  [chainId.testnet]: tokens.pathUsd,
+} as const satisfies Record<ChainId, string>
 
 /**
- * Default token decimals for TIP-20 stablecoins (e.g. pathUSD).
+ * Default token decimals for TIP-20 stablecoins (e.g. pathUSD, USDC).
  *
  * All TIP-20 tokens on Tempo use 6 decimals, so there is no risk of
  * client/server mismatch within the Tempo ecosystem. Other chains and
  * runtimes should set `decimals` explicitly to match their token.
  */
 export const decimals = 6
+
+/** Default payment-channel escrow contract addresses per chain. */
+export const escrowContract = {
+  [chainId.mainnet]: '0x0901aED692C755b870F9605E56BAA66C35BEfF69',
+  [chainId.testnet]: '0x542831e3E4Ace07559b7C8787395f4Fb99F70787',
+} as const satisfies Record<ChainId, string>
+
+/** Default RPC URLs for each Tempo chain. */
+export const rpcUrl = {
+  [chainId.mainnet]: 'https://rpc.tempo.xyz',
+  [chainId.testnet]: 'https://rpc.moderato.tempo.xyz',
+} as const satisfies Record<ChainId, string>
+
+/** Resolves the default currency. */
+export function resolveCurrency(parameters: {
+  /** Chain ID. */
+  chainId?: number | undefined
+  /** Whether in testnet mode. */
+  testnet?: boolean | undefined
+}): string {
+  const id = parameters.chainId ?? (parameters.testnet ? chainId.testnet : chainId.mainnet)
+  return currency[id as keyof typeof currency] ?? tokens.pathUsd
+}

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

@@ -656,6 +656,156 @@ describe('tempo', () => {
     })
   })
 
+  describe('default currency resolution', () => {
+    test('mainnet (default) resolves to USDC', () => {
+      const method = tempo_server.charge({
+        getClient: () => client,
+        account: accounts[0].address,
+      })
+      expect((method.defaults as Record<string, unknown>)?.currency).toBe(
+        '0x20C000000000000000000000b9537d11c60E8b50',
+      )
+    })
+
+    test('testnet: true defaults to pathUSD', () => {
+      const method = tempo_server.charge({
+        getClient: () => client,
+        account: accounts[0].address,
+        testnet: true,
+      })
+      expect((method.defaults as Record<string, unknown>)?.currency).toBe(
+        '0x20c0000000000000000000000000000000000000',
+      )
+    })
+
+    test('unknown chain defaults to pathUSD', () => {
+      const method = tempo_server.charge({
+        getClient: () => client,
+        account: accounts[0].address,
+        chainId: 69420,
+      })
+      expect((method.defaults as Record<string, unknown>)?.currency).toBe(
+        '0x20c0000000000000000000000000000000000000',
+      )
+    })
+
+    test('explicit currency overrides default', () => {
+      const method = tempo_server.charge({
+        getClient: () => client,
+        account: accounts[0].address,
+        testnet: false,
+        currency: '0xcustom',
+      })
+      expect(method.defaults?.currency).toBe('0xcustom')
+    })
+
+    test('decimals defaults to 6', () => {
+      const method = tempo_server.charge({
+        getClient: () => client,
+        account: accounts[0].address,
+      })
+      expect((method.defaults as Record<string, unknown>)?.decimals).toBe(6)
+    })
+
+    test('challenge contains USDC currency (mainnet default)', async () => {
+      const handler = Mppx_server.create({
+        methods: [
+          tempo_server.charge({
+            getClient: () => client,
+            account: accounts[0].address,
+          }),
+        ],
+        realm,
+        secretKey,
+      })
+
+      const result = await (handler.charge as Function)({ amount: '1' })(
+        new Request('https://example.com'),
+      )
+      expect(result.status).toBe(402)
+      if (result.status !== 402) throw new Error()
+
+      const challenge = Challenge.fromResponse(result.challenge, {
+        methods: [tempo_client.charge()],
+      })
+      expect(challenge.request.currency).toBe('0x20C000000000000000000000b9537d11c60E8b50')
+    })
+
+    test('challenge contains pathUSD currency when testnet: true', async () => {
+      const handler = Mppx_server.create({
+        methods: [
+          tempo_server.charge({
+            getClient: () => client,
+            account: accounts[0].address,
+            testnet: true,
+          }),
+        ],
+        realm,
+        secretKey,
+      })
+
+      const result = await (handler.charge as Function)({ amount: '1', chainId: chain.id })(
+        new Request('https://example.com'),
+      )
+      expect(result.status).toBe(402)
+      if (result.status !== 402) throw new Error()
+
+      const challenge = Challenge.fromResponse(result.challenge, {
+        methods: [tempo_client.charge()],
+      })
+      expect(challenge.request.currency).toBe('0x20c0000000000000000000000000000000000000')
+    })
+
+    test('challenge contains pathUSD currency (unknown chain)', async () => {
+      const handler = Mppx_server.create({
+        methods: [
+          tempo_server.charge({
+            getClient: () => client,
+            account: accounts[0].address,
+            chainId: 69420,
+          }),
+        ],
+        realm,
+        secretKey,
+      })
+
+      const result = await (handler.charge as Function)({ amount: '1' })(
+        new Request('https://example.com'),
+      )
+      expect(result.status).toBe(402)
+      if (result.status !== 402) throw new Error()
+
+      const challenge = Challenge.fromResponse(result.challenge, {
+        methods: [tempo_client.charge()],
+      })
+      expect(challenge.request.currency).toBe('0x20c0000000000000000000000000000000000000')
+    })
+
+    test('explicit currency in challenge overrides testnet default', async () => {
+      const handler = Mppx_server.create({
+        methods: [
+          tempo_server.charge({
+            getClient: () => client,
+            account: accounts[0].address,
+            testnet: false,
+            currency: asset,
+          }),
+        ],
+        realm,
+        secretKey,
+      })
+
+      const result = await handler.charge({ amount: '1' })(new Request('https://example.com'))
+      expect(result.status).toBe(402)
+      if (result.status !== 402) throw new Error()
+
+      const challenge = Challenge.fromResponse(result.challenge, {
+        methods: [tempo_client.charge()],
+      })
+      expect(challenge.request.currency).toBe(asset)
+    })
+  })
+
   describe('attribution memo', () => {
     test('client always generates attribution memo (hash credential)', async () => {
       const httpServer = await Http.createServer(async (req, res) => {

package/src/tempo/server/Charge.ts

@@ -40,7 +40,7 @@ export function charge<const parameters extends charge.Parameters>(
 ) {
   const {
     amount,
-    currency,
+    currency = defaults.resolveCurrency(parameters),
     decimals = defaults.decimals,
     description,
     externalId,
@@ -71,7 +71,7 @@ export function charge<const parameters extends charge.Parameters>(
     async request({ credential, request }) {
       const chainId = await (async () => {
         if (request.chainId) return request.chainId
-        if (parameters.testnet) return defaults.testnetChainId
+        if (parameters.testnet) return defaults.chainId.testnet
         return (await getClient({})).chain?.id
       })()
 

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

@@ -1,4 +1,5 @@
-import type { Challenge, z } from 'mppx'
+import type { z } from 'mppx'
+import { Challenge } from 'mppx'
 import { Mppx as Mppx_server, tempo as tempo_server } from 'mppx/server'
 import { type Address, createClient, type Hex } from 'viem'
 import { Addresses } from 'viem/tempo'
@@ -1334,6 +1335,193 @@ describe('monotonicity and TOCTOU (unit tests)', () => {
   })
 })
 
+describe('session default currency resolution', () => {
+  const mockClient = createClient({ transport: http('http://localhost:1') })
+  const mockMainnetClient = createClient({
+    chain: {
+      id: 4217,
+      name: 'Tempo',
+      nativeCurrency: { name: 'ETH', symbol: 'ETH', decimals: 18 },
+      rpcUrls: { default: { http: ['http://localhost:1'] } },
+    },
+    transport: http('http://localhost:1'),
+  })
+  const mockTestnetClient = createClient({
+    chain: {
+      id: 42431,
+      name: 'Tempo Testnet',
+      nativeCurrency: { name: 'ETH', symbol: 'ETH', decimals: 18 },
+      rpcUrls: { default: { http: ['http://localhost:1'] } },
+    },
+    transport: http('http://localhost:1'),
+  })
+
+  test('mainnet (default) resolves to USDC', () => {
+    const server = session({
+      store: Store.memory(),
+      getClient: () => mockClient,
+      account: '0x0000000000000000000000000000000000000001',
+      escrowContract: '0x0000000000000000000000000000000000000002',
+    } as session.Parameters)
+    expect(server.defaults?.currency).toBe('0x20C000000000000000000000b9537d11c60E8b50')
+  })
+
+  test('testnet: true defaults to pathUSD', () => {
+    const server = session({
+      store: Store.memory(),
+      getClient: () => mockClient,
+      account: '0x0000000000000000000000000000000000000001',
+      escrowContract: '0x0000000000000000000000000000000000000002',
+      testnet: true,
+    } as session.Parameters)
+    expect(server.defaults?.currency).toBe('0x20c0000000000000000000000000000000000000')
+  })
+
+  test('unknown chain defaults to pathUSD', () => {
+    const server = session({
+      store: Store.memory(),
+      getClient: () => mockClient,
+      account: '0x0000000000000000000000000000000000000001',
+      escrowContract: '0x0000000000000000000000000000000000000002',
+      chainId: 69420,
+    } as session.Parameters)
+    expect(server.defaults?.currency).toBe('0x20c0000000000000000000000000000000000000')
+  })
+
+  test('explicit currency overrides default', () => {
+    const server = session({
+      store: Store.memory(),
+      getClient: () => mockClient,
+      account: '0x0000000000000000000000000000000000000001',
+      currency: '0xcustom',
+      escrowContract: '0x0000000000000000000000000000000000000002',
+      chainId: 4217,
+      testnet: false,
+    } as session.Parameters)
+    expect(server.defaults?.currency).toBe('0xcustom')
+  })
+
+  test('decimals defaults to 6', () => {
+    const server = session({
+      store: Store.memory(),
+      getClient: () => mockClient,
+      account: '0x0000000000000000000000000000000000000001',
+      escrowContract: '0x0000000000000000000000000000000000000002',
+      chainId: 42431,
+    } as session.Parameters)
+    expect(server.defaults?.decimals).toBe(6)
+  })
+
+  test('challenge contains USDC currency (mainnet default)', async () => {
+    const handler = Mppx_server.create({
+      methods: [
+        tempo_server.session({
+          store: Store.memory(),
+          getClient: () => mockMainnetClient,
+          account: '0x0000000000000000000000000000000000000001',
+          escrowContract: '0x0000000000000000000000000000000000000002',
+          chainId: 4217,
+          testnet: false,
+        }),
+      ],
+      realm: 'api.example.com',
+      secretKey: 'secret',
+    })
+
+    const result = await (handler.session as Function)({
+      amount: '1',
+      decimals: 6,
+      unitType: 'token',
+    })(new Request('https://example.com'))
+    expect(result.status).toBe(402)
+
+    const challenge = Challenge.fromResponse(result.challenge)
+    expect(challenge.request.currency).toBe('0x20C000000000000000000000b9537d11c60E8b50')
+  })
+
+  test('challenge contains pathUSD currency when testnet: true', async () => {
+    const handler = Mppx_server.create({
+      methods: [
+        tempo_server.session({
+          store: Store.memory(),
+          getClient: () => mockTestnetClient,
+          account: '0x0000000000000000000000000000000000000001',
+          escrowContract: '0x0000000000000000000000000000000000000002',
+          testnet: true,
+        }),
+      ],
+      realm: 'api.example.com',
+      secretKey: 'secret',
+    })
+
+    const result = await (handler.session as Function)({
+      amount: '1',
+      decimals: 6,
+      unitType: 'token',
+      chainId: 42431,
+    })(new Request('https://example.com'))
+    expect(result.status).toBe(402)
+
+    const challenge = Challenge.fromResponse(result.challenge)
+    expect(challenge.request.currency).toBe('0x20c0000000000000000000000000000000000000')
+  })
+
+  test('challenge contains pathUSD currency (unknown chain)', async () => {
+    const handler = Mppx_server.create({
+      methods: [
+        tempo_server.session({
+          store: Store.memory(),
+          getClient: () => mockTestnetClient,
+          account: '0x0000000000000000000000000000000000000001',
+          escrowContract: '0x0000000000000000000000000000000000000002',
+          chainId: 69420,
+        }),
+      ],
+      realm: 'api.example.com',
+      secretKey: 'secret',
+    })
+
+    const result = await (handler.session as Function)({
+      amount: '1',
+      decimals: 6,
+      unitType: 'token',
+    })(new Request('https://example.com'))
+    expect(result.status).toBe(402)
+
+    const challenge = Challenge.fromResponse(result.challenge)
+    expect(challenge.request.currency).toBe('0x20c0000000000000000000000000000000000000')
+  })
+
+  test('explicit currency in challenge overrides testnet default', async () => {
+    const handler = Mppx_server.create({
+      methods: [
+        tempo_server.session({
+          store: Store.memory(),
+          getClient: () => mockClient,
+          account: '0x0000000000000000000000000000000000000001',
+          currency: '0xcustom',
+          escrowContract: '0x0000000000000000000000000000000000000002',
+          chainId: 4217,
+          testnet: false,
+        }),
+      ],
+      realm: 'api.example.com',
+      secretKey: 'secret',
+    })
+
+    const result = await handler.session({
+      amount: '1',
+      decimals: 6,
+      unitType: 'token',
+    })(new Request('https://example.com'))
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(result.challenge)
+    expect(challenge.request.currency).toBe('0xcustom')
+  })
+})
+
 function nextSalt(): Hex {
   saltCounter++
   return `0x${saltCounter.toString(16).padStart(64, '0')}` as Hex

package/src/tempo/server/Session.ts

@@ -85,7 +85,7 @@ export function session<const parameters extends session.Parameters>(p?: paramet
   const parameters = p as parameters
   const {
     amount,
-    currency,
+    currency = defaults.resolveCurrency(parameters),
     decimals = defaults.decimals,
     store: rawStore = Store.memory(),
     suggestedDeposit,
@@ -127,7 +127,7 @@ export function session<const parameters extends session.Parameters>(p?: paramet
       // Extract chainId from request or default.
       const chainId = await (async () => {
         if (request.chainId) return request.chainId
-        if (parameters.testnet) return defaults.testnetChainId
+        if (parameters.testnet) return defaults.chainId.testnet
         return (await getClient({})).chain?.id
       })()
 
@@ -156,7 +156,12 @@ export function session<const parameters extends session.Parameters>(p?: paramet
         return undefined
       })()
 
-      return { ...request, chainId, escrowContract: resolvedEscrow, feePayer: resolvedFeePayer }
+      return {
+        ...request,
+        chainId,
+        escrowContract: resolvedEscrow,
+        feePayer: resolvedFeePayer,
+      }
     },
 
     async verify({ credential }) {

package/src/tempo/session/Voucher.test.ts

@@ -131,4 +131,50 @@ describe('Voucher', () => {
     expect(voucher.cumulativeAmount).toBe(5000000n)
     expect(voucher.signature).toBe(sig)
   })
+
+  test('parseVoucherFromPayload with zero amount', () => {
+    const sig =
+      '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab' as const
+    const voucher = parseVoucherFromPayload(channelId, '0', sig)
+    expect(voucher.cumulativeAmount).toBe(0n)
+  })
+
+  test('verifyVoucher rejects wrong escrow contract', async () => {
+    const signature = await signVoucher(
+      client,
+      account,
+      { channelId, cumulativeAmount },
+      escrowContract,
+      chainId,
+    )
+
+    const wrongEscrow = '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd' as const
+    const isValid = await verifyVoucher(
+      wrongEscrow,
+      chainId,
+      { channelId, cumulativeAmount, signature },
+      account.address,
+    )
+    expect(isValid).toBe(false)
+  })
+
+  test('signVoucher and verifyVoucher round-trip with zero amount', async () => {
+    const zeroAmount = 0n
+    const signature = await signVoucher(
+      client,
+      account,
+      { channelId, cumulativeAmount: zeroAmount },
+      escrowContract,
+      chainId,
+    )
+    expect(signature).toMatch(/^0x/)
+
+    const isValid = await verifyVoucher(
+      escrowContract,
+      chainId,
+      { channelId, cumulativeAmount: zeroAmount, signature },
+      account.address,
+    )
+    expect(isValid).toBe(true)
+  })
 })