ingenium 0.0.1

package/src/session/middleware.ts

@@ -0,0 +1,379 @@
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+import { Buffer } from 'node:buffer'
+import type { IngeniumMiddleware } from '../middleware/types.ts'
+import type { IngeniumContext } from '../context/context.ts'
+import { MemoryStore } from './store-memory.ts'
+import type { Session, SessionCookieOptions, SessionOptions, SessionStore } from './types.ts'
+
+// ───── Constants ────────────────────────────────────────────────────────────
+
+const DEFAULT_COOKIE_NAME = 'ingenium.sid'
+const DEFAULT_MAX_AGE_SECONDS = 60 * 60 * 24 * 7 // 7 days
+/** ID byte length — 18 bytes → 24 base64url chars, ~144 bits of entropy. */
+const ID_BYTES = 18
+
+// ───── Cookie helpers ───────────────────────────────────────────────────────
+// TODO: migrate to ctx.cookies — kept inline for now because session has
+// specific behaviours (rolling, secret-rotation re-signing, destroy-on-commit)
+// that don't map 1:1 onto the generic cookie API.
+
+/**
+ * Parse a `Cookie` request header into a name→value map. Handles:
+ * - Multiple cookies separated by `;` (with optional whitespace)
+ * - Quoted values: `name="quoted value"`
+ * - Percent-encoded characters via `decodeURIComponent`
+ * - Duplicate names: first occurrence wins (matches RFC 6265 §5.4 typical behaviour)
+ *
+ * Malformed pairs are skipped silently — this is a defensive parser that
+ * never throws on user input.
+ */
+export function parseCookieHeader(header: string | undefined): Record<string, string> {
+  const out: Record<string, string> = Object.create(null) as Record<string, string>
+  if (!header) return out
+
+  const parts = header.split(';')
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i]!
+    const eq = part.indexOf('=')
+    if (eq < 0) continue
+    const name = part.slice(0, eq).trim()
+    if (!name || name in out) continue
+    let value = part.slice(eq + 1).trim()
+    // Strip surrounding double quotes.
+    if (value.length >= 2 && value.charCodeAt(0) === 0x22 && value.charCodeAt(value.length - 1) === 0x22) {
+      value = value.slice(1, -1)
+    }
+    try {
+      out[name] = decodeURIComponent(value)
+    } catch {
+      // Bad percent-encoding — keep raw value rather than throwing.
+      out[name] = value
+    }
+  }
+  return out
+}
+
+/**
+ * Serialize a single `Set-Cookie` value. We implement this inline to avoid
+ * pulling in `cookie` as a dependency.
+ *
+ * `maxAge` is in seconds; when supplied we also emit an absolute `Expires`
+ * for older clients that ignore `Max-Age`.
+ */
+export function serializeCookie(
+  name: string,
+  value: string,
+  opts: SessionCookieOptions & { maxAge?: number } = {},
+): string {
+  // Encode the value so semicolons / whitespace cannot break the header.
+  const segments: string[] = [`${name}=${encodeURIComponent(value)}`]
+  if (opts.domain) segments.push(`Domain=${opts.domain}`)
+  segments.push(`Path=${opts.path ?? '/'}`)
+
+  if (typeof opts.maxAge === 'number') {
+    // Floor — Max-Age must be an integer.
+    const ma = Math.floor(opts.maxAge)
+    segments.push(`Max-Age=${ma}`)
+    const expires = new Date(Date.now() + ma * 1000)
+    segments.push(`Expires=${expires.toUTCString()}`)
+  }
+
+  if (opts.httpOnly !== false) segments.push('HttpOnly')
+  if (opts.secure) segments.push('Secure')
+  const sameSite = opts.sameSite ?? 'lax'
+  segments.push(`SameSite=${sameSite[0]!.toUpperCase()}${sameSite.slice(1)}`)
+
+  return segments.join('; ')
+}
+
+/**
+ * Append a `Set-Cookie` value to the response, preserving any existing
+ * `Set-Cookie` header(s) from earlier middleware.
+ */
+function appendSetCookie(ctx: IngeniumContext, value: string): void {
+  const existing = ctx.getHeader('set-cookie')
+  if (!existing) {
+    ctx.set('set-cookie', value)
+  } else if (Array.isArray(existing)) {
+    ctx.set('set-cookie', [...existing, value])
+  } else {
+    ctx.set('set-cookie', [existing, value])
+  }
+}
+
+// ───── Signing ──────────────────────────────────────────────────────────────
+
+/** HMAC-SHA-256 the id with `secret`, base64url-encoded. */
+function signId(id: string, secret: string): string {
+  return createHmac('sha256', secret).update(id).digest('base64url')
+}
+
+/**
+ * Verify `cookieValue` (`<id>.<sig>`) against any of the supplied secrets.
+ * Returns the id and the index of the matching secret, or `null`.
+ *
+ * Uses {@link timingSafeEqual} to defeat byte-wise timing oracles.
+ */
+function verifySigned(
+  cookieValue: string,
+  secrets: readonly string[],
+): { id: string; secretIndex: number } | null {
+  const dot = cookieValue.lastIndexOf('.')
+  if (dot <= 0 || dot >= cookieValue.length - 1) return null
+  const id = cookieValue.slice(0, dot)
+  const sig = cookieValue.slice(dot + 1)
+  const sigBuf = Buffer.from(sig, 'base64url')
+  if (sigBuf.length === 0) return null
+
+  for (let i = 0; i < secrets.length; i++) {
+    const expected = Buffer.from(signId(id, secrets[i]!), 'base64url')
+    if (expected.length !== sigBuf.length) continue
+    if (timingSafeEqual(expected, sigBuf)) return { id, secretIndex: i }
+  }
+  return null
+}
+
+/** Generate a fresh, opaque session id. */
+function newId(): string {
+  return randomBytes(ID_BYTES).toString('base64url')
+}
+
+// ───── Session implementation ───────────────────────────────────────────────
+
+/**
+ * @internal Mutable-by-design implementation of {@link Session}. The public
+ * `data` field is exposed via `Object.freeze` to keep callers from mutating
+ * around the dirty-tracking surface.
+ */
+class SessionImpl implements Session {
+  /** Tracks whether the session needs to be persisted on response. */
+  dirty: boolean
+  /** True when no record existed in the store at request start. */
+  readonly isNew: boolean
+  /** True after `destroy()` — middleware will clear cookie + store. */
+  destroyed = false
+
+  private _id: string
+  private _data: Record<string, unknown>
+
+  constructor(
+    id: string,
+    data: Record<string, unknown>,
+    isNew: boolean,
+    private readonly store: SessionStore,
+    /** Set to `true` when secret rotation requires re-signing on response. */
+    public needsResign: boolean,
+  ) {
+    this._id = id
+    this._data = data
+    this.isNew = isNew
+    // A brand-new session with no data is NOT dirty — we don't want to
+    // create empty rows or cookies for every anonymous request.
+    this.dirty = false
+  }
+
+  get id(): string {
+    return this._id
+  }
+
+  get data(): Readonly<Record<string, unknown>> {
+    return Object.freeze({ ...this._data })
+  }
+
+  get<T = unknown>(key: string): T | undefined {
+    return this._data[key] as T | undefined
+  }
+
+  set(key: string, value: unknown): void {
+    this._data[key] = value
+    this.dirty = true
+  }
+
+  delete(key: string): void {
+    if (key in this._data) {
+      delete this._data[key]
+      this.dirty = true
+    }
+  }
+
+  async destroy(): Promise<void> {
+    await this.store.destroy(this._id)
+    this._data = Object.create(null) as Record<string, unknown>
+    this.destroyed = true
+    this.dirty = false
+  }
+
+  async regenerate(): Promise<void> {
+    const oldId = this._id
+    this._id = newId()
+    // Old id must die so a stolen cookie cannot resurrect the session.
+    await this.store.destroy(oldId)
+    this.dirty = true
+    this.needsResign = true
+  }
+
+  /** @internal Snapshot for persistence; cheap shallow clone. */
+  snapshot(): Record<string, unknown> {
+    return { ...this._data }
+  }
+}
+
+// ───── Middleware factory ───────────────────────────────────────────────────
+
+/**
+ * Cookie-backed session middleware.
+ *
+ * The middleware attaches a {@link Session} instance at `ctx.session`. To
+ * make this typesafe in user code, augment the `IngeniumContext` interface in
+ * your own project:
+ *
+ * @example
+ * ```ts
+ * declare module 'ingenium' {
+ *   interface IngeniumContext { session: import('ingenium').Session }
+ * }
+ *
+ * import { ingenium, sessionMiddleware } from 'ingenium'
+ * const app = ingenium()
+ * app.use(sessionMiddleware({ secret: process.env.SESSION_SECRET! }))
+ *
+ * app.get('/me', (ctx) => ({ user: ctx.session.get('user') }))
+ * app.post('/login', async (ctx) => {
+ *   ctx.session.set('user', { id: 1 })
+ *   await ctx.session.regenerate() // mitigate session fixation
+ * })
+ * ```
+ *
+ * Security choices:
+ * - HMAC-SHA-256 over the session id, base64url-encoded; verified with
+ *   `timingSafeEqual`.
+ * - 144-bit (18-byte) random ids.
+ * - Defaults: `HttpOnly`, `SameSite=Lax`, `Path=/`. Set `secure: true`
+ *   behind TLS to enable `Secure`.
+ * - Tampered or unknown cookies silently issue a fresh session — never an
+ *   error response, since this is an attacker-influenced surface.
+ */
+export function sessionMiddleware(opts: SessionOptions): IngeniumMiddleware {
+  // ── Construction-time validation ─────────────────────────────────────────
+  const secrets: readonly string[] = Array.isArray(opts.secret)
+    ? opts.secret.slice()
+    : [opts.secret]
+  if (secrets.length === 0 || secrets.some((s) => typeof s !== 'string' || s.length === 0)) {
+    throw new Error('sessionMiddleware: `secret` must be a non-empty string or non-empty string[]')
+  }
+
+  const cookieName = opts.cookieName ?? DEFAULT_COOKIE_NAME
+  const maxAgeSeconds = opts.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS
+  const rolling = opts.rolling ?? false
+  const cookieOpts: SessionCookieOptions = opts.cookie ?? {}
+  const store: SessionStore = opts.store ?? new MemoryStore()
+
+  return async (ctx, next) => {
+    const cookies = parseCookieHeader(ctx.headers.cookie as string | undefined)
+    const raw = cookies[cookieName]
+
+    let id: string
+    let data: Record<string, unknown>
+    let isNew: boolean
+    let needsResign = false
+
+    if (raw) {
+      const verified = verifySigned(raw, secrets)
+      if (verified) {
+        const loaded = await store.get(verified.id)
+        if (loaded) {
+          id = verified.id
+          data = { ...loaded }
+          isNew = false
+          // If verified by anything other than the active key, re-sign.
+          if (verified.secretIndex !== 0) needsResign = true
+        } else {
+          // Cookie validly signed but store has nothing — treat as new.
+          id = newId()
+          data = Object.create(null) as Record<string, unknown>
+          isNew = true
+        }
+      } else {
+        // Bad signature → silently issue a new session.
+        id = newId()
+        data = Object.create(null) as Record<string, unknown>
+        isNew = true
+      }
+    } else {
+      id = newId()
+      data = Object.create(null) as Record<string, unknown>
+      isNew = true
+    }
+
+    const session = new SessionImpl(id, data, isNew, store, needsResign)
+    // Decorator-by-assignment. Type augmentation (see JSDoc above) keeps
+    // this typesafe in user code without polluting the shared prototype.
+    ;(ctx as unknown as { session: Session }).session = session
+
+    try {
+      await next()
+    } finally {
+      await commit(ctx, session, secrets[0]!, cookieName, maxAgeSeconds, rolling, cookieOpts, store)
+    }
+  }
+}
+
+/**
+ * Persist session changes and write the appropriate `Set-Cookie` header.
+ * Runs in `finally` so we still clean up after handler errors.
+ */
+async function commit(
+  ctx: IngeniumContext,
+  session: SessionImpl,
+  signingSecret: string,
+  cookieName: string,
+  maxAgeSeconds: number,
+  rolling: boolean,
+  cookieOpts: SessionCookieOptions,
+  store: SessionStore,
+): Promise<void> {
+  if (session.destroyed) {
+    // Clear cookie. Max-Age=0 is the cross-browser way to expire immediately.
+    appendSetCookie(
+      ctx,
+      serializeCookie(cookieName, '', { ...cookieOpts, maxAge: 0 }),
+    )
+    return
+  }
+
+  // Spec: persist + cookie when session is dirty OR new. Persisting empty
+  // new sessions is intentional — it lets handlers rely on a stable id
+  // across requests for anon flows (CSRF tokens, A/B buckets, etc.).
+  const shouldPersist = session.dirty || session.isNew
+
+  if (shouldPersist) {
+    await store.set(session.id, session.snapshot(), maxAgeSeconds)
+    const signed = `${session.id}.${signId(session.id, signingSecret)}`
+    appendSetCookie(
+      ctx,
+      serializeCookie(cookieName, signed, { ...cookieOpts, maxAge: maxAgeSeconds }),
+    )
+    return
+  }
+
+  // Re-sign without re-persisting (e.g. secret rotation on a clean read).
+  if (session.needsResign && !session.isNew) {
+    const signed = `${session.id}.${signId(session.id, signingSecret)}`
+    appendSetCookie(
+      ctx,
+      serializeCookie(cookieName, signed, { ...cookieOpts, maxAge: maxAgeSeconds }),
+    )
+    if (rolling && store.touch) await store.touch(session.id, maxAgeSeconds)
+    return
+  }
+
+  // Rolling: refresh TTL + cookie even when nothing changed.
+  if (rolling && !session.isNew) {
+    if (store.touch) await store.touch(session.id, maxAgeSeconds)
+    const signed = `${session.id}.${signId(session.id, signingSecret)}`
+    appendSetCookie(
+      ctx,
+      serializeCookie(cookieName, signed, { ...cookieOpts, maxAge: maxAgeSeconds }),
+    )
+  }
+}

package/src/session/store-memory.ts

@@ -0,0 +1,79 @@
+import type { SessionStore } from './types.ts'
+
+interface Entry {
+  data: Record<string, unknown>
+  expiresAt: number
+}
+
+/**
+ * In-process session store backed by a `Map`. Suitable for development and
+ * single-instance deployments. NOT shared across workers/replicas.
+ *
+ * Expired entries are evicted lazily on access AND periodically by a
+ * background sweep. The sweep timer is `unref()`'d so it never keeps the
+ * Node process alive on its own.
+ */
+export class MemoryStore implements SessionStore {
+  private readonly map = new Map<string, Entry>()
+  private readonly sweep: NodeJS.Timeout | null
+
+  /**
+   * @param sweepIntervalMs How often to scan the map for expired entries.
+   * Defaults to 60s. Pass `0` to disable the timer entirely (tests).
+   */
+  constructor(sweepIntervalMs = 60_000) {
+    if (sweepIntervalMs > 0) {
+      this.sweep = setInterval(() => this.purge(), sweepIntervalMs)
+      // Don't keep the event loop alive just for the sweep.
+      this.sweep.unref?.()
+    } else {
+      this.sweep = null
+    }
+  }
+
+  async get(id: string): Promise<Record<string, unknown> | null> {
+    const entry = this.map.get(id)
+    if (!entry) return null
+    if (entry.expiresAt <= Date.now()) {
+      this.map.delete(id)
+      return null
+    }
+    return entry.data
+  }
+
+  async set(id: string, data: Record<string, unknown>, ttlSeconds: number): Promise<void> {
+    this.map.set(id, { data, expiresAt: Date.now() + ttlSeconds * 1000 })
+  }
+
+  async destroy(id: string): Promise<void> {
+    this.map.delete(id)
+  }
+
+  async touch(id: string, ttlSeconds: number): Promise<void> {
+    const entry = this.map.get(id)
+    if (!entry) return
+    entry.expiresAt = Date.now() + ttlSeconds * 1000
+  }
+
+  /**
+   * Stop the background sweep timer. Useful in tests / graceful shutdown.
+   * After this call the store still works but expired entries are only
+   * evicted on access.
+   */
+  stop(): void {
+    if (this.sweep) clearInterval(this.sweep)
+  }
+
+  /** @internal Test helper: number of live (non-expired) entries. */
+  size(): number {
+    this.purge()
+    return this.map.size
+  }
+
+  private purge(): void {
+    const now = Date.now()
+    for (const [id, entry] of this.map) {
+      if (entry.expiresAt <= now) this.map.delete(id)
+    }
+  }
+}

package/src/session/types.ts

@@ -0,0 +1,95 @@
+/**
+ * Session middleware types.
+ *
+ * @see ./middleware.ts for the {@link sessionMiddleware} factory and the
+ * module-augmentation pattern users opt into for typed `ctx.session`.
+ */
+
+/** Cookie attribute overrides. */
+export interface SessionCookieOptions {
+  /** Cookie `Domain` attribute. Omitted when undefined. */
+  domain?: string
+  /** Cookie `Path` attribute. @default '/' */
+  path?: string
+  /** Cookie `HttpOnly` attribute. @default true */
+  httpOnly?: boolean
+  /** Cookie `SameSite` attribute. @default 'lax' */
+  sameSite?: 'lax' | 'strict' | 'none'
+  /** Cookie `Secure` attribute. @default false */
+  secure?: boolean
+}
+
+/** Options accepted by {@link sessionMiddleware}. */
+export interface SessionOptions {
+  /**
+   * HMAC secret(s) for signing the session-id cookie.
+   *
+   * - Single string: used for both signing and verification.
+   * - Array: index `0` is the active signing key; ALL entries are accepted
+   *   for verification, enabling key rotation. Cookies signed with an older
+   *   key are re-signed with the active key on the next response.
+   */
+  secret: string | string[]
+  /** Name of the session cookie. @default 'ingenium.sid' */
+  cookieName?: string
+  /** Cookie / store TTL in seconds. @default 604800 (7 days) */
+  maxAgeSeconds?: number
+  /**
+   * If true, the cookie expiry and store TTL are refreshed on every request,
+   * even when the session data did not change. @default false
+   */
+  rolling?: boolean
+  /** Cookie attribute overrides. */
+  cookie?: SessionCookieOptions
+  /**
+   * Backing store. Defaults to an in-process {@link MemoryStore} which is
+   * NOT suitable for clustered deployments — supply your own for Redis,
+   * Postgres, etc.
+   */
+  store?: SessionStore
+}
+
+/**
+ * Per-request session handle attached as `ctx.session`.
+ *
+ * Mutations (`set`, `delete`, `destroy`, `regenerate`) mark the session as
+ * dirty so the middleware persists changes after the handler returns.
+ */
+export interface Session {
+  /** Stable, opaque session id (rotated by {@link Session.regenerate}). */
+  readonly id: string
+  /** Frozen view of the session data. */
+  readonly data: Readonly<Record<string, unknown>>
+  /** Read a value from the session. */
+  get<T = unknown>(key: string): T | undefined
+  /** Write a value into the session. Marks the session dirty. */
+  set(key: string, value: unknown): void
+  /** Remove a key from the session. Marks the session dirty. */
+  delete(key: string): void
+  /** Drop the session: remove from store + clear the cookie. */
+  destroy(): Promise<void>
+  /**
+   * Issue a new session id while preserving the current data. The old id is
+   * removed from the store. Use after privilege changes (e.g. login) to
+   * mitigate session-fixation attacks.
+   */
+  regenerate(): Promise<void>
+}
+
+/**
+ * Pluggable session storage. Implementations must be safe to call
+ * concurrently for distinct ids; per-id ordering is the caller's concern.
+ */
+export interface SessionStore {
+  /** Look up a session by id. Returns `null` for unknown / expired ids. */
+  get(id: string): Promise<Record<string, unknown> | null>
+  /** Persist `data` under `id` with the given TTL (seconds). */
+  set(id: string, data: Record<string, unknown>, ttlSeconds: number): Promise<void>
+  /** Remove a session entirely. No-op if it does not exist. */
+  destroy(id: string): Promise<void>
+  /**
+   * OPTIONAL: extend an existing session's TTL without rewriting its data.
+   * Used by `rolling` sessions on requests that did not mutate state.
+   */
+  touch?(id: string, ttlSeconds: number): Promise<void>
+}

package/src/sinatra/filters.ts

@@ -0,0 +1,129 @@
+/**
+ * Sinatra-style `before` / `after` filters.
+ *
+ * `before(pattern?, handler)` runs BEFORE the route handler. Equivalent to
+ *   app.use(prefix, mw)  // when pattern is given
+ *   app.use(mw)          // when pattern is omitted
+ * The user writes only the body of the filter — the wrapper invokes
+ * `await next()` automatically. If the filter calls a response writer
+ * (`ctx.json`, `ctx.text`, ...) the chain short-circuits because `next()`
+ * is never called, so the route handler does not run.
+ *
+ * `after(pattern?, handler)` runs AFTER the route handler resolves but
+ * BEFORE the adapter writes to the wire. The wrapper calls `await next()`
+ * first and then runs the user filter, so the filter can observe the final
+ * response state on `ctx`.
+ *
+ * Pattern semantics in v0.0.1:
+ *   - Simple boundary-respecting prefix match (reuses the same
+ *     `pathStartsWith` rule the app uses for scoped middleware).
+ *   - `'/admin/*'` and `'/admin'` both match `/admin` and `/admin/users`
+ *     but neither matches `/administrator`. The trailing `/*` is sugar
+ *     and is stripped before matching.
+ *   - Regex patterns and trailing-slash flexibility are out of scope.
+ */
+
+import type { IngeniumMiddleware } from '../middleware/types.ts'
+import type { IngeniumApp } from '../app.ts'
+
+/**
+ * Strip the Sinatra-style trailing `/*` (or bare `*`) from a prefix so that
+ * `/admin/*` and `/admin` both reduce to `/admin` for prefix matching.
+ * A bare `*` (or `/*`) means "every path" → empty prefix.
+ */
+function normalizeFilterPattern(pattern: string): string {
+  if (pattern === '*' || pattern === '/*' || pattern === '/') return ''
+  if (pattern.endsWith('/*')) return pattern.slice(0, -2)
+  if (pattern.endsWith('*')) return pattern.slice(0, -1)
+  return pattern
+}
+
+/**
+ * Wrap a user `before` filter so it auto-calls `next()` after its body runs.
+ * If the filter throws, the error propagates to the framework error boundary.
+ * If the filter writes a response (and never calls `next()`), it
+ * short-circuits — but since the wrapper IS the one that calls `next()`, we
+ * detect short-circuit by checking `ctx._written` after the user filter
+ * resolves and skip the downstream chain in that case.
+ */
+function wrapBefore(handler: IngeniumMiddleware): IngeniumMiddleware {
+  return async (ctx, next) => {
+    // The handler may receive a no-op `next` of its own — but for ergonomic
+    // Sinatra parity we want it to look handler-shaped (just `(ctx) => ...`).
+    // We pass a `noopNext` and inspect ctx._written afterward to decide
+    // whether to invoke the real downstream chain.
+    const noopNext = async (): Promise<void> => {}
+    await handler(ctx, noopNext)
+    // Short-circuit if the filter wrote a response — don't run the route.
+    if ((ctx as unknown as { _written?: boolean })._written) return
+    await next()
+  }
+}
+
+/**
+ * Wrap a user `after` filter so it runs only AFTER the downstream chain
+ * resolves. The filter sees the final response state on `ctx` (status code,
+ * headers, body buffer). Errors thrown by the filter propagate to the
+ * framework error boundary just like errors from any other middleware.
+ */
+function wrapAfter(handler: IngeniumMiddleware): IngeniumMiddleware {
+  return async (ctx, next) => {
+    await next()
+    const noopNext = async (): Promise<void> => {}
+    await handler(ctx, noopNext)
+  }
+}
+
+/**
+ * Register a `before` filter on `app`. If `pattern` is omitted, the filter
+ * is registered as a global middleware (runs for every request). Otherwise
+ * the pattern is normalized and registered as a path-scoped middleware.
+ */
+export function registerBefore(
+  app: IngeniumApp,
+  patternOrHandler: string | IngeniumMiddleware,
+  maybeHandler?: IngeniumMiddleware,
+): IngeniumApp {
+  if (typeof patternOrHandler === 'function') {
+    app.use(wrapBefore(patternOrHandler))
+    return app
+  }
+  if (typeof maybeHandler !== 'function') {
+    throw new TypeError('before(pattern, handler): handler must be a function')
+  }
+  const prefix = normalizeFilterPattern(patternOrHandler)
+  if (prefix === '') {
+    app.use(wrapBefore(maybeHandler))
+  } else {
+    app.use(prefix, wrapBefore(maybeHandler))
+  }
+  return app
+}
+
+/**
+ * Register an `after` filter on `app`. Same pattern semantics as
+ * `registerBefore`, but the user body runs after the downstream chain.
+ */
+export function registerAfter(
+  app: IngeniumApp,
+  patternOrHandler: string | IngeniumMiddleware,
+  maybeHandler?: IngeniumMiddleware,
+): IngeniumApp {
+  if (typeof patternOrHandler === 'function') {
+    app.use(wrapAfter(patternOrHandler))
+    return app
+  }
+  if (typeof maybeHandler !== 'function') {
+    throw new TypeError('after(pattern, handler): handler must be a function')
+  }
+  const prefix = normalizeFilterPattern(patternOrHandler)
+  if (prefix === '') {
+    app.use(wrapAfter(maybeHandler))
+  } else {
+    app.use(prefix, wrapAfter(maybeHandler))
+  }
+  return app
+}
+
+/** @internal Exposed for tests. */
+export const _internal_normalizeFilterPattern = normalizeFilterPattern