mppx 0.6.27 → 0.6.29

package/src/client/Mppx.ts

@@ -7,7 +7,7 @@ import * as Fetch from './internal/Fetch.js'
 import * as Transport from './Transport.js'
 
 export type Methods = readonly (Method.AnyClient | readonly Method.AnyClient[])[]
-type EventResponseOf<transport extends Transport.Transport> =
+type EventResponseOf<transport extends Transport.AnyTransport> =
   | Response
   | Transport.ResponseOf<transport>
 
@@ -16,7 +16,7 @@ type EventResponseOf<transport extends Transport.Transport> =
  */
 export type Mppx<
   methods extends Methods = Methods,
-  transport extends Transport.Transport = Transport.Transport,
+  transport extends Transport.AnyTransport = Transport.Transport,
 > = {
   /** Payment-aware fetch function that automatically handles 402 responses. */
   fetch: Fetch.from.Fetch<FlattenMethods<methods>>
@@ -125,6 +125,7 @@ export function create<
     ...(resolvedOnChallenge && { onChallenge: resolvedOnChallenge }),
     ...(orderChallenges && { orderChallenges }),
     methods,
+    transport,
   } satisfies Fetch.from.Config<FlattenMethods<methods>>
   const fetch = Fetch.from<FlattenMethods<methods>>(config_fetch)
 
@@ -282,7 +283,7 @@ export function restore(): void {
 export declare namespace create {
   type Config<
     methods extends Methods = Methods,
-    transport extends Transport.Transport = Transport.Transport,
+    transport extends Transport.AnyTransport = Transport.Transport,
   > = {
     /** Controls when `Accept-Payment` is injected. */
     acceptPaymentPolicy?: Fetch.from.Config['acceptPaymentPolicy'] | undefined

package/src/client/Transport.test.ts

@@ -1,6 +1,7 @@
 import { Challenge, Credential, Mcp } from 'mppx'
 import { Transport } from 'mppx/client'
 import { Methods } from 'mppx/tempo'
+import { Header as x402_Header, Types as x402_Types, type PaymentRequired } from 'mppx/x402'
 import { describe, expect, test } from 'vp/test'
 
 const realm = 'api.example.com'
@@ -23,27 +24,34 @@ const credential = Credential.from({
   payload: { signature: '0xabc123', type: 'transaction' },
 })
 
+const x402PaymentRequired = {
+  accepts: [
+    {
+      amount: '10000',
+      asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+      maxTimeoutSeconds: 60,
+      network: 'eip155:84532',
+      payTo: '0x209693Bc6afc0C5328bA36FaF03C514EF312287C',
+      scheme: x402_Types.schemes[0],
+    },
+  ],
+  resource: {
+    url: 'https://api.example.com/x402',
+  },
+  x402Version: 2,
+} satisfies PaymentRequired
+
 describe('http', () => {
   describe('isPaymentRequired', () => {
-    test('returns true for 402 response', () => {
-      const transport = Transport.http()
-      const response = new Response(null, { status: 402 })
-
-      expect(transport.isPaymentRequired(response)).toBe(true)
-    })
+    test.each([
+      { expected: true, status: 402 },
+      { expected: false, status: 200 },
+      { expected: false, status: 401 },
+    ])('returns $expected for $status response', ({ expected, status }) => {
+      const response = new Response(null, { status })
 
-    test('returns false for 200 response', () => {
       const transport = Transport.http()
-      const response = new Response(null, { status: 200 })
-
-      expect(transport.isPaymentRequired(response)).toBe(false)
-    })
-
-    test('returns false for other error responses', () => {
-      const transport = Transport.http()
-      const response = new Response(null, { status: 401 })
-
-      expect(transport.isPaymentRequired(response)).toBe(false)
+      expect(transport.isPaymentRequired(response)).toBe(expected)
     })
   })
 
@@ -80,32 +88,159 @@ describe('http', () => {
   })
 
   describe('getChallenges', () => {
-    test('returns all HTTP challenges', () => {
+    test.each([
+      {
+        expectedIds: [challenge.id, 'alternate'],
+        expectedMethods: ['tempo', 'stripe'],
+        headers: () => ({
+          'WWW-Authenticate': `${Challenge.serialize(challenge)}, ${Challenge.serialize({
+            ...challenge,
+            id: 'alternate',
+            method: 'stripe' as const,
+          })}`,
+        }),
+        name: 'Payment auth challenges',
+      },
+      {
+        expectedIds: [`${x402_Types.syntheticChallengeIdPrefix}0`],
+        expectedMethods: [x402_Types.paymentMethod],
+        headers: () => ({
+          'PAYMENT-REQUIRED': x402_Header.encodePaymentRequired(x402PaymentRequired),
+        }),
+        name: 'x402 challenges',
+      },
+      {
+        expectedIds: [
+          `${x402_Types.syntheticChallengeIdPrefix}0`,
+          `${x402_Types.syntheticChallengeIdPrefix}1`,
+        ],
+        expectedMethods: [x402_Types.paymentMethod, x402_Types.paymentMethod],
+        headers: () => ({
+          'PAYMENT-REQUIRED': x402_Header.encodePaymentRequired({
+            ...x402PaymentRequired,
+            accepts: [
+              x402PaymentRequired.accepts[0]!,
+              {
+                ...x402PaymentRequired.accepts[0]!,
+                amount: '20000',
+              },
+            ],
+          }),
+        }),
+        name: 'multiple x402 accepts',
+      },
+      {
+        expectedIds: [challenge.id, `${x402_Types.syntheticChallengeIdPrefix}0`],
+        expectedMethods: ['tempo', x402_Types.paymentMethod],
+        headers: () => ({
+          'PAYMENT-REQUIRED': x402_Header.encodePaymentRequired(x402PaymentRequired),
+          'WWW-Authenticate': Challenge.serialize(challenge),
+        }),
+        name: 'Payment auth and x402 challenges when both are present',
+      },
+    ])('returns $name', ({ expectedIds, expectedMethods, headers }) => {
       const transport = Transport.http()
-      const alternate = { ...challenge, id: 'alternate', method: 'stripe' as const }
       const response = new Response(null, {
         status: 402,
-        headers: {
-          'WWW-Authenticate': `${Challenge.serialize(challenge)}, ${Challenge.serialize(alternate)}`,
-        },
+        headers: headers(),
       })
+      const challenges = transport.getChallenges?.(response) ?? []
 
-      expect(transport.getChallenges?.(response).map((entry) => entry.id)).toEqual([
-        challenge.id,
-        'alternate',
-      ])
+      expect(challenges.map((entry) => entry.id)).toEqual(expectedIds)
+      expect(challenges.map((entry) => entry.method)).toEqual(expectedMethods)
     })
   })
 
   describe('setCredential', () => {
-    test('default', () => {
+    test.each([
+      {
+        challenge,
+        credential: Credential.serialize(credential),
+        expectedHeader: 'Authorization',
+        expectedValue: Credential.serialize(credential),
+        name: 'Payment auth credential for Payment auth challenge',
+      },
+      {
+        challenge: Transport.http().getChallenges!(
+          new Response(null, {
+            status: 402,
+            headers: {
+              'PAYMENT-REQUIRED': x402_Header.encodePaymentRequired(x402PaymentRequired),
+            },
+          }),
+        )[0],
+        credential: 'x402-signature',
+        expectedHeader: 'PAYMENT-SIGNATURE',
+        expectedValue: 'x402-signature',
+        name: 'raw x402 credential for x402 challenge',
+      },
+      {
+        challenge,
+        credential: 'custom-credential',
+        expectedHeader: 'Authorization',
+        expectedValue: 'custom-credential',
+        name: 'non-Payment credential for non-x402 challenge',
+      },
+      {
+        challenge: undefined,
+        credential: 'custom-credential',
+        expectedHeader: 'Authorization',
+        expectedValue: 'custom-credential',
+        name: 'credential without selected challenge',
+      },
+    ])('writes $name', ({ challenge, credential, expectedHeader, expectedValue }) => {
       const transport = Transport.http()
-      const serialized = Credential.serialize(credential)
 
-      const result = transport.setCredential({}, serialized)
+      const result = transport.setCredential({}, credential, { challenge })
+      const headers = result.headers as Headers
+
+      expect(headers.get(expectedHeader)).toBe(expectedValue)
+    })
+
+    test('does not treat unbranded Payment-auth challenges as x402', () => {
+      const transport = Transport.http()
+      const untrustedChallenge = Challenge.from({
+        id: `${x402_Types.syntheticChallengeIdPrefix}0`,
+        intent: x402_Types.exactIntent,
+        method: x402_Types.paymentMethod,
+        realm: 'api.example.com',
+        request: x402PaymentRequired.accepts[0]!,
+      })
+
+      const result = transport.setCredential({}, 'credential', {
+        challenge: untrustedChallenge,
+      })
+      const headers = result.headers as Headers
+
+      expect(headers.get('Authorization')).toBe('credential')
+      expect(headers.get(x402_Types.paymentSignatureHeader)).toBeNull()
+    })
+
+    test('removes stale credential headers before setting the retry credential', () => {
+      const transport = Transport.http()
+      const x402Challenge = Transport.http().getChallenges!(
+        new Response(null, {
+          status: 402,
+          headers: {
+            'PAYMENT-REQUIRED': x402_Header.encodePaymentRequired(x402PaymentRequired),
+          },
+        }),
+      )[0]
+
+      const result = transport.setCredential(
+        {
+          headers: {
+            Authorization: 'Payment stale',
+            [x402_Types.paymentSignatureHeader]: 'stale-x402',
+          },
+        },
+        'fresh-x402',
+        { challenge: x402Challenge },
+      )
       const headers = result.headers as Headers
 
-      expect(headers.get('Authorization')).toBe(serialized)
+      expect(headers.get('Authorization')).toBeNull()
+      expect(headers.get(x402_Types.paymentSignatureHeader)).toBe('fresh-x402')
     })
 
     test('preserves existing headers', () => {

package/src/client/Transport.ts

@@ -1,6 +1,19 @@
 import * as Challenge from '../Challenge.js'
 import * as Credential from '../Credential.js'
 import * as Mcp from '../Mcp.js'
+import * as x402_Header from '../x402/Header.js'
+import * as x402_ChallengeBrand from '../x402/internal/ChallengeBrand.js'
+import * as x402_Types from '../x402/Types.js'
+
+const paymentRequiredStatus = 402
+const paymentAuthChallengeHeader = 'WWW-Authenticate'
+const paymentAuthCredentialHeader = 'Authorization'
+const credentialHeaders = [
+  paymentAuthCredentialHeader,
+  x402_Types.paymentRequiredHeader,
+  x402_Types.paymentResponseHeader,
+  x402_Types.paymentSignatureHeader,
+]
 
 /**
  * Client-side transport adapter.
@@ -18,10 +31,21 @@ export type Transport<in out request = unknown, in out response = unknown> = {
   /** Extracts the challenge from a payment-required response. */
   getChallenge: (response: response) => Challenge.Challenge
   /** Attaches a credential to a request. */
-  setCredential: (request: request, credential: string) => request
+  setCredential: (
+    request: request,
+    credential: string,
+    options?: setCredential.Options | undefined,
+  ) => request
 }
 export type AnyTransport = Transport<any, any>
 
+export declare namespace setCredential {
+  type Options = {
+    /** Challenge selected for credential creation. */
+    challenge?: Challenge.Challenge | undefined
+  }
+}
+
 /** Extracts the response type from a transport. */
 export type ResponseOf<transport extends Transport> =
   transport extends Transport<any, infer response> ? response : never
@@ -55,33 +79,77 @@ export function from<request, response>(
  * HTTP transport for client-side payment handling.
  *
  * - Detects payment required via 402 status
- * - Extracts challenges from `WWW-Authenticate` header
- * - Sends credentials via `Authorization` header
+ * - Extracts Payment auth challenges from `WWW-Authenticate`
+ * - Falls back to x402 exact challenges from `PAYMENT-REQUIRED`
+ * - Sends credentials via `Authorization` or `PAYMENT-SIGNATURE`
  */
 export function http() {
   return from<RequestInit, Response>({
     name: 'http',
 
     isPaymentRequired(response) {
-      return response.status === 402
+      return response.status === paymentRequiredStatus
     },
 
     getChallenges(response) {
-      return Challenge.fromResponseList(response)
+      return paymentRequiredChallenges(response)
     },
 
     getChallenge(response) {
-      return Challenge.fromResponse(response)
+      const challenge = paymentRequiredChallenges(response)[0]
+      if (!challenge) throw new Error('No challenge in response.')
+      return challenge
     },
 
-    setCredential(request, credential) {
+    setCredential(request, credential, options) {
       const headers = new Headers(request.headers)
-      headers.set('Authorization', credential)
+      for (const header of credentialHeaders) headers.delete(header)
+      if (isX402Challenge(options?.challenge)) {
+        headers.set(x402_Types.paymentSignatureHeader, credential)
+      } else {
+        headers.set(paymentAuthCredentialHeader, credential)
+      }
       return { ...request, headers }
     },
   })
 }
 
+function paymentRequiredChallenges(response: Response): Challenge.Challenge[] {
+  return [
+    ...(response.headers.has(paymentAuthChallengeHeader)
+      ? Challenge.fromResponseList(response)
+      : []),
+    ...x402Challenges(response),
+  ]
+}
+
+function x402Challenges(response: Response): Challenge.Challenge[] {
+  const header = response.headers.get(x402_Types.paymentRequiredHeader)
+  if (!header) return []
+  const paymentRequired = x402_Header.decodePaymentRequired(header)
+  if (response.url && paymentRequired.resource.url !== response.url)
+    throw new Error('x402 payment-required resource does not match response URL.')
+  return paymentRequired.accepts.map((accepted, index) =>
+    x402_ChallengeBrand.mark(
+      Challenge.from({
+        id: `${x402_Types.syntheticChallengeIdPrefix}${index}`,
+        intent: x402_Types.exactIntent,
+        method: x402_Types.paymentMethod,
+        realm: new URL(paymentRequired.resource.url).host,
+        request: {
+          ...accepted,
+          ...(paymentRequired.extensions ? { extensions: paymentRequired.extensions } : {}),
+          resource: paymentRequired.resource,
+        },
+      }),
+    ),
+  )
+}
+
+function isX402Challenge(challenge: Challenge.Challenge | undefined): boolean {
+  return x402_ChallengeBrand.is(challenge)
+}
+
 /**
  * MCP transport for client-side payment handling.
  *

package/src/client/index.ts

@@ -1,5 +1,5 @@
 export * as Expires from '../Expires.js'
 export * as Fetch from './internal/Fetch.js'
-export { session, stripe, tempo } from './Methods.js'
+export { evm, session, stripe, tempo } from './Methods.js'
 export * as Mppx from './Mppx.js'
 export * as Transport from './Transport.js'

package/src/client/internal/Fetch.test.ts

@@ -665,8 +665,37 @@ describe('Fetch.from: 402 retry path', () => {
     await fetch('https://example.com/api')
 
     const retryInit = calls[1]!.init as Record<string, unknown>
-    const headers = retryInit.headers as Record<string, string>
-    expect(headers.Authorization).toBe('credential')
+    const headers = new Headers(retryInit.headers as HeadersInit)
+    expect(headers.get('Authorization')).toBe('credential')
+  })
+
+  test('sends credential retry to the final 402 response URL', async () => {
+    let callCount = 0
+    const calls: { input: RequestInfo | URL; init: RequestInit | undefined }[] = []
+    const mockFetch: typeof globalThis.fetch = async (input, init) => {
+      calls.push({ input, init })
+      callCount++
+      if (callCount === 1) {
+        const response = make402()
+        Object.defineProperty(response, 'url', {
+          value: 'https://payments.example.com/protected',
+        })
+        return response
+      }
+      return new Response('OK', { status: 200 })
+    }
+
+    const fetch = Fetch.from({
+      fetch: mockFetch,
+      methods: [noopMethod],
+    })
+
+    const response = await fetch('https://api.example.com/protected')
+
+    expect(response.status).toBe(200)
+    expect(calls[0]!.input).toBe('https://api.example.com/protected')
+    expect(calls[1]!.input).toBe('https://payments.example.com/protected')
+    expect(new Headers(calls[1]!.init?.headers).get('Authorization')).toBe('credential')
   })
 
   test('emits client events and allows challenge handler to provide credential', async () => {

package/src/client/internal/Fetch.ts

@@ -4,6 +4,7 @@ import * as AcceptPayment from '../../internal/AcceptPayment.js'
 import type { MaybePromise } from '../../internal/types.js'
 import type * as Method from '../../Method.js'
 import type * as z from '../../zod.js'
+import * as Transport from '../Transport.js'
 
 // We tag wrappers with a global symbol so we can recognize wrappers created by mppx,
 // even across multiple module instances/bundles. This lets restore() avoid clobbering
@@ -162,6 +163,7 @@ export function from<const methods extends readonly Method.AnyClient[]>(
     methods,
     onChallenge,
     orderChallenges,
+    transport = Transport.http(),
   } = config
   const events = config.eventDispatcher ?? createEventDispatcher()
   const resolvedAcceptPayment = acceptPayment ?? AcceptPayment.resolve(methods)
@@ -183,7 +185,7 @@ export function from<const methods extends readonly Method.AnyClient[]>(
     )
     const response = await baseFetch(initialRequest.input, initialRequest.init)
 
-    if (response.status !== 402) return response
+    if (!transport.isPaymentRequired(response)) return response
 
     // Only extract context for payment handling after confirming 402.
     const context = (init as Record<string, unknown> | undefined)?.context
@@ -198,8 +200,9 @@ export function from<const methods extends readonly Method.AnyClient[]>(
     let mi: methods[number] | undefined
 
     try {
-      // Parse all challenges from the response (supports merged WWW-Authenticate headers).
-      challenges = Challenge.fromResponseList(response)
+      challenges = transport.getChallenges
+        ? transport.getChallenges(response)
+        : [transport.getChallenge(response)]
 
       const candidates = AcceptPayment.selectChallengeCandidates(
         challenges,
@@ -258,10 +261,17 @@ export function from<const methods extends readonly Method.AnyClient[]>(
         }),
       )
 
-      const paymentResponse = await baseFetch(initialRequest.input, {
-        ...fetchInit,
-        headers: withAuthorizationHeader(initialRequest.headers, credential),
-      })
+      const paymentResponse = await baseFetch(
+        resolvePaymentRetryInput(response, initialRequest.input),
+        transport.setCredential(
+          {
+            ...fetchInit,
+            headers: initialRequest.headers,
+          },
+          credential,
+          { challenge: selectedChallenge },
+        ),
+      )
       if (paymentResponse.ok)
         await events.emit(
           'payment.response',
@@ -335,6 +345,8 @@ export declare namespace from {
       | undefined
     /** Filters and sorts supported challenges before credential creation. */
     orderChallenges?: AcceptPayment.OrderChallenges<methods> | undefined
+    /** Transport to use for challenge extraction and credential attachment. */
+    transport?: Transport.AnyTransport | undefined
   }
 
   type Fetch<methods extends readonly Method.AnyClient[] = readonly Method.AnyClient[]> = (
@@ -688,18 +700,6 @@ function freezeSnapshot<value>(value: value): value {
   return value
 }
 
-/** @internal */
-function withAuthorizationHeader(headers: unknown, credential: string): Record<string, string> {
-  const normalized = normalizeHeaders(headers)
-  // Remove any existing Authorization header regardless of casing to avoid
-  // duplicate/conflicting credentials on retry.
-  for (const key of Object.keys(normalized)) {
-    if (key.toLowerCase() === 'authorization') delete normalized[key]
-  }
-  normalized.Authorization = credential
-  return normalized
-}
-
 /** @internal */
 function prepareInitialRequest<methods extends readonly Method.AnyClient[]>(
   input: RequestInfo | URL,
@@ -843,3 +843,10 @@ function resolveRequestUrl(input: RequestInfo | URL): URL {
   if (input instanceof Request) return new URL(input.url)
   return new URL(input, isBrowser() ? globalThis.location.href : undefined)
 }
+
+function resolvePaymentRetryInput(
+  response: Response,
+  fallback: RequestInfo | URL,
+): RequestInfo | URL {
+  return response.url ? response.url : fallback
+}

package/src/evm/Assets.ts

@@ -0,0 +1 @@
+export * from '../x402/Assets.js'

package/src/evm/Chains.ts

@@ -0,0 +1,5 @@
+/** Base mainnet EVM chain ID. */
+export const base = 8453
+
+/** Base Sepolia testnet EVM chain ID. */
+export const baseSepolia = 84532

package/src/evm/Methods.ts

@@ -0,0 +1,44 @@
+import { getAddress, parseUnits } from 'viem'
+
+import * as Method from '../Method.js'
+import * as z from '../zod.js'
+import * as Types from './Types.js'
+
+/** Native Payment-auth EVM charge method. */
+export const charge = Method.from({
+  name: Types.paymentMethod,
+  intent: Types.chargeIntent,
+  schema: {
+    credential: {
+      payload: Types.ChargePayloadSchema,
+    },
+    request: z.pipe(
+      Types.ChargeRequestInputSchema,
+      z.transform(
+        ({
+          amount,
+          chainId,
+          credentialTypes = ['authorization'],
+          currency,
+          decimals,
+          permit2Address,
+          recipient,
+          splits,
+          ...request
+        }) => ({
+          ...request,
+          amount: parseUnits(amount, decimals).toString(),
+          currency: getAddress(currency),
+          methodDetails: {
+            chainId,
+            credentialTypes,
+            decimals,
+            ...(permit2Address ? { permit2Address: getAddress(permit2Address) } : {}),
+            ...(splits ? { splits } : {}),
+          },
+          recipient: getAddress(recipient),
+        }),
+      ),
+    ),
+  },
+})