@hostwebhook/platform-node 0.1.0 → 0.3.0

package/dist/busqueda-literal.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Lo que se teclea en un buscador es TEXTO, no una expresión regular.
+ *
+ * ## El fallo que cierra
+ *
+ * `GET /api/credentials?search=` y `GET /api/signing-secrets?search=` metían la
+ * cadena de la query directamente en un `$regex` de MongoDB. O sea que quien
+ * llamaba elegía la expresión regular que ejecuta el motor de la base.
+ *
+ * Y el motor de Mongo resuelve por retroceso, igual que el de JavaScript:
+ *
+ *     1. se crea una credencial con `name` = 100 000 letras 'a'
+ *        (ni el DTO ni el esquema ponían tope a la longitud);
+ *     2. `GET /api/credentials?search=(a%2B)%2Bb`
+ *
+ * y `(a+)+b` contra esa cadena es exponencial. Una petición barata deja un
+ * worker de mongod girando, y la base es la MISMA para todos los inquilinos del
+ * clúster. Repitiendo hasta el tope de peticiones —que además se esquiva
+ * variando `X-Forwarded-For`, cosa que el propio `client-ip.ts` avisa de que es
+ * falsificable— la CPU no baja.
+ *
+ * Lo más llamativo es que el escape correcto ya estaba escrito noventa líneas
+ * más abajo en el mismo fichero, para el buscador de etiquetas. Estaba resuelto
+ * y copiado a medias.
+ *
+ * ## Lo que hace
+ *
+ * Escapa los metacaracteres —para que el patrón case LITERALMENTE lo que se
+ * escribió— y acota la longitud. Lo segundo importa aparte: el coste de una
+ * búsqueda crece con el patrón además de con el texto, y un buscador no
+ * necesita mil caracteres.
+ *
+ * ⚠️ El escape en sí NO vive aquí: es `escaparRegex`, en el módulo de al
+ * lado. Esta función es «escapar Y acotar»; hay un puñado de sitios que
+ * incrustan un valor interno en un patrón y no pueden recortarlo sin cambiar
+ * lo que significa, y ésos usan el primitivo pelado. Una sola expresión de
+ * escape en todo el repositorio, y dos maneras de pedirla.
+ *
+ * No se usa `$text`: exigiría un índice de texto por colección y cambiaría la
+ * semántica de «contiene» a «palabras completas», que no es lo que el panel
+ * ofrece hoy.
+ */
+/** Un buscador no necesita más. Por encima, se recorta. */
+export declare const MAX_BUSQUEDA = 200;
+/**
+ * Devuelve la cadena lista para meter en un `$regex`, casando literalmente.
+ *
+ * Se exporta también `MAX_BUSQUEDA` para que quien quiera pueda rechazar en vez
+ * de recortar; aquí se recorta porque un buscador que devuelve un error por
+ * escribir de más es peor que uno que busca por los primeros 200 caracteres.
+ */
+export declare function busquedaLiteral(bruto: unknown): string;

package/dist/busqueda-literal.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * Lo que se teclea en un buscador es TEXTO, no una expresión regular.
+ *
+ * ## El fallo que cierra
+ *
+ * `GET /api/credentials?search=` y `GET /api/signing-secrets?search=` metían la
+ * cadena de la query directamente en un `$regex` de MongoDB. O sea que quien
+ * llamaba elegía la expresión regular que ejecuta el motor de la base.
+ *
+ * Y el motor de Mongo resuelve por retroceso, igual que el de JavaScript:
+ *
+ *     1. se crea una credencial con `name` = 100 000 letras 'a'
+ *        (ni el DTO ni el esquema ponían tope a la longitud);
+ *     2. `GET /api/credentials?search=(a%2B)%2Bb`
+ *
+ * y `(a+)+b` contra esa cadena es exponencial. Una petición barata deja un
+ * worker de mongod girando, y la base es la MISMA para todos los inquilinos del
+ * clúster. Repitiendo hasta el tope de peticiones —que además se esquiva
+ * variando `X-Forwarded-For`, cosa que el propio `client-ip.ts` avisa de que es
+ * falsificable— la CPU no baja.
+ *
+ * Lo más llamativo es que el escape correcto ya estaba escrito noventa líneas
+ * más abajo en el mismo fichero, para el buscador de etiquetas. Estaba resuelto
+ * y copiado a medias.
+ *
+ * ## Lo que hace
+ *
+ * Escapa los metacaracteres —para que el patrón case LITERALMENTE lo que se
+ * escribió— y acota la longitud. Lo segundo importa aparte: el coste de una
+ * búsqueda crece con el patrón además de con el texto, y un buscador no
+ * necesita mil caracteres.
+ *
+ * ⚠️ El escape en sí NO vive aquí: es `escaparRegex`, en el módulo de al
+ * lado. Esta función es «escapar Y acotar»; hay un puñado de sitios que
+ * incrustan un valor interno en un patrón y no pueden recortarlo sin cambiar
+ * lo que significa, y ésos usan el primitivo pelado. Una sola expresión de
+ * escape en todo el repositorio, y dos maneras de pedirla.
+ *
+ * No se usa `$text`: exigiría un índice de texto por colección y cambiaría la
+ * semántica de «contiene» a «palabras completas», que no es lo que el panel
+ * ofrece hoy.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_BUSQUEDA = void 0;
+exports.busquedaLiteral = busquedaLiteral;
+const escapar_regex_1 = require("./escapar-regex");
+/** Un buscador no necesita más. Por encima, se recorta. */
+exports.MAX_BUSQUEDA = 200;
+/**
+ * Devuelve la cadena lista para meter en un `$regex`, casando literalmente.
+ *
+ * Se exporta también `MAX_BUSQUEDA` para que quien quiera pueda rechazar en vez
+ * de recortar; aquí se recorta porque un buscador que devuelve un error por
+ * escribir de más es peor que uno que busca por los primeros 200 caracteres.
+ */
+function busquedaLiteral(bruto) {
+    if (typeof bruto !== 'string' || bruto.length === 0)
+        return '';
+    return (0, escapar_regex_1.escaparRegex)(bruto.slice(0, exports.MAX_BUSQUEDA));
+}

package/dist/escapar-regex.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Lo que escribe el usuario es TEXTO, no un patrón.
+ *
+ * Sin escapar pasan dos cosas, y ninguna es «no encuentra nada»: un
+ * paréntesis suelto hace que Mongo rechace la consulta entera con un error
+ * de sintaxis, y un patrón anidado del tipo «grupo repetido dentro de grupo
+ * repetido» se convierte en un ReDoS — el regex lo evalúa el servidor de
+ * base de datos, así que quien se queda colgado es él, no el proceso que
+ * recibió la petición.
+ *
+ * ⚠️ **Ésta es la única expresión regular de escape del repositorio.** No
+ * escribas otra: `busquedaLiteral` la usa, y todo lo demás usa una de las
+ * dos. Cuál de las dos:
+ *
+ *  - `busquedaLiteral` — texto que teclea alguien en un buscador. Escapa
+ *    **y acota** la longitud, porque el coste de la búsqueda crece con el
+ *    patrón además de con el texto. Es la que quieres casi siempre.
+ *  - `escaparRegex` (ésta) — un valor interno que se incrusta en un patrón
+ *    y que NO puede recortarse sin cambiar lo que significa.
+ *
+ * El 2026-08-27 este módulo decía que quedaban «tres copias literales» por
+ * migrar. Eran DOCE: se habían contado buscando los nombres `escapeRegex` y
+ * `escaparRegex`, y la mitad estaban escritas a pelo dentro de la consulta,
+ * sin función que buscar. Contar por el nombre no es inventariar — hay que
+ * contar por la clase de caracteres. `una-sola-copia-del-escape.spec.ts` lo
+ * cuenta ahora por ti y no deja aparecer la trece.
+ */
+export declare function escaparRegex(s: string): string;

package/dist/escapar-regex.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escaparRegex = escaparRegex;
+/**
+ * Lo que escribe el usuario es TEXTO, no un patrón.
+ *
+ * Sin escapar pasan dos cosas, y ninguna es «no encuentra nada»: un
+ * paréntesis suelto hace que Mongo rechace la consulta entera con un error
+ * de sintaxis, y un patrón anidado del tipo «grupo repetido dentro de grupo
+ * repetido» se convierte en un ReDoS — el regex lo evalúa el servidor de
+ * base de datos, así que quien se queda colgado es él, no el proceso que
+ * recibió la petición.
+ *
+ * ⚠️ **Ésta es la única expresión regular de escape del repositorio.** No
+ * escribas otra: `busquedaLiteral` la usa, y todo lo demás usa una de las
+ * dos. Cuál de las dos:
+ *
+ *  - `busquedaLiteral` — texto que teclea alguien en un buscador. Escapa
+ *    **y acota** la longitud, porque el coste de la búsqueda crece con el
+ *    patrón además de con el texto. Es la que quieres casi siempre.
+ *  - `escaparRegex` (ésta) — un valor interno que se incrusta en un patrón
+ *    y que NO puede recortarse sin cambiar lo que significa.
+ *
+ * El 2026-08-27 este módulo decía que quedaban «tres copias literales» por
+ * migrar. Eran DOCE: se habían contado buscando los nombres `escapeRegex` y
+ * `escaparRegex`, y la mitad estaban escritas a pelo dentro de la consulta,
+ * sin función que buscar. Contar por el nombre no es inventariar — hay que
+ * contar por la clase de caracteres. `una-sola-copia-del-escape.spec.ts` lo
+ * cuenta ahora por ti y no deja aparecer la trece.
+ */
+function escaparRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/escape-html.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Escapar HTML, una sola vez y en un solo sitio.
+ *
+ * Había TRES copias de esta función en el repo —en `credentials.controller`,
+ * en `approval-nodes.controller` y en `send-and-wait.controller`— idénticas
+ * carácter por carácter. Que hoy coincidan no es garantía de nada: son tres
+ * sitios donde alguien puede añadir un caso, olvidarse de los otros dos, y
+ * dejar dos escapes peores que el tercero sin que nada lo señale.
+ *
+ * Y estaba a punto de haber una cuarta, para el email de invitación.
+ *
+ * Los cinco caracteres son los de siempre, y el orden importa: `&` va primero
+ * o acabaría escapando los `&` que introducen los demás reemplazos.
+ */
+export declare function escapeHtml(valor: unknown): string;

package/dist/escape-html.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeHtml = escapeHtml;
+/**
+ * Escapar HTML, una sola vez y en un solo sitio.
+ *
+ * Había TRES copias de esta función en el repo —en `credentials.controller`,
+ * en `approval-nodes.controller` y en `send-and-wait.controller`— idénticas
+ * carácter por carácter. Que hoy coincidan no es garantía de nada: son tres
+ * sitios donde alguien puede añadir un caso, olvidarse de los otros dos, y
+ * dejar dos escapes peores que el tercero sin que nada lo señale.
+ *
+ * Y estaba a punto de haber una cuarta, para el email de invitación.
+ *
+ * Los cinco caracteres son los de siempre, y el orden importa: `&` va primero
+ * o acabaría escapando los `&` que introducen los demás reemplazos.
+ */
+function escapeHtml(valor) {
+    return String(valor)
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}

package/dist/index.d.ts

@@ -1 +1,10 @@
 export { encrypt, decrypt, type Llaves } from './crypto';
+export * from './escape-html';
+export * from './mongo-databases';
+export * from './postgres-databases';
+export * from './busqueda-literal';
+export * from './escapar-regex';
+export * from './presets-de-oauth/github-oauth-presets';
+export * from './presets-de-oauth/linkedin-oauth-presets';
+export * from './presets-de-oauth/mailchimp-oauth-presets';
+export * from './presets-de-oauth/shopify-oauth-presets';

package/dist/index.js

@@ -1,6 +1,32 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.decrypt = exports.encrypt = void 0;
 var crypto_1 = require("./crypto");
 Object.defineProperty(exports, "encrypt", { enumerable: true, get: function () { return crypto_1.encrypt; } });
 Object.defineProperty(exports, "decrypt", { enumerable: true, get: function () { return crypto_1.decrypt; } });
+__exportStar(require("./escape-html"), exports);
+__exportStar(require("./mongo-databases"), exports);
+__exportStar(require("./postgres-databases"), exports);
+__exportStar(require("./busqueda-literal"), exports);
+__exportStar(require("./escapar-regex"), exports);
+/* Los presets de OAuth: datos puros, cero dependencias externas (shopify usa el
+   `crypto` de Node, que es incorporado). Los comparten la api, `nodes/` y los
+   ayudantes de `common/` que hablan con cada plataforma. */
+__exportStar(require("./presets-de-oauth/github-oauth-presets"), exports);
+__exportStar(require("./presets-de-oauth/linkedin-oauth-presets"), exports);
+__exportStar(require("./presets-de-oauth/mailchimp-oauth-presets"), exports);
+__exportStar(require("./presets-de-oauth/shopify-oauth-presets"), exports);

package/dist/mongo-databases.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Las bases que MongoDB trae siempre y que nadie elige como destino.
+ *
+ * Vive en `common` y no junto al nodo porque la usan los dos lados y en
+ * direcciones opuestas: el nodo de Mongo al listar las bases del servidor, y
+ * `CredentialsService` al comprobar que la base tecleada en el formulario
+ * existe. Importarla desde `nodes/` en `credentials/` invertiría la
+ * dependencia (los nodos importan credenciales, no al revés).
+ */
+export declare const BASES_INTERNAS: ReadonlySet<string>;
+/**
+ * Por qué rechazar la base que declara una credencial de Mongo, o `null` si
+ * no hay motivo.
+ *
+ * ⚠️ La distinción que lo es todo: `disponibles === undefined` significa **no
+ * se pudo mirar** (credencial acotada a una base, servidor caído), y eso
+ * **nunca** bloquea. Una lista vacía sí es una respuesta. Tratar los dos
+ * casos igual impediría guardar credenciales perfectamente buenas.
+ *
+ * Existe porque `client.db("no_existe")` no falla en Mongo —las bases se
+ * crean al escribir— así que un nombre mal tecleado se guarda tan campante y
+ * después toda lectura devuelve cero, sin error. Medido el 2026-08-12: una
+ * credencial decía `my_hostwebhook_testing_database` y el servidor sólo tenía
+ * `test`.
+ */
+export declare function motivoDeBaseInvalida(pedida: string | null | undefined, disponibles: string[] | undefined): string | null;

package/dist/mongo-databases.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASES_INTERNAS = void 0;
+exports.motivoDeBaseInvalida = motivoDeBaseInvalida;
+/**
+ * Las bases que MongoDB trae siempre y que nadie elige como destino.
+ *
+ * Vive en `common` y no junto al nodo porque la usan los dos lados y en
+ * direcciones opuestas: el nodo de Mongo al listar las bases del servidor, y
+ * `CredentialsService` al comprobar que la base tecleada en el formulario
+ * existe. Importarla desde `nodes/` en `credentials/` invertiría la
+ * dependencia (los nodos importan credenciales, no al revés).
+ */
+exports.BASES_INTERNAS = new Set([
+    'admin',
+    'local',
+    'config',
+]);
+/**
+ * Por qué rechazar la base que declara una credencial de Mongo, o `null` si
+ * no hay motivo.
+ *
+ * ⚠️ La distinción que lo es todo: `disponibles === undefined` significa **no
+ * se pudo mirar** (credencial acotada a una base, servidor caído), y eso
+ * **nunca** bloquea. Una lista vacía sí es una respuesta. Tratar los dos
+ * casos igual impediría guardar credenciales perfectamente buenas.
+ *
+ * Existe porque `client.db("no_existe")` no falla en Mongo —las bases se
+ * crean al escribir— así que un nombre mal tecleado se guarda tan campante y
+ * después toda lectura devuelve cero, sin error. Medido el 2026-08-12: una
+ * credencial decía `my_hostwebhook_testing_database` y el servidor sólo tenía
+ * `test`.
+ */
+function motivoDeBaseInvalida(pedida, disponibles) {
+    const nombre = (pedida ?? '').trim();
+    if (!nombre)
+        return null;
+    if (!disponibles)
+        return null;
+    if (disponibles.includes(nombre))
+        return null;
+    return disponibles.length > 0
+        ? `Database "${nombre}" doesn't exist on this server. Available: ${disponibles.join(', ')}`
+        : `Database "${nombre}" doesn't exist on this server, and the server has no databases yet`;
+}

package/dist/postgres-databases.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Qué bases ofrece el selector del formulario de una credencial de Postgres.
+ *
+ * Aparte del servicio, como `mongo-databases.ts`, para que la consulta y el
+ * filtrado se puedan probar sin levantar un Postgres.
+ */
+/**
+ * Las bases a las que un cliente se puede conectar de verdad.
+ *
+ * Los dos filtros están por un motivo concreto, y quitarlos no rompe nada
+ * hasta que alguien elige la opción equivocada:
+ *
+ * - `datistemplate = false` deja fuera `template0` y `template1`, que son
+ *   plantillas y no destinos.
+ * - `datallowconn = true` es el que de verdad importa: **`template0` rechaza
+ *   conexiones por diseño**. Ofrecerla es ofrecer una opción que sólo puede
+ *   fallar, y el error (`FATAL: database "template0" is not currently
+ *   accepting connections`) no se parece en nada a «esa no la elijas».
+ */
+export declare const SQL_BASES_DE_POSTGRES = "SELECT datname FROM pg_database\n          WHERE datistemplate = false AND datallowconn = true\n          ORDER BY datname";
+/**
+ * Los nombres, de lo que devuelva el driver.
+ *
+ * Se valida el tipo en vez de castear: `pg` tipa las filas por lo que le
+ * digas, no por lo que llegue, así que una fila rara entraría como `undefined`
+ * y pintaría una opción vacía en el desplegable.
+ */
+export declare function nombresDeBases(filas: ReadonlyArray<{
+    datname?: unknown;
+}>): string[];

package/dist/postgres-databases.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Qué bases ofrece el selector del formulario de una credencial de Postgres.
+ *
+ * Aparte del servicio, como `mongo-databases.ts`, para que la consulta y el
+ * filtrado se puedan probar sin levantar un Postgres.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SQL_BASES_DE_POSTGRES = void 0;
+exports.nombresDeBases = nombresDeBases;
+/**
+ * Las bases a las que un cliente se puede conectar de verdad.
+ *
+ * Los dos filtros están por un motivo concreto, y quitarlos no rompe nada
+ * hasta que alguien elige la opción equivocada:
+ *
+ * - `datistemplate = false` deja fuera `template0` y `template1`, que son
+ *   plantillas y no destinos.
+ * - `datallowconn = true` es el que de verdad importa: **`template0` rechaza
+ *   conexiones por diseño**. Ofrecerla es ofrecer una opción que sólo puede
+ *   fallar, y el error (`FATAL: database "template0" is not currently
+ *   accepting connections`) no se parece en nada a «esa no la elijas».
+ */
+exports.SQL_BASES_DE_POSTGRES = `SELECT datname FROM pg_database
+          WHERE datistemplate = false AND datallowconn = true
+          ORDER BY datname`;
+/**
+ * Los nombres, de lo que devuelva el driver.
+ *
+ * Se valida el tipo en vez de castear: `pg` tipa las filas por lo que le
+ * digas, no por lo que llegue, así que una fila rara entraría como `undefined`
+ * y pintaría una opción vacía en el desplegable.
+ */
+function nombresDeBases(filas) {
+    return filas
+        .map((f) => f.datname)
+        .filter((n) => typeof n === 'string' && n.trim() !== '');
+}

package/dist/presets-de-oauth/github-oauth-presets.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Constantes y formas del OAuth de HostWebhook contra GitHub.
+ *
+ * ── Qué se guarda, y por qué es distinto a los demás proveedores ──
+ *
+ * Casi todos los proveedores de esta carpeta guardan un `access_token` del
+ * usuario y lo refrescan. Aquí NO. Lo que se guarda es un `installationId`, y
+ * **ningún secreto**: cada llamada mina un token de instalación firmando un
+ * JWT con la private key de la app, que vive en el entorno.
+ *
+ * La razón no es estética. Un token de usuario muere cuando esa persona deja
+ * la organización, y una automatización que lleva meses corriendo se cae con
+ * ella. El token de instalación pertenece a la instalación, no a quien la hizo.
+ *
+ * Consecuencia práctica: aquí no hay nada que caduque en la base de datos, y
+ * el flujo de OAuth existe para dos cosas —comprobar que el usuario autorizó y
+ * quedarse con el `installation_id` que vuelve en el callback—, no para
+ * quedarse con su token.
+ *
+ * ── Contra qué docs está escrito (verificado 2026-08-25) ──
+ *
+ *   - JWT: RS256; `iss` es el App ID (los docs admiten también el client id);
+ *     `iat` **60 segundos en el pasado** por deriva de reloj; `exp` como mucho
+ *     10 minutos en el futuro.
+ *   - Token de instalación: `POST /app/installations/{id}/access_tokens` con
+ *     el JWT en `Authorization: Bearer`. Dura **1 hora**.
+ *   - Token de usuario: 8 h (28800 s), refresh de 6 meses. No se usa más allá
+ *     del intercambio inicial — ver arriba.
+ *
+ * ── ⚠️ Las variables de entorno ──
+ *
+ * Son `GITHUB_APP_*`. `GITHUB_OAUTH_CLIENT_ID` y `GITHUB_OAUTH_CLIENT_SECRET`
+ * ya existían y son de OTRA app: la OAuth App que usa `MCP_OAUTH_PRESETS.github`
+ * para llegar al servidor MCP de GitHub. Reusar ese par rompería las dos cosas.
+ */
+export declare const GITHUB_APP_OAUTH_CONFIG: {
+    readonly authorizationEndpoint: "https://github.com/login/oauth/authorize";
+    readonly tokenEndpoint: "https://github.com/login/oauth/access_token";
+    readonly apiBase: "https://api.github.com";
+    /** La versión de la API REST que fijan todas las llamadas. Fijarla es lo que
+     *  evita que un cambio de GitHub llegue sin avisar. */
+    readonly apiVersion: "2026-03-10";
+    /** Nombres de las variables con las credenciales registradas de HW. */
+    readonly clientIdEnv: "GITHUB_APP_CLIENT_ID";
+    readonly clientSecretEnv: "GITHUB_APP_CLIENT_SECRET";
+    readonly appIdEnv: "GITHUB_APP_ID";
+    /** La private key va en base64: un PEM en crudo dentro de una variable de
+     *  entorno se parte por los saltos de línea y sólo se descubre en runtime. */
+    readonly privateKeyBase64Env: "GITHUB_APP_PRIVATE_KEY_BASE64";
+    /**
+     * El secreto con el que GitHub firma cada entrega del webhook.
+     *
+     * ⚠️ Es el mismo valor que hay escrito en **Webhook → Secret** del registro
+     * de la app en github.com. Si los dos no dicen exactamente lo mismo, TODAS
+     * las entregas se rechazan con 401 y en GitHub se ven en rojo — el síntoma
+     * es un trigger activo que no dispara nunca.
+     *
+     * Sin la variable no se deja pasar nada: un despliegue al que le falte no
+     * debe convertirse en un endpoint abierto por el que cualquiera pueda
+     * inyectar eventos. Ver `verificarFirmaGithub`.
+     */
+    readonly webhookSecretEnv: "GITHUB_APP_WEBHOOK_SECRET";
+    /** El JWT no puede pedir más de 10 minutos. Se usan 9 para dejar margen. */
+    readonly jwtLifetimeSeconds: number;
+    /** Los docs piden retrasar `iat` para absorber la deriva de reloj. */
+    readonly jwtClockSkewSeconds: 60;
+    /** Un token de instalación dura 1 h; se re-mina un minuto antes. */
+    readonly installationTokenTtlSeconds: number;
+    readonly installationTokenSafetySeconds: 60;
+};
+/** El `type` de la credencial que crea este flujo. */
+export declare const GITHUB_APP_CREDENTIAL_TYPE = "github_app";
+/** El `type` de la credencial de token pegado. Mismas operaciones, otra vía. */
+export declare const GITHUB_PAT_CREDENTIAL_TYPE = "github_pat";
+/**
+ * Lo que devuelve `POST /login/oauth/access_token`.
+ *
+ * Todo opcional a propósito: GitHub responde `200` con un cuerpo de error
+ * cuando el `code` ya se usó, así que tratar `access_token` como obligatorio
+ * convierte un error explicable en un fallo de parseo.
+ */
+export interface GithubTokenResponse {
+    access_token?: string;
+    token_type?: string;
+    scope?: string;
+    expires_in?: number;
+    refresh_token?: string;
+    refresh_token_expires_in?: number;
+    error?: string;
+    error_description?: string;
+}
+/** Lo que devuelve `POST /app/installations/{id}/access_tokens`. */
+export interface GithubInstallationTokenResponse {
+    token?: string;
+    /** ISO-8601. Una hora después de emitirlo. */
+    expires_at?: string;
+    permissions?: Record<string, string>;
+    repository_selection?: 'all' | 'selected';
+    message?: string;
+}
+/** La instalación, tal como la devuelve `GET /app/installations/{id}`. */
+export interface GithubInstallation {
+    id?: number;
+    account?: {
+        login?: string;
+        type?: string;
+        avatar_url?: string;
+    };
+    repository_selection?: 'all' | 'selected';
+    app_id?: number;
+    target_type?: string;
+}
+/**
+ * El blob cifrado de una credencial `github_app`.
+ *
+ * No lleva token. Es deliberado — ver la cabecera de este fichero.
+ */
+export interface GithubAppStoredPayload {
+    /** La instalación. Es lo único que hace falta para minar tokens. */
+    installationId: string;
+    /** La cuenta donde se instaló, para poder nombrar la credencial y para que
+     *  el usuario distinga dos instalaciones en la lista. */
+    accountLogin?: string;
+    accountType?: string;
+    /** `all` o `selected`. Cambia el texto que se le enseña al usuario cuando el
+     *  selector de repos sale corto. */
+    repositorySelection?: 'all' | 'selected';
+    authMode: 'app';
+}
+/**
+ * El blob cifrado de una credencial `github_pat`.
+ *
+ * Aquí SÍ hay un secreto del usuario, y además caduca: GitHub obliga a poner
+ * fecha a los fine-grained. Guardar la fecha permite avisar antes de que una
+ * corrida se caiga por una credencial muerta.
+ */
+export interface GithubPatStoredPayload {
+    token: string;
+    /** ISO-8601, cuando GitHub la ha dicho. */
+    expiresAt?: string | null;
+    authMode: 'pat';
+}
+export interface PendingGithubOAuthState {
+    orgId: string;
+    userId: string;
+    credentialName: string;
+    /** En reconexión, para actualizar la credencial en vez de crear otra. */
+    credentialId?: string;
+    tags?: string[];
+    /** La carpeta elegida en el formulario. Viaja por Redis entre `start` y el
+     *  callback; sin esto la elección se perdía por el camino. */
+    folderId?: string;
+    clientId: string;
+    clientSecret: string;
+    /** Marca absoluta en ms de cuándo caduca este estado pendiente. */
+    expiresAt: number;
+}
+/**
+ * A dónde se manda al usuario: a **INSTALAR**, no a autorizar.
+ *
+ * En GitHub son dos gestos distintos y sólo uno sirve para lo que hace este
+ * nodo. `/login/oauth/authorize` le da a HostWebhook permiso para actuar en su
+ * nombre; **no instala nada**, así que después no hay ninguna instalación de la
+ * que sacar un token y la conexión muere con "no lo has instalado en ninguna
+ * cuenta". Pasó en producción, con el mensaje correcto y la puerta equivocada.
+ *
+ * `/apps/{slug}/installations/new` es la buena: lleva por elegir cuenta y
+ * elegir repositorios, que es justo la promesa que le hacemos al usuario en el
+ * texto de al lado. Y con "Request user authorization (OAuth) during
+ * installation" encendido en el registro de la app, al terminar vuelve al
+ * Callback URL con el `code` — así que el resto del flujo no cambia.
+ *
+ * `state` viaja igual y vuelve igual: los docs lo contemplan explícitamente
+ * para esta URL, que es lo que permite seguir atando la vuelta con lo que
+ * guardamos en Redis.
+ *
+ * Sigue sin llevar `scope`, por lo de siempre: los permisos de una GitHub App
+ * se declaran al registrarla, y lo que el usuario elige son repos.
+ */
+export declare function buildGithubInstallUrl(params: {
+    appSlug: string;
+    state: string;
+}): string;
+/**
+ * El nombre que se ve en la lista de credenciales.
+ *
+ * Prefiere la cuenta donde se instaló, que es lo que de verdad alcanza el
+ * token y lo que necesita alguien que tenga dos instalaciones. El id suelto es
+ * el último recurso: es feo, pero es cierto y único, y gana a una fila vacía.
+ */
+export declare function githubDisplayName(inst: GithubInstallation): string;
+/**
+ * Decodifica la private key desde la variable en base64.
+ *
+ * Devuelve `null` en vez de reventar cuando falta o viene mal, para que quien
+ * llama pueda dar un mensaje que diga QUÉ variable falta. Un stack trace de
+ * `crypto` no le sirve a nadie a las tres de la mañana.
+ */
+export declare function decodeGithubPrivateKey(raw: string | undefined): string | null;