# 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.