@mantiq/core 0.5.21 → 0.5.23

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.
@@ -99,9 +113,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)
@@ -169,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

@@ -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,
@@ -55,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>> {
@@ -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 {
@@ -176,6 +211,10 @@ export class MantiqRequest implements MantiqRequestContract {
     this.routeParams = params
   }
 
+  setRouteParam(key: string, value: any): void {
+    this.routeParams[key] = value
+  }
+
   // ── Session ──────────────────────────────────────────────────────────────
 
   session(): SessionStore {
@@ -213,6 +252,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 +295,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

@@ -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'
@@ -56,12 +59,19 @@ 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 { 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'
 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'
 
@@ -101,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

@@ -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,8 +47,13 @@ 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.)
-        decrypted[name] = value
+        // 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}" — discarding value`)
+        }
+        decrypted[name] = ''
       }
     }
 
@@ -83,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/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/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
+    }
+  }
+}