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.
51 lines
2.1 KiB
Text
51 lines
2.1 KiB
Text
// aborist/mesh — cryptographic identity stack per peer.
|
|
//
|
|
// Each peer carries two keypairs and one shared epoch secret.
|
|
// Keys are raw 32-byte forms; everything lives in the standard SQLite db.
|
|
//
|
|
// Render: dot -Tpng docs/diagrams/mesh-identity-stack.dot -o /tmp/x.png
|
|
|
|
digraph mesh_identity_stack {
|
|
rankdir=TB;
|
|
bgcolor="white";
|
|
node [shape=box, style="rounded,filled", fontname="Helvetica"];
|
|
edge [fontname="Helvetica", fontsize=10];
|
|
|
|
subgraph cluster_peer {
|
|
label="One peer (e.g. alice)";
|
|
style="rounded,dashed";
|
|
color="#666666";
|
|
|
|
sign_priv [label="Ed25519 priv\n(sign_priv, 32B)", fillcolor="#ffe8a3"];
|
|
sign_pub [label="Ed25519 pub\n(sign_pub, 32B)\nshared with group", fillcolor="#fff7d6"];
|
|
dh_priv [label="X25519 priv\n(dh_priv, 32B)", fillcolor="#a3d8ff"];
|
|
dh_pub [label="X25519 pub\n(dh_pub, 32B)\nshared with group", fillcolor="#d6ecff"];
|
|
member_id [label="member_id\n8 hex chars", fillcolor="#eeeeee"];
|
|
|
|
sign_priv -> sign_pub [label="public_key()"];
|
|
dh_priv -> dh_pub [label="public_key()"];
|
|
}
|
|
|
|
subgraph cluster_group {
|
|
label="Per-epoch group state";
|
|
style="rounded,dashed";
|
|
color="#666666";
|
|
|
|
roster [label="mesh_roster\n(epoch, member_id, sign_pub, dh_pub, role)", fillcolor="#e8ffe8"];
|
|
epoch [label="mesh_epochs\n(epoch_id, secret_envelope, started_event_hash)", fillcolor="#e8ffe8"];
|
|
secret [label="symmetric epoch secret\n32 random bytes\nnever stored in clear", fillcolor="#ffd6d6"];
|
|
|
|
epoch -> secret [label="wrapped per member via ECDH"];
|
|
}
|
|
|
|
audit [label="audit_events\n(prev_event_hash, event_hash)\nappend-only Merkle chain", fillcolor="#ffffff", shape=note];
|
|
|
|
sign_priv -> audit [label="signs each\nmembership op", style=dashed];
|
|
sign_pub -> roster [label="enrolled at"];
|
|
dh_pub -> roster [label="enrolled at"];
|
|
dh_priv -> secret [label="ECDH-unwraps\nself's envelope entry", style=dashed, color="#0066cc"];
|
|
member_id -> roster [label="keys by"];
|
|
|
|
{rank=same; sign_priv; dh_priv;}
|
|
{rank=same; sign_pub; dh_pub;}
|
|
}
|