docs: reading keys and declarations

Clients checking signatures or sealing read the registry and
_continuum/access: operators grant reading them.

Auth plan M7, M8 (docs).

2 files changed, 20 insertions, 0 deletions

diff --git a/docs/access.md b/docs/access.md
index 4a0fd0e..83c39f9 100644
--- a/docs/access.md
+++ b/docs/access.md
@@ -277,6 +277,24 @@ over it, as `ssh-keygen -Y sign -n continuum-value` makes it, with one of its `k
 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:
+
+```sh
+curl -u alice -X POST -H 'Content-Type: application/json' \
+  --data '{"path": ["_continuum", "users"], "rights": ["read"]}' \
+  http://localhost:3000/admin/users/bob/caps
+curl -u alice -X POST -H 'Content-Type: application/json' \
+  --data '{"path": ["_continuum", "access"], "rights": ["read"]}' \
+  http://localhost:3000/admin/users/bob/caps
+```
+
+Under a strict policy, the same, as part of bob's entry, signed (`continuum-signed put
+_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
diff --git a/scripts/continuum-signed b/scripts/continuum-signed
index 4ce68db..dc5bd75 100755
--- a/scripts/continuum-signed
+++ b/scripts/continuum-signed
@@ -28,6 +28,8 @@
 #
 # `seal` seals for every key of each reader, as the registry has them; `open` opens with
 # CONTINUUM_KEY, which must then be the private key itself (age reads no agent).
+# `verify` and `seal` read the registry (`_continuum/users`) and the declarations
+# (`_continuum/access`): the user needs reading them (docs/access.md).
 # `verify` checks one level: the envelope against the user's keys as the node shows
 # the registry. The registry's entries are values signed by their users too; checking
 # them, and theirs, up to users one trusts, is `verify` again, on each.