diff --git a/GO_TUI_PLAN.md b/GO_TUI_PLAN.md new file mode 100644 index 0000000..7693070 --- /dev/null +++ b/GO_TUI_PLAN.md @@ -0,0 +1,543 @@ +# WireGuard Client Manager - Go TUI Implementation Plan + +## Executive Summary + +Converting the bash-based `wg-client-manager` to a modern, responsive Go TUI application using Bubble Tea and the Charm ecosystem. This will provide a better user experience with interactive forms, real-time status updates, and intuitive navigation. + +## Technology Stack + +### Core Framework +- **bubbletea** (v1.3.10) - Elm-architecture TUI framework +- **lipgloss** - Expressive styling and theming + +### Component Libraries +- **huh** - Terminal forms for client creation +- **bubble-table** - Interactive table for client list +- **bubbles** - Text input and other UI components +- **qrterminal** - QR code generation for terminal display + +### Go Modules +- WireGuard Go library (if available) or exec-based wrapper +- Configuration management (Viper or native config) +- File system operations (os, path/filepath) + +## Functional Requirements Analysis + +### Commands to Implement + +| Command | Current Behavior | TUI Implementation | +|---------|-----------------|-------------------| +| **add** | Interactive prompts or WGI_ env vars | Form modal with fields: name, DNS, PSK option | +| **remove** | Command-line with confirmation | Select from list → Confirm modal → Delete | +| **list** | Table view with status | Interactive table with sorting, filtering | +| **show** | Display client config | Detail view with copyable sections | +| **qr** | Display QR code | Inline QR code in modal | + +### Key Features + +#### 1. Client Management +- **Add client** + - Name input (regex validation: `[a-zA-Z0-9_-]+`, max 64 chars) + - Optional DNS configuration + - PSK toggle (yes/no) + - Auto-assign IPv4/IPv6 addresses + - Generate client keys + - Create server and client configs + - Generate QR code + +- **Remove client** + - Select from list + - Confirmation dialog + - Remove config files + - Reload WireGuard + +- **List clients** + - Table view: Name, IPv4, IPv6, Status (Connected/Disconnected) + - Sorting by column + - Filtering/search + - Real-time status refresh + +- **Show client details** + - Full configuration display + - Copy to clipboard functionality + - Status information (last handshake, transfer stats) + +- **QR code display** + - ANSI-colored QR code in terminal + - Toggle fullscreen/inline mode + +#### 2. Configuration Loading +- Read `/etc/wg-admin/config.conf` +- Environment variable support +- Validation of required settings (SERVER_DOMAIN, WG_PORT, etc.) + +#### 3. Validation +- Client name format +- IP availability checks +- DNS server format validation +- Pre-install checks (WireGuard installed, config exists) + +#### 4. Security +- Run as root required +- Proper file permissions (0600 for keys) +- Atomic config writes +- Temporary key cleanup + +#### 5. Backup & Recovery +- Auto-backup before add/remove +- Config backup/restore functionality + +## Architecture Design + +### Package Structure + +``` +wg-admin-tui/ +├── cmd/ +│ └── main.go # Entry point +├── internal/ +│ ├── config/ +│ │ ├── config.go # Configuration loading +│ │ └── defaults.go # Default values +│ ├── wireguard/ +│ │ ├── client.go # Client management +│ │ ├── keys.go # Key generation +│ │ ├── config.go # WireGuard config parsing +│ │ └── status.go # Status monitoring +│ ├── tui/ +│ │ ├── app.go # Main TUI application +│ │ ├── model.go # Application state +│ │ ├── update.go # Message handlers +│ │ ├── view.go # Rendering +│ │ ├── screens/ +│ │ │ ├── list.go # Client list view +│ │ │ ├── add.go # Add client form +│ │ │ ├── detail.go # Client detail view +│ │ │ └── qr.go # QR code view +│ │ ├── components/ +│ │ │ ├── table.go # Client table +│ │ │ ├── statusbar.go # Status bar +│ │ │ └── modal.go # Modal dialogs +│ │ └── theme/ +│ │ ├── colors.go # Color scheme +│ │ └── style.go # Styling utilities +│ ├── validation/ +│ │ ├── client.go # Client name validation +│ │ ├── network.go # IP/DNS validation +│ │ └── config.go # Config syntax validation +│ └── backup/ +│ ├── backup.go # Backup operations +│ └── restore.go # Restore operations +├── pkg/ +│ └── util/ +│ ├── exec.go # Command execution helpers +│ └── file.go # File operations +└── go.mod +``` + +### Component Design + +#### 1. Main Application (app.go) +```go +type Application struct { + model Model + programs *tea.Program + config *config.Config + wireguard *wireguard.Client +} + +func NewApplication() (*Application, error) +func (a *Application) Run() error +``` + +#### 2. Model (model.go) +```go +type Model struct { + screen Screen // Current active screen + clients []Client // Client data + selected int // Selected client + loading bool // Loading state + error error // Error message + table table.Model // Client table + form *huh.Form // Add client form + modal *Modal // Active modal + status Status // Status bar state +} + +type Screen interface { + Init() tea.Cmd + Update(msg tea.Msg) (Screen, tea.Cmd) + View() string +} +``` + +#### 3. Screens +- **ListScreen**: Display client table +- **AddScreen**: Form for adding client +- **DetailScreen**: Show client configuration +- **QRScreen**: Display QR code + +#### 4. WireGuard Integration +```go +type Client struct { + Name string + IPv4 string + IPv6 string + PublicKey string + HasPSK bool + Status ConnectionStatus + LastSeen time.Time + Handshake string + ConfigPath string +} + +type Manager interface { + ListClients() ([]Client, error) + AddClient(name, dns string, usePSK bool) (*Client, error) + RemoveClient(name string) error + GetClient(name string) (*Client, error) + GetStatus() (Status, error) + ReloadConfig() error +} +``` + +## Implementation Roadmap + +### Phase 1: Project Setup & Foundation (Days 1-2) + +**Goal**: Establish project structure and core framework + +**Tasks**: +- [ ] Initialize Go module +- [ ] Set up project structure +- [ ] Add dependencies (bubbletea, lipgloss, huh, bubble-table, qrterminal) +- [ ] Create configuration loading from `/etc/wg-admin/config.conf` +- [ ] Implement root check +- [ ] Create basic TUI skeleton with empty screens +- [ ] Set up logging (both file and console) + +**Deliverables**: +- Working TUI that launches and shows a placeholder screen +- Configuration system in place + +### Phase 2: Client List View (Days 3-4) + +**Goal**: Display clients in interactive table + +**Tasks**: +- [ ] Implement WireGuard client list parsing +- [ ] Create `Client` struct +- [ ] Set up bubble-table with columns: Name, IPv4, IPv6, Status +- [ ] Parse client configs from `/etc/wireguard/conf.d/client-*.conf` +- [ ] Check connection status using `wg show` +- [ ] Implement keyboard navigation (j/k, arrows, Enter, q) +- [ ] Add status bar with help text +- [ ] Implement auto-refresh (every 30 seconds) + +**Deliverables**: +- Functional client list with real-time status + +### Phase 3: Add Client Form (Days 5-6) + +**Goal**: Create interactive form for adding clients + +**Tasks**: +- [ ] Create add screen with `huh` form +- [ ] Implement fields: + - Client name (text input) + - DNS servers (text input with default) + - Use PSK (toggle/confirm) +- [ ] Add validation: + - Client name regex + - IP availability check + - DNS format validation +- [ ] Implement WireGuard key generation +- [ ] Auto-assign IPv4/IPv6 addresses +- [ ] Create server config file +- [ ] Create client config file +- [ ] Generate QR code +- [ ] Implement atomic config writes +- [ ] Auto-backup before add +- [ ] Reload WireGuard config + +**Deliverables**: +- Working add client form with all validations + +### Phase 4: Client Detail View (Days 7-8) + +**Goal**: Show full client configuration + +**Tasks**: +- [ ] Create detail screen +- [ ] Display: + - Client name + - IP addresses + - Public key + - Full configuration + - Connection status + - Last handshake + - Transfer stats (Rx/Tx) +- [ ] Implement copy to clipboard +- [ ] Add "Back" and "Delete" buttons +- [ ] Delete confirmation modal +- [ ] Remove client with config deletion +- [ ] Auto-backup before remove +- [ ] Reload WireGuard config + +**Deliverables**: +- Functional detail view with delete capability + +### Phase 5: QR Code Display (Days 9-10) + +**Goal**: Display QR codes for mobile setup + +**Tasks**: +- [ ] Create QR screen +- [ ] Read client config +- [ ] Generate QR code using `qrterminal` +- [ ] Display QR code inline +- [ ] Implement fullscreen QR mode +- [ ] Add resize handling for QR codes +- [ ] Test with various terminal sizes + +**Deliverables**: +- Working QR code display + +### Phase 6: Polish & UX Improvements (Days 11-12) + +**Goal**: Improve user experience + +**Tasks**: +- [ ] Add color themes +- [ ] Implement modal dialogs for confirmations +- [ ] Add toast notifications for success/error +- [ ] Implement search/filter clients +- [ ] Add sorting by columns +- [ ] Improve error messages with actionable guidance +- [ ] Add keyboard shortcuts help +- [ ] Implement loading indicators + +**Deliverables**: +- Polished, user-friendly interface + +### Phase 7: Backup & Recovery (Days 13-14) + +**Goal**: Add backup and restore functionality + +**Tasks**: +- [ ] Implement backup operations +- [ ] Create restore functionality +- [ ] Add backup history view +- [ ] Implement retention policy +- [ ] Add backup/restore screens + +**Deliverables**: +- Complete backup/restore system + +## User Experience Design + +### Screen Flow + +``` +┌─────────────────────────────────────┐ +│ Client List (Main) │ +│ ┌─────┬─────┬──────────┬─────────┐│ +│ │Name │IPv4 │ IPv6 │ Status ││ +│ ├─────┼─────┼──────────┼─────────┤│ +│ │laptop│ .2 │ ::2 │Connected││ ← Selected +│ │phone │ .3 │ ::3 │ Disc ││ +│ └─────┴─────┴──────────┴─────────┘│ +│ │ +│ [a] Add [d] Detail [?] Help [q] Quit│ +└─────────────────────────────────────┘ + ↓ Enter +┌─────────────────────────────────────┐ +│ Client Detail: laptop │ +│ │ +│ Name: laptop │ +│ IPv4: 10.10.69.2 │ +│ IPv6: fd69:dead:beef:69::2 │ +│ Status: Connected │ +│ Last Handshake: 2m ago │ +│ Rx: 1.2 MB Tx: 3.4 MB │ +│ │ +│ [Interface] │ +│ PrivateKey = ... │ +│ Address = 10.10.69.2/24... │ +│ │ +│ [ESC] Back [x] Delete [c] Copy │ +└─────────────────────────────────────┘ + ↓ 'a' from list +┌─────────────────────────────────────┐ +│ Add New Client │ +│ │ +│ Client Name: [_________] │ +│ DNS Servers: [8.8.8.8, 8.8.4.4] │ +│ Use PSK? [x] Yes │ +│ │ +│ [Enter] Submit [ESC] Cancel │ +└─────────────────────────────────────┘ + ↓ 'q' from detail +┌─────────────────────────────────────┐ +│ Delete Confirmation │ +│ │ +│ Delete client 'laptop'? │ +│ │ +│ [Enter] Yes [ESC] No │ +└─────────────────────────────────────┘ +``` + +### Keyboard Shortcuts + +| Key | Action | +|-----|--------| +| `q` | Quit | +| `a` | Add client | +| `d` | Show details | +| `x` | Delete | +| `r` | Refresh | +| `/` | Search/filter | +| `↑/k` | Move up | +| `↓/j` | Move down | +| `Enter` | Select/Confirm | +| `Esc` | Back/Cancel | +| `?` | Help | +| `c` | Copy to clipboard | + +### Color Scheme + +```go +// Default theme +const ( + ColorPrimary lipgloss.Color + ColorSecondary lipgloss.Color + ColorSuccess lipgloss.Color + ColorWarning lipgloss.Color + ColorError lipgloss.Color + ColorMuted lipgloss.Color +) + +// Example +ColorPrimary = lipgloss.Color("#007AFF") // Blue +ColorSuccess = lipgloss.Color("#34C759") // Green +ColorWarning = lipgloss.Color("#FF9500") // Orange +ColorError = lipgloss.Color("#FF3B30") // Red +ColorMuted = lipgloss.Color("#8E8E93") // Gray +``` + +## Error Handling Strategy + +### Validation Errors +- Display inline validation messages +- Show specific error with action guidance +- Keep form state on error +- Highlight invalid fields + +### System Errors +- Show modal with error message +- Log full error to file +- Provide actionable guidance +- Offer retry or cancel options + +### Examples +``` +ERROR: Client 'laptop' already exists +Action: Choose a different name or remove existing client first + +ERROR: No available IPv4 addresses +Action: Remove unused clients or expand VPN range +``` + +## Performance Considerations + +1. **Lazy Loading** + - Load clients on screen init + - Cache client data between refreshes + +2. **Asynchronous Operations** + - Run WireGuard status checks in background + - Use tea.Cmd for async operations + +3. **Throttled Refresh** + - Auto-refresh every 30 seconds (configurable) + - Manual refresh with 'r' key + +4. **QR Code Optimization** + - Generate on demand, not cached + - Use appropriate error correction level + +## Security Considerations + +1. **Root Privileges** + - Check for root at startup + - Display clear error if not root + +2. **Key Storage** + - Write keys with 0600 permissions + - Clean up temporary key files + +3. **Atomic Operations** + - Write to temp file, then move + - Prevent config corruption + +4. **Input Validation** + - Strict regex for client names + - IP availability checks + - DNS format validation + +## Testing Strategy + +### Unit Tests +- Validation functions +- Configuration parsing +- Client model methods + +### Integration Tests +- WireGuard config generation +- Key generation +- Backup/restore + +### Manual Testing +- End-to-end workflows +- Terminal size handling +- Error scenarios + +## Milestones + +| Milestone | Days | Goal | +|-----------|------|------| +| M1: Foundation | 2 | Project setup, basic TUI | +| M2: List View | 4 | Client list with status | +| M3: Add Client | 6 | Working add form | +| M4: Detail & Delete | 8 | Full client management | +| M5: QR Codes | 10 | QR code display | +| M6: Polish | 12 | UX improvements | +| M7: Complete | 14 | Fully functional TUI | + +## Success Criteria + +- ✅ All bash functionality replicated in TUI +- ✅ Responsive and performant UI +- ✅ Clear error messages with actionable guidance +- ✅ Keyboard shortcuts for all actions +- ✅ Real-time client status updates +- ✅ Working QR code generation +- ✅ Backup/restore functionality +- ✅ Polished, intuitive user experience + +## Future Enhancements + +- Config import/export +- Client statistics dashboard +- Connection monitoring view +- Multiple server support +- Template-based client creation +- Bulk operations +- Dark/Light theme toggle + +--- + +**Estimated Timeline**: 14 days for MVP +**Primary Dependencies**: bubbletea, lipgloss, huh, bubble-table, qrterminal +**Minimum Go Version**: 1.21+ +**Target Terminal**: ANSI-compatible terminals (Linux, macOS, Windows with WSL)