access: signatures required

"signatures": "required": a change counts only once a signature by its
committer vouches for it, and waits until then; every node then signs
every change it makes.

Auth plan M6.

2 files changed, 11 insertions, 4 deletions

diff --git a/docs/access.md b/docs/access.md
index df8ad53..ba9caf1 100644
--- a/docs/access.md
+++ b/docs/access.md
@@ -192,6 +192,12 @@ revocation since refuses nothing it allowed then, and every node judges alike.
 * Everything else, protocol data or not, by a user the registry lets write there.
 * A node that isn't a member may only register itself.
 
+With `"signatures": "required"`, a change also needs a signature by the node it names
+([`api.md`](api.md), Signed changes): every node then signs every change it makes, and
+one no signature vouches for yet waits, with whatever builds on it, until one does
+(they come with the changes, or within a second on their own). A member can then no
+longer write as another member; the user a change names is still its node's word.
+
 In a swarm without a registry, whatever a user would need, any member may. A refused
 change stays out, and so does whatever builds on it; the node logs it (`Refused a
 change`) and lists the last thousand (`GET /admin/refused`). A change whose
@@ -199,9 +205,8 @@ dependencies haven't come yet waits for them.
 
 What it doesn't do yet:
 
-* **Prove who wrote it.** A change is its claimed node's and user's: a member could
-  claim another member, or a user its node doesn't have. Changes are signed
-  ([`api.md`](api.md), Signed changes), but the policy doesn't require it yet.
+* **Prove the user.** A change is its node's (with signatures required, proven) and its
+  claimed user's: a member could claim a user its operator doesn't have.
 * **Judge a joining node's first sync.** An empty document has no policy: what it gets
   from the node it joins through is taken as it is, as that node judged it.
 * **Agree at once.** The policy applies as each node gets it: a change received between
diff --git a/docs/api.md b/docs/api.md
index c2b9cb4..5d94fac 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -261,7 +261,9 @@ A change left unsigned, such as a metric written many times a second, is vouched
 by the node's next signed one: with `--sign-every 1s` (the default), the node signs its
 latest change at most a second after it if nothing signed it before, so every change is vouched
 for within a second, at one signature a second at most; `--sign-every all` signs every
-change as it is made, and `--sign-every none` signs only those above.
+change as it is made, and `--sign-every none` signs only those above. A swarm whose policy requires
+signatures ([`access.md`](access.md), Changes judged on every node) has every change
+signed as it is made, whatever `--sign-every` says.
 Signatures travel with sync messages: a node passes on, for each node's writes, the
 latest signature it checked, and checks one it receives once it holds the change (a
 signature costs about 30 µs to check, and one per node and run vouches for the rest).