SIAR — Survivable Identity & Autonomous Routing

Caution

⚠️ FOUNDATIONAL DEVELOPMENT NOTICE — NOT CURRENTLY USABLE ON ANY DEVICE

Active Foundational Development: SIAR is currently in pre-alpha foundational systems development. It is NOT YET USABLE on any daily-driver mobile phone, desktop, or operational device. End-user applications and installable packages will become operational upon the completion of the first formal milestone release (Milestone 1 / v0.1.0+).
AI / LLM Development Transparency Disclosure: SIAR's extensive architectural specifications (176 specifications across 514k+ lines), wiki documentation, and codebase are heavily developed with the assistance of advanced Artificial Intelligence / Large Language Models (AI/LLMs) working under human architectural direction and verification.
URGENT: Security Researchers, Cryptographers & Protocol Engineers Required: Because SIAR is designed for post-infrastructure, disaster-recovery, and high-threat environments, independent third-party security researchers and protocol engineers are urgently needed to perform formal mathematical verification, cryptographic audits, memory safety inspections, and fuzz testing across the cryptography (siar-crypto, siar-crypto-mls), wire framing (siar-protocol, siar-protocol-ext), transport/routing (siar-transport, siar-routing-policy), storage, and media subsystems to discover and eliminate potential vulnerabilities before real-world deployment.

DO NOT deploy SIAR in production, life-safety, high-threat, or operational environments until formal independent audits and the v0.1.0 milestone release are complete.

🏛️ Organization Stewardship & Research Initiative:
SIAR is an open-source systems initiative developed and stewarded under Irshad Lab (@irshadlab) — focused on local-first computing, resilient peer-to-peer networking, and sovereign systems engineering.

Official Showcase, Package Center & Live Architecture Documentation:

🌐 Official Product Presentation

🖼️ Desktop UI Reference Gallery — Dark/Light themes, Contact Verification, MLS Groups & Settings

📚 Comprehensive Technical Wiki (50 Chapters) — System Stack, Multi-Device Trust, Routing, DTN, Security Center, Calls, Testing & Operations

📘 End-to-End User & Operations Manual — Zero-Knowledge Setup, QR/NFC Pairing, Vault Export/Import & Anti-Forensics

📑 System Architecture & Protocol Specs (mdBook) — 33+ numbered core specs + 27 UI/UX specs

📦 Universal Package Center — .deb, .rpm, .apk, .dmg, brew, winget

🔬 Interactive WASM Mesh Simulator Lab

🛡️ SLSA Level 3+ Supply Chain Cryptographic Verifier

What SIAR Is
Core Design Rules
Specification Governance: sys-arch for Core, ui-ux for UI
Architecture: Five Layers
Transport & Routing Policy Engine
Multi-Device Identity & Trust
End-to-End Security Model
DTN: Store-Carry-Forward
Realtime Calls & Media
Headless Daemon & Embedded Nodes
Protocol Extensions & WASM
Anonymity Transport Plane
Workspace Crate Map (41 Domain Crates)
Deployment Modes
SIAR vs Traditional Messengers
Implementation Status & Roadmap
Prerequisites & Environment Setup
Build & Compilation Tutorial
Node Configuration & User Guide
Testing & Fuzzing
License & Dual-Tier Model

What SIAR Is

SIAR ( Survivable Identity & Autonomous Routing ) is a reusable, zero-infrastructure, multi-transport, offline-first P2P communication platform.

Traditional messengers (WhatsApp, Signal, Telegram) assume always-on infrastructure: centralized server clusters, public DNS, PKI, and continuous Internet access. When natural disasters strike, telecommunications infrastructure collapses, or state-level censorship severs external backhauls, these apps completely fail.

SIAR is engineered from first principles to invert these assumptions:

Zero-Infrastructure Invariant — the system must operate seamlessly when zero external servers, DNS nodes, or Internet gateways are reachable.
Cryptographic Sovereignty — identities are root Ed25519 signing pairs owned exclusively by local devices — no phone numbers, email addresses, or centralized registries.
Opportunistic Dissemination — messages and files are delay-tolerant bundles that travel over any available medium (BLE, Wi-Fi Direct, Wi-Fi Aware, Bluetooth Classic, LAN, Internet QUIC) through store-carry-forward physical mules.
Unified Cross-Platform Core — a high-performance, memory-safe pure-Rust workspace powers CLI daemons, solar-powered mesh repeaters, Android apps, and desktop interfaces.
Reusable Platform — the underlying architecture is not messenger-specific. The same crates back messaging, files, emergency SOS, group comms, ERP payloads, and future custom applications.

The governing rule from sys-arch/:

The application expresses intent and constraints. The platform selects paths, manages retries, falls back to DTN, and re-establishes sessions — without the application understanding transport mechanics.

Core Design Rules

These rules appear directly in the sys-arch specifications and govern every crate in the workspace:

Rule	Specification Source
Feature code must never implement transport selection	`sys-arch/03` §2
The daemon owns durable state; UI is a client of the runtime	`sys-arch/16` §1
Transport security protects the path; application E2EE protects the conversation regardless of path	`sys-arch/28` §1
A person is an account, not a device — routing must address accounts, not device keys	`sys-arch/02` §2
DTN is not Bluetooth forwarding logic or emergency-only forwarding — it is a transport-neutral persistence layer	`sys-arch/06` §2
Protocol extensions are a versioned capability architecture, not a dynamic plugin system for arbitrary untrusted code	`sys-arch/01` §2
SIAR must treat anonymity as an explicit routing/security property, not a side effect of encryption	`sys-arch/34` §1
The call is a logical secure session; network paths, codecs, devices, and surfaces are replaceable implementation resources inside that session	`sys-arch/29` §1

Specification Governance: sys-arch for Core, ui-ux for UI

All engineering and implementation in SIAR strictly follows a dual-specification authority model:

┌──────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                   SIAR SPECIFICATION GOVERNANCE ARCHITECTURE                            │
├────────────────────────────────────────────────────┬─────────────────────────────────────────────────────┤
│ 📐 Core Engine, Protocols & Daemons: sys-arch/     │ 🎨 Frontends, UI/UX & State Machines: ui-ux/        │
├────────────────────────────────────────────────────┼─────────────────────────────────────────────────────┤
│ • Authority Corpus: sys-arch/ (176 Specifications) │ • Authority Corpus: ui-ux/ (27 Specifications)      │
│   - Parts 01–33: Core Mesh, Local-First Engine,    │   - ui-ux-01..03: App Shells & Platform Navigation  │
│     DTN, Multi-Transport, Security & Codecs        │   - ui-ux-04..06: Timelines, Composer & Attachments │
│   - Parts 34–150: Anonymous Mixnet, Private        │   - ui-ux-07..10: Realtime Calls, Groups & Files    │
│     Mailboxes, Cloud Ecosystem & Resilient Ops     │   - ui-ux-11..17: Security Center, SOS & Pairing    │
│                                                    │   - ui-ux-18..27: Tokens, Motion, A11y & Gates      │
│ • Target Codebases:                                │ • Target Codebases:                                 │
│   - Pure-Rust domain crates: crates/siar-* (41)    │   - apps/desktop (Slint 1.16 Native Desktop GUI)     │
│   - apps/emergency-node (Headless Solar Daemon)    │   - apps/android (Jetpack Compose + JNI UI layer)   │
│   - apps/cli (Interactive Terminal & Diagnostics)  │   - crates/siar-ui-state / siar-ui-slint            │
│ • Core Invariants:                                 │ • UI Invariants:                                    │
│   - Zero external infrastructure dependency        │   - UI is strictly a decoupled client of runtime    │
│   - Feature code never implements transport choice │   - UI never owns durable transport or crypto state │
│   - Pure Rust, memory-safe, panic-free paths       │   - Reactive state machines isolate UI from events  │
└────────────────────────────────────────────────────┴─────────────────────────────────────────────────────┘

1. Core Development Follows `sys-arch/`

All backend runtime engines, protocol framing, cryptographic handshakes, transport drivers, and storage subsystems must strictly follow the sys-arch/ specification corpus:

Wire Protocols & Handshakes: Binary wire framing, extension negotiation, and capability schemas follow sys-arch/01 and sys-arch/07.
Identity & Cryptography: Root Ed25519 account sovereignty, device certificates, OpenMLS trees, and SAS out-of-band verification follow sys-arch/02 and sys-arch/28.
Transport & Multi-Metric Routing: Candidate discovery, link-state scoring, adaptive transport selection, and battery-aware scheduling follow sys-arch/03 and sys-arch/13.
DTN & Emergency Survivability: Delay-tolerant bundle store-carry-forward and life-safety priority queues follow sys-arch/06 and sys-arch/17.
Daemon Lifecycle & Headless Services: Headless unattended operation, crash recovery, and WAL replay follow sys-arch/09, sys-arch/16, and sys-arch/20.

2. User Interface Development Follows `ui-ux/`

All user-facing graphical applications, mobile experiences, layout systems, visual states, and reactive UI state machines must strictly follow the ui-ux/ specification corpus:

Application Shells & Navigation: Multi-pane desktop navigation, mobile tab bars, window state restoration, and back-stack handling follow ui-ux-01, ui-ux-02 (implemented natively in Slint via siar-ui-slint), and ui-ux-03.
Conversations & Message Timeline: Message bubbles, delivery checkmarks (Pending, DTN Relayed, Delivered, Read), media carousels, and composer attachments follow ui-ux-04, ui-ux-05, and ui-ux-06.
Security Center & Trust Flows: Cryptographic identity management, key rotation warnings, device revocation ceremonies, recovery phrase verification, and SAS visual comparisons follow ui-ux-15.
Emergency SOS & Offline Degraded States: High-contrast offline mesh indicators, zero-connection SOS banners, transport fallback indicators, and battery-saver modes follow ui-ux-17 and ui-ux-24.
Design Tokens, Typography & Inclusive Access: Color tokens, typography scales, touch targets, screen reader semantic labels, and motion curves follow ui-ux-21 and ui-ux-22.

3. Core-to-UI Separation Invariant

In accordance with sys-arch/16 and ui-ux-01:

The Daemon Owns State: The pure-Rust core runtime manages durable database storage, active network sockets, cryptographic ratchet states, and routing decisions.
The UI is a Stateless Client: Frontend applications (apps/desktop, apps/android) observe reactive state streams exposed by siar-ui-state and emit user intent commands.
No Direct Socket or Crypto Manipulation in UI: UI code must never open raw network sockets, attempt ad-hoc cryptographic operations, or implement private transport failover logic.

Architecture: Five Layers

SIAR is structured into five distinct, decoupled architectural layers:

+---------------------------------------------------------------------------------------+
|                                5. Applications & UI/UX                                |
|  - apps/android (Jetpack Compose + JNI)   - apps/desktop (Slint 1.16 Native GUI)      |
|  - apps/emergency-node (Solar Repeater)   - apps/cli (Dev Diagnostics & CLI Node)     |
+---------------------------------------------------------------------------------------+
|                                4. High-Level Services                                 |
|  - siar-messaging (Message & Group Engine)- siar-calls (Realtime AV1 / Opus Sessions) |
|  - siar-identity-multidevice (Certs, SAS) - siar-ui-state / siar-ui-slint (UI Views)  |
|  - siar-files (Blob Transfer Service)     - siar-dtn-bundle-service (DTN Sync)        |
+---------------------------------------------------------------------------------------+
|                            3. Routing, Policy & DTN Engine                            |
|  - siar-routing-policy (Multi-Metric)     - siar-dtn-bundle (Spray-and-Wait Forward)  |
|  - siar-connectivity (Link State Probes)  - siar-emergency (Priority Classes P0–P3)   |
+---------------------------------------------------------------------------------------+
|                             2. Storage, Crypto & Reliability                          |
|  - siar-crypto (Ed25519/X25519 AEAD)      - siar-crypto-mls (RFC 9420 MLS E2EE)       |
|  - siar-storage (Stoolap Embedded SQL)    - siar-blob-manifest (BLAKE3 Merkle DAG)    |
|  - siar-resource-limits (Backpressure)    - siar-crash-recovery (WAL & Checkpoints)   |
|  - siar-event-log (Monotonic Sequence Log)                                            |
+---------------------------------------------------------------------------------------+
|                              1. Transport & Wire Protocols                            |
|  - siar-protocol (Postcard Wire Codec)    - siar-protocol-ext (CapNeg & Scheduler)    |
|  - siar-capability (2-Phase Confirmation) - siar-transport (Pooled Connection Socket) |
|  - siar-transport-ble / -ble-android      - siar-transport-bluetooth-classic (RFCOMM) |
|  - siar-transport-wifi-direct (P2P)       - siar-transport-wifi-aware (NAN Proximity) |
+---------------------------------------------------------------------------------------+

Transport & Routing Policy Engine

Specification: sys-arch/03 · Crate: siar-routing-policy

The platform supports all of the following physical paths simultaneously:

Iroh QUIC (direct / relay)   Wi-Fi Direct (P2P)
Local LAN (multicast)        Wi-Fi Aware (NAN)
Bluetooth Classic (RFCOMM)   Bluetooth LE (GATT)
DTN / store-carry-forward    future transports

Rather than letting application code pick a transport, each operation publishes DeliveryRequirements (priority class, deadline, bandwidth floor, metered/roaming policy, relay allowance, DTN opt-in). The routing policy engine:

Resolves candidate paths for the destination account across all of its devices.
Scores each candidate with a multi-metric weighted formula (RTT, bandwidth, setup cost, stability, energy cost, congestion, candidate state).
Applies hard constraint elimination (metered, roaming, background restriction, scope, revoked device, deadline).
Applies layered policy checks (system → application → user → operation → network context).
Returns a RoutePlan (Direct / Redundant / Hedged / Dtn) with per-device routing for multi-device accounts.

Policy profiles include: RealTime, Interactive, Bulk, Background, Emergency, LowPower, OffGrid. The engine also enforces stickiness hysteresis to prevent oscillation under measurement jitter.

SIAR automatically shifts between three operational modes:

Mode	Available Networks	Delivery Mechanism
Connected Online	Internet / LAN / Wi-Fi	Iroh QUIC, direct end-to-end streams
Local Tactical Mesh	Wi-Fi Direct, Wi-Fi Aware, LAN	Hop-by-hop mesh forwarding (sub-10 ms)
Air-Gapped / Off-Grid	BLE GATT, Bluetooth Classic	Physical mule DTN with Spray-and-Wait

Multi-Device Identity & Trust

Specification: sys-arch/02 · Crate: siar-identity-multidevice

A person is not a device. SIAR distinguishes five identity layers:

Account Identity  →  Device Identity  →  Transport Identity  →  Session Identity  →  Application Profile

Each device generates an independent Ed25519 key pair and obtains a DeviceCertificate signed by the account's root authority. The trust model supports:

Multiple active devices (phone, laptop, headless node, secondary phone)
Independent per-device keys with device-specific transport addresses
Monotonic revocation — a revoked device cannot forge retroactive authority
SAS (Short Authentication String) out-of-band verification for secure linking (QR code, NFC, or verbal code)
Per-device capability sets — a headless relay does not advertise REALTIME_MEDIA
Account recovery with encrypted key backups and import validation before any local state is touched
Algorithm agility — signature and KEM schemes are replaceable without breaking the identity model
Organization/enterprise namespaces with multi-tenant composite keys

The identity layer is designed to remain reusable outside the messenger — the same model backs messaging, files, emergency SOS, ERP, and any future application built on this platform.

End-to-End Security Model

Specification: sys-arch/28 · Crates: siar-crypto, siar-crypto-mls

Application E2EE (MLS RFC 9420)
      ↓
Conversation / Group Security (OpenMLS tree ratchet)
      ↓
Authenticated Device Sessions (Ed25519 + X25519)
      ↓
Iroh / QUIC Transport Security
      ↓
Internet / LAN / BLE / Relay / DTN

Threat model: any relay server, DTN carrier, public network, nearby Bluetooth peer, server database, third-party plugin, external FFI caller, stolen device, or old backup can be hostile or compromised. The design trusts only: the current unlocked local device, explicitly authorized devices, verified contacts, and explicit organization/authority keys.

Required security properties:

End-to-end confidentiality — ciphertext is unreadable by relays, carriers, or infrastructure operators
Forward secrecy — compromise of today's keys does not expose past messages (MLS epoch ratchet)
Post-compromise security — after a device is removed, new group state remains confidential from it
Offline / DTN-safe encryption — messages encrypted for delivery remain sealed while carried by DTN mules
Metadata minimization — routing decisions carry no content; RouteMetricEvent has no peer-identity or IP fields by construction

DTN: Store-Carry-Forward

Specification: sys-arch/06 · Crate: siar-dtn-bundle

DTN (Delay-Tolerant Networking) enables communication without a continuous end-to-end path:

Alice (no Internet, no Wi-Fi, no direct Bluetooth to destination)
  ↓
Bob (physical mule — encounters Alice via BLE)
  ↓
Carol (physical mule — encounters Bob via Wi-Fi Direct)
  ↓
Gateway (encounters Carol, has Internet)
  ↓
Destination

The DTN subsystem persists payloads locally, carries them across time, and forwards them when useful connectivity appears. It is transport-neutral and supports:

Text messages, delivery receipts, emergency SOS, authority alerts
Small file metadata and selected file chunks
Custom application events for ERP and third-party integrations

Spray-and-Wait replication (configurable dtn_replication_budget) limits network flooding while maximising delivery probability. Bundle custody receipts confirm when a mule has accepted responsibility for forwarding. The routing policy engine integrates DTN as a first-class RouteStrategy::Dtn outcome — fallback to DTN is a policy decision, not a last-resort hack.

Realtime Calls & Media

Specification: sys-arch/29 · Crates: siar-calls, siar-media-android, siar-media-audio, siar-media-av1

A call is a logical secure session; network paths, codecs, devices, and display surfaces are replaceable resources inside that session:

Call Controller
    ├── Signaling   (ringing / accept / reject / busy / timeout)
    ├── Security    (session authentication bound to E2EE identity)
    └── Policy      (codec selection, bitrate, hold/resume, path handoff)
         ├── siar-media-android  (Android MediaCodec zero-copy hardware surfaces)
         ├── siar-media-av1      (desktop dav1d AV1 software decoder)
         └── siar-media-audio    (Opus + AEC / NS / AGC DSP pipeline)

The call architecture supports:

P2P signaling without a signaling server — session control messages travel over the same Iroh/mesh transport as regular messages
Multipath resilience — the session survives a path change; the routing engine's RouteChangeEvent::NewPath triggers codec renegotiation, not call termination
Hardware zero-copy surfaces on Android — MediaCodec decodes directly into SurfaceTexture without intermediate copy
Pure-Rust DSP on desktop — Opus encode/decode, acoustic echo cancellation (AEC), noise suppression (NS), automatic gain control (AGC)
Crash-safe call history — call records are written to durable storage before the session is confirmed torn down

Headless Daemon & Embedded Nodes

Specification: sys-arch/16 · App: apps/emergency-node

The platform does not require the user interface to remain alive for core networking to function:

Slint Desktop UI   ──Secure Local IPC / Direct Core Wiring──▶  comm-daemon / runtime
                                                                  ├── Identity
                                                                  ├── Messaging
                                                                  ├── Files & DTN
                                                                  ├── Routing & Multipath
                                                                  ├── Power policy
                                                                  └── Recovery
                                                                          │
                                                                 Iroh / LAN / BLE / Wi-Fi

apps/emergency-node is a standalone headless daemon deployable on:

Raspberry Pi, OpenWrt routers, embedded Linux single-board computers
Solar-powered field nodes and dedicated mobile repeater boosters
Linux servers for self-hosted relay infrastructure

In headless mode, the daemon autonomously stores, carries, and re-transmits encrypted bundles across disconnected network partitions — functioning as a mesh repeater during complete Internet blackouts and disaster scenarios, without any UI requirement.

Self-hosted relay infrastructure (sys-arch/11) allows organizations to deploy private relay fleets, regional relay clusters, and DTN gateway bridges without lock-in to any centralized service.

Protocol Extensions & WASM

Specifications: sys-arch/01, sys-arch/22 · Crates: siar-protocol-ext, siar-capability

Instead of a single monolithic protocol enum, SIAR uses a versioned capability architecture:

Communication Session
    │
    ├── Core Control Protocol (always present)
    │
    └── Extension Negotiation (per-peer capability set)
          ├── messaging/1
          ├── files/1
          ├── dtn/1
          ├── emergency/1
          ├── calls/1
          └── custom-app/1  (third-party or ERP extensions)

Two-phase capability confirmation (NegotiationHash + HandshakeNonce) ensures peers agree on extension support before sending extension frames. FairScheduler and BoundedQueue in siar-protocol-ext enforce weighted-fair scheduling and backpressure across all extensions — a slow file transfer cannot starve an emergency SOS.

WASM-compatible components (sys-arch/22) enable portable execution of selected logic (custom protocol handlers, routing filters, ERP integrations) across desktop, server, embedded Linux, and browser-compatible environments — while the native Rust core retains ownership of networking, hardware codecs, secure key stores, and daemon lifecycle.

Anonymity Transport Plane

Specification: sys-arch/34

SIAR's existing transports optimize for reachability, latency, bandwidth, reliability, and offline operation. They do not, by themselves, provide strong resistance against network metadata analysis — a network observer can still infer communication relationships from timing and volume, even when message contents are E2EE-protected.

Part 34 introduces an independent High-Anonymity Transport Plane based on mix-network principles (Loopix/Sphinx/Nym):

Sphinx packet encapsulation — layered onion routing with per-hop key agreement
Randomized delays and cover traffic — timing analysis resistance
Anonymous mailboxes — offline reception and unlinkable reply capability
Strict downgrade prevention — explicit anonymity policy, not a best-effort side effect

The anonymity plane is an additive routing class integrated with SIAR's existing policy engine — it does not replace or weaken direct, mesh, DTN, or realtime transport.

Workspace Crate Map (41 Domain Crates)

SIAR is a modular Rust cargo workspace comprising 41 domain crates, 4 application environments, 2 Android JNI runtime bridges, and fuzz testing targets:

siar/
├── apps/
│   ├── android/                          # Android Native App & JNI Bridges
│   │   ├── app/                          # Jetpack Compose UI (Chat, Groups, Settings, Radar)
│   │   ├── messaging-jni/                # Rust JNI cdylib surface (siar-android-messaging)
│   │   ├── rust-jni-glue/                # Shared JNI glue, memory safety, and JVM callbacks
│   │   └── build-native.sh               # Multi-ABI cargo-ndk build automation script
│   ├── cli/                              # Interactive Terminal Messenger & Diagnostics Node
│   ├── desktop/                          # Native Desktop GUI (Slint 1.16 Shell & Core Wiring)
│   └── emergency-node/                   # Headless Emergency DTN Relay & Booster Daemon
├── crates/
│   ├── [Core Domain, Identity & Trust]
│   │   ├── siar-domain/                  # Core entities: AccountId, DeviceId, Ticket, SafetyFingerprint
│   │   ├── siar-crypto/                  # Ed25519, X25519, ChaCha20-Poly1305, zeroize primitives
│   │   ├── siar-crypto-mls/              # IETF MLS (RFC 9420) Tree-KEM 1:1 and group E2EE engine
│   │   ├── siar-identity-multidevice/    # Multi-device authority, device certs, trust store, SAS pairing
│   │   └── siar-identity-audit-recorder/ # Monotonic append-only audit trail for identity lifecycle & revocations
│   ├── [Protocols, Capability & Extension Engine]
│   │   ├── siar-protocol/                # Wire envelopes, Postcard binary codec, frame types
│   │   ├── siar-protocol-ext/            # Extensible protocol engine: FairScheduler, BoundedQueue, health
│   │   └── siar-capability/              # Two-phase capability negotiation & codec matrices
│   ├── [Mesh Routing, Policy & Dynamic Connectivity]
│   │   ├── siar-routing-policy/          # Multi-metric candidate scoring, hysteresis, decide_route
│   │   └── siar-connectivity/            # Cross-transport state engine, connection pooling & link probes
│   ├── [Multi-Transport Physical Sockets]
│   │   ├── siar-transport/               # Transport manager, pooled socket multiplexer & lifecycle
│   │   ├── siar-transport-ble/           # Linux/cross-platform Bluetooth Low Energy (L2CAP CoC) driver
│   │   ├── siar-transport-ble-android/   # Android native Bluetooth Low Energy transport driver
│   │   ├── siar-transport-bluetooth-classic/ # High-throughput RFCOMM Bluetooth Classic transport
│   │   ├── siar-transport-wifi-direct/   # High-bandwidth Wi-Fi Direct P2P ad-hoc transport
│   │   └── siar-transport-wifi-aware/    # Wi-Fi Aware (NAN — Neighbor Awareness Networking) transport
│   ├── [DTN, Emergency Priority & Life-Safety Services]
│   │   ├── siar-dtn-bundle/              # Bundle framing, custody receipts & Spray-and-Wait forwarding
│   │   ├── siar-dtn-bundle-service/      # Background daemon service orchestrating DTN bundle sync
│   │   ├── siar-emergency/               # 5-tier priority class queuing (P0 Life-Safety to P4 Bulk)
│   │   └── siar-emergency-service/       # Autonomous SOS beacon broadcaster & triage packet engine
│   ├── [Storage, Blobs, Event Logging & Reliability]
│   │   ├── siar-storage/                 # Pure-Rust Stoolap embedded relational SQL (Messages, Outbox)
│   │   ├── siar-event-log/               # Monotonic append-only event log & causal gap detection
│   │   ├── siar-event-notify/            # Internal reactive pub-sub event notification dispatcher
│   │   ├── siar-event-registry/          # Global schema registry of system events and audit subscribers
│   │   ├── siar-blob-manifest/           # SIMD BLAKE3 Merkle DAG blob chunking & AEAD encryption
│   │   ├── siar-file-transfer-service/   # Peer-assisted swarm blob chunk distribution coordinator
│   │   ├── siar-files/                   # High-level file transfer service, chunked AEAD v2, stream-to-many
│   │   ├── siar-resource-limits/         # Token-bucket backpressure, ring buffers & queue drop policies
│   │   ├── siar-crash-recovery/          # WAL recovery, transactional checkpoints & corrupt state isolation
│   │   ├── siar-startup-recovery/        # Cold-boot consistency verification & orphaned ticket repair
│   │   └── siar-remote-ingestion/        # Ingestion gateway for external telemetry and bridge adapters
│   ├── [Messaging Orchestration & UI State Machines]
│   │   ├── siar-messaging/               # MessageService, GroupService, Ticket manager, multi-node tests
│   │   ├── siar-ui-state/                # Framework-agnostic UI state machines & Security Center
│   │   └── siar-ui-slint/                # Slint 1.16 UI component library, semantic Theme tokens & shell
│   ├── [Realtime Media, Voice/Video & Hardware Codecs]
│   │   ├── siar-media-core/              # Media traits, raw video/audio buffers, sample clocks
│   │   ├── siar-media-audio/             # Pure-Rust lock-free audio DSP (Opus, AEC, NS, AGC, <10ms latency)
│   │   ├── siar-media-av1/               # Desktop dav1d AV1 video decoder with lookahead decoding
│   │   ├── siar-media-android/           # Android MediaCodec hardware surface zero-copy pipeline
│   │   ├── siar-media-image/             # Image processing, format transcoding & responsive thumbnails
│   │   └── siar-calls/                   # Realtime P2P media call session protocols & signaling
│   └── [Simulation & Test Harness]
│       └── siar-testkit/                 # In-memory virtual radio mesh simulator & link impairments
├── platform/
│   └── android/                          # Android native platform bindings & permission harnesses
└── fuzz/                                 # Cargo Fuzz targets (frame & blob decoders)

Deployment Modes

SIAR deploys in three distinct forms:

1. Standalone User Applications

App	Platform	UI Framework
`apps/android`	Android (minSdk 26)	Jetpack Compose + JNI bridge to Rust core
`apps/desktop`	Linux, Windows	Slint 1.16 Native Desktop GUI (`crates/siar-ui-slint`)
`apps/cli`	Any POSIX	Interactive terminal — identity, tickets, DTN

2. Headless Off-Grid Repeater Daemon

apps/emergency-node runs headless on any Linux device:

Raspberry Pi, OpenWrt routers, solar-powered field nodes
Autonomous store-carry-forward DTN mesh repeater
No GUI required; daemon owns all networking and storage state

3. Embedded / Self-Hosted Relay Infrastructure

The headless runtime (sys-arch/16) and relay architecture (sys-arch/11) support:

Organization-private relay fleets and regional clusters
DTN gateway bridges between Internet and off-grid mesh segments
Multi-cloud / bare-metal deployment with no product-level relay lock-in

SIAR vs Traditional Messengers

Feature	SIAR	Signal / WhatsApp / Telegram
Server Requirement	None — fully autonomous P2P / mesh	Mandatory central cloud servers
Offline / Disaster Operation	Native — BLE, Wi-Fi Direct/Aware, DTN	Unusable without Internet
Addressing & Identity	Self-sovereign Peer Tickets / Ed25519 root keys	Phone numbers / cloud user IDs
Transport Layer	Multi-transport adaptive path routing (8+ physical paths)	HTTPS / WebSockets / TCP
Group Security	OpenMLS (RFC 9420) forward secrecy + post-compromise	Custom Signal Protocol / server-managed
Hardware Codec Acceleration	Native Android `MediaCodec` + pure-Rust DSP	WebRTC / platform C-libs
Anonymity	Mixnet / Sphinx transport plane (Part 34)	None / VPN-dependent
Self-Hosted Relay	Full support — no lock-in	Not supported
Extensibility	Versioned protocol extensions + WASM sandbox	Closed monolithic protocol

Implementation Status & Roadmap

SIAR maintains an honest, compile-and-test-verified implementation tracking matrix per ROADMAP.md. All coverage figures are from the sys-arch/ specification corpus (33 numbered core-architecture docs + 27 ui-ux-NN UI specs).

┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│                              SIAR IMPLEMENTATION MATURITY OVERVIEW                               │
│                              (as of 2026-10-24 · rustc 1.91 verified)                           │
├───────────────────────────────┬──────────────────────────────┬──────────────────────────────────┤
│ Architectural Layer           │ Spec Coverage                │ Verified State                   │
├───────────────────────────────┼──────────────────────────────┼──────────────────────────────────┤
│ Tier 0 — Foundational Core    │                              │                                  │
│                               │                              │                                  │
│  01 · siar-protocol-ext       │ ✅ 108/108 — SPEC COMPLETE   │ FairScheduler, BoundedQueue,     │
│                               │   115 tests, 0 warnings      │ extension health & DoD self-audit│
│  02 · siar-identity-multidevice│ ✅ 204/204 — SPEC COMPLETE  │ Root authority, DeviceCert,      │
│                               │   251 tests, 0 warnings      │ TrustStore, algorithm agility,   │
│                               │                              │ SAS pairing, identity lifecycle  │
│  03 · siar-routing-policy     │ ✅ 200/200 — SPEC COMPLETE   │ Multi-metric scoring, RoutePlan, │
│                               │   263 tests, 0 warnings      │ hysteresis, decide_route,        │
│                               │                              │ multidevice routing, 19 rounds   │
│  04 · siar-event-log          │ ✅ Substantially Complete    │ Monotonic sequence log, outbox,  │
│                               │   Phases 1–8 complete        │ reassembly, HLC, search, audit   │
│  05 · siar-blob-manifest      │ 🟡 Round 27 Complete         │ BLAKE3 Merkle DAG, siar-files    │
│       & siar-files            │   693 tests, 0 warnings      │ chunked AEAD v2, stream-to-many, │
│                               │                              │ QUIC files/1, pull-by-reference  │
│  06 · siar-dtn-bundle         │ 🟡 ~83/192 (~43%)            │ Spray-and-Wait, bundle framing,  │
│                               │   119 tests, Round 5         │ store-carry-forward forwarding   │
│  07 · siar-capability         │ 🟡 ~113/164 (~69%)           │ 2-phase capability negotiation,  │
│                               │   122 tests, Round N+3       │ hierarchical negotiation, UI     │
│  08 · siar-resource-limits    │ ✅ ~192/193 — SPEC COMPLETE  │ Token-bucket backpressure, DoD   │
│                               │   434 tests, 0 warnings      │ passed, ResourceRuntime facade   │
│  09 · siar-crash-recovery     │ ✅ 186/186 — SPEC COMPLETE   │ WAL recovery, isolation, DoD     │
│                               │   498 tests, 0 warnings      │ passed, executable audit clean   │
├───────────────────────────────┼──────────────────────────────┼──────────────────────────────────┤
│ Tier 1 — Security Backbone    │                              │                                  │
│  28 · siar-crypto / mls       │ 🟡 ~46/127 (~36%)            │ Ed25519/X25519, MLS E2EE,        │
│                               │                              │ replay protection, revocation    │
├───────────────────────────────┼──────────────────────────────┼──────────────────────────────────┤
│ Tier 2 — UI/UX (27 specs)     │                              │                                  │
│  ui-ux-15 · Security Center   │ 🟡 ~183/221 (~83%)           │ RecoveryScope, RevocationCaps,   │
│                               │                              │ CompromiseResponse, contact SAS  │
│  ui-ux-01..14, 16..27         │ 🟡 Slint Desktop Transition  │ Desktop migrated Dioxus → Slint  │
│                               │   (2026-10-22)               │ (crates/siar-ui-slint): Theme    │
│                               │                              │ tokens, persistent history & MLS │
├───────────────────────────────┼──────────────────────────────┼──────────────────────────────────┤
│ Multi-Transport Layer         │ ✅ Production Hardened        │ Pooled stream multiplexer,       │
│                               │                              │ files/1 over QUIC, multi-node e2e│
└───────────────────────────────┴──────────────────────────────┴──────────────────────────────────┘

Tier 0 progress — 6 of 9 foundational core specs are spec-complete or substantially complete (01, 02, 03, 04, 08, 09). Specs 05, 06, and 07 are in active, verified development (siar-files has completed 27 rounds with 693 passing tests; siar-dtn-bundle has 119 tests; siar-capability has 122 tests). See ROADMAP.md for section-by-section coverage notes and the next-priority ordering.

Quality discipline applied to every spec round:

Compile + test + cargo clippy -D warnings + cargo fmt + doc-warning-free — verified clean before a round is marked done
Over 1,700+ passing tests across workspace crates
Zero regressions in any dependent crate at any point across all rounds of spec work
Real bugs caught by tests (not review): pooled-connection reuse silently dropping messages after the first; expired operation never enforced at routing-decision level; DTN file_chunk() constructor contradicting its own spec example; stickiness test using a stale pre-mutation health snapshot; Stoolap top-N memory overflow in GC paging; self-deadlock on transfer cancellation

Resolved reconciliation questions (see MIGRATION.md for full disposition):

Device certificate reconciliation: Retired plan.md-era siar_crypto::device_cert and siar_domain::device::{DeviceRegistry, DeviceEvent} in favor of root-key-signed siar-identity-multidevice with additive TransportKeyBinding.
Routing reconciliation: Retired siar-routing into siar-routing-policy (link health, relay composition, congestion tracker) and siar-connectivity (CandidateTable, DeviceRoutes).
DTN reconciliation: Retired siar-dtn into siar-dtn-bundle (seen-bundle dedup, async BundleStore, opaque RouteToken) and local quota-bounded storage in apps/emergency-node.

Prerequisites & Environment Setup

1. Nix Development Environment (Recommended)

SIAR provides a universal, cross-distribution Nix installer (install-nix.sh) that automates Nix setup across any Linux distribution (Arch, Ubuntu, Debian, Fedora, RHEL, openSUSE, Alpine, Void, etc.) and macOS:

# Automated cross-distribution Nix installer
./install-nix.sh

# Or remotely via curl:
curl --proto '=https' --tlsv1.2 -sSfL \
  https://raw.githubusercontent.com/irshadlab/siar/develop/scripts/install-nix.sh | bash

See the full Nix Installation & Configuration Guide for distro-specific options, diagnostics (--doctor), and uninstallation (--uninstall).

Once installed, the hermetic Nix Flake (flake.nix, shell.nix) provides Rust 1.91, GTK3, WebKit2GTK, ALSA, OpenSSL, CMake, libxdo, and Darwin SDK frameworks automatically:

# Enter the fully provisioned hermetic development shell
nix develop

# Build workspace binaries directly with Nix
nix build .#siar-cli
nix build .#siar-desktop
nix build .#siar-emergency-node

# Run Nix checks and flake validation
nix flake check

If you use direnv:

direnv allow

2. Manual Rust & Platform Setup

Rust — 1.91.0 or newer:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add x86_64-unknown-linux-gnu aarch64-linux-android \
  armv7-linux-androideabi i686-linux-android x86_64-linux-android

Android Development (for apps/android):
- Android SDK API Level 34+, NDK r25b or newer
- cargo install cargo-ndk
- Set ANDROID_HOME and ANDROID_NDK_HOME environment variables

System dependencies (Linux GUI):

sudo apt-get install -y build-essential pkg-config libssl-dev \
  libgtk-3-dev libwebkit2gtk-4.1-dev libsoup-3.0-dev libasound2-dev \
  libjavascriptcoregtk-4.1-dev cmake libopus-dev libdav1d-dev

Build & Compilation Tutorial

1. Building the Rust Workspace

# Check compilation across all workspace crates
cargo check --workspace

# Build all binaries in debug mode
cargo build --workspace

# Build optimized release binaries
cargo build --workspace --release

Compiled binaries land in target/release/:

target/release/siar-cli
target/release/siar-desktop
target/release/siar-emergency-node

2. Cross-Compiling Android Native (.so) Libraries

cd apps/android
./build-native.sh

This invokes cargo ndk for all Android-relevant workspace crates and places .so files in: apps/android/app/src/main/jniLibs/<abi>/

3. Building the Android Application

cd apps/android
./gradlew assembleDebug      # Build debug APK
./gradlew installDebug       # Install on connected device/emulator

Node Configuration & User Guide

1. Command-Line Interface (`siar-cli`)

siar-cli provides an interactive terminal interface for managing identities, tickets, direct messaging, and anonymous token mailboxes.

siar-cli   # auto-initializes persistent identity under OS data directory

SIAR Interactive Messenger
--------------------------
1. Show My Peer Ticket
2. Add Contact Peer Ticket
3. Send 1:1 Direct Text
4. Send Anonymous Mailbox Message
5. Check Token Mailbox
6. Exit

Show My Peer Ticket — displays your Base64-encoded PeerTicket; share out-of-band via QR code or text.
Add Contact — paste a contact's PeerTicket; the CLI decodes and resolves the peer's public key and endpoint address.
Send Direct Text — checks candidate routes via TransportManager (LocalLan, InternetDirect, BLE) and dispatches through the routing policy engine.
Send Anonymous Mailbox Message — delivers to a relay node via an unlinkable single-use token mailbox path.

2. Desktop Application (`siar-desktop`)

cargo run --bin siar-desktop

🖼️ Visual Design Reference: See docs/screenshots/README.md for full UI references across dark/light themes, contact verification, groups, and settings.

Features (Migrated to native Slint 1.16 in crates/siar-ui-slint):

Adaptive 3-Pane Shell (ui-ux-02, ui-ux-22) — Navigation rail (64px), conversation list (320px), responsive message timeline with light/dark/high-contrast theme tokens.
Persistent Conversation History — 1:1 encrypted messages survive app restarts with smooth scroll-anchored pagination ("Load earlier messages").
Unread Tracking & Read Marks — Per-chat highest incoming sequence persisted to disk (read-marks.txt); zero phantom badge drift.
Contact Security & SAS Verification (ui-ux-08, ui-ux-15) — 60-digit Short Authentication String numeric safety numbers computed from siar-identity-multidevice; persistent device=<key> pinning; global warning banner with "Review" / "Dismiss" actions when keys change.
MLS Group Chat & Seamless Invites (ui-ux-09) — Multi-member MLS (RFC 9420) group states persist locally in SQLite; one-step invites via WelcomeBundle and one-tap join.
Own Identity & Hardware Diagnostics (ui-ux-18) — Short/full fingerprint disclosure on demand, device public identifiers, and transport link status summary.

3. Headless Emergency Relay Node (`siar-emergency-node`)

cargo run --bin siar-emergency-node

Behavior:

Listens on all local network interfaces and available Bluetooth/BLE adapters
Maintains in-memory & on-disk DTN store-carry-forward queue for offline messages
Periodically probes nearby nodes, updates link quality metrics (rtt_millis, reliability), and flushes pending queues when a route becomes available

4. Android Messenger App (`apps/android`)

Grant permissions on launch:

Bluetooth & Nearby Devices — BLUETOOTH_SCAN, BLUETOOTH_CONNECT, NEARBY_WIFI_DEVICES
Location — required on Android 12 and below for physical proximity discovery (ACCESS_FINE_LOCATION)

Features:

Chats Tab — 1:1 conversations, contact import via Peer Tickets, text + media attachments
Groups Tab — MLS group creation, group invites, multi-device encrypted threads

Testing & Fuzzing

Unit & Integration Tests

# Full workspace test suite
cargo test --workspace

# End-to-end multi-node integration suite
cargo test -p siar-messaging --test end_to_end

# Mesh network simulation (siar-testkit virtual radio)
cargo test -p siar-testkit

Nix Automated Checks

nix flake check

Fuzzing

cargo install cargo-fuzz

# Fuzz wire frame decoder
cargo fuzz run decode_frame

# Fuzz blob frame decoder
cargo fuzz run decode_blob_frame

License & Dual-Tier Model

SIAR employs a two-tier open-source licensing model designed for maximum library adoption while protecting user-facing standalone applications:

┌─────────────────────────────────────────────────────────────────────────────┐
│                            SIAR LICENSING MODEL                             │
├──────────────────────────────────────┬──────────────────────────────────────┤
│    Core Libraries (crates/*)         │    Standalone Apps (apps/*)          │
│    - siar-crypto / siar-crypto-mls   │    - apps/android (Jetpack Compose)  │
│    - siar-transport / siar-routing-policy│ - apps/desktop (Slint GUI)        │
│    - siar-storage / siar-messaging   │    - apps/cli (Terminal Node)        │
│    - siar-dtn-bundle / siar-protocol │    - apps/emergency-node (Daemon)    │
│                                      │                                      │
│    📜 MIT License OR Apache-2.0      │    📜 GNU AGPLv3 / Commercial        │
│    (Permissive Open Source)          │    (Copyleft & Enterprise Exemption) │
└──────────────────────────────────────┴──────────────────────────────────────┘

1. Permissive Core Libraries (`crates/*`): MIT OR Apache-2.0

All underlying Rust crates and protocol engines are dual-licensed under MIT OR Apache-2.0. You may freely embed, link (statically or dynamically), and build proprietary or open-source applications using these crates without any commercial subscription or copyleft obligations.

2. Standalone Applications & Daemons (`apps/*`): GNU AGPLv3

All end-user client applications (apps/android, apps/desktop, apps/cli) and headless daemons (apps/emergency-node) are licensed under GNU AGPLv3.

100% Free for Everyone — anyone can use, inspect, modify, and self-host.
Copyleft on Modifications — if you modify and distribute or run these applications over a network, you must release your modifications under AGPLv3.

3. Commercial Exemption (`SIAR-CEEL-1.0`)

For commercial enterprises that wish to rebrand, white-label, or host modified closed-source versions without AGPLv3 obligations:

Full legal terms and commercial subscription tiers: LICENSE-COMMERCIAL.md
Contact: licensing@irshadlab.org / licensing@siar.network

Contributing

Read CONTRIBUTING.md and CLA.md before opening a Pull Request.
All contributions are governed by the CLA, granting Irshad Lab dual-licensing rights.
Maintain zero-warning clean compilation across all targets (cargo check --workspace, cargo clippy -D warnings --workspace).
Preserve strict boundary isolation — core crates under crates/ must remain pure-Rust without mandatory C-library linkages.
Platform-specific hardware integration must be strictly isolated in dedicated crates (siar-media-android, siar-transport-ble-android).
Follow Specification Governance: Core domain, protocol, transport, routing, and daemon development must strictly follow sys-arch/; all UI, desktop/mobile interaction, visual state machines, and styling must strictly follow ui-ux/. Pull requests must cite their governing specification chapters.

Built with Rust, Kotlin, and OpenMLS by Irshad Lab and the SIAR Open Source Engineering Team.

Name		Name	Last commit message	Last commit date
.config		.config
.github/workflows		.github/workflows
apps		apps
assets/branding		assets/branding
crates		crates
deployments/k8s		deployments/k8s
dist		dist
docs		docs
fuzz		fuzz
platform/android/media/src/main/kotlin/com/siar/media		platform/android/media/src/main/kotlin/com/siar/media
scripts		scripts
sys-arch		sys-arch
ui-ux		ui-ux
wiki		wiki
workspace-hack		workspace-hack
.envrc		.envrc
.gitignore		.gitignore
CHANGES_SINCE_UPLOAD.md		CHANGES_SINCE_UPLOAD.md
CLA.md		CLA.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE-AGPLv3		LICENSE-AGPLv3
LICENSE-APACHE		LICENSE-APACHE
LICENSE-COMMERCIAL.md		LICENSE-COMMERCIAL.md
LICENSE-MIT		LICENSE-MIT
MIGRATION.md		MIGRATION.md
NOTICE		NOTICE
README.md		README.md
ROADMAP.md		ROADMAP.md
SIAR_SYSTEM_ARCHITECTURE_DESIGN_RATIONALE.md		SIAR_SYSTEM_ARCHITECTURE_DESIGN_RATIONALE.md
SIAR_SYSTEM_CAPABILITIES_AND_COMPARISON.md		SIAR_SYSTEM_CAPABILITIES_AND_COMPARISON.md
clippy.toml		clippy.toml
default.nix		default.nix
deny.toml		deny.toml
flake.lock		flake.lock
flake.nix		flake.nix
install-nix.sh		install-nix.sh
rust-toolchain.toml		rust-toolchain.toml
shell.nix		shell.nix
spec-order.md		spec-order.md

Latest commit

History

Folders and files

Repository files navigation

SIAR — Survivable Identity & Autonomous Routing

⚠️ FOUNDATIONAL DEVELOPMENT NOTICE — NOT CURRENTLY USABLE ON ANY DEVICE

Table of Contents

What SIAR Is

Core Design Rules

Specification Governance: sys-arch for Core, ui-ux for UI

1. Core Development Follows sys-arch/

2. User Interface Development Follows ui-ux/

3. Core-to-UI Separation Invariant

Architecture: Five Layers

Transport & Routing Policy Engine

Multi-Device Identity & Trust

End-to-End Security Model

DTN: Store-Carry-Forward

Realtime Calls & Media

Headless Daemon & Embedded Nodes

Protocol Extensions & WASM

Anonymity Transport Plane

Workspace Crate Map (41 Domain Crates)

Deployment Modes

1. Standalone User Applications

2. Headless Off-Grid Repeater Daemon

3. Embedded / Self-Hosted Relay Infrastructure

SIAR vs Traditional Messengers

Implementation Status & Roadmap

Prerequisites & Environment Setup

1. Nix Development Environment (Recommended)

2. Manual Rust & Platform Setup

Build & Compilation Tutorial

1. Building the Rust Workspace

2. Cross-Compiling Android Native (.so) Libraries

3. Building the Android Application

Node Configuration & User Guide

1. Command-Line Interface (siar-cli)

2. Desktop Application (siar-desktop)

3. Headless Emergency Relay Node (siar-emergency-node)

4. Android Messenger App (apps/android)

Testing & Fuzzing

Unit & Integration Tests

Nix Automated Checks

Fuzzing

License & Dual-Tier Model

1. Permissive Core Libraries (crates/*): MIT OR Apache-2.0

2. Standalone Applications & Daemons (apps/*): GNU AGPLv3

3. Commercial Exemption (SIAR-CEEL-1.0)

Contributing

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

1. Core Development Follows `sys-arch/`

2. User Interface Development Follows `ui-ux/`

1. Command-Line Interface (`siar-cli`)

2. Desktop Application (`siar-desktop`)

3. Headless Emergency Relay Node (`siar-emergency-node`)

4. Android Messenger App (`apps/android`)

1. Permissive Core Libraries (`crates/*`): MIT OR Apache-2.0

2. Standalone Applications & Daemons (`apps/*`): GNU AGPLv3

3. Commercial Exemption (`SIAR-CEEL-1.0`)