diff options
| author | tv <tv@krebsco.de> | 2026-11-16 04:43:29 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-16 04:43:29 +0000 |
| commit | 041a0c0facadbe7cc8c7ef663a0b0c2ecc20f625 (patch) | |
| tree | d4df736ec045eb34bdf21145c816f26bdf063519 /docs/federation.md | |
| parent | ed6ad252be5e3b0c355ab6a508e1e27e207d4c6a (diff) | |
federation: what a version names anew, by a number, nothing unsigned
A version setting a party's keys or node list had the change writing it
write an envelope without a signature at the party's place, `prev`
empty and `seq` 0, and only that change, so that it was ahead of every
set before it: a kind of envelope of its own, a rule on who writes it,
the same written again with the version, and a genesis and a fork
writing them too.
Each version gives, for each party's keys and node list, the number of
the version that named them anew (`since`): its own where it does, else
that of the version it changes. A party's keys are those of its set
where the set names a version numbered at least that; otherwise those
the version names; its node list the same. Nothing is written for it,
the document holds no envelope without a signature, and what a key an
earlier version named writes at a history from before still counts no
more.
Diffstat (limited to 'docs/federation.md')
| -rw-r--r-- | docs/federation.md | 198 |
1 files changed, 99 insertions, 99 deletions
diff --git a/docs/federation.md b/docs/federation.md index 93fb41e..b9bb42e 100644 --- a/docs/federation.md +++ b/docs/federation.md @@ -95,17 +95,15 @@ policy). A swarm that isn't federated reads a `cv3.` string as the string it is. A change writing an envelope that names another version than the one current at its history is refused, but for an epoch's first change (a remake's snapshot, a fork's -genesis), which is judged by none, and for the key sets and node lists a version sets, -which name the version being written (Keys). Of the envelopes a place holds, written at -once, its value is the one with the highest version number, then the highest `seq`, then -the lower SHA-256, among those signed by a key their party holds (Keys); where none is, -nothing there counts. Judging a change goes by all of them, as they stand: its `prev` -names the first of all, whoever signed it, so a party's first envelope where another's -is (a place given to it, an envelope a dropped key wrote) names that one, its `seq` one -more. So what a place holds is its party's to say, never the order of -operations, which whoever writes a change steers, nor a key the party dropped; and what -was signed under a later version is ahead of anything written at a history from before -it. +genesis), which is judged by none. Of the envelopes a place holds, written at once, its +value is the one with the highest version number, then the highest `seq`, then the lower +SHA-256, among those signed by a key their party holds (Keys); where none is, nothing +there counts. Judging a change goes by all of them, as they stand: its `prev` names the +first of all, whoever signed it, so a party's first envelope where another's is (a place +given to it, an envelope a dropped key wrote) names that one, its `seq` one more. So +what a place holds is its party's to say, never the order of operations, which whoever +writes a change steers, nor a key the party dropped; and what was signed under a later +version is ahead of anything written at a history from before it. A swarm under a strict policy reads by `seq` alone, the same way, and replays a value its user signed as the chain of envelopes that leads to it *(checked: @@ -136,10 +134,10 @@ current at its heads, Forks). Spread out: ```json { "federation": 1, "number": 7, "changes": "<hash of the version it changes>", - "keys": { "tv": ["ssh-ed25519 AAAA… tv"], - "lass": ["ssh-ed25519 AAAA… lass"], - "makefu": ["ssh-ed25519 AAAA… makefu"] }, - "nodes": {}, + "keys": { "tv": { "since": 0, "keys": ["ssh-ed25519 AAAA… tv"] }, + "lass": { "since": 4, "keys": ["ssh-ed25519 AAAA… lass"] }, + "makefu": { "since": 7, "keys": ["ssh-ed25519 AAAA… makefu"] } }, + "nodes": { "tv": { "since": 0, "nodes": ["<node ID>"] } }, "rules": [ { "path": "names/r/wiki", "writer": "lass" }, { "path": "home/{party}/**", "writer": "{party}" }, @@ -151,15 +149,17 @@ current at its heads, Forks). Spread out: * **The federation** it follows, and its **number**, one more than that of the version it changes. -* **The parties and their keys**: one party at least, each by name, as continuum's - user names, 1 to 64 of `A-Z a-z 0-9 . _ @ -` but not `@`, with one `ssh-ed25519` key - or more, compared as keys (their comments aside), none twice in the version. With - them the party signs its votes and proposals on this version, its key set and its - node list (Keys, Nodes). Where a party's keys differ from those the version it - changes names (a party new in it, or one whose keys the parties replace), the - version **sets** them (Keys). -* **The node lists it sets** (`nodes`), by party, each a list of node IDs: the first - version and a fork's set those of the parties that start it (Nodes). +* **The parties and their keys** (`keys`): one party at least, each by name, as + continuum's user names, 1 to 64 of `A-Z a-z 0-9 . _ @ -` but not `@`, with one + `ssh-ed25519` key or more, compared as keys (their comments aside), none twice in the + version. With them the party signs its votes and proposals on this version, its key + set and its node list (Keys, Nodes). Its `since` is the number of the version that + named them anew: this one's where it does (a party new in it, keys the parties + replace, or the same keys named anew), else that of the version it changes, whose + keys for the party it then names unchanged. +* **The node lists** (`nodes`), by party, each a list of node IDs with its `since` as + keys have one, for the parties a version named one for anew, this or an earlier one: + the first version and a fork's name those of the parties that start it (Nodes). * **The rules**, in order: the first whose path matches a path says who writes there. A path is segments separated by `/`, none empty. A rule's first segment is literal, and not `_continuum`; any other is literal, `{party}` (the name of a party of the @@ -204,13 +204,12 @@ the way to what it writes there as it does to `@` keys. | `_continuum/federation/versions/<hash>` | a version that passed | any member, once it passed | | `_continuum/federation/proposals/<party>/<hash>` | a version proposed | that party | | `_continuum/federation/votes/<party>/<version>/<proposal>` | `true` or `false` | that party | -| `_continuum/federation/keys/<party>` | its keys | that party, by a key its version names; the change writing a version that sets them | -| `_continuum/federation/nodes/<party>` | its nodes' IDs | that party, by a key its version names; the change writing a version that sets them | +| `_continuum/federation/keys/<party>` | its keys | that party, by a key its version names | +| `_continuum/federation/nodes/<party>` | its nodes' IDs | that party, by a key its version names | What a party writes is an envelope, signed by one of its keys. A version is written as -its text, a plain string; the key sets and node lists it sets, as envelopes without a -signature; all of them count by the votes the version had. A proposal's place takes -only the proposal. +its text, a plain string, and counts by the votes it had. A proposal's place takes only +the proposal. A federated swarm has no user registry, and of `_continuum` takes only these writes: @@ -269,11 +268,11 @@ that could pass at one history and be taken back at another would let two versio written without anyone voting twice. Once a proposal passed on the current version, a node writes it as soon as it holds it -passed, at `_continuum/federation/versions/<hash>`, with the key sets and node lists it -sets (Keys, Nodes): any member may, and the same version written by several is one -(below). Every node judges that change by its history: the proposal written there, on -the version the text changes, its votes there, and that version current. A version takes -effect when it is written, and judges every change in sight of it. +passed, at `_continuum/federation/versions/<hash>`: any member may, and the same version +written by several is one (below). Every node judges that change by its history: the +proposal written there, on the version the text changes, its votes there, and that +version current. A version takes effect when it is written, and judges every change in +sight of it. **A node takes a version only where it changes the version the node reads**, or is one it took, written again. A change writing any other, valid at its history or not, it @@ -336,28 +335,27 @@ its key set and its node list. Everything else it signs with its keys at version current at its history names for the party, numbered as any envelope. A set is checked only where it is written, never by the keys of a set (What counts, 2). -The change that writes a version setting a party's keys writes them there too, and only -that change, or it is refused: an envelope without a signature (`cv3.<value>.<meta>.`), -the keys the version names for the party and no others, its meta naming the swarm, its -path, that version and the party, `at` 0, `prev` empty and `seq` 0, so that it is the -same wherever the version is written. It is ahead of every set naming an earlier -version, and the party's next set replaces it. +A party's keys are those of its set where the set names a version numbered at least the +`since` its version gives the party's keys; otherwise, and while it has written none, +those its version names. So once a version names a party's keys anew, no set naming an +earlier version counts, and the party's next set, naming that version, does. Nothing is +written for it: the version says it. -* **A value counts only while the key that signed it is among its party's keys**, those - of its set: votes, proposals, sets and node lists aside, which go by the keys their - version names. A party changes its keys by itself: it writes a set with the new keys, - signs again with one of them what should stay (a change is judged at its history, - where only the set it replaces is the party's), writes a set without the old ones, - and signs again after it what should stay (a client does it all). What a key it - dropped signed counts no more; what that key writes at a history from before the drop - can't name what the party signed after it as replaced, and counts no more either, so - it takes nothing out. A key added back, from a backup say, brings back what it signed - where it is still there. +* **A value counts only while the key that signed it is among its party's keys**, as + above: votes, proposals, sets and node lists aside, which go by the keys their version + names. A party changes its keys by itself: it writes a set with the new keys, signs + again with one of them what should stay (a change is judged at its history, where only + the set it replaces is the party's), writes a set without the old ones, and signs + again after it what should stay (a client does it all). What a key it dropped signed + counts no more; what that key writes at a history from before the drop can't name what + the party signed after it as replaced, and counts no more either, so it takes nothing + out. A key added back, from a backup say, brings back what it signed where it is still + there. * **Only a version revokes a key it names.** One lost or stolen is answered by a version - naming the party's keys anew, whose set is ahead of every set before it. What the - party then signs names that version, and is ahead of anything the old key writes at a - history from before it. Until then, the old key votes, and writes the party's set and - node list, as the party's. + naming the party's keys anew: no set before it counts any more. What the party then + signs names that version, and is ahead of anything the old key writes at a history + from before it. Until then, the old key votes, and writes the party's set and node + list, as the party's. * **A party's own key change reaches its votes and proposals** once a version names its new keys. A party can keep the keys its version names apart, offline, and sign its values with a set of its own. @@ -374,7 +372,8 @@ whole. These count no more, and nothing else does: longer one, the place went to another, a rule changed; and of a party that is no longer one, its key set and its node list; 2. a value signed by a key that isn't among its party's, votes, proposals, key sets - and node lists aside, which go by the keys their version names; + and node lists aside, which go by the keys their version names; and a key set or + node list naming a version before the `since` its version gives it (Keys); 3. a proposal on a version that isn't current, and the votes on that version; 4. a version behind the current one; 5. an envelope behind another at its place, of those 2 leaves; @@ -392,16 +391,18 @@ party writes there again. A party lists the nodes that carry for it, by node ID, at `_continuum/federation/nodes/<party>`: one envelope, signed with a key its version -names, or set by a version as a version sets keys (Keys). A node's party is its -operator's, in its configuration, and its own member entry names it. A node is a member -while that party lists it: it registers, commits changes and syncs, and nodes sync with -members only (Stages). Another party's list does nothing. A party's list counts until -the party writes another or a version sets one, whatever keys its version names since, -so that no change of keys leaves a swarm without members; a list a stolen key wrote -stays until the party writes one under the version that replaced that key, which it can -at once, through any member. A node commits whatever envelopes it is given, its party's -and others' alike: what counts is who signed a value, not which node committed it. So a -party without nodes of its own writes through any node that takes its envelopes. +names. A party's list is that one where it names a version numbered at least the `since` +its version gives the party's list, otherwise the list its version gives, if any, as +with keys (Keys). A node's party is its operator's, in its configuration, and its own +member entry names it. A node is a member while that party lists it: it registers, +commits changes and syncs, and nodes sync with members only (Stages). Another party's +list does nothing. A party's list counts until the party writes another or a version +names one anew, whatever keys its version names since, so that no change of keys leaves +a swarm without members; a list a stolen key wrote stays until the party writes one +under the version that replaced that key, which it can at once, through any member. A +node commits whatever envelopes it is given, its party's and others' alike: what counts +is who signed a value, not which node committed it. So a party without nodes of its own +writes through any node that takes its envelopes. A node keeps some of its neighbours among its own party's nodes and those of the parties its operator names, so that a party listing many nodes can't be every node's @@ -423,12 +424,12 @@ the group won't follow passed, the parties can't agree, or it leaves the federat snapshot leaves out, by the version current at those heads (Remakes), the federation's versions, and continuum's own data (member entries, remake records and acks, earlier epochs' metadata, the swarm's name): of versions, only the group's own, - the fork's first, with the key sets and node lists it sets. It names the highest - version at those heads as the one it changes, is numbered one past it, and sets the - node lists of the parties that start it, and the keys of any party it names anew; - judged by none, as an epoch's first change is. Every proposal is a chance to fork: - the version is usually one that didn't pass. To leave the federation, the genesis - holds another policy instead, and what it needs. + the fork's first. It names the highest version at those heads as the one it changes, + is numbered one past it, and names anew the node lists of the parties that start it, + and the keys of any party whose keys it changes; judged by none, as an epoch's first + change is. Every proposal is a chance to fork: the version is usually one that didn't + pass. To leave the federation, the genesis holds another policy instead, and what it + needs. 2. A fork is named by the hash of its first version together with the heads it names, which nobody can steer to a given name, the old swarm's least of all: its genesis change writes it at `_continuum/swarm`, as every node checks, and an envelope's meta @@ -472,20 +473,19 @@ for parties, zones, blocks and names that are nobody's by their spelling. ### Starting a federation A federation starts with a swarm of its own: its genesis change, the swarm's first, -holds the federated policy, the swarm's name and the first version, with the key sets -and node lists it sets, and nothing else; among those lists, one naming a node of its -founders', so the federation starts with members, and other nodes come in as their -parties list them. It is built byte for byte from the first version alone, as a fork's -genesis is from its version and heads (Forks): its writer from the swarm's name, time 0, -no message; and the swarm is named by the first version's hash, so one first version -makes one swarm, and a node joining builds the genesis change and checks it. A swarm -strict from its start records its policy in its genesis change too -(`--bootstrap-policy`) *(checked: `swarm::bootstrap`)*, which starts it empty: content -before it would be a change from before the federation, judged by none. So nothing is -from before the federation, and nothing writes the policy's place after the genesis -change: the federation changes by versions, and is left by a fork. A running swarm -doesn't become federated; its parties start one, and sign into it, after the genesis -change, what they keep. +holds the federated policy, the swarm's name and the first version, and nothing else; +among the node lists the version gives, one names a node of its founders', so the +federation starts with members, and other nodes come in as their parties list them. It +is built byte for byte from the first version alone, as a fork's genesis is from its +version and heads (Forks): its writer from the swarm's name, time 0, no message; and the +swarm is named by the first version's hash, so one first version makes one swarm, and a +node joining builds the genesis change and checks it. A swarm strict from its start +records its policy in its genesis change too (`--bootstrap-policy`) *(checked: +`swarm::bootstrap`)*, which starts it empty: content before it would be a change from +before the federation, judged by none. So nothing is from before the federation, and +nothing writes the policy's place after the genesis change: the federation changes by +versions, and is left by a fork. A running swarm doesn't become federated; its parties +start one, and sign into it, after the genesis change, what they keep. ### Remakes @@ -625,7 +625,7 @@ What an attacker does, and what happens. *Unit*: the judging, with crafted chang | 3 | An older envelope written where a newer one is | Refused: `prev`, `seq` | unit | | 4 | An older envelope put beside the newer by a change that saw neither | Taken, and behind | unit | | 5 | A former holder writes a chain at a history where it held the place | Behind what is written under the version that gave the place away | unit | -| 6 | A key set signed by a key the version doesn't name, or by one a later version replaced, at a history from before | Refused; or behind the set the later version set | unit | +| 6 | A key set signed by a key the version doesn't name, or by one a later version replaced, at a history from before | Refused; or, naming a version before the one that named the party's keys anew, it counts no more | unit | | 7 | A key set without the key that signed it | Counts: a set is checked where it is written | unit | | 8 | A version written without the votes, or not changing the current one at its history | Refused at its history | unit | | 9 | A version not in its JCS bytes, a field missing or more, a rule under `_continuum`, without a literal first segment, with `@`, `**` not last, `{party}` twice, or a writer that is no party of it | No version: can't pass, refused where written as one | unit | @@ -673,13 +673,13 @@ What an attacker does, and what happens. *Unit*: the judging, with crafted chang | 51 | A fork at heads of its founder's choosing | Joiners holding the document are told what those heads lack | sim | | 52 | A fork's version giving a party that didn't go keys of its founder's | Joiners holding the document are told, party by party | sim | | 53 | Two founders forking one version at one set of heads | One swarm: the genesis change is built byte for byte | sim | -| 54 | A group whose parties list no nodes forks | Its version sets their node lists | sim | +| 54 | A group whose parties list no nodes forks | Its version names their node lists | sim | | 55 | A federation, or a policy, a node doesn't know | It stops taking changes | unit | | 56 | Two parties each writing a key set beside the other's vote, crossed | Nothing: votes go by their version's keys, at a remake too | unit | | 57 | Content written before a federation's genesis change, and a change built on it | None: the genesis change is the swarm's first | unit | | 58 | A federation's genesis change whose first version lists no node | Nothing after it is taken: no node is a member | unit | | 59 | A version replacing every listed party's keys | The lists still count, each its party's until it writes another | unit | -| 60 | A version written without the key sets or node lists it sets, or those written by another change, or numbered otherwise | Refused | unit | +| 60 | A version whose `since` for a party is neither its own number nor that of the version it changes, or that changes a party's keys or list without naming them anew | No version: refused written as one | unit | | 61 | A version written again late, at a history from before the next, by a member that was away | Taken: it is one every node took | unit | | 62 | A proposal whose text doesn't hash to its place | Refused | unit | | 63 | An honest member writes a version valid where it is written, on the side a node doesn't read | Refused, and reported apart; its committer isn't refused as a whole | unit | @@ -799,20 +799,20 @@ On a federated swarm: ## Stages 1. **The federated policy**: a swarm started federated by its genesis change, with the - key sets and node lists its first version sets; versions and what makes one valid, - rules and paths, values in `@` keys, keys, votes, passing and dead, which version a - node takes and the current one, judging by it; votes and proposals by their version's - keys; the protocol data as listed, all else closed; the `cv3.` envelope with the - meta's version, and the order by it; node lists, a node's party in its configuration, - and no token from another node; what every reading of a strict policy in continuum + node lists its first version gives; versions and what makes one valid, rules and + paths, values in `@` keys, keys, votes, passing and dead, which version a node takes + and the current one, judging by it; votes and proposals by their version's keys; the + protocol data as listed, all else closed; the `cv3.` envelope with the meta's + version, and the order by it; node lists, a node's party in its configuration, and no + token from another node; what every reading of a strict policy in continuum (`strict()`) makes of the federated one; screening's frontier moved by every change touching what the federation reads (versions, proposals, votes, key sets, node lists), as `access::screen` moves it today for what continuum's rules read; the byte - formats (a version's JCS bytes, hashes in paths and how two compare, the envelopes a - version sets, the meta's version); the bound on the writers a node starts in an - epoch; and the sizes a version, a set, a list, a path and a value may have, each - within what a sync message carries. A node that doesn't know the policy stops taking - changes. Until stage 4, a federated swarm takes no remake. + formats (a version's JCS bytes, hashes in paths and how two compare, the meta's + version); the bound on the writers a node starts in an epoch; and the sizes a + version, a set, a list, a path and a value may have, each within what a sync message + carries. A node that doesn't know the policy stops taking changes. Until stage 4, a + federated swarm takes no remake. 2. **What counts**, read by the current version and the keys; shown in the API. Reports of the versions a node refused, and its operator having it drop what it took; a tool reporting, from the votes, a party that voted twice. |
