@saulwade/swl-ses 2.6.0 → 2.8.0

package/scripts/lib/w4-verificar-veredicto.js

@@ -0,0 +1,302 @@
+'use strict';
+
+/**
+ * Verificador del `CertificationVerdict` (ADR-0053 § Decisión pieza 5, F32/T-06,
+ * REQ-32-06). Núcleo PURO con el puerto de attestation INYECTADO
+ * (`attestationVerifier`) — este módulo nunca invoca `gh`, nunca hace red ni
+ * filesystem por su cuenta; el adaptador real de `gh attestation verify`
+ * origin-pinned es T-09 (fuera del alcance de esta tarea).
+ *
+ * C3a — honestidad del modo dev (ADR-0053 § Honestidad del red-team, C6): en
+ * F32/T-06 este verificador SÓLO puede ejercitarse contra un
+ * `attestationVerifier` SIMULADO (un stub de test, nunca `gh` real). Ningún
+ * resultado `{ok:true}` producido con un stub constituye "origen verificado"
+ * en el sentido de ADR-0053 — esa garantía exige el adaptador real de T-09,
+ * el environment protegido `certificacion` y el resto del provisioning
+ * humano (H-3/H-4/H-6/H-7/H-10). El propio veredicto lo declara: en modo
+ * dev, `firma.dev.nota` (constante fija, validada por
+ * `w4-veredicto.js#validateCertificationVerdict`) dice explícitamente
+ * "verificador dev, adaptador de attestation simulado" — y este verificador
+ * NUNCA certifica un veredicto dev (`VERDICT_DEV_NO_CERTIFICANTE`),
+ * cualquiera sea el resultado del puerto.
+ *
+ * Solo lectura: nunca muta `verdict`. Nunca lanza — todo camino de error
+ * retorna `{ ok:false, codigo }` (fail-closed en cada borde, incluyendo
+ * cualquier excepción del puerto inyectado — C4).
+ */
+
+const crypto = require('node:crypto');
+
+const { validateCertificationVerdict } = require('./w4-veredicto');
+const { canonicalizarIJson } = require('./signed-envelope');
+
+const MAX_BUNDLE_BYTES = 8 * 1024 * 1024;
+
+const CODIGOS = Object.freeze({
+  MALFORMED: 'VERDICT_MALFORMED',
+  REQUEST_REQUIRED: 'VERDICT_REQUEST_REQUIRED',
+  REQUEST_MISMATCH: 'VERDICT_REQUEST_MISMATCH',
+  DEV_NO_CERTIFICANTE: 'VERDICT_DEV_NO_CERTIFICANTE',
+  SIGNATURE_INVALID: 'VERDICT_SIGNATURE_INVALID',
+  ORIGIN_MISMATCH: 'VERDICT_ORIGIN_MISMATCH',
+});
+
+function esObjetoPlano(valor) {
+  return Boolean(valor) && typeof valor === 'object' && !Array.isArray(valor)
+    && Object.getPrototypeOf(valor) === Object.prototype
+    && Object.getOwnPropertySymbols(valor).length === 0;
+}
+
+function congelarProfundo(valor) {
+  if (valor && typeof valor === 'object' && !Object.isFrozen(valor)) {
+    Object.values(valor).forEach(congelarProfundo);
+    Object.freeze(valor);
+  }
+  return valor;
+}
+
+function rechazo(codigo) {
+  return Object.freeze({ ok: false, codigo });
+}
+
+function clavesExactas(valor, esperadas) {
+  return esObjetoPlano(valor)
+    && JSON.stringify(Object.keys(valor).sort()) === JSON.stringify([...esperadas].sort());
+}
+
+// ---------------------------------------------------------------------------
+// C2 — anti-replay: requestEsperado es obligatorio, comparación exacta.
+// ---------------------------------------------------------------------------
+
+// Defensa en profundidad deliberadamente redundante: `runtime`/`os`/`model`
+// (vía w4-veredicto.js#validarMatrixEntry, enum + `IDENTIFICADOR` ASCII) y
+// `commit`/`tarballDigest` (hex ASCII) ya restringen estos campos a ASCII
+// antes de llegar aquí, así que hoy ningún valor real requiere normalización
+// NFKC. Se conserva porque es barata (una llamada nativa por campo) y actúa
+// como anti-regresión: si el validador upstream (`validarRequestEsperadoShape`
+// / `validateCertificationVerdict`) alguna vez se relaja a Unicode más amplio,
+// esta normalización sigue cerrando el vector de confusión NFKC sin requerir
+// un cambio coordinado en este módulo.
+function normalizarNFKC(valor) {
+  return typeof valor === 'string' ? valor.normalize('NFKC') : valor;
+}
+
+function validarRequestEsperadoShape(valor) {
+  if (!clavesExactas(valor, ['commit', 'tarballDigest', 'matrix'])) return false;
+  if (typeof valor.commit !== 'string' || typeof valor.tarballDigest !== 'string') return false;
+  if (!Array.isArray(valor.matrix) || valor.matrix.length === 0) return false;
+  return valor.matrix.every((entrada) => (
+    clavesExactas(entrada, ['runtime', 'os', 'model'])
+    && typeof entrada.runtime === 'string' && typeof entrada.os === 'string' && typeof entrada.model === 'string'
+  ));
+}
+
+function claveMatrixEntry(entrada) {
+  return `${normalizarNFKC(entrada.runtime)}|${normalizarNFKC(entrada.os)}|${normalizarNFKC(entrada.model)}`;
+}
+
+/**
+ * Comparación EXACTA (C2) de `verdict.request` contra `requestEsperado`, con
+ * normalización NFKC por campo — el arreglo `matrix` se compara como
+ * multiconjunto (el orden de las entradas nunca es información de
+ * seguridad); cualquier entrada distinta, faltante o sobrante rechaza.
+ */
+function coincideRequest(verdictRequest, requestEsperado) {
+  if (normalizarNFKC(verdictRequest.commit) !== normalizarNFKC(requestEsperado.commit)) return false;
+  if (normalizarNFKC(verdictRequest.tarballDigest) !== normalizarNFKC(requestEsperado.tarballDigest)) return false;
+  if (verdictRequest.matrix.length !== requestEsperado.matrix.length) return false;
+  const propias = verdictRequest.matrix.map(claveMatrixEntry).sort();
+  const esperadas = requestEsperado.matrix.map(claveMatrixEntry).sort();
+  return JSON.stringify(propias) === JSON.stringify(esperadas);
+}
+
+// ---------------------------------------------------------------------------
+// C1 — binding firma <-> payload: el núcleo calcula el digest esperado.
+// ---------------------------------------------------------------------------
+
+/**
+ * `sha256(canonicalizarIJson(verdict SIN el bloque 'firma')))` — puro,
+ * independientemente testeable (C1: "la comparación vive en el core
+ * testeable"). Excluir `firma` es deliberado: el digest identifica el
+ * CONTENIDO atestiguado, no la firma misma (que se añade después de
+ * calcular el digest, en el flujo real de `gh attestation sign`).
+ */
+function sha256Utf8(texto) {
+  return crypto.createHash('sha256').update(texto, 'utf8').digest('hex');
+}
+
+function bytesVerdictSinFirma(verdict) {
+  const { firma, ...sinFirma } = verdict;
+  void firma;
+  return canonicalizarIJson(sinFirma);
+}
+
+function digestVerdictSinFirma(verdict) {
+  return sha256Utf8(bytesVerdictSinFirma(verdict));
+}
+
+// ---------------------------------------------------------------------------
+// C3/C4 — contrato documentado del adaptador real + fail-closed en su salida.
+// ---------------------------------------------------------------------------
+
+/**
+ * Contrato documentado del adaptador REAL de `gh attestation verify`
+ * (T-09, NO ejecutado en F32/T-06 — este módulo sólo recibe el puerto
+ * inyectado). Entrada, tres argumentos (ADR-0056):
+ *   `(bundle: Buffer, expectedArtifactDigest: string sha256 hex,
+ *     artifactBytes: string)`
+ * donde `artifactBytes` son los bytes canónicos I-JSON del veredicto SIN el
+ * bloque `firma` (los mismos cuyo sha256 es `expectedArtifactDigest`).
+ * Salida esperada, `exactKeys` estricto (C3c/C4): SIN campos adicionales,
+ * SIN tipos laxos —
+ *
+ *   { identidadOIDC: { repo: string, workflow: string, ref: string },
+ *     firmaValida: boolean }
+ *
+ * El `gh` real (v2.89.0, verificado en T-09) EXIGE el artefacto en disco
+ * (`gh attestation verify <file-path> --owner … --signer-workflow …`) y NO
+ * soporta un modo `--digest` de digest-desnudo; por eso el núcleo pasa los
+ * `artifactBytes`, que el adaptador escribe a un archivo temporal 0600 y
+ * entrega a `gh`. `gh` computa el sha256 del archivo y lo compara contra el
+ * sujeto atestiguado por Sigstore — así se materializa la comparación C1 en
+ * el mundo real. `expectedArtifactDigest` se pasa además como cross-check
+ * barato (el adaptador puede aseverar `sha256(artifactBytes) === expected`
+ * antes de invocar `gh`). Este verificador nunca parsea el bundle Sigstore
+ * ni toca disco/red por sí mismo (el efecto vive en el adaptador de T-09).
+ */
+function validarFormaSalidaAttestation(valor) {
+  if (!clavesExactas(valor, ['identidadOIDC', 'firmaValida'])) return false;
+  if (typeof valor.firmaValida !== 'boolean') return false;
+  const identidad = valor.identidadOIDC;
+  if (!clavesExactas(identidad, ['repo', 'workflow', 'ref'])) return false;
+  return typeof identidad.repo === 'string' && identidad.repo.length > 0
+    && typeof identidad.workflow === 'string' && identidad.workflow.length > 0
+    && typeof identidad.ref === 'string' && identidad.ref.length > 0;
+}
+
+/**
+ * Contrato de ENTRADA del adaptador real: `bundle` son bytes crudos
+ * acotados (mismo patrón fail-closed que
+ * `scripts/lib/runtime-build-attestation.js#validateRawBytes` — prototipo
+ * `Buffer`/`Uint8Array`, sin propiedades intrusas, tamaño en
+ * `(0, MAX_BUNDLE_BYTES]`). Este módulo NO parsea el bundle como I-JSON
+ * (ese formato lo define Sigstore, no ADR-0053) — sólo acota su forma antes
+ * de calcular su digest (C7) y de pasarlo al puerto.
+ */
+function validarBundleBytes(bundle) {
+  if (!bundle || typeof bundle !== 'object') return false;
+  const prototipo = Object.getPrototypeOf(bundle);
+  if (prototipo !== Buffer.prototype && prototipo !== Uint8Array.prototype) return false;
+  if (['buffer', 'byteOffset', 'byteLength'].some((propiedad) => Object.hasOwn(bundle, propiedad))) return false;
+  return bundle.byteLength > 0 && bundle.byteLength <= MAX_BUNDLE_BYTES;
+}
+
+function validarPinOrigen(valor) {
+  return clavesExactas(valor, ['repo', 'workflow', 'ref'])
+    && typeof valor.repo === 'string' && valor.repo.length > 0
+    && typeof valor.workflow === 'string' && valor.workflow.length > 0
+    && typeof valor.ref === 'string' && valor.ref.length > 0;
+}
+
+// ---------------------------------------------------------------------------
+// verificarVeredicto — orquestador fail-closed.
+// ---------------------------------------------------------------------------
+
+/**
+ * Verifica un `CertificationVerdict` contra el mecanismo de aislamiento de
+ * ADR-0053. Nunca lanza: retorna `{ok:false, codigo}` en cualquier borde de
+ * fallo, o `{ok:true, verdict, identidadOIDC}` (deep-frozen) sólo cuando
+ * TODAS las condiciones se cumplen — estructura válida, request coincidente
+ * (C2), modo `real` con firma protegida verificada con origen pineado
+ * (C1/C3/C4/C7). Un veredicto `modo:'dev'` NUNCA certifica, aunque esté
+ * perfectamente bien formado (C3a).
+ *
+ * @param {unknown} verdict
+ * @param {{pinOrigen: unknown, requestEsperado: unknown,
+ *   attestationVerifier: (bundle: Buffer, expectedArtifactDigest: string,
+ *     artifactBytes: string) => Promise<unknown> | unknown, bundle: unknown}} opciones
+ */
+async function verificarVeredicto(verdict, opciones) {
+  let sano;
+  try {
+    sano = validateCertificationVerdict(verdict);
+  } catch {
+    return rechazo(CODIGOS.MALFORMED);
+  }
+
+  const opcionesSanas = esObjetoPlano(opciones) ? opciones : {};
+  const { pinOrigen, requestEsperado, attestationVerifier, bundle } = opcionesSanas;
+
+  // C2: "nunca acepta sin request" — precondición incondicional, antes de
+  // ramificar por modo dev/real.
+  if (!validarRequestEsperadoShape(requestEsperado)) return rechazo(CODIGOS.REQUEST_REQUIRED);
+  if (!coincideRequest(sano.request, requestEsperado)) return rechazo(CODIGOS.REQUEST_MISMATCH);
+
+  // C6 (delegado a validateCertificationVerdict, ejecutado arriba): un
+  // veredicto dev con `firma.dev.nota` distinta del literal fijo ya fue
+  // rechazado como VERDICT_MALFORMED. Llegar aquí con modo:'dev' significa
+  // que la nota es exactamente la esperada — igual NUNCA certifica (C3a).
+  if (sano.firma.modo === 'dev') return rechazo(CODIGOS.DEV_NO_CERTIFICANTE);
+
+  // ---- Camino 'real' — bloque sigstore completo, C1/C3/C4/C7. --------------
+
+  if (typeof attestationVerifier !== 'function') return rechazo(CODIGOS.SIGNATURE_INVALID);
+  if (!validarBundleBytes(bundle)) return rechazo(CODIGOS.SIGNATURE_INVALID);
+
+  // C7: el bundle presentado en esta verificación debe ser el mismo que el
+  // veredicto declaró al emitirse — nunca invocar el puerto con un bundle
+  // sustituido después de los hechos.
+  const bundleDigest = crypto.createHash('sha256').update(bundle).digest('hex');
+  if (bundleDigest !== sano.firma.bundleDigest) return rechazo(CODIGOS.SIGNATURE_INVALID);
+
+  if (!validarPinOrigen(pinOrigen)) return rechazo(CODIGOS.SIGNATURE_INVALID);
+
+  // C1 (ADR-0056): el núcleo puro deriva del CONTENIDO del propio veredicto
+  // tanto los bytes canónicos como su digest — nunca de un valor que el caller
+  // pudiera inyectar — y ambos se pasan al puerto: el adaptador real necesita
+  // los bytes para presentarle a `gh attestation verify` el artefacto en disco
+  // (no existe modo digest-desnudo), y el digest queda como cross-check.
+  const artifactBytes = bytesVerdictSinFirma(sano);
+  const expectedArtifactDigest = sha256Utf8(artifactBytes);
+
+  let salidaCruda;
+  try {
+    salidaCruda = await attestationVerifier(bundle, expectedArtifactDigest, artifactBytes);
+  } catch {
+    // C4: cualquier excepción del puerto -> rechazo, nunca propagar.
+    return rechazo(CODIGOS.SIGNATURE_INVALID);
+  }
+
+  // C3/C4: forma exacta y tipos estrictos antes de confiar en nada de la salida.
+  if (!validarFormaSalidaAttestation(salidaCruda)) return rechazo(CODIGOS.SIGNATURE_INVALID);
+  if (salidaCruda.firmaValida !== true) return rechazo(CODIGOS.SIGNATURE_INVALID);
+
+  // Origen exacto: repo, workflow Y ref, los tres, igualdad estricta de string.
+  const { identidadOIDC } = salidaCruda;
+  if (identidadOIDC.repo !== pinOrigen.repo || identidadOIDC.workflow !== pinOrigen.workflow
+      || identidadOIDC.ref !== pinOrigen.ref) {
+    return rechazo(CODIGOS.ORIGIN_MISMATCH);
+  }
+
+  // El veredicto es AUTÉNTICO y de ORIGEN correcto. Pero `ok:true` NO autoriza
+  // por sí solo un badge: un veredicto real de un candidato que falló los SLO
+  // trae `certifica:false`. Se expone `certifica` al tope del resultado para que
+  // el generador de claims (T-10) NUNCA pueda leer `ok` aislado — el badge exige
+  // `ok === true && certifica === true`. Ver gate W4-H (32-PLAN.md).
+  return congelarProfundo({
+    ok: true,
+    certifica: sano.certifica === true,
+    verdict: sano,
+    identidadOIDC: { ...identidadOIDC },
+  });
+}
+
+module.exports = {
+  CODIGOS,
+  MAX_BUNDLE_BYTES,
+  bytesVerdictSinFirma,
+  digestVerdictSinFirma,
+  validarBundleBytes,
+  validarFormaSalidaAttestation,
+  verificarVeredicto,
+};

package/scripts/limpiar-artefactos-python.js

@@ -1,131 +1,131 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * limpiar-artefactos-python.js — limpia caché Python antes de empaquetar.
- *
- * Se ejecuta como `prepack` antes de `npm pack` y `npm publish` para evitar
- * que artefactos locales (.pyc, __pycache__/) contaminen el tarball publicado.
- *
- * Reglas de seguridad (defensa en profundidad):
- *   1. Aborta si cwd no coincide con la raíz del package.json del repo.
- *   2. Profundidad máxima de recursión: 3 niveles desde la raíz.
- *   3. Allowlist explícita de directorios a EXCLUIR de la búsqueda
- *      (node_modules, .git, temp, .planning, respositorios-git, _userland).
- *   4. Solo elimina directorios cuyo nombre coincide exactamente con el
- *      conjunto cerrado: __pycache__, .pytest_cache, .mypy_cache, .ruff_cache.
- *   5. Solo elimina archivos sueltos con extensiones .pyc, .pyo.
- *   6. En CI no-interactivo respeta el flag SWL_PREPACK_DRY=1 (no borra,
- *      solo lista).
- *
- * Exit codes:
- *   0 — OK (limpieza ejecutada o nada que limpiar)
- *   1 — error de invariante (cwd incorrecto, package.json no encontrado)
- */
-
-const fs   = require('fs');
-const path = require('path');
-
-const { NOMBRES_VALIDOS } = require('./lib/paquetes-conocidos');
-const {
-  DIRS_ARTEFACTOS_PYTHON: DIRS_A_LIMPIAR,
-  EXTS_ARTEFACTOS_PYTHON: EXTS_A_LIMPIAR,
-} = require('./lib/artefactos-python');
-
-const PROFUNDIDAD_MAX = 3;
-const DIRS_EXCLUIDOS  = new Set([
-  'node_modules', '.git', 'temp', '.planning', 'respositorios-git',
-  '_userland', 'tests', '.github',
-]);
-
-const dryRun = process.env.SWL_PREPACK_DRY === '1';
-
-function log(msg) { process.stdout.write(`[prepack] ${msg}\n`); }
-function err(msg) { process.stderr.write(`[prepack] ERROR: ${msg}\n`); }
-
-/**
- * Verifica que el cwd actual contiene el package.json del repo swl-ses.
- * Esto evita que el script borre directorios en la máquina del usuario si
- * algún día se invocara desde un cwd incorrecto (ej. dentro de un tarball
- * extraído por npm en .npm/_cacache).
- */
-function verificarRaiz() {
-  const cwd = process.cwd();
-  const pkgPath = path.join(cwd, 'package.json');
-  if (!fs.existsSync(pkgPath)) {
-    err(`no existe package.json en cwd: ${cwd}`);
-    process.exit(1);
-  }
-  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-  if (!NOMBRES_VALIDOS.includes(pkg.name)) {
-    err(`package.json en ${cwd} no corresponde a swl-ses (name: ${pkg.name}). Abortando por seguridad.`);
-    process.exit(1);
-  }
-  return cwd;
-}
-
-/**
- * Recorre el árbol desde root con profundidad limitada y elimina los
- * artefactos Python detectados. No sigue symlinks.
- */
-function limpiar(root, profundidad = 0) {
-  if (profundidad > PROFUNDIDAD_MAX) return { dirs: 0, files: 0 };
-
-  let dirsEliminados = 0;
-  let filesEliminados = 0;
-
-  let entries;
-  try {
-    entries = fs.readdirSync(root, { withFileTypes: true });
-  } catch (e) {
-    err(`no se pudo leer ${root}: ${e.message}`);
-    return { dirs: 0, files: 0 };
-  }
-
-  for (const entry of entries) {
-    if (entry.isSymbolicLink()) continue;
-    const fullPath = path.join(root, entry.name);
-
-    if (entry.isDirectory()) {
-      if (DIRS_A_LIMPIAR.has(entry.name)) {
-        if (dryRun) {
-          log(`[dry-run] borraría dir: ${path.relative(process.cwd(), fullPath)}`);
-        } else {
-          fs.rmSync(fullPath, { recursive: true, force: true });
-          log(`borrado dir: ${path.relative(process.cwd(), fullPath)}`);
-        }
-        dirsEliminados++;
-      } else if (!DIRS_EXCLUIDOS.has(entry.name) && !entry.name.startsWith('.')) {
-        const sub = limpiar(fullPath, profundidad + 1);
-        dirsEliminados  += sub.dirs;
-        filesEliminados += sub.files;
-      }
-    } else if (entry.isFile()) {
-      const ext = path.extname(entry.name).toLowerCase();
-      if (EXTS_A_LIMPIAR.has(ext)) {
-        if (dryRun) {
-          log(`[dry-run] borraría archivo: ${path.relative(process.cwd(), fullPath)}`);
-        } else {
-          fs.rmSync(fullPath, { force: true });
-        }
-        filesEliminados++;
-      }
-    }
-  }
-
-  return { dirs: dirsEliminados, files: filesEliminados };
-}
-
-function main() {
-  const root = verificarRaiz();
-  const result = limpiar(root);
-
-  if (result.dirs === 0 && result.files === 0) {
-    log('sin artefactos Python que limpiar.');
-  } else {
-    const accion = dryRun ? 'detectados' : 'eliminados';
-    log(`${accion}: ${result.dirs} directorios + ${result.files} archivos.`);
-  }
-}
-
-main();
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * limpiar-artefactos-python.js — limpia caché Python antes de empaquetar.
+ *
+ * Se ejecuta como `prepack` antes de `npm pack` y `npm publish` para evitar
+ * que artefactos locales (.pyc, __pycache__/) contaminen el tarball publicado.
+ *
+ * Reglas de seguridad (defensa en profundidad):
+ *   1. Aborta si cwd no coincide con la raíz del package.json del repo.
+ *   2. Profundidad máxima de recursión: 3 niveles desde la raíz.
+ *   3. Allowlist explícita de directorios a EXCLUIR de la búsqueda
+ *      (node_modules, .git, temp, .planning, respositorios-git, _userland).
+ *   4. Solo elimina directorios cuyo nombre coincide exactamente con el
+ *      conjunto cerrado: __pycache__, .pytest_cache, .mypy_cache, .ruff_cache.
+ *   5. Solo elimina archivos sueltos con extensiones .pyc, .pyo.
+ *   6. En CI no-interactivo respeta el flag SWL_PREPACK_DRY=1 (no borra,
+ *      solo lista).
+ *
+ * Exit codes:
+ *   0 — OK (limpieza ejecutada o nada que limpiar)
+ *   1 — error de invariante (cwd incorrecto, package.json no encontrado)
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const { NOMBRES_VALIDOS } = require('./lib/paquetes-conocidos');
+const {
+  DIRS_ARTEFACTOS_PYTHON: DIRS_A_LIMPIAR,
+  EXTS_ARTEFACTOS_PYTHON: EXTS_A_LIMPIAR,
+} = require('./lib/artefactos-python');
+
+const PROFUNDIDAD_MAX = 3;
+const DIRS_EXCLUIDOS  = new Set([
+  'node_modules', '.git', 'temp', '.planning', 'respositorios-git',
+  '_userland', 'tests', '.github',
+]);
+
+const dryRun = process.env.SWL_PREPACK_DRY === '1';
+
+function log(msg) { process.stdout.write(`[prepack] ${msg}\n`); }
+function err(msg) { process.stderr.write(`[prepack] ERROR: ${msg}\n`); }
+
+/**
+ * Verifica que el cwd actual contiene el package.json del repo swl-ses.
+ * Esto evita que el script borre directorios en la máquina del usuario si
+ * algún día se invocara desde un cwd incorrecto (ej. dentro de un tarball
+ * extraído por npm en .npm/_cacache).
+ */
+function verificarRaiz() {
+  const cwd = process.cwd();
+  const pkgPath = path.join(cwd, 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    err(`no existe package.json en cwd: ${cwd}`);
+    process.exit(1);
+  }
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  if (!NOMBRES_VALIDOS.includes(pkg.name)) {
+    err(`package.json en ${cwd} no corresponde a swl-ses (name: ${pkg.name}). Abortando por seguridad.`);
+    process.exit(1);
+  }
+  return cwd;
+}
+
+/**
+ * Recorre el árbol desde root con profundidad limitada y elimina los
+ * artefactos Python detectados. No sigue symlinks.
+ */
+function limpiar(root, profundidad = 0) {
+  if (profundidad > PROFUNDIDAD_MAX) return { dirs: 0, files: 0 };
+
+  let dirsEliminados = 0;
+  let filesEliminados = 0;
+
+  let entries;
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch (e) {
+    err(`no se pudo leer ${root}: ${e.message}`);
+    return { dirs: 0, files: 0 };
+  }
+
+  for (const entry of entries) {
+    if (entry.isSymbolicLink()) continue;
+    const fullPath = path.join(root, entry.name);
+
+    if (entry.isDirectory()) {
+      if (DIRS_A_LIMPIAR.has(entry.name)) {
+        if (dryRun) {
+          log(`[dry-run] borraría dir: ${path.relative(process.cwd(), fullPath)}`);
+        } else {
+          fs.rmSync(fullPath, { recursive: true, force: true });
+          log(`borrado dir: ${path.relative(process.cwd(), fullPath)}`);
+        }
+        dirsEliminados++;
+      } else if (!DIRS_EXCLUIDOS.has(entry.name) && !entry.name.startsWith('.')) {
+        const sub = limpiar(fullPath, profundidad + 1);
+        dirsEliminados  += sub.dirs;
+        filesEliminados += sub.files;
+      }
+    } else if (entry.isFile()) {
+      const ext = path.extname(entry.name).toLowerCase();
+      if (EXTS_A_LIMPIAR.has(ext)) {
+        if (dryRun) {
+          log(`[dry-run] borraría archivo: ${path.relative(process.cwd(), fullPath)}`);
+        } else {
+          fs.rmSync(fullPath, { force: true });
+        }
+        filesEliminados++;
+      }
+    }
+  }
+
+  return { dirs: dirsEliminados, files: filesEliminados };
+}
+
+function main() {
+  const root = verificarRaiz();
+  const result = limpiar(root);
+
+  if (result.dirs === 0 && result.files === 0) {
+    log('sin artefactos Python que limpiar.');
+  } else {
+    const accion = dryRun ? 'detectados' : 'eliminados';
+    log(`${accion}: ${result.dirs} directorios + ${result.files} archivos.`);
+  }
+}
+
+main();