@k2b/cloud 0.42.0 → 0.44.0

package/src/access/PrincipalAvatar.tsx

@@ -0,0 +1,63 @@
+import { Show } from "solid-js";
+import { CloudAvatar } from "../account/Avatar";
+import type { AccessEntry } from "../contracts/shared";
+
+// One hue per principal kind from the avatar palette, so a group, a service account and all signed-in people
+// read apart at a glance. People use a neutral background.
+const hues = { group: "#22c55e", service_account: "#8b5cf6", authenticated: "#3b82f6" } as const;
+
+/** The 32px avatar of an access entry in the expanded editor and on the denial page. */
+export default function PrincipalAvatar(props: {
+  entry: Pick<AccessEntry, "principal" | "avatarHash" | "serviceAccountKind">;
+  label: string;
+}) {
+  const icon = () => {
+    switch (props.entry.principal.type) {
+      case "group":
+        return "ti-users-group";
+      case "service_account":
+        return "ti-robot";
+      case "authenticated":
+        return "ti-world";
+      default:
+        return "ti-world";
+    }
+  };
+  const hue = () => {
+    const type = props.entry.principal.type;
+    return type === "group" || type === "service_account" || type === "authenticated" ? hues[type] : undefined;
+  };
+  return (
+    <Show
+      when={props.entry.principal.type === "user" ? props.entry.principal : undefined}
+      fallback={
+        <span
+          class="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-[var(--ui-surface-muted)] text-secondary"
+          // The avatar formula: a light share of the hue on the surface, a dark share on the text, in both themes.
+          style={
+            hue()
+              ? {
+                  background: `color-mix(in srgb, ${hue()} 18%, var(--k2b-surface))`,
+                  color: `color-mix(in srgb, ${hue()} 55%, var(--k2b-text))`,
+                }
+              : undefined
+          }
+          aria-hidden="true"
+        >
+          <i class={`ti ${icon()} text-xs`} />
+        </span>
+      }
+    >
+      {(user) => (
+        <CloudAvatar
+          username={props.label}
+          userId={user().userId}
+          avatarHash={props.entry.avatarHash}
+          size="sm"
+          class="h-8 w-8"
+          style={{ background: "var(--k2b-surface-muted)", color: "var(--k2b-text-secondary)" }}
+        />
+      )}
+    </Show>
+  );
+}

package/src/access/PrincipalPicker.tsx

@@ -1,5 +1,5 @@
 import { Combobox, type ComboboxOption, useLocale } from "@k2b/ui";
-import type { Principal, ServiceAccountKind } from "../contracts/shared";
+import type { Principal, ServiceAccountKind, ServiceAccountStatus } from "../contracts/shared";
 import { accessMessages } from "./messages";
 import { principalLabel } from "./principal-label";
 import { serviceAccountKindDisplay } from "./service-account-kind";
@@ -24,16 +24,29 @@ type Entity =
         appId: string | null;
         resourceType: string | null;
         resourceId: string | null;
+        status: "active" | "disabled";
       };
     };
+/** The service-account facts a consumer can check before offering an account. */
+export type PrincipalPickerServiceAccount = Extract<Entity, { kind: "service_account" }>["serviceAccount"];
 /** Shared identity selector; the consumer owns the meaning of the assignment. */
 export default function PrincipalPicker(props: {
   existing?: Principal[];
   allowPublic?: boolean;
   allowAuthenticated?: boolean;
+  /** Defaults to true; disable only for a documented user-backed workflow. */
   allowServiceAccounts?: boolean;
+  /** Optional directory filters for the resource's accepted credential kinds. */
+  serviceAccountKinds?: ServiceAccountKind[];
+  serviceAccountStatus?: ServiceAccountStatus;
+  /** Offers only the service accounts this returns `true` for, such as active accounts the resource can accept. */
+  serviceAccountFilter?: (account: PrincipalPickerServiceAccount) => boolean;
   disabled?: boolean;
   readOnly?: boolean;
+  /** Replaces the default placeholder, which lists the principal kinds on offer. */
+  placeholder?: string;
+  /** The consumer's name and description for every signed-in person. */
+  signedIn?: { label: string; description: string };
   /** `serviceAccountKind` is set for service accounts so a new row can show the same kind as the result. */
   onSelect: (
     principal: Principal,
@@ -56,8 +69,9 @@ export default function PrincipalPicker(props: {
     if (props.allowAuthenticated !== false)
       entries.push({
         principal: { type: "authenticated" },
-        label: principalLabel({ principal: { type: "authenticated" } }, locale()),
+        label: props.signedIn?.label ?? principalLabel({ principal: { type: "authenticated" } }, locale()),
         icon: "ti ti-lock-open-2",
+        description: props.signedIn?.description,
       });
     if (props.allowPublic)
       entries.push({
@@ -68,7 +82,13 @@ export default function PrincipalPicker(props: {
     if (search.length >= 2) {
       const url = new URL("/api/accounts/entities", window.location.origin);
       url.searchParams.set("search", search);
-      url.searchParams.set("kinds", props.allowServiceAccounts ? "user,group,service_account" : "user,group");
+      url.searchParams.set("kinds", props.allowServiceAccounts !== false ? "user,group,service_account" : "user,group");
+      if (props.allowServiceAccounts !== false && props.serviceAccountKinds?.length) {
+        url.searchParams.set("service_account_kinds", props.serviceAccountKinds.join(","));
+      }
+      if (props.allowServiceAccounts !== false && props.serviceAccountStatus) {
+        url.searchParams.set("service_account_status", props.serviceAccountStatus);
+      }
       url.searchParams.set("per_page", "10");
       const users = props.existing?.flatMap((p) => (p.type === "user" ? [p.userId] : [])) ?? [];
       const groups = props.existing?.flatMap((p) => (p.type === "group" ? [p.groupId] : [])) ?? [];
@@ -98,7 +118,7 @@ export default function PrincipalPicker(props: {
             icon: "ti ti-users-group",
             description: e.group.description ?? undefined,
           });
-        else {
+        else if (!props.serviceAccountFilter || props.serviceAccountFilter(e.serviceAccount)) {
           const account = e.serviceAccount;
           const kind = serviceAccountKindDisplay(account.kind, t());
           entries.push({
@@ -133,13 +153,14 @@ export default function PrincipalPicker(props: {
       disabled={props.disabled}
       readOnly={props.readOnly}
       placeholder={
-        props.allowAuthenticated !== false || props.allowPublic
-          ? props.allowServiceAccounts
+        props.placeholder ??
+        (props.allowAuthenticated !== false || props.allowPublic
+          ? props.allowServiceAccounts !== false
             ? t().addAll
             : t().addAudience
-          : props.allowServiceAccounts
+          : props.allowServiceAccounts !== false
             ? t().addService
-            : t().addBasic
+            : t().addBasic)
       }
       fetchData={load}
       onSelect={(option) => {

package/src/access/ResourceApiKeys.tsx

@@ -217,12 +217,11 @@ export default function ResourceApiKeys(props: ResourceApiKeysProps) {
     if (confirmed) await revokeMutation.mutate({ id: key.id, name: key.name });
   };
 
-  // The heading is a detail panel section heading: in a detail panel the keys line up with the sections around them,
-  // and below a settings group title they read as one level down.
+  // The heading is a detail panel section heading without an icon: in a details panel the keys line up with the
+  // sections around them, and below a settings group title they read as one level down. Keys are flat rows.
   return (
     <DetailPanel.Section
       title={props.title ?? t().apiKeys}
-      icon="ti ti-key"
       description={props.description ?? t().apiKeysDescription}
       actions={
         <Button type="button" variant="secondary" size="sm" onClick={openCreate} disabled={createMutation.loading()}>
@@ -235,7 +234,7 @@ export default function ResourceApiKeys(props: ResourceApiKeysProps) {
         <div class="flex flex-col gap-2">
           <For each={keys()}>
             {(key) => (
-              <div class="group/api-key flex items-center gap-3 rounded-lg bg-zinc-50/70 p-3 dark:bg-zinc-900/35">
+              <div class="group/api-key flex items-center gap-3 py-1.5">
                 <div class="min-w-0 flex-1">
                   {/* The name and its tags wrap instead of squeezing the name to a few letters in a narrow section. */}
                   <div class="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1">

package/src/access/app-access-adapter.ts

@@ -0,0 +1,51 @@
+import { hc } from "hono/client";
+import { z } from "zod";
+import type { AppAccessApi } from "../api/app-access";
+import { AppAccessSnapshotSchema } from "../contracts/app-access";
+import { AccessEntrySchema } from "../contracts/shared";
+import type { AppAccessChange, AppAccessSnapshot } from "../services/app-access-management";
+
+export class AppAccessClientError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+  }
+}
+
+/** Same audited route for an app's own settings and explicit administration repair. */
+export const appAccessAdapter = (appId: string, options: { repair?: boolean } = {}) => {
+  const client = hc<AppAccessApi>("/_cloud/app-access");
+  const param = { appId };
+  const query = options.repair ? { repair: "1" as const } : {};
+  return {
+    async read(signal?: AbortSignal): Promise<AppAccessSnapshot> {
+      const response = await client[":appId"].$get({ param, query }, { init: { credentials: "same-origin", signal } });
+      const data = await response.json();
+      if (response.ok) return AppAccessSnapshotSchema.parse(data);
+      throw new AppAccessClientError(
+        typeof data === "object" && data !== null && "code" in data && typeof data.code === "string" ? data.code : "APP_ACCESS_READ_FAILED",
+        typeof data === "object" && data !== null && "message" in data && typeof data.message === "string"
+          ? data.message
+          : "The access list could not be loaded.",
+        response.status,
+      );
+    },
+    async change(change: AppAccessChange, signal?: AbortSignal) {
+      const response = await client[":appId"].$post({ param, query, json: change }, { init: { credentials: "same-origin", signal } });
+      const data = await response.json();
+      if (response.ok) return z.object({ entry: AccessEntrySchema.optional(), canUse: z.boolean() }).parse(data);
+      throw new AppAccessClientError(
+        typeof data === "object" && data !== null && "code" in data && typeof data.code === "string"
+          ? data.code
+          : "APP_ACCESS_CHANGE_FAILED",
+        typeof data === "object" && data !== null && "message" in data && typeof data.message === "string"
+          ? data.message
+          : "The access change could not be confirmed.",
+        response.status,
+      );
+    },
+  };
+};

package/src/access/app-access-messages.ts

@@ -0,0 +1,172 @@
+import { i18n } from "@k2b/stdlib";
+
+export const appAccessMessages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      access: "Access",
+      apps: "Apps",
+      app: "App",
+      use: "Use",
+      manage: "Manage access",
+      retry: "Try again",
+      reload: "Reload",
+      accessChanged: "Your app access changed. Reload to check your access.",
+      whoUses: ({ name }: { name: string }) => `Who uses ${name}`,
+      description: ({ name }: { name: string }) =>
+        `Only these people, groups and service accounts see ${name} in the launcher, search and Assistant.`,
+      useDescription: "Open the app and work with it. Permissions within the app control what each person sees.",
+      manageDescription: "Use the app and change this list.",
+      repairNotice: ({ name }: { name: string }) =>
+        `You are editing access as a Cloud administrator. This does not give you use of ${name}. Every change is recorded in the audit log.`,
+      noManagerLead: "No one manages access.",
+      noManager: "Assign at least one person Manage access.",
+      inherited: ({ name }: { name: string }) =>
+        `Until now, all signed-in people could use ${name}. That stays the same until you change it.`,
+      loadFailedLead: "The list could not be loaded.",
+      loadFailed: "No changes were made.",
+      saveFailed: "Not saved.",
+      listChanged: "This grant has changed. Reload the list before trying again.",
+      alreadyGranted: "This entry already has access. Reload the list to see the current access.",
+      uncertain: "The change could not be confirmed. Reload the list before trying again.",
+      savedRefreshFailed: "Saved. The list could not be refreshed. Reload before making another change.",
+      lastManager: "At least one person must manage access. Add another manager first.",
+      forbidden: "You are not allowed to manage this list.",
+      removeSelfTitle: "Remove your own access?",
+      changeSelfTitle: "Change your own access?",
+      removeAudienceTitle: "Remove access for all signed-in people?",
+      removeAudience: ({ name }: { name: string }) => `People without another grant can no longer use ${name}.`,
+      changeSelfEntry: ({ name }: { name: string }) => `This grant for ${name} changes to Use. Your other grants still apply.`,
+      removeSelf: ({ name }: { name: string }) => `Afterwards, you cannot open ${name} or change this list.`,
+      removeSelfManagement: ({ name }: { name: string }) => `You can still use ${name}, but can no longer change this list.`,
+      removeSelfEntry: ({ name }: { name: string }) => `This removes this grant for ${name}. Your other grants still apply.`,
+      remainingManagers: ({ managers, count }: { managers: string; count: number }) =>
+        count === 0 ? "" : count === 1 ? `${managers} still manages access.` : `${managers} still manage access.`,
+      closeNotice: "Close notice",
+      cancel: "Cancel",
+      remove: "Remove",
+      change: "Change",
+      add: "Add a person, group or service account",
+      signedIn: "All signed-in people",
+      signedInDescription: "Everyone with an account in this Cloud",
+      group: ({ count }: { count: number }) =>
+        `Group · ${count === 0 ? "no people" : count === 1 ? "1 person" : `${count.toLocaleString("en")} people`}`,
+      fixedSignedIn: "All signed-in people. The app sets this rule; there is nothing to configure here.",
+      fixedNoGuests: "Signed-in people except guests. The app sets this rule; there is nothing to configure here.",
+      fixedAdmins: "Cloud administrators only. The app sets this rule; there is nothing to configure here.",
+      fixedRoles: "People with the Cloud roles required by the app. The app sets this rule.",
+      resources: "Accounts with an effective resource permission in this app. Manage permissions within the app.",
+      resourcesLabel: "Resource permissions",
+      legacy: "This app uses its existing access checks.",
+      deniedTitle: ({ name }: { name: string }) => `${name} is not available to you`,
+      revokedTitle: ({ name }: { name: string }) => `Your access to ${name} was removed`,
+      revokedDescription: "You had access until now. If this was a mistake, ask:",
+      deniedGrants: "Only people with access may use this app. Access is managed by:",
+      deniedFixed: "If you need this app, contact your Cloud administration.",
+      deniedResources: "Ask someone who manages resource permissions in this app for access.",
+      deniedAdmins: ({ name }: { name: string }) => `Only Cloud administrators use ${name}.`,
+      deniedNoGuests: ({ name }: { name: string }) => `Guests cannot use ${name}.`,
+      deniedRoles: ({ name }: { name: string }) => `Only people with specific Cloud roles use ${name}.`,
+      askAdministration: "Cloud administration",
+      home: "Go to home",
+      adminHintBefore: "As a Cloud administrator, you can repair access under ",
+      adminHintLink: "Administration → Apps",
+      adminHintAfter: ". You need your own grant to use the app.",
+      repair: "Repair access",
+      repairShort: "Repair",
+      backToApps: "Back to Apps",
+      configurable: "Configured in the app",
+      rule: "Who uses the app",
+      overview: "Each app decides who may use it. Review its rule here and repair configurable access when no one manages it.",
+      fixedSignedInLabel: "Fixed: all signed-in people",
+      fixedNoGuestsLabel: "Fixed: no guests",
+      fixedAdminsLabel: "Fixed: Cloud administrators only",
+      fixedRolesLabel: "Fixed: Cloud roles",
+      legacyLabel: "Existing access checks",
+      count: ({ count }: { count: number }) => (count === 1 ? "1 grant" : `${count} grants`),
+    },
+    de: {
+      access: "Zugriff",
+      apps: "Apps",
+      app: "App",
+      use: "Nutzen",
+      manage: "Zugriff verwalten",
+      retry: "Erneut versuchen",
+      reload: "Erneut laden",
+      accessChanged: "Dein App-Zugriff hat sich geändert. Lade die Seite neu, um deinen Zugriff zu prüfen.",
+      whoUses: ({ name }: { name: string }) => `Wer ${name} nutzt`,
+      description: ({ name }: { name: string }) =>
+        `Nur diese Personen, Gruppen und Dienstkonten sehen ${name} im Start-Menü, in der Suche und beim Assistenten.`,
+      useDescription: "App öffnen und mit ihr arbeiten. Was jemand darin sieht, regeln die Rechte der App.",
+      manageDescription: "Nutzen und diese Liste ändern.",
+      repairNotice: ({ name }: { name: string }) =>
+        `Du bearbeitest den Zugriff als Cloud-Admin. Nutzen kannst du ${name} damit nicht. Jede Änderung steht im Protokoll.`,
+      noManagerLead: "Niemand verwaltet den Zugriff.",
+      noManager: "Lege mindestens eine Person mit „Zugriff verwalten“ fest.",
+      inherited: ({ name }: { name: string }) => `Bisher nutzten alle angemeldeten Personen ${name}. Das bleibt so, bis du es änderst.`,
+      loadFailedLead: "Die Liste lädt gerade nicht.",
+      loadFailed: "Es hat sich nichts geändert.",
+      saveFailed: "Nicht gespeichert.",
+      listChanged: "Diese Freigabe wurde inzwischen geändert. Lade die Liste vor einem neuen Versuch erneut.",
+      alreadyGranted: "Dieser Eintrag hat schon Zugriff. Lade die Liste erneut, um den aktuellen Zugriff zu sehen.",
+      uncertain: "Die Änderung konnte nicht bestätigt werden. Lade die Liste vor einem neuen Versuch erneut.",
+      savedRefreshFailed: "Gespeichert. Die Liste konnte nicht aktualisiert werden. Lade sie vor einer weiteren Änderung erneut.",
+      lastManager: "Mindestens eine Person muss den Zugriff verwalten. Füge zuerst eine weitere hinzu.",
+      forbidden: "Du darfst diese Liste nicht verwalten.",
+      removeSelfTitle: "Eigenen Zugriff entfernen?",
+      changeSelfTitle: "Eigenen Zugriff ändern?",
+      removeAudienceTitle: "Zugriff für alle angemeldeten Personen entfernen?",
+      removeAudience: ({ name }: { name: string }) => `Personen ohne weitere Freigabe können ${name} danach nicht mehr nutzen.`,
+      changeSelfEntry: ({ name }: { name: string }) =>
+        `Diese Freigabe für ${name} wird auf Nutzen geändert. Deine anderen Freigaben gelten weiter.`,
+      removeSelf: ({ name }: { name: string }) => `Danach kannst du ${name} nicht mehr öffnen und diese Liste nicht mehr ändern.`,
+      removeSelfManagement: ({ name }: { name: string }) => `Du kannst ${name} weiter nutzen, aber diese Liste nicht mehr ändern.`,
+      removeSelfEntry: ({ name }: { name: string }) => `Diese Freigabe für ${name} wird entfernt. Deine anderen Freigaben gelten weiter.`,
+      remainingManagers: ({ managers, count }: { managers: string; count: number }) =>
+        count === 0 ? "" : count === 1 ? `${managers} verwaltet den Zugriff weiter.` : `${managers} verwalten den Zugriff weiter.`,
+      closeNotice: "Hinweis schließen",
+      cancel: "Abbrechen",
+      remove: "Entfernen",
+      change: "Ändern",
+      add: "Person, Gruppe oder Dienstkonto hinzufügen",
+      signedIn: "Alle angemeldeten Personen",
+      signedInDescription: "Jede Person mit Konto in dieser Cloud",
+      group: ({ count }: { count: number }) =>
+        `Gruppe · ${count === 0 ? "keine Personen" : count === 1 ? "1 Person" : `${count.toLocaleString("de")} Personen`}`,
+      fixedSignedIn: "Alle angemeldeten Personen. Das legt die App fest; hier gibt es dazu nichts einzustellen.",
+      fixedNoGuests: "Angemeldete Personen außer Gästen. Das legt die App fest; hier gibt es dazu nichts einzustellen.",
+      fixedAdmins: "Nur Cloud-Admins. Das legt die App fest; hier gibt es dazu nichts einzustellen.",
+      fixedRoles: "Personen mit den von der App verlangten Cloud-Rollen. Das legt die App fest.",
+      resources: "Konten mit einer wirksamen Ressourcenberechtigung in dieser App. Berechtigungen werden innerhalb der App verwaltet.",
+      resourcesLabel: "Ressourcenberechtigungen",
+      legacy: "Diese App verwendet ihre bisherigen Zugriffsprüfungen.",
+      deniedTitle: ({ name }: { name: string }) => `${name} ist für dich nicht freigegeben`,
+      revokedTitle: ({ name }: { name: string }) => `Dein Zugriff auf ${name} wurde entfernt`,
+      revokedDescription: "Du hattest bis eben Zugriff. Wenn das ein Versehen ist, frag:",
+      deniedGrants: "Diese App nutzen nur Personen mit Freigabe. Den Zugriff verwalten:",
+      deniedFixed: "Wenn du die App brauchst, wende dich an die Cloud-Verwaltung.",
+      deniedResources: "Bitte jemanden, der Ressourcenberechtigungen in dieser App verwaltet, um Zugriff.",
+      deniedAdmins: ({ name }: { name: string }) => `${name} nutzen nur Cloud-Admins.`,
+      deniedNoGuests: ({ name }: { name: string }) => `${name} nutzen nur angemeldete Personen außer Gästen.`,
+      deniedRoles: ({ name }: { name: string }) => `${name} nutzen nur Personen mit bestimmten Cloud-Rollen.`,
+      askAdministration: "Cloud-Verwaltung",
+      home: "Zur Startseite",
+      adminHintBefore: "Als Cloud-Admin kannst du den Zugriff unter ",
+      adminHintLink: "Verwaltung → Apps",
+      adminHintAfter: " reparieren. Nutzen kannst du die App erst mit einer Freigabe.",
+      repair: "Zugriff reparieren",
+      repairShort: "Reparieren",
+      backToApps: "Zurück zu Apps",
+      configurable: "Einstellbar in der App",
+      rule: "Wer nutzt die App",
+      overview:
+        "Jede App legt selbst fest, wer sie nutzt. Hier siehst du die Regeln und reparierst einstellbaren Zugriff, wenn niemand ihn mehr verwaltet.",
+      fixedSignedInLabel: "Fest: alle angemeldeten Personen",
+      fixedNoGuestsLabel: "Fest: keine Gäste",
+      fixedAdminsLabel: "Fest: nur Cloud-Admins",
+      fixedRolesLabel: "Fest: Cloud-Rollen",
+      legacyLabel: "Bisherige Zugriffsprüfungen",
+      count: ({ count }: { count: number }) => (count === 1 ? "1 Freigabe" : `${count} Freigaben`),
+    },
+  },
+});

package/src/access/messages.ts

@@ -4,6 +4,13 @@ export const accessMessages = i18n.define({
   baseLocale: "en",
   messages: {
     en: {
+      newPermission: "Permission for new entry",
+      saved: "Saved",
+      saving: "Saving",
+      you: "you",
+      clearSelection: ({ name }: { name: string }) => `Remove selection: ${name}`,
+      person: "Person",
+      group: "Group",
       view: "View",
       edit: "Edit",
       manage: "Manage",
@@ -87,6 +94,13 @@ export const accessMessages = i18n.define({
       neverUsed: "Never used",
     },
     de: {
+      newPermission: "Recht für neuen Eintrag",
+      saved: "Gespeichert",
+      saving: "Wird gespeichert",
+      you: "du",
+      clearSelection: ({ name }) => `Auswahl entfernen: ${name}`,
+      person: "Person",
+      group: "Gruppe",
       view: "Ansehen",
       edit: "Bearbeiten",
       manage: "Verwalten",

package/src/access/ui.ts

@@ -6,10 +6,13 @@
  * from depending on Cloud's broad legacy UI entrypoint.
  */
 
+export { type AppAccessEditorProps, default as AppAccessEditor } from "./AppAccessEditor";
+export { appAccessAdapter } from "./app-access-adapter";
+export { appAccessMessages } from "./app-access-messages";
 export { isManagerEntry, type ManagerCandidate } from "./managers";
 export type { AllowedLevel, GrantableLevel } from "./PermissionEditor";
 export { default as PermissionEditor } from "./PermissionEditor";
-export { default as PrincipalPicker, principalKey } from "./PrincipalPicker";
+export { default as PrincipalPicker, type PrincipalPickerServiceAccount, principalKey } from "./PrincipalPicker";
 export { principalLabel } from "./principal-label";
 export type {
   ResourceApiKey,

package/src/account/Avatar.tsx

@@ -16,22 +16,40 @@ const avatarSource = (userId?: string | null, avatarHash?: string | null): strin
   return `/api/accounts/users/${encodeURIComponent(userId)}/avatar?rev=${encodeURIComponent(avatarHash)}`;
 };
 
-/** The URL of a person's uploaded picture, or undefined when there is none. */
+/** The URL of a person's picture, or undefined while the person shows initials. */
 export const cloudAvatarSource = avatarSource;
 
+/**
+ * Where an avatar's image comes from. A person has one only with a hash; a service account always has one, its photo
+ * or its robot, so it is linked even without a hash and revalidates. A system actor has none.
+ */
+export const cloudAvatarImage = (params: {
+  kind: CloudAvatarKind;
+  userId?: string | null;
+  avatarHash?: string | null;
+}): string | undefined => {
+  if (params.kind === "user") return avatarSource(params.userId, params.avatarHash);
+  if (params.kind === "system" || !params.userId) return undefined;
+  const rev = params.avatarHash ? `?rev=${encodeURIComponent(params.avatarHash)}` : "";
+  return `/api/accounts/users/${encodeURIComponent(params.userId)}/avatar${rev}`;
+};
+
 const KIND_ICON: Record<CloudAvatarKind, string | undefined> = {
   user: undefined,
   service_account: "ti ti-robot",
   system: "ti ti-settings-automation",
 };
 
-/** One avatar for every Cloud surface: the uploaded picture when there is one, otherwise initials. */
+/**
+ * One avatar for every Cloud surface. A person shows a photo, a built avatar, or initials; a service account shows its
+ * photo or robot in a square, with its icon only while the image cannot load.
+ */
 export function CloudAvatar(props: CloudAvatarProps): JSX.Element {
   const kind = () => props.kind ?? "user";
   return (
     <Avatar
       name={props.username}
-      src={kind() === "user" ? avatarSource(props.userId, props.avatarHash) : undefined}
+      src={cloudAvatarImage({ kind: kind(), userId: props.userId, avatarHash: props.avatarHash })}
       icon={KIND_ICON[kind()]}
       shape={kind() === "user" ? "circle" : "square"}
       alt={props.alt}