@hostwebhook/platform-contracts 0.1.0 → 0.3.0

package/dist/servicios/avisos-en-vivo.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Lo que un nodo le manda decir al panel. Nada más.
+ *
+ * ## Por qué
+ *
+ * Costura de la Fase 2. `nodes/` y `common/` importaban `ingress/` 18 veces, y
+ * las 18 apuntaban a la MISMA clase:
+ *
+ *   10  `WebhookGateway`         el gateway de Socket.IO
+ *    8  `WebhookGatewayModule`   cableado, desaparece con la mudanza
+ *
+ * `WebhookGateway` es un `@WebSocketGateway` de 2000 líneas: mantiene el
+ * servidor de sockets, las salas por organización, la autenticación de cada
+ * conexión —con sus modelos de `Token`, `User` y `ApiKey`—, el túnel de
+ * desarrollo y las peticiones HTTP en espera. Nada de eso puede vivir en
+ * `hw-nodes`: quien tiene abiertos los sockets del panel es el gateway.
+ *
+ * Lo que el nodo necesita es mucho menos: **decir que algo ha pasado**.
+ *
+ * ## Lo que ya estaba bien
+ *
+ * Los diez métodos reciben datos planos, y no por casualidad: los llamantes
+ * ya hacen `.toJSON()` o pasan por `comoObjetoPlano(...)` antes de emitir.
+ * Aquí no hay ningún documento de Mongoose que aplanar — algo que en la
+ * costura de ficheros costó un adaptador entero.
+ *
+ * ⚠️ Por eso las cargas se declaran `object` y NO `Record<string, unknown>`,
+ * que fue lo primero que escribí. Una firma de índice hace el contrato MÁS
+ * ESTRICTO que la realidad: rechaza lo que devuelve `.toJSON()` de Mongoose
+ * —que no la tiene— y también una interfaz declarada como `PipelineStep`.
+ * Trece errores de compilación que no señalaban ningún dato mal formado,
+ * sólo un contrato mal escrito. Es la segunda vez en esta fase.
+ *
+ * ⚠️ Y una que el inventario evitó: un `grep` de `gateway.<algo>` sacaba
+ * `subscribe` y `unsubscribe` de más. Son de `DiscordGatewayService`, otra
+ * clase que en `discord.provider` también se llama `gateway`. Medir por el
+ * TIPO inyectado y no por el nombre de la propiedad es lo que los descarta.
+ *
+ * ## ⚠️ Nueve avisan, uno CONTESTA
+ *
+ * Nueve de los diez son difusión a la sala `org:<id>`: se mandan y no se
+ * espera nada. Si se pierde uno, el panel enseña un dato viejo hasta que
+ * alguien recargue — molesto y nada más.
+ *
+ * `resolveSyncWaiter` no. Ése completa una **petición HTTP que el gateway
+ * tiene retenida** (el modo síncrono de un webhook): al otro lado hay alguien
+ * esperando una respuesta. Si ese mensaje se pierde, el que llamó se queda
+ * colgado hasta que salte el 408 de `waitForSync`.
+ *
+ * Va en el mismo contrato porque hoy es la misma inyección y su único
+ * llamante es el motor, pero quien implemente esto por red tiene que tratarlo
+ * distinto: los nueve pueden ser «dispara y olvida», éste no.
+ */
+/** Un aviso en vivo al panel de la organización. */
+export interface AvisosEnVivo {
+    emitNewEvent(webhookId: string, orgId: string, evento: object): void;
+    emitEventUpdate(webhookId: string, orgId: string, evento: object): void;
+    emitWebhookUpdate(webhookId: string, orgId: string, webhook: object): void;
+    /** Un paso de pipeline terminó. */
+    emitPipelineStep(orgId: string, paso: object): void;
+    /**
+     * Un nodo FUENTE recibió algo.
+     *
+     * Evento propio y no `pipeline:step` porque un webhook recibiendo tráfico
+     * no ejecuta un paso, y fabricarle uno falso ensucia a quien escucha pasos
+     * de verdad.
+     */
+    emitNodePayload(orgId: string, data: {
+        nodeType: string;
+        nodeId: string;
+        lastPayload: unknown;
+        /** Datos de ejemplo adoptados a mano; viaja aparte del payload. */
+        example?: boolean;
+    }): void;
+    /** Un trigger acaba de recibir algo de su proveedor. */
+    emitTriggerActivity(orgId: string, data: {
+        nodeId: string;
+        lastPushAt: string;
+    }): void;
+    emitApprovalUpdate(orgId: string, data: {
+        type: 'created' | 'resolved';
+        pendingApproval: object;
+    }): void;
+    emitSwRunComplete(orgId: string, swId: string, run: object): void;
+    /**
+     * Un contador de uso cambió. Sin payload: quien escucha vuelve a pedir
+     * `GET /auth/me/usage`.
+     */
+    emitUsageInvalidate(orgId: string): void;
+    /**
+     * ⚠️ Contesta una petición HTTP que el gateway tiene RETENIDA.
+     *
+     * No es difusión. Al otro lado hay un cliente esperando la respuesta de un
+     * webhook en modo síncrono; perder este mensaje lo deja colgado hasta el
+     * 408 de `waitForSync`. Los otros nueve pueden ser «dispara y olvida»; éste
+     * necesita entrega, y por eso está escrito aparte y no mezclado arriba.
+     */
+    resolveSyncWaiter(eventId: string, resultado: {
+        status: number;
+        body: Record<string, unknown>;
+    }): void;
+}
+/**
+ * ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2.
+ */
+export declare const AVISOS_EN_VIVO = "AVISOS_EN_VIVO";

package/dist/servicios/avisos-en-vivo.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Lo que un nodo le manda decir al panel. Nada más.
+ *
+ * ## Por qué
+ *
+ * Costura de la Fase 2. `nodes/` y `common/` importaban `ingress/` 18 veces, y
+ * las 18 apuntaban a la MISMA clase:
+ *
+ *   10  `WebhookGateway`         el gateway de Socket.IO
+ *    8  `WebhookGatewayModule`   cableado, desaparece con la mudanza
+ *
+ * `WebhookGateway` es un `@WebSocketGateway` de 2000 líneas: mantiene el
+ * servidor de sockets, las salas por organización, la autenticación de cada
+ * conexión —con sus modelos de `Token`, `User` y `ApiKey`—, el túnel de
+ * desarrollo y las peticiones HTTP en espera. Nada de eso puede vivir en
+ * `hw-nodes`: quien tiene abiertos los sockets del panel es el gateway.
+ *
+ * Lo que el nodo necesita es mucho menos: **decir que algo ha pasado**.
+ *
+ * ## Lo que ya estaba bien
+ *
+ * Los diez métodos reciben datos planos, y no por casualidad: los llamantes
+ * ya hacen `.toJSON()` o pasan por `comoObjetoPlano(...)` antes de emitir.
+ * Aquí no hay ningún documento de Mongoose que aplanar — algo que en la
+ * costura de ficheros costó un adaptador entero.
+ *
+ * ⚠️ Por eso las cargas se declaran `object` y NO `Record<string, unknown>`,
+ * que fue lo primero que escribí. Una firma de índice hace el contrato MÁS
+ * ESTRICTO que la realidad: rechaza lo que devuelve `.toJSON()` de Mongoose
+ * —que no la tiene— y también una interfaz declarada como `PipelineStep`.
+ * Trece errores de compilación que no señalaban ningún dato mal formado,
+ * sólo un contrato mal escrito. Es la segunda vez en esta fase.
+ *
+ * ⚠️ Y una que el inventario evitó: un `grep` de `gateway.<algo>` sacaba
+ * `subscribe` y `unsubscribe` de más. Son de `DiscordGatewayService`, otra
+ * clase que en `discord.provider` también se llama `gateway`. Medir por el
+ * TIPO inyectado y no por el nombre de la propiedad es lo que los descarta.
+ *
+ * ## ⚠️ Nueve avisan, uno CONTESTA
+ *
+ * Nueve de los diez son difusión a la sala `org:<id>`: se mandan y no se
+ * espera nada. Si se pierde uno, el panel enseña un dato viejo hasta que
+ * alguien recargue — molesto y nada más.
+ *
+ * `resolveSyncWaiter` no. Ése completa una **petición HTTP que el gateway
+ * tiene retenida** (el modo síncrono de un webhook): al otro lado hay alguien
+ * esperando una respuesta. Si ese mensaje se pierde, el que llamó se queda
+ * colgado hasta que salte el 408 de `waitForSync`.
+ *
+ * Va en el mismo contrato porque hoy es la misma inyección y su único
+ * llamante es el motor, pero quien implemente esto por red tiene que tratarlo
+ * distinto: los nueve pueden ser «dispara y olvida», éste no.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AVISOS_EN_VIVO = void 0;
+/**
+ * ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2.
+ */
+exports.AVISOS_EN_VIVO = 'AVISOS_EN_VIVO';

package/dist/servicios/canal-de-stream.d.ts

@@ -0,0 +1,78 @@
+/**
+ * El canal por el que el ejecutor le va dando trozos a una respuesta que el
+ * gateway tiene RETENIDA.
+ *
+ * ## De dónde sale la forma
+ *
+ * No es difusión. Es el mismo gesto que `resolveSyncWaiter` en
+ * `avisos-en-vivo.ts`, y su comentario lo dice mejor que yo:
+ *
+ *   «Contesta una petición HTTP que el gateway tiene RETENIDA. No es difusión.
+ *    Al otro lado hay un cliente esperando la respuesta.»
+ *
+ * Aquí es un SSE en vez de una respuesta única: el widget de chat mantiene
+ * abierta una conexión y el nodo de IA le manda tokens según los produce.
+ *
+ * ## ⚠️ Por qué NO se reusa `AVISOS_EN_VIVO`
+ *
+ * Porque ese contrato es «un aviso en vivo **al panel de la organización**» y
+ * todo lo suyo va con `orgId`. El visitante de un chat NO es el panel: es
+ * alguien anónimo en la web de un cliente. Mandar sus tokens por una sala de
+ * organización sería una fuga.
+ *
+ * La clave aquí es el STREAM, no la organización.
+ *
+ * ## ⚠️ Y por qué el gateway se queda el SSE
+ *
+ * Se valoró que el widget conectara directo al ejecutor. Se descartó: la puerta
+ * del chat es `@Public()` —sin sesión, porque es un widget en la web de un
+ * cliente—, así que eso le pondría una puerta pública y sin autenticar al
+ * servicio que corre el Code Node con código del usuario. Y habría que
+ * duplicar el control de orígenes, que ya avisa de que «un cliente que no sea
+ * un navegador ignora las cabeceras».
+ *
+ * Una sola puerta pública. El coste es un salto por trozo sobre conexión
+ * persistente, y el ritmo lo pone el modelo, no la red.
+ */
+/**
+ * Lo que viaja por el stream.
+ *
+ * ⚠️ Se declara AQUÍ y no se importa de `ai-nodes`: es lo que cruza la
+ * frontera, así que su forma es parte del contrato y no del ejecutor. Y son
+ * datos planos —cadenas, números, un booleano—, que es lo que hace que pueda
+ * cruzar.
+ */
+export type EventoDeStream = {
+    event: 'token';
+    data: {
+        text: string;
+    };
+} | {
+    event: 'tool_start';
+    data: {
+        name: string;
+        input: Record<string, unknown>;
+    };
+} | {
+    event: 'tool_end';
+    data: {
+        name: string;
+        output: string;
+        success: boolean;
+        durationMs: number;
+    };
+};
+/**
+ * Lo que escribe un trozo en el SSE. Es un callback y por eso NO viaja: quien
+ * lo tiene es el gateway, que sostiene la respuesta.
+ */
+export type EmisorDeStream = (evento: EventoDeStream) => void | Promise<void>;
+export interface CanalDeStream {
+    /**
+     * Un trozo para ese stream. Si nadie lo escucha, se tira sin ruido: quien
+     * cerró la pestaña no es un error.
+     */
+    emitir(streamId: string, evento: EventoDeStream): void;
+}
+/** ⚠️ Cadena y no `Symbol`. */
+export declare const CANAL_DE_STREAM = "CANAL_DE_STREAM";

package/dist/servicios/canal-de-stream.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CANAL_DE_STREAM = void 0;
+/** ⚠️ Cadena y no `Symbol`. */
+exports.CANAL_DE_STREAM = 'CANAL_DE_STREAM';

package/dist/servicios/conversaciones-del-chat.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Las conversaciones de un chat trigger, por repositorio.
+ *
+ * ## Por qué costó más que las otras trece
+ *
+ * Las demás costuras invertían un servicio. Ésta y la de entregas invierten el
+ * acceso directo a una COLECCIÓN, y ésta además **mutaba el documento vivo**:
+ *
+ *     const existing = await this.conversationModel.findOne({...});
+ *     existing.messages.push(userMsg);
+ *     existing.expiresAt = expiresAt;
+ *     await existing.save();
+ *
+ * Eso no es una consulta que se pueda mover: es un documento de Mongoose
+ * cambiando en memoria y guardándose. Por eso quedó fuera del lote del #468 —
+ * cerrarla obliga a decidir de quién es la colección.
+ *
+ * La respuesta, mirando lo que se hace con ella: es del gateway. El panel
+ * lista conversaciones, la retención se administra desde `plans/` con
+ * `chatConversationRetentionDays`, y el índice TTL vive en su entidad. El nodo
+ * escribe turnos y los vuelve a leer.
+ *
+ * ## Y de paso arregla algo que ya estaba anotado
+ *
+ * El llamante de `upsert` tenía este comentario:
+ *
+ *   *«Plainify each entry so we don't leak Mongoose subdocument refs (parent,
+ *   `$__`, `_doc`, …) into the payload — those circular refs blow up recursive
+ *   walkers like extractAttachments / template renderers with "Maximum call
+ *   stack size exceeded"».*
+ *
+ * O sea que ya se estaba aplanando a mano, después de recibir el documento,
+ * porque no hacerlo reventaba. El repositorio devuelve datos planos y ese
+ * peligro desaparece en origen en vez de esquivarse en cada llamante.
+ *
+ * ## ⚠️ Lo que no se puede perder
+ *
+ * - **`expiresAt` se refresca en CADA turno de usuario.** La ventana de
+ *   retención rueda con la actividad; sin eso, una sesión larga caduca a mitad
+ *   de conversación. `null` significa «no caduca» (plan enterprise).
+ * - **El dedupe de voz.** Los SDK de voz repiten la transcripción final, así
+ *   que un turno idéntico al último —mismo rol y mismo contenido recortado— no
+ *   se añade. Sin eso el transcript sale duplicado.
+ * - **Los borradores pendientes son la memoria entre turnos.** Es lo que deja
+ *   al modelo entender un «confirma» que llega en el turno siguiente.
+ */
+/** Un turno del transcript. `mode` ausente significa texto. */
+export interface MensajeDeConversacion {
+    role: string;
+    content: string;
+    mode?: 'voice';
+}
+/** Un borrador que quedó a medias y espera confirmación. */
+export interface BorradorPendiente {
+    draftId: string;
+    operation: string;
+    subject?: string;
+    createdAt: Date;
+}
+/** Una conversación, plana. */
+export interface Conversacion {
+    id: string;
+    sessionId: string;
+    title?: string;
+    messages: MensajeDeConversacion[];
+    pendingDrafts: BorradorPendiente[];
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+export interface RepositorioDeConversaciones {
+    /** La lista paginada del panel, con su total. */
+    listarPorTrigger(triggerId: string, opts: {
+        offset: number;
+        limit: number;
+    }): Promise<{
+        datos: Conversacion[];
+        total: number;
+    }>;
+    /** ⚠️ `null` si no existe o no es de ese trigger; el llamante decide el 404. */
+    buscarPorId(conversationId: string, triggerId: string): Promise<Conversacion | null>;
+    /**
+     * Un turno de usuario: lo añade a la sesión, o la crea.
+     *
+     * ⚠️ `expiresAt` se escribe SIEMPRE, exista ya la conversación o no: es lo
+     * que hace rodar la ventana de retención con la actividad.
+     */
+    guardarTurnoDeUsuario(params: {
+        orgId: string;
+        chatTriggerId: string;
+        sessionId: string;
+        title?: string;
+        mensaje: MensajeDeConversacion;
+        /** `null` = no caduca. */
+        expiresAt: Date | null;
+    }): Promise<Conversacion>;
+    /**
+     * Un turno de voz.
+     *
+     * ⚠️ Devuelve `anadido: false` cuando el turno es idéntico al último —mismo
+     * rol y mismo contenido recortado—. Los SDK de voz repiten la transcripción
+     * final y sin eso el transcript sale duplicado.
+     */
+    guardarTurnoDeVoz(params: {
+        orgId: string;
+        chatTriggerId: string;
+        sessionId: string;
+        title: string;
+        mensaje: MensajeDeConversacion;
+        expiresAt: Date | null;
+    }): Promise<{
+        conversationId: string;
+        anadido: boolean;
+    }>;
+    /** La respuesta del asistente, al final del transcript. */
+    anadirRespuesta(conversationId: string, content: string): Promise<void>;
+    /** Lo que el widget relee al recargar la página a mitad de sesión. */
+    historialDeSesion(chatTriggerId: string, sessionId: string): Promise<{
+        conversationId: string | null;
+        messages: MensajeDeConversacion[];
+    }>;
+    /**
+     * Aplica lo que pasó con los borradores en un turno y devuelve cómo quedó.
+     *
+     * ⚠️ Se quitan los enviados y se añaden los nuevos EN ESE ORDEN, y devuelve
+     * los ids resultantes porque el llamante los registra: sin ese log no había
+     * forma de averiguar por qué el modelo vio el borrador equivocado en el
+     * turno siguiente.
+     */
+    aplicarEventosDeBorrador(conversationId: string, cambios: {
+        quitar: string[];
+        anadir: Array<{
+            draftId: string;
+            operation: string;
+            subject?: string;
+        }>;
+    }): Promise<string[]>;
+}
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+export declare const CONVERSACIONES_DEL_CHAT = "CONVERSACIONES_DEL_CHAT";

package/dist/servicios/conversaciones-del-chat.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Las conversaciones de un chat trigger, por repositorio.
+ *
+ * ## Por qué costó más que las otras trece
+ *
+ * Las demás costuras invertían un servicio. Ésta y la de entregas invierten el
+ * acceso directo a una COLECCIÓN, y ésta además **mutaba el documento vivo**:
+ *
+ *     const existing = await this.conversationModel.findOne({...});
+ *     existing.messages.push(userMsg);
+ *     existing.expiresAt = expiresAt;
+ *     await existing.save();
+ *
+ * Eso no es una consulta que se pueda mover: es un documento de Mongoose
+ * cambiando en memoria y guardándose. Por eso quedó fuera del lote del #468 —
+ * cerrarla obliga a decidir de quién es la colección.
+ *
+ * La respuesta, mirando lo que se hace con ella: es del gateway. El panel
+ * lista conversaciones, la retención se administra desde `plans/` con
+ * `chatConversationRetentionDays`, y el índice TTL vive en su entidad. El nodo
+ * escribe turnos y los vuelve a leer.
+ *
+ * ## Y de paso arregla algo que ya estaba anotado
+ *
+ * El llamante de `upsert` tenía este comentario:
+ *
+ *   *«Plainify each entry so we don't leak Mongoose subdocument refs (parent,
+ *   `$__`, `_doc`, …) into the payload — those circular refs blow up recursive
+ *   walkers like extractAttachments / template renderers with "Maximum call
+ *   stack size exceeded"».*
+ *
+ * O sea que ya se estaba aplanando a mano, después de recibir el documento,
+ * porque no hacerlo reventaba. El repositorio devuelve datos planos y ese
+ * peligro desaparece en origen en vez de esquivarse en cada llamante.
+ *
+ * ## ⚠️ Lo que no se puede perder
+ *
+ * - **`expiresAt` se refresca en CADA turno de usuario.** La ventana de
+ *   retención rueda con la actividad; sin eso, una sesión larga caduca a mitad
+ *   de conversación. `null` significa «no caduca» (plan enterprise).
+ * - **El dedupe de voz.** Los SDK de voz repiten la transcripción final, así
+ *   que un turno idéntico al último —mismo rol y mismo contenido recortado— no
+ *   se añade. Sin eso el transcript sale duplicado.
+ * - **Los borradores pendientes son la memoria entre turnos.** Es lo que deja
+ *   al modelo entender un «confirma» que llega en el turno siguiente.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONVERSACIONES_DEL_CHAT = void 0;
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+exports.CONVERSACIONES_DEL_CHAT = 'CONVERSACIONES_DEL_CHAT';

package/dist/servicios/corridas-programadas.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Lo que el motor necesita del flujo programado. UN método.
+ *
+ * ## Por qué
+ *
+ * `pipeline-run` llama a `ScheduledWorkflowsService.recordRun(swId, run)` al
+ * terminar una corrida que arrancó en un flujo programado. Es la única
+ * llamada: medido.
+ *
+ * ⚠️ Y NO es un `lastRunAt` que se pueda escribir a mano desde aquí. `recordRun`
+ * además archiva la fila en `scheduledworkflowruns` y poda a las últimas cien.
+ * Reimplementarlo del lado del motor sería una segunda copia de esa regla.
+ *
+ * ⚠️ Tiene que TERMINAR antes de que salga el marco `complete`: el panel
+ * relee el flujo cuando ese marco llega, así que apuntar después es una carrera
+ * que se pierde a veces. Por eso se espera, a diferencia de la salud del
+ * webhook.
+ */
+export interface CorridasProgramadas {
+    apuntarCorrida(swId: string, corrida: {
+        startedAt: Date;
+        completedAt: Date;
+        durationMs: number;
+        status: 'success' | 'partial' | 'failure';
+        errorMessage?: string | null;
+    }): Promise<void>;
+}
+/** ⚠️ Cadena y no `Symbol`. */
+export declare const CORRIDAS_PROGRAMADAS = "CORRIDAS_PROGRAMADAS";

package/dist/servicios/corridas-programadas.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CORRIDAS_PROGRAMADAS = void 0;
+/** ⚠️ Cadena y no `Symbol`. */
+exports.CORRIDAS_PROGRAMADAS = 'CORRIDAS_PROGRAMADAS';

package/dist/servicios/credencial/permiso-sobre-credencial.d.ts

@@ -0,0 +1,61 @@
+/**
+ * ¿Puede este usuario poner esta credencial? — la pregunta, sin la respuesta.
+ *
+ * ## Por qué existe
+ *
+ * Costura de la Fase 2. `node-controller.factory` aplicaba
+ * `@UseGuards(CredentialFolderGuard)` a los ~30 tipos de nodo, y ese guardia
+ * vive en `credentials/`: consulta la colección de credenciales y resuelve
+ * permisos de carpeta. Con eso, el factory —y con él todos los controladores
+ * de nodo— no se puede mudar a `hw-nodes` sin llevarse el dominio entero de
+ * credenciales, que es la Fase 4.
+ *
+ * ## Lo que NO se hace, y por qué
+ *
+ * Lo fácil era quitar el guardia y decir «ya autoriza el gateway al proxear».
+ * Y es defendible: la autenticación va EN el gateway por diseño.
+ *
+ * ⚠️ Pero este guardia existe **porque la comprobación se olvidó trece
+ * veces**. Su propio docblock cuenta el agujero: bastaba con leerle el id de
+ * credencial a un nodo que sí se pudiera ver, ponérselo a un nodo propio y
+ * ejecutarlo, y la credencial de la carpeta negada se descifraba igual. Y un
+ * id de Mongo no es un secreto: sale en el lienzo y en la barra del navegador.
+ *
+ * Dejar esa garantía viviendo SÓLO en el proxy es apostar a que nada alcance
+ * nunca `hw-nodes` por otro camino — una mala configuración, un servicio
+ * nuevo, una prueba. Cuando pase, el agujero vuelve, y vuelve callado.
+ *
+ * Así que la pregunta se queda y lo que se va es la RESPUESTA: `hw-nodes`
+ * preguntará por la red privada a quien tenga el dato. Una llamada por
+ * escritura de nodo que lleve credencial —crear o editar—, no por ejecución.
+ * Un salto interno es ~1 ms contra los 100-500 ms que el nodo gasta llamando
+ * a Slack o a Gmail.
+ */
+/** Los tres papeles sobre una carpeta, de menos a más. */
+export type RolDeCarpeta = 'viewer' | 'editor' | 'owner';
+export interface PreguntaDePermiso {
+    credentialId: string;
+    userId: string;
+    orgId: string;
+    rolMinimo: RolDeCarpeta;
+}
+export interface PermisoSobreCredencial {
+    /**
+     * ⚠️ Devuelve `true` cuando la credencial NO EXISTE, y eso no es un
+     * descuido: es la semántica que hay que conservar.
+     *
+     * Negar aquí daría un 403 sobre algo inexistente, y un 403 dice «existe
+     * pero no es tuya». Dejando pasar, el manejador contesta 404 como siempre y
+     * no se filtra qué ids existen — que es justo lo que este guardia protege,
+     * porque los ids circulan.
+     *
+     * O sea: `false` significa «existe y NO puedes», nunca «no la encuentro».
+     */
+    puedeUsar(pregunta: PreguntaDePermiso): Promise<boolean>;
+}
+/**
+ * ⚠️ Cadena y no `Symbol`. Un `Symbol` no sobrevive a una frontera de módulo
+ * duplicada ni a una serialización, y esto está pensado para acabar cruzando
+ * una red.
+ */
+export declare const PERMISO_SOBRE_CREDENCIAL = "PERMISO_SOBRE_CREDENCIAL";

package/dist/servicios/credencial/permiso-sobre-credencial.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * ¿Puede este usuario poner esta credencial? — la pregunta, sin la respuesta.
+ *
+ * ## Por qué existe
+ *
+ * Costura de la Fase 2. `node-controller.factory` aplicaba
+ * `@UseGuards(CredentialFolderGuard)` a los ~30 tipos de nodo, y ese guardia
+ * vive en `credentials/`: consulta la colección de credenciales y resuelve
+ * permisos de carpeta. Con eso, el factory —y con él todos los controladores
+ * de nodo— no se puede mudar a `hw-nodes` sin llevarse el dominio entero de
+ * credenciales, que es la Fase 4.
+ *
+ * ## Lo que NO se hace, y por qué
+ *
+ * Lo fácil era quitar el guardia y decir «ya autoriza el gateway al proxear».
+ * Y es defendible: la autenticación va EN el gateway por diseño.
+ *
+ * ⚠️ Pero este guardia existe **porque la comprobación se olvidó trece
+ * veces**. Su propio docblock cuenta el agujero: bastaba con leerle el id de
+ * credencial a un nodo que sí se pudiera ver, ponérselo a un nodo propio y
+ * ejecutarlo, y la credencial de la carpeta negada se descifraba igual. Y un
+ * id de Mongo no es un secreto: sale en el lienzo y en la barra del navegador.
+ *
+ * Dejar esa garantía viviendo SÓLO en el proxy es apostar a que nada alcance
+ * nunca `hw-nodes` por otro camino — una mala configuración, un servicio
+ * nuevo, una prueba. Cuando pase, el agujero vuelve, y vuelve callado.
+ *
+ * Así que la pregunta se queda y lo que se va es la RESPUESTA: `hw-nodes`
+ * preguntará por la red privada a quien tenga el dato. Una llamada por
+ * escritura de nodo que lleve credencial —crear o editar—, no por ejecución.
+ * Un salto interno es ~1 ms contra los 100-500 ms que el nodo gasta llamando
+ * a Slack o a Gmail.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PERMISO_SOBRE_CREDENCIAL = void 0;
+/**
+ * ⚠️ Cadena y no `Symbol`. Un `Symbol` no sobrevive a una frontera de módulo
+ * duplicada ni a una serialización, y esto está pensado para acabar cruzando
+ * una red.
+ */
+exports.PERMISO_SOBRE_CREDENCIAL = 'PERMISO_SOBRE_CREDENCIAL';