@agentlip/hub 0.1.0

package/src/authMiddleware.ts

@@ -0,0 +1,134 @@
+/**
+ * Auth middleware utilities for HTTP mutations + WebSocket token validation.
+ * 
+ * Security requirements:
+ * - All token comparisons use constant-time comparison (prevent timing attacks)
+ * - Tokens are NEVER echoed in error responses or logs
+ * - Generic error messages that don't leak token info
+ */
+
+import { constantTimeEqual } from "./authToken";
+
+/**
+ * Parse Bearer token from Authorization header.
+ * Returns the token string if valid "Bearer <token>" format, null otherwise.
+ * 
+ * Does NOT log or include the token in any error state.
+ */
+export function parseBearerToken(req: Request): string | null {
+  const authHeader = req.headers.get("Authorization");
+  if (!authHeader) {
+    return null;
+  }
+
+  // Must be "Bearer <token>" format (case-insensitive "Bearer")
+  const match = authHeader.match(/^Bearer\s+(.+)$/i);
+  if (!match) {
+    return null;
+  }
+
+  const token = match[1];
+  // Reject empty or whitespace-only tokens
+  if (!token || token.trim().length === 0) {
+    return null;
+  }
+
+  return token;
+}
+
+export type AuthOk = { ok: true };
+export type AuthFailure = { ok: false; response: Response };
+export type AuthResult = AuthOk | AuthFailure;
+
+/**
+ * Require valid Bearer token auth for HTTP requests.
+ * 
+ * Uses constant-time comparison to prevent timing attacks.
+ * Returns generic 401 response on failure (no token info leaked).
+ * 
+ * @param req - Incoming HTTP request
+ * @param expectedToken - The valid auth token (from server.json)
+ * @returns { ok: true } on success, { ok: false, response: Response } on failure
+ */
+export function requireAuth(req: Request, expectedToken: string): AuthResult {
+  const providedToken = parseBearerToken(req);
+
+  if (providedToken === null) {
+    return {
+      ok: false,
+      response: new Response(
+        JSON.stringify({
+          error: "Unauthorized",
+          code: "MISSING_AUTH",
+        }),
+        {
+          status: 401,
+          headers: { "Content-Type": "application/json" },
+        }
+      ),
+    };
+  }
+
+  // Constant-time comparison prevents timing attacks
+  if (!constantTimeEqual(providedToken, expectedToken)) {
+    return {
+      ok: false,
+      response: new Response(
+        JSON.stringify({
+          error: "Unauthorized",
+          code: "INVALID_AUTH",
+        }),
+        {
+          status: 401,
+          headers: { "Content-Type": "application/json" },
+        }
+      ),
+    };
+  }
+
+  return { ok: true };
+}
+
+export type WsAuthOk = { ok: true };
+export type WsAuthFailure = { ok: false; closeCode: number; closeReason: string };
+export type WsAuthResult = WsAuthOk | WsAuthFailure;
+
+/**
+ * Require valid token query param for WebSocket connections.
+ * 
+ * WebSocket auth uses ?token=<value> query parameter since
+ * browsers cannot set custom headers on WebSocket connections.
+ * 
+ * Uses constant-time comparison to prevent timing attacks.
+ * Returns close code/reason on failure (no token info leaked).
+ * 
+ * Close codes:
+ * - 4001: Missing token
+ * - 4003: Invalid token (Forbidden)
+ * 
+ * @param url - WebSocket connection URL
+ * @param expectedToken - The valid auth token (from server.json)
+ * @returns { ok: true } on success, { ok: false, closeCode, closeReason } on failure
+ */
+export function requireWsToken(url: URL, expectedToken: string): WsAuthResult {
+  const providedToken = url.searchParams.get("token");
+
+  if (providedToken === null || providedToken.trim().length === 0) {
+    return {
+      ok: false,
+      closeCode: 4001,
+      closeReason: "Missing authentication token",
+    };
+  }
+
+  // Constant-time comparison prevents timing attacks
+  if (!constantTimeEqual(providedToken, expectedToken)) {
+    return {
+      ok: false,
+      closeCode: 4003,
+      closeReason: "Invalid authentication token",
+    };
+  }
+
+  return { ok: true };
+}

package/src/authToken.ts

@@ -0,0 +1,32 @@
+import { randomBytes } from "node:crypto";
+
+/**
+ * Generate a cryptographically random auth token.
+ * 
+ * Generates >=128-bit entropy token (32 bytes = 256 bits).
+ * Returns 64-character hex string.
+ * 
+ * Never log this token.
+ */
+export function generateAuthToken(): string {
+  return randomBytes(32).toString("hex");
+}
+
+/**
+ * Constant-time string comparison helper for auth token validation.
+ * Prevents timing attacks.
+ * 
+ * Returns true if strings are equal, false otherwise.
+ */
+export function constantTimeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+
+  return result === 0;
+}

package/src/bodyParser.ts

@@ -0,0 +1,272 @@
+/**
+ * Input validation and size limit utilities for HTTP and WebSocket.
+ *
+ * Provides safe JSON body parsing with:
+ * - Configurable byte limits
+ * - Proper error handling (no user content echoed in errors)
+ * - Validation helpers
+ *
+ * Size limits from plan (0.1.2 Safe Defaults):
+ * - HTTP message content: 64KB
+ * - Attachment metadata: 16KB
+ * - WS message: 256KB
+ */
+
+/**
+ * Size limit constants (bytes).
+ */
+export const SIZE_LIMITS = {
+  /** Max message content: 64KB */
+  MESSAGE_BODY: 64 * 1024,
+  /** Max attachment metadata: 16KB */
+  ATTACHMENT: 16 * 1024,
+  /** Max WebSocket message: 256KB */
+  WS_MESSAGE: 256 * 1024,
+  /** Default HTTP body limit: 64KB */
+  DEFAULT_HTTP: 64 * 1024,
+} as const;
+
+/**
+ * Options for reading JSON body.
+ */
+export interface ReadJsonBodyOptions {
+  /** Maximum bytes to accept (default: 64KB) */
+  maxBytes?: number;
+}
+
+/**
+ * Result of parsing JSON body.
+ */
+export type JsonBodyResult<T = unknown> =
+  | { ok: true; data: T }
+  | { ok: false; response: Response };
+
+/**
+ * Read and parse JSON body from HTTP request with size validation.
+ *
+ * Security:
+ * - Size checked before parsing (DoS protection)
+ * - Invalid JSON errors do not echo user content
+ * - Generic error messages
+ *
+ * @param req - HTTP request
+ * @param options - Size limit options
+ * @returns Parsed JSON or error response
+ */
+export async function readJsonBody<T = unknown>(
+  req: Request,
+  options: ReadJsonBodyOptions = {}
+): Promise<JsonBodyResult<T>> {
+  const maxBytes = options.maxBytes ?? SIZE_LIMITS.DEFAULT_HTTP;
+
+  // Check Content-Length header first (fast path rejection)
+  const contentLength = req.headers.get("Content-Length");
+  if (contentLength) {
+    const length = parseInt(contentLength, 10);
+    if (!isNaN(length) && length > maxBytes) {
+      return {
+        ok: false,
+        response: payloadTooLargeResponse(maxBytes),
+      };
+    }
+  }
+
+  // Check Content-Type
+  const contentType = req.headers.get("Content-Type");
+  if (!contentType || !contentType.includes("application/json")) {
+    return {
+      ok: false,
+      response: invalidContentTypeResponse(),
+    };
+  }
+
+  try {
+    // Read body as ArrayBuffer to check actual size
+    const buffer = await req.arrayBuffer();
+
+    if (buffer.byteLength > maxBytes) {
+      return {
+        ok: false,
+        response: payloadTooLargeResponse(maxBytes),
+      };
+    }
+
+    // Decode and parse JSON
+    const text = new TextDecoder().decode(buffer);
+
+    try {
+      const data = JSON.parse(text) as T;
+      return { ok: true, data };
+    } catch {
+      return {
+        ok: false,
+        response: invalidJsonResponse(),
+      };
+    }
+  } catch {
+    // Body read error (connection reset, etc.)
+    return {
+      ok: false,
+      response: bodyReadErrorResponse(),
+    };
+  }
+}
+
+/**
+ * Validate a WebSocket message size.
+ *
+ * @param data - Message data (string or binary)
+ * @param maxBytes - Maximum allowed bytes (default: 256KB)
+ * @returns true if within limit
+ */
+export function validateWsMessageSize(
+  data: string | ArrayBuffer | Uint8Array,
+  maxBytes: number = SIZE_LIMITS.WS_MESSAGE
+): boolean {
+  let size: number;
+
+  if (typeof data === "string") {
+    // For strings, use byte length (UTF-8)
+    size = new TextEncoder().encode(data).length;
+  } else if (data instanceof ArrayBuffer) {
+    size = data.byteLength;
+  } else {
+    size = data.length;
+  }
+
+  return size <= maxBytes;
+}
+
+/**
+ * Parse and validate WebSocket JSON message.
+ *
+ * @param data - Raw message data
+ * @param maxBytes - Maximum allowed bytes
+ * @returns Parsed object or null on failure
+ */
+export function parseWsMessage<T = unknown>(
+  data: string | ArrayBuffer | Uint8Array,
+  maxBytes: number = SIZE_LIMITS.WS_MESSAGE
+): T | null {
+  if (!validateWsMessageSize(data, maxBytes)) {
+    return null;
+  }
+
+  let text: string;
+  if (typeof data === "string") {
+    text = data;
+  } else if (data instanceof ArrayBuffer) {
+    text = new TextDecoder().decode(data);
+  } else {
+    text = new TextDecoder().decode(data);
+  }
+
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validate that serialized JSON stays within size limit.
+ * Useful for validating attachment value_json before insertion.
+ *
+ * @param value - Value to check
+ * @param maxBytes - Maximum serialized size
+ * @returns true if within limit
+ */
+export function validateJsonSize(value: unknown, maxBytes: number): boolean {
+  try {
+    const serialized = JSON.stringify(value);
+    return new TextEncoder().encode(serialized).length <= maxBytes;
+  } catch {
+    return false;
+  }
+}
+
+// ============================================================================
+// Error response helpers (generic messages, no user content echoed)
+// ============================================================================
+
+/**
+ * Create 413 Payload Too Large response.
+ */
+export function payloadTooLargeResponse(maxBytes: number): Response {
+  return new Response(
+    JSON.stringify({
+      error: `Payload too large (max ${Math.floor(maxBytes / 1024)}KB)`,
+      code: "PAYLOAD_TOO_LARGE",
+    }),
+    {
+      status: 413,
+      headers: { "Content-Type": "application/json" },
+    }
+  );
+}
+
+/**
+ * Create 400 Bad Request response for invalid JSON.
+ */
+export function invalidJsonResponse(): Response {
+  return new Response(
+    JSON.stringify({
+      error: "Invalid JSON",
+      code: "INVALID_INPUT",
+    }),
+    {
+      status: 400,
+      headers: { "Content-Type": "application/json" },
+    }
+  );
+}
+
+/**
+ * Create 415 Unsupported Media Type response.
+ */
+export function invalidContentTypeResponse(): Response {
+  return new Response(
+    JSON.stringify({
+      error: "Content-Type must be application/json",
+      code: "INVALID_INPUT",
+    }),
+    {
+      status: 415,
+      headers: { "Content-Type": "application/json" },
+    }
+  );
+}
+
+/**
+ * Create 400 Bad Request response for body read errors.
+ */
+export function bodyReadErrorResponse(): Response {
+  return new Response(
+    JSON.stringify({
+      error: "Failed to read request body",
+      code: "INVALID_INPUT",
+    }),
+    {
+      status: 400,
+      headers: { "Content-Type": "application/json" },
+    }
+  );
+}
+
+/**
+ * Create generic 400 Bad Request response for validation errors.
+ *
+ * @param message - Error message (should not contain user input)
+ */
+export function validationErrorResponse(message: string): Response {
+  return new Response(
+    JSON.stringify({
+      error: message,
+      code: "INVALID_INPUT",
+    }),
+    {
+      status: 400,
+      headers: { "Content-Type": "application/json" },
+    }
+  );
+}

package/src/config.ts

@@ -0,0 +1,273 @@
+/**
+ * Workspace config loader and schema validation
+ * 
+ * Security requirements:
+ * - Only load agentlip.config.ts from workspace root (never traverse upward)
+ * - Validate plugin module paths to prevent path traversal
+ * - Return null for missing config (optional file)
+ */
+
+import { join, resolve, relative, normalize } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * Plugin configuration
+ */
+export interface PluginConfig {
+  name: string;
+  type: "linkifier" | "extractor";
+  enabled: boolean;
+  /** Path to custom plugin module (relative to workspace root or absolute). Default: built-in */
+  module?: string;
+  /** Plugin-specific configuration */
+  config?: Record<string, unknown>;
+}
+
+/**
+ * Workspace configuration schema
+ */
+export interface WorkspaceConfig {
+  plugins?: PluginConfig[];
+  rateLimits?: {
+    perConnection?: number;
+    global?: number;
+  };
+  limits?: {
+    maxMessageSize?: number;
+    maxAttachmentSize?: number;
+    maxWsMessageSize?: number;
+    maxWsConnections?: number;
+    maxWsQueueSize?: number;
+    maxEventReplayBatch?: number;
+  };
+  pluginDefaults?: {
+    timeout?: number;
+    memoryLimit?: number;
+  };
+}
+
+/**
+ * Result of config loading
+ */
+export interface LoadConfigResult {
+  config: WorkspaceConfig;
+  /** Absolute path to config file (if loaded) */
+  configPath?: string;
+}
+
+/**
+ * Validate that a plugin module path does not escape workspace root.
+ * 
+ * Security: prevents path traversal attacks via plugin.module field.
+ * 
+ * @param modulePath - Plugin module path (relative or absolute)
+ * @param workspaceRoot - Workspace root directory (absolute)
+ * @returns Absolute path to module if valid
+ * @throws Error if path escapes workspace root
+ */
+export function validatePluginModulePath(
+  modulePath: string,
+  workspaceRoot: string
+): string {
+  const absWorkspaceRoot = resolve(workspaceRoot);
+  
+  // Resolve module path relative to workspace root (if relative)
+  const absModulePath = resolve(absWorkspaceRoot, modulePath);
+  
+  // Normalize paths to handle '..' and '.' components
+  const normalizedWorkspaceRoot = normalize(absWorkspaceRoot);
+  const normalizedModulePath = normalize(absModulePath);
+  
+  // Check that resolved path is within workspace root
+  const rel = relative(normalizedWorkspaceRoot, normalizedModulePath);
+  
+  // relative() returns a path that:
+  // - starts with '..' if target is outside source
+  // - is empty string if paths are identical
+  // - is a relative path within if target is inside source
+  
+  if (rel.startsWith("..") || resolve(normalizedWorkspaceRoot, rel) !== normalizedModulePath) {
+    throw new Error(
+      `Plugin module path escapes workspace root: ${modulePath} ` +
+      `(resolves to ${normalizedModulePath}, workspace: ${normalizedWorkspaceRoot})`
+    );
+  }
+  
+  return normalizedModulePath;
+}
+
+/**
+ * Validate workspace config schema.
+ * 
+ * Performs basic structural validation and security checks.
+ * 
+ * @param config - Config object to validate
+ * @param workspaceRoot - Workspace root for plugin path validation
+ * @throws Error if validation fails
+ */
+export function validateWorkspaceConfig(
+  config: unknown,
+  workspaceRoot: string
+): asserts config is WorkspaceConfig {
+  if (config === null || typeof config !== "object") {
+    throw new Error("Config must be an object");
+  }
+  
+  const cfg = config as Record<string, unknown>;
+  
+  // Validate plugins array (if present)
+  if (cfg.plugins !== undefined) {
+    if (!Array.isArray(cfg.plugins)) {
+      throw new Error("plugins must be an array");
+    }
+    
+    for (const [idx, plugin] of cfg.plugins.entries()) {
+      if (plugin === null || typeof plugin !== "object") {
+        throw new Error(`plugins[${idx}] must be an object`);
+      }
+      
+      const p = plugin as Record<string, unknown>;
+      
+      // Required fields
+      if (typeof p.name !== "string" || p.name.length === 0) {
+        throw new Error(`plugins[${idx}].name must be a non-empty string`);
+      }
+      
+      if (p.type !== "linkifier" && p.type !== "extractor") {
+        throw new Error(`plugins[${idx}].type must be "linkifier" or "extractor"`);
+      }
+      
+      if (typeof p.enabled !== "boolean") {
+        throw new Error(`plugins[${idx}].enabled must be a boolean`);
+      }
+      
+      // Validate module path (if provided)
+      if (p.module !== undefined) {
+        if (typeof p.module !== "string") {
+          throw new Error(`plugins[${idx}].module must be a string`);
+        }
+        
+        // Security: validate path does not escape workspace
+        try {
+          validatePluginModulePath(p.module, workspaceRoot);
+        } catch (err: any) {
+          throw new Error(`plugins[${idx}].module: ${err.message}`);
+        }
+      }
+      
+      // Validate config (if provided)
+      if (p.config !== undefined) {
+        if (p.config === null || typeof p.config !== "object" || Array.isArray(p.config)) {
+          throw new Error(`plugins[${idx}].config must be an object`);
+        }
+      }
+    }
+  }
+  
+  // Validate rateLimits (if present)
+  if (cfg.rateLimits !== undefined) {
+    if (cfg.rateLimits === null || typeof cfg.rateLimits !== "object") {
+      throw new Error("rateLimits must be an object");
+    }
+    
+    const rl = cfg.rateLimits as Record<string, unknown>;
+    
+    if (rl.perConnection !== undefined && typeof rl.perConnection !== "number") {
+      throw new Error("rateLimits.perConnection must be a number");
+    }
+    
+    if (rl.global !== undefined && typeof rl.global !== "number") {
+      throw new Error("rateLimits.global must be a number");
+    }
+  }
+  
+  // Validate limits (if present)
+  if (cfg.limits !== undefined) {
+    if (cfg.limits === null || typeof cfg.limits !== "object") {
+      throw new Error("limits must be an object");
+    }
+    
+    const lim = cfg.limits as Record<string, unknown>;
+    const limitFields = [
+      "maxMessageSize",
+      "maxAttachmentSize",
+      "maxWsMessageSize",
+      "maxWsConnections",
+      "maxWsQueueSize",
+      "maxEventReplayBatch",
+    ];
+    
+    for (const field of limitFields) {
+      if (lim[field] !== undefined && typeof lim[field] !== "number") {
+        throw new Error(`limits.${field} must be a number`);
+      }
+    }
+  }
+  
+  // Validate pluginDefaults (if present)
+  if (cfg.pluginDefaults !== undefined) {
+    if (cfg.pluginDefaults === null || typeof cfg.pluginDefaults !== "object") {
+      throw new Error("pluginDefaults must be an object");
+    }
+    
+    const pd = cfg.pluginDefaults as Record<string, unknown>;
+    
+    if (pd.timeout !== undefined && typeof pd.timeout !== "number") {
+      throw new Error("pluginDefaults.timeout must be a number");
+    }
+    
+    if (pd.memoryLimit !== undefined && typeof pd.memoryLimit !== "number") {
+      throw new Error("pluginDefaults.memoryLimit must be a number");
+    }
+  }
+}
+
+/**
+ * Load and validate workspace config from agentlip.config.ts.
+ * 
+ * Security guarantees:
+ * - Only loads from workspace root (never traverses upward)
+ * - Validates plugin module paths to prevent path traversal
+ * - Returns null if config file doesn't exist (optional file)
+ * 
+ * @param workspaceRoot - Absolute path to workspace root directory
+ * @returns Config object or null if file doesn't exist
+ * @throws Error if config exists but is invalid
+ */
+export async function loadWorkspaceConfig(
+  workspaceRoot: string
+): Promise<LoadConfigResult | null> {
+  const absWorkspaceRoot = resolve(workspaceRoot);
+  const configPath = join(absWorkspaceRoot, "agentlip.config.ts");
+  
+  // Convert to file:// URL for dynamic import
+  const configUrl = pathToFileURL(configPath).href;
+  
+  let configModule: unknown;
+  try {
+    configModule = await import(configUrl);
+  } catch (err: any) {
+    // File doesn't exist or has syntax errors
+    if (err?.code === "ERR_MODULE_NOT_FOUND" || err?.code === "ENOENT") {
+      return null;
+    }
+    
+    // Config exists but has errors - propagate
+    throw new Error(`Failed to load agentlip.config.ts: ${err.message}`);
+  }
+  
+  // Extract default export
+  const config = (configModule as any)?.default;
+  
+  if (config === undefined) {
+    throw new Error("agentlip.config.ts must have a default export");
+  }
+  
+  // Validate config schema
+  validateWorkspaceConfig(config, absWorkspaceRoot);
+  
+  return {
+    config,
+    configPath,
+  };
+}