mppx 0.0.1 → 0.1.0

package/src/server/Request.ts

@@ -0,0 +1,33 @@
+import type { IncomingMessage, RequestListener, ServerResponse } from 'node:http'
+import * as FetchServer from '@remix-run/node-fetch-server'
+
+export type FetchHandler = (request: Request) => Promise<Response> | Response
+
+/**
+ * Converts a Fetch API handler into a Node.js HTTP request listener.
+ *
+ * Uses [`@remix-run/node-fetch-server`](https://github.com/remix-run/remix/blob/main/packages/node-fetch-server/src/lib/request-listener.ts).
+ *
+ * @param handler - A Fetch API handler: `(request: Request) => Response`.
+ * @param options - Optional error handler.
+ * @returns A Node.js `(req, res)` listener.
+ */
+export function toNodeListener(
+  handler: FetchHandler,
+  options?: FetchServer.RequestListenerOptions | undefined,
+): RequestListener {
+  return FetchServer.createRequestListener(handler, options) as never
+}
+
+/**
+ * Converts a Node.js `IncomingMessage`/`ServerResponse` pair to a Fetch API `Request`.
+ *
+ * Uses [`@remix-run/node-fetch-server`](https://github.com/remix-run/remix/blob/main/packages/node-fetch-server/src/lib/request-listener.ts).
+ *
+ * @param req - The Node.js IncomingMessage.
+ * @param res - The Node.js ServerResponse (used for abort signal lifecycle).
+ * @returns A Fetch API Request.
+ */
+export function fromNodeListener(req: IncomingMessage, res: ServerResponse): Request {
+  return FetchServer.createRequest(req, res)
+}

package/src/server/Response.test.ts

@@ -0,0 +1,31 @@
+import { Challenge } from 'mppx'
+import { Response } from 'mppx/server'
+import { describe, expect, test } from 'vitest'
+import * as Errors from '../Errors.js'
+
+const challenge = Challenge.from({
+  id: 'abc123',
+  intent: 'charge',
+  method: 'tempo',
+  realm: 'api.example.com',
+  request: { amount: '1000000' },
+})
+
+describe('requirePayment', () => {
+  test('returns 402 Response with WWW-Authenticate header', () => {
+    const response = Response.requirePayment({ challenge })
+
+    expect(response.status).toBe(402)
+    expect(response.headers.get('WWW-Authenticate')).toBe(Challenge.serialize(challenge))
+  })
+
+  test('includes problem details in body when error provided', async () => {
+    const error = new Errors.PaymentRequiredError()
+
+    const response = Response.requirePayment({ challenge, error })
+
+    expect(response.headers.get('Content-Type')).toBe('application/problem+json')
+    const body = await response.json()
+    expect(body).toEqual(error.toProblemDetails(challenge.id))
+  })
+})

package/src/server/Response.ts

@@ -0,0 +1,27 @@
+import * as Challenge from '../Challenge.js'
+import type * as Errors from '../Errors.js'
+
+export function requirePayment(parameters: requirePayment.Parameters): Response {
+  const { challenge, error } = parameters
+
+  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))
+  }
+
+  return new Response(body, { status: 402, headers })
+}
+
+export declare namespace requirePayment {
+  type Parameters = {
+    challenge: Challenge.Challenge
+    error?: Errors.PaymentError | undefined
+  }
+}

package/src/server/Transport.test.ts

@@ -0,0 +1,294 @@
+import { Challenge, Credential, Mcp, Receipt } from 'mppx'
+import { Transport } from 'mppx/server'
+import { MethodIntents as Intents } from 'mppx/tempo'
+import { describe, expect, test } from 'vitest'
+import { BadRequestError, ChannelClosedError } from '../Errors.js'
+
+const realm = 'api.example.com'
+const secretKey = 'test-secret-key'
+
+const challenge = Challenge.fromIntent(Intents.charge, {
+  realm,
+  secretKey,
+  request: {
+    amount: '1000',
+    currency: '0x20c0000000000000000000000000000000000001',
+    decimals: 6,
+    recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
+    expires: '2025-01-01T00:00:00.000Z',
+  },
+})
+
+const credential = Credential.from({
+  challenge,
+  payload: { signature: '0xabc123', type: 'transaction' },
+})
+
+const receipt = Receipt.from({
+  method: 'tempo',
+  status: 'success',
+  timestamp: '2025-01-01T00:00:00.000Z',
+  reference: '0xtxhash',
+})
+
+describe('http', () => {
+  describe('getCredential', () => {
+    test('returns credential from Authorization header', () => {
+      const transport = Transport.http()
+      const request = new Request('https://example.com', {
+        headers: { Authorization: Credential.serialize(credential) },
+      })
+
+      expect(transport.getCredential(request)).toMatchInlineSnapshot(`
+        {
+          "challenge": {
+            "expires": "2025-01-01T00:00:00.000Z",
+            "id": "jIuTUdphF_TyhJ-NT1lK2r5YzPXw4tuELfslOVa3nls",
+            "intent": "charge",
+            "method": "tempo",
+            "realm": "api.example.com",
+            "request": {
+              "amount": "1000000000",
+              "currency": "0x20c0000000000000000000000000000000000001",
+              "expires": "2025-01-01T00:00:00.000Z",
+              "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
+            },
+          },
+          "payload": {
+            "signature": "0xabc123",
+            "type": "transaction",
+          },
+        }
+      `)
+    })
+
+    test('returns null when no Authorization header', () => {
+      const transport = Transport.http()
+      const request = new Request('https://example.com')
+
+      expect(transport.getCredential(request)).toBeNull()
+    })
+
+    test('returns null when no Payment scheme present', () => {
+      const transport = Transport.http()
+      const request = new Request('https://example.com', {
+        headers: { Authorization: 'Bearer invalid' },
+      })
+
+      expect(transport.getCredential(request)).toBeNull()
+    })
+  })
+
+  describe('respondChallenge', () => {
+    test('default', async () => {
+      const transport = Transport.http()
+      const request = new Request('https://example.com')
+
+      const response = await transport.respondChallenge({ challenge, input: request })
+
+      expect({
+        status: response.status,
+        headers: Object.fromEntries(response.headers),
+      }).toMatchInlineSnapshot(`
+        {
+          "headers": {
+            "cache-control": "no-store",
+            "www-authenticate": "Payment id="jIuTUdphF_TyhJ-NT1lK2r5YzPXw4tuELfslOVa3nls", realm="api.example.com", method="tempo", intent="charge", request="eyJjdXJyZW5jeSI6IjB4MjBjMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMSIsImV4cGlyZXMiOiIyMDI1LTAxLTAxVDAwOjAwOjAwLjAwMFoiLCJyZWNpcGllbnQiOiIweDc0MmQzNUNjNjYzNEMwNTMyOTI1YTNiODQ0QmM5ZTc1OTVmOGZFMDAiLCJhbW91bnQiOiIxMDAwMDAwMDAwIn0", expires="2025-01-01T00:00:00.000Z"",
+          },
+          "status": 402,
+        }
+      `)
+    })
+  })
+
+  describe('respondChallenge with error status codes', () => {
+    test('BadRequestError returns 400', async () => {
+      const transport = Transport.http()
+      const request = new Request('https://example.com')
+      const error = new BadRequestError({ reason: 'invalid parameters' })
+
+      const response = await transport.respondChallenge({ challenge, input: request, error })
+
+      expect(response.status).toBe(400)
+      const body = await response.json()
+      expect(body.type).toBe('https://tempoxyz.github.io/payment-auth-spec/problems/bad-request')
+      expect(body.status).toBe(400)
+    })
+
+    test('ChannelClosedError returns 410', async () => {
+      const transport = Transport.http()
+      const request = new Request('https://example.com')
+      const error = new ChannelClosedError({ reason: 'channel finalized' })
+
+      const response = await transport.respondChallenge({ challenge, input: request, error })
+
+      expect(response.status).toBe(410)
+      const body = await response.json()
+      expect(body.type).toBe('https://paymentauth.org/problems/stream/channel-finalized')
+      expect(body.status).toBe(410)
+    })
+  })
+
+  describe('respondReceipt', () => {
+    test('default', () => {
+      const transport = Transport.http()
+      const originalResponse = new Response('OK', { status: 200 })
+
+      const response = transport.respondReceipt({
+        receipt,
+        response: originalResponse,
+        challengeId: challenge.id,
+      })
+
+      expect({
+        status: response.status,
+        headers: Object.fromEntries(response.headers),
+      }).toMatchInlineSnapshot(`
+        {
+          "headers": {
+            "content-type": "text/plain;charset=UTF-8",
+            "payment-receipt": "eyJtZXRob2QiOiJ0ZW1wbyIsInJlZmVyZW5jZSI6IjB4dHhoYXNoIiwic3RhdHVzIjoic3VjY2VzcyIsInRpbWVzdGFtcCI6IjIwMjUtMDEtMDFUMDA6MDA6MDAuMDAwWiJ9",
+          },
+          "status": 200,
+        }
+      `)
+    })
+  })
+})
+
+describe('mcp', () => {
+  const mcpRequest: Mcp.JsonRpcRequest = {
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'tools/call',
+    params: {
+      name: 'test-tool',
+    },
+  }
+
+  describe('getCredential', () => {
+    test('returns credential from _meta', () => {
+      const transport = Transport.mcp()
+      const request: Mcp.JsonRpcRequest = {
+        ...mcpRequest,
+        params: {
+          ...mcpRequest.params,
+          _meta: {
+            [Mcp.credentialMetaKey]: credential,
+          },
+        },
+      }
+
+      expect(transport.getCredential(request)).toMatchInlineSnapshot(`
+        {
+          "challenge": {
+            "expires": "2025-01-01T00:00:00.000Z",
+            "id": "jIuTUdphF_TyhJ-NT1lK2r5YzPXw4tuELfslOVa3nls",
+            "intent": "charge",
+            "method": "tempo",
+            "realm": "api.example.com",
+            "request": {
+              "amount": "1000000000",
+              "currency": "0x20c0000000000000000000000000000000000001",
+              "expires": "2025-01-01T00:00:00.000Z",
+              "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
+            },
+          },
+          "payload": {
+            "signature": "0xabc123",
+            "type": "transaction",
+          },
+        }
+      `)
+    })
+
+    test('returns null when no credential in _meta', () => {
+      const transport = Transport.mcp()
+
+      expect(transport.getCredential(mcpRequest)).toBeNull()
+    })
+  })
+
+  describe('respondChallenge', () => {
+    test('default', () => {
+      const transport = Transport.mcp()
+
+      expect(transport.respondChallenge({ challenge, input: mcpRequest })).toMatchInlineSnapshot(`
+        {
+          "error": {
+            "code": -32042,
+            "data": {
+              "challenges": [
+                {
+                  "expires": "2025-01-01T00:00:00.000Z",
+                  "id": "jIuTUdphF_TyhJ-NT1lK2r5YzPXw4tuELfslOVa3nls",
+                  "intent": "charge",
+                  "method": "tempo",
+                  "realm": "api.example.com",
+                  "request": {
+                    "amount": "1000000000",
+                    "currency": "0x20c0000000000000000000000000000000000001",
+                    "expires": "2025-01-01T00:00:00.000Z",
+                    "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
+                  },
+                },
+              ],
+              "httpStatus": 402,
+            },
+            "message": "Payment Required",
+          },
+          "id": 1,
+          "jsonrpc": "2.0",
+        }
+      `)
+    })
+  })
+
+  describe('respondReceipt', () => {
+    test('default', () => {
+      const transport = Transport.mcp()
+      const successResponse: Mcp.Response = {
+        jsonrpc: '2.0',
+        id: 1,
+        result: { content: [] },
+      }
+
+      expect(
+        transport.respondReceipt({ receipt, response: successResponse, challengeId: challenge.id }),
+      ).toMatchInlineSnapshot(`
+        {
+          "id": 1,
+          "jsonrpc": "2.0",
+          "result": {
+            "_meta": {
+              "org.paymentauth/receipt": {
+                "challengeId": "jIuTUdphF_TyhJ-NT1lK2r5YzPXw4tuELfslOVa3nls",
+                "method": "tempo",
+                "reference": "0xtxhash",
+                "status": "success",
+                "timestamp": "2025-01-01T00:00:00.000Z",
+              },
+            },
+            "content": [],
+          },
+        }
+      `)
+    })
+
+    test('returns error response unchanged', () => {
+      const transport = Transport.mcp()
+      const errorResponse: Mcp.Response = {
+        jsonrpc: '2.0',
+        id: 1,
+        error: {
+          code: -32600,
+          message: 'Invalid Request',
+        },
+      }
+
+      expect(
+        transport.respondReceipt({ receipt, response: errorResponse, challengeId: challenge.id }),
+      ).toBe(errorResponse)
+    })
+  })
+})

package/src/server/Transport.ts

@@ -0,0 +1,222 @@
+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'
+
+export { type McpSdk, mcpSdk } from '../mcp-sdk/server/Transport.js'
+
+/**
+ * Server-side transport adapter.
+ *
+ * Abstracts how challenges are issued and credentials are received
+ * across different transport protocols (HTTP, MCP, etc.).
+ */
+export type Transport<
+  in out input = unknown,
+  in out challengeOutput = unknown,
+  in receiptResponse = challengeOutput,
+  out receiptOutput = receiptResponse,
+> = {
+  /** Transport name for identification. */
+  name: string
+  /**
+   * Extracts credential from the transport input.
+   * Returns `null` if no credential was provided, or throws if malformed.
+   */
+  getCredential: (input: input) => Credential.Credential | null
+  /** Creates a transport response for a payment challenge. */
+  respondChallenge: (options: {
+    challenge: Challenge.Challenge
+    error?: Errors.PaymentError | undefined
+    input: input
+  }) => challengeOutput | Promise<challengeOutput>
+  /** Attaches a receipt to a successful response. */
+  respondReceipt: (options: {
+    challengeId: string
+    receipt: Receipt.Receipt
+    response: receiptResponse
+  }) => receiptOutput
+}
+export type AnyTransport = Transport<any, any, any, any>
+
+export type Http = Transport<Request, Response>
+
+export type Mcp = Transport<core_Mcp.JsonRpcRequest, core_Mcp.Response>
+
+export type Sse<stream = any> = Transport<
+  Request,
+  Response,
+  Response | AsyncIterable<string> | ((stream: stream) => AsyncIterable<string>),
+  Response
+>
+
+/** Extracts the input type from a transport. */
+export type InputOf<transport extends AnyTransport = AnyTransport> =
+  transport extends Transport<infer input, any, any> ? input : never
+
+/** Extracts the challenge output type from a transport. */
+export type ChallengeOutputOf<transport extends AnyTransport = AnyTransport> =
+  transport extends Transport<any, infer challengeOutput, any> ? challengeOutput : never
+
+/** Extracts the receipt output type from a transport. */
+export type ReceiptResponseOf<transport extends AnyTransport = AnyTransport> =
+  transport extends Transport<any, any, infer response, any> ? response : never
+
+/** Extracts the resolved receipt type (return type of respondReceipt). */
+export type ReceiptOutputOf<transport extends AnyTransport = AnyTransport> =
+  transport extends Transport<any, any, any, infer output> ? output : never
+
+/**
+ * The `withReceipt` overload set for a given transport.
+ *
+ * Produces one overload per union member of `ReceiptOutputOf<transport>`,
+ * so TypeScript can contextually type generator function parameters.
+ */
+export type WithReceipt<transport extends AnyTransport = Http> = WithReceiptOverloads<transport>
+
+/**
+ * Creates a custom server-side transport.
+ *
+ * @example
+ * ```ts
+ * import { Transport } from 'mppx/server'
+ *
+ * const custom = Transport.from({
+ *   name: 'custom',
+ *   getCredential(input) { ... },
+ *   respondChallenge({ challenge, input }) { ... },
+ *   respondReceipt({ receipt, response, challengeId }) { ... },
+ * })
+ * ```
+ */
+export function from<
+  input = unknown,
+  challengeOutput = unknown,
+  receiptOutput = challengeOutput,
+  receiptResolved = receiptOutput,
+>(
+  transport: Transport<input, challengeOutput, receiptOutput, receiptResolved>,
+): Transport<input, challengeOutput, receiptOutput, receiptResolved> {
+  return transport
+}
+
+/**
+ * HTTP transport for server-side payment handling.
+ *
+ * - Reads credentials from the `Authorization` header
+ * - Issues challenges via `WWW-Authenticate` header with 402 status
+ * - Attaches receipts via `Payment-Receipt` header
+ */
+export function http(): Http {
+  return from<Request, Response>({
+    name: 'http',
+
+    getCredential(request) {
+      const header = request.headers.get('Authorization')
+      if (!header) return null
+      const payment = Credential.extractPaymentScheme(header)
+      if (!payment) return null
+      return Credential.deserialize(payment)
+    },
+
+    respondChallenge({ challenge, error }) {
+      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))
+      }
+
+      return new Response(body, { status: error?.status ?? 402, headers })
+    },
+
+    respondReceipt({ receipt, response }) {
+      const headers = new Headers(response.headers)
+      headers.set('Payment-Receipt', Receipt.serialize(receipt))
+      return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+      })
+    },
+  })
+}
+
+/**
+ * MCP transport for server-side payment handling with raw JSON-RPC.
+ *
+ * - Reads credentials from `_meta["org.paymentauth/credential"]`
+ * - Issues challenges via JSON-RPC error with code -32042/-32043
+ * - Attaches receipts via `_meta["org.paymentauth/receipt"]`
+ *
+ * Use this transport when handling raw JSON-RPC messages directly.
+ * For use with `@modelcontextprotocol/sdk`, use `mcpSdk()` instead.
+ */
+export function mcp() {
+  return from<core_Mcp.JsonRpcRequest, core_Mcp.Response>({
+    name: 'mcp',
+
+    getCredential(request) {
+      const meta = request.params?._meta
+      const credential = meta?.[core_Mcp.credentialMetaKey]
+      if (!credential) return null
+      return credential
+    },
+
+    respondChallenge({ challenge, input, error }) {
+      return {
+        jsonrpc: '2.0',
+        id: input.id,
+        error: {
+          code: mcpErrorCode(error),
+          message: error?.message ?? 'Payment Required',
+          data: {
+            httpStatus: error?.status ?? 402,
+            challenges: [challenge],
+            ...(error && { problem: error.toProblemDetails(challenge.id) }),
+          },
+        },
+      }
+    },
+
+    respondReceipt({ receipt, response, challengeId }) {
+      if ('error' in response) return response
+
+      const mcpReceipt: core_Mcp.Receipt = {
+        ...receipt,
+        challengeId,
+      }
+
+      return {
+        ...response,
+        result: {
+          ...response.result,
+          _meta: {
+            ...response.result._meta,
+            [core_Mcp.receiptMetaKey]: mcpReceipt,
+          },
+        },
+      }
+    },
+  })
+}
+
+/** @internal */
+function mcpErrorCode(error?: Errors.PaymentError): number {
+  if (!error) return core_Mcp.paymentRequiredCode
+  if (error instanceof Errors.MalformedCredentialError) return -32602
+  if (error instanceof Errors.PaymentRequiredError) return core_Mcp.paymentRequiredCode
+  return core_Mcp.paymentVerificationFailedCode
+}
+
+/** @internal Distributes over the receipt response union to create overloads. */
+type WithReceiptOverloads<transport extends AnyTransport = Http> = {
+  // biome-ignore lint/style/useShorthandFunctionType: _
+  (): ReceiptOutputOf<transport>
+} & UnionToIntersection<Distribute<ReceiptResponseOf<transport>, ReceiptOutputOf<transport>>>

package/src/server/index.ts

@@ -0,0 +1,8 @@
+export * as Expires from '../Expires.js'
+export * as Store from '../Store.js'
+export { stripe, tempo } from './Methods.js'
+export * as Mppx from './Mppx.js'
+export * as NodeListener from './NodeListener.js'
+export * as Request from './Request.js'
+export * as Response from './Response.js'
+export * as Transport from './Transport.js'