Admin CLI y consola de comandos

La administración de BloomX se puede hacer también con comandos: una terminal en el navegador (/admin/profile/console) y una CLI por API (bloomx, paquete @kyntocg/bloomx-cli) que se conecta por HTTPS a la misma instancia. Ambas usan el mismo motor: un catálogo de comandos tipado cuyos handlers llaman a las MISMAS rutas /api/admin/* que la consola gráfica (misma validación, límites y auditoría), así que nada se duplica y nada queda fuera.

Instalación#

npm i -g @kyntocg/bloomx-cli     # Node >= 18, sin dependencias
# o sin instalar:
npx @kyntocg/bloomx-cli login https://mail.example.com

Iniciar sesión y dominio acotado#

bloomx login https://mail.example.com pide correo, contraseña (sin eco) y el código MFA si aplica, y guarda un token (nunca la contraseña) en tu almacén de usuario con permisos 0600 (~/.config/bloomx/credentials.json, %APPDATA%\bloomx en Windows; jamás en el repositorio). La cuenta debe ser un administrador de esa instancia (permission_level ≥ 1) o la manager dueña del dominio de la instancia en el backend compartido. Tras el login la CLI muestra el dominio al que quedó acotada la sesión y todos los comandos operan solo sobre ese dominio: no existe una bandera --domain.

bloomx login https://mail.example.com            # interactivo
bloomx login https://mail.example.com --token bxa_...   # con un token creado en la consola web (tokens create)
bloomx whoami                                    # cuenta, rol, permission_level, dominio y ámbitos
bloomx profiles | bloomx use mail.acme.com       # varias instancias (perfiles)
bloomx logout [--all]                            # revoca el token en el servidor

Uso#

bloomx help                                      # catálogo (solo lo que tu nivel permite)
bloomx help users sessions revoke                # un comando
bloomx users list --status disabled --json | jq .
bloomx users create ana@example.com --name "Ana"  # contraseña temporal, se muestra UNA vez
bloomx audit --event "admin.users.*" --from 2026-01-01
bloomx theme export > theme.json && bloomx theme import --file theme.json --dry-run
bloomx shell                                      # REPL (alias: bloomx ssh): Tab, ↑/↓, Ctrl+C, Ctrl+L

• Salida: tablas y texto con los colores de tu terminal (o del tema en la web); --json entrega datos en bruto para pipes; los comandos que devuelven CSV lo escriben a stdout (> users.csv) o con --out.
• Entrada: --file ruta.json o --stdin (pipe) para comandos con JSON/CSV; en la consola web, --stdin abre un modo pegado (termina con una línea EOF).
• Códigos de salida: 0 ok · 1 error del comando · 2 uso incorrecto · 3 sin permiso o sin sesión · 4 falta confirmación o step-up · 5 límite de tasa/tiempo · 6 red · 127 comando desconocido.
• Consola web (/admin/profile/console, enlazada en el menú y en «Mi perfil»): historial con ↑/↓ (solo en la pestaña), Tab (comandos, subcomandos, banderas, valores y correos de usuarios), help, clear/Ctrl+L, exit, Ctrl+C que cancela, copiar salida, región role="log" accesible y diseño adaptable.
• Importar archivos de correo: bloomx transfer import <archivo> sube por trozos con hash y reanudación (--resume); transfer download <job> --out baja una exportación. El navegador no puede leer archivos locales desde la terminal: para eso está el asistente de /admin/transfer.

Niveles de permisos (permission_level)#

El rol de administrador ya no es un sí/no: cada cuenta tiene un `permission_level` de 0 a 4 (columna "permission_level" de la tabla UserPermission, el mismo nombre en la API, la CLI y el JSON). El nivel efectivo es el máximo entre el del entorno y el de la base de datos. Cada ruta, comando y sección del menú declara su nivel mínimo en un único sitio (src/lib/admin-levels.ts); la comprobación vive en requireLevel(n) (rutas) y en el motor de comandos, de modo que ocultar un botón nunca es la única barrera (las rutas responden 403 aunque se llamen directamente). requireAdmin equivale a nivel ≥ 3.

• `ADMIN_EMAILS` es semilla y rescate: esos correos son nivel 4 «fijado por entorno»; la consola y la CLI no pueden degradarlos (solo quitándolos de la variable). Compatibilidad total: quien hoy es admin queda en 4. ADMIN_EMAILS_LOCKED=true = modo solo-entorno (la gestión por consola/CLI se desactiva: nivel 4 si está en el entorno, 0 si no). La manager dueña del dominio se trata como nivel 4 en su instancia.
• Quién asigna qué: solo un nivel estrictamente menor al propio (un superadmin asigna 0-4; conceder el 4 exige confirmación explícita --confirm-super). Nadie modifica a alguien de nivel igual o superior (un superadmin sí puede revocar a otro superadmin de consola, nunca al del entorno) ni a sí mismo: nadie se auto-escala ni se auto-degrada, y la instancia nunca se queda sin superadmin.
• Cada cambio exige step-up con MFA (un código TOTP reciente; la manager usa su contraseña), exige que la cuenta exista y tenga MFA (o que el MFA sea obligatorio y se enrole en su primer acceso), respeta un máximo de 25 cuentas con nivel ≥ 3, tiene rate limit, se audita (admin.permissions.changed: quién, a quién, nivel anterior → nuevo, IP; historial inmutable en UserPermissionHistory) y avisa por correo a la cuenta y a los superadmins. Los cambios aplican a las sesiones abiertas en ≤ 30 s y bajar o quitar el nivel invalida de inmediato sus tokens de CLI (a nivel 0 también su sesión privilegiada).
• Acciones sobre otras cuentas (deshabilitar, restablecer, cuotas, sesiones, desvincular...): el actor debe tener un nivel mayor que el de la cuenta objetivo (cannot_modify_peer_or_higher).
• Menú y vistas: el menú oculta lo que tu nivel no permite; la vista Permisos (/admin/permissions) muestra la escala, las cuentas con nivel ≥ 1 (origen entorno/consola, quién lo concedió y cuándo), el selector «Asignar nivel» con step-up y el historial; la ficha de usuario muestra «Nivel de permisos: N · nombre» con un selector de solo los niveles que puedes asignar.
• Tokens de CLI: heredan el nivel de la cuenta como tope (nunca más; si la cuenta baja, el token baja) y además tienen su ámbito: read desde el nivel 1, write y security desde el 2 (los comandos de seguridad siguen exigiendo su propio nivel).

bloomx perms levels                              # la escala 0-4
bloomx perms list [--json]                       # cuentas con nivel >= 1, origen y estado
bloomx perms set ana@example.com 2 --note "helpdesk"   # step-up con código MFA
bloomx perms set cto@example.com 4 --confirm-super     # conceder superadmin
bloomx perms history --email ana@example.com
bloomx perms unlock ana@example.com              # solo superadmin (ver sesión privilegiada)

Una sola sesión privilegiada#

Para toda cuenta con permission_level ≥ 1 solo puede haber una sesión privilegiada abierta a la vez, contando juntas la consola web de administración (/admin/**, incluida la consola de comandos) y el CLI interactivo (tokens de CLI). No afecta al correo web normal de la cuenta (que conserva sus sesiones habituales mientras no entre al admin).

• La sesión nueva gana: en el primer uso de admin de una sesión web (su jti) o de un token interactivo que no es el dueño del slot (tabla PrivilegedSession, una fila por cuenta), la anterior se revoca en el acto en servidor (jti en RevokedSession o token revocado) y, al volver a usarse, recibe 401 `superseded` con un mensaje claro («Tu sesión se cerró porque iniciaste otra desde <dispositivo> (<IP>) a las <hora>»); la web redirige al login y el CLI explica qué hacer. Dos entradas simultáneas se serializan con un candado por cuenta: gana una y la otra queda revocada. Las renovaciones y refrescos conservan el jti: no son una sesión nueva.
• Decisión sobre los tokens: por defecto todo token interactivo ocupa el slot, sin excepciones (también los de solo lectura creados desde la consola web). Los tokens «machine» (tokens create --machine: cron/CI) son la única clase que no lo ocupa: solo lectura, 24 h por defecto (máx. 7 d), nunca nivel 4 (tope 3), acotados por el nivel de la cuenta, emitidos solo con step-up MFA, listados y revocables (tokens list|revoke), con cada uso auditado e invalidados si la cuenta baja de nivel; respetan el bloqueo de la cuenta.
• Aviso al cerrar la anterior: correo transaccional de la instancia (con la marca del dominio, es/en) y notificación push PWA a la cuenta, con qué sesión se cerró (web o CLI), IP, dispositivo, hora y qué hacer si no fuiste tú (cambiar contraseña y cerrar todas las sesiones). Dedupe: como mucho 1 aviso por minuto y cuenta; sin tokens ni datos sensibles. Si el reemplazo viene de una IP o dispositivo distinto, el aviso lo destaca y se envía además una alerta inmediata (correo + push) a todos los superadmins, con el evento de seguridad admin.session.superseded.suspicious.
• Inactividad y tope: la sesión privilegiada se cierra tras 15 min sin actividad (configurable por instancia entre 5 y 60: session policy set --idle-minutes N, nivel 4 con MFA) y tiene un tope absoluto de 12 h; el siguiente uso recibe 401 `expired` (distinto de superseded). Los sondeos de estado de la cabecera no cuentan como actividad. La web revalida al volver a la pestaña, así que lo detecta al instante y redirige al login con el mensaje.
• «Pelea de sesiones»: 3 reemplazos en 10 min (umbral y ventana configurables con session policy set --lock-threshold/--lock-window) bloquean el acceso privilegiado de la cuenta (web y CLI, también los tokens machine; el correo web normal no se toca) hasta que un superadmin la desbloquee (perms unlock <correo> o el botón de la vista Permisos, con step-up MFA). Al bloquear: correo + push al afectado (qué pasó y qué hacer), alerta a los demás superadmins y evento admin.session.lockout. Rescate: si queda bloqueado el único superadmin, define ADMIN_LOCKOUT_RESET=<correo> en el entorno, vuelve a desplegar, accede (el bloqueo se levanta) y quita la variable; con una manager dueña del dominio también hay desbloqueo desde su consola.
• Los cierres normales (logout, «Cerrar sesión privilegiada», bloomx logout, caducidad) liberan el slot; bajar a nivel 0 revoca la sesión privilegiada. Las managers dueñas del dominio usan una cookie del backend compartido que esta instancia no puede revocar: el slot aplica a sus tokens de CLI, no a su sesión web de manager. La vista Permisos y «Mi perfil» muestran tu sesión privilegiada (dónde, desde cuándo, cuándo caduca) con el botón Cerrar sesión privilegiada (session show / session close).

Seguridad del motor#

• Solo administradores: la consola web usa la cookie de admin (con la cabecera X-Requested-With como defensa CSRF adicional); la CLI usa tokens Authorization: Bearer bxa_.... Cualquier otro caso es 401/403 (falla cerrado); el rol del token se revalida en cada petición.
• Sin ejecución arbitraria: el analizador de línea (comillas y escapes) no es un shell (sin variables, pipes, globbing ni sustitución) y nunca ejecuta comandos del sistema; no lee archivos del servidor y los comandos nunca devuelven variables de entorno ni claves privadas (config get solo muestra una lista blanca y los secretos solo indican si existen).
• Límites: línea de 8 KB, entrada de 512 KB, salida de 1 MB, 25 s por comando síncrono y 60 comandos/min por administrador (límite asíncrono, Redis si está configurado) más un límite por IP.
• Riesgo, confirmación y step-up: cada comando es read, write, destructive o security. Los destructive y security exigen confirmación explícita (--yes o un y interactivo) y step-up (contraseña, código MFA o de recuperación; prueba HMAC de 10 min atada a tu cuenta; los de permisos y tokens exigen un código MFA).
• Auditoría: cada comando ejecutado (y cada rechazo) se registra con el sistema de auditoría existente (usuario, comando saneado, riesgo, resultado, IP, agente, token por su id corto). Se redactan banderas y valores sensibles (contraseñas, tokens, claves, volcados JSON/CSV): nunca se registran. Se consulta con bloomx audit --event "admin.cli.*".
• Aislamiento: funciona en cualquier instancia (nada fijado a un dominio) y no usa secretos globales del backend compartido; los tokens y los niveles son por instancia.

Tokens de CLI#

Se emiten tras iniciar sesión con contraseña y MFA, o desde la consola web con tokens create --name mi-equipo. En la base de datos solo vive el SHA-256 (tabla AdminCliToken); el valor se muestra una sola vez. Tienen nombre, ámbitos (read, write, security), caducidad (12 h por defecto, 30 d máximo), última IP/uso y se revocan al instante (tokens list, tokens revoke <id>, tokens revoke-all, bloomx logout). Máximo 10 activos por cuenta. Los de una manager guardan su cookie de sesión del backend cifrada para que los comandos que hablan con el backend funcionen igual que en la web.

Comandos por categoría#

Generado del catálogo real (159 comandos). Cada uno tiene descripción es/en, nivel mínimo, riesgo y permisos; bloomx help <comando> muestra sus argumentos y banderas. Globales: --json, --yes/-y, --help. Los comandos de este catálogo cubren todas las acciones de las vistas del admin (ver cobertura).

Ayuda#

Sesión y cuenta#

Importar / exportar#

Usuarios#

Cuentas vinculadas#

Sistema#

Correo#

Auditoría#

Retención y cuotas#

Seguridad#

Proveedores OAuth#

Dominio, marca y temas#

Extensiones#

IA de la instancia#

Spam y remitentes#

Facturación y desarrollo#

Permisos#

Sesión privilegiada#

Cobertura de la consola gráfica#

Un test comprueba que cada ruta `/api/admin/`** está cubierta por un comando o excluida con un motivo técnico concreto. Excluidas:

SSH real (opcional, no implementado)#

Si necesitas el protocolo SSH de verdad, la opción es una pasarela en un VPS (o contenedor) con el puerto 22 abierto que proxea a esta API: nunca expone el shell del sistema, solo traduce SSH a llamadas HTTPS autenticadas.

1. Servidor SSH con ssh2 en el VPS: solo autenticación por clave pública (sin contraseñas), una clave por administrador, asociada a su cuenta y a un token de CLI guardado en el almacén del gateway (cifrado).
2. Cada sesión abre un pseudo-terminal que ejecuta el REPL de bloomx en proceso (sin /bin/sh): cada línea se envía a POST /api/admin/cli/exec con el token del administrador; el autocompletado usa GET /api/admin/cli/complete.
3. Hereda todas las garantías del servidor (niveles, ámbitos, step-up, auditoría, slot único de sesión privilegiada, inactividad): el gateway no decide nada. El step-up se pide en el terminal y se reenvía a POST /api/admin/cli/reauth.
4. Endurecimiento: ForceCommand/shell fijo, sin reenvío de puertos ni de agente, límites de conexiones por IP, fail2ban, registros enviados a tu SIEM y rotación de tokens (el slot único cierra el anterior al reconectar).

import { Server } from 'ssh2';
import { readFileSync } from 'node:fs';

const API = process.env.BLOOMX_URL; // https://mail.example.com
const keys = loadAuthorizedKeys();   // { publicKey -> { email, token } } (token en un almacén cifrado)

new Server({ hostKeys: [readFileSync('/etc/bloomx-gw/host_ed25519')] }, (client) => {
  client.on('authentication', (ctx) => {
    const entry = ctx.method === 'publickey' && keys.match(ctx.key);
    entry ? ((client.entry = entry), ctx.accept()) : ctx.reject(['publickey']);
  });
  client.on('session', (accept) => {
    const session = accept();
    session.on('pty', (a) => a()).on('shell', (a) => {
      const stream = a();
      runBloomxRepl(stream, async (line) => {
        const res = await fetch(`${API}/api/admin/cli/exec`, {
          method: 'POST',
          headers: { Authorization: `Bearer ${client.entry.token}`, 'Content-Type': 'application/json' },
          body: JSON.stringify({ line }),
        });
        return res.json();   // { output, text, needs, ... } -> se imprime en el terminal
      });
    });
  });
}).listen(22, '0.0.0.0');

API#

curl -s https://mail.example.com/api/admin/cli/exec \
  -H "Authorization: Bearer $BLOOMX_TOKEN" -H "Content-Type: application/json" \
  -d '{"argv":["users","list","--json"]}'