# wireguard — Capability Group

Instalar, configurar, operar y monitorizar un mesh WireGuard hub-and-spoke desde Go y Bash.

## Funciones

| ID | Firma corta | Que hace |
|---|---|---|
| `wg_install_bash_infra` | `wg_install() -> json` | Instala wireguard-tools en Linux (debian/ubuntu/fedora/arch). Idempotente. |
| `wg_keygen_go_infra` | `WGKeygen(withPSK bool) (WGKeys, error)` | Genera par de claves Curve25519 (privada+publica+opcional PSK). |
| `wg_hub_setup_bash_infra` | `wg_hub_setup(private_key, subnet_cidr, listen_port) -> json` | Configura el host como hub: crea wg0.conf, abre firewall, habilita ip_forward, arranca wg-quick@wg0. Idempotente. |
| `wg_client_install_bash_infra` | `wg_client_install(config_path_or_stdin, [iface]) -> json` | Device-side: instala wg0.conf, habilita wg-quick, verifica handshake con hub. |
| `wg_peer_remove_go_infra` | `WGPeerRemove(deviceID, configPath string) (WGPeerRemoveResult, error)` | Quita peer del hub por device_id, syncconf en caliente. Idempotente. |
| `wg_peer_revoke_go_infra` | `WGPeerRevoke(deviceID, operator, reason, configPath, auditDBPath string) (WGPeerRevokeAudit, error)` | Kill switch: revoca peer permanentemente con audit log hash-chained. |
| `wg_status_bash_infra` | `wg_status([interface_name]) -> json` | Parsea `wg show <iface> dump` a JSON con peers, handshake age, status (online/stale/never), bytes rx/tx, device_id. |

## Ejemplo canonico — setup completo de un nodo nuevo

```bash
# 1. Instalar wg en el hub (si no esta instalado)
source bash/functions/infra/wg_install.sh
wg_install | jq .version

# 2. Generar claves para el hub
# (via Go — requiere wg binary)
./fn run wg_keygen_go_infra

# 3. Configurar hub
source bash/functions/infra/wg_hub_setup.sh
wg_hub_setup "$HUB_PRIVATE_KEY" "10.42.0.0/24" 51820 | jq .

# 4. Instalar config en cliente (acepta stdin para pipes)
source bash/functions/infra/wg_client_install.sh
wg_client_install /path/to/wg0.conf | jq .handshake_ok

# 5. Ver estado del mesh
source bash/functions/infra/wg_status.sh
wg_status wg0 | jq .peers[].status
```

## Ejemplo canonico — monitorizar mesh (dashboard / agents_dashboard Mesh panel)

```bash
source bash/functions/infra/wg_status.sh

# Peers online
wg_status | jq '[.peers[] | select(.status=="online")] | length'

# Tabla compacta: device_id, status, ago
wg_status | jq -r '.peers[] | [.device_id, .status, (.latest_handshake_ago_s|tostring)+"s"] | @tsv'

# Testing sin sudo (WG_FAKE_DUMP + WG_FAKE_CONF)
WG_FAKE_DUMP=fixtures/dump.tsv WG_FAKE_CONF=fixtures/wg0.conf wg_status wg0 | jq .
```

## Ejemplo canonico — revocar peer comprometido

```bash
# Quitar peer de wg0.conf (sin audit log)
./fn run wg_peer_remove_go_infra -- --device-id pc-comprometido --config /etc/wireguard/wg0.conf

# Kill switch con audit log inviolable
./fn run wg_peer_revoke_go_infra -- \
  --device-id pc-comprometido \
  --operator lucas \
  --reason "dispositivo perdido" \
  --config /etc/wireguard/wg0.conf \
  --audit-db /var/lib/wg/audit.db
```

## Fronteras

- **No cubre**: gestión de DNS WireGuard, split-tunnel avanzado, integración con cloud providers (AWS VPC, Tailscale).
- **No cubre**: rotación automática de claves (cron + wg_keygen + wg_hub_setup es la composición manual).
- **No cubre**: UI web para el mesh — `wg_status` provee el JSON que consume `agents_dashboard`.
- `nordvpn_set_protocol_bash_infra` usa WireGuard internamente (NordLynx) pero no pertenece a este grupo — opera NordVPN, no un mesh propio.

## Prerequisitos

- `wireguard-tools` instalado en el host (usar `wg_install_bash_infra`).
- `wg show` requiere `CAP_NET_ADMIN` / root. Para tests: `WG_FAKE_DUMP` + `WG_FAKE_CONF`.
- Comentarios `# DeviceID:<id>` antes de cada `[Peer]` en `/etc/wireguard/wg0.conf` para resolver `device_id` en `wg_status`.