mppx 0.5.0 → 0.5.3

package/src/server/Mppx.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage, ServerResponse } from 'node:http'
+import { isDeepStrictEqual } from 'node:util'
 
 import * as Challenge from '../Challenge.js'
 import * as Credential from '../Credential.js'
@@ -300,10 +301,12 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
 
         // Credential was provided but malformed
         if (credentialError) {
+          const reason = getSafeCredentialReason(credentialError)
           const response = await transport.respondChallenge({
             challenge,
             input,
-            error: new Errors.MalformedCredentialError({ reason: credentialError.message }),
+            error: new Errors.MalformedCredentialError(reason ? { reason } : {}),
+            html: method.html,
           })
           return { challenge: response, status: 402 }
         }
@@ -314,6 +317,7 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
             challenge,
             input,
             error: new Errors.PaymentRequiredError({ description }),
+            html: method.html,
           })
           return { challenge: response, status: 402 }
         }
@@ -328,6 +332,7 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
               id: credential.challenge.id,
               reason: 'challenge was not issued by this server',
             }),
+            html: method.html,
           })
           return { challenge: response, status: 402 }
         }
@@ -339,13 +344,6 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
         // Note: we compare specific payment parameters rather than the full
         // request because the `request` hook may produce credential-dependent
         // output (e.g. `feePayer` differs between 402 and credential calls).
-        //
-        // Skip this check for topUp and voucher actions: the route's
-        // `request` hook may produce a different amount because these
-        // requests carry no application body (e.g. no model field for
-        // dynamic pricing). The credential echoes a challenge obtained
-        // from the original request which had the correct amount; the
-        // on-chain voucher signature is the real validation.
         {
           for (const field of ['method', 'intent', 'realm'] as const) {
             if (credential.challenge[field] !== challenge[field]) {
@@ -356,65 +354,26 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
                   id: credential.challenge.id,
                   reason: `credential ${field} does not match this route's requirements`,
                 }),
+                html: method.html,
               })
               return { challenge: response, status: 402 }
             }
           }
 
-          // Use safeParse (not raw payload) so only methods whose schema
-          // defines `action` can trigger the skip. Without this, a client
-          // could inject `action: 'topUp'` on a charge credential to bypass
-          // the amount check. Zod strips unknown keys, so charge payloads
-          // (which don't define `action`) will have it removed.
-          const parsed = method.schema.credential.payload.safeParse(credential.payload)
-          const action = parsed.success
-            ? (parsed.data as Record<string, unknown>)?.action
-            : undefined
-          if (action !== 'topUp' && action !== 'voucher') {
-            const routeReq = challenge.request as Record<string, unknown>
-            const echoedReq = credential.challenge.request as Record<string, unknown>
-            const routeDetails = (routeReq.methodDetails ?? {}) as Record<string, unknown>
-            const echoedDetails = (echoedReq.methodDetails ?? {}) as Record<string, unknown>
-            for (const field of ['amount', 'currency', 'recipient'] as const) {
-              const routeVal = routeReq[field] ?? routeDetails[field]
-              if (
-                routeVal !== undefined &&
-                String(routeVal) !== String(echoedReq[field] ?? echoedDetails[field])
-              ) {
-                const response = await transport.respondChallenge({
-                  challenge,
-                  input,
-                  error: new Errors.InvalidChallengeError({
-                    id: credential.challenge.id,
-                    reason: `credential ${field} does not match this route's requirements`,
-                  }),
-                })
-                return { challenge: response, status: 402 }
-              }
-            }
-
-            // Compare payment-relevant methodDetails fields (memo, splits).
-            // These are excluded from the top-level field check above but
-            // affect verification semantics — a credential issued for a
-            // no-splits route must not be accepted on a splits route.
-            for (const field of ['memo', 'splits'] as const) {
-              const routeVal = routeDetails[field]
-              const echoedVal = echoedDetails[field]
-              if (
-                routeVal !== undefined &&
-                JSON.stringify(routeVal) !== JSON.stringify(echoedVal)
-              ) {
-                const response = await transport.respondChallenge({
-                  challenge,
-                  input,
-                  error: new Errors.InvalidChallengeError({
-                    id: credential.challenge.id,
-                    reason: `credential ${field} does not match this route's requirements`,
-                  }),
-                })
-                return { challenge: response, status: 402 }
-              }
-            }
+          const mismatch = getRequestBindingMismatch(
+            challenge.request as Record<string, unknown>,
+            credential.challenge.request as Record<string, unknown>,
+          )
+          if (mismatch) {
+            const response = await transport.respondChallenge({
+              challenge,
+              input,
+              error: new Errors.InvalidChallengeError({
+                id: credential.challenge.id,
+                reason: `credential ${mismatch} does not match this route's requirements`,
+              }),
+            })
+            return { challenge: response, status: 402 }
           }
         }
 
@@ -432,11 +391,11 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
         // Validate payload structure against method schema
         try {
           method.schema.credential.payload.parse(credential.payload)
-        } catch (e) {
+        } catch {
           const response = await transport.respondChallenge({
             challenge,
             input,
-            error: new Errors.InvalidPayloadError({ reason: (e as Error).message }),
+            error: new Errors.InvalidPayloadError(),
           })
           return { challenge: response, status: 402 }
         }
@@ -447,10 +406,9 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
         try {
           receiptData = await verify({ credential, request } as never)
         } catch (e) {
-          const error =
-            e instanceof Errors.PaymentError
-              ? e
-              : new Errors.VerificationFailedError({ reason: (e as Error).message })
+          if (!(e instanceof Errors.PaymentError))
+            console.error('mppx: internal verification error', e)
+          const error = e instanceof Errors.PaymentError ? e : new Errors.VerificationFailedError()
           const response = await transport.respondChallenge({
             challenge,
             input,
@@ -473,6 +431,8 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
           withReceipt<response>(response?: response) {
             if (managementResponse) {
               return transport.respondReceipt({
+                credential,
+                input,
                 receipt: receiptData,
                 response: managementResponse as never,
                 challengeId: credential.challenge.id,
@@ -480,6 +440,8 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
             }
             if (!response) throw new Error('withReceipt() requires a response argument')
             return transport.respondReceipt({
+              credential,
+              input,
               receipt: receiptData,
               response: response as never,
               challengeId: credential.challenge.id,
@@ -501,6 +463,13 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
   }
 }
 
+function getSafeCredentialReason(error: unknown): string | undefined {
+  if (error instanceof Credential.InvalidCredentialEncodingError) return error.message
+  if (error instanceof Credential.MissingAuthorizationHeaderError) return error.message
+  if (error instanceof Credential.MissingPaymentSchemeError) return error.message
+  return undefined
+}
+
 declare namespace createMethodFn {
   type Parameters<
     method extends Method.Method = Method.Method,
@@ -552,6 +521,88 @@ function resolveRealmFromRequest(input: unknown): string {
   return defaultRealm
 }
 
+type RequestBindingField = 'amount' | 'currency' | 'recipient' | 'chainId' | 'memo' | 'splits'
+
+const requestBindingFields = [
+  'amount',
+  'currency',
+  'recipient',
+  'chainId',
+  'memo',
+  'splits',
+] as const satisfies readonly RequestBindingField[]
+
+type RequestBinding = Partial<Record<RequestBindingField, unknown>>
+
+function getRequestBindingMismatch(
+  expectedRequest: Record<string, unknown>,
+  actualRequest: Record<string, unknown>,
+): RequestBindingField | undefined {
+  const expected = getRequestBinding(expectedRequest)
+  const actual = getRequestBinding(actualRequest)
+
+  return requestBindingFields.find(
+    (field) => !requestBindingValuesMatch(field, expected[field], actual[field]),
+  )
+}
+
+function getRequestBinding(request: Record<string, unknown>): RequestBinding {
+  const methodDetails = (request.methodDetails ?? {}) as Record<string, unknown>
+
+  return {
+    amount: request.amount ?? methodDetails.amount,
+    currency: request.currency ?? methodDetails.currency,
+    recipient: request.recipient ?? methodDetails.recipient,
+    chainId: request.chainId ?? methodDetails.chainId,
+    memo: methodDetails.memo,
+    splits: methodDetails.splits,
+  }
+}
+
+function requestBindingValuesMatch(
+  field: RequestBindingField,
+  expected: unknown,
+  actual: unknown,
+): boolean {
+  return isDeepStrictEqual(
+    normalizeRequestBindingValue(field, expected),
+    normalizeRequestBindingValue(field, actual),
+  )
+}
+
+function normalizeRequestBindingValue(field: RequestBindingField, value: unknown): unknown {
+  switch (field) {
+    case 'memo':
+      return normalizeHex(value)
+    case 'splits':
+      return normalizeComparable(value)
+    default:
+      return normalizeScalar(value)
+  }
+}
+
+function normalizeScalar(value: unknown): string | undefined {
+  return value === undefined ? undefined : String(value)
+}
+
+function normalizeHex(value: unknown): unknown {
+  return typeof value === 'string' && value.startsWith('0x') ? value.toLowerCase() : value
+}
+
+function normalizeComparable(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(normalizeComparable)
+
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, nested]) => [key, normalizeComparable(nested)]),
+    )
+  }
+
+  return normalizeHex(value)
+}
+
 export type MethodFn<
   method extends Method.Method,
   transport extends Transport.AnyTransport,
@@ -668,7 +719,6 @@ export function compose(
       if (credential) {
         const { method: credMethod, intent: credIntent } = credential.challenge
         const credReq = credential.challenge.request as Record<string, unknown>
-        const credDetails = (credReq.methodDetails ?? {}) as Record<string, unknown>
 
         // Filter by name+intent, then narrow by comparing stable request fields
         // from the echoed challenge against each handler's canonical request.
@@ -680,16 +730,7 @@ export function compose(
           if (!meta || meta.name !== credMethod || meta.intent !== credIntent) return false
           const canonical = meta._canonicalRequest
           if (!canonical) return true
-          const canonicalDetails = (canonical.methodDetails ?? {}) as Record<string, unknown>
-          for (const field of ['amount', 'currency', 'recipient', 'chainId'] as const) {
-            const canonicalVal = canonical[field] ?? canonicalDetails[field]
-            if (
-              canonicalVal !== undefined &&
-              String(canonicalVal) !== String(credReq[field] ?? credDetails[field])
-            )
-              return false
-          }
-          return true
+          return !getRequestBindingMismatch(canonical, credReq)
         })
 
         const match =

package/src/server/Transport.test.ts

@@ -135,6 +135,8 @@ describe('http', () => {
       const originalResponse = new Response('OK', { status: 200 })
 
       const response = transport.respondReceipt({
+        credential,
+        input: new Request('https://example.com'),
         receipt,
         response: originalResponse,
         challengeId: challenge.id,
@@ -252,7 +254,13 @@ describe('mcp', () => {
       }
 
       expect(
-        transport.respondReceipt({ receipt, response: successResponse, challengeId: challenge.id }),
+        transport.respondReceipt({
+          credential,
+          input: mcpRequest,
+          receipt,
+          response: successResponse,
+          challengeId: challenge.id,
+        }),
       ).toMatchInlineSnapshot(`
         {
           "id": 1,
@@ -285,7 +293,13 @@ describe('mcp', () => {
       }
 
       expect(
-        transport.respondReceipt({ receipt, response: errorResponse, challengeId: challenge.id }),
+        transport.respondReceipt({
+          credential,
+          input: mcpRequest,
+          receipt,
+          response: errorResponse,
+          challengeId: challenge.id,
+        }),
       ).toBe(errorResponse)
     })
   })

package/src/server/Transport.ts

@@ -1,9 +1,13 @@
+import { Json } from 'ox'
+
 import * as Challenge from '../Challenge.js'
 import * as Credential from '../Credential.js'
 import * as Errors from '../Errors.js'
 import type { Distribute, UnionToIntersection } from '../internal/types.js'
 import * as core_Mcp from '../Mcp.js'
 import * as Receipt from '../Receipt.js'
+import * as Html from './internal/html/config.js'
+import { serviceWorker } from './internal/html/serviceWorker.gen.js'
 
 export { type McpSdk, mcpSdk } from '../mcp-sdk/server/Transport.js'
 
@@ -30,11 +34,14 @@ export type Transport<
   respondChallenge: (options: {
     challenge: Challenge.Challenge
     error?: Errors.PaymentError | undefined
+    html?: Html.Options | undefined
     input: input
   }) => challengeOutput | Promise<challengeOutput>
   /** Attaches a receipt to a successful response. */
   respondReceipt: (options: {
     challengeId: string
+    credential: Credential.Credential
+    input: input
     receipt: Receipt.Receipt
     response: receiptResponse
   }) => receiptOutput
@@ -87,7 +94,7 @@ export type WithReceipt<transport extends AnyTransport = Http> = WithReceiptOver
  *   name: 'custom',
  *   getCredential(input) { ... },
  *   respondChallenge({ challenge, input }) { ... },
- *   respondReceipt({ receipt, response, challengeId }) { ... },
+ *   respondReceipt({ receipt, response, challengeId, credential, input }) { ... },
  * })
  * ```
  */
@@ -121,17 +128,64 @@ export function http(): Http {
       return Credential.deserialize(payment)
     },
 
-    respondChallenge({ challenge, error }) {
+    respondChallenge(options) {
+      const { challenge, error, input } = options
+
+      if (options.html && new URL(input.url).searchParams.has(Html.serviceWorkerParam))
+        return new Response(serviceWorker, {
+          status: 200,
+          headers: {
+            'Content-Type': 'application/javascript',
+            'Cache-Control': 'no-store',
+          },
+        })
+
       const headers: Record<string, string> = {
         'WWW-Authenticate': Challenge.serialize(challenge),
         'Cache-Control': 'no-store',
       }
 
-      let body: string | null = null
-      if (error) {
-        headers['Content-Type'] = 'application/problem+json'
-        body = JSON.stringify(error.toProblemDetails(challenge.id))
-      }
+      const body = (() => {
+        if (options.html && input.headers.get('Accept')?.includes('text/html')) {
+          headers['Content-Type'] = 'text/html; charset=utf-8'
+          const html = String.raw
+          return html`<!doctype html>
+            <html lang="en">
+              <head>
+                <meta charset="UTF-8" />
+                <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+                <title>Payment Required</title>
+                <style>
+                  :root {
+                    color-scheme: dark light;
+                  }
+                </style>
+              </head>
+              <body>
+                <h1>Payment Required</h1>
+                <pre>
+${Json.stringify(challenge, null, 2)
+                    .replace(/&/g, '&amp;')
+                    .replace(/</g, '&lt;')
+                    .replace(/>/g, '&gt;')}</pre
+                >
+                <div id="root"></div>
+                <script id="${Html.dataId}" type="application/json">
+                  ${Json.stringify({ config: options.html.config, challenge }).replace(
+                    /</g,
+                    '\\u003c',
+                  )}
+                </script>
+                ${options.html.content}
+              </body>
+            </html> `
+        }
+        if (error) {
+          headers['Content-Type'] = 'application/problem+json'
+          return JSON.stringify(error.toProblemDetails(challenge.id))
+        }
+        return null
+      })()
 
       return new Response(body, { status: error?.status ?? 402, headers })
     },

package/src/server/internal/html/config.ts

@@ -0,0 +1,8 @@
+export type Options = {
+  config: Record<string, unknown>
+  content: string
+}
+
+export const dataId = '__MPPX_DATA__'
+
+export const serviceWorkerParam = '__mppx_worker'

package/src/server/internal/html/serviceWorker.client.ts

@@ -0,0 +1,28 @@
+import { serviceWorkerParam } from './config.js'
+
+export async function submitCredential(credential: string): Promise<void> {
+  const url = new URL(location.href)
+  url.searchParams.set(serviceWorkerParam, '')
+
+  const registration = await navigator.serviceWorker.register(url.pathname + url.search)
+
+  const serviceWorker = await new Promise<ServiceWorker>((resolve) => {
+    const mppxWorker = registration.installing ?? registration.waiting ?? registration.active
+    if (mppxWorker?.state === 'activated') return resolve(mppxWorker)
+    const target = mppxWorker ?? registration
+    target.addEventListener('statechange', function handler() {
+      const active = registration.active
+      if (active?.state === 'activated') {
+        target.removeEventListener('statechange', handler)
+        resolve(active)
+      }
+    })
+  })
+
+  await new Promise<void>((resolve) => {
+    const channel = new MessageChannel()
+    channel.port1.onmessage = () => resolve()
+    serviceWorker.postMessage({ credential }, [channel.port2])
+  })
+  location.reload()
+}

package/src/server/internal/html/serviceWorker.gen.ts

@@ -0,0 +1,2 @@
+// Generated — do not edit.
+export const serviceWorker = "(function(){let e=self,t;e.addEventListener(`activate`,t=>{t.waitUntil(e.clients.claim())}),e.addEventListener(`message`,e=>{if(!e.source)return;let n=e.data?.credential;typeof n!=`string`||!n.startsWith(`Payment `)||(t=n,e.ports[0]?.postMessage(`ack`))}),e.addEventListener(`fetch`,n=>{if(!t||n.request.mode!==`navigate`||new URL(n.request.url).origin!==e.location.origin)return;let r=new Headers(n.request.headers);r.set(`Authorization`,t),t=void 0,n.respondWith(fetch(n.request,{headers:r})),e.registration.unregister()})})();"

package/src/server/internal/html/serviceWorker.ts

@@ -0,0 +1,27 @@
+const serviceWorker = self as unknown as ServiceWorkerGlobalScope
+
+let credential: string | undefined
+
+serviceWorker.addEventListener('activate', (event) => {
+  event.waitUntil(serviceWorker.clients.claim())
+})
+
+serviceWorker.addEventListener('message', (event) => {
+  if (!event.source) return
+  const value = event.data?.credential
+  if (typeof value !== 'string' || !value.startsWith('Payment ')) return
+  credential = value
+  event.ports[0]?.postMessage('ack')
+})
+
+serviceWorker.addEventListener('fetch', (event) => {
+  if (!credential || event.request.mode !== 'navigate') return
+  if (new URL(event.request.url).origin !== serviceWorker.location.origin) return
+
+  const headers = new Headers(event.request.headers)
+  headers.set('Authorization', credential)
+  credential = undefined
+
+  event.respondWith(fetch(event.request, { headers }))
+  serviceWorker.registration.unregister()
+})

package/src/server/internal/html/tsconfig.worker.client.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["es2022", "dom"],
+    "types": []
+  },
+  "include": ["serviceWorker.client.ts"]
+}

package/src/server/internal/html/tsconfig.worker.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["es2022", "webworker"],
+    "types": []
+  },
+  "include": ["serviceWorker.ts"]
+}

package/src/stripe/server/Charge.ts

@@ -5,6 +5,7 @@ import type { LooseOmit, OneOf } from '../../internal/types.js'
 import * as Method from '../../Method.js'
 import type { StripeClient } from '../internal/types.js'
 import * as Methods from '../Methods.js'
+import { html as htmlContent } from './internal/html.gen.js'
 
 /**
  * Creates a Stripe charge method intent for usage on the server.
@@ -38,6 +39,7 @@ export function charge<const parameters extends charge.Parameters>(parameters: p
     decimals,
     description,
     externalId,
+    html,
     metadata,
     networkId,
     paymentMethodTypes,
@@ -59,9 +61,11 @@ export function charge<const parameters extends charge.Parameters>(parameters: p
       paymentMethodTypes,
     } as unknown as Defaults,
 
-    async verify({ credential }) {
+    html: html ? { config: html, content: htmlContent } : undefined,
+
+    async verify({ credential, request }) {
       const { challenge } = credential
-      const { request } = challenge
+      const resolvedRequest = Methods.charge.schema.request.parse(request)
 
       Expires.assert(challenge.expires, challenge.id)
 
@@ -72,15 +76,23 @@ export function charge<const parameters extends charge.Parameters>(parameters: p
         externalId?: string
       }
 
-      const userMetadata = request.methodDetails?.metadata as Record<string, string> | undefined
+      const userMetadata = resolvedRequest.methodDetails?.metadata as
+        | Record<string, string>
+        | undefined
       const resolvedMetadata = { ...buildAnalytics({ credential }), ...userMetadata }
 
       const pi = client
-        ? await createWithClient({ client, challenge, request, spt, metadata: resolvedMetadata })
+        ? await createWithClient({
+            client,
+            challenge,
+            request: resolvedRequest,
+            spt,
+            metadata: resolvedMetadata,
+          })
         : await createWithSecretKey({
             secretKey: secretKey!,
             challenge,
-            request,
+            request: resolvedRequest,
             spt,
             metadata: resolvedMetadata,
           })
@@ -108,6 +120,8 @@ export declare namespace charge {
   type Defaults = LooseOmit<Method.RequestDefaults<typeof Methods.charge>, 'recipient'>
 
   type Parameters = {
+    /** Render payment page when Accept header is text/html (e.g. in browsers) */
+    html?: { createTokenUrl: string; publishableKey: string } | undefined
     /** Optional metadata to include in SPT creation requests. */
     metadata?: Record<string, string> | undefined
   } & Defaults &