@k2b/cloud 0.42.0 → 0.44.0

package/src/server/public-storage.ts

@@ -0,0 +1,106 @@
+import { objectStoreBackend } from "../_internal/object-store-config";
+import { validateObjectKey } from "../_internal/object-store-key";
+import { get } from "../services/settings";
+import { clientIpBucket } from "./client-ip";
+import { ratelimit } from "./ratelimit";
+
+const notFound = () => new Response(null, { status: 404, headers: { "Cache-Control": "no-store" } });
+
+/** Platform-owned anonymous delivery. Never accepts a bucket, private prefix or listing. */
+export const servePublicStorage = async (request: Request, clientAddress = "unknown"): Promise<Response> => {
+  let path: string;
+  try {
+    // Validate before application decoding; Bun has already resolved transport
+    // dot segments. The S3 key below always starts in the public area.
+    const raw = request.url.replace(/^[a-z]+:\/\/[^/]+/i, "").split(/[?#]/, 1)[0] ?? "";
+    if (/[\\]|%(?:2e|2f|5c)/i.test(raw)) return notFound();
+    const match = /^\/public\/storage\/([a-z][a-z0-9-]{0,79})\/(.+)$/.exec(raw);
+    if (!match || match[1] === "storage") return notFound();
+    const area = `public/${match[1]}/`;
+    path = area + validateObjectKey(decodeURIComponent(match[2] ?? ""), area);
+  } catch {
+    return notFound();
+  }
+  if (request.method !== "GET" && request.method !== "HEAD") return notFound();
+  try {
+    const perSecond = Math.max(1, Math.floor(await get<number>("security.rate_limit_per_second")));
+    const budget = await ratelimit({ id: "public-storage", limit: perSecond }).check(clientIpBucket(clientAddress));
+    if (budget.limited)
+      return new Response("Rate limit exceeded.", {
+        status: 429,
+        headers: { "Cache-Control": "no-store", "Retry-After": String(Math.max(1, Math.ceil(budget.resetIn / 1000))) },
+      });
+    const { client, limit } = await objectStoreBackend();
+    const stat = await client.stat(path);
+    if (stat.size > limit) return notFound();
+    const headers = new Headers({
+      "Content-Type": stat.type || "application/octet-stream",
+      "Content-Length": String(stat.size),
+      ETag: stat.etag,
+      "Last-Modified": stat.lastModified.toUTCString(),
+      "Cache-Control": "public, max-age=300",
+      "X-Content-Type-Options": "nosniff",
+      // Apply to every type, including mislabelled or future active formats.
+      "Content-Security-Policy": "sandbox; default-src 'none'; frame-ancestors 'none'",
+    });
+    const essence = stat.type.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+    const inline =
+      /^(?:image\/(?:png|jpeg|gif|webp|avif|bmp|x-icon)|audio\/(?:mpeg|ogg|wav|webm|mp4)|video\/(?:mp4|webm|ogg)|text\/plain)$/;
+    if (!inline.test(essence)) headers.set("Content-Disposition", "attachment");
+    const ifNoneMatch = request.headers.get("if-none-match");
+    const modifiedSince = request.headers.get("if-modified-since");
+    if (
+      ifNoneMatch
+        ? ifNoneMatch.split(",").some((value) => value.trim() === stat.etag || value.trim() === "*")
+        : modifiedSince && stat.lastModified.getTime() <= Date.parse(modifiedSince)
+    ) {
+      headers.delete("Content-Length");
+      return new Response(null, { status: 304, headers });
+    }
+    if (request.method === "HEAD") return new Response(null, { headers });
+    const reader = client.file(path).stream().getReader();
+    let size = 0;
+    const abort = () => {
+      void reader.cancel(request.signal.reason).catch(() => {});
+    };
+    request.signal.addEventListener("abort", abort, { once: true });
+    const release = () => {
+      request.signal.removeEventListener("abort", abort);
+      reader.releaseLock();
+    };
+    if (request.signal.aborted) abort();
+    const stream = new ReadableStream<Uint8Array>(
+      {
+        async pull(controller) {
+          try {
+            const next = await reader.read();
+            if (next.done) {
+              release();
+              controller.close();
+              return;
+            }
+            size += next.value.byteLength;
+            if (size > limit) throw new RangeError("Public object exceeds the configured size limit.");
+            controller.enqueue(next.value);
+          } catch (error) {
+            await reader.cancel(error).catch(() => {});
+            release();
+            controller.error(error);
+          }
+        },
+        async cancel(reason) {
+          try {
+            await reader.cancel(reason);
+          } finally {
+            release();
+          }
+        },
+      },
+      { highWaterMark: 0 },
+    );
+    return new Response(stream, { headers });
+  } catch (error) {
+    if (error instanceof Error && "code" in error && ["NoSuchKey", "NotFound", "ENOENT"].includes(String(error.code))) return notFound();
+    return new Response("Storage is unavailable.", { status: 503, headers: { "Cache-Control": "no-store" } });
+  }
+};

package/src/server/services/access.ts

@@ -5,6 +5,7 @@ import { accessMessages } from "../../access/messages";
 import { recursiveGroupIdsSubquery } from "../../services/accounts/group-sql";
 import { toPgUuidArray } from "../../services/postgres";
 import type { ServiceAccountKind } from "../../services/service-accounts";
+import type { RequestAuthority } from "../middleware/auth";
 
 export type AccessDb = typeof sql;
 
@@ -305,6 +306,13 @@ export const deleteAccess = async (params: { id: string }, db: AccessDb = sql):
  * Each app implements this to connect their resources to auth.access.
  */
 export type ResourceAccessAdapter<TResourceId = string> = {
+  /**
+   * Whether any resource in this adapter has an effective read/write/admin right.
+   * Use an existence query, never enumerate resources. Preserve domain eligibility,
+   * principal semantics, resource binding and credential ceilings. Use db and signal.
+   * Optional for existing adapters; required when selected by appAccess.resources().
+   */
+  hasAnyRight?: (subject: AccessSubject, context: { authority: RequestAuthority; db: AccessDb; signal: AbortSignal }) => Promise<boolean>;
   /** Get all access entries for a resource */
   list: (resourceId: TResourceId) => Promise<AccessEntry[]>;
   /** Add an access entry to a resource */

package/src/services/accounts/app.ts

@@ -1,5 +1,6 @@
 import { sql } from "bun";
 import { accountCategory } from "../../contracts/account-categories";
+import type { PersonAvatar } from "../../contracts/avatar";
 import type {
   BaseGroup,
   BaseUser,
@@ -7,6 +8,8 @@ import type {
   EntityListItem,
   GroupMember,
   MutationResult,
+  ServiceAccountKind,
+  ServiceAccountStatus,
   User,
   UserProfile,
   UserProvider,
@@ -34,6 +37,7 @@ import { providers } from "../providers";
 import { session } from "../session";
 import { get as getSetting } from "../settings";
 import { type AccountsActor, canMutateManagedGroup, hasOnlySelfUpdateFields, isAdminActor, isSelfTarget } from "./authz";
+import type { AvatarChange, AvatarState } from "./avatar";
 import { listDuplicateEmails } from "./duplicate-emails";
 import * as entities from "./entities";
 import * as groups from "./groups";
@@ -378,6 +382,29 @@ export const accountsAppService = {
         result,
       });
     },
+    getAvatarState: async (config: { id: string }) => users.getAvatarState(config),
+    /** One save of the profile picture dialog: a photo, a built avatar, or which stored picture others see. */
+    updateAvatar: async (config: { actor: AccountsActor; id: string; change: AvatarChange }) => {
+      const target = await users.getMinimal({ id: config.id });
+      const targetInfo = userTarget(target);
+      const selfService = config.actor.userId === config.id;
+      if (!selfService) {
+        const adminError = await requireAdminActor<AvatarState<PersonAvatar>>({
+          actor: config.actor,
+          action: "accounts.user.avatar.update",
+          target: targetInfo,
+        });
+        if (adminError) return adminError;
+      }
+      const result = fromMutationResult(await users.updateAvatar({ id: config.id, change: config.change }));
+      return recordCompletedMutation({
+        action: "accounts.user.avatar.update",
+        actor: auditActor(config.actor),
+        target: targetInfo,
+        metadata: { selfService, kind: result.ok ? result.data.kind : null, avatarHash: result.ok ? result.data.avatarHash : null },
+        result,
+      });
+    },
     group: {
       list: async (config: {
         userId: string;
@@ -388,6 +415,7 @@ export const accountsAppService = {
         const userGroups = await users.getGroups({
           id: config.userId,
           recursive: config.recursive,
+          includePersonal: false,
         });
         const query = config.filter?.query?.trim().toLowerCase();
         const filtered = query ? userGroups.filter((groupName) => groupName.toLowerCase().includes(query)) : userGroups;
@@ -1227,6 +1255,8 @@ export const accountsAppService = {
       profile?: UserProfile;
       userIds?: string[];
       groupIds?: string[];
+      serviceAccountKinds?: ServiceAccountKind[];
+      serviceAccountStatus?: ServiceAccountStatus;
       excludeUserIds?: string[];
       excludeGroupIds?: string[];
       excludeServiceAccountIds?: string[];
@@ -1258,6 +1288,8 @@ export const accountsAppService = {
         profile: config.profile,
         userIds: config.userIds,
         groupIds: config.groupIds,
+        serviceAccountKinds: config.serviceAccountKinds,
+        serviceAccountStatus: config.serviceAccountStatus,
         excludeUserIds: config.excludeUserIds,
         excludeGroupIds: config.excludeGroupIds,
         excludeServiceAccountIds: config.excludeServiceAccountIds,
@@ -1629,9 +1661,9 @@ export const accountsAppService = {
           (SELECT COUNT(*)::int FROM auth.users WHERE provider = 'local') AS local_accounts_total,
           (SELECT COUNT(*)::int FROM auth.users WHERE provider = 'local' AND profile = 'user') AS local_user_accounts_total,
           (SELECT COUNT(*)::int FROM auth.users WHERE provider = 'local' AND profile = 'guest') AS local_guest_accounts_total,
-          (SELECT COUNT(*)::int FROM auth.groups) AS groups_total,
-          (SELECT COUNT(*)::int FROM auth.groups WHERE provider = 'ipa') AS ipa_groups_total,
-          (SELECT COUNT(*)::int FROM auth.groups WHERE provider = 'local') AS local_groups_total,
+          (SELECT COUNT(*)::int FROM auth.groups g WHERE NOT EXISTS (SELECT 1 FROM auth.user_posix p WHERE p.primary_group_id = g.id)) AS groups_total,
+          (SELECT COUNT(*)::int FROM auth.groups g WHERE provider = 'ipa' AND NOT EXISTS (SELECT 1 FROM auth.user_posix p WHERE p.primary_group_id = g.id)) AS ipa_groups_total,
+          (SELECT COUNT(*)::int FROM auth.groups g WHERE provider = 'local' AND NOT EXISTS (SELECT 1 FROM auth.user_posix p WHERE p.primary_group_id = g.id)) AS local_groups_total,
           (SELECT COUNT(*)::int FROM auth.account_requests WHERE status = 'pending') AS open_requests,
           (
             SELECT COUNT(*)::int

package/src/services/accounts/avatar.ts

@@ -1,7 +1,18 @@
 import { createHash } from "node:crypto";
 import { sql } from "bun";
+import {
+  type AvatarConfig,
+  type AvatarKind,
+  canonicalAvatarConfig,
+  type PersonAvatar,
+  PersonAvatarSchema,
+  type RobotAvatar,
+  RobotAvatarSchema,
+  robotAvatarFromSeed,
+} from "../../contracts/avatar";
 import { MAX_AVATAR_BYTES, MAX_AVATAR_DATA_URL_LENGTH } from "../../contracts/profile";
 import type { MutationResult } from "../../contracts/shared";
+import { AVATAR_RENDERER_REVISION, renderAvatarSvg } from "../../shared/avatar-art";
 import { stripImageMetadata } from "../image-metadata";
 
 export { MAX_AVATAR_BYTES, MAX_AVATAR_DATA_URL_LENGTH } from "../../contracts/profile";
@@ -78,46 +89,342 @@ export const parseAvatarDataUrl = (input: string): MutationResult<ParsedAvatarDa
   };
 };
 
-export const getAvatar = async (params: { id: string }): Promise<StoredAvatar | null> => {
-  const [row] = await sql<{ avatar_data_url: string | null; avatar_hash: string | null }[]>`
-    SELECT avatar_data_url, avatar_hash
-    FROM auth.users
-    WHERE id = ${params.id}::uuid
-  `;
-  if (!row?.avatar_data_url || !row.avatar_hash) return null;
+/** The image others see under an account's avatar URL. */
+export type ServedAvatar = {
+  hash: string;
+  contentType: ParsedAvatarDataUrl["contentType"] | "image/svg+xml";
+  bytes: Buffer;
+};
+
+/**
+ * What the profile picture dialog shows: the active kind, the built config, and the stored photo. Only the account
+ * holder (or an administrator for a service account) reads this; others see only the active picture.
+ */
+export type AvatarState<Built extends AvatarConfig = AvatarConfig> = {
+  kind: AvatarKind;
+  built: Built | null;
+  hasPhoto: boolean;
+  photo: string | null;
+  avatarHash: string | null;
+};
+
+/** One save in the dialog: store and show a photo or a built avatar, or switch to what is stored. */
+export type AvatarChange<Built extends AvatarConfig = AvatarConfig> = { dataUrl: string } | { built: Built } | { use: AvatarKind };
+
+type AvatarRow = {
+  id: string;
+  avatar_kind: AvatarKind | null;
+  avatar_config: unknown;
+  avatar_data_url: string | null;
+  avatar_hash: string | null;
+};
+
+/** The hash of a built avatar; it changes with the renderer revision, so caches refetch a redrawn avatar. */
+export const builtAvatarHash = (config: AvatarConfig): string =>
+  createHash("sha256")
+    .update(`built:${AVATAR_RENDERER_REVISION}:${canonicalAvatarConfig(config)}`)
+    .digest("hex");
 
+const svgAvatar = (config: AvatarConfig, hash: string): ServedAvatar => ({
+  hash,
+  contentType: "image/svg+xml",
+  bytes: Buffer.from(renderAvatarSvg(config)),
+});
+
+const photoAvatar = (row: AvatarRow): ServedAvatar | null => {
+  if (!row.avatar_data_url || !row.avatar_hash) return null;
   const parsed = parseAvatarDataUrl(row.avatar_data_url);
-  if (!parsed.ok) return null;
-  if (parsed.data.hash !== row.avatar_hash) return null;
+  if (!parsed.ok || parsed.data.hash !== row.avatar_hash) return null;
   return parsed.data;
 };
 
-export const setAvatar = async (params: { id: string; dataUrl: string }): Promise<MutationResult<{ avatarHash: string }>> => {
-  const parsed = parseAvatarDataUrl(params.dataUrl);
-  if (!parsed.ok) return parsed;
+const parsePerson = (value: unknown): PersonAvatar | null => {
+  const parsed = PersonAvatarSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+};
+const parseRobot = (value: unknown): RobotAvatar | null => {
+  const parsed = RobotAvatarSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+};
+
+/** A row from before built avatars has no kind: a stored photo is active, otherwise initials. */
+const userKind = (row: AvatarRow): AvatarKind => row.avatar_kind ?? (row.avatar_data_url ? "photo" : "initials");
+
+/**
+ * A service account always shows a picture: its photo, or its robot, drawn from the account id until customised. The
+ * seed is the id as stored, so every spelling of the id in a URL draws the same robot.
+ */
+const serviceAccountRobot = (row: AvatarRow): RobotAvatar => parseRobot(row.avatar_config) ?? robotAvatarFromSeed(row.id);
+
+const readUserRow = async (db: typeof sql, id: string, lock = false): Promise<AvatarRow | undefined> => {
+  const [row] = lock
+    ? await db<AvatarRow[]>`
+        SELECT id, avatar_kind, avatar_config, avatar_data_url, avatar_hash FROM auth.users WHERE id = ${id}::uuid FOR UPDATE
+      `
+    : await db<AvatarRow[]>`SELECT id, avatar_kind, avatar_config, avatar_data_url, avatar_hash FROM auth.users WHERE id = ${id}::uuid`;
+  return row;
+};
+
+const readServiceAccountRow = async (db: typeof sql, id: string, lock = false): Promise<AvatarRow | undefined> => {
+  const [row] = lock
+    ? await db<AvatarRow[]>`
+        SELECT id, avatar_kind, avatar_config, avatar_data_url, avatar_hash FROM auth.service_accounts WHERE id = ${id}::uuid FOR UPDATE
+      `
+    : await db<AvatarRow[]>`
+        SELECT id, avatar_kind, avatar_config, avatar_data_url, avatar_hash FROM auth.service_accounts WHERE id = ${id}::uuid
+      `;
+  return row;
+};
 
+/**
+ * The image others see for a person or a service account, or null when a person shows initials. An inactive photo is
+ * never served.
+ */
+export const getAvatar = async (params: { id: string }): Promise<ServedAvatar | null> => {
+  const user = await readUserRow(sql, params.id);
+  if (user) {
+    const kind = userKind(user);
+    if (kind === "photo") return photoAvatar(user);
+    if (kind === "built") {
+      // The served hash comes from the renderer drawing these bytes, not from storage: while a rollout mixes renderer
+      // revisions, a stored hash of another revision never marks these bytes as immutable.
+      const config = parsePerson(user.avatar_config);
+      return config ? svgAvatar(config, builtAvatarHash(config)) : null;
+    }
+    return null;
+  }
+  const account = await readServiceAccountRow(sql, params.id);
+  if (!account) return null;
+  if (account.avatar_kind === "photo") return photoAvatar(account);
+  const robot = serviceAccountRobot(account);
+  return svgAvatar(robot, builtAvatarHash(robot));
+};
+
+const userState = (row: AvatarRow): AvatarState<PersonAvatar> => ({
+  kind: userKind(row),
+  built: parsePerson(row.avatar_config),
+  hasPhoto: row.avatar_data_url !== null,
+  photo: row.avatar_data_url,
+  avatarHash: row.avatar_hash,
+});
+
+const serviceAccountState = (row: AvatarRow): AvatarState<RobotAvatar> => {
+  const robot = serviceAccountRobot(row);
+  return {
+    kind: row.avatar_kind === "photo" ? "photo" : "built",
+    built: robot,
+    hasPhoto: row.avatar_data_url !== null,
+    photo: row.avatar_data_url,
+    avatarHash: row.avatar_kind === "photo" ? row.avatar_hash : (row.avatar_hash ?? builtAvatarHash(robot)),
+  };
+};
+
+export const getAvatarState = async (params: { id: string }): Promise<AvatarState<PersonAvatar> | null> => {
+  const row = await readUserRow(sql, params.id);
+  return row ? userState(row) : null;
+};
+
+export const getServiceAccountAvatarState = async (params: { id: string }): Promise<AvatarState<RobotAvatar> | null> => {
+  const row = await readServiceAccountRow(sql, params.id);
+  return row ? serviceAccountState(row) : null;
+};
+
+const strippedPhoto = (dataUrl: string): MutationResult<{ dataUrl: string; hash: string }> => {
+  const parsed = parseAvatarDataUrl(dataUrl);
+  if (!parsed.ok) return parsed;
   const bytes = Buffer.from(stripImageMetadata(parsed.data.bytes));
-  const dataUrl = `data:${parsed.data.contentType};base64,${bytes.toString("base64")}`;
-  const rows = await sql<{ avatar_hash: string }[]>`
-    UPDATE auth.users
-    SET avatar_data_url = ${dataUrl},
-        avatar_hash = ${hashAvatar(dataUrl)}
-    WHERE id = ${params.id}::uuid
-    RETURNING avatar_hash
-  `;
-  const avatarHash = rows[0]?.avatar_hash;
-  if (!avatarHash) return { ok: false, error: "User not found", status: 404 };
-  return { ok: true, data: { avatarHash } };
-};
-
-export const clearAvatar = async (params: { id: string }): Promise<MutationResult<void>> => {
-  const rows = await sql<{ id: string }[]>`
-    UPDATE auth.users
-    SET avatar_data_url = NULL,
-        avatar_hash = NULL
-    WHERE id = ${params.id}::uuid
-    RETURNING id
-  `;
-  if (!rows[0]) return { ok: false, error: "User not found", status: 404 };
-  return { ok: true, data: undefined };
+  const stripped = `data:${parsed.data.contentType};base64,${bytes.toString("base64")}`;
+  return { ok: true, data: { dataUrl: stripped, hash: hashAvatar(stripped) } };
+};
+
+const notFound = { ok: false, error: "User not found", status: 404 } as const;
+const missing = (what: string) => ({ ok: false, error: `No ${what} is stored to show.`, status: 409 }) as const;
+
+/** A change whose photo is already stripped; stripping happens before any storage access and throws a typed 422. */
+type PreparedChange = { photo: { dataUrl: string; hash: string } } | Exclude<AvatarChange, { dataUrl: string }>;
+
+const prepareChange = (change: AvatarChange): MutationResult<PreparedChange> => {
+  if (!("dataUrl" in change)) return { ok: true, data: change };
+  const photo = strippedPhoto(change.dataUrl);
+  return photo.ok ? { ok: true, data: { photo: photo.data } } : photo;
+};
+
+/** Applies one dialog save to a person: the new values for the avatar columns, or why the save cannot happen. */
+const nextUserColumns = (row: AvatarRow, change: PreparedChange): MutationResult<AvatarRow> => {
+  if ("photo" in change) {
+    return { ok: true, data: { ...row, avatar_kind: "photo", avatar_data_url: change.photo.dataUrl, avatar_hash: change.photo.hash } };
+  }
+  if ("built" in change) {
+    const config = parsePerson(change.built);
+    if (!config) return { ok: false, error: "A person's avatar must use the person shape set.", status: 400 };
+    return { ok: true, data: { ...row, avatar_kind: "built", avatar_config: config, avatar_hash: builtAvatarHash(config) } };
+  }
+  if (change.use === "photo") {
+    if (!row.avatar_data_url) return missing("photo");
+    return { ok: true, data: { ...row, avatar_kind: "photo", avatar_hash: hashAvatar(row.avatar_data_url) } };
+  }
+  if (change.use === "built") {
+    const config = parsePerson(row.avatar_config);
+    if (!config) return missing("avatar");
+    return { ok: true, data: { ...row, avatar_kind: "built", avatar_hash: builtAvatarHash(config) } };
+  }
+  return { ok: true, data: { ...row, avatar_kind: "initials", avatar_hash: null } };
+};
+
+const nextServiceAccountColumns = (row: AvatarRow, change: PreparedChange): MutationResult<AvatarRow> => {
+  if ("photo" in change) {
+    return { ok: true, data: { ...row, avatar_kind: "photo", avatar_data_url: change.photo.dataUrl, avatar_hash: change.photo.hash } };
+  }
+  if ("built" in change) {
+    const config = parseRobot(change.built);
+    if (!config) return { ok: false, error: "A service account's avatar must use the robot shape set.", status: 400 };
+    return { ok: true, data: { ...row, avatar_kind: "built", avatar_config: config, avatar_hash: builtAvatarHash(config) } };
+  }
+  if (change.use === "photo") {
+    if (!row.avatar_data_url) return missing("photo");
+    return { ok: true, data: { ...row, avatar_kind: "photo", avatar_hash: hashAvatar(row.avatar_data_url) } };
+  }
+  if (change.use === "built") {
+    const config = parseRobot(row.avatar_config);
+    return { ok: true, data: { ...row, avatar_kind: "built", avatar_hash: config ? builtAvatarHash(config) : null } };
+  }
+  return { ok: false, error: "A service account always shows a picture: a photo or its robot.", status: 400 };
+};
+
+const writeUserColumns = (db: typeof sql, id: string, row: AvatarRow) => db`
+  UPDATE auth.users
+  SET avatar_kind = ${row.avatar_kind},
+      avatar_config = ${row.avatar_config === null ? null : JSON.stringify(row.avatar_config)}::text::jsonb,
+      avatar_data_url = ${row.avatar_data_url},
+      avatar_hash = ${row.avatar_hash}
+  WHERE id = ${id}::uuid
+`;
+
+const writeServiceAccountColumns = (db: typeof sql, id: string, row: AvatarRow) => db`
+  UPDATE auth.service_accounts
+  SET avatar_kind = ${row.avatar_kind},
+      avatar_config = ${row.avatar_config === null ? null : JSON.stringify(row.avatar_config)}::text::jsonb,
+      avatar_data_url = ${row.avatar_data_url},
+      avatar_hash = ${row.avatar_hash}
+  WHERE id = ${id}::uuid
+`;
+
+/** Saves a person's profile picture: a photo, a built avatar, or which stored picture others see. */
+export const updateAvatar = async (params: { id: string; change: AvatarChange }): Promise<MutationResult<AvatarState<PersonAvatar>>> => {
+  const change = prepareChange(params.change);
+  if (!change.ok) return change;
+  return sql.begin(async (tx) => {
+    const row = await readUserRow(tx, params.id, true);
+    if (!row) return notFound;
+    const next = nextUserColumns(row, change.data);
+    if (!next.ok) return next;
+    await writeUserColumns(tx, params.id, next.data);
+    return { ok: true, data: userState(next.data) };
+  });
+};
+
+/** Saves a service account's picture: a photo, a customised robot, or which of them others see. */
+export const updateServiceAccountAvatar = async (params: {
+  id: string;
+  change: AvatarChange;
+}): Promise<MutationResult<AvatarState<RobotAvatar>>> => {
+  const change = prepareChange(params.change);
+  if (!change.ok) return change;
+  return sql.begin(async (tx) => {
+    const row = await readServiceAccountRow(tx, params.id, true);
+    if (!row) return { ok: false, error: "Service account not found", status: 404 };
+    const next = nextServiceAccountColumns(row, change.data);
+    if (!next.ok) return next;
+    await writeServiceAccountColumns(tx, params.id, next.data);
+    return { ok: true, data: serviceAccountState(next.data) };
+  });
+};
+
+/** Stores and shows a photo. Kept for the photo-only callers; same as `updateAvatar` with `{ dataUrl }`. */
+export const setAvatar = async (params: { id: string; dataUrl: string }): Promise<MutationResult<{ avatarHash: string }>> => {
+  const result = await updateAvatar({ id: params.id, change: { dataUrl: params.dataUrl } });
+  if (!result.ok) return result;
+  return { ok: true, data: { avatarHash: result.data.avatarHash ?? "" } };
+};
+
+/** Deletes a person's photo. When the photo was showing, initials show instead; a shown built avatar stays. */
+export const clearAvatar = async (params: { id: string }): Promise<MutationResult<void>> =>
+  sql.begin(async (tx) => {
+    const row = await readUserRow(tx, params.id, true);
+    if (!row) return notFound;
+    const showingPhoto = userKind(row) === "photo";
+    await writeUserColumns(tx, params.id, {
+      ...row,
+      avatar_kind: showingPhoto ? "initials" : row.avatar_kind,
+      avatar_data_url: null,
+      avatar_hash: showingPhoto ? null : row.avatar_hash,
+    });
+    return { ok: true, data: undefined };
+  });
+
+/** Deletes a service account's photo; its robot shows again. */
+export const clearServiceAccountAvatar = async (params: { id: string }): Promise<MutationResult<AvatarState<RobotAvatar>>> =>
+  sql.begin(async (tx) => {
+    const row = await readServiceAccountRow(tx, params.id, true);
+    if (!row) return { ok: false, error: "Service account not found", status: 404 };
+    const config = parseRobot(row.avatar_config);
+    const next: AvatarRow = { ...row, avatar_kind: "built", avatar_data_url: null, avatar_hash: config ? builtAvatarHash(config) : null };
+    await writeServiceAccountColumns(tx, params.id, next);
+    return { ok: true, data: serviceAccountState(next) };
+  });
+
+const REFRESH_BATCH = 500;
+
+type RefreshRow = { id: string; avatar_config: unknown; avatar_hash: string | null };
+
+/**
+ * Writes the current renderer's hash for one stored built avatar, only if the row still holds the config and hash
+ * that were read: a save on another replica in between wins and keeps its own hash.
+ */
+export const writeRefreshedHash = async (db: typeof sql, table: "users" | "service_accounts", row: RefreshRow): Promise<boolean> => {
+  const config = table === "users" ? parsePerson(row.avatar_config) : parseRobot(row.avatar_config);
+  const hash = config ? builtAvatarHash(config) : null;
+  if (!hash || hash === row.avatar_hash) return false;
+  const configText = JSON.stringify(row.avatar_config);
+  const written =
+    table === "users"
+      ? await db`
+          UPDATE auth.users SET avatar_hash = ${hash}
+          WHERE id = ${row.id}::uuid AND avatar_kind = 'built'
+            AND avatar_config = ${configText}::text::jsonb AND avatar_hash IS NOT DISTINCT FROM ${row.avatar_hash}
+        `
+      : await db`
+          UPDATE auth.service_accounts SET avatar_hash = ${hash}
+          WHERE id = ${row.id}::uuid AND COALESCE(avatar_kind, 'built') = 'built'
+            AND avatar_config = ${configText}::text::jsonb AND avatar_hash IS NOT DISTINCT FROM ${row.avatar_hash}
+        `;
+  return written.count > 0;
+};
+
+/**
+ * Re-hashes stored built avatars after the renderer revision changed, so every client fetches the redrawn image. Runs
+ * at startup in bounded batches and writes only rows whose hash differs.
+ */
+export const refreshBuiltAvatarHashes = async (db: typeof sql = sql): Promise<number> => {
+  let updated = 0;
+  for (const table of ["users", "service_accounts"] as const) {
+    let after = "00000000-0000-0000-0000-000000000000";
+    for (;;) {
+      const rows =
+        table === "users"
+          ? await db<RefreshRow[]>`
+              SELECT id, avatar_config, avatar_hash FROM auth.users
+              WHERE avatar_kind = 'built' AND id > ${after}::uuid ORDER BY id LIMIT ${REFRESH_BATCH}
+            `
+          : await db<RefreshRow[]>`
+              SELECT id, avatar_config, avatar_hash FROM auth.service_accounts
+              WHERE COALESCE(avatar_kind, 'built') = 'built' AND avatar_config IS NOT NULL AND id > ${after}::uuid
+              ORDER BY id LIMIT ${REFRESH_BATCH}
+            `;
+      for (const row of rows) if (await writeRefreshedHash(db, table, row)) updated++;
+      if (rows.length < REFRESH_BATCH) break;
+      after = rows.at(-1)?.id ?? after;
+    }
+  }
+  return updated;
 };

package/src/services/accounts/base-group.ts

@@ -4,8 +4,7 @@ import type { BaseGroup, UserProvider } from "../../contracts/shared";
 type DbRow = Record<string, unknown>;
 
 /**
- * Joins the owner of a personal Linux group (the group stored as a user's
- * `auth.user_posix.primary_group_id`) onto `auth.groups g` as
+ * Joins the durable owner of a personal Linux group onto `auth.groups g` as
  * `personal_owner_id`, `personal_owner_uid`, and `personal_owner_display_name`.
  * A function, so importing this module never binds Bun's default `sql` handle.
  */
@@ -15,9 +14,9 @@ export const personalOwnerJoin = () => sql`
       owner.id AS personal_owner_id,
       owner.uid AS personal_owner_uid,
       COALESCE(NULLIF(owner.display_name, ''), NULLIF(owner.mail, ''), owner.uid) AS personal_owner_display_name
-    FROM auth.user_posix owner_posix
-    JOIN auth.users owner ON owner.id = owner_posix.user_id
-    WHERE owner_posix.primary_group_id = g.id
+    FROM auth.personal_groups owner_group
+    JOIN auth.users owner ON owner.id = owner_group.owner_id
+    WHERE owner_group.group_id = g.id AND owner_group.retired_at IS NULL
     ORDER BY owner.id
     LIMIT 1
   ) personal_owner ON TRUE