@agenticmail/enterprise 0.2.1

package/src/lib/resilience.ts

@@ -0,0 +1,326 @@
+/**
+ * Resilience Utilities
+ * 
+ * Retry logic, circuit breakers, connection health checks,
+ * rate limiting, and graceful degradation patterns.
+ */
+
+// ─── Retry with Exponential Backoff ──────────────────────
+
+export interface RetryOptions {
+  maxAttempts: number;
+  baseDelayMs: number;
+  maxDelayMs: number;
+  backoffMultiplier: number;
+  retryableErrors?: (err: Error) => boolean;
+  onRetry?: (attempt: number, err: Error, delayMs: number) => void;
+}
+
+const DEFAULT_RETRY: RetryOptions = {
+  maxAttempts: 3,
+  baseDelayMs: 500,
+  maxDelayMs: 30_000,
+  backoffMultiplier: 2,
+};
+
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  opts: Partial<RetryOptions> = {},
+): Promise<T> {
+  const config = { ...DEFAULT_RETRY, ...opts };
+  let lastError: Error = new Error('No attempts made');
+
+  for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (err: any) {
+      lastError = err;
+
+      if (attempt === config.maxAttempts) break;
+      if (config.retryableErrors && !config.retryableErrors(err)) break;
+
+      // Exponential backoff with jitter
+      const delay = Math.min(
+        config.baseDelayMs * Math.pow(config.backoffMultiplier, attempt - 1) + Math.random() * 200,
+        config.maxDelayMs,
+      );
+
+      config.onRetry?.(attempt, err, delay);
+      await sleep(delay);
+    }
+  }
+
+  throw lastError;
+}
+
+// ─── Circuit Breaker ─────────────────────────────────────
+
+export type CircuitState = 'closed' | 'open' | 'half-open';
+
+export interface CircuitBreakerOptions {
+  failureThreshold: number;    // Failures before opening
+  recoveryTimeMs: number;      // Time before half-open
+  successThreshold: number;    // Successes in half-open to close
+  timeout?: number;            // Per-call timeout in ms
+}
+
+export class CircuitBreaker {
+  private state: CircuitState = 'closed';
+  private failures = 0;
+  private successes = 0;
+  private lastFailureTime = 0;
+  private readonly opts: CircuitBreakerOptions;
+
+  constructor(opts: Partial<CircuitBreakerOptions> = {}) {
+    this.opts = {
+      failureThreshold: opts.failureThreshold ?? 5,
+      recoveryTimeMs: opts.recoveryTimeMs ?? 30_000,
+      successThreshold: opts.successThreshold ?? 2,
+      timeout: opts.timeout,
+    };
+  }
+
+  async execute<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.state === 'open') {
+      if (Date.now() - this.lastFailureTime >= this.opts.recoveryTimeMs) {
+        this.state = 'half-open';
+        this.successes = 0;
+      } else {
+        throw new CircuitOpenError(
+          `Circuit breaker is open. Retry after ${this.opts.recoveryTimeMs}ms`,
+        );
+      }
+    }
+
+    try {
+      const result = this.opts.timeout
+        ? await withTimeout(fn(), this.opts.timeout)
+        : await fn();
+
+      this.onSuccess();
+      return result;
+    } catch (err) {
+      this.onFailure();
+      throw err;
+    }
+  }
+
+  private onSuccess(): void {
+    if (this.state === 'half-open') {
+      this.successes++;
+      if (this.successes >= this.opts.successThreshold) {
+        this.state = 'closed';
+        this.failures = 0;
+      }
+    } else {
+      this.failures = 0;
+    }
+  }
+
+  private onFailure(): void {
+    this.failures++;
+    this.lastFailureTime = Date.now();
+    if (this.failures >= this.opts.failureThreshold) {
+      this.state = 'open';
+    }
+  }
+
+  getState(): CircuitState { return this.state; }
+  reset(): void { this.state = 'closed'; this.failures = 0; this.successes = 0; }
+}
+
+export class CircuitOpenError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CircuitOpenError';
+  }
+}
+
+// ─── Rate Limiter (Token Bucket) ─────────────────────────
+
+export interface RateLimiterOptions {
+  maxTokens: number;           // Bucket capacity
+  refillRate: number;          // Tokens per second
+  refillIntervalMs?: number;   // How often to refill (default: 1000)
+}
+
+export class RateLimiter {
+  private tokens: number;
+  private lastRefill: number;
+  private readonly opts: Required<RateLimiterOptions>;
+
+  constructor(opts: RateLimiterOptions) {
+    this.opts = {
+      maxTokens: opts.maxTokens,
+      refillRate: opts.refillRate,
+      refillIntervalMs: opts.refillIntervalMs ?? 1000,
+    };
+    this.tokens = this.opts.maxTokens;
+    this.lastRefill = Date.now();
+  }
+
+  /**
+   * Try to consume a token. Returns true if allowed, false if rate limited.
+   */
+  tryConsume(count = 1): boolean {
+    this.refill();
+    if (this.tokens >= count) {
+      this.tokens -= count;
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Get time in ms until next token is available.
+   */
+  getRetryAfterMs(): number {
+    this.refill();
+    if (this.tokens >= 1) return 0;
+    const tokensNeeded = 1 - this.tokens;
+    return Math.ceil((tokensNeeded / this.opts.refillRate) * 1000);
+  }
+
+  private refill(): void {
+    const now = Date.now();
+    const elapsed = now - this.lastRefill;
+    const tokensToAdd = (elapsed / 1000) * this.opts.refillRate;
+    this.tokens = Math.min(this.opts.maxTokens, this.tokens + tokensToAdd);
+    this.lastRefill = now;
+  }
+}
+
+// ─── Per-Key Rate Limiter (for API endpoints) ────────────
+
+export class KeyedRateLimiter {
+  private limiters = new Map<string, RateLimiter>();
+  private readonly opts: RateLimiterOptions;
+  private cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(opts: RateLimiterOptions) {
+    this.opts = opts;
+    // Cleanup stale entries every 5 minutes
+    this.cleanupTimer = setInterval(() => this.cleanup(), 5 * 60_000);
+    if (this.cleanupTimer && typeof this.cleanupTimer === 'object' && 'unref' in this.cleanupTimer) {
+      this.cleanupTimer.unref();
+    }
+  }
+
+  tryConsume(key: string, count = 1): boolean {
+    let limiter = this.limiters.get(key);
+    if (!limiter) {
+      limiter = new RateLimiter(this.opts);
+      this.limiters.set(key, limiter);
+    }
+    return limiter.tryConsume(count);
+  }
+
+  getRetryAfterMs(key: string): number {
+    const limiter = this.limiters.get(key);
+    return limiter ? limiter.getRetryAfterMs() : 0;
+  }
+
+  private cleanup(): void {
+    // Remove limiters that haven't been used (all have full tokens)
+    for (const [key, limiter] of this.limiters) {
+      if (limiter.getRetryAfterMs() === 0) {
+        this.limiters.delete(key);
+      }
+    }
+  }
+
+  destroy(): void {
+    if (this.cleanupTimer) clearInterval(this.cleanupTimer);
+    this.limiters.clear();
+  }
+}
+
+// ─── Connection Health Monitor ───────────────────────────
+
+export interface HealthCheckOptions {
+  intervalMs: number;        // How often to check (default: 30s)
+  timeoutMs: number;         // Health check timeout
+  unhealthyThreshold: number; // Consecutive failures before unhealthy
+  healthyThreshold: number;   // Consecutive successes before healthy
+}
+
+export class HealthMonitor {
+  private healthy = true;
+  private consecutiveFailures = 0;
+  private consecutiveSuccesses = 0;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private readonly check: () => Promise<void>;
+  private readonly opts: HealthCheckOptions;
+  private listeners: ((healthy: boolean) => void)[] = [];
+
+  constructor(check: () => Promise<void>, opts: Partial<HealthCheckOptions> = {}) {
+    this.check = check;
+    this.opts = {
+      intervalMs: opts.intervalMs ?? 30_000,
+      timeoutMs: opts.timeoutMs ?? 5_000,
+      unhealthyThreshold: opts.unhealthyThreshold ?? 3,
+      healthyThreshold: opts.healthyThreshold ?? 2,
+    };
+  }
+
+  start(): void {
+    if (this.timer) return;
+    this.timer = setInterval(() => this.runCheck(), this.opts.intervalMs);
+    if (this.timer && typeof this.timer === 'object' && 'unref' in this.timer) {
+      this.timer.unref();
+    }
+  }
+
+  stop(): void {
+    if (this.timer) { clearInterval(this.timer); this.timer = null; }
+  }
+
+  isHealthy(): boolean { return this.healthy; }
+
+  onStatusChange(fn: (healthy: boolean) => void): void {
+    this.listeners.push(fn);
+  }
+
+  private async runCheck(): Promise<void> {
+    try {
+      await withTimeout(this.check(), this.opts.timeoutMs);
+      this.consecutiveFailures = 0;
+      this.consecutiveSuccesses++;
+      if (!this.healthy && this.consecutiveSuccesses >= this.opts.healthyThreshold) {
+        this.healthy = true;
+        this.listeners.forEach(fn => fn(true));
+      }
+    } catch {
+      this.consecutiveSuccesses = 0;
+      this.consecutiveFailures++;
+      if (this.healthy && this.consecutiveFailures >= this.opts.unhealthyThreshold) {
+        this.healthy = false;
+        this.listeners.forEach(fn => fn(false));
+      }
+    }
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`Operation timed out after ${ms}ms`)), ms);
+    promise
+      .then(v => { clearTimeout(timer); resolve(v); })
+      .catch(e => { clearTimeout(timer); reject(e); });
+  });
+}
+
+// ─── Request ID Generator ────────────────────────────────
+
+let counter = 0;
+const prefix = Math.random().toString(36).substring(2, 8);
+
+export function requestId(): string {
+  return `${prefix}-${(++counter).toString(36)}-${Date.now().toString(36)}`;
+}

package/src/middleware/index.ts

@@ -0,0 +1,286 @@
+/**
+ * Enterprise Middleware Stack
+ * 
+ * Rate limiting, request logging, error handling, validation,
+ * CORS, request IDs, and security headers.
+ */
+
+import type { Context, Next, MiddlewareHandler } from 'hono';
+import { KeyedRateLimiter, requestId } from '../lib/resilience.js';
+import type { DatabaseAdapter } from '../db/adapter.js';
+
+// ─── Request ID ──────────────────────────────────────────
+
+export function requestIdMiddleware(): MiddlewareHandler {
+  return async (c: Context, next: Next) => {
+    const id = c.req.header('X-Request-Id') || requestId();
+    c.set('requestId' as any, id);
+    c.header('X-Request-Id', id);
+    await next();
+  };
+}
+
+// ─── Request Logging ─────────────────────────────────────
+
+export function requestLogger(): MiddlewareHandler {
+  return async (c: Context, next: Next) => {
+    const start = Date.now();
+    const method = c.req.method;
+    const path = c.req.path;
+
+    await next();
+
+    const elapsed = Date.now() - start;
+    const status = c.res.status;
+    const reqId = c.get('requestId' as any) || '-';
+
+    // Structured log line
+    const level = status >= 500 ? 'ERROR' : status >= 400 ? 'WARN' : 'INFO';
+    console.log(
+      `[${new Date().toISOString()}] ${level} ${method} ${path} ${status} ${elapsed}ms req=${reqId}`,
+    );
+  };
+}
+
+// ─── Rate Limiting ───────────────────────────────────────
+
+interface RateLimitConfig {
+  /** Requests per window */
+  limit: number;
+  /** Window in seconds */
+  windowSec: number;
+  /** Key extractor (default: IP) */
+  keyFn?: (c: Context) => string;
+  /** Skip rate limiting for these paths */
+  skipPaths?: string[];
+}
+
+export function rateLimiter(config: RateLimitConfig): MiddlewareHandler {
+  const limiter = new KeyedRateLimiter({
+    maxTokens: config.limit,
+    refillRate: config.limit / config.windowSec,
+  });
+
+  return async (c: Context, next: Next) => {
+    // Skip health checks
+    if (config.skipPaths?.some(p => c.req.path.startsWith(p))) {
+      return next();
+    }
+
+    const key = config.keyFn?.(c) ||
+      c.req.header('x-forwarded-for')?.split(',')[0]?.trim() ||
+      c.req.header('x-real-ip') ||
+      'unknown';
+
+    if (!limiter.tryConsume(key)) {
+      const retryAfter = Math.ceil(limiter.getRetryAfterMs(key) / 1000);
+      c.header('Retry-After', String(retryAfter));
+      c.header('X-RateLimit-Limit', String(config.limit));
+      c.header('X-RateLimit-Remaining', '0');
+      return c.json(
+        { error: 'Too many requests', retryAfter },
+        429,
+      );
+    }
+
+    await next();
+  };
+}
+
+// ─── Security Headers ────────────────────────────────────
+
+export function securityHeaders(): MiddlewareHandler {
+  return async (c: Context, next: Next) => {
+    await next();
+
+    c.header('X-Content-Type-Options', 'nosniff');
+    c.header('X-Frame-Options', 'DENY');
+    c.header('X-XSS-Protection', '0'); // Modern browsers: CSP is better
+    c.header('Referrer-Policy', 'strict-origin-when-cross-origin');
+    c.header('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');
+
+    // Only set HSTS if behind TLS
+    if (c.req.url.startsWith('https://') || c.req.header('x-forwarded-proto') === 'https') {
+      c.header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+    }
+  };
+}
+
+// ─── Error Handler ───────────────────────────────────────
+
+export interface ApiError {
+  error: string;
+  code?: string;
+  details?: unknown;
+  requestId?: string;
+}
+
+export function errorHandler(): MiddlewareHandler {
+  return async (c: Context, next: Next) => {
+    try {
+      await next();
+    } catch (err: any) {
+      const reqId = c.get('requestId' as any);
+      const status = err.status || err.statusCode || 500;
+      const message = status >= 500 ? 'Internal server error' : err.message;
+
+      // Log full error for 5xx
+      if (status >= 500) {
+        console.error(`[${new Date().toISOString()}] ERROR req=${reqId}`, err);
+      }
+
+      const body: ApiError = {
+        error: message,
+        code: err.code,
+        requestId: reqId,
+      };
+
+      // Include validation details for 400s
+      if (status === 400 && err.details) {
+        body.details = err.details;
+      }
+
+      return c.json(body, status);
+    }
+  };
+}
+
+// ─── Input Validation ────────────────────────────────────
+
+export class ValidationError extends Error {
+  status = 400;
+  code = 'VALIDATION_ERROR';
+  details: Record<string, string>;
+
+  constructor(details: Record<string, string>) {
+    const fields = Object.keys(details).join(', ');
+    super(`Validation failed: ${fields}`);
+    this.details = details;
+  }
+}
+
+type Validator = {
+  field: string;
+  type: 'string' | 'number' | 'boolean' | 'email' | 'url' | 'uuid';
+  required?: boolean;
+  minLength?: number;
+  maxLength?: number;
+  min?: number;
+  max?: number;
+  pattern?: RegExp;
+};
+
+export function validate(body: Record<string, any>, validators: Validator[]): void {
+  const errors: Record<string, string> = {};
+
+  for (const v of validators) {
+    const value = body[v.field];
+
+    if (value === undefined || value === null || value === '') {
+      if (v.required) errors[v.field] = 'Required';
+      continue;
+    }
+
+    switch (v.type) {
+      case 'string':
+        if (typeof value !== 'string') { errors[v.field] = 'Must be a string'; break; }
+        if (v.minLength && value.length < v.minLength) errors[v.field] = `Min length: ${v.minLength}`;
+        if (v.maxLength && value.length > v.maxLength) errors[v.field] = `Max length: ${v.maxLength}`;
+        if (v.pattern && !v.pattern.test(value)) errors[v.field] = 'Invalid format';
+        break;
+      case 'number':
+        if (typeof value !== 'number' || isNaN(value)) { errors[v.field] = 'Must be a number'; break; }
+        if (v.min !== undefined && value < v.min) errors[v.field] = `Min: ${v.min}`;
+        if (v.max !== undefined && value > v.max) errors[v.field] = `Max: ${v.max}`;
+        break;
+      case 'boolean':
+        if (typeof value !== 'boolean') errors[v.field] = 'Must be a boolean';
+        break;
+      case 'email':
+        if (typeof value !== 'string' || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value))
+          errors[v.field] = 'Invalid email';
+        break;
+      case 'url':
+        try { new URL(value); } catch { errors[v.field] = 'Invalid URL'; }
+        break;
+      case 'uuid':
+        if (typeof value !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value))
+          errors[v.field] = 'Invalid UUID';
+        break;
+    }
+  }
+
+  if (Object.keys(errors).length > 0) {
+    throw new ValidationError(errors);
+  }
+}
+
+// ─── Audit Logger Middleware ─────────────────────────────
+
+export function auditLogger(db: DatabaseAdapter): MiddlewareHandler {
+  // Only audit mutating operations
+  const AUDIT_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+  return async (c: Context, next: Next) => {
+    await next();
+
+    if (!AUDIT_METHODS.has(c.req.method)) return;
+    if (c.res.status >= 400) return; // Don't audit failed requests
+
+    try {
+      const userId = c.get('userId' as any) || 'anonymous';
+      const path = c.req.path;
+      const method = c.req.method;
+
+      // Derive action from path + method
+      const segments = path.split('/').filter(Boolean);
+      const resource = segments[segments.length - 2] || segments[segments.length - 1] || 'unknown';
+      const actionMap: Record<string, string> = {
+        POST: 'create', PUT: 'update', PATCH: 'update', DELETE: 'delete',
+      };
+      const action = `${resource}.${actionMap[method] || method.toLowerCase()}`;
+
+      await db.logEvent({
+        actor: userId,
+        actorType: 'user',
+        action,
+        resource: path,
+        ip: c.req.header('x-forwarded-for')?.split(',')[0]?.trim() || c.req.header('x-real-ip'),
+      });
+    } catch {
+      // Never let audit logging break the request
+    }
+  };
+}
+
+// ─── RBAC Middleware ─────────────────────────────────────
+
+type Role = 'owner' | 'admin' | 'member' | 'viewer';
+
+const ROLE_HIERARCHY: Record<Role, number> = {
+  viewer: 0,
+  member: 1,
+  admin: 2,
+  owner: 3,
+};
+
+export function requireRole(minRole: Role): MiddlewareHandler {
+  return async (c: Context, next: Next) => {
+    const userRole = c.get('userRole' as any) as Role | undefined;
+
+    // API keys bypass role check (scopes handle auth)
+    if (c.get('authType' as any) === 'api-key') {
+      return next();
+    }
+
+    if (!userRole || ROLE_HIERARCHY[userRole] < ROLE_HIERARCHY[minRole]) {
+      return c.json({
+        error: 'Insufficient permissions',
+        required: minRole,
+        current: userRole || 'none',
+      }, 403);
+    }
+
+    return next();
+  };
+}