docs: fix genuine passive-voice hits in docs/swarm
Read all 94 write-good.Passive hits across docs/swarm/ (ca.md, README.md, secrets.md, services.md, sso.md, ui.md) in context. 44 are genuine catches with a nameable, usually already-established actor (swarm-controller, authelia, swarmctl, the controller, the gateway, this module, hyperhive itself, or 'the operator' for manual actions) — rewritten to active. 50 are legitimate passives or false catches, left alone: predicate-adjective state descriptions (is expected/misconfigured/ broken), negative-capability idioms (no X is needed/placed, can't be Yed/listed/fetched), config-state conditionals (whenever/when X is enabled/configured/set), requirement-list labels (is required), 'is tracked as' idiom, backward-looking changelog facts with no actor (was removed/verified/introduced), ambiguous-actor statements left conservatively alone (agents are created and destroyed — could be hive-c0re or swarm-controller, doc doesn't say), and a couple of deliberately-parallel idiom pairs. Several sibling-inconsistency fixes: a passive clause sitting next to an already-active sibling describing the same fact/mechanism (ca.md's two-bullet consumer list, README's 4-item WireGuard-mesh bullet list, README's controller-registers-hooks paragraph, sso.md's followed-a-302 sentence). Verified via vale on the whole directory, diffed against main's exact baseline (not just the Passive count): write-good.Passive 94 -> 50 exactly, every other category unchanged (1 pre-existing Microsoft.Contractions error at services... at secrets.md:182, 8 TooWordy, 1 Microsoft.We, 1 Microsoft.FirstPerson — same counts, same locations).
This commit is contained in:
parent
e9d59f3d10
commit
fab2a0dedc
6 changed files with 79 additions and 78 deletions
|
|
@ -5,7 +5,7 @@ provider** every protected vhost checks (`auth_request`), and — once any
|
|||
client is declared — an **OIDC provider** issuing tokens to relying
|
||||
parties: the forge and the matrix homeserver.
|
||||
|
||||
The second role is derived rather than switched:
|
||||
The second role derives rather than switches:
|
||||
`services.hyperhive.swarm.authelia.oidc.clients` being non-empty turns it
|
||||
on. authelia refuses to start with a provider that has no clients, so a
|
||||
separate `enable` would be a second fact free to disagree with the first.
|
||||
|
|
@ -18,10 +18,10 @@ name all follow `deploy.authelia`, so there is nothing to turn on
|
|||
separately. (Details, including why a client hive must not declare that
|
||||
vhost: [`../networking/gateway.md`](../networking/gateway.md).)
|
||||
|
||||
**Authelia doesn't start until at least one user exists.** The user
|
||||
store is generated empty — deliberately, since seeding a default account
|
||||
would put a credential in a config file — but authelia validates it at
|
||||
startup and treats "no users" as fatal:
|
||||
**Authelia doesn't start until at least one user exists.** This module
|
||||
generates the user store empty — deliberately, since seeding a default
|
||||
account would put a credential in a config file — but authelia validates
|
||||
it at startup and treats "no users" as fatal:
|
||||
|
||||
```
|
||||
error reading the authentication database: could not validate the schema:
|
||||
|
|
@ -47,8 +47,8 @@ password: <generated>
|
|||
this password is stored nowhere — record it now
|
||||
```
|
||||
|
||||
The password is generated, hashed, and printed once; only the hash is
|
||||
kept. `swarmctl` reads and writes authelia's `users.yml` directly — it's
|
||||
`swarmctl` generates, hashes, and prints the password once, keeping only
|
||||
the hash. It reads and writes authelia's `users.yml` directly — it's
|
||||
the one user store, shared with `swarm-authelia-bridge`, which creates
|
||||
agent identities in the same file. No restart: authelia watches it. Full
|
||||
reference: [`../tools/swarmctl-cli.md`](../tools/swarmctl-cli.md).
|
||||
|
|
@ -84,7 +84,7 @@ Two behaviours worth knowing before you rely on them:
|
|||
already was. Revocation is the exception on purpose: a typo'd group
|
||||
name that reported success would leave an account holding access you
|
||||
believe you took away, and that's the one outcome nobody re-checks.
|
||||
- **The resulting group list is printed** because group names have no
|
||||
- **`swarmctl` prints the resulting group list** because group names have no
|
||||
registry anywhere. A misspelled `--add-group` creates a real group that
|
||||
no access-control rule mentions, so the user gains nothing and no error
|
||||
is possible — reading the line back is the only check there is.
|
||||
|
|
@ -115,8 +115,8 @@ authelia's first boot to mint that client's secret and copies it into the
|
|||
service's container, and the service's own module contributes its client
|
||||
entry — callback URL included — to authelia's client list.
|
||||
|
||||
The callback is built once and read twice, so the redirect URI authelia is
|
||||
told to allow and the one the service actually sends can't drift apart. A
|
||||
The callback is built once and read twice, so the redirect URI authelia
|
||||
accepts and the one the service actually sends can't drift apart. A
|
||||
mismatch there is a rejected login with no error text worth reading.
|
||||
|
||||
⚠️ The delivery is a copy, not a `bindMounts` entry, and deliberately so:
|
||||
|
|
@ -147,7 +147,7 @@ services.hyperhive.swarm = {
|
|||
};
|
||||
```
|
||||
|
||||
**Both are asserted at eval.** A hive that boots with SSO
|
||||
**This module asserts both at eval.** A hive that boots with SSO
|
||||
half-configured shows a login button that always fails — a symptom
|
||||
many layers from its cause, and far worse to diagnose than an
|
||||
evaluation error.
|
||||
|
|
@ -173,9 +173,9 @@ Two consequences worth stating plainly:
|
|||
host-side ownership arrangement to maintain.
|
||||
- **Matrix SSO lives inside the homeserver.** The client-server API is
|
||||
spoken by non-browser clients holding matrix access tokens — every
|
||||
agent's own daemon — as well as by federation, so `/_matrix/` is served
|
||||
directly and authenticates itself. The forward-auth vhosts protect
|
||||
browser surfaces; this isn't one of them.
|
||||
agent's own daemon — as well as by federation, so the homeserver
|
||||
serves `/_matrix/` directly and authenticates it itself. The
|
||||
forward-auth vhosts protect browser surfaces; this isn't one of them.
|
||||
|
||||
## Machine clients
|
||||
|
||||
|
|
@ -197,7 +197,7 @@ thing to keep in step, and it drifts silently — a mismatch presents as a
|
|||
valid token refused at the target, which reads like a broken credential
|
||||
rather than a broken name.
|
||||
|
||||
**Tokens are signed (`RS256`), not opaque**, because a resource server
|
||||
**Authelia signs tokens (`RS256`), not opaque ones**, because a resource server
|
||||
that can't call the provider back is a real case here: the telemetry
|
||||
collector verifies offline against `/jwks.json`, and an opaque token gives
|
||||
it nothing to verify. The queue's responder introspects instead — a
|
||||
|
|
@ -218,15 +218,15 @@ HTML instead of the failure that actually happened:
|
|||
- `/api/oidc/token`, `/.well-known/openid-configuration` — a client
|
||||
parsing an error page as its JSON document
|
||||
|
||||
Authelia's `/api/` and `/.well-known/` prefixes are routed **without**
|
||||
error interception. The split is by _audience_, not by an enumerated path
|
||||
The gateway routes authelia's `/api/` and `/.well-known/` prefixes
|
||||
**without** error interception. The split is by _audience_, not by an enumerated path
|
||||
list: a human gets the page, every machine caller gets the status.
|
||||
Enumerating endpoints individually would leave the next one added
|
||||
silently intercepted.
|
||||
|
||||
The same shape bites any machine route behind a browser-shaped gate: a
|
||||
`302` to a login page is followed, the login page answers `200`, and the
|
||||
caller reports success while nothing happened. Log ingest hit exactly this
|
||||
The same shape bites any machine route behind a browser-shaped gate: the
|
||||
caller follows a `302` to a login page, the login page answers `200`,
|
||||
and the caller reports success while nothing happened. Log ingest hit exactly this
|
||||
and lost eleven hours of delivery in silence.
|
||||
|
||||
**Checking it, if you change this routing.** Point the vhost at a dead
|
||||
|
|
|
|||
Loading…
Reference in a new issue