@zbruceli/openclaw-dchat 0.1.11 → 0.2.0

package/.claude/settings.local.json

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

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.2.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),
@@ -490,6 +596,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 +670,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 +739,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, ""),
                 });

package/src/ipfs.test.ts

@@ -0,0 +1,301 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import http from "http";
+import { EventEmitter } from "events";
+import { IpfsService, IPFS_FILE_TYPE, mimeToIpfsFileType, buildFileMetadata } from "./ipfs.js";
+import { decryptAesGcm, encryptAesGcm, keyToByteArray, byteArrayToKey } from "./crypto.js";
+
+describe("mimeToIpfsFileType", () => {
+  it("maps image/* to IMAGE (1)", () => {
+    expect(mimeToIpfsFileType("image/png")).toBe(IPFS_FILE_TYPE.IMAGE);
+    expect(mimeToIpfsFileType("image/jpeg")).toBe(IPFS_FILE_TYPE.IMAGE);
+    expect(mimeToIpfsFileType("image/gif")).toBe(IPFS_FILE_TYPE.IMAGE);
+    expect(mimeToIpfsFileType("Image/WebP")).toBe(IPFS_FILE_TYPE.IMAGE);
+  });
+
+  it("maps audio/* to AUDIO (2)", () => {
+    expect(mimeToIpfsFileType("audio/mpeg")).toBe(IPFS_FILE_TYPE.AUDIO);
+    expect(mimeToIpfsFileType("audio/ogg")).toBe(IPFS_FILE_TYPE.AUDIO);
+    expect(mimeToIpfsFileType("Audio/WAV")).toBe(IPFS_FILE_TYPE.AUDIO);
+  });
+
+  it("maps video/* to VIDEO (3)", () => {
+    expect(mimeToIpfsFileType("video/mp4")).toBe(IPFS_FILE_TYPE.VIDEO);
+    expect(mimeToIpfsFileType("Video/WebM")).toBe(IPFS_FILE_TYPE.VIDEO);
+  });
+
+  it("maps unknown types to FILE (0)", () => {
+    expect(mimeToIpfsFileType("application/pdf")).toBe(IPFS_FILE_TYPE.FILE);
+    expect(mimeToIpfsFileType("text/plain")).toBe(IPFS_FILE_TYPE.FILE);
+  });
+
+  it("defaults to IMAGE when undefined", () => {
+    expect(mimeToIpfsFileType(undefined)).toBe(IPFS_FILE_TYPE.IMAGE);
+  });
+});
+
+describe("IPFS_FILE_TYPE constants", () => {
+  it("has correct values", () => {
+    expect(IPFS_FILE_TYPE.FILE).toBe(0);
+    expect(IPFS_FILE_TYPE.IMAGE).toBe(1);
+    expect(IPFS_FILE_TYPE.AUDIO).toBe(2);
+    expect(IPFS_FILE_TYPE.VIDEO).toBe(3);
+  });
+});
+
+describe("IpfsService.buildMessageOptions", () => {
+  const service = new IpfsService("10.0.0.1:5001");
+
+  const fakeResult = {
+    hash: "QmTestHash123",
+    key: Buffer.alloc(16, 0xab),
+    nonce: Buffer.alloc(12, 0xcd),
+    nonceSize: 12,
+  };
+
+  it("produces correct wire format for IMAGE", () => {
+    const opts = service.buildMessageOptions(fakeResult, IPFS_FILE_TYPE.IMAGE);
+
+    expect(opts.ipfsHash).toBe("QmTestHash123");
+    expect(opts.ipfsIp).toBe("10.0.0.1:5001");
+    expect(opts.ipfsEncrypt).toBe(1);
+    expect(opts.ipfsEncryptAlgorithm).toBe("AES/GCM/NoPadding");
+    expect(opts.ipfsEncryptKeyBytes).toEqual(keyToByteArray(fakeResult.key));
+    expect(opts.ipfsEncryptNonceSize).toBe(12);
+    expect(opts.fileType).toBe(IPFS_FILE_TYPE.IMAGE);
+  });
+
+  it("produces correct wire format for AUDIO with duration", () => {
+    const opts = service.buildMessageOptions(fakeResult, IPFS_FILE_TYPE.AUDIO, {
+      mediaDuration: 5.3,
+      fileMimeType: "audio/ogg",
+    });
+
+    expect(opts.fileType).toBe(IPFS_FILE_TYPE.AUDIO);
+    expect(opts.mediaDuration).toBe(5.3);
+    expect(opts.fileMimeType).toBe("audio/ogg");
+  });
+
+  it("produces correct wire format for FILE with name/ext", () => {
+    const opts = service.buildMessageOptions(fakeResult, IPFS_FILE_TYPE.FILE, {
+      fileName: "doc.pdf",
+      fileExt: ".pdf",
+      fileMimeType: "application/pdf",
+      fileSize: 12345,
+    });
+
+    expect(opts.fileType).toBe(IPFS_FILE_TYPE.FILE);
+    expect(opts.fileName).toBe("doc.pdf");
+    expect(opts.fileExt).toBe(".pdf");
+    expect(opts.fileMimeType).toBe("application/pdf");
+    expect(opts.fileSize).toBe(12345);
+  });
+
+  it("omits optional extra fields when not provided", () => {
+    const opts = service.buildMessageOptions(fakeResult, IPFS_FILE_TYPE.IMAGE);
+
+    expect(opts.fileMimeType).toBeUndefined();
+    expect(opts.fileName).toBeUndefined();
+    expect(opts.fileExt).toBeUndefined();
+    expect(opts.fileSize).toBeUndefined();
+    expect(opts.mediaWidth).toBeUndefined();
+    expect(opts.mediaHeight).toBeUndefined();
+    expect(opts.mediaDuration).toBeUndefined();
+  });
+
+  it("includes image dimensions when provided", () => {
+    const opts = service.buildMessageOptions(fakeResult, IPFS_FILE_TYPE.IMAGE, {
+      mediaWidth: 1920,
+      mediaHeight: 1080,
+    });
+
+    expect(opts.mediaWidth).toBe(1920);
+    expect(opts.mediaHeight).toBe(1080);
+  });
+});
+
+describe("IpfsService constructor", () => {
+  it("parses host and port from gateway string", () => {
+    const service = new IpfsService("192.168.1.1:8080");
+    const opts = service.buildMessageOptions(
+      { hash: "Qm", key: Buffer.alloc(16), nonce: Buffer.alloc(12), nonceSize: 12 },
+      IPFS_FILE_TYPE.IMAGE,
+    );
+    expect(opts.ipfsIp).toBe("192.168.1.1:8080");
+  });
+
+  it("uses default gateway when none provided", () => {
+    const service = new IpfsService();
+    const opts = service.buildMessageOptions(
+      { hash: "Qm", key: Buffer.alloc(16), nonce: Buffer.alloc(12), nonceSize: 12 },
+      IPFS_FILE_TYPE.IMAGE,
+    );
+    expect(opts.ipfsIp).toBe("64.225.88.71:80");
+  });
+});
+
+describe("encrypt → upload → download → decrypt round-trip", () => {
+  it("data survives round-trip through encryption and key serialization", () => {
+    // Simulate the full data flow without a real IPFS server:
+    // 1. Encrypt (what upload does internally)
+    const original = Buffer.from("Hello IPFS image data!");
+    const { ciphertext, key, nonce } = encryptAesGcm(original);
+
+    // 2. Serialize key to wire format (what buildMessageOptions does)
+    const wireKeyBytes = keyToByteArray(key);
+    const nonceSize = nonce.length;
+
+    // 3. Deserialize and decrypt (what download does)
+    const restoredKey = byteArrayToKey(wireKeyBytes);
+    const decrypted = decryptAesGcm(ciphertext, restoredKey, nonceSize);
+
+    expect(decrypted.toString()).toBe(original.toString());
+  });
+});
+
+describe("IpfsService HTTP error handling", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("rejects on non-200 response", async () => {
+    // Mock http.request to return a 500 response
+    const mockRes = new EventEmitter() as any;
+    mockRes.statusCode = 500;
+
+    const mockReq = new EventEmitter() as any;
+    mockReq.write = vi.fn();
+    mockReq.end = vi.fn();
+    mockReq.destroy = vi.fn();
+
+    vi.spyOn(http, "request").mockImplementation((_opts: any, callback: any) => {
+      process.nextTick(() => {
+        callback(mockRes);
+        mockRes.emit("data", Buffer.from("Internal Server Error"));
+        mockRes.emit("end");
+      });
+      return mockReq;
+    });
+
+    const service = new IpfsService("127.0.0.1:5001");
+    await expect(service.upload(Buffer.from("test"))).rejects.toThrow("IPFS HTTP 500");
+  });
+
+  it("rejects on request timeout", async () => {
+    const mockReq = new EventEmitter() as any;
+    mockReq.write = vi.fn();
+    mockReq.end = vi.fn();
+    mockReq.destroy = vi.fn();
+
+    vi.spyOn(http, "request").mockImplementation(() => {
+      process.nextTick(() => {
+        mockReq.emit("timeout");
+      });
+      return mockReq;
+    });
+
+    const service = new IpfsService("127.0.0.1:5001");
+    await expect(service.upload(Buffer.from("test"))).rejects.toThrow("IPFS request timed out");
+  });
+
+  it("rejects on connection error", async () => {
+    const mockReq = new EventEmitter() as any;
+    mockReq.write = vi.fn();
+    mockReq.end = vi.fn();
+    mockReq.destroy = vi.fn();
+
+    vi.spyOn(http, "request").mockImplementation(() => {
+      process.nextTick(() => {
+        mockReq.emit("error", new Error("ECONNREFUSED"));
+      });
+      return mockReq;
+    });
+
+    const service = new IpfsService("127.0.0.1:5001");
+    await expect(service.upload(Buffer.from("test"))).rejects.toThrow("ECONNREFUSED");
+  });
+
+  it("download rejects on non-200 response", async () => {
+    const mockRes = new EventEmitter() as any;
+    mockRes.statusCode = 404;
+
+    const mockReq = new EventEmitter() as any;
+    mockReq.write = vi.fn();
+    mockReq.end = vi.fn();
+    mockReq.destroy = vi.fn();
+
+    vi.spyOn(http, "request").mockImplementation((_opts: any, callback: any) => {
+      process.nextTick(() => {
+        callback(mockRes);
+        mockRes.emit("data", Buffer.from("not found"));
+        mockRes.emit("end");
+      });
+      return mockReq;
+    });
+
+    const service = new IpfsService("127.0.0.1:5001");
+    await expect(
+      service.download("QmMissing", { encrypt: 1, encryptKeyBytes: Array.from(Buffer.alloc(16)), encryptNonceSize: 12 }),
+    ).rejects.toThrow("IPFS HTTP 404");
+  });
+});
+
+describe("buildFileMetadata", () => {
+  it("extracts extension from fileName", () => {
+    const result = buildFileMetadata({
+      buffer: Buffer.from("pdf content"),
+      contentType: "application/pdf",
+      fileName: "report.pdf",
+    });
+    expect(result.fileName).toBe("report.pdf");
+    expect(result.fileExt).toBe("pdf");
+    expect(result.fileSize).toBe(11);
+  });
+
+  it("derives extension from MIME when fileName has no extension", () => {
+    const result = buildFileMetadata({
+      buffer: Buffer.from("data"),
+      contentType: "application/pdf",
+      fileName: "report",
+    });
+    expect(result.fileName).toBe("report.pdf");
+    expect(result.fileExt).toBe("pdf");
+  });
+
+  it("derives extension from MIME when no fileName", () => {
+    const result = buildFileMetadata({
+      buffer: Buffer.from("data"),
+      contentType: "image/png",
+    });
+    expect(result.fileName).toBe("file.png");
+    expect(result.fileExt).toBe("png");
+  });
+
+  it("falls back to bin for unknown MIME and no fileName", () => {
+    const result = buildFileMetadata({
+      buffer: Buffer.from("data"),
+      contentType: "application/x-unknown",
+    });
+    expect(result.fileName).toBe("file.bin");
+    expect(result.fileExt).toBe("bin");
+  });
+
+  it("handles docx MIME type", () => {
+    const result = buildFileMetadata({
+      buffer: Buffer.from("docx"),
+      contentType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      fileName: "letter.docx",
+    });
+    expect(result.fileExt).toBe("docx");
+    expect(result.fileName).toBe("letter.docx");
+  });
+
+  it("prefers fileName extension over MIME", () => {
+    const result = buildFileMetadata({
+      buffer: Buffer.from("data"),
+      contentType: "application/octet-stream",
+      fileName: "archive.tar.gz",
+    });
+    expect(result.fileExt).toBe("gz");
+    expect(result.fileName).toBe("archive.tar.gz");
+  });
+});

package/src/ipfs.ts

@@ -0,0 +1,268 @@
+import http from "http";
+import https from "https";
+import { encryptAesGcm, decryptAesGcm, keyToByteArray, byteArrayToKey } from "./crypto.js";
+import type { MessageOptions } from "./types.js";
+
+/** IPFS file type constants matching nMobile wire format. */
+export const IPFS_FILE_TYPE = {
+  FILE: 0,
+  IMAGE: 1,
+  AUDIO: 2,
+  VIDEO: 3,
+} as const;
+
+/** Map a MIME type string to an nMobile IPFS file type number. */
+export function mimeToIpfsFileType(mime?: string): number {
+  if (!mime) return IPFS_FILE_TYPE.IMAGE; // default to image
+  const lower = mime.toLowerCase();
+  if (lower.startsWith("image/")) return IPFS_FILE_TYPE.IMAGE;
+  if (lower.startsWith("audio/")) return IPFS_FILE_TYPE.AUDIO;
+  if (lower.startsWith("video/")) return IPFS_FILE_TYPE.VIDEO;
+  return IPFS_FILE_TYPE.FILE;
+}
+
+/** Common MIME → extension mappings for file transfers. */
+const MIME_TO_EXT: Record<string, string> = {
+  "application/pdf": "pdf",
+  "application/zip": "zip",
+  "application/x-zip-compressed": "zip",
+  "application/msword": "doc",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx",
+  "application/vnd.ms-excel": "xls",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "xlsx",
+  "application/vnd.ms-powerpoint": "ppt",
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation": "pptx",
+  "text/plain": "txt",
+  "text/csv": "csv",
+  "text/html": "html",
+  "application/json": "json",
+  "application/xml": "xml",
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/gif": "gif",
+  "image/webp": "webp",
+  "audio/aac": "aac",
+  "audio/mpeg": "mp3",
+  "audio/ogg": "ogg",
+  "audio/wav": "wav",
+  "video/mp4": "mp4",
+  "video/webm": "webm",
+};
+
+/**
+ * Build file metadata (fileName, fileExt, fileSize) for outbound media.
+ * Derives extension from the original filename or MIME type.
+ */
+export function buildFileMetadata(media: {
+  buffer: Buffer;
+  contentType?: string;
+  fileName?: string;
+}): { fileName: string; fileExt: string; fileSize: number } {
+  let ext: string | undefined;
+  let name = media.fileName;
+
+  // Try to get extension from filename
+  if (name) {
+    const dotIdx = name.lastIndexOf(".");
+    if (dotIdx > 0) {
+      ext = name.substring(dotIdx + 1).toLowerCase();
+    }
+  }
+
+  // Fall back to MIME type
+  if (!ext && media.contentType) {
+    ext = MIME_TO_EXT[media.contentType.toLowerCase()];
+  }
+
+  ext = ext || "bin";
+
+  // Ensure filename has extension
+  if (!name) {
+    name = `file.${ext}`;
+  } else if (!name.includes(".")) {
+    name = `${name}.${ext}`;
+  }
+
+  return { fileName: name, fileExt: ext, fileSize: media.buffer.length };
+}
+
+export interface IpfsUploadResult {
+  hash: string;
+  key: Buffer;
+  nonce: Buffer;
+  nonceSize: number;
+}
+
+const DEFAULT_TIMEOUT = 60_000;
+
+/**
+ * IPFS service for uploading/downloading encrypted media
+ * via an IPFS HTTP API gateway (compatible with nMobile).
+ */
+export class IpfsService {
+  private host: string;
+  private port: number;
+  private protocol: "http" | "https";
+
+  constructor(gateway?: string) {
+    const gw = gateway ?? "64.225.88.71:80";
+    const parts = gw.split(":");
+    this.host = parts[0];
+    this.port = parseInt(parts[1] ?? "80", 10);
+    this.protocol = this.port === 443 ? "https" : "http";
+  }
+
+  /**
+   * Encrypt plaintext with AES-128-GCM, then upload to IPFS via /api/v0/add.
+   */
+  async upload(plaintext: Buffer): Promise<IpfsUploadResult> {
+    const { ciphertext, key, nonce } = encryptAesGcm(plaintext);
+
+    const boundary = "----IpfsBoundary" + Date.now().toString(36);
+    const fieldName = "file";
+    const fileName = "upload";
+
+    // Build multipart form-data manually
+    const header = Buffer.from(
+      `--${boundary}\r\n` +
+        `Content-Disposition: form-data; name="${fieldName}"; filename="${fileName}"\r\n` +
+        `Content-Type: application/octet-stream\r\n\r\n`,
+    );
+    const footer = Buffer.from(`\r\n--${boundary}--\r\n`);
+    const body = Buffer.concat([header, ciphertext, footer]);
+
+    const responseBody = await this._request("POST", "/api/v0/add", body, {
+      "Content-Type": `multipart/form-data; boundary=${boundary}`,
+    });
+
+    const result = JSON.parse(responseBody);
+    const hash = result.Hash;
+    if (!hash) {
+      throw new Error(`IPFS add response missing Hash: ${responseBody}`);
+    }
+
+    return { hash, key, nonce, nonceSize: nonce.length };
+  }
+
+  /**
+   * Download from IPFS via /api/v0/cat, then decrypt with AES-128-GCM.
+   */
+  async download(
+    hash: string,
+    encryptOpts: {
+      encrypt?: number;
+      encryptKeyBytes?: number[];
+      encryptNonceSize?: number;
+    },
+  ): Promise<Buffer> {
+    const responseBody = await this._requestRaw("POST", `/api/v0/cat?arg=${hash}`);
+
+    if (!encryptOpts.encrypt || !encryptOpts.encryptKeyBytes) {
+      // Not encrypted — return raw
+      return responseBody;
+    }
+
+    const key = byteArrayToKey(encryptOpts.encryptKeyBytes);
+    const nonceSize = encryptOpts.encryptNonceSize ?? 12;
+    return decryptAesGcm(responseBody, key, nonceSize);
+  }
+
+  /**
+   * Build nMobile-compatible MessageOptions from an upload result.
+   */
+  buildMessageOptions(
+    uploadResult: IpfsUploadResult,
+    fileType: number,
+    extra?: {
+      fileMimeType?: string;
+      fileName?: string;
+      fileExt?: string;
+      fileSize?: number;
+      mediaWidth?: number;
+      mediaHeight?: number;
+      mediaDuration?: number;
+    },
+  ): MessageOptions {
+    const options: MessageOptions = {
+      ipfsHash: uploadResult.hash,
+      ipfsIp: `${this.host}:${this.port}`,
+      ipfsEncrypt: 1,
+      ipfsEncryptAlgorithm: "AES/GCM/NoPadding",
+      ipfsEncryptKeyBytes: keyToByteArray(uploadResult.key),
+      ipfsEncryptNonceSize: uploadResult.nonceSize,
+      fileType,
+    };
+
+    if (extra?.fileMimeType) options.fileMimeType = extra.fileMimeType;
+    if (extra?.fileName) options.fileName = extra.fileName;
+    if (extra?.fileExt) options.fileExt = extra.fileExt;
+    if (extra?.fileSize !== undefined) options.fileSize = extra.fileSize;
+    if (extra?.mediaWidth !== undefined) options.mediaWidth = extra.mediaWidth;
+    if (extra?.mediaHeight !== undefined) options.mediaHeight = extra.mediaHeight;
+    if (extra?.mediaDuration !== undefined) options.mediaDuration = extra.mediaDuration;
+
+    return options;
+  }
+
+  /** HTTP request returning text response. */
+  private _request(
+    method: string,
+    path: string,
+    body?: Buffer,
+    headers?: Record<string, string>,
+  ): Promise<string> {
+    return this._requestRaw(method, path, body, headers).then((buf) => buf.toString("utf-8"));
+  }
+
+  /** HTTP request returning raw Buffer response. */
+  private _requestRaw(
+    method: string,
+    path: string,
+    body?: Buffer,
+    headers?: Record<string, string>,
+  ): Promise<Buffer> {
+    const transport = this.protocol === "https" ? https : http;
+
+    return new Promise<Buffer>((resolve, reject) => {
+      const req = transport.request(
+        {
+          hostname: this.host,
+          port: this.port,
+          path,
+          method,
+          headers: {
+            ...headers,
+            ...(body ? { "Content-Length": body.length.toString() } : {}),
+          },
+          timeout: DEFAULT_TIMEOUT,
+        },
+        (res) => {
+          const chunks: Buffer[] = [];
+          res.on("data", (chunk: Buffer) => chunks.push(chunk));
+          res.on("end", () => {
+            const result = Buffer.concat(chunks);
+            if (res.statusCode && (res.statusCode < 200 || res.statusCode >= 300)) {
+              reject(
+                new Error(
+                  `IPFS HTTP ${res.statusCode}: ${result.toString("utf-8").slice(0, 200)}`,
+                ),
+              );
+              return;
+            }
+            resolve(result);
+          });
+          res.on("error", reject);
+        },
+      );
+
+      req.on("timeout", () => {
+        req.destroy();
+        reject(new Error("IPFS request timed out"));
+      });
+      req.on("error", reject);
+
+      if (body) req.write(body);
+      req.end();
+    });
+  }
+}

package/src/wire.test.ts

@@ -8,6 +8,7 @@ import {
   isControlMessage,
   isDisplayableMessage,
   nknToInbound,
+  parseInlineMediaDataUri,
   parseNknPayload,
   receiptToNkn,
   stripNknSubClientPrefix,
@@ -172,6 +173,65 @@ describe("nknToInbound", () => {
     expect(result!.body).toBe("[Voice Message]");
   });
 
+  it("extracts IPFS hash from audio message with options.ipfsHash", () => {
+    const msg: MessageData = {
+      id: "msg-audio-ipfs-1",
+      contentType: "audio",
+      content: "QmAudioHash...",
+      options: {
+        ipfsHash: "QmAudioHash...",
+        ipfsEncrypt: 1,
+        ipfsEncryptAlgorithm: "AES/GCM/NoPadding",
+        ipfsEncryptKeyBytes: Array.from(Buffer.alloc(16, 0xab)),
+        ipfsEncryptNonceSize: 12,
+        fileType: 2,
+        mediaDuration: 5.3,
+      },
+      timestamp: Date.now(),
+    };
+    const result = nknToInbound("sender", msg, selfAddr);
+    expect(result!.body).toBe("[Voice Message]");
+    expect(result!.ipfsHash).toBe("QmAudioHash...");
+    expect(result!.ipfsOptions).toBeDefined();
+    expect(result!.ipfsOptions!.ipfsEncrypt).toBe(1);
+    expect(result!.ipfsOptions!.mediaDuration).toBe(5.3);
+  });
+
+  it("extracts IPFS hash from audio message content when options.ipfsHash is missing", () => {
+    const msg: MessageData = {
+      id: "msg-audio-ipfs-2",
+      contentType: "audio",
+      content: "QmAudioContentHash",
+      options: {
+        ipfsEncrypt: 1,
+        ipfsEncryptKeyBytes: Array.from(Buffer.alloc(16, 0xcd)),
+        ipfsEncryptNonceSize: 12,
+      },
+      timestamp: Date.now(),
+    };
+    const result = nknToInbound("sender", msg, selfAddr);
+    expect(result!.ipfsHash).toBe("QmAudioContentHash");
+    expect(result!.ipfsOptions).toBeDefined();
+  });
+
+  it("translates IPFS audio message (contentType ipfs, fileType 2)", () => {
+    const msg: MessageData = {
+      id: "msg-ipfs-audio",
+      contentType: "ipfs",
+      content: "QmIpfsAudio...",
+      options: {
+        ipfsHash: "QmIpfsAudio...",
+        fileType: 2,
+        mediaDuration: 12.5,
+      },
+      timestamp: Date.now(),
+    };
+    const result = nknToInbound("sender", msg, selfAddr);
+    expect(result!.body).toBe("[Audio]");
+    expect(result!.ipfsHash).toBe("QmIpfsAudio...");
+    expect(result!.ipfsOptions!.mediaDuration).toBe(12.5);
+  });
+
   it("returns null for control messages", () => {
     const receipt: MessageData = {
       id: "msg-6",
@@ -264,3 +324,74 @@ describe("stripNknSubClientPrefix", () => {
     expect(stripNknSubClientPrefix("cd3530abcdef")).toBe("cd3530abcdef");
   });
 });
+
+describe("parseInlineMediaDataUri", () => {
+  it("parses D-Chat markdown audio data-URI (audio/x-aac)", () => {
+    const raw = "![audio](data:audio/x-aac;base64,AAAA)";
+    const result = parseInlineMediaDataUri(raw);
+    expect(result).not.toBeNull();
+    expect(result!.mime).toBe("audio/x-aac");
+    expect(result!.buffer).toEqual(Buffer.from("AAAA", "base64"));
+  });
+
+  it("parses nMobile markdown audio data-URI (audio/aac)", () => {
+    const b64 = Buffer.from("hello audio").toString("base64");
+    const raw = `![audio](data:audio/aac;base64,${b64})`;
+    const result = parseInlineMediaDataUri(raw);
+    expect(result).not.toBeNull();
+    expect(result!.mime).toBe("audio/aac");
+    expect(result!.buffer.toString()).toBe("hello audio");
+  });
+
+  it("parses raw data-URI without markdown wrapper", () => {
+    const b64 = Buffer.from("raw data").toString("base64");
+    const raw = `data:audio/ogg;base64,${b64}`;
+    const result = parseInlineMediaDataUri(raw);
+    expect(result).not.toBeNull();
+    expect(result!.mime).toBe("audio/ogg");
+    expect(result!.buffer.toString()).toBe("raw data");
+  });
+
+  it("returns null for non-data-URI content", () => {
+    expect(parseInlineMediaDataUri("QmSomeIpfsHash")).toBeNull();
+    expect(parseInlineMediaDataUri("just plain text")).toBeNull();
+    expect(parseInlineMediaDataUri("")).toBeNull();
+  });
+
+  it("returns null for invalid base64", () => {
+    expect(parseInlineMediaDataUri("data:audio/aac;utf8,notbase64")).toBeNull();
+  });
+});
+
+describe("nknToInbound — inline audio", () => {
+  const selfAddr = "self-address-abc123";
+
+  it("sets inlineMediaDataUri for audio with data-URI content", () => {
+    const b64 = Buffer.from("aac-audio-data").toString("base64");
+    const msg: MessageData = {
+      id: "msg-voice-1",
+      contentType: "audio",
+      content: `![audio](data:audio/x-aac;base64,${b64})`,
+      options: { fileType: 2, fileExt: "aac", mediaDuration: 3.5 },
+      timestamp: Date.now(),
+    };
+    const result = nknToInbound("sender", msg, selfAddr);
+    expect(result!.body).toBe("[Voice Message]");
+    expect(result!.inlineMediaDataUri).toBe(msg.content);
+    // ipfsHash should also be set as fallback (content contains "data:" but also matches)
+    // but IPFS download will fail gracefully — inline path takes priority in channel.ts
+  });
+
+  it("does not set inlineMediaDataUri for audio without data-URI", () => {
+    const msg: MessageData = {
+      id: "msg-voice-2",
+      contentType: "audio",
+      content: "QmSomeHash",
+      options: { ipfsHash: "QmSomeHash" },
+      timestamp: Date.now(),
+    };
+    const result = nknToInbound("sender", msg, selfAddr);
+    expect(result!.inlineMediaDataUri).toBeUndefined();
+    expect(result!.ipfsHash).toBe("QmSomeHash");
+  });
+});

package/src/wire.ts

@@ -59,6 +59,8 @@ export interface InboundMessageResult {
   groupSubject?: string;
   ipfsHash?: string;
   ipfsOptions?: MessageOptions;
+  /** Raw inline media data-URI (e.g. "![audio](data:audio/aac;base64,...)") for voice messages. */
+  inlineMediaDataUri?: string;
 }
 
 /**
@@ -141,11 +143,36 @@ export function nknToInbound(
     senderId: src,
     senderName,
     groupSubject,
-    ipfsHash: msg.options?.ipfsHash || (ct === "ipfs" ? msg.content : undefined),
+    ipfsHash:
+      msg.options?.ipfsHash || (ct === "ipfs" || ct === "audio" ? msg.content : undefined),
     ipfsOptions: ct === "ipfs" || ct === "audio" ? msg.options : undefined,
+    // D-Chat/nMobile send voice messages inline as base64 data-URI in content
+    inlineMediaDataUri:
+      ct === "audio" && msg.content?.includes("data:") ? msg.content : undefined,
   };
 }
 
+/**
+ * Parse an inline media data-URI from nMobile/D-Chat format.
+ * Handles: "![audio](data:audio/aac;base64,...)" and raw "data:audio/aac;base64,..."
+ * Returns { mime, buffer } or null if not a valid data-URI.
+ */
+export function parseInlineMediaDataUri(
+  raw: string,
+): { mime: string; buffer: Buffer } | null {
+  // Extract data-URI from markdown image syntax: ![...](data:...)
+  const mdMatch = raw.match(/!\[.*?\]\((data:[^)]+)\)/);
+  const dataUri = mdMatch ? mdMatch[1] : raw.startsWith("data:") ? raw : null;
+  if (!dataUri) return null;
+
+  const match = dataUri.match(/^data:([^;]+);base64,(.+)$/s);
+  if (!match) return null;
+
+  const mime = match[1];
+  const buffer = Buffer.from(match[2], "base64");
+  return { mime, buffer };
+}
+
 /**
  * Build an outbound NKN MessageData from text.
  * Sets appropriate content type and topic/groupId fields.