@stigmer/server 3.26.0 → 3.27.1

package/src/domain/iampolicy/__tests__/access-lists.test.ts

@@ -7,15 +7,19 @@
  * resolver answers and rendered as kind/id with the id as its name
  * everywhere else (the Java PrincipalEnricher fallback). Moved from the
  * cloud's iam/policy/access-lists.ts; the arms below are the Java
- * contract read from that file.
+ * contract read from that file. A grantee that is not a person (a team)
+ * is named by the composed principal display, one call per kind, keyed by
+ * kind and id so one kind's view never names another kind's id.
  */
 import { create } from "@bufbuild/protobuf";
 import { describe, expect, it } from "vitest";
 
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { IamPolicySchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
 import { ApiResourceRefViewSchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/io_pb";
 import type { IamPolicySpec } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
 
+import type { PrincipalDisplay } from "../../../extensions/principal-display.js";
 import { buildPrincipalAccessList, resolveHierarchy } from "../access-lists.js";
 import type { PrincipalDisplayResolver } from "../access-lists.js";
 import { policyIdFor } from "../constants.js";
@@ -139,7 +143,7 @@ describe("buildPrincipalAccessList", () => {
       ),
     );
     expect(
-      await buildPrincipalAccessList(store, nobody, [
+      await buildPrincipalAccessList(store, nobody, undefined, [
         { kind: "agent", id: "a1" },
       ]),
     ).toEqual([]);
@@ -150,7 +154,7 @@ describe("buildPrincipalAccessList", () => {
     await store.save(row(orgRole("ida_bob", "member", "acme")));
     await store.save(row(orgRole("ida_alice", "owner", "acme")));
     await store.save(row(orgRole("ida_bob", "viewer", "acme")));
-    const entries = await buildPrincipalAccessList(store, nobody, [
+    const entries = await buildPrincipalAccessList(store, nobody, undefined, [
       { kind: "organization", id: "acme" },
     ]);
     expect(entries.map((e) => e.principal?.id)).toEqual([
@@ -167,7 +171,7 @@ describe("buildPrincipalAccessList", () => {
   it("marks grants from a parent level as inherited and names the owning level", async () => {
     const store = fakeIamPolicyStore();
     await store.save(row(orgRole("ida_alice", "admin", "acme")));
-    const entries = await buildPrincipalAccessList(store, nobody, [
+    const entries = await buildPrincipalAccessList(store, nobody, undefined, [
       { kind: "agent", id: "a1" },
       { kind: "organization", id: "acme" },
     ]);
@@ -190,7 +194,7 @@ describe("buildPrincipalAccessList", () => {
         }),
       ),
     );
-    const entries = await buildPrincipalAccessList(store, nobody, [
+    const entries = await buildPrincipalAccessList(store, nobody, undefined, [
       { kind: "organization", id: "acme" },
     ]);
     expect(
@@ -228,11 +232,121 @@ describe("buildPrincipalAccessList", () => {
         );
       },
     };
-    const entries = await buildPrincipalAccessList(store, resolver, [
+    const entries = await buildPrincipalAccessList(store, resolver, undefined, [
       { kind: "organization", id: "acme" },
     ]);
     expect(asked).toEqual([["ida_alice", "ida_bob"]]);
     expect(entries.map((e) => e.principal?.name)).toEqual(["Alice", "ida_bob"]);
     expect(entries[0]?.principal?.email).toBe("alice@example.com");
   });
+
+  it("names a team grantee through the composed principal display, once per kind, and never lends one kind's view to another kind's id", async () => {
+    const store = fakeIamPolicyStore();
+    // A person and a team that share an id string: the views must not cross.
+    await store.save(row(orgRole("shared_1", "viewer", "acme")));
+    await store.save(
+      row(
+        triple({ kind: "team", id: "shared_1", relation: "member" }, "viewer", {
+          kind: "organization",
+          id: "acme",
+        }),
+      ),
+    );
+    await store.save(
+      row(
+        triple({ kind: "team", id: "tm_gone", relation: "member" }, "viewer", {
+          kind: "organization",
+          id: "acme",
+        }),
+      ),
+    );
+    const asked: Array<[ApiResourceKind, string[]]> = [];
+    const teams: PrincipalDisplay = {
+      resolve: (kind, ids) => {
+        asked.push([kind, [...ids]]);
+        return Promise.resolve(
+          new Map([
+            [
+              "shared_1",
+              create(ApiResourceRefViewSchema, {
+                kind: "team",
+                id: "shared_1",
+                name: "Site Reliability",
+              }),
+            ],
+          ]),
+        );
+      },
+    };
+    const entries = await buildPrincipalAccessList(store, nobody, teams, [
+      { kind: "organization", id: "acme" },
+    ]);
+    expect(asked).toEqual([[ApiResourceKind.team, ["shared_1", "tm_gone"]]]);
+    expect(entries.map((e) => [e.principal?.kind, e.principal?.name])).toEqual([
+      ["identity_account", "shared_1"],
+      ["team", "Site Reliability"],
+      // A team the display does not know (deleted since) keeps the fallback.
+      ["team", "tm_gone"],
+    ]);
+  });
+
+  it("names every grantee with the relation qualifier its rows hold, and never merges two qualifiers of one grantee", async () => {
+    const store = fakeIamPolicyStore();
+    const agent = { kind: "agent", id: "agt_1" };
+    await store.save(
+      row(
+        triple({ kind: "identity_account", id: "ida_alice" }, "viewer", agent),
+      ),
+    );
+    await store.save(
+      row(
+        triple(
+          { kind: "team", id: "tm_sre", relation: "member" },
+          "viewer",
+          agent,
+        ),
+      ),
+    );
+    // Not a shape the grant step admits today; the grouping must still
+    // keep a second qualifier apart so its revoke names the right row.
+    await store.save(
+      row(
+        triple(
+          { kind: "team", id: "tm_sre", relation: "maintainer" },
+          "viewer",
+          agent,
+        ),
+      ),
+    );
+    const teams: PrincipalDisplay = {
+      resolve: () =>
+        Promise.resolve(
+          new Map([
+            [
+              "tm_sre",
+              create(ApiResourceRefViewSchema, {
+                kind: "team",
+                id: "tm_sre",
+                name: "SRE",
+              }),
+            ],
+          ]),
+        ),
+    };
+    const entries = await buildPrincipalAccessList(store, nobody, teams, [
+      agent,
+    ]);
+    expect(
+      entries.map((e) => [
+        e.principal?.kind,
+        e.principal?.id,
+        e.principal?.relation,
+        e.principal?.name,
+      ]),
+    ).toEqual([
+      ["identity_account", "ida_alice", "", "ida_alice"],
+      ["team", "tm_sre", "member", "SRE"],
+      ["team", "tm_sre", "maintainer", "SRE"],
+    ]);
+  });
 });

package/src/domain/iampolicy/__tests__/constants.test.ts

@@ -15,7 +15,10 @@
  *     and never appear here;
  *   - the byte-pinned copy moved from the cloud's handlers as-is, plus the
  *     new sentences (the two edition refusals, the unknown permission, the
- *     unknown principal kind, the malformed triple);
+ *     unknown principal kind, the malformed triple, the four principal
+ *     refusals a team grantee brought);
+ *   - `USER_GRANT_PRINCIPAL_KINDS` — a person and a team, and no kind the
+ *     hierarchy walk would read as a structural parent;
  *   - the canonical text's one weakness and its closure (slice 2 ruling
  *     Q-S2-1): `ApiResourceRef` fields carry no character pattern, so an
  *     id or relation holding `:`, `#` or `@` could spell another triple's
@@ -44,10 +47,14 @@ import {
   malformedTripleField,
   malformedTripleMessage,
   noGrantableRolesMessage,
+  personQualifierMessage,
   policyIdFor,
   policyNotFoundMessage,
   principalNotGrantableMessage,
   roleNotGrantableMessage,
+  teamNotGrantableMessage,
+  teamQualifierMessage,
+  teamRoleNotGrantableMessage,
   unknownPermissionMessage,
   unknownPrincipalKindMessage,
   unknownResourceKindMessage,
@@ -310,11 +317,11 @@ describe("BLUEPRINT_KINDS — the legacy-creator rule's scan (Q-OR-6b)", () => {
 });
 
 describe("USER_GRANT_PRINCIPAL_KINDS — who a person may grant a role to (Q-S9-2)", () => {
-  it("is exactly the identity account: a role names a person; `team` is not an ApiResourceKind, so no wire spec can name it", () => {
+  it("is exactly a person and a team of people — the one vocabulary the writer admits and the reader treats as no structural parent", () => {
     expect([...USER_GRANT_PRINCIPAL_KINDS]).toEqual([
       ApiResourceKind.identity_account,
+      ApiResourceKind.team,
     ]);
-    expect(ApiResourceKind).not.toHaveProperty("team");
   });
 
   it("names no kind the hierarchy walk would read as a structural parent", () => {
@@ -370,7 +377,22 @@ describe("byte-pinned copy", () => {
 
   it("spells the principal refusal in the role sentence's shape, listing the grantable principal kinds", () => {
     expect(principalNotGrantableMessage("organization")).toBe(
-      "Principal kind 'organization' cannot be granted a role. Grantable principal kinds: [identity_account]",
+      "Principal kind 'organization' cannot be granted a role. Grantable principal kinds: [identity_account, team]",
+    );
+  });
+
+  it("spells the four team-era principal refusals, each naming what to fix", () => {
+    expect(personQualifierMessage("member")).toBe(
+      "Principal kind 'identity_account' takes no relation; got 'member'",
+    );
+    expect(teamQualifierMessage("admin")).toBe(
+      "A team principal must name the relation 'member' (the team's members); got 'admin'",
+    );
+    expect(teamNotGrantableMessage("session")).toBe(
+      "A team cannot be granted access to resource kind 'session'.",
+    );
+    expect(teamRoleNotGrantableMessage("owner", "agent", ["viewer"])).toBe(
+      "Role 'owner' cannot be granted to a team on resource kind 'agent'. Roles a team can hold: [viewer]",
     );
   });
 

package/src/domain/iampolicy/__tests__/controller.test.ts

@@ -23,9 +23,12 @@
  *     annotation-driven check; the wire-kind refusals on every lane;
  *   - get loads before it authorizes (NOT_FOUND with no Authorizer call;
  *     the row's kind and id as the target); delete authorizes before it
- *     loads; create validates the role before it writes.
+ *     loads; create validates the role before it writes, then runs the
+ *     `iam-policy-create:pre-side-effect-gate` slot, whose refusal leaves
+ *     no row; bootstrapPolicy never runs that slot.
  */
 import { create } from "@bufbuild/protobuf";
+import type { DescMessage } from "@bufbuild/protobuf";
 import {
   Code,
   ConnectError,
@@ -59,6 +62,7 @@ import type {
 import type { CallerIdentity } from "../../../extensions/identity.js";
 import type { PolicyGrantScope } from "../../../extensions/policy-grant-scope.js";
 import { createApiResourceInterceptor } from "../../../pipeline/interceptors/apiresource.js";
+import type { PipelineStep } from "../../../pipeline/pipeline.js";
 import {
   callerIdentityKey,
   trustedLocalIdentityFor,
@@ -186,6 +190,7 @@ async function harness(options: {
   engine?: boolean;
   edition?: ServerEdition;
   scope?: PolicyGrantScope;
+  createGate?: PipelineStep<DescMessage>;
 }): Promise<Harness> {
   const policies = fakeIamPolicyStore();
   const accounts = fakeIdentityAccountStore();
@@ -226,6 +231,17 @@ async function harness(options: {
         authorizer,
         grantScope: options.scope ?? newOrganizationOnlyGrantScope(),
         queries: engine,
+        principalDisplay: undefined,
+        gateSteps: new Map(
+          options.createGate === undefined
+            ? []
+            : [
+                [
+                  "iam-policy-create:pre-side-effect-gate",
+                  [options.createGate],
+                ],
+              ],
+        ),
         edition: options.edition ?? ServerEdition.oss,
         logger: silent,
       });
@@ -877,6 +893,44 @@ describe("the write lanes' order", () => {
       roleNotGrantableMessage("admin", "organization", ["viewer"]),
     );
   });
+
+  it("create runs the iam-policy-create gate slot after the role check and before the write; a refusing gate leaves no row", async () => {
+    const seen: string[] = [];
+    const refusingGate: PipelineStep<DescMessage> = {
+      name: "RefuseForTest",
+      execute() {
+        seen.push("gate");
+        throw new ConnectError("refused by the gate", Code.FailedPrecondition);
+      },
+    };
+    const h = await harness({ caller: alice, createGate: refusingGate });
+    // A role the step refuses never reaches the gate.
+    await refusal(() => h.command.create(orgRole(ALICE_ID, "editor", "acme")));
+    expect(seen).toEqual([]);
+    const error = await refusal(() =>
+      h.command.create(orgRole(ALICE_ID, "member", "acme")),
+    );
+    expect(error.code).toBe(Code.FailedPrecondition);
+    expect(error.rawMessage).toBe("refused by the gate");
+    expect(seen).toEqual(["gate"]);
+    expect(h.policies.rows.size).toBe(0);
+  });
+
+  it("bootstrapPolicy, the platform's structural lane, never runs the create gate slot", async () => {
+    const seen: string[] = [];
+    const h = await harness({
+      caller: internal,
+      createGate: {
+        name: "RecordForTest",
+        execute() {
+          seen.push("gate");
+        },
+      },
+    });
+    await h.command.bootstrapPolicy(orgRole(ALICE_ID, "member", "acme"));
+    expect(seen).toEqual([]);
+    expect(h.policies.rows.size).toBe(1);
+  });
 });
 
 describe("a wire kind string is refused BEFORE position 1 on every annotated lane (Q-S6-1)", () => {

package/src/domain/iampolicy/__tests__/grant-path.test.ts

@@ -272,7 +272,7 @@ describe("the one writer is the one gate: nothing is read, written or notified f
     "admin",
     { kind: "organisation", id: "acme" },
   );
-  const unknownPrincipal = triple({ kind: "team", id: "tm_1" }, "viewer", {
+  const unknownPrincipal = triple({ kind: "group", id: "grp_1" }, "viewer", {
     kind: "agent",
     id: AGENT,
   });
@@ -280,7 +280,7 @@ describe("the one writer is the one gate: nothing is read, written or notified f
     kind: "organization",
     id: "acme#admin",
   });
-  const bothUnknown = triple({ kind: "team", id: "tm_1" }, "admin", {
+  const bothUnknown = triple({ kind: "group", id: "grp_1" }, "admin", {
     kind: "organisation",
     id: "acme",
   });
@@ -290,7 +290,7 @@ describe("the one writer is the one gate: nothing is read, written or notified f
     const { policies, path } = pathOver(recorded, recordingLifecycle(recorded));
     const refusals: ReadonlyArray<[IamPolicySpec, string]> = [
       [unknownResource, unknownResourceKindMessage("organisation")],
-      [unknownPrincipal, unknownPrincipalKindMessage("team")],
+      [unknownPrincipal, unknownPrincipalKindMessage("group")],
       [malformed, malformedTripleMessage("resource.id")],
       [bothUnknown, unknownResourceKindMessage("organisation")],
     ];

package/src/domain/iampolicy/__tests__/steps.test.ts

@@ -8,7 +8,10 @@
  * SCOPE lists none → UNIMPLEMENTED naming the editions that serve
  * per-resource grants; the role is not in proto ∩ scope → the cloud's
  * second copy listing the intersection in proto order. The intersection
- * is what keeps a scope from widening the contract by accident.
+ * is what keeps a scope from widening the contract by accident. A person
+ * names no relation qualifier; a team is granted only its kind's team
+ * roles (never ownership, never on a kind that lists none), always as its
+ * members, and nothing at all under open source's organization-only scope.
  *
  * Grant and Revoke are proven for the one thing a step adds over the
  * grant path: the result they leave under POLICY_RESULT_KEY (the revoke
@@ -30,9 +33,13 @@ import { RequestContext } from "../../../pipeline/request-context.js";
 import {
   PER_RESOURCE_GRANTS_UNIMPLEMENTED_MESSAGE,
   noGrantableRolesMessage,
+  personQualifierMessage,
   policyIdFor,
   principalNotGrantableMessage,
   roleNotGrantableMessage,
+  teamNotGrantableMessage,
+  teamQualifierMessage,
+  teamRoleNotGrantableMessage,
   unknownResourceKindMessage,
 } from "../constants.js";
 import { newIamPolicyGrantPath } from "../grant-path.js";
@@ -190,6 +197,121 @@ describe("ValidateGrantableRole", () => {
     );
   });
 
+  it("a person names no relation qualifier: identity_account:<id>#<anything> names nobody and would be a tuple OpenFGA refuses", async () => {
+    const error = await refusal(() =>
+      organizationOnly.execute(
+        contextOf(
+          triple(
+            { kind: "identity_account", id: "ida_bob", relation: "member" },
+            "viewer",
+            { kind: "organization", id: "acme" },
+          ),
+        ),
+      ),
+    );
+    expect(error.code).toBe(Code.InvalidArgument);
+    expect(error.rawMessage).toBe(personQualifierMessage("member"));
+  });
+
+  describe("a team principal", () => {
+    const team = { kind: "team", id: "tm_sre", relation: "member" };
+    const perResource = newValidateGrantableRoleStep(
+      scopeOf(
+        new Map([
+          [ApiResourceKind.agent, [IamRole.owner, IamRole.viewer]],
+          [
+            ApiResourceKind.agent_channel,
+            [IamRole.owner, IamRole.viewer, IamRole.participant],
+          ],
+          [ApiResourceKind.session, [IamRole.owner, IamRole.viewer]],
+          [
+            ApiResourceKind.organization,
+            [IamRole.owner, IamRole.admin, IamRole.member, IamRole.viewer],
+          ],
+        ]),
+      ),
+    );
+
+    it("is granted a role its kind's team_grantable_roles lists, as the team's members", () => {
+      expect(
+        perResource.execute(
+          contextOf(triple(team, "viewer", { kind: "agent", id: "agt_1" })),
+        ),
+      ).toBeUndefined();
+      expect(
+        perResource.execute(
+          contextOf(
+            triple(team, "participant", {
+              kind: "agent_channel",
+              id: "ach_1",
+            }),
+          ),
+        ),
+      ).toBeUndefined();
+    });
+
+    it("is never granted ownership, though a person could be: a team holds only its kind's team roles", async () => {
+      const error = await refusal(() =>
+        perResource.execute(
+          contextOf(triple(team, "owner", { kind: "agent", id: "agt_1" })),
+        ),
+      );
+      expect(error.code).toBe(Code.InvalidArgument);
+      expect(error.rawMessage).toBe(
+        teamRoleNotGrantableMessage("owner", "agent", ["viewer"]),
+      );
+    });
+
+    it("is refused on a kind that lists no team role — a session stays personal, an organization role is no team's", async () => {
+      for (const [kind, id, role] of [
+        ["session", "ses_1", "viewer"],
+        ["organization", "acme", "member"],
+      ] as const) {
+        const error = await refusal(() =>
+          perResource.execute(contextOf(triple(team, role, { kind, id }))),
+        );
+        expect(error.code, kind).toBe(Code.InvalidArgument);
+        expect(error.rawMessage, kind).toBe(teamNotGrantableMessage(kind));
+      }
+    });
+
+    it("must name the team's members as its relation", async () => {
+      for (const relation of ["", "admin"]) {
+        const error = await refusal(() =>
+          perResource.execute(
+            contextOf(
+              triple({ ...team, relation }, "viewer", {
+                kind: "agent",
+                id: "agt_1",
+              }),
+            ),
+          ),
+        );
+        expect(error.code, relation).toBe(Code.InvalidArgument);
+        expect(error.rawMessage, relation).toBe(teamQualifierMessage(relation));
+      }
+    });
+
+    it("is granted nothing under open source's organization-only scope: per-resource grants are UNIMPLEMENTED, and the organization lists no team role", async () => {
+      const onAgent = await refusal(() =>
+        organizationOnly.execute(
+          contextOf(triple(team, "viewer", { kind: "agent", id: "agt_1" })),
+        ),
+      );
+      expect(onAgent.code).toBe(Code.Unimplemented);
+      const onOrganization = await refusal(() =>
+        organizationOnly.execute(
+          contextOf(
+            triple(team, "member", { kind: "organization", id: "acme" }),
+          ),
+        ),
+      );
+      expect(onOrganization.rawMessage).toBe(
+        teamNotGrantableMessage("organization"),
+      );
+    });
+  });
+
   it("a scope can only NARROW the proto: a role it adds is clipped from the list", async () => {
     const widening = newValidateGrantableRoleStep(
       scopeOf(

package/src/domain/iampolicy/access-lists.ts

@@ -17,12 +17,20 @@
  *
  * Display enrichment is a seam (`PrincipalDisplayResolver`) because the
  * data lives in the identity-account domain; display-resolver.ts fills it
- * over that domain's PORT. A principal the resolver does not answer for —
- * any kind that is not an identity account, or an account whose row is
- * gone — renders as kind/id with the id standing in as the display name,
- * the Java `enrich()` fallback shape.
+ * over that domain's PORT. A grantee of any other kind (a team) is named by
+ * the edition's `drivers.principalDisplay` when one is composed
+ * (extensions/principal-display.ts). A principal nobody answers for — no
+ * driver, or an account or team whose row is gone — renders as kind/id
+ * with the id standing in as the display name, the Java `enrich()`
+ * fallback shape.
+ *
+ * Every entry names its grantee exactly as the rows hold it: kind, id AND
+ * the relation qualifier (`team:<id>#member`), and entries group by all
+ * three. A revoke matches the qualifier exactly (grant-path.ts
+ * `findByTriple`), so a list that dropped it would hand the console a
+ * grantee whose revoke finds no row and succeeds having deleted nothing.
  */
-import { create } from "@bufbuild/protobuf";
+import { clone, create } from "@bufbuild/protobuf";
 
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import type { IamPolicy } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
@@ -38,7 +46,11 @@ import {
 } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/io_pb";
 import { ApiResourceRefSchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
 
-import { kindEnumName } from "../../pipeline/apiresource-meta.js";
+import type { PrincipalDisplay } from "../../extensions/principal-display.js";
+import {
+  kindByEnumName,
+  kindEnumName,
+} from "../../pipeline/apiresource-meta.js";
 import { assignableRelations, roleInfoFromRelation } from "./roles.js";
 import type { IamPolicyStore } from "./store.js";
 
@@ -100,12 +112,14 @@ export interface PrincipalDisplayResolver {
 
 /**
  * Groups assignable-role policies by principal in first-seen order (the
- * Java LinkedHashMap contract), enriched where the resolver answers and
- * the Java fallback shape (name = id) everywhere else.
+ * Java LinkedHashMap contract), enriched where the resolver (people) or
+ * the composed principal display (every other kind) answers, and the Java
+ * fallback shape (name = id) everywhere else.
  */
 export async function buildPrincipalAccessList(
   policies: IamPolicyStore,
   displayResolver: PrincipalDisplayResolver,
+  principalDisplay: PrincipalDisplay | undefined,
   hierarchy: ReadonlyArray<HierarchyLevel>,
 ): Promise<ReadonlyArray<PrincipalAccess>> {
   interface GrantAtLevel {
@@ -128,11 +142,11 @@ export async function buildPrincipalAccessList(
     return [];
   }
 
-  const accountKind = kindEnumName(ApiResourceKind.identity_account);
-  const accountIds = grants
-    .filter((g) => g.policy.spec?.principal?.kind === accountKind)
-    .map((g) => g.policy.spec?.principal?.id ?? "");
-  const enriched = await displayResolver.resolveIdentityAccounts(accountIds);
+  const enriched = await resolvePrincipalViews(
+    grants.map((g) => g.policy),
+    displayResolver,
+    principalDisplay,
+  );
 
   const grouped = new Map<
     string,
@@ -143,19 +157,24 @@ export async function buildPrincipalAccessList(
     if (principal === undefined) {
       continue;
     }
-    const key = `${principal.kind}:${principal.id}`;
+    const key = `${principal.kind}:${principal.id}#${principal.relation}`;
     let entry = grouped.get(key);
     if (entry === undefined) {
+      const view = enriched.get(`${principal.kind}:${principal.id}`);
       entry = {
-        // The Java enrich() fallback shape for unresolved principals of
-        // ANY kind: kind/id with the id standing in as the display name.
-        principal:
-          enriched.get(principal.id) ??
-          create(ApiResourceRefViewSchema, {
-            kind: principal.kind,
-            id: principal.id,
-            name: principal.id,
-          }),
+        // A resolved view is shared by every qualifier of one grantee, so
+        // each entry stamps its own copy. The Java enrich() fallback shape
+        // for unresolved principals of ANY kind: kind/id with the id
+        // standing in as the display name.
+        principal: withRelation(
+          view ??
+            create(ApiResourceRefViewSchema, {
+              kind: principal.kind,
+              id: principal.id,
+              name: principal.id,
+            }),
+          principal.relation,
+        ),
         roles: [],
       };
       grouped.set(key, entry);
@@ -171,6 +190,62 @@ export async function buildPrincipalAccessList(
   );
 }
 
+/**
+ * The display views of every distinct principal the rows name, keyed
+ * `kind:id` (the grouping key, so two kinds can never share an id's view):
+ * people through the identity-account resolver, every other kind the
+ * edition's principal display knows through it, one call per kind. A kind
+ * string that names no kind (a legacy row) and every kind with no display
+ * are simply absent, so the caller's fallback shape names them.
+ */
+async function resolvePrincipalViews(
+  rows: ReadonlyArray<IamPolicy>,
+  displayResolver: PrincipalDisplayResolver,
+  principalDisplay: PrincipalDisplay | undefined,
+): Promise<ReadonlyMap<string, ApiResourceRefView>> {
+  const accountKind = kindEnumName(ApiResourceKind.identity_account);
+  const idsByKind = new Map<string, Set<string>>();
+  for (const row of rows) {
+    const principal = row.spec?.principal;
+    if (principal === undefined) {
+      continue;
+    }
+    const ids = idsByKind.get(principal.kind) ?? new Set<string>();
+    ids.add(principal.id);
+    idsByKind.set(principal.kind, ids);
+  }
+
+  const views = new Map<string, ApiResourceRefView>();
+  for (const [kindName, ids] of idsByKind) {
+    let resolved: ReadonlyMap<string, ApiResourceRefView>;
+    if (kindName === accountKind) {
+      resolved = await displayResolver.resolveIdentityAccounts([...ids]);
+    } else {
+      const kind = kindByEnumName(kindName);
+      if (
+        principalDisplay === undefined ||
+        kind === ApiResourceKind.api_resource_kind_unknown
+      ) {
+        continue;
+      }
+      resolved = await principalDisplay.resolve(kind, [...ids]);
+    }
+    for (const [id, view] of resolved) {
+      views.set(`${kindName}:${id}`, view);
+    }
+  }
+  return views;
+}
+
+function withRelation(
+  view: ApiResourceRefView,
+  relation: string,
+): ApiResourceRefView {
+  const stamped = clone(ApiResourceRefViewSchema, view);
+  stamped.relation = relation;
+  return stamped;
+}
+
 function buildGrant(
   policy: IamPolicy,
   isInherited: boolean,