# 0043 — Guardrails de seguridad para Father Bot

**Estado:** pendiente

## Objetivo

Implementar capas adicionales de seguridad para Father Bot (el agente que crea otros agentes). Dado que tiene acceso de escritura al repositorio y puede ejecutar scripts, necesita restricciones mas alla del ACL admin-only basico que se configura en el issue 0037.

## Contexto

- Father Bot usa `provider: claude-code` con `bypassPermissions` y `working_dir` apuntando a la raiz del proyecto. Esto le da acceso completo de lectura/escritura.
- Actualmente la unica barrera es el ACL admin-only de `security/permissions.yaml`.
- El sistema de seguridad centralizado (issue 0024) ya soporta grupos de usuarios y agentes, pero no tiene restricciones dinamicas basadas en env vars ni path-scoping fino.
- Solo el propietario del servidor accede actualmente, pero el sistema debe estar preparado para multiples desarrolladores.

## Arquitectura

### 1. Visibilidad basada en .env (developer allowlist)

Nuevo env var `FATHER_BOT_ALLOWED_USERS` que lista los Matrix user IDs autorizados para interactuar con Father Bot. Esto complementa (no reemplaza) el ACL centralizado.

```
# .env
FATHER_BOT_ALLOWED_USERS="@admin:matrix-af2f3d.organic-machine.com,@dev2:matrix-af2f3d.organic-machine.com"
```

**Implementacion:**
- `agents/_specials/father-bot/config.yaml` referencia el env var
- El runtime valida `FATHER_BOT_ALLOWED_USERS` antes de procesar cualquier mensaje
- Si el env var esta vacio o no existe, DENEGAR todo (deny-by-default)
- Log de nivel WARN por cada intento denegado

### 2. Path scoping para el subprocess claude-code

Restringir las operaciones de escritura del subprocess `claude -p` a paths seguros:

**Paths permitidos (escritura):**
- `agents/` — crear nuevos agentes
- `agents/_specials/` — si se crean specials
- `cmd/launcher/main.go` — blank imports

**Paths permitidos (lectura):**
- Todo el repositorio (necesita leer templates, config, rules)

**Paths prohibidos (lectura y escritura):**
- `.env` — contiene secrets
- `security/` — no debe auto-modificar permisos
- `.git/` — no debe tocar el historial

**Implementacion:**
- Instrucciones en el system prompt (primera linea de defensa)
- Validacion en un wrapper/hook que el subprocess claude-code respete
- Audit log de cada archivo tocado

### 3. Rate limiting de operaciones de creacion

- Maximo 3 agentes por hora (configurable via env var `FATHER_BOT_MAX_CREATES_PER_HOUR`)
- Contador persistido en memoria del agente o en SQLite
- Si se excede, rechazar con mensaje explicativo

### 4. Audit trail extendido

- Log estructurado de cada operacion de creacion:
  - Timestamp, usuario solicitante, tipo (agent/robot), ID creado, resultado (exito/fallo)
  - Scripts ejecutados y exit codes
  - Archivos creados/modificados
- Opcionalmente enviar resumen a un room de auditoria (`security.audit.log_to_room`)

### 5. Validacion de agentes creados

Antes de reiniciar el launcher, verificar que el agente creado:
- No tiene `security.sanitize.enabled: false` (debe heredar defaults seguros)
- No tiene `tools.ssh.allowed_commands: ["*"]` (no wildcard en SSH)
- No tiene `tools.file_ops.allowed_paths: ["/"]` (no root access)
- Tiene seccion de seguridad en el system prompt
- Compila sin errores

## Tareas

### Fase 1 — Developer allowlist

- [ ] **1.1** Implementar validacion de `FATHER_BOT_ALLOWED_USERS` en el runtime de father-bot
- [ ] **1.2** Deny-by-default si env var vacio
- [ ] **1.3** Tests unitarios para la validacion

### Fase 2 — Path scoping

- [ ] **2.1** Definir allowlist/denylist de paths en config.yaml
- [ ] **2.2** Implementar validacion post-ejecucion (verificar que solo se tocaron paths permitidos)
- [ ] **2.3** Tests para path validation

### Fase 3 — Rate limiting

- [ ] **3.1** Implementar contador de creaciones por hora
- [ ] **3.2** Rechazar con mensaje si se excede el limite
- [ ] **3.3** Tests para rate limiting

### Fase 4 — Audit trail

- [ ] **4.1** Extender audit log con eventos de creacion de agentes
- [ ] **4.2** Opcion de enviar a room de auditoria
- [ ] **4.3** Tests para audit events

### Fase 5 — Validacion de agentes creados

- [ ] **5.1** Implementar validador de config de agente creado
- [ ] **5.2** Rechazar creacion si la config viola politicas de seguridad
- [ ] **5.3** Tests para validador

## Decisiones de diseno

1. **Deny-by-default en env var vacio**: si nadie configura `FATHER_BOT_ALLOWED_USERS`, father-bot no responde a nadie. Esto previene que un deploy sin configurar exponga el agente.

2. **Path scoping via system prompt + validacion**: la primera linea de defensa es el system prompt (instrucciones explicitas). La segunda es validacion post-ejecucion que verifica que archivos fueron tocados.

3. **Rate limiting simple**: no necesitamos un sistema sofisticado. Un contador en memoria con reset por hora es suficiente para la frecuencia esperada de creacion de agentes.

4. **Validacion de config creada**: previene escalacion de privilegios indirecta (crear un agente con mas permisos de los debidos).

## Prerequisitos

- Issue 0037 completado (father-bot funcional)
- Sistema de permisos centralizado (issue 0024) — ya completado

## Riesgos

| Riesgo | Mitigacion |
|--------|------------|
| Env var no configurado en deploy | Deny-by-default: father-bot inactivo sin config |
| Path scoping evadido via symlinks | Resolver symlinks antes de validar (como en tools/file/) |
| Rate limit reseteado al reiniciar | Aceptable: es defensa en profundidad, no la unica barrera |