@fuzdev/fuz_app 0.75.0 → 0.77.0

package/dist/server/serve_fact_route.js

@@ -1,38 +1,67 @@
 /**
- * `GET /api/facts/:hash` — content-addressed fact serving.
+ * Content-addressed fact serving — cell-scoped, per-reference reads.
  *
- * 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.
+ * Two routes serve fact bytes from the PG-backed fact store:
+ *
+ * - `GET /api/cells/:cell_id/facts/:hash` — the **per-reference read**.
+ *   The request names the referencing cell. Authz is scoped to that one
+ *   reference: `can_view_cell(caller, cell) AND cell.refs includes hash`.
+ *   This is the path non-admin callers use, and the only path for
+ *   confidential content.
+ * - `GET /api/facts/:hash` — the **bare-hash read**, restricted to admins.
+ *
+ * Embedded facts stream from the `fact.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.
+ * ## Authorization — authz lives on the cell→fact edge, not the hash
+ *
+ * Facts are global, content-addressed, owner-less bytes: identical bytes
+ * from different owners dedup to **one** `fact` row. Keying access control
+ * on the bare hash therefore unions visibility across every owner that
+ * references it — A's private bytes leak the instant B references identical
+ * bytes from a public cell. The fix is to scope authz to the
+ * `(cell, hash)` edge: a caller reads a fact *through a specific cell it
+ * can view that references the hash*. Dedup becomes a pure storage
+ * optimization with zero authz consequence — whether two owners' bytes
+ * share a `fact` row is invisible to the read check.
+ *
+ * The cell-scoped route resolves the named cell, requires
+ * `can_view_cell(caller, cell)`, and requires `cell.refs` to include the
+ * 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 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.
+ * (Explicitly-public facts — a producer opting bytes into world-readable
+ * status — are a future refinement; there is no such concept today, so
+ * the bare-hash route stays strictly admin-gated.)
+ *
+ * Auth shape on the cell-scoped route is `{account: 'none', actor: 'none'}`
+ * — the dispatcher's authorization phase is skipped for pure-public routes,
+ * so the 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` and are admitted only by a `cell.visibility ===
+ * 'public'` cell. 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.
+ *
+ * 404 is the universal "not viewable" response: missing fact, missing or
+ * unviewable cell, or the cell doesn't reference the hash. We deliberately
+ * 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.
  *
  * ## Defense-in-depth
  *
@@ -47,151 +76,223 @@ 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 { Uuid } from '@fuzdev/fuz_util/id.js';
 import { z } from 'zod';
-import { build_request_context } from '../auth/request_context.js';
+import { build_request_context, get_request_context, has_role, } from '../auth/request_context.js';
+import { ROLE_ADMIN } from '../auth/role_schema.js';
+import { ActingActor } from '../http/auth_shape.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_get } from '../db/cell_queries.js';
 import { query_cell_grant_list_for_cell } from '../db/cell_grant_queries.js';
 import { can_view_cell } from '../auth/cell_authorize.js';
 import { 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.
+ * Path-param schema for the bare-hash route. 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 bare_hash_params_schema = z.strictObject({
+    hash: FactHashSchema,
+});
+/**
+ * Path-param schema for the cell-scoped route. `cell_id` validates as a
+ * `Uuid`; `hash` as the canonical fact-hash form. Malformed values 400 via
+ * the standard params-validation shape.
  */
-const params_schema = z.strictObject({
+const cell_fact_params_schema = z.strictObject({
+    cell_id: Uuid,
     hash: FactHashSchema,
 });
+/** Shared error-schema entry: tighten the auto-derived 400 to the literal emitted by params validation. */
+const params_400_error = {
+    400: z.looseObject({
+        error: z.literal(ERROR_INVALID_ROUTE_PARAMS),
+        issues: z.array(z.unknown()),
+    }),
+};
+/**
+ * Serve a fact's bytes by hash, after the caller has been authorized for it.
+ *
+ * This is the shared tail of both routes — it never re-checks authz, so it
+ * MUST only be called once the caller has been admitted (admin on the
+ * bare-hash route, viewable referencing cell on the cell-scoped route).
+ * Reuses the embedded-stream / `X-Accel-Redirect` / disk-stream logic.
+ *
+ * Returns 404 when the fact's metadata is missing or its embedded bytes
+ * have vanished (a race), so the response shape is identical whether the
+ * fact is genuinely absent or merely unviewable.
+ */
+const serve_fact_bytes = async (c, route, hash, config) => {
+    const { facts_dir, x_accel_redirect_prefix, log } = config;
+    const meta = await query_get_fact_meta({ db: route.db }, hash);
+    if (!meta) {
+        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,
+    });
+};
 /**
- * Build the `GET /api/facts/:hash` `RouteSpec`.
+ * Resolve the caller's `RequestContext` on a pure-public route from the
+ * session-middleware-set account id. Multi-actor accounts return `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. Unauthenticated callers return `null`.
+ */
+const build_public_request_context = async (c, route) => {
+    const account_id = c.get(ACCOUNT_ID_KEY);
+    if (!account_id)
+        return null;
+    const actors = await query_actors_by_account({ db: route.db }, account_id);
+    if (actors.length !== 1)
+        return null;
+    return build_request_context({ db: route.db }, account_id, actors[0].id);
+};
+/**
+ * Build the cell-scoped `GET /api/cells/:cell_id/facts/:hash` `RouteSpec`
+ * — the per-reference read.
+ *
+ * Resolves the named cell (404 if missing / soft-deleted), requires
+ * `can_view_cell(caller, cell)` AND `cell.refs` to include the hash
+ * (else 404, masked), then serves the bytes. Authz is scoped to this one
+ * `(cell, hash)` edge — never unioned across the fact's other referrers.
  *
  * 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.
+ * from `c.var.account_id` and enforces visibility per-reference.
  */
-export const create_serve_fact_route_spec = (options) => {
+export const create_serve_cell_fact_route_spec = (options) => {
     const { facts_dir, x_accel_redirect_prefix, log } = options;
+    const config = { facts_dir, x_accel_redirect_prefix, log };
     return {
         method: 'GET',
-        path: '/api/facts/:hash',
+        path: '/api/cells/:cell_id/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,
+        description: 'Serve content-addressed fact bytes through a named referencing cell. 404 unless the cell admits the caller via can_view_cell AND references the hash (per-reference, never union-of-referrers).',
+        params: cell_fact_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()),
-            }),
-        },
+        errors: params_400_error,
         handler: async (c, route) => {
-            const { hash } = get_route_params(c);
-            const meta = await query_get_fact_meta({ db: route.db }, hash);
-            if (!meta) {
+            const { cell_id, hash } = get_route_params(c);
+            // Resolve the named cell. Missing / soft-deleted → 404 (masked).
+            const cell = await query_cell_get({ db: route.db }, cell_id);
+            if (!cell) {
                 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.
+            // The cell→fact edge: the cell must actually reference the hash.
+            // `cell.refs` is auto-derived from `data` on every write, so this is
+            // the authoritative "does this cell reference these bytes" check.
+            // Missing edge → 404 (masked), never "exists elsewhere".
+            if (!cell.refs?.includes(hash)) {
                 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}`);
+            // Per-reference view check — scoped to *this* cell only.
+            const req_ctx = await build_public_request_context(c, route);
+            // Unauthenticated callers skip the grant fetch entirely — no grant
+            // can admit a null req_ctx (the only admit path is the
+            // public-visibility branch in `can_view_cell`, which doesn't read
+            // grants).
+            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)) {
+                // 404 (not 403) so an unviewable cell→fact edge doesn't leak.
                 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}`,
-                });
+            return serve_fact_bytes(c, route, hash, config);
+        },
+    };
+};
+/**
+ * Build the admin-only bare-hash `GET /api/facts/:hash` `RouteSpec`.
+ *
+ * An admin's reach already spans every cell, so serving by bare hash grants
+ * no escalation — the union concern that made this route a cross-owner leak
+ * for non-admins is vacuous for an admin. Non-admin callers are rejected at
+ * the auth phase (403) and never reach the handler. Confidential non-admin
+ * reads always go through the cell-scoped route above.
+ *
+ * Auth is `{account: 'required', actor: 'required', roles: ['admin']}` —
+ * the dispatcher's authorization phase resolves the acting actor and the
+ * post-authorization guard enforces the admin role before the handler runs.
+ * The handler re-checks `has_role(_, admin)` as defense-in-depth so a future
+ * mounting/auth-shape regression fails closed rather than serving by bare
+ * hash to a non-admin.
+ */
+export const create_serve_fact_route_spec = (options) => {
+    const { facts_dir, x_accel_redirect_prefix, log } = options;
+    const config = { facts_dir, x_accel_redirect_prefix, log };
+    return {
+        method: 'GET',
+        path: '/api/facts/:hash',
+        auth: { account: 'required', actor: 'required', roles: [ROLE_ADMIN] },
+        description: 'Serve content-addressed fact bytes by bare hash — admin only. Non-admin reads go through GET /api/cells/:cell_id/facts/:hash (per-reference).',
+        params: bare_hash_params_schema,
+        // `actor: 'required'` (implied by the admin role gate) needs the
+        // authorization phase to resolve an acting actor — registry-time
+        // invariant 2 requires the `acting?` slot. On a GET it lives on
+        // `query` (a multi-actor admin disambiguates via `?acting=<actor>`).
+        query: z.strictObject({ acting: ActingActor }),
+        input: z.null(),
+        // The body is a binary stream; no JSON output schema applies.
+        output: z.null(),
+        errors: params_400_error,
+        handler: async (c, route) => {
+            const { hash } = get_route_params(c);
+            // Defense-in-depth: the auth phase already gated this on the admin
+            // role, but re-check the resolved context so a mounting/auth-shape
+            // regression fails closed instead of serving by bare hash.
+            if (!has_role(get_request_context(c), ROLE_ADMIN)) {
+                return c.body(null, 404);
             }
-            // 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,
-            });
+            return serve_fact_bytes(c, route, hash, config);
         },
     };
 };

package/dist/testing/CLAUDE.md

@@ -574,7 +574,11 @@ auth-related routes (login/logout/verify/sessions/tokens/password/signup)
 and asserts `DEFAULT_INTEGRATION_ERROR_COVERAGE` (20%). Bootstrap is
 excluded because no describe block in this suite drives it — its declared
 codes would always be uncovered. Consumer-specific routes aren't exercised
-here either — they don't count against the baseline. Override with
+here either — they don't count against the baseline. 403 authorization
+denials (the credential-channel gate on `/logout` + `/password`, the invite
+gate on `/signup`) are likewise excluded via `ignore_statuses: [403]` — they're
+exercised by the conformance + attack-surface suites, not this lifecycle suite.
+Override with
 `error_coverage_min?: number` (set to `0` to skip the assertion — useful for
 minimal route sets whose declared error codes outpace the suite's
 denial-path drivers).
@@ -960,6 +964,35 @@ a `*.cross.test.ts`, never an in-process setup). Authed cookies come from the
 fresh-per-test keeper via `fixture.transport.cookies()`, not the stale
 globalSetup handle. fuz_app's own wiring is `src/test/cross_backend/ws.cross.test.ts`.
 
+### `cross_backend/role_grant_offer_notification_ws.ts` — `describe_role_grant_offer_notification_ws_tests`
+
+Real-upgrade coverage of the consentful-role-grants WS notification fan-out —
+the seven server-initiated notifications (`received` → recipient,
+`accepted`/`declined` → grantor, `retracted` → recipient, flat
+`role_grant_revoke` → revokee, and `role_grant_offer_supersede` → each
+superseded sibling's grantor on **both** the accept- and revoke-cascade paths).
+`describe_role_grant_offer_notification_ws_tests({setup_test, capabilities,
+base_url, ws_path})` opens the affected counterparty's socket
+(`create_ws_transport`), drives the lifecycle RPC over `fixture.transport`, then
+strict-parses the delivered frame against its canonical params schema from
+`auth/role_grant_offer_notifications.ts` (the guard against serialization drift —
+field / null / datetime / the flat revoke shape / the supersede `reason` +
+`cause_id`). Unlike `describe_cross_process_ws_tests` (consumer-agnostic,
+`heartbeat`-only), this drives a real **domain** notification family — but one
+built from spine primitives only (accounts / role-grants / offers / WS), zero
+consumer domain, so it lives here and runs against any backend that wires the
+standard RPC actions' `notification_sender` and registers a WS socket: fuz_app's
+own spine self-tests (`testing_spine_server`, whose `ws_transport` is threaded
+as the sender via `spine_rpc_endpoints({notification_sender})`; the Rust
+`testing_spine_stub`, which wires it natively) and downstream twin-impl
+consumers (fuz_forge's Deno + Rust backends call it as a thin invocation).
+Sends queue on the post-commit drain, so `WsClient.wait_for` polls + waits
+(method + predicate filter ignores unrelated frames). Accounts are seeded with
+`ROLE_ADMIN` (the only admin-grantable role) so they can open an admin-gated WS
+where one exists (forge) and be offered the role; harmless on the auth-only
+spine. Gated on `capabilities.ws`; cross-process only. fuz_app's own wiring is
+`src/test/cross_backend/role_grant_offer_notification_ws.cross.test.ts`.
+
 ### `cross_backend/sse_round_trip.ts` — `describe_cross_process_sse_tests`
 
 Cross-process counterpart to the in-process `sse_round_trip.ts` harness —

package/dist/testing/cross_backend/default_spine_surface.d.ts

@@ -1,4 +1,5 @@
 import '../assert_dev_env.js';
+import type { NotificationSender } from '../../auth/role_grant_offer_notifications.js';
 import { type RoleSchemaResult } from '../../auth/role_schema.js';
 import { type SessionOptions } from '../../auth/session_cookie.js';
 import { type RouteSpec } from '../../http/route_spec.js';
@@ -35,6 +36,26 @@ export declare const SPINE_RPC_PATH = "/api/rpc";
  * surface stub leaves `ctx.audit_sse` null so the snapshot stays SSE-free.
  */
 export declare const SPINE_SSE_PATH = "/api/admin/audit/stream";
+/** Options for {@link spine_rpc_endpoints}. */
+export interface SpineRpcEndpointsOptions {
+    /**
+     * WS notification sender threaded into the role-grant-offer sub-factory for
+     * server-initiated fan-out (`role_grant_offer_received` / `_accepted` /
+     * `_declined` / `_retracted` / `_supersede`, flat `role_grant_revoke`).
+     *
+     * **Shared-instance trap.** Pass the SAME `BackendWebsocketTransport`
+     * instance the WS endpoint registers connections against — the transport
+     * *is* the connection registry, so a separate instance would fan out to an
+     * empty registry and reach nobody (silently). The TS spine binary
+     * constructs one `ws_transport` and threads it both here and into
+     * `register_ws_endpoint`.
+     *
+     * Omitted (the default) for the shared `create_spine_surface_spec` path —
+     * surface generation doesn't depend on it, and it must stay absent there so
+     * the declared snapshot is unaffected.
+     */
+    readonly notification_sender?: NotificationSender | null;
+}
 /**
  * Factory-form RPC endpoints over the per-test `ctx.deps`. `create_app_server`
  * (in the binary) owns live dispatch; the surface builder invokes the factory
@@ -45,8 +66,12 @@ export declare const SPINE_SSE_PATH = "/api/admin/audit/stream";
  * `actions` (see `testing_reset_actions.ts`); it is intentionally excluded
  * here so it stays off the declared surface (the harness calls it directly
  * over the daemon-token channel).
+ *
+ * `options.notification_sender`, when supplied, reaches the role-grant-offer
+ * sub-factory so the spine emits the WS notification family — see
+ * `SpineRpcEndpointsOptions`.
  */
-export declare const spine_rpc_endpoints: (ctx: AppServerContext) => Array<RpcEndpointSpec>;
+export declare const spine_rpc_endpoints: (ctx: AppServerContext, options?: SpineRpcEndpointsOptions) => Array<RpcEndpointSpec>;
 /**
  * Account REST + signup route specs under `/api/account` (bootstrap
  * auto-mounted by the surface builder / `create_app_server`), plus the

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

@@ -1 +1 @@
-{"version":3,"file":"default_spine_surface.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/default_spine_surface.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA6B9B,OAAO,EAAqB,KAAK,gBAAgB,EAAC,MAAM,2BAA2B,CAAC;AACpF,OAAO,EAAwB,KAAK,cAAc,EAAC,MAAM,8BAA8B,CAAC;AAGxF,OAAO,EAAqB,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAC5E,OAAO,KAAK,EAAC,cAAc,EAAE,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAC3E,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,4BAA4B,CAAC;AAGjE;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,cAAc,CAAC,MAAM,CAAwC,CAAC;AAElG;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AAEpD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,gBAExB,CAAC;AAEH,iEAAiE;AACjE,eAAO,MAAM,cAAc,aAAa,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,4BAA4B,CAAC;AAExD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,gBAAgB,KAAG,KAAK,CAAC,eAAe,CAOhF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GAAI,KAAK,gBAAgB,KAAG,KAAK,CAAC,SAAS,CAiB/E,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,QAAO,cAM1C,CAAC"}
+{"version":3,"file":"default_spine_surface.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/default_spine_surface.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA6B9B,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,8CAA8C,CAAC;AACrF,OAAO,EAAqB,KAAK,gBAAgB,EAAC,MAAM,2BAA2B,CAAC;AACpF,OAAO,EAAwB,KAAK,cAAc,EAAC,MAAM,8BAA8B,CAAC;AAGxF,OAAO,EAAqB,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAC5E,OAAO,KAAK,EAAC,cAAc,EAAE,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAC3E,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,4BAA4B,CAAC;AAGjE;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,cAAc,CAAC,MAAM,CAAwC,CAAC;AAElG;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AAEpD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,gBAExB,CAAC;AAEH,iEAAiE;AACjE,eAAO,MAAM,cAAc,aAAa,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,4BAA4B,CAAC;AAExD,+CAA+C;AAC/C,MAAM,WAAW,wBAAwB;IACxC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACzD;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,GAC/B,KAAK,gBAAgB,EACrB,UAAU,wBAAwB,KAChC,KAAK,CAAC,eAAe,CAQvB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GAAI,KAAK,gBAAgB,KAAG,KAAK,CAAC,SAAS,CAiB/E,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,QAAO,cAM1C,CAAC"}

package/dist/testing/cross_backend/default_spine_surface.js

@@ -74,13 +74,15 @@ export const SPINE_SSE_PATH = '/api/admin/audit/stream';
  * `actions` (see `testing_reset_actions.ts`); it is intentionally excluded
  * here so it stays off the declared surface (the harness calls it directly
  * over the daemon-token channel).
+ *
+ * `options.notification_sender`, when supplied, reaches the role-grant-offer
+ * sub-factory so the spine emits the WS notification family — see
+ * `SpineRpcEndpointsOptions`.
  */
-export const spine_rpc_endpoints = (ctx) => [
+export const spine_rpc_endpoints = (ctx, options) => [
     {
         path: SPINE_RPC_PATH,
-        actions: create_standard_rpc_actions(ctx.deps, {
-            roles: spine_roles,
-        }),
+        actions: create_standard_rpc_actions({ ...ctx.deps, notification_sender: options?.notification_sender ?? null }, { roles: spine_roles }),
     },
 ];
 /**

package/dist/testing/cross_backend/role_grant_offer_notification_ws.d.ts

@@ -0,0 +1,24 @@
+import '../assert_dev_env.js';
+import { type BackendCapabilities } from './capabilities.js';
+import type { SetupTest } from './setup.js';
+/** Configuration for {@link describe_role_grant_offer_notification_ws_tests}. */
+export interface RoleGrantOfferNotificationWsTestOptions {
+    /** Per-test fixture producer (`default_cross_process_setup(handle, ...)`). */
+    readonly setup_test: SetupTest;
+    /** Backend capability flags; every case gates on `capabilities.ws`. */
+    readonly capabilities: BackendCapabilities;
+    /** Base URL the backend is reachable at (e.g. `http://localhost:1178`). */
+    readonly base_url: string;
+    /** WebSocket endpoint path on the backend (e.g. `/api/ws`). */
+    readonly ws_path: string;
+}
+/**
+ * Register the role-grant-offer WS notification suite — seven cases over a real
+ * upgrade, one per server-initiated notification (received / accepted /
+ * declined / retracted / revoke + supersede on both the accept and revoke
+ * cascades). Each opens the affected counterparty's socket, drives the
+ * lifecycle RPC, and strict-parses the delivered frame against its canonical
+ * params schema. Gated on `capabilities.ws`.
+ */
+export declare const describe_role_grant_offer_notification_ws_tests: (options: RoleGrantOfferNotificationWsTestOptions) => void;
+//# sourceMappingURL=role_grant_offer_notification_ws.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"role_grant_offer_notification_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/role_grant_offer_notification_ws.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAqE9B,OAAO,EAAC,KAAK,mBAAmB,EAAU,MAAM,mBAAmB,CAAC;AACpE,OAAO,KAAK,EAAC,SAAS,EAAkC,MAAM,YAAY,CAAC;AAK3E,iFAAiF;AACjF,MAAM,WAAW,uCAAuC;IACvD,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,+CAA+C,GAC3D,SAAS,uCAAuC,KAC9C,IA8VF,CAAC"}