@saulwade/swl-ses 2.6.1 → 2.8.0

package/scripts/lib/certificacion-loop-state.js

@@ -0,0 +1,421 @@
+'use strict';
+
+/**
+ * Estado verificable del programa de certificación C10.
+ *
+ * `eventos.jsonl` es la autoridad. `LOOP-STATE.md` es una vista derivada. La
+ * confianza en la cadena parte de un hash génesis que el caller protege fuera
+ * del directorio de estado.
+ *
+ * @module scripts/lib/certificacion-loop-state
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { atomicWriteSync } = require('../../hooks/lib/atomic-write');
+
+const ARCHIVO_EVENTOS = 'eventos.jsonl';
+const ARCHIVO_SNAPSHOT = 'LOOP-STATE.md';
+const ESTADO_GENESIS = 'bootstrap';
+const HASH_GENESIS = '0'.repeat(64);
+const HASH_PATTERN = /^[a-f0-9]{64}$/i;
+const CAMPOS_PAYLOAD = [
+  'tipo',
+  'schemaVersion',
+  'secuencia',
+  'prevHash',
+  'timestamp',
+  'actor',
+  'nodo',
+  'estado',
+  'evidencia',
+];
+const CAMPOS_EVENTO = [...CAMPOS_PAYLOAD, 'hash'];
+const CAMPOS_GENESIS = [
+  'schemaVersion',
+  'timestamp',
+  'actor',
+  'nodo',
+  'estado',
+  'evidencia',
+];
+
+function esObjetoPlano(valor) {
+  if (valor === null || typeof valor !== 'object') return false;
+  const prototipo = Object.getPrototypeOf(valor);
+  return prototipo === Object.prototype || prototipo === null;
+}
+
+function validarValorJSON(valor, activos) {
+  if (valor === null || typeof valor === 'string' || typeof valor === 'boolean') return;
+  if (typeof valor === 'number' && Number.isFinite(valor)) return;
+  if (typeof valor !== 'object') throw new TypeError('tipo no serializable');
+  if (!Array.isArray(valor) && !esObjetoPlano(valor)) throw new TypeError('objeto no plano');
+  if (activos.has(valor)) throw new TypeError('referencia cíclica');
+  if (Object.getOwnPropertySymbols(valor).length > 0) throw new TypeError('clave symbol');
+  activos.add(valor);
+  validarContenedorJSON(valor, activos);
+  activos.delete(valor);
+}
+
+function validarContenedorJSON(valor, activos) {
+  if (Array.isArray(valor)) {
+    for (let indice = 0; indice < valor.length; indice += 1) {
+      if (!Object.hasOwn(valor, indice)) throw new TypeError('array disperso');
+      validarValorJSON(valor[indice], activos);
+    }
+    return;
+  }
+  for (const clave of Object.keys(valor)) validarValorJSON(valor[clave], activos);
+}
+
+function validarEvidencia(evidencia) {
+  if (!esObjetoPlano(evidencia)) {
+    throw new TypeError('evidencia no es JSON serializable: debe ser objeto plano');
+  }
+  try {
+    validarValorJSON(evidencia, new WeakSet());
+  } catch (error) {
+    throw new TypeError(`evidencia no es JSON serializable: ${error.message}`);
+  }
+}
+
+function ordenarValorCanonico(valor) {
+  if (Array.isArray(valor)) return valor.map(ordenarValorCanonico);
+  if (!esObjetoPlano(valor)) return valor;
+  const ordenado = Object.create(null);
+  for (const clave of Object.keys(valor).sort()) {
+    ordenado[clave] = ordenarValorCanonico(valor[clave]);
+  }
+  return ordenado;
+}
+
+function construirPayloadCanonico(evento) {
+  return {
+    tipo: evento.tipo,
+    schemaVersion: evento.schemaVersion,
+    secuencia: evento.secuencia,
+    prevHash: evento.prevHash,
+    timestamp: evento.timestamp,
+    actor: evento.actor,
+    nodo: evento.nodo,
+    estado: evento.estado,
+    evidencia: ordenarValorCanonico(evento.evidencia),
+  };
+}
+
+function calcularHashEvento(evento) {
+  validarEvidencia(evento.evidencia);
+  const payload = JSON.stringify(construirPayloadCanonico(evento));
+  return crypto.createHash('sha256').update(payload, 'utf8').digest('hex');
+}
+
+function validarTextoRequerido(objeto, campo) {
+  if (typeof objeto[campo] !== 'string' || objeto[campo].trim() === '') {
+    throw new TypeError(`campo requerido: ${campo}`);
+  }
+}
+
+function validarCamposBase(objeto) {
+  for (const campo of CAMPOS_GENESIS) {
+    if (!Object.hasOwn(objeto, campo) || objeto[campo] === null) {
+      throw new TypeError(`campo requerido: ${campo}`);
+    }
+  }
+  for (const campo of CAMPOS_GENESIS.filter((campo) => campo !== 'evidencia')) {
+    validarTextoRequerido(objeto, campo);
+  }
+  if (Number.isNaN(Date.parse(objeto.timestamp))) {
+    throw new TypeError('campo requerido: timestamp');
+  }
+  validarEvidencia(objeto.evidencia);
+}
+
+function validarGenesis(genesis) {
+  if (!esObjetoPlano(genesis)) throw new TypeError('genesis debe ser un objeto');
+  validarCamposBase(genesis);
+  if (genesis.estado !== ESTADO_GENESIS) {
+    throw new TypeError(`estado génesis debe ser ${ESTADO_GENESIS}`);
+  }
+}
+
+function crearEventoGenesis(genesis) {
+  const payload = construirPayloadCanonico({
+    tipo: 'genesis',
+    schemaVersion: genesis.schemaVersion,
+    secuencia: 0,
+    prevHash: HASH_GENESIS,
+    timestamp: genesis.timestamp,
+    actor: genesis.actor,
+    nodo: genesis.nodo,
+    estado: genesis.estado,
+    evidencia: genesis.evidencia,
+  });
+  return { ...payload, hash: calcularHashEvento(payload) };
+}
+
+function resolverRutas(dir) {
+  if (typeof dir !== 'string' || dir.trim() === '') {
+    throw new TypeError('dir debe ser un string no vacío');
+  }
+  const directorio = path.resolve(dir);
+  return {
+    eventos: path.join(directorio, ARCHIVO_EVENTOS),
+    snapshot: path.join(directorio, ARCHIVO_SNAPSHOT),
+  };
+}
+
+function crearSnapshot(eventos) {
+  const ultimo = eventos[eventos.length - 1];
+  return [
+    '# Estado del loop C10',
+    '',
+    '> Vista derivada. La autoridad es `eventos.jsonl`.',
+    '',
+    `- Secuencia: \`${ultimo.secuencia}\``,
+    `- Último hash: \`${ultimo.hash}\``,
+    `- Eventos: \`${eventos.length}\``,
+    `- Tipo: \`${ultimo.tipo}\``,
+    `- Nodo: \`${ultimo.nodo}\``,
+    `- Estado: \`${ultimo.estado}\``,
+    `- Timestamp: \`${ultimo.timestamp}\``,
+    '',
+  ].join('\n');
+}
+
+function escribirSnapshotGenesis(rutas, evento) {
+  try {
+    atomicWriteSync(rutas.snapshot, crearSnapshot([evento]), 'utf8');
+  } catch (causa) {
+    const error = new Error('snapshot no persistido; usar genesisHash para regenerarlo', {
+      cause: causa,
+    });
+    error.code = 'C10_SNAPSHOT_WRITE_FAILED';
+    error.estadoPersistido = true;
+    error.genesisHash = evento.hash;
+    throw error;
+  }
+}
+
+function inicializarEstado({ dir, genesis } = {}) {
+  const rutas = resolverRutas(dir);
+  // Génesis única por contrato: incluso un replay idéntico debe rechazarse.
+  if (fs.existsSync(rutas.eventos)) {
+    throw new Error('eventos.jsonl ya existe; la génesis es única');
+  }
+  validarGenesis(genesis);
+  const evento = crearEventoGenesis(genesis);
+  const errorEvento = validarEvento(evento, 0, HASH_GENESIS);
+  if (errorEvento) throw new Error(`evento génesis inválido: ${errorEvento}`);
+  atomicWriteSync(rutas.eventos, `${JSON.stringify(evento)}\n`, 'utf8');
+  escribirSnapshotGenesis(rutas, evento);
+  return evento.hash;
+}
+
+function resultadoInvalido(motivo, eventos, ultimoHash = HASH_GENESIS) {
+  return { ok: false, motivo, eventos, ultimoHash };
+}
+
+function normalizarAncla(opciones) {
+  const ancla = opciones && opciones.genesisHashEsperado;
+  if (typeof ancla !== 'string' || !HASH_PATTERN.test(ancla)) return null;
+  return ancla.toLowerCase();
+}
+
+function validarCamposEvento(evento, indice) {
+  if (!esObjetoPlano(evento)) return `evento ${indice} no es un objeto`;
+  const campos = Object.keys(evento).sort();
+  const esperados = [...CAMPOS_EVENTO].sort();
+  if (JSON.stringify(campos) !== JSON.stringify(esperados)) {
+    return `campos inválidos en evento ${indice}`;
+  }
+  try {
+    validarCamposBase(evento);
+  } catch (error) {
+    return `${error.message} en evento ${indice}`;
+  }
+  if (typeof evento.tipo !== 'string' || evento.tipo.trim() === '') {
+    return `tipo inválido en evento ${indice}`;
+  }
+  return null;
+}
+
+function validarEvento(evento, indice, hashAnterior) {
+  const errorCampos = validarCamposEvento(evento, indice);
+  if (errorCampos) return errorCampos;
+  if (evento.secuencia !== indice) return `secuencia inválida en evento ${indice}`;
+  if (evento.prevHash !== hashAnterior) return `prevHash inválido en evento ${indice}`;
+  if (indice === 0 && evento.tipo !== 'genesis') return 'el evento 0 no es genesis';
+  if (indice === 0 && evento.estado !== ESTADO_GENESIS) return 'estado génesis inválido';
+  if (indice > 0 && evento.tipo === 'genesis') return `genesis duplicada en evento ${indice}`;
+  if (!HASH_PATTERN.test(evento.hash)) return `hash inválido en evento ${indice}`;
+  if (calcularHashEvento(evento) !== evento.hash) return `hash inválido en evento ${indice}`;
+  return null;
+}
+
+function separarLineas(contenido) {
+  const lineas = contenido.split(/\r?\n/);
+  if (lineas.at(-1) === '') lineas.pop();
+  return lineas;
+}
+
+function verificarCadenaEventos(dir, genesisHashEsperado) {
+  const rutas = resolverRutas(dir);
+  if (!fs.existsSync(rutas.eventos)) {
+    return resultadoInvalido('eventos.jsonl no existe', 0);
+  }
+  const lineas = separarLineas(fs.readFileSync(rutas.eventos, 'utf8'));
+  if (lineas.length === 0) return resultadoInvalido('eventos.jsonl está vacío', 0);
+  return procesarLineas(lineas, genesisHashEsperado);
+}
+
+function procesarLineas(lineas, genesisHashEsperado) {
+  const eventos = [];
+  let hashAnterior = HASH_GENESIS;
+  for (let indice = 0; indice < lineas.length; indice += 1) {
+    const parseado = procesarLinea(lineas, indice, hashAnterior);
+    if (!parseado.ok) return parseado;
+    if (indice === 0 && parseado.evento.hash !== genesisHashEsperado) {
+      return resultadoInvalido('ancla genesis no coincide', lineas.length, hashAnterior);
+    }
+    eventos.push(parseado.evento);
+    hashAnterior = parseado.evento.hash;
+  }
+  return crearResultadoCadena(eventos, hashAnterior);
+}
+
+function procesarLinea(lineas, indice, hashAnterior) {
+  if (lineas[indice].trim() === '') {
+    return resultadoInvalido(`línea vacía en evento ${indice}`, lineas.length, hashAnterior);
+  }
+  return parsearLinea(lineas[indice], indice, lineas.length, hashAnterior);
+}
+
+function crearResultadoCadena(eventos, ultimoHash) {
+  return {
+    ok: true,
+    motivo: 'ok',
+    eventos: eventos.length,
+    ultimoHash,
+    lista: eventos,
+  };
+}
+
+function parsearLinea(linea, indice, total, hashAnterior) {
+  let evento;
+  try {
+    evento = JSON.parse(linea);
+  } catch {
+    return resultadoInvalido(`JSON inválido en evento ${indice}`, total, hashAnterior);
+  }
+  const motivo = validarEvento(evento, indice, hashAnterior);
+  if (motivo) return resultadoInvalido(motivo, total, hashAnterior);
+  return { ok: true, evento };
+}
+
+function verificarEstado(dir, opciones = {}) {
+  const ancla = normalizarAncla(opciones);
+  if (!ancla) return resultadoInvalido('genesisHashEsperado inválido', 0);
+  const cadena = verificarCadenaEventos(dir, ancla);
+  if (!cadena.ok) return cadena;
+  return verificarSnapshot(dir, cadena);
+}
+
+function verificarSnapshot(dir, cadena) {
+  const rutas = resolverRutas(dir);
+  if (!fs.existsSync(rutas.snapshot)) {
+    return resultadoInvalido('LOOP-STATE.md no existe', cadena.eventos, cadena.ultimoHash);
+  }
+  const esperado = crearSnapshot(cadena.lista);
+  const actual = fs.readFileSync(rutas.snapshot, 'utf8');
+  if (actual !== esperado) {
+    return resultadoInvalido('snapshot divergente', cadena.eventos, cadena.ultimoHash);
+  }
+  return { ok: true, motivo: 'ok', eventos: cadena.eventos, ultimoHash: cadena.ultimoHash };
+}
+
+function regenerarSnapshot(dir, opciones = {}) {
+  const ancla = normalizarAncla(opciones);
+  if (!ancla) throw new Error('genesisHashEsperado inválido');
+  const cadena = verificarCadenaEventos(dir, ancla);
+  if (!cadena.ok) throw new Error(`cadena inválida: ${cadena.motivo}`);
+  const contenido = crearSnapshot(cadena.lista);
+  atomicWriteSync(resolverRutas(dir).snapshot, contenido, 'utf8');
+  return contenido;
+}
+
+const CAMPOS_EVENTO_NUEVO = ['tipo', ...CAMPOS_GENESIS];
+
+function normalizarPrevHash(opciones) {
+  const prevHash = opciones && opciones.prevHashEsperado;
+  if (typeof prevHash !== 'string' || !HASH_PATTERN.test(prevHash)) return null;
+  return prevHash.toLowerCase();
+}
+
+function validarCamposEventoNuevo(evento) {
+  if (!esObjetoPlano(evento)) throw new TypeError('evento debe ser un objeto');
+  const claves = Object.keys(evento);
+  const claveInesperada = claves.find((clave) => !CAMPOS_EVENTO_NUEVO.includes(clave));
+  if (claveInesperada) throw new TypeError(`clave inesperada: ${claveInesperada}`);
+  validarCamposBase(evento);
+  validarTextoRequerido(evento, 'tipo');
+}
+
+function verificarCadenaYSnapshotVigentes(dir, ancla, prevHashEsperado) {
+  const cadena = verificarCadenaEventos(dir, ancla);
+  if (!cadena.ok) throw new Error(`cadena inválida: ${cadena.motivo}`);
+  if (cadena.ultimoHash !== prevHashEsperado) {
+    throw new Error('prevHashEsperado no coincide con el tip actual; releer antes de reintentar');
+  }
+  const snapshot = verificarSnapshot(dir, cadena);
+  if (!snapshot.ok) throw new Error(`snapshot inválido: ${snapshot.motivo}`);
+  return cadena;
+}
+
+function construirEventoEncadenado(evento, cadena) {
+  const payload = construirPayloadCanonico({
+    tipo: evento.tipo,
+    schemaVersion: evento.schemaVersion,
+    secuencia: cadena.eventos,
+    prevHash: cadena.ultimoHash,
+    timestamp: evento.timestamp,
+    actor: evento.actor,
+    nodo: evento.nodo,
+    estado: evento.estado,
+    evidencia: evento.evidencia,
+  });
+  const eventoFinal = { ...payload, hash: calcularHashEvento(payload) };
+  const errorEvento = validarEvento(eventoFinal, cadena.eventos, cadena.ultimoHash);
+  if (errorEvento) throw new Error(`evento inválido: ${errorEvento}`);
+  return eventoFinal;
+}
+
+function persistirEventoAnexado(dir, eventoFinal, eventosPrevios) {
+  const rutas = resolverRutas(dir);
+  const contenidoActual = fs.readFileSync(rutas.eventos, 'utf8');
+  const nuevoContenido = `${contenidoActual}${JSON.stringify(eventoFinal)}\n`;
+  atomicWriteSync(rutas.eventos, nuevoContenido, 'utf8');
+  atomicWriteSync(rutas.snapshot, crearSnapshot([...eventosPrevios, eventoFinal]), 'utf8');
+}
+
+function agregarEvento(dir, evento, opciones = {}) {
+  const ancla = normalizarAncla(opciones);
+  if (!ancla) throw new Error('genesisHashEsperado inválido');
+  const prevHashEsperado = normalizarPrevHash(opciones);
+  if (!prevHashEsperado) throw new Error('prevHashEsperado inválido');
+  validarCamposEventoNuevo(evento);
+  const cadena = verificarCadenaYSnapshotVigentes(dir, ancla, prevHashEsperado);
+  const eventoFinal = construirEventoEncadenado(evento, cadena);
+  persistirEventoAnexado(dir, eventoFinal, cadena.lista);
+  return eventoFinal.hash;
+}
+
+module.exports = {
+  agregarEvento,
+  calcularHashEvento,
+  inicializarEstado,
+  regenerarSnapshot,
+  verificarEstado,
+};