@securecoms/agent-bridge 0.5.0 → 0.6.0

package/connectors/openclaw/openclaw-entry.js

@@ -0,0 +1,602 @@
+/**
+ * SecureComs OpenClaw Channel Plugin (daemon-backed connector).
+ *
+ * Registers SecureComs as a first-class OpenClaw messaging channel WITHOUT
+ * embedding any cryptography in OpenClaw. All MLS key agreement and AEAD
+ * encryption happen in a separate local process — the SecureComs Agent Bridge
+ * daemon — which holds the agent credential. This channel talks to that daemon
+ * over an authenticated loopback socket (127.0.0.1, bearer-token-gated): the
+ * daemon locally terminates the end-to-end encryption and hands the cleartext
+ * to the agent on the SAME machine. Cleartext never touches the network or the
+ * server; the wire hop (daemon <-> SecureComs relay) stays MLS end-to-end.
+ *
+ * This is the "universal daemon client" pattern wearing an OpenClaw channel
+ * shim. The daemon is identical for every framework; only this thin file is
+ * OpenClaw-specific. It mirrors the AgentVault plugin's OpenClaw glue
+ * (resolveAgentRoute -> finalizeInboundContext -> dispatchReplyWithBufferedBlockDispatcher)
+ * but replaces the gen2 MLS transport with a daemon loopback client.
+ *
+ * This is the REFERENCE CONNECTOR for the harness connector contract
+ * (docs/superpowers/specs/2026-07-19-harness-connector-contract-design.md §5).
+ * It implements the contract's lifecycle (§4.2) and two-anchor identity gate
+ * (§4.3) via ./gate.js (resolveBoundIdentity / evaluateGate / backoffDelayMs).
+ *
+ * Identity resolution (in order):
+ *   1. bound_identity — a POSITIVE wiring act only, never inferred from which
+ *      connection files exist (spec §4.3 Check 2 / audit C1). Read from
+ *      SECURECOMS_CONNECTION_FILE (daemon-supervised env form) or from
+ *      securecoms.binding.json dropped alongside this file by `agent-bridge
+ *      wire` (spec §6.2). No binding present -> the connector refuses to
+ *      attach and waits (reason: "unwired"); it never guesses.
+ *   2. connection file — ~/.securecoms/connections/<bound_identity>.json,
+ *      written by the daemon on every startup (spec §3). REQUIRED to attach:
+ *      supplies bridge_url (WS) and token_file (a PATH, never a token
+ *      value). Re-read on every connect attempt (§4.2 step 6 -> step 1) so a
+ *      moved port is picked up on reconnect. If the file is absent or
+ *      unparseable (daemon not started yet, or a stale binding) the
+ *      connector HOLDS — same as the unwired/no-token case — and never
+ *      attempts the two-anchor gate or opens a WS. It does NOT fall back to
+ *      openclaw.json as an attach path: doing so would run the gate with an
+ *      undefined fileIdentity and produce a misleading "check 1 failed /
+ *      stale port reuse" log instead of an honest "waiting for the daemon."
+ *
+ * openclaw.json channels.securecoms (bridgeUrl / tokenFile) and the
+ * SECURECOMS_BRIDGE_URL / SECURECOMS_BRIDGE_TOKEN_FILE env vars are optional
+ * bootstrap hints only, never a standalone attach path — the connector does
+ * not read them for attaching; the connection file above is the sole source
+ * of bridge_url/token_file. There is no value-form token fallback anywhere:
+ * a token secret is never accepted as an environment or config VALUE (audit
+ * M2 — that is exactly the leak ADR-0008 E warns about: inherited by
+ * children, visible to `ps eww` and crash dumps). The token is always read
+ * from a file.
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { evaluateGate, resolveBoundIdentity, backoffDelayMs } from "./gate.js";
+
+// Runtime injected by register() — used by the inbound handler.
+let _runtime = null;
+// Active channel instances keyed by accountId.
+const _channels = new Map();
+
+// ---------------------------------------------------------------------------
+// Account / identity / connection-file resolution.
+// ---------------------------------------------------------------------------
+
+function _expand(p) {
+  return p && p.startsWith("~") ? p.replace(/^~/, homedir()) : p;
+}
+
+function _connectionFilePath(identityId) {
+  return join(homedir(), ".securecoms", "connections", `${identityId}.json`);
+}
+
+// Resolve bridge_url/token_file/token for a FIXED bound identity. Called both
+// at initial resolveAccount() and, per spec §4.3, on EVERY connect attempt
+// (never re-derives boundIdentity itself — that is fixed for the connector's
+// life and is not this function's job).
+//
+// The connection file is REQUIRED to attach (see header comment). If it is
+// absent or unparseable this returns `null` — a not-ready sentinel — rather
+// than falling back to openclaw.json/env. Callers MUST treat `null` as "hold,
+// never gate, never open a WS" (see _probeAndGate); running evaluateGate()
+// with an undefined fileIdentity is exactly the bug this sentinel prevents.
+// A missing token (file present, token file unreadable) is also "not ready
+// yet" — returned as `{ ..., token: null }` — since the daemon may simply not
+// have finished writing it.
+function _resolveConnection(boundIdentity, sc) {
+  void sc; // openclaw.json/env are optional bootstrap hints only, not read here (see header comment)
+
+  let conn;
+  try {
+    conn = JSON.parse(readFileSync(_connectionFilePath(boundIdentity), "utf8"));
+  } catch {
+    // Connection file not present/readable yet (daemon not started, or a
+    // stale binding). No attach path without it — not-ready sentinel.
+    return null;
+  }
+
+  if (typeof conn.bridge_url !== "string" || conn.bridge_url === "" ||
+      typeof conn.token_file !== "string" || conn.token_file === "") {
+    // Present but PARTIAL connection file (parses as valid JSON but is
+    // missing/blank bridge_url or token_file — e.g. daemon mid-write, or a
+    // stale/corrupt file). Treat exactly like the absent/unparseable case:
+    // not-ready sentinel, never dereference the missing fields below.
+    return null;
+  }
+
+  const wsUrl = conn.bridge_url;
+  const httpBase = conn.bridge_url.replace(/^ws/, "http").replace(/\/v1\/ws$/, "");
+  const tokenFile = conn.token_file;
+  const fileIdentity = conn.identity_id;
+
+  let token = null;
+  if (tokenFile) {
+    try { token = readFileSync(_expand(tokenFile), "utf8").trim(); } catch { /* leave null -> not ready */ }
+  }
+
+  return { httpBase, wsUrl, token, tokenFile, fileIdentity };
+}
+
+function resolveAccount(cfg, accountId) {
+  const sc = cfg?.channels?.securecoms ?? {};
+  const id = accountId ?? "default";
+
+  // bound_identity: a positive wiring act ONLY (spec §4.3 Check 2 / audit
+  // C1) — never inferred from which connection files happen to exist. The
+  // fourth arg (listConnections) is an intentionally-unused seam; this
+  // connector never auto-discovers.
+  const boundIdentity = resolveBoundIdentity(
+    process.env,
+    (p) => readFileSync(_expand(p), "utf8"),
+    join(import.meta.dirname, "securecoms.binding.json"),
+    () => [],
+  );
+  if (!boundIdentity) {
+    // Unwired: start() must wait, never connect (no directory-census guess).
+    return { accountId: id, configured: false, reason: "unwired" };
+  }
+
+  // May be null (not-ready sentinel) if the connection file doesn't exist
+  // yet — the daemon may not have started. That's fine here: `configured`
+  // only reflects binding, not daemon reachability (see comment below); the
+  // probe/gate/backoff loop is what actually holds until a connection file
+  // shows up (see LoopbackChannel._probeAndGate).
+  const resolved = _resolveConnection(boundIdentity, sc);
+
+  return {
+    accountId: id,
+    boundIdentity,
+    fileIdentity: resolved?.fileIdentity,
+    bridgeUrl: resolved?.httpBase,
+    agentName: sc.agentName ?? "OpenClaw Agent",
+    // Wired == configured. Whether the daemon is reachable RIGHT NOW is a
+    // transient condition handled by the probe/gate/backoff loop below, not
+    // a reason to refuse to even start the channel.
+    configured: true,
+  };
+}
+
+function listAccountIds(cfg) {
+  return cfg?.channels?.securecoms ? ["default"] : [];
+}
+
+// ---------------------------------------------------------------------------
+// Loopback client — plays the transport role (replaces gen2 SecureChannel).
+// Receive: device-wide WS push from the daemon. Send: HTTP POST /v1/send.
+// Dependency-free: Node 22 global WebSocket + global fetch.
+// ---------------------------------------------------------------------------
+
+class LoopbackChannel {
+  constructor({ boundIdentity, sc, onMessage, onStateChange, log }) {
+    // Fixed for the connector's life (spec §4.3): re-derived nowhere below.
+    this.boundIdentity = boundIdentity;
+    this.sc = sc ?? {};
+    this.onMessage = onMessage;
+    this.onStateChange = onStateChange;
+    this.log = log || (() => {});
+    this.state = "idle";
+    this.deviceId = undefined;
+    this.sessionCount = 0;
+    // Populated by _resolve() on each attempt — never captured permanently.
+    this.bridgeUrl = null;
+    this.wsUrl = null;
+    this.token = null;
+    this._ws = null;
+    this._stopped = false;
+    this._attempt = 0;
+    this._ownIdentity = null;
+  }
+
+  _setState(s) {
+    this.state = s;
+    try { this.onStateChange?.(s); } catch { /* ignore */ }
+  }
+
+  // Re-read the connection file + token file on EVERY attempt (spec §4.2
+  // step 6 -> step 1): a moved port (rewritten connection file) must be
+  // picked up on reconnect. boundIdentity is NEVER re-derived here — see
+  // constructor comment and spec §4.3 ("re-deriving the binding on reconnect
+  // would itself be a vulnerability").
+  _resolve() {
+    return _resolveConnection(this.boundIdentity, this.sc);
+  }
+
+  async start() {
+    await this._probeAndGate();
+  }
+
+  // Probe the daemon and run the two-anchor gate BEFORE opening any WS
+  // (spec §4.2 step 2-3, §4.3). Called on startup AND on every reconnect —
+  // the WS close handler below calls _scheduleReconnect(), never _connect()
+  // directly, so a moved/replaced daemon is re-verified on every attempt
+  // (audit C3). On any failure this schedules a backed-off retry and returns
+  // WITHOUT opening a WS; it never throws for conditions that can resolve
+  // themselves (unwired, daemon down, gate mismatch), so a transient hiccup
+  // never permanently kills the channel.
+  async _probeAndGate() {
+    if (this._stopped) return;
+
+    const acct = this._resolve();
+    if (!acct) {
+      // No connection file yet at all (daemon not started, or a stale
+      // binding). The connection file is REQUIRED to attach — hold exactly
+      // like the no-token case below, never attempt the gate with an
+      // undefined fileIdentity, never open a WS.
+      this._setState("idle");
+      this.log(
+        `[securecoms] no connection file at ~/.securecoms/connections/${this.boundIdentity}.json yet; ` +
+          "the daemon authors it on startup — ensure the daemon is upgraded and running",
+      );
+      this._scheduleReconnect();
+      return;
+    }
+    if (!acct.token) {
+      // Connection file exists but the token file isn't readable yet (daemon
+      // mid-startup). Keep waiting; never guess.
+      this._setState("idle");
+      this.log("[SecureComs] not yet resolvable (no connection file / token) — waiting");
+      this._scheduleReconnect();
+      return;
+    }
+    this.bridgeUrl = acct.httpBase;
+    this.wsUrl = acct.wsUrl;
+    this.token = acct.token;
+
+    let h;
+    try {
+      h = await (await fetch(`${this.bridgeUrl}/healthz`)).json();
+    } catch (e) {
+      this._setState("error");
+      this.log(`[SecureComs] daemon unreachable at ${this.bridgeUrl}: ${e?.message ?? e}`);
+      this._scheduleReconnect();
+      return;
+    }
+
+    const gate = evaluateGate({
+      fileIdentity: acct.fileIdentity,
+      healthzIdentity: h.identity_id,
+      boundIdentity: this.boundIdentity,
+    });
+    if (!gate.ok) {
+      this._setState("error");
+      this.log(`[SecureComs] refusing to attach: ${gate.reason}`);
+      this._scheduleReconnect();
+      return;
+    }
+
+    this.deviceId = h.identity_id;
+    this.sessionCount = h.joined_channels ?? 0;
+    this.log(`[SecureComs] daemon ok identity=${h.identity_id} joined=${h.joined_channels}`);
+    // Echo-suppression anchor — set ONLY after the gate passes.
+    this._ownIdentity = this.boundIdentity;
+    // Backoff is reset on a real WS open (see _connect's "open" handler), NOT
+    // here: a daemon that keeps passing the gate but whose WS handshake keeps
+    // failing (e.g. the port accepts TCP but never completes the WS upgrade)
+    // must still back off, not hammer at attempt=0 forever.
+    this._connect();
+  }
+
+  _scheduleReconnect() {
+    if (this._stopped) return;
+    const delay = backoffDelayMs(this._attempt++);
+    setTimeout(() => this._probeAndGate(), delay);
+  }
+
+  _connect() {
+    if (this._stopped) return;
+    // WHATWG WebSocket can't set headers, so the token rides the query string
+    // (the daemon accepts ?token=, loopback-only bind keeps it on this host).
+    const ws = new WebSocket(`${this.wsUrl}?token=${encodeURIComponent(this.token)}`);
+    this._ws = ws;
+
+    ws.addEventListener("open", () => {
+      this._setState("ready");
+      this.log(`[SecureComs] connected to daemon WS ${this.wsUrl}`);
+      // Backoff resets only on a real WS open — a passing gate alone isn't
+      // enough (see comment in _probeAndGate).
+      this._attempt = 0;
+    });
+
+    ws.addEventListener("message", (ev) => {
+      let frame;
+      try {
+        frame = JSON.parse(typeof ev.data === "string" ? ev.data : ev.data.toString());
+      } catch { return; }
+      if (frame.type !== "message") return;
+      // Never feed our own sends back into the agent (no echo loop).
+      if (frame.sender_id && this._ownIdentity && frame.sender_id === this._ownIdentity) {
+        this._ack(frame.message_id);
+        return;
+      }
+      Promise.resolve(
+        this.onMessage?.(frame.text ?? "", {
+          conversationId: frame.channel_id,
+          messageId: frame.message_id,
+          senderId: frame.sender_id,
+          timestamp: frame.ts,
+        }),
+      )
+        .catch((e) => this.log(`[SecureComs] onMessage error: ${e?.message ?? e}`))
+        // at-least-once: ack after the turn completes so a crash mid-handle replays.
+        .finally(() => this._ack(frame.message_id));
+    });
+
+    ws.addEventListener("close", () => {
+      if (this._stopped) return;
+      this._setState("idle");
+      this.log("[SecureComs] daemon WS closed; reconnecting");
+      // Reconnect ALWAYS re-probes and re-gates (spec §4.2 step 6, audit C3)
+      // — never re-opens a WS directly from here.
+      this._scheduleReconnect();
+    });
+
+    ws.addEventListener("error", (e) => {
+      this.log(`[SecureComs] WS error: ${e?.message ?? "unknown"}`);
+    });
+  }
+
+  _ack(messageId) {
+    try { this._ws?.send(JSON.stringify({ type: "ack", message_id: messageId })); } catch { /* ignore */ }
+  }
+
+  /** Send a reply into a specific SecureComs channel via the daemon. */
+  async send(channelId, text) {
+    const r = await fetch(`${this.bridgeUrl}/v1/send`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${this.token}` },
+      body: JSON.stringify({ channel_id: channelId, text }),
+    });
+    if (!r.ok) throw new Error(`send failed: ${r.status} ${(await r.text()).slice(0, 200)}`);
+    return r.json();
+  }
+
+  // Report agent operational status to the daemon (POST /v1/status). Drives the
+  // web "Thinking…" indicator (J1). Best-effort and FIRE-AND-FORGET: callers do
+  // NOT await it, so the status round-trip adds no latency to the turn. On this
+  // deployment an MLS publish (which /v1/status performs) costs ~4.4s, so any
+  // await here would add seconds before the reply — the exact lag we hit. No
+  // AbortSignal timeout either: a 2s cap fired before the ~4.4s publish landed,
+  // so the "working" status never published and the strip never showed. Let the
+  // background fetch run to completion; it swallows its own errors.
+  async reportStatus(channelId, state) {
+    try {
+      await fetch(`${this.bridgeUrl}/v1/status`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${this.token}` },
+        body: JSON.stringify({ channel_id: channelId, state }),
+      });
+    } catch { /* best-effort: never break a turn on a status POST */ }
+  }
+
+  async stop() {
+    this._stopped = true;
+    try { this._ws?.close(); } catch { /* ignore */ }
+    this._setState("idle");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Inbound handler — routes a decrypted message into the OpenClaw agent loop.
+// Mirrors the AgentVault DM glue; replies are delivered back to the SAME
+// SecureComs channel the message arrived on (closure over metadata).
+// ---------------------------------------------------------------------------
+
+async function _handleInbound({ text, metadata, channel, account, cfg }) {
+  const core = _runtime;
+  if (!core) return;
+
+  const conv = metadata.conversationId ?? "default";
+  const senderId = "securecoms:owner";
+
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg,
+    channel: "securecoms",
+    accountId: account.accountId,
+    peer: { kind: "direct", id: senderId },
+  });
+
+  const storePath = core.channel.session.resolveStorePath(cfg?.session?.store, {
+    agentId: route.agentId,
+  });
+
+  const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
+  const previousTimestamp = core.channel.session.readSessionUpdatedAt({
+    storePath,
+    sessionKey: route.sessionKey,
+  });
+
+  const body = core.channel.reply.formatAgentEnvelope({
+    channel: "SecureComs",
+    from: "Owner",
+    timestamp: new Date(metadata.timestamp).getTime(),
+    previousTimestamp,
+    envelope: envelopeOptions,
+    body: text,
+  });
+
+  const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: body,
+    RawBody: text,
+    CommandBody: text,
+    From: senderId,
+    To: `securecoms:agent:${account.accountId}`,
+    SessionKey: route.sessionKey,
+    AccountId: account.accountId,
+    ChatType: "direct",
+    ConversationLabel: "SecureComs",
+    SenderName: "Owner",
+    SenderId: senderId,
+    Provider: "securecoms",
+    Surface: "securecoms",
+    MessageSid: metadata.messageId,
+    Timestamp: new Date(metadata.timestamp).getTime(),
+    OriginatingChannel: "securecoms",
+    OriginatingTo: `securecoms:agent:${account.accountId}`,
+    // The owner is cryptographically authenticated by the SecureComs daemon
+    // (MLS membership + bridge token); authorize command execution.
+    CommandAuthorized: true,
+  });
+
+  await core.channel.session.recordInboundSession({
+    storePath,
+    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+    ctx: ctxPayload,
+    onRecordError: (err) => core.error?.(`[SecureComs] session record failed: ${String(err)}`),
+  });
+
+  // J1 activity indicator: flip the agent to "working" for the duration of the
+  // reply turn (the LLM dispatch, the bulk of "thinking") and back to "idle"
+  // when it finishes OR throws. FIRE-AND-FORGET (not awaited): the status
+  // publish costs ~4.4s on this deployment, so awaiting it added that latency
+  // before the reply and after the turn. Ordering stays correct without the
+  // await because "working" is issued before a multi-second dispatch, giving it
+  // a large head-start over the reply's own publish — the ping→pong race that
+  // motivated awaiting doesn't occur when the reply itself takes seconds to
+  // publish. The web client clears the strip on the later "idle".
+  channel.reportStatus(conv, "working");
+  try {
+    await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+      ctx: ctxPayload,
+      cfg,
+      dispatcherOptions: {
+        deliver: async (payload) => {
+          // Drop chain-of-thought / reasoning blocks; only send finalized text.
+          if (payload?.kind === "thinking" || payload?.kind === "reasoning") return;
+          const t = (payload?.text ?? "").trim();
+          if (t) await channel.send(conv, t);
+        },
+        onError: (err, info) => core.error?.(`[SecureComs] ${info?.kind ?? "reply"} error: ${String(err)}`),
+      },
+      replyOptions: {},
+    });
+  } finally {
+    channel.reportStatus(conv, "idle");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Channel plugin definition
+// ---------------------------------------------------------------------------
+
+const secureComsPlugin = {
+  id: "securecoms",
+  meta: {
+    id: "securecoms",
+    label: "SecureComs",
+    selectionLabel: "SecureComs (E2E Encrypted)",
+    blurb: "End-to-end encrypted messaging via the local SecureComs daemon.",
+    aliases: ["sc", "secure-coms"],
+  },
+  capabilities: {
+    chatTypes: ["direct", "room"],
+  },
+  config: {
+    listAccountIds,
+    resolveAccount,
+  },
+  gateway: {
+    probe: async (ctx) => {
+      const accountId = ctx?.accountId ?? "default";
+      const ch = _channels.get(accountId);
+      if (!ch) return { ok: false, status: "disconnected", error: "Channel not started" };
+      return { ok: ch.state === "ready", status: ch.state, deviceId: ch.deviceId, sessions: ch.sessionCount };
+    },
+    status: (ctx) => {
+      const accountId = ctx?.accountId ?? "default";
+      const ch = _channels.get(accountId);
+      if (!ch) return { connected: false, status: "not_started" };
+      return { connected: ch.state === "ready", status: ch.state, deviceId: ch.deviceId, sessions: ch.sessionCount, encrypted: true };
+    },
+    startAccount: async (ctx) => {
+      const { account, cfg, log, abortSignal } = ctx;
+      const _log = typeof log === "function" ? log : log?.info?.bind(log);
+
+      if (!account.configured) {
+        throw new Error(
+          "SecureComs channel is not wired to an agent identity " +
+            `(${account.reason ?? "unwired"}). Run \`agent-bridge wire --identity <id>\` ` +
+            "(or set SECURECOMS_CONNECTION_FILE) to bind this connector, then restart OpenClaw.",
+        );
+      }
+
+      _log?.(`[SecureComs] starting channel (identity=${account.boundIdentity})`);
+
+      // startAccount MUST stay pending while the channel runs; resolving signals
+      // "stopped" to the gateway (auto-restart). Block until abortSignal fires.
+      await new Promise((resolveP, reject) => {
+        const channel = new LoopbackChannel({
+          boundIdentity: account.boundIdentity,
+          sc: cfg?.channels?.securecoms,
+          log: _log,
+          onMessage: async (text, metadata) => {
+            if (!_runtime) {
+              _log?.("[SecureComs] runtime not ready — dropping inbound message");
+              return;
+            }
+            try {
+              await _handleInbound({ text, metadata, channel, account, cfg });
+            } catch (err) {
+              _log?.(`[SecureComs] inbound dispatch error: ${String(err)}`);
+            }
+          },
+          // Errors are recoverable (probe/gate/backoff retries automatically —
+          // see LoopbackChannel._probeAndGate), so no state here is treated as
+          // a permanent failure. The promise resolves only on abort.
+          onStateChange: (state) => {
+            _log?.(`[SecureComs] state → ${state}`);
+          },
+        });
+
+        _channels.set(account.accountId, channel);
+
+        abortSignal?.addEventListener("abort", async () => {
+          await channel.stop();
+          _channels.delete(account.accountId);
+          resolveP();
+        });
+
+        channel.start().catch(reject);
+      });
+
+      return { stop: async () => {} };
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    targets: [
+      { id: "owner", label: "SecureComs Owner", accountId: "default" },
+      { id: "default", label: "SecureComs Owner (default)", accountId: "default" },
+    ],
+    // Proactive send (cron / cross-channel). Requires an explicit target channel
+    // id in `to`; without channel context we can't guess which SecureComs
+    // conversation to use, so this errors rather than mis-routing.
+    sendText: async ({ text, to, accountId }) => {
+      const ch = _channels.get(accountId ?? "default");
+      if (!ch) return { ok: false, error: "SecureComs channel is not connected" };
+      if (!to) return { ok: false, error: "SecureComs proactive send requires a target channel_id in `to`" };
+      try {
+        await ch.send(to, text);
+        return { ok: true };
+      } catch (err) {
+        return { ok: false, error: String(err) };
+      }
+    },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Plugin entry point
+// ---------------------------------------------------------------------------
+
+export default {
+  id: "securecoms",
+  name: "SecureComs",
+  description: "End-to-end encrypted messaging via the local SecureComs Agent Bridge daemon.",
+  register(api) {
+    _runtime = api.runtime;
+    api.registerChannel({ plugin: secureComsPlugin });
+  },
+};

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

@@ -0,0 +1,30 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+describe("openclaw-entry", () => {
+  it("loads as ESM and exposes the plugin entry without connecting", async () => {
+    const mod = await import("./openclaw-entry.js");
+    expect(mod.default ?? mod).toBeTruthy(); // exports the OpenClaw plugin factory/shape
+  });
+
+  it("exposes register() and the securecoms channel id, without opening a socket", async () => {
+    const mod = await import("./openclaw-entry.js");
+    const plugin = mod.default;
+    expect(plugin.id).toBe("securecoms");
+    expect(typeof plugin.register).toBe("function");
+  });
+
+  it("does not read a token value from the environment (audit M2)", () => {
+    const src = readFileSync(join(import.meta.dirname, "openclaw-entry.js"), "utf8");
+    expect(src).not.toMatch(/process\.env\.SECURECOMS_BRIDGE_TOKEN\b(?!_FILE)/);
+  });
+
+  it("never opens a WebSocket or fetches /healthz merely from being imported", () => {
+    const src = readFileSync(join(import.meta.dirname, "openclaw-entry.js"), "utf8");
+    // Only reachable inside class methods (_connect/_probeAndGate), never at module top level.
+    const topLevel = src.split("class LoopbackChannel")[0];
+    expect(topLevel).not.toMatch(/new WebSocket\(/);
+    expect(topLevel).not.toMatch(/\bfetch\(/);
+  });
+});

package/connectors/openclaw/openclaw.plugin.json

@@ -0,0 +1,25 @@
+{
+  "id": "securecoms",
+  "name": "SecureComs",
+  "description": "End-to-end encrypted messaging bridged from the local SecureComs Agent Bridge daemon. The daemon holds the credential and performs all MLS cryptography; this channel talks to it over an authenticated loopback socket (127.0.0.1, bearer-token-gated) after the daemon locally terminates the E2E encryption, and never touches keys. Cleartext exists only on this machine, never on the network or the server.",
+  "version": "0.1.0",
+  "kind": "channel",
+  "channels": ["securecoms"],
+  "outbound": {
+    "deliveryMode": "direct",
+    "targets": [
+      { "id": "owner", "label": "SecureComs Owner", "accountId": "default" },
+      { "id": "default", "label": "SecureComs Owner (default)", "accountId": "default" }
+    ]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {
+      "bridgeUrl": { "type": "string", "description": "SecureComs daemon loopback base URL (e.g. http://127.0.0.1:7079)" },
+      "tokenFile": { "type": "string", "description": "Path to the daemon bridge-token file" },
+      "agentName": { "type": "string", "description": "Display name for this agent" }
+    }
+  },
+  "uiHints": {}
+}

package/connectors/openclaw/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "securecoms-openclaw",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "SecureComs channel for OpenClaw — bridges the local SecureComs Agent Bridge daemon (E2E MLS) over loopback. No crypto in OpenClaw.",
+  "openclaw": {
+    "extensions": ["./openclaw-entry.js"],
+    "channel": {
+      "id": "securecoms",
+      "label": "SecureComs",
+      "selectionLabel": "SecureComs (E2E Encrypted)",
+      "blurb": "End-to-end encrypted messaging via the local SecureComs daemon.",
+      "aliases": ["sc", "secure-coms"]
+    },
+    "install": { "defaultChoice": "local" }
+  }
+}