@nifrajs/core 2.1.0 → 2.3.0

package/dist/server/logger.js

@@ -22,7 +22,7 @@ const SENSITIVE_KEY_PARTS = [
     "ssn",
 ];
 /**
- * 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.
@@ -72,7 +72,7 @@ function redactValue(value, seen, config) {
         return value.map((item) => redactValue(item, seen, config));
     const out = {};
     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);
@@ -92,7 +92,7 @@ function writeToStderr(line) {
 }
 /**
  * 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.
  */
@@ -115,7 +115,7 @@ export function jsonLogger(write = writeToStderr, options) {
     };
 }
 const noop = () => 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 = {
     debug: noop,
     info: noop,

package/dist/server/registry.d.ts

@@ -83,20 +83,20 @@ export type WsRouteInfoFor<Path extends string, In extends StandardSchemaV1 | un
 /**
  * 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, Method extends string, Path extends string, Info extends RouteInfo> = R & {
     [P in Path]: {

package/dist/server/response-contract-lane.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 { StandardSchemaV1 } from "../schema/standard.js";
+import type { IdentityPlugin } from "./plugin.js";
+/**
+ * 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;
+};
+/**
+ * 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 declare function checkResponseContract(schema: StandardSchemaV1, result: unknown, mode: "warn" | "enforce"): ResponseContractOutcome | Promise<ResponseContractOutcome>;
+/**
+ * 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>;
+}
+/**
+ * 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 declare function responseContract(mode?: ResponseContractMode): IdentityPlugin;
+//# sourceMappingURL=response-contract-lane.d.ts.map

package/dist/server/response-contract-lane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-contract-lane.d.ts","sourceRoot":"","sources":["../../src/server/response-contract-lane.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAiC,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAE5F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAGjD;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,SAAS,CAAA;AAErD,uFAAuF;AACvF,MAAM,MAAM,uBAAuB;AACjC,yGAAyG;AACvG;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE;AAClD,gGAAgG;GAC9F;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AAC9E,kGAAkG;GAChG;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AA0B5D;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAQ5D;AA0BD;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAA;IACnC,KAAK,CACH,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,OAAO,GACd,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAA;CAC9D;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,oBAA6B,GAAG,cAAc,CAUpF"}

package/dist/server/response-contract-lane.js

@@ -0,0 +1,81 @@
+import { INSTALL_RESPONSE_CONTRACT } from "./install.js";
+const isPlainObject = (v) => 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, value) {
+    if (!isPlainObject(result) || !isPlainObject(value))
+        return [];
+    return Object.keys(result).filter((k) => !(k in value));
+}
+function describeIssues(issues) {
+    return issues
+        .map((issue) => {
+        const path = Array.isArray(issue.path)
+            ? issue.path
+                .map((seg) => String(typeof seg === "object" && seg !== null ? seg.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, result, mode) {
+    // 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, result, mode) {
+    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.`,
+        };
+}
+/**
+ * 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 = "warn") {
+    const runtime = {
+        mode,
+        check: (schema, result) => checkResponseContract(schema, result, mode),
+    };
+    const apply = (app) => {
+        ;
+        app[INSTALL_RESPONSE_CONTRACT](runtime);
+        return app;
+    };
+    return Object.assign(apply, { pluginName: "nifra:response-contract" });
+}
+//# sourceMappingURL=response-contract-lane.js.map

package/dist/server/response-contract-lane.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-contract-lane.js","sourceRoot":"","sources":["../../src/server/response-contract-lane.ts"],"names":[],"mappings":"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"}