@atproto/lex-server 0.0.8 → 0.0.10

package/src/nodejs.ts

@@ -11,6 +11,7 @@ import {
 import { ListenOptions } from 'node:net'
 import { Readable } from 'node:stream'
 import { pipeline } from 'node:stream/promises'
+import type { ReadableStream as NodeReadableStream } from 'node:stream/web'
 import { createHttpTerminator } from 'http-terminator'
 import { WebSocket as WebSocketPonyfill, WebSocketServer } from 'ws'
 import { FetchHandler } from './lex-server.js'
@@ -28,6 +29,36 @@ function isUpgradeRequest(request: Request, upgrade: string): boolean {
   )
 }
 
+/**
+ * Upgrades an HTTP request to a WebSocket connection for Node.js.
+ *
+ * This function must be passed to the {@link LexRouter} constructor to enable
+ * subscription (WebSocket) support on Node.js. It creates a WebSocket instance
+ * and a placeholder response that signals the need for protocol upgrade.
+ *
+ * The actual upgrade is handled internally when the response is sent through
+ * {@link sendResponse}.
+ *
+ * @param request - The incoming HTTP request to upgrade
+ * @returns An object containing the WebSocket and upgrade response
+ * @throws {TypeError} If the request is not a valid WebSocket upgrade request
+ *
+ * @example
+ * ```typescript
+ * import { LexRouter } from '@atproto/lex-server'
+ * import { upgradeWebSocket } from '@atproto/lex-server/nodejs'
+ *
+ * // Pass to router for subscription support
+ * const router = new LexRouter({ upgradeWebSocket })
+ *
+ * // Now you can add subscription handlers
+ * router.add(subscribeRepos, async function* (ctx) {
+ *   for await (const event of eventStream) {
+ *     yield event
+ *   }
+ * })
+ * ```
+ */
 export function upgradeWebSocket(request: Request): {
   response: Response
   socket: WebSocket
@@ -106,6 +137,33 @@ function handleWebSocketUpgrade(
   })
 }
 
+/**
+ * Sends a fetch API Response through a Node.js ServerResponse.
+ *
+ * Handles both regular HTTP responses and WebSocket upgrades. For WebSocket
+ * upgrades (status 101), delegates to the WebSocket upgrade handler.
+ *
+ * This function is used internally by {@link toRequestListener} and
+ * {@link createServer}, but can be used directly for custom integrations.
+ *
+ * @param req - The Node.js IncomingMessage
+ * @param res - The Node.js ServerResponse to write to
+ * @param response - The fetch API Response to send
+ * @throws {TypeError} If headers have already been sent
+ *
+ * @example
+ * ```typescript
+ * import http from 'node:http'
+ * import { sendResponse } from '@atproto/lex-server/nodejs'
+ *
+ * const server = http.createServer(async (req, res) => {
+ *   const response = new Response('Hello, World!', {
+ *     headers: { 'Content-Type': 'text/plain' }
+ *   })
+ *   await sendResponse(req, res, response)
+ * })
+ * ```
+ */
 export async function sendResponse(
   req: IncomingMessage,
   res: ServerResponse,
@@ -128,7 +186,7 @@ export async function sendResponse(
   }
 
   if (response.body != null && req.method !== 'HEAD') {
-    const stream = Readable.fromWeb(response.body as any)
+    const stream = Readable.fromWeb(response.body as NodeReadableStream)
     await pipeline(stream, res)
   } else {
     await response.body?.cancel()
@@ -222,7 +280,7 @@ function toHeaders(headers: IncomingHttpHeaders): Headers {
   return result
 }
 
-function toBody(req: IncomingMessage): null | ReadableStream<Uint8Array> {
+function toBody(req: IncomingMessage): null | ReadableStream {
   if (
     req.method === 'GET' ||
     req.method === 'HEAD' ||
@@ -239,21 +297,53 @@ function toBody(req: IncomingMessage): null | ReadableStream<Uint8Array> {
     return null
   }
 
-  return Readable.toWeb(req) as ReadableStream<Uint8Array>
+  return Readable.toWeb(req) as ReadableStream
 }
 
+/**
+ * Network address type for Node.js TCP connections.
+ *
+ * @example
+ * ```typescript
+ * const addr: NetAddr = {
+ *   transport: 'tcp',
+ *   hostname: '192.168.1.100',
+ *   port: 54321
+ * }
+ * ```
+ */
 export type NetAddr = {
+  /** Always 'tcp' for Node.js HTTP connections. */
   transport: 'tcp'
+  /** The IP address of the remote client. */
   hostname: string
+  /** The port number of the remote client. */
   port: number
 }
 
+/**
+ * Connection metadata for Node.js HTTP requests.
+ *
+ * Provides information about the client connection, including the remote
+ * address and a promise that resolves when the connection is fully closed
+ * (including WebSocket connections).
+ */
 export type NodeConnectionInfo = {
+  /** Promise that resolves when the connection is fully closed. */
   completed: Promise<void>
+  /** The remote address of the client, if available. */
   remoteAddr: NetAddr | undefined
 }
 
+/**
+ * Interface for objects that can handle fetch-style requests.
+ *
+ * Used by {@link createServer} and {@link serve} to accept either
+ * a fetch handler function or an object with a `fetch` method
+ * (like {@link LexRouter}).
+ */
 export interface HandlerObject {
+  /** The fetch handler method. */
   fetch: FetchHandler
 }
 
@@ -284,6 +374,32 @@ function toConnectionInfo(req: IncomingMessage): NodeConnectionInfo {
   }
 }
 
+/**
+ * Converts a fetch-style handler to a Node.js request listener.
+ *
+ * The returned listener can be used with Node.js HTTP servers directly,
+ * or as middleware in frameworks like Express (supports the `next` callback).
+ *
+ * @typeParam Request - The request class type (default: IncomingMessage)
+ * @typeParam Response - The response class type (default: ServerResponse)
+ * @param fetchHandler - The fetch-style handler function
+ * @returns A Node.js RequestListener compatible with http.createServer
+ *
+ * @example Using as Express middleware
+ * ```typescript
+ * import express from 'express'
+ * import { toRequestListener } from '@atproto/lex-server/nodejs'
+ * import { LexRouter } from '@atproto/lex-server'
+ *
+ * const router = new LexRouter()
+ * // Register handlers...
+ *
+ * const app = express()
+ *
+ * // Mount the XRPC router
+ * app.use('/xrpc', toRequestListener(router.fetch))
+ * ```
+ */
 export function toRequestListener<
   Request extends typeof IncomingMessage = typeof IncomingMessage,
   Response extends typeof ServerResponse<
@@ -310,15 +426,54 @@ export function toRequestListener<
   }) satisfies RequestListener<Request, Response>
 }
 
+/**
+ * Options for creating an XRPC server.
+ *
+ * Extends Node.js {@link ServerOptions} with additional options for graceful shutdown.
+ */
 export type CreateServerOptions<
   Request extends typeof IncomingMessage = typeof IncomingMessage,
   Response extends typeof ServerResponse<
     InstanceType<Request>
   > = typeof ServerResponse,
 > = ServerOptions<Request, Response> & {
+  /**
+   * Timeout in milliseconds for graceful termination.
+   *
+   * When `terminate()` is called, the server will wait up to this duration
+   * for active connections to complete before forcibly closing them.
+   */
   gracefulTerminationTimeout?: number
 }
 
+/**
+ * Extended HTTP server with graceful shutdown support.
+ *
+ * Extends the standard Node.js HttpServer with a `terminate()` method
+ * for graceful shutdown and implements `AsyncDisposable` for use with
+ * `await using`.
+ *
+ * @typeParam Request - The request class type
+ * @typeParam Response - The response class type
+ *
+ * @example Graceful shutdown
+ * ```typescript
+ * const server = createServer(router)
+ * server.listen(3000)
+ *
+ * process.on('SIGTERM', async () => {
+ *   console.log('Shutting down...')
+ *   await server.terminate()
+ *   console.log('Server stopped')
+ * })
+ * ```
+ *
+ * @example Using with await using
+ * ```typescript
+ * await using server = await serve(router, { port: 3000 })
+ * // Server will be automatically terminated when scope exits
+ * ```
+ */
 export interface Server<
   Request extends typeof IncomingMessage = typeof IncomingMessage,
   Response extends typeof ServerResponse<
@@ -326,10 +481,56 @@ export interface Server<
   > = typeof ServerResponse,
 > extends HttpServer<Request, Response>,
     AsyncDisposable {
+  /**
+   * Gracefully terminates the server.
+   *
+   * Stops accepting new connections and waits for active connections
+   * to complete (up to `gracefulTerminationTimeout`).
+   *
+   * @returns Promise that resolves when the server is fully stopped
+   */
   terminate(): Promise<void>
   [Symbol.asyncDispose](): Promise<void>
 }
 
+/**
+ * Creates an HTTP server configured for XRPC request handling.
+ *
+ * The server includes graceful shutdown support and can be used with
+ * either a fetch handler function or an object with a `fetch` method
+ * (like {@link LexRouter}).
+ *
+ * Note: This creates the server but does not start listening. Call
+ * `server.listen()` to start the server, or use {@link serve} for
+ * a combined create-and-listen operation.
+ *
+ * @typeParam Request - The request class type
+ * @typeParam Response - The response class type
+ * @param handler - A fetch handler or object with fetch method
+ * @param options - Server configuration options
+ * @returns An HTTP server with graceful shutdown support
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { LexRouter } from '@atproto/lex-server'
+ * import { createServer, upgradeWebSocket } from '@atproto/lex-server/nodejs'
+ *
+ * const router = new LexRouter({ upgradeWebSocket })
+ * router.add(myMethod, myHandler)
+ *
+ * const server = createServer(router)
+ * server.listen(3000, () => {
+ *   console.log('Server listening on port 3000')
+ * })
+ * ```
+ *
+ * @example With graceful termination timeout
+ * ```typescript
+ * const server = createServer(router, {
+ *   gracefulTerminationTimeout: 10000 // 10 seconds
+ * })
+ * ```
+ */
 export function createServer<
   Request extends typeof IncomingMessage = typeof IncomingMessage,
   Response extends typeof ServerResponse<
@@ -375,6 +576,23 @@ export function createServer<
   return server as Server<Request, Response>
 }
 
+/**
+ * Combined options for creating and starting an XRPC server.
+ *
+ * Includes both server creation options and network listen options.
+ *
+ * @typeParam Request - The request class type
+ * @typeParam Response - The response class type
+ *
+ * @example
+ * ```typescript
+ * const options: StartServerOptions = {
+ *   port: 3000,
+ *   host: '0.0.0.0',
+ *   gracefulTerminationTimeout: 10000
+ * }
+ * ```
+ */
 export type StartServerOptions<
   Request extends typeof IncomingMessage = typeof IncomingMessage,
   Response extends typeof ServerResponse<
@@ -382,6 +600,67 @@ export type StartServerOptions<
   > = typeof ServerResponse,
 > = ListenOptions & CreateServerOptions<Request, Response>
 
+/**
+ * Creates and starts an HTTP server, returning when it's ready to accept connections.
+ *
+ * This is a convenience function that combines {@link createServer} and `server.listen()`
+ * into a single async operation. The returned promise resolves once the server
+ * is actively listening.
+ *
+ * @typeParam Request - The request class type
+ * @typeParam Response - The response class type
+ * @param handler - A fetch handler or object with fetch method (like {@link LexRouter})
+ * @param options - Combined server and listen options
+ * @returns Promise resolving to the running server
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { LexRouter } from '@atproto/lex-server'
+ * import { serve, upgradeWebSocket } from '@atproto/lex-server/nodejs'
+ *
+ * const router = new LexRouter({ upgradeWebSocket })
+ *
+ * // Register handlers
+ * router.add(getProfile, async (ctx) => {
+ *   return { body: await db.getProfile(ctx.params.actor) }
+ * })
+ *
+ * // Start server on port 3000
+ * const server = await serve(router, { port: 3000 })
+ * console.log('Server listening on port 3000')
+ *
+ * // Graceful shutdown
+ * process.on('SIGTERM', () => server.terminate())
+ * process.on('SIGINT', () => server.terminate())
+ * ```
+ *
+ * @example With all options
+ * ```typescript
+ * const server = await serve(router, {
+ *   port: 3000,
+ *   host: '0.0.0.0',
+ *   gracefulTerminationTimeout: 15000,
+ * })
+ * ```
+ *
+ * @example Using with await using (auto-cleanup)
+ * ```typescript
+ * async function main() {
+ *   await using server = await serve(router, { port: 3000 })
+ *
+ *   // Server is running...
+ *   console.log('Server listening on port 3000')
+ *
+ *   // Wait for termination signal
+ *   await Promise.race([
+ *     once(process, 'SIGINT'),
+ *     once(process, 'SIGTERM'),
+ *   ])
+ *
+ *   // Server will be automatically terminated when scope exits
+ * }
+ * ```
+ */
 export async function serve<
   Request extends typeof IncomingMessage = typeof IncomingMessage,
   Response extends typeof ServerResponse<

package/src/service-auth.ts

@@ -17,41 +17,150 @@ import { LexRouterAuth } from './lex-server.js'
 const BEARER_PREFIX = 'Bearer '
 
 /**
- * A function to check and record nonce uniqueness.
+ * Callback function to check and record nonce uniqueness.
+ *
+ * Used to prevent replay attacks by ensuring each nonce is only used once.
+ * The implementation must track nonces for at least the `maxAge` duration
+ * (default 5 minutes before and after the current time).
+ *
+ * @param nonce - The nonce string from the JWT token
+ * @returns Promise resolving to `true` if the nonce is unique (first time seen),
+ *          `false` if it has been seen before
+ *
+ * @example
+ * ```typescript
+ * // Using Redis for nonce tracking
+ * const checkNonce: UniqueNonceChecker = async (nonce) => {
+ *   const key = `nonce:${nonce}`
+ *   const result = await redis.setnx(key, '1')
+ *   if (result === 1) {
+ *     await redis.expire(key, 600) // 10 minutes TTL
+ *     return true
+ *   }
+ *   return false
+ * }
+ * ```
  */
 export type UniqueNonceChecker = (nonce: string) => Promise<boolean>
 
+/**
+ * Configuration options for AT Protocol service authentication.
+ *
+ * Service auth is used for server-to-server communication in the AT Protocol,
+ * where one service authenticates to another using signed JWT tokens tied to
+ * the caller's DID.
+ *
+ * @example
+ * ```typescript
+ * const options: ServiceAuthOptions = {
+ *   audience: 'did:web:api.example.com',
+ *   unique: async (nonce) => nonceStore.checkAndAdd(nonce),
+ *   maxAge: 300, // 5 minutes
+ *   // Optional DID resolver options
+ *   plcDirectoryUrl: 'https://plc.directory'
+ * }
+ * ```
+ */
 export type ServiceAuthOptions = CreateDidResolverOptions & {
   /**
-   * Expected audience ("aud") claim in the JWT token. Set to `null` to skip
-   * audience verification (not recommended).
+   * Expected audience ("aud") claim in the JWT token.
+   *
+   * This should be the DID of your service. The token must include this
+   * value in its `aud` claim to be accepted. Set to `null` to skip
+   * audience verification (not recommended for production).
    */
   audience: null | DidString
   /**
-   * Function to check and record nonce uniqueness. The value checked here must
-   * be unique within {@link ServiceAuthOptions.maxAge} seconds before and after
-   * the current time.
+   * Function to check and record nonce uniqueness.
    *
-   * @param nonce - The nonce to check.
+   * This is critical for preventing replay attacks. The value checked here
+   * must be unique within `maxAge` seconds before and after the current time.
+   *
+   * @param nonce - The nonce to check
+   * @returns Promise resolving to `true` if unique, `false` if seen before
    */
   unique: UniqueNonceChecker
   /**
    * Maximum age of the JWT token in seconds.
    *
+   * Tokens with `iat` (issued at) or `exp` (expiry) timestamps outside
+   * this window from the current time will be rejected.
+   *
    * @default 300 (5 minutes)
    */
   maxAge?: number
 }
 
+/**
+ * Credentials returned after successful service authentication.
+ *
+ * Contains the verified DID, resolved DID document, and parsed JWT token.
+ * These are available in handler context as `ctx.credentials`.
+ *
+ * @example
+ * ```typescript
+ * router.add(protectedMethod, {
+ *   handler: async (ctx) => {
+ *     const { did, didDocument, jwt } = ctx.credentials
+ *     console.log('Request from:', did)
+ *     console.log('Token expires:', new Date(jwt.payload.exp * 1000))
+ *     return { body: { callerDid: did } }
+ *   },
+ *   auth: serviceAuth({ audience: myDid, unique: checkNonce })
+ * })
+ * ```
+ */
 export type ServiceAuthCredentials = {
+  /** The verified AT Protocol DID of the caller. */
   did: AtprotoDid
+  /** The resolved DID document of the caller. */
   didDocument: AtprotoDidDocument
+  /** The parsed and validated JWT token. */
   jwt: ParsedJwt
 }
 
 /**
- * Creates an authentication handler for LexRouter that verifies AT protocol
- * "service auth" JWT bearer tokens signed by decentralized identifiers (DIDs).
+ * Creates an authentication handler for verifying AT Protocol service auth JWTs.
+ *
+ * Service auth is the standard authentication mechanism for server-to-server
+ * communication in the AT Protocol. It uses JWT bearer tokens signed by the
+ * caller's DID signing key, with the signature verified against the public
+ * key in the caller's DID document.
+ *
+ * The handler performs the following validations:
+ * - Extracts and parses the Bearer token from the Authorization header
+ * - Validates JWT structure and claims (aud, exp, iat, lxm, nonce)
+ * - Resolves the issuer's DID document
+ * - Verifies the JWT signature against the `#atproto` verification method
+ * - Checks nonce uniqueness to prevent replay attacks
+ *
+ * @param options - Configuration options for service auth
+ * @returns An auth handler function for use with {@link LexRouter.add}
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { LexRouter, serviceAuth } from '@atproto/lex-server'
+ *
+ * const router = new LexRouter()
+ *
+ * const auth = serviceAuth({
+ *   audience: 'did:web:api.example.com',
+ *   unique: async (nonce) => {
+ *     // Check if nonce has been seen, return true if unique
+ *     const isNew = await redis.setnx(`nonce:${nonce}`, '1')
+ *     if (isNew) await redis.expire(`nonce:${nonce}`, 600)
+ *     return isNew
+ *   }
+ * })
+ *
+ * router.add(myMethod, {
+ *   handler: async (ctx) => {
+ *     console.log('Authenticated as:', ctx.credentials.did)
+ *     return { body: { success: true } }
+ *   },
+ *   auth
+ * })
+ * ```
  */
 export function serviceAuth({
   audience,
@@ -190,17 +299,50 @@ async function parseJwtBearer(
   return parseJwt(token, options)
 }
 
+/**
+ * Options for parsing and validating a JWT token.
+ */
 export type ParseJwtOptions = {
+  /** Maximum age in seconds for token validity window. */
   maxAge: number
+  /** Expected audience claim, or null to skip audience verification. */
   audience: null | DidString
+  /** Function to check nonce uniqueness. */
   unique: UniqueNonceChecker
+  /** Expected lexicon method NSID for the `lxm` claim. */
   lxm: string
 }
 
+/**
+ * A parsed and partially validated JWT token.
+ *
+ * Contains the decoded header and payload, along with the raw bytes
+ * needed for signature verification.
+ *
+ * @example
+ * ```typescript
+ * const jwt: ParsedJwt = {
+ *   header: { alg: 'ES256K', typ: 'JWT' },
+ *   payload: {
+ *     iss: 'did:plc:abc123',
+ *     aud: 'did:web:api.example.com',
+ *     exp: 1704067200,
+ *     iat: 1704066900,
+ *     lxm: 'com.atproto.sync.getBlob'
+ *   },
+ *   message: new Uint8Array([...]),
+ *   signature: new Uint8Array([...])
+ * }
+ * ```
+ */
 export type ParsedJwt = {
+  /** The decoded JWT header containing algorithm and type. */
   header: HeaderObject
+  /** The decoded JWT payload containing claims. */
   payload: PayloadObject
+  /** The raw header.payload bytes for signature verification. */
   message: Uint8Array
+  /** The decoded signature bytes. */
   signature: Uint8Array
 }