> ## Documentation Index
> Fetch the complete documentation index at: https://woku.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Allowlist de IPs por empresa

> Restringir el acceso autenticado a Woku a una lista de bloques CIDR confiables

Algunas empresas exigen que el acceso a su panel Woku solo se permita
desde **IPs específicas**, la red corporativa, una VPN, o un rango
de oficinas. Woku soporta esto vía un allowlist de **CIDR blocks**
per-empresa, configurable y opt-in.

## Conceptos

* **CIDR**: notación estándar para describir un rango de IPs.
  Ejemplos: `10.0.0.0/8` (toda la red 10.x.x.x), `203.0.113.5/32`
  (solo esa IP exacta), `2001:db8::/32` (un prefijo IPv6).
* **Opt-in per-empresa**: cada empresa decide si activa el control.
  Por defecto está **desactivado** y todo el tráfico autenticado
  pasa sin restricción.
* **Fail-closed**: si la empresa no se puede resolver o la IP de la
  request es desconocida (no hay `x-forwarded-for` ni IP directa),
  el guard responde 403.
* **IPv4 + IPv6**: el matcher soporta ambos.

## Activar el allowlist

Para activar el control en tu empresa:

1. Ve a **Empresa → Seguridad → Allowlist de IPs**.
2. Carga los CIDR blocks desde donde puedes acceder. Ejemplos típicos:
   * Red corporativa: `192.168.0.0/16`
   * VPN: `10.0.0.0/8`
   * IP única (oficina): `203.0.113.5/32`
3. Marca **Habilitado**.
4. Guarda.

> ⚠️ **No puedes activar el allowlist con la lista vacía**: el
> servidor rechaza la operación porque dejaría a todo el equipo
> sin acceso.

## Qué pasa cuando alguien intenta entrar fuera del allowlist

El servidor responde `403 Forbidden` con el mensaje
"Request IP not in company allowlist". El usuario:

* **No puede iniciar sesión** desde esa IP, aunque tenga credenciales
  válidas.
* **Pierde el acceso a su sesión actual** si esa sesión hace un
  request desde una IP no permitida.

Todas las acciones bloqueadas quedan registradas en el
[registro de auditoría](/seguridad/audit-log) como `403 Forbidden`
con `company.ip-allowlist.enforce`.

## Detección de IP

El guard prioriza el header `x-forwarded-for` (necesario porque
detrás de un balanceador como ALB, la IP de socket es la del LB):

1. Si `x-forwarded-for: <ip1>, <ip2>, ...` está presente, usa la
   primera IP.
2. Si no, usa `request.ip` (socket directo).
3. Si ninguna está disponible y el allowlist está activo: 403.

> Para que esto funcione en producción, el reverse proxy debe estar
> configurado para inyectar `x-forwarded-for` con la IP real del
> cliente. La infraestructura actual de Woku (AWS Copilot/ALB) ya lo
> hace.

## Garantías

* **Validación server-side**: las CIDRs se validan con `ip-cidr`
  antes de guardar. Una entrada inválida es rechazada con 400.
* **Deduplicación**: la lista se recorta y se eliminan duplicados al
  guardar.
* **Inmediato**: el cambio aplica al próximo request. No hay cache.
* **Auditable**: cada update queda registrado.

## Limitaciones conocidas

* El guard se aplica **por endpoint** (`@UseGuards(IpAllowlistGuard)`).
  En esta primera entrega NO está aplicado automáticamente a todos
  los endpoints company-scoped: los equipos que necesiten enforcement
  estricto deben pedirlo en un cambio puntual por endpoint sensible
  (o esperar al rollout global en el próximo release).
* Solo aplica a endpoints que llevan `companyId` en la ruta. Si una
  empresa tiene endpoints que no son scope-by-path, el allowlist no
  los gatea.

## ¿Y si me quedo afuera por error?

Si configuras un allowlist incorrecto y pierdes acceso, **contacta a
soporte** (`team@woku.app`). Un administrador interno puede limpiar
el allowlist vía endpoint backoffice. La acción queda registrada en
el audit log.