fips/docs/design/fips-software-architecture.md

FIPS Software Architecture

This document describes the stable architectural decisions that guide the FIPS codebase — the "why" behind the code's shape. It covers design principles and patterns that are expected to remain stable as the implementation evolves. For protocol behavior and wire formats, see the protocol layer documents.

Ownership and Entity Hierarchy

A FIPS node owns transports, which produce links, which authenticate into peers:

Node
├── Transports (HashMap<TransportId, TransportHandle>)
│   └── Each transport instance manages one communication medium
├── Links (HashMap<LinkId, Link>)
│   └── Each link is a connection to a remote endpoint over a transport
├── Peers (HashMap<NodeAddr, PeerSlot>)
│   └── Each peer is an authenticated remote FIPS node
├── TreeState — local view of the spanning tree
├── CoordCache — destination coordinates for routing
├── Sessions — end-to-end FSP sessions (HashMap by NodeAddr)
└── Identity — this node's cryptographic identity

Key ownership rules:

• A transport exists for the lifetime of the node (configured at startup)
• A link is created when connecting to a remote endpoint and destroyed when the connection terminates
• A peer is created when a link successfully authenticates (Noise IK handshake) and destroyed when the link goes down
• Links and peers have a one-to-one mapping with coupled lifecycles — peer teardown implies link teardown

Event-Driven Execution Model

The node uses an async select loop as its main event loop, multiplexing events from all sources into a single processing stream:

• Transport events: Inbound datagrams from all transports arrive via a shared mpsc channel
• Timer events: Periodic and one-shot timers for keepalive, stale peer detection, cache expiry, handshake timeouts
• TUN events: Outbound IPv6 packets from local applications
• Control events: Identity registrations from DNS, shutdown signals

Within the select loop, events are dispatched to focused handler functions organized by concern (handshake processing, gossip handling, forwarding, session management, timeout handling). Each handler operates on the node's state directly — there is no separate message-passing between internal components.

Why a single select loop: FIPS protocol operations frequently need to read and modify multiple pieces of state (e.g., forwarding a packet reads the coordinate cache, peer ancestry, and bloom filters simultaneously). A single-threaded event loop avoids the complexity of locking and provides deterministic ordering of state changes.

Exceptions: The TUN reader and writer run in separate blocking threads because TUN I/O is blocking (kernel file descriptor). They communicate with the main event loop via channels.

Phase-Based State Machine Pattern

FIPS entities use a Rust enum-of-structs pattern for state machines where each phase carries only the data relevant to that phase:

enum PeerSlot {
    Connecting(PeerConnection),   // handshake in progress
    Active(ActivePeer),           // authenticated, participating
}

Each variant holds a different struct with phase-appropriate fields. The PeerConnection struct carries handshake state; ActivePeer carries tree position, bloom filters, and link statistics. Transitioning between phases consumes the old struct and produces the new one, making it impossible to access handshake state after authentication is complete.

This pattern enforces at the type level that code handling an authenticated peer cannot accidentally reference handshake state, and vice versa.

See fips-state-machines.md for a detailed treatment of this pattern.

Two-Layer Encryption Rationale

FIPS uses independent Noise IK encryption at two layers:

Layer	Scope	What It Protects
FLP (link)	Hop-by-hop	All traffic on each peer link
FSP (session)	End-to-end	Application payload between endpoints

Why two layers instead of one:

• Link encryption protects all traffic from passive observers on the underlying transport — including routing metadata (TreeAnnounce, bloom filters, discovery messages) that would otherwise be visible
• Session encryption protects application payloads from intermediate routing nodes, which must decrypt link encryption to read routing headers
• Both layers always apply. For adjacent peers, traffic is encrypted twice. This eliminates special cases ("local peer" vs. "remote destination") and means topology changes (a direct peer becomes multi-hop) don't affect sessions.

Why the same pattern (Noise IK) at both layers: Both layers need mutual authentication with identity hiding for the initiator. Reusing the same cryptographic stack (secp256k1, ChaCha20-Poly1305, SHA-256) simplifies the implementation and reduces the number of cryptographic dependencies.

Identity Model

FIPS uses three related but distinct identifiers at different layers:

keypair (secp256k1)
    │
    ├── pubkey (32 bytes) — the endpoint identity, used in Noise handshakes
    │
    ├── node_addr = SHA-256(pubkey)[0..16] — routing identifier, visible to
    │   transit nodes, cannot be reversed to pubkey
    │
    └── IPv6 address = fd + node_addr[0..15] — overlay address for IPv6
        applications

Privacy property: Transit nodes see only node_addrs in packet headers. They can forward traffic without knowing the Nostr identities of the endpoints. An observer can verify "does this node_addr belong to pubkey X?" but cannot enumerate communicating identities from traffic alone.

Self-sovereign: Nodes generate their own identities without coordination. The identity system uses Nostr keypairs (secp256k1), so existing npub/nsec pairs work directly.

Protocol Self-Healing Design

FIPS control protocols are designed for eventual consistency, tolerating packet loss without acknowledgment/retry machinery:

Protocol	Self-Healing Property
TreeAnnounce	Full state with monotonic sequence; lost announcement recovered on next send
FilterAnnounce	Full filter replacement with sequence; stale filter recovered on next update
LookupRequest	Timeout-based retry at application level
SessionSetup	Timeout-based retry; lost setup triggers re-establishment on first data failure
CoordsRequired/PathBroken	Rate-limited, best-effort; lost error recovered by session idle timeout

Why no ack/retry: FIPS operates over unreliable transports (primarily UDP). Adding reliability to control messages would require per-message state, retransmission timers, and acknowledgment tracking — complexity that gossip protocols avoid by sending full state periodically. A lost TreeAnnounce is simply replaced by the next one, which carries the same or newer state.

Bounded State Principle

FIPS nodes maintain state proportional to O(P × D), where P is the number of direct peers and D is the tree depth — not O(N) where N is the network size.

What each node stores:

State	Size	Scope
Peer ancestry (TreeAnnounce)	P × D entries	Direct peers only
Bloom filters	P × 1 KB	One per peer
Coordinate cache	Configurable (50K default)	Destinations actively routed
Identity cache	Configurable (10K default)	IPv6 adapter only
Sessions	Configurable (10K default)	Active end-to-end sessions

A node does not know about nodes in distant parts of the network. It knows its direct peers, their tree positions, and the destinations it has recently routed traffic to. This scales naturally: adding nodes to the network does not increase the per-node state of existing nodes (except for a slight increase in bloom filter occupancy).

Transport Opacity

Transport addresses are opaque byte vectors above FLP. The transport layer interprets them (e.g., UDP parses "ip:port" strings); all layers above treat them as handles passed back to the transport for sending.

Architectural boundary: Adding a new transport type (e.g., BLE) requires implementing the transport trait and potentially a new TransportHandle variant. No changes to FLP, FSP, or any routing logic. The transport trait defines the interface:

• send(addr, data) — send a datagram
• mtu() — maximum datagram size
• start() / stop() — lifecycle
• discover() — optional endpoint discovery

Inbound datagrams are pushed via a shared channel, aggregating all transports into a single event stream for the main loop.

Cache Architecture

Unified Coordinate Cache

The coordinate cache maps NodeAddr → TreeCoordinate. It was originally two separate caches (session-populated and discovery-populated) but was merged into a single cache because both stored the same type of data and the distinction was conceptual, not functional.

Key properties:

• TTL-based expiration (300s default) with refresh on use — active routing resets the TTL, keeping hot entries alive
• LRU eviction when full — least recently used entries are evicted first
• Flush on parent change — when the local node's tree parent changes, the entire cache is flushed because the node's own coordinates have changed, making cached distance calculations potentially invalid

Identity Cache (LRU-Only)

The identity cache maps FIPS address prefix → (NodeAddr, PublicKey). The mapping is deterministic (derived from public key) and never becomes stale, so there is no TTL — only LRU eviction bounded by a configurable size.

This cache is needed only by the IPv6 adapter. The native FIPS API provides the public key directly.

Timer Ordering

Cache and session timers are ordered to ensure correct lifecycle behavior:

Session idle timeout (90s) < Coordinate cache TTL (300s) ≤ DNS TTL (300s)

When traffic stops, the session tears down first (90s). When traffic resumes, a fresh SessionSetup re-warms transit caches that are still within their TTL (300s). This ordering prevents the case where a session outlives its transit cache entries, which would cause routing failures.

Receive Path Design

Transports use a channel-push model rather than a poll/receive method. Each transport takes a sender handle (PacketTx) at construction and spawns an internal receive loop that pushes inbound datagrams onto the channel. The node's main select loop reads from the corresponding receiver.

Why push, not poll: Async Rust cannot express async methods on trait objects (the Transport trait is synchronous). The channel-push model works around this limitation: the concrete transport implementation (e.g., UdpTransport) spawns its own async receive task and pushes to a channel, while the trait surface remains synchronous for send(), mtu(), etc.

The TransportHandle enum provides async dispatch for methods that need it (like send_async()) without requiring dyn dispatch.

References

• fips-intro.md — Protocol overview
• fips-link-layer.md — FLP specification
• fips-session-layer.md — FSP specification
• fips-state-machines.md — Phase-based state machine pattern
• fips-configuration.md — YAML configuration reference