mirror of
https://github.com/jmcorgan/fips.git
synced 2026-10-05 19:18:25 +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.
126 lines
6.3 KiB
XML
126 lines
6.3 KiB
XML
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 840 370" font-family="monospace" font-size="12">
|
|
<style>
|
|
rect.box { rx: 4; stroke-width: 1.5; }
|
|
rect.source { fill: #1a3a2a; stroke: #40a060; }
|
|
rect.derived { fill: #1a2a3a; stroke: #4080c0; }
|
|
rect.encoding { fill: #2a2040; stroke: #8060c0; }
|
|
rect.compat { fill: #2a1a1a; stroke: #c06040; }
|
|
rect.use { fill: #151520; stroke: #404060; stroke-width: 1; rx: 3; }
|
|
text { fill: #e0e0e0; }
|
|
text.title { font-size: 16px; font-weight: bold; }
|
|
text.subtitle { font-size: 12px; fill: #909090; }
|
|
text.label { font-size: 13px; font-weight: bold; }
|
|
text.detail { font-size: 10px; fill: #909090; }
|
|
text.op { font-size: 10px; fill: #b0b0b0; font-style: italic; }
|
|
text.use-text { font-size: 10px; fill: #c0c0c0; }
|
|
line.arrow { stroke: #606080; stroke-width: 1.5; }
|
|
line.derive { stroke: #4080c0; stroke-width: 1.5; }
|
|
line.encode { stroke: #8060c0; stroke-width: 1.5; stroke-dasharray: 4,3; }
|
|
polygon.head { fill: #606080; }
|
|
polygon.dhead { fill: #4080c0; }
|
|
polygon.ehead { fill: #8060c0; }
|
|
</style>
|
|
|
|
<!-- Background -->
|
|
<rect width="840" height="370" fill="#0d1117" rx="8"/>
|
|
|
|
<!-- Title -->
|
|
<text x="420" y="28" text-anchor="middle" class="title">FIPS Identity Derivation</text>
|
|
<text x="420" y="46" text-anchor="middle" class="subtitle">From Nostr keypair to protocol identifiers</text>
|
|
|
|
<!-- ═══ Source: pubkey ═══ -->
|
|
<rect x="280" y="70" width="240" height="50" class="box source"/>
|
|
<text x="400" y="92" text-anchor="middle" class="label">pubkey</text>
|
|
<text x="400" y="106" text-anchor="middle" class="detail">Nostr cryptographic identity</text>
|
|
|
|
<!-- ═══ Left branch: bech32 encoding → npub ═══ -->
|
|
|
|
<!-- Arrow: pubkey left edge → npub -->
|
|
<line x1="280" y1="95" x2="188" y2="95" class="encode"/>
|
|
<polygon points="190,91 180,95 190,99" class="ehead"/>
|
|
<text x="226" y="87" text-anchor="middle" class="op">encode</text>
|
|
|
|
<!-- npub box -->
|
|
<rect x="30" y="70" width="150" height="50" class="box encoding"/>
|
|
<text x="105" y="92" text-anchor="middle" class="label">npub</text>
|
|
<text x="105" y="106" text-anchor="middle" class="detail">human-readable form</text>
|
|
|
|
<!-- npub use box -->
|
|
<rect x="10" y="144" width="190" height="54" class="use"/>
|
|
<text x="105" y="162" text-anchor="middle" class="use-text">Display & configuration</text>
|
|
<text x="105" y="176" text-anchor="middle" class="use-text">User-facing identifiers</text>
|
|
<text x="105" y="190" text-anchor="middle" class="use-text">DNS queries (npub.fips)</text>
|
|
|
|
<!-- npub → use connection -->
|
|
<line x1="105" y1="120" x2="105" y2="144" stroke="#606080" stroke-width="1" stroke-dasharray="3,3"/>
|
|
|
|
<!-- ═══ Right branch: pubkey → session encryption ═══ -->
|
|
|
|
<!-- Arrow: pubkey right edge → use -->
|
|
<line x1="520" y1="95" x2="620" y2="95" class="arrow"/>
|
|
<polygon points="618,91 628,95 618,99" class="head"/>
|
|
|
|
<!-- pubkey use box -->
|
|
<rect x="620" y="66" width="200" height="58" class="use"/>
|
|
<text x="720" y="86" text-anchor="middle" class="use-text">Endpoint authentication</text>
|
|
<text x="720" y="100" text-anchor="middle" class="use-text">Link & session encryption</text>
|
|
<text x="720" y="114" text-anchor="middle" class="use-text">Known only to endpoints</text>
|
|
|
|
<!-- ═══ Down: pubkey → one-way hash → node_addr ═══ -->
|
|
|
|
<!-- Arrow down from pubkey -->
|
|
<line x1="400" y1="120" x2="400" y2="170" class="derive"/>
|
|
<polygon points="396,168 400,176 404,168" class="dhead"/>
|
|
<text x="416" y="148" class="op">SHA-256, truncate to 16 bytes</text>
|
|
|
|
<!-- node_addr box -->
|
|
<rect x="280" y="176" width="240" height="50" class="box derived"/>
|
|
<text x="400" y="198" text-anchor="middle" class="label">node_addr</text>
|
|
<text x="400" y="212" text-anchor="middle" class="detail">opaque routing identifier</text>
|
|
|
|
<!-- ═══ Right branch: node_addr → routing use ═══ -->
|
|
|
|
<!-- Arrow: node_addr right edge → use -->
|
|
<line x1="520" y1="201" x2="620" y2="201" class="arrow"/>
|
|
<polygon points="618,197 628,201 618,205" class="head"/>
|
|
|
|
<!-- node_addr use box -->
|
|
<rect x="620" y="172" width="200" height="58" class="use"/>
|
|
<text x="720" y="192" text-anchor="middle" class="use-text">Packet header addressing</text>
|
|
<text x="720" y="206" text-anchor="middle" class="use-text">Spanning tree coordinates</text>
|
|
<text x="720" y="220" text-anchor="middle" class="use-text">Bloom filter entries</text>
|
|
|
|
<!-- ═══ Down: node_addr → derive → IPv6 address ═══ -->
|
|
|
|
<!-- Arrow down from node_addr -->
|
|
<line x1="400" y1="226" x2="400" y2="276" class="derive"/>
|
|
<polygon points="396,274 400,282 404,274" class="dhead"/>
|
|
<text x="416" y="254" class="op">0xfd + node_addr[0..15]</text>
|
|
|
|
<!-- IPv6 address box -->
|
|
<rect x="280" y="282" width="240" height="50" class="box compat"/>
|
|
<text x="400" y="304" text-anchor="middle" class="label">IPv6 address</text>
|
|
<text x="400" y="318" text-anchor="middle" class="detail">overlay address for IP compatibility</text>
|
|
|
|
<!-- ═══ Right branch: IPv6 → application use ═══ -->
|
|
|
|
<!-- Arrow: IPv6 right edge → use -->
|
|
<line x1="520" y1="307" x2="620" y2="307" class="arrow"/>
|
|
<polygon points="618,303 628,307 618,311" class="head"/>
|
|
|
|
<!-- IPv6 use box -->
|
|
<rect x="620" y="278" width="200" height="58" class="use"/>
|
|
<text x="720" y="298" text-anchor="middle" class="use-text">TUN interface (fips0)</text>
|
|
<text x="720" y="312" text-anchor="middle" class="use-text">Unmodified IP applications</text>
|
|
<text x="720" y="326" text-anchor="middle" class="use-text">ping, curl, ssh, etc.</text>
|
|
|
|
<!-- ═══ Left: privacy annotation ═══ -->
|
|
<rect x="10" y="218" width="245" height="62" fill="#151520" stroke="#505040" stroke-width="1" rx="3"/>
|
|
<text x="132" y="236" text-anchor="middle" font-size="11" font-weight="bold" fill="#d0a040">Privacy boundary</text>
|
|
<text x="132" y="252" text-anchor="middle" class="use-text">Intermediate routers see only</text>
|
|
<text x="132" y="266" text-anchor="middle" class="use-text">node_addr — never the pubkey.</text>
|
|
|
|
<!-- Dashed line connecting privacy box to node_addr -->
|
|
<line x1="255" y1="249" x2="280" y2="201" stroke="#505040" stroke-width="1" stroke-dasharray="3,3"/>
|
|
</svg>
|