nnlgsakib · nnlgsakib · Apr 10, 2026 · Apr 10, 2026 · Apr 10, 2026 · Apr 10, 2026
diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md
@@ -115,6 +115,10 @@
 - **NETW-03**: Protocol handlers: /memory/store/1.0.0, /memory/fetch/1.0.0, /memory/query/1.0.0, /memory/sync/1.0.0
 - **NETW-04**: NAT traversal via libp2p autorelay
 - **NETW-05**: Peer reputation scoring and blacklisting
+- **NETW-06**: Connection gater that blocks low-reputation and explicitly blocked peers
+- **NETW-07**: libp2p Resource Manager with per-peer connection and stream limits
+- **NETW-08**: Per-peer rate limiting on protocol handlers (/memory/store, /memory/fetch, /memory/query)
+- **NETW-09**: Peer blocklist/allowlist configurable via config file
 
 ### Daemon Architecture & CLI Restructure
 
@@ -178,10 +182,14 @@
 | MCP-03 | Phase 6 | Pending |
 | MCP-04 | Phase 6 | Pending |
 | MCP-05 | Phase 6 | Pending |
+| NETW-06 | Phase 8 | Pending |
+| NETW-07 | Phase 8 | Pending |
+| NETW-08 | Phase 8 | Pending |
+| NETW-09 | Phase 8 | Pending |
 
 **Coverage:**
-- v1 requirements: 33 total
-- Mapped to phases: 33
+- v1 requirements: 37 total
+- Mapped to phases: 37
 - Unmapped: 0 ✓
 
 ---

diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
@@ -2,7 +2,7 @@
 
 **Project:** DMGN  
 **Created:** 2025-04-09  
-**Granularity:** Standard (6 phases)
+**Granularity:** Standard (8 phases)
 
 ## Summary
 
@@ -15,6 +15,7 @@
 | 5 | [Query & Sync](#phase-5-query--sync) | Cross-peer search and consistency | Vector search, gossip sync | 5 |
 | 6 | [MCP & Polish](#phase-6-mcp--polish) | Full MCP support and production readiness | MCP tools, metrics, docs | 5 |
 | 7 | [Daemon Architecture](#phase-7-daemon-architecture--cli-restructure) | Persistent background daemon with integrated MCP and auto peer networking | Daemon, MCP auto-serve, stop cmd | 7 |
+| 8 | [Networking Enhancements](#phase-8-networking-enhancements) | QUIC transport, NAT traversal, networking security | QUIC v1, Relay v2, hole punching, connection gater, resource mgr | 4 |
 
 ---
 
@@ -168,6 +169,36 @@
 
 ---
 
+## Phase 8: Networking Enhancements
+
+**Goal:** Add QUIC transport, NAT traversal, and networking layer security for production-grade P2P connectivity
+
+**Requirements:** NETW-02, NETW-04, NETW-06, NETW-07, NETW-08, NETW-09
+
+**Success Criteria:**
+1. Node listens on both TCP and QUIC v1 transports
+2. QUIC transport functional for peer connections
+3. Circuit Relay v2 enables nodes behind NAT to be reachable
+4. Direct hole punching reduces relay dependency
+5. Configuration supports listen address arrays and NAT options
+6. Connection gater blocks low-reputation and explicitly blocked peers
+7. Resource Manager enforces per-peer connection and stream limits
+8. Protocol handlers rate-limited per peer
+9. Peer blocklist/allowlist configurable via config
+
+**Key Components:**
+- QUIC transport configuration (quic-v1 multiaddr)
+- Circuit Relay v2 service (relay for other peers)
+- Hole punching (direct NAT traversal)
+- TURN fallback configuration
+- Updated config struct (ListenAddrs array, NAT booleans)
+- Connection gater integrated with ReputationManager
+- libp2p Resource Manager (connection/stream limits)
+- Per-peer protocol rate limiter
+- Config-driven peer blocklist/allowlist
+
+---
+
 ## Dependency Graph
 
 ```
@@ -184,6 +215,8 @@ Phase 5: Query & Sync (depends on Phase 2, 4)
 Phase 6: MCP & Polish (depends on all previous)
     ↓
 Phase 7: Daemon Architecture & CLI Restructure (depends on all previous)
+    ↓
+Phase 8: Networking Enhancements (depends on Phase 3, 7)
 ```
 
 ---
@@ -211,6 +244,7 @@ Phase 7: Daemon Architecture & CLI Restructure (depends on all previous)
 | 5 | **Complete** | 2026-04-09 | 2026-04-09 |
 | 6 | **Complete** | 2026-04-09 | 2026-04-09 |
 | 7 | **Planned** | — | — |
+| 8 | **Planned** | — | — |
 
 ---
 

diff --git a/.planning/STATE.md b/.planning/STATE.md
@@ -2,11 +2,11 @@
 gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
-status: Executing Phase 07
-last_updated: "2026-04-10T03:31:53.496Z"
+status: Phase 8 ready for planning
+last_updated: "2026-04-10T04:55:00.000Z"
 progress:
-  total_phases: 7
-  completed_phases: 5
+  total_phases: 8
+  completed_phases: 6
   total_plans: 22
   completed_plans: 14
   percent: 64
@@ -20,7 +20,7 @@ See: `.planning/PROJECT.md` (updated 2025-04-09)
 
 **Core value:** User owns their identity and memory data that persists across devices and time, with no central server or third-party control.
 
-**Current focus:** Phase 07 — cli-enhancements
+**Current focus:** Phase 08 — Networking Enhancements (QUIC transport, NAT traversal)
 
 ## Phase Progress
 
@@ -32,6 +32,8 @@ See: `.planning/PROJECT.md` (updated 2025-04-09)
 | 4: Distributed Storage | **Complete** | Shamir sharding, DHT-based distribution, store/fetch protocols |
 | 5: Query & Sync | **Complete** | Vector index, hybrid scoring, GossipSub, delta sync, cross-peer query |
 | 6: MCP & Polish | **Complete** | MCP server (7 tools), OTel, backup/restore, peer reputation, docs |
+| 7: Daemon Architecture | **Complete** | Background daemon, integrated MCP, start/stop commands |
+| 8: Networking Enhancements | **Planned** | QUIC transport, NAT traversal (Circuit Relay v2, hole punching, TURN) |
 
 ## Active Work
 
@@ -71,6 +73,8 @@ Phase 6 Completed Plans:
 16. **Local-only MCP by default**: MCP server works offline-first, `--network` flag opts into P2P features.
 17. **Weighted reputation scoring**: `0.3*uptime + 0.3*latency + 0.2*sync + 0.2*availability` with exponential decay toward neutral.
 18. **Protobuf migration (hybrid)**: Wire (store/fetch, gossip, delta) = protobuf, disk = BadgerDB native, memory = hybrid (protobuf replication + JSON local), API = JSON (required)
+19. **QUIC transport**: Add QUIC v1 alongside TCP for improved latency and NAT traversal support
+20. **NAT traversal**: Enable Circuit Relay v2, direct hole punching, and TURN fallback for nodes behind NAT
 
 ## Blockers
 
@@ -84,6 +88,7 @@ None.
 
 ## Recent Changes
 
+- 2026-04-10: Phase 8 context captured — QUIC transport, NAT traversal (Circuit Relay v2, hole punching, TURN)
 - 2026-04-09: Phase 01 protobuf migration verified — all 4 protocols at v2.0.0, JSON eliminated from wire
 - 2026-04-09: Phase 1 context captured — Protobuf migration decisions (wire format, gossip, disk, memory model)
 - 2026-04-09: Phase 6 complete — 4 plans executed, 28 new tests, 13 test packages all passing

diff --git a/.planning/phases/08-networking-enhancements/08-01-PLAN.md b/.planning/phases/08-networking-enhancements/08-01-PLAN.md
@@ -0,0 +1,134 @@
+---
+phase: 8
+plan: 1
+type: implementation
+wave: 1
+depends_on: []
+files_modified:
+  - internal/config/config.go
+autonomous: true
+requirements:
+  - NETW-02
+  - NETW-04
+---
+
+# Plan 08-01: Config Migration for QUIC & NAT Traversal
+
+<objective>
+Add new config fields for QUIC listen addresses and NAT traversal options. Migrate from single `ListenAddr` string to `ListenAddrs` array with backward compatibility. Update defaults to include both TCP and QUIC v1 listen addresses.
+</objective>
+
+<tasks>
+
+## Task 1: Add new config fields and defaults
+
+<read_first>
+- `internal/config/config.go` — current Config struct with `ListenAddr string`
+- `.planning/phases/08-networking-enhancements/08-CONTEXT.md` — decisions D-01 through D-10
+- `.planning/phases/08-networking-enhancements/08-RESEARCH.md` — config migration strategy
+</read_first>
+
+<action>
+Add new fields to the `Config` struct in `internal/config/config.go`:
+
+```go
+ListenAddrs         []string `json:"listen_addrs"`
+EnableHolePunching  bool     `json:"enable_hole_punching"`
+EnableRelayService  bool     `json:"enable_relay_service"`
+RelayServers        []string `json:"relay_servers"`
+```
+
+Add these fields after the existing `ListenAddr` field. Keep `ListenAddr` for backward compatibility.
+
+Update `DefaultConfig()` to set:
+```go
+ListenAddrs:        []string{"/ip4/0.0.0.0/tcp/0", "/ip4/0.0.0.0/udp/0/quic-v1"},
+EnableHolePunching: true,
+EnableRelayService: false,
+RelayServers:       []string{},
+```
+</action>
+
+<acceptance_criteria>
+- `internal/config/config.go` contains `ListenAddrs []string` field with json tag `listen_addrs`
+- `internal/config/config.go` contains `EnableHolePunching bool` field with json tag `enable_hole_punching`
+- `internal/config/config.go` contains `EnableRelayService bool` field with json tag `enable_relay_service`
+- `internal/config/config.go` contains `RelayServers []string` field with json tag `relay_servers`
+- `DefaultConfig()` returns config with `ListenAddrs` containing exactly `["/ip4/0.0.0.0/tcp/0", "/ip4/0.0.0.0/udp/0/quic-v1"]`
+- `DefaultConfig()` returns config with `EnableHolePunching: true`
+- `DefaultConfig()` returns config with `EnableRelayService: false`
+- `go build ./...` succeeds
+</acceptance_criteria>
+
+<verify>
+```bash
+go build ./...
+```
+</verify>
+
+<threat_model>
+No security impact — config fields only. NAT traversal defaults are conservative (hole punching enabled, relay service off by default). Relay service is opt-in to prevent unwanted resource consumption.
+</threat_model>
+
+## Task 2: Add GetListenAddrs() backward compatibility method
+
+<read_first>
+- `internal/config/config.go` — the Config struct after Task 1 modifications
+</read_first>
+
+<action>
+Add the following method to `internal/config/config.go`:
+
+```go
+// GetListenAddrs returns the listen addresses to use.
+// Falls back to legacy ListenAddr if ListenAddrs is empty,
+// and returns default TCP+QUIC addresses if both are empty.
+func (c *Config) GetListenAddrs() []string {
+	if len(c.ListenAddrs) > 0 {
+		return c.ListenAddrs
+	}
+	if c.ListenAddr != "" {
+		return []string{c.ListenAddr}
+	}
+	return []string{"/ip4/0.0.0.0/tcp/0", "/ip4/0.0.0.0/udp/0/quic-v1"}
+}
+```
+</action>
+
+<acceptance_criteria>
+- `internal/config/config.go` contains `func (c *Config) GetListenAddrs() []string`
+- Method returns `ListenAddrs` when non-empty
+- Method returns `[]string{ListenAddr}` when `ListenAddrs` is empty but `ListenAddr` is set
+- Method returns default TCP+QUIC addresses when both are empty
+- `go build ./...` succeeds
+</acceptance_criteria>
+
+<verify>
+```bash
+go build ./...
+```
+</verify>
+
+</tasks>
+
+<verification>
+1. `go build ./...` — compiles without errors
+2. `go vet ./internal/config/...` — no vet issues
+3. Config struct has 4 new fields visible in source
+4. DefaultConfig() includes QUIC listen address
+</verification>
+
+<success_criteria>
+- Config struct has `ListenAddrs`, `EnableHolePunching`, `EnableRelayService`, `RelayServers` fields
+- `GetListenAddrs()` provides backward compatibility for existing single-address configs
+- Default config includes both TCP and QUIC v1 listen addresses
+- No breaking changes to existing config loading
+</success_criteria>
+
+<must_haves>
+- QUIC listen address in default config (D-01, D-02)
+- ListenAddrs array replacing single ListenAddr (D-03)
+- TCP kept alongside QUIC (D-04)
+- NAT config booleans (D-06, D-07, D-10)
+- Backward compatibility for existing config files
+</must_haves>