mppx 0.6.27 → 0.6.29

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

@@ -0,0 +1,109 @@
+import * as evmRoot from 'mppx/evm'
+import {
+  assets as clientAssets,
+  chains as clientChains,
+  charge as clientCharge,
+  evm as clientEvm,
+} from 'mppx/evm/client'
+import { assets as serverAssets, charge as serverCharge, evm as serverEvm } from 'mppx/evm/server'
+import type { Account } from 'viem'
+import { describe, expectTypeOf, test } from 'vp/test'
+
+import { Mppx as ClientMppx } from '../client/index.js'
+import { Mppx as ServerMppx } from '../server/index.js'
+
+const account = {} as Account
+const recipient = '0x209693Bc6afc0C5328bA36FaF03C514EF312287C'
+const secretKey = 'test-secret'
+const settle = async () => ({
+  reference: `0x${'1'.repeat(64)}` as `0x${string}`,
+})
+const facilitator = {
+  settle: async () => ({
+    network: 'eip155:8453',
+    success: true,
+    transaction: `0x${'1'.repeat(64)}` as `0x${string}`,
+  }),
+  verify: async () => ({ isValid: true }),
+}
+
+describe('evm public interface', () => {
+  test('exports EVM asset metadata from root and subpaths', () => {
+    expectTypeOf(evmRoot.assets.base.USDC).toMatchTypeOf<typeof serverAssets.base.USDC>()
+    expectTypeOf(clientAssets.baseSepolia.USDC).toMatchTypeOf<
+      typeof serverAssets.baseSepolia.USDC
+    >()
+    expectTypeOf(evmRoot.chains.base).toMatchTypeOf<number>()
+    expectTypeOf(clientChains.baseSepolia).toMatchTypeOf<number>()
+  })
+
+  test('server charge works through subpath exports and tuple helper', () => {
+    const direct = serverCharge({
+      currency: serverAssets.base.USDC,
+      recipient,
+      x402: { facilitator },
+    })
+    expectTypeOf(direct.name).toEqualTypeOf<'evm'>()
+    expectTypeOf(direct.intent).toEqualTypeOf<'charge'>()
+
+    const mppx = ServerMppx.create({
+      methods: [
+        serverEvm({
+          currency: serverAssets.base.USDC,
+          recipient,
+          x402: { facilitator },
+        }),
+      ],
+      secretKey,
+    })
+
+    expectTypeOf(mppx.evm.charge).toBeFunction()
+    expectTypeOf(mppx.evm.charge({ amount: '0.01' })).toBeFunction()
+  })
+
+  test('server charge accepts a custom settlement override', () => {
+    const direct = serverCharge({
+      currency: serverAssets.base.USDC,
+      recipient,
+      settle,
+    })
+    expectTypeOf(direct.name).toEqualTypeOf<'evm'>()
+    expectTypeOf(direct.intent).toEqualTypeOf<'charge'>()
+  })
+
+  test('client charge works through subpath exports and tuple helper', () => {
+    const direct = clientCharge({
+      account,
+      currencies: [clientAssets.baseSepolia.USDC],
+      maxAmount: '0.01',
+      networks: [clientChains.baseSepolia],
+    })
+    expectTypeOf(direct.name).toEqualTypeOf<'evm'>()
+    expectTypeOf(direct.intent).toEqualTypeOf<'charge'>()
+
+    const mppx = ClientMppx.create({
+      methods: [
+        clientEvm({
+          account,
+          currencies: [clientAssets.baseSepolia.USDC],
+          maxAmount: '0.01',
+          networks: [clientEvm.chains.baseSepolia],
+        }),
+      ],
+      polyfill: false,
+    })
+
+    expectTypeOf(mppx.createCredential).toBeFunction()
+  })
+
+  test('server charge rejects x402 exact config shape', () => {
+    serverCharge({
+      // @ts-expect-error evm.charge takes shared charge config, not x402 exact config.
+      config: {
+        currency: serverAssets.base.USDC,
+        recipient,
+        x402: { facilitator },
+      },
+    })
+  })
+})

package/src/evm/Types.ts

@@ -0,0 +1,140 @@
+import { Bytes, Hash } from 'ox'
+
+import * as z from '../zod.js'
+
+/** Payment method name for Payment-auth EVM challenges. */
+export const paymentMethod = 'evm' as const
+
+/** Payment intent name for one-time EVM charges. */
+export const chargeIntent = 'charge' as const
+
+/** CAIP-2 namespace prefix for EVM networks. */
+export const evmNetworkPrefix = 'eip155:' as const
+
+/** EIP-3009 transfer authorization method identifier. */
+export const eip3009 = 'eip3009' as const
+
+/** EVM charge credential types supported by this package. */
+export const credentialTypes = ['authorization'] as const
+
+const atomicAmount = z.string().check(z.regex(/^\d+$/, 'Invalid atomic amount'))
+
+/** EIP-3009 domain metadata for `transferWithAuthorization` signatures. */
+export const AuthorizationConfigSchema = z.object({
+  name: z.string().check(z.minLength(1)),
+  version: z.string().check(z.minLength(1)),
+})
+export type AuthorizationConfig = z.infer<typeof AuthorizationConfigSchema>
+
+/** CAIP-2 EVM network identifier. */
+export type EvmNetwork = `${typeof evmNetworkPrefix}${number}`
+
+/** EVM-specific charge method details. */
+export const MethodDetailsSchema = z.object({
+  chainId: z.number(),
+  credentialTypes: z.optional(z.array(z.enum(credentialTypes)).check(z.minLength(1))),
+  decimals: z.optional(z.number()),
+  permit2Address: z.optional(z.address()),
+  splits: z.optional(
+    z.array(
+      z.object({
+        amount: atomicAmount,
+        recipient: z.address(),
+      }),
+    ),
+  ),
+})
+export type MethodDetails = z.infer<typeof MethodDetailsSchema>
+
+/** Canonical Payment-auth EVM charge request. */
+export const ChargeRequestSchema = z.object({
+  amount: atomicAmount,
+  currency: z.address(),
+  description: z.optional(z.string()),
+  externalId: z.optional(z.string()),
+  methodDetails: MethodDetailsSchema,
+  recipient: z.address(),
+})
+export type ChargeRequest = z.infer<typeof ChargeRequestSchema>
+
+/** Public route input before display-unit amounts are converted to atomic units. */
+export const ChargeRequestInputSchema = z.object({
+  amount: z.amount(),
+  chainId: z.number(),
+  currency: z.address(),
+  credentialTypes: z.optional(z.array(z.enum(credentialTypes)).check(z.minLength(1))),
+  decimals: z.number(),
+  description: z.optional(z.string()),
+  externalId: z.optional(z.string()),
+  permit2Address: z.optional(z.address()),
+  recipient: z.address(),
+  splits: z.optional(
+    z.array(
+      z.object({
+        amount: atomicAmount,
+        recipient: z.address(),
+      }),
+    ),
+  ),
+})
+export type ChargeRequestInput = z.infer<typeof ChargeRequestInputSchema>
+
+/** Payment-auth EVM authorization credential payload. */
+export const AuthorizationPayloadSchema = z.object({
+  from: z.address(),
+  nonce: z.hash(),
+  signature: z.signature(),
+  to: z.address(),
+  type: z.literal('authorization'),
+  validAfter: atomicAmount,
+  validBefore: atomicAmount,
+  value: atomicAmount,
+})
+export type AuthorizationPayload = z.infer<typeof AuthorizationPayloadSchema>
+
+/** Payment-auth EVM charge credential payload. */
+export const ChargePayloadSchema = AuthorizationPayloadSchema
+export type ChargePayload = z.infer<typeof ChargePayloadSchema>
+
+/** EIP-712 type definition for EIP-3009 `transferWithAuthorization`. */
+export const authorizationTypes = {
+  TransferWithAuthorization: [
+    { name: 'from', type: 'address' },
+    { name: 'to', type: 'address' },
+    { name: 'value', type: 'uint256' },
+    { name: 'validAfter', type: 'uint256' },
+    { name: 'validBefore', type: 'uint256' },
+    { name: 'nonce', type: 'bytes32' },
+  ],
+} as const
+
+/** Returns the EIP-712 domain for an EIP-3009 authorization signature. */
+export function authorizationDomain(parameters: {
+  authorization: AuthorizationConfig
+  chainId: number
+  currency: `0x${string}`
+}) {
+  return {
+    chainId: parameters.chainId,
+    name: parameters.authorization.name,
+    verifyingContract: parameters.currency,
+    version: parameters.authorization.version,
+  } as const
+}
+
+/** Computes the Payment-auth EVM challenge hash used as the EIP-3009 nonce. */
+export function challengeHash(challenge: { id: string; realm: string }): `0x${string}` {
+  return Hash.keccak256(Bytes.fromString(`${challenge.id}${challenge.realm}`), {
+    as: 'Hex',
+  }) as `0x${string}`
+}
+
+/** Converts a chain ID to the CAIP-2 EVM network identifier. */
+export function networkOf(chainId: number): EvmNetwork {
+  return `${evmNetworkPrefix}${chainId}`
+}
+
+/** Formats an EVM address as a did:pkh source identifier. */
+export function toSource(parameters: { address: `0x${string}`; chainId: number }) {
+  return `did:pkh:eip155:${parameters.chainId}:${parameters.address}` as const
+}

package/src/evm/client/Charge.test.ts

@@ -0,0 +1,99 @@
+import { Challenge } from 'mppx'
+import type { Account } from 'viem'
+import { describe, expect, test, vi } from 'vp/test'
+
+import * as Assets from '../Assets.js'
+import * as Chains from '../Chains.js'
+import { charge } from './Charge.js'
+
+const account = {
+  address: '0x1111111111111111111111111111111111111111',
+  signTypedData: vi.fn(async () => '0x1234'),
+} as unknown as Account
+
+describe('evm charge client', () => {
+  test('does not sign x402 payloads from unbranded Payment-auth challenges', async () => {
+    const signTypedData = vi.fn(async () => '0x1234')
+    const client = charge({
+      account: {
+        ...account,
+        signTypedData,
+      } as unknown as Account,
+      currencies: [Assets.baseSepolia.USDC],
+      maxAmount: '0.01',
+      networks: [Chains.baseSepolia],
+    })
+    const challenge = Challenge.from({
+      id: 'attacker-controlled',
+      intent: 'charge',
+      method: 'evm',
+      realm: 'api.example.com',
+      request: {
+        amount: '10000',
+        asset: Assets.baseSepolia.USDC.address,
+        maxTimeoutSeconds: 60,
+        network: 'eip155:84532',
+        payTo: '0x2222222222222222222222222222222222222222',
+        scheme: 'exact',
+      },
+    })
+
+    await expect(client.createCredential({ challenge } as never)).rejects.toThrow()
+    expect(signTypedData).not.toHaveBeenCalled()
+  })
+
+  test('does not use server-supplied decimals for maxAmount policy', async () => {
+    const client = charge({
+      account,
+      maxAmount: '1',
+    })
+    const challenge = Challenge.from({
+      id: 'native',
+      intent: 'charge',
+      method: 'evm',
+      realm: 'api.example.com',
+      request: {
+        amount: '1000000000000000000',
+        currency: Assets.baseSepolia.USDC.address,
+        methodDetails: {
+          chainId: 84532,
+          credentialTypes: ['authorization'],
+          decimals: 18,
+        },
+        recipient: '0x2222222222222222222222222222222222222222',
+      },
+    })
+
+    await expect(client.createCredential({ challenge } as never)).rejects.toThrow(
+      'EVM charge maxAmount requires currency decimals.',
+    )
+  })
+
+  test('requires network policy for raw hex currencies', async () => {
+    const client = charge({
+      account,
+      currencies: [Assets.baseSepolia.USDC.address],
+      maxAmount: '1',
+    })
+    const challenge = Challenge.from({
+      id: 'native',
+      intent: 'charge',
+      method: 'evm',
+      realm: 'api.example.com',
+      request: {
+        amount: '1000000',
+        currency: Assets.baseSepolia.USDC.address,
+        methodDetails: {
+          chainId: 84532,
+          credentialTypes: ['authorization'],
+          decimals: 6,
+        },
+        recipient: '0x2222222222222222222222222222222222222222',
+      },
+    })
+
+    await expect(client.createCredential({ challenge } as never)).rejects.toThrow(
+      'EVM raw currency allowlists require networks.',
+    )
+  })
+})

package/src/evm/client/Charge.ts

@@ -0,0 +1,198 @@
+import type { Account } from 'viem'
+import { getAddress, parseUnits } from 'viem'
+
+import * as Credential from '../../Credential.js'
+import * as Method from '../../Method.js'
+import * as x402_Exact from '../../x402/client/Exact.js'
+import * as x402_ChallengeBrand from '../../x402/internal/ChallengeBrand.js'
+import * as z from '../../zod.js'
+import * as Assets from '../Assets.js'
+import * as Methods from '../Methods.js'
+import * as Types from '../Types.js'
+
+/**
+ * Creates an EVM charge client method.
+ *
+ * Signs native Payment-auth `authorization` credentials for EVM charges. It
+ * also keeps x402 exact signing for x402 compatibility challenges.
+ */
+export function charge(parameters: charge.Parameters) {
+  return Method.toClient(Methods.charge, {
+    context: z.object({
+      account: z.optional(z.custom<Account>()),
+    }),
+    async createCredential({ challenge, context }) {
+      if (isX402Challenge(challenge))
+        return x402_Exact.createCredential({
+          challenge: challenge as never,
+          config: parameters as x402_Exact.Config,
+          context,
+        })
+
+      const account = (context?.account ?? parameters.account) as charge.Signer
+      if (!account.signTypedData) throw new Error('EVM authorization requires a typed-data signer.')
+
+      const request = challenge.request as Types.ChargeRequest
+      assertPolicy(parameters, request)
+      if (!request.methodDetails.credentialTypes?.includes('authorization')) {
+        throw new Error('EVM authorization is not accepted by this challenge.')
+      }
+      if (request.methodDetails.splits?.length) {
+        throw new Error('EVM authorization does not support payment splits.')
+      }
+
+      const authorization = resolveAuthorization(parameters, request)
+      const validBefore = challenge.expires
+        ? Math.floor(new Date(challenge.expires).getTime() / 1000).toString()
+        : (Math.floor(Date.now() / 1000) + 300).toString()
+
+      const payload: Types.AuthorizationPayload = {
+        from: getAddress(account.address),
+        nonce: Types.challengeHash(challenge),
+        signature: await account.signTypedData({
+          domain: Types.authorizationDomain({
+            authorization,
+            chainId: request.methodDetails.chainId,
+            currency: request.currency as `0x${string}`,
+          }),
+          message: {
+            from: getAddress(account.address),
+            nonce: Types.challengeHash(challenge),
+            to: getAddress(request.recipient),
+            validAfter: 0n,
+            validBefore: BigInt(validBefore),
+            value: BigInt(request.amount),
+          },
+          primaryType: 'TransferWithAuthorization',
+          types: Types.authorizationTypes,
+        }),
+        to: getAddress(request.recipient),
+        type: 'authorization',
+        validAfter: '0',
+        validBefore,
+        value: request.amount,
+      }
+
+      return Credential.serialize(
+        Credential.from({
+          challenge,
+          payload,
+          source: Types.toSource({
+            address: getAddress(account.address),
+            chainId: request.methodDetails.chainId,
+          }),
+        }),
+      )
+    },
+  })
+}
+
+export declare namespace charge {
+  type Signer = Account & {
+    signTypedData?: (parameters: any) => Promise<`0x${string}`>
+  }
+
+  type Parameters = {
+    /** Account used to sign EVM charge credentials. */
+    account: Account
+    /** EIP-3009 token domain metadata for custom currencies. */
+    authorization?: Types.AuthorizationConfig | undefined
+    /** Optional token decimals used to parse `maxAmount` when currency metadata is not provided. */
+    decimals?: number | undefined
+    /** Optional maximum display-unit amount the client is willing to pay. */
+    maxAmount?: string | undefined
+    /** Optional maximum atomic amount the client is willing to pay. */
+    maxAtomicAmount?: string | undefined
+    /** Optional allowlist of supported EVM chain IDs. */
+    networks?: readonly number[] | undefined
+    /** Optional allowlist of supported currencies. */
+    currencies?: readonly (`0x${string}` | Assets.KnownAsset)[] | undefined
+    /** Legacy alias for `currencies`. */
+    assets?: readonly (`0x${string}` | Assets.KnownAsset)[] | undefined
+  }
+}
+
+function isX402Challenge(challenge: { request: Record<string, unknown> }) {
+  return (
+    x402_ChallengeBrand.is(challenge) &&
+    challenge.request.scheme === 'exact' &&
+    typeof challenge.request.network === 'string'
+  )
+}
+
+function assertPolicy(parameters: charge.Parameters, request: Types.ChargeRequest) {
+  const chainId = request.methodDetails.chainId
+  const network = Types.networkOf(chainId)
+  if (parameters.networks && !parameters.networks.includes(chainId))
+    throw new Error(`EVM chain ID is not allowed: ${chainId}.`)
+
+  const currencies = parameters.currencies ?? parameters.assets
+  if (currencies?.some((currency) => !Assets.isAsset(currency)) && !parameters.networks?.length)
+    throw new Error('EVM raw currency allowlists require networks.')
+  if (currencies) {
+    const acceptedCurrency = getAddress(request.currency as `0x${string}`)
+    const allowed = currencies.some((currency) =>
+      currencyMatches(currency, acceptedCurrency, network),
+    )
+    if (!allowed) throw new Error(`EVM currency is not allowed: ${acceptedCurrency}.`)
+  }
+
+  if (
+    parameters.maxAtomicAmount !== undefined &&
+    BigInt(request.amount) > BigInt(parameters.maxAtomicAmount)
+  )
+    throw new Error('EVM charge amount exceeds maxAtomicAmount.')
+
+  if (parameters.maxAmount !== undefined) {
+    const decimals = decimalsOfAcceptedCurrency(parameters, request)
+    if (decimals === undefined) throw new Error('EVM charge maxAmount requires currency decimals.')
+    if (BigInt(request.amount) > parseUnits(parameters.maxAmount, decimals))
+      throw new Error('EVM charge amount exceeds maxAmount.')
+  }
+}
+
+function resolveAuthorization(
+  parameters: charge.Parameters,
+  request: Types.ChargeRequest,
+): Types.AuthorizationConfig {
+  const currencies = parameters.currencies ?? parameters.assets
+  const acceptedCurrency = getAddress(request.currency as `0x${string}`)
+  const network = Types.networkOf(request.methodDetails.chainId)
+  const currency = currencies?.find((currency) =>
+    currencyMatches(currency, acceptedCurrency, network),
+  )
+  if (currency && Assets.isAsset(currency) && currency.transfer.type === Types.eip3009)
+    return {
+      name: currency.transfer.name,
+      version: currency.transfer.version,
+    }
+  if (parameters.authorization) return parameters.authorization
+  throw new Error('EVM authorization requires token name and version.')
+}
+
+function addressOf(currency: `0x${string}` | Assets.KnownAsset): `0x${string}` {
+  return Assets.isAsset(currency) ? currency.address : currency
+}
+
+function currencyMatches(
+  currency: `0x${string}` | Assets.KnownAsset,
+  acceptedCurrency: `0x${string}`,
+  network: Types.EvmNetwork,
+): boolean {
+  if (getAddress(addressOf(currency)) !== acceptedCurrency) return false
+  return !Assets.isAsset(currency) || currency.network === network
+}
+
+function decimalsOfAcceptedCurrency(
+  parameters: charge.Parameters,
+  request: Types.ChargeRequest,
+): number | undefined {
+  const currencies = parameters.currencies ?? parameters.assets
+  const acceptedCurrency = getAddress(request.currency as `0x${string}`)
+  const network = Types.networkOf(request.methodDetails.chainId)
+  const currency = currencies?.find((currency) =>
+    currencyMatches(currency, acceptedCurrency, network),
+  )
+  if (currency && Assets.isAsset(currency)) return currency.decimals
+  return parameters.decimals
+}

package/src/evm/client/Methods.ts

@@ -0,0 +1,19 @@
+import * as Assets from '../Assets.js'
+import * as Chains from '../Chains.js'
+import { charge as charge_ } from './Charge.js'
+
+/** Creates EVM client methods from shared charge parameters. */
+export function evm(parameters: evm.Parameters) {
+  return [evm.charge(parameters)] as const
+}
+
+export namespace evm {
+  export type Parameters = charge_.Parameters
+
+  /** Creates an EVM `charge` client 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/client/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/evm/index.ts

@@ -0,0 +1,13 @@
+export * as Assets from './Assets.js'
+export * as Chains from './Chains.js'
+export * as Methods from './Methods.js'
+export * as Types from './Types.js'
+export * as assets from './Assets.js'
+export * as chains from './Chains.js'
+export * from './Types.js'
+export type {
+  ExactEip3009Transfer,
+  ExactPermit2Transfer,
+  ExactTransfer,
+  ResourceInfo,
+} from '../x402/Types.js'