@nifrajs/web 3.5.0 → 4.0.2

package/dist/internal/output-guard.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The data guard. Every value a loader, action, boundary loader or server function sends toward the
+ * browser passes through its declared output schema first:
+ *
+ * - keys the schema does not declare are dropped - that is the guarantee, and it holds even when the
+ *   schema itself would accept them;
+ * - a declared field of the wrong shape fails the request, and the error names field paths only,
+ *   never a value;
+ * - a deferred value must be declared as one (`t.deferred(inner)`), and its resolved value is guarded
+ *   by `inner` before it streams.
+ *
+ * Projection reads the schema's JSON Schema: a nifra schema's `jsonSchema`, or a Standard JSON Schema
+ * (`~standard.jsonSchema.output`). A schema that exposes neither is trusted to strip unknown keys in
+ * its own `validate` output, as zod and valibot objects do by default.
+ */
+import type { StandardSchemaV1 } from "@nifrajs/core/server";
+export declare const DECLASSIFIED_KEY = "x-nifra-declassified";
+/** A field name that usually holds a credential or personal identifier. */
+export declare function isSensitiveFieldName(name: string): boolean;
+/** A browser-bound value failed its output contract. The message carries paths, never values. */
+export declare class OutputGuardError extends Error {
+    readonly name = "OutputGuardError";
+    readonly paths: readonly string[];
+    constructor(message: string, paths?: readonly string[]);
+}
+interface RunState {
+    readonly label: string;
+    readonly issues: string[];
+}
+type Project = (value: unknown, state: RunState) => unknown;
+interface CompiledGuard {
+    /** Undefined when the schema exposes no JSON Schema to project by. */
+    readonly project: Project | undefined;
+    readonly validate: StandardSchemaV1["~standard"]["validate"];
+}
+/**
+ * Prepare `schema` as the output contract of `owner`. Throws when the schema declares a sensitive
+ * field it does not declassify, or references a definition it lacks - at route load, not per request.
+ */
+export declare function outputGuard(schema: unknown, owner: string, exportName: string): CompiledGuard;
+/** Project `value` through `guard`, then validate it. Throws (or rejects) an {@link OutputGuardError}. */
+export declare function runGuard(guard: CompiledGuard, value: unknown, label: string): unknown;
+/** What a browser-bound channel sends, and how it is named in errors. */
+export interface ChannelContract {
+    /** `the loader of "blog/[slug].tsx"` */
+    readonly label: string;
+    readonly guard: CompiledGuard | undefined;
+    /** Where the missing schema goes, for the error when data arrives without one. */
+    readonly missing: string;
+    /** An action may wrap its data in `revalidate(paths, data)`. */
+    readonly revalidate?: boolean;
+}
+/**
+ * Guard one value a channel produced. Nothing, a redirect and an error status pass as they are; a 2xx
+ * `Response` is refused because its body would reach the browser without passing the schema.
+ */
+export declare function guardValue(contract: ChannelContract, value: unknown): unknown;
+/**
+ * Wrap a channel function so everything it returns passes {@link guardValue}. A scalar result stays
+ * synchronous; an object result settles through a promise, as `await` would. A thrown `Response` is
+ * the same answer as a returned one, so a thrown 2xx is refused as well.
+ */
+export declare function guardChannel<Args extends unknown[]>(fn: (...args: Args) => unknown, contract: ChannelContract): (...args: Args) => unknown;
+export {};
+//# sourceMappingURL=output-guard.d.ts.map

package/dist/internal/output-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-guard.d.ts","sourceRoot":"","sources":["../../src/internal/output-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAkB,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAQ5E,eAAO,MAAM,gBAAgB,yBAAyB,CAAA;AAGtD,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAG1D;AA+BD,iGAAiG;AACjG,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAkB,IAAI,sBAAqB;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;gBACrB,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,SAAS,MAAM,EAAO;CAI3D;AAGD,UAAU,QAAQ;IAChB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAC1B;AACD,KAAK,OAAO,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAA;AAE3D,UAAU,aAAa;IACrB,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAAA;IACrC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC,UAAU,CAAC,CAAA;CAC7D;AA+cD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,aAAa,CA0B7F;AAgCD,0GAA0G;AAC1G,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAWrF;AAED,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,CAAA;IACzC,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,gEAAgE;IAChE,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAC9B;AAQD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CA0B7E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,SAAS,OAAO,EAAE,EACjD,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,EAC9B,QAAQ,EAAE,eAAe,GACxB,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAsB5B"}