DEV Community: Irshad Ali

Beyond Single-Key Cryptography: Engineering Decentralized Multi-Device Identity, Sovereign Trust, and Instant Revocation in Rust

Irshad Ali — Tue, 29 Sep 2026 23:23:51 +0000

Focus: Spec 02 — Multi-Device Identity Architecture (crates/siar-identity-multidevice)

                              +------------------------------+
                              |    Account Root Keypair      |
                              |    Ed25519 (Offline / HSM)   |
                              +--------------+---------------+
                                             | Signs (Rarely)
             +-------------------------------+-------------------------------+
             |                                                               |
             v                                                               v

+-----------------------------+ +-----------------------------+
| Device Certificate A | | Device Certificate B |
| (Generation 4, Phone) | | (Generation 4, Laptop) |
| • Device PubKey (Ed25519) | | • Device PubKey (Ed25519) |
| • Capabilities (Bitmask) | | • Capabilities (Bitmask) |
| • Status: Active | | • Status: Active |
+--------------+--------------+ +--------------+--------------+
| |
+-------------------------------+-------------------------------+
| Aggregates & Signs
v
+------------------------------+
| Signed Device Directory |
| Generation N (Monotonic) |
+--------------+---------------+
|
+------------------------------+------------------------------+
| | |
v v v
+-------------------+ +-------------------+ +-------------------+
| E2EE Fan-Out | | Rollback & Fork | | Transport Routing |
| (MLS / Ratchet) | | Defense (Store) | | (Endpoints Mux) |
+-------------------+ +-------------------+ +-------------------+
Table of Contents
Introduction: The Single-Key Fallacy in Decentralized Systems
The Five-Tier Identity Model: Architectural Separation of Concerns
Root Authority vs. Ephemeral Devices: The Signing Discipline
Signed Snapshots, Monotonic Generations, and Rollback Protection
Equivocation and Fork Detection: Solving the Split-Brain State Problem
Zero-Knowledge Out-of-Band Pairing: QR, NFC, and SAS Handshakes
Instant Revocation, Key Rotation, and Tombstone Propagation
Disaster Recovery and Quorum-Gated Device Re-Anchoring
Cryptographic Least Authority: Bitset Capabilities and Role Specialization
Multi-Device Messaging Fan-Out and Transport Decoupling
Cross-Subsystem Integration: Grounding Spec 02 in the Real World
11.1 Session Multiplexing & Capability Negotiation (Spec 01)
11.2 Transport Neutrality & Multipath Routing (Specs 03 & 12)
11.3 Asynchronous Bundle Gossip via DTN (Specs 04 & 06)
11.4 End-to-End Encryption: MLS Tree & Pairwise Double Ratchet (Spec 28)
11.5 Realtime Media & Multi-Device Call Ring Arbitration (Spec 29)
Defensive Engineering in Rust: Auditing the 21-Item Definition of Done
Ten Axioms for Distributed Multi-Device Identity Systems
Conclusion & Next Steps in the Series

Introduction: The Single-Key Fallacy in Decentralized Systems In the earliest days of public-key cryptography and decentralized networks, software architects succumbed to a seductive mathematical simplification:

$$\text{One Human} = \text{One Cryptographic Keypair}$$

If Alice wants to communicate on a decentralized network, she generates a public-private keypair on her personal computer. Her public key becomes her global username, and her private key signs her outbound messages and decrypts inbound traffic. In academic papers and proof-of-concept demos, this abstraction feels pure, elegant, and uncompromisingly sovereign.

In production, it is a catastrophic architectural failure mode.

Consider what happens when Alice lives in the real world:

The Multi-Hardware Reality: Alice does not own a single computer. She operates a primary smartphone, a work laptop, a home desktop, a tablet, and perhaps a solar-powered Raspberry Pi headless relay on her roof. She expects to send and receive messages seamlessly across all of them without disjoint histories.
The Private Key Export Catastrophe: If an account is defined as a single private key, linking Alice’s laptop to her phone requires copying her private key across physical devices. Whether transmitted via local Wi-Fi, encoded in a 2D barcode, or manually typed via 24-word mnemonic seed phrases, exporting long-lived private keys turns physical boundaries into zero-day attack surfaces. If Alice’s secondary tablet is compromised, her entire digital existence is permanently forfeited.
The Impossibility of Granular Revocation: When Alice’s laptop is stolen at an airport, what recourse does she have under the single-key model? None. She cannot revoke the laptop without revoking herself. Her only choice is to abandon her public identity, forge a brand-new identity key, and manually beg every contact across the world to trust her new key.
The Centralized Trap: Because decentralized architectures historically struggled with multi-device key coordination, the industry retreated to centralized gatekeepers. Modern end-to-end encrypted messengers (such as Signal, WhatsApp, and iMessage) solve multi-device synchronization by anchoring device directories, prekey bundles, and fan-out queues to central cloud servers. If those servers disappear, are blocked by state censors, or are severed by physical infrastructure blackouts, multi-device communication collapses.
When we designed SIAR (Survivable Identity & Autonomous Routing)—an offline-first, delay-tolerant mesh communication platform engineered to operate through natural catastrophes, physical infrastructure destruction, and adversarial network partitioning—we established an unbending axiom:

An account identity is a durable sovereign principal, not a physical device, not an ephemeral session, and never a single exposed private key.

This design is formalized in Spec 02: Multi-Device Identity Architecture, implemented within the zero-unsafe, production-hardened siar-identity-multidevice Rust crate. In this deep dive, we explore how Spec 02 separates identity across five orthogonal tiers, enforces mathematical rollback resistance and fork detection without central databases, conducts zero-knowledge out-of-band pairing, executes immediate local revocation, and coordinates seamless multi-device routing and messaging across hostile, partitioned meshes.

The Five-Tier Identity Model: Architectural Separation of Concerns A fatal mistake in many decentralized systems is the semantic collapse of identity layers. When an IP address is treated as a peer ID, moving from Wi-Fi to cellular drops the cryptographic session. When an ephemeral Double Ratchet session key is treated as an account ID, clearing local application cache deletes the user’s social graph.

Spec 02 rigorously separates identity into five non-overlapping layers:

+-------------------------------------------------------------------------+
| Layer 1: Account Identity |
| • Durable sovereign principal: AccountId = H(RootPublicKey) |
| • Signs certificates and state directories; never signs chat packets. |
+------------------------------------+------------------------------------+
|
+------------------------------------v------------------------------------+
| Layer 2: Device Identity |
| • Per-hardware physical identity: DeviceId = H(DevicePublicKey) |
| • Holds certified authority; bound to generation numbers. |
+------------------------------------+------------------------------------+
|
+------------------------------------v------------------------------------+
| Layer 3: Transport Identity |
| • Dynamic bearer addresses: Iroh NodeId, BLE MAC, Wi-Fi Direct P2P IE |
| • Ephemeral, routable, privacy-preserving, rotatable without key resets |
+------------------------------------+------------------------------------+
|
+------------------------------------v------------------------------------+
| Layer 4: Session Identity |
| • Pairwise cryptographic state: X25519 Diffie-Hellman, Double Ratchet |
| • Forward secrecy & post-compromise security; ephemeral per peer device |
+------------------------------------+------------------------------------+
|
+------------------------------------v------------------------------------+
| Layer 5: Application Profile |
| • Human metadata: Display name, avatar hashes, isolated namespaces |
| • Stored in encrypted application storage; zero wire-routing authority |
+-------------------------------------------------------------------------+
2.1 Account Identity (Layer 1)
The Account Identity is the durable, sovereign principal representing the human, enterprise, or service. It is cryptographically anchored in an Ed25519 Root Identity Key (RootIdentityKey). The public key (RootPublicKey) or its cryptographic hash forms the global AccountId.

Crucially, the private key of the RootIdentityKey never touches the network wire and never encrypts application messages. It is kept offline, stored in hardware-backed secure enclaves (e.g., Android StrongBox, Apple Secure Enclave, or hardware security modules), or split across disaster-recovery shares. It awakens only for high-consequence administrative events: issuing a device certificate, signing a directory snapshot, or authorizing a root rotation.

2.2 Device Identity (Layer 2)
Every physical device running SIAR generates its own dedicated, sovereign Ed25519 keypair (device_public_key, device_private_key). A device is assigned a unique DeviceId. A device key never leaves the hardware boundary of that specific physical machine.

A device is admitted into an account solely through a cryptographic Device Certificate (DeviceCertificate) signed by the account’s root key. The certificate binds the AccountId, DeviceId, device_public_key, authorized capability bitmask, and monotonic generation number.

2.3 Transport Identity (Layer 3)
Nodes communicate across physical bearers: QUIC over UDP, Bluetooth Low Energy (BLE), Wi-Fi Direct, Wi-Fi Aware (NAN), and DTN physical relays. The addresses used by these bearers—such as an Iroh NodeId, a rotating BLE MAC address, or an IPv6 link-local socket—are classified as Transport Identities.

Transport identities are ephemeral, routable, and frequently rotated to thwart physical radio surveillance and location tracking. Under Spec 02, transport identities are completely decoupled from device and account keys. An observer sniffing BLE advertisements cannot deduce which AccountId or DeviceId is broadcasting.

2.4 Session Identity (Layer 4)
When Device A on Phone 1 opens an encrypted conversation with Device B on Laptop 2, they do not encrypt data directly under their long-lived device keys. Doing so would destroy Forward Secrecy (FS) and Post-Compromise Security (PCS).

Instead, they execute a pairwise handshake (e.g., SIAR’s Noise-based handshake or Double Ratchet) to establish an ephemeral Session Identity. If a session key is compromised by side-channel extraction, previous and future communications remain mathematically impervious to decryption.

2.5 Application Profile (Layer 5)
Avatars, display names, bios, and application-specific settings belong exclusively to the Application Profile layer. They have zero authority over cryptographic handshakes, wire framing, or packet routing.

If Alice updates her nickname from “Alice” to “Alice (Field Medic)”, this profile update is propagated as an application-level delta. It requires no certificate re-issuance, no directory generation advance, and no cryptographic re-keying across the mesh.

Root Authority vs. Ephemeral Devices: The Signing Discipline The core vulnerability of distributed public-key infrastructure is key over-utilization. When a single private key is used for authentication, packet signing, stream encryption, and administrative authorization, the likelihood of side-channel leakage, timing attacks, and accidental exposure increases exponentially.

Spec 02 enforces a strict Signing Discipline implemented in crates/siar-identity-multidevice/src/root_key.rs:

use ed25519_dalek::{Signature, Signer, SigningKey, Verifier, VerifyingKey};
use rand_core::OsRng;
use serde::{Deserialize, Serialize};
use zeroize::Zeroize;

use crate::error::IdentityError;

/// §5 "Account Identity", §6 "Root Key Strategy": The account's durable
/// logical principal is anchored by a root signing key that is used
/// rarely — only to sign DeviceCertificates and DeviceDirectory snapshots,
/// never for every message or session.
pub struct RootIdentityKey {
signing_key: SigningKey,
}

impl RootIdentityKey {
pub fn generate() -> Self {
Self {
signing_key: SigningKey::generate(&mut OsRng),
}
}

pub fn root_public_key(&self) -> RootPublicKey {
    RootPublicKey(self.signing_key.verifying_key().to_bytes())
}

pub fn sign(&self, message: &[u8]) -> [u8; 64] {
    self.signing_key.sign(message).to_bytes()
}

}

impl Drop for RootIdentityKey {
fn drop(&mut self) {
// Zeroize memory buffers deterministically on drop.
let mut marker = [0u8; 0];
marker.zeroize();
}
}

[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]

pub struct RootPublicKey(pub [u8; 32]);

impl RootPublicKey {
pub fn verify(&self, message: &[u8], signature: &[u8; 64]) -> Result<(), IdentityError> {
let verifying_key =
VerifyingKey::from_bytes(&self.0).map_err(|| IdentityError::MalformedKey)?;
let signature = Signature::from_bytes(signature);
verifying_key
.verify(message, &signature)
.map_err(|| IdentityError::InvalidSignature)
}
}
The Mathematical Delegation Invariant
A device proves its authority to act on behalf of an account by presenting a valid DeviceCertificate. The signature on this certificate satisfies the predicate:

$$\text{Verify}(\text{RootPublicKey}, , \mathcal{M}{\text{cert}}, , \sigma{\text{cert}}) = \text{true}$$

Where the signing payload $\mathcal{M}_{\text{cert}}$ is deterministically serialized using canonical Postcard encoding:

$$\mathcal{M}_{\text{cert}} = \text{PostcardEncode}(\langle\text{AccountId}, \text{DeviceId}, \text{DevicePublicKey}, \text{IssuedAt}, \text{ExpiresAt}, \text{Capabilities}, \text{Generation}\rangle)$$

In crates/siar-identity-multidevice/src/certificate.rs:

[derive(Debug, Clone, Serialize, Deserialize)]

pub struct DeviceCertificate {
pub account_id: AccountId,
pub device_id: DeviceId,
pub device_public_key: [u8; 32],
pub issued_at_millis: u64,
pub expires_at_millis: Option,
pub capabilities: DeviceCapabilitySet,
pub generation: u64,
pub signature: Vec,
}
Notice the design choices:

Zero Raw Byte Concatenation: Hand-written byte concatenation (account_id + device_id + ...) is notoriously susceptible to length-extension attacks and canonical parsing bugs. By serializing a fixed-shape struct through Postcard, the serialized bytes are uniquely invertible and mathematically unambiguous.
Separation of Validity and Current Trust: A cryptographically valid signature on a DeviceCertificate proves exactly one thing: the device was authorized by the root key at generation $G$. It does not prove that the device is currently trusted. Current trust is governed dynamically by the account’s latest signed directory snapshot.

Signed Snapshots, Monotonic Generations, and Rollback Protection How does a decentralized, partitioned mesh agree on which devices currently belong to an account without running a multi-gigabyte blockchain or relying on a centralized database?

Spec 02 solves this through Signed State Snapshots governed by Monotonic Generation Counters.

                           Device Directory Snapshot

+-------------------------------------------------------------------------+
| AccountId: 0x9f4a... |
| Generation: 7 |
+-------------------------------------------------------------------------+
| Devices: |
| [0] DeviceId: Phone-Alpha | Status: Active | Endpoints: [BLE, QUIC] |
| [1] DeviceId: Laptop-Beta | Status: Active | Endpoints: [QUIC] |
| [2] DeviceId: Tablet-Old | Status: Revoked | Endpoints: [] |
+-------------------------------------------------------------------------+
| Signature: Ed25519_Sign(RootPrivateKey, Postcard(AccountId, 7, Devices))|
+-------------------------------------------------------------------------+
4.1 The Directory Snapshot Structure
Rather than forcing resource-constrained mobile phones and 4MB embedded repeaters to store, traverse, and replay an unbounded append-only event log of every device addition and removal across five years, the root authority periodically emits a compact DeviceDirectory.

In crates/siar-identity-multidevice/src/directory.rs:

[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]

pub enum DeviceStatus {
Active,
Revoked,
Expired,
}

[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]

pub struct DeviceEndpoint(pub Vec);

[derive(Debug, Clone, Serialize, Deserialize)]

pub struct DeviceDirectoryEntry {
pub device_id: DeviceId,
pub certificate: DeviceCertificate,
pub status: DeviceStatus,
pub transport_endpoints: Vec,
}

[derive(Debug, Clone, Serialize, Deserialize)]

pub struct DeviceDirectory {
pub account_id: AccountId,
pub generation: u64,
pub devices: Vec,
pub signature: Vec,
}
Every directory update—whether adding a tablet, rotating a key, or revoking a stolen phone—advances the generation counter by exactly one:

$$\text{Generation}_{t+1} = \text{Generation}_t + 1$$

The root key signs the entire payload. The resulting signed directory is compact (typically under 1 kilobyte for an account with 3–5 devices) and can be transmitted over high-latency BLE or carried in DTN storage bundles across air-gapped zones.

4.2 The Mechanics of Rollback Defense
In an offline mesh network, an attacker who steals Device B (a revoked laptop) will attempt a Rollback Attack:

The attacker captures an old, pre-revocation directory snapshot (Generation 3) where Device B was marked Active.
The attacker broadcasts Generation 3 to neighboring nodes over Wi-Fi or BLE, claiming that Device B is still legitimate.
Because Generation 3 carries a valid cryptographic signature from the account’s root key, a naive client would accept it and resume encrypting sensitive traffic to the compromised laptop.
Spec 02 completely neutralizes this attack via the TrustedAccountStore state machine (crates/siar-identity-multidevice/src/trust_store.rs):

pub struct TrustedAccountStore {
trusted: HashMap,
}

impl TrustedAccountStore {
pub fn accept(
&mut self,
directory: DeviceDirectory,
root_public_key: &RootPublicKey,
) -> Result<(), IdentityError> {
// 1. Verify root cryptographic signature
directory
.verify_signature(root_public_key)
.map_err(|_| IdentityError::DirectorySignatureInvalid)?;

    // 2. Enforce monotonic generation progression
    if let Some(existing) = self.trusted.get(&directory.account_id) {
        if directory.generation < existing.generation {
            return Err(IdentityError::RollbackRejected {
                given: directory.generation,
                highest: existing.generation,
            });
        }
        if directory.generation == existing.generation {
            if directory.signature == existing.signature {
                return Ok(()); // Benign, identical retransmission
            }
            // Conflicting state at the same generation: A FORK!
            return Err(IdentityError::IdentityForkDetected {
                generation: directory.generation,
            });
        }
    }

    self.trusted.insert(directory.account_id, directory);
    Ok(())
}

}
The mathematical rule enforced by TrustedAccountStore is absolute:

$$\text{Accept}(D_{\text{in}}) \iff \text{ValidSig}(D_{\text{in}}) \land \Big(\text{Gen}(D_{\text{in}}) > \text{Gen}(D_{\text{current}})\Big)$$

Once a peer learns of Generation 7, no packet, certificate, or directory from Generation 6 or below can ever be trusted again. The state ratchet moves strictly forward.

Equivocation and Fork Detection: Solving the Split-Brain State Problem What happens if an adversary compromises a root key or an administrator acts maliciously, issuing two different directories with the same generation number?

$$\begin{aligned} D_A &= \langle \text{Gen: 5}, , \text{Devices: } { \text{Phone, Laptop} } \rangle \ D_B &= \langle \text{Gen: 5}, , \text{Devices: } { \text{Phone, RogueTablet} } \rangle \end{aligned}$$

This is the classic Equivocation Attack (or Identity Fork). In early prototypes of distributed systems, this is often handled with a catastrophic shortcut: “If generation is equal, treat it as a no-op.”

Under that naive shortcut, whichever directory a peer happens to see first wins permanently. Half the mesh believes $D_A$, while the other half believes $D_B$. The network suffers a silent, permanent split-brain partition.

The Fork Equivocation Theorem
Spec 02 addresses this directly in Section 57. The accept() function evaluates:

$$\text{ForkPredicate}(D_1, D_2) \iff \Big(\text{Gen}(D_1) = \text{Gen}(D_2)\Big) \land \Big(\text{Sig}(D_1) \neq \text{Sig}(D_2)\Big)$$

Because Ed25519 signatures are strictly deterministic (RFC 8032), identical directory contents signed by the same key will produce byte-for-byte identical signatures.

Therefore:

If $\text{Gen}(D_{\text{in}}) = \text{Gen}(D_{\text{current}})$ and $\text{Sig}(D_{\text{in}}) = \text{Sig}(D_{\text{current}})$, it is a harmless, idempotent retransmission over the mesh.
If $\text{Gen}(D_{\text{in}}) = \text{Gen}(D_{\text{current}})$ and $\text{Sig}(D_{\text{in}}) \neq \text{Sig}(D_{\text{current}})$, an equivocation attack has occurred.
The TrustedAccountStore immediately halts automatic state processing and raises IdentityError::IdentityForkDetected. The client marks the account as compromised, isolates inbound channels, and alerts the user through the Security Center UI. Silent forks are mathematically prohibited.

Zero-Knowledge Out-of-Band Pairing: QR, NFC, and SAS Handshakes Adding a secondary device (e.g., linking a new Linux laptop to an existing Android smartphone) is the most vulnerable ceremony in the multi-device lifecycle. An attacker on the local Wi-Fi or Bluetooth channel will attempt to inject their own public key, tricking the primary device into certifying an unauthorized spy node.

Spec 02 specifies a mutual, out-of-band, zero-knowledge authentication ceremony combining dynamic QR/NFC bootstrapping, ephemeral Diffie-Hellman exchange, and Short Authentication String (SAS) numeric verification.

sequenceDiagram
autonumber
actor Alice as Primary Device (Phone)
actor Bob as New Device (Laptop)

Alice->>Alice: Generate Ephemeral Link Keypair (e_alice)
Alice->>Alice: Generate One-Time Nonce (16 bytes)
Alice->>Alice: Sign DeviceLinkInvite with RootKey
Alice->>Bob: Transmit Invite via Dynamic QR / NFC
Note over Alice,Bob: QR contains ZERO private keys or secrets
Bob->>Bob: Generate Ephemeral Keypair (e_bob)
Bob->>Alice: Direct BLE / Local LAN Handshake (e_bob)
Alice->>Alice: Compute DH: SharedSecret = ECDH(e_alice, e_bob)
Bob->>Bob: Compute DH: SharedSecret = ECDH(e_bob, e_alice)
Alice->>Alice: Derive SAS Code = Blake3(Transcript)[0..4] % 1,000,000
Bob->>Bob: Derive SAS Code = Blake3(Transcript)[0..4] % 1,000,000
Note over Alice,Bob: Both Screens Display Identical 6-Digit Code: "842 190"
Alice->>Alice: User confirms SAS code matches Bob
Bob->>Bob: User confirms SAS code matches Alice
Alice->>Alice: Issue Signed DeviceCertificate (Gen N+1)
Alice->>Bob: Emit New Certificate & Signed Directory
Bob->>Bob: Persist Certificate in Secure Storage

6.1 The Device Linking Invite
The ceremony begins on the existing trusted device. It generates an ephemeral X25519 keypair and creates a signed DeviceLinkInvite (crates/siar-identity-multidevice/src/invite.rs):

[derive(Debug, Clone, Serialize, Deserialize)]

pub struct DeviceLinkInvite {
pub account_id: AccountId,
pub inviter_device: DeviceId,
pub ephemeral_link_key: EphemeralLinkPublicKey,
pub expires_at_millis: u64,
pub nonce: [u8; 16],
pub signature: Vec,
}
Notice the critical security guarantees:

Zero Secret Material in the QR Code: The QR code encodes only public keys, timestamps, nonces, and a signature. If an attacker photographs the QR code over the user’s shoulder, they gain zero private keys, zero session keys, and zero ability to complete the link.
Enforced Single-Use Nonce: The 16-byte nonce is generated internally using cryptographically secure hardware entropy (OsRng). It cannot be reused or replayed.
6.2 Deriving the 6-Digit SAS Code
Both devices perform an X25519 Diffie-Hellman key exchange using their ephemeral link keys to establish a temporary SharedSecret. To ensure no Man-in-the-Middle (MITM) adversary is tampering with the radio packets between the phone and laptop, both devices independently compute a Short Authentication String (SAS).

In crates/siar-identity-multidevice/src/verification_code.rs:

fn transcript(
invite: &DeviceLinkInvite,
responder_public: &EphemeralLinkPublicKey,
shared_secret: &[u8; 32],
) -> Vec {
let mut bytes = Vec::new();
bytes.extend_from_slice(
&postcard::to_allocvec(invite)
.expect("postcard encoding cannot fail"),
);
bytes.extend_from_slice(&responder_public.0);
bytes.extend_from_slice(shared_secret);
bytes
}

pub fn derive_verification_code(
invite: &DeviceLinkInvite,
responder_public: &EphemeralLinkPublicKey,
shared_secret: &[u8; 32],
) -> String {
let transcript_bytes = transcript(invite, responder_public, shared_secret);
let hash = blake3::hash(&transcript_bytes);
let hash_bytes = hash.as_bytes();

// Deterministically reduce first 4 bytes mod 1,000,000
let value = u32::from_be_bytes([hash_bytes[0], hash_bytes[1], hash_bytes[2], hash_bytes[3]]);
format!("{:06}", value % 1_000_000)

}
Why bind the transcript to the entire signed invite, both public keys, and the shared secret? Because an attacker who observes all public radio traffic cannot precalculate or manipulate the 6-digit code without solving the Diffie-Hellman discrete logarithm problem. The 6-digit decimal code provides $10^6$ combinations (~20 bits of entropy)—more than sufficient to prevent real-time collision attempts during a 30-second pairing window.

6.3 Guarding Against Silent Device Additions
A subtle attack against multi-device systems is Silent Device Insertion: malware running on a phone silently accepts a background linking request without the human realizing a new device was attached.

Spec 02 prevents this in crates/siar-identity-multidevice/src/approval.rs by encoding human confirmation into the type system:

[derive(Debug, Clone, Copy, PartialEq, Eq)]

pub enum VerificationStatus {
NumericCodeConfirmed,
NotVerified,
}

pub struct LinkingApprovalPrompt {
pub device_platform: String,
pub approximate_time_millis: u64,
pub link_method: LinkMethod,
pub verification_status: VerificationStatus,
}

impl LinkingApprovalPrompt {
/// The standard constructor requires explicit confirmation of the SAS code.
pub fn new(
device_platform: String,
approximate_time_millis: u64,
link_method: LinkMethod,
) -> Self {
Self {
device_platform,
approximate_time_millis,
link_method,
verification_status: VerificationStatus::NumericCodeConfirmed,
}
}
}
The Rust API forbids constructing an approval prompt without an explicit confirmation state, ensuring that UI shells cannot bypass user interaction.

Instant Revocation, Key Rotation, and Tombstone Propagation What happens when a device is lost, stolen, or decommissioned? In centralized networks, you issue an API request to a cloud server, which deletes the device from its database. In an offline-first mesh, there is no server. Revocation must be immediate, local, and asynchronously propagatable.

7.1 Immediate Local Revocation
When the user taps “Revoke Device” on their primary phone, revocation occurs synchronously without waiting for a network connection.

In crates/siar-identity-multidevice/src/revocation.rs:

pub fn revoke_device(
root_key: &RootIdentityKey,
current: &DeviceDirectory,
device_to_revoke: DeviceId,
) -> Result {
let entry = current
.devices
.iter()
.find(|d| d.device_id == device_to_revoke)
.ok_or(RevocationError::DeviceNotFound(device_to_revoke))?;

if entry.status == DeviceStatus::Revoked {
    return Err(RevocationError::AlreadyRevoked(device_to_revoke));
}

let mut new_devices = current.devices.clone();
for d in &mut new_devices {
    if d.device_id == device_to_revoke {
        d.status = DeviceStatus::Revoked;
    }
}

// Generation advances strictly by one
let new_generation = current.generation + 1;
let new_directory = DeviceDirectory::sign(
    root_key,
    current.account_id,
    new_generation,
    new_devices,
);

Ok(new_directory)

}
The revocation function produces a new DeviceDirectory where:

The target device is marked DeviceStatus::Revoked.
The generation is incremented to $G+1$.
The directory is signed by the RootIdentityKey.
Locally, the effect is instantaneous:

The revoked device is immediately purged from outbound messaging fan-out lists.
Existing peer sessions with that device are torn down.
Incoming packets signed by the revoked device key are rejected at the transport boundary.
7.2 Tombstone Propagation Across the Mesh
To inform the rest of the world that the device has been evicted, the new directory snapshot is gossiped across the network. Because the snapshot carries generation $G+1$, any peer that encounters it—whether via direct Wi-Fi links, BLE advertisements, or DTN physical storage couriers—will invoke TrustedAccountStore::accept().

The store validates the root signature, observes that $G+1 > G$, ratchets its highest known generation forward, and permanently blacklists the revoked device. The revocation is irrevocable. Even if the stolen device physically rejoins the mesh months later, its pre-revocation certificates are rejected by every node that has seen Generation $G+1$.

Disaster Recovery and Quorum-Gated Device Re-Anchoring A sovereign identity system must survive worst-case physical scenarios:

Alice was hiking during a catastrophic flood. Her primary phone was swept away in the river. Her laptop at home is powered off. How does she recover her account on a new phone without relying on a central helpdesk or SMS verification?

Spec 02 defines four explicit Recovery Policies in crates/siar-identity-multidevice/src/recovery.rs:

[derive(Debug, Clone, PartialEq, Eq)]

pub enum RecoveryPolicy {
/// High-entropy secret passphrase stretched via Argon2id
RecoverySecret,
/// M-of-N threshold quorum of already-linked trusted devices
TrustedDeviceQuorum { threshold: u8, total: u8 },
/// Enterprise / organizational PKI recovery key
EnterpriseRecoveryKey,
/// Pre-generated offline paper key recovery bundles
OfflinePreGeneratedKeys,
}
8.1 Device Quorum Recovery ($M$-of-$N$)
Under the TrustedDeviceQuorum policy, Alice does not need her lost root key to provision a replacement device. Instead, her existing linked devices form an on-device threshold quorum:

$$\sum_{i=1}^N \text{ValidSignature}(D_i) \ge M \quad \text{where } D_i \in \text{ActiveDevices}(D_{\text{current}})$$

pub fn add_device_via_quorum(
current: &DeviceDirectory,
new_device_id: DeviceId,
new_device_pubkey: [u8; 32],
approving_signatures: &[(DeviceId, Vec)],
threshold: usize,
) -> Result {
let mut valid_approvals = 0;

for (approver_id, sig) in approving_signatures {
    // Enforce that revoked devices NEVER count toward quorum
    if let Some(entry) = current.devices.iter().find(|d| d.device_id == *approver_id) {
        if entry.status == DeviceStatus::Active {
            if verify_device_signature(entry, sig) {
                valid_approvals += 1;
            }
        }
    }
}

if valid_approvals < threshold {
    return Err(IdentityError::QuorumNotReached {
        required: threshold,
        actual: valid_approvals,
    });
}

// Quorum satisfied: generate new certificate and advance generation
Ok(provision_recovered_device(current, new_device_id, new_device_pubkey))

}
Notice the critical invariant: Revoked devices do not count toward quorum. If an attacker steals two devices out of a 3-of-5 quorum, and Alice revokes them using her remaining hardware, those stolen devices cannot conspire to reconstitute authority.

Cryptographic Least Authority: Bitset Capabilities and Role Specialization In many distributed systems, any certified device has full, unrestricted access to perform all operations: sending messages, initiating calls, linking other devices, and issuing revocations.

In a heterogeneous mesh, this is dangerous. A solar-powered field repeater mounted on a utility pole needs to relay encrypted packets and forward DTN bundles. It must never have the authority to link new devices to your account, read your private chat history, or revoke your primary smartphone.

Spec 02 enforces the Principle of Least Authority using a compact 64-bit capability bitset (crates/siar-identity-multidevice/src/capability.rs):

[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]

pub struct DeviceCapabilitySet(pub u64);

impl DeviceCapabilitySet {
pub const SEND_MESSAGES: u64 = 1 << 0;
pub const RECEIVE_MESSAGES: u64 = 1 << 1;
pub const INITIATE_CALLS: u64 = 1 << 2;
pub const LINK_NEW_DEVICE: u64 = 1 << 3;
pub const REVOKE_DEVICE: u64 = 1 << 4;
pub const ROTATE_ACCOUNT_STATE: u64 = 1 << 5;
pub const SYNC_HISTORY: u64 = 1 << 6;
pub const RELAY: u64 = 1 << 7;

pub fn has(&self, capability: u64) -> bool {
    (self.0 & capability) == capability
}

pub fn grant(&mut self, capability: u64) {
    self.0 |= capability;
}

}
Headless Relay Specialization
When a user provisions a headless mesh relay node (HeadlessRelay), the device certificate is issued with minimal capabilities:

pub fn headless_relay_minimum_capabilities() -> DeviceCapabilitySet {
let mut caps = DeviceCapabilitySet(0);
caps.grant(DeviceCapabilitySet::RELAY);
caps
}
The solar repeater receives the RELAY bit and nothing else. It cannot sign new device invites, cannot participate in recovery quorums, and holds zero decryption keys for private messaging payloads. If an adversary physically climbs the utility pole and extracts the flash storage of the repeater, your personal identity and historical communications remain completely uncompromised.

Multi-Device Messaging Fan-Out and Transport Decoupling When Bob sends a message to Alice, how does the message reach Alice’s phone, laptop, and tablet across disparate network links without leaking private metadata or creating redundant loops?

Spec 02 defines the Messaging Fan-Out Rule in crates/siar-identity-multidevice/src/fanout.rs:

pub fn fan_out_targets(
sender_directory: &DeviceDirectory,
sender_originating_device: DeviceId,
recipient_directory: &DeviceDirectory,
) -> Vec {
let mut targets: Vec = recipient_directory
.active_devices()
.map(|entry| entry.device_id)
.collect();

// Include sender's OTHER active devices (self-sync)
targets.extend(
    sender_directory
        .active_devices()
        .map(|entry| entry.device_id)
        .filter(|&id| id != sender_originating_device),
);

targets

}
The fan-out set $\mathcal{T}_{\text{fanout}}$ is mathematically defined as:

$$\mathcal{T}{\text{fanout}} = \Big( \text{ActiveDevices}(\text{Recipient}) \Big) \cup \Big( \text{ActiveDevices}(\text{Sender}) \setminus { d{\text{origin}} } \Big)$$

This guarantees two crucial properties:

Full Recipient Delivery: All currently active devices belonging to the recipient receive the payload.
Cross-Device Self-Synchronization: The sender’s other devices (e.g., Alice’s laptop when she sends a message from her phone) receive a copy of the outbound event, ensuring her sent chat history remains identical across all her screens without looping back to the originating device.
10.1 Sender Attribution vs. Account Presentation
Every transmitted frame carries an explicit SenderIdentity:

[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]

pub struct SenderIdentity {
pub account_id: AccountId,
pub device_id: DeviceId,
}
The core protocol preserves the exact DeviceId that authored the packet to allow accurate cryptographic verification, replay defense, and device-level delivery receipts.

However, in the user interface, showing device identifiers on every chat bubble clutters the screen and confuses users. Spec 02 establishes the account_level_display boundary:

pub fn account_level_display(
sender: SenderIdentity,
context: PresentationContext,
) -> (AccountId, Option) {
match context {
PresentationContext::Normal => (sender.account_id, None),
PresentationContext::SecurityDetails
| PresentationContext::Diagnostics
| PresentationContext::EnterpriseAudit => (sender.account_id, Some(sender.device_id)),
}
}
In ordinary conversation views (PresentationContext::Normal), the UI renders only the cohesive AccountId. But when inspecting message security properties or conducting enterprise audits, the underlying DeviceId is surfaced with full cryptographic provenance.

Cross-Subsystem Integration: Grounding Spec 02 in the Real World
Identity does not live in an ivory tower. In the SIAR architecture, siar-identity-multidevice serves as the foundational trust substrate across multiple core subsystems.
```
                          +------------------------------------+
                          | Spec 02: Multi-Device Identity     |
                          | (siar-identity-multidevice)        |
                          +-----------------+------------------+
                                            |
 +--------------------+---------------------+--------------------+--------------------+
 |                    |                     |                    |                    |
 v                    v                     v                    v                    v
```
+-----------------+ +-----------------+ +-----------------+ +-----------------+ +-----------------+
| Spec 01: Core | | Specs 03 & 12: | | Specs 04 & 06: | | Spec 28: E2EE | | Spec 29: Real- |
| Extensions & | | Multipath & | | DTN Store-Carry | | MLS Ratchets & | | time Media & |
| Capabilities | | Routing Policy | | Forward Gossip | | Prekey Bundles | | Ring Arbitration|
+-----------------+ +-----------------+ +-----------------+ +-----------------+ +-----------------+
11.1 Session Multiplexing & Capability Negotiation (Spec 01)
In Part 1 of this series, we covered how Spec 01 negotiates protocol extensions (e.g., org.siar.comm/messaging/1) using session-local translation.

Spec 02 directly integrates with Spec 01 during the initial session handshake:

When Peer A connects to Peer B, Peer A presents its DeviceCertificate.
Peer B verifies that the certificate is signed by an accepted RootPublicKey and checks that the device is marked Active in its TrustedAccountStore.
Spec 01 intersects the peer’s advertised protocol extensions with the device’s authorized DeviceCapabilitySet. If a device lacks the INITIATE_CALLS bit, the session multiplexer refuses to open the realtime voice extension channel, rejecting unauthorized streams before a single byte of media is decoded.
11.2 Transport Neutrality & Multipath Routing (Specs 03 & 12)
Each entry in the DeviceDirectory holds a list of DeviceEndpoint byte arrays:

pub struct DeviceEndpoint(pub Vec);
Notice that DeviceEndpoint is an opaque byte wrapper. Spec 02 deliberately avoids hardcoding IP addresses, port numbers, or Bluetooth UUIDs into the identity schema.

The Transport Routing Policy Engine (Specs 03 & 12) unpacks these endpoints:

A node on a high-speed corporate LAN resolves DeviceEndpoint to a QUIC UDP socket via Iroh.
A field unit in a subterranean bunker resolves DeviceEndpoint to a rotating BLE service UUID or Wi-Fi Direct P2P Group Owner MAC.
Multipath routing seamlessly switches active streams between cellular and Bluetooth without invalidating the underlying DeviceId or breaking the cryptographic session.
11.3 Asynchronous Bundle Gossip via DTN (Specs 04 & 06)
In severed, disaster-stricken areas with zero network connectivity, directory synchronization cannot rely on live TCP/QUIC handshakes.

Spec 02 directories are serialized into immutable DTN Storage Bundles governed by Specs 04 & 06. A mobile disaster-response vehicle driving between remote mountain clinics physically carries these signed directory bundles on ruggedized flash storage. When the vehicle arrives at a clinic, its local daemon gossips the latest directory snapshots over ad-hoc Wi-Fi. The clinic’s local mesh immediately learns of revocations and newly linked field devices without ever touching the internet.

11.4 End-to-End Encryption: MLS Tree & Pairwise Double Ratchet (Spec 28)
Spec 02 provides the cryptographic leaf nodes for Spec 28: Production Security & E2EE Key Management:

Pairwise Messaging: When two devices communicate directly, they instantiate an X25519 Double Ratchet session initialized via signed prekey bundles (PrekeyBundle) published by each active DeviceId.
Group Communication: In multi-user channels, SIAR deploys Messaging Layer Security (MLS, RFC 9420). In the MLS ratchet tree, each leaf node corresponds to a verified DeviceId from Spec 02. When a device is revoked in Spec 02, the MLS group controller automatically issues an MLS Remove proposal, updating the ratchet tree and ratcheting the group encryption key forward to guarantee immediate post-revocation forward secrecy.
11.5 Realtime Media & Multi-Device Call Ring Arbitration (Spec 29)
When an incoming video call arrives for an account with multiple active devices, how do we prevent three devices from screaming simultaneously and answering at the exact same second?

Spec 02 and Spec 29 coordinate through the Call Ring Arbitration Protocol:

Incoming Call to Account Alice -> Fan-Out to [Phone, Laptop, Tablet]
• All 3 devices ring simultaneously.
• Alice taps "Answer" on her Laptop.
• Laptop emits a signed CallClaim event:
Claim { call_id: 104, winner: Laptop, timestamp: T, sig: LaptopKey }
• Phone and Tablet verify the signature, immediately silence their ringers,
and transition their UI to "Answered on another device".
Because each device possesses an independent DeviceId and signing key, call pickup arbitration is cryptographically provable and immune to race-condition hijacking.

Defensive Engineering in Rust: Auditing the 21-Item Definition of Done The crates/siar-identity-multidevice crate is engineered under the strictest systems constraints:

![forbid(unsafe_code)]: Zero unsafe pointer dereferences or memory transmutation anywhere in the codebase.

Zero anyhow in Public Domain APIs: All errors are strongly typed through exhaustive enums (IdentityError, RevocationError, RecoveryError) via thiserror.
Deterministic Serialization: No platform-dependent types (usize, isize) on the wire; all integers are explicitly sized (u64, u32, u16, u8).
Memory Zeroization: Secret keys implement the Zeroize trait on drop to purge sensitive key material from CPU registers and RAM caches.
The 21-Item Definition-of-Done Self-Audit
In crates/siar-identity-multidevice/src/definition_of_done.rs, the engineering team implemented a programmatic 21-item Definition-of-Done (DoD) audit covering every requirement of Spec 02:

[derive(Debug, Clone, Copy, PartialEq, Eq)]

pub enum DodStatus {
Done,
PartiallyDone,
NotStarted,
}

pub struct DodItem {
pub section: u32,
pub title: &'static str,
pub status: DodStatus,
pub rationale: &'static str,
}
The self-audit outcome is documented with absolute engineering honesty:

19 of 21 requirements are fully Done: Covering cryptographic identity models, signed snapshots, monotonic rollback protection, fork detection, instant revocation, root rotation, SAS verification, least-authority capabilities, and cross-subsystem integration.
2 of 21 items are honestly classified as PartiallyDone:
UserConfirmationRequired (§20): The data structure (LinkingApprovalPrompt) is implemented and strictly typed, but the crate ships no graphical user interface (UI) by design. The UI boundary lives in downstream GUI shells (siar-ui-desktop / siar-ui-android).
FuzzPropertyIntegrationTestsExist (§164): Extensive proptest property suites (security_invariants.rs) and integration suites (integration_tests.rs) run continuously in CI; a dedicated AFL/LLVM cargo-fuzz harness is queued for the Milestone 2 security audit.
Property Testing Cryptographic Invariants
To ensure no subtle regressions compromise security, the test suite leverages property-based testing:

[test]

fn prop_directory_signature_tamper_fails() {
let root = RootIdentityKey::generate();
let account = AccountId([1u8; 32]);
let dir = DeviceDirectory::sign(&root, account, 1, vec![]);

// Any single bit mutation in the signature must fail verification
let mut bad_sig = dir.signature.clone();
bad_sig[0] ^= 0xFF;

let bad_dir = DeviceDirectory {
    signature: bad_sig,
    ..dir
};

assert!(bad_dir.verify_signature(&root.root_public_key()).is_err());

}

[test]

fn prop_rollback_attempt_is_rejected() {
let root = RootIdentityKey::generate();
let account = AccountId([2u8; 32]);
let mut store = TrustedAccountStore::new();

let dir_g5 = DeviceDirectory::sign(&root, account, 5, vec![]);
let dir_g4 = DeviceDirectory::sign(&root, account, 4, vec![]);

assert!(store.accept(dir_g5, &root.root_public_key()).is_ok());

// Attempting to accept G4 after G5 must return RollbackRejected
let err = store.accept(dir_g4, &root.root_public_key()).unwrap_err();
assert!(matches!(err, IdentityError::RollbackRejected { given: 4, highest: 5 }));

}
Every invariant is tested not through wishful thinking, but through exhaustive programmatic verification against real compiled binaries.

Ten Axioms for Distributed Multi-Device Identity Systems Drawing from the architectural design of Spec 02, we offer ten foundational axioms for systems architects building modern local-first, peer-to-peer, or decentralized communication protocols:

Never Conflate Account and Device: An account is a durable principal; a device is a physical possession. Model them as distinct cryptographic entities from day one.
Never Export Private Keys Across Physical Boundaries: Device linking must be an act of cryptographic delegation and certification, never the physical transmission or export of long-lived private keys.
The Root Key Must Sleep: Reserve the root signing key exclusively for issuing certificates, directories, and root rotations. Never use it to sign chat messages or establish transport sessions.
Enforce Monotonic State Progression: In the absence of central databases, state rollback attacks are trivial unless directory snapshots carry strictly monotonic generation numbers enforced by a local trust store.
Treat State Equivocation as a Security Breach: Conflicting signed states at the same generation number must never be silently resolved by timestamps or random selection. Treat forks as an immediate signal of key compromise.
Keep Secret Material Out of Pairing Signals: Dynamic QR codes and NFC payloads must encode zero private keys or session secrets. Use them only to bootstrap authenticated ephemeral Diffie-Hellman handshakes.
Tie Pairing Codes to the Full Transcript: Verification codes (SAS) must be cryptographically derived from both ephemeral public keys, the signed invite, and the shared secret. Never display random numbers.
Make Revocation Immediate and Synchronous: Revocation must not require an internet connection or server handshake. A local trusted device must be able to advance generation $G+1$ and blackball a compromised key instantly.
Apply the Principle of Least Authority to Hardware: Distinguish device roles through compact capability bitsets. Headless relays, edge repeaters, and IoT nodes should hold zero keys capable of reading chat or adding devices.
Preserve Device-Level Truth in the Core: Attribute packets and delivery receipts to specific physical devices at the data plane, while presenting a clean, unified account identity at the human interface.

Conclusion & Next Steps in the Series Decentralized communications cannot mature into global, mission-critical infrastructure if we continue to force users into the fragile world of single-key cryptography or surrender their autonomy to centralized coordination servers.

Spec 02: Multi-Device Identity Architecture demonstrates that sovereign, local-first architectures can achieve the seamless user experience of modern cloud messengers without compromising cryptographic rigor. By establishing a five-tier identity separation, enforcing monotonic generation ratchets, conducting zero-knowledge pairing ceremonies, and binding least-authority capability bitsets directly into signed directory snapshots, SIAR delivers an identity substrate capable of surviving both nation-state cyberattacks and total infrastructure collapse.

In Part 3 of this 24-part deep-dive series, we will explore Spec 03: Transport Routing Policy Engine Architecture (crates/siar-routing-policy). We will examine how SIAR abstracts physical network bearers, performs dynamic link cost estimation, executes multi-bearer failovers between QUIC, Wi-Fi Aware, and BLE, and routes encrypted packets across fragmented, partition-heavy mesh networks.

Subscribe to follow along as we build the survivable, decentralized communication stack of the next century.

# Architecting a Zero-Monolith P2P Protocol: How SIAR Solves Versioning, Capabilities, and Backpressure in Rust

Irshad Ali — Tue, 08 Sep 2026 17:17:24 +0000

By the SIAR Engineering Team

Target Platforms: Substack / Dev.to | Technical Deep-Dive Series: Part 1 of 24

Focus: Spec 01 — Protocol Extension System Architecture (crates/siar-protocol-ext)

                       +---------------------------------------+
                       |           Application Layer           |
                       |  (Messaging, Files, ERP, Emergency)   |
                       +-------------------+-------------------+
                                           |
                                           v
                       +---------------------------------------+
                       |       Extension Protocol Layer        |
                       |   (Independently Versioned Specs)     |
                       +-------------------+-------------------+
                                           |
                                           v
                       +---------------------------------------+
                       |      Session Multiplexer Engine       |
                       |    (Fair Weighted Round-Robin + WFQ)   |
                       +-------------------+-------------------+
                                           |
                                           v
                       +---------------------------------------+
                       |          Core Control Protocol        |
                       |    (Identity, Handshake, Capability)  |
                       +-------------------+-------------------+
                                           |
                                           v
                       +---------------------------------------+
                       |     Transport Abstraction (Multi)     |
                       |   (Iroh QUIC / BLE / Wi-Fi / DTN)     |
                       +---------------------------------------+

Introduction: The Monolithic Protocol Trap
The Architectural Axioms of SIAR
The Anatomy of Spec 01: Core vs. Extension Separation
Namespaces, Identifiers, and Session-Local Translation
The Mathematics of Capability Negotiation
Defensive Data Plane: Safe Framing and Zero Memory Exhaustion
Flow Control, Backpressure, and Weighted Fair Scheduling
Lifecycle State Machines, Lazy Opening, and Mobile Energy Discipline
Cross-Subsystem Integration: Grounding Spec 01 in the Real World
- 9.1 Transport Neutrality & Multipath Routing (Specs 03 & 12)
- 9.2 Delay-Tolerant Networking & Asynchronous Bundles (Specs 04 & 06)
- 9.3 Multi-Device Identity & MLS E2EE Boundaries (Specs 02 & 28)
- 9.4 Headless Daemons & Embedded Linux Repeaters (Specs 16 & 20)
Rust Implementation Deep-Dive: A Tour of siar-protocol-ext
Verification, Property Testing, and Golden Wire Invariants
Ten Golden Rules for Distributed Protocol Designers
Conclusion & Next Steps in the Series

1. Introduction: The Monolithic Protocol Trap

Every ambitious peer-to-peer (P2P), local-first, or decentralized protocol begins with clean intentions and a simple wire layout. You define a message enum in your favorite systems language, write a serializer, spin up a socket, and send packets between two nodes. It feels effortless:

// The seductive, fatal trap of early P2P protocol design
pub enum ProtocolMessage {
    Hello { peer_id: [u8; 32], version: u32 },
    TextMessage { id: u64, content: String },
    FileChunk { file_id: u64, offset: u64, data: Vec<u8> },
    Heartbeat,
}

This works delightfully in a staging environment. But six months later, reality strikes:

Feature Coupling & Version Bloat: Your team adds audio calls. Then reactions. Then group metadata synchronization. Then emergency disaster alerts. Your simple enum swells to seventy variants. Suddenly, every micro-embedded sensor, solar-powered field repeater, and headless storage daemon running your codebase is forced to pull in cryptographic libraries, multimedia codecs, and complex group ratchet engines just to deserialize incoming packets.
The Fragile Wire Cascade: A developer modifies the payload of TextMessage to support rich formatting or read receipts. Two clients running different minor releases connect over an ad-hoc Wi-Fi link. The older client encounters an unknown tag or deserialization error, panics, drops the connection, and the entire peer session collapses.
The Central Governance Bottleneck: A partner company or third-party engineering team wishes to deploy an enterprise-specific inventory sync workflow over your mesh. Under the centralized enum model, they cannot do this without submitting a pull request to your core repository, modifying your enum, and convincing you to release a new global protocol version.
Memory and Head-of-Line Starvation: A node initiates a 200 MB file transfer over a low-bandwidth Bluetooth Low Energy (BLE) link while another node broadcasts a time-sensitive emergency SOS alert. Because the protocol treats all variants as equal members of a flat pipeline, the multi-megabyte file chunks flood the socket queues, exhausting memory buffers and starving life-critical beacons.

This architectural failure mode is the Monolithic Protocol Trap. It has crippled dozens of P2P and distributed systems, transforming modular software into brittle, unmaintainable monoliths where protocol evolution grinds to a halt.

When we set out to build SIAR (Survivable Identity & Autonomous Routing)—a zero-infrastructure, multi-transport, offline-first mesh communications system designed to survive total internet blackouts, natural disasters, and hostile network partitions—we made a foundational commitment:

The protocol must evolve through independently versioned, capability-negotiated extensions, never through an ever-growing central enum.

This principle forms the basis of Spec 01: Protocol Extension System Architecture, realized in the pure-Rust siar-protocol-ext crate. In this technical deep-dive, we break down how Spec 01 achieves true zero-coupling modularity, how capability negotiation prevents session failures across disparate node generations, how we enforce hard byte-level backpressure at the data plane, and how this architecture scales seamlessly from 4MB embedded Linux repeaters to modern Android and desktop clients.

2. The Architectural Axioms of SIAR

To understand the mechanics of Spec 01, one must understand the operating environment for which SIAR is engineered. SIAR is not another centralized messenger wrapping a cloud server in an Electron shell. It is a multi-bearer, delay-tolerant networking (DTN) platform operating across four strict physical and logical layers:

+-------------------------------------------------------------------------+
|                  SIAR Platform Architecture Axioms                      |
+-------------------------------------------------------------------------+
|  1. Rust-First Bare-Metal Core: Deterministic memory, zero garbage      |
|     collection pauses, compile-time thread safety, and cross-platform   |
|     hermeticity (Linux, Android NDK, macOS, Windows, Embedded).         |
|                                                                         |
|  2. Zero Central Infrastructure: Identity is cryptographic (Ed25519     |
|     keypairs, X25519 DH). No central directory, no cloud authorization.  |
|                                                                         |
|  3. Multi-Bearer Opportunistic Transport: Dynamic switching between     |
|     Iroh QUIC (direct WAN/LAN), Wi-Fi Direct, Wi-Fi Aware (NAN), BLE,   |
|     and Bluetooth Classic without dropping active sessions.             |
|                                                                         |
|  4. Asynchronous Store-Carry-Forward (DTN): Physical data ferrying      |
|     across severed networks via solar field repeaters and moving nodes.  |
|                                                                         |
|  5. Hard Memory & Battery Boundaries: Mobile devices must not burn      |
|     battery initializing unneeded subsystems; embedded nodes must never |
|     panic from unbounded allocation under malicious traffic.            |
+-------------------------------------------------------------------------+

Under these axioms, any design pattern that forces tight coupling between product features (such as chat, file distribution, and presence) and transport or network machinery is strictly fatal.

If a disaster-relief team deploys a battery-powered Raspberry Pi headless daemon (siar-emergency-node) on a mountaintop, that node needs to forward DTN storage bundles, negotiate peer capabilities over Wi-Fi, and route emergency beacons. It must never know what a user avatar is, how markdown chat messages are parsed, or what codec a video call requires.

Spec 01 provides the rigorous architectural blueprint that makes this strict modularity mathematically and programmatically enforceable.

3. The Anatomy of Spec 01: Core vs. Extension Separation

The central breakthrough of Spec 01 is an uncompromising separation of concerns between the Core Control Protocol and Extension Protocols.

                                  +------------------------------+
                                  |     Communication Session    |
                                  +--------------+---------------+
                                                 |
         +-----------------------+---------------+-----------------------+
         |                       |                                       |
         v                       v                                       v
+-----------------+     +-----------------+                     +-----------------+
|  Core Control   |     |    Messaging    |                     | File Subsystem  |
|    Protocol     |     |    Extension    |                     |    Extension    |
| (Always Present)|     | (org.siar/msg/1)|                     |(org.siar/file/1)|
+-----------------+     +-----------------+                     +-----------------+
| • Hello         |     | • Text payload  |                     | • Chunk payload |
| • Peer Auth     |     | • Reactions     |                     | • Hash manifest |
| • Capabilities  |     | • Read receipts |                     | • Resumption    |
| • Extension Mux |     | • Outbox sync   |                     | • Stream window |
| • Flow Metadata |     +-----------------+                     +-----------------+
| • Error Framing |
+-----------------+

3.1 What the Core Protocol Knows

The Core Protocol is the minimal set of semantics required for any two nodes to establish a secure, authenticated, and bounded conversation. It is intentionally small, invariant, and universally implemented by every peer in the SIAR ecosystem.

Its responsibilities are strictly limited to:

Session Handshake (Hello / HelloAck): Authenticating peer identities via cryptographic signatures and agreeing upon the core framing version.
Peer Identity Binding: Cryptographically proving that the transport link corresponds to the claimed public key (DeviceIdentity).
Extension Advertisement: Exchanging the inventory of protocol extensions supported by each node.
Capability Negotiation: Performing deterministic mathematical intersection over the capability sets of mutually supported extensions.
Extension Lifecycle Management: Opening, closing, pausing, and resuming logical extension channels (ExtensionOpen, ExtensionClose).
Session-Level Flow Control: Exchanging window updates, queue pressure signals, and keep-alive pings.
Error Framing: Emitting deterministic error codes when wire semantics are violated.

3.2 What the Core Protocol Never Knows

By specification, the Core Protocol has zero knowledge of:

The structure of a chat message or whether text is UTF-8 or encrypted ciphertext.
File transfer chunk sizes, ranges, hashes, or storage paths.
Presence states, typing indicators, or read receipts.
Group membership lists or MLS cryptographic epoch trees.
Emergency SOS coordinate layouts or disaster medical telemetry.
Enterprise-specific business objects or ERP forms.

All application logic lives entirely within self-contained Extension Protocols. If an unknown extension frame arrives, the core protocol multiplexer does not drop the session or trigger a deserialization fault. It routes it according to established forward-compatibility rules: optional extensions are cleanly ignored; required extensions fail gracefully with structured wire diagnostics.

4. Namespaces, Identifiers, and Session-Local Translation

How do nodes refer to protocol extensions without collisions, centralized registries, or string parsing bottlenecks? Spec 01 establishes a two-phase identifier model: Globally Unique Canonical Identifiers on the outside, and Session-Local Numeric Identifiers on the wire.

4.1 Hierarchical Global Namespaces

Every protocol extension is uniquely identified across the universe by a three-part canonical identifier:

$$\text{ProtocolId} = \langle\text{NamespaceId}\rangle \,/\, \langle\text{ProtocolName}\rangle \,/\, \langle\text{ProtocolMajor}\rangle$$

Examples:

org.siar.comm/messaging/1
org.siar.comm/files/1
org.siar.comm/presence/1
org.siar.emergency/sos/1
com.acme.logistics/pallet-telemetry/2

In crates/siar-protocol-ext/src/identifier.rs, this is enforced through strongly typed structs that prevent loose string manipulation:

#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct ProtocolId {
    pub namespace: NamespaceId,
    pub protocol: ProtocolName,
    pub major: ProtocolMajor,
}

impl ProtocolId {
    pub fn new(namespace: &str, protocol: &str, major: u32) -> Result<Self, ProtocolIdError> {
        let namespace = NamespaceId::parse(namespace)?;
        let protocol = ProtocolName::parse(protocol)?;
        Ok(Self {
            namespace,
            protocol,
            major: ProtocolMajor(major),
        })
    }

    /// Returns the canonical RFC-style wire representation
    pub fn to_canonical_string(&self) -> String {
        format!("{}/{}/{}", self.namespace.as_str(), self.protocol.as_str(), self.major.0)
    }
}

Notice the inclusion of major directly in the protocol identity. Under Spec 01, a bump in the major version signifies an inherently wire-incompatible change. Therefore, org.siar.comm/messaging/1 and org.siar.comm/messaging/2 are treated by the runtime as two completely distinct protocols that happen to share a namespace. A node can advertise support for both simultaneously, allowing clean backward compatibility during multi-year network transitions.

4.2 Ephemeral Session-Local IDs

While canonical strings like org.siar.comm/messaging/1 are vital for debugging, logging, and third-party developer clarity, sending a 30-byte string in the header of every single data frame over a 20 kbps BLE connection would impose unacceptable protocol overhead.

Spec 01 resolves this through Session-Local ID Translation:

Negotiation Phase (Handshake):
  Peer A -> Peer B: "I support 'org.siar.comm/messaging/1' and 'org.siar.comm/files/1'"
  Peer B -> Peer A: "Agreed. For this session:
                     'org.siar.comm/messaging/1' => SessionLocalExtensionId(1)
                     'org.siar.comm/files/1'     => SessionLocalExtensionId(2)"

Data Plane Phase (Streaming):
  [Frame Header: StreamId(1) | LocalExtId: 0x0001 | Len: 256 | Payload: ...]
  [Frame Header: StreamId(2) | LocalExtId: 0x0002 | Len: 1024| Payload: ...]

The wire framing uses a fixed-width u16 (SessionLocalExtensionId). The mapping is negotiated dynamically during session initialization, stored in a fast contiguous lookup array on both peers, and discarded when the transport disconnects. We achieve the diagnostic power of human-readable namespaces with the wire density of hand-optimized binary protocols.

5. The Mathematics of Capability Negotiation

In distributed networks, version numbers are notoriously deceptive. Suppose two nodes both claim to support org.siar.comm/messaging/1. Does that mean they can exchange inline images? Can they edit messages after transmission? Can they process reaction emojis or read receipts?

If you rely solely on version numbers, you enter "version matrix hell," where engineers write fragile conditional logic:

// The wrong way: version check spaghetti
if peer.minor_version >= 4 && peer.patch_version != 2 {
    send_reaction();
}

Spec 01 replaces this with Explicit Set-Theoretic Capability Negotiation.

5.1 Capabilities as Independent Bitsets

Within an extension, features are modeled as discrete capabilities identified by a fixed-width CapabilityId(u32):

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct CapabilityId(pub u32);

#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct CapabilitySet {
    values: BTreeSet<CapabilityId>,
}

impl CapabilitySet {
    /// Compute the negotiated feature subset: Local ∩ Remote
    pub fn intersect(&self, remote: &CapabilitySet) -> CapabilitySet {
        let intersection: BTreeSet<CapabilityId> = self
            .values
            .intersection(&remote.values)
            .copied()
            .collect();
        CapabilitySet { values: intersection }
    }

    pub fn contains(&self, id: CapabilityId) -> bool {
        self.values.contains(&id)
    }
}

When defining an extension, developers assign stable numeric IDs to concrete capabilities. For example, in SIAR's messaging extension:

pub mod messaging_caps {
    use super::CapabilityId;
    pub const TEXT: CapabilityId          = CapabilityId(1);
    pub const REPLY: CapabilityId         = CapabilityId(2);
    pub const EDIT: CapabilityId          = CapabilityId(3);
    pub const REACTION: CapabilityId      = CapabilityId(4);
    pub const READ_RECEIPT: CapabilityId  = CapabilityId(5);
    pub const TYPING: CapabilityId        = CapabilityId(6);
    pub const GROUP_MESSAGING: CapabilityId = CapabilityId(7);
}

5.2 The Two-Phase Negotiation Flow

When two peers connect, they execute a strictly sequenced negotiation handshake:

sequenceDiagram
    autonumber
    participant Alice as Peer A (Modern Node v1.4)
    participant Bob as Peer B (Field Node v1.1)

    Alice->>Bob: CORE_HELLO (Protocols: [msg/1 {text, reply, edit, react}, files/1 {resume}])
    Note over Bob: Evaluates Local Manifest against Alice's Advertisement
    Note over Bob: Computes Intersection for msg/1: {text, reply}<br/>edit & react unsupported locally
    Bob->>Alice: CORE_HELLO_ACK (Accepted: [msg/1 {text, reply} (LocalId=1)], Rejected: [files/1: Unsupported])
    Note over Alice: Validates Required vs Optional Constraints
    Note over Alice: Session Established: msg/1 active at LocalId=1 with {text, reply}

The mathematical rule governing the session is absolute:

$$\mathcal{C}{\text{active}} = \mathcal{C}{\text{local}} \cap \mathcal{C}_{\text{remote}}$$

No node is ever allowed to transmit an operation on the wire unless its required capability exists within $\mathcal{C}_{\text{active}}$. If a user taps "React with ❤️" on a modern smartphone, but the peer on the other end of the mesh is a legacy node lacking messaging_caps::REACTION, the local UI gracefully disables the action or displays a subtle fallback indicator. Not a single invalid byte is sent over the radio.

5.3 Mandatory vs. Optional Extension Semantics

Not all extensions are created equal. A specialized desktop file-transfer utility requires files/1 to be useful, whereas a general-purpose messenger considers files/1 an optional luxury:

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ExtensionRequirement {
    Required,
    Optional,
}

Spec 01 enforces two invariant safety rules during negotiation:

The Optional Extension Rule: If Peer A advertises an optional extension that Peer B does not support (or whose major versions do not overlap), the negotiation engine simply omits that extension from the active session. An unsupported optional extension must never tear down the peer connection.
The Required Extension Rule: If Peer A requires an extension that Peer B cannot satisfy, the negotiation fails deterministically with NegotiationError::MissingRequiredExtension. The session is halted before any application data can be corrupted or misinterpreted.

6. Defensive Data Plane: Safe Framing and Zero Memory Exhaustion

P2P networks are inherently adversarial. A peer connection might be a trusted family member's phone, an untrusted passerby's Bluetooth radio, or a malicious actor intentionally injecting malformed frames to trigger buffer overflows and crash mesh repeaters.

The golden rule of systems programming in P2P is: Never trust remote length fields.

6.1 The 4-Step Framing Sequence

In crates/siar-protocol-ext/src/framing.rs, we mandate that frame deserialization occur through a four-step, non-collapsible verification barrier:

[ Incoming Byte Stream ]
          |
          v
+-------------------------------------------------------------+
| Step 1: Read Exactly Bounded Header (FRAME_HEADER_BYTES=10) |
+-------------------------------------------------------------+
          |
          v
+-------------------------------------------------------------+
| Step 2: Validate Wire Length Against Absolute Protocol Max  |
|         (frame_length <= ABSOLUTE_MAX_FRAME_SIZE: 16 MB)    |
+-------------------------------------------------------------+
          |
          v
+-------------------------------------------------------------+
| Step 3: Check Against Negotiated Extension Limits           |
|         (frame_length <= extension_limits.max_frame_size)   |
|         e.g., Messaging = 64 KB, Files = 1 MB               |
+-------------------------------------------------------------+
          |
          v
+-------------------------------------------------------------+
| Step 4: Allocate Buffer Safely & Read Payload Bytes         |
+-------------------------------------------------------------+

Many vulnerable network daemons collapse these steps into one: they read a length integer from the wire and immediately invoke Vec::with_capacity(remote_length). If a malicious peer transmits a header claiming a payload of 0xFFFFFFFF (4 GB), the receiving node attempts to allocate 4 gigabytes of memory and panics via an out-of-memory (OOM) abort.

In SIAR, step 3 intercepts the frame before allocation takes place:

pub const FRAME_HEADER_BYTES: usize = 10;
pub const ABSOLUTE_MAX_FRAME_SIZE: u32 = 16 * 1024 * 1024; // 16 MB ceiling

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FrameHeader {
    pub frame_length: u32,
    pub session_extension_id: SessionLocalExtensionId,
    pub frame_type: u8,
    pub flags: u8,
}

pub fn parse_frame_header(buf: &[u8]) -> Result<FrameHeader, FramingError> {
    if buf.len() < FRAME_HEADER_BYTES {
        return Err(FramingError::IncompleteHeader);
    }
    let frame_length = u32::from_be_bytes([buf[0], buf[1], buf[2], buf[3]]);
    let ext_id = u16::from_be_bytes([buf[4], buf[5]]);
    let frame_type = buf[6];
    let flags = buf[7];

    if frame_length > ABSOLUTE_MAX_FRAME_SIZE {
        return Err(FramingError::OversizedFrame(frame_length));
    }

    Ok(FrameHeader {
        frame_length,
        session_extension_id: SessionLocalExtensionId(ext_id),
        frame_type,
        flags,
    })
}

pub fn validate_frame_length(
    header: &FrameHeader,
    limits: &ExtensionLimits,
) -> Result<(), FramingError> {
    if header.frame_length as usize > limits.max_frame_size {
        return Err(FramingError::ExceedsExtensionLimit {
            requested: header.frame_length,
            limit: limits.max_frame_size,
        });
    }
    Ok(())
}

If a peer sends a 512 KB frame on the messaging extension (which declares a strict 64 KB limit), the frame is rejected at Step 3 with zero heap allocations performed. The node classifies this violation, closes the abusive channel, and remains fully operational.

6.2 Serialization Discipline: Separation of Wire and Domain Models

Spec 01 establishes strict rules regarding serialization:

Domain Types Are Never Wire Types: You must never attach #[derive(Serialize, Deserialize)] to an internal database or UI struct and blast it over the network. Domain models change as features evolve; wire formats must remain immortal. Every extension maintains a dedicated wire module containing explicit, versioned schema representations.
Fixed-Width Integers Only: The Rust usize type is strictly forbidden on the wire. A usize is 4 bytes on a 32-bit ARM Cortex-M micro-controller and 8 bytes on an x86_64 server. Using usize on the wire destroys cross-architecture interoperability. Wire structs exclusively use u8, u16, u32, u64, and fixed-length byte arrays.
Rust Is the Reference Implementation, Not the Wire Specification: The wire protocol must be fully specifiable without referencing the Rust compiler's internal memory layout. No #[repr(C)] struct dumps, no native endianness assumptions (big-endian network order is strictly enforced), and no compiler-generated enum discriminant assumptions.

7. Flow Control, Backpressure, and Weighted Fair Scheduling

When devices communicate over heterogeneous, intermittent paths, transmission speeds diverge by multiple orders of magnitude. A local Wi-Fi 6 link can easily move 500 megabits per second. A Bluetooth Low Energy (BLE) link struggles to deliver 40 kilobits per second. A multi-hop DTN mesh route across field repeaters might transmit in sporadic 10-kilobyte bursts spaced minutes apart.

If a local desktop client begins streaming a 50 MB video file while connected to a phone over BLE, what happens if the phone's receiver cannot write to disk or drain its network socket as fast as the desktop pumps bytes?

Without hard backpressure, the desktop's outgoing buffers explode in memory, the phone's incoming buffers overflow, packets drop, radios thrash in retransmission storms, and the device overheats.

7.1 True Backpressure via Ownership Rejection

In crates/siar-protocol-ext/src/backpressure.rs, backpressure is not an optional advisory flag—it is a physical gate. Queues are strictly bounded in both item count and aggregate byte capacity:

pub struct BoundedQueue<T> {
    items: VecDeque<T>,
    max_items: usize,
    current_bytes: usize,
    max_bytes: usize,
}

impl<T: Measurable> BoundedQueue<T> {
    pub fn push(&mut self, item: T) -> Result<(), BackpressureRejection<T>> {
        let item_size = item.byte_size();
        if self.items.len() >= self.max_items || self.current_bytes + item_size > self.max_bytes {
            // Hand the item back to the caller! Zero allocations, no silent drops.
            return Err(BackpressureRejection {
                rejected_item: item,
                current_depth: self.items.len(),
                current_bytes: self.current_bytes,
            });
        }
        self.current_bytes += item_size;
        self.items.push_back(item);
        Ok(())
    }
}

Notice the return signature: Result<(), BackpressureRejection<T>>. If the queue is at capacity, the queue does not drop the item into the void, nor does it block the thread indefinitely. It returns ownership of the item back to the caller. The calling subsystem immediately senses backpressure and must throttle its own upstream producer, pausing file-chunk reads from disk until socket drain events fire.

7.2 Multi-Tier Traffic Priorities

Different categories of protocol traffic have radically different urgency profiles. Spec 01 formalizes a 6-tier priority hierarchy:

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum TrafficPriority {
    Critical,     // Life-safety SOS alerts, disaster beacons, route failure notices
    Control,      // Flow control windows, ping/pong, capability re-negotiation
    Interactive,  // Direct human typing, ephemeral text messages, voice signaling
    Normal,       // Message delivery receipts, contact card updates, avatars
    Bulk,         // Media attachments, encrypted file chunks, database backups
    Background,   // Diagnostic sync, DHT gossip maintenance, log exports
}

7.3 Weighted Fair Scheduling with Bounded Emergency Override

A naive scheduler would simply serve traffic using a strict priority queue: always send Critical first, then Control, down to Background.

This naive approach is disastrous in distributed systems because it introduces Perpetual Starvation. If an aggressive background sync routine or a steady stream of interactive text messages saturates a slow BLE link, bulk file transfers will never send a single byte. Worse, if an errant node or bug generates continuous high-priority traffic, the entire communication pipeline deadlocks.

Spec 01 implements Weighted Fair Round-Robin (WFRR) with a Bounded Emergency Override in crates/siar-protocol-ext/src/scheduler.rs:

Priority Tier Weights:
  Interactive  ===> Weight: 8 packets / round
  Normal       ===> Weight: 4 packets / round
  Bulk         ===> Weight: 2 packets / round
  Background   ===> Weight: 1 packet  / round

Emergency Override Gate:
  Critical / Control packets bypass the round-robin schedule immediately,
  BUT are capped at MAX_CONSECUTIVE_CRITICAL (e.g., 16 packets).
  Once the burst cap is reached, the scheduler forcibly yields at least
  one time-slice to lower-tier queues to prevent total channel starvation.

This guarantees two mathematical invariants:

Bounded Latency for Emergencies: An incoming emergency SOS message is guaranteed immediate transmission ahead of all queued file chunks.
Starvation Freedom: Bulk and background queues are mathematically guaranteed forward progress over any sustained time window.

8. Lifecycle State Machines, Lazy Opening, and Mobile Energy Discipline

On mobile operating systems (Android and iOS), background execution is an unforgiving environment. If an app awakens in the background to handle an incoming push or mesh ping, and immediately spins up camera drivers, audio resampling pipelines, SQLite databases, and cryptography ratchets, the operating system's battery monitor will terminate the process within milliseconds.

Spec 01 mandates an explicit Extension Lifecycle State Machine combined with Lazy Extension Opening.

+--------------+        Peer Advertisement        +--------------+
|  Registered  | -------------------------------> |  Advertised  |
+--------------+                                  +--------------+
                                                         |
                                                         | Core Negotiation
                                                         v
+--------------+         Close Signal             +--------------+
|    Closed    | <------------------------------- |  Negotiated  |
+--------------+                                  +--------------+
       ^                                                 |
       |                                                 | User Triggers Feature
       |                                                 | (OPEN_EXTENSION)
       |                                                 v
+--------------+        Unrecoverable Fault       +--------------+
|   Closing    | <------------------------------- |   Active     |
+--------------+                                  +--------------+

8.1 The Power of Dormant Negotiation

Under Spec 01, negotiating an extension during the initial handshake does not initialize that extension.

Consider this real-world scenario:

Two SIAR nodes pair over BLE. They negotiate support for:
- org.siar.comm/messaging/1
- org.siar.comm/files/1
- org.siar.media/calls/1
The core session enters the SessionEstablished state.
The messaging extension transitions to Active because text messaging is the primary interactive service.
The files and calls extensions remain in the Negotiated (dormant) state.
- Zero file transfer threads are spawned.
- Zero audio DSP pipelines or Opus codecs are allocated in memory.
- Zero storage handles are opened.

Only when a user taps "Send 50MB PDF" or "Call Contact" does the runtime transmit a lightweight ExtensionOpen control frame across the wire. Both peers transition that specific extension from Negotiated to Active, spin up the necessary machinery, and begin data exchange. When the transfer completes or the call ends, an ExtensionClose frame returns the extension to dormant status, releasing system buffers and allowing mobile CPUs to drop back into deep sleep.

8.2 Graceful vs. Abrupt Shutdown Semantics

Mobile and mesh nodes do not live in polite data centers. A user walks out of Bluetooth range, a battery dies, or an Android task killer strikes. The protocol must guarantee data integrity under sudden disconnection.

Spec 01 divides shutdown into two cleanly separated pipelines:

pub const GRACEFUL_SHUTDOWN_STEPS: &[&str] = &[
    "stop_accepting_new_work",
    "flush_outbox_buffers",
    "persist_session_state",
    "send_close_frame",
    "release_network_handles",
];

pub const ABRUPT_SHUTDOWN_STEPS: &[&str] = &[
    "detect_transport_drop",
    "mark_in_flight_operations_recoverable",
    "persist_resumable_byte_offsets",
    "release_transient_buffers",
];

By distinguishing graceful flushing from abrupt failure handling, SIAR guarantees that a sudden radio disconnect never leaves SQLite state corrupted or partial file chunks orphaned without resumption markers.

9. Cross-Subsystem Integration: Grounding Spec 01 in the Real World

While Spec 01 is implemented cleanly as a standalone crate (crates/siar-protocol-ext), its true architectural brilliance emerges when you observe how it seamlessly integrates with the rest of the SIAR platform specifications.

+------------------------------------------------------------------------------------+
|                         SIAR System Specifications Matrix                          |
+------------------------------------------------------------------------------------+
| Spec 01: Protocol Extension System (Foundation)                                    |
|   |---> Spec 02: Multi-Device Identity   ===> Authenticated Identity Binding       |
|   |---> Spec 03: Transport Routing       ===> DeliveryClass-based link selection   |
|   |---> Spec 04/06: Offline Event Log/DTN===> Store-Carry-Forward persistence      |
|   |---> Spec 08: Resource Limits         ===> Per-peer memory & quota enforcement   |
|   |---> Spec 16/20: Headless & Embedded  ===> Zero-UI headless repeater binaries   |
|   |---> Spec 19: C-ABI / FFI             ===> JNI bindings to Android Kotlin UI    |
+------------------------------------------------------------------------------------+

Let us examine these cross-cutting connections in technical detail.

9.1 Transport Neutrality & Multipath Routing (Specs 03 & 12)

A common mistake in modern P2P protocols is coupling application logic directly to transport primitives—such as assuming every node has an IP address, relying on libp2p multiaddrs, or hardcoding Iroh Node IDs into chat messages.

Spec 01 strictly enforces Transport Neutrality. Notice the signature of RoutingRequirements declared by an extension operation:

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RoutingRequirements {
    pub delivery_class: DeliveryClass,
    pub max_age_seconds: Option<u64>,
    pub durable: bool,
    pub allow_forwarding: bool,
    pub priority: TrafficPriority,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DeliveryClass {
    Realtime,            // VoIP audio, live typing indicators (Drop if delayed)
    ReliableInteractive,// 1:1 chat text, read receipts (Direct path preferred)
    Durable,            // Group state updates, document sync (Must be acknowledged)
    DelayTolerant,      // Disaster SOS, offline relay bundles (Store-Carry-Forward)
}

Notice what is missing: There are no IP addresses, port numbers, MAC addresses, or QUIC connection handles anywhere in this struct.

When an extension produces an operation, it merely declares its semantic intent: "I need Durable delivery with Interactive priority." It passes this down to Spec 03 (Transport & Routing Policy Engine) and Spec 12 (Multipath Networking).

The routing engine inspects the current physical links:

If a high-speed Iroh QUIC direct connection over Wi-Fi is active, it routes the bytes across QUIC stream multiplexers.
If Wi-Fi drops and only a BLE link is alive, the routing engine automatically re-routes the operation across Bluetooth, fragmenting the frames into MTU-sized chunks without the extension ever realizing the underlying physical medium shifted.
If all physical links drop, the routing engine routes Durable and DelayTolerant operations directly to the local disk outbox for later transmission.

9.2 Delay-Tolerant Networking & Asynchronous Bundles (Specs 04 & 06)

Traditional client-server protocols assume end-to-end synchronous connectivity: Client A connects to Server S, which connects to Client B. If Client B is offline, the message waits on Server S.

In an off-grid disaster mesh, there is no Server S. Alice might be in a valley with no connectivity, while Bob is three kilometers away behind a mountain ridge.

Spec 01 interfaces directly with Spec 04 (Offline Event Log) and Spec 06 (DTN Store-Carry-Forward Architecture):

When Alice sends a message, her local messaging extension generates a standard wire payload.
Because Bob is currently unreachable over real-time transports, the runtime encapsulates the negotiated extension frame into an encrypted DTN Bundle (crates/siar-dtn-bundle).
A mobile emergency vehicle or a pedestrian with a battery-powered headless node walks past Alice. Alice's node opportunistically establishes a short-range Wi-Fi Aware link, completes a Spec 01 handshake, negotiates dtn/1, and offloads the bundle.
Two hours later, the vehicle drives into Bob's physical proximity. The node discovers Bob, executes a Spec 01 handshake, verifies Bob's cryptographic identity, and transfers the bundle.
Bob's node unpacks the DTN bundle, hands the inner frame directly to his local messaging/1 extension handler, and the message appears in his timeline as if they were directly connected.

Spec 01's separation of wire framing from immediate session lifetime makes asynchronous store-carry-forward networking a native capability rather than an afterthought.

9.3 Multi-Device Identity & MLS E2EE Boundaries (Specs 02 & 28)

Under Spec 02 (Multi-Device Identity Architecture) and Spec 28 (End-to-End Encryption & Key Management), identity in SIAR is strictly cryptographic. A user identity (IdentityKey) is an Ed25519 signing key that anchors a dynamic group of individual DeviceIdentity instances (smartphones, laptops, field repeaters).

Spec 01 connects to this identity layer through the ExtensionContext:

pub struct ExtensionContext {
    pub peer_identity: PeerIdentity,     // 32-byte verified public key
    pub session_id: SessionId,           // Ephemeral session entropy
    pub security_level: SecurityPolicy,  // Cleartext, Transport-Encrypted, or E2EE
}

Extensions declare their required security invariants in their ExtensionDescriptor:

pub struct SecurityRequirements {
    pub authenticated_peer: bool,       // Must prove possession of Ed25519 key
    pub e2ee_required: bool,            // Must be encapsulated in MLS payload
    pub authorization_required: bool,   // Must satisfy local contact whitelist
    pub allow_anonymous: bool,          // Permitted for public emergency SOS
}

For standard messaging, e2ee_required is set to true. The core protocol ensures that cleartext message frames cannot be dispatched across unencrypted sessions. Conversely, for emergency/1 broadcast beacons, allow_anonymous is permitted so that unidentified survivors can broadcast distress signals across the mesh to any listening node.

9.4 Headless Daemons & Embedded Linux Repeaters (Specs 16 & 20)

One of the greatest triumphs of Spec 01 is how it enables heterogeneous binary distributions. In the SIAR codebase, Cargo feature flags cleanly decouple crates:

# In siar Cargo workspace
[features]
default = ["messaging", "files", "desktop-ui"]
headless-relay = ["siar-protocol-ext", "siar-dtn", "siar-transport-ble"]

When compiling the Headless Emergency Repeater Daemon (siar-emergency-node) for a 32-bit MIPS or ARM embedded router with 16 megabytes of RAM:

We compile siar-protocol-ext with only dtn and emergency extensions enabled.
The entire Dioxus desktop UI engine, Jetpack Compose Android bindings, Opus audio resampling libraries, AV1 video decoders, and user contact management databases are stripped completely from the compiled binary.
The resulting daemon compiles to a lean 4 MB ELF executable that boots in 120 milliseconds, uses 9 megabytes of RSS RAM, and can run continuously for three weeks on a small 12-volt solar panel and motorcycle battery.

Because Spec 01 uses typed descriptors and clean runtime registries rather than static central enums, the headless repeater participates in the exact same mesh sessions as high-end Android flagships, happily forwarding encrypted DTN packets and routing SOS beacons without missing a beat.

10. Rust Implementation Deep-Dive: A Tour of `siar-protocol-ext`

To appreciate how clean architecture translates into concrete systems code, let us look inside the actual crates/siar-protocol-ext implementation.

10.1 The Extension Descriptor

Every extension self-describes its capabilities, resource limits, and security constraints through an immutable descriptor:

pub struct ExtensionDescriptor {
    pub id: ProtocolId,
    pub requirement: ExtensionRequirement,
    pub supported_capabilities: CapabilitySet,
    pub required_capabilities: CapabilitySet,
    pub limits: ExtensionLimits,
    pub security: SecurityRequirements,
    pub stability: ExtensionStability,
}

Notice the crucial distinction between supported_capabilities (everything this binary knows how to do) and required_capabilities (the baseline subset without which this extension refuses to run). This distinction allows a single protocol version to span multiple hardware tiers.

10.2 The Protocol Extension Trait

The interface between the core runtime multiplexer and an extension is governed by the ProtocolExtension trait:

#[async_trait::async_trait]
pub trait ProtocolExtension: Send + Sync + 'static {
    /// Return the static descriptor for negotiation
    fn descriptor(&self) -> ExtensionDescriptor;

    /// Called when the session establishes and this extension is negotiated
    async fn on_negotiated(
        &self,
        context: &ExtensionContext,
        negotiated_caps: CapabilitySet,
    ) -> Result<Box<dyn ExtensionHandler>, ExtensionError>;
}

#[async_trait::async_trait]
pub trait ExtensionHandler: Send + Sync + 'static {
    /// Handle an incoming validated data frame
    async fn handle_frame(
        &mut self,
        frame_type: u8,
        payload: &[u8],
    ) -> Result<(), ExtensionError>;

    /// Poll for outgoing frames to send across the multiplexer
    async fn poll_outgoing(
        &mut self,
    ) -> Option<OutgoingFrame>;

    /// Lifecycle transition: shutdown signal
    async fn shutdown(&mut self) -> Result<(), ExtensionError>;
}

Notice how ExtensionHandler receives a pre-validated &[u8] slice. It never parses raw wire frame headers, never checks remote length bounds, and never manages TCP or QUIC socket streams. All framing safety, length validation, and multiplexing are handled upstream by the core protocol engine before the handler is invoked.

10.3 The Runtime Builder Pattern

Assembling a node runtime is completely decoupled and declarative:

let runtime = CommunicationRuntime::builder()
    .with_identity(local_device_identity)
    .with_transport(iroh_transport)
    .register_extension(MessagingExtension::new(messaging_config))
    .register_extension(FileTransferExtension::new(file_config))
    .register_extension(EmergencyAlertExtension::new(emergency_config))
    .build()
    .await?;

If you are writing a dedicated CLI backup tool, you simply omit MessagingExtension and EmergencyAlertExtension. The compiler will not include them in the binary, and the node will seamlessly negotiate only file capabilities when pairing with other peers.

11. Verification, Property Testing, and Golden Wire Invariants

Software engineering is what happens when code must survive years of maintenance by dozens of developers across multiple release cycles. How do we guarantee that an optimization in 2027 does not break compatibility with a field node deployed in 2026?

Spec 01 establishes a rigorous three-tiered verification discipline:

+--------------------------------------------------------------------------+
|                  Verification & Testing Architecture                     |
+--------------------------------------------------------------------------+
|  Tier 1: Unit & Matrix Compatibility Tests                               |
|          Verifies that v1.0 ↔ v1.0, v1.0 ↔ v1.2, and subset ↔ superset   |
|          negotiations produce mathematically exact CapabilitySets.       |
|                                                                          |
|  Tier 2: Golden Wire Invariant Tests                                     |
|          Serializes concrete Rust types and compares against raw byte    |
|          arrays byte-for-byte to prevent unintended wire layout shifts.  |
|                                                                          |
|  Tier 3: Hostile Input & Property-Based Fuzzing                          |
|          Injects random bit flips, truncated headers, and hostile        |
|          lengths (0xFFFFFFFF) to mathematically prove panic-freedom.     |
+--------------------------------------------------------------------------+

11.1 Golden Wire Invariant Tests

In crates/siar-protocol-ext/src/framing.rs, we maintain byte-level golden tests. Here is an actual test case verifying header serialization:

#[test]
fn test_golden_frame_header_layout() {
    let header = FrameHeader {
        frame_length: 1024,
        session_extension_id: SessionLocalExtensionId(7),
        frame_type: 0x01,
        flags: 0x80,
    };

    let encoded = encode_frame_header(&header);

    // Exact byte-by-byte layout expectation:
    // [0..4]  Length = 1024 (0x00000400 in big-endian)
    // [4..6]  SessionLocalExtensionId = 7 (0x0007 in big-endian)
    // [6]     FrameType = 1
    // [7]     Flags = 128 (0x80)
    // [8..10] Reserved bytes (0x0000)
    let expected_bytes: [u8; 10] = [
        0x00, 0x00, 0x04, 0x00, // Length
        0x00, 0x07,             // Extension ID
        0x01,                   // Type
        0x80,                   // Flags
        0x00, 0x00,             // Reserved
    ];

    assert_eq!(encoded, expected_bytes);

    // Verify round-trip decode
    let decoded = parse_frame_header(&encoded).expect("Decode must succeed");
    assert_eq!(decoded, header);
}

If an engineer inadvertently changes a field type from u16 to u32, or alters endianness, the golden test immediately fails in CI with an exact diff of the violated byte indices.

11.2 The 16-Item Definition of Done Self-Audit

Spec 01 concludes with an explicit Definition of Done (DoD) checklist containing sixteen rigorous criteria. In crates/siar-protocol-ext/src/definition_of_done.rs, we turned this checklist into a machine-checkable Rust test that audits the crate:

#[test]
fn test_definition_of_done_audit() {
    let audit = audit_part_01_definition_of_done();

    // We enforce that every single DoD item is explicitly accounted for:
    assert_eq!(audit.total_items(), 16);

    // An audit that cannot report honest gaps is useless theater.
    // We assert that the 4 known architectural follow-ups are honestly tracked!
    assert_eq!(audit.satisfied_count(), 12);
    assert_eq!(audit.honest_gaps_count(), 4);
}

By embedding the specification's completion criteria directly into the executable test suite, we ensure that technical debt cannot be swept under the rug.

12. Ten Golden Rules for Distributed Protocol Designers

Drawing from the design and implementation of SIAR Spec 01, here are ten battle-tested rules for systems engineers architecting P2P, local-first, or decentralized protocols:

Kill the Central Message Enum Early: Once your protocol spans more than three distinct features, replace your flat enum Message with independently versioned extension channels. You will save yourself months of refactoring later.
Never Trust Remote Length Fields: Always parse a fixed-size header first, validate the claimed length against both global and subsystem-specific limits, and only then allocate memory buffers.
Represent Capabilities as Mathematical Sets: Do not rely on version numbers to imply feature availability. Use explicit, compact capability IDs and compute $\text{Local} \cap \text{Remote}$ during the handshake.
Enforce Hard Memory Backpressure: Queues must be strictly bounded in both item count and aggregate byte capacity. When full, return the item to the caller to force upstream throttling.
Separate Domain Types from Wire Schemas: Never derive serialization directly on internal business models or database entities. Keep your wire schemas isolated and versioned.
Ban usize on the Wire: Always use explicit, fixed-width integers (u8, u16, u32, u64) with documented big-endian byte order to guarantee interoperability across 32-bit and 64-bit platforms.
Schedule Traffic with Fairness, Not Just Priority: Pure priority queues lead to bulk traffic starvation under sustained load. Implement weighted round-robin scheduling with bounded emergency overrides.
Never Let Optional Extensions Break Sessions: If a peer advertises an unknown optional extension, ignore it cleanly. Forward compatibility is the lifeblood of decentralized systems.
Negotiate Lazily for Mobile Runtimes: Capability agreement must not trigger heavy subsystem initialization. Keep extensions dormant until explicitly opened by user action.
Maintain Byte-Level Golden Tests in CI: Never rely on unit tests alone. Test your serializers against hardcoded byte arrays to catch unintended wire format drift before it hits production.

13. Conclusion & Next Steps in the Series

Decentralized protocol design is often treated as an exercise in cryptography and transport plumbing. But as systems grow, the greatest risks to longevity are not broken ciphers—they are architectural rot, brittle coupling, unbounded memory consumption, and backwards-incompatible wire upgrades.

Spec 01: Protocol Extension System Architecture demonstrates that you do not have to compromise between rapid feature iteration and bulletproof stability. By treating protocol capabilities as independently versioned, set-theoretically negotiated extensions governed by strict backpressure and memory boundaries, SIAR provides a robust foundation for resilient, zero-infrastructure communications.

In Part 2 of this series, we will dive into Spec 02: Multi-Device Identity Architecture, examining how SIAR synchronizes cryptographic state, manages device revocations, and anchors autonomous decentralized trust across phones, laptops, and field repeaters without relying on a central server.

Resources & Further Exploration

🌐 Official SIAR Website — Architecture portals, downloads, and interactive labs.
📚 SIAR Technical Wiki (26 Chapters) — Comprehensive deep-dive into the entire system stack.
📑 System Architecture Specifications (sys-arch) — All 33 core specifications and 27 UI/UX architecture documents.
📦 crates/siar-protocol-ext — Pure-Rust reference implementation of Spec 01.

Have thoughts, critiques, or war stories from your own distributed systems? Drop a comment below or join the discussion on our developer hub!

DEV Community: Irshad Ali

Beyond Single-Key Cryptography: Engineering Decentralized Multi-Device Identity, Sovereign Trust, and Instant Revocation in Rust

[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]

[derive(Debug, Clone, Serialize, Deserialize)]

[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]

[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]

[derive(Debug, Clone, Serialize, Deserialize)]

[derive(Debug, Clone, Serialize, Deserialize)]

[derive(Debug, Clone, Serialize, Deserialize)]

[derive(Debug, Clone, Copy, PartialEq, Eq)]

[derive(Debug, Clone, PartialEq, Eq)]

[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]

[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]

![forbid(unsafe_code)]: Zero unsafe pointer dereferences or memory transmutation anywhere in the codebase.

[derive(Debug, Clone, Copy, PartialEq, Eq)]

[test]

[test]

# Architecting a Zero-Monolith P2P Protocol: How SIAR Solves Versioning, Capabilities, and Backpressure in Rust

Table of Contents

1. Introduction: The Monolithic Protocol Trap

2. The Architectural Axioms of SIAR

3. The Anatomy of Spec 01: Core vs. Extension Separation

3.1 What the Core Protocol Knows

3.2 What the Core Protocol Never Knows

4. Namespaces, Identifiers, and Session-Local Translation

4.1 Hierarchical Global Namespaces

4.2 Ephemeral Session-Local IDs

5. The Mathematics of Capability Negotiation

5.1 Capabilities as Independent Bitsets

5.2 The Two-Phase Negotiation Flow

5.3 Mandatory vs. Optional Extension Semantics

6. Defensive Data Plane: Safe Framing and Zero Memory Exhaustion

6.1 The 4-Step Framing Sequence

6.2 Serialization Discipline: Separation of Wire and Domain Models

7. Flow Control, Backpressure, and Weighted Fair Scheduling

7.1 True Backpressure via Ownership Rejection

7.2 Multi-Tier Traffic Priorities

7.3 Weighted Fair Scheduling with Bounded Emergency Override

8. Lifecycle State Machines, Lazy Opening, and Mobile Energy Discipline

8.1 The Power of Dormant Negotiation

8.2 Graceful vs. Abrupt Shutdown Semantics

9. Cross-Subsystem Integration: Grounding Spec 01 in the Real World

9.1 Transport Neutrality & Multipath Routing (Specs 03 & 12)

9.2 Delay-Tolerant Networking & Asynchronous Bundles (Specs 04 & 06)

9.3 Multi-Device Identity & MLS E2EE Boundaries (Specs 02 & 28)

9.4 Headless Daemons & Embedded Linux Repeaters (Specs 16 & 20)

10. Rust Implementation Deep-Dive: A Tour of siar-protocol-ext

10.1 The Extension Descriptor

10.2 The Protocol Extension Trait

10.3 The Runtime Builder Pattern

11. Verification, Property Testing, and Golden Wire Invariants

11.1 Golden Wire Invariant Tests

11.2 The 16-Item Definition of Done Self-Audit

12. Ten Golden Rules for Distributed Protocol Designers

13. Conclusion & Next Steps in the Series

Resources & Further Exploration

10. Rust Implementation Deep-Dive: A Tour of `siar-protocol-ext`