chainlesschain 0.162.188 → 0.162.193

package/src/lib/settings-hooks.cjs

@@ -78,19 +78,55 @@ function settingsFiles(cwd, explicitFile) {
   return list;
 }
 
-function readJson(file, onWarn) {
+function sha256Content(content) {
+  return crypto
+    .createHash("sha256")
+    .update(Buffer.isBuffer(content) ? content : String(content))
+    .digest("hex");
+}
+
+function readJsonRecord(
+  file,
+  onWarn,
+  { kind = "settings", errors = null } = {},
+) {
+  if (!_deps.fs.existsSync(file)) return null;
+  let raw = null;
   try {
-    if (!_deps.fs.existsSync(file)) return null;
-    const parsed = JSON.parse(_deps.fs.readFileSync(file, "utf-8"));
-    return parsed && typeof parsed === "object" ? parsed : null;
+    raw = _deps.fs.readFileSync(file, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new TypeError("settings root must be a JSON object");
+    }
+    return {
+      data: parsed,
+      digest: sha256Content(raw),
+      sourceFile: path.resolve(file),
+    };
   } catch (err) {
     const msg = `hooks: ignoring malformed ${file} (${err.message})`;
+    const record = Object.freeze({
+      code:
+        kind === "managed"
+          ? "CC_MANAGED_SETTINGS_INVALID"
+          : "CC_SETTINGS_HOOKS_INVALID",
+      kind,
+      sourceFile: path.resolve(file),
+      digest: raw == null ? null : sha256Content(raw),
+      authorityBearing: true,
+      message: msg,
+    });
+    if (Array.isArray(errors)) errors.push(record);
     if (typeof onWarn === "function") onWarn(msg);
     else process.stderr.write(msg + "\n");
-    return null; // fail-open
+    return null;
   }
 }
 
+function readJson(file, onWarn) {
+  return readJsonRecord(file, onWarn)?.data || null;
+}
+
 function managedSettingsFile(env = process.env) {
   if (env.CC_MANAGED_SETTINGS) return path.resolve(env.CC_MANAGED_SETTINGS);
   if (process.platform === "win32") {
@@ -100,7 +136,31 @@ function managedSettingsFile(env = process.env) {
   return "/etc/chainlesschain/managed-settings.json";
 }
 
-function appendHookBlock(merged, data) {
+function attachAuthoritySource(target, source) {
+  if (!source) return target;
+  const authoritySource = Object.freeze({
+    kind:
+      source.kind === "managed"
+        ? "managed"
+        : source.kind === "plugin"
+          ? "plugin"
+          : "settings",
+    sourceFile:
+      typeof source.sourceFile === "string" && source.sourceFile
+        ? path.resolve(source.sourceFile)
+        : null,
+    digest: String(source.digest || ""),
+  });
+  Object.defineProperty(target, "authoritySource", {
+    value: authoritySource,
+    enumerable: true,
+    writable: false,
+    configurable: false,
+  });
+  return target;
+}
+
+function appendHookBlock(merged, data, authoritySource) {
   const block =
     data && data.hooks && typeof data.hooks === "object" ? data.hooks : null;
   if (!block) return false;
@@ -109,9 +169,9 @@ function appendHookBlock(merged, data) {
     if (!Array.isArray(groups)) continue;
     for (const g of groups) {
       if (!g || typeof g !== "object" || !Array.isArray(g.hooks)) continue;
-      const cmds = g.hooks.filter(
-        (h) => h && h.type === "command" && h.command,
-      );
+      const cmds = g.hooks
+        .filter((h) => h && h.type === "command" && h.command)
+        .map((h) => attachAuthoritySource({ ...h }, authoritySource));
       if (cmds.length === 0) continue;
       if (!merged[event]) merged[event] = [];
       merged[event].push({ matcher: g.matcher ?? null, hooks: cmds });
@@ -123,7 +183,7 @@ function appendHookBlock(merged, data) {
 
 /**
  * Load + concatenate the `hooks` blocks across the hierarchy.
- * @returns {{ hooks: Record<string, Array<{matcher:string|null, hooks:Array<{type,command,timeout}>}>>, files:string[] }}
+ * @returns {{ hooks: Record<string, Array<{matcher:string|null, hooks:Array<{type,command,timeout,authoritySource?}>}>>, files:string[], authorityErrors?:Array<object> }}
  */
 function loadHooks({
   cwd = process.cwd(),
@@ -133,15 +193,23 @@ function loadHooks({
 } = {}) {
   const merged = {};
   const files = [];
+  const authorityErrors = [];
   const managedFile = managedSettingsFile(env);
   let managed = null;
+  let managedRecord = null;
   if (_deps.fs.existsSync(managedFile)) {
-    managed = readJson(managedFile, onWarn);
-    if (!managed) {
+    const managedErrors = [];
+    managedRecord = readJsonRecord(managedFile, onWarn, {
+      kind: "managed",
+      errors: managedErrors,
+    });
+    managed = managedRecord?.data || null;
+    if (!managedRecord) {
       const error = new Error(
         `managed settings are unreadable or malformed: ${managedFile}`,
       );
       error.code = "CC_MANAGED_SETTINGS_INVALID";
+      if (managedErrors[0]) error.authorityError = managedErrors[0];
       throw error;
     }
   }
@@ -160,12 +228,33 @@ function loadHooks({
     const resolved = path.resolve(file);
     if (seenPaths.has(resolved)) continue;
     seenPaths.add(resolved);
-    const data = readJson(file, onWarn);
-    const contributed = appendHookBlock(merged, data);
+    const record = readJsonRecord(file, onWarn, {
+      kind: "settings",
+      errors: authorityErrors,
+    });
+    const contributed = record
+      ? appendHookBlock(merged, record.data, {
+          kind: "settings",
+          sourceFile: record.sourceFile,
+          digest: record.digest,
+        })
+      : false;
     if (contributed) files.push(file);
   }
-  if (managed && appendHookBlock(merged, managed)) files.push(managedFile);
+  if (
+    managedRecord &&
+    appendHookBlock(merged, managed, {
+      kind: "managed",
+      sourceFile: managedRecord.sourceFile,
+      digest: managedRecord.digest,
+    })
+  ) {
+    files.push(managedFile);
+  }
   const result = { hooks: merged, files };
+  if (authorityErrors.length > 0) {
+    result.authorityErrors = authorityErrors;
+  }
   if (managed) {
     result.managed = managed;
     result.managedFile = managedFile;
@@ -173,6 +262,32 @@ function loadHooks({
   return result;
 }
 
+/**
+ * Preserve loader failures across plugin-hook merging without making them look
+ * like a hook event. The runtime consumes this non-enumerable, immutable host
+ * metadata and blocks tool execution rather than running a partial authority
+ * set. Returns an object even when there are no valid hooks but errors exist.
+ */
+function attachAuthorityErrors(hooks, errors) {
+  const target = hooks && typeof hooks === "object" ? hooks : {};
+  const normalized = Array.isArray(errors)
+    ? errors.map((entry) =>
+        Object.freeze({
+          sourceFile: entry?.sourceFile || entry?.file || null,
+          code: entry?.code || "CC_HOOK_AUTHORITY_INVALID",
+          message: entry?.message || null,
+        }),
+      )
+    : [];
+  Object.defineProperty(target, "_authorityErrors", {
+    value: Object.freeze(normalized),
+    enumerable: false,
+    writable: false,
+    configurable: false,
+  });
+  return target;
+}
+
 /**
  * Compile a matcher into a test fn (pipe / wildcard / regex). Inlined twin of
  * hook-manager.compileMatcher so this .cjs has no ESM dependency.
@@ -224,7 +339,7 @@ function umbrellaFor(tool) {
  * `event` is stamped on each hook so a supervisor can key runs by (event+cmd).
  *
  * @returns {Array<{command:string, timeout?:number, event:string,
- *                  async:boolean, asyncRewake:boolean}>}
+ *                  async:boolean, asyncRewake:boolean, authoritySource?:object}>}
  */
 function collectHooks(hooksBlock, event, toolName) {
   const groups = (hooksBlock && hooksBlock[event]) || [];
@@ -245,8 +360,8 @@ function collectHooks(hooksBlock, event, toolName) {
   for (const g of groups) {
     const fn = compileMatcher(g.matcher);
     if (fn(umbrella) || (raw && fn(raw)) || (mcpServer && fn(mcpServer))) {
-      for (const h of g.hooks)
-        out.push({
+      for (const h of g.hooks) {
+        const collected = {
           command: h.command,
           timeout: h.timeout,
           event,
@@ -260,16 +375,16 @@ function collectHooks(hooksBlock, event, toolName) {
           ...(h.environmentAllowlist != null
             ? { environmentAllowlist: h.environmentAllowlist }
             : {}),
-          ...(h.envAllowlist != null
-            ? { envAllowlist: h.envAllowlist }
-            : {}),
+          ...(h.envAllowlist != null ? { envAllowlist: h.envAllowlist } : {}),
           ...(h.sandboxPolicy !== undefined
             ? { sandboxPolicy: h.sandboxPolicy }
             : {}),
           ...(h.requiredBoundaries !== undefined
             ? { requiredBoundaries: h.requiredBoundaries }
             : {}),
-        });
+        };
+        out.push(attachAuthoritySource(collected, h.authoritySource));
+      }
     }
   }
   return out;
@@ -413,6 +528,7 @@ function projectHookTrustNotice({ cwd = process.cwd(), settingsFile } = {}) {
 
 module.exports = {
   loadHooks,
+  attachAuthorityErrors,
   projectHookTrustNotice,
   collectHooks,
   compileMatcher,

package/src/lib/settings-loader.cjs

@@ -294,13 +294,22 @@ function addRule({ cwd = process.cwd(), kind, rule, scope = "project" } = {}) {
  * model / env vars for a run without editing .chainlesschain/config.json.
  *
  * @param {object} [opts] { cwd, settingsFile, onWarn }
- * @returns {{ model: string|null, env: Record<string,string>, files: string[] }}
+ * @returns {{
+ *   model: string|null,
+ *   modelSource: string|null,
+ *   env: Record<string,string>,
+ *   envSources: Record<string,string>,
+ *   files: string[]
+ * }}
  */
 function loadSettingsConfig(opts = {}) {
   const cwd = opts.cwd || process.cwd();
   let model = null;
+  let modelSource = null;
   const env = {};
+  const envSources = {};
   let sandbox = null;
+  let managedSandbox = null;
   const files = [];
   for (const file of settingsPaths(cwd, opts.settingsFile)) {
     const data = readSettingsFile(file, { onWarn: opts.onWarn });
@@ -308,12 +317,14 @@ function loadSettingsConfig(opts = {}) {
     let contributed = false;
     if (typeof data.model === "string" && data.model.trim()) {
       model = data.model.trim();
+      modelSource = file;
       contributed = true;
     }
     if (data.env && typeof data.env === "object" && !Array.isArray(data.env)) {
       for (const [k, v] of Object.entries(data.env)) {
         if (typeof v === "string") {
           env[k] = v;
+          envSources[k] = file;
           contributed = true;
         }
       }
@@ -334,12 +345,14 @@ function loadSettingsConfig(opts = {}) {
     let contributed = false;
     if (typeof data.model === "string" && data.model.trim()) {
       model = data.model.trim();
+      modelSource = managed.file;
       contributed = true;
     }
     if (data.env && typeof data.env === "object" && !Array.isArray(data.env)) {
       for (const [k, v] of Object.entries(data.env)) {
         if (typeof v === "string") {
           env[k] = v;
+          envSources[k] = managed.file;
           contributed = true;
         }
       }
@@ -349,12 +362,22 @@ function loadSettingsConfig(opts = {}) {
       typeof data.sandbox === "object" &&
       !Array.isArray(data.sandbox)
     ) {
+      managedSandbox = JSON.parse(JSON.stringify(data.sandbox));
       sandbox = mergeSandboxSettings(sandbox, data.sandbox);
       contributed = true;
     }
     if (contributed) files.push(managed.file);
   }
-  return { model, env, sandbox, files };
+  return {
+    model,
+    modelSource,
+    env,
+    envSources,
+    sandbox,
+    managedSandbox,
+    files,
+    managedFile: managed.settings ? managed.file : null,
+  };
 }
 
 function mergeSandboxSettings(base, overlay) {

package/src/lib/side-effect-ledger-store.js

@@ -12,6 +12,7 @@
 import {
   appendEvent as storeAppendEvent,
   readEvents as storeReadEvents,
+  findLatestEvent as storeFindLatestEvent,
 } from "../harness/jsonl-session-store.js";
 import {
   SideEffectLedger,
@@ -24,14 +25,38 @@ export const SIDE_EFFECT_LEDGER_EVENT = "side_effect_ledger";
 export const _deps = {
   appendEvent: storeAppendEvent,
   readEvents: storeReadEvents,
+  findLatestEvent: storeFindLatestEvent,
 };
 
+function findLatestLedgerEvent(sessionId) {
+  if (
+    typeof _deps.findLatestEvent === "function" &&
+    _deps.findLatestEvent !== storeFindLatestEvent
+  ) {
+    return _deps.findLatestEvent(sessionId, SIDE_EFFECT_LEDGER_EVENT);
+  }
+  // Existing tests and embedders historically injected only readEvents.
+  if (_deps.readEvents !== storeReadEvents) {
+    const events = _deps.readEvents(sessionId) || [];
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+      const event = events[index];
+      if (event?.type === SIDE_EFFECT_LEDGER_EVENT) return event;
+    }
+    return null;
+  }
+  return storeFindLatestEvent(sessionId, SIDE_EFFECT_LEDGER_EVENT);
+}
+
 export class SideEffectLedgerPersistenceError extends Error {
   constructor(operation, sessionId, cause) {
-    const detail = cause?.message || String(cause || "unknown persistence error");
-    super(`Side-effect ledger ${operation} failed for ${sessionId}: ${detail}`, {
-      cause,
-    });
+    const detail =
+      cause?.message || String(cause || "unknown persistence error");
+    super(
+      `Side-effect ledger ${operation} failed for ${sessionId}: ${detail}`,
+      {
+        cause,
+      },
+    );
     this.name = "SideEffectLedgerPersistenceError";
     this.code =
       operation === "read"
@@ -91,9 +116,9 @@ export function persistSideEffectLedger(sessionId, ledger, opts = {}) {
  */
 export function loadSideEffectLedger(sessionId, opts = {}) {
   const failIfUnavailable = opts.failIfUnavailable !== false;
-  let events = [];
+  let event = null;
   try {
-    events = _deps.readEvents(sessionId) || [];
+    event = findLatestLedgerEvent(sessionId);
   } catch (error) {
     const fallback = persistenceFailure(
       "read",
@@ -103,25 +128,22 @@ export function loadSideEffectLedger(sessionId, opts = {}) {
     );
     if (fallback === false) return new SideEffectLedger(opts);
   }
-  for (let i = events.length - 1; i >= 0; i--) {
-    const e = events[i];
-    if (
-      e &&
-      e.type === SIDE_EFFECT_LEDGER_EVENT &&
-      e.data &&
-      Array.isArray(e.data.ops)
-    ) {
-      try {
-        return SideEffectLedger.fromJSON(e.data, opts);
-      } catch (error) {
-        const fallback = persistenceFailure(
-          "read",
-          sessionId || "<missing-session>",
-          error,
-          failIfUnavailable,
+  if (event) {
+    try {
+      if (!Array.isArray(event?.data?.ops)) {
+        throw new TypeError(
+          "latest side-effect ledger snapshot must contain an ops array",
         );
-        if (fallback === false) return new SideEffectLedger(opts);
       }
+      return SideEffectLedger.fromJSON(event.data, opts);
+    } catch (error) {
+      const fallback = persistenceFailure(
+        "read",
+        sessionId || "<missing-session>",
+        error,
+        failIfUnavailable,
+      );
+      if (fallback === false) return new SideEffectLedger(opts);
     }
   }
   return new SideEffectLedger(opts);

package/src/lib/skill-execution-identity.js

@@ -0,0 +1,217 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export const SKILL_EXECUTION_IDENTITY_VERSION = 1;
+
+const EXECUTION_REASONS = new Set(["run_skill", "cli_skill_run"]);
+
+function sha256(parts) {
+  const digest = createHash("sha256");
+  for (const part of parts) {
+    const bytes = Buffer.isBuffer(part) ? part : Buffer.from(String(part));
+    digest.update(String(bytes.length));
+    digest.update("\0");
+    digest.update(bytes);
+    digest.update("\0");
+  }
+  return `sha256:${digest.digest("hex")}`;
+}
+
+function canonicalRealPath(value) {
+  let result = fs.realpathSync(path.resolve(value)).replace(/\\/g, "/");
+  if (process.platform === "win32") result = result.toLowerCase();
+  return result;
+}
+
+function securityError(code, message, details = {}) {
+  const error = new Error(
+    message,
+    details.cause ? { cause: details.cause } : {},
+  );
+  error.name = "SkillExecutionSecurityError";
+  error.code = code;
+  if (details.skillId) error.skillId = details.skillId;
+  if (details.previousDigest) error.previousDigest = details.previousDigest;
+  if (details.currentDigest) error.currentDigest = details.currentDigest;
+  return error;
+}
+
+function readStableRegularFile(file, options = {}) {
+  let before;
+  try {
+    before = fs.lstatSync(file);
+  } catch (cause) {
+    if (options.optional && cause?.code === "ENOENT") return null;
+    throw securityError(
+      "CC_SKILL_COMPONENT_UNAVAILABLE",
+      `Skill component is unavailable: ${path.basename(file)}`,
+      { cause },
+    );
+  }
+  if (before.isSymbolicLink() || !before.isFile()) {
+    throw securityError(
+      "CC_SKILL_COMPONENT_UNSAFE",
+      `Skill component must be a regular, non-symlink file: ${path.basename(file)}`,
+    );
+  }
+
+  const bytes = fs.readFileSync(file);
+  const after = fs.lstatSync(file);
+  if (
+    before.size !== after.size ||
+    before.mtimeMs !== after.mtimeMs ||
+    before.ino !== after.ino
+  ) {
+    throw securityError(
+      "CC_SKILL_SNAPSHOT_RACE",
+      `Skill component changed while its identity was being captured: ${path.basename(file)}`,
+    );
+  }
+  return Object.freeze({
+    bytes,
+    size: bytes.length,
+    digest: sha256([bytes]),
+  });
+}
+
+/**
+ * Capture the exact files the legacy runtime could execute or interpret.
+ * SKILL.md covers frontmatter, instructions, and embedded MCP declarations;
+ * handler.js covers the only handler path used by current CLI dispatch.
+ */
+export function captureSkillExecutionSnapshot(options = {}) {
+  if (!options.skillDir) {
+    throw new TypeError("captureSkillExecutionSnapshot requires skillDir");
+  }
+  const rootRealPath = canonicalRealPath(options.skillDir);
+  const skillMdPath = path.join(rootRealPath, "SKILL.md");
+  const handlerPath = path.join(rootRealPath, "handler.js");
+  const skillMd = readStableRegularFile(skillMdPath);
+  const handler = readStableRegularFile(handlerPath, { optional: true });
+  const skillId = String(options.skillId || path.basename(rootRealPath));
+  const source = String(options.source || "unknown");
+  const identityDigest = sha256([
+    `skill-execution-identity-v${SKILL_EXECUTION_IDENTITY_VERSION}`,
+    source,
+    skillId,
+    rootRealPath,
+  ]);
+  const contentDigest = sha256([
+    `skill-execution-content-v${SKILL_EXECUTION_IDENTITY_VERSION}`,
+    "SKILL.md",
+    skillMd.digest,
+    "handler.js",
+    handler?.digest || "absent",
+  ]);
+
+  return Object.freeze({
+    schemaVersion: SKILL_EXECUTION_IDENTITY_VERSION,
+    identityDigest,
+    contentDigest,
+    rootRealPath,
+    handlerPresent: handler !== null,
+    skillFileBytes: skillMd.size,
+    componentDigests: Object.freeze({
+      "SKILL.md": skillMd.digest,
+      "handler.js": handler?.digest || null,
+    }),
+    // Kept only in the short-lived verification snapshot. Callers must store
+    // executionIdentityMetadata(snapshot), never this content-bearing object.
+    skillMdContent: skillMd.bytes.toString("utf8"),
+  });
+}
+
+/** Produce the content-free descriptor safe to retain in loader caches. */
+export function executionIdentityMetadata(snapshot) {
+  return Object.freeze({
+    schemaVersion: snapshot.schemaVersion,
+    identityDigest: snapshot.identityDigest,
+    contentDigest: snapshot.contentDigest,
+    rootRealPath: snapshot.rootRealPath,
+    handlerPresent: snapshot.handlerPresent,
+    componentDigests: Object.freeze({ ...snapshot.componentDigests }),
+  });
+}
+
+export function describeSkillExecutionAuthority(skill = {}) {
+  const hasHandler = skill.hasHandler === true;
+  const isolated = skill.isolation === true;
+  return Object.freeze({
+    schemaVersion: SKILL_EXECUTION_IDENTITY_VERSION,
+    mode: !hasHandler
+      ? "instructions-only"
+      : isolated
+        ? "controlled-agent-tools"
+        : "blocked-direct-handler",
+    directHandlerAllowed: false,
+    controlledToolEntryRequired: hasHandler,
+  });
+}
+
+export function isSkillExecutionContext(context = {}) {
+  return (
+    context.forExecution === true ||
+    EXECUTION_REASONS.has(String(context.loadedBecause || ""))
+  );
+}
+
+/**
+ * The only currently mediated handler-skill route is agent-core's explicit
+ * isolated-skill branch. It executes an agent loop whose tool calls re-enter
+ * host policy; it never imports handler.js. Every direct-handler route is
+ * denied until a restricted worker/RPC transport exists.
+ */
+export function assertControlledSkillExecution(skill, context = {}) {
+  if (!isSkillExecutionContext(context) || skill?.hasHandler !== true) {
+    return describeSkillExecutionAuthority(skill);
+  }
+
+  const reason = String(context.loadedBecause || "");
+  if (reason === "run_skill" && skill.isolation === true) {
+    return describeSkillExecutionAuthority(skill);
+  }
+
+  throw securityError(
+    "CC_SKILL_DIRECT_HANDLER_BLOCKED",
+    `Skill "${skill.id || "unknown"}" cannot execute handler.js directly. ` +
+      "Use an isolated agent/tool route so every external call re-enters host policy.",
+    { skillId: skill.id },
+  );
+}
+
+export function skillDigestDriftError(skill, previousDigest, currentDigest) {
+  return securityError(
+    "CC_SKILL_DIGEST_DRIFT",
+    `Skill "${skill.id || "unknown"}" changed after discovery and was not reauthorized.`,
+    {
+      skillId: skill.id,
+      previousDigest,
+      currentDigest,
+    },
+  );
+}
+
+export function skillIdentityChangedError(skill) {
+  return securityError(
+    "CC_SKILL_IDENTITY_CHANGED",
+    `Skill "${skill.id || "unknown"}" changed identity after discovery; reload the skill registry before use.`,
+    { skillId: skill.id },
+  );
+}
+
+export function skillReauthorizationError(skill, cause) {
+  return securityError(
+    "CC_SKILL_REAUTHORIZE_FAILED",
+    `Skill "${skill.id || "unknown"}" digest reauthorization failed.`,
+    { skillId: skill.id, cause },
+  );
+}
+
+export function skillTrustRequiredError(skill) {
+  return securityError(
+    "CC_SKILL_TRUST_REQUIRED",
+    `Skill "${skill.id || "unknown"}" requires host authorization for its current source and content digest before first execution.`,
+    { skillId: skill.id },
+  );
+}