# 0003 — Control de acceso por grupos (multicomunidad) y /admin

Estado
- aceptada

Contexto
- El bot debe convivir con múltiples comunidades/grupos.
- Evitar ruido/abuso en grupos donde el bot no está aprobado.
- Requerimos un flujo de aprobación simple, auditable y consistente con el diseño “solo DM”.

Decisión
- Añadir tabla allowed_groups con:
  - group_id (PK), label (opcional), status ('pending'|'allowed'|'blocked'),
    discovered_at, updated_at, discovered_by (opcional).
- Modos de gating:
  - off — sin control.
  - discover — grupos desconocidos pasan a 'pending'; detener procesamiento y (opcional) notificar por DM a ADMIN_USERS.
  - enforce — solo se procesan mensajes/comandos de grupos 'allowed'.
- Servicio AllowedGroups con caché en memoria e interfaz:
  - isAllowed(groupId), setStatus(groupId, status), upsertPending(groupId, discoveredBy), listByStatus(status), seedFromEnv().
- Comandos /admin (solo ADMIN_USERS normalizados):
  - pendientes, habilitar-aquí, deshabilitar-aquí, allow-group <jid>, block-group <jid>, sync-grupos.
- Métricas:
  - Gauges: allowed_groups_total_pending|allowed|blocked.
  - Counters: unknown_groups_discovered_total, messages_blocked_group_total, commands_blocked_total, sync_skipped_group_total.
- Variables de entorno:
  - GROUP_GATING_MODE, ADMIN_USERS, ALLOWED_GROUPS, NOTIFY_ADMINS_ON_DISCOVERY.

Consecuencias
- Despliegues multicomunidad más seguros y con menos ruido.
- Complejidad moderada (tabla + caché + comandos de admin).
- Operativa documentada y métricas para observabilidad.

Alternativas consideradas
- Lista blanca hardcodeada: poca flexibilidad y sin trazabilidad.
- Restringir a una única comunidad: limita casos de uso.
- Sin control: riesgo de abuso y ruido.

Notas de implementación
- Gate aplicado en server.ts y CommandService (retorno temprano según modo).
- GroupSyncService ignora grupos no allowed (incluye scheduler).
- Reminders y TaskService filtran por grupos válidos en modo enforce.