laantungir/fips
1
0
Fork 0
mirror of https://github.com/jmcorgan/fips.git synced 2026-08-09 00:04:54 +00:00
Code Issues Packages Projects Releases Wiki Activity
125 Commits 5 Branches 10 Tags
92d5df8037ea2ac898fc72472bf9432fb913e4c0
Commit Graph
9 Commits
Author SHA1 Message Date
Johnathan Corgan d46dc874ef Restructure design docs around protocol layers 
Reorganize FIPS design documentation from implementation-centric
structure (routing, gossip protocol, wire protocol, transports) to
protocol-layer organization with clear service boundaries.

New documents (8):
- fips-transport-layer.md — transport layer spec
- fips-link-layer.md — FLP spec (peer auth, link encryption, forwarding)
- fips-session-layer.md — FSP spec (end-to-end encryption, sessions)
- fips-ipv6-adapter.md — IPv6 adaptation (TUN, DNS, MTU enforcement)
- fips-mesh-operation.md — routing, discovery, error recovery
- fips-wire-formats.md — consolidated wire format reference
- fips-spanning-tree.md — tree algorithm reference
- fips-bloom-filters.md — bloom filter math reference

Rewritten (2):
- fips-intro.md — breadth-first intro with layer model diagrams
- fips-software-architecture.md — slimmed to stable decisions

Updated (3):
- spanning-tree-dynamics.md — removed stale root refresh, aligned terminology
- fips-configuration.md — fixed priority type (u16 → u8)
- fips-state-machines.md — synced code examples with codebase

Deleted (6): fips-transports.md, fips-wire-protocol.md,
fips-gossip-protocol.md, fips-session-protocol.md, fips-routing.md,
fips-tun-driver.md (content absorbed into new structure)
 2026-02-17 04:50:04 +00:00
Johnathan Corgan 20467f5650 Design doc audit: correct 7 code/doc divergences across 5 documents 
Systematic review identified 12 divergences between design docs and
implementation. Corrected 7, deferred 3 for further analysis.

Changes:
- Session tie-breaker: npub → node_addr ordering
- Dual cache architecture: CoordCache (50K, TTL 300s) and RouteCache
  (10K, LRU) with correct names, sizes, and eviction policies
- LookupResponse routing: greedy-only → find_next_hop + reverse-path
- Discovery TTL default: 8 → 64
- Parent selection: v1 depth-only algorithm, cost metrics marked v2
- Leaf-only mode: implementation status note added
- Data overhead: 36-byte → 38-byte header
- Verification pass fixed stale cache/header refs in session protocol doc
 2026-02-14 19:26:25 +00:00
Johnathan Corgan 5d7af5b478 Implement FilterAnnounce send/receive, remove TTL/K-hop scoping 
Add bloom filter reachability announcement protocol:
- FilterAnnounce encode/decode (wire format 0x20, 1035 bytes)
- node/bloom.rs: send/receive with debounce, split-horizon loop prevention
- Handler wiring: dispatch, tick, peer promotion/removal, cross-connection
- Five integration tests: 10-node, star, chain, ring, 100-node convergence

Remove TTL/K-hop mechanism from code and design docs after discovering
that per-entry TTL scoping is fundamentally incompatible with flat bloom
filter merge + regeneration architecture. Each node re-originates filters
with fresh TTL, making propagation unbounded regardless of TTL value.
Split-horizon remains the primary loop prevention mechanism.

Document spanning tree known limitations (v1) in spanning-tree-dynamics.md.

316 tests pass, clean build, zero warnings.
 2026-02-11 03:16:25 +00:00
Johnathan Corgan 5e7342c57c Standardize naming conventions across docs and source 
Rename NodeId to NodeAddr and npub to pubkey throughout documentation
and source code for consistency with the established identity model.
Add FIPS API vs IPv6 adapter overview to session protocol document.
Add transport address terminology note to wire protocol document.
 2026-02-06 04:03:32 +00:00
Johnathan Corgan a8115f7622 Unify Noise IK for both link and session layers 
Design change: Session layer now uses Noise IK pattern (previously KK),
matching the link layer. Rationale: initiator knows destination npub,
responder learns initiator identity from handshake - same asymmetry as
link connections.

Document consistency fixes:
- Auth* events → Noise IK msg1/msg2 terminology in state machines
- PeerId → NodeId in routing code examples
- BloomUpdate → FilterAnnounce terminology
- Updated cross-references and tables
 2026-02-02 02:25:39 +00:00
Johnathan Corgan e582f50de7 Session 51: Create fips-intro.md protocol introduction 
New comprehensive protocol introduction replacing fips-design.md:
- What is FIPS / Why FIPS: goals and design philosophy
- How It Works: transport, spanning tree, bloom filters, routing overview
- Prior Work: Yggdrasil/Ironwood, Noise Protocol, WireGuard references
- Identity System: npub/nsec, node_id derivation, fd00::/8 addressing
- Two-Layer Encryption: link layer (Noise IK), session layer (Noise KK)
- Spanning Tree Protocol: root election, parent selection, gossip limits
- Bloom Filter Routing: filter explanation, propagation, discovery
- Transport Abstraction: transport/link distinction, bridging, types
- Security: threat model, Sybil resistance, accurate metadata exposure

Updated cross-references in README.md and other design docs.
Deleted obsolete fips-design.md.
 2026-02-01 20:51:01 +00:00
Johnathan Corgan 7c2e11c5de Session 50: Design document reorganization and gossip protocol 
- Create fips-gossip-protocol.md with wire formats for TreeAnnounce,
  FilterAnnounce, LookupRequest/LookupResponse
- Refactor fips-routing.md to reference gossip protocol for wire formats
- Update fips-session-protocol.md: remove reconciliation section,
  condense peer connection section
- Update spanning-tree-dynamics.md with gossip protocol reference
- Reorganize README.md with suggested reading order
- Remove obsolete fips-architecture-review.md
 2026-02-01 17:42:17 +00:00
Johnathan Corgan fc20c47119 Resolve architecture review items and reconcile terminology 
- Standardize coordinate ordering to [self, parent, ..., root] across all docs
- Fix 8 coordinate ordering instances in spanning-tree-dynamics.md
- Clarify cache naming: discovery.cache and session.cache configure Node.coord_cache
- Reconcile Transport vs Link terminology:
  - Transport = interface/medium (UDP socket, Ethernet NIC)
  - Link = connection instance to a specific peer
- Update fips-design.md: replace FipsLink trait with architecture reference
- Rename fips-links.md to "Transport Protocols", add terminology section
- Update review doc: mark items 1, 5, 13 RESOLVED; items 2-4, 7 DEFERRED
 2026-01-29 17:00:33 +00:00
Johnathan Corgan 7194200f55 Add docs/design directory with protocol specifications 
Move design documents from working directory into source tree:
- fips-design.md - Full protocol design specification
- spanning-tree-dynamics.md - Spanning tree protocol dynamics study

Add README index files for docs/ and docs/design/.
 2026-01-25 22:02:54 +00:00