access first usersauth

2 files changed, 48 insertions, 0 deletions

diff --git a/docs/access.md b/docs/access.md
new file mode 100644
index 0000000..8cb1ef9
--- /dev/null
+++ b/docs/access.md
@@ -0,0 +1,42 @@
+# Users and what they may do
+
+Who the users are, and what each may do, is the swarm's: a registry in the document,
+the same on every node. How a user proves who it is stays each node's: its
+`--htpasswd`, or a reverse proxy naming the user (`--user-header`, [`trust.md`](trust.md)).
+
+## The registry
+
+`_continuum/users/<name>`, one entry per user. It is protocol data: every member holds
+it, a remake's snapshot carries it into the next epoch, and it holds no secrets (no
+password hashes: every member reads the document).
+
+```json
+{ "since": 1762400000000, "by": "continuum:3f…",
+  "caps": { "8c41e2…": { "path": [], "rights": ["read", "write"],
+                        "by": "continuum:3f…", "since": 1762400000000 } },
+  "disabled": false }
+```
+
+* **Names** are what `--htpasswd` and the proxy give: 1 to 64 of `A-Z a-z 0-9 . _ @ -`.
+* **Capabilities** (`caps`): each a path, as segments as the store's API takes them,
+  and the rights it gives there and below: `read`, `write`. A capability covers its
+  path segment by segment (`servers/eu` covers `servers/eu/0`, not `servers/europe`).
+  One outside protocol data never covers protocol data: `[]` is all of the swarm's
+  data, `["_continuum"]` protocol data, managing users included (`_continuum/users`).
+  They are kept by a random ID, so two capabilities granted at once both hold, and
+  revoking one removes it alone. Each names who granted it (`by`: a user as
+  `user:<name>`, or the node that recorded it) and when (`since`).
+* **`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.
+
+## A new swarm
+
+Its genesis node records the first users, with the swarm ID, in its first change:
+
+* those of `--bootstrap-users`, each with everything (`[]` and `["_continuum"]`);
+* unset: the users of its `--htpasswd` with `[]`, and those of them, or of the
+  proxy's, in `--protocol-writers` with `["_continuum"]` too.
+
+A swarm nobody could manage doesn't start: with none of them with `["_continuum"]`,
+`--genesis` is refused, naming both options.
diff --git a/docs/example.toml b/docs/example.toml
index a868327..26be818 100644
--- a/docs/example.toml
+++ b/docs/example.toml
@@ -85,6 +85,12 @@ htpasswd = "/etc/continuum/htpasswd"
 # writable.
 # protocol-writers = ["alice"]
 
+# With genesis: the new swarm's first users, each may do everything, protocol data and
+# managing users included (docs/access.md). Unset, the users of htpasswd may read and
+# write the swarm's data, and those also in protocol-writers everything. A swarm nobody
+# could manage doesn't start: set this, or protocol-writers, for one of htpasswd's users.
+# bootstrap-users = ["alice"]
+
 # How log lines look: text (timestamped), journal (for systemd's journal: no timestamp or
 # colours, the level as each line's priority, for journalctl -p), or auto: journal when
 # stdout goes to the journal, else text.