@hostwebhook/platform-node 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -4,3 +4,10 @@ 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';
+export * from './reference-id';
+export * from './rate-limiter';
+export * from './un-hueco-se-toma-de-una-vez';

package/dist/index.js

@@ -23,3 +23,19 @@ __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);
+/* `reference-id` necesita `mongoose` de verdad (`Types.ObjectId` en ejecución):
+   es la ÚNICA dependencia real del paquete, y va como `peerDependency` porque
+   todo consumidor ya la tiene.
+
+   `rate-limiter` y su ayudante sólo usan `ioredis` como TIPO, así que no pesan
+   nada en ejecución — el `Redis` se lo pasa quien llama. */
+__exportStar(require("./reference-id"), exports);
+__exportStar(require("./rate-limiter"), exports);
+__exportStar(require("./un-hueco-se-toma-de-una-vez"), exports);

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;

package/dist/presets-de-oauth/github-oauth-presets.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GITHUB_PAT_CREDENTIAL_TYPE = exports.GITHUB_APP_CREDENTIAL_TYPE = exports.GITHUB_APP_OAUTH_CONFIG = void 0;
+exports.buildGithubInstallUrl = buildGithubInstallUrl;
+exports.githubDisplayName = githubDisplayName;
+exports.decodeGithubPrivateKey = decodeGithubPrivateKey;
+exports.GITHUB_APP_OAUTH_CONFIG = {
+    authorizationEndpoint: 'https://github.com/login/oauth/authorize',
+    tokenEndpoint: 'https://github.com/login/oauth/access_token',
+    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. */
+    apiVersion: '2026-03-10',
+    /** Nombres de las variables con las credenciales registradas de HW. */
+    clientIdEnv: 'GITHUB_APP_CLIENT_ID',
+    clientSecretEnv: 'GITHUB_APP_CLIENT_SECRET',
+    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. */
+    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`.
+     */
+    webhookSecretEnv: 'GITHUB_APP_WEBHOOK_SECRET',
+    /** El JWT no puede pedir más de 10 minutos. Se usan 9 para dejar margen. */
+    jwtLifetimeSeconds: 9 * 60,
+    /** Los docs piden retrasar `iat` para absorber la deriva de reloj. */
+    jwtClockSkewSeconds: 60,
+    /** Un token de instalación dura 1 h; se re-mina un minuto antes. */
+    installationTokenTtlSeconds: 60 * 60,
+    installationTokenSafetySeconds: 60,
+};
+/** El `type` de la credencial que crea este flujo. */
+exports.GITHUB_APP_CREDENTIAL_TYPE = 'github_app';
+/** El `type` de la credencial de token pegado. Mismas operaciones, otra vía. */
+exports.GITHUB_PAT_CREDENTIAL_TYPE = 'github_pat';
+/**
+ * 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.
+ */
+function buildGithubInstallUrl(params) {
+    const qs = new URLSearchParams({ state: params.state });
+    return `https://github.com/apps/${encodeURIComponent(params.appSlug)}/installations/new?${qs.toString()}`;
+}
+/**
+ * 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.
+ */
+function githubDisplayName(inst) {
+    const login = inst.account?.login?.trim();
+    if (login)
+        return `GitHub (${login})`;
+    return inst.id ? `GitHub (installation ${inst.id})` : 'GitHub';
+}
+/**
+ * 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.
+ */
+function decodeGithubPrivateKey(raw) {
+    if (!raw || !raw.trim())
+        return null;
+    try {
+        const pem = Buffer.from(raw.trim(), 'base64').toString('utf8');
+        // Comprobar que de verdad salió un PEM y no cualquier cosa que decodifique.
+        // Sin esto, una variable con un valor viejo daría un error de firma
+        // ilegible varias capas más abajo.
+        return pem.includes('-----BEGIN') && pem.includes('PRIVATE KEY')
+            ? pem
+            : null;
+    }
+    catch {
+        return null;
+    }
+}