aboutsummaryrefslogtreecommitdiffstats
path: root/docs/openapi.yaml
Commit message (Collapse)AuthorAgeFilesLines
* api: a swarm holding a store at a node's APItv19 hours1-0/+230
| | | | | | | | | | | | | | | | | | | | | | Behind the `federation` feature, a node of a swarm holding a store has, at its API (`docs/store.md`, Members; `docs/openapi.yaml`, Events): * `GET /events`: its store's ID, its checkpoint's, its heads, and how many events it took after its checkpoint; * `POST /events`: an event put, whoever signed it, offered to the store and written into the document at its ID unless the store refuses it (`422`, with why): taken, held, or waiting for what it builds on; * `GET /events/{id}`: an event the store holds, or its checkpoint, as its bytes; * `GET /events/counts`: what counts as the store reads now: the current version, each party's keys and nodes, the values at places, the members; * `GET /events/refused`: what the store refused, its own refusals apart, its operator's drops, and the rest with why; * `POST /admin/events/drop` and `/admin/events/allow`: its operator has it drop what it took, and take it back. The events' endpoints are anyone's this node lets in, as the store's are; dropping and taking back need `write` on `_continuum`, as what operators do. While a node holds no store, they answer `404`.
* federation: the store read from the documenttv20 hours1-2/+2
| | | | | | | | | | | | | | | | A node of a swarm holding a store holds the store, read from its document (`docs/store.md`, What the store takes from the document): `federation::held`. Whenever the document changes, a worker reads the events it holds that the store wasn't offered from it, under the document's lock, and offers them to the store without it, each taken as from anywhere: once its dependencies are held, judged at its history. Another document (a drop, a rejoin) is read as it comes, the store going on. The node reads its store anew from its document whenever it starts, from the root, by what is its own of it: the events it refused by what it took before, and those its operator had it drop, which it keeps in a file (`--store-file`), written whenever that changes, so that a store read anew in another order refuses what it refused before. A file that doesn't read stops the node from starting; without one, a restart may take what it refused.
* node: a swarm holding a store, started from its root or joined by its IDtv20 hours1-1/+2
| | | | | | | | | | | | | | | | | | | | Behind the `federation` feature, two options: * `--store-root PATH` starts a swarm holding a store, or goes on with one, from the store's root, as bytes in the file, which the federation must take as a root. With no document to start on, the node builds the genesis change from it, as every node given the root does, and is ready at once; a document to start on must be of the root's swarm. * `--store-id ID` joins one through seeds by its ID, the root's SHA-256 in hex. An empty document of the first epoch takes as its root only that store's genesis change, built again from the root it holds (`document::events::is_genesis`), whatever peers name: the root pin doesn't wait for seeds, nor is disputed. Either names the swarm the node joins, which a state file must remember too, and can't be combined with the other, nor with what makes a new swarm's first change (`--genesis`, `--bootstrap-users`, `--bootstrap-keys`, `--bootstrap-policy`, `--remake`, `--genesis-root`). The root is read as a file of its own kind (`store`), counted among the node's files.
* store: a signed value chosen by seq is named sotv2 days1-1/+1
| | | | | | | | Where the policy asks for signed values, a place's value is chosen by `seq`, but conflict reports still called the choice `newestWins`, and the code and the architecture still said "newest" of what a read shows. A report names it `highestSeq`; the rest says "the one a read shows".
* signed values: value and meta apart, numbered; the highest seq is readtv2 days1-4/+5
| | | | | | | | | | | | | | | | | | | | | | | | | A member could put a user's older signed value back beside a newer one: a change made with dependencies from before both is judged where the place was empty, so the older envelope (`prev` empty) is taken; and of values written at once, the one read was the one with the highest operation, which whoever writes the change steers. A revoked capability, a lifted ban or an earlier policy came back that way, signed by whoever signed it then. An envelope is now `cv2.<value>.<meta>.<signature>`: the value as its user wrote it, and apart from it what continuum adds (swarm, path, user, at, seq, prev), the signature over the value's line and the meta's. `seq` is one more than that of the envelope it replaces, 0 where it replaces none; every node checks it with `prev`. Of the values a place holds, written at once, signed ones are read before any other, the highest `seq` first, of equal ones the lower digest (`store::candidates`): reads, snapshots and writes all go by it. An older envelope beside a newer one changes nothing. `application/continuum-signed` is the value's line, the meta's, then the signature; `scripts/continuum-signed` writes and checks it so. The wire version goes up: nodes must agree on what a place's value is.
* auth: whoami says what the request may dotv8 days1-1/+1
| | | | | | | | | `GET /auth/whoami` lists the user's capabilities (`caps`) and its token's `limit`, if any, side by side; what the request may do is what both give, as endpoints decide it. It says so now (`may`): the capabilities, or with a limit each capability met with each of the limit's (`Capability::meet`): at the deeper of the two paths, a `*` of one taking the other's key there, with the rights both name; nothing where the paths part, no right is shared, or the path is protocol data one of them doesn't name.
* access: ending a single sessiontv8 days1-2/+7
| | | | | | | | | | | | | | | | | | | | Logging out of the dashboard (`DELETE /auth/session`) only cleared the cookie: the session's tokens stayed taken until they expired, by every node. Ending them took `POST /auth/logout`, which ends all of a user's sessions. Now `DELETE /auth/session` ends the session of the token it comes with (the cookie, or a bearer token): where the swarm has a registry, it is recorded as `_continuum/sessions/<user>/<session>` (`registry::session_path`), its value until when the session would have lasted, and every node refuses the session's tokens once the change reaches it (`token::Refused::Ended`): the page's own, its narrow tokens, and one handed to another member's dashboard, all refreshed from it and keeping its ID. The rules take the entry from the user itself or one who manages users, as a logout. A remake's snapshot leaves out entries past that time, a user's map where none is left: their tokens are expired anyway. Without a registry the document can't record it: the node ending it refuses the session's tokens itself (`AppState::ended_sessions`, until it restarts), others take them until they expire, as a logout there is refused.
* dashboard: a subscribed node's message written out, read from it when showntv8 days1-0/+27
| | | | | | | | | | A subscribed node's messages come without being written out (their stream leaves the text out: up to 8 KiB each, 500 at a time), so the figures box said only when, both ends, type and size of one. Now the node answers for one message by its number, `GET /admin/dashboard/messages/own/{seq}` (`{"text": …}`, `404` once it isn't kept), which pages of other origins may call as they do its streams (`cors::open`), and the page reads it when the message is shown, with its narrow token, and keeps it on the message. Where it can't be read, the box says why.
* access: what a node holds alone by `_continuum/local/<node ID>/<name>`tv9 days1-2/+2
| | | | | | | | | | | | | | | | Setting a node's log filter took `write` on `_continuum`, all of the protocol data: whoever could change one node's logging could change the swarm's members, remakes and users too. Now what a node holds alone has paths of its own for capabilities, under `_continuum/local/<node ID>/`: `log` (`/admin/log`), `config` (`/admin/config`) and `debug` (`/debug`, always `write`), `read` to look and `write` to act (`api::access::needed`, which takes the node's ID). So `_continuum/local/<node ID>` is everything on one node, `_continuum/local/*/log` the log filter on every node, and holders of `_continuum` keep it all. Nothing is stored there: the store refuses writes under `_continuum/local`, and the rules refuse a change touching it, as for epoch metadata. The quarantine stays with `_continuum`: its entries are everyone's writes, which a node-local capability mustn't show.
* remake: replayWindow and archiveRetention in an octet-stream import's querytv9 days1-0/+10
| | | | | | | An import uploaded as `application/octet-stream` takes `rules`, `baseHeads`, `settle` and `switchDelay` in the query, but not the retentions: for those the document had to go base64-encoded in the JSON form. Now `replayWindow` and `archiveRetention` go in the query too, as JSON like the rules (`{"epochs":1,"age":"7d"}`, as in the body).
* dashboard: keys edited, the last removed with a password, failures kepttv9 days1-2/+4
| | | | | | | | | | | | | | | | | | | | | The credentials dialog listed a user's keys whole, to add one or remove one but the last, and any failure replaced the dialog with the error, the form lost. * A key is shown short: its type, the first and last four characters of what tells it apart (an Ed25519 key's base64 after the part all of them share), its comment; the whole line in its tooltip. * A key can be edited, its name and its line: saved under the name, a new name written first and the old one removed. * A user with a password on this node (`--htpasswd`) may remove its last key: it logs in by the password. GET /auth/keys says so (`password`), and DELETE /auth/keys/{id} takes it then; the rules no longer keep the last key on every node (no other node can tell who has a password where; under a strict policy the signed entry keeps one still). * What fails says why beside where it was asked (the add form, the edited row, the removed one), which stays as it was, to be set right and tried again.
* roots: an epoch's root pinned, and named in every handshaketv9 days1-0/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Review 2, N7, the care it raised: a joining node's empty document took as the first epoch's root whatever dependency-less change came first, from whichever peer it joined through; the first epoch's ID is all zeros, so nothing pinned it. A remake's epoch has its ID, the snapshot change's hash, which the rules hold its root to. * Every node names its epoch's root in HELLO and HELLO_REPLY (the epoch's ID for a remake's, its genesis change for the first; wire version 45). A node whose document starts from another root of the same epoch refuses the handshake, logging it: another history under the swarm's ID, a forged root or a genesis started again. * A joining node with an empty document takes as its root only the one it was given (--genesis-root, new), else the one its peers name, and none while they name different ones (access::screen::RootPin, kept in Screening across documents): one peer hands it another root only if it is all the joiner hears, or never, with --genesis-root. A root refused is listed with the refused, what builds on it with it. * The genesis node logs the root (`The swarm's root`); GET /admin/epochs shows it (`root`). A genesis started again under a remembered swarm ID used to merge with the nodes of it still running; they now refuse it (another root), and the docs say to join them with seeds instead. The epoch's identity stays as it is (generation 0 all zeros): records and epoch metadata name it so, and every comparison of epochs with them.
* remake: turning a running swarm strict, keeping what an operator signedtv9 days1-1/+33
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Until a swarm is strict, the user a change names is its node's word, so any member could have planted registry entries, policy, bans or user-signed values as any user, plain or signed by a key it put there itself; writing the strict policy trusted all of it as it was. A remake of a new kind, `strict`, turns a swarm strict instead: * Its content is a manifest (access::strict): the swarm, the strict policy, and each value kept at the places values are signed, by the SHA-256 of its JSON, signed by an operator (ssh-keygen -Y sign -n continuum-strict). * Every node builds the next epoch as compaction does, keeping at the signed places only the values the manifest names, as they were at the base, and writing its policy (RemakeKind::protocol, the one kind that changes protocol data). Writes after the base reach the new epoch only by replays, judged by the strict policy. * A node votes for one only with its manifest signed by one of --strict-keys, keys given out of the document; without any, for none (logged once, `Not voting for a strict remake`), unless --follow-strict-remakes. A coordinator proposes only what it would vote for (403). Once a majority commits one, every node switches, as with any remake: refusing to switch would only cut a node off. * GET /admin/strict-manifest gives the manifest keeping everything held now, the values for review and the heads they are at; continuum-signed strict shows them, signs once confirmed and proposes at those heads. The sim a_swarm_turning_strict_through_a_remake: a member plants a registry entry as a manager; the operator's manifest leaves it out; a and b, given the key, commit; c, without, follows; the entry is gone and the policy strict everywhere.
* users: a user manages its own keystv9 days1-0/+43
| | | | | | | | | | | | | | | | | Only a user who may manage users could change a user's keys: a user couldn't add a new laptop's key, or remove a lost one. A user now manages its own keys, whatever else it may do: * GET /auth/keys: its keys, its entry, and the envelope holding it under a strict policy (`signed`), to sign against. * PUT /auth/keys/{id} with an authorized_keys line, DELETE /auth/keys/{id}: one change, as the user. The rules take a write of _continuum/users/<name>/keys/… from the user it names. * Under a strict policy, the user signs its entry with only its keys changed, with a key it holds already (envelope::check takes that from the user itself), PUT to its own entry even without write on the registry; continuum-signed key-add and key-remove do so.
* dashboard: log out of this browser, and say what can't betv9 days1-0/+1
| | | | | | | | | | | | | | The dashboard had no way to log out; only the login page did. It now shows the user beside the connection, and "log out" where the page got in by its session: that ends this browser's session (DELETE /auth/session), other sessions of the user going on, and opens the login page. Where it got in by what it can't end, the browser's password or the proxy's, it says so instead (the token answer now names `login`, how the user proved it). After logging out, a page still let in by the browser's password says so too. A list of a user's sessions, to end one by one, is in future-work.md.
* envelope: a signed value names its swarmtv9 days1-2/+2
| | | | | | | | | | | | Review 3.1, part of finding 12: a signed value's payload bound path, user, time and prev, but not the swarm. A user with the same name and key in two swarms could have an envelope replayed from one into the other, wherever the path holds no envelope yet (prev ""). The payload now names the swarm (`swarm`), and a node takes an envelope only for its own. /auth/whoami says the swarm, and continuum-signed and the example in api.md sign it. Wire version 44: nodes before this refuse such envelopes, and those after refuse the old ones.
* login: a token asked to live less ends its session with ittv9 days1-1/+1
| | | | | | | | | | | | Review finding 8, first part: a refreshed token's lifetime came from the refresh request, and it kept the session's end. So the five-minute read-all token a dashboard hands to another member's refreshed into a 12-hour one, renewable for seven days. A token asked to live less (`lifetime`, at login or refresh) now ends its session with it: nobody refreshes it past its end, its holder included, and a session begun from it (POST /auth/session) ends then too.
* remake: replay from the quarantine where the user may writetv9 days1-3/+13
| | | | | | | | | | POST /admin/quarantine/{id}/replay needs write on _continuum, which never covers user data, and replayed every path of the entry as the user who asked: every node refused the user data in it. It now replays only the paths the user may write and keeps the rest in the entry (left), for one who may; 403 if the user may write none. Review finding 3 (quarantine replays).
* dashboard: a token handed over to another member's dashboardtv10 days1-0/+3
| | | | | | | | Opening another member's dashboard passes a token reading only, for five minutes, in the URL's fragment; its login page begins a session with it. Tokens may be asked for with a shorter lifetime. Auth plan M3 (hand-off).
* swarm: changes taken unjudged, dropped (REFUSALS)tv10 days1-1/+4
| | | | | | | | | A node refusing changes a peer brought tells it which broke a rule; the peer judges them itself, and if its rules refuse them too, drops them with all built on them (its document forked without them, a fresh actor), quarantining its own writes among them. Wire version 42. Auth plan M6 (rejoin on taint).
* access: members refused as a wholetv10 days1-1/+10
| | | | | | | | | With signatures required, a member whose own change broke a rule is refused as a whole: sent nothing, shown in /peers (refused), in stats (sync.refusedPeers) and on the dashboard, until a change of its is taken again or the epoch changes. Auth plan M6 (diverged standing).
* auth: the session cookie lets in reads onlytv10 days1-1/+2
| | | | | | | | The cookie lets in GET, HEAD and the session's own requests; anything changing something brings the token itself, which no page of another site or port can make a browser send. The dashboard's writes send it. Auth plan M3 (browsers).
* auth: a login page and browser sessionstv10 days1-0/+50
| | | | | | | | | GET /login without authentication: log in by password or with a token (from a login by key). POST/DELETE /auth/session keep the token as an HttpOnly, SameSite=Strict cookie; the dashboard sends a browser without a user there and renews the session while open. Auth plan M2/M3 (browsers).
* access: values sealed for their readerstv10 days1-2/+2
| | | | | | | | | | cs1.<age file>: a value encrypted with age to its readers' SSH keys, which no node decrypts. _continuum/access/sealed declares paths whose values must be sealed, for named readers or anyone; nodes check the recipients by age's key tags, at the API and on receipt. Auth plan M8, reworked: sealed values instead of containers, readers as users only (nodes hold no keys).
* auth: logging in by keytv10 days1-0/+57
| | | | | | | | POST /auth/challenge and /auth/login/key: a node-signed challenge, valid five minutes and taken once, signed with one of the user's SSH keys (ssh-keygen -Y sign -n continuum-login), for a token. Auth plan M7 (key login, M2b).
* api: signed values at the storetv10 days1-8/+37
| | | | | | | | | PUT with application/continuum-signed writes an envelope where values are signed (403/409 saying why); reads open envelopes and name the signer (x-continuum-signed-by), ?raw=true shows them. Under strict, unsigned writes reaching a signed value and the users API are 409. Auth plan M7.
* access: logouts apart from users' entriestv10 days1-1/+1
| | | | | | | | _continuum/logouts/<name> holds when a user's tokens were last revoked, written by the user itself or by one who may manage users, so users' entries can be signed by their managers alone. Auth plan M7.
* access: the policy enforcedtv10 days1-0/+34
| | | | | | | | _continuum/access/policy ({"version": 1}) has every node screen every change it receives, on every path changes come in. A policy a node doesn't know stops its writes through the API. GET /admin/refused. Auth plan M6.
* signatures: verified changestv10 days1-2/+8
| | | | | | | GET /admin/changes shows whether a signature by its node vouches for each change. Auth plan M5.
* signatures: on their own (SIGNATURES)tv10 days1-1/+4
| | | | | | | Signatures no sync message took go on their own within a second, to each peer not sent them yet (wire version bumped). Auth plan M5.
* signatures: changes signed by their nodetv10 days1-0/+14
| | | | | | | | | | Every node signs the changes it commits with its node key, an Ed25519 signature over the change's hash, kept beside the document. One signature on an actor's latest change vouches for its earlier ones. Protocol data and paths listed in _continuum/access/signed are signed, and writes with ?signed=true. Auth plan M5.
* access: no manages flagtv10 days1-2/+1
| | | | | | | GET /admin/users no longer lists a manages flag per user: whether a user may manage users follows from its capabilities. Auth plan M1 (cleanup).
* dashboard: without LINKS; LINKS removedtv10 days1-31/+7
| | | | | | | | | The dashboard reads every member's links from the members themselves; LINKS and LINKS_REPLY, swarm::links and their wire tags go (wire version bumped). Nodes the browser can't reach are drawn from what the reachable ones measure. Auth plan M3.
* dashboard: subscribed nodes' messages in the consoletv10 days1-3/+9
| | | | | | | Each tick's messages of a subscribed node, listed in the console with this node's own, from its own stream. Auth plan M3 (live data from every reachable node).
* dashboard: subscribed nodes' messages as dotstv10 days1-0/+14
| | | | | | | The page reads a subscribed node's message counts from it too, and draws them as dots on the map, as this node's own. Auth plan M3 (live data from every reachable node).
* dashboard: own links over the API, and CORStv10 days1-0/+35
| | | | | | | | | GET /admin/dashboard/links/own and its event stream: a node's own links, as LINKS_REPLY carried them, for other members' dashboards with a token. CORS for the members' dashboard origins and --cors-origins, without credentials. Auth plan M3.
* auth: logging in, and tokens as bearerstv10 days1-0/+112
| | | | | | | | | POST /auth/login (by htpasswd or the proxy), /auth/refresh, /auth/logout, GET /auth/whoami; every request may bring Authorization: Bearer instead of a password. --token-lifetime and --session-lifetime. Auth plan M2.
* access: the users endpointstv10 days1-0/+180
| | | | | | | | /admin/users: list, add (one or several), remove, disable, grant and revoke capabilities; each one change, refused if it would lock its writer out. Capabilities as the store's paths name them. Auth plan M1.
* access: authorization at the APItv10 days1-2/+2
| | | | | | | | | Every request is judged by the registry the node holds: store reads pruned to what the user may read, writes refused where it may not, admin endpoints by protocol capabilities. Without a registry, as before (--protocol-writers for protocol data). Auth plan M1.
* HyParView (slim)tv11 days1-1/+4
|
* plumtreetv11 days1-1/+4
|
* indirect probestv11 days1-1/+4
|
* handshakes countedtv11 days1-1/+4
|
* trees at runtimetv11 days1-1/+5
|
* dashboard: add epoch switch indicatortv13 days1-1/+3
|
* dashboard: map remake votestv13 days1-1/+3
|
* dashboard: swarm-wide epoch shinetv13 days1-2/+2
|
* asked again countertv13 days1-1/+4
|
* neigbours by transporttv13 days1-1/+6
|
* own tree shapetv13 days1-1/+19
|