0011. Reefs, Nereids and Mandates, managed with top-level commands¶
In short
Reefs, Nereids and Mandates are managed with top-level commands, with --reef and --nereid as the flags everywhere; a Mandate binds one reef to one Nereid. Status: Proposed (2026-10-17, rewritten 2026-10-25).
Status: Proposed (2026-10-17, rewritten 2026-10-25)
Context¶
The model's words changed twice. The first ADRs said Concept and Controller; the Lean Inception of #79 changed them to Interface and Implementation, managed under a platform system group, with an Implementation installed into an Interface and one active Instance per Interface. The owner's voice sessions of 2026-10-25 reviewed the CLI command by command on the MVP's journey (secrets first, then authentication with two identity brokers side by side) and found:
- A capability and whoever fulfils it are different things: a reef can exist with no Nereid, and one controller can look after several reefs, as in Kubernetes. Nesting the Nereid under the reef is wrong.
- A Tool's credentials repeated in every Class or Instance are wrong: they belong to the controller's installation, as a StorageClass's provisioner holds them.
- A secret travelling in plain text inside the platform can be captured in logs, even over HTTPS.
Decision¶
Words. A reef is the contract of a capability, an API group (ADR 0009); a Nereid fulfils one or more reefs; a Mandate binds one reef to one Nereid (ADR 0002). Controller stays the mechanism, in ADRs and code: each Nereid runs as a Kubernetes controller that reconciles and writes status (ADR 0005). Instance, Tool and Vendor keep their meaning from ADR 0002.
Commands that change the platform are top-level nouns, with --reef and --nereid as the flags everywhere:
nereus reef list
nereus reef apply authentication --from-file ./reefs/authentication/
nereus nereid suggest --reef authentication
nereus nereid apply keycloak \
--reef authentication
nereus nereid apply sao \
--reef authentication \
--image ghcr.io/getnereus/nereus/authentication-auth0-controller:0.1.0
nereus mandate create corporate \
--reef authentication \
--nereid keycloak \
--default
nereus status
- Nereid names are global to the platform and free: the Tool's name or a name from the myth, suggested by
nereus nereid suggest.--reefrepeats when one Nereid looks after several reefs. --imagenames an image other than the one the CLI pins for that name.nereus statusshows the mechanism: one row per reef and Nereid pair, columnsREEF,NEREID,VERSION,STATUS,AGE.nereus nereid listshows the Nereids: one row per Nereid, columnsNEREID,REEFS,IMAGE,STATUS,AGE;nereus nereid get <nereid>adds the image's title, description and digest.--paramis the only flag for parameters (no--set), and--reefthe only flag naming a reef (no--implements).
$ nereus status
REEF NEREID VERSION STATUS AGE
authentication keycloak 0.1.0 Ready 3m
sao 0.1.0 Ready 3m
core built-in 0.1.0 Ready 38m
secrets azure-key-vault 0.1.0 Ready 8m
$ nereus nereid list
NEREID REEFS IMAGE STATUS AGE
azure-key-vault secrets ghcr.io/getnereus/nereus/secrets-azure-key-vault-controller:0.1.0 Ready 8m
keycloak authentication ghcr.io/getnereus/nereus/authentication-keycloak-controller:0.1.0 Ready 3m
sao authentication ghcr.io/getnereus/nereus/authentication-auth0-controller:0.1.0 Ready 3m
The kinds and their fields, in core.getnereus.dev/v1alpha1 (ADR 0009): Reef.spec holds the contract (API group, version, commands); Nereid.spec.reefs (a list), Nereid.spec.image and Nereid.spec.params (authentication and default target parameters); Mandate.spec.reef, Mandate.spec.nereid, Mandate.spec.params (overrides) and Mandate.spec.default. A reef's own objects key their entries by reef (reef: in a Cloud access entry). Today's names (spec.interface, interface:) are current code, to be renamed.
Where parameters live.
- The Nereid owns its authentication and its default target parameters, set once at
nereid apply(authentication=workload-identity, a defaultvaultUrl). A Nereid may serve several targets (several vaults). The first secrets Nereid, its default Mandatevaultand the Mandate's RSA key are made bynereus init(ADR 0003), never by the person. - The Mandate may override the target parameters with
--paramand adds the parameters of its own choice (identityProvider,credentials=secret:<name>); the common case needs only--reefand--nereid. - An Instance's fields are generic: fields the reef defines, common to its Nereids. A Nereid ignores what it does not use and says so in
status. What one Nereid needs and the others lack becomes a new common field of the reef, never a Nereid-specific kind.
A reef's contract may require capabilities of every Nereid. The secrets reef requires client-side encryption: every secrets Nereid publishes a public key for each Mandate naming it and decrypts inside its own boundary, and the CLI encrypts each secret before sending it, with envelope encryption (an AES-256-GCM data key encrypts the value; the Mandate's RSA-OAEP-256 public key wraps the data key). The key belongs to the Mandate, not to the reef or the Nereid: a Mandate picks the target vault, and a Nereid may serve several vaults through its params. nereus secrets apply encrypts with the key of the Mandate it targets, the reef's default one unless a Mandate is named. The CLI stays provider-agnostic; only the Nereid differs:
| Nereid | The private key |
|---|---|
Azure Key Vault (--target azure) |
a non-exportable RSA key in Key Vault; the Nereid calls Key Vault to decrypt |
| OpenBao, local k3d with no target | a non-exportable RSA key of the Transit engine (rsa-4096, exportable and allow_plaintext_backup false; reading the key returns its public key); the Nereid calls Transit to decrypt, which uses OAEP with SHA-256 for the hash and MGF1 (RSA-OAEP-256), checked against OpenBao 2.7.1 |
| fallback, a Nereid with no vault | Sealed Secrets style: the private key in a cluster Secret |
$ nereus secrets apply google-sso --from-file google-sso.json
encrypted locally with the public key of mandate vault (envelope: AES-256-GCM + RSA-OAEP-256)
secret/google-sso stored by nereid azure-key-vault (2 keys, values hidden)
Log redaction stays, whatever the encryption.
Repositories and images: one per Nereid's Tool, named <reef>-<tool>-controller (secrets-azure-key-vault-controller, authentication-keycloak-controller); the image is ghcr.io/getnereus/nereus/<reef>-<tool>-controller while the monorepo holds them.
Prior art¶
- The Lean Inception (Paulo Caroli) (martinfowler.com): the workshop of #79 that first exercised the model on the MVP's journey.
- Kubernetes storage classes (StorageClass): the provisioner holds the credentials and the class selects the target with parameters; the Nereid and the Mandate split them the same way.
- Sealed Secrets (Bitnami) (github.com/bitnami-labs/sealed-secrets): the controller holds the private key, and
kubesealencrypts on the client with its public certificate; the secrets reef's contract takes the same shape, and the fallback Nereid the same storage of the key. - OpenBao's Transit secrets engine (openbao.org, API): encryption as a service, with RSA keys (
rsa-2048,rsa-3072,rsa-4096), keys not exportable by default and adecryptendpoint; the local secrets Nereid decrypts through it.
Consequences¶
- ADR 0002's words changed for people: reef, Nereid, Mandate. The legacy
platform system interface ...,platform system install ...andplatform system interface use ...map tonereus reef ...,nereus nereid apply ...andnereus mandate create ... --default(docs/agent/cli.md). - No secret value crosses the platform in plain text: the API, the logs and the cluster see only the envelope, until the Nereid writes it to its vault.
- The reef's schema must be designed for every Nereid it expects, at the risk of a lowest common denominator; new common fields are the way out.
- The code still names Interface and Implementation; renaming it is a change of its own.
Open questions¶
- Published (#404): the Nereid writes the key in its Mandate's
status.publicKey(pem,algorithm,fingerprint,version, and where the vault keeps it,storage);versiongrows by one each time the key changes, andstorage: memorysays the vault keeps nothing across a restart (OpenBao in dev mode). Until the API exists, the CLI reads it through the kubeconfig, so the trust is the cluster's TLS and RBAC, andnereus initprints the fingerprint. - How the key is rotated, and how the CLI pins it (trust on first use, with
nereus secrets apply) (open).
Rewritten 2026-10-25 from voice session; raw data in Drive #pontos/raw/2026-10-25. Rewritten again 2026-10-25 (order 20261025-1724): init makes the first secrets Nereid and its Mandate; OpenBao Transit keys are non-exportable; "Mandate" is the working term. Rewritten again 2026-10-25 (order 20261025-1805): nereid list and status columns, --param and --reef as the only flags. Rewritten again 2026-10-25 (order 20261025-1812): the fields of the kinds, and nereid get. Rewritten again 2026-10-25 (order 20261025-2158): the public key is the Mandate's, published in its status, and its OAEP hash.