wireguard-vpn/app/README.md

# WGRplane - WireGuard Remote Plane Control

**WGRplane** adalah aplikasi kontrol WireGuard Remote Plane yang dibangun dengan fitur lengkap (paritas penuh dengan **WGDashboard**) ditambah integrasi **policy.json API**.

---

## Fitur Utama

- **Peer Management**: CRUD peer, generate QR code, export config
- **Real-time Monitoring**: Status peer, grafik trafik, riwayat koneksi
- **Scheduling & Automation**: Jadwal penghapusan/restriksi peer, reset data usage
- **Security**: Autentikasi dashboard (username/password), TOTP (2FA), API key
- **Multi-Server**: Akses multi WGDashboard instance via API keys
- **Plugins System**: Ekspansi fitur via plugin (experimental)
- **i18n & Themes**: Multi-bahasa, dark/light mode

---

## Arsitektur

```
wg0.conf (dengan/tanpa #Access)
        ↓
wg-engine-api (Go) -- membaca API storage (api-policy.json)
        ↓                             ↓
        +-- GET /api/policy (merged: API + #Access fallback)
        +-- POST /api/policy (write ke api-policy.json, trigger sync)
        ↓
policy.json (merged: API overrides #Access)
        ↓
wg-policy-engine.sh (tidak diubah)
        ↓
iptables / ipset rules
```

### Tech Stack

| Komponen | Teknologi |
|-----------|------------|
| **WGRplane Backend** | Python + Flask |
| **WGRplane Frontend** | Vue.js 3 |
| **wg-engine-api** | Go (Golang) |
| **Database** | SQLite (default), PostgreSQL/MySQL via SQLAlchemy |
| **Desktop App** | ElectronJS + Vue.js |

---

## Port & Autentikasi

| Service | Port | Autentikasi |
|---------|------|---------------|
| WGRplane Dashboard | **10086** | Session-based + TOTP |
| wg-engine-api (Go) | **10087** | Custom header: `wg-rplane-datadunia` |

---

## API Endpoints (wg-engine-api)

### Autentikasi
Semua request harus menyertakan header:
```
wg-rplane-datadunia: <TOKEN>
```

### Endpoints

| Endpoint | Method | Deskripsi |
|----------|--------|-------------|
| `/api/policy` | GET | Ambil policy.json (merge: API + #Access fallback) |
| `/api/policy` | POST | Update policy (simpan ke api-policy.json, trigger sync) |
| `/api/reload` | POST | Trigger wg-policy-engine.sh untuk apply rules |

### Contoh Penggunaan

```bash
# Ambil policy
curl -H "wg-rplane-datadunia: VALID_TOKEN" http://localhost:10087/api/policy

# Update policy untuk client
curl -X POST \
  -H "Content-Type: application/json" \
  -H "wg-rplane-datadunia: VALID_TOKEN" \
  -d '{"ip": "10.0.0.2", "access": ["1.1.1.1/32"], "internet": true}' \
  http://localhost:10087/api/policy

# Trigger reload
curl -X POST \
  -H "wg-rplane-datadunia: VALID_TOKEN" \
  http://localhost:10087/api/reload
```

---

## Migration: #Access ke API

| Aspek | Detail |
|-------|--------|
| **Strategi** | API with #Access fallback (API dicoba pertama, fallback ke #Access) |
| **Precedence** | API policy OVERRIDE #Access untuk IP client yang sama |
| **Storage API** | `/etc/wireguard/api-policy.json` (terpisah dari policy.json) |
| **Locking** | Menggunakan `/var/lock/wg-policy.lock` (SAMA dengan script shell) |
| **Atomic Write** | Tulis ke tmp file → `mv` (mencegah corrupt saat crash) |

---

## Instalasi

### Prerequisites

```bash
# Python dependencies (WGRplane)
pip install -r requirements.txt

# Go dependencies (wg-engine-api)
cd wg-engine-api
go mod download
```

### Jalankan WGRplane (Python/Flask)

```bash
python app.py
# atau dengan Gunicorn
gunicorn -w 4 -b 0.0.0.0:10086 app:app
```

### Jalankan wg-engine-api (Go)

```bash
cd wg-engine-api
go build -o wg-engine-api .
./wg-engine-api &
# atau install ke /usr/local/bin/
cp wg-engine-api /usr/local/bin/
```

---

## Testing

### Bats (Shell Scripts)

```bash
apt install bats
bats /tests/policy.bats
```

### Go Tests (wg-engine-api)

```bash
cd wg-engine-api
go test ./...
```

### Manual QA

```bash
# Test auth
curl -H "wg-rplane-datadunia: wrong" http://localhost:10087/api/policy
# Expected: 401 Unauthorized

# Test policy retrieval
curl -H "wg-rplane-datadunia: VALID_TOKEN" http://localhost:10087/api/policy

# Test policy update
curl -X POST -H "Content-Type: application/json" \
  -H "wg-rplane-datadunia: VALID_TOKEN" \
  -d '{"ip": "10.0.0.2", "access": ["1.1.1.1/32"]}' \
  http://localhost:10087/api/policy

# Verify iptables rules
wg-policy-ctl rules
```

---

## Deployment

### Systemd Services

WGRplane menggunakan systemd untuk manajemen service:

```bash
# Copy systemd units
cp wg-policy.service wg-policy-health.timer wg-policy-health.service /etc/systemd/system/

# Enable & start
systemctl daemon-reload
systemctl enable wg-policy.service
systemctl enable wg-policy-health.timer
systemctl start wg-policy.service
systemctl start wg-policy-health.timer
```

### Install Script

Gunakan `install.sh` untuk instalasi otomatis:

```bash
sudo ./install.sh install
```

---

## Dokumentasi Tambahan

- **Plan File**: `plan.md` (detail rencana implementasi 20 tasks dalam 7 fase)
- **AGENTS.md**: Panduan untuk AI agent dalam mengembangkan proyek ini
- **Parent Repo**: `https://git.datadunia.com/hainzero/WGRplane.git` (submodule di `/app`)

---

## Lisensi

Proyek ini mengikuti lisensi dari WGDashboard (donaldzou/WGDashboard) dan modifikasi untuk integrasi policy.json API.