laantungir/fips
1
0
Fork 0
mirror of https://github.com/jmcorgan/fips.git synced 2026-08-09 08:14:42 +00:00
Code Issues Packages Projects Releases Wiki Activity
71 Commits 5 Branches 10 Tags
fbdfe4e4f6b1de61e8bc62db9b9dc0baf2f59af3
Commit Graph
11 Commits
Author SHA1 Message Date
Johnathan Corgan 73129f16d7 Rename design docs for clarity, reorganize node architecture diagram 
- fips-architecture.md → fips-software-architecture.md with all
  cross-references updated (4 files)
- fips-transport-abstraction.svg → fips-node-architecture.svg, moved
  from Transport Abstraction section to Architecture Overview in
  fips-intro.md
- Added descriptive paragraph for node architecture diagram covering
  three-layer design (application interfaces, router core, transports)
 2026-02-13 15:03:06 +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 4890940bb7 Session 49: Wire protocol design with session indices 
- Add fips-wire-protocol.md: comprehensive packet dispatch design
  - Wire format: discriminator byte + session indices for O(1) dispatch
  - WireGuard-style roaming: crypto authority, not address
  - Security: rate limiting, replay protection, state machine strictness
  - Transport considerations for UDP, TCP, Tor

- Rename fips-protocol-flow.md → fips-session-protocol.md

- Update fips-design.md wire format section
  - Replace TLV with discriminator + index format
  - Cross-reference fips-wire-protocol.md for details

- Update cross-references in all design docs
 2026-02-01 16:28:16 +00:00
Johnathan Corgan a5a62b3768 Session 43: CLI config option and state machine design 
Add command-line argument parsing with clap:
- -c/--config option to specify config file path
- Overrides default search path when provided
- Proper error handling for missing/invalid files

Improve logging:
- Peer connection log now uses separate log entries per field
- Better readability with aligned timestamps

Fix ICMPv6 error handling:
- Add multicast destination filter to should_send_icmp_error()
- Router Solicitation packets (ff02::2) now silently dropped
- Add test case for multicast destination

Add phase-based state machine design document:
- Document pattern where lifecycle phases use distinct structs in enum
- PeerSlot::Connecting(PeerConnection) -> PeerSlot::Active(ActivePeer)
- Benefits: type safety, memory efficiency, security
- Describes timeout handling and lookup table requirements
 2026-01-31 23:33:02 +00:00
Johnathan Corgan ca24ba02b7 Add TUN driver design document 
- docs/design/fips-tun-driver.md: comprehensive TUN interface documentation
- Architecture diagrams, component descriptions, packet flow
- Implementation status checklist (completed vs planned)
- Testing instructions and configuration reference
 2026-01-30 05:38:58 +00:00
Johnathan Corgan 3b6a4da17d Complete FIPS architecture review cleanup 
- Rename fips-links.md to fips-transports.md, update all references
- Update README with all 6 design documents in organized sections
- Reorganize architecture review: remove verbose resolved items, consolidate
  deferred items, focus on actionable issues
- Clarify Transport/Link/Peer lifecycle in architecture doc:
  - Transports static after startup
  - Links on-demand, driven by peer lifecycle
  - Connectionless transports (UDP) immediate established
  - Connection-oriented (Tor) require link setup before auth
- Add Resource Limits configuration section (max_peers, max_transports,
  max_pending_auth, max_pending_lookups, memory_budget)
- Close timer management as non-issue (tokio handles scale)
- Defer init/shutdown to future iteration

Review status: 6 resolved, 5 deferred, 4 low-priority open
 2026-01-29 18:17:07 +00:00
Johnathan Corgan dc0acf32ea Add FIPS routing design document 
Create fips-routing.md covering the complete routing architecture:
- Bloom filter design: 4KB filters, K=2 scope, event-driven updates
- Discovery protocol: LookupRequest/Response with signed proofs
- Greedy tree routing using coordinates from discovery
- Session establishment model for minimal data packet overhead
- Router coordinate caching with LRU eviction

Key design decisions:
- Leaf-only mode for constrained devices (single peer handles routing)
- Separation of discovery (find destination) from routing (deliver packets)
- Session setup pays coordinate cost once; data packets carry only addresses
- 36-byte data packet header comparable to IPv6

Update design docs README to include new document.
 2026-01-26 00:12:47 +00:00
Johnathan Corgan d8cba510a7 Add FIPS link protocol design document 
New docs/design/fips-links.md covering:
- Link terminology (L2/L2-equivalent, not "transport")
- Link categories: overlay, shared medium, point-to-point
- Characteristics table: encapsulation, addressing, MTU, latency,
  reliability, bandwidth, discovery
- TCP-over-TCP problem and UDP preference rationale
- NAT/firewall traversal requirements
- IPv6 interface exposure to applications

Update README.md with new document entry.
 2026-01-25 22:52:37 +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