@securecoms/agent-bridge 0.4.0 → 0.6.0

package/README.md

@@ -348,6 +348,16 @@ pm2 start "npx @agentvault/connect-agent-bridge --credential ./agent.json" \
   --name securecoms-bridge
 ```
 
+### Install behavior
+
+`agent-bridge install --credential <path>` (launchd on macOS, systemd user unit on Linux) prepares and verifies the service rather than pointing it at your download:
+
+- The credential file is validated (readable, valid JSON, all required fields) and **copied into a durable per-agent directory** `~/securecoms-agent-<slug>/` (dir `0700`, file `0600`). The service runs from that copy, so moving or deleting the original download can't break the daemon. A directory already owned by a *different* agent identity is refused, never overwritten.
+- A **free port is auto-selected** from `7077-7276` (lowest free wins; sibling service definitions and live binds both count as taken). Pass `--port N` to override; the explicit port is honored as-is.
+- Install **verifies the daemon actually came up** and fails loudly with the log path if it didn't — no silent crash-loops.
+- Install echoes the credential's `device_id`, `issued_at`, and a redacted api-key fingerprint so you can confirm you installed the newest download. **Re-running install is the only way to update a live (e.g. rotated) credential** — replacing the downloaded file alone does nothing.
+- Optional `--harness openclaw|hermes|custom` prints a paste-ready config snippet with the chosen port and the token-file path (the token itself never appears in output).
+
 ---
 
 ## Security

package/connectors/openclaw/gate.js

@@ -0,0 +1,41 @@
+// packages/connect-agent-bridge/connectors/openclaw/gate.js
+// ESM module (package is "type":"module"). No require / module.exports (audit C1).
+
+// bound_identity: explicit binding ONLY. `listConnections` is passed but INTENTIONALLY
+// never consulted — bound_identity must be a positive act, never a directory census
+// (audit C1). The seam exists so a test can prove no auto-discovery, and so the §9 C1
+// mutation ("reintroduce auto-discovery here") has a concrete target that turns red.
+export function resolveBoundIdentity(env, readFileText, bindingPath, listConnections) {
+  void listConnections; // never used by design
+  const connFile = env && env.SECURECOMS_CONNECTION_FILE;
+  if (connFile) {
+    try {
+      const id = JSON.parse(readFileText(connFile)).identity_id;
+      if (id) return id;
+    } catch (_) { /* fall through */ }
+  }
+  try {
+    const id = JSON.parse(readFileText(bindingPath)).identity_id;
+    if (id) return id;
+  } catch (_) { /* no binding */ }
+  return null;
+}
+
+export function evaluateGate(input) {
+  const { fileIdentity, healthzIdentity, boundIdentity } = input;
+  if (!boundIdentity) return { ok: false, reason: "unwired: no binding (refusing to guess)" };
+  if (fileIdentity !== healthzIdentity) {
+    return { ok: false, reason: "check 1 failed: file identity != daemon identity (stale port reuse)" };
+  }
+  if (boundIdentity !== healthzIdentity) {
+    return { ok: false, reason: "check 2 failed: bound identity != daemon identity (wrong file / compartment)" };
+  }
+  return { ok: true };
+}
+
+export function backoffDelayMs(attempt) {
+  const base = 250;
+  const cap = 30000;
+  const exp = Math.min(cap, base * Math.pow(2, Math.max(0, attempt)));
+  return Math.floor(Math.random() * exp); // full jitter
+}

package/connectors/openclaw/gate.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from "vitest";
+import { resolveBoundIdentity, evaluateGate, backoffDelayMs } from "./gate.js";
+
+describe("evaluateGate (two anchors)", () => {
+  it("passes when file, healthz, and bound all agree", () => {
+    expect(evaluateGate({ fileIdentity: "A", healthzIdentity: "A", boundIdentity: "A" }).ok).toBe(true);
+  });
+  it("Check 1 fails on stale port reuse (file A, daemon reports B)", () => {
+    const r = evaluateGate({ fileIdentity: "A", healthzIdentity: "B", boundIdentity: "A" });
+    expect(r.ok).toBe(false);
+    expect(r.reason).toMatch(/check 1 failed/i);
+  });
+  it("Check 2 fails on wrong-file compartment crossing (bound B, self-consistent file A)", () => {
+    // The audit C1/wrong-file case: file(A) and daemon(A) agree, but the connector is bound to B.
+    const r = evaluateGate({ fileIdentity: "A", healthzIdentity: "A", boundIdentity: "B" });
+    expect(r.ok).toBe(false);
+    expect(r.reason).toMatch(/check 2 failed/i);
+  });
+  it("refuses when there is no binding (null) — no directory census", () => {
+    const r = evaluateGate({ fileIdentity: "A", healthzIdentity: "A", boundIdentity: null });
+    expect(r.ok).toBe(false);
+  });
+});
+
+describe("resolveBoundIdentity", () => {
+  const noList = () => [] as string[];
+  it("reads identity from SECURECOMS_CONNECTION_FILE", () => {
+    const read = (p: string) => p === "/conn/A.json" ? JSON.stringify({ identity_id: "A" }) : "";
+    expect(resolveBoundIdentity({ SECURECOMS_CONNECTION_FILE: "/conn/A.json" }, read, "/plugin/securecoms.binding.json", noList)).toBe("A");
+  });
+  it("reads identity from securecoms.binding.json when no env", () => {
+    const read = (p: string) => p === "/plugin/securecoms.binding.json" ? JSON.stringify({ identity_id: "B" }) : "";
+    expect(resolveBoundIdentity({}, read, "/plugin/securecoms.binding.json", noList)).toBe("B");
+  });
+  it("returns null when neither is present (connector must wait, never guess)", () => {
+    const read = () => { throw new Error("ENOENT"); };
+    expect(resolveBoundIdentity({}, read, "/plugin/securecoms.binding.json", noList)).toBeNull();
+  });
+  it("C1 REGRESSION: refuses (null) even when the connections dir has exactly one file — NO auto-discovery (audit C1)", () => {
+    const read = () => { throw new Error("ENOENT"); };       // no env conn file, no binding
+    const listConnections = () => ["A.json"];                // a sole connection file exists
+    expect(resolveBoundIdentity({}, read, "/plugin/securecoms.binding.json", listConnections)).toBeNull();
+  });
+});
+
+describe("backoffDelayMs", () => {
+  it("is bounded by the cap and never negative", () => {
+    for (let i = 0; i < 20; i++) {
+      const d = backoffDelayMs(i);
+      expect(d).toBeGreaterThanOrEqual(0);
+      expect(d).toBeLessThanOrEqual(30000);
+    }
+  });
+});

package/connectors/openclaw/openclaw-entry.gate.test.ts

@@ -0,0 +1,321 @@
+// packages/connect-agent-bridge/connectors/openclaw/openclaw-entry.gate.test.ts
+//
+// The security-bearing wiring test: proves the two-anchor gate (gate.js,
+// exercised through openclaw-entry.js's real startAccount path) actually
+// BLOCKS a WS open on an identity mismatch, and actually OPENS one on a
+// match. gate.test.ts only exercises evaluateGate() as a pure function —
+// nothing previously proved the connector calls it before _connect(), or
+// that a failure really suppresses `new WebSocket(...)`.
+//
+// Drives the real plugin.gateway.startAccount(ctx) with a tmp $HOME
+// containing a real (buildConnectionFile-shaped) connection file, and stubs
+// only the two I/O seams the connector touches: global fetch (for
+// GET /healthz) and global WebSocket.
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mkdtempSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildConnectionFile, writeConnectionFile } from "../../src/service/connection-file.js";
+
+const BOUND_ID = "wiring-test-bound-identity";
+const OTHER_ID = "wiring-test-other-identity";
+const PORT = 7099;
+const TOKEN_VALUE = "wiring-test-token-value";
+
+const ORIGINAL_CONN_FILE_ENV = process.env.SECURECOMS_CONNECTION_FILE;
+
+function waitFor(predicate: () => boolean, opts: { timeout?: number; interval?: number } = {}): Promise<void> {
+  const { timeout = 3000, interval = 10 } = opts;
+  const start = Date.now();
+  return new Promise((resolve, reject) => {
+    const check = () => {
+      if (predicate()) return resolve();
+      if (Date.now() - start > timeout) return reject(new Error("waitFor: condition never became true"));
+      setTimeout(check, interval);
+    };
+    check();
+  });
+}
+
+// Fresh FakeWebSocket class + instance list per test, so nothing leaks
+// between cases.
+function makeFakeWebSocket() {
+  const instances: Array<{
+    url: string;
+    listeners: Record<string, Array<(ev?: unknown) => void>>;
+    close: () => void;
+    _emit: (type: string, ev?: unknown) => void;
+  }> = [];
+
+  class FakeWebSocket {
+    url: string;
+    listeners: Record<string, Array<(ev?: unknown) => void>> = {};
+
+    constructor(url: string) {
+      this.url = url;
+      instances.push(this);
+    }
+
+    addEventListener(type: string, cb: (ev?: unknown) => void) {
+      (this.listeners[type] ??= []).push(cb);
+    }
+
+    send() {
+      /* no-op */
+    }
+
+    close() {
+      this._emit("close");
+    }
+
+    _emit(type: string, ev?: unknown) {
+      for (const cb of this.listeners[type] ?? []) cb(ev ?? {});
+    }
+  }
+
+  return { FakeWebSocket, instances };
+}
+
+describe("openclaw-entry — gate blocks/allows the WS open (wiring)", () => {
+  let home: string;
+  let connFilePath: string;
+  let tokenFilePath: string;
+  let logs: string[];
+  let healthzIdentity: string;
+  let fetchMock: ReturnType<typeof vi.fn>;
+  let controller: AbortController;
+
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), "sc-wiring-"));
+
+    tokenFilePath = join(home, "bridge-token");
+    writeFileSync(tokenFilePath, TOKEN_VALUE, { mode: 0o600 });
+
+    const doc = buildConnectionFile({
+      identityId: BOUND_ID,
+      port: PORT,
+      tokenFile: tokenFilePath,
+      slug: "wiring-test",
+      label: "Wiring Test",
+      instanceId: "wiring-test-instance",
+      now: new Date().toISOString(),
+    });
+    writeConnectionFile(home, doc);
+    // Same file doubles as the SECURECOMS_CONNECTION_FILE binding source —
+    // resolveBoundIdentity only ever reads its .identity_id field.
+    connFilePath = join(home, ".securecoms", "connections", `${BOUND_ID}.json`);
+    process.env.SECURECOMS_CONNECTION_FILE = connFilePath;
+
+    logs = [];
+    healthzIdentity = OTHER_ID; // default: mismatched, overridden per test
+    fetchMock = vi.fn(async (url: string) => {
+      if (String(url).endsWith("/healthz")) {
+        return { json: async () => ({ identity_id: healthzIdentity, joined_channels: 0 }) };
+      }
+      throw new Error(`unexpected fetch in wiring test: ${url}`);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    controller = new AbortController();
+  });
+
+  afterEach(async () => {
+    controller.abort();
+    vi.unstubAllGlobals();
+    vi.unmock("node:os");
+    if (ORIGINAL_CONN_FILE_ENV === undefined) delete process.env.SECURECOMS_CONNECTION_FILE;
+    else process.env.SECURECOMS_CONNECTION_FILE = ORIGINAL_CONN_FILE_ENV;
+    vi.resetModules();
+  });
+
+  // `homedir()` (node:os) is what openclaw-entry.js uses to locate
+  // ~/.securecoms/connections/<id>.json — mocked to point at the tmp HOME
+  // instead of the real one. (process.env.HOME alone does not reliably move
+  // Node's os.homedir() inside vitest's worker pool — verified empirically.)
+  async function loadPlugin() {
+    vi.resetModules();
+    vi.doMock("node:os", async (importOriginal) => {
+      const actual = await importOriginal<typeof import("node:os")>();
+      return { ...actual, homedir: () => home };
+    });
+    const mod = await import("./openclaw-entry.js");
+    let capturedPlugin: any;
+    mod.default.register({
+      runtime: {},
+      registerChannel: ({ plugin }: { plugin: unknown }) => {
+        capturedPlugin = plugin;
+      },
+    });
+    expect(capturedPlugin).toBeTruthy();
+    return capturedPlugin;
+  }
+
+  it("gate REFUSES on identity mismatch: no WS is ever opened, and a reconnect is scheduled", async () => {
+    const { FakeWebSocket, instances } = makeFakeWebSocket();
+    vi.stubGlobal("WebSocket", FakeWebSocket);
+
+    const plugin = await loadPlugin();
+    const account = plugin.config.resolveAccount({}, "default");
+    expect(account.configured).toBe(true);
+    expect(account.boundIdentity).toBe(BOUND_ID);
+
+    healthzIdentity = OTHER_ID; // daemon reports a different identity than bound/file
+
+    const startPromise = plugin.gateway.startAccount({
+      account,
+      cfg: {},
+      log: (msg: string) => logs.push(String(msg)),
+      abortSignal: controller.signal,
+    });
+
+    await waitFor(() => logs.some((m) => /refusing to attach/i.test(m)));
+
+    expect(instances.length).toBe(0); // WebSocket constructor NEVER called
+
+    // Prove a reconnect was actually scheduled (not just logged): the
+    // backoff timer fires and _probeAndGate re-probes, calling fetch again.
+    await waitFor(() => fetchMock.mock.calls.length >= 2);
+    expect(instances.length).toBe(0); // still zero after the retry
+
+    controller.abort();
+    await startPromise;
+  });
+
+  it("gate PASSES on identity match: the WS opens with the expected URL", async () => {
+    const { FakeWebSocket, instances } = makeFakeWebSocket();
+    vi.stubGlobal("WebSocket", FakeWebSocket);
+
+    const plugin = await loadPlugin();
+    const account = plugin.config.resolveAccount({}, "default");
+    expect(account.configured).toBe(true);
+
+    healthzIdentity = BOUND_ID; // daemon confirms the bound identity
+
+    const startPromise = plugin.gateway.startAccount({
+      account,
+      cfg: {},
+      log: (msg: string) => logs.push(String(msg)),
+      abortSignal: controller.signal,
+    });
+
+    await waitFor(() => instances.length >= 1);
+
+    expect(instances.length).toBe(1);
+    expect(instances[0].url).toBe(`ws://127.0.0.1:${PORT}/v1/ws?token=${encodeURIComponent(TOKEN_VALUE)}`);
+
+    controller.abort();
+    await startPromise;
+  });
+
+  it("reconnect re-gates: after a healthy open, a mismatched identity blocks the next WS open", async () => {
+    const { FakeWebSocket, instances } = makeFakeWebSocket();
+    vi.stubGlobal("WebSocket", FakeWebSocket);
+
+    const plugin = await loadPlugin();
+    const account = plugin.config.resolveAccount({}, "default");
+
+    healthzIdentity = BOUND_ID; // start out matching
+
+    const startPromise = plugin.gateway.startAccount({
+      account,
+      cfg: {},
+      log: (msg: string) => logs.push(String(msg)),
+      abortSignal: controller.signal,
+    });
+
+    await waitFor(() => instances.length >= 1);
+    expect(instances.length).toBe(1);
+    const ws = instances[0];
+    ws._emit("open");
+
+    // Daemon identity flips (e.g. a different daemon now answers on the same
+    // port) and the WS drops — the close handler must re-probe and re-gate,
+    // not just reopen.
+    healthzIdentity = OTHER_ID;
+    const fetchCallsBeforeClose = fetchMock.mock.calls.length;
+    ws._emit("close");
+
+    await waitFor(() => fetchMock.mock.calls.length > fetchCallsBeforeClose);
+    await waitFor(() => logs.some((m) => /refusing to attach/i.test(m)));
+
+    // No second WebSocket was opened — the mismatch blocked the reconnect.
+    expect(instances.length).toBe(1);
+
+    controller.abort();
+    await startPromise;
+  });
+
+  it("connection file ABSENT: holds, never fetches healthz, never opens a WS", async () => {
+    const { FakeWebSocket, instances } = makeFakeWebSocket();
+    vi.stubGlobal("WebSocket", FakeWebSocket);
+
+    // Point SECURECOMS_CONNECTION_FILE at a standalone binding doc (just an
+    // identity_id) rather than the real connections-dir file written in
+    // beforeEach — resolveBoundIdentity only reads .identity_id from it, so
+    // binding can resolve while the ACTUAL
+    // ~/.securecoms/connections/<id>.json (what _resolveConnection reads)
+    // stays absent. This mirrors a daemon that hasn't started yet.
+    const bindingOnlyPath = join(home, "binding-only.json");
+    writeFileSync(bindingOnlyPath, JSON.stringify({ identity_id: BOUND_ID }));
+    process.env.SECURECOMS_CONNECTION_FILE = bindingOnlyPath;
+    // beforeEach wrote a full, valid connection file at this exact path
+    // (connFilePath === the real connections-dir path _resolveConnection
+    // reads) — remove it so the daemon-not-started case is genuinely absent.
+    unlinkSync(connFilePath);
+
+    const plugin = await loadPlugin();
+    const account = plugin.config.resolveAccount({}, "default");
+    expect(account.configured).toBe(true);
+    expect(account.boundIdentity).toBe(BOUND_ID);
+    // No real connection file was written at the connections-dir path, so
+    // resolveAccount could not read bridge_url from it.
+    expect(account.bridgeUrl).toBeUndefined();
+
+    const startPromise = plugin.gateway.startAccount({
+      account,
+      cfg: {},
+      log: (msg: string) => logs.push(String(msg)),
+      abortSignal: controller.signal,
+    });
+
+    await waitFor(() => logs.some((m) => /no connection file at/i.test(m)));
+
+    expect(instances.length).toBe(0); // WebSocket constructor NEVER called
+    expect(fetchMock).not.toHaveBeenCalled(); // _probeAndGate returns before the healthz fetch
+
+    controller.abort();
+    await startPromise;
+  });
+
+  it("connection file PARTIAL (missing bridge_url): holds, never opens a WS", async () => {
+    const { FakeWebSocket, instances } = makeFakeWebSocket();
+    vi.stubGlobal("WebSocket", FakeWebSocket);
+
+    // Overwrite the real connection file (written whole in beforeEach) with a
+    // partial doc: valid JSON, but no bridge_url/token_file. _resolveConnection
+    // must treat this exactly like the absent case (FIX 2) — not-ready
+    // sentinel, no TypeError dereferencing conn.bridge_url.
+    writeFileSync(connFilePath, JSON.stringify({ identity_id: BOUND_ID }));
+
+    const plugin = await loadPlugin();
+    const account = plugin.config.resolveAccount({}, "default");
+    expect(account.configured).toBe(true);
+    expect(account.boundIdentity).toBe(BOUND_ID);
+
+    const startPromise = plugin.gateway.startAccount({
+      account,
+      cfg: {},
+      log: (msg: string) => logs.push(String(msg)),
+      abortSignal: controller.signal,
+    });
+
+    await waitFor(() => logs.some((m) => /no connection file at/i.test(m)));
+
+    expect(instances.length).toBe(0); // WebSocket constructor NEVER called
+    expect(fetchMock).not.toHaveBeenCalled(); // held before the healthz fetch, same as the absent-file branch
+
+    controller.abort();
+    await startPromise;
+  });
+});