0011. The first slice of teams and authorization¶
Status: Proposed (2026-11-15)
From #897 (Refine the authorization reef: an openfga Nereid answers who may do what), refined with the owner on 2026-11-15. The journey is #1644 (the first slice of teams and authorization); each task below is one of its sub-issues.
This file is the plan an agent carries out end to end, without asking design questions. Read it whole before the first task. When this file and the repository disagree, the repository wins: record the difference in the progress log and go on.
The answer¶
Users and teams are registered. A role is bound to a team, or to a position in it, on a node of the tenancy tree. The Nereus API asks before every read and write. A member with a privileged position may do what the other members may not.
$ nereus authorization can-i create environment/environments \
--owner project/payments \
--user bruno
no: no binding gives bruno create on environment/environments at project/payments
$ nereus environment create staging \
--owner project/payments
✗ environment/environments/staging: bruno may not create environment/environments at project/payments. To see who may, run:
nereus authorization binding list --owner project/payments
Nothing was changed.
Decisions¶
Each taken with the owner on 2026-11-15 unless another date is given.
- Team, not Group (#1306, owner 2026-11-10):
TeamandMemberlive in theteamsreef,RoleandBindingin theauthorizationreef,Userin core. Reason: access derives from team membership, so there is no second list of groups to keep in sync; an identity provider's groups are an output, never the source. - A person is one
Userof Nereus with several identities (ADR 0006: the person is aUserof core, not asub). The subject of every check isuser:<User name>, never an identity provider'ssubor an e-mail. Reason: the owner's Google, Microsoft and other accounts must give the same access. - A token whose identity is linked to no
Userhas no permission. Reason: having a login is not having permission (#1306). - The first identity is linked by the token's verified e-mail; a second identity is out of this slice. An administrator creates the User with its e-mail; the first sign-in of a token with
email_verified: trueand that e-mail links{issuer, sub}. Reason: ADR 0006 asks for an e-mail code to link a newsub, which needs a notification reef that does not exist. This is a stand-in: it trusts theemail_verifiedclaim of the instance's own issuer, also when that issuer brokered another identity provider. ADR 0006 also says the platform generates the User's id; in this slice the id is the object's name. Task 2 records both as stand-ins and amends ADR 0006. - A binding names a team, a position in a team, or (the exception) one User. The position is a free name on the
Memberin this slice. Reason: when the person in the position changes, the access follows without touching a binding; #1307'sPositionkind (skills, level, places) takes the same name later, and the binding and the tuples do not change. - Teams do not nest. Reason: the tenancy tree (Organization, Project, nested Projects) already gives the hierarchy, and access flows down it.
- Managing members is a rule like any other (
teams:members:create,delete), carried by a role. Reason: #1306, "who may create a role or a binding is itself a rule". - A position that a binding names is assigned only by who may create bindings at that binding's node. Reason: whoever manages members must not give themselves more access than they hold.
- The objects are the source of truth; the
openfgaNereid writes the tuples. Reason: declarative and auditable; deleting OpenFGA loses nothing. - One fixed OpenFGA model, versioned with the Nereid and tested with
fga model test. A new role becomes tuples, never a new model. Reason: deterministic first. - One OpenFGA type,
node, serves every tenancy kind. This differs from ADR 0015's sketch ("one OpenFGA type per tenancy kind"): the tenancy kinds come from each instance, and a fixed model cannot name them. Task 2 records it in the ADR. - OpenFGA runs from its official Helm chart through the release reef, with Postgres through the
Databasekind, as thekeycloakNereid does. Reason: open source first, and nothing new to invent. - The slice refuses Environments and the tenancy tree too.
nereus environmentandnereus tenancyreach the platform through the Nereus API since #1638 and #1639 (both under #1320, the CLI never knows the cluster). - OpenFGA down: every read and write is refused, except
whoami,statusanddoctor. Reason: fail closed; an outage must never become a way to read. nereus-adminsis the emergency exit. A token in that Keycloak group passes when the normal check does not, andnereus doctorwarns when the exit was used. Before theauthorizationreef has a default Mandate, today's rule holds unchanged (onlynereus-admins). Reason: the exit exists already and does not depend on OpenFGA; #1306's root User with MFA replaces it later.- Agents as subjects are out of this slice.
Member.spec.kindtakes onlypersonnow;agentjoins later. - Roles:
administratoris built in (every verb on every kind of every reef, present and future; never changed or deleted).viewer,developerandteam-leadare editable examples. - Commands use singular kinds (
nereus authorization role create), as ADR 0013 (command conventions) and the built decks do; #1306's sketch used plurals.--ownertakes<kind>/<name>in lowercase, asnereus environmentdoes. can-iis a new verb, undernereus authorization can-i, with the shortcutnereus can-i. With no--userit answers for the caller; asking about another User is itself a permission. Task 2 amends ADR 0013.- The pillar "No single control point" joins
docs/vision.mdin this slice (owner, 2026-11-15, from Thinking in Platforms, Kaspar von Grünberg and Luca Galante, 2026). - The agent merges alone during this journey (the envelope of #1644): one task, one PR, merged by rebase once
make checksand the scene the task names pass. A design decision or a bug the plan does not cover is settled with a Fable agent and recorded in the progress log. - No password users on
k3d-nereus(the refiner's call, the conservative one): the two signed-in people of the final scene exist only on the throwaway cluster of the scene. Onk3d-nereusthe proof iscan-i --user. Reason: the kept cluster's Keycloak must not gain accounts with a password an agent chose.
The CLI¶
The source of truth for the commands is the deck docs/specs/cli/reefs/authorization.yaml (26 slides, 22 of them a command, every one planned), approved by the owner on 2026-11-15. Build each command to print what its slide shows: where this file and the deck differ on a command's output, the deck wins. The commands, in the order of the story:
| Command | Reef | Task |
|---|---|---|
nereus reef apply authorization, nereus reef apply teams |
core | 4, 5 |
nereus nereid apply openfga --reef authorization |
core | 6 |
nereus user create\|apply\|list\|get\|delete |
core | 3 |
nereus teams create\|apply\|list\|get\|delete (default kind Team) |
teams | 4 |
nereus teams member create\|apply\|list\|get\|delete |
teams | 4 |
nereus authorization role create\|apply\|list\|get\|delete |
authorization | 5 |
nereus authorization binding create\|apply\|list\|get\|delete |
authorization | 5 |
nereus authorization can-i <verb> <reef>/<kinds>, nereus can-i |
authorization | 8 |
Every command follows ADR 0013: long options, --dry-run on every change, --examples, output lines ending in created, configured, unchanged or deleted with the full path (teams/teams/payments/members/ana created), and a Next steps: block with a blank line before and after and the commands indented two spaces. A refusal follows ADR 0012 (error messages).
The options the deck fixes:
$ nereus user create ana \
--email ana@example.com
$ nereus teams create payments \
--owner project/payments
$ nereus teams member create ana \
--team payments \
--position tech-lead
$ nereus authorization role create release-manager \
--rule release:releases:create,apply,delete
$ nereus authorization binding create payments-leads \
--role team-lead \
--team payments \
--position tech-lead \
--owner project/payments
$ nereus authorization binding create ana-admin \
--role administrator \
--user ana
A rule is <reef>:<kinds>:<verbs>, each part a comma list or *. The reef is the name the CLI uses (environment, core); the kinds are the plurals of the routes (environments); the verbs are ADR 0013's (create, apply, list, get, delete, deploy, render, logs, publish) plus can-i.
The kinds¶
The fields a builder may not change; the rest (status, printer columns, validation details) is the builder's.
User, core.getnereus.dev/v1alpha1, cluster scoped. spec.email (required), spec.displayName (optional). The linked identities are a list of {issuer, sub}, written only by the Nereus API; follow ADR 0006 (its example near "The person is a User of core") and ADR 0005 (one writer per field) for where the list sits. The object's name is the User's id in this slice.
Team, teams.getnereus.dev/v1alpha1, cluster scoped, the reef's default kind. spec.owner: {kind, name} (required, a node of the tenancy tree), spec.description.
Member, teams.getnereus.dev/v1alpha1, cluster scoped. spec.team (required), spec.user (a User's name; the CLI defaults it to the member's name), spec.kind (person, the only value now), spec.position (optional, a free name, lowercase). A member is unique in its team; the builder chooses how the object's name carries both (the path printed is teams/teams/<team>/members/<name>).
Role, authorization.getnereus.dev/v1alpha1, cluster scoped, the reef's default kind. spec.rules: [{reef, kinds: [], verbs: []}], spec.owner: {kind, name} (optional: with none the role serves the whole instance). A built-in role carries an annotation and refuses apply and delete.
Binding, authorization.getnereus.dev/v1alpha1, cluster scoped. spec.role (required), exactly one subject: spec.team with an optional spec.position, or spec.user; spec.owner: {kind, name} (optional: with none the binding holds on the whole instance). A binding refuses a role, team or User that does not exist, and a role whose owner is neither its own node nor an ancestor of it.
Neither reef has a Nereid of its own for the objects (the API keeps them, as with tenancy); the authorization reef's Nereid, openfga, only answers the question. Neither Role nor Binding names OpenFGA.
The model¶
controllers/openfga/model.fga, as it is here. It passes fga model test (9 of 9 checks) with the store file below.
model
schema 1.1
type user
type team
relations
define member: [user]
type position
relations
define holder: [user]
type grant
relations
define subject: [user, team#member, position#holder]
type instance
relations
define granted: [grant#subject with rule_matches]
define can: granted
type node
relations
define parent: [instance, node]
define granted: [grant#subject with rule_matches]
define can: granted or can from parent
condition rule_matches(reef: string, kind: string, verb: string, rule_reef: string, rule_kind: string, rule_verb: string) {
(rule_reef == "*" || rule_reef == reef) && (rule_kind == "*" || rule_kind == kind) && (rule_verb == "*" || rule_verb == verb)
}
The question is always one check: user:<name> can on node:<kind>/<name> (or on instance:nereus when the object has no owner), with the context {reef, kind, verb}.
The tuples the Nereid writes, from the objects:
| From | Tuple |
|---|---|
| a tenancy node with no parent | instance:nereus parent node:organization/example |
| a tenancy node with a parent | node:organization/example parent node:project/payments |
a Member with a User |
user:ana member team:payments |
a Member with a position |
user:ana holder position:payments/tech-lead |
a Binding to a team, per rule triple |
team:payments#member subject grant:<binding>/<triple> |
a Binding to a position, per rule triple |
position:payments/tech-lead#holder subject grant:<binding>/<triple> |
a Binding to a User, per rule triple |
user:ana subject grant:<binding>/<triple> |
| the same binding, per rule triple | grant:<binding>/<triple>#subject granted node:project/payments, with the condition rule_matches and the context {rule_reef, rule_kind, rule_verb} |
A role's rules expand to one triple per reef, kind and verb (environment:environments:create,delete is two triples). The grant's id comes from the binding's name and the triple, never from an index, so the same objects always give the same tuples. A node's id is its kind in lowercase, a slash and its name.
The store file of the tests, controllers/openfga/model.fga.yaml (the builder may add cases, never remove one):
name: nereus authorization
model_file: ./model.fga
tuples:
- {user: "instance:nereus", relation: parent, object: "node:organization/example"}
- {user: "node:organization/example", relation: parent, object: "node:project/payments"}
- {user: "node:project/payments", relation: parent, object: "node:project/payments-mobile"}
- {user: "node:organization/example", relation: parent, object: "node:project/billing"}
- {user: "user:ana", relation: member, object: "team:payments"}
- {user: "user:bruno", relation: member, object: "team:payments"}
- {user: "user:ana", relation: holder, object: "position:payments/tech-lead"}
- {user: "user:root", relation: subject, object: "grant:root-admin/0"}
- user: "grant:root-admin/0#subject"
relation: granted
object: "instance:nereus"
condition: {name: rule_matches, context: {rule_reef: "*", rule_kind: "*", rule_verb: "*"}}
- {user: "team:payments#member", relation: subject, object: "grant:payments-developers/0"}
- user: "grant:payments-developers/0#subject"
relation: granted
object: "node:project/payments"
condition: {name: rule_matches, context: {rule_reef: "*", rule_kind: "*", rule_verb: "list"}}
- {user: "team:payments#member", relation: subject, object: "grant:payments-developers/1"}
- user: "grant:payments-developers/1#subject"
relation: granted
object: "node:project/payments"
condition: {name: rule_matches, context: {rule_reef: "*", rule_kind: "*", rule_verb: "get"}}
- {user: "position:payments/tech-lead#holder", relation: subject, object: "grant:payments-leads/0"}
- user: "grant:payments-leads/0#subject"
relation: granted
object: "node:project/payments"
condition: {name: rule_matches, context: {rule_reef: "environment", rule_kind: "environments", rule_verb: "create"}}
tests:
- name: the slice
check:
- {user: "user:ana", object: "node:project/payments", context: {reef: environment, kind: environments, verb: create}, assertions: {can: true}}
- {user: "user:bruno", object: "node:project/payments", context: {reef: environment, kind: environments, verb: create}, assertions: {can: false}}
- {user: "user:bruno", object: "node:project/payments", context: {reef: environment, kind: environments, verb: list}, assertions: {can: true}}
- {user: "user:ana", object: "node:project/payments-mobile", context: {reef: environment, kind: environments, verb: create}, assertions: {can: true}}
- {user: "user:ana", object: "node:project/billing", context: {reef: environment, kind: environments, verb: create}, assertions: {can: false}}
- {user: "user:ana", object: "node:organization/example", context: {reef: environment, kind: environments, verb: create}, assertions: {can: false}}
- {user: "user:ana", object: "node:project/payments", context: {reef: delivery, kind: deliveries, verb: create}, assertions: {can: false}}
- {user: "user:root", object: "node:project/billing", context: {reef: anything, kind: future, verb: delete}, assertions: {can: true}}
- {user: "user:carla", object: "node:project/payments", context: {reef: environment, kind: environments, verb: list}, assertions: {can: false}}
The command that proves it (the image is pinned by digest in the make target of task 6):
docker run \
--rm \
--volume "${PWD}/controllers/openfga":/w:ro \
openfga/cli model test \
--tests /w/model.fga.yaml
How the Nereus API decides¶
One function, in a new api/authorization.py. admitted() (api/server.py) cannot hold it: it sees only the request and the verifier, before the body is read, and knows neither the route's reef and kinds nor the stored object. So the route wrappers (service_route, streamed_route, cluster_route, object_route) gain a declaration per registration: the reef, the kinds (plural) and a function that gives the owner of the object the request names (from the body on a PUT, from the stored object on a GET or DELETE). The wrapper asks before act runs, and filters the items of a list after it. Every registration in every api/*_routes.py gets its declaration; a route with none refuses to register, so a new route cannot forget it. /v2 (api/registry_proxy.py, the registry), /v1/screens and /v1/ideas/notes are checked on the instance, as registry, screens and ideas with the kinds their paths name.
In order:
- Open routes (
/healthz,/v1/me,/v1/status,/v1/doctor,/.well-known/nereus-configuration) are never asked. - No default Mandate of the
authorizationreef: today's rule, unchanged (nereus-adminsonly). The slice changes nothing on an instance that has not installed the reef. - The User: the token's
{issuer, sub}is looked up in the Users' identities; with none, a User whosespec.emailequals the token's e-mail, only when the token saysemail_verified: true, gets the identity linked now (api/auth.pydoes not reademail_verifiedtoday, andPrincipalhas no issuer: add both, the issuer from the verifier). - The check: the Nereus API asks the reef's default Mandate's Nereid, never OpenFGA by name. It finds the service the way
api/ideas_notes.pyfinds doris (mandate_of(), which names theideasreef today and takes the reef as an argument from now on, picks the reef's default Mandate;address()builds the service's address from itsspec.nereid). The contract isPOST /v1/checkwith{user, verb, reef, kinds, node}(kindsis the plural, asenvironments;nodeis{kind, name}with the Kind as the objects write it, asProject, ornullfor the instance;spec.ownerand a tenancy node'sspec.parentcarry the Kind the same way, and only the Nereid lowercases it for anode:id), answering{allowed, bindings}(the names of the bindings that grant it, forcan-i's "yes"). A timeout of two seconds, a refused connection or any answer but 200 counts as "down". - Allowed: go on, and log the person as today (
who(principal)). - Not allowed, no User, or down, and the token is in
nereus-admins: go on through the emergency exit, log it, and count it fornereus doctor. An administrator who has their own User and a binding toadministratornever uses the exit; task 11 creates both first. - Otherwise refuse: 403 when the answer was no or the token has no User, 503 when the Nereid is down, each with ADR 0012's fields (
cause,fix), so the CLI prints the next steps.
Which node a request is checked on:
| Request | Node |
|---|---|
PUT of an object with spec.owner |
the owner in the body; when it changes an existing object's owner, both the old and the new |
GET and DELETE of one object |
the stored object's spec.owner |
| a list | every object is kept or dropped by a check on its own owner (one check per distinct owner, not per object) |
an object with no spec.owner (core kinds, an instance-wide Role or Binding, a User) |
the instance |
| a tenancy kind | the node itself; creating a node under a parent is checked on the parent |
a Team |
its spec.owner; a Member is checked on its team's owner |
The verb comes from the request: a list is list, GET of one object get, PUT with mustNotExist is create, another PUT apply, DELETE delete; a route that is none of these (a publish, a log stream) names its own ADR 0013 verb.
Tasks¶
Each task is one sub-issue of #1644, one worktree, one PR. "Proves it" is the command whose passing output goes in the PR. Every task also runs make checks once before its PR and commits the record (chore(checks): record make checks (#<id>)), as every merged change does.
Task 1 (#1653): the pillar "No single control point"¶
- Touches:
docs/vision.md(the list of pillars and its###section), the README's "The pillars" section. - Depends on: nothing.
- Does: adds the pillar: control (identity, authorization, quota, policy) is enforced in layers (the cloud, Kubernetes, the Environment, the Nereus API), so one layer failing or misconfigured does not collapse the platform. The section says what holds today (the Nereus API's check and the emergency exit of this slice) and what does not yet (Kubernetes RBAC from the bindings, cloud policy), and credits the book.
- Done when: the pillar count and both lists agree.
- Proves it:
make docs-lint.
Task 2 (#1654): the ADR of teams, roles and Users, and the amendments¶
- Touches: a new ADR in
docs/adr/(the next number), ADR 0006, ADR 0013, ADR 0015,mkdocs.yml. - Depends on: nothing. It can run beside every other task.
- Does: writes the ADR #1306 asks for,
Proposed, by the checklist ofdocs/agent/adr.md, with## Prior art(GitHub teams, Backstage'sGroupandUser, Kubernetes RBAC, AWS's root user, OpenFGA's modelling of roles, each opened and quoted). It records decisions 1 to 19 above, #1306's decisions of 2026-11-10, and the stand-ins of decision 4. It amends ADR 0006 with those stand-ins (the first identity by verified e-mail, the User's name as its id), ADR 0013 with the verbcan-i, and ADR 0015 with decision 11 (onenodetype). It comments on #1306 that the commands are singular. - Done when: the ADR is in the index and the docs build.
- Proves it:
make docs-lintand the docs build ofmake checks. Accepting the ADR is the owner's.
Task 3 (#1645): the User kind of core, and the person behind a token¶
- Touches:
cli/src/nereus/crds/(the new CRD),make chart(the templates ofcli/src/nereus/charts/nereus-reefs),cli/tests/test_crds.py, the API's RBAC (cli/src/nereus/charts/nereus/templates/api.yaml, pinned bycli/tests/test_chart.py), a newapi/user_routes.pyandcli/src/nereus/user_service.py, a newcli/src/nereus/commands/user.py,api/auth.py(Principal),/v1/me(api/server.py),nereus whoami(cli/src/nereus/commands/login.py). - Copy from:
api/mandate_routes.py,cli/src/nereus/mandate_service.py,cli/src/nereus/commands/mandate.pyand their tests (a core kind served at/v1/core/...). - Depends on: nothing.
- Does: the kind;
/v1/core/users[/{name}](admins only for now, like every route until task 7); the commands; a function that gives the User of aPrincipal(by identity, else by verified e-mail, linking it), used by/v1/me, which now also answersuser;nereus whoamiprints the User's name, or says the person has no User yet with the next step. - Done when: a User is created, listed and deleted through the API; a token whose e-mail is not verified links nothing; a second User with the same e-mail is refused.
- Proves it: the unit tests of
api/andcli/tests/for the routes, the commands and the lookup. The end-to-end proof is task 11's scene: the reference profile ofmake scene-corehas no sign-in, so the API takes no write there.
Task 4 (#1646): the teams reef¶
- Touches: a new
reefs/teams/(the CRDs, an admission policy,samples/), the symlinkcli/src/nereus/interfaces/teams,cli/src/nereus/cli.py(where a reef's group is registered), a newapi/teams_routes.py,cli/src/nereus/teams_service.py,cli/src/nereus/commands/teams.py, the API's RBAC and its pin, the reference profile, a newtest/scene-core-teams, a new deckdocs/specs/cli/reefs/teams.yaml(the team slides move there from the authorization deck,status: built),docs/specs/cli/index.yaml. - Copy from: the commit
2597436a(the usage reef, 43 files: route module, command, deck, samples, scene,test_boundaries,test_profiles), andreefs/tenancy/admission.yamlfor the admission policy. - Depends on: nothing to start (a
Membernames a User by name; the check that the User exists joins when task 3 is onmain). - Does:
TeamandMemberas in "The kinds"; the routes/v1/teams/teams[/{name}]and/v1/teams/members[/{name}]; the commands; refusals: a team whose owner does not exist, a member of a team that does not exist, a team deleted while it has members or a binding names it. - Done when: the deck's team commands print what their slides show.
- Proves it: the unit tests (each command both ways, as
cli/tests/test_mandate_through_api.py), andmake scene-corewith the newscene-core-teams, which applies the objects withkubectlasscene-core-usagedoes (the reference profile has no sign-in, so the API takes no write there): the CRDs install, the admission policy refuses a team with no owner, the objects are stored. The commands end to end are task 11's.
Task 5 (#1647): the authorization reef's kinds¶
- Touches: a new
reefs/authorization/(the CRDs, the built-inadministrator, an admission policy,samples/withviewer,developerandteam-lead), the symlink undercli/src/nereus/interfaces/,cli/src/nereus/cli.py, a newapi/authorization_routes.py,cli/src/nereus/authorization_service.py,cli/src/nereus/commands/authorization.py, the API's RBAC and its pin, a newtest/scene-core-authorization, the deckdocs/specs/cli/reefs/authorization.yaml(role and binding slides tobuilt). - Copy from: the same as task 4.
- Depends on: nothing to start (a binding's check that its team exists joins when task 4 is on
main). Tasks 3, 4 and 5 touch the same registration lines (cli.py, the API's RBAC,create_appinapi/server.py): the second and third to merge rebase and keep both sides. - Does:
RoleandBindingas in "The kinds"; the routes/v1/authorization/roles[/{name}]and/v1/authorization/bindings[/{name}]; the commands with--rule;administratorapplied with the reef and refused onapplyanddelete; a role refused on delete while a binding names it. The example roles:vieweris*:*:list,get;developerisviewerpluscreate,apply,deleteon the kinds of build, delivery and release;team-leadisdeveloperplusenvironment:environments:create,deleteandteams:members:create,delete. A profile cannot apply sample objects today, so the samples are applied bynereus authorization role apply --pathand the reef'sNext steps:says so. - Done when: the deck's role and binding commands print what their slides show.
- Proves it: the unit tests, and
make scene-corewithscene-core-authorization, driven withkubectlas in task 4.
Task 6 (#1648): the openfga Nereid¶
- Touches: a new
controllers/openfga/made withscripts/nereid/new(docs/guides/build/new-nereid.md),Makefile(NEREIDS, a targetauthorization-model-test),cli/src/nereus/local_nereids.py(TOOLS, its RBAC),cli/tests/test_boundaries.py(BY_INIT), the README's table of Nereids. - Copy from:
controllers/keycloak/(keycloak.py:release_objectsandensure_releasefor the chart through the release reef,database_objectandensure_databasefor Postgres, the connection read from the Secret<name>-database;server.py: the loop andready()), and doris for a Nereid that serves HTTP to the Nereus API. - Depends on: the fields of "The kinds" only; it is built against fixtures, beside tasks 3, 4 and 5.
- Does: installs OpenFGA (the chart
openfga/openfga, its version pinned, the Postgres of theDatabasekind, migrations as the chart runs them); creates the store and writesmodel.fgawhen its content changed, keeping the store and model ids in its status; each pass reads the tenancy nodes, Teams, Members, Roles and Bindings, computes the tuples of "The model", reads the store's tuples and writes only the difference; servesPOST /v1/check(the contract of "How the Nereus API decides") and/healthz; reports Ready only when OpenFGA answers and the tuples are in step. - Done when: the objects of the model's store file, as fixture objects, give exactly the store file's tuples, and the nine answers of its tests through
POST /v1/checkagainst an OpenFGA the test starts in Docker (openfga/openfga run, in memory; skipped where Docker is absent, somake checksstays as it is). The proof on a cluster, with flux and cloudnative-pg, is task 11's scene. - Proves it:
make authorization-model-test; the Nereid's unit tests (the tuples computed from fixture objects, the difference, the check).make contractandmake scene-idprun only on the owner's word and are not delegated to this journey: do not run them.
Task 7 (#1649): the Nereus API asks before acting¶
- Touches: a new
api/authorization.py,api/server.py(admitted(),service_route,cluster_route,object_route,streamed_route),api/registry_proxy.py(its own group check), every registration in everyapi/*_routes.py(its declaration),cli/src/nereus/commands/doctor.py(aWARNstate, which does not exist today, and the check of the emergency exit). - Depends on: tasks 3, 4, 5 and 6 on
main, and #1638 and #1639. - Does: "How the Nereus API decides", whole. The refusal's text is the deck's.
nereus doctorgainsWARNand one line: how many times the emergency exit was used since the API started. AWARNnever failsdoctor: its exit code stays 0. - Done when (in the unit tests, with a fake check service; end to end in task 11): with the reef installed, a User with the
developerrole at a Project lists there and is refused a create; a User with no binding is refused everything but the open routes; with the Nereid stopped, everyone butnereus-adminsgets 503 and the same message every time; with no Mandate of the reef, every existing test passes unchanged. - Proves it: the unit tests of
api/authorization.pywith a fake check service (allowed, refused, down, no User, admin through the exit, no Mandate, the list filter with two owners, a registration with no declaration refused), andmake scene-coreunchanged (no Mandate of the reef there).
Task 8 (#1650): can-i¶
- Touches:
api/authorization_routes.py(POST /v1/authorization/can-i),cli/src/nereus/commands/authorization.py, the top-level shortcut incli/src/nereus/cli.py, the deck's slides tobuilt. - Depends on: task 7.
- Does:
nereus authorization can-i <verb> <reef>/<kinds> [--owner <kind>/<name>] [--user <name>]: the deck's lines (yes: authorization/bindings/<binding> gives <role> to <subject> at <node>, orno: no binding gives <user> <verb> on <reef>/<kinds> at <node>); exit code 0 for yes and 1 for no. Asking with--userneedsauthorization:can-i:getat that node. The shortcutnereus can-iis the same command. - Done when: the deck's three
can-islides print what they show. - Proves it: the unit tests, and the step in the final scene.
Task 9 (#1651): only who may bind assigns a position a binding names¶
- Touches:
cli/src/nereus/teams_service.py, its tests. - Depends on: task 7.
- Does: creating or changing a
Memberwith aspec.positionthat some Binding names is allowed only to who mayauthorization:bindings:createat that binding's node (decision 8); the refusal names the binding and says who can do it. - Done when: a User with only
teams:members:create,deleteadds a member with no position, and is refused giving themselvestech-lead. - Proves it: the unit tests, and the step in the final scene.
Task 10 (#1655): the profile, the walkthrough and the docs¶
- Touches:
cli/src/nereus/charts/nereus/profiles/internal-developer-platform.yaml(theteamsreef, theauthorizationreef with{name: openfga}and its default Mandate), ADR 0014's note that these "do not exist yet", a newdocs/guides/access/authorization.md,docs/features.md(the rows that waited for #897, and the stand-ins table),mkdocs.yml, the decks' remaining statuses. - Depends on: tasks 4, 5, 6 and 7.
- Does: the profile installs the two reefs and the Nereid; the walkthrough is the deck's story with real output;
docs/features.mdsays what is built. - Done when: the profile lists the two reefs, the Nereid and the default Mandate, and its tests pass; a fresh instance of the profile ending with the
authorizationreef Ready is seen in task 11. - Proves it: the profile's unit tests (
cli/tests/test_profiles.py), the docs build, and task 11'smake scene.make scene-idpis not delegated to this journey: leave it, named in the PR, for the owner's word.
Task 11 (#1652): the final scene, and the slice on k3d-nereus¶
- Touches:
test/scene(a new step file it sources), a helper that creates two local people in the scene's Keycloak through its admin API (the Secretkeycloak-admin), with a verified e-mail atexample.com, and signs each in withtest/oidc-flow. - Depends on: every task above.
- Does: the scene below, on the throwaway cluster of
make scene; thenscripts/registry/release publish,scripts/deploy/live --allow-kept-cluster, the two reefs and the Nereid applied onk3d-nereus, and the proof of decision 22 there. On both clusters the first step is the administrator's own access: the signed-in administrator creates their own User (the e-mailnereus whoamishows) and a binding ofadministratorto it, through the emergency exit, once. - Done when: the scene passes, and on
k3d-nereusnereus doctorends with exit code 0 (aWARNof the emergency exit is expected after the first step) andnereus authorization can-i ... --user brunoanswersnowhile--user anaanswersyes. - Proves it:
make scene, and the commands' output onk3d-nereuspasted in #1644.
The final scene¶
On the scene's cluster, signed in as the scene's administrator unless a step says otherwise:
nereus user create anaandbruno; a teampaymentsowned byproject/payments;anaa member with the positiontech-lead,brunoa member with none.- Bindings:
developerto the team,team-leadto the position, both atproject/payments. can-i create environment/environments --owner project/payments --user anasays yes and names the binding;--user brunosays no.- As bruno:
nereus environment listanswers;nereus environment createis refused with its next steps and exit code 1; nothing was created. - As ana: the same
create --dry-runis accepted. - As bruno: adding a member with no position is refused (bruno is not a team lead); as ana, it is accepted; as ana, giving herself or anyone the position
tech-leadon a second team whose binding she may not create is refused (task 9). nereus teams member delete ana --team payments;can-ifor ana now says no, and as ana thecreate --dry-runis refused (leaving the team removes the access).- A person with a login and no User is refused everything but
nereus whoami, which says so. - The
openfgaNereid scaled to zero: as bruno, a list is refused with the "down" message; as the administrator it answers, andnereus doctorshows theWARNof the emergency exit. Scaled back, bruno's list answers again. - OpenFGA's database deleted and the Nereid restarted: after one pass, step 3's answers are the same (the objects are the source of truth).
Carrying it out¶
Who: one Opus agent orchestrates and owns the journey (it comments "Owner session:
Waves:
| Wave | Tasks, in parallel | Ends with |
|---|---|---|
| A | 3, 4, 5, 6, and one subagent for 1 then 2 (merge order: 3, 4, 5, then 6) | milestone 1: the kinds and the Nereid on main; nothing is enforced, so nothing changes for anyone |
| B | 7, with 10's docs drafted beside it | the API asks |
| C | 8, 9, 10 | milestone 2: the slice is whole |
| D | 11, by the orchestrator | milestone 3: the scene passes and k3d-nereus runs it |
A release and a deploy to k3d-nereus happen at milestones 1, 2 and 3, never between.
Quota-safe order. Every task merges alone and leaves main green and usable: tasks 3 to 6 add kinds and a Nereid nothing uses yet; task 7 changes nothing while the reef has no Mandate; the profile gains the reef only in task 10. When the quota ends, a new session resumes from the state, never from memory: gh issue view 1644 (the sub-issues open and closed, and the comments), the progress log below, gh pr list, git worktree list. A task with a worktree and no merged PR is resumed in that worktree.
The rules every subagent gets (the same block in every brief, plus its task's section):
- Read
CLAUDE.md,docs/agent/rules.mdanddocs/agent/worktrees.mdfirst. Work only in the task's worktree (scripts/worktree/new <type> <issue>-<slug>); the main clone is read and pulled only. - Its own scratch directory for commit messages and notes, never a shared one.
- Tests first. Targeted tests while working;
make checksonce at the end; never two scenes at the same time on this machine (the orchestrator says when a subagent may runmake scene-core;make sceneandmake scene-idpare run by the orchestrator). - Conventional Commits, one per topic, with
git -C <worktree> add --allthengit -C <worktree> commit --file <message file>as plain separate commands. - Public by design: no e-mail, personal or company name, internal domain, account id or token; examples use
example.com. - Never
speak. Never message another session. Never push or merge: the orchestrator does both. - Report in a few lines: the commits, each check run and its result, what was left out and why. Never file contents.
The orchestrator, per task: brief the subagent; when it reports, read the diff, rebase onto main, run what the task's "Proves it" names, open the PR saying what ran, merge by rebase, close the sub-issue, add its line to the progress log, remove the worktree. A check failing three times in a row on the same task stops that task: the log says what was tried, and the orchestrator goes on to a task that does not depend on it.
Limits, with no exception:
- Nothing destructive on the host: no
sudo, nodocker system prune, no deleting of a k3d cluster other than the scenes' own throwaway ones, normoutside a worktree or a scratch directory, nothing written to the owner's home but whatmakealready writes. - No cloud resource: no cloud provider's CLI is run at all.
k3d-nereusis reached only throughscripts/registry/release publish,scripts/deploy/live --allow-kept-clusterand thenereusCLI. It may go down and come up as often as needed. While another session is alive on the repository (claude-peers), an[ask]comes first (docs/agent/peers.md).- The release publishes to the project's own registry on ghcr.io. A new package (the
openfgaNereid's image) is private until a click makes it public (#1338,docs/agent/publish.md). The owner pre-authorized that click for this journey (2026-11-15): the agent makes it in the owner's browser (the Chrome tools), for the packages this plan creates and for nothing else on that page, and records it in the progress log. When the browser is not reachable, install the Nereid onk3d-nereusfrom the local registry (docs/guides/operate/kept-cluster-update.md, "without publishing": the image atlocalhost:5111, thennereus nereid apply openfga --image ...), and leave the click as the one item waiting for the owner.
Out of scope¶
Each with the better solution it leads to.
- A second identity on the same User: ADR 0006's e-mail code through a notification reef;
nereus user identitycommands. - The instance's root User (#1306): created by
nereus init, MFA required, its sign-ins audited; it replaces thenereus-adminsemergency exit. - Agents as subjects:
Member.spec.kind: agent, a token by OAuth 2.0 Token Exchange (RFC 8693) with theactclaim, and a permission that is the intersection of the person's and the agent's scope; the audit trail records both. - Quotas: Kubernetes
ResourceQuotaobject counts first, then aquotareef (Quota, Budget) on the same tenancy nodes; aTeamis already a place a quota can attach. - Bindings projected into Kubernetes RBAC: the layer below the Nereus API of the pillar "No single control point" (ADR 0015: "the API projects them into the namespaces where a Project runs"), so
kubectlis refused too. - The
Positionkind (#1307): skills, level and places; the position's name on aMemberbecomes a reference to it. - Groups mirrored to or from an identity provider: a Nereid writes Keycloak groups from the teams (#1306: an output, never the source).
- No escalation on bindings: today whoever may create bindings at a node may grant any role there; later, only what they hold themselves, as Kubernetes RBAC's
escalateandbind. - The model test in
make checks:make authorization-model-testneeds Docker, whichmake checksdoes not use today. nereus environment kubeconfigstill reads the kubeconfig (#1638); serving a virtual cluster's credentials through the API is its own decision.
Progress log¶
One line per task when its PR merges, and one per decision the plan did not cover. Newest last.
| When | Task | What | By |
|---|---|---|---|
| 2026-11-15 | plan | The plan, the deck and the model's tests (9 of 9) written; #1638 and #1639 put environment and tenancy behind the Nereus API |
the refining session |
| 2026-11-15 | 1 (#1653) | The pillar "No single control point" in docs/vision.md and the README; the deck more-than-an-idp counts twenty-three (PR #1661) |
alimede |
| 2026-11-15 | 3 (#1645) | The User kind of core, /v1/core/users, nereus user, the User behind a token (by {issuer, sub}, else once by verified e-mail), /v1/me and nereus whoami answer it |
alimede |
| 2026-11-15 | orchestration | A subagent's commit in a worktree may be refused by guard-main when its session's cwd is the main clone; the orchestrator then commits for it. On a rebase, the docs/checks/ conflict takes the task's side and the README is re-rendered from main's with scripts/checks/checks render, never taken whole from the task's side |
alimede |
| 2026-11-15 | 3 (#1645) | A security review found a race in linking an identity: put_cluster takes an expected_version, and user_of and put_user write with a compare-and-swap (PR #1663) |
alimede |
| 2026-11-15 | 2 (#1654) | ADR 0027 (teams, roles and Users), Proposed; ADR 0006, 0013 and 0015 amended; #1306 told the commands are singular (PR #1664). administrator comes with the authorization reef, not with nereus init as #1306 said |
alimede |
| 2026-11-15 | 4 (#1646) | The teams reef: Team, Member (its User must exist), /v1/teams/..., nereus teams, the deck teams.yaml, scene-core-teams (passed). No profile can install a reef with no Nereid: the scene applies it with nereus reef apply teams |
alimede |
| 2026-11-15 | 5 (#1647) | The authorization reef's kinds: Role, Binding (its role, team or User must exist; the role's owner reaches the binding's node, on create and on apply), the built-in administrator applied with the reef (not by nereus init), the examples viewer, developer, team-lead, nereus authorization role\|binding, scene-core-authorization (passed). A security review: only the reef marks a role built in (built-in-name policy). A User is not deleted while a binding names it |
alimede |
| 2026-11-15 | 5 (#1647) | Two defects only a scene caught: thetis's image did not COPY reefs/authorization (now cli/tests/test_dockerfile_reefs.py checks every image that builds the CLI); and Kubernetes' CEL type checker refuses a map literal mixing a string and a list, which cel-python accepts. Gap: make checks does not compile CEL as the API server does |
alimede |
| 2026-11-15 | 6 (#1648) | The openfga Nereid: chart 0.4.1 through the release reef, Postgres through Database, the store and model written, the tuples computed from the objects and only the difference written, POST /v1/check; make authorization-model-test (9 of 9); the fixtures guarded against the real CRDs. Repository over plan: grant ids are grant:<binding>/<reef>.<kind>.<verb> with * written _ (OpenFGA refuses : and * there); the store and model ids live in the Mandate's status (authorization); migrations run in an init container; nereid apply openfga does not make the default Mandate (--default is its next step, the switch of decision 15) |
alimede |
| 2026-11-15 | milestone 1 | The kinds and the Nereid on main; nothing is enforced yet |
alimede |
| 2026-11-15 | milestone 1 | Released v0.1.11 (3 images built, 24 reused) and deployed to k3d-nereus (smoke test and nereus doctor pass). The click that makes openfga-controller public on ghcr.io was refused by Claude Code's permission classifier in the owner's browser: it waits for the owner, and make promote CHECK=1 fails on that one package until then |
alimede |
| 2026-11-16 | 7 (#1649) | The Nereus API asks the authorization reef's default Mandate's Nereid before acting: api/authorization.py, a declaration on every route (an undeclared one refuses to register), the emergency exit counted, nereus doctor's WARN. A security review found two defects before the PR, both fixed with tests: a PUT's verb now comes from the field its action reads (a query create was gated as a create on the parent while overwriting a node), and a stored owner that cannot be read fails closed (only a 404 means none). Left out: the deck's doctor line for openfga not answering |
alimede |
| 2026-11-16 | 10 (#1655) | The internal-developer-platform profile installs teams and authorization with openfga and its default Mandate openfga; a reef no Nereid serves gets a lane of its own, which openfga waits for (READS in profiles.py); the walkthrough docs/guides/access/authorization.md carries the deck's output until task 11 replaces it; docs/features.md and ADR 0014's note updated. The deck's nereid-apply and fail-closed slides stay planned: what tasks 6 and 7 print differs from them, and task 11's real output settles them. make scene-idp not run (the owner's word) |
alimede |
| 2026-11-16 | 9 (#1651) | Only who may authorization:bindings:create at a binding's node gives a member a position that binding names. Repository over plan: the check lives in the Nereus API (a route declares extra checks, position_checks in api/teams_routes.py), not in teams_service.py, since only the API knows the asker. Asked on a create and on an apply that changes the position or its User; taking a position away is not checked (it reduces access) |
alimede |
| 2026-11-16 | 7 (#1649) | A security review of the merged code: a listing whose answer has no items was answered unfiltered; it now fails closed with 500 Unfilterable (PR #1671) |
alimede |
| 2026-11-16 | 8 (#1650) | nereus authorization can-i and the shortcut nereus can-i, through POST /v1/authorization/can-i (one yes: line per granting binding, exit code 1 for no). A check that cannot run is a refusal, never a no: 409 NoDefaultMandate with no default Mandate of the reef, 503 when the Nereid is down. A security review: a question about yourself never tells whether a node exists (a missing node answers a plain no), and with --user nothing is looked up before the authorization:can-i:get gate passes. Left out: --team |
alimede |
| 2026-11-16 | milestone 2 | The slice is whole on main: the API asks, can-i, positions guarded, the profile installs both reefs |
alimede |
| 2026-11-16 | milestone 2 | Released v0.1.12 and deployed to k3d-nereus at cdd1fc1 (smoke test and nereus doctor pass) |
alimede |
| 2026-11-16 | 11 (#1652) | The final scene of teams and authorization (test/scene-authorization, steps 1 to 10 of the plan) and the walkthrough's real output. It caught four defects, each one local fix with a test, none for Fable: the chart's pods carried app.kubernetes.io/name=openfga, which the Nereid's own Service and NetworkPolicy select (nameOverride); a profile applied the authorization reef without its built-in administrator (authorization_service.built_ins on both paths); nereus database delete waited for a name its owner created again (wait_gone compares the uid); and nereus-mcp moves the issuer, so the scene signs in again. The API now logs why it refused a token. Task 10 had left the scene's counts at 13 Nereids |
alimede |
| 2026-11-16 | milestone 3 | Released v0.1.13 (main d83f6706, PR #1739) and deployed to k3d-nereus; the openfga Nereid moved to it with nereus nereid apply openfga --image ..., and its server's Deployment was recreated once for the new selector. The administrator has its own User and the binding owner-admin; can-i --user answers yes for the tech lead and no for the other member |
alimede |
| 2026-11-16 | decision 15 | The doctor's emergency-exit warned until the API restarted, also after the fix: four of nine uses came within the openfga Nereid's 5-second sync after owner-admin was created. It now names the last use and by whom, and warns only while that use is less than a day old (the owner's choice, not a Fable call) |
nemertes |
| 2026-11-16 | journey | Closed: the final scene passed, the slice runs on k3d-nereus, ADR 0027 is Accepted and openfga-controller is public on ghcr.io. A stale CLI commands cache after a restart hid nereus authorization until nereus reef list (#982) |
nemertes |