@mantiq/core 0.5.22 → 0.5.23

package/package.json

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

package/src/application/Application.ts

@@ -210,11 +210,64 @@ export class Application extends ContainerImpl {
     coreProviders: Constructor<ServiceProvider>[] = [],
     userProviders: Constructor<ServiceProvider>[] = [],
   ): Promise<void> {
+    this.validateEnvironment()
     const packageProviders = await this.discoverPackageProviders()
     await this.registerProviders([...coreProviders, ...packageProviders, ...userProviders])
     await this.bootProviders()
   }
 
+  /**
+   * Validate environment variables on startup.
+   * Called at the beginning of bootstrap() to catch misconfigurations early.
+   *
+   * Checks:
+   * - APP_ENV must be set
+   * - APP_KEY format (if set): must start with 'base64:' and decode to exactly 32 bytes
+   * - Warns if APP_DEBUG=true in production
+   */
+  validateEnvironment(): void {
+    // APP_ENV must be set
+    if (!process.env['APP_ENV']) {
+      throw new Error(
+        'APP_ENV is not set. Set it in your .env file (e.g., APP_ENV=local).',
+      )
+    }
+
+    // Validate APP_KEY format when present
+    const appKey = process.env['APP_KEY']
+    if (appKey) {
+      if (!appKey.startsWith('base64:')) {
+        throw new Error(
+          'APP_KEY must start with "base64:". Generate one with: bun mantiq key:generate',
+        )
+      }
+
+      try {
+        const decoded = Buffer.from(appKey.slice(7), 'base64')
+        if (decoded.length !== 32) {
+          throw new Error(
+            `APP_KEY must decode to exactly 32 bytes (got ${decoded.length}). ` +
+            'Generate one with: bun mantiq key:generate',
+          )
+        }
+      } catch (e) {
+        if (e instanceof Error && e.message.startsWith('APP_KEY must')) {
+          throw e
+        }
+        throw new Error(
+          'APP_KEY contains invalid base64 data. Generate one with: bun mantiq key:generate',
+        )
+      }
+    }
+
+    // Warn on APP_DEBUG=true in production
+    if (process.env['APP_ENV'] === 'production' && process.env['APP_DEBUG'] === 'true') {
+      console.warn(
+        '[Mantiq] WARNING: APP_DEBUG=true in production. This may expose sensitive data.',
+      )
+    }
+  }
+
   // ── Provider lifecycle ────────────────────────────────────────────────────
 
   /**

package/src/cache/FileCacheStore.ts

@@ -1,6 +1,7 @@
 import type { CacheStore } from '../contracts/Cache.ts'
 import { join } from 'node:path'
-import { mkdir, rm, readdir } from 'node:fs/promises'
+import { mkdir, rm, readdir, rename } from 'node:fs/promises'
+import { randomBytes } from 'node:crypto'
 
 interface FileCachePayload {
   value: unknown
@@ -94,13 +95,44 @@ export class FileCacheStore implements CacheStore {
   /**
    * 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.
+   * Uses write-to-temp + rename to avoid TOCTOU race conditions.
+   * If the key already exists (and is not expired), returns false.
    */
   async add(key: string, value: unknown, ttl?: number): Promise<boolean> {
-    if (await this.has(key)) return false
-    await this.put(key, value, ttl)
+    await this.ensureDirectory()
+
+    const targetPath = this.path(key)
+
+    // Check if key already exists and is not expired
+    const file = Bun.file(targetPath)
+    if (await file.exists()) {
+      try {
+        const payload: FileCachePayload = await file.json()
+        if (payload.expiresAt === null || Date.now() <= payload.expiresAt) {
+          return false
+        }
+        // Expired — fall through to overwrite
+      } catch {
+        // Corrupted file — fall through to overwrite
+      }
+    }
+
+    // Write to a temp file first, then atomically rename into place
+    const tmpPath = join(this.directory, `_tmp_${randomBytes(8).toString('hex')}.cache`)
+    const payload: FileCachePayload = {
+      value,
+      expiresAt: ttl != null ? Date.now() + ttl * 1000 : null,
+    }
+    await Bun.write(tmpPath, JSON.stringify(payload))
+
+    try {
+      await rename(tmpPath, targetPath)
+    } catch {
+      // Cleanup temp file on failure
+      try { await rm(tmpPath) } catch { /* ignore */ }
+      return false
+    }
+
     return true
   }
 

package/src/contracts/Request.ts

@@ -11,8 +11,8 @@ export interface MantiqRequest {
   // ── Input ────────────────────────────────────────────────────────────────
   query(key: string, defaultValue?: string): string
   query(): Record<string, string>
-  input(key: string, defaultValue?: any): Promise<any>
-  input(): Promise<Record<string, any>>
+  input<T = any>(key: string, defaultValue?: any): Promise<T>
+  input<T = Record<string, any>>(): Promise<T>
   only(...keys: string[]): Promise<Record<string, any>>
   except(...keys: string[]): Promise<Record<string, any>>
   has(...keys: string[]): boolean
@@ -42,6 +42,7 @@ export interface MantiqRequest {
   param(key: string, defaultValue?: any): any
   params(): Record<string, any>
   setRouteParams(params: Record<string, any>): void
+  setRouteParam(key: string, value: any): void
 
   // ── Session ──────────────────────────────────────────────────────────────
   session(): SessionStore

package/src/contracts/Router.ts

@@ -21,6 +21,7 @@ export interface RouteMatch {
   params: Record<string, any>
   middleware: string[]
   routeName?: string | undefined
+  bindings?: Map<string, { model: any; key: string }>
 }
 
 export interface RouteDefinition {
@@ -60,4 +61,5 @@ export interface RouterRoute {
   whereNumber(param: string): this
   whereAlpha(param: string): this
   whereUuid(param: string): this
+  bind(param: string, model: any, key?: string): this
 }

package/src/encryption/errors.ts

@@ -1,11 +1,12 @@
 import { MantiqError } from '../errors/MantiqError.ts'
+import { ErrorCodes } from '../errors/ErrorCodes.ts'
 
 /**
  * Thrown when encryption fails (e.g. invalid key, algorithm error).
  */
 export class EncryptionError extends MantiqError {
   constructor(message = 'Could not encrypt the data.', context?: Record<string, any>) {
-    super(message, context)
+    super(message, context, ErrorCodes.ENCRYPTION_FAILED)
   }
 }
 
@@ -14,7 +15,7 @@ export class EncryptionError extends MantiqError {
  */
 export class DecryptionError extends MantiqError {
   constructor(message = 'Could not decrypt the data.', context?: Record<string, any>) {
-    super(message, context)
+    super(message, context, ErrorCodes.DECRYPTION_FAILED)
   }
 }
 
@@ -25,6 +26,8 @@ export class MissingAppKeyError extends MantiqError {
   constructor() {
     super(
       'No application encryption key has been specified. Set the APP_KEY environment variable (use "base64:<key>" format for raw keys).',
+      undefined,
+      ErrorCodes.MISSING_APP_KEY,
     )
   }
 }

package/src/errors/ConfigKeyNotFoundError.ts

@@ -1,7 +1,12 @@
 import { MantiqError } from './MantiqError.ts'
+import { ErrorCodes } from './ErrorCodes.ts'
 
 export class ConfigKeyNotFoundError extends MantiqError {
   constructor(public readonly key: string) {
-    super(`Config key '${key}' not found and no default value provided.`)
+    super(
+      `Config key '${key}' not found and no default value provided.`,
+      undefined,
+      ErrorCodes.CONFIG_NOT_FOUND,
+    )
   }
 }

package/src/errors/ContainerResolutionError.ts

@@ -1,4 +1,5 @@
 import { MantiqError } from './MantiqError.ts'
+import { ErrorCodes } from './ErrorCodes.ts'
 
 export class ContainerResolutionError extends MantiqError {
   constructor(
@@ -8,6 +9,8 @@ export class ContainerResolutionError extends MantiqError {
   ) {
     super(
       `Cannot resolve ${String(abstract)}: ${reason}.${details ? ' ' + details : ''}`,
+      undefined,
+      ErrorCodes.CONTAINER_RESOLUTION,
     )
   }
 }

package/src/errors/ErrorCodes.ts

@@ -0,0 +1,27 @@
+/**
+ * Structured error codes for all MantiqJS framework errors.
+ *
+ * Each error code follows the pattern `E_{CATEGORY}_{DESCRIPTION}`.
+ */
+export const ErrorCodes = {
+  AUTH_UNAUTHENTICATED: 'E_AUTH_UNAUTHENTICATED',
+  AUTH_UNAUTHORIZED: 'E_AUTH_UNAUTHORIZED',
+  AUTH_FORBIDDEN: 'E_AUTH_FORBIDDEN',
+  VALIDATION_FAILED: 'E_VALIDATION_FAILED',
+  MODEL_NOT_FOUND: 'E_MODEL_NOT_FOUND',
+  ROUTE_NOT_FOUND: 'E_ROUTE_NOT_FOUND',
+  CSRF_MISMATCH: 'E_CSRF_MISMATCH',
+  ENCRYPTION_FAILED: 'E_ENCRYPTION_FAILED',
+  DECRYPTION_FAILED: 'E_DECRYPTION_FAILED',
+  MISSING_APP_KEY: 'E_MISSING_APP_KEY',
+  RATE_LIMITED: 'E_RATE_LIMITED',
+  CONTAINER_RESOLUTION: 'E_CONTAINER_RESOLUTION',
+  CONFIG_NOT_FOUND: 'E_CONFIG_NOT_FOUND',
+  QUERY_ERROR: 'E_QUERY_ERROR',
+  CONNECTION_LOST: 'E_CONNECTION_LOST',
+  CONNECTION_FAILED: 'E_CONNECTION_FAILED',
+  DRIVER_NOT_SUPPORTED: 'E_DRIVER_NOT_SUPPORTED',
+  HTTP_ERROR: 'E_HTTP_ERROR',
+} as const
+
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes]

package/src/errors/ForbiddenError.ts

@@ -1,7 +1,8 @@
 import { HttpError } from './HttpError.ts'
+import { ErrorCodes } from './ErrorCodes.ts'
 
 export class ForbiddenError extends HttpError {
   constructor(message = 'Forbidden', headers?: Record<string, string>) {
-    super(403, message, headers)
+    super(403, message, headers, undefined, ErrorCodes.AUTH_FORBIDDEN)
   }
 }

package/src/errors/HttpError.ts

@@ -1,4 +1,6 @@
 import { MantiqError } from './MantiqError.ts'
+import { ErrorCodes } from './ErrorCodes.ts'
+import type { ErrorCode } from './ErrorCodes.ts'
 
 /**
  * Base class for all HTTP-facing errors.
@@ -10,7 +12,8 @@ export class HttpError extends MantiqError {
     message: string,
     public readonly headers?: Record<string, string>,
     context?: Record<string, any>,
+    errorCode?: ErrorCode | string,
   ) {
-    super(message, context)
+    super(message, context, errorCode ?? ErrorCodes.HTTP_ERROR)
   }
 }

package/src/errors/MantiqError.ts

@@ -1,14 +1,25 @@
+import type { ErrorCode } from './ErrorCodes.ts'
+
 /**
  * Base error class for all MantiqJS errors.
- * All packages must throw subclasses of this — never raw Error.
+ * All packages must throw subclasses of this -- never raw Error.
  */
 export class MantiqError extends Error {
+  /**
+   * Machine-readable error code for structured error handling.
+   * Subclasses should set this to the appropriate `ErrorCodes.*` value.
+   * Accepts any string to allow packages like OAuth to use spec-defined codes.
+   */
+  public readonly errorCode: ErrorCode | string | undefined
+
   constructor(
     message: string,
     public readonly context?: Record<string, any>,
+    errorCode?: ErrorCode | string,
   ) {
     super(message)
     this.name = this.constructor.name
+    this.errorCode = errorCode
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, this.constructor)
     }

package/src/errors/NotFoundError.ts

@@ -1,7 +1,8 @@
 import { HttpError } from './HttpError.ts'
+import { ErrorCodes } from './ErrorCodes.ts'
 
 export class NotFoundError extends HttpError {
   constructor(message = 'Not Found', headers?: Record<string, string>) {
-    super(404, message, headers)
+    super(404, message, headers, undefined, ErrorCodes.ROUTE_NOT_FOUND)
   }
 }

package/src/errors/TokenMismatchError.ts

@@ -1,10 +1,11 @@
 import { HttpError } from './HttpError.ts'
+import { ErrorCodes } from './ErrorCodes.ts'
 
 /**
  * Thrown when the CSRF token is missing or invalid.
  */
 export class TokenMismatchError extends HttpError {
   constructor(message = 'CSRF token mismatch.') {
-    super(419, message)
+    super(419, message, undefined, undefined, ErrorCodes.CSRF_MISMATCH)
   }
 }

package/src/errors/TooManyRequestsError.ts

@@ -1,10 +1,11 @@
 import { HttpError } from './HttpError.ts'
+import { ErrorCodes } from './ErrorCodes.ts'
 
 export class TooManyRequestsError extends HttpError {
   constructor(
     message = 'Too Many Requests',
     public readonly retryAfter?: number,
   ) {
-    super(429, message, retryAfter ? { 'Retry-After': String(retryAfter) } : undefined)
+    super(429, message, retryAfter ? { 'Retry-After': String(retryAfter) } : undefined, undefined, ErrorCodes.RATE_LIMITED)
   }
 }

package/src/errors/UnauthorizedError.ts

@@ -1,7 +1,8 @@
 import { HttpError } from './HttpError.ts'
+import { ErrorCodes } from './ErrorCodes.ts'
 
 export class UnauthorizedError extends HttpError {
   constructor(message = 'Unauthorized', headers?: Record<string, string>) {
-    super(401, message, headers)
+    super(401, message, headers, undefined, ErrorCodes.AUTH_UNAUTHENTICATED)
   }
 }

package/src/errors/ValidationError.ts

@@ -1,10 +1,11 @@
 import { HttpError } from './HttpError.ts'
+import { ErrorCodes } from './ErrorCodes.ts'
 
 export class ValidationError extends HttpError {
   constructor(
     public readonly errors: Record<string, string[]>,
     message = 'The given data was invalid.',
   ) {
-    super(422, message, undefined, { errors })
+    super(422, message, undefined, { errors }, ErrorCodes.VALIDATION_FAILED)
   }
 }

package/src/helpers/signedUrl.ts

@@ -0,0 +1,26 @@
+import { Application } from '../application/Application.ts'
+import type { AesEncrypter } from '../encryption/Encrypter.ts'
+import { UrlSigner } from '../url/UrlSigner.ts'
+import { ENCRYPTER } from './encrypt.ts'
+
+/**
+ * Create a signed URL.
+ *
+ * @example const url = await signedUrl('https://example.com/verify?user=42')
+ */
+export async function signedUrl(url: string, expiresAt?: Date): Promise<string> {
+  const encrypter = Application.getInstance().make<AesEncrypter>(ENCRYPTER)
+  const signer = new UrlSigner(encrypter)
+  return signer.sign(url, expiresAt)
+}
+
+/**
+ * Validate a signed URL.
+ *
+ * @example const valid = await hasValidSignature('https://example.com/verify?user=42&signature=...')
+ */
+export async function hasValidSignature(url: string): Promise<boolean> {
+  const encrypter = Application.getInstance().make<AesEncrypter>(ENCRYPTER)
+  const signer = new UrlSigner(encrypter)
+  return signer.validate(url)
+}

package/src/helpers/url.ts

@@ -0,0 +1,31 @@
+import { Application } from '../application/Application.ts'
+import type { AesEncrypter } from '../encryption/Encrypter.ts'
+import { UrlSigner } from '../url/UrlSigner.ts'
+import { ENCRYPTER } from './encrypt.ts'
+
+/**
+ * Create a signed URL.
+ *
+ * @example
+ * const url = await signedUrl('https://example.com/unsubscribe?user=42')
+ * const temp = await signedUrl('https://example.com/download', new Date(Date.now() + 3600_000))
+ */
+export async function signedUrl(url: string, expiresAt?: Date): Promise<string> {
+  const encrypter = Application.getInstance().make<AesEncrypter>(ENCRYPTER)
+  const signer = new UrlSigner(encrypter)
+  return signer.sign(url, expiresAt)
+}
+
+/**
+ * Validate a signed URL: verify signature and check expiration.
+ *
+ * @example
+ * if (await hasValidSignature(request.fullUrl())) {
+ *   // URL is authentic and not expired
+ * }
+ */
+export async function hasValidSignature(url: string): Promise<boolean> {
+  const encrypter = Application.getInstance().make<AesEncrypter>(ENCRYPTER)
+  const signer = new UrlSigner(encrypter)
+  return signer.validate(url)
+}

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/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,6 +88,13 @@ 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)

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/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/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/url/UrlSigner.ts

@@ -0,0 +1,131 @@
+import type { AesEncrypter } from '../encryption/Encrypter.ts'
+
+/**
+ * URL signing utility.
+ *
+ * Generates signed URLs with HMAC-based signatures so you can create links
+ * that prove they haven't been tampered with (e.g. email verification links,
+ * temporary download URLs).
+ *
+ * Uses the application's AesEncrypter key to derive HMAC-SHA256 signatures.
+ *
+ * @example
+ * ```ts
+ * const signer = new UrlSigner(encrypter)
+ * const signed = await signer.sign('https://example.com/verify?user=42')
+ * const isValid = await signer.validate(signed) // true
+ *
+ * const temp = await signer.temporarySignedUrl('https://example.com/download/file.zip', 60)
+ * ```
+ */
+export class UrlSigner {
+  private signingKey: CryptoKey | null = null
+
+  constructor(private readonly encrypter: AesEncrypter) {}
+
+  /**
+   * Sign a URL by appending a signature (and optional expiration) as query parameters.
+   */
+  async sign(url: string, expiresAt?: Date): Promise<string> {
+    const parsed = new URL(url)
+
+    // Remove any existing signature params to prevent double-signing
+    parsed.searchParams.delete('signature')
+    parsed.searchParams.delete('expires')
+
+    if (expiresAt) {
+      parsed.searchParams.set('expires', String(Math.floor(expiresAt.getTime() / 1000)))
+    }
+
+    const signature = await this.createSignature(parsed.toString())
+    parsed.searchParams.set('signature', signature)
+
+    return parsed.toString()
+  }
+
+  /**
+   * Validate a signed URL — verify the signature and check expiration.
+   */
+  async validate(url: string): Promise<boolean> {
+    const parsed = new URL(url)
+
+    const signature = parsed.searchParams.get('signature')
+    if (!signature) return false
+
+    // Check expiration before verifying signature
+    const expires = parsed.searchParams.get('expires')
+    if (expires) {
+      const expiresAt = Number(expires) * 1000
+      if (Date.now() > expiresAt) return false
+    }
+
+    // Reconstruct the URL without the signature to verify
+    parsed.searchParams.delete('signature')
+    const expectedSignature = await this.createSignature(parsed.toString())
+
+    return timingSafeEqual(signature, expectedSignature)
+  }
+
+  /**
+   * Create a temporary signed URL that expires after the given number of minutes.
+   */
+  async temporarySignedUrl(url: string, minutes: number): Promise<string> {
+    return this.sign(url, new Date(Date.now() + minutes * 60_000))
+  }
+
+  // ── Internal ────────────────────────────────────────────────────────────
+
+  /**
+   * Derive the HMAC signing key from the encrypter's raw AES key.
+   */
+  private async getSigningKey(): Promise<CryptoKey> {
+    if (this.signingKey) return this.signingKey
+
+    this.signingKey = await crypto.subtle.importKey(
+      'raw',
+      this.encrypter.getKey() as ArrayBuffer,
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['sign', 'verify'],
+    )
+
+    return this.signingKey
+  }
+
+  /**
+   * Create an HMAC-SHA256 signature for the given data string.
+   */
+  private async createSignature(data: string): Promise<string> {
+    const key = await this.getSigningKey()
+    const encoded = new TextEncoder().encode(data)
+    const signature = await crypto.subtle.sign('HMAC', key, encoded)
+    return encodeHex(new Uint8Array(signature))
+  }
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+function encodeHex(bytes: Uint8Array): string {
+  let hex = ''
+  for (let i = 0; i < bytes.length; i++) {
+    hex += bytes[i]!.toString(16).padStart(2, '0')
+  }
+  return hex
+}
+
+/**
+ * Constant-time string comparison to prevent timing attacks on signature verification.
+ */
+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
+}

package/src/websocket/WebSocketKernel.ts

@@ -94,7 +94,9 @@ export class WebSocketKernel {
       try {
         decrypted[name] = await this.encrypter!.decrypt(value)
       } catch {
-        decrypted[name] = value
+        // Can't decrypt — expired key, tampered, or wrong format.
+        // Don't pass through the encrypted blob; discard it.
+        decrypted[name] = ''
       }
     }