ADR-0008: Access is three orthogonal axes, not one role ladder
ADR-0008: Access is three orthogonal axes, not one role ladder
Section titled “ADR-0008: Access is three orthogonal axes, not one role ladder”Status: Accepted · Date: 2026-10-18
Context
Section titled “Context”AccessService shipped one thing: a role ladder with a fixed z.enum of six
WordPress-shaped roles and a fixed vocabulary of content:* capabilities. It
answered “may this subject do this kind of thing?” and nothing else.
Three deployments immediately need more than that, and each reaches for it in a different direction:
- A self-serve dashboard. Signup, email verification, an admin listing users and editing them. The built-in ladder is exactly right, and any abstraction added for the cases below is cost paid by everyone.
- A closed organisation — a municipal intranet, an enterprise panel — where nobody signs themselves up. The identifier is a national identity document captured at hire, the initial password is generated by IT and handed over on paper, it is rotated every three months, and the account lifecycle is owned by a different department from the one that manages permissions.
- A document-sharing product. Someone is given access to one file and to nothing else. No global role ladder expresses that: the role is real, but its blast radius is a single resource.
Cases 2 and 3 pull in opposite directions — one wants an identity layer that is the provider’s job, the other wants a per-resource scope that is not a role at all. Folding either into the ladder corrupts the other.
Two failure modes showed up in the existing code before this decision:
ROLE_RANKwas aRecord<AccessRole, number>hardcoded next to the registry. A role registered throughuseRegisterRoleresolved toundefined, andundefined >= rankisfalse— so a custom role silently inherited nothing while still appearing inuseRoles(). Extending the registry was a lie.useRegisterRolevalidated nothing, so a definition missing a field poisoned every subsequent check without a warning.
Decision
Section titled “Decision”The three axes are separate, and the credential never reaches the role
Section titled “The three axes are separate, and the credential never reaches the role”Identity is who the person is in your system; credential is how they
proved it; authorization is what they may do. Principal carries the
credential result (subject, method, provider, claims) and holds no
roles. Identity is yours and outlives the provider account.
The rule that falls out: an OAuth sign-in never grants elevation. Signing in with Google proves “I control this account” — a real, strong claim — and says nothing about employment. A deployment that lets anyone self-register therefore creates an identity with no scope and no elevated role; elevation requires someone with the authority to grant it. The same reasoning means a deployment whose users register with a personal email must keep its own role table: the provider has no concept of the employment relationship and cannot revoke on offboarding.
Anonymity is a value, not an error
Section titled “Anonymity is a value, not an error”useResolve() returns { ok: true, data: null } for a visitor and
{ ok: false, error } only when the provider itself failed. Collapsing them
turns a broken identity provider into a public route, and the symptom — every
guarded endpoint returning 401 — reads as “nobody is logged in” rather than
“the backend is down”. An unknown provider id is ok: false for the same
reason: a typo must not quietly open a route.
Roles and capabilities are open strings; rank is data
Section titled “Roles and capabilities are open strings; rank is data”AccessRoleSchema and AccessCapabilitySchema became format-validated strings.
The built-ins live in BUILT_IN_ROLE_SLUGS / BUILT_IN_CAPABILITIES const
tuples, so autocomplete survives while a typo fails loudly at the schema
boundary instead of silently granting nothing.
rank moved from the hardcoded table into AccessRoleDefinition, and
useRegisterRole validates before storing. This is what makes a custom role a
first-class participant in the hierarchy rather than a special case.
The cost is accepted knowingly: a mistyped role slug no longer fails at compile
time. It fails at runtime with the Unknown access role error, one call earlier.
A grant is a role scoped to a resource
Section titled “A grant is a role scoped to a resource”useGrantAwareCan() checks global roles first, then Grant rows for that exact
resource. A grant reuses the same registry — viewer, commenter and
editor mean whatever the deployment registered them to mean — so there is one
vocabulary, not two. Only the scope differs.
GrantResolver is injected, so the core never learns where rows live. Grant
expiry is evaluated by the core, not the resolver: revoking a contractor is
deleting one row, not auditing every query path that might have cached the role.
An unreadable expiresAt is treated as expired, because a share whose
deadline cannot be read is a share nobody meant to leave open. A missing
resolver denies rather than skips.
The directory owns the lockout invariants
Section titled “The directory owns the lockout invariants”DirectoryService wraps a DirectoryRepository and enforces the rules that
otherwise live in a code review nobody reads:
- the last active holder of a role cannot lose it (a suspended holder does not rescue them — counting them would let the system drop to zero live administrators);
- nobody may suspend, delete or demote themselves;
- you cannot grant a role more privileged than the best one you hold, and
owneris never granted through these paths at all; useUpdate({ roles })runs the same guards, because an update that accepts{ roles: [] }is a way arounduseRemoveRole;useSuspendis a soft offboarding — reversible, auditable, and distinct fromuseDelete.
Every refusal carries a stable code, so a UI can say “promote someone else
first” instead of matching on message text.
Consequences
Section titled “Consequences”Better. One authorization vocabulary for global and per-resource access. A
deployment can be a plain dashboard with zero configuration, or a closed
organisation with identity capture and a rotation policy, without either
forking the toolkit. The lockout guards are the default rather than a review
comment. dist/ stays free of database concerns, so the core remains testable
with a plain object.
Worse. The public AccessRoleDefinition gained a required rank and
useRegisterRole now throws on a malformed definition — a source-level break
for anyone who was registering a custom role, who was silently getting no
inheritance anyway. Roles and capabilities are strings, so a typo is a runtime
error rather than a compile error. DirectoryService is deliberately not a
singleton: it is constructed with a repository, because a process-global
directory is a process-global database handle.
Deliberately absent. Deleting a provider account, revoking a live session and forcing a password change are not methods here. A directory row disappearing must never be the only thing that happens on offboarding, and those operations belong to whichever provider the deployment actually uses.