mppx 0.0.1 → 0.1.0

package/src/server/Mppx.ts

@@ -0,0 +1,378 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import * as Challenge from '../Challenge.js'
+import type * as Credential from '../Credential.js'
+import * as Errors from '../Errors.js'
+import type * as MethodIntent from '../MethodIntent.js'
+import type * as Receipt from '../Receipt.js'
+import type * as z from '../zod.js'
+import * as NodeListener from './NodeListener.js'
+import * as Request from './Request.js'
+import * as Transport from './Transport.js'
+
+export type Methods = readonly (MethodIntent.AnyServer | readonly MethodIntent.AnyServer[])[]
+
+/**
+ * Payment handler.
+ */
+export type Mppx<
+  methods extends Methods = Methods,
+  transport extends Transport.AnyTransport = Transport.Http,
+> = {
+  /** Methods to configure. */
+  methods: FlattenMethods<methods>
+  /** Server realm (e.g., hostname). */
+  realm: string
+  /** The transport used. */
+  transport: transport
+} & Handlers<FlattenMethods<methods>, transport>
+
+/** Extracts the transport override from a method intent, if any. */
+type TransportOverrideOf<mi> = mi extends { transport?: infer transport }
+  ? Exclude<transport, undefined> extends Transport.AnyTransport
+    ? Exclude<transport, undefined>
+    : never
+  : never
+
+/** Resolves the effective transport for an intent: override if present, else global default. */
+type EffectiveTransportOf<mi, defaultTransport extends Transport.AnyTransport> = [
+  TransportOverrideOf<mi>,
+] extends [never]
+  ? defaultTransport
+  : TransportOverrideOf<mi>
+
+type Handlers<
+  methods extends readonly MethodIntent.AnyServer[],
+  transport extends Transport.AnyTransport,
+> = {
+  [intent in methods[number]['name']]: IntentFn<
+    Extract<methods[number], { name: intent }>,
+    EffectiveTransportOf<Extract<methods[number], { name: intent }>, transport>,
+    NonNullable<Extract<methods[number], { name: intent }>['defaults']>
+  >
+}
+
+/**
+ * Creates a server-side payment handler from method intents.
+ *
+ * It is highly recommended to set a `secretKey` to bind challenges to their contents,
+ * and allow the server to verify that incoming credentials match challenges it issued.
+ *
+ * @example
+ * ```ts
+ * import { Mppx, tempo } from 'mppx/server'
+ *
+ * const payment = Mppx.create({
+ *   methods: [tempo()],
+ *   secretKey: process.env.PAYMENT_SECRET_KEY,
+ * })
+ * ```
+ */
+export function create<
+  const methods extends Methods,
+  const transport extends Transport.AnyTransport = Transport.Http,
+>(config: create.Config<methods, transport>): Mppx<methods, transport> {
+  const {
+    realm = 'MPP Payment',
+    secretKey = 'tmp',
+    transport = Transport.http() as transport,
+  } = config
+
+  const methods = config.methods.flat() as unknown as FlattenMethods<methods>
+
+  const handlers: Record<string, unknown> = {}
+
+  for (const mi of methods) {
+    handlers[mi.name] = createIntentFn({
+      defaults: mi.defaults,
+      intent: mi,
+      realm,
+      request: mi.request as never,
+      respond: mi.respond as never,
+      secretKey,
+      transport: (mi.transport ?? transport) as never,
+      verify: mi.verify as never,
+    })
+  }
+
+  return { methods, realm: realm as string, transport, ...handlers } as never
+}
+
+export declare namespace create {
+  type Config<
+    methods extends Methods = Methods,
+    transport extends Transport.AnyTransport = Transport.Http,
+  > = {
+    /** Array of configured methods. @example [tempo()] */
+    methods: methods
+    /** Server realm (e.g., hostname). @default "MPP Payment". */
+    realm?: string | undefined
+    /** Secret key for HMAC-bound challenge IDs for stateless verification. */
+    secretKey?: string | undefined
+    /** Transport to use. @default Transport.http() */
+    transport?: transport | undefined
+  }
+}
+
+function createIntentFn<
+  intent extends MethodIntent.MethodIntent,
+  transport extends Transport.AnyTransport,
+  defaults extends Record<string, unknown>,
+>(
+  parameters: createIntentFn.Parameters<intent, transport, defaults>,
+): createIntentFn.ReturnType<intent, transport, defaults>
+// biome-ignore lint/correctness/noUnusedVariables: _
+function createIntentFn(parameters: createIntentFn.Parameters): createIntentFn.ReturnType {
+  const { defaults, intent, realm, respond, secretKey, transport, verify } = parameters
+
+  return (options) => {
+    const meta = {
+      ...intent,
+      ...defaults,
+      ...options,
+    }
+    return Object.assign(
+      async (input: Transport.InputOf): Promise<IntentFn.Response> => {
+        const { description, ...rest } = options
+        const expires = 'expires' in options ? (options.expires as string | undefined) : undefined
+
+        // Merge defaults with per-request options
+        const merged = { ...defaults, ...rest }
+
+        // Extract credential once — getCredential may have side effects (e.g. SSE transports).
+        const [credential, credentialError] = (() => {
+          try {
+            return [
+              transport.getCredential(input) as Credential.Credential | null,
+              undefined,
+            ] as const
+          } catch (e) {
+            return [null, e as Error] as const
+          }
+        })()
+
+        // Transform request if method provides a `request` function.
+        const request = (
+          parameters.request
+            ? await parameters.request({ credential, request: merged } as never)
+            : merged
+        ) as never
+
+        // Recompute challenge from options. The HMAC-bound ID means we don't need to
+        // store challenges server-side—if the client echoes back a credential with
+        // a matching ID, we know it was issued by us with these exact parameters.
+        const challenge = Challenge.fromIntent(intent, {
+          description,
+          expires,
+          realm,
+          request,
+          secretKey,
+        })
+
+        // Credential was provided but malformed
+        if (credentialError) {
+          const response = await transport.respondChallenge({
+            challenge,
+            input,
+            error: new Errors.MalformedCredentialError({ reason: credentialError.message }),
+          })
+          return { challenge: response, status: 402 }
+        }
+
+        // No credential provided—issue challenge
+        if (!credential) {
+          const response = await transport.respondChallenge({
+            challenge,
+            input,
+            error: new Errors.PaymentRequiredError({ realm, description }),
+          })
+          return { challenge: response, status: 402 }
+        }
+
+        // Verify the echoed challenge was issued by us by recomputing its HMAC.
+        // This is stateless—no database lookup needed.
+        if (!Challenge.verify(credential.challenge, { secretKey })) {
+          const response = await transport.respondChallenge({
+            challenge,
+            input,
+            error: new Errors.InvalidChallengeError({
+              id: credential.challenge.id,
+              reason: 'challenge was not issued by this server',
+            }),
+          })
+          return { challenge: response, status: 402 }
+        }
+
+        // Validate payload structure against intent schema
+        try {
+          intent.schema.credential.payload.parse(credential.payload)
+        } catch (e) {
+          const response = await transport.respondChallenge({
+            challenge,
+            input,
+            error: new Errors.InvalidPayloadError({ reason: (e as Error).message }),
+          })
+          return { challenge: response, status: 402 }
+        }
+
+        // User-provided verification (e.g., check signature, submit tx, verify payment).
+        // If verification fails, re-issue the challenge so the client can retry.
+        let receiptData: Receipt.Receipt
+        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 })
+          const response = await transport.respondChallenge({
+            challenge,
+            input,
+            error,
+          })
+          return { challenge: response, status: 402 }
+        }
+
+        // If the method's `respond` hook returns a Response, it means this
+        // request is a management action (e.g. channel open, voucher POST)
+        // and the user's route handler should NOT run. `withReceipt()` will
+        // return the management response directly. If undefined, `withReceipt()`
+        // expects the caller to pass the user handler's response instead.
+        const managementResponse = respond
+          ? await respond({ credential, input, receipt: receiptData, request } as never)
+          : undefined
+
+        return {
+          status: 200,
+          withReceipt<response>(response?: response) {
+            if (managementResponse) {
+              return transport.respondReceipt({
+                receipt: receiptData,
+                response: managementResponse as never,
+                challengeId: credential.challenge.id,
+              }) as response
+            }
+            if (!response) throw new Error('withReceipt() requires a response argument')
+            return transport.respondReceipt({
+              receipt: receiptData,
+              response: response as never,
+              challengeId: credential.challenge.id,
+            }) as response
+          },
+        }
+      },
+      { _internal: meta },
+    )
+  }
+}
+
+declare namespace createIntentFn {
+  type Parameters<
+    intent extends MethodIntent.MethodIntent = MethodIntent.MethodIntent,
+    transport extends Transport.AnyTransport = Transport.Http,
+    defaults extends Record<string, unknown> = Record<string, unknown>,
+  > = {
+    defaults?: defaults
+    intent: intent
+    realm: string
+    request?: MethodIntent.RequestFn<intent>
+    respond?: MethodIntent.RespondFn<intent>
+    secretKey: string
+    transport: transport
+    verify: MethodIntent.VerifyFn<intent>
+  }
+
+  type ReturnType<
+    intent extends MethodIntent.MethodIntent = MethodIntent.MethodIntent,
+    transport extends Transport.AnyTransport = Transport.Http,
+    defaults extends Record<string, unknown> = Record<string, unknown>,
+  > = IntentFn<intent, transport, defaults>
+}
+
+export type IntentFn<
+  intent extends MethodIntent.MethodIntent,
+  transport extends Transport.AnyTransport,
+  defaults extends Record<string, unknown>,
+> = (
+  options: IntentFn.Options<intent, defaults>,
+) => (input: Transport.InputOf<transport>) => Promise<IntentFn.Response<transport>>
+/** @internal */
+export type AnyIntentFn = (options: any) => (input: any) => Promise<any>
+
+/** @internal */
+declare namespace IntentFn {
+  export type Options<
+    intent extends MethodIntent.MethodIntent,
+    defaults extends Record<string, unknown> = Record<string, unknown>,
+  > = {
+    /** Optional human-readable description of the payment. */
+    description?: string | undefined
+    /** Optional challenge expiration timestamp (ISO 8601). */
+    expires?: string | undefined
+  } & MethodIntent.WithDefaults<z.input<intent['schema']['request']>, defaults>
+
+  export type Response<transport extends Transport.AnyTransport = Transport.Http> =
+    | {
+        challenge: Transport.ChallengeOutputOf<transport>
+        status: 402
+      }
+    | {
+        status: 200
+        withReceipt: Transport.WithReceipt<transport>
+      }
+}
+
+/**
+ * Wraps a payment handler to create a Node.js HTTP listener.
+ *
+ * On 402: writes the challenge response and ends the connection.
+ * On 200: sets the Payment-Receipt header; caller should write response body.
+ *
+ * @example
+ * ```ts
+ * import * as http from 'node:http'
+ * import { Mppx } from 'mppx/server'
+ *
+ * const payment = Mppx.create({ ... })
+ *
+ * http.createServer(async (req, res) => {
+ *   const result = await Mppx.toNodeListener(
+ *     payment.charge({
+ *       amount: '1', currency: '...', recipient: '0x...',
+ *     }),
+ *   )(req, res)
+ *   if (result.status === 402) return
+ *   res.end('OK')
+ * })
+ * ```
+ */
+export function toNodeListener(
+  handler: (input: globalThis.Request) => Promise<IntentFn.Response<Transport.Http>>,
+): (req: IncomingMessage, res: ServerResponse) => Promise<IntentFn.Response<Transport.Http>> {
+  return async (req, res) => {
+    const result = await handler(Request.fromNodeListener(req, res))
+
+    if (result.status === 402) {
+      await NodeListener.sendResponse(res, result.challenge as globalThis.Response)
+    } else {
+      const wrapped = result.withReceipt(new globalThis.Response()) as globalThis.Response
+      res.setHeader('Payment-Receipt', wrapped.headers.get('Payment-Receipt')!)
+    }
+
+    return result
+  }
+}
+
+/**
+ * Flattens a methods config tuple, preserving positional types.
+ * @internal
+ */
+type FlattenMethods<methods extends Methods> = methods extends readonly [
+  infer head,
+  ...infer tail extends Methods,
+]
+  ? head extends readonly MethodIntent.AnyServer[]
+    ? readonly [...head, ...FlattenMethods<tail>]
+    : head extends MethodIntent.AnyServer
+      ? readonly [head, ...FlattenMethods<tail>]
+      : never
+  : readonly []

package/src/server/NodeListener.test.ts

@@ -0,0 +1,188 @@
+import { NodeListener, Request } from 'mppx/server'
+import { afterEach, describe, expect, test } from 'vitest'
+import * as Http from '~test/Http.js'
+
+let server: Awaited<ReturnType<typeof Http.createServer>> | undefined
+
+afterEach(() => server?.close())
+
+describe('sendResponse', () => {
+  test('writes status and headers', async () => {
+    server = await Http.createServer(async (_, res) => {
+      const response = new Response(null, {
+        status: 204,
+        headers: { 'X-Custom': 'hello' },
+      })
+      await NodeListener.sendResponse(res, response)
+    })
+
+    const response = await fetch(server.url)
+    expect(response.status).toBe(204)
+    expect(response.headers.get('X-Custom')).toBe('hello')
+  })
+
+  test('streams text body', async () => {
+    server = await Http.createServer(async (_, res) => {
+      const response = new Response('hello world', {
+        status: 200,
+        headers: { 'Content-Type': 'text/plain' },
+      })
+      await NodeListener.sendResponse(res, response)
+    })
+
+    const response = await fetch(server.url)
+    expect(response.status).toBe(200)
+    expect(await response.text()).toBe('hello world')
+  })
+
+  test('streams json body', async () => {
+    server = await Http.createServer(async (_, res) => {
+      const response = Response.json({ fortune: 'You will be rich' })
+      await NodeListener.sendResponse(res, response)
+    })
+
+    const response = await fetch(server.url)
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({ fortune: 'You will be rich' })
+  })
+
+  test('streams chunked body', async () => {
+    server = await Http.createServer(async (_, res) => {
+      const stream = new ReadableStream({
+        start(controller) {
+          controller.enqueue(new TextEncoder().encode('chunk1'))
+          controller.enqueue(new TextEncoder().encode('chunk2'))
+          controller.close()
+        },
+      })
+      const response = new Response(stream, { status: 200 })
+      await NodeListener.sendResponse(res, response)
+    })
+
+    const response = await fetch(server.url)
+    expect(response.status).toBe(200)
+    expect(await response.text()).toBe('chunk1chunk2')
+  })
+
+  test('handles null body', async () => {
+    server = await Http.createServer(async (_, res) => {
+      const response = new Response(null, { status: 204 })
+      await NodeListener.sendResponse(res, response)
+    })
+
+    const response = await fetch(server.url)
+    expect(response.status).toBe(204)
+    expect(await response.text()).toBe('')
+  })
+
+  test('preserves multiple Set-Cookie headers', async () => {
+    server = await Http.createServer(async (_req, res) => {
+      const headers = new Headers()
+      headers.append('Set-Cookie', 'a=1')
+      headers.append('Set-Cookie', 'b=2')
+      const response = new Response('ok', { headers })
+      await NodeListener.sendResponse(res, response)
+    })
+
+    const response = await fetch(server.url)
+    expect(response.headers.getSetCookie()).toEqual(['a=1', 'b=2'])
+  })
+
+  test('skips body for HEAD requests', async () => {
+    let bodyWritten = false
+    server = await Http.createServer(async (_req, res) => {
+      const original = res.write.bind(res)
+      res.write = (...args: any[]) => {
+        bodyWritten = true
+        // @ts-expect-error
+        return original(...(args as any))
+      }
+      const response = new Response('should not be sent', {
+        status: 200,
+        headers: { 'Content-Type': 'text/plain' },
+      })
+      await NodeListener.sendResponse(res, response)
+    })
+
+    const response = await fetch(server.url, { method: 'HEAD' })
+    expect(response.status).toBe(200)
+    expect(response.headers.get('Content-Type')).toBe('text/plain')
+    expect(bodyWritten).toBe(false)
+  })
+})
+
+describe('toNodeListener', () => {
+  test('converts fetch handler to node listener', async () => {
+    const handler = Request.toNodeListener(async (request) => {
+      const url = new URL(request.url)
+      return Response.json({ path: url.pathname })
+    })
+
+    server = await Http.createServer(handler)
+
+    const response = await fetch(`${server.url}/hello`)
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({ path: '/hello' })
+  })
+
+  test('forwards request method', async () => {
+    const handler = Request.toNodeListener(async (request) => {
+      return Response.json({ method: request.method })
+    })
+
+    server = await Http.createServer(handler)
+
+    const response = await fetch(server.url, { method: 'POST' })
+    expect(await response.json()).toEqual({ method: 'POST' })
+  })
+
+  test('forwards request headers', async () => {
+    const handler = Request.toNodeListener(async (request) => {
+      return Response.json({ auth: request.headers.get('X-Api-Key') })
+    })
+
+    server = await Http.createServer(handler)
+
+    const response = await fetch(server.url, {
+      headers: { 'X-Api-Key': 'secret123' },
+    })
+    expect(await response.json()).toEqual({ auth: 'secret123' })
+  })
+
+  test('forwards request body', async () => {
+    const handler = Request.toNodeListener(async (request) => {
+      const body = await request.json()
+      return Response.json({ echo: body })
+    })
+
+    server = await Http.createServer(handler)
+
+    const response = await fetch(server.url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ hello: 'world' }),
+    })
+    expect(await response.json()).toEqual({ echo: { hello: 'world' } })
+  })
+
+  test('streams response body', async () => {
+    const handler = Request.toNodeListener(async () => {
+      const stream = new ReadableStream({
+        start(controller) {
+          controller.enqueue(new TextEncoder().encode('a'))
+          controller.enqueue(new TextEncoder().encode('b'))
+          controller.enqueue(new TextEncoder().encode('c'))
+          controller.close()
+        },
+      })
+      return new Response(stream, {
+        headers: { 'Content-Type': 'text/plain' },
+      })
+    })
+
+    server = await Http.createServer(handler)
+
+    const response = await fetch(server.url)
+    expect(await response.text()).toBe('abc')
+  })
+})

package/src/server/NodeListener.ts

@@ -0,0 +1,3 @@
+import * as FetchServer from '@remix-run/node-fetch-server'
+
+export const sendResponse = FetchServer.sendResponse

package/src/server/Request.test.ts

@@ -0,0 +1,102 @@
+import { EventEmitter } from 'node:events'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { Request } from 'mppx/server'
+import { describe, expect, test } from 'vitest'
+
+function createMockRequest(options: {
+  method?: string
+  url?: string
+  rawHeaders?: string[]
+  socket?: { encrypted?: boolean }
+}): [IncomingMessage, ServerResponse] {
+  const rawHeaders = options.rawHeaders ?? []
+  const headers = Object.fromEntries(
+    rawHeaders.reduce<[string, string][]>((acc, v, i, arr) => {
+      if (i % 2 === 0 && arr[i + 1]) acc.push([v.toLowerCase(), arr[i + 1]!])
+      return acc
+    }, []),
+  )
+  const req = Object.assign(new EventEmitter(), {
+    method: options.method ?? 'GET',
+    url: options.url ?? '/',
+    headers,
+    rawHeaders,
+    socket: options.socket ?? {},
+  }) as unknown as IncomingMessage
+
+  const res = new EventEmitter() as unknown as ServerResponse
+
+  return [req, res]
+}
+
+describe('fromNodeListener', () => {
+  test('converts IncomingMessage to Fetch Request', () => {
+    const [req, res] = createMockRequest({
+      method: 'POST',
+      url: '/api/resource',
+      rawHeaders: [
+        'Host',
+        'example.com',
+        'Authorization',
+        'Bearer token',
+        'Content-Type',
+        'application/json',
+      ],
+    })
+
+    const request = Request.fromNodeListener(req, res)
+
+    expect(request.method).toBe('POST')
+    expect(request.url).toBe('http://example.com/api/resource')
+    expect(request.headers.get('Authorization')).toBe('Bearer token')
+    expect(request.headers.get('Content-Type')).toBe('application/json')
+  })
+
+  test('uses default values when host/url/method missing', () => {
+    const [req, res] = createMockRequest({})
+
+    const request = Request.fromNodeListener(req, res)
+
+    expect(request.method).toBe('GET')
+    expect(request.url).toBe('http://localhost/')
+  })
+
+  test('preserves multi-value headers via append', () => {
+    const [req, res] = createMockRequest({
+      rawHeaders: ['Host', 'example.com', 'Set-Cookie', 'a=1', 'Set-Cookie', 'b=2'],
+    })
+
+    const request = Request.fromNodeListener(req, res)
+
+    expect(request.headers.get('Set-Cookie')).toBe('a=1, b=2')
+  })
+
+  test('skips HTTP/2 pseudo-headers', () => {
+    const [req, res] = createMockRequest({
+      rawHeaders: [':method', 'GET', ':path', '/', 'Host', 'example.com'],
+    })
+
+    const request = Request.fromNodeListener(req, res)
+
+    expect([...request.headers.keys()]).toEqual(['host'])
+    expect(request.headers.get('Host')).toBe('example.com')
+  })
+
+  test('streams body for POST requests', async () => {
+    const [req, res] = createMockRequest({
+      method: 'POST',
+      rawHeaders: ['Host', 'example.com', 'Content-Type', 'application/json'],
+    })
+
+    const request = Request.fromNodeListener(req, res)
+
+    setImmediate(() => {
+      req.emit('data', Buffer.from('{"hello":'))
+      req.emit('data', Buffer.from('"world"}'))
+      req.emit('end')
+    })
+
+    const body = await request.text()
+    expect(body).toBe('{"hello":"world"}')
+  })
+})