@mantiq/core 0.5.21 → 0.5.23

package/src/providers/CoreServiceProvider.ts

@@ -10,6 +10,8 @@ import { StartSession } from '../middleware/StartSession.ts'
 import { EncryptCookies } from '../middleware/EncryptCookies.ts'
 import { VerifyCsrfToken } from '../middleware/VerifyCsrfToken.ts'
 import { ThrottleRequests } from '../rateLimit/ThrottleRequests.ts'
+import { SecureHeaders } from '../middleware/SecureHeaders.ts'
+import { TimeoutMiddleware } from '../middleware/TimeoutMiddleware.ts'
 import { ROUTER } from '../helpers/route.ts'
 import { ENCRYPTER } from '../helpers/encrypt.ts'
 import { AesEncrypter } from '../encryption/Encrypter.ts'
@@ -80,6 +82,8 @@ 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) => {
@@ -96,6 +100,10 @@ export class CoreServiceProvider extends ServiceProvider {
     if (appKey) {
       const encrypter = await AesEncrypter.fromAppKey(appKey)
       this.app.instance(ENCRYPTER, encrypter)
+
+      // Give WebSocketKernel the encrypter so it can decrypt cookies on upgrade
+      const wsKernel = this.app.make(WebSocketKernel)
+      wsKernel.setEncrypter(encrypter)
     }
 
     // ── Auto-register middleware aliases on HttpKernel ─────────────────────
@@ -106,6 +114,8 @@ export class CoreServiceProvider extends ServiceProvider {
     kernel.registerMiddleware('encrypt.cookies', EncryptCookies)
     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)
@@ -118,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/Store.ts

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

package/src/support/Enum.ts

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

package/src/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

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