@dotdo/postgres 0.1.0

package/src/worker/auth.ts

@@ -0,0 +1,1104 @@
+/**
+ * Authentication middleware for PostgresDO Worker routes
+ * Integrates with oauth.do for token validation and user-scoped database access
+ *
+ * Security features:
+ * - JWT structure validation (3 segments)
+ * - Algorithm validation (rejects alg:none)
+ * - Token expiration checking (exp/nbf claims)
+ * - Empty signature rejection
+ * - Rate limiting for auth failures
+ * - SQL injection prevention in database IDs
+ * - Token length limits (DoS prevention)
+ */
+import type { Context, Next, MiddlewareHandler } from 'hono'
+
+// Re-export Env for external use
+export type { Env } from './types'
+import {
+  TokenCache,
+  type TokenCacheConfig,
+  type CacheStats,
+  // Re-export shared auth types and utilities
+  type AuthenticatedUser,
+  type AuthTokenValidationResult as TokenValidationResult,
+  extractBearerToken,
+  generateDatabaseId as sharedGenerateDatabaseId,
+  validateToken as sharedValidateToken,
+  DEFAULT_OAUTH_URL,
+  DEFAULT_TOKEN_CACHE_TTL,
+} from '@dotdo/postgres-shared'
+
+// Re-export for backwards compatibility
+export type { AuthenticatedUser, TokenValidationResult }
+
+// ============================================================================
+// Security Constants
+// ============================================================================
+
+/**
+ * Maximum allowed JWT token length in bytes.
+ *
+ * @security Prevents DoS attacks via oversized tokens that could exhaust memory
+ *           or CPU during parsing. 8KB is generous for legitimate JWTs while
+ *           blocking maliciously large payloads.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7519 - JWT specification
+ */
+const MAX_TOKEN_LENGTH = 8192
+
+/**
+ * Maximum allowed clock skew between server and token issuer in seconds.
+ *
+ * @security Allows for reasonable time differences between systems while
+ *           preventing replay attacks with expired tokens. 60 seconds is
+ *           standard practice for distributed systems.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4 - exp claim
+ * @see https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5 - nbf claim
+ */
+const MAX_CLOCK_SKEW_SECONDS = 60
+
+/**
+ * Time window for rate limiting in milliseconds (1 minute).
+ *
+ * @security Sliding window for tracking authentication failures per token prefix.
+ *           Balances security (blocking brute force) with usability (not too short).
+ */
+const RATE_LIMIT_WINDOW_MS = 60000
+
+/**
+ * Maximum authentication failures allowed per rate limit window.
+ *
+ * @security Prevents brute force and credential stuffing attacks. 10 failures
+ *           per minute is strict enough to stop automated attacks while allowing
+ *           for legitimate user errors.
+ */
+const RATE_LIMIT_MAX_FAILURES = 10
+
+/**
+ * Prefix for rate limit tracking keys.
+ *
+ * @security Uses token prefix (first 20 chars) to prevent attackers from
+ *           evading rate limits by rotating tokens while keeping signature.
+ */
+const RATE_LIMIT_KEY_PREFIX = 'token:'
+
+/**
+ * Number of token characters used for rate limit key generation.
+ *
+ * @security 20 characters is enough to identify unique tokens without
+ *           storing full tokens in memory for rate limiting.
+ */
+const RATE_LIMIT_KEY_LENGTH = 20
+
+/**
+ * Maximum number of rate limit entries to store in memory.
+ *
+ * @security Prevents memory exhaustion attacks where an attacker sends requests
+ *           with many unique token prefixes to grow the Map unboundedly.
+ *           10,000 entries at ~100 bytes each = ~1MB memory budget.
+ */
+const RATE_LIMIT_MAX_ENTRIES = 10000
+
+/**
+ * Interval for cleaning up expired rate limit entries in milliseconds.
+ *
+ * @security Periodic cleanup prevents memory leaks from expired entries.
+ *           Every 5 minutes balances cleanup overhead with memory efficiency.
+ */
+const RATE_LIMIT_CLEANUP_INTERVAL_MS = 300000
+
+// ============================================================================
+// Error Codes - Consistent error response codes
+// ============================================================================
+
+/**
+ * Standardized error codes for authentication failures.
+ * These codes are exposed in API responses to help clients understand failures.
+ */
+export const AUTH_ERROR_CODES = {
+  /** No token provided */
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  /** Token failed validation */
+  INVALID_TOKEN: 'INVALID_TOKEN',
+  /** Too many failed attempts */
+  RATE_LIMITED: 'RATE_LIMITED',
+} as const
+
+export type AuthErrorCode = (typeof AUTH_ERROR_CODES)[keyof typeof AUTH_ERROR_CODES]
+
+/**
+ * Standardized error messages for authentication failures.
+ * Consistent messages improve security by not leaking implementation details.
+ */
+export const AUTH_ERROR_MESSAGES = {
+  [AUTH_ERROR_CODES.UNAUTHORIZED]: 'Missing authentication token',
+  [AUTH_ERROR_CODES.INVALID_TOKEN]: 'Invalid authentication token',
+  [AUTH_ERROR_CODES.RATE_LIMITED]: 'Too many authentication failures. Please try again later.',
+} as const
+
+/**
+ * Performs a timing-safe comparison of two strings.
+ *
+ * @security This function uses constant-time comparison to prevent timing attacks.
+ *           Timing attacks can leak information about the secret by measuring
+ *           how long the comparison takes.
+ *
+ * @param a - First string to compare
+ * @param b - Second string to compare
+ * @returns true if strings are equal, false otherwise
+ */
+export function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) {
+    // Still do comparison to prevent timing leaks on length difference
+    let result = 0
+    for (let i = 0; i < a.length; i++) {
+      result |= a.charCodeAt(i) ^ (b.charCodeAt(i % b.length) || 0)
+    }
+    return false
+  }
+
+  let result = 0
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i)
+  }
+  return result === 0
+}
+
+// ============================================================================
+// Default Configuration Values
+// ============================================================================
+
+/**
+ * Default paths that bypass authentication.
+ *
+ * @security These paths expose minimal information and are required for
+ *           health checks and load balancer probes. No sensitive data
+ *           should ever be exposed on these endpoints.
+ */
+const DEFAULT_PUBLIC_PATHS = ['/ping', '/health']
+
+// ============================================================================
+// Rate Limiting
+// ============================================================================
+
+/**
+ * Tracks authentication failures within a sliding time window.
+ */
+interface RateLimitEntry {
+  /** Number of failures in the current window */
+  count: number
+  /** Timestamp when the current window started */
+  windowStart: number
+}
+
+/**
+ * In-memory rate limiter for authentication failures.
+ *
+ * @security This is a simple sliding window rate limiter. In production with
+ *           multiple Workers, consider using Durable Objects or external
+ *           storage for distributed rate limiting.
+ *
+ * @note Keys are token prefixes, not full tokens, to prevent memory exhaustion
+ *       while still providing per-token-family rate limiting.
+ *
+ * Memory bounds:
+ * - Max entries: 10,000 (RATE_LIMIT_MAX_ENTRIES)
+ * - Periodic cleanup: every 5 minutes (RATE_LIMIT_CLEANUP_INTERVAL_MS)
+ * - LRU-style eviction when at capacity
+ */
+const authFailureRateLimiter = new Map<string, RateLimitEntry>()
+
+/**
+ * Timestamp of the last cleanup operation.
+ * Used to track when periodic cleanup should run.
+ */
+let lastCleanupTime = Date.now()
+
+/**
+ * Performs cleanup of expired rate limit entries.
+ * Called lazily during checkRateLimit to avoid needing a timer.
+ *
+ * @security This prevents memory leaks from accumulated expired entries.
+ *           Uses lazy cleanup during normal operations instead of a timer
+ *           to work better with Cloudflare Workers' event-driven model.
+ *
+ * @returns Number of entries removed
+ */
+function cleanupExpiredRateLimitEntries(): number {
+  const now = Date.now()
+  let removed = 0
+
+  // Remove entries older than the rate limit window
+  for (const [key, entry] of authFailureRateLimiter) {
+    if (now - entry.windowStart > RATE_LIMIT_WINDOW_MS) {
+      authFailureRateLimiter.delete(key)
+      removed++
+    }
+  }
+
+  lastCleanupTime = now
+  return removed
+}
+
+/**
+ * Evicts oldest entries when rate limiter is at capacity.
+ * Uses Map iteration order (insertion order) for LRU-like eviction.
+ *
+ * @security Prevents memory exhaustion from attackers creating many unique
+ *           rate limit keys. Evicts 10% of entries to amortize eviction cost.
+ */
+function evictOldestEntries(): void {
+  // Evict 10% of max entries to amortize eviction overhead
+  const evictCount = Math.ceil(RATE_LIMIT_MAX_ENTRIES / 10)
+  let evicted = 0
+
+  for (const key of authFailureRateLimiter.keys()) {
+    if (evicted >= evictCount) break
+    authFailureRateLimiter.delete(key)
+    evicted++
+  }
+}
+
+/**
+ * Checks if a request should be rate limited based on prior failures.
+ *
+ * Uses a sliding window algorithm:
+ * 1. If no entry exists or window expired, start a new window with count=1
+ * 2. Otherwise, increment the failure count
+ * 3. Return true if count exceeds the threshold
+ *
+ * Memory safety:
+ * - Runs periodic cleanup every RATE_LIMIT_CLEANUP_INTERVAL_MS
+ * - Evicts oldest entries when at RATE_LIMIT_MAX_ENTRIES capacity
+ *
+ * @security Prevents brute force attacks by limiting authentication attempts.
+ *           Attack vector: Attacker tries many passwords/tokens in rapid succession.
+ *           Mitigation: After 10 failures in 60 seconds, all requests with that
+ *           token prefix are blocked.
+ *
+ * @param key - Rate limit key (typically "token:" + first 20 chars of token)
+ * @returns true if the request should be rate limited, false otherwise
+ */
+function checkRateLimit(key: string): boolean {
+  const now = Date.now()
+
+  // Lazy cleanup: run periodically during normal operations
+  // This avoids needing a timer which doesn't work well in Workers
+  if (now - lastCleanupTime > RATE_LIMIT_CLEANUP_INTERVAL_MS) {
+    cleanupExpiredRateLimitEntries()
+  }
+
+  // Check if we need to evict before adding a new entry
+  if (!authFailureRateLimiter.has(key) && authFailureRateLimiter.size >= RATE_LIMIT_MAX_ENTRIES) {
+    evictOldestEntries()
+  }
+
+  const entry = authFailureRateLimiter.get(key)
+
+  if (!entry || now - entry.windowStart > RATE_LIMIT_WINDOW_MS) {
+    authFailureRateLimiter.set(key, { count: 1, windowStart: now })
+    return false
+  }
+
+  entry.count++
+  return entry.count > RATE_LIMIT_MAX_FAILURES
+}
+
+/**
+ * Clears all rate limit state. Intended for testing only.
+ *
+ * @security In production, this should never be exposed to external callers.
+ *           Only exported for use in test cleanup between test cases.
+ */
+export function clearRateLimitState(): void {
+  authFailureRateLimiter.clear()
+  lastCleanupTime = Date.now()
+}
+
+/**
+ * Get rate limiter statistics for monitoring.
+ *
+ * @returns Current rate limiter stats including size and last cleanup time
+ */
+export function getRateLimiterStats(): { size: number; maxSize: number; lastCleanupTime: number } {
+  return {
+    size: authFailureRateLimiter.size,
+    maxSize: RATE_LIMIT_MAX_ENTRIES,
+    lastCleanupTime,
+  }
+}
+
+// ============================================================================
+// JWT Security Validation
+// ============================================================================
+
+/**
+ * Result of JWT security validation.
+ */
+interface JWTSecurityResult {
+  /** Whether the token passed all security checks */
+  valid: boolean
+  /** Human-readable error message if validation failed */
+  error?: string
+  /** Decoded JWT header if parsing succeeded */
+  header?: Record<string, unknown>
+  /** Decoded JWT payload if parsing succeeded */
+  payload?: Record<string, unknown>
+}
+
+/**
+ * Validates a JWT token against security requirements BEFORE cryptographic verification.
+ *
+ * This function performs structural and timing validation to reject obviously
+ * invalid or malicious tokens without incurring the cost of signature verification.
+ *
+ * @security This function prevents the following attack vectors:
+ *
+ * 1. **DoS via oversized tokens**: Attackers send huge tokens to exhaust memory/CPU.
+ *    Mitigation: Reject tokens > 8KB before any parsing.
+ *
+ * 2. **Algorithm confusion (alg:none)**: Attacker crafts unsigned token with alg:none.
+ *    Mitigation: Explicitly reject none/None/NONE algorithms.
+ *    @see https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/
+ *
+ * 3. **Replay attacks with expired tokens**: Attacker captures and replays old tokens.
+ *    Mitigation: Check exp claim with 60-second clock skew tolerance.
+ *
+ * 4. **Future-dated tokens**: Attacker creates tokens with nbf far in the future.
+ *    Mitigation: Check nbf claim with 60-second clock skew tolerance.
+ *
+ * 5. **SQL injection via claims**: Attacker embeds SQL in sub claim to attack database.
+ *    Mitigation: Validate sub claim against SQL injection patterns.
+ *
+ * 6. **Empty signature bypass**: Attacker sends token with empty signature segment.
+ *    Mitigation: Explicitly check signature is non-empty.
+ *
+ * @param token - Raw JWT string from Authorization header
+ * @returns Validation result with decoded header/payload if successful
+ *
+ * @example
+ * ```typescript
+ * const result = validateJWTSecurity(token)
+ * if (!result.valid) {
+ *   return unauthorized(result.error)
+ * }
+ * // Proceed to cryptographic verification
+ * ```
+ */
+function validateJWTSecurity(token: string): JWTSecurityResult {
+  // SECURITY: Prevent DoS via oversized tokens
+  if (token.length > MAX_TOKEN_LENGTH) {
+    return { valid: false, error: 'Token exceeds maximum length' }
+  }
+
+  // SECURITY: JWT must have exactly 3 segments (header.payload.signature)
+  const parts = token.split('.')
+  if (parts.length !== 3) {
+    return { valid: false, error: 'Invalid JWT structure - must have 3 segments' }
+  }
+
+  const [headerB64, payloadB64, signature] = parts
+
+  // SECURITY: Empty segments indicate malformed or crafted tokens
+  if (!headerB64 || !payloadB64) {
+    return { valid: false, error: 'Invalid JWT - empty header or payload' }
+  }
+
+  // SECURITY: Empty signature indicates unsigned token (potential alg:none bypass)
+  if (!signature || signature.length === 0) {
+    return { valid: false, error: 'Invalid JWT - empty signature' }
+  }
+
+  // Parse and validate header
+  let header: Record<string, unknown>
+  try {
+    header = JSON.parse(atob(headerB64))
+  } catch {
+    return { valid: false, error: 'Invalid JWT header encoding' }
+  }
+
+  // SECURITY: Explicitly reject alg:none and common case variations
+  // This is a critical security check - the alg:none attack is well-documented
+  const alg = header.alg
+  if (!alg || alg === 'none' || alg === 'None' || alg === 'NONE') {
+    return { valid: false, error: 'Invalid algorithm - alg:none not allowed' }
+  }
+
+  // Parse and validate payload
+  let payload: Record<string, unknown>
+  try {
+    payload = JSON.parse(atob(payloadB64))
+  } catch {
+    return { valid: false, error: 'Invalid JWT payload encoding' }
+  }
+
+  const now = Math.floor(Date.now() / 1000)
+
+  // SECURITY: Validate exp claim type and value
+  if (payload.exp !== undefined) {
+    // exp must be a finite number (not string, array, object, NaN, or Infinity)
+    if (typeof payload.exp !== 'number' || !Number.isFinite(payload.exp)) {
+      return { valid: false, error: 'Invalid exp claim - must be a finite number' }
+    }
+    const exp = payload.exp
+    // Reject tokens at or past their expiration (exp === now means expired)
+    if (exp + MAX_CLOCK_SKEW_SECONDS <= now) {
+      return { valid: false, error: 'Token has expired' }
+    }
+    // SECURITY: Reject tokens with unreasonably long lifetime (max 7 days)
+    const maxFutureExp = now + 7 * 24 * 60 * 60
+    if (exp > maxFutureExp) {
+      return { valid: false, error: 'Token expiration too far in future' }
+    }
+  }
+
+  // SECURITY: Validate nbf claim type and value
+  if (payload.nbf !== undefined) {
+    if (typeof payload.nbf !== 'number' || !Number.isFinite(payload.nbf)) {
+      return { valid: false, error: 'Invalid nbf claim - must be a finite number' }
+    }
+    const nbf = payload.nbf
+    // Reject tokens at exactly the skew boundary (strict)
+    if (nbf - MAX_CLOCK_SKEW_SECONDS >= now) {
+      return { valid: false, error: 'Token not yet valid' }
+    }
+  }
+
+  // SECURITY: Validate iat claim type and check for future-dated tokens
+  if (payload.iat !== undefined) {
+    if (typeof payload.iat !== 'number' || !Number.isFinite(payload.iat)) {
+      return { valid: false, error: 'Invalid iat claim - must be a finite number' }
+    }
+    const iat = payload.iat
+    // Reject tokens issued too far in the future (clock manipulation)
+    if (iat - MAX_CLOCK_SKEW_SECONDS > now) {
+      return { valid: false, error: 'Token issued in the future' }
+    }
+    // SECURITY: Reject tokens with iat set far in the past (lifetime manipulation)
+    const maxPastIat = now - 365 * 24 * 60 * 60 // Max 1 year ago
+    if (iat < maxPastIat) {
+      return { valid: false, error: 'Token issued too long ago' }
+    }
+  }
+
+  // SECURITY: Validate that exp > nbf when both are present
+  if (payload.exp !== undefined && payload.nbf !== undefined) {
+    if (payload.exp <= payload.nbf) {
+      return { valid: false, error: 'Invalid token - exp must be greater than nbf' }
+    }
+  }
+
+  // SECURITY: Check sub claim - must be a string if present
+  const sub = payload.sub
+  if (sub !== undefined && typeof sub !== 'string') {
+    return { valid: false, error: 'Invalid sub claim - must be a string' }
+  }
+  // SECURITY: Check sub claim for SQL injection patterns
+  if (typeof sub === 'string' && containsSQLInjection(sub)) {
+    return { valid: false, error: 'Invalid user ID - contains forbidden characters' }
+  }
+
+  // SECURITY: Check email claim for SQL injection patterns
+  const email = payload.email
+  if (email !== undefined) {
+    if (typeof email !== 'string') {
+      return { valid: false, error: 'Invalid email claim - must be a string' }
+    }
+    if (containsSQLInjection(email)) {
+      return { valid: false, error: 'Invalid email - contains forbidden characters' }
+    }
+  }
+
+  return { valid: true, header, payload }
+}
+
+/**
+ * SQL injection patterns to detect in user-controlled input.
+ *
+ * @security Each pattern targets a specific SQL injection technique:
+ *
+ * - `--` : SQL comment syntax, used to truncate queries
+ * - `;`  : Statement terminator, enables multi-statement injection
+ * - `'`  : String delimiter, enables string escaping attacks
+ * - `"`  : Identifier delimiter, enables identifier injection
+ * - `/*` : Block comment start, used to obfuscate injections
+ * - `* /`: Block comment end, paired with start for injection
+ * - `DROP/DELETE/INSERT/UPDATE/SELECT/UNION`: Destructive or data-exfiltrating keywords
+ *
+ * @note This is a defense-in-depth measure. Primary SQL injection prevention
+ *       should use parameterized queries. This catches malicious data before
+ *       it reaches the database layer.
+ */
+const SQL_INJECTION_PATTERNS: readonly RegExp[] = [
+  /--/, // SQL line comment - truncates query
+  /;/, // Statement terminator - allows chaining
+  /'/, // String delimiter - escaping attacks
+  /"/, // Identifier delimiter - injection
+  /\/\*/, // Block comment start - obfuscation
+  /\*\//, // Block comment end - obfuscation
+  /\bDROP\b/i, // DDL - data destruction
+  /\bDELETE\b/i, // DML - data deletion
+  /\bINSERT\b/i, // DML - unauthorized inserts
+  /\bUPDATE\b/i, // DML - data modification
+  /\bSELECT\b/i, // DQL - data exfiltration
+  /\bUNION\b/i, // Set operator - query manipulation
+] as const
+
+/**
+ * Detects potential SQL injection patterns in a string.
+ *
+ * @security This is a blocklist-based detection. It catches common SQL injection
+ *           patterns but should NOT be the only line of defense. Always use
+ *           parameterized queries for database operations.
+ *
+ * @param value - String to check for SQL injection patterns
+ * @returns true if any SQL injection pattern is detected
+ *
+ * @example
+ * ```typescript
+ * containsSQLInjection("user123")           // false - safe
+ * containsSQLInjection("admin'--")          // true - comment injection
+ * containsSQLInjection("1; DROP TABLE")     // true - statement chaining
+ * ```
+ */
+function containsSQLInjection(value: string): boolean {
+  return SQL_INJECTION_PATTERNS.some((pattern) => pattern.test(value))
+}
+
+/**
+ * Generates a safe, deterministic database identifier from a user ID.
+ *
+ * @security This function provides defense-in-depth sanitization before
+ *           generating the database ID. Even though validateJWTSecurity
+ *           already checks for SQL injection, this ensures any user ID
+ *           that reaches the database layer is safe.
+ *
+ * Sanitization rules:
+ * - `--` -> `_` : Prevents SQL comment injection
+ * - `/*` -> `_` : Prevents block comment start
+ * - `* /`-> `_` : Prevents block comment end
+ * - `;`  -> `_` : Prevents statement chaining
+ * - `'`  -> `_` : Prevents string delimiter attacks
+ * - `"`  -> `_` : Prevents identifier injection
+ *
+ * @param userId - User identifier from JWT sub claim
+ * @returns Safe database identifier in format "user_{sanitized_id}"
+ *
+ * @example
+ * ```typescript
+ * generateDatabaseId("user123")           // "user_user123"
+ * generateDatabaseId("admin'--")          // "user_admin___"
+ * generateDatabaseId("test@example.com")  // "user_test_example_com"
+ * ```
+ */
+export function generateDatabaseId(userId: string): string {
+  // SECURITY: Ensure userId is a string (defense-in-depth)
+  if (typeof userId !== 'string') {
+    throw new Error('Invalid userId - must be a string')
+  }
+
+  // SECURITY: Replace all non-alphanumeric characters with underscores
+  // This is the most secure approach - only allow safe characters
+  const sanitized = userId
+    // First handle null bytes and control characters
+    .replace(/\x00/g, '_') // Null byte
+    .replace(/[\x01-\x1f\x7f]/g, '_') // Control characters
+    // Handle common SQL injection patterns
+    .replace(/--/g, '_') // SQL comment
+    .replace(/\/\*/g, '_') // Block comment start
+    .replace(/\*\//g, '_') // Block comment end
+    // Handle shell injection patterns
+    .replace(/\$/g, '_') // Shell variable
+    .replace(/`/g, '_') // Shell backtick
+    .replace(/\|/g, '_') // Pipe
+    .replace(/&/g, '_') // Background/AND
+    // Handle individual dangerous characters
+    .replace(/;/g, '_') // Statement terminator / shell separator
+    .replace(/'/g, '_') // String delimiter
+    .replace(/"/g, '_') // Identifier delimiter
+    .replace(/\\/g, '_') // Escape character
+    .replace(/\n/g, '_') // Newline
+    .replace(/\r/g, '_') // Carriage return
+    // Final sanitization: only allow alphanumeric, underscore, hyphen, dot, @
+    // Then replace anything else
+    .replace(/[^a-zA-Z0-9_\-\.@]/g, '_')
+
+  return sharedGenerateDatabaseId(sanitized)
+}
+
+/**
+ * Configuration for the token validation cache.
+ *
+ * @security Caching reduces load on the OAuth provider but introduces a
+ *           window where revoked tokens may still be accepted. Balance
+ *           TTL based on your security requirements.
+ */
+export interface AuthTokenCacheConfig {
+  /** Maximum number of tokens to cache (default: 1000) */
+  maxSize?: number
+  /** Cache TTL in milliseconds (default: 60000 = 1 minute) */
+  ttl?: number
+  /** Interval for cleanup of expired entries in ms (default: 60000) */
+  cleanupInterval?: number
+}
+
+/**
+ * Configuration options for the authentication middleware.
+ *
+ * @security Review all options carefully - incorrect configuration can
+ *           create security vulnerabilities.
+ */
+export interface AuthConfig {
+  /**
+   * OAuth provider URL for token validation.
+   * @default 'https://oauth.do'
+   */
+  oauthUrl?: string
+
+  /**
+   * How long to cache valid tokens in milliseconds.
+   * @default 60000 (1 minute)
+   * @security Lower values improve security (faster revocation) at cost of
+   *           more OAuth provider requests. Higher values improve performance
+   *           but delay token revocation.
+   */
+  tokenCacheTTL?: number
+
+  /**
+   * Advanced cache configuration options.
+   * Overrides tokenCacheTTL if ttl is specified.
+   */
+  cacheConfig?: AuthTokenCacheConfig
+
+  /**
+   * Custom token validation function.
+   * Use this to integrate with custom OAuth providers or add additional validation.
+   *
+   * @security Your validator MUST verify the cryptographic signature.
+   *           Returning valid:true without signature verification is a
+   *           critical vulnerability.
+   */
+  validateToken?: (token: string) => Promise<TokenValidationResult>
+
+  /**
+   * Allow requests without authentication tokens.
+   * @default false
+   * @security Only enable if your application explicitly handles anonymous users.
+   *           Anonymous users should have minimal permissions.
+   */
+  allowAnonymous?: boolean
+
+  /**
+   * Paths that bypass authentication entirely.
+   * @default ['/ping', '/health']
+   * @security Keep this list minimal. Only include endpoints that expose
+   *           no sensitive data and are needed for infrastructure (health checks).
+   */
+  publicPaths?: string[]
+
+  /**
+   * Custom handler for unauthorized requests.
+   * Use to customize error responses or redirect to login pages.
+   */
+  onUnauthorized?: (c: Context) => Response
+}
+
+/**
+ * Authentication context available in request handlers.
+ *
+ * Access via `getAuth(c)` or `c.get('auth')`.
+ */
+export interface AuthContext {
+  /** Authenticated user info, null if not authenticated */
+  user: AuthenticatedUser | null
+  /** Raw JWT token, null if not provided */
+  token: string | null
+  /** True if user is authenticated */
+  isAuthenticated: boolean
+  /** Database ID for this user's isolated database, null if not authenticated */
+  databaseId: string | null
+}
+
+/**
+ * Default cache configuration values.
+ *
+ * @security These defaults balance security and performance:
+ * - 1000 entries: Limits memory usage
+ * - 60s TTL: Quick revocation while reducing OAuth provider load
+ * - 60s cleanup: Regular purging of expired entries
+ */
+const DEFAULT_CACHE_CONFIG: TokenCacheConfig = {
+  maxSize: 1000,
+  defaultTTL: 60000,
+  cleanupInterval: 60000,
+}
+
+/**
+ * Global token validation cache instance.
+ * @internal
+ */
+let tokenCache = new TokenCache(DEFAULT_CACHE_CONFIG)
+
+/**
+ * Reconfigures the global token cache with new settings.
+ * Disposes the existing cache and creates a new one.
+ *
+ * @param config - New cache configuration
+ *
+ * @example
+ * ```typescript
+ * configureTokenCache({
+ *   maxSize: 5000,      // More entries for high-traffic apps
+ *   defaultTTL: 30000,  // 30 second TTL for faster revocation
+ * })
+ * ```
+ */
+export function configureTokenCache(config: TokenCacheConfig): void {
+  tokenCache.dispose()
+  tokenCache = new TokenCache({
+    ...DEFAULT_CACHE_CONFIG,
+    ...config,
+  })
+}
+
+/**
+ * Returns current token cache statistics for monitoring.
+ *
+ * @returns Cache stats including hits, misses, and size
+ */
+export function getTokenCacheStats(): CacheStats {
+  return tokenCache.stats
+}
+
+/**
+ * Clears all cached tokens. Intended for testing only.
+ *
+ * @security In production, avoid clearing the cache as it will cause
+ *           a thundering herd to the OAuth provider.
+ */
+export function clearTokenCache(): void {
+  tokenCache.clear()
+}
+
+export { extractBearerToken }
+
+/**
+ * Creates a Hono middleware handler that validates JWT tokens.
+ *
+ * This middleware:
+ * 1. Skips authentication for public paths
+ * 2. Extracts Bearer token from Authorization header
+ * 3. Applies rate limiting for failed attempts
+ * 4. Validates JWT structure and security claims
+ * 5. Validates token with OAuth provider (with caching)
+ * 6. Sets authenticated user context
+ *
+ * @security The middleware applies multiple layers of validation in order
+ *           of computational cost - cheap checks first (structure, rate limit)
+ *           before expensive checks (OAuth provider validation).
+ *
+ * @param config - Authentication configuration options
+ * @returns Hono middleware handler
+ *
+ * @example
+ * ```typescript
+ * const app = new Hono()
+ * app.use('*', createAuthMiddleware({
+ *   publicPaths: ['/ping', '/health', '/docs'],
+ *   tokenCacheTTL: 30000, // 30 second cache
+ * }))
+ * ```
+ */
+export function createAuthMiddleware(config: AuthConfig = {}): MiddlewareHandler {
+  const {
+    oauthUrl = DEFAULT_OAUTH_URL,
+    tokenCacheTTL = DEFAULT_TOKEN_CACHE_TTL,
+    cacheConfig,
+    validateToken,
+    allowAnonymous = false,
+    publicPaths = DEFAULT_PUBLIC_PATHS,
+    onUnauthorized,
+  } = config
+
+  if (cacheConfig) {
+    // Build config without undefined values for exactOptionalPropertyTypes
+    // Use explicit default values to avoid assigning potentially-undefined optional properties
+    const tokenCacheConfig: TokenCacheConfig = {
+      maxSize: cacheConfig.maxSize ?? 1000,
+      defaultTTL: cacheConfig.ttl ?? tokenCacheTTL,
+      cleanupInterval: cacheConfig.cleanupInterval ?? 60000,
+    }
+    configureTokenCache(tokenCacheConfig)
+  }
+
+  return async (c: Context, next: Next) => {
+    const path = new URL(c.req.url).pathname
+    if (publicPaths.some((p) => path === p || path.startsWith(p + '/'))) {
+      c.set('auth', {
+        user: null,
+        token: null,
+        isAuthenticated: false,
+        databaseId: null,
+      } as AuthContext)
+      return next()
+    }
+
+    const token = extractBearerToken(c.req.raw)
+
+    if (!token) {
+      if (allowAnonymous) {
+        c.set('auth', {
+          user: null,
+          token: null,
+          isAuthenticated: false,
+          databaseId: null,
+        } as AuthContext)
+        return next()
+      }
+
+      if (onUnauthorized) {
+        return onUnauthorized(c)
+      }
+
+      return c.json(
+        {
+          error: true,
+          code: AUTH_ERROR_CODES.UNAUTHORIZED,
+          message: 'Missing authentication token',
+        },
+        401
+      )
+    }
+
+    // SECURITY: Use token prefix for rate limit key to prevent evasion
+    const rateLimitKey = RATE_LIMIT_KEY_PREFIX + token.slice(0, RATE_LIMIT_KEY_LENGTH)
+
+    if (checkRateLimit(rateLimitKey)) {
+      return c.json(
+        {
+          error: true,
+          code: AUTH_ERROR_CODES.RATE_LIMITED,
+          message: 'Too many authentication failures. Please try again later.',
+        },
+        429
+      )
+    }
+
+    const securityCheck = validateJWTSecurity(token)
+    if (!securityCheck.valid) {
+      if (onUnauthorized) {
+        return onUnauthorized(c)
+      }
+
+      return c.json(
+        {
+          error: true,
+          code: AUTH_ERROR_CODES.INVALID_TOKEN,
+          message: securityCheck.error || 'Token failed security validation',
+        },
+        401
+      )
+    }
+
+    let validationResult = tokenCache.get(token)
+
+    if (!validationResult) {
+      validationResult = validateToken
+        ? await validateToken(token)
+        : await sharedValidateToken(token, { oauthUrl })
+
+      if (validationResult.valid) {
+        tokenCache.set(token, validationResult, tokenCacheTTL)
+      }
+    }
+
+    if (!validationResult.valid) {
+      if (onUnauthorized) {
+        return onUnauthorized(c)
+      }
+
+      return c.json(
+        {
+          error: true,
+          code: AUTH_ERROR_CODES.INVALID_TOKEN,
+          message: validationResult.error || 'Invalid authentication token',
+        },
+        401
+      )
+    }
+
+    const user = validationResult.user!
+    c.set('auth', {
+      user,
+      token,
+      isAuthenticated: true,
+      databaseId: generateDatabaseId(user.id),
+    } as AuthContext)
+
+    return next()
+  }
+}
+
+/**
+ * Creates a middleware that enforces authentication.
+ *
+ * Use this on routes that MUST have an authenticated user.
+ * For routes that work with optional authentication, use
+ * createAuthMiddleware with allowAnonymous:true instead.
+ *
+ * @returns Hono middleware handler
+ *
+ * @example
+ * ```typescript
+ * app.get('/api/private', requireAuth(), (c) => {
+ *   const user = requireUser(c)
+ *   return c.json({ userId: user.id })
+ * })
+ * ```
+ */
+export function requireAuth(): MiddlewareHandler {
+  return async (c: Context, next: Next) => {
+    const auth = c.get('auth') as AuthContext | undefined
+
+    if (!auth?.isAuthenticated) {
+      return c.json(
+        {
+          error: true,
+          code: AUTH_ERROR_CODES.UNAUTHORIZED,
+          message: 'Authentication required',
+        },
+        401
+      )
+    }
+
+    return next()
+  }
+}
+
+/**
+ * Retrieves the authentication context from a request.
+ *
+ * Returns a default unauthenticated context if none is set.
+ * This is safe to call on any route, even those without auth middleware.
+ *
+ * @param c - Hono context
+ * @returns Authentication context
+ *
+ * @example
+ * ```typescript
+ * app.get('/api/data', (c) => {
+ *   const auth = getAuth(c)
+ *   if (auth.isAuthenticated) {
+ *     return c.json({ user: auth.user })
+ *   }
+ *   return c.json({ guest: true })
+ * })
+ * ```
+ */
+export function getAuth(c: Context): AuthContext {
+  const auth = c.get('auth') as AuthContext | undefined
+  return (
+    auth || {
+      user: null,
+      token: null,
+      isAuthenticated: false,
+      databaseId: null,
+    }
+  )
+}
+
+/**
+ * Retrieves the authenticated user or throws an error.
+ *
+ * Use this in routes protected by requireAuth() where you need
+ * the user object and want TypeScript to know it's non-null.
+ *
+ * @param c - Hono context
+ * @returns Authenticated user
+ * @throws Error if user is not authenticated
+ *
+ * @example
+ * ```typescript
+ * app.get('/api/profile', requireAuth(), (c) => {
+ *   const user = requireUser(c) // Type: AuthenticatedUser (not null)
+ *   return c.json({ email: user.email })
+ * })
+ * ```
+ */
+export function requireUser(c: Context): AuthenticatedUser {
+  const auth = getAuth(c)
+  if (!auth.user) {
+    throw new Error('User not authenticated')
+  }
+  return auth.user
+}
+
+/**
+ * Retrieves the database ID for the authenticated user or throws an error.
+ *
+ * The database ID is a sanitized, deterministic identifier derived from
+ * the user ID. Use this to access the user's isolated database.
+ *
+ * @param c - Hono context
+ * @returns Database ID string (e.g., "user_abc123")
+ * @throws Error if user is not authenticated
+ *
+ * @example
+ * ```typescript
+ * app.get('/api/data', requireAuth(), (c) => {
+ *   const dbId = getDatabaseId(c)
+ *   const db = await getDatabase(dbId)
+ *   // ...
+ * })
+ * ```
+ */
+export function getDatabaseId(c: Context): string {
+  const auth = getAuth(c)
+  if (!auth.databaseId) {
+    throw new Error('User not authenticated - no database ID')
+  }
+  return auth.databaseId
+}
+
+/**
+ * Gets the Durable Object ID for a user's database.
+ *
+ * @param namespace - Durable Object namespace binding
+ * @param userId - User identifier from JWT
+ * @returns Durable Object ID for the user's database
+ *
+ * @example
+ * ```typescript
+ * const doId = getUserDOId(env.POSTGRES_DO, user.id)
+ * const stub = env.POSTGRES_DO.get(doId)
+ * ```
+ */
+export function getUserDOId(namespace: DurableObjectNamespace, userId: string): DurableObjectId {
+  const databaseId = generateDatabaseId(userId)
+  return namespace.idFromName(databaseId)
+}
+
+/**
+ * Gets a Durable Object stub for a user's database.
+ *
+ * Convenience function that combines getUserDOId and namespace.get().
+ *
+ * @param namespace - Durable Object namespace binding
+ * @param userId - User identifier from JWT
+ * @returns Durable Object stub for the user's database
+ *
+ * @example
+ * ```typescript
+ * const stub = getUserDOStub(env.POSTGRES_DO, user.id)
+ * const response = await stub.fetch(request)
+ * ```
+ */
+export function getUserDOStub(
+  namespace: DurableObjectNamespace,
+  userId: string
+): DurableObjectStub {
+  const id = getUserDOId(namespace, userId)
+  return namespace.get(id)
+}