feat(infra): auto-commit con 86 cambios

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-26 19:38:15 +02:00
parent 34c27876e0
commit 621e8895c9
85 changed files with 11840 additions and 92 deletions
@@ -0,0 +1,66 @@
+---
+name: wg_hub_setup
+kind: function
+lang: bash
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "wg_hub_setup(private_key, subnet_cidr, listen_port) -> json"
+description: "Configura el host como hub WireGuard (servidor). Crea /etc/wireguard/wg0.conf con clave privada + IP pool + ListenPort. Abre UDP en firewall (ufw o iptables), habilita ip_forward persistente en /etc/sysctl.d/99-wireguard.conf, persiste y arranca systemd unit wg-quick@wg0. Idempotente: misma PrivateKey = no-op; PrivateKey distinta = backup + rewrite."
+tags: [wireguard, hub, infra, mesh, systemd]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+params:
+  - name: private_key
+    desc: "base64 WG private key del hub (44 chars, generada por wg_keygen o `wg genkey`)"
+  - name: subnet_cidr
+    desc: "subnet hub con bits del host, ej. 10.42.0.1/24. El hub recibe la .1"
+  - name: listen_port
+    desc: "UDP port donde escucha WireGuard (default 51820, rango 1024-65535)"
+output: "JSON {status, config_path, interface, hub_ip}. status: configured | reconfigured | already-configured"
+tested: false
+tests: []
+test_file_path: ""
+file_path: "bash/functions/infra/wg_hub_setup.sh"
+---
+
+## Ejemplo
+
+```bash
+# Generar clave (o usar wg_keygen del registry)
+PRIVKEY=$(wg genkey)
+
+source bash/functions/infra/wg_hub_setup.sh
+wg_hub_setup "$PRIVKEY" "10.42.0.1/24" 51820
+# {"status":"configured","config_path":"/etc/wireguard/wg0.conf","interface":"wg0","hub_ip":"10.42.0.1"}
+
+# Segunda ejecución con la misma clave → no-op
+wg_hub_setup "$PRIVKEY" "10.42.0.1/24" 51820
+# {"status":"already-configured","config_path":"/etc/wireguard/wg0.conf","interface":"wg0","hub_ip":"10.42.0.1"}
+
+# Cambiar clave → backup de conf anterior + rewrite
+wg_hub_setup "$NUEVA_PRIVKEY" "10.42.0.1/24" 51820
+# {"status":"reconfigured","config_path":"/etc/wireguard/wg0.conf","interface":"wg0","hub_ip":"10.42.0.1"}
+```
+
+## Cuando usarla
+
+Cuando necesites convertir un VPS/host en el nodo central (hub) de una red mesh WireGuard. Úsala inmediatamente después de `wg_install` para dejar el hub listo para recibir peers. El hub escucha en un puerto UDP público; los peers se conectan a él con su propia clave y la AllowedIPs del hub.
+
+## Gotchas
+
+- Requiere `sudo` con NOPASSWD para: `tee /etc/wireguard/`, `chmod`, `sysctl`, `iptables`/`ufw`, `systemctl`. Configurar antes en sudoers.
+- NUNCA reusar la misma `private_key` entre hubs distintos. Cada hub tiene su propio par de claves independiente.
+- El bloque `PostUp`/`PostDown` usa `eth0` como interfaz de salida para NAT. En VPS con interfaz distinta (ens3, enp3s0) editar `/etc/wireguard/wg0.conf` manualmente antes de reiniciar.
+- Conflicto de subnet con docker0 si usas 172.17.0.0/16. Evitar solapamiento — usar 10.42.x.x o 192.168.200.x para WireGuard.
+- `systemd-resolved` en VPS Ubuntu puede interferir con resolución DNS cuando WireGuard está activo si el conf añade `DNS =`. Esta función NO setea DNS para evitar el problema — configurarlo a nivel peer si se necesita.
+- Si `systemctl start wg-quick@wg0` falla, revisar logs con `journalctl -u wg-quick@wg0 -n 50`.
+- En entornos cloud (AWS/GCP/Azure) el security group / firewall de red del proveedor también debe abrir el puerto UDP, independientemente de ufw/iptables local.
+
+## Capability growth log
+
+<!-- Rellenar solo cuando haya version bump real -->