chainlesschain 0.163.8 → 0.165.1

package/src/lib/runtime-provenance-ledger.js

@@ -1,16 +1,51 @@
 /**
- * RuntimeProvenanceLedger - Immutable audit trail for runtime provenance
+ * RuntimeProvenanceLedger - bounded, hash-chained runtime provenance.
  *
- * Records every context source, tool call, and response that flows through
- * the CLI runtime. Provides hash-chained immutability guarantees.
+ * Records context sources, tool calls and responses that flow through the CLI
+ * runtime. The in-memory view is deliberately a retained window: every entry
+ * keeps an absolute index, and the hash of the last evicted entry anchors the
+ * first retained entry. Exports state explicitly when older entries are no
+ * longer resident instead of claiming that the retained suffix is a complete
+ * history.
  */
 
 import { createHash } from "node:crypto";
 
+export const DEFAULT_RUNTIME_PROVENANCE_MAX_ENTRIES = 4_096;
+const DEFAULT_GENESIS_HASH = "0".repeat(64);
+
+function positiveEntryLimit(value) {
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new TypeError(
+      "runtime provenance maxEntries must be a positive integer",
+    );
+  }
+  return parsed;
+}
+
+function freezeJsonSnapshot(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    for (const nested of Object.values(value)) freezeJsonSnapshot(nested);
+    Object.freeze(value);
+  }
+  return value;
+}
+
 class RuntimeProvenanceLedger {
   constructor(options = {}) {
-    this._entries = [];
-    this._lastHash = options.genesisHash || "0000000000000000000000000000000000000000000000000000000000000000";
+    this._maxEntries = positiveEntryLimit(
+      options.maxEntries ?? DEFAULT_RUNTIME_PROVENANCE_MAX_ENTRIES,
+    );
+    this._genesisHash = options.genesisHash || DEFAULT_GENESIS_HASH;
+    this._lastHash = this._genesisHash;
+    this._entries = new Array(this._maxEntries);
+    this._retainedStart = 0;
+    this._retainedCount = 0;
+    this._nextIndex = 0;
+    this._evictedThroughIndex = null;
+    this._evictedThroughHash = null;
+    this._entriesByIndex = new Map();
     this._spanIndex = new Map();
     this._traceIndex = new Map();
   }
@@ -94,97 +129,187 @@ class RuntimeProvenanceLedger {
     });
   }
 
+  _addIndex(index, key, absoluteIndex) {
+    if (!key) return;
+    let bucket = index.get(key);
+    if (!bucket) {
+      bucket = new Set();
+      index.set(key, bucket);
+    }
+    bucket.add(absoluteIndex);
+  }
+
+  _removeIndex(index, key, absoluteIndex) {
+    if (!key) return;
+    const bucket = index.get(key);
+    if (!bucket) return;
+    bucket.delete(absoluteIndex);
+    if (bucket.size === 0) index.delete(key);
+  }
+
+  _evictOldest() {
+    const evicted = this._entries[this._retainedStart];
+    if (!evicted) {
+      throw new Error("runtime provenance ring is internally inconsistent");
+    }
+    this._entriesByIndex.delete(evicted.index);
+    this._removeIndex(this._traceIndex, evicted.traceId, evicted.index);
+    this._removeIndex(this._spanIndex, evicted.span, evicted.index);
+    this._evictedThroughIndex = evicted.index;
+    this._evictedThroughHash = evicted.hash;
+    this._entries[this._retainedStart] = undefined;
+    this._retainedStart = (this._retainedStart + 1) % this._maxEntries;
+    this._retainedCount -= 1;
+  }
+
+  _retainedEntries() {
+    const retained = new Array(this._retainedCount);
+    for (let offset = 0; offset < this._retainedCount; offset += 1) {
+      retained[offset] =
+        this._entries[(this._retainedStart + offset) % this._maxEntries];
+    }
+    return retained;
+  }
+
+  _retainedAnchorHash() {
+    return this._evictedThroughHash || this._genesisHash;
+  }
+
   /**
-   * Append entry with hash chaining for immutability
+   * Append an entry with an absolute index and hash-chain binding.
    */
   _append(entry) {
-    const entryWithHash = {
-      ...entry,
-      index: this._entries.length,
+    // The returned entries are also the ring's storage records. Snapshot the
+    // caller's JSON data before hashing so later mutations cannot invalidate
+    // the hash chain, then recursively freeze the snapshot so storage keys
+    // used during eviction cannot be rewritten through get/export results.
+    const payload = { ...entry };
+    delete payload.index;
+    delete payload.prevHash;
+    delete payload.hash;
+    const serialized = JSON.stringify({
+      ...payload,
+      index: this._nextIndex,
       prevHash: this._lastHash,
-    };
-    // Compute hash
-    const hash = createHash("sha256")
-      .update(JSON.stringify(entryWithHash))
-      .digest("hex");
-    entryWithHash.hash = hash;
-    this._entries.push(entryWithHash);
+    });
+    const snapshot = JSON.parse(serialized);
+    const hash = createHash("sha256").update(serialized).digest("hex");
+    snapshot.hash = hash;
+    const entryWithHash = freezeJsonSnapshot(snapshot);
+
+    if (this._retainedCount === this._maxEntries) this._evictOldest();
+    const writeIndex =
+      (this._retainedStart + this._retainedCount) % this._maxEntries;
+    this._entries[writeIndex] = entryWithHash;
+    this._retainedCount += 1;
+    this._entriesByIndex.set(entryWithHash.index, entryWithHash);
+    this._addIndex(
+      this._traceIndex,
+      entryWithHash.traceId,
+      entryWithHash.index,
+    );
+    this._addIndex(this._spanIndex, entryWithHash.span, entryWithHash.index);
+    this._nextIndex += 1;
     this._lastHash = hash;
-    // Index
-    if (entry.traceId) {
-      if (!this._traceIndex.has(entry.traceId)) this._traceIndex.set(entry.traceId, []);
-      this._traceIndex.get(entry.traceId).push(entryWithHash.index);
-    }
-    if (entry.span) {
-      if (!this._spanIndex.has(entry.span)) this._spanIndex.set(entry.span, []);
-      this._spanIndex.get(entry.span).push(entryWithHash.index);
-    }
     return entryWithHash;
   }
 
   /**
-   * Verify entire chain integrity
+   * Verify the retained suffix and its independently stored boundary anchor.
    */
   verifyIntegrity() {
-    let currentHash = this._entries[0]?.prevHash || "0".repeat(64);
-    for (const entry of this._entries) {
-      const { hash, prevHash, ...rest } = entry;
-      if (prevHash !== currentHash) return false;
-      const computed = createHash("sha256").update(JSON.stringify({ ...rest, prevHash: currentHash })).digest("hex");
+    const entries = this._retainedEntries();
+    let currentHash = this._retainedAnchorHash();
+    let expectedIndex =
+      this._evictedThroughIndex === null ? 0 : this._evictedThroughIndex + 1;
+    for (const entry of entries) {
+      if (entry.index !== expectedIndex || entry.prevHash !== currentHash) {
+        return false;
+      }
+      const { hash } = entry;
+      const entryForHash = { ...entry };
+      delete entryForHash.hash;
+      const computed = createHash("sha256")
+        .update(JSON.stringify(entryForHash))
+        .digest("hex");
       if (computed !== hash) return false;
       currentHash = hash;
+      expectedIndex += 1;
     }
-    return true;
+    return currentHash === this._lastHash && expectedIndex === this._nextIndex;
+  }
+
+  _indexedEntries(index, key) {
+    const indices = index.get(key);
+    if (!indices) return [];
+    return [...indices]
+      .map((absoluteIndex) => this._entriesByIndex.get(absoluteIndex))
+      .filter(Boolean);
   }
 
   /**
-   * Get all entries for a trace
+   * Get retained entries for a trace.
    */
   getTraceEntries(traceId) {
-    const indices = this._traceIndex.get(traceId) || [];
-    return indices.map(i => this._entries[i]);
+    return this._indexedEntries(this._traceIndex, traceId);
   }
 
   /**
-   * Get all entries for a span
+   * Get retained entries for a span.
    */
   getSpanEntries(spanId) {
-    const indices = this._spanIndex.get(spanId) || [];
-    return indices.map(i => this._entries[i]);
+    return this._indexedEntries(this._spanIndex, spanId);
   }
 
   /**
-   * Get provenance chain for a response
+   * Get the retained provenance window for a response.
    */
   getProvenance(options = {}) {
     if (options.traceId) return this.getTraceEntries(options.traceId);
     if (options.span) return this.getSpanEntries(options.span);
-    return [...this._entries];
+    return this._retainedEntries();
   }
 
   /**
-   * Export ledger to JSON (for persistence/debugging)
+   * Export the retained window without presenting it as complete history.
    */
   export() {
+    const entries = this._retainedEntries();
+    const evictedEntries = this._nextIndex - entries.length;
+    const truncated = evictedEntries > 0;
     return {
-      genesisHash: this._entries[0]?.prevHash,
+      // Compatibility: genesisHash remains the hash immediately before the
+      // first exported entry, just as it was when every entry was retained.
+      genesisHash: entries[0]?.prevHash,
+      originalGenesisHash: this._genesisHash,
       lastHash: this._lastHash,
-      entries: this._entries,
+      entries,
       verified: this.verifyIntegrity(),
+      verificationScope: truncated ? "retained-window" : "complete",
+      totalEntries: this._nextIndex,
+      retainedEntries: entries.length,
+      evictedEntries,
+      truncated,
+      anchor: {
+        hash: this._retainedAnchorHash(),
+        evictedThroughIndex: this._evictedThroughIndex,
+        firstRetainedIndex: entries[0]?.index ?? null,
+      },
       exportedAt: new Date().toISOString(),
     };
   }
 
   /**
-   * Flush pending entries to disk (called on exit)
+   * Flush pending entries to disk (called on exit).
    */
   flush() {
-    // In production this would persist to disk; for now we're in-memory
+    // In production this would persist to disk; for now the bounded retained
+    // window and its eviction anchor remain available in memory.
     return Promise.resolve(true);
   }
 }
 
-// Export global singleton instance
+// Export global singleton instance.
 const runtimeProvenanceLedger = new RuntimeProvenanceLedger();
 export default runtimeProvenanceLedger;
 export { RuntimeProvenanceLedger, runtimeProvenanceLedger };

package/src/lib/scoped-permission-store.js

@@ -0,0 +1,369 @@
+/**
+ * Workspace-bound, expiring permission rules owned by the CLI.
+ *
+ * The state lives outside the repository so an agent cannot authorize itself
+ * by editing a project file. Mutations use the shared durable security store:
+ * cross-process lock, atomic replace, fsync, and fail-closed corrupt reads.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import projectRoot from "./project-root.cjs";
+import permissionRules from "./permission-rules.cjs";
+import { getMachineSecurityAnchorDir } from "./paths.js";
+import {
+  mutateSecurityStore,
+  readSecurityStore,
+} from "./durable-security-store.js";
+
+const { findGitProjectRoot } = projectRoot;
+const { parseRule } = permissionRules;
+
+const STATE_SCHEMA = "cc.scoped-permission-rules";
+const STATE_SCHEMA_VERSION = 1;
+const STORE_LABEL = "scoped permission";
+const RULE_ID_PATTERN = /^spr_[0-9a-f]{32}$/;
+const DECISIONS = new Set(["allow", "ask", "deny"]);
+const DEFAULT_MAX_RECORDS = 1000;
+
+export const SCOPED_PERMISSION_ERROR_CODES = Object.freeze({
+  INVALID: "CC_SCOPED_PERMISSION_INVALID",
+  CONFLICT: "CC_SCOPED_PERMISSION_CONFLICT",
+  NOT_FOUND: "CC_SCOPED_PERMISSION_NOT_FOUND",
+  CORRUPT: "CC_SCOPED_PERMISSION_CORRUPT",
+});
+
+function scopedPermissionError(code, message, cause = null) {
+  const error = new Error(message);
+  error.code = code;
+  if (cause) error.cause = cause;
+  return error;
+}
+
+function canonicalWorkspaceRoot(cwd) {
+  const resolved = path.resolve(cwd || process.cwd());
+  const root = findGitProjectRoot(resolved) || resolved;
+  let canonical = root;
+  try {
+    canonical = fs.realpathSync.native(root);
+  } catch {
+    // A missing/unreadable cwd will be rejected by the caller that uses it.
+  }
+  const normalized = path.normalize(canonical);
+  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+function workspaceBinding(cwd) {
+  const root = canonicalWorkspaceRoot(cwd);
+  const id = createHash("sha256")
+    .update(`cc-scoped-permission-workspace-v1\n${root}`, "utf8")
+    .digest("hex");
+  return Object.freeze({ id, root });
+}
+
+export function defaultScopedPermissionStatePath(cwd = process.cwd()) {
+  const workspace = workspaceBinding(cwd);
+  return path.join(
+    getMachineSecurityAnchorDir(),
+    "permission-center",
+    "workspaces",
+    `${workspace.id}.json`,
+  );
+}
+
+function emptyState(workspace) {
+  return {
+    schema: STATE_SCHEMA,
+    schemaVersion: STATE_SCHEMA_VERSION,
+    generation: 0,
+    updatedAt: null,
+    workspace,
+    rules: [],
+  };
+}
+
+function validateRecord(record, seenIds) {
+  if (
+    !record ||
+    !RULE_ID_PATTERN.test(record.id || "") ||
+    seenIds.has(record.id) ||
+    !DECISIONS.has(record.decision) ||
+    !parseRule(record.rule) ||
+    !Number.isInteger(record.revision) ||
+    record.revision < 1 ||
+    !Number.isFinite(record.createdAt) ||
+    !Number.isFinite(record.expiresAt) ||
+    record.expiresAt <= record.createdAt ||
+    (record.revokedAt !== null && !Number.isFinite(record.revokedAt)) ||
+    typeof record.reason !== "string" ||
+    record.reason.length > 500
+  ) {
+    throw scopedPermissionError(
+      SCOPED_PERMISSION_ERROR_CODES.CORRUPT,
+      "Scoped permission state contains an invalid rule record",
+    );
+  }
+  seenIds.add(record.id);
+}
+
+function validateState(value, workspace) {
+  if (
+    !value ||
+    value.schema !== STATE_SCHEMA ||
+    value.schemaVersion !== STATE_SCHEMA_VERSION ||
+    !Number.isInteger(value.generation) ||
+    value.generation < 0 ||
+    !value.workspace ||
+    value.workspace.id !== workspace.id ||
+    value.workspace.root !== workspace.root ||
+    !Array.isArray(value.rules)
+  ) {
+    throw scopedPermissionError(
+      SCOPED_PERMISSION_ERROR_CODES.CORRUPT,
+      "Scoped permission state has an invalid schema or workspace binding",
+    );
+  }
+  const seenIds = new Set();
+  for (const record of value.rules) validateRecord(record, seenIds);
+  return value;
+}
+
+function statusFor(record, now) {
+  if (record.revokedAt !== null) return "revoked";
+  if (record.expiresAt <= now) return "expired";
+  return "active";
+}
+
+function projectRecord(record, now, filePath) {
+  return Object.freeze({
+    ...structuredClone(record),
+    status: statusFor(record, now),
+    source: "cli-security-store",
+    sourceFile: filePath,
+    scope: "workspace",
+  });
+}
+
+export class ScopedPermissionStore {
+  constructor({
+    cwd = process.cwd(),
+    filePath = null,
+    now = () => Date.now(),
+    maxRecords = DEFAULT_MAX_RECORDS,
+    lock = undefined,
+    randomId = () => `spr_${randomUUID().replaceAll("-", "")}`,
+  } = {}) {
+    this.workspace = workspaceBinding(cwd);
+    this.filePath = path.resolve(
+      filePath || defaultScopedPermissionStatePath(this.workspace.root),
+    );
+    const relativeToWorkspace = path.relative(
+      this.workspace.root,
+      this.filePath,
+    );
+    if (
+      relativeToWorkspace === "" ||
+      (!relativeToWorkspace.startsWith("..") &&
+        !path.isAbsolute(relativeToWorkspace))
+    ) {
+      throw scopedPermissionError(
+        SCOPED_PERMISSION_ERROR_CODES.INVALID,
+        "Scoped permission authority must be stored outside the workspace",
+      );
+    }
+    this._now = typeof now === "function" ? now : () => Number(now);
+    this.maxRecords = Math.max(
+      1,
+      Math.floor(Number(maxRecords) || DEFAULT_MAX_RECORDS),
+    );
+    this._lock = lock;
+    this._randomId = randomId;
+  }
+
+  _read() {
+    const stored = readSecurityStore(this.filePath, STORE_LABEL);
+    if (Object.keys(stored).length === 0) return emptyState(this.workspace);
+    return validateState(stored, this.workspace);
+  }
+
+  list() {
+    const state = this._read();
+    const now = this._now();
+    return Object.freeze({
+      schema: state.schema,
+      schemaVersion: state.schemaVersion,
+      generation: state.generation,
+      updatedAt: state.updatedAt,
+      workspace: structuredClone(state.workspace),
+      file: this.filePath,
+      rules: state.rules.map((record) =>
+        projectRecord(record, now, this.filePath),
+      ),
+    });
+  }
+
+  add({
+    decision,
+    rule,
+    expiresAt,
+    reason = "",
+    expectedGeneration = null,
+  } = {}) {
+    const normalizedDecision = String(decision || "")
+      .trim()
+      .toLowerCase();
+    const normalizedRule = String(rule || "").trim();
+    const normalizedReason = String(reason || "").trim();
+    const now = this._now();
+    const expiry = Number(expiresAt);
+    if (!DECISIONS.has(normalizedDecision)) {
+      throw scopedPermissionError(
+        SCOPED_PERMISSION_ERROR_CODES.INVALID,
+        "decision must be allow | ask | deny",
+      );
+    }
+    if (!parseRule(normalizedRule)) {
+      throw scopedPermissionError(
+        SCOPED_PERMISSION_ERROR_CODES.INVALID,
+        "rule must be a valid Tool or Tool(pattern) permission rule",
+      );
+    }
+    if (!Number.isFinite(expiry) || expiry <= now) {
+      throw scopedPermissionError(
+        SCOPED_PERMISSION_ERROR_CODES.INVALID,
+        "expiresAt must be a future timestamp",
+      );
+    }
+    if (normalizedReason.length > 500) {
+      throw scopedPermissionError(
+        SCOPED_PERMISSION_ERROR_CODES.INVALID,
+        "reason must be at most 500 characters",
+      );
+    }
+
+    let created = null;
+    mutateSecurityStore(
+      this.filePath,
+      STORE_LABEL,
+      (draft) => {
+        const current =
+          Object.keys(draft).length === 0
+            ? emptyState(this.workspace)
+            : validateState(draft, this.workspace);
+        if (
+          expectedGeneration !== null &&
+          Number(expectedGeneration) !== current.generation
+        ) {
+          throw scopedPermissionError(
+            SCOPED_PERMISSION_ERROR_CODES.CONFLICT,
+            `Scoped permission generation changed (expected ${expectedGeneration}, current ${current.generation})`,
+          );
+        }
+
+        const retained = [...current.rules];
+        while (retained.length >= this.maxRecords) {
+          const inactiveIndex = retained.findIndex(
+            (record) => statusFor(record, now) !== "active",
+          );
+          if (inactiveIndex < 0) break;
+          retained.splice(inactiveIndex, 1);
+        }
+        if (retained.length >= this.maxRecords) {
+          throw scopedPermissionError(
+            SCOPED_PERMISSION_ERROR_CODES.INVALID,
+            `Scoped permission store is full (${this.maxRecords} retained rules)`,
+          );
+        }
+        const id = this._randomId();
+        if (
+          !RULE_ID_PATTERN.test(id) ||
+          retained.some((item) => item.id === id)
+        ) {
+          throw scopedPermissionError(
+            SCOPED_PERMISSION_ERROR_CODES.INVALID,
+            "Could not allocate a valid unique scoped permission id",
+          );
+        }
+        created = {
+          id,
+          decision: normalizedDecision,
+          rule: normalizedRule,
+          revision: 1,
+          createdAt: now,
+          expiresAt: expiry,
+          revokedAt: null,
+          reason: normalizedReason,
+        };
+        Object.assign(draft, current, {
+          generation: current.generation + 1,
+          updatedAt: now,
+          rules: [...retained, created],
+        });
+        validateState(draft, this.workspace);
+      },
+      this._lock ? { lock: this._lock } : undefined,
+    );
+    return projectRecord(created, now, this.filePath);
+  }
+
+  revoke({ id, expectedRevision = null } = {}) {
+    const normalizedId = String(id || "").trim();
+    if (!RULE_ID_PATTERN.test(normalizedId)) {
+      throw scopedPermissionError(
+        SCOPED_PERMISSION_ERROR_CODES.INVALID,
+        "A valid scoped permission id is required",
+      );
+    }
+    const now = this._now();
+    let revoked = null;
+    mutateSecurityStore(
+      this.filePath,
+      STORE_LABEL,
+      (draft) => {
+        const current =
+          Object.keys(draft).length === 0
+            ? emptyState(this.workspace)
+            : validateState(draft, this.workspace);
+        const index = current.rules.findIndex(
+          (record) => record.id === normalizedId,
+        );
+        if (index < 0) {
+          throw scopedPermissionError(
+            SCOPED_PERMISSION_ERROR_CODES.NOT_FOUND,
+            `Scoped permission rule not found: ${normalizedId}`,
+          );
+        }
+        const record = current.rules[index];
+        if (
+          expectedRevision !== null &&
+          Number(expectedRevision) !== record.revision
+        ) {
+          throw scopedPermissionError(
+            SCOPED_PERMISSION_ERROR_CODES.CONFLICT,
+            `Scoped permission revision changed (expected ${expectedRevision}, current ${record.revision})`,
+          );
+        }
+        if (record.revokedAt !== null) {
+          revoked = record;
+          return;
+        }
+        revoked = {
+          ...record,
+          revision: record.revision + 1,
+          revokedAt: now,
+        };
+        const rules = [...current.rules];
+        rules[index] = revoked;
+        Object.assign(draft, current, {
+          generation: current.generation + 1,
+          updatedAt: now,
+          rules,
+        });
+        validateState(draft, this.workspace);
+      },
+      this._lock ? { lock: this._lock } : undefined,
+    );
+    return projectRecord(revoked, now, this.filePath);
+  }
+}