@hostwebhook/platform-contracts 0.1.0 → 0.3.0

package/dist/servicios/credenciales-del-gateway.d.ts

@@ -0,0 +1,722 @@
+import { BadRequestException } from '@nestjs/common';
+import type { CredentialType } from '@hostwebhook/node-types';
+/**
+ * Lo que un nodo pregunta al gateway sobre una credencial.
+ *
+ * ## Esta costura NO se corta como las otras diecinueve
+ *
+ * En todas las anteriores bastaba con invertir la dependencia: declarar la
+ * superficie usada y atarla con un token. Aquí eso sería un error de diseño.
+ *
+ * Un `getDecrypted(id)` por token funcionaría perfectamente dentro del repo, y
+ * el día que la costura fuera HTTP significaría **hw-nodes pidiendo secretos
+ * descifrados por la red en cada ejecución, sin que nadie compruebe que ese
+ * nodo tenga algo que ver con esa credencial**. Es justo lo que el
+ * `hw-credentials` de la Fase 4 existe para evitar. Cortarla así sería trabajo
+ * que hay que rehacer.
+ *
+ * Así que este contrato se construye en la forma FINAL desde el principio:
+ *
+ *   describir()   metadatos. No trae el secreto, y no puede traerlo.
+ *   material()    el secreto, y SIEMPRE diciendo quién lo pide.  (PR C)
+ *   tokenDe…()    tokens ya refrescados; el cliente se monta en el nodo. (PR C)
+ *
+ * Este PR trae sólo `describir`. Cada método llega cuando su implementación
+ * está atada — un contrato con métodos que nadie provee es una mentira que
+ * compila.
+ *
+ * ## Por qué `describir` no lleva quién pide, y `material` sí
+ *
+ * Porque no son la misma pregunta. `credentials.service.findOne` hace
+ * `.select('-encryptedData')`: devuelve el tipo, el nombre y los metadatos, y
+ * el secreto NO sale por ahí. Exigir atribución para leer el tipo de una
+ * credencial sería ruido en el registro de accesos, que existe para responder
+ * «quién leyó este secreto».
+ */
+/**
+ * Los metadatos de una credencial. Medido dos veces, por caminos distintos:
+ * de los 53 sitios que llaman a `findOne`, lo único que se lee del documento
+ * es `type` (161 veces), `metadata` (25) y `name` (6).
+ *
+ * ⚠️ Los `accessToken`, `phoneNumberId` y `organizationId` que aparecen al
+ * barrer NO salen de aquí: son blobs ya descifrados, o documentos que devuelve
+ * `SlackOAuthService.findCredentialsByTeamId`. Se comprobó uno por uno.
+ */
+export interface DescripcionDeCredencial {
+    id: string;
+    /**
+     * ⚠️ El tipo viene de `@hostwebhook/node-types`, no de la entidad. Es un
+     * paquete, así que los dos lados lo alcanzan y este contrato no toca
+     * Mongoose ni de refilón.
+     */
+    type: CredentialType;
+    name: string;
+    /**
+     * ⚠️ Los metadatos SIN pasar por `toJSON()`.
+     *
+     * El `toJSON` de la entidad los borra cuando la credencial está marcada
+     * como sensible — eso es para la respuesta HTTP, no para el motor. Quien
+     * los lee aquí es el enrutado por túnel y la zona horaria del calendario,
+     * que necesitan el valor real. Aplanar con `toJSON()` los dejaría vacíos
+     * para las credenciales sensibles, en silencio y sólo para algunas.
+     */
+    metadata: Record<string, unknown>;
+}
+/**
+ * Quién pide un secreto, y con qué derecho. Las dos formas son EXPLÍCITAS.
+ *
+ * ## Por qué es obligatorio y no un `context?` opcional
+ *
+ * Porque opcional es lo que hay hoy y no funciona. De las 59 lecturas de
+ * secretos en `nodes/` + `common/`:
+ *
+ *     19  dicen de verdad qué nodo fue
+ *      7  pasan `relatedEntity` con `id: ctx.entityId ?? ''` — el campo está
+ *         y el id viene VACÍO, así que la fila del registro dice
+ *         «un social_media_action, id ''», que no enlaza con nada
+ *      8  sólo un `purpose`
+ *     25  nada
+ *
+ * El registro de accesos del api#433 existe y funciona; dos tercios de las
+ * lecturas no lo alimentan. Ponerlo en el TIPO lo arregla de una vez y sin
+ * riesgo de ejecución: lo que falta no compila.
+ *
+ * ⚠️ El caso del id vacío no lo caza TypeScript —`'' `es un `string` válido—,
+ * así que el adaptador lo comprueba y lo apunta. Ver `comoAtribuir`.
+ */
+/**
+ * Los tipos de entidad que pueden pedir una credencial.
+ *
+ * ## Por qué es una unión y no un `string`
+ *
+ * Porque con `string` la grafía se tuerce sola. El registro de accesos tenía
+ * las dos mezcladas —`telegramAction` y `discordAction` en camel;
+ * `ai_node`, `social_media_action`, `vector_store` y `voice_agent` en snake—
+ * y `relatedEntityType` se agrupa con
+ * `$group: { _id: { type: '$relatedEntityType', id: '$relatedEntityId' } }`.
+ * Dos grafías del mismo tipo son dos entidades distintas al mirar el registro.
+ *
+ * ⚠️ Se elige CAMEL porque es lo que casa con el `nodeType` real que registra
+ * cada nodo (`socialMediaAction`, `docsAction`, `sheetsAction`…). Snake era
+ * ad hoc. Con esto, una grafía nueva no compila hasta que se declara aquí, que
+ * es el momento de decidirla.
+ *
+ * ⚠️ Y sí, cambiar `ai_node` por `aiNode` parte la agrupación de las filas
+ * viejas. El `id` sigue siendo el mismo —que es la clave de verdad— y el
+ * registro es forense, no un índice: se prefiere que de hoy en adelante diga
+ * una sola cosa.
+ */
+export type TipoDeEntidad = 'trigger' | 'webhook' | 'aiNode' | 'socialMediaAction' | 'socialPost' | 'calendarAction' | 'docsAction' | 'driveAction' | 'sheetsAction' | 'emailAction' | 'gmailAction' | 'approvalNode' | 'telegramAction' | 'whatsappAction' | 'discordAction' | 'slackAction' | 'mongoAction' | 'postgresAction' | 'httpAction' | 'githubAction' | 'notionAction' | 'jiraAction' | 'shopifyAction' | 'mailchimpAction' | 'firecrawlAction' | 'notificationAction' | 'googleAnalyticsAction' | 'googleContactsAction' | 'vectorStore' | 'voiceAgent';
+/**
+ * Por qué esta lectura NO se puede comprobar contra el documento de hoy.
+ *
+ * ⚠️ Son excepciones NOMBRADAS, no agujeros. En los dos casos el documento
+ * correcto contra el que comprobar **ya no está en la base**, así que releerlo
+ * no arregla nada: daría `sin_vinculo` sobre una lectura perfectamente
+ * legítima. Y como van con nombre, se cuentan aparte en el registro y no se
+ * confunden nunca con un `ok`.
+ *
+ *   `baja-de-suscripcion`  Al cambiar o desconectar la credencial de un
+ *     trigger, la baja se da con el documento ANTERIOR —a propósito, porque
+ *     hay que hablar con el proveedor usando la credencial VIEJA— mientras la
+ *     base ya tiene la nueva. Comprobar contra la base denegaría el 100% de
+ *     las veces, y el `catch` de ese camino sólo hace `warn`: sería un fallo
+ *     MUDO con el proveedor siguiendo empujando a un trigger muerto.
+ *
+ *   `plan-congelado`  La aprobación de social media guarda el plan con sus
+ *     `credentialId` y lo despacha horas después. Si en medio alguien quita
+ *     una cuenta del selector, el nodo ya no la referencia — pero la
+ *     publicación que se aprobó sí la incluía.
+ *
+ * ⚠️ Añadir un motivo nuevo es abrir una puerta: hay un guardián que enumera
+ * quién puede usar cada uno, para que la lista no crezca sin que se vea.
+ */
+export type MotivoSinComprobar = 'baja-de-suscripcion' | 'plan-congelado';
+export type QuienPide = 
+/**
+ * Un nodo, trigger o entidad del dominio. Es el caso normal.
+ *
+ * `type` e `id` son los que ya usa `relatedEntity` del registro de accesos,
+ * para que las filas de antes y las de ahora se lean igual.
+ */
+{
+    modo: 'nodo';
+    type: TipoDeEntidad;
+    id: string;
+    motivo?: MotivoSinComprobar;
+    /**
+     * Quién lo disparó, cuando lo disparó alguien.
+     *
+     * 🔥 No es redundante con `modo: 'usuario'`, y lo parecía. Los dos modos
+     * responden a preguntas distintas: `modo` dice contra QUÉ se comprueba el
+     * vínculo —un nodo o una persona—, y esto dice quién apretó el botón.
+     *
+     * Existe porque el gateway ya hacía las dos cosas a la vez y la unión no
+     * lo dejaba decir: `vector_store_embed` pasa `userId` Y
+     * `relatedEntity: {type:'vectorStore'}`, porque una persona pidió
+     * incrustar en un almacén concreto. Con la unión a secas había que elegir
+     * una de las dos, y elegir es perder una columna del registro sin que
+     * nada falle.
+     */
+    userId?: string;
+    /** Desde dónde. Ver `sourceIp` en el modo `usuario`. */
+    sourceIp?: string;
+}
+/**
+ * Una persona con sesión que eligió la credencial a mano.
+ *
+ * ⚠️ Es la excepción, y existe porque hay un caso que no puede ser `nodo`:
+ * `ai-nodes.controller` lista voces para una credencial que la persona
+ * acaba de elegir y cuyo nodo puede no existir todavía. Sin este modo, ese
+ * endpoint tendría que inventarse un nodo o quedarse sin atribuir — y
+ * inventárselo es peor, porque ensucia el registro con filas que apuntan a
+ * cosas que no existen.
+ *
+ * La lista de quién usa este modo la fija un guardián, para que no crezca
+ * sin que se vea.
+ */
+ | {
+    modo: 'usuario';
+    userId: string;
+    /**
+     * La IP desde la que se pidió, si el llamante la tiene.
+     *
+     * ⚠️ El registro de accesos SIEMPRE ha tenido esta columna y seis
+     * llamantes del gateway la rellenaban. El contrato no la llevaba, así que
+     * pasarlos a él la habría vaciado — sin error, sin test rojo, y sin que
+     * nadie mirara esa columna hasta el día que hiciera falta.
+     */
+    sourceIp?: string;
+};
+/** El secreto, con el tipo que dice cómo interpretarlo. */
+export interface MaterialDeCredencial {
+    type: CredentialType;
+    /**
+     * Los metadatos, que ya viajan por `describir` y aquí ahorran un viaje.
+     *
+     * ⚠️ No es comodidad: la familia de bases de datos leía la MISMA metadata
+     * dos veces por despacho —una con `findOne`, para la base efectiva, y otra
+     * con `getTunnelIdForCredential`, que sólo mira `metadata.tunnelId`— además
+     * del `getDecrypted`. Tres consultas para una credencial. Con esto es una.
+     *
+     * ⚠️ Y llega SIN pasar por `toJSON()`, igual que en `describir`: ese
+     * transform borra `metadata` en las credenciales marcadas sensibles, que es
+     * justo de donde sale el `tunnelId` del enrutado. Es la tercera vez que esa
+     * decisión del adaptador resulta ser carga.
+     */
+    metadata: Record<string, unknown>;
+    /**
+     * ⚠️ Una cadena, siempre — es lo que devuelve `getDecrypted` hoy. Quien la
+     * necesita como objeto la parsea, que es lo que ya hace: las credenciales
+     * de cuenta de servicio de Google llegan como JSON en texto.
+     */
+    material: string;
+}
+/** Las siete redes que despachan por `common/social-providers`. */
+export type RedSocial = 'bluesky' | 'twitter' | 'mastodon' | 'linkedin' | 'threads' | 'instagram' | 'facebook';
+/** Una página o empresa de LinkedIn en nombre de la que se puede publicar. */
+export interface OrganizacionDeLinkedIn {
+    urn: string;
+    name: string;
+    vanityName?: string;
+}
+/**
+ * Lo MÍNIMO con lo que se puede llamar a la API de cada red.
+ *
+ * ## ⚠️ Esto NO es el blob guardado, y la diferencia es de seguridad
+ *
+ * En Google el error fue que lo guardado era MÁS DÉBIL que lo utilizable: un
+ * refresh token con el que no se llama a nada. Aquí, en Meta, está invertido —
+ * **lo guardado es más fuerte**. El blob de `instagram_oauth2` y
+ * `facebook_oauth2` lleva dos tokens:
+ *
+ *   `pageAccessToken`   el que el proveedor usa, y el único que necesita
+ *   `userAccessToken`   60 días, y es con el que se piden por `/me/accounts`
+ *                       los tokens de TODAS las páginas del usuario
+ *
+ * Los dos son `string`. Una firma `Promise<string>`, o un `{ token: string }`,
+ * **compila con el que no toca**, y el resultado no es una caída: es hw-nodes
+ * sosteniendo por la red, en cada publicación, la credencial que acuña tokens
+ * de página. Se comprobó que los proveedores declaran `userAccessToken` y no
+ * lo leen NUNCA.
+ *
+ * El tercer caso, más callado: el blob de `mastodon_oauth2` lleva el
+ * `clientId`/`clientSecret` de la app que HostWebhook registró **en esa
+ * instancia**. El proveedor tampoco los toca. Sacarlos por `material()` rompe
+ * «los client secrets se quedan en el gateway» sin que nada falle.
+ *
+ * ## Por qué es una unión discriminada y no una bolsa de opcionales
+ *
+ * Un `{ token: string; instanceUrl?: string; userId?: string }` compila para
+ * las siete y falla en ejecución, por red y de una en una: mastodon llamando a
+ * `https://undefined/api/v1/statuses`, threads a `/undefined/threads`. El
+ * identificador va en la RUTA, no en la cabecera, y mastodon ni siquiera tiene
+ * host fijo. Aquí, la red que se olvida de su campo no compila.
+ *
+ * ⚠️ Cada variante es la interfaz `Session` que el proveedor YA tenía por
+ * dentro. El estrechamiento no se inventa: se muda al gateway, que es donde
+ * está el blob.
+ */
+export type SesionSocial = 
+/**
+ * ⚠️ Bluesky no manda un token: manda una app password DURADERA y de cuenta
+ * completa. Se llama como lo que es. El `createSession` lo hace el nodo
+ * porque el canje no necesita nada del gateway —no hay OAuth de bluesky en
+ * el repo, es app password— y porque el `did` sólo existe después.
+ */
+{
+    red: 'bluesky';
+    identifier: string;
+    appPassword: string;
+    pdsUrl: string;
+}
+/** El ÚNICO que llega refrescado: el gateway lo rota y lo persiste. */
+ | {
+    red: 'twitter';
+    accessToken: string;
+    userId: string;
+}
+/** ⚠️ `instanceUrl` no es adorno: el fediverso no tiene host fijo. */
+ | {
+    red: 'mastodon';
+    accessToken: string;
+    instanceUrl: string;
+    userId: string;
+    fullHandle: string;
+} | {
+    red: 'linkedin';
+    accessToken: string;
+    /** A quién se publica: persona o página. Sin esto no hay `ugcPosts`. */
+    authorUrn: string;
+    memberId: string;
+    memberName: string;
+    /** Derivado de `authorUrn` con `authorKindOf`. */
+    authorKind: 'person' | 'organization' | null;
+    scopes: readonly string[];
+    /** El nombre de la PÁGINA cuando se publica como página; si no, el del
+     *  miembro. Con el del miembro a secas, los logs de una publicación
+     *  como página decían el nombre de la persona. */
+    authorName: string;
+}
+/** `userId` va en la RUTA (`/{userId}/threads`), no en la cabecera. */
+ | {
+    red: 'threads';
+    accessToken: string;
+    userId: string;
+    username: string;
+}
+/** ⚠️ El token de PÁGINA, nunca el de usuario. Ver la cabecera. */
+ | {
+    red: 'instagram';
+    pageAccessToken: string;
+    igUserId: string;
+    igUsername: string;
+}
+/** ⚠️ Igual: el de página. */
+ | {
+    red: 'facebook';
+    pageAccessToken: string;
+    pageId: string;
+    pageName: string;
+};
+/** La sesión de UNA red, para que el proveedor no tenga que estrechar. */
+export type SesionDe<R extends RedSocial> = Extract<SesionSocial, {
+    red: R;
+}>;
+/**
+ * Un canal de Discord, tal y como lo enseña el selector del trigger.
+ *
+ * ⚠️ Vive en el contrato y no en `credentials.service.ts` porque los dos lados
+ * lo necesitan: quien lo produce está en `hw-credentials` y quien lo consume en
+ * `nodes/`. Tenerlo en el servicio obligaba al consumidor a importar las 4.270
+ * líneas del dominio para nombrar diez campos.
+ *
+ * `type` es el entero de Discord (0=texto, 2=voz, 4=categoría, 5=anuncios,
+ * 10/11/12=hilos, 13=stage, 15=foro); el panel ramifica sobre él para filtrar
+ * y elegir icono.
+ */
+export interface DiscordChannelSummary {
+    id: string;
+    name: string;
+    type: number;
+    parentId: string | null;
+    position: number;
+    topic: string | null;
+    guildId: string;
+    guildName: string;
+    guildIcon: string | null;
+}
+/**
+ * Los proveedores cuyo token se refresca con el `client_secret` de nuestra app.
+ *
+ * ⚠️ Una unión cerrada y no una cadena. Con `string`, un proveedor mal escrito
+ * llega hasta el gateway y vuelve como «no existe» en tiempo de ejecución; así
+ * no compila. Crece cuando se cierre slack y atlassian, que tienen más
+ * superficie que un refresco.
+ */
+/**
+ * Los proveedores cuyo access token vive detrás del `client_secret` de nuestra
+ * app y hay que pedirlo, no descifrarlo.
+ *
+ * ⚠️ Distinto de `ProveedorConRefresco`: allí el llamante YA tiene un token y
+ * pide su sustituto; aquí no tiene ninguno y pide uno vivo. Son dos verbos
+ * distintos y por eso son dos uniones y dos métodos.
+ */
+export type ProveedorConToken = 'slack' | 'atlassian';
+export type ProveedorConRefresco = 'notion' | 'shopify';
+export interface CredencialesDelGateway {
+    /**
+     * Los metadatos de una credencial de la organización.
+     *
+     * ⚠️ **Lanza `NotFoundException` si no existe**, igual que hoy. No devuelve
+     * `null`: hay un llamante —`common/discord-operations.service.ts`— que
+     * envuelve esta llamada en un `.catch(onFailureReturn(...))` a propósito.
+     * Convertir el fallo en `null` dejaría ese `catch` sin nada que atrapar y
+     * el resto de llamantes sin error donde hoy lo hay.
+     */
+    describir(id: string, orgId: string): Promise<DescripcionDeCredencial>;
+    /**
+     * El secreto, y el tipo con el que interpretarlo.
+     *
+     * ⚠️ Devuelve los DOS juntos a propósito. El patrón real, idéntico en 28
+     * ficheros, es `findOne` para el tipo → ramificar → descifrar. Devolverlos
+     * juntos quita un viaje de red por ejecución cuando esta costura sea HTTP.
+     *
+     * ⚠️ `tipoEsperado` NO es una comodidad: es dónde se comprueba.
+     *
+     * Muchos llamantes hacen hoy `findOne` → «¿es del tipo que espero?» → lanzar
+     * → y sólo entonces descifrar. Ese orden importa y se pierde si el contrato
+     * trae las dos cosas de un tirón: una credencial del tipo equivocado
+     * acabaría descifrada igual, con su fila en el registro de accesos, para
+     * luego tirarla. Pasándole el tipo, la comprobación se hace **en el
+     * gateway y antes de descifrar**, así que la que no toca no se descifra
+     * nunca. Es mejor que hoy, no igual.
+     */
+    material(id: string, orgId: string, quien: QuienPide, purpose: string, tipoEsperado?: CredentialType | readonly CredentialType[]): Promise<MaterialDeCredencial>;
+    /**
+     * Apunta que la credencial se usó. Para la columna «último uso» del panel.
+     *
+     * ⚠️ Devuelve una promesa que los llamantes NO esperan: todos hacen
+     * `.catch(…)` y siguen. Que fallar en apuntar el uso tumbe una publicación
+     * en Mastodon sería absurdo, y así está hoy.
+     */
+    marcarUsada(id: string): Promise<void>;
+    /**
+     * Los canales que el bot ve, para el selector del trigger de Discord.
+     *
+     * ⚠️ Esto es un LISTADO, no un secreto, y por eso no lleva `purpose`: no
+     * devuelve material que nadie pueda usar para autenticarse. Sí lleva `quien`,
+     * porque el token del bot con el que se pregunta SÍ es de alguien y la
+     * pregunta se hace en su nombre.
+     *
+     * 🔥 Y por eso no vale «que el nodo pida el token y liste él». Ese token abre
+     * el servidor entero; lo que el nodo necesita es la lista de canales. Sacar
+     * el secreto para derivar una lista es justo lo que este contrato existe para
+     * no hacer.
+     */
+    canalesDeDiscord(id: string, orgId: string, quien: QuienPide): Promise<DiscordChannelSummary[]>;
+    /**
+     * Un access token fresco de un proveedor cuyo `client_secret` vive en el
+     * gateway.
+     *
+     * 🔥 Por esto los cinco servicios de OAuth NO se mudan. Refrescar necesita el
+     * secreto de NUESTRA app, y ése no puede salir a `hw-nodes`: si saliera, cada
+     * nodo tendría con qué hacerse pasar por la aplicación entera. Lo que cruza
+     * es el token ya refrescado, que sirve para una cuenta y caduca.
+     *
+     * ⚠️ `staleToken` no es un detalle: es el token que ACABA de recibir un 401.
+     * Distinguirlo del guardado es lo que evita gastar una rotación cuando otro
+     * proceso ya refrescó — y en Shopify las rotaciones son finitas.
+     *
+     * Devuelve `null` cuando no hay nada que refrescar (una app custom, un token
+     * que no caduca, una credencial que ya no existe). `null` es una respuesta,
+     * no un fallo: el llamante sigue con el token que tenía.
+     */
+    refrescarTokenDeProveedor(proveedor: ProveedorConRefresco, params: {
+        credentialId: string;
+        orgId: string;
+        staleToken: string;
+    }): Promise<string | null>;
+    /**
+     * Apaga las credenciales de una tienda que desinstaló la app.
+     *
+     * ⚠️ La tienda sale de la CREDENCIAL, nunca de la cabecera del webhook: si
+     * no, la cabecera decidiría a quién se le apaga la conexión. Devuelve cuántas
+     * se marcaron, que es lo que el llamante apunta en telemetría.
+     */
+    marcarTiendaDesinstalada(shop: string, orgId: string): Promise<number>;
+    /**
+     * Un access token VIVO de Slack o Atlassian, refrescado si hacía falta.
+     *
+     * ⚠️ Lleva `quien` porque esto SÍ es una lectura: entrega al llamante una
+     * credencial usable, y esa entrega tiene que quedar en el registro de
+     * accesos.
+     *
+     * 🔥 Y hasta ahora no quedaba. Estos dos servicios se saltan `getDecrypted`
+     * a propósito —necesitan el documento crudo para guardar el token
+     * refrescado— y sólo sellaban `lastUsedAt`. O sea que cada resolución de
+     * token de Slack o Jira era INVISIBLE para el registro, con `quien` o sin él.
+     * El adaptador lo apunta ahora explícitamente.
+     */
+    tokenDeProveedor(proveedor: ProveedorConToken, id: string, orgId: string, quien: QuienPide): Promise<string>;
+    /**
+     * Los datos del espacio de Slack conectado.
+     *
+     * ⚠️ SIN `quien`, y no por descuido: no devuelve nada con lo que
+     * autenticarse. El id del equipo y el nombre del espacio son los mismos que
+     * el panel ya enseña en la tarjeta de la credencial.
+     */
+    espacioDeSlack(id: string, orgId: string): Promise<{
+        teamId: string;
+        teamName: string;
+        botUserId: string;
+        scopes: string[];
+    }>;
+    /**
+     * Un installation token de la GitHub App, ya acuñado.
+     *
+     * 🔥 La llave privada de una GitHub App es el secreto más gordo que tenemos:
+     * con ella se firma un JWT como la aplicación y se acuñan tokens para
+     * CUALQUIER instalación — todas las de todos los clientes. Lo que sale de
+     * aquí es un token de UNA instalación que caduca en una hora.
+     *
+     * ⚠️ Esto no existía y el api tenía la llave. Era una incoherencia con Slack
+     * y Atlassian, que sí pasaron por el contrato con este mismo razonamiento,
+     * y encima con el secreto más peligroso de los tres. Ver el PR que lo trajo.
+     *
+     * Y de paso el api deja de ver el blob descifrado: antes pedía `material` y
+     * se lo pasaba a `tokenFor`. Ahora no pide ni el secreto ni la llave.
+     */
+    tokenDeInstalacionDeGithub(id: string, orgId: string, quien: QuienPide): Promise<string>;
+    /**
+     * Las credenciales de una organización, para que el agente pueda nombrarlas.
+     *
+     * ⚠️ `id`, `name` y `type`, y NADA más. El llamante hacía
+     * `.select('name type')` contra el modelo — la barrera estaba en la consulta
+     * y no en el serializador, a propósito, para que no dependiera de que nadie
+     * rompiera un `toJSON`. Aquí la barrera es el tipo: `encryptedData` y
+     * `metadata` (host, correo, URL del servidor…) no existen en la respuesta.
+     */
+    credencialesDeLaOrganizacion(orgId: string): Promise<Array<{
+        id: string;
+        name: string;
+        type: string;
+    }>>;
+    /**
+     * Qué carpetas de credencial ve esta persona, y cuántas hay en total.
+     *
+     * ⚠️ Los dos números juntos porque el llamante necesita los dos y por una
+     * razón concreta: si ve TODAS, no hay que filtrar nada y se ahorra el filtro
+     * entero. Pedirlos por separado eran dos viajes y una carrera entre ellos.
+     *
+     * 🔥 Y quita un acceso CRUDO a la colección: `canvas` contaba con
+     * `connection.collection('credentialfolders')`. Eso es el gateway leyendo
+     * una tabla que ya no es suya.
+     */
+    carpetasDeCredencialAccesibles(userId: string, orgId: string): Promise<{
+        total: number;
+        accesibles: string[];
+    }>;
+    /**
+     * Las credenciales que el lienzo enseña, ya recortadas.
+     *
+     * 🔥 Esto NO entraba por un import, y por eso se me escapó tres veces: el
+     * lienzo barre un mapa de nombres de colección y `credentials` era una
+     * entrada más. Medir por imports no lo veía.
+     *
+     * ⚠️ Y lo importante no es de dónde salen los datos, es **quién decide qué se
+     * esconde**. Hoy lo decidía el gateway: aplicaba una proyección y luego
+     * recortaba `metadata` de las credenciales sensibles. Esa regla es del dueño
+     * del dato, y el dueño es este contrato. Dos sitios decidiendo qué es
+     * sensible es uno que se queda atrás.
+     *
+     * `carpetas` es la lista de carpetas que la persona puede abrir, o `null` si
+     * las ve todas. `folderId: null` —«Sin carpeta»— es visible para cualquiera.
+     */
+    credencialesParaElLienzo(orgId: string, carpetas: string[] | null): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Refresca el token de LA APP de Atlassian, la del Marketplace.
+     *
+     * ⚠️ No es la credencial de nadie: `atlassian-privacy` tiene su propia
+     * colección, con el token que HostWebhook usa para las llamadas de app que
+     * Atlassian exige (borrado de datos personales). Sólo reusaba el intercambio
+     * OAuth, que necesita el `client_secret` de nuestra app.
+     *
+     * 🔥 Y por eso pasa por aquí, como Slack, Shopify y la GitHub App: lo que
+     * cruza es el token refrescado, que vale para una cuenta y caduca. El
+     * `client_secret` —que sirve para cualquiera— no sale de este servicio.
+     *
+     * Devuelve `null` si no hay nada que refrescar; el llamante sigue con lo que
+     * tenía en vez de quedarse sin token.
+     */
+    refrescarTokenDeAppDeAtlassian(oauth: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    /** El sitio de Atlassian conectado. Mismo criterio: metadatos, no secreto. */
+    sitioDeAtlassian(id: string, orgId: string): Promise<{
+        cloudId: string;
+        siteUrl: string;
+        siteName: string;
+    }>;
+    /** La URL de webhook entrante que Slack dio al conectar, si la hay. */
+    urlDeWebhookDeSlack(id: string, orgId: string): Promise<string | null>;
+    /**
+     * Los ids de las credenciales de un espacio de Slack.
+     *
+     * 🔥 Ids y organización, NO documentos. El método del gateway devuelve
+     * `CredentialDocument[]` —con el blob cifrado dentro— y los llamantes usan el
+     * `_id` y, en un sitio, el `organizationId`. Mandar el documento por la red
+     * habría sacado el secreto de todo un espacio para no usarlo.
+     *
+     * ⚠️ La primera versión devolvía sólo `string[]` y `tsc` la tumbó: un tercer
+     * llamante emite telemetría POR ORGANIZACIÓN. Medir dos usos y no el tercero
+     * es cómo un contrato nace ya corto.
+     *
+     * ⚠️ Y sin `orgId`, que es lo raro y es correcto: el evento entrante de Slack
+     * sólo trae `team_id`, y de ESO se deduce la organización. Es la única
+     * búsqueda del contrato que va al revés.
+     */
+    credencialesDeEquipoDeSlack(teamId: string): Promise<Array<{
+        id: string;
+        organizationId: string;
+    }>>;
+    /**
+     * Las credenciales de un tipo, para elegir cuenta.
+     *
+     * 🔥 Sólo `id` y `name`, que es lo único que el llamante usa. El método del
+     * gateway devuelve la página entera de documentos —con `encryptedData`
+     * dentro— y quien la pedía hacía `data.map((c) => ({ id, name }))` y tiraba
+     * el resto. Por la red eso habría sacado hasta 50 secretos para enseñar una
+     * lista de nombres.
+     *
+     * ⚠️ Sin `quien` y sin `purpose`: no descifra nada. Es la lista que el panel
+     * ya enseña.
+     */
+    credencialesDeTipo(orgId: string, tipo: CredentialType): Promise<Array<{
+        id: string;
+        name: string;
+    }>>;
+    /**
+     * La configuración con la que el AI Node habla con un servidor MCP.
+     *
+     * ⚠️ Éste SÍ es método del contrato y `configDeOllama` no, aunque se
+     * parezcan. Ollama es derivación pura del material —parsear y validar— y se
+     * hace del lado del nodo. Éste, cuando el blob trae `oauth`, delega en
+     * `McpOAuthService` para REFRESCAR el token, y eso necesita el secreto de la
+     * app, que no sale del gateway. Derivar no es refrescar: es la misma
+     * distinción que costó cara en Google.
+     */
+    configDeMcp(id: string, orgId: string, quien: QuienPide, purpose: string): Promise<{
+        url: string;
+        authHeader?: string;
+    }>;
+    /**
+     * La sesión mínima con la que un nodo social puede llamar a su API.
+     *
+     * ⚠️ `red` NO es una comodidad: es el `tipoEsperado` de `material()`. El
+     * gateway lo traduce al `CredentialType` que toca y comprueba ANTES de
+     * descifrar, así que la credencial equivocada no se descifra ni deja fila en
+     * el registro. Y es lo que estrecha el tipo de vuelta.
+     *
+     * ⚠️ El nombre dice «sesión» y no «token» a propósito. Sólo en X hay trabajo
+     * de refresco aquí dentro —2 h de vida, rotación con el `client_secret` de
+     * HostWebhook, y la rotación se PERSISTE—. En las otras seis esto devuelve
+     * lo guardado, estrechado: si el token está muerto, la primera señal es el
+     * 401 de la API. Threads y Meta los renuevan crones del gateway, fuera de
+     * aquí.
+     *
+     * ⚠️ NO cachear el resultado del lado del nodo. El cron de Meta reescribe el
+     * blob por debajo y `setAuthor`/`refreshOrganizations` de LinkedIn cambian
+     * el `authorUrn` que el despacho lee. Este contrato no tiene invalidación.
+     */
+    sesionSocial<R extends RedSocial>(red: R, id: string, orgId: string, quien: QuienPide, purpose: string): Promise<SesionDe<R>>;
+    /**
+     * Un access token de Google, ya refrescado.
+     *
+     * ⚠️ Esto reemplaza a `getGoogleAuthClient`, que devolvía un `OAuth2Client`
+     * VIVO. Ese objeto no cruza una red — pero tampoco hace falta que cruce: el
+     * método original son doce líneas que piden un token y hacen
+     * `new google.auth.OAuth2()`. La fábrica se queda del lado del nodo
+     * (`clienteDeGoogle`, aquí al lado) y lo que viaja es la cadena.
+     */
+    tokenDeGoogle(id: string, orgId: string, quien: QuienPide, purpose: string): Promise<string>;
+}
+/**
+ * Traduce `QuienPide` a lo que el registro de accesos entiende hoy.
+ *
+ * ⚠️ Y comprueba el id vacío, que es el agujero que el tipo no puede cerrar.
+ * Devuelve también si la atribución es utilizable, para que el adaptador lo
+ * apunte en vez de dejarlo pasar callando.
+ */
+export declare function comoAtribuir(quien: QuienPide): {
+    relatedEntity?: {
+        type: string;
+        id: string;
+    };
+    userId?: string;
+    sourceIp?: string;
+    motivo?: MotivoSinComprobar;
+    sirve: boolean;
+};
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+/**
+ * La credencial existe, pero no es del tipo que el llamante pide.
+ *
+ * ⚠️ Extiende `BadRequestException` A PROPÓSITO: mismo estado y mismo texto que
+ * lanzaba el adaptador, así que las familias que YA pasan `tipoEsperado` —mongo,
+ * postgres, las memorias del AI Node— no cambian ni una letra. Lo que añade es
+ * un `instanceof` con el que un llamante puede volver a poner SU mensaje.
+ *
+ * ## Por qué hacía falta
+ *
+ * `tipoEsperado` no es una comodidad: es dónde se comprueba, y comprobar en el
+ * gateway es lo que evita descifrar una credencial que se va a rechazar. Pero
+ * los helpers de Mailchimp y Shopify lanzaban un `ForbiddenException` con un
+ * mensaje accionable en inglés —«Connect a Shopify store from Settings →
+ * Credentials»— que SALE POR LA API al usuario. Pasar `tipoEsperado` cambiaba
+ * el mensaje y el código HTTP; no pasarlo obligaba a descifrar primero, que es
+ * peor que hoy. Con el `instanceof`, el llamante recupera su mensaje sin
+ * renunciar a la comprobación temprana.
+ *
+ * ⚠️ Lo que NUNCA hay que hacer es olfatear la prosa del mensaje con un regex:
+ * el texto del adaptador no es contrato, y el día que se reescriba, el `catch`
+ * deja de reconocerlo EN SILENCIO.
+ *
+ * ⚠️ Y `instanceof` no cruza HTTP. El día que esta costura sea red, la clase
+ * hay que rehidratarla desde el código de estado en el cliente del transporte.
+ * Es UN sitio y está a la vista; olfatear la prosa serían N escondidos.
+ */
+/**
+ * 🔥 El discriminador que hace que la clase sobreviva al cable.
+ *
+ * `instanceof` no cruza HTTP, y el código de estado tampoco basta: esta
+ * excepción es un **400**, igual que la validación de entrada y media docena
+ * de errores más de hw-credentials. Rehidratar «por el 400» convertiría
+ * cualquier petición mal formada en «la credencial es de otro tipo».
+ *
+ * ⚠️ Y lo que NUNCA hay que hacer es olfatear la prosa del mensaje: el texto
+ * no es contrato, y el día que se reescriba el `catch` deja de reconocerlo EN
+ * SILENCIO. Por eso va un campo propio en el CUERPO.
+ */
+export declare const MOTIVO_TIPO_EQUIVOCADO = "credencial-de-tipo-equivocado";
+export declare class CredencialDeTipoEquivocado extends BadRequestException {
+    readonly credentialId: string;
+    readonly tipoReal: string;
+    readonly tiposEsperados: readonly string[];
+    constructor(credentialId: string, tipoReal: string, tiposEsperados: readonly string[]);
+}
+export declare const CREDENCIALES_DEL_GATEWAY = "CREDENCIALES_DEL_GATEWAY";
+/**
+ * El túnel por el que hay que salir para esta credencial, si lo hay.
+ *
+ * ⚠️ Deliberadamente NO es un método del contrato. `getTunnelIdForCredential`
+ * lo era en el gateway, y al medirlo resultó ser `metadata.tunnelId` y nada
+ * más — y `describir()` ya trae `metadata`. Añadir un método habría sido una
+ * llamada de red por cada consulta para leer un campo que ya venía en la
+ * anterior.
+ *
+ * Vive aquí y no repetido en los cinco sitios que lo derivan porque «leer un
+ * campo de un mapa» es exactamente donde una copia se queda con el nombre
+ * viejo el día que el campo cambie.
+ */
+export declare function tunelDe(cred: {
+    metadata?: Record<string, unknown>;
+}): string | null;