mppx 0.8.17 → 0.8.18

package/src/proxy/Service.ts

@@ -1,280 +0,0 @@
-import * as Metadata from '../discovery/internal/Metadata.js'
-
-/** A proxied upstream service with route definitions and optional request/response hooks. */
-export type Service = {
-  /** Base URL of the upstream service (e.g. `'https://api.openai.com'`). */
-  baseUrl: string
-  /** Free-form service categories for discovery metadata. */
-  categories?: string[] | undefined
-  /** Short description of the service. */
-  description?: string | undefined
-  /** Structured service documentation links for discovery metadata. */
-  docs?: Docs | undefined
-  /** Unique identifier used as the URL prefix (e.g. `'openai'` → `/{id}/...`). */
-  id: string
-  /** Handles failed upstream attempts before the proxy returns a response. Retries do not re-verify payment. */
-  onUpstreamError?: UpstreamErrorHandler | undefined
-  /** 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
-  /** Map of route patterns to endpoint handlers. */
-  routes: EndpointMap
-  /** Human-readable title for the service (e.g. `'OpenAI'`). */
-  title?: string | undefined
-}
-
-export type Docs = {
-  apiReference?: string | undefined
-  homepage?: string | undefined
-  llms?: string | 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
-
-/** Context passed to an upstream error handler after a failed proxy attempt. */
-export type UpstreamErrorContext = Context & {
-  /** One-based upstream attempt number. */
-  attempt: number
-  /** Error thrown while preparing or sending the request. Undefined for HTTP error responses. */
-  error: unknown | undefined
-  /** Non-2xx upstream response. Undefined when the attempt threw. */
-  response: Response | undefined
-  /** Rewritten request sent to the upstream service. */
-  upstreamRequest: Request
-}
-
-/** Action returned by an upstream error handler. */
-export type UpstreamErrorAction =
-  | {
-      /** Wait this many milliseconds before retrying. */
-      delay?: number | undefined
-      retry: true
-    }
-  | {
-      /** Optional response to return instead of the original failure. */
-      response?: Response | undefined
-      retry: false
-    }
-
-/**
- * Handles a non-2xx upstream response or thrown request error.
- *
- * This hook runs before the response is returned. It cannot observe failures
- * from a streaming body after response headers have been sent.
- */
-export type UpstreamErrorHandler<options = unknown> = (
-  context: UpstreamErrorContext & Partial<Omit<options & {}, 'onUpstreamError' | 'routes'>>,
-) => UpstreamErrorAction | Promise<UpstreamErrorAction>
-
-export type From<
-  options extends {
-    routes: string
-  },
-> = {
-  routes: EndpointMap<options['routes']>
-} & Omit<options, 'onUpstreamError' | 'routes'> & {
-    onUpstreamError?: UpstreamErrorHandler<options> | undefined
-  }
-
-/**
- * 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 {
-    baseUrl: config.baseUrl,
-    categories: config.categories,
-    description: config.description,
-    docs: resolveDocs(config),
-    id,
-    onUpstreamError: config.onUpstreamError as Service['onUpstreamError'],
-    routes: config.routes,
-    title: config.title,
-    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
-    /** Free-form service categories for discovery metadata. */
-    categories?: string[] | undefined
-    /** Short description of the service. */
-    description?: string | undefined
-    /** Structured service documentation links for discovery metadata. */
-    docs?: Docs | undefined
-    /** Shorthand: inject custom headers. */
-    headers?: Record<string, string> | undefined
-    /** Documentation URL for the service. String for a static base URL, or a function receiving an optional endpoint pattern. */
-    docsLlmsUrl?:
-      | string
-      | ((options: { route?: string | undefined }) => string | undefined)
-      | undefined
-    /** Shorthand: full request mutation function. Takes priority over `bearer`/`headers`. */
-    mutate?: ((req: Request) => Request | Promise<Request>) | undefined
-    /** Handles failed upstream attempts before the proxy returns a response. Retries do not re-verify payment. */
-    onUpstreamError?: UpstreamErrorHandler<options> | 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
-    /** Human-readable title for the service. */
-    title?: string | undefined
-  }
-}
-
-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
-}
-
-/** Renders an llms.txt markdown string for a list of services. */
-export function toLlmsTxt(
-  services: Service[],
-  options?: {
-    description?: string | undefined
-    openApiPath?: string | undefined
-    title?: string | undefined
-  },
-): string {
-  const lines: string[] = [
-    `# ${options?.title ?? 'API Proxy'}`,
-    '',
-    `> ${options?.description ?? 'Paid API proxy powered by [Machine Payments Protocol](https://mpp.tempo.xyz).'}`,
-    '',
-  ]
-
-  if (services.length === 0) return lines.join('\n')
-
-  lines.push('## Services', '')
-  for (const s of services) {
-    const label = s.title ?? s.id
-    const desc = s.description ? `: ${s.description}` : ''
-    lines.push(`- ${label}${desc}`)
-  }
-  lines.push('', `[OpenAPI discovery](${options?.openApiPath ?? '/openapi.json'})`)
-
-  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
-}
-
-/** Derives discovery payment metadata from an explicitly priced endpoint handler. */
-export function paymentOf(endpoint: Endpoint): Record<string, unknown> | null {
-  if (endpoint === true) return null
-  const handler = typeof endpoint === 'function' ? endpoint : endpoint.pay
-  if (!('_internal' in handler)) return null
-  const metadata = handler._internal as Metadata.Metadata | undefined
-  if (!metadata) return null
-  if (Metadata.isComposed(metadata))
-    return { offers: Metadata.offers(metadata).map(Metadata.paymentOffer) }
-  return Metadata.paymentOffer(metadata)
-}
-
-function resolveDocs(config: from.Config): Docs | undefined {
-  if (config.docs) {
-    return {
-      ...config.docs,
-      ...(config.docs.llms ? {} : { llms: resolveLlmsFromLegacy(config.docsLlmsUrl) }),
-    }
-  }
-  const llms = resolveLlmsFromLegacy(config.docsLlmsUrl)
-  return llms ? { llms } : undefined
-}
-
-function resolveLlmsFromLegacy(
-  input: string | ((options: { route?: string | undefined }) => string | undefined) | undefined,
-): string | undefined {
-  if (!input) return undefined
-  if (typeof input === 'string') return input
-  return input({}) ?? undefined
-}

package/src/proxy/index.ts

@@ -1,6 +0,0 @@
-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

@@ -1,139 +0,0 @@
-import { describe, expect, test } from 'vp/test'
-
-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 payment protocol headers', () => {
-    const headers = new globalThis.Headers({
-      'Accept-Payment': 'evm/charge',
-      'Content-Type': 'application/json',
-      'PAYMENT-RECEIPT': 'receipt',
-      'PAYMENT-REQUIRED': 'required',
-      'PAYMENT-RESPONSE': 'response',
-      'PAYMENT-SIGNATURE': 'signature',
-      'WWW-Authenticate': 'Payment id="abc"',
-    })
-    const result = Headers.scrub(headers)
-    expect(result.has('accept-payment')).toBe(false)
-    expect(result.has('payment-receipt')).toBe(false)
-    expect(result.has('payment-required')).toBe(false)
-    expect(result.has('payment-response')).toBe(false)
-    expect(result.has('payment-signature')).toBe(false)
-    expect(result.has('www-authenticate')).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')
-  })
-
-  // Regression: an upstream service must never be able to issue a cookie
-  // under the proxy's origin. Otherwise a compromised or attacker-influenced
-  // upstream can session-fixate (`Set-Cookie: session=evil; Domain=…`) every
-  // sibling subdomain of the proxy. See the docblock on `scrubResponse`.
-  test('behavior: strips set-cookie so upstream cannot set cookies on proxy origin', () => {
-    const response = new Response('body', {
-      headers: [
-        ['Set-Cookie', '__Secure-session=evil; Domain=.example.com; Secure; HttpOnly'],
-        ['Set-Cookie', 'tracking=1; Path=/'],
-        ['Content-Type', 'application/json'],
-      ],
-    })
-    const result = Headers.scrubResponse(response)
-    expect(result.headers.has('set-cookie')).toBe(false)
-    expect(result.headers.getSetCookie?.() ?? []).toEqual([])
-    expect(result.headers.get('content-type')).toBe('application/json')
-  })
-})

package/src/proxy/internal/Headers.ts

@@ -1,66 +0,0 @@
-const hopByHopHeaders = new Set([
-  'connection',
-  'keep-alive',
-  'transfer-encoding',
-  'upgrade',
-  'proxy-authenticate',
-  'proxy-authorization',
-  'te',
-  'trailer',
-])
-
-// Payment credentials are consumed by the proxy and must never reach upstream services.
-const paymentHeaders = new Set([
-  'accept-payment',
-  'authorization',
-  'payment-receipt',
-  'payment-required',
-  'payment-response',
-  'payment-signature',
-  'www-authenticate',
-])
-
-/** Strips hop-by-hop, auth, encoding, cookie, and forwarding headers from a request before proxying upstream. */
-export function scrub(headers: Headers): Headers {
-  const scrubbed = new Headers()
-
-  for (const [name, value] of headers) {
-    const lower = name.toLowerCase()
-
-    if (paymentHeaders.has(lower)) 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
-}
-
-/**
- * Strips re-streaming headers (`content-encoding`, `content-length`) and
- * security-sensitive headers (`set-cookie`) from an upstream response.
- *
- * `set-cookie` is dropped because a paid API proxy must never let an upstream
- * service set cookies in the user's browser under the proxy's origin. If a
- * compromised, misbehaving, or attacker-influenced upstream returned
- * `Set-Cookie: session=evil; Domain=.example.com`, the browser would honor it
- * for every sibling subdomain of the proxy — turning any future path-confusion
- * or open-redirect bug in the surrounding deployment into a session-fixation
- * primitive. Proxied services authenticate via bearer tokens / signed
- * payloads, never cookies, so dropping `set-cookie` is purely defensive.
- */
-export function scrubResponse(response: Response): Response {
-  const headers = new Headers(response.headers)
-  headers.delete('content-encoding')
-  headers.delete('content-length')
-  headers.delete('set-cookie')
-  return new Response(response.body, {
-    status: response.status,
-    statusText: response.statusText,
-    headers,
-  })
-}