@zbruceli/openclaw-dchat 0.1.0

package/src/seen-tracker.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import { SeenTracker } from "./seen-tracker.js";
+
+describe("SeenTracker", () => {
+  it("tracks seen message IDs", () => {
+    const tracker = new SeenTracker();
+    expect(tracker.hasSeen("msg-1")).toBe(false);
+    tracker.markSeen("msg-1");
+    expect(tracker.hasSeen("msg-1")).toBe(true);
+  });
+
+  it("checkAndMark returns false for new, true for seen", () => {
+    const tracker = new SeenTracker();
+    expect(tracker.checkAndMark("msg-1")).toBe(false);
+    expect(tracker.checkAndMark("msg-1")).toBe(true);
+    expect(tracker.checkAndMark("msg-2")).toBe(false);
+  });
+
+  it("tracks size correctly", () => {
+    const tracker = new SeenTracker();
+    expect(tracker.size).toBe(0);
+    tracker.markSeen("a");
+    tracker.markSeen("b");
+    tracker.markSeen("c");
+    expect(tracker.size).toBe(3);
+  });
+
+  it("evicts oldest entries when over capacity", () => {
+    const tracker = new SeenTracker(3);
+    tracker.markSeen("a");
+    tracker.markSeen("b");
+    tracker.markSeen("c");
+    expect(tracker.size).toBe(3);
+
+    // Adding a 4th should evict "a" (oldest)
+    tracker.markSeen("d");
+    expect(tracker.size).toBe(3);
+    expect(tracker.hasSeen("a")).toBe(false);
+    expect(tracker.hasSeen("b")).toBe(true);
+    expect(tracker.hasSeen("c")).toBe(true);
+    expect(tracker.hasSeen("d")).toBe(true);
+  });
+
+  it("re-marking refreshes position (LRU behavior)", () => {
+    const tracker = new SeenTracker(3);
+    tracker.markSeen("a");
+    tracker.markSeen("b");
+    tracker.markSeen("c");
+
+    // Re-mark "a" to move it to the end
+    tracker.markSeen("a");
+
+    // Now "b" is oldest; adding "d" should evict "b"
+    tracker.markSeen("d");
+    expect(tracker.hasSeen("b")).toBe(false);
+    expect(tracker.hasSeen("a")).toBe(true);
+    expect(tracker.hasSeen("c")).toBe(true);
+    expect(tracker.hasSeen("d")).toBe(true);
+  });
+
+  it("clear removes all entries", () => {
+    const tracker = new SeenTracker();
+    tracker.markSeen("a");
+    tracker.markSeen("b");
+    expect(tracker.size).toBe(2);
+    tracker.clear();
+    expect(tracker.size).toBe(0);
+    expect(tracker.hasSeen("a")).toBe(false);
+  });
+
+  it("handles default max size of 10000", () => {
+    const tracker = new SeenTracker();
+    for (let i = 0; i < 10001; i++) {
+      tracker.markSeen(`msg-${i}`);
+    }
+    expect(tracker.size).toBe(10000);
+    // First entry should have been evicted
+    expect(tracker.hasSeen("msg-0")).toBe(false);
+    expect(tracker.hasSeen("msg-10000")).toBe(true);
+  });
+});

package/src/seen-tracker.ts

@@ -0,0 +1,56 @@
+/**
+ * LRU-based dedup tracker for incoming NKN message IDs.
+ * Prevents duplicate processing when the same message arrives
+ * via multiple NKN sub-clients.
+ */
+export class SeenTracker {
+  private seen: Map<string, true>;
+  private maxSize: number;
+
+  constructor(maxSize = 10_000) {
+    this.seen = new Map();
+    this.maxSize = maxSize;
+  }
+
+  /** Returns true if the ID was already seen. */
+  hasSeen(id: string): boolean {
+    return this.seen.has(id);
+  }
+
+  /** Mark an ID as seen. Evicts oldest entries if over capacity. */
+  markSeen(id: string): void {
+    if (this.seen.has(id)) {
+      // Move to end (most recent) by deleting and re-inserting
+      this.seen.delete(id);
+    }
+    this.seen.set(id, true);
+    this.evict();
+  }
+
+  /** Check + mark in one call. Returns true if already seen. */
+  checkAndMark(id: string): boolean {
+    if (this.seen.has(id)) {
+      return true;
+    }
+    this.markSeen(id);
+    return false;
+  }
+
+  get size(): number {
+    return this.seen.size;
+  }
+
+  clear(): void {
+    this.seen.clear();
+  }
+
+  private evict(): void {
+    while (this.seen.size > this.maxSize) {
+      // Map iterates in insertion order; first key is oldest
+      const oldest = this.seen.keys().next().value;
+      if (oldest !== undefined) {
+        this.seen.delete(oldest);
+      }
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,144 @@
+/**
+ * D-Chat/nMobile wire format types.
+ * Matches the MessageData envelope sent over NKN relay for full interop
+ * with D-Chat Desktop and nMobile.
+ */
+
+export type MessageContentType =
+  | "text"
+  | "textExtension"
+  | "image"
+  | "audio"
+  | "video"
+  | "file"
+  | "ipfs"
+  | "piece"
+  | "receipt"
+  | "contact"
+  | "contactOptions"
+  | "deviceInfo"
+  | "deviceRequest"
+  | "topic:subscribe"
+  | "topic:unsubscribe"
+  | "privateGroup:invitation"
+  | "privateGroup:accept"
+  | "privateGroup:subscribe"
+  | "privateGroup:quit"
+  | "privateGroup:optionRequest"
+  | "privateGroup:optionResponse"
+  | "privateGroup:memberRequest"
+  | "privateGroup:memberResponse"
+  | "read"
+  | "discovery:broadcast";
+
+/** Control content types that should not be forwarded to the agent. */
+export const CONTROL_CONTENT_TYPES: ReadonlySet<string> = new Set([
+  "receipt",
+  "read",
+  "contact",
+  "contactOptions",
+  "deviceInfo",
+  "deviceRequest",
+  "topic:subscribe",
+  "topic:unsubscribe",
+  "privateGroup:invitation",
+  "privateGroup:accept",
+  "privateGroup:subscribe",
+  "privateGroup:quit",
+  "privateGroup:optionRequest",
+  "privateGroup:optionResponse",
+  "privateGroup:memberRequest",
+  "privateGroup:memberResponse",
+  "discovery:broadcast",
+]);
+
+/** Content types that carry displayable message content. */
+export const DISPLAYABLE_CONTENT_TYPES: ReadonlySet<string> = new Set([
+  "text",
+  "textExtension",
+  "image",
+  "audio",
+  "video",
+  "file",
+  "ipfs",
+]);
+
+export interface MessageOptions {
+  deleteAfterSeconds?: number;
+  updateBurnAfterAt?: number;
+  profileVersion?: string;
+
+  // Full image IPFS (nMobile format)
+  ipfsHash?: string;
+  ipfsIp?: string;
+  ipfsEncrypt?: number;
+  ipfsEncryptAlgorithm?: string; // "AES/GCM/NoPadding"
+  ipfsEncryptKeyBytes?: number[]; // byte array (16 bytes for AES-128)
+  ipfsEncryptNonceSize?: number; // 12 — nonce prepended to ciphertext
+
+  // Thumbnail IPFS (nMobile format)
+  ipfsThumbnailHash?: string;
+  ipfsThumbnailIp?: string;
+  ipfsThumbnailEncrypt?: number;
+  ipfsThumbnailEncryptAlgorithm?: string;
+  ipfsThumbnailEncryptKeyBytes?: number[];
+  ipfsThumbnailEncryptNonceSize?: number;
+
+  // File info
+  fileType?: number | string; // 0=file, 1=image, 2=audio, 3=video
+  fileName?: string;
+  fileExt?: string;
+  fileMimeType?: string;
+  fileSize?: number;
+  mediaWidth?: number;
+  mediaHeight?: number;
+  mediaDuration?: number; // seconds (float), used for audio/video
+}
+
+/** Wire format message envelope sent over NKN relay. */
+export interface MessageData {
+  id: string;
+  contentType: MessageContentType;
+  content?: string;
+  options?: MessageOptions;
+  topic?: string;
+  groupId?: string;
+  targetID?: string; // receipt: references original message ID
+  readIds?: string[]; // read receipt: array of message IDs
+  timestamp: number;
+}
+
+export type NknConnectionState = "disconnected" | "connecting" | "connected";
+
+export interface DchatAccountConfig {
+  seed?: string; // hex wallet seed (64 chars)
+  keystoreJson?: string; // alternative: nkn-sdk keystore JSON
+  keystorePassword?: string;
+  numSubClients?: number; // default: 4
+  ipfsGateway?: string; // default: "64.225.88.71:80"
+  enabled?: boolean;
+  name?: string;
+  dm?: {
+    allowFrom?: Array<string | number>;
+    policy?: string;
+  };
+}
+
+export interface ResolvedDchatAccount {
+  accountId: string;
+  name: string;
+  enabled: boolean;
+  configured: boolean;
+  seed?: string;
+  numSubClients: number;
+  ipfsGateway: string;
+  config: DchatAccountConfig;
+}
+
+/** NKN seed RPC servers for client bootstrap. */
+export const NKN_SEED_RPC_SERVERS = [
+  "http://seed.nkn.org:30003",
+  "http://mainnet-seed-0001.nkn.org:30003",
+  "http://mainnet-seed-0002.nkn.org:30003",
+  "http://mainnet-seed-0003.nkn.org:30003",
+];

package/src/wire.test.ts

@@ -0,0 +1,266 @@
+import { describe, expect, it } from "vitest";
+import type { MessageData } from "./types.js";
+import {
+  extractDmAddressFromSessionKey,
+  extractGroupIdFromSessionKey,
+  extractTopicFromSessionKey,
+  genTopicHash,
+  isControlMessage,
+  isDisplayableMessage,
+  nknToInbound,
+  parseNknPayload,
+  receiptToNkn,
+  stripNknSubClientPrefix,
+  textToNkn,
+} from "./wire.js";
+
+describe("genTopicHash", () => {
+  it("generates topic hash with dchat prefix", () => {
+    const hash = genTopicHash("general");
+    expect(hash).toMatch(/^dchat[0-9a-f]{40}$/);
+  });
+
+  it("strips leading # characters", () => {
+    expect(genTopicHash("#general")).toBe(genTopicHash("general"));
+    expect(genTopicHash("##general")).toBe(genTopicHash("general"));
+  });
+
+  it("produces consistent hashes", () => {
+    expect(genTopicHash("d-chat")).toBe(genTopicHash("d-chat"));
+  });
+
+  it("produces different hashes for different topics", () => {
+    expect(genTopicHash("alpha")).not.toBe(genTopicHash("beta"));
+  });
+});
+
+describe("parseNknPayload", () => {
+  it("parses valid JSON message", () => {
+    const msg: MessageData = {
+      id: "test-123",
+      contentType: "text",
+      content: "hello",
+      timestamp: Date.now(),
+    };
+    const result = parseNknPayload(JSON.stringify(msg));
+    expect(result).toEqual(msg);
+  });
+
+  it("returns null for invalid JSON", () => {
+    expect(parseNknPayload("not json")).toBeNull();
+  });
+
+  it("returns null for missing required fields", () => {
+    expect(parseNknPayload(JSON.stringify({ id: "test" }))).toBeNull();
+    expect(parseNknPayload(JSON.stringify({ contentType: "text" }))).toBeNull();
+  });
+
+  it("returns null for non-object values", () => {
+    expect(parseNknPayload(JSON.stringify(42))).toBeNull();
+    expect(parseNknPayload(JSON.stringify(null))).toBeNull();
+  });
+});
+
+describe("isControlMessage / isDisplayableMessage", () => {
+  it("identifies control messages", () => {
+    expect(isControlMessage("receipt")).toBe(true);
+    expect(isControlMessage("read")).toBe(true);
+    expect(isControlMessage("contact")).toBe(true);
+    expect(isControlMessage("topic:subscribe")).toBe(true);
+    expect(isControlMessage("discovery:broadcast")).toBe(true);
+  });
+
+  it("identifies displayable messages", () => {
+    expect(isDisplayableMessage("text")).toBe(true);
+    expect(isDisplayableMessage("textExtension")).toBe(true);
+    expect(isDisplayableMessage("ipfs")).toBe(true);
+    expect(isDisplayableMessage("audio")).toBe(true);
+  });
+
+  it("control messages are not displayable", () => {
+    expect(isDisplayableMessage("receipt")).toBe(false);
+    expect(isControlMessage("text")).toBe(false);
+  });
+});
+
+describe("nknToInbound", () => {
+  const selfAddr = "self-address-abc123";
+
+  it("translates direct text message", () => {
+    const msg: MessageData = {
+      id: "msg-1",
+      contentType: "text",
+      content: "Hello from NKN",
+      timestamp: Date.now(),
+    };
+    const result = nknToInbound("sender-addr-xyz789", msg, selfAddr);
+    expect(result).not.toBeNull();
+    expect(result!.body).toBe("Hello from NKN");
+    expect(result!.chatType).toBe("direct");
+    expect(result!.sessionKey).toBe("dchat:dm:sender-addr-xyz789");
+    expect(result!.senderId).toBe("sender-addr-xyz789");
+  });
+
+  it("scopes DM session key to account identity", () => {
+    const msg: MessageData = {
+      id: "msg-acct",
+      contentType: "text",
+      content: "multi-account test",
+      timestamp: Date.now(),
+    };
+    const result = nknToInbound("sender-addr", msg, selfAddr, { accountId: "work" });
+    expect(result!.sessionKey).toBe("dchat:work:dm:sender-addr");
+
+    // default account omits the account prefix for backwards compat
+    const resultDefault = nknToInbound("sender-addr", msg, selfAddr, { accountId: "default" });
+    expect(resultDefault!.sessionKey).toBe("dchat:dm:sender-addr");
+
+    // no accountId also omits prefix
+    const resultNone = nknToInbound("sender-addr", msg, selfAddr);
+    expect(resultNone!.sessionKey).toBe("dchat:dm:sender-addr");
+  });
+
+  it("translates topic message", () => {
+    const msg: MessageData = {
+      id: "msg-2",
+      contentType: "text",
+      content: "Hello topic",
+      topic: "general",
+      timestamp: Date.now(),
+    };
+    const result = nknToInbound("sender-addr", msg, selfAddr);
+    expect(result).not.toBeNull();
+    expect(result!.chatType).toBe("group");
+    expect(result!.sessionKey).toBe("dchat:topic:general");
+    expect(result!.groupSubject).toBe("#general");
+  });
+
+  it("translates IPFS image message", () => {
+    const msg: MessageData = {
+      id: "msg-3",
+      contentType: "ipfs",
+      content: "QmXyz...",
+      options: { fileType: 1, ipfsHash: "QmXyz..." },
+      timestamp: Date.now(),
+    };
+    const result = nknToInbound("sender", msg, selfAddr);
+    expect(result).not.toBeNull();
+    expect(result!.body).toBe("[Image]");
+    expect(result!.ipfsHash).toBe("QmXyz...");
+  });
+
+  it("translates IPFS file message", () => {
+    const msg: MessageData = {
+      id: "msg-4",
+      contentType: "ipfs",
+      content: "QmAbc...",
+      options: { fileType: 0, fileName: "report.pdf" },
+      timestamp: Date.now(),
+    };
+    const result = nknToInbound("sender", msg, selfAddr);
+    expect(result!.body).toBe("[File: report.pdf]");
+  });
+
+  it("translates audio message", () => {
+    const msg: MessageData = {
+      id: "msg-5",
+      contentType: "audio",
+      content: "base64data...",
+      timestamp: Date.now(),
+    };
+    const result = nknToInbound("sender", msg, selfAddr);
+    expect(result!.body).toBe("[Voice Message]");
+  });
+
+  it("returns null for control messages", () => {
+    const receipt: MessageData = {
+      id: "msg-6",
+      contentType: "receipt",
+      targetID: "msg-1",
+      timestamp: Date.now(),
+    };
+    expect(nknToInbound("sender", receipt, selfAddr)).toBeNull();
+
+    const readReceipt: MessageData = {
+      id: "msg-7",
+      contentType: "read",
+      readIds: ["msg-1"],
+      timestamp: Date.now(),
+    };
+    expect(nknToInbound("sender", readReceipt, selfAddr)).toBeNull();
+  });
+
+  it("handles textExtension content type", () => {
+    const msg: MessageData = {
+      id: "msg-8",
+      contentType: "textExtension",
+      content: "burn after read message",
+      options: { deleteAfterSeconds: 3600 },
+      timestamp: Date.now(),
+    };
+    const result = nknToInbound("sender", msg, selfAddr);
+    expect(result!.body).toBe("burn after read message");
+  });
+});
+
+describe("textToNkn", () => {
+  it("creates text MessageData", () => {
+    const msg = textToNkn("Hello world");
+    expect(msg.contentType).toBe("text");
+    expect(msg.content).toBe("Hello world");
+    expect(msg.id).toBeTruthy();
+    expect(msg.timestamp).toBeGreaterThan(0);
+    expect(msg.topic).toBeUndefined();
+  });
+
+  it("sets topic field for topic messages", () => {
+    const msg = textToNkn("Hello topic", { topic: "general" });
+    expect(msg.topic).toBe("general");
+  });
+
+  it("sets groupId for group messages", () => {
+    const msg = textToNkn("Hello group", { groupId: "group-123" });
+    expect(msg.groupId).toBe("group-123");
+  });
+});
+
+describe("receiptToNkn", () => {
+  it("creates receipt MessageData", () => {
+    const msg = receiptToNkn("original-msg-id");
+    expect(msg.contentType).toBe("receipt");
+    expect(msg.targetID).toBe("original-msg-id");
+  });
+});
+
+describe("session key extractors", () => {
+  it("extracts topic from session key", () => {
+    expect(extractTopicFromSessionKey("dchat:topic:general")).toBe("general");
+    expect(extractTopicFromSessionKey("dchat:dm:addr")).toBeUndefined();
+  });
+
+  it("extracts group ID from session key", () => {
+    expect(extractGroupIdFromSessionKey("dchat:group:abc123")).toBe("abc123");
+    expect(extractGroupIdFromSessionKey("dchat:dm:addr")).toBeUndefined();
+  });
+
+  it("extracts DM address from session key", () => {
+    expect(extractDmAddressFromSessionKey("dchat:dm:some-nkn-addr")).toBe("some-nkn-addr");
+    expect(extractDmAddressFromSessionKey("dchat:topic:general")).toBeUndefined();
+  });
+
+  it("extracts DM address from account-scoped session key", () => {
+    expect(extractDmAddressFromSessionKey("dchat:work:dm:some-nkn-addr")).toBe("some-nkn-addr");
+  });
+});
+
+describe("stripNknSubClientPrefix", () => {
+  it("strips __N__. prefix", () => {
+    expect(stripNknSubClientPrefix("__0__.cd3530abcdef")).toBe("cd3530abcdef");
+    expect(stripNknSubClientPrefix("__3__.cd3530abcdef")).toBe("cd3530abcdef");
+    expect(stripNknSubClientPrefix("__12__.cd3530abcdef")).toBe("cd3530abcdef");
+  });
+
+  it("leaves plain addresses unchanged", () => {
+    expect(stripNknSubClientPrefix("cd3530abcdef")).toBe("cd3530abcdef");
+  });
+});