Nexus-Guard-Suite/.omo/plans/archive/multi-interface-refactor.md

# 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