feat: teams, users and impersonation

[TheMeinerLP]

Teams and people per tenant, who is in which team, invitations, password resets, and viewing the
platform as a tenant sees it. Subsystems C and D — the last three of the five things the goal
asked for.

Design: docs/superpowers/specs/2026-08-16-teams-and-users-design.md
Runbook: docs/runbooks/directory-and-impersonation-setup.md

Merge #62 first. This branch sits on top of it, so until #62 lands the diff below also shows
#62's commits; GitHub cleans that up by itself once it merges.

The base is main rather than feat/per-tenant-app-instance on purpose: build-pr.yml triggers
on pull_request: branches: [main], so a stacked base means no CI at all — a tidier diff is not
worth an unverified branch.

Two problems that look like one

Conflating them would have put a directory-wide credential in a browser.

Reading who somebody is is a token question. No Graph, no secret, no second registration.

Changing the directory needs Graph application permissions, which only a confidential client
can use.

The first one fixes a bug that has been open since SSO was set up

The tenant application has shown "No tenant (platform-level account)" for every user. The cause
is now confirmed rather than suspected: PrincipalResolver reads a claim named organization,
and the Apus app registration has groupMembershipClaims: null and optionalClaims: null. The
claim was not mis-mapped — Entra was never going to emit it.

Tenant.spec.identity.groupId ties a tenant to an Entra group, TenantGroupIndex maps a token's
groups claim back to a tenant, and an explicit organization claim still wins where a broker
emits one. Setting groupMembershipClaims is step 1 of the runbook and needs none of the
permissions below — it is worth doing even if the rest is declined.

Where the narrowing lives

Group.ReadWrite.All, User.ReadWrite.All and User.Invite.All are directory-wide. Entra has no
"these groups only" variant of any of them. The credential this API holds could rename any group
in the organisation and reset any account's password.

So DirectoryGuard is the only thing between a controller bug and the whole directory, and it is
closed by default — an instance that has not been told which groups are managed refuses
everything, which is also its state at startup and if the tenant index ever fails to load. It is
pure: no network call, because a guard that has to reach out to decide fails open exactly when
the network does.

It refuses a group no Tenant claims, a user outside one, a password reset aimed at a privileged
directory account, and a reset of the caller's own password. Its 13 tests are written from the
attacker's side — refusesResettingThePasswordOfAGlobalAdministrator, not resetWorks.

Impersonation only ever narrows

The effective principal never holds platform-admin and never holds a role its caller does not.
There is no combination of headers that lets anyone do something they could not already do as
themselves; the only thing that changes is which tenant they do it in. That is what makes the
feature's blast radius equal to its caller's, and why the policy strips the platform role rather
than checking for its absence.

Applied in one server filter rather than per controller, so a controller written later cannot
forget it — every one of them already resolves through PrincipalResolver, and the filter
replaces the request's authentication. A refused impersonation fails the request rather than
quietly serving the real principal: being answered as yourself while believing you are a tenant
is worse than an error.

The banner lives in the console layout, not on the page that starts the session. Once it is
running every page answers as somebody else, and a banner you stop seeing when you navigate is a
banner you stop seeing exactly when you have forgotten.

Not lying when the directory is down

Graph is somebody else's service and it will be throttling at some point. A tenant whose storage
and renders are fine must stay readable.

• reads report the panel unavailable with the reason, so nobody goes to read server logs for
  something the server already said
• a count is null, never 0 — a zero meaning "we could not ask" is a fact an administrator
  would act on
• a team of unknown size says "Unknown size"
• writes do not degrade: an invitation that silently did not happen is worse than an error
• a team's membership says "Loading" rather than "Nobody is in this team yet" while the answer is
  still out

Assignments, and one trap in them

Who is in which team is fetched per team, when somebody opens it — not up front, which would be a
request per team on every page load for a list most people only scan.

The endpoint checks the team belongs to this tenant rather than trusting the id in the path.
Without that the group guard would still pass, because the tenant's own group is managed, while
the id pointed at any group in the organisation — turning a members endpoint into a way to read
every group's membership. There is a test aimed at exactly that.

Verification

:api:test	passes — 13 guard cases (attacker's side), 20 controller cases, 9 impersonation cases, 2 filter-order cases, 7 index cases, 7 Graph-parsing cases, 6 resolver cases
:operator:test	passes
spotlessCheck	clean
pnpm lint / typecheck	clean
pnpm test	183 (143 core + 18 app + 22 console)
Charts	rendered both ways; the directory block is off by default and the secret comes from secretKeyRef, never inlined
CRD	regenerated; the diff is 5 lines and nothing else

What still needs a human

Everything in the runbook, and none of it is automatable from inside Apus — granting an
application permission is a directory administrator's decision, and Apus deliberately holds no
permission that would let it grant itself another. The runbook states what the permissions allow
in plain words before asking for them, so the trade can be declined with the facts in view.

🤖 Generated with Claude Code

https://claude.ai/code/session_019Bff5mpWkUnZA77jys8DiR

[github-actions]

Test results

672 tests   672 ✅  48s ⏱️
 93 suites    0 💤
 93 files      0 ❌

Results for commit 1cad447.

♻️ This comment has been updated with latest results.