chainlesschain 0.166.10 → 0.166.13

package/src/lib/hook-audit-store.js

@@ -0,0 +1,170 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { getHomeDir } from "./paths.js";
+import {
+  mutateSecurityStore,
+  readSecurityStore,
+} from "./durable-security-store.js";
+import { stableStringify } from "./hook-runtime-contract.js";
+
+export const HOOK_AUDIT_STORE_SCHEMA =
+  "chainlesschain.hook-runtime-audit-store/v1";
+export const HOOK_AUDIT_RECORD_SCHEMA = "chainlesschain.hook-runtime-audit/v1";
+export const DEFAULT_MAX_HOOK_AUDIT_RECORDS = 10000;
+
+function sha256(label, value) {
+  return crypto
+    .createHash("sha256")
+    .update(`${label}\0`, "utf8")
+    .update(String(value), "utf8")
+    .digest("hex");
+}
+
+function safeToken(value, max = 256) {
+  if (value == null) return null;
+  const text = String(value);
+  return text.length <= max ? text : text.slice(0, max);
+}
+
+function digestToken(value) {
+  if (value == null || value === "") return null;
+  const text = String(value);
+  return /^[a-f0-9]{64}$/iu.test(text)
+    ? text.toLowerCase()
+    : sha256("chainlesschain.hook-audit-token.v1", text);
+}
+
+function normalizeRecord(record = {}) {
+  return {
+    schema: HOOK_AUDIT_RECORD_SCHEMA,
+    timestamp: safeToken(record.timestamp || new Date().toISOString(), 64),
+    phase: safeToken(record.phase, 32),
+    event: safeToken(record.event, 96),
+    eventId: digestToken(record.eventId),
+    executionId: digestToken(record.executionId),
+    hookId: digestToken(record.hookId),
+    hookDigest: digestToken(record.hookDigest),
+    sourceKind: safeToken(record.sourceKind, 32),
+    sourceDigest: digestToken(record.sourceDigest),
+    trustStatus: safeToken(record.trustStatus, 64),
+    priority: Number.isFinite(Number(record.priority))
+      ? Number(record.priority)
+      : null,
+    executionMode: safeToken(record.executionMode, 32),
+    status: safeToken(record.status, 32),
+    decision: safeToken(record.decision, 32),
+    durationMs: Number.isFinite(Number(record.durationMs))
+      ? Math.max(0, Math.floor(Number(record.durationMs)))
+      : null,
+    errorCode: safeToken(record.errorCode, 96),
+  };
+}
+
+function hashRecord(prevHash, record) {
+  return sha256(
+    "chainlesschain.hook-audit-chain.v1",
+    `${prevHash || "genesis"}\n${stableStringify(record)}`,
+  );
+}
+
+function validateStore(store) {
+  if (Object.keys(store).length === 0) {
+    return {
+      schema: HOOK_AUDIT_STORE_SCHEMA,
+      anchorHash: null,
+      headHash: null,
+      records: [],
+    };
+  }
+  if (
+    store.schema !== HOOK_AUDIT_STORE_SCHEMA ||
+    !Array.isArray(store.records) ||
+    (store.anchorHash != null && typeof store.anchorHash !== "string") ||
+    (store.headHash != null && typeof store.headHash !== "string")
+  ) {
+    const error = new Error("Hook audit store has an invalid schema");
+    error.code = "CC_HOOK_AUDIT_STORE_INVALID";
+    throw error;
+  }
+  return store;
+}
+
+export class HookAuditStore {
+  constructor({ filePath, maxRecords, now } = {}) {
+    this.filePath =
+      filePath ||
+      process.env.CC_HOOK_AUDIT_FILE ||
+      path.join(getHomeDir(), "audit", "hook-runtime-v1.json");
+    this.maxRecords = Math.max(
+      100,
+      Math.min(100000, Number(maxRecords) || DEFAULT_MAX_HOOK_AUDIT_RECORDS),
+    );
+    this.now = typeof now === "function" ? now : () => new Date().toISOString();
+  }
+
+  append(record) {
+    const normalized = normalizeRecord({
+      ...record,
+      timestamp: record?.timestamp || this.now(),
+    });
+    return mutateSecurityStore(this.filePath, "Hook runtime audit", (draft) => {
+      const store = validateStore(draft);
+      if (Object.keys(draft).length === 0) Object.assign(draft, store);
+      const prevHash = draft.headHash || draft.anchorHash || null;
+      const hash = hashRecord(prevHash, normalized);
+      draft.records.push({ record: normalized, prevHash, hash });
+      draft.headHash = hash;
+      if (draft.records.length > this.maxRecords) {
+        const removeCount = draft.records.length - this.maxRecords;
+        const removed = draft.records.splice(0, removeCount);
+        draft.anchorHash =
+          removed[removed.length - 1]?.hash || draft.anchorHash;
+      }
+      return Object.freeze({ ...normalized, prevHash, hash });
+    });
+  }
+
+  list({ limit = 100 } = {}) {
+    const store = validateStore(
+      readSecurityStore(this.filePath, "Hook runtime audit"),
+    );
+    return store.records.slice(-Math.max(0, Number(limit) || 0));
+  }
+
+  verify() {
+    const store = validateStore(
+      readSecurityStore(this.filePath, "Hook runtime audit"),
+    );
+    let prev = store.anchorHash || null;
+    for (let index = 0; index < store.records.length; index += 1) {
+      const entry = store.records[index];
+      if (!entry || entry.prevHash !== prev) {
+        return { ok: false, length: store.records.length, brokenAt: index };
+      }
+      const expected = hashRecord(prev, entry.record);
+      if (entry.hash !== expected) {
+        return { ok: false, length: store.records.length, brokenAt: index };
+      }
+      prev = entry.hash;
+    }
+    return {
+      ok: prev === (store.headHash || store.anchorHash || null),
+      length: store.records.length,
+      brokenAt:
+        prev === (store.headHash || store.anchorHash || null)
+          ? -1
+          : store.records.length,
+      headHash: store.headHash || null,
+    };
+  }
+}
+
+let defaultStore;
+export function getDefaultHookAuditStore() {
+  if (!defaultStore) defaultStore = new HookAuditStore();
+  return defaultStore;
+}
+
+export function _resetDefaultHookAuditStore() {
+  defaultStore = undefined;
+}

package/src/lib/hook-manager.js

@@ -6,19 +6,14 @@
 import crypto from "crypto";
 import broker from "./process-execution-broker/index.js";
 import hookEnvironment from "./hook-environment.cjs";
+import { HOOK_EVENT_TYPES, HOOK_PRIORITY } from "./hook-runtime-contract.js";
 
 const { buildManagedHookEnvironment } = hookEnvironment;
 
 /**
  * Hook priority levels — lower values run first.
  */
-export const HookPriority = {
-  SYSTEM: 0,
-  HIGH: 100,
-  NORMAL: 500,
-  LOW: 900,
-  MONITOR: 1000,
-};
+export const HookPriority = HOOK_PRIORITY;
 
 /**
  * Hook execution types.
@@ -33,47 +28,7 @@ export const HookType = {
 /**
  * All supported hook event names.
  */
-export const HookEvents = {
-  Setup: "Setup",
-  PreIPCCall: "PreIPCCall",
-  PostIPCCall: "PostIPCCall",
-  IPCError: "IPCError",
-  PreToolUse: "PreToolUse",
-  PostToolUse: "PostToolUse",
-  ToolError: "ToolError",
-  SessionStart: "SessionStart",
-  SessionEnd: "SessionEnd",
-  PreCompact: "PreCompact",
-  PostCompact: "PostCompact",
-  Notification: "Notification",
-  UserPromptSubmit: "UserPromptSubmit",
-  AssistantResponse: "AssistantResponse",
-  AgentStart: "AgentStart",
-  AgentStop: "AgentStop",
-  TaskAssigned: "TaskAssigned",
-  TaskCompleted: "TaskCompleted",
-  PreFileAccess: "PreFileAccess",
-  PostFileAccess: "PostFileAccess",
-  FileModified: "FileModified",
-  MemorySave: "MemorySave",
-  MemoryLoad: "MemoryLoad",
-  AuditLog: "AuditLog",
-  ComplianceCheck: "ComplianceCheck",
-  DataSubjectRequest: "DataSubjectRequest",
-  PreGitCommit: "PreGitCommit",
-  PostGitCommit: "PostGitCommit",
-  PreGitPush: "PreGitPush",
-  CIFailure: "CIFailure",
-  IterationWarning: "IterationWarning",
-  IterationBudgetExhausted: "IterationBudgetExhausted",
-  /**
-   * Stop: Fired at the END of every agent turn/loop iteration, BEFORE waiting
-   * for the next user input. Aligns with Claude Code hook spec.
-   * Fires regardless of outcome (success, error, max-iterations, stop).
-   * Does NOT fire on final process exit (use SessionEnd/Shutdown for that).
-   */
-  Stop: "Stop",
-};
+export const HookEvents = HOOK_EVENT_TYPES;
 
 /**
  * Ensure hooks table exists in the database.
@@ -290,8 +245,7 @@ export async function executeHook(hook, context = {}) {
       }
       const env = buildManagedHookEnvironment({
         managedAllowlist: hook.managedEnvironmentAllowlist,
-        requestedAllowlist:
-          hook.environmentAllowlist || hook.envAllowlist,
+        requestedAllowlist: hook.environmentAllowlist || hook.envAllowlist,
         values: {
           HOOK_EVENT: hook.event,
           HOOK_CONTEXT: JSON.stringify(context),
@@ -364,39 +318,27 @@ export async function executeHook(hook, context = {}) {
  * Returns array of { hookId, hookName, success, result, error, executionTime }.
  */
 export async function executeHooks(db, eventName, context = {}) {
-  const hooks = listHooks(db, { event: eventName, enabledOnly: true });
-  const results = [];
-
-  for (const hook of hooks) {
-    // Check matcher against context
-    if (hook.matcher) {
-      const matchFn = compileMatcher(hook.matcher);
-      const target =
-        context.target ||
-        context.channel ||
-        context.tool ||
-        context.file ||
-        eventName;
-      if (!matchFn(target)) {
-        continue;
-      }
-    }
-
-    const outcome = await executeHook(hook, context);
-    results.push({
-      hookId: hook.id,
-      hookName: hook.name,
-      ...outcome,
-    });
-
-    // Update stats
-    updateHookStats(db, hook.id, {
-      executionTime: outcome.executionTime,
-      success: outcome.success,
-    });
-  }
-
-  return results;
+  // Compatibility API: SQLite rows are definitions only. All scheduling,
+  // timeout, trust, decision and audit semantics belong to Hooks v2.
+  const { executeHooksV2Event } = await import("./hooks-v2-producers.js");
+  const outcome = await executeHooksV2Event(eventName, context, {
+    hookDb: db,
+    matchTarget:
+      context.target ||
+      context.channel ||
+      context.tool_name ||
+      context.tool ||
+      context.file ||
+      eventName,
+  });
+  return (outcome.results || []).map((record) => ({
+    hookId: record.sourceHookId || record.hookId,
+    hookName: record.hookName || record.hookId,
+    success: record.status === "success",
+    result: record.result?.raw ?? record.result ?? null,
+    error: record.error || null,
+    executionTime: record.durationMs || 0,
+  }));
 }
 
 /**

package/src/lib/hook-runtime-adapters.js

@@ -0,0 +1,233 @@
+import crypto from "node:crypto";
+import settingsHookLoader from "./settings-hooks.cjs";
+import {
+  HOOK_EXECUTION_MODE,
+  HOOK_PRIORITY,
+  normalizeHookPriority,
+  normalizeHookTimeoutMs,
+  stableStringify,
+} from "./hook-runtime-contract.js";
+import { computeHookDefinitionDigest } from "./hook-trust.js";
+
+const { collectHooks, compileMatcher } = settingsHookLoader;
+
+function adapterId(prefix, value) {
+  return `${prefix}:${crypto
+    .createHash("sha256")
+    .update(stableStringify(value), "utf8")
+    .digest("hex")}`;
+}
+
+function settingsAuthority(authoritySource = {}) {
+  const scope =
+    authoritySource.scope ||
+    (authoritySource.kind === "plugin"
+      ? "plugin"
+      : authoritySource.sourceFile
+        ? "project"
+        : "explicit");
+  return Object.freeze({
+    kind: authoritySource.kind || "settings",
+    sourceFile: authoritySource.sourceFile || null,
+    digest: authoritySource.digest || null,
+    scope,
+    requiresConsent: scope === "project",
+  });
+}
+
+export function adaptSettingsHookDefinitions(
+  settingsHooks,
+  event,
+  matchTarget = "",
+  { cwd = process.cwd(), failureMode = "fail-closed" } = {},
+) {
+  const authorityErrors = settingsHooks?._authorityErrors;
+  if (Array.isArray(authorityErrors) && authorityErrors.length > 0) {
+    const error = new Error(
+      "Settings Hook authority could not be loaded safely",
+    );
+    error.code = authorityErrors[0]?.code || "CC_HOOK_AUTHORITY_INVALID";
+    error.authorityErrors = authorityErrors;
+    throw error;
+  }
+  return collectHooks(settingsHooks, event, matchTarget).map((hook, index) => {
+    const authority = settingsAuthority(hook.authoritySource);
+    const identity = {
+      event,
+      command: hook.command,
+      shell: hook.shell ?? true,
+      authority,
+      index,
+    };
+    const definition = {
+      id: adapterId("settings", identity),
+      event,
+      type: "command",
+      command: hook.command,
+      shell: hook.shell == null ? true : hook.shell,
+      cwd,
+      priority: normalizeHookPriority(hook.priority, HOOK_PRIORITY.NORMAL),
+      timeoutMs: normalizeHookTimeoutMs(
+        hook.timeout == null ? undefined : Number(hook.timeout) * 1000,
+      ),
+      executionMode:
+        hook.async === true
+          ? HOOK_EXECUTION_MODE.ASYNC
+          : HOOK_EXECUTION_MODE.BLOCKING,
+      asyncRewake: hook.asyncRewake === true,
+      legacyPayload: true,
+      legacyAdapter: true,
+      legacyHook: hook,
+      origin: hook.origin || "settings",
+      authority,
+      environmentAllowlist:
+        hook.environmentAllowlist || hook.envAllowlist || undefined,
+      sandboxPolicy: hook.sandboxPolicy,
+      requiredBoundaries: hook.requiredBoundaries,
+      pluginId: hook.pluginId || null,
+      pluginVersion: hook.pluginVersion || null,
+      pluginSource: hook.pluginSource || null,
+      failureMode: failureMode === "ignore" ? "ignore" : "fail-closed",
+    };
+    definition.definitionDigest = computeHookDefinitionDigest(definition);
+    return Object.freeze(definition);
+  });
+}
+
+function databaseMatchTarget(context, event) {
+  return (
+    context.target ||
+    context.channel ||
+    context.tool_name ||
+    context.tool ||
+    context.file ||
+    event
+  );
+}
+
+export function readDatabaseHookRows(db, event) {
+  if (!db || typeof db.prepare !== "function") return [];
+  return db
+    .prepare(
+      "SELECT * FROM hooks WHERE event = ? AND enabled = 1 ORDER BY priority ASC, id ASC",
+    )
+    .all(event);
+}
+
+function databaseReadFailureDefinition(event) {
+  const authority = Object.freeze({
+    kind: "database",
+    scope: "explicit",
+    subject: "database:hook-observer",
+    requiresConsent: false,
+  });
+  const definition = {
+    id: `database:adapter-read-failure:${event}`,
+    event,
+    type: "js",
+    handler() {
+      const error = new Error(
+        "Database Hook observer source could not be read",
+      );
+      error.code = "CC_HOOK_DATABASE_READ_FAILED";
+      throw error;
+    },
+    priority: HOOK_PRIORITY.NORMAL,
+    timeoutMs: normalizeHookTimeoutMs(),
+    executionMode: HOOK_EXECUTION_MODE.BLOCKING,
+    origin: "database",
+    authority,
+    failureMode: "ignore",
+    observeOnly: true,
+    databaseHookName: "database-hook-observer",
+  };
+  definition.definitionDigest = computeHookDefinitionDigest(definition);
+  return Object.freeze(definition);
+}
+
+export function adaptDatabaseHookDefinitions(db, event, context = {}) {
+  const target = databaseMatchTarget(context, event);
+  const definitions = [];
+  let rows;
+  try {
+    rows = readDatabaseHookRows(db, event);
+  } catch {
+    // Database hooks are a legacy, observe-only source. A missing table or an
+    // unavailable optional database must remain visible in the canonical
+    // audit/event stream, but it cannot acquire decision authority merely by
+    // failing to load.
+    return [databaseReadFailureDefinition(event)];
+  }
+  for (const row of rows) {
+    if (row.matcher && !compileMatcher(row.matcher)(target)) continue;
+    const commandBacked = new Set(["command", "script"]).has(row.type);
+    const authority = Object.freeze({
+      kind: "database",
+      scope: "explicit",
+      subject: `database:${row.id}`,
+      requiresConsent: false,
+    });
+    const definition = {
+      id: `database:${row.id}`,
+      event,
+      type: commandBacked ? "command" : "js",
+      ...(commandBacked
+        ? { command: row.handler || "", shell: true }
+        : { handler: () => null }),
+      priority: normalizeHookPriority(row.priority, HOOK_PRIORITY.NORMAL),
+      timeoutMs: normalizeHookTimeoutMs(row.timeout),
+      executionMode:
+        row.type === "async"
+          ? HOOK_EXECUTION_MODE.ASYNC
+          : HOOK_EXECUTION_MODE.BLOCKING,
+      legacyPayload: true,
+      legacyAdapter: true,
+      origin: "database",
+      authority,
+      failureMode: "ignore",
+      observeOnly: true,
+      databaseHookId: row.id,
+      databaseHookName: row.name,
+      recordResult(record) {
+        const success = record?.status === "success";
+        const executionTime = Math.max(0, Number(record?.durationMs) || 0);
+        const current = db
+          .prepare(
+            "SELECT execution_count, error_count, total_execution_time FROM hooks WHERE id = ?",
+          )
+          .get(row.id);
+        if (!current) return;
+        db.prepare(
+          `UPDATE hooks
+             SET execution_count = ?,
+                 error_count = ?,
+                 total_execution_time = ?,
+                 updated_at = datetime('now')
+           WHERE id = ?`,
+        ).run(
+          (current.execution_count || 0) + 1,
+          (current.error_count || 0) + (success ? 0 : 1),
+          (current.total_execution_time || 0) + executionTime,
+          row.id,
+        );
+      },
+    };
+    definition.definitionDigest = computeHookDefinitionDigest(definition);
+    definitions.push(Object.freeze(definition));
+  }
+  return definitions;
+}
+
+export function collectCanonicalAdapterHooks(
+  event,
+  context,
+  { settingsHooks, hookDb, matchTarget, cwd, settingsFailureMode } = {},
+) {
+  return [
+    ...adaptSettingsHookDefinitions(settingsHooks, event, matchTarget, {
+      cwd,
+      failureMode: settingsFailureMode,
+    }),
+    ...adaptDatabaseHookDefinitions(hookDb, event, context),
+  ];
+}