mirror of
https://github.com/jmcorgan/fips.git
synced 2026-10-30 15:48:34 +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.
154 lines
8.6 KiB
XML
154 lines
8.6 KiB
XML
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 920" font-family="monospace" font-size="12">
|
||
<style>
|
||
text { fill: #e0e0e0; }
|
||
text.title { font-size: 16px; font-weight: bold; }
|
||
text.subtitle { font-size: 12px; fill: #909090; }
|
||
text.step { font-size: 11px; fill: #5080c0; font-weight: bold; }
|
||
text.decision { font-size: 12px; }
|
||
text.action { font-size: 12px; }
|
||
text.branch { font-size: 11px; fill: #a0a0b0; }
|
||
text.caption { font-size: 13px; fill: #808090; font-style: italic; }
|
||
polygon.diamond { fill: #1a1a2e; stroke: #5080c0; stroke-width: 1.5; }
|
||
rect.start { fill: #2e3a5e; stroke: #5080c0; stroke-width: 1.5; }
|
||
rect.outcome { fill: #1a3a2a; stroke: #40a060; stroke-width: 1.5; rx: 4; }
|
||
rect.error { fill: #2a1a1a; stroke: #c06040; stroke-width: 1.5; rx: 4; }
|
||
rect.interim { fill: #1a2a3a; stroke: #4080c0; stroke-width: 1.5; rx: 4; }
|
||
line.arrow { stroke: #606080; stroke-width: 1.5; }
|
||
marker { fill: #606080; }
|
||
</style>
|
||
|
||
<defs>
|
||
<marker id="arrowhead" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
|
||
<polygon points="0 0, 8 3, 0 6" fill="#606080"/>
|
||
</marker>
|
||
</defs>
|
||
|
||
<!-- Background -->
|
||
<rect width="720" height="920" fill="#0d1117" rx="8"/>
|
||
|
||
<!-- Title -->
|
||
<text x="360" y="30" text-anchor="middle" class="title">Routing Decision Chain</text>
|
||
<text x="360" y="48" text-anchor="middle" class="subtitle">Per-hop forwarding priority at each FMP router</text>
|
||
|
||
<!-- ============================================================ -->
|
||
<!-- START: Packet arrives -->
|
||
<!-- ============================================================ -->
|
||
<rect x="260" y="74" width="200" height="36" rx="18" class="start"/>
|
||
<text x="360" y="97" text-anchor="middle" class="action">Packet arrives</text>
|
||
|
||
<!-- Arrow: start → decision 1 -->
|
||
<line x1="360" y1="110" x2="360" y2="140" class="arrow" marker-end="url(#arrowhead)"/>
|
||
|
||
<!-- ============================================================ -->
|
||
<!-- STEP 1: Local delivery? -->
|
||
<!-- ============================================================ -->
|
||
<text x="240" y="155" text-anchor="end" class="step">1</text>
|
||
<polygon points="360,140 440,180 360,220 280,180" class="diamond"/>
|
||
<text x="360" y="176" text-anchor="middle" class="decision">Local</text>
|
||
<text x="360" y="190" text-anchor="middle" class="decision">delivery?</text>
|
||
|
||
<!-- Yes → right to outcome -->
|
||
<line x1="440" y1="180" x2="520" y2="180" class="arrow" marker-end="url(#arrowhead)"/>
|
||
<text x="475" y="172" text-anchor="middle" class="branch">Yes</text>
|
||
<rect x="528" y="162" width="160" height="36" class="outcome"/>
|
||
<text x="608" y="185" text-anchor="middle" class="action">Deliver to application</text>
|
||
|
||
<!-- No → down -->
|
||
<line x1="360" y1="220" x2="360" y2="260" class="arrow" marker-end="url(#arrowhead)"/>
|
||
<text x="372" y="244" class="branch">No</text>
|
||
|
||
<!-- ============================================================ -->
|
||
<!-- STEP 2: Direct peer? -->
|
||
<!-- ============================================================ -->
|
||
<text x="240" y="275" text-anchor="end" class="step">2</text>
|
||
<polygon points="360,260 440,300 360,340 280,300" class="diamond"/>
|
||
<text x="360" y="296" text-anchor="middle" class="decision">Direct</text>
|
||
<text x="360" y="310" text-anchor="middle" class="decision">peer?</text>
|
||
|
||
<!-- Yes → right to outcome -->
|
||
<line x1="440" y1="300" x2="520" y2="300" class="arrow" marker-end="url(#arrowhead)"/>
|
||
<text x="475" y="292" text-anchor="middle" class="branch">Yes</text>
|
||
<rect x="528" y="282" width="160" height="36" class="outcome"/>
|
||
<text x="608" y="305" text-anchor="middle" class="action">Forward to peer</text>
|
||
|
||
<!-- No → down -->
|
||
<line x1="360" y1="340" x2="360" y2="380" class="arrow" marker-end="url(#arrowhead)"/>
|
||
<text x="372" y="364" class="branch">No</text>
|
||
|
||
<!-- ============================================================ -->
|
||
<!-- STEP 3: Coords known? -->
|
||
<!-- ============================================================ -->
|
||
<text x="240" y="395" text-anchor="end" class="step">3</text>
|
||
<polygon points="360,380 440,420 360,460 280,420" class="diamond"/>
|
||
<text x="360" y="416" text-anchor="middle" class="decision">Coords</text>
|
||
<text x="360" y="430" text-anchor="middle" class="decision">known?</text>
|
||
|
||
<!-- No → right to error outcome -->
|
||
<line x1="440" y1="420" x2="520" y2="420" class="arrow" marker-end="url(#arrowhead)"/>
|
||
<text x="475" y="412" text-anchor="middle" class="branch">No</text>
|
||
<rect x="528" y="402" width="160" height="36" class="error"/>
|
||
<text x="608" y="425" text-anchor="middle" class="action">No route → error signal</text>
|
||
|
||
<!-- Yes → down -->
|
||
<line x1="360" y1="460" x2="360" y2="530" class="arrow" marker-end="url(#arrowhead)"/>
|
||
<text x="372" y="500" class="branch">Yes</text>
|
||
|
||
<!-- ============================================================ -->
|
||
<!-- STEP 4: Bloom filter hit? -->
|
||
<!-- ============================================================ -->
|
||
<text x="240" y="545" text-anchor="end" class="step">4</text>
|
||
<polygon points="360,530 440,570 360,610 280,570" class="diamond"/>
|
||
<text x="360" y="566" text-anchor="middle" class="decision">Bloom filter</text>
|
||
<text x="360" y="580" text-anchor="middle" class="decision">hit?</text>
|
||
|
||
<!-- Yes → right to interim step -->
|
||
<line x1="440" y1="570" x2="520" y2="570" class="arrow" marker-end="url(#arrowhead)"/>
|
||
<text x="475" y="562" text-anchor="middle" class="branch">Yes</text>
|
||
<rect x="520" y="546" width="176" height="48" class="interim"/>
|
||
<text x="608" y="562" text-anchor="middle" class="action">Rank candidates by</text>
|
||
<text x="608" y="576" text-anchor="middle" class="action">tree distance and</text>
|
||
<text x="608" y="590" text-anchor="middle" class="action">link performance</text>
|
||
|
||
<!-- Arrow from interim → final outcome -->
|
||
<line x1="608" y1="594" x2="608" y2="620" class="arrow" marker-end="url(#arrowhead)"/>
|
||
<rect x="528" y="628" width="160" height="36" class="outcome"/>
|
||
<text x="608" y="651" text-anchor="middle" class="action">Forward to 'best'</text>
|
||
|
||
<!-- No → down -->
|
||
<line x1="360" y1="610" x2="360" y2="660" class="arrow" marker-end="url(#arrowhead)"/>
|
||
<text x="372" y="640" class="branch">No</text>
|
||
|
||
<!-- ============================================================ -->
|
||
<!-- STEP 5: Greedy tree forward -->
|
||
<!-- ============================================================ -->
|
||
<text x="240" y="683" text-anchor="end" class="step">5</text>
|
||
<rect x="260" y="668" width="200" height="36" class="outcome"/>
|
||
<text x="360" y="691" text-anchor="middle" class="action">Greedy tree forward</text>
|
||
|
||
<!-- ============================================================ -->
|
||
<!-- Legend -->
|
||
<!-- ============================================================ -->
|
||
<rect x="40" y="740" width="640" height="120" fill="#151520" stroke="#404060" stroke-width="1" rx="4"/>
|
||
|
||
<rect x="60" y="762" width="24" height="14" rx="7" fill="#2e3a5e" stroke="#5080c0" stroke-width="1"/>
|
||
<text x="92" y="774" font-size="11" fill="#a0a0b0">Start / entry point</text>
|
||
|
||
<polygon points="64,800 72,793 80,800 72,807" fill="#1a1a2e" stroke="#5080c0" stroke-width="1"/>
|
||
<text x="88" y="804" font-size="11" fill="#a0a0b0">Routing decision (checked in priority order)</text>
|
||
|
||
<rect x="60" y="822" width="24" height="14" rx="4" fill="#1a3a2a" stroke="#40a060" stroke-width="1"/>
|
||
<text x="92" y="834" font-size="11" fill="#a0a0b0">Forwarding action (packet delivered or sent)</text>
|
||
|
||
<rect x="410" y="762" width="24" height="14" rx="4" fill="#1a2a3a" stroke="#4080c0" stroke-width="1"/>
|
||
<text x="442" y="774" font-size="11" fill="#a0a0b0">Intermediate processing step</text>
|
||
|
||
<rect x="410" y="793" width="24" height="14" rx="4" fill="#2a1a1a" stroke="#c06040" stroke-width="1"/>
|
||
<text x="442" y="805" font-size="11" fill="#a0a0b0">Terminal error (no route available)</text>
|
||
|
||
<line x1="410" y1="831" x2="434" y2="831" stroke="#606080" stroke-width="1.5" marker-end="url(#arrowhead)"/>
|
||
<text x="442" y="835" font-size="11" fill="#a0a0b0">Control flow direction</text>
|
||
|
||
<!-- Caption -->
|
||
<text x="360" y="896" text-anchor="middle" class="caption">Each hop checks 1–4 in priority order, falling through to greedy tree (5) when bloom yields no candidate; missing coords is the only error path</text>
|
||
</svg>
|
