dbreportes-conector 1.0.0

package/README.md

@@ -0,0 +1,124 @@
+# Conector de DBReportes
+
+Enlace local que permite a DBReportes consultar una base de datos privada
+—`localhost`, un contenedor, la red interna de la empresa— **sin exponerla a
+internet y sin abrir ningún puerto**.
+
+## Cómo funciona
+
+El conector abre una conexión **saliente** hacia el servidor de DBReportes
+(WebSocket sobre 443) y queda a la espera. Cuando alguien ejecuta un reporte,
+el servidor pide por ese enlace que se abra un socket contra la base, y los
+bytes viajan multiplexados por la misma conexión.
+
+Hacia fuera se comporta como cualquier programa que habla con un servicio web:
+no escucha en ningún puerto, no publica la base y no necesita que se toque el
+cortafuegos.
+
+```
+tu red                                     DBReportes
+┌──────────────┐                          ┌──────────────┐
+│  base        │◀── socket local ──┐      │              │
+│  conector    │───── WSS 443 ─────┼─────▶│  servidor    │
+└──────────────┘   (saliente)      └      └──────────────┘
+```
+
+## Uso
+
+El token se genera desde la página, en **Conectores → Nuevo conector**. Se
+muestra **una sola vez**: no queda guardado en claro y no hay forma de volver a
+verlo.
+
+```
+npx dbreportes-conector --servidor https://reportes.tuempresa.com --token dbrk_...
+```
+
+Con variables de entorno, que es lo cómodo en una máquina virtual o un
+contenedor:
+
+```
+DBREPORTES_SERVIDOR=https://reportes.tuempresa.com \
+DBREPORTES_TOKEN=dbrk_... \
+npx dbreportes-conector
+```
+
+Mientras el conector esté en marcha, en el formulario de conexión de
+DBReportes se elige este conector y se escribe el host **tal como lo ve esta
+máquina**: `localhost`, el nombre de un contenedor o una dirección de la red
+interna.
+
+El enlace es de la empresa, no de quien lo levantó: se enciende una vez y
+todos sus empleados trabajan contra esa base desde la página.
+
+## Opciones
+
+| Opción | Variable | Qué hace |
+|---|---|---|
+| `--servidor <url>` | `DBREPORTES_SERVIDOR` | Dirección de DBReportes |
+| `--token <token>` | `DBREPORTES_TOKEN` | Token emitido al dar de alta el conector |
+| `--ca <ruta>` | `DBREPORTES_CA` | Certificado de una autoridad propia |
+| `--sin-verificar` | `DBREPORTES_VERIFICAR_TLS=off` | No verificar el certificado de la base |
+| `--json` | `DBREPORTES_JSON=on` | Una línea de JSON por suceso |
+| `--version` | | Mostrar la versión |
+| `--help` | | Mostrar la ayuda |
+
+Códigos de salida: `0` cierre ordenado · `2` faltan datos o son inválidos ·
+`3` no se pudo leer el certificado.
+
+## Cifrado
+
+Dos capas, y ninguna la puede leer el servidor:
+
+1. **WSS** cifra el tramo entre el conector y DBReportes.
+2. Si la conexión usa `require`, `verify-ca` o `verify-full`, **el cifrado
+   contra la base lo termina el conector**, con el nombre real del host. El
+   servidor solo reenvía bytes ya cifrados.
+
+Por eso `--sin-verificar` es una mala idea salvo en una red de confianza con un
+certificado autofirmado. Lo correcto en ese caso es pasar la autoridad con
+`--ca`.
+
+La conexión a la base es **solo de lectura**: el servidor pone la sesión en
+`default_transaction_read_only` y rechaza cualquier escritura.
+
+## Para automatizar
+
+No hay ningún paso interactivo: nunca pregunta nada ni espera una tecla. Con
+`--json` cada suceso sale como una línea de JSON, con `hora`, `nivel`, `evento`
+y `mensaje`, lista para que otro programa la lea:
+
+```
+{"hora":"2026-09-01T20:14:03.221Z","nivel":"info","mensaje":"enlazado con wss://…","evento":"enlazado"}
+```
+
+Eventos: `arranque`, `enlazado`, `listo`, `stream`, `desenlazado`, `reintento`,
+`aviso`, `cierre`.
+
+`SIGINT` y `SIGTERM` cierran el enlace de forma ordenada, así que funciona
+igual como servicio de systemd o como contenedor.
+
+Ejemplo de unidad de systemd:
+
+```ini
+[Unit]
+Description=Conector de DBReportes
+After=network-online.target
+
+[Service]
+Environment=DBREPORTES_SERVIDOR=https://reportes.tuempresa.com
+Environment=DBREPORTES_TOKEN=dbrk_...
+Environment=DBREPORTES_JSON=on
+ExecStart=/usr/bin/npx dbreportes-conector
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Si el enlace se cae, el conector reconecta solo con espera creciente (de 1 s
+hasta 30 s), así que no hace falta vigilarlo.
+
+## Requisitos
+
+Node.js 20 o superior. Nada más.

package/bin/conector.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+// Arranque del conector desde la terminal.
+//
+// Pensado para que dé igual quién lo lance: una persona, el arranque de una
+// máquina virtual o un agente automático. Por eso no pregunta nada, todo se
+// puede dar por variables de entorno, y con --json cada suceso sale como una
+// línea de JSON que otro programa puede leer.
+import fs from 'node:fs';
+import process from 'node:process';
+
+import { Conector, VERSION } from '../src/conector.js';
+import { tokenBienFormado } from '../src/protocolo.js';
+
+const USO = `dbreportes-conector ${VERSION}
+
+Enlaza una base de datos privada con DBReportes sin exponerla a internet.
+La conexión la abre esta máquina hacia el servidor; no se abre ningún puerto.
+
+Uso:
+  npx dbreportes-conector --servidor <url> --token <token>
+
+Opciones:
+  --servidor <url>   Dirección de DBReportes (p. ej. https://reportes.empresa.com)
+  --token <token>    Token del conector, emitido al darlo de alta
+  --ca <ruta>        Certificado de la autoridad propia de tu base
+  --sin-verificar    No verificar el certificado de la base (solo en red de confianza)
+  --json             Una línea de JSON por suceso, para consumo automático
+  --version          Mostrar la versión
+  --help             Mostrar esta ayuda
+
+Variables de entorno equivalentes:
+  DBREPORTES_SERVIDOR, DBREPORTES_TOKEN, DBREPORTES_CA,
+  DBREPORTES_VERIFICAR_TLS=off, DBREPORTES_JSON=on
+
+Códigos de salida:
+  0  cierre ordenado
+  2  faltan datos o son inválidos
+  3  no se pudo leer el certificado indicado
+
+Una vez enlazado, en el formulario de conexión de DBReportes se elige este
+conector y se escribe el host tal como lo ve ESTA máquina (por ejemplo
+"localhost" o el nombre de un contenedor).
+`;
+
+function leerArgumentos(argv) {
+  const args = { flags: new Set() };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    switch (a) {
+      case '--servidor':
+      case '--server':
+        args.servidor = argv[++i];
+        break;
+      case '--token':
+        args.token = argv[++i];
+        break;
+      case '--ca':
+        args.ca = argv[++i];
+        break;
+      case '--sin-verificar':
+        args.flags.add('sin-verificar');
+        break;
+      case '--json':
+        args.flags.add('json');
+        break;
+      case '--version':
+      case '-v':
+        args.flags.add('version');
+        break;
+      case '--help':
+      case '-h':
+        args.flags.add('help');
+        break;
+      default:
+        if (a.startsWith('-')) args.desconocida = a;
+        break;
+    }
+  }
+  return args;
+}
+
+const args = leerArgumentos(process.argv.slice(2));
+
+if (args.flags.has('version')) {
+  process.stdout.write(VERSION + '\n');
+  process.exit(0);
+}
+if (args.flags.has('help')) {
+  process.stdout.write(USO);
+  process.exit(0);
+}
+
+const enJSON = args.flags.has('json') || process.env.DBREPORTES_JSON === 'on';
+
+/** Un suceso por línea: legible para una persona, analizable para un programa. */
+function informar(nivel, mensaje, extra = {}) {
+  if (enJSON) {
+    const linea = { hora: new Date().toISOString(), nivel, mensaje, ...extra };
+    process.stdout.write(JSON.stringify(linea) + '\n');
+    return;
+  }
+  const marca = nivel === 'error' ? '✗' : nivel === 'aviso' ? '!' : '·';
+  process.stdout.write(`${marca} ${mensaje}\n`);
+}
+
+function salirCon(codigo, mensaje) {
+  informar('error', mensaje);
+  if (!enJSON) process.stderr.write('\nEjecuta con --help para ver el uso.\n');
+  process.exit(codigo);
+}
+
+if (args.desconocida) salirCon(2, `opción desconocida: ${args.desconocida}`);
+
+const servidor = args.servidor ?? process.env.DBREPORTES_SERVIDOR;
+const token = args.token ?? process.env.DBREPORTES_TOKEN;
+
+if (!servidor) salirCon(2, 'falta --servidor (o la variable DBREPORTES_SERVIDOR)');
+if (!token) salirCon(2, 'falta --token (o la variable DBREPORTES_TOKEN)');
+if (!tokenBienFormado(token)) {
+  salirCon(2, 'el token no tiene el formato esperado: debe empezar por "dbrk_"');
+}
+
+const rutaCA = args.ca ?? process.env.DBREPORTES_CA;
+let caTLS = null;
+if (rutaCA) {
+  try {
+    caTLS = fs.readFileSync(rutaCA);
+  } catch (err) {
+    salirCon(3, `no se pudo leer el certificado ${rutaCA}: ${err.message}`);
+  }
+}
+
+const verificarTLS =
+  !args.flags.has('sin-verificar') && process.env.DBREPORTES_VERIFICAR_TLS !== 'off';
+
+if (!verificarTLS) {
+  informar(
+    'aviso',
+    'la verificación del certificado de la base está desactivada: úsalo solo en una red de confianza',
+  );
+}
+
+const conector = new Conector({ servidor, token, verificarTLS, caTLS });
+
+conector.on('enlazado', ({ servidor: s }) => {
+  informar('info', `enlazado con ${s}`, { evento: 'enlazado', servidor: s });
+  informar(
+    'info',
+    'listo: elige este conector en el formulario de conexión y usa el host tal como lo ve esta máquina',
+    { evento: 'listo' },
+  );
+});
+
+conector.on('desenlazado', ({ codigo, motivo }) => {
+  informar('aviso', `enlace cerrado (${codigo}${motivo ? ': ' + motivo : ''})`, {
+    evento: 'desenlazado',
+    codigo,
+  });
+});
+
+conector.on('reintento', ({ intento, esperaMs }) => {
+  informar('info', `reintentando en ${Math.round(esperaMs / 1000)} s (intento ${intento})`, {
+    evento: 'reintento',
+    intento,
+    esperaMs,
+  });
+});
+
+conector.on('stream', ({ host, puerto, tls }) => {
+  informar('info', `consulta hacia ${host}:${puerto}${tls ? ' (cifrada)' : ''}`, {
+    evento: 'stream',
+    host,
+    puerto,
+    tls,
+  });
+});
+
+conector.on('aviso', (mensaje) => informar('aviso', mensaje, { evento: 'aviso' }));
+
+// Una señal cierra el enlace de forma ordenada: en una máquina virtual esto es
+// lo que ocurre al apagar el servicio, y dejar sockets colgando alargaría el
+// apagado sin motivo.
+for (const senal of ['SIGINT', 'SIGTERM']) {
+  process.on(senal, () => {
+    informar('info', 'cerrando el enlace', { evento: 'cierre' });
+    conector.detener();
+    process.exit(0);
+  });
+}
+
+informar('info', `conector ${VERSION}: abriendo enlace con ${servidor}`, {
+  evento: 'arranque',
+  version: VERSION,
+});
+conector.iniciar();

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "dbreportes-conector",
+  "version": "1.0.0",
+  "description": "Enlace local que permite a DBReportes alcanzar una base de datos privada (localhost, Docker, LAN) sin exponerla a internet.",
+  "license": "MIT",
+  "author": "Jonathan Paredes",
+  "type": "module",
+  "bin": {
+    "dbreportes-conector": "./bin/conector.js"
+  },
+  "main": "./src/conector.js",
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "keywords": [
+    "dbreportes",
+    "postgres",
+    "tunnel",
+    "conector"
+  ]
+}

package/src/conector.js

@@ -0,0 +1,277 @@
+// El conector: abre el enlace hacia DBReportes y, cuando el servidor lo pide,
+// conecta con la base que solo esta máquina alcanza.
+//
+// La conexión la abre siempre este lado. Nunca se escucha en ningún puerto ni
+// se expone la base: hacia fuera se comporta como cualquier programa que habla
+// con un servicio web.
+import net from 'node:net';
+import tls from 'node:tls';
+import { EventEmitter } from 'node:events';
+import { WebSocket } from 'ws';
+
+import {
+  CABECERA_TOKEN,
+  RUTA_ENLACE,
+  TRAMA,
+  codificar,
+  codificarJSON,
+  decodificar,
+  decodificarJSON,
+} from './protocolo.js';
+
+/** Versión que se anuncia en el saludo. */
+export const VERSION = '1.0.0';
+
+/** Espera entre reintentos: arranca corta y crece hasta el tope. */
+const ESPERA_MINIMA_MS = 1_000;
+const ESPERA_MAXIMA_MS = 30_000;
+
+/** Un socket que no llega a abrirse en este plazo se da por perdido. */
+const ESPERA_DE_CONEXION_MS = 15_000;
+
+/** Tope de la trama aceptada, igual que el del servidor. */
+const TOPE_TRAMA = 8 * 1024 * 1024;
+
+/**
+ * Conector enlazado a un servidor de DBReportes.
+ *
+ * Emite: 'enlazado', 'desenlazado', 'reintento', 'stream', 'aviso', 'error'.
+ */
+export class Conector extends EventEmitter {
+  #servidor;
+  #token;
+  #opciones;
+  #ws = null;
+  #streams = new Map();
+  #intento = 0;
+  #reintento = null;
+  #detenido = false;
+
+  /**
+   * @param {object} cfg
+   * @param {string} cfg.servidor  URL del servidor (wss://… o https://…).
+   * @param {string} cfg.token     Token emitido al dar de alta el conector.
+   * @param {boolean} [cfg.verificarTLS=true]  Verificar el certificado de la base.
+   * @param {string}  [cfg.caTLS]   Certificado de una autoridad propia.
+   */
+  constructor({ servidor, token, verificarTLS = true, caTLS = null }) {
+    super();
+    this.#servidor = normalizarServidor(servidor);
+    this.#token = token;
+    this.#opciones = { verificarTLS, caTLS };
+  }
+
+  /** Abre el enlace y lo mantiene, reconectando si se cae. */
+  iniciar() {
+    this.#detenido = false;
+    this.#abrir();
+  }
+
+  /** Cierra el enlace y deja de reintentar. */
+  detener() {
+    this.#detenido = true;
+    if (this.#reintento) {
+      clearTimeout(this.#reintento);
+      this.#reintento = null;
+    }
+    this.#cerrarTodo();
+    if (this.#ws) {
+      try {
+        this.#ws.close(1000, 'cierre solicitado');
+      } catch {
+        /* ya cerrado */
+      }
+      this.#ws = null;
+    }
+  }
+
+  /** Cuántos streams hay abiertos ahora mismo. */
+  get streamsAbiertos() {
+    return this.#streams.size;
+  }
+
+  /** Si el enlace está en pie. */
+  get enlazado() {
+    return this.#ws?.readyState === WebSocket.OPEN;
+  }
+
+  #abrir() {
+    const url = this.#servidor + RUTA_ENLACE;
+    const ws = new WebSocket(url, {
+      headers: { [CABECERA_TOKEN]: this.#token },
+      maxPayload: TOPE_TRAMA,
+      // Sin Origin: lo pone un navegador, y el servidor rechaza los que no
+      // reconoce. Un conector no es una página.
+      followRedirects: false,
+    });
+    this.#ws = ws;
+
+    ws.on('open', () => {
+      this.#intento = 0;
+      ws.send(
+        codificar(TRAMA.SALUDO, 0, codificarJSON({ version: VERSION, motores: ['postgres'] })),
+      );
+      this.emit('enlazado', { servidor: this.#servidor });
+    });
+
+    ws.on('message', (datos) => this.#recibir(datos));
+
+    ws.on('close', (codigo, motivo) => {
+      this.#cerrarTodo();
+      this.#ws = null;
+      this.emit('desenlazado', { codigo, motivo: motivo?.toString() ?? '' });
+      this.#programarReintento();
+    });
+
+    ws.on('error', (err) => {
+      // El cierre viene detrás y es quien programa el reintento; aquí solo se
+      // informa, para que un fallo de red no acabe en excepción sin capturar.
+      this.emit('aviso', err.message);
+    });
+
+    // Un enlace mudo se cierra: el servidor manda ping cada 25 s.
+    ws.on('ping', () => {
+      /* la librería responde el pong sola */
+    });
+  }
+
+  #programarReintento() {
+    if (this.#detenido) return;
+    this.#intento += 1;
+    const espera = Math.min(ESPERA_MINIMA_MS * 2 ** (this.#intento - 1), ESPERA_MAXIMA_MS);
+    this.emit('reintento', { intento: this.#intento, esperaMs: espera });
+    this.#reintento = setTimeout(() => this.#abrir(), espera);
+    this.#reintento.unref?.();
+  }
+
+  #enviar(tipo, stream, cuerpo) {
+    if (this.#ws?.readyState !== WebSocket.OPEN) return;
+    this.#ws.send(codificar(tipo, stream, cuerpo));
+  }
+
+  #recibir(datos) {
+    const trama = decodificar(datos);
+    if (!trama) return;
+
+    switch (trama.tipo) {
+      case TRAMA.ABRIR:
+        this.#abrirStream(trama.stream, decodificarJSON(trama.cuerpo));
+        break;
+
+      case TRAMA.DATOS: {
+        const socket = this.#streams.get(trama.stream);
+        // El cuerpo apunta al búfer del mensaje: se copia porque la escritura
+        // puede quedar en cola.
+        if (socket) socket.write(Buffer.from(trama.cuerpo));
+        break;
+      }
+
+      case TRAMA.CERRAR: {
+        const socket = this.#streams.get(trama.stream);
+        this.#streams.delete(trama.stream);
+        socket?.end();
+        break;
+      }
+
+      default:
+        break;
+    }
+  }
+
+  #abrirStream(id, destino) {
+    if (!destino || typeof destino.host !== 'string' || !Number.isInteger(destino.puerto)) {
+      this.#enviar(TRAMA.FALLO_AL_ABRIR, id, Buffer.from('destino inválido', 'utf8'));
+      return;
+    }
+
+    const { host, puerto, tls: conTLS } = destino;
+    let socket;
+
+    if (conTLS) {
+      // El cifrado contra la base lo termina este extremo, con el nombre real
+      // del host: así el servidor solo ve bytes cifrados que no puede leer, y
+      // el certificado se valida contra quien de verdad responde.
+      socket = tls.connect({
+        host,
+        port: puerto,
+        servername: host,
+        rejectUnauthorized: this.#opciones.verificarTLS,
+        ca: this.#opciones.caTLS ?? undefined,
+      });
+    } else {
+      socket = net.connect({ host, port: puerto });
+    }
+
+    socket.setTimeout(ESPERA_DE_CONEXION_MS);
+    let abierto = false;
+
+    const listoPara = conTLS ? 'secureConnect' : 'connect';
+    socket.once(listoPara, () => {
+      abierto = true;
+      socket.setTimeout(0);
+      socket.setNoDelay(true);
+      this.#streams.set(id, socket);
+      this.#enviar(TRAMA.ABIERTO, id, null);
+      this.emit('stream', { id, host, puerto, tls: Boolean(conTLS) });
+    });
+
+    socket.on('data', (trozo) => this.#enviar(TRAMA.DATOS, id, trozo));
+
+    socket.on('timeout', () => {
+      if (!abierto) socket.destroy(new Error('la base no respondió a tiempo'));
+    });
+
+    socket.on('error', (err) => {
+      if (!abierto) {
+        // El motivo viaja de vuelta para que en la página se vea por qué
+        // falló, en vez de un «no se pudo conectar» sin explicación.
+        this.#enviar(TRAMA.FALLO_AL_ABRIR, id, Buffer.from(motivoLegible(err), 'utf8'));
+      }
+      this.#streams.delete(id);
+      socket.destroy();
+    });
+
+    socket.on('close', () => {
+      if (this.#streams.delete(id)) this.#enviar(TRAMA.CERRAR, id, null);
+    });
+  }
+
+  #cerrarTodo() {
+    for (const socket of this.#streams.values()) socket.destroy();
+    this.#streams.clear();
+  }
+}
+
+/** Deja la URL del servidor lista para abrir el WebSocket. */
+export function normalizarServidor(servidor) {
+  if (typeof servidor !== 'string' || servidor.trim() === '') {
+    throw new Error('falta la dirección del servidor');
+  }
+  let url = servidor.trim().replace(/\/+$/, '');
+  if (url.startsWith('https://')) url = 'wss://' + url.slice('https://'.length);
+  else if (url.startsWith('http://')) url = 'ws://' + url.slice('http://'.length);
+  else if (!url.startsWith('ws://') && !url.startsWith('wss://')) url = 'wss://' + url;
+  return url;
+}
+
+/** Traduce el error del sistema a algo que se entienda en la página. */
+export function motivoLegible(err) {
+  switch (err?.code) {
+    case 'ECONNREFUSED':
+      return 'la base rechazó la conexión: comprueba el puerto y que esté encendida';
+    case 'ENOTFOUND':
+      return 'no se encontró ese host desde la máquina del conector';
+    case 'ETIMEDOUT':
+      return 'la base no respondió a tiempo';
+    case 'EHOSTUNREACH':
+    case 'ENETUNREACH':
+      return 'esa dirección no es alcanzable desde la máquina del conector';
+    case 'CERT_HAS_EXPIRED':
+      return 'el certificado de la base está caducado';
+    case 'DEPTH_ZERO_SELF_SIGNED_CERT':
+    case 'SELF_SIGNED_CERT_IN_CHAIN':
+      return 'el certificado de la base es autofirmado: indica su autoridad con --ca';
+    default:
+      return err?.message ?? 'no se pudo conectar con la base';
+  }
+}

package/src/protocolo.js

@@ -0,0 +1,67 @@
+// Protocolo del enlace. Espeja internal/domain/enlace.go: si cambia uno, cambia
+// el otro, porque los dos extremos leen los mismos bytes.
+
+/** Ruta donde el conector abre su enlace saliente. */
+export const RUTA_ENLACE = '/api/connector/link';
+
+/** El token viaja en cabecera; en la URL quedaría en los registros de proxies. */
+export const CABECERA_TOKEN = 'x-dbreportes-conector';
+
+/** Prefijo de los tokens, para reconocerlos de un vistazo. */
+export const PREFIJO_TOKEN = 'dbrk_';
+
+/** Tipos de trama. */
+export const TRAMA = Object.freeze({
+  ABRIR: 1,
+  ABIERTO: 2,
+  FALLO_AL_ABRIR: 3,
+  DATOS: 4,
+  CERRAR: 5,
+  SALUDO: 6,
+});
+
+/** Un byte de tipo y cuatro de identificador de stream. */
+const CABECERA = 5;
+
+/** Arma el bloque binario listo para enviar. */
+export function codificar(tipo, stream, cuerpo) {
+  const datos = cuerpo ?? Buffer.alloc(0);
+  const salida = Buffer.allocUnsafe(CABECERA + datos.length);
+  salida.writeUInt8(tipo, 0);
+  salida.writeUInt32BE(stream >>> 0, 1);
+  if (datos.length > 0) datos.copy(salida, CABECERA);
+  return salida;
+}
+
+/** Separa un bloque recibido; null si no llega a trama. */
+export function decodificar(datos) {
+  const buf = Buffer.isBuffer(datos) ? datos : Buffer.from(datos);
+  if (buf.length < CABECERA) return null;
+  return {
+    tipo: buf.readUInt8(0),
+    stream: buf.readUInt32BE(1),
+    cuerpo: buf.subarray(CABECERA),
+  };
+}
+
+/** Serializa un cuerpo como JSON en UTF-8. */
+export function codificarJSON(valor) {
+  return Buffer.from(JSON.stringify(valor), 'utf8');
+}
+
+/** Lee un cuerpo JSON; null si viene malformado. */
+export function decodificarJSON(cuerpo) {
+  try {
+    return JSON.parse(Buffer.from(cuerpo).toString('utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Comprueba que un token tenga la forma que emite el servidor. */
+export function tokenBienFormado(token) {
+  if (typeof token !== 'string' || !token.startsWith(PREFIJO_TOKEN)) return false;
+  const cuerpo = token.slice(PREFIJO_TOKEN.length);
+  if (!/^[A-Za-z0-9_-]+$/.test(cuerpo)) return false;
+  return Buffer.from(cuerpo, 'base64url').length === 32;
+}