Connections Module Overview

El módulo connections gestiona las integraciones con servicios externos que DaraMex consume — correo SMTP, bots de Telegram y servicios de Google (Gmail, Sheets, Calendar) vía OAuth 2.0.

Tras la refactor connections-redesign el contrato entre catálogo y runtime es un slug por entrada de available_connections, y cada connection apunta por FK al catálogo. Ya no existen los campos provider/type en la tabla connections.

Slugs soportados

Slug	Auth type	Forma del config	Origen
smtp	credentials	host, port, user, password, secure	Registry in-code
telegram	credentials	botToken, chatId?	Registry in-code
gmail	oauth	GoogleOAuthConfig	Registry in-code (scopes: gmail.send, gmail.modify)
sheets	oauth	GoogleOAuthConfig	Registry in-code (scopes: spreadsheets, drive.file, drive.readonly)
calendar	oauth	GoogleOAuthConfig	Registry in-code (scopes: calendar, calendar.events)

El contrato entre DB y código se mantiene por el slug. Ver Registry Contract.

Modelo de visibilidad

Cada conexión pertenece a un usuario (addedById, NOT NULL) dentro de orgId + agencyId. La visibilidad gobierna quién más la ve:

Valor	Semántica
private (default)	Sólo el autor (addedById) puede ver, actualizar o eliminar la conexión
restricted	Cualquier usuario dentro del mismo orgId + agencyId puede verla

Autorización en dos capas:

1. CASL a nivel de controlador via @CheckPolicies sobre el subject connections.connection para las acciones read, create, update, delete.
2. Filtrado por visibilidad dentro de las queries/commands: GetConnectionsQuery combina buildAccessFilter(...) + connection.isVisibleTo(userId); GetConnectionByIdQuery y los update/delete comprueban isVisibleTo antes de operar (ownershipViolation en caso contrario).

Forma de la entidad

type ConnectionProps = {
  orgId: string;
  agencyId: string;
  addedById: string;
  availableConnectionId: string;   // FK → connections.available_connections(id)
  visibility: 'private' | 'restricted';
  label: string | null;            // antes `name`; opcional
  status: 'active' | 'error' | 'disconnected';
  config: IConnectionConfig;       // SmtpConfig | TelegramConfig | GoogleOAuthConfig
};

En la respuesta HTTP (IConnectionResponse) se adjunta además el slug joineado desde el catálogo para comodidad del cliente.

Las credenciales sensibles (password, botToken, accessToken, refreshToken) se guardan cifradas en config (AES-256-GCM).

Endpoints principales

Todas las rutas están prefijadas con /connections.

Método	Ruta	Descripción
GET	/available	Lista del catálogo (slug, displayName, authType, cover, icon, description)
GET	/available/:id	Entrada puntual del catálogo
GET	/available/:id/form-schema	Descriptor de formulario ({ fields: [] } para OAuth)
POST	/available/seed	Sincroniza el catálogo con el registry in-code (idempotente)
PUT	/available/:id	Edita sólo displayName, icon, cover, description
DELETE	/available/:id	Elimina la entrada si no hay connections que la referencien (409 si hay)
GET	/	Lista conexiones visibles al usuario dentro del scope org + agency
GET	/:id	Obtiene una conexión por ID (respeta visibilidad)
POST	/	Crea una conexión de cualquier slug credentials
PUT	/:id	Actualiza label, status, config, visibility
DELETE	/:id	Elimina (revoca token Google en fire-and-forget si aplica)
POST	/test	Prueba la conectividad sin persistir ({ availableConnectionId, config })
POST	/oauth/start	Inicia flujo OAuth ({ availableConnectionId, label?, visibility? }) — rechaza slugs credentials con oauth_not_supported
GET	/oauth/callback	Callback OAuth; resuelve el estado contra el slug declarado en el state token

El flujo de descubrimiento por parte del frontend está descrito en Auth Discovery Flow.

Rate limits

• POST /oauth/start: 10 req/min por usuario (userId)
• POST /test: 5 req/min por usuario (userId)

Políticas de plataforma

Tres políticas uuid7 gobiernan la edición del catálogo (subject connections.available-connection):

• update.platform.connections.available-connection → PUT /available/:id
• delete.platform.connections.available-connection → DELETE /available/:id
• manage.platform.connections.available-connection → POST /available/seed

Se asignan a roles platform-admin durante el seed de system policies.

Páginas relacionadas

• Available Connections Catalog — catálogo, endpoints CRUD, tabla DB
• Auth Discovery Flow — cómo el panel ramifica por authType
• Registry Contract — contrato registry in-code ↔ DB catalog
• Recipient Allowlists — allow/deny de destinatarios en Telegram y SMTP
• Google Providers (Gmail, Sheets, Calendar) — comportamiento por slug Google
• Google OAuth Architecture — flujo OAuth end-to-end + taxonomía de errores
• Runbook: Connections Redesign Migration — migración de provider+type+name a slug + FK + label
• Runbook: Google OAuth Prereqs — setup en Google Cloud Console