auth: logging in, and tokens as bearers

POST /auth/login (by htpasswd or the proxy), /auth/refresh,
/auth/logout, GET /auth/whoami; every request may bring
Authorization: Bearer instead of a password. --token-lifetime and
--session-lifetime.

Auth plan M2.

1 files changed, 32 insertions, 0 deletions

diff --git a/docs/access.md b/docs/access.md
index db86e21..e8c5455 100644
--- a/docs/access.md
+++ b/docs/access.md
@@ -73,6 +73,38 @@ A user the node lets in but the registry doesn't have may do nothing (`403`).
 whole swarm (its members, its remakes, its users), so it is given apart, never by
 accident with the data. A user who may do both has both.
 
+## Tokens
+
+A user logs in on any node, by what that node checks (its `--htpasswd`, or a proxy's
+`--user-header`), and gets a token every node of the swarm takes, sent as
+`Authorization: Bearer <token>` instead of a password:
+
+```sh
+curl -u alice -X POST http://localhost:3000/auth/login       # {"token": "ct1.…", …}
+curl -H "Authorization: Bearer ct1.…" http://other-node:3000/store
+```
+
+* **Who signs it**: the node it logged in on, with its node key. Every node takes a
+  token signed by a member of the swarm (the member list gives the keys: a node ID is
+  its key), and none signed by another or since forgotten.
+* **What it says**: who, how it proved it, when it ends, and optionally less than the
+  user may do (`limit`, capabilities as `POST /admin/users/{name}` takes them): never
+  what the user may do. Every node judges a request by the registry it holds then, so
+  a capability granted or revoked counts on a node as soon as the change reaches it.
+* **How long**: `--token-lifetime` (12 hours), refreshed (`POST /auth/refresh`, on any
+  node, which signs the new one) until `--session-lifetime` (7 days) after the login;
+  then the user logs in again. A refreshed token may say less (`limit`), never more.
+* **Revoking**: a user disabled or removed is refused at once; all of a user's tokens,
+  by the user (`POST /auth/logout`) or by one who may manage users (`DELETE
+  /admin/users/{name}/tokens`), which sets `tokensNotBefore` in its entry: tokens issued
+  before aren't taken any more. A token of a node forgotten by the swarm isn't taken
+  either. In a swarm without a registry, a token is taken until it expires.
+* **What it means to trust**: any member could sign a token for any user, as it could
+  write anything as anyone ([`trust.md`](trust.md)). A token is a bearer's: whoever holds it is
+  the user until it ends, so it goes over TLS only, as passwords do.
+
+`GET /auth/whoami` says who a request's user is, how it proved it, and what it may do.
+
 ## Managing users
 
 Through `/admin/users` ([`openapi.yaml`](openapi.yaml), Users): looking needs `read` on