cursedbelt-core 1.0.0

package/src/core/session/claims.ts

@@ -0,0 +1,181 @@
+/**
+ * The GuardEngine session assertion (02 §4.2) — the one claims vocabulary the
+ * server signs, the wire carries, and the client reads.
+ *
+ * The single most important property here is that **the wire only signals**.
+ * `PrivateModePayload.claims` is a decoded convenience copy and is marked
+ * advisory in the type's own documentation because panes kept treating it as an
+ * authorization result: one pane unlocking would reveal another pane's bytes
+ * because both read the same "unlocked" boolean. Every server route that serves
+ * private bytes or mutates data re-verifies the opaque `token` per request
+ * (03 §2.3), so a forged or stale `claims` object buys nothing.
+ *
+ * Both schemas are `.strict()`: an unknown claim key is a forged or
+ * version-skewed token, and silently ignoring it is how a `permissions` typo
+ * becomes an accidental grant.
+ */
+import { z } from 'zod';
+
+/** Roles, ordered least→most privileged. RBAC checks compare permissions, not this. */
+export const CC_ROLES = ['VIEWER', 'MEMBER', 'ADMIN', 'OWNER'] as const;
+export type CCRole = (typeof CC_ROLES)[number];
+
+/**
+ * The permission that gates infrastructure features (02 §4.4). `configEditor`
+ * and `dbAdmin` can read plaintext env values and run destructive DB operations,
+ * which is not an "every team member" power even when the feature is
+ * config-enabled.
+ */
+export const INFRA_WRITE = 'infra:write';
+
+/**
+ * Reads the audit trail (`GET /api/guard/audit`) — owner decision D27, Option C.
+ *
+ * A SEPARATE permission from {@link INFRA_WRITE}, and not granted to ADMIN by
+ * default. Three things had to be true at once and no single existing grant made
+ * them so:
+ *
+ *   * The trail is the most sensitive read surface the product has — every
+ *     action every member of a tenant has taken. In a tenant where ADMINs manage
+ *     each other it is also a record of what the OTHER ADMINs did, and deciding
+ *     on every customer's behalf that ADMINs watch each other is not a default
+ *     worth shipping.
+ *   * The person who actually wants a change log is usually an ADMIN, and
+ *     OWNER-only means they must ask the account owner — who is frequently the
+ *     person least interested in the request.
+ *   * Reusing `infra:write` (what shipped before this) makes reading the trail
+ *     inseparable from editing config and running destructive DB operations.
+ *     They are different powers and a customer will eventually want to split
+ *     them.
+ *
+ * So: OWNER carries it by role, and anyone else gets it as an explicit
+ * per-membership grant through `identity.setMembershipPermissions` — the path
+ * that already exists. Nothing is surprising by default, and delegating is one
+ * row rather than a redesign.
+ */
+export const AUDIT_READ = 'audit:read';
+
+/**
+ * Role ordering, as a number, for the privilege-escalation checks (02 §3). Only
+ * ADMINISTRATION compares roles; a route still compares PERMISSIONS.
+ */
+export const CC_ROLE_RANK: Readonly<Record<CCRole, number>> = Object.freeze({
+  VIEWER: 0,
+  MEMBER: 1,
+  ADMIN: 2,
+  OWNER: 3,
+});
+
+/** Is `role` at least as privileged as `floor`? */
+export const roleAtLeast = (role: CCRole, floor: CCRole): boolean => CC_ROLE_RANK[role] >= CC_ROLE_RANK[floor];
+
+/**
+ * The permissions a ROLE carries by itself (02 §3).
+ *
+ * Without this table `guard.features.rbac` was a switch that locked everyone
+ * out: memberships are created with an EMPTY grant array, every permission-gated
+ * route compares `claims.permissions`, and nothing anywhere derived one from the
+ * other — so with RBAC on, a freshly signed-up OWNER of a brand-new tenant could
+ * not write a note, and there was nobody above them to grant it. Roles are the
+ * grant surface (`memberships` IS the RBAC surface); explicit per-membership
+ * grants stay as the exception, not the only path.
+ *
+ * The vocabulary is deliberately exactly the permissions the tree actually
+ * enforces — `knowledge:write`/`knowledge:delete` (the knowledge mixin's
+ * sub-blocks), `infra:write` (guard secrets + the privileged ops) and
+ * `audit:read` (the trail). Inventing grants nothing checks would be a table
+ * that drifts from the moment it lands.
+ */
+export const CC_ROLE_PERMISSIONS: Readonly<Record<CCRole, readonly string[]>> = Object.freeze({
+  // Read-only. Every listing route is unguarded-by-permission, so a VIEWER sees
+  // the app and mutates nothing.
+  VIEWER: Object.freeze([]),
+  // The everyday contributor: writes content, deletes nothing.
+  MEMBER: Object.freeze(['knowledge:write']),
+  // Runs the tenant's content and its people; still not its infrastructure, and
+  // deliberately NOT the audit trail (D27 Option C): in a tenant where ADMINs
+  // manage each other, the trail is a record of what the other ADMINs did, and
+  // that is a decision each customer makes with a per-membership grant rather
+  // than one this table makes for all of them.
+  ADMIN: Object.freeze(['knowledge:write', 'knowledge:delete']),
+  // Infrastructure too: secrets, config editor, db admin — and the trail.
+  OWNER: Object.freeze(['knowledge:write', 'knowledge:delete', AUDIT_READ, INFRA_WRITE]),
+});
+
+/**
+ * What a membership actually grants: the role's permissions UNION any explicit
+ * per-membership grants (`identity.setMembershipPermissions`). Deduplicated and
+ * sorted so a claims set is stable for a given grant — an unstable permission
+ * order makes two equivalent tokens compare unequal in a test and in a cache key.
+ */
+export const effectivePermissions = (role: CCRole, grants: readonly string[] = []): string[] =>
+  [...new Set([...CC_ROLE_PERMISSIONS[role], ...grants])].sort();
+
+export const CCUserClaimsSchema = z
+  .object({
+    tenantId: z.string().min(1),
+    userId: z.string().min(1),
+    role: z.enum(CC_ROLES),
+    /** 'media:write', 'knowledge:delete', 'infra:write', … */
+    permissions: z.array(z.string()).default([]),
+    /** Private-mode reveal granted for this session. */
+    privateScope: z.boolean().default(false),
+    /** Epoch SECONDS (not ms) — the signing and verification paths must agree. */
+    exp: z.number().int().positive(),
+    /** Revocation handle: lock adds it to the denylist until `exp` (02 §4.2). */
+    jti: z.string().min(1),
+  })
+  .strict();
+
+export type CCUserClaims = z.infer<typeof CCUserClaimsSchema>;
+
+export const PrivateModePayloadSchema = z
+  .object({
+    unlocked: z.boolean().default(false),
+    /** Signed claims token; opaque to consumers — never parsed on the client for access. */
+    token: z.string().nullable().default(null),
+    /** Decoded convenience copy — ADVISORY ONLY. Never an authorization result. */
+    claims: CCUserClaimsSchema.nullable().default(null),
+  })
+  .strict();
+
+export type PrivateModePayload = z.infer<typeof PrivateModePayloadSchema>;
+
+/**
+ * The canonical locked assertion. Lock re-asserts exactly this on the
+ * `session:private-mode` wire, in every tab (03 §6.5) — a partially-cleared
+ * payload (token nulled but `unlocked` left true) is the shape that kept
+ * revealing stale panes after a lock.
+ */
+export const LOCKED_PRIVATE_MODE: PrivateModePayload = Object.freeze({
+  unlocked: false,
+  token: null,
+  claims: null,
+});
+
+/** Does this claims set carry `permission`? The one lookup RBAC and §4.4 share. */
+export const hasPermission = (claims: CCUserClaims | null | undefined, permission: string): boolean =>
+  claims?.permissions.includes(permission) === true;
+
+/** Convenience for the privileged-feature gate (02 §4.4). */
+export const hasInfraWrite = (claims: CCUserClaims | null | undefined): boolean =>
+  hasPermission(claims, INFRA_WRITE);
+
+/**
+ * May this session read the audit trail (D27)?
+ *
+ * The CLIENT's copy of the route's own check, and it is the permission rather
+ * than the role for a reason the previous shape got wrong: a role test here
+ * drifts from the server's answer the moment a grant is handed out explicitly,
+ * which under Option C is the ONLY way anyone but an OWNER gets it.
+ */
+export const canReadAuditTrail = (claims: CCUserClaims | null | undefined): boolean =>
+  hasPermission(claims, AUDIT_READ);
+
+/**
+ * Has this token expired, given a clock in ms? Centralized so the server's
+ * verification and the client's proactive-refresh path can never disagree about
+ * whether `exp` is seconds or milliseconds.
+ */
+export const claimsExpired = (claims: CCUserClaims, nowMs: number = Date.now()): boolean =>
+  claims.exp * 1000 <= nowMs;

package/src/core/sharing/index.ts

@@ -0,0 +1,33 @@
+/** The fleet's sharing/access vocabulary — see `./model.ts` for the whole
+ *  contract. Storage lives in `cursedbelt-server/sharing`, the UI in
+ *  `cursedbelt/react/sharing`; both speak these words. */
+export {
+	accessMeets,
+	describeAccess,
+	describeShareEvent,
+	isShareAccess,
+	isShareLevel,
+	isShareSubjectType,
+	levelsMeeting,
+	normalizeSubject,
+	normalizeSubjectId,
+	resolveAccess,
+	resourceKey,
+	sameResource,
+	sameSubject,
+	SHARE_ACTIONS,
+	strongerAccess,
+} from "./model";
+export type {
+	ShareAccess,
+	ShareAction,
+	ShareEvent,
+	ShareGrant,
+	ShareGroup,
+	ShareGroupMember,
+	ShareLevel,
+	ShareResource,
+	ShareSubject,
+	ShareSubjectType,
+	ShareViewer,
+} from "./model";

package/src/core/sharing/model.spec.ts

@@ -0,0 +1,104 @@
+/**
+ * The precedence rules, as pure functions — the ONE written definition the SQLite
+ * store is checked against (`server/sharing/store.spec.ts` asserts they agree).
+ */
+import { describe, expect, test } from "bun:test";
+import {
+	accessMeets,
+	describeAccess,
+	levelsMeeting,
+	normalizeSubjectId,
+	resolveAccess,
+	resourceKey,
+	type ShareGrant,
+	strongerAccess,
+} from "./model";
+
+const resource = { app: "family", kind: "person", id: "p1" };
+
+const grant = (
+	subject: ShareGrant["subject"],
+	level: ShareGrant["level"],
+	id = "p1",
+): ShareGrant => ({
+	resource: { ...resource, id },
+	subject,
+	level,
+	grantedBy: "owner@example.com",
+	grantedAt: "2026-08-11T00:00:00.000Z",
+	note: "",
+});
+
+describe("the level algebra", () => {
+	test("write covers read; read does not cover write", () => {
+		expect(accessMeets("write", "read")).toBe(true);
+		expect(accessMeets("write", "write")).toBe(true);
+		expect(accessMeets("read", "read")).toBe(true);
+		expect(accessMeets("read", "write")).toBe(false);
+		expect(accessMeets("none", "read")).toBe(false);
+	});
+
+	test("grants only ever widen", () => {
+		expect(strongerAccess("read", "write")).toBe("write");
+		expect(strongerAccess("write", "read")).toBe("write");
+		expect(strongerAccess("none", "read")).toBe("read");
+		expect(strongerAccess("none", "none")).toBe("none");
+	});
+
+	test("`levelsMeeting` is what a store's IN (…) list must hold", () => {
+		expect(levelsMeeting("read")).toEqual(["read", "write"]);
+		expect(levelsMeeting("write")).toEqual(["write"]);
+	});
+});
+
+describe("resolveAccess", () => {
+	test("takes the strongest grant that reaches the viewer", () => {
+		const grants = [
+			grant({ type: "user", id: "aunt@example.com" }, "read"),
+			grant({ type: "group", id: "g-family" }, "write"),
+		];
+		expect(
+			resolveAccess(grants, resource, {
+				subjectId: "aunt@example.com",
+				groupIds: ["g-family"],
+			}),
+		).toBe("write");
+		// Without the group membership, only their own grant reaches them.
+		expect(resolveAccess(grants, resource, { subjectId: "aunt@example.com" })).toBe("read");
+	});
+
+	test("ignores grants on other resources", () => {
+		const grants = [grant({ type: "user", id: "aunt@example.com" }, "write", "p2")];
+		expect(resolveAccess(grants, resource, { subjectId: "aunt@example.com" })).toBe("none");
+	});
+
+	test("matches an address case- and whitespace-insensitively", () => {
+		const grants = [grant({ type: "user", id: "aunt@example.com" }, "read")];
+		expect(resolveAccess(grants, resource, { subjectId: " Aunt@Example.com " })).toBe("read");
+	});
+});
+
+describe("normalizeSubjectId", () => {
+	test("lowercases a user address, and only trims a group id", () => {
+		expect(normalizeSubjectId("user", " Aunt@Example.COM ")).toBe("aunt@example.com");
+		// A group id is minted by an app and may be case-sensitive; lowercasing it
+		// would silently collide two distinct ids.
+		expect(normalizeSubjectId("group", " G-Family ")).toBe("G-Family");
+	});
+});
+
+describe("resourceKey", () => {
+	test("is stable and never parsed back — an id may contain a slash", () => {
+		expect(resourceKey({ app: "family", kind: "place", id: "Kingston/Hull" })).toBe(
+			"family/place/Kingston/Hull",
+		);
+	});
+});
+
+describe("describeAccess", () => {
+	test("gives a UI one wording per level", () => {
+		expect(describeAccess("write")).toBe("Can view and change it");
+		expect(describeAccess("read")).toBe("Can view it");
+		expect(describeAccess("none")).toBe("No access");
+	});
+});

package/src/core/sharing/model.ts

@@ -0,0 +1,296 @@
+/**
+ * The fleet's ONE sharing/access vocabulary — pure, framework-free, storage-free.
+ *
+ * ── What this replaces ──────────────────────────────────────────────────────
+ * `cursedalchemy` carried a unified `shares` + `group_shares` pair across ~30
+ * resource types: per-record read/write, an audit trail and notification hooks,
+ * all in one place. That app is superseded, and the fleet has been re-deriving
+ * the same idea one app at a time — `apps/family` grew a whole roles model plus
+ * a `guards.ts` because it needed "who may change THIS record", and its own
+ * `CLAUDE.md` recorded the hole it could not close: *"No per-item ACL.
+ * Visibility is still two levels rather than a per-person grant list."*
+ *
+ * `life`, `money` and `arcade` are queued to need exactly that. So the PATTERN
+ * (not ca's code) lands here once:
+ *
+ *   a **resource** is `(app, kind, id)` — an opaque triple, so nothing in this
+ *   module has to know what a person, a budget or a saved game is;
+ *   a **grant** is `(subject, resource, level, grantedBy, grantedAt)`;
+ *   a **subject** is a user or a GROUP, because "share it with the family" is one
+ *   act the owner performs once, not one act per relative;
+ *   **revocation and the audit trail are part of the primitive**, never a caller's
+ *   concern — an app that has to remember to write the audit row is an app whose
+ *   audit trail has holes exactly where somebody was in a hurry.
+ *
+ * ── Why the vocabulary is separate from the store ────────────────────────────
+ * `cursedbelt-server/sharing` owns the SQLite half and `cursedbelt/react/sharing`
+ * draws the panel. Both need the same words, and the react half must not pull
+ * `bun:sqlite` into a browser bundle. So the types and the precedence rules live
+ * here (`cursedbelt-core/sharing`), which is typechecked with `types: []` — it cannot
+ * accidentally depend on a runtime.
+ *
+ * ── The precedence rule, in one sentence ────────────────────────────────────
+ * A subject's access to a resource is the STRONGEST of every grant that reaches
+ * them — their own and every group they are in. Grants only ever widen; there is
+ * deliberately no "deny" grant. A deny row in a table whose whole job is "who may
+ * see this" produces the state nobody can reason about (a user in two groups, one
+ * allowed and one denied) and the answer would then depend on row order. An app
+ * that needs an exception denies it in its OWN model — `apps/family`'s tri-state
+ * `members` columns are exactly that, and they sit ABOVE this layer rather than
+ * inside it.
+ */
+
+/** What a grant lets a subject do. Two levels, on purpose: ca had two and used
+ *  both; a third ("comment", "admin") is a per-app concept every time. */
+export type ShareLevel = "read" | "write";
+
+/** The answer to "what may this subject do with this resource" — a level, or
+ *  nothing at all. Separate from {@link ShareLevel} so a function returning "no
+ *  access" cannot be mistaken for one returning a grant. */
+export type ShareAccess = "none" | ShareLevel;
+
+/** A grant is made to a person or to a named group of people. */
+export type ShareSubjectType = "user" | "group";
+
+export interface ShareSubject {
+	type: ShareSubjectType;
+	/** A fleet account address for `user`, a group id for `group`. Normalized —
+	 *  see {@link normalizeSubjectId}. */
+	id: string;
+}
+
+/**
+ * What is being shared: `(app, kind, id)`.
+ *
+ * `app` is the satellite ("family", "life"), `kind` is that app's own word for the
+ * sort of record ("person", "budget", "list"), `id` is the row. Nothing here
+ * validates the pair against a schema, and that is the point — a new kind is a
+ * string an app already has, not a migration in `cursedbelt`.
+ */
+export interface ShareResource {
+	app: string;
+	kind: string;
+	id: string;
+}
+
+/** One grant. `grantedAt` is an ISO-8601 string, matching the fleet's audit
+ *  vocabulary (the audit module behind `cursedbelt-server`) rather than the epoch-millis apps use
+ *  for their own rows — an audit trail is read by humans far more often than it is
+ *  sorted by a machine. */
+export interface ShareGrant {
+	resource: ShareResource;
+	subject: ShareSubject;
+	level: ShareLevel;
+	/** The account that made the grant. Never inferred from the session inside the
+	 *  store — the caller passes it, because the store has no session. */
+	grantedBy: string;
+	grantedAt: string;
+	/** Why, for whoever reads the list six months later. */
+	note: string;
+}
+
+/** Who is asking. `groupIds` may be omitted, in which case a store resolves the
+ *  subject's groups itself; passing them is an optimization for a caller that
+ *  already knows. */
+export interface ShareViewer {
+	subjectId: string;
+	groupIds?: readonly string[];
+}
+
+/** A named set of people — "the family", "the trustees". Groups are what make
+ *  "share this with everybody who matters" one act instead of eleven. */
+export interface ShareGroup {
+	id: string;
+	name: string;
+	createdBy: string;
+	createdAt: string;
+	note: string;
+}
+
+export interface ShareGroupMember {
+	groupId: string;
+	subjectId: string;
+	addedBy: string;
+	addedAt: string;
+}
+
+/**
+ * Everything that can happen to a grant or a group.
+ *
+ * `regrade` is its own action rather than a second `grant`: raising somebody from
+ * read to write is the change a reader of the trail is looking for, and a trail
+ * that records it as another grant makes that invisible.
+ */
+export type ShareAction =
+	| "grant"
+	| "regrade"
+	| "revoke"
+	| "group.create"
+	| "group.rename"
+	| "group.delete"
+	| "group.join"
+	| "group.leave";
+
+export const SHARE_ACTIONS: readonly ShareAction[] = [
+	"grant",
+	"regrade",
+	"revoke",
+	"group.create",
+	"group.rename",
+	"group.delete",
+	"group.join",
+	"group.leave",
+];
+
+/**
+ * One line of the audit trail.
+ *
+ * 🔴 **An event outlives the grant it describes.** Revoking deletes the grant row
+ * and appends an event; nothing in this primitive ever deletes an event. An audit
+ * trail that is a JOIN onto live grants can only tell you about access that still
+ * exists, which is the opposite of the question anybody asks it ("who COULD see
+ * this in March?"). That is why `resource`, `subject` and `level` are copied onto
+ * the event rather than referenced.
+ */
+export interface ShareEvent {
+	id: number;
+	at: string;
+	action: ShareAction;
+	/** Null for a group lifecycle event, which is about no single resource. */
+	resource: ShareResource | null;
+	subject: ShareSubject;
+	/** The level AFTER the action; for a revoke, the level that was taken away. */
+	level: ShareLevel | null;
+	/** Only set by `regrade` — what it was before. */
+	previousLevel: ShareLevel | null;
+	actor: string;
+	note: string;
+}
+
+const ACCESS_RANK: Record<ShareAccess, number> = { none: 0, read: 1, write: 2 };
+
+export const isShareLevel = (value: unknown): value is ShareLevel =>
+	value === "read" || value === "write";
+
+export const isShareAccess = (value: unknown): value is ShareAccess =>
+	value === "none" || isShareLevel(value);
+
+export const isShareSubjectType = (value: unknown): value is ShareSubjectType =>
+	value === "user" || value === "group";
+
+/** The stronger of two answers. Grants only widen, so this is the whole
+ *  resolution rule. */
+export const strongerAccess = (a: ShareAccess, b: ShareAccess): ShareAccess =>
+	ACCESS_RANK[a] >= ACCESS_RANK[b] ? a : b;
+
+/** Does this access cover what is being attempted? `write` covers `read`; nothing
+ *  covers a level above itself. */
+export const accessMeets = (access: ShareAccess, atLeast: ShareLevel): boolean =>
+	ACCESS_RANK[access] >= ACCESS_RANK[atLeast];
+
+/** The levels a grant must carry to satisfy `atLeast`, for a store building an
+ *  `IN (…)` list. `read` is satisfied by either level; `write` only by itself. */
+export const levelsMeeting = (atLeast: ShareLevel): readonly ShareLevel[] =>
+	atLeast === "read" ? ["read", "write"] : ["write"];
+
+/**
+ * 🔴 The one normalization, and it is a security property rather than tidiness.
+ *
+ * A user subject is a fleet address, and addresses arrive from a form: `"  Ameena@
+ * Example.com "`. Storing that verbatim means the grant the owner just made does
+ * not match the session that signs in, so the app silently answers "no access"
+ * and the owner's only recourse is to guess at whitespace. Lowercasing is also
+ * what makes a grant idempotent — one row per (subject, resource), which is what
+ * `regrade` depends on.
+ *
+ * A GROUP id is minted by the app, so it is trimmed but NOT lowercased: doing so
+ * would silently collide two ids that differ only in case, and an app is entitled
+ * to mint case-sensitive ids.
+ */
+export const normalizeSubjectId = (type: ShareSubjectType, id: string): string =>
+	type === "user" ? id.trim().toLowerCase() : id.trim();
+
+export const normalizeSubject = (subject: ShareSubject): ShareSubject => ({
+	type: subject.type,
+	id: normalizeSubjectId(subject.type, subject.id),
+});
+
+/** A stable string for a resource — for a map key, a log line or a test name.
+ *  Never parsed back: `id` may contain anything, including a slash. */
+export const resourceKey = (resource: ShareResource): string =>
+	`${resource.app}/${resource.kind}/${resource.id}`;
+
+export const sameResource = (a: ShareResource, b: ShareResource): boolean =>
+	a.app === b.app && a.kind === b.kind && a.id === b.id;
+
+export const sameSubject = (a: ShareSubject, b: ShareSubject): boolean =>
+	a.type === b.type && a.id === b.id;
+
+/**
+ * The precedence rule as a pure function: the strongest grant that reaches this
+ * viewer, across their own grants and their groups'.
+ *
+ * The SQLite store answers the same question in SQL (it must — a read that
+ * filters in JavaScript cannot keep a COUNT honest), so this exists as the ONE
+ * written definition both halves are checked against, and as the answer for a
+ * caller holding grants in memory. If the two ever disagree, this one is right.
+ */
+export function resolveAccess(
+	grants: readonly ShareGrant[],
+	resource: ShareResource,
+	viewer: ShareViewer,
+): ShareAccess {
+	const subjectId = normalizeSubjectId("user", viewer.subjectId);
+	const groups = new Set((viewer.groupIds ?? []).map((id) => normalizeSubjectId("group", id)));
+	let access: ShareAccess = "none";
+	for (const grant of grants) {
+		if (!sameResource(grant.resource, resource)) continue;
+		const reaches =
+			grant.subject.type === "user"
+				? grant.subject.id === subjectId
+				: groups.has(grant.subject.id);
+		if (reaches) access = strongerAccess(access, grant.level);
+	}
+	return access;
+}
+
+/**
+ * One line of the audit trail, as a sentence.
+ *
+ * Pure and here rather than in the panel, because the trail is read in two places
+ * that must say the same thing: the sharing panel, and whatever notification the
+ * `onEvent` hook eventually sends. A subject label may be supplied (a group's name,
+ * a person's display name) — without one it falls back to the id, which is an
+ * address or a group id and is always at least true.
+ */
+export function describeShareEvent(event: ShareEvent, subjectLabel?: string): string {
+	const who = subjectLabel?.trim() || event.subject.id;
+	const target = event.subject.type === "group" ? `the group ${who}` : who;
+	switch (event.action) {
+		case "grant":
+			return `${event.actor} shared this with ${target} (${event.level === "write" ? "can change it" : "view only"})`;
+		case "regrade":
+			return `${event.actor} changed ${target} from ${event.previousLevel} to ${event.level}`;
+		case "revoke":
+			return `${event.actor} stopped sharing this with ${target}${event.note ? ` — ${event.note}` : ""}`;
+		case "group.create":
+			return `${event.actor} created the group ${event.note || who}`;
+		case "group.rename":
+			return `${event.actor} renamed a group to ${event.note}`;
+		case "group.delete":
+			return `${event.actor} deleted the group ${who}`;
+		case "group.join":
+			return `${event.actor} added ${event.note} to the group ${who}`;
+		case "group.leave":
+			return `${event.actor} removed ${event.note} from the group ${who}`;
+	}
+}
+
+/** A sentence for a UI: what this access lets somebody do. One wording, so eleven
+ *  apps do not invent eleven. */
+export const describeAccess = (access: ShareAccess): string =>
+	access === "write"
+		? "Can view and change it"
+		: access === "read"
+			? "Can view it"
+			: "No access";