Federation: multiplayer aborist

Gossip-based mesh for cross-peer data sharing.

Mesh — gossip / membership layer for federated aborist trees.

Off by default. Loaded only when the user explicitly opts in via aborist mesh init (creates this peer’s identity) and aborist mesh enable (flips the gating flag in the meta table).

The cryptographic substrate:

• Ed25519 (signing) — every gossip message and every membership mutation event is signed by the sender’s pubkey.

• X25519 (ECDH) — used to wrap each epoch’s symmetric mesh secret to every current member’s DH pubkey, so the new secret is reconstructible only by the post-rotation roster.

Membership state is per-epoch:

epoch 0 = group genesis (just the founder) epoch N = the N-th roster mutation (add member, kick, scheduled rotate)

Eviction is a rotate where the kicked member’s pubkey isn’t in the new envelope. Their previously-signed events stay verifiable forever (historical roster preserved in mesh_roster), but they no longer have the new secret, so any AEAD-protected gossip for epoch N+1 is opaque to them.

This module deliberately avoids networking. The wire layer (HTTP/TLS gossip server + sync client) lives in aborist.mesh.wire and is also opt-in.

class aborist.mesh.MeshIdentity(member_id: 'str', sign_priv: 'bytes', sign_pub: 'bytes', dh_priv: 'bytes', dh_pub: 'bytes', group_name: 'str', created_at: 'int')

Bases: object

Parameters:

• member_id (str)

• sign_priv (bytes)

• sign_pub (bytes)

• dh_priv (bytes)

• dh_pub (bytes)

• group_name (str)

• created_at (int)

member_id: str

sign_priv: bytes

sign_pub: bytes

dh_priv: bytes

dh_pub: bytes

group_name: str

created_at: int

class aborist.mesh.MeshRosterEntry(member_id: 'str', sign_pub: 'bytes', dh_pub: 'bytes', role: 'str')

Bases: object

Parameters:

• member_id (str)

• sign_pub (bytes)

• dh_pub (bytes)

• role (str)

member_id: str

sign_pub: bytes

dh_pub: bytes

role: str

aborist.mesh.aead_decrypt(key, nonce, ciphertext, aad=b'')

Decrypt + verify. Raises ValueError on tag mismatch (no plaintext leak).

Parameters:

• key (bytes)

• nonce (bytes)

• ciphertext (bytes)

• aad (bytes)

Return type:

bytes

aborist.mesh.aead_encrypt(key, nonce, plaintext, aad=b'')

Encrypt + authenticate. Returns ciphertext||tag.

Parameters:

• key (bytes)

• nonce (bytes)

• plaintext (bytes)

• aad (bytes)

Return type:

bytes

aborist.mesh.current_epoch(conn)

Parameters:

conn (Connection)

Return type:

int | None

aborist.mesh.ecdh_shared_secret(priv_bytes, peer_pub_bytes)

X25519 ECDH -> 32-byte shared secret (HKDF-extracted).

Parameters:

• priv_bytes (bytes)

• peer_pub_bytes (bytes)

Return type:

bytes

aborist.mesh.generate_dh_keypair()

Return (priv_bytes, pub_bytes) for a fresh X25519 keypair.

Return type:

tuple[bytes, bytes]

aborist.mesh.generate_signing_keypair()

Return (priv_bytes, pub_bytes) for a fresh Ed25519 keypair.

Return type:

tuple[bytes, bytes]

aborist.mesh.init_identity(conn, *, group_name, member_id=None)

Generate this peer’s keys and seed epoch 0 with this peer as founding admin.

Idempotent on re-call only in the sense that it raises — the schema enforces a singleton via PK = 1. Caller is expected to check load_identity() first.

Parameters:

• conn (Connection)

• group_name (str)

• member_id (str | None)

Return type:

MeshIdentity

aborist.mesh.is_enabled(conn)

Parameters:

conn (Connection)

Return type:

bool

aborist.mesh.load_identity(conn)

Parameters:

conn (Connection)

Return type:

MeshIdentity | None

aborist.mesh.set_enabled(conn, enabled)

Parameters:

• conn (Connection)

• enabled (bool)

Return type:

None

aborist.mesh.sign(priv_bytes, message)

Ed25519 sign. 64-byte signature.

Parameters:

• priv_bytes (bytes)

• message (bytes)

Return type:

bytes

aborist.mesh.verify(pub_bytes, signature, message)

Ed25519 verify. Returns True/False — never raises.

Parameters:

• pub_bytes (bytes)

• signature (bytes)

• message (bytes)

Return type:

bool