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 de9bfec498
commit fe65c5e527
85 changed files with 11840 additions and 92 deletions
@@ -0,0 +1,57 @@
+---
+name: wg_peer_add
+kind: function
+lang: go
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "func WGPeerAdd(spec WGPeerSpec, configPath, subnetCIDR string) (WGPeerResult, error)"
+description: "Hub-side: anade peer WireGuard al wg0.conf con IP asignada del pool, syncconf en caliente sin reiniciar interface. Idempotente por PublicKey + DeviceID. Mantiene comentario # DeviceID:<id> sobre cada bloque [Peer] para tracking inverso."
+tags: [wireguard, hub, peer, mesh, infra]
+params:
+  - name: spec
+    desc: "WGPeerSpec con DeviceID (identificador logico), PublicKey (base64), PresharedKey (base64, opcional), AllowedIPs (CIDR; vacio = autoasignar del pool)"
+  - name: configPath
+    desc: "Ruta absoluta al wg0.conf del hub, ej /etc/wireguard/wg0.conf"
+  - name: subnetCIDR
+    desc: "Subnet del pool de IPs WireGuard, ej '10.42.0.0/24'. La .1 se reserva para el hub y se excluye del pool."
+output: "WGPeerResult con DeviceID, AssignedIP (pura sin CIDR), ConfigPath y Status ('added'|'already-present'|'reconfigured')"
+uses_functions: []
+uses_types: [wg_peer_spec_go_infra, wg_peer_result_go_infra]
+returns: [wg_peer_result_go_infra]
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+tested: true
+tests:
+  - "peer nuevo con AllowedIPs vacio asigna 10.42.0.2"
+  - "agregar segundo peer asigna 10.42.0.3"
+  - "agregar mismo PublicKey otra vez retorna already-present"
+  - "agregar DeviceID existente con clave distinta retorna reconfigured"
+test_file_path: "functions/infra/wg_peer_add_test.go"
+file_path: "functions/infra/wg_peer_add.go"
+---
+
+## Ejemplo
+
+```go
+spec := infra.WGPeerSpec{
+    DeviceID:  "pc-aurgi",
+    PublicKey: "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=",
+}
+res, err := infra.WGPeerAdd(spec, "/etc/wireguard/wg0.conf", "10.42.0.0/24")
+// res.AssignedIP == "10.42.0.2"  (primera IP libre del pool)
+// res.Status    == "added"
+```
+
+## Cuando usarla
+
+Cuando un dispositivo nuevo (PC, contenedor, mobile) se une al mesh WireGuard del hub. Llamar tras generar las claves con `wg_keygen_go_infra`. Idempotente: si el DeviceID ya existe con la misma clave, devuelve `already-present` sin tocar el config.
+
+## Gotchas
+
+- **Race condition**: si dos llamadas concurrentes añaden peers simultáneamente, la segunda puede asignar la misma IP libre. Usar file lock (`flock`) sobre `configPath` para serializar en produccion.
+- **WG_SKIP_SYNCCONF=1**: en entornos CI sin WireGuard instalado, establecer esta variable para saltarse el exec de `wg syncconf`. Los tests ya la activan en el `init()`.
+- **syncconf falla → rollback automático**: si el `wg syncconf` devuelve error, se restaura el backup `.bak` y se devuelve error. El config queda intacto.
+- **chmod 600**: la función hace `chmod 600` sobre `configPath` tras cada escritura. Asegúrate de que el proceso tiene permisos sobre el archivo.
+- **Hub IP .1**: la función excluye `<red>.1` del pool de autoasignación. El hub debe tener esa IP. Si el hub usa otra IP, ajustar la lógica de `wgNextFreeIP`.