From e696d2f40636a6613eddfb1a3afdf87aa7ffdedd Mon Sep 17 00:00:00 2001
From: tv <tv@krebsco.de>
Date: Sat, 7 Nov 2026 22:35:21 +0100
Subject: 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).
---
 docs/openapi.yaml | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

(limited to 'docs/openapi.yaml')

diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 6abfc6d..1bd3a16 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -838,6 +838,63 @@ paths:
         '403': { description: Not a registered, enabled user. }
         '503': { description: Not ready yet. }
 
+  /auth/challenge:
+    post:
+      tags: [Auth]
+      summary: A challenge to log in by key
+      description: |
+        A challenge for `POST /auth/login/key`, signed by this node, valid for five
+        minutes, taken once. The user signs it, exactly, with one of its keys
+        (`docs/access.md`, The registry), as `ssh-keygen -Y sign -n continuum-login`
+        does. No authentication.
+      security: []
+      responses:
+        '200':
+          description: The challenge.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  challenge: { type: string, example: 'cc1.eyJub2RlIjo….Tm9kZS…' }
+                  namespace: { type: string, example: continuum-login }
+                  expiresAt: { type: integer, format: int64, description: Unix ms. }
+        '503': { description: Not ready yet. }
+
+  /auth/login/key:
+    post:
+      tags: [Auth]
+      summary: Log in by key for a token
+      description: |
+        A challenge (`POST /auth/challenge`) signed by one of the user's keys: a token,
+        as `POST /auth/login` gives one (`login: key`). No authentication: the
+        signature proves the user.
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [user, challenge, signature]
+              properties:
+                user: { type: string }
+                challenge: { type: string }
+                signature: { type: string, description: 'Armored, as `ssh-keygen -Y sign` writes it.' }
+                limit:
+                  type: array
+                  items: { $ref: '#/components/schemas/CapabilityRequest' }
+      responses:
+        '200':
+          description: The token.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/TokenAnswer' }
+        '400': { description: A request or limit that isn't one. }
+        '401': { description: 'Not a challenge of this node, expired or used, or not signed by one of the user''s keys, or the user disabled or unknown (the message says which).' }
+        '409': { description: No user registry, which holds the keys. }
+        '503': { description: Not ready yet. }
+
   /auth/refresh:
     post:
       tags: [Auth]
-- 
cgit v1.3.1