@mantiq/core 0.5.23 → 0.6.0

package/package.json

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

package/src/application/Application.ts

@@ -298,14 +298,22 @@ export class Application extends ContainerImpl {
   /**
    * Boot all registered (non-deferred) providers.
    * Called after ALL providers have been registered.
+   *
+   * Errors are re-thrown with descriptive messages so they surface
+   * immediately rather than being silently swallowed.
    */
   async bootProviders(): Promise<void> {
     for (const provider of this.providers) {
+      const name = provider.constructor?.name ?? 'Unknown'
       try {
         await provider.boot()
       } catch (e) {
-        const name = provider.constructor?.name ?? 'Unknown'
-        console.error(`[Mantiq] ${name}.boot() failed:`, (e as Error)?.stack ?? e)
+        // Re-throw with context so the developer knows which provider failed.
+        // Previously errors were only logged, masking critical boot failures.
+        throw new Error(
+          `[Mantiq] ${name}.boot() failed: ${(e as Error)?.message ?? e}`,
+          { cause: e },
+        )
       }
     }
     this.booted = true
@@ -330,6 +338,10 @@ export class Application extends ContainerImpl {
   /**
    * Override make() to handle deferred provider loading.
    * If a binding isn't found in the container, check deferred providers.
+   *
+   * Deferred providers are registered and booted synchronously where possible.
+   * If register() or boot() return a Promise, this method will throw — callers
+   * must use makeAsync() for providers that require async initialization.
    */
   override make<T>(abstract: Bindable<T>): T {
     try {
@@ -345,17 +357,74 @@ export class Application extends ContainerImpl {
           for (const [key, p] of this.deferredProviders.entries()) {
             if (p === deferredProvider) this.deferredProviders.delete(key)
           }
-          // Register + boot the deferred provider now
-          const boot = async () => {
+
+          const providerName = deferredProvider.constructor?.name ?? 'DeferredProvider'
+
+          // Register the deferred provider synchronously. If register()
+          // returns a Promise, it means the provider requires async init —
+          // we cannot silently fire-and-forget because make() would return
+          // before the binding is registered.
+          const registerResult = deferredProvider.register()
+          if (registerResult && typeof (registerResult as any).then === 'function') {
+            throw new Error(
+              `[Mantiq] ${providerName}.register() is async but was triggered via synchronous make(). ` +
+              `Use await app.makeAsync(${String((abstract as any)?.name ?? abstract)}) instead.`,
+            )
+          }
+
+          // Boot the deferred provider synchronously.
+          const bootResult = deferredProvider.boot()
+          if (bootResult && typeof (bootResult as any).then === 'function') {
+            throw new Error(
+              `[Mantiq] ${providerName}.boot() is async but was triggered via synchronous make(). ` +
+              `Use await app.makeAsync(${String((abstract as any)?.name ?? abstract)}) instead.`,
+            )
+          }
+
+          this.providers.push(deferredProvider)
+          return super.make(abstract)
+        }
+      }
+      throw err
+    }
+  }
+
+  /**
+   * Async version of make() that properly awaits deferred provider boot.
+   *
+   * Use this when the deferred provider's register() or boot() may be async.
+   * For synchronous providers, make() is sufficient and faster.
+   */
+  async makeAsync<T>(abstract: Bindable<T>): Promise<T> {
+    try {
+      return super.make(abstract)
+    } catch (err) {
+      if (
+        err instanceof ContainerResolutionError &&
+        err.reason === 'not_bound'
+      ) {
+        const deferredProvider = this.deferredProviders.get(abstract)
+        if (deferredProvider) {
+          // Remove from deferred map so we don't loop
+          for (const [key, p] of this.deferredProviders.entries()) {
+            if (p === deferredProvider) this.deferredProviders.delete(key)
+          }
+
+          const providerName = deferredProvider.constructor?.name ?? 'DeferredProvider'
+
+          // Await register + boot so the binding is fully available
+          // before we resolve it. Errors propagate to the caller.
+          try {
             await deferredProvider.register()
             await deferredProvider.boot()
-            this.providers.push(deferredProvider)
+          } catch (e) {
+            throw new Error(
+              `[Mantiq] ${providerName} deferred boot failed: ${(e as Error)?.message ?? e}`,
+              { cause: e },
+            )
           }
-          // 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)
-          })
+
+          this.providers.push(deferredProvider)
           return super.make(abstract)
         }
       }

package/src/cache/FileCacheStore.ts

@@ -81,10 +81,42 @@ export class FileCacheStore implements CacheStore {
     }
   }
 
+  /**
+   * Fix #194: Atomic increment using write-to-temp + rename to prevent
+   * TOCTOU race conditions where concurrent increments could lose updates.
+   */
   async increment(key: string, value = 1): Promise<number> {
-    const current = await this.get<number>(key)
-    const newValue = (current ?? 0) + value
-    await this.put(key, newValue)
+    await this.ensureDirectory()
+    const targetPath = this.path(key)
+    const file = Bun.file(targetPath)
+
+    let current = 0
+    if (await file.exists()) {
+      try {
+        const payload: FileCachePayload = await file.json()
+        if (payload.expiresAt !== null && Date.now() > payload.expiresAt) {
+          // Expired — treat as 0
+        } else {
+          current = (payload.value as number) ?? 0
+        }
+      } catch {
+        // Corrupted file — start from 0
+      }
+    }
+
+    const newValue = current + value
+
+    // Atomic write: temp file + rename to avoid partial reads by concurrent operations
+    const tmpPath = join(this.directory, `_tmp_${randomBytes(8).toString('hex')}.cache`)
+    const payload: FileCachePayload = { value: newValue, expiresAt: null }
+    await Bun.write(tmpPath, JSON.stringify(payload))
+
+    try {
+      await rename(tmpPath, targetPath)
+    } catch {
+      try { await rm(tmpPath) } catch { /* ignore */ }
+    }
+
     return newValue
   }
 

package/src/cache/MemoryCacheStore.ts

@@ -43,6 +43,14 @@ export class MemoryCacheStore implements CacheStore {
     this.store.clear()
   }
 
+  /**
+   * Increment a cached numeric value.
+   *
+   * Note (#194): This get-then-put is safe in single-threaded Bun because
+   * there is no I/O between the read and write — the event loop cannot
+   * yield to another task mid-execution. If Bun gains multi-threaded
+   * workers sharing memory, this would need a lock or atomic operation.
+   */
   async increment(key: string, value = 1): Promise<number> {
     const current = await this.get<number>(key)
     const newValue = (current ?? 0) + value

package/src/exceptions/Handler.ts

@@ -8,6 +8,11 @@ import { UnauthorizedError } from '../errors/UnauthorizedError.ts'
 import { MantiqResponse } from '../http/Response.ts'
 import { renderDevErrorPage } from './DevErrorPage.ts'
 
+/** Security: escape HTML special characters to prevent XSS in error pages. */
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;')
+}
+
 export class DefaultExceptionHandler implements ExceptionHandler {
   dontReport: Constructor<Error>[] = [
     NotFoundError,
@@ -102,12 +107,15 @@ export class DefaultExceptionHandler implements ExceptionHandler {
   }
 
   private genericHtmlPage(status: number, message: string): string {
+    // Security: escape message to prevent XSS — error messages may contain
+    // user-controlled input (e.g., URL paths, query parameters).
+    const safeMessage = escapeHtml(message)
     return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${status} ${message}</title>
+  <title>${status} ${safeMessage}</title>
   <style>
     body { font-family: system-ui, sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f7fafc; color: #2d3748; }
     .box { text-align: center; }
@@ -118,7 +126,7 @@ export class DefaultExceptionHandler implements ExceptionHandler {
 <body>
   <div class="box">
     <h1>${status}</h1>
-    <p>${message}</p>
+    <p>${safeMessage}</p>
   </div>
 </body>
 </html>`

package/src/middleware/Cors.ts

@@ -24,12 +24,26 @@ export class CorsMiddleware implements Middleware {
     const defaultOrigin = appUrl || '*'
     const defaultCredentials = !!appUrl
 
+    let origin = configRepo?.get('cors.origin', defaultOrigin) ?? defaultOrigin
+    let credentials = configRepo?.get('cors.credentials', defaultCredentials) ?? defaultCredentials
+
+    // Security: origin='*' with credentials=true is dangerous — it effectively
+    // disables same-origin policy by reflecting any request origin. Force
+    // credentials to false when origin is a wildcard.
+    if (origin === '*' && credentials) {
+      console.warn(
+        '[Mantiq] CORS: origin="*" with credentials=true is insecure. ' +
+        'Forcing credentials=false. Set an explicit origin to use credentials.',
+      )
+      credentials = false
+    }
+
     this.config = {
-      origin: configRepo?.get('cors.origin', defaultOrigin) ?? defaultOrigin,
+      origin,
       methods: configRepo?.get('cors.methods', ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']) ?? ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
       allowedHeaders: configRepo?.get('cors.allowedHeaders', ['Content-Type', 'Authorization', 'X-Requested-With', 'X-CSRF-TOKEN', 'X-XSRF-TOKEN', 'X-Mantiq']) ?? ['Content-Type', 'Authorization', 'X-Requested-With', 'X-CSRF-TOKEN', 'X-XSRF-TOKEN', 'X-Mantiq'],
       exposedHeaders: configRepo?.get('cors.exposedHeaders', ['X-Heartbeat']) ?? ['X-Heartbeat'],
-      credentials: configRepo?.get('cors.credentials', defaultCredentials) ?? defaultCredentials,
+      credentials,
       maxAge: configRepo?.get('cors.maxAge', 7200) ?? 7200,
     }
   }
@@ -76,15 +90,11 @@ export class CorsMiddleware implements Middleware {
   private setOriginHeader(headers: Headers, requestOrigin: string): void {
     const { origin } = this.config
     if (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', '*')
-      }
+      // When origin='*', always use the literal wildcard. The constructor
+      // ensures credentials is false when origin='*', so this is spec-safe.
+      // We never reflect an arbitrary request origin — that would defeat
+      // same-origin policy when combined with credentials.
+      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

@@ -97,8 +97,9 @@ export class EncryptCookies implements Middleware {
 
         headers.append('Set-Cookie', newSetCookie)
       } catch {
-        // If encryption fails, send unencrypted (shouldn't happen with valid key)
-        headers.append('Set-Cookie', setCookie)
+        // Security: drop the cookie entirely rather than sending it unencrypted.
+        // Sending plaintext cookies would expose sensitive data on the wire.
+        console.warn(`[Mantiq] Failed to encrypt cookie "${name}" — dropping cookie to prevent plaintext exposure.`)
       }
     }
 

package/src/middleware/StartSession.ts

@@ -55,6 +55,16 @@ export class StartSession implements Middleware {
     // Save session
     await session.save()
 
+    // Probabilistic garbage collection: ~2% chance per request to clean up expired sessions.
+    // This avoids the need for a dedicated cron job while keeping overhead minimal.
+    if (Math.random() < 0.02) {
+      const lifetime = config.lifetime * 60 // convert minutes to seconds
+      handler.gc(lifetime).catch(() => {
+        // GC failures are non-critical — log and continue
+        console.warn('[Mantiq] Session garbage collection failed.')
+      })
+    }
+
     // Attach cookie to response
     return this.addCookieToResponse(response, session, config)
   }

package/src/middleware/VerifyCsrfToken.ts

@@ -1,5 +1,6 @@
 import type { Middleware, NextFunction } from '../contracts/Middleware.ts'
 import type { MantiqRequest } from '../contracts/Request.ts'
+import { timingSafeEqual as cryptoTimingSafeEqual } from 'node:crypto'
 import { TokenMismatchError } from '../errors/TokenMismatchError.ts'
 import { AesEncrypter } from '../encryption/Encrypter.ts'
 import { serializeCookie } from '../http/Cookie.ts'
@@ -113,17 +114,21 @@ export class VerifyCsrfToken implements Middleware {
 
 /**
  * Constant-time string comparison to prevent timing attacks on token verification.
+ * Uses node:crypto's timingSafeEqual which handles length-mismatch internally
+ * without leaking token length via timing side-channels.
  */
 function timingSafeEqual(a: string, b: string): boolean {
-  if (a.length !== b.length) return false
-
   const encoder = new TextEncoder()
   const bufA = encoder.encode(a)
   const bufB = encoder.encode(b)
 
-  let result = 0
-  for (let i = 0; i < bufA.length; i++) {
-    result |= bufA[i]! ^ bufB[i]!
-  }
-  return result === 0
+  // Pad to equal length so we never leak the expected token length via an early return.
+  const maxLen = Math.max(bufA.length, bufB.length)
+  const paddedA = new Uint8Array(maxLen)
+  const paddedB = new Uint8Array(maxLen)
+  paddedA.set(bufA)
+  paddedB.set(bufB)
+
+  // If lengths differ the tokens cannot match, but we still compare in constant time.
+  return bufA.length === bufB.length && cryptoTimingSafeEqual(paddedA, paddedB)
 }

package/src/session/SessionManager.ts

@@ -9,7 +9,8 @@ const SESSION_DEFAULTS: SessionConfig = {
   lifetime: 120,
   cookie: 'mantiq_session',
   path: '/',
-  secure: false,
+  // Security: default to secure cookies (HTTPS-only). Override in dev config for HTTP.
+  secure: true,
   httpOnly: true,
   sameSite: 'Lax',
 }

package/src/session/Store.ts

@@ -162,6 +162,9 @@ export class SessionStore {
       await this.handler.destroy(this.id)
     }
     this.id = SessionStore.generateId()
+    // Security: regenerate the CSRF token alongside the session ID to prevent
+    // token fixation attacks (e.g. after login).
+    this.regenerateToken()
   }
 
   /**
@@ -182,7 +185,9 @@ export class SessionStore {
   // ── Static helpers ──────────────────────────────────────────────────────
 
   static generateId(): string {
-    const bytes = new Uint8Array(20)
+    // Security: use 256 bits (32 bytes) of entropy per OWASP session ID guidelines.
+    // Produces a 64-char hex string.
+    const bytes = new Uint8Array(32)
     crypto.getRandomValues(bytes)
     let id = ''
     for (let i = 0; i < bytes.length; i++) {

package/src/websocket/WebSocketKernel.ts

@@ -8,11 +8,30 @@ import { parseCookies } from '../http/Cookie.ts'
  *
  * Core only provides the infrastructure — @mantiq/realtime registers
  * its handler via registerHandler(). Without it, all upgrades return 426.
+ *
+ * IMPORTANT: WebSocket upgrade requests bypass the HTTP middleware pipeline
+ * entirely. This means middleware like VerifyCsrfToken, StartSession, and
+ * CorsMiddleware do NOT run on WebSocket connections. Authentication must
+ * be handled in the onUpgrade hook (via the registered WebSocketHandler's
+ * `onUpgrade` method). Cookie decryption is handled manually below.
+ *
+ * If you need additional request validation on upgrade, register an
+ * `onUpgrade` callback in your WebSocketHandler implementation that
+ * performs the necessary checks (e.g., origin verification, rate limiting).
  */
 export class WebSocketKernel {
   private handler: WebSocketHandler | null = null
   private encrypter: AesEncrypter | null = null
 
+  /**
+   * Optional hooks that run during the upgrade request before the handler's
+   * onUpgrade. Use this to add origin checks, rate limiting, or other
+   * validation that would normally be done by HTTP middleware.
+   *
+   * Return a Response to reject the upgrade, or void/undefined to continue.
+   */
+  private upgradeHooks: Array<(request: MantiqRequest) => Promise<Response | void>> = []
+
   /**
    * Called by @mantiq/realtime to register its WebSocket handler.
    */
@@ -20,6 +39,18 @@ export class WebSocketKernel {
     this.handler = handler
   }
 
+  /**
+   * Register a hook that runs on every WebSocket upgrade request.
+   * Since WebSocket upgrades bypass the HTTP middleware pipeline,
+   * use this to add checks that middleware would normally handle
+   * (e.g., origin validation, rate limiting, auth).
+   *
+   * Return a Response to reject the upgrade, or void to continue.
+   */
+  onUpgrade(hook: (request: MantiqRequest) => Promise<Response | void>): void {
+    this.upgradeHooks.push(hook)
+  }
+
   /**
    * Inject the encrypter so WebSocket upgrades can decrypt cookies.
    * Called during CoreServiceProvider boot.
@@ -30,6 +61,9 @@ export class WebSocketKernel {
 
   /**
    * Called by HttpKernel when an upgrade request is detected.
+   *
+   * NOTE: The HTTP middleware pipeline does NOT run for WebSocket upgrades.
+   * Authentication is delegated to the handler's onUpgrade method.
    */
   async handleUpgrade(request: Request, server: any): Promise<Response> {
     if (!this.handler) {
@@ -47,6 +81,15 @@ export class WebSocketKernel {
       await this.decryptCookies(mantiqRequest)
     }
 
+    // Run onUpgrade hooks — these substitute for HTTP middleware that
+    // would normally run (auth, origin checks, rate limiting, etc.).
+    for (const hook of this.upgradeHooks) {
+      const rejection = await hook(mantiqRequest)
+      if (rejection instanceof Response) {
+        return rejection
+      }
+    }
+
     const context = await this.handler.onUpgrade(mantiqRequest)
 
     if (!context) {
@@ -65,15 +108,26 @@ export class WebSocketKernel {
   /**
    * Returns the Bun WebSocket handlers object for Bun.serve().
    * If no handler is registered, provides no-op stubs.
+   *
+   * Includes maxPayloadLength from the handler if available, which tells
+   * Bun to enforce a transport-level message size limit.
    */
   getBunHandlers(): object {
     const h = this.handler
-    return {
+    const handlers: Record<string, any> = {
       open: (ws: any) => h?.open(ws),
       message: (ws: any, msg: any) => h?.message(ws, msg),
       close: (ws: any, code: number, reason: string) => h?.close(ws, code, reason),
       drain: (ws: any) => h?.drain(ws),
     }
+
+    // Pass maxPayloadLength to Bun's WebSocket config if the handler provides it.
+    // This enforces a transport-level limit on incoming message sizes.
+    if (h && typeof (h as any).getMaxPayloadLength === 'function') {
+      handlers.maxPayloadLength = (h as any).getMaxPayloadLength()
+    }
+
+    return handlers
   }
 
   // ── Private ───────────────────────────────────────────────────────────────