chainlesschain 0.165.5 → 0.165.6

package/src/lib/remote-approval-bridge.js

@@ -43,11 +43,15 @@ import {
   REMOTE_MEMBERSHIP_HOST_UNAVAILABLE_CODE,
 } from "./remote-membership-host-store.js";
 import {
+  assertDirectWsUrlAllowed,
   buildDirectPairingUri,
+  isLoopbackBindHost,
   pickLanAddress,
   renderQrCode,
   resolveRemoteControlOptions,
+  resolveRemoteControlWsUrl,
 } from "./remote-control.js";
+import { logger } from "./logger.js";
 
 const DEFAULT_DECISION_TIMEOUT_MS = 5 * 60 * 1000;
 const REMOTE_LEASE_AUTHORIZATION_KIND =
@@ -345,7 +349,8 @@ export class RemoteApprovalBridge {
 
   /**
    * Pairing descriptor for devices. Relay-configured servers return a ready
-   * E2EE URI; otherwise build the direct-LAN URI from the caller's endpoint.
+   * E2EE URI; otherwise build a direct URI from the explicitly selected
+   * loopback/LAN endpoint.
    */
   pairingInfo({ lanWsUrl = null } = {}) {
     if (!this.pairing) return null;
@@ -363,6 +368,7 @@ export class RemoteApprovalBridge {
       });
     return {
       uri,
+      mode: this.pairing.uri ? "relay" : "direct",
       remoteSessionId: this.remoteSessionId,
       scopes: this.pairing.scopes,
       expiresAt: this.pairing.expiresAt,
@@ -1297,21 +1303,60 @@ export class RemoteApprovalBridge {
  * self-hosts a lightweight WS server on an OS-assigned port (no sessionManager
  * needed — the session stays client-hosted), starts a bridge for this run's
  * session, prints the pairing URI (+ optional QR) to stderr, and returns the
- * gate confirmer + teardown. Relay settings (env/config) flow through, so a
- * configured relay yields an E2EE pairing URI reaching devices off-LAN.
+ * gate confirmer + teardown. Relay settings flow through the startup
+ * environment; LAN exposure remains a separate explicit caller authority.
  */
 export async function startHeadlessRemoteApproval({
   agentSessionId,
+  allowLan = false,
   env = process.env,
-  config = {},
+  config = undefined,
   writeErr = () => {},
   isText = false,
   decisionTimeoutMs = undefined,
   deps = {},
 } = {}) {
+  let effectiveConfig = config;
+  if (effectiveConfig === undefined) {
+    try {
+      const configModule =
+        deps.configModule || (await import("./config-manager.js"));
+      effectiveConfig = configModule.loadConfig();
+    } catch {
+      effectiveConfig = {};
+    }
+  }
+  const resolved = resolveRemoteControlOptions({
+    flags: { allowApprove: true, allowLan: allowLan === true },
+    env,
+    config: effectiveConfig || {},
+  });
+  if (!resolved.relayUrl && !resolved.lanAccessible) {
+    throw new Error(
+      "remote approval is loopback-only by default; configure a relay, or enable " +
+        "allowLan with a non-loopback host (omit host to use 0.0.0.0) on a trusted network",
+    );
+  }
+  const lanAddress = resolved.lanAccessible
+    ? deps.lanAddress ||
+      (deps.pickLanAddress ? deps.pickLanAddress() : pickLanAddress())
+    : null;
+  const preflightLanWsUrl = resolveRemoteControlWsUrl(
+    { ...resolved, port: 1 },
+    { lanAddress },
+  );
+  if (
+    !resolved.relayUrl &&
+    resolved.lanAccessible &&
+    isLoopbackBindHost(new URL(preflightLanWsUrl).hostname)
+  ) {
+    throw new Error(
+      "LAN binding is enabled but no private LAN address can be advertised; " +
+        "configure a private host or a relay",
+    );
+  }
   const { ChainlessChainWSServer } =
     deps.serverModule || (await import("../gateways/ws/ws-server.js"));
-  const resolved = resolveRemoteControlOptions({ flags: {}, env, config });
   const server = new ChainlessChainWSServer({
     port: 0,
     host: resolved.host,
@@ -1319,50 +1364,95 @@ export async function startHeadlessRemoteApproval({
     remoteSessionRelayUrl: resolved.relayUrl,
     remoteSessionPeerId: resolved.peerId,
   });
-  await server.start();
-  const bridge = new RemoteApprovalBridge({
-    wsUrl: `ws://127.0.0.1:${server.port}`,
-    token: resolved.token,
-    agentSessionId,
-    scopes: ["observe", "approve"],
-    decisionTimeoutMs,
-  });
+  let bridge;
   try {
-    await bridge.start();
+    await server.start();
+    const createBridge =
+      deps.createBridge || ((options) => new RemoteApprovalBridge(options));
+    bridge = createBridge({
+      wsUrl: resolveRemoteControlWsUrl(
+        { ...resolved, port: server.port, allowLan: resolved.lanAccessible },
+        { lanAddress: null },
+      ),
+      token: resolved.token,
+      agentSessionId,
+      scopes: ["observe", "approve"],
+      decisionTimeoutMs,
+    });
+    try {
+      await bridge.start();
+    } catch (err) {
+      await server.stop().catch(() => undefined);
+      throw err;
+    }
+    const lanWsUrl = resolveRemoteControlWsUrl(
+      { ...resolved, port: server.port },
+      { lanAddress },
+    );
+    const pairing = bridge.pairingInfo({ lanWsUrl });
+    if (resolved.relayUrl && pairing?.mode !== "relay") {
+      throw new Error(
+        "the configured relay did not provide a pairing URI; refusing to fall back to direct pairing",
+      );
+    }
+    if (
+      !resolved.relayUrl &&
+      pairing?.mode !== "relay" &&
+      !resolved.lanAccessible
+    ) {
+      throw new Error(
+        "direct remote approval requires explicit allowLan on a trusted network",
+      );
+    }
+    if (pairing?.mode === "direct") {
+      if (isLoopbackBindHost(new URL(lanWsUrl).hostname)) {
+        throw new Error(
+          "LAN binding is enabled but no private LAN address can be advertised",
+        );
+      }
+      assertDirectWsUrlAllowed(lanWsUrl);
+      const warn = deps.warn || ((message) => logger.warn(message));
+      warn(
+        `LAN remote approval enabled on ${resolved.host}:${server.port}. ` +
+          "Direct pairing uses plaintext ws:// with bearer credentials; use only on a trusted network.",
+      );
+    }
+    if (!pairing?.uri) {
+      throw new Error("remote approval did not produce a pairing URI");
+    }
+    if (isText) {
+      writeErr(
+        "  remote-control: approvals can be answered from a paired device\n",
+      );
+      writeErr(`  pairing: ${pairing.uri}\n`);
+      const qr = await renderQrCode(pairing.uri, deps);
+      if (qr) writeErr(qr + "\n");
+    }
+    return {
+      pairing,
+      server,
+      bridge,
+      confirmer: bridge.makeConfirmer({
+        onAsk: (ask) => {
+          if (isText) {
+            writeErr(
+              `  permission(${ask.tool || "?"}): waiting for remote approval…\n`,
+            );
+          }
+        },
+      }),
+      consumeAuthorization: (authorization, context) =>
+        bridge.consumeAuthorization(authorization, context),
+      close: async () => {
+        await bridge.close().catch(() => undefined);
+        await server.stop().catch(() => undefined);
+      },
+    };
   } catch (err) {
+    if (bridge) {
+      await bridge.close().catch(() => undefined);
+    }
     await server.stop().catch(() => undefined);
     throw err;
   }
-  const lanAddress = deps.lanAddress || pickLanAddress() || "127.0.0.1";
-  const pairing = bridge.pairingInfo({
-    lanWsUrl: `ws://${lanAddress}:${server.port}`,
-  });
-  if (isText) {
-    writeErr(
-      "  remote-control: approvals can be answered from a paired device\n",
-    );
-    writeErr(`  pairing: ${pairing.uri}\n`);
-    const qr = await renderQrCode(pairing.uri, deps);
-    if (qr) writeErr(qr + "\n");
-  }
-  return {
-    pairing,
-    server,
-    bridge,
-    confirmer: bridge.makeConfirmer({
-      onAsk: (ask) => {
-        if (isText) {
-          writeErr(
-            `  permission(${ask.tool || "?"}): waiting for remote approval…\n`,
-          );
-        }
-      },
-    }),
-    consumeAuthorization: (authorization, context) =>
-      bridge.consumeAuthorization(authorization, context),
-    close: async () => {
-      await bridge.close().catch(() => undefined);
-      await server.stop().catch(() => undefined);
-    },
-  };
 }

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