chainlesschain 0.162.154 → 0.162.155

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

@@ -0,0 +1,360 @@
+/**
+ * RemoteApprovalBridge — routes interactive permission asks from a LOCAL
+ * agent process (headless run / REPL) to paired mobile/web devices
+ * (gap-analysis 第四阶段 #2).
+ *
+ * The bridge is the remote-session HOST for a client-hosted session: it
+ * connects to a cc WS server (self-hosted or `cc remote-control start`),
+ * registers a remote session under this process's agent session id, and then
+ *
+ *   ask:    publishes a `permission.request` runtime event (fan-out delivers
+ *           to WS members, E2EE relay members, and triggers vendor push wake —
+ *           the event type matches isApprovalRequestEvent).
+ *   answer: paired devices publish `approval.resolve`; because the session is
+ *           NOT server-hosted, the server forwards it back to this host as a
+ *           `remote-session-control` frame (batch-18 protocol extension) and
+ *           the bridge settles the pending gate decision.
+ *   after:  publishes `permission.resolved` so device UIs can clear the card.
+ *
+ * `makeConfirmer()` adapts this to the ApprovalGate confirmer contract
+ * (`async (ctx) => boolean`) with an optional local fallback racing the
+ * remote decision and a fail-closed timeout.
+ */
+
+import { randomBytes } from "crypto";
+import { WsRpcClient } from "./ws-rpc-client.js";
+import {
+  buildDirectPairingUri,
+  pickLanAddress,
+  renderQrCode,
+  resolveRemoteControlOptions,
+} from "./remote-control.js";
+
+const DEFAULT_DECISION_TIMEOUT_MS = 5 * 60 * 1000;
+
+export class RemoteApprovalBridge {
+  constructor({
+    wsUrl,
+    token = null,
+    agentSessionId,
+    name = null,
+    scopes = ["observe", "approve"],
+    decisionTimeoutMs = DEFAULT_DECISION_TIMEOUT_MS,
+    createClient = null,
+    now = Date.now,
+  } = {}) {
+    if (!wsUrl) throw new Error("wsUrl is required");
+    if (!agentSessionId) throw new Error("agentSessionId is required");
+    this.wsUrl = wsUrl;
+    this.token = token;
+    this.agentSessionId = agentSessionId;
+    this.name = name || `approval-bridge:${agentSessionId}`;
+    this.scopes = scopes;
+    this.decisionTimeoutMs = decisionTimeoutMs;
+    this._createClient = createClient || ((url) => new WsRpcClient({ url }));
+    this._now = now;
+    this.client = null;
+    this.remoteSessionId = null;
+    this.pairing = null;
+    this._pending = new Map(); // requestId → { resolve, timer }
+    this._counter = 0;
+    this._closed = false;
+  }
+
+  /** Connect, register the client-hosted remote session, start listening. */
+  async start() {
+    this.client = this._createClient(this.wsUrl);
+    await this.client.connect();
+    await this.client.auth(this.token);
+    this.client.onEvent((message) => this._onServerEvent(message));
+    const created = await this.client.request("remote-session-create", {
+      sessionId: this.agentSessionId,
+      name: this.name,
+      scopes: this.scopes,
+    });
+    this.remoteSessionId = created.session.sessionId;
+    this.pairing = created.pairing;
+    return this;
+  }
+
+  /**
+   * Pairing descriptor for devices. Relay-configured servers return a ready
+   * E2EE URI; otherwise build the direct-LAN URI from the caller's endpoint.
+   */
+  pairingInfo({ lanWsUrl = null } = {}) {
+    if (!this.pairing) return null;
+    const uri =
+      this.pairing.uri ||
+      buildDirectPairingUri({
+        wsUrl: lanWsUrl || this.wsUrl,
+        serverToken: this.token,
+        remoteSessionId: this.remoteSessionId,
+        agentSessionId: this.agentSessionId,
+        pairingToken: this.pairing.token,
+        scopes: this.pairing.scopes,
+        expiresAt: this.pairing.expiresAt,
+      });
+    return {
+      uri,
+      remoteSessionId: this.remoteSessionId,
+      scopes: this.pairing.scopes,
+      expiresAt: this.pairing.expiresAt,
+    };
+  }
+
+  _onServerEvent(message) {
+    if (
+      message?.type !== "remote-session-control" ||
+      message.remoteSessionId !== this.remoteSessionId ||
+      message.event?.type !== "approval.resolve"
+    ) {
+      return;
+    }
+    const requestId = message.event.requestId || message.event.approvalId;
+    const pending = requestId ? this._pending.get(requestId) : null;
+    if (!pending) return;
+    this._pending.delete(requestId);
+    clearTimeout(pending.timer);
+    const answer = message.event.answer ?? message.event.approved;
+    pending.resolve({
+      approved: answer === true || answer === "true" || answer === "yes",
+      via: "remote",
+      from: message.from || null,
+    });
+  }
+
+  /** Number of devices that can approve (excludes this host). */
+  async approverCount() {
+    try {
+      const devices = await this.client.request("remote-session-devices", {
+        remoteSessionId: this.remoteSessionId,
+      });
+      return (devices.devices || []).filter(
+        (device) => !device.isHost && device.scopes?.includes("approve"),
+      ).length;
+    } catch {
+      return 0;
+    }
+  }
+
+  /**
+   * Publish a permission ask to paired devices and await the decision.
+   * Resolves `{approved, via, from}`; times out fail-closed (`approved:false,
+   * via:"timeout"`). The `permission.request` type triggers vendor push wake.
+   */
+  requestDecision({
+    tool,
+    action = null,
+    detail = null,
+    timeoutMs,
+    onRequestId = null,
+  } = {}) {
+    const requestId = `ra-${process.pid}-${++this._counter}-${randomBytes(4).toString("hex")}`;
+    if (onRequestId) {
+      try {
+        onRequestId(requestId);
+      } catch {
+        // observer only
+      }
+    }
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this._pending.delete(requestId);
+        this._publish({
+          type: "permission.resolved",
+          requestId,
+          approved: false,
+          via: "timeout",
+        });
+        resolve({ approved: false, via: "timeout", from: null });
+      }, timeoutMs || this.decisionTimeoutMs);
+      if (typeof timer.unref === "function") timer.unref();
+      this._pending.set(requestId, {
+        timer,
+        resolve: (decision) => {
+          this._publish({
+            type: "permission.resolved",
+            requestId,
+            approved: decision.approved,
+            via: decision.via,
+          });
+          resolve(decision);
+        },
+      });
+      this._publish({
+        type: "permission.request",
+        requestId,
+        tool: tool || null,
+        action,
+        detail,
+        askedAt: this._now(),
+      });
+    });
+  }
+
+  /** Settle a pending ask locally (e.g. the terminal user answered first). */
+  resolveLocally(requestId, approved) {
+    const pending = this._pending.get(requestId);
+    if (!pending) return false;
+    this._pending.delete(requestId);
+    clearTimeout(pending.timer);
+    pending.resolve({ approved, via: "local", from: null });
+    return true;
+  }
+
+  _publish(event) {
+    if (this._closed || !this.client) return;
+    this.client
+      .request("remote-session-publish", {
+        remoteSessionId: this.remoteSessionId,
+        event,
+      })
+      .catch(() => {
+        // Best-effort — a device that missed the request simply cannot answer;
+        // the timeout keeps the gate fail-closed.
+      });
+  }
+
+  /**
+   * ApprovalGate confirmer (`async (ctx) => boolean`). With a `fallback`
+   * confirmer, the LOCAL prompt races the remote decision (first answer wins);
+   * without one (headless), the remote decision alone gates, fail-closed on
+   * timeout.
+   */
+  makeConfirmer({ fallback = null, timeoutMs = null, onAsk = null } = {}) {
+    return async (ctx) => {
+      const ask = {
+        tool: ctx?.tool || ctx?.name || null,
+        action: ctx?.action || null,
+        detail:
+          typeof ctx?.command === "string"
+            ? ctx.command
+            : ctx?.args
+              ? JSON.stringify(ctx.args).slice(0, 2000)
+              : null,
+      };
+      if (onAsk) {
+        try {
+          onAsk(ask);
+        } catch {
+          // observer only
+        }
+      }
+      let requestId = null;
+      const remote = this.requestDecision({
+        ...ask,
+        timeoutMs,
+        onRequestId: (id) => {
+          requestId = id;
+        },
+      });
+      if (!fallback) {
+        const decision = await remote;
+        return decision.approved;
+      }
+      const local = Promise.resolve()
+        .then(() => fallback(ctx))
+        .then((approved) => ({ approved: approved === true, via: "local" }));
+      const decision = await Promise.race([remote, local]);
+      // Local answer won → settle the remote ask too (publishes
+      // permission.resolved so device UIs clear the pending card).
+      if (decision.via === "local" && requestId) {
+        this.resolveLocally(requestId, decision.approved);
+      }
+      return decision.approved;
+    };
+  }
+
+  async close() {
+    this._closed = true;
+    for (const [requestId, pending] of this._pending) {
+      clearTimeout(pending.timer);
+      pending.resolve({ approved: false, via: "closed", from: null });
+      this._pending.delete(requestId);
+    }
+    try {
+      if (this.client && this.remoteSessionId) {
+        await this.client
+          .request("remote-session-close", {
+            remoteSessionId: this.remoteSessionId,
+          })
+          .catch(() => undefined);
+      }
+    } finally {
+      this.client?.close();
+    }
+  }
+}
+
+/**
+ * One-call assembly for headless runs (`cc agent -p --remote-control`):
+ * 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.
+ */
+export async function startHeadlessRemoteApproval({
+  agentSessionId,
+  env = process.env,
+  config = {},
+  writeErr = () => {},
+  isText = false,
+  decisionTimeoutMs = undefined,
+  deps = {},
+} = {}) {
+  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,
+    token: resolved.token,
+    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,
+  });
+  try {
+    await bridge.start();
+  } catch (err) {
+    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`,
+          );
+        }
+      },
+    }),
+    close: async () => {
+      await bridge.close().catch(() => undefined);
+      await server.stop().catch(() => undefined);
+    },
+  };
+}

package/src/lib/remote-control.js

@@ -0,0 +1,270 @@
+/**
+ * remote-control core — option resolution, pairing payloads, and discovery
+ * state for the unified `cc remote-control` entry (gap-analysis 第四阶段 #1).
+ *
+ * The heavy lifting (WS server, remote-session registry, E2EE relay, push)
+ * already exists under src/gateways + src/harness; this module only composes
+ * it into one entry point:
+ *
+ *   - resolveRemoteControlOptions()  flags > env > config > 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).
+ *   - 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).
+ */
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { randomBytes } from "crypto";
+import { REMOTE_SESSION_SCOPES } from "../harness/remote-session-registry.js";
+
+export const REMOTE_CONTROL_DEFAULT_PORT = 18800;
+export const REMOTE_CONTROL_PAIRING_SCHEME =
+  "chainlesschain://remote-control/pair#";
+export const REMOTE_CONTROL_DEFAULT_SCOPES = Object.freeze([
+  "observe",
+  "prompt",
+  "approve",
+  "interrupt",
+]);
+
+function b64url(value) {
+  return Buffer.from(value, "utf8").toString("base64url");
+}
+
+function unb64url(value) {
+  return Buffer.from(String(value), "base64url").toString("utf8");
+}
+
+/** Parse a comma/space separated scope list, validating against the registry. */
+export function parseScopes(raw) {
+  if (raw == null || raw === "") return [...REMOTE_CONTROL_DEFAULT_SCOPES];
+  const scopes = String(raw)
+    .split(/[\s,]+/)
+    .map((scope) => scope.trim())
+    .filter(Boolean);
+  if (scopes.length === 0) return [...REMOTE_CONTROL_DEFAULT_SCOPES];
+  for (const scope of scopes) {
+    if (!REMOTE_SESSION_SCOPES.includes(scope)) {
+      throw new Error(
+        `Unknown remote-control scope "${scope}". Valid: ${REMOTE_SESSION_SCOPES.join(", ")}`,
+      );
+    }
+  }
+  return [...new Set(scopes)];
+}
+
+/**
+ * Resolve effective start options. Precedence: explicit flags > environment >
+ * config (`remoteControl` / legacy `remoteSession` blocks) > defaults. 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.
+ */
+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 resolvedPort =
+    Number.isFinite(port) && port >= 1 && port <= 65535
+      ? Math.floor(port)
+      : REMOTE_CONTROL_DEFAULT_PORT;
+  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 peerId =
+    flags.peerId ||
+    env.CC_REMOTE_SESSION_PEER_ID ||
+    rc.peerId ||
+    legacy.peerId ||
+    (relayUrl
+      ? `cc-host-${os.hostname()}-${randomBytes(4).toString("hex")}`
+      : null);
+  return {
+    port: resolvedPort,
+    host: flags.host || rc.host || "0.0.0.0",
+    token,
+    relayUrl,
+    peerId,
+    scopes: parseScopes(flags.scopes ?? rc.scopes ?? null),
+    name: flags.name || rc.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) {
+        return entry.address;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Direct (LAN) pairing descriptor for hosts without a signaling relay: the
+ * device connects straight to the host's WS endpoint, authenticates with the
+ * embedded server token, then joins the remote session with the one-time
+ * pairing token. Encodes as `chainlesschain://remote-control/pair#<b64url json>`
+ * so the same string works as QR payload and deep link.
+ */
+export function buildDirectPairingUri({
+  wsUrl,
+  serverToken,
+  remoteSessionId,
+  agentSessionId,
+  pairingToken,
+  scopes,
+  expiresAt,
+}) {
+  if (!wsUrl || !remoteSessionId || !pairingToken) {
+    throw new Error("wsUrl, remoteSessionId and pairingToken are required");
+  }
+  const payload = {
+    v: 1,
+    transport: "direct",
+    wsUrl,
+    serverToken: serverToken || null,
+    remoteSessionId,
+    agentSessionId: agentSessionId || null,
+    pairingToken,
+    scopes: Array.isArray(scopes) ? scopes : null,
+    expiresAt: expiresAt ?? null,
+  };
+  return REMOTE_CONTROL_PAIRING_SCHEME + b64url(JSON.stringify(payload));
+}
+
+/** Inverse of buildDirectPairingUri. Throws on malformed input. */
+export function parseDirectPairingUri(uri) {
+  if (
+    typeof uri !== "string" ||
+    !uri.startsWith(REMOTE_CONTROL_PAIRING_SCHEME)
+  ) {
+    throw new Error("Not a remote-control pairing URI");
+  }
+  const payload = JSON.parse(
+    unb64url(uri.slice(REMOTE_CONTROL_PAIRING_SCHEME.length)),
+  );
+  if (payload.v !== 1 || payload.transport !== "direct") {
+    throw new Error(
+      `Unsupported remote-control pairing payload (v=${payload.v}, transport=${payload.transport})`,
+    );
+  }
+  return payload;
+}
+
+// ─── discovery state files ────────────────────────────────────────────────
+
+export function remoteControlStateDir(homedir = os.homedir()) {
+  return path.join(homedir, ".chainlesschain", "remote-control");
+}
+
+function stateFilePath(dir, port) {
+  return path.join(dir, `${port}.json`);
+}
+
+/**
+ * Persist a running host's discovery record (0600 file, 0700 dir). Contains
+ * the server token — local-user trust domain only, mirroring the IDE bridge.
+ */
+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), {
+    encoding: "utf-8",
+    mode: 0o600,
+  });
+  return file;
+}
+
+export function removeRemoteControlState(port, { dir } = {}) {
+  const file = stateFilePath(dir || remoteControlStateDir(), port);
+  try {
+    fs.unlinkSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function isPidAlive(pid) {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM = alive but owned elsewhere; ESRCH = gone.
+    return err.code === "EPERM";
+  }
+}
+
+/**
+ * All discovery records with liveness annotated. Unreadable/corrupt files are
+ * reported as `invalid` rather than thrown (a stale half-written file must
+ * never break `status`).
+ */
+export function readRemoteControlStates({ dir } = {}) {
+  const stateDir = dir || remoteControlStateDir();
+  let names = [];
+  try {
+    names = fs.readdirSync(stateDir).filter((name) => name.endsWith(".json"));
+  } catch {
+    return [];
+  }
+  const states = [];
+  for (const name of names) {
+    const file = path.join(stateDir, name);
+    try {
+      const state = JSON.parse(fs.readFileSync(file, "utf-8"));
+      states.push({
+        ...state,
+        stateFile: file,
+        alive: isPidAlive(state.pid),
+      });
+    } catch {
+      states.push({ stateFile: file, invalid: true, alive: false });
+    }
+  }
+  return states;
+}
+
+/**
+ * Terminal QR for a pairing URI via the OPTIONAL `qrcode` package. Returns
+ * null when unavailable/failed — callers always print the URI regardless.
+ */
+export async function renderQrCode(text, _deps = {}) {
+  try {
+    const importer = _deps.importer || ((spec) => import(spec));
+    const mod = await importer("qrcode");
+    const qrcode = mod.default || mod;
+    return await qrcode.toString(text, { type: "terminal", small: true });
+  } catch {
+    return null;
+  }
+}

package/src/lib/repl-denials.js

@@ -61,6 +61,10 @@ export function classifyDenial(ev = {}) {
     (shellPol ? "shell-policy" : viaFromPrefix(errStr)) ||
     "policy";
   const rule = (policy && policy.rule) || (shellPol && shellPol.ruleId) || null;
+  const chain =
+    result && Array.isArray(result.permissionChain)
+      ? result.permissionChain
+      : null;
   return {
     tool: tool || "?",
     summary: String(
@@ -69,9 +73,29 @@ export function classifyDenial(ev = {}) {
     reason: errStr || "(denied)",
     via,
     rule,
+    ...(chain ? { chain } : {}),
   };
 }
 
+/**
+ * One compact line for a layer-by-layer permission chain, e.g.
+ * `settings-rules→no-match · shell-policy→warn · approval-gate→deny (user-deny, trusted)`.
+ * Returns null when there is nothing to explain.
+ */
+export function formatDenialChain(chain) {
+  if (!Array.isArray(chain) || chain.length === 0) return null;
+  const parts = chain.map((step) => {
+    const base = `${step.layer}→${step.outcome ?? "?"}`;
+    const detail = [
+      step.rule ? String(step.rule) : null,
+      step.via && step.via !== step.outcome ? String(step.via) : null,
+      step.policy ? String(step.policy) : null,
+    ].filter(Boolean);
+    return detail.length ? `${base} (${detail.join(", ")})` : base;
+  });
+  return parts.join(" · ");
+}
+
 /** Two denials are "the same" attempt when tool + command + rule + via match. */
 function sameDenial(a, b) {
   return (
@@ -131,6 +155,8 @@ export function formatDenials(log, opts = {}) {
     const what = d.summary ? `${d.tool} ${d.summary}` : d.tool || "?";
     const times = d.count > 1 ? ` ×${d.count}` : "";
     lines.push(`  • ${what}${times}  [${where}${ago}]`);
+    const chainLine = formatDenialChain(d.chain);
+    if (chainLine) lines.push(`      chain: ${chainLine}`);
     if (d.reason) lines.push(`      ${d.reason}`);
   }
   return lines.join("\n");

package/src/lib/shell-approval.js

@@ -87,5 +87,9 @@ export async function evaluateShellCommandWithApproval({
     shellPolicy,
     riskLevel,
     policy: gateResult.policy,
+    // Explainability passthrough (autoMode.decisions wrapper attaches these):
+    // which gate rule fired and why — surfaced in the permission chain.
+    gateReason: gateResult.reason ?? null,
+    gateRule: gateResult.rule ?? null,
   };
 }