@fuzdev/fuz_app 0.144.0 → 0.146.0

package/dist/server/serve_fact_route.js

@@ -20,7 +20,8 @@
  * `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.
+ * `internal;` and carries the fact hardening headers, so X-Accel serving can't
+ * be enabled against a public or header-less location.
  *
  * REST, not RPC: binary responses don't fit the JSON-RPC envelope.
  *
@@ -69,14 +70,18 @@
  *
  * Auth shape on the cell-scoped route is `{account: 'none', actor: 'none'}`
  * — the dispatcher's authorization phase is skipped for pure-public routes,
- * so the handler builds the `RequestContext` itself from `c.var.account_id`
- * (populated by the `/api/*` session middleware) by resolving the caller's
- * single actor and loading their role_grants. Unauthed callers pass through
- * with `req_ctx: null` and are admitted only by a `cell.visibility ===
- * 'public'` cell whose `moderation` admits an audience (unmoderated or
+ * so the handler builds the `RequestContext` itself from the resolved account
+ * id (`get_public_account_id`, over what the `/api/*` auth middleware set) by
+ * resolving the caller's single actor and loading their role_grants.
+ * Unauthed callers pass through with `req_ctx: null` and are admitted only by
+ * a `cell.visibility === 'public'` cell whose `moderation` admits an audience (unmoderated or
  * `'approved'`). Multi-actor accounts fall through with `req_ctx: null`
  * — there's no `acting?` slot on a pure-public route, so multi-actor
- * callers are treated as anonymous.
+ * callers are treated as anonymous. A scope-narrowed API token is treated as
+ * anonymous too, not refused (`get_public_account_id`): a narrowed token
+ * reaches no non-RPC surface, but on a route that admits anonymous callers
+ * a 403 would enforce nothing — the holder drops the `Authorization` header and
+ * re-reads every public cell anyway.
  *
  * 404 is the universal "not viewable" response: missing fact, missing or
  * unviewable cell, or the cell doesn't reference the hash. We deliberately
@@ -96,8 +101,13 @@
  * from executing as stored XSS for any reader of a referencing cell, **every**
  * served-fact response carries `X-Content-Type-Options: nosniff` +
  * `Content-Security-Policy: default-src 'none'; sandbox` (the
- * `FACT_SECURITY_HEADERS` set, applied in all three serve branches). The same
- * pair, byte-identical, is set by the Rust twin (`fuz_fact_serving::serve`).
+ * `FACT_SECURITY_HEADERS` set from `server/fact_security_headers.ts`,
+ * byte-identical with the Rust twin `fuz_fact_serving`). The embedded and
+ * disk-stream branches set them on the response. On the `X-Accel-Redirect`
+ * branch nginx serves the bytes, and the headers the client sees come from the
+ * internal facts location, not this response — that location must carry the
+ * lines `fact_security_header_directives` renders, which `create_x_accel_config`
+ * enforces.
  * `Content-Disposition: attachment` is deliberately **not** added — it would
  * force-download and break legitimate inline image rendering.
  *
@@ -118,10 +128,9 @@ import { Readable } from 'node:stream';
 import { join } from 'node:path';
 import { FactHashSchema, Uuid } from '../primitive_schemas.js';
 import { z } from 'zod';
-import { build_request_context, get_request_context, has_scoped_role } from '../auth/request_context.js';
+import { build_request_context, get_public_account_id, get_request_context, has_scoped_role } from '../auth/request_context.js';
 import { ROLE_ADMIN } from '../auth/role_schema.js';
 import { ActingActor } from '../http/auth_shape.js';
-import { ACCOUNT_ID_KEY } from '../hono_context.js';
 import { query_active_actors_by_account } from '../auth/account_queries.js';
 import { get_route_params } from '../http/route_spec.js';
 import { ERROR_INVALID_ROUTE_PARAMS } from '../http/error_schemas.js';
@@ -131,33 +140,7 @@ import { query_cell_grant_list_for_cell } from '../db/cell_grant_queries.js';
 import { can_view_cell } from '../auth/cell_authorize.js';
 import { cell_steward_admits } from '../auth/cell_steward.js';
 import { parse_file_fact_url } from '../db/file_fact_url.js';
-/** `Cache-Control` for fact responses — 5 min revocation window. */
-const CACHE_CONTROL = 'private, max-age=300';
-/**
- * `X-Content-Type-Options` for fact responses — block MIME sniffing so an
- * `application/octet-stream` fact can't be sniffed into executable HTML.
- */
-const X_CONTENT_TYPE_OPTIONS = 'nosniff';
-/**
- * `Content-Security-Policy` for fact responses. Fact bytes carry a
- * producer-supplied `content_type` served verbatim inline, so a fact stored as
- * (or sniffable to) `text/html` would otherwise execute as stored XSS for any
- * reader of a referencing cell. `default-src 'none'; sandbox` neutralizes
- * script execution and sub-resource loads even when a fact is rendered inline;
- * harmless for directly-served images (they load no sub-resources). The same
- * pair, byte-identical, is set by the Rust twin (`fuz_fact_serving::serve`).
- */
-const CONTENT_SECURITY_POLICY = "default-src 'none'; sandbox";
-/**
- * The untrusted-content hardening headers applied to every served-fact
- * response across all three branches (embedded, `X-Accel-Redirect`,
- * disk-stream). `Content-Disposition: attachment` is deliberately omitted — it
- * would force-download and break legitimate inline image rendering.
- */
-const FACT_SECURITY_HEADERS = {
-    'X-Content-Type-Options': X_CONTENT_TYPE_OPTIONS,
-    'Content-Security-Policy': CONTENT_SECURITY_POLICY
-};
+import { FACT_CACHE_CONTROL, FACT_SECURITY_HEADERS } from './fact_security_headers.js';
 /**
  * Path-param schema for the bare-hash route. Matching the canonical
  * fact-hash form here pushes malformed-hash 400s through the framework's
@@ -220,7 +203,7 @@ const serve_fact_bytes = async (c, route, hash, config) => {
         return c.body(bytes, 200, {
             'Content-Type': content_type,
             'Content-Length': size,
-            'Cache-Control': CACHE_CONTROL,
+            'Cache-Control': FACT_CACHE_CONTROL,
             ...FACT_SECURITY_HEADERS
         });
     }
@@ -234,10 +217,12 @@ const serve_fact_bytes = async (c, route, hash, config) => {
     const { shard, rest } = parsed;
     if (x_accel !== undefined) {
         // Production: hand off to nginx via the validated `internal;` facts location.
+        // nginx answers with that location's own `add_header` set, not these
+        // headers, which is why the validator requires the fact pair there.
         return c.body(null, 200, {
             'Content-Type': content_type,
             'Content-Length': size,
-            'Cache-Control': CACHE_CONTROL,
+            'Cache-Control': FACT_CACHE_CONTROL,
             'X-Accel-Redirect': `${x_accel.redirect_prefix}${shard}/${rest}`,
             ...FACT_SECURITY_HEADERS
         });
@@ -250,22 +235,27 @@ const serve_fact_bytes = async (c, route, hash, config) => {
     return c.body(web_stream, 200, {
         'Content-Type': content_type,
         'Content-Length': size,
-        'Cache-Control': CACHE_CONTROL,
+        'Cache-Control': FACT_CACHE_CONTROL,
         ...FACT_SECURITY_HEADERS
     });
 };
 /**
  * Resolve the caller's `RequestContext` on a pure-public route from the
- * session-middleware-set account id. Multi-actor accounts return `null`
- * (no `acting?` slot on a public route to disambiguate); single active-actor
- * accounts resolve their actor and role_grants for owner / grant / admin
- * admission paths. Unauthenticated callers return `null`. Soft-deleted
- * (tombstoned) actors are excluded from the count
- * (`query_active_actors_by_account`), matching the acting-actor resolution
- * path — a tombstoned actor is never resolvable here.
+ * session-middleware-set account id, read through `get_public_account_id`, so
+ * a scope-narrowed API token returns `null` — downgraded to anonymous, not
+ * refused (see the module doc). Twin of the Rust
+ * `AuthGate::public_request_context`.
+ *
+ * Multi-actor accounts return `null` (no `acting?` slot on a public route to
+ * disambiguate); single active-actor accounts resolve their actor and
+ * role_grants for owner / grant / admin admission paths. Unauthenticated
+ * callers return `null`. Soft-deleted (tombstoned) actors are excluded from the
+ * count (`query_active_actors_by_account`), matching the acting-actor
+ * resolution path — a tombstoned actor is never resolvable here.
  */
 const build_public_request_context = async (c, route) => {
-    const account_id = c.get(ACCOUNT_ID_KEY);
+    // a narrowed token is the anonymous caller here, never a refusal
+    const account_id = get_public_account_id(c);
     if (!account_id)
         return null;
     const actors = await query_active_actors_by_account({ db: route.db }, account_id);
@@ -284,7 +274,8 @@ const build_public_request_context = async (c, route) => {
  * `(cell, hash)` edge — never unioned across the fact's other referrers.
  *
  * Pure-public auth — the handler builds the per-request `RequestContext`
- * from `c.var.account_id` and enforces visibility per-reference.
+ * from the resolved account id (`get_public_account_id`) and enforces
+ * visibility per-reference.
  */
 export const create_serve_cell_fact_route_spec = (options) => {
     const { facts_dir, x_accel, log } = options;

package/dist/server/x_accel.d.ts

@@ -5,37 +5,139 @@
  * 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.
+ * cell-visibility check. A location with its own `add_header` also stops the
+ * server-level headers from applying, so the facts location must carry the fact
+ * hardening headers itself (`fact_security_header_directives` in
+ * `server/fact_security_headers.ts`).
  *
- * 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. This is the only nginx property
- * fuz_app validates; there is no general config validator.
+ * `XAccelConfig` makes these assertions structural: a consumer can only obtain
+ * the redirect prefix by building an `XAccelConfig`, which runs
+ * `validate_facts_internal_location` and throws **loudly** on any violation — it
+ * cannot silently fall closed.
+ *
+ * ## Rules
+ *
+ * The config is tokenized as nginx reads it (`ngx_conf_read_token`): whitespace
+ * is exactly space, tab, CR and LF; an unquoted word ends only at those or at
+ * `;` / `{` (a `}` inside a word is part of it, and so is a `{` straight after
+ * `$`); `#` starts a comment only where a token would start; quoted strings are
+ * one word, with nginx's backslash escapes. It is then parsed into nested
+ * blocks, and every `location` at any depth, in every `server` block, is
+ * classified against the prefix (trailing slashes ignored). A location *serves
+ * the prefix* when it is a prefix-type location (no modifier, or `^~`) whose
+ * path is the prefix or below it. Each one must:
+ *
+ * - use `^~` — a plain prefix location is refused;
+ * - be a direct child of a `server` block — one nested in another location is
+ *   refused;
+ * - carry, as top-level directives of its own body, an exact `internal;` and
+ *   each `fact_security_header_directives` line (token-equal: whitespace and
+ *   quoting are free, the words are not);
+ * - set those headers with no other `add_header` — one naming a
+ *   `FACT_SECURITY_HEADERS` header (ASCII case-insensitive) that is not
+ *   token-equal to its required line is refused, since nginx sends both values
+ *   and a client may read only the first (`sniff, nosniff`);
+ * - hold only simple directives — any nested block (`location`, `if`,
+ *   `limit_except`, …) is refused, and so is `include`, since included files
+ *   are not followed.
+ *
+ * The first two rules are what keep regex locations out: nginx never evaluates
+ * regex locations for a path whose longest prefix match is a `^~` location at
+ * server level, and because every prefix location at or below the prefix must
+ * be such a location, the longest match for any redirected path always is. (A
+ * longer plain location below the prefix can't exist — the `^~` rule refuses
+ * it.)
+ *
+ * The prefix may appear only in its own location lines and their bodies:
+ * `internal;` admits every internal redirect and subrequest, so any other
+ * directive with a word naming the prefix (trailing slash trimmed, so
+ * `/_facts$uri` counts) is refused, in any block at any depth — a `rewrite`,
+ * `try_files`, `error_page`, `index`, `add_before_body`, or a `set` / `map`
+ * value that a redirect later reads. The only exemptions are each `location`'s
+ * own modifier and path words and the bodies of the locations serving the
+ * prefix.
+ *
+ * The prefix itself must be an absolute path ending in exactly one `/` — the
+ * server appends `<shard>/<rest>` straight onto it, so `/_facts` would redirect
+ * to `/_factsab/…`, outside the validated location. At least one location
+ * serving the prefix must sit exactly at it (`/_facts` or `/_facts/`): one only
+ * below it (`location ^~ /_facts/00/`) leaves every other redirect path to
+ * whatever location matches next, and nginx compares location paths
+ * byte-for-byte, so `/_facts//` sits below it too.
+ *
+ * Module directives that undo those guarantees are refused too:
+ *
+ * - `ssi` with any value but `off`, anywhere in the config. SSI `include
+ *   virtual` is a subrequest, which `internal;` admits, so an SSI-processed
+ *   response — a fact inheriting `ssi on` from `http` or `server`, or any page
+ *   carrying user content — could include another fact's bytes.
+ * - `more_set_headers` / `more_clear_headers` (headers-more) everywhere except
+ *   inside a `location` that doesn't serve the prefix (or a block within one):
+ *   they run after `add_header` and can strip the hardening headers, so they
+ *   are refused in the facts location and at every level above it, including
+ *   any block there (`if`, another `server`).
+ *
+ * Also refused: an `=` location on the prefix or below it (it can't serve the
+ * nested paths the redirect emits); a regex location (`~` / `~*`) whose pattern
+ * spells out the prefix (after unescaping `\/`, ASCII case-folded for `~*`) —
+ * dead under the rules above, refused for the clearer message; a config with no
+ * location at the prefix; and blocks nested more than 64 deep (a parse error, so
+ * the walks can't exhaust the stack). `include` at server level is allowed, but
+ * its file is not read — keep facts-related locations and the directives above
+ * out of included files.
+ *
+ * The threat model is operator mistakes, not an adversarial config author: the
+ * prefix check is textual, so a value assembled from pieces (`/_fac$1`) evades
+ * it. Beyond the config text:
+ *
+ * - The validator checks URL paths only — another `root` or `alias` that maps
+ *   onto the facts directory would serve its files publicly, so keep the facts
+ *   directory outside every other location's root.
+ * - nginx honours `X-Accel-Redirect` from any proxied upstream (`proxy_pass`,
+ *   `fastcgi_pass`, `uwsgi_pass`, `scgi_pass`, `grpc_pass`), so every upstream in
+ *   the server is trusted to point into the prefix; an untrusted one needs
+ *   `proxy_ignore_headers X-Accel-Redirect;` (or the `fastcgi_` / `uwsgi_` /
+ *   `scgi_` equivalent).
+ * - Other module code can redirect internally too (njs `internalRedirect`, perl,
+ *   echo), or strip the hardening headers as headers-more can (njs
+ *   `js_header_filter`, lua-nginx-module `header_filter_by_lua*`), and the
+ *   check sees none of it, so run trusted modules and content only.
+ *
+ * The Rust twin is `fuz_fact_serving`'s `nginx.rs`, held to the same rules and
+ * the same fixture corpus.
+ *
+ * @example
+ * ```ts
+ * const x_accel = create_x_accel_config(
+ * 	'/_facts/',
+ * 	`server {
+ * 	location ^~ /_facts/ {
+ * 		internal;
+ * 		alias /srv/app/facts/;
+ * 		${fact_security_header_directives().join('\n\t\t')}
+ * 	}
+ * }`
+ * );
+ * ```
  *
  * @module
  */
 import { z } from 'zod';
 /** Result of the facts-location check. */
 export interface NginxFactsValidation {
-    /** `true` when the facts location exists and is `internal;`. */
+    /** `true` when every rule passes. */
     ok: boolean;
-    /** Fatal issues — a missing or non-`internal` facts location. */
+    /** Fatal issues, each naming the offending 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.
+ * Assert the nginx config serves the X-Accel facts prefix only from `internal;`
+ * locations carrying the fact hardening headers. See the module docs for the
+ * rules; every violation is collected, so one call reports them all.
  *
- * @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;`
+ * @param config - the nginx config string to check
+ * @param facts_location - the facts location path the redirect prefix points at (e.g. `/_facts/`)
+ * @returns `{ok, errors}` — `ok` is `true` only when every rule passes
  */
 export declare const validate_facts_internal_location: (config: string, facts_location: string) => NginxFactsValidation;
 /**
@@ -44,10 +146,11 @@ export declare const validate_facts_internal_location: (config: string, facts_lo
  *
  * 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.
+ * X-Accel serving is impossible to enable without proving at boot that the
+ * facts location is `internal;` and carries the fact hardening headers — 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<{
     redirect_prefix: z.ZodString;
@@ -63,18 +166,19 @@ export declare class XAccelConfigError extends Error {
     constructor(errors: Array<string>);
 }
 /**
- * Build a validated `XAccelConfig`, asserting the nginx `location` serving
- * `redirect_prefix` is `internal;`.
+ * Build a validated `XAccelConfig`, asserting the nginx config serves
+ * `redirect_prefix` only from safe locations (the module-level rules).
  *
  * The make-impossible-states gate: serving can only emit `X-Accel-Redirect`
- * into a location proven `internal;` at boot.
+ * into a location proven `internal;` and header-carrying at boot.
  *
- * @param redirect_prefix - the X-Accel redirect prefix (e.g. `/_facts/`)
- * @param nginx_config - the nginx config template string to validate against
+ * @param redirect_prefix - the X-Accel redirect prefix, ending in `/` (e.g. `/_facts/`)
+ * @param nginx_config - the nginx config 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.
+ * @throws `XAccelConfigError` carrying every violation
+ *   `validate_facts_internal_location` finds — a prefix not ending in `/`, a
+ *   missing, public, header-less, re-headered, exact-match, or regex-shadowed
+ *   facts location, or `ssi` / headers-more reaching it.
  */
 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

@@ -1 +1 @@
-{"version":3,"file":"x_accel.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/x_accel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,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;;0CAKF,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"}
+{"version":3,"file":"x_accel.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/x_accel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2HG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,0CAA0C;AAC1C,MAAM,WAAW,oBAAoB;IACpC,qCAAqC;IACrC,EAAE,EAAE,OAAO,CAAC;IACZ,wDAAwD;IACxD,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,gCAAgC,GAC5C,QAAQ,MAAM,EACd,gBAAgB,MAAM,KACpB,oBAYF,CAAC;AA+IF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY;;0CAKF,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;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,GACjC,iBAAiB,MAAM,EACvB,cAAc,MAAM,KAClB,YAMF,CAAC"}