@zbruceli/openclaw-dchat 0.1.11 → 0.3.0

package/.claude/settings.local.json

@@ -2,7 +2,11 @@
   "permissions": {
     "allow": [
       "WebFetch(domain:docs.openclaw.ai)",
-      "Bash(node:*)"
+      "Bash(node:*)",
+      "Bash(ls:*)",
+      "Bash(npm test:*)",
+      "Bash(npm run:*)",
+      "Bash(openclaw status:*)"
     ]
   }
 }

package/README.md

@@ -7,42 +7,44 @@ OpenClaw channel plugin for **D-Chat / nMobile** — decentralized end-to-end en
 - Direct messages (DM) with NKN addresses
 - Topic-based group chat (NKN pub/sub)
 - Private group messaging
-- IPFS media placeholders (image, audio, file)
+- Media support — images, voice messages, and file transfers
+  - Images and files sent/received over IPFS with AES-128-GCM encryption
+  - Voice messages via inline AAC (D-Chat Desktop & nMobile compatible)
+  - Graceful fallback to URL text when IPFS upload fails
 - Delivery receipts
-- AES-128-GCM encryption (nMobile wire format compatible)
 - Multi-account support
 - DM policy enforcement (pairing, allowlist, open, disabled)
+- Full nMobile wire format compatibility
 
 ## Installation
 
 ```bash
 openclaw plugins install @zbruceli/openclaw-dchat
+openclaw gateway restart
 ```
 
 ## Configuration
 
-After installing, add the D-Chat channel:
+Add the D-Chat channel after installing:
 
 ```bash
-openclaw channels add --channel dchat
+# Interactive wizard
+openclaw channels add
+
+# Non-interactive
+openclaw channels add --channel dchat --access-token <64-char-hex-seed>
 ```
 
-The onboarding wizard will prompt you for:
+You'll need:
 
-1. **NKN wallet seed** — a 64-character hex string. Generate one with `nkn-sdk` or use an existing seed from D-Chat Desktop / nMobile.
-2. **DM policy** — controls who can send you direct messages:
+1. **NKN wallet seed** — a 64-character hex string. Generate one in D-Chat Desktop (Settings > 1-click bot generation), or use `nkn-sdk`, or reuse an existing seed.
+2. **DM policy** — controls who can send direct messages:
    - `pairing` (default) — new senders must be approved via pairing code
    - `allowlist` — only explicitly allowed NKN addresses
    - `open` — accept DMs from anyone
    - `disabled` — no DMs
 
-You can also configure via environment variables:
-
-```bash
-export DCHAT_SEED="your-64-char-hex-wallet-seed"
-```
-
-Or set directly in your OpenClaw config:
+### Config file
 
 ```yaml
 channels:
@@ -54,22 +56,58 @@ channels:
       - "nkn-address-hex"
 ```
 
+## Pairing
+
+With the default `dmPolicy: pairing`, new senders receive a pairing code that must be approved:
+
+```bash
+openclaw pairing list dchat
+openclaw pairing approve dchat <CODE>
+```
+
+## Channel Management
+
+```bash
+openclaw channels status          # check status
+openclaw channels remove --channel dchat  # remove channel
+openclaw plugins uninstall openclaw-dchat # uninstall plugin
+```
+
+## Debugging
+
+```bash
+openclaw logs | grep -i dchat
+```
+
 ## Development
 
 ```bash
-# Install dependencies
-npm install
+npm install    # install dependencies
+npm test       # run tests
+npm run test:watch  # watch mode
+```
+
+### Local Development
 
-# Run tests
-npm test
+Use the link workflow to avoid the publish/reinstall cycle:
 
-# Watch mode
-npm run test:watch
+```bash
+openclaw plugins install -l /path/to/openclaw-dchat
+openclaw gateway restart  # after code changes, just restart
+```
+
+### Clean Reinstall
+
+```bash
+openclaw plugins uninstall openclaw-dchat
+openclaw channels remove --channel dchat
+openclaw plugins install @zbruceli/openclaw-dchat
+openclaw gateway restart
 ```
 
-## How it works
+## How It Works
 
-The plugin connects to the NKN relay network as a MultiClient node, enabling peer-to-peer messaging without centralized servers. Messages use the same wire format as D-Chat Desktop and nMobile, so you can chat between OpenClaw and any D-Chat/nMobile client.
+The plugin connects to the NKN relay network as a MultiClient node, enabling peer-to-peer messaging without centralized servers. Messages use the same wire format as D-Chat Desktop and nMobile for full interop. Media (images, files) is encrypted with AES-128-GCM and transferred via IPFS; voice messages use inline AAC encoding.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zbruceli/openclaw-dchat",
-  "version": "0.1.11",
+  "version": "0.3.0",
   "description": "OpenClaw D-Chat/nMobile channel plugin — decentralized E2E encrypted messaging over the NKN relay network",
   "type": "module",
   "main": "index.ts",
@@ -17,6 +17,8 @@
     "typescript": "^5.8.0"
   },
   "scripts": {
+    "dev": "echo 'Run: openclaw plugins install -l . && openclaw gateway restart'",
+    "dev:test": "vitest --watch",
     "test": "vitest run",
     "test:watch": "vitest"
   },

package/src/channel.ts

@@ -8,6 +8,7 @@ import {
   DEFAULT_ACCOUNT_ID,
   deleteAccountFromConfigSection,
   normalizeAccountId,
+  resolveOutboundMediaUrls,
   resolveSenderCommandAuthorization,
   setAccountEnabledInConfigSection,
   type ChannelPlugin,
@@ -59,12 +60,15 @@ import {
   extractGroupIdFromSessionKey,
   extractTopicFromSessionKey,
   genTopicHash,
+  ipfsToNkn,
   nknToInbound,
+  parseInlineMediaDataUri,
   parseNknPayload,
   receiptToNkn,
   stripNknSubClientPrefix,
   textToNkn,
 } from "./wire.js";
+import { IpfsService, mimeToIpfsFileType, buildFileMetadata } from "./ipfs.js";
 
 // Per-account NKN bus instances and dedup trackers, keyed by accountId
 const busMap = new Map<string, NknBus>();
@@ -91,7 +95,7 @@ export const dchatPlugin: ChannelPlugin<ResolvedDchatAccount> = {
   onboarding: dchatOnboardingAdapter,
   capabilities: {
     chatTypes: ["direct", "group"],
-    media: false, // IPFS media support is a stretch goal for v2
+    media: true,
     threads: false,
     reactions: false,
     polls: false,
@@ -227,6 +231,108 @@ export const dchatPlugin: ChannelPlugin<ResolvedDchatAccount> = {
         messageId: msgData.id,
       };
     },
+    sendMedia: async ({ to, text, mediaUrl, accountId }) => {
+      const core = getDchatRuntime();
+      const logger = core.logging.getChildLogger({ module: "dchat" });
+      const resolvedAccountId =
+        accountId ??
+        resolveDefaultDchatAccountId(core.config.loadConfig() as CoreConfig);
+      const bus = getBusForAccount(resolvedAccountId);
+      if (!bus) {
+        throw new Error(`D-Chat account "${resolvedAccountId}" not connected`);
+      }
+
+      const accountCfg = resolveDchatAccount({
+        cfg: core.config.loadConfig() as CoreConfig,
+        accountId: resolvedAccountId,
+      });
+
+      const topicName = to.startsWith("topic:") ? to.slice("topic:".length) : undefined;
+      const groupId = to.startsWith("group:") ? to.slice("group:".length) : undefined;
+
+      let mediaMessageId: string | undefined;
+
+      if (mediaUrl) {
+        try {
+          const media = await core.media.loadWebMedia(mediaUrl);
+          const ipfs = new IpfsService(accountCfg.ipfsGateway);
+          const uploadResult = await ipfs.upload(Buffer.from(media.buffer));
+          const fileType = mimeToIpfsFileType(media.contentType);
+          const fileMeta = buildFileMetadata(media);
+          const options = ipfs.buildMessageOptions(uploadResult, fileType, {
+            fileMimeType: media.contentType,
+            ...fileMeta,
+          });
+          const msgData = ipfsToNkn(options, { topic: topicName, groupId });
+          const payload = JSON.stringify(msgData);
+          mediaMessageId = msgData.id;
+
+          if (topicName) {
+            const topicHash = genTopicHash(topicName);
+            const subscribers = await bus.getSubscribers(topicHash);
+            const selfAddr = bus.getAddress();
+            const dests = subscribers.filter((addr) => addr !== selfAddr);
+            if (dests.length > 0) {
+              bus.sendToMultiple(dests, payload);
+            }
+          } else if (groupId) {
+            const dest = to.replace(/^group:/i, "");
+            bus.sendNoReply(dest, payload);
+          } else {
+            const dest = to.replace(/^dchat:/i, "");
+            await bus.send(dest, payload);
+          }
+        } catch (err) {
+          logger.warn(`sendMedia failed for ${mediaUrl}: ${err}`);
+          // Fallback: send the URL as plain text so the recipient still gets a link
+          const fallbackMsg = textToNkn(mediaUrl, { topic: topicName, groupId });
+          const fallbackPayload = JSON.stringify(fallbackMsg);
+          mediaMessageId = fallbackMsg.id;
+
+          if (topicName) {
+            const topicHash = genTopicHash(topicName);
+            const subscribers = await bus.getSubscribers(topicHash);
+            const selfAddr = bus.getAddress();
+            const dests = subscribers.filter((addr) => addr !== selfAddr);
+            if (dests.length > 0) {
+              bus.sendToMultiple(dests, fallbackPayload);
+            }
+          } else if (groupId) {
+            const dest = to.replace(/^group:/i, "");
+            bus.sendNoReply(dest, fallbackPayload);
+          } else {
+            const dest = to.replace(/^dchat:/i, "");
+            await bus.send(dest, fallbackPayload);
+          }
+        }
+      }
+
+      // Send accompanying text as a separate message if present
+      if (text) {
+        const msgData = textToNkn(text, { topic: topicName, groupId });
+        const payload = JSON.stringify(msgData);
+
+        if (topicName) {
+          const topicHash = genTopicHash(topicName);
+          const subscribers = await bus.getSubscribers(topicHash);
+          const selfAddr = bus.getAddress();
+          const dests = subscribers.filter((addr) => addr !== selfAddr);
+          if (dests.length > 0) {
+            bus.sendToMultiple(dests, payload);
+          }
+        } else if (groupId) {
+          const dest = to.replace(/^group:/i, "");
+          bus.sendNoReply(dest, payload);
+        } else {
+          const dest = to.replace(/^dchat:/i, "");
+          await bus.send(dest, payload);
+        }
+
+        return { channel: "dchat", messageId: msgData.id };
+      }
+
+      return { channel: "dchat", messageId: mediaMessageId ?? "" };
+    },
   },
   setup: {
     resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
@@ -332,6 +438,39 @@ export const dchatPlugin: ChannelPlugin<ResolvedDchatAccount> = {
       const seenTracker = new SeenTracker();
       seenMap.set(account.accountId, seenTracker);
 
+      // Listen for heartbeat events
+      bus.on("heartbeat", ({ success, failures }: { success: boolean; failures: number }) => {
+        if (!success) {
+          logger.warn(`[${account.accountId}] heartbeat echo failed (${failures} consecutive)`);
+        }
+      });
+      bus.on("heartbeatReconnect", ({ failures }: { failures: number }) => {
+        logger.warn(
+          `[${account.accountId}] heartbeat failed ${failures} times, reconnecting...`,
+        );
+        ctx.setStatus({ accountId: account.accountId, connected: false });
+      });
+      let initialConnectDone = false;
+      bus.on("stateChange", (state: string) => {
+        if (state === "connected" && initialConnectDone) {
+          ctx.setStatus({
+            accountId: account.accountId,
+            connected: true,
+            lastConnectedAt: Date.now(),
+          });
+          logger.info(`[${account.accountId}] reconnected as ${bus.getAddress()}`);
+        }
+      });
+      bus.on("reconnectFailed", (err: unknown) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.error(`[${account.accountId}] reconnect failed: ${msg}`);
+        ctx.setStatus({
+          accountId: account.accountId,
+          connected: false,
+          lastError: `reconnect failed: ${msg}`,
+        });
+      });
+
       try {
         const address = await bus.connect(
           { seed: account.seed, numSubClients: account.numSubClients },
@@ -347,6 +486,7 @@ export const dchatPlugin: ChannelPlugin<ResolvedDchatAccount> = {
           lastConnectedAt: Date.now(),
         });
         logger.info(`[${account.accountId}] connected as ${address}`);
+        initialConnectDone = true;
 
         // Register inbound message handler
         bus.onMessage((rawSrc, rawPayload) => {
@@ -490,6 +630,71 @@ export const dchatPlugin: ChannelPlugin<ResolvedDchatAccount> = {
                 sessionKey: route.sessionKey,
               });
 
+              // Download full-resolution IPFS media if present (non-fatal on failure)
+              let mediaFields: Record<string, unknown> = {};
+              let inboundBodyText = inbound.body;
+              if (inbound.ipfsHash && inbound.ipfsOptions) {
+                try {
+                  const ipfs = new IpfsService(account.ipfsGateway);
+                  const data = await ipfs.download(inbound.ipfsHash, {
+                    encrypt: inbound.ipfsOptions.ipfsEncrypt,
+                    encryptKeyBytes: inbound.ipfsOptions.ipfsEncryptKeyBytes,
+                    encryptNonceSize: inbound.ipfsOptions.ipfsEncryptNonceSize,
+                  });
+                  const mime =
+                    inbound.ipfsOptions.fileMimeType ??
+                    (await core.media.detectMime?.({ buffer: data })) ??
+                    "application/octet-stream";
+                  const saved = await core.channel.media.saveMediaBuffer(
+                    data,
+                    mime,
+                    "inbound",
+                  );
+                  mediaFields = {
+                    MediaPath: saved.path,
+                    MediaUrl: `file://${saved.path}`,
+                    MediaType: mime,
+                  };
+                  // Replace placeholder with media tag so the agent sees the
+                  // full-resolution image from IPFS, not a text placeholder.
+                  const kind = mime.startsWith("audio/")
+                    ? "audio"
+                    : mime.startsWith("video/")
+                      ? "video"
+                      : mime.startsWith("image/")
+                        ? "image"
+                        : "file";
+                  inboundBodyText = `<media:${kind}>`;
+                } catch (err) {
+                  logger.warn(`IPFS download failed: ${err}`);
+                  // Non-fatal: message still delivered with placeholder text
+                }
+              }
+
+              // Handle inline audio (D-Chat/nMobile send voice as base64 data-URI)
+              if (!mediaFields.MediaPath && inbound.inlineMediaDataUri) {
+                try {
+                  const parsed = parseInlineMediaDataUri(inbound.inlineMediaDataUri);
+                  if (parsed) {
+                    // Normalize nMobile MIME variants to standard audio/aac
+                    const mime = parsed.mime === "audio/x-aac" ? "audio/aac" : parsed.mime;
+                    const saved = await core.channel.media.saveMediaBuffer(
+                      parsed.buffer,
+                      mime,
+                      "inbound",
+                    );
+                    mediaFields = {
+                      MediaPath: saved.path,
+                      MediaUrl: `file://${saved.path}`,
+                      MediaType: mime,
+                    };
+                    inboundBodyText = "<media:audio>";
+                  }
+                } catch (err) {
+                  logger.warn(`Inline audio decode failed: ${err}`);
+                }
+              }
+
               const body = core.channel.reply.formatAgentEnvelope({
                 channel: "D-Chat",
                 from:
@@ -499,14 +704,15 @@ export const dchatPlugin: ChannelPlugin<ResolvedDchatAccount> = {
                 timestamp: msg.timestamp,
                 previousTimestamp,
                 envelope: envelopeOptions,
-                body: inbound.body,
+                body: inboundBodyText,
               });
 
               const ctxPayload = core.channel.reply.finalizeInboundContext({
                 Body: body,
-                BodyForAgent: inbound.body,
-                RawBody: inbound.body,
-                CommandBody: inbound.body,
+                BodyForAgent: inboundBodyText,
+                RawBody: inboundBodyText,
+                CommandBody: inboundBodyText,
+                ...mediaFields,
                 From:
                   inbound.chatType === "direct"
                     ? `dchat:${src}`
@@ -567,28 +773,59 @@ export const dchatPlugin: ChannelPlugin<ResolvedDchatAccount> = {
               const { dispatcher, replyOptions, markDispatchIdle } =
                 core.channel.reply.createReplyDispatcherWithTyping({
                   deliver: async (payload) => {
-                    // Deliver reply back to NKN
                     const replyText = payload.text ?? "";
-                    if (!replyText) return;
-
                     const topic = extractTopicFromSessionKey(inbound.sessionKey);
                     const groupIdFromKey = extractGroupIdFromSessionKey(inbound.sessionKey);
-                    const replyMsg = textToNkn(replyText, { topic, groupId: groupIdFromKey });
-                    const replyPayload = JSON.stringify(replyMsg);
-
-                    if (topic) {
-                      const topicHash = genTopicHash(topic);
-                      const subscribers = await bus.getSubscribers(topicHash);
-                      const dests = subscribers.filter((a) => a !== selfAddress);
-                      if (dests.length > 0) {
-                        bus.sendToMultiple(dests, replyPayload);
+
+                    // Helper to route a payload string via NKN
+                    const routeNkn = async (nknPayload: string) => {
+                      if (topic) {
+                        const topicHash = genTopicHash(topic);
+                        const subscribers = await bus.getSubscribers(topicHash);
+                        const dests = subscribers.filter((a) => a !== selfAddress);
+                        if (dests.length > 0) {
+                          bus.sendToMultiple(dests, nknPayload);
+                        }
+                      } else if (groupIdFromKey) {
+                        bus.sendNoReply(groupIdFromKey, nknPayload);
+                      } else {
+                        bus.sendNoReply(src, nknPayload);
+                      }
+                    };
+
+                    // Handle media URLs (images, audio, files)
+                    const mediaUrls = resolveOutboundMediaUrls(payload);
+                    if (mediaUrls.length > 0) {
+                      const ipfs = new IpfsService(account.ipfsGateway);
+                      for (const mediaUrl of mediaUrls) {
+                        try {
+                          const media = await core.media.loadWebMedia(mediaUrl);
+                          const uploadResult = await ipfs.upload(Buffer.from(media.buffer));
+                          const fileType = mimeToIpfsFileType(media.contentType);
+                          const fileMeta = buildFileMetadata(media);
+                          const options = ipfs.buildMessageOptions(uploadResult, fileType, {
+                            fileMimeType: media.contentType,
+                            ...fileMeta,
+                          });
+                          const msgData = ipfsToNkn(options, { topic, groupId: groupIdFromKey });
+                          await routeNkn(JSON.stringify(msgData));
+                        } catch (err) {
+                          logger.warn(`media send failed for ${mediaUrl}: ${err}`);
+                          // Fallback: send the URL as plain text
+                          try {
+                            const fallback = textToNkn(mediaUrl, { topic, groupId: groupIdFromKey });
+                            await routeNkn(JSON.stringify(fallback));
+                          } catch {
+                            // fallback send failure is non-fatal
+                          }
+                        }
                       }
-                    } else if (groupIdFromKey) {
-                      // Private group: route reply to the group address
-                      bus.sendNoReply(groupIdFromKey, replyPayload);
-                    } else {
-                      bus.sendNoReply(src, replyPayload);
                     }
+
+                    // Handle text (existing logic)
+                    if (!replyText) return;
+                    const replyMsg = textToNkn(replyText, { topic, groupId: groupIdFromKey });
+                    await routeNkn(JSON.stringify(replyMsg));
                   },
                   humanDelay: core.channel.reply.resolveHumanDelayConfig(cfg, ""),
                 });