mppx 0.8.1 → 0.8.3

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

@@ -2,6 +2,7 @@ import { Challenge, Credential, Errors, Mcp, Receipt } from 'mppx'
 import { tempo } from 'mppx/client'
 import { Mppx as Mppx_server, tempo as tempo_server } from 'mppx/server'
 import { Header as x402_Header, Types as x402_Types, type PaymentRequired } from 'mppx/x402'
+import { Base64 } from 'ox'
 import { createClient, defineChain } from 'viem'
 import { describe, expect, test, vi } from 'vp/test'
 import * as Http from '~test/Http.js'
@@ -351,7 +352,8 @@ const x402PaymentRequired = {
 } satisfies PaymentRequired
 
 /** Builds a valid 402 response with a WWW-Authenticate header. */
-function make402(overrides?: { expires?: string; intent?: string; method?: string }) {
+function make402(overrides?: { expires?: string; id?: string; intent?: string; method?: string }) {
+  const id = overrides?.id ?? 'abc'
   const method = overrides?.method ?? 'test'
   const intent = overrides?.intent ?? 'test'
   const expires = overrides?.expires ? `, expires="${overrides.expires}"` : ''
@@ -359,7 +361,7 @@ function make402(overrides?: { expires?: string; intent?: string; method?: strin
     .replace(/\+/g, '-')
     .replace(/\//g, '_')
     .replace(/=+$/, '')
-  const header = `Payment id="abc", realm="test", method="${method}", intent="${intent}", request="${request}"${expires}`
+  const header = `Payment id="${id}", realm="test", method="${method}", intent="${intent}", request="${request}"${expires}`
   return new Response(null, {
     status: 402,
     headers: { 'WWW-Authenticate': header },
@@ -379,6 +381,11 @@ function makeCombined402() {
   })
 }
 
+// Strict x402 encoding rejects unsupported accepts before the transport can filter them.
+function encodeRawPaymentRequiredHeader(value: unknown): string {
+  return Base64.fromString(JSON.stringify(value))
+}
+
 describe('Fetch.from: init passthrough (non-402)', () => {
   test('preserves init object identity while adding Accept-Payment', async () => {
     const receivedInits: (RequestInit | undefined)[] = []
@@ -780,6 +787,69 @@ describe('Fetch.from: 402 retry path', () => {
     expect(calls).toHaveLength(2)
   })
 
+  test('settles MCP-over-HTTP result metadata payment challenges at the fetch boundary', async () => {
+    const mcpChallenge = Challenge.from({
+      id: 'mcp-result-challenge',
+      intent: 'test',
+      method: 'test',
+      realm: 'test',
+      request: { amount: '1' },
+    })
+    const method = {
+      ...noopMethod,
+      createCredential: async ({ challenge }: { challenge: Challenge.Challenge }) =>
+        Credential.serialize({ challenge, payload: { source: 'mcp-result' } }),
+    }
+    const initialBody = JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'tools/call',
+      params: { name: 'paid-tool' },
+    })
+    let callCount = 0
+    const calls: { init: RequestInit | undefined }[] = []
+    const mockFetch: typeof globalThis.fetch = async (_input, init) => {
+      calls.push({ init })
+      callCount++
+      if (callCount === 1)
+        return Response.json({
+          jsonrpc: '2.0',
+          id: 1,
+          result: {
+            content: [{ type: 'text', text: 'Payment Required' }],
+            isError: true,
+            _meta: {
+              [Mcp.paymentRequiredMetaKey]: {
+                httpStatus: 402,
+                challenges: [mcpChallenge],
+              },
+            },
+          },
+        })
+
+      const body = JSON.parse(init?.body as string)
+      expect(new Headers(init?.headers).get('Authorization')).toBeNull()
+      expect(body.params['_meta'][Mcp.credentialMetaKey]).toMatchObject({
+        payload: { source: 'mcp-result' },
+      })
+      return Response.json({ ok: true })
+    }
+
+    const fetch = Fetch.from({
+      fetch: mockFetch,
+      methods: [method],
+    })
+
+    const response = await fetch('https://example.com/mcp', {
+      method: 'POST',
+      headers: { accept: 'application/json, text/event-stream' },
+      body: initialBody,
+    })
+
+    expect(response.status).toBe(200)
+    expect(calls).toHaveLength(2)
+  })
+
   test('settles MCP-over-HTTP when the JSON-RPC request body is carried by Request input', async () => {
     const mcpChallenge = Challenge.from({
       id: 'mcp-request-input-challenge',
@@ -1356,6 +1426,63 @@ describe('Fetch.from: 402 retry path', () => {
     expect(response.status).toBe(200)
   })
 
+  test('ignores unsupported x402 accepts when selecting a Payment auth challenge', async () => {
+    let callCount = 0
+    const createCredential = vi.fn(async () => 'tempo-credential')
+    const tempoChallenge = Challenge.from({
+      id: 'tempo',
+      realm: 'test',
+      method: 'tempo',
+      intent: 'charge',
+      request: { amount: '1' },
+    })
+    const mockFetch: typeof globalThis.fetch = async (_input, init) => {
+      callCount++
+      if (callCount === 1) {
+        return new Response(null, {
+          status: 402,
+          headers: {
+            [x402_Types.paymentRequiredHeader]: encodeRawPaymentRequiredHeader({
+              accepts: [
+                {
+                  amount: '10000',
+                  asset: 'USDC',
+                  maxTimeoutSeconds: 60,
+                  network: 'solana:mainnet',
+                  payTo: '9xQeWvG816bUx9EPjHmaT23yvVM2ZWdYqPxfowV5n2kg',
+                  scheme: 'exact',
+                },
+              ],
+              resource: { url: 'https://example.com/api' },
+              x402Version: 2,
+            }),
+            'WWW-Authenticate': Challenge.serialize(tempoChallenge),
+          },
+        })
+      }
+
+      expect(new Headers(init?.headers).get('Authorization')).toBe('tempo-credential')
+      return new Response('OK', { status: 200 })
+    }
+
+    const fetch = Fetch.from({
+      fetch: mockFetch,
+      methods: [
+        {
+          name: 'tempo',
+          intent: 'charge',
+          context: undefined,
+          createCredential,
+        },
+      ] as const,
+    })
+
+    const response = await fetch('https://example.com/api')
+
+    expect(response.status).toBe(200)
+    expect(createCredential).toHaveBeenCalledOnce()
+  })
+
   test('orderChallenges filters and sorts supported challenges before signing', async () => {
     let callCount = 0
     const pathUsd = Challenge.from({
@@ -1544,8 +1671,42 @@ describe('Fetch.from: 402 retry path', () => {
     )
   })
 
-  test('retries exactly once — does not loop on repeated 402', async () => {
+  test('creates a fresh credential for each incremental 402 challenge', async () => {
+    const createCredential = vi.fn(
+      async ({ challenge }: { challenge: Challenge.Challenge }) => `credential-${challenge.id}`,
+    )
+    const calls: { init: RequestInit | undefined }[] = []
+    let callCount = 0
+    const mockFetch: typeof globalThis.fetch = async (_input, init) => {
+      calls.push({ init })
+      callCount++
+      if (callCount === 1) return make402({ id: 'first' })
+      if (callCount === 2) return make402({ id: 'second' })
+      if (callCount === 3) return make402({ id: 'third' })
+      return new Response('OK', { status: 200 })
+    }
+
+    const fetch = Fetch.from({
+      fetch: mockFetch,
+      methods: [{ ...noopMethod, createCredential }],
+    })
+
+    const response = await fetch('https://example.com/api')
+
+    expect(response.status).toBe(200)
+    expect(createCredential.mock.calls.map((call) => call[0].challenge.id)).toEqual([
+      'first',
+      'second',
+      'third',
+    ])
+    expect(
+      calls.slice(1).map((call) => new Headers(call.init?.headers).get('Authorization')),
+    ).toEqual(['credential-first', 'credential-second', 'credential-third'])
+  })
+
+  test('caps repeated 402 retries at three', async () => {
     let callCount = 0
+    const createCredential = vi.fn(async () => 'credential')
     const mockFetch: typeof globalThis.fetch = async () => {
       callCount++
       return make402()
@@ -1553,11 +1714,32 @@ describe('Fetch.from: 402 retry path', () => {
 
     const fetch = Fetch.from({
       fetch: mockFetch,
-      methods: [noopMethod],
+      methods: [{ ...noopMethod, createCredential }],
+    })
+
+    const response = await fetch('https://example.com/api')
+    expect(callCount).toBe(4)
+    expect(createCredential).toHaveBeenCalledTimes(3)
+    expect(response.status).toBe(402)
+  })
+
+  test('respects configured retry cap', async () => {
+    let callCount = 0
+    const createCredential = vi.fn(async () => 'credential')
+    const mockFetch: typeof globalThis.fetch = async () => {
+      callCount++
+      return make402()
+    }
+
+    const fetch = Fetch.from({
+      fetch: mockFetch,
+      maxPaymentRetries: 1,
+      methods: [{ ...noopMethod, createCredential }],
     })
 
     const response = await fetch('https://example.com/api')
     expect(callCount).toBe(2)
+    expect(createCredential).toHaveBeenCalledOnce()
     expect(response.status).toBe(402)
   })
 })

package/src/client/internal/Fetch.ts

@@ -11,6 +11,7 @@ import * as Transport from '../Transport.js'
 // even across multiple module instances/bundles. This lets restore() avoid clobbering
 // an unrelated fetch installed by user code or another library.
 const MPPX_FETCH_WRAPPER = Symbol.for('mppx.fetch.wrapper')
+const defaultMaxPaymentRetries = 3
 
 type WrappedFetch = typeof globalThis.fetch & {
   [MPPX_FETCH_WRAPPER]?: typeof globalThis.fetch
@@ -161,6 +162,7 @@ export function from<const methods extends readonly Method.AnyClient[]>(
     acceptPayment,
     acceptPaymentPolicy = 'always',
     fetch = globalThis.fetch,
+    maxPaymentRetries = defaultMaxPaymentRetries,
     methods,
     onChallenge,
     orderChallenges,
@@ -185,7 +187,7 @@ export function from<const methods extends readonly Method.AnyClient[]>(
       hasExplicitAcceptPayment,
       acceptPaymentPolicy,
     )
-    const response = await baseFetch(cloneRequestInput(initialRequest.input), initialRequest.init)
+    let response = await baseFetch(cloneRequestInput(initialRequest.input), initialRequest.init)
     const transportRequest = withCapturedBody(initialRequest.init, await capturedBody)
 
     if (!(await transport.isPaymentRequired(response, transportRequest as never))) return response
@@ -203,91 +205,96 @@ export function from<const methods extends readonly Method.AnyClient[]>(
     let mi: methods[number] | undefined
 
     try {
-      challenges = transport.getChallenges
-        ? await transport.getChallenges(response, transportRequest as never)
-        : [await transport.getChallenge(response, transportRequest as never)]
-
-      const candidates = AcceptPayment.selectChallengeCandidates(
-        challenges,
-        methods,
-        paymentPreferences.entries,
-      )
-      const orderedCandidates = await resolveChallengeOrder(
-        candidates,
-        (requestOrderChallenges as AcceptPayment.OrderChallenges<methods> | undefined) ??
-          orderChallenges,
-      )
-      const selected = orderedCandidates[0]
-      if (!selected)
-        throw new Error(
-          `No method found for challenges: ${challenges.map((c) => `${c.method}.${c.intent}`).join(', ')}. Available: ${methods.map((m) => `${m.name}.${m.intent}`).join(', ')}`,
-        )
-
-      const selectedChallenge = selected.challenge
-      challenge = selectedChallenge
-      mi = selected.method
-      if (challenge.expires) Expires.assert(challenge.expires, challenge.id)
+      for (let retry = 0; retry < maxPaymentRetries; retry++) {
+        challenges = transport.getChallenges
+          ? await transport.getChallenges(response, transportRequest as never)
+          : [await transport.getChallenge(response, transportRequest as never)]
 
-      const createCredential = memoizeCreateCredential((overrideContext?: AnyContextFor<methods>) =>
-        resolveCredential(selectedChallenge, selected.method, overrideContext ?? context),
-      )
-      const eventCredential = await events.emit(
-        'challenge.received',
-        createChallengeReceivedPayload({
-          challenge: selectedChallenge,
+        const candidates = AcceptPayment.selectChallengeCandidates(
           challenges,
-          createCredential,
-          init,
-          input,
-          method: selected.method,
-          response,
-        }),
-      )
-      const onChallengeCredential =
-        eventCredential ??
-        (onChallenge
-          ? await onChallenge(challenge, {
-              createCredential,
-            })
-          : undefined)
-      const credential = onChallengeCredential ?? (await createCredential())
-      validateCredentialHeaderValue(credential)
-      await events.emit(
-        'credential.created',
-        createCredentialCreatedPayload({
-          challenge: selectedChallenge,
-          credential,
-          init,
-          input,
-          method: selected.method,
-          response,
-        }),
-      )
-
-      const paymentResponse = await baseFetch(
-        resolvePaymentRetryInput(response, initialRequest.input, initialRequest.input),
-        transport.setCredential(
-          {
-            ...fetchInit,
-            headers: initialRequest.headers,
-          },
-          credential,
-          { challenge: selectedChallenge },
-        ),
-      )
-      if (paymentResponse.ok)
+          methods,
+          paymentPreferences.entries,
+        )
+        const orderedCandidates = await resolveChallengeOrder(
+          candidates,
+          (requestOrderChallenges as AcceptPayment.OrderChallenges<methods> | undefined) ??
+            orderChallenges,
+        )
+        const selected = orderedCandidates[0]
+        if (!selected)
+          throw new Error(
+            `No method found for challenges: ${challenges.map((c) => `${c.method}.${c.intent}`).join(', ')}. Available: ${methods.map((m) => `${m.name}.${m.intent}`).join(', ')}`,
+          )
+
+        const selectedChallenge = selected.challenge
+        challenge = selectedChallenge
+        mi = selected.method
+        if (challenge.expires) Expires.assert(challenge.expires, challenge.id)
+
+        const createCredential = memoizeCreateCredential(
+          (overrideContext?: AnyContextFor<methods>) =>
+            resolveCredential(selectedChallenge, selected.method, overrideContext ?? context),
+        )
+        const eventCredential = await events.emit(
+          'challenge.received',
+          createChallengeReceivedPayload({
+            challenge: selectedChallenge,
+            challenges,
+            createCredential,
+            init,
+            input,
+            method: selected.method,
+            response,
+          }),
+        )
+        const onChallengeCredential =
+          eventCredential ??
+          (onChallenge
+            ? await onChallenge(challenge, {
+                createCredential,
+              })
+            : undefined)
+        const credential = onChallengeCredential ?? (await createCredential())
+        validateCredentialHeaderValue(credential)
         await events.emit(
-          'payment.response',
-          createPaymentResponsePayload({
+          'credential.created',
+          createCredentialCreatedPayload({
             challenge: selectedChallenge,
             credential,
             init,
             input,
             method: selected.method,
-            response: paymentResponse,
+            response,
           }),
         )
-      return paymentResponse
+
+        response = await baseFetch(
+          resolvePaymentRetryInput(response, initialRequest.input, initialRequest.input),
+          transport.setCredential(
+            {
+              ...fetchInit,
+              headers: initialRequest.headers,
+            },
+            credential,
+            { challenge: selectedChallenge },
+          ),
+        )
+        if (response.ok)
+          await events.emit(
+            'payment.response',
+            createPaymentResponsePayload({
+              challenge: selectedChallenge,
+              credential,
+              init,
+              input,
+              method: selected.method,
+              response,
+            }),
+          )
+        if (!(await transport.isPaymentRequired(response, transportRequest as never)))
+          return response
+      }
+      return response
     } catch (error) {
       await events.emit(
         'payment.failed',
@@ -335,6 +342,8 @@ export declare namespace from {
     fetch?: typeof globalThis.fetch
     /** Advanced shared event dispatcher. `challenge.received` handlers run before `onChallenge`; the first non-empty credential returned by a handler skips `onChallenge`. */
     eventDispatcher?: ClientEventDispatcher<methods, any> | undefined
+    /** Maximum number of payment challenge retries after the initial response. @default 3 */
+    maxPaymentRetries?: number | undefined
     /** Array of methods to use. */
     methods: methods
     /** Called when a 402 challenge is received and no event handler supplies a credential. */

package/src/client/internal/protocols/Mcp.ts

@@ -21,6 +21,11 @@ function jsonRpcRequestId(body: unknown): number | string | undefined {
 
 const responseCache = new WeakMap<Response, Promise<Mcp.Response | undefined>>()
 
+type CorePaymentRequiredData = NonNullable<Mcp.ErrorObject['data']>
+
+export type PaymentRequiredData = Pick<CorePaymentRequiredData, 'challenges'> &
+  Partial<Pick<CorePaymentRequiredData, 'httpStatus' | 'problem'>>
+
 function mcpHttpRequestId(request?: RequestInit): number | string | undefined {
   const id = jsonRpcRequestId(request?.body)
   if (id === undefined) return undefined
@@ -55,26 +60,45 @@ function parseMessage(value: unknown): Mcp.Response | undefined {
     : undefined
 }
 
-function paymentRequiredChallenges(
-  message: Mcp.Response | undefined,
-  id: number | string,
-): Challenge.Challenge[] {
-  if (
-    !message ||
-    message.id !== id ||
-    !('error' in message) ||
-    message.error?.code !== Mcp.paymentRequiredCode
-  )
-    return []
-  const challenges = message.error?.data?.challenges
-  if (!Array.isArray(challenges) || challenges.length === 0) return []
+function paymentRequiredDataFromValue(data: unknown): PaymentRequiredData | undefined {
+  if (!data || typeof data !== 'object') return undefined
+  const challenges = (data as { challenges?: unknown } | undefined)?.challenges
+  if (!Array.isArray(challenges) || challenges.length === 0) return undefined
   const parsed: Challenge.Challenge[] = []
   for (const challenge of challenges) {
     const result = Challenge.Schema.safeParse(challenge)
-    if (!result.success) return []
+    if (!result.success) return undefined
     parsed.push(result.data as Challenge.Challenge)
   }
-  return parsed
+  const { httpStatus, problem } = data as {
+    httpStatus?: unknown
+    problem?: PaymentRequiredData['problem']
+  }
+  return {
+    challenges: parsed,
+    ...(typeof httpStatus === 'number' ? { httpStatus } : {}),
+    ...(problem !== undefined ? { problem } : {}),
+  }
+}
+
+/** Extracts validated payment-required data from MCP errors or tool result metadata. */
+export function paymentRequiredData(
+  message: Mcp.Response | undefined,
+): PaymentRequiredData | undefined {
+  if (!message) return undefined
+  if ('error' in message) {
+    if (message.error?.code !== Mcp.paymentRequiredCode) return undefined
+    return paymentRequiredDataFromValue(message.error.data)
+  }
+  return paymentRequiredDataFromValue(message.result?._meta?.[Mcp.paymentRequiredMetaKey])
+}
+
+function paymentRequiredChallenges(
+  message: Mcp.Response | undefined,
+  id: number | string,
+): Challenge.Challenge[] {
+  if (!message || message.id !== id) return []
+  return paymentRequiredData(message)?.challenges ?? []
 }
 
 async function parseSseJsonRpcResponse(response: Response): Promise<Mcp.Response | undefined> {

package/src/client/internal/protocols/X402.ts

@@ -16,11 +16,15 @@ export function x402(): Protocol {
       if (response.status !== paymentRequiredStatus) return []
       const header = response.headers.get(x402_Types.paymentRequiredHeader)
       if (!header) return []
-      const paymentRequired = x402_Header.decodePaymentRequired(header)
+      const paymentRequired = x402_Header.decodePaymentRequiredEnvelope(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(
+      return paymentRequired.accepts.flatMap((rawAccepted, index) => {
+        const parsed = x402_Types.PaymentRequirementsSchema.safeParse(rawAccepted)
+        if (!parsed.success) return []
+
+        const accepted = parsed.data
+        return x402_ChallengeBrand.mark(
           Challenge.from({
             id: `${x402_Types.syntheticChallengeIdPrefix}${index}`,
             intent: x402_Types.exactIntent,
@@ -32,8 +36,8 @@ export function x402(): Protocol {
               resource: paymentRequired.resource,
             },
           }),
-        ),
-      )
+        )
+      })
     },
     setCredential(request, credential) {
       return setCredentialHeader(request, x402_Types.paymentSignatureHeader, credential)

package/src/mcp/client/McpClient.integration.test.ts

@@ -33,6 +33,17 @@ const isLocalnet = tempoNetwork === 'localnet'
 
 let escrowContract: Address
 
+// TODO: Remove once the minimum viem version is >=2.54.0, which uses client-first Tempo call builders.
+function tokenGetBalanceCall(parameters: { account: Address; token: Address }) {
+  const call = Actions.token.getBalance.call as unknown as {
+    length: number
+    (parameters: { account: Address; token: Address }): unknown
+    (client: unknown, parameters: { account: Address; token: Address }): unknown
+  }
+  if (call.length >= 2) return call(testClient, parameters)
+  return call(parameters)
+}
+
 beforeAll(async () => {
   escrowContract = await deployEscrow()
   await fundAccount({ address: accounts[4].address, token: Addresses.pathUsd })
@@ -621,7 +632,7 @@ async function getPaymentRequiredError(
 async function getTokenBalance(account: Address): Promise<bigint> {
   return readContract(
     testClient,
-    Actions.token.getBalance.call({ account, token: asset }) as never,
+    tokenGetBalanceCall({ account, token: asset }) as never,
   ) as Promise<bigint>
 }
 

package/src/server/Mppx.test.ts

@@ -87,6 +87,7 @@ describe('request handler', () => {
       {
         "challengeId": "[challengeId]",
         "detail": "Payment is required.",
+        "hint": "Use a supported wallet to pay for this resource using one of the supported payment methods returned in the WWW-Authenticate header. See https://mpp.dev/tools/wallet.md",
         "instance": "[instance]",
         "status": 402,
         "title": "Payment Required",
@@ -119,6 +120,7 @@ describe('request handler', () => {
       {
         "challengeId": "[challengeId]",
         "detail": "Credential is malformed: Invalid base64url or JSON..",
+        "hint": "Use a supported wallet to construct valid credentials for one of the supported payment methods returned in the WWW-Authenticate header. See https://mpp.dev/tools/wallet.md",
         "instance": "[instance]",
         "status": 402,
         "title": "Malformed Credential",
@@ -806,6 +808,7 @@ describe('request handler (node)', () => {
       {
         "challengeId": "[challengeId]",
         "detail": "Payment is required.",
+        "hint": "Use a supported wallet to pay for this resource using one of the supported payment methods returned in the WWW-Authenticate header. See https://mpp.dev/tools/wallet.md",
         "instance": "[instance]",
         "status": 402,
         "title": "Payment Required",