@mantiq/core 0.5.22 → 0.6.0

package/src/http/Kernel.ts

@@ -56,6 +56,20 @@ export class HttpKernel {
     this.globalMiddleware = middleware
   }
 
+  /**
+   * Check whether a middleware alias has been registered.
+   */
+  hasMiddleware(alias: string): boolean {
+    return alias in this.middlewareAliases
+  }
+
+  /**
+   * Return all registered middleware alias names.
+   */
+  getRegisteredAliases(): string[] {
+    return Object.keys(this.middlewareAliases)
+  }
+
   /**
    * Middleware registered by packages that run before the app's global middleware.
    * Separate from globalMiddleware so setGlobalMiddleware() doesn't overwrite them.
@@ -202,11 +216,53 @@ export class HttpKernel {
 
   // ── Private ───────────────────────────────────────────────────────────────
 
+  /**
+   * Resolve route model bindings.
+   * Replaces raw parameter values (e.g. '42') with model instances.
+   * Returns a 404 response if any bound model is not found.
+   */
+  private async resolveBindings(
+    match: RouteMatch,
+    request: MantiqRequestContract,
+  ): Promise<Response | null> {
+    if (!match.bindings || match.bindings.size === 0) return null
+
+    for (const [param, { model, key }] of match.bindings) {
+      const value = request.param(param)
+      if (value === undefined) continue
+
+      let instance: any
+
+      if (key === '__custom__') {
+        // Custom resolver function (from router.bind())
+        instance = await model(String(value))
+      } else {
+        // Model class with .where().first()
+        instance = await model.where(key, value).first()
+      }
+
+      if (!instance) {
+        return new Response(
+          JSON.stringify({ error: `${param} not found.` }),
+          { status: 404, headers: { 'Content-Type': 'application/json' } },
+        )
+      }
+
+      request.setRouteParam(param, instance)
+    }
+
+    return null
+  }
+
   /**
    * Call the route action (controller method or closure).
    * Converts the return value to a Response.
    */
   private async callAction(match: RouteMatch, request: MantiqRequestContract): Promise<Response> {
+    // Resolve model bindings before calling the action
+    const bindingError = await this.resolveBindings(match, request)
+    if (bindingError) return bindingError
+
     const action = match.action
 
     let result: any

package/src/http/Request.ts

@@ -58,15 +58,15 @@ export class MantiqRequest implements MantiqRequestContract {
     return this.parsedQuery[key] ?? defaultValue ?? (undefined as any)
   }
 
-  async input(): Promise<Record<string, any>>
-  async input(key: string, defaultValue?: any): Promise<any>
-  async input(key?: string, defaultValue?: any): Promise<any> {
+  async input<T = Record<string, any>>(): Promise<T>
+  async input<T = any>(key: string, defaultValue?: any): Promise<T>
+  async input<T = any>(key?: string, defaultValue?: any): Promise<T> {
     if (!this.parsedBody) {
       await this.parseBody()
     }
     const merged = { ...this.query(), ...this.parsedBody }
-    if (key === undefined) return merged
-    return merged[key] ?? defaultValue
+    if (key === undefined) return merged as T
+    return (merged[key] ?? defaultValue) as T
   }
 
   async only(...keys: string[]): Promise<Record<string, any>> {
@@ -211,6 +211,10 @@ export class MantiqRequest implements MantiqRequestContract {
     this.routeParams = params
   }
 
+  setRouteParam(key: string, value: any): void {
+    this.routeParams[key] = value
+  }
+
   // ── Session ──────────────────────────────────────────────────────────────
 
   session(): SessionStore {

package/src/index.ts

@@ -24,6 +24,8 @@ export { Event, Listener } from './contracts/EventDispatcher.ts'
 export type { WebSocketHandler, WebSocketContext } from './websocket/WebSocketContext.ts'
 
 // ── Errors ────────────────────────────────────────────────────────────────────
+export { ErrorCodes } from './errors/ErrorCodes.ts'
+export type { ErrorCode } from './errors/ErrorCodes.ts'
 export { MantiqError } from './errors/MantiqError.ts'
 export { HttpError } from './errors/HttpError.ts'
 export { NotFoundError } from './errors/NotFoundError.ts'
@@ -46,6 +48,7 @@ export { UploadedFile } from './http/UploadedFile.ts'
 export { HttpKernel } from './http/Kernel.ts'
 export { RouterImpl } from './routing/Router.ts'
 export { Route } from './routing/Route.ts'
+export type { RouteBinding } from './routing/Route.ts'
 export { RouteMatched } from './routing/events.ts'
 export { Pipeline } from './middleware/Pipeline.ts'
 export { CorsMiddleware } from './middleware/Cors.ts'
@@ -57,6 +60,8 @@ 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 { TimeoutMiddleware } from './middleware/TimeoutMiddleware.ts'
+export { RouteModelBinding } from './middleware/RouteModelBinding.ts'
 export { Enum } from './support/Enum.ts'
 export { WebSocketKernel } from './websocket/WebSocketKernel.ts'
 export { DefaultExceptionHandler } from './exceptions/Handler.ts'
@@ -64,6 +69,9 @@ export { CoreServiceProvider } from './providers/CoreServiceProvider.ts'
 export { Discoverer } from './discovery/Discoverer.ts'
 export type { DiscoveryManifest } from './discovery/Discoverer.ts'
 
+// ── URL Signing ──────────────────────────────────────────────────────────────
+export { UrlSigner } from './url/UrlSigner.ts'
+
 // ── Encryption ────────────────────────────────────────────────────────────────
 export { AesEncrypter } from './encryption/Encrypter.ts'
 
@@ -103,4 +111,5 @@ export { hash, hashCheck } from './helpers/hash.ts'
 export { cache } from './helpers/cache.ts'
 export { session } from './helpers/session.ts'
 export { dd, dump } from './helpers/dd.ts'
+export { signedUrl, hasValidSignature } from './helpers/signedUrl.ts'
 export { base_path, app_path, config_path, database_path, storage_path, public_path, resource_path } from './helpers/paths.ts'

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

@@ -47,11 +47,13 @@ export class EncryptCookies implements Middleware {
         const decoded = decodeURIComponent(value)
         decrypted[name] = await this.encrypter.decrypt(decoded)
       } catch {
-        // Can't decrypt — expired key, tampered, or wrong format
+        // Can't decrypt — expired key, tampered, or wrong format.
+        // Discard the value instead of passing through the encrypted blob,
+        // which could cause unexpected behavior downstream.
         if (process.env.APP_DEBUG === 'true') {
-          console.warn(`[Mantiq] Failed to decrypt cookie "${name}" — using raw value`)
+          console.warn(`[Mantiq] Failed to decrypt cookie "${name}" — discarding value`)
         }
-        decrypted[name] = value
+        decrypted[name] = ''
       }
     }
 
@@ -86,10 +88,18 @@ export class EncryptCookies implements Middleware {
       try {
         const encrypted = await this.encrypter.encrypt(value)
         const newSetCookie = `${encodeURIComponent(name)}=${encodeURIComponent(encrypted)}; ${parts.join('; ')}`
+
+        if (newSetCookie.length > 4096) {
+          console.warn(
+            `[Mantiq] Cookie "${name}" exceeds 4KB (${newSetCookie.length} bytes) — browsers may silently ignore it.`,
+          )
+        }
+
         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/RouteModelBinding.ts

@@ -0,0 +1,43 @@
+import type { Middleware, NextFunction } from '../contracts/Middleware.ts'
+import type { MantiqRequest } from '../contracts/Request.ts'
+
+/**
+ * Middleware that resolves route parameters to model instances.
+ *
+ * Register bindings before adding to the middleware stack:
+ *
+ * @example
+ *   const binding = new RouteModelBinding()
+ *   binding.bind('user', User)           // looks up User.where('id', value).first()
+ *   binding.bind('post', Post, 'slug')   // looks up Post.where('slug', value).first()
+ *
+ *   kernel.registerMiddleware('bindings', RouteModelBinding)
+ */
+export class RouteModelBinding implements Middleware {
+  private bindings = new Map<string, { model: any; key: string }>()
+
+  bind(param: string, model: any, key = 'id'): void {
+    this.bindings.set(param, { model, key })
+  }
+
+  async handle(request: MantiqRequest, next: NextFunction): Promise<Response> {
+    const params = request.params()
+
+    for (const [param, { model, key }] of this.bindings) {
+      const value = params[param]
+      if (value === undefined) continue
+
+      const instance = await model.where(key, value).first()
+      if (!instance) {
+        return new Response(
+          JSON.stringify({ error: `${param} not found.` }),
+          { status: 404, headers: { 'Content-Type': 'application/json' } },
+        )
+      }
+
+      request.setRouteParam(param, instance)
+    }
+
+    return next()
+  }
+}

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/TimeoutMiddleware.ts

@@ -0,0 +1,47 @@
+import type { Middleware, NextFunction } from '../contracts/Middleware.ts'
+import type { MantiqRequest } from '../contracts/Request.ts'
+
+/**
+ * Request timeout middleware.
+ *
+ * Aborts requests that exceed a configurable time limit, returning a 408
+ * status. Default timeout is 30 seconds.
+ *
+ * Usage with route alias:
+ *   route.get('/heavy', handler).middleware('timeout')      // 30s default
+ *   route.get('/heavy', handler).middleware('timeout:60')   // 60s
+ */
+export class TimeoutMiddleware implements Middleware {
+  private timeout = 30_000 // default 30s
+
+  setParameters(params: string[]): void {
+    if (params[0]) this.timeout = Number(params[0]) * 1000
+  }
+
+  async handle(request: MantiqRequest, next: NextFunction): Promise<Response> {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), this.timeout)
+
+    try {
+      const response = await Promise.race([
+        next(),
+        new Promise<never>((_, reject) => {
+          controller.signal.addEventListener('abort', () =>
+            reject(new Error(`Request timed out after ${this.timeout}ms`)),
+          )
+        }),
+      ])
+      clearTimeout(timer)
+      return response
+    } catch (err: any) {
+      clearTimeout(timer)
+      if (err.message?.includes('timed out')) {
+        return new Response(JSON.stringify({ error: 'Request Timeout' }), {
+          status: 408,
+          headers: { 'Content-Type': 'application/json' },
+        })
+      }
+      throw err
+    }
+  }
+}

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/providers/CoreServiceProvider.ts

@@ -11,6 +11,7 @@ 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 { TimeoutMiddleware } from '../middleware/TimeoutMiddleware.ts'
 import { ROUTER } from '../helpers/route.ts'
 import { ENCRYPTER } from '../helpers/encrypt.ts'
 import { AesEncrypter } from '../encryption/Encrypter.ts'
@@ -82,6 +83,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())
+    this.app.bind(TimeoutMiddleware, () => new TimeoutMiddleware())
 
     // HTTP kernel — singleton, depends on Router + ExceptionHandler + WsKernel
     this.app.singleton(HttpKernel, (c) => {
@@ -113,6 +115,7 @@ export class CoreServiceProvider extends ServiceProvider {
     kernel.registerMiddleware('session', StartSession)
     kernel.registerMiddleware('csrf', VerifyCsrfToken)
     kernel.registerMiddleware('secure-headers', SecureHeaders)
+    kernel.registerMiddleware('timeout', TimeoutMiddleware)
 
     // Register middleware groups from config
     const configRepo = this.app.make(ConfigRepository)
@@ -125,6 +128,29 @@ export class CoreServiceProvider extends ServiceProvider {
       kernel.registerMiddlewareGroup(name, middleware)
     }
 
+    // ── Boot-time convention validation ────────────────────────────────────
+    // Validate that all aliases referenced by middleware groups are registered
+    for (const [group, aliases] of Object.entries(middlewareGroups)) {
+      for (const alias of aliases) {
+        const name = alias.split(':')[0]!
+        if (!kernel.hasMiddleware(name)) {
+          throw new Error(
+            `Middleware group '${group}' references unknown alias '${name}'.\n` +
+            `Registered aliases: ${kernel.getRegisteredAliases().join(', ')}`,
+          )
+        }
+      }
+    }
+
+    // Validate APP_KEY when encrypt.cookies middleware is active
+    const needsKey = Object.values(middlewareGroups).flat().includes('encrypt.cookies')
+    if (needsKey && !appKey) {
+      throw new Error(
+        'APP_KEY is required when encrypt.cookies middleware is active.\n' +
+        'Generate one with: bun mantiq key:generate',
+      )
+    }
+
     // Legacy: if app.middleware is set, apply as global middleware (backward compat)
     const globalMiddleware = configRepo.get('app.middleware', []) as string[]
     if (globalMiddleware.length > 0) {

package/src/routing/Route.ts

@@ -1,9 +1,15 @@
 import type { HttpMethod, RouteAction, RouterRoute } from '../contracts/Router.ts'
 
+export interface RouteBinding {
+  model: any
+  key: string
+}
+
 export class Route implements RouterRoute {
   public routeName?: string
   public middlewareList: string[] = []
   public wheres: Record<string, RegExp> = {}
+  public bindings = new Map<string, RouteBinding>()
 
   constructor(
     public readonly methods: HttpMethod[],
@@ -37,4 +43,9 @@ export class Route implements RouterRoute {
   whereUuid(param: string): this {
     return this.where(param, /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i)
   }
+
+  bind(param: string, model: any, key = 'id'): this {
+    this.bindings.set(param, { model, key })
+    return this
+  }
 }

package/src/routing/Router.ts

@@ -160,12 +160,43 @@ export class RouterImpl implements RouterContract {
       const result = RouteMatcher.match(route, pathname)
       if (result) {
         RouterImpl._dispatcher?.emit(new RouteMatched(route.routeName, route.action, request))
-        return {
+
+        // Merge route-level bindings with router-level bindings (route-level takes precedence)
+        const bindings = new Map<string, { model: any; key: string }>()
+
+        // Add router-level model bindings (model class → where('id', value).first())
+        for (const [param, ModelClass] of this.modelBindings) {
+          if (result.params[param] !== undefined) {
+            bindings.set(param, { model: ModelClass, key: 'id' })
+          }
+        }
+
+        // Add router-level custom bindings (resolver function)
+        for (const [param, resolver] of this.customBindings) {
+          if (result.params[param] !== undefined) {
+            bindings.set(param, { model: resolver, key: '__custom__' })
+          }
+        }
+
+        // Route-level bindings override router-level
+        for (const [param, binding] of route.bindings) {
+          if (result.params[param] !== undefined) {
+            bindings.set(param, binding)
+          }
+        }
+
+        const match: RouteMatch = {
           action: route.action,
           params: result.params,
           middleware: route.middlewareList,
           routeName: route.routeName,
         }
+
+        if (bindings.size > 0) {
+          match.bindings = bindings
+        }
+
+        return match
       }
     }
 

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++) {