mppx 0.6.28 → 0.6.30

package/src/evm/server/Charge.ts

@@ -0,0 +1,283 @@
+import { getAddress, recoverTypedDataAddress } from 'viem'
+
+import type * as Credential from '../../Credential.js'
+import { VerificationFailedError } from '../../Errors.js'
+import * as Method from '../../Method.js'
+import * as Receipt from '../../Receipt.js'
+import * as ServerTransport from '../../server/Transport.js'
+import * as X402 from '../../x402/server/EvmCharge.js'
+import * as Assets from '../Assets.js'
+import * as Methods from '../Methods.js'
+import * as Types from '../Types.js'
+
+/**
+ * Creates an EVM charge server method.
+ *
+ * Speaks the native Payment-auth `evm/charge` wire format.
+ */
+export function charge(
+  parameters: charge.NativeConfig,
+): Method.Server<typeof Methods.charge, charge.Defaults>
+export function charge(parameters: charge.NativeConfig): Method.AnyServer {
+  const config = resolveConfig(parameters)
+  const paths = createPaths(config)
+  const transport = httpTransport(paths)
+
+  return Method.toServer<typeof Methods.charge, charge.Defaults, typeof transport>(Methods.charge, {
+    defaults: {
+      chainId: config.chainId,
+      currency: config.currency,
+      credentialTypes: ['authorization'],
+      decimals: config.decimals,
+      recipient: config.recipient,
+    },
+    transport,
+    async verify({ credential }) {
+      const payload = credential.payload as Types.AuthorizationPayload
+      const request = credential.challenge.request as Types.ChargeRequest
+      const chainId = request.methodDetails.chainId
+      const isX402Credential = X402.isCredential(credential)
+
+      if (!request.methodDetails.credentialTypes?.includes('authorization')) {
+        throw new VerificationFailedError({
+          reason: 'EVM authorization credentials are not supported for this challenge',
+        })
+      }
+
+      if (request.methodDetails.splits?.length) {
+        throw new VerificationFailedError({
+          reason: 'EVM authorization credentials do not support splits',
+        })
+      }
+
+      assertAddressEqual(payload.to, request.recipient, 'EVM authorization recipient mismatch')
+      if (payload.value !== request.amount)
+        throw new VerificationFailedError({ reason: 'EVM authorization amount mismatch' })
+      if (!isX402Credential && payload.nonce !== Types.challengeHash(credential.challenge))
+        throw new VerificationFailedError({ reason: 'EVM authorization challenge hash mismatch' })
+      const now = BigInt(Math.floor(Date.now() / 1000))
+      if (BigInt(payload.validAfter) > now)
+        throw new VerificationFailedError({ reason: 'EVM authorization is not valid yet' })
+      if (BigInt(payload.validBefore) <= now)
+        throw new VerificationFailedError({ reason: 'EVM authorization has expired' })
+
+      const signer = await recoverTypedDataAddress({
+        domain: Types.authorizationDomain({
+          authorization: config.authorization,
+          chainId,
+          currency: request.currency as `0x${string}`,
+        }),
+        message: {
+          from: getAddress(payload.from),
+          nonce: payload.nonce as `0x${string}`,
+          to: getAddress(payload.to),
+          validAfter: BigInt(payload.validAfter),
+          validBefore: BigInt(payload.validBefore),
+          value: BigInt(payload.value),
+        },
+        primaryType: 'TransferWithAuthorization',
+        signature: payload.signature as `0x${string}`,
+        types: Types.authorizationTypes,
+      })
+      assertAddressEqual(signer, payload.from, 'EVM authorization signature mismatch')
+
+      const source = Types.toSource({ address: getAddress(payload.from), chainId })
+      if (credential.source && credential.source !== source) {
+        throw new VerificationFailedError({ reason: 'EVM authorization source mismatch' })
+      }
+
+      const settled = await config.settle({
+        credential,
+        payload,
+        request,
+        source,
+      })
+
+      return Receipt.from({
+        method: Types.paymentMethod,
+        reference: settled.reference,
+        status: 'success',
+        timestamp: settled.timestamp ?? new Date().toISOString(),
+      })
+    },
+  })
+}
+
+export declare namespace charge {
+  type Parameters = NativeConfig
+  type Native = Method.Server<typeof Methods.charge, Defaults>
+
+  type NativeConfig = BaseConfig & CurrencyConfig & RecipientConfig
+
+  type BaseConfig = {
+    /** EIP-3009 token domain metadata. Required for custom currency addresses; inferred for known assets. */
+    authorization?: Types.AuthorizationConfig | undefined
+    /** EVM chain ID. Required for custom currency addresses; inferred for known assets. */
+    chainId?: number | undefined
+    /** Token decimal places. Required for custom currency addresses; inferred for known assets. */
+    decimals?: number | undefined
+    /** Custom settlement override. If omitted, `x402.facilitator` is used. */
+    settle?: SettleAuthorization | undefined
+    /** x402 compatibility options. */
+    x402?: X402.Options | undefined
+  }
+
+  type CurrencyConfig = {
+    /** Token contract address or known EVM asset metadata. */
+    currency: `0x${string}` | Assets.KnownAsset
+  }
+
+  type RecipientConfig = {
+    /** Recipient wallet address. */
+    recipient: `0x${string}`
+  }
+
+  type RouteOptions = {
+    /** Required display-unit token amount. */
+    amount: string
+    /** Optional human-readable payment description. */
+    description?: string | undefined
+    /** Optional external correlation ID. */
+    externalId?: string | undefined
+  }
+
+  type SettleAuthorization = (parameters: {
+    credential: Credential.Credential<Types.AuthorizationPayload>
+    payload: Types.AuthorizationPayload
+    request: Types.ChargeRequest
+    source: ReturnType<typeof Types.toSource>
+  }) => Promise<{
+    reference: string
+    timestamp?: string | undefined
+  }>
+
+  type Defaults = {
+    chainId: number
+    currency: `0x${string}`
+    credentialTypes: ['authorization']
+    decimals: number
+    recipient: `0x${string}`
+  }
+}
+
+type ResolvedConfig = {
+  authorization: Types.AuthorizationConfig
+  chainId: number
+  currency: `0x${string}`
+  decimals: number
+  recipient: `0x${string}`
+  settle: charge.SettleAuthorization
+  x402: X402.ResolvedOptions
+}
+
+type HttpPath = {
+  bindCredential: NonNullable<ServerTransport.Http['bindCredential']>
+  captureRequest?: ServerTransport.Http['captureRequest'] | undefined
+  getCredential: ServerTransport.Http['getCredential']
+  respondChallenge: (
+    options: Parameters<ServerTransport.Http['respondChallenge']>[0],
+    response?: Response | undefined,
+  ) => Response | Promise<Response>
+  respondReceipt: (
+    options: Parameters<ServerTransport.Http['respondReceipt']>[0],
+    response: Response,
+  ) => Response
+}
+
+type HttpPaths = {
+  mpp: HttpPath
+  x402: HttpPath
+}
+
+function resolveConfig(config: charge.NativeConfig): ResolvedConfig {
+  const { currency, recipient } = config
+  let address: `0x${string}`
+  let authorization = config.authorization
+  let chainId = config.chainId
+  let decimals = config.decimals
+
+  if (Assets.isAsset(currency)) {
+    address = currency.address
+    chainId ??= Number(currency.network.slice('eip155:'.length))
+    decimals ??= currency.decimals
+    if (currency.transfer.type === Types.eip3009) {
+      authorization ??= {
+        name: currency.transfer.name,
+        version: currency.transfer.version,
+      }
+    }
+  } else {
+    address = currency
+  }
+
+  if (!authorization) throw new Error('EVM authorization requires `authorization` metadata.')
+  if (chainId === undefined) throw new Error('EVM authorization requires `chainId`.')
+  if (decimals === undefined) throw new Error('EVM authorization requires `decimals`.')
+
+  const x402 = X402.resolveOptions({
+    authorization,
+    options: config.x402,
+  })
+  const settle = config.settle ?? (x402?.facilitator ? X402.settleWithFacilitator(x402) : undefined)
+  if (!settle) throw new Error('EVM authorization requires `settle` or `x402.facilitator`.')
+
+  return {
+    authorization,
+    chainId,
+    currency: getAddress(address),
+    decimals,
+    recipient: getAddress(recipient),
+    settle,
+    x402,
+  }
+}
+
+function createPaths(config: ResolvedConfig): HttpPaths {
+  return {
+    mpp: createMppPath(),
+    x402: X402.createPath(config.x402),
+  }
+}
+
+function createMppPath(): HttpPath {
+  const transport = ServerTransport.http()
+  return {
+    bindCredential: (options) => transport.bindCredential?.(options) ?? options.credential,
+    captureRequest: transport.captureRequest,
+    getCredential: transport.getCredential,
+    respondChallenge: (options) => transport.respondChallenge(options),
+    respondReceipt: (options, response) => transport.respondReceipt({ ...options, response }),
+  }
+}
+
+function httpTransport(paths: HttpPaths): ServerTransport.Http {
+  return ServerTransport.from<Request, Response>({
+    name: 'evm-http',
+
+    captureRequest: paths.mpp.captureRequest,
+
+    getCredential(input) {
+      return paths.mpp.getCredential(input) ?? paths.x402.getCredential(input)
+    },
+
+    bindCredential(options) {
+      if (X402.isPendingCredential(options.credential)) return paths.x402.bindCredential(options)
+      return paths.mpp.bindCredential?.(options) ?? options.credential
+    },
+
+    async respondChallenge(options) {
+      const response = await paths.mpp.respondChallenge(options)
+      return paths.x402.respondChallenge(options, response)
+    },
+
+    respondReceipt(options) {
+      const response = paths.mpp.respondReceipt(options, options.response)
+      return paths.x402.respondReceipt(options, response)
+    },
+  })
+}
+
+function assertAddressEqual(actual: string, expected: string, reason: string) {
+  if (getAddress(actual) === getAddress(expected)) return
+  throw new VerificationFailedError({ reason })
+}

package/src/evm/server/Methods.ts

@@ -0,0 +1,22 @@
+import type { NoExtraKeys } from '../../internal/types.js'
+import * as Assets from '../Assets.js'
+import * as Chains from '../Chains.js'
+import { charge as charge_ } from './Charge.js'
+
+/** Creates EVM server methods from shared charge parameters. */
+export function evm<const parameters extends evm.Parameters>(
+  parameters: NoExtraKeys<parameters, evm.Parameters>,
+) {
+  return [evm.charge(parameters)] as const
+}
+
+export namespace evm {
+  export type Parameters = charge_.Parameters
+
+  /** Creates an EVM `charge` server method. */
+  export const charge = charge_
+  /** Known EVM asset metadata for public config. */
+  export const assets = Assets
+  /** Common EVM chain IDs for public config. */
+  export const chains = Chains
+}

package/src/evm/server/index.ts

@@ -0,0 +1,5 @@
+export * as assets from '../Assets.js'
+export * as Chains from '../Chains.js'
+export * as chains from '../Chains.js'
+export { charge } from './Charge.js'
+export { evm } from './Methods.js'

package/src/index.ts

@@ -3,9 +3,11 @@ export * as Challenge from './Challenge.js'
 export * as Credential from './Credential.js'
 export * as Errors from './Errors.js'
 export * as Expires from './Expires.js'
+export * as evm from './evm/index.js'
 export * as Mcp from './Mcp.js'
 export * as Method from './Method.js'
 export * as PaymentRequest from './PaymentRequest.js'
 export * as Receipt from './Receipt.js'
 export * as Store from './Store.js'
+export * as x402 from './x402/index.js'
 export * as z from './zod.js'

package/src/internal/HeaderCodec.ts

@@ -0,0 +1,36 @@
+import { Base64 } from 'ox'
+
+import type * as z from '../zod.js'
+
+/**
+ * Creates a typed codec for JSON HTTP header values.
+ *
+ * x402 uses plain base64 JSON header bodies, while the Payment auth scheme uses
+ * its own base64url/JCS serializers. Keep this helper internal so transports
+ * can opt into the exact wire encoding their protocol expects.
+ */
+export function createJson<const schema extends z.ZodMiniType>(schema: schema) {
+  type value = z.output<schema>
+
+  return {
+    encode(value: value): string {
+      return Base64.fromString(JSON.stringify(schema.parse(value)))
+    },
+    decode(value: string): value {
+      try {
+        return schema.parse(JSON.parse(Base64.toString(value))) as value
+      } catch {
+        throw new InvalidJsonHeaderError()
+      }
+    },
+  }
+}
+
+/** Error thrown when a JSON header value is not valid base64-encoded JSON. */
+export class InvalidJsonHeaderError extends Error {
+  override readonly name = 'InvalidJsonHeaderError'
+
+  constructor() {
+    super('Invalid base64 JSON header.')
+  }
+}

package/src/middlewares/elysia.test.ts

@@ -63,6 +63,31 @@ describe('payment', () => {
 
     server.close()
   })
+
+  test('copies transport-specific success headers', async () => {
+    const intent = () => async () => ({
+      status: 200 as const,
+      withReceipt: (response?: Response) =>
+        new Response(response?.body ?? null, {
+          headers: {
+            ...(response ? Object.fromEntries(response.headers) : {}),
+            'PAYMENT-RESPONSE': 'x402-response',
+          },
+          status: response?.status ?? 200,
+        }),
+    })
+
+    const app = new Elysia().guard({ beforeHandle: payment(intent as any, {} as any) }, (app) =>
+      app.get('/', () => ({ data: 'content' })),
+    )
+
+    const server = await createServer(app)
+    const response = await globalThis.fetch(server.url)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('PAYMENT-RESPONSE')).toBe('x402-response')
+
+    server.close()
+  })
 })
 
 function createChargeHarness(feePayer: boolean) {

package/src/middlewares/elysia.ts

@@ -67,8 +67,7 @@ export function payment<const intent extends Mppx_internal.AnyMethodFn>(
     const managementResponse = getManagementResponse(result)
     if (managementResponse) return managementResponse
     const receipt = result.withReceipt(new Response())
-    const header = receipt.headers.get('Payment-Receipt')
-    if (header) set.headers['Payment-Receipt'] = header
+    for (const [key, value] of receipt.headers) set.headers[key] = value
   }
 }
 

package/src/middlewares/express.test.ts

@@ -162,6 +162,34 @@ describe('charge', () => {
   })
 })
 
+describe('payment', () => {
+  test('copies transport-specific success headers', async () => {
+    const intent = () => async () => ({
+      status: 200 as const,
+      withReceipt: (response?: Response) =>
+        new Response(response?.body ?? null, {
+          headers: {
+            ...(response ? Object.fromEntries(response.headers) : {}),
+            'PAYMENT-RESPONSE': 'x402-response',
+          },
+          status: response?.status ?? 200,
+        }),
+    })
+
+    const app = express()
+    app.get('/', payment(intent as any, {} as any), (_req, res) => {
+      res.json({ data: 'content' })
+    })
+
+    const server = await createServer(app)
+    const response = await globalThis.fetch(server.url)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('PAYMENT-RESPONSE')).toBe('x402-response')
+
+    server.close()
+  })
+})
+
 describe('session', () => {
   let escrowContract: Address
 

package/src/middlewares/express.ts

@@ -99,7 +99,7 @@ export function payment<const intent extends Mppx_internal.AnyMethodFn>(
     const originalJson = res.json.bind(res)
     res.json = (body: any) => {
       const wrapped = result.withReceipt(Response.json(body))
-      res.setHeader('Payment-Receipt', wrapped.headers.get('Payment-Receipt')!)
+      for (const [key, value] of wrapped.headers) res.setHeader(key, value)
       return originalJson(body)
     }
 

package/src/middlewares/hono.test.ts

@@ -1,9 +1,20 @@
 import { serve } from '@hono/node-server'
 import { Hono } from 'hono'
 import { Challenge, Credential, Method, Receipt, z } from 'mppx'
-import { Mppx as Mppx_client, session as sessionIntent, tempo as tempo_client } from 'mppx/client'
+import {
+  evm as evm_client,
+  Mppx as Mppx_client,
+  session as sessionIntent,
+  tempo as tempo_client,
+} from 'mppx/client'
 import { Mppx, discovery, payment } from 'mppx/hono'
-import { tempo as tempo_server } from 'mppx/server'
+import { evm as evm_server, Mppx as ServerMppx, tempo as tempo_server } from 'mppx/server'
+import {
+  paymentRequiredHeader,
+  paymentResponseHeader,
+  paymentSignatureHeader,
+  type PaymentPayload,
+} from 'mppx/x402'
 import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vp/test'
@@ -53,6 +64,30 @@ describe('payment', () => {
 
     server.close()
   })
+
+  test('copies transport-specific success headers', async () => {
+    const intent = () => async () => ({
+      status: 200 as const,
+      withReceipt: (response?: Response) =>
+        new Response(response?.body ?? null, {
+          headers: {
+            ...(response ? Object.fromEntries(response.headers) : {}),
+            'PAYMENT-RESPONSE': 'x402-response',
+          },
+          status: response?.status ?? 200,
+        }),
+    })
+
+    const app = new Hono()
+    app.get('/', payment(intent as any, {} as any), (c) => c.json({ data: 'content' }))
+
+    const server = await createServer(app)
+    const response = await globalThis.fetch(server.url)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('PAYMENT-RESPONSE')).toBe('x402-response')
+
+    server.close()
+  })
 })
 
 const scopeMethod = Method.toServer(
@@ -187,8 +222,109 @@ describe('charge', () => {
 
     server.close()
   })
+
+  test('serves tempo and x402 from one Hono endpoint', async () => {
+    const transaction = `0x${'2'.repeat(64)}` as const
+    const payments = ServerMppx.create({
+      methods: [
+        tempo_server.charge({
+          account: accounts[0],
+          currency: asset,
+          getClient: () => client,
+          recipient: accounts[0].address,
+        }),
+        evm_server.charge({
+          currency: evm_server.assets.baseSepolia.USDC,
+          recipient: accounts[0].address,
+          x402: {
+            facilitator: {
+              async verify(paymentPayload: PaymentPayload) {
+                return {
+                  isValid: true,
+                  payer: payerOf(paymentPayload),
+                }
+              },
+              async settle(paymentPayload: PaymentPayload) {
+                return {
+                  network: paymentPayload.accepted.network,
+                  payer: payerOf(paymentPayload),
+                  success: true,
+                  transaction,
+                }
+              },
+            },
+          },
+        }),
+      ],
+      secretKey,
+    })
+
+    const route = payments.compose(
+      [payments.tempo.charge, { amount: '0', chainId: client.chain!.id }],
+      [payments.evm.charge, { amount: '0.01' }],
+    )
+
+    const app = new Hono()
+    app.get('/paid', async (c) => {
+      const result = await route(c.req.raw)
+      if (result.status === 402) return result.challenge
+      return result.withReceipt(c.json({ data: 'paid' }))
+    })
+
+    const server = await createServer(app)
+    const challenge = await globalThis.fetch(`${server.url}/paid`)
+    expect(challenge.status).toBe(402)
+    expect(challenge.headers.get('WWW-Authenticate')).toContain('Payment')
+    expect(challenge.headers.get(paymentRequiredHeader)).toBeTruthy()
+
+    const tempoPayment = Mppx_client.create({
+      methods: [
+        tempo_client.charge({
+          account: accounts[0],
+          getClient: () => client,
+        }),
+      ],
+      polyfill: false,
+    })
+    const tempoResponse = await tempoPayment.fetch(`${server.url}/paid`)
+    expect(tempoResponse.status).toBe(200)
+    expect(await tempoResponse.json()).toEqual({ data: 'paid' })
+    expect(tempoResponse.headers.get('Payment-Receipt')).toBeTruthy()
+
+    const x402Payment = Mppx_client.create({
+      methods: [
+        evm_client.charge({
+          account: accounts[0],
+        }),
+      ],
+      polyfill: false,
+    })
+    const paymentSignature = await x402Payment.createCredential(pureX402Challenge(challenge))
+    const x402Response = await x402Payment.rawFetch(`${server.url}/paid`, {
+      headers: { [paymentSignatureHeader]: paymentSignature },
+    })
+    expect(x402Response.status).toBe(200)
+    expect(await x402Response.json()).toEqual({ data: 'paid' })
+    expect(x402Response.headers.get(paymentResponseHeader)).toBeTruthy()
+
+    server.close()
+  })
 })
 
+function payerOf(paymentPayload: PaymentPayload): string {
+  if ('authorization' in paymentPayload.payload) return paymentPayload.payload.authorization.from
+  return paymentPayload.payload.permit2Authorization.from
+}
+
+function pureX402Challenge(response: Response): Response {
+  const paymentRequired = response.headers.get(paymentRequiredHeader)
+  if (!paymentRequired) throw new Error('Missing PAYMENT-REQUIRED header.')
+  return new Response(null, {
+    headers: { [paymentRequiredHeader]: paymentRequired },
+    status: 402,
+  })
+}
+
 describe('scope binding', () => {
   const scopeOpts = {
     amount: '1',

package/src/middlewares/nextjs.test.ts

@@ -59,6 +59,28 @@ describe('payment', () => {
 
     server.close()
   })
+
+  test('copies transport-specific success headers', async () => {
+    const intent = () => async () => ({
+      status: 200 as const,
+      withReceipt: (response?: Response) =>
+        new Response(response?.body ?? null, {
+          headers: {
+            ...(response ? Object.fromEntries(response.headers) : {}),
+            'PAYMENT-RESPONSE': 'x402-response',
+          },
+          status: response?.status ?? 200,
+        }),
+    })
+    const handler = payment(intent as any, {} as any, () => Response.json({ data: 'content' }))
+
+    const server = await createServer(handler)
+    const response = await globalThis.fetch(server.url)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('PAYMENT-RESPONSE')).toBe('x402-response')
+
+    server.close()
+  })
 })
 
 function createChargeHarness(feePayer: boolean) {

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

@@ -13,6 +13,26 @@ describe('scrub', () => {
     expect(result.get('content-type')).toBe('application/json')
   })
 
+  test('behavior: strips payment protocol headers', () => {
+    const headers = new globalThis.Headers({
+      'Accept-Payment': 'evm/charge',
+      'Content-Type': 'application/json',
+      'PAYMENT-RECEIPT': 'receipt',
+      'PAYMENT-REQUIRED': 'required',
+      'PAYMENT-RESPONSE': 'response',
+      'PAYMENT-SIGNATURE': 'signature',
+      'WWW-Authenticate': 'Payment id="abc"',
+    })
+    const result = Headers.scrub(headers)
+    expect(result.has('accept-payment')).toBe(false)
+    expect(result.has('payment-receipt')).toBe(false)
+    expect(result.has('payment-required')).toBe(false)
+    expect(result.has('payment-response')).toBe(false)
+    expect(result.has('payment-signature')).toBe(false)
+    expect(result.has('www-authenticate')).toBe(false)
+    expect(result.get('content-type')).toBe('application/json')
+  })
+
   test('behavior: strips cookie header', () => {
     const headers = new globalThis.Headers({
       Cookie: 'session=abc123',