@ngockhoale/ukit 2.7.4 → 2.7.5

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to UKit are documented here.
 
+## 2.7.5 - 2026-09-20
+
+Hook performance work — cycle C40 (TASK-001..007): `.mjs` module steps,
+fail-closed registry, and a hook budget guard.
+
+- `hook-chain-runner` supports `"<path>.mjs[:N]"` module steps: the arg is
+  imported in-proc and its `runHook(ctx)` is invoked with
+  `{payload, payloadText, projectRoot, env, deadlineMs, signal}` — no child
+  process spawn on the hot path. A throw reports `error`, a
+  `deadlineMs`/`AbortSignal` breach reports `timeout` + `killed`; infra
+  failures exit 2 when the step is fail-closed, else 1. Every step appends a
+  `recordHookTiming` telemetry row under its `<name>.mjs` hook name, and
+  `UKIT_HOOK_DEADLINE_MS` is scrubbed from `process.env`/`ctx.env` around the
+  import so a stale host deadline cannot leak into module steps.
+- Fail-closed registry extended: `sensitive-data-guard.mjs` and
+  `block-dangerous.mjs` join `FAIL_CLOSED_SCRIPTS`, so module-step verdicts
+  keep the same fail-closed posture as the `.sh` wrappers they replaced.
+- `sensitive-data-guard`, `block-dangerous`, and `record-execution` ported to
+  dual-mode modules: each `.mjs` exports `runHook(ctx)` for chain execution
+  plus an `isDirectRun()` CLI path for standalone/debug invocation;
+  `hookFailClosed` is exported per module (`true` for the two gates, `false`
+  for the telemetry sink). The `.sh` files remain as thin wrappers — staging,
+  salvage glue (`UKIT_SALVAGED_*` env), telemetry, then a single
+  `node <module>.mjs` call — with byte-identical verdicts verified against the
+  pre-port implementations. `record-execution.mjs` also exposes
+  `setLedgerMessageEmitter` on `execution-ledger.mjs` so in-proc runs route
+  the `noteSweepFailure` systemMessage through the emitter instead of fd 1.
+- Settings + bridge wiring: `settings.json` chains and the omp bridge
+  `HOOK_EVENT_MAP` now point at the `.mjs` steps; the bridge's
+  `TIMEOUT_STAYS_CLOSED` / payload-stays-closed checks cover
+  `block-dangerous.mjs` so verdicts stay identical after the swap.
+- Hook budget guard: `tests/hooks/hookChainBudget.test.js` enforces ≤8 chain
+  steps per group, requires a `:N` suffix on every `.sh|mjs` arg, and pins
+  outer `timeout` ≥ Σ(:N) + 10s — adding or removing a hook without updating
+  the outer fails loudly. The same suite asserts the settings↔bridge mirror
+  1:1 for every event/matcher lane. The contract is documented under
+  `UKIT_INTERNALS.md → Hook budget`.
+
 ## 2.7.4 - 2026-09-20
 
 Deferred hook findings + residual risks — cycle C39 (TASK-001..005).

package/manifests/platform.full.yaml

@@ -1096,6 +1096,20 @@ items:
     packs:
       - core
 
+  # TASK-004 (C40): advisory module the thin .sh wrapper delegates to and the
+  # chain runner loads in-proc.
+  - id: hook-record-execution-module
+    type: hook
+    sourceTemplate: .claude/hooks/record-execution.mjs
+    targetPath: .claude/hooks/record-execution.mjs
+    requires:
+      - ukit-runtime-scripts
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-completion-gate
     type: hook
     sourceTemplate: .claude/hooks/completion-gate.sh
@@ -1141,6 +1155,20 @@ items:
     packs:
       - core
 
+  # TASK-003 (C40): fail-closed module the thin .sh wrapper delegates to and
+  # the chain runner loads in-proc.
+  - id: hook-block-dangerous-module
+    type: hook
+    sourceTemplate: .claude/hooks/block-dangerous.mjs
+    targetPath: .claude/hooks/block-dangerous.mjs
+    requires:
+      - ukit-runtime-scripts
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   # requires: [ukit-runtime-scripts] is forward-declared for the shared sensitive-value
   # scanner (consumed by the guard once TASK-039 wires it). The guard is fail-closed, so
   # its runtime dependency must be installed first — keeps the ordering posture explicit.
@@ -1156,6 +1184,21 @@ items:
     packs:
       - core
 
+  # TASK-002 (C40): dual-mode module the thin .sh wrapper delegates to and the
+  # chain runner loads in-proc. Requires ukit-runtime-scripts for the scanner
+  # AND hook-field-salvage.mjs (both ship via that directory item).
+  - id: hook-sensitive-data-guard-module
+    type: hook
+    sourceTemplate: .claude/hooks/sensitive-data-guard.mjs
+    targetPath: .claude/hooks/sensitive-data-guard.mjs
+    requires:
+      - ukit-runtime-scripts
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-handoff-model-guard
     type: hook
     sourceTemplate: .claude/hooks/handoff-model-guard.sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.7.4",
+  "version": "2.7.5",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/templates/.claude/hooks/block-dangerous.mjs

@@ -0,0 +1,377 @@
+// block-dangerous.mjs — C40 TASK-003 port of block-dangerous.sh into a
+// dual-mode module (SPEC §FR-006, §8):
+//
+//   * `runHook(ctx)` — in-proc chain step. ctx = { payload, payloadText,
+//     projectRoot, env, deadlineMs, signal } -> { code, stdout, stderr }.
+//     Byte-identical verdicts to the .sh: dangerous pattern / unsafe rm verdict
+//     -> identical permissionDecision JSON + `BLOCKED: <reason>` stderr; safe
+//     command -> code 0 empty. Under the chain marker (UKIT_HOOK_CHAIN_RUNNER)
+//     decisions are `ask` + code 2; on the direct host they are `deny` + code 0
+//     (bypassPermissions auto-approves `ask` — TASK-223/probe verdict).
+//   * `isDirectRun()` CLI mode — the .sh thin wrapper execs
+//     `node block-dangerous.mjs` with the exact env contract the bash glue
+//     produced (INPUT_FILE PROJECT_ROOT UKIT_HOOK_DEADLINE_MS
+//     UKIT_SALVAGE_ACTIVE UKIT_SALVAGED_COMMAND).
+//
+// FAIL-CLOSED gate. The raw command and matched pattern are NEVER echoed —
+// arguments and comments can carry secrets, and the pattern text itself
+// restates the dangerous command. Truncated/degraded input salvages only a
+// provably-complete tool_input.command via ukit/runtime/hook-field-salvage.mjs;
+// anything else refuses `deny` — a partial command is never evaluated.
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { salvageField } from '../ukit/runtime/hook-field-salvage.mjs';
+
+export const hookFailClosed = true;
+
+// POSIX [[:space:]] exactly (grep -E semantics; JS \s also matches unicode).
+const SP = '[\\t\\n\\v\\f\\r ]';
+
+// --- byte-pinned verdicts ----------------------------------------------------
+const REASON_DANGEROUS =
+  'Dangerous command pattern detected; it could cause irreversible damage. UKit defers this to a human decision.';
+const REASON_UNSAFE_TARGET =
+  'Unsafe delete target detected; recursive force-delete could cause irreversible damage. UKit defers this to a human decision.';
+const REASON_GENERIC_RM =
+  'Recursive force-delete outside safe cleanup targets (dist/build/coverage/.next/.nuxt/.turbo/tmp/.cache/node_modules) is destructive. UKit defers this to a human decision.';
+const REASON_SALVAGE_REFUSAL =
+  'UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound) and the command could not be recovered, so dangerous-command gate cannot prove it safe.';
+
+const TIMEOUT_REFUSAL = {
+  code: 2,
+  stdout:
+    '{"systemMessage":"UKit dangerous-command gate timed out before finishing its scan; blocked fail-closed rather than pass an uninspected payload."}\n',
+  stderr:
+    'BLOCKED: dangerous-command gate timed out; blocked fail-closed rather than pass an uninspected payload.\n',
+};
+const CRASH_REFUSAL = {
+  code: 2,
+  stdout:
+    '{"systemMessage":"UKit dangerous-command gate crashed before finishing its scan; blocked fail-closed rather than pass an uninspected payload. Run `ukit install` if this repeats."}\n',
+  stderr: 'BLOCKED: dangerous-command gate crashed; payload never inspected (fail-closed).\n',
+};
+
+// ukit_emit_permission_decision parity (hook-input.sh): the JSON shape is
+// harness-agnostic, the exit code is not — direct host exits 0 (non-zero
+// discards stdout), chain exits 2 (bridge parses stdout only on code 2).
+// stderr always carries the BLOCKED line.
+function emitDecision(decision, reason, env) {
+  const inChain = Boolean(env.UKIT_HOOK_CHAIN_RUNNER);
+  return {
+    code: inChain ? 2 : 0,
+    stdout:
+      `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"${decision}",` +
+      `"permissionDecisionReason":"${reason}"}}\n`,
+    stderr: `BLOCKED: ${reason}\n`,
+  };
+}
+const emitDangerous = (reason, env) =>
+  emitDecision(env.UKIT_HOOK_CHAIN_RUNNER ? 'ask' : 'deny', reason, env);
+const emitRefusal = (env) => emitDecision('deny', REASON_SALVAGE_REFUSAL, env);
+
+// --- command extraction ------------------------------------------------------
+// jq/node heredoc parity: tool_input.command string, else ''.
+function extractCommand({ rawInput, env }) {
+  if (env.UKIT_SALVAGE_ACTIVE === '1') {
+    // TASK-003 degraded path: the wrapper already recovered a COMPLETE command —
+    // skip normal extraction (the staged prefix would not parse anyway).
+    return { command: env.UKIT_SALVAGED_COMMAND ?? '' };
+  }
+  try {
+    const payload = JSON.parse(rawInput || '{}');
+    const command = payload?.tool_input?.command;
+    return { command: typeof command === 'string' ? command : '' };
+  } catch {
+    return { unparseable: true };
+  }
+}
+
+// --- verbatim ports of the .sh scan semantics ---------------------------------
+// CMD_HEAD=$(echo "$COMMAND" | sed -E 's/^[[:space:]]*//' | awk '{print $1}' | basename)
+const SAFE_TEXT_HEADS = new Set(['grep', 'egrep', 'fgrep', 'rg', 'ag', 'awk', 'sed', 'echo', 'printf', 'cat']);
+const PIPE_TO_SHELL_RE = new RegExp(`\\|${SP}*(bash|sh|zsh|eval|xargs)(${SP}|$)`, 'm');
+
+// DANGEROUS_PATTERNS — grep -E semantics preserved. Verified against BSD/GNU
+// grep: the fork-bomb entry's `{` is an invalid interval, so it (and every
+// other entry) is a literal substring except the three that carry real ERE.
+const DANGEROUS_LITERALS = [
+  'rm -rf /',
+  'rm -rf ~',
+  'git push --force',
+  'git push -f ',
+  'git reset --hard',
+  'git clean -fd',
+  '> /dev/sda',
+  'mkfs.',
+  ':(){ :|:& };:',
+  'dd if=/dev/',
+];
+const DANGEROUS_REGEXES = [
+  // "rm -rf \.?\.([[:space:]]|$)" — rm -rf . / rm -rf .. (+ trailing ws/EOL)
+  new RegExp(`rm -rf \\.?\\.(${SP}|$)`, 'm'),
+  /git checkout \./,
+  /git restore \./,
+];
+
+// rm segment analysis — byte-identical port of the .sh per-segment allowlist.
+const SAFE_NAMES = '(?:dist|build|coverage|\\.next|\\.nuxt|\\.turbo|tmp|temp|\\.cache|node_modules)';
+const SAFE_ONE_TARGET_RE = new RegExp(`^(?:\\./)?${SAFE_NAMES}(?:/.*)?$`);
+const UNSAFE_ONE_TARGET_RE = /^(\/.*|~|~\/.*|\.\.|\.\.\/.*|\.)$/;
+const RM_WORD_RE = new RegExp(`(^|[;&|${SP.slice(1, -1)}"'])rm([${SP.slice(1, -1)}"']|$)`, 'm');
+const UNSAFE_TARGET_RE = new RegExp(`(^|${SP})(\\/|~|\\.\\.?($|\\/)|\\.($|\\/))`, 'm');
+const SAFE_DELETE_RE = new RegExp(`(^|${SP})(\\./)?${SAFE_NAMES}(\\/|${SP}|$)`, 'm');
+const HAS_RECURSIVE_RE = new RegExp(`(^|${SP})--recursive|(^|${SP})-[a-zA-Z]*[rR]`, 'm');
+const HAS_FORCE_RE = new RegExp(`(^|${SP})--force|(^|${SP})-[a-zA-Z]*f`, 'm');
+
+const basename = (token) => token.split('/').pop();
+
+// ukit_canonical_path parity: realpath -m semantics — resolve the deepest
+// existing ancestor, append the lexical remainder; unresolvable -> '' (the
+// caller fails closed, never silently allows). UKIT_REALPATH_MISSING=1 (set by
+// the wrapper when no system realpath exists) forces the same fail-closed —
+// the pre-port gate could not prove containment without realpath.
+function canonicalPath(p, env) {
+  if (env && env.UKIT_REALPATH_MISSING === '1') return '';
+  try {
+    const out = fs.realpathSync.native(p);
+    if (out) return out;
+  } catch {}
+  let rest = '';
+  let cur = p;
+  const existsOrLink = (q) => {
+    try {
+      fs.lstatSync(q);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  while (cur && cur !== '/' && !existsOrLink(cur)) {
+    rest = `/${path.basename(cur)}${rest}`;
+    const parent = cur.slice(0, cur.lastIndexOf('/')) || (cur.startsWith('/') ? '/' : cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  if (!cur) cur = '/';
+  try {
+    const out = fs.realpathSync.native(cur);
+    return `${out}${rest}`;
+  } catch {
+    return '';
+  }
+}
+
+function evaluate({ command, projectRoot, env }) {
+  if (!command) return { code: 0, stdout: '', stderr: '' };
+
+  // Quoted-span scrub: only when the invoked command is a pure text tool AND
+  // its output cannot reach a shell — `echo "rm -rf /" | bash` executes the
+  // quoted text, so it must never be scrubbed.
+  const head = (command.trimStart().split(/\s+/)[0] || '');
+  const cmdHead = basename(head);
+  let scan = command;
+  if (SAFE_TEXT_HEADS.has(cmdHead) && !PIPE_TO_SHELL_RE.test(command)) {
+    scan = command.replace(/'[^']*'/g, "'Q'").replace(/"[^"]*"/g, '"Q"');
+  }
+
+  for (const literal of DANGEROUS_LITERALS) {
+    if (scan.includes(literal)) return emitDangerous(REASON_DANGEROUS, env);
+  }
+  for (const re of DANGEROUS_REGEXES) {
+    if (re.test(scan)) return emitDangerous(REASON_DANGEROUS, env);
+  }
+
+  // rm handling: allow safe cleanup targets only; everything else defers.
+  const projectRootCanon = canonicalPath(projectRoot, env);
+
+  let verdictUnsafe = false;
+  let verdictGeneric = false;
+  let directSeen = false;
+
+  for (const rawSegment of scan.split(/[;&|\n]/)) {
+    const segment = rawSegment;
+    if (!segment) continue;
+    const tokens = segment.trimStart().split(/\s+/).filter(Boolean);
+    if (basename(tokens[0] || '') !== 'rm') continue;
+
+    // flags: leading -x tokens until `--` or the first non-flag word.
+    let hasR = false;
+    let hasF = false;
+    let i = 1;
+    for (; i < tokens.length; i += 1) {
+      const t = tokens[i];
+      if (t === '--') break;
+      if (!t.startsWith('-')) break;
+      if (t === '--recursive') hasR = true;
+      else if (t === '--force') hasF = true;
+      else if (t.startsWith('--')) { /* other long flag: ignore */ }
+      else {
+        if (/[rR]/.test(t)) hasR = true;
+        if (t.includes('f')) hasF = true;
+      }
+    }
+    if (!(hasR && hasF)) continue;
+    directSeen = true;
+
+    // targets: the first non-flag word and every later non-dash word.
+    const targets = [];
+    {
+      let saw = false;
+      for (let j = 1; j < tokens.length; j += 1) {
+        const t = tokens[j];
+        if (!saw) {
+          if (t === '--') {
+            saw = true;
+            continue;
+          }
+          if (t.startsWith('-')) continue;
+          saw = true;
+          targets.push(t);
+        } else if (!t.startsWith('-')) {
+          targets.push(t);
+        }
+      }
+    }
+
+    let allSafe = true;
+    let anyUnsafe = false;
+    for (let target of targets) {
+      // Strip ONE trailing slash (never shrink a bare `/` or `~` to '').
+      if (target.length > 1 && target.endsWith('/')) target = target.slice(0, -1);
+      if (UNSAFE_ONE_TARGET_RE.test(target)) {
+        anyUnsafe = true;
+        allSafe = false;
+      } else if (SAFE_ONE_TARGET_RE.test(target)) {
+        // TASK-013 containment gate: the allowlisted NAME is not enough — the
+        // canonical target must live inside the canonical project root.
+        if (target.includes('..')) {
+          allSafe = false;
+        } else {
+          const abs = target.startsWith('/') ? target : `${projectRootCanon}/${target}`;
+          const canon = canonicalPath(abs, env);
+          if (!projectRootCanon || !canon || !canon.startsWith(`${projectRootCanon}/`)) {
+            allSafe = false;
+          }
+        }
+      } else {
+        allSafe = false;
+      }
+    }
+    if (anyUnsafe) verdictUnsafe = true;
+    else if (!allSafe) verdictGeneric = true;
+  }
+
+  if (!directSeen && RM_WORD_RE.test(scan) && HAS_RECURSIVE_RE.test(scan) && HAS_FORCE_RE.test(scan)) {
+    // Whole-command fallback (wrapped/quoted rm, flags after targets): unsafe
+    // wins over the allowlist — a safe word elsewhere never legitimises an
+    // absolute/home/parent target we can also see.
+    if (UNSAFE_TARGET_RE.test(scan)) verdictUnsafe = true;
+    else if (!SAFE_DELETE_RE.test(scan)) verdictGeneric = true;
+  }
+
+  if (verdictUnsafe) return emitDangerous(REASON_UNSAFE_TARGET, env);
+  if (verdictGeneric) return emitDangerous(REASON_GENERIC_RM, env);
+  return { code: 0, stdout: '', stderr: '' };
+}
+
+// --- SPEC §8 chain-step entry --------------------------------------------------
+export async function runHook(ctx) {
+  const env = (ctx && ctx.env) || {};
+  const projectRoot =
+    env.CLAUDE_PROJECT_DIR || (ctx && ctx.projectRoot) || env.PROJECT_ROOT || process.cwd();
+  const deadlineMs =
+    Number.parseInt((ctx && ctx.deadlineMs) ?? env.UKIT_HOOK_DEADLINE_MS ?? '', 10) || 3000;
+
+  const rawInput =
+    typeof (ctx && ctx.payloadText) === 'string' && ctx.payloadText.length > 0
+      ? ctx.payloadText
+      : (() => {
+          try {
+            return JSON.stringify((ctx && ctx.payload) ?? {});
+          } catch {
+            return '';
+          }
+        })();
+
+  let extracted = extractCommand({ rawInput, env });
+  if (extracted.unparseable) {
+    // The .sh only salvages on a staging-degraded flag; in-proc there is no flag
+    // — an unparseable payloadText IS the degradation. `{"…`-prefixed text that
+    // fails to parse is a truncated payload: salvage tool_input.command only
+    // when provably complete, else refuse deny (a partial command is never
+    // evaluated). Non-JSON garbage is nothing to scan -> pass, same as jq
+    // failing on the .sh path.
+    if (rawInput.trimStart().startsWith('{')) {
+      const salvaged = salvageField(rawInput, 'tool_input.command');
+      if (!salvaged.complete || salvaged.value === null) return emitRefusal(env);
+      extracted = { command: salvaged.value };
+    } else {
+      extracted = { command: '' };
+    }
+  }
+
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(TIMEOUT_REFUSAL), Math.max(1, deadlineMs));
+    if (timer && typeof timer.unref === 'function') timer.unref();
+  });
+  try {
+    const run = (async () => {
+      if (ctx && ctx.signal && ctx.signal.aborted) return TIMEOUT_REFUSAL;
+      return evaluate({ command: extracted.command, projectRoot, env });
+    })();
+    return await Promise.race([run, timeout]);
+  } catch {
+    return CRASH_REFUSAL;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// --- 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;
+  // .sh parity: the deadline bounded the extraction node — expiry produced an
+  // empty command and a pass (exit 0, no output).
+  const timer = setTimeout(() => process.exit(0), HOOK_DEADLINE_MS);
+  if (timer && typeof timer.unref === 'function') timer.unref();
+
+  let rawInput = '';
+  try {
+    rawInput = await fsp.readFile(env.INPUT_FILE || '', 'utf8');
+  } catch {}
+  const projectRoot = env.PROJECT_ROOT || env.CLAUDE_PROJECT_DIR || process.cwd();
+
+  try {
+    const extracted = extractCommand({ rawInput, env });
+    const command = extracted.unparseable ? '' : extracted.command;
+    const verdict = evaluate({ command, projectRoot, env });
+    if (verdict.stdout) process.stdout.write(verdict.stdout);
+    if (verdict.stderr) process.stderr.write(verdict.stderr);
+    process.exit(verdict.code);
+  } catch {
+    // Fail-closed (guard parity): a crash means the payload was never
+    // inspected — refuse, never a silent non-blocking hook error.
+    if (CRASH_REFUSAL.stdout) process.stdout.write(CRASH_REFUSAL.stdout);
+    if (CRASH_REFUSAL.stderr) process.stderr.write(CRASH_REFUSAL.stderr);
+    process.exit(CRASH_REFUSAL.code);
+  }
+}
+
+if (isDirectRun()) {
+  main();
+}