@securecoms/agent-bridge 0.4.0 → 0.5.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/dist/bin.js

@@ -2725,6 +2725,15 @@ function parseServerFrame(frame) {
 }
 
 // ../connect-sdk-ts/dist/transport/ws-pings.js
+function base64UrlNoPad(s) {
+  const bytes = new TextEncoder().encode(s);
+  let bin = "";
+  for (const b of bytes)
+    bin += String.fromCharCode(b);
+  const b64 = typeof btoa === "function" ? btoa(bin) : Buffer.from(bytes).toString("base64");
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+var BEARER_SUBPROTOCOL = "securecoms.bearer.v1";
 function openDeliveryPings(o) {
   const base = o.backoffBaseMs ?? 500;
   const cap = o.backoffCapMs ?? 8e3;
@@ -2873,8 +2882,7 @@ function openDeliveryPings(o) {
     }
     if (closed || gen !== connectGen)
       return;
-    const sep = o.url.includes("?") ? "&" : "?";
-    const ws = new o.wsImpl(`${o.url}${sep}token=${encodeURIComponent(token)}`);
+    const ws = new o.wsImpl(o.url, [BEARER_SUBPROTOCOL, base64UrlNoPad(token)]);
     sock = ws;
     ws.onopen = () => {
       push({ reconnected: true });
@@ -2974,8 +2982,8 @@ function openDeliveryPings(o) {
             return Promise.resolve({ value: void 0, done: true });
           if (queue.length)
             return Promise.resolve({ value: queue.shift(), done: false });
-          return new Promise((resolve2) => {
-            waiter = resolve2;
+          return new Promise((resolve3) => {
+            waiter = resolve3;
           });
         }
       };
@@ -5693,7 +5701,7 @@ var BridgeAgent = class _BridgeAgent {
     let got = this.takeBuffered(channelId);
     if (got.length || waitSeconds <= 0) return got;
     const cap = Math.min(waitSeconds, 50) * 1e3;
-    await new Promise((resolve2) => {
+    await new Promise((resolve3) => {
       let fired = false;
       let timer;
       const wake = () => {
@@ -5702,7 +5710,7 @@ var BridgeAgent = class _BridgeAgent {
         clearTimeout(timer);
         const i = this.waiters.indexOf(wake);
         if (i >= 0) this.waiters.splice(i, 1);
-        resolve2();
+        resolve3();
       };
       timer = setTimeout(wake, cap);
       this.waiters.push(wake);
@@ -5961,7 +5969,7 @@ function jsonError(res, code, detail) {
   json(res, httpStatus(code), errorBody(code, detail));
 }
 function readBody(req, cap) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     let size = 0;
     let done = false;
     const chunks = [];
@@ -5981,7 +5989,7 @@ function readBody(req, cap) {
     req.on("end", () => {
       if (!done) {
         done = true;
-        resolve2(Buffer.concat(chunks).toString("utf8"));
+        resolve3(Buffer.concat(chunks).toString("utf8"));
       }
     });
     req.on("error", (e) => {
@@ -6395,8 +6403,8 @@ async function handleInbound(sock, agent, data, inflight) {
 }
 
 // src/bin.ts
-import { readFileSync as readFileSync6, mkdirSync, writeFileSync as writeFileSync2, rmSync, existsSync as existsSync2, realpathSync } from "node:fs";
-import { join as join8, dirname as dirname5 } from "node:path";
+import { readFileSync as readFileSync6, mkdirSync, writeFileSync as writeFileSync2, rmSync, existsSync as existsSync2, realpathSync, readdirSync } from "node:fs";
+import { join as join9, dirname as dirname5, isAbsolute as isAbsolute2, resolve as resolve2 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir as homedir2, userInfo } from "node:os";
 import { spawnSync } from "node:child_process";
@@ -6531,6 +6539,161 @@ function uninstallService(input, deps) {
   throw new ServiceUnsupportedError(`Service uninstall isn't supported on ${deps.platform} yet.`);
 }
 
+// src/service/install-prep.ts
+import { join as join8 } from "node:path";
+function assertReadableCredential(absPath, deps) {
+  let raw;
+  try {
+    raw = deps.readFile(absPath);
+  } catch {
+    throw new Error(`install: credential file not found or unreadable: ${absPath}`);
+  }
+  let json2;
+  try {
+    json2 = JSON.parse(raw);
+  } catch {
+    throw new Error(`install: credential file is not valid JSON: ${absPath}`);
+  }
+  for (const k of REQUIRED) {
+    if (typeof json2[k] !== "string" || !json2[k]) {
+      throw new Error(`install: credential file missing required field '${k}': ${absPath}`);
+    }
+  }
+  const issuedAt = typeof json2.issued_at === "string" && json2.issued_at ? json2.issued_at : null;
+  return { deviceId: json2.device_id, identityId: json2.identity_id, issuedAt };
+}
+function durableDir(home, slug) {
+  return join8(home, `securecoms-agent-${slug}`);
+}
+function durableCredentialPath(home, slug) {
+  return join8(durableDir(home, slug), `${slug}.json`);
+}
+function takeCustody(args2, deps) {
+  const dir = durableDir(args2.home, args2.slug);
+  const dest = durableCredentialPath(args2.home, args2.slug);
+  try {
+    if (deps.fileExists(dest) && deps.realpath(args2.sourceAbsPath) === deps.realpath(dest)) return dest;
+  } catch {
+  }
+  if (deps.fileExists(dest)) {
+    try {
+      const existing = JSON.parse(deps.readFile(dest));
+      if (existing.device_id && existing.device_id !== args2.parsed.deviceId) {
+        throw new Error(
+          `install: ${dir} already belongs to a different agent (device ${existing.device_id}). Pass a distinct --label to install this agent in its own directory.`
+        );
+      }
+    } catch (e) {
+      if (e instanceof Error && e.message.startsWith("install:")) throw e;
+    }
+  }
+  deps.mkdirp(dir, 448);
+  deps.writeFileMode(dest, deps.readFile(args2.sourceAbsPath), 384);
+  return dest;
+}
+var PORT_MIN = 7077;
+var PORT_MAX = 7276;
+function parseClaimedPorts(fileContents) {
+  const claimed = /* @__PURE__ */ new Set();
+  const re = /--port(?:<\/string>\s*<string>|\s+)(\d+)/g;
+  for (const text of fileContents) {
+    let m;
+    while ((m = re.exec(text)) !== null) claimed.add(Number(m[1]));
+  }
+  return claimed;
+}
+function readSiblingDefs(dir, prefix, deps) {
+  let names;
+  try {
+    names = deps.listDir(dir);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const n of names) {
+    if (!n.startsWith(prefix)) continue;
+    try {
+      out.push(deps.readFile(join8(dir, n)));
+    } catch {
+    }
+  }
+  return out;
+}
+function selectPort(args2, deps) {
+  const defs = [
+    ...readSiblingDefs(args2.launchAgentsDir, "com.securecoms.bridge.", deps),
+    ...readSiblingDefs(args2.systemdDir, "securecoms-bridge-", deps)
+  ];
+  const claimed = parseClaimedPorts(defs);
+  for (let port = PORT_MIN; port <= PORT_MAX; port++) {
+    if (claimed.has(port)) continue;
+    if (!deps.probeBindFree(port)) continue;
+    return port;
+  }
+  throw new Error(`install: no free port in ${PORT_MIN}-${PORT_MAX} \u2014 stop an unused bridge or pass --port`);
+}
+async function verifyDaemonUp(args2, deps) {
+  const attempts = args2.attempts ?? 20;
+  const delayMs = args2.delayMs ?? 250;
+  for (let i = 0; i < attempts; i++) {
+    if (deps.probeConnect(args2.port)) return true;
+    try {
+      if (deps.readFile(args2.logPath).includes("[bridge] listening on")) return true;
+    } catch {
+    }
+    await deps.sleep(delayMs);
+  }
+  return false;
+}
+function harnessSnippet(args2) {
+  const label = args2.harness === "hermes" ? "Hermes" : args2.harness === "openclaw" ? "OpenClaw" : "your harness";
+  return [
+    `# ${label}: point the agent at this bridge`,
+    `SECURECOMS_BRIDGE_URL=ws://127.0.0.1:${args2.port}/v1/ws`,
+    `SECURECOMS_BRIDGE_TOKEN="$(cat ${args2.tokenFilePath})"`
+  ].join("\n");
+}
+async function orchestrateInstall(ctx) {
+  const parsed = assertReadableCredential(ctx.credentialAbsPath, ctx.prepDeps);
+  const stemForSlug = ctx.label ?? ctx.credentialAbsPath.replace(/^.*[\\/]/, "").replace(/\.[^.]*$/, "");
+  const slug = slugify(stemForSlug);
+  const durablePath = takeCustody(
+    { home: ctx.home, slug, sourceAbsPath: ctx.credentialAbsPath, parsed },
+    ctx.prepDeps
+  );
+  const port = ctx.explicitPort ?? selectPort(
+    { launchAgentsDir: ctx.launchAgentsDir ?? `${ctx.home}/Library/LaunchAgents`, systemdDir: ctx.systemdDir ?? `${ctx.home}/.config/systemd/user` },
+    ctx.prepDeps
+  );
+  const input = ctx.buildServiceInput(durablePath, port, slug);
+  const result = ctx.installService(input);
+  const up = await verifyDaemonUp(
+    { port, logPath: result.logHint, attempts: ctx.verifyAttempts, delayMs: ctx.verifyDelayMs },
+    ctx.prepDeps
+  );
+  if (!up) {
+    throw new Error(
+      `install: the daemon did not come up \u2014 check its log: ${result.logHint}`
+    );
+  }
+  const apiKey = JSON.parse(ctx.prepDeps.readFile(durablePath)).api_key;
+  const lines = [
+    `Installed service ${result.label}`,
+    `  device:  ${parsed.deviceId}`,
+    parsed.issuedAt ? `  issued:  ${parsed.issuedAt}` : `  issued:  (unknown \u2014 older credential)`,
+    `  api key: ${tokenFingerprint(apiKey)}`,
+    `  port:    ${port}`,
+    `  token:   ${result.tokenHint}`,
+    `  (Re-running install is the only way to update a live credential \u2014 replacing the download alone does nothing.)`
+  ];
+  let harnessSnippetShown = false;
+  if (ctx.harness && ctx.harness !== "none") {
+    lines.push("", harnessSnippet({ slug, port, tokenFilePath: result.tokenHint, harness: ctx.harness }));
+    harnessSnippetShown = true;
+  }
+  return { echo: lines.join("\n") + "\n", harnessSnippetShown };
+}
+
 // src/bin.ts
 function nodeMajorOk(version) {
   return Number(version.split(".")[0]) >= 24;
@@ -6571,11 +6734,47 @@ function realResolveDeps() {
     fileExists: (p) => existsSync2(p)
   };
 }
-function runServiceVerb(verb) {
+function realPrepDeps() {
+  return {
+    readFile: (p) => readFileSync6(p, "utf8"),
+    writeFileMode: (p, data, mode) => writeFileSync2(p, data, { mode }),
+    mkdirp: (p, mode) => {
+      mkdirSync(p, { recursive: true, mode: mode ?? 493 });
+    },
+    fileExists: (p) => existsSync2(p),
+    realpath: (p) => realpathSync(p),
+    listDir: (p) => {
+      try {
+        return readdirSync(p);
+      } catch {
+        return [];
+      }
+    },
+    // Synchronous spawn-free-loop probes: node's net API is async-only, so each
+    // probe is a tiny `node -e` child that binds/connects and exits 0/1.
+    probeBindFree: (port) => {
+      const r = spawnSync(process.execPath, [
+        "-e",
+        `const s=require('net').createServer();s.once('error',()=>process.exit(1));s.listen(${port},'127.0.0.1',()=>{s.close(()=>process.exit(0))});`
+      ]);
+      return r.status === 0;
+    },
+    probeConnect: (port) => {
+      const r = spawnSync(process.execPath, [
+        "-e",
+        `const s=require('net').connect(${port},'127.0.0.1');s.once('connect',()=>{s.destroy();process.exit(0)});s.once('error',()=>process.exit(1));setTimeout(()=>process.exit(1),500);`
+      ]);
+      return r.status === 0;
+    },
+    // No unref: an unref'd timer would let the process exit mid-verification.
+    sleep: (ms) => new Promise((res) => setTimeout(res, ms))
+  };
+}
+async function runServiceVerb(verb) {
   const credentialPath = argOrEnv("--credential", "SECURECOMS_CREDENTIAL");
   const label = argOrEnv("--label", "SECURECOMS_LABEL");
-  if (!credentialPath && !label) {
-    process.stderr.write(`usage: agent-bridge ${verb} --credential <path> [--label <name>] [--store <path>] [--port N]
+  if (verb === "install" ? !credentialPath : !credentialPath && !label) {
+    process.stderr.write(`usage: agent-bridge ${verb} --credential <path> [--label <name>] [--store <path>] [--port N] [--harness openclaw|hermes|custom]
 `);
     process.exit(2);
   }
@@ -6585,25 +6784,43 @@ function runServiceVerb(verb) {
     const meta = loadPackageMeta(import.meta.url);
     binScript = resolveStableBinScript({ binScript, packageName: meta.name }, realResolveDeps());
   }
-  const input = {
-    credentialPath: credentialPath ?? "",
-    storePath: argOrEnv("--store", "SECURECOMS_STORE"),
-    port: portStr ? Number(portStr) : void 0,
-    label,
-    execPath: process.execPath,
-    binScript,
-    home: homedir2(),
-    uid: userInfo().uid
-  };
   try {
     if (verb === "install") {
-      const r = installService(input, realServiceDeps());
-      process.stdout.write(`Installed service ${r.label}
-  file:  ${r.filePath}
-  logs:  ${r.logHint}
-  token: ${r.tokenHint} (the local BRIDGE_TOKEN)
-`);
+      const credAbs = isAbsolute2(credentialPath) ? credentialPath : resolve2(credentialPath);
+      const r = await orchestrateInstall({
+        credentialAbsPath: credAbs,
+        label,
+        explicitPort: portStr ? Number(portStr) : void 0,
+        harness: argOrEnv("--harness", "SECURECOMS_HARNESS"),
+        home: homedir2(),
+        prepDeps: realPrepDeps(),
+        // O-1: the real installService is 2-arg; partially apply the deps so
+        // orchestrateInstall only ever sees the 1-arg seam.
+        installService: (input) => installService(input, realServiceDeps()),
+        buildServiceInput: (durableCredentialPath2, port, _slug) => ({
+          credentialPath: durableCredentialPath2,
+          storePath: argOrEnv("--store", "SECURECOMS_STORE"),
+          // O-2: not dropped
+          port,
+          label,
+          execPath: process.execPath,
+          binScript,
+          home: homedir2(),
+          uid: userInfo().uid
+        })
+      });
+      process.stdout.write(r.echo);
     } else {
+      const input = {
+        credentialPath: credentialPath ?? "",
+        storePath: argOrEnv("--store", "SECURECOMS_STORE"),
+        port: portStr ? Number(portStr) : void 0,
+        label,
+        execPath: process.execPath,
+        binScript,
+        home: homedir2(),
+        uid: userInfo().uid
+      };
       const r = uninstallService(input, realServiceDeps());
       process.stdout.write(r.removed ? `Removed service (${r.filePath})
 ` : `No service installed for this agent
@@ -6625,7 +6842,7 @@ async function main() {
   }
   const verb = parseVerb(process.argv);
   if (verb) {
-    runServiceVerb(verb);
+    await runServiceVerb(verb);
     return;
   }
   const credentialPath = argOrEnv("--credential", "SECURECOMS_CREDENTIAL");
@@ -6644,7 +6861,7 @@ async function main() {
 `);
     process.exit(1);
   }
-  const tokenFile = daemon.tokenFile ?? join8(dirname5(credentialPath), "bridge-token");
+  const tokenFile = daemon.tokenFile ?? join9(dirname5(credentialPath), "bridge-token");
   const token = resolveToken({ tokenFile, token: daemon.token });
   const agent = new BridgeAgent(cfg);
   await agent.start();

package/dist/config.d.ts

@@ -24,6 +24,7 @@ export interface BridgeConfig {
     /** For memoryProvider="openclaw": the OpenClaw agent dir slug, e.g. "cortina" (→ <base_dir>/agents/<agent>/). */
     memoryAgent?: string;
 }
+export declare const REQUIRED: readonly ["api_key", "identity_id", "device_id", "signing_private_key", "enclave_id", "api_base"];
 export declare function loadConfig(opts: {
     credentialPath: string;
     storePath?: string;

package/dist/index.js

@@ -2630,6 +2630,15 @@ function parseServerFrame(frame) {
 }
 
 // ../connect-sdk-ts/dist/transport/ws-pings.js
+function base64UrlNoPad(s) {
+  const bytes = new TextEncoder().encode(s);
+  let bin = "";
+  for (const b of bytes)
+    bin += String.fromCharCode(b);
+  const b64 = typeof btoa === "function" ? btoa(bin) : Buffer.from(bytes).toString("base64");
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+var BEARER_SUBPROTOCOL = "securecoms.bearer.v1";
 function openDeliveryPings(o) {
   const base = o.backoffBaseMs ?? 500;
   const cap = o.backoffCapMs ?? 8e3;
@@ -2778,8 +2787,7 @@ function openDeliveryPings(o) {
     }
     if (closed || gen !== connectGen)
       return;
-    const sep = o.url.includes("?") ? "&" : "?";
-    const ws = new o.wsImpl(`${o.url}${sep}token=${encodeURIComponent(token)}`);
+    const ws = new o.wsImpl(o.url, [BEARER_SUBPROTOCOL, base64UrlNoPad(token)]);
     sock = ws;
     ws.onopen = () => {
       push({ reconnected: true });

package/dist/service/config.d.ts

@@ -20,4 +20,5 @@ export interface ServiceConfig {
     unitPath: string;
     logPath: string;
 }
+export declare function slugify(s: string): string;
 export declare function deriveServiceConfig(input: ServiceInput): ServiceConfig;

package/dist/service/install-prep.d.ts

@@ -0,0 +1,68 @@
+import { type ServiceInput } from "./config.js";
+export interface PrepDeps {
+    readFile: (p: string) => string;
+    writeFileMode: (p: string, data: string, mode: number) => void;
+    mkdirp: (p: string, mode?: number) => void;
+    fileExists: (p: string) => boolean;
+    realpath: (p: string) => string;
+    listDir: (p: string) => string[];
+    probeBindFree: (port: number) => boolean;
+    probeConnect: (port: number) => boolean;
+    sleep: (ms: number) => Promise<void>;
+}
+export interface ParsedCredential {
+    deviceId: string;
+    identityId: string;
+    issuedAt: string | null;
+}
+export declare function assertReadableCredential(absPath: string, deps: PrepDeps): ParsedCredential;
+export declare function durableDir(home: string, slug: string): string;
+export declare function durableCredentialPath(home: string, slug: string): string;
+export declare function takeCustody(args: {
+    home: string;
+    slug: string;
+    sourceAbsPath: string;
+    parsed: ParsedCredential;
+}, deps: PrepDeps): string;
+export declare const PORT_MIN = 7077;
+export declare const PORT_MAX = 7276;
+export declare function parseClaimedPorts(fileContents: string[]): Set<number>;
+export declare function selectPort(args: {
+    launchAgentsDir: string;
+    systemdDir: string;
+}, deps: PrepDeps): number;
+export declare function verifyDaemonUp(args: {
+    port: number;
+    logPath: string;
+    attempts?: number;
+    delayMs?: number;
+}, deps: PrepDeps): Promise<boolean>;
+export declare function harnessSnippet(args: {
+    slug: string;
+    port: number;
+    tokenFilePath: string;
+    harness: string;
+}): string;
+export interface OrchestrateInstallCtx {
+    credentialAbsPath: string;
+    label?: string;
+    explicitPort?: number;
+    harness?: string;
+    home: string;
+    launchAgentsDir?: string;
+    systemdDir?: string;
+    prepDeps: PrepDeps;
+    installService: (input: ServiceInput) => {
+        label: string;
+        filePath: string;
+        logHint: string;
+        tokenHint: string;
+    };
+    buildServiceInput: (durableCredentialPath: string, port: number, slug: string) => ServiceInput;
+    verifyAttempts?: number;
+    verifyDelayMs?: number;
+}
+export declare function orchestrateInstall(ctx: OrchestrateInstallCtx): Promise<{
+    echo: string;
+    harnessSnippetShown: boolean;
+}>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@securecoms/agent-bridge",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",