@fuzdev/fuz_app 0.67.1 → 0.69.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"cell_audit_action_specs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cell_audit_action_specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAMtB;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;kBAO7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,2EAA2E;AAC3E,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,eAAO,MAAM,kBAAkB;;;kBAG7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;kBAE9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAWH,CAAC;AAEtC,+DAA+D;AAC/D,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAAyC,CAAC"}

package/dist/auth/cell_audit_action_specs.js

@@ -0,0 +1,70 @@
+/**
+ * `cell_audit_list` RPC — per-cell audit timeline.
+ *
+ * Returns audit-log rows whose metadata names this cell on any of the
+ * `(cell_id, source_id, parent_id, child_id, target_id, new_id)` keys
+ * used by the cell-domain event types. The handler 404-masks for
+ * callers who are not in the cell's manage tier (`can_manage_cell` =
+ * admin / owner) — the timeline reveals who-touched-the-cell, so it is
+ * gated above `can_view_cell`.
+ *
+ * Read-only; no audit side effect. Returns the most-recent
+ * `CELL_AUDIT_LIST_DEFAULT_LIMIT` events; pagination is intentionally
+ * not on the wire yet — the only consumer renders a single page. Add
+ * `{before, limit}` input + `{next_before}` output together when a
+ * paginating consumer surfaces.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { Uuid } from '@fuzdev/fuz_util/id.js';
+import { ActingActor } from '../http/auth_shape.js';
+/**
+ * Wire shape for a single cell-audit row. Narrower than
+ * `AuditLogEventJson` — `account_id` and `target_account_id` are
+ * deliberately omitted so this verb does NOT surface the actor↔account
+ * join. `target_actor_id` and `metadata` are dropped too: `target_actor_id`
+ * is NULL for every cell-domain event (the grant recipient lives inside
+ * `metadata.principal` on grant rows, not on the audit-log top-level
+ * field); `metadata` is unread by the timeline UI.
+ *
+ * `ip` is also omitted: it is PII about the actors who touched the cell,
+ * and even at the manage tier this per-cell timeline has no need for it
+ * (admins reach the full `audit_log` surface, which carries `ip`, through
+ * the admin audit verbs). Keeping it off this wire avoids leaking
+ * collaborators' IPs to a cell's owner.
+ *
+ * All omitted fields can be re-added under a richer admin-only
+ * event-detail view later — keep the wire surface honest about what
+ * consumers use.
+ */
+export const CellAuditEventJson = z.strictObject({
+    id: Uuid,
+    seq: z.number(),
+    event_type: z.string(),
+    outcome: z.enum(['success', 'failure']),
+    actor_id: Uuid.nullable(),
+    created_at: z.string(),
+});
+/** Page size for `cell_audit_list`. Single page at MVP; no cursor wire. */
+export const CELL_AUDIT_LIST_DEFAULT_LIMIT = 50;
+export const CellAuditListInput = z.strictObject({
+    cell_id: Uuid.meta({ description: 'Cell whose audit trail to fetch.' }),
+    acting: ActingActor,
+});
+export const CellAuditListOutput = z.strictObject({
+    events: z.array(CellAuditEventJson),
+});
+export const cell_audit_list_action_spec = {
+    method: 'cell_audit_list',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { account: 'required', actor: 'required' },
+    side_effects: false,
+    input: CellAuditListInput,
+    output: CellAuditListOutput,
+    async: true,
+    description: 'List the most-recent audit events referencing the cell on any of `cell_id`, `source_id`, `parent_id`, `child_id`, `target_id`, or `new_id` metadata keys. Manage-tier only (admin / owner) — the timeline reveals who touched the cell, so viewers and editors get the IDOR-mask 404. 404 on miss or unauthorized — same shape as `cell_get` so private-cell existence does not leak.',
+};
+/** Registry export to compose into `all_cell_action_specs`. */
+export const all_cell_audit_action_specs = [cell_audit_list_action_spec];

package/dist/auth/cell_audit_actions.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `cell_audit_list` handler — per-cell audit timeline read.
+ *
+ * Authz is **manage-tier** (`can_manage_cell` = admin / owner), NOT
+ * `can_view_cell`. The timeline surfaces the `actor_id` of every account
+ * that touched the cell (including via `cell_field` / `cell_item` / clone
+ * edges where the cell is the target / child / source); exposing that to
+ * mere viewers — or, for a public cell, to any authenticated caller —
+ * leaks who-touched-what. Gating to admin / owner mirrors
+ * `cell_grant_list` ("the audit trail is the manager's to read"). Misses +
+ * unauthorized reads both 404 with `cell_not_found` — private-cell
+ * existence stays masked. No audit side effect (read-only).
+ *
+ * @module
+ */
+import { type RpcAction } from '../actions/action_rpc.js';
+export declare const create_cell_audit_actions: () => Array<RpcAction>;
+//# sourceMappingURL=cell_audit_actions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cell_audit_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cell_audit_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAsC,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAgC7F,eAAO,MAAM,yBAAyB,QAAO,KAAK,CAAC,SAAS,CA0B3D,CAAC"}

package/dist/auth/cell_audit_actions.js

@@ -0,0 +1,59 @@
+/**
+ * `cell_audit_list` handler — per-cell audit timeline read.
+ *
+ * Authz is **manage-tier** (`can_manage_cell` = admin / owner), NOT
+ * `can_view_cell`. The timeline surfaces the `actor_id` of every account
+ * that touched the cell (including via `cell_field` / `cell_item` / clone
+ * edges where the cell is the target / child / source); exposing that to
+ * mere viewers — or, for a public cell, to any authenticated caller —
+ * leaks who-touched-what. Gating to admin / owner mirrors
+ * `cell_grant_list` ("the audit trail is the manager's to read"). Misses +
+ * unauthorized reads both 404 with `cell_not_found` — private-cell
+ * existence stays masked. No audit side effect (read-only).
+ *
+ * @module
+ */
+import { rpc_action } from '../actions/action_rpc.js';
+import { jsonrpc_errors } from '../http/jsonrpc_errors.js';
+import { cell_audit_list_action_spec, CELL_AUDIT_LIST_DEFAULT_LIMIT, } from './cell_audit_action_specs.js';
+import { ERROR_CELL_NOT_FOUND } from './cell_action_specs.js';
+import { query_cell_get } from '../db/cell_queries.js';
+import { query_audit_log_list_by_cell } from '../db/cell_audit_queries.js';
+import { can_manage_cell } from './cell_authorize.js';
+/**
+ * Project a DB row onto the narrowed wire shape. `account_id` /
+ * `target_account_id` / `target_actor_id` / `metadata` / `ip` are
+ * deliberately omitted — see `CellAuditEventJson` docstring for the
+ * rationale.
+ */
+const to_cell_audit_event_json = (row) => ({
+    id: row.id,
+    seq: row.seq,
+    event_type: row.event_type,
+    outcome: row.outcome,
+    actor_id: row.actor_id,
+    created_at: typeof row.created_at === 'string' ? row.created_at : row.created_at.toISOString(),
+});
+export const create_cell_audit_actions = () => {
+    const handler = async (input, ctx) => {
+        const auth = ctx.auth;
+        const cell = await query_cell_get(ctx, input.cell_id);
+        if (!cell) {
+            throw jsonrpc_errors.not_found('cell', { reason: ERROR_CELL_NOT_FOUND });
+        }
+        // Manage-tier gate (admin / owner). A populated timeline leaks both
+        // the existence of the cell and the actor IDs that touched it (incl.
+        // across `cell_field` / `cell_item` / clone edges), so viewers — and
+        // any authed caller on a public cell — must NOT read it. Non-managers
+        // get the same 404 as a non-viewer on `cell_get` (IDOR mask). Grants
+        // aren't consulted (manage tier is owner/admin only).
+        if (!can_manage_cell(auth, cell)) {
+            throw jsonrpc_errors.not_found('cell', { reason: ERROR_CELL_NOT_FOUND });
+        }
+        const rows = await query_audit_log_list_by_cell(ctx, cell.id, {
+            limit: CELL_AUDIT_LIST_DEFAULT_LIMIT,
+        });
+        return { events: rows.map(to_cell_audit_event_json) };
+    };
+    return [rpc_action(cell_audit_list_action_spec, handler)];
+};

package/dist/auth/cell_audit_events.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Canonical cell-layer audit event registry.
+ *
+ * Maps every cell-domain `event_type` a cell handler emits to its
+ * metadata schema. Consumers register the whole bundle in one shot via
+ * `create_audit_log_config({extra_events: {...cell_audit_events, ...}})`
+ * so the cell handlers' `deps.audit.emit(...)` calls validate against the
+ * extended registry. Spreading lets an app fold its own event types in
+ * alongside.
+ *
+ * Aggregator module by design — not a compat shim. The per-event metadata
+ * schemas live in their own files (`cell_audit_metadata.ts`,
+ * `cell_grant_audit_metadata.ts`, `cell_field_audit_metadata.ts`,
+ * `cell_item_audit_metadata.ts`); this module is the single registration
+ * surface that keeps the keys in lockstep with the handlers.
+ *
+ * @module
+ */
+import type { z } from 'zod';
+/**
+ * Cell-layer `event_type → metadata schema` map for `extra_events`.
+ *
+ * Covers the six generic cell verbs' mutation events plus the grant /
+ * field / item relation events. Read-only verbs (`cell_get`, `cell_list`,
+ * `cell_*_list`, `cell_audit_list`) emit nothing and are absent here.
+ */
+export declare const cell_audit_events: Readonly<Record<string, z.ZodType>>;
+//# sourceMappingURL=cell_audit_events.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cell_audit_events.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cell_audit_events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAiB3B;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAYjE,CAAC"}

package/dist/auth/cell_audit_events.js

@@ -0,0 +1,42 @@
+/**
+ * Canonical cell-layer audit event registry.
+ *
+ * Maps every cell-domain `event_type` a cell handler emits to its
+ * metadata schema. Consumers register the whole bundle in one shot via
+ * `create_audit_log_config({extra_events: {...cell_audit_events, ...}})`
+ * so the cell handlers' `deps.audit.emit(...)` calls validate against the
+ * extended registry. Spreading lets an app fold its own event types in
+ * alongside.
+ *
+ * Aggregator module by design — not a compat shim. The per-event metadata
+ * schemas live in their own files (`cell_audit_metadata.ts`,
+ * `cell_grant_audit_metadata.ts`, `cell_field_audit_metadata.ts`,
+ * `cell_item_audit_metadata.ts`); this module is the single registration
+ * surface that keeps the keys in lockstep with the handlers.
+ *
+ * @module
+ */
+import { CellAuditMetadata, CellCloneAuditMetadata } from './cell_audit_metadata.js';
+import { CellGrantCreateAuditMetadata, CellGrantRevokeAuditMetadata, } from './cell_grant_audit_metadata.js';
+import { CellFieldSetAuditMetadata, CellFieldDeleteAuditMetadata, } from './cell_field_audit_metadata.js';
+import { CellItemInsertAuditMetadata, CellItemMoveAuditMetadata, CellItemDeleteAuditMetadata, } from './cell_item_audit_metadata.js';
+/**
+ * Cell-layer `event_type → metadata schema` map for `extra_events`.
+ *
+ * Covers the six generic cell verbs' mutation events plus the grant /
+ * field / item relation events. Read-only verbs (`cell_get`, `cell_list`,
+ * `cell_*_list`, `cell_audit_list`) emit nothing and are absent here.
+ */
+export const cell_audit_events = {
+    cell_create: CellAuditMetadata,
+    cell_update: CellAuditMetadata,
+    cell_delete: CellAuditMetadata,
+    cell_clone: CellCloneAuditMetadata,
+    cell_grant_create: CellGrantCreateAuditMetadata,
+    cell_grant_revoke: CellGrantRevokeAuditMetadata,
+    cell_field_set: CellFieldSetAuditMetadata,
+    cell_field_delete: CellFieldDeleteAuditMetadata,
+    cell_item_insert: CellItemInsertAuditMetadata,
+    cell_item_move: CellItemMoveAuditMetadata,
+    cell_item_delete: CellItemDeleteAuditMetadata,
+};

package/dist/auth/cell_audit_metadata.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Audit-log metadata schemas for the cell layer's mutation events.
+ *
+ * Apps register these via `extra_events:` on `create_audit_log_config`
+ * alongside any app-defined event types.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/**
+ * Shared metadata envelope for cell mutations. `kind` and `path` are
+ * captured at emit-time so the audit-log viewer can show useful context
+ * for soft-deleted rows even after the cell snapshot is gone. Relation
+ * membership is tracked independently via the `cell_item_*` /
+ * `cell_field_*` per-row audit events.
+ *
+ * Loose object: per-kind handlers may extend the metadata without spec
+ * churn.
+ */
+export declare const CellAuditMetadata: z.ZodObject<{
+    cell_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    kind: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export type CellAuditMetadata = z.infer<typeof CellAuditMetadata>;
+/**
+ * Metadata envelope for `cell_clone`.
+ *
+ * `source_id` and `new_id` capture the parent → clone edge. `deep` flags
+ * whether children were walked. `item_count` reports the number of
+ * children actually cloned (post-skip). `kind` is captured at emit-time so
+ * an operator can filter the audit log by source shape (e.g., "every
+ * collection clone").
+ *
+ * No skipped-child count is recorded: surfacing how many children the
+ * caller couldn't view would leak the source's hidden-child count to the
+ * cloner (who owns — and can audit — the clone). Non-viewable children are
+ * dropped silently (D8).
+ */
+export declare const CellCloneAuditMetadata: z.ZodObject<{
+    source_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    new_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    deep: z.ZodBoolean;
+    item_count: z.ZodNumber;
+    kind: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type CellCloneAuditMetadata = z.infer<typeof CellCloneAuditMetadata>;
+//# sourceMappingURL=cell_audit_metadata.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cell_audit_metadata.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cell_audit_metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAGtB;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB;;;;iBAI5B,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB;;;;;;iBAMjC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/auth/cell_audit_metadata.js

@@ -0,0 +1,46 @@
+/**
+ * Audit-log metadata schemas for the cell layer's mutation events.
+ *
+ * Apps register these via `extra_events:` on `create_audit_log_config`
+ * alongside any app-defined event types.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { Uuid } from '@fuzdev/fuz_util/id.js';
+/**
+ * Shared metadata envelope for cell mutations. `kind` and `path` are
+ * captured at emit-time so the audit-log viewer can show useful context
+ * for soft-deleted rows even after the cell snapshot is gone. Relation
+ * membership is tracked independently via the `cell_item_*` /
+ * `cell_field_*` per-row audit events.
+ *
+ * Loose object: per-kind handlers may extend the metadata without spec
+ * churn.
+ */
+export const CellAuditMetadata = z.looseObject({
+    cell_id: Uuid,
+    kind: z.string().optional(),
+    path: z.string().nullable().optional(),
+});
+/**
+ * Metadata envelope for `cell_clone`.
+ *
+ * `source_id` and `new_id` capture the parent → clone edge. `deep` flags
+ * whether children were walked. `item_count` reports the number of
+ * children actually cloned (post-skip). `kind` is captured at emit-time so
+ * an operator can filter the audit log by source shape (e.g., "every
+ * collection clone").
+ *
+ * No skipped-child count is recorded: surfacing how many children the
+ * caller couldn't view would leak the source's hidden-child count to the
+ * cloner (who owns — and can audit — the clone). Non-viewable children are
+ * dropped silently (D8).
+ */
+export const CellCloneAuditMetadata = z.looseObject({
+    source_id: Uuid,
+    new_id: Uuid,
+    deep: z.boolean(),
+    item_count: z.number().int().nonnegative(),
+    kind: z.string().optional(),
+});

package/dist/auth/cell_authorize.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Cell view + edit + manage authorization helpers.
+ *
+ * Pure functions over `(auth, cell, grants)`. No DB I/O; the caller is
+ * responsible for loading the cell row and the cell's grant list out-of-
+ * band, then handing both to the predicate.
+ *
+ * Unauthenticated callers pass `null` for `auth` — public pages can
+ * resolve `cell.visibility === 'public'` cells without a session, and
+ * that branch is the only path that admits them. Callers may pass `null`
+ * for `grants` in that case (and any case where they know they don't
+ * need to consider grants); `grant_admits` short-circuits on null.
+ *
+ * Three tiers:
+ *
+ * - `can_view_cell` — admin / public / owner / any `viewer`+ grant.
+ * - `can_edit_cell` — admin / owner / `editor` grant. NULL `created_by`
+ *   is admin-only (system-origin defense-in-depth).
+ * - `can_manage_cell` — admin / owner only. Not delegable, not a grant
+ *   level. Gates the manage tier: `visibility` writes and all grant
+ *   management (`cell_grant_create` / `_list` / `_revoke`).
+ *
+ * Grant-admit branches: per-`actor_id` grants admit the matching
+ * actor; `(role, scope_id?)` grants admit any holder of an active
+ * role_grant matching those literals (`scope_id IS NULL` admits any-scope
+ * role_grant). The grant's `level` (`viewer` / `editor`) gates which
+ * predicate it satisfies.
+ *
+ * @module
+ */
+import { type RequestContext } from './request_context.js';
+import type { CellRow } from '../db/cell_queries.js';
+import type { CellGrantRow } from '../db/cell_grant_queries.js';
+/**
+ * View authorization for a cell.
+ *
+ * - Admin: always allowed.
+ * - `cell.visibility === 'public'`: allowed for everyone, including
+ *   unauthenticated callers (e.g. a public landing cell).
+ * - Owner (`cell.created_by === auth.actor.id`): allowed.
+ * - Any active grant on the cell admits the caller (actor-shaped:
+ *   match on actor_id; role-shaped: match on `(role, scope_id?)`
+ *   against an active role_grant).
+ * - Otherwise: false.
+ *
+ * @param auth - request context, or `null` for unauthenticated callers
+ * @param cell - the cell row
+ * @param grants - the cell's grant list, or `null` to skip the grant branch
+ * @returns whether the caller may view the cell
+ */
+export declare const can_view_cell: (auth: RequestContext | null, cell: CellRow, grants: ReadonlyArray<CellGrantRow> | null) => boolean;
+/**
+ * Edit authorization for a cell.
+ *
+ * Unauthenticated callers can never edit. Admin always allowed.
+ *
+ * IMPORTANT: the `cell.created_by === null` branch is **explicit
+ * defense-in-depth**. NULL `created_by` means system origin (well-known
+ * cells seeded by migration, future daemon/agent cells). Non-admin edits
+ * MUST be denied — editor-level grants do NOT bypass this guard,
+ * because system cells are policy-controlled at admin level. Do NOT
+ * collapse into a single equality check that would silently return
+ * `false` for NULL via JS equality semantics — the explicit branch
+ * survives refactors and reads as a load-bearing security property.
+ *
+ * @param auth - request context, or `null` for unauthenticated callers
+ * @param cell - the cell row
+ * @param grants - the cell's grant list, or `null` to skip the grant branch
+ * @returns whether the caller may edit the cell
+ */
+export declare const can_edit_cell: (auth: RequestContext | null, cell: CellRow, grants: ReadonlyArray<CellGrantRow> | null) => boolean;
+/**
+ * Manage authorization for a cell — `admin || owner`.
+ *
+ * The implicit tier above editor: gates `visibility` writes and all grant
+ * management (`cell_grant_create` / `_list` / `_revoke`). NOT delegable and
+ * NOT a grant level — an editor-grant holder is never a manager. Grants are
+ * not consulted.
+ *
+ * NULL `created_by` (system origin) has no owner, so manage falls to
+ * admin only — the explicit NULL guard lives in `is_owner`.
+ *
+ * @param auth - request context, or `null` for unauthenticated callers
+ * @param cell - the cell row
+ * @returns whether the caller is in the manage tier for the cell
+ */
+export declare const can_manage_cell: (auth: RequestContext | null, cell: CellRow) => boolean;
+//# sourceMappingURL=cell_authorize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cell_authorize.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cell_authorize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAW,KAAK,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAInE,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,6BAA6B,CAAC;AA+D9D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,GACzB,MAAM,cAAc,GAAG,IAAI,EAC3B,MAAM,OAAO,EACb,QAAQ,aAAa,CAAC,YAAY,CAAC,GAAG,IAAI,KACxC,OAMF,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa,GACzB,MAAM,cAAc,GAAG,IAAI,EAC3B,MAAM,OAAO,EACb,QAAQ,aAAa,CAAC,YAAY,CAAC,GAAG,IAAI,KACxC,OAUF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,cAAc,GAAG,IAAI,EAAE,MAAM,OAAO,KAAG,OAI5E,CAAC"}

package/dist/auth/cell_authorize.js

@@ -0,0 +1,172 @@
+/**
+ * Cell view + edit + manage authorization helpers.
+ *
+ * Pure functions over `(auth, cell, grants)`. No DB I/O; the caller is
+ * responsible for loading the cell row and the cell's grant list out-of-
+ * band, then handing both to the predicate.
+ *
+ * Unauthenticated callers pass `null` for `auth` — public pages can
+ * resolve `cell.visibility === 'public'` cells without a session, and
+ * that branch is the only path that admits them. Callers may pass `null`
+ * for `grants` in that case (and any case where they know they don't
+ * need to consider grants); `grant_admits` short-circuits on null.
+ *
+ * Three tiers:
+ *
+ * - `can_view_cell` — admin / public / owner / any `viewer`+ grant.
+ * - `can_edit_cell` — admin / owner / `editor` grant. NULL `created_by`
+ *   is admin-only (system-origin defense-in-depth).
+ * - `can_manage_cell` — admin / owner only. Not delegable, not a grant
+ *   level. Gates the manage tier: `visibility` writes and all grant
+ *   management (`cell_grant_create` / `_list` / `_revoke`).
+ *
+ * Grant-admit branches: per-`actor_id` grants admit the matching
+ * actor; `(role, scope_id?)` grants admit any holder of an active
+ * role_grant matching those literals (`scope_id IS NULL` admits any-scope
+ * role_grant). The grant's `level` (`viewer` / `editor`) gates which
+ * predicate it satisfies.
+ *
+ * @module
+ */
+import { has_role } from './request_context.js';
+import { is_role_grant_active } from './account_schema.js';
+import { ROLE_ADMIN } from './role_schema.js';
+const cell_is_public = (cell) => cell.visibility === 'public';
+/**
+ * Whether any grant admits `auth` at the given level.
+ *
+ * `null` grants short-circuits to false — callers who skipped the load
+ * (e.g. unauthenticated requests, where no grant could admit anyway)
+ * pass null instead of allocating an empty array. Authenticated
+ * callers that loaded a list pass it as-is; an empty array is
+ * semantically distinct ("loaded, no grants exist") and walks to false
+ * via the empty `for...of`.
+ *
+ * Actor-shaped grants match `auth.actor.id`. Role-shaped grants walk
+ * `auth.role_grants` for an active role_grant with matching role and either a
+ * matching `scope_id` or `g.scope_id IS NULL` (any scope). The active-
+ * role_grant recheck via `is_role_grant_active` is belt-and-suspenders for
+ * long-lived requests crossing an expiration boundary; middleware
+ * already filtered to active role_grants at request entry.
+ */
+const grant_admits = (auth, grants, required_level) => {
+    if (grants === null)
+        return false;
+    const now = new Date();
+    for (const g of grants) {
+        // Editor-required filters out viewer-level grants up front.
+        if (required_level === 'editor' && g.level !== 'editor')
+            continue;
+        if (g.actor_id !== null) {
+            // Actor-shaped grants only match a resolved acting actor. Account-
+            // grain auth (no `acting` declared on input → `actor: null`) cannot
+            // match an actor-id grant by definition.
+            if (auth.actor !== null && g.actor_id === auth.actor.id)
+                return true;
+            continue;
+        }
+        // Role-shaped principal. The CHECK constraint on cell_grant
+        // guarantees `role IS NOT NULL` here (actor_id xor role).
+        const matched = auth.role_grants.some((p) => p.role === g.role &&
+            (g.scope_id === null || p.scope_id === g.scope_id) &&
+            is_role_grant_active(p, now));
+        if (matched)
+            return true;
+    }
+    return false;
+};
+/**
+ * Whether `auth` owns `cell` (the implicit manage tier below admin).
+ *
+ * Owner is the `cell.created_by` actor field — not a role, not a
+ * delegable grant level. NULL `created_by` (system origin) is never
+ * owned by anyone; the explicit `created_by !== null` guard keeps that
+ * a load-bearing property rather than relying on JS equality returning
+ * false for NULL.
+ */
+const is_owner = (auth, cell) => auth.actor !== null && cell.created_by !== null && cell.created_by === auth.actor.id;
+/**
+ * View authorization for a cell.
+ *
+ * - Admin: always allowed.
+ * - `cell.visibility === 'public'`: allowed for everyone, including
+ *   unauthenticated callers (e.g. a public landing cell).
+ * - Owner (`cell.created_by === auth.actor.id`): allowed.
+ * - Any active grant on the cell admits the caller (actor-shaped:
+ *   match on actor_id; role-shaped: match on `(role, scope_id?)`
+ *   against an active role_grant).
+ * - Otherwise: false.
+ *
+ * @param auth - request context, or `null` for unauthenticated callers
+ * @param cell - the cell row
+ * @param grants - the cell's grant list, or `null` to skip the grant branch
+ * @returns whether the caller may view the cell
+ */
+export const can_view_cell = (auth, cell, grants) => {
+    if (auth && has_role(auth, ROLE_ADMIN))
+        return true;
+    if (cell_is_public(cell))
+        return true;
+    if (auth && is_owner(auth, cell))
+        return true;
+    if (auth && grant_admits(auth, grants, 'viewer'))
+        return true;
+    return false;
+};
+/**
+ * Edit authorization for a cell.
+ *
+ * Unauthenticated callers can never edit. Admin always allowed.
+ *
+ * IMPORTANT: the `cell.created_by === null` branch is **explicit
+ * defense-in-depth**. NULL `created_by` means system origin (well-known
+ * cells seeded by migration, future daemon/agent cells). Non-admin edits
+ * MUST be denied — editor-level grants do NOT bypass this guard,
+ * because system cells are policy-controlled at admin level. Do NOT
+ * collapse into a single equality check that would silently return
+ * `false` for NULL via JS equality semantics — the explicit branch
+ * survives refactors and reads as a load-bearing security property.
+ *
+ * @param auth - request context, or `null` for unauthenticated callers
+ * @param cell - the cell row
+ * @param grants - the cell's grant list, or `null` to skip the grant branch
+ * @returns whether the caller may edit the cell
+ */
+export const can_edit_cell = (auth, cell, grants) => {
+    if (!auth)
+        return false;
+    if (has_role(auth, ROLE_ADMIN))
+        return true;
+    if (cell.created_by === null)
+        return false; // explicit: NULL = admin-only
+    // Owner check requires a resolved acting actor — account-grain auth
+    // (`actor: null`) cannot match an actor-id `created_by`. Grant-admit
+    // fallback below handles the actor-grain editor-grant path.
+    if (is_owner(auth, cell))
+        return true;
+    if (grant_admits(auth, grants, 'editor'))
+        return true;
+    return false;
+};
+/**
+ * Manage authorization for a cell — `admin || owner`.
+ *
+ * The implicit tier above editor: gates `visibility` writes and all grant
+ * management (`cell_grant_create` / `_list` / `_revoke`). NOT delegable and
+ * NOT a grant level — an editor-grant holder is never a manager. Grants are
+ * not consulted.
+ *
+ * NULL `created_by` (system origin) has no owner, so manage falls to
+ * admin only — the explicit NULL guard lives in `is_owner`.
+ *
+ * @param auth - request context, or `null` for unauthenticated callers
+ * @param cell - the cell row
+ * @returns whether the caller is in the manage tier for the cell
+ */
+export const can_manage_cell = (auth, cell) => {
+    if (!auth)
+        return false;
+    if (has_role(auth, ROLE_ADMIN))
+        return true;
+    return is_owner(auth, cell);
+};

package/dist/auth/cell_data_schema.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Generic cell-data base schema.
+ *
+ * The wire-side shape every cell consumer can read without per-kind
+ * knowledge: a permissive bag with three universally-relevant typed
+ * fields. Per-kind schemas extend this and narrow `kind` to a literal.
+ *
+ * Loose object: arbitrary additional fields pass through unvalidated,
+ * preserving the "unknown kinds ship without RPC churn" property. Per-kind
+ * shape enforcement is opt-in via the `validate_data` deps slot — see
+ * `cell_actions.ts`.
+ *
+ * **Discipline**: a field joins `CellData` only when at least two
+ * consumers in different domains read it generically. `kind` (editor
+ * dispatch + sub-API registry), `label` (list/index rendering), and
+ * `summary` (card subtitle + share-target description) meet this bar.
+ * Future candidates require evidence of generic usage — otherwise they
+ * stay per-kind.
+ *
+ * **Visibility is not in here.** Access control is a peer of `cell_grant`,
+ * not content metadata — `cell.visibility` lives as a top-level column on
+ * `CellJson` and `CellRow` (the `CellVisibility` enum is defined in
+ * `cell_action_specs.ts` next to the wire fields that use it), and is
+ * enforced by `can_view_cell` reading the column directly (no JSON dive).
+ *
+ * @module
+ */
+import { z } from 'zod';
+/**
+ * Base cell-data shape. All fields optional; loose mode admits arbitrary
+ * additional keys so apps can attach metadata or stage new kinds without
+ * touching the wire schema.
+ *
+ * `kind` is optional because cells without a registered kind are valid —
+ * admin-curated content, in-development types, or unknown shapes pass
+ * through. Known kinds get richer validation via the per-kind sub-API.
+ */
+export declare const CellData: z.ZodObject<{
+    kind: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type CellData = z.infer<typeof CellData>;
+//# sourceMappingURL=cell_data_schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cell_data_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cell_data_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ;;;;iBAInB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC"}