aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation
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/guides/federation
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/guides/federation')
-rw-r--r--docs/guides/federation/running-a-node.md9
1 files changed, 9 insertions, 0 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}`,