@k2b/cloud 0.41.0 → 0.42.0

package/src/_internal/define-app.ts

@@ -1,9 +1,12 @@
 import { type AppSkillDefinition, appSkillManifestHash, registerAppSkills, validateAppSkillCatalog } from "../ai/app-skills";
+import { type AppAccessDeclaration, compileAppAccess } from "../contracts/app-access";
 import { startLiveOutbox } from "../events/live";
 import { registerHelp } from "../services/help";
 import { preloadLayoutHelp } from "../ssr/help";
+import { registerPageSwap } from "../ssr/page-swap";
 import { preloadPanelConsent } from "../ssr/panel-consent";
 import { invokeCapabilityStream } from "./capability-streams";
+import { withCapabilityRequestTimeout } from "./capability-timeout";
 import { bindProcessApplicationId, clearProcessApplicationId } from "./process-identity";
 /**
  * defineApp() — The single entry point for every cloud app.
@@ -49,8 +52,10 @@ import type { AppSettingsMap, KindToType } from "../contracts/settings-types";
 import type { Role } from "../contracts/shared";
 import type { HelpDefinition } from "../server/help";
 import { getLocale, resolveLocale } from "../server/locale";
+import { requireAppAccess, stopAppAccessConnections } from "../server/middleware/app-access";
 import { type AuthContext, auth } from "../server/middleware/auth";
 import { requireInvocation } from "../server/middleware/invocation";
+import "../events/app-access";
 import { matchedRouteTemplate, routeTemplate } from "../server/middleware/route-template";
 import { runtime as runtimeMiddleware } from "../server/middleware/runtime";
 import { preloadLayoutAnnouncements, settings as settingsMiddleware } from "../server/middleware/settings";
@@ -86,6 +91,7 @@ import { cliPluginRoutePrefixes, createCliPluginRoutes, validateAppCliModules }
 import { FONT_PRELOAD_LINKS } from "./font-preloads";
 import { createHeartbeat, createRegistryMembership } from "./heartbeat";
 import { compileHelp } from "./help";
+import { createHttpDrain } from "./http-drain";
 import { createPageResponses } from "./page-responses";
 import { configurePostgresApplicationName } from "./postgres-application-name";
 import { getProcessSync, startProcessSync } from "./process-sync";
@@ -129,6 +135,7 @@ type ResolvedPageOptions = PageOptions & { performanceRoute?: string; themePrefe
  */
 export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefinitionMap = {}, AppId extends string = string> = {
   id: AppId;
+  access?: AppAccessDeclaration;
   name: string;
   icon: string;
   description: string;
@@ -137,6 +144,8 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
   appearance?: AppAppearance;
   /** URL prefix for SSR asset isolation. Omit for the global `/_ssr/` path (core). */
   basePath?: string;
+  /** Swap Layout content within this app while keeping the rail, tab bar and panel document. Default: false; focusMode pages still load a document. */
+  pageSwap?: boolean;
   /** Base URL as seen by other containers (e.g. "http://app-notebooks:3000"). */
   baseUrl: string;
   adminHref?: string;
@@ -530,6 +539,8 @@ export const defineApp = <
   // cannot override.
   const ssr = Object.assign(
     createStatusPreservingSsrHandler<ResolvedPageOptions>(html, async (c) => {
+      if (opts.pageSwap)
+        registerPageSwap(c, isDevelopment ? String(developmentStamp) : `${buildMetadata.version}:${buildMetadata.release}`);
       c.get("page").lang = getLocale(c);
       c.get("page").themePreference = readThemePreferenceFromCookieHeader(c.req.header("Cookie"));
       const user = c.get("user");
@@ -578,13 +589,19 @@ export const defineApp = <
     openapi: opts.openapi,
     cli: opts.cli,
   };
-  const meta: AppMeta = { ...baseMeta, presentation: compileAppPresentation(baseMeta, opts.presentation) };
+  const meta: AppMeta = {
+    ...baseMeta,
+    access: compileAppAccess(opts.access),
+    presentation: compileAppPresentation(baseMeta, opts.presentation),
+  };
 
   // ── 3. start() — builds and boots the Hono server ────────────────────
   const start = async (startOpts: StartOptions): Promise<StartResult> => {
     const port = startOpts.port ?? 3000;
     const baseUrl = opts.baseUrl;
     const log = logger("app");
+    const http = createHttpDrain();
+    if (!meta.access) log.warn("Application has no access declaration; legacy entry and discovery rules remain active", { appId: meta.id });
 
     // Settings are encrypted at rest, so every container needs the secret. It
     // is only read on the first decrypt, which meant a container without it
@@ -632,6 +649,7 @@ export const defineApp = <
       // Registry entry
       const entry: AppRegistryEntry = {
         id: meta.id,
+        access: meta.access,
         name: meta.name,
         icon: meta.icon,
         description: meta.description,
@@ -766,6 +784,7 @@ export const defineApp = <
       // Framework-owned mounts answer before the app's router ever runs, so the
       // app middleware cannot report their template. Without this, every hashed
       // island chunk would land in telemetry as its own route.
+      const invocationApp = { getApp: async (id: string) => (id === meta.id ? meta : null) };
       const server = new Hono<AuthContext>()
         .use("*", routeTemplate)
         .get(APP_READINESS_PATH, () => appReadinessResponse(meta.id))
@@ -774,11 +793,14 @@ export const defineApp = <
         .all("/public/*", servePublicAsset(isDevelopment, sharedStylesheetVersion(buildMetadata.release)))
         .use(
           "/_internal/sync/*",
-          requireInvocation((c) => ({
-            targetAppId: meta.id,
-            operation: syncInvocationOperation(c.req.method, new URL(c.req.url).pathname.slice("/_internal/sync".length)),
-            schemaHash: null,
-          })),
+          requireInvocation(
+            (c) => ({
+              targetAppId: meta.id,
+              operation: syncInvocationOperation(c.req.method, new URL(c.req.url).pathname.slice("/_internal/sync".length)),
+              schemaHash: null,
+            }),
+            invocationApp,
+          ),
         )
         .use("/_internal/sync/*", auth.requireOAuthScope("admin"))
         .use("/_internal/sync/*", async (c, next) => {
@@ -787,79 +809,73 @@ export const defineApp = <
         })
         .route("/_internal/sync", createSyncOpsRoutes(getProcessSync));
 
-      if (opts.cli && cliModules.length > 0) server.route(CLOUD_CLI_PLUGIN_ROUTE, createCliPluginRoutes(meta.id, opts.cli));
-
-      if (compiledHelp) {
-        const pageBase = compiledHelp.summary.pageBase;
-        const centralPageBase = `/help/apps/${encodeURIComponent(meta.id)}`;
-        server.get(pageBase, (c) => c.redirect(centralPageBase, 302));
-        server.get(`${pageBase}/:topic`, (c) => c.redirect(`${centralPageBase}/${encodeURIComponent(c.req.param("topic"))}`, 302));
-      }
-
       if (compiledCapabilities) {
-        const invoke = async (c: Context<AuthContext>, kind: "query" | "action" | "review") => {
-          // Framework-owned endpoints run before the app's settings middleware,
-          // so the operator default is read directly instead of via a snapshot.
-          const requestLocale = resolveLocale(c.req.raw.headers, await get<string>("app.locale"));
-          const messages = capabilityMessages(requestLocale);
-          const parsedBody = await readBoundedJson(c.req.raw, CAPABILITY_MAX_REQUEST_BYTES);
-          if (!parsedBody.ok) {
-            const message = parsedBody.reason === "too_large" ? messages.requestTooLarge : messages.requestBodyJson;
-            return c.json({ code: CAPABILITY_FRAMEWORK_ERROR_CODES.validationFailed, message }, 400);
-          }
-          if (
-            typeof parsedBody.data !== "object" ||
-            parsedBody.data === null ||
-            Array.isArray(parsedBody.data) ||
-            !Object.hasOwn(parsedBody.data, "input") ||
-            Object.keys(parsedBody.data).length !== 1
-          ) {
-            return c.json(
-              {
-                code: CAPABILITY_FRAMEWORK_ERROR_CODES.validationFailed,
-                message: messages.requestInputOnly,
+        const invoke = async (c: Context<AuthContext>, kind: "query" | "action" | "review") =>
+          withCapabilityRequestTimeout(c, kind, async () => {
+            // Framework-owned endpoints run before the app's settings middleware,
+            // so the operator default is read directly instead of via a snapshot.
+            const requestLocale = resolveLocale(c.req.raw.headers, await get<string>("app.locale"));
+            const messages = capabilityMessages(requestLocale);
+            const parsedBody = await readBoundedJson(c.req.raw, CAPABILITY_MAX_REQUEST_BYTES);
+            if (!parsedBody.ok) {
+              const message = parsedBody.reason === "too_large" ? messages.requestTooLarge : messages.requestBodyJson;
+              return c.json({ code: CAPABILITY_FRAMEWORK_ERROR_CODES.validationFailed, message }, 400);
+            }
+            if (
+              typeof parsedBody.data !== "object" ||
+              parsedBody.data === null ||
+              Array.isArray(parsedBody.data) ||
+              !Object.hasOwn(parsedBody.data, "input") ||
+              Object.keys(parsedBody.data).length !== 1
+            ) {
+              return c.json(
+                {
+                  code: CAPABILITY_FRAMEWORK_ERROR_CODES.validationFailed,
+                  message: messages.requestInputOnly,
+                },
+                400,
+              );
+            }
+            const body = parsedBody.data as { input: unknown };
+            const actor = c.get("actor");
+            const user = actor.kind === "user" ? actor.user : actor.delegatedUser;
+            const idempotencyKey = c.req.header("idempotency-key") || undefined;
+            const invocation = {
+              compiled: compiledCapabilities,
+              localId: c.req.param("capabilityId") ?? "",
+              input: body.input,
+              expectedSchemaHash: c.req.header("x-cloud-capability-schema-hash") ?? null,
+              context: {
+                authority: auth.getAuthority(c),
+                actor,
+                accessSubject: c.get("accessSubject"),
+                user,
+                idempotencyKey,
+                locale: requestLocale,
+                requestId: normalizeInvocationRequestId(c.req.header("x-request-id")) ?? crypto.randomUUID(),
+                origin: CapabilityOriginSchema.catch("http").parse(c.req.header(CAPABILITY_ORIGIN_HEADER)),
+                signal: c.req.raw.signal,
               },
-              400,
-            );
-          }
-          const body = parsedBody.data as { input: unknown };
-          const actor = c.get("actor");
-          const user = actor.kind === "user" ? actor.user : actor.delegatedUser;
-          const idempotencyKey = c.req.header("idempotency-key") || undefined;
-          const invocation = {
-            compiled: compiledCapabilities,
-            localId: c.req.param("capabilityId") ?? "",
-            input: body.input,
-            expectedSchemaHash: c.req.header("x-cloud-capability-schema-hash") ?? null,
-            context: {
-              actor,
-              accessSubject: c.get("accessSubject"),
-              user,
-              idempotencyKey,
-              locale: requestLocale,
-              requestId: normalizeInvocationRequestId(c.req.header("x-request-id")) ?? crypto.randomUUID(),
-              origin: CapabilityOriginSchema.catch("http").parse(c.req.header(CAPABILITY_ORIGIN_HEADER)),
-              signal: c.req.raw.signal,
-            },
-            onUnexpectedError: (error: unknown) =>
-              log.error(kind === "review" ? "Capability review failed" : "Capability execution failed", {
-                appId: meta.id,
-                kind,
-                capabilityId: c.req.param("capabilityId") ?? "",
-                error: error instanceof Error ? error.message : String(error),
-              }),
-          };
-          const result =
-            kind === "review" ? await reviewCompiledCapability(invocation) : await invokeCompiledCapability({ ...invocation, kind });
-          const operation = kind === "action" ? compiledCapabilities.actions.get(invocation.localId) : undefined;
-          const serialized = serializeCapabilityProviderResult(result, {
-            nonIdempotentAction: kind === "action" && operation?.manifest.idempotency === "none",
-          });
-          return new Response(serialized.body, {
-            status: serialized.status,
-            headers: { "content-type": "application/json" },
+              onUnexpectedError: (error: unknown) =>
+                log.error(kind === "review" ? "Capability review failed" : "Capability execution failed", {
+                  appId: meta.id,
+                  kind,
+                  capabilityId: c.req.param("capabilityId") ?? "",
+                  error: error instanceof Error ? error.message : String(error),
+                }),
+            };
+            const result =
+              kind === "review" ? await reviewCompiledCapability(invocation) : await invokeCompiledCapability({ ...invocation, kind });
+            const operation = kind === "action" ? compiledCapabilities.actions.get(invocation.localId) : undefined;
+            const serialized = serializeCapabilityProviderResult(result, {
+              review: kind === "review",
+              nonIdempotentAction: kind === "action" && operation?.manifest.idempotency === "none",
+            });
+            return new Response(serialized.body, {
+              status: serialized.status,
+              headers: { "content-type": "application/json" },
+            });
           });
-        };
         const capabilityAuth = (kind: "queries" | "actions", review = false) =>
           requireInvocation((c) => {
             const localId = c.req.param("capabilityId") ?? "";
@@ -878,7 +894,7 @@ export const defineApp = <
               operation: invocationOperation,
               schemaHash: operation.manifest.schemaHash,
             };
-          });
+          }, invocationApp);
         for (const kind of ["queries", "actions"] as const) {
           server.post(
             `/api/_internal/capabilities/v1/streams/${kind}/:capabilityId/:verb`,
@@ -893,6 +909,7 @@ export const defineApp = <
                 verb: c.req.param("verb") ?? "",
                 request: c.req.raw,
                 context: {
+                  authority: auth.getAuthority(c),
                   actor,
                   accessSubject: c.get("accessSubject"),
                   user: actor.kind === "user" ? actor.user : actor.delegatedUser,
@@ -932,7 +949,7 @@ export const defineApp = <
             const widgetId = c.req.param("widgetId") ?? "";
             if (!declaredWidgetIds.has(widgetId) || !startOpts.widgets?.[widgetId]) return null;
             return { targetAppId: meta.id, operation: widgetInvocationOperation(widgetId), schemaHash: null };
-          }),
+          }, invocationApp),
           auth.requireOAuthScope("read", "admin"),
           runtimeMiddleware(),
           settingsMiddleware(),
@@ -947,10 +964,31 @@ export const defineApp = <
         );
       }
 
+      cleanup.push(() => stopAppAccessConnections());
+      server.use(
+        "*",
+        requireAppAccess(meta, (c, message) =>
+          ssr.error(c, 403, {
+            title: "No access",
+            description: message,
+            layout: "minimal",
+          }),
+        ),
+      );
+
+      if (opts.cli && cliModules.length > 0) server.route(CLOUD_CLI_PLUGIN_ROUTE, createCliPluginRoutes(meta.id, opts.cli));
+
+      if (compiledHelp) {
+        const pageBase = compiledHelp.summary.pageBase;
+        const centralPageBase = `/help/apps/${encodeURIComponent(meta.id)}`;
+        server.get(pageBase, (c) => c.redirect(centralPageBase, 302));
+        server.get(`${pageBase}/:topic`, (c) => c.redirect(`${centralPageBase}/${encodeURIComponent(c.req.param("topic"))}`, 302));
+      }
+
       // OpenAPI spec mount. Registered on the framework server (before the
       // user-fetch catch-all below) so it bypasses any auth / rate-limit
       // middleware on the api router — the spec must stay reachable without
-      // a session for `app-api-docs` to render it.
+      // a session for legacy apps. Declared app access is enforced above.
       //
       // The `servers` override is load-bearing: hono-openapi walks the
       // BARE api router and emits paths relative to its own root (e.g.
@@ -1030,18 +1068,36 @@ export const defineApp = <
       log.info(`Registered "${meta.id}"`, { baseUrl });
 
       // Graceful shutdown
-      let stopping = false;
-      const shutdown = async () => {
-        if (stopping) return;
-        stopping = true;
-        log.info(`Stopping: ${meta.id}`);
-        await stopStartedResources();
-      };
+      let shutdownPromise: Promise<void> | undefined;
+      const shutdown = () =>
+        (shutdownPromise ??= (async () => {
+          const drained = http.stop();
+          log.info(`Stopping: ${meta.id}`);
+          try {
+            await drained;
+          } finally {
+            await stopStartedResources();
+          }
+        })());
 
-      process.on("SIGTERM", () => void shutdown().then(() => process.exit(0)));
-      process.on("SIGINT", () => void shutdown().then(() => process.exit(0)));
+      const stopAndExit = () =>
+        void shutdown().then(
+          () => process.exit(0),
+          (error: unknown) => {
+            log.error("HTTP shutdown failed", { appId: meta.id, error: error instanceof Error ? error.message : String(error) });
+            process.exit(1);
+          },
+        );
+      process.on("SIGTERM", stopAndExit);
+      process.on("SIGINT", stopAndExit);
 
-      return { hostname: "0.0.0.0", port, development: isDevelopment, idleTimeout: REQUEST_IDLE_TIMEOUT_SECONDS, fetch: server.fetch };
+      return {
+        hostname: "0.0.0.0",
+        port,
+        development: isDevelopment,
+        idleTimeout: REQUEST_IDLE_TIMEOUT_SECONDS,
+        fetch: (request, bunServer) => http.fetch(request, bunServer, (request) => server.fetch(request, bunServer)),
+      };
     } catch (error) {
       await stopStartedResources();
       throw error;

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/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/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;

package/src/access/PrincipalPicker.tsx

@@ -1,7 +1,7 @@
 import { Combobox, type ComboboxOption, useLocale } from "@k2b/ui";
 import type { Principal, ServiceAccountKind } from "../contracts/shared";
-import { groupDisplayName } from "../shared/account-display";
 import { accessMessages } from "./messages";
+import { principalLabel } from "./principal-label";
 import { serviceAccountKindDisplay } from "./service-account-kind";
 
 export const principalKey = (p: Principal) =>
@@ -13,7 +13,7 @@ export const principalKey = (p: Principal) =>
         ? `s:${p.serviceAccountId}`
         : p.type;
 type Entity =
-  | { kind: "user"; user: { id: string; displayName: string; uid: string; mail: string | null } }
+  | { kind: "user"; user: { id: string; displayName: string; uid: string; mail: string | null; avatarHash?: string | null } }
   | { kind: "group"; group: { id: string; name: string; description: string | null } }
   | {
       kind: "service_account";
@@ -35,17 +35,36 @@ export default function PrincipalPicker(props: {
   disabled?: boolean;
   readOnly?: boolean;
   /** `serviceAccountKind` is set for service accounts so a new row can show the same kind as the result. */
-  onSelect: (principal: Principal, display: { displayName: string; serviceAccountKind?: ServiceAccountKind }) => void;
+  onSelect: (
+    principal: Principal,
+    display: { displayName: string; avatarHash?: string | null; serviceAccountKind?: ServiceAccountKind },
+  ) => void;
 }) {
   const locale = useLocale(),
     t = () => accessMessages.resolve([locale()]).t;
-  type Entry = { principal: Principal; label: string; icon: string; description?: string; serviceAccountKind?: ServiceAccountKind };
+  type Entry = {
+    principal: Principal;
+    label: string;
+    icon: string;
+    description?: string;
+    avatarHash?: string | null;
+    serviceAccountKind?: ServiceAccountKind;
+  };
   let selectable = new Map<string, Entry>();
   const load = async (search: string, signal: AbortSignal): Promise<ComboboxOption[]> => {
     const entries: Entry[] = [];
     if (props.allowAuthenticated !== false)
-      entries.push({ principal: { type: "authenticated" }, label: t().allUsers, icon: "ti ti-lock-open-2" });
-    if (props.allowPublic) entries.push({ principal: { type: "public" }, label: t().public, icon: "ti ti-world" });
+      entries.push({
+        principal: { type: "authenticated" },
+        label: principalLabel({ principal: { type: "authenticated" } }, locale()),
+        icon: "ti ti-lock-open-2",
+      });
+    if (props.allowPublic)
+      entries.push({
+        principal: { type: "public" },
+        label: principalLabel({ principal: { type: "public" } }, locale()),
+        icon: "ti ti-world",
+      });
     if (search.length >= 2) {
       const url = new URL("/api/accounts/entities", window.location.origin);
       url.searchParams.set("search", search);
@@ -64,14 +83,18 @@ export default function PrincipalPicker(props: {
         if (e.kind === "user")
           entries.push({
             principal: { type: "user", userId: e.user.id },
-            label: e.user.displayName || e.user.uid,
+            label: principalLabel(
+              { principal: { type: "user", userId: e.user.id }, displayName: e.user.displayName || e.user.uid },
+              locale(),
+            ),
+            avatarHash: e.user.avatarHash,
             icon: "ti ti-user",
             description: e.user.mail ?? e.user.uid,
           });
         else if (e.kind === "group")
           entries.push({
             principal: { type: "group", groupId: e.group.id },
-            label: groupDisplayName(e.group.name, locale()),
+            label: principalLabel({ principal: { type: "group", groupId: e.group.id }, displayName: e.group.name }, locale()),
             icon: "ti ti-users-group",
             description: e.group.description ?? undefined,
           });
@@ -80,7 +103,14 @@ export default function PrincipalPicker(props: {
           const kind = serviceAccountKindDisplay(account.kind, t());
           entries.push({
             principal: { type: "service_account", serviceAccountId: account.id },
-            label: account.name,
+            label: principalLabel(
+              {
+                principal: { type: "service_account", serviceAccountId: account.id },
+                displayName: account.name,
+                serviceAccountKind: account.kind,
+              },
+              locale(),
+            ),
             // Resource-bound accounts often share a name; their binding tells them apart.
             description:
               account.kind === "resource_bound"
@@ -114,7 +144,12 @@ export default function PrincipalPicker(props: {
       fetchData={load}
       onSelect={(option) => {
         const entry = selectable.get(option.id);
-        if (entry) props.onSelect(entry.principal, { displayName: entry.label, serviceAccountKind: entry.serviceAccountKind });
+        if (entry)
+          props.onSelect(entry.principal, {
+            displayName: entry.label,
+            avatarHash: entry.avatarHash,
+            serviceAccountKind: entry.serviceAccountKind,
+          });
       }}
     />
   );