arborist/docs/diagrams/mesh-secret-envelope.dot

// arborist/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];
}