@fuzdev/fuz_app 0.143.0 → 0.145.0

package/dist/db/fact_store.d.ts

@@ -1,8 +1,8 @@
 /**
- * PG-backed `FactStore` implementation.
+ * PG-backed `HeldFactStore` implementation.
  *
  * Wraps the raw queries in `db/fact_queries.ts` with the lifecycle the
- * `FactStore` interface promises:
+ * `HeldFactStore` interface promises:
  *
  * - sync hash on `put`; `put_stream` hashes as it streams
  * - idempotent insert (`ON CONFLICT DO NOTHING` in the queries layer)
@@ -33,13 +33,63 @@
  * `external_url` has any other shape, and any external row on a store with no
  * disk CAS configured, as unavailable: a warning and `null`.
  *
+ * ## Holders
+ *
+ * Every put names its holder (`HeldFactPutOptions.holder`): the actor whose
+ * request carried the bytes, or `null` for a system put (seeds, server-side
+ * imports). A named holder gets a `fact_holder` row on every put — a
+ * deduplicated put included, since bringing identical bytes is possession. The
+ * `fact` row, its refs, and the holder row commit in one transaction. Cell ref
+ * admission (`auth/cell_ref_admission.ts`) reads the holder rows. The holder is
+ * a spine concept, so `PgFactStore` implements `HeldFactStore` — the
+ * `@fuzdev/fuz_util` `FactStore` reads plus puts that take `HeldFactPutOptions` —
+ * rather than the backend-agnostic `FactStore`, whose puts name no actor.
+ *
  * @module
  */
 import type { QueryDeps } from './query_deps.js';
+import type { Uuid } from '../primitive_schemas.js';
 import type { Logger } from '@fuzdev/fuz_util/log.ts';
 import type { FactHash } from '@fuzdev/fuz_util/hash_schemas.ts';
 import type { FactMeta, FactPutOptions, FactStore, PutStreamOutcome } from '@fuzdev/fuz_util/fact_store.ts';
 import { type FactDiskStorageDeps } from './fact_disk_storage.js';
+/**
+ * Options for `HeldFactStore.put` / `put_stream`: the `@fuzdev/fuz_util`
+ * `FactPutOptions` plus the required `holder`.
+ *
+ * `holder` is the actor that brought these bytes, recorded in `fact_holder`
+ * whether or not the fact already existed. `null` is a system put (seeds,
+ * server-side imports) that records no holder — a cell write can newly
+ * reference such a fact only as a global admin or as an actor that puts the
+ * same bytes itself (refs a cell already carries stay admitted through update
+ * and clone). Required, so a put on behalf of a caller can't silently skip the
+ * possession record. Twin of the Rust `PutOptions::holder`.
+ */
+export interface HeldFactPutOptions extends FactPutOptions {
+    holder: Uuid | null;
+}
+/**
+ * A fact store whose puts record possession: the `@fuzdev/fuz_util`
+ * `FactStore` reads, plus `put` / `put_stream` taking `HeldFactPutOptions` with
+ * its required `holder`.
+ *
+ * The holder is required — a store typed by the generic `FactStore` cannot
+ * record possession, so cell ref admission (`auth/cell_ref_admission.ts`)
+ * could never admit a ref to a fact put through it. `AppDeps.fact_store` is
+ * typed by this interface; `PgFactStore` implements it.
+ */
+export interface HeldFactStore extends Omit<FactStore, 'put' | 'put_stream'> {
+    /**
+     * Idempotent like `FactStore.put`; records `options.holder` (when non-null)
+     * on a fresh insert and a dedup hit alike.
+     */
+    put: (bytes: Uint8Array, options: HeldFactPutOptions) => Promise<FactHash>;
+    /**
+     * Idempotent like `FactStore.put_stream`; records `options.holder` (when
+     * non-null) on a fresh insert and a dedup hit alike.
+     */
+    put_stream: (stream: ReadableStream<Uint8Array>, max_bytes: number, options: HeldFactPutOptions) => Promise<PutStreamOutcome>;
+}
 /** Default embedded-vs-referenced cutoff (1 MiB). */
 export declare const FACT_EMBEDDED_THRESHOLD_DEFAULT: number;
 /**
@@ -70,10 +120,11 @@ export interface PgFactStoreDeps {
     log?: Logger;
 }
 /**
- * PG-backed `FactStore`. Delegates to `db/fact_queries.ts` for I/O and adds
- * the lifecycle layer described in the module doc.
+ * PG-backed fact store. Delegates to `db/fact_queries.ts` for I/O and adds
+ * the lifecycle layer described in the module doc. Implements `HeldFactStore`:
+ * the `@fuzdev/fuz_util` `FactStore` reads, puts taking `HeldFactPutOptions`.
  */
-export declare class PgFactStore implements FactStore {
+export declare class PgFactStore implements HeldFactStore {
     #private;
     constructor(options: PgFactStoreDeps);
     /**
@@ -82,9 +133,12 @@ export declare class PgFactStore implements FactStore {
      * 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.
+     * 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.
+     *
+     * @mutates fact_holder - records `options.holder` (when non-null) in the transaction that writes the `fact` row
      */
-    put(bytes: Uint8Array, options?: FactPutOptions): Promise<FactHash>;
+    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
@@ -100,9 +154,11 @@ export declare class PgFactStore implements FactStore {
      *
      * Requires `fs` (and, for the over-threshold spill, `disk_root`) to be
      * configured. The streaming twin of `put`; mirrors the Rust
-     * `FactStore::put_stream`.
+     * `FactStore::put_stream`. Records `options.holder` the way `put` does.
+     *
+     * @mutates fact_holder - records `options.holder` (when non-null) in the transaction that writes the `fact` row
      */
-    put_stream(stream: ReadableStream<Uint8Array>, max_bytes: number, options?: FactPutOptions): Promise<PutStreamOutcome>;
+    put_stream(stream: ReadableStream<Uint8Array>, max_bytes: number, options: HeldFactPutOptions): Promise<PutStreamOutcome>;
     /**
      * Retrieve bytes. Embedded reads return PG bytes directly. An external
      * read comes from the disk CAS and nowhere else: the bytes at the row's

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,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;AAYxC,OAAO,EAIN,KAAK,mBAAmB,EACxB,MAAM,wBAAwB,CAAC;AAEhC,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;;;GAGG;AACH,qBAAa,WAAY,YAAW,SAAS;;gBAOhC,OAAO,EAAE,eAAe;IAQpC;;;;;;;OAOG;IACG,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IA+BzE;;;;;;;;;;;;;;;;OAgBG;IACG,UAAU,CACf,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,cAAc,GACtB,OAAO,CAAC,gBAAgB,CAAC;IA6B5B;;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}

package/dist/db/fact_store.js

@@ -1,8 +1,8 @@
 /**
- * PG-backed `FactStore` implementation.
+ * PG-backed `HeldFactStore` implementation.
  *
  * Wraps the raw queries in `db/fact_queries.ts` with the lifecycle the
- * `FactStore` interface promises:
+ * `HeldFactStore` interface promises:
  *
  * - sync hash on `put`; `put_stream` hashes as it streams
  * - idempotent insert (`ON CONFLICT DO NOTHING` in the queries layer)
@@ -33,18 +33,32 @@
  * `external_url` has any other shape, and any external row on a store with no
  * disk CAS configured, as unavailable: a warning and `null`.
  *
+ * ## Holders
+ *
+ * Every put names its holder (`HeldFactPutOptions.holder`): the actor whose
+ * request carried the bytes, or `null` for a system put (seeds, server-side
+ * imports). A named holder gets a `fact_holder` row on every put — a
+ * deduplicated put included, since bringing identical bytes is possession. The
+ * `fact` row, its refs, and the holder row commit in one transaction. Cell ref
+ * admission (`auth/cell_ref_admission.ts`) reads the holder rows. The holder is
+ * a spine concept, so `PgFactStore` implements `HeldFactStore` — the
+ * `@fuzdev/fuz_util` `FactStore` reads plus puts that take `HeldFactPutOptions` —
+ * rather than the backend-agnostic `FactStore`, whose puts name no actor.
+ *
  * @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 { 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 { 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;
 /**
- * PG-backed `FactStore`. Delegates to `db/fact_queries.ts` for I/O and adds
- * the lifecycle layer described in the module doc.
+ * PG-backed fact store. Delegates to `db/fact_queries.ts` for I/O and adds
+ * the lifecycle layer described in the module doc. Implements `HeldFactStore`:
+ * the `@fuzdev/fuz_util` `FactStore` reads, puts taking `HeldFactPutOptions`.
  */
 export class PgFactStore {
     #deps;
@@ -65,7 +79,10 @@ 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.
+     * 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.
+     *
+     * @mutates fact_holder - records `options.holder` (when non-null) in the transaction that writes the `fact` row
      */
     async put(bytes, options) {
         const hash = fact_hash_bytes(bytes);
@@ -82,16 +99,13 @@ export class PgFactStore {
             row_bytes = bytes;
             row_external_url = null;
         }
-        const inserted = await query_put_fact(this.#deps, {
+        await this.#insert_row({
             hash,
             bytes: row_bytes,
             external_url: row_external_url,
-            content_type: options?.content_type ?? null,
+            content_type: options.content_type ?? null,
             size: bytes.length
-        });
-        if (inserted) {
-            await query_put_fact_refs(this.#deps, hash, resolve_refs(bytes, options));
-        }
+        }, resolve_refs(bytes, options), options.holder);
         return hash;
     }
     /**
@@ -109,7 +123,9 @@ export class PgFactStore {
      *
      * Requires `fs` (and, for the over-threshold spill, `disk_root`) to be
      * configured. The streaming twin of `put`; mirrors the Rust
-     * `FactStore::put_stream`.
+     * `FactStore::put_stream`. Records `options.holder` the way `put` does.
+     *
+     * @mutates fact_holder - records `options.holder` (when non-null) in the transaction that writes the `fact` row
      */
     async put_stream(stream, max_bytes, options) {
         if (this.#fs === undefined) {
@@ -118,18 +134,31 @@ export class PgFactStore {
         const streamed = await stream_fact_to_disk(this.#fs, this.#disk_root, stream, max_bytes, this.#embedded_threshold);
         const row_bytes = streamed.placement.kind === 'embedded' ? streamed.placement.bytes : null;
         const row_external_url = streamed.placement.kind === 'disk' ? streamed.placement.external_url : null;
-        const inserted = await query_put_fact(this.#deps, {
+        await this.#insert_row({
             hash: streamed.hash,
             bytes: row_bytes,
             external_url: row_external_url,
-            content_type: options?.content_type ?? null,
+            content_type: options.content_type ?? null,
             size: streamed.size
-        });
-        if (inserted && options?.refs && options.refs.length > 0) {
-            await query_put_fact_refs(this.#deps, streamed.hash, options.refs);
-        }
+        }, options.refs ?? [], options.holder);
         return { hash: streamed.hash, sha256: streamed.sha256, size: streamed.size };
     }
+    /**
+     * Insert the `fact` row, then — in the same transaction — its refs (fresh
+     * insert only) and the holder row (every put, a dedup hit included). Shared
+     * by `put` and `put_stream`; twin of the Rust `PgFactStore::insert_row`.
+     */
+    async #insert_row(row, refs, holder) {
+        await this.#deps.db.transaction(async (db) => {
+            const inserted = await query_put_fact({ db }, row);
+            if (inserted && refs.length > 0) {
+                await query_put_fact_refs({ db }, row.hash, refs);
+            }
+            if (holder !== null) {
+                await query_put_fact_holder({ db }, holder, row.hash);
+            }
+        });
+    }
     /**
      * Retrieve bytes. Embedded reads return PG bytes directly. An external
      * read comes from the disk CAS and nowhere else: the bytes at the row's
@@ -219,9 +248,9 @@ export class PgFactStore {
  * from JSON content; otherwise no refs.
  */
 const resolve_refs = (bytes, options) => {
-    if (options?.refs !== undefined)
+    if (options.refs !== undefined)
         return options.refs;
-    if (options?.content_type !== 'application/json')
+    if (options.content_type !== 'application/json')
         return [];
     let value;
     try {

package/dist/server/fact_security_headers.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The untrusted-content hardening headers every served fact carries.
+ *
+ * Fact bytes are served with a producer-supplied `content_type` emitted
+ * verbatim, inline. To stop a fact stored as (or sniffable to) `text/html` from
+ * executing as stored XSS for any reader of a referencing cell, every fact
+ * response carries `FACT_SECURITY_HEADERS`: `X-Content-Type-Options: nosniff` +
+ * `Content-Security-Policy: default-src 'none'; sandbox`.
+ *
+ * The embedded and disk-stream branches of `server/serve_fact_route.ts` set them
+ * on the response directly. On the `X-Accel-Redirect` branch nginx serves the
+ * bytes from its internal facts location, and a location with its own
+ * `add_header` stops the server-level headers from applying — so that location
+ * must carry the set itself, as the lines `fact_security_header_directives`
+ * renders. The X-Accel validator (`server/x_accel.ts`) refuses a facts location
+ * without them.
+ *
+ * The Rust twin is `fuz_fact_serving::fact_security_headers`; both pin the same
+ * literals.
+ *
+ * @module
+ */
+/**
+ * `X-Content-Type-Options` for fact responses — block MIME sniffing so an
+ * `application/octet-stream` fact can't be sniffed into executable HTML.
+ */
+export declare const FACT_X_CONTENT_TYPE_OPTIONS = "nosniff";
+/**
+ * `Content-Security-Policy` for fact responses. 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).
+ */
+export declare const FACT_CONTENT_SECURITY_POLICY = "default-src 'none'; sandbox";
+/**
+ * The fact hardening headers, in render order. `Content-Disposition:
+ * attachment` is deliberately absent — it would force-download and break
+ * legitimate inline image rendering.
+ */
+export declare const FACT_SECURITY_HEADERS: {
+    readonly 'X-Content-Type-Options': "nosniff";
+    readonly 'Content-Security-Policy': "default-src 'none'; sandbox";
+};
+/**
+ * The exact nginx `add_header … always;` lines the internal facts location must
+ * carry, rendered from `FACT_SECURITY_HEADERS`. `always` makes nginx add the
+ * header on every status, not just 2xx/3xx. The X-Accel validator refuses a
+ * facts location missing any of them.
+ *
+ * @returns one `add_header` directive per header, each ending in `always;`
+ */
+export declare const fact_security_header_directives: () => Array<string>;
+//# sourceMappingURL=fact_security_headers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fact_security_headers.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/fact_security_headers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;GAGG;AACH,eAAO,MAAM,2BAA2B,YAAY,CAAC;AAErD;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,gCAAgC,CAAC;AAE1E;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;CAGxB,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,QAAO,KAAK,CAAC,MAAM,CAG7D,CAAC"}

package/dist/server/fact_security_headers.js

@@ -0,0 +1,53 @@
+/**
+ * The untrusted-content hardening headers every served fact carries.
+ *
+ * Fact bytes are served with a producer-supplied `content_type` emitted
+ * verbatim, inline. To stop a fact stored as (or sniffable to) `text/html` from
+ * executing as stored XSS for any reader of a referencing cell, every fact
+ * response carries `FACT_SECURITY_HEADERS`: `X-Content-Type-Options: nosniff` +
+ * `Content-Security-Policy: default-src 'none'; sandbox`.
+ *
+ * The embedded and disk-stream branches of `server/serve_fact_route.ts` set them
+ * on the response directly. On the `X-Accel-Redirect` branch nginx serves the
+ * bytes from its internal facts location, and a location with its own
+ * `add_header` stops the server-level headers from applying — so that location
+ * must carry the set itself, as the lines `fact_security_header_directives`
+ * renders. The X-Accel validator (`server/x_accel.ts`) refuses a facts location
+ * without them.
+ *
+ * The Rust twin is `fuz_fact_serving::fact_security_headers`; both pin the same
+ * literals.
+ *
+ * @module
+ */
+/**
+ * `X-Content-Type-Options` for fact responses — block MIME sniffing so an
+ * `application/octet-stream` fact can't be sniffed into executable HTML.
+ */
+export const FACT_X_CONTENT_TYPE_OPTIONS = 'nosniff';
+/**
+ * `Content-Security-Policy` for fact responses. 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).
+ */
+export const FACT_CONTENT_SECURITY_POLICY = "default-src 'none'; sandbox";
+/**
+ * The fact hardening headers, in render order. `Content-Disposition:
+ * attachment` is deliberately absent — it would force-download and break
+ * legitimate inline image rendering.
+ */
+export const FACT_SECURITY_HEADERS = {
+    'X-Content-Type-Options': FACT_X_CONTENT_TYPE_OPTIONS,
+    'Content-Security-Policy': FACT_CONTENT_SECURITY_POLICY
+};
+/**
+ * The exact nginx `add_header … always;` lines the internal facts location must
+ * carry, rendered from `FACT_SECURITY_HEADERS`. `always` makes nginx add the
+ * header on every status, not just 2xx/3xx. The X-Accel validator refuses a
+ * facts location missing any of them.
+ *
+ * @returns one `add_header` directive per header, each ending in `always;`
+ */
+export const fact_security_header_directives = () => Object.entries(FACT_SECURITY_HEADERS).map(([name, value]) => `add_header ${name} "${value}" always;`);

package/dist/server/serve_fact_route.d.ts

@@ -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.
  *
@@ -41,6 +42,25 @@
  * hash. B publishing identical bytes from B's public cell makes them
  * readable *via B's cell* — it never touches A's private reference.
  *
+ * The edge is only as safe as what may create it. A cell's `refs` derive
+ * from its `data`, and any account that can write a cell writes its `data` —
+ * so this route alone would make a known hash a read capability: name it in
+ * a cell you own, flip the cell public, and the bytes serve to the world,
+ * while a 200 against a 404 says whether the fact exists. What closes that is
+ * **possession-gated ref admission** on the cell verbs
+ * (`auth/cell_ref_admission.ts`): a non-admin `cell_create` / `cell_update` /
+ * `cell_clone` may introduce a ref only to a fact its acting actor holds —
+ * one it put the bytes of, recorded in `fact_holder` on every put, a
+ * deduplicated put included — and is refused `403 cell_ref_not_held`
+ * otherwise, the same answer whether or not a fact is stored. Refs a cell
+ * already carries stay admitted through updates and clones, so a viewer who
+ * clones a cell carries its refs: what a viewer can read through a cell, it
+ * can republish — no more than downloading the bytes and uploading them
+ * again. A serve is a snapshot of the edge at read time; revoking someone's
+ * access to a cell does not withdraw refs they already wrote elsewhere.
+ * Writers that bypass the verbs (seeds, raw inserts) are trusted and not
+ * admitted.
+ *
  * The bare-hash route is **admin-only**: an admin's reach already spans
  * every cell, so serving by bare hash grants no escalation. Non-admin
  * callers are rejected at the auth phase and never reach the handler.
@@ -64,10 +84,11 @@
  * don't distinguish 403 from 404 — neither the existence of a fact nor the
  * existence of a cell→fact edge should leak through the public surface.
  *
- * Content-addressed serving of inline `blake3:` images (a markdown doc cell
- * with embedded image refs) works through this model: the referencing cell
- * is the doc cell, so serving goes view-doc-cell → doc-cell-refs-include-hash
- * → serve.
+ * A ref is a `data` string value that is exactly a fact hash
+ * (`derive_cell_refs`) — a hash inside prose or markup is not one. So a doc
+ * cell that shows images stores each image's hash as its own string value
+ * (an attachment list, say) beside the text that places them; serving then
+ * goes view-doc-cell → doc-cell-refs-include-hash → serve.
  *
  * ## Untrusted-content hardening
  *
@@ -76,8 +97,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.
  *

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;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;AAkEjD,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;AAkHD;;;;;;;;;;;;GAYG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwHG;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;AAuCjD,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;AAoHD;;;;;;;;;;;;GAYG;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

@@ -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.
  *
@@ -41,6 +42,25 @@
  * hash. B publishing identical bytes from B's public cell makes them
  * readable *via B's cell* — it never touches A's private reference.
  *
+ * The edge is only as safe as what may create it. A cell's `refs` derive
+ * from its `data`, and any account that can write a cell writes its `data` —
+ * so this route alone would make a known hash a read capability: name it in
+ * a cell you own, flip the cell public, and the bytes serve to the world,
+ * while a 200 against a 404 says whether the fact exists. What closes that is
+ * **possession-gated ref admission** on the cell verbs
+ * (`auth/cell_ref_admission.ts`): a non-admin `cell_create` / `cell_update` /
+ * `cell_clone` may introduce a ref only to a fact its acting actor holds —
+ * one it put the bytes of, recorded in `fact_holder` on every put, a
+ * deduplicated put included — and is refused `403 cell_ref_not_held`
+ * otherwise, the same answer whether or not a fact is stored. Refs a cell
+ * already carries stay admitted through updates and clones, so a viewer who
+ * clones a cell carries its refs: what a viewer can read through a cell, it
+ * can republish — no more than downloading the bytes and uploading them
+ * again. A serve is a snapshot of the edge at read time; revoking someone's
+ * access to a cell does not withdraw refs they already wrote elsewhere.
+ * Writers that bypass the verbs (seeds, raw inserts) are trusted and not
+ * admitted.
+ *
  * The bare-hash route is **admin-only**: an admin's reach already spans
  * every cell, so serving by bare hash grants no escalation. Non-admin
  * callers are rejected at the auth phase and never reach the handler.
@@ -64,10 +84,11 @@
  * don't distinguish 403 from 404 — neither the existence of a fact nor the
  * existence of a cell→fact edge should leak through the public surface.
  *
- * Content-addressed serving of inline `blake3:` images (a markdown doc cell
- * with embedded image refs) works through this model: the referencing cell
- * is the doc cell, so serving goes view-doc-cell → doc-cell-refs-include-hash
- * → serve.
+ * A ref is a `data` string value that is exactly a fact hash
+ * (`derive_cell_refs`) — a hash inside prose or markup is not one. So a doc
+ * cell that shows images stores each image's hash as its own string value
+ * (an attachment list, say) beside the text that places them; serving then
+ * goes view-doc-cell → doc-cell-refs-include-hash → serve.
  *
  * ## Untrusted-content hardening
  *
@@ -76,8 +97,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.
  *
@@ -111,33 +137,9 @@ 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 { FACT_SECURITY_HEADERS } from './fact_security_headers.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
-};
 /**
  * Path-param schema for the bare-hash route. Matching the canonical
  * fact-hash form here pushes malformed-hash 400s through the framework's
@@ -214,6 +216,8 @@ 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,