@dotdo/postgres 0.1.0

package/dist/worker/auth.js

@@ -0,0 +1,837 @@
+import { TokenCache, extractBearerToken, generateDatabaseId as sharedGenerateDatabaseId, validateToken as sharedValidateToken, DEFAULT_OAUTH_URL, DEFAULT_TOKEN_CACHE_TTL, } from '@dotdo/postgres-shared';
+// ============================================================================
+// 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',
+};
+/**
+ * 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.',
+};
+/**
+ * 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, b) {
+    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'];
+/**
+ * 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();
+/**
+ * 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() {
+    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() {
+    // 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) {
+    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() {
+    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() {
+    return {
+        size: authFailureRateLimiter.size,
+        maxSize: RATE_LIMIT_MAX_ENTRIES,
+        lastCleanupTime,
+    };
+}
+/**
+ * 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) {
+    // 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;
+    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;
+    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 = [
+    /--/, // 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
+];
+/**
+ * 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) {
+    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) {
+    // 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);
+}
+/**
+ * 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 = {
+    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) {
+    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() {
+    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() {
+    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 = {}) {
+    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 = {
+            maxSize: cacheConfig.maxSize ?? 1000,
+            defaultTTL: cacheConfig.ttl ?? tokenCacheTTL,
+            cleanupInterval: cacheConfig.cleanupInterval ?? 60000,
+        };
+        configureTokenCache(tokenCacheConfig);
+    }
+    return async (c, 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,
+            });
+            return next();
+        }
+        const token = extractBearerToken(c.req.raw);
+        if (!token) {
+            if (allowAnonymous) {
+                c.set('auth', {
+                    user: null,
+                    token: null,
+                    isAuthenticated: false,
+                    databaseId: null,
+                });
+                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),
+        });
+        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() {
+    return async (c, next) => {
+        const auth = c.get('auth');
+        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) {
+    const auth = c.get('auth');
+    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) {
+    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) {
+    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, userId) {
+    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, userId) {
+    const id = getUserDOId(namespace, userId);
+    return namespace.get(id);
+}
+//# sourceMappingURL=auth.js.map