chainlesschain 0.165.5 → 0.165.8

package/src/lib/remote-control.js

@@ -6,14 +6,13 @@
  * already exists under src/gateways + src/harness; this module only composes
  * it into one entry point:
  *
- *   - resolveRemoteControlOptions()  flags > env > config > defaults
+ *   - resolveRemoteControlOptions()  explicit authority > safe defaults
  *   - buildDirectPairingUri()        LAN pairing descriptor (no relay needed)
  *   - parseDirectPairingUri()        inverse, used by clients + tests
  *   - pickLanAddress()               best-effort non-internal IPv4
  *   - state file read/write          ~/.chainlesschain/remote-control/<port>.json
  *     so `cc remote-control status/stop` can discover a running host process.
- *     The file is 0600 and CONTAINS THE SERVER TOKEN — same local trust model
- *     as ~/.chainlesschain/ide/<port>.json (readable only by the OS user).
+ *     The file is 0600 and deliberately contains no bearer/pairing token.
  *   - renderQrCode()                 lazy OPTIONAL `qrcode` import; returns
  *     null when the package is not installed (URI printing is the contract,
  *     the QR is progressive enhancement — no hard dependency, trap #6/#27).
@@ -23,19 +22,123 @@ import fs from "fs";
 import os from "os";
 import path from "path";
 import { randomBytes } from "crypto";
+import { isIP } from "net";
 import { REMOTE_SESSION_SCOPES } from "../harness/remote-session-registry.js";
 import { extractHost, isPrivateHost } from "./sandbox-network-policy.js";
 
 export const REMOTE_CONTROL_DEFAULT_PORT = 18800;
+export const REMOTE_CONTROL_DEFAULT_HOST = "127.0.0.1";
 export const REMOTE_CONTROL_PAIRING_SCHEME =
   "chainlesschain://remote-control/pair#";
 export const REMOTE_CONTROL_DEFAULT_SCOPES = Object.freeze([
   "observe",
   "prompt",
-  "approve",
-  "interrupt",
 ]);
 
+function cleanHost(value) {
+  if (value == null) return null;
+  const host = String(value).trim();
+  return host || null;
+}
+
+function normalizeBindHost(value, label) {
+  let host = cleanHost(value);
+  if (!host) return null;
+  if (host.startsWith("[") && host.endsWith("]")) {
+    host = host.slice(1, -1);
+  }
+  host = host.replace(/\.+$/, "").toLowerCase();
+  if (host.includes("%")) {
+    throw new Error(
+      `Invalid ${label} "${host}": scoped IPv6 bind hosts are not supported.`,
+    );
+  }
+  if (host === "localhost" || isIP(host) !== 0) return host;
+  throw new Error(
+    `Invalid ${label} "${host}": use localhost or an IPv4/IPv6 literal without a port.`,
+  );
+}
+
+function mappedIpv4FirstOctet(host) {
+  const dotted = host.match(/^::ffff:(\d{1,3})\.\d{1,3}\.\d{1,3}\.\d{1,3}$/i);
+  if (dotted) return Number(dotted[1]);
+  const hex = host.match(/^::ffff:([0-9a-f]{1,4}):[0-9a-f]{1,4}$/i);
+  if (!hex) return null;
+  return (parseInt(hex[1], 16) >> 8) & 0xff;
+}
+
+/** Whether a bind host is restricted to this machine. */
+export function isLoopbackBindHost(value) {
+  let host = cleanHost(value)?.toLowerCase();
+  if (!host) return false;
+  if (host.startsWith("[") && host.endsWith("]")) {
+    host = host.slice(1, -1);
+  }
+  host = host.replace(/\.+$/, "");
+  return (
+    host === "localhost" ||
+    (isIP(host) === 6 && host === "::1") ||
+    (isIP(host) === 4 && host.split(".")[0] === "127") ||
+    mappedIpv4FirstOctet(host) === 127
+  );
+}
+
+function isWildcardBindHost(value) {
+  let host = cleanHost(value)?.toLowerCase();
+  if (host?.startsWith("[") && host.endsWith("]")) {
+    host = host.slice(1, -1);
+  }
+  return host === "0.0.0.0" || host === "::";
+}
+
+function isLanBindHost(value) {
+  let host = cleanHost(value)?.toLowerCase();
+  if (host?.startsWith("[") && host.endsWith("]")) {
+    host = host.slice(1, -1);
+  }
+  return (
+    isWildcardBindHost(host) ||
+    isLoopbackBindHost(host) ||
+    (isIP(host) !== 0 && isPrivateHost(host))
+  );
+}
+
+function isAdvertisableLanAddress(value) {
+  const host = cleanHost(value)?.toLowerCase();
+  return (
+    isIP(host) !== 0 &&
+    isPrivateHost(host) &&
+    !isLoopbackBindHost(host) &&
+    !isWildcardBindHost(host) &&
+    host !== "169.254.169.254"
+  );
+}
+
+function wsHost(value) {
+  const host = cleanHost(value) || REMOTE_CONTROL_DEFAULT_HOST;
+  if (host.startsWith("[") && host.endsWith("]")) return host;
+  return host.includes(":") ? `[${host}]` : host;
+}
+
+/** Resolve the direct endpoint that is safe to advertise to pairing clients. */
+export function resolveRemoteControlWsUrl(
+  { host = REMOTE_CONTROL_DEFAULT_HOST, port, allowLan = false } = {},
+  { lanAddress = null } = {},
+) {
+  let endpointHost;
+  if (allowLan && !isLoopbackBindHost(host)) {
+    endpointHost = isWildcardBindHost(host)
+      ? isAdvertisableLanAddress(lanAddress)
+        ? cleanHost(lanAddress)
+        : REMOTE_CONTROL_DEFAULT_HOST
+      : cleanHost(host);
+  } else if (isLoopbackBindHost(host)) {
+    endpointHost = cleanHost(host);
+  } else {
+    endpointHost = REMOTE_CONTROL_DEFAULT_HOST;
+  }
+  return `ws://${wsHost(endpointHost)}:${port}`;
+}
 function b64url(value) {
   return Buffer.from(value, "utf8").toString("base64url");
 }
@@ -63,22 +166,70 @@ export function parseScopes(raw) {
 }
 
 /**
- * Resolve effective start options. Precedence: explicit flags > environment >
- * config (`remoteControl` / legacy `remoteSession` blocks) > defaults. A
+ * Resolve effective start options. Remote Control is always command/flag
+ * activated by its caller; repository/project configuration is only allowed
+ * to disable it. In particular, checked-in config cannot widen the bind host,
+ * grant approve/interrupt, select a relay, or install a long-lived token.
+ *
+ * Direct LAN and privileged scopes are distinct command-line authorities. A
  * missing token is AUTO-GENERATED (32 hex chars) — the WS server must never
- * come up unauthenticated on the unified entry, even on loopback, because the
- * pairing URI embeds the token and pairing is the whole point.
+ * come up unauthenticated, even on loopback.
  */
 export function resolveRemoteControlOptions({
   flags = {},
   env = process.env,
   config = {},
 } = {}) {
-  const rc = config.remoteControl || {};
-  const legacy = config.remoteSession || {};
-  const port = Number(
-    flags.port ?? env.CC_REMOTE_CONTROL_PORT ?? rc.port ?? undefined,
-  );
+  const rc =
+    config.remoteControl && typeof config.remoteControl === "object"
+      ? config.remoteControl
+      : {};
+  const legacy =
+    config.remoteSession && typeof config.remoteSession === "object"
+      ? config.remoteSession
+      : {};
+  if (
+    config.remoteControl === false ||
+    rc.enabled === false ||
+    legacy.remoteControlEnabled === false
+  ) {
+    throw new Error("Remote Control is disabled by configuration");
+  }
+
+  const warnings = [];
+  if (
+    Object.prototype.hasOwnProperty.call(rc, "host") ||
+    Object.prototype.hasOwnProperty.call(rc, "allowLan")
+  ) {
+    warnings.push(
+      "Ignoring project Remote Control exposure settings; use explicit --host/--allow-lan for this invocation.",
+    );
+  }
+
+  const flagHost = normalizeBindHost(flags.host, "--host");
+  const allowLan = flags.allowLan === true;
+  if (flagHost && !isLoopbackBindHost(flagHost) && !allowLan) {
+    throw new Error(
+      `Refusing non-loopback --host "${flagHost}" without --allow-lan. ` +
+        "Add --allow-lan on a trusted network, or remove --host and configure --relay-url.",
+    );
+  }
+  const host = flagHost || (allowLan ? "0.0.0.0" : REMOTE_CONTROL_DEFAULT_HOST);
+  if (allowLan && host === "::") {
+    throw new Error(
+      'Refusing IPv6 wildcard host "::": use an explicit private IPv6 address ' +
+        "or 0.0.0.0 so the advertised endpoint matches the listener.",
+    );
+  }
+  if (allowLan && !isLanBindHost(host)) {
+    throw new Error(
+      `Refusing --allow-lan with non-private host "${host}". ` +
+        "Use a loopback, wildcard, or private LAN address; use a relay for public networks.",
+    );
+  }
+  const lanAccessible = allowLan && !isLoopbackBindHost(host);
+
+  const port = Number(flags.port ?? env.CC_REMOTE_CONTROL_PORT ?? undefined);
   const resolvedPort =
     Number.isFinite(port) && port >= 1 && port <= 65535
       ? Math.floor(port)
@@ -86,40 +237,59 @@ export function resolveRemoteControlOptions({
   const token =
     flags.token ||
     env.CC_REMOTE_CONTROL_TOKEN ||
-    rc.token ||
     randomBytes(16).toString("hex");
-  const relayUrl =
-    flags.relayUrl ||
-    env.CC_REMOTE_SESSION_RELAY_URL ||
-    rc.relayUrl ||
-    legacy.relayUrl ||
-    null;
+  const relayUrl = flags.relayUrl || env.CC_REMOTE_SESSION_RELAY_URL || null;
   const peerId =
     flags.peerId ||
     env.CC_REMOTE_SESSION_PEER_ID ||
-    rc.peerId ||
-    legacy.peerId ||
     (relayUrl
       ? `cc-host-${os.hostname()}-${randomBytes(4).toString("hex")}`
       : null);
+
+  const requestedScopes = parseScopes(flags.scopes ?? null);
+  if (requestedScopes.includes("approve") && flags.allowApprove !== true) {
+    throw new Error(
+      'Remote Control scope "approve" requires explicit --allow-approve',
+    );
+  }
+  if (requestedScopes.includes("interrupt") && flags.allowInterrupt !== true) {
+    throw new Error(
+      'Remote Control scope "interrupt" requires explicit --allow-interrupt',
+    );
+  }
+  const scopes = [...requestedScopes];
+  if (flags.allowApprove === true && !scopes.includes("approve")) {
+    scopes.push("approve");
+  }
+  if (flags.allowInterrupt === true && !scopes.includes("interrupt")) {
+    scopes.push("interrupt");
+  }
+
   return {
     port: resolvedPort,
-    host: flags.host || rc.host || "0.0.0.0",
+    host,
+    allowLan,
+    exposesLan: lanAccessible,
+    lanAccessible,
+    warnings,
     token,
     relayUrl,
     peerId,
-    scopes: parseScopes(flags.scopes ?? rc.scopes ?? null),
-    name: flags.name || rc.name || `remote-control @ ${os.hostname()}`,
+    scopes,
+    name: flags.name || `remote-control @ ${os.hostname()}`,
   };
 }
-
 /** First non-internal IPv4 address, or null. Pure over an interfaces map. */
 export function pickLanAddress(interfaces = os.networkInterfaces()) {
   for (const entries of Object.values(interfaces || {})) {
     for (const entry of entries || []) {
       const family =
         entry.family === "IPv4" || entry.family === 4 ? "IPv4" : entry.family;
-      if (family === "IPv4" && !entry.internal && entry.address) {
+      if (
+        family === "IPv4" &&
+        !entry.internal &&
+        isAdvertisableLanAddress(entry.address)
+      ) {
         return entry.address;
       }
     }
@@ -226,14 +396,22 @@ function stateFilePath(dir, port) {
 }
 
 /**
- * Persist a running host's discovery record (0600 file, 0700 dir). Contains
- * the server token — local-user trust domain only, mirroring the IDE bridge.
+ * Persist a running host's non-secret discovery record (0600 file, 0700 dir).
+ * Pairing/server tokens are intentionally rejected so status, crash recovery,
+ * diagnostics, and uploaded state artifacts cannot disclose them.
  */
 export function writeRemoteControlState(state, { dir } = {}) {
   const stateDir = dir || remoteControlStateDir();
   fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
   const file = stateFilePath(stateDir, state.port);
-  fs.writeFileSync(file, JSON.stringify(state, null, 2), {
+  const {
+    token: _token,
+    serverToken: _serverToken,
+    pairingToken: _pairingToken,
+    pairingUri: _pairingUri,
+    ...safeState
+  } = state;
+  fs.writeFileSync(file, JSON.stringify(safeState, null, 2), {
     encoding: "utf-8",
     mode: 0o600,
   });
@@ -279,8 +457,16 @@ export function readRemoteControlStates({ dir } = {}) {
     const file = path.join(stateDir, name);
     try {
       const state = JSON.parse(fs.readFileSync(file, "utf-8"));
+      const legacyExposure = state.exposure == null;
+      const exposure = legacyExposure
+        ? state.host && !isLoopbackBindHost(state.host)
+          ? "legacy-unknown-lan"
+          : "legacy-unknown"
+        : state.exposure;
       states.push({
         ...state,
+        exposure,
+        legacyExposure,
         stateFile: file,
         alive: isPidAlive(state.pid),
       });

package/src/lib/resume-session.js

@@ -6,10 +6,12 @@
 
 import fs from "fs";
 import path from "path";
-import os from "os";
 import { logger } from "./logger.js";
+import { getSessionStoreDir } from "./paths.js";
 
-const SESSION_DIR = path.join(os.homedir(), ".chainlesschain", "sessions");
+function sessionDir() {
+  return getSessionStoreDir();
+}
 
 /**
  * List recent chat sessions
@@ -18,15 +20,16 @@ const SESSION_DIR = path.join(os.homedir(), ".chainlesschain", "sessions");
  */
 export function listSessions(limit = 10) {
   try {
-    if (!fs.existsSync(SESSION_DIR)) {
+    const directory = sessionDir();
+    if (!fs.existsSync(directory)) {
       return [];
     }
 
     const files = fs
-      .readdirSync(SESSION_DIR)
+      .readdirSync(directory)
       .filter((f) => f.endsWith(".json"))
       .map((f) => {
-        const filePath = path.join(SESSION_DIR, f);
+        const filePath = path.join(directory, f);
         const stat = fs.statSync(filePath);
         let summary = "";
         try {
@@ -59,7 +62,7 @@ export function listSessions(limit = 10) {
  */
 export function loadSession(sessionId) {
   try {
-    const filePath = path.join(SESSION_DIR, `${sessionId}.json`);
+    const filePath = path.join(sessionDir(), `${sessionId}.json`);
     if (!fs.existsSync(filePath)) {
       return null;
     }

package/src/lib/session-core-singletons.js

@@ -10,6 +10,10 @@
 import { join } from "node:path";
 import { promises as fsp, existsSync, mkdirSync } from "node:fs";
 import { getHomeDir } from "./paths.js";
+import {
+  ensureTrustedSessionLifecycleScope,
+  resolveTrustedSessionLifecycleScope,
+} from "./session-lifecycle-scope.js";
 import {
   MemoryStore,
   BetaFlags,
@@ -26,7 +30,10 @@ import {
 let _memoryStore = null;
 let _betaFlags = null;
 let _approvalGate = null;
-let _sessionManager = null;
+// SessionManager owns live handles as well as its parked-session sidecar. A
+// Claude project bucket must therefore receive a separate in-process manager
+// even when another project happens to reuse the same session id.
+const _sessionManagersByScope = new Map();
 
 export function getMemoryStorePath() {
   return join(getHomeDir(), "memory-store.json");
@@ -67,12 +74,14 @@ export async function getApprovalGate() {
   return _approvalGate;
 }
 
-export function getParkedSessionsPath() {
-  return join(getHomeDir(), "parked-sessions.json");
+export function getParkedSessionsPath(options = {}) {
+  return resolveTrustedSessionLifecycleScope(options).parkedSessionsPath;
 }
 
-function createParkedSessionsStore(filePath) {
+function createParkedSessionsStore(filePath, options = {}) {
+  const ensureDirectory = options.ensureDirectory || null;
   async function readAll() {
+    ensureDirectory?.();
     try {
       const raw = await fsp.readFile(filePath, "utf8");
       return JSON.parse(raw || "{}");
@@ -81,6 +90,7 @@ function createParkedSessionsStore(filePath) {
     }
   }
   async function writeAll(map) {
+    ensureDirectory?.();
     const dir = join(filePath, "..");
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     await fsp.writeFile(filePath, JSON.stringify(map, null, 2), "utf8");
@@ -106,12 +116,17 @@ function createParkedSessionsStore(filePath) {
   };
 }
 
-export function getSessionManager() {
-  if (_sessionManager) return _sessionManager;
-  const store = createParkedSessionsStore(getParkedSessionsPath());
-  _sessionManager = new SessionManager({ store });
-  _sessionManager._parkedStore = store;
-  return _sessionManager;
+export function getSessionManager(options = {}) {
+  const scope = resolveTrustedSessionLifecycleScope(options);
+  const existing = _sessionManagersByScope.get(scope.key);
+  if (existing) return existing;
+  const store = createParkedSessionsStore(scope.parkedSessionsPath, {
+    ensureDirectory: () => ensureTrustedSessionLifecycleScope(scope),
+  });
+  const manager = new SessionManager({ store });
+  manager._parkedStore = store;
+  _sessionManagersByScope.set(scope.key, manager);
+  return manager;
 }
 
 export function createStreamRouter() {
@@ -122,7 +137,7 @@ export function resetSessionCoreSingletonsForTests() {
   _memoryStore = null;
   _betaFlags = null;
   _approvalGate = null;
-  _sessionManager = null;
+  _sessionManagersByScope.clear();
 }
 
 // =====================================================================

package/src/lib/session-host-lease.js

@@ -12,7 +12,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
-import { getStatePath } from "./paths.js";
+import * as cliPaths from "./paths.js";
 import {
   mutateSecurityStore,
   readSecurityStore,
@@ -291,7 +291,28 @@ function publicRevocation(record, replayed) {
 }
 
 export function getSessionHostLeaseRoot() {
-  return path.join(getStatePath(), "session-host-leases");
+  const projectDir =
+    typeof cliPaths.getClaudeProjectStorageDir === "function"
+      ? cliPaths.getClaudeProjectStorageDir()
+      : null;
+  if (projectDir) {
+    const stateRoot = path.join(projectDir, "session-host-leases");
+    // The caller did not supply this location; it is derived exclusively from
+    // the validated launch environment. Establish the same private project
+    // tree for host leases that JSONL uses for transcripts.
+    if (
+      typeof cliPaths.getHomeDir === "function" &&
+      typeof cliPaths.ensureClaudeProjectStorageTree === "function"
+    ) {
+      cliPaths.ensureClaudeProjectStorageTree(
+        cliPaths.getHomeDir(),
+        projectDir,
+        { extraDirectories: [stateRoot] },
+      );
+    }
+    return stateRoot;
+  }
+  return path.join(cliPaths.getStatePath(), "session-host-leases");
 }
 
 export class SessionHostLeaseAuthority {
@@ -970,14 +991,27 @@ export class SessionHostLeaseAuthority {
   }
 }
 
-const defaultAuthority = new SessionHostLeaseAuthority();
+const scopedAuthorities = new Map();
+
+function authorityFor(options = {}) {
+  const stateRoot = path.resolve(
+    options?.stateRoot || getSessionHostLeaseRoot(),
+  );
+  let authority = scopedAuthorities.get(stateRoot);
+  if (!authority) {
+    authority = new SessionHostLeaseAuthority({ stateRoot });
+    scopedAuthorities.set(stateRoot, authority);
+  }
+  return authority;
+}
 
 export function acquireSessionHostLease(sessionId, options) {
-  return defaultAuthority.acquire(sessionId, options);
+  const { stateRoot = null, ...leaseOptions } = options || {};
+  return authorityFor({ stateRoot }).acquire(sessionId, leaseOptions);
 }
 
-export function withSessionHostWriteAuthority(sessionId, task) {
-  return defaultAuthority.withWriteAuthority(sessionId, task);
+export function withSessionHostWriteAuthority(sessionId, task, options = {}) {
+  return authorityFor(options).withWriteAuthority(sessionId, task);
 }
 
 export function createSessionHostWriteDelegation(lease) {
@@ -990,23 +1024,24 @@ export function withSessionHostDelegatedWriteAuthority(
   task,
   options,
 ) {
-  return defaultAuthority.withDelegatedWriteAuthority(
+  const { stateRoot = null, ...delegationOptions } = options || {};
+  return authorityFor({ stateRoot }).withDelegatedWriteAuthority(
     sessionId,
     delegation,
     task,
-    options,
+    delegationOptions,
   );
 }
 
 export function withSessionHostRecoveryLease(
   sessionId,
   task,
-  { hostKind = "background-recovery" } = {},
+  { hostKind = "background-recovery", stateRoot = null } = {},
 ) {
   if (typeof task !== "function") {
     throw new TypeError("session host recovery callback is required");
   }
-  const lease = acquireSessionHostLease(sessionId, { hostKind });
+  const lease = acquireSessionHostLease(sessionId, { hostKind, stateRoot });
   try {
     const result = task(lease);
     if (result && typeof result.then === "function") {
@@ -1018,17 +1053,18 @@ export function withSessionHostRecoveryLease(
   }
 }
 
-export function assertSessionHostWriteAuthority(sessionId) {
-  return defaultAuthority.withWriteAuthority(
+export function assertSessionHostWriteAuthority(sessionId, options = {}) {
+  return authorityFor(options).withWriteAuthority(
     sessionId,
     (authority) => authority,
   );
 }
 
-export function readSessionHostAuthority(sessionId) {
-  return defaultAuthority.readAuthority(sessionId);
+export function readSessionHostAuthority(sessionId, options = {}) {
+  return authorityFor(options).readAuthority(sessionId);
 }
 
-export function revokeSessionHostAuthority(sessionId, options) {
-  return defaultAuthority.revoke(sessionId, options);
+export function revokeSessionHostAuthority(sessionId, options = {}) {
+  const { stateRoot = null, ...revocationOptions } = options;
+  return authorityFor({ stateRoot }).revoke(sessionId, revocationOptions);
 }