1 files changed, 32 insertions, 0 deletions
diff --git a/docs/access.md b/docs/access.md
index 682b22b..0366e26 100644
--- a/docs/access.md
+++ b/docs/access.md
@@ -29,6 +29,9 @@ password hashes: every member reads the document).
 * **`disabled`**: the entry stays (who wrote what stays readable), and gives nothing.
   An entry that doesn't read as above gives less, never more: a capability that
   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…"`; Ed25519 only): what
+  it signs values with (Values signed by their users, below).
 
 ## A new swarm
 
@@ -231,3 +234,32 @@ curl -X PUT localhost:3000/store/_continuum/banned/<node ID> \
   -H 'Content-Type: application/json' -d '{"by": "alice", "reason": "compromised"}'
 ```
 
+## Values signed by their users
+
+A member's node signs its changes, but the user a change names is its node's word: a
+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).
+
+```sh
+curl -X PUT localhost:3000/store/_continuum/access/policy \
+  -H 'Content-Type: application/json' -d '{"version": 1, "values": "signed"}'
+```
+
+Signed then are what decides who may do what (every user's entry, every entry of
+`_continuum/access`, every ban), and the paths listed at `_continuum/access/userSigned`,
+a list of paths as capabilities name them, `*` for any one key:
+`[["config"], ["servers", "*", "secret"]]`. Each such value is an envelope, one string
+(`cv1.<payload>.<signature>`): the payload names the path, the value (`null`: deleted),
+the user, when, and the envelope it replaces (`prev`), and the signature is the user's
+over it, as `ssh-keygen -Y sign -n continuum-value` makes it, with one of its `keys`.
+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`). Values there before the policy stay as they are until
+replaced: a registry whose entries hold the users' keys turns strict as it is. Without
+the policy, signed values may be written all the same, and plain ones too.
+
+What it doesn't do yet: **judge signed values on receipt.** Each node checks the
+values its users write through it; a member writing to its document directly could
+still write there.