@c9up/ream 0.1.3

package/src/server/Server.ts

@@ -0,0 +1,147 @@
+/**
+ * Server — manages HTTP server middleware, error handler, and router.
+ *
+ * Like AdonisJS Server class:
+ * - server.use([() => import('#middleware/...')]) — lazy class middleware
+ * - server.errorHandler(() => import('#exceptions/handler')) — custom exception handler
+ */
+
+import type { ExceptionHandler } from '../http/Exception.js'
+import type { HttpContext } from '../http/HttpContext.js'
+import type { MiddlewareFunction } from '../middleware/Pipeline.js'
+import type { Router } from '../router/Router.js'
+
+/**
+ * A middleware class with a handle method.
+ * This is the pattern used by AdonisJS middleware.
+ */
+export interface MiddlewareClass {
+  handle(ctx: HttpContext, next: () => Promise<void>): Promise<void> | void
+}
+
+/** Lazy import returning a module with a default export. */
+export type LazyImport<T> = () => Promise<{ default: T }>
+
+// biome-ignore lint/suspicious/noExplicitAny: contravariance — same as ControllerAction
+export type ErrorHandlerClass = new (...args: any[]) => ExceptionHandler
+
+// biome-ignore lint/suspicious/noExplicitAny: contravariance — middleware class constructors
+type MiddlewareClassConstructor = new (...args: any[]) => MiddlewareClass
+
+/** What server.use() and router.use() accept: lazy imports or direct functions. */
+export type MiddlewareEntry = LazyImport<MiddlewareClassConstructor> | MiddlewareFunction
+
+export class Server {
+  #router: Router
+  #serverMiddleware: MiddlewareFunction[] = []
+  #errorHandlerImporter?: LazyImport<ErrorHandlerClass>
+  #resolvedErrorHandler?: ExceptionHandler
+  #trustedProxies: string[] = []
+
+  constructor(router: Router) {
+    this.#router = router
+  }
+
+  /**
+   * Configure the trusted-proxy CIDR list. The Rust HyperServer uses it to
+   * pre-resolve `request.ip` once per request — JS reads the field, no CIDR
+   * matching in TS.
+   *
+   * Empty list (default, 2026-05+) is **strict fail-closed**: `X-Forwarded-For`
+   * and `X-Real-IP` are ignored entirely; only the socket peer is used.
+   * Apps deployed behind a reverse proxy must list the proxy's CIDR
+   * (`'10.0.0.0/8'`, `'192.0.2.0/24'`, etc.) or pass the `'*'` sentinel
+   * for permissive mode (accepts spoofing as the explicit trade-off when
+   * proxy CIDRs can't be enumerated).
+   */
+  trustedProxies(cidrs: string[]): this {
+    this.#trustedProxies = [...cidrs]
+    return this
+  }
+
+  /** Read the current trusted-proxy list (consumed by Ignitor at boot). */
+  getTrustedProxies(): readonly string[] {
+    return this.#trustedProxies
+  }
+
+  /**
+   * Register global server middleware.
+   * Accepts lazy imports of middleware classes (AdonisJS pattern):
+   *   server.use([() => import('#middleware/log_request_middleware')])
+   */
+  use(middleware: MiddlewareEntry[]): this {
+    for (const mw of middleware) {
+      this.#serverMiddleware.push(resolveMiddlewareEntry(mw))
+    }
+    return this
+  }
+
+  /**
+   * Register a custom error handler.
+   *   server.errorHandler(() => import('#exceptions/handler'))
+   */
+  errorHandler(handler: LazyImport<ErrorHandlerClass>): this {
+    this.#errorHandlerImporter = handler
+    return this
+  }
+
+  /** Boot — resolve the error handler. Called by Ignitor during ready phase. */
+  async boot(): Promise<void> {
+    if (this.#errorHandlerImporter) {
+      const mod = await this.#errorHandlerImporter()
+      const HandlerClass = mod.default
+      this.#resolvedErrorHandler = new HandlerClass()
+    }
+  }
+
+  getServerMiddleware(): MiddlewareFunction[] {
+    return [...this.#serverMiddleware]
+  }
+
+  getErrorHandler(): ExceptionHandler | undefined {
+    return this.#resolvedErrorHandler
+  }
+
+  getRouter(): Router {
+    return this.#router
+  }
+}
+
+/**
+ * Convert a MiddlewareEntry (lazy import or function) into a MiddlewareFunction.
+ * Lazy imports are resolved on first call and cached.
+ */
+export function resolveMiddlewareEntry(entry: MiddlewareEntry): MiddlewareFunction {
+  // Direct middleware function (2 params: ctx, next)
+  if (isMiddlewareFunction(entry)) {
+    return entry
+  }
+
+  // Lazy import of a middleware class — resolve + cache on first invocation
+  // After isMiddlewareFunction returns false, entry is narrowed to LazyImport<MiddlewareClassConstructor>
+  const lazyImport = entry
+  let cached: MiddlewareClass | undefined
+  return async (ctx: HttpContext, next: () => Promise<void>) => {
+    if (!cached) {
+      const mod = await lazyImport()
+      cached = new mod.default()
+    }
+    await cached.handle(ctx, next)
+  }
+}
+
+/** Check if an entry is a direct middleware function (not a lazy import). */
+function isMiddlewareFunction(entry: MiddlewareEntry): entry is MiddlewareFunction {
+  // A lazy import factory returns a promise (dynamic import). Middleware functions don't.
+  // We check: if calling it with no args returns a thenable, it's a lazy import.
+  // Better heuristic: lazy imports are () => import(...) which have .length === 0
+  // and middleware functions have .length >= 2 (ctx, next).
+  // Edge case: arrow with defaults has length 1. But lazy import() always has length 0.
+  if (typeof entry !== 'function') return false
+  // Functions with 2+ params are definitely middleware
+  if (entry.length >= 2) return true
+  // Functions with 0 params are likely lazy imports
+  if (entry.length === 0) return false
+  // 1 param is ambiguous — treat as middleware (ctx only, no next)
+  return true
+}

package/src/services/app.ts

@@ -0,0 +1,34 @@
+/**
+ * Application singleton service.
+ *
+ * Usage:
+ *   import app from '@c9up/ream/services/app'
+ *   const logger = app.container.make('logger')
+ *   if (app.inProduction) { ... }
+ */
+
+import type { Application } from '../Application.js'
+
+let instance: Application | undefined
+
+/** @internal Set the app instance (called by Ignitor). */
+export function setApp(app: Application): void {
+  instance = app
+}
+
+const app: Application = new Proxy({} as Application, {
+  get(_target, prop) {
+    if (!instance) {
+      throw new Error(
+        'Application accessed before initialization. ' +
+          'Ensure this code runs during or after the boot phase.',
+      )
+    }
+    // Bind methods so private-field writes inside the class resolve
+    // against the real instance brand instead of the Proxy.
+    const value = Reflect.get(instance, prop, instance)
+    return typeof value === 'function' ? value.bind(instance) : value
+  },
+})
+
+export default app

package/src/services/router.ts

@@ -0,0 +1,44 @@
+/**
+ * Router singleton service — proxy to the Ignitor's router instance.
+ *
+ * Usage in module route files:
+ *   import router from '@c9up/ream/services/router'
+ *   router.get('/tasks', [TasksController, 'index'])
+ *
+ * The proxy is initialized by Ignitor before preload files are imported.
+ */
+
+import type { Router } from '../router/Router.js'
+
+let instance: Router | undefined
+
+/** @internal Set the router instance (called by Ignitor). */
+export function setRouter(router: Router): void {
+  instance = router
+}
+
+/** @internal Get the router instance directly. */
+export function getRouter(): Router | undefined {
+  return instance
+}
+
+/**
+ * Router proxy — defers all property access to the underlying instance.
+ * Throws if accessed before Ignitor initializes it.
+ */
+const router: Router = new Proxy({} as Router, {
+  get(_target, prop) {
+    if (!instance) {
+      throw new Error(
+        'Router accessed before initialization. ' +
+          'Ensure your route files are loaded as preloads in reamrc.ts, not at import time.',
+      )
+    }
+    // Bind methods so private-field writes inside the class resolve
+    // against the real instance brand instead of the Proxy.
+    const value = Reflect.get(instance, prop, instance)
+    return typeof value === 'function' ? value.bind(instance) : value
+  },
+})
+
+export default router

package/src/services/server.ts

@@ -0,0 +1,40 @@
+/**
+ * Server singleton service — proxy to the Ignitor's Server instance.
+ *
+ * Usage in start/kernel.ts:
+ *   import server from '@c9up/ream/services/server'
+ *   server.errorHandler(() => import('#exceptions/handler'))
+ *   server.use([() => import('#middleware/logging')])
+ */
+
+import type { Server } from '../server/Server.js'
+
+let instance: Server | undefined
+
+/** @internal Set the server instance (called by Ignitor). */
+export function setServer(server: Server): void {
+  instance = server
+}
+
+/** @internal Get the server instance directly. */
+export function getServer(): Server | undefined {
+  return instance
+}
+
+const server: Server = new Proxy({} as Server, {
+  get(_target, prop) {
+    if (!instance) {
+      throw new Error(
+        'Server accessed before initialization. ' +
+          'Ensure your kernel files are loaded as preloads in reamrc.ts.',
+      )
+    }
+    // Bind methods to the real instance so private-field access inside
+    // them resolves against the underlying class brand — passing the
+    // Proxy as `this` breaks `#field` writes (Proxy isn't branded).
+    const value = Reflect.get(instance, prop, instance)
+    return typeof value === 'function' ? value.bind(instance) : value
+  },
+})
+
+export default server

package/src/session/Session.ts

@@ -0,0 +1,231 @@
+/**
+ * Session — server-side session management.
+ *
+ * Like AdonisJS Session:
+ *   session.get('key')
+ *   session.put('key', value)
+ *   session.flash('success', 'Saved!')
+ *   session.forget('key')
+ *
+ * Backed by pluggable drivers (cookie, memory, redis).
+ */
+
+export interface SessionDriver {
+  read(sessionId: string): Promise<Record<string, unknown>>
+  write(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<void>
+  destroy(sessionId: string): Promise<void>
+  touch(sessionId: string, ttl: number): Promise<void>
+}
+
+export interface SessionConfig {
+  driver: string
+  cookieName?: string
+  maxAge?: number // seconds, default 7200 (2h)
+  clearWithBrowser?: boolean
+  /**
+   * When true, re-emit Set-Cookie on every response so the cookie's `maxAge`
+   * window slides forward on each request. Active users won't be logged out
+   * mid-session; the trade-off is a `Vary: Cookie` side-channel on every
+   * response (defeats shared HTTP caches). Default `false` to preserve cache
+   * behaviour. Express-session and AdonisJS expose the same toggle.
+   */
+  rolling?: boolean
+}
+
+/**
+ * Generate a fresh session ID. Format mirrors AdonisJS / express-session —
+ * 32 bytes of base64url entropy (~256 bits). Defined here so `regenerate()`
+ * can pick a new id without bringing in a driver dependency.
+ */
+function generateSessionId(): string {
+  const bytes = new Uint8Array(32)
+  // `crypto.getRandomValues` is a Node ≥ 19 builtin AND the standard browser
+  // API; same call site works on both runtimes without a polyfill.
+  crypto.getRandomValues(bytes)
+  let str = ''
+  for (let i = 0; i < bytes.length; i++) {
+    str += String.fromCharCode(bytes[i] ?? 0)
+  }
+  return btoa(str).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')
+}
+
+export class Session {
+  #data: Record<string, unknown> = {}
+  #flashData: Record<string, unknown> = {}
+  #previousFlash: Record<string, unknown> = {}
+  #dirty = false
+  #sessionId: string
+  /**
+   * The session id active when the request arrived, captured at construction.
+   * The middleware uses this on the way out to migrate driver storage
+   * (`driver.write(newId)` + `driver.destroy(oldId)`) when the application
+   * called `regenerate()` mid-request.
+   */
+  readonly #originalSessionId: string
+  #regenerated = false
+
+  constructor(sessionId: string, data: Record<string, unknown> = {}) {
+    this.#sessionId = sessionId
+    this.#originalSessionId = sessionId
+    this.#data = { ...data }
+    const flash = data.__flash
+    this.#previousFlash =
+      typeof flash === 'object' && flash !== null && !Array.isArray(flash)
+        ? // biome-ignore lint/suspicious/noExplicitAny: flash narrowed to non-null non-array object; branded as Record for key access
+          (flash as any as Record<string, unknown>)
+        : {}
+    delete this.#data.__flash
+  }
+
+  /** Current session id. Mutated by `regenerate()`. */
+  get sessionId(): string {
+    return this.#sessionId
+  }
+
+  /**
+   * Rotate the session id while preserving the data. The standard mitigation
+   * for session-fixation (CWE-384): call this whenever a privilege boundary
+   * is crossed — login, role change, sensitive-action confirmation. Warden's
+   * `SessionStrategy.login()` calls it automatically before writing the
+   * authenticated user id.
+   *
+   * The new id takes effect inside this Session instance immediately so
+   * subsequent `session.get()` / `session.put()` see the same data under
+   * the new id. The SessionMiddleware sees `wasRegenerated() === true` on
+   * the way out and migrates the driver storage + emits a new Set-Cookie.
+   */
+  regenerate(): void {
+    this.#sessionId = generateSessionId()
+    this.#regenerated = true
+    this.#dirty = true
+  }
+
+  /** @internal — read by SessionMiddleware to detect a mid-request rotation. */
+  wasRegenerated(): boolean {
+    return this.#regenerated
+  }
+
+  /** @internal — the id captured at request arrival; used to destroy the old driver entry post-regenerate. */
+  originalSessionId(): string {
+    return this.#originalSessionId
+  }
+
+  /** Get a session value. */
+  get<T = unknown>(key: string, defaultValue?: T): T {
+    if (key in this.#data) {
+      // biome-ignore lint/suspicious/noExplicitAny: session data stored as unknown; caller brands the value type via T
+      return this.#data[key] as any as T
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: generic default — caller brands the value type via T
+    return defaultValue as any as T
+  }
+
+  /** Set a session value. */
+  put(key: string, value: unknown): void {
+    this.#data[key] = value
+    this.#dirty = true
+  }
+
+  /** Check if a key exists. */
+  has(key: string): boolean {
+    return key in this.#data
+  }
+
+  /** Get all session data. */
+  all(): Record<string, unknown> {
+    return { ...this.#data }
+  }
+
+  /** Remove a key. */
+  forget(key: string): void {
+    delete this.#data[key]
+    this.#dirty = true
+  }
+
+  /** Get and remove a key. */
+  pull<T = unknown>(key: string, defaultValue?: T): T {
+    const value = this.get<T>(key, defaultValue)
+    this.forget(key)
+    return value
+  }
+
+  /** Clear all session data. */
+  clear(): void {
+    this.#data = {}
+    this.#dirty = true
+  }
+
+  /** Increment a numeric value. */
+  increment(key: string, amount = 1): void {
+    const current = this.get<number>(key) ?? 0
+    this.put(key, current + amount)
+  }
+
+  /** Decrement a numeric value. */
+  decrement(key: string, amount = 1): void {
+    this.increment(key, -amount)
+  }
+
+  // ─── Flash data ───────────────────────────────────────────
+
+  /** Set flash data (available only on the next request). */
+  flash(key: string, value: unknown): void {
+    this.#flashData[key] = value
+    this.#dirty = true
+  }
+
+  /** Flash all current input. */
+  flashAll(input: Record<string, unknown>): void {
+    for (const [k, v] of Object.entries(input)) {
+      this.#flashData[k] = v
+    }
+    this.#dirty = true
+  }
+
+  /** Flash only specific keys. */
+  flashOnly(input: Record<string, unknown>, keys: string[]): void {
+    for (const k of keys) {
+      if (k in input) this.#flashData[k] = input[k]
+    }
+    this.#dirty = true
+  }
+
+  /** Flash all except specific keys. */
+  flashExcept(input: Record<string, unknown>, keys: string[]): void {
+    const keySet = new Set(keys)
+    for (const [k, v] of Object.entries(input)) {
+      if (!keySet.has(k)) this.#flashData[k] = v
+    }
+    this.#dirty = true
+  }
+
+  /** Get a flashed value from the previous request. */
+  flashMessages(): Record<string, unknown> {
+    return { ...this.#previousFlash }
+  }
+
+  /** Get a specific flash message from the previous request. */
+  old<T = unknown>(key: string, defaultValue?: T): T {
+    if (key in this.#previousFlash) {
+      // biome-ignore lint/suspicious/noExplicitAny: flash data stored as unknown; caller brands the value type via T
+      return this.#previousFlash[key] as any as T
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: generic default — caller brands the value type via T
+    return defaultValue as any as T
+  }
+
+  // ─── Serialization ────────────────────────────────────────
+
+  /** Serialize for storage. Includes flash data for next request. */
+  toJSON(): Record<string, unknown> {
+    const result = { ...this.#data }
+    if (Object.keys(this.#flashData).length > 0) {
+      result.__flash = this.#flashData
+    }
+    return result
+  }
+
+  isDirty(): boolean {
+    return this.#dirty
+  }
+}

package/src/session/SessionMiddleware.ts

@@ -0,0 +1,153 @@
+/**
+ * Session middleware — initializes session on each request.
+ *
+ * Reads session ID from cookie, loads data via driver, attaches to ctx,
+ * and writes back after the handler runs.
+ */
+
+import { randomBytes } from 'node:crypto'
+import type { HttpContext } from '../http/HttpContext.js'
+import { CookieDriver } from './drivers/CookieDriver.js'
+import { MemoryDriver } from './drivers/MemoryDriver.js'
+import type { SessionConfig, SessionDriver } from './Session.js'
+import { Session } from './Session.js'
+
+interface ResolvedSessionConfig {
+  driver: string
+  cookieName: string
+  maxAge: number
+  clearWithBrowser: boolean
+  rolling: boolean
+}
+
+export default class SessionMiddleware {
+  #driver: SessionDriver
+  #cookieDriver: CookieDriver | null = null
+  #config: ResolvedSessionConfig
+
+  constructor(config?: SessionConfig & { secret?: string }) {
+    this.#config = {
+      driver: config?.driver ?? 'memory',
+      cookieName: config?.cookieName ?? 'ream_session',
+      maxAge: config?.maxAge ?? 7200,
+      clearWithBrowser: config?.clearWithBrowser ?? false,
+      rolling: config?.rolling ?? false,
+    }
+
+    if (this.#config.driver === 'cookie') {
+      if (!config?.secret) {
+        throw new Error(
+          'Cookie session driver requires a secret. Set session.secret in your config.',
+        )
+      }
+      this.#cookieDriver = new CookieDriver(config.secret)
+      this.#driver = this.#cookieDriver
+    } else if (this.#config.driver === 'memory') {
+      this.#driver = new MemoryDriver()
+    } else {
+      throw new Error(`Unknown session driver: ${this.#config.driver}`)
+    }
+  }
+
+  async handle(ctx: HttpContext, next: () => Promise<void>) {
+    const cookieName = this.#config.cookieName
+    const maxAge = this.#config.maxAge
+    const rolling = this.#config.rolling
+    const isProduction = process.env.NODE_ENV === 'production'
+
+    // Read session ID from cookie — pre-parsed by the Rust HyperServer.
+    let sessionId = ctx.request.cookie(cookieName)
+    const hadIncomingCookie = sessionId !== null
+
+    // Cookie driver: the cookie value IS the session data (encrypted)
+    if (this.#cookieDriver) {
+      const data = await this.#driver.read(sessionId ?? '')
+      sessionId = sessionId ?? generateSessionId()
+      const session = new Session(sessionId, data)
+      ctx.store.set('session', session)
+
+      await next()
+
+      // Default: only emit Set-Cookie if the session was actually modified —
+      // sending a cookie on every response defeats HTTP caching, leaks state
+      // to CDNs, and creates a privacy side-channel (response varies even for
+      // read-only GETs).
+      // Rolling mode: re-emit on every response with an existing session so
+      // the cookie maxAge window slides forward (active users don't time out
+      // mid-session). Caller opts in via SessionConfig.rolling.
+      const shouldEmit = session.isDirty() || (rolling && hadIncomingCookie)
+      if (shouldEmit) {
+        const encoded = this.#cookieDriver.encode(session.toJSON())
+        ctx.response.cookie(cookieName, encoded, {
+          maxAge: this.#config.clearWithBrowser ? undefined : maxAge,
+          path: '/',
+          httpOnly: true,
+          sameSite: 'lax',
+          secure: isProduction,
+        })
+      }
+      return
+    }
+
+    // Server-side drivers (memory, redis)
+    if (!sessionId) {
+      sessionId = generateSessionId()
+    }
+
+    const data = await this.#driver.read(sessionId)
+    const session = new Session(sessionId, data)
+    ctx.store.set('session', session)
+
+    await next()
+
+    // Session-fixation mitigation: if the handler called `session.regenerate()`
+    // (typically via Warden's SessionStrategy.login), the session id has been
+    // rotated. Migrate the driver storage atomically — write under the new
+    // id first, then destroy the old entry so a crash between calls leaves
+    // the user with a valid session under one of the two ids rather than
+    // none. The cookie below picks up `session.sessionId` which already
+    // returns the new value.
+    const regenerated = session.wasRegenerated()
+    const isNew = !hadIncomingCookie
+    if (regenerated) {
+      const originalId = session.originalSessionId()
+      const currentId = session.sessionId
+      await this.#driver.write(currentId, session.toJSON(), maxAge)
+      // Best-effort: a destroy failure leaves a stale entry that TTL will
+      // sweep, but should not crash the request. The new session is already
+      // live under `currentId`.
+      try {
+        await this.#driver.destroy(originalId)
+      } catch {
+        // benign — TTL will reclaim it.
+      }
+    } else if (session.isDirty()) {
+      await this.#driver.write(sessionId, session.toJSON(), maxAge)
+    } else if (!isNew) {
+      await this.#driver.touch(sessionId, maxAge)
+    }
+
+    // Emit Set-Cookie only when there is server-side state worth
+    // pinning to the browser: the session was modified (isDirty → we
+    // just wrote it), regenerated (rotated id post-login), or rolling
+    // mode is sliding an existing session's window. A brand-new but
+    // CLEAN anonymous request gets NO cookie — otherwise every first
+    // read-only GET hands out a persistent tracking id that points at
+    // no server-side row (touch() is a no-op without a backing entry),
+    // defeats HTTP caching, and leaks a Set-Cookie to CDNs. This mirrors
+    // the cookie-driver path above (which already omits `isNew`).
+    if (session.isDirty() || regenerated || (rolling && hadIncomingCookie)) {
+      ctx.response.cookie(cookieName, session.sessionId, {
+        maxAge: this.#config.clearWithBrowser ? undefined : maxAge,
+        path: '/',
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: isProduction,
+      })
+    }
+  }
+}
+
+function generateSessionId(): string {
+  return randomBytes(24).toString('base64url')
+}

package/src/session/drivers/CookieDriver.ts

@@ -0,0 +1,48 @@
+import { CookieSigner } from '../../security/CookieSigner.js'
+import type { SessionDriver } from '../Session.js'
+
+/**
+ * Cookie session driver — stores session data in an encrypted cookie (AES-256-GCM).
+ * Stateless on the server. Limited by cookie size (~4KB).
+ * Requires a secret for encryption.
+ */
+export class CookieDriver implements SessionDriver {
+  private signer: CookieSigner
+
+  constructor(secret: string) {
+    if (!secret) {
+      throw new Error(
+        'CookieDriver requires a secret for session encryption. Set session.secret in your config.',
+      )
+    }
+    this.signer = new CookieSigner(secret)
+  }
+
+  async read(sessionId: string): Promise<Record<string, unknown>> {
+    if (!sessionId) return {}
+    const decrypted = this.signer.decrypt(sessionId)
+    if (!decrypted) return {}
+    try {
+      return JSON.parse(decrypted)
+    } catch {
+      return {}
+    }
+  }
+
+  async write(_sessionId: string, _data: Record<string, unknown>, _ttl: number): Promise<void> {
+    // Cookie driver writes via the response cookie — handled by middleware
+  }
+
+  async destroy(_sessionId: string): Promise<void> {
+    // Cookie deletion handled by middleware setting maxAge=0
+  }
+
+  async touch(_sessionId: string, _ttl: number): Promise<void> {
+    // Cookie renewal handled by middleware
+  }
+
+  /** Encode session data for cookie storage (encrypted). */
+  encode(data: Record<string, unknown>): string {
+    return this.signer.encrypt(JSON.stringify(data))
+  }
+}