mirror of
https://github.com/jmcorgan/fips.git
synced 2026-07-30 19:46:15 +00:00
Johnathan Corgan
5abf9a9325
Restructures /docs/ by reader purpose (tutorials, how-to, reference, design), adds the new-user-progression and operator-recipe content the prior layout lacked, runs an accuracy pass against current source across the pre-existing design docs, and rewrites the gateway feature-set documentation end-to-end around its actual operational profile (a niche feature designed for systems already serving DHCP/DNS to a LAN, with two independent halves — outbound LAN→mesh, inbound mesh→LAN — sharing one nftables table, one binary, and one control socket). Top-level README and getting-started rewritten around two equally-weighted deployment modes (overlay on existing IP networks; ground-up over non-IP transports). ## Additions - 11 new tutorials in docs/tutorials/: an 8-step new-user progression from single-daemon test-mesh peering through to a ground-up two-device mesh, an IPv6-adapter side-trip walkthrough, an Advanced Tutorials index, and a hand-held OpenWrt walk-through for fips-gateway deployment that exercises both halves of the feature. - 12 new how-tos in docs/how-to/: firewall activation, Nostr discovery (resolve / advertise / open across five scenarios), Tor onion (directory + control_port modes), UDP buffer tuning, unprivileged-user setup, persistent identity, host aliases, Bluetooth LE peering, MTU diagnostics, manual Linux-host gateway deployment (covers both halves), gateway troubleshooting (organised by half), and a section index. - 9 new reference docs in docs/reference/: configuration, wire formats, control-socket protocol, four CLI references (fips, fipsctl, fipstop, fips-gateway), security posture matrix, and Nostr events catalog. Configuration and wire-formats are renamed-and-extended from prior design/ versions; the other seven are net-new. - 6 new design docs: fips-concepts, fips-architecture, and fips-prior-work split out of the deleted fips-intro.md; consolidated fips-mmp and fips-mtu aggregations; and a new generic port-advertisement-and-nat-traversal doc (Nostr-signaled port advertisement plus UDP NAT-traversal protocol, FIPS as an example implementation, suitable for eventual NIP submission). - Top-level docs/getting-started.md walking through the binary-installer-only Install story. - packaging/common/hosts pre-populated with the eight public test-mesh nodes so shortnames resolve out of the box on every fresh install. ## Changes - 23 wire-format diagrams relocated to reference/diagrams/ alongside the wire-formats move. - 4 design diagrams corrected against source code (fips-protocol-stack, fips-identity-derivation, fips-coordinate-discovery, fips-routing-decision). - 10 pre-existing design docs reconciled with current source. Numeric corrections: stale link-MMP report bounds (now [1s, 5s] with 200 ms cold-start floor); UDP default MTU (now 1280, IPv6 minimum); node_addr formula (SHA-256(pubkey)[..16]); Noise patterns (IK at link, XK at session); peer-ACL semantics (strict allowlist requires ALL in peers.deny); daemon DNS upstream ([::1]:5354); on-the-wire bloom-filter size (1,071 bytes); obsolete Cargo-feature references (PR #79 dropped them) removed. - Transport framing tightened across the docs: TCP is for UDP-filtered networks (not NAT traversal); Tor is a deployment mode (not failover); WebSocket dropped (not a shipped FIPS transport); WiFi promoted to Implemented via Ethernet in infrastructure mode; classic-Bluetooth row removed (BLE is the only Bluetooth-mode transport). - docs/design/fips-gateway.md rewritten end-to-end to lead with the niche-feature framing and the two-halves structure. Title moved from "FIPS Outbound LAN Gateway" to "FIPS Gateway"; architecture section describes the common machinery (the fips-gateway service, the nftables table, the control socket) before splitting into separate "Outbound Half" and "Inbound Half" sections of equal weight; security considerations split per-half; no Future Work section (speculative directions live in the project tracker, not in protocol design docs). Inbound port forwarding is a first-class half rather than a buried "Implemented Extensions" subsection. - Gateway terminology unified across all gateway docs as a separate Linux service running alongside the fips daemon (its own systemd unit / OpenWrt init script). Container- pattern terms (sidecar) are reserved for the Docker/Kubernetes sidecar deployment examples — the testing/sidecar/ tree, examples/k8s-sidecar/, examples/sidecar-nostr-relay/, examples/wireguard-sidecar-macos/, and the related CHANGELOG / top-level README entries — where the term carries its standard container meaning. - Net-new design body content: rekey section in fips-mesh-layer (Noise IK msg1/msg2 over the established link, K-bit cutover, drain window, smaller-NodeAddr-wins tie-breaker on dual-init); Mesh Size Estimation and Antipoison FPR Cap sections in fips-bloom-filters; Mesh-Interface Query Filter subsection in fips-ipv6-adapter; failure-suppression knobs and clock- skew tolerance in fips-nostr-discovery; loop-rejection and mid-chain ancestor swap added to spanning-tree propagation / stability rules; Priority Chain in fips-mesh-operation renumbered to match the routing-decision diagram. - Top-level README: dropped the stale nostr-discovery cargo-feature parenthetical. docs/README.md and the four section READMEs (tutorials, how-to, reference, design) refreshed for the new structure; index rows reflect both halves of the gateway feature and the new fips-gateway CLI reference. - Cargo.toml [package.metadata.deb] assets path updated for the fips-security.md move; .gitignore /reference/ rule anchored to repo root so docs/reference/ is trackable. - packaging/openwrt-ipk/files/etc/fips/fips.yaml configuration-doc URL updated to the new docs/reference/configuration.md location. ## Deletions - docs/design/fips-intro.md (split into the three new intro design docs). - docs/design/document-relationships.svg (orphan, no longer referenced). - docs/proposals/ tree removed; the only proposal it contained (the Nostr UDP hole-punch protocol) was rewritten as the new generic design/port-advertisement-and-nat-traversal.md.
104 lines
3.7 KiB
TOML
104 lines
3.7 KiB
TOML
[package]
|
|
name = "fips"
|
|
version = "0.3.0-dev"
|
|
edition = "2024"
|
|
description = "A distributed, decentralized network routing protocol for mesh nodes connecting over arbitrary transports"
|
|
license = "MIT"
|
|
authors = ["Johnathan Corgan <jcorgan@corganlabs.com>"]
|
|
repository = "https://github.com/jmcorgan/fips"
|
|
readme = "README.md"
|
|
|
|
[dependencies]
|
|
ratatui = "0.30"
|
|
secp256k1 = { version = "0.30", features = ["rand", "global-context"] }
|
|
sha2 = "0.10"
|
|
hkdf = "0.12"
|
|
chacha20poly1305 = "0.10"
|
|
rand = "0.10.0"
|
|
thiserror = "2.0"
|
|
bech32 = "0.11"
|
|
serde = { version = "1.0", features = ["derive"] }
|
|
serde_json = "1.0"
|
|
serde_yaml = "0.9"
|
|
dirs = "6.0"
|
|
hex = "0.4"
|
|
clap = { version = "4.5", features = ["derive"] }
|
|
tracing = "0.1"
|
|
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
|
|
tokio = { version = "1", features = ["rt", "macros", "signal", "sync", "net", "time", "process", "io-util"] }
|
|
futures = "0.3"
|
|
simple-dns = "0.11.2"
|
|
socket2 = { version = "0.6.2", features = ["all"] }
|
|
tokio-socks = "0.5"
|
|
portable-atomic = { version = "1", features = ["std"] }
|
|
|
|
nostr = { version = "0.44", features = ["std", "nip59"] }
|
|
nostr-sdk = "0.44"
|
|
|
|
[target.'cfg(unix)'.dependencies]
|
|
tun = { version = "0.8.5", features = ["async"] }
|
|
libc = "0.2"
|
|
|
|
[target.'cfg(target_os = "linux")'.dependencies]
|
|
rtnetlink = "0.20.0"
|
|
rustables = "0.8.7"
|
|
|
|
# bluer/BlueZ needs glibc — see build.rs `bluer_available` cfg gate.
|
|
[target.'cfg(all(target_os = "linux", not(target_env = "musl")))'.dependencies]
|
|
bluer = { version = "0.17", features = ["bluetoothd", "l2cap"] }
|
|
|
|
[target.'cfg(windows)'.dependencies]
|
|
wintun = "0.5"
|
|
windows-service = "0.7"
|
|
|
|
[package.metadata.deb]
|
|
maintainer = "Johnathan Corgan <jcorgan@corganlabs.com>"
|
|
copyright = "2026 Johnathan Corgan"
|
|
license-file = ["LICENSE", "0"]
|
|
section = "net"
|
|
priority = "optional"
|
|
depends = "libc6, systemd, libdbus-1-3"
|
|
recommends = "bluez"
|
|
extended-description = """\
|
|
FIPS is a distributed, decentralized network routing protocol for mesh \
|
|
nodes connecting over arbitrary transports including UDP, TCP, Ethernet, \
|
|
Tor, and Bluetooth (BLE). It provides encrypted peer-to-peer connectivity \
|
|
with automatic key management, TUN-based virtual networking, and .fips DNS \
|
|
resolution."""
|
|
maintainer-scripts = "packaging/debian/"
|
|
assets = [
|
|
["target/release/fips", "/usr/bin/", "755"],
|
|
["target/release/fipsctl", "/usr/bin/", "755"],
|
|
["target/release/fipstop", "/usr/bin/", "755"],
|
|
["packaging/common/fips.yaml", "/etc/fips/fips.yaml", "600"],
|
|
["packaging/common/hosts", "/etc/fips/hosts", "644"],
|
|
["packaging/common/fips.nft", "/etc/fips/fips.nft", "644"],
|
|
["packaging/debian/fips.service", "/lib/systemd/system/fips.service", "644"],
|
|
["packaging/debian/fips-dns.service", "/lib/systemd/system/fips-dns.service", "644"],
|
|
["packaging/debian/fips-firewall.service", "/lib/systemd/system/fips-firewall.service", "644"],
|
|
["packaging/common/fips-dns-setup", "/usr/lib/fips/fips-dns-setup", "755"],
|
|
["packaging/common/fips-dns-teardown", "/usr/lib/fips/fips-dns-teardown", "755"],
|
|
["packaging/debian/fips.tmpfiles", "/usr/lib/tmpfiles.d/fips.conf", "644"],
|
|
["target/release/fips-gateway", "/usr/bin/", "755"],
|
|
["packaging/debian/fips-gateway.service", "/lib/systemd/system/fips-gateway.service", "644"],
|
|
["docs/design/fips-security.md", "/usr/share/doc/fips/fips-security.md", "644"],
|
|
]
|
|
conf-files = ["/etc/fips/fips.yaml", "/etc/fips/hosts", "/etc/fips/fips.nft"]
|
|
|
|
[dev-dependencies]
|
|
tempfile = "3.15"
|
|
criterion = { version = "0.8.2", features = ["html_reports"] }
|
|
tokio = { version = "1", features = ["test-util"] }
|
|
|
|
[[bin]]
|
|
name = "fipsctl"
|
|
path = "src/bin/fipsctl.rs"
|
|
|
|
[[bin]]
|
|
name = "fips-gateway"
|
|
path = "src/bin/fips-gateway.rs"
|
|
|
|
[[bin]]
|
|
name = "fipstop"
|
|
path = "src/bin/fipstop/main.rs"
|