feat: sembrar ALLOWED_GROUPS desde env y exponer métricas en /metrics

Co-authored-by: aider (openrouter/openai/gpt-5) <aider@aider.chat>

docs/architecture.md

@@ -48,3 +48,18 @@ Observabilidad y errores
 - Métricas:
   - sync_runs_total, contadores de alias resueltos, etc.
   - Estados de gauges/counters expuestos en /metrics (Prom/JSON).
+
+Control de acceso por grupos (allowed_groups)
+- Esquema: tabla allowed_groups (group_id PK, label, status: pending|allowed|blocked, discovered_at/updated_at, discovered_by).
+- Servicio: AllowedGroups con caché en memoria e interfaz isAllowed, setStatus, upsertPending, listByStatus, seedFromEnv.
+- Flujo:
+  - Discover (GROUP_GATING_MODE='discover'): ante tráfico de un grupo desconocido, se registra como pending y se retorna temprano; opcionalmente se notifica a ADMIN_USERS (NOTIFY_ADMINS_ON_DISCOVERY='true').
+  - Enforce (GROUP_GATING_MODE='enforce'): se ignoran mensajes/comandos en grupos no allowed; /admin tiene bypass para permitir aprobación in situ.
+- Superficies aplicadas:
+  - server.ts: retorno temprano en discover y enforce; excepción para /admin.
+  - services/command.ts: guard de enforce para evitar procesar comandos de grupos no allowed.
+  - services/group-sync.ts: sincronización de miembros salta grupos no allowed (incluye scheduler).
+  - tasks/service.ts: en enforce, crear tareas con group_id=null si el grupo no está allowed (compatibilidad).
+  - reminders.ts: omite tareas/grupos no allowed al generar recordatorios en enforce.
+- Observabilidad:
+  - Gauges allowed_groups_total_* y counters unknown_groups_discovered_total, messages_blocked_group_total, commands_blocked_total, sync_skipped_group_total, admin_actions_total_{allow,block}.

docs/operations.md

@@ -15,6 +15,10 @@ Variables de entorno (principales)
 - GROUP_MEMBERS_SYNC_INTERVAL_MS: intervalo de sync de miembros (default 6h; min 10s en dev).
 - GROUP_MEMBERS_INACTIVE_RETENTION_DAYS: días para borrar miembros inactivos (default 180).
 - TZ: zona horaria para recordatorios (default Europe/Madrid).
+- GROUP_GATING_MODE: 'off' | 'discover' | 'enforce' (control de acceso por grupos; por defecto 'off').
+- ADMIN_USERS: lista separada por comas de IDs/JIDs autorizados para /admin (se normalizan a dígitos).
+- ALLOWED_GROUPS: lista separada por comas de group_id@g.us para sembrado inicial en arranque.
+- NOTIFY_ADMINS_ON_DISCOVERY: 'true'/'false' para avisar por DM a ADMIN_USERS al descubrir un grupo (modo 'discover').
 
 Endpoints operativos
 - GET /metrics
@@ -42,6 +46,13 @@ Datos y backups
 
 Métricas de referencia
 - sync_runs_total, identity_alias_resolved_total, contadores/gauges específicos de colas y limpieza.
+- Control de acceso por grupos (multicomunidades):
+  - allowed_groups_total_pending, allowed_groups_total_allowed, allowed_groups_total_blocked (gauges).
+  - unknown_groups_discovered_total (counter).
+  - messages_blocked_group_total (counter).
+  - commands_blocked_total (counter).
+  - sync_skipped_group_total (counter).
+  - admin_actions_total_allow, admin_actions_total_block (counters).
 - Añadir nuevas métricas usando Metrics.inc/set y documentarlas aquí.
 
 Buenas prácticas

src/server.ts

@@ -471,6 +471,9 @@ export class WebhookServer {
 		// Run database migrations (up-only) before starting services
 		await Migrator.migrateToLatest(this.dbInstance);
 
+		// Etapa 7: seed inicial de grupos permitidos desde ALLOWED_GROUPS (best-effort)
+		try { AllowedGroups.seedFromEnv(); } catch {}
+
 		const PORT = process.env.PORT || '3007';
 		console.log('✅ Environment variables validated');