@nifrajs/web 3.5.0 → 4.0.0

package/dist/internal/response-controls.js

@@ -0,0 +1,256 @@
+import { status as statusResult, } from "@nifrajs/core/server";
+import { DATA_HEADER } from "../router.js";
+import { isResponseResult } from "./render-document.js";
+export const PRIVATE_NO_STORE = "private, no-store";
+/**
+ * Headers of a navigation data response. It shares its URL with the document and differs only by a
+ * request header, so it must never be stored by a cache keyed on the URL alone: a stored data payload
+ * would be served in place of the page.
+ */
+export const DATA_RESPONSE_HEADERS = Object.freeze({
+    "cache-control": PRIVATE_NO_STORE,
+    vary: DATA_HEADER,
+});
+/**
+ * Merge order of the header writers: middleware root to leaf (`MIDDLEWARE_SCOPE + i`), layouts root
+ * to leaf (`i`), then the page loader, then the action.
+ */
+export const PAGE_SCOPE = 1e9;
+export const ACTION_SCOPE = PAGE_SCOPE + 1;
+export const MIDDLEWARE_SCOPE = -PAGE_SCOPE;
+// RFC 9110 `token` and `field-value` (visible ASCII, space, tab, obs-text). A value outside this set
+// could split the header block or be rejected by the transport after the loader already ran.
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const FIELD_VALUE = /^[\t\x20-\x7e\x80-\xff]*$/;
+const FRAMEWORK_PREFIX = "x-nifra-";
+const TRANSPORT_OWNED = new Set([
+    "connection",
+    "content-encoding",
+    "content-length",
+    "keep-alive",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+]);
+const reservedReason = (name) => {
+    if (name === "set-cookie")
+        return "use ctx.set.cookie(), which applies the secure cookie defaults";
+    if (name === "location")
+        return "return redirect() instead";
+    if (name === "content-type")
+        return "the framework sets it for the representation it renders";
+    if (TRANSPORT_OWNED.has(name))
+        return "the transport owns it";
+    if (name.startsWith(FRAMEWORK_PREFIX))
+        return "the x-nifra- prefix is reserved for the framework";
+    return undefined;
+};
+/** `existing` with the data-request header added, so a cache keeps the document and its data apart. */
+export function varyOnDataHeader(existing) {
+    if (existing === null || existing === undefined)
+        return DATA_HEADER;
+    let empty = true;
+    for (const part of existing.split(",")) {
+        const name = part.trim().toLowerCase();
+        if (name === "")
+            continue;
+        if (name === "*" || name === DATA_HEADER)
+            return existing;
+        empty = false;
+    }
+    return empty ? DATA_HEADER : `${existing}, ${DATA_HEADER}`;
+}
+const CACHE_CONTROL = "cache-control";
+/** Headers of a rendered page that carries a cookie queued through `ctx.set`. */
+export const PRIVATE_PAGE_HEADERS = Object.freeze({
+    [CACHE_CONTROL]: PRIVATE_NO_STORE,
+});
+/**
+ * `outcome` kept out of shared caches, for a request that queued a cookie through `ctx.set`.
+ *
+ * A rendered page is already private, and a plain render (`redirect()`, `status()`) inherits the
+ * serving app's header record. That leaves a hand-built `Response`, which inherits nothing, and a
+ * plain render that names its own `cache-control`, which would win over the inherited one.
+ */
+export function privateOutcome(outcome) {
+    if (outcome instanceof Response)
+        return privateResponse(outcome);
+    if (!isResponseResult(outcome))
+        return outcome;
+    const plain = outcome.plain;
+    const own = plain?.headers;
+    if (plain === undefined || own === undefined)
+        return outcome;
+    let headers;
+    for (const name of Object.keys(own)) {
+        if (name.toLowerCase() !== CACHE_CONTROL)
+            continue;
+        headers ??= { ...own };
+        delete headers[name];
+    }
+    if (headers === undefined)
+        return outcome;
+    headers[CACHE_CONTROL] = PRIVATE_NO_STORE;
+    return statusResult(plain.status, plain.body, { headers });
+}
+function privateResponse(response) {
+    if (response.headers.get(CACHE_CONTROL) === PRIVATE_NO_STORE)
+        return response;
+    try {
+        response.headers.set(CACHE_CONTROL, PRIVATE_NO_STORE);
+        return response;
+    }
+    catch {
+        // Immutable headers (`Response.redirect()`, a `fetch()` result): answer with a copy.
+        const headers = new Headers(response.headers);
+        headers.set(CACHE_CONTROL, PRIVATE_NO_STORE);
+        return new Response(response.body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers,
+        });
+    }
+}
+/**
+ * One page request's `ctx.set`: the response headers and cookies its loaders and action write.
+ *
+ * Every loader gets its own header record ({@link scope}), merged in a fixed order when the response
+ * is committed, so layout loaders that run in parallel with the page loader cannot race on a name.
+ * Cookies go straight to the serving app's own controls, which serialize them with the secure defaults
+ * and append them to whatever the request answers with.
+ */
+export class PageResponseControls {
+    #c;
+    #written;
+    #sealed = false;
+    #personalized = false;
+    constructor(c) {
+        this.#c = c;
+    }
+    /** True once a cookie was queued through `ctx.set`: the response is specific to this visitor. */
+    get personalized() {
+        return this.#personalized;
+    }
+    /** The `ctx.set` of one loader or action. `order` fixes where its headers land in the merge. */
+    scope(order) {
+        return new ScopedResponseControls(this, order);
+    }
+    /** A scope's header record, created on first use. */
+    track(order) {
+        const headers = Object.create(null);
+        this.#written ??= [];
+        this.#written.push({ order, headers });
+        return headers;
+    }
+    /** The serving app's controls, marked as carrying per-visitor state. Throws once sealed. */
+    cookies(member) {
+        this.assertOpen(member);
+        this.personalize();
+        return this.#c.set;
+    }
+    /** Mark the response as one visitor's - a queued cookie, or a draft render - so no cache stores it. */
+    personalize() {
+        if (this.#personalized)
+            return;
+        this.#personalized = true;
+        // A redirect or status render merges the serving app's header record, so this keeps those
+        // outcomes out of shared caches too (a 301 is cacheable by default).
+        this.#c.set.headers["cache-control"] = PRIVATE_NO_STORE;
+    }
+    assertOpen(member) {
+        if (!this.#sealed)
+            return;
+        throw new Error(`[nifra/web] ctx.set.${member} was used after the response was committed. Write response headers and cookies before the loader or action returns - a deferred promise settles too late.`);
+    }
+    /**
+     * Close the controls: the response is decided. A later write - a deferred promise that settles after
+     * the loader returned - throws instead of being dropped without a trace.
+     */
+    seal() {
+        if (this.#sealed)
+            return;
+        this.#sealed = true;
+        if (this.#written === undefined)
+            return;
+        for (const entry of this.#written)
+            Object.freeze(entry.headers);
+    }
+    /**
+     * Seal, validate, and merge every written header. Returns `undefined` when none was written.
+     * Throws on a name or value that cannot be sent, and on a name the framework or transport owns.
+     */
+    commit() {
+        this.seal();
+        const written = this.#written;
+        if (written === undefined)
+            return undefined;
+        if (written.length > 1)
+            written.sort((a, b) => a.order - b.order);
+        let merged;
+        for (const entry of written) {
+            for (const rawName of Object.keys(entry.headers)) {
+                const name = validHeaderName(rawName);
+                merged ??= Object.create(null);
+                merged[name] = validHeaderValue(name, entry.headers[rawName]);
+            }
+        }
+        return merged;
+    }
+    /**
+     * The committed headers for the document. Written headers make the document vary on the
+     * data-request header; a queued cookie makes it private, whatever a loader asked for.
+     */
+    documentHeaders() {
+        const written = this.commit();
+        if (written !== undefined)
+            written.vary = varyOnDataHeader(written.vary);
+        if (!this.#personalized)
+            return written;
+        const headers = written ?? Object.create(null);
+        headers["cache-control"] = PRIVATE_NO_STORE;
+        return headers;
+    }
+}
+class ScopedResponseControls {
+    #owner;
+    #order;
+    #headers;
+    constructor(owner, order) {
+        this.#owner = owner;
+        this.#order = order;
+    }
+    get headers() {
+        this.#owner.assertOpen("headers");
+        this.#headers ??= this.#owner.track(this.#order);
+        return this.#headers;
+    }
+    cookie(name, value, options) {
+        this.#owner.cookies("cookie()").cookie(name, value, options);
+    }
+    deleteCookie(name, options) {
+        this.#owner.cookies("deleteCookie()").deleteCookie(name, options);
+    }
+}
+function validHeaderName(rawName) {
+    if (!TOKEN.test(rawName)) {
+        throw new Error(`[nifra/web] ctx.set.headers: ${JSON.stringify(rawName)} is not a valid header name`);
+    }
+    const name = rawName.toLowerCase();
+    const reason = reservedReason(name);
+    if (reason !== undefined) {
+        throw new Error(`[nifra/web] ctx.set.headers: "${name}" is reserved - ${reason}`);
+    }
+    return name;
+}
+// The message names the header only: a value can carry a token or a visitor's data.
+function validHeaderValue(name, value) {
+    if (typeof value !== "string") {
+        throw new Error(`[nifra/web] ctx.set.headers: the value of "${name}" must be a string`);
+    }
+    if (!FIELD_VALUE.test(value)) {
+        throw new Error(`[nifra/web] ctx.set.headers: the value of "${name}" contains a character a header cannot carry (a line break, a control character, or one outside Latin-1)`);
+    }
+    return value;
+}
+//# sourceMappingURL=response-controls.js.map

package/dist/internal/response-controls.js.map

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

package/dist/internal/runtime-contract.d.ts

@@ -1,28 +1,23 @@
-/** Phantom brand key for {@link ServerOnly}. */
-declare const SERVER_ONLY_BRAND: unique symbol;
+/** Phantom brand key for {@link BackendOnly}. */
+declare const BACKEND_ONLY_BRAND: unique symbol;
 /**
  * Type-level intent marker for a value that must only exist on the server - a secret, a DB handle, a
- * server-only client. `ServerOnly<T>` is structurally `T` (the brand is an optional phantom field, so
+ * server-only client. `BackendOnly<T>` is structurally `T` (the brand is an optional phantom field, so
  * existing code keeps type-checking), but it advertises to readers + the compiler that the value is
  * not meant to cross to the browser. It is **purely type-level** and erases at build - it does NOT,
  * by itself, keep the value out of the client bundle.
  *
- * The enforcement is two runtime conventions:
- *  - add the side-effect import `import "@nifrajs/web/server-only"` at the top of the module - the
- *    client build ({@link buildClient}) fails loud, with the import chain, if it reaches a browser
- *    chunk (the poison-import marker);
- *  - or name the file `*.server.ts` - the `.server` convention empties it in the client build.
- *
- * Use this brand to express the intent in the types; pair it with one of those runtime markers so a
- * leak is caught at build time rather than shipping a secret to the client.
+ * The enforcement is the zone rules: code under `backend/` or in a `*.backend.ts` file never reaches a
+ * browser build, and a module that imports `@nifrajs/web/backend-only` fails every browser build that
+ * reaches it, wherever it lives.
  *
  * @example
- * import "@nifrajs/web/server-only"
- * import type { ServerOnly } from "@nifrajs/web"
- * export const apiKey: ServerOnly<string> = process.env.SECRET_API_KEY!
+ * import "@nifrajs/web/backend-only"
+ * import type { BackendOnly } from "@nifrajs/web"
+ * export const apiKey: BackendOnly<string> = process.env.SECRET_API_KEY!
  */
-export type ServerOnly<T> = T & {
-    readonly [SERVER_ONLY_BRAND]?: never;
+export type BackendOnly<T> = T & {
+    readonly [BACKEND_ONLY_BRAND]?: never;
 };
 /**
  * Pre-hydration form guard - a tiny inline script flushed in `<head>` (it runs in the window between

package/dist/internal/runtime-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-contract.d.ts","sourceRoot":"","sources":["../../src/internal/runtime-contract.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,OAAO,CAAC,MAAM,iBAAiB,EAAE,OAAO,MAAM,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,GAAG;IAAE,QAAQ,CAAC,CAAC,iBAAiB,CAAC,CAAC,EAAE,KAAK,CAAA;CAAE,CAAA;AAExE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,QAOjB,CAAA;AAEf;;;;;yCAKyC;AACzC,eAAO,MAAM,gBAAgB,OAAO,CAAA"}
+{"version":3,"file":"runtime-contract.d.ts","sourceRoot":"","sources":["../../src/internal/runtime-contract.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,OAAO,CAAC,MAAM,kBAAkB,EAAE,OAAO,MAAM,CAAA;AAE/C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG;IAAE,QAAQ,CAAC,CAAC,kBAAkB,CAAC,CAAC,EAAE,KAAK,CAAA;CAAE,CAAA;AAE1E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,QAOjB,CAAA;AAEf;;;;;yCAKyC;AACzC,eAAO,MAAM,gBAAgB,OAAO,CAAA"}

package/dist/internal/runtime-contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-contract.js","sourceRoot":"","sources":["../../src/internal/runtime-contract.ts"],"names":[],"mappings":"AA0BA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAC9B,mEAAmE;IACnE,kEAAkE;IAClE,yEAAyE;IACzE,6EAA6E;IAC7E,iCAAiC;IACjC,qFAAqF;IACrF,aAAa,CAAA;AAEf;;;;;yCAKyC;AACzC,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAA"}
+{"version":3,"file":"runtime-contract.js","sourceRoot":"","sources":["../../src/internal/runtime-contract.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAC9B,mEAAmE;IACnE,kEAAkE;IAClE,yEAAyE;IACzE,6EAA6E;IAC7E,iCAAiC;IACjC,qFAAqF;IACrF,aAAa,CAAA;AAEf;;;;;yCAKyC;AACzC,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAA"}

package/dist/internal/secret-scan.d.ts

@@ -0,0 +1,104 @@
+import type { ClientModuleGraph } from "../module-graph.js";
+import type { ZoneClassifier } from "../zones.js";
+import type { ModuleSource } from "./zone-graph.js";
+export type SecretRule = 
+/** A PEM private key block. */
+"private-key"
+/** A URL carrying a password: `postgres://user:password@host`. */
+ | "credential-url"
+/** A known secret token format: AWS, Stripe secret keys, GitHub, Slack, OpenAI, Anthropic, ... */
+ | "key-format"
+/** A high-entropy string literal assigned to a secret-like name. Source files only. */
+ | "assigned-secret"
+/** The value of a non-public build environment variable, raw or URL, base64, JSON or HTML encoded. */
+ | "private-env-value";
+/**
+ * One reviewed false positive. It names the rule, where the finding is and why it may ship: there is
+ * no exemption by value, so a credential that turns up somewhere else still fails the build.
+ */
+export interface SecretExemption {
+    readonly rule: SecretRule;
+    /** The finding's file as reported: app-relative for a source or `public/` file, output-relative for
+     * an emitted file. */
+    readonly file?: string;
+    /** For `private-env-value`: the variable whose value may ship. */
+    readonly env?: string;
+    readonly reason: string;
+}
+export interface SecretFinding {
+    readonly rule: SecretRule;
+    /** The source module the match came from when it is known, else the published file. */
+    readonly file: string;
+    readonly line: number;
+    /** The published file the match is in, when {@link file} names the module it came from. */
+    readonly via?: string;
+    /** What matched, never the value: `"AWS access key id"`, `"value of DATABASE_URL (base64)"`. */
+    readonly what: string;
+    /** The first characters and the length, enough to recognize a key without publishing it. */
+    readonly preview: string;
+}
+/** A module bundled into a published file. */
+export interface SecretOrigin {
+    /** As a finding names it: app-relative, or `node_modules/<package>/...`. */
+    readonly name: string;
+    readonly path: string;
+}
+export interface SecretScanFile {
+    /** Where the file is, as a finding should name it. */
+    readonly name: string;
+    readonly text: string;
+    /** A first-party source file: the assigned-secret rule applies. */
+    readonly firstParty?: boolean;
+    /** For an emitted bundle: the modules in it, so a finding names the one a match came from (a
+     * content-hashed file name is no place for an exemption). */
+    readonly origins?: readonly SecretOrigin[];
+}
+export interface SecretScanInput {
+    /** Source modules the browser build loaded, scanned before minification. */
+    readonly sources?: readonly SecretScanFile[];
+    /** Files that will be served: emitted bundles, maps, `public/` copies, prerendered pages. */
+    readonly artifacts?: readonly SecretScanFile[];
+    /** The build environment whose non-public values must not ship (default: none). */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** The public-env prefix (default `"PUBLIC_"`); prefixed variables are public by declaration. */
+    readonly publicEnvPrefix?: string;
+    readonly exemptions?: readonly SecretExemption[];
+}
+/** Refuse an exemption that does not name its rule, its location and its reason. */
+export declare function assertSecretExemptions(exemptions: readonly SecretExemption[]): void;
+/**
+ * Scan what a build publishes. Sources are scanned first: a match there is reported at its source
+ * location, and the same text in an emitted file (where names are hashed) is not reported again,
+ * exempted or not.
+ */
+export declare function scanForSecrets(input: SecretScanInput): SecretFinding[];
+/**
+ * A scrubber for text a dev tool hands to a person or an agent: logs, error messages, stacks,
+ * codeframes. Broader than the build scan because a log line is not a published artifact: every JWT
+ * (a session token is a credential), an `Authorization`/`Cookie` value, and every non-public env
+ * value in each encoding the build scan matches. Each hit becomes `[redacted:<what>]`.
+ */
+export declare function createRedactor(env: Readonly<Record<string, string | undefined>>, publicEnvPrefix?: string): (text: string) => string;
+/** The build environment: Bun's, else Node's. */
+export declare const buildEnvironment: () => Readonly<Record<string, string | undefined>>;
+/** Scan and throw the build-failing message on any finding. */
+export declare function assertNoSecrets(input: SecretScanInput): void;
+/** The build-failing message for secret findings, or `undefined` when there are none. */
+export declare function formatSecretFindings(findings: readonly SecretFinding[]): string | undefined;
+/** A published file's text, or `undefined` for a binary one (a NUL byte in its first 8 KB). */
+export declare function textOf(bytes: Uint8Array): string | undefined;
+/** An emitted bundle, plus its inline source map decoded: base64 would hide a key from every rule. */
+export declare function emittedScanFiles(name: string, text: string, origins?: readonly SecretOrigin[]): SecretScanFile[];
+/** How a finding names a module: app-relative inside the app, from `node_modules/` for a package. */
+export declare function originName(appRoot: string, file: string): string;
+/**
+ * The scan's view of a client graph: the first-party browser modules as sources, and for each emitted
+ * file (by basename) the modules bundled into it.
+ */
+export declare function graphScanInput(graph: ClientModuleGraph, sourceOf: (id: string) => ModuleSource, classifier: ZoneClassifier): {
+    sources: SecretScanFile[];
+    originsOf: (outputName: string) => SecretOrigin[];
+};
+/** Every file under a `public/` directory, named as the app sees it (`public/robots.txt`). */
+export declare function publicScanFiles(dir: string, label: string): SecretScanFile[];
+//# sourceMappingURL=secret-scan.d.ts.map

package/dist/internal/secret-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-scan.d.ts","sourceRoot":"","sources":["../../src/internal/secret-scan.ts"],"names":[],"mappings":"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"}