@nifrajs/core 2.1.0 → 2.3.0

package/src/server/logger.ts

@@ -35,12 +35,12 @@ const SENSITIVE_KEY_PARTS: ReadonlyArray<string> = [
 
 /**
  * Tunes redaction. Key-name redaction always runs; the rest is **opt-in**:
- * - `keyParts` — extra case-insensitive key fragments, added to the built-in denylist.
- * - `valuePatterns` — regexes matched against string **values** *and* the log message; each match is
+ * - `keyParts` - extra case-insensitive key fragments, added to the built-in denylist.
+ * - `valuePatterns` - regexes matched against string **values** *and* the log message; each match is
  *   replaced with the placeholder. This is the value-scanning hook for secrets that land in a value or
- *   message (e.g. `err.message`), which key-name redaction can't catch. Off unless provided — the
+ *   message (e.g. `err.message`), which key-name redaction can't catch. Off unless provided - the
  *   default path does no value scanning, so it stays allocation-light. See {@link commonSecretPatterns}.
- * - `placeholder` — the replacement string (default `[REDACTED]`).
+ * - `placeholder` - the replacement string (default `[REDACTED]`).
  */
 export interface RedactOptions {
   readonly keyParts?: readonly string[]
@@ -49,7 +49,7 @@ export interface RedactOptions {
 }
 
 /**
- * A conservative, high-signal set of patterns for {@link RedactOptions.valuePatterns} — opt in by
+ * A conservative, high-signal set of patterns for {@link RedactOptions.valuePatterns} - opt in by
  * passing it (or a subset) to `jsonLogger`/`redactLogFields`. Covers bearer tokens, JWTs, emails, and a
  * few well-known key formats (Stripe, GitHub, AWS access-key ids). Chosen to minimize false positives;
  * add your own (e.g. internal id formats) as needed. Every pattern is global so all matches are scrubbed.
@@ -106,7 +106,7 @@ function redactValue(value: unknown, seen: WeakSet<object>, config: RedactConfig
   if (Array.isArray(value)) return value.map((item) => redactValue(item, seen, config))
   const out: Record<string, unknown> = {}
   for (const [key, val] of Object.entries(value)) {
-    // A sensitive key wins outright (don't scan it) — the whole value is replaced.
+    // A sensitive key wins outright (don't scan it) - the whole value is replaced.
     out[key] = isSensitiveKey(key, config.keyParts)
       ? config.placeholder
       : redactValue(val, seen, config)
@@ -129,7 +129,7 @@ function writeToStderr(line: string): void {
 
 /**
  * The default logger: one redacted JSON object per line. `write` is injectable for tests or
- * alternative sinks (defaults to stderr). `options` tunes redaction — pass `valuePatterns` (e.g.
+ * alternative sinks (defaults to stderr). `options` tunes redaction - pass `valuePatterns` (e.g.
  * {@link commonSecretPatterns}) to also scrub secrets embedded in values + the message. Framework keys
  * (`level`, `message`, `time`) always win over user fields of the same name.
  */
@@ -158,7 +158,7 @@ export function jsonLogger(
 
 const noop = (): void => undefined
 
-/** Discards everything — for tests, or when log output is handled elsewhere. */
+/** Discards everything - for tests, or when log output is handled elsewhere. */
 export const silentLogger: Logger = {
   debug: noop,
   info: noop,

package/src/server/registry.ts

@@ -108,20 +108,20 @@ export type WsRouteInfoFor<
 /**
  * Merge a new route into the registry, combining methods that share a path.
  *
- * SCALING CEILING (measured — see many-routes.test-d.ts and the isolation study below): a single
- * fluent chain hits TS2589 at ~95-100 routes. This intersection is NOT the cause — in isolation it
+ * SCALING CEILING (measured - see many-routes.test-d.ts and the isolation study below): a single
+ * fluent chain hits TS2589 at ~95-100 routes. This intersection is NOT the cause - in isolation it
  * accumulates 1000+ routes cleanly, and heavy per-route `Params<Path>`/schema inference alone
  * reaches 600+. The wall is an INTERACTION unique to the fluent builder: each `.get(path, handler)`
  * both (a) computes the handler's context type from the path (`c.params.id` inferred from `:id`)
  * AND (b) returns `Server<AddRoute<growing-R, …>, Ctx>`. Neither alone strains the compiler; the
- * PRODUCT — recomputing the handler context while re-threading the ever-larger registry at each of
- * N steps — exhausts TypeScript's per-expression instantiation budget around N≈95. It is therefore
+ * PRODUCT - recomputing the handler context while re-threading the ever-larger registry at each of
+ * N steps - exhausts TypeScript's per-expression instantiation budget around N≈95. It is therefore
  * O(N) and inherent to any builder that infers handler context AND accumulates a typed route
  * registry (Elysia/tRPC/hono's typed clients cap the same way); it is not fixable by reshaping
  * AddRoute. Past ~90 routes, use a path that DOESN'T form the product: split into domain groups and
  * `.merge()` them (each group is a short chain; a merge is one `R & R2` intersection with no
  * per-call context work), or contract-first `implement()` (the registry is one object type declared
- * upfront — no grow-R-per-call, so no ceiling at all).
+ * upfront - no grow-R-per-call, so no ceiling at all).
  */
 export type AddRoute<
   R extends Registry,

package/src/server/response-contract-lane.ts

@@ -0,0 +1,164 @@
+/**
+ * Making a route's declared `response` schema mean something at runtime.
+ *
+ * ## The gap this closes
+ *
+ * A `response` schema is a LOWER bound, not an upper one. It says "at least these fields, of these
+ * types"; it never said "only these". TypeScript does not close the gap either - excess-property
+ * checking fires on a fresh object literal in an annotated position, and a handler is neither: it is a
+ * contextually-typed argument that usually returns a variable. So this compiles, and ships every field:
+ *
+ *     app.get("/me", { response: PublicUser }, async () => {
+ *       const user = await db.users.find(id)   // { id, name, email, passwordHash, ... }
+ *       return user                            // all of it goes on the wire
+ *     })
+ *
+ * The client's type says `{ id, name }`, so the leak is invisible from both ends. And it can appear
+ * with no code change at all: add a column to `users`, and the next deploy ships it to browsers.
+ *
+ * ## Why the behaviour follows the schema, not this module
+ *
+ * Standard Schema exposes exactly one operation - `validate` - and no way to enumerate a schema's
+ * declared keys. So a projection of "just the declared fields" cannot be written generically here;
+ * the only clean value available is whatever `validate()` returns. That is deliberate on the spec's
+ * part, and it means enforcement inherits each validator's own semantics:
+ *
+ *   - a STRIPPING schema (zod, valibot) returns a cleaned value -> the undeclared fields are removed
+ *   - a STRICT schema (`@nifrajs/schema`'s `t.object`) reports issues -> the response is a violation
+ *
+ * That is not an inconsistency to paper over: a strict schema has already declared that extra fields
+ * are an error, and a stripping one has declared they are ignorable. Enforcement honours what the
+ * author wrote rather than overriding it.
+ */
+import type { StandardIssue, StandardResult, StandardSchemaV1 } from "../schema/standard.ts"
+import { INSTALL_RESPONSE_CONTRACT } from "./install.ts"
+import type { IdentityPlugin } from "./plugin.ts"
+import type { AnyServer } from "./server.ts"
+
+/**
+ * How hard a declared `response` schema is held.
+ *
+ *   - `warn`    - check and log; the response is sent UNCHANGED, so enabling it cannot break anything.
+ *   - `enforce` - serialize the validated value, so undeclared data cannot reach the wire.
+ *
+ * There is no `off`: not installing the plugin IS off, and that is what keeps this module out of an
+ * app's bundle entirely rather than shipping a disabled branch to everyone.
+ */
+export type ResponseContractMode = "warn" | "enforce"
+
+/** The outcome of checking one handler result against its declared response schema. */
+export type ResponseContractOutcome =
+  /** Nothing to report. `value` is what should be serialized (the original result, or the cleaned one). */
+  | { readonly kind: "ok"; readonly value: unknown }
+  /** `warn` only: the payload differed from the contract. The ORIGINAL result is still served. */
+  | { readonly kind: "warn"; readonly value: unknown; readonly message: string }
+  /** `enforce` only: the payload cannot be reconciled with the contract, so it must not be sent. */
+  | { readonly kind: "violation"; readonly message: string }
+
+const isPlainObject = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v)
+
+/** Top-level keys present in the handler's result but absent from the validated value. */
+function droppedKeys(result: unknown, value: unknown): string[] {
+  if (!isPlainObject(result) || !isPlainObject(value)) return []
+  return Object.keys(result).filter((k) => !(k in value))
+}
+
+function describeIssues(issues: ReadonlyArray<StandardIssue>): string {
+  return issues
+    .map((issue) => {
+      const path = Array.isArray(issue.path)
+        ? issue.path
+            .map((seg) =>
+              String(typeof seg === "object" && seg !== null ? (seg as { key: unknown }).key : seg),
+            )
+            .join(".")
+        : ""
+      return path === "" ? issue.message : `${path}: ${issue.message}`
+    })
+    .join("; ")
+}
+
+/**
+ * Check one result against the route's declared response schema.
+ *
+ * Returns synchronously when the schema does (the common case), so an app that opts in does not pay a
+ * microtask per response for a check that had no work to do.
+ */
+export function checkResponseContract(
+  schema: StandardSchemaV1,
+  result: unknown,
+  mode: "warn" | "enforce",
+): ResponseContractOutcome | Promise<ResponseContractOutcome> {
+  // A handler may return a raw Response as deliberate control flow (a redirect, a stream). There is no
+  // JSON payload to hold to the contract, and re-serializing one would corrupt it.
+  if (result instanceof Response || result === undefined) return { kind: "ok", value: result }
+  const settled = schema["~standard"].validate(result)
+  return settled instanceof Promise
+    ? settled.then((r) => interpret(r, result, mode))
+    : interpret(settled, result, mode)
+}
+
+function interpret(
+  settled: StandardResult<unknown>,
+  result: unknown,
+  mode: "warn" | "enforce",
+): ResponseContractOutcome {
+  if (settled.issues !== undefined) {
+    const message = `response does not satisfy its declared contract: ${describeIssues(settled.issues)}`
+    // `warn` never changes what is served - it reports and gets out of the way, so switching it on can
+    // never be the thing that broke production.
+    return mode === "warn"
+      ? { kind: "warn", value: result, message }
+      : { kind: "violation", message }
+  }
+  const dropped = droppedKeys(result, settled.value)
+  if (mode === "enforce") return { kind: "ok", value: settled.value }
+  return dropped.length === 0
+    ? { kind: "ok", value: result }
+    : {
+        kind: "warn",
+        value: result,
+        message: `response carries fields its contract does not declare: ${dropped.join(", ")}. They are being sent; \`responseContract: "enforce"\` would strip them.`,
+      }
+}
+
+/**
+ * What the server holds when the plugin is installed. The kernel calls `check` through this object and
+ * never imports the implementation, so an app that does not install the plugin does not carry it.
+ */
+export interface ResponseContractRuntime {
+  readonly mode: ResponseContractMode
+  check(
+    schema: StandardSchemaV1,
+    result: unknown,
+  ): ResponseContractOutcome | Promise<ResponseContractOutcome>
+}
+
+interface ResponseContractInstallable {
+  [INSTALL_RESPONSE_CONTRACT](runtime: ResponseContractRuntime): void
+}
+
+/**
+ * Hold every route's declared `response` schema to what the handler actually returned.
+ *
+ *     app.use(responseContract("enforce"))
+ *
+ * Install it before the routes it should cover - like `idempotency()`, the decision is made per route
+ * at registration, so routes registered earlier are not retroactively covered.
+ *
+ * A contracted route leaves the fused and native fast paths, because the check needs the handler's
+ * value before it becomes bytes. That is the same trade an idempotent route makes, and the reason this
+ * is opt-in rather than always on.
+ */
+export function responseContract(mode: ResponseContractMode = "warn"): IdentityPlugin {
+  const runtime: ResponseContractRuntime = {
+    mode,
+    check: (schema, result) => checkResponseContract(schema, result, mode),
+  }
+  const apply = <S extends AnyServer>(app: S): S => {
+    ;(app as unknown as ResponseContractInstallable)[INSTALL_RESPONSE_CONTRACT](runtime)
+    return app
+  }
+  return Object.assign(apply, { pluginName: "nifra:response-contract" }) as IdentityPlugin
+}