@k2b/cloud 0.40.0 → 0.42.0

package/src/_internal/heartbeat.ts

@@ -1,6 +1,8 @@
 /** Keep an app discoverable even when the ephemeral registry is recreated. */
 
-import { APP_REGISTRY_TTL_MS } from "./registry";
+import { createHash, randomBytes } from "node:crypto";
+import { hostname } from "node:os";
+import { APP_REGISTRY_TTL_MS, type AppInstanceRecord, appInstancePrefix } from "./registry";
 
 const HEARTBEAT_INTERVAL_MS = 60_000;
 const HEARTBEAT_WRITE_TIMEOUT_MS = 10_000;
@@ -15,8 +17,171 @@ type HeartbeatRegistry<T> = {
   delete: (input: { key: string }) => Promise<unknown>;
 };
 
+type SnapshotRegistry<T> = {
+  snapshot: (input: { prefix: string }) => Promise<{ entries: { key: string; value: T }[] }>;
+};
+
+type MembershipRegistry = HeartbeatRegistry<AppInstanceRecord> & SnapshotRegistry<AppInstanceRecord>;
+
+type SharedEntry = {
+  read: () => Promise<{ value: unknown } | undefined>;
+  write: () => Promise<unknown>;
+  remove: () => Promise<unknown>;
+  prepare: (() => Promise<void>) | undefined;
+};
+
+const entryDigest = (value: unknown): string => createHash("sha256").update(JSON.stringify(value)).digest("base64url");
+
+type MembershipLock = {
+  withLock: <T>(
+    input: { resource: string; ttlMs?: number; signal?: AbortSignal },
+    fn: (lock: { expiresAt: Date }) => Promise<T>,
+  ) => Promise<T | null>;
+};
+
+/** One process membership shared by its app and capability heartbeats. Getters stay lazy until use. */
+export const createRegistryMembership = (
+  appId: string,
+  options: {
+    registry: () => MembershipRegistry;
+    lock: () => MembershipLock;
+    instanceId?: string;
+    hostname?: string;
+    startedAt?: number;
+    writeTimeoutMs?: number;
+  },
+) => {
+  const instanceId = options.instanceId ?? randomBytes(12).toString("base64url");
+  const prefix = appInstancePrefix(appId);
+  const key = `${prefix}${instanceId}`;
+  const value: AppInstanceRecord = {
+    appId,
+    instanceId,
+    hostname: options.hostname ?? hostname(),
+    startedAt: options.startedAt ?? Date.now(),
+    entries: {},
+  };
+  const writeTimeoutMs = options.writeTimeoutMs ?? HEARTBEAT_WRITE_TIMEOUT_MS;
+  if (!Number.isFinite(writeTimeoutMs) || writeTimeoutMs <= 0) throw new RangeError("Membership write timeout must be positive and finite");
+  let left = false;
+  const sharedEntries = new Map<string, SharedEntry>();
+
+  // Prepare idempotent dependent data outside the lock to preserve its bounded lease.
+  const prepareShared = async (sharedKey: string): Promise<void> => {
+    for (const [key, { prepare }] of sharedEntries) {
+      if (key !== sharedKey) await prepare?.();
+    }
+  };
+
+  const locked = async (write: (lock: { expiresAt: Date }) => Promise<void>): Promise<void> => {
+    const result = await options
+      .lock()
+      .withLock({ resource: appId, ttlMs: writeTimeoutMs, signal: AbortSignal.timeout(writeTimeoutMs) }, async (lock) => {
+        await write(lock);
+        return true;
+      });
+    if (result === null) throw new Error(`Registry membership lock unavailable for app ${appId}`);
+  };
+  const upsert = () => options.registry().upsert({ key, value });
+  const publishShared = async (): Promise<void> => {
+    if (left) return;
+    await upsert();
+    // Never mix entries from different processes: the capability catalog rejects mismatched manifests.
+    for (const { write } of sharedEntries.values()) {
+      if (left) return;
+      await write();
+    }
+  };
+
+  return {
+    join: async (sharedKey: string, sharedValue: unknown, entry: SharedEntry): Promise<void> => {
+      left = false;
+      await prepareShared(sharedKey);
+      await locked(async () => {
+        value.entries[sharedKey] = entryDigest(sharedValue);
+        sharedEntries.set(sharedKey, entry);
+        await publishShared();
+      });
+    },
+    publish: async (sharedKey: string): Promise<void> => {
+      if (left) return;
+      await prepareShared(sharedKey);
+      await locked(async () => {
+        if (left) return;
+        await publishShared();
+      });
+    },
+    adopt: async (sharedKey: string): Promise<void> => {
+      if (left) return;
+      // A live process started after this one covers stored state when all read keys it declares match.
+      // Ignore keys it never registered, but heal split pairs when both keys are declared.
+      // Start order is total (instance id breaks ties), so two live replicas never take turns.
+      const startedLater = (other: AppInstanceRecord): boolean =>
+        other.startedAt > value.startedAt || (other.startedAt === value.startedAt && other.instanceId > value.instanceId);
+      const needsRepublish = async (): Promise<boolean> => {
+        const stored = await Promise.all(
+          [...sharedEntries].map(async ([key, { read }]) => {
+            const entry = await read();
+            return { key, digest: entry ? entryDigest(entry.value) : undefined };
+          }),
+        );
+        if (stored.some(({ digest }) => digest === undefined)) return false;
+        if (stored.every(({ key, digest }) => digest === value.entries[key])) return false;
+        const snapshot = await options.registry().snapshot({ prefix });
+        return !snapshot.entries.some(
+          ({ value }) =>
+            startedLater(value) &&
+            stored.some(({ key }) => key in value.entries) &&
+            stored.every(({ key, digest }) => !(key in value.entries) || value.entries[key] === digest),
+        );
+      };
+      if (!(await needsRepublish())) return;
+      await prepareShared(sharedKey);
+      await locked(async (lock) => {
+        if (left) return;
+        const stillNeedsRepublish = await needsRepublish();
+        if (left || !stillNeedsRepublish) return;
+        if (Date.now() > lock.expiresAt.getTime() - writeTimeoutMs / 2) {
+          throw new Error("membership lease expired during adoption; shared entry left to its TTL");
+        }
+        await publishShared();
+      });
+    },
+    renew: async (): Promise<void> => {
+      if (left) return;
+      if (!(await options.registry().touch({ key }))) {
+        await locked(async () => {
+          if (!left) await upsert();
+        });
+      }
+    },
+    leave: async (): Promise<void> => {
+      left = true;
+      // A failed delete must never lead to shared removal: leave routing to its TTL.
+      // Repeat the delete even after leaving, to remove a late registration write.
+      await options.registry().delete({ key });
+      await locked(async (lock) => {
+        const snapshot = await options.registry().snapshot({ prefix });
+        // Ephemeral has no conditional delete, so the remaining lease bounds the removal window.
+        // A delete that NATS applies only after the lease expired can still remove a newer
+        // replica's entry; that replica restores it on its next refresh (at most 60 s).
+        if (Date.now() > lock.expiresAt.getTime() - writeTimeoutMs / 2) {
+          throw new Error("membership lease expired during stop; shared entry left to its TTL");
+        }
+        if (!snapshot.entries.some((entry) => entry.key !== key)) {
+          for (const { remove } of sharedEntries.values()) {
+            if (Date.now() > lock.expiresAt.getTime() - writeTimeoutMs / 2) {
+              throw new Error("membership lease expired during stop; shared entry left to its TTL");
+            }
+            await remove();
+          }
+        }
+      });
+    },
+  };
+};
+
 type HeartbeatOptions<T> = {
-  registry: HeartbeatRegistry<T>;
   key?: string;
   /** Publish dependent data before advertising or renewing the app. */
   beforeWrite?: () => Promise<void>;
@@ -26,7 +191,10 @@ type HeartbeatOptions<T> = {
   writeTimeoutMs?: number;
   onError?: (error: unknown) => void;
   onStale?: (error: unknown) => void;
-};
+} & (
+  | { registry: HeartbeatRegistry<T>; membership?: undefined }
+  | { registry: HeartbeatRegistry<T> & SnapshotRegistry<T>; membership: ReturnType<typeof createRegistryMembership> }
+);
 
 export const createHeartbeat = <T>(appId: string, entry: T, options: HeartbeatOptions<T>) => {
   const intervalMs = options.intervalMs ?? HEARTBEAT_INTERVAL_MS;
@@ -44,6 +212,7 @@ export const createHeartbeat = <T>(appId: string, entry: T, options: HeartbeatOp
   let timer: Timer | null = null;
   let inFlight: Promise<void> | null = null;
   let running = false;
+  let needsMembershipCleanup = false;
   let lastSuccessAt = 0;
   let staleReported = false;
   const key = options.key ?? `apps/${appId}`;
@@ -54,31 +223,49 @@ export const createHeartbeat = <T>(appId: string, entry: T, options: HeartbeatOp
     staleReported = false;
   };
 
+  const remove = () => (options.membership ? options.membership.leave() : registry.delete({ key }));
+  const upsert = () => registry.upsert({ key, value: entry });
+
   const register = async (): Promise<void> => {
     await options.beforeWrite?.();
-    await registry.upsert({ key, value: entry });
+    if (options.membership) {
+      const registry = options.registry;
+      await options.membership.join(key, entry, {
+        read: async () => (await registry.snapshot({ prefix: key })).entries.find((candidate) => candidate.key === key),
+        write: upsert,
+        remove: () => registry.delete({ key }),
+        prepare: options.beforeWrite,
+      });
+    } else await upsert();
     noteSuccess();
   };
 
   const refresh = async (): Promise<void> => {
     // Touch renews the existing entry (and emits a registry invalidation).
     // Avoid rebuilding the manifest here. A missing entry is repaired
-    // immediately, preserving restart-free registry recovery.
+    // immediately, preserving restart-free registry recovery. The newest live
+    // publisher wins; an entry whose publisher left is replaced by this one.
     await options.beforeWrite?.();
+    await options.membership?.renew();
     const touched = await registry.touch({ key });
-    if (!touched) await registry.upsert({ key, value: entry });
+    if (!touched) {
+      if (options.membership) await options.membership.publish(key);
+      else await upsert();
+    } else if (options.membership) {
+      await options.membership.adopt(key);
+    }
     noteSuccess();
   };
 
   const writeWithTimeout = async (write: Promise<void>): Promise<void> => {
     let timer: Timer | null = null;
     let timedOut = false;
-    void write
-      .then(async () => {
-        // A write that completed after its timeout must not resurrect a stopped app.
-        if (timedOut && !running) await registry.delete({ key }).catch(() => false);
-      })
-      .catch(() => undefined);
+    // A write that settled after its timeout must not resurrect a stopped app. A failed
+    // operation may still have landed earlier steps, such as the liveness key.
+    const removeLateWrite = async () => {
+      if (timedOut && !running) await remove().catch(() => false);
+    };
+    void write.then(removeLateWrite, removeLateWrite).catch(() => undefined);
     try {
       await Promise.race([
         write,
@@ -140,6 +327,7 @@ export const createHeartbeat = <T>(appId: string, entry: T, options: HeartbeatOp
         return;
       }
       running = true;
+      needsMembershipCleanup = options.membership !== undefined;
       const operation = writeWithTimeout(register());
       inFlight = operation;
       try {
@@ -153,7 +341,7 @@ export const createHeartbeat = <T>(appId: string, entry: T, options: HeartbeatOp
       schedule(intervalMs);
     },
     stop: async () => {
-      if (!running) return;
+      if (!running && !needsMembershipCleanup) return;
       running = false;
       if (timer) clearTimeout(timer);
       timer = null;
@@ -165,7 +353,8 @@ export const createHeartbeat = <T>(appId: string, entry: T, options: HeartbeatOp
         // still required so a stopped app cannot remain discoverable.
       }
       inFlight = null;
-      await registry.delete({ key });
+      await remove();
+      needsMembershipCleanup = false;
     },
   };
 };

package/src/_internal/http-drain.ts

@@ -0,0 +1,56 @@
+import type { Server } from "bun";
+
+/** Matches the existing runtime worker drain deadline. */
+export const HTTP_DRAIN_TIMEOUT_MS = 30_000;
+
+/** Bun supplies the listening server to fetch, including for default-export entrypoints. */
+export const createHttpDrain = (options: { timeoutMs?: number } = {}) => {
+  type HttpServer = Pick<Server<unknown>, "stop">;
+  const isHttpServer = (value: unknown): value is HttpServer =>
+    typeof value === "object" && value !== null && "stop" in value && typeof value.stop === "function";
+  const servers = new Set<HttpServer>();
+  let stopping = false;
+  let draining: Promise<void> | undefined;
+  return {
+    get stopping() {
+      return stopping;
+    },
+    fetch: async (request: Request, transport: unknown, handle: (request: Request) => Response | Promise<Response>): Promise<Response> => {
+      const server = isHttpServer(transport) ? transport : undefined;
+      if (server) servers.add(server);
+      if (stopping) {
+        // A listener that had not served a request before the signal was not
+        // captured yet. Reject that first request and close it as well.
+        void server?.stop(false);
+        return Response.json({ status: "stopping" }, { status: 503, headers: { "Retry-After": "3", Connection: "close" } });
+      }
+      // Preserve Bun request identity for websocket upgrades, requestIP and
+      // per-request timeouts. Forced stop aborts the native request signal.
+      return handle(request);
+    },
+    stop: (): Promise<void> => {
+      stopping = true;
+      draining ??= (async () => {
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        let timedOut = false;
+        try {
+          await Promise.race([
+            Promise.all([...servers].map((server) => server.stop(false))),
+            new Promise<void>((resolve) => {
+              timer = setTimeout(() => {
+                // Cancel application work as well as the transport, before
+                // lifecycle hooks can tear down NATS or other dependencies.
+                timedOut = true;
+                resolve();
+              }, options.timeoutMs ?? HTTP_DRAIN_TIMEOUT_MS);
+            }),
+          ]);
+          if (timedOut) await Promise.all([...servers].map((server) => server.stop(true)));
+        } finally {
+          clearTimeout(timer);
+        }
+      })();
+      return draining;
+    },
+  };
+};

package/src/_internal/registry-validation.ts

@@ -1,4 +1,5 @@
 import { CLOUD_CLI_MODULE_NAME } from "../cli/plugin";
+import { AppAccessRuleSchema } from "../contracts/app-access";
 import { PlatformPermissionSchema } from "../contracts/outgoing-mail";
 import type { AppRegistryEntry } from "../contracts/registry";
 import { isOwnAppPath, SAME_ORIGIN_PATH } from "./app-path";
@@ -28,6 +29,8 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
   if (!isStringArray(value.routes) || value.routes.some((route) => !route.startsWith("/"))) {
     return invalid("routes", "an array of absolute paths");
   }
+  if (value.access !== undefined && !AppAccessRuleSchema.safeParse(value.access).success)
+    return invalid("access", "a declarative app access rule");
   if (value.startedAt !== undefined && !(typeof value.startedAt === "number" && Number.isFinite(value.startedAt))) {
     return invalid("startedAt", "a finite number");
   }

package/src/_internal/registry.ts

@@ -1,4 +1,5 @@
-import type { EphemeralConfig } from "@k2b/sync";
+import { createHash } from "node:crypto";
+import type { EphemeralConfig, MutexConfig } from "@k2b/sync";
 import type { AppAppearanceColor } from "../contracts/app";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "../contracts/capabilities";
 import { fileProviderIssues } from "../contracts/file-provider";
@@ -45,6 +46,32 @@ export const CAPABILITY_REGISTRY_CONFIG = {
 } as const satisfies EphemeralConfig;
 
 export const APP_REGISTRY_PREFIX = "apps/";
+export const APP_INSTANCE_PREFIX = "instances/";
+
+// Fit Sync's 96-byte name limit for every app id that fits apps/<id>; appId stays in the record value.
+export const appInstancePrefix = (appId: string): string => {
+  const segment = createHash("sha256").update(appId).digest("base64url").slice(0, 16);
+  return `${APP_INSTANCE_PREFIX}${segment}/`;
+};
+
+export type AppInstanceRecord = {
+  appId: string;
+  instanceId: string;
+  hostname: string;
+  startedAt: number;
+  entries: Record<string, string>;
+};
+
+// The id and owner are a cross-version contract: all replicas must use the same lock.
+// TTL and retry are local budgets; Sync's drift identity is [id, owner, replicas].
+export const APP_MEMBERSHIP_LOCK_CONFIG = {
+  id: "cloud-app-membership",
+  owner: REGISTRY_OWNER,
+  retry: { delayMs: 200, maxAttempts: 50 },
+} as const satisfies MutexConfig;
+
+export const appInstanceRegistry = lazySync((sync) => sync.ephemeral<AppInstanceRecord>(APP_REGISTRY_CONFIG));
+export const appMembershipLock = lazySync((sync) => sync.mutex(APP_MEMBERSHIP_LOCK_CONFIG));
 
 export type CapabilityRegistryRecord = { appId: string; manifest: CapabilityManifest; presentation?: CapabilityPresentationCatalog };
 

package/src/_internal/runtime-context.ts

@@ -15,6 +15,7 @@ export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[], capabiliti
     const searchTags = searchQueries?.flatMap((query) => query.universalSearch!.tags.flatMap((tag) => [tag.tag, ...(tag.aliases ?? [])]));
     return {
       id: e.id,
+      access: e.access,
       platformPermissions: e.platformPermissions ? [...e.platformPermissions] : undefined,
       name: e.name,
       icon: e.icon,

package/src/_internal/setup-lock.ts

@@ -0,0 +1,103 @@
+import type { Mutex } from "@k2b/sync";
+import { expBackoff } from "@k2b/sync/retry";
+import { logger } from "../services/logging";
+import { lazySync, waitForNats } from "./process-sync";
+
+const SETUP_LEASE_MS = 60_000;
+const setupMutex = lazySync((sync) => sync.mutex({ id: "app-setup", owner: "cloud", ttlMs: SETUP_LEASE_MS, retry: { maxAttempts: 1 } }));
+
+const scheduleRenewal = (renew: () => Promise<void> | undefined, intervalMs: number): (() => void) => {
+  const timer = setInterval(() => void renew(), intervalMs);
+  timer.unref();
+  return () => clearInterval(timer);
+};
+
+/** Internal seam for testing lease timing without NATS or wall-clock waits. */
+export const runExclusive = async ({
+  mutex,
+  resource,
+  run,
+  leaseMs = SETUP_LEASE_MS,
+  sleep = Bun.sleep,
+  now = Date.now,
+  schedule = scheduleRenewal,
+  log = logger("setup"),
+}: {
+  mutex: Pick<Mutex, "ready" | "acquire" | "extend" | "release">;
+  resource: string;
+  run: () => Promise<void>;
+  leaseMs?: number;
+  sleep?: (ms: number) => Promise<unknown>;
+  now?: () => number;
+  schedule?: typeof scheduleRenewal;
+  log?: Pick<ReturnType<typeof logger>, "info" | "warn" | "error">;
+}): Promise<void> => {
+  const startedAt = now();
+  const nats = { application: resource };
+  await waitForNats(() => mutex.ready(), nats);
+  let lastWaitLog = Number.NEGATIVE_INFINITY;
+  let attempt = 1;
+  let lock = await waitForNats(() => mutex.acquire({ resource }), nats);
+  while (!lock) {
+    if (now() - lastWaitLog >= 30_000) {
+      lastWaitLog = now();
+      log.info("waiting for setup on another replica", { appId: resource, waitedMs: now() - startedAt });
+    }
+    await sleep(Math.min(2_000, expBackoff(attempt++, { baseMs: 250, maxMs: 2_000, jitter: 0.2 })));
+    lock = await waitForNats(() => mutex.acquire({ resource }), nats);
+  }
+
+  const lease = lock;
+  let lost = false;
+  let running = true;
+  let confirmedExpiresAt = lease.expiresAt.getTime();
+  let renewing: Promise<void> | undefined;
+  const checkExpiry = () => {
+    if (running && now() >= confirmedExpiresAt) lost = true;
+  };
+  const cancelRenewal = schedule(() => {
+    // Check even when an earlier extend is still in flight or the event loop was delayed.
+    checkExpiry();
+    if (renewing || lost) return;
+    renewing = (async () => {
+      try {
+        const extended = await mutex.extend(lease);
+        // extend mutates the handle; check the previous confirmed expiry first.
+        checkExpiry();
+        if (extended) confirmedExpiresAt = lease.expiresAt.getTime();
+        else lost = true;
+      } catch (error) {
+        log.warn("setup lease renewal failed", { appId: resource, error });
+        checkExpiry();
+      }
+    })().finally(() => {
+      renewing = undefined;
+    });
+    return renewing;
+  }, leaseMs / 3);
+
+  try {
+    try {
+      await run();
+    } finally {
+      checkExpiry();
+      running = false;
+      cancelRenewal();
+      // Do not race a release against an unfinished renewal.
+      await renewing;
+      if (lost) {
+        log.error("setup lease lost; another replica may have run setup concurrently; restarting so setup reruns", { appId: resource });
+      }
+    }
+    if (lost) throw new Error(`Setup lease lost for application "${resource}"`);
+  } finally {
+    try {
+      if (!(await mutex.release(lease))) log.warn("setup lease release failed; it will expire", { appId: resource });
+    } catch (error) {
+      log.warn("setup lease release failed; it will expire", { appId: resource, error });
+    }
+  }
+};
+
+export const runSetupExclusively = (appId: string, setup: () => Promise<void>): Promise<void> =>
+  runExclusive({ mutex: setupMutex(), resource: appId, run: setup });

package/src/_internal/status-preserving-ssr.ts

@@ -7,6 +7,7 @@ import type { RailSnapshot } from "../contracts/rail-preferences";
 import type { SettingsFlat, Unflatten } from "../contracts/settings-types";
 import type { User } from "../contracts/shared";
 import type { CORE_SETTINGS } from "../services/settings/core-settings";
+import { preloadDisplayApps } from "../ssr/runtime";
 import { measureServerPhase } from "./server-timing";
 
 type PageEnv<T extends object> = {
@@ -45,6 +46,7 @@ export const createStatusPreservingSsrHandler = <T extends object>(
     const handler = args[args.length - 1] as SsrHandler<E, T>;
 
     return createHandler<E>(...middlewares, async (context) => {
+      await preloadDisplayApps(context);
       const result = await measureServerPhase(context, "ssr_data", () => handler(context as Context<E & PageEnv<T>>));
       if (result instanceof Response) return result;
       await measureServerPhase(context, "ssr_finalize", () => finalizePage?.(context as unknown as Context<PageEnv<T>>));

package/src/access/PermissionEditor.tsx

@@ -4,11 +4,11 @@ import { createEffect, createMemo, createSignal, For, onCleanup, Show } from "so
 import { createStore, reconcile } from "solid-js/store";
 import { CloudAvatar } from "../account/Avatar";
 import type { AccessEntry, PermissionLevel, Principal, ServiceAccountKind } from "../contracts/shared";
-import { groupDisplayName } from "../shared/account-display";
 import { createGroupCoverage, type GroupCoverage, GroupCoveragePanel, GroupCoverageToggle } from "./GroupCoverage";
 import { isManagerEntry } from "./managers";
 import { accessMessages } from "./messages";
 import PrincipalPicker, { principalKey } from "./PrincipalPicker";
+import { principalLabel } from "./principal-label";
 import { serviceAccountKindDisplay } from "./service-account-kind";
 
 // ─────────────────────────────────────────────────────────────────────────
@@ -43,7 +43,7 @@ type PermissionEditorProps = {
   grantAccess: (
     principal: Principal,
     permission: GrantableLevel,
-    display?: { displayName: string; serviceAccountKind?: ServiceAccountKind },
+    display?: { displayName: string; avatarHash?: string | null; serviceAccountKind?: ServiceAccountKind },
     scope?: string,
   ) => Promise<AccessEntry>;
 
@@ -145,16 +145,6 @@ const resolveEntryDisplay = (
   return defaults[permission] ?? defaults.none;
 };
 
-const getEntryDisplayName = (entry: AccessEntry, t: ReturnType<typeof accessMessages.resolve>["t"], locale: string): string => {
-  // Audiences always use the localized label; a server-supplied name is not translated.
-  if (entry.principal.type === "authenticated") return t.allUsers;
-  if (entry.principal.type === "public") return t.public;
-  if (entry.displayName) return entry.principal.type === "group" ? groupDisplayName(entry.displayName, locale) : entry.displayName;
-  if (entry.principal.type === "user") return entry.principal.userId;
-  if (entry.principal.type === "service_account") return entry.principal.serviceAccountId;
-  return entry.principal.groupId;
-};
-
 const getPrincipalIcon = (entry: AccessEntry, t: ReturnType<typeof accessMessages.resolve>["t"]): string => {
   switch (entry.principal.type) {
     case "user":
@@ -204,7 +194,10 @@ export default function PermissionEditor(props: PermissionEditorProps) {
     }
   }
 
-  const grant = async (principal: Principal, display: { displayName: string; serviceAccountKind?: ServiceAccountKind }) => {
+  const grant = async (
+    principal: Principal,
+    display: { displayName: string; avatarHash?: string | null; serviceAccountKind?: ServiceAccountKind },
+  ) => {
     if (disposed || grantPending() || updateMut.loading() || revokeMut.loading()) return;
     const key = principalKey(principal);
     if (entries.some((entry) => principalKey(entry.principal) === key)) return;
@@ -224,8 +217,14 @@ export default function PermissionEditor(props: PermissionEditorProps) {
       const entry = await props.grantAccess(principal, first.level, display, first.scope);
       if (disposed) return;
       const index = entries.findIndex((entry) => entry.id === id);
-      if (index !== -1) setEntries(index, reconcile({ ...entry }));
-      announce(t().accessGranted({ name: display.displayName }));
+      const saved = {
+        ...entry,
+        displayName: entry.displayName ?? display.displayName,
+        avatarHash: entry.avatarHash !== undefined ? entry.avatarHash : display.avatarHash,
+        serviceAccountKind: entry.serviceAccountKind ?? display.serviceAccountKind,
+      };
+      if (index !== -1) setEntries(index, reconcile(saved));
+      announce(t().accessGranted({ name: principalLabel(saved, locale()) }));
     } catch (err) {
       if (!disposed) setEntries((current) => current.filter((entry) => entry.id !== id));
       // Prompts are global, so a grant that fails after its dialog closed still says so.
@@ -264,7 +263,7 @@ export default function PermissionEditor(props: PermissionEditorProps) {
 
   const revokeMut = mutation.create<string | null, AccessEntry>({
     mutation: async (entry) => {
-      const displayName = getEntryDisplayName(entry, t(), locale());
+      const displayName = principalLabel(entry, locale());
       const confirmed = await prompts.confirm(t().removeAccessConfirm({ name: displayName }), {
         title: t().removeAccess,
         variant: "danger",
@@ -395,7 +394,7 @@ function AccessEntryRow(props: {
 }) {
   const locale = useLocale();
   const t = () => accessMessages.resolve([locale()]).t;
-  const displayName = () => getEntryDisplayName(props.entry, t(), locale());
+  const displayName = () => principalLabel(props.entry, locale());
   const entryKey = () => levelKey(props.entry.permission, props.entry.scope);
   const display = () => resolveEntryDisplay(props.entry.permission, props.entry.scope, props.allowed, t());
   const manageLabel = () => resolveEntryDisplay("admin", undefined, props.allowed, t()).label;