fips_setup/plans/fips-overview.md

FIPS: Free Internetworking Peering System — Overview

1. What It Does

FIPS is a self-organizing, decentralized mesh network written in Rust. It allows any set of machines to form an encrypted peer-to-peer network that routes traffic without any central authority, DNS, ISP, or infrastructure dependency.

The Elevator Pitch

Connect to one peer and you can reach the entire mesh. No accounts, no servers, no registration. Your cryptographic keypair is your address.

Concrete Capabilities

Capability	Description
Mesh networking	Nodes discover each other, build routing automatically, and relay traffic for each other across multiple hops
Multi-transport	Works over UDP, TCP, Ethernet, Tor, and Bluetooth (BLE) — designed for serial and radio too
End-to-end encryption	Double-layer: every hop is encrypted and every session is independently encrypted end-to-end
Nostr-native identity	Your node address is a Nostr keypair — npub1... — no registration, no CA, no central authority
IPv6 compatibility	A TUN interface maps npubs to fd00::/8 IPv6 addresses so unmodified apps like SSH, curl, and ping6 just work
DNS for the mesh	Built-in .fips DNS resolver: ping6 npub1abc...fips resolves and routes through the mesh
Zero configuration	A node can start with no config file; add one peer address and you join the network
Operator tooling	fipsctl CLI and fipstop TUI dashboard for live monitoring of peers, links, sessions, and routing

What You Gain

1. Sovereignty — You own your identity. No one can revoke your address or deny you access.
2. Resilience — The mesh self-heals around failures. No single point of failure.
3. Privacy — Intermediate nodes route traffic without learning endpoint identities. Hop-by-hop + end-to-end encryption means even your direct peers cannot read your session traffic.
4. Transport freedom — If you can get packets between two machines by any means — WiFi, Bluetooth, a serial cable, Tor, the public internet — FIPS can build a mesh link over it.
5. Application transparency — Existing IPv6 apps work without modification through the TUN adapter.

---

2. How It Works (High Level)

Architecture: Three Protocol Layers

┌─────────────────────────────────────────────────┐
│  Applications (SSH, curl, custom)                │
│  ↕ IPv6 TUN adapter (fd00::/8) + .fips DNS      │
├─────────────────────────────────────────────────┤
│  FSP — FIPS Session Protocol                     │
│  End-to-end Noise XK encryption between npubs    │
│  Port-based service multiplexing                 │
├─────────────────────────────────────────────────┤
│  FMP — FIPS Mesh Protocol                        │
│  Peer auth (Noise IK), spanning tree,            │
│  bloom filters, hop-by-hop forwarding            │
├─────────────────────────────────────────────────┤
│  Transport Layer                                 │
│  UDP | TCP | Ethernet | Tor | BLE                │
└─────────────────────────────────────────────────┘

Identity: Your Keypair Is Your Address

1. A node generates a secp256k1 keypair (same as Nostr)
2. The public key (npub) is the node's identity
3. A node_addr (16-byte SHA-256 hash of the pubkey) is used internally for routing — intermediate routers see only this hash, not the npub
4. An IPv6 address (fd00::/8) is deterministically derived from the node_addr for the TUN interface

All three representations — npub, node_addr, IPv6 — are derived from the same keypair. No registration needed.

Self-Organization: Spanning Tree + Bloom Filters

The mesh organizes itself through two complementary mechanisms:

Spanning Tree (The Coordinate System)

• Nodes gossip TreeAnnounce messages with their direct peers
• Each node independently selects a parent based on cost-weighted depth
• The network converges on a single root (the node with the smallest node_addr) — no voting, no election
• Every node gets a coordinate — its path from itself to the root
• These coordinates enable distance calculations between any two nodes without global topology knowledge
• Tree state per node is O(peers × depth), not O(network size)

Bloom Filters (Reachability Knowledge)

• Each node maintains per-peer bloom filters summarizing which destinations are reachable through each peer
• Filters propagate transitively through tree edges using split-horizon (borrowed from distance-vector routing) to prevent loops
• At each hop, the router checks: "which of my peers can possibly reach destination D?" — definitive "no" eliminates a peer; "maybe" means worth checking
• Fixed 1 KB filter size regardless of network size; effective for networks up to ~2,000 nodes

Routing Decision (Per-Hop)

At each hop, the forwarding decision is:

1. Local delivery? — destination is this node
2. Direct peer? — destination is an authenticated neighbor
3. Bloom-guided selection — bloom filters identify candidate peers; tree coordinates rank them by distance
4. Greedy tree routing — forward to the peer closest to the destination in tree distance

Two-Layer Encryption

Every packet is encrypted twice, independently:

Layer	Scope	Noise Pattern	Purpose
FMP	Hop-by-hop	Noise IK	Encrypts ALL traffic on each peer link
FSP	End-to-end	Noise XK	Encrypts application payload between endpoints

A packet from node A to node D through intermediaries B and C:

A encrypts payload with A↔D session key (FSP)
A wraps + encrypts with A↔B link key (FMP) → sends to B
B decrypts link layer, reads destination, re-encrypts with B↔C link key → forwards to C
C decrypts link layer, re-encrypts with C↔D link key → forwards to D
D decrypts link layer, then decrypts session layer → gets payload

Intermediate nodes B and C route by destination node_addr but cannot read the session payload.

Transport Agnosticism

FIPS treats transports as dumb pipes. Each transport implements: send bytes, receive bytes, report MTU. The mesh layer handles everything above that. A single packet path might traverse:

WiFi → Ethernet → UDP/Internet → Tor → BLE

The application never knows or cares which transports are involved.

---

3. How It Is Innovative

3.1 Nostr Identity as Network Address

Most mesh networks invent their own identity system. FIPS reuses Nostr keypairs (secp256k1/Schnorr) as native node addresses. This is significant because:

• No identity infrastructure — no CA, no registrar, no DNS. Generate a keypair and you have an address.
• Cross-ecosystem compatibility — the same npub that identifies you on Nostr relays identifies your FIPS node. Your social identity and your network identity can be the same key.
• Ephemeral or persistent — generate a throwaway keypair for a session, or keep a persistent identity across restarts. The network treats both the same.

No other mesh network uses an existing social-protocol identity system as its native addressing scheme.

3.2 Spanning Tree Coordinates + Bloom Filter Routing

FIPS combines two well-understood techniques in a novel way:

• Spanning tree coordinates (adapted from Yggdrasil/Ironwood) give every node a position without global topology knowledge
• Bloom filter reachability (adapted from distance-vector split-horizon) narrows forwarding candidates probabilistically

The key insight: bloom filters are an optimization, not a correctness requirement. If filters saturate in a large network, routing still works via greedy tree distance — it just evaluates more candidates per hop. This graceful degradation is unusual; most systems that depend on probabilistic structures fail hard when those structures saturate.

Each node's state is O(peers × depth), not O(N). A node in a 10,000-node network with 5 peers and depth 10 stores ~50 ancestry entries — not 10,000 routing table entries.

3.3 True Transport Agnosticism

Most "multi-transport" systems support maybe UDP and TCP. FIPS has working implementations for:

• UDP and TCP (overlay over existing internet)
• Raw Ethernet (no IP stack needed — MAC-level, with auto-discovery)
• Tor (SOCKS5 + onion service for anonymous peering)
• Bluetooth Low Energy (L2CAP channels with MTU negotiation)

The architecture is designed for serial links and radio too. This isn't theoretical — the transport interface is genuinely minimal (send/receive datagrams + report MTU), making new transports straightforward to add.

The implication: FIPS can build a mesh that spans the public internet, a local WiFi network, a Bluetooth PAN, and a Tor hidden service — all simultaneously, all transparently to applications.

3.4 Double-Layer Encryption with Metadata Minimization

The two independent encryption layers (hop-by-hop Noise IK + end-to-end Noise XK) are not just defense-in-depth — they serve distinct purposes:

• Hop-by-hop (IK): Authenticates peers and encrypts ALL link traffic, including routing gossip. An observer on the transport sees only encrypted blobs.
• End-to-end (XK): Protects application payload across untrusted intermediaries. XK is chosen over IK specifically because it delays initiator identity disclosure until msg3, providing stronger identity hiding for traffic traversing untrusted nodes.

Intermediate routers see only node_addr (a one-way hash) — they cannot learn the Nostr identities of the communicating endpoints. This is a deliberate metadata minimization design, not an accident.

3.5 IPv6 Adaptation Without Compromise

Many overlay networks require custom APIs or modified applications. FIPS provides a TUN interface that maps npubs to fd00::/8 IPv6 addresses, complete with:

• .fips DNS resolution (ping6 npub1abc...fips)
• ICMPv6 Packet Too Big for path MTU discovery
• TCP MSS clamping
• Static hostname mapping via /etc/fips/hosts

Unmodified SSH, curl, web browsers, and any IPv6-capable application work transparently. This makes FIPS immediately useful without waiting for application ecosystem adoption.

3.6 Qubes OS Integration (This Repository)

The fips_setup repository demonstrates FIPS running as a Qubes OS ProxyVM (sys-fips), slotting into the Qubes network chain:

AppVMs → sys-fips (ProxyVM) → sys-firewall → sys-net → Internet
              └─ fips0 (TUN) → FIPS mesh (encrypted)

Any AppVM pointed at sys-fips transparently gains access to the FIPS mesh. This is a practical deployment model that leverages Qubes' compartmentalization — the FIPS node runs in its own security domain, isolated from application VMs.

---

Summary

Dimension	FIPS Approach
Identity	Nostr keypairs — self-sovereign, no infrastructure
Routing	Spanning tree coordinates + bloom filter candidate selection
Encryption	Dual-layer: Noise IK hop-by-hop + Noise XK end-to-end
Transports	UDP, TCP, Ethernet, Tor, BLE — designed for radio/serial
Application compat	IPv6 TUN + .fips DNS — unmodified apps work
State per node	O(peers × depth), not O(network size)
Configuration	Zero-config possible; one peer address to join
Implementation	Rust, ~100+ source files, MIT licensed

FIPS is not just another VPN or overlay network. It is a complete replacement for the network layer that can operate alongside or independently of the internet, using whatever physical media are available, with cryptographic identity as the foundation rather than an afterthought.