access: bans

_continuum/banned/<node ID>: every node refuses the banned node's
changes from then on (judged as the ban stood) and leaves its
handshakes unanswered.

Auth plan M6.

1 files changed, 16 insertions, 1 deletions

diff --git a/docs/access.md b/docs/access.md
index ba9caf1..3818b04 100644
--- a/docs/access.md
+++ b/docs/access.md
@@ -190,7 +190,8 @@ revocation since refuses nothing it allowed then, and every node judges alike.
   any member.
 * A user's tokens revoked by that user too (logging out).
 * 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.
+* A node that isn't a member may only register itself; a banned node nothing (Banning
+  a node, below).
 
 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
@@ -216,3 +217,17 @@ What it doesn't do yet:
 A node that doesn't know the policy (another version, or a setting it lacks) takes no
 writes through the API (`409`) and receives without judging, until it is upgraded.
 
+## Banning a node
+
+A node can be banned: `_continuum/banned/<node ID>`, written by a user who may write
+there (protocol data). Every node then leaves its handshakes unanswered, so it is
+neither synced with nor counted a member, and with the policy every node refuses the
+changes it commits from then on, judged as the ban stood when they were made (what it
+wrote before stays). Deleting the entry lifts the ban. A ban doesn't remove the node
+from the member list: forget it too (`DELETE /peers/<node ID>`).
+
+```sh
+curl -X PUT localhost:3000/store/_continuum/banned/<node ID> \
+  -H 'Content-Type: application/json' -d '{"by": "alice", "reason": "compromised"}'
+```
+