aboutsummaryrefslogtreecommitdiffstats
path: root/docs/openapi.yaml
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-19 20:11:05 +0000
committertv <tv@krebsco.de>2026-11-19 21:27:21 +0100
commit9bf334bedbc4b0cc3ce32fcd3baef27d3072f194 (patch)
tree6236db6799c2523ccdb899e6a42cc2153ce4eb08 /docs/openapi.yaml
parentfc6c7101cdb42666c1f79df4206029c7cf7e61c6 (diff)
federated nodes: a party's keys log in as the party, for federation work
A party's people work with the federation by signing as the party, with a key of its set; what they need of a node is to read and to put events, which a node's users, its operators, may do with every power besides. POST /auth/login/party takes a challenge (POST /auth/challenge) signed with one of the keys that sign for the party (fold::State::signing_keys: those its current version names, and its key set as it counts), for the namespace continuum-login, armored or as the federation spells a signature (keys::signer, keys::verifies_in: the federation's checks, but for the namespace), and answers a token as the party. Logins by key are counted per party as per user (challenge::take_with, shared with logging in by a registry's keys). The token names the key (Claims::party). Such a session does federation work alone (api::access::federated): what --store-readers do, and POST /events; anything else is 403. Every request checks that the key still signs for the party: once a version or the party's key set drops it, 401. A build from before reads no token naming a key, as its claims deny fields they don't know, so never takes a party's session for a user's; and only the node that issued it takes it, as every token in a federated swarm.
Diffstat (limited to 'docs/openapi.yaml')
-rw-r--r--docs/openapi.yaml38
1 files changed, 37 insertions, 1 deletions
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index a64c739..797c46f 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -902,6 +902,42 @@ paths:
'409': { description: No user registry, which holds the keys. }
'503': { description: Not ready yet. }
+ /auth/login/party:
+ post:
+ tags: [Auth, Events]
+ summary: Log in as a party, by one of its keys (federation)
+ description: |
+ On a node holding a federated store (`federation` feature): a challenge
+ (`POST /auth/challenge`) signed by one of the keys that sign for the party there,
+ those its current version names or of its key set as it counts, for the namespace
+ `continuum-login` (an ECDSA signature's `s` low, as for events). A token as the
+ party (`login: party`): a party's session, which does federation work alone,
+ reading the events API, putting events and checking forks, while that key signs
+ for the party (`401` once it doesn't); anything else is `403`. The node that
+ issued it alone takes it. No authentication: the signature proves the party.
+ security: []
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [party, challenge, signature]
+ properties:
+ party: { type: string }
+ challenge: { type: string }
+ signature: { type: string, description: 'Armored, as `ssh-keygen -Y sign -n continuum-login` writes it, or its blob in base64.' }
+ responses:
+ '200':
+ description: The token.
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/TokenAnswer' }
+ '400': { description: A request that isn't one. }
+ '401': { description: 'Not a challenge of this node, expired or used, or not signed by a key that signs for the party, or no party of the current version (the message says which).' }
+ '409': { description: No federated store here. }
+ '503': { description: Not ready yet. }
+
/auth/session:
post:
tags: [Auth]
@@ -1038,7 +1074,7 @@ paths:
get:
tags: [Auth]
summary: Who you are here
- description: The swarm, the user, how it proved it (`htpasswd`, `header`, `token`), its registry entry's capabilities (`caps`), what this request may do (`may`, a list of capabilities; with a token that says less, what both give), and its token's claims if it came with one.
+ description: The swarm, the user, how it proved it (`htpasswd`, `header`, `token`), its registry entry's capabilities (`caps`), what this request may do (`may`, a list of capabilities; with a token that says less, what both give), and its token's claims if it came with one (of a party's session, `party`: the key it logged in with).
responses:
'200':
description: Who.