fix: Action TOKEN
This commit is contained in:
datadunia
@@ -1,104 +1,116 @@
|
|||||||
# WireGuard Policy Firewall + WGRplane (`03.wireguard-policy`)
|
# AGENTS.md -- WireGuard Policy Firewall + WGRplane
|
||||||
|
|
||||||
This repository contains two components:
|
**Generated:** 2026-05-08
|
||||||
1. **WireGuard Policy Firewall** - Shell script-based dynamic iptables/ipset policy engine
|
**Project:** 03.wireguard-policy
|
||||||
2. **WGRplane** - Go-native control plane with Vue 3 frontend
|
|
||||||
|
|
||||||
---
|
## OVERVIEW
|
||||||
|
Hybrid project: (1) WireGuard Policy Firewall -- shell script iptables/ipset engine driven by `wg0.conf` `#Access` comments. (2) WGRplane -- Go binary (port 10087) serving REST API + Vue 3 SPA for WireGuard control plane management.
|
||||||
|
|
||||||
## Component 1: WireGuard Policy Firewall
|
## STRUCTURE
|
||||||
|
```
|
||||||
|
03.wireguard-policy/
|
||||||
|
├── app/ # WGRplane: Go backend + Vue 3 frontend (see app/AGENTS.md)
|
||||||
|
│ ├── *.go # 13 Go files, flat package (no subdirs)
|
||||||
|
│ ├── frontend/ # Vue 3 SPA (see app/frontend/src/AGENTS.md)
|
||||||
|
│ └── docs/ # Swagger auto-generated (DO NOT EDIT)
|
||||||
|
├── wg-sync-policy.sh # Parses wg0.conf → policy.json (atomic write + flock)
|
||||||
|
├── wg-policy-engine.sh # Reads policy.json → iptables/ipset WG_POLICY chain
|
||||||
|
├── wg-sync-watch.sh # inotifywait daemon, debounces wg0.conf changes
|
||||||
|
├── wg-policy-lib.sh # Shared shell library (source only, never execute directly)
|
||||||
|
├── wg-policy-ctl # CLI wrapper for operator use
|
||||||
|
├── wg-policy-cleanup.sh # PostDown cleanup (run by WireGuard)
|
||||||
|
├── *.service / *.timer # systemd units for daemon + health check
|
||||||
|
├── install.sh # Unified installer (embeds all scripts, built by build.sh)
|
||||||
|
├── build.sh / build.bat # Rebuilds install.sh from source scripts
|
||||||
|
├── Dockerfile # Multi-stage: Go build + frontend build
|
||||||
|
└── README.md # Full user documentation
|
||||||
|
```
|
||||||
|
|
||||||
## Architecture & Configuration Flow
|
## WHERE TO LOOK
|
||||||
- **Goal:** Dynamic iptables/ipset rules based on WireGuard configuration (`wg0.conf`).
|
| Task | Location |
|
||||||
- **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.
|
| Policy firewall logic | `wg-sync-policy.sh`, `wg-policy-engine.sh`, `wg-policy-lib.sh` |
|
||||||
|
| Firewall rule chain | `wg-policy-engine.sh` -- WG_POLICY iptables chain |
|
||||||
|
| Policy JSON schema | `wg-sync-policy.sh` output / `wg-policy-engine.sh` input |
|
||||||
|
| WGRplane API handlers | `app/handlers.go` |
|
||||||
|
| WGRplane DB models | `app/models.go` |
|
||||||
|
| Auth middleware | `app/auth.go` (CAUTION: see known issues) |
|
||||||
|
| nftables rules (forward mode) | `app/nftables.go` |
|
||||||
|
| Webhook delivery | `app/webhook.go` |
|
||||||
|
| Vue frontend | `app/frontend/src/` |
|
||||||
|
| i18n translations | `app/frontend/src/i18n/locales/` (en, id, zh) |
|
||||||
|
| Backend i18n | `app/active.{en,id,zh}.json` |
|
||||||
|
| Systemd service config | `wg-policy.service`, `wgrplane.service` |
|
||||||
|
|
||||||
## Critical Parsing Rules & Design Constraints
|
## CRITICAL DESIGN RULES
|
||||||
- **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
|
### Policy Firewall -- `#Access` MUST NOT be changed
|
||||||
- `wg-policy-ctl status`: Check the overall health, including interface status, JSON validity, lock files, and iptables rules counts.
|
- WireGuard `AllowedIPs` on the server side = Cryptokey Routing, not firewall whitelist
|
||||||
- `wg-policy-ctl validate`: Validates `policy.json` without applying.
|
- Putting destination IPs in server's `AllowedIPs` breaks routing (WG tunnels those packets INTO client)
|
||||||
- `wg-policy-ctl rules`: View the applied iptables rules in the active chain (`WG_POLICY`).
|
- `#Access` comment is the ONLY correct way to declare firewall destinations per-peer
|
||||||
- `wg-policy-ctl reload`: Forces a re-sync from `wg0.conf` and re-applies iptables.
|
- **NEVER refactor to parse targets from `AllowedIPs`** -- architecturally incorrect
|
||||||
|
|
||||||
## Script Constraints & Gotchas
|
### Atomic Writes
|
||||||
- **Atomic Operations:** Always use atomic writes (`mv -f tmp target`) for `policy.json` to prevent the policy engine from reading partial files.
|
- Always `mv -f tmp target` for `policy.json` -- never write directly
|
||||||
- **Locking:** `wg-sync-policy.sh` uses file-based locking (`flock`) to prevent race conditions during updates.
|
- `wg-sync-policy.sh` uses `flock` -- never bypass locking
|
||||||
- **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
|
### Rollback
|
||||||
- Restart the watcher service: `systemctl restart wg-policy.service`
|
- `wg-policy-engine.sh` creates `WG_POLICY_BAK` chain; traps `ERR` for rollback
|
||||||
- Check service logs: `journalctl -u wg-policy.service -f`
|
|
||||||
|
|
||||||
---
|
### No SaveConfig
|
||||||
|
- WireGuard `SaveConfig = true` strips ALL comments including `#Access` -- NEVER enable
|
||||||
|
|
||||||
## Component 2: WGRplane (Go App in `/app`)
|
## KNOWN ISSUES / GOTCHAS
|
||||||
|
- **AuthMiddleware NOT applied**: `auth.go` defines `AuthMiddleware` but it is NOT wired to any routes in `main.go`. All API endpoints currently unprotected (auth header still checked inside handlers via manual if-check, but middleware chain is absent).
|
||||||
|
- **TOTP secrets in-memory**: `totpSecrets` map in `auth.go` is not persisted; lost on restart.
|
||||||
|
- **WebSocket stats are MOCK**: `stats.go` broadcasts randomly generated numbers, not real WireGuard traffic.
|
||||||
|
- **Plugin system is stub**: `plugins.go` TelegramNotifier/SlackNotifier just print to stdout.
|
||||||
|
- **Binary + DB in app/**: `wgrplane` binary and `wgrplane.db` live in `app/` (non-standard, intentional).
|
||||||
|
- **Duplicate i18n**: `app/active.*.json` (backend i18n) and `app/frontend/src/i18n/locales/` (frontend i18n) are separate systems.
|
||||||
|
|
||||||
## Architecture Overview
|
## ANTI-PATTERNS
|
||||||
WGRplane is a Go-native WireGuard control plane application with a Vue 3 frontend, providing a modern web dashboard for WireGuard management.
|
- Never parse firewall targets from `AllowedIPs` -- use `#Access` only
|
||||||
|
- Never write `policy.json` without atomic mv + flock
|
||||||
|
- Never run `wg-policy-lib.sh` directly (source-only library)
|
||||||
|
- Never enable `SaveConfig = true` in wg0.conf
|
||||||
|
- Do NOT edit `app/docs/docs.go` -- auto-generated by swaggo
|
||||||
|
- Do NOT put business logic in `app/main.go` -- it's bootstrap only
|
||||||
|
|
||||||
- **Single Binary:** The Go binary (`app/main.go`) serves both the REST API (port 10087) and the built Vue frontend from `app/frontend/dist/`.
|
## COMMANDS
|
||||||
- **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
|
### Policy Firewall
|
||||||
- `app/main.go` - Bootstrap server, routing, init DB
|
```bash
|
||||||
- `app/handlers.go` - REST API route handlers
|
wg-policy-ctl status # Health: interface, JSON validity, rule counts
|
||||||
- `app/models.go` - GORM models (Server, Peer, Webhook, SMTP)
|
wg-policy-ctl validate # Validate policy.json without applying
|
||||||
- `app/auth.go` - JWT, TOTP, API key auth middleware
|
wg-policy-ctl rules # Show active WG_POLICY iptables rules
|
||||||
- `app/nftables.go` - nftables rule management (mode forward)
|
wg-policy-ctl reload # Force re-sync from wg0.conf + re-apply
|
||||||
- `app/webhook.go` - Webhook engine with retry/backoff
|
wg-policy-ctl policy # Show raw policy.json
|
||||||
- `app/scheduler.go` - Cron jobs (expiry, data limit, reset)
|
wg-policy-ctl log # Show dropped packet logs (rate-limited)
|
||||||
- `app/stats.go` - WebSocket Hub for real-time stats
|
systemctl restart wg-policy.service
|
||||||
- `app/frontend/` - Vue 3 SPA (TypeScript, TailwindCSS 4)
|
journalctl -u wg-policy.service -f
|
||||||
|
```
|
||||||
|
|
||||||
## Tech Stack
|
### WGRplane (Go App)
|
||||||
| Component | Technology |
|
```bash
|
||||||
|-----------|------------|
|
cd app && go build -o ../wgrplane . # Build Go binary
|
||||||
| **Backend** | Go, Gorilla Mux, GORM (SQLite via glebarez/sqlite) |
|
cd app/frontend && npm install && npm run build # Build Vue frontend
|
||||||
| **Frontend** | Vue 3, TypeScript, Vite, TailwindCSS 4, vue-i18n 9 |
|
./wgrplane # Run (serves :10087)
|
||||||
| **Auth** | JWT (golang-jwt/v5), TOTP (pquerna/otp), API Key |
|
systemctl restart wgrplane.service
|
||||||
| **WebSockets** | gorilla/websocket |
|
journalctl -u wgrplane.service -f
|
||||||
| **Webhooks** | Go net/http with retry + exponential backoff |
|
curl -H "wg-rplane-datadunia: test-api-key" http://localhost:10087/api/servers
|
||||||
| **Scheduling** | robfig/cron v3 |
|
```
|
||||||
| **QR Code** | skip2/go-qrcode |
|
|
||||||
| **Email** | jordan-wright/email (SMTP) |
|
|
||||||
|
|
||||||
## Authentication Methods
|
### Installer
|
||||||
WGRplane supports three authentication methods:
|
```bash
|
||||||
|
./build.sh # Rebuild install.sh from source scripts (Linux)
|
||||||
|
./build.bat # Rebuild install.sh from source scripts (Windows)
|
||||||
|
sudo ./install.sh install # Full install (deps + scripts + systemd + service)
|
||||||
|
sudo ./install.sh uninstall # Remove all
|
||||||
|
```
|
||||||
|
|
||||||
| Method | Header | Notes |
|
## DEPENDENCIES
|
||||||
|--------|--------|-------|
|
- Shell: `jq`, `inotify-tools` (required); `ipset` (optional, O(1) lookup)
|
||||||
| API Key | `wg-rplane-datadunia: <KEY>` | Set via env var `WG_API_KEY`. Default: `test-api-key` |
|
- Go: 1.25.1, SQLite (glebarez/sqlite), Gorilla Mux, GORM, JWT, TOTP, WebSocket
|
||||||
| JWT | `Authorization: Bearer <TOKEN>` | Expires in 15 minutes. Secret via env var `JWT_SECRET` |
|
- Frontend: Vue 3, TypeScript, Vite, TailwindCSS 4, vue-i18n 9
|
||||||
| TOTP | `X-TOTP: <CODE>` | Required if user enables TOTP |
|
- Auth headers: `wg-rplane-datadunia: <KEY>` (API key) | `Authorization: Bearer <JWT>` | `X-TOTP: <CODE>`
|
||||||
|
- Env vars: `WG_API_KEY` (default: test-api-key), `JWT_SECRET`, `WG_RPLANE_MODE` (forward|standalone), `APP_FRONTEND_DIR`
|
||||||
## 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.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user