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, 112 insertions, 0 deletions

diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 5bf5a50..64c5b9b 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -26,6 +26,7 @@ servers:
 
 security:
   - basic: []
+  - bearer: []
 
 tags:
   - name: Store
@@ -38,6 +39,10 @@ tags:
     description: |
       Replacing the swarm's document with a new epoch (compaction, replacement,
       import), and what happened to local writes that a remake couldn't place.
+  - name: Auth
+    description: |
+      Logging in on this node for a token every node of the swarm takes, and using it
+      (docs/access.md, Tokens).
   - name: Users
     description: |
       The swarm's users and what each may do (docs/access.md): reading needs `read` on
@@ -733,6 +738,91 @@ paths:
         '401':
           $ref: '#/components/responses/Unauthorized'
 
+  /auth/login:
+    post:
+      tags: [Auth]
+      summary: Log in for a token
+      description: |
+        As a user this node lets in (htpasswd, or a trusted proxy's user-header): a token
+        signed by this node, taken by every node of the swarm until `expiresAt`
+        (`token-lifetime`), refreshable until `sessionExpiresAt` (`session-lifetime`).
+        With `limit`, the token gives only what it allows too.
+      security:
+        - basic: []
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Limit'
+      responses:
+        '200':
+          description: The token.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/TokenAnswer' }
+        '400': { description: A token instead of a password, or a limit that isn't one. }
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403': { description: Not a registered, enabled user. }
+        '503': { description: Not ready yet. }
+
+  /auth/refresh:
+    post:
+      tags: [Auth]
+      summary: Refresh a token
+      description: A new token for the same login, signed by this node; with `limit`, narrower still (within the token's).
+      security:
+        - bearer: []
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Limit'
+      responses:
+        '200':
+          description: The token.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/TokenAnswer' }
+        '400': { description: No token, or a limit wider than the token's. }
+        '401': { description: The token isn't taken, or its login ended. }
+
+  /auth/logout:
+    post:
+      tags: [Auth]
+      summary: End all of your logins
+      description: Every token of the user, of every login, no longer taken (`tokensNotBefore`).
+      responses:
+        '204': { description: Done. }
+        '409': { description: No user registry; tokens are taken until they expire. }
+
+  /auth/whoami:
+    get:
+      tags: [Auth]
+      summary: Who you are here
+      description: The user, how it proved it (`htpasswd`, `header`, `token`), its registry entry's capabilities, and its token's claims if it came with one.
+      responses:
+        '200':
+          description: Who.
+          content:
+            application/json:
+              schema:
+                type: object
+
+  /admin/users/{name}/tokens:
+    parameters:
+      - { name: name, in: path, required: true, schema: { type: string } }
+    delete:
+      tags: [Users]
+      summary: Revoke every token of a user
+      responses:
+        '204': { description: Revoked. }
+        '403': { description: May not manage users. }
+        '404': { description: No such user. }
+        '409': { description: No user registry. }
+
   /admin/users:
     get:
       tags: [Users]
@@ -1468,6 +1558,10 @@ components:
     basic:
       type: http
       scheme: basic
+    bearer:
+      type: http
+      scheme: bearer
+      description: A token from `POST /auth/login` on any node of the swarm (docs/access.md, Tokens).
 
   parameters:
     key:
@@ -1637,6 +1731,24 @@ components:
             $ref: '#/components/schemas/Error'
 
   schemas:
+    Limit:
+      type: object
+      properties:
+        limit:
+          type: array
+          items: { $ref: '#/components/schemas/CapabilityRequest' }
+    TokenAnswer:
+      type: object
+      properties:
+        token: { type: string, description: '`ct1.…`: send it as `Authorization: Bearer <token>`.' }
+        user: { type: string }
+        issuer: { type: string, description: The node that signed it. }
+        expiresAt: { type: integer, description: Unix ms. }
+        sessionExpiresAt: { type: integer, description: Unix ms. }
+        limit:
+          type: array
+          nullable: true
+          items: { $ref: '#/components/schemas/CapabilityRequest' }
     CapabilityRequest:
       type: object
       required: [path, rights]