vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

docs: clear write-good.Passive hits in docs/swarm/credentials.md

Browse source 
6 genuine passive-voice rewrites (actor named or replaced with an
active construction); 7 false positives left untouched — the
design-intent 'is meant to have' idiom, and the six identical
'must be stated' renewal-column table cells (a deliberate terse
placeholder directive, not a describable action with an actor).
This commit is contained in:
iris 2026-09-20 04:15:07 +02:00 • committed by mara
commit 69b70a9c6f
1 changed files with 12 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

24
docs/swarm/credentials.md
View file

@ -6,9 +6,9 @@ credential is meant to have — who mints it, who reads it, and how it renews
the files that exist right now; this page replaces it, and `secrets.md` gets the files that exist right now; this page replaces it, and `secrets.md` gets
deleted, once the swarm's credential path matches what's described below. deleted, once the swarm's credential path matches what's described below.
**Public material is a value.** A certificate or a public nkey is handed to **Public material is a value.** The store hands a certificate or a public
every client that connects, so the store is a fine place for it. Nothing nkey to every client that connects, so it's a fine place for that material.
below is about those. Nothing below is about those.
**No secret the store holds is ever written to disk.** That's the invariant, **No secret the store holds is ever written to disk.** That's the invariant,
and everything else in this page follows from it. A value pulled from the and everything else in this page follows from it. A value pulled from the
@ -21,7 +21,7 @@ plus one file per identity.
**Those files are mTLS client certificates, one per identity, and they're **Those files are mTLS client certificates, one per identity, and they're
the only credential on disk.** Each has to be a file, and the reason is the the only credential on disk.** Each has to be a file, and the reason is the
whole asymmetry: the certificate is what authenticates a principal to the whole asymmetry: the certificate is what authenticates a principal to the
store, so it's the one credential that can't be fetched from the store. store, so it's the one credential nothing can fetch from the store.
Something has to exist on disk before the first request, or there's nothing Something has to exist on disk before the first request, or there's nothing
to make the request with. Every identity — an agent, a hive, a swarm-level to make the request with. Every identity — an agent, a hive, a swarm-level
service — needs one; a host running several holds several, and its only service — needs one; a host running several holds several, and its only
@ -32,8 +32,8 @@ value."_ A literal in a nix expression lands in the nix store —
world-readable and permanent — so that option takes a path to the world-readable and permanent — so that option takes a path to the
certificate on disk, never the certificate's bytes. certificate on disk, never the certificate's bytes.
**The hive hands an agent an identity, never a secret.** An agent container **The hive hands an agent an identity, never a secret.** Its hive passes an
is passed an mTLS certificate from its hive and from then on authenticates agent container an mTLS certificate, and from then on the agent authenticates
to the store under its own name, pulling what it needs when it needs it. No to the store under its own name, pulling what it needs when it needs it. No
process reads a secret on another principal's behalf: the principal that process reads a secret on another principal's behalf: the principal that
needs a value is the principal that authenticates for it. needs a value is the principal that authenticates for it.
@ -60,8 +60,8 @@ strategy for every credential, including the mTLS leaf.
**An agent's mTLS leaf is in the store; a hive's isn't, and the difference **An agent's mTLS leaf is in the store; a hive's isn't, and the difference
isn't an inconsistency.** The rule the exception protects is that nothing isn't an inconsistency.** The rule the exception protects is that nothing
can fetch from the store the credential it would need in order to fetch. A can fetch from the store the credential it would need in order to fetch. A
hive's leaf is that credential, so it can only come off disk. An agent's is hive's leaf is that credential, so it can only come off disk. The _hive_,
read by the _hive_, which already holds one — so publishing it costs nothing which already holds one, reads an agent's — so publishing it costs nothing
and buys the property this page asks for: the swarm mints it, the hive only and buys the property this page asks for: the swarm mints it, the hive only
carries it, and no hive ever needs the capability to mint an identity. carries it, and no hive ever needs the capability to mint an identity.
`swarm-controller` proves the leaf it publishes before the creation job `swarm-controller` proves the leaf it publishes before the creation job
@ -91,8 +91,8 @@ agent that believes it reaches the store and never does.
## Progressive enhancement ## Progressive enhancement
New functionality has to match this shape immediately — no PR introducing a New functionality has to match this shape immediately — no PR introducing a
credential gets a pass on any of the rules below. Existing functionality can credential gets a pass on any of the rules below. A PR can move existing
be moved step by step, as long as each individual step moves toward the functionality step by step, as long as each individual step moves toward the
target shape; a step that doesn't isn't allowed just because it's existing. target shape; a step that doesn't isn't allowed just because it's existing.
A pull request that touches a credential can't: A pull request that touches a credential can't:
@ -109,6 +109,6 @@ A pull request that touches a credential can't:
the store the store
While the swarm's credential path is still moving to this shape, a PR that While the swarm's credential path is still moving to this shape, a PR that
moves a secret into bao is allowed to leave its renewal strategy unresolved, moves a secret into bao may leave its renewal strategy unresolved, provided
provided it opens a follow-up issue to settle renewal. That's a migration-era it opens a follow-up issue to settle renewal. That's a migration-era
allowance, not a standing exception to the renewal-strategy rule above. allowance, not a standing exception to the renewal-strategy rule above.