@saulwade/swl-ses 2.6.0 → 2.8.0

package/scripts/lib/runtime-operation-adapter.js

@@ -0,0 +1,267 @@
+'use strict';
+
+/** Traducción fail-closed de eventos Core-3 a operaciones W2 1.1 branded. */
+
+const crypto = require('node:crypto');
+const util = require('node:util');
+
+const {
+  verifyOperation,
+} = require('./policy-contract');
+const {
+  canonicalizarIJson,
+  parsearIJson,
+  validarTimestampIso,
+} = require('./signed-envelope');
+
+const MAX_EVENT_BYTES = 256 * 1024;
+const MAX_CONTEXT_BYTES = 4096;
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+const UNSAFE_TEXT = /[\u0000-\u001F\u007F\u001B\u200B-\u200F\u202A-\u202E\u2060-\u206F]/u;
+const EFFECT_FIELDS = Object.freeze({
+  filesystem: Object.freeze(['pathStyle', 'absolutePath', 'access']),
+  process: Object.freeze(['mode', 'pathStyle', 'executablePath', 'argv']),
+  network: Object.freeze(['scheme', 'asciiHost', 'port']),
+  memory: Object.freeze(['namespace', 'resourceId', 'access']),
+  delegation: Object.freeze(['targetAgentNodeId', 'capabilities']),
+  skill: Object.freeze(['skillNodeId']),
+});
+const EFFECT_BINDINGS = Object.freeze({
+  process: Object.freeze({ capability: 'shell.exec', effectKind: 'execute' }),
+  network: Object.freeze({ capability: 'network.access', effectKind: 'access' }),
+  delegation: Object.freeze({ capability: 'delegate', effectKind: 'delegate' }),
+  skill: Object.freeze({ capability: 'skill.invoke', effectKind: 'invoke' }),
+});
+const REASONS = Object.freeze({
+  RUNTIME_UNSUPPORTED: 'El runtime no pertenece al contrato Core-3.',
+  EVENT_INVALID: 'El evento nativo no cumple el contrato Core-3.',
+  CONTEXT_INVALID: 'El contexto de operación no cumple el contrato Core-3.',
+  TOOL_UNSUPPORTED: 'La herramienta no tiene traducción Core-3.',
+  OPERATION_INVALID: 'La herramienta no produce una operación W2 válida.',
+});
+const EFFORT_LEVELS = new Set(['low', 'medium', 'high', 'xhigh', 'max']);
+
+function crearTools(prefijo) {
+  return Object.freeze(Object.fromEntries(
+    Object.keys(EFFECT_FIELDS).map((kind) => [`${prefijo}${kind}`, kind])
+  ));
+}
+
+const RUNTIMES = Object.freeze({
+  'claude-code': Object.freeze({
+    eventName: 'PreToolUse',
+    transcriptNullable: false,
+    required: Object.freeze([
+      'session_id', 'transcript_path', 'cwd', 'permission_mode', 'hook_event_name',
+      'tool_name', 'tool_input', 'tool_use_id',
+    ]),
+    optional: Object.freeze(['prompt_id', 'effort', 'agent_id', 'agent_type']),
+    tools: crearTools('mcp__swl__'),
+  }),
+  'codex-cli': Object.freeze({
+    eventName: 'PreToolUse',
+    transcriptNullable: true,
+    required: Object.freeze([
+      'session_id', 'turn_id', 'transcript_path', 'cwd', 'hook_event_name', 'model',
+      'permission_mode', 'tool_name', 'tool_input', 'tool_use_id',
+    ]),
+    optional: Object.freeze([]),
+    tools: crearTools('mcp__swl__'),
+  }),
+  'gemini-cli': Object.freeze({
+    eventName: 'BeforeTool',
+    transcriptNullable: false,
+    required: Object.freeze([
+      'session_id', 'transcript_path', 'cwd', 'hook_event_name', 'timestamp',
+      'tool_name', 'tool_input',
+    ]),
+    optional: Object.freeze(['mcp_context', 'original_request_name']),
+    tools: crearTools('mcp_swl_'),
+  }),
+});
+
+function esObjetoPlano(valor) {
+  if (!valor || typeof valor !== 'object' || Array.isArray(valor)
+      || util.types.isProxy(valor)) return false;
+  const proto = Object.getPrototypeOf(valor);
+  return proto === Object.prototype;
+}
+
+function validarClaves(valor, requeridas, opcionales = []) {
+  if (!esObjetoPlano(valor)) throw new TypeError('objeto inválido');
+  const permitidas = new Set([...requeridas, ...opcionales]);
+  if (requeridas.some((key) => !Object.hasOwn(valor, key))
+      || Object.keys(valor).some((key) => !permitidas.has(key))) {
+    throw new TypeError('shape inválido');
+  }
+}
+
+function validarTexto(valor, maximo = 4096) {
+  if (typeof valor !== 'string' || valor.length === 0 || valor.length > maximo
+      || valor.normalize('NFKC') !== valor || UNSAFE_TEXT.test(valor)) {
+    throw new TypeError('texto inválido');
+  }
+}
+
+function parsearBytes(rawBytes, maximo) {
+  if (util.types.isProxy(rawBytes) || !Buffer.isBuffer(rawBytes)
+      || rawBytes.length === 0 || rawBytes.length > maximo) {
+    throw new TypeError('bytes inválidos');
+  }
+  return parsearIJson(Buffer.from(rawBytes));
+}
+
+function validarCampoOpcional(evento, key) {
+  if (!Object.hasOwn(evento, key)) return;
+  if (key === 'effort') {
+    validarClaves(evento.effort, ['level']);
+    if (!EFFORT_LEVELS.has(evento.effort.level)) throw new TypeError('effort inválido');
+    return;
+  }
+  if (key === 'mcp_context') {
+    if (!esObjetoPlano(evento.mcp_context)
+        || Buffer.byteLength(canonicalizarIJson(evento.mcp_context)) > 4096) {
+      throw new TypeError('mcp_context inválido');
+    }
+    return;
+  }
+  validarTexto(evento[key], 4096);
+}
+
+function validarEvento(runtime, evento) {
+  validarClaves(evento, runtime.required, runtime.optional);
+  for (const key of ['session_id', 'cwd', 'hook_event_name', 'tool_name']) {
+    validarTexto(evento[key], key === 'cwd' ? 4096 : 128);
+  }
+  if (evento.hook_event_name !== runtime.eventName || !esObjetoPlano(evento.tool_input)) {
+    throw new TypeError('evento o tool_input inválido');
+  }
+  for (const key of ['turn_id', 'model', 'permission_mode', 'tool_use_id']) {
+    if (Object.hasOwn(evento, key)) validarTexto(evento[key], 256);
+  }
+  if (evento.transcript_path === null) {
+    if (!runtime.transcriptNullable) throw new TypeError('transcript_path inválido');
+  } else {
+    validarTexto(evento.transcript_path, 4096);
+  }
+  if (Object.hasOwn(evento, 'timestamp')) {
+    validarTimestampIso(evento.timestamp, 'evento timestamp');
+  }
+  for (const key of runtime.optional) validarCampoOpcional(evento, key);
+}
+
+function validarContexto(contexto) {
+  validarClaves(contexto, ['phaseId', 'taskId', 'fsmVersion', 'timestamp']);
+  if (!IDENTIFIER.test(contexto.phaseId) || !/^T-[0-9]{2}$/u.test(contexto.taskId)) {
+    throw new TypeError('identidad de contexto inválida');
+  }
+  validarTimestampIso(contexto.timestamp, 'contexto timestamp');
+  if (!Number.isSafeInteger(contexto.fsmVersion) || contexto.fsmVersion < 0
+      || Object.is(contexto.fsmVersion, -0)) {
+    throw new TypeError('fsmVersion inválida');
+  }
+}
+
+function crearEffect(kind, toolInput) {
+  validarClaves(toolInput, EFFECT_FIELDS[kind]);
+  return { kind, ...toolInput };
+}
+
+function bindingEffect(effect) {
+  if (effect.kind === 'filesystem') {
+    return effect.access === 'read'
+      ? { capability: 'filesystem.read', effectKind: 'read' }
+      : { capability: 'filesystem.mutate', effectKind: 'mutate' };
+  }
+  if (effect.kind === 'memory') {
+    return effect.access === 'read'
+      ? { capability: 'memory.read', effectKind: 'read' }
+      : { capability: 'memory.write', effectKind: 'mutate' };
+  }
+  return EFFECT_BINDINGS[effect.kind];
+}
+
+function sha256(texto) {
+  return crypto.createHash('sha256').update(texto, 'utf8').digest('hex');
+}
+
+function crearOperacion(runtimeId, evento, contexto, effect) {
+  const eventoCanonico = canonicalizarIJson(evento);
+  const contextoCanonico = canonicalizarIJson(contexto);
+  const effectCanonico = canonicalizarIJson(effect);
+  const binding = bindingEffect(effect);
+  return {
+    schemaVersion: '1.1.0',
+    operationId: `op:${sha256(`${runtimeId}\0${eventoCanonico}\0${contextoCanonico}`)}`,
+    ...binding,
+    payloadDigest: sha256(eventoCanonico),
+    scope: { digest: sha256(effectCanonico) },
+    cwd: evento.cwd,
+    fsmVersion: contexto.fsmVersion,
+    timestamp: contexto.timestamp,
+    phaseId: contexto.phaseId,
+    taskId: contexto.taskId,
+    effect,
+  };
+}
+
+function denegar(runtimeId, code) {
+  return Object.freeze({
+    status: 'denied', code, reason: REASONS[code],
+    runtimeId: typeof runtimeId === 'string' && Object.hasOwn(RUNTIMES, runtimeId)
+      ? runtimeId : null,
+    effectiveMode: 'proposal_only',
+  });
+}
+
+function parsearEvento(runtimeId, runtime, rawEventBytes) {
+  try {
+    const evento = parsearBytes(rawEventBytes, MAX_EVENT_BYTES);
+    validarEvento(runtime, evento);
+    return evento;
+  } catch {
+    return denegar(runtimeId, 'EVENT_INVALID');
+  }
+}
+
+function parsearContexto(runtimeId, rawContextBytes) {
+  try {
+    const contexto = parsearBytes(rawContextBytes, MAX_CONTEXT_BYTES);
+    validarContexto(contexto);
+    return contexto;
+  } catch {
+    return denegar(runtimeId, 'CONTEXT_INVALID');
+  }
+}
+
+function traducirOperacionRuntime(runtimeId, rawEventBytes, rawContextBytes) {
+  if (typeof runtimeId !== 'string' || !Object.hasOwn(RUNTIMES, runtimeId)) {
+    return denegar(runtimeId, 'RUNTIME_UNSUPPORTED');
+  }
+  const runtime = RUNTIMES[runtimeId];
+  const evento = parsearEvento(runtimeId, runtime, rawEventBytes);
+  if (evento.status === 'denied') return evento;
+  if (!Object.hasOwn(runtime.tools, evento.tool_name)) {
+    return denegar(runtimeId, 'TOOL_UNSUPPORTED');
+  }
+  const kind = runtime.tools[evento.tool_name];
+  const contexto = parsearContexto(runtimeId, rawContextBytes);
+  if (contexto.status === 'denied') return contexto;
+  if (evento.timestamp && evento.timestamp !== contexto.timestamp) {
+    return denegar(runtimeId, 'CONTEXT_INVALID');
+  }
+  try {
+    const effect = crearEffect(kind, evento.tool_input);
+    const rawOperation = Buffer.from(canonicalizarIJson(
+      crearOperacion(runtimeId, evento, contexto, effect)
+    ));
+    return Object.freeze({
+      status: 'translated', runtimeId, effectiveMode: 'proposal_only',
+      operation: verifyOperation(rawOperation),
+    });
+  } catch {
+    return denegar(runtimeId, 'OPERATION_INVALID');
+  }
+}
+
+module.exports = { traducirOperacionRuntime };

package/scripts/lib/schema-version.js

@@ -1,164 +1,164 @@
-'use strict';
-
-/**
- * scripts/lib/schema-version.js
- *
- * Helper de compatibilidad de schemas JSON aplicando reglas backward/forward
- * del libro "Designing Data-Intensive Applications" de Martin Kleppmann
- * (Capítulo 4, "Encoding and Evolution", p.112).
- *
- * Reglas implementadas (cita textual del libro):
- *
- *   "Backward compatibility — Newer code can read data that was written by
- *    older code.
- *
- *    Forward compatibility — Older code can read data that was written by
- *    newer code."
- *
- * Aplicado a SWL: cuando un schema evoluciona, el helper indica si un
- * documento dado puede leerse con el schema dado y bajo qué modalidad
- * de compatibilidad.
- *
- * Convenciones SemVer asumidas para $schemaVersion:
- *   - MAJOR (X.0.0): breaking change (renombre, cambio de tipo, eliminación)
- *   - MINOR (1.X.0): campo nuevo opcional, enum value nuevo
- *   - PATCH (1.0.X): clarificación de descripción, sin cambio estructural
- *
- * Skill relacionado: proceso-ddia-fundamentos § Schema Evolution.
- * ADR: 0026 — Versionado de schemas JSON con $schemaVersion.
- */
-
-/**
- * Parsea un string SemVer "MAJOR.MINOR.PATCH" a tupla numérica.
- * @param {string} version
- * @returns {[number, number, number] | null}
- */
-function parsearVersion(version) {
-  if (typeof version !== 'string') return null;
-  const m = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
-  if (!m) return null;
-  return [parseInt(m[1], 10), parseInt(m[2], 10), parseInt(m[3], 10)];
-}
-
-/**
- * Verifica si un documento es compatible con un schema según sus $schemaVersion.
- *
- * @param {object} documento - Documento JSON con propiedad opcional $schemaVersion
- * @param {object} schema - JSON Schema con propiedad opcional $schemaVersion
- * @returns {{
- *   compatible: boolean,
- *   modo: "none" | "backward" | "forward" | "incompatible",
- *   advertencias: string[]
- * }}
- *
- * Casos:
- *   - Ambos sin $schemaVersion → { compatible: true, modo: "none", advertencias: [warning] }
- *   - Documento sin, schema con  → { compatible: true, modo: "forward", advertencias: [warning] }
- *   - Doc 1.0.0 vs Schema 1.0.0  → { compatible: true, modo: "none" }
- *   - Doc 1.0.0 vs Schema 1.1.0  → { compatible: true, modo: "forward" } (dato viejo + código nuevo)
- *   - Doc 1.1.0 vs Schema 1.0.0  → { compatible: true, modo: "backward" } (dato nuevo + código viejo)
- *   - Doc 2.0.0 vs Schema 1.0.0  → { compatible: false, modo: "incompatible" } (MAJOR rompe)
- *   - Doc 1.0.0 vs Schema 2.0.0  → { compatible: false, modo: "incompatible" }
- *   - Versión malformada         → { compatible: false, modo: "incompatible", advertencias: [error] }
- */
-function verificarCompatibilidad(documento, schema) {
-  const advertencias = [];
-
-  const docVerStr = documento && documento.$schemaVersion;
-  const schVerStr = schema && schema.$schemaVersion;
-
-  if (!docVerStr && !schVerStr) {
-    return {
-      compatible: true,
-      modo: 'none',
-      advertencias: [
-        'Ni documento ni schema declaran $schemaVersion. Compatibilidad asumida pero no verificable.',
-      ],
-    };
-  }
-
-  if (!docVerStr && schVerStr) {
-    return {
-      compatible: true,
-      modo: 'forward',
-      advertencias: [
-        `Documento sin $schemaVersion contra schema ${schVerStr}. Asumiendo forward-compat (código nuevo lee dato viejo sin versión).`,
-      ],
-    };
-  }
-
-  if (docVerStr && !schVerStr) {
-    return {
-      compatible: false,
-      modo: 'incompatible',
-      advertencias: [
-        `Documento declara $schemaVersion ${docVerStr} pero schema no la declara. Schema debe actualizarse a $schemaVersion para validación correcta.`,
-      ],
-    };
-  }
-
-  const docVer = parsearVersion(docVerStr);
-  const schVer = parsearVersion(schVerStr);
-
-  if (!docVer) {
-    return {
-      compatible: false,
-      modo: 'incompatible',
-      advertencias: [`Documento $schemaVersion malformada: "${docVerStr}". Debe ser MAJOR.MINOR.PATCH (ej: "1.0.0").`],
-    };
-  }
-  if (!schVer) {
-    return {
-      compatible: false,
-      modo: 'incompatible',
-      advertencias: [`Schema $schemaVersion malformada: "${schVerStr}". Debe ser MAJOR.MINOR.PATCH (ej: "1.0.0").`],
-    };
-  }
-
-  const [docMaj, docMin] = docVer;
-  const [schMaj, schMin] = schVer;
-
-  // MAJOR distinto → incompatible (regla DDIA Cap 4: MAJOR es breaking)
-  if (docMaj !== schMaj) {
-    return {
-      compatible: false,
-      modo: 'incompatible',
-      advertencias: [
-        `MAJOR diferente: documento ${docVerStr} vs schema ${schVerStr}. ` +
-        `Cambios MAJOR son breaking por convención SemVer. Migración explícita requerida.`,
-      ],
-    };
-  }
-
-  // Mismo MAJOR.MINOR → compatible total (PATCH no afecta estructura)
-  if (docMin === schMin) {
-    return { compatible: true, modo: 'none', advertencias: [] };
-  }
-
-  // Documento MINOR menor que schema → forward (código nuevo lee dato viejo)
-  if (docMin < schMin) {
-    return {
-      compatible: true,
-      modo: 'forward',
-      advertencias: [
-        `Documento ${docVerStr} más antiguo que schema ${schVerStr}. ` +
-        `Forward-compat: código nuevo debe ignorar campos nuevos ausentes en dato viejo.`,
-      ],
-    };
-  }
-
-  // Documento MINOR mayor que schema → backward (código viejo lee dato nuevo)
-  return {
-    compatible: true,
-    modo: 'backward',
-    advertencias: [
-      `Documento ${docVerStr} más nuevo que schema ${schVerStr}. ` +
-      `Backward-compat: código viejo debe ignorar campos desconocidos en dato nuevo.`,
-    ],
-  };
-}
-
-module.exports = {
-  parsearVersion,
-  verificarCompatibilidad,
-};
+'use strict';
+
+/**
+ * scripts/lib/schema-version.js
+ *
+ * Helper de compatibilidad de schemas JSON aplicando reglas backward/forward
+ * del libro "Designing Data-Intensive Applications" de Martin Kleppmann
+ * (Capítulo 4, "Encoding and Evolution", p.112).
+ *
+ * Reglas implementadas (cita textual del libro):
+ *
+ *   "Backward compatibility — Newer code can read data that was written by
+ *    older code.
+ *
+ *    Forward compatibility — Older code can read data that was written by
+ *    newer code."
+ *
+ * Aplicado a SWL: cuando un schema evoluciona, el helper indica si un
+ * documento dado puede leerse con el schema dado y bajo qué modalidad
+ * de compatibilidad.
+ *
+ * Convenciones SemVer asumidas para $schemaVersion:
+ *   - MAJOR (X.0.0): breaking change (renombre, cambio de tipo, eliminación)
+ *   - MINOR (1.X.0): campo nuevo opcional, enum value nuevo
+ *   - PATCH (1.0.X): clarificación de descripción, sin cambio estructural
+ *
+ * Skill relacionado: proceso-ddia-fundamentos § Schema Evolution.
+ * ADR: 0026 — Versionado de schemas JSON con $schemaVersion.
+ */
+
+/**
+ * Parsea un string SemVer "MAJOR.MINOR.PATCH" a tupla numérica.
+ * @param {string} version
+ * @returns {[number, number, number] | null}
+ */
+function parsearVersion(version) {
+  if (typeof version !== 'string') return null;
+  const m = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
+  if (!m) return null;
+  return [parseInt(m[1], 10), parseInt(m[2], 10), parseInt(m[3], 10)];
+}
+
+/**
+ * Verifica si un documento es compatible con un schema según sus $schemaVersion.
+ *
+ * @param {object} documento - Documento JSON con propiedad opcional $schemaVersion
+ * @param {object} schema - JSON Schema con propiedad opcional $schemaVersion
+ * @returns {{
+ *   compatible: boolean,
+ *   modo: "none" | "backward" | "forward" | "incompatible",
+ *   advertencias: string[]
+ * }}
+ *
+ * Casos:
+ *   - Ambos sin $schemaVersion → { compatible: true, modo: "none", advertencias: [warning] }
+ *   - Documento sin, schema con  → { compatible: true, modo: "forward", advertencias: [warning] }
+ *   - Doc 1.0.0 vs Schema 1.0.0  → { compatible: true, modo: "none" }
+ *   - Doc 1.0.0 vs Schema 1.1.0  → { compatible: true, modo: "forward" } (dato viejo + código nuevo)
+ *   - Doc 1.1.0 vs Schema 1.0.0  → { compatible: true, modo: "backward" } (dato nuevo + código viejo)
+ *   - Doc 2.0.0 vs Schema 1.0.0  → { compatible: false, modo: "incompatible" } (MAJOR rompe)
+ *   - Doc 1.0.0 vs Schema 2.0.0  → { compatible: false, modo: "incompatible" }
+ *   - Versión malformada         → { compatible: false, modo: "incompatible", advertencias: [error] }
+ */
+function verificarCompatibilidad(documento, schema) {
+  const advertencias = [];
+
+  const docVerStr = documento && documento.$schemaVersion;
+  const schVerStr = schema && schema.$schemaVersion;
+
+  if (!docVerStr && !schVerStr) {
+    return {
+      compatible: true,
+      modo: 'none',
+      advertencias: [
+        'Ni documento ni schema declaran $schemaVersion. Compatibilidad asumida pero no verificable.',
+      ],
+    };
+  }
+
+  if (!docVerStr && schVerStr) {
+    return {
+      compatible: true,
+      modo: 'forward',
+      advertencias: [
+        `Documento sin $schemaVersion contra schema ${schVerStr}. Asumiendo forward-compat (código nuevo lee dato viejo sin versión).`,
+      ],
+    };
+  }
+
+  if (docVerStr && !schVerStr) {
+    return {
+      compatible: false,
+      modo: 'incompatible',
+      advertencias: [
+        `Documento declara $schemaVersion ${docVerStr} pero schema no la declara. Schema debe actualizarse a $schemaVersion para validación correcta.`,
+      ],
+    };
+  }
+
+  const docVer = parsearVersion(docVerStr);
+  const schVer = parsearVersion(schVerStr);
+
+  if (!docVer) {
+    return {
+      compatible: false,
+      modo: 'incompatible',
+      advertencias: [`Documento $schemaVersion malformada: "${docVerStr}". Debe ser MAJOR.MINOR.PATCH (ej: "1.0.0").`],
+    };
+  }
+  if (!schVer) {
+    return {
+      compatible: false,
+      modo: 'incompatible',
+      advertencias: [`Schema $schemaVersion malformada: "${schVerStr}". Debe ser MAJOR.MINOR.PATCH (ej: "1.0.0").`],
+    };
+  }
+
+  const [docMaj, docMin] = docVer;
+  const [schMaj, schMin] = schVer;
+
+  // MAJOR distinto → incompatible (regla DDIA Cap 4: MAJOR es breaking)
+  if (docMaj !== schMaj) {
+    return {
+      compatible: false,
+      modo: 'incompatible',
+      advertencias: [
+        `MAJOR diferente: documento ${docVerStr} vs schema ${schVerStr}. ` +
+        `Cambios MAJOR son breaking por convención SemVer. Migración explícita requerida.`,
+      ],
+    };
+  }
+
+  // Mismo MAJOR.MINOR → compatible total (PATCH no afecta estructura)
+  if (docMin === schMin) {
+    return { compatible: true, modo: 'none', advertencias: [] };
+  }
+
+  // Documento MINOR menor que schema → forward (código nuevo lee dato viejo)
+  if (docMin < schMin) {
+    return {
+      compatible: true,
+      modo: 'forward',
+      advertencias: [
+        `Documento ${docVerStr} más antiguo que schema ${schVerStr}. ` +
+        `Forward-compat: código nuevo debe ignorar campos nuevos ausentes en dato viejo.`,
+      ],
+    };
+  }
+
+  // Documento MINOR mayor que schema → backward (código viejo lee dato nuevo)
+  return {
+    compatible: true,
+    modo: 'backward',
+    advertencias: [
+      `Documento ${docVerStr} más nuevo que schema ${schVerStr}. ` +
+      `Backward-compat: código viejo debe ignorar campos desconocidos en dato nuevo.`,
+    ],
+  };
+}
+
+module.exports = {
+  parsearVersion,
+  verificarCompatibilidad,
+};