@ngockhoale/ukit 2.7.4 → 2.7.6

package/templates/.claude/hooks/sensitive-data-guard.mjs

@@ -0,0 +1,513 @@
+// sensitive-data-guard.mjs — C40 TASK-002 port of sensitive-data-guard.sh's
+// inline-node scan + salvage glue into a dual-mode module (SPEC §FR-005, §8):
+//
+//   * `runHook(ctx)` — in-proc chain step. ctx = { payload, payloadText,
+//     projectRoot, env, deadlineMs, signal } -> { code, stdout, stderr }.
+//     Byte-identical verdicts to the .sh: detection -> code 2 + same stderr
+//     BLOCKED lines + same systemMessage JSON; clean -> code 0 empty; crash or
+//     deadline -> the same fail-closed refusals (BUG-C21-03 parity).
+//   * `isDirectRun()` CLI mode — the .sh thin wrapper execs
+//     `node sensitive-data-guard.mjs` with the exact env contract the heredoc
+//     consumed (INPUT_FILE PROJECT_ROOT SCRIPT_PATH UKIT_HOOK_DEADLINE_MS
+//     UKIT_SALVAGE_ACTIVE UKIT_SALVAGED_EVENT UKIT_SALVAGED_TOOL_NAME
+//     UKIT_SALVAGED_FIELD_NAME UKIT_SALVAGED_FIELD_VALUE).
+//
+// FAIL-CLOSED on detection (code 2). Never echoes the detected value — labels
+// only, values withheld (leak-safe scanner contract). Fails open only when
+// there is nothing to scan (malformed stdin with no degraded flag, no channel).
+// Truncated input is NEVER scanned partial: the degraded path salvages only
+// provably-complete fields via ukit/runtime/hook-field-salvage.mjs and refuses
+// fail-closed otherwise.
+//
+// User escape hatches (explicit human action only):
+//   - security.sensitiveDataGate=false in .ukit/storage/config.json
+//   - .ukit/storage/security/allowlist.json { values:[sha256...], paths:[...] }
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { salvageField } from '../ukit/runtime/hook-field-salvage.mjs';
+
+export const hookFailClosed = true;
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_SCANNER_PATH = path.join(MODULE_DIR, '..', 'ukit', 'runtime', 'sensitive-value-scanner.mjs');
+
+// --- byte-pinned verdicts (parity with the .sh) -----------------------------
+const SALVAGE_REFUSAL = {
+  code: 2,
+  stdout:
+    '{"systemMessage":"UKit sensitive-data gate blocked this call: the tool-call payload was truncated or stalled during stdin staging and its scanned field could not be recovered intact, so it was never scanned. Fail-closed — reduce the payload or check for a stalled producer."}\n',
+  stderr:
+    'BLOCKED (sensitive data gate): truncated/stalled payload; scanned field unrecoverable — refused fail-closed.\n',
+};
+const TIMEOUT_REFUSAL = {
+  code: 2,
+  stdout:
+    '{"systemMessage":"UKit sensitive-data gate timed out before finishing its scan; blocked fail-closed rather than pass an uninspected payload."}\n',
+  stderr:
+    'BLOCKED (sensitive data gate): scan timed out; blocked fail-closed rather than pass an uninspected payload.\n',
+};
+const crashRefusal = (detail) => ({
+  code: 2,
+  stdout:
+    '{"systemMessage":"UKit sensitive-data gate crashed before finishing its scan; blocked fail-closed rather than pass an uninspected payload. Run `ukit install` if this repeats."}\n',
+  stderr: `BLOCKED (sensitive data gate): scanner process ${detail}; payload never inspected (fail-closed).\n`,
+});
+const SCANNER_UNAVAILABLE = {
+  code: 2,
+  stdout:
+    '{"systemMessage":"UKit blocked this call: the sensitive-data scanner module is unavailable (fail-closed). Run `ukit install`."}\n',
+  stderr:
+    'BLOCKED (sensitive data gate unavailable): the shared scanner module ' +
+    'ukit/runtime/sensitive-value-scanner.mjs is missing or failed to load, ' +
+    'so this payload cannot be proven clean. Run `ukit install` to restore it.\n',
+};
+
+// Inner early-verdict propagation (the heredoc called process.exit; the module
+// returns a verdict instead).
+class VerdictSignal extends Error {
+  constructor(verdict) {
+    super('verdict');
+    this.verdict = verdict;
+  }
+}
+
+// TASK-003 degraded-path salvage: reconstruct just enough payload from the
+// provably-COMPLETE salvaged fields. In-proc mode salvages straight from the
+// truncated payloadText via salvageField; CLI mode consumes the bash-salvaged
+// UKIT_SALVAGED_* env (identical semantics). Any salvage gap refuses fail-closed
+// — a partial field is never scanned.
+function salvageValue(env, text, dotPath) {
+  if (env.UKIT_SALVAGE_ACTIVE === '1') {
+    const v = env[dotPath.env];
+    return v === undefined ? null : v;
+  }
+  const r = salvageField(text, dotPath.field);
+  return r.complete ? r.value : null;
+}
+
+function reconstructSalvagedPayload(payload, { env, rawText }) {
+  const event = salvageValue(env, rawText, { env: 'UKIT_SALVAGED_EVENT', field: 'hook_event_name' });
+  if (!event) return false;
+  payload.hook_event_name = event;
+  if (event === 'PreToolUse') {
+    const toolName = salvageValue(env, rawText, { env: 'UKIT_SALVAGED_TOOL_NAME', field: 'tool_name' });
+    if (!toolName) return false;
+    const fieldName = { Read: 'file_path', Grep: 'path', Bash: 'command' }[toolName];
+    if (!fieldName) return false;
+    const value = salvageValue(env, rawText, {
+      env: 'UKIT_SALVAGED_FIELD_VALUE',
+      field: `tool_input.${fieldName}`,
+    });
+    if (value === null) return false;
+    payload.tool_name = toolName;
+    payload.tool_input = { [fieldName]: value };
+    return true;
+  }
+  if (event === 'UserPromptSubmit') {
+    const value = salvageValue(env, rawText, { env: 'UKIT_SALVAGED_FIELD_VALUE', field: 'prompt' });
+    if (value === null) return false;
+    payload.prompt = value;
+    return true;
+  }
+  return false;
+}
+
+// --- the scan itself (verbatim port of the .sh heredoc) ----------------------
+async function evaluate({ rawInput, projectRoot, env }) {
+  const payload = (() => {
+    try {
+      const parsed = JSON.parse(rawInput);
+      return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    } catch {
+      return {};
+    }
+  })();
+
+  // Degraded input: env salvage (bash wrapper recovered fields) applies on top
+  // of a parsed payload exactly like the heredoc. In-proc truncated-payloadText
+  // salvage happens in runHook before evaluate is called.
+  if (env.UKIT_SALVAGE_ACTIVE === '1' && env.UKIT_SALVAGED_EVENT) {
+    payload.hook_event_name = env.UKIT_SALVAGED_EVENT;
+    if (env.UKIT_SALVAGED_EVENT === 'PreToolUse' && env.UKIT_SALVAGED_TOOL_NAME) {
+      payload.tool_name = env.UKIT_SALVAGED_TOOL_NAME;
+      payload.tool_input = {};
+      if (env.UKIT_SALVAGED_FIELD_NAME) {
+        payload.tool_input[env.UKIT_SALVAGED_FIELD_NAME] = env.UKIT_SALVAGED_FIELD_VALUE;
+      }
+    } else if (env.UKIT_SALVAGED_EVENT === 'UserPromptSubmit') {
+      payload.prompt = env.UKIT_SALVAGED_FIELD_VALUE;
+    }
+  }
+
+  const readJsonSafe = async (filePath, fallback) => {
+    try {
+      return JSON.parse(await fsp.readFile(filePath, 'utf8'));
+    } catch {
+      return fallback;
+    }
+  };
+
+  const config = await readJsonSafe(path.join(projectRoot, '.ukit', 'storage', 'config.json'), null);
+  if (config && config.security && config.security.sensitiveDataGate === false) {
+    return { code: 0, stdout: '', stderr: '' };
+  }
+
+  const allowlist = (await readJsonSafe(path.join(projectRoot, '.ukit', 'storage', 'security', 'allowlist.json'), null)) || {};
+  const allowedValueHashes = new Set(
+    Array.isArray(allowlist.values) ? allowlist.values.filter((v) => typeof v === 'string') : [],
+  );
+  const allowedPaths = Array.isArray(allowlist.paths) ? allowlist.paths.filter((p) => typeof p === 'string') : [];
+
+  const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+
+  const pathAllowed = (filePath) => {
+    const normalized = String(filePath).replace(/\\/g, '/').trim();
+    let relative = normalized;
+    try {
+      relative = path.relative(projectRoot, normalized);
+    } catch {
+      // keep normalized
+    }
+    return allowedPaths.some((allowed) => allowed === normalized || allowed === relative);
+  };
+
+  // --- high-confidence secret value scan (shared runtime module) ---
+  const SCANNER_PATH = env.SCRIPT_PATH || DEFAULT_SCANNER_PATH;
+  let scannerModule = null;
+  let scannerTried = false;
+  const loadScanner = async () => {
+    if (scannerTried) return scannerModule;
+    scannerTried = true;
+    try {
+      scannerModule = await import(pathToFileURL(SCANNER_PATH).href);
+    } catch {
+      scannerModule = null;
+    }
+    return scannerModule;
+  };
+
+  const blockScannerUnavailable = () => {
+    throw new VerdictSignal(SCANNER_UNAVAILABLE);
+  };
+
+  // --- secret file classification ---
+  const classifySecretFile = (filePath) => {
+    if (typeof filePath !== 'string' || !filePath.trim()) return null;
+    const normalized = filePath.replace(/\\/g, '/').trim();
+    const rawBase = normalized.split('/').pop();
+    if (!rawBase) return null;
+    const base = rawBase.toLowerCase();
+    if (base.endsWith('.env.example')) return null;
+    if (base === '.env' || base.startsWith('.env.')) return 'dotenv/secret env file';
+    if (base.endsWith('.pub') || base.endsWith('.public')) return null;
+    if (/^id_(rsa|dsa|ecdsa|ed25519)(\.|$)/.test(base)) return 'SSH private key';
+    if (/\.(pem|key|p12|pfx|keystore|jks)$/.test(base)) return 'key/certificate file';
+    if (/^credentials\.(json|ya?ml|txt|ini)$/.test(base)) return 'credentials file';
+    if (/^service[_-]?account.*\.json$/.test(base)) return 'service-account key file';
+    if (base === '.npmrc' || base === '.netrc' || base === '.htpasswd') return 'credentials file';
+    if (/^secrets?\.(json|ya?ml|txt|ini|env)$/.test(base)) return 'secrets file';
+    if (/(^|\/)\.aws\/credentials$/i.test(normalized)) return 'AWS credentials file';
+    return null;
+  };
+
+  // --- bash command shapes that dump secrets ---
+  const DUMP_VERBS = new Set([
+    'cat', 'head', 'tail', 'less', 'more', 'zless', 'zcat', 'xxd', 'strings',
+    'base64', 'od', 'hexdump', 'bat', 'grep', 'egrep', 'fgrep', 'rg', 'awk', 'sed',
+  ]);
+
+  const scanBashShapes = (command) => {
+    const found = [];
+    const segments = command.split(/\|\||&&|;|\||\n/);
+    for (const rawSegment of segments) {
+      const segment = rawSegment.trim();
+      if (!segment) continue;
+      const tokens = segment.split(/\s+/);
+      const head = tokens[0].replace(/^["']+|["']+$/g, '');
+
+      if ((head === 'env' || head === 'printenv' || head === 'history') && tokens.length === 1) {
+        found.push({ label: `bare \`${head}\` dumps environment/history (may contain tokens)`, value: segment });
+        continue;
+      }
+      if (head === 'export' && (tokens[1] === '-p' || tokens[1] === '--print')) {
+        found.push({ label: 'bare `export -p` dumps all environment variables', value: segment });
+        continue;
+      }
+
+      if (DUMP_VERBS.has(head)) {
+        for (const token of tokens.slice(1)) {
+          const cleaned = token.replace(/^["']+|["',:]+$/g, '');
+          const kind = classifySecretFile(cleaned);
+          if (kind && !pathAllowed(cleaned)) {
+            found.push({ label: `${head} reads ${kind}`, value: cleaned, isPath: true });
+          }
+        }
+      }
+
+      const headBase = head.replace(/^.*\//, '');
+      const CRED_USER_TOOLS = new Set(['curl', 'wget', 'ftp', 'lftp', 'aria2c', 'http', 'https']);
+      const inlineUser = /(^|\s)(-u|--user)\s+["']?([^\s"':]+):([^\s"']+)/.exec(segment);
+      if (inlineUser && CRED_USER_TOOLS.has(headBase)) {
+        const numericIds = /^\d+$/.test(inlineUser[3]) && /^\d+$/.test(inlineUser[4]);
+        if (!numericIds) {
+          found.push({ label: 'curl/wget inline credentials (-u user:password)', value: segment });
+        }
+      }
+      if (/https?:\/\/[^\s/@'"]+:[^\s/@'"]+@/.test(segment)) {
+        found.push({ label: 'URL with embedded credentials (user:pass@host)', value: segment });
+      }
+    }
+    return found;
+  };
+
+  // --- channel wiring ---
+  const event = String(payload.hook_event_name || '');
+  const toolName = String(payload.tool_name || '');
+  const toolInput = payload.tool_input && typeof payload.tool_input === 'object' ? payload.tool_input : {};
+
+  const textChannels = [];
+  const filePathChannels = [];
+  let bashCommand = null;
+
+  if (event === 'UserPromptSubmit') {
+    const prompt = [payload.prompt, payload.user_prompt, payload.text].find(
+      (candidate) => typeof candidate === 'string' && candidate.trim(),
+    );
+    if (prompt) textChannels.push({ channel: 'prompt', text: prompt });
+  } else if (event === 'PreToolUse') {
+    if (toolName === 'Read' && typeof toolInput.file_path === 'string') {
+      filePathChannels.push(toolInput.file_path);
+    } else if (toolName === 'Grep') {
+      if (typeof toolInput.path === 'string' && toolInput.path.trim()) filePathChannels.push(toolInput.path);
+      if (typeof toolInput.pattern === 'string') textChannels.push({ channel: 'grep pattern', text: toolInput.pattern });
+    } else if (toolName === 'Bash' && typeof toolInput.command === 'string') {
+      bashCommand = toolInput.command;
+    }
+  } else {
+    return { code: 0, stdout: '', stderr: '' };
+  }
+
+  // --- collect findings ---
+  const findings = [];
+
+  for (const filePath of filePathChannels) {
+    const kind = classifySecretFile(filePath);
+    if (kind && !pathAllowed(filePath)) {
+      findings.push({ label: `Read of ${kind}`, preview: filePath, hashSource: filePath });
+    }
+  }
+
+  // The value scan needs the shared scanner module only when a text/bash
+  // channel exists to scan; a pure secret-file Read verdict never depends on it.
+  const needsScanner = textChannels.length > 0 || bashCommand;
+  let scanner = null;
+  if (needsScanner) {
+    scanner = await loadScanner();
+    if (!scanner || typeof scanner.scanText !== 'function') {
+      blockScannerUnavailable();
+    }
+  }
+  const gateEnabled = scanner ? scanner.isSensitiveDataGateEnabled(config) !== false : true;
+  const allowlistHashes = scanner ? scanner.loadSensitiveAllowlist({ security: { allowlist } }) : [];
+
+  const scanTextLabels = (text) => {
+    let verdict;
+    try {
+      verdict = scanner.scanText(text, { allowlistHashes, gateEnabled });
+    } catch {
+      blockScannerUnavailable();
+    }
+    return verdict && Array.isArray(verdict.labels) ? verdict.labels : [];
+  };
+
+  const seenLabels = new Set();
+  for (const { channel, text } of textChannels) {
+    for (const label of scanTextLabels(text)) {
+      const key = `${channel}:${label}`;
+      if (seenLabels.has(key)) continue;
+      seenLabels.add(key);
+      findings.push({ label: `${label} in ${channel}` });
+    }
+  }
+
+  if (bashCommand) {
+    for (const finding of scanBashShapes(bashCommand)) {
+      if (finding.isPath) {
+        findings.push({ label: `bash command touches ${finding.label}`, preview: finding.value });
+        continue;
+      }
+      if (allowedValueHashes.has(sha256(finding.value))) continue;
+      findings.push({ label: `${finding.label} in bash command`, value: finding.value });
+    }
+    for (const label of scanTextLabels(bashCommand)) {
+      const key = `bash:${label}`;
+      if (seenLabels.has(key)) continue;
+      seenLabels.add(key);
+      findings.push({ label: `${label} in bash command` });
+    }
+  }
+
+  if (findings.length === 0) {
+    return { code: 0, stdout: '', stderr: '' };
+  }
+
+  // --- machine-generated envelope lane (UserPromptSubmit only) ---
+  const MACHINE_ENVELOPE_RE = /^(?:task-notification|system-reminder|cross-session-message)$/i;
+  const isCompleteMachineEnvelope = (text) => {
+    const trimmed = String(text || '').trim();
+    const opening = /^<([a-z-]+)(?:\s[^>]*)?>/i.exec(trimmed);
+    if (!opening || !MACHINE_ENVELOPE_RE.test(opening[1])) return false;
+    const tag = opening[1];
+    const closing = new RegExp(`</${tag}>$`, 'i');
+    return closing.test(trimmed);
+  };
+  const promptText = textChannels.length > 0 ? textChannels[0].text : null;
+  if (event === 'UserPromptSubmit' && promptText && isCompleteMachineEnvelope(promptText)) {
+    const labels = [...new Set(findings.map((f) => f.label))];
+    return {
+      code: 0,
+      stdout: `${JSON.stringify({
+        systemMessage: `UKit sensitive-data gate: ${findings.length} secret-shaped value(s) inside a machine-generated notification (${labels.slice(0, 3).join('; ')}${labels.length > 3 ? '; …' : ''}). Delivered without blocking — treat as fixture/log plumbing, not a typed secret. Never repeat the values in your reply.`,
+      })}\n`,
+      stderr: '',
+    };
+  }
+
+  // --- block message: redacted previews only, never the secret itself ---
+  const describeFinding = (finding) => {
+    const where = finding.preview ? `${finding.preview}` : '(value withheld)';
+    return `  - ${finding.label}: ${where}`;
+  };
+
+  const lines = [
+    `BLOCKED (sensitive data): ${findings.length} potential secret(s) detected. Nothing was sent to the AI.`,
+    ...findings.map(describeFinding),
+    'Detection is format-true only: a match must itself be a vendor-formatted key,',
+    'a private key block, a JWT, or a credentials file. Code, prose, hashes and',
+    'encoded blobs are not blocked. To proceed, the USER can choose one of:',
+    '  1. Redact the secret (placeholder like <API_KEY>) and retry.',
+    '  2. Approve it explicitly: add the full sha256 (shasum -a 256 of the value) or the file path',
+    '     to .ukit/storage/security/allowlist.json — that file is protected from AI edits.',
+    '  3. Disable the gate: security.sensitiveDataGate=false in .ukit/storage/config.json (not recommended).',
+    'Never repeat or guess the detected value in your reply. Ask the user instead.',
+  ];
+  return {
+    code: 2,
+    stdout: `${JSON.stringify({
+      systemMessage: `UKit blocked this call: ${findings.length} potential secret(s) detected (${findings.map((f) => f.label).slice(0, 3).join('; ')}${findings.length > 3 ? '; …' : ''}). Redact the value, allowlist its sha256, or ask the user to decide.`,
+    })}\n`,
+    stderr: `${lines.join('\n')}\n`,
+  };
+}
+
+// --- SPEC §8 chain-step entry ------------------------------------------------
+export async function runHook(ctx) {
+  const env = (ctx && ctx.env) || {};
+  const projectRoot = (ctx && ctx.projectRoot) || env.PROJECT_ROOT || process.cwd();
+  const deadlineMs =
+    Number.parseInt((ctx && ctx.deadlineMs) ?? env.UKIT_HOOK_DEADLINE_MS ?? '', 10) || 3000;
+
+  let rawInput;
+  try {
+    rawInput =
+      typeof (ctx && ctx.payloadText) === 'string' && ctx.payloadText.length > 0
+        ? ctx.payloadText
+        : JSON.stringify((ctx && ctx.payload) ?? {});
+  } catch {
+    return crashRefusal('crashed');
+  }
+
+  // In-proc degraded path: a payloadText that does not parse is the chain's
+  // equivalent of the .sh's truncated/stalled staging flag. Salvage the
+  // decision-relevant field only when it is provably complete (salvageField);
+  // anything else refuses fail-closed — a partial field is never scanned.
+  const parsedOk = (() => {
+    try {
+      // A literal `null` payload parses fine — the .sh treated it like `{}`
+      // (no fields to scan → pass), so normalize it to `{}` rather than routing
+      // to the salvage/refusal path.
+      if (JSON.parse(rawInput) === null) rawInput = '{}';
+      return true;
+    } catch {
+      return false;
+    }
+  })();
+  if (!parsedOk && rawInput && env.UKIT_SALVAGE_ACTIVE !== '1') {
+    const salvaged = {};
+    if (!reconstructSalvagedPayload(salvaged, { env, rawText: rawInput })) {
+      return SALVAGE_REFUSAL;
+    }
+    rawInput = JSON.stringify(salvaged);
+  }
+
+  let deadline;
+  const timeout = new Promise((resolve) => {
+    deadline = setTimeout(() => resolve(TIMEOUT_REFUSAL), deadlineMs);
+    if (deadline && typeof deadline.unref === 'function') deadline.unref();
+  });
+  try {
+    const verdict = await Promise.race([evaluate({ rawInput, projectRoot, env }), timeout]);
+    return verdict;
+  } catch (error) {
+    if (error instanceof VerdictSignal) return error.verdict;
+    return crashRefusal('crashed');
+  } finally {
+    clearTimeout(deadline);
+  }
+}
+
+// --- direct-run CLI mode (the .sh thin wrapper's target) ---------------------
+export function isDirectRun() {
+  try {
+    const invoked = process.argv[1] ? fs.realpathSync(process.argv[1]) : '';
+    const self = fs.realpathSync(fileURLToPath(import.meta.url));
+    return invoked === self;
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  const env = process.env;
+  const HOOK_DEADLINE_MS = Number.parseInt(env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
+  // BUG-C21-03 (FAIL-CLOSED, parity with the staging refusal): a wedged scan
+  // must never pass an uninspected payload. The deadline emits the redacted §8
+  // degrade reason and exits 2 — never a silent exit-0 pass.
+  setTimeout(() => {
+    try {
+      process.stdout.write(TIMEOUT_REFUSAL.stdout);
+    } catch {}
+    try {
+      // stderr mirror: piped stdout is async and process.exit() can truncate
+      // the pending write — without this the block arrives with no reason.
+      process.stderr.write(TIMEOUT_REFUSAL.stderr);
+    } catch {}
+    process.exit(2);
+  }, HOOK_DEADLINE_MS).unref();
+
+  let rawInput = '';
+  try {
+    rawInput = await fsp.readFile(env.INPUT_FILE || '', 'utf8');
+  } catch {}
+  const projectRoot = env.PROJECT_ROOT || process.cwd();
+
+  try {
+    const verdict = await evaluate({ rawInput, projectRoot, env });
+    if (verdict.stdout) process.stdout.write(verdict.stdout);
+    if (verdict.stderr) process.stderr.write(verdict.stderr);
+    process.exit(verdict.code);
+  } catch (error) {
+    const refusal = error instanceof VerdictSignal ? error.verdict : crashRefusal('crashed');
+    if (refusal.stdout) process.stdout.write(refusal.stdout);
+    if (refusal.stderr) process.stderr.write(refusal.stderr);
+    process.exit(refusal.code);
+  }
+}
+
+if (isDirectRun()) {
+  main();
+}