mppx 0.7.0 → 0.8.0

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

@@ -0,0 +1,220 @@
+import { Challenge, Mcp } from 'mppx'
+import { Methods } from 'mppx/tempo'
+import { describe, expect, test } from 'vp/test'
+
+import { mcp } from './Mcp.js'
+
+const challenge = Challenge.fromMethod(Methods.charge, {
+  realm: 'api.example.com',
+  secretKey: 'test-secret-key',
+  expires: '2025-01-01T00:00:00.000Z',
+  request: {
+    amount: '0.001',
+    currency: '0x20c0000000000000000000000000000000000001',
+    decimals: 6,
+    recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
+  },
+})
+
+const paymentRequired = {
+  jsonrpc: '2.0',
+  id: 1,
+  error: {
+    code: Mcp.paymentRequiredCode,
+    message: 'Payment Required',
+    data: { challenges: [challenge] },
+  },
+}
+
+const request = (overrides: Partial<RequestInit> = {}) =>
+  ({
+    headers: { accept: 'application/json, text/event-stream' },
+    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: {} }),
+    ...overrides,
+  }) satisfies RequestInit
+
+const jsonResponse = (body: unknown, contentType = 'application/json') =>
+  new Response(typeof body === 'string' ? body : JSON.stringify(body), {
+    headers: { 'content-type': contentType },
+  })
+
+const sseResponse = (body: string) =>
+  new Response(body, { headers: { 'content-type': 'text/event-stream' } })
+
+const sseEvent = (data: unknown, event = 'message') =>
+  `${event ? `event: ${event}\n` : ''}data: ${
+    typeof data === 'string' ? data : JSON.stringify(data)
+  }\n\n`
+
+async function getChallengeIds(response: Response, requestInit = request()) {
+  return (await mcp().getChallenges(response, requestInit)).map((entry) => entry.id)
+}
+
+describe('mcp HTTP protocol', () => {
+  test('extracts payment challenges from JSON-RPC error JSON', async () => {
+    expect(await getChallengeIds(jsonResponse(paymentRequired))).toEqual([challenge.id])
+  })
+
+  test('extracts all valid payment challenges', async () => {
+    const alternate = { ...challenge, id: 'alternate' }
+    const response = jsonResponse({
+      ...paymentRequired,
+      error: {
+        ...paymentRequired.error,
+        data: { challenges: [challenge, alternate] },
+      },
+    })
+
+    expect(await getChallengeIds(response)).toEqual([challenge.id, alternate.id])
+  })
+
+  test('parses JSON content types case-insensitively', async () => {
+    const response = jsonResponse(paymentRequired, 'Application/JSON; charset=utf-8')
+
+    expect(await getChallengeIds(response)).toEqual([challenge.id])
+  })
+
+  test.each([
+    { body: '[', name: 'invalid JSON' },
+    { body: [paymentRequired], name: 'JSON-RPC batch' },
+    {
+      body: { jsonrpc: '2.0', method: 'notifications/progress', params: {} },
+      name: 'notification',
+    },
+    { body: { jsonrpc: '2.0', id: 1, method: 'tools/call', params: {} }, name: 'request' },
+    { body: { ...paymentRequired, jsonrpc: '2.1' }, name: 'wrong JSON-RPC version' },
+    { body: { ...paymentRequired, id: null }, name: 'null id' },
+    { body: { ...paymentRequired, id: 2 }, name: 'different id' },
+    { body: { ...paymentRequired, result: {} }, name: 'result and error together' },
+    { body: { jsonrpc: '2.0', id: 1, result: {} }, name: 'successful result' },
+    {
+      body: {
+        jsonrpc: '2.0',
+        id: 1,
+        error: { code: -32600, message: 'Invalid Request' },
+      },
+      name: 'non-payment error',
+    },
+    {
+      body: {
+        jsonrpc: '2.0',
+        id: 1,
+        error: { code: `${Mcp.paymentRequiredCode}`, message: 'Payment Required' },
+      },
+      name: 'string error code',
+    },
+    {
+      body: {
+        jsonrpc: '2.0',
+        id: 1,
+        error: { code: Mcp.paymentRequiredCode, message: 402 },
+      },
+      name: 'non-string error message',
+    },
+  ])('ignores $name message shapes', async ({ body }) => {
+    expect(await getChallengeIds(jsonResponse(body))).toEqual([])
+  })
+
+  test.each([
+    { challenges: undefined, name: 'missing challenges' },
+    { challenges: [], name: 'empty challenges' },
+    { challenges: challenge, name: 'non-array challenges' },
+    { challenges: [{ ...challenge, realm: undefined }], name: 'invalid challenge' },
+    {
+      challenges: [challenge, { ...challenge, realm: undefined }],
+      name: 'partially invalid challenges',
+    },
+  ])('ignores $name', async ({ challenges }) => {
+    const response = jsonResponse({
+      ...paymentRequired,
+      error: {
+        ...paymentRequired.error,
+        data: challenges === undefined ? undefined : { challenges },
+      },
+    })
+
+    expect(await getChallengeIds(response)).toEqual([])
+  })
+
+  test('matches string request and response ids without coercion', async () => {
+    const stringRequest = request({
+      body: JSON.stringify({ jsonrpc: '2.0', id: '1', method: 'tools/call', params: {} }),
+    })
+    const response = jsonResponse({ ...paymentRequired, id: '1' })
+
+    expect(await getChallengeIds(response, stringRequest)).toEqual([challenge.id])
+    expect(await getChallengeIds(jsonResponse(paymentRequired), stringRequest)).toEqual([])
+  })
+
+  test.each([
+    {
+      body: '{',
+      headers: { accept: 'application/json, text/event-stream' },
+      name: 'malformed request JSON',
+    },
+    {
+      body: JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }),
+      headers: { accept: 'application/json, text/event-stream' },
+      name: 'request without id',
+    },
+    {
+      body: JSON.stringify({ jsonrpc: '2.0', id: 1, params: {} }),
+      headers: { accept: 'application/json, text/event-stream' },
+      name: 'request without method',
+    },
+    {
+      body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: {} }),
+      headers: { accept: 'application/json' },
+      name: 'request without Streamable HTTP accept',
+    },
+  ])('does not inspect responses for $name', async ({ body, headers }) => {
+    expect(
+      await getChallengeIds(jsonResponse(paymentRequired), request({ body, headers })),
+    ).toEqual([])
+  })
+
+  test('accepts the mcp-method header as MCP request provenance', async () => {
+    const requestInit = request({
+      headers: { 'mcp-method': 'tools/call' },
+    })
+
+    expect(await getChallengeIds(jsonResponse(paymentRequired), requestInit)).toEqual([
+      challenge.id,
+    ])
+  })
+
+  test('does not inspect native HTTP 402 responses', async () => {
+    expect(await getChallengeIds(jsonResponse(paymentRequired), request({}))).toEqual([
+      challenge.id,
+    ])
+    expect(
+      await getChallengeIds(
+        new Response(JSON.stringify(paymentRequired), {
+          status: 402,
+          headers: { 'content-type': 'application/json' },
+        }),
+      ),
+    ).toEqual([])
+  })
+
+  test.each([
+    { body: sseEvent(paymentRequired), name: 'message event' },
+    { body: sseEvent(paymentRequired, ''), name: 'event without explicit type' },
+    { body: `: keepalive\n\n${sseEvent(paymentRequired)}`, name: 'message after SSE comment' },
+  ])('extracts payment challenges from SSE $name', async ({ body }) => {
+    expect(await getChallengeIds(sseResponse(body))).toEqual([challenge.id])
+  })
+
+  test.each([
+    { body: sseEvent('{'), name: 'invalid JSON' },
+    { body: sseEvent({ jsonrpc: '2.0', method: 'notifications/progress' }), name: 'notification' },
+    { body: sseEvent(paymentRequired, 'progress'), name: 'non-message event' },
+    {
+      body:
+        sseEvent({ jsonrpc: '2.0', method: 'notifications/progress' }) + sseEvent(paymentRequired),
+      name: 'payment challenge after first data event',
+    },
+  ])('ignores SSE $name', async ({ body }) => {
+    expect(await getChallengeIds(sseResponse(body))).toEqual([])
+  })
+})

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

@@ -0,0 +1,162 @@
+import { createParser } from 'eventsource-parser'
+
+import * as Challenge from '../../../Challenge.js'
+import * as Credential from '../../../Credential.js'
+import * as Mcp from '../../../Mcp.js'
+import type { Protocol } from './Protocol.js'
+import { paymentRequiredStatus } from './Shared.js'
+
+/** Returns the JSON-RPC request id — only requests can receive a `-32042` response. */
+function jsonRpcRequestId(body: unknown): number | string | undefined {
+  if (typeof body !== 'string') return undefined
+  try {
+    const message = JSON.parse(body)
+    const id = message?.id
+    if (message?.jsonrpc !== '2.0' || typeof message?.method !== 'string') return undefined
+    return typeof id === 'string' || typeof id === 'number' ? id : undefined
+  } catch {
+    return undefined
+  }
+}
+
+const responseCache = new WeakMap<Response, Promise<Mcp.Response | undefined>>()
+
+function mcpHttpRequestId(request?: RequestInit): number | string | undefined {
+  const id = jsonRpcRequestId(request?.body)
+  if (id === undefined) return undefined
+  const headers = new Headers(request?.headers)
+  if (headers.has('mcp-method')) return id
+  const accept = headers.get('accept')?.toLowerCase() ?? ''
+  return accept.includes('application/json') && accept.includes('text/event-stream')
+    ? id
+    : undefined
+}
+
+function parseMessage(value: unknown): Mcp.Response | undefined {
+  if (!value || typeof value !== 'object') return undefined
+  const message = value as {
+    error?: { code?: unknown; message?: unknown }
+    id?: unknown
+    jsonrpc?: unknown
+    result?: unknown
+  }
+  const id = message.id
+  if (message.jsonrpc !== '2.0') return undefined
+  if (id !== undefined && typeof id !== 'string' && typeof id !== 'number') return undefined
+  const hasError = 'error' in message
+  const hasResult = 'result' in message
+  if (hasError === hasResult) return undefined
+  if (hasError)
+    return Number.isInteger(message.error?.code) && typeof message.error?.message === 'string'
+      ? (value as Mcp.Response)
+      : undefined
+  return id !== undefined && typeof message.result === 'object'
+    ? (value as Mcp.Response)
+    : 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 []
+  const parsed: Challenge.Challenge[] = []
+  for (const challenge of challenges) {
+    const result = Challenge.Schema.safeParse(challenge)
+    if (!result.success) return []
+    parsed.push(result.data as Challenge.Challenge)
+  }
+  return parsed
+}
+
+async function parseSseJsonRpcResponse(response: Response): Promise<Mcp.Response | undefined> {
+  const reader = response.clone().body?.getReader()
+  if (!reader) return undefined
+
+  const decoder = new TextDecoder()
+  let dataEventSeen = false
+  let message: Mcp.Response | undefined
+  const parser = createParser({
+    onEvent(event) {
+      if (dataEventSeen || !event.data) return
+      dataEventSeen = true
+      if (event.event && event.event !== 'message') return
+      try {
+        message = parseMessage(JSON.parse(event.data))
+      } catch {}
+    },
+  })
+
+  try {
+    for (;;) {
+      if (dataEventSeen) return message
+      const { done, value } = await reader.read()
+      if (done) {
+        parser.feed(decoder.decode())
+        parser.reset({ consume: true })
+        return message
+      }
+      parser.feed(decoder.decode(value, { stream: true }))
+    }
+  } finally {
+    void reader.cancel().catch(() => {})
+  }
+}
+
+/** Reads a cloned HTTP body into the first JSON-RPC response message, if any. */
+function parseJsonRpcResponse(response: Response): Promise<Mcp.Response | undefined> {
+  const cached = responseCache.get(response)
+  if (cached) return cached
+  const promise = (async (): Promise<Mcp.Response | undefined> => {
+    const contentType = response.headers.get('content-type')?.toLowerCase() ?? ''
+    if (contentType.includes('application/json'))
+      return response
+        .clone()
+        .json()
+        .then(parseMessage)
+        .catch(() => undefined)
+    if (contentType.includes('text/event-stream')) return parseSseJsonRpcResponse(response)
+    return undefined
+  })()
+  responseCache.set(response, promise)
+  return promise
+}
+
+/**
+ * MCP-over-HTTP — remote MCP rides Streamable HTTP, so its challenge is a JSON-RPC `-32042` error
+ * in a normal 200 body (often `text/event-stream`), and the credential rides back in `_meta`.
+ */
+export function mcp(): Protocol {
+  return {
+    getChallenges(response, request) {
+      // The 402 schemes own status 402; MCP challenges arrive in a normal 200 body.
+      const id = mcpHttpRequestId(request)
+      if (response.status === paymentRequiredStatus || id === undefined) return []
+      return parseJsonRpcResponse(response).then((message) =>
+        paymentRequiredChallenges(message, id),
+      )
+    },
+    setCredential(request, credential) {
+      const message = JSON.parse(request.body as string) as Mcp.Request
+      const parsed = Credential.deserialize(credential)
+      return {
+        ...request,
+        body: JSON.stringify({
+          ...message,
+          params: {
+            ...message.params,
+            ['_meta']: { ...message.params?.['_meta'], [Mcp.credentialMetaKey]: parsed },
+          },
+        }),
+      }
+    },
+  }
+}

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

@@ -0,0 +1,21 @@
+import * as Challenge from '../../../Challenge.js'
+import * as Constants from '../../../Constants.js'
+import type { Protocol } from './Protocol.js'
+import { paymentRequiredStatus, setCredentialHeader } from './Shared.js'
+
+/** MPP — the native HTTP scheme: a 402 carrying a `WWW-Authenticate` challenge, paid back in `Authorization`. */
+export function mpp(): Protocol {
+  return {
+    getChallenges(response) {
+      if (
+        response.status !== paymentRequiredStatus ||
+        !response.headers.has(Constants.Headers.wwwAuthenticate)
+      )
+        return []
+      return Challenge.fromResponseList(response)
+    },
+    setCredential(request, credential) {
+      return setCredentialHeader(request, Constants.Headers.authorization, credential)
+    },
+  }
+}

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

@@ -0,0 +1,10 @@
+import type * as Challenge from '../../../Challenge.js'
+import type { MaybePromise } from '../../../internal/types.js'
+
+/** One payment protocol over the `http` transport. */
+export type Protocol = {
+  /** This protocol's challenges from a response; `[]` when the response isn't its concern. */
+  getChallenges: (response: Response, request?: RequestInit) => MaybePromise<Challenge.Challenge[]>
+  /** Attaches this protocol's credential to a retry request. */
+  setCredential: (request: RequestInit, credential: string) => RequestInit
+}

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

@@ -0,0 +1,25 @@
+import * as Constants from '../../../Constants.js'
+import * as x402_Types from '../../../x402/Types.js'
+
+/** HTTP status that signals a native payment challenge. */
+export const paymentRequiredStatus = 402
+
+/** Credential headers purged before a fresh credential is attached. */
+const credentialHeaders = [
+  Constants.Headers.authorization,
+  x402_Types.paymentRequiredHeader,
+  x402_Types.paymentResponseHeader,
+  x402_Types.paymentSignatureHeader,
+]
+
+/** Attaches `credential` under `header`, clearing any stale credential headers first. */
+export function setCredentialHeader(
+  request: RequestInit,
+  header: string,
+  credential: string,
+): RequestInit {
+  const headers = new Headers(request.headers)
+  for (const stale of credentialHeaders) headers.delete(stale)
+  headers.set(header, credential)
+  return { ...request, headers }
+}

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

@@ -0,0 +1,42 @@
+import * as Challenge from '../../../Challenge.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'
+import type { Protocol } from './Protocol.js'
+import { paymentRequiredStatus, setCredentialHeader } from './Shared.js'
+
+/**
+ * x402 — a 402 carrying a `PAYMENT-REQUIRED` header, paid back in `PAYMENT-SIGNATURE`. Synthesized
+ * challenges are branded for `evm/client/Charge.ts`, keeping them distinct from native `evm`
+ * charges with the same method/intent.
+ */
+export function x402(): Protocol {
+  return {
+    getChallenges(response) {
+      if (response.status !== paymentRequiredStatus) return []
+      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,
+            },
+          }),
+        ),
+      )
+    },
+    setCredential(request, credential) {
+      return setCredentialHeader(request, x402_Types.paymentSignatureHeader, credential)
+    },
+  }
+}

package/src/discovery/OpenApi.test.ts

@@ -73,7 +73,7 @@ function createMppx<const methods extends Mppx.Methods>(methods: methods) {
   return Mppx.create({
     methods,
     realm: 'test-realm',
-    secretKey: 'test-secret',
+    secretKey: 'test-secret-key-test-secret-key-32',
   })
 }
 

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

@@ -14,7 +14,7 @@ import { Mppx as ServerMppx } from '../server/index.js'
 
 const account = {} as Account
 const recipient = '0x209693Bc6afc0C5328bA36FaF03C514EF312287C'
-const secretKey = 'test-secret'
+const secretKey = 'test-secret-key-test-secret-key-32'
 const settle = async () => ({
   reference: `0x${'1'.repeat(64)}` as `0x${string}`,
 })

package/src/evm/client/index.ts

@@ -1,4 +1,5 @@
 export * as assets from '../Assets.js'
+/** @deprecated Use `chains` instead. */
 export * as Chains from '../Chains.js'
 export * as chains from '../Chains.js'
 export { charge } from './Charge.js'

package/src/evm/index.ts

@@ -1,4 +1,6 @@
+/** @deprecated Use `assets` instead. */
 export * as Assets from './Assets.js'
+/** @deprecated Use `chains` instead. */
 export * as Chains from './Chains.js'
 export * as Methods from './Methods.js'
 export * as Types from './Types.js'

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

@@ -45,7 +45,7 @@ describe('evm charge server', () => {
           },
         }),
       ],
-      secretKey: 'test-secret',
+      secretKey: 'test-secret-key-test-secret-key-32',
     })
     const client = ClientMppx.create({
       methods: [

package/src/evm/server/index.ts

@@ -1,4 +1,5 @@
 export * as assets from '../Assets.js'
+/** @deprecated Use `chains` instead. */
 export * as Chains from '../Chains.js'
 export * as chains from '../Chains.js'
 export { charge } from './Charge.js'

package/src/{mcp-sdk → mcp}/client/McpClient.integration.test.ts

@@ -25,7 +25,7 @@ import * as McpServer_transport from '../server/Transport.js'
 import * as McpClient from './McpClient.js'
 
 const realm = 'api.example.com'
-const secretKey = 'test-secret-key'
+const secretKey = 'test-secret-key-test-secret-key-32'
 const chargeAmountRaw = 1_000_000n
 const doubleSessionAmountRaw = chargeAmountRaw * 2n
 const topUpAmountRaw = chargeAmountRaw * 3n
@@ -410,6 +410,7 @@ describe.runIf(isLocalnet)('McpClient.wrap integration', () => {
 type WrappedClient = {
   callTool: (
     params: { name: string; arguments?: Record<string, unknown>; _meta?: Record<string, unknown> },
+    resultSchema?: undefined,
     options?: { context?: unknown; timeout?: number },
   ) => Promise<McpClient.CallToolResult>
 }
@@ -545,9 +546,14 @@ async function createHarness(options?: {
   const clientTransport = new StreamableHTTPClientTransport(new URL(`${httpServer.url}/mcp`))
   await sdkClient.connect(clientTransport as never)
 
-  const mcp = McpClient.wrap(sdkClient, {
-    methods: [chargeMethod, sessionMethod],
-  })
+  // Wrap a facade over the same session so `sdkClient` keeps raw (challenge-
+  // throwing) behavior for the credential-level scenarios below.
+  const mcp = McpClient.wrap(
+    { callTool: sdkClient.callTool.bind(sdkClient) as Client['callTool'] },
+    {
+      methods: [chargeMethod, sessionMethod],
+    },
+  )
 
   return {
     async close() {