chainlesschain 0.166.84 → 0.166.86

package/src/lib/settings-loader.cjs

@@ -50,6 +50,7 @@ const _deps = {
   writeSecurityStore: (...args) => securityStore().writeSecurityStore(...args),
   withFileLock: (...args) => lockHelper()(...args),
 };
+const settingsObservations = new WeakSet();
 
 // A process-wide owner deliberately revokes unrelated projects too. Matching
 // only contributing paths misses absent files, parent discovery and aliases.
@@ -145,9 +146,11 @@ function accrete(target, sources, arr, file, kind) {
 }
 
 /** The ordered list of candidate settings files for a cwd. */
-function settingsPaths(cwd, explicitFile) {
+function settingsPaths(cwd, explicitFile, userSettingsFile = null) {
   const home = _deps.homedir();
-  const list = [path.join(home, ".claude", "settings.json")];
+  const list = [
+    userSettingsFile || path.join(home, ".claude", "settings.json"),
+  ];
   // When run from a subdirectory, the project-root `.claude` sits BELOW cwd's
   // own (closest wins) but ABOVE the user layer — so its rules apply yet a
   // cwd-local settings file still overrides them. Null when cwd IS the root.
@@ -170,10 +173,10 @@ function settingsPaths(cwd, explicitFile) {
 function inspectSettingsSources(opts = {}) {
   const cwd = path.resolve(opts.cwd || process.cwd());
   const candidates = [
-    ...settingsPaths(cwd, opts.settingsFile),
+    ...settingsPaths(cwd, opts.settingsFile, opts.userSettingsFile),
     managedSettingsPath(opts),
   ];
-  return Object.freeze({
+  const observation = Object.freeze({
     schema: "chainlesschain.settings-source-observation/v1",
     cwd,
     sources: observeSettingsSources(candidates, {
@@ -181,6 +184,8 @@ function inspectSettingsSources(opts = {}) {
       maxBytes: opts.maxBytes,
     }),
   });
+  settingsObservations.add(observation);
+  return observation;
 }
 
 /** Organization-controlled settings file. This layer is always highest. */
@@ -273,13 +278,50 @@ function loadSettings(opts = {}) {
   const cwd = opts.cwd || process.cwd();
   const env = opts.env || process.env;
   const onWarn = opts.onWarn;
+  function* layers() {
+    for (const file of settingsPaths(cwd, opts.settingsFile)) {
+      yield { file, settings: readSettingsFile(file, { onWarn }) };
+    }
+  }
+  return mergePermissionSettings(layers(), env, () =>
+    loadManagedSettings({
+      env,
+      managedSettingsFile: opts.managedSettingsFile,
+      onWarn,
+    }),
+  );
+}
 
+/**
+ * Project the exact JSON trees read and hashed by inspectSettingsSources.
+ * No path discovery or filesystem read occurs here. The final source has the
+ * managed role even when an earlier explicit/user/project source has the same
+ * path; retaining both positions preserves precedence and provenance.
+ *
+ * This is a byte-bound projection, not a fresh authority check or an atomic
+ * inventory snapshot. Environment inputs retain their existing sampling rules.
+ */
+function projectSettingsObservation(observation, { env = {} } = {}) {
+  if (!settingsObservations.has(observation)) {
+    throw new TypeError("A strict settings source observation is required");
+  }
+  const managed = observation.sources[observation.sources.length - 1];
+  return mergePermissionSettings(
+    observation.sources.slice(0, -1).map((source) => ({
+      file: source.logicalPath,
+      settings: source.settings,
+    })),
+    env,
+    () => ({ file: managed.logicalPath, settings: managed.settings }),
+  );
+}
+
+function mergePermissionSettings(layers, env, readManaged) {
   let rules = emptyRules();
   const sources = {};
   const files = [];
 
-  for (const file of settingsPaths(cwd, opts.settingsFile)) {
-    const data = readSettingsFile(file, { onWarn });
+  for (const { file, settings: data } of layers) {
     if (!data) continue;
     const perms =
       data.permissions && typeof data.permissions === "object"
@@ -308,11 +350,7 @@ function loadSettings(opts = {}) {
   }
   if (envContributed) files.push("<env>");
 
-  const managedLoaded = loadManagedSettings({
-    env,
-    managedSettingsFile: opts.managedSettingsFile,
-    onWarn,
-  });
+  const managedLoaded = readManaged();
   if (managedLoaded.settings) {
     rules = applyManagedPermissionPolicy(
       rules,
@@ -354,7 +392,38 @@ function scopeFile(cwd, scope) {
  * @returns {{ file:string, added:boolean }} added=false → already present.
  * @throws if the target file exists but is malformed JSON (refuse to clobber).
  */
-function addRule({ cwd = process.cwd(), kind, rule, scope = "project" } = {}) {
+function appendPermissionRule(data, file, kind, rule) {
+  if (
+    Object.hasOwn(data, "permissions") &&
+    (!data.permissions ||
+      typeof data.permissions !== "object" ||
+      Array.isArray(data.permissions))
+  )
+    throw new TypeError(`refusing to overwrite malformed permissions: ${file}`);
+  data.permissions ??= {};
+  for (const decision of KINDS) {
+    if (
+      Object.hasOwn(data.permissions, decision) &&
+      (!Array.isArray(data.permissions[decision]) ||
+        data.permissions[decision].some((entry) => typeof entry !== "string"))
+    )
+      throw new TypeError(
+        `refusing to overwrite malformed permission rules: ${file}`,
+      );
+  }
+  data.permissions[kind] ??= [];
+  if (data.permissions[kind].includes(rule)) return false;
+  data.permissions[kind].push(rule);
+  return true;
+}
+
+function addRule({
+  cwd = process.cwd(),
+  kind,
+  rule,
+  scope = "project",
+  settingsAuthority = null,
+} = {}) {
   const entryCwd = process.cwd();
   const absoluteCwd = path.resolve(entryCwd, cwd);
   // Check before lock acquisition: notification callbacks may reenter here.
@@ -368,11 +437,38 @@ function addRule({ cwd = process.cwd(), kind, rule, scope = "project" } = {}) {
   if (!["project", "local", "user"].includes(scope)) {
     throw new TypeError("scope must be project | local | user");
   }
-  const file = path.resolve(entryCwd, scopeFile(absoluteCwd, scope));
-  _deps.fs.mkdirSync(path.dirname(file), { recursive: true });
+  let file = path.resolve(entryCwd, scopeFile(absoluteCwd, scope));
+  if (settingsAuthority !== null) {
+    const authority = require("./settings-permission-authority.cjs");
+    const bound =
+      authority.settingsPermissionAuthorityOptions(settingsAuthority);
+    if (absoluteCwd !== bound.cwd)
+      throw new TypeError("settings authority cwd mismatch");
+    if (scope === "user") file = bound.userSettingsFile;
+  } else _deps.fs.mkdirSync(path.dirname(file), { recursive: true });
   let began = false;
   let committed = false;
   try {
+    if (settingsAuthority !== null) {
+      const authority = require("./settings-permission-authority.cjs");
+      const result = authority.mutateSettingsPermissionSource(
+        settingsAuthority,
+        {
+          logicalPath: file,
+          prepare: (data) => appendPermissionRule(data, file, kind, rule),
+          revokeLocal() {
+            beginSettingsMutation();
+            began = true;
+          },
+          replace(physicalPath, data) {
+            _deps.writeSecurityStore(physicalPath, "settings", data);
+            committed = true;
+          },
+        },
+      );
+      if (began) finishSettingsMutation("ready");
+      return { file, added: result.changed };
+    }
     const result = _deps.withFileLock(
       file,
       () => {
@@ -387,35 +483,8 @@ function addRule({ cwd = process.cwd(), kind, rule, scope = "project" } = {}) {
           );
         }
         const data = _deps.readSecurityStore(file, "settings");
-        if (
-          Object.hasOwn(data, "permissions") &&
-          (!data.permissions ||
-            typeof data.permissions !== "object" ||
-            Array.isArray(data.permissions))
-        ) {
-          throw new TypeError(
-            `refusing to overwrite malformed permissions: ${file}`,
-          );
-        }
-        data.permissions ??= {};
-        // Refuse to hide a damaged rule list, including a different decision.
-        for (const decision of KINDS) {
-          if (
-            Object.hasOwn(data.permissions, decision) &&
-            (!Array.isArray(data.permissions[decision]) ||
-              data.permissions[decision].some(
-                (entry) => typeof entry !== "string",
-              ))
-          ) {
-            throw new TypeError(
-              `refusing to overwrite malformed permission rules: ${file}`,
-            );
-          }
-        }
-        data.permissions[kind] ??= [];
-        if (data.permissions[kind].includes(rule))
+        if (!appendPermissionRule(data, file, kind, rule))
           return { file, added: false };
-        data.permissions[kind].push(rule);
         beginSettingsMutation();
         began = true;
         _deps.writeSecurityStore(file, "settings", data);
@@ -662,6 +731,7 @@ function readStringArraySetting(key, opts = {}) {
 
 module.exports = {
   inspectSettingsSources,
+  projectSettingsObservation,
   loadSettings,
   loadSettingsConfig,
   readSettingsFile,

package/src/lib/settings-permission-authority.cjs

@@ -0,0 +1,373 @@
+"use strict";
+
+// Trusted-host, cooperative Linux binding. Only explicit provisioning creates
+// an authority; a reader/writer never registers or repairs a missing domain.
+const path = require("node:path");
+const { types } = require("node:util");
+const { createHash } = require("node:crypto");
+const fs = require("node:fs");
+const { observeSettingsSources } = require("./settings-source-observation.cjs");
+const domain = require("./settings-authority-domain.cjs");
+const records = require("./settings-authority-record.cjs");
+const bindings = new WeakMap();
+const SCHEMA = "chainlesschain.settings-permission-launch/v1";
+const loader = () => require("./settings-loader.cjs");
+
+function fail(code = "CC_SETTINGS_PERMISSION_BINDING_INVALID") {
+  throw Object.assign(
+    new Error("Persistent settings permission binding is unavailable"),
+    { code },
+  );
+}
+
+function dataCopy(input, depth = 0) {
+  if (input === null || ["string", "boolean", "number"].includes(typeof input))
+    return input;
+  if (!input || typeof input !== "object" || types.isProxy(input) || depth > 12)
+    fail();
+  const array = Array.isArray(input);
+  if (
+    !array &&
+    ![Object.prototype, null].includes(Object.getPrototypeOf(input))
+  )
+    fail();
+  const output = array ? [] : {};
+  const keys = Reflect.ownKeys(input);
+  if (keys.length > 1024) fail();
+  for (const key of keys) {
+    if (array && key === "length") continue;
+    const descriptor = Object.getOwnPropertyDescriptor(input, key);
+    if (
+      typeof key !== "string" ||
+      !descriptor ||
+      !Object.hasOwn(descriptor, "value") ||
+      key === "__proto__" ||
+      (array && !/^(0|[1-9][0-9]*)$/.test(key))
+    )
+      fail();
+    output[key] = dataCopy(descriptor.value, depth + 1);
+  }
+  if (
+    array &&
+    (output.length !== input.length ||
+      Object.keys(output).length !== input.length)
+  )
+    fail();
+  return Object.freeze(output);
+}
+
+function exactKeys(value, keys) {
+  if (
+    !value ||
+    Array.isArray(value) ||
+    Object.keys(value).sort().join(",") !== [...keys].sort().join(",")
+  )
+    fail();
+}
+
+function absolute(value) {
+  if (
+    typeof value !== "string" ||
+    !value ||
+    !path.isAbsolute(value) ||
+    path.resolve(value) !== value
+  )
+    fail();
+  return value;
+}
+
+function captureContexts(input, captured = false) {
+  const contexts = dataCopy(input);
+  if (!Array.isArray(contexts) || !contexts.length || contexts.length > 64)
+    fail();
+  const ids = new Set();
+  return Object.freeze(
+    contexts.map((context) => {
+      const fields = [
+        "contextId",
+        "cwd",
+        "settingsFile",
+        "managedSettingsFile",
+        "userSettingsFile",
+        "scopedFile",
+      ];
+      if (captured) exactKeys(context, fields);
+      else if (Object.keys(context).some((key) => !fields.includes(key)))
+        fail();
+      if (
+        typeof context.contextId !== "string" ||
+        !/^[a-zA-Z0-9._:-]{1,128}$/.test(context.contextId) ||
+        ids.has(context.contextId)
+      )
+        fail();
+      ids.add(context.contextId);
+      const cwd = captured
+        ? absolute(context.cwd)
+        : path.resolve(context.cwd || process.cwd());
+      const settingsFile =
+        context.settingsFile === null || context.settingsFile === undefined
+          ? null
+          : captured
+            ? absolute(context.settingsFile)
+            : path.resolve(cwd, context.settingsFile);
+      const managedSettingsFile = captured
+        ? absolute(context.managedSettingsFile)
+        : loader().managedSettingsPath(context);
+      const userSettingsFile = captured
+        ? absolute(context.userSettingsFile)
+        : context.userSettingsFile
+          ? path.resolve(context.userSettingsFile)
+          : loader().scopeFile(cwd, "user");
+      const scopedFile = captured
+        ? absolute(context.scopedFile)
+        : context.scopedFile
+          ? path.resolve(context.scopedFile)
+          : require("./scoped-permission-store.js").defaultScopedPermissionStatePath(
+              cwd,
+            );
+      return Object.freeze({
+        contextId: context.contextId,
+        cwd,
+        settingsFile,
+        managedSettingsFile: path.resolve(managedSettingsFile),
+        userSettingsFile: path.resolve(userSettingsFile),
+        scopedFile,
+      });
+    }),
+  );
+}
+
+function observe(contexts) {
+  const observations = new Map();
+  const manifests = contexts.map((context) => {
+    const observation = loader().inspectSettingsSources(context);
+    const scopedObservation = observeSettingsSources([context.scopedFile])[0];
+    observations.set(context.contextId, { observation, scopedObservation });
+    return records.createManifest({
+      contextId: context.contextId,
+      discovery: [
+        context.cwd,
+        context.userSettingsFile,
+        context.managedSettingsFile,
+        ...(context.settingsFile ? [context.settingsFile] : []),
+        context.scopedFile,
+      ],
+      sources: [...observation.sources, scopedObservation],
+    });
+  });
+  return { observations, manifests };
+}
+
+function observer(contexts, save = () => {}) {
+  return (expected) => {
+    if (
+      expected.length !== contexts.length ||
+      expected.some(
+        (context, index) => context.contextId !== contexts[index].contextId,
+      )
+    )
+      fail("CC_SETTINGS_AUTHORITY_BINDING_CHANGED");
+    // Recompute the complete discovery route, never reuse ledger source paths.
+    const current = observe(contexts);
+    save(current.observations);
+    return current.manifests;
+  };
+}
+
+/** Explicit administrator/host provisioning. Parent directories must exist. */
+function initializeSettingsPermissionAuthority({
+  directory,
+  forbiddenRoots,
+  contexts,
+}) {
+  const captured = captureContexts(contexts);
+  const initial = observe(captured);
+  const handle = domain.initializeSettingsAuthorityDomain({
+    directory,
+    forbiddenRoots: [
+      ...new Set([
+        ...forbiddenRoots,
+        ...captured.map((context) => context.cwd),
+      ]),
+    ],
+    contexts: initial.manifests,
+    observeContexts: observer(captured),
+  });
+  try {
+    return dataCopy({
+      schema: SCHEMA,
+      domain: domain.exportSettingsAuthorityDomain(handle),
+      contexts: captured,
+    });
+  } finally {
+    domain.closeSettingsAuthorityDomain(handle);
+  }
+}
+
+/** Reopen a fixed launch descriptor in a process or Worker; never bootstrap. */
+function openSettingsPermissionAuthority({ launch, contextId }) {
+  launch = dataCopy(launch);
+  exactKeys(launch, ["schema", "domain", "contexts"]);
+  if (launch.schema !== SCHEMA) fail();
+  const contexts = captureContexts(launch.contexts, true);
+  const selected = contexts.find((context) => context.contextId === contextId);
+  if (!selected) fail("CC_SETTINGS_AUTHORITY_CONTEXT_UNREGISTERED");
+  const handle = domain.reopenSettingsAuthorityDomain({
+    descriptor: launch.domain,
+  });
+  const binding = Object.freeze({});
+  const state = { handle, launch, contexts, selected, closed: false };
+  bindings.set(binding, state);
+  try {
+    readSettingsPermissionAuthority(binding);
+    return binding;
+  } catch (error) {
+    closeSettingsPermissionAuthority(binding);
+    throw error;
+  }
+}
+
+function stateFor(binding) {
+  const state = bindings.get(binding);
+  if (!state || state.closed) fail();
+  return state;
+}
+
+function settingsPermissionAuthorityOptions(binding) {
+  return stateFor(binding).selected;
+}
+
+function exportSettingsPermissionAuthority(binding) {
+  const state = stateFor(binding);
+  domain.exportSettingsAuthorityDomain(state.handle); // Verify namespace first.
+  return state.launch;
+}
+
+function readSettingsPermissionAuthority(binding, { forUpdate = false } = {}) {
+  const state = stateFor(binding);
+  let observations;
+  const read = forUpdate
+    ? domain.readSettingsAuthorityForUpdate
+    : domain.readSettingsAuthority;
+  const result = read(state.handle, {
+    observeContexts: observer(state.contexts, (value) => {
+      observations = value;
+    }),
+    localRevision: () => localRevision(state),
+  });
+  const observed = observations.get(state.selected.contextId);
+  return Object.freeze({
+    snapshot: result.snapshot,
+    observation: observed.observation,
+    scopedObservation: observed.scopedObservation,
+  });
+}
+
+function localRevision(state) {
+  const settings = loader().getSettingsPermissionRevision();
+  const scoped =
+    require("./scoped-permission-store.js").getScopedPermissionRevision();
+  if (
+    state.localRevision?.settings !== settings ||
+    state.localRevision?.scoped !== scoped
+  )
+    state.localRevision = Object.freeze({ settings, scoped });
+  return state.localRevision;
+}
+
+// Keep the observation's minting and projection within one loader instance.
+// Hosts with an ESM transform loader can also load CJS through native require;
+// the native observation must still pass its original private WeakSet brand.
+function projectSettingsPermissionObservation(observation, options) {
+  return loader().projectSettingsObservation(observation, options);
+}
+
+function assertSettingsPermissionWritableRoots(binding, roots) {
+  const state = stateFor(binding);
+  const directory = domain.exportSettingsAuthorityDomain(
+    state.handle,
+  ).directory;
+  for (const root of roots) {
+    const canonical = fs.realpathSync(absolute(root));
+    const overlaps = [
+      path.relative(canonical, directory),
+      path.relative(directory, canonical),
+    ].some(
+      (relative) =>
+        relative === "" ||
+        (!relative.startsWith(".." + path.sep) &&
+          relative !== ".." &&
+          !path.isAbsolute(relative)),
+    );
+    if (overlaps) fail("CC_SETTINGS_AUTHORITY_DOMAIN_OVERLAP");
+  }
+}
+
+// Used only by the official synchronous settings writer. Callbacks remain a
+// trusted host contract; no callback or arbitrary source enters launch data.
+function mutateSettingsPermissionSource(
+  binding,
+  { logicalPath, prepare, revokeLocal, replace },
+) {
+  const state = stateFor(binding);
+  logicalPath = absolute(logicalPath);
+  for (let attempt = 0; attempt < 8; attempt++) {
+    const current = readSettingsPermissionAuthority(binding, {
+      forUpdate: true,
+    });
+    const source = [
+      ...current.observation.sources,
+      current.scopedObservation,
+    ].find((item) => item.logicalPath === logicalPath);
+    if (!source) fail("CC_SETTINGS_AUTHORITY_SOURCE_UNREGISTERED");
+    const data = JSON.parse(JSON.stringify(source.settings || {}));
+    if (prepare(data) === false)
+      return { changed: false, snapshot: current.snapshot };
+    const bytes = Buffer.from(`${JSON.stringify(data, null, 2)}\n`);
+    if (bytes.length > 1024 * 1024) fail("CC_SETTINGS_SOURCE_TOO_LARGE");
+    try {
+      return domain.transitionSettingsAuthority(state.handle, {
+        intent: {
+          kind: "write",
+          physicalPath: source.physicalPath,
+          after: {
+            exists: true,
+            byteLength: bytes.length,
+            digest: createHash("sha256").update(bytes).digest("hex"),
+          },
+        },
+        expectedSnapshot: current.snapshot,
+        localRevision: () => localRevision(state),
+        observeContexts: observer(state.contexts),
+        revokeLocal,
+        replace: () => replace(source.physicalPath, data),
+      });
+    } catch (error) {
+      if (
+        error.cause?.code !== "CC_SETTINGS_AUTHORITY_CONFLICT" ||
+        error.commitState !== "not-committed" ||
+        error.authorityState !== "unchanged"
+      )
+        throw error;
+    }
+  }
+  fail("CC_SETTINGS_AUTHORITY_CONFLICT");
+}
+
+function closeSettingsPermissionAuthority(binding) {
+  const state = stateFor(binding);
+  domain.closeSettingsAuthorityDomain(state.handle);
+  state.closed = true;
+}
+
+module.exports = {
+  initializeSettingsPermissionAuthority,
+  openSettingsPermissionAuthority,
+  exportSettingsPermissionAuthority,
+  closeSettingsPermissionAuthority,
+  settingsPermissionAuthorityOptions,
+  readSettingsPermissionAuthority,
+  projectSettingsPermissionObservation,
+  mutateSettingsPermissionSource,
+  assertSettingsPermissionWritableRoots,
+};