Extensiones

Una extensión (en el código y en la interfaz también se llama *expansión*) añade interfaz y lógica a BloomX sin tocar su código. Se compone de un manifest.json (declarativo: qué se muestra, qué funciones expone, qué permisos pide) y, opcionalmente, un server.js que se ejecuta en el backend compartido dentro de un sandbox. Para construir una paso a paso ve a Crear una extensión.

Modelo#

• Las extensiones viven en el repositorio bloomx-extensions (una carpeta por extensión) y se publican al backend (base de datos + almacenamiento). Cada dominio (empresa) instala las que quiere.
• El frontend recibe de GET /api/config las extensiones habilitadas del dominio (con sus template, es decir el manifest, y sus settings sin secretos) y pinta su interfaz en los *puntos de montaje*.
• Cuando la interfaz llama a una función (CALL_BACKEND) o se dispara un hook, el frontend hace un proxy firmado al backend (/api/extension/execute o /api/extension/hooks), que ejecuta server.js en el sandbox.
• Extensiones solo cliente ("clientOnly": true, sin server.js), como slash-commands, appointments o google-sync, no ejecutan nada en el backend.

Contrato handler(ctx)#

Cada función exportada por server.js recibe un único parámetro ctx y devuelve un valor serializable a JSON (hasta 5 MB). Un test del repositorio falla si algún handler declara más de un parámetro.

// server.js  (CommonJS, o "export function")
module.exports = {
    // UN solo parámetro: ctx
    scanContent: async (ctx) => {
        const text = String(ctx.emailContent || '');
        const words = String(ctx.env.DLP_KEYWORDS || '').split(',').filter(Boolean);
        const hit = words.find((w) => text.toLowerCase().includes(w.trim().toLowerCase()));
        if (hit) return { stop: true, message: 'Contenido bloqueado por política: ' + hit };
        return { success: true };
    },
};

• Errores: throw new Error(msg) devuelve {success:false, error} con HTTP 500; AUTH_REQUIRED da 401; un timeout, 408; una acción no exportada, 404.
• Convención (no impuesta): devolver {success, ...}.
• Para los hooks (ctx.event) el retorno tiene semántica propia, ver Hooks.

Manifest y schema#

El schema canónico es bloomx-extensions/_shared/manifest-schema.ts, con dos copias idénticas (backend y frontend) que un test compara. Los errores impiden cargar o publicar; los avisos no.

• Reglas cruzadas: todo CALL_BACKEND.function, mount.handler e intercept.handler debe existir en api.functions. Profundidad máxima del árbol de componentes: 40. Una acción desconocida es un error; un componente o punto de montaje desconocido, solo un aviso.
• backendRoutes genera un aviso: no hay router /api/ext/[id]/*, así que no se sirve.
• La lista de tipos de componente se deriva de ui-schema.ts (los ~70 del kit) más los nombres del formato antiguo (COLUMN, DATA_TABLE…): un tipo del kit nunca da el aviso «componente desconocido». Límites del manifest: 1 MB, 12 etiquetas, 6 capturas, 20 entradas de changelog y 50 000 nodos recorridos.
• Validación al publicar: además del manifest, el backend valida todo el UI con el espejo de ui-schema.ts (ruta del error incluida, p. ej. mounts[0].component.props.tone). Estructura inválida = 400; UI inválido o fuera de límites (600 nodos y 24 niveles por árbol, 256 KB, 200 mounts, 100 overlays, 5000 nodos en total) = 422. Aplica a POST /api/admin/extensions, a las acciones de /admin (createExtension, syncRepositoryExtensions), a sync-extensions.mjs y scripts/sync-repository-extensions.mjs (fallan cerrados), a la siembra y a la instalación (422 EXTENSION_INVALID). Al cargar una extensión ya publicada, el frontend trata los problemas de los campos de catálogo como avisos (lenientCatalog), no como errores.

{
  "manifestVersion": "1.0",
  "id": "core-dlp",
  "version": "1.0.0",
  "name": "Data Loss Prevention",
  "permissions": ["READ_EMAIL", "ENV_READ:DLP_KEYWORDS"],
  "api": {
    "runtime": "nodejs",
    "entry": "server.js",
    "functions": { "scanContent": { "handler": "scanContent", "timeout": 5000 } }
  },
  "intercepts": [
    { "point": "EMAIL_PRE_SEND", "handler": "scanContent", "priority": "HIGH", "onError": "block" }
  ]
}

Interfaz declarativa#

La interfaz es un árbol JSON de componentes (por ejemplo BUTTON, TEXT, INPUT, CARD, ROW, MODAL, TABS, FORM, LIST, DATA_TABLE, MARKDOWN, FILE_UPLOAD, WIZARD…) y acciones (SET_STATE, CALL_BACKEND, CALL_API, TOAST, OPEN_OVERLAY, OPEN_URL, INSERT_CONTENT, APPEND_BODY, SET_SUBJECT, ADD_ATTACHMENT, NEXT_STEP, SECURE_SAVE, OAUTH_CONNECT…). Las expresiones ${...} las evalúa un intérprete propio sin eval; CALL_API solo acepta rutas propias /api/...; OPEN_URL y los enlaces solo http(s), mailto y tel.

Puntos de montaje soportados por el schema: los de correo, barra lateral, editor, calendario, contactos y ajustes (tabla completa con su contexto en Puntos de montaje), más EVENT_LOCATION_BUILDER, SETTINGS_TAB, CUSTOM_SETTINGS_TAB, PAGE, OVERLAY, SLASH_COMMAND y los *_HANDLER de edición. No todos tienen consumidor en la interfaz: BEFORE_SEND_HANDLER, CUSTOM_ROUTE y backendRoutes no hacen nada hoy.

Una extensión puede declarar páginas completas (PAGE) y entradas de navegación (navEntries, capacidades ui.pages.v1 y nav.entries.v1): ver la guía Página completa y navegación.

Permisos#

El manifest declara los permisos que la extensión necesita. El catálogo (PERMISSION_CATALOG en el schema) da a cada uno una etiqueta, una descripción y un riesgo; es lo que ve el administrador del dominio.

• Validación. validateManifest comprueba que permissions sea una lista de strings; un permiso que no está en el catálogo produce un aviso (Permiso desconocido) y la plataforma lo ignora. ENV_READ:NOMBRE se valida aparte (^[A-Z][A-Z0-9_]{1,63}$ y no reservada) y un nombre inválido es error.
• Confirmación al instalar. El administrador ve la lista legible (describePermissions: etiqueta, descripción y riesgo; los desconocidos se marcan como tales) y debe confirmar antes de instalar. Pide solo lo necesario: lo que pidas se le muestra tal cual.
• Se hacen cumplir en el servidor: ENV_READ:*, READ_EMAIL, MAIL_LABEL y los de servicios (CALENDAR_*, CONTACTS_*, FORMATS, STORAGE, NOTIFY). El ejecutor rechaza una operación de servicio sin su permiso con un error claro (CALENDAR_PERMISSION_DENIED: services.calendar.createEvent requires CALENDAR_WRITE in the extension manifest). El resto (READ_USER, AI_GENERATE, HTTP_REQUEST, OAUTH_*, local:secure-storage) documenta la intención y los reservados (API_ROUTE_CREATE, PAGE_ROUTE_CREATE, DB_*) no tienen efecto.
• Detalle de cada operación y su permiso: Servicios del sandbox.

Credenciales por dominio#

• Cada empresa configura sus propias credenciales (por ejemplo GIPHY_API_KEY) en el panel de administración (extensiones → credenciales) o con PUT /api/extension/settings. Se guardan cifradas (enc:v1:, AES-256-GCM con DATA_ENCRYPTION_KEY del backend) y nunca vuelven al navegador: la interfaz solo ve {name, configured}.
• Solo se aceptan nombres declarados con ENV_READ:* en el manifest y no reservados; valor de hasta 4096 caracteres, sin caracteres de control. null o cadena vacía borra.
• Lectura en ejecución: por cada ENV_READ:X, en este orden: (1) la credencial del dominio (cifrada, la escribe el manager desde el panel), (2) el valor heredado que guardaban las instalaciones antiguas y (3) la variable global del backend, salvo las variables de plataforma (base de datos, almacenamiento, cifrado, claves privadas, EXTENSION_*, etc.), que ninguna extensión puede leer. EXTENSION_GLOBAL_ENV_FALLBACK es un control de endurecimiento opcional: none desactiva el paso 3 y una lista lo limita a esos nombres. El panel muestra la fuente activa de cada variable.
• En modo legado (sin firma) la extensión recibe las mismas credenciales, que quedan dentro del sandbox y no se devuelven; no tiene services.mail y cada ejecución se audita. requireSignature rechaza el modo legado.
• Desinstalar una extensión borra sus credenciales y authData, y intenta revocar los tokens OAuth en el proveedor (Google, HubSpot, Notion, Zoom; mejor esfuerzo, 5 s).

Configuración por dominio vs variables de entorno#

El manifest puede declarar settingsSchema: los campos que el administrador configura por dominio en la consola (extensiones → detalle → pestañas Ajustes y Credenciales), sin tocar variables de entorno del servidor. Cada campo tiene key, type, label/description (texto o {es, en}), default, required, group (secciones definidas en groups), visibleWhen: {key, in:[...]} y los límites propios de su tipo.

"settingsSchema": {
  "groups": [{ "id": "scan", "label": { "es": "Análisis", "en": "Scanning" } }],
  "fields": [
    { "key": "mode", "type": "enum", "group": "scan", "default": "block", "legacyEnv": "DLP_MODE",
      "label": { "es": "Modo", "en": "Mode" },
      "options": [{ "value": "block", "label": { "es": "Bloquear", "en": "Block" } }, "warn", "log"] },
    { "key": "keywords", "type": "list", "group": "scan", "maxItems": 100, "itemMaxLength": 100,
      "legacyEnv": "DLP_KEYWORDS", "label": { "es": "Palabras clave", "en": "Keywords" } },
    { "key": "GIPHY_API_KEY", "type": "string", "secret": true, "required": true,
      "label": { "es": "Clave de API", "en": "API key" } }
  ]
}

Secretos frente a ajustes#

• Secretos (secret: true): tokens, claves y contraseñas. La key es el nombre de variable en MAYÚSCULAS (el mismo de ENV_READ:*) y no admite default. Se guardan cifrados como credenciales del dominio, se editan solo en la pestaña Credenciales y su valor nunca vuelve al navegador. La pestaña Ajustes solo muestra «n de m secretos configurados» con un enlace.
• Ajustes (el resto): valores tipados que se guardan en claro en ExtensionOnDomain.settings.config y la extensión recibe en `ctx.settings[key]`. No pongas secretos aquí. Claves reservadas: credentials, env, meta, ui, config, configMeta, authData, mandatory.

// server.js: los ajustes NO secretos llegan en ctx.settings; los secretos, en ctx.env
module.exports = {
    async onEmailPreSend(ctx) {
        const mode = ctx.settings.mode || 'block';          // dominio > heredado > defecto
        const keywords = ctx.settings.keywords || [];
        const key = ctx.env.GIPHY_API_KEY;                  // credencial cifrada del dominio
        // ...
    }
};

Secretos de solo escritura (write-only)#

• Un secreto se declara con secret: true, writeOnly: true o type: "secret" (equivalentes). Se cifra en reposo (AES-256-GCM, la misma DATA_ENCRYPTION_KEY que la clave de IA) y nunca se vuelve a leer: la API solo devuelve { name, configured, set, updatedAt?, last4? }. last4 (los 4 últimos caracteres) solo existe si el campo declara revealLast4: true (apagado por defecto; secretos de menos de 12 caracteres no revelan nada).
• En la consola cada secreto muestra «Guardado — escribe para reemplazar» con la fecha de la última rotación y las acciones Reemplazar y Borrar (esta última pide confirmación). El campo es type=password con autocomplete="new-password".
• Un campo vacío en un guardado no borra nada: solo null (la acción Borrar) elimina el valor. Reemplazar y borrar quedan en la auditoría con quién y cuándo, nunca con el valor (tampoco en exportaciones, copias, registros de ejecución, errores, estado de páginas ni respuestas de execute).
• Validación en servidor al guardar: pattern, format y maxLength del campo (tope 4096). El error indica el motivo sin repetir el valor.
• Dentro del sandbox: el server.js recibe el secreto descifrado en ctx.env (secretos de dominio, solo los declarados con ENV_READ:*) o en el propio elemento de ctx.settings (secretos por elemento de objects), solo durante esa ejecución y solo si la extensión lo declara y tiene permiso.
• Migración: los valores que aún estuvieran en claro (instalaciones antiguas) se cifran en el primer guardado de la extensión, de forma idempotente (repetirlo no cambia nada). Compatibilidad: cualquier cliente que dependiera de leer un valor guardado ya no podrá hacerlo (solo se devuelve el estado); un cliente antiguo que enviaba "" para borrar debe enviar null.

Selector de usuarios: user, users y userMap#

Son ajustes que configura el administrador (nivel ≥ 3) eligiendo cuentas del propio dominio. Se guarda siempre el id estable del usuario (nunca el correo); la consola resuelve el nombre y el correo con un buscador asíncrono y paginado. Solo se ven y se validan las cuentas del dominio actual.

• userMap usa valueType: boolean (por defecto), string, number (min, max, integer) o select (options). default es el valor de quien no tiene entrada; la tabla solo guarda entradas explícitas.
• filter: { minLevel?, role? } acota quién se puede elegir (nivel de permiso mínimo o nombre del nivel: user, support, operator, admin, superadmin).
• Validación en servidor (el servidor de la consola, contra la base del dominio): cada id nuevo debe existir, no estar desactivado y cumplir el filtro (errores userMissing, userDisabled, userFilter). Los ids ya guardados que luego desaparecen no bloquean otros cambios: la consola los marca «Usuario eliminado» y ofrece «Quitar eliminados». El backend compartido valida formato, tipos y topes.
• En el handler: ctx.settings.owner es el id, ctx.settings.recipients la lista y ctx.settings.digest el mapa completo (es configuración del administrador, sin secretos de usuarios). ctx.settings.forUser(key, userId) y ctx.settings.getUserValue(key, userId) devuelven la entrada explícita o, si no existe, el default (funciones no enumerables: no salen en JSON.stringify(ctx.settings)).
• API del buscador (nivel 3): GET /api/admin/extensions/users?q=&page=&limit= y ?ids=a,b (resuelve y marca los inexistentes). CLI: extensions users --q ana.

"settingsSchema": {
  "fields": [
    { "key": "owner", "type": "user", "label": { "es": "Responsable", "en": "Owner" }, "filter": { "minLevel": 3 } },
    { "key": "recipients", "type": "users", "maxItems": 10, "label": { "es": "Destinatarios", "en": "Recipients" } },
    { "key": "digest", "type": "userMap", "valueType": "boolean", "default": false,
      "label": { "es": "Recibe el resumen", "en": "Gets the digest" } },
    { "key": "dailyLimit", "type": "userMap", "valueType": "number", "min": 1, "max": 500, "integer": true, "default": 20,
      "label": { "es": "Límite diario por usuario", "en": "Daily limit per user" } },
    { "key": "API_TOKEN", "type": "secret", "pattern": "^tok_[A-Za-z0-9]{16,}$", "revealLast4": true,
      "label": { "es": "Token de la API", "en": "API token" } }
  ]
}

// server.js
module.exports = {
    async sendDigest(ctx) {
        const { owner, recipients, digest } = ctx.settings;   // owner = id; recipients = ids; digest = { [userId]: boolean } (solo entradas explicitas)
        const wants = (id) => ctx.settings.forUser('digest', id);          // entrada explicita o default del schema
        const limit = ctx.settings.getUserValue('dailyLimit', ctx.user.id); // numero, o 20 si el usuario no tiene entrada
        const token = ctx.env.API_TOKEN;                                   // secreto write-only: solo existe aqui, dentro del sandbox
        if (!wants(ctx.user.id)) return { skipped: 'opt-out' };
        // ... un id eliminado sigue llegando como id: comprueba con ctx.services.users.get(id) si lo necesitas
    }
};

{
  "recipients": [
    "usr_002"
  ],
  "digest": {
    "usr_001": true,
    "usr_003": true,
    "usr_099": true
  },
  "quota": {
    "usr_002": 25
  }
}

Listas de elementos (objects), acciones y registro#

• `objects`: lista editable de registros (p. ej. los endpoints de un webhook). itemFields declara los sub-campos (tipos simples, con required y visibleWhen); cada elemento lleva un id estable ([a-z0-9-], único, hasta 32 caracteres) que la consola genera a partir de un nombre más un sufijo y no se puede editar después de guardar. Máximo 50 elementos.
• Secretos por elemento: un sub-campo con secret: true se guarda cifrado por elemento (nombre campo.id.subcampo), es de solo escritura y llega al handler únicamente dentro del sandbox. La consola solo recibe secretsSet (los nombres establecidos): muestra «Configurado / No configurado», un campo de contraseña vacío para establecer o reemplazar y el botón «Quitar». Los secretos viajan en secrets del mismo PUT y solo si el administrador los cambió.
• `templates`: elementos sugeridos con un botón «Añadir desde plantilla». No quedan activos por defecto: se añade el elemento, el administrador lo revisa y pulsa Guardar.
• `actions`: botones que invocan una función de api.functions con {itemId?} (scope: "global" arriba del formulario o "item" dentro de cada tarjeta, que se deshabilita si el elemento tiene cambios sin guardar). confirm pide confirmación. El resultado (status, código HTTP, latencia, mensaje y report[]) se muestra saneado y nunca incluye secretos; máximo 10 ejecuciones por minuto (HTTP 429).
• `runLog: {limit}`: registro acotado de ejecuciones (fecha, evento, destino, estado, intentos, latencia, código y mensaje corto; nunca cuerpos, cabeceras ni secretos). Alimenta «Registro de ejecuciones recientes» en la pestaña Estado y registro.
• Errores de validación: cada error lleva path, code y params además de message (español de respaldo). La consola traduce siempre por code + params (es/en): type, control, format, pattern, number, integer, min, max, option, options, list, maxItems, maxChars, required, objects, itemId, itemDup, itemUnknown, itemSecret, itemField (con el sub-código en params.sub), json, jsonSize... El message solo se usa si el código no tiene traducción.
• En un campo objects obligatorio, el listado «Configuración completa» cuenta 1 cuando hay al menos un elemento.

"settingsSchema": {
  "fields": [{
    "key": "endpoints", "type": "objects", "required": true, "maxItems": 20,
    "label": { "es": "Endpoints", "en": "Endpoints" },
    "itemFields": [
      { "key": "name", "type": "string", "required": true, "label": "Name" },
      { "key": "url", "type": "string", "format": "url", "required": true, "label": "URL" },
      { "key": "secret", "type": "string", "secret": true, "required": true, "label": "Signing secret" }
    ],
    "templates": [{ "id": "slack", "label": "Slack", "value": { "name": "Slack", "url": "https://hooks.example.com/x" } }]
  }],
  "actions": [{ "id": "send-test", "label": "Send test event", "handler": "sendTest", "scope": "item", "itemsKey": "endpoints" }],
  "runLog": { "limit": 50 }
}

Prioridad y retrocompatibilidad#

• Valor efectivo de un ajuste: ajuste del dominio > valor heredado del dominio > variable de entorno global (`legacyEnv`) > `default`. Si nada lo define, la clave queda sin valor (unset).
• legacyEnv nombra la variable de entorno que respaldaba el ajuste antes de existir el esquema (p. ej. DLP_KEYWORDS). Si el esquema es heredado y la clave ya está en MAYÚSCULAS, esa misma clave hace de legacyEnv. Las extensiones sin settingsSchema siguen funcionando igual y la pestaña Ajustes muestra la tabla de solo lectura de antes.
• El panel marca cada ajuste que aún se resuelve desde el entorno heredado («usando variable de entorno (heredada): migra a Ajustes») y avisa en el Resumen. Importar desde el entorno (solo si hay algo importable) copia al dominio esos ajustes no secretos; los secretos no se tocan y el valor del entorno global nunca se muestra en la consola: se copia en el servidor. Un campo con envImport: false queda fuera de la importación.
• Restablecer a valores por defecto borra los ajustes guardados del dominio (pide confirmación) y no toca las credenciales.

Validación, auditoría y límites#

• La consola valida en vivo con las mismas reglas que el backend (validateFieldValue, módulo compartido settings-schema); el servidor vuelve a validar y responde 422 {errors:[{path:"values.<clave>", message}]}, que la consola pinta junto al campo. Un required visible sin valor (propio, heredado o por defecto) cuenta en la lista «Configuración completa X/Y» del Resumen.
• API: GET/PUT/POST /api/extension/config (el proxy de la consola es /api/admin/extensions/config: lectura nivel 3, escritura y importación nivel 4; CLI: extensions config, config set, config reset, config import-env).
• Auditoría: cada cambio registra admin.extension.config con la acción, el resultado y solo los nombres de las claves cambiadas o importadas, nunca sus valores.
• Límites: hasta 60 campos por esquema; texto de 1000 caracteres (5000 en multiline); listas de 200 elementos de 200 caracteres; JSON de 8 KB; patrones regex de 200 caracteres sin referencias hacia atrás ni lookaround; settings.config completo, 32 KB.

Webhooks salientes#

La extensión webhooks (core-webhooks) entrega eventos de correo a las URL que configure el administrador. Se configura en la consola (extensiones → Webhooks → Ajustes): hasta 20 endpoints, cada uno con nombre, URL https, interruptor *Activo*, secreto de firma (cifrado y de solo escritura), eventos, filtros y límites. Sin secreto no se entrega.

Filtros y contenido#

Los filtros opcionales folder, senderDomain y label solo se evalúan si el evento trae ese dato; si el filtro está configurado y falta el dato, el evento no se entrega (skipped): es más seguro filtrar de más que de menos. includeSubject e includeBody solo añaden asunto/cuerpo cuando el contexto del evento los trae.

Payload y firma#

{ "id": "7b0c2f0e-...", "type": "email.received", "version": 1, "createdAt": "2026-01-01T10:00:00.000Z",
  "data": { "emailId": "...", "userId": "...", "timestamp": "..." } }

• Cabeceras: X-BloomX-Signature: sha256=<hex>, X-BloomX-Timestamp (segundos Unix), X-BloomX-Event y X-BloomX-Delivery (uuid, igual en los reintentos).
• Firma: sha256=HMAC-SHA256(secreto, "<timestamp>.<cuerpo exacto>"). El timestamp se renueva en cada reintento; el id del payload no cambia, así que sirve para deduplicar.
• Verificación en el receptor: usa el cuerpo crudo, compara en tiempo constante y rechaza timestamps con más de 5 minutos de diferencia (anti-replay). Guarda además los X-BloomX-Delivery ya vistos durante 5 minutos.

const crypto = require('node:crypto');

// rawBody: el cuerpo CRUDO recibido (string/Buffer), sin reserializar
function verify(rawBody, headers, secret, toleranceSec = 300) {
  const ts = Number(headers['x-bloomx-timestamp']);
  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > toleranceSec) return false; // anti-replay
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const got = String(headers['x-bloomx-signature'] || '');
  return got.length === expected.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}

import hashlib, hmac, time

def verify(raw_body: bytes, headers: dict, secret: str, tolerance: int = 300) -> bool:
    try:
        ts = int(headers["X-BloomX-Timestamp"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - ts) > tolerance:
        return False
    signed = f"{ts}.".encode() + raw_body
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, headers.get("X-BloomX-Signature", ""))

Entrega, reintentos y registro#

• Reintentos de 0 a 5 con espera exponencial (300 ms · 2^n) dentro de un presupuesto de ≈9 s por evento (los hooks se cortan a 10 s) y 18 peticiones por invocación (el sandbox permite 20). Los endpoints se entregan en paralelo.
• Límite de tasa por endpoint (rateLimitPerMinute), calculado sobre el registro de entregas (máximo 100 entradas guardadas).
• SSRF y redirecciones: solo https, sin credenciales en la URL, sin localhost, redes privadas ni IPv6 literal; no se siguen redirecciones (una 3xx se registra como fallo: configura la URL final).
• Enviar evento de prueba: botón dentro de cada endpoint (deshabilitado si tiene cambios sin guardar); hace un único intento de webhook.test y muestra código, latencia y mensaje.
• Registro de entregas: «Registro de ejecuciones recientes» en Estado y registro (fecha, evento, destino, estado, intentos, latencia, código, mensaje). Nunca URLs, cuerpos, cabeceras ni secretos.
• Endpoint heredado (webhookUrl / WEBHOOK_URL): si no hay endpoints se sintetiza uno solo para EMAIL_RECEIVED, firmado con WEBHOOK_SECRET si existe y con el campo antiguo event: "email_received". Ambos ajustes están obsoletos: crea un endpoint nuevo con su secreto y retira el heredado.

Grupos por defecto de mail-groups#

• `defaultGroups` (desde la 1.1.0) es una lista objects de hasta 30 grupos del dominio: alias, dirección opcional, descripción, hasta 200 miembros y visibilidad (domain o private). Plantillas sugeridas (no activas): todos, soporte y ventas.
• Prioridad del usuario: los grupos del dominio se fusionan por debajo de los alias del usuario; si el usuario tiene un alias con el mismo nombre (con o sin @), gana el suyo y nunca se modifica ni se borra nada de lo suyo. La expansión es idempotente y no duplica direcciones.
• Aplicar ahora (applyNow) no copia nada: el modelo es de expansión en tiempo de uso, así que la acción devuelve un informe de validación (report[]: aplicado u omitido y el motivo).
• `autoAddNewUsers` no existe por una limitación técnica real: añadir usuarios nuevos exige conocer los usuarios del dominio y enterarse de un alta, y el sandbox no tiene ni un servicio de directorio de usuarios (ctx.user es solo quien ejecuta; los services.* operan sobre el usuario actual) ni un evento de alta en LIFECYCLE_EVENTS. Haría falta un servicio de host users.list con permiso propio o un evento USER_CREATED con su lista blanca de contexto.

Sandbox y sus límites#

Cada invocación crea un worker_threads nuevo (sin variables de entorno del proceso) con un contexto node:vm de prototipo nulo y sin eval/new Function. Toda entrada/salida sale por mensajes al hilo principal.

• Disponible: console, setTimeout/clearTimeout, URL, URLSearchParams, un Buffer mínimo (from, byteLength, isBuffer, toString), crypto con randomUUID, sha256Hex y hmacSha256Hex, fetch (a través de safe-fetch), module/exports y process.env (solo las variables autorizadas).
• No existe: require, import, eval, setInterval, AbortController, Headers, Request, Response, FormData, Blob.
• safe-fetch bloquea IP privadas y metadatos de nube, valida la IP al conectar y limita las redirecciones a 3.

Hooks (intercepts)#

Un intercept engancha una función a un evento del sistema. Se declara en intercepts o en su alias hooks. Campos: point (EMAIL_PRE_SEND, EMAIL_RECEIVED, CRON o uno de los nueve eventos de ciclo de vida), handler, priority (HIGH, NORMAL, LOW, MONITOR o número), onError (block o continue, por defecto continue) y, para CRON, schedule (hourly o daily).

• Si el backend no responde, el frontend envía igualmente el correo y registra el fallo; con EXTENSION_HOOKS_FAIL_CLOSED=true no lo envía. EXTENSION_HOOKS_DISABLED=true desactiva la llamada. Timeout de la llamada: 10 s.
• En modo legado solo EMAIL_PRE_SEND se acepta; EMAIL_RECEIVED, CRON y los eventos de ciclo de vida responden 403 (estos últimos ni se disparan desde el frontend).

Preferencias del usuario y extensiones obligatorias#

Cada usuario puede desactivar una extensión para sí mismo en /extensions (se guarda en expansionSettings["system:extension-prefs"]). Eso ya no solo oculta la interfaz: en dominios firmados el frontend incluye la lista disabledExtensions (leída de los ajustes del usuario en el servidor, no del navegador; ids válidos, sin duplicados, máx. 200) dentro del cuerpo firmado de hooks y execute, y el backend no ejecuta esas extensiones para ese usuario.

El administrador marca una extensión como obligatoria en la consola (/admin/extensions → detalle → «Obligatoria para todos»; pide confirmación, audita extension.mandatory_changed y exige requireAdmin más la sesión de gestor del dominio). Si el manifest ya la declara, el interruptor queda bloqueado. Desinstalar retira la política. La extensión DLP se publica con mandatory: true.

Detalles de seguridad en Extensiones: validación, preferencias y obligatorias.

Servicios del sandbox (services.*)#

Además de services.ai, services.auth y services.mail, el sandbox ofrece cinco servicios con acceso controlado a los datos del usuario: services.calendar, services.contacts, services.storage, services.notify y services.formats. Cada operación es await ctx.services.<servicio>.<operación>(args): un único objeto de argumentos y una Promise que resuelve con el data de la respuesta. Las tablas reflejan la validación real del backend (host-services.ts, formats-service.ts).

Modelo de seguridad#

• Solo dominios firmados. Las llamadas salen firmadas con Ed25519 con la clave del backend hacia /api/internal/<servicio> del frontend del dominio. En modo legado ctx.services.calendar|contacts|storage|notify|formats no existe (ausente): la extensión debe degradar (if (!ctx.services?.calendar) ...). Sin clave de firma en el backend solo queda services.formats (operaciones locales).
• `userId` lo fija el host a partir de la identidad firmada del dominio (X-User-Id); la extensión nunca puede elegirlo ni pasarlo en args. El extensionId (namespacing de storage y atribución de notify) también lo fija el host.
• Propiedad por usuario. Toda consulta y escritura filtra por el usuario; un id ajeno se comporta como inexistente (not_found, sin oráculo). Los calendarios de solo lectura no se pueden escribir (read_only).
• Sin secretos. Nunca se exponen tokens de Google, externalId, syncToken ni inviteUid. Los errores no llevan detalles internos ni datos personales.
• Mínimo privilegio. Cada operación exige un permiso del manifest; sin él, falla con <SERVICIO>_PERMISSION_DENIED (no con un "undefined is not a function").
• Argumentos estrictos. Una clave desconocida es error (<SERVICIO>_INVALID_ARGS). El frontend revalida con zod estricto.
• Anti-bucle. Los cambios hechos por services.* no disparan hooks de ciclo de vida (p. ej. crear un evento con createEvent no emite CALENDAR_EVENT_CREATED).

services.calendar#

Fechas en ISO 8601. Un Event es {id, calendarId, title, description, location, startsAt, endsAt, allDay, status, responseStatus, source, organizerEmail, conferenceUrl, attendees:[{email,name,responseStatus}]}.

services.contacts#

Un Contact es {id, email, name, notes, source, createdAt}.

services.storage#

Almacén clave-valor privado por usuario y extensión: una extensión no puede leer el de otra. Claves ^[A-Za-z0-9_.:/-]{1,128}$; el valor es cualquier JSON serializable. Al borrar al usuario se borran sus filas.

// Permiso: STORAGE. Contador persistente por usuario y extension.
const storage = ctx.services && ctx.services.storage;
if (!storage) return { success: false, code: 'STORAGE_SERVICE_UNAVAILABLE' };
try {
    const current = await storage.get({ key: 'stats/opened' });          // { value: null } si no existe
    const count = (current.value && current.value.count) || 0;
    await storage.set({ key: 'stats/opened', value: { count: count + 1 } });   // { ok: true, usedBytes, quotaBytes }
    const page = await storage.list({ prefix: 'stats/', limit: 20 });    // { keys, usedBytes, quotaBytes }
    await storage.delete({ key: 'stats/old' });                          // { deleted: boolean }
} catch (error) {
    if (String(error.message).startsWith('STORAGE_INVALID_ARGS')) { /* valor > 64 KB o clave invalida */ }
    if (error.message === 'STORAGE_ERROR: quota_exceeded') { /* cuota de 256 KB agotada */ }
}

services.notify#

El aviso se guarda y la interfaz lo muestra como toast (GET /api/expansions/notifications). Tope de 20 pendientes por usuario y extensión y 30 por minuto por extensión (rate_limited).

services.users (solo lectura)#

Permiso `READ_USERS` (riesgo alto: lo aprueba el administrador al instalar o actualizar la extensión). Lista y consulta las cuentas de este dominio: la fuente es la propia instancia (su base de datos) a través del puente firmado con la executionGrant, así que no hay forma de consultar otro dominio. Exige la capacidad lifecycle.events.v2 (cliente con clientApi ≥ 7).

• Campos mínimos: id, email, name y createdAt. Nunca contraseña ni hash, tokens, MFA, ajustes ni nivel de permiso.
• Paginación estable por cursor (fecha de alta + id): un alta durante el recorrido ni duplica ni salta filas.
• Cuotas: 30 llamadas por ejecución, 120 consultas por minuto por extensión (USERS_ERROR: rate_limited) y límite por usuario en la ruta. Cada consulta queda en la auditoría (extension.users.read: quién, extensión, operación y número de filas; sin datos de las cuentas).
• Permisos reales en dos sitios: el backend (manifest) y la instancia (la executionGrant firmada por ella lleva los permisos); sin READ_USERS falla con USERS_PERMISSION_DENIED.
• Solo dominios firmados. En modo legado ctx.services.users no existe: degrada.

let cursor = null;
do {
    const page = await ctx.services.users.list({ limit: 100, cursor: cursor ?? undefined });
    for (const u of page.users) { /* u.id, u.email, u.name, u.createdAt */ }
    cursor = page.nextCursor;
} while (cursor);

Estado compartido del dominio (storage.listShared)#

Las claves de services.storage que empiezan por shared/ se guardan en el espacio del usuario, pero cualquier ejecución de la misma extensión puede leerlas con listShared({prefix: "shared/...", limit?}) (1–200, solo valores, sin quién las escribió). Solo se escriben (`set`/`delete`) desde un hook de servidor: la concesión firmada por la instancia lleva el evento que originó la ejecución, y sin él la escritura falla con STORAGE_ERROR: forbidden; así un usuario no puede añadirse a listas compartidas desde el navegador. mail-groups lo usa para el alta automática en grupos.

Ejemplo completo#

Busca un hueco libre, crea el evento y avisa al usuario. Es el patrón de summarizer (que solo crea eventos tras confirmación explícita), simplificado.

// server.js
// Permisos: CALENDAR_READ, CALENDAR_WRITE, NOTIFY
module.exports = {
    bookFirstSlot: async (ctx) => {
        const { calendar, notify } = ctx.services || {};
        if (!calendar) return { success: false, code: 'CALENDAR_SERVICE_UNAVAILABLE' };   // modo legado o sin permiso: degradar
        try {
            const from = new Date().toISOString();
            const to = new Date(Date.now() + 7 * 86400000).toISOString();
            const { slots } = await calendar.findFreeSlots({ from, to, durationMinutes: 30, timeZone: 'Europe/Madrid', limit: 1 });
            if (slots.length === 0) return { success: false, code: 'NO_SLOT' };
            const title = String((ctx.args && ctx.args.title) || 'Reunion').slice(0, 200);
            const { event } = await calendar.createEvent({ title, startsAt: slots[0].start, endsAt: slots[0].end });
            if (notify) await notify.toast({ message: 'Evento creado', level: 'success', url: '/calendar' }).catch(() => {});
            return { success: true, eventId: event.id };
        } catch (error) {
            // p. ej. 'CALENDAR_PERMISSION_DENIED: services.calendar.createEvent requires CALENDAR_WRITE ...'
            return { success: false, code: String(error.message).split(':')[0] };
        }
    },
};

Límites por invocación#

Errores#

Todo fallo es un Error cuyo mensaje empieza por el prefijo del servicio (<P>): CALENDAR_, CONTACTS_, STORAGE_, NOTIFY_ o FORMATS_. Atrápalo con try/catch y decide.

services.formats (utilidades puras)#

Requiere el permiso FORMATS (riesgo bajo: no accede a datos del usuario). Todo salvo plantillas y HTML se resuelve en el propio backend, sin red; renderTemplate y sanitizeHtml viajan al frontend por el puente firmado.

// Permiso: FORMATS. Todo devuelve una Promise; sin permiso falla con FORMATS_PERMISSION_DENIED.
const f = ctx.services && ctx.services.formats;
if (!f) return { success: false, code: 'FORMATS_SERVICE_UNAVAILABLE' };

const when = await f.formatDate({ value: '2026-10-05T15:30:00Z', locale: 'es-ES', timeZone: 'Europe/Madrid', style: 'long' });   // texto con formato local (string)
const price = await f.formatNumber({ value: 1234.5, locale: 'es-ES', style: 'currency', currency: 'EUR' });                  // texto con formato local (string)

const { ics } = await f.buildIcs({                                   // CRLF, escapes y folding a 75 octetos ya aplicados
    method: 'REQUEST',
    events: [{ summary: 'Demo, con coma; y punto y coma', startsAt: '2026-10-05T15:30:00Z', endsAt: '2026-10-05T16:00:00Z',
               attendees: [{ email: 'ana@example.com', name: 'Ana' }] }],
});
const { events } = await f.parseIcs({ ics });                        // [{ uid, summary, startsAt, endsAt, allDay, attendees, ... }]

const { vcard } = await f.buildVcard({ version: '4.0', contacts: [{ name: 'Ana Perez', email: 'ana@example.com', org: 'Acme' }] });
const { contacts } = await f.parseVcard({ vcard });                  // [{ name, email, phone, org, title, note }]

const { text } = await f.renderTemplate({ template: 'Hola {{ nombre }}', variables: { nombre: 'Ana' } });   // Liquid; un fallo de render es un error, nunca la plantilla cruda
const { html } = await f.sanitizeHtml({ html: '<p onclick="x()">Hola</p><script>x()</script>' });

• ICS y vCard seguros. En buildIcs y buildVcard los CR/LF y caracteres de control se eliminan de todo valor (no se puede inyectar una propiedad nueva), los textos se escapan (\, ;, , y saltos de línea) y las líneas se pliegan a 75 octetos sin partir caracteres UTF-8, con CRLF. Los parámetros (CN) se limpian de comillas y separadores.
• parseIcs y parseVcard despliegan las líneas plegadas, desescapan y limpian controles; ignoran lo que no reconocen.
• renderTemplate: si la plantilla falla (sintaxis, límites) el error es FORMATS_ERROR: invalid_args; nunca se devuelve la plantilla sin renderizar. Escapa los valores de las variables que vayan a un HTML antes de interpolar (así lo hace signature).
• sanitizeHtml usa la misma configuración del sanitizador del frontend (DOMPurify: sin scripts, formularios, iframes ni URI peligrosas; los enlaces reciben rel="noopener noreferrer nofollow"), ejecutada en el servidor con un DOM, así que conserva el formato seguro. Si el DOM del servidor no estuviera disponible, degrada a texto escapado sin etiquetas (seguro, pero sin formato).
• Los fallos de las operaciones locales se reportan como FORMATS_ERROR: invalid_args (sin detalles internos).

Eventos de ciclo de vida#

Son nueve eventos de la aplicación a los que una extensión puede suscribirse. Se declaran como cualquier intercept: en intercepts o en su alias hooks (misma forma {point, handler, priority?}). El handler recibe ctx = {...contexto, event, userId} más services. La tabla muestra el contexto mínimo y exacto: el backend lo filtra con una lista blanca y descarta cualquier otro campo (asuntos, cuerpos, destinatarios…).

{
  "manifestVersion": "1.0",
  "id": "contact-welcome",
  "version": "1.0.0",
  "name": "Contact welcome",
  "permissions": ["CONTACTS_READ", "STORAGE", "NOTIFY"],
  "api": {
    "runtime": "nodejs",
    "entry": "server.js",
    "functions": { "onContactSaved": { "handler": "onContactSaved", "timeout": 8000 } }
  },
  "hooks": [
    { "point": "CONTACT_SAVED", "handler": "onContactSaved", "priority": "NORMAL" }
  ]
}

// server.js
module.exports = {
    // hook CONTACT_SAVED, ctx = { contactId, email, created, source, event, userId, settings, services }
    onContactSaved: async (ctx) => {
        const { storage, contacts, notify } = ctx.services || {};
        if (!storage || !ctx.created) return { skipped: true };     // modo legado: los hooks de ciclo de vida ni se disparan
        try {
            const key = 'seen/' + ctx.contactId;
            const seen = await storage.get({ key });
            if (seen.value) return { skipped: true, reason: 'already_seen' };
            const found = contacts ? await contacts.get({ contactId: ctx.contactId }) : { contact: null };
            const label = (found.contact && found.contact.name) || ctx.email || ctx.contactId;
            await storage.set({ key, value: { at: new Date().toISOString() } });
            if (notify) await notify.toast({ message: 'Nuevo contacto: ' + String(label).slice(0, 150), level: 'info' });
            return { success: true };
        } catch (error) {
            return { success: false, code: String(error.message).split(':')[0] };   // un hook nunca debe lanzar
        }
    },
};

Eventos v2 (lifecycle.events.v2)#

Cinco eventos más, con payload versionado (v: 1) y mínimo. Cada uno exige un permiso en el manifest (si falta, validateManifest da error y el backend no invoca el handler) y la capacidad lifecycle.events.v2 (requires.clientApi ≥ 7: los clientes antiguos siguen recibiendo la versión anterior de la extensión). No existe USER_DELETED: la plataforma no borra cuentas, solo las deshabilita.

• El handler corre COMO el usuario afectado en USER_* (ctx.userId == subjectUserId) y como el dueño del buzón en el resto; ctx.services.users permite leer el directorio.
• Procedencia: `ctx.hook = {event, eventKey}` lo fija solo el servidor (en /execute es siempre null, aunque el cliente envíe context.hook). Un handler que actúa sobre eventos v2 debe exigir ctx.hook?.event === "...": el resto del contexto puede venir de un cliente.
• Idempotencia: eventKey es determinista por hecho (uc:<id>, sp:<correo>, lb:<correo>:<etiqueta>, …). El frontend descarta repeticiones del mismo hecho durante 10 min (60 s en etiquetas) y los consumidores deben deduplicar por eventKey (los webhooks usan un id/X-BloomX-Delivery estable derivado de él).
• Asíncronos y aislados: after(), timeout de 5 s en la llamada, ≤ 60 por minuto, y un fallo (backend caído, handler roto, timeout) solo deja una línea de log: nunca bloquea ni revierte el registro, el alta, la deshabilitación, la ingesta ni el etiquetado.
• Privacidad por defecto: sin contraseñas, hashes, tokens, asuntos ni cuerpos (lista blanca en el frontend y otra vez en el backend). La importación de correo y lo que hagan las extensiones con services.* no emiten estos eventos (anti-bucle).

Reglas y límites#

• No bloqueantes. No pueden impedir ni modificar la acción: stop y modify se ignoran (solo EMAIL_PRE_SEND los admite). onError: "block" se ignora y validateManifest lo avisa. El frontend los lanza en segundo plano (after()), así que no retrasan la respuesta al usuario.
• Solo dominios firmados. En modo legado no se dispara ninguno. El userId sale de la identidad firmada, nunca del cuerpo.
• Límites. Como máximo 10 handlers por evento (el resto se ignora), ordenados por prioridad; timeout por handler ≤ 10 s (el menor entre el del manifest y 10 s) y presupuesto total de 20 s (pasado el cual los handlers pendientes se omiten). La llamada del frontend espera como máximo 5 s.
• Frecuencia. El frontend emite como máximo 60 disparos por minuto por usuario y evento; el exceso se descarta en silencio.
• Anti-bucle. Lo que hagas con services.* dentro del handler no vuelve a disparar eventos.
• Un point desconocido es un error de manifest; EMAIL_PRE_SEND, EMAIL_RECEIVED y CRON siguen su propia semántica (ver Hooks).

Puntos de montaje y su contexto#

Cada punto pasa a la extensión un contexto fijo (el registro MOUNT_POINT_CONTEXT de src/lib/expansions/mount-points.ts); se lee con expresiones ${context.clave}. El contexto nunca incluye auth, user, env ni services: la identidad la pone el servidor. La columna Estado indica si hoy hay un <ExtensionLoader> que lo pinte, según el código del frontend.

Los demás puntos (EVENT_LOCATION_BUILDER, CUSTOM_SETTINGS_TAB, PAGE, OVERLAY, SLASH_COMMAND, *_HANDLER…) mantienen su comportamiento anterior. Un punto que el schema conoce pero la interfaz aún no pinta valida sin avisos y no se muestra: no falla, pero no tiene efecto hasta que exista el consumidor.

{
  "manifestVersion": "1.0",
  "id": "sender-context",
  "version": "1.0.0",
  "name": "Sender context",
  "permissions": ["CONTACTS_READ", "STORAGE"],
  "api": {
    "runtime": "nodejs",
    "entry": "server.js",
    "functions": {
      "lookupSender": { "handler": "lookupSender" },
      "savePrefs": { "handler": "savePrefs" }
    }
  },
  "mounts": [
    {
      "point": "EMAIL_READER_SIDEBAR",
      "component": {
        "type": "CARD",
        "props": { "title": "Sender" },
        "children": [
          { "type": "HEADLESS", "props": { "onLoad": {
            "action": "CALL_BACKEND", "function": "lookupSender",
            "args": { "email": "${context.fromContact.email}" },
            "onSuccess": { "action": "SET_STATE", "key": "sender", "value": "${result}" }
          } } },
          { "type": "TEXT", "props": { "content": "${state.sender.name}" } }
        ]
      }
    },
    {
      "point": "SETTINGS_PANEL",
      "component": {
        "type": "FORM",
        "props": { "onSubmit": {
          "action": "CALL_BACKEND", "function": "savePrefs",
          "args": { "label": "${formData.label}" },
          "onSuccess": { "action": "TOAST", "message": "Saved" }
        } },
        "children": [ { "type": "INPUT", "props": { "name": "label", "label": "Label" } } ]
      }
    }
  ]
}

slashCommands#

Los comandos / del editor de redacción salen de los manifests de las extensiones instaladas. Cada uno es {key, description, action, arguments?} con key ^[a-zA-Z0-9_-]{1,32}$. / al inicio o tras un espacio abre el menú; flechas, Home/End navegan, Enter ejecuta, Tab completa y Esc cierra. El texto tras el comando llega como args/slashArgs. Si dos extensiones repiten la clave gana la primera.

"slashCommands": [
  { "key": "shrug", "description": "Insertar ¯\\_(ツ)_/¯", "action": { "action": "INSERT_CONTENT", "content": "¯\\_(ツ)_/¯" } },
  { "key": "ai", "description": "Redactar con IA", "arguments": "<tema>",
    "action": { "action": "OPEN_OVERLAY", "targetId": "ai-dialog", "passArgs": true } }
]

Versionado del cliente y compatibilidad#

El backend es compartido y guarda una sola copia de cada extensión, pero cada instancia (frontend) puede desplegar una versión distinta del cliente. La solución es versionar el cliente y negociar capacidades: el cliente dice qué sabe hacer y el backend sirve a cada instancia la versión de la extensión que ese cliente puede ejecutar.

Identidad del cliente#

• CLIENT_API_VERSION (entero; hoy 5): contrato cliente↔backend de extensiones. Es independiente de la versión de la app y del BUILD_ID. CLIENT_CAPABILITIES son cadenas estables. Ambos se definen en src/lib/expansions/client/capabilities.ts.
• Registro único CAPABILITY_REGISTRY en client-contract.ts (copia idéntica en el frontend, el backend y bloomx-extensions/_shared).
• Cabeceras X-BloomX-Client-Api (entero) y X-BloomX-Client-Caps (lista separada por comas, máx. 1024 caracteres y 64 capacidades) en todas las llamadas al backend.
• Con firma Ed25519 activa, el mensaje firmado pasa a BLOOMX-SIG-V2 = V1 + dos líneas (api y caps), de modo que no se pueden quitar ni añadir. Sin firma (modo legado) viajan como informativas.
• Un cliente sin cabeceras es la línea base legacy: clientApi 1 + las capacidades con since: 1.

requires en el manifest#

"requires": { "clientApi": ">=2", "capabilities": ["settings.schema.v1", "ai.v1"] }
// clientApi: 2 | ">=2" | ">=2 <4"   (sin "requires" = compatible con legacy / without it = legacy-compatible)

• Sin requires la extensión es compatible con legacy (todas las 1.0.x).
• Las capacidades desconocidas se rechazan al publicar: hay que registrarlas primero (decisión documentada, evita erratas y capacidades futuras sin soporte).
• Un verificador estático (bloomx-extensions/_shared/feature-rules.mjs, usado por validate y por los tests) obliga a declarar la capacidad cuando el manifest o server.js usa settingsSchema, onSubmit en campos (no FORM), los componentes STACK/REPEAT/EMPTY/SKELETON/TEXTAREA u onCancel, props.toolbar, un bloque ai o services.ai.chat/status, ai.json(), eventos de ciclo de vida, permisos de servicios del host, o kind/conferencingProviders.

Resolución por petición#

• Se sirve la versión más alta no-yanked cuyos requires cumple el cliente.
• La versión fijada por el dominio (settings.meta.pinnedVersion, o install con version explícita) se respeta si es compatible y no está yanked.
• Si hay una versión más nueva incompatible, la respuesta incluye upgrade { latestVersion, requires, missingCaps, clientApiNeeded }.
• Si ninguna es compatible, la extensión no se entrega: aparece en incompatibleExtensions de /api/config, y install/update/toggle/execute responden 409 EXTENSION_CLIENT_INCOMPATIBLE.
• La ejecución en el backend (execute, hooks, settings, config) usa la versión resuelta para ese dominio y cliente. mandatory se conserva: si la última versión viva es obligatoria, la servida también.
• Se aplica en /api/config, /api/extensions, public-list, /api/manager/extensions (versionInfo), execute, hooks y settings/config.

Tabla ExtensionVersion#

ExtensionVersion guarda extensionId, version, template, requiresClientApi, requiresCaps, status (published, deprecated, yanked), scriptUrl, scriptSource y contentHash, con UNIQUE(extensionId, version). Extension es el puntero a la última versión. Las versiones son inmutables: el mismo número con otro contenido responde 409 VERSION_EXISTS (el sync aborta; sube la versión, o usa --replace <id>@<ver> de forma explícita).

Publicar una extensión que necesita un cliente nuevo#

1. Cliente: registra la capacidad en CAPABILITY_REGISTRY (las 3 copias), añádela a CLIENT_CAPABILITIES, sube CLIENT_API_VERSION si cambia el contrato y añade la regla en feature-rules.mjs.
2. Extensión: sube la versión, añade requires, ejecuta npm run validate y npm test. Conserva la anterior publicable: node --experimental-strip-types scripts/archive-legacy-versions.mjs (desde bloomx-extensions) archiva versiones previas desde git en <ext>/versions/<ver>/.
3. Sync: node --env-file=.env scripts/sync-repository-extensions.mjs (o sync-extensions.mjs). Conserva la versión que sirve la BD, archiva y mueve el puntero.
4. Orden de despliegue: (a) crear la tabla ExtensionVersion (prisma/schema_push.prisma con npm run prisma:push, o el DDL idempotente de prisma/schema.prisma); (b) desplegar el backend (preview primero, luego prod); (c) ejecutar el sync de extensiones; (d) desplegar los frontends.

Deprecación y ciclo de vida#

• Política: se mantiene publicada como mínimo la última versión compatible con la línea base legacy mientras haya instancias legacy, y las 2 últimas versiones menores previas de cada línea.
• deprecated = se sirve marcada; yanked = nunca se sirve, instala ni ejecuta. Ambos son reversibles.
• CLI: node --env-file=.env scripts/extension-version.mjs list|yank|deprecate|restore <id> [<version>]. API: POST/GET /api/admin/extensions/versions (Basic Auth de plataforma).
• Regla: añadir una capacidad exige registrarla y/o subir CLIENT_API_VERSION; los tests lo exigen.
• Opcional: la variable BLOOMX_MIN_CLIENT_API en el backend añade la cabecera X-BloomX-Min-Client-Api a las respuestas de extensiones. Enlaza con la sección «Cómo se actualiza la PWA» de Operación.

Versiones legacy archivadas#

Extensiones con carpeta versions/ en el repositorio de extensiones: appointments, calendar, composer-helper, dlp, giphy, google-drive, google-meet, google-sync, hubspot, mail-groups, notion, organizer, sealer, signature, slash-commands, smart-reply, summarizer, translator, trello, webhooks, zoom. Se reconstruyen desde el historial git eligiendo, por cada número de versión, el commit más nuevo compatible con la línea base. El contenido que hoy sirva la BD de producción se conserva automáticamente en el primer sync (la BD manda). Si el commit histórico no existe, no se puede reconstruir esa versión.

Catálogo actual y estado#