@k2b/cloud 0.41.0 → 0.42.0

package/src/capabilities/server.ts

@@ -6,11 +6,13 @@ import { dispatchCapability, loadCapabilityCatalogPage } from "../api/capabiliti
 import { env } from "../config/env";
 import {
   CAPABILITY_FRAMEWORK_ERROR_CODES,
+  CAPABILITY_MAX_REVIEW_RESPONSE_BYTES,
   CapabilityActionReviewDataSchema,
   type CapabilityOrigin,
   capabilityResultSchema,
 } from "../contracts/capabilities";
 import type { RequestAuthority } from "../server";
+import { canUseApp } from "../services/app-access";
 import { get } from "../services/settings";
 import { resolveAppPresentation } from "../shared/app-presentation";
 import { publicCloudOrigin } from "../shared/app-url";
@@ -184,7 +186,7 @@ export const invokeCapabilityWithDataSchema = <TDataSchema extends z.ZodType, TI
 ): Promise<CapabilityClientResult<z.output<TDataSchema>>> => invokeCapabilityWithResultSchema(invocation, dataSchema, caller);
 
 export const listCapabilityCatalog = async (
-  options: { cursor?: string; limit?: number; locale?: string } = {},
+  options: { cursor?: string; limit?: number; locale?: string; authority?: RequestAuthority | null } = {},
 ): Promise<CapabilityCatalogClientResult> => {
   const limit = options.limit ?? 25;
   const messages = capabilityMessages(options.locale);
@@ -197,30 +199,35 @@ export const listCapabilityCatalog = async (
   try {
     return {
       ok: true,
-      data: await loadCapabilityCatalogPage({ cursor: options.cursor, limit }, {}, options.locale),
+      data: await loadCapabilityCatalogPage({ cursor: options.cursor, limit }, {}, options.locale, options.authority ?? null),
     };
   } catch {
     return { ok: false, error: { code: "APP_UNAVAILABLE", message: messages.cloudUnavailable, status: 503 } };
   }
 };
 
-export const getCapabilityCatalogApp = async (appId: string, locale?: string): Promise<CapabilityCatalogAppClientResult> => {
+export const getCapabilityCatalogApp = async (
+  appId: string,
+  locale?: string,
+  authority: RequestAuthority | null = null,
+): Promise<CapabilityCatalogAppClientResult> => {
   try {
     const [capability, registeredApp] = await Promise.all([getCapability(appId), getApp(appId)]);
     const presentedApp = registeredApp && locale ? resolveAppPresentation(registeredApp, locale) : registeredApp;
     return {
       ok: true,
-      data: capability
-        ? {
-            appId: capability.appId,
-            appName: presentedApp?.name ?? capability.appName,
-            appIcon: capability.appIcon,
-            appDescription: presentedApp?.description ?? capability.appDescription,
-            manifest: locale
-              ? resolveCapabilityManifestPresentation(capability.manifest, capability.presentation, locale)
-              : capability.manifest,
-          }
-        : null,
+      data:
+        capability && registeredApp && (await canUseApp(authority, registeredApp))
+          ? {
+              appId: capability.appId,
+              appName: presentedApp?.name ?? capability.appName,
+              appIcon: capability.appIcon,
+              appDescription: presentedApp?.description ?? capability.appDescription,
+              manifest: locale
+                ? resolveCapabilityManifestPresentation(capability.manifest, capability.presentation, locale)
+                : capability.manifest,
+            }
+          : null,
     };
   } catch {
     return { ok: false, error: { code: "APP_UNAVAILABLE", message: capabilityMessages(locale).cloudUnavailable, status: 503 } };
@@ -237,7 +244,10 @@ export const getCapabilityActionWording = async (
   appId: string,
   localId: string,
   locale?: string,
+  authority: RequestAuthority | null = null,
 ): Promise<CapabilityActionWording | null> => {
+  const registeredApp = await getApp(appId);
+  if (!registeredApp || !(await canUseApp(authority, registeredApp))) return null;
   const capability = await getCapability(appId);
   const action = capability?.manifest.actions.find((candidate) => candidate.localId === localId);
   return capability && action ? resolveCapabilityActionWording(action, capability.presentation, locale ?? DEFAULT_LOCALE) : null;
@@ -263,7 +273,12 @@ export const reviewCapabilityAction = async <TInput = unknown>(
         locale: caller.locale ?? undefined,
         origin: caller.origin ?? "app",
       });
-      return readCapabilityResponse(outcome, CapabilityActionReviewDataSchema);
+      return await readCapabilityResponse(
+        outcome,
+        CapabilityActionReviewDataSchema,
+        CAPABILITY_MAX_REVIEW_RESPONSE_BYTES,
+        combineCapabilitySignals(caller.signal, invocation.signal),
+      );
     }
     const response = await (caller.transport ?? fetch)(
       new Request(
@@ -276,7 +291,12 @@ export const reviewCapabilityAction = async <TInput = unknown>(
         { body: JSON.stringify({ input: invocation.input }) },
       ),
     );
-    return readCapabilityResponse(response, CapabilityActionReviewDataSchema);
+    return await readCapabilityResponse(
+      response,
+      CapabilityActionReviewDataSchema,
+      CAPABILITY_MAX_REVIEW_RESPONSE_BYTES,
+      combineCapabilitySignals(caller.signal, invocation.signal),
+    );
   } catch (cause) {
     return unavailable(cause, undefined, caller.locale ?? undefined);
   }

package/src/cli/access.ts

@@ -1,3 +1,4 @@
+import { principalLabel } from "../access/principal-label";
 import type { AccessEntry, EntityListItem, PermissionLevel, Principal } from "../contracts";
 import { arg, command, confirmFlag, flag, paginationFlags } from "./commands";
 import type { CloudCliContext, CloudCliTableColumn } from "./index";
@@ -120,21 +121,7 @@ const principalKey = (principal: Principal): string => {
   }
 };
 
-const entryDisplayName = (entry: AccessEntry): string => {
-  if (entry.displayName) return entry.displayName;
-  switch (entry.principal.type) {
-    case "user":
-      return entry.principal.userId;
-    case "group":
-      return entry.principal.groupId;
-    case "service_account":
-      return entry.principal.serviceAccountId;
-    case "authenticated":
-      return "All users (incl. guests)";
-    case "public":
-      return "Public";
-  }
-};
+const entryDisplayName = (entry: AccessEntry, locale?: string): string => principalLabel(entry, locale);
 
 const formatEntityCandidate = (item: EntityListItem): string => {
   if (item.kind === "user") return `${item.user.displayName} (${item.user.uid}${item.user.mail ? `, ${item.user.mail}` : ""})`;
@@ -257,17 +244,20 @@ const entryTypeLabel = (entry: AccessEntry): string => {
 };
 
 // Resource-bound service accounts back resource API keys, which are managed with those keys.
-const accessRows = (entries: AccessEntry[], options: { includeServiceAccounts?: boolean; scopes?: readonly string[] } = {}) =>
+const accessRows = (
+  entries: AccessEntry[],
+  options: { includeServiceAccounts?: boolean; scopes?: readonly string[]; locale?: string } = {},
+) =>
   entries
     .filter((entry) => options.includeServiceAccounts || entry.serviceAccountKind !== "resource_bound")
     .sort((a, b) => {
       const rank = permissionRank(b.permission) - permissionRank(a.permission);
       if (rank !== 0) return rank;
-      return entryDisplayName(a).localeCompare(entryDisplayName(b));
+      return entryDisplayName(a, options.locale).localeCompare(entryDisplayName(b, options.locale));
     })
     .map((entry) => ({
       accessId: entry.id,
-      principal: entryDisplayName(entry),
+      principal: entryDisplayName(entry, options.locale),
       type: entryTypeLabel(entry),
       permission: entry.permission,
       ...(options.scopes ? { scope: entry.scope ?? options.scopes[0] } : {}),
@@ -287,7 +277,7 @@ export const printAccessEntries = (
   options: { includeServiceAccounts?: boolean; jsonValue?: unknown; scopes?: readonly string[] } = {},
 ) => {
   if (printStructured(ctx, options.jsonValue ?? entries)) return;
-  const rows = accessRows(entries, options);
+  const rows = accessRows(entries, { ...options, locale: ctx.options.locale });
   if (rows.length === 0) {
     ctx.print("No direct grants.");
     return;
@@ -426,7 +416,7 @@ export const createAccessCommands = <TResource extends AccessResource>(adapter:
       const principal = await resolveAccessPrincipal(ctx, flags as PrincipalFlags, adapter);
       const entry = await adapter.grant(ctx, resource, principal, permission, scope);
       if (!printStructured(ctx, { resource, entry }))
-        ctx.print(`Granted ${permission}${scopeSuffix(scope)} on ${resource.label} to ${entryDisplayName(entry)}.`);
+        ctx.print(`Granted ${permission}${scopeSuffix(scope)} on ${resource.label} to ${entryDisplayName(entry, ctx.options.locale)}.`);
     },
   });
 
@@ -462,13 +452,15 @@ export const createAccessCommands = <TResource extends AccessResource>(adapter:
       if (existing) {
         await adapter.update(ctx, resource, existing.id, permission, scope);
         if (!printStructured(ctx, { resource, accessId: existing.id, permission, scope, action: "updated" })) {
-          ctx.print(`Updated ${entryDisplayName(existing)} to ${permission}${scopeSuffix(scope)} on ${resource.label}.`);
+          ctx.print(
+            `Updated ${entryDisplayName(existing, ctx.options.locale)} to ${permission}${scopeSuffix(scope)} on ${resource.label}.`,
+          );
         }
         return;
       }
       const entry = await adapter.grant(ctx, resource, principal, permission, scope);
       if (!printStructured(ctx, { resource, entry, action: "created" })) {
-        ctx.print(`Granted ${permission}${scopeSuffix(scope)} on ${resource.label} to ${entryDisplayName(entry)}.`);
+        ctx.print(`Granted ${permission}${scopeSuffix(scope)} on ${resource.label} to ${entryDisplayName(entry, ctx.options.locale)}.`);
       }
     },
   });
@@ -496,7 +488,7 @@ export const createAccessCommands = <TResource extends AccessResource>(adapter:
         const entry = entries.find((candidate) => principalKey(candidate.principal) === principalKey(principal));
         if (!entry) throw new Error("No direct grant for that principal.");
         accessId = entry.id;
-        label = entryDisplayName(entry);
+        label = entryDisplayName(entry, ctx.options.locale);
       } else if (principalFlagCount(flags as PrincipalFlags) > 0) {
         throw new Error("Pass either --access-id or one principal flag, not both.");
       }

package/src/cli/admin/linux.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import { type LinuxIdentityConfiguration, LinuxIdentityConfigurationSchema } from "../../contracts/posix";
 import { cliText, command, confirmFlag, flag, printStructured, readCliInput } from "../index";
 import { apiGet, apiJson, queryString } from "./shared";
@@ -31,6 +32,10 @@ export const linuxCommands = [
     flags: {
       config: flag.input({ required: true, description: "Configuration JSON: --config, --config-file, or --stdin" }),
       rangeReserved: flag.boolean({ name: "range-reserved", description: "Confirm the range is reserved across all connected systems" }),
+      replaceUnreadable: flag.boolean({
+        name: "replace-unreadable",
+        description: "Explicitly replace an unreadable stored Linux configuration",
+      }),
       yes: confirmFlag("Confirm replacing Linux identity configuration"),
     },
     async run({ ctx, flags }) {
@@ -40,7 +45,9 @@ export const linuxCommands = [
         );
       const input = await readCliInput(flags.config, { label: "Linux configuration", required: true });
       if (input === undefined) throw new Error("Missing Linux configuration.");
-      const config = LinuxIdentityConfigurationSchema.parse(JSON.parse(input));
+      const { unreadable: _unreadable, ...config } = LinuxIdentityConfigurationSchema.safeExtend({
+        unreadable: z.boolean().optional(),
+      }).parse(JSON.parse(input));
       if (config.enabled && !flags.rangeReserved)
         throw new Error(
           cliText(ctx, {
@@ -48,7 +55,11 @@ export const linuxCommands = [
             de: "Zum Aktivieren ist --range-reserved erforderlich.",
           }),
         );
-      const result = await apiJson<unknown>(ctx, "PUT", `${path}/configuration`, { config, rangeReserved: flags.rangeReserved });
+      const result = await apiJson<unknown>(ctx, "PUT", `${path}/configuration`, {
+        config,
+        rangeReserved: flags.rangeReserved,
+        ...(flags.replaceUnreadable ? { replaceUnreadable: true } : {}),
+      });
       if (!printStructured(ctx, result)) ctx.print(JSON.stringify(result, null, 2));
     },
   }),

package/src/cli/admin/outgoing-mail.ts

@@ -35,13 +35,25 @@ export const outgoingMailCommands = [
     flags: {
       contentDays: flag.string({ required: true, description: "Content retention in days" }),
       recordDays: flag.string({ required: true, description: "Record retention in days (at least content retention)" }),
+      replaceContent: flag.boolean({ name: "replace-unreadable-content", description: "Explicitly replace unreadable content retention" }),
+      replaceRecords: flag.boolean({ name: "replace-unreadable-records", description: "Explicitly replace unreadable record retention" }),
       yes: confirmFlag("Confirm changing outgoing mail retention"),
     },
     async run({ ctx, flags }) {
       confirmed(flags.yes);
       const retention = MailRetentionSchema.parse({ contentDays: Number(flags.contentDays), recordDays: Number(flags.recordDays) });
       if (retention.recordDays < retention.contentDays) throw new Error("Record retention must be at least content retention.");
-      const result = await apiJson<MailRetention>(ctx, "PUT", `${root}/retention`, retention);
+      const result = await apiJson<MailRetention>(ctx, "PUT", `${root}/retention`, {
+        ...retention,
+        ...(flags.replaceContent || flags.replaceRecords
+          ? {
+              replaceUnreadable: [
+                ...(flags.replaceContent ? ["outgoing_mail.content_retention_days"] : []),
+                ...(flags.replaceRecords ? ["outgoing_mail.record_retention_days"] : []),
+              ],
+            }
+          : {}),
+      });
       if (!printStructured(ctx, result)) print(ctx, result);
     },
   }),
@@ -183,7 +195,12 @@ export const outgoingMailCommands = [
       printJsonOrTable(
         ctx,
         result,
-        result.items.map((app) => ({ ...app, reads: app.readDeclared, profiles: app.profiles.join(","), logApps: app.logApps.join(",") })),
+        result.items.map((app) => ({
+          ...app,
+          reads: app.readDeclared,
+          profiles: app.profiles.join(","),
+          logApps: app.logApps.map((id) => `${id}:${app.logContentApps?.includes(id) ? "content" : "metadata"}`).join(","),
+        })),
         [
           { key: "appId" },
           { key: "name" },
@@ -226,15 +243,20 @@ export const outgoingMailCommands = [
     summary: "Choose which other applications' mail logs an app may read",
     args: { app: arg.required({ valueLabel: "app" }) },
     flags: {
-      apps: flag.string({ description: "Comma-separated source application IDs" }),
+      apps: flag.string({ description: "Comma-separated source application IDs (replaces all grants)" }),
+      contentApps: flag.string({ description: "Subset of --apps allowed to read text and attachment names" }),
       ownOnly: flag.boolean({ description: "Remove all other application log grants" }),
       yes: confirmFlag("Confirm application mail log access change"),
     },
     async run({ ctx, args, flags }) {
       confirmed(flags.yes);
       if ((flags.apps !== undefined) === !!flags.ownOnly) throw new Error("Choose exactly one of --apps or --own-only.");
+      if (flags.contentApps !== undefined && flags.apps === undefined) throw new Error("--content-apps requires --apps.");
       const reader = MailLogAppIdSchema.safeParse(args.app);
-      const value = MailLogAccessSchema.safeParse({ apps: flags.apps?.split(",").map((app) => app.trim()) ?? [] });
+      const value = MailLogAccessSchema.safeParse({
+        apps: flags.apps?.split(",").map((app) => app.trim()) ?? [],
+        ...(flags.contentApps !== undefined ? { contentApps: flags.contentApps.split(",").map((app) => app.trim()) } : {}),
+      });
       if (!reader.success || args.app === "core" || !value.success || value.data.apps.includes(args.app))
         throw new Error("Choose a valid reader and distinct source apps other than Core or the reader itself.");
       print(ctx, await apiJson(ctx, "PUT", `${root}/apps/${encodeURIComponent(args.app)}/log-access`, value.data));

package/src/cli/capabilities.ts

@@ -4,6 +4,8 @@ import {
   CAPABILITY_FRAMEWORK_ERROR_CODES,
   CAPABILITY_MAX_CATALOG_BYTES,
   CAPABILITY_MAX_RESULT_BYTES,
+  CAPABILITY_MAX_REVIEW_RESPONSE_BYTES,
+  CapabilityActionReviewDataSchema,
   CapabilityCatalogSchema,
   CapabilityErrorSchema,
   type CapabilityManifest,
@@ -295,6 +297,23 @@ export default defineCliCommands({
         await invoke({ ctx, kind: "queries", appId, capabilityId: reader.localId, inputValue: { id: ref.id }, manifest: app.manifest });
       },
     }),
+    command("review", {
+      summary: "Read the complete proposed Action without executing it",
+      args: { appId: arg.required({ description: "Owning app id" }), actionId: arg.required({ description: "App-local action id" }) },
+      flags: { input: flag.input({ required: true, description: "Strict JSON input; supports --input-file or --stdin" }) },
+      run: async ({ ctx, args, flags }) => {
+        const response = await ctx.fetch(
+          `/api/capabilities/v1/actions/${encodeURIComponent(args.appId)}/${encodeURIComponent(args.actionId)}/review`,
+          {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ input: await parseInput(flags.input) }),
+          },
+        );
+        const review = CapabilityActionReviewDataSchema.parse(await readCapabilityJson(response, CAPABILITY_MAX_REVIEW_RESPONSE_BYTES));
+        printGenericResult(ctx, review);
+      },
+    }),
     command("action", {
       summary: "Invoke an app mutation",
       args: {

package/src/config/env.ts

@@ -98,12 +98,6 @@ const registry = defineEnv({
     scope: "runtime",
     doc: "Comma-separated host names, IP addresses and CIDR ranges on internal networks allowed for outgoing mail SMTP and bounce IMAP connections; unset allows only public targets, an explicit value replaces this default, and invalid entries including `/0` stop the owning process at startup.",
   },
-  GEO_ALLOWED_TARGETS: {
-    schema: envList,
-    default: ["geo"],
-    scope: "runtime",
-    doc: "Comma-separated host names, IP addresses and CIDR ranges on internal networks allowed for Geo requests; unset allows public targets and `geo`, an explicit value replaces this default, and invalid entries including `/0` stop the owning process at startup.",
-  },
 
   // Identity and OAuth
   CLOUD_IDENTITY_KEY_ENCRYPTION_KEY: {

package/src/contracts/app-access.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import type { RequestAuthority } from "../server/middleware/auth";
+import { type Role, RoleSchema } from "./shared";
+
+const publicRoutes = z
+  .array(
+    z
+      .string()
+      .startsWith("/")
+      .refine((path) => !path.startsWith("//") && !/[?#]/.test(path)),
+  )
+  .readonly()
+  .optional();
+export const FixedAppAccessRuleSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("signedIn") }).strict(),
+  z.object({ kind: z.literal("noGuests") }).strict(),
+  z.object({ kind: z.literal("roles"), roles: z.array(RoleSchema).min(1).readonly() }).strict(),
+]);
+export type FixedAppAccessRule = z.infer<typeof FixedAppAccessRuleSchema>;
+export const AppAccessRuleSchema = z.union([
+  z.object({ kind: z.literal("signedIn"), publicRoutes }).strict(),
+  z.object({ kind: z.literal("noGuests"), publicRoutes }).strict(),
+  z.object({ kind: z.literal("roles"), roles: z.array(RoleSchema).min(1).readonly(), publicRoutes }).strict(),
+  z.object({ kind: z.literal("grants"), until: FixedAppAccessRuleSchema.optional(), publicRoutes }).strict(),
+]);
+/** Serializable entry rule evaluated by the platform; never application callback code. */
+export type AppAccessRule = z.infer<typeof AppAccessRuleSchema>;
+/** The optional management restriction runs in the owning application, in addition to a management grant. */
+export type AppAccessDeclaration = AppAccessRule & {
+  canManage?: (authority: RequestAuthority) => boolean | Promise<boolean>;
+};
+type PublicOptions = { publicRoutes?: readonly string[] };
+export const appAccess = {
+  signedIn: (options: PublicOptions = {}): AppAccessRule & { kind: "signedIn" } => ({ kind: "signedIn", ...options }),
+  noGuests: (options: PublicOptions = {}): AppAccessRule & { kind: "noGuests" } => ({ kind: "noGuests", ...options }),
+  roles: (roles: readonly Role[], options: PublicOptions = {}): AppAccessRule & { kind: "roles" } => ({ kind: "roles", roles, ...options }),
+  grants: (
+    options: PublicOptions & { until?: FixedAppAccessRule; canManage?: AppAccessDeclaration["canManage"] } = {},
+  ): AppAccessDeclaration => ({ kind: "grants", ...options }),
+};
+
+export const compileAppAccess = (declaration: AppAccessDeclaration | undefined): AppAccessRule | undefined => {
+  if (!declaration) return undefined;
+  const { canManage, ...rule } = declaration;
+  if (canManage && (rule.kind !== "grants" || typeof canManage !== "function"))
+    throw new Error("Only configurable app access accepts canManage");
+  return AppAccessRuleSchema.parse(rule);
+};

package/src/contracts/app.ts

@@ -1,4 +1,5 @@
 import type { Sync } from "@k2b/sync";
+import type { AppAccessRule } from "./app-access";
 import type { PlatformPermission } from "./outgoing-mail";
 import type { AppRegistryHelpSummary } from "./registry";
 import type { Role } from "./shared";
@@ -15,7 +16,7 @@ export type LegalLink = {
   icon?: string;
 };
 
-/** Static page links for the global search UI, ranked after resource results.
+/** Static page links for the global search UI, shown before resource results.
  * These declare navigation only; they do not create capabilities or readers.
  */
 export type AppSearchLink = {
@@ -24,6 +25,7 @@ export type AppSearchLink = {
   description?: string;
   href: string;
   icon?: string;
+  /** Alternate search terms. At `nav.href`, these also match the automatic app launcher. */
   keywords?: readonly string[];
 };
 
@@ -121,6 +123,7 @@ export type AppPanel = {
 };
 
 export type AppMeta = {
+  access?: AppAccessRule;
   platformPermissions?: readonly PlatformPermission[];
   id: string;
   name: string;

package/src/contracts/approvals.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { APP_APPROVAL_LIMITS } from "./app-approval";
-import { CapabilityActionReviewDataSchema, CapabilityAppIdSchema } from "./capabilities";
+import { CapabilityActionReviewPresentationSchema, CapabilityAppIdSchema } from "./capabilities";
 
 export { APPROVAL_COUNTS_PATH, APPROVALS_API_PATH, APPROVALS_PAGE_PATH } from "./approval-paths";
 
@@ -42,7 +42,7 @@ export const PendingApprovalSchema = z
     /** What the person reads: the first line names the app and the Action, later lines add `Label: value` details. */
     sentence: z.string(),
     /** The owning app's review as the person saw it when Cloud asked. */
-    review: CapabilityActionReviewDataSchema.nullable(),
+    review: CapabilityActionReviewPresentationSchema.nullable(),
     /** Where the request waits. The title is chat content, written by a person or a model, never Cloud's own words. */
     requester: z.object({ kind: z.literal("chat"), appId: z.string(), title: z.string().nullable(), href: z.string() }).strict(),
     /** Ways the person may remember this approval, the same the chat card offers. */

package/src/contracts/avatar.ts

@@ -0,0 +1,186 @@
+import { z } from "zod";
+
+/**
+ * The shape set of built avatars: a person's comic avatar and an agent's robot. A stored config names one option per
+ * part by a stable id. Ids are never removed or renamed once released, so every stored config keeps rendering; new
+ * options only add ids. `v` changes only when the schema itself breaks, and each version keeps its own schema and
+ * drawing.
+ */
+export const AVATAR_SHAPE_SET_VERSION = 1;
+
+export const PERSON_FACES = ["round", "oval", "square"] as const;
+export const PERSON_SKIN_TONES = ["s1", "s2", "s3", "s4", "s5", "s6"] as const;
+/** Every hairstyle passed a human review for unwanted associations; see the review list in the renderer tests. */
+export const PERSON_HAIRSTYLES = ["none", "short", "buzz", "curly", "afro", "long", "bob", "bun", "locs"] as const;
+export const PERSON_HAIR_COLORS = ["black", "dark", "brown", "blond", "red", "grey", "white", "blue", "pink"] as const;
+export const PERSON_EYES = ["dots", "ovals", "happy", "wink", "calm"] as const;
+export const PERSON_BROWS = ["none", "straight", "arched", "thick", "raised"] as const;
+export const PERSON_MOUTHS = ["smile", "grin", "neutral", "oh", "smirk"] as const;
+export const PERSON_BEARDS = ["none", "stubble", "moustache", "goatee", "full"] as const;
+export const PERSON_GLASSES = ["none", "round", "square", "half", "sun"] as const;
+export const PERSON_HEADWEAR = ["none", "beanie", "cap", "hijab", "turban", "kippa", "phones"] as const;
+export const PERSON_EXTRAS = ["none", "freckles", "blush", "earrings", "mole"] as const;
+export const AVATAR_BACKGROUNDS = ["sky", "mint", "sand", "rose", "lilac", "stone", "peach", "teal"] as const;
+
+export const ROBOT_HEADS = ["square", "round", "capsule", "tv"] as const;
+export const ROBOT_ANTENNAS = ["none", "ball", "double", "dish"] as const;
+export const ROBOT_EYES = ["round", "visor", "pixel", "cyclops", "happy"] as const;
+export const ROBOT_MOUTHS = ["grill", "smile", "led", "line", "none"] as const;
+export const ROBOT_BODIES = ["plain", "panel", "light", "buttons"] as const;
+export const ROBOT_COLORS = ["steel", "white", "blue", "teal", "coral", "yellow", "purple", "graphite"] as const;
+
+export const PersonAvatarSchema = z
+  .object({
+    v: z.literal(AVATAR_SHAPE_SET_VERSION),
+    kind: z.literal("person"),
+    face: z.enum(PERSON_FACES),
+    skin: z.enum(PERSON_SKIN_TONES),
+    hair: z.enum(PERSON_HAIRSTYLES),
+    hairColor: z.enum(PERSON_HAIR_COLORS),
+    eyes: z.enum(PERSON_EYES),
+    brows: z.enum(PERSON_BROWS),
+    mouth: z.enum(PERSON_MOUTHS),
+    beard: z.enum(PERSON_BEARDS),
+    glasses: z.enum(PERSON_GLASSES),
+    head: z.enum(PERSON_HEADWEAR),
+    extra: z.enum(PERSON_EXTRAS),
+    bg: z.enum(AVATAR_BACKGROUNDS),
+  })
+  .strict();
+export type PersonAvatar = z.infer<typeof PersonAvatarSchema>;
+
+export const RobotAvatarSchema = z
+  .object({
+    v: z.literal(AVATAR_SHAPE_SET_VERSION),
+    kind: z.literal("robot"),
+    head: z.enum(ROBOT_HEADS),
+    antenna: z.enum(ROBOT_ANTENNAS),
+    eyes: z.enum(ROBOT_EYES),
+    mouth: z.enum(ROBOT_MOUTHS),
+    body: z.enum(ROBOT_BODIES),
+    color: z.enum(ROBOT_COLORS),
+    bg: z.enum(AVATAR_BACKGROUNDS),
+  })
+  .strict();
+export type RobotAvatar = z.infer<typeof RobotAvatarSchema>;
+
+export const AvatarConfigSchema = z.discriminatedUnion("kind", [PersonAvatarSchema, RobotAvatarSchema]);
+export type AvatarConfig = z.infer<typeof AvatarConfigSchema>;
+
+/** Which picture others see: an uploaded photo, the built avatar, or the fallback (initials for people). */
+export const AVATAR_KINDS = ["photo", "built", "initials"] as const;
+export type AvatarKind = (typeof AVATAR_KINDS)[number];
+
+/** A stored config is a handful of short ids; anything larger than this is not a config. */
+export const MAX_AVATAR_CONFIG_BYTES = 1024;
+
+/** The JSON text whose hash identifies a built avatar: keys in schema order, so equal configs hash equally. */
+export const canonicalAvatarConfig = (config: AvatarConfig): string =>
+  JSON.stringify(config.kind === "person" ? PersonAvatarSchema.parse(config) : RobotAvatarSchema.parse(config));
+
+type Random = () => number;
+
+const pick = <T>(list: readonly T[], random: Random): T => list[Math.floor(random() * list.length) % list.length] as T;
+
+/** A first draft for a person: random, with a calm smile and nothing on top, so the person starts from a plain face. */
+export const startPersonAvatar = (random: Random = Math.random): PersonAvatar => ({
+  v: AVATAR_SHAPE_SET_VERSION,
+  kind: "person",
+  face: pick(PERSON_FACES, random),
+  skin: pick(PERSON_SKIN_TONES, random),
+  hair: pick(PERSON_HAIRSTYLES.slice(1), random),
+  hairColor: pick(PERSON_HAIR_COLORS.slice(0, 6), random),
+  eyes: pick(PERSON_EYES, random),
+  brows: pick(PERSON_BROWS.slice(1), random),
+  mouth: "smile",
+  beard: "none",
+  glasses: "none",
+  head: "none",
+  extra: "none",
+  bg: pick(AVATAR_BACKGROUNDS, random),
+});
+
+/** Headwear the random button may choose; religious headwear is only ever the person's own choice. */
+export const RANDOM_PERSON_HEADWEAR = ["beanie", "cap", "phones"] as const;
+
+/** "Random" in the builder: everything changes except the skin tone, which stays the person's choice. */
+export const randomizePersonAvatar = (current: PersonAvatar, random: Random = Math.random): PersonAvatar => {
+  const maybe = <T extends string>(chance: number, list: readonly T[]): T | "none" => (random() < chance ? pick(list, random) : "none");
+  return {
+    v: AVATAR_SHAPE_SET_VERSION,
+    kind: "person",
+    face: pick(PERSON_FACES, random),
+    skin: current.skin,
+    hair: pick(PERSON_HAIRSTYLES.slice(1), random),
+    hairColor: random() < 0.85 ? pick(PERSON_HAIR_COLORS.slice(0, 7), random) : pick(PERSON_HAIR_COLORS, random),
+    eyes: pick(PERSON_EYES, random),
+    brows: pick(PERSON_BROWS.slice(1), random),
+    mouth: pick(PERSON_MOUTHS, random),
+    beard: maybe(0.3, PERSON_BEARDS.slice(1)),
+    glasses: maybe(0.35, PERSON_GLASSES.slice(1)),
+    head: maybe(0.25, RANDOM_PERSON_HEADWEAR),
+    extra: maybe(0.35, PERSON_EXTRAS.slice(1)),
+    bg: pick(AVATAR_BACKGROUNDS, random),
+  };
+};
+
+export const randomRobotAvatar = (random: Random = Math.random): RobotAvatar => ({
+  v: AVATAR_SHAPE_SET_VERSION,
+  kind: "robot",
+  head: pick(ROBOT_HEADS, random),
+  antenna: pick(ROBOT_ANTENNAS, random),
+  eyes: pick(ROBOT_EYES, random),
+  mouth: pick(ROBOT_MOUTHS, random),
+  body: pick(ROBOT_BODIES, random),
+  color: pick(ROBOT_COLORS, random),
+  bg: pick(AVATAR_BACKGROUNDS, random),
+});
+
+/** A small seeded generator (cyrb53 seed, mulberry32 stream): the same seed draws the same robot everywhere. */
+export const seededRandom = (seed: string): Random => {
+  let h1 = 0xdeadbeef;
+  let h2 = 0x41c6ce57;
+  for (let index = 0; index < seed.length; index++) {
+    const code = seed.charCodeAt(index);
+    h1 = Math.imul(h1 ^ code, 2654435761);
+    h2 = Math.imul(h2 ^ code, 1597334677);
+  }
+  let state = (Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909)) >>> 0;
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+};
+
+/**
+ * The parts a seed draws from, frozen at shape set 1. New robot options join the builder, never this list, so an
+ * agent's robot never changes when the shape set grows.
+ */
+const ROBOT_SEED_PARTS_V1 = {
+  head: ["square", "round", "capsule", "tv"],
+  antenna: ["none", "ball", "double", "dish"],
+  eyes: ["round", "visor", "pixel", "cyclops", "happy"],
+  mouth: ["grill", "smile", "led", "line", "none"],
+  body: ["plain", "panel", "light", "buttons"],
+  color: ["steel", "white", "blue", "teal", "coral", "yellow", "purple", "graphite"],
+  bg: ["sky", "mint", "sand", "rose", "lilac", "stone", "peach", "teal"],
+} as const satisfies { [Part in Exclude<keyof RobotAvatar, "v" | "kind">]: readonly RobotAvatar[Part][] };
+
+/** The robot an agent shows until someone changes it: drawn from its account id, so it never changes by itself. */
+export const robotAvatarFromSeed = (seed: string): RobotAvatar => {
+  const random = seededRandom(seed);
+  return {
+    v: AVATAR_SHAPE_SET_VERSION,
+    kind: "robot",
+    head: pick(ROBOT_SEED_PARTS_V1.head, random),
+    antenna: pick(ROBOT_SEED_PARTS_V1.antenna, random),
+    eyes: pick(ROBOT_SEED_PARTS_V1.eyes, random),
+    mouth: pick(ROBOT_SEED_PARTS_V1.mouth, random),
+    body: pick(ROBOT_SEED_PARTS_V1.body, random),
+    color: pick(ROBOT_SEED_PARTS_V1.color, random),
+    bg: pick(ROBOT_SEED_PARTS_V1.bg, random),
+  };
+};