@fuzdev/fuz_app 0.99.0 → 0.100.0

package/dist/server/serve_fact_route.d.ts

@@ -14,8 +14,11 @@
  * (filesystem-backed `file:<shard>/<rest>` URLs) either return an
  * `X-Accel-Redirect` header pointing into nginx's internal facts location
  * (production) or stream from disk via the filesystem `FactExternalFetcher`
- * (dev / tests). The runtime mode is selected by the optional
- * `x_accel_redirect_prefix` factory option — set in prod, unset in dev.
+ * (dev / tests). The runtime mode is selected by the optional `x_accel`
+ * factory option — a validated `XAccelConfig` (built via
+ * `create_x_accel_config` in `server/x_accel.ts`) set in prod, unset in dev.
+ * The handle can only be obtained by proving the facts nginx location is
+ * `internal;`, so X-Accel serving can't be enabled against a public location.
  *
  * REST, not RPC: binary responses don't fit the JSON-RPC envelope.
  *
@@ -87,6 +90,7 @@
 import type { Logger } from '@fuzdev/fuz_util/log.ts';
 import { type RouteSpec } from '../http/route_spec.js';
 import type { AppDeps } from '../auth/deps.js';
+import type { XAccelConfig } from './x_accel.js';
 export interface CreateServeFactRouteSpecOptions {
     /**
      * App deps reference. Currently unused at handler time (cell + fact
@@ -100,12 +104,13 @@ export interface CreateServeFactRouteSpecOptions {
     facts_dir: string;
     /**
      * When set, external facts return an `X-Accel-Redirect` pointing at
-     * `${prefix}<shard>/<rest>` — nginx's internal facts location serves
-     * the bytes. When unset, external facts stream from
-     * `<facts_dir>/<shard>/<rest>` directly. Production sets this (e.g.
-     * `/_facts/`); tests + dev leave it unset.
+     * `${x_accel.redirect_prefix}<shard>/<rest>` — nginx's internal facts
+     * location serves the bytes. When unset, external facts stream from
+     * `<facts_dir>/<shard>/<rest>` directly. Production sets a validated
+     * `XAccelConfig` (built via `create_x_accel_config`, which proves the
+     * facts location is `internal;`); tests + dev leave it unset.
      */
-    x_accel_redirect_prefix?: string;
+    x_accel?: XAccelConfig;
     log: Logger;
 }
 /**

package/dist/server/serve_fact_route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve_fact_route.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/serve_fact_route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AAMH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAepD,OAAO,EAAsC,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAE1F,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,iBAAiB,CAAC;AAkE7C,MAAM,WAAW,+BAA+B;IAC/C;;;;;;OAMG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,GAAG,EAAE,MAAM,CAAC;CACZ;AAgHD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,GAC7C,SAAS,+BAA+B,KACtC,SA8CF,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,+BAA+B,KACtC,SAgCF,CAAC"}
+{"version":3,"file":"serve_fact_route.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/serve_fact_route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AAMH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAepD,OAAO,EAAsC,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAE1F,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,iBAAiB,CAAC;AAM7C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,cAAc,CAAC;AA6D/C,MAAM,WAAW,+BAA+B;IAC/C;;;;;;OAMG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;CACZ;AAgHD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,GAC7C,SAAS,+BAA+B,KACtC,SA8CF,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,+BAA+B,KACtC,SAgCF,CAAC"}

package/dist/server/serve_fact_route.js

@@ -14,8 +14,11 @@
  * (filesystem-backed `file:<shard>/<rest>` URLs) either return an
  * `X-Accel-Redirect` header pointing into nginx's internal facts location
  * (production) or stream from disk via the filesystem `FactExternalFetcher`
- * (dev / tests). The runtime mode is selected by the optional
- * `x_accel_redirect_prefix` factory option — set in prod, unset in dev.
+ * (dev / tests). The runtime mode is selected by the optional `x_accel`
+ * factory option — a validated `XAccelConfig` (built via
+ * `create_x_accel_config` in `server/x_accel.ts`) set in prod, unset in dev.
+ * The handle can only be obtained by proving the facts nginx location is
+ * `internal;`, so X-Accel serving can't be enabled against a public location.
  *
  * REST, not RPC: binary responses don't fit the JSON-RPC envelope.
  *
@@ -167,7 +170,7 @@ const params_400_error = {
  * fact is genuinely absent or merely unviewable.
  */
 const serve_fact_bytes = async (c, route, hash, config) => {
-    const { facts_dir, x_accel_redirect_prefix, log } = config;
+    const { facts_dir, x_accel, log } = config;
     const meta = await query_get_fact_meta({ db: route.db }, hash);
     if (!meta) {
         return c.body(null, 404);
@@ -198,13 +201,13 @@ const serve_fact_bytes = async (c, route, hash, config) => {
         return c.body(null, 404);
     }
     const { shard, rest } = parsed;
-    if (x_accel_redirect_prefix !== undefined) {
-        // Production: hand off to nginx via the internal facts location.
+    if (x_accel !== undefined) {
+        // Production: hand off to nginx via the validated `internal;` facts location.
         return c.body(null, 200, {
             'Content-Type': content_type,
             'Content-Length': size,
             'Cache-Control': CACHE_CONTROL,
-            'X-Accel-Redirect': `${x_accel_redirect_prefix}${shard}/${rest}`,
+            'X-Accel-Redirect': `${x_accel.redirect_prefix}${shard}/${rest}`,
             ...FACT_SECURITY_HEADERS,
         });
     }
@@ -252,8 +255,8 @@ const build_public_request_context = async (c, route) => {
  * from `c.var.account_id` and enforces visibility per-reference.
  */
 export const create_serve_cell_fact_route_spec = (options) => {
-    const { facts_dir, x_accel_redirect_prefix, log } = options;
-    const config = { facts_dir, x_accel_redirect_prefix, log };
+    const { facts_dir, x_accel, log } = options;
+    const config = { facts_dir, x_accel, log };
     return {
         method: 'GET',
         path: '/api/cells/:cell_id/facts/:hash',
@@ -310,8 +313,8 @@ export const create_serve_cell_fact_route_spec = (options) => {
  * hash to a non-admin.
  */
 export const create_serve_fact_route_spec = (options) => {
-    const { facts_dir, x_accel_redirect_prefix, log } = options;
-    const config = { facts_dir, x_accel_redirect_prefix, log };
+    const { facts_dir, x_accel, log } = options;
+    const config = { facts_dir, x_accel, log };
     return {
         method: 'GET',
         path: '/api/facts/:hash',

package/dist/server/x_accel.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Fail-loud validation of the X-Accel facts nginx location.
+ *
+ * The `X-Accel-Redirect` serving path's confidentiality depends on the facts
+ * nginx location being `internal;` — only the authz'd handler's redirect (an
+ * internal subrequest) may reach it. A *public* facts location would serve any
+ * fact's bytes to anyone who guesses the `<shard>/<rest>` path, bypassing every
+ * cell-visibility check. `XAccelConfig` makes that assertion structural: a
+ * consumer can only obtain the redirect prefix by building an `XAccelConfig`,
+ * which runs this check and throws **loudly** on a missing or non-`internal;`
+ * location — it cannot silently fall closed.
+ *
+ * This is a best-effort string check (brace-matched `location` blocks), the TS
+ * twin of the Rust `fuz_fact_serving` `nginx.rs` — not a real nginx parser, but
+ * it catches the security-critical omission. Distinct from
+ * `validate_nginx_config` (`server/validate_nginx.ts`), which validates the
+ * `/api` Authorization-strip + security headers and takes no facts-location
+ * path.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Result of the facts-location check. */
+export interface NginxFactsValidation {
+    /** `true` when the facts location exists and is `internal;`. */
+    ok: boolean;
+    /** Fatal issues — a missing or non-`internal` facts location. */
+    errors: Array<string>;
+}
+/**
+ * Assert the nginx `location` serving the X-Accel facts prefix is `internal;`.
+ *
+ * `facts_location` is the path the X-Accel redirect prefix points at (e.g.
+ * `/_facts/`). Returns a fatal error when no matching `location` block exists,
+ * or when the matching block is not marked `internal;` — either is a public
+ * facts location that bypasses cell visibility.
+ *
+ * @param config - the nginx config template string to check
+ * @param facts_location - the facts location path the redirect prefix points at
+ * @returns `{ok, errors}` — `ok` is `true` only when the location exists and is `internal;`
+ */
+export declare const validate_facts_internal_location: (config: string, facts_location: string) => NginxFactsValidation;
+/**
+ * A validated X-Accel redirect configuration — the only handle that enables the
+ * `X-Accel-Redirect` serving path in `server/serve_fact_route.ts`.
+ *
+ * The redirect prefix can be obtained **only** by passing the nginx config
+ * through `validate_facts_internal_location` (via `create_x_accel_config`), so
+ * X-Accel serving is impossible to enable without proving the facts location is
+ * `internal;` at boot — a public facts location would bypass every
+ * cell-visibility check. A Zod-branded type: the brand can't be forged without
+ * an explicit cast, so the factory is the only ordinary construction path.
+ */
+export declare const XAccelConfig: z.core.$ZodBranded<z.ZodObject<{
+    /** The validated redirect prefix the serving path prepends (e.g. `/_facts/`). */
+    redirect_prefix: z.ZodString;
+}, z.core.$strict>, "XAccelConfig", "out">;
+export type XAccelConfig = z.infer<typeof XAccelConfig>;
+/**
+ * A misconfigured X-Accel facts location — a fail-loud boot error thrown by
+ * `create_x_accel_config`.
+ */
+export declare class XAccelConfigError extends Error {
+    /** The validator errors that made the location unsafe. */
+    readonly errors: Array<string>;
+    constructor(errors: Array<string>);
+}
+/**
+ * Build a validated `XAccelConfig`, asserting the nginx `location` serving
+ * `redirect_prefix` is `internal;`.
+ *
+ * The make-impossible-states gate: serving can only emit `X-Accel-Redirect`
+ * into a location proven `internal;` at boot.
+ *
+ * @param redirect_prefix - the X-Accel redirect prefix (e.g. `/_facts/`)
+ * @param nginx_config - the nginx config template string to validate against
+ * @returns the validated `XAccelConfig` carrying `redirect_prefix`
+ * @throws `XAccelConfigError` when `nginx_config` has no matching `location` for
+ *   `redirect_prefix`, or the matching block is not marked `internal;` — either
+ *   is a public facts location that bypasses every cell-visibility check.
+ */
+export declare const create_x_accel_config: (redirect_prefix: string, nginx_config: string) => XAccelConfig;
+//# sourceMappingURL=x_accel.d.ts.map

package/dist/server/x_accel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x_accel.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/x_accel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,0CAA0C;AAC1C,MAAM,WAAW,oBAAoB;IACpC,gEAAgE;IAChE,EAAE,EAAE,OAAO,CAAC;IACZ,iEAAiE;IACjE,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACtB;AAuDD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gCAAgC,GAC5C,QAAQ,MAAM,EACd,gBAAgB,MAAM,KACpB,oBAqBF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY;IAEvB,iFAAiF;;0CAG5D,CAAC;AACxB,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC3C,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;gBACnB,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC;CAKjC;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,GACjC,iBAAiB,MAAM,EACvB,cAAc,MAAM,KAClB,YAMF,CAAC"}

package/dist/server/x_accel.js

@@ -0,0 +1,148 @@
+/**
+ * Fail-loud validation of the X-Accel facts nginx location.
+ *
+ * The `X-Accel-Redirect` serving path's confidentiality depends on the facts
+ * nginx location being `internal;` — only the authz'd handler's redirect (an
+ * internal subrequest) may reach it. A *public* facts location would serve any
+ * fact's bytes to anyone who guesses the `<shard>/<rest>` path, bypassing every
+ * cell-visibility check. `XAccelConfig` makes that assertion structural: a
+ * consumer can only obtain the redirect prefix by building an `XAccelConfig`,
+ * which runs this check and throws **loudly** on a missing or non-`internal;`
+ * location — it cannot silently fall closed.
+ *
+ * This is a best-effort string check (brace-matched `location` blocks), the TS
+ * twin of the Rust `fuz_fact_serving` `nginx.rs` — not a real nginx parser, but
+ * it catches the security-critical omission. Distinct from
+ * `validate_nginx_config` (`server/validate_nginx.ts`), which validates the
+ * `/api` Authorization-strip + security headers and takes no facts-location
+ * path.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Strip every trailing `/` so `/_facts/` and `/_facts` compare equal. */
+const trim_trailing_slashes = (value) => value.replace(/\/+$/, '');
+/** `true` if a location block body contains an `internal` directive. */
+const is_internal = (content) => content.split(/[;\s]+/).some((token) => token === 'internal');
+/**
+ * Extract `{path, content}` for each `location … { … }` block, brace-matched so
+ * nested blocks are kept whole. `path` is the last whitespace token before the
+ * opening brace (the location path, after any modifier). Best-effort: a stray
+ * `location` token in a comment can produce a spurious block, harmless for this
+ * check.
+ */
+const find_location_blocks = (config) => {
+    const blocks = [];
+    let search = 0;
+    let kw;
+    while ((kw = config.indexOf('location', search)) !== -1) {
+        // Require a token boundary before `location` (start or whitespace) so
+        // `relocation` etc. don't match.
+        const boundary_ok = kw === 0 || /\s/.test(config[kw - 1]);
+        const after = kw + 'location'.length;
+        const brace = config.indexOf('{', after);
+        if (brace === -1)
+            break;
+        if (!boundary_ok) {
+            search = after;
+            continue;
+        }
+        const header = config.slice(after, brace).trim();
+        const tokens = header.split(/\s+/).filter((token) => token.length > 0);
+        const path = tokens.length > 0 ? tokens[tokens.length - 1] : '';
+        // Brace-match the body.
+        let depth = 1;
+        let i = brace + 1;
+        while (i < config.length && depth > 0) {
+            const ch = config[i];
+            if (ch === '{')
+                depth++;
+            else if (ch === '}')
+                depth--;
+            i++;
+        }
+        blocks.push({ path, content: config.slice(brace, i) });
+        search = i;
+    }
+    return blocks;
+};
+/**
+ * Assert the nginx `location` serving the X-Accel facts prefix is `internal;`.
+ *
+ * `facts_location` is the path the X-Accel redirect prefix points at (e.g.
+ * `/_facts/`). Returns a fatal error when no matching `location` block exists,
+ * or when the matching block is not marked `internal;` — either is a public
+ * facts location that bypasses cell visibility.
+ *
+ * @param config - the nginx config template string to check
+ * @param facts_location - the facts location path the redirect prefix points at
+ * @returns `{ok, errors}` — `ok` is `true` only when the location exists and is `internal;`
+ */
+export const validate_facts_internal_location = (config, facts_location) => {
+    const errors = [];
+    const normalized = trim_trailing_slashes(facts_location);
+    const blocks = find_location_blocks(config);
+    const matching = blocks.filter((block) => trim_trailing_slashes(block.path) === normalized);
+    if (matching.length === 0) {
+        errors.push(`No nginx \`location ${facts_location}\` block found — the X-Accel facts location must ` +
+            `exist and be marked \`internal;\` so only the authz'd handler's redirect can reach it. ` +
+            `A public facts location bypasses every cell-visibility check.`);
+    }
+    else if (!matching.some((block) => is_internal(block.content))) {
+        errors.push(`nginx \`location ${facts_location}\` is NOT marked \`internal;\` — a public facts ` +
+            `location serves any fact's bytes to anyone who guesses the path, bypassing every ` +
+            `cell-visibility check. Add \`internal;\` to the block.`);
+    }
+    return { ok: errors.length === 0, errors };
+};
+/**
+ * A validated X-Accel redirect configuration — the only handle that enables the
+ * `X-Accel-Redirect` serving path in `server/serve_fact_route.ts`.
+ *
+ * The redirect prefix can be obtained **only** by passing the nginx config
+ * through `validate_facts_internal_location` (via `create_x_accel_config`), so
+ * X-Accel serving is impossible to enable without proving the facts location is
+ * `internal;` at boot — a public facts location would bypass every
+ * cell-visibility check. A Zod-branded type: the brand can't be forged without
+ * an explicit cast, so the factory is the only ordinary construction path.
+ */
+export const XAccelConfig = z
+    .strictObject({
+    /** The validated redirect prefix the serving path prepends (e.g. `/_facts/`). */
+    redirect_prefix: z.string(),
+})
+    .brand('XAccelConfig');
+/**
+ * A misconfigured X-Accel facts location — a fail-loud boot error thrown by
+ * `create_x_accel_config`.
+ */
+export class XAccelConfigError extends Error {
+    /** The validator errors that made the location unsafe. */
+    errors;
+    constructor(errors) {
+        super(`X-Accel facts location is not safely \`internal;\`: ${errors.join('; ')}`);
+        this.name = 'XAccelConfigError';
+        this.errors = errors;
+    }
+}
+/**
+ * Build a validated `XAccelConfig`, asserting the nginx `location` serving
+ * `redirect_prefix` is `internal;`.
+ *
+ * The make-impossible-states gate: serving can only emit `X-Accel-Redirect`
+ * into a location proven `internal;` at boot.
+ *
+ * @param redirect_prefix - the X-Accel redirect prefix (e.g. `/_facts/`)
+ * @param nginx_config - the nginx config template string to validate against
+ * @returns the validated `XAccelConfig` carrying `redirect_prefix`
+ * @throws `XAccelConfigError` when `nginx_config` has no matching `location` for
+ *   `redirect_prefix`, or the matching block is not marked `internal;` — either
+ *   is a public facts location that bypasses every cell-visibility check.
+ */
+export const create_x_accel_config = (redirect_prefix, nginx_config) => {
+    const validation = validate_facts_internal_location(nginx_config, redirect_prefix);
+    if (!validation.ok) {
+        throw new XAccelConfigError(validation.errors);
+    }
+    return XAccelConfig.parse({ redirect_prefix });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.99.0",
+  "version": "0.100.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",