aboutsummaryrefslogtreecommitdiffstats
path: root/docs/api.md
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-15 12:28:33 +0000
committertv <tv@krebsco.de>2026-11-15 12:28:33 +0000
commit6be5646df342b21fe82c63f59cfec5a369ab54f8 (patch)
tree48ede9923ab4fa762623a6e32b9b18a088276b98 /docs/api.md
parentd1d081cf8e0e8bb5809c1c82bbdfec6bd7ad0285 (diff)
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.<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.
Diffstat (limited to 'docs/api.md')
-rw-r--r--docs/api.md20
1 files changed, 12 insertions, 8 deletions
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