@stacksjs/bun-router 0.0.15 → 0.0.17

package/src/file-serving/static-files.ts

@@ -18,6 +18,12 @@ export interface StaticFileConfig {
   compressionThreshold?: number
   cacheControl?: string
   dotfiles?: 'allow' | 'deny' | 'ignore'
+  /**
+   * Files larger than this (bytes) are streamed straight from disk via
+   * `Bun.file()` instead of being buffered into the in-memory cache.
+   * Streamed responses support HTTP Range requests (206). Default: 5 MiB.
+   */
+  maxCacheFileSize?: number
 }
 
 export interface FileCache {
@@ -62,6 +68,7 @@ export class StaticFileServer {
       compressionThreshold: config.compressionThreshold ?? 1024,
       cacheControl: config.cacheControl ?? '',
       dotfiles: config.dotfiles ?? 'ignore',
+      maxCacheFileSize: config.maxCacheFileSize ?? 5 * 1024 * 1024, // 5 MiB
       ...config,
     }
   }
@@ -71,10 +78,19 @@ export class StaticFileServer {
    */
   async serve(request: Request): Promise<Response | null> {
     const url = new URL(request.url)
-    const pathname = decodeURIComponent(url.pathname)
 
-    // Security: prevent directory traversal
-    if (pathname.includes('..') || pathname.includes('\0')) {
+    // Malformed percent-encoding must not crash the server with a 500
+    let pathname: string
+    try {
+      pathname = decodeURIComponent(url.pathname)
+    }
+    catch {
+      return new Response('Bad Request', { status: 400 })
+    }
+
+    // Security: prevent directory traversal (the check runs after
+    // decoding, so encoded forms like %2e%2e are covered too)
+    if (pathname.includes('..') || pathname.includes('\0') || pathname.includes('\\')) {
       return new Response('Forbidden', { status: 403 })
     }
 
@@ -122,6 +138,12 @@ export class StaticFileServer {
         return this.serveCachedFile(request, cached, requestPath, startTime)
       }
 
+      // Large files are streamed straight from disk (with Range support)
+      // instead of buffered into the in-memory cache
+      if (size > this.config.maxCacheFileSize) {
+        return this.serveStreamedFile(request, filePath, requestPath, lastModified, startTime)
+      }
+
       // Read and cache file
       const content = await file.arrayBuffer()
       const mimeType = file.type || this.getMimeType(filePath)
@@ -226,6 +248,75 @@ export class StaticFileServer {
     return new Response(content, { headers })
   }
 
+  /**
+   * Stream a file from disk without buffering it into memory.
+   * Supports single-range HTTP Range requests (RFC 9110 §14).
+   */
+  private serveStreamedFile(
+    request: Request,
+    filePath: string,
+    requestPath: string,
+    lastModified: string,
+    startTime: number,
+  ): Response {
+    const file = Bun.file(filePath)
+    const size = file.size
+    const mimeType = file.type || this.getMimeType(filePath)
+
+    const headers = new Headers()
+    headers.set('Content-Type', mimeType)
+    headers.set('Accept-Ranges', 'bytes')
+
+    if (this.config.lastModified) {
+      headers.set('Last-Modified', lastModified)
+      if (request.headers.get('if-modified-since') === lastModified) {
+        this.updateStats(requestPath, 0, startTime, true)
+        return new Response(null, { status: 304, headers })
+      }
+    }
+
+    if (this.config.cacheControl) {
+      headers.set('Cache-Control', this.config.cacheControl)
+    }
+    else {
+      headers.set('Cache-Control', this.config.immutable
+        ? `public, max-age=${this.config.maxAge}, immutable`
+        : `public, max-age=${this.config.maxAge}`)
+    }
+
+    // Single-range requests: "bytes=start-end", "bytes=start-", "bytes=-suffix"
+    const rangeHeader = request.headers.get('range')
+    const rangeMatch = rangeHeader?.match(/^bytes=(\d*)-(\d*)$/)
+    if (rangeMatch && (rangeMatch[1] !== '' || rangeMatch[2] !== '')) {
+      let start: number
+      let end: number
+      if (rangeMatch[1] === '') {
+        // Suffix range: last N bytes
+        const suffixLength = Number(rangeMatch[2])
+        start = Math.max(0, size - suffixLength)
+        end = size - 1
+      }
+      else {
+        start = Number(rangeMatch[1])
+        end = rangeMatch[2] === '' ? size - 1 : Math.min(Number(rangeMatch[2]), size - 1)
+      }
+
+      if (start > end || start >= size) {
+        headers.set('Content-Range', `bytes */${size}`)
+        return new Response(null, { status: 416, headers })
+      }
+
+      headers.set('Content-Range', `bytes ${start}-${end}/${size}`)
+      headers.set('Content-Length', String(end - start + 1))
+      this.updateStats(requestPath, end - start + 1, startTime, false)
+      return new Response(file.slice(start, end + 1), { status: 206, headers })
+    }
+
+    headers.set('Content-Length', String(size))
+    this.updateStats(requestPath, size, startTime, false)
+    return new Response(file, { headers })
+  }
+
   /**
    * Resolve file path, handling index files and extensions
    */
@@ -380,6 +471,15 @@ export class StaticFileServer {
     this.compressionCache.clear()
   }
 
+  /**
+   * Invalidate a single cached file (e.g. from a file watcher), leaving
+   * the rest of the cache warm.
+   */
+  invalidateFile(filePath: string): void {
+    this.cache.delete(filePath)
+    this.compressionCache.delete(filePath)
+  }
+
   /**
    * Get cache size
    */
@@ -567,15 +667,52 @@ export const FileServingUtils = {
    */
   createFileWatcher: async (server: StaticFileServer, watchPath: string): Promise<{ close: () => void }> => {
     const fs = await import('node:fs')
-    const watcher = fs.watch(watchPath, { recursive: true }, (eventType: string, filename: string | null) => {
-      if (eventType === 'change' || eventType === 'rename') {
+    const path = await import('node:path')
+
+    // Changes are debounced and invalidated per-file: a burst of writes
+    // (build output, git checkout) used to flush the entire cache once
+    // per event. Events without a filename still fall back to a full clear.
+    const pendingFiles = new Set<string>()
+    let fullClear = false
+    let debounceTimer: ReturnType<typeof setTimeout> | null = null
+
+    const flush = () => {
+      debounceTimer = null
+      if (fullClear) {
         server.clearCache()
-        console.warn(`File changed: ${filename || 'unknown'}, cache cleared`)
       }
+      else {
+        for (const file of pendingFiles) {
+          server.invalidateFile(file)
+        }
+      }
+      pendingFiles.clear()
+      fullClear = false
+    }
+
+    const watcher = fs.watch(watchPath, { recursive: true }, (eventType: string, filename: string | null) => {
+      if (eventType !== 'change' && eventType !== 'rename') {
+        return
+      }
+      if (filename) {
+        pendingFiles.add(path.join(watchPath, filename))
+      }
+      else {
+        fullClear = true
+      }
+      if (debounceTimer) {
+        clearTimeout(debounceTimer)
+      }
+      debounceTimer = setTimeout(flush, 100)
     })
 
     return {
-      close: () => watcher.close(),
+      close: () => {
+        if (debounceTimer) {
+          clearTimeout(debounceTimer)
+        }
+        watcher.close()
+      },
     }
   },
 }

package/src/index.ts

@@ -1,14 +1,66 @@
+/**
+ * @stacksjs/bun-router — a fast, type-safe router for Bun.
+ *
+ * Main entry point. The most commonly used exports:
+ * - `Router` — the primary router class (from `./router`)
+ * - `FluentRouter` / `router` — chainable routing API
+ * - `Auth`, `JWT`, `ApiKeyManager`, `OAuth2Helper` — auth helpers
+ * - `Container`, `createContainer` — dependency-injection container
+ * - `url()` / `registerNamedRoute()` — named-route URL generation
+ * - `Errors` — namespaced error/exception types
+ */
+
+// Authentication (JWT, API keys, OAuth2)
 export { default as Auth } from './auth'
 export * from './auth'
+
+// Runtime configuration
 export * from './config'
+
+// Dependency-injection container. Exported by name — the decorator module
+// (`Get`, `Post`, `Controller`, …) would collide with router exports if
+// star-exported; import those from `@stacksjs/bun-router/container/decorators`.
+export {
+  BindingBuilder,
+  Container,
+  createContainer,
+  getContainer,
+  setContainer,
+} from './container/container'
+export type { Binding, BindingScope, ContainerOptions, ResolutionContext, Token } from './container/container'
+export { ContextualContainer, EnvironmentManager } from './container/contextual-binding'
+export { DefaultServiceProviderManager } from './container/service-provider'
+
+// Error types and helpers (namespaced — many generic names)
 export * as Errors from './errors'
+
+// Built-in middleware (CORS, CSRF, sessions, rate limiting, …)
 export * from './middleware'
-export { getCurrentRequest, request, runWithRequest, setCurrentRequest } from './request/context'
+
+// Request context (AsyncLocalStorage-backed current request; lazy — see enableRequestContext)
+export { enableRequestContext, getCurrentRequest, request, runWithRequest, setCurrentRequest } from './request/context'
+
+// Session stores and manager
 export * from './session'
+
+// Response factory helpers
 export * from './response/response-factory'
+
+// The Router class and routing features (fluent API, throttling, caching, …)
 export * from './router'
 export { MiddlewareGroupRegistry, middlewareGroups } from './router/middleware-groups'
+
+// Testing utilities
 export * from './testing'
+
+// Public types
 export * from './types'
+
+// Validation (Laravel-style rules, custom rules, middleware)
+export * from './validation/validator'
+
+// Named-route URL generation
 export { clearNamedRoutes, getNamedRoutePath, getNamedRoutes, registerNamedRoute, url, type UrlOptions } from './url'
+
+// Path/template utilities
 export * from './utils'

package/src/middleware/cors.ts

@@ -1,32 +1,100 @@
 import type { EnhancedRequest, NextFunction } from '../types'
 import { config } from '../config'
 
-// Default CORS headers
+// Default CORS headers.
+//
+// IMPORTANT: when credentials are NOT enabled it is safe to allow any origin
+// with `*`. The default config below deliberately keeps credentials disabled.
+// The `*` + `Allow-Credentials: true` combination is forbidden by the CORS
+// spec and is dangerous (it lets any site read credentialed responses), so the
+// logic in `getCorsHeaders` guarantees that combination can never be emitted.
 const DEFAULT_CORS_HEADERS: Record<string, string> = {
   'Access-Control-Allow-Origin': '*',
   'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH, OPTIONS',
   'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Requested-With, Accept, Origin',
   'Access-Control-Max-Age': '86400',
-  'Access-Control-Allow-Credentials': 'true',
 }
 
 export default class Cors {
-  private getCorsHeaders(): Record<string, string> {
-    const corsConfig = (config.server as any)?.cors
+  /**
+   * Resolve the `Access-Control-Allow-Origin` value for a request.
+   *
+   * Supports a string origin (`'*'` or an explicit origin) or an array of
+   * allowed origins. For an allowlist, the request `Origin` is reflected back
+   * only when it is present in the list. When credentials are enabled a literal
+   * `*` is never returned (it would be both spec-violating and dangerous).
+   */
+  private resolveAllowOrigin(
+    configuredOrigin: string | string[] | undefined,
+    credentials: boolean,
+    requestOrigin: string | null,
+  ): { value: string | null, vary: boolean } {
+    // Explicit allowlist: only reflect the request origin when it matches.
+    if (Array.isArray(configuredOrigin)) {
+      if (requestOrigin && configuredOrigin.includes(requestOrigin)) {
+        return { value: requestOrigin, vary: true }
+      }
+      // Origin not allowed: do not emit an Allow-Origin header at all.
+      return { value: null, vary: true }
+    }
+
+    const origin = configuredOrigin || '*'
+
+    if (origin === '*') {
+      // The `*` wildcard cannot be combined with credentials. When credentials
+      // are enabled, reflect the specific request origin instead (which is the
+      // only spec-compliant way to support credentialed cross-origin requests).
+      if (credentials) {
+        if (requestOrigin) {
+          return { value: requestOrigin, vary: true }
+        }
+        // No request origin to reflect — omit the header rather than send `*`.
+        return { value: null, vary: true }
+      }
+      return { value: '*', vary: false }
+    }
+
+    // A single explicit origin was configured.
+    return { value: origin, vary: false }
+  }
+
+  private getCorsHeaders(req: EnhancedRequest): Record<string, string> {
+    const corsConfig = config.server?.cors
+    const requestOrigin = req.headers.get('origin')
+
     if (corsConfig && corsConfig.enabled) {
-      return {
-        'Access-Control-Allow-Origin': corsConfig.origin || '*',
+      const credentials = Boolean(corsConfig.credentials)
+      const { value: allowOrigin, vary } = this.resolveAllowOrigin(corsConfig.origin, credentials, requestOrigin)
+
+      const headers: Record<string, string> = {
         'Access-Control-Allow-Methods': Array.isArray(corsConfig.methods) ? corsConfig.methods.join(', ') : DEFAULT_CORS_HEADERS['Access-Control-Allow-Methods'],
         'Access-Control-Allow-Headers': Array.isArray(corsConfig.allowedHeaders) ? corsConfig.allowedHeaders.join(', ') : DEFAULT_CORS_HEADERS['Access-Control-Allow-Headers'],
         'Access-Control-Max-Age': String(corsConfig.maxAge || 86400),
-        'Access-Control-Allow-Credentials': String(corsConfig.credentials || false),
       }
+
+      if (allowOrigin !== null) {
+        headers['Access-Control-Allow-Origin'] = allowOrigin
+      }
+
+      // Only advertise credentials when an origin is actually allowed. Never
+      // pair credentials with a `*` wildcard.
+      if (credentials && allowOrigin !== null && allowOrigin !== '*') {
+        headers['Access-Control-Allow-Credentials'] = 'true'
+      }
+
+      if (vary) {
+        headers.Vary = 'Origin'
+      }
+
+      return headers
     }
+
+    // No CORS config: fall back to the permissive (but credential-free) defaults.
     return { ...DEFAULT_CORS_HEADERS }
   }
 
   async handle(req: EnhancedRequest, next: NextFunction): Promise<Response> {
-    const corsHeaders = this.getCorsHeaders()
+    const corsHeaders = this.getCorsHeaders(req)
 
     // Handle preflight OPTIONS request
     if (req.method === 'OPTIONS') {

package/src/middleware/csrf.ts

@@ -1,25 +1,27 @@
-import type { EnhancedRequest, NextFunction } from '../types'
-import { createHash, randomBytes } from 'node:crypto'
+import type { EnhancedRequest, NextFunction, SecurityConfig } from '../types'
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
 import { config } from '../config'
 
+/** Maximum number of issued tokens kept for verification (oldest evicted first). */
+const MAX_TOKENS = 10_000
+
+/** Token lifetime in milliseconds. */
+const TOKEN_TTL_MS = 2 * 60 * 60 * 1000 // 2 hours
+
 export default class Csrf {
-  private static tokens = new Map<string, string>()
+  // Issued tokens with their issue timestamp. Bounded (LRU by insertion
+  // order) and TTL'd — the previous implementation grew without limit.
+  private static tokens = new Map<string, number>()
 
   async handle(req: EnhancedRequest, next: NextFunction): Promise<Response> {
-    const csrfConfig = config.server?.security?.csrf || {} as any
-
-    // Skip CSRF protection for safe methods
-    if (['GET', 'HEAD', 'OPTIONS'].includes(req.method)) {
-      const response = await next()
-      return response || new Response('Not Found', { status: 404 })
-    }
+    const csrfConfig: Partial<SecurityConfig['csrf']> = config.server?.security?.csrf ?? {}
 
-    // Skip for methods that don't modify state
     const method = req.method.toUpperCase()
     const ignoredMethods = ['GET', 'HEAD', 'OPTIONS', ...(csrfConfig?.ignoreMethods || [])]
 
     if (ignoredMethods.includes(method)) {
-      // For safe methods, generate a new token for the response
+      // Safe methods don't need verification, but the response carries a
+      // fresh token cookie so the client has something to submit later
       const token = this.generateToken(csrfConfig?.secret || 'csrf-secret')
 
       // Continue to next middleware
@@ -50,8 +52,8 @@ export default class Csrf {
       const newHeaders = new Headers(response.headers)
       newHeaders.append('Set-Cookie', cookieOptions.join('; '))
 
-      // Store token for verification
-      Csrf.tokens.set(token, token)
+      // Store token for verification (bounded + TTL)
+      Csrf.storeToken(token)
 
       return new Response(response.body, {
         status: response.status,
@@ -60,19 +62,33 @@ export default class Csrf {
       })
     }
 
+    // Bearer-authed requests can't be CSRF'd — the token doesn't
+    // ride on cookies, so a hostile origin can't trick a browser into
+    // sending it. Mirrors Laravel Sanctum / Django REST framework /
+    // express-csurf semantics. Filed against stacksjs/stacks#1922.
+    const authHeader = req.headers.get('authorization') ?? req.headers.get('Authorization')
+    if (authHeader && /^Bearer\s+\S/i.test(authHeader)) {
+      const response = await next()
+      return response || new Response('Not Found', { status: 404 })
+    }
+
     // For unsafe methods, verify the CSRF token
     // Check for token in headers or in the request body
-    const token = req.headers.get('X-CSRF-TOKEN')
+    const rawToken = req.headers.get('X-CSRF-TOKEN')
       || req.jsonBody?.csrf_token
       || req.jsonBody?._token
       || null
+    const token = typeof rawToken === 'string' ? rawToken : null
 
     // Get token from cookies for comparison
     const cookies = this.parseCookies(req)
     const cookieToken = cookies[csrfConfig?.cookie?.name || 'csrf-token']
 
-    // Verify the token
-    if (!token || !cookieToken || token !== cookieToken || !Csrf.tokens.has(token)) {
+    // Verify the token: double-submit value must match the cookie
+    // (constant-time comparison) and must have been issued by us
+    if (!token || !cookieToken
+      || !Csrf.safeCompare(token, cookieToken)
+      || !Csrf.isTokenValid(token)) {
       return new Response(
         JSON.stringify({ error: 'CSRF token validation failed' }),
         {
@@ -87,6 +103,42 @@ export default class Csrf {
     return response || new Response('Not Found', { status: 404 })
   }
 
+  /**
+   * Constant-time string comparison — a plain `!==` leaks how many leading
+   * characters of the token were correct through response timing.
+   */
+  private static safeCompare(a: string, b: string): boolean {
+    const bufA = Buffer.from(a)
+    const bufB = Buffer.from(b)
+    if (bufA.length !== bufB.length) {
+      return false
+    }
+    return timingSafeEqual(bufA, bufB)
+  }
+
+  private static storeToken(token: string): void {
+    if (Csrf.tokens.size >= MAX_TOKENS) {
+      // Evict the oldest issued token (Map preserves insertion order)
+      const oldest = Csrf.tokens.keys().next().value
+      if (oldest !== undefined) {
+        Csrf.tokens.delete(oldest)
+      }
+    }
+    Csrf.tokens.set(token, Date.now())
+  }
+
+  private static isTokenValid(token: string): boolean {
+    const issuedAt = Csrf.tokens.get(token)
+    if (issuedAt === undefined) {
+      return false
+    }
+    if (Date.now() - issuedAt > TOKEN_TTL_MS) {
+      Csrf.tokens.delete(token)
+      return false
+    }
+    return true
+  }
+
   private generateToken(secret: string): string {
     const randomString = randomBytes(16).toString('hex')
     return createHash('sha256')
@@ -99,10 +151,16 @@ export default class Csrf {
     if (!cookieHeader)
       return {}
 
-    return cookieHeader.split(';').reduce((cookies, cookie) => {
-      const [name, value] = cookie.trim().split('=')
-      cookies[name] = value
-      return cookies
-    }, {} as Record<string, string>)
+    const cookies: Record<string, string> = {}
+    for (const cookie of cookieHeader.split(';')) {
+      const eqIndex = cookie.indexOf('=')
+      if (eqIndex === -1)
+        continue
+      const name = cookie.slice(0, eqIndex).trim()
+      if (!name)
+        continue
+      cookies[name] = cookie.slice(eqIndex + 1).trim()
+    }
+    return cookies
   }
 }

package/src/middleware/ddos_protection.ts

@@ -15,7 +15,7 @@ export interface DDoSProtectionOptions {
   skipSuccessfulRequests?: boolean
   skipFailedRequests?: boolean
   keyGenerator?: (req: EnhancedRequest) => string
-  onLimitReached?: (req: EnhancedRequest, rateLimitInfo: any) => Response | Promise<Response>
+  onLimitReached?: (req: EnhancedRequest, rateLimitInfo: DDoSRateLimitInfo) => Response | Promise<Response>
   store?: 'memory' | 'redis'
   redis?: {
     url: string
@@ -31,6 +31,14 @@ interface RequestInfo {
   blockExpires?: number
 }
 
+/**
+ * Rate-limit details passed to `onLimitReached` when a client is blocked.
+ */
+export interface DDoSRateLimitInfo extends RequestInfo {
+  /** Seconds until the block lifts (mirrors the Retry-After header) */
+  retryAfter: number
+}
+
 export default class DDoSProtection {
   private options: DDoSProtectionOptions
   private requestStore: Map<string, RequestInfo> = new Map()
@@ -91,6 +99,8 @@ export default class DDoSProtection {
         }
       }
     }, this.options.windowSize! / 2) // Cleanup every half window
+    // Background housekeeping must not keep the process alive
+    this.cleanupInterval.unref?.()
   }
 
   private isWhitelisted(ip: string): boolean {
@@ -105,6 +115,20 @@ export default class DDoSProtection {
     let info = this.requestStore.get(key)
 
     if (!info) {
+      // Hard cap on tracked clients: a spoofed-IP flood would otherwise
+      // grow the store faster than the interval cleanup can drain it.
+      // Evicting the oldest entries (Map insertion order) only resets
+      // counters for long-idle clients.
+      if (this.requestStore.size >= 100_000) {
+        let toEvict = Math.ceil(this.requestStore.size / 10)
+        for (const oldestKey of this.requestStore.keys()) {
+          this.requestStore.delete(oldestKey)
+          if (--toEvict <= 0) {
+            break
+          }
+        }
+      }
+
       info = {
         count: 0,
         firstRequest: now,
@@ -149,7 +173,7 @@ export default class DDoSProtection {
     info.blockExpires = now + this.options.blockDuration!
   }
 
-  private createBlockedResponse(req: EnhancedRequest, info: RequestInfo): Response {
+  private createBlockedResponse(req: EnhancedRequest, info: RequestInfo): Response | Promise<Response> {
     const retryAfter = Math.ceil((info.blockExpires! - Date.now()) / 1000)
 
     const headers = {
@@ -160,7 +184,7 @@ export default class DDoSProtection {
     }
 
     if (this.options.onLimitReached) {
-      return this.options.onLimitReached(req, { ...info, retryAfter }) as Response
+      return this.options.onLimitReached(req, { ...info, retryAfter })
     }
 
     return new Response(JSON.stringify({

package/src/middleware/input_validation.ts

@@ -1,6 +1,10 @@
 import type { EnhancedRequest, NextFunction } from '../types'
 import { config } from '../config'
 
+// Hoisted format regexes — previously compiled on every validation call
+const EMAIL_REGEX = /^[^\s@]+@[^\s@][^\s.@]*\.[^\s@]+$/
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
 export interface ValidationRule {
   type: 'string' | 'number' | 'boolean' | 'email' | 'url' | 'uuid' | 'date' | 'regex' | 'custom'
   required?: boolean
@@ -148,8 +152,7 @@ export default class InputValidation {
         break
 
       case 'email': {
-        const emailRegex = /^[^\s@]+@[^\s@][^\s.@]*\.[^\s@]+$/
-        if (typeof value === 'string' && !emailRegex.test(value)) {
+        if (typeof value === 'string' && !EMAIL_REGEX.test(value)) {
           errors.push({
             field: fieldPath,
             message: 'Must be a valid email address',
@@ -174,8 +177,7 @@ export default class InputValidation {
         break
 
       case 'uuid': {
-        const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
-        if (typeof value === 'string' && !uuidRegex.test(value)) {
+        if (typeof value === 'string' && !UUID_REGEX.test(value)) {
           errors.push({
             field: fieldPath,
             message: 'Must be a valid UUID',
@@ -233,8 +235,10 @@ export default class InputValidation {
       })
     }
 
-    // Pattern validation
-    if (rule.pattern && typeof value === 'string' && !rule.pattern.test(value)) {
+    // Pattern validation — skipped for type 'regex', which already
+    // validated the pattern above (running it twice produced duplicate
+    // errors for the same field)
+    if (rule.type !== 'regex' && rule.pattern && typeof value === 'string' && !rule.pattern.test(value)) {
       errors.push({
         field: fieldPath,
         message: 'Does not match required pattern',

package/src/middleware/performance_alerting.ts

@@ -182,6 +182,8 @@ export default class PerformanceAlerting {
       this.cleanupOldNotifications()
       this.autoResolveAlerts()
     }, 10000) // Check every 10 seconds
+    // Background checks must not keep the process alive
+    this.checkInterval.unref?.()
   }
 
   private evaluateRules(): void {

package/src/middleware/performance_monitor.ts

@@ -269,6 +269,8 @@ export default class PerformanceMonitor implements Middleware {
     this.cleanupInterval = setInterval(() => {
       this.cleanupOldMetrics()
     }, 60000) // Cleanup every minute
+    // Background housekeeping must not keep the process alive
+    this.cleanupInterval.unref?.()
   }
 
   private cleanupOldMetrics(): void {