Proveedores OAuth como extensión

Un proveedor OAuth (Google, Microsoft, Zoom o Slack, o el tuyo) es una extensión: declara oauthProviders en su manifest y el núcleo de la instancia ejecuta el flujo. Las demás extensiones lo usan por dependencia y nunca ven tokens.

Modelo#

• Núcleo (/api/oauth/[provider]/start|callback|reconnect|unlink): PKCE S256, state opaco de un solo uso, verificación del id_token OIDC por JWKS, comprobación de iss (RFC 9207), returnTo saneado, refresh con bloqueo y rotación, revocación RFC 7009 al desvincular. Los alias de Google (/api/auth/google, /api/auth/callback/google) usan el mismo flujo.
• Registro: los proveedores salen de los manifests instalados. Si no hay extensión, Google sigue funcionando con las variables GOOGLE_* solo cuando todos los endpoints son hosts oficiales de Google.
• Credenciales: el client secret y las credenciales compartidas se guardan cifradas (AES-256-GCM v3) en la tabla de la instancia OAuthProviderConfig, ancladas a los hosts aprobados. Si cambia un host, el proveedor pasa a needs_reapproval.
• Broker: el backend llama a la instancia (/api/internal/host/oauth) presentando la executionGrant que la propia instancia firmó (ver "Concesiones de ejecución") y expone services.oauth y ctx.libs.<proveedor>.<acción>. Los grupos de scopes y el acceso compartido los deriva la INSTANCIA de la concesión. Permisos: OAUTH_ACCOUNT:<proveedor>:<grupo> y OAUTH_SHARED:<proveedor>.
• Principales: user (cuenta del usuario), organizer (cuenta compartida) y service (cuenta de servicio; el JWT lo firma el núcleo).

Escribir un proveedor OAuth como extensión#

1. Declara oauthProviders con endpoints https, puerto 443, DNS público y allowedHosts (regla anti-SSRF).
2. Cataloga los scopes con group, texto es/en y risk.
3. Declara actions (método, ruta con parámetros, scopes requeridos, fixedQuery, bodyFrom, upload, write). Nada que no esté declarado se puede llamar.
4. Pon requires.capabilities con oauth.provider.v1 y requires.clientApi 5 (con funciones v2: oauth.provider.v2 y clientApi 9).
5. Publica; el administrador introduce el client id y el secreto en la consola (/admin/extensions, o oauth secret set en la CLI de administración) y aprueba los hosts del proveedor.
6. Atajo: npm run new:oauth-provider -- <id> genera el esqueleto, las pruebas y la prueba de flujo (ver "Plantilla y generador").

{
  "id": "core-googlelib",
  "version": "1.0.0",
  "requires": { "clientApi": 5, "capabilities": ["oauth.provider.v1", "oauth.broker.v1"] },
  "oauthProviders": [{
    "id": "google",
    "displayName": "Google",
    "authorizeUrl": "https://accounts.google.com/o/oauth2/v2/auth",
    "tokenUrl": "https://oauth2.googleapis.com/token",
    "apiBase": "https://www.googleapis.com",
    "allowedHosts": ["accounts.google.com", "oauth2.googleapis.com", "www.googleapis.com"],
    "pkce": true,
    "clientIdSetting": "GOOGLE_CLIENT_ID",
    "clientSecretCredential": "GOOGLE_CLIENT_SECRET",
    "redirectPath": "/api/auth/callback/google",
    "scopes": [{ "id": "https://www.googleapis.com/auth/calendar.events", "group": "calendar", "es": "Eventos", "en": "Events", "risk": "medium" }],
    "actions": [{ "id": "calendar.events.list", "group": "calendar", "method": "GET", "path": "/calendar/v3/calendars/{calendarId}/events", "requiresScopes": ["https://www.googleapis.com/auth/calendar.events"] }]
  }]
}

Dependencias entre extensiones#

requires.extensions acepta rangos semver (^, ~, comparadores y *). Instalar una extensión instala o propone sus dependencias; si una dependencia se pausa o desinstala, las dependientes se pausan (no se borran) y se reanudan al volver. Los ciclos se rechazan al publicar. Capacidad: ext.dependencies.v1 (clientApi 3).

{
  "id": "core-calendar",
  "requires": { "extensions": { "core-googlelib": "^1.0.0" } },
  "permissions": ["OAUTH_ACCOUNT:google:calendar", "OAUTH_SHARED:google"]
}

// server.js
const events = await ctx.libs.google.calendar.events.list({ calendarId: 'primary' });

Rutas y páginas de extensiones: modos de autenticación#

Las rutas backendRoutes se sirven en /api/ext/<id>/... y las páginas públicas en /p/**. Cada ruta declara auth:

"backendRoutes": [
  { "path": "/hook/:id", "method": "POST", "handler": "onHook", "auth": "hmac", "hmac": { "header": "X-Signature", "secretSetting": "HOOK_SECRET" } },
  { "path": "/status", "method": "GET", "handler": "status", "auth": "admin", "minLevel": 2, "stepUp": true }
]

Capacidades: ext.routes.v1, ext.routes.auth.v1, ext.pages.auth.v1 (clientApi 4). El borde de la instancia firma dentro de la URL el origen, nivel, usuario e IP; el backend los verifica.

Seguridad: modelo de amenazas STRIDE#

Requisito: la clave de dominio de la instancia#

GoogleLib, la IA por puente, los servicios del host y las rutas propias de extensiones (ext.grants.v1, oauth.*, ext.routes*) solo funcionan si la instancia firma sus peticiones con su BLOOMX_DOMAIN_PRIVATE_KEY. Una instancia sin clave sigue en modo legado y recibe exactamente las versiones de extensiones de siempre (google-sync, meet, calendar y drive 1.x, con tokens por context.auth): anuncia al backend clientApi 3 y solo las capacidades que funcionan sin firmar. Al registrar la clave pasa sola a las versiones nuevas, sin tocar nada más.

1. Genera el par en tu equipo: node scripts/gen-domain-keypair.mjs (la clave privada no se genera ni viaja por el navegador).
2. Guarda la privada como variable de entorno secreta BLOOMX_DOMAIN_PRIVATE_KEY de la instancia y vuelve a desplegar.
3. Registra la clave pública en el backend: bloomx-admin security keys register (sesión de gestor, nivel 4 con reautenticación), la pantalla /admin/register o POST /api/manager/domain-key.
4. Comprueba con bloomx-admin security signing (signed: true): el aviso del panel de Extensiones, IA y Cuentas vinculadas desaparece y las extensiones se pueden actualizar.

Concesiones de ejecución (sin clave global del backend)#

El backend compartido no tiene ninguna clave propia ni firma nada. Cuando una instancia le pide ejecutar una extensión, hook o ruta, adjunta una executionGrant: un mensaje Ed25519 firmado con la clave de dominio de la instancia (BLOOMX_DOMAIN_PRIVATE_KEY, la misma que ya firma sus peticiones). Lleva dominio (iss/aud), extensión y versión, usuario (sub, null en rutas públicas), la lista cerrada de permisos de esa ejecución, jti, iat/exp (120 s por defecto, BLOOMX_GRANT_TTL_SECONDS), nonce y tope de usos (BLOOMX_GRANT_MAX_USES).

• El backend solo la reenvía: comprueba que corresponde a la ejecución (dominio autenticado de la petición, extensión, versión, usuario, no caducada) y la presenta tal cual a /api/internal/host/*. El sandbox nunca la ve.
• La instancia la verifica sola, con la clave pública derivada de su privada y sin red: firma, exp, aud, extensión y usuario del cuerpo, servicio dentro de los permisos y tope de usos por jti (la misma ejecución hace N llamadas hasta exp). Una extensión no puede ampliar permisos ni cambiar de usuario o dominio porque rompería la firma.
• Versionado: capacidad ext.grants.v1 (clientApi 6). Si la instancia la anuncia y no hay concesión válida, el backend NO ofrece servicios del host (nunca cae a una clave global); una concesión mal formada o de otro dominio, extensión, versión o usuario se rechaza con INVALID_GRANT.
• Legado deprecado: instancias y backends antiguos que usan la firma del backend (BACKEND_SIGNING_PRIVATE_KEY, BLOOMX_BACKEND_PUBLIC_KEY, /.well-known/bloomx-backend-key.json) siguen funcionando durante la transición; la instancia lo avisa en el log y en /admin. Para apagarlo: BLOOMX_ACCEPT_BACKEND_SIGNATURE=false. Se retirará en una versión futura.
• Migración de credenciales: sin entrega automática. migrate-googlelib solo informa de los nombres de las credenciales; guárdalas en cada instancia con oauth secret set.

Reglas de seguridad adicionales#

• Tokens como permiso: context.auth y getToken() solo llegan a extensiones cuyo manifest declara OAUTH_READ o a una lista cerrada de versiones antiguas (google-meet, calendar, google-drive, google-sync, zoom y hubspot, hasta su última versión legada). Cualquier otra extensión no los recibe. Está deprecado: usa OAUTH_ACCOUNT:*.
• Ids reservados: google, microsoft, zoom, slack, github y similares solo los registra su extensión oficial (core-googlelib, core-microsoftlib, core-zoomlib, core-slacklib...); ni siquiera una oficial puede registrar el id de otra. Se valida al publicar y de nuevo en la instancia.
• Rutas de acciones: un parámetro de ruta nunca puede ser . ni .. y la ruta final tras normalizar la URL debe ser exactamente la construida; un id con %2e%2e, / o ? no sale del servidor.
• Límites por acción: cuota por minuto y usuario/extensión/proveedor (120 lecturas, 30 escrituras) y, si la acción lo declara, quotaPerHour (tope duro por hora fijado por el manifest, no por la extensión). allowedFromSetting limita un parámetro a una lista que fija el admin (p. ej. canales de Slack).
• Cuenta atada a su proveedor: cada cuenta guarda el hash de los endpoints del proveedor que la emitió; si otro proveedor usara el mismo id, sus tokens no se envían ni se refrescan.
• Aprobación de proveedores no integrados: quedan en pending_approval hasta que un administrador (nivel 3 + step-up) aprueba sus hosts (POST /api/admin/oauth/providers/<id>/approve o oauth approve). El inicio de sesión solo funciona con el Google oficial y exige email_verified explícito.
• Aprobaciones al instalar/actualizar: cada ruta pública (PUBLIC_ROUTE:<MÉTODO> <ruta> o PUBLIC_ROUTE:PAGE <ruta>), OAUTH_SHARED:* y OAUTH_ACCOUNT:* de grupos de riesgo alto (gmail, drive...) se aprueban una a una; una versión nueva que añade alguna queda pendiente.
• Cuentas compartidas: el organizador y la cuenta de servicio solo conceden los scopes de una lista fija (Google: calendario y Meet).
• Transporte: la conexión al proveedor fija la IP validada (sin ventana de DNS rebinding) e incluye 6to4, NAT64 e IPv6 compatible como direcciones privadas. NEXT_PUBLIC_BACKEND_URL debe ser https en producción y es FIJA por instancia: el registro de proveedores no sigue redirecciones, se valida por esquema estricto y los proveedores no integrados exigen la aprobación del administrador. No existe ninguna clave global del backend.
• Patrones: los pattern de acciones y rutas se validan contra ReDoS al publicar y se ejecutan con control de errores.
• HMAC: timestampHeader es obligatorio salvo allowReplay: true; sin timestamp el detector de repeticiones es por proceso y no es una defensa fuerte en serverless.
• GET con efectos: una ruta session/admin con sideEffects: true rechaza peticiones Sec-Fetch-Site: cross-site.
• Páginas `admin` en el servidor: sin el nivel, el navegador no recibe el árbol de componentes de esas páginas y las acciones que invocan (y su handler) responden 403. El state inicial solo se oculta si la extensión no conserva otros mounts con componente: no pongas datos sensibles en state.
• Sin tabla `OAuthFlow` en producción el flujo falla cerrado en lugar de degradar a memoria.

Cumplimiento (verificado por código y pruebas)#

Proveedores incluidos: MicrosoftLib, ZoomLib y SlackLib#

Los tres siguen el patrón de GoogleLib: un manifest con oauthProviders, un server.js solo de estado (sin red ni secretos) y extensiones dependientes con OAUTH_ACCOUNT:<proveedor>:<grupo>. Requieren oauth.provider.v2 (clientApi 9) y clave de dominio en la instancia. Los tokens nunca llegan a una extensión.

{
  "id": "core-microsoftlib", "version": "1.0.0",
  "requires": { "clientApi": 9, "capabilities": ["oauth.provider.v1", "oauth.provider.v2", "oauth.broker.v1", "settings.schema.v1"] },
  "oauthProviders": [{
    "id": "microsoft", "displayName": "Microsoft",
    "authorizeUrl": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize",
    "tokenUrl": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
    "jwksUri": "https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys",
    "issuer": "https://login.microsoftonline.com/{claim:tid}/v2.0",
    "userinfoUrl": "https://graph.microsoft.com/oidc/userinfo", "apiBase": "https://graph.microsoft.com",
    "allowedHosts": ["login.microsoftonline.com", "graph.microsoft.com"],
    "variables": { "tenant": { "setting": "MICROSOFT_TENANT", "default": "common", "pattern": "^(common|organizations|consumers|[0-9a-fA-F-]{36})$" } },
    "pkce": true, "clientIdSetting": "MICROSOFT_CLIENT_ID", "clientSecretCredential": "MICROSOFT_CLIENT_SECRET",
    "actions": [{ "id": "calendar.events.list", "group": "calendar", "method": "GET", "path": "/v1.0/me/events", "requiresScopes": ["Calendars.Read"],
      "params": { "top": { "in": "query", "type": "integer", "min": 1, "max": 100, "queryName": "$top" } } }]
  }]
}

{
  "id": "core-zoomlib", "version": "1.0.0",
  "oauthProviders": [{
    "id": "zoom", "displayName": "Zoom",
    "authorizeUrl": "https://zoom.us/oauth/authorize", "tokenUrl": "https://zoom.us/oauth/token", "revokeUrl": "https://zoom.us/oauth/revoke",
    "userinfoUrl": "https://api.zoom.us/v2/users/me", "apiBase": "https://api.zoom.us", "allowedHosts": ["zoom.us", "api.zoom.us"],
    "pkce": true, "tokenAuth": "basic", "revokeToken": "access",
    "serviceCredentials": { "grant": "account_credentials", "accountIdSetting": "ZOOM_ACCOUNT_ID", "clientIdSetting": "ZOOM_S2S_CLIENT_ID", "clientSecretCredential": "ZOOM_S2S_CLIENT_SECRET" },
    "clientIdSetting": "ZOOM_CLIENT_ID", "clientSecretCredential": "ZOOM_CLIENT_SECRET"
  }]
}

// core-zoom 2.0.0 (conferencing): "requires": { "extensions": { "core-zoomlib": "^1.0.0" } }, "permissions": ["OAUTH_ACCOUNT:zoom:meetings", "OAUTH_SHARED:zoom"]
await ctx.libs.zoom.meetings.create({ userId: "me", meeting: { topic: "Demo", type: 2 } });                    // cuenta del usuario
await ctx.libs.zoom.meetings.create({ userId: "host@acme.com", meeting: { topic: "Demo" } }, { principal: "service" }); // Server-to-Server

{
  "id": "core-slacklib", "version": "1.0.0",
  "oauthProviders": [{
    "id": "slack", "displayName": "Slack", "tokenFormat": "slack-v2", "pkce": false,
    "authorizeUrl": "https://slack.com/oauth/v2/authorize", "tokenUrl": "https://slack.com/api/oauth.v2.access", "revokeUrl": "https://slack.com/api/auth.revoke",
    "apiBase": "https://slack.com", "allowedHosts": ["slack.com"],
    "scopes": [{ "id": "chat:write", "group": "chat", "es": "Publicar mensajes", "en": "Post messages", "risk": "medium" },
               { "id": "user:chat:write", "group": "chat", "es": "Publicar como tú", "en": "Post as you", "risk": "medium" }],
    "actions": [{ "id": "chat.postMessage", "group": "chat", "method": "POST", "path": "/api/chat.postMessage", "write": true, "quotaPerHour": 120, "requiresScopes": ["chat:write"],
      "params": { "channel": { "in": "body", "type": "string", "required": true, "pattern": "^[CG][A-Z0-9]{2,20}$", "allowedFromSetting": "SLACK_ALLOWED_CHANNELS" },
                  "text": { "in": "body", "type": "string", "maxLength": 3000 } } }]
  }]
}

// slack-notify: "permissions": ["OAUTH_ACCOUNT:slack:chat"]
await ctx.libs.slack.chat.postMessage({ channel: ctx.settings.channel, text: "Nuevo correo de Ana" });

Funciones v3 (oauth.provider.v3): credencial de bot y rutas con dispatch#

DiscordLib 1.1.0 añade, bajo la capacidad oauth.provider.v3 (clientApi 12), solo campos nuevos: una credencial de bot del proveedor (botCredential, token write-only que solo guarda el núcleo), acciones con credential: "bot" (cabecera Authorization: Bot inyectada por el núcleo, nunca devuelta), moderation (acciones apagadas salvo ajuste del admin), guild (restricción a servidores permitidos), pathSettings y rutas con dispatch (tras verificar una firma hmac Ed25519 el router entrega el evento a los hooks de otras extensiones). Las instancias sin la capacidad siguen recibiendo la versión anterior. Detalle y ejemplos en DiscordLib: bot de Discord.

Funciones v2 (oauth.provider.v2)#

Desvincular y revocar, por proveedor#

Plantilla y generador#

bloomx-extensions/_oauth-provider-template/ es un ejemplo documentado y probado ("Acme"): manifest.src.mjs comentado, server.js de estado, README paso a paso y pruebas. Como _template, empieza por _ y su JSON se llama manifest.template.json: no es publicable y los sincronizadores, la validación y el control de versiones la ignoran. npm run new:oauth-provider -- <id> crea <id>lib/ con los datos ficticios sustituidos (los hosts quedan como <id>-todo-replace.com para que no se olviden) y la prueba de flujo contra un servidor OAuth falso. Un id reservado exige --core y solo vale para su extensión oficial.

cd bloomx-extensions
npm run new:oauth-provider -- mi-crm                 # crea mi-crmlib/ y la prueba de flujo del frontend
npm run new:oauth-provider -- github --core          # extension OFICIAL de un id reservado (core-githublib)
node --experimental-strip-types _shared/sdk/build-manifest.mjs mi-crmlib/manifest.src.mjs
node --experimental-strip-types _shared/validate.mjs mi-crmlib
node --experimental-strip-types --test mi-crmlib/tests/*.test.mjs
cd ../bloomx && npx vitest run src/lib/oauth/__tests__/mi-crm.flow.test.ts

Probar con credenciales reales#

Las pruebas automáticas usan servidores OAuth falsos y manifests reales; no se han ejecutado contra Microsoft, Zoom ni Slack reales (requiere credenciales). Para comprobarlo en una instancia con clave de dominio:

1. Microsoft: en Entra ID registra una aplicación web con redirect https://<instancia>/api/oauth/microsoft/callback, crea un secreto y concede los permisos delegados del catálogo. Guarda MICROSOFT_CLIENT_ID, MICROSOFT_TENANT (organizations o el GUID de tu tenant; common admite cuentas personales, pero las reuniones de Teams exigen cuenta de trabajo o escuela) y el secreto en los ajustes de MicrosoftLib.
2. Zoom: crea una app *General* (OAuth de usuario) con redirect https://<instancia>/api/oauth/zoom/callback y los scopes granulares; guarda ZOOM_CLIENT_ID y ZOOM_CLIENT_SECRET. Para S2S crea otra app *Server-to-Server OAuth* y guarda ZOOM_ACCOUNT_ID, ZOOM_S2S_CLIENT_ID, ZOOM_S2S_CLIENT_SECRET y ZOOM_HOST_EMAIL.
3. Slack: crea la app en api.slack.com/apps con redirect https://<instancia>/api/oauth/slack/callback, scopes de bot chat:write, channels:read, users:read; guarda SLACK_CLIENT_ID, SLACK_CLIENT_SECRET y los ids de canal en SLACK_ALLOWED_CHANNELS, e invita al bot al canal (/invite @app).
4. Como administrador, aprueba los hosts del proveedor (/admin/extensions o oauth approve <id>) y guarda el secreto (oauth secret set); como usuario, vincula la cuenta en Ajustes → Integraciones o con /api/oauth/<id>/start y revisa Cuentas vinculadas en /admin/accounts.
5. Prueba: crear una reunión de Teams o Zoom desde el selector de ubicación de un evento, o activar slack-notify y pulsar "Enviar prueba". Nunca compartas los secretos: se guardan cifrados en la instancia y no los ve ninguna extensión.

Migrar una instancia#

1. Simulacro: node --experimental-strip-types scripts/migrate-googlelib.mjs (backend).
2. Aplicar: añade --apply. Copia los ajustes no secretos; las extensiones de origen no se tocan.
3. Credenciales: el script NO mueve secretos. Guárdalas en cada instancia con oauth secret set (cifradas con su clave).
4. Revertir: --rollback (desactiva) o --rollback --purge. Las cuentas vinculadas y los tokens no se tocan.