@devlas/dte-sii 2.12.26 → 2.13.0

package/utils/httpDebug.js

@@ -0,0 +1,223 @@
+// Copyright (c) 2026 Devlas SpA — https://devlas.cl
+// Licencia MIT. Ver archivo LICENSE para mas detalles.
+/**
+ * httpDebug.js — Registro de TODAS las llamadas HTTP al portal del SII.
+ *
+ * Motivación real: depurando una certificación hubo cinco minutos de pantalla
+ * congelada sin ninguna forma de saber qué estaba pasando. La causa era una
+ * consulta que dispara cuatro requests secuenciales al portal, ninguno de los
+ * cuales dejaba rastro. De 26 llamadas en `SiiCertificacion` solo 5 se guardaban,
+ * y de las 14 de `SiiPortalAuth`, ninguna.
+ *
+ * Este módulo es el único punto donde se decide qué se guarda y cómo. Se engancha
+ * en los dos clientes HTTP de la librería (son independientes: `SiiSession` usa
+ * `got` y `SiiPortalAuth` usa `https` nativo, sin código en común).
+ *
+ * ── Está apagado por defecto ──────────────────────────────────────────────────
+ * Solo actúa si el consumidor define `SII_HTTP_DEBUG_DIR`. Sin esa variable, el
+ * costo es una comparación por request y nada más.
+ *
+ * ── Nunca rompe la operación real ─────────────────────────────────────────────
+ * Todo va dentro de try/catch. Un fallo al escribir el diagnóstico jamás puede
+ * tumbar un envío al SII.
+ *
+ * @module dte-sii/utils/httpDebug
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** Tope por archivo. Una respuesta del portal ronda los 50 KB; 512 KB cubre casos raros sin llenar el disco. */
+const MAX_BYTES = 512 * 1024;
+
+/** Contador por directorio: numera las llamadas para que el orden cronológico se lea en el nombre. */
+const _contadores = new Map();
+
+/**
+ * Cabeceras que nunca se escriben en claro.
+ * `set-cookie` y `cookie` llevan la sesión viva del SII (~90 min de validez): quedaría
+ * una credencial usable en disco. `authorization` por el mismo motivo.
+ */
+const HEADERS_SENSIBLES = new Set(['set-cookie', 'cookie', 'authorization', 'proxy-authorization']);
+
+/** Marcador único, para poder grepear qué se redactó. */
+const REDACTADO = '[REDACTADO-POR-httpDebug]';
+
+/**
+ * Redacta secretos del cuerpo de una respuesta.
+ *
+ * `<RSASK>` es la llave privada RSA que el SII entrega dentro del CAF: si se guarda
+ * en claro, cualquiera con acceso al disco puede timbrar documentos con esos folios.
+ * Hoy se escribe sin protección en varios puntos de la librería; acá al menos no se
+ * amplifica el problema.
+ */
+function redactarCuerpo(texto) {
+  if (!texto) return texto;
+  return String(texto)
+    .replace(/<RSASK>[\s\S]*?<\/RSASK>/gi, `<RSASK>${REDACTADO}</RSASK>`)
+    .replace(/-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?-----END [^-]*PRIVATE KEY-----/gi, REDACTADO);
+}
+
+/** Devuelve una copia de los headers con los sensibles redactados. */
+function redactarHeaders(headers) {
+  const salida = {};
+  for (const [k, v] of Object.entries(headers || {})) {
+    salida[k] = HEADERS_SENSIBLES.has(k.toLowerCase()) ? REDACTADO : v;
+  }
+  return salida;
+}
+
+/** Convierte una URL en un fragmento corto y legible para el nombre de archivo. */
+function _slugDesdeUrl(urlStr) {
+  try {
+    const { pathname } = new URL(urlStr);
+    const ultimo = pathname.split('/').filter(Boolean).pop() || 'raiz';
+    return ultimo.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 48);
+  } catch {
+    return 'url-invalida';
+  }
+}
+
+function _siguienteNumero(dir) {
+  const n = (_contadores.get(dir) || 0) + 1;
+  _contadores.set(dir, n);
+  return String(n).padStart(3, '0');
+}
+
+/**
+ * ¿Está activa la captura? Se lee en cada llamada a propósito: el consumidor puede
+ * definir la variable por corrida (un directorio distinto por etapa).
+ * @returns {string|null} Directorio destino, o null si está apagada.
+ */
+function dirActivo() {
+  return process.env.SII_HTTP_DEBUG_DIR || null;
+}
+
+/**
+ * Registra una llamada HTTP. Best-effort: nunca lanza.
+ *
+ * Escribe dos cosas:
+ *  - `NNN-METODO-recurso-STATUS.html` con el cuerpo de la respuesta.
+ *  - Una línea en `index.jsonl` con los metadatos, para poder revisar una corrida
+ *    entera de un vistazo (`jq`, `grep`) sin abrir cada archivo.
+ *
+ * @param {Object} info
+ * @param {string} info.url
+ * @param {string} [info.method='GET']
+ * @param {number} [info.status]
+ * @param {Object} [info.headers] - Cabeceras de respuesta (se redactan).
+ * @param {string} [info.body] - Cuerpo de respuesta (se redacta).
+ * @param {string} [info.reqBody] - Cuerpo enviado (form POST). Se redacta igual.
+ * @param {number} [info.ms] - Duración.
+ * @param {string} [info.cliente] - Qué cliente HTTP lo emitió, para saber de dónde vino.
+ */
+function registrarHttpDebug(info = {}) {
+  const dir = dirActivo();
+  if (!dir) return;
+
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+
+    const { url = '', method = 'GET', status = 0, headers, body, reqBody, ms, cliente } = info;
+    const n = _siguienteNumero(dir);
+    const nombre = `${n}-${method.toUpperCase()}-${_slugDesdeUrl(url)}-${status}.html`;
+
+    let cuerpo = redactarCuerpo(body) ?? '';
+    let truncado = false;
+    if (Buffer.byteLength(cuerpo, 'utf-8') > MAX_BYTES) {
+      cuerpo = cuerpo.slice(0, MAX_BYTES) + `\n\n${REDACTADO} — truncado en ${MAX_BYTES} bytes`;
+      truncado = true;
+    }
+
+    // El cuerpo enviado importa tanto como la respuesta: cuando el SII rechaza un
+    // envío, la causa está en el XML que se le mandó. Si es corto va inline en el
+    // comentario; si no, a un archivo aparte para no volver ilegible el principal.
+    const reqTexto = reqBody ? redactarCuerpo(String(reqBody)) : '';
+    let archivoReq = null;
+    if (reqTexto.length > 2000) {
+      archivoReq = nombre.replace(/\.html$/, '-request.txt');
+      const recortado = Buffer.byteLength(reqTexto, 'utf-8') > MAX_BYTES
+        ? reqTexto.slice(0, MAX_BYTES) + `\n\n${REDACTADO} — truncado en ${MAX_BYTES} bytes`
+        : reqTexto;
+      fs.writeFileSync(path.join(dir, archivoReq), recortado, 'utf-8');
+    }
+
+    // Encabezado legible dentro del propio archivo: al abrir uno suelto se entiende
+    // a qué llamada corresponde sin tener que cruzarlo con el índice.
+    const cabecera = [
+      '<!--',
+      `  ${method.toUpperCase()} ${url}`,
+      `  status: ${status}${ms != null ? `  |  ${ms} ms` : ''}${cliente ? `  |  cliente: ${cliente}` : ''}`,
+      `  fecha: ${new Date().toISOString()}`,
+      archivoReq ? `  request body: ${archivoReq}` : null,
+      reqTexto && !archivoReq ? `  request body: ${reqTexto}` : null,
+      '-->',
+      '',
+    ].filter(Boolean).join('\n');
+
+    fs.writeFileSync(path.join(dir, nombre), cabecera + cuerpo, 'utf-8');
+
+    fs.appendFileSync(
+      path.join(dir, 'index.jsonl'),
+      JSON.stringify({
+        n,
+        ts: new Date().toISOString(),
+        method: method.toUpperCase(),
+        url,
+        status,
+        ms: ms ?? null,
+        cliente: cliente ?? null,
+        bytes: Buffer.byteLength(String(body ?? ''), 'utf-8'),
+        truncado,
+        archivo: nombre,
+        archivoRequest: archivoReq,
+        headers: redactarHeaders(headers),
+      }) + '\n',
+      'utf-8',
+    );
+  } catch (_e) {
+    // El diagnóstico jamás puede romper la operación real contra el SII.
+  }
+}
+
+/**
+ * `fetch` que ademas deja el intercambio en el debug HTTP.
+ *
+ * Devuelve el texto ya leido porque el cuerpo de un Response se consume una sola vez:
+ * si el debug lo leyera por su cuenta, el llamador se quedaria sin cuerpo.
+ *
+ * @param {string} url
+ * @param {Object} [opciones] - Igual que las de `fetch`.
+ * @param {string} [cliente] - Quien hizo la llamada, para ubicarla en el indice.
+ * @returns {Promise<{ response: Response, text: string }>}
+ */
+async function fetchRegistrado(url, opciones = {}, cliente = undefined) {
+  const t0 = Date.now();
+  const response = await fetch(url, opciones);
+  const text = await response.text();
+  // Con el debug apagado se sale acá, ANTES de tocar nada de la respuesta. Estas llamadas
+  // están en el camino de emisión real (EnviadorSII, WsReclamo): recorrer los headers para
+  // después descartarlos sería trabajo y superficie de fallo en producción a cambio de nada.
+  if (!dirActivo()) return { response, text };
+  registrarHttpDebug({
+    url,
+    method: opciones.method || 'GET',
+    status: response.status,
+    headers: Object.fromEntries(response.headers),
+    body: text,
+    reqBody: opciones.body,
+    ms: Date.now() - t0,
+    cliente,
+  });
+  return { response, text };
+}
+
+module.exports = {
+  registrarHttpDebug,
+  fetchRegistrado,
+  redactarCuerpo,
+  redactarHeaders,
+  dirActivo,
+  REDACTADO,
+  MAX_BYTES,
+};

package/utils/index.js

@@ -52,6 +52,7 @@ const {
 // Sanitización
 const {
   sanitizeSiiText,
+  sanitizeTedText,
   truncateText,
   sanitizeGiroRecep,
   sanitizeRazonSocial,
@@ -176,6 +177,7 @@ module.exports = {
   // Sanitización
   // ─────────────────────────────────────────
   sanitizeSiiText,
+  sanitizeTedText,
   truncateText,
   sanitizeGiroRecep,
   sanitizeRazonSocial,

package/utils/paths.js

@@ -0,0 +1,152 @@
+// Copyright (c) 2026 Devlas SpA — https://devlas.cl
+// Licencia MIT. Ver archivo LICENSE para mas detalles.
+/**
+ * paths.js — Resolución centralizada de los directorios donde escribe la librería.
+ *
+ * REGLA DE FRONTERA: esta librería es un paquete público y **no conoce a sus
+ * consumidores**. Nunca debe adivinar dónde escribir ni asumir un layout de
+ * directorios, un sistema operativo o el nombre de un proyecto que la usa.
+ * El directorio siempre lo inyecta quien la consume: por parámetro (preferido)
+ * o por variable de entorno.
+ *
+ * Antes de este módulo convivían cinco convenciones distintas —`process.cwd()`,
+ * `__dirname/../..`, rutas relativas, una ruta con el nombre de un repo consumidor
+ * y una ruta de `AppData` de Windows— lo que hacía imposible saber dónde iba a
+ * quedar un archivo de diagnóstico.
+ *
+ * @module dte-sii/utils/paths
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+/**
+ * Directorio para archivos de diagnóstico (HTML del portal, XML, dumps).
+ *
+ * Orden de resolución: el que inyecta el consumidor → `SII_DEBUG_DIR` → `null`.
+ * Devolver `null` es una respuesta válida y significa **no escribir nada**: el
+ * diagnóstico es opcional y jamás debe crear directorios en ubicaciones que el
+ * consumidor no eligió.
+ *
+ * @param {string} [dirInyectado] - Directorio provisto por el consumidor.
+ * @returns {string|null} Ruta absoluta, o null si nadie definió dónde escribir.
+ */
+function resolveDebugDir(dirInyectado) {
+  const dir = dirInyectado || process.env.SII_DEBUG_DIR || null;
+  return dir ? path.resolve(dir) : null;
+}
+
+/**
+ * Directorio para datos que deben sobrevivir entre ejecuciones (caché de sesión
+ * SII, por ejemplo).
+ *
+ * A diferencia del debug, acá sí hay un fallback: perder la caché de sesión
+ * dispara el error "máximo de sesiones autenticadas" del SII, así que conviene
+ * escribir en algún lado antes que en ninguno. El fallback es `os.tmpdir()`,
+ * que es neutral respecto del sistema operativo.
+ *
+ * ⚠️ En un contenedor con filesystem efímero, `DATADIR` debe apuntar a un volumen
+ * persistente o la caché se pierde en cada redeploy.
+ *
+ * @param {string} [dirInyectado] - Directorio provisto por el consumidor.
+ * @returns {string} Ruta absoluta (siempre devuelve algo).
+ */
+function resolveDataDir(dirInyectado) {
+  return path.resolve(dirInyectado || process.env.DATADIR || path.join(os.tmpdir(), 'dte-sii'));
+}
+
+/**
+ * Directorio para **artefactos funcionales**: archivos que la propia librería vuelve
+ * a leer después (`estructuras.json`, `session.json`, `periodo-libros.json`, CAFs).
+ *
+ * Se distingue de `resolveDebugDir` porque acá no se puede devolver `null`: si no
+ * hay dónde escribir, el flujo se rompe más adelante al intentar leerlos. Por eso
+ * hay fallback, pero neutral (`resolveDataDir`) en vez de las adivinanzas que había
+ * antes — `process.cwd()` (depende de desde dónde se lanzó el proceso) y
+ * `__dirname/../..` (que en una instalación normal apunta dentro de `node_modules`).
+ *
+ * @param {string} [dirInyectado] - Directorio provisto por el consumidor.
+ * @param {string} [subdir] - Subdirectorio opcional bajo el base resuelto.
+ * @returns {string} Ruta absoluta (siempre devuelve algo).
+ */
+function resolveArtifactDir(dirInyectado, subdir = '') {
+  const base = path.resolve(
+    dirInyectado || process.env.SII_DEBUG_DIR || path.join(resolveDataDir(), 'debug'),
+  );
+  return subdir ? path.join(base, subdir) : base;
+}
+
+/**
+ * Escribe un archivo de diagnóstico. Best-effort: si no hay directorio definido
+ * o falla la escritura, no hace nada y **nunca lanza** — el diagnóstico no puede
+ * tumbar una operación real contra el SII.
+ *
+ * @param {string|null} dir - Directorio ya resuelto (ver resolveDebugDir).
+ * @param {string} filename - Nombre del archivo.
+ * @param {string|Buffer} content - Contenido.
+ * @returns {string|null} Ruta escrita, o null si no se escribió.
+ */
+function saveDebugFile(dir, filename, content) {
+  if (!dir) return null;
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = path.join(dir, filename);
+    fs.writeFileSync(filePath, content ?? '', 'utf-8');
+    return filePath;
+  } catch (_e) {
+    return null;
+  }
+}
+
+/** Stamp de tiempo apto para nombres de archivo y directorio. Convención ya usada en todo el repo. */
+function runStamp(date = new Date()) {
+  return date.toISOString().replace(/[:.]/g, '-');
+}
+
+/** Normaliza un RUT para usarlo como nombre de directorio: sin puntos, en mayúsculas. */
+function rutSlug(rut) {
+  return String(rut || 'sin-rut').replace(/\./g, '').trim().toUpperCase();
+}
+
+/**
+ * Directorio de UNA ejecución, clasificado para poder encontrarlo después.
+ *
+ *     {base}/{RUT}/{YYYY-MM-DD}/{HH-MM-SS}_{operacion}/
+ *
+ * Tres niveles con un porqué cada uno:
+ *  - **RUT** primero: al depurar siempre se parte de "qué contribuyente".
+ *  - **Fecha** después: agrupa el día completo; es el filtro natural cuando el
+ *    usuario dice "esto pasó ayer" y hay muchas corridas acumuladas.
+ *  - **Hora + operación**: dentro del día, las corridas quedan ordenadas
+ *    cronológicamente por nombre y se lee de un vistazo qué hizo cada una
+ *    (`14-32-07_generar-sets`) sin tener que abrirlas.
+ *
+ * Reemplaza cinco layouts distintos que convivían (`debug/auto-caf/{RUT}/{stamp}/{tipo}`,
+ * `debug/cert-v2/{rut}/{stamp}`, `debug/caf/{ambiente}/{RUT}/...`, archivos sueltos en
+ * la raíz de `debug/cert-v2`, y rutas relativas al cwd).
+ *
+ * @param {Object} opts
+ * @param {string} [opts.baseDir] - Base inyectada por el consumidor.
+ * @param {string} opts.rut - RUT del contribuyente.
+ * @param {string} opts.operacion - Qué se está ejecutando (ej. 'generar-sets', 'caf-39').
+ * @param {Date} [opts.date] - Momento de la corrida (default: ahora).
+ * @returns {string} Ruta absoluta del directorio de la corrida.
+ */
+function resolveRunDir({ baseDir, rut, operacion, date = new Date() }) {
+  const iso = date.toISOString();               // 2026-08-11T22:46:35.123Z
+  const fecha = iso.slice(0, 10);               // 2026-08-11
+  const hora = iso.slice(11, 19).replace(/:/g, '-'); // 22-46-35
+  const nombre = operacion ? `${hora}_${operacion}` : hora;
+  return path.join(resolveArtifactDir(baseDir), rutSlug(rut), fecha, nombre);
+}
+
+module.exports = {
+  resolveDebugDir,
+  resolveDataDir,
+  resolveArtifactDir,
+  resolveRunDir,
+  saveDebugFile,
+  runStamp,
+  rutSlug,
+};

package/utils/sanitize.js

@@ -40,6 +40,53 @@ function sanitizeSiiText(text) {
     .trim();
 }
 
+/**
+ * Sanitizar texto que va DENTRO del TED (timbre electrónico).
+ *
+ * Además de lo que hace `sanitizeSiiText`, pliega los acentuados de Latin-1 a ASCII
+ * (á→a, ñ→n, Ü→U…).
+ *
+ * ⚠️ Esto NO es cosmético y no se puede omitir: **el lector de PDF417 del SII no
+ * devuelve los bytes ≥ 128 tal como se codificaron**. Medido contra el portal de
+ * Muestras Impresas el 11/08/2026 — el SII leyó del código de barras:
+ *
+ *     "Cajón AFECTO"    ->  "Cajnn AFECTO"
+ *     "Pañuelo AFECTO"  ->  "Pauuelo AFECTO"
+ *     "CIGUEÑALES"      ->  "CIGUEAALES"
+ *
+ * (el carácter acentuado se pierde y el siguiente se duplica). Como el TED viaja
+ * firmado, el SII verifica la firma sobre lo que ÉL leyó, no sobre lo que se codificó:
+ * cualquier documento con tilde o ñ en RSR o IT1 termina rechazado con
+ * "Error Tecnico: TED - Firma invalida", y basta uno para tumbar la revisión completa.
+ *
+ * Se descartó que fuera un problema nuestro de codificación: se verificó que la firma
+ * es válida sobre los bytes latin1, que el TED del envío y el del DTE son idénticos, y
+ * que bwip-js codifica el byte correctamente — el barcode generado con `binarytext`
+ * resultó idéntico al generado escapando el byte a mano (`^243` con `parse`).
+ *
+ * Solo aplica al TED. El DTE conserva el texto real con sus acentos: acá se pliega
+ * únicamente lo que va al código de barras, y se hace ANTES de firmar para que la
+ * firma cubra exactamente los bytes que el SII va a leer.
+ *
+ * @param {string} text - Texto a sanitizar (RSR o IT1 del TED)
+ * @returns {string} - Texto sin caracteres fuera de ASCII
+ */
+function sanitizeTedText(text) {
+  return sanitizeSiiText(text)
+    // Descompone en letra base + diacrítico y descarta el diacrítico.
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    // Lo que NFD no separa (ligaduras y símbolos con forma propia).
+    .replace(/[fffifl]/g, m => ({ 'ff': 'ff', 'fi': 'fi', 'fl': 'fl' })[m])
+    .replace(/Æ/g, 'AE').replace(/æ/g, 'ae')
+    .replace(/Ø/g, 'O').replace(/ø/g, 'o')
+    .replace(/Ð/g, 'D').replace(/ð/g, 'd')
+    .replace(/Þ/g, 'TH').replace(/þ/g, 'th')
+    .replace(/ß/g, 'ss')
+    // Red de seguridad: cualquier resto no-ASCII se elimina antes del barcode.
+    .replace(/[^\x20-\x7E]/g, '');
+}
+
 /**
  * Truncar texto a longitud máxima (preservando palabras completas si es posible)
  * 
@@ -127,6 +174,7 @@ function safeSegment(value, fallback = 'sin-valor') {
 
 module.exports = {
   sanitizeSiiText,
+  sanitizeTedText,
   truncateText,
   sanitizeGiroRecep,
   sanitizeRazonSocial,

package/utils/xml.js

@@ -10,6 +10,7 @@
 
 const { XMLParser, XMLBuilder } = require('fast-xml-parser');
 const { safeSegment } = require('./sanitize');
+const { resolveDataDir } = require('./paths');
 
 // ============================================
 // PARSERS SINGLETON (evita múltiples instancias)
@@ -276,8 +277,9 @@ function saveEnvioArtifacts({
     const tipoDte = meta.items.length === 1 ? meta.items[0]?.tipoDTE : 'multiple';
     const folio = meta.items.length === 1 ? meta.items[0]?.folio : null;
 
-    // Usar baseDir si se proporciona, sino raíz de static/nodejs como fallback
-    const effectiveBase = baseDir || path.resolve(__dirname, '..', '..', '..');
+    // El fallback era `__dirname/../../..`, una ruta que solo tenía sentido con un
+    // layout de directorios concreto del consumidor original.
+    const effectiveBase = baseDir || resolveDataDir();
     const historicoBaseDir = path.join(effectiveBase, 'historicos');
     const rutDir = safeSegment(meta.rutEmisor || 'sin-rut');
     const tipoDir = safeSegment(`dte-${tipoDte || 'sin-tipo'}`);