@nifrajs/core 1.12.0 → 2.0.0

package/src/server/request-context.ts

@@ -0,0 +1,271 @@
+/**
+ * The runtime request context (`c`): the `RawContext` implementation the handler receives, its lazy
+ * `c.set` response-controls backing, and the bounded body readers behind `c.boundedBody`/`c.boundedJson`.
+ * Type-imports the kernel's spine (never its values) and pulls its primitives from `runtime-core`, so it
+ * sits below the server module in the graph.
+ */
+import type { RequestBudget } from "../budget.ts"
+import { drainCapped, parseContentLength, readBoundedBytes } from "./body.ts"
+import type { Platform } from "./context.ts"
+import { type CookieOptions, parseCookies, serializeCookie } from "./cookies.ts"
+import { jsonError } from "./http.ts"
+import { searchOf } from "./query.ts"
+import {
+  CONTEXT_SEARCH,
+  CONTEXT_SET,
+  fallbackWaitUntil,
+  getNeverAbortSignal,
+  getUnboundedRequestBudget,
+  headerOf,
+  requestOf,
+  TEXT_DECODER,
+} from "./runtime-core.ts"
+import type { CtxSet, RawContext, RequestSource } from "./server.ts"
+
+/** A fixed past instant for cookie deletion (`Expires`). A literal epoch - deterministic, unlike an
+ * argless `new Date()`. */
+const EPOCH = new Date(0)
+
+class LazyResponseControls implements CtxSet {
+  status?: number
+  _headers?: Record<string, string>
+  _cookies?: string[]
+
+  get headers(): Record<string, string> {
+    this._headers ??= {}
+    return this._headers
+  }
+
+  cookie(name: string, value: string, options?: CookieOptions): void {
+    // Secure-by-default: HttpOnly + Secure + SameSite=Lax + Path=/, overridable per call.
+    const merged: CookieOptions = {
+      httpOnly: true,
+      secure: true,
+      sameSite: "lax",
+      path: "/",
+      ...options,
+    }
+    this._cookies ??= []
+    this._cookies.push(serializeCookie(name, value, merged))
+  }
+
+  deleteCookie(name: string, options?: Pick<CookieOptions, "path" | "domain">): void {
+    // Expire immediately; default Path=/, and match the original path/domain or the browser keeps it.
+    this._cookies ??= []
+    this._cookies.push(
+      serializeCookie(name, "", { path: "/", ...options, maxAge: 0, expires: EPOCH }),
+    )
+  }
+}
+
+/** Coerce `c.json`/`c.text`'s second arg - a status number (the common case) or a full `ResponseInit`. */
+function statusInit(init?: ResponseInit | number): ResponseInit | undefined {
+  return typeof init === "number" ? { status: init } : init
+}
+
+export class RequestContext implements RawContext {
+  // `declare` keeps TypeScript's class-field emit from first writing `undefined` to every slot; the
+  // constructor initializes only the eager request state, while lazy fields remain absent until used.
+  // Not `readonly`: the lifecycle replaces it with the validated/coerced value when a `params` schema is
+  // declared (`c.params` stays `readonly` to handlers via the `Context` interface).
+  declare params: Record<string, string>
+  declare body: unknown
+  private declare searchValue: string | undefined
+  private declare signalValue: AbortSignal | undefined
+  private declare budgetValue: RequestBudget | undefined
+  private declare platformValue: Platform | undefined
+
+  private declare setValue: CtxSet | undefined
+  private declare queryValue: unknown
+  private declare queryReady: boolean
+  private declare cookiesValue: Readonly<Record<string, string>> | undefined
+  private declare readonly source: RequestSource
+  private declare readonly maxBodyBytes: number
+
+  constructor(source: RequestSource, params: Record<string, string>, maxBodyBytes: number)
+  constructor(
+    source: RequestSource,
+    params: Record<string, string>,
+    search: string | undefined,
+    signal: AbortSignal,
+    budget: RequestBudget,
+    platform: Platform | undefined,
+    maxBodyBytes: number,
+  )
+  constructor(
+    source: RequestSource,
+    params: Record<string, string>,
+    searchOrMaxBodyBytes: string | number | undefined,
+    signal?: AbortSignal,
+    budget?: RequestBudget,
+    platform?: Platform,
+    maxBodyBytes?: number,
+  ) {
+    this.source = source
+    this.params = params
+    if (typeof searchOrMaxBodyBytes === "number") {
+      this.maxBodyBytes = searchOrMaxBodyBytes
+      return
+    }
+    if (searchOrMaxBodyBytes !== undefined) this.searchValue = searchOrMaxBodyBytes
+    this.signalValue = signal
+    this.budgetValue = budget
+    if (platform !== undefined) this.platformValue = platform
+    this.maxBodyBytes = maxBodyBytes as number
+  }
+
+  static native(
+    source: RequestSource,
+    params: Record<string, string>,
+    maxBodyBytes: number,
+  ): RequestContext {
+    return new RequestContext(source, params, maxBodyBytes)
+  }
+
+  [CONTEXT_SET](): CtxSet | undefined {
+    return this.setValue
+  }
+
+  get [CONTEXT_SEARCH](): string {
+    this.searchValue ??= searchOf(this.source.url)
+    return this.searchValue
+  }
+
+  get set(): CtxSet {
+    this.setValue ??= new LazyResponseControls()
+    return this.setValue
+  }
+
+  get signal(): AbortSignal {
+    return this.signalValue ?? getNeverAbortSignal()
+  }
+
+  get budget(): RequestBudget {
+    return this.budgetValue ?? getUnboundedRequestBudget()
+  }
+
+  get env(): unknown {
+    return this.platformValue?.env
+  }
+
+  get clientIp(): string | undefined {
+    // The server resolves the trust declaration into `platform.clientIp` before the context is built,
+    // so this getter just surfaces the already-derived value (raw socket peer by default).
+    return this.platformValue?.clientIp
+  }
+
+  get waitUntil(): (promise: Promise<unknown>) => void {
+    return this.platformValue?.waitUntil ?? fallbackWaitUntil
+  }
+
+  get req(): Request {
+    return requestOf(this.source)
+  }
+
+  get request(): Request {
+    return requestOf(this.source)
+  }
+
+  json(body: unknown, init?: ResponseInit | number): Response {
+    return Response.json(body, statusInit(init))
+  }
+
+  text(body: string, init?: ResponseInit | number): Response {
+    const i = statusInit(init)
+    // Default to text/plain; if the caller passes their own headers, they own the content-type.
+    if (i?.headers !== undefined) return new Response(body, i)
+    return new Response(body, { ...i, headers: { "content-type": "text/plain; charset=utf-8" } })
+  }
+
+  get query(): unknown {
+    if (!this.queryReady) {
+      this.queryValue = new URLSearchParams(this[CONTEXT_SEARCH])
+      this.queryReady = true
+    }
+    return this.queryValue
+  }
+
+  set query(v: unknown) {
+    this.queryValue = v
+    this.queryReady = true
+  }
+
+  get cookies(): Readonly<Record<string, string>> {
+    this.cookiesValue ??= parseCookies(headerOf(this.source, "cookie"))
+    return this.cookiesValue
+  }
+
+  boundedBody(maxBytes?: number): Promise<Uint8Array> {
+    return readBoundedBodyOrThrow(this.source, this.maxBodyBytes, maxBytes)
+  }
+
+  boundedJson<T = unknown>(maxBytes?: number): Promise<T> {
+    return readBoundedJsonBodyOrThrow<T>(this.source, this.maxBodyBytes, maxBytes)
+  }
+}
+
+/** Backs `c.boundedBody`: bounded byte read that throws a flat 413/400 `Response` (caught by
+ * `runLifecycle` as control flow, like `throw redirect(...)`), so a handler can't ignore the cap.
+ * The byte-cap itself lives in `./body.ts` (shared with the schema path and `verifyWebhook`). */
+async function readBoundedBodyOrThrow(
+  req: RequestSource,
+  maxBodyBytes: number,
+  maxBytes?: number,
+): Promise<Uint8Array> {
+  const r = await readBoundedBytes(req, maxBytes ?? maxBodyBytes)
+  if (r.ok) return r.bytes
+  throw r.status === 413
+    ? jsonError(413, "payload_too_large")
+    : jsonError(400, "invalid_content_length")
+}
+
+/** Backs `c.boundedJson`: `readBoundedBodyOrThrow` + `JSON.parse`, throwing a flat 400 on bad JSON. */
+async function readBoundedJsonBodyOrThrow<T>(
+  req: RequestSource,
+  maxBodyBytes: number,
+  maxBytes?: number,
+): Promise<T> {
+  const parsed = await readBoundedJsonSource(req, maxBytes ?? maxBodyBytes)
+  if (parsed instanceof Response) throw parsed
+  return parsed as T
+}
+
+/**
+ * Read a JSON body with the same byte cap used by schema validation and `c.boundedJson`.
+ * Non-chunked, framed requests with an in-cap `Content-Length` use the runtime-native `req.json()`;
+ * chunked or length-less requests fall back to the streaming byte-cap guard.
+ */
+export async function readBoundedJsonSource(
+  req: RequestSource,
+  maxBytes: number,
+): Promise<unknown | Response> {
+  const declared = headerOf(req, "content-length")
+  if (declared !== null) {
+    // A present Content-Length must be a non-negative integer (HTTP grammar: `1*DIGIT`). A
+    // non-numeric / negative / fractional / exponential value (`Number()` would happily accept
+    // "abc"->NaN, "-5", "1.5", "1e3", "0x10") is malformed -> 400, rather than silently falling
+    // through to the streaming guard - which is an UPPER-bound cap only, so a lying SMALLER length
+    // would otherwise be read in full. Real HTTP servers only hand us a valid framed length; this
+    // hardens hand-built Requests (tests, the in-process client) and crafted input.
+    const length = parseContentLength(declared)
+    if (length === undefined) return jsonError(400, "invalid_content_length")
+    if (length > maxBytes) return jsonError(413, "payload_too_large")
+    const chunked = headerOf(req, "transfer-encoding") !== null
+    if (!chunked) {
+      try {
+        return await req.json()
+      } catch {
+        return jsonError(400, "invalid_json")
+      }
+    }
+  }
+  const body = req.body
+  if (body === null) return jsonError(400, "invalid_json")
+  const drained = await drainCapped(body, maxBytes)
+  if (!drained.ok) return jsonError(413, "payload_too_large")
+  try {
+    return JSON.parse(TEXT_DECODER.decode(drained.bytes))
+  } catch {
+    return jsonError(400, "invalid_json")
+  }
+}

package/src/server/respond.ts

@@ -0,0 +1,93 @@
+/**
+ * Response construction from a handler's return value: the header/cookie init, the fused-lane
+ * responders, the fast JSON path, and cookie append. Imports only the runtime-core primitives + the
+ * spine types, so the wire-response format lives in one module distinct from the request engine.
+ */
+import {
+  CONTEXT_SET,
+  EMPTY_RESPONSE_CONTROLS,
+  type HandlerResult,
+  isResponseResult,
+} from "./runtime-core.ts"
+import type { CtxSet, RawContext } from "./server.ts"
+
+/** Build the response headers init. The common path (no `c.set`) returns `undefined` so `Response`
+ * gets no `headers` at all. Cookies force a `Headers` object - multiple `Set-Cookie`s can't live in a
+ * `Record<string,string>` (the 2nd would overwrite the 1st), so they're `append`ed individually. */
+function headersInit(set: CtxSet): Record<string, string> | Headers | undefined {
+  const cookies = set._cookies
+  if (cookies === undefined || cookies.length === 0) return set._headers
+  const headers = new Headers(set._headers)
+  for (const cookie of cookies) headers.append("set-cookie", cookie)
+  return headers
+}
+
+// Keep the fast JSON respond path byte-identical to `Response.json` without probing it at module
+// scope: workerd forbids `Response.json()` during startup. A shared `Headers` is safe to reuse
+// across responses: the Response constructor copies `init.headers` into its own list.
+const JSON_CT_HEADERS = new Headers({
+  "content-type": "application/json;charset=utf-8",
+})
+const JSON_INIT_200: ResponseInit = { status: 200, headers: JSON_CT_HEADERS }
+
+/** Fused-lane respond when `c.set` is untouched. Bun 1.3's native `Response.json` now beats the
+ * older hand-inlined stringify + Response construction on this lane while preserving the exact
+ * body/content-type contract; keep the generic fallback for non-JSON values. */
+export function fusedRespondNoSet(result: unknown): Response {
+  if (
+    result !== undefined &&
+    !(result instanceof Response) &&
+    typeof result === "object" &&
+    result !== null &&
+    !isResponseResult(result)
+  ) {
+    return Response.json(result)
+  }
+  return toResponse(result as HandlerResult, EMPTY_RESPONSE_CONTROLS)
+}
+
+/** Fused-lane respond with a context: read `c.set` once; untouched (the common case) -> the fast
+ * JSON respond; touched -> the generic `toResponse` with those controls (statuses, headers, cookies). */
+export function fusedRespond(result: unknown, ctx: RawContext): Response {
+  const set = ctx[CONTEXT_SET]()
+  if (set === undefined) return fusedRespondNoSet(result)
+  return toResponse(result as HandlerResult, set)
+}
+
+export function toResponse(result: HandlerResult, set: CtxSet): Response {
+  if (isResponseResult(result)) {
+    return appendCookiesToResponse(result.toResponse(), set)
+  }
+  if (result instanceof Response) {
+    return appendCookiesToResponse(result, set)
+  }
+  const headers = headersInit(set)
+  const status = set.status ?? (result === undefined ? 204 : 200)
+  if (headers === undefined && result !== undefined) {
+    // Fast respond (profiled ~50 ns/req faster on every plain-JSON return): `JSON.stringify` + a
+    // prebuilt init beats `Response.json`'s internal init handling. Output is byte-identical -
+    // same body bytes, same probed content-type. `undefined` from stringify (a function/symbol
+    // result) delegates to Response.json so its TypeError contract stays the single source.
+    const body = JSON.stringify(result) as string | undefined
+    if (body !== undefined) {
+      return new Response(
+        body,
+        status === 200 ? JSON_INIT_200 : { status, headers: JSON_CT_HEADERS },
+      )
+    }
+  }
+  const init: ResponseInit = headers === undefined ? { status } : { status, headers }
+  return result === undefined ? new Response(null, init) : Response.json(result, init)
+}
+
+export function appendCookiesToResponse(response: Response, set: CtxSet): Response {
+  // A handler may queue cookies (`c.set.cookie` - e.g. a session cookie) AND return its own Response
+  // (e.g. `redirect("/")` after login). Cookies accumulate additively, so append them to the
+  // returned Response - otherwise the canonical set-session-then-redirect pattern would silently drop
+  // the cookie. (Other `c.set` fields stay the returned Response's own concern.)
+  const cookies = set._cookies
+  if (cookies !== undefined && cookies.length > 0) {
+    for (const cookie of cookies) response.headers.append("set-cookie", cookie)
+  }
+  return response
+}

package/src/server/runtime-core.ts

@@ -0,0 +1,74 @@
+/**
+ * Runtime-core: the small primitives shared across the server's request/response modules - the context
+ * symbols, the `ResponseResult` marker, the lazy never-abort signal / unbounded budget singletons, and
+ * the request-source accessors. Kept in one leaf (it only type-imports the server's spine types, never
+ * its values) so `request-context`, `respond`, `node-outcome`, and the kernel form a cycle-free graph.
+ */
+import { createUnboundedRequestBudget, type RequestBudget } from "../budget.ts"
+import type { CtxSet, RequestSource } from "./server.ts"
+
+/** A handler returns a `Response` (used as-is) or any value (serialized to JSON). */
+export type HandlerResult = Response | unknown
+
+export const RESPONSE_RESULT = Symbol.for("nifra.response.result")
+export const CONTEXT_SET = Symbol("nifra.context.set")
+export const CONTEXT_SEARCH = Symbol("nifra.context.search")
+
+export interface ResponseResult {
+  readonly [RESPONSE_RESULT]: true
+  toResponse(): Response
+  toNodeBody?(): {
+    readonly status: number
+    readonly headers: Readonly<Record<string, string | readonly string[]>> | undefined
+    readonly body: string | Uint8Array
+  }
+}
+
+export function isResponseResult(value: unknown): value is ResponseResult {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { readonly [RESPONSE_RESULT]?: unknown })[RESPONSE_RESULT] === true &&
+    typeof (value as { readonly toResponse?: unknown }).toResponse === "function"
+  )
+}
+
+/** The concrete `Request` for a source - itself when a real `Request` was passed (the Web path), or the
+ * lazily-built one (the Node adapter). A real `Request` IS a `RequestSource`, so no wrapper is allocated
+ * on the Web hot path. */
+export function requestOf(source: RequestSource): Request {
+  return source.request ?? (source as unknown as Request)
+}
+
+export function headerOf(source: RequestSource, name: string): string | null {
+  return source.header?.(name) ?? source.headers.get(name)
+}
+
+/** Off-edge `waitUntil`: run the background work fire-and-forget, never leaking an unhandled
+ * rejection. Edge runtimes pass their own (Workers `ctx.waitUntil`) via the platform arg. */
+export const fallbackWaitUntil = (promise: Promise<unknown>): void => {
+  void promise.catch(() => {})
+}
+
+// Finalization only reads `status`, `_headers`, and `_cookies`. The user-visible mutator methods
+// live on `LazyResponseControls`, created by the `c.set` getter only when user code touches it.
+export const EMPTY_RESPONSE_CONTROLS = Object.freeze({}) as CtxSet
+
+export const TEXT_DECODER = new TextDecoder()
+
+/**
+ * Shared never-aborting signal for `ctx.signal` when no timeout is armed - created lazily and
+ * cached. NOT a module-scope `new AbortController()`: edge runtimes (Cloudflare workerd) forbid
+ * constructing one in global scope; the first request builds it inside the handler, then it's
+ * reused at zero per-request cost.
+ */
+let neverAbortSignal: AbortSignal | undefined
+let unboundedRequestBudget: RequestBudget | undefined
+export const getNeverAbortSignal = (): AbortSignal => {
+  neverAbortSignal ??= new AbortController().signal
+  return neverAbortSignal
+}
+export const getUnboundedRequestBudget = (): RequestBudget => {
+  unboundedRequestBudget ??= createUnboundedRequestBudget(getNeverAbortSignal())
+  return unboundedRequestBudget
+}

package/src/server/server-types.ts

@@ -0,0 +1,204 @@
+/**
+ * Public API-surface types for the server: construction options, the capacity-admission contract,
+ * route/tool/MCP descriptors, and the middleware bundle shape. Pure types (no runtime), split out of
+ * the server kernel so the descriptor/option vocabulary is one file, distinct from the engine.
+ */
+import type { CapabilityUseEvent } from "../internal/capability-runtime.ts"
+import type { AssuranceEvidence } from "../internal/route-assurance.ts"
+import type { Method } from "../router/router.ts"
+import type { ClientIpTrust } from "./client-ip.ts"
+import type { Context, Platform, RouteSchema } from "./context.ts"
+import type { Logger } from "./logger.ts"
+import type { MaybePromise, OnRequestResult } from "./server.ts"
+
+/**
+ * The outcome of a capacity-admission decision. `admitted` requests carry a `release` the server calls
+ * exactly once when the response is finalized; a shed request carries a ready `429` Response.
+ */
+export type AdmissionDecision =
+  | { readonly admitted: true; release(): void }
+  | { readonly admitted: false; readonly response: Response }
+
+/**
+ * A capacity-admission gate. Decides, per request, whether the instance has capacity to run it now -
+ * bounding *concurrency*, which rate limits (frequency) and deadlines (duration) do not. Provide an
+ * implementation (see `@nifrajs/middleware`'s `createAdmissionController`) as {@link ServerOptions.admission}.
+ *
+ * Enabling it trades the fused native-route lane for native matching + this gate (the gate cannot be a
+ * per-request `onRequest` hook without disabling native routes entirely); when unset, the request path
+ * is untouched.
+ */
+export interface AdmissionController {
+  admit(req: Request): AdmissionDecision | Promise<AdmissionDecision>
+}
+
+export interface ServerOptions {
+  /**
+   * Max request body size (bytes), enforced **only when a route declares a body schema** - the cap
+   * lives in the schema-validated read path. Default 1_000_000.
+   *
+   * A route WITHOUT a body schema (raw body, file upload, BYO-validation) that reads `c.req` directly
+   * is not auto-bounded - use **`c.boundedBody(maxBytes?)`** / **`c.boundedJson(maxBytes?)`**, which
+   * apply this same cap (override per route by passing `maxBytes` - larger for an upload endpoint,
+   * smaller to tighten one).
+   */
+  readonly maxBodyBytes?: number
+  /** Max inbound WebSocket message size (bytes) when `listen()`ing on Bun - frames over this are rejected
+   * by the runtime before reaching your handler (so a huge frame can't be JSON-parsed into memory).
+   * Default: `maxBodyBytes` (1 MB). */
+  readonly wsMaxPayloadBytes?: number
+  /** Per-request timeout (ms): a slower request gets a 503 and `ctx.signal` aborts. 0 disables (default). */
+  readonly requestTimeoutMs?: number
+  /**
+   * How to derive `c.clientIp` behind a reverse proxy or CDN. Omit (default) to trust only the raw
+   * socket peer and never believe a forwarded header. Set `{ trustedHops: n }` when the app sits
+   * behind `n` proxies you operate (the caller is read from `X-Forwarded-For` past those hops), or
+   * `{ header: name }` to trust one edge-set header's first value. Declaring trust the app can't
+   * actually enforce lets clients forge their IP, so leave it unset unless a proxy really fronts you.
+   */
+  readonly clientIp?: ClientIpTrust
+  /**
+   * Admit the public `x-nifra-deadline` header and let it shorten local work. Disabled by default:
+   * services that participate in trusted cross-service deadline propagation opt in explicitly,
+   * while ordinary/public HTTP routes pay no header-admission tax and ignore hostile client values.
+   */
+  readonly acceptInboundDeadlines?: boolean
+  /**
+   * Maximum time accepted from an inbound `x-nifra-deadline`, in milliseconds. An incoming absolute
+   * deadline may shorten this cap (and `requestTimeoutMs`, when configured), never extend it.
+   * Default 30_000; applies only when `acceptInboundDeadlines` is enabled and the header is present.
+   */
+  readonly maxInboundDeadlineMs?: number
+  /** When `listen()`ing, install SIGTERM/SIGINT handlers that gracefully `stop()`. Default false. */
+  readonly gracefulSignals?: boolean
+  /**
+   * Capacity-admission gate (see {@link AdmissionController}). Bounds concurrent in-flight work so a
+   * healthy instance sheds load (`429` + `Retry-After`) instead of accepting more than it can finish.
+   * Off by default. Enabling it disables the fused native-route fast path (requests route through the
+   * shared matched lane where the gate runs); when unset, the request path pays nothing.
+   */
+  readonly admission?: AdmissionController
+  /**
+   * Optional token-only observation hook called by `useCapability(c, id)`. It receives no request,
+   * parameters, body, tenant, or values. Routes without capability declarations keep the old hot path.
+   */
+  readonly onCapabilityUse?: (event: CapabilityUseEvent) => void
+  /** Structured logger for framework events (redacts secrets). Default: JSON to stderr. */
+  readonly logger?: Logger
+  /**
+   * App-wide fallback fired when a route **without its own `onValidationError`** fails body/query
+   * validation. Same contract as the per-route hook (`(issues, ctx, kind) => Response | repaired-value |
+   * undefined`): a route's own hook takes precedence, and a route can fall through to the plain `422` by
+   * returning `undefined`. Use it for one app-wide error envelope (like tRPC's `errorFormatter` /
+   * Fastify's `setErrorHandler`) instead of repeating a formatter per route.
+   */
+  readonly onValidationError?: RouteSchema["onValidationError"]
+}
+
+/**
+ * MCP tool safety hints, surfaced in `tools/list`, that tell an agent how risky a `.tool()` call is - so it
+ * can decide whether to auto-invoke or confirm first. All optional; an omitted hint means "unknown". Mirrors
+ * the MCP spec's tool `annotations`.
+ */
+export interface ToolAnnotations {
+  /** Human-readable display title for the tool, distinct from the machine `name`. */
+  readonly title?: string
+  /** The tool does not modify its environment (a pure read). */
+  readonly readOnlyHint?: boolean
+  /** The tool may perform destructive updates - only meaningful when `readOnlyHint` is not `true`. */
+  readonly destructiveHint?: boolean
+  /** Repeated calls with the same arguments have no additional effect beyond the first. */
+  readonly idempotentHint?: boolean
+  /** The tool interacts with external entities (an "open world" beyond this server). */
+  readonly openWorldHint?: boolean
+}
+
+/**
+ * A registered route's public descriptor - method, path, and input schemas. The
+ * router trie discards the original patterns, so this flat list is what lets tools
+ * (e.g. `toOpenAPI`) enumerate routes after registration.
+ */
+export interface RouteDescriptor {
+  readonly method: Method
+  readonly path: string
+  readonly schema: RouteSchema | undefined
+  /** Effective enforcement evidence, populated only during reflection/introspection. */
+  readonly assurance?: readonly AssuranceEvidence[]
+  /** Normalized declared effect tokens, populated only when the route declares any. */
+  readonly capabilities?: readonly string[]
+  /** Set when the route is a declared dynamic route family (`schema.family`). */
+  readonly family?: boolean
+  readonly tool?: {
+    readonly name: string
+    readonly description: string
+    readonly annotations?: ToolAnnotations
+  }
+}
+
+/** A message in an MCP prompt's rendered output (see {@link Server.prompt}). */
+export interface PromptMessage {
+  readonly role: "user" | "assistant"
+  readonly content: { readonly type: "text"; readonly text: string }
+}
+
+/** One declared argument of an MCP prompt, surfaced in `prompts/list`. */
+export interface PromptArgument {
+  readonly name: string
+  readonly description?: string
+  readonly required?: boolean
+}
+
+/** An app-declared MCP resource - read-only data an agent can fetch through `nifra mcp`. */
+export interface McpResourceDescriptor {
+  readonly uri: string
+  readonly name: string
+  readonly description?: string
+  readonly mimeType?: string
+  readonly read: () => MaybePromise<string | { readonly text: string; readonly mimeType?: string }>
+}
+
+/** An app-declared MCP prompt - a reusable prompt template an agent can fetch through `nifra mcp`. */
+export interface McpPromptDescriptor {
+  readonly name: string
+  readonly description: string
+  readonly arguments?: readonly PromptArgument[]
+  readonly handler: (args: Record<string, string>) => MaybePromise<readonly PromptMessage[]>
+}
+
+/**
+ * The handle `listen()` returns - the slice of Bun's server nifra holds and exposes.
+ * Declared explicitly (rather than `ReturnType<typeof Bun.serve>`) so the public type
+ * surface doesn't leak the ambient `Bun` global into consumers' `.d.ts` resolution.
+ */
+export interface RunningServer {
+  readonly port: number
+  readonly hostname: string
+  readonly pendingRequests: number
+  stop(closeActiveConnections?: boolean): void
+}
+
+/**
+ * A bundle of lifecycle hooks applied together via {@link Server.use} - the unit
+ * `@nifrajs/middleware` ships (cors, security headers, rate-limit). Every hook is
+ * optional and wired to its lifecycle point. Middleware is context-agnostic (sees
+ * the base `Context`); `use` does no context-type merging - the full type-merging
+ * plugin system is deferred, and `.use` is reserved as its future entry point.
+ */
+export interface Middleware {
+  readonly name?: string
+  readonly onRequest?: (req: Request, platform?: Platform) => MaybePromise<OnRequestResult>
+  readonly around?: <T>(context: Context, next: () => MaybePromise<T>) => MaybePromise<T>
+  readonly beforeHandle?: (context: Context) => MaybePromise<unknown>
+  readonly afterHandle?: (result: unknown, context: Context) => MaybePromise<unknown>
+  readonly onResponse?: (response: Response, req: Request) => MaybePromise<Response>
+  readonly onResponseFinalized?: (outcome: ResponseFinalization, req: Request) => MaybePromise<void>
+  readonly onError?: (error: unknown, context: Context) => MaybePromise<unknown>
+}
+
+/** The terminal response-pipeline outcome observed after every transforming `onResponse` hook. */
+export interface ResponseFinalization {
+  /** The final response, or the last response available when a transformation failed. */
+  readonly response: Response
+  /** A response-hook failure. Terminal observers run fail-open before the error is rethrown. */
+  readonly error?: unknown
+}