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