platform/docs/roles-and-teams.md

# Roles and teams

**Status: plan, not built.** Phase 0 landed 2026-08-23 (`roles` is a table). Everything below phase 0 is
design, written down so the work starts from a spec rather than from a conversation.

## What this is

Officer began as one person's server and its authorization model says so: four role names in a TypeScript
union, one owner identified by holding one of them, and grants keyed on a role string. That is correct for
a homelab and it cannot express a company, where the same person is an administrator of one area and an
ordinary member of another.

Two things are wanted, and they are separable:

- **Roles as data**, so a role can be added without a deploy, and so each can eventually carry its own
  provisioning.
- **Teams**, so a user belongs to several and holds a different role in each.

**Teams are optional and must stay optional.** A homelab with family and friends on it may never make one;
its owner's answer is "team family, team friends" or no teams at all, and either has to work. A company
uses both. Nothing below may make teams mandatory to reach a feature.

---

## What already landed — phase 0, 2026-08-23

The `roles` table exists, seeded with `Super Admin`, `Admin`, `Developer`, `Member`, each flagged
`isSystem` because the platform's own code names it. `provisioningScript` is declared and null.

**Nothing reads it yet.** `USER_ROLES` is still the type, `users.role` is still plain text with no foreign
key, and `authorize.ts` is untouched. That was deliberate: the change is additive, so it cannot fail on
existing data, which is what made it safe to hand to an unattended rollout across five hosts.

**No foreign key, and this is the reason.** `db:push` creates a table and adds a constraint in the same
run, so a foreign key from `users.role` onto an empty `roles` is violated by every existing account.
Verified against a scratch database: push reported the violation, created the table, skipped the
constraint, **and exited 0**. See `prompts/deploy-commander.md` → "Schema changes".

---

## Decisions

### D1. The owner is an identity. It is never a role.

`OWNER_USER_ID` — user 1, the account whose home is the home of the OS user the platform runs as.

Before phase 0, `isSuperAdmin()` answered `user.role === 'Super Admin'`. That was correct while roles were
a hardcoded union and nothing could write a new one. **The moment roles are editable data it becomes a
privilege-escalation path**: "add a role" and "become the owner" are the same feature, reachable from
whatever UI manages roles.

So ownership moves to `user.id === OWNER_USER_ID`, and `getOwnerUser()` becomes a primary-key lookup rather
than "the lowest id holding Super Admin". **This is the load-bearing change in phase 1** and everything
else can wait behind it.

### D2. Several Super Admins are allowed, and the role provisions sudo

Today `create-user.ts` and `updateUserRoleHandler` refuse to create a second Super Admin. That limit goes:
a company has an owner and several administrators, and a homelab owner may add one or never do.

**Holding `Super Admin` provisions an OS account with sudo.** Which means, plainly: that person is outside
Officer's permission system. `role_permissions`, the `confined` kernel containment and the
"`execution` is never grantable" rule bound nobody who can `sudo cat` any home on the box. And the grant is
irreversible in practice — revoking the role does not revoke an SSH key, a cron entry or a setuid binary
they left behind.

That is the operator's decision to make, not the platform's to prevent. What the platform owes them is for
the UI to say what it is rather than presenting it as one more row in a dropdown.

### D3. `Admin` is app-wide authority with no operating-system privilege

The role most companies actually staff: creates accounts, manages grants, sees every dashboard, and cannot
read the CEO's files. It already exists and `rolePermitsDevTools()` already excludes it deliberately —
"administering the platform is not developing on it". This decision only writes that down.

### D4. A role may be deleted, but not while anyone holds it

Refuse the delete; never reassign. Silently moving accounts to a fallback role is a permission change
nobody asked for, and "absence denies" is the posture everywhere else in this system.

`isSystem` roles refuse both delete and rename, because the code names them by name:
`rolePermitsDevTools()` tests for `Developer`, `bootstrap.ts` writes `Super Admin`, `users.role` defaults to
`Member`. Renaming one is a code change that has not happened yet.

### D5. Grants stay keyed on the role NAME, with `ON UPDATE CASCADE`

`role_permissions.role` and `users.role` both hold a name. Re-keying them onto a serial id would touch
`authorize.ts` — the file standing between a Member and a shell — to buy what Postgres gives for free: a
rename cascades to every user and every grant, atomically, with no code change.

The cost is that a rename is a data migration rather than a label edit, which is honest — a role name
appears in `rolePermitsDevTools`, in report text, and in whatever a plugin has written down.

### D6. A team is a scope. Permissions UNION across a user's teams.

Admin in marketing and member in developers means marketing's admin level does not reach developers'
files — but a user's effective permission for a given capability is the **highest level any of their teams
grants**, plus their global role.

Union is the only coherent resolution, and it has a consequence worth stating: **adding somebody to a team
can only ever grant, never restrict.** A team cannot be used to limit someone. If restriction is ever
wanted, that is a different and much harder system (deny rules, precedence, conflict resolution) and it
should be refused rather than half-built.

### D7. The global role remains, and answers a different question

Two questions, two mechanisms:

- **"May this account administer the server at all?"** — the global role. Super Admin, Admin.
- **"What may this account do in this area?"** — team membership with a role in that team.

This is the shape GitHub, Slack and Workspace all converged on, and the reason is that the first question
has no natural team to ask it about. A homelab uses only the first and never makes a team.

### D8. Per-role provisioning is a script the role carries

`provisioningScript` on the role row. Run when an account is granted that role; the reference implementation
is `Developer`, which today gets a Postgres role of its own through `rolePermitsDevTools()` — a special case
in code that should become a row.

The historical note matters for whoever builds it: that gate was originally for **rootless** Docker, and
rootless specifically. `usermod -aG docker` is root by a longer route —
`docker run -v /:/host -it alpine chroot /host` reads `.env`, every member's home and the wallet seed. Any
provisioning script that adds a user to a privileged group is granting more than its role name suggests.

---

## Phases

### Phase 0 — roles are a table ✅ DONE 2026-08-23

Additive only. Nothing reads it.

### Phase 1 — the owner stops being a role ✅ DONE 2026-08-23

The load-bearing phase, and small.

1. `isOwner(user)` = `user.id === OWNER_USER_ID`. `getOwnerUser()` = lookup by that id.
2. Split the two meanings of today's `isSuperAdmin()`: ownership, and holding the role. **Every existing
   call site keeps meaning OWNER**, so no route changes who it admits. Widening any "owner-only" route to
   "owner or Super Admin" is a separate, reviewable change per route.
3. Drop the second-Super-Admin refusals in `create-user.ts` and `updateUserRoleHandler`.
4. ~~Remove the `users` CHECK that pins user 1 to `Super Admin`~~ — **KEPT, overruling this plan.** It is
   redundant for the question it was written for: `isOwner` is an id comparison and never reads that column.
   But it still forbids user 1 being set to `Member` while remaining the owner, which is a state with no
   benefit and a confusing display. A constraint that costs nothing and forbids a nonsense state is worth
   keeping after its original reason has gone.

**One asymmetry introduced deliberately.** An existing account can now be promoted to `Super Admin`;
creating one directly as `Super Admin` is still refused by `create-user.ts`. Promotion happens to an account
somebody has looked at, from a screen showing who they are. Creation is a form filled in once, and the role
that provisions sudo should not be a dropdown default reached by accident. Create, then promote.

Reviewable on its own, and nothing downstream can start until ownership is an identity.

### Phase 2 — the foreign key, and role CRUD

1. **Two releases, not one.** The rows are on every host after phase 0; the constraint ships separately,
   and its release plan carries the SQL explicitly per `prompts/deploy-commander.md`.
2. `users.role` and `role_permissions.role` become foreign keys with `ON UPDATE CASCADE` (D5).
3. Role CRUD: list with holder counts, create, rename, delete guarded by D4.
4. `USER_ROLES` stops being the source of truth. `UserRole` becomes `string`, and the picker reads the
   table. **This is where the typed-union safety is lost** — worth a runtime validator at the write path to
   replace what the compiler was doing.

### Phase 3 — per-role provisioning

`provisioningScript` gets a runner, and `rolePermitsDevTools()` becomes a row rather than a branch. Needs
D8's warning in front of whoever writes the first script.

### Phase 4 — teams

1. `teams`, and `team_members(team_id, user_id, role)` — the role scoped to the team.
2. `team_permissions(team_id, role, permission, level)`, or a discriminator on `role_permissions`. Decide by
   asking whether a team's roles are the same set as the global ones; probably yes, and probably that means
   one table with a nullable `team_id`.
3. `authorize.ts` resolves the union (D6): global role grants, plus the highest level any team grants.
   **This is the one change in the whole plan that alters the resolver**, so it wants tests before it wants
   code — `permissions/authorize.test.ts` is already pure and mockless, which is what makes that possible.
4. Teams UI, and the account screen showing which teams a user is in and as what.

### Phase 5 — account creation — **DONE, and it was done before this phase was written**

`POST /api/users` is owner-gated and live, with a form under Settings → User Management: same password
validator as bootstrap, a role checked against the `roles` table, `Super Admin` refused outright, an
optional inbound SSH key, and Linux provisioning with `POST /users/:id/provision-linux` to retry it.
Alongside it: role change, password reset, delete.

It shipped in `69a31051`. This section spent days telling readers it did not exist and sequencing work
around building it — and on 2026-08-23 it produced a concrete cost, when a recommendation to "do phase 5
first" was made from this text and withdrawn only because someone opened `api/users/` to write the spec.

The general lesson, since it is the second time this exact shape has bitten: `bun run docs:check` compares
numbers, so counts stay honest while prose rots quietly. **A phase marked as not built is worth verifying
against the tree before it is planned around**, not because the plan was careless but because a plan is
written once and the code moves every day.

---

## What must not be built

- **Deny rules.** See D6. Teams grant; they never restrict.
- **A role that confers ownership.** See D1. There is exactly one owner and no role reaches it.
- **Team-scoped `execution` capabilities.** Tasks, items, desktop and browser run as the owner's OS user in
  the owner's home. A team cannot make that safe, and "team developers gets terminal" has to stay a no —
  the answer is a `confined` grant with a Linux user, which is per-account by nature.

## Verification

- `bunx tsgo` clean. Note that on this machine `earlyoom` SIGTERMs the `bunx` wrapper around 15s; run the
  binary directly.
- `permissions/authorize.test.ts` is the primary guard, and it uses real registry keys deliberately so a
  rename goes red rather than passing vacuously. Phase 4 must extend it before changing the resolver.
- `bun run docs:check` — the permission count claim in `CLAUDE.md` moves whenever the registry does.
- Any schema phase: verify by query per host, never by `db:push`'s exit code.

## Teams — decided 2026-08-23

The four open questions were answered by the owner. Recorded here so phase 4 is implementation rather
than another round of design.

**A team owns a shared folder.** Not only an authorization grouping — storage is the part that was
actually wanted. Team *dashboards* are a probable later addition and were explicitly deferred, because
they need a permission shape nothing here has: people who can edit a dashboard's STRUCTURE versus people
who only see what it renders. Every grant today is read-or-write over a whole capability, so that is a new
model rather than a new level. Build the folder; leave room for the dashboards.

**Any Admin may create a team**, not the owner alone. Teams are self-service for people already trusted to
administer the platform. This is what makes the quota section below necessary rather than optional: an
Admin creating a team is an Admin allocating disk.

**A team may grant a capability the member's own role lacks** — the union, per D6 — with one rule on top:
**whoever creates the team can only attach capabilities they hold themselves.** Escalation is capped at the
creator's own reach rather than the whole registry. `execution` and `admin` stay ungrantable regardless,
and `confined` still resolves to nothing for an account with no Linux user.

**Deleting a role is refused while anyone holds it, in a team or globally.** The same rule D4 already
applies to global holders, extended rather than special-cased; the refusal should name the teams.

### Two things phase 4 must not get wrong

**The shared folder is enforced by the kernel, not by the grant.** Every role already holds `files` at
`write` — they are the seeded `confined` defaults — so the capability is not what keeps one team out of
another's folder. A Linux group per team is. The grant says whether someone can use the files surface at
all; group membership says which folders they reach. Both are required and they are not substitutes.

**The grant cache is keyed on ROLE today**, deliberately: "at most one entry per role, and a new account
needs no warm-up" (`permissions/authorize.ts`). Teams end that — effective permissions become role plus
memberships, which is per-user. That property is easy to lose without noticing and awkward to recover, so
it should be a decision in the implementation rather than a side effect.

## Quotas — the model, and the prerequisite nobody can skip

The owner declares platform-level defaults and maxima: per user, and per team. Admins allocate inside
them. A change re-applies at the Linux level through `POST /users/:id/provision-linux`, which already
exists as a retry path and becomes "re-apply current policy to this account".

**Enforcement is the kernel's job, not the platform's.** Members hold `terminal` at `write` and have their
own Linux accounts, so a quota the platform tracks by counting bytes through the file browser is
decorative — a member opens a terminal or SSHes in and writes past it. Only filesystem quotas bind.

**Which means a filesystem that can carry them.** Checked on 2026-08-23: neither `officer-dev` nor `alpha`
can. Both are ext4 with homes on the root filesystem, no `usrquota`/`grpquota`/`prjquota` mount options,
and neither has the ext4 `quota` or `project` feature. Enabling `project` needs `tune2fs -O project` on an
UNMOUNTED filesystem, and `/` cannot be unmounted on a running server — so it is a rescue boot, not a
config change.

The cheap moment is when a host is built, by giving the Linux homes their own filesystem with quota
features from the start. Retrofitting a live host is expensive and gets more so with every account on it.

**Where this actually matters is `edge-pertento`** — the first real multi-user deployment, and the only
one that will have accounts that are not the owner's. `officer-dev` is a development machine and will not
be multi-user; alpha is the owner's own. Check edge-pertento's disk before it gains more accounts.

**On a host that cannot enforce, the platform says so** — "policy recorded, not enforceable here" — rather
than storing numbers that do nothing. A feature that silently does nothing is worse than one that admits
it cannot.

## Open questions

None outstanding for phase 4. The four that were here are answered above.
   holds globally; the same question exists per team and is not answered here.