@fuzdev/fuz_app 0.144.0 → 0.145.0

package/dist/server/x_accel.d.ts

@@ -5,37 +5,112 @@
  * 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);
+ * - 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.
+ *
+ * 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; and a config
+ * with no location serving the prefix. `include` at server level is allowed,
+ * but its file is not read — keep facts-related locations 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).
+ * - Module code can redirect internally too (ssi `include virtual`, njs
+ *   `internalRedirect`, perl, echo), 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 +119,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 +139,18 @@ 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 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 missing, public, header-less,
+ *   exact-match, or regex-shadowed facts location.
  */
 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;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;AAsHF;;;;;;;;;;;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;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,GACjC,iBAAiB,MAAM,EACvB,cAAc,MAAM,KAClB,YAMF,CAAC"}