clawmatrix 0.1.23 → 0.2.0

package/src/config.ts

@@ -79,31 +79,102 @@ const ProxyModelGroupSchema = z.object({
 
 const KnowledgeConfigSchema = z.object({
   enabled: z.boolean().default(false),
+  paths: z.array(z.string()).default([]),
   debounce: z.number().default(5000),
   maxFileSize: z.number().default(512 * 1024),
 }).optional();
 
+const SentinelConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  /** Override port for sentinel listener. Default: inherits gateway's listenPort for automatic takeover. */
+  listenPort: z.number().optional(),
+  listenHost: z.string().optional(),
+}).optional();
+
 const WebConfigSchema = z.object({
   enabled: z.boolean().default(false),
   token: z.string().min(8, "web token must be at least 8 characters"),
 }).optional();
 
+const AcpAgentInfoSchema = z.object({
+  id: z.string(),
+  description: z.string().default(""),
+});
+
+const NotifyTargetSchema = z.object({
+  channel: z.string(),
+  to: z.string(),
+  accountId: z.string().optional(),
+  threadId: z.union([z.string(), z.number()]).optional(),
+});
+
+const PeerApprovalConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  /** "notify" = auto-approve + send notification; "required" = block until approved. */
+  mode: z.enum(["notify", "required"]).default("notify"),
+  /** Approval timeout in ms (required mode only). Default: 20 minutes. */
+  timeout: z.number().default(1_200_000),
+  /** Pre-approved nodeIds (always allowed without approval/notification). */
+  allowList: z.array(z.string()).default([]),
+  /** Path to persist approved peers (relative to workspace .clawmatrix/). */
+  persistPath: z.string().default("approved-peers.json"),
+  /** Notification targets for approval events (e.g. telegram, feishu). */
+  notifyTargets: z.array(NotifyTargetSchema).default([]),
+}).optional();
+
+const TerminalConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  /** Default shell (auto-detected from $SHELL if not set). */
+  shell: z.string().optional(),
+  /** Idle session timeout in ms (default: 1800000 = 30 min). */
+  sessionTTL: z.number().default(1_800_000),
+  /** Max concurrent terminal sessions (default: 3). */
+  maxSessions: z.number().default(3),
+  /** Allowed nodeIds that can open terminals (empty = all authenticated peers). */
+  allowFrom: z.array(z.string()).default([]),
+}).optional();
+
+const AcpConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  /** ACP agents available on this node. Advertised to peers via capabilities. */
+  agents: z.array(AcpAgentInfoSchema).default([]),
+  /** Override spawn commands per agent name. Default: agent name is used as the binary. */
+  commands: z.record(z.string(), z.array(z.string())).default({}),
+  /** Per-turn timeout in ms (default: 600000 = 10 min). */
+  timeout: z.number().default(600_000),
+  /** Idle persistent session TTL in ms (default: 1800000 = 30 min). */
+  sessionTTL: z.number().default(1_800_000),
+  /** Max concurrent ACP sessions (default: 5). 0 = unlimited. */
+  maxSessions: z.number().default(5),
+}).optional();
+
 const RawClawMatrixConfigSchema = z.object({
   nodeId: z.string(),
   secret: z.string().min(16, "secret must be at least 16 characters"),
   listen: z.boolean().default(false),
   listenHost: z.string().default("0.0.0.0"),
-  listenPort: z.number().default(19000),
+  listenPort: z.number().default(0),
   peers: z.array(PeerConfigSchema).default([]),
   agents: z.array(AgentInfoSchema).default([]),
   models: z.array(ModelInfoSchema).default([]),
   proxyModels: z.array(ProxyModelGroupSchema).default([]),
   tags: z.array(z.string()).default([]),
-  proxyPort: z.number().default(19001),
+  proxyPort: z.number().default(0),
   toolProxy: ToolProxyConfigSchema.optional(),
   handoffTimeout: z.number().default(600_000),
+  modelTimeout: z.number().default(120_000),
+  toolTimeout: z.number().default(30_000),
+  sentinel: SentinelConfigSchema,
   web: WebConfigSchema,
   knowledge: KnowledgeConfigSchema,
+  terminal: TerminalConfigSchema,
+  acp: AcpConfigSchema,
+  peerApproval: z.union([
+    z.boolean(),           // true = required mode, false = disabled
+    PeerApprovalConfigSchema,
+  ]).default(true),
+  e2ee: z.boolean().default(true),
+  compression: z.boolean().default(false),
 });
 
 /** Flat proxy model after group expansion (used internally). */
@@ -121,8 +192,18 @@ export interface ProxyModel {
   compat?: z.infer<typeof ModelCompatSchema>;
 }
 
-export type ClawMatrixConfig = Omit<z.infer<typeof RawClawMatrixConfigSchema>, "proxyModels"> & {
+export interface PeerApprovalConfig {
+  enabled: boolean;
+  mode: "notify" | "required";
+  timeout: number;
+  allowList: string[];
+  persistPath: string;
+  notifyTargets: Array<{ channel: string; to: string; accountId?: string; threadId?: string | number }>;
+}
+
+export type ClawMatrixConfig = Omit<z.infer<typeof RawClawMatrixConfigSchema>, "proxyModels" | "peerApproval"> & {
   proxyModels: ProxyModel[];
+  peerApproval: PeerApprovalConfig;
 };
 
 export { RawClawMatrixConfigSchema as ClawMatrixConfigSchema };
@@ -159,5 +240,37 @@ export function parseConfig(raw: unknown): ClawMatrixConfig {
     }
   }
 
-  return { ...parsed, proxyModels };
+  // Normalize peerApproval: boolean → object
+  let peerApproval: PeerApprovalConfig;
+  const rawApproval = parsed.peerApproval;
+  if (typeof rawApproval === "boolean") {
+    peerApproval = {
+      enabled: rawApproval,
+      mode: "required",
+      timeout: 1_200_000,
+      allowList: [],
+      persistPath: "approved-peers.json",
+      notifyTargets: [],
+    };
+  } else if (rawApproval) {
+    peerApproval = {
+      enabled: rawApproval.enabled,
+      mode: rawApproval.mode,
+      timeout: rawApproval.timeout,
+      allowList: rawApproval.allowList,
+      persistPath: rawApproval.persistPath,
+      notifyTargets: rawApproval.notifyTargets,
+    };
+  } else {
+    peerApproval = {
+      enabled: false,
+      mode: "notify",
+      timeout: 1_200_000,
+      allowList: [],
+      persistPath: "approved-peers.json",
+      notifyTargets: [],
+    };
+  }
+
+  return { ...parsed, proxyModels, peerApproval };
 }

package/src/connection.ts

@@ -12,6 +12,18 @@ import type {
   ToolProxyInfo,
 } from "./types.ts";
 import { generateNonce, computeHmac, verifyHmac } from "./auth.ts";
+import {
+  generateX25519KeyPair,
+  deriveSessionKey,
+  derivePerPeerSecret,
+  encryptBinary,
+  decryptBinary,
+  isBinaryEncrypted,
+  publicKeyToBase64,
+  base64ToPublicKey,
+  type KeyPair,
+} from "./crypto.ts";
+import { debug } from "./debug.ts";
 
 const HEARTBEAT_BASE = 12_000;
 const HEARTBEAT_JITTER = 6_000;
@@ -35,6 +47,15 @@ export interface ConnectionEvents {
   error: [error: Error];
 }
 
+export interface ConnectionE2eeOptions {
+  e2ee?: boolean;
+  compression?: boolean;
+  /** Defer sending auth_ok for inbound connections until completeAuth() is called. */
+  deferAuthOk?: boolean;
+  /** Persistent identity key pair (TOFU). If provided, used instead of ephemeral keys. */
+  identityKeyPair?: import("./crypto.ts").KeyPair;
+}
+
 export class Connection extends EventEmitter<ConnectionEvents> {
   readonly role: ConnectionRole;
   private transport: WsTransport;
@@ -45,8 +66,15 @@ export class Connection extends EventEmitter<ConnectionEvents> {
   remoteNodeId: string | null = null;
   remoteCapabilities: NodeCapabilities | null = null;
   authenticated = false;
+  /** Whether this connection has an active E2EE session. */
+  get encrypted(): boolean { return this.sessionKey !== null; }
+  /** Remote peer's persistent public key (available after E2EE handshake). */
+  get remoteIdentityKey(): string | null {
+    return this._remotePublicKey ? publicKeyToBase64(this._remotePublicKey) : null;
+  }
 
   private heartbeatTimer: ReturnType<typeof setTimeout> | null = null;
+  private dummyTimer: ReturnType<typeof setTimeout> | null = null;
   private authTimer: ReturnType<typeof setTimeout> | null = null;
   private missedPongs = 0;
   private pendingNonce: string | null = null;
@@ -55,12 +83,25 @@ export class Connection extends EventEmitter<ConnectionEvents> {
   /** Exponential moving average of heartbeat RTT in milliseconds. */
   latencyMs = 0;
 
+  // ── Deferred auth ──────────────────────────────────────────────
+  private deferAuthOk: boolean;
+  /** Whether auth_ok has been sent (for deferred mode). */
+  private authOkSent = false;
+
+  // ── E2EE state ──────────────────────────────────────────────────
+  private e2eeEnabled: boolean;
+  private compressionEnabled: boolean;
+  private localKeyPair: KeyPair | null = null;
+  private _remotePublicKey: Buffer | null = null;
+  private sessionKey: Buffer | null = null;
+
   constructor(
     transport: WsTransport,
     role: ConnectionRole,
     nodeId: string,
     secret: string,
     localCapabilities: NodeCapabilities,
+    e2eeOptions?: ConnectionE2eeOptions,
   ) {
     super();
     this.transport = transport;
@@ -68,6 +109,15 @@ export class Connection extends EventEmitter<ConnectionEvents> {
     this.nodeId = nodeId;
     this.secret = secret;
     this.localCapabilities = localCapabilities;
+    this.deferAuthOk = e2eeOptions?.deferAuthOk ?? false;
+    this.e2eeEnabled = e2eeOptions?.e2ee ?? true;
+    this.compressionEnabled = e2eeOptions?.compression ?? false;
+
+    if (this.e2eeEnabled) {
+      // Use persistent identity key pair if provided (TOFU model),
+      // otherwise generate an ephemeral key pair per connection.
+      this.localKeyPair = e2eeOptions?.identityKeyPair ?? generateX25519KeyPair();
+    }
 
     // Both inbound and outbound get an auth timeout to prevent hanging connections
     this.authTimer = setTimeout(() => {
@@ -106,165 +156,295 @@ export class Connection extends EventEmitter<ConnectionEvents> {
   private async sendAuthChallenge() {
     const nonce = generateNonce();
     this.pendingNonce = nonce;
-    this.sendRaw({
-      type: "auth_challenge",
-      from: this.nodeId,
-      timestamp: Date.now(),
-      payload: { nonce },
-    });
+    // Minimal obfuscated format: no type/from fields, just short keys
+    // n=nonce, k=publicKey (if E2EE), i=nodeId (for per-peer secret derivation)
+    const msg: Record<string, string> = { n: nonce, i: this.nodeId };
+    if (this.localKeyPair) {
+      msg.k = publicKeyToBase64(this.localKeyPair.publicKey);
+    }
+    this.sendRaw(msg);
   }
 
   // ── Send helpers ───────────────────────────────────────────────
+  /** Send a frame, encrypting the entire frame if a session key is established. */
   send(frame: ClusterFrame | AnyClusterFrame) {
     if (this.closed) return;
-    this.sendRaw(frame);
+    if (this.sessionKey) {
+      // Full frame encryption → binary base64 envelope (no JSON structure on wire)
+      this.sendRaw(encryptBinary(this.sessionKey, JSON.stringify(frame), this.compressionEnabled));
+    } else {
+      this.sendRaw(frame);
+    }
   }
 
+  /** Send raw data. Strings sent as-is (for binary envelopes); objects JSON-encoded. */
   private sendRaw(data: unknown) {
     if (this.transport.readyState === WebSocket.OPEN) {
-      this.transport.send(JSON.stringify(data));
+      this.transport.send(typeof data === "string" ? data : JSON.stringify(data));
     }
   }
 
   // ── Message dispatch ───────────────────────────────────────────
   private async onRawMessage(data: unknown) {
-    let frame: AnyClusterFrame;
-    try {
-      frame = JSON.parse(typeof data === "string" ? data : String(data));
-    } catch {
-      return;
+    const str = typeof data === "string" ? data : String(data);
+    if (!str.length) return;
+
+    let frame: AnyClusterFrame | undefined;
+
+    // Binary encrypted envelope (base64, not JSON)
+    if (this.sessionKey && isBinaryEncrypted(str)) {
+      try {
+        frame = JSON.parse(decryptBinary(this.sessionKey, str));
+      } catch (err) {
+        debug("e2ee", `Frame decryption failed: ${err}`);
+        return;
+      }
+      // Discard dummy traffic
+      if ((frame as any).type === "_d") return;
+    }
+
+    // JSON: handshake messages or plaintext frames
+    if (!frame) {
+      try {
+        frame = JSON.parse(str);
+      } catch {
+        return;
+      }
     }
 
     if (!this.authenticated) {
-      await this.handleAuthMessage(frame);
+      await this.handleAuthMessage(frame!);
       return;
     }
 
-    if (frame.type === "ping") {
-      this.sendRaw({
+    // Approval pending: HMAC passed but auth_ok not yet sent.
+    // Only allow ping/pong — drop all business frames.
+    if (!this.authOkSent) {
+      if (frame!.type !== "ping" && frame!.type !== "pong") return;
+    }
+
+    if (frame!.type === "ping") {
+      this.send({
         type: "pong",
         from: this.nodeId,
         timestamp: Date.now(),
-      });
+      } as AnyClusterFrame);
       return;
     }
-    if (frame.type === "pong") {
+    if (frame!.type === "pong") {
       this.missedPongs = 0;
       if (this.lastPingSentAt > 0) {
         const rtt = Date.now() - this.lastPingSentAt;
-        // Exponential moving average (α = 0.3)
         this.latencyMs = this.latencyMs === 0 ? rtt : Math.round(this.latencyMs * 0.7 + rtt * 0.3);
         this.emit("latency", this.latencyMs);
       }
       return;
     }
 
-    this.emit("message", frame);
+    this.emit("message", frame!);
   }
 
-  private async handleAuthMessage(frame: AnyClusterFrame) {
+  private async handleAuthMessage(frame: any) {
     if (this.role === "inbound") {
+      // ── Obfuscated E2EE key exchange: {"k":"<pubkey>"} ──
+      if (frame.k && !frame.n && !frame.type) {
+        if (this.localKeyPair) {
+          this._remotePublicKey = base64ToPublicKey(frame.k);
+          const nonceSalt = this.pendingNonce ? Buffer.from(this.pendingNonce) : undefined;
+          this.sessionKey = deriveSessionKey(this.localKeyPair, this._remotePublicKey, nonceSalt);
+          debug("e2ee", "Session key derived from key exchange");
+        }
+        return; // Wait for encrypted auth_verify
+      }
+
+      // ── Encrypted auth_verify (decrypted from binary envelope in onRawMessage) ──
+      if (frame.type === "auth_verify") {
+        const { nodeId, sig, agents, models, tags, deviceInfo, toolProxy, acpAgents } = frame.payload as {
+          nodeId: string; sig: string;
+          agents?: AgentInfo[]; models?: ModelInfo[]; tags?: string[];
+          deviceInfo?: DeviceInfo; toolProxy?: ToolProxyInfo;
+          acpAgents?: import("./types.ts").AcpAgentInfo[];
+        };
+        if (!this.pendingNonce) return;
+
+        const peerSecret = derivePerPeerSecret(this.secret, this.nodeId, nodeId);
+        const valid = await verifyHmac(this.pendingNonce, peerSecret, sig);
+        this.pendingNonce = null;
+
+        if (!valid) {
+          // Minimal error response — no identifiable type strings
+          this.sendRaw({ e: "sig" });
+          this.close(4001, "auth failed");
+          return;
+        }
+
+        this.remoteNodeId = nodeId;
+        this.remoteCapabilities = {
+          nodeId, agents: agents ?? [], models: models ?? [],
+          tags: tags ?? [], deviceInfo, toolProxy, acpAgents,
+        };
+        this.authenticated = true;
+        this.clearAuthTimer();
+
+        if (this.deferAuthOk) {
+          // Don't send auth_ok yet — wait for completeAuth() after approval
+          this.emit("authenticated", this.remoteCapabilities);
+          return;
+        }
+
+        this.sendAuthOkAndStart();
+        this.emit("authenticated", this.remoteCapabilities);
+        return;
+      }
+
+      // ── Legacy plaintext auth (E2EE disabled) ──
       if (frame.type !== "auth") return;
       const { nodeId, sig, agents, models, tags, deviceInfo, toolProxy } = frame.payload as {
-        nodeId: string;
-        sig: string;
-        agents?: AgentInfo[];
-        models?: ModelInfo[];
-        tags?: string[];
-        deviceInfo?: DeviceInfo;
-        toolProxy?: ToolProxyInfo;
+        nodeId: string; sig: string;
+        agents?: AgentInfo[]; models?: ModelInfo[]; tags?: string[];
+        deviceInfo?: DeviceInfo; toolProxy?: ToolProxyInfo;
       };
       if (!this.pendingNonce) return;
 
-      const valid = await verifyHmac(this.pendingNonce, this.secret, sig);
+      const peerSecret = derivePerPeerSecret(this.secret, this.nodeId, nodeId);
+      const valid = await verifyHmac(this.pendingNonce, peerSecret, sig);
       this.pendingNonce = null;
 
       if (!valid) {
-        this.sendRaw({
-          type: "auth_fail",
-          from: this.nodeId,
-          timestamp: Date.now(),
-          payload: { reason: "Invalid signature" },
-        } satisfies AuthFail);
+        this.sendRaw({ e: "sig" });
         this.close(4001, "auth failed");
         return;
       }
 
       this.remoteNodeId = nodeId;
       this.remoteCapabilities = {
-        nodeId,
-        agents: agents ?? [],
-        models: models ?? [],
-        tags: tags ?? [],
-        deviceInfo,
-        toolProxy,
+        nodeId, agents: agents ?? [], models: models ?? [],
+        tags: tags ?? [], deviceInfo, toolProxy,
       };
       this.authenticated = true;
       this.clearAuthTimer();
 
-      this.sendRaw({
-        type: "auth_ok",
-        from: this.nodeId,
-        timestamp: Date.now(),
-        payload: {
-          nodeId: this.nodeId,
-          agents: this.localCapabilities.agents,
-          models: this.localCapabilities.models,
-          tags: this.localCapabilities.tags,
-          deviceInfo: this.localCapabilities.deviceInfo,
-          toolProxy: this.localCapabilities.toolProxy,
-        },
-      } as AuthOk);
-
-      this.startHeartbeat();
-      this.emit("authenticated", this.remoteCapabilities);
+      if (this.deferAuthOk) {
+        this.emit("authenticated", this.remoteCapabilities);
+      } else {
+        this.sendAuthOkAndStart();
+        this.emit("authenticated", this.remoteCapabilities);
+      }
     } else {
-      if (frame.type === "auth_challenge") {
-        const { nonce } = (frame as AuthChallenge).payload;
-        const sig = await computeHmac(nonce, this.secret);
-        this.sendRaw({
-          type: "auth",
-          from: this.nodeId,
-          timestamp: Date.now(),
-          payload: {
-            nodeId: this.nodeId,
-            sig,
-            agents: this.localCapabilities.agents,
-            models: this.localCapabilities.models,
-            tags: this.localCapabilities.tags,
-            deviceInfo: this.localCapabilities.deviceInfo,
-            toolProxy: this.localCapabilities.toolProxy,
-          },
-        });
+      // ── Outbound (client) ──
+
+      // Obfuscated challenge: {"n":"<nonce>","k":"<pubkey>","i":"<nodeId>"}
+      if (frame.n && !frame.type) {
+        const nonce: string = frame.n;
+        const publicKey: string | undefined = frame.k;
+        const serverNodeId: string = frame.i;
+
+        if (publicKey && this.localKeyPair) {
+          // E2EE: derive session key, send key exchange + encrypted auth_verify
+          this._remotePublicKey = base64ToPublicKey(publicKey);
+          this.sessionKey = deriveSessionKey(this.localKeyPair, this._remotePublicKey, Buffer.from(nonce));
+          debug("e2ee", "Session key derived from challenge");
+
+          // Key exchange: minimal {"k":"<pubkey>"} (plaintext, server needs it)
+          this.sendRaw({ k: publicKeyToBase64(this.localKeyPair.publicKey) });
+
+          // auth_verify: binary encrypted via send()
+          const sig = await computeHmac(nonce, derivePerPeerSecret(this.secret, this.nodeId, serverNodeId));
+          this.send({
+            type: "auth_verify", from: this.nodeId, timestamp: Date.now(),
+            payload: {
+              nodeId: this.nodeId, sig,
+              agents: this.localCapabilities.agents,
+              models: this.localCapabilities.models,
+              tags: this.localCapabilities.tags,
+              deviceInfo: this.localCapabilities.deviceInfo,
+              toolProxy: this.localCapabilities.toolProxy,
+            },
+          } as AnyClusterFrame);
+        } else {
+          // Legacy plaintext (no E2EE)
+          const sig = await computeHmac(nonce, derivePerPeerSecret(this.secret, this.nodeId, serverNodeId));
+          this.sendRaw({
+            type: "auth", from: this.nodeId, timestamp: Date.now(),
+            payload: {
+              nodeId: this.nodeId, sig,
+              agents: this.localCapabilities.agents,
+              models: this.localCapabilities.models,
+              tags: this.localCapabilities.tags,
+              deviceInfo: this.localCapabilities.deviceInfo,
+              toolProxy: this.localCapabilities.toolProxy,
+            },
+          });
+        }
         return;
       }
 
+      // auth_ok (decrypted from binary envelope, or plaintext legacy)
       if (frame.type === "auth_ok") {
         const ok = frame as AuthOk;
         this.remoteNodeId = ok.payload.nodeId;
         this.remoteCapabilities = {
-          nodeId: ok.payload.nodeId,
-          agents: ok.payload.agents,
-          models: ok.payload.models,
-          tags: ok.payload.tags,
-          deviceInfo: ok.payload.deviceInfo,
-          toolProxy: ok.payload.toolProxy,
+          nodeId: ok.payload.nodeId, agents: ok.payload.agents,
+          models: ok.payload.models, tags: ok.payload.tags,
+          deviceInfo: ok.payload.deviceInfo, toolProxy: ok.payload.toolProxy,
+          acpAgents: ok.payload.acpAgents,
         };
         this.authenticated = true;
+        this.authOkSent = true; // outbound: auth complete, allow business frames
         this.clearAuthTimer();
+
         this.startHeartbeat();
+        this.startDummyTraffic();
         this.emit("authenticated", this.remoteCapabilities);
         return;
       }
 
-      if (frame.type === "auth_fail") {
-        const fail = frame as AuthFail;
-        this.emit("error", new Error(`Auth failed: ${fail.payload.reason}`));
+      // Auth failure: {"e":"sig"} or legacy {"type":"auth_fail",...}
+      if (frame.e || frame.type === "auth_fail") {
+        const reason = frame.e || (frame.payload?.reason ?? "unknown");
+        this.emit("error", new Error(`Auth failed: ${reason}`));
         this.close(4001, "auth failed");
       }
     }
   }
 
+  /** Send auth_ok with capabilities and start heartbeat/dummy traffic. */
+  private sendAuthOkAndStart() {
+    if (this.authOkSent) return;
+    this.authOkSent = true;
+    const authOk = {
+      type: "auth_ok", from: this.nodeId, timestamp: Date.now(),
+      payload: {
+        nodeId: this.nodeId,
+        agents: this.localCapabilities.agents,
+        models: this.localCapabilities.models,
+        tags: this.localCapabilities.tags,
+        deviceInfo: this.localCapabilities.deviceInfo,
+        toolProxy: this.localCapabilities.toolProxy,
+        acpAgents: this.localCapabilities.acpAgents,
+      },
+    } as AuthOk;
+
+    if (this.sessionKey) {
+      this.send(authOk);
+    } else {
+      this.sendRaw(authOk);
+    }
+
+    this.startHeartbeat();
+    this.startDummyTraffic();
+  }
+
+  /**
+   * Complete deferred auth — send auth_ok and start heartbeat.
+   * Call this after peer approval succeeds. Only applies to inbound connections
+   * with deferAuthOk enabled. No-op otherwise.
+   */
+  completeAuth() {
+    if (!this.authenticated || this.closed || this.role !== "inbound") return;
+    this.sendAuthOkAndStart();
+  }
+
   private clearAuthTimer() {
     if (this.authTimer) {
       clearTimeout(this.authTimer);
@@ -286,11 +466,26 @@ export class Connection extends EventEmitter<ConnectionEvents> {
           return;
         }
         this.lastPingSentAt = Date.now();
-        this.sendRaw({
+        this.send({
           type: "ping",
           from: this.nodeId,
           timestamp: this.lastPingSentAt,
-        });
+        } as AnyClusterFrame);
+        scheduleNext();
+      }, interval);
+    };
+    scheduleNext();
+  }
+
+  // ── Dummy traffic (breaks heartbeat timing pattern) ────────────
+  private startDummyTraffic() {
+    if (!this.sessionKey) return;
+    const scheduleNext = () => {
+      // Random interval 2-8 seconds — interleaves with heartbeat to obscure pattern
+      const interval = 2_000 + Math.random() * 6_000;
+      this.dummyTimer = setTimeout(() => {
+        if (this.closed || !this.sessionKey) return;
+        this.send({ type: "_d", from: "", timestamp: 0 } as unknown as AnyClusterFrame);
         scheduleNext();
       }, interval);
     };
@@ -306,6 +501,14 @@ export class Connection extends EventEmitter<ConnectionEvents> {
       clearTimeout(this.heartbeatTimer);
       this.heartbeatTimer = null;
     }
+    if (this.dummyTimer) {
+      clearTimeout(this.dummyTimer);
+      this.dummyTimer = null;
+    }
+    // Clear session key material (don't null localKeyPair if it's a
+    // persistent identity owned by the caller)
+    this.sessionKey = null;
+    this._remotePublicKey = null;
     try {
       this.transport.close(code, reason);
     } catch {