chainlesschain 0.164.0 → 0.165.2

package/src/lib/remote-membership-host-store.js

@@ -107,6 +107,7 @@ const LEASE_FIELDS = Object.freeze([
 ]);
 const AUTHENTICATION_CHALLENGE_FIELDS = Object.freeze([
   "authorityVersion",
+  "capabilities",
   "challengeId",
   "connectionNonce",
   "coordinatorId",
@@ -116,6 +117,13 @@ const AUTHENTICATION_CHALLENGE_FIELDS = Object.freeze([
   "expiresAtMs",
   "issuedAtMs",
   "membershipEpoch",
+  "joinPolicy",
+  "joinVia",
+  "nextCredentialKeySha256",
+  "nextCredentialPublicKey",
+  "nextCredentialType",
+  "nextPrincipalId",
+  "nextSessionExpiresAt",
   "principalId",
   "purpose",
   "schema",
@@ -873,13 +881,20 @@ function replayHostStore(store, { missing = false } = {}) {
           throw new TypeError(`${label} has an invalid session snapshot`);
         }
         if (sessionSnapshot) {
+          const priorSessionEpoch = BigInt(sessionSnapshot.sessionEpoch);
+          const nextSessionEpoch = BigInt(payload.sessionEpoch);
+          const reenabled =
+            sessionSnapshot.status === "closed" &&
+            payload.status === "active" &&
+            nextSessionEpoch === priorSessionEpoch + 1n;
           if (
             payload.sessionId !== sessionSnapshot.sessionId ||
             payload.agentSessionId !== sessionSnapshot.agentSessionId ||
             payload.hostPrincipalId !== sessionSnapshot.hostPrincipalId ||
             payload.createdAt !== sessionSnapshot.createdAt ||
-            payload.expiresAt !== sessionSnapshot.expiresAt ||
-            BigInt(payload.sessionEpoch) < BigInt(sessionSnapshot.sessionEpoch)
+            (!reenabled && payload.expiresAt !== sessionSnapshot.expiresAt) ||
+            (reenabled && payload.expiresAt < sessionSnapshot.expiresAt) ||
+            nextSessionEpoch < priorSessionEpoch
           ) {
             throw new TypeError(`${label} rolls back the session identity`);
           }
@@ -905,7 +920,12 @@ function replayHostStore(store, { missing = false } = {}) {
               (nextEpoch === priorEpoch &&
                 canonicalJson(current) !== canonicalJson(previous)) ||
               (nextEpoch === priorEpoch + 1n &&
-                current.status === previous.status)
+                current.status === previous.status &&
+                !(
+                  reenabled &&
+                  current.principalId === payload.hostPrincipalId &&
+                  current.status === "active"
+                ))
             ) {
               throw new TypeError(`${label} forks or skips a principal epoch`);
             }
@@ -920,16 +940,16 @@ function replayHostStore(store, { missing = false } = {}) {
               );
             }
           }
-          const priorSessionEpoch = BigInt(sessionSnapshot.sessionEpoch);
-          const nextSessionEpoch = BigInt(payload.sessionEpoch);
           if (
             nextSessionEpoch > priorSessionEpoch + 1n ||
             (nextSessionEpoch === priorSessionEpoch &&
               payload.status !== sessionSnapshot.status) ||
             (nextSessionEpoch === priorSessionEpoch + 1n &&
-              (sessionSnapshot.status !== "active" ||
-                payload.status !== "closed")) ||
-            sessionSnapshot.status === "closed"
+              !(
+                (sessionSnapshot.status === "active" &&
+                  payload.status === "closed") ||
+                reenabled
+              ))
           ) {
             throw new TypeError(`${label} forks or reopens the session epoch`);
           }
@@ -1591,8 +1611,17 @@ export class DurableRemoteMembershipHostStore {
         challenge.credentialType !== "ed25519" ||
         challenge.credentialPublicKey !==
           bootstrap.hostCredentialPublicKeySpki ||
-        challenge.purpose !== "session.resume" ||
-        challenge.scopes !== null
+        !["session.resume", "session.reenable"].includes(challenge.purpose) ||
+        (challenge.purpose === "session.resume" &&
+          (challenge.scopes !== null ||
+            challenge.capabilities !== null ||
+            challenge.joinPolicy !== null ||
+            challenge.joinVia !== null ||
+            challenge.nextCredentialType !== null ||
+            challenge.nextCredentialPublicKey !== null ||
+            challenge.nextCredentialKeySha256 !== null ||
+            challenge.nextPrincipalId !== null ||
+            challenge.nextSessionExpiresAt !== null))
       ) {
         throw trustRejected("authentication challenge is not host-bound");
       }
@@ -1604,6 +1633,26 @@ export class DurableRemoteMembershipHostStore {
       canonicalInteger(challenge.membershipEpoch, "challenge.membershipEpoch");
       safeTimestamp(challenge.issuedAtMs, "challenge.issuedAtMs");
       safeTimestamp(challenge.expiresAtMs, "challenge.expiresAtMs");
+      if (challenge.purpose === "session.reenable") {
+        if (
+          !Array.isArray(challenge.scopes) ||
+          challenge.scopes.length === 0 ||
+          challenge.capabilities !== null ||
+          challenge.joinVia !== null ||
+          !challenge.joinPolicy ||
+          typeof challenge.joinPolicy !== "object" ||
+          Array.isArray(challenge.joinPolicy) ||
+          challenge.nextCredentialType !== "ed25519" ||
+          typeof challenge.nextCredentialPublicKey !== "string" ||
+          !DIGEST_RE.test(String(challenge.nextCredentialKeySha256)) ||
+          challenge.nextPrincipalId !==
+            `ed25519:${challenge.nextCredentialKeySha256}` ||
+          !Number.isSafeInteger(challenge.nextSessionExpiresAt) ||
+          challenge.nextSessionExpiresAt <= challenge.issuedAtMs
+        ) {
+          throw trustRejected("re-enable challenge is malformed");
+        }
+      }
       if (
         challenge.expiresAtMs <= challenge.issuedAtMs ||
         challenge.expiresAtMs <= safeTimestamp(this._now(), "host clock") ||

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/shell-approval.js

@@ -32,6 +32,129 @@ import {
   resolveInstallPolicy,
 } from "./install-command-policy.js";
 
+const SHELL_EXECUTION_DESCRIPTOR_VERSION =
+  "chainlesschain.shell-execution-descriptor/v1";
+
+function deepFreezeData(value, seen = new WeakSet()) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value))
+    return value;
+  if (seen.has(value)) return value;
+  seen.add(value);
+  for (const child of Object.values(value)) deepFreezeData(child, seen);
+  return Object.freeze(value);
+}
+
+function cloneData(value, label) {
+  try {
+    return structuredClone(value);
+  } catch (cause) {
+    throw new Error(`${label} must be structured-cloneable`, { cause });
+  }
+}
+
+/** Capture only the declared run_shell data contract and freeze it. */
+export function snapshotShellExecutionArgs(args = {}, fallbackCommand = null) {
+  const source = args && typeof args === "object" ? args : {};
+  const snapshot = {
+    command:
+      source.command !== undefined
+        ? cloneData(source.command, "command")
+        : cloneData(fallbackCommand ?? null, "command"),
+  };
+  for (const key of ["cwd", "shell", "run_in_background", "timeout"]) {
+    if (source[key] !== undefined) snapshot[key] = cloneData(source[key], key);
+  }
+  return deepFreezeData(snapshot);
+}
+
+/**
+ * Build the bounded, secret-free data tuple shown to ApprovalGate and later
+ * consumed at dispatch. Runtime objects/callbacks never enter this descriptor.
+ */
+export function createShellExecutionDescriptor({
+  args,
+  workspace = null,
+  shellInvocation = null,
+  pluginInvocation = null,
+  pluginSandboxPolicy = null,
+  pluginSandboxExecutionContract = null,
+  sandbox = null,
+  environmentRef = null,
+} = {}) {
+  const shellArgs = snapshotShellExecutionArgs(args);
+  const descriptor = {
+    ...shellArgs,
+    execution: {
+      version: SHELL_EXECUTION_DESCRIPTOR_VERSION,
+      mode: shellArgs.run_in_background === true ? "background" : "foreground",
+      workspace: workspace || null,
+      shell: shellInvocation
+        ? {
+            kind: shellInvocation.kind || null,
+            useDefaultShell: shellInvocation.useDefaultShell === true,
+            file: shellInvocation.file || null,
+            argv: Array.isArray(shellInvocation.argv)
+              ? [...shellInvocation.argv]
+              : [],
+          }
+        : null,
+      plugin: pluginInvocation
+        ? {
+            command: pluginInvocation.command || null,
+            id: pluginInvocation.pluginId || null,
+            version: pluginInvocation.pluginVersion || null,
+            source: pluginInvocation.pluginSource || null,
+            bin: pluginInvocation.binName || null,
+            path: pluginInvocation.binPath || null,
+            runtime: pluginInvocation.runtime || null,
+            argv: Array.isArray(pluginInvocation.args)
+              ? [...pluginInvocation.args]
+              : [],
+            executableSha256:
+              pluginInvocation.executableIdentity?.sha256 || null,
+            sandboxPolicy: pluginSandboxPolicy
+              ? cloneData(pluginSandboxPolicy, "pluginSandboxPolicy")
+              : null,
+            sandboxExecution: pluginSandboxExecutionContract
+              ? {
+                  version:
+                    pluginSandboxExecutionContract.contractVersion || null,
+                  kind: pluginSandboxExecutionContract.kind || null,
+                  pluginRoot: pluginSandboxExecutionContract.pluginRoot || null,
+                  workingDirectory:
+                    pluginSandboxExecutionContract.workingDirectory || null,
+                  runtimePath:
+                    pluginSandboxExecutionContract.runtimePath || null,
+                  entrySha256:
+                    pluginSandboxExecutionContract.entryIdentity?.sha256 ||
+                    null,
+                  runtimeSha256:
+                    pluginSandboxExecutionContract.runtimeIdentity?.sha256 ||
+                    null,
+                }
+              : null,
+          }
+        : null,
+      sandbox: sandbox ? cloneData(sandbox, "sandbox") : null,
+      environment: environmentRef
+        ? cloneData(environmentRef, "environmentRef")
+        : null,
+    },
+  };
+  return deepFreezeData(descriptor);
+}
+
+export function shellApprovalAction(riskLevel) {
+  return riskLevel ? `${riskLevel}-risk` : null;
+}
+
+export function commitShellApprovalSideEffects(result) {
+  const audit = result?.installAudit || null;
+  if (!audit) return false;
+  recordInstallCommandAudit(audit.entry, audit.options || {});
+  return true;
+}
+
 export const SHELL_TO_RISK = {
   allow: RISK.LOW,
   warn: RISK.MEDIUM,
@@ -41,10 +164,16 @@ export const SHELL_TO_RISK = {
 
 export async function evaluateShellCommandWithApproval({
   command,
+  args = null,
   sessionId = null,
   approvalGate = null,
   shellPolicyOptions = {},
   installPolicy = null,
+  workspace = null,
+  targetEnv = null,
+  policyEnv = process.env,
+  policyVersion = null,
+  deferSideEffects = false,
 } = {}) {
   const shellPolicy = sharedShellPolicy.evaluateShellCommandPolicy(
     command,
@@ -62,8 +191,9 @@ export async function evaluateShellCommandWithApproval({
   // CC_INSTALL_RISK_FLOOR) so the real run_shell path picks it up with no extra
   // wiring. Both unset → disabled → the block below is skipped, byte-unchanged.
   const effectiveInstallPolicy =
-    installPolicy || resolveInstallPolicy({ env: process.env });
+    installPolicy || resolveInstallPolicy({ env: policyEnv });
   let install = null;
+  let installAudit = null;
   if (effectiveInstallPolicy && effectiveInstallPolicy.enabled) {
     const cls = classifyCodeAcquisition(command);
     if (cls.flagged) {
@@ -72,8 +202,8 @@ export async function evaluateShellCommandWithApproval({
         riskLevel = applyRiskFloor(riskLevel, effectiveInstallPolicy.riskFloor);
       }
       if (effectiveInstallPolicy.audit) {
-        recordInstallCommandAudit(
-          {
+        installAudit = {
+          entry: {
             command,
             shellDecision: shellPolicy.decision,
             riskLevel,
@@ -82,8 +212,12 @@ export async function evaluateShellCommandWithApproval({
             global: hasGlobalInstall(cls),
             sessionId,
           },
-          effectiveInstallPolicy.auditOpts || {},
-        );
+          options: effectiveInstallPolicy.auditOpts || {},
+        };
+        if (!deferSideEffects) {
+          recordInstallCommandAudit(installAudit.entry, installAudit.options);
+          installAudit = null;
+        }
       }
     }
   }
@@ -100,6 +234,7 @@ export async function evaluateShellCommandWithApproval({
       riskLevel,
       policy: null,
       install,
+      installAudit,
     };
   }
 
@@ -114,14 +249,29 @@ export async function evaluateShellCommandWithApproval({
       riskLevel,
       policy: null,
       install,
+      installAudit,
     };
   }
 
+  const operationArgs = args
+    ? Object.isFrozen(args)
+      ? args
+      : deepFreezeData(cloneData(args, "run_shell approval args"))
+    : snapshotShellExecutionArgs({ command });
+  const effectivePolicyVersion =
+    typeof policyVersion === "string" && policyVersion
+      ? policyVersion
+      : `shell-policy:${shellPolicy.decision}:${shellPolicy.ruleId || "none"}`;
+  const action = shellApprovalAction(riskLevel);
   const gateResult = await approvalGate.decide({
     sessionId,
     riskLevel,
     tool: "run_shell",
-    args: { command },
+    args: operationArgs,
+    cwd: workspace,
+    targetEnv,
+    policyVersion: effectivePolicyVersion,
+    action,
   });
 
   return {
@@ -133,6 +283,19 @@ export async function evaluateShellCommandWithApproval({
     riskLevel,
     policy: gateResult.policy,
     install,
+    installAudit,
+    authorization: gateResult.authorization || null,
+    authorizationContext: gateResult.authorization
+      ? {
+          tool: "run_shell",
+          action,
+          args: operationArgs,
+          workspace,
+          session: sessionId,
+          targetEnv,
+          policyVersion: effectivePolicyVersion,
+        }
+      : null,
     // Explainability passthrough (autoMode.decisions wrapper attaches these):
     // which gate rule fired and why — surfaced in the permission chain.
     gateReason: gateResult.reason ?? null,