@fuzdev/fuz_app 0.146.0 → 0.147.0

package/dist/db/fact_disk_storage.js

@@ -20,14 +20,15 @@
  * re-hashing it (`server/serve_fact_route.ts`). This twins the Rust `fuz_fact`
  * §fsync posture: data-sync before the rename; the parent-dir fsync stays
  * deliberately waived (a lost dirent is regenerable under content addressing).
- * If the final path already exists the temp is dropped instead of renamed over
- * — idempotent dedup (same hash → byte-identical content), mirroring the Rust
- * commit path. `.tmp/` is a sibling of `<shard>/` under the same `facts_dir` so
- * `rename` is always same-filesystem (no EXDEV).
+ * The temp is renamed over the final path even when a file is already there:
+ * the temp's bytes are the ones just hashed, so the rename is a no-op for a
+ * sound file and replaces a corrupt one (a torn write, bit rot) with bytes that
+ * match their name — a re-upload heals the CAS. `.tmp/` is a sibling of
+ * `<shard>/` under the same `facts_dir` so `rename` is always same-filesystem
+ * (no EXDEV).
  *
  * @module
  */
-import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { Blake3Hasher } from '@fuzdev/blake3-wasm';
 import { to_error_message } from '@fuzdev/fuz_util/error.ts';
@@ -42,12 +43,11 @@ export const FACT_TMP_DIRNAME = '.tmp';
 /** Default age (1 hour) past which a `.tmp/*` file is considered orphaned. */
 export const FACT_TMP_ORPHAN_MAX_AGE_MS = 60 * 60 * 1000;
 /**
- * Stream `source` to storage with bounded memory: hash BLAKE3 + SHA-256
- * incrementally in one pass, buffer in memory until the bytes cross
- * `embedded_threshold`, then spill the buffer + remaining chunks through a temp
- * file and atomically land it in the disk CAS. Peak heap is
- * `O(chunk + embedded_threshold)`, never `O(artifact)`, so a multi-GB upload
- * never buffers in RAM.
+ * Stream `source` to storage with bounded memory: hash BLAKE3 incrementally,
+ * buffer in memory until the bytes cross `embedded_threshold`, then spill the
+ * buffer + remaining chunks through a temp file and atomically land it in the
+ * disk CAS. Peak heap is `O(chunk + embedded_threshold)`, never `O(artifact)`, so a
+ * multi-GB upload never buffers in RAM.
  *
  * - **Embedded vs disk.** A body `<= embedded_threshold` stays in memory and is
  *   returned as `{kind: 'embedded'}` for the PG `bytes` column. Above it (with a
@@ -66,7 +66,6 @@ export const FACT_TMP_ORPHAN_MAX_AGE_MS = 60 * 60 * 1000;
 export const stream_fact_to_disk = async (deps, facts_dir, source, max_bytes, embedded_threshold) => {
     await blake3_ready;
     const blake3 = new Blake3Hasher();
-    const sha256 = createHash('sha256');
     let size = 0;
     // Buffer leading bytes until they cross the embedded threshold; small facts
     // stay embedded (no disk), large ones never buffer past the threshold.
@@ -78,7 +77,6 @@ export const stream_fact_to_disk = async (deps, facts_dir, source, max_bytes, em
         if (size > max_bytes)
             throw new FactPayloadTooLargeError(size, max_bytes);
         blake3.update(chunk);
-        sha256.update(chunk);
     };
     try {
         // Phase 1: read + hash + buffer until the threshold is crossed or the
@@ -103,7 +101,6 @@ export const stream_fact_to_disk = async (deps, facts_dir, source, max_bytes, em
             const hash = (FACT_HASH_PREFIX + to_hex(blake3.finalize()));
             return {
                 hash,
-                sha256: sha256.digest('hex'),
                 size,
                 placement: { kind: 'embedded', bytes: concat_chunks(buffered, buffered_len) }
             };
@@ -161,7 +158,6 @@ export const stream_fact_to_disk = async (deps, facts_dir, source, max_bytes, em
         const { shard, rest } = await commit_temp_to_cas(deps, tmp_path, facts_dir, hash);
         return {
             hash,
-            sha256: sha256.digest('hex'),
             size,
             placement: { kind: 'disk', external_url: mint_file_fact_url(shard, rest) }
         };
@@ -179,7 +175,7 @@ export const stream_fact_to_disk = async (deps, facts_dir, source, max_bytes, em
 /**
  * Write fully-buffered `bytes` for `hash` to the canonical
  * `<facts_dir>/<shard>/<rest>` path, then publish via `commit_temp_to_cas`
- * (fsync'd temp + atomic rename, dedup-aware). The buffering twin of
+ * (fsync'd temp + atomic rename). The buffering twin of
  * `stream_fact_to_disk`, used by `PgFactStore.put` for oversize sync bytes.
  * Returns the `file:` `external_url` for the `fact` row.
  *
@@ -271,11 +267,14 @@ export const sweep_orphan_temps = async (deps, facts_dir, options) => {
  * Publish a written temp file into the CAS at `<facts_dir>/<shard>/<rest>`:
  * `fsync` the temp's data (durability before the rename — the serve path streams
  * the file without re-hashing, so the bytes must be stable before they become
- * the canonical body), then either drop the temp (byte-identical content already
- * present — idempotent dedup) or atomically `rename` it into place. On any
- * failure the temp is unlinked and an `ENOSPC` is surfaced as `FactStorageFullError`.
- * The single commit path shared by both writers above — twins the Rust `fuz_fact`
- * `SpillFile::rename_into_cas` (data-sync before rename; parent-dir fsync waived).
+ * the canonical body), then atomically `rename` it into place, over a file
+ * already there. The temp holds the bytes `hash` was computed from, so
+ * replacing an existing file is harmless when it is sound and heals it when it
+ * is not; a reader holding the old file open keeps reading the old inode. On
+ * any failure the temp is unlinked and an `ENOSPC` is surfaced as
+ * `FactStorageFullError`. The single commit path shared by both writers above
+ * (data-sync before rename; parent-dir fsync waived, as on the Rust `fuz_fact`
+ * disk CAS).
  *
  * @mutates `facts_dir` filesystem
  */
@@ -284,13 +283,8 @@ const commit_temp_to_cas = async (deps, tmp_path, facts_dir, hash) => {
     const final_path = join(facts_dir, shard, rest);
     try {
         await deps.fsync(tmp_path);
-        if (await deps.stat(final_path)) {
-            await deps.remove(tmp_path).catch(() => undefined);
-        }
-        else {
-            await deps.mkdir(join(facts_dir, shard), { recursive: true });
-            await deps.rename(tmp_path, final_path);
-        }
+        await deps.mkdir(join(facts_dir, shard), { recursive: true });
+        await deps.rename(tmp_path, final_path);
     }
     catch (err) {
         await deps.remove(tmp_path).catch(() => undefined);

package/dist/db/fact_queries.d.ts

@@ -5,9 +5,8 @@
  * idempotent (`ON CONFLICT DO NOTHING`) so the same hash can be written by
  * two callers without the second observing an error.
  *
- * Higher-level lifecycle (verify-on-read, JSON ref auto-extraction,
- * embedded-vs-referenced selection) lives in `db/fact_store.ts`. Queries
- * here are deliberately mechanical.
+ * Higher-level lifecycle (verify-on-read, embedded-vs-referenced selection)
+ * lives in `db/fact_store.ts`. Queries here are deliberately mechanical.
  *
  * @module
  */

package/dist/db/fact_queries.d.ts.map

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

package/dist/db/fact_queries.js

@@ -5,9 +5,8 @@
  * idempotent (`ON CONFLICT DO NOTHING`) so the same hash can be written by
  * two callers without the second observing an error.
  *
- * Higher-level lifecycle (verify-on-read, JSON ref auto-extraction,
- * embedded-vs-referenced selection) lives in `db/fact_store.ts`. Queries
- * here are deliberately mechanical.
+ * Higher-level lifecycle (verify-on-read, embedded-vs-referenced selection)
+ * lives in `db/fact_store.ts`. Queries here are deliberately mechanical.
  *
  * @module
  */

package/dist/db/fact_store.d.ts

@@ -6,8 +6,8 @@
  *
  * - sync hash on `put`; `put_stream` hashes as it streams
  * - idempotent insert (`ON CONFLICT DO NOTHING` in the queries layer)
- * - JSON ref auto-extraction when `content_type` signals JSON and the
- *   caller didn't pass an explicit `refs` array
+ * - refs are exactly the caller's `options.refs` — the bytes are never
+ *   scanned for hashes, whatever the `content_type`
  * - verify-on-read for disk-backed content; embedded reads skip verify
  *   because PG storage IS the hash table
  * - mismatched disk bytes return `null` + log warning (treat as
@@ -17,10 +17,10 @@
  * land in the PG `bytes` column; larger bytes go to the disk CAS at
  * `<facts_dir>/<shard>/<rest>` (`db/fact_disk_storage.ts`) and the row records a
  * `file:<shard>/<rest>` `external_url`. `put` takes fully-buffered bytes;
- * `put_stream` is the bounded-memory streaming twin (hash BLAKE3 + SHA-256 in
- * one pass, spill past the threshold, enforce `max_bytes` / `ENOSPC`). `put`
- * needs `disk_root` + `fs` (the `runtime/*Deps`) for the over-threshold path
- * only: without them the store has nowhere to put bytes it cannot embed, and an
+ * `put_stream` is the bounded-memory streaming twin (hash BLAKE3 as it streams,
+ * spill past the threshold, enforce `max_bytes` / `ENOSPC`). `put` needs
+ * `disk_root` + `fs` (the `runtime/*Deps`) for the over-threshold path only:
+ * without them the store has nowhere to put bytes it cannot embed, and an
  * oversize `put` throws. `put_stream` needs `fs` for a body of any size — with
  * none it throws before reading the stream — and `disk_root` for the
  * over-threshold spill: with none, a body that passes the threshold throws
@@ -31,7 +31,9 @@
  * — the store makes no network request. The column is free text
  * (`query_put_fact` inserts what it is given), so `get` treats a row whose
  * `external_url` has any other shape, and any external row on a store with no
- * disk CAS configured, as unavailable: a warning and `null`.
+ * disk CAS configured, as unavailable: a warning and `null`. A `file:` URL
+ * naming another fact's file (`file_fact_url_addresses`) is refused the same
+ * way, logged as an error, before the file is read.
  *
  * ## Holders
  *
@@ -133,24 +135,23 @@ export declare class PgFactStore implements HeldFactStore {
      * are configured) at `<facts_dir>/<shard>/<rest>` with a `file:` URL. Oversize
      * without a disk root throws: the store has nowhere to put bytes it cannot
      * embed. Idempotent — `ON CONFLICT DO NOTHING` + content-addressed disk
-     * filenames make a re-write a no-op. `options.holder`, when set, is recorded
-     * as a holder on a fresh insert and a dedup hit alike.
+     * filenames make a re-write harmless (it renames verified bytes over the same
+     * file). Refs are exactly `options.refs` (none when omitted). `options.holder`,
+     * when set, is recorded as a holder on a fresh insert and a dedup hit alike.
      *
      * @mutates fact_holder - records `options.holder` (when non-null) in the transaction that writes the `fact` row
      */
     put(bytes: Uint8Array, options: HeldFactPutOptions): Promise<FactHash>;
     /**
-     * Stream bytes into the store with bounded memory, returning the finalized
-     * digests + size. Delegates the byte path to `stream_fact_to_disk` (hash
-     * BLAKE3 + SHA-256 in one pass, buffer to the embedded threshold, spill to the
-     * disk CAS), then inserts the `fact` row by placement — embedded bytes go to
-     * the PG `bytes` column, disk-spilled bytes record the `file:` `external_url`.
+     * Stream bytes into the store with bounded memory, returning the fact hash +
+     * size. Delegates the byte path to `stream_fact_to_disk` (hash BLAKE3 as it
+     * streams, buffer to the embedded threshold, spill to the disk CAS), then
+     * inserts the `fact` row by placement — embedded bytes go to the PG `bytes`
+     * column, disk-spilled bytes record the `file:` `external_url`.
      * The cap is enforced mid-stream (`FactPayloadTooLargeError`); a disk-full mid-
      * stream throws `FactStorageFullError`.
      *
-     * Refs: explicit `options.refs` are recorded; JSON auto-extraction is NOT
-     * attempted (it would need a buffered re-read, defeating the bounded-memory
-     * contract) — streamed uploads are opaque blobs.
+     * Refs are exactly `options.refs` (none when omitted), as on `put`.
      *
      * Requires `fs` (and, for the over-threshold spill, `disk_root`) to be
      * configured. The streaming twin of `put`; mirrors the Rust
@@ -167,7 +168,8 @@ export declare class PgFactStore implements HeldFactStore {
      * Returns `null`, with a warning log, for an external row the store cannot
      * serve — an `external_url` that is not a `file:<shard>/<rest>` URL, no disk
      * CAS configured (`disk_root` + `fs`), a failed disk read, or bytes that
-     * don't match the hash. Never makes a network request.
+     * don't match the hash — and, with an error log, for a URL that names
+     * another fact's file. Never makes a network request.
      */
     get(hash: FactHash): Promise<Uint8Array | null>;
     has(hash: FactHash): Promise<boolean>;

package/dist/db/fact_store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fact_store.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/fact_store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAOtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,KAAK,EACX,QAAQ,EACR,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,MAAM,gCAAgC,CAAC;AAcxC,OAAO,EAIN,KAAK,mBAAmB,EACxB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACzD,MAAM,EAAE,IAAI,GAAG,IAAI,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,SAAS,EAAE,KAAK,GAAG,YAAY,CAAC;IAC3E;;;OAGG;IACH,GAAG,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3E;;;OAGG;IACH,UAAU,EAAE,CACX,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kBAAkB,KACvB,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC/B;AAED,qDAAqD;AACrD,eAAO,MAAM,+BAA+B,QAAc,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,mBAAmB,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,qBAAa,WAAY,YAAW,aAAa;;gBAOpC,OAAO,EAAE,eAAe;IAQpC;;;;;;;;;;OAUG;IACG,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAgC5E;;;;;;;;;;;;;;;;;;OAkBG;IACG,UAAU,CACf,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kBAAkB,GACzB,OAAO,CAAC,gBAAgB,CAAC;IA+C5B;;;;;;;;;OASG;IACG,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IA0C/C,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrC,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAWlD,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAIxD;;;;;;;;;;;;;;;;;;OAkBG;IACG,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CAG3F"}
+{"version":3,"file":"fact_store.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/fact_store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,KAAK,EACX,QAAQ,EACR,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,MAAM,gCAAgC,CAAC;AAcxC,OAAO,EAIN,KAAK,mBAAmB,EACxB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACzD,MAAM,EAAE,IAAI,GAAG,IAAI,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,SAAS,EAAE,KAAK,GAAG,YAAY,CAAC;IAC3E;;;OAGG;IACH,GAAG,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3E;;;OAGG;IACH,UAAU,EAAE,CACX,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kBAAkB,KACvB,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC/B;AAED,qDAAqD;AACrD,eAAO,MAAM,+BAA+B,QAAc,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,mBAAmB,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,qBAAa,WAAY,YAAW,aAAa;;gBAOpC,OAAO,EAAE,eAAe;IAQpC;;;;;;;;;;;OAWG;IACG,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAgC5E;;;;;;;;;;;;;;;;OAgBG;IACG,UAAU,CACf,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kBAAkB,GACzB,OAAO,CAAC,gBAAgB,CAAC;IA+C5B;;;;;;;;;;OAUG;IACG,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAiD/C,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrC,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAWlD,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAIxD;;;;;;;;;;;;;;;;;;OAkBG;IACG,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CAG3F"}

package/dist/db/fact_store.js

@@ -6,8 +6,8 @@
  *
  * - sync hash on `put`; `put_stream` hashes as it streams
  * - idempotent insert (`ON CONFLICT DO NOTHING` in the queries layer)
- * - JSON ref auto-extraction when `content_type` signals JSON and the
- *   caller didn't pass an explicit `refs` array
+ * - refs are exactly the caller's `options.refs` — the bytes are never
+ *   scanned for hashes, whatever the `content_type`
  * - verify-on-read for disk-backed content; embedded reads skip verify
  *   because PG storage IS the hash table
  * - mismatched disk bytes return `null` + log warning (treat as
@@ -17,10 +17,10 @@
  * land in the PG `bytes` column; larger bytes go to the disk CAS at
  * `<facts_dir>/<shard>/<rest>` (`db/fact_disk_storage.ts`) and the row records a
  * `file:<shard>/<rest>` `external_url`. `put` takes fully-buffered bytes;
- * `put_stream` is the bounded-memory streaming twin (hash BLAKE3 + SHA-256 in
- * one pass, spill past the threshold, enforce `max_bytes` / `ENOSPC`). `put`
- * needs `disk_root` + `fs` (the `runtime/*Deps`) for the over-threshold path
- * only: without them the store has nowhere to put bytes it cannot embed, and an
+ * `put_stream` is the bounded-memory streaming twin (hash BLAKE3 as it streams,
+ * spill past the threshold, enforce `max_bytes` / `ENOSPC`). `put` needs
+ * `disk_root` + `fs` (the `runtime/*Deps`) for the over-threshold path only:
+ * without them the store has nowhere to put bytes it cannot embed, and an
  * oversize `put` throws. `put_stream` needs `fs` for a body of any size — with
  * none it throws before reading the stream — and `disk_root` for the
  * over-threshold spill: with none, a body that passes the threshold throws
@@ -31,7 +31,9 @@
  * — the store makes no network request. The column is free text
  * (`query_put_fact` inserts what it is given), so `get` treats a row whose
  * `external_url` has any other shape, and any external row on a store with no
- * disk CAS configured, as unavailable: a warning and `null`.
+ * disk CAS configured, as unavailable: a warning and `null`. A `file:` URL
+ * naming another fact's file (`file_fact_url_addresses`) is refused the same
+ * way, logged as an error, before the file is read.
  *
  * ## Holders
  *
@@ -48,10 +50,10 @@
  * @module
  */
 import { to_error_message } from '@fuzdev/fuz_util/error.ts';
-import { fact_hash_bytes, fact_hash_verify, fact_hash_extract_refs } from '@fuzdev/fuz_util/fact_hash.ts';
+import { fact_hash_bytes, fact_hash_verify } from '@fuzdev/fuz_util/fact_hash.ts';
 import { query_delete_fact, query_get_fact, query_get_fact_meta, query_get_fact_refs, query_has_fact, query_put_fact, query_put_fact_refs } from './fact_queries.js';
 import { query_put_fact_holder } from './fact_holder_queries.js';
-import { is_file_fact_url } from './file_fact_url.js';
+import { file_fact_url_addresses, parse_file_fact_url } from './file_fact_url.js';
 import { read_fact_bytes_from_disk, stream_fact_to_disk, write_fact_bytes_to_disk } from './fact_disk_storage.js';
 /** Default embedded-vs-referenced cutoff (1 MiB). */
 export const FACT_EMBEDDED_THRESHOLD_DEFAULT = 1024 * 1024;
@@ -79,8 +81,9 @@ export class PgFactStore {
      * are configured) at `<facts_dir>/<shard>/<rest>` with a `file:` URL. Oversize
      * without a disk root throws: the store has nowhere to put bytes it cannot
      * embed. Idempotent — `ON CONFLICT DO NOTHING` + content-addressed disk
-     * filenames make a re-write a no-op. `options.holder`, when set, is recorded
-     * as a holder on a fresh insert and a dedup hit alike.
+     * filenames make a re-write harmless (it renames verified bytes over the same
+     * file). Refs are exactly `options.refs` (none when omitted). `options.holder`,
+     * when set, is recorded as a holder on a fresh insert and a dedup hit alike.
      *
      * @mutates fact_holder - records `options.holder` (when non-null) in the transaction that writes the `fact` row
      */
@@ -105,21 +108,19 @@ export class PgFactStore {
             external_url: row_external_url,
             content_type: options.content_type ?? null,
             size: bytes.length
-        }, resolve_refs(bytes, options), options.holder);
+        }, options.refs ?? [], options.holder);
         return hash;
     }
     /**
-     * Stream bytes into the store with bounded memory, returning the finalized
-     * digests + size. Delegates the byte path to `stream_fact_to_disk` (hash
-     * BLAKE3 + SHA-256 in one pass, buffer to the embedded threshold, spill to the
-     * disk CAS), then inserts the `fact` row by placement — embedded bytes go to
-     * the PG `bytes` column, disk-spilled bytes record the `file:` `external_url`.
+     * Stream bytes into the store with bounded memory, returning the fact hash +
+     * size. Delegates the byte path to `stream_fact_to_disk` (hash BLAKE3 as it
+     * streams, buffer to the embedded threshold, spill to the disk CAS), then
+     * inserts the `fact` row by placement — embedded bytes go to the PG `bytes`
+     * column, disk-spilled bytes record the `file:` `external_url`.
      * The cap is enforced mid-stream (`FactPayloadTooLargeError`); a disk-full mid-
      * stream throws `FactStorageFullError`.
      *
-     * Refs: explicit `options.refs` are recorded; JSON auto-extraction is NOT
-     * attempted (it would need a buffered re-read, defeating the bounded-memory
-     * contract) — streamed uploads are opaque blobs.
+     * Refs are exactly `options.refs` (none when omitted), as on `put`.
      *
      * Requires `fs` (and, for the over-threshold spill, `disk_root`) to be
      * configured. The streaming twin of `put`; mirrors the Rust
@@ -141,7 +142,7 @@ export class PgFactStore {
             content_type: options.content_type ?? null,
             size: streamed.size
         }, options.refs ?? [], options.holder);
-        return { hash: streamed.hash, sha256: streamed.sha256, size: streamed.size };
+        return { hash: streamed.hash, size: streamed.size };
     }
     /**
      * Insert the `fact` row, then — in the same transaction — its refs (fresh
@@ -167,7 +168,8 @@ export class PgFactStore {
      * Returns `null`, with a warning log, for an external row the store cannot
      * serve — an `external_url` that is not a `file:<shard>/<rest>` URL, no disk
      * CAS configured (`disk_root` + `fs`), a failed disk read, or bytes that
-     * don't match the hash. Never makes a network request.
+     * don't match the hash — and, with an error log, for a URL that names
+     * another fact's file. Never makes a network request.
      */
     async get(hash) {
         const row = await query_get_fact(this.#deps, hash);
@@ -181,10 +183,15 @@ export class PgFactStore {
         }
         // the URL is not echoed — the column is free text, so its shape and
         // length are whatever the row's writer chose
-        if (!is_file_fact_url(row.external_url)) {
+        const parsed = parse_file_fact_url(row.external_url);
+        if (!parsed) {
             this.#log?.warn(`PgFactStore.get external_url for ${hash} is not a file:<shard>/<rest> URL; treating as not-found`);
             return null;
         }
+        if (!file_fact_url_addresses(parsed, hash)) {
+            this.#log?.error(`PgFactStore.get external_url for ${hash} addresses another fact's file; treating as not-found`);
+            return null;
+        }
         if (this.#disk_root === undefined || this.#fs === undefined) {
             this.#log?.warn(`PgFactStore.get ${hash} is disk-backed and no disk CAS is configured (disk_root + fs); treating as not-found`);
             return null;
@@ -243,27 +250,6 @@ export class PgFactStore {
         return query_delete_fact(this.#deps, hash);
     }
 }
-/**
- * Resolve refs for a `put` call: explicit `refs` win; otherwise auto-extract
- * from JSON content; otherwise no refs.
- */
-const resolve_refs = (bytes, options) => {
-    if (options.refs !== undefined)
-        return options.refs;
-    if (options.content_type !== 'application/json')
-        return [];
-    let value;
-    try {
-        value = JSON.parse(new TextDecoder().decode(bytes));
-    }
-    catch {
-        // Malformed JSON — caller mislabeled content_type. Fall back to no refs;
-        // the alternative (throwing) would surprise callers who set
-        // content_type advisorially.
-        return [];
-    }
-    return fact_hash_extract_refs(value);
-};
 /**
  * Coerce whatever the driver returns for BYTEA into a `Uint8Array`.
  *

package/dist/db/file_fact_url.d.ts

@@ -11,9 +11,11 @@
  *
  * Centralizing the regex + the `fact_disk_path` split keeps the shape in one
  * place: `PgFactStore`'s disk CAS (`db/fact_disk_storage.ts`), the
- * `serve_fact_route` defense-in-depth check, and the disk read
+ * `serve_fact_route` defense-in-depth checks (shape, then
+ * `file_fact_url_addresses`), and the disk read
  * (`read_fact_bytes_from_disk`) all derive the layout here, so the write path
- * and the read path can't drift. The TS twin of the Rust `fact_disk_path` (`fuz_fact`).
+ * and the read path can't drift. The TS twin of the Rust `fact_disk_path`
+ * (`fuz_fact`).
  *
  * Defense-in-depth: a `..` segment can't match (`.` isn't in `[0-9a-f]`),
  * neither can absolute paths, query strings, or any non-hex character.
@@ -33,8 +35,6 @@ export declare const FILE_FACT_URL_PATTERN: RegExp;
  */
 export declare const FileFactUrl: z.core.$ZodBranded<z.ZodString, "FileFactUrl", "out">;
 export type FileFactUrl = z.infer<typeof FileFactUrl>;
-/** Type guard. Useful when discriminating a `string | null` column. */
-export declare const is_file_fact_url: (s: string) => s is FileFactUrl;
 /**
  * Split a `FactHash` into its on-disk `<shard>/<rest>` parts — the first 2
  * hex chars of the digest (shard subdir) + the remaining 62. The single
@@ -56,6 +56,21 @@ export declare const parse_file_fact_url: (url: string) => {
     shard: string;
     rest: string;
 } | null;
+/**
+ * Whether a parsed `file:<shard>/<rest>` URL is the disk address of `hash` —
+ * `shard` + `rest` is its hex.
+ *
+ * The shape check (`parse_file_fact_url`) says a URL is safe to join onto the
+ * facts directory; this says it names `hash`'s own file. A reader checks both
+ * before it serves the file as `hash`'s bytes: a row whose `external_url` names
+ * another fact's file would otherwise serve those bytes under this hash, past
+ * this hash's admission. Twin of the Rust `ParsedFactUrl::addresses`
+ * (`fuz_fact`).
+ */
+export declare const file_fact_url_addresses: (parsed: {
+    shard: string;
+    rest: string;
+}, hash: FactHash) => boolean;
 /**
  * Construct a canonical `file:<shard>/<rest>` URL. The writer side
  * (`db/fact_disk_storage.ts`) assembles the shape from a freshly-computed

package/dist/db/file_fact_url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file_fact_url.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/file_fact_url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,iEAAiE;AACjE,eAAO,MAAM,qBAAqB,QAAyC,CAAC;AAE5E;;;;GAIG;AACH,eAAO,MAAM,WAAW,uDAA+D,CAAC;AACxF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,GAAI,GAAG,MAAM,KAAG,CAAC,IAAI,WAA4C,CAAC;AAE/F;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,QAAQ,KAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAG5E,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC/B,KAAK,MAAM,KACT;IAAE,GAAG,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAItD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,EAAE,MAAM,MAAM,KAAG,WAC1B,CAAC"}
+{"version":3,"file":"file_fact_url.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/file_fact_url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,iEAAiE;AACjE,eAAO,MAAM,qBAAqB,QAAyC,CAAC;AAE5E;;;;GAIG;AACH,eAAO,MAAM,WAAW,uDAA+D,CAAC;AACxF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,QAAQ,KAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAG5E,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC/B,KAAK,MAAM,KACT;IAAE,GAAG,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAItD,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,GACnC,QAAQ;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACvC,MAAM,QAAQ,KACZ,OAGF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,EAAE,MAAM,MAAM,KAAG,WAC1B,CAAC"}

package/dist/db/file_fact_url.js

@@ -11,9 +11,11 @@
  *
  * Centralizing the regex + the `fact_disk_path` split keeps the shape in one
  * place: `PgFactStore`'s disk CAS (`db/fact_disk_storage.ts`), the
- * `serve_fact_route` defense-in-depth check, and the disk read
+ * `serve_fact_route` defense-in-depth checks (shape, then
+ * `file_fact_url_addresses`), and the disk read
  * (`read_fact_bytes_from_disk`) all derive the layout here, so the write path
- * and the read path can't drift. The TS twin of the Rust `fact_disk_path` (`fuz_fact`).
+ * and the read path can't drift. The TS twin of the Rust `fact_disk_path`
+ * (`fuz_fact`).
  *
  * Defense-in-depth: a `..` segment can't match (`.` isn't in `[0-9a-f]`),
  * neither can absolute paths, query strings, or any non-hex character.
@@ -32,8 +34,6 @@ export const FILE_FACT_URL_PATTERN = /^file:([0-9a-f]{2})\/([0-9a-f]{62})$/;
  * string literals don't satisfy the brand.
  */
 export const FileFactUrl = z.string().regex(FILE_FACT_URL_PATTERN).brand('FileFactUrl');
-/** Type guard. Useful when discriminating a `string | null` column. */
-export const is_file_fact_url = (s) => FILE_FACT_URL_PATTERN.test(s);
 /**
  * Split a `FactHash` into its on-disk `<shard>/<rest>` parts — the first 2
  * hex chars of the digest (shard subdir) + the remaining 62. The single
@@ -56,6 +56,21 @@ export const parse_file_fact_url = (url) => {
         return null;
     return { url: url, shard: m[1], rest: m[2] };
 };
+/**
+ * Whether a parsed `file:<shard>/<rest>` URL is the disk address of `hash` —
+ * `shard` + `rest` is its hex.
+ *
+ * The shape check (`parse_file_fact_url`) says a URL is safe to join onto the
+ * facts directory; this says it names `hash`'s own file. A reader checks both
+ * before it serves the file as `hash`'s bytes: a row whose `external_url` names
+ * another fact's file would otherwise serve those bytes under this hash, past
+ * this hash's admission. Twin of the Rust `ParsedFactUrl::addresses`
+ * (`fuz_fact`).
+ */
+export const file_fact_url_addresses = (parsed, hash) => {
+    const { shard, rest } = fact_disk_path(hash);
+    return parsed.shard === shard && parsed.rest === rest;
+};
 /**
  * Construct a canonical `file:<shard>/<rest>` URL. The writer side
  * (`db/fact_disk_storage.ts`) assembles the shape from a freshly-computed

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

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAA4B,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAG5E;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;kBAqDxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,wBAAwB,GAAG,qBAAqB,CAAC;IACxD,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACtB;AAED,MAAM,MAAM,sBAAsB,GAAG,gBAAgB,GAAG,qBAAqB,CAAC;AAE9E;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,aAAa,KAAG,sBAmBxD,CAAC"}
+{"version":3,"file":"env.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAkB,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAGlE;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;kBAqDxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,wBAAwB,GAAG,qBAAqB,CAAC;IACxD,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACtB;AAED,MAAM,MAAM,sBAAsB,GAAG,gBAAgB,GAAG,qBAAqB,CAAC;AAE9E;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,aAAa,KAAG,sBAmBxD,CAAC"}

package/dist/server/env.js

@@ -9,7 +9,7 @@
  * @module
  */
 import { z } from 'zod';
-import { create_validated_keyring } from '../auth/keyring.js';
+import { create_keyring } from '../auth/keyring.js';
 import { format_allowed_origins_error, parse_allowed_origins } from '../http/origin.js';
 /**
  * Base Zod schema for server environment variables.
@@ -83,7 +83,7 @@ export const BaseServerEnv = z.strictObject({
  * @returns `{ok: true, keyring, allowed_origins, bootstrap_token_path}` or `{ok: false, field, errors}`
  */
 export const validate_server_env = (env) => {
-    const keyring_result = create_validated_keyring(env.SECRET_FUZ_COOKIE_KEYS);
+    const keyring_result = create_keyring(env.SECRET_FUZ_COOKIE_KEYS);
     if (!keyring_result.ok) {
         return { ok: false, field: 'SECRET_FUZ_COOKIE_KEYS', errors: keyring_result.errors };
     }

package/dist/server/serve_fact_route.d.ts

@@ -113,13 +113,17 @@
  *
  * ## Defense-in-depth
  *
- * `external_url` is re-validated against the `file:<shard>/<rest>` shape
- * before it addresses the filesystem or an `X-Accel-Redirect`. `PgFactStore`
- * writes only that shape, but the column is free text and `query_put_fact`
+ * `external_url` is re-validated before it addresses the filesystem or an
+ * `X-Accel-Redirect`: it must have the `file:<shard>/<rest>` shape, and it must
+ * be the requested hash's own address (`file_fact_url_addresses`). `PgFactStore`
+ * writes only such URLs, but the column is free text and `query_put_fact`
  * inserts what it is given, so a row written past the store — or a
  * row-injection bug upstream — would otherwise hand nginx an
- * attacker-controlled path. Any other shape is a logged 404, the same
- * unavailable that `PgFactStore.get` reports for it as `null`.
+ * attacker-controlled path, or serve another fact's bytes under this hash,
+ * behind this hash's admission. The serve path never re-hashes what it
+ * streams, so this binding is what ties the bytes to the name. Either refusal
+ * is a logged error and the masked 404, the same unavailable that
+ * `PgFactStore.get` reports as `null`. Twin of the Rust `fuz_fact_serving`.
  *
  * @module
  */

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4HG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAetD,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAO/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAoCjD,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;AAyHD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iCAAiC,GAC7C,SAAS,+BAA+B,KACtC,SAuDF,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,+BAA+B,KACtC,SA2CF,CAAC"}
+{"version":3,"file":"serve_fact_route.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/serve_fact_route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgIG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAetD,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAO/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAoCjD,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;AA6HD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iCAAiC,GAC7C,SAAS,+BAA+B,KACtC,SAuDF,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,+BAA+B,KACtC,SA2CF,CAAC"}

package/dist/server/serve_fact_route.js

@@ -113,13 +113,17 @@
  *
  * ## Defense-in-depth
  *
- * `external_url` is re-validated against the `file:<shard>/<rest>` shape
- * before it addresses the filesystem or an `X-Accel-Redirect`. `PgFactStore`
- * writes only that shape, but the column is free text and `query_put_fact`
+ * `external_url` is re-validated before it addresses the filesystem or an
+ * `X-Accel-Redirect`: it must have the `file:<shard>/<rest>` shape, and it must
+ * be the requested hash's own address (`file_fact_url_addresses`). `PgFactStore`
+ * writes only such URLs, but the column is free text and `query_put_fact`
  * inserts what it is given, so a row written past the store — or a
  * row-injection bug upstream — would otherwise hand nginx an
- * attacker-controlled path. Any other shape is a logged 404, the same
- * unavailable that `PgFactStore.get` reports for it as `null`.
+ * attacker-controlled path, or serve another fact's bytes under this hash,
+ * behind this hash's admission. The serve path never re-hashes what it
+ * streams, so this binding is what ties the bytes to the name. Either refusal
+ * is a logged error and the masked 404, the same unavailable that
+ * `PgFactStore.get` reports as `null`. Twin of the Rust `fuz_fact_serving`.
  *
  * @module
  */
@@ -139,7 +143,7 @@ import { query_cell_get } from '../db/cell_queries.js';
 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';
+import { file_fact_url_addresses, parse_file_fact_url } from '../db/file_fact_url.js';
 import { FACT_CACHE_CONTROL, FACT_SECURITY_HEADERS } from './fact_security_headers.js';
 /**
  * Path-param schema for the bare-hash route. Matching the canonical
@@ -208,12 +212,16 @@ const serve_fact_bytes = async (c, route, hash, config) => {
         });
     }
     // External — defense-in-depth re-validate the URL before trusting it
-    // to address the filesystem.
+    // to address the filesystem: its shape, then that it is this hash's file
     const parsed = parse_file_fact_url(meta.external_url);
     if (!parsed) {
         log.error(`serve_fact: external_url for ${hash} is not a file:<shard>/<rest> URL; answering 404`);
         return c.body(null, 404);
     }
+    if (!file_fact_url_addresses(parsed, hash)) {
+        log.error(`serve_fact: external_url for ${hash} addresses another fact's file; answering 404`);
+        return c.body(null, 404);
+    }
     const { shard, rest } = parsed;
     if (x_accel !== undefined) {
         // Production: hand off to nginx via the validated `internal;` facts location.