@c9up/ream 0.1.7 → 0.1.9

package/src/bodyparser/BodyParserMiddleware.ts

@@ -8,6 +8,7 @@
 
 import type { HttpContext } from '../http/HttpContext.js'
 import { hydrateMultipartPayload } from './MultipartFile.js'
+import { parseSize } from './parseSize.js'
 
 export interface BodyParserConfig {
   json?: {
@@ -27,7 +28,10 @@ export interface BodyParserConfig {
   }
   multipart?: {
     enabled?: boolean
+    /** Total multipart body size cap (sum of all file sizes). Default: '20mb'. */
     limit?: string
+    /** Maximum number of files per request. Default: 20. */
+    maxFiles?: number
     maxFields?: number
     tmpDir?: string
     types?: string[]
@@ -60,6 +64,7 @@ const DEFAULT_CONFIG: ResolvedBodyParserConfig = {
   multipart: {
     enabled: true,
     limit: '20mb',
+    maxFiles: 20,
     maxFields: 500,
     tmpDir: '/tmp',
     types: ['multipart/form-data'],
@@ -113,6 +118,7 @@ export default class BodyParserMiddleware {
     if (this.#config.multipart.enabled && matchesType(contentType, this.#config.multipart.types)) {
       const payload = ctx.request.multipart()
       if (payload) {
+        if (this.#rejectMultipart(ctx, payload.files, payload.fields)) return
         const { fields, files } = hydrateMultipartPayload(payload)
         ctx.request.setParsedBody(fields)
         ctx.request.setFiles(files)
@@ -128,28 +134,49 @@ export default class BodyParserMiddleware {
     if (matchesType(contentType, this.#config.multipart.types)) return this.#config.multipart.limit
     return this.#config.raw.limit
   }
+
+  /** Returns true (and writes a 413/400) when the multipart payload exceeds configured limits. */
+  #rejectMultipart(
+    ctx: HttpContext,
+    files: Array<{ size: number }>,
+    fields: Array<unknown>,
+  ): boolean {
+    const cfg = this.#config.multipart
+    const maxBytes = parseSize(cfg.limit)
+
+    if (fields.length > cfg.maxFields) {
+      ctx.response.status(400).json({
+        error: {
+          code: 'E_TOO_MANY_FIELDS',
+          message: `Upload exceeds maxFields (${cfg.maxFields})`,
+        },
+      })
+      return true
+    }
+
+    if (files.length > cfg.maxFiles) {
+      ctx.response.status(400).json({
+        error: { code: 'E_TOO_MANY_FILES', message: `Upload exceeds maxFiles (${cfg.maxFiles})` },
+      })
+      return true
+    }
+
+    const totalBytes = files.reduce((sum, f) => sum + f.size, 0)
+    if (totalBytes > maxBytes) {
+      ctx.response.status(413).json({
+        error: { code: 'E_REQUEST_ENTITY_TOO_LARGE', message: 'Upload exceeds size limit' },
+      })
+      return true
+    }
+
+    return false
+  }
 }
 
 function matchesType(contentType: string, types: string[]): boolean {
   return types.some((t) => contentType.includes(t))
 }
 
-function parseSize(size: string): number {
-  const match = size.match(/^(\d+)(kb|mb|gb)?$/i)
-  if (!match) return 1024 * 1024 // default 1mb
-  const num = parseInt(match[1], 10)
-  switch (match[2]?.toLowerCase()) {
-    case 'kb':
-      return num * 1024
-    case 'mb':
-      return num * 1024 * 1024
-    case 'gb':
-      return num * 1024 * 1024 * 1024
-    default:
-      return num
-  }
-}
-
 function parseFormUrlEncoded(body: string): Record<string, unknown> {
   const result: Record<string, unknown> = {}
   if (!body) return result

package/src/bodyparser/parseSize.ts

@@ -1,6 +1,7 @@
 /**
  * Parse a human-readable size string (e.g. '1mb', '512kb', '2gb') to bytes.
- * Single source of truth — used by both BodyParserMiddleware and MultipartFile.
+ * Single source of truth, imported by BodyParserMiddleware (which previously
+ * carried an identical inline copy — consolidated 2026-06-15).
  */
 export function parseSize(size: string): number {
   const match = size.match(/^(\d+)(kb|mb|gb)?$/i)

package/src/container/Container.ts

@@ -158,15 +158,12 @@ export class Container {
     const paramTypes: unknown[] =
       Reflect.getMetadata('design:paramtypes', target.prototype, method) ?? []
 
-    const args = paramTypes.map((type, index) => {
-      // Runtime values take precedence
-      if (runtimeValues && index < runtimeValues.length) {
-        return runtimeValues[index]
-      }
-      // Auto-resolve class dependencies — type is a constructor function here
-      if (isClassConstructor(type)) {
-        return this.resolve(type)
-      }
+    const len = Math.max(paramTypes.length, runtimeValues?.length ?? 0)
+    const args = Array.from({ length: len }, (_, index) => {
+      // Runtime values take precedence (and fill slots beyond paramTypes)
+      if (runtimeValues && index < runtimeValues.length) return runtimeValues[index]
+      const type = paramTypes[index]
+      if (isClassConstructor(type)) return this.resolve(type)
       return undefined
     })
 
@@ -281,15 +278,48 @@ export class Container {
     const paramTypes: unknown[] =
       explicitDeps ?? Reflect.getMetadata('design:paramtypes', target) ?? []
 
+    const injectTokens = getInjectTokens(target)
+    const lazyIndices = getLazyParams(target)
+
+    // No `design:paramtypes` (a dev transpiler may not emit decorator metadata —
+    // esbuild / tsx don't). Recover what we can, and NEVER construct with
+    // silently-undefined deps (that masked a whole DI outage in dev):
     if (paramTypes.length === 0) {
+      // (a) `@Inject(token)` records its tokens INDEPENDENTLY of decorator
+      //     metadata, so even without `design:paramtypes` we can resolve the
+      //     constructor from that map alone.
+      if (injectTokens.size > 0) {
+        const maxIndex = Math.max(...injectTokens.keys())
+        const deps = Array.from({ length: maxIndex + 1 }, (_value, index) => {
+          const depToken = injectTokens.get(index)
+          if (!depToken) return undefined
+          if (lazyIndices.includes(index)) {
+            return createLazyProxy(() => this.resolve<object>(depToken))
+          }
+          return this.resolve(depToken)
+        })
+        const instance = new target(...deps)
+        if (scope === 'singleton') this.#singletons.set(key, instance)
+        return instance
+      }
+      // (b) The constructor declares parameters but we have no way to resolve
+      //     them (no metadata, no @Inject, no containerInjections). Fail LOUDLY
+      //     instead of `new target()` with undefined deps.
+      if (target.length > 0) {
+        throw new ReamError(
+          'CONTAINER_MISSING_METADATA',
+          `Cannot auto-construct ${target.name}: it declares ${target.length} constructor parameter(s) but no dependency metadata was found.`,
+          {
+            hint: 'Enable decorator metadata (swc/tsc emitDecoratorMetadata), annotate constructor params with @Inject(token), or declare static containerInjections.',
+          },
+        )
+      }
+      // (c) Genuine zero-argument class.
       const instance = new target()
       if (scope === 'singleton') this.#singletons.set(key, instance)
       return instance
     }
 
-    const injectTokens = getInjectTokens(target)
-    const lazyIndices = getLazyParams(target)
-
     const deps = paramTypes.map((type, index) => {
       const namedToken = injectTokens.get(index)
       // After the typeof check, type is a constructor function and valid as ServiceToken

package/src/decorators/Service.ts

@@ -5,7 +5,7 @@
  */
 
 import 'reflect-metadata'
-import type { ServiceMetadata, ServiceScope } from '../container/types.js'
+import type { ServiceMetadata, ServiceScope, ServiceToken } from '../container/types.js'
 
 const SERVICE_METADATA_KEY = Symbol('ream:service')
 const INJECT_METADATA_KEY = Symbol('ream:inject')
@@ -50,9 +50,9 @@ export function Service(options: { scope?: ServiceScope; as?: string } = {}): Cl
  *
  * @implements FR16
  */
-export function Inject(token: string): ParameterDecorator {
+export function Inject(token: ServiceToken): ParameterDecorator {
   return (target, _propertyKey, parameterIndex) => {
-    const existingTokens: Map<number, string> =
+    const existingTokens: Map<number, ServiceToken> =
       Reflect.getOwnMetadata(INJECT_METADATA_KEY, target) ?? new Map()
     existingTokens.set(parameterIndex, token)
     Reflect.defineMetadata(INJECT_METADATA_KEY, existingTokens, target)
@@ -62,7 +62,7 @@ export function Inject(token: string): ParameterDecorator {
 /**
  * Get named injection tokens for a class constructor.
  */
-export function getInjectTokens(target: AnyConstructor): Map<number, string> {
+export function getInjectTokens(target: AnyConstructor): Map<number, ServiceToken> {
   return Reflect.getOwnMetadata(INJECT_METADATA_KEY, target) ?? new Map()
 }
 
@@ -81,5 +81,3 @@ export function getInjectTokens(target: AnyConstructor): Map<number, string> {
 export function inject(): ClassDecorator {
   return Service({ scope: 'transient' })
 }
-
-export { INJECT_METADATA_KEY, SERVICE_METADATA_KEY }

package/src/events/Emitter.ts

@@ -12,8 +12,12 @@
  * Listeners support @inject() for DI when a container resolver is provided.
  */
 
+import { AsyncLocalStorage } from 'node:async_hooks'
 import type { EventBus } from './native.js'
 
+/** Per-request correlation ID stored in async context so concurrent requests don't corrupt each other. */
+const correlationStorage = new AsyncLocalStorage<string | undefined>()
+
 /**
  * Listener class interface — must have a handle() method.
  */
@@ -56,8 +60,9 @@ export class Emitter {
   /**
    * Listen for a string-based event.
    *   emitter.on('user:registered', (user) => { ... })
+   *   emitter.on<User>('user:registered', (user) => { ... })  // typed payload
    */
-  on(event: string, listener: ListenerFn): void
+  on<T>(event: string, listener: ListenerFn<T>): void
   on(event: EventConstructor | string, listener: Listener): void {
     if (typeof event === 'string') {
       const list = this.stringListeners.get(event) ?? []
@@ -229,38 +234,36 @@ export class Emitter {
 
   // ─── Correlation context ──────────────────────────────────
 
-  /** Current correlation ID for event chain tracing. */
-  private _correlationId?: string
-
-  /** Set the correlation ID for subsequent events (typically from HTTP request context). */
+  /**
+   * Set the correlation ID for subsequent events in the current async context.
+   * Uses AsyncLocalStorage so concurrent requests each have their own trace ID —
+   * a shared mutable field would let concurrent requests corrupt each other.
+   */
   setCorrelationId(id: string): void {
-    this._correlationId = id
+    correlationStorage.enterWith(id)
   }
 
-  /** Get the current correlation ID. */
+  /**
+   * Clear the correlation ID for the current async context. `enterWith` does
+   * not auto-unset, so a long-lived/reused context (and, notably, sequential
+   * tests sharing a worker) would leak the last set id — call this to reset.
+   */
+  clearCorrelationId(): void {
+    correlationStorage.enterWith(undefined)
+  }
+
+  /** Get the correlation ID for the current async context. */
   getCorrelationId(): string | undefined {
-    return this._correlationId
+    return correlationStorage.getStore()
   }
 
-  /**
-   * Inject the active correlation ID at the top level of the payload so
-   * the bus's Event envelope (`{ id, name, data, correlationId, ... }`)
-   * surfaces it on the subscriber side — both the Rust `ream-events`
-   * envelope serde and `FakeBus.parseEmitData()` already read
-   * `correlationId` from the parsed `data` string. Without this injection
-   * `setCorrelationId()` was a no-op functional API. Returns `data`
-   * unchanged when no correlation ID is set OR when `data` is not a plain
-   * object (primitives / arrays / null can't carry a sibling field).
-   */
+  /** Inject the active correlation ID at the top level of the payload. */
   #wrapForBus(data: unknown): unknown {
-    if (this._correlationId === undefined) return data
-    if (data === null || typeof data !== 'object' || Array.isArray(data)) {
-      return data
-    }
-    const obj = data as Record<string, unknown>
-    // User-supplied correlationId wins — don't clobber an explicit value.
-    if (typeof obj.correlationId === 'string') return data
-    return { ...obj, correlationId: this._correlationId }
+    const correlationId = correlationStorage.getStore()
+    if (correlationId === undefined) return data
+    if (!isPlainObject(data)) return data
+    if (typeof data.correlationId === 'string') return data
+    return { ...data, correlationId }
   }
 
   // ─── Introspection ────────────────────────────────────────
@@ -304,8 +307,9 @@ export class BaseEvent {
     BaseEvent._emitter = emitter
   }
 
-  static resetEmitter(): void {
-    BaseEvent._emitter = undefined
+  /** @internal Ownership-guarded reset — only clears if `emitter` is still the active one. */
+  static resetEmitter(emitter: Emitter): void {
+    if (BaseEvent._emitter === emitter) BaseEvent._emitter = undefined
   }
 
   /**
@@ -331,3 +335,7 @@ function classToEventName(cls: EventConstructor): string {
 function isListenerClass(listener: Listener): boolean {
   return typeof listener === 'function' && typeof listener.prototype?.handle === 'function'
 }
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}

package/src/events/EventsProvider.ts

@@ -23,6 +23,8 @@ export interface EventsAppContext {
 }
 
 export default class EventsProvider {
+  #emitter: Emitter | undefined
+
   constructor(protected app: EventsAppContext) {}
 
   register() {
@@ -47,12 +49,12 @@ export default class EventsProvider {
   }
 
   async boot() {
-    const emitter = this.app.container.resolve<Emitter>(Emitter)
-    BaseEvent.useEmitter(emitter)
-    setEmitter(emitter)
+    this.#emitter = this.app.container.resolve<Emitter>(Emitter)
+    BaseEvent.useEmitter(this.#emitter)
+    setEmitter(this.#emitter)
   }
 
   async shutdown() {
-    BaseEvent.resetEmitter()
+    if (this.#emitter) BaseEvent.resetEmitter(this.#emitter)
   }
 }

package/src/graphql/GraphQLEngine.ts

@@ -40,6 +40,43 @@ interface RustParseResult {
 }
 interface GraphqlNative {
   graphqlParse(query: string): string
+  /** `{ "Type.field": { "argName": "ScalarType" } }` extracted from the SDL. */
+  graphqlSchemaArgTypes(sdl: string): string
+}
+
+/**
+ * Coerce an argument value to its schema-declared scalar type. GraphQL input
+ * coercion: a string literal `"5"` for an `Int` arg becomes the number `5`, a
+ * number for an `ID` becomes its string form, etc. Arrays coerce element-wise.
+ * Unknown / custom / enum types pass through untouched.
+ */
+function coerceScalar(value: unknown, type: string): unknown {
+  if (value === null || value === undefined) return value
+  if (Array.isArray(value)) return value.map((v) => coerceScalar(v, type))
+  switch (type) {
+    case 'Int':
+      if (typeof value === 'number') return value
+      if (typeof value === 'string' && value.trim() !== '' && Number.isInteger(Number(value))) {
+        return Number(value)
+      }
+      return value
+    case 'Float':
+      if (typeof value === 'number') return value
+      if (typeof value === 'string' && value.trim() !== '' && !Number.isNaN(Number(value))) {
+        return Number(value)
+      }
+      return value
+    case 'Boolean':
+      if (typeof value === 'boolean') return value
+      if (value === 'true') return true
+      if (value === 'false') return false
+      return value
+    case 'ID':
+      return typeof value === 'number' ? String(value) : value
+    default:
+      // String, custom scalars, enums, input objects — left as the client sent.
+      return value
+  }
 }
 
 let graphqlNativeCache: GraphqlNative | undefined
@@ -65,6 +102,39 @@ const OPERATION_TYPE: Record<string, string> = {
   subscription: 'Subscription',
 }
 
+/**
+ * Bound a parsed selection tree's depth and total field count. Iterative (explicit
+ * stack) so a pathological deeply-nested query can't overflow the JS call stack
+ * during the check itself, and short-circuits as soon as a limit is crossed.
+ * Returns an error message, or `null` when the query is within limits.
+ */
+function checkSelectionLimits(
+  fields: SelectionField[],
+  maxDepth: number,
+  maxComplexity: number,
+): string | null {
+  let count = 0
+  const stack: Array<{ field: SelectionField; depth: number }> = fields.map((field) => ({
+    field,
+    depth: 1,
+  }))
+  while (stack.length > 0) {
+    const top = stack.pop()
+    if (!top) break
+    if (top.depth > maxDepth) {
+      return `Query is too deep (max depth ${maxDepth})`
+    }
+    count += 1
+    if (count > maxComplexity) {
+      return `Query is too complex (max ${maxComplexity} fields)`
+    }
+    for (const child of top.field.selection) {
+      stack.push({ field: child, depth: top.depth + 1 })
+    }
+  }
+  return null
+}
+
 /** Map a Rust `ParsedField` (sub_fields) onto the engine's `SelectionField` (selection). */
 function mapRustField(f: RustParsedField): SelectionField {
   return {
@@ -82,6 +152,22 @@ export interface GraphQLConfig {
   path?: string
   /** Enable playground/introspection in dev (default: true when NODE_ENV !== 'production'). */
   playground?: boolean
+  /**
+   * Reject a query string longer than this many characters BEFORE parsing —
+   * caps the work the parser does on a hostile payload (default: 100_000).
+   */
+  maxQueryBytes?: number
+  /**
+   * Reject a query whose selection set nests deeper than this — bounds
+   * resolver recursion / amplification (default: 12).
+   */
+  maxDepth?: number
+  /**
+   * Reject a query selecting more than this many fields in total (aliases
+   * count) — bounds fan-out where a client repeats an expensive resolver
+   * (default: 1000).
+   */
+  maxComplexity?: number
 }
 
 export interface ResolverOptions {
@@ -120,6 +206,24 @@ export class GraphQLEngine {
   #container?: { make<T>(target: new (...args: unknown[]) => T): T }
   readonly path: string
   #playground: boolean
+  #maxQueryBytes: number
+  #maxDepth: number
+  #maxComplexity: number
+  /** Lazily-parsed `Type.field → argName → scalarType` map for input coercion. */
+  #argTypes?: Record<string, Record<string, string>>
+
+  /** Parse (once) the schema's argument types from the SDL for coercion. */
+  #schemaArgTypes(): Record<string, Record<string, string>> {
+    if (this.#argTypes === undefined) {
+      try {
+        this.#argTypes = JSON.parse(graphqlNative().graphqlSchemaArgTypes(this.#schemaSource))
+      } catch {
+        // Native unavailable or schema unparseable → coercion becomes a no-op.
+        this.#argTypes = {}
+      }
+    }
+    return this.#argTypes ?? {}
+  }
 
   constructor(config: GraphQLConfig) {
     if (!fs.existsSync(config.schemaPath)) {
@@ -128,6 +232,9 @@ export class GraphQLEngine {
     this.#schemaSource = fs.readFileSync(config.schemaPath, 'utf8')
     this.path = config.path ?? '/graphql'
     this.#playground = config.playground ?? process.env.NODE_ENV !== 'production'
+    this.#maxQueryBytes = config.maxQueryBytes ?? 100_000
+    this.#maxDepth = config.maxDepth ?? 12
+    this.#maxComplexity = config.maxComplexity ?? 1000
   }
 
   /** Set IoC container for resolver instantiation. */
@@ -196,12 +303,28 @@ export class GraphQLEngine {
     data?: Record<string, unknown>
     errors?: Array<{ message: string; path?: string[] }>
   }> {
+    // DoS guard 1 — cap the raw query size BEFORE handing it to the parser, so a
+    // hostile multi-MB payload can't tie up the native parser.
+    if (request.query.length > this.#maxQueryBytes) {
+      return {
+        errors: [{ message: `Query exceeds the maximum size of ${this.#maxQueryBytes} bytes` }],
+      }
+    }
+
     // Parse the query to extract operation type and fields
     const parsed = this.#parseQuery(request.query)
     if (parsed.errors) {
       return { errors: parsed.errors }
     }
 
+    // DoS guard 2 — bound the selection tree's depth and total field count
+    // (aliases included) before resolving anything. Iterative walk so the check
+    // itself can't blow the stack on a deeply nested query.
+    const limitError = checkSelectionLimits(parsed.fields, this.#maxDepth, this.#maxComplexity)
+    if (limitError) {
+      return { errors: [{ message: limitError }] }
+    }
+
     const data: Record<string, unknown> = {}
     const errors: Array<{ message: string; path?: string[] }> = []
 
@@ -260,7 +383,7 @@ export class GraphQLEngine {
         }
       }
 
-      const args = this.#buildArgs(field, request.variables)
+      const args = this.#buildArgs(field, request.variables, typeName)
       const result = await handler.call(instance, null, args, ctx)
       // Prune to the client's selection set: a resolver returning a rich
       // object (ORM entity, etc.) must not leak fields the client did not
@@ -279,6 +402,7 @@ export class GraphQLEngine {
   #buildArgs(
     field: SelectionField,
     variables: Record<string, unknown> | undefined,
+    typeName: string,
   ): Record<string, unknown> {
     const args: Record<string, unknown> = {}
     for (const [k, v] of Object.entries(field.args)) {
@@ -293,6 +417,15 @@ export class GraphQLEngine {
         if (!(k in args)) args[k] = v
       }
     }
+    // Coerce each argument to its schema-declared scalar type (Int/Float/Boolean/
+    // ID). A literal `task(id: "5")` or a string variable thus reaches the
+    // resolver as the right runtime type instead of being silently mistyped.
+    const argTypes = this.#schemaArgTypes()[`${typeName}.${field.name}`]
+    if (argTypes) {
+      for (const [k, declaredType] of Object.entries(argTypes)) {
+        if (k in args) args[k] = coerceScalar(args[k], declaredType)
+      }
+    }
     return args
   }
 
@@ -307,15 +440,18 @@ export class GraphQLEngine {
       return 'Unauthorized'
     }
 
+    // Read roles/permissions from the top level OR nested under `user` — the
+    // auth provider (e.g. warden) sets `ctx.auth.user.roles`, not the top level.
+    // Mirrors the HTTP guard middleware fix.
     if (roles.length > 0) {
-      const userRoles = ctx.auth?.roles ?? []
+      const userRoles = ctx.auth?.roles ?? ctx.auth?.user?.roles ?? []
       if (!roles.some((r) => userRoles.includes(r))) {
         return 'Insufficient role'
       }
     }
 
     if (permissions.length > 0) {
-      const userPerms = ctx.auth?.permissions ?? []
+      const userPerms = ctx.auth?.permissions ?? ctx.auth?.user?.permissions ?? []
       if (!permissions.every((p) => userPerms.includes(p))) {
         return 'Insufficient permissions'
       }

package/src/graphql/GraphQLProvider.ts

@@ -15,6 +15,7 @@
  * @implements Story 24.5
  */
 
+import { ReamError } from '../errors/ReamError.js'
 import type { AppContext } from '../Provider.js'
 import { Provider } from '../Provider.js'
 import type { Router } from '../router/Router.js'
@@ -42,9 +43,23 @@ export class GraphQLProvider extends Provider {
     const config = this.app.config.get<GraphQLConfig>('graphql')
     const engine = this.#engine ?? (config?.schemaPath ? new GraphQLEngine(config) : undefined)
     if (!engine) return // GraphQL not configured — opt-out.
-    engine.useContainer(this.app.container)
+    const container = this.app.container
+    if (container.has('graphql')) {
+      if (container.resolve('graphql') === engine) {
+        this.#engine = engine
+        return // re-register is idempotent
+      }
+      throw new ReamError(
+        'GRAPHQL_PROVIDER_ALREADY_REGISTERED',
+        "Container token 'graphql' is already bound to a different instance",
+        {
+          hint: 'Only one GraphQLProvider can own the graphql binding. Remove the duplicate provider from your reamrc.ts.',
+        },
+      )
+    }
+    engine.useContainer(container)
     this.#engine = engine
-    this.app.container.singleton('graphql', () => engine)
+    container.singleton('graphql', () => engine)
   }
 
   override async boot(): Promise<void> {

package/src/http/HttpContext.ts

@@ -27,6 +27,23 @@ export interface AuthState {
   permissions?: string[]
 }
 
+/**
+ * Per-request authorization entry point — populated by an authorization
+ * middleware (e.g. `@c9up/warden`'s Bouncer initializer). A structural
+ * contract only: Ream stays agnostic of any concrete authorization package,
+ * exactly as `auth` is a slot that Warden fills. A handler authorizes via
+ * `await ctx.bouncer?.authorize('post.edit', post)` (throws on denial, mapped
+ * to 403 by the ExceptionHandler) or branches on `ctx.bouncer?.allows(...)`.
+ */
+export interface Authorizer {
+  /** True iff the action is authorized. Never throws on denial. */
+  allows(ability: string, ...args: unknown[]): Promise<boolean>
+  /** Boolean negation of {@link allows}. Never throws on denial. */
+  denies(ability: string, ...args: unknown[]): Promise<boolean>
+  /** Resolves on allow; throws an authorization failure (status 403) on deny. */
+  authorize(ability: string, ...args: unknown[]): Promise<void>
+}
+
 export interface RouteInfo {
   pattern: string
   name?: string
@@ -62,7 +79,11 @@ export class HttpContext {
   /** Authentication state — populated by auth middleware. */
   auth: AuthState = { authenticated: false }
 
-  /** Detected locale. */
+  /**
+   * Request locale — the primary subtag of the first `Accept-Language` entry
+   * (e.g. `fr-CH,fr;q=0.9` → `fr`), defaulting to `en`. Middleware (or i18n)
+   * may override it; it's a plain mutable field.
+   */
   locale = 'en'
 
   /** Per-request key-value store (for middleware to pass data downstream). */
@@ -75,6 +96,13 @@ export class HttpContext {
    */
   events?: Emitter
 
+  /**
+   * Per-request authorization entry point, when an authorization middleware
+   * is wired (e.g. `@c9up/warden`'s Bouncer initializer). Undefined when no
+   * such middleware ran. See {@link Authorizer}.
+   */
+  bouncer?: Authorizer
+
   /** Route URL resolver for redirect().toRoute(). */
   #routeUrlResolver?: RouteUrlResolver
 
@@ -89,6 +117,7 @@ export class HttpContext {
     this.route = route
     this.request = new Request(rawRequest, params)
     this.response = new Response()
+    this.locale = parseAcceptLanguage(this.request.header('accept-language')) ?? 'en'
 
     // Wire redirect builder with request context
     this.response.setRedirectFactory(
@@ -106,3 +135,11 @@ export class HttpContext {
     this.#routeUrlResolver = resolver
   }
 }
+
+/** Primary subtag of the first Accept-Language entry: `fr-CH,fr;q=0.9` → `fr`. */
+function parseAcceptLanguage(header: string | undefined): string | undefined {
+  if (!header) return undefined
+  const first = header.split(',')[0]?.trim().split(';')[0]?.trim()
+  const primary = first?.split('-')[0]?.toLowerCase()
+  return primary || undefined
+}