shield-harness 0.1.0

package/.claude/hooks/lib/sh-utils.js

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+// sh-utils.js — Shared utilities for all Shield Harness hooks (Node.js)
+// Spec: DETAILED_DESIGN.md §2.2b
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { execSync } = require("child_process");
+
+// --- Constants ---
+
+const SH_DIR = ".shield-harness";
+const EVIDENCE_FILE = path.join(SH_DIR, "logs", "evidence-ledger.jsonl");
+const SESSION_FILE = path.join(SH_DIR, "session.json");
+const PATTERNS_FILE = path.join(
+  ".claude",
+  "patterns",
+  "injection-patterns.json",
+);
+const CHAIN_GENESIS_HASH = "0".repeat(64);
+
+// --- Hook I/O ---
+
+/**
+ * Read and parse hook input from stdin.
+ * @returns {Object} { raw, hookType, toolName, toolInput, toolResult, sessionId, timestamp }
+ */
+function readHookInput() {
+  let raw;
+  try {
+    raw = fs.readFileSync("/dev/stdin", "utf8");
+  } catch {
+    // Windows fallback: file descriptor 0
+    raw = fs.readFileSync(0, "utf8");
+  }
+  const input = JSON.parse(raw);
+  return {
+    raw,
+    hookType: input.hook_type || "",
+    toolName: input.tool_name || "",
+    toolInput: input.tool_input || {},
+    toolResult: input.tool_result || "",
+    sessionId: input.session_id || "",
+    timestamp: input.timestamp || "",
+  };
+}
+
+/**
+ * Output allow response and exit 0.
+ * @param {string} [context] - Optional additionalContext
+ */
+function allow(context) {
+  if (context) {
+    process.stdout.write(JSON.stringify({ additionalContext: context }));
+  } else {
+    process.stdout.write("{}");
+  }
+  process.exit(0);
+}
+
+/**
+ * Output allow response with updatedInput and exit 0.
+ * @param {Object} updatedInput - Modified tool input
+ */
+function allowWithUpdate(updatedInput) {
+  process.stdout.write(JSON.stringify({ updatedInput }));
+  process.exit(0);
+}
+
+/**
+ * Output allow response with updatedToolResult and exit 0.
+ * @param {string} updatedToolResult - Modified tool output
+ */
+function allowWithResult(updatedToolResult) {
+  process.stdout.write(JSON.stringify({ updatedToolResult }));
+  process.exit(0);
+}
+
+/**
+ * Output deny response and exit 2.
+ * @param {string} reason - Denial reason
+ */
+function deny(reason) {
+  process.stdout.write(JSON.stringify({ reason }));
+  process.exit(2);
+}
+
+// --- Normalization ---
+
+/**
+ * NFKC normalization (native — no subprocess).
+ * @param {string} input
+ * @returns {string}
+ */
+function nfkcNormalize(input) {
+  return input.normalize("NFKC");
+}
+
+/**
+ * Normalize file path (Windows backslash -> forward slash, resolve).
+ * @param {string} filePath
+ * @returns {string}
+ */
+function normalizePath(filePath) {
+  return path.resolve(filePath.replace(/\\/g, "/"));
+}
+
+// --- Crypto ---
+
+/**
+ * SHA-256 hash (native crypto).
+ * @param {string} input
+ * @returns {string} hex digest
+ */
+function sha256(input) {
+  return crypto.createHash("sha256").update(input).digest("hex");
+}
+
+// --- Session ---
+
+/**
+ * Read session.json (fail-safe: returns {} on error).
+ * @returns {Object}
+ */
+function readSession() {
+  try {
+    return JSON.parse(fs.readFileSync(SESSION_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Write session.json atomically (tmp + rename).
+ * @param {Object} data
+ */
+function writeSession(data) {
+  const dir = path.dirname(SESSION_FILE);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${SESSION_FILE}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+  fs.renameSync(tmp, SESSION_FILE);
+}
+
+// --- Evidence ---
+
+/**
+ * Append evidence entry to JSONL ledger with SHA-256 hash chain.
+ * Entries are transformed to OCSF Detection Finding (class_uid: 2004) format.
+ * @param {Object} entry
+ */
+function appendEvidence(entry) {
+  const dir = path.dirname(EVIDENCE_FILE);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  // OCSF transformation (lazy require to avoid startup cost)
+  let ocsfEntry;
+  try {
+    const { toDetectionFinding } = require("./ocsf-mapper");
+    ocsfEntry = toDetectionFinding(entry);
+  } catch {
+    // Fallback: use raw entry if OCSF mapper is unavailable
+    ocsfEntry = { ...entry };
+  }
+
+  // Read last hash for chain continuity
+  let prevHash = CHAIN_GENESIS_HASH;
+  try {
+    const content = fs.readFileSync(EVIDENCE_FILE, "utf8").trim();
+    if (content) {
+      const lines = content.split("\n");
+      const lastLine = lines[lines.length - 1];
+      const lastEntry = JSON.parse(lastLine);
+      if (lastEntry.hash) prevHash = lastEntry.hash;
+    }
+  } catch {
+    // First entry or file doesn't exist — use genesis hash
+  }
+
+  const record = {
+    ...ocsfEntry,
+    recorded_at: new Date().toISOString(),
+    prev_hash: prevHash,
+  };
+  record.hash = sha256(JSON.stringify(record));
+
+  fs.appendFileSync(EVIDENCE_FILE, JSON.stringify(record) + "\n");
+}
+
+// --- Hash Chain Verification ---
+
+/**
+ * Verify the integrity of the evidence-ledger hash chain.
+ * @param {string} [ledgerPath] - Path to evidence-ledger.jsonl (defaults to EVIDENCE_FILE)
+ * @returns {{ valid: boolean, entries: number, brokenAt?: number, reason?: string }}
+ */
+function verifyHashChain(ledgerPath) {
+  const filePath = ledgerPath || EVIDENCE_FILE;
+
+  let content;
+  try {
+    content = fs.readFileSync(filePath, "utf8").trim();
+  } catch {
+    // File does not exist — empty chain is valid
+    return { valid: true, entries: 0 };
+  }
+
+  if (!content) {
+    return { valid: true, entries: 0 };
+  }
+
+  const lines = content.split("\n");
+  let expectedPrevHash = CHAIN_GENESIS_HASH;
+
+  for (let i = 0; i < lines.length; i++) {
+    const entry = JSON.parse(lines[i]);
+
+    // Check prev_hash linkage
+    if (entry.prev_hash !== expectedPrevHash) {
+      return {
+        valid: false,
+        entries: lines.length,
+        brokenAt: i,
+        reason: "prev_hash_mismatch",
+      };
+    }
+
+    // Recompute hash: remove 'hash' field, hash the rest
+    const { hash, ...rest } = entry;
+    const computed = sha256(JSON.stringify(rest));
+    if (computed !== hash) {
+      return {
+        valid: false,
+        entries: lines.length,
+        brokenAt: i,
+        reason: "hash_mismatch",
+      };
+    }
+
+    expectedPrevHash = hash;
+  }
+
+  return { valid: true, entries: lines.length };
+}
+
+// --- YAML ---
+
+/**
+ * Read YAML file (requires js-yaml). Fail-close if js-yaml unavailable.
+ * @param {string} filePath
+ * @returns {Object}
+ */
+function readYaml(filePath) {
+  let yaml;
+  try {
+    yaml = require("js-yaml");
+  } catch {
+    deny("js-yaml is not installed. Required for YAML operations.");
+  }
+  return yaml.load(fs.readFileSync(filePath, "utf8"));
+}
+
+// --- Command Detection ---
+
+/**
+ * Check if a command exists on the system.
+ * Tries 'which' (Unix/Git Bash) first, then 'where' (Windows cmd).
+ * @param {string} cmd
+ * @returns {boolean}
+ */
+function commandExists(cmd) {
+  // Reject non-alphanumeric command names to prevent injection
+  if (!/^[a-zA-Z0-9_\-]+$/.test(cmd)) {
+    return false;
+  }
+  for (const checker of ["which", "where"]) {
+    try {
+      execSync(`${checker} ${cmd}`, {
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      return true;
+    } catch {
+      // Try next checker
+    }
+  }
+  return false;
+}
+
+// --- Patterns ---
+
+/**
+ * Load injection patterns from JSON file.
+ * Fail-close: if file missing or corrupted, deny.
+ * @returns {Object} parsed patterns
+ */
+function loadPatterns() {
+  if (!fs.existsSync(PATTERNS_FILE)) {
+    deny("injection-patterns.json not found. Run npx shield-harness init.");
+  }
+  try {
+    return JSON.parse(fs.readFileSync(PATTERNS_FILE, "utf8"));
+  } catch {
+    deny("injection-patterns.json is corrupted.");
+  }
+}
+
+module.exports = {
+  // Constants
+  SH_DIR,
+  EVIDENCE_FILE,
+  SESSION_FILE,
+  PATTERNS_FILE,
+  CHAIN_GENESIS_HASH,
+  // Hook I/O
+  readHookInput,
+  allow,
+  allowWithUpdate,
+  allowWithResult,
+  deny,
+  // Normalization
+  nfkcNormalize,
+  normalizePath,
+  // Crypto
+  sha256,
+  // Session
+  readSession,
+  writeSession,
+  // Evidence
+  appendEvidence,
+  // YAML
+  readYaml,
+  // Command Detection
+  commandExists,
+  // Patterns
+  loadPatterns,
+  // Hash Chain
+  verifyHashChain,
+};

package/.claude/hooks/lint-on-save.js

@@ -0,0 +1,240 @@
+"use strict";
+/**
+ * Post-tool hook: Run linter/formatter on source files after Edit/Write.
+ *
+ * Triggered after Edit or Write tools modify files.
+ * - Python files (.py): Runs ruff (format + lint) and ty (type check) if available
+ * - PowerShell files (.ps1, .psm1): Runs PSScriptAnalyzer if available
+ * - Other files: Skips silently
+ *
+ * All tool checks use graceful degradation — missing tools are silently skipped.
+ */
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const { readHookInput } = require("./lib/sh-utils");
+
+// --- Constants ---
+
+const MAX_PATH_LENGTH = 4096;
+const COMMAND_TIMEOUT = 30000;
+
+// --- Path Validation ---
+
+/**
+ * Validate file path for security.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function validatePath(filePath) {
+  if (!filePath || filePath.length > MAX_PATH_LENGTH) return false;
+  if (filePath.includes("..")) return false;
+  return true;
+}
+
+// --- Command Execution ---
+
+/**
+ * Run a command and return { code, stdout, stderr }.
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {string} cwd
+ * @returns {{ code: number, stdout: string, stderr: string }}
+ */
+function runCommand(cmd, args, cwd) {
+  try {
+    const stdout = execFileSync(cmd, args, {
+      cwd,
+      timeout: COMMAND_TIMEOUT,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return { code: 0, stdout: stdout || "", stderr: "" };
+  } catch (e) {
+    if (e.code === "ENOENT") {
+      return { code: -1, stdout: "", stderr: `Command not found: ${cmd}` };
+    }
+    if (e.killed) {
+      return { code: 1, stdout: "", stderr: "Command timed out" };
+    }
+    return {
+      code: e.status || 1,
+      stdout: e.stdout || "",
+      stderr: e.stderr || "",
+    };
+  }
+}
+
+// --- Python Linting ---
+
+/**
+ * Run Python linters (ruff, ty) if available.
+ * @param {string} filePath
+ * @param {string} projectDir
+ * @param {string} relPath
+ * @returns {string[]} issues found
+ */
+function lintPython(filePath, projectDir, relPath) {
+  const issues = [];
+
+  // Run ruff format
+  let result = runCommand(
+    "uv",
+    ["run", "ruff", "format", filePath],
+    projectDir,
+  );
+  if (result.code === -1) return []; // uv not found, skip all Python linting
+  if (result.code !== 0) {
+    issues.push(`ruff format failed:\n${result.stderr || result.stdout}`);
+  }
+
+  // Run ruff check with auto-fix
+  result = runCommand(
+    "uv",
+    ["run", "ruff", "check", "--fix", filePath],
+    projectDir,
+  );
+  if (result.code !== 0) {
+    const output = result.stdout || result.stderr;
+    if (output.trim()) {
+      issues.push(`ruff check issues:\n${output}`);
+    }
+  }
+
+  // Run ty type check
+  result = runCommand("uv", ["run", "ty", "check", filePath], projectDir);
+  if (result.code !== 0) {
+    const output = result.stdout || result.stderr;
+    if (output.trim()) {
+      issues.push(`ty check issues:\n${output}`);
+    }
+  }
+
+  if (issues.length > 0) {
+    process.stderr.write(`[lint-on-save] Issues found in ${relPath}:\n`);
+    for (const issue of issues) {
+      process.stderr.write(issue + "\n");
+    }
+    process.stderr.write("\nPlease review and fix these issues.\n");
+  } else {
+    process.stdout.write(`[lint-on-save] OK: ${relPath} passed all checks\n`);
+  }
+
+  return issues;
+}
+
+// --- PowerShell Linting ---
+
+/**
+ * Escape a string for safe use inside PowerShell single-quoted string.
+ * @param {string} s
+ * @returns {string} escaped string, or empty if unsafe
+ */
+function escapePowershellString(s) {
+  if (s.includes("\x00") || s.includes("\n") || s.includes("\r")) {
+    return "";
+  }
+  return s.replace(/'/g, "''");
+}
+
+/**
+ * Run PowerShell linter (PSScriptAnalyzer) if available.
+ * @param {string} filePath
+ * @param {string} projectDir
+ * @param {string} relPath
+ * @returns {string[]} issues found
+ */
+function lintPowershell(filePath, projectDir, relPath) {
+  const issues = [];
+
+  const safePath = escapePowershellString(filePath);
+  if (!safePath) {
+    process.stderr.write(
+      `[lint-on-save] WARNING: Unsafe path rejected for PSScriptAnalyzer: ${relPath}\n`,
+    );
+    return [];
+  }
+
+  const result = runCommand(
+    "pwsh",
+    [
+      "-NoProfile",
+      "-Command",
+      `Invoke-ScriptAnalyzer -Path '${safePath}' -Severity Warning,Error`,
+    ],
+    projectDir,
+  );
+
+  if (result.code === -1) return []; // pwsh not found, skip
+  if (result.code === 0 && result.stdout.trim()) {
+    process.stderr.write(
+      `[lint-on-save] PSScriptAnalyzer issues in ${relPath}:\n`,
+    );
+    process.stderr.write(result.stdout + "\n");
+    issues.push(result.stdout);
+  } else if (result.code === 0) {
+    process.stdout.write(
+      `[lint-on-save] OK: ${relPath} passed PSScriptAnalyzer\n`,
+    );
+  }
+
+  return issues;
+}
+
+// --- Hook handler ---
+
+/**
+ * @param {object} data - PostToolUse hook input
+ */
+function handler(data) {
+  const toolInput = data.toolInput || data.tool_input || {};
+  const filePath = toolInput.file_path;
+
+  if (!filePath) return;
+  if (!validatePath(filePath)) {
+    process.stderr.write(
+      `[lint-on-save] WARNING: Invalid path rejected: ${filePath}\n`,
+    );
+    return;
+  }
+
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+  let relPath;
+  if (filePath.startsWith(projectDir)) {
+    relPath = path.relative(projectDir, filePath);
+  } else {
+    relPath = filePath;
+  }
+
+  if (filePath.endsWith(".py")) {
+    lintPython(filePath, projectDir, relPath);
+  } else if (filePath.endsWith(".ps1") || filePath.endsWith(".psm1")) {
+    lintPowershell(filePath, projectDir, relPath);
+  }
+  // Other file types: skip silently
+}
+
+// --- Exports (for testing) ---
+
+module.exports = {
+  validatePath,
+  runCommand,
+  lintPython,
+  lintPowershell,
+  escapePowershellString,
+  handler,
+  MAX_PATH_LENGTH,
+  COMMAND_TIMEOUT,
+};
+
+// --- Entry point ---
+
+if (require.main === module) {
+  try {
+    const input = readHookInput();
+    handler(input);
+  } catch (e) {
+    process.stderr.write(`[lint-on-save] Error: ${e.message}\n`);
+  }
+}

package/.claude/hooks/sh-circuit-breaker.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// sh-circuit-breaker.js — Retry loop before agent stops
+// Spec: DETAILED_DESIGN.md §5.2
+// Event: Stop
+// Target response time: < 50ms
+"use strict";
+
+const {
+  readHookInput,
+  allow,
+  deny,
+  readSession,
+  writeSession,
+  appendEvidence,
+} = require("./lib/sh-utils");
+
+const HOOK_NAME = "sh-circuit-breaker";
+const MAX_RETRIES = 3;
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+try {
+  const input = readHookInput();
+  const session = readSession();
+
+  // Step 1: Check stop_hook_active flag (infinite loop prevention)
+  if (session.stop_hook_active === true) {
+    session.stop_hook_active = false;
+    writeSession(session);
+
+    try {
+      appendEvidence({
+        hook: HOOK_NAME,
+        event: "Stop",
+        decision: "allow",
+        reason:
+          "stop_hook_active flag was set — allowing to prevent infinite loop",
+        retry_count: session.retry_count || 0,
+        session_id: input.sessionId,
+      });
+    } catch {
+      // Evidence failure is non-blocking
+    }
+
+    allow(
+      "[sh-circuit-breaker] stop_hook_active detected — allowing stop to prevent loop.",
+    );
+    return;
+  }
+
+  // Step 2: Read and evaluate retry count
+  const currentRetry = (session.retry_count || 0) + 1;
+
+  if (currentRetry > MAX_RETRIES) {
+    // Retry limit reached — allow the stop
+    session.retry_count = 0;
+    session.stop_hook_active = false;
+    writeSession(session);
+
+    try {
+      appendEvidence({
+        hook: HOOK_NAME,
+        event: "Stop",
+        decision: "allow",
+        reason: `Retry limit reached (${MAX_RETRIES}/${MAX_RETRIES})`,
+        retry_count: MAX_RETRIES,
+        session_id: input.sessionId,
+      });
+    } catch {
+      // Evidence failure is non-blocking
+    }
+
+    allow(
+      `[sh-circuit-breaker] リトライ上限（${MAX_RETRIES}回）に到達しました。停止を許可します。`,
+    );
+    return;
+  }
+
+  // Step 3: Retry — deny the stop request
+  session.retry_count = currentRetry;
+  session.stop_hook_active = true;
+  writeSession(session);
+
+  try {
+    appendEvidence({
+      hook: HOOK_NAME,
+      event: "Stop",
+      decision: "deny",
+      reason: `Retry ${currentRetry}/${MAX_RETRIES}`,
+      retry_count: currentRetry,
+      session_id: input.sessionId,
+    });
+  } catch {
+    // Evidence failure is non-blocking
+  }
+
+  deny(
+    `[sh-circuit-breaker] リトライ ${currentRetry}/${MAX_RETRIES}。まだ停止しないでください。別のアプローチを試してください。`,
+  );
+} catch (_err) {
+  // Control hook — fail-open (allow stop on error)
+  allow();
+}
+
+// ---------------------------------------------------------------------------
+// Exports (for testing)
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  MAX_RETRIES,
+};