Technical Briefing – Free Internetworking Peering System (FIPS) Repository: https://github.com/moses-y/fips

What This Does

FIPS implements a decentralized mesh‑routing protocol built on Nostr‑style secp256k1 identities. Core Rust code lives under src/; the protocol stack, node lifecycle, and transport handling are defined in a handful of modules that together create a self‑organising network capable of spanning‑tree routing, bloom‑filter peer selection, and Noise‑based encryption. The testing/ tree contains Docker‑based chaos‑simulation harnesses used for protocol stress‑testing.

Key files:

  • src/bin/fips.rs – binary entry point (fn main).
  • src/node/lifecycle.rs – node start/stop logic (fn start).
  • src/control/queries.rs – RPC entry point (dispatch).
  • src/transport/udp.rs – UDP overlay implementation.
  • src/identity/local.rs – generation of Nostr keypairs.

All configuration is read from a fips.yaml file (search order documented in the README).

How It Is Wired

  1. Program start – cargo build --release produces target/release/fips. Execution begins at src/bin/fips.rs:21 (main).
  2. main parses CLI flags, then calls src/node/lifecycle.rs:234 → start.
  3. start creates a Node (via src/node/mod.rs:new) and spawns the control socket (src/control/mod.rs).
  4. The control socket registers RPC handlers; the primary dispatch function is src/control/queries.rs:399 (dispatch), which reaches 42 other functions and is not called elsewhere.
  5. Network I/O is handed to src/transport/mod.rs (123 functions). UDP transport is instantiated in src/transport/udp.rs, which ultimately calls socket::bind (external) and registers the packet channel.
  6. Incoming packets are routed through src/node/handlers/*. The most heavily used handler is src/node/handlers/forwarding.rs, which participates in 8 distinct call paths.
  7. Peer discovery and tree coordination rely on src/protocol/* and src/bloom/*. The bloom filter (src/bloom/filter.rs) is invoked from 48 other files and provides insert, contains, and serialization helpers.
  8. Cryptographic identity handling flows through src/identity/*; make_node_addr (154 call sites) and node_addr (142 sites) are the highest‑fan‑out functions, making them the primary change‑impact points.

File‑level blast radius (calls from many places):

  • src/bloom/filter.rs – 48 callers, 25 functions reachable.
  • src/transport/mod.rs – 17 callers, 123 functions reachable.
  • src/node/mod.rs – 25 callers, 76 functions reachable.

No circular module dependencies were detected, simplifying static analysis and future refactoring.

How To Use It

# Clone and build
git clone https://github.com/moses-y/fips.git
cd fips
cargo build --release

# Run a node (requires root for TUN)
sudo ./target/release/fips          # defaults, generates ephe‑meral identity
# or with explicit config
sudo ./target/release/fips -c fips.yaml

Configuration (fips.yaml) lives in the current directory, $HOME/.config/fips/, or /etc/fips/. A minimal two‑node example is documented in the README and uses the identity.nsec field for a Nostr secret key; omitting it generates a fresh key on each start.

For protocol‑level testing, the chaos harness can be built with Docker:

cd testing/chaos
docker build -t fips-chaos .
./scripts/chaos.sh  # runs predefined scenarios

The harness reads testing/static/.env (currently committed) for environment variables; replace or remove it before production use.

Code Health & Issues

Measured findings (static analysis):

  • HIGH – Deep nesting – src/control/mod.rs, src/node/handlers/encrypted.rs, src/node/handlers/forwarding.rs (max depth 8).
  • HIGH – Duplicated code – repeated 6‑line blocks across 44 files (e.g., src/cache/coord_cache.rs, src/protocol/discovery.rs).
  • MEDIUM – Broad exception handling – testing/chaos/sim/runner.py uses bare except.
  • MEDIUM – Oversized files – src/node/handlers/session.rs, src/node/mod.rs, src/node/tests/routing.rs (> 1 k LOC each).
  • MEDIUM – High branching density – src/identity/encoding.rs (15 branches in 46 lines).

Code‑health audit adds:

  • HIGH – No CI workflow – repository lacks any .github/workflows/*.
  • HIGH – Deploy image not gated – testing/chaos/Dockerfile builds without CI validation.
  • HIGH – Committed secret file – testing/static/.env should be removed and rotated.
  • MEDIUM – Dependabot missing – only one manifest (Cargo.toml).
  • MEDIUM – Base image not pinned – testing/chaos/Dockerfile uses debian:bookworm-slim.
  • MEDIUM – No pre‑commit secret scan.
  • MEDIUM – Docker image runs as root – add a non‑root USER.

All issues include concrete fix recommendations in the audit; no additional concerns were found.

The Bottom Line

FIPS delivers a complete Rust‑based mesh routing stack with documented design assets and a functional test harness. The codebase is functional but shows classic early‑stage technical debt: deep nesting, duplicated logic, and large modules that will hinder maintainability. Absence of CI/CD and the presence of a committed .env are immediate risks for production use. The project is suitable for teams comfortable with Rust and willing to invest in refactoring and CI integration before deploying in a security‑sensitive environment.