auth: a login page and browser sessions

GET /login without authentication: log in by password or with a token
(from a login by key). POST/DELETE /auth/session keep the token as an
HttpOnly, SameSite=Strict cookie; the dashboard sends a browser
without a user there and renews the session while open.

Auth plan M2/M3 (browsers).

1 files changed, 50 insertions, 0 deletions

diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index ab14710..bb1d34b 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -895,6 +895,56 @@ paths:
         '409': { description: No user registry, which holds the keys. }
         '503': { description: Not ready yet. }
 
+  /auth/session:
+    post:
+      tags: [Auth]
+      summary: Keep a token as the browser's session
+      description: |
+        As `POST /auth/refresh`, and the new token set as the session cookie
+        (`continuum-token`, `HttpOnly`, `SameSite=Strict`, for as long as the token is
+        valid): requests without `Authorization` that bring it are its user's.
+      security:
+        - bearer: []
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Limit'
+      responses:
+        '200':
+          description: The token, also set as the cookie.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/TokenAnswer' }
+        '400': { description: No token, or a limit that isn't one or says more than the token's. }
+        '401': { description: 'The token isn''t taken, or its login ended.' }
+        '503': { description: Not ready yet. }
+    delete:
+      tags: [Auth]
+      summary: Forget the browser's session
+      description: The session cookie cleared. The token stays valid until it expires (`POST /auth/logout` ends them all).
+      responses:
+        '204': { description: Forgotten. }
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+  /login:
+    get:
+      tags: [Auth]
+      summary: The page to log in on
+      description: |
+        With the dashboard: a page to log in on by password or with a token, without
+        authentication. It keeps a session (`POST /auth/session`) and opens
+        `/admin/dashboard`, where a browser without a user is sent (`303`).
+      security: []
+      responses:
+        '200':
+          description: The page.
+          content:
+            text/html: {}
+        '404': { description: A build without the dashboard. }
+
   /auth/refresh:
     post:
       tags: [Auth]