mppx 0.6.27 → 0.6.29

package/src/server/Mppx.ts

@@ -11,6 +11,8 @@ import type { MaybePromise } from '../internal/types.js'
 import type * as Method from '../Method.js'
 import * as PaymentRequest from '../PaymentRequest.js'
 import type * as Receipt from '../Receipt.js'
+import * as x402_Header from '../x402/Header.js'
+import * as x402_Types from '../x402/Types.js'
 import * as z from '../zod.js'
 import * as Html from './internal/html/config.js'
 import { serviceWorker } from './internal/html/serviceWorker.gen.js'
@@ -790,7 +792,7 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
             : staticMeta
 
         // Extract credential once — getCredential may have side effects (e.g. SSE transports).
-        const [credential, credentialError] = (() => {
+        let [credential, credentialError] = (() => {
           try {
             const credential = transport.getCredential(input) as Credential.Credential | null
             return [credential ? hydrateCredentialMeta(credential) : null, undefined] as const
@@ -898,6 +900,21 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
         if ('response' in routeChallenge) return { challenge: routeChallenge.response, status: 402 }
         const { challenge, parsedRequest, request } = routeChallenge
 
+        if (credential && transport.bindCredential) {
+          try {
+            credential = hydrateCredentialMeta(
+              (await transport.bindCredential({
+                challenge,
+                credential,
+                input,
+              })) as Credential.Credential,
+            )
+          } catch (e) {
+            credential = null
+            credentialError = e as Error
+          }
+        }
+
         // Credential was provided but malformed
         if (credentialError) {
           const reason = getSafeCredentialReason(credentialError)
@@ -2004,6 +2021,29 @@ type ConfiguredHandler = ((input: Request) => Promise<MethodFn.Response<Transpor
   }
 }
 
+const paymentAuthChallengeHeader = 'WWW-Authenticate'
+
+const challengeHeaderMerges = [
+  {
+    name: paymentAuthChallengeHeader,
+    values: (context) =>
+      context.challengeEntries
+        .map((entry) =>
+          (entry.result.challenge as Response).headers.get(paymentAuthChallengeHeader),
+        )
+        .filter((value): value is string => value !== null),
+    merge: (values) => values,
+  },
+  {
+    name: x402_Types.paymentRequiredHeader,
+    values: (context) =>
+      context.negotiatedChallengeResponses
+        .map((response) => response.headers.get(x402_Types.paymentRequiredHeader))
+        .filter((value): value is string => value !== null),
+    merge: mergeX402PaymentRequiredHeaders,
+  },
+] satisfies readonly ChallengeHeaderMerge[]
+
 /** An entry for `compose()`: a method reference, handler function ref, or string key paired with its options. */
 type ComposeEntry<methods extends readonly Method.AnyServer[]> =
   | {
@@ -2172,7 +2212,7 @@ export function compose(
         if (result?.status !== 402) continue
 
         const response = result.challenge as Response
-        const wwwAuth = response.headers.get('WWW-Authenticate')
+        const wwwAuth = response.headers.get(paymentAuthChallengeHeader)
         if (!wwwAuth) continue
 
         entries.push({
@@ -2199,14 +2239,39 @@ export function compose(
       }
     })()
 
-    // Merge WWW-Authenticate headers from all 402 responses.
+    const challengeResponses = results.flatMap((result) =>
+      result.status === 402 ? [result.challenge as Response] : [],
+    )
+    const unnegotiatedX402Responses =
+      input.headers.has('Accept-Payment') || challengeEntries.length === 0
+        ? []
+        : challengeResponses.filter(
+            (response) =>
+              response.headers.has(x402_Types.paymentRequiredHeader) &&
+              !response.headers.has(paymentAuthChallengeHeader),
+          )
+    const negotiatedChallengeResponses =
+      challengeEntries.length > 0
+        ? [
+            ...challengeEntries.map((entry) => entry.result.challenge as Response),
+            ...unnegotiatedX402Responses,
+          ]
+        : challengeResponses
+
+    // Merge challenge headers from the negotiated 402 responses.
     const mergedHeaders = new Headers()
     mergedHeaders.set('Cache-Control', 'no-store')
 
-    for (const entry of challengeEntries) {
-      const response = entry.result.challenge as Response
-      const wwwAuth = response.headers.get('WWW-Authenticate')
-      if (wwwAuth) mergedHeaders.append('WWW-Authenticate', wwwAuth)
+    for (const header of challengeHeaderMerges) {
+      for (const value of header.merge(
+        header.values({
+          challengeEntries,
+          challengeResponses,
+          negotiatedChallengeResponses,
+        }),
+      )) {
+        mergedHeaders.append(header.name, value)
+      }
     }
 
     // Collect html-enabled handlers and their challenges
@@ -2257,11 +2322,15 @@ export function compose(
       }
     }
 
-    // Non-HTML fallback: use first handler's body
+    // Non-HTML fallback: prefer the first Payment-auth body, otherwise use
+    // the first transport-specific 402 body.
     let body: string | null = null
-    for (const entry of challengeEntries) {
+    const bodyResponses =
+      challengeEntries.length > 0
+        ? challengeEntries.map((entry) => entry.result.challenge as Response)
+        : challengeResponses
+    for (const response of bodyResponses) {
       if (!body) {
-        const response = entry.result.challenge as Response
         const contentType = response.headers.get('Content-Type')
         if (contentType) mergedHeaders.set('Content-Type', contentType)
         body = await response.text()
@@ -2276,6 +2345,50 @@ export function compose(
   }
 }
 
+type ChallengeHeaderMerge = {
+  name: string
+  values(context: {
+    challengeEntries: readonly {
+      handler: ConfiguredHandler
+      challenge: Challenge.Challenge
+      result: Extract<MethodFn.Response<Transport.Http>, { status: 402 }>
+    }[]
+    challengeResponses: readonly Response[]
+    negotiatedChallengeResponses: readonly Response[]
+  }): readonly string[]
+  merge(values: readonly string[]): readonly string[]
+}
+
+function mergeX402PaymentRequiredHeaders(values: readonly string[]): readonly string[] {
+  if (values.length === 0) return []
+  const [first, ...rest] = values.map((value) => x402_Header.decodePaymentRequired(value))
+  if (!first) throw new Error('Expected at least one x402 payment-required header.')
+  const incompatible = rest.some(
+    (value) =>
+      !isDeepStrictEqual(value.resource, first.resource) ||
+      !isDeepStrictEqual(value.extensions, first.extensions),
+  )
+  if (incompatible)
+    return [
+      x402_Header.encodePaymentRequired({
+        ...first,
+        error: [first.error, 'Cannot merge x402 payment requirements with different resources.']
+          .filter((value): value is string => value !== undefined && value.length > 0)
+          .join('; '),
+      }),
+    ]
+  const error = [first.error, ...rest.map((value) => value.error)]
+    .filter((value): value is string => value !== undefined && value.length > 0)
+    .join('; ')
+  return [
+    x402_Header.encodePaymentRequired({
+      ...first,
+      accepts: [first.accepts, ...rest.map((value) => value.accepts)].flat(),
+      ...(error ? { error } : {}),
+    }),
+  ]
+}
+
 /**
  * Wraps a payment handler to create a Node.js HTTP listener.
  *
@@ -2316,7 +2429,7 @@ export function toNodeListener(
       }
 
       const wrapped = result.withReceipt(new globalThis.Response()) as globalThis.Response
-      res.setHeader('Payment-Receipt', wrapped.headers.get('Payment-Receipt')!)
+      for (const [name, value] of wrapped.headers) res.setHeader(name, value)
     }
 
     return result

package/src/server/NodeListener.test.ts

@@ -1,7 +1,7 @@
 import { EventEmitter } from 'node:events'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 
-import { NodeListener, Request } from 'mppx/server'
+import { Mppx, NodeListener, Request } from 'mppx/server'
 import { afterEach, describe, expect, test } from 'vp/test'
 import * as Http from '~test/Http.js'
 
@@ -185,6 +185,33 @@ describe('toNodeListener', () => {
     expect(await response.json()).toEqual({ path: '/hello' })
   })
 
+  test('copies all receipt response headers for successful payment handlers', async () => {
+    const handler = Mppx.toNodeListener(async () => ({
+      status: 200,
+      withReceipt(response?: Response) {
+        if (!response) {
+          const error = new Error('withReceipt() requires a response argument')
+          error.name = 'MissingReceiptResponseError'
+          throw error
+        }
+        const headers = new Headers(response?.headers)
+        headers.set('Payment-Receipt', 'receipt')
+        headers.set('PAYMENT-RESPONSE', 'x402-response')
+        return new Response(response?.body, { headers })
+      },
+    }))
+
+    server = await Http.createServer(async (req, res) => {
+      await handler(req, res)
+      res.end('ok')
+    })
+
+    const response = await fetch(server.url)
+    expect(response.headers.get('Payment-Receipt')).toBe('receipt')
+    expect(response.headers.get('PAYMENT-RESPONSE')).toBe('x402-response')
+    expect(await response.text()).toBe('ok')
+  })
+
   test('forwards request method', async () => {
     const handler = Request.toNodeListener(async (request) => {
       return Response.json({ method: request.method })

package/src/server/Transport.test.ts

@@ -408,6 +408,7 @@ describe('http', () => {
       }).toMatchInlineSnapshot(`
         {
           "headers": {
+            "cache-control": "private",
             "content-type": "text/plain;charset=UTF-8",
             "payment-receipt": "eyJtZXRob2QiOiJ0ZW1wbyIsInJlZmVyZW5jZSI6IjB4dHhoYXNoIiwic3RhdHVzIjoic3VjY2VzcyIsInRpbWVzdGFtcCI6IjIwMjUtMDEtMDFUMDA6MDA6MDAuMDAwWiJ9",
           },
@@ -415,6 +416,24 @@ describe('http', () => {
         }
       `)
     })
+
+    test('preserves existing cache directives while marking receipts private', () => {
+      const transport = Transport.http()
+      const originalResponse = new Response('OK', {
+        status: 200,
+        headers: { 'Cache-Control': 'max-age=60' },
+      })
+
+      const response = transport.respondReceipt({
+        credential,
+        input: new Request('https://example.com'),
+        receipt,
+        response: originalResponse,
+        challengeId: challenge.id,
+      })
+
+      expect(response.headers.get('Cache-Control')).toBe('max-age=60, private')
+    })
   })
 })
 

package/src/server/Transport.ts

@@ -26,6 +26,18 @@ export type Transport<
   name: string
   /** Captures the transport request into an immutable verification snapshot. */
   captureRequest?: ((input: input) => MaybePromise<Method.CapturedRequest>) | undefined
+  /**
+   * Rebinds a transport-native credential to the route challenge after request
+   * normalization. Transports with non-Payment-auth wire formats can parse their
+   * payload early, then attach the canonical mppx challenge here.
+   */
+  bindCredential?:
+    | ((options: {
+        challenge: Challenge.Challenge
+        credential: Credential.Credential
+        input: input
+      }) => MaybePromise<Credential.Credential>)
+    | undefined
   /**
    * Extracts credential from the transport input.
    * Returns `null` if no credential was provided, or throws if malformed.
@@ -196,6 +208,7 @@ export function http(): Http {
 
     respondReceipt({ receipt, response }) {
       const headers = new Headers(response.headers)
+      headers.set('Cache-Control', withPrivateCacheControl(headers.get('Cache-Control')))
       headers.set('Payment-Receipt', Receipt.serialize(receipt))
       return new Response(response.body, {
         status: response.status,
@@ -206,6 +219,13 @@ export function http(): Http {
   })
 }
 
+function withPrivateCacheControl(value: string | null): string {
+  if (!value) return 'private'
+  const directives = value.split(',').map((directive) => directive.trim().toLowerCase())
+  if (directives.includes('private')) return value
+  return `${value}, private`
+}
+
 /**
  * MCP transport for server-side payment handling with raw JSON-RPC.
  *

package/src/server/index.ts

@@ -1,6 +1,6 @@
 export * as Expires from '../Expires.js'
 export * as Store from '../Store.js'
-export { stripe, tempo } from './Methods.js'
+export { evm, stripe, tempo } from './Methods.js'
 export * as Mppx from './Mppx.js'
 export * as NodeListener from './NodeListener.js'
 export * as Request from './Request.js'

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

@@ -4,13 +4,18 @@ import { afterEach, describe, expect, test, vi } from 'vp/test'
 import * as Http from '~test/Http.js'
 
 import type { StripeClient } from '../internal/types.js'
+import type { charge as StripeCharge } from './Charge.js'
 
 const realm = 'api.example.com'
 const secretKey = 'test-secret-key'
 
 let httpServer: Awaited<ReturnType<typeof Http.createServer>> | undefined
 
-afterEach(() => httpServer?.close())
+afterEach(() => {
+  httpServer?.close()
+  httpServer = undefined
+  vi.restoreAllMocks()
+})
 
 function createMockStripeClient(
   overrides?: Partial<{ status: string; id: string; throws: boolean }>,
@@ -126,6 +131,215 @@ describe('stripe.charge with client', () => {
     expect(params.metadata.mpp_is_mpp).toBe('true')
   })
 
+  test('behavior: applies Connect settlement parameters in client call', async () => {
+    const { client, create } = createMockStripeClient()
+
+    const server = Mppx.create({
+      methods: [
+        stripe.charge({
+          client,
+          connect({ request }) {
+            expect(request.amount).toBe('100')
+            return {
+              applicationFeeAmount: 12,
+              onBehalfOf: 'acct_merchant',
+              stripeAccount: 'acct_connected',
+              transferData: { amount: 88, destination: 'acct_destination' },
+              transferGroup: 'order_123',
+            }
+          },
+          networkId: 'internal',
+          paymentMethodTypes: ['card'],
+        }),
+      ],
+      realm,
+      secretKey,
+    })
+
+    const handle = server.charge({ amount: '1', currency: 'usd', decimals: 2 })
+    const firstResult = await handle(new Request('https://example.com'))
+    expect(firstResult.status).toBe(402)
+    if (firstResult.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(firstResult.challenge)
+    expect(challenge.request).not.toHaveProperty('connect')
+    expect(challenge.request.methodDetails).not.toHaveProperty('applicationFeeAmount')
+    expect(challenge.request.methodDetails).not.toHaveProperty('stripeAccount')
+
+    const credential = Credential.from({
+      challenge,
+      payload: { spt: 'spt_test_token' },
+    })
+
+    const result = await handle(
+      new Request('https://example.com', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+
+    expect(result.status).toBe(200)
+    const [params, options] = create.mock.calls[0]!
+    expect(params).toMatchObject({
+      application_fee_amount: 12,
+      on_behalf_of: 'acct_merchant',
+      transfer_data: { amount: 88, destination: 'acct_destination' },
+      transfer_group: 'order_123',
+    })
+    expect(options).toMatchObject({ stripeAccount: 'acct_connected' })
+  })
+
+  test('behavior: applies Connect settlement parameters in secretKey call', async () => {
+    const fetchMock = vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      new Response(JSON.stringify({ id: 'pi_fetch_123', status: 'succeeded' }), {
+        status: 200,
+      }),
+    )
+
+    const server = Mppx.create({
+      methods: [
+        stripe.charge({
+          connect: {
+            applicationFeeAmount: 12,
+            onBehalfOf: 'acct_merchant',
+            stripeAccount: 'acct_connected',
+            transferData: { amount: 88, destination: 'acct_destination' },
+            transferGroup: 'order_123',
+          },
+          networkId: 'internal',
+          paymentMethodTypes: ['card'],
+          secretKey,
+        }),
+      ],
+      realm,
+      secretKey,
+    })
+
+    const handle = server.charge({ amount: '1', currency: 'usd', decimals: 2 })
+    const firstResult = await handle(new Request('https://example.com'))
+    expect(firstResult.status).toBe(402)
+    if (firstResult.status !== 402) throw new Error()
+
+    const credential = Credential.from({
+      challenge: Challenge.fromResponse(firstResult.challenge),
+      payload: { spt: 'spt_test_token' },
+    })
+    const result = await handle(
+      new Request('https://example.com', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+
+    expect(result.status).toBe(200)
+    expect(fetchMock).toHaveBeenCalledOnce()
+    const [input, init] = fetchMock.mock.calls[0]!
+    expect(input).toBe('https://api.stripe.com/v1/payment_intents')
+    const headers = new Headers(init?.headers)
+    expect(headers.get('Stripe-Account')).toBe('acct_connected')
+    const body = init?.body as URLSearchParams
+    expect(body.get('application_fee_amount')).toBe('12')
+    expect(body.get('on_behalf_of')).toBe('acct_merchant')
+    expect(body.get('transfer_data[amount]')).toBe('88')
+    expect(body.get('transfer_data[destination]')).toBe('acct_destination')
+    expect(body.get('transfer_group')).toBe('order_123')
+  })
+
+  test('error: surfaces Connect PaymentIntent creation failures', async () => {
+    const { client } = createMockStripeClient({ throws: true })
+
+    const server = Mppx.create({
+      methods: [
+        stripe.charge({
+          client,
+          connect: { stripeAccount: 'acct_connected' },
+          networkId: 'internal',
+          paymentMethodTypes: ['card'],
+        }),
+      ],
+      realm,
+      secretKey,
+    })
+
+    httpServer = await Http.createServer(async (req, res) => {
+      const result = await Mppx.toNodeListener(
+        server.charge({ amount: '1', currency: 'usd', decimals: 2 }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('OK')
+    })
+
+    const response = await fetch(httpServer.url)
+    const challenge = Challenge.fromResponse(response)
+    const credential = Credential.from({
+      challenge,
+      payload: { spt: 'spt_test_token' },
+    })
+
+    const paidResponse = await fetch(httpServer.url, {
+      headers: { Authorization: Credential.serialize(credential) },
+    })
+    expect(paidResponse.status).toBe(402)
+    const body = (await paidResponse.json()) as { detail: string }
+    expect(body.detail).toContain('Stripe PaymentIntent failed')
+  })
+
+  const invalidConnectCases: readonly {
+    name: string
+    connect: StripeCharge.ConnectSettlement
+  }[] = [
+    { name: 'empty stripeAccount', connect: { stripeAccount: '' } },
+    { name: 'fee exceeds amount', connect: { applicationFeeAmount: 101 } },
+    { name: 'negative fee', connect: { applicationFeeAmount: -1 } },
+    {
+      name: 'empty transfer destination',
+      connect: { transferData: { destination: '' } },
+    },
+    {
+      name: 'missing transfer destination',
+      connect: { transferData: {} } as StripeCharge.ConnectSettlement,
+    },
+    {
+      name: 'transfer amount exceeds amount',
+      connect: { transferData: { amount: 101, destination: 'acct_destination' } },
+    },
+  ]
+
+  for (const { connect, name } of invalidConnectCases) {
+    test(`error: rejects invalid Connect settlement parameters (${name})`, async () => {
+      const { client, create } = createMockStripeClient()
+
+      const server = Mppx.create({
+        methods: [
+          stripe.charge({
+            client,
+            connect,
+            networkId: 'internal',
+            paymentMethodTypes: ['card'],
+          }),
+        ],
+        realm,
+        secretKey,
+      })
+
+      const handle = server.charge({ amount: '1', currency: 'usd', decimals: 2 })
+      const firstResult = await handle(new Request('https://example.com'))
+      expect(firstResult.status).toBe(402)
+      if (firstResult.status !== 402) throw new Error()
+
+      const credential = Credential.from({
+        challenge: Challenge.fromResponse(firstResult.challenge),
+        payload: { spt: 'spt_test_token' },
+      })
+      const result = await handle(
+        new Request('https://example.com', {
+          headers: { Authorization: Credential.serialize(credential) },
+        }),
+      )
+
+      expect(result.status).toBe(402)
+      expect(create).not.toHaveBeenCalled()
+    })
+  }
+
   test('behavior: rejects when client throws', async () => {
     const { client } = createMockStripeClient({ throws: true })