@fuzdev/fuz_app 0.67.0 → 0.68.0

package/dist/auth/cell_field_audit_metadata.js

@@ -0,0 +1,28 @@
+/**
+ * Audit-log metadata schemas for `cell_field_set` / `cell_field_delete`.
+ *
+ * IDs only — same discipline as the cell + cell_grant envelopes (audit
+ * logs store references, not denormalized strings). 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_field_set`. Emitted on every successful
+ * create OR update path (UPSERT on `(source_id, name)`); the audit
+ * reader correlates create-vs-update via repeated `(source_id, name)`
+ * if needed.
+ */
+export const CellFieldSetAuditMetadata = z.looseObject({
+    source_id: Uuid,
+    name: z.string(),
+    target_id: Uuid,
+});
+/** Metadata envelope for `cell_field_delete`. */
+export const CellFieldDeleteAuditMetadata = z.looseObject({
+    source_id: Uuid,
+    name: z.string(),
+    target_id: Uuid,
+});

package/dist/auth/cell_grant_action_specs.d.ts

@@ -0,0 +1,333 @@
+/**
+ * Cell-grant ACL RPC specs — declarative contract for the three
+ * `cell_grant_*` verbs (`create`, `revoke`, `list`).
+ *
+ * The grant primitive is a resource-side ACL: each row admits a
+ * principal (actor or role+scope) at a level (viewer / editor) on a
+ * single cell. Owner is implicit on `cell.created_by` and never appears
+ * in the grant list.
+ *
+ * Principal is `{actor_id}` or `{role, scope_id?}` — no name resolver on
+ * this verb. Callers pick an actor by id via `actor_search` (debounced
+ * prefix search) and submit the resolved id directly.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Error reason — grant id did not resolve, or caller may not see it. */
+export declare const ERROR_CELL_GRANT_NOT_FOUND: "cell_grant_not_found";
+/**
+ * Error reason — `cell_grant_create` principal resolves to the cell's
+ * owner. Owner access is implicit (`cell.created_by`); a self-grant
+ * row would shadow it without changing access and create a confusing
+ * self-leave path.
+ */
+export declare const ERROR_CELL_GRANT_PRINCIPAL_IS_OWNER: "cell_grant_principal_is_owner";
+/**
+ * Error reason — role-shaped principal references a role string not
+ * registered in the role schema. Would produce a dead grant row that
+ * no role_grant could match.
+ */
+export declare const ERROR_CELL_GRANT_UNKNOWN_ROLE: "cell_grant_unknown_role";
+/** Grant level — view-only or view-plus-edit. */
+export declare const CellGrantLevel: z.ZodEnum<{
+    viewer: "viewer";
+    editor: "editor";
+}>;
+export type CellGrantLevel = z.infer<typeof CellGrantLevel>;
+/**
+ * Wire-input principal. Discriminated by `kind`. Actor-shaped principals
+ * carry a resolved `actor_id` — the picker UI runs `actor_search` to
+ * convert a typed name to an id before this verb is called.
+ */
+export declare const CellGrantPrincipalInput: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"actor">;
+    actor_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"role">;
+    role: z.ZodString;
+    scope_id: z.ZodOptional<z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>>;
+}, z.core.$strict>], "kind">;
+export type CellGrantPrincipalInput = z.infer<typeof CellGrantPrincipalInput>;
+/**
+ * Wire-format for a cell_grant row. Mirrors `CellJson`'s shape — ISO-string
+ * `created_at`, branded UUIDs, principal columns surfaced as-is. Caller
+ * inspects `actor_id` xor `role` to render the right principal label.
+ */
+export declare const GrantJson: z.ZodObject<{
+    id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    cell_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    level: z.ZodEnum<{
+        viewer: "viewer";
+        editor: "editor";
+    }>;
+    actor_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    role: z.ZodNullable<z.ZodString>;
+    scope_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    granted_by: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    created_at: z.ZodString;
+}, z.core.$strict>;
+export type GrantJson = z.infer<typeof GrantJson>;
+/**
+ * Input for `cell_grant_create`. Idempotent on the unique index —
+ * re-granting the same `(cell_id, principal)` pair updates `level` +
+ * `granted_by` rather than producing a duplicate row.
+ */
+export declare const CellGrantCreateInput: z.ZodObject<{
+    cell_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    level: z.ZodEnum<{
+        viewer: "viewer";
+        editor: "editor";
+    }>;
+    principal: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"actor">;
+        actor_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"role">;
+        role: z.ZodString;
+        scope_id: z.ZodOptional<z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>>;
+    }, z.core.$strict>], "kind">;
+    acting: z.ZodOptional<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+}, z.core.$strict>;
+export type CellGrantCreateInput = z.infer<typeof CellGrantCreateInput>;
+export declare const CellGrantCreateOutput: z.ZodObject<{
+    grant: z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        cell_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        level: z.ZodEnum<{
+            viewer: "viewer";
+            editor: "editor";
+        }>;
+        actor_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+        role: z.ZodNullable<z.ZodString>;
+        scope_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+        granted_by: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+        created_at: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type CellGrantCreateOutput = z.infer<typeof CellGrantCreateOutput>;
+export declare const CellGrantRevokeInput: z.ZodObject<{
+    grant_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    acting: z.ZodOptional<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+}, z.core.$strict>;
+export type CellGrantRevokeInput = z.infer<typeof CellGrantRevokeInput>;
+/**
+ * Output for `cell_grant_revoke`. `still_admitted` is `true` when the
+ * caller retains some admit path on the cell after the revoke (other
+ * grant, ownership, admin). Always `true` for non-self revokes (the
+ * caller didn't admit via this row to begin with).
+ */
+export declare const CellGrantRevokeOutput: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    still_admitted: z.ZodBoolean;
+}, z.core.$strict>;
+export type CellGrantRevokeOutput = z.infer<typeof CellGrantRevokeOutput>;
+export declare const CellGrantListInput: z.ZodObject<{
+    cell_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    acting: z.ZodOptional<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+}, z.core.$strict>;
+export type CellGrantListInput = z.infer<typeof CellGrantListInput>;
+export declare const CellGrantListOutput: z.ZodObject<{
+    grants: z.ZodArray<z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        cell_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        level: z.ZodEnum<{
+            viewer: "viewer";
+            editor: "editor";
+        }>;
+        actor_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+        role: z.ZodNullable<z.ZodString>;
+        scope_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+        granted_by: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+        created_at: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CellGrantListOutput = z.infer<typeof CellGrantListOutput>;
+export declare const cell_grant_create_action_spec: {
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: {
+        account: "required";
+        actor: "required";
+    };
+    side_effects: true;
+    input: z.ZodObject<{
+        cell_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        level: z.ZodEnum<{
+            viewer: "viewer";
+            editor: "editor";
+        }>;
+        principal: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"actor">;
+            actor_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"role">;
+            role: z.ZodString;
+            scope_id: z.ZodOptional<z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>>;
+        }, z.core.$strict>], "kind">;
+        acting: z.ZodOptional<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        grant: z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            cell_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            level: z.ZodEnum<{
+                viewer: "viewer";
+                editor: "editor";
+            }>;
+            actor_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+            role: z.ZodNullable<z.ZodString>;
+            scope_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+            granted_by: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+            created_at: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    async: true;
+    description: string;
+};
+export declare const cell_grant_revoke_action_spec: {
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: {
+        account: "required";
+        actor: "required";
+    };
+    side_effects: true;
+    input: z.ZodObject<{
+        grant_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        acting: z.ZodOptional<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+        still_admitted: z.ZodBoolean;
+    }, z.core.$strict>;
+    async: true;
+    description: string;
+};
+export declare const cell_grant_list_action_spec: {
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: {
+        account: "required";
+        actor: "required";
+    };
+    side_effects: false;
+    input: z.ZodObject<{
+        cell_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        acting: z.ZodOptional<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        grants: z.ZodArray<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            cell_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            level: z.ZodEnum<{
+                viewer: "viewer";
+                editor: "editor";
+            }>;
+            actor_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+            role: z.ZodNullable<z.ZodString>;
+            scope_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+            granted_by: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+            created_at: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    async: true;
+    description: string;
+};
+/** All cell_grant action specs — composed into `all_cell_action_specs`. */
+export declare const all_cell_grant_action_specs: readonly [{
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: {
+        account: "required";
+        actor: "required";
+    };
+    side_effects: true;
+    input: z.ZodObject<{
+        cell_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        level: z.ZodEnum<{
+            viewer: "viewer";
+            editor: "editor";
+        }>;
+        principal: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"actor">;
+            actor_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"role">;
+            role: z.ZodString;
+            scope_id: z.ZodOptional<z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>>;
+        }, z.core.$strict>], "kind">;
+        acting: z.ZodOptional<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        grant: z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            cell_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            level: z.ZodEnum<{
+                viewer: "viewer";
+                editor: "editor";
+            }>;
+            actor_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+            role: z.ZodNullable<z.ZodString>;
+            scope_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+            granted_by: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+            created_at: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    async: true;
+    description: string;
+}, {
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: {
+        account: "required";
+        actor: "required";
+    };
+    side_effects: true;
+    input: z.ZodObject<{
+        grant_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        acting: z.ZodOptional<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+        still_admitted: z.ZodBoolean;
+    }, z.core.$strict>;
+    async: true;
+    description: string;
+}, {
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: {
+        account: "required";
+        actor: "required";
+    };
+    side_effects: false;
+    input: z.ZodObject<{
+        cell_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        acting: z.ZodOptional<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        grants: z.ZodArray<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            cell_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            level: z.ZodEnum<{
+                viewer: "viewer";
+                editor: "editor";
+            }>;
+            actor_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+            role: z.ZodNullable<z.ZodString>;
+            scope_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+            granted_by: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+            created_at: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    async: true;
+    description: string;
+}];
+//# sourceMappingURL=cell_grant_action_specs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cell_grant_action_specs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cell_grant_action_specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAQtB,yEAAyE;AACzE,eAAO,MAAM,0BAA0B,EAAG,sBAA+B,CAAC;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,mCAAmC,EAAG,+BAAwC,CAAC;AAE5F;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAG,yBAAkC,CAAC;AAIhF,iDAAiD;AACjD,eAAO,MAAM,cAAc;;;EAA+B,CAAC;AAC3D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,uBAAuB;;;;;;;4BAYlC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;kBASpB,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAIlD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;kBAO/B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;kBAAqC,CAAC;AACxE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAI1E,eAAO,MAAM,oBAAoB;;;kBAG/B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;kBAGhC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAI1E,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;AAItE,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAWL,CAAC;AAEtC,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;CAWL,CAAC;AAEtC,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAWH,CAAC;AAEtC,2EAA2E;AAC3E,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAI9B,CAAC"}

package/dist/auth/cell_grant_action_specs.js

@@ -0,0 +1,148 @@
+/**
+ * Cell-grant ACL RPC specs — declarative contract for the three
+ * `cell_grant_*` verbs (`create`, `revoke`, `list`).
+ *
+ * The grant primitive is a resource-side ACL: each row admits a
+ * principal (actor or role+scope) at a level (viewer / editor) on a
+ * single cell. Owner is implicit on `cell.created_by` and never appears
+ * in the grant list.
+ *
+ * Principal is `{actor_id}` or `{role, scope_id?}` — no name resolver on
+ * this verb. Callers pick an actor by id via `actor_search` (debounced
+ * prefix search) and submit the resolved id directly.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { Uuid } from '@fuzdev/fuz_util/id.js';
+import { ActingActor } from '../http/auth_shape.js';
+// -- Error reasons ----------------------------------------------------------
+/** Error reason — grant id did not resolve, or caller may not see it. */
+export const ERROR_CELL_GRANT_NOT_FOUND = 'cell_grant_not_found';
+/**
+ * Error reason — `cell_grant_create` principal resolves to the cell's
+ * owner. Owner access is implicit (`cell.created_by`); a self-grant
+ * row would shadow it without changing access and create a confusing
+ * self-leave path.
+ */
+export const ERROR_CELL_GRANT_PRINCIPAL_IS_OWNER = 'cell_grant_principal_is_owner';
+/**
+ * Error reason — role-shaped principal references a role string not
+ * registered in the role schema. Would produce a dead grant row that
+ * no role_grant could match.
+ */
+export const ERROR_CELL_GRANT_UNKNOWN_ROLE = 'cell_grant_unknown_role';
+// -- Shared schemas ---------------------------------------------------------
+/** Grant level — view-only or view-plus-edit. */
+export const CellGrantLevel = z.enum(['viewer', 'editor']);
+/**
+ * Wire-input principal. Discriminated by `kind`. Actor-shaped principals
+ * carry a resolved `actor_id` — the picker UI runs `actor_search` to
+ * convert a typed name to an id before this verb is called.
+ */
+export const CellGrantPrincipalInput = z.discriminatedUnion('kind', [
+    z.strictObject({
+        kind: z.literal('actor'),
+        actor_id: Uuid,
+    }),
+    z.strictObject({
+        kind: z.literal('role'),
+        role: z.string().min(1),
+        scope_id: Uuid.nullish().meta({
+            description: '`null` / omitted = any-scope grant (admits any matching-role role_grant).',
+        }),
+    }),
+]);
+/**
+ * Wire-format for a cell_grant row. Mirrors `CellJson`'s shape — ISO-string
+ * `created_at`, branded UUIDs, principal columns surfaced as-is. Caller
+ * inspects `actor_id` xor `role` to render the right principal label.
+ */
+export const GrantJson = z.strictObject({
+    id: Uuid,
+    cell_id: Uuid,
+    level: CellGrantLevel,
+    actor_id: Uuid.nullable(),
+    role: z.string().nullable(),
+    scope_id: Uuid.nullable(),
+    granted_by: Uuid.nullable(),
+    created_at: z.string(),
+});
+// -- cell_grant_create ------------------------------------------------------
+/**
+ * Input for `cell_grant_create`. Idempotent on the unique index —
+ * re-granting the same `(cell_id, principal)` pair updates `level` +
+ * `granted_by` rather than producing a duplicate row.
+ */
+export const CellGrantCreateInput = z.strictObject({
+    cell_id: Uuid.meta({ description: 'Cell to grant access on.' }),
+    level: CellGrantLevel.meta({ description: 'Grant level: `viewer` or `editor`.' }),
+    principal: CellGrantPrincipalInput.meta({
+        description: 'Subject of the grant. Discriminated by `kind`.',
+    }),
+    acting: ActingActor,
+});
+export const CellGrantCreateOutput = z.strictObject({ grant: GrantJson });
+// -- cell_grant_revoke ------------------------------------------------------
+export const CellGrantRevokeInput = z.strictObject({
+    grant_id: Uuid.meta({ description: 'Grant to revoke.' }),
+    acting: ActingActor,
+});
+/**
+ * Output for `cell_grant_revoke`. `still_admitted` is `true` when the
+ * caller retains some admit path on the cell after the revoke (other
+ * grant, ownership, admin). Always `true` for non-self revokes (the
+ * caller didn't admit via this row to begin with).
+ */
+export const CellGrantRevokeOutput = z.strictObject({
+    ok: z.literal(true),
+    still_admitted: z.boolean(),
+});
+// -- cell_grant_list --------------------------------------------------------
+export const CellGrantListInput = z.strictObject({
+    cell_id: Uuid.meta({ description: 'Cell whose grants to list.' }),
+    acting: ActingActor,
+});
+export const CellGrantListOutput = z.strictObject({
+    grants: z.array(GrantJson),
+});
+// -- Action specs -----------------------------------------------------------
+export const cell_grant_create_action_spec = {
+    method: 'cell_grant_create',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { account: 'required', actor: 'required' },
+    side_effects: true,
+    input: CellGrantCreateInput,
+    output: CellGrantCreateOutput,
+    async: true,
+    description: 'Grant view or edit access on a cell. Manage-tier only (admin / owner) — editor-grant holders cannot manage grants. Idempotent on `(cell_id, principal)`. Owner-as-principal rejected. Actor-shaped principals carry a pre-resolved `actor_id` (callers pick via `actor_search`); no name resolver on this verb.',
+};
+export const cell_grant_revoke_action_spec = {
+    method: 'cell_grant_revoke',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { account: 'required', actor: 'required' },
+    side_effects: true,
+    input: CellGrantRevokeInput,
+    output: CellGrantRevokeOutput,
+    async: true,
+    description: 'Revoke a grant. Manage-tier only (admin / owner), plus self for actor-shaped grants ("leave shared cell"). Returns `still_admitted` so the UI can tell the recipient whether other admit paths remain.',
+};
+export const cell_grant_list_action_spec = {
+    method: 'cell_grant_list',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { account: 'required', actor: 'required' },
+    side_effects: false,
+    input: CellGrantListInput,
+    output: CellGrantListOutput,
+    async: true,
+    description: "List grants on a cell. Manage-tier only (admin / owner); viewers and editors get IDOR-mask 404 (the share list is the manager's to curate).",
+};
+/** All cell_grant action specs — composed into `all_cell_action_specs`. */
+export const all_cell_grant_action_specs = [
+    cell_grant_create_action_spec,
+    cell_grant_revoke_action_spec,
+    cell_grant_list_action_spec,
+];

package/dist/auth/cell_grant_actions.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Cell-grant ACL RPC handlers.
+ *
+ * Three `request_response` actions bound to specs in
+ * `./cell_grant_action_specs.ts`:
+ *
+ * Grant management is **manage-tier only** (`can_manage_cell` = admin /
+ * owner). Editor-grant holders may edit a cell's content + relations but
+ * cannot manage its grants — delegating the share list would let an editor
+ * widen access or mint peer editors and escape the manager's authority.
+ *
+ * - `cell_grant_create` — admin / owner only. Validates role-shaped
+ *   principals against the role schema; rejects owner-as-principal.
+ *   Actor-shaped principals carry a pre-resolved `actor_id` (callers pick
+ *   via `actor_search`). Idempotent — re-granting the same principal
+ *   updates `level` via UPSERT.
+ * - `cell_grant_revoke` — admin / owner, plus self for actor-shaped grants
+ *   ("leave shared cell"). Returns `still_admitted` computed by re-running
+ *   `can_view_cell` against the remaining grants.
+ * - `cell_grant_list` — admin / owner only. Viewers and editors alike get
+ *   the IDOR-mask 404 (the share list is the manager's to curate).
+ *
+ * All three 404 with `cell_not_found` on cell-miss / cell-unviewable, and
+ * with `cell_grant_not_found` on grant-miss, mirroring the existence-leak
+ * guards in `cell_actions.ts`.
+ *
+ * Audit events `cell_grant_create` / `cell_grant_revoke` carry IDs only
+ * (no display-name snapshots); see `./cell_grant_audit_metadata.ts`.
+ *
+ * @module
+ */
+import { type RpcAction } from '../actions/action_rpc.js';
+import type { RoleSchemaResult } from './role_schema.js';
+import type { RouteFactoryDeps } from './deps.js';
+import { type GrantJson } from './cell_grant_action_specs.js';
+import { type CellGrantRow } from '../db/cell_grant_queries.js';
+/**
+ * Dependencies for `create_cell_grant_actions`.
+ *
+ * `roles` is the role schema — read for the role-validity gate on
+ * `cell_grant_create`. The other slots match `CellActionDeps` so
+ * audit-log emit goes through the same fire-and-forget plumbing.
+ */
+export type CellGrantActionDeps = Pick<RouteFactoryDeps, 'log' | 'audit'> & {
+    roles: RoleSchemaResult;
+};
+export declare const to_grant_json: (row: CellGrantRow) => GrantJson;
+/** Create the three `cell_grant_*` RPC actions. */
+export declare const create_cell_grant_actions: (deps: CellGrantActionDeps) => Array<RpcAction>;
+//# sourceMappingURL=cell_grant_actions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cell_grant_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cell_grant_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAsC,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAE7F,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAEhD,OAAO,EAaN,KAAK,SAAS,EACd,MAAM,8BAA8B,CAAC;AAItC,OAAO,EAKN,KAAK,YAAY,EAEjB,MAAM,6BAA6B,CAAC;AAOrC;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,OAAO,CAAC,GAAG;IAC3E,KAAK,EAAE,gBAAgB,CAAC;CACxB,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,KAAK,YAAY,KAAG,SAShD,CAAC;AAgDH,mDAAmD;AACnD,eAAO,MAAM,yBAAyB,GAAI,MAAM,mBAAmB,KAAG,KAAK,CAAC,SAAS,CAoIpF,CAAC"}