chainlesschain 0.165.4 → 0.165.6

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),
       });