auth: logging in by key

POST /auth/challenge and /auth/login/key: a node-signed challenge,
valid five minutes and taken once, signed with one of the user's SSH
keys (ssh-keygen -Y sign -n continuum-login), for a token.

Auth plan M7 (key login, M2b).

1 files changed, 16 insertions, 0 deletions

diff --git a/docs/access.md b/docs/access.md
index 20fa23d..a182266 100644
--- a/docs/access.md
+++ b/docs/access.md
@@ -106,6 +106,22 @@ curl -H "Authorization: Bearer ct1.…" http://other-node:3000/store
   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.
 
+A user with keys in its entry (`keys`, The registry, above) logs in on any node without
+a password: it asks for a challenge, signs it with one of its keys, and gets the same
+token (`login: "key"`).
+
+```sh
+c=$(curl -s -X POST localhost:3000/auth/challenge | jq -r .challenge)
+printf %s "$c" | ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n continuum-login > sig
+jq -n --arg c "$c" --rawfile s sig '{user: "alice", challenge: $c, signature: $s}' |
+  curl -s -X POST localhost:3000/auth/login/key -H 'Content-Type: application/json' -d @-
+```
+
+A challenge is the node's, signed by it, valid for five minutes, and taken once;
+the signature must be by one of the user's keys, as the registry the node holds then
+says, and the user enabled (`401` if not, saying why). A swarm without a registry has
+no keys (`409`).
+
 `GET /auth/whoami` says who a request's user is, how it proved it, and what it may do.
 
 Pages of other origins, the dashboards of other members, may call a node with a token: