impulso 0.22.0 → 0.24.0

package/shared/telematics.cjs

@@ -0,0 +1,444 @@
+'use strict';
+// impulso — shared secure telematics writer
+//
+// NDJSON append-only event log. Config is loaded once from
+// <home>/config.json. All emit failures are silent —
+// telematics must never throw or disrupt the harness.
+//
+// Interfaces:
+//   loadTelematicsConfig(home, _fs?) -> { enabled, sensitiveKeys }
+//   redact(value, sensitiveKeys) -> redacted copy
+//   sanitizeId(raw) -> string
+//   createTelematics({ harness, sessionId, processId, cwd, home,
+//                      now, uuid, fs })
+//     -> { enabled, sessionId, emit(eventType, payload), close() }
+
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+// ----------------------------------------------------------------
+// BUILTIN_SENSITIVE_KEYS — always active, case-insensitive.
+// Matches common credential / token / secret key names across
+// providers. Supplemented by config telematics.sensitiveKeys.
+// ----------------------------------------------------------------
+const BUILTIN_SENSITIVE_KEYS = [
+  'apiKey',
+  'api_key',
+  'authorization',
+  'token',
+  'accessToken',
+  'refreshToken',
+  'secret',
+  'password',
+  'passwd',
+  'credential',
+  'cookie',
+  'set-cookie',
+  'privateKey',
+  'clientSecret',
+];
+
+// ----------------------------------------------------------------
+// Pattern-based redaction. Applied to string values during walk.
+// ----------------------------------------------------------------
+const PATTERN_REDACTIONS = [
+  // Bearer tokens: "Bearer eyJ..." -> "Bearer [REDACTED]"
+  { pattern: /\bBearer\s+([^\s"',;)}\]]+)/gi, replace: 'Bearer [REDACTED]' },
+  // OpenAI / similar sk- keys: sk-<40+ chars>
+  { pattern: /\bsk-[a-zA-Z0-9_-]{20,}\b/g, replace: '[REDACTED_SK_KEY]' },
+  // GitHub classic tokens: ghp_xxx, gho_xxx, ghu_xxx, ghs_xxx, ghr_xxx
+  { pattern: /\bgh[pousr]_[a-zA-Z0-9]{36,}\b/g, replace: '[REDACTED_GH_TOKEN]' },
+  // AWS access key IDs: AKIA... (20 uppercase alphanumeric)
+  { pattern: /\bAKIA[A-Z0-9]{16}\b/g, replace: '[REDACTED_AWS_KEY]' },
+  // PEM private key blocks (detect header line)
+  {
+    pattern:
+      /-----BEGIN (?:RSA |EC |DSA |OPENSSH |ENCRYPTED )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |DSA |OPENSSH |ENCRYPTED )?PRIVATE KEY-----/g,
+    replace: '[REDACTED_PEM]',
+  },
+];
+
+// ----------------------------------------------------------------
+// loadTelematicsConfig
+//
+// Reads <home>/config.json. Returns { enabled, sensitiveKeys }.
+// Missing file, malformed JSON, absent telematics key,
+// telematics.enabled !== true → disabled.
+// telematics.sensitiveKeys: string array or absent.
+// Unknown keys ignored. Never writes or repairs config.
+// ----------------------------------------------------------------
+function loadTelematicsConfig(homeDir, _fs, _path) {
+  const fs = _fs || require('node:fs');
+  const p = _path || path;
+  const configPath = p.join(homeDir, 'config.json');
+  try {
+    if (!fs.existsSync(configPath)) {
+      return { enabled: false, sensitiveKeys: [] };
+    }
+    const raw = fs.readFileSync(configPath, 'utf8');
+    const cfg = JSON.parse(raw);
+    if (!cfg || typeof cfg !== 'object') {
+      return { enabled: false, sensitiveKeys: [] };
+    }
+    const telematics = cfg.telematics;
+    if (!telematics || typeof telematics !== 'object') {
+      return { enabled: false, sensitiveKeys: [] };
+    }
+    if (telematics.enabled !== true) {
+      return { enabled: false, sensitiveKeys: [] };
+    }
+    // Parse sensitiveKeys: optional array of nonempty strings
+    let extra = [];
+    if (Array.isArray(telematics.sensitiveKeys)) {
+      extra = telematics.sensitiveKeys
+        .filter(function (k) {
+          return typeof k === 'string' && k.length > 0;
+        })
+        .map(function (k) {
+          return k.toLowerCase();
+        });
+    }
+    return { enabled: true, sensitiveKeys: extra };
+  } catch (_) {
+    return { enabled: false, sensitiveKeys: [] };
+  }
+}
+
+// ----------------------------------------------------------------
+// sanitizeId
+//
+// Trims whitespace and strips everything except [A-Za-z0-9._-].
+// Rejects `.`, `..`, and empty results to prevent path traversal
+// when the ID is used as a directory name in path.join.
+// Returns empty string when input is null/undefined or result is
+// empty/rejected after filtering.
+// ----------------------------------------------------------------
+function sanitizeId(raw) {
+  if (raw == null || typeof raw !== 'string') return '';
+  const cleaned = raw.trim().replace(/[^A-Za-z0-9._-]/g, '');
+  // Reject dot, dot-dot, and empty — these cause path.join traversal
+  if (cleaned === '.' || cleaned === '..' || cleaned.length === 0) return '';
+  return cleaned;
+}
+
+// ----------------------------------------------------------------
+// redact
+//
+// Deep-walks value without mutation.
+// 1. Key name matching (case-insensitive) → "[REDACTED]", no descent.
+// 2. String pattern scanning for secrets (Bearer, sk-, GitHub, AWS, PEM).
+// 3. key=value pairs: if key matches sensitive set, redact value.
+// 4. JSON/query strings: URL query-style &key=value redaction.
+// 5. Cycles, unsupported values, getters/proxies →
+//    "[UNSERIALIZABLE]"; never throws.
+//
+// Returns a redacted deep copy.
+// ----------------------------------------------------------------
+function redact(value, sensitiveKeys) {
+  // Built-ins always apply. Configured keys are additive.
+  const extraLen = Array.isArray(sensitiveKeys) ? sensitiveKeys.length : 0;
+
+  const keySet = new Set();
+  for (let i = 0; i < BUILTIN_SENSITIVE_KEYS.length; i++) {
+    keySet.add(BUILTIN_SENSITIVE_KEYS[i].toLowerCase());
+  }
+  for (let j = 0; j < extraLen; j++) {
+    keySet.add(String(sensitiveKeys[j]).toLowerCase());
+  }
+
+  const seen = new WeakSet(); // cycle detection
+
+  function walk(v, depth) {
+    if (depth === undefined) depth = 0;
+    if (depth > 100) return '[UNSERIALIZABLE]'; // depth guard
+    if (v === null || v === undefined) return v;
+    if (typeof v !== 'object') {
+      if (typeof v === 'string') {
+        return redactString(v, keySet);
+      }
+      return v;
+    }
+
+    // Cycle / unsupported check
+    if (typeof v === 'object') {
+      try {
+        // Detect getters/proxies by attempting key enumeration
+        Object.keys(v);
+      } catch (_) {
+        return '[UNSERIALIZABLE]';
+      }
+      try {
+        if (seen.has(v)) return '[UNSERIALIZABLE]';
+        seen.add(v);
+      } catch (_) {
+        return '[UNSERIALIZABLE]';
+      }
+    }
+
+    if (Array.isArray(v)) {
+      const arrOut = [];
+      for (let ai = 0; ai < v.length; ai++) {
+        try {
+          arrOut.push(walk(v[ai], depth + 1));
+        } catch (_) {
+          arrOut.push('[UNSERIALIZABLE]');
+        }
+      }
+      return arrOut;
+    }
+
+    // Object
+    const out = {};
+    let keys;
+    try {
+      keys = Object.keys(v);
+    } catch (_) {
+      return '[UNSERIALIZABLE]';
+    }
+    for (let ki = 0; ki < keys.length; ki++) {
+      const k = keys[ki];
+      const klower = String(k).toLowerCase();
+      try {
+        if (keySet.has(klower)) {
+          out[k] = '[REDACTED]';
+        } else {
+          out[k] = walk(v[k], depth + 1);
+        }
+      } catch (_) {
+        out[k] = '[UNSERIALIZABLE]';
+      }
+    }
+    return out;
+  }
+
+  return walk(value);
+}
+
+// ----------------------------------------------------------------
+// redactString — apply pattern redactions to string values
+// ----------------------------------------------------------------
+function redactString(str, keySet) {
+  let result = str;
+  for (let i = 0; i < PATTERN_REDACTIONS.length; i++) {
+    result = result.replace(PATTERN_REDACTIONS[i].pattern, PATTERN_REDACTIONS[i].replace);
+  }
+
+  // Redact key=value pairs where key matches sensitive set.
+  // Matches sequences like: key=value, key="value", key='value'
+  // in URLs, headers, JSON-embedded query strings.
+  const eqPattern = /([\w.-]+)\s*=\s*("[^"]*"|'[^']*'|[^\s&;,}'"\]]+)/gi;
+  result = result.replace(eqPattern, function (_match, key, _value) {
+    const lower = key.toLowerCase();
+    if (keySet.has(lower)) {
+      return key + '=[REDACTED]';
+    }
+    return _match;
+  });
+
+  return result;
+}
+
+// ----------------------------------------------------------------
+// createTelematics
+//
+// Factory. Loads config exactly once during construction. Returns
+// a telematics instance:
+//
+//   .enabled    boolean — false when config absent/disabled
+//   .sessionId  string | null — sanitised session id (null when disabled)
+//   .emit(eventType, payload)   writes a single NDJSON envelope; never throws
+//   .close()    closes the underlying fd; never throws
+//
+// Envelope keys per spec:
+//   schemaVersion  — integer 1
+//   eventId        — UUID per event
+//   eventType      — string
+//   timestamp      — UTC ISO-8601
+//   monotonicMs    — ms since construction
+//   harness        — "claude" | "opencode"
+//   sessionId      — sanitised session id
+//   processId      — numeric PID
+//   cwd            — current working directory
+//   payload        — redacted event payload
+// ----------------------------------------------------------------
+function createTelematics(deps) {
+  const harness = deps.harness;
+  const sessionId = deps.sessionId;
+  const processId = deps.processId;
+  const cwd = deps.cwd;
+  const home = deps.home;
+  const now = deps.now;
+  const uuidFn = deps.uuid;
+  const fs = deps.fs;
+
+  // One-time config load
+  const cfg = loadTelematicsConfig(home, fs, path);
+
+  if (!cfg.enabled) {
+    return {
+      enabled: false,
+      sessionId: null,
+      emit: function () {
+        /* noop */
+      },
+      close: function () {
+        /* noop */
+      },
+    };
+  }
+
+  // Build effective sensitive key set
+  const sensitiveKeys = [];
+  for (let i = 0; i < BUILTIN_SENSITIVE_KEYS.length; i++) {
+    if (sensitiveKeys.indexOf(BUILTIN_SENSITIVE_KEYS[i].toLowerCase()) === -1) {
+      sensitiveKeys.push(BUILTIN_SENSITIVE_KEYS[i].toLowerCase());
+    }
+  }
+  if (Array.isArray(cfg.sensitiveKeys)) {
+    for (let j = 0; j < cfg.sensitiveKeys.length; j++) {
+      const ek = String(cfg.sensitiveKeys[j]).toLowerCase();
+      if (sensitiveKeys.indexOf(ek) === -1) {
+        sensitiveKeys.push(ek);
+      }
+    }
+  }
+
+  // Sanitize sessionId or generate one
+  let sid = sanitizeId(sessionId);
+  if (!sid) {
+    if (typeof uuidFn === 'function') {
+      sid = sanitizeId(String(uuidFn()));
+    }
+    if (!sid) {
+      sid = 'gen-' + Date.now() + '-' + Math.random().toString(36).slice(2, 10);
+      sid = sanitizeId(sid);
+    }
+  }
+  if (!sid) {
+    sid = 'gen-' + Date.now();
+  }
+
+  // Construction timestamp for monotonicMs baseline
+  const startMs = Date.now();
+
+  // Log directory: <home>/logs/<sanitized-session-id>/
+  const logDir = path.join(home, 'logs', sid);
+  const logFile = path.join(logDir, 'events.ndjson');
+
+  let fd = null;
+  let ensured = false;
+
+  // ----------------------------------------------------------------
+  // ensureLogDir — create dir mode 0700, open file mode 0600
+  // Refuses symlinks, nonregular files, and paths that resolve
+  // outside <home>/logs/. Fails closed: if we can't secure it,
+  // telemetry stays disabled for the process (emit becomes noop
+  // after failed ensure).
+  // ----------------------------------------------------------------
+  function ensureLogDir() {
+    if (ensured) return fd !== null;
+    ensured = true;
+    try {
+      // Resolve logDir and verify it stays under <home>/logs/
+      const resolved = path.resolve(logDir);
+      const logsPrefix = path.resolve(home, 'logs') + path.sep;
+      if (!resolved.startsWith(logsPrefix)) {
+        return false; // path escaped the logs sandbox — fail closed
+      }
+
+      // Create log directory chain with 0700
+      fs.mkdirSync(logDir, { recursive: true, mode: 0o700 });
+      // Explicit chmod to counter umask
+      fs.chmodSync(logDir, 0o700);
+
+      // Check if log file exists and is regular + not symlink
+      let stat;
+      let exists = false;
+      try {
+        stat = fs.lstatSync(logFile);
+        exists = true;
+      } catch (_) {
+        /* file does not exist — ok */
+      }
+
+      if (exists) {
+        // Refuse nonregular targets or symlinks
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+          return false; // fail closed
+        }
+        // Chmod existing file before use
+        fs.chmodSync(logFile, 0o600);
+      }
+
+      // Open for append
+      fd = fs.openSync(logFile, 'a', 0o600);
+      // Chmod again after open (best-effort)
+      try {
+        fs.fchmodSync(fd, 0o600);
+      } catch (_) {
+        /* best effort */
+      }
+      return true;
+    } catch (_) {
+      return false; // fail closed
+    }
+  }
+
+  function emit(eventType, payload) {
+    try {
+      if (!ensureLogDir()) return;
+      const monotonicMs = Date.now() - startMs;
+      let eventId;
+      try {
+        eventId = uuidFn ? String(uuidFn()) : crypto.randomUUID();
+      } catch (_) {
+        eventId = 'fallback-' + Date.now() + '-' + Math.random().toString(36).slice(2, 10);
+      }
+      const redactedPayload = redact(payload, sensitiveKeys);
+      const envelope = {
+        schemaVersion: 1,
+        eventId: eventId,
+        eventType: eventType,
+        timestamp: typeof now === 'function' ? now() : new Date().toISOString(),
+        monotonicMs: monotonicMs,
+        harness: harness,
+        sessionId: sid,
+        processId: processId,
+        cwd: cwd,
+        payload: redactedPayload,
+      };
+      const line = JSON.stringify(envelope) + '\n';
+      if (fd !== null) {
+        fs.writeSync(fd, line);
+      }
+    } catch (_) {
+      // Silent — telematics must never throw
+    }
+  }
+
+  function close() {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch (_) {
+        /* silent */
+      }
+      fd = null;
+    }
+  }
+
+  return {
+    enabled: true,
+    sessionId: sid,
+    emit: emit,
+    close: close,
+  };
+}
+
+module.exports = {
+  createTelematics: createTelematics,
+  redact: redact,
+  loadTelematicsConfig: loadTelematicsConfig,
+  sanitizeId: sanitizeId,
+  BUILTIN_SENSITIVE_KEYS: BUILTIN_SENSITIVE_KEYS,
+};