chainlesschain 0.165.4 → 0.165.6

package/src/commands/remote-control.js

@@ -10,13 +10,12 @@
  *   cc remote-control status [--json]
  *   cc remote-control stop [--port N]
  *
- * `start` boots the WS server IN-PROCESS, then opens a loopback client that
- * acts as the remote session HOST (the registry closes a remote session when
- * its host disconnects, so this client stays open for the server's lifetime).
+ * `start` boots the WS server IN-PROCESS, then opens a loopback client backed
+ * by durable possession-proof membership. A crash detaches transport without
+ * silently transferring host authority.
  * With a relay configured you get the E2EE `chainlesschain://remote-session/…`
- * URI; without one you get a direct-LAN pairing URI embedding ws://<lan-ip>.
- * Devices join with observe/prompt/approve/interrupt scopes — the same wire
- * contract the web-panel and Android client already speak.
+ * URI. Without one, the safe default is a loopback-only direct pairing URI;
+ * LAN binding, approval, and interruption are separate explicit opt-ins.
  */
 
 import chalk from "chalk";
@@ -24,16 +23,24 @@ import { logger } from "../lib/logger.js";
 import { loadConfig } from "../lib/config-manager.js";
 import { createAgentRuntimeFactory } from "../runtime/runtime-factory.js";
 import { WsRpcClient } from "../lib/ws-rpc-client.js";
+import { RemoteApprovalBridge } from "../lib/remote-approval-bridge.js";
 import {
-  buildDirectPairingUri,
+  assertDirectWsUrlAllowed,
+  isLoopbackBindHost,
   pickLanAddress,
   readRemoteControlStates,
   removeRemoteControlState,
   renderQrCode,
   resolveRemoteControlOptions,
+  resolveRemoteControlWsUrl,
   writeRemoteControlState,
 } from "../lib/remote-control.js";
 
+function websocketHost(host) {
+  const value = String(host || "127.0.0.1");
+  return value.includes(":") && !value.startsWith("[") ? `[${value}]` : value;
+}
+
 export function registerRemoteControlCommand(program) {
   const cmd = program
     .command("remote-control")
@@ -48,17 +55,23 @@ export function registerRemoteControlCommand(program) {
       "Start the remote-control host (WS server + remote session) and print the pairing URI/QR",
     )
     .option("-p, --port <port>", "WS server port (default 18800)")
-    .option("--host <host>", "Bind host (default 0.0.0.0)")
+    .option("--host <host>", "Bind host (default 127.0.0.1)")
+    .option(
+      "--allow-lan",
+      "DANGEROUS: allow a private/LAN listener (defaults host to 0.0.0.0)",
+    )
     .option("--token <token>", "Server auth token (default: auto-generated)")
     .option(
       "--relay-url <url>",
-      "Signaling relay URL for E2EE pairing (falls back to direct LAN pairing when unset)",
+      "Signaling relay URL for outbound E2EE pairing",
     )
     .option("--peer-id <id>", "Stable relay peer ID for this host")
     .option(
       "--scopes <csv>",
-      "Granted device scopes (observe,prompt,approve,interrupt)",
+      "Base device scopes (default observe,prompt; privileged scopes need their opt-ins)",
     )
+    .option("--allow-approve", "Grant paired devices the approve scope")
+    .option("--allow-interrupt", "Grant paired devices the interrupt scope")
     .option("--name <name>", "Remote session display name")
     .option(
       "--session <agentSessionId>",
@@ -90,6 +103,37 @@ export function registerRemoteControlCommand(program) {
     });
 }
 
+/** Preserve an exact validated bind host instead of broadening it via serve. */
+export function buildRemoteControlServerOptions(resolved) {
+  return {
+    port: resolved.port,
+    host: resolved.host,
+    token: resolved.token,
+    allowRemote: false,
+    remoteSessionRelayUrl: resolved.relayUrl,
+    remoteSessionPeerId: resolved.peerId,
+  };
+}
+
+function redactStatusUrl(value) {
+  if (!value) return value || null;
+  try {
+    const parsed = new URL(String(value));
+    const hadCredentials = Boolean(parsed.username || parsed.password);
+    const hadQuery = Boolean(parsed.search);
+    parsed.username = "";
+    parsed.password = "";
+    parsed.search = "";
+    parsed.hash = "";
+    return (
+      parsed.toString() +
+      (hadCredentials || hadQuery ? "[credentials/query redacted]" : "")
+    );
+  } catch {
+    return "[invalid URL redacted]";
+  }
+}
+
 /**
  * Boot the host: server runtime + loopback host client + remote session +
  * pairing printout + discovery state. Resolves `{code}` (0 = serving; the
@@ -99,6 +143,7 @@ export function registerRemoteControlCommand(program) {
 export async function runRemoteControlStart(options = {}, _deps = {}) {
   const log = _deps.log || ((m) => console.log(m));
   const errLog = _deps.err || ((m) => logger.error(m));
+  const warnLog = _deps.warn || ((m) => logger.warn(m));
   const env = _deps.env || process.env;
   const stateDir = _deps.stateDir; // undefined → default dir
   let config = {};
@@ -114,6 +159,9 @@ export async function runRemoteControlStart(options = {}, _deps = {}) {
       flags: {
         port: options.port,
         host: options.host,
+        allowLan: options.allowLan,
+        allowApprove: options.allowApprove,
+        allowInterrupt: options.allowInterrupt,
         token: options.token,
         relayUrl: options.relayUrl,
         peerId: options.peerId,
@@ -127,6 +175,40 @@ export async function runRemoteControlStart(options = {}, _deps = {}) {
     errLog(err.message);
     return { code: 4 };
   }
+  const localControlHost =
+    resolved.host === "0.0.0.0"
+      ? "127.0.0.1"
+      : resolved.host === "::"
+        ? "::1"
+        : resolved.host;
+  const localControlUrl = `ws://${websocketHost(localControlHost)}:${resolved.port}`;
+
+  for (const warning of resolved.warnings) warnLog(warning);
+  if (resolved.lanAccessible) {
+    warnLog(
+      `LAN access enabled on ${resolved.host}:${resolved.port}. This exposes the ` +
+        "authenticated WebSocket endpoint to the local network; use only on a trusted network." +
+        (resolved.relayUrl
+          ? ""
+          : " Direct pairing uses plaintext ws:// with bearer credentials; prefer --relay-url when available."),
+    );
+  }
+  const lanAddress = resolved.lanAccessible
+    ? _deps.lanAddress ||
+      (_deps.pickLanAddress ? _deps.pickLanAddress() : pickLanAddress())
+    : null;
+  const preflightWsUrl = resolveRemoteControlWsUrl(resolved, { lanAddress });
+  if (
+    !resolved.relayUrl &&
+    resolved.lanAccessible &&
+    isLoopbackBindHost(new URL(preflightWsUrl).hostname)
+  ) {
+    errLog(
+      "LAN binding is enabled but no private LAN address can be advertised; " +
+        "use --host with a private interface address or configure a relay",
+    );
+    return { code: 4 };
+  }
 
   // Refuse to double-start on a port that already has a LIVE host.
   const existing = readRemoteControlStates({ dir: stateDir }).find(
@@ -146,14 +228,7 @@ export async function runRemoteControlStart(options = {}, _deps = {}) {
       _deps.startServer ||
       (async () =>
         createAgentRuntimeFactory()
-          .createServerRuntime({
-            port: resolved.port,
-            host: resolved.host,
-            token: resolved.token,
-            allowRemote: resolved.host !== "127.0.0.1",
-            remoteSessionRelayUrl: resolved.relayUrl,
-            remoteSessionPeerId: resolved.peerId,
-          })
+          .createServerRuntime(buildRemoteControlServerOptions(resolved))
           .startServer());
     server = await startServer(resolved);
   } catch (err) {
@@ -161,19 +236,19 @@ export async function runRemoteControlStart(options = {}, _deps = {}) {
     return { code: 1 };
   }
 
-  // Loopback HOST connection — must stay open, its disconnect closes the
-  // remote session (registry semantics).
-  const client =
-    _deps.createClient?.(resolved) ||
-    new WsRpcClient({ url: `ws://127.0.0.1:${resolved.port}` });
-  let remoteSession;
-  let pairing;
+  // Create an agent session first when the caller did not select one. This
+  // bootstrap client is not the Remote Session host and never receives pairing
+  // authority.
+  let sessionClient = null;
   let agentSessionId = options.session || null;
   try {
-    await client.connect();
-    await client.auth(resolved.token);
     if (!agentSessionId) {
-      const created = await client.request("session-create", {
+      sessionClient = new WsRpcClient({
+        url: localControlUrl,
+      });
+      await sessionClient.connect();
+      await sessionClient.auth(resolved.token);
+      const created = await sessionClient.request("session-create", {
         sessionType: "agent",
         projectRoot: _deps.cwd || process.cwd(),
       });
@@ -186,16 +261,42 @@ export async function runRemoteControlStart(options = {}, _deps = {}) {
         throw new Error("session-create returned no sessionId");
       }
     }
-    const createdRemote = await client.request("remote-session-create", {
-      sessionId: agentSessionId,
+  } catch (err) {
+    errLog(`Failed to create agent session: ${err.message}`);
+    sessionClient?.close();
+    try {
+      await server.stop?.();
+    } catch {
+      // best-effort teardown
+    }
+    return { code: 1 };
+  } finally {
+    sessionClient?.close();
+  }
+
+  // Standalone start uses the same durable, possession-proof membership host
+  // as headless/REPL approvals. A crash detaches the transport; restarting with
+  // the same agent session resumes or re-enables the durable membership.
+  const createBridge =
+    _deps.createBridge ||
+    ((bridgeOptions) => new RemoteApprovalBridge(bridgeOptions));
+  let bridge;
+  try {
+    bridge = createBridge({
+      wsUrl: localControlUrl,
+      token: resolved.token,
+      agentSessionId,
       name: resolved.name,
       scopes: resolved.scopes,
+      approvalStateFile: _deps.approvalStateFile,
+      membershipHostStateFile: _deps.membershipHostStateFile,
+      membershipHostWitnessFile: _deps.membershipHostWitnessFile,
+      membershipHostAuthorityLockFile: _deps.membershipHostAuthorityLockFile,
     });
-    remoteSession = createdRemote.session;
-    pairing = createdRemote.pairing;
+    await bridge.start();
   } catch (err) {
-    errLog(`Failed to create remote session: ${err.message}`);
-    client.close();
+    errLog(`Failed to create durable remote session: ${err.message}`);
+    await bridge?.close?.().catch(() => undefined);
     try {
       await server.stop?.();
     } catch {
@@ -203,37 +304,63 @@ export async function runRemoteControlStart(options = {}, _deps = {}) {
     }
     return { code: 1 };
   }
+  const client = bridge.client;
+  const pairing = bridge.pairing;
+  const remoteSession = {
+    sessionId: bridge.remoteSessionId,
+  };
 
-  const relayMode = Boolean(pairing?.uri);
-  const lanAddress = _deps.lanAddress || pickLanAddress() || "127.0.0.1";
-  const wsUrl = `ws://${lanAddress}:${resolved.port}`;
-  const pairingUri = relayMode
-    ? pairing.uri
-    : buildDirectPairingUri({
-        wsUrl,
-        serverToken: resolved.token,
-        remoteSessionId: remoteSession.sessionId,
-        agentSessionId,
-        pairingToken: pairing.token,
-        scopes: pairing.scopes,
-        expiresAt: pairing.expiresAt,
-      });
+  let relayMode;
+  let wsUrl;
+  let pairingUri;
+  try {
+    relayMode = Boolean(pairing?.uri);
+    if (resolved.relayUrl && !relayMode) {
+      throw new Error(
+        "Relay pairing was requested but no relay URI was issued; refusing direct fallback",
+      );
+    }
+    wsUrl = resolveRemoteControlWsUrl(resolved, { lanAddress });
+    if (!relayMode) assertDirectWsUrlAllowed(wsUrl);
+    pairingUri = bridge.pairingInfo({ lanWsUrl: wsUrl })?.uri;
+    if (!pairingUri) throw new Error("Remote session returned no pairing URI");
+  } catch (err) {
+    await bridge.close?.().catch(() => undefined);
+    await server.stop?.().catch(() => undefined);
+    errLog(`Failed to finish remote-control startup: ${err.message}`);
+    return { code: 1 };
+  }
 
   const state = {
     pid: process.pid,
     port: resolved.port,
     host: resolved.host,
     wsUrl,
-    token: resolved.token,
     mode: relayMode ? "relay" : "direct",
-    relayUrl: resolved.relayUrl || null,
+    exposure: relayMode
+      ? "outbound-relay"
+      : resolved.lanAccessible
+        ? "direct-lan"
+        : "loopback",
+    lanAccessible: resolved.lanAccessible,
+    relayUrl: redactStatusUrl(resolved.relayUrl),
     peerId: resolved.peerId || null,
     agentSessionId,
     remoteSessionId: remoteSession.sessionId,
     scopes: pairing.scopes,
     startedAt: new Date().toISOString(),
   };
-  const stateFile = writeRemoteControlState(state, { dir: stateDir });
+  let stateFile;
+  try {
+    stateFile = (_deps.writeState || writeRemoteControlState)(state, {
+      dir: stateDir,
+    });
+  } catch (err) {
+    await bridge.close?.().catch(() => undefined);
+    await server.stop?.().catch(() => undefined);
+    errLog(`Failed to finish remote-control startup: ${err.message}`);
+    return { code: 1 };
+  }
   const cleanup = () => {
     removeRemoteControlState(resolved.port, { dir: stateDir });
   };
@@ -241,70 +368,102 @@ export async function runRemoteControlStart(options = {}, _deps = {}) {
   process.once("SIGINT", cleanup);
   process.once("SIGTERM", cleanup);
 
-  if (options.json) {
-    log(
-      JSON.stringify(
-        {
-          mode: state.mode,
-          wsUrl,
-          port: resolved.port,
-          agentSessionId,
-          remoteSessionId: remoteSession.sessionId,
-          pairingUri,
-          pairing: {
-            token: pairing.token,
-            scopes: pairing.scopes,
-            expiresAt: pairing.expiresAt,
+  try {
+    if (options.json) {
+      log(
+        JSON.stringify(
+          {
+            mode: state.mode,
+            exposure: state.exposure,
+            host: resolved.host,
+            lanAccessible: resolved.lanAccessible,
+            wsUrl,
+            port: resolved.port,
+            agentSessionId,
+            remoteSessionId: remoteSession.sessionId,
+            pairingUri,
+            pairing: {
+              token: pairing.token,
+              scopes: pairing.scopes,
+              expiresAt: pairing.expiresAt,
+            },
+            stateFile,
           },
-          stateFile,
-        },
-        null,
-        2,
-      ),
-    );
-  } else {
-    log("");
-    log(chalk.bold("  Remote Control ready"));
-    log("");
-    log(
-      `  Mode:        ${state.mode === "relay" ? chalk.cyan("relay (E2EE)") : chalk.cyan("direct LAN")}`,
-    );
-    log(`  WS server:   ${chalk.cyan(wsUrl)}`);
-    log(`  Agent sess:  ${agentSessionId}`);
-    log(`  Remote sess: ${remoteSession.sessionId}`);
-    log(`  Scopes:      ${pairing.scopes.join(", ")}`);
-    log(
-      `  Token exp:   ${pairing.expiresAt ? new Date(pairing.expiresAt).toISOString() : "n/a"} ${chalk.dim("(one-time; re-run start for another device)")}`,
-    );
-    log("");
-    log("  Pairing URI (open in ChainlessChain mobile / paste in web panel):");
-    log("");
-    log("    " + chalk.green(pairingUri));
-    if (options.qr !== false) {
-      const qr = await renderQrCode(pairingUri, _deps);
-      if (qr) {
-        log("");
-        log(
-          qr
-            .split("\n")
-            .map((line) => "  " + line)
-            .join("\n"),
-        );
-      } else {
+          null,
+          2,
+        ),
+      );
+    } else {
+      log("");
+      log(chalk.bold("  Remote Control ready"));
+      log("");
+      log(
+        `  Mode:        ${
+          state.mode === "relay"
+            ? chalk.cyan("relay (E2EE, outbound)")
+            : state.exposure === "direct-lan"
+              ? chalk.yellow("direct LAN (explicit opt-in)")
+              : chalk.cyan("direct loopback")
+        }`,
+      );
+      log(`  WS server:   ${chalk.cyan(wsUrl)}`);
+      log(`  Agent sess:  ${agentSessionId}`);
+      log(`  Remote sess: ${remoteSession.sessionId}`);
+      log(`  Scopes:      ${pairing.scopes.join(", ")}`);
+      log(
+        `  Token exp:   ${pairing.expiresAt ? new Date(pairing.expiresAt).toISOString() : "n/a"} ${chalk.dim("(one-time; re-run start for another device)")}`,
+      );
+      log("");
+      log(
+        relayMode || resolved.lanAccessible
+          ? "  Pairing URI (open in ChainlessChain mobile / paste in web panel):"
+          : "  Pairing URI (local clients on this machine only):",
+      );
+      log("");
+      log("    " + chalk.green(pairingUri));
+      if (!relayMode && !resolved.lanAccessible) {
         log("");
         log(
-          chalk.dim(
-            "  (install the optional `qrcode` package for a terminal QR)",
+          chalk.yellow(
+            "  Loopback only: use --allow-lan on a trusted network or configure --relay-url for another device.",
           ),
         );
       }
+      if (options.qr !== false && (relayMode || resolved.lanAccessible)) {
+        const qr = await renderQrCode(pairingUri, _deps);
+        if (qr) {
+          log("");
+          log(
+            qr
+              .split("\n")
+              .map((line) => "  " + line)
+              .join("\n"),
+          );
+        } else {
+          log("");
+          log(
+            chalk.dim(
+              "  (install the optional `qrcode` package for a terminal QR)",
+            ),
+          );
+        }
+      }
+      log("");
+      log(chalk.dim("  Press Ctrl+C to stop"));
+      log("");
     }
-    log("");
-    log(chalk.dim("  Press Ctrl+C to stop"));
-    log("");
+  } catch (err) {
+    process.removeListener("exit", cleanup);
+    process.removeListener("SIGINT", cleanup);
+    process.removeListener("SIGTERM", cleanup);
+    cleanup();
+    await bridge.close?.().catch(() => undefined);
+    await server.stop?.().catch(() => undefined);
+    errLog(`Failed to finish remote-control startup: ${err.message}`);
+    return { code: 1 };
   }
 
-  return { code: 0, client, server, state, pairingUri };
+  return { code: 0, client, bridge, server, state, pairingUri };
 }
 
 export function runRemoteControlStatus(options = {}, _deps = {}) {
@@ -320,9 +479,20 @@ export function runRemoteControlStatus(options = {}, _deps = {}) {
   if (options.json) {
     log(
       JSON.stringify(
-        // The token stays in the 0600 state file — status output may be pasted
-        // into issues/chat, so redact it here.
-        states.map(({ token: _token, ...rest }) => rest),
+        // Defense in depth for legacy state files written before tokens were
+        // removed from discovery state.
+        states.map(
+          ({
+            token: _token,
+            serverToken: _serverToken,
+            pairingToken: _pairingToken,
+            pairingUri: _pairingUri,
+            ...rest
+          }) => ({
+            ...rest,
+            relayUrl: redactStatusUrl(rest.relayUrl),
+          }),
+        ),
         null,
         2,
       ),
@@ -343,7 +513,22 @@ export function runRemoteControlStatus(options = {}, _deps = {}) {
     const badge = state.alive ? chalk.green("running") : chalk.yellow("stale");
     log(
       `  ${badge}  port ${String(state.port).padEnd(6)} pid ${String(state.pid).padEnd(8)} ` +
-        `${(state.mode || "?").padEnd(7)} session ${state.agentSessionId || "?"}`,
+        `${(state.mode || "?").padEnd(7)} ${(state.exposure || "?").padEnd(18)} ` +
+        `host ${state.host || "?"} session ${state.agentSessionId || "?"}`,
+    );
+  }
+  if (
+    states.some(
+      (state) =>
+        state.alive &&
+        state.legacyExposure &&
+        state.exposure === "legacy-unknown-lan",
+    )
+  ) {
+    log(
+      chalk.red(
+        "  Warning: a legacy host may still be LAN-exposed. Stop and restart it to apply the loopback default.",
+      ),
     );
   }
   log("");

package/src/commands/session-location.js

@@ -5,6 +5,7 @@ import {
   buildExecutionLocationCatalog,
   buildExecutionLocationHandoffPreview,
   computeExecutionLocationTargetFactsDigest,
+  createExecutionLocationTargetAttestation,
 } from "../lib/execution-location-contract.js";
 import { captureAmbientExecutionLocation } from "../lib/execution-location-runtime.js";
 import {
@@ -333,6 +334,24 @@ export function prepareSessionReplicaHandoff(sessionId, options, deps = {}) {
   if (targetFactsDigest !== String(options.expectedTargetFactsDigest || "")) {
     throw new Error("target facts changed before location handoff append");
   }
+  if (!/^sha256:[a-f0-9]{64}$/u.test(String(options.attestationDigest || ""))) {
+    throw new Error("source target attestation digest is invalid");
+  }
+  // observedAt is intentionally excluded from targetFactsDigest but included
+  // in attestationDigest. The source-side probe and this target-side prepare
+  // are separate process invocations, so a real target can never reproduce
+  // the source probe's timestamp. Bind the handoff event to this fresh target
+  // observation; the source rehashes its receipt and immediately verifies the
+  // canonical target projection before it is allowed to resume.
+  const targetAttestation = createExecutionLocationTargetAttestation({
+    profileDigest: options.profileDigest,
+    sourceSessionId: sessionId,
+    sourceHeadHash: options.expectedHeadHash,
+    sourceEventCount: Number(options.expectedEventCount),
+    targetEvidenceId: options.targetEvidenceId,
+    baseCommit: binding.source.git.commit,
+    binding,
+  });
   return (
     deps.installSessionReplicaWithLocationHandoff ||
     installSessionReplicaWithLocationHandoff
@@ -348,7 +367,7 @@ export function prepareSessionReplicaHandoff(sessionId, options, deps = {}) {
       profileDigest: options.profileDigest,
       targetEvidenceId: options.targetEvidenceId,
       targetFactsDigest,
-      attestationDigest: options.attestationDigest,
+      attestationDigest: targetAttestation.attestationDigest,
       binding,
     },
   );