@nifrajs/core 2.14.1 → 3.2.0

package/src/security/baseline.ts

@@ -0,0 +1,172 @@
+import type { AssurancePolicy, AssuranceRule } from "../assurance.ts"
+import { NIFRA_ASSURANCE_IDS } from "../internal/route-assurance.ts"
+
+/**
+ * How much a {@link securityBaseline} demands. Each level is a superset of the one before it, so
+ * raising the level only ever adds findings.
+ *
+ * - `"essential"` - the invariants that hold for ANY app and never false-positive on a reasonable
+ *   one: a body read must be bounded, an unlimited body may never claim to be bounded, an agent tool
+ *   ingress must be bounded, and an authenticated state change must prove CSRF. Every required piece
+ *   of evidence here is either published by the core from the route schema or only demanded when the
+ *   route already opted into the risk (CSRF is required only where authentication is present). Safe to
+ *   adopt on day one.
+ * - `"standard"` (default) - essential, plus: a route the app itself classified as `pii` or higher
+ *   must be authenticated, whether it reads or writes. High signal, low noise - it fires only on
+ *   routes the application already labelled sensitive.
+ * - `"strict"` - standard, plus the opinionated, higher-friction requirements: every route must carry
+ *   a response contract, every read must carry security headers, and every mutation must be rate
+ *   limited. These need middleware the app has to install, so they are opt-in rather than default.
+ */
+export type SecurityBaselineLevel = "essential" | "standard" | "strict"
+
+/** Tuning for {@link securityBaseline}. Every knob only ever tightens the policy. */
+export interface SecurityBaselineOptions {
+  /** How much the baseline demands. Default `"standard"`. See {@link SecurityBaselineLevel}. */
+  readonly level?: SecurityBaselineLevel
+  /**
+   * How to treat a route no rule matched. Default `"ignore"` so the baseline is purely additive - it
+   * asserts the invariants below and stays silent on everything else, which lets a project adopt it
+   * without first classifying its whole route table. Set `"error"` to make an unclassified route a
+   * finding, turning the baseline into a closed allow-list (recommended once the table is covered).
+   */
+  readonly unmatched?: "error" | "ignore"
+  /**
+   * Require that a matched route's evidence was installed by runtime enforcement (middleware/plugin
+   * or framework policy) rather than asserted inline on `schema.assurance`. Default `true`: an author
+   * label is not proof, and a security baseline that accepts labels is theater. Set `false` only to
+   * stage adoption before guards emit runtime evidence.
+   */
+  readonly requireRuntimeProvenance?: boolean
+}
+
+const MUTATING = ["POST", "PUT", "PATCH", "DELETE"] as const
+const READING = ["GET", "HEAD"] as const
+/** The classification threshold above which the baseline demands authentication. */
+const SENSITIVE = "pii" as const
+
+/**
+ * A first-match-wins security policy that turns the recurring audit finding classes into machine
+ * checked route invariants. Composed only from the public assurance engine, so it inherits its
+ * fail-closed evaluation, provenance checks, and selector validation - no bespoke evaluator.
+ *
+ * The rules are ordered most-specific-first because assurance evaluation is first-match-wins: each
+ * route is owned by exactly one rule, so that rule carries the FULL requirement bundle for its class
+ * (a body-carrying mutation proves bounded-body AND CSRF in one rule, not two). Raising the `level`
+ * widens those bundles; it never reorders them.
+ *
+ * Coverage by level (see {@link SecurityBaselineLevel} for the rationale):
+ *
+ * | invariant | essential | standard | strict |
+ * | --- | :-: | :-: | :-: |
+ * | unlimited body can never be "bounded" (F-001) | ✓ | ✓ | ✓ |
+ * | every body read is bounded | ✓ | ✓ | ✓ |
+ * | agent tool ingress is bounded | ✓ | ✓ | ✓ |
+ * | authenticated mutation proves CSRF | ✓ | ✓ | ✓ |
+ * | pii+ route is authenticated | | ✓ | ✓ |
+ * | every route carries a response contract | | | ✓ |
+ * | every read carries security headers | | | ✓ |
+ * | every mutation is rate limited | | | ✓ |
+ *
+ * The baseline deliberately does not select on `access`/`zone` capabilities: those selectors require
+ * capability definitions and would make the preset refuse an app that declares none. Extend the
+ * returned policy's `rules` for capability- or path-specific requirements; put more specific rules
+ * before these so they own their routes first.
+ */
+export function securityBaseline(options: SecurityBaselineOptions = {}): AssurancePolicy {
+  const level = options.level ?? "standard"
+  const strict = level === "strict"
+  const authSensitive = level !== "essential"
+  const provenance = options.requireRuntimeProvenance === false ? "any" : "runtime"
+
+  const A = NIFRA_ASSURANCE_IDS
+  // Evidence the app must install middleware for, gated to the levels that assume that cost.
+  const contract = strict ? [A.RESPONSE_CONTRACT] : []
+  const headers = strict ? [A.SECURITY_HEADERS] : []
+  const rateLimit = strict ? [A.RATE_LIMITED] : []
+  const authed = authSensitive ? [A.AUTHENTICATED] : []
+
+  const rules: AssuranceRule[] = [
+    // The static twin of the config-time rejection: a schema route that opted into `bodyLimit:
+    // "unlimited"` can never carry `nifra.body-bounded` (the core withholds it), so requiring it is a
+    // standing ban. Owns the unlimited case before any body rule below can soften it. (F-001.)
+    {
+      name: "banned-unlimited-body",
+      match: { hasBody: true, bodyLimit: "unlimited" },
+      require: [A.BODY_BOUNDED],
+    },
+    // Agent tool ingress buffers attacker-influenced arguments; it must be bounded. Not CSRF-guarded:
+    // tool calls are token-authenticated machine traffic, not ambient-cookie browser posts.
+    {
+      name: "tool-ingress-bounded",
+      match: { tools: true, hasBody: true },
+      require: [A.BODY_BOUNDED, ...contract],
+      requireProvenance: provenance,
+    },
+  ]
+
+  // Sensitive mutations, split by body shape so bounded-body is required only where a body exists.
+  // Emitted only when a level adds a requirement beyond the generic mutation rules, otherwise they
+  // would be redundant duplicates that only slow evaluation.
+  if (authSensitive || strict) {
+    rules.push(
+      {
+        name: "sensitive-mutation-body",
+        match: { methods: [...MUTATING], hasBody: true, classificationAtLeast: SENSITIVE },
+        require: [A.BODY_BOUNDED, ...authed, ...contract, ...rateLimit],
+        requireCsrfWithAuthenticated: true,
+        requireProvenance: provenance,
+      },
+      {
+        name: "sensitive-mutation",
+        match: { methods: [...MUTATING], classificationAtLeast: SENSITIVE },
+        require: [...authed, ...contract, ...rateLimit],
+        requireCsrfWithAuthenticated: true,
+        requireProvenance: provenance,
+      },
+    )
+  }
+
+  rules.push(
+    {
+      name: "mutation-body",
+      match: { methods: [...MUTATING], hasBody: true },
+      require: [A.BODY_BOUNDED, ...contract, ...rateLimit],
+      requireCsrfWithAuthenticated: true,
+      requireProvenance: provenance,
+    },
+    {
+      name: "mutation",
+      match: { methods: [...MUTATING] },
+      require: [...contract, ...rateLimit],
+      requireCsrfWithAuthenticated: true,
+      requireProvenance: provenance,
+    },
+  )
+
+  if (authSensitive || strict) {
+    rules.push({
+      name: "sensitive-read",
+      match: { methods: [...READING], classificationAtLeast: SENSITIVE },
+      require: [...authed, ...contract, ...headers],
+      requireProvenance: provenance,
+    })
+  }
+
+  // The catch-all read rule. At essential/standard its requirement bundle is empty, so it is a pure
+  // classification that simply marks reads as covered - which matters only under `unmatched: "error"`,
+  // where an unowned route would otherwise fail. At strict it demands the response + header contract.
+  rules.push({
+    name: "read",
+    match: { methods: [...READING] },
+    require: [...contract, ...headers],
+    ...(strict ? { requireProvenance: provenance } : {}),
+  })
+
+  return {
+    rules,
+    unmatched: options.unmatched ?? "ignore",
+    // A wrong import reflecting zero routes must fail, not silently pass a security gate.
+    allowEmpty: false,
+  }
+}

package/src/server/bare-error-lane.ts

@@ -0,0 +1,77 @@
+/**
+ * The bare lane's ERROR rendering, as free functions the kernel delegates to.
+ *
+ * ## Why this is a lane module and not methods on `Server`
+ *
+ * These are the cold half of the bare request lane: what happens when a handler (or a `derive`)
+ * throws, rather than returns. The success half stays on the class - it reads request-lifecycle
+ * state and is the async-frame-skip hot path - but the error half needs none of that class state:
+ * `renderBareError` is pure control-flow routing, and `emitRequestErrorLog` needs only the logger
+ * and the detail policy, both of which are config fixed at construction. Passing those two in keeps
+ * this file free of any runtime dependency back on `server.ts`, so there is no import cycle: the
+ * `RawContext`/`CtxSet` imports are type-only and erased (the same shape `edge.ts` already relies on).
+ *
+ * A single source of truth for the thrown-value contract matters because it is a security surface:
+ * an unhandled throw must render as a 500 with no caller-controlled body, and the amount of the
+ * error's own text that reaches the log sink is the app's `errorLogDetail` call, not an accident of
+ * which lane caught it. Both the generic bare lane and the fused body runner route here, so that
+ * decision lives in exactly one place.
+ */
+import { pathnameOf } from "./http.ts"
+import type { Logger } from "./logger.ts"
+import { isResponseResult, type ResponseResult } from "./runtime-core.ts"
+import type { CtxSet, RawContext } from "./server.ts"
+
+/** How much of a thrown error's own text reaches the log sink. Mirrors `Server`'s option. */
+export type ErrorLogDetail = "full" | "message" | "none"
+
+/**
+ * Render a value thrown on the bare lane. Three shapes, in the order the lane means them:
+ *   - a bare `Response` is the app answering directly - passed through untouched;
+ *   - a thrown `status(...)` is control flow, still plain data: rendered through the same `finalize`
+ *     a RETURNED one takes, with the request's `c.set`, so it costs what the return costs;
+ *   - anything else is a real fault: logged once, then a bodyless 500 (never the caller's error text).
+ *
+ * `responseSet` and `logError` are injected rather than imported so this file keeps no runtime edge
+ * back to `server.ts` (`responseSet` reaches into the context's set symbol; `logError` closes over the
+ * server's logger). Both run only on the throw path, so the closures cost nothing on the hot lane.
+ */
+export function renderBareError<T>(
+  err: unknown,
+  ctx: RawContext,
+  finalize: (result: unknown, set: CtxSet, ctx: RawContext) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
+  responseSet: (ctx: RawContext) => CtxSet,
+  logError: (err: unknown, ctx: RawContext) => void,
+  internalError: () => T,
+): T {
+  if (err instanceof Response) return wrapResponse(err)
+  if (isResponseResult(err)) return finalize(err, responseSet(ctx), ctx)
+  logError(err, ctx)
+  return internalError()
+}
+
+/**
+ * Write an unhandled request error to the log. An error's own text can quote the input that produced
+ * it, so how much of it reaches the sink is the app's call (`detail`). The default keeps it: a 500
+ * with no message and no stack is an incident nobody can diagnose, and the framework already ships
+ * the narrower instrument for the leak - a redacting logger with `valuePatterns`. `"none"` is there
+ * for an untrusted sink.
+ */
+export function emitRequestErrorLog(
+  logger: Logger,
+  detail: ErrorLogDetail,
+  err: unknown,
+  ctx: RawContext,
+): void {
+  logger.error("unhandled request error", {
+    method: ctx.req.method,
+    path: pathnameOf(ctx.req.url),
+    name: err instanceof Error ? err.name : "Error",
+    // `detail`, not `message`: the logger uses `message` for its own first argument, so a field of
+    // that name is silently overwritten and the thrown error's own text never reaches the sink. It
+    // survived only incidentally inside `stack`, and was lost outright for a non-Error throw.
+    ...(detail === "none" ? {} : { detail: err instanceof Error ? err.message : String(err) }),
+    ...(detail === "full" && err instanceof Error ? { stack: err.stack } : {}),
+  })
+}

package/src/server/body-lane.ts

@@ -0,0 +1,203 @@
+/**
+ * The shared framed body parser. Kept separate from RequestContext so compact edge consumers can
+ * reuse the exact trust-boundary lane without bundling the full context implementation (cookies,
+ * deferred responses, and request helpers).
+ */
+import { drainCapped, hasTrustedBodyFraming, parseContentLength, RAW_BODY_READERS } from "./body.ts"
+import { plainError } from "./http.ts"
+import { guardParsedValue, type ProtoPoisoning, parseJsonGuarded } from "./proto-guard.ts"
+import { isUrlEncodedForm, readBoundedForm } from "./query.ts"
+import {
+  headerOf,
+  isResponseResult,
+  PRE_DECODED_BODY,
+  type PreDecodedBody,
+  type ResponseResult,
+  TEXT_DECODER,
+} from "./runtime-core.ts"
+import type { MaybePromise, RequestSource } from "./server.ts"
+
+type JsonResultContinuation<T> = (result: unknown | ResponseResult) => T | Promise<T>
+type JsonErrorContinuation<T> = (error: unknown) => T | Promise<T>
+
+type FramedJsonSource = RequestSource & {
+  readonly bytes?: () => Promise<Uint8Array>
+  readonly jsonWithByteLength?: () => Promise<{
+    readonly value: unknown
+    readonly byteLength: number
+  }>
+}
+
+const INVALID_JSON = (): ResponseResult => plainError(400, "invalid_json")
+
+/** Read a JSON source with the declared-length precheck, delivered-byte recheck, streaming cap, and
+ * prototype-poisoning guard in one lane. */
+export function readBoundedJsonSource(
+  req: RequestSource,
+  maxBytes: number,
+  protoPoisoning?: ProtoPoisoning,
+): Promise<unknown | ResponseResult>
+export function readBoundedJsonSource<T>(
+  req: RequestSource,
+  maxBytes: number,
+  protoPoisoning: ProtoPoisoning,
+  onResult: JsonResultContinuation<T>,
+  onError: JsonErrorContinuation<T>,
+): Promise<T>
+export function readBoundedJsonSource<T>(
+  req: RequestSource,
+  maxBytes: number,
+  protoPoisoning: ProtoPoisoning = "reject",
+  onResult?: JsonResultContinuation<T>,
+  onError?: JsonErrorContinuation<T>,
+): Promise<unknown | ResponseResult | T> {
+  const preDecoded = (req as { [PRE_DECODED_BODY]?: PreDecodedBody })[PRE_DECODED_BODY]
+  if (preDecoded !== undefined) {
+    return onResult === undefined
+      ? Promise.resolve(preDecoded.value)
+      : Promise.resolve(preDecoded.value).then(onResult)
+  }
+
+  const raw = ((req as { [RAW_BODY_READERS]?: RequestSource })[RAW_BODY_READERS] ??
+    req) as FramedJsonSource
+  const declared = headerOf(req, "content-length")
+  if (declared !== null) {
+    const length = parseContentLength(declared)
+    if (length === undefined)
+      return onResult === undefined
+        ? Promise.resolve(plainError(400, "invalid_content_length"))
+        : Promise.resolve(plainError(400, "invalid_content_length")).then(onResult)
+    if (length > maxBytes)
+      return onResult === undefined
+        ? Promise.resolve(plainError(413, "payload_too_large"))
+        : Promise.resolve(plainError(413, "payload_too_large")).then(onResult)
+
+    if (hasTrustedBodyFraming(req)) {
+      return raw.json().then(
+        (parsed) => {
+          try {
+            const guarded = guardParsedValue(parsed, protoPoisoning)
+            return onResult === undefined ? guarded : onResult(guarded)
+          } catch {
+            return onResult === undefined
+              ? plainError(400, "invalid_json")
+              : onResult(plainError(400, "invalid_json"))
+          }
+        },
+        () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
+      )
+    }
+
+    if (headerOf(req, "transfer-encoding") === null) {
+      const jsonWithByteLength = raw.jsonWithByteLength
+      if (jsonWithByteLength !== undefined) {
+        return jsonWithByteLength.call(raw).then(
+          ({ value, byteLength }) => {
+            if (byteLength > length || byteLength > maxBytes) {
+              return onResult === undefined
+                ? plainError(413, "payload_too_large")
+                : onResult(plainError(413, "payload_too_large"))
+            }
+            try {
+              const guarded = guardParsedValue(value, protoPoisoning)
+              return onResult === undefined ? guarded : onResult(guarded)
+            } catch {
+              return onResult === undefined
+                ? plainError(400, "invalid_json")
+                : onResult(plainError(400, "invalid_json"))
+            }
+          },
+          () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
+        )
+      }
+
+      const bytesReader = raw.bytes
+      if (bytesReader !== undefined) {
+        return bytesReader.call(raw).then(
+          (bytes) => {
+            if (bytes.byteLength > length || bytes.byteLength > maxBytes) {
+              return onResult === undefined
+                ? plainError(413, "payload_too_large")
+                : onResult(plainError(413, "payload_too_large"))
+            }
+            try {
+              const parsed = parseJsonGuarded(TEXT_DECODER.decode(bytes), protoPoisoning)
+              return onResult === undefined ? parsed : onResult(parsed)
+            } catch {
+              return onResult === undefined
+                ? plainError(400, "invalid_json")
+                : onResult(plainError(400, "invalid_json"))
+            }
+          },
+          () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
+        )
+      }
+
+      return raw.arrayBuffer().then(
+        (buffer) => {
+          const bytes = new Uint8Array(buffer)
+          if (bytes.byteLength > length || bytes.byteLength > maxBytes) {
+            return onResult === undefined
+              ? plainError(413, "payload_too_large")
+              : onResult(plainError(413, "payload_too_large"))
+          }
+          try {
+            const parsed = parseJsonGuarded(TEXT_DECODER.decode(bytes), protoPoisoning)
+            return onResult === undefined ? parsed : onResult(parsed)
+          } catch {
+            return onResult === undefined
+              ? plainError(400, "invalid_json")
+              : onResult(plainError(400, "invalid_json"))
+          }
+        },
+        () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
+      )
+    }
+  }
+
+  const body = raw.body
+  const streamed =
+    body === null
+      ? Promise.resolve<unknown | ResponseResult>(plainError(400, "invalid_json"))
+      : drainCapped(body, maxBytes).then((drained) => {
+          if (!drained.ok) return plainError(413, "payload_too_large")
+          try {
+            return parseJsonGuarded(TEXT_DECODER.decode(drained.bytes), protoPoisoning)
+          } catch {
+            return plainError(400, "invalid_json")
+          }
+        })
+  return onResult === undefined ? streamed : streamed.then(onResult, onError)
+}
+
+/** The shared content-type dispatcher around the JSON and urlencoded lanes. */
+export function readBodyFramed<T>(
+  source: RequestSource,
+  maxBodyBytes: number,
+  protoPoisoning: ProtoPoisoning,
+  onParsed: (parsed: unknown) => MaybePromise<T>,
+  wrapResponse: (response: Response | ResponseResult) => T,
+  onError: (err: unknown) => MaybePromise<T>,
+): Promise<T> {
+  const contentType = headerOf(source, "content-type") ?? ""
+  if (contentType !== "application/json" && !contentType.includes("application/json")) {
+    if (isUrlEncodedForm(contentType)) {
+      return readBoundedForm(source, maxBodyBytes).then(
+        (form) => (isResponseResult(form) ? wrapResponse(form) : onParsed(form)),
+        onError,
+      ) as Promise<T>
+    }
+    return Promise.resolve(wrapResponse(plainError(415, "unsupported_media_type")))
+  }
+  try {
+    return readBoundedJsonSource(
+      source,
+      maxBodyBytes,
+      protoPoisoning,
+      (parsed) => (isResponseResult(parsed) ? wrapResponse(parsed) : onParsed(parsed)),
+      onError,
+    )
+  } catch (err) {
+    return Promise.resolve(onError(err))
+  }
+}

package/src/server/body.ts

@@ -37,6 +37,14 @@ export function rawBodySourceOf<T extends BodySource>(req: T): T {
   return ((req as { [RAW_BODY_READERS]?: T })[RAW_BODY_READERS] as T | undefined) ?? req
 }
 
+/**
+ * The byte cap a route that declared `bodyLimit: "unlimited"` reads under. It is a real number, not
+ * `Infinity` or a skipped check: every bounded reader keeps its single `> maxBytes` enforcement
+ * point (and its `assertByteLimit` guard) rather than growing an uncapped branch that a future
+ * caller could reach by accident. No HTTP body reaches 2^53-1 bytes, so this is unlimited in fact.
+ */
+export const UNLIMITED_BODY_BYTES = Number.MAX_SAFE_INTEGER
+
 /** Security/resource limits must be finite byte counts. Invalid values otherwise make `> maxBytes`
  * comparisons fail open (notably for `NaN`) and can re-enable unbounded buffering. */
 export function assertByteLimit(value: number, name = "maxBytes"): void {

package/src/server/bridge-markers.ts

@@ -0,0 +1,24 @@
+/**
+ * Wire marker keys shared between @nifrajs/core and the @nifrajs/node adapter.
+ *
+ * Each entry names a symbol looked up with `Symbol.for(...)`, so the two packages agree ONLY by the
+ * string. A rename on one side and not the other is a silent protocol break - no type error, just a
+ * symbol that never matches and a body that stops taking the direct-write lane. This module is the
+ * single source: core defines its own symbols from these literals, and `scripts/gen-node-outcome.ts`
+ * copies the map verbatim into the adapter's generated contract, so @nifrajs/node reads the identical
+ * strings without a runtime dependency on core (the same deployment shape the generated outcome type
+ * preserves).
+ *
+ * Keep this module import-free: every core file that owns one of these symbols imports it, so a cycle
+ * here would reach most of the response path.
+ */
+export const NODE_BRIDGE_MARKER_KEYS = {
+  /** A `Response` carrying its already-serialized bytes, so the Node writer emits them without a drain. */
+  responseBody: "nifra.response.body",
+  /** A plain-data response-result carrier the node lane renders without building a `Response`. */
+  responseResult: "nifra.response.result",
+  /** Proof that a header record's names are already the lowercase wire spelling. */
+  lowercaseHeaderKeys: "nifra.headers.lowercase",
+  /** A mounted handler's node-direct resolver entry point. */
+  resolveNodeMount: "@nifrajs/core/resolve-node-mount",
+} as const

package/src/server/context.ts

@@ -64,7 +64,12 @@ export type Params<Path extends string> = Prettify<RawParams<Path>>
 export interface RouteSchema {
   /** Transport body cap for this route. Defaults to the server's maxBodyBytes. Use a finite
    * smaller/larger limit for a specific endpoint. The 'unlimited' value is an explicit
-   * streaming/upload exemption and requires a non-empty bodyLimitReason for auditability. */
+   * streaming/upload exemption and requires a non-empty bodyLimitReason for auditability.
+   *
+   * 'unlimited' is legal only for schema-less streaming/upload routes. It is rejected with `body` or
+   * `idempotency`, because those lanes buffer the body before user code can apply a protocol-specific
+   * bound. Read an unlimited route from `c.req.body` as a stream and bound it by the protocol it speaks;
+   * `nifra.body-bounded` is deliberately NOT published for an unlimited route. */
   readonly bodyLimit?: number | "unlimited"
   /** Required explanation when bodyLimit is 'unlimited' (for example, a streaming upload is
    * bounded by an upstream object-store protocol). */

package/src/server/contract.ts

@@ -5,9 +5,11 @@ import { METHODS, type Method } from "../router/router.ts"
 import type { InferInput, InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
 import { assertByteLimit } from "./body.ts"
 import type { Context, IdempotencyConfig, Params, RouteSchema } from "./context.ts"
-import type { EmptyRegistry, OutputOf, Registry } from "./registry.ts"
+import type { EmptyRegistry, OutputOf, Registry, RouteInfoFor } from "./registry.ts"
 import { Server } from "./server.ts"
 
+type EmptyResponseMap = NonNullable<unknown>
+
 /** An additional (non-success) response a contract operation can document, e.g. a `404`. */
 export interface ResponseDef {
   readonly description?: string
@@ -88,7 +90,9 @@ type OpErrorBodies<Rs extends Record<string, ResponseDef>> = {
   [K in keyof Rs as K extends `2${string}`
     ? never
     : K extends `${infer N extends number}`
-      ? N
+      ? Rs[K] extends { schema: StandardSchemaV1 }
+        ? N
+        : never
       : never]: Rs[K] extends {
     schema: infer S extends StandardSchemaV1
   }
@@ -106,6 +110,26 @@ type OpErrors<O extends OperationDef> = O extends {
     : OpErrorBodies<Rs>
   : unknown
 
+/** The schema-bearing status map a contract consumer can use for success and failure narrowing. */
+type OpAdditionalResponseMap<O extends OperationDef> = O extends {
+  responses: infer Rs extends Record<string, ResponseDef>
+}
+  ? {
+      [K in keyof Rs as K extends `${infer N extends number}`
+        ? Rs[K] extends { schema: StandardSchemaV1 }
+          ? N
+          : never
+        : never]: Rs[K] extends { schema: infer S extends StandardSchemaV1 }
+        ? InferOutput<S>
+        : never
+    }
+  : EmptyResponseMap
+
+type OpResponseMap<O extends OperationDef> = Omit<OpAdditionalResponseMap<O>, 200> &
+  (O extends { response: infer R extends StandardSchemaV1 }
+    ? { 200: InferOutput<R> }
+    : EmptyResponseMap)
+
 /**
  * RouteInfo as a *decoupled consumer* sees it from the contract alone: the
  * `output` is the declared `response` schema's type, or `unknown` when none is
@@ -118,6 +142,7 @@ type RouteInfoForOp<O extends OperationDef> = {
   readonly query: OpQuery<O>
   readonly body: OpBody<O>
   readonly output: OpResponse<O>
+  readonly responses: OpResponseMap<O>
   // The error union from the op's non-2xx `responses` - so a decoupled contract client sees typed error
   // bodies, just like an inline route's `errors`. `unknown` when the op declares no error responses.
   readonly errors: OpErrors<O>
@@ -143,6 +168,25 @@ type SchemaForOp<O extends OperationDef> = (O extends { body: infer B extends St
     : Record<never, never>) &
   (O extends { params: infer P extends StandardSchemaV1 } ? { params: P } : Record<never, never>)
 
+type OpResponseSchemas<O extends OperationDef> = O extends {
+  responses: infer Rs extends Record<string, ResponseDef>
+}
+  ? {
+      [K in keyof Rs as K extends `2${string}`
+        ? never
+        : Rs[K] extends { schema: StandardSchemaV1 }
+          ? K extends `${infer N extends number}`
+            ? N
+            : never
+          : never]: Rs[K] extends { schema: infer S extends StandardSchemaV1 } ? S : never
+    }
+  : EmptyResponseMap
+
+type RouteSchemaForOp<O extends OperationDef> = SchemaForOp<O> &
+  RouteSchema &
+  (O extends { response: infer R extends StandardSchemaV1 } ? { response: R } : EmptyResponseMap) &
+  (keyof OpResponseSchemas<O> extends never ? EmptyResponseMap : { errors: OpResponseSchemas<O> })
+
 /**
  * The handler context for an op - identical to the inline `Context<Path, S>`, so a
  * handler written for an inline route type-checks unchanged under `implement`
@@ -245,23 +289,12 @@ export type RegistryFromImpl<
   C extends ContractShape,
   H extends HandlersFor<C, Ctx>,
   Ctx = NonNullable<unknown>,
+  HookOutput = never,
 > = {
   [P in C[keyof C]["path"]]: {
-    [K in keyof C as C[K]["path"] extends P ? C[K]["method"] : never]: {
-      readonly params: Params<C[K]["path"]>
-      readonly query: OpQuery<C[K]>
-      readonly body: OpBody<C[K]>
-      readonly output: C[K] extends { response: infer R extends StandardSchemaV1 }
-        ? InferOutput<R>
-        : H[K] extends AnyFn
-          ? OutputOf<H[K]>
-          : unknown
-      // The error union from the op's non-2xx `responses` (see OpErrors) - a graduated contract client sees
-      // the same typed error bodies as the inline `errors` path.
-      readonly errors: OpErrors<C[K]>
-      // Mirrors RouteInfoForOp: no SSE contract on contract ops (yet) - mode conformance holds.
-      readonly sse: never
-    }
+    [K in keyof C as C[K]["path"] extends P ? C[K]["method"] : never]: H[K] extends AnyFn
+      ? RouteInfoFor<C[K]["path"], RouteSchemaForOp<C[K]>, OutputOf<H[K]>, HookOutput>
+      : RouteInfoFor<C[K]["path"], RouteSchemaForOp<C[K]>, unknown, HookOutput>
   }
 }
 
@@ -290,9 +323,24 @@ export function implement<
   H extends HandlersFor<C, Ctx>,
   R extends Registry = EmptyRegistry,
   Ctx = NonNullable<unknown>,
->(contract: C, handlers: H, app?: Server<R, Ctx>): Server<R & RegistryFromImpl<C, H, Ctx>, Ctx> {
-  const target = (app ?? new Server()) as Server<R, Ctx>
+  HookOutput = never,
+>(
+  contract: C,
+  handlers: H,
+  app?: Server<R, Ctx, HookOutput>,
+): Server<R & RegistryFromImpl<C, H, Ctx, HookOutput>, Ctx, HookOutput> {
+  const target = (app ?? new Server()) as Server<R, Ctx, HookOutput>
   const routes = Object.entries(contract).map(([name, op]) => {
+    const errors =
+      op.responses === undefined
+        ? undefined
+        : Object.fromEntries(
+            Object.entries(op.responses)
+              .filter(
+                ([status, response]) => !status.startsWith("2") && response.schema !== undefined,
+              )
+              .map(([status, response]) => [Number(status), response.schema!]),
+          )
     // body/query are validated at the request boundary; `response` is a type + introspection contract
     // ONLY - never validated at runtime and never read on the request hot path (the lifecycle reads
     // schema.body/query by name; the `bare`/bodyOnly/queryOnly fast-path gates ignore `response`). Built
@@ -304,6 +352,7 @@ export function implement<
       op.body !== undefined ||
       op.query !== undefined ||
       op.response !== undefined ||
+      (errors !== undefined && Object.keys(errors).length > 0) ||
       op.capabilities !== undefined ||
       op.idempotency !== undefined ||
       op.bodyLimit !== undefined ||
@@ -316,6 +365,7 @@ export function implement<
             ...(op.body !== undefined ? { body: op.body } : {}),
             ...(op.query !== undefined ? { query: op.query } : {}),
             ...(op.response !== undefined ? { response: op.response } : {}),
+            ...(errors !== undefined && Object.keys(errors).length > 0 ? { errors } : {}),
             ...(op.capabilities !== undefined ? { capabilities: op.capabilities } : {}),
             ...(op.idempotency !== undefined ? { idempotency: op.idempotency } : {}),
             ...(op.bodyLimit !== undefined ? { bodyLimit: op.bodyLimit } : {}),
@@ -335,5 +385,5 @@ export function implement<
   target.registerBatch(routes)
   // Runtime registered exactly the contract's routes through the inline path; the
   // registry type is computed from the contract inputs + handler return types.
-  return target as unknown as Server<R & RegistryFromImpl<C, H, Ctx>, Ctx>
+  return target as unknown as Server<R & RegistryFromImpl<C, H, Ctx, HookOutput>, Ctx, HookOutput>
 }