@saulwade/swl-ses 2.6.1 → 2.8.0

package/scripts/lib/signed-envelope.js

@@ -0,0 +1,545 @@
+'use strict';
+
+/** Verificación Ed25519 sobre JCS/I-JSON con trust monotónico branded. */
+
+const crypto = require('node:crypto');
+const util = require('node:util');
+
+const { parsearJSONSeguro } = require('./frontmatter-canonico');
+
+const SCHEMA_VERSION = '1.0.0';
+const TRUST_BOOTSTRAP = 'trust_bootstrap';
+const USAGES = new Set(['principal', 'policy_context', 'approval', 'evidence', 'integrity']);
+const SHA256 = /^[a-f0-9]{64}$/u;
+const IDENTIFICADOR = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+const BASE64URL = /^[A-Za-z0-9_-]{86}$/u;
+const CLAVES_ENVELOPE = ['schemaVersion', 'type', 'keyId', 'claims', 'signature'];
+const CLAVES_UNSIGNED = ['schemaVersion', 'type', 'keyId', 'claims'];
+const CLAVES_TRUST = [
+  'schemaVersion', 'trustEpoch', 'previousTrustDigest', 'trustDigest', 'issuedAt', 'entries',
+];
+const CLAVES_ENTRY = [
+  'keyId', 'usage', 'issuer', 'subject', 'scopes', 'notBefore', 'notAfter', 'revoked',
+  'publicKey',
+];
+const ROOT_VERIFIERS = new WeakSet();
+const ROOT_META = new WeakMap();
+const TRUST_CONTEXTS = new WeakSet();
+const TRUST_META = new WeakMap();
+const VERIFIED_ENVELOPES = new WeakSet();
+const ENVELOPE_META = new WeakMap();
+const ROOT_VERIFIERS_BY_DIGEST = new Map();
+const TYPED_ARRAY_PROTOTYPE = Object.getPrototypeOf(Uint8Array.prototype);
+const GET_ARRAY_BUFFER = Object.getOwnPropertyDescriptor(TYPED_ARRAY_PROTOTYPE, 'buffer').get;
+const GET_BYTE_OFFSET = Object.getOwnPropertyDescriptor(TYPED_ARRAY_PROTOTYPE, 'byteOffset').get;
+const GET_BYTE_LENGTH = Object.getOwnPropertyDescriptor(TYPED_ARRAY_PROTOTYPE, 'byteLength').get;
+
+function crearError(codigo, mensaje) {
+  const error = new Error(mensaje);
+  error.codigo = codigo;
+  return error;
+}
+
+function fallar(codigo, mensaje) {
+  throw crearError(codigo, mensaje);
+}
+
+function validarClavesExactas(valor, claves, etiqueta) {
+  const actuales = Object.keys(valor).sort();
+  const esperadas = [...claves].sort();
+  if (JSON.stringify(actuales) !== JSON.stringify(esperadas)) {
+    fallar('CONTRACT_INVALID', `${etiqueta} con propiedades inválidas`);
+  }
+}
+
+function validarMaterializado(valor, etiqueta) {
+  if (!valor || typeof valor !== 'object' || Array.isArray(valor) || util.types.isProxy(valor)) {
+    fallar('MATERIALIZATION_INVALID', `${etiqueta} no materializable`);
+  }
+  const prototipo = Object.getPrototypeOf(valor);
+  if (prototipo !== Object.prototype && prototipo !== null) {
+    fallar('MATERIALIZATION_INVALID', `${etiqueta} con prototipo inválido`);
+  }
+  const descriptores = Object.getOwnPropertyDescriptors(valor);
+  if (Object.getOwnPropertySymbols(valor).length > 0) {
+    fallar('MATERIALIZATION_INVALID', `${etiqueta} con símbolos`);
+  }
+  if (Object.values(descriptores).some((item) => !item.enumerable || !('value' in item))) {
+    fallar('MATERIALIZATION_INVALID', `${etiqueta} con accessors`);
+  }
+}
+
+function validarCadenaUnicode(valor) {
+  for (let indice = 0; indice < valor.length; indice += 1) {
+    const unidad = valor.charCodeAt(indice);
+    if (unidad >= 0xd800 && unidad <= 0xdbff) {
+      const siguiente = valor.charCodeAt(indice + 1);
+      if (!(siguiente >= 0xdc00 && siguiente <= 0xdfff)) {
+        fallar('IJSON_INVALID', 'I-JSON inválido');
+      }
+      indice += 1;
+    } else if (unidad >= 0xdc00 && unidad <= 0xdfff) fallar('IJSON_INVALID', 'I-JSON inválido');
+  }
+}
+
+function validarArregloIJson(valor) {
+  if (util.types.isProxy(valor)) fallar('IJSON_INVALID', 'I-JSON inválido');
+  const claves = Reflect.ownKeys(valor);
+  const esperadas = [...Array(valor.length).keys()].map(String);
+  const visibles = claves.filter((clave) => clave !== 'length');
+  if (
+    visibles.some((clave) => typeof clave !== 'string')
+    || JSON.stringify(visibles) !== JSON.stringify(esperadas)
+  ) {
+    fallar('IJSON_INVALID', 'I-JSON inválido');
+  }
+  for (const item of valor) validarIJson(item);
+}
+
+function validarObjetoIJson(valor) {
+  validarMaterializado(valor, 'I-JSON');
+  for (const [clave, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(valor))) {
+    validarCadenaUnicode(clave);
+    validarIJson(descriptor.value);
+  }
+}
+
+function validarIJson(valor) {
+  if (valor === null || typeof valor === 'boolean') return;
+  if (typeof valor === 'string') return validarCadenaUnicode(valor);
+  if (typeof valor === 'number' && Number.isFinite(valor)) return;
+  if (Array.isArray(valor)) return validarArregloIJson(valor);
+  if (valor && typeof valor === 'object') return validarObjetoIJson(valor);
+  fallar('IJSON_INVALID', 'I-JSON inválido');
+}
+
+function serializarCanonico(valor) {
+  if (valor === null || typeof valor === 'boolean' || typeof valor === 'string') {
+    return JSON.stringify(valor);
+  }
+  if (typeof valor === 'number') return JSON.stringify(valor);
+  if (Array.isArray(valor)) return `[${valor.map(serializarCanonico).join(',')}]`;
+  const propiedades = Object.keys(valor).sort().map((clave) => (
+    `${JSON.stringify(clave)}:${serializarCanonico(valor[clave])}`
+  ));
+  return `{${propiedades.join(',')}}`;
+}
+
+function canonicalizarIJson(valor) {
+  try {
+    validarIJson(valor);
+    return serializarCanonico(valor);
+  } catch (error) {
+    if (error.codigo === 'IJSON_INVALID') throw error;
+    throw crearError('IJSON_INVALID', 'I-JSON inválido');
+  }
+}
+
+function copiarBytes(rawBytes) {
+  if (!rawBytes || typeof rawBytes !== 'object') {
+    fallar('RAW_BYTES_INVALID', 'raw bytes inválidos');
+  }
+  if (util.types.isProxy(rawBytes)) fallar('RAW_BYTES_INVALID', 'raw bytes inválidos');
+  const prototipo = Object.getPrototypeOf(rawBytes);
+  const propiedadesIntrusas = ['buffer', 'byteOffset', 'byteLength'].some(
+    (propiedad) => Object.hasOwn(rawBytes, propiedad)
+  );
+  if (
+    propiedadesIntrusas
+    || (prototipo !== Buffer.prototype && prototipo !== Uint8Array.prototype)
+  ) {
+    fallar('RAW_BYTES_INVALID', 'raw bytes inválidos');
+  }
+  const buffer = GET_ARRAY_BUFFER.call(rawBytes);
+  if (util.types.isSharedArrayBuffer(buffer)) {
+    fallar('RAW_BYTES_INVALID', 'raw bytes compartidos');
+  }
+  const offset = GET_BYTE_OFFSET.call(rawBytes);
+  const longitud = GET_BYTE_LENGTH.call(rawBytes);
+  const bytes = Buffer.from(buffer, offset, longitud);
+  return Buffer.from(bytes);
+}
+
+function decodificarUtf8(rawBytes) {
+  const bytes = copiarBytes(rawBytes);
+  if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+    fallar('RAW_BYTES_INVALID', 'raw bytes con BOM');
+  }
+  try {
+    return new util.TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    fallar('RAW_BYTES_INVALID', 'raw bytes no son UTF-8');
+  }
+}
+
+function parsearRawIJson(rawBytes) {
+  try {
+    const texto = decodificarUtf8(rawBytes);
+    const { valor } = parsearJSONSeguro(texto);
+    validarIJson(valor);
+    return valor;
+  } catch (error) {
+    if (error.codigo === 'RAW_BYTES_INVALID' || error.codigo === 'IJSON_INVALID') throw error;
+    if (error.codigo === 'JSON_CLAVE_DUPLICADA') {
+      throw crearError('IJSON_DUPLICATE', 'Clave JSON duplicada');
+    }
+    throw crearError('IJSON_INVALID', 'I-JSON raw inválido');
+  }
+}
+
+function sha256(bytes) {
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+function crearPublicKeyEd25519(publicKey, codigo) {
+  if (typeof publicKey !== 'string') throw crearError(codigo, 'clave pública inválida');
+  let keyObject;
+  try {
+    keyObject = crypto.createPublicKey(publicKey);
+  } catch {
+    throw crearError(codigo, 'clave pública inválida');
+  }
+  if (keyObject.asymmetricKeyType !== 'ed25519') fallar(codigo, 'clave no Ed25519');
+  return keyObject;
+}
+
+function digestPublicKey(keyObject) {
+  return sha256(keyObject.export({ format: 'der', type: 'spki' }));
+}
+
+function validarIdentificador(valor, etiqueta) {
+  if (typeof valor !== 'string' || !IDENTIFICADOR.test(valor)) {
+    fallar('CONTRACT_INVALID', `${etiqueta} inválido`);
+  }
+}
+
+function validarTimestampIso(valor, etiqueta) {
+  const patron = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u;
+  if (typeof valor !== 'string' || !patron.test(valor)) {
+    fallar('CONTRACT_INVALID', `${etiqueta} inválido`);
+  }
+  const milisegundos = Date.parse(valor);
+  if (Number.isNaN(milisegundos) || new Date(milisegundos).toISOString() !== valor) {
+    fallar('CONTRACT_INVALID', `${etiqueta} inválido`);
+  }
+}
+
+function congelarProfundo(valor) {
+  if (!valor || typeof valor !== 'object' || Object.isFrozen(valor)) return valor;
+  Object.values(valor).forEach(congelarProfundo);
+  return Object.freeze(valor);
+}
+
+function validarUnsigned(unsigned) {
+  validarMaterializado(unsigned, 'envelope unsigned');
+  validarClavesExactas(unsigned, CLAVES_UNSIGNED, 'envelope unsigned');
+  if (unsigned.schemaVersion !== SCHEMA_VERSION) fallar('CONTRACT_INVALID', 'schema futuro');
+  validarIdentificador(unsigned.type, 'type');
+  validarIdentificador(unsigned.keyId, 'keyId');
+  validarMaterializado(unsigned.claims, 'claims');
+  canonicalizarIJson(unsigned.claims);
+}
+
+function crearBytesFirma(type, unsigned) {
+  validarIdentificador(type, 'dominio');
+  validarUnsigned(unsigned);
+  const dominio = Buffer.from(`swl-ses/${type}/v1\0`, 'utf8');
+  return Buffer.concat([dominio, Buffer.from(canonicalizarIJson(unsigned), 'utf8')]);
+}
+
+function calcularTrustDigest(entries) {
+  if (!Array.isArray(entries)) fallar('TRUST_RECEIPT_INVALID', 'entries inválidas');
+  return sha256(Buffer.from(canonicalizarIJson(entries), 'utf8'));
+}
+
+function validarOpciones(valor, claves, etiqueta) {
+  try {
+    validarMaterializado(valor, etiqueta);
+    validarClavesExactas(valor, claves, etiqueta);
+  } catch {
+    fallar('OPTIONS_INVALID', `${etiqueta} inválidas`);
+  }
+}
+
+function crearRootVerifier(opciones) {
+  validarOpciones(
+    opciones,
+    ['rootPublicKey', 'rootKeyDigest', 'expectedRootKeyId'],
+    'opciones root'
+  );
+  validarIdentificador(opciones.expectedRootKeyId, 'root keyId');
+  if (!SHA256.test(opciones.rootKeyDigest)) fallar('ROOT_PIN_INVALID', 'pin inválido');
+  const keyObject = crearPublicKeyEd25519(opciones.rootPublicKey, 'ROOT_PIN_INVALID');
+  if (digestPublicKey(keyObject) !== opciones.rootKeyDigest) fallar('ROOT_PIN_INVALID', 'pin inválido');
+  const existente = ROOT_VERIFIERS_BY_DIGEST.get(opciones.rootKeyDigest);
+  if (existente) {
+    if (existente.keyId !== opciones.expectedRootKeyId) {
+      fallar('ROOT_PIN_INVALID', 'keyId de pin inválido');
+    }
+    return existente;
+  }
+  const verifier = Object.freeze({
+    kind: 'root-verifier',
+    keyId: opciones.expectedRootKeyId,
+    publicKeyDigest: opciones.rootKeyDigest,
+  });
+  ROOT_VERIFIERS.add(verifier);
+  ROOT_META.set(verifier, { keyObject, highWater: null });
+  ROOT_VERIFIERS_BY_DIGEST.set(opciones.rootKeyDigest, verifier);
+  return verifier;
+}
+
+function esRootVerifier(valor) {
+  return ROOT_VERIFIERS.has(valor);
+}
+
+function extraerUnsigned(envelope) {
+  return {
+    schemaVersion: envelope.schemaVersion,
+    type: envelope.type,
+    keyId: envelope.keyId,
+    claims: envelope.claims,
+  };
+}
+
+function parsearEnvelope(rawBytes) {
+  const envelope = parsearRawIJson(rawBytes);
+  validarMaterializado(envelope, 'envelope');
+  validarClavesExactas(envelope, CLAVES_ENVELOPE, 'envelope');
+  validarUnsigned(extraerUnsigned(envelope));
+  if (typeof envelope.signature !== 'string' || !BASE64URL.test(envelope.signature)) {
+    fallar('SIGNATURE_INVALID', 'firma inválida');
+  }
+  const signature = Buffer.from(envelope.signature, 'base64url');
+  if (signature.length !== 64 || signature.toString('base64url') !== envelope.signature) {
+    fallar('SIGNATURE_INVALID', 'firma inválida');
+  }
+  return { envelope, signature };
+}
+
+function verificarFirma(envelope, signature, keyObject) {
+  const bytes = crearBytesFirma(envelope.type, extraerUnsigned(envelope));
+  if (!crypto.verify(null, bytes, keyObject, signature)) {
+    fallar('SIGNATURE_INVALID', 'firma inválida');
+  }
+}
+
+function validarScopes(scopes) {
+  if (!Array.isArray(scopes) || scopes.length === 0) fallar('TRUST_RECEIPT_INVALID', 'scopes inválidos');
+  if (!scopes.every((scope) => typeof scope === 'string' && IDENTIFICADOR.test(scope))) {
+    fallar('TRUST_RECEIPT_INVALID', 'scopes inválidos');
+  }
+  if (new Set(scopes).size !== scopes.length || [...scopes].sort().join() !== scopes.join()) {
+    fallar('TRUST_RECEIPT_INVALID', 'scopes inválidos');
+  }
+}
+
+function validarEntry(entry) {
+  validarMaterializado(entry, 'trust entry');
+  validarClavesExactas(entry, CLAVES_ENTRY, 'trust entry');
+  validarIdentificador(entry.keyId, 'keyId');
+  if (!USAGES.has(entry.usage)) fallar('TRUST_RECEIPT_INVALID', 'usage inválido');
+  validarIdentificador(entry.issuer, 'issuer');
+  validarIdentificador(entry.subject, 'subject');
+  validarScopes(entry.scopes);
+  validarTimestampIso(entry.notBefore, 'notBefore');
+  validarTimestampIso(entry.notAfter, 'notAfter');
+  if (entry.notBefore >= entry.notAfter || typeof entry.revoked !== 'boolean') {
+    fallar('TRUST_RECEIPT_INVALID', 'vigencia inválida');
+  }
+  return crearPublicKeyEd25519(entry.publicKey, 'TRUST_RECEIPT_INVALID');
+}
+
+function indexarEntries(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) {
+    fallar('TRUST_RECEIPT_INVALID', 'entries inválidas');
+  }
+  const index = new Map();
+  const materiales = new Set();
+  for (const entry of entries) {
+    const keyObject = validarEntry(entry);
+    const digest = digestPublicKey(keyObject);
+    if (index.has(entry.keyId) || materiales.has(digest)) {
+      fallar('TRUST_RECEIPT_INVALID', 'clave duplicada');
+    }
+    index.set(entry.keyId, { entry, keyObject });
+    materiales.add(digest);
+  }
+  if ([...index.keys()].sort().join() !== [...index.keys()].join()) {
+    fallar('TRUST_RECEIPT_INVALID', 'entries no ordenadas');
+  }
+  return index;
+}
+
+function validarClaimsTrust(claims) {
+  validarMaterializado(claims, 'trust claims');
+  validarClavesExactas(claims, CLAVES_TRUST, 'trust claims');
+  if (claims.schemaVersion !== SCHEMA_VERSION || !Number.isInteger(claims.trustEpoch)) {
+    fallar('TRUST_RECEIPT_INVALID', 'trust version inválida');
+  }
+  if (claims.trustEpoch < 0 || !SHA256.test(claims.previousTrustDigest)) {
+    fallar('TRUST_RECEIPT_INVALID', 'trust chain inválida');
+  }
+  if (!SHA256.test(claims.trustDigest)) fallar('TRUST_RECEIPT_INVALID', 'trust digest inválido');
+  validarTimestampIso(claims.issuedAt, 'issuedAt');
+  const index = indexarEntries(claims.entries);
+  if (calcularTrustDigest(claims.entries) !== claims.trustDigest) {
+    fallar('TRUST_RECEIPT_INVALID', 'trust digest inválido');
+  }
+  return index;
+}
+
+function validarAvanceTrust(claims, previous, rootVerifier) {
+  const rootMeta = ROOT_META.get(rootVerifier);
+  if (previous === null) {
+    if (rootMeta.highWater !== null) fallar('TRUST_ROLLBACK', 'génesis trust repetida');
+    if (claims.trustEpoch !== 0 || claims.previousTrustDigest !== '0'.repeat(64)) {
+      fallar('TRUST_ROLLBACK', 'génesis trust inválida');
+    }
+    return;
+  }
+  if (!TRUST_CONTEXTS.has(previous)) fallar('TRUST_ROLLBACK', 'high-water no verificado');
+  const meta = TRUST_META.get(previous);
+  if (meta.rootVerifier !== rootVerifier) fallar('TRUST_ROLLBACK', 'raíz trust distinta');
+  if (rootMeta.highWater !== previous) fallar('TRUST_ROLLBACK', 'high-water trust obsoleto');
+  const epochOk = claims.trustEpoch === previous.trustEpoch + 1;
+  const digestOk = claims.previousTrustDigest === previous.trustDigest;
+  const timeOk = claims.issuedAt >= previous.lastTrustedTime;
+  if (!epochOk || !digestOk || !timeOk) fallar('TRUST_ROLLBACK', 'rollback trust detectado');
+}
+
+function verificarBootstrapReceipt(rawBytes, opciones) {
+  validarOpciones(opciones, ['rootVerifier', 'previousTrustContext'], 'opciones bootstrap');
+  if (!ROOT_VERIFIERS.has(opciones.rootVerifier)) fallar('ROOT_PIN_INVALID', 'raíz no verificada');
+  const { envelope, signature } = parsearEnvelope(rawBytes);
+  if (envelope.type !== TRUST_BOOTSTRAP || envelope.keyId !== opciones.rootVerifier.keyId) {
+    fallar('TRUST_RECEIPT_INVALID', 'bootstrap trust inválido');
+  }
+  verificarFirma(envelope, signature, ROOT_META.get(opciones.rootVerifier).keyObject);
+  const index = validarClaimsTrust(envelope.claims);
+  validarAvanceTrust(envelope.claims, opciones.previousTrustContext, opciones.rootVerifier);
+  congelarProfundo(envelope.claims);
+  const context = Object.freeze({
+    kind: 'verified-trust-context',
+    trustEpoch: envelope.claims.trustEpoch,
+    trustDigest: envelope.claims.trustDigest,
+    lastTrustedTime: envelope.claims.issuedAt,
+  });
+  TRUST_CONTEXTS.add(context);
+  TRUST_META.set(context, { index, rootVerifier: opciones.rootVerifier });
+  ROOT_META.get(opciones.rootVerifier).highWater = context;
+  return context;
+}
+
+function esTrustContextVerificado(valor) {
+  return TRUST_CONTEXTS.has(valor);
+}
+
+function validarOpcionesEnvelope(opciones) {
+  validarOpciones(
+    opciones,
+    ['trustContext', 'expectedType', 'requiredScope', 'now'],
+    'opciones envelope'
+  );
+  if (!TRUST_CONTEXTS.has(opciones.trustContext)) fallar('TRUST_CONTEXT_INVALID', 'trust no verificado');
+  if (!USAGES.has(opciones.expectedType)) fallar('ENVELOPE_INVALID', 'type inválido');
+  validarIdentificador(opciones.requiredScope, 'scope');
+  validarTimestampIso(opciones.now, 'now');
+}
+
+function validarTrustHighWater(context) {
+  const metadata = TRUST_META.get(context);
+  const root = ROOT_META.get(metadata.rootVerifier);
+  if (root.highWater !== context) {
+    fallar('TRUST_ROLLBACK', 'trust context histórico');
+  }
+}
+
+function validarEntryVigente(entry, opciones, context) {
+  if (entry.usage !== opciones.expectedType || !entry.scopes.includes(opciones.requiredScope)) {
+    fallar('ENVELOPE_INVALID', 'purpose o scope inválido');
+  }
+  if (entry.revoked || opciones.now < entry.notBefore || opciones.now > entry.notAfter) {
+    fallar('ENVELOPE_INVALID', 'clave fuera de vigencia');
+  }
+  if (opciones.now < context.lastTrustedTime) fallar('TRUST_ROLLBACK', 'tiempo confiable retrocedió');
+}
+
+function verificarEnvelope(rawBytes, opciones) {
+  validarOpcionesEnvelope(opciones);
+  validarTrustHighWater(opciones.trustContext);
+  const { envelope, signature } = parsearEnvelope(rawBytes);
+  if (envelope.type !== opciones.expectedType) fallar('ENVELOPE_INVALID', 'type inesperado');
+  const trust = TRUST_META.get(opciones.trustContext);
+  const found = trust.index.get(envelope.keyId);
+  if (!found) fallar('ENVELOPE_INVALID', 'keyId desconocido');
+  validarEntryVigente(found.entry, opciones, opciones.trustContext);
+  verificarFirma(envelope, signature, found.keyObject);
+  congelarProfundo(envelope.claims);
+  const verified = Object.freeze({
+    kind: 'verified-envelope',
+    schemaVersion: envelope.schemaVersion,
+    type: envelope.type,
+    keyId: envelope.keyId,
+    issuer: found.entry.issuer,
+    subject: found.entry.subject,
+    verifiedScope: opciones.requiredScope,
+    rootKeyDigest: trust.rootVerifier.publicKeyDigest,
+    signerPublicKeyDigest: digestPublicKey(found.keyObject),
+    claims: envelope.claims,
+    trustEpoch: opciones.trustContext.trustEpoch,
+    trustDigest: opciones.trustContext.trustDigest,
+  });
+  VERIFIED_ENVELOPES.add(verified);
+  ENVELOPE_META.set(verified, Object.freeze({
+    rootVerifier: trust.rootVerifier,
+    expectedType: opciones.expectedType,
+    requiredScope: opciones.requiredScope,
+    signerPublicKeyDigest: verified.signerPublicKeyDigest,
+  }));
+  return verified;
+}
+
+function revalidarEnvelopeVerificado(envelope, now) {
+  if (!VERIFIED_ENVELOPES.has(envelope)) fallar('ENVELOPE_INVALID', 'envelope no verificado');
+  validarTimestampIso(now, 'now');
+  const metadata = ENVELOPE_META.get(envelope);
+  const current = ROOT_META.get(metadata.rootVerifier).highWater;
+  validarTrustHighWater(current);
+  const trust = TRUST_META.get(current);
+  const found = trust.index.get(envelope.keyId);
+  if (!found) fallar('ENVELOPE_INVALID', 'keyId retirado');
+  validarEntryVigente(found.entry, {
+    expectedType: metadata.expectedType,
+    requiredScope: metadata.requiredScope,
+    now,
+  }, current);
+  if (digestPublicKey(found.keyObject) !== metadata.signerPublicKeyDigest) {
+    fallar('TRUST_ROLLBACK', 'firmante sustituido');
+  }
+  return Object.freeze({
+    rootKeyDigest: trust.rootVerifier.publicKeyDigest,
+    trustEpoch: current.trustEpoch,
+    trustDigest: current.trustDigest,
+    lastTrustedTime: current.lastTrustedTime,
+  });
+}
+
+function esEnvelopeVerificado(valor) {
+  return VERIFIED_ENVELOPES.has(valor);
+}
+
+module.exports = {
+  calcularTrustDigest,
+  canonicalizarIJson,
+  crearBytesFirma,
+  crearRootVerifier,
+  esEnvelopeVerificado,
+  esRootVerifier,
+  esTrustContextVerificado,
+  parsearIJson: parsearRawIJson,
+  revalidarEnvelopeVerificado,
+  validarTimestampIso,
+  verificarBootstrapReceipt,
+  verificarEnvelope,
+};