russell@unturf.com
c7275b5618
Adds docs/mesh.md and five graphviz diagrams covering the federation layer: identity stack, epoch state machine, per-member secret envelope, gossip wire contract, and operator decision tree. Pins the protocol contract for the upcoming HTTP wire (mesh sync, mesh serve). Makefile gets a 'docs' target with pattern rule so PNG renders are incremental from .dot sources.
63 lines
2.7 KiB
Text
63 lines
2.7 KiB
Text
// aborist/mesh — per-member secret envelope.
|
|
//
|
|
// Every epoch carries one fresh 32-byte symmetric secret. That single
|
|
// secret is wrapped N times, once per member, using ECDH between the
|
|
// rotator's X25519 priv and each member's X25519 pub. Each member
|
|
// unwraps only their own slot. Evicted members get no slot at all.
|
|
//
|
|
// Render: dot -Tpng docs/diagrams/mesh-secret-envelope.dot -o /tmp/x.png
|
|
|
|
digraph mesh_secret_envelope {
|
|
rankdir=LR;
|
|
bgcolor="white";
|
|
node [shape=box, style="rounded,filled", fontname="Helvetica"];
|
|
edge [fontname="Helvetica", fontsize=10];
|
|
|
|
secret [label="epoch_N_secret\n32 random bytes", fillcolor="#ffd6d6", shape=cylinder];
|
|
|
|
subgraph cluster_wrap {
|
|
label="rotate_epoch() — done by actor (admin)";
|
|
style="rounded,dashed";
|
|
color="#666666";
|
|
|
|
ecdh_a [label="ECDH(rotator_dh_priv,\n alice_dh_pub)\n -> shared_a (HKDF)", fillcolor="#e8f0ff"];
|
|
ecdh_b [label="ECDH(rotator_dh_priv,\n bob_dh_pub)\n -> shared_b (HKDF)", fillcolor="#e8f0ff"];
|
|
ecdh_c [label="ECDH(rotator_dh_priv,\n carol_dh_pub)\n -> shared_c (HKDF)", fillcolor="#e8f0ff"];
|
|
|
|
wrap_a [label="ChaCha20-Poly1305\n(shared_a, nonce_a, secret,\n aad=alice.member_id)"];
|
|
wrap_b [label="ChaCha20-Poly1305\n(shared_b, nonce_b, secret,\n aad=bob.member_id)"];
|
|
wrap_c [label="ChaCha20-Poly1305\n(shared_c, nonce_c, secret,\n aad=carol.member_id)"];
|
|
|
|
secret -> wrap_a;
|
|
secret -> wrap_b;
|
|
secret -> wrap_c;
|
|
|
|
ecdh_a -> wrap_a [label="key"];
|
|
ecdh_b -> wrap_b [label="key"];
|
|
ecdh_c -> wrap_c [label="key"];
|
|
}
|
|
|
|
envelope [label="mesh_epochs.secret_envelope (JSON)\n{\n alice: {nonce_b64, ct_b64},\n bob: {nonce_b64, ct_b64},\n carol: {nonce_b64, ct_b64}\n}", fillcolor="#fff7d6", shape=note];
|
|
|
|
wrap_a -> envelope [label="alice slot"];
|
|
wrap_b -> envelope [label="bob slot"];
|
|
wrap_c -> envelope [label="carol slot"];
|
|
|
|
subgraph cluster_unwrap {
|
|
label="Each peer unwraps only their own slot";
|
|
style="rounded,dashed";
|
|
color="#666666";
|
|
|
|
node [fillcolor="#d6ffd6"];
|
|
u_alice [label="alice:\nECDH(alice_dh_priv,\n rotator_dh_pub)\nthen AEAD-decrypt slot.alice"];
|
|
u_bob [label="bob:\nECDH(bob_dh_priv,\n rotator_dh_pub)\nthen AEAD-decrypt slot.bob"];
|
|
u_carol [label="carol:\nECDH(carol_dh_priv,\n rotator_dh_pub)\nthen AEAD-decrypt slot.carol"];
|
|
}
|
|
|
|
envelope -> u_alice;
|
|
envelope -> u_bob;
|
|
envelope -> u_carol;
|
|
|
|
evicted [label="evicted dave\nno slot in envelope\nValueError on unwrap", fillcolor="#ffe0e0", shape=octagon];
|
|
envelope -> evicted [label="dave NOT included", color="#cc0000", style=dashed];
|
|
}
|