@fuzdev/fuz_app 0.67.1 → 0.69.0

package/dist/auth/cell_item_action_specs.js

@@ -0,0 +1,182 @@
+/**
+ * Cell-item RPC specs — declarative contract for the four ordered-child
+ * verbs (`insert` / `move` / `delete` / `list`).
+ *
+ * `(parent_id, position) → child_id` rows. `position` is opaque text
+ * (fractional-indexing key); the wire validates the alphabet
+ * (`^[0-9A-Za-z]+$`) and length, the lex-ordering invariant is the
+ * client's contract.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { Uuid } from '@fuzdev/fuz_util/id.js';
+import { FRACTIONAL_INDEX_LENGTH_MAX, FRACTIONAL_INDEX_REGEX, } from '@fuzdev/fuz_util/fractional_index.js';
+import { ActingActor } from '../http/auth_shape.js';
+// -- Error reasons ----------------------------------------------------------
+/** Error reason — `cell_item_list` got neither `parent_id` nor `child_id`. */
+export const ERROR_CELL_ITEM_LIST_REQUIRES_PARENT_OR_CHILD = 'cell_item_list_requires_parent_or_child';
+/**
+ * Error reason — `(parent_id, position)` collision on `cell_item_insert`
+ * or `cell_item_move`. Surfaces when two clients computed the same
+ * fractional-indexing key (rare given helper-side jitter; the safety
+ * net for the residual race). Client refreshes its bracket and retries.
+ */
+export const ERROR_CELL_ITEM_POSITION_TAKEN = 'cell_item_position_taken';
+// -- Shared schemas ---------------------------------------------------------
+/**
+ * Position grammar — base62 fractional-indexing key. Wire enforces
+ * non-empty, alphabet only, and the helper's `FRACTIONAL_INDEX_LENGTH_MAX`
+ * cap (well above realistic lengths even for hundreds of consecutive
+ * front-inserts; set high to avoid arbitrary cliffs). Lex ordering is the
+ * contract; the no-trailing-`'0'` invariant lives in the helper, not the
+ * wire.
+ */
+export const CellItemPosition = z
+    .string()
+    .min(1)
+    .max(FRACTIONAL_INDEX_LENGTH_MAX)
+    .regex(FRACTIONAL_INDEX_REGEX)
+    .brand('CellItemPosition');
+/**
+ * Wire-format for a `cell_item` row.
+ *
+ * `position` is branded `CellItemPosition` so consumers that round-trip
+ * the value back into a `position_after` / `position` input field don't
+ * need a cast at every call site. Wire ingress is validated by the
+ * `CellItemPosition` Zod schema (alphabet + length); wire egress trusts
+ * the DB CHECK constraint that backs `cell_item.position`, so the
+ * server-side `to_item_json` casts a raw string from `CellItemRow`.
+ */
+export const ItemJson = z.strictObject({
+    parent_id: Uuid,
+    position: CellItemPosition,
+    child_id: Uuid,
+    created_at: z.string(),
+});
+// -- cell_item_insert -------------------------------------------------------
+/**
+ * Input for `cell_item_insert`. Caller computes `position` via
+ * `fractional_index_between(prev, next)` (`@fuzdev/fuz_util/fractional_index.js`)
+ * client-side. Returns `cell_item_position_taken` on `(parent_id,
+ * position)` unique violation; client refreshes bracket and retries.
+ */
+export const CellItemInsertInput = z.strictObject({
+    parent_id: Uuid.meta({ description: 'Cell to insert into.' }),
+    child_id: Uuid.meta({ description: 'Cell to insert as a child.' }),
+    position: CellItemPosition.meta({
+        description: 'Fractional-indexing key. Client-computed via `fractional_index_between`.',
+    }),
+    acting: ActingActor,
+});
+export const CellItemInsertOutput = z.strictObject({ item: ItemJson });
+// -- cell_item_move ---------------------------------------------------------
+/**
+ * Input for `cell_item_move`. Move within the same parent (cross-parent
+ * moves are a future extension).
+ */
+export const CellItemMoveInput = z.strictObject({
+    parent_id: Uuid.meta({ description: 'Parent cell.' }),
+    position: CellItemPosition.meta({ description: 'Current position of the row to move.' }),
+    new_position: CellItemPosition.meta({ description: 'New fractional-indexing key.' }),
+    acting: ActingActor,
+});
+export const CellItemMoveOutput = z.strictObject({ item: ItemJson });
+// -- cell_item_delete -------------------------------------------------------
+/** Input for `cell_item_delete`. Idempotent on the slot key. */
+export const CellItemDeleteInput = z.strictObject({
+    parent_id: Uuid.meta({ description: 'Parent cell.' }),
+    position: CellItemPosition.meta({ description: 'Slot to delete.' }),
+    acting: ActingActor,
+});
+export const CellItemDeleteOutput = z.strictObject({
+    ok: z.literal(true),
+    deleted: z.boolean(),
+});
+// -- cell_item_list ---------------------------------------------------------
+/**
+ * Input for `cell_item_list`. Pass `parent_id` for forward items or
+ * `child_id` for reverse lists — exactly one. Reverse listing has 2-layer
+ * authz (child view-check gates the call; per-parent view-check filters
+ * the rows).
+ *
+ * Forward listing supports cursor pagination via `position_after`
+ * (return rows with `position > position_after`). The reverse listing
+ * doesn't paginate (the result set is small in practice — number of
+ * parents containing a given child).
+ */
+export const CellItemListInput = z
+    .strictObject({
+    parent_id: Uuid.optional().meta({
+        description: 'List forward items whose parent is this cell.',
+    }),
+    child_id: Uuid.optional().meta({
+        description: 'List reverse parents whose child is this cell.',
+    }),
+    position_after: CellItemPosition.optional().meta({
+        description: 'Cursor for forward pagination — return rows whose position > this.',
+    }),
+    limit: z.number().int().positive().max(500).optional().meta({
+        description: 'Page size cap (max 500). Omit for unbounded — explicit list calls escape the bundled `cell_get` cap.',
+    }),
+    acting: ActingActor,
+})
+    .refine((v) => Boolean(v.parent_id) !== Boolean(v.child_id), {
+    message: ERROR_CELL_ITEM_LIST_REQUIRES_PARENT_OR_CHILD,
+});
+export const CellItemListOutput = z.strictObject({
+    items: z.array(ItemJson),
+});
+// -- Action specs -----------------------------------------------------------
+export const cell_item_insert_action_spec = {
+    method: 'cell_item_insert',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { account: 'required', actor: 'required' },
+    side_effects: true,
+    input: CellItemInsertInput,
+    output: CellItemInsertOutput,
+    async: true,
+    description: 'Insert a cell as an ordered child at `position` under `parent`. Caller must be able to edit `parent` and view `child`. Returns `cell_item_position_taken` on `(parent_id, position)` unique violation; client refreshes bracket and retries.',
+};
+export const cell_item_move_action_spec = {
+    method: 'cell_item_move',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { account: 'required', actor: 'required' },
+    side_effects: true,
+    input: CellItemMoveInput,
+    output: CellItemMoveOutput,
+    async: true,
+    description: 'Move an item within its parent to a new position. Caller must be able to edit `parent`. Returns `cell_item_position_taken` on the new-position unique violation.',
+};
+export const cell_item_delete_action_spec = {
+    method: 'cell_item_delete',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { account: 'required', actor: 'required' },
+    side_effects: true,
+    input: CellItemDeleteInput,
+    output: CellItemDeleteOutput,
+    async: true,
+    description: 'Delete the item at `(parent, position)`. Idempotent — `deleted: false` when no row matched. Caller must be able to edit `parent`.',
+};
+export const cell_item_list_action_spec = {
+    method: 'cell_item_list',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { account: 'optional', actor: 'optional' },
+    side_effects: false,
+    input: CellItemListInput,
+    output: CellItemListOutput,
+    async: true,
+    rate_limit: 'ip',
+    description: 'List forward items (pass `parent_id`) or reverse parents (pass `child_id`). Forward listing filters children to those the caller may view (strict target-visibility). Reverse listing has 2-layer authz: gate on `can_view_cell(child)` first (404 otherwise), then filter rows by per-parent `can_view_cell`. Per-IP rate-limited — symmetric with `cell_get` to bound public-surface id-walking.',
+};
+/** All cell_item action specs — composed into `all_cell_action_specs`. */
+export const all_cell_item_action_specs = [
+    cell_item_insert_action_spec,
+    cell_item_move_action_spec,
+    cell_item_delete_action_spec,
+    cell_item_list_action_spec,
+];

package/dist/auth/cell_item_actions.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Cell-item RPC handlers.
+ *
+ * Four `request_response` actions bound to the specs in
+ * `./cell_item_action_specs.ts`:
+ *
+ * - `cell_item_insert` — admin / owner / editor-grant on `parent` may
+ *   insert; `child` must be view-admitted. Returns
+ *   `cell_item_position_taken` on `(parent_id, position)` unique
+ *   violation; client refreshes bracket and retries.
+ * - `cell_item_move` — admin / owner / editor-grant on `parent`. Same
+ *   collision-error shape as insert.
+ * - `cell_item_delete` — admin / owner / editor-grant on `parent`.
+ *   Idempotent: `deleted: false` when no row matched.
+ * - `cell_item_list` — bidirectional. Forward (pass `parent_id`) is
+ *   gated on `can_view_cell(parent)` and filters children to those the
+ *   caller may view (strict target-visibility, batched). Reverse (pass
+ *   `child_id`) has 2-layer authz: gate on `can_view_cell(child)`, then
+ *   filter rows by `can_view_cell(parent)`.
+ *
+ * IDOR-mask 404s on cell-miss / cell-unviewable, mirroring the existence-
+ * leak guards in `cell_actions.ts`.
+ *
+ * Audit events `cell_item_insert` / `cell_item_move` / `cell_item_delete`
+ * carry IDs only — see `./cell_item_audit_metadata.ts`.
+ *
+ * @module
+ */
+import { type RpcAction } from '../actions/action_rpc.js';
+import type { RouteFactoryDeps } from './deps.js';
+import { type ItemJson } from './cell_item_action_specs.js';
+import { type CellItemRow } from '../db/cell_item_queries.js';
+export type CellItemActionDeps = Pick<RouteFactoryDeps, 'log' | 'audit'>;
+export declare const to_item_json: (row: CellItemRow) => ItemJson;
+/** Create the four `cell_item_*` RPC actions. */
+export declare const create_cell_item_actions: (deps: CellItemActionDeps) => Array<RpcAction>;
+//# sourceMappingURL=cell_item_actions.d.ts.map

package/dist/auth/cell_item_actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell_item_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cell_item_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,0BAA0B,CAAC;AAGlC,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAEhD,OAAO,EAeN,KAAK,QAAQ,EACb,MAAM,6BAA6B,CAAC;AAMrC,OAAO,EAMN,KAAK,WAAW,EAChB,MAAM,4BAA4B,CAAC;AAOpC,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,OAAO,CAAC,CAAC;AAEzE,eAAO,MAAM,YAAY,GAAI,KAAK,WAAW,KAAG,QAS9C,CAAC;AAOH,iDAAiD;AACjD,eAAO,MAAM,wBAAwB,GAAI,MAAM,kBAAkB,KAAG,KAAK,CAAC,SAAS,CA2KlF,CAAC"}

package/dist/auth/cell_item_actions.js

@@ -0,0 +1,204 @@
+/**
+ * Cell-item RPC handlers.
+ *
+ * Four `request_response` actions bound to the specs in
+ * `./cell_item_action_specs.ts`:
+ *
+ * - `cell_item_insert` — admin / owner / editor-grant on `parent` may
+ *   insert; `child` must be view-admitted. Returns
+ *   `cell_item_position_taken` on `(parent_id, position)` unique
+ *   violation; client refreshes bracket and retries.
+ * - `cell_item_move` — admin / owner / editor-grant on `parent`. Same
+ *   collision-error shape as insert.
+ * - `cell_item_delete` — admin / owner / editor-grant on `parent`.
+ *   Idempotent: `deleted: false` when no row matched.
+ * - `cell_item_list` — bidirectional. Forward (pass `parent_id`) is
+ *   gated on `can_view_cell(parent)` and filters children to those the
+ *   caller may view (strict target-visibility, batched). Reverse (pass
+ *   `child_id`) has 2-layer authz: gate on `can_view_cell(child)`, then
+ *   filter rows by `can_view_cell(parent)`.
+ *
+ * IDOR-mask 404s on cell-miss / cell-unviewable, mirroring the existence-
+ * leak guards in `cell_actions.ts`.
+ *
+ * Audit events `cell_item_insert` / `cell_item_move` / `cell_item_delete`
+ * carry IDs only — see `./cell_item_audit_metadata.ts`.
+ *
+ * @module
+ */
+import { rpc_action, } from '../actions/action_rpc.js';
+import { jsonrpc_errors } from '../http/jsonrpc_errors.js';
+import { is_pg_unique_violation } from '../db/pg_error.js';
+import { cell_item_insert_action_spec, cell_item_move_action_spec, cell_item_delete_action_spec, cell_item_list_action_spec, ERROR_CELL_ITEM_POSITION_TAKEN, } from './cell_item_action_specs.js';
+import { ERROR_CELL_NOT_FOUND } from './cell_action_specs.js';
+import { can_view_cell, can_edit_cell } from './cell_authorize.js';
+import { filter_visible_target_ids } from './cell_relation_visibility.js';
+import { query_cell_get } from '../db/cell_queries.js';
+import { query_cell_grant_list_for_cell } from '../db/cell_grant_queries.js';
+import { query_cell_item_insert, query_cell_item_move, query_cell_item_delete, query_cell_item_list_for_parent, query_cell_item_list_for_child, } from '../db/cell_item_queries.js';
+export const to_item_json = (row) => ({
+    parent_id: row.parent_id,
+    // `cell.position` is a DB-shape string; brand at the wire boundary so
+    // consumers can round-trip it without casting (the DB CHECK constraint
+    // is the runtime validator on egress, the Zod brand is the validator
+    // on ingress).
+    position: row.position,
+    child_id: row.child_id,
+    created_at: typeof row.created_at === 'string' ? row.created_at : row.created_at.toISOString(),
+});
+const position_taken_error = () => jsonrpc_errors.invalid_params('cell_item position taken', {
+    reason: ERROR_CELL_ITEM_POSITION_TAKEN,
+});
+/** Create the four `cell_item_*` RPC actions. */
+export const create_cell_item_actions = (deps) => {
+    const insert_handler = async (input, ctx) => {
+        const auth = ctx.auth;
+        const parent = await query_cell_get(ctx, input.parent_id);
+        if (!parent) {
+            throw jsonrpc_errors.not_found('cell', { reason: ERROR_CELL_NOT_FOUND });
+        }
+        const parent_grants = await query_cell_grant_list_for_cell(ctx, parent.id);
+        if (!can_edit_cell(auth, parent, parent_grants)) {
+            throw jsonrpc_errors.not_found('cell', { reason: ERROR_CELL_NOT_FOUND });
+        }
+        const child = await query_cell_get(ctx, input.child_id);
+        if (!child) {
+            throw jsonrpc_errors.not_found('cell', { reason: ERROR_CELL_NOT_FOUND });
+        }
+        // Child must be view-admitted — otherwise insert leaks existence.
+        const child_grants = await query_cell_grant_list_for_cell(ctx, child.id);
+        if (!can_view_cell(auth, child, child_grants)) {
+            throw jsonrpc_errors.not_found('cell', { reason: ERROR_CELL_NOT_FOUND });
+        }
+        let row;
+        try {
+            row = await query_cell_item_insert(ctx, {
+                parent_id: input.parent_id,
+                position: input.position,
+                child_id: input.child_id,
+            });
+        }
+        catch (err) {
+            if (is_pg_unique_violation(err))
+                throw position_taken_error();
+            throw err;
+        }
+        deps.audit.emit(ctx, {
+            event_type: 'cell_item_insert',
+            actor_id: auth.actor.id,
+            account_id: auth.account.id,
+            ip: ctx.client_ip,
+            metadata: {
+                parent_id: row.parent_id,
+                position: row.position,
+                child_id: row.child_id,
+            },
+        });
+        return { item: to_item_json(row) };
+    };
+    const move_handler = async (input, ctx) => {
+        const auth = ctx.auth;
+        const parent = await query_cell_get(ctx, input.parent_id);
+        if (!parent) {
+            throw jsonrpc_errors.not_found('cell', { reason: ERROR_CELL_NOT_FOUND });
+        }
+        const parent_grants = await query_cell_grant_list_for_cell(ctx, parent.id);
+        if (!can_edit_cell(auth, parent, parent_grants)) {
+            throw jsonrpc_errors.not_found('cell', { reason: ERROR_CELL_NOT_FOUND });
+        }
+        let row;
+        try {
+            row = await query_cell_item_move(ctx, input.parent_id, input.position, input.new_position);
+        }
+        catch (err) {
+            if (is_pg_unique_violation(err))
+                throw position_taken_error();
+            throw err;
+        }
+        if (!row) {
+            // Source row missing — raced with deleter. 404 covers the gap.
+            throw jsonrpc_errors.not_found('cell_item', { reason: ERROR_CELL_NOT_FOUND });
+        }
+        deps.audit.emit(ctx, {
+            event_type: 'cell_item_move',
+            actor_id: auth.actor.id,
+            account_id: auth.account.id,
+            ip: ctx.client_ip,
+            metadata: {
+                parent_id: row.parent_id,
+                position_old: input.position,
+                position_new: row.position,
+            },
+        });
+        return { item: to_item_json(row) };
+    };
+    const delete_handler = async (input, ctx) => {
+        const auth = ctx.auth;
+        const parent = await query_cell_get(ctx, input.parent_id);
+        if (!parent) {
+            throw jsonrpc_errors.not_found('cell', { reason: ERROR_CELL_NOT_FOUND });
+        }
+        const parent_grants = await query_cell_grant_list_for_cell(ctx, parent.id);
+        if (!can_edit_cell(auth, parent, parent_grants)) {
+            throw jsonrpc_errors.not_found('cell', { reason: ERROR_CELL_NOT_FOUND });
+        }
+        const deleted = await query_cell_item_delete(ctx, input.parent_id, input.position);
+        if (deleted) {
+            deps.audit.emit(ctx, {
+                event_type: 'cell_item_delete',
+                actor_id: auth.actor.id,
+                account_id: auth.account.id,
+                ip: ctx.client_ip,
+                metadata: {
+                    parent_id: deleted.parent_id,
+                    position: deleted.position,
+                    child_id: deleted.child_id,
+                },
+            });
+        }
+        return { ok: true, deleted: deleted !== null };
+    };
+    const list_handler = async (input, ctx) => {
+        const auth = ctx.auth;
+        // Forward listing: gate on can_view_cell(parent), then filter the
+        // children to those the caller may view (strict target-visibility).
+        if (input.parent_id !== undefined) {
+            const parent = await query_cell_get(ctx, input.parent_id);
+            if (!parent) {
+                throw jsonrpc_errors.not_found('cell', { reason: ERROR_CELL_NOT_FOUND });
+            }
+            const parent_grants = auth ? await query_cell_grant_list_for_cell(ctx, parent.id) : null;
+            if (!can_view_cell(auth, parent, parent_grants)) {
+                throw jsonrpc_errors.not_found('cell', { reason: ERROR_CELL_NOT_FOUND });
+            }
+            const rows = await query_cell_item_list_for_parent(ctx, parent.id, {
+                limit: input.limit,
+                position_after: input.position_after,
+            });
+            const visible_children = await filter_visible_target_ids(ctx, auth, rows.map((r) => r.child_id));
+            return { items: rows.filter((r) => visible_children.has(r.child_id)).map(to_item_json) };
+        }
+        // Reverse listing: 2-layer authz. First, can_view_cell(child).
+        const child = await query_cell_get(ctx, input.child_id);
+        if (!child) {
+            throw jsonrpc_errors.not_found('cell', { reason: ERROR_CELL_NOT_FOUND });
+        }
+        const child_grants = auth ? await query_cell_grant_list_for_cell(ctx, child.id) : null;
+        if (!can_view_cell(auth, child, child_grants)) {
+            throw jsonrpc_errors.not_found('cell', { reason: ERROR_CELL_NOT_FOUND });
+        }
+        // Then filter rows by per-parent can_view_cell. Batched (not N+1):
+        // one bulk visibility filter over all parent ids, same as the forward
+        // branch. Bounded by `limit` at the query so a heavily inbound-linked
+        // child can't force an unbounded fetch on this public endpoint.
+        const rows = await query_cell_item_list_for_child(ctx, child.id, { limit: input.limit });
+        const visible_parents = await filter_visible_target_ids(ctx, auth, rows.map((r) => r.parent_id));
+        return { items: rows.filter((r) => visible_parents.has(r.parent_id)).map(to_item_json) };
+    };
+    return [
+        rpc_action(cell_item_insert_action_spec, insert_handler),
+        rpc_action(cell_item_move_action_spec, move_handler),
+        rpc_action(cell_item_delete_action_spec, delete_handler),
+        rpc_action(cell_item_list_action_spec, list_handler),
+    ];
+};

package/dist/auth/cell_item_audit_metadata.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Audit-log metadata schemas for `cell_item_insert` / `_move` / `_delete`.
+ *
+ * IDs only (positions are opaque text, not user-derived; safe to log).
+ * Apps register these via `extra_events:` on `create_audit_log_config`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Metadata envelope for `cell_item_insert`. */
+export declare const CellItemInsertAuditMetadata: z.ZodObject<{
+    parent_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    position: z.ZodString;
+    child_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+}, z.core.$loose>;
+export type CellItemInsertAuditMetadata = z.infer<typeof CellItemInsertAuditMetadata>;
+/**
+ * Metadata envelope for `cell_item_move`. Carries both old and new
+ * position so the audit trail shows the reorder without a join back to
+ * the live row.
+ */
+export declare const CellItemMoveAuditMetadata: z.ZodObject<{
+    parent_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    position_old: z.ZodString;
+    position_new: z.ZodString;
+}, z.core.$loose>;
+export type CellItemMoveAuditMetadata = z.infer<typeof CellItemMoveAuditMetadata>;
+/** Metadata envelope for `cell_item_delete`. */
+export declare const CellItemDeleteAuditMetadata: z.ZodObject<{
+    parent_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    position: z.ZodString;
+    child_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+}, z.core.$loose>;
+export type CellItemDeleteAuditMetadata = z.infer<typeof CellItemDeleteAuditMetadata>;
+//# sourceMappingURL=cell_item_audit_metadata.d.ts.map

package/dist/auth/cell_item_audit_metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell_item_audit_metadata.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cell_item_audit_metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAGtB,gDAAgD;AAChD,eAAO,MAAM,2BAA2B;;;;iBAItC,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEtF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;;;;iBAIpC,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,gDAAgD;AAChD,eAAO,MAAM,2BAA2B;;;;iBAItC,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC"}

package/dist/auth/cell_item_audit_metadata.js

@@ -0,0 +1,32 @@
+/**
+ * Audit-log metadata schemas for `cell_item_insert` / `_move` / `_delete`.
+ *
+ * IDs only (positions are opaque text, not user-derived; safe to log).
+ * Apps register these via `extra_events:` on `create_audit_log_config`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { Uuid } from '@fuzdev/fuz_util/id.js';
+/** Metadata envelope for `cell_item_insert`. */
+export const CellItemInsertAuditMetadata = z.looseObject({
+    parent_id: Uuid,
+    position: z.string(),
+    child_id: Uuid,
+});
+/**
+ * Metadata envelope for `cell_item_move`. Carries both old and new
+ * position so the audit trail shows the reorder without a join back to
+ * the live row.
+ */
+export const CellItemMoveAuditMetadata = z.looseObject({
+    parent_id: Uuid,
+    position_old: z.string(),
+    position_new: z.string(),
+});
+/** Metadata envelope for `cell_item_delete`. */
+export const CellItemDeleteAuditMetadata = z.looseObject({
+    parent_id: Uuid,
+    position: z.string(),
+    child_id: Uuid,
+});

package/dist/auth/cell_relation_visibility.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Strict relation-read visibility filter.
+ *
+ * Forward relation reads (the `cell_get` bundle, forward `cell_field_list`
+ * / `cell_item_list`, the deep-clone walk) must not surface edges whose
+ * target the caller cannot view — otherwise an editor of a public parent
+ * could enumerate private children by id, or a public cell could leak the
+ * existence of private linked cells. This helper bulk-loads the target
+ * cells + their grants and runs `can_view_cell` per target in memory,
+ * returning the set of viewable target ids. Batched (two queries for the
+ * whole id-set) to avoid the N+1 a naive per-row check would cause.
+ *
+ * @module
+ */
+import type { Uuid } from '@fuzdev/fuz_util/id.js';
+import type { QueryDeps } from '../db/query_deps.js';
+import type { RequestContext } from './request_context.js';
+/**
+ * Return the subset of `target_ids` the caller may view.
+ *
+ * Soft-deleted targets and ids with no matching cell are absent from the
+ * result (treated as not-viewable). Grants are loaded only for
+ * authenticated callers — `null` auth admits solely via the public
+ * branch of `can_view_cell`, so the grant load is skipped entirely.
+ *
+ * @param deps - query deps
+ * @param auth - request context, or `null` for unauthenticated callers
+ * @param target_ids - candidate cell ids (duplicates are harmless)
+ * @returns the set of ids the caller may view
+ */
+export declare const filter_visible_target_ids: (deps: QueryDeps, auth: RequestContext | null, target_ids: ReadonlyArray<Uuid>) => Promise<Set<Uuid>>;
+//# sourceMappingURL=cell_relation_visibility.d.ts.map

package/dist/auth/cell_relation_visibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell_relation_visibility.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cell_relation_visibility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAEjD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAKzD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,SAAS,EACf,MAAM,cAAc,GAAG,IAAI,EAC3B,YAAY,aAAa,CAAC,IAAI,CAAC,KAC7B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAwBnB,CAAC"}

package/dist/auth/cell_relation_visibility.js

@@ -0,0 +1,57 @@
+/**
+ * Strict relation-read visibility filter.
+ *
+ * Forward relation reads (the `cell_get` bundle, forward `cell_field_list`
+ * / `cell_item_list`, the deep-clone walk) must not surface edges whose
+ * target the caller cannot view — otherwise an editor of a public parent
+ * could enumerate private children by id, or a public cell could leak the
+ * existence of private linked cells. This helper bulk-loads the target
+ * cells + their grants and runs `can_view_cell` per target in memory,
+ * returning the set of viewable target ids. Batched (two queries for the
+ * whole id-set) to avoid the N+1 a naive per-row check would cause.
+ *
+ * @module
+ */
+import { can_view_cell } from './cell_authorize.js';
+import { query_cell_load_many } from '../db/cell_queries.js';
+import { query_cell_grant_list_for_cells } from '../db/cell_grant_queries.js';
+/**
+ * Return the subset of `target_ids` the caller may view.
+ *
+ * Soft-deleted targets and ids with no matching cell are absent from the
+ * result (treated as not-viewable). Grants are loaded only for
+ * authenticated callers — `null` auth admits solely via the public
+ * branch of `can_view_cell`, so the grant load is skipped entirely.
+ *
+ * @param deps - query deps
+ * @param auth - request context, or `null` for unauthenticated callers
+ * @param target_ids - candidate cell ids (duplicates are harmless)
+ * @returns the set of ids the caller may view
+ */
+export const filter_visible_target_ids = async (deps, auth, target_ids) => {
+    const visible = new Set();
+    if (target_ids.length === 0)
+        return visible;
+    const unique = [...new Set(target_ids)];
+    const cells = await query_cell_load_many(deps, unique);
+    // Grants only matter for authenticated callers — null auth admits via
+    // the public branch alone, so skip the grant load entirely.
+    const grants_by_cell = new Map();
+    if (auth) {
+        const grant_rows = await query_cell_grant_list_for_cells(deps, unique);
+        for (const g of grant_rows) {
+            let list = grants_by_cell.get(g.cell_id);
+            if (list === undefined) {
+                list = [];
+                grants_by_cell.set(g.cell_id, list);
+            }
+            list.push(g);
+        }
+    }
+    for (const cell of cells) {
+        const grants = auth ? (grants_by_cell.get(cell.id) ?? []) : null;
+        if (can_view_cell(auth, cell, grants))
+            visible.add(cell.id);
+    }
+    return visible;
+};

package/dist/auth/deps.d.ts

@@ -8,6 +8,7 @@
  * @module
  */
 import type { Logger } from '@fuzdev/fuz_util/log.js';
+import type { FactStore } from '@fuzdev/fuz_util/fact_store.js';
 import type { Keyring } from './keyring.js';
 import type { PasswordHashDeps } from './password.js';
 import type { Db } from '../db/db.js';
@@ -42,6 +43,14 @@ export interface AppDeps {
      * is no pool slot on the handler context.
      */
     audit: AuditEmitter;
+    /**
+     * Optional content-addressed byte store. Present only on backends that
+     * serve binary content (facts) — minimal consumers leave it unset. The
+     * consumer constructs a `PgFactStore` (`db/fact_store.ts`) wired to a
+     * `file_fact_fetcher` (`server/file_fact_fetcher.ts`) at its own backend
+     * assembly and assigns it here; `create_app_backend` stays facts-agnostic.
+     */
+    fact_store?: FactStore;
 }
 /**
  * Capabilities for route spec factories.

package/dist/auth/deps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deps.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/deps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AACpC,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAErD;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACvB,+DAA+D;IAC/D,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACnD,2BAA2B;IAC3B,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,qBAAqB;IACrB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,0CAA0C;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,yBAAyB;IACzB,EAAE,EAAE,EAAE,CAAC;IACP,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,KAAK,EAAE,YAAY,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC"}
+{"version":3,"file":"deps.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/deps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AACpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gCAAgC,CAAC;AAE9D,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AACpC,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAErD;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACvB,+DAA+D;IAC/D,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACnD,2BAA2B;IAC3B,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,qBAAqB;IACrB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,0CAA0C;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,yBAAyB;IACzB,EAAE,EAAE,EAAE,CAAC;IACP,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,KAAK,EAAE,YAAY,CAAC;IACpB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC"}

package/dist/auth/role_grant_queries.d.ts

@@ -134,6 +134,36 @@ export declare const query_role_grant_has_role: (deps: QueryDeps, actor_id: stri
  * @returns `true` if any actor on the account has an active global role_grant for `role`
  */
 export declare const query_account_has_global_role: (deps: QueryDeps, account_id: string, role: string) => Promise<boolean>;
+/**
+ * Like `query_account_has_global_role`, but only counts the grant when the
+ * **account itself is active** (`deleted_at IS NULL`). Used by the last-admin
+ * branch of the removability guard: a soft-deleted admin can't log in and is
+ * excluded from `query_count_active_accounts_with_global_role`, so the guard
+ * must use the same active-account predicate when testing whether the *target*
+ * is an admin — otherwise removing an already-tombstoned admin is falsely
+ * blocked as `cannot_delete_last_admin` even though it can't lower the active
+ * count. The keeper branch deliberately uses the unconditional
+ * `query_account_has_global_role` (a keeper is never removable regardless of
+ * tombstone state).
+ *
+ * @param deps - query dependencies
+ * @param account_id - the account to check
+ * @param role - the role to check for (e.g. `ROLE_ADMIN`)
+ * @returns `true` if the account is active and any of its actors holds an active global `role` grant
+ */
+export declare const query_account_has_active_global_role: (deps: QueryDeps, account_id: string, role: string) => Promise<boolean>;
+/**
+ * Count **active** accounts (`deleted_at IS NULL`) holding an active global
+ * role_grant for `role`. Used by the last-admin guard on `account_delete` /
+ * `account_purge`: a soft-deleted account's admin grant isn't revoked, so a
+ * plain grant count would include tombstoned (unusable) admins — this joins
+ * `account` and excludes them, counting only admins that can actually log in.
+ *
+ * @param deps - query dependencies
+ * @param role - the role to count (e.g. `ROLE_ADMIN`)
+ * @returns the number of distinct active accounts with an active global `role` grant
+ */
+export declare const query_count_active_accounts_with_global_role: (deps: QueryDeps, role: string) => Promise<number>;
 /**
  * List all role_grants for an actor (including revoked/expired).
  */