@zbruceli/openclaw-dchat 0.1.0

package/src/config-schema.ts

@@ -0,0 +1,124 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { z } from "zod";
+import type { DchatAccountConfig, ResolvedDchatAccount } from "./types.js";
+
+type CoreConfig = OpenClawConfig & {
+  channels?: {
+    dchat?: DchatAccountConfig & {
+      accounts?: Record<string, DchatAccountConfig>;
+      defaultAccount?: string;
+    };
+  };
+};
+
+export type { CoreConfig };
+
+const DEFAULT_ACCOUNT_ID = "default";
+
+/* ── Zod config schema (powers web UI form via buildChannelConfigSchema) ── */
+
+const dchatAccountSchema = z.object({
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  seed: z.string().optional(),
+  keystoreJson: z.string().optional(),
+  keystorePassword: z.string().optional(),
+  numSubClients: z.number().optional(),
+  ipfsGateway: z.string().optional(),
+  dm: z
+    .object({
+      policy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
+      allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    })
+    .optional(),
+});
+
+export const DchatConfigSchema = dchatAccountSchema.extend({
+  accounts: z.record(z.string(), dchatAccountSchema.optional()).optional(),
+  defaultAccount: z.string().optional(),
+});
+
+/* ── Config helpers ── */
+
+export function listDchatAccountIds(cfg: CoreConfig): string[] {
+  const dchatConfig = cfg.channels?.dchat;
+  if (!dchatConfig) return [];
+
+  const ids: string[] = [];
+
+  // Top-level config counts as the default account
+  if (dchatConfig.seed || dchatConfig.keystoreJson) {
+    ids.push(DEFAULT_ACCOUNT_ID);
+  }
+
+  // Named accounts
+  if (dchatConfig.accounts) {
+    for (const id of Object.keys(dchatConfig.accounts)) {
+      if (!ids.includes(id)) {
+        ids.push(id);
+      }
+    }
+  }
+
+  if (ids.length === 0 && dchatConfig.enabled !== false) {
+    ids.push(DEFAULT_ACCOUNT_ID);
+  }
+
+  return ids;
+}
+
+export function resolveDefaultDchatAccountId(cfg: CoreConfig): string {
+  const dchatConfig = cfg.channels?.dchat;
+  if (dchatConfig?.defaultAccount) return dchatConfig.defaultAccount;
+  // If top-level seed exists, treat as the default account
+  if (dchatConfig?.seed?.trim()) return DEFAULT_ACCOUNT_ID;
+  // Otherwise pick the first named account
+  const named = dchatConfig?.accounts ? Object.keys(dchatConfig.accounts) : [];
+  return named[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+export function resolveDchatAccountConfig(params: {
+  cfg: CoreConfig;
+  accountId?: string | null;
+}): DchatAccountConfig {
+  const { cfg, accountId } = params;
+  const dchatConfig = cfg.channels?.dchat;
+  if (!dchatConfig) return { enabled: false };
+
+  if (accountId && dchatConfig.accounts?.[accountId]) {
+    // Named account: merge channel-level fields (e.g. dm policy) as defaults
+    const acct = dchatConfig.accounts[accountId];
+    return {
+      ...dchatConfig,
+      ...acct,
+      dm: { ...dchatConfig.dm, ...acct.dm },
+    };
+  }
+
+  // Top-level config (default account without explicit accounts.default entry)
+  return dchatConfig;
+}
+
+export function resolveDchatAccount(params: {
+  cfg: CoreConfig;
+  accountId?: string | null;
+}): ResolvedDchatAccount {
+  const { cfg, accountId: rawAccountId } = params;
+  const accountId = rawAccountId || DEFAULT_ACCOUNT_ID;
+  const accountConfig = resolveDchatAccountConfig({ cfg, accountId });
+
+  const hasSeed = Boolean(accountConfig.seed?.trim());
+  const hasKeystore = Boolean(accountConfig.keystoreJson?.trim());
+
+  const baseEnabled = cfg.channels?.dchat?.enabled !== false;
+  return {
+    accountId,
+    name: accountConfig.name || accountId,
+    enabled: baseEnabled && accountConfig.enabled !== false,
+    configured: hasSeed,
+    seed: accountConfig.seed?.trim(),
+    numSubClients: accountConfig.numSubClients ?? 4,
+    ipfsGateway: accountConfig.ipfsGateway ?? "64.225.88.71:80",
+    config: accountConfig,
+  };
+}

package/src/crypto.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+import { byteArrayToKey, decryptAesGcm, encryptAesGcm, keyToByteArray } from "./crypto.js";
+
+describe("AES-128-GCM crypto", () => {
+  it("encrypts and decrypts round-trip", () => {
+    const plaintext = Buffer.from("Hello, D-Chat!");
+    const { ciphertext, key } = encryptAesGcm(plaintext);
+
+    const decrypted = decryptAesGcm(ciphertext, key);
+    expect(decrypted.toString()).toBe("Hello, D-Chat!");
+  });
+
+  it("produces different ciphertext for same plaintext", () => {
+    const plaintext = Buffer.from("Same input");
+    const result1 = encryptAesGcm(plaintext);
+    const result2 = encryptAesGcm(plaintext);
+
+    // Different random keys/nonces should produce different ciphertext
+    expect(result1.ciphertext).not.toEqual(result2.ciphertext);
+  });
+
+  it("uses correct nonce and key sizes", () => {
+    const { key, nonce } = encryptAesGcm(Buffer.from("test"));
+    expect(key.length).toBe(16); // AES-128 = 16-byte key
+    expect(nonce.length).toBe(12); // GCM standard nonce
+  });
+
+  it("ciphertext format: nonce (12B) + encrypted + auth tag (16B)", () => {
+    const plaintext = Buffer.from("test data");
+    const { ciphertext, nonce } = encryptAesGcm(plaintext);
+
+    // First 12 bytes should be the nonce
+    expect(ciphertext.subarray(0, 12)).toEqual(nonce);
+
+    // Minimum size: 12 (nonce) + 1 (data) + 16 (auth tag) = 29
+    expect(ciphertext.length).toBeGreaterThanOrEqual(12 + 1 + 16);
+  });
+
+  it("fails to decrypt with wrong key", () => {
+    const plaintext = Buffer.from("secret");
+    const { ciphertext } = encryptAesGcm(plaintext);
+    const wrongKey = Buffer.alloc(16, 0xff);
+
+    expect(() => decryptAesGcm(ciphertext, wrongKey)).toThrow();
+  });
+
+  it("handles empty plaintext", () => {
+    const plaintext = Buffer.alloc(0);
+    const { ciphertext, key } = encryptAesGcm(plaintext);
+
+    const decrypted = decryptAesGcm(ciphertext, key);
+    expect(decrypted.length).toBe(0);
+  });
+
+  it("handles large plaintext", () => {
+    const plaintext = Buffer.alloc(1024 * 100, 0x42); // 100KB
+    const { ciphertext, key } = encryptAesGcm(plaintext);
+
+    const decrypted = decryptAesGcm(ciphertext, key);
+    expect(decrypted).toEqual(plaintext);
+  });
+});
+
+describe("key conversion helpers", () => {
+  it("converts key to byte array (nMobile wire format)", () => {
+    const key = Buffer.from([
+      0xb0, 0x71, 0x5a, 0xff, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a,
+      0x0b,
+    ]);
+    const bytes = keyToByteArray(key);
+    expect(bytes).toEqual([176, 113, 90, 255, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]);
+  });
+
+  it("round-trips key through byte array", () => {
+    const original = Buffer.from([
+      0xde, 0xad, 0xbe, 0xef, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
+      0x0c,
+    ]);
+    const bytes = keyToByteArray(original);
+    const restored = byteArrayToKey(bytes);
+    expect(restored).toEqual(original);
+  });
+
+  it("encryption + byte array round-trip", () => {
+    const plaintext = Buffer.from("nMobile interop test");
+    const { ciphertext, key } = encryptAesGcm(plaintext);
+
+    // Simulate nMobile wire format: convert key to number[] and back
+    const keyBytes = keyToByteArray(key);
+    const restoredKey = byteArrayToKey(keyBytes);
+
+    const decrypted = decryptAesGcm(ciphertext, restoredKey);
+    expect(decrypted.toString()).toBe("nMobile interop test");
+  });
+});

package/src/crypto.ts

@@ -0,0 +1,56 @@
+import crypto from "crypto";
+
+const ALGORITHM = "aes-128-gcm";
+const KEY_BYTES = 16;
+const NONCE_BYTES = 12;
+const AUTH_TAG_BYTES = 16;
+
+export interface EncryptResult {
+  ciphertext: Buffer; // nonce (12 bytes) + encrypted data + auth tag (16 bytes)
+  key: Buffer; // 16-byte AES key
+  nonce: Buffer; // 12-byte nonce (also prepended to ciphertext)
+}
+
+/**
+ * Encrypt with AES-128-GCM, prepending nonce to ciphertext (nMobile convention).
+ * Output format: [nonce (12 bytes)] [encrypted data] [auth tag (16 bytes)]
+ */
+export function encryptAesGcm(plaintext: Buffer): EncryptResult {
+  const key = crypto.randomBytes(KEY_BYTES);
+  const nonce = crypto.randomBytes(NONCE_BYTES);
+
+  const cipher = crypto.createCipheriv(ALGORITHM, key, nonce);
+  const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+
+  const ciphertext = Buffer.concat([nonce, encrypted, authTag]);
+
+  return { ciphertext, key, nonce };
+}
+
+/**
+ * Decrypt AES-128-GCM with nonce prepended to ciphertext (nMobile convention).
+ * Input format: [nonce (12 bytes)] [encrypted data] [auth tag (16 bytes)]
+ */
+export function decryptAesGcm(data: Buffer, key: Buffer, nonceSize: number = NONCE_BYTES): Buffer {
+  const nonce = data.subarray(0, nonceSize);
+  const ciphertextWithTag = data.subarray(nonceSize);
+
+  const encrypted = ciphertextWithTag.subarray(0, ciphertextWithTag.length - AUTH_TAG_BYTES);
+  const authTag = ciphertextWithTag.subarray(ciphertextWithTag.length - AUTH_TAG_BYTES);
+
+  const decipher = crypto.createDecipheriv(ALGORITHM, key, nonce);
+  decipher.setAuthTag(authTag);
+
+  return Buffer.concat([decipher.update(encrypted), decipher.final()]);
+}
+
+/** Convert a Buffer key to a number[] array (nMobile wire format). */
+export function keyToByteArray(key: Buffer): number[] {
+  return Array.from(key);
+}
+
+/** Convert a number[] byte array back to Buffer. */
+export function byteArrayToKey(bytes: number[]): Buffer {
+  return Buffer.from(bytes);
+}

package/src/nkn-bus.ts

@@ -0,0 +1,213 @@
+import { EventEmitter } from "events";
+import nkn from "nkn-sdk";
+import { NKN_SEED_RPC_SERVERS, type NknConnectionState } from "./types.js";
+
+export interface NknBusOptions {
+  seed: string;
+  numSubClients?: number;
+}
+
+/**
+ * NKN MultiClient wrapper for D-Chat wire-format messaging.
+ * Handles connect, send, receive, subscribe, and reconnection.
+ */
+export class NknBus extends EventEmitter {
+  private client: nkn.MultiClient | null = null;
+  private state: NknConnectionState = "disconnected";
+  private address: string | undefined;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private seed: string | undefined;
+  private numSubClients: number;
+  private abortSignal: AbortSignal | undefined;
+
+  constructor() {
+    super();
+    this.numSubClients = 4;
+  }
+
+  getState(): NknConnectionState {
+    return this.state;
+  }
+
+  getAddress(): string | undefined {
+    return this.address;
+  }
+
+  async connect(opts: NknBusOptions, abortSignal?: AbortSignal): Promise<string> {
+    if (this.client) {
+      await this.disconnect();
+    }
+
+    this.seed = opts.seed;
+    this.numSubClients = opts.numSubClients ?? 4;
+    this.abortSignal = abortSignal;
+    this.setState("connecting");
+
+    try {
+      this.client = new nkn.MultiClient({
+        seed: opts.seed,
+        numSubClients: this.numSubClients,
+        originalClient: false,
+        rpcServerAddr: NKN_SEED_RPC_SERVERS[0],
+      });
+
+      await new Promise<void>((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          reject(new Error("NKN connection timeout after 30s"));
+        }, 30000);
+
+        if (abortSignal?.aborted) {
+          clearTimeout(timeout);
+          reject(new Error("Aborted"));
+          return;
+        }
+
+        const onAbort = () => {
+          clearTimeout(timeout);
+          reject(new Error("Aborted"));
+        };
+        abortSignal?.addEventListener("abort", onAbort, { once: true });
+
+        this.client!.onConnect(() => {
+          clearTimeout(timeout);
+          abortSignal?.removeEventListener("abort", onAbort);
+          resolve();
+        });
+      });
+
+      this.address = this.client.addr;
+      this.setState("connected");
+
+      // Register message handler: src may include __N__. sub-client prefix; caller should normalize
+      this.client.onMessage(({ src, payload }: { src: string; payload: Uint8Array | string }) => {
+        let data: string;
+        if (payload instanceof Uint8Array) {
+          data = new TextDecoder().decode(payload);
+        } else {
+          data = payload;
+        }
+        this.emit("message", src, data);
+      });
+
+      return this.address;
+    } catch (err) {
+      this.setState("disconnected");
+      if (this.client) {
+        try {
+          this.client.close();
+        } catch {
+          // ignore close errors during cleanup
+        }
+        this.client = null;
+      }
+      throw err;
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.client) {
+      try {
+        this.client.close();
+      } catch {
+        // ignore close errors
+      }
+      this.client = null;
+    }
+    this.address = undefined;
+    this.setState("disconnected");
+  }
+
+  /**
+   * Send a message and wait for recipient ACK.
+   * Used for direct text messages.
+   */
+  async send(dest: string, payload: string): Promise<void> {
+    this.ensureConnected();
+    await this.client!.send(dest, payload, {
+      msgHoldingSeconds: 3600,
+    });
+  }
+
+  /**
+   * Send without waiting for ACK (fire-and-forget).
+   * Used for media messages and topic broadcasts.
+   */
+  sendNoReply(dest: string, payload: string): void {
+    this.ensureConnected();
+    this.client!.send(dest, payload, {
+      noReply: true,
+      msgHoldingSeconds: 3600,
+    });
+  }
+
+  /**
+   * Send to multiple destinations (topic broadcast).
+   * Fire-and-forget.
+   */
+  sendToMultiple(dests: string[], payload: string): void {
+    this.ensureConnected();
+    if (dests.length === 0) return;
+    this.client!.send(dests, payload, {
+      noReply: true,
+      msgHoldingSeconds: 3600,
+    });
+  }
+
+  /** Subscribe to a topic on the NKN blockchain. */
+  async subscribe(topicHash: string, duration = 400000, fee = "0"): Promise<string> {
+    this.ensureConnected();
+    const txnHash = await this.client!.subscribe(topicHash, duration, "", "", {
+      fee,
+      attrs: undefined,
+      buildOnly: undefined,
+    } as nkn.TransactionOptions);
+    return String(txnHash);
+  }
+
+  /** Unsubscribe from a topic. */
+  async unsubscribe(topicHash: string, fee = "0"): Promise<string> {
+    this.ensureConnected();
+    const txnHash = await this.client!.unsubscribe(topicHash, "", {
+      fee,
+      attrs: undefined,
+      buildOnly: undefined,
+    } as nkn.TransactionOptions);
+    return String(txnHash);
+  }
+
+  /** Fetch subscriber addresses for a topic. */
+  async getSubscribers(topicHash: string): Promise<string[]> {
+    this.ensureConnected();
+    const result = await this.client!.getSubscribers(topicHash, {
+      offset: 0,
+      limit: 1000,
+      txPool: true,
+    });
+    const subs = result.subscribers;
+    if (Array.isArray(subs)) {
+      return subs;
+    }
+    // Record<string, string> form — keys are addresses
+    return Object.keys(subs);
+  }
+
+  /** Register a handler for incoming NKN messages. */
+  onMessage(handler: (src: string, data: string) => void): void {
+    this.on("message", handler);
+  }
+
+  private ensureConnected(): void {
+    if (!this.client || this.state !== "connected") {
+      throw new Error("NKN client not connected");
+    }
+  }
+
+  private setState(next: NknConnectionState): void {
+    this.state = next;
+    this.emit("stateChange", next);
+  }
+}

package/src/onboarding.ts

@@ -0,0 +1,195 @@
+import type { DmPolicy } from "openclaw/plugin-sdk";
+import {
+  addWildcardAllowFrom,
+  mergeAllowFromEntries,
+  formatDocsLink,
+  type ChannelOnboardingAdapter,
+  type ChannelOnboardingDmPolicy,
+  type WizardPrompter,
+} from "openclaw/plugin-sdk";
+import { listDchatAccountIds, resolveDchatAccount, type CoreConfig } from "./config-schema.js";
+
+const channel = "dchat" as const;
+
+function setDchatDmPolicy(cfg: CoreConfig, policy: DmPolicy) {
+  const existingAllowFrom = cfg.channels?.dchat?.dm?.allowFrom ?? [];
+  const allowFrom =
+    policy === "open"
+      ? addWildcardAllowFrom(existingAllowFrom)
+      : existingAllowFrom.filter((e) => String(e) !== "*");
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      dchat: {
+        ...cfg.channels?.dchat,
+        dm: {
+          ...cfg.channels?.dchat?.dm,
+          policy,
+          allowFrom,
+        },
+      },
+    },
+  };
+}
+
+async function promptDchatAllowFrom(params: {
+  cfg: CoreConfig;
+  prompter: WizardPrompter;
+}): Promise<CoreConfig> {
+  const { cfg, prompter } = params;
+  const existingAllowFrom = cfg.channels?.dchat?.dm?.allowFrom ?? [];
+
+  const entry = await prompter.text({
+    message: "NKN address to allow (full public key hex)",
+    placeholder: "abc123...def456 (64-char hex NKN address)",
+    initialValue: existingAllowFrom[0] ? String(existingAllowFrom[0]) : undefined,
+    validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+  });
+
+  const parts = String(entry)
+    .split(/[\n,;]+/g)
+    .map((e) => e.trim())
+    .filter(Boolean);
+
+  const unique = mergeAllowFromEntries(existingAllowFrom, parts);
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      dchat: {
+        ...cfg.channels?.dchat,
+        enabled: true,
+        dm: {
+          ...cfg.channels?.dchat?.dm,
+          policy: "allowlist",
+          allowFrom: unique,
+        },
+      },
+    },
+  };
+}
+
+const dmPolicy: ChannelOnboardingDmPolicy = {
+  label: "D-Chat",
+  channel,
+  policyKey: "channels.dchat.dm.policy",
+  allowFromKey: "channels.dchat.dm.allowFrom",
+  getCurrent: (cfg) => ((cfg as CoreConfig).channels?.dchat?.dm?.policy as DmPolicy) ?? "pairing",
+  setPolicy: (cfg, policy) => setDchatDmPolicy(cfg as CoreConfig, policy),
+  promptAllowFrom: promptDchatAllowFrom,
+};
+
+export const dchatOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel,
+  getStatus: async ({ cfg }) => {
+    const typedCfg = cfg as CoreConfig;
+    const accountIds = listDchatAccountIds(typedCfg);
+    const anyConfigured = accountIds.some(
+      (id) => resolveDchatAccount({ cfg: typedCfg, accountId: id }).configured,
+    );
+    return {
+      channel,
+      configured: anyConfigured,
+      statusLines: [`D-Chat: ${anyConfigured ? "configured" : "needs wallet seed"}`],
+      selectionHint: anyConfigured ? "configured" : "needs seed",
+    };
+  },
+  configure: async ({ cfg, prompter, forceAllowFrom }) => {
+    let next = cfg as CoreConfig;
+    const existing = next.channels?.dchat ?? {};
+    const account = resolveDchatAccount({ cfg: next });
+
+    if (!account.configured) {
+      await prompter.note(
+        [
+          "D-Chat uses the NKN relay network for decentralized E2E encrypted messaging.",
+          "You need a wallet seed (64-character hex string) to connect.",
+          "Generate one with nkn-sdk or use an existing seed from D-Chat/nMobile.",
+          `Docs: ${formatDocsLink("/channels/dchat", "channels/dchat")}`,
+        ].join("\n"),
+        "D-Chat setup",
+      );
+    }
+
+    // Check for env var (validate same 64-hex format as prompted input)
+    const envSeed = process.env.DCHAT_SEED?.trim() || process.env.NKN_SEED?.trim();
+    if (envSeed && /^[0-9a-f]{64}$/i.test(envSeed) && !existing.seed) {
+      const useEnv = await prompter.confirm({
+        message: "NKN seed env var detected. Use env value?",
+        initialValue: true,
+      });
+      if (useEnv) {
+        next = {
+          ...next,
+          channels: {
+            ...next.channels,
+            dchat: {
+              ...next.channels?.dchat,
+              enabled: true,
+              seed: envSeed,
+            },
+          },
+        };
+        if (forceAllowFrom) {
+          next = await promptDchatAllowFrom({ cfg: next, prompter });
+        }
+        return { cfg: next };
+      }
+    }
+
+    // Prompt for seed
+    let seed = existing.seed ?? "";
+    if (seed) {
+      const keep = await prompter.confirm({
+        message: "Wallet seed already configured. Keep it?",
+        initialValue: true,
+      });
+      if (!keep) {
+        seed = "";
+      }
+    }
+
+    if (!seed) {
+      seed = String(
+        await prompter.text({
+          message: "NKN wallet seed (64-char hex)",
+          validate: (value) => {
+            const raw = String(value ?? "").trim();
+            if (!raw) return "Required";
+            if (!/^[0-9a-f]{64}$/i.test(raw)) {
+              return "Must be a 64-character hex string";
+            }
+            return undefined;
+          },
+        }),
+      ).trim();
+    }
+
+    next = {
+      ...next,
+      channels: {
+        ...next.channels,
+        dchat: {
+          ...next.channels?.dchat,
+          enabled: true,
+          seed,
+        },
+      },
+    };
+
+    if (forceAllowFrom) {
+      next = await promptDchatAllowFrom({ cfg: next, prompter });
+    }
+
+    return { cfg: next };
+  },
+  dmPolicy,
+  disable: (cfg) => ({
+    ...(cfg as CoreConfig),
+    channels: {
+      ...(cfg as CoreConfig).channels,
+      dchat: { ...(cfg as CoreConfig).channels?.dchat, enabled: false },
+    },
+  }),
+};

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setDchatRuntime(next: PluginRuntime) {
+  runtime = next;
+}
+
+export function getDchatRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("D-Chat runtime not initialized");
+  }
+  return runtime;
+}