@securecoms/agent-bridge 0.21.0 → 0.24.0

package/connectors/openclaw/openclaw-entry.js

@@ -61,6 +61,74 @@ let _runtime = null;
 // Active channel instances keyed by accountId.
 const _channels = new Map();
 
+// ---------------------------------------------------------------------------
+// Inbound delivery contract (P0 containment Task 8).
+//
+// The daemon delivers at-least-once: a `message` frame stays in-flight until
+// we `ack` it, and is re-buffered for the next consumer when the socket drops.
+// So:
+//   - a message_id we already handled is acked again and NEVER re-dispatched
+//     (bounded `seen` set, same shape as the native runtime's data plane);
+//   - on first sight we ask the daemon's content-free reply-receipt ledger
+//     (GET /v1/reply-receipt) whether a reply was already published for it —
+//     a replacement host must not re-run the model/tools for an answered turn;
+//   - a failed turn is NOT acked. We close the socket so the daemon re-buffers
+//     the frame for a clean retry (leaving it in-flight on a live socket would
+//     strand it until the next reconnect);
+//   - a runtime that is not registered yet is the same "retry later" case,
+//     never a silent drop;
+//   - a message that keeps failing is given up on after MAX_INBOUND_ATTEMPTS
+//     handler failures (acked + logged), so one poison message cannot re-run
+//     tools forever. Runtime-not-ready and a failed receipt lookup do NOT
+//     count toward that cap: neither ran the turn, and giving up on them
+//     would be a silent drop of a message nobody processed.
+// ---------------------------------------------------------------------------
+
+export const MAX_INBOUND_ATTEMPTS = 3;
+const SEEN_MAX = 5000;
+
+/** Thrown by the inbound handler when register() has not injected a runtime. */
+export class RuntimeNotReadyError extends Error {
+  constructor() {
+    super("OpenClaw runtime not registered yet");
+    this.name = "RuntimeNotReadyError";
+  }
+}
+
+/** Thrown when the reply-receipt lookup cannot answer (never a handler failure). */
+class ReceiptLookupError extends Error {
+  constructor(detail) {
+    super(`reply receipt lookup failed: ${detail}`);
+    this.name = "ReceiptLookupError";
+  }
+}
+
+/**
+ * The agent's OWNER, as attested by the daemon's authorization block. This is
+ * the exact predicate the bridge uses for owner-scoped OpenClaw memory
+ * (BridgeAgent.mayReadOpenClawMemoryForTurn): audience "owner_dm" with an
+ * "active" sender. The block is derived by the daemon from server-authenticated
+ * roster data, never from message plaintext. Anything else — including a
+ * missing block from an older daemon, an unknown version, or the owner
+ * speaking in a group room (the daemon does not classify that as owner) —
+ * is NOT the owner. Fail closed.
+ */
+export function isOwnerAuthorization(authorization) {
+  return (
+    authorization !== null &&
+    typeof authorization === "object" &&
+    authorization.version === 1 &&
+    authorization.audience === "owner_dm" &&
+    authorization.sender_membership === "active"
+  );
+}
+
+/** "direct" only for a DM the daemon classified as one; everything else is a group. */
+export function chatTypeFor(authorization) {
+  const audience = authorization && typeof authorization === "object" ? authorization.audience : undefined;
+  return audience === "owner_dm" || audience === "other_human_dm" ? "direct" : "group";
+}
+
 // ---------------------------------------------------------------------------
 // Account / identity / connection-file resolution.
 // ---------------------------------------------------------------------------
@@ -188,6 +256,15 @@ export class LoopbackChannel {
     this._stopped = false;
     this._attempt = 0;
     this._ownIdentity = null;
+    // Inbound dedup/retry state (see "Inbound delivery contract" above).
+    this._seen = new Set();
+    this._inFlight = new Set();
+    this._failures = new Map();
+    this._blockSeq = new Map(); // SEC-06 #18: inReplyTo -> { seq, pending } (see _blockKey)
+    // Consecutive failed turns. While > 0, a WS open does NOT reset the
+    // reconnect backoff, so a failing turn is retried with growing delay
+    // instead of a ~250 ms redelivery loop.
+    this._failStreak = 0;
   }
 
   _setState(s) {
@@ -226,10 +303,7 @@ export class LoopbackChannel {
       // 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.log("[SecureComs] no connection file at configured location; waiting for daemon");
       this._scheduleReconnect();
       return;
     }
@@ -248,9 +322,9 @@ export class LoopbackChannel {
     let h;
     try {
       h = await (await fetch(`${this.bridgeUrl}/healthz`)).json();
-    } catch (e) {
+    } catch {
       this._setState("error");
-      this.log(`[SecureComs] daemon unreachable at ${this.bridgeUrl}: ${e?.message ?? e}`);
+      this.log("[SecureComs] daemon unreachable");
       this._scheduleReconnect();
       return;
     }
@@ -262,14 +336,14 @@ export class LoopbackChannel {
     });
     if (!gate.ok) {
       this._setState("error");
-      this.log(`[SecureComs] refusing to attach: ${gate.reason}`);
+      this.log("[SecureComs] refusing to attach: identity gate failed");
       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}`);
+    this.log("[SecureComs] daemon identity gate passed");
     // 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
@@ -294,10 +368,11 @@ export class LoopbackChannel {
 
     ws.addEventListener("open", () => {
       this._setState("ready");
-      this.log(`[SecureComs] connected to daemon WS ${this.wsUrl}`);
+      this.log("[SecureComs] connected to daemon WebSocket");
       // Backoff resets only on a real WS open — a passing gate alone isn't
-      // enough (see comment in _probeAndGate).
-      this._attempt = 0;
+      // enough (see comment in _probeAndGate) — and not while turns are
+      // failing: a close we forced for redelivery must still back off.
+      if (this._failStreak === 0) this._attempt = 0;
     });
 
     ws.addEventListener("message", (ev) => {
@@ -306,22 +381,7 @@ export class LoopbackChannel {
         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));
+      void this._onInboundFrame(frame);
     });
 
     ws.addEventListener("close", () => {
@@ -333,17 +393,155 @@ export class LoopbackChannel {
       this._scheduleReconnect();
     });
 
-    ws.addEventListener("error", (e) => {
-      this.log(`[SecureComs] WS error: ${e?.message ?? "unknown"}`);
+    ws.addEventListener("error", () => {
+      this.log("[SecureComs] WebSocket error");
     });
   }
 
+  // Acks go to the CURRENT socket, not the one the frame arrived on: if that
+  // socket was replaced mid-turn, the daemon re-buffered the frame onto the
+  // new one, and only an ack there clears it.
   _ack(messageId) {
     try { this._ws?.send(JSON.stringify({ type: "ack", message_id: messageId })); } catch { /* ignore */ }
   }
 
+  _remember(messageId) {
+    if (this._seen.size >= SEEN_MAX) {
+      const oldest = this._seen.values().next();
+      if (!oldest.done) this._seen.delete(oldest.value);
+    }
+    this._seen.add(messageId);
+  }
+
+  // Close the current socket so the daemon re-buffers every un-acked frame
+  // for redelivery. The close handler re-probes and re-gates as usual.
+  _requestRedelivery() {
+    try { this._ws?.close(); } catch { /* already closing */ }
+  }
+
+  async _hasReplyReceipt(messageId) {
+    let r;
+    try {
+      r = await fetch(`${this.bridgeUrl}/v1/reply-receipt?in_reply_to=${encodeURIComponent(messageId)}`, {
+        headers: { authorization: `Bearer ${this.token}` },
+      });
+    } catch {
+      throw new ReceiptLookupError("daemon unreachable");
+    }
+    if (!r.ok) throw new ReceiptLookupError(`HTTP ${r.status}`);
+    let body;
+    try {
+      body = await r.json();
+    } catch {
+      // A 200 with a non-JSON/unparseable body is a daemon-side lookup
+      // failure, not a handler failure: it must not count toward
+      // MAX_INBOUND_ATTEMPTS (that would eventually ack-and-drop a message
+      // that was never actually processed).
+      throw new ReceiptLookupError("invalid JSON body");
+    }
+    return body?.found === true;
+  }
+
+  /**
+   * Handle one inbound `message` frame under the at-least-once contract (see
+   * "Inbound delivery contract" at the top of this file). Never throws.
+   */
+  async _onInboundFrame(frame) {
+    const messageId = frame.message_id;
+    if (typeof messageId !== "string" || messageId === "") {
+      this.log("[SecureComs] inbound frame without message_id; ignoring");
+      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._remember(messageId);
+      this._ack(messageId);
+      return;
+    }
+    if (this._seen.has(messageId)) {
+      // Already handled (or reconciled via a reply receipt): ack the
+      // redelivered copy, never run the turn twice.
+      this._ack(messageId);
+      return;
+    }
+    if (this._inFlight.has(messageId)) {
+      // Redelivered onto a replacement socket while the original turn is
+      // still running. The original's completion acks on the current socket.
+      return;
+    }
+
+    this._inFlight.add(messageId);
+    try {
+      if (await this._hasReplyReceipt(messageId)) {
+        this._remember(messageId);
+        this._ack(messageId);
+        return;
+      }
+      await this.onMessage?.(typeof frame.text === "string" ? frame.text : "", {
+        conversationId: frame.channel_id,
+        messageId,
+        senderId: frame.sender_id,
+        senderName: frame.sender_name,
+        authorization: frame.authorization,
+        timestamp: frame.ts,
+      });
+      this._failures.delete(messageId);
+      this._failStreak = 0;
+      this._remember(messageId);
+      this._ack(messageId);
+    } catch (err) {
+      this._failStreak++;
+      if (err instanceof RuntimeNotReadyError || err instanceof ReceiptLookupError) {
+        this.log("[SecureComs] inbound message not processed yet (runtime not ready or reply-receipt lookup failed); leaving unacked for redelivery");
+        this._requestRedelivery();
+        return;
+      }
+      const attempts = (this._failures.get(messageId) ?? 0) + 1;
+      if (attempts >= MAX_INBOUND_ATTEMPTS) {
+        this._failures.delete(messageId);
+        this.log("[SecureComs] inbound turn failed MAX_INBOUND_ATTEMPTS times; giving up and acking the message");
+        this._remember(messageId);
+        this._ack(messageId);
+        return;
+      }
+      if (this._failures.size >= SEEN_MAX) {
+        const oldest = this._failures.keys().next();
+        if (!oldest.done) this._failures.delete(oldest.value);
+      }
+      this._failures.set(messageId, attempts);
+      this.log("[SecureComs] inbound turn failed; leaving unacked for redelivery");
+      this._requestRedelivery();
+    } finally {
+      this._inFlight.delete(messageId);
+    }
+  }
+
+  /**
+   * SEC-06 #18: a stable idempotency_key per reply block. The daemon matches a
+   * keyless retry only against the most recent part, so two identical blocks
+   * would collapse into one message. The key is `<inReplyTo>:<n>`: n advances
+   * after a confirmed send, and also when a new block arrives after an
+   * unconfirmed one (that block is abandoned). A retry of the unconfirmed block
+   * (same text) reuses its key, so the daemon never publishes it twice.
+   */
+  _blockKey(inReplyTo, text) {
+    let st = this._blockSeq.get(inReplyTo);
+    if (!st) {
+      st = { seq: 0, pending: undefined };
+      if (this._blockSeq.size >= SEEN_MAX) {
+        const oldest = this._blockSeq.keys().next();
+        if (!oldest.done) this._blockSeq.delete(oldest.value);
+      }
+      this._blockSeq.set(inReplyTo, st);
+    }
+    if (st.pending !== undefined && st.pending !== text) st.seq++;
+    st.pending = text;
+    return { key: `${inReplyTo}:${st.seq}`, st };
+  }
+
   /** Send a reply into a specific SecureComs channel via the daemon. */
   async send(channelId, text, inReplyTo) {
+    const block = inReplyTo ? this._blockKey(inReplyTo, text) : null;
     const r = await fetch(`${this.bridgeUrl}/v1/send`, {
       method: "POST",
       headers: { "content-type": "application/json", authorization: `Bearer ${this.token}` },
@@ -351,9 +549,14 @@ export class LoopbackChannel {
         channel_id: channelId,
         text,
         ...(inReplyTo ? { in_reply_to: inReplyTo } : {}),
+        ...(block ? { idempotency_key: block.key } : {}),
       }),
     });
     if (!r.ok) throw new Error(`send failed: ${r.status} ${(await r.text()).slice(0, 200)}`);
+    if (block) {
+      block.st.seq++;
+      block.st.pending = undefined;
+    }
     return r.json();
   }
 
@@ -390,17 +593,33 @@ export class LoopbackChannel {
 
 async function _handleInbound({ text, metadata, channel, account, cfg }) {
   const core = _runtime;
-  if (!core) return;
-
-  const conv = metadata.conversationId ?? "default";
-  const senderId = "securecoms:owner";
+  if (!core) throw new RuntimeNotReadyError();
 
+  const conv = metadata.conversationId;
+  if (typeof conv !== "string" || conv === "") {
+    throw new Error("inbound frame has no channel_id");
+  }
+  // The REAL sender, as the daemon decrypted and attributed it. Never a
+  // hard-coded owner: who sent a message and whether they may run commands
+  // are separate facts, and only the daemon's authorization block speaks to
+  // the second.
+  const senderId = typeof metadata.senderId === "string" && metadata.senderId !== "" ? metadata.senderId : "unknown";
+  const senderName = typeof metadata.senderName === "string" && metadata.senderName !== "" ? metadata.senderName : senderId;
+  const chatType = chatTypeFor(metadata.authorization);
+  const commandAuthorized = isOwnerAuthorization(metadata.authorization);
+
+  // Route by the CHANNEL, so each SecureComs room/DM is its own conversation.
   const route = core.channel.routing.resolveAgentRoute({
     cfg,
     channel: "securecoms",
     accountId: account.accountId,
-    peer: { kind: "direct", id: senderId },
+    peer: { kind: chatType, id: conv },
   });
+  // Session isolation is enforced HERE, not delegated to OpenClaw's dmScope:
+  // under the default dmScope every direct peer collapses into the agent's
+  // main session, which would merge two different humans' DMs (and the
+  // owner's) into one history. One session per SecureComs channel, always.
+  const sessionKey = `agent:${route.agentId}:securecoms:${chatType}:${conv}`;
 
   const storePath = core.channel.session.resolveStorePath(cfg?.session?.store, {
     agentId: route.agentId,
@@ -409,12 +628,12 @@ async function _handleInbound({ text, metadata, channel, account, cfg }) {
   const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
   const previousTimestamp = core.channel.session.readSessionUpdatedAt({
     storePath,
-    sessionKey: route.sessionKey,
+    sessionKey,
   });
 
   const body = core.channel.reply.formatAgentEnvelope({
     channel: "SecureComs",
-    from: "Owner",
+    from: senderName,
     timestamp: new Date(metadata.timestamp).getTime(),
     previousTimestamp,
     envelope: envelopeOptions,
@@ -425,13 +644,13 @@ async function _handleInbound({ text, metadata, channel, account, cfg }) {
     Body: body,
     RawBody: text,
     CommandBody: text,
-    From: senderId,
+    From: `securecoms:${senderId}`,
     To: `securecoms:agent:${account.accountId}`,
-    SessionKey: route.sessionKey,
+    SessionKey: sessionKey,
     AccountId: account.accountId,
-    ChatType: "direct",
+    ChatType: chatType,
     ConversationLabel: "SecureComs",
-    SenderName: "Owner",
+    SenderName: senderName,
     SenderId: senderId,
     Provider: "securecoms",
     Surface: "securecoms",
@@ -439,14 +658,15 @@ async function _handleInbound({ text, metadata, channel, account, cfg }) {
     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,
+    // Command execution is the OWNER's alone, as attested by the daemon's
+    // authorization block (isOwnerAuthorization). MLS membership proves a
+    // sender is in the room, not that they own this agent.
+    CommandAuthorized: commandAuthorized,
   });
 
   await core.channel.session.recordInboundSession({
     storePath,
-    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+    sessionKey,
     ctx: ctxPayload,
     onRecordError: (err) => core.error?.(`[SecureComs] session record failed: ${String(err)}`),
   });
@@ -495,7 +715,7 @@ const secureComsPlugin = {
     aliases: ["sc", "secure-coms"],
   },
   capabilities: {
-    chatTypes: ["direct", "room"],
+    chatTypes: ["direct", "group", "room"],
   },
   config: {
     listAccountIds,
@@ -535,15 +755,18 @@ const secureComsPlugin = {
           boundIdentity: account.boundIdentity,
           sc: cfg?.channels?.securecoms,
           log: _log,
+          // Throws on failure (including runtime-not-ready) so the channel
+          // leaves the frame unacked for redelivery — never a silent drop.
           onMessage: async (text, metadata) => {
             if (!_runtime) {
-              _log?.("[SecureComs] runtime not ready — dropping inbound message");
-              return;
+              _log?.("[SecureComs] runtime not ready — leaving inbound message unacked for redelivery");
+              throw new RuntimeNotReadyError();
             }
             try {
               await _handleInbound({ text, metadata, channel, account, cfg });
             } catch (err) {
               _log?.(`[SecureComs] inbound dispatch error: ${String(err)}`);
+              throw err;
             }
           },
           // Errors are recoverable (probe/gate/backoff retries automatically —

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

@@ -47,6 +47,32 @@ describe("openclaw-entry", () => {
       channel_id: "channel-1",
       text: "reply text",
       in_reply_to: "inbound-1",
+      idempotency_key: "inbound-1:0",
     }]);
   });
+
+  it("SEC-06 #18: every reply block gets a stable idempotency_key (identical blocks stay two messages; a retry reuses its key)", async () => {
+    const keys: unknown[] = [];
+    let ok = true;
+    vi.stubGlobal("fetch", async (_url: string, init: RequestInit) => {
+      keys.push((JSON.parse(String(init.body)) as Record<string, unknown>).idempotency_key);
+      return ok
+        ? { ok: true, json: async () => ({ message_id: "m" }) }
+        : { ok: false, status: 500, text: async () => "boom" };
+    });
+    const { LoopbackChannel } = await import("./openclaw-entry.js");
+    const channel = new LoopbackChannel({ boundIdentity: "agent-1" });
+    channel.bridgeUrl = "http://127.0.0.1:7090";
+    channel.token = "token";
+    await channel.send("c", "ok", "in-1");
+    await channel.send("c", "ok", "in-1"); // a second, identical block
+    ok = false;
+    await expect(channel.send("c", "third", "in-1")).rejects.toThrow();
+    await expect(channel.send("c", "third", "in-1")).rejects.toThrow(); // retry of the same block
+    ok = true;
+    await channel.send("c", "fourth", "in-1"); // the unconfirmed block is abandoned
+    await channel.send("c", "other", "in-2");
+    await channel.send("c", "no correlation");
+    expect(keys).toEqual(["in-1:0", "in-1:1", "in-1:2", "in-1:2", "in-1:3", "in-2:0", undefined]);
+  });
 });

package/dist/bin.d.ts

@@ -3,13 +3,9 @@ import { type ResolveNodeDeps } from "./service/resolve-node.js";
 import { type Harness } from "./service/wire.js";
 export declare function nodeMajorOk(version: string): boolean;
 /**
- * P0b (daemon-stability): a redacted fingerprint of a bearer token for logs —
- * a short prefix plus the total length, never the raw value. Lets an
- * operator eyeball "yes, a token was loaded, and it looks like the one I
- * expect" without the full secret ever hitting stderr (see the tokenFile
- * comment at the top of this file). Mirrors the install-path token hint's
- * philosophy of pointing at the token FILE rather than printing the secret
- * (see service/install.ts's tokenHint, which returns the bridge-token path).
+ * A redacted bearer-token hint for explicit foreground install output: a short
+ * prefix plus the total length, never the raw value. Long-running service
+ * diagnostics do not call this helper or expose even the hint.
  */
 export declare function tokenFingerprint(token: string): string;
 export declare function parseVerb(argv: string[]): "install" | "uninstall" | "status" | "wire" | "unwire" | null;