mppx 0.6.27 → 0.6.29

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'>()
+  })
+})

package/src/x402/Types.ts

@@ -0,0 +1,248 @@
+import * as z from '../zod.js'
+
+export const versions = [2] as const
+
+/** mppx method name used for EVM charge challenges backed by x402. */
+export const paymentMethod = 'evm' as const
+
+/** mppx intent name used for EVM charge challenges backed by x402 exact. */
+export const exactIntent = 'charge' as const
+
+export const schemes = ['exact'] as const
+export const assetTransferMethods = ['eip3009', 'permit2'] as const
+
+/** CAIP-2 namespace prefix for EVM networks. */
+export const evmNetworkPrefix = 'eip155:' as const
+
+/** Prefix for synthetic mppx challenge IDs derived from x402 `accepts` entries. */
+export const syntheticChallengeIdPrefix = 'x402:' as const
+
+/** x402 protocol version supported by this package. */
+export type Version = 2
+
+/** mppx payment method name used for EVM charge challenges backed by x402. */
+export type PaymentMethod = typeof paymentMethod
+
+/** mppx intent name used for EVM charge challenges backed by x402 exact. */
+export type ExactIntent = typeof exactIntent
+
+/** x402 scheme supported by this package. */
+export type Scheme = (typeof schemes)[number]
+
+/** x402 exact EVM asset transfer method. */
+export type AssetTransferMethod = (typeof assetTransferMethods)[number]
+
+/** CAIP-2 EVM network identifier. */
+export type EvmNetwork = `${typeof evmNetworkPrefix}${number}`
+
+/** HTTP header carrying a base64-encoded x402 payment-required response. */
+export const paymentRequiredHeader = 'PAYMENT-REQUIRED'
+
+/** HTTP header carrying a base64-encoded x402 payment payload. */
+export const paymentSignatureHeader = 'PAYMENT-SIGNATURE'
+
+/** HTTP header carrying a base64-encoded x402 settlement response. */
+export const paymentResponseHeader = 'PAYMENT-RESPONSE'
+
+const nonEmptyString = z.string().check(z.minLength(1))
+const positiveNumber = z.number().check(z.refine((value) => value > 0, 'Must be positive'))
+const atomicAmount = z.string().check(z.regex(/^\d+$/, 'Invalid atomic amount'))
+const address = z.address()
+const evmNetwork = z
+  .string()
+  .check(
+    z.regex(new RegExp(`^${evmNetworkPrefix}\\d+$`), 'Invalid EVM CAIP-2 network'),
+  ) as z.ZodMiniType<EvmNetwork>
+
+/** Describes the protected resource in x402 v2 payment-required responses. */
+export const ResourceInfoSchema = z.object({
+  description: z.optional(z.string()),
+  iconUrl: z.optional(z.string()),
+  mimeType: z.optional(z.string()),
+  serviceName: z.optional(z.string()),
+  tags: z.optional(z.array(z.string())),
+  url: nonEmptyString,
+})
+
+/** Describes the protected resource in x402 v2 payment-required responses. */
+export type ResourceInfo = z.infer<typeof ResourceInfoSchema>
+
+/** Public transfer configuration for exact EVM payments. */
+export const ExactTransferSchema = z.discriminatedUnion('type', [
+  z.object({
+    name: nonEmptyString,
+    type: z.literal('eip3009'),
+    version: nonEmptyString,
+  }),
+  z.object({
+    name: z.optional(z.string()),
+    type: z.literal('permit2'),
+    version: z.optional(z.string()),
+  }),
+])
+
+/** Public EIP-3009 transfer configuration for exact EVM payments. */
+export type ExactEip3009Transfer = Extract<z.infer<typeof ExactTransferSchema>, { type: 'eip3009' }>
+
+/** Public Permit2 transfer configuration for exact EVM payments. */
+export type ExactPermit2Transfer = Extract<z.infer<typeof ExactTransferSchema>, { type: 'permit2' }>
+
+/** Public transfer configuration for exact EVM payments. */
+export type ExactTransfer = z.infer<typeof ExactTransferSchema>
+
+/** Known asset metadata used to derive x402 wire `extra` fields. */
+export type Asset = {
+  address: `0x${string}`
+  decimals: number
+  transfer: ExactTransfer
+}
+
+/** x402 v2 payment requirements for the `exact` scheme. */
+export const PaymentRequirementsSchema = z.object({
+  amount: atomicAmount,
+  asset: nonEmptyString,
+  extra: z.optional(z.record(z.string(), z.unknown())),
+  maxTimeoutSeconds: positiveNumber,
+  network: evmNetwork,
+  payTo: nonEmptyString,
+  scheme: z.enum(schemes),
+})
+
+/** x402 v2 payment requirements for the `exact` scheme. */
+export type PaymentRequirements = z.infer<typeof PaymentRequirementsSchema>
+
+/** x402 v2 protocol extension value. */
+export const ExtensionSchema = z.object({
+  info: z.record(z.string(), z.unknown()),
+  schema: z.record(z.string(), z.unknown()),
+})
+
+/** x402 v2 protocol extension value. */
+export type Extension = z.infer<typeof ExtensionSchema>
+
+/** x402 v2 protocol extensions map. */
+export const ExtensionsSchema = z.record(z.string(), ExtensionSchema)
+
+/** x402 v2 protocol extensions map. */
+export type Extensions = z.infer<typeof ExtensionsSchema>
+
+/** Public exact EVM route request accepted by `mppx` handlers. */
+export type ExactRequest = PaymentRequirements & {
+  extensions?: Extensions | undefined
+  resource?: ResourceInfo | undefined
+}
+
+/** x402 v2 payment-required response. */
+export const PaymentRequiredSchema = z.object({
+  accepts: z.array(PaymentRequirementsSchema).check(z.minLength(1)),
+  error: z.optional(z.string()),
+  extensions: z.optional(ExtensionsSchema),
+  resource: ResourceInfoSchema,
+  x402Version: z.literal(2),
+})
+
+/** x402 v2 payment-required response. */
+export type PaymentRequired = z.infer<typeof PaymentRequiredSchema>
+
+/** EIP-3009 transferWithAuthorization payload for exact EVM payments. */
+export const ExactEip3009PayloadSchema = z.object({
+  authorization: z.object({
+    from: address,
+    nonce: z.hash(),
+    to: address,
+    validAfter: atomicAmount,
+    validBefore: atomicAmount,
+    value: atomicAmount,
+  }),
+  signature: z.signature(),
+})
+
+/** EIP-3009 transferWithAuthorization payload for exact EVM payments. */
+export type ExactEip3009Payload = z.infer<typeof ExactEip3009PayloadSchema>
+
+/** Permit2 payload for exact EVM payments. */
+export const ExactPermit2PayloadSchema = z.object({
+  permit2Authorization: z.object({
+    deadline: atomicAmount,
+    from: address,
+    nonce: atomicAmount,
+    permitted: z.object({
+      amount: atomicAmount,
+      token: address,
+    }),
+    spender: address,
+    witness: z.object({
+      to: address,
+      validAfter: atomicAmount,
+    }),
+  }),
+  signature: z.signature(),
+})
+
+/** Permit2 payload for exact EVM payments. */
+export type ExactPermit2Payload = z.infer<typeof ExactPermit2PayloadSchema>
+
+/** Exact EVM payment payload body. */
+export const ExactPayloadSchema = z.union([ExactEip3009PayloadSchema, ExactPermit2PayloadSchema])
+
+/** Exact EVM payment payload body. */
+export type ExactPayload = z.infer<typeof ExactPayloadSchema>
+
+/** x402 v2 payment payload. */
+export const PaymentPayloadSchema = z.object({
+  accepted: PaymentRequirementsSchema,
+  extensions: z.optional(ExtensionsSchema),
+  payload: ExactPayloadSchema,
+  resource: z.optional(ResourceInfoSchema),
+  x402Version: z.literal(2),
+})
+
+/** x402 v2 payment payload. */
+export type PaymentPayload = z.infer<typeof PaymentPayloadSchema>
+
+/** Facilitator verification response. */
+export const VerifyResponseSchema = z.object({
+  extensions: z.optional(ExtensionsSchema),
+  extra: z.optional(z.record(z.string(), z.unknown())),
+  invalidMessage: z.optional(z.string()),
+  invalidReason: z.optional(z.string()),
+  isValid: z.boolean(),
+  payer: z.optional(z.string()),
+})
+
+/** Facilitator verification response. */
+export type VerifyResponse = z.infer<typeof VerifyResponseSchema>
+
+/** Facilitator settlement response and x402 `PAYMENT-RESPONSE` body. */
+export const SettleResponseSchema = z.object({
+  amount: z.optional(atomicAmount),
+  errorMessage: z.optional(z.string()),
+  errorReason: z.optional(z.string()),
+  extensions: z.optional(ExtensionsSchema),
+  extra: z.optional(z.record(z.string(), z.unknown())),
+  network: nonEmptyString,
+  payer: z.optional(z.string()),
+  success: z.boolean(),
+  transaction: z.string(),
+})
+
+/** Facilitator settlement response and x402 `PAYMENT-RESPONSE` body. */
+export type SettleResponse = z.infer<typeof SettleResponseSchema>
+
+/** x402 facilitator client interface used by server exact config. */
+export type Facilitator = {
+  settle: (
+    paymentPayload: PaymentPayload,
+    paymentRequirements: PaymentRequirements,
+  ) => Promise<SettleResponse>
+  verify: (
+    paymentPayload: PaymentPayload,
+    paymentRequirements: PaymentRequirements,
+  ) => Promise<VerifyResponse>
+}
+
+/** Extracts x402 `PaymentRequirements` from a canonical exact request. */
+export function toPaymentRequirements(request: ExactRequest): PaymentRequirements {
+  const { extensions: _extensions, resource: _resource, ...paymentRequirements } = request
+  return PaymentRequirementsSchema.parse(paymentRequirements)
+}

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

@@ -0,0 +1,180 @@
+import { Challenge } from 'mppx'
+import type { Account } from 'viem'
+import { describe, expect, test, vi } from 'vp/test'
+
+import * as Chains from '../../evm/Chains.js'
+import * as Assets from '../Assets.js'
+import * as Header from '../Header.js'
+import * as RouteBinding from '../internal/RouteBinding.js'
+import * as Types from '../Types.js'
+import { createCredential } from './Exact.js'
+
+type X402Challenge = Parameters<typeof createCredential>[0]['challenge']
+
+const account = {
+  address: '0x1111111111111111111111111111111111111111',
+  signTypedData: vi.fn(async () => '0x1234'),
+} as unknown as Account
+const usdc = Assets.define({
+  address: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+  decimals: 6,
+  network: 'eip155:84532',
+  transfer: {
+    name: 'USDC',
+    type: 'eip3009',
+    version: '2',
+  },
+})
+
+describe('x402 exact credential helper', () => {
+  test('enforces max amount, network, and currency policy before signing', async () => {
+    const config = {
+      account,
+      currencies: [usdc],
+      maxAmount: '0.01',
+      networks: [Chains.baseSepolia],
+    } as const
+
+    await expect(
+      createCredential({
+        challenge: challenge({ amount: '10001' }),
+        config,
+        context: {},
+      }),
+    ).rejects.toThrow('x402 exact amount exceeds maxAmount.')
+
+    await expect(
+      createCredential({
+        challenge: challenge({ network: 'eip155:8453' }),
+        config,
+        context: {},
+      }),
+    ).rejects.toThrow('x402 exact chain ID is not allowed: 8453.')
+
+    await expect(
+      createCredential({
+        challenge: challenge({ asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' }),
+        config,
+        context: {},
+      }),
+    ).rejects.toThrow(
+      'x402 exact currency is not allowed: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.',
+    )
+
+    expect(account.signTypedData).not.toHaveBeenCalled()
+  })
+
+  test('requires network policy for raw hex currencies', async () => {
+    await expect(
+      createCredential({
+        challenge: challenge(),
+        config: {
+          account,
+          currencies: [usdc.address],
+          maxAmount: '0.01',
+        },
+        context: {},
+      }),
+    ).rejects.toThrow('x402 exact raw currency allowlists require networks.')
+  })
+
+  test('signs EIP-3009 exact payment payloads', async () => {
+    const signTypedData = vi.fn(async () => '0x1234')
+    const config = {
+      account: {
+        ...account,
+        signTypedData,
+      } as unknown as Account,
+      currencies: [usdc],
+      maxAmount: '0.01',
+      networks: [Chains.baseSepolia],
+    } as const
+
+    const credential = await createCredential({
+      challenge: challenge(),
+      config,
+      context: {},
+    })
+    const paymentPayload = Header.decodePaymentSignature(credential)
+
+    expect(signTypedData).toHaveBeenCalledOnce()
+    expect(paymentPayload.x402Version).toBe(2)
+    expect(paymentPayload.accepted.scheme).toBe('exact')
+    expect('authorization' in paymentPayload.payload).toBe(true)
+    if (!('authorization' in paymentPayload.payload)) throw new Error()
+    expect(paymentPayload.extensions?.mppx?.info.method).toBe('GET')
+    expect(paymentPayload.extensions?.mppx?.info.nonce).toMatch(/^[0-9a-f]{64}$/)
+    expect(paymentPayload.payload.authorization.nonce).toBe(
+      RouteBinding.nonce({
+        accepted: paymentPayload.accepted,
+        extensions: paymentPayload.extensions!,
+        resource: paymentPayload.resource!,
+      }),
+    )
+    expect(paymentPayload.payload.signature).toBe('0x1234')
+  })
+
+  test('uses a fresh route-bound nonce for repeated payments', async () => {
+    const config = {
+      account,
+      currencies: [usdc],
+      maxAmount: '0.01',
+      networks: [Chains.baseSepolia],
+    } as const
+
+    const first = Header.decodePaymentSignature(
+      await createCredential({
+        challenge: challenge(),
+        config,
+        context: {},
+      }),
+    )
+    const second = Header.decodePaymentSignature(
+      await createCredential({
+        challenge: challenge(),
+        config,
+        context: {},
+      }),
+    )
+
+    expect(first.extensions?.mppx?.info.nonce).not.toBe(second.extensions?.mppx?.info.nonce)
+    if (!('authorization' in first.payload) || !('authorization' in second.payload))
+      throw new Error()
+    expect(first.payload.authorization.nonce).not.toBe(second.payload.authorization.nonce)
+  })
+})
+
+function challenge(overrides: Partial<Types.PaymentRequirements> = {}): X402Challenge {
+  return Challenge.from({
+    id: 'x402-test',
+    intent: 'charge',
+    method: 'evm',
+    realm: 'example.com',
+    request: {
+      amount: '10000',
+      asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+      extra: {
+        assetTransferMethod: 'eip3009',
+        name: 'USDC',
+        version: '2',
+      },
+      maxTimeoutSeconds: 60,
+      network: 'eip155:84532',
+      payTo: '0x2222222222222222222222222222222222222222',
+      scheme: 'exact',
+      extensions: {
+        mppx: {
+          info: { method: 'GET' },
+          schema: {
+            additionalProperties: false,
+            properties: { method: { type: 'string' }, nonce: { type: 'string' } },
+            required: ['method'],
+            type: 'object',
+          },
+        },
+      },
+      resource: { url: 'https://example.com/paid' },
+      ...overrides,
+    },
+  }) as X402Challenge
+}

package/src/x402/client/Exact.ts

@@ -0,0 +1,198 @@
+import type { Account } from 'viem'
+import { getAddress, parseUnits } from 'viem'
+
+import type * as Challenge from '../../Challenge.js'
+import * as Assets from '../Assets.js'
+import * as Header from '../Header.js'
+import * as RouteBinding from '../internal/RouteBinding.js'
+import * as Types from '../Types.js'
+
+/**
+ * Creates an x402 exact `PAYMENT-SIGNATURE` credential.
+ */
+export async function createCredential(parameters: createCredential.Parameters): Promise<string> {
+  const account = (parameters.context?.account ?? parameters.config.account) as Signer
+  if (!account.signTypedData) throw new Error('x402 exact requires a typed-data signer.')
+
+  const request = parameters.challenge.request as Types.ExactRequest
+  const accepted = Types.toPaymentRequirements(request)
+  assertPolicy(parameters.config, accepted)
+  if (!request.resource || !request.extensions?.mppx)
+    throw new Error('x402 exact EIP-3009 requires route binding.')
+  const extensions = withNonceSalt(request.extensions)
+  const transferMethod = accepted.extra?.assetTransferMethod ?? 'eip3009'
+  if (transferMethod !== 'eip3009')
+    throw new Error(`x402 exact ${String(transferMethod)} signing is not implemented yet.`)
+
+  const name = accepted.extra?.name
+  const version = accepted.extra?.version
+  if (typeof name !== 'string' || typeof version !== 'string')
+    throw new Error('x402 exact EIP-3009 requires token name and version.')
+
+  const now = Math.floor(Date.now() / 1000)
+  const authorization: Types.ExactEip3009Payload['authorization'] = {
+    from: getAddress(account.address),
+    nonce: RouteBinding.nonce({
+      accepted,
+      extensions,
+      resource: request.resource,
+    }),
+    to: getAddress(accepted.payTo),
+    validAfter: (now - 600).toString(),
+    validBefore: (now + accepted.maxTimeoutSeconds).toString(),
+    value: accepted.amount,
+  }
+  const signature = await account.signTypedData({
+    domain: {
+      chainId: chainIdOf(accepted.network),
+      name,
+      verifyingContract: getAddress(accepted.asset),
+      version,
+    },
+    message: {
+      ...authorization,
+      value: BigInt(authorization.value),
+      validAfter: BigInt(authorization.validAfter),
+      validBefore: BigInt(authorization.validBefore),
+    },
+    primaryType: 'TransferWithAuthorization',
+    types: authorizationTypes,
+  })
+
+  return Header.encodePaymentSignature({
+    accepted,
+    extensions,
+    payload: {
+      authorization,
+      signature,
+    },
+    ...(request.resource ? { resource: request.resource } : {}),
+    x402Version: 2,
+  })
+}
+
+export declare namespace createCredential {
+  type Parameters = {
+    challenge: Challenge.Challenge<Types.ExactRequest>
+    config: Config
+    context?: Context | undefined
+  }
+}
+
+export type Context = {
+  account?: Account | undefined
+}
+
+export type Signer = Account & {
+  signTypedData?: (parameters: any) => Promise<`0x${string}`>
+}
+
+export type Config = {
+  /** Account used to sign exact EVM payment payloads. */
+  account: Account
+  /** 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
+}
+
+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
+
+function chainIdOf(network: Types.EvmNetwork): number {
+  return Number(network.slice(Types.evmNetworkPrefix.length))
+}
+
+function assertPolicy(parameters: Config, accepted: Types.PaymentRequirements) {
+  const chainId = chainIdOf(accepted.network)
+  if (parameters.networks && !parameters.networks.includes(chainId))
+    throw new Error(`x402 exact 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('x402 exact raw currency allowlists require networks.')
+  if (currencies) {
+    const acceptedCurrency = getAddress(accepted.asset as `0x${string}`)
+    const allowed = currencies.some((currency) =>
+      currencyMatches(currency, acceptedCurrency, accepted.network),
+    )
+    if (!allowed) throw new Error(`x402 exact currency is not allowed: ${acceptedCurrency}.`)
+  }
+
+  if (
+    parameters.maxAtomicAmount !== undefined &&
+    BigInt(accepted.amount) > BigInt(parameters.maxAtomicAmount)
+  )
+    throw new Error('x402 exact amount exceeds maxAtomicAmount.')
+
+  if (parameters.maxAmount !== undefined) {
+    const decimals = decimalsOfAcceptedCurrency(parameters, accepted)
+    if (decimals === undefined) throw new Error('x402 exact maxAmount requires currency decimals.')
+    if (BigInt(accepted.amount) > parseUnits(parameters.maxAmount, decimals))
+      throw new Error('x402 exact amount exceeds maxAmount.')
+  }
+}
+
+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: Config,
+  accepted: Types.PaymentRequirements,
+): number | undefined {
+  const currencies = parameters.currencies ?? parameters.assets
+  const acceptedCurrency = getAddress(accepted.asset as `0x${string}`)
+  const currency = currencies?.find((currency) =>
+    currencyMatches(currency, acceptedCurrency, accepted.network),
+  )
+  if (currency && Assets.isAsset(currency)) return currency.decimals
+  return parameters.decimals
+}
+
+function withNonceSalt(extensions: Types.Extensions): Types.Extensions {
+  const mppx = extensions.mppx
+  if (!mppx) return extensions
+  return {
+    ...extensions,
+    mppx: {
+      ...mppx,
+      info: {
+        ...mppx.info,
+        nonce: randomNonceSalt(),
+      },
+    },
+  }
+}
+
+function randomNonceSalt(): string {
+  const crypto = globalThis.crypto
+  if (!crypto?.getRandomValues) throw new Error('x402 exact requires crypto randomness.')
+  const bytes = crypto.getRandomValues(new Uint8Array(32))
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('')
+}

package/src/x402/index.ts

@@ -0,0 +1,5 @@
+export * as Assets from './Assets.js'
+export * as Header from './Header.js'
+export * as Types from './Types.js'
+export * as assets from './Assets.js'
+export * from './Types.js'

package/src/x402/internal/ChallengeBrand.ts

@@ -0,0 +1,14 @@
+const x402Challenge = Symbol.for('mppx.x402.challenge')
+
+/** Marks a synthetic challenge as originating from an x402 `PAYMENT-REQUIRED` response. */
+export function mark<const challenge extends object>(challenge: challenge): challenge {
+  Object.defineProperty(challenge, x402Challenge, {
+    value: true,
+  })
+  return challenge
+}
+
+/** Returns whether a challenge originated from an x402 `PAYMENT-REQUIRED` response. */
+export function is(challenge: unknown): boolean {
+  return Boolean((challenge as { [x402Challenge]?: true } | undefined)?.[x402Challenge])
+}