diff options
| -rw-r--r-- | docs/federation.md | 210 |
1 files changed, 119 insertions, 91 deletions
diff --git a/docs/federation.md b/docs/federation.md index 0778374..5ada122 100644 --- a/docs/federation.md +++ b/docs/federation.md @@ -122,8 +122,9 @@ the first, number 0, which only the genesis change writes; a fork's first, Forks ```json { "federation": 1, "number": 7, "changes": "<hash of the version it changes>", "share": [2, 3], - "parties": ["tv", "lass", "makefu"], - "keys": { "makefu": ["ssh-ed25519 AAAA… makefu"] }, + "keys": { "tv": ["ssh-ed25519 AAAA… tv"], + "lass": ["ssh-ed25519 AAAA… lass"], + "makefu": ["ssh-ed25519 AAAA… makefu"] }, "rules": [ { "path": "names/r/wiki/@", "writer": "lass" }, { "path": "home/{party}/**", "writer": "{party}" }, @@ -136,10 +137,11 @@ the first, number 0, which only the genesis change writes; a fork's first, Forks it changes. * **The share** of the parties a proposal needs, two whole numbers `[a, b]`, 0 < a ≤ b, 2·a > b: with `[2, 3]`, the votes of two of every three (3·votes ≥ 2·parties). -* **The parties**, by name: as continuum's user names, 1 to 64 of `A-Z a-z 0-9 . _ @ - -`, each once. -* **The keys it sets**: those of a party new in it, or of one whose keys the parties - replace (Keys). +* **The parties and their keys**: each party by name, as continuum's user names, 1 to + 64 of `A-Z a-z 0-9 . _ @ -`, with the keys its votes and proposals on this version + are signed with. 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 rules**, in order: the first whose path matches a path says who writes there. A path is segments separated by `/`. A rule's first segment is literal, and not `_continuum`; any other is literal, `{party}` (a party's name), `*` (any one @@ -176,17 +178,19 @@ What a party writes is an envelope, signed by one of its keys. A version, and th version sets, are written unsigned, and count by the votes the version had. A proposal's place takes only the proposal. Of continuum's own data, a federated swarm keeps what nodes write for the protocol (member entries, remakes and their acks, epochs), written -by members as in every swarm; a member's change carries its node's signature, as -signatures are required in a strict swarm. It has no user registry: `_continuum/users`, -bans, and every other entry of `_continuum/access` are closed, and nothing reads them. A -party logs in to its own nodes as its operator sets up, and a node takes tokens only -from the nodes of its own party (Nodes). +by members as in every swarm, but a member's entry by that member only; a member's +change carries its node's signature, as signatures are required in a strict swarm. It +has no user registry: `_continuum/users`, bans, logouts, sessions, forgotten nodes, and +every entry of `_continuum/access`, the policy's place included, are closed: a write +there is refused, and nothing reads them. A party logs in to its own nodes as its +operator sets up, and a node takes tokens only from the nodes of its own party (Nodes). ### Changing the policy A **proposal** is a version a party writes at -`_continuum/federation/proposals/<party>/<hash>`, its hash the version's. Like a vote, -it counts as written, by the keys its party had at its history, until it lapses. +`_continuum/federation/proposals/<party>/<hash>`, its hash the version's, signed with +one of the keys the version it changes names for its party. It counts as written by +those, whatever keys the party writes since, until it lapses. A party **votes** on a proposal by writing `true` or `false` at `_continuum/federation/votes/<party>/<version>/<proposal>`: the version the proposal @@ -195,10 +199,11 @@ changes, and the proposal, by their hashes. No vote there is no vote. * **A vote is taken only where, at its history, its version is current and its proposal is written.** A vote cast at a history from before can't reach a proposal made since. -* **A vote never changes**, and **counts as cast**: by the keys its party had at its - history, whatever keys the party has since. It goes only with its version, when that - is replaced (What counts), and nobody deletes it before. A write at a vote's place - is refused. +* **A vote never changes**, and **counts as cast**: signed with one of the keys its + version names for its party, whatever keys the party writes since. So a vote is + checked from itself and its version alone, by a client too, after the document + dropped it. It goes only with its version, when that is replaced (What counts), and + nobody deletes it before. A write at a vote's place is refused. * **A proposal passes** once at least the share of its version's parties voted `true`. It is **dead** once so many voted `false` that the rest are fewer than the share. * **One yes at a time.** A party's `true` is taken only if, at its history, every other @@ -233,13 +238,13 @@ versions behind it, which may go (What counts). every party's keys (Forks). What the side not read deleted as housekeeping, and counts by the version read, its party's client puts back. * **A party that voted twice shows**: its two votes on one version, both signed with - its keys, each taken where it was cast. A node reports it (a log, the API), with both - votes, from the history: a place holding two votes counts by its read like any - place, and two `true`s are voting twice only where neither proposal was dead at the - other's history. A client keeps the votes, as they are signed and anyone can check - them after the document has dropped them. That proves its keys signed both, not that - it meant to: two of its nodes voting each by itself, or a stolen key, look the same. - Taking it out is the parties' choice, and a fork. + keys the version names for it, each taken where it was cast. A node reports it (a log, + the API), with both votes, from the history: a place holding two votes counts by its + read like any place, and two `true`s are voting twice only where neither proposal was + dead at the other's history. A client keeps the votes, as they are signed and anyone + can check them after the document has dropped them. That proves its keys signed both, + not that it meant to: two of its nodes voting each by itself, or a stolen key, look + the same. Taking it out is the parties' choice, and a fork. * **A proposal on a version that isn't current lapses**, with the votes on that version. @@ -250,20 +255,22 @@ naming another (Changing the federation). ### Keys -A party's keys are at `_continuum/federation/keys/<party>`: one envelope, the set, +A party votes and proposes with the keys its version names for it; everything else it +writes, with its keys at `_continuum/federation/keys/<party>`: one envelope, the set, signed with a key of the set it replaces, numbered as any envelope. 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 (`cv2.<value>.<meta>.`), the keys the version sets and no others, its meta naming that version, the party as its user, `at` -0, `prev` and `seq` as any envelope's, so that its bytes are the version's. It is +0, `prev` and `seq` as any envelope's, the same from every member at one history. It is ahead of every set written under an earlier version, and the party's next set names it as the one it replaces. * **A value counts only while the key that signed it is among its party's keys**, - votes and proposals excepted, which count as written. Changing keys is: write the - new set, and sign again what should stay (a client does that, its deletions too). A - key added back, from a backup say, can bring back what it signed, and what a `null` - of its party covered once that `null` went (What counts). + votes and proposals excepted, which go by their version's. Changing keys is: write + the new set, and sign again, in the same change, what should stay, its node list + among it (a client does that, its deletions too). A key added back, from a backup + say, can bring back what it signed, and what a `null` of its party covered once that + `null` went (What counts). * **Only a version revokes a key.** A party changing its keys by itself adds keys and tidies; but a key it drops can still sign, at a history from before the drop, a set of its own numbered past the party's, and nothing in the document tells which of two @@ -271,8 +278,10 @@ as the one it replaces. destroyed, is answered by a version setting the party's keys, which is ahead of every set before it. What the party then signs again names that version, and is ahead of anything the old key writes at a history from before it. -* **A vote cast with a key before the version that replaced it stays cast**: one - party's votes, on the versions current until then. +* **A party's own key change reaches its votes and proposals** once a version names + its new keys; until then its version's keep voting, as only a version revokes a key. + After a version replaces a party's keys, the party signs its node list again, through + any node that takes its envelopes. ### What counts @@ -286,24 +295,24 @@ whole. These count no more, and nothing else is stale: longer one, the place went to another, a rule changed; and of a party that is no longer one, its keys and its node list; 2. a value signed by a key that isn't among its party's, votes and proposals - excepted; + excepted, which go by the keys their version names; 3. a proposal on a version that isn't current, and the votes on that version; 4. a version behind the current one: of a lower number, or of its number with the higher hash; 5. an envelope behind another at its place; 6. the member entry of a node its own party doesn't list (Nodes); -7. a party's `null` where the deleting change's history holds everything its place - held before it in this epoch, from empty, all signed by keys its party no longer - holds. A `null` the epoch's first change holds goes only at a remake (Remakes), as - what it covers isn't in this epoch's history to judge by. Judging it reads the - place's history: slow, not wrong. +7. a party's `null` where the deleting change's history holds everything its place held + before it or beside it in this epoch, from empty, all signed by keys its party no + longer holds. A `null` the epoch's first change holds goes only at a remake + (Remakes), as what it covers isn't in this epoch's history to judge by. Judging it + reads the place's history: slow, not wrong. **Any member may delete what counts no more**, place by place, never a map holding -places; every node judges the deletion by the document the deleting change makes. That -is the federation's own housekeeping; remakes carry whatever is there. So that -deletions don't flood the document, the one whose write made something stale deletes -it in the same change; others delete only what they find stale, as in a swarm whose -parties went quiet. +places, and a member entry whole; every node judges the deletion by the document the +deleting change makes. That is the federation's own housekeeping; remakes carry whatever +is there. So that deletions don't flood the document, the one whose write made something +stale deletes it in the same change; others delete only what they find stale, as in a +swarm whose parties went quiet. **What is deleted can be put back** where its place is empty, by anyone who holds it, at a history where the version it names is current, and counts if its key is among its @@ -321,10 +330,9 @@ A party lists the nodes that carry for it, by node ID, at 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); it takes tokens only from the nodes that party lists. Another party's list -does nothing. 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. +does nothing. 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. ### Forks @@ -333,7 +341,8 @@ the group won't follow passed, the parties can't agree, or it leaves the federat **forks**: it starts a swarm of its own from the document. 1. One of the group starts the new swarm. Its genesis change holds what the old - document read as at heads it names, as a remake's snapshot does, but for the + document read as at heads it names, built byte for byte as a remake's snapshot is, + so that one version and one set of heads make one swarm, but for the federation's versions, the keys they set, continuum's member entries and the swarm's name: of versions, only the group's own, the fork's first. It names the highest version at those heads as the one it changes, is numbered one past it, and sets @@ -382,12 +391,14 @@ 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 writes the federated -policy and the first version, with the keys it sets, as a swarm strict from its start -records its policy (`--bootstrap-policy`) *(checked: `swarm::bootstrap`)*. 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 what they keep. +A federation starts with a swarm of its own: its genesis change, the swarm's first, +writes the federated policy and the first version, with the keys it sets, as a swarm +strict from its start records its policy (`--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 @@ -403,21 +414,22 @@ is continuum's as in every swarm. What a federated node asks of a remake: chain of envelopes that leads from what the new document holds there to what the old one reads, each in a change of its own, judged again in the new epoch, the other writes with them, each after those its change builds on, clocks only between changes - neither of which saw the other, as continuum replays under a strict policy - *(checked: `remake::delta`)*. Versions written after the base go with them, each in - one change with the keys it sets, whatever names a version before the next, each - judged by the votes replayed before it. Of changes neither of which saw the other, a - party's votes go before its key sets, so that a vote is replayed where its key is its - party's, as where it was cast. Whether a place is held already goes by version - number, then `seq`. What the new epoch refuses (its key was dropped by a version, its - place given to another) goes to the quarantine of the node that holds it, and its - party signs it again if it still may. -* **Housekeeping after the base** isn't replayed: what it deleted is stale again, and - is deleted again. But where a chain starts on an empty place (`prev` empty) and what - the new document holds there counts no more by what was replayed so far, the - replaying node deletes that in the first link's own change, judged by the document - that change makes, as housekeeping is; the link is checked against the place as the - deletion leaves it. + neither of which saw the other, as continuum replays under a strict policy *(checked: + `remake::delta`)*. Versions written after the base go with them, each in one change + with the keys it sets, whatever names a version before the next, each judged by the + votes replayed before it. Votes and proposals go by the keys their version names, + which is replayed before them, so they count as cast in the new epoch too, whatever + key sets of their party are replayed around them. Whether a place is held already goes + by version number, then `seq`. What the new epoch refuses (its key was dropped by a + version, its place given to another) goes to the quarantine of the node that holds it, + and its party signs it again if it still may. +* **Housekeeping after the base** isn't replayed: what it deleted is stale again, and is + deleted again, but for a `null` that went by rule 7 (What counts), which the snapshot + holds, so that it goes only at the next remake. And where a chain starts on an empty + place (`prev` empty) and what the new document holds there counts no more by what was + replayed so far, the replaying node deletes that in the first link's own change, + judged by the document that change makes, as housekeeping is; the link is checked + against the place as the deletion leaves it. * **A party's `null`** is left out of the snapshot once a version later than the one it names is current: nothing naming an earlier one can be written in the new epoch, and an empty place reads as one holding `null` does. One the snapshot keeps goes @@ -425,15 +437,13 @@ is continuum's as in every swarm. What a federated node asks of a remake: A remake's base is its coordinator's word, so all this holds for any base, not only a recent one. So a remake decides nothing that counts, but what it can't hold: of two -envelopes of one version and `seq` at a place at the base, the snapshot keeps one, and -a write after the base on the other, an envelope put back after it on one the snapshot +envelopes of one version and `seq` at a place at the base, the snapshot keeps one, and a +write after the base on the other, an envelope put back after it on one the snapshot lacks, or a write after it on a `null` the snapshot left out, goes to the quarantine, -and its party writes again. So does a vote cast under a key set its party wrote beside -another, the one not read: a party writing two key sets at once is answered as one -voting twice. A swarm that never remakes stays as -correct as one that remakes all the time; it only grows slower. A remake does end one -thing: nothing is written at a history from before it, so what a dropped key or a -node taken off its list could still write there ends with it. +and its party writes again. A swarm that never remakes stays as correct as one that +remakes all the time; it only grows slower. A remake does end one thing: nothing is +written at a history from before it, so what a dropped key or a node taken off its list +could still write there ends with it. A node that doesn't hold the epoch before (it joins, or was away) can't check: it takes the epoch its peers give it. @@ -476,7 +486,14 @@ Recommendations, not rules: none of these breaks a promise, only how fast a node unless some party's `true` and `false` for it are both there. Without a party voting twice, at most one version changes a version. With one, nodes still read the same version once they hold the same changes, and the parties fork. -3. **Carrying on.** A fork is a swarm of its own, named by its first version and the +3. **Remakes.** A node follows a remake only where its snapshot reads as the old + document did at the base, which it checks. What came after is replayed in history's + order, each change judged as every node judges it: versions by the votes replayed + before them; votes and proposals by the keys their version names, which comes + before them; envelopes as chains, from what the snapshot holds, by version, then + `seq`. So what counted, counts, but what a remake can't hold (Remakes), each of which + its party writes again. +4. **Carrying on.** A fork is a swarm of its own, named by its first version and the heads it names, joined by its operators' choice only. A party nobody follows carries on alone. @@ -500,7 +517,7 @@ What an attacker does, and what happens. *Unit*: the judging, with crafted chang | 11 | `true` and `false` on one proposal at once | Both held; a node that saw only one may write a version. As 10 | unit, every order | | 12 | A vote changed, or deleted while its version is current | Refused | unit | | 13 | A vote cast at a history from before, on a proposal made since | Refused: its proposal isn't written there | unit | -| 14 | A party changes keys after voting, or beside its vote | Its vote counts as cast, at a remake too: replayed before the key set | unit | +| 14 | A party changes keys after voting or proposing, or beside its vote or proposal | It counts as cast, by its version's keys, at a remake too | unit | | 15 | Votes split, honestly or not | Nothing passes; nays make the proposals dead, and another passes | unit | | 16 | The parties beyond the share never vote, or vote `false` on everything | Nothing passes; the others fork | sim | | 17 | The party a version takes out writes that version itself | Written: a version counts by its votes, not its writer | unit | @@ -535,10 +552,15 @@ What an attacker does, and what happens. *Unit*: the judging, with crafted chang | 46 | Two envelopes of one version and `seq` at a base, a write after it on the one not kept | Quarantined; its party writes again | unit | | 47 | A `null` deleted while what it covers could still count, or one the epoch's first change holds | Refused, by the deleting change's history | unit | | 48 | 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 | -| 49 | A party writes two key sets at once and votes under the one not read | At a remake, the vote may be refused: as voting twice, the parties fork | unit | -| 50 | A coordinator records an old base | Everything after it is replayed, each as every node judges it | sim | -| 51 | A write after a base on a `null` the snapshot left out | Quarantined; its party writes again | unit | -| 52 | A version written without the keys it sets, or keys written by another change | Refused | unit | +| 49 | 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 | +| 50 | Content written before a federation's genesis change, and a change built on it | None: the genesis change is the swarm's first | unit | +| 51 | A party's node writing another node's member entry | Refused: an entry is its member's | unit | +| 52 | A `null` and an envelope of its party at once, the `null` read | Rule 7 waits for both: the `null` stays while the envelope could count | unit | +| 53 | Two founders forking one version at one set of heads | One swarm: the genesis change is built byte for byte | sim | +| 54 | A party's node writing logouts, sessions or forgotten nodes | Refused: closed | unit | +| 55 | A coordinator records an old base | Everything after it is replayed, each as every node judges it | sim | +| 56 | A write after a base on a `null` the snapshot left out | Quarantined; its party writes again | unit | +| 57 | A version written without the keys it sets, or keys written by another change | Refused | unit | ## Roads not taken @@ -567,6 +589,9 @@ What an attacker does, and what happens. *Unit*: the judging, with crafted chang as a tie broken by hash would let a change made later to look as old take the place of the one every node took. A federation started by its genesis change needs none of it. +* **Votes counted by the keys their party had at their history.** A remake replays a + vote and its party's key set in an order of its own, and where two parties' key sets + and votes cross, no order keeps every vote. The keys a version names don't move. * **Freezing the policy once two versions share a number.** One party could stop the federation at every close vote; the lower hash keeps nodes agreeing until the parties fork. @@ -605,18 +630,21 @@ On a federated swarm: and lets the others in as they turn up; * its names under `names/r/tv/` and `names/w/tv/` by one rule each, its address blocks by a rule each; other names given by versions; +* kartei's entries signed in by their parties after the genesis change, never as + content before it; * a tool reads what counts and writes what kartei's consumers read today. ## Stages 1. **The federated policy**: a swarm started federated by its genesis change; versions - and what makes one valid, rules and paths, keys, votes, passing and dead, the - current version, judging by it; the meta's version - number and the order by it; node lists, a node's party in its configuration, and - tokens from one's own party's nodes only; continuum's readings of a policy and of an - envelope taking the federated policy and the meta's version beside the six fields - it has today. A node that doesn't know the policy stops taking changes. Until stage - 4, a federated swarm takes no remake. + and what makes one valid, rules and paths, keys, votes, passing and dead, the current + version, judging by it; votes and proposals by their version's keys; the protocol + data closed but for member entries, each its member's, remakes, acks and epochs; the + meta's version number and the order by it; node lists, a node's party in its + configuration, and tokens from one's own party's nodes only; continuum's readings of + a policy and of an envelope taking the federated policy and the meta's version beside + the six fields it has today. 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. Housekeeping. Reports of a party that voted twice. 3. **Nodes**: membership by the node lists and the party a node's own entry names, a @@ -626,7 +654,7 @@ On a federated swarm: 5. **Forks**: a swarm started from another's document, named by its first version and the heads it names, and the check against it. 6. **The registry**: the rules for krebs, the tool that signs kartei's entries in as - their parties', and the one that reads them out. + their parties', after the genesis change, and the one that reads them out. Each stage's tests are its rows of Attacks. Each stage keeps every swarm that isn't federated as it is, its tests passing untouched. |
