@mantiq/core 0.5.21 → 0.5.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantiq/core",
-  "version": "0.5.21",
+  "version": "0.5.22",
   "description": "Service container, router, middleware, HTTP kernel, config, and exception handler",
   "type": "module",
   "license": "MIT",

package/src/application/Application.ts

@@ -189,9 +189,7 @@ export class Application extends ContainerImpl {
             providers.push(mod[providerName])
           }
         } catch (e) {
-          if (process.env.APP_DEBUG === 'true') {
-            console.warn(`[Mantiq] Failed to load provider from ${file}:`, (e as Error)?.message ?? e)
-          }
+          console.warn(`[Mantiq] Failed to load provider from ${file}:`, (e as Error)?.message ?? e)
         }
       }
     } catch {
@@ -250,7 +248,12 @@ export class Application extends ContainerImpl {
    */
   async bootProviders(): Promise<void> {
     for (const provider of this.providers) {
-      await provider.boot()
+      try {
+        await provider.boot()
+      } catch (e) {
+        const name = provider.constructor?.name ?? 'Unknown'
+        console.error(`[Mantiq] ${name}.boot() failed:`, (e as Error)?.stack ?? e)
+      }
     }
     this.booted = true
   }
@@ -295,9 +298,11 @@ export class Application extends ContainerImpl {
             await deferredProvider.boot()
             this.providers.push(deferredProvider)
           }
-          // @internal: sync wrapper — deferred providers must not have async register/boot
-          // that relies on other async operations. In practice this is fine.
-          void boot()
+          // Deferred boot — catch and log errors instead of swallowing
+          boot().catch((e) => {
+            const name = deferredProvider.constructor?.name ?? 'DeferredProvider'
+            console.error(`[Mantiq] ${name} deferred boot failed:`, (e as Error)?.stack ?? e)
+          })
           return super.make(abstract)
         }
       }

package/src/cache/FileCacheStore.ts

@@ -91,6 +91,13 @@ export class FileCacheStore implements CacheStore {
     return this.increment(key, -value)
   }
 
+  /**
+   * Store an item in the cache if the key does not already exist.
+   *
+   * Note: File-based storage cannot guarantee atomicity. Between the existence
+   * check and the write, another process could set the key. For truly atomic
+   * add semantics, use the Redis or Memcached cache driver.
+   */
   async add(key: string, value: unknown, ttl?: number): Promise<boolean> {
     if (await this.has(key)) return false
     await this.put(key, value, ttl)

package/src/cache/MemoryCacheStore.ts

@@ -55,8 +55,20 @@ export class MemoryCacheStore implements CacheStore {
   }
 
   async add(key: string, value: unknown, ttl?: number): Promise<boolean> {
-    if (await this.has(key)) return false
-    await this.put(key, value, ttl)
+    // Atomic check-and-set: read the entry directly and check expiry in one step
+    // to avoid TOCTOU race between has() and put().
+    const existing = this.store.get(key)
+    if (existing) {
+      if (existing.expiresAt === null || Date.now() <= existing.expiresAt) {
+        return false
+      }
+      // Expired — remove and allow re-add
+      this.store.delete(key)
+    }
+    this.store.set(key, {
+      value,
+      expiresAt: ttl != null ? Date.now() + ttl * 1000 : null,
+    })
     return true
   }
 }

package/src/contracts/Request.ts

@@ -18,6 +18,10 @@ export interface MantiqRequest {
   has(...keys: string[]): boolean
   filled(...keys: string[]): Promise<boolean>
 
+  // ── Body errors ────────────────────────────────────────────────────────
+  hasBodyError(): boolean
+  bodyError(): Error | null
+
   // ── Headers & metadata ───────────────────────────────────────────────────
   header(key: string, defaultValue?: string): string | undefined
   headers(): Record<string, string>
@@ -50,6 +54,9 @@ export interface MantiqRequest {
   isAuthenticated(): boolean
   setUser(user: any): void
 
+  // ── FormData ────────────────────────────────────────────────────────────
+  formData(): Promise<FormData>
+
   // ── Raw ──────────────────────────────────────────────────────────────────
   raw(): Request
 }

package/src/discovery/Discoverer.ts

@@ -156,9 +156,7 @@ export class Discoverer {
           mod.default(router)
         }
       } catch (e) {
-        if (process.env.APP_DEBUG === 'true') {
-          console.warn(`[Mantiq] Failed to load route file ${file}:`, (e as Error)?.message ?? e)
-        }
+        console.warn(`[Mantiq] Failed to load route file ${file}:`, (e as Error)?.message ?? e)
       }
     }
   }

package/src/exceptions/DevErrorPage.ts

@@ -10,6 +10,21 @@ import type { MantiqRequest } from '../contracts/Request.ts'
  * - Copy as Markdown button
  * - Source file context when available
  */
+/**
+ * Security: headers that must never appear on the debug page, even in dev mode.
+ * These can contain authentication credentials, session tokens, and CSRF secrets.
+ */
+const SENSITIVE_HEADERS = new Set([
+  'authorization',
+  'cookie',
+  'set-cookie',
+  'x-csrf-token',
+  'x-xsrf-token',
+  'proxy-authorization',
+  'x-api-key',
+  'x-auth-token',
+])
+
 export function renderDevErrorPage(request: MantiqRequest, error: unknown): string {
   const err = error instanceof Error ? error : new Error(String(error))
   const stack = err.stack ?? err.message
@@ -51,8 +66,13 @@ export function renderDevErrorPage(request: MantiqRequest, error: unknown): stri
     })
     .join('')
 
+  // Security: redact sensitive headers to prevent leaking auth tokens,
+  // cookies, and CSRF secrets — even on the dev error page.
   const headersHtml = Object.entries(request.headers())
-    .map(([k, v]) => `<tr><td class="td-key">${escapeHtml(k)}</td><td class="td-val">${escapeHtml(v)}</td></tr>`)
+    .map(([k, v]) => {
+      const redacted = SENSITIVE_HEADERS.has(k.toLowerCase()) ? '********' : v
+      return `<tr><td class="td-key">${escapeHtml(k)}</td><td class="td-val">${escapeHtml(redacted)}</td></tr>`
+    })
     .join('')
 
   const queryString = request.fullUrl().includes('?') ? request.fullUrl().split('?')[1] : ''
@@ -63,14 +83,13 @@ export function renderDevErrorPage(request: MantiqRequest, error: unknown): stri
     }).join('')
     : '<tr><td class="td-val" colspan="2" style="opacity:.5">No query parameters</td></tr>'
 
-  // Markdown for clipboard
+  // Markdown for clipboard — also redact sensitive headers
   const markdown = [
     `# ${err.name}: ${err.message}`,
     '',
     `**Status:** ${statusCode}`,
     `**Method:** ${request.method()}`,
     `**URL:** ${request.fullUrl()}`,
-    `**IP:** ${request.ip()}`,
     `**User Agent:** ${request.userAgent()}`,
     '',
     '## Stack Trace',
@@ -81,7 +100,10 @@ export function renderDevErrorPage(request: MantiqRequest, error: unknown): stri
     '## Request Headers',
     '| Header | Value |',
     '|--------|-------|',
-    ...Object.entries(request.headers()).map(([k, v]) => `| ${k} | ${v} |`),
+    ...Object.entries(request.headers()).map(([k, v]) => {
+      const redacted = SENSITIVE_HEADERS.has(k.toLowerCase()) ? '********' : v
+      return `| ${k} | ${redacted} |`
+    }),
     '',
     `*Bun ${bunVersion} — MantiqJS*`,
   ].join('\n')
@@ -454,7 +476,7 @@ export function renderDevErrorPage(request: MantiqRequest, error: unknown): stri
             <tr><td class="td-key">Method</td><td class="td-val">${escapeHtml(request.method())}</td></tr>
             <tr><td class="td-key">Path</td><td class="td-val">${escapeHtml(request.path())}</td></tr>
             <tr><td class="td-key">Full URL</td><td class="td-val">${escapeHtml(request.fullUrl())}</td></tr>
-            <tr><td class="td-key">IP Address</td><td class="td-val">${escapeHtml(request.ip())}</td></tr>
+            <!-- Security: IP address omitted to prevent leaking client addresses in shared debug output -->
             <tr><td class="td-key">User Agent</td><td class="td-val">${escapeHtml(request.userAgent())}</td></tr>
             <tr><td class="td-key">Expects JSON</td><td class="td-val">${request.expectsJson() ? 'Yes' : 'No'}</td></tr>
             <tr><td class="td-key">Authenticated</td><td class="td-val">${request.isAuthenticated() ? 'Yes' : 'No'}</td></tr>

package/src/exceptions/Handler.ts

@@ -85,6 +85,7 @@ export class DefaultExceptionHandler implements ExceptionHandler {
   ): Response {
     // API routes always get JSON — even in debug mode
     if (request.expectsJson()) {
+      // Security: in production (debug=false), never expose error details
       const body: Record<string, any> = { error: { message: 'Internal Server Error', status: 500 } }
       if (debug && err.stack) {
         body['error']['message'] = err.message

package/src/http/Kernel.ts

@@ -99,9 +99,42 @@ export class HttpKernel {
 
     const request = MantiqRequest.fromBun(bunRequest)
 
+    // Pass the direct connection IP from Bun's server
+    const socketAddr = server.requestIP(bunRequest)
+    if (socketAddr) {
+      request.setConnectionIp(socketAddr.address)
+    }
+
+    // Configure trusted proxies and body size limit from config
+    let maxBodySize = 10 * 1024 * 1024 // default 10MB
+    try {
+      const config = this.container.make(ConfigRepository)
+      const proxies = config.get<string[]>('app.trustedProxies', [])
+      if (proxies && proxies.length > 0) {
+        request.setTrustedProxies(proxies)
+      }
+      maxBodySize = config.get<number>('app.maxBodySize', maxBodySize)
+    } catch {
+      // ConfigRepository may not be bound yet — leave defaults
+    }
+
+    // Reject oversized request bodies before reading them (413 Payload Too Large)
+    const contentLength = Number(bunRequest.headers.get('content-length'))
+    if (contentLength > maxBodySize) {
+      return new Response('Payload Too Large', { status: 413 })
+    }
+
     try {
-      // Combine prepend + global + append middleware (deduplicated, preserving order)
-      const allMiddleware = [...new Set([...this.prependMiddleware, ...this.globalMiddleware, ...this.appendMiddleware])]
+      // Combine prepend + global + append middleware
+      // Deduplicate exact duplicates but keep parameterized variants (auth:admin vs auth:user)
+      const seen = new Set<string>()
+      const allMiddleware: string[] = []
+      for (const mw of [...this.prependMiddleware, ...this.globalMiddleware, ...this.appendMiddleware]) {
+        if (!seen.has(mw)) {
+          seen.add(mw)
+          allMiddleware.push(mw)
+        }
+      }
       const globalClasses = this.resolveMiddlewareList(allMiddleware)
 
       const response = await new Pipeline(this.container)

package/src/http/Request.ts

@@ -11,6 +11,9 @@ export class MantiqRequest implements MantiqRequestContract {
   private authenticatedUser: any = null
   private cookies: Record<string, string> | null = null
   private sessionStore: SessionStore | null = null
+  private connectionIp: string = '127.0.0.1'
+  private trustedProxies: string[] = []
+  private _bodyError: Error | null = null
 
   constructor(
     private readonly bunRequest: Request,
@@ -86,6 +89,20 @@ export class MantiqRequest implements MantiqRequestContract {
     return keys.every((k) => all[k] !== undefined && all[k] !== '' && all[k] !== null)
   }
 
+  /**
+   * Whether a body parsing error occurred (malformed JSON, wrong content-type, etc.).
+   */
+  hasBodyError(): boolean {
+    return this._bodyError !== null
+  }
+
+  /**
+   * Return the body parsing error, or null if parsing succeeded.
+   */
+  bodyError(): Error | null {
+    return this._bodyError
+  }
+
   // ── Headers & metadata ───────────────────────────────────────────────────
 
   header(key: string, defaultValue?: string): string | undefined {
@@ -112,10 +129,28 @@ export class MantiqRequest implements MantiqRequestContract {
   }
 
   ip(): string {
-    // @internal: Bun doesn't expose IP on Request — callers should pass it via middleware if needed
-    return this.header('x-forwarded-for')?.split(',')[0]?.trim()
-      ?? this.header('x-real-ip')
-      ?? '127.0.0.1'
+    // Only trust proxy headers when the direct connection comes from a trusted proxy
+    if (this.trustedProxies.length > 0 && this.trustedProxies.includes(this.connectionIp)) {
+      const forwarded = this.header('x-forwarded-for')?.split(',')[0]?.trim()
+      if (forwarded) return forwarded
+      const realIp = this.header('x-real-ip')
+      if (realIp) return realIp
+    }
+    return this.connectionIp
+  }
+
+  /**
+   * Set the direct connection IP address (from the server/socket).
+   */
+  setConnectionIp(ip: string): void {
+    this.connectionIp = ip
+  }
+
+  /**
+   * Configure which proxy IPs are trusted to set X-Forwarded-For / X-Real-IP.
+   */
+  setTrustedProxies(proxies: string[]): void {
+    this.trustedProxies = proxies
   }
 
   userAgent(): string {
@@ -213,6 +248,12 @@ export class MantiqRequest implements MantiqRequestContract {
     this.authenticatedUser = user
   }
 
+  // ── FormData ────────────────────────────────────────────────────────────
+
+  async formData(): Promise<FormData> {
+    return this.bunRequest.clone().formData() as Promise<FormData>
+  }
+
   // ── Raw ──────────────────────────────────────────────────────────────────
 
   raw(): Request {
@@ -250,8 +291,12 @@ export class MantiqRequest implements MantiqRequestContract {
           }
         }
       }
-    } catch {
-      // Body parsing failed — leave parsedBody as empty object
+    } catch (error) {
+      // Body parsing failed — store the error for inspection
+      this._bodyError = error instanceof Error ? error : new Error(String(error))
+      if (typeof process !== 'undefined' && process.env?.APP_DEBUG === 'true') {
+        console.warn('[Mantiq] Body parse error:', this._bodyError.message)
+      }
     }
   }
 }

package/src/http/Response.ts

@@ -19,7 +19,36 @@ export class MantiqResponse {
     })
   }
 
+  /**
+   * Validate that a redirect URL is safe.
+   * Security: reject protocol-relative URLs (//evil.com), javascript:, data:,
+   * and other dangerous schemes that could redirect users to malicious sites.
+   * Only relative paths and http(s) URLs on the same origin are allowed.
+   */
+  private static validateRedirectUrl(url: string): void {
+    const trimmed = url.trim()
+
+    // Reject protocol-relative URLs (//evil.com)
+    if (trimmed.startsWith('//')) {
+      throw new Error('Unsafe redirect URL: protocol-relative URLs are not allowed')
+    }
+
+    // Reject dangerous schemes
+    const lower = trimmed.toLowerCase()
+    if (lower.startsWith('javascript:') || lower.startsWith('data:') || lower.startsWith('vbscript:')) {
+      throw new Error('Unsafe redirect URL: dangerous scheme detected')
+    }
+
+    // If it looks like an absolute URL, only allow http(s)
+    if (/^[a-z][a-z0-9+\-.]*:/i.test(trimmed)) {
+      if (!lower.startsWith('http://') && !lower.startsWith('https://')) {
+        throw new Error('Unsafe redirect URL: only http and https schemes are allowed')
+      }
+    }
+  }
+
   static redirect(url: string, status: number = 302): Response {
+    MantiqResponse.validateRedirectUrl(url)
     return new Response(null, {
       status,
       headers: { Location: url },
@@ -37,15 +66,37 @@ export class MantiqResponse {
     return new Response(stream)
   }
 
+  /**
+   * Security: sanitize Content-Disposition filename to prevent header injection.
+   * - Strip CR/LF to block header injection via newlines
+   * - Escape double quotes to prevent breaking out of the quoted filename
+   * - Strip path separators to prevent directory traversal
+   * - Use RFC 6266 filename* parameter for non-ASCII characters
+   */
+  private static sanitizeFilename(filename: string): string {
+    return filename
+      .replace(/[\r\n]/g, '')       // Strip newlines — prevents header injection
+      .replace(/[/\\]/g, '')        // Strip path separators — prevents traversal
+      .replace(/"/g, '\\"')         // Escape quotes — prevents breaking out of quoted string
+  }
+
   static download(
     content: Uint8Array | string,
     filename: string,
     mimeType?: string,
   ): Response {
+    const sanitized = MantiqResponse.sanitizeFilename(filename)
+
+    // RFC 6266: use filename* with UTF-8 encoding for non-ASCII filenames
+    const isAscii = /^[\x20-\x7E]+$/.test(sanitized)
+    const disposition = isAscii
+      ? `attachment; filename="${sanitized}"`
+      : `attachment; filename="${sanitized}"; filename*=UTF-8''${encodeURIComponent(sanitized)}`
+
     return new Response(content, {
       headers: {
         'Content-Type': mimeType ?? 'application/octet-stream',
-        'Content-Disposition': `attachment; filename="${filename}"`,
+        'Content-Disposition': disposition,
       },
     })
   }
@@ -100,6 +151,8 @@ export class ResponseBuilder implements MantiqResponseBuilder {
   }
 
   redirect(url: string): Response {
+    // Security: reuse the same URL validation as MantiqResponse.redirect()
+    MantiqResponse['validateRedirectUrl'](url)
     const headers = new Headers({ Location: url, ...this.responseHeaders })
     for (const c of this.cookieStrings) headers.append('Set-Cookie', c)
     return new Response(null, { status: this.statusExplicitlySet ? this.statusCode : 302, headers })

package/src/http/UploadedFile.ts

@@ -35,7 +35,7 @@ export class UploadedFile {
    * @param options.disk - Storage disk (currently only local filesystem)
    */
   async store(path: string, _options?: { disk?: string }): Promise<string> {
-    const filename = `${Date.now()}_${this.file.name}`
+    const filename = `${Date.now()}_${sanitizeFilename(this.file.name)}`
     const fullPath = `${path}/${filename}`
     const bytes = await this.file.arrayBuffer()
     await Bun.write(fullPath, bytes)
@@ -54,3 +54,26 @@ export class UploadedFile {
     return this.file.stream()
   }
 }
+
+/**
+ * Sanitize a filename to prevent path traversal attacks.
+ * Strips directory separators and ".." sequences, returning only the basename.
+ */
+function sanitizeFilename(name: string): string {
+  // Extract basename — strip any path separators (Unix and Windows)
+  let safe = name.split('/').pop()!
+  safe = safe.split('\\').pop()!
+
+  // Remove any remaining ".." sequences
+  safe = safe.replace(/\.\./g, '')
+
+  // Remove control characters and null bytes
+  safe = safe.replace(/[\x00-\x1f]/g, '')
+
+  // Fallback if the name is empty after sanitization
+  if (!safe || safe === '.' || safe === '..') {
+    safe = 'unnamed'
+  }
+
+  return safe
+}

package/src/index.ts

@@ -56,6 +56,8 @@ export { VerifyCsrfToken } from './middleware/VerifyCsrfToken.ts'
 export { RateLimiter, MemoryStore } from './rateLimit/RateLimiter.ts'
 export type { RateLimitConfig, RateLimitStore, LimiterResolver } from './rateLimit/RateLimiter.ts'
 export { ThrottleRequests, getDefaultRateLimiter, setDefaultRateLimiter } from './rateLimit/ThrottleRequests.ts'
+export { SecureHeaders } from './middleware/SecureHeaders.ts'
+export { Enum } from './support/Enum.ts'
 export { WebSocketKernel } from './websocket/WebSocketKernel.ts'
 export { DefaultExceptionHandler } from './exceptions/Handler.ts'
 export { CoreServiceProvider } from './providers/CoreServiceProvider.ts'

package/src/middleware/Cors.ts

@@ -76,7 +76,15 @@ export class CorsMiddleware implements Middleware {
   private setOriginHeader(headers: Headers, requestOrigin: string): void {
     const { origin } = this.config
     if (origin === '*') {
-      headers.set('Access-Control-Allow-Origin', '*')
+      if (this.config.credentials) {
+        // CORS spec forbids Access-Control-Allow-Origin: * with credentials.
+        // Reflect the request's Origin header instead; if absent, omit CORS headers entirely.
+        if (!requestOrigin) return
+        headers.set('Access-Control-Allow-Origin', requestOrigin)
+        headers.set('Vary', 'Origin')
+      } else {
+        headers.set('Access-Control-Allow-Origin', '*')
+      }
     } else if (Array.isArray(origin)) {
       if (origin.includes(requestOrigin)) {
         headers.set('Access-Control-Allow-Origin', requestOrigin)

package/src/middleware/EncryptCookies.ts

@@ -47,7 +47,10 @@ export class EncryptCookies implements Middleware {
         const decoded = decodeURIComponent(value)
         decrypted[name] = await this.encrypter.decrypt(decoded)
       } catch {
-        // Can't decrypt — skip this cookie (expired key, tampered, etc.)
+        // Can't decrypt — expired key, tampered, or wrong format
+        if (process.env.APP_DEBUG === 'true') {
+          console.warn(`[Mantiq] Failed to decrypt cookie "${name}" — using raw value`)
+        }
         decrypted[name] = value
       }
     }

package/src/middleware/SecureHeaders.ts

@@ -0,0 +1,72 @@
+import type { Middleware, NextFunction } from '../contracts/Middleware.ts'
+import type { MantiqRequest } from '../contracts/Request.ts'
+
+/**
+ * Security headers middleware.
+ *
+ * Adds common security headers to every response to protect against
+ * clickjacking, MIME sniffing, XSS, and downgrade attacks.
+ *
+ * Register as 'secure-headers' alias and add to middleware groups:
+ *   middlewareGroups: {
+ *     web: ['cors', 'secure-headers', 'encrypt.cookies', 'session', 'csrf'],
+ *   }
+ */
+export class SecureHeaders implements Middleware {
+  async handle(request: MantiqRequest, next: NextFunction): Promise<Response> {
+    const response = await next()
+    const headers = new Headers(response.headers)
+
+    // Prevent clickjacking — page cannot be embedded in iframes
+    if (!headers.has('X-Frame-Options')) {
+      headers.set('X-Frame-Options', 'SAMEORIGIN')
+    }
+
+    // Prevent MIME type sniffing — browser must respect Content-Type
+    if (!headers.has('X-Content-Type-Options')) {
+      headers.set('X-Content-Type-Options', 'nosniff')
+    }
+
+    // Enable browser XSS filter (legacy, but harmless)
+    if (!headers.has('X-XSS-Protection')) {
+      headers.set('X-XSS-Protection', '1; mode=block')
+    }
+
+    // Enforce HTTPS in production
+    if (!headers.has('Strict-Transport-Security')) {
+      if (process.env.APP_ENV === 'production') {
+        headers.set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains')
+      }
+    }
+
+    // Control what the browser is allowed to load.
+    // Security: do NOT include 'unsafe-inline' or 'unsafe-eval' — they defeat
+    // the purpose of CSP. Use nonce-based script/style loading instead.
+    // The nonce is generated per-request; pass it to templates via request.cspNonce.
+    if (!headers.has('Content-Security-Policy')) {
+      const nonce = crypto.randomUUID().replace(/-/g, '')
+      // Attach nonce to request so templates/views can reference it
+      ;(request as any).cspNonce = nonce
+      headers.set(
+        'Content-Security-Policy',
+        `default-src 'self'; script-src 'self' 'nonce-${nonce}'; style-src 'self' 'nonce-${nonce}'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self' ws: wss:; object-src 'none'; base-uri 'self'; form-action 'self'`,
+      )
+    }
+
+    // Prevent leaking referer to external sites
+    if (!headers.has('Referrer-Policy')) {
+      headers.set('Referrer-Policy', 'strict-origin-when-cross-origin')
+    }
+
+    // Disable browser features you don't use
+    if (!headers.has('Permissions-Policy')) {
+      headers.set('Permissions-Policy', 'camera=(), microphone=(), geolocation=()')
+    }
+
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    })
+  }
+}

package/src/providers/CoreServiceProvider.ts

@@ -10,6 +10,7 @@ import { StartSession } from '../middleware/StartSession.ts'
 import { EncryptCookies } from '../middleware/EncryptCookies.ts'
 import { VerifyCsrfToken } from '../middleware/VerifyCsrfToken.ts'
 import { ThrottleRequests } from '../rateLimit/ThrottleRequests.ts'
+import { SecureHeaders } from '../middleware/SecureHeaders.ts'
 import { ROUTER } from '../helpers/route.ts'
 import { ENCRYPTER } from '../helpers/encrypt.ts'
 import { AesEncrypter } from '../encryption/Encrypter.ts'
@@ -80,6 +81,7 @@ export class CoreServiceProvider extends ServiceProvider {
 
     // Rate limiting — zero-config, uses shared in-memory store
     this.app.singleton(ThrottleRequests, () => new ThrottleRequests())
+    this.app.singleton(SecureHeaders, () => new SecureHeaders())
 
     // HTTP kernel — singleton, depends on Router + ExceptionHandler + WsKernel
     this.app.singleton(HttpKernel, (c) => {
@@ -96,6 +98,10 @@ export class CoreServiceProvider extends ServiceProvider {
     if (appKey) {
       const encrypter = await AesEncrypter.fromAppKey(appKey)
       this.app.instance(ENCRYPTER, encrypter)
+
+      // Give WebSocketKernel the encrypter so it can decrypt cookies on upgrade
+      const wsKernel = this.app.make(WebSocketKernel)
+      wsKernel.setEncrypter(encrypter)
     }
 
     // ── Auto-register middleware aliases on HttpKernel ─────────────────────
@@ -106,6 +112,7 @@ export class CoreServiceProvider extends ServiceProvider {
     kernel.registerMiddleware('encrypt.cookies', EncryptCookies)
     kernel.registerMiddleware('session', StartSession)
     kernel.registerMiddleware('csrf', VerifyCsrfToken)
+    kernel.registerMiddleware('secure-headers', SecureHeaders)
 
     // Register middleware groups from config
     const configRepo = this.app.make(ConfigRepository)

package/src/session/Store.ts

@@ -40,7 +40,8 @@ export class SessionStore {
    */
   async save(): Promise<void> {
     await this.handler.write(this.id, JSON.stringify(this.attributes))
-    this.started = false
+    // Keep started=true so the session remains writable after save.
+    // Middleware may still need to write to the session after saving.
   }
 
   // ── Getters & setters ───────────────────────────────────────────────────

package/src/support/Enum.ts

@@ -0,0 +1,96 @@
+/**
+ * Base Enum class — Laravel-style backed enums for TypeScript.
+ *
+ * @example
+ *   class UserStatus extends Enum {
+ *     static Active = new UserStatus('active')
+ *     static Inactive = new UserStatus('inactive')
+ *     static Banned = new UserStatus('banned')
+ *   }
+ *
+ *   UserStatus.from('active')     // → UserStatus.Active
+ *   UserStatus.values()           // → ['active', 'inactive', 'banned']
+ *   UserStatus.cases()            // → [Active, Inactive, Banned]
+ *   UserStatus.Active.value       // → 'active'
+ *   UserStatus.Active.label       // → 'Active'
+ *   UserStatus.Active.is(status)  // → boolean
+ */
+export class Enum {
+  readonly value: string | number
+
+  constructor(value: string | number) {
+    this.value = value
+  }
+
+  /** Human-readable label — derived from the static property name. */
+  get label(): string {
+    const ctor = this.constructor as typeof Enum
+    for (const [key, val] of Object.entries(ctor)) {
+      if (val === this) {
+        // Convert PascalCase/camelCase to spaced: 'InProgress' → 'In Progress'
+        return key.replace(/([a-z])([A-Z])/g, '$1 $2')
+      }
+    }
+    return String(this.value)
+  }
+
+  /** Check if this enum equals another value (enum instance, string, or number). */
+  is(other: Enum | string | number): boolean {
+    if (other instanceof Enum) return this.value === other.value
+    return this.value === other
+  }
+
+  /** Check if this enum does NOT equal another value. */
+  isNot(other: Enum | string | number): boolean {
+    return !this.is(other)
+  }
+
+  /** String representation — returns the raw value. */
+  toString(): string {
+    return String(this.value)
+  }
+
+  /** JSON serialization — returns the raw value. */
+  toJSON(): string | number {
+    return this.value
+  }
+
+  // ── Static methods (called on the subclass) ────────────────────────────
+
+  /** Get all enum instances. */
+  static cases(): Enum[] {
+    return Object.values(this).filter((v) => v instanceof Enum)
+  }
+
+  /** Get all raw values. */
+  static values(): (string | number)[] {
+    return this.cases().map((c) => c.value)
+  }
+
+  /** Get all labels. */
+  static labels(): string[] {
+    return this.cases().map((c) => c.label)
+  }
+
+  /** Get an enum instance from a raw value. Throws if not found. */
+  static from(value: string | number): Enum {
+    const found = this.tryFrom(value)
+    if (!found) throw new Error(`"${value}" is not a valid ${this.name} value. Valid: ${this.values().join(', ')}`)
+    return found
+  }
+
+  /** Get an enum instance from a raw value. Returns null if not found. */
+  static tryFrom(value: string | number): Enum | null {
+    return this.cases().find((c) => c.value === value) ?? null
+  }
+
+  /** Check if a value is valid for this enum. */
+  static has(value: string | number): boolean {
+    return this.values().includes(value)
+  }
+
+  /** Get a map of value → label for select dropdowns, etc. */
+  static options(): Array<{ value: string | number; label: string }> {
+    return this.cases().map((c) => ({ value: c.value, label: c.label }))
+  }
+}

package/src/websocket/WebSocketKernel.ts

@@ -1,5 +1,7 @@
 import type { WebSocketHandler } from './WebSocketContext.ts'
+import type { AesEncrypter } from '../encryption/Encrypter.ts'
 import { MantiqRequest } from '../http/Request.ts'
+import { parseCookies } from '../http/Cookie.ts'
 
 /**
  * Handles WebSocket upgrade detection and lifecycle delegation.
@@ -9,6 +11,7 @@ import { MantiqRequest } from '../http/Request.ts'
  */
 export class WebSocketKernel {
   private handler: WebSocketHandler | null = null
+  private encrypter: AesEncrypter | null = null
 
   /**
    * Called by @mantiq/realtime to register its WebSocket handler.
@@ -17,6 +20,14 @@ export class WebSocketKernel {
     this.handler = handler
   }
 
+  /**
+   * Inject the encrypter so WebSocket upgrades can decrypt cookies.
+   * Called during CoreServiceProvider boot.
+   */
+  setEncrypter(encrypter: AesEncrypter): void {
+    this.encrypter = encrypter
+  }
+
   /**
    * Called by HttpKernel when an upgrade request is detected.
    */
@@ -29,6 +40,13 @@ export class WebSocketKernel {
     }
 
     const mantiqRequest = MantiqRequest.fromBun(request)
+
+    // Decrypt cookies — WebSocket upgrades bypass the middleware pipeline,
+    // so EncryptCookies never runs. Manually decrypt here.
+    if (this.encrypter) {
+      await this.decryptCookies(mantiqRequest)
+    }
+
     const context = await this.handler.onUpgrade(mantiqRequest)
 
     if (!context) {
@@ -57,4 +75,29 @@ export class WebSocketKernel {
       drain: (ws: any) => h?.drain(ws),
     }
   }
+
+  // ── Private ───────────────────────────────────────────────────────────────
+
+  private async decryptCookies(request: MantiqRequest): Promise<void> {
+    const cookieHeader = request.header('cookie')
+    if (!cookieHeader) return
+
+    const cookies = parseCookies(cookieHeader)
+    const decrypted: Record<string, string> = {}
+    const except = ['XSRF-TOKEN']
+
+    for (const [name, value] of Object.entries(cookies)) {
+      if (except.includes(name)) {
+        decrypted[name] = value
+        continue
+      }
+      try {
+        decrypted[name] = await this.encrypter!.decrypt(value)
+      } catch {
+        decrypted[name] = value
+      }
+    }
+
+    request.setCookies(decrypted)
+  }
 }