diff options
| author | tv <tv@krebsco.de> | 2026-11-19 20:11:05 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-19 21:27:21 +0100 |
| commit | 9bf334bedbc4b0cc3ce32fcd3baef27d3072f194 (patch) | |
| tree | 6236db6799c2523ccdb899e6a42cc2153ce4eb08 /docs | |
| parent | fc6c7101cdb42666c1f79df4206029c7cf7e61c6 (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')
| -rw-r--r-- | docs/guides/federation/running-a-node.md | 9 | ||||
| -rw-r--r-- | docs/openapi.yaml | 38 |
2 files changed, 46 insertions, 1 deletions
diff --git a/docs/guides/federation/running-a-node.md b/docs/guides/federation/running-a-node.md index e08a47e..ea51f8a 100644 --- a/docs/guides/federation/running-a-node.md +++ b/docs/guides/federation/running-a-node.md @@ -71,6 +71,15 @@ alone, so that a party listing many nodes can't be all of a node's neighbours. what an operator does to the store (`/admin/events/…`): for an application, or someone watching, that needn't act for the node. A token is taken by the node that issued it only, and gives what its user may do. +* **A party's keys** log in to every node holding the store, without a password: a + challenge (`POST /auth/challenge`) signed with 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`, gives a token as the party (`POST /auth/login/party`). + Such a session does federation work alone: what a reader does, and putting events + (`POST /events`), while that key signs for the party (`401` once it doesn't). So a + party's people, each with a key of its set, work with the federation through any node + that holds it, as no operator has to let them in, and with nothing of an operator's + powers. * **The events** (`docs/openapi.yaml`, Events): `GET /events` (the store's ID, its checkpoint, its heads, how many events it took, the node's party, and whether it votes for it by itself), `POST /events` (an event, whoever signed it), `GET /events/{id}`, 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. |
