mppx 0.6.28 → 0.6.30

package/src/x402/Assets.ts

@@ -0,0 +1,65 @@
+import type { Asset, EvmNetwork, ExactTransfer } from './Types.js'
+
+const knownAsset = Symbol('mppx.x402.asset')
+
+/** Known x402 asset metadata. */
+export type KnownAsset = Asset & {
+  readonly [knownAsset]: true
+  network: EvmNetwork
+}
+
+/** Creates typed x402 asset metadata for custom tokens. */
+export function define(parameters: define.Parameters): KnownAsset {
+  return {
+    [knownAsset]: true,
+    address: parameters.address,
+    decimals: parameters.decimals,
+    network: parameters.network,
+    transfer: parameters.transfer,
+  }
+}
+
+export declare namespace define {
+  type Parameters = {
+    address: `0x${string}`
+    decimals: number
+    network: EvmNetwork
+    transfer: ExactTransfer
+  }
+}
+
+/** Base network known assets. */
+export const base = {
+  USDC: define({
+    address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+    decimals: 6,
+    network: 'eip155:8453',
+    transfer: {
+      // USDC's EIP-712 domain name differs between Base and Base Sepolia.
+      name: 'USD Coin',
+      type: 'eip3009',
+      version: '2',
+    },
+  }),
+} as const
+
+/** Base Sepolia known assets. */
+export const baseSepolia = {
+  USDC: define({
+    address: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+    decimals: 6,
+    network: 'eip155:84532',
+    transfer: {
+      // Base Sepolia test USDC signs with the shorter EIP-712 domain name.
+      name: 'USDC',
+      type: 'eip3009',
+      version: '2',
+    },
+  }),
+} as const
+
+/** Returns true when a value is known x402 asset metadata. */
+export function isAsset(value: unknown): value is KnownAsset {
+  if (typeof value !== 'object' || value === null) return false
+  return (value as Partial<KnownAsset>)[knownAsset] === true
+}

package/src/x402/Exact.e2e.test.ts

@@ -0,0 +1,448 @@
+import { evm as evmClient, Mppx as ClientMppx, tempo as tempoClient } from 'mppx/client'
+import { evm, Mppx as ServerMppx, NodeListener, Request as ServerRequest, tempo } from 'mppx/server'
+import { describe, expect, test } from 'vp/test'
+import * as Http from '~test/Http.js'
+import { accounts, asset, client } from '~test/tempo/viem.js'
+
+import * as Header from './Header.js'
+import * as RouteBinding from './internal/RouteBinding.js'
+import * as Types from './Types.js'
+
+const secretKey = 'test-secret'
+const transaction = `0x${'1'.repeat(64)}`
+
+describe('x402 exact e2e', () => {
+  test('serves tempo and x402 paid routes from a live server', async () => {
+    const tempoPayment = ServerMppx.create({
+      methods: [
+        tempo.charge({
+          account: accounts[0],
+          currency: asset,
+          getClient: () => client,
+          recipient: accounts[0].address,
+        }),
+      ],
+      secretKey,
+    })
+
+    const facilitator: Types.Facilitator = {
+      async verify(paymentPayload) {
+        return {
+          isValid: true,
+          payer: payerOf(paymentPayload),
+        }
+      },
+      async settle(paymentPayload) {
+        return {
+          network: paymentPayload.accepted.network,
+          payer: payerOf(paymentPayload),
+          success: true,
+          transaction,
+        }
+      },
+    }
+    const x402Payment = ServerMppx.create({
+      methods: [
+        evm.charge({
+          currency: evm.assets.baseSepolia.USDC,
+          recipient: accounts[0].address,
+          x402: { facilitator },
+        }),
+      ],
+      secretKey,
+    })
+
+    const server = await Http.createServer(async (req, res) => {
+      const request = ServerRequest.fromNodeListener(req, res)
+
+      if (req.url === '/tempo') {
+        const result = await tempoPayment.tempo.charge({
+          amount: '0',
+          chainId: client.chain!.id,
+        })(request)
+        if (result.status === 402) return NodeListener.sendResponse(res, result.challenge)
+        return NodeListener.sendResponse(res, result.withReceipt(new Response('tempo ok')))
+      }
+
+      if (req.url === '/x402') {
+        const result = await x402Payment.evm.charge({
+          amount: '0.01',
+        })(request)
+        if (result.status === 402) return NodeListener.sendResponse(res, result.challenge)
+        return NodeListener.sendResponse(res, result.withReceipt(new Response('x402 ok')))
+      }
+
+      return NodeListener.sendResponse(res, new Response('not found', { status: 404 }))
+    })
+
+    try {
+      const tempoClientPayment = ClientMppx.create({
+        methods: [
+          tempoClient.charge({
+            account: accounts[0],
+            getClient: () => client,
+          }),
+        ],
+        polyfill: false,
+      })
+      const tempoResponse = await tempoClientPayment.fetch(`${server.url}/tempo`)
+      expect(tempoResponse.status).toBe(200)
+      expect(await tempoResponse.text()).toBe('tempo ok')
+      expect(tempoResponse.headers.has('Payment-Receipt')).toBe(true)
+
+      const x402ClientPayment = ClientMppx.create({
+        methods: [
+          evmClient.charge({
+            account: accounts[0],
+          }),
+        ],
+        polyfill: false,
+      })
+      const x402Required = await x402ClientPayment.rawFetch(`${server.url}/x402`)
+      expect(x402Required.status).toBe(402)
+      expect(x402Required.headers.has(Types.paymentRequiredHeader)).toBe(true)
+
+      const paymentSignature = await x402ClientPayment.createCredential(
+        pureX402Challenge(x402Required),
+      )
+      const paymentPayload = Header.decodePaymentSignature(paymentSignature)
+      expect(paymentPayload.accepted.scheme).toBe('exact')
+
+      const x402Response = await x402ClientPayment.rawFetch(`${server.url}/x402`, {
+        headers: { [Types.paymentSignatureHeader]: paymentSignature },
+      })
+      expect(x402Response.status).toBe(200)
+      expect(await x402Response.text()).toBe('x402 ok')
+
+      const paymentResponseHeader = x402Response.headers.get(Types.paymentResponseHeader)
+      expect(paymentResponseHeader).toBeTruthy()
+      expect(Header.decodePaymentResponse(paymentResponseHeader!).transaction).toBe(transaction)
+    } finally {
+      server.close()
+    }
+  })
+
+  test('rejects x402 payment payload replayed across resources with same requirements', async () => {
+    let verifyCalls = 0
+    const payment = ServerMppx.create({
+      methods: [
+        evm.charge({
+          currency: evm.assets.baseSepolia.USDC,
+          recipient: accounts[0].address,
+          x402: {
+            facilitator: {
+              async verify() {
+                verifyCalls++
+                return { isValid: true }
+              },
+              async settle(paymentPayload: Types.PaymentPayload) {
+                return {
+                  network: paymentPayload.accepted.network,
+                  success: true,
+                  transaction,
+                }
+              },
+            },
+          },
+        }),
+      ],
+      secretKey,
+    })
+    const route = payment.evm.charge({ amount: '0.01' })
+
+    const routeAChallenge = await route(new Request('https://example.com/a'))
+    expect(routeAChallenge.status).toBe(402)
+    if (routeAChallenge.status !== 402) throw new Error()
+
+    const paymentRequired = Header.decodePaymentRequired(
+      routeAChallenge.challenge.headers.get(Types.paymentRequiredHeader)!,
+    )
+    const accepted = paymentRequired.accepts[0]!
+    const paymentSignature = Header.encodePaymentSignature({
+      accepted,
+      payload: {
+        authorization: {
+          from: accounts[0].address,
+          nonce: `0x${'1'.repeat(64)}`,
+          to: accepted.payTo as `0x${string}`,
+          validAfter: '0',
+          validBefore: '9999999999',
+          value: accepted.amount,
+        },
+        signature: `0x${'2'.repeat(130)}`,
+      },
+      resource: paymentRequired.resource,
+      x402Version: 2,
+    })
+
+    const result = await route(
+      new Request('https://example.com/b', {
+        headers: { [Types.paymentSignatureHeader]: paymentSignature },
+      }),
+    )
+
+    expect(result.status).toBe(402)
+    expect(verifyCalls).toBe(0)
+  })
+
+  test('rejects x402 route extensions with extra binding fields', async () => {
+    let verifyCalls = 0
+    const payment = ServerMppx.create({
+      methods: [
+        evm.charge({
+          currency: evm.assets.baseSepolia.USDC,
+          recipient: accounts[0].address,
+          x402: {
+            facilitator: {
+              async verify() {
+                verifyCalls++
+                return { isValid: true }
+              },
+              async settle(paymentPayload: Types.PaymentPayload) {
+                return {
+                  network: paymentPayload.accepted.network,
+                  success: true,
+                  transaction,
+                }
+              },
+            },
+          },
+        }),
+      ],
+      secretKey,
+    })
+    const route = payment.evm.charge({ amount: '0.01' })
+
+    const first = await route(new Request('https://example.com/a'))
+    expect(first.status).toBe(402)
+    if (first.status !== 402) throw new Error()
+
+    const paymentRequired = Header.decodePaymentRequired(
+      first.challenge.headers.get(Types.paymentRequiredHeader)!,
+    )
+    const accepted = paymentRequired.accepts[0]!
+    const mppxExtension = paymentRequired.extensions!.mppx
+    if (!mppxExtension) throw new Error()
+    const extensions: Types.Extensions = {
+      ...paymentRequired.extensions!,
+      mppx: {
+        schema: mppxExtension.schema,
+        info: {
+          ...mppxExtension.info,
+          extra: 'not allowed',
+        },
+      },
+    }
+    const paymentSignature = Header.encodePaymentSignature({
+      accepted,
+      extensions,
+      payload: {
+        authorization: {
+          from: accounts[0].address,
+          nonce: RouteBinding.nonce({
+            accepted,
+            extensions,
+            resource: paymentRequired.resource,
+          }),
+          to: accepted.payTo as `0x${string}`,
+          validAfter: '0',
+          validBefore: '9999999999',
+          value: accepted.amount,
+        },
+        signature: `0x${'2'.repeat(130)}`,
+      },
+      resource: paymentRequired.resource,
+      x402Version: 2,
+    })
+
+    const result = await route(
+      new Request('https://example.com/a', {
+        headers: { [Types.paymentSignatureHeader]: paymentSignature },
+      }),
+    )
+
+    expect(result.status).toBe(402)
+    expect(verifyCalls).toBe(0)
+  })
+
+  test('does not advertise x402 for body-bearing requests without a digest', async () => {
+    let verifyCalls = 0
+    const payment = ServerMppx.create({
+      methods: [
+        evm.charge({
+          currency: evm.assets.baseSepolia.USDC,
+          recipient: accounts[0].address,
+          x402: {
+            facilitator: {
+              async verify() {
+                verifyCalls++
+                return { isValid: true }
+              },
+              async settle(paymentPayload: Types.PaymentPayload) {
+                return {
+                  network: paymentPayload.accepted.network,
+                  success: true,
+                  transaction,
+                }
+              },
+            },
+          },
+        }),
+      ],
+      secretKey,
+    })
+    const route = payment.evm.charge({ amount: '0.01' })
+
+    const result = await route(
+      new Request('https://example.com/body', {
+        body: JSON.stringify({ a: 1 }),
+        method: 'POST',
+      }),
+    )
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+    expect(result.challenge.headers.has('WWW-Authenticate')).toBe(true)
+    expect(result.challenge.headers.has(Types.paymentRequiredHeader)).toBe(false)
+
+    const getChallenge = await route(new Request('https://example.com/body'))
+    expect(getChallenge.status).toBe(402)
+    if (getChallenge.status !== 402) throw new Error()
+    const paymentRequired = Header.decodePaymentRequired(
+      getChallenge.challenge.headers.get(Types.paymentRequiredHeader)!,
+    )
+    const accepted = paymentRequired.accepts[0]!
+    const paymentSignature = Header.encodePaymentSignature({
+      accepted,
+      extensions: paymentRequired.extensions,
+      payload: {
+        authorization: {
+          from: accounts[0].address,
+          nonce: RouteBinding.nonce({
+            accepted,
+            extensions: paymentRequired.extensions!,
+            resource: paymentRequired.resource,
+          }),
+          to: accepted.payTo as `0x${string}`,
+          validAfter: '0',
+          validBefore: '9999999999',
+          value: accepted.amount,
+        },
+        signature: `0x${'2'.repeat(130)}`,
+      },
+      resource: paymentRequired.resource,
+      x402Version: 2,
+    })
+    const replay = await route(
+      new Request('https://example.com/body', {
+        body: JSON.stringify({ a: 2 }),
+        headers: { [Types.paymentSignatureHeader]: paymentSignature },
+        method: 'POST',
+      }),
+    )
+    expect(replay.status).toBe(402)
+    expect(verifyCalls).toBe(0)
+  })
+
+  test('serves tempo and x402 from one composed live endpoint', async () => {
+    const payment = ServerMppx.create({
+      methods: [
+        tempo.charge({
+          account: accounts[0],
+          currency: asset,
+          getClient: () => client,
+          recipient: accounts[0].address,
+        }),
+        evm.charge({
+          currency: evm.assets.baseSepolia.USDC,
+          recipient: accounts[0].address,
+          x402: {
+            facilitator: {
+              async verify(paymentPayload: Types.PaymentPayload) {
+                return {
+                  isValid: true,
+                  payer: payerOf(paymentPayload),
+                }
+              },
+              async settle(paymentPayload: Types.PaymentPayload) {
+                return {
+                  network: paymentPayload.accepted.network,
+                  payer: payerOf(paymentPayload),
+                  success: true,
+                  transaction,
+                }
+              },
+            },
+          },
+        }),
+      ],
+      secretKey,
+    })
+    const paid = payment.compose(
+      [payment.tempo.charge, { amount: '0', chainId: client.chain!.id }],
+      [payment.evm.charge, { amount: '0.01' }],
+    )
+
+    const server = await Http.createServer(async (req, res) => {
+      const request = ServerRequest.fromNodeListener(req, res)
+      const result = await paid(request)
+      if (result.status === 402) return NodeListener.sendResponse(res, result.challenge)
+      return NodeListener.sendResponse(res, result.withReceipt(new Response('paid ok')))
+    })
+
+    try {
+      const challenge = await fetch(server.url)
+      expect(challenge.status).toBe(402)
+      expect(challenge.headers.has('WWW-Authenticate')).toBe(true)
+      expect(challenge.headers.has(Types.paymentRequiredHeader)).toBe(true)
+
+      const tempoClientPayment = ClientMppx.create({
+        methods: [
+          tempoClient.charge({
+            account: accounts[0],
+            getClient: () => client,
+          }),
+        ],
+        polyfill: false,
+      })
+      const tempoResponse = await tempoClientPayment.fetch(server.url)
+      expect(tempoResponse.status).toBe(200)
+      expect(await tempoResponse.text()).toBe('paid ok')
+      expect(tempoResponse.headers.has('Payment-Receipt')).toBe(true)
+
+      const x402ClientPayment = ClientMppx.create({
+        methods: [
+          evmClient.charge({
+            account: accounts[0],
+          }),
+        ],
+        polyfill: false,
+      })
+      const paymentSignature = await x402ClientPayment.createCredential(
+        pureX402Challenge(challenge),
+      )
+      const x402Response = await x402ClientPayment.rawFetch(server.url, {
+        headers: { [Types.paymentSignatureHeader]: paymentSignature },
+      })
+      expect(x402Response.status).toBe(200)
+      expect(await x402Response.text()).toBe('paid ok')
+      expect(x402Response.headers.has(Types.paymentResponseHeader)).toBe(true)
+    } finally {
+      server.close()
+    }
+  })
+})
+
+function payerOf(paymentPayload: Types.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(Types.paymentRequiredHeader)
+  if (!paymentRequired) throw new Error('Missing PAYMENT-REQUIRED header.')
+  return new Response(null, {
+    headers: { [Types.paymentRequiredHeader]: paymentRequired },
+    status: 402,
+  })
+}

package/src/x402/Header.test.ts

@@ -0,0 +1,73 @@
+import * as Header from './Header.js'
+import type * as Types from './Types.js'
+
+describe('x402 headers', () => {
+  test('round trips PAYMENT-REQUIRED header values', () => {
+    const paymentRequired: Types.PaymentRequired = {
+      accepts: [
+        {
+          amount: '10000',
+          asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+          extra: {
+            assetTransferMethod: 'eip3009',
+            name: 'USDC',
+            version: '2',
+          },
+          maxTimeoutSeconds: 60,
+          network: 'eip155:84532',
+          payTo: '0x209693Bc6afc0C5328bA36FaF03C514EF312287C',
+          scheme: 'exact',
+        },
+      ],
+      resource: {
+        mimeType: 'application/json',
+        url: 'https://api.example.com/premium-data',
+      },
+      extensions: {
+        mppx: {
+          info: { method: 'GET' },
+          schema: {
+            properties: { method: { type: 'string' } },
+            required: ['method'],
+            type: 'object',
+          },
+        },
+      },
+      x402Version: 2,
+    }
+
+    const header = Header.encodePaymentRequired(paymentRequired)
+
+    expect(Header.decodePaymentRequired(header)).toEqual(paymentRequired)
+  })
+
+  test('round trips PAYMENT-SIGNATURE header values', () => {
+    const paymentPayload: Types.PaymentPayload = {
+      accepted: {
+        amount: '10000',
+        asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+        maxTimeoutSeconds: 60,
+        network: 'eip155:84532',
+        payTo: '0x209693Bc6afc0C5328bA36FaF03C514EF312287C',
+        scheme: 'exact',
+      },
+      payload: {
+        authorization: {
+          from: '0x857b06519E91e3A54538791bDbb0E22373e36b66',
+          nonce: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f13480',
+          to: '0x209693Bc6afc0C5328bA36FaF03C514EF312287C',
+          validAfter: '1740672089',
+          validBefore: '1740672154',
+          value: '10000',
+        },
+        signature:
+          '0x2d6a7588d6acca505cbf0d9a4a227e0c52c6c34008c8e8986a1283259764173608a2ce6496642e377d6da8dbbf5836e9bd15092f9ecab05ded3d6293af148b571c',
+      },
+      x402Version: 2,
+    }
+
+    const header = Header.encodePaymentSignature(paymentPayload)
+
+    expect(Header.decodePaymentSignature(header)).toEqual(paymentPayload)
+  })
+})

package/src/x402/Header.ts

@@ -0,0 +1,34 @@
+import * as HeaderCodec from '../internal/HeaderCodec.js'
+import {
+  PaymentPayloadSchema,
+  PaymentRequiredSchema,
+  SettleResponseSchema,
+  type PaymentPayload,
+  type PaymentRequired,
+  type SettleResponse,
+} from './Types.js'
+
+const paymentRequired = HeaderCodec.createJson(PaymentRequiredSchema)
+const paymentSignature = HeaderCodec.createJson(PaymentPayloadSchema)
+const paymentResponse = HeaderCodec.createJson(SettleResponseSchema)
+
+/** Encodes an x402 payment-required object for the `PAYMENT-REQUIRED` header. */
+export const encodePaymentRequired: (paymentRequired: PaymentRequired) => string =
+  paymentRequired.encode
+
+/** Decodes an x402 `PAYMENT-REQUIRED` header value. */
+export const decodePaymentRequired: (value: string) => PaymentRequired = paymentRequired.decode
+
+/** Encodes an x402 payment payload for the `PAYMENT-SIGNATURE` header. */
+export const encodePaymentSignature: (paymentPayload: PaymentPayload) => string =
+  paymentSignature.encode
+
+/** Decodes an x402 `PAYMENT-SIGNATURE` header value. */
+export const decodePaymentSignature: (value: string) => PaymentPayload = paymentSignature.decode
+
+/** Encodes an x402 settlement response for the `PAYMENT-RESPONSE` header. */
+export const encodePaymentResponse: (paymentResponse: SettleResponse) => string =
+  paymentResponse.encode
+
+/** Decodes an x402 `PAYMENT-RESPONSE` header value. */
+export const decodePaymentResponse: (value: string) => SettleResponse = paymentResponse.decode

package/src/x402/PublicInterface.test-d.ts

@@ -0,0 +1,39 @@
+import { evm, Mppx } from 'mppx/server'
+import type { Account } from 'viem'
+import { describe, expectTypeOf, test } from 'vp/test'
+
+import { evm as clientEvm } from '../client/index.js'
+
+const secretKey = 'test-secret'
+
+describe('x402 public interface', () => {
+  test('server evm charge accepts known assets without transfer metadata', () => {
+    const mppx = Mppx.create({
+      methods: [
+        evm.charge({
+          currency: evm.assets.base.USDC,
+          recipient: '0x209693Bc6afc0C5328bA36FaF03C514EF312287C',
+          x402: {
+            facilitator: 'https://x402.org/facilitator',
+          },
+        }),
+      ],
+      secretKey,
+    })
+
+    expectTypeOf(mppx.evm.charge).toBeFunction()
+    expectTypeOf(mppx.evm.charge({ amount: '0.01' })).toBeFunction()
+  })
+
+  test('client evm charge exposes account config and policies', () => {
+    const method = clientEvm.charge({
+      account: {} as Account,
+      currencies: [clientEvm.assets.baseSepolia.USDC],
+      maxAmount: '0.01',
+      networks: [clientEvm.chains.baseSepolia],
+    })
+
+    expectTypeOf(method.intent).toEqualTypeOf<'charge'>()
+    expectTypeOf(method.name).toEqualTypeOf<'evm'>()
+  })
+})