@ngockhoale/ukit 2.4.3 → 2.5.1

package/src/core/uninstall.js

@@ -2,12 +2,158 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import {
   cleanupEmptyParents,
+  copyFileRawExclusive,
   readJsonIfExists,
   removeLinkOrDir,
   removeLinkOnly,
   resolveProjectRelativePath,
 } from './fileOps.js';
 import { removeGitignoreBlock } from './ensureGitignore.js';
+import { PROJECT_IMPORTANT_FILENAME } from './projectImportant.js';
+
+// PROJECT_IMPORTANT.md is owner content, never UKit-managed. It must NEVER appear
+// in ALLOWED_UNINSTALL_PREFIXES and is never deleted/renamed/chmodded/rewritten/
+// tracked/followed. Before any destructive uninstall step a regular source gets a
+// raw-byte backup beside it at the project root (never under .claude/.ukit/.codex/
+// .omp — those may be deleted): `<name>.ukit-backup`, then `.ukit-backup.1`, `.2`, …
+// via bounded exclusive-create collision walk. See docs/PROJECT_IMPORTANT_SPEC.md §15.
+const IMPORTANT_BACKUP_SUFFIX = '.ukit-backup';
+const IMPORTANT_BACKUP_COLLISION_LIMIT = 100;
+
+function importantBackupCandidateName(index) {
+  return index === 0
+    ? `${PROJECT_IMPORTANT_FILENAME}${IMPORTANT_BACKUP_SUFFIX}`
+    : `${PROJECT_IMPORTANT_FILENAME}${IMPORTANT_BACKUP_SUFFIX}.${index}`;
+}
+
+// Read-only inspection used by BOTH dry-run and real runs: resolves which backup
+// candidate would be used without creating anything. An existing backup whose
+// bytes already match the source is reused; a different-bytes or non-regular
+// occupant pushes the walk to the next suffix. Nothing is ever overwritten.
+async function planImportantBackup(projectRoot) {
+  const sourcePath = path.join(projectRoot, PROJECT_IMPORTANT_FILENAME);
+  const plan = {
+    sourcePath,
+    sourceBytes: null,
+    sourceExists: false,
+    sourceIsRegular: false,
+    wouldBackup: false,
+    backupPath: null,
+    reused: false,
+    exhausted: false,
+    preservedPaths: [],
+    backupWarnings: [],
+  };
+
+  let stat;
+  try {
+    stat = await fs.lstat(sourcePath); // lstat: never follow a source symlink
+  } catch {
+    return plan; // no source — nothing to preserve or back up
+  }
+  plan.sourceExists = true;
+  plan.preservedPaths.push(sourcePath);
+
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    // Symlink/non-regular source: never followed or copied — preserved in place.
+    plan.backupWarnings.push(
+      `[UKit] ${PROJECT_IMPORTANT_FILENAME} is not a regular file; preserved in place without a backup. Run \`ukit doctor\`.`,
+    );
+    return plan;
+  }
+  plan.sourceIsRegular = true;
+  plan.sourceBytes = await fs.readFile(sourcePath); // raw bytes, no decode
+
+  for (let index = 0; index <= IMPORTANT_BACKUP_COLLISION_LIMIT; index += 1) {
+    const candidatePath = path.join(projectRoot, importantBackupCandidateName(index));
+    let candidateStat;
+    try {
+      candidateStat = await fs.lstat(candidatePath);
+    } catch {
+      candidateStat = null;
+    }
+    if (!candidateStat) {
+      plan.wouldBackup = true;
+      plan.backupPath = candidatePath;
+      return plan;
+    }
+    if (candidateStat.isFile() && !candidateStat.isSymbolicLink()) {
+      const existingBytes = await fs.readFile(candidatePath).catch(() => null);
+      if (existingBytes && existingBytes.equals(plan.sourceBytes)) {
+        plan.backupPath = candidatePath;
+        plan.reused = true;
+        return plan;
+      }
+    }
+    // different bytes or non-regular — try next suffix
+  }
+
+  plan.exhausted = true;
+  plan.backupWarnings.push(
+    `[UKit] Backup name space exhausted (${IMPORTANT_BACKUP_COLLISION_LIMIT + 1} candidates in use); `
+      + `${PROJECT_IMPORTANT_FILENAME} preserved in place without a backup. Free a backup slot and rerun \`ukit uninstall\`.`,
+  );
+  return plan;
+}
+
+// Real-run backup: byte-identical raw copy via exclusive create (COPYFILE_EXCL —
+// never overwrites). EEXIST means the slot filled between plan and copy; the walk
+// re-checks it (equal bytes → reuse, else next suffix). Any other failure cleans
+// up a possible partial copy and ABORTS uninstall before managed deletion.
+async function createImportantBackup(projectRoot, sourcePath, sourceBytes) {
+  for (let index = 0; index <= IMPORTANT_BACKUP_COLLISION_LIMIT; index += 1) {
+    const candidatePath = path.join(projectRoot, importantBackupCandidateName(index));
+    let candidateStat;
+    try {
+      candidateStat = await fs.lstat(candidatePath);
+    } catch {
+      candidateStat = null;
+    }
+    if (candidateStat) {
+      if (candidateStat.isFile() && !candidateStat.isSymbolicLink()) {
+        const existingBytes = await fs.readFile(candidatePath).catch(() => null);
+        if (existingBytes && existingBytes.equals(sourceBytes)) {
+          return candidatePath; // reused — already byte-identical
+        }
+      }
+      continue;
+    }
+    try {
+      await copyFileRawExclusive(sourcePath, candidatePath); // preserves mode where supported
+      return candidatePath;
+    } catch (error) {
+      if (error?.code === 'EEXIST') {
+        // Lost the race — the slot now exists. Reuse it when its bytes match the
+        // source; otherwise advance to the next suffix.
+        try {
+          const racedStat = await fs.lstat(candidatePath);
+          if (racedStat.isFile() && !racedStat.isSymbolicLink()) {
+            const racedBytes = await fs.readFile(candidatePath).catch(() => null);
+            if (racedBytes && racedBytes.equals(sourceBytes)) {
+              return candidatePath;
+            }
+          }
+        } catch {
+          // vanished again — either way, move on
+        }
+        continue;
+      }
+      try {
+        await fs.rm(candidatePath, { force: true }); // clean partial backup
+      } catch {
+        // best-effort cleanup only
+      }
+      // Error carries no source content — only the failing operation.
+      throw new Error(
+        `[UKit] Uninstall aborted: could not back up ${PROJECT_IMPORTANT_FILENAME} (${error?.code || error?.message}). Managed paths were not removed.`,
+        { cause: error },
+      );
+    }
+  }
+  throw new Error(
+    `[UKit] Uninstall aborted: no free backup name for ${PROJECT_IMPORTANT_FILENAME} after ${IMPORTANT_BACKUP_COLLISION_LIMIT} collisions. Managed paths were not removed.`,
+  );
+}
 
 // Use lstat (not access) so broken symlinks are also detected as existing.
 async function pathExistsLstat(targetPath) {
@@ -254,13 +400,42 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
     );
   }
 
+  // PROJECT_IMPORTANT.md preservation — read-only plan first (spec §15). The
+  // source is never touched: only inspected via lstat + readFile.
+  const importantPlan = await planImportantBackup(projectRoot);
+
   if (dryRun) {
-    // Use lstat (not access) so broken symlinks are included in the report.
+    // Dry run creates nothing: report the collision-resolved candidate and the
+    // preserved/refused state only. lstat (not access) keeps broken symlinks visible.
     const wouldRemove = [];
     for (const { abs } of safeEntries) {
       if (await pathExistsLstat(abs)) wouldRemove.push(abs);
     }
-    return { removed: 0, attempted: allEntries.length, wasInstalled: true, wouldRemove, skippedSymlinkParents };
+    return {
+      removed: 0,
+      attempted: allEntries.length,
+      wasInstalled: true,
+      wouldRemove,
+      wouldBackup: importantPlan.wouldBackup,
+      backupPaths: importantPlan.backupPath ? [importantPlan.backupPath] : [],
+      preservedPaths: importantPlan.preservedPaths,
+      backupWarnings: importantPlan.backupWarnings,
+      skippedSymlinkParents,
+    };
+  }
+
+  // Backup runs BEFORE any destructive step. A failure here aborts uninstall —
+  // managed paths stay intact and the source is never modified.
+  const backupPaths = [];
+  if (importantPlan.wouldBackup) {
+    const backupPath = await createImportantBackup(
+      projectRoot,
+      importantPlan.sourcePath,
+      importantPlan.sourceBytes,
+    );
+    backupPaths.push(backupPath);
+  } else if (importantPlan.backupPath && importantPlan.reused) {
+    backupPaths.push(importantPlan.backupPath); // existing byte-identical backup
   }
 
   // Remove all paths in parallel
@@ -289,5 +464,14 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
     await cleanupEmptyParents(removedPath, projectRoot);
   }
 
-  return { removed, attempted: allEntries.length, wasInstalled: true, skippedSymlinkParents };
+  return {
+    removed,
+    attempted: allEntries.length,
+    wasInstalled: true,
+    wouldBackup: importantPlan.wouldBackup,
+    backupPaths,
+    preservedPaths: importantPlan.preservedPaths,
+    backupWarnings: importantPlan.backupWarnings,
+    skippedSymlinkParents,
+  };
 }

package/templates/.claude/hooks/project-important.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# SessionStart hook: emit the deterministic PROJECT_IMPORTANT.md mandate envelope
+# once per context epoch (docs/PROJECT_IMPORTANT_SPEC.md §6, §7, §9).
+# ADVISORY ONLY — always exit 0. A missing runtime or a renderer failure degrades
+# to the frozen `unreadable` warning line, never a raw exception, never a blocked
+# session. No renderer logic lives here — the shared runtime module renders.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
+# Arm advisory latency telemetry when available; a missing runtime (pre-install
+# tree) simply leaves telemetry off.
+source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
+  trap ukit_cleanup_hook_input EXIT
+  # Bounded stdin (H01): the SessionStart payload is unused, but it still flows
+  # through the staging bound so a producer that never closes the pipe cannot
+  # hold this hook open (R4.5).
+  ukit_stage_hook_input 1048576 truncate || exit 0
+else
+  # Runtime helper missing (pre-install tree): the SAME bounded staging,
+  # inline — read cap+1 in the background, bound the wait, never drain with an
+  # unconditional `cat`.
+  UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c 1048577 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  else
+    head -c 1048577 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  fi
+  __ukit_reader=$!
+  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_stage_ms" in
+    ''|*[!0-9]*) __ukit_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_stage_ms" -gt 0 ] 2>/dev/null || __ukit_stage_ms=2000
+  printf -v __ukit_stage_s '%d.%03d' $((__ukit_stage_ms / 1000)) $((__ukit_stage_ms % 1000))
+  ( sleep "$__ukit_stage_s" 2>/dev/null; kill -9 "$__ukit_reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  __ukit_waiter=$!
+  wait "$__ukit_reader" 2>/dev/null
+  kill "$__ukit_waiter" 2>/dev/null
+  wait "$__ukit_waiter" 2>/dev/null
+  exec 8<&-
+  trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
+fi
+
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+SCRIPT="$PROJECT_ROOT/.claude/ukit/runtime/project-important.mjs"
+UNREADABLE_WARNING='[UKit] PROJECT_IMPORTANT.md was not injected: the file could not be read. Run `ukit doctor`.'
+
+if [ ! -f "$SCRIPT" ]; then
+  printf '%s\n' "$UNREADABLE_WARNING"
+  exit 0
+fi
+
+# The wrapped runtime self-arms on UKIT_HOOK_DEADLINE_MS (SCRIPT_ARM/EXIT_ARM),
+# so a wedged read exits 0 inside the deadline instead of orphaning a node child.
+INPUT="$(cat "$UKIT_INPUT_FILE" 2>/dev/null)"
+OUTPUT=$(printf '%s' "$INPUT" | UKIT_PROJECT_ROOT="$PROJECT_ROOT" UKIT_HARNESS=claude-code UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" node "$SCRIPT" 2>/dev/null)
+STATUS=$?
+
+if [ "$STATUS" -ne 0 ] || [ -z "$OUTPUT" ]; then
+  printf '%s\n' "$UNREADABLE_WARNING"
+  exit 0
+fi
+
+printf '%s\n' "$OUTPUT"
+exit 0

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

@@ -27,6 +27,8 @@
 # a broken gate must not brick every session, but every real detection blocks.
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK_DIR="$SCRIPT_DIR"
+SCRIPT_PATH="$HOOK_DIR/../ukit/runtime/sensitive-value-scanner.mjs"
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 # Bounded stdin (H01) — fail-closed overflow: an oversized payload is REFUSED
 # (silent exit 2, nothing staged, nothing echoed). The gate never truncates
@@ -78,7 +80,7 @@ else
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi
 
-INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" node <<'NODE'
+INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" SCRIPT_PATH="$SCRIPT_PATH" UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" node <<'NODE'
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
 setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
 const fs = require('fs');
@@ -132,37 +134,44 @@ function pathAllowed(filePath) {
   return allowedPaths.some((allowed) => allowed === normalized || allowed === relative);
 }
 
-// --- high-confidence secret value patterns (shared by prompt + bash scanning) ---
-// AKIA/ASIA/AIza prefixes are pure base64-compatible text, so an encoded blob
-// can contain a coincidental key-shaped substring (round-17 live case: ASIA…
-// inside a base64 payload). Those rules must stand alone — no base64/base64url
-// character on either side. Padding "=" is a boundary: it only ends a blob.
-const TOKEN_PATTERNS = [
-  { label: 'OpenAI/Anthropic-style API key', re: /\bsk-(?:proj-|ant-|svc-|acct-|admin-)?[A-Za-z0-9_-]{20,}/g },
-  { label: 'AWS access key id', re: /(?<![A-Za-z0-9+/_-])(?:AKIA|ASIA)[0-9A-Z]{16}(?![A-Za-z0-9+/_-])/g },
-  { label: 'GitHub token', re: /\bgh[pousr]_[A-Za-z0-9]{30,}\b/g },
-  { label: 'GitHub fine-grained token', re: /\bgithub_pat_[A-Za-z0-9_]{20,}/g },
-  { label: 'GitLab token', re: /\bglpat-[A-Za-z0-9_-]{20,}/g },
-  { label: 'Slack token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}/g },
-  { label: 'Google API key', re: /(?<![A-Za-z0-9+/_-])AIza[0-9A-Za-z_-]{20,}(?![A-Za-z0-9+/_-])/g },
-  { label: 'Stripe live key', re: /\b[srp]k_live_[A-Za-z0-9]{20,}/g },
-  { label: 'JWT', re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g },
-  { label: 'private key block', re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY-----/g },
-];
-
-// No keyword-assignment lane ("password: …", "token = …") on purpose — it was
-// the source of every false positive: it guessed at whatever followed a
-// keyword, blocking code, prose and shell syntax that is never a secret.
-function scanSecretText(text) {
-  const found = [];
-  for (const { label, re } of TOKEN_PATTERNS) {
-    re.lastIndex = 0;
-    let match;
-    while ((match = re.exec(text)) !== null) {
-      found.push({ label, value: match[0] });
-    }
+// --- high-confidence secret value scan (TASK-039: shared runtime module) ---
+// The token-pattern definitions and matching live in the shared runtime
+// module ukit/runtime/sensitive-value-scanner.mjs (manifest requires:
+// ukit-runtime-scripts) — there is deliberately NO local pattern copy here, so
+// the hook and the PROJECT_IMPORTANT renderer can never drift apart. File/path
+// classification and Bash command shapes stay in this hook.
+// Leak-safety: the scanner returns labels only — never a value, excerpt, or
+// hash — so blocked-prompt previews can no longer print a value's truncated
+// sha256; the redacted block message says the value is withheld instead.
+const SCANNER_PATH = process.env.SCRIPT_PATH || '';
+let scannerModule = null;
+let scannerTried = false;
+async function loadScanner() {
+  if (scannerTried) return scannerModule;
+  scannerTried = true;
+  try {
+    const { pathToFileURL } = require('url');
+    scannerModule = await import(pathToFileURL(SCANNER_PATH).href);
+  } catch {
+    scannerModule = null;
   }
-  return found;
+  return scannerModule;
+}
+
+// The gate is fail-closed on detection AND on scanner availability: a missing
+// or crashing scanner must never silently bypass a channel that could carry a
+// secret (the module is shipped by ukit-runtime-scripts, which the manifest
+// declares this hook requires). Same redacted block shape as a detection.
+function blockScannerUnavailable() {
+  process.stderr.write(
+    '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',
+  );
+  process.stdout.write(`${JSON.stringify({
+    systemMessage: 'UKit blocked this call: the sensitive-data scanner module is unavailable (fail-closed). Run `ukit install`.',
+  })}\n`);
+  process.exit(2);
 }
 
 // --- secret file classification ---
@@ -266,7 +275,8 @@ if (event === 'UserPromptSubmit') {
   process.exit(0);
 }
 
-// --- collect findings ---
+// --- collect findings (async: the value scan delegates to the shared module) ---
+void (async () => {
 const findings = [];
 
 for (const filePath of filePathChannels) {
@@ -276,14 +286,36 @@ for (const filePath of filePathChannels) {
   }
 }
 
-const seenValues = new Set();
+// 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 } }) : [];
+
+function 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 finding of scanSecretText(text)) {
-    if (allowedValueHashes.has(sha256(finding.value))) continue;
-    const key = `${channel}:${finding.label}:${finding.value}`;
-    if (seenValues.has(key)) continue;
-    seenValues.add(key);
-    findings.push({ label: `${finding.label} in ${channel}`, value: finding.value });
+  for (const label of scanTextLabels(text)) {
+    const key = `${channel}:${label}`;
+    if (seenLabels.has(key)) continue;
+    seenLabels.add(key);
+    findings.push({ label: `${label} in ${channel}` });
   }
 }
 
@@ -296,12 +328,11 @@ if (bashCommand) {
     if (allowedValueHashes.has(sha256(finding.value))) continue;
     findings.push({ label: `${finding.label} in bash command`, value: finding.value });
   }
-  for (const finding of scanSecretText(bashCommand)) {
-    if (allowedValueHashes.has(sha256(finding.value))) continue;
-    const key = `bash:${finding.label}:${finding.value}`;
-    if (seenValues.has(key)) continue;
-    seenValues.add(key);
-    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` });
   }
 }
 
@@ -336,10 +367,10 @@ if (event === 'UserPromptSubmit' && promptText && isCompleteMachineEnvelope(prom
 }
 
 // --- block message: redacted previews only, never the secret itself ---
+// The shared scanner returns labels only, so value findings can no longer show
+// a truncated sha256 — the value stays withheld entirely (leak-safe contract).
 function describeFinding(finding) {
-  const where = finding.preview
-    ? `${finding.preview}`
-    : `${String(finding.value).slice(0, 3)}…(${String(finding.value).length} chars, sha256 ${sha256(String(finding.value)).slice(0, 12)}…)`;
+  const where = finding.preview ? `${finding.preview}` : '(value withheld)';
   return `  - ${finding.label}: ${where}`;
 }
 
@@ -363,6 +394,7 @@ process.stdout.write(`${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`);
 process.exit(2);
+})();
 NODE
 
 exit $?

package/templates/.claude/settings.json

@@ -226,6 +226,11 @@
     "SessionStart": [
       {
         "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/project-important.sh\"",
+            "timeout": 8
+          },
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-prune-bash.sh\"",