@sentinel-atl/hardening 0.3.0

package/src/auth.ts

@@ -0,0 +1,162 @@
+/**
+ * API Key Authentication middleware.
+ *
+ * Supports:
+ * - Bearer token in Authorization header
+ * - X-API-Key header
+ * - ?apiKey query parameter
+ *
+ * Keys are validated using constant-time comparison to prevent timing attacks.
+ * Multiple keys can be configured with different scopes (read, write, admin).
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { timingSafeEqual } from 'node:crypto';
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+export type AuthScope = 'read' | 'write' | 'admin';
+
+export interface ApiKey {
+  /** The key value (plaintext — in production, store hashed) */
+  key: string;
+  /** Human-readable label */
+  label?: string;
+  /** Scopes this key grants */
+  scopes: AuthScope[];
+}
+
+export interface AuthConfig {
+  /** Whether auth is enabled (default: false — opt-in) */
+  enabled: boolean;
+  /** Registered API keys */
+  keys: ApiKey[];
+  /** Paths that don't require auth (e.g., /health, badge endpoints) */
+  publicPaths?: string[];
+  /** Custom realm for WWW-Authenticate header */
+  realm?: string;
+}
+
+export interface AuthResult {
+  authenticated: boolean;
+  key?: ApiKey;
+  error?: string;
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────
+
+function constantTimeCompare(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  const bufA = Buffer.from(a, 'utf-8');
+  const bufB = Buffer.from(b, 'utf-8');
+  return timingSafeEqual(bufA, bufB);
+}
+
+function extractApiKey(req: IncomingMessage): string | undefined {
+  // 1. Authorization: Bearer <key>
+  const authHeader = req.headers['authorization'];
+  if (authHeader?.startsWith('Bearer ')) {
+    return authHeader.slice(7);
+  }
+
+  // 2. X-API-Key header
+  const xApiKey = req.headers['x-api-key'];
+  if (typeof xApiKey === 'string' && xApiKey) {
+    return xApiKey;
+  }
+
+  // 3. Query parameter
+  const url = new URL(req.url ?? '/', `http://localhost`);
+  const queryKey = url.searchParams.get('apiKey');
+  if (queryKey) {
+    return queryKey;
+  }
+
+  return undefined;
+}
+
+// ─── Auth Check ──────────────────────────────────────────────────────
+
+/**
+ * Authenticate an incoming request.
+ */
+export function authenticate(req: IncomingMessage, config: AuthConfig): AuthResult {
+  if (!config.enabled) {
+    return { authenticated: true };
+  }
+
+  // Check public paths
+  const url = new URL(req.url ?? '/', `http://localhost`);
+  const path = url.pathname;
+  if (config.publicPaths?.some(p => path === p || path.startsWith(p + '/'))) {
+    return { authenticated: true };
+  }
+
+  const providedKey = extractApiKey(req);
+  if (!providedKey) {
+    return { authenticated: false, error: 'Missing API key' };
+  }
+
+  // Find matching key (constant-time comparison)
+  for (const registeredKey of config.keys) {
+    if (constantTimeCompare(providedKey, registeredKey.key)) {
+      return { authenticated: true, key: registeredKey };
+    }
+  }
+
+  return { authenticated: false, error: 'Invalid API key' };
+}
+
+/**
+ * Check if request has the required scope.
+ */
+export function hasScope(result: AuthResult, required: AuthScope): boolean {
+  if (!result.authenticated) return false;
+  if (!result.key) return true; // Auth disabled or public path
+  if (result.key.scopes.includes('admin')) return true;
+  return result.key.scopes.includes(required);
+}
+
+/**
+ * Send a 401 Unauthorized response.
+ */
+export function sendUnauthorized(res: ServerResponse, config: AuthConfig, error?: string): void {
+  const realm = config.realm ?? 'Sentinel';
+  res.writeHead(401, {
+    'Content-Type': 'application/json',
+    'WWW-Authenticate': `Bearer realm="${realm}"`,
+  });
+  res.end(JSON.stringify({ error: error ?? 'Unauthorized' }));
+}
+
+/**
+ * Send a 403 Forbidden response.
+ */
+export function sendForbidden(res: ServerResponse, error?: string): void {
+  res.writeHead(403, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ error: error ?? 'Forbidden: insufficient scope' }));
+}
+
+/**
+ * Create a default auth config from environment variables.
+ *
+ * SENTINEL_API_KEYS=key1:read,write;key2:admin
+ */
+export function authConfigFromEnv(): AuthConfig {
+  const envKeys = process.env['SENTINEL_API_KEYS'];
+  if (!envKeys) {
+    return { enabled: false, keys: [] };
+  }
+
+  const keys: ApiKey[] = envKeys.split(';').filter(Boolean).map((entry, i) => {
+    const [key, scopeStr] = entry.split(':');
+    const scopes = (scopeStr ?? 'read').split(',').map(s => s.trim()) as AuthScope[];
+    return { key: key.trim(), label: `key-${i}`, scopes };
+  });
+
+  return {
+    enabled: keys.length > 0,
+    keys,
+    publicPaths: ['/health'],
+  };
+}

package/src/cors.ts

@@ -0,0 +1,118 @@
+/**
+ * CORS middleware — configurable origin allowlist.
+ *
+ * Replaces the `Access-Control-Allow-Origin: *` wildcard with
+ * explicit origin checking and proper Vary headers.
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+export interface CorsConfig {
+  /** Allowed origins. Use ['*'] to allow all (not recommended for production). */
+  allowedOrigins: string[];
+  /** Allowed HTTP methods */
+  allowedMethods?: string[];
+  /** Allowed request headers */
+  allowedHeaders?: string[];
+  /** Headers to expose to the browser */
+  exposedHeaders?: string[];
+  /** Whether to allow credentials (cookies, auth headers) */
+  allowCredentials?: boolean;
+  /** Max age for preflight cache (seconds) */
+  maxAge?: number;
+}
+
+// ─── Default Config ──────────────────────────────────────────────────
+
+export function defaultCorsConfig(): CorsConfig {
+  return {
+    allowedOrigins: ['*'],
+    allowedMethods: ['GET', 'POST', 'DELETE', 'OPTIONS'],
+    allowedHeaders: ['Content-Type', 'Authorization', 'X-API-Key', 'X-Caller-Id', 'X-Server-Name'],
+    allowCredentials: false,
+    maxAge: 86400, // 24 hours
+  };
+}
+
+// ─── CORS Application ───────────────────────────────────────────────
+
+/**
+ * Apply CORS headers to a response.
+ * Returns true if this was a preflight request (caller should end the response).
+ */
+export function applyCors(
+  req: IncomingMessage,
+  res: ServerResponse,
+  config: CorsConfig
+): boolean {
+  const origin = req.headers['origin'];
+
+  // Determine if origin is allowed
+  let allowedOrigin: string;
+  if (config.allowedOrigins.includes('*')) {
+    // Wildcard — but if credentials are enabled, must echo specific origin
+    allowedOrigin = config.allowCredentials && origin ? origin : '*';
+  } else if (origin && config.allowedOrigins.includes(origin)) {
+    allowedOrigin = origin;
+  } else if (!origin) {
+    // Same-origin or non-browser request — no CORS header needed
+    allowedOrigin = '';
+  } else {
+    // Origin not allowed — don't set any CORS headers
+    allowedOrigin = '';
+  }
+
+  if (allowedOrigin) {
+    res.setHeader('Access-Control-Allow-Origin', allowedOrigin);
+
+    // Vary: Origin — critical for caching when origin-specific
+    if (allowedOrigin !== '*') {
+      res.setHeader('Vary', 'Origin');
+    }
+  }
+
+  if (config.allowCredentials) {
+    res.setHeader('Access-Control-Allow-Credentials', 'true');
+  }
+
+  if (config.exposedHeaders?.length) {
+    res.setHeader('Access-Control-Expose-Headers', config.exposedHeaders.join(', '));
+  }
+
+  // Handle preflight
+  if (req.method === 'OPTIONS') {
+    if (config.allowedMethods?.length) {
+      res.setHeader('Access-Control-Allow-Methods', config.allowedMethods.join(', '));
+    }
+    if (config.allowedHeaders?.length) {
+      res.setHeader('Access-Control-Allow-Headers', config.allowedHeaders.join(', '));
+    }
+    if (config.maxAge !== undefined) {
+      res.setHeader('Access-Control-Max-Age', String(config.maxAge));
+    }
+    res.writeHead(204);
+    res.end();
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Create a CORS config from environment variable.
+ *
+ * SENTINEL_CORS_ORIGINS=https://example.com,https://app.example.com
+ */
+export function corsConfigFromEnv(): CorsConfig {
+  const envOrigins = process.env['SENTINEL_CORS_ORIGINS'];
+  const origins = envOrigins
+    ? envOrigins.split(',').map(o => o.trim()).filter(Boolean)
+    : ['*'];
+
+  return {
+    ...defaultCorsConfig(),
+    allowedOrigins: origins,
+  };
+}

package/src/index.ts

@@ -0,0 +1,62 @@
+/**
+ * @sentinel-atl/hardening — Production Hardening Middleware
+ *
+ * Reusable security middleware for all Sentinel HTTP servers:
+ * - API key authentication with scoped access
+ * - CORS with configurable origin allowlist
+ * - TLS/HTTPS support
+ * - Rate limit headers (RFC 6585)
+ * - Persistent nonce replay protection
+ * - Audit log rotation
+ */
+
+export {
+  authenticate,
+  hasScope,
+  sendUnauthorized,
+  sendForbidden,
+  authConfigFromEnv,
+  type AuthConfig,
+  type AuthScope,
+  type ApiKey,
+  type AuthResult,
+} from './auth.js';
+
+export {
+  applyCors,
+  defaultCorsConfig,
+  corsConfigFromEnv,
+  type CorsConfig,
+} from './cors.js';
+
+export {
+  createSecureServer,
+  tlsConfigFromEnv,
+  type TlsConfig,
+} from './tls.js';
+
+export {
+  RateLimiter,
+  setRateLimitHeaders,
+  sendRateLimited,
+  parseRateLimit,
+  type RateLimitInfo,
+} from './rate-limit.js';
+
+export {
+  NonceStore,
+  type NonceStoreConfig,
+} from './nonce-store.js';
+
+export {
+  rotateIfNeeded,
+  cleanupRotatedFiles,
+  totalLogSize,
+  type RotationConfig,
+} from './audit-rotation.js';
+
+export {
+  applySecurityHeaders,
+  securityHeadersConfigFromEnv,
+  type SecurityHeadersConfig,
+} from './security-headers.js';

package/src/nonce-store.ts

@@ -0,0 +1,111 @@
+/**
+ * Persistent nonce store — survives server restarts.
+ *
+ * Wraps the SentinelStore interface to provide a Set-like API for nonce tracking.
+ * Nonces auto-expire based on intent expiry to prevent unbounded growth.
+ */
+
+import type { SentinelStore } from '@sentinel-atl/store';
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+export interface NonceStoreConfig {
+  /** Underlying persistent store */
+  store: SentinelStore;
+  /** Key prefix (default: 'nonce:') */
+  prefix?: string;
+  /** Default TTL in seconds (default: 300 = 5 minutes) */
+  defaultTtl?: number;
+}
+
+// ─── Persistent Nonce Set ────────────────────────────────────────────
+
+/**
+ * A Set<string>-compatible nonce tracker backed by persistent storage.
+ *
+ * Drop-in replacement for the in-memory Set<string> used in validateIntent().
+ * Nonces are stored with a TTL so they auto-expire and don't grow forever.
+ */
+export class NonceStore {
+  private store: SentinelStore;
+  private prefix: string;
+  private defaultTtl: number;
+
+  constructor(config: NonceStoreConfig) {
+    this.store = config.store;
+    this.prefix = config.prefix ?? 'nonce:';
+    this.defaultTtl = config.defaultTtl ?? 300;
+  }
+
+  /** Check if a nonce has been seen. */
+  async has(nonce: string): Promise<boolean> {
+    return this.store.has(this.prefix + nonce);
+  }
+
+  /** Mark a nonce as seen with optional TTL in seconds. */
+  async add(nonce: string, ttlSeconds?: number): Promise<void> {
+    await this.store.set(this.prefix + nonce, '1', ttlSeconds ?? this.defaultTtl);
+  }
+
+  /**
+   * Create a Set<string>-compatible adapter for use with validateIntent().
+   *
+   * Returns an object that looks like Set<string> with .has() and .add()
+   * but uses async persistent storage under the hood.
+   *
+   * IMPORTANT: The returned adapter makes .has() and .add() synchronous-looking
+   * by maintaining a local cache that's flushed asynchronously. For strict
+   * distributed replay protection, use the async methods directly.
+   */
+  toSyncAdapter(): Set<string> & { flush(): Promise<void> } {
+    const self = this;
+    const pendingAdds: Array<{ nonce: string; ttl?: number }> = [];
+    const localCache = new Set<string>();
+
+    type AdapterType = Set<string> & { flush(): Promise<void> };
+
+    const adapter: AdapterType = {
+      has(nonce: string): boolean {
+        return localCache.has(nonce);
+      },
+      add(nonce: string): AdapterType {
+        localCache.add(nonce);
+        pendingAdds.push({ nonce });
+        return adapter;
+      },
+      get size() {
+        return localCache.size;
+      },
+      async flush(): Promise<void> {
+        for (const { nonce } of pendingAdds) {
+          await self.add(nonce);
+        }
+        pendingAdds.length = 0;
+      },
+      // Satisfy Set interface minimally
+      delete: (nonce: string) => localCache.delete(nonce),
+      clear: () => localCache.clear(),
+      forEach: (cb: (v: string, v2: string, s: Set<string>) => void) => localCache.forEach(cb),
+      entries: () => localCache.entries(),
+      keys: () => localCache.keys(),
+      values: () => localCache.values(),
+      [Symbol.iterator]: () => localCache[Symbol.iterator](),
+      [Symbol.toStringTag]: 'NonceStore',
+    };
+
+    return adapter as Set<string> & { flush(): Promise<void> };
+  }
+
+  /**
+   * Pre-load nonces from the store into a local Set for synchronous checking.
+   * Useful at startup to restore state from a previous session.
+   */
+  async preload(): Promise<Set<string>> {
+    const keys = await this.store.keys(this.prefix);
+    const set = new Set<string>();
+    for (const key of keys) {
+      set.add(key.slice(this.prefix.length));
+    }
+    return set;
+  }
+}

package/src/rate-limit.ts

@@ -0,0 +1,141 @@
+/**
+ * Rate-limit response headers per RFC 6585 / draft-ietf-httpapi-ratelimit-headers.
+ *
+ * Adds standard headers so clients know their quota status:
+ *   RateLimit-Limit:     total requests allowed per window
+ *   RateLimit-Remaining: requests remaining in current window
+ *   RateLimit-Reset:     seconds until window resets
+ *   Retry-After:         seconds to wait (only on 429)
+ */
+
+import type { ServerResponse } from 'node:http';
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+export interface RateLimitInfo {
+  /** Maximum requests per window */
+  limit: number;
+  /** Remaining requests in current window */
+  remaining: number;
+  /** When the window resets (Unix timestamp in seconds) */
+  resetAt: number;
+}
+
+// ─── Header Application ──────────────────────────────────────────────
+
+/**
+ * Set rate limit headers on a response.
+ */
+export function setRateLimitHeaders(res: ServerResponse, info: RateLimitInfo): void {
+  const retryAfter = Math.max(0, Math.ceil(info.resetAt - Date.now() / 1000));
+
+  res.setHeader('RateLimit-Limit', String(info.limit));
+  res.setHeader('RateLimit-Remaining', String(Math.max(0, info.remaining)));
+  res.setHeader('RateLimit-Reset', String(retryAfter));
+}
+
+/**
+ * Send a 429 Too Many Requests response with Retry-After header.
+ */
+export function sendRateLimited(res: ServerResponse, info: RateLimitInfo): void {
+  const retryAfter = Math.max(1, Math.ceil(info.resetAt - Date.now() / 1000));
+
+  res.writeHead(429, {
+    'Content-Type': 'application/json',
+    'Retry-After': String(retryAfter),
+    'RateLimit-Limit': String(info.limit),
+    'RateLimit-Remaining': '0',
+    'RateLimit-Reset': String(retryAfter),
+  });
+  res.end(JSON.stringify({
+    error: 'Too Many Requests',
+    retryAfter,
+  }));
+}
+
+// ─── Enhanced Rate Limiter ──────────────────────────────────────────
+
+/**
+ * Production-grade rate limiter with header support.
+ */
+export class RateLimiter {
+  private windows = new Map<string, { count: number; resetAt: number }>();
+
+  constructor(
+    private maxRequests: number,
+    private windowMs: number
+  ) {}
+
+  /**
+   * Check if a request is allowed and return rate limit info.
+   */
+  check(key: string): { allowed: boolean; info: RateLimitInfo } {
+    const now = Date.now();
+    const entry = this.windows.get(key);
+
+    if (!entry || now >= entry.resetAt) {
+      const resetAt = now + this.windowMs;
+      this.windows.set(key, { count: 1, resetAt });
+      return {
+        allowed: true,
+        info: {
+          limit: this.maxRequests,
+          remaining: this.maxRequests - 1,
+          resetAt: Math.ceil(resetAt / 1000),
+        },
+      };
+    }
+
+    if (entry.count >= this.maxRequests) {
+      return {
+        allowed: false,
+        info: {
+          limit: this.maxRequests,
+          remaining: 0,
+          resetAt: Math.ceil(entry.resetAt / 1000),
+        },
+      };
+    }
+
+    entry.count++;
+    return {
+      allowed: true,
+      info: {
+        limit: this.maxRequests,
+        remaining: this.maxRequests - entry.count,
+        resetAt: Math.ceil(entry.resetAt / 1000),
+      },
+    };
+  }
+
+  /**
+   * Clean up expired windows to prevent memory leaks.
+   * Call periodically (e.g., every 5 minutes).
+   */
+  cleanup(): number {
+    const now = Date.now();
+    let removed = 0;
+    for (const [key, entry] of this.windows) {
+      if (now >= entry.resetAt) {
+        this.windows.delete(key);
+        removed++;
+      }
+    }
+    return removed;
+  }
+}
+
+/**
+ * Parse a rate limit spec like "100/min" into limiter parameters.
+ */
+export function parseRateLimit(spec: string): { max: number; windowMs: number } {
+  const match = spec.match(/^(\d+)\/(min|hour|day)$/);
+  if (!match) return { max: 100, windowMs: 60_000 };
+
+  const max = parseInt(match[1]);
+  const windowMs = match[2] === 'min' ? 60_000
+    : match[2] === 'hour' ? 3_600_000
+    : 86_400_000;
+
+  return { max, windowMs };
+}

package/src/security-headers.ts

@@ -0,0 +1,79 @@
+/**
+ * Security Response Headers — standard HTTP security headers for all Sentinel servers.
+ *
+ * Sets headers recommended by OWASP:
+ *   X-Content-Type-Options: nosniff
+ *   X-Frame-Options: DENY
+ *   X-XSS-Protection: 0  (modern browsers use CSP instead)
+ *   Content-Security-Policy: default-src 'none'
+ *   Strict-Transport-Security: max-age=31536000; includeSubDomains (when TLS)
+ *   Referrer-Policy: strict-origin-when-cross-origin
+ *   Permissions-Policy: camera=(), microphone=(), geolocation=()
+ */
+
+import type { ServerResponse } from 'node:http';
+
+export interface SecurityHeadersConfig {
+  /** Whether to add HSTS header (only makes sense over TLS) */
+  hsts?: boolean;
+  /** HSTS max-age in seconds (default: 31536000 = 1 year) */
+  hstsMaxAge?: number;
+  /** Custom Content-Security-Policy (default: "default-src 'none'") */
+  contentSecurityPolicy?: string;
+  /** Custom Permissions-Policy */
+  permissionsPolicy?: string;
+  /** Whether to add X-Frame-Options (default: true) */
+  frameOptions?: boolean;
+}
+
+/**
+ * Apply standard security headers to a response.
+ */
+export function applySecurityHeaders(
+  res: ServerResponse,
+  config?: SecurityHeadersConfig
+): void {
+  // Prevent MIME type sniffing
+  res.setHeader('X-Content-Type-Options', 'nosniff');
+
+  // Disable legacy XSS filter (CSP is the modern approach)
+  res.setHeader('X-XSS-Protection', '0');
+
+  // Content Security Policy
+  res.setHeader(
+    'Content-Security-Policy',
+    config?.contentSecurityPolicy ?? "default-src 'none'"
+  );
+
+  // Clickjacking protection
+  if (config?.frameOptions !== false) {
+    res.setHeader('X-Frame-Options', 'DENY');
+  }
+
+  // Referrer policy
+  res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
+
+  // Permissions policy
+  res.setHeader(
+    'Permissions-Policy',
+    config?.permissionsPolicy ?? 'camera=(), microphone=(), geolocation=()'
+  );
+
+  // HSTS (only over TLS)
+  if (config?.hsts) {
+    const maxAge = config.hstsMaxAge ?? 31_536_000;
+    res.setHeader('Strict-Transport-Security', `max-age=${maxAge}; includeSubDomains`);
+  }
+}
+
+/**
+ * Create a security headers config from environment variables.
+ *
+ * SENTINEL_HSTS=true (enabled when TLS is enabled)
+ */
+export function securityHeadersConfigFromEnv(): SecurityHeadersConfig {
+  return {
+    hsts: process.env['SENTINEL_HSTS'] === 'true' ||
+          !!process.env['SENTINEL_TLS_CERT'],
+  };
+}