From 6be5646df342b21fe82c63f59cfec5a369ab54f8 Mon Sep 17 00:00:00 2001 From: tv Date: Sun, 15 Nov 2026 12:28:33 +0000 Subject: signed values: value and meta apart, numbered; the highest seq is read 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...`: 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. --- docs/access.md | 12 +++++++++--- docs/api.md | 20 ++++++++++++-------- docs/openapi.yaml | 9 +++++---- 3 files changed, 26 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/access.md b/docs/access.md index c03f7c4..2f7fa5a 100644 --- a/docs/access.md +++ b/docs/access.md @@ -426,9 +426,15 @@ Signed then are what decides who may do what (every user's entry, every entry of `_continuum/access`, every ban), and the paths listed at `_continuum/access/userSigned`, a list of paths as capabilities name them, `*` for any one key: `[["config"], ["servers", "*", "secret"]]`. Each such value is an envelope, one string -(`cv1..`): the payload names the path, the value (`null`: deleted), -the user, when, and the envelope it replaces (`prev`), and the signature is the user's -over it, as `ssh-keygen -Y sign -n continuum-value` makes it, with one of its `keys`. +(`cv2...`): the value as its user wrote it (`null`: deleted); +apart from it, the meta, which names the swarm, the path, the user, when, the envelope +it replaces (`prev`) and its number (`seq`, one more than that one's, 0 where it +replaces none); and the user's signature over both, as +`ssh-keygen -Y sign -n continuum-value` makes it, with one of its `keys`. Where a place +holds several envelopes, written at once, the one with the highest `seq` is its value +(of equal ones, the one with the lower SHA-256), before anything that isn't one: so an +older envelope put back beside a newer one, by a change made not to see it, changes +nothing, whatever the order of the changes' operations. `scripts/continuum-signed` is a reference client, with `ssh-keygen`, `curl` and `jq`: it logs in by key, writes and deletes signed values (`put config '{"mode": "fast"}'`), and checks one against its user's keys (`verify config`). diff --git a/docs/api.md b/docs/api.md index 2665306..41a4f4d 100644 --- a/docs/api.md +++ b/docs/api.md @@ -164,7 +164,8 @@ way on every node: * **The same key**: one write wins, the same one everywhere. "Newest" means by Automerge's operation order (the write made after seeing more changes; between equals, by the writer's actor ID), not by any clock: of two truly concurrent writes, which wins - is arbitrary, but it is the same on every node. + is arbitrary, but it is the same on every node. Values their users signed come first + (Signed values, below): of those, the one its user numbered highest (`seq`). * **Maps written at the same key** merge into one: their keys are united, each key as above. * **A write and a delete** of the same key: the write stays (a delete removes only what @@ -312,17 +313,20 @@ document. ## Signed values Where the swarm has its users sign values ([`access.md`](access.md), Values signed by -their users), a user writes one by signing it with its SSH key: the payload, one line -of JSON, then the signature, as `application/continuum-signed`. +their users), a user writes one by signing it with its SSH key: the value, one line of +JSON; the meta, one line of JSON; then the signature of those two lines (without the +second's newline), as `application/continuum-signed`. ```sh # The swarm it is for; the envelope there, if any, and what replaces it names: its -# SHA-256 (none: ""). +# SHA-256 (none: "") and the number after its own (none: 0). swarm=$(curl -sf -u alice localhost:3000/auth/whoami | jq -r .swarm) read=$(curl -sf -u alice -H 'Accept: text/plain' 'localhost:3000/store/config?raw=true') prev=${read:+$(printf %s "$read" | sha256sum | cut -d' ' -f1)} -printf '{"swarm":"%s","path":["config"],"value":{"mode":"fast"},"user":"alice","at":%s,"prev":"%s"}' \ - "$swarm" "$(date +%s000)" "$prev" > payload +meta=$(printf %s "$read" | cut -d. -f3 | tr _- /+ | jq -Rr '@base64d') +seq=${meta:+$(( $(printf %s "$meta" | jq .seq) + 1 ))} +printf '{"mode":"fast"}\n{"swarm":"%s","path":["config"],"user":"alice","at":%s,"seq":%s,"prev":"%s"}' \ + "$swarm" "$(date +%s000)" "${seq:-0}" "$prev" > payload ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n continuum-value payload { cat payload; echo; cat payload.sig; } | curl -X PUT localhost:3000/store/config \ -u alice -H 'Content-Type: application/continuum-signed' --data-binary @- @@ -330,8 +334,8 @@ ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n continuum-value payload The node writes it as its envelope if the authenticated user signed it (`403` if not), for this swarm and this path, with one of its keys, may write there (`403`), and it replaces what is -there (`prev`, the SHA-256 of the envelope it replaces; `409` if it names another: -read again and sign anew), and only where values are signed (`409` elsewhere). It +there (`prev`, the SHA-256 of the envelope it replaces, and `seq`, one more than that +one's; `409` if it names another: read again and sign anew), and only where values are signed (`409` elsewhere). It answers with the value, as a `PUT` does; a signed `null` deletes, with `204`. It stays as an envelope (reads show nothing there), so the value written next names it in `prev`: the chain goes on through deletions, and an envelope from before one can't be diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 1b4a199..5728da5 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -110,7 +110,7 @@ paths: - $ref: '#/components/parameters/at' - name: raw in: query - description: Values their users signed as stored, as envelopes (`cv1..`), to check them. + description: Values their users signed as stored, as envelopes (`cv2...`), to check them. schema: type: boolean default: false @@ -158,8 +158,8 @@ paths: `application/vnd.continuum.timestamp; format=rfc3339|unix|unix-ms|http-date`; a body that isn't one is `400`, saying why. - A value its user signed (`application/continuum-signed`: the payload's line of - JSON, then its armored SSH signature; `api.md`, Signed values) is written as its + A value its user signed (`application/continuum-signed`: the value's line of + JSON, the meta's, then the armored SSH signature of both; `api.md`, Signed values) is written as its envelope where values are signed: by the authenticated user, for this path, with one of its keys, replacing what is there. A signed `null` deletes (`204`). parameters: @@ -192,7 +192,8 @@ paths: schema: type: string example: | - {"swarm":"6f9a…","path":["config"],"value":{"mode":"fast"},"user":"alice","at":1762400000000,"prev":""} + {"mode":"fast"} + {"swarm":"6f9a…","path":["config"],"user":"alice","at":1762400000000,"seq":0,"prev":""} -----BEGIN SSH SIGNATURE----- U1NIU0lH… -----END SSH SIGNATURE----- -- cgit v1.3.1