@fuzdev/fuz_app 0.142.0 → 0.144.0

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/http/CLAUDE.md

@@ -24,7 +24,7 @@ effects, see ../../../docs/architecture.md.
 - `http/surface_query.ts` — pure filters/groupings over `AppSurface`.
 - `http/proxy.ts` — trusted-proxy middleware, CIDR parsing, rightmost-first XFF resolution. Pulls `hono/utils/ipaddr` for CIDR matching.
 - `http/client_ip.ts` — `get_client_ip(c)` — reads the resolved IP off the context (set by `proxy.ts`'s middleware). Split out of `proxy.ts` so it's hono-free: dispatch + route modules that only _read_ the IP don't pull `hono/utils/ipaddr`, keeping cross-process test surfaces free of the optional `hono` peer.
-- `http/ip_canonical.ts` — RFC 5952 IPv6 canonicalization + IPv4-mapped collapse; `IP_LITERAL_CHARS` regex.
+- `http/ip_canonical.ts` — RFC 5952 IPv6 canonicalization + IPv4-mapped collapse, `rate_limit_ip_key` (an IPv6 client's `/64`), and its own `parse_ipv4_bits` / `parse_ipv6_bits` (the grammar of Rust's `IpAddr::from_str`); `IP_LITERAL_CHARS` regex. Imports nothing — the dispatcher keys its IP limiter through it, so it must stay hono-free (`src/test/hono_free_modules.test.ts` walks every `src/lib` module's graph).
 - `http/origin.ts` — origin allowlist: the strict pattern grammar shared with the Rust spine, typed refusals, and the Origin-only middleware.
 - `http/jsonrpc.ts` — JSON-RPC 2.0 envelope schemas (MCP superset), `JsonrpcErrorCode`, `_meta`.
 - `http/jsonrpc_errors.ts` — `ThrownJsonrpcError`, `jsonrpc_errors` throwers, HTTP-status mappings.

package/dist/http/ip_canonical.d.ts

@@ -18,7 +18,8 @@
  *    strings (`'unknown'`, `'attacker:controlled'`, `'::1\n'`) pass
  *    through unchanged so downstream strict validators can still
  *    reject them.
- * 2. Parses via Hono's `convertIPv*ToBinary` family.
+ * 2. Parses with `parse_ipv4_bits` / `parse_ipv6_bits` — the grammar of
+ *    Rust's `IpAddr::from_str`, which the spine parses with.
  * 3. Re-emits the canonical RFC 5952 string (lowercase hex,
  *    longest-zero-run compressed, IPv4-mapped emitted in the dotted
  *    form mandated by RFC 5952 §5).
@@ -37,8 +38,31 @@
  * the limiter call sites apply it — the client IP stays the full address
  * everywhere else (audit rows, token `last_used_ip`, `REMOTE_ADDR`).
  *
+ * The module imports nothing: the action dispatcher keys its IP limiter
+ * through it, so it must not pull the optional `hono` peer.
+ *
  * @module
  */
+/**
+ * Parse a dotted-quad IPv4 address to its 32-bit value.
+ *
+ * Four decimal octets, each 0–255 with no leading zeros (`01.2.3.4` is
+ * refused, as Rust's `Ipv4Addr::from_str` refuses it).
+ *
+ * @returns the address as an unsigned 32-bit number, or `null` when `ip` isn't one
+ */
+export declare const parse_ipv4_bits: (ip: string) => number | null;
+/**
+ * Parse an IPv6 address to its 128-bit value.
+ *
+ * The grammar of Rust's `Ipv6Addr::from_str`: eight groups of one to four
+ * hex digits (either case), or fewer around a single `::` standing for one or
+ * more zero groups, the last two groups optionally written as a dotted-quad
+ * IPv4 address. No zone (`%eth0`) — callers strip it first.
+ *
+ * @returns the address as a `bigint` in `[0, 2^128)`, or `null` when `ip` isn't one
+ */
+export declare const parse_ipv6_bits: (ip: string) => bigint | null;
 /**
  * Allowed character set for a bare IP literal.
  *
@@ -95,7 +119,7 @@ export declare const canonicalize_ip: (ip: string) => string;
  *
  * Pure helper exported for the test suite to exercise the
  * canonicalization invariants directly without a full
- * `convertIPv6ToBinary` round-trip.
+ * `parse_ipv6_bits` round-trip.
  *
  * @param bits - the 128-bit IPv6 value as `bigint`. Must satisfy `0n <= bits < 2n ** 128n`;
  *   throws `RangeError` otherwise. Silent truncation would mask caller bugs since the

package/dist/http/ip_canonical.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ip_canonical.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/ip_canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAIH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,QAAqB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,eAAe,GAAI,IAAI,MAAM,KAAG,MAmC5C,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,wBAAwB,GAAI,MAAM,MAAM,KAAG,MAgEvD,CAAC;AAKF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,GAAI,IAAI,MAAM,KAAG,MAc9C,CAAC"}
+{"version":3,"file":"ip_canonical.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/ip_canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AASH;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,IAAI,MAAM,KAAG,MAAM,GAAG,IAKrD,CAAC;AA0BF;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAAI,IAAI,MAAM,KAAG,MAAM,GAAG,IAkBrD,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,QAAqB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,eAAe,GAAI,IAAI,MAAM,KAAG,MAsB5C,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,wBAAwB,GAAI,MAAM,MAAM,KAAG,MAgEvD,CAAC;AAKF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,GAAI,IAAI,MAAM,KAAG,MAQ9C,CAAC"}

package/dist/http/ip_canonical.js

@@ -18,7 +18,8 @@
  *    strings (`'unknown'`, `'attacker:controlled'`, `'::1\n'`) pass
  *    through unchanged so downstream strict validators can still
  *    reject them.
- * 2. Parses via Hono's `convertIPv*ToBinary` family.
+ * 2. Parses with `parse_ipv4_bits` / `parse_ipv6_bits` — the grammar of
+ *    Rust's `IpAddr::from_str`, which the spine parses with.
  * 3. Re-emits the canonical RFC 5952 string (lowercase hex,
  *    longest-zero-run compressed, IPv4-mapped emitted in the dotted
  *    form mandated by RFC 5952 §5).
@@ -37,9 +38,92 @@
  * the limiter call sites apply it — the client IP stays the full address
  * everywhere else (audit rows, token `last_used_ip`, `REMOTE_ADDR`).
  *
+ * The module imports nothing: the action dispatcher keys its IP limiter
+ * through it, so it must not pull the optional `hono` peer.
+ *
  * @module
  */
-import { convertIPv6ToBinary, distinctRemoteAddr } from 'hono/utils/ipaddr';
+/** A dotted-quad IPv4 address: four decimal octets, 0–255, no leading zeros. */
+const IPV4_REGEX = /^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])$/;
+/** One IPv6 group: one to four hex digits. */
+const IPV6_GROUP_REGEX = /^[0-9a-fA-F]{1,4}$/;
+/**
+ * Parse a dotted-quad IPv4 address to its 32-bit value.
+ *
+ * Four decimal octets, each 0–255 with no leading zeros (`01.2.3.4` is
+ * refused, as Rust's `Ipv4Addr::from_str` refuses it).
+ *
+ * @returns the address as an unsigned 32-bit number, or `null` when `ip` isn't one
+ */
+export const parse_ipv4_bits = (ip) => {
+    if (!IPV4_REGEX.test(ip))
+        return null;
+    let bits = 0;
+    for (const octet of ip.split('.'))
+        bits = bits * 256 + Number(octet);
+    return bits;
+};
+/**
+ * Parse the colon-separated groups on one side of a `::` (or the whole
+ * address when there is none), `null` on a malformed one. Only the last group
+ * of the address may be a dotted-quad IPv4 tail, which fills two groups.
+ */
+const parse_ipv6_groups = (part, allow_ipv4_tail) => {
+    if (part === '')
+        return [];
+    const pieces = part.split(':');
+    const groups = [];
+    for (let i = 0; i < pieces.length; i++) {
+        const piece = pieces[i];
+        if (allow_ipv4_tail && i === pieces.length - 1 && piece.includes('.')) {
+            const ipv4 = parse_ipv4_bits(piece);
+            if (ipv4 === null)
+                return null;
+            groups.push(Math.floor(ipv4 / 0x10000), ipv4 % 0x10000);
+        }
+        else if (IPV6_GROUP_REGEX.test(piece)) {
+            groups.push(parseInt(piece, 16));
+        }
+        else {
+            return null;
+        }
+    }
+    return groups;
+};
+/**
+ * Parse an IPv6 address to its 128-bit value.
+ *
+ * The grammar of Rust's `Ipv6Addr::from_str`: eight groups of one to four
+ * hex digits (either case), or fewer around a single `::` standing for one or
+ * more zero groups, the last two groups optionally written as a dotted-quad
+ * IPv4 address. No zone (`%eth0`) — callers strip it first.
+ *
+ * @returns the address as a `bigint` in `[0, 2^128)`, or `null` when `ip` isn't one
+ */
+export const parse_ipv6_bits = (ip) => {
+    const halves = ip.split('::');
+    let groups;
+    if (halves.length === 1) {
+        const all = parse_ipv6_groups(ip, true);
+        if (all === null || all.length !== 8)
+            return null;
+        groups = all;
+    }
+    else if (halves.length === 2) {
+        const head = parse_ipv6_groups(halves[0], false);
+        const tail = parse_ipv6_groups(halves[1], true);
+        if (head === null || tail === null || head.length + tail.length > 7)
+            return null;
+        groups = [...head, ...new Array(8 - head.length - tail.length).fill(0), ...tail];
+    }
+    else {
+        return null;
+    }
+    let bits = 0n;
+    for (const group of groups)
+        bits = (bits << 16n) | BigInt(group);
+    return bits;
+};
 /**
  * Allowed character set for a bare IP literal.
  *
@@ -86,39 +170,27 @@ export const IP_LITERAL_CHARS = /^[0-9a-fA-F.:]+$/;
 export const canonicalize_ip = (ip) => {
     const lowered = ip.toLowerCase();
     // Strict char-set filter — reject brackets, whitespace, control bytes,
-    // letters g-z before invoking the parser. Hono's `convertIPv6ToBinary`
-    // silently accepts `'::1\n'` and similar; canonicalizing those would
-    // erase the malformed form so downstream `validate_ip_strict` could no
-    // longer reject it. Pass-through preserves the original string.
+    // letters g-z, and `%` (so a zone) before invoking the parser, so a
+    // malformed form passes through for downstream `validate_ip_strict` to
+    // reject
     if (!IP_LITERAL_CHARS.test(lowered))
         return lowered;
-    const family = distinctRemoteAddr(lowered);
-    if (family === 'IPv4') {
-        // IPv4's dotted-decimal form is already canonical — no transform
-        // needed. Malformed forms (`999.999.999.999`) still pass through
-        // here; downstream `validate_ip_strict` rejects them via its own
-        // round-trip parse.
+    // IPv4's dotted-decimal form is already canonical — no transform needed.
+    // Malformed forms (`999.999.999.999`) fail both parsers and pass through.
+    if (parse_ipv4_bits(lowered) !== null)
         return lowered;
+    const bits = parse_ipv6_bits(lowered);
+    if (bits === null)
+        return lowered;
+    const canonical = ipv6_bigint_to_canonical(bits);
+    // Strip `::ffff:` only when the canonical form is dotted IPv4-mapped
+    // (`::ffff:X.X.X.X`). Pure IPv6 values that happen to start with
+    // `::ffff:` (e.g. `::ffff:1` → `0:0:0:0:0:0:ffff:1`, where group[5] is 0
+    // not 0xffff) emit without the dot and are preserved.
+    if (canonical.startsWith('::ffff:') && canonical.substring(7).includes('.')) {
+        return canonical.substring(7);
     }
-    if (family === 'IPv6') {
-        try {
-            const bits = convertIPv6ToBinary(lowered);
-            const canonical = ipv6_bigint_to_canonical(bits);
-            // Strip `::ffff:` only when the canonical form is dotted
-            // IPv4-mapped (`::ffff:X.X.X.X`). Pure IPv6 values that happen
-            // to start with `::ffff:` (e.g. `::ffff:1` → `0:0:0:0:0:0:ffff:1`,
-            // where group[5] is 0 not 0xffff) emit without the dot and
-            // are preserved.
-            if (canonical.startsWith('::ffff:') && canonical.substring(7).includes('.')) {
-                return canonical.substring(7);
-            }
-            return canonical;
-        }
-        catch {
-            return lowered;
-        }
-    }
-    return lowered;
+    return canonical;
 };
 /**
  * Convert a 128-bit IPv6 binary value into its RFC 5952 canonical string form.
@@ -132,7 +204,7 @@ export const canonicalize_ip = (ip) => {
  *
  * Pure helper exported for the test suite to exercise the
  * canonicalization invariants directly without a full
- * `convertIPv6ToBinary` round-trip.
+ * `parse_ipv6_bits` round-trip.
  *
  * @param bits - the 128-bit IPv6 value as `bigint`. Must satisfy `0n <= bits < 2n ** 128n`;
  *   throws `RangeError` otherwise. Silent truncation would mask caller bugs since the
@@ -226,17 +298,10 @@ export const rate_limit_ip_key = (ip) => {
     const canonical = canonicalize_ip(zone_at === -1 ? ip : ip.slice(0, zone_at));
     if (!IP_LITERAL_CHARS.test(canonical))
         return ip;
-    const family = distinctRemoteAddr(canonical);
-    if (family === 'IPv4')
+    if (parse_ipv4_bits(canonical) !== null)
         return canonical;
-    if (family !== 'IPv6')
+    const bits = parse_ipv6_bits(canonical);
+    if (bits === null)
         return ip;
-    let bits;
-    try {
-        bits = convertIPv6ToBinary(canonical);
-    }
-    catch {
-        return ip;
-    }
     return `${ipv6_bigint_to_canonical(bits & IPV6_PREFIX_64_MASK)}/64`;
 };

package/dist/server/serve_fact_route.d.ts

@@ -41,6 +41,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 +83,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
  *

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkHG;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"}

package/dist/server/serve_fact_route.js

@@ -41,6 +41,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 +83,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
  *

package/dist/testing/CLAUDE.md

@@ -968,7 +968,9 @@ source of truth for wire-shape conformance.
   gates `describe_fact_serving_cross_tests` (the cell-scoped per-reference +
   admin-only bare-hash fact-serving parity suite); like cells it stays off the
   declared surface and is `true` on every spine that mounts the serve routes +
-  the `_testing_put_fact` seeder. `ready` gates `describe_ready_cross_tests`
+  the `_testing_put_fact` seeder (whose optional `holder` records a
+  `fact_holder` row, so a non-admin can reference what it seeds) — it also
+  gates `describe_cell_ref_admission_cross_tests`. `ready` gates `describe_ready_cross_tests`
   (anonymous `GET /ready` → `200 {ready: true}` on a clean spine bootstrap);
   like cells/sse the `/ready` deploy gate stays off the declared surface, `true`
   on every spine that live-mounts it over the shared `expected_schema.json`.
@@ -1607,7 +1609,8 @@ are `src/test/auth/cell_crud_parity.db.test.ts`
   payload-expiry tests never reached. Daemon-token-gated like its siblings; the
   Rust mirror is `fuz_testing::create_testing_mint_session_action_spec`.
 
-  Also in the module and **not** bundled: `_testing_origin_check`
+  In the hono-free sibling `testing/cross_backend/testing_origin_check.ts`,
+  **not** bundled: `_testing_origin_check`
   (`create_testing_origin_check_action()`, `run_testing_origin_check(input)`,
   `TestingOriginCheckInput` / `TestingOriginCheckOutput`) — answers the origin
   allowlist's parse and request check for one `{patterns, origin}` pair:
@@ -1617,7 +1620,8 @@ are `src/test/auth/cell_crud_parity.db.test.ts`
   keeps an exact action-manifest gate; the spine binary appends it in
   `build_full_spine_rpc_actions`.
 
-  Also **not** bundled: `_testing_shorten_credential_expiry`
+  Back in `testing_reset_actions.ts`, also **not** bundled:
+  `_testing_shorten_credential_expiry`
   (`create_testing_shorten_credential_expiry_action()`) — pulls an account's
   `auth_session` and `api_token` expiries in to `seconds` (1–60) from now,
   shorten-only (`LEAST`, an eternal token gaining one), answering
@@ -1628,8 +1632,8 @@ are `src/test/auth/cell_crud_parity.db.test.ts`
   `_testing_origin_check`. The Rust mirror is
   `fuz_testing::create_testing_shorten_credential_expiry_action_spec`.
 
-  Also in the module — but **not** bundled by `create_testing_actions` —
-  `_testing_action_manifest` (+ `create_testing_action_manifest_action(mounted)`):
+  Also in `testing_reset_actions.ts` — but **not** bundled by
+  `create_testing_actions` — `_testing_action_manifest` (+ `create_testing_action_manifest_action(mounted)`):
   dumps the live RPC registry as a normalized `ActionManifest` for the
   cross-impl manifest-parity gate (see §Cross-impl RPC-manifest parity). It must
   enumerate _every_ mounted method, which `create_testing_actions` (one
@@ -1638,6 +1642,28 @@ are `src/test/auth/cell_crud_parity.db.test.ts`
   complete action list plus its own spec. Daemon-token-gated like its siblings;
   the Rust mirror is `fuz_testing::create_testing_action_manifest_action_spec`.
 
+### Cell ref admission parity — `cross_backend/cell_ref_admission.ts`
+
+`describe_cell_ref_admission_cross_tests({setup_test, capabilities, rpc_path?})`
+— possession-gated ref admission over real HTTP: a non-admin `cell_create`
+naming a stored fact it never put and one naming an unstored hash get one
+identical `403 cell_ref_not_held` (status + error body); a system-put fact is
+refused too; the uploader's public cell serves the bytes to anyone; a second
+actor putting identical bytes becomes a holder; an editor keeps refs another
+writer introduced and is refused adding (or restoring a dropped) unheld one; a
+shallow and a deep clone carry each row's source refs, while a patch adding an
+unheld ref or moving a child's ref onto the root is refused; the keeper (a
+global admin) is ungated; a grantee who read a fact through a granted cell
+can't name its hash in a cell of its own, before or after the revoke; the ref
+grammar is exact (prose, markup, `blake3:zz`, uppercase, object keys are not
+refs); and a hidden cell's update, a create under a hidden parent, and a clone
+of a hidden source answer `404` whatever `data` names. Facts are put through
+`cross_put_fact` (exported by `fact_serving.ts`), whose `holder` maps onto
+`_testing_put_fact`'s optional `holder` key. Gated on
+`capabilities.fact_serving`; cross-process only. fuz_app's own wiring is
+`src/test/cross_backend/cell_ref_admission.cross.test.ts`; the in-process
+cases are `src/test/auth/cell_ref_admission{,.fact_less}.db.test.ts`.
+
 ### Token-scope surface parity — `cross_backend/token_scope_surface.ts`
 
 `describe_token_scope_surface_cross_tests({setup_test, capabilities, rpc_path?,

package/dist/testing/cross_backend/cell_crud.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cell_crud.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/cell_crud.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA6D9B,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,YAAY,CAAC;AAG1E,eAAO,MAAM,8BAA8B,GAC1C,SAAS,uCAAuC,KAC9C,IA6fF,CAAC"}
+{"version":3,"file":"cell_crud.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/cell_crud.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA6D9B,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,YAAY,CAAC;AAG1E,eAAO,MAAM,8BAA8B,GAC1C,SAAS,uCAAuC,KAC9C,IAggBF,CAAC"}

package/dist/testing/cross_backend/cell_crud.js

@@ -100,14 +100,17 @@ export const describe_cell_crud_cross_tests = (options) => {
         });
         test_if(capabilities.cell_crud, 'refs are deduped and lexicographically sorted (deterministic, cross-impl-identical)', async () => {
             const fixture = await setup_test();
-            const owner = await fixture.create_account({ username: 'cell_refs_owner' });
             const t = fixture.fresh_transport();
-            const owner_headers = owner.create_session_headers();
+            // The keeper — a global admin, whom ref admission doesn't gate — so
+            // fabricated hashes nobody holds are writable refs (a non-admin
+            // writing them is `cell_ref_not_held`, the admission suite's
+            // subject), and the case runs on backends without the fact chain.
+            const owner_headers = fixture.create_session_headers();
             // Three valid distinct fact hashes that sort a < b < c, embedded in
             // `data` in a deliberately unsorted, nested, duplicated order. Both
             // spines must derive `refs` as the sorted [a, b, c] regardless of
             // traversal order or `HashSet` iteration — the byte-identical
-            // cross-backend contract (Rust `extract_refs` ↔ TS `derive_refs`).
+            // cross-backend contract (Rust `extract_refs` ↔ TS `derive_cell_refs`).
             const ref_a = `blake3:${'a'.repeat(64)}`;
             const ref_b = `blake3:${'b'.repeat(64)}`;
             const ref_c = `blake3:${'c'.repeat(64)}`;

package/dist/testing/cross_backend/cell_gated_create.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cell_gated_create.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/cell_gated_create.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAoE9B,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,YAAY,CAAC;AAqB1E,eAAO,MAAM,sCAAsC,GAClD,SAAS,uCAAuC,KAC9C,IAuTF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,eAAO,MAAM,kCAAkC,GAC9C,SAAS,uCAAuC,KAC9C,IA25BF,CAAC"}
+{"version":3,"file":"cell_gated_create.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/cell_gated_create.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAoE9B,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,YAAY,CAAC;AAqB1E,eAAO,MAAM,sCAAsC,GAClD,SAAS,uCAAuC,KAC9C,IAuTF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,eAAO,MAAM,kCAAkC,GAC9C,SAAS,uCAAuC,KAC9C,IAs6BF,CAAC"}