mppx 0.5.1 → 0.5.4

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

@@ -101,6 +101,222 @@ describe('http', () => {
     })
   })
 
+  describe('respondChallenge html', () => {
+    const htmlOptions = {
+      config: { foo: 'bar' },
+      content: '<script src="/pay.js"></script>',
+      formatAmount: () => '$10.00',
+      text: undefined,
+      theme: undefined,
+    } satisfies Parameters<Transport.Http['respondChallenge']>[0]['html']
+
+    test('returns html when Accept includes text/html', async () => {
+      const transport = Transport.http()
+      const request = new Request('https://example.com', {
+        headers: { Accept: 'text/html' },
+      })
+
+      const response = await transport.respondChallenge({
+        challenge,
+        input: request,
+        html: htmlOptions,
+      })
+
+      expect(response.status).toBe(402)
+      expect(response.headers.get('Content-Type')).toBe('text/html; charset=utf-8')
+      expect(response.headers.get('WWW-Authenticate')).toContain('Payment')
+      expect(response.headers.get('Cache-Control')).toBe('no-store')
+
+      const body = await response.text()
+      expect(body).toContain('<!doctype html>')
+      expect(body).toContain('<title>Payment Required</title>')
+      expect(body).toContain('$10.00')
+      expect(body).toContain('Payment Required')
+      expect(body).toContain('<script src="/pay.js"></script>')
+      expect(body).toContain('__MPPX_DATA__')
+    })
+
+    test('returns service worker script when __mppx_worker param is set', async () => {
+      const transport = Transport.http()
+      const request = new Request('https://example.com?__mppx_worker')
+
+      const response = await transport.respondChallenge({
+        challenge,
+        input: request,
+        html: htmlOptions,
+      })
+
+      expect(response.status).toBe(200)
+      expect(response.headers.get('Content-Type')).toBe('application/javascript')
+      expect(response.headers.get('Cache-Control')).toBe('no-store')
+
+      const body = await response.text()
+      expect(body).toContain('addEventListener')
+    })
+
+    test('does not return html when Accept does not include text/html', async () => {
+      const transport = Transport.http()
+      const request = new Request('https://example.com', {
+        headers: { Accept: 'application/json' },
+      })
+
+      const response = await transport.respondChallenge({
+        challenge,
+        input: request,
+        html: htmlOptions,
+      })
+
+      expect(response.status).toBe(402)
+      expect(response.headers.get('Content-Type')).toBeNull()
+      expect(await response.text()).toBe('')
+    })
+
+    test('renders description when challenge has one', async () => {
+      const transport = Transport.http()
+      const request = new Request('https://example.com', {
+        headers: { Accept: 'text/html' },
+      })
+
+      const challengeWithDescription = {
+        ...challenge,
+        description: 'Access to premium content',
+      }
+
+      const response = await transport.respondChallenge({
+        challenge: challengeWithDescription,
+        input: request,
+        html: htmlOptions,
+      })
+
+      const body = await response.text()
+      expect(body).toContain('Access to premium content')
+      expect(body).toContain('mppx-summary-description')
+    })
+
+    test('renders expires when challenge has one', async () => {
+      const transport = Transport.http()
+      const request = new Request('https://example.com', {
+        headers: { Accept: 'text/html' },
+      })
+
+      const response = await transport.respondChallenge({
+        challenge,
+        input: request,
+        html: htmlOptions,
+      })
+
+      const body = await response.text()
+      expect(body).toContain('Expires at')
+      expect(body).toContain('2025-01-01T00:00:00.000Z')
+      expect(body).toContain('mppx-summary-expires')
+    })
+
+    test('does not render description when challenge lacks one', async () => {
+      const transport = Transport.http()
+      const request = new Request('https://example.com', {
+        headers: { Accept: 'text/html' },
+      })
+
+      const challengeNoDescription = { ...challenge }
+      delete (challengeNoDescription as any).description
+
+      const response = await transport.respondChallenge({
+        challenge: challengeNoDescription,
+        input: request,
+        html: htmlOptions,
+      })
+
+      const body = await response.text()
+      expect(body).not.toMatch(/<p class="mppx-summary-description"/)
+    })
+
+    test('applies custom text', async () => {
+      const transport = Transport.http()
+      const request = new Request('https://example.com', {
+        headers: { Accept: 'text/html' },
+      })
+
+      const response = await transport.respondChallenge({
+        challenge,
+        input: request,
+        html: {
+          ...htmlOptions,
+          text: { title: 'Pay Up', paymentRequired: 'Gotta Pay' },
+        },
+      })
+
+      const body = await response.text()
+      expect(body).toContain('<title>Pay Up</title>')
+      expect(body).toContain('Gotta Pay')
+    })
+
+    test('applies custom theme logo', async () => {
+      const transport = Transport.http()
+      const request = new Request('https://example.com', {
+        headers: { Accept: 'text/html' },
+      })
+
+      const response = await transport.respondChallenge({
+        challenge,
+        input: request,
+        html: {
+          ...htmlOptions,
+          theme: { logo: 'https://example.com/logo.png' },
+        },
+      })
+
+      const body = await response.text()
+      expect(body).toContain('https://example.com/logo.png')
+      expect(body).toContain('mppx-logo')
+    })
+
+    test('embeds config and challenge in data script', async () => {
+      const transport = Transport.http()
+      const request = new Request('https://example.com', {
+        headers: { Accept: 'text/html' },
+      })
+
+      const response = await transport.respondChallenge({
+        challenge,
+        input: request,
+        html: htmlOptions,
+      })
+
+      const body = await response.text()
+      // Extract the JSON data from the script tag
+      const dataMatch = body.match(
+        /<script id="__MPPX_DATA__" type="application\/json">\s*([\s\S]*?)\s*<\/script>/,
+      )
+      expect(dataMatch).not.toBeNull()
+
+      const data = JSON.parse(dataMatch?.[1]?.replace(/\\u003c/g, '<') ?? '')
+      expect(data.config).toEqual({ foo: 'bar' })
+      expect(data.challenge.id).toBe(challenge.id)
+      expect(data.challenge.method).toBe('tempo')
+      expect(data.text.paymentRequired).toBe('Payment Required')
+    })
+
+    test('sanitizes html in formatted amount', async () => {
+      const transport = Transport.http()
+      const request = new Request('https://example.com', {
+        headers: { Accept: 'text/html' },
+      })
+
+      const response = await transport.respondChallenge({
+        challenge,
+        input: request,
+        html: {
+          ...htmlOptions,
+          formatAmount: () => '<script>alert("xss")</script>',
+        },
+      })
+
+      const body = await response.text()
+      expect(body).not.toContain('<script>alert("xss")</script>')
+      expect(body).toContain('&lt;script&gt;')
+    })
+  })
+
   describe('respondChallenge with error status codes', () => {
     test('BadRequestError returns 400', async () => {
       const transport = Transport.http()
@@ -135,6 +351,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 +470,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 +509,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)
     })
   })