wireguard-vpn/AGENTS.md

WireGuard Policy Firewall + WGRplane (03.wireguard-policy)

This repository contains two components:

1. WireGuard Policy Firewall - Shell script-based dynamic iptables/ipset policy engine
2. WGRplane - Go-native control plane with Vue 3 frontend

---

Component 1: WireGuard Policy Firewall

Architecture & Configuration Flow

• Goal: Dynamic iptables/ipset rules based on WireGuard configuration (wg0.conf).
• Data Flow: wg0.conf -> wg-sync-policy.sh -> policy.json -> wg-policy-engine.sh -> iptables/ipset
• File Watcher: wg-sync-watch.sh monitors wg0.conf via inotifywait and debounces changes to re-run the sync and engine.

Critical Parsing Rules & Design Constraints

• Target IPs Parsing (#Access): The firewall script uses the custom #Access comment in wg0.conf to define egress/firewall whitelists for clients.
• Why #Access is mandatory: WireGuard's native AllowedIPs on a Server dictates routing towards the client. If we put target destinations in the Server's AllowedIPs, the Server would wrongly route traffic destined for those IPs into the client tunnel. Therefore, a custom #Access comment is the only correct way to define firewall whitelist destinations without breaking WireGuard's Cryptokey Routing.
• Do not remove #Access: Future agents MUST NOT attempt to refactor the script to parse targets from AllowedIPs. It is architecturally incorrect for this use case.

Testing & Verifying

• wg-policy-ctl status: Check the overall health, including interface status, JSON validity, lock files, and iptables rules counts.
• wg-policy-ctl validate: Validates policy.json without applying.
• wg-policy-ctl rules: View the applied iptables rules in the active chain (WG_POLICY).
• wg-policy-ctl reload: Forces a re-sync from wg0.conf and re-applies iptables.

Script Constraints & Gotchas

• Atomic Operations: Always use atomic writes (mv -f tmp target) for policy.json to prevent the policy engine from reading partial files.
• Locking: wg-sync-policy.sh uses file-based locking (flock) to prevent race conditions during updates.
• Rollback: wg-policy-engine.sh creates a backup chain (WG_POLICY_BAK) and uses a trap on ERR to rollback if applying rules fails halfway.
• Dependencies: Requires jq and inotify-tools.

Development Commands

• Restart the watcher service: systemctl restart wg-policy.service
• Check service logs: journalctl -u wg-policy.service -f

---

Component 2: WGRplane (Go App in /app)

Architecture Overview

WGRplane is a Go-native WireGuard control plane application with a Vue 3 frontend, providing a modern web dashboard for WireGuard management.

• Single Binary: The Go binary (app/main.go) serves both the REST API (port 10087) and the built Vue frontend from app/frontend/dist/.
• Hybrid Mode:
  • forward - Directly applies nftables rules on the local machine
  • standalone - Acts as a control plane that triggers webhooks to remote WireGuard servers
• 2-Column Policy: Each peer has AllowAccess (CIDR whitelist) and AllowInternet (boolean toggle)

Key File Locations

• app/main.go - Bootstrap server, routing, init DB
• app/handlers.go - REST API route handlers
• app/models.go - GORM models (Server, Peer, Webhook, SMTP)
• app/auth.go - JWT, TOTP, API key auth middleware
• app/nftables.go - nftables rule management (mode forward)
• app/webhook.go - Webhook engine with retry/backoff
• app/scheduler.go - Cron jobs (expiry, data limit, reset)
• app/stats.go - WebSocket Hub for real-time stats
• app/frontend/ - Vue 3 SPA (TypeScript, TailwindCSS 4)

Tech Stack

Component	Technology
Backend	Go, Gorilla Mux, GORM (SQLite via glebarez/sqlite)
Frontend	Vue 3, TypeScript, Vite, TailwindCSS 4, vue-i18n 9
Auth	JWT (golang-jwt/v5), TOTP (pquerna/otp), API Key
WebSockets	gorilla/websocket
Webhooks	Go net/http with retry + exponential backoff
Scheduling	robfig/cron v3
QR Code	skip2/go-qrcode
Email	jordan-wright/email (SMTP)

Authentication Methods

WGRplane supports three authentication methods:

Method	Header	Notes
API Key	wg-rplane-datadunia: <KEY>	Set via env var WG_API_KEY. Default: test-api-key
JWT	Authorization: Bearer <TOKEN>	Expires in 15 minutes. Secret via env var JWT_SECRET
TOTP	X-TOTP: <CODE>	Required if user enables TOTP

Development Commands

• Build Go binary: cd app && go build -o ../wgrplane .
• Build frontend: cd app/frontend && npm install && npm run build
• Run locally: ./wgrplane (serves on http://localhost:10087)
• Restart service: systemctl restart wgrplane.service
• Check service logs: journalctl -u wgrplane.service -f

Testing & Verifying

• Test auth (no header): curl http://localhost:10087/api/servers (expect 401)
• Test auth (correct): curl -H "wg-rplane-datadunia: test-api-key" http://localhost:10087/api/servers
• View Swagger docs: Visit http://localhost:10087/swagger/
• WebSocket test: Connect to ws://localhost:10087/ws/stats

References

• For detailed WGRplane documentation: See app/README.md
• For WGRplane-specific AI agent guidance: See app/AGENTS.md

---

Notes for AI Agents

• The .sisyphus/ directory contains planning artifacts and may be cleaned up after plan completion.
• When working on Policy Firewall scripts, always preserve #Access comment parsing logic.
• When working on WGRplane, remember it's a single binary serving both API and frontend on port 10087.