fn_registry/docs/capabilities/wireguard.md

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

# 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)

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

# 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.