mppx 0.0.1 → 0.1.0

package/src/proxy/Proxy.ts

@@ -0,0 +1,175 @@
+import type * as http from 'node:http'
+import { createFetchProxy } from '@remix-run/fetch-proxy'
+import * as Request from '../server/Request.js'
+import * as Headers from './internal/Headers.js'
+import * as Route from './internal/Route.js'
+import * as Service from './Service.js'
+
+/** A paid API proxy that gates upstream services behind the mppx 402 protocol. */
+export type Proxy = {
+  /** Fetch API handler. Works with Bun, Deno, Next.js, Hono, Elysia, SvelteKit, etc. */
+  fetch: (request: Request) => Promise<Response>
+  /** Node.js request listener. Works with Express, Fastify, `http.createServer`, etc. */
+  listener: (req: http.IncomingMessage, res: http.ServerResponse) => void
+}
+
+/**
+ * Creates a paid API proxy.
+ *
+ * Routes incoming requests to upstream services, injects credentials,
+ * and requires payment via the mppx 402 protocol for non-free endpoints.
+ *
+ * @example
+ * ```ts
+ * import { Proxy, openai } from 'mppx/proxy'
+ * import { Mppx, tempo } from 'mppx/server'
+ *
+ * const mppx = Mppx.create({ methods: [tempo()] })
+ *
+ * const proxy = Proxy.create({
+ *   services: [
+ *     openai({
+ *       apiKey: 'sk-...',
+ *       routes: {
+ *         'POST /v1/chat/completions': mppx.charge({ amount: '0.05' }),
+ *         'GET /v1/models': true,
+ *       },
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+export function create(config: create.Config): Proxy {
+  const fetchImpl = config.fetch ?? globalThis.fetch
+
+  const services = new Map(
+    config.services.map((s) => {
+      const proxy = createFetchProxy(s.baseUrl, {
+        fetch: fetchImpl,
+        rewriteCookieDomain: false,
+        rewriteCookiePath: false,
+      })
+      return [s.id, { service: s, proxy }] as const
+    }),
+  )
+
+  async function handle(request: globalThis.Request): Promise<Response> {
+    const url = new URL(request.url)
+
+    const pathname = Route.pathname(url, config.basePath)
+
+    if (!pathname) return new Response('Not Found', { status: 404 })
+
+    if (request.method === 'GET' && pathname === '/llms.txt')
+      return new Response(Service.toLlmsTxt(config.services), {
+        headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+      })
+
+    if (request.method === 'GET' && (pathname === '/services' || pathname === '/services/'))
+      return Response.json(config.services.map(Service.serialize))
+
+    {
+      const match = pathname.match(/^\/services\/([^/]+)\/?$/)
+      if (request.method === 'GET' && match) {
+        const service = config.services.find((s) => s.id === match[1])
+        if (!service) return new Response('Not Found', { status: 404 })
+        return Response.json(Service.serialize(service))
+      }
+    }
+
+    const parsed = Route.parse(pathname)
+    if (!parsed) return new Response('Not Found', { status: 404 })
+
+    const { serviceId, upstreamPath } = parsed
+    const entry = services.get(serviceId)
+    if (!entry) return new Response('Not Found', { status: 404 })
+
+    const { service, proxy } = entry
+
+    const matched =
+      Route.match(service.routes, request.method, upstreamPath) ??
+      // Management POSTs (e.g. session close) may target a path whose route
+      // is registered for a different HTTP method (e.g. GET). Fall back to
+      // path-only matching so the payment handler can process the action.
+      (request.method === 'POST' && request.headers.has('authorization')
+        ? Route.matchPath(service.routes, upstreamPath)
+        : null)
+    if (!matched) return new Response('Not Found', { status: 404 })
+
+    const endpoint = matched.value as Service.Endpoint
+    const ctx: Service.Context = { request, service, upstreamPath }
+
+    if (endpoint === true) return proxyUpstream({ request, service, ctx, proxy })
+
+    const handler = typeof endpoint === 'function' ? endpoint : endpoint.pay
+    const result = await handler(request)
+    if (result.status === 402) return result.challenge
+
+    const options = Service.getOptions(endpoint)
+    const upstreamRes = await proxyUpstream({
+      request,
+      service,
+      ctx: { ...ctx, ...options },
+      proxy,
+    })
+    return result.withReceipt(upstreamRes)
+  }
+
+  return {
+    fetch: handle,
+    listener: Request.toNodeListener(handle),
+  }
+}
+
+export declare namespace create {
+  export type Config = {
+    /** Base path prefix to strip before routing (e.g. `'/api/proxy'`). */
+    basePath?: string | undefined
+    /** Custom `fetch` implementation. Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch | undefined
+    /** Services to proxy. Each service is mounted at `/{serviceId}/`. */
+    services: Service.Service[]
+  }
+}
+
+declare namespace proxyUpstream {
+  type Options = {
+    ctx: Service.Context
+    proxy: (input: URL | RequestInfo, init?: RequestInit) => Promise<Response>
+    request: globalThis.Request
+    service: Service.Service
+  }
+}
+
+/** @internal */
+async function proxyUpstream(options: proxyUpstream.Options): Promise<Response> {
+  const { request, service, ctx, proxy } = options
+  const url = ctx.upstreamPath + new URL(request.url).search
+  const headers = Headers.scrub(request.headers)
+
+  const method = request.method.toUpperCase()
+  const hasBody = method !== 'GET' && method !== 'HEAD'
+
+  const init: RequestInit & { duplex?: 'half' } = {
+    method: request.method,
+    headers,
+    signal: request.signal,
+  }
+
+  if (hasBody && request.body) {
+    init.body = request.body
+    init.duplex = 'half'
+  }
+
+  let upstreamReq = new globalThis.Request(new URL(url, new URL(service.baseUrl).origin), init)
+
+  if (service.rewriteRequest) upstreamReq = await service.rewriteRequest(upstreamReq, ctx)
+
+  let upstreamRes = await proxy(upstreamReq)
+
+  upstreamRes = Headers.scrubResponse(upstreamRes)
+
+  if (service.rewriteResponse) upstreamRes = await service.rewriteResponse(upstreamRes, ctx)
+
+  return upstreamRes
+}

package/src/proxy/Service.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, test } from 'vitest'
+import * as Service from './Service.js'
+
+describe('from', () => {
+  test('behavior: creates service with id and baseUrl', () => {
+    const service = Service.from('api', {
+      baseUrl: 'https://api.example.com',
+      routes: { 'GET /v1/status': true },
+    })
+    expect(service.id).toBe('api')
+    expect(service.baseUrl).toBe('https://api.example.com')
+  })
+
+  test('behavior: bearer sets Authorization header', async () => {
+    const service = Service.from('api', {
+      baseUrl: 'https://api.example.com',
+      bearer: 'sk-123',
+      routes: { 'GET /v1/data': true },
+    })
+    const req = new Request('https://example.com')
+    const ctx = { request: req, service, upstreamPath: '/v1/data' }
+    const result = await service.rewriteRequest!(req, ctx)
+    expect(result.headers.get('authorization')).toBe('Bearer sk-123')
+  })
+
+  test('behavior: headers sets custom headers', async () => {
+    const service = Service.from('api', {
+      baseUrl: 'https://api.example.com',
+      headers: { 'X-Api-Key': 'secret' },
+      routes: { 'GET /v1/data': true },
+    })
+    const req = new Request('https://example.com')
+    const ctx = { request: req, service, upstreamPath: '/v1/data' }
+    const result = await service.rewriteRequest!(req, ctx)
+    expect(result.headers.get('x-api-key')).toBe('secret')
+  })
+
+  test('behavior: multiple headers sets all headers', async () => {
+    const service = Service.from('api', {
+      baseUrl: 'https://api.example.com',
+      headers: { 'X-Key': 'a', 'X-Secret': 'b' },
+      routes: { 'GET /v1/data': true },
+    })
+    const req = new Request('https://example.com')
+    const ctx = { request: req, service, upstreamPath: '/v1/data' }
+    const result = await service.rewriteRequest!(req, ctx)
+    expect(result.headers.get('x-key')).toBe('a')
+    expect(result.headers.get('x-secret')).toBe('b')
+  })
+
+  test('behavior: mutate calls mutate function', async () => {
+    const service = Service.from('api', {
+      baseUrl: 'https://api.example.com',
+      mutate: (req) => {
+        req.headers.set('X-Mutated', 'yes')
+        return req
+      },
+      routes: { 'GET /v1/data': true },
+    })
+    const req = new Request('https://example.com')
+    const ctx = { request: req, service, upstreamPath: '/v1/data' }
+    const result = await service.rewriteRequest!(req, ctx)
+    expect(result.headers.get('x-mutated')).toBe('yes')
+  })
+
+  test('behavior: no auth config means no rewriteRequest', () => {
+    const service = Service.from('api', {
+      baseUrl: 'https://api.example.com',
+      routes: { 'GET /v1/data': true },
+    })
+    expect(service.rewriteRequest).toBeUndefined()
+  })
+
+  test('behavior: per-endpoint options override service bearer', async () => {
+    const handler: Service.IntentHandler = async () => ({
+      status: 200 as const,
+      withReceipt: <T>(r: T) => r,
+    })
+    const service = Service.from('api', {
+      baseUrl: 'https://api.example.com',
+      bearer: 'sk-default',
+      routes: {
+        'GET /v1/data': {
+          pay: handler,
+          options: { bearer: 'sk-override' },
+        },
+      },
+    })
+    const endpoint = service.routes['GET /v1/data']!
+    const options = Service.getOptions(endpoint)
+    const req = new Request('https://example.com')
+    const ctx = { request: req, service, upstreamPath: '/v1/data', ...options }
+    const result = await service.rewriteRequest!(req, ctx)
+    expect(result.headers.get('authorization')).toBe('Bearer sk-override')
+  })
+})
+
+describe('custom', () => {
+  test('behavior: alias for from', () => {
+    expect(Service.custom).toBe(Service.from)
+  })
+})
+
+describe('getOptions', () => {
+  test('behavior: returns options from endpoint object', () => {
+    const handler: Service.IntentHandler = async () => ({
+      status: 200 as const,
+      withReceipt: <T>(r: T) => r,
+    })
+    const endpoint: Service.Endpoint = { pay: handler, options: { apiKey: 'sk-123' } }
+    expect(Service.getOptions(endpoint)).toEqual({ apiKey: 'sk-123' })
+  })
+
+  test('behavior: returns undefined for function endpoint', () => {
+    const handler: Service.IntentHandler = async () => ({
+      status: 200 as const,
+      withReceipt: <T>(r: T) => r,
+    })
+    expect(Service.getOptions(handler)).toBeUndefined()
+  })
+
+  test('behavior: returns undefined for true endpoint', () => {
+    expect(Service.getOptions(true)).toBeUndefined()
+  })
+})

package/src/proxy/Service.ts

@@ -0,0 +1,227 @@
+import { Value } from 'ox'
+
+/** A proxied upstream service with route definitions and optional request/response hooks. */
+export type Service = {
+  /** Unique identifier used as the URL prefix (e.g. `'openai'` → `/{id}/...`). */
+  id: string
+  /** Base URL of the upstream service (e.g. `'https://api.openai.com'`). */
+  baseUrl: string
+  /** Map of route patterns to endpoint handlers. */
+  routes: EndpointMap
+  /** Hook to modify the upstream request before sending (e.g. inject auth headers). */
+  rewriteRequest?: ((req: Request, ctx: Context) => Request | Promise<Request>) | undefined
+  /** Hook to modify the upstream response before returning to the client. */
+  rewriteResponse?: ((res: Response, ctx: Context) => Response | Promise<Response>) | undefined
+}
+
+/**
+ * An endpoint definition.
+ *
+ * - `IntentHandler` — payment required, calls the handler to issue a 402 challenge or verify payment.
+ * - `{ pay, options }` — payment required with per-endpoint config overrides.
+ * - `true` — free passthrough, no payment required, rewriteRequest is applied.
+ */
+export type Endpoint = IntentHandler | { pay: IntentHandler; options: EndpointOptions } | true
+
+/** Map of `"METHOD /pattern"` keys to endpoint definitions. */
+export type EndpointMap<routes extends string = string> = Partial<Record<routes, Endpoint>> &
+  Record<string & {}, Endpoint>
+
+/** Per-endpoint configuration overrides (e.g. `{ apiKey: 'sk-...' }`). */
+export type EndpointOptions = {
+  [key: string]: unknown
+}
+
+/** A function that handles the mppx payment flow for a request. */
+export type IntentHandler = (input: Request) => Promise<IntentResult>
+
+/** Result of an intent handler — either a 402 challenge or a 200 with receipt attachment. */
+export type IntentResult =
+  | { challenge: Response; status: 402 }
+  | { status: 200; withReceipt: <response>(response: response) => response }
+
+/** Context passed to `rewriteRequest`/`rewriteResponse` hooks, including any per-endpoint options. */
+export type Context = {
+  request: Request
+  service: Service
+  upstreamPath: string
+} & EndpointOptions
+
+export type From<
+  options extends {
+    routes: string
+  },
+> = {
+  routes: EndpointMap<options['routes']>
+} & Omit<options, 'routes'>
+
+/**
+ * Creates a service definition.
+ *
+ * @example
+ * ```ts
+ * Service.from('my-api', {
+ *   baseUrl: 'https://api.example.com',
+ *   bearer: 'sk-...',
+ *   routes: {
+ *     'POST /v1/generate': mppx.charge({ amount: '0.01' }),
+ *     'GET /v1/status': true,
+ *   },
+ * })
+ * ```
+ */
+export function from<options = unknown>(id: string, config: from.Config<options>): Service {
+  const rewriteFromConfig = resolveRewriteRequest(config)
+  return {
+    id,
+    baseUrl: config.baseUrl,
+    routes: config.routes,
+    rewriteRequest: config.rewriteRequest
+      ? rewriteFromConfig
+        ? async (req, ctx) => {
+            req = await rewriteFromConfig(req, ctx)
+            return (config.rewriteRequest as Service['rewriteRequest'])!(req, ctx)
+          }
+        : (config.rewriteRequest as Service['rewriteRequest'])
+      : rewriteFromConfig,
+  }
+}
+
+export declare namespace from {
+  export type Config<options = unknown> = {
+    /** Base URL of the upstream service. */
+    baseUrl: string
+    /** Shorthand: inject `Authorization: Bearer {token}` header. */
+    bearer?: string | undefined
+    /** Shorthand: inject custom headers. */
+    headers?: Record<string, string> | undefined
+    /** Shorthand: full request mutation function. Takes priority over `bearer`/`headers`. */
+    mutate?: ((req: Request) => Request | Promise<Request>) | undefined
+    /** Hook to modify the upstream request. Receives typed per-endpoint options via `ctx`. */
+    rewriteRequest?:
+      | ((req: Request, ctx: Context & Partial<options & {}>) => Request | Promise<Request>)
+      | undefined
+    /** Map of route patterns to endpoint definitions. */
+    routes: EndpointMap
+  }
+}
+
+export { from as custom }
+
+function resolveRewriteRequest(
+  config: from.Config,
+): ((req: Request, ctx: Context) => Request | Promise<Request>) | undefined {
+  if (config.mutate) {
+    const mutate = config.mutate
+    return (req, ctx) => {
+      const options = ctx as Partial<from.Config>
+      const m = options.mutate ?? mutate
+      return m(req)
+    }
+  }
+  if (config.bearer) {
+    const bearer = config.bearer
+    return (req, ctx) => {
+      const options = ctx as Partial<from.Config>
+      req.headers.set('Authorization', `Bearer ${options.bearer ?? bearer}`)
+      return req
+    }
+  }
+  if (config.headers) {
+    const headers = config.headers
+    return (req, ctx) => {
+      const options = ctx as Partial<from.Config>
+      const h = options.headers ?? headers
+      for (const [name, value] of Object.entries(h)) req.headers.set(name, value)
+      return req
+    }
+  }
+  return undefined
+}
+
+/** Serializes a service for discovery responses. */
+export function serialize(s: Service) {
+  return {
+    id: s.id,
+    baseUrl: s.baseUrl,
+    routes: Object.entries(s.routes).map(([pattern, endpoint]) => {
+      const tokens = pattern.trim().split(/\s+/)
+      const hasMethod = tokens.length >= 2
+      return {
+        method: hasMethod ? tokens[0] : undefined,
+        path: hasMethod ? tokens.slice(1).join(' ') : tokens[0],
+        pattern,
+        payment: endpoint ? resolvePayment(endpoint) : null,
+      }
+    }),
+  }
+}
+
+/** Renders an llms.txt markdown string for a list of services. */
+export function toLlmsTxt(services: Service[]): string {
+  const lines: string[] = [
+    '# API Proxy',
+    '',
+    '> Paid API proxy powered by [Machine Payments Protocol](https://mpp.tempo.xyz).',
+    '',
+    'For machine-readable service data, use `GET /services` (JSON).',
+    '',
+  ]
+
+  if (services.length === 0) return lines.join('\n')
+
+  lines.push('## Services', '')
+  for (const s of services) {
+    const serialized = serialize(s)
+    const free = serialized.routes.filter((r) => r.payment === null).length
+    const paid = serialized.routes.length - free
+    const parts = [paid && `${paid} paid`, free && `${free} free`].filter(Boolean).join(', ')
+    lines.push(`- [${s.id}](${s.baseUrl}): ${parts}`)
+  }
+
+  for (const s of services) {
+    const serialized = serialize(s)
+    lines.push('', `## ${s.id}`, '')
+    for (const route of serialized.routes) {
+      if (!route.payment) {
+        lines.push(`- \`${route.pattern}\`: Free`)
+        continue
+      }
+      const p = route.payment as Record<string, unknown>
+      const parts = [`${p.intent}`]
+      if (p.amount) {
+        const unit = `${p.amount} units`
+        parts.push(p.unitType ? `${unit} per ${p.unitType}` : unit)
+      }
+      if (p.description) parts.push(`"${p.description}"`)
+      const meta = [
+        p.currency && `currency: ${p.currency}`,
+        p.decimals !== undefined && `decimals: ${p.decimals}`,
+      ].filter(Boolean)
+      if (meta.length) parts.push(`(${meta.join(', ')})`)
+      lines.push(`- \`${route.pattern}\`: ${parts.join(' — ')}`)
+    }
+  }
+
+  return lines.join('\n')
+}
+
+/** Extracts per-endpoint options from an endpoint definition. */
+export function getOptions(endpoint: Endpoint): EndpointOptions | undefined {
+  if (typeof endpoint === 'object' && endpoint !== null && 'options' in endpoint)
+    return endpoint.options
+  return undefined
+}
+
+function resolvePayment(endpoint: Endpoint): Record<string, unknown> | null {
+  if (endpoint === true) return null
+  const handler = typeof endpoint === 'function' ? endpoint : endpoint.pay
+  if (!('_internal' in handler)) return {}
+  const { name, method, defaults, schema, ...rest } = handler._internal as Record<string, unknown>
+  const amount = (() => {
+    if (typeof rest.amount === 'string' && typeof rest.decimals === 'number')
+      return String(Value.from(rest.amount, rest.decimals))
+    return rest.amount
+  })()
+  return { intent: name, method, ...rest, ...(amount !== undefined && { amount }) }
+}

package/src/proxy/index.ts

@@ -0,0 +1,6 @@
+export * as Proxy from './Proxy.js'
+export * as Service from './Service.js'
+export { from as custom } from './Service.js'
+export { anthropic } from './services/anthropic.js'
+export { openai } from './services/openai.js'
+export { stripe } from './services/stripe.js'

package/src/proxy/internal/Headers.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from 'vitest'
+import * as Headers from './Headers.js'
+
+describe('scrub', () => {
+  test('behavior: strips authorization header', () => {
+    const headers = new globalThis.Headers({
+      Authorization: 'Bearer secret',
+      'Content-Type': 'application/json',
+    })
+    const result = Headers.scrub(headers)
+    expect(result.has('authorization')).toBe(false)
+    expect(result.get('content-type')).toBe('application/json')
+  })
+
+  test('behavior: strips cookie header', () => {
+    const headers = new globalThis.Headers({
+      Cookie: 'session=abc123',
+      Accept: 'text/html',
+    })
+    const result = Headers.scrub(headers)
+    expect(result.has('cookie')).toBe(false)
+    expect(result.get('accept')).toBe('text/html')
+  })
+
+  test('behavior: strips hop-by-hop headers', () => {
+    const headers = new globalThis.Headers({
+      Connection: 'keep-alive',
+      'Keep-Alive': 'timeout=5',
+      'Transfer-Encoding': 'chunked',
+      Upgrade: 'websocket',
+      'Proxy-Authenticate': 'Basic',
+      'Proxy-Authorization': 'Basic abc',
+      TE: 'trailers',
+      Trailer: 'Expires',
+      'Content-Type': 'application/json',
+    })
+    const result = Headers.scrub(headers)
+    expect(result.has('connection')).toBe(false)
+    expect(result.has('keep-alive')).toBe(false)
+    expect(result.has('transfer-encoding')).toBe(false)
+    expect(result.has('upgrade')).toBe(false)
+    expect(result.has('proxy-authenticate')).toBe(false)
+    expect(result.has('proxy-authorization')).toBe(false)
+    expect(result.has('te')).toBe(false)
+    expect(result.has('trailer')).toBe(false)
+    expect(result.get('content-type')).toBe('application/json')
+  })
+
+  test('behavior: strips x-forwarded-* headers', () => {
+    const headers = new globalThis.Headers({
+      'X-Forwarded-For': '127.0.0.1',
+      'X-Forwarded-Proto': 'https',
+      'X-Forwarded-Host': 'example.com',
+      Accept: '*/*',
+    })
+    const result = Headers.scrub(headers)
+    expect(result.has('x-forwarded-for')).toBe(false)
+    expect(result.has('x-forwarded-proto')).toBe(false)
+    expect(result.has('x-forwarded-host')).toBe(false)
+    expect(result.get('accept')).toBe('*/*')
+  })
+
+  test('behavior: preserves safe headers', () => {
+    const headers = new globalThis.Headers({
+      'Content-Type': 'application/json',
+      Accept: 'text/html',
+      'User-Agent': 'test-agent/1.0',
+      'X-Custom-Header': 'value',
+    })
+    const result = Headers.scrub(headers)
+    expect(result.get('content-type')).toBe('application/json')
+    expect(result.get('accept')).toBe('text/html')
+    expect(result.get('user-agent')).toBe('test-agent/1.0')
+    expect(result.get('x-custom-header')).toBe('value')
+  })
+})
+
+describe('scrubResponse', () => {
+  test('behavior: strips content-encoding and content-length', () => {
+    const response = new Response('body', {
+      headers: {
+        'Content-Encoding': 'gzip',
+        'Content-Length': '42',
+        'Content-Type': 'application/json',
+      },
+    })
+    const result = Headers.scrubResponse(response)
+    expect(result.headers.has('content-encoding')).toBe(false)
+    expect(result.headers.has('content-length')).toBe(false)
+    expect(result.headers.get('content-type')).toBe('application/json')
+  })
+
+  test('behavior: preserves status and body', async () => {
+    const response = new Response('hello', { status: 201, statusText: 'Created' })
+    const result = Headers.scrubResponse(response)
+    expect(result.status).toBe(201)
+    expect(result.statusText).toBe('Created')
+    expect(await result.text()).toBe('hello')
+  })
+})

package/src/proxy/internal/Headers.ts

@@ -0,0 +1,40 @@
+const hopByHopHeaders = new Set([
+  'connection',
+  'keep-alive',
+  'transfer-encoding',
+  'upgrade',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'te',
+  'trailer',
+])
+
+export function scrub(headers: Headers): Headers {
+  const scrubbed = new Headers()
+
+  for (const [name, value] of headers) {
+    const lower = name.toLowerCase()
+
+    if (lower === 'authorization') continue
+    if (lower === 'accept-encoding') continue
+    if (lower === 'content-length') continue
+    if (lower === 'cookie') continue
+    if (hopByHopHeaders.has(lower)) continue
+    if (lower.startsWith('x-forwarded-')) continue
+
+    scrubbed.append(name, value)
+  }
+
+  return scrubbed
+}
+
+export function scrubResponse(response: Response): Response {
+  const headers = new Headers(response.headers)
+  headers.delete('content-encoding')
+  headers.delete('content-length')
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  })
+}