users: a user manages its own keys

Only a user who may manage users could change a user's keys: a user
couldn't add a new laptop's key, or remove a lost one.

A user now manages its own keys, whatever else it may do:

* GET /auth/keys: its keys, its entry, and the envelope holding it
  under a strict policy (`signed`), to sign against.
* PUT /auth/keys/{id} with an authorized_keys line, DELETE
  /auth/keys/{id}: one change, as the user. The rules take a write of
  _continuum/users/<name>/keys/… from the user it names.
* Under a strict policy, the user signs its entry with only its keys
  changed, with a key it holds already (envelope::check takes that from
  the user itself), PUT to its own entry even without write on the
  registry; continuum-signed key-add and key-remove do so.

2 files changed, 49 insertions, 1 deletions

diff --git a/docs/access.md b/docs/access.md
index 3541efd..5983c7c 100644
--- a/docs/access.md
+++ b/docs/access.md
@@ -31,7 +31,12 @@ password hashes: every member reads the document).
   doesn't read is left out, and anything but `false` disables.
 * **`keys`**: the user's SSH keys, each by a name of its choosing, as an
   `authorized_keys` line has it (`"laptop": "ssh-ed25519 AAAA…"`; Ed25519 only): what
-  it signs values with (Values signed by their users, below).
+  it signs values with (Values signed by their users, below) and logs in with. A user
+  manages its own, whatever else it may do: `GET /auth/keys`, `PUT /auth/keys/<name>`
+  with the line, `DELETE /auth/keys/<name>`; under a strict policy, by signing its
+  entry with only its keys changed (`continuum-signed key-add laptop
+  ~/.ssh/id_ed25519.pub`, `key-remove laptop`), with a key it holds already. Every
+  node takes that from the user itself, as from one who may manage users.
 
 ## A new swarm
 
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 2ebf7fc..de62b59 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -977,6 +977,49 @@ paths:
         '204': { description: Done. }
         '409': { description: No user registry; tokens are taken until they expire. }
 
+  /auth/keys:
+    get:
+      tags: [Auth]
+      summary: Your keys
+      description: Your keys, your registry entry as recorded, and under a strict policy the envelope holding it (`signed`), which signing it anew names (`prev`).
+      responses:
+        '200':
+          description: Yours.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  keys: { type: object, additionalProperties: { type: string } }
+                  entry: { type: object }
+                  signed: { type: string, nullable: true }
+        '404': { description: No entry of yours. }
+
+  /auth/keys/{id}:
+    parameters:
+      - { name: id, in: path, required: true, schema: { type: string } }
+    put:
+      tags: [Auth]
+      summary: Add or replace one of your keys
+      description: Whatever else you may do. Under a strict policy `409`; sign your entry with the keys changed instead (`continuum-signed key-add`).
+      requestBody:
+        content:
+          text/plain:
+            schema: { type: string }
+            example: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA… laptop
+      responses:
+        '204': { description: Done. }
+        '400': { description: Not an Ed25519 public key, or not a key's name. }
+        '404': { description: No entry of yours. }
+        '409': { description: Strict policy. }
+    delete:
+      tags: [Auth]
+      summary: Remove one of your keys
+      responses:
+        '204': { description: Done. }
+        '404': { description: No entry of yours, or no such key. }
+        '409': { description: Strict policy. }
+
   /auth/whoami:
     get:
       tags: [Auth]