summaryrefslogtreecommitdiffstats
path: root/docs/access.md
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-18 12:41:10 +0000
committertv <tv@krebsco.de>2026-11-18 13:42:58 +0100
commit0bfe07af92a775b0e896e0fc5a989a1d9b65f7b3 (patch)
treecd8d576ac13160163a2cee508cf985ef183b3a01 /docs/access.md
parentb0f0e1a9edb08b324df2ec5e97d15e7089349fdb (diff)
docs: references to a section of the same document linked to it
Where a document names one of its own sections in parentheses ("(What counts, 5)", "(Joining, below)"), the name links to the section by its GitHub-style ID; paragraphs that grew past the width are wrapped anew, links and code kept on one line each. References to another document's sections stay as they are.
Diffstat (limited to 'docs/access.md')
-rw-r--r--docs/access.md160
1 files changed, 82 insertions, 78 deletions
diff --git a/docs/access.md b/docs/access.md
index 71725e2..7c6c7e6 100644
--- a/docs/access.md
+++ b/docs/access.md
@@ -33,16 +33,16 @@ password hashes: every member reads the document).
doesn't read is left out, and anything but `false` disables.
* **`keys`**: the user's SSH keys, each by a name of its choosing, as an
`authorized_keys` line has it (`"laptop": "ssh-ed25519 AAAA… alice@laptop"`; Ed25519
- only; the comment, 256 bytes at most, is kept and checks nothing): what it signs values with (Values signed by their users, below) and logs in with. A user
- manages its own, whatever else it may do: `GET /auth/keys`, `PUT /auth/keys/<name>`
- with the line, `DELETE /auth/keys/<name>` (not with a token that has a `limit`); under a
- strict policy, by signing its
- entry with only its keys changed (`continuum-signed key-add laptop
- ~/.ssh/id_ed25519.pub`, `key-remove laptop`), with a key it holds already. Every
- node takes that from the user itself, as from one who may manage users. Its last key
- it removes only on a node where it has a password (`--htpasswd`), which it logs in
- by then (`409` elsewhere); under a strict policy, never (it signs its entry with
- one).
+ only; the comment, 256 bytes at most, is kept and checks nothing): what it signs values
+ with ([Values signed by their users](#values-signed-by-their-users), below) and logs in
+ with. A user manages its own, whatever else it may do: `GET /auth/keys`,
+ `PUT /auth/keys/<name>` with the line, `DELETE /auth/keys/<name>` (not with a token that
+ has a `limit`); under a strict policy, by signing its entry with only its keys changed
+ (`continuum-signed key-add laptop ~/.ssh/id_ed25519.pub`, `key-remove laptop`), with a
+ key it holds already. Every node takes that from the user itself, as from one who may
+ manage users. Its last key it removes only on a node where it has a password
+ (`--htpasswd`), which it logs in by then (`409` elsewhere); under a strict policy, never
+ (it signs its entry with one).
## A new swarm
@@ -52,16 +52,17 @@ everything (`[]` and `["_continuum"]`). Other users, of its `--htpasswd` or any
may do nothing until added (the genesis node warns of those of its `--htpasswd`). With
`--bootstrap-keys alice=ssh-ed25519\ AAAA…\ laptop` it records their keys too, so they
log in by key and sign values from the start, and with
-`--bootstrap-policy '{"version": 1, "values": "signed"}'` the policy (Values signed by
-their users, below) in the same change: the swarm is strict from its start, and no
-change of it is from before the policy. So it starts empty: content (`--genesis
---remake`) would be a change of its own before that one, and is refused with a strict
-policy; a swarm started from content turns strict through a strict remake (Turning a
-swarm strict, below).
-Without it, the swarm has no registry: its users are all alike (A swarm without a
-registry, below), until someone gives it one. `--protocol-writers` counts in
-both: without a registry, as who may write protocol data; with one, to set it right
-should nobody be left who may manage users (Keeping the swarm manageable, below).
+`--bootstrap-policy '{"version": 1, "values": "signed"}'` the policy
+([Values signed by their users](#values-signed-by-their-users), below) in the same change:
+the swarm is strict from its start, and no change of it is from before the policy. So it
+starts empty: content (`--genesis --remake`) would be a change of its own before that one,
+and is refused with a strict policy; a swarm started from content turns strict through a
+strict remake ([Turning a swarm strict](#turning-a-swarm-strict), below). Without it, the
+swarm has no registry: its users are all alike
+([A swarm without a registry](#a-swarm-without-a-registry), below), until someone gives it
+one. `--protocol-writers` counts in both: without a registry, as who may write protocol
+data; with one, to set it right should nobody be left who may manage users
+([Keeping the swarm manageable](#keeping-the-swarm-manageable), below).
## At the HTTP API
@@ -70,17 +71,17 @@ change to it counts on a node as soon as it has reached it.
* **The store** (`/store`, `/stream`): writing a path (`PUT`, `POST`, `DELETE`) takes
`write` on it, or, inside a list or text, on the list, as every node judges the
- change (a list's items have no paths of their own, Changes judged on every node,
- below); `?prune=true` deletes maps left empty only up to the highest one the
- user may write. Reading takes `read`: of a place the user may read only partly, it
- sees the keys on the way to what it may read, as a directory one may pass through
- but not list (a capability on `servers/eu` shows `servers` with `eu` alone in it),
- and nothing else; a list on the way is left out whole, as its items have no paths of
- their own. A shallow read (`?shallow=true`) shows such a map as a map and no more (no
- size), and nothing beside the way: a scalar at a `*` no capability covers stays
- hidden. Native forms (`text/plain` of a map, a counter as its own type) only of
- what it may read whole. What a write answers with is what was written. A stream
- shows what the user could read when it opened.
+ change (a list's items have no paths of their own,
+ [Changes judged on every node](#changes-judged-on-every-node), below); `?prune=true`
+ deletes maps left empty only up to the highest one the user may write. Reading takes
+ `read`: of a place the user may read only partly, it sees the keys on the way to what it
+ may read, as a directory one may pass through but not list (a capability on `servers/eu`
+ shows `servers` with `eu` alone in it), and nothing else; a list on the way is left out
+ whole, as its items have no paths of their own. A shallow read (`?shallow=true`) shows
+ such a map as a map and no more (no size), and nothing beside the way: a scalar at a `*`
+ no capability covers stays hidden. Native forms (`text/plain` of a map, a counter as its
+ own type) only of what it may read whole. What a write answers with is what was written.
+ A stream shows what the user could read when it opened.
* **Protocol data** is in the store too, under `_continuum`: `read` and `write` on it
as on any path.
* **Looking at the node** (`/admin/stats`, `GET /peers`, the dashboard): any user with
@@ -154,9 +155,9 @@ curl -H "Authorization: Bearer ct1.…" http://other-node:3000/store
write anything as anyone ([`trust.md`](trust.md)). A token is a bearer's: whoever holds it is
the user until it ends, so it goes over TLS only, as passwords do.
-A user with keys in its entry (`keys`, The registry, above) logs in on any node without
-a password: it asks for a challenge, signs it with one of its keys, and gets the same
-token (`login: "key"`).
+A user with keys in its entry (`keys`, [The registry](#the-registry), above) logs in on
+any node without a password: it asks for a challenge, signs it with one of its keys, and
+gets the same token (`login: "key"`).
```sh
c=$(curl -s -X POST localhost:3000/auth/challenge | jq -r .challenge)
@@ -292,9 +293,10 @@ stays as it is, wherever it comes from later (a joining node catching up, say).
* Everything else, protocol data or not, by a user the registry lets write there.
* A map made on the way to what a change writes, where there was none (`servers`, for a
first write at `servers/eu/0`), as what it writes within it.
-* A node that isn't a member may only register itself; a banned node nothing (Banning
- a node, below). So a node registers before anything else it writes, through the API
- or its own: a change refused stays out with every change built on it.
+* A node that isn't a member may only register itself; a banned node nothing
+ ([Banning a node](#banning-a-node), below). So a node registers before anything else it
+ writes, through the API or its own: a change refused stays out with every change built
+ on it.
A node judges each change it makes the same way before it leaves, its own writes and
those through the API alike: one every node would refuse is rolled back, never
@@ -422,7 +424,7 @@ A member's node signs its changes, but the user a change names is its node's wor
member could write as any user. A swarm can have its users sign the values that
matter themselves, with their SSH keys, so no member can write them but as a user
signed them: the policy's `"values": "signed"` (strict; it requires signatures too),
-given to its genesis node (A new swarm, above):
+given to its genesis node ([A new swarm](#a-new-swarm), above):
```sh
continuum --genesis --bootstrap-users alice \
@@ -448,10 +450,10 @@ it logs in by key, writes and deletes signed values (`put config '{"mode": "fast
and checks one against its user's keys (`verify config`).
What a client reads to check a signature, the signer's keys, is in the registry, and
-whom to seal for (Values sealed for their readers, below) in `_continuum/access`: both
-protocol data, which a user's capabilities cover only if given so. Neither holds
-secrets (every member holds the document), so give the users who check or seal reading
-them:
+whom to seal for ([Values sealed for their readers](#values-sealed-for-their-readers),
+below) in `_continuum/access`: both protocol data, which a user's capabilities cover only
+if given so. Neither holds secrets (every member holds the document), so give the users
+who check or seal reading them:
```sh
curl -u alice -X POST -H 'Content-Type: application/json' \
@@ -468,40 +470,40 @@ _continuum/users/bob '{…}'`).
A node takes one only from that user, for that path, replacing what is there, by one of
the user's keys, and if the user may write there ([`api.md`](api.md), Signed values); it
writes nothing else there, nor within or above such a value (`409`), and the users API
-changes nothing (`409`). A swarm turns strict only at its start (`--bootstrap-policy`, A
-new swarm, above) or through a remake (Turning a swarm strict, below), which keeps only
-what an operator looked over: each is its epoch's first change, so no change of a strict
-epoch is from before its policy. A change writing a strict policy where the policy isn't
-strict is refused; and a policy reads strict only where its `values` is a string, as
-continuum writes it: one that would read strict only through an Automerge text is one no
-node knows, never what its characters spell. A strict swarm stays strict: its policy is written again only
-as strict, never relaxed nor deleted, nor moved to a policy its nodes don't know (a node
-that doesn't know a policy reads it as none it can judge by); to leave it, start a new
-swarm from its content (A new swarm, above). A value there that isn't an envelope starts
-its chain anew: any envelope its user once signed for that path replacing nothing
-(`prev` empty) can be put there again. Without the policy, signed values may be written
-all the same, and plain ones too.
+changes nothing (`409`). A swarm turns strict only at its start (`--bootstrap-policy`,
+[A new swarm](#a-new-swarm), above) or through a remake
+([Turning a swarm strict](#turning-a-swarm-strict), below), which keeps only what an
+operator looked over: each is its epoch's first change, so no change of a strict epoch is
+from before its policy. A change writing a strict policy where the policy isn't strict is
+refused; and a policy reads strict only where its `values` is a string, as continuum
+writes it: one that would read strict only through an Automerge text is one no node knows,
+never what its characters spell. A strict swarm stays strict: its policy is written again
+only as strict, never relaxed nor deleted, nor moved to a policy its nodes don't know (a
+node that doesn't know a policy reads it as none it can judge by); to leave it, start a
+new swarm from its content ([A new swarm](#a-new-swarm), above). A value there that isn't
+an envelope starts its chain anew: any envelope its user once signed for that path
+replacing nothing (`prev` empty) can be put there again. Without the policy, signed values
+may be written all the same, and plain ones too.
Keep two users who may manage users, or two keys each: under a strict policy, a
registry whose only manager lost its keys changes no more (the protocol writers do
everything there again only while nobody may manage users).
-Every node judges the changes it receives alike (Changes judged on every node, above),
-as their writer saw the registry: at such a place, only a string that is an envelope
-that checks, replacing the one there then; nothing within one; and above one, nothing
-replacing or deleting what holds one (a map made where there is none yet is fine). So
-a member writing to its document directly gets nothing there past the others: the
-registry, the policy and the bans change only as a user who may change them signed.
-But "may" is read where a change was written, which its writer chooses: a capability
-revoked, a user disabled or a key removed holds against members that weren't members
-before it, not against one that was, with a user that could sign then. That member can
-commit, at a history from before, an envelope the user signed then, numbered after what
-was there then, and the next after it, as far as it likes; the place's value is then
-the one with the highest `seq`. A remake ends it: nothing is written at a history from
-before the new epoch.
-A remake is outside this: its snapshot is the quorum's, so a `replace` or `import`
-remake a majority of members commits writes at signed places whatever its content
-holds, plain values too.
+Every node judges the changes it receives alike
+([Changes judged on every node](#changes-judged-on-every-node), above), as their writer
+saw the registry: at such a place, only a string that is an envelope that checks,
+replacing the one there then; nothing within one; and above one, nothing replacing or
+deleting what holds one (a map made where there is none yet is fine). So a member writing
+to its document directly gets nothing there past the others: the registry, the policy and
+the bans change only as a user who may change them signed. But "may" is read where a
+change was written, which its writer chooses: a capability revoked, a user disabled or a
+key removed holds against members that weren't members before it, not against one that
+was, with a user that could sign then. That member can commit, at a history from before,
+an envelope the user signed then, numbered after what was there then, and the next after
+it, as far as it likes; the place's value is then the one with the highest `seq`. A remake
+ends it: nothing is written at a history from before the new epoch. A remake is outside
+this: its snapshot is the quorum's, so a `replace` or `import` remake a majority of
+members commits writes at signed places whatever its content holds, plain values too.
### Turning a swarm strict
@@ -546,9 +548,10 @@ writing `_continuum/remakes`.
## Values sealed for their readers
Anyone may read the whole document: every member holds it. A value only some may read
-is sealed for them: encrypted with age to their SSH keys (`keys`, The registry,
-above), so only they open it. Every node syncs, stores and remakes it as the string it
-is, and none decrypts it: `cs1.<the age file, base64url>` (binary, not armored).
+is sealed for them: encrypted with age to their SSH keys (`keys`,
+[The registry](#the-registry), above), so only they open it. Every node syncs, stores and
+remakes it as the string it is, and none decrypts it: `cs1.<the age file, base64url>`
+(binary, not armored).
```sh
jq -r '.keys[]' <(curl -s -u alice localhost:3000/store/_continuum/users/bob) > readers
@@ -570,10 +573,11 @@ exactly their keys, as the registry has them when it is written. A node tells wi
decrypting: an age file names each `ssh-ed25519` recipient by a tag, the first four
bytes of the SHA-256 of its key. A write leaving a value there plain, or sealed for a
reader's key too few or a stranger's too many, is refused (`409`), and with the policy
-every node refuses such a change on receipt (Changes judged on every node, above). A
-value signed by its user (Values signed by their users) holds the sealed value; the
-signature is over the ciphertext, so every node checks who wrote it without reading
-it.
+every node refuses such a change on receipt
+([Changes judged on every node](#changes-judged-on-every-node), above). A value signed by
+its user ([Values signed by their users](#values-signed-by-their-users)) holds the sealed
+value; the signature is over the ciphertext, so every node checks who wrote it without
+reading it.
`scripts/continuum-signed` seals and opens them too, with age: `seal secrets/db
'{"password": "…"}'` seals for the readers declared there (or `CONTINUUM_READERS`),