@hostwebhook/platform-node 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -4,3 +4,7 @@ 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

@@ -23,3 +23,10 @@ __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/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;
+    }
+}

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

@@ -0,0 +1,314 @@
+/**
+ * LinkedIn OAuth 2.0 configuration for HostWebhook.
+ *
+ * LinkedIn's auth model is plain OAuth 2.0 (NOT PKCE) with a
+ * confidential client. No per-instance dance like Mastodon — single
+ * HW-wide registered app, env-var-driven client credentials.
+ *
+ * ## SON DOS APPS DE LINKEDIN, no una
+ *
+ * LinkedIn exige que **Community Management API sea el unico producto** de su
+ * aplicacion, «due to legal and security constraints». En una app que ya tenga
+ * Share o Sign In with LinkedIn, la opcion de pedirlo sale en gris; y donde ya
+ * esta concedido, activar OIDC lo deshabilita. No es un fallo de configuracion
+ * ni algo que se arregle insistiendo: son dos aplicaciones.
+ *
+ *   App MIEMBRO — https://www.linkedin.com/developers/apps
+ *     Products: "Sign In with LinkedIn using OpenID Connect" + "Share on
+ *     LinkedIn". Gratuitas y automaticas.
+ *     Da: openid, profile, email, w_member_social.
+ *     Sirve para: publicar en un perfil personal.
+ *     Env: LINKEDIN_OAUTH_CLIENT_ID / LINKEDIN_OAUTH_CLIENT_SECRET.
+ *
+ *   App PAGINA — otra aplicacion, creada limpia y SIN anadirle ningun otro
+ *     producto antes de pedirlo.
+ *     Products: "Community Management API", y nada mas. Pasa por revision.
+ *     Da: r_organization_social, w_organization_social, rw_organization_admin.
+ *     Sirve para: publicar como pagina Y SONDEAR sus posts (lo unico que
+ *     desbloquea el trigger).
+ *     Env: LINKEDIN_ORG_OAUTH_CLIENT_ID / LINKEDIN_ORG_OAUTH_CLIENT_SECRET.
+ *
+ * Las dos registran el MISMO redirect: `{API_URL}/api/credentials/linkedin/
+ * oauth/callback`. No hay ambiguedad al volver porque el `state` guardado en
+ * Redis dice de que app salio, y con el la pareja de credenciales correcta.
+ *
+ * ## Lo que NO tiene la app de pagina
+ *
+ * OIDC. Ahi no hay `openid`, asi que `/v2/userinfo` no se puede llamar y esa
+ * conexion no conoce a la persona: se identifica por las paginas que
+ * administra (`organizationAcls`). De ahi que `memberId` y `personUrn` sean
+ * opcionales — ver `LinkedInOAuthStoredAuth`.
+ *
+ * Token lifetime: 60 days (default). Refresh tokens optional and
+ * issued only when LinkedIn deems necessary — most HW deployments
+ * just persist the access token until expiry, then prompt reconnect.
+ *
+ * ## Las dos identidades
+ *
+ * Una credencial de LinkedIn representa **a quien se publica y a quien se
+ * sondea**, y eso puede ser una persona (`urn:li:person:{sub}`) o una pagina
+ * de empresa (`urn:li:organization:{id}`). Todo el provider ya trabajaba con
+ * un solo `authorUrn`, asi que la eleccion vive en la credencial y ni el nodo
+ * ni el trigger tienen que enterarse: cambiar de identidad es cambiar ese URN.
+ *
+ * La diferencia que importa esta en la LECTURA, no en la escritura:
+ *
+ *   - publicar como persona -> `w_member_social`, producto gratuito.
+ *   - publicar como pagina  -> `w_organization_social`, Community Management.
+ *   - LEER los posts propios de una persona -> `r_member_social`, que LinkedIn
+ *     describe como «restricted and available to approved users only» y no
+ *     esta concediendo. Por eso el trigger sobre un perfil personal no puede
+ *     funcionar por mucho que la app este bien montada.
+ *   - LEER los posts de una pagina -> `r_organization_social`, y ese SI se
+ *     concede via Community Management API.
+ *
+ * De ahi que el trigger sea una funcion de la identidad elegida y de los
+ * scopes concedidos, no de una tabla fija: si LinkedIn cambiara de criterio y
+ * concediera `r_member_social`, el perfil personal empieza a sondear solo, sin
+ * tocar una linea. Ver `pollBlockReason`.
+ */
+export declare const LINKEDIN_OAUTH_CONFIG: {
+    readonly authorizationEndpoint: "https://www.linkedin.com/oauth/v2/authorization";
+    readonly tokenEndpoint: "https://www.linkedin.com/oauth/v2/accessToken";
+    /** OpenID Connect userinfo — returns sub (member id), name, email, etc. */
+    readonly userInfoWebhook: "https://api.linkedin.com/v2/userinfo";
+    /** Env var names holding HW's registered client credentials. */
+    readonly clientIdEnv: "LINKEDIN_OAUTH_CLIENT_ID";
+    readonly clientSecretEnv: "LINKEDIN_OAUTH_CLIENT_SECRET";
+    /**
+     * Scopes extra que este despliegue puede pedir, separados por coma.
+     *
+     * ## Por que es una variable y no una constante
+     *
+     * LinkedIn rechaza la autorizacion ENTERA con `unauthorized_scope_error` si
+     * pides un scope que la app no tiene habilitado — no lo ignora. Meter los
+     * scopes de pagina en la lista fija romperia el conector personal, que hoy
+     * funciona, en todos los despliegues cuya app aun no tenga aprobado
+     * Community Management API.
+     *
+     * Asi que la lista base es la que garantizan los dos productos gratuitos, y
+     * lo que dependa de una aprobacion se enciende aqui cuando LinkedIn la
+     * concede:
+     *
+     *     LINKEDIN_OAUTH_EXTRA_SCOPES=r_organization_social,w_organization_social,rw_organization_admin
+     *
+     * Es una variable y no un booleano a proposito: LinkedIn renombra y trocea
+     * sus permisos cada pocos meses, y asi ajustarlo no pide un despliegue de
+     * codigo.
+     */
+    readonly extraScopesEnv: "LINKEDIN_OAUTH_EXTRA_SCOPES";
+    /** Default scope set:
+     *   - openid profile email — OIDC identity (always required)
+     *   - w_member_social — post on behalf of the authenticated member
+     *
+     * `w_member_social` is "Share on LinkedIn" product scope — must be
+     * enabled on the LinkedIn app via the Products tab. */
+    readonly defaultScopes: readonly ["openid", "profile", "email", "w_member_social"];
+    /** Credenciales de la SEGUNDA app, la de Community Management API. */
+    readonly orgClientIdEnv: "LINKEDIN_ORG_OAUTH_CLIENT_ID";
+    readonly orgClientSecretEnv: "LINKEDIN_ORG_OAUTH_CLIENT_SECRET";
+    /** Sobrescribe los scopes de la app de pagina sin desplegar codigo. */
+    readonly orgScopesEnv: "LINKEDIN_ORG_OAUTH_SCOPES";
+    /**
+     * Lo que concede Community Management API en su nivel de desarrollo:
+     *   - r_organization_social — leer los posts de la pagina (EL TRIGGER)
+     *   - w_organization_social — publicar como la pagina
+     *   - rw_organization_admin — listar que paginas administra el miembro
+     *
+     * Sin `openid` a proposito: esa app no tiene OIDC y pedirlo la tumbaria
+     * entera con `unauthorized_scope_error`.
+     */
+    readonly orgDefaultScopes: readonly ["r_organization_social", "w_organization_social", "rw_organization_admin"];
+};
+/**
+ * De cual de las dos apps sale una conexion.
+ *
+ * Viaja en el `state` de Redis entre el `start` y el callback, y queda
+ * guardado en la credencial: un reconnect tiene que volver por la MISMA app,
+ * porque la otra ni tiene sus permisos ni reconoce su client_id.
+ */
+export type LinkedInAppKind = 'member' | 'organization';
+/**
+ * La version de la API de marketing que se declara en cada llamada a `/rest`.
+ *
+ * Iba escrita en el provider, y ahora la necesitan dos sitios: el provider y el
+ * descubrimiento de paginas del OAuth. Una sola copia, porque LinkedIn RETIRA
+ * las versiones viejas cada pocos meses («The Marketing Version 202507 has been
+ * sunset») y en `/rest` una version retirada no es un aviso, es un fallo. Con
+ * dos copias, subir una y olvidar la otra deja media integracion rota.
+ *
+ * Los `/v2` no la consultan — de ahi que el desfase no diera la cara.
+ */
+export declare const LINKEDIN_REST_VERSION = "202607";
+/** Leer los posts propios de una PERSONA. Restringido por LinkedIn. */
+export declare const LINKEDIN_MEMBER_READ_SCOPE = "r_member_social";
+/** Leer los posts de una PAGINA. Community Management API. */
+export declare const LINKEDIN_ORG_READ_SCOPE = "r_organization_social";
+/** Publicar como PAGINA. Community Management API. */
+export declare const LINKEDIN_ORG_WRITE_SCOPE = "w_organization_social";
+/** Listar las paginas que administra el miembro (`organizationAcls`). */
+export declare const LINKEDIN_ORG_ADMIN_SCOPE = "rw_organization_admin";
+/**
+ * Los scopes que se piden en la autorizacion: los base mas los que este
+ * despliegue haya encendido por entorno.
+ *
+ * `env` se inyecta para que la prueba no tenga que tocar `process.env`.
+ */
+export declare function resolveDefaultScopes(env?: NodeJS.ProcessEnv): string[];
+/** Lo que se le pide a la app de pagina. Sobrescribible por entorno. */
+export declare function resolveOrgScopes(env?: NodeJS.ProcessEnv): string[];
+/** Los scopes y los nombres de variable que le tocan a cada app. */
+export declare function appConfigFor(kind: LinkedInAppKind): {
+    clientIdEnv: string;
+    clientSecretEnv: string;
+    scopes: (env?: NodeJS.ProcessEnv) => string[];
+};
+/** Trocea una lista de scopes escrita a mano: coma, espacio o salto. */
+export declare function parseScopeList(raw: string | undefined | null): string[];
+/** Que clase de autor es un URN. `null` cuando no se reconoce. */
+export type LinkedInAuthorKind = 'person' | 'organization';
+export declare function authorKindOf(urn: string | undefined | null): LinkedInAuthorKind | null;
+/** Una pagina de empresa que el miembro administra. */
+export interface LinkedInOrganization {
+    /** `urn:li:organization:{id}` — lo que se guarda como `authorUrn`. */
+    urn: string;
+    /** Nombre visible. Cae al URN cuando LinkedIn no lo devuelve. */
+    name: string;
+    /** `vanityName` — el trozo de linkedin.com/company/{vanityName}. */
+    vanityName?: string;
+    /** El rol con el que figura el miembro (ADMINISTRATOR, etc.). */
+    role?: string;
+}
+/**
+ * Los elementos de `organizationAcls` convertidos en paginas.
+ *
+ * LinkedIn devuelve el URN en `organization` y, cuando la proyeccion cuela,
+ * los datos decorados en `organization~`. Se toleran las dos formas porque la
+ * decoracion es lo primero que deja de venir cuando cambia la version de la
+ * API, y perder el nombre no puede costar la pagina entera: un desplegable que
+ * dice `urn:li:organization:123` es feo, pero elegible; uno vacio no.
+ */
+export declare function parseOrganizationAcls(elements: Array<Record<string, unknown>>): LinkedInOrganization[];
+/**
+ * La persona de una credencial, o cadena vacia si no la hay.
+ *
+ * Las credenciales anteriores a las paginas no guardan `personUrn`: entonces
+ * `authorUrn` solo podia ser la persona, asi que ese es el relleno correcto —
+ * PERO solo si de verdad es un URN de persona. Cayendo a `authorUrn` a secas,
+ * una credencial de la app de pagina devolveria el URN de la pagina como si
+ * fuera su persona, y `setAuthor` la aceptaria como identidad «personal».
+ */
+export declare function personUrnOf(payload: Record<string, unknown>): string;
+export declare function toOrganizations(raw: unknown): LinkedInOrganization[];
+/**
+ * Por que ESTA credencial no puede sondear, o `null` si puede.
+ *
+ * Un solo sitio lo decide, y lo consultan los tres que opinan: la compuerta de
+ * activacion del trigger, el provider antes de gastar una llamada, y la
+ * pantalla para avisar antes de guardar.
+ *
+ * ## La regla del silencio
+ *
+ * Con `scopes` vacio o ausente NO se bloquea. Las credenciales anteriores a
+ * esto guardan la lista, pero una que no la tenga no es prueba de que falte el
+ * permiso — es prueba de que no lo sabemos, y bloquear por no saber convierte
+ * un fallo nuestro en un «no se puede» del usuario. Se bloquea solo cuando
+ * consta que el scope NO fue concedido.
+ */
+export declare function pollBlockReason(params: {
+    authorUrn?: string | null;
+    scopes?: string[] | null;
+}): string | null;
+/**
+ * Por que ESTA credencial no puede publicar, o `null` si puede.
+ *
+ * Misma regla del silencio que `pollBlockReason`. Publicar como persona es el
+ * caso gratuito; como pagina hace falta Community Management.
+ */
+export declare function postBlockReason(params: {
+    authorUrn?: string | null;
+    scopes?: string[] | null;
+}): string | null;
+export interface LinkedInUserInfo {
+    /** OIDC `sub` — opaque LinkedIn member id. Used as the URN base
+     *  (`urn:li:person:{sub}`) for posts via the UGC webhook. */
+    sub: string;
+    name: string;
+    given_name?: string;
+    family_name?: string;
+    email?: string;
+    picture?: string;
+}
+export interface LinkedInOAuthStoredAuth {
+    accessToken: string;
+    /** LinkedIn issues refresh tokens at its discretion. Optional. */
+    refreshToken?: string;
+    /** Absolute expiry in ms. Defaults to 60 days when LinkedIn returns
+     *  `expires_in: 5183999`. */
+    expiresAt?: number;
+    tokenType: string;
+    scopes: string[];
+    /** De cual de las dos apps salio. Un reconnect vuelve por la misma. */
+    appKind: LinkedInAppKind;
+    /**
+     * `sub` from /v2/userinfo — the URN base.
+     *
+     * Opcional porque la app de PAGINA no tiene OIDC: ahi no hay `/v2/userinfo`
+     * que llamar y la conexion no conoce a la persona, solo sus paginas.
+     */
+    memberId?: string;
+    memberName?: string;
+    email?: string;
+    /**
+     * A quien se publica y a quien se sondea. Por defecto la persona; puede
+     * apuntar a una de las paginas de `organizations`.
+     *
+     * Es el unico campo que lee el provider, de ahi que cambiar de identidad no
+     * toque ni un nodo ni un trigger.
+     */
+    authorUrn: string;
+    /**
+     * La persona, cuando se sabe. `authorUrn` se puede mover a una pagina y hay
+     * que poder volver.
+     *
+     * Ausente en dos casos distintos: en una credencial anterior a las paginas
+     * (ahi `authorUrn` ERA la persona, y de eso se ocupa `personUrnOf`) y en una
+     * conexion por la app de pagina, que no tiene OIDC y nunca conoce a nadie.
+     */
+    personUrn?: string;
+    /** Las paginas que el miembro administra, descubiertas al conectar. */
+    organizations?: LinkedInOrganization[];
+}
+export interface LinkedInOAuthStoredData {
+    /** Cached display name + email at the top level for fast UI. */
+    memberName: string;
+    email?: string;
+    oauth: LinkedInOAuthStoredAuth;
+}
+export interface PendingLinkedInOAuthState {
+    orgId: string;
+    userId: string;
+    credentialName: string;
+    /** Optional — set on reconnect to update an existing credential. */
+    credentialId?: string;
+    tags?: string[];
+    /** Carpeta destino elegida en el formulario. Viaja por Redis entre el
+     *  `start` y el callback: sin declararla aqui se perdia por el camino. */
+    folderId?: string;
+    clientId: string;
+    clientSecret: string;
+    requestedScopes: string[];
+    /** De que app salio. El callback lo necesita para saber si hay OIDC. */
+    appKind: LinkedInAppKind;
+    /** Absolute ms timestamp when this pending state expires (10 min). */
+    expiresAt: number;
+}
+export interface LinkedInTokenResponse {
+    access_token: string;
+    refresh_token?: string;
+    expires_in?: number;
+    scope?: string;
+    token_type?: string;
+    error?: string;
+    error_description?: string;
+}