api: signed values at the store

PUT with application/continuum-signed writes an envelope where values
are signed (403/409 saying why); reads open envelopes and name the
signer (x-continuum-signed-by), ?raw=true shows them. Under strict,
unsigned writes reaching a signed value and the users API are 409.

Auth plan M7.

1 files changed, 30 insertions, 0 deletions

diff --git a/docs/api.md b/docs/api.md
index 5d94fac..92289bf 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -272,6 +272,36 @@ a second (SIGNATURES), to each peer that wasn't sent them yet.
 The signatures a node has are kept in its document file (`--document-file`) with the
 document.
 
+## Signed values
+
+Where the swarm has its users sign values ([`access.md`](access.md), Values signed by
+their users), a user writes one by signing it with its SSH key: the payload, one line
+of JSON, then the signature, as `application/continuum-signed`.
+
+```sh
+# The envelope there, if any, and what replaces it names: its SHA-256 (none: "").
+read=$(curl -sf -u alice -H 'Accept: text/plain' 'localhost:3000/store/config?raw=true')
+prev=${read:+$(printf %s "$read" | sha256sum | cut -d' ' -f1)}
+printf '{"path":["config"],"value":{"mode":"fast"},"user":"alice","at":%s,"prev":"%s"}' \
+  "$(date +%s000)" "$prev" > payload
+ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n continuum-value payload
+{ cat payload; echo; cat payload.sig; } | curl -X PUT localhost:3000/store/config \
+  -u alice -H 'Content-Type: application/continuum-signed' --data-binary @-
+```
+
+The node writes it as its envelope if the authenticated user signed it (`403` if not),
+for this path, with one of its keys, may write there (`403`), and it replaces what is
+there (`prev`, the SHA-256 of the envelope it replaces; `409` if it names another:
+read again and sign anew), and only where values are signed (`409` elsewhere). It
+answers with the value, as a `PUT` does; a signed `null` deletes, with `204`. Under
+the policy, every other write reaching a signed value, at it, within it or above it,
+is `409`, and so is the users API's.
+
+A read opens envelopes: each shows as the value it holds, a signed `null` as nothing,
+and a read of one names its signer (`x-continuum-signed-by`). `?raw=true` shows them as
+they are stored, envelopes, which anyone can check; so do typed JSON and native reads,
+and streams (`/stream`).
+
 ## Protocol data
 
 `_continuum` holds what the nodes coordinate through: the swarm ID, the member registry,