taskbot/docs/adr/0003-allowed-groups-multicommunity.md

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 , block-group , 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.