docs: update AGENTS.md, archive plans

2026-06-07 06:14:46 +07:00
parent c2f0e53f1d
commit 281ac48d28
10 changed files with 512 additions and 6 deletions
@@ -0,0 +1,118 @@
+# Multi-Interface Refactor
+## TL;DR
+
+> **Objective**: Refactor NexusGuard from single WireGuard interface to multi-interface per WgServer.
+## Context
+
+**Original Request**: User wants firewall bug fixed + multi-node isolation like wgdashboard where each node has configurable wg_isolation and NAT interface.
+**Interview Summary**:
+- Default deny all for client<->client, allow server->client default
+- Isolation configurable per node via UI checkbox
+- NAT interface (eth0/eth1/ens5) configurable per node
+- Current architecture only supports 1 local interface (wg0)
+
+**Research Findings**:
+- WgManager hardcoded to wg0 (wgmanager_linux.go:25)
+- Firewall InitNetwork() runs once globally for single subnet
+- NAT uses auto-detected default route interface
+- WgServer model lacks InterfaceName, IsLocal, PeerIsolation, NatInterface fields
+
+---
+
+## Work Objectives
+
+**Core Objective**: Enable multiple local WireGuard interfaces, each with independent subnet, firewall isolation, and NAT egress interface.
+
+**Concrete Deliverables**:
+1. Database migration adding 4 fields to wg_servers table
+2. WgManager supporting multiple interfaces by name
+3. Firewall manager with per-interface chains (forward_wgX, input_wgX)
+4. Startup initialization loop for all IsLocal=true servers
+5. API handlers using server context for all operations
+6. Cleanup of hardcoded Local Primary Node references
+
+**Definition of Done**:
+- [ ] Migration runs: ALTER TABLE wg_servers ADD COLUMN ...
+- [ ] wg0, wg1, wg2 interfaces can run simultaneously
+- [ ] Each interface has independent peer isolation (configurable)
+- [ ] Each interface uses configured NAT interface for masquerade
+- [ ] Firewall rules scoped to correct interface chain
+- [ ] Peer sync works per server (WgServerID filter)
+- [ ] All existing tests pass
+- [ ] Manual QA: 2+ local nodes with different subnets/NAT interfaces
+
+**Must Have**:
+- Backward compatible: existing single-node deployments work unchanged
+- Default values: InterfaceName=wg0, IsLocal=false, PeerIsolation=true, NatInterface= (auto)
+
+**Must NOT Have** (Guardrails):
+- NO breaking changes to external node provisioning
+- NO nft flush table - only atomic add/remove
+- NO hardcoded interface names in firewall code
+- NO cross-interface peer leakage
+
+---
+
+## Verification Strategy
+
+**Test Decision**:
+- Infrastructure exists: YES (Go test with -tags dev, GORM AutoMigrate)
+- Automated tests: Tests-after (add tests for new multi-interface logic)
+- Framework: Go testing (standard library)
+
+**QA Policy**: Every task includes agent-executed QA scenarios.
+
+| Domain | Tool | Evidence Pattern |
+|--------|------|------------------|
+| Go unit/integration | go test -tags dev ./... | .sisyphus/evidence/task-{N}-test.log |
+| nftables rules | bash (nft list) | .sisyphus/evidence/task-{N}-nftables.txt |
+| WireGuard interfaces | bash (ip link, wg show) | .sisyphus/evidence/task-{N}-wg.txt |
+| API endpoints | bash (curl) | .sisyphus/evidence/task-{N}-api.json |
+Wave 2 (Core Logic - 4 parallel):
+├── T5: LinuxWgManager multi-interface implementation [deep]
+├── T6: LinuxManager InitNetworkForServer + Teardown [deep]
+├── T7: NAT per-interface masquerade rules [unspecified-high]
+├── T8: Peer sync per-server (WgServerID filter) [unspecified-high]
+Wave 3 (Startup & Recovery - 3 parallel):
+├── T9: Main.go startup loop for all local servers [deep]
+├── T10: Firewall rules re-apply per server [unspecified-high]
+├── T11: Input rule (WG port) per server [quick]
+Wave 4 (API Handlers - 5 parallel):
+├── T12: servers.go Create/Update with multi-interface [quick]
+├── T13: peers.go device creation with server context [quick]
+├── T14: peer_sync.go SyncLocalPeers per server [quick]
+├── T15: rules.go syncRuleToFirewall per server [quick]
+├── T16: provisioning.go server-aware [quick]
+Wave 5 (Cleanup & Migration - 2 parallel):
+├── T17: Remove hardcoded Local Primary Node refs [quick]
+├── T18: Migration script + backfill defaults [quick]
+
+---
+
+## TODOs
+
+- [x] 1. Database Migration + Model Updates [quick]
+- [x] 2. WgManager Interface + Multi-Interface Struct [deep]
+- [x] 3. NetManager Interface + Per-Server Methods [deep]
+- [x] 4. nftables Chain-Per-Interface Scaffolding [quick]
+- [x] 5. LinuxWgManager Multi-Interface Implementation [deep]
+- [x] 6. LinuxManager InitNetworkForServer + Teardown [deep]
+- [x] 7. NAT Per-Interface Masquerade Rules [unspecified-high]
+- [x] 8. Peer Sync Per-Server (WgServerID Filter) [unspecified-high]
+- [x] 9. Main.go Startup Loop for All Local Servers [deep]
+- [x] 10. Firewall Rules Re-apply Per Server [unspecified-high]
+- [x] 11. Input Rule (WG Port) Per Server [quick]
+- [x] 12. servers.go Create/Update Multi-Interface [quick]
+- [x] 13. peers.go Device Creation with Server Context [quick]
+- [x] 14. peer_sync.go SyncLocalPeers Per Server [quick]
+- [x] 15. rules.go syncRuleToFirewall Per Server [quick]
+- [x] 16. provisioning.go Server-Aware [quick]
+- [x] 17. Remove Hardcoded Local Primary Node References [quick]
+- [x] 18. Migration Script + Backfill Defaults [quick]
+- [x] 19. Unit Tests for Multi-Interface Logic [unspecified-low]
+- [x] 20. Integration Test: 2 Local Nodes Different Subnets [unspecified-high]
+- [x] 21. Manual QA Checklist Execution [unspecified-high]
+- [x] F1. Plan Compliance Audit — oracle
+- [x] F2. Code Quality Review — unspecified-high
+- [x] F3. Real Manual QA — unspecified-high + playwright
+- [x] F4. Scope Fidelity Check — deep