access: authorization at the API

Every request is judged by the registry the node holds: store reads
pruned to what the user may read, writes refused where it may not,
admin endpoints by protocol capabilities. Without a registry, as
before (--protocol-writers for protocol data).

Auth plan M1.

1 files changed, 11 insertions, 7 deletions

diff --git a/docs/trust.md b/docs/trust.md
index 4435f99..bcf9bc7 100644
--- a/docs/trust.md
+++ b/docs/trust.md
@@ -40,12 +40,12 @@ requests from there can be any user. With the default loopback addresses, that i
 user of the host; with only the API's Unix socket (`--trusted-proxies unix`), those its
 file's permissions let in: the node's user and group ([`operations.md`](operations.md), Behind a
 reverse proxy). It listens on `127.0.0.1:3000` by default (`--bind-addr`) and speaks
-plain HTTP: to expose it, put a TLS proxy in front. All users may read and write user
-data and use the admin endpoints (remakes, forgetting peers, exports, log filters).
-There are no read-only users: whoever may open the dashboard may also edit and delete
-the document's data from it, and its writes reach the whole swarm.
-Only the users in `--protocol-writers` may write protocol data through the store; epoch
-metadata and the swarm ID are never writable. The `/debug` endpoints exist only with
+plain HTTP: to expose it, put a TLS proxy in front. What each user may do is the
+swarm's: its user registry, in the document, gives each capabilities by path, to read
+and to write, protocol data apart ([`access.md`](access.md)); a user the registry doesn't have
+may do nothing. In a swarm without a registry (one from before it), all users may read
+and write user data and use the admin endpoints, and only those in `--protocol-writers`
+write protocol data. Epoch metadata and the swarm ID are never writable. The `/debug` endpoints exist only with
 `--debug-api`.
 
 **The configuration.** Whoever can write a node's configuration file or its options can
@@ -65,6 +65,9 @@ node acts on what the document says:
 * **The member registry**: each node writes its own entry, but nothing stops a member
   from writing others'. The registry decides the topology and, through the alive
   stamps, the electorate of a remake.
+* **The user registry**: written through the API only by users given protocol data,
+  but a member can write any entry into its own document, and every node then serves
+  users as it says; the checks at the API bind honest nodes only.
 * **Forget records**: any member can make the swarm forget a peer (until it says HELLO
   again).
 * **Remakes**: any member can propose one, vote, and, as coordinator, decide. Votes
@@ -114,7 +117,8 @@ Not against a hostile member, but against honest ones getting in each other's wa
   ([`remakes.md`](remakes.md)).
 * A snapshot every node builds itself and checks against the committed epoch, and
   downloads checked against their hashes.
-* Protocol data writable through the API only by `--protocol-writers`, and logged.
+* Protocol data writable through the API only by users given it ([`access.md`](access.md)), or
+  in a swarm without a registry by `--protocol-writers`, and logged.
 
 ## Not yet