@7ots/cli 0.1.0

package/server/platform/auth.mjs

@@ -0,0 +1,290 @@
+/**
+ * Acceso a la plataforma: enlace por correo y "Entrar con notlogin" (OIDC + PKCE).
+ *
+ *   POST /auth/email          { email }  → manda el enlace (buzón de apumail de la plataforma)
+ *   GET  /auth/email?token=…  página con el botón "Entrar" (los antivirus del correo abren
+ *                              los enlaces: un GET nunca gasta el enlace)
+ *   POST /auth/email/confirm  token=…    gasta el enlace, abre sesión y lleva a /app/
+ *   GET  /auth/notlogin                   → notlogin.com/authorize
+ *   GET  /auth/notlogin/callback          ?code&state → sesión y /app/
+ *   POST /auth/logout
+ *
+ * Variables:
+ *   PLATFORM_URL             origen público (https://7ots.com); los enlaces nunca salen de la cabecera Host
+ *   PLATFORM_MAIL_INBOX      buzón de apumail que manda los enlaces · PLATFORM_MAIL_TOKEN su token
+ *                            (sin buzón y fuera de producción, el enlace sale por consola)
+ *   NOTLOGIN_CLIENT_ID       slug de 7ots como vendor de notlogin (también el `aud` del id_token)
+ *   NOTLOGIN_CLIENT_SECRET   opcional · NOTLOGIN_URL (defecto https://notlogin.com)
+ *
+ * Sesión: cookie `ots_session` (HttpOnly, SameSite=Lax, 30 días); en la base de datos solo su hash.
+ */
+
+import { createHash, createPublicKey, randomBytes, verify as cryptoVerify } from 'node:crypto';
+import { reqT, teamT } from '../i18n.mjs';
+import { signValue, unsignValue } from './crypto.mjs';
+import { SESSION_TTL, consumeLoginToken, createLoginToken, createSession, deleteSession, recentLoginTokens, sessionAccount, upsertAccount } from './store.mjs';
+
+const penv = process.env;
+export const SESSION_COOKIE = 'ots_session';
+const OIDC_COOKIE = 'ots_oidc';
+const OIDC_TTL = 10 * 60_000;
+const EMAIL_RE = /^[^\s@]{1,64}@[^\s@]+\.[^\s@]{2,}$/;
+
+const notloginUrl = () => (penv.NOTLOGIN_URL || 'https://notlogin.com').replace(/\/+$/, '');
+export const notloginConfigured = () => !!penv.NOTLOGIN_CLIENT_ID;
+export const mailConfigured = () => !!(penv.PLATFORM_MAIL_INBOX && penv.PLATFORM_MAIL_TOKEN);
+const production = () => penv.NODE_ENV === 'production';
+
+export function parseCookies(h = '') {
+  const out = {};
+  for (const part of String(h).split(';')) {
+    const i = part.indexOf('=');
+    if (i > 0) out[part.slice(0, i).trim()] = decodeURIComponent(part.slice(i + 1).trim());
+  }
+  return out;
+}
+
+/** Cuenta de la sesión de esta petición (o null). */
+export function currentAccount(req) {
+  return sessionAccount(parseCookies(req.headers.cookie)[SESSION_COOKIE]);
+}
+
+/**
+ * @param {{ send: Function, readJson: Function, originOf: (req) => string, clientIp: (req) => string }} deps
+ */
+export function createAuth({ send, readJson, originOf, clientIp }) {
+  const base = (req) => (penv.PLATFORM_URL || originOf(req)).replace(/\/+$/, '');
+  const secure = (req) => base(req).startsWith('https:');
+  const ipHits = new Map();
+
+  function cookie(req, name, value, { path = '/', maxAge }) {
+    return `${name}=${encodeURIComponent(value)}; Path=${path}; HttpOnly; SameSite=Lax; Max-Age=${Math.floor(maxAge / 1000)}${secure(req) ? '; Secure' : ''}`;
+  }
+
+  function startSession(req, res, account, via) {
+    const raw = createSession(account.id, via);
+    res.setHeader('Set-Cookie', [cookie(req, SESSION_COOKIE, raw, { maxAge: SESSION_TTL }), cookie(req, OIDC_COOKIE, '', { path: '/auth/notlogin', maxAge: 0 })]);
+  }
+
+  function redirect(res, to) {
+    res.writeHead(303, { Location: to, 'Cache-Control': 'no-store' });
+    res.end();
+  }
+
+  /** Vuelve a la pantalla de acceso con un aviso (clave i18n que traduce el dashboard). */
+  const fail = (res, key) => redirect(res, `/app/?error=${encodeURIComponent(key)}`);
+
+  function tooMany(req) {
+    const ip = clientIp(req);
+    const now = Date.now();
+    const recent = (ipHits.get(ip) || []).filter((t) => now - t < 3600_000);
+    if (recent.length >= 10) return true;
+    recent.push(now);
+    ipHits.set(ip, recent);
+    if (ipHits.size > 5000) ipHits.clear();
+    return false;
+  }
+
+  async function sendLink(req, email) {
+    const url = `${base(req)}/auth/email?token=${createLoginToken(email)}`;
+    const t = reqT(req); // el correo, en el idioma de quien lo pide
+    if (!mailConfigured()) {
+      if (production()) throw Object.assign(new Error('mail'), { status: 501, key: 'platform.api.mailNotConfigured' });
+      console.log(`[7ots] ${teamT()('platform.log.magicLink', { email, url })}`);
+      return;
+    }
+    const api = (penv.APUMAIL_API || 'https://api.apumail.com').replace(/\/+$/, '');
+    const r = await fetch(`${api}/api/v1/inbox/${encodeURIComponent(penv.PLATFORM_MAIL_INBOX.toLowerCase())}/send`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${penv.PLATFORM_MAIL_TOKEN}` },
+      body: JSON.stringify({ to: email, subject: t('platform.mail.subject'), text: t('platform.mail.body', { url }) }),
+      signal: AbortSignal.timeout(15000),
+    }).catch(() => null);
+    if (!r?.ok) {
+      console.error('[7ots] plataforma: no se pudo mandar el enlace', r?.status ?? 'sin respuesta');
+      throw Object.assign(new Error('mail'), { status: 502, key: 'platform.api.mailFailed' });
+    }
+  }
+
+  // ── notlogin (OIDC) ──
+
+  const redirectUri = (req) => `${base(req)}/auth/notlogin/callback`;
+
+  function notloginStart(req, res) {
+    if (!notloginConfigured()) return fail(res, 'platform.api.notloginNotConfigured');
+    const verifier = randomBytes(32).toString('base64url');
+    const st = { s: randomBytes(16).toString('base64url'), v: verifier, n: randomBytes(16).toString('base64url'), e: Date.now() + OIDC_TTL };
+    const params = new URLSearchParams({
+      vendor: penv.NOTLOGIN_CLIENT_ID,
+      client_id: penv.NOTLOGIN_CLIENT_ID,
+      redirect_uri: redirectUri(req),
+      response_type: 'code',
+      scope: 'openid profile email',
+      state: st.s,
+      nonce: st.n,
+      code_challenge: createHash('sha256').update(verifier).digest('base64url'),
+      code_challenge_method: 'S256',
+    });
+    res.setHeader('Set-Cookie', cookie(req, OIDC_COOKIE, signValue(Buffer.from(JSON.stringify(st)).toString('base64url')), { path: '/auth/notlogin', maxAge: OIDC_TTL }));
+    redirect(res, `${notloginUrl()}/authorize?${params}`);
+  }
+
+  async function notloginCallback(req, res, url) {
+    const raw = unsignValue(parseCookies(req.headers.cookie)[OIDC_COOKIE]);
+    let st = null;
+    try {
+      st = raw && JSON.parse(Buffer.from(raw, 'base64url').toString('utf8'));
+    } catch {
+      /* cookie rota */
+    }
+    const code = url.searchParams.get('code');
+    if (!st || st.e < Date.now() || !code || url.searchParams.get('state') !== st.s) return fail(res, 'platform.api.notloginFailed');
+    try {
+      const body = new URLSearchParams({ grant_type: 'authorization_code', code, code_verifier: st.v, redirect_uri: redirectUri(req), client_id: penv.NOTLOGIN_CLIENT_ID });
+      if (penv.NOTLOGIN_CLIENT_SECRET) body.set('client_secret', penv.NOTLOGIN_CLIENT_SECRET);
+      const r = await fetch(`${notloginUrl()}/api/oauth/token`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+        body,
+        redirect: 'manual',
+        signal: AbortSignal.timeout(8000),
+      });
+      const j = await r.json().catch(() => ({}));
+      if (!r.ok || !j.id_token) throw new Error(`token ${r.status}`);
+      const claims = await verifyIdToken(j.id_token, st.n);
+      const account = upsertAccount({ notloginSub: claims.sub, email: claims.email_verified ? claims.email : null });
+      startSession(req, res, account, 'notlogin');
+      redirect(res, '/app/');
+    } catch (e) {
+      console.warn('[7ots] notlogin:', e.message);
+      fail(res, 'platform.api.notloginFailed');
+    }
+  }
+
+  /** @returns {Promise<boolean>} */
+  return async function handle(req, res, url) {
+    const p = url.pathname;
+    if (!p.startsWith('/auth/')) return false;
+    const t = reqT(req);
+    const write = req.method === 'POST';
+    // Formularios propios: mismo origen (la cookie es Lax, pero así no hay CSRF de login).
+    const origin = req.headers.origin;
+    if (write && origin && origin !== base(req) && origin !== originOf(req)) {
+      send(res, 403, { error: t('server.admin.sameOrigin') });
+      return true;
+    }
+
+    if (p === '/auth/providers' && req.method === 'GET') {
+      send(res, 200, { email: mailConfigured() || !production(), notlogin: notloginConfigured() });
+      return true;
+    }
+
+    if (p === '/auth/email' && write) {
+      const { email } = await readJson(req, 4096);
+      const e = String(email || '').trim().toLowerCase();
+      if (!EMAIL_RE.test(e) || e.length > 200) return send(res, 400, { error: t('platform.api.badEmail') }), true;
+      if (tooMany(req) || recentLoginTokens(e) >= 5) return send(res, 429, { error: t('platform.api.tooManyLinks') }), true;
+      try {
+        await sendLink(req, e);
+      } catch (err) {
+        send(res, err.status || 500, { error: t(err.key || 'server.http.internal') });
+        return true;
+      }
+      send(res, 200, { ok: true });
+      return true;
+    }
+
+    if (p === '/auth/email' && req.method === 'GET') {
+      const token = String(url.searchParams.get('token') || '').replace(/[^A-Za-z0-9_-]/g, '');
+      // same-origin (no no-referrer): con no-referrer el navegador envía el formulario con `Origin: null`.
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store', 'Referrer-Policy': 'same-origin', 'Content-Security-Policy': "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'" });
+      res.end(confirmPage(t, token));
+      return true;
+    }
+
+    if (p === '/auth/email/confirm' && write) {
+      const form = await readForm(req);
+      const email = consumeLoginToken(form.get('token'));
+      if (!email) return fail(res, 'platform.api.linkInvalid'), true;
+      startSession(req, res, upsertAccount({ email }), 'email');
+      redirect(res, '/app/');
+      return true;
+    }
+
+    if (p === '/auth/notlogin' && req.method === 'GET') return notloginStart(req, res), true;
+    if (p === '/auth/notlogin/callback' && req.method === 'GET') return await notloginCallback(req, res, url), true;
+
+    if (p === '/auth/logout' && write) {
+      deleteSession(parseCookies(req.headers.cookie)[SESSION_COOKIE]);
+      res.setHeader('Set-Cookie', cookie(req, SESSION_COOKIE, '', { maxAge: 0 }));
+      send(res, 200, { ok: true });
+      return true;
+    }
+
+    send(res, 404, { error: t('server.http.notFound') });
+    return true;
+  };
+}
+
+async function readForm(req) {
+  let size = 0;
+  const chunks = [];
+  for await (const c of req) {
+    size += c.length;
+    if (size > 4096) break;
+    chunks.push(c);
+  }
+  return new URLSearchParams(Buffer.concat(chunks).toString('utf8'));
+}
+
+function confirmPage(t, token) {
+  const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>7ots.com</title>
+<style>body{margin:0;min-height:100vh;display:grid;place-items:center;font:16px/1.5 system-ui,sans-serif;background:#f8f7fc;color:#16152a}
+main{text-align:center;padding:32px}button{font:600 16px system-ui,sans-serif;background:#5b47f0;color:#fff;border:0;border-radius:8px;padding:12px 28px;cursor:pointer}
+@media (prefers-color-scheme:dark){body{background:#0b0a14;color:#f0eff7}button{background:#8b7cff;color:#0b0a14}}</style></head>
+<body><main><p>${esc(t('platform.mail.confirm'))}</p><form method="post" action="/auth/email/confirm"><input type="hidden" name="token" value="${esc(token)}"><button type="submit">${esc(t('platform.mail.button'))}</button></form></main></body></html>`;
+}
+
+// ───────────────────────────── id_token de notlogin (EdDSA) ─────────────────────────────
+
+let jwks = null; // { at, keys: Map<kid, KeyObject> }
+
+async function loadJwks(force) {
+  if (!force && jwks && Date.now() - jwks.at < 5 * 60_000) return jwks.keys;
+  const r = await fetch(`${notloginUrl()}/.well-known/jwks.json`, { signal: AbortSignal.timeout(8000) });
+  if (!r.ok) throw new Error(`jwks ${r.status}`);
+  const keys = new Map();
+  for (const k of (await r.json()).keys || []) {
+    try {
+      keys.set(k.kid, createPublicKey({ key: k, format: 'jwk' }));
+    } catch {
+      /* clave rara: se ignora */
+    }
+  }
+  jwks = { at: Date.now(), keys };
+  return keys;
+}
+
+const part = (s) => JSON.parse(Buffer.from(s, 'base64url').toString('utf8'));
+
+async function verifyIdToken(idToken, nonce) {
+  const [h, p, s] = String(idToken).split('.');
+  if (!s) throw new Error('id_token mal formado');
+  const header = part(h);
+  if (header.alg !== 'EdDSA') throw new Error('alg inesperado');
+  let keys = await loadJwks(false);
+  let key = keys.get(header.kid);
+  if (!key) key = (keys = await loadJwks(true)).get(header.kid);
+  if (!key) throw new Error('clave de firma desconocida');
+  if (!cryptoVerify(null, Buffer.from(`${h}.${p}`), key, Buffer.from(s, 'base64url'))) throw new Error('firma inválida');
+  const c = part(p);
+  const now = Math.floor(Date.now() / 1000);
+  if (c.iss !== notloginUrl()) throw new Error('iss');
+  if (c.aud !== penv.NOTLOGIN_CLIENT_ID && !(Array.isArray(c.aud) && c.aud.includes(penv.NOTLOGIN_CLIENT_ID))) throw new Error('aud');
+  if (c.token_use && c.token_use !== 'id') throw new Error('token_use');
+  if (!(c.exp + 60 > now)) throw new Error('caducado');
+  if (c.nonce !== nonce) throw new Error('nonce');
+  if (typeof c.sub !== 'string' || !c.sub) throw new Error('sin sub');
+  return c;
+}

package/server/platform/crypto.mjs

@@ -0,0 +1,80 @@
+/**
+ * Criptografía de la plataforma. Todo sale de PLATFORM_SECRET (≥ 32 caracteres, aleatorio):
+ *   - las claves de cada ots se guardan cifradas (AES-256-GCM),
+ *   - las cookies temporales del login (estado de OIDC) van firmadas (HMAC-SHA256),
+ *   - los tokens (sesión, enlace por email) se guardan como hash, nunca en claro.
+ * Cambiar PLATFORM_SECRET invalida las claves guardadas: los usuarios tendrían que volver a ponerlas.
+ */
+
+import { createCipheriv, createDecipheriv, createHash, createHmac, hkdfSync, randomBytes, timingSafeEqual } from 'node:crypto';
+
+let keys = null;
+
+function derive() {
+  if (keys) return keys;
+  const secret = process.env.PLATFORM_SECRET || '';
+  if (secret.length < 32) throw new Error('PLATFORM_SECRET debe tener al menos 32 caracteres (la plataforma no arranca sin él)');
+  const k = (info) => Buffer.from(hkdfSync('sha256', secret, '7ots-platform', info, 32));
+  keys = { box: k('secrets-v1'), mac: k('cookies-v1') };
+  return keys;
+}
+
+/** Comprueba PLATFORM_SECRET al arrancar (lanza si falta). */
+export function assertSecret() {
+  derive();
+}
+
+/** Cifra un objeto → "v1.<iv>.<tag>.<datos>" (base64url). */
+export function seal(obj) {
+  const iv = randomBytes(12);
+  const c = createCipheriv('aes-256-gcm', derive().box, iv);
+  const data = Buffer.concat([c.update(JSON.stringify(obj ?? {}), 'utf8'), c.final()]);
+  return ['v1', iv.toString('base64url'), c.getAuthTag().toString('base64url'), data.toString('base64url')].join('.');
+}
+
+/** Descifra lo de seal(). Vacío o inválido → {} (y avisa: nunca rompe el ots). */
+export function open(text) {
+  if (!text) return {};
+  try {
+    const [v, iv, tag, data] = String(text).split('.');
+    if (v !== 'v1') return {};
+    const d = createDecipheriv('aes-256-gcm', derive().box, Buffer.from(iv, 'base64url'));
+    d.setAuthTag(Buffer.from(tag, 'base64url'));
+    return JSON.parse(Buffer.concat([d.update(Buffer.from(data, 'base64url')), d.final()]).toString('utf8'));
+  } catch {
+    console.warn('[7ots] plataforma: no se pudieron descifrar unas claves (¿cambió PLATFORM_SECRET?)');
+    return {};
+  }
+}
+
+/** Firma un valor corto para una cookie: "<valor>.<mac>". */
+export function signValue(value) {
+  return `${value}.${createHmac('sha256', derive().mac).update(value).digest('base64url')}`;
+}
+
+/** Devuelve el valor si la firma es buena; si no, null. */
+export function unsignValue(signed) {
+  const s = String(signed || '');
+  const i = s.lastIndexOf('.');
+  if (i < 1) return null;
+  const value = s.slice(0, i);
+  return safeEqual(s.slice(i + 1), createHmac('sha256', derive().mac).update(value).digest('base64url')) ? value : null;
+}
+
+export const token = (bytes = 32) => randomBytes(bytes).toString('base64url');
+export const sha256 = (s) => createHash('sha256').update(String(s)).digest('base64url');
+
+/** Id corto y legible para URLs: prefijo + 16 caracteres [a-z0-9]. */
+export function newId(prefix) {
+  const alphabet = 'abcdefghijklmnopqrstuvwxyz0123456789';
+  const b = randomBytes(16);
+  let out = '';
+  for (const x of b) out += alphabet[x % 36];
+  return `${prefix}_${out}`;
+}
+
+export function safeEqual(a, b) {
+  const x = Buffer.from(String(a));
+  const y = Buffer.from(String(b));
+  return x.length === y.length && timingSafeEqual(x, y);
+}

package/server/platform/db.mjs

@@ -0,0 +1,130 @@
+/**
+ * Base de datos de la plataforma 7ots.com (solo con PLATFORM=true).
+ *
+ * SQLite de Node (node:sqlite): sin dependencias ni servidor aparte. Un fichero,
+ * PLATFORM_DB (defecto data/platform.db), en modo WAL.
+ *
+ *   accounts       cuentas (email y/o notlogin_sub)
+ *   sessions       sesiones del dashboard (se guarda el hash del token, nunca el token)
+ *   login_tokens   enlaces de acceso por email (hash, 15 min, un solo uso)
+ *   ots            los agentes: identidad, widget y ajustes en JSON; claves cifradas aparte
+ *   conversations  una por visitante y sesión del widget (o contacto de un canal)
+ *   messages       lo que dijo cada uno (texto, sin el `raw` del proveedor)
+ *   usage          contadores por ots, mes y tipo
+ */
+
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS accounts (
+  id TEXT PRIMARY KEY,
+  email TEXT UNIQUE,
+  notlogin_sub TEXT UNIQUE,
+  name TEXT NOT NULL DEFAULT '',
+  plan TEXT NOT NULL DEFAULT 'free',
+  created_at INTEGER NOT NULL,
+  last_login_at INTEGER
+);
+CREATE TABLE IF NOT EXISTS sessions (
+  id TEXT PRIMARY KEY,
+  account_id TEXT NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,
+  created_at INTEGER NOT NULL,
+  expires_at INTEGER NOT NULL,
+  via TEXT NOT NULL DEFAULT ''
+);
+CREATE INDEX IF NOT EXISTS sessions_account ON sessions(account_id);
+CREATE TABLE IF NOT EXISTS login_tokens (
+  hash TEXT PRIMARY KEY,
+  email TEXT NOT NULL,
+  expires_at INTEGER NOT NULL,
+  used_at INTEGER
+);
+CREATE TABLE IF NOT EXISTS ots (
+  id TEXT PRIMARY KEY,
+  account_id TEXT NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'on',
+  domains TEXT NOT NULL DEFAULT '[]',
+  identity TEXT NOT NULL DEFAULT '{}',
+  widget TEXT NOT NULL DEFAULT '{}',
+  settings TEXT NOT NULL DEFAULT '{}',
+  secrets TEXT NOT NULL DEFAULT '',
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS ots_account ON ots(account_id);
+CREATE TABLE IF NOT EXISTS conversations (
+  id TEXT PRIMARY KEY,
+  ots_id TEXT NOT NULL REFERENCES ots(id) ON DELETE CASCADE,
+  channel TEXT NOT NULL DEFAULT 'web',
+  visitor TEXT NOT NULL DEFAULT '',
+  page TEXT NOT NULL DEFAULT '',
+  title TEXT NOT NULL DEFAULT '',
+  messages INTEGER NOT NULL DEFAULT 0,
+  started_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS conversations_ots ON conversations(ots_id, updated_at DESC);
+CREATE TABLE IF NOT EXISTS messages (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  conversation_id TEXT NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
+  role TEXT NOT NULL,
+  content TEXT NOT NULL,
+  at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS messages_conversation ON messages(conversation_id, id);
+CREATE TABLE IF NOT EXISTS usage (
+  account_id TEXT NOT NULL,
+  ots_id TEXT NOT NULL,
+  month TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  count INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (ots_id, month, kind)
+);
+CREATE INDEX IF NOT EXISTS usage_account ON usage(account_id, month);
+`;
+
+let db = null;
+
+/** Abre (y crea si hace falta) la base de datos. Idempotente. */
+export function openDb(path = process.env.PLATFORM_DB) {
+  if (db) return db;
+  const file = path === ':memory:' ? path : resolve(ROOT, path || join('data', 'platform.db'));
+  if (file !== ':memory:') mkdirSync(dirname(file), { recursive: true });
+  db = new DatabaseSync(file);
+  db.exec('PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 3000;');
+  db.exec(SCHEMA);
+  return db;
+}
+
+export function getDb() {
+  return db || openDb();
+}
+
+/** Cierra la base de datos (tests). */
+export function closeDb() {
+  db?.close();
+  db = null;
+}
+
+/** Varias escrituras como una sola. */
+export function tx(fn) {
+  const d = getDb();
+  d.exec('BEGIN');
+  try {
+    const out = fn(d);
+    d.exec('COMMIT');
+    return out;
+  } catch (e) {
+    d.exec('ROLLBACK');
+    throw e;
+  }
+}
+
+/** Mes en curso (UTC) para los contadores: "2026-09". */
+export const monthOf = (t = Date.now()) => new Date(t).toISOString().slice(0, 7);