aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-19 20:06:05 +0000
committertv <tv@krebsco.de>2026-11-19 21:26:49 +0100
commitfc6c7101cdb42666c1f79df4206029c7cf7e61c6 (patch)
treeb9a2f088aedcafa762d552cada23eba134f9e849 /docs/guides/federation
parentd93f574d14a2e52a1d7dfd1e256f70c6eb9644ef (diff)
federated nodes: users who read the federation alone (--store-readers)
On a federated node, every user its htpasswd or proxy lets in may do everything: put events, have it drop what it took, vote through it with its party's key, make fork roots, read the document. An application or someone watching needn't act for the node. `--store-readers USER,...` names users who read the federation and do nothing else (`api::access::federated`, before the registry's checks): GET and HEAD of the events API (/events and below), checking a fork (POST /events/fork), and keeping a session (whoami, refresh, logout); anything else is 403, saying so. Its other users are its operators, as all were: a node setting nothing changes nothing.
Diffstat (limited to 'docs/guides/federation')
-rw-r--r--docs/guides/federation/running-a-node.md12
1 files changed, 8 insertions, 4 deletions
diff --git a/docs/guides/federation/running-a-node.md b/docs/guides/federation/running-a-node.md
index 94781d4..e08a47e 100644
--- a/docs/guides/federation/running-a-node.md
+++ b/docs/guides/federation/running-a-node.md
@@ -63,10 +63,14 @@ alone, so that a party listing many nodes can't be all of a node's neighbours.
## Its API
* **Who it lets in** is its own (`--htpasswd`, or a reverse proxy naming the user):
- there is no user registry, and every user it lets in may do everything at it: put
- events, read, have it drop what it took and take it back, vote through it, make a
- fork's root. A token is taken by the node that issued it only. Let in those who act
- for the node, and give a party without nodes of its own a user to put its events.
+ there is no user registry. Its users are its operators, and may do everything at it:
+ put events, read, have it drop what it took and take it back, vote through it, make a
+ fork's root. Those named in `--store-readers` read the federation and do nothing
+ else: `GET` of the events API below, and checking a fork (`POST /events/fork`), but
+ nothing of the document (`/store`, `/stream`), the node (`/peers`, `/admin/…`), nor
+ 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.
* **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}`,