@fuzdev/fuz_app 0.67.1 → 0.69.0

package/dist/server/fact_write.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared helper for routing fact bytes between embedded (PG `bytes`
+ * column) and external (filesystem + `put_ref`) storage tiers based
+ * on size.
+ *
+ * External writes go through atomic temp+rename so the `facts` row
+ * never references a partial file; idempotence comes from POSIX
+ * `rename` overwrite + `INSERT ... ON CONFLICT DO NOTHING` in the
+ * fact-store queries layer.
+ *
+ * @module
+ */
+import { type FactHash } from '@fuzdev/fuz_util/fact_hash.js';
+import type { FactStore } from '@fuzdev/fuz_util/fact_store.js';
+export interface WriteFactOptions {
+    content_type: string;
+}
+/**
+ * Write `bytes` as a fact, choosing embedded (PG) vs external (disk +
+ * `put_ref`) based on `embedded_threshold`. Returns the canonical
+ * `blake3:` hash either way.
+ *
+ * @param fact_store - the `FactStore` (typically `PgFactStore`)
+ * @param embedded_threshold - bytes ≤ threshold → embedded; > threshold → disk
+ * @param facts_dir - root of the sharded facts directory tree on disk
+ * @param bytes - the raw fact bytes
+ * @param options - content type for the fact metadata
+ * @returns the fact's `blake3:<hex64>` hash
+ * @mutates `fact_store`, `facts_dir` filesystem
+ */
+export declare const write_fact: (fact_store: FactStore, embedded_threshold: number, facts_dir: string, bytes: Uint8Array, options: WriteFactOptions) => Promise<FactHash>;
+//# sourceMappingURL=fact_write.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fact_write.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/fact_write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,EAAoC,KAAK,QAAQ,EAAC,MAAM,+BAA+B,CAAC;AAC/F,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gCAAgC,CAAC;AAG9D,MAAM,WAAW,gBAAgB;IAChC,YAAY,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU,GACtB,YAAY,SAAS,EACrB,oBAAoB,MAAM,EAC1B,WAAW,MAAM,EACjB,OAAO,UAAU,EACjB,SAAS,gBAAgB,KACvB,OAAO,CAAC,QAAQ,CA4BlB,CAAC"}

package/dist/server/fact_write.js

@@ -0,0 +1,56 @@
+/**
+ * Shared helper for routing fact bytes between embedded (PG `bytes`
+ * column) and external (filesystem + `put_ref`) storage tiers based
+ * on size.
+ *
+ * External writes go through atomic temp+rename so the `facts` row
+ * never references a partial file; idempotence comes from POSIX
+ * `rename` overwrite + `INSERT ... ON CONFLICT DO NOTHING` in the
+ * fact-store queries layer.
+ *
+ * @module
+ */
+import { randomBytes } from 'node:crypto';
+import { writeFile, rename, mkdir, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { FACT_HASH_PREFIX, fact_hash_bytes } from '@fuzdev/fuz_util/fact_hash.js';
+import { mint_file_fact_url } from './file_fact_url.js';
+/**
+ * Write `bytes` as a fact, choosing embedded (PG) vs external (disk +
+ * `put_ref`) based on `embedded_threshold`. Returns the canonical
+ * `blake3:` hash either way.
+ *
+ * @param fact_store - the `FactStore` (typically `PgFactStore`)
+ * @param embedded_threshold - bytes ≤ threshold → embedded; > threshold → disk
+ * @param facts_dir - root of the sharded facts directory tree on disk
+ * @param bytes - the raw fact bytes
+ * @param options - content type for the fact metadata
+ * @returns the fact's `blake3:<hex64>` hash
+ * @mutates `fact_store`, `facts_dir` filesystem
+ */
+export const write_fact = async (fact_store, embedded_threshold, facts_dir, bytes, options) => {
+    if (bytes.length <= embedded_threshold) {
+        return fact_store.put(bytes, options);
+    }
+    const hash = fact_hash_bytes(bytes);
+    const hex = hash.slice(FACT_HASH_PREFIX.length);
+    const shard = hex.slice(0, 2);
+    const rest = hex.slice(2);
+    const shard_dir = join(facts_dir, shard);
+    const tmp_dir = join(facts_dir, '.tmp');
+    const tmp_path = join(tmp_dir, `${randomBytes(16).toString('hex')}.tmp`);
+    const final_path = join(shard_dir, rest);
+    await Promise.all([mkdir(shard_dir, { recursive: true }), mkdir(tmp_dir, { recursive: true })]);
+    let renamed = false;
+    try {
+        await writeFile(tmp_path, bytes);
+        await rename(tmp_path, final_path);
+        renamed = true;
+    }
+    finally {
+        if (!renamed) {
+            await unlink(tmp_path).catch(() => undefined);
+        }
+    }
+    return fact_store.put_ref(mint_file_fact_url(shard, rest), bytes.length, options);
+};

package/dist/server/file_fact_fetcher.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Filesystem-backed `FactExternalFetcher`.
+ *
+ * Resolves `file:<shard>/<rest>` external URLs against a configured
+ * facts directory. The URL shape is the canonical relative-path scheme:
+ * 2 hex chars for the shard subdir + 62 hex chars for the rest of the
+ * blake3 hash (64 hex chars total). Files live at
+ * `<facts_dir>/<shard>/<rest>` after the writer atomically temp+renames
+ * them in.
+ *
+ * **Pre-filter regex**: `^file:[0-9a-f]{2}/[0-9a-f]{62}$`. A `..`
+ * segment can't match (`.` isn't in `[0-9a-f]`); neither can absolute
+ * paths, query strings, or any non-hex character. Defense-in-depth in
+ * front of `path.join` — the fetcher never trusts the URL came from a
+ * fact row, even though it always does in practice.
+ *
+ * The fetcher does NOT verify hash content — `PgFactStore.get` calls
+ * `fact_hash_verify(hash, bytes)` after the fetch and returns null on
+ * mismatch.
+ *
+ * Runtime: uses `node:fs/promises` + `node:fs` `createReadStream` so
+ * the same code works under Deno (via node compat) and vitest.
+ *
+ * @module
+ */
+import type { FactExternalFetcher } from '../db/fact_store.js';
+/** Construction options. */
+export interface FileFactFetcherOptions {
+    /**
+     * Absolute path to the facts directory. Files resolve to
+     * `<facts_dir>/<shard>/<rest>`.
+     */
+    facts_dir: string;
+}
+/**
+ * Build a `FactExternalFetcher` that resolves `file:` URLs against the
+ * filesystem. Throws on a malformed URL before touching the disk so
+ * `PgFactStore.get` logs the warning + returns null without an I/O
+ * round-trip on bad data.
+ */
+export declare const create_file_fact_fetcher: (options: FileFactFetcherOptions) => FactExternalFetcher;
+//# sourceMappingURL=file_fact_fetcher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file_fact_fetcher.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/file_fact_fetcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAOH,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AAG7D,4BAA4B;AAC5B,MAAM,WAAW,sBAAsB;IACtC;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GAAI,SAAS,sBAAsB,KAAG,mBA0B1E,CAAC"}

package/dist/server/file_fact_fetcher.js

@@ -0,0 +1,60 @@
+/**
+ * Filesystem-backed `FactExternalFetcher`.
+ *
+ * Resolves `file:<shard>/<rest>` external URLs against a configured
+ * facts directory. The URL shape is the canonical relative-path scheme:
+ * 2 hex chars for the shard subdir + 62 hex chars for the rest of the
+ * blake3 hash (64 hex chars total). Files live at
+ * `<facts_dir>/<shard>/<rest>` after the writer atomically temp+renames
+ * them in.
+ *
+ * **Pre-filter regex**: `^file:[0-9a-f]{2}/[0-9a-f]{62}$`. A `..`
+ * segment can't match (`.` isn't in `[0-9a-f]`); neither can absolute
+ * paths, query strings, or any non-hex character. Defense-in-depth in
+ * front of `path.join` — the fetcher never trusts the URL came from a
+ * fact row, even though it always does in practice.
+ *
+ * The fetcher does NOT verify hash content — `PgFactStore.get` calls
+ * `fact_hash_verify(hash, bytes)` after the fetch and returns null on
+ * mismatch.
+ *
+ * Runtime: uses `node:fs/promises` + `node:fs` `createReadStream` so
+ * the same code works under Deno (via node compat) and vitest.
+ *
+ * @module
+ */
+import { readFile } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { Readable } from 'node:stream';
+import { join } from 'node:path';
+import { parse_file_fact_url } from './file_fact_url.js';
+/**
+ * Build a `FactExternalFetcher` that resolves `file:` URLs against the
+ * filesystem. Throws on a malformed URL before touching the disk so
+ * `PgFactStore.get` logs the warning + returns null without an I/O
+ * round-trip on bad data.
+ */
+export const create_file_fact_fetcher = (options) => {
+    const { facts_dir } = options;
+    const resolve_path = (url) => {
+        const parsed = parse_file_fact_url(url);
+        if (!parsed) {
+            throw new Error(`invalid file fact url: ${url}`);
+        }
+        return join(facts_dir, parsed.shard, parsed.rest);
+    };
+    return {
+        fetch_bytes: async (url) => {
+            const path = resolve_path(url);
+            const buf = await readFile(path);
+            return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+        },
+        // `Promise.resolve().then(...)` (rather than `async`) funnels any
+        // `resolve_path` throw into a rejection without an unused `await`.
+        fetch_stream: (url) => Promise.resolve().then(() => {
+            const path = resolve_path(url);
+            const node_stream = createReadStream(path);
+            return Readable.toWeb(node_stream);
+        }),
+    };
+};

package/dist/server/file_fact_url.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Canonical filesystem-fact URL shape.
+ *
+ * `external_url` on the generic `facts` row is `string | null` because the
+ * `FactStore` interface stays federation-friendly (future
+ * `https://...` / `s3://...` shapes). Filesystem-minted URLs are exactly
+ * `file:<shard>/<rest>` where `<shard>` is the first 2 hex chars of the
+ * blake3 digest and `<rest>` the remaining 62 — files land at
+ * `<facts_dir>/<shard>/<rest>` after the writer atomically temp+renames
+ * them in.
+ *
+ * Centralizing the regex keeps the shape in one place: the `serve_fact_route`
+ * defense-in-depth check and the `file_fact_fetcher` resolver both validate
+ * against it, so federation work that loosens or extends the shape (e.g.,
+ * admitting `https://`) updates one place, not several.
+ *
+ * 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.
+ * Used in front of `path.join` so the resolver never trusts the URL came
+ * from a fact row, even though it always does in practice.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Anchored, capture-group form: `^file:(<shard>)/(<rest>)$`. */
+export declare const FILE_FACT_URL_PATTERN: RegExp;
+/**
+ * Branded URL form. Construct only via `parse_file_fact_url` or
+ * `mint_file_fact_url` — those are the validated boundaries. Direct
+ * string literals don't satisfy the brand.
+ */
+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;
+/**
+ * Validate a string against the canonical shape. Returns the branded URL
+ * plus its parsed parts, or `null` on shape mismatch — callers decide
+ * whether that's a 404 (read), a skip (GC), or a hard reject (write).
+ */
+export declare const parse_file_fact_url: (url: string) => {
+    url: FileFactUrl;
+    shard: string;
+    rest: string;
+} | null;
+/**
+ * Construct a canonical `file:<shard>/<rest>` URL. The writer side
+ * (`server/fact_write.ts`) assembles the shape from a freshly-computed
+ * hash; this helper centralizes the literal so a future shape change is
+ * a single edit.
+ */
+export declare const mint_file_fact_url: (shard: string, rest: string) => FileFactUrl;
+//# sourceMappingURL=file_fact_url.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file_fact_url.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/file_fact_url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,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;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC/B,KAAK,MAAM,KACT;IAAC,GAAG,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAAG,IAIpD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,EAAE,MAAM,MAAM,KAAG,WAC1B,CAAC"}

package/dist/server/file_fact_url.js

@@ -0,0 +1,52 @@
+/**
+ * Canonical filesystem-fact URL shape.
+ *
+ * `external_url` on the generic `facts` row is `string | null` because the
+ * `FactStore` interface stays federation-friendly (future
+ * `https://...` / `s3://...` shapes). Filesystem-minted URLs are exactly
+ * `file:<shard>/<rest>` where `<shard>` is the first 2 hex chars of the
+ * blake3 digest and `<rest>` the remaining 62 — files land at
+ * `<facts_dir>/<shard>/<rest>` after the writer atomically temp+renames
+ * them in.
+ *
+ * Centralizing the regex keeps the shape in one place: the `serve_fact_route`
+ * defense-in-depth check and the `file_fact_fetcher` resolver both validate
+ * against it, so federation work that loosens or extends the shape (e.g.,
+ * admitting `https://`) updates one place, not several.
+ *
+ * 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.
+ * Used in front of `path.join` so the resolver never trusts the URL came
+ * from a fact row, even though it always does in practice.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Anchored, capture-group form: `^file:(<shard>)/(<rest>)$`. */
+export const FILE_FACT_URL_PATTERN = /^file:([0-9a-f]{2})\/([0-9a-f]{62})$/;
+/**
+ * Branded URL form. Construct only via `parse_file_fact_url` or
+ * `mint_file_fact_url` — those are the validated boundaries. Direct
+ * 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);
+/**
+ * Validate a string against the canonical shape. Returns the branded URL
+ * plus its parsed parts, or `null` on shape mismatch — callers decide
+ * whether that's a 404 (read), a skip (GC), or a hard reject (write).
+ */
+export const parse_file_fact_url = (url) => {
+    const m = FILE_FACT_URL_PATTERN.exec(url);
+    if (!m)
+        return null;
+    return { url: url, shard: m[1], rest: m[2] };
+};
+/**
+ * Construct a canonical `file:<shard>/<rest>` URL. The writer side
+ * (`server/fact_write.ts`) assembles the shape from a freshly-computed
+ * hash; this helper centralizes the literal so a future shape change is
+ * a single edit.
+ */
+export const mint_file_fact_url = (shard, rest) => `file:${shard}/${rest}`;

package/dist/server/serve_fact_route.d.ts

@@ -0,0 +1,78 @@
+/**
+ * `GET /api/facts/:hash` — content-addressed fact serving.
+ *
+ * Resolves a fact hash to the bytes referenced by at least one viewable
+ * cell. Embedded facts stream from the `facts.bytes` PG column;
+ * external facts (filesystem-backed `file:<shard>/<rest>` URLs) either
+ * return an `X-Accel-Redirect` header pointing into nginx's internal
+ * facts location (production) or stream from disk via the filesystem
+ * `FactExternalFetcher` (dev / tests). The runtime mode is selected by
+ * the optional `x_accel_redirect_prefix` factory option — set in prod,
+ * unset in dev.
+ *
+ * REST, not RPC: binary responses don't fit the JSON-RPC envelope.
+ *
+ * ## Authorization
+ *
+ * Auth is `{account: 'none', actor: 'none'}` — the dispatcher's
+ * authorization phase is skipped for pure-public routes, so this 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`. Viewers are admitted via `can_view_cell` over
+ * **every** active cell that references the hash. 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
+ * (admitted only by the public-visibility branch). A fact is viewable iff
+ * at least one referencing cell admits the caller; unauthenticated callers
+ * are admitted only via a referencing cell with `cell.visibility ===
+ * 'public'`. Facts with no referencing active cell are unreachable here —
+ * orphan-fact GC reaps them separately.
+ *
+ * 404 is the universal "not viewable" response: missing fact, missing
+ * referencing cell, all referencing cells private to other actors. We
+ * deliberately don't distinguish 403 from 404 — the existence of a
+ * private hash should not leak through the public surface.
+ *
+ * ## Defense-in-depth
+ *
+ * The `external_url` regex is re-validated before issuing
+ * `X-Accel-Redirect` even though `PgFactStore.put_ref` only writes
+ * `file:<shard>/<rest>`-shaped URLs. A future row-injection bug
+ * upstream would otherwise hand nginx an attacker-controlled path.
+ *
+ * @module
+ */
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+import { type RouteSpec } from '../http/route_spec.js';
+import type { AppDeps } from '../auth/deps.js';
+export interface CreateServeFactRouteSpecOptions {
+    /**
+     * App deps reference. Currently unused at handler time (cell + fact
+     * tables are read via `RouteContext.db`); kept on the factory
+     * signature for symmetry with sibling route factories and to give
+     * future role_grant-scoped viewer extensions somewhere to read other
+     * deps without changing the public shape.
+     */
+    deps: AppDeps;
+    /** Absolute path of the facts directory. Used for the dev/test streaming path. */
+    facts_dir: string;
+    /**
+     * When set, external facts return an `X-Accel-Redirect` pointing at
+     * `${prefix}<shard>/<rest>` — nginx's internal facts location serves
+     * the bytes. When unset, external facts stream from
+     * `<facts_dir>/<shard>/<rest>` directly. Production sets this (e.g.
+     * `/_facts/`); tests + dev leave it unset.
+     */
+    x_accel_redirect_prefix?: string;
+    log: Logger;
+}
+/**
+ * Build the `GET /api/facts/:hash` `RouteSpec`.
+ *
+ * Pure-public auth — the handler builds the per-request `RequestContext`
+ * from `c.var.account_id` and enforces visibility per-fact via the
+ * cell-walk above.
+ */
+export declare const create_serve_fact_route_spec: (options: CreateServeFactRouteSpecOptions) => RouteSpec;
+//# sourceMappingURL=serve_fact_route.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serve_fact_route.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/serve_fact_route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAKH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAOpD,OAAO,EAAmB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAEvE,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,iBAAiB,CAAC;AAoB7C,MAAM,WAAW,+BAA+B;IAC/C;;;;;;OAMG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,+BAA+B,KACtC,SAgIF,CAAC"}

package/dist/server/serve_fact_route.js

@@ -0,0 +1,205 @@
+/**
+ * `GET /api/facts/:hash` — content-addressed fact serving.
+ *
+ * Resolves a fact hash to the bytes referenced by at least one viewable
+ * cell. Embedded facts stream from the `facts.bytes` PG column;
+ * external facts (filesystem-backed `file:<shard>/<rest>` URLs) either
+ * return an `X-Accel-Redirect` header pointing into nginx's internal
+ * facts location (production) or stream from disk via the filesystem
+ * `FactExternalFetcher` (dev / tests). The runtime mode is selected by
+ * the optional `x_accel_redirect_prefix` factory option — set in prod,
+ * unset in dev.
+ *
+ * REST, not RPC: binary responses don't fit the JSON-RPC envelope.
+ *
+ * ## Authorization
+ *
+ * Auth is `{account: 'none', actor: 'none'}` — the dispatcher's
+ * authorization phase is skipped for pure-public routes, so this 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`. Viewers are admitted via `can_view_cell` over
+ * **every** active cell that references the hash. 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
+ * (admitted only by the public-visibility branch). A fact is viewable iff
+ * at least one referencing cell admits the caller; unauthenticated callers
+ * are admitted only via a referencing cell with `cell.visibility ===
+ * 'public'`. Facts with no referencing active cell are unreachable here —
+ * orphan-fact GC reaps them separately.
+ *
+ * 404 is the universal "not viewable" response: missing fact, missing
+ * referencing cell, all referencing cells private to other actors. We
+ * deliberately don't distinguish 403 from 404 — the existence of a
+ * private hash should not leak through the public surface.
+ *
+ * ## Defense-in-depth
+ *
+ * The `external_url` regex is re-validated before issuing
+ * `X-Accel-Redirect` even though `PgFactStore.put_ref` only writes
+ * `file:<shard>/<rest>`-shaped URLs. A future row-injection bug
+ * upstream would otherwise hand nginx an attacker-controlled path.
+ *
+ * @module
+ */
+import { createReadStream } from 'node:fs';
+import { Readable } from 'node:stream';
+import { join } from 'node:path';
+import { FactHashSchema } from '@fuzdev/fuz_util/fact_hash.js';
+import { z } from 'zod';
+import { build_request_context } from '../auth/request_context.js';
+import { ACCOUNT_ID_KEY } from '../hono_context.js';
+import { query_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';
+import { query_get_fact, query_get_fact_meta } from '../db/fact_queries.js';
+import { query_cell_list_by_ref } 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 { parse_file_fact_url } from './file_fact_url.js';
+/** `Cache-Control` for fact responses — 5 min revocation window. */
+const CACHE_CONTROL = 'private, max-age=300';
+/**
+ * Path-param schema. Matching the canonical fact-hash form here pushes
+ * malformed-hash 400s through the framework's standard params-validation
+ * error shape (`ERROR_INVALID_ROUTE_PARAMS`), which the round-trip
+ * validator expects.
+ */
+const params_schema = z.strictObject({
+    hash: FactHashSchema,
+});
+/**
+ * Build the `GET /api/facts/:hash` `RouteSpec`.
+ *
+ * Pure-public auth — the handler builds the per-request `RequestContext`
+ * from `c.var.account_id` and enforces visibility per-fact via the
+ * cell-walk above.
+ */
+export const create_serve_fact_route_spec = (options) => {
+    const { facts_dir, x_accel_redirect_prefix, log } = options;
+    return {
+        method: 'GET',
+        path: '/api/facts/:hash',
+        auth: { account: 'none', actor: 'none' },
+        description: 'Serve content-addressed fact bytes. 404 unless at least one referencing cell admits the caller via can_view_cell.',
+        params: params_schema,
+        input: z.null(),
+        // The body is a binary stream; no JSON output schema applies.
+        output: z.null(),
+        errors: {
+            // Tighten the auto-derived 400 from `ApiError` (`error: string`) to
+            // the actual literal emitted by `create_params_validation`, so
+            // `assert_error_schema_tightness` reads the surface as specific
+            // rather than generic.
+            400: z.looseObject({
+                error: z.literal(ERROR_INVALID_ROUTE_PARAMS),
+                issues: z.array(z.unknown()),
+            }),
+        },
+        handler: async (c, route) => {
+            const { hash } = get_route_params(c);
+            const meta = await query_get_fact_meta({ db: route.db }, hash);
+            if (!meta) {
+                return c.body(null, 404);
+            }
+            // Pure-public route — dispatcher skips the authorization phase, so
+            // build the `RequestContext` here from the session-middleware-set
+            // account id. Multi-actor accounts fall through with `null` (no
+            // `acting?` slot on a public route to disambiguate); single-actor
+            // accounts resolve their actor and role_grants for owner / grant /
+            // admin admission paths.
+            const account_id = c.get(ACCOUNT_ID_KEY);
+            let req_ctx = null;
+            if (account_id) {
+                const actors = await query_actors_by_account({ db: route.db }, account_id);
+                if (actors.length === 1) {
+                    req_ctx = await build_request_context({ db: route.db }, account_id, actors[0].id);
+                }
+            }
+            // `include_grant_count: false` — the authz walk only reads
+            // `can_view_cell`-relevant fields, so skip the per-row grant
+            // COUNT subquery. Cheap to begin with; even cheaper now.
+            const referencing_cells = await query_cell_list_by_ref({ db: route.db }, hash, {
+                include_grant_count: false,
+            });
+            // Sequential walk with early break on first admit — preserves
+            // the original `.some()` short-circuit. Unauthenticated callers
+            // skip the grant fetch entirely since no grant can admit a null
+            // req_ctx (the only admit path is the public-visibility branch
+            // in `can_view_cell`, which doesn't need grants). Authenticated
+            // callers eat one `cell_grant` lookup per referencing cell up
+            // to the first admit; acceptable at MVP fact-serve scale.
+            // TODO: if profiling shows this hot, batch grants in one query
+            // across all referencing cells, or push the predicate into SQL.
+            let viewable = false;
+            for (const cell of referencing_cells) {
+                const grants = req_ctx
+                    ? await query_cell_grant_list_for_cell({ db: route.db }, cell.id)
+                    : null;
+                if (can_view_cell(req_ctx, cell, grants)) {
+                    viewable = true;
+                    break;
+                }
+            }
+            if (!viewable) {
+                // 404 (not 403) so existence of private hashes doesn't leak
+                // through the public surface. Same response shape as a
+                // genuinely missing fact.
+                return c.body(null, 404);
+            }
+            const content_type = meta.content_type ?? 'application/octet-stream';
+            const size = String(meta.size);
+            if (meta.external_url === null) {
+                // Embedded — bytes live in the PG row.
+                const row = await query_get_fact({ db: route.db }, hash);
+                if (!row || row.bytes === null) {
+                    // Race: meta said embedded but bytes vanished. Treat as not-found.
+                    log.warn(`serve_fact: embedded bytes missing for ${hash} (meta said embedded, row=${row ? 'present' : 'null'})`);
+                    return c.body(null, 404);
+                }
+                const bytes = to_uint8(row.bytes);
+                return c.body(bytes, 200, {
+                    'Content-Type': content_type,
+                    'Content-Length': size,
+                    'Cache-Control': CACHE_CONTROL,
+                });
+            }
+            // External — defense-in-depth re-validate the URL before trusting it
+            // to address the filesystem.
+            const parsed = parse_file_fact_url(meta.external_url);
+            if (!parsed) {
+                log.error(`serve_fact: rejecting malformed external_url for ${hash}: ${meta.external_url}`);
+                return c.body(null, 404);
+            }
+            const { shard, rest } = parsed;
+            if (x_accel_redirect_prefix !== undefined) {
+                // Production: hand off to nginx via the internal facts location.
+                return c.body(null, 200, {
+                    'Content-Type': content_type,
+                    'Content-Length': size,
+                    'Cache-Control': CACHE_CONTROL,
+                    'X-Accel-Redirect': `${x_accel_redirect_prefix}${shard}/${rest}`,
+                });
+            }
+            // Dev / tests: stream from disk. `createReadStream` errors land on the
+            // returned ReadableStream, which Hono surfaces as a 500 to the client.
+            const file_path = join(facts_dir, shard, rest);
+            const node_stream = createReadStream(file_path);
+            const web_stream = Readable.toWeb(node_stream);
+            return c.body(web_stream, 200, {
+                'Content-Type': content_type,
+                'Content-Length': size,
+                'Cache-Control': CACHE_CONTROL,
+            });
+        },
+    };
+};
+/**
+ * Coerce whatever the driver returns for BYTEA into a `Uint8Array`. Same
+ * shape as the helper in `PgFactStore.get` — `pg` returns a `Buffer`
+ * (`Uint8Array` subclass), `pglite` already returns `Uint8Array`.
+ */
+const to_uint8 = (value) => value instanceof Uint8Array && value.constructor === Uint8Array
+    ? value
+    : new Uint8Array(value.buffer, value.byteOffset, value.byteLength);