@eryxenx/fca 1.0.0

package/src/api/socket/e2ee/index.js

@@ -0,0 +1,925 @@
+"use strict";
+
+/**
+ * NEXCA E2EE Bridge — Signal Protocol + Noise WebSocket
+ *
+ * Wraps the `fb-messenger-e2ee` npm package (real dependency, not a bundled
+ * vendor copy) and exposes it through NEXCA's own api.e2ee / connectE2EE /
+ * listenE2EE surface, so the rest of fca-eryxenx and GoatBot never need to
+ * know which E2EE engine is underneath.
+ *
+
+ * Full protocol stack:
+ *   • @signalapp/libsignal-client — Signal Protocol (Double Ratchet)
+ *   • Noise_XX_25519_AESGCM_SHA256 WebSocket handshake
+ *   • WA-binary + Protobuf message encoding
+ *   • ICDC device registration with Facebook
+ */
+
+const path = require("path");
+const logger = require("../../../utils/nexca-logger");
+const nativeMediaBridge = require("./native/nativeMediaBridge");
+const { decodeIncomingMedia } = require("./mediaDecode");
+const localMediaServer = require("./localMediaServer");
+
+// Simple FIFO-bounded Map.set — evicts the oldest entry once maxSize is
+// exceeded, so long-lived per-message caches (media buffers, thread/sender
+// lookups) can't grow unbounded over a multi-hour/overnight process
+// lifetime and eventually get OOM-killed.
+function boundedSet(map, key, value, maxSize) {
+    if (map.size >= maxSize && !map.has(key)) {
+        const oldestKey = map.keys().next().value;
+        map.delete(oldestKey);
+    }
+    map.set(key, value);
+    return map;
+}
+
+function loadFBClient() {
+    try {
+        // Pre-compiled from HerokeyVN/FB-Messenger-E2EE (fb-messenger-e2ee).
+        // Compiled ahead of time (esbuild, CJS, node16 target) and committed
+        // directly here because:
+        //   1. fb-messenger-e2ee is NOT published on the npm registry — only
+        //      available as TypeScript source on GitHub.
+        //   2. Depending on it as a git/file dependency nested inside
+        //      fca-eryxenx (itself installed via `github:` in GoatBot-Pro)
+        //      is unreliable — npm does not consistently build nested
+        //      non-registry dependencies during a git-dependency install.
+        // Shipping plain compiled JS here means zero build step is needed
+        // at install time — just `require()`.
+        return require("./vendor/fme/dist/index.cjs").FBClient;
+    } catch (err) {
+        throw new Error(
+            "E2EE engine (vendor/fme) failed to load.\n" +
+            "  Make sure these are installed: @noble/curves, @noble/hashes,\n" +
+            "  @signalapp/libsignal-client, protobufjs, ws, fca-unofficial\n" +
+            "  Cause: " + err.message
+        );
+    }
+}
+
+class E2EEBridge {
+    constructor(ctx, api, defaultFuncs) {
+        this.ctx = ctx;
+        this.api = api;
+        this.defaultFuncs = defaultFuncs || null;
+        this.client = null;
+        this.connected = false;
+        this._messageCallback = null;
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Setup
+    // ─────────────────────────────────────────────────────────────────────────
+
+    async connect(deviceStorePath, userId) {
+        // Guard against concurrent/duplicate connect() calls (e.g. bot code
+        // calling api.connectE2EE() explicitly while auto-connect is also
+        // running) — without this, two parallel connects race and corrupt
+        // `this.client`, causing undefined responses downstream.
+        if (this._connectPromise) return this._connectPromise;
+        if (this.connected) return Promise.resolve({ userId: this.ctx.userID });
+
+        this._connectPromise = this._doConnect(deviceStorePath, userId)
+            .catch((err) => {
+                this._connectPromise = null;
+                throw err;
+            });
+        return this._connectPromise;
+    }
+
+    async _doConnect(deviceStorePath, userId) {
+        const fs = require("fs");
+
+        userId = userId || this.ctx.userID;
+
+        // Default to .nexca/e2ee_device.json in the user's project directory
+        if (!deviceStorePath) {
+            deviceStorePath = path.join(process.cwd(), ".nexca", "e2ee_device.json");
+        }
+
+        // Auto-create parent directory — users don't need to create it manually
+        try {
+            fs.mkdirSync(path.dirname(deviceStorePath), { recursive: true });
+        } catch (_) {}
+
+        logger.info("E2EE", "Device store: " + deviceStorePath);
+
+        const FBClient = loadFBClient();
+
+        // Re-use the already-loaded session from NEXCA's cookie jar.
+        // fb-messenger-e2ee accepts an in-memory appState directly (array or
+        // cookie string) and does its own independent fca-unofficial login
+        // internally to derive the CAT/bootstrap material E2EE needs. This is
+        // the library's documented, supported flow — it runs alongside NEXCA's
+        // own MQTT session without conflict (separate login call, same cookies).
+        const appState = this.api.getAppState();
+
+        this.client = new FBClient({
+            appState,
+            platform: "facebook",
+        });
+
+        logger.info("E2EE", "Bootstrapping auth via fb-messenger-e2ee (appState login)...");
+        const connectResult = await this.client.connect();
+        const resolvedUserId = connectResult && connectResult.userId;
+
+        logger.info("E2EE", "Opening Noise WebSocket (Signal Protocol)...");
+        const _e2eeDevicePath = deviceStorePath;
+        const _e2eeUserId     = resolvedUserId || userId;
+        await this.client.connectE2EE(_e2eeDevicePath, _e2eeUserId);
+
+        // Auto-reconnect the Noise WebSocket whenever it drops unexpectedly.
+        // `this.connected` stays true through reconnect cycles; it's only set
+        // false by an explicit api.e2ee.disconnect() call.
+        const _self = this;
+        this.client.onEvent("disconnected", function _onE2EEDisconnected() {
+            if (!_self.connected) return; // intentional disconnect — skip
+            logger.warn("E2EE", "Noise WebSocket disconnected — reconnecting in 5s...");
+            setTimeout(async function () {
+                if (!_self.connected) return;
+                try {
+                    await _self.client.connectE2EE(_e2eeDevicePath, _e2eeUserId);
+                    logger.success("E2EE", "E2EE WebSocket reconnected.");
+                } catch (err) {
+                    logger.error("E2EE", "E2EE reconnect failed: " + (err && err.message ? err.message : String(err)));
+                    // Retry again after another 10s if reconnect failed
+                    if (_self.connected) {
+                        setTimeout(async function () {
+                            if (!_self.connected) return;
+                            try {
+                                await _self.client.connectE2EE(_e2eeDevicePath, _e2eeUserId);
+                                logger.success("E2EE", "E2EE WebSocket reconnected (retry).");
+                            } catch (err2) {
+                                logger.error("E2EE", "E2EE reconnect retry failed: " + (err2 && err2.message ? err2.message : String(err2)));
+                            }
+                        }, 10000);
+                    }
+                }
+            }, 5000);
+        });
+
+        // Forward incoming E2EE messages to the registered callback.
+        this.client.onEvent("e2ee_message", async (msg) => {
+            this._senderJidMap = this._senderJidMap || new Map();
+            this._mediaCache = this._mediaCache || new Map();
+            this._msgThreadMap = this._msgThreadMap || new Map();
+            this._msgTextCache = this._msgTextCache || new Map();
+            if (msg.id) boundedSet(this._senderJidMap, String(msg.id), msg.senderJid || null, 500);
+            if (msg.id && msg.text) boundedSet(this._msgTextCache, String(msg.id), String(msg.text), 500);
+
+            if (msg.kind && msg.kind !== "text" && msg.media) {
+                try {
+                    const meta = decodeIncomingMedia(msg.kind, msg.media);
+                    if (meta) boundedSet(this._mediaCache, String(msg.id), meta, 50);
+                } catch (err) {
+                    logger.error("E2EE", "[media-decode] failed to decode incoming " + msg.kind + ": " +
+                        (err && err.message ? err.message : String(err)));
+                }
+            }
+
+            if (!this._messageCallback) return;
+
+            const senderID =
+                msg.senderId ||
+                (typeof msg.senderJid === "string" ? msg.senderJid.split(".")[0] : "");
+
+            // GoatBot (handlerEvents.js, threadsData, etc.) expects plain
+            // numeric threadIDs everywhere — DB lookups, isNaN() checks, etc.
+            // FME group threads arrive as "<id>@g.us" (WA-binary JID style),
+            // which breaks those checks and crashes handlerEvents.js. Strip
+            // any "@..." suffix so downstream code sees a plain numeric ID.
+            function normalizeThreadId(id) {
+                if (typeof id !== "string") return id;
+                var at = id.indexOf("@");
+                return at === -1 ? id : id.slice(0, at);
+            }
+            const normalizedThreadId = normalizeThreadId(msg.threadId);
+            this._knownE2EEThreads = this._knownE2EEThreads || new Set();
+            this._knownE2EEThreads.add(normalizedThreadId);
+            if (msg.id) boundedSet(this._msgThreadMap, String(msg.id), normalizedThreadId, 500);
+            if (msg.replyTo && msg.replyTo.messageId) boundedSet(this._msgThreadMap, String(msg.replyTo.messageId), normalizedThreadId, 500);
+
+            // Build mentions: vendor surfaces an array [{ id, text }] or object
+            var mentions = {};
+            if (Array.isArray(msg.mentions)) {
+                msg.mentions.forEach(function(m) {
+                    if (m && m.id) mentions[m.id] = m.text || "@" + m.id;
+                });
+            } else if (msg.mentions && typeof msg.mentions === "object") {
+                mentions = msg.mentions;
+            }
+
+            const isReply = !!(msg.replyTo && msg.replyTo.messageId);
+            if (isReply) {
+                try {
+                    console.log("[E2EE-DEBUG] msg.replyTo raw:", JSON.stringify(msg.replyTo, (k, v) => typeof v === "bigint" ? v.toString() : Buffer.isBuffer(v) ? `<Buffer ${v.length}b>` : v));
+                } catch (_) { console.log("[E2EE-DEBUG] msg.replyTo (raw, non-serializable):", msg.replyTo); }
+            }
+            if (msg.kind && msg.kind !== "text") {
+                try {
+                    console.log("[E2EE-DEBUG] msg.kind=" + msg.kind + " msg.media keys:", msg.media ? Object.keys(msg.media) : null);
+                } catch (_) {}
+            }
+            if (msg.kind === "reaction") {
+                try {
+                    console.log("[E2EE-DEBUG] FULL reaction msg dump:", JSON.stringify(msg, (k, v) => typeof v === "bigint" ? v.toString() : Buffer.isBuffer(v) ? `<Buffer ${v.length}b>` : v, 2));
+                } catch (_) { console.log("[E2EE-DEBUG] FULL reaction msg (non-serializable):", msg); }
+
+                this._messageCallback(null, {
+                    type: "message_reaction",
+                    threadID: normalizedThreadId,
+                    messageID: msg.targetId,
+                    reaction: msg.reaction,
+                    senderID: msg.senderId || senderID,
+                    userID: msg.senderId || senderID,
+                    isE2EE: true
+                });
+                return;
+            }
+
+            const event = {
+                type:        isReply ? "message_reply" : "message",
+                senderID,
+                threadID:    normalizedThreadId,
+                body:        msg.text || "",
+                isE2EE:      true,
+                isGroup:     !!msg.isGroup,
+                timestamp:   msg.timestampMs || Date.now(),
+                messageID:   msg.id || "",
+                attachments: [],
+                mentions,
+                args:        (msg.text || "").trim().split(/\s+/).filter(Boolean),
+            };
+
+            // Populate ctx.threadTypes so that sendMessage.js can detect this
+            // as a DM and route attachments through OldMessage (not MQTT).
+            // E2EE DM messages arrive via the Noise WebSocket — not MQTT — so
+            // parseDelta never sees them and ctx.threadTypes stays empty unless
+            // we populate it here.
+            if (!event.isGroup && normalizedThreadId) {
+                this.ctx.threadTypes = this.ctx.threadTypes || {};
+                this.ctx.threadTypes[String(normalizedThreadId)] = 'dm';
+            }
+
+            // Eagerly resolve any E2EE media on this message itself.
+            const ownMeta = this._mediaCache.get(String(msg.id));
+            if (ownMeta) {
+                try {
+                    const url = await this.resolveAttachment(ownMeta);
+                    event.attachments = [{
+                        type: ownMeta.kind === "image" ? "photo" : ownMeta.kind === "video" ? "video" : ownMeta.kind === "audio" ? "audio" : "file",
+                        ID: event.messageID,
+                        url,
+                        isE2EE: true,
+                        filename: ownMeta.fileName,
+                        width: ownMeta.width,
+                        height: ownMeta.height
+                    }];
+                } catch (err) {
+                    logger.error("E2EE", "[media-resolve] failed to resolve own attachment: " + (err && err.message ? err.message : String(err)));
+                }
+            }
+
+            // Populate messageReply so reply handlers work the same as in MQTT
+            if (isReply) {
+                const replyText = msg.replyTo.text || this._msgTextCache.get(String(msg.replyTo.messageId)) || "";
+                event.messageReply = {
+                    messageID: msg.replyTo.messageId,
+                    senderID:  msg.replyTo.senderId || "",
+                    threadID:  normalizedThreadId,
+                    body:      replyText,
+                    args:      replyText.trim().split(/\s+/).filter(Boolean),
+                    isE2EE:    true,
+                    isGroup:   !!msg.isGroup,
+                    mentions:  {},
+                    attachments: []
+                };
+
+                // Resolve the ORIGINAL message's media (if any) from cache — this
+                // is what makes reply-based commands like imgur.js work in E2EE.
+                const repliedMeta = this._mediaCache.get(String(msg.replyTo.messageId));
+                if (repliedMeta) {
+                    try {
+                        const url = await this.resolveAttachment(repliedMeta);
+                        event.messageReply.attachments = [{
+                            type: repliedMeta.kind === "image" ? "photo" : repliedMeta.kind === "video" ? "video" : repliedMeta.kind === "audio" ? "audio" : "file",
+                            ID: msg.replyTo.messageId,
+                            url,
+                            isE2EE: true,
+                            filename: repliedMeta.fileName,
+                            width: repliedMeta.width,
+                            height: repliedMeta.height
+                        }];
+                    } catch (err) {
+                        logger.error("E2EE", "[media-resolve] failed to resolve replied attachment: " + (err && err.message ? err.message : String(err)));
+                    }
+                }
+            }
+
+            this._messageCallback(null, event);
+        });
+
+        // Incoming E2EE reactions — needed for onReaction handlers (e.g. a
+        // reaction-triggered unsend feature) to fire in encrypted threads.
+        this.client.onEvent("e2ee_reaction", (r) => {
+            console.log("[E2EE-DEBUG] e2ee_reaction fired:", JSON.stringify(r, (k, v) => typeof v === "bigint" ? v.toString() : v));
+            if (!this._messageCallback) return;
+            const threadID = r.chatJid ? String(r.chatJid).split("@")[0].split(".")[0] : "";
+            const senderID = r.senderId || (r.senderJid ? String(r.senderJid).split(".")[0] : "");
+            this._messageCallback(null, {
+                type: "message_reaction",
+                threadID,
+                messageID: r.messageId,
+                reaction: r.reaction,
+                senderID,
+                userID: senderID,
+                isE2EE: true
+            });
+        });
+
+        // (Removed: catch-all debug event logger. It served its purpose while
+        // discovering the native engine's event shapes — message, typing,
+        // reaction, message_unsend, read_receipt, e2ee_receipt, presence are
+        // all known now. Leaving it running printed thousands of lines/hour
+        // for every typing indicator across all active threads, which added
+        // unnecessary CPU/memory overhead over a multi-hour uptime.)
+
+        // Surface connection errors so the bot log shows them.
+        // Silently ignore DuplicatedMessage errors — these are harmless replays on reconnect.
+        this.client.onEvent("error", (err) => {
+            if (err && (err.code === 1 || (err.message && err.message.includes("old counter")))) return;
+            logger.error("E2EE", "E2EE error: " + (err && err.message ? err.message : String(err)));
+        });
+
+        this.connected = true;
+        logger.success("E2EE", "E2EE active — Signal Protocol / Noise WebSocket (vendored)");
+
+        // Diagnostic: log memory + internal cache sizes every 10 min so a
+        // future OOM can be correlated against actual growth data instead of
+        // guessing which structure is leaking.
+        if (!this._memDiagInterval) {
+            this._memDiagInterval = setInterval(() => {
+                try {
+                    const mem = process.memoryUsage();
+                    const fmtMB = (b) => (b / 1024 / 1024).toFixed(1) + "MB";
+                    console.log(`[MEM-DIAG] rss=${fmtMB(mem.rss)} heapUsed=${fmtMB(mem.heapUsed)} heapTotal=${fmtMB(mem.heapTotal)} external=${fmtMB(mem.external)} arrayBuffers=${fmtMB(mem.arrayBuffers || 0)}`);
+                    console.log(`[MEM-DIAG] caches: mediaCache=${this._mediaCache ? this._mediaCache.size : 0} msgThreadMap=${this._msgThreadMap ? this._msgThreadMap.size : 0} msgTextCache=${this._msgTextCache ? this._msgTextCache.size : 0} senderJidMap=${this._senderJidMap ? this._senderJidMap.size : 0} seenGroupMsgIds=${this._seenGroupMsgIds ? this._seenGroupMsgIds.size : 0} knownThreads=${this._knownE2EEThreads ? this._knownE2EEThreads.size : 0} knownGroups=${this._knownE2EEGroups ? this._knownE2EEGroups.size : 0} localMediaServerCache=${localMediaServer.getCacheSize()}`);
+                } catch (err) {
+                    console.log("[MEM-DIAG] logging failed:", err && err.message ? err.message : err);
+                }
+            }, 10 * 60 * 1000);
+            this._memDiagInterval.unref();
+        }
+
+        // GROUP E2EE only: the vendor engine's own group Sender-Key decrypt
+        // has an unresolved bug (repeated "missing sender key state" /
+        // "ciphertext version too old" errors). The native mautrix-go engine
+        // decrypts these correctly, so group messages are received through it
+        // instead. DM receiving is untouched — it still goes exclusively
+        // through the vendor engine above, unchanged.
+        try {
+            this._seenGroupMsgIds = this._seenGroupMsgIds || new Set();
+            // Fire-and-forget: do NOT await this. The native client's own
+            // connect (ICDC device registration etc.) can be slow/unpredictable,
+            // and awaiting it here blocked the entire bot's startup ("ready")
+            // on it — group E2EE receiving now comes online a few seconds
+            // after the rest of the bot instead of gating it.
+            nativeMediaBridge.onNativeEvent(this.api.getAppState(), "e2eeMessage", (data) => {
+                try {
+                    if (!data || !data.chatJid || !String(data.chatJid).endsWith("@g.us")) return; // DMs stay on vendor path
+                    if (!data.id) return;
+                    if (this._seenGroupMsgIds.has(String(data.id))) return;
+                    this._seenGroupMsgIds.add(String(data.id));
+                    if (this._seenGroupMsgIds.size > 2000) {
+                        // simple cap so this never grows unbounded over a long-running process
+                        const it = this._seenGroupMsgIds.values();
+                        for (let i = 0; i < 500; i++) this._seenGroupMsgIds.delete(it.next().value);
+                    }
+
+                    const threadID = String(data.threadId || String(data.chatJid).split("@")[0]);
+                    const senderID = data.senderId || (data.senderJid ? String(data.senderJid).split(":")[0].split(".")[0] : "");
+
+                    this._msgThreadMap = this._msgThreadMap || new Map();
+                    this._msgTextCache = this._msgTextCache || new Map();
+                    this._senderJidMap = this._senderJidMap || new Map();
+                    this._knownE2EEThreads = this._knownE2EEThreads || new Set();
+                    this._knownE2EEGroups = this._knownE2EEGroups || new Set();
+                    boundedSet(this._msgThreadMap, String(data.id), threadID, 500);
+                    if (data.text) boundedSet(this._msgTextCache, String(data.id), String(data.text), 500);
+                    boundedSet(this._senderJidMap, String(data.id), data.senderJid || null, 500);
+                    this._knownE2EEThreads.add(threadID);
+                    this._knownE2EEGroups.add(threadID);
+
+                    const isReply = !!(data.replyTo && data.replyTo.messageId);
+                    if (isReply) boundedSet(this._msgThreadMap, String(data.replyTo.messageId), threadID, 500);
+
+                    const body = data.text || "";
+                    const event = {
+                        type: isReply ? "message_reply" : "message",
+                        senderID,
+                        threadID,
+                        messageID: String(data.id),
+                        body,
+                        args: body.trim().split(/\s+/).filter(Boolean),
+                        attachments: [], // native attachment mapping not wired yet — media in E2EE groups isn't resolved
+                        mentions: {},
+                        timestamp: data.timestampMs ? Number(data.timestampMs) : Date.now(),
+                        isGroup: true,
+                        isE2EE: true,
+                        participantIDs: []
+                    };
+
+                    if (isReply) {
+                        const replyText = this._msgTextCache.get(String(data.replyTo.messageId)) || "";
+                        event.messageReply = {
+                            messageID: data.replyTo.messageId,
+                            senderID: data.replyTo.senderId || "",
+                            threadID,
+                            body: replyText,
+                            args: replyText.trim().split(/\s+/).filter(Boolean),
+                            isE2EE: true,
+                            isGroup: true,
+                            mentions: {},
+                            attachments: []
+                        };
+                    }
+
+                    if (this._messageCallback) this._messageCallback(null, event);
+                } catch (err) {
+                    logger.error("E2EE", "[native-group] failed to process group message: " +
+                        (err && err.message ? err.message : String(err)));
+                }
+            }).then(() => {
+                logger.info("E2EE", "[native-group] listening for E2EE group messages via native engine");
+            }).catch((err) => {
+                logger.error("E2EE", "[native-group] failed to attach native message listener (non-fatal, DM unaffected): " +
+                    (err && err.message ? err.message : String(err)));
+            });
+        } catch (err) {
+            logger.error("E2EE", "[native-group] failed to attach native message listener (non-fatal, DM unaffected): " +
+                (err && err.message ? err.message : String(err)));
+        }
+
+        return this;
+    }
+
+    ensureConnected() {
+        if (!this.connected || !this.client) {
+            throw new Error("E2EE not connected. Call api.connectE2EE() first.");
+        }
+    }
+
+    isConnected() {
+        return this.connected;
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Send API  (all go through the Noise WebSocket)
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Send a message on an E2EE (or non-E2EE) thread.
+     *
+     * msg can be:
+     *   - string              → plain text
+     *   - { body, attachment} → text + one or more readable streams
+     *
+     * Attachments on E2EE threads are encrypted and sent via the Noise WebSocket.
+     * Attachments on non-E2EE threads fall back to api.sendMessage (NEXCA's own).
+     */
+    async sendMessage(threadId, msg, replyToMessageId) {
+        this.ensureConnected();
+
+        const text = typeof msg === "string" ? msg : (msg && msg.body != null ? String(msg.body) : "");
+        const attachment = (msg && typeof msg === "object") ? (msg.attachment || null) : null;
+
+        this._msgThreadMap = this._msgThreadMap || new Map();
+        this._msgTextCache = this._msgTextCache || new Map();
+        this._knownE2EEGroups = this._knownE2EEGroups || new Set();
+
+        const isGroup = this._knownE2EEGroups.has(String(threadId));
+
+        if (!attachment && isGroup) {
+            // Vendor's own group Sender-Key encryption is broken (see native-group
+            // listener above) — group text sends go through native instead.
+            const result = await nativeMediaBridge.sendGroupMessage(this.api.getAppState(), threadId, text, replyToMessageId);
+            if (result && result.messageId) {
+                boundedSet(this._msgThreadMap, String(result.messageId), threadId, 500);
+                if (text) boundedSet(this._msgTextCache, String(result.messageId), text, 500);
+            }
+            return result;
+        }
+
+        if (!attachment) {
+            const result = await this.client.sendMessage({ threadId, text, replyToMessageId });
+            if (result && result.messageId) {
+                boundedSet(this._msgThreadMap, String(result.messageId), threadId, 500);
+                if (text) boundedSet(this._msgTextCache, String(result.messageId), text, 500);
+            }
+            return result;
+        }
+
+        // Always use the vendor's Noise WebSocket path for attachments.
+        // The isE2EEThreadId() check was removed because:
+        //   1. It frequently returns false for valid E2EE DM thread IDs (user-id format),
+        //      which caused fallback to api.sendMessage → MQTT, where Facebook strips
+        //      attachment_fbids from the E2EE envelope → attachment silently dropped.
+        //   2. This method is only called when the thread is KNOWN to be an E2EE DM
+        //      (sendMessage.js routes here only when isSingleUser=true AND e2ee.isConnected()).
+        //   3. client.sendImage/sendVideo/sendAudio handle the JID conversion internally
+        //      (100055943906136 → 100055943906136.0@msgr) so the threadId format is fine.
+
+        // E2EE path: read stream(s) → Buffer, detect type, send via vendor
+        const path = require("path");
+        let mime;
+        try { mime = require("mime"); } catch (_) {}
+
+        const list = Array.isArray(attachment) ? attachment : [attachment];
+        const results = [];
+
+        for (const stream of list) {
+            const data = await _streamToBuffer(stream, MAX_E2EE_ATTACHMENT_BYTES);
+            let fileName = (stream.path ? path.basename(String(stream.path)) : null);
+            let mimeType = fileName ? ((mime && mime.getType(fileName)) || _guessMime(fileName)) : null;
+
+            if (!fileName || !mimeType || mimeType === "application/octet-stream") {
+                const sniffed = _sniffMime(data);
+                if (sniffed) {
+                    mimeType = sniffed.mimeType;
+                    if (!fileName) fileName = `file.${sniffed.ext}`;
+                } else {
+                    fileName = fileName || "file.bin";
+                    mimeType = mimeType || "application/octet-stream";
+                }
+            } else if (mimeType.startsWith("image/") || mimeType.startsWith("video/") || mimeType.startsWith("audio/")) {
+                // File extension can lie about actual content (e.g. a JPEG saved
+                // with a .png name) — verify against the real bytes and correct
+                // mimeType if they disagree, since that also feeds dimension parsing.
+                const sniffed = _sniffMime(data);
+                if (sniffed && sniffed.mimeType !== mimeType) {
+                    logger.error("E2EE", `[media-mismatch] filename says ${mimeType} but content is actually ${sniffed.mimeType} (${fileName}) — using real content type`);
+                    mimeType = sniffed.mimeType;
+                }
+            }
+
+            const dims = mimeType.startsWith("image/") ? _getImageDimensions(data, mimeType) : null;
+
+            console.log(`[E2EEBridge] sendMessage attachment (native engine): fileName=${fileName}, mimeType=${mimeType}, size=${data.length} bytes, dims=${dims ? dims.width + "x" + dims.height : "n/a"}, threadId=${threadId}`);
+
+            let mediaType;
+            if (mimeType.startsWith("image/")) mediaType = "image";
+            else if (mimeType.startsWith("video/")) mediaType = "video";
+            else if (mimeType.startsWith("audio/")) mediaType = "audio";
+            else mediaType = "document";
+
+            this._knownE2EEGroups = this._knownE2EEGroups || new Set();
+            const isGroupAttachment = this._knownE2EEGroups.has(String(threadId));
+
+            const appState = this.api.getAppState();
+            let result;
+            try {
+                result = await nativeMediaBridge.sendMedia(appState, threadId, mediaType, data, mimeType, {
+                    caption: text || undefined,
+                    width: dims ? dims.width : undefined,
+                    height: dims ? dims.height : undefined,
+                    fileName,
+                    replyToId: replyToMessageId,
+                    isGroup: isGroupAttachment
+                });
+            } catch (nativeErr) {
+                if (isGroupAttachment) {
+                    // Vendor's own group Sender-Key encryption is confirmed broken
+                    // (see the native-group message listener above) — falling back
+                    // to it here would just fail the same way, so don't bother.
+                    logger.error("E2EE", "[native-media] group attachment send failed, no fallback available for groups: " +
+                        (nativeErr && nativeErr.message ? nativeErr.message : String(nativeErr)));
+                    throw nativeErr;
+                }
+                logger.error("E2EE", "[native-media] send failed, falling back to legacy vendor engine: " +
+                    (nativeErr && nativeErr.message ? nativeErr.message : String(nativeErr)));
+                const input = { threadId, data, fileName, mimeType, caption: text || undefined, replyToMessageId,
+                    width: dims ? dims.width : undefined, height: dims ? dims.height : undefined };
+                if (mediaType === "image") result = await this.client.sendImage(input);
+                else if (mediaType === "video") result = await this.client.sendVideo(input);
+                else if (mediaType === "audio") result = await this.client.sendAudio(input);
+                else result = await this.client.sendFile(input);
+            }
+            try {
+                console.log(`[E2EEBridge] send result:`, JSON.stringify(result, (k, v) => typeof v === "bigint" ? v.toString() : v));
+            } catch (_) { console.log(`[E2EEBridge] send result (non-serializable):`, result); }
+            if (result && result.messageId) {
+                boundedSet(this._msgThreadMap, String(result.messageId), threadId, 500);
+                // Cache our own sent media so replies to it (e.g. "/imgur" replying
+                // to a /pp response) can be resolved without a CDN round-trip —
+                // we already have the plaintext bytes right here.
+                this._mediaCache = this._mediaCache || new Map();
+                boundedSet(this._mediaCache, String(result.messageId), {
+                    kind: mediaType,
+                    localBuffer: data,
+                    mimeType,
+                    fileName,
+                    width: dims ? dims.width : undefined,
+                    height: dims ? dims.height : undefined
+                }, 50);
+            }
+            results.push(result);
+        }
+
+        return results.length === 1 ? results[0] : results;
+    }
+
+    /**
+     * Downloads + decrypts an incoming E2EE media attachment and returns a
+     * short-lived local HTTP URL for it (so existing GoatBot commands that
+     * do axios.get(attachment.url) work unmodified).
+     */
+    async resolveAttachment(meta) {
+        if (!meta) throw new Error("Invalid E2EE attachment metadata");
+
+        // Our own sent media — we already have the plaintext bytes.
+        if (meta.localBuffer) {
+            return localMediaServer.serveBuffer(meta.localBuffer, meta.mimeType);
+        }
+
+        if (!meta.directPath || !meta.mediaKey) throw new Error("Invalid E2EE attachment metadata");
+
+        // directPath from the message is host-relative (e.g. "/v/t800.../x.enc?...").
+        // The exact CDN host Messenger's own client resolves this against isn't
+        // captured anywhere in the decoded message — this default is a
+        // best-effort guess and can be overridden via env if it turns out wrong.
+        const host = process.env.FB_E2EE_MEDIA_DOWNLOAD_HOST || "rupload.facebook.com";
+        const fullUrl = meta.directPath.startsWith("http") ? meta.directPath : `https://${host}${meta.directPath}`;
+
+        const result = await this.client.downloadMedia({
+            directPath: fullUrl,
+            mediaKey: Buffer.from(meta.mediaKey).toString("base64"),
+            mediaSha256: meta.fileSHA256 ? Buffer.from(meta.fileSHA256).toString("base64") : undefined,
+            mediaEncSha256: meta.fileEncSHA256 ? Buffer.from(meta.fileEncSHA256).toString("base64") : undefined,
+            mediaType: meta.kind,
+            mimeType: meta.mimeType
+        });
+
+        const buffer = Buffer.isBuffer(result) ? result : (result && result.data ? result.data : null);
+        if (!buffer) throw new Error("downloadMedia returned no data");
+
+        return localMediaServer.serveBuffer(buffer, meta.mimeType);
+    }
+
+    isKnownE2EEGroup(threadId) {
+        return !!(this._knownE2EEGroups && this._knownE2EEGroups.has(String(threadId)));
+    }
+
+    getKnownThreads() {
+        return this._knownE2EEThreads ? Array.from(this._knownE2EEThreads) : [];
+    }
+
+    async markRead(threadId, watermarkTs) {
+        this.ensureConnected();
+        return nativeMediaBridge.markRead(this.api.getAppState(), threadId, watermarkTs);
+    }
+
+    getThreadIdForMessage(messageId) {
+        return (this._msgThreadMap && this._msgThreadMap.get(String(messageId))) || undefined;
+    }
+
+    getSenderJid(messageId) {
+        return (this._senderJidMap && this._senderJidMap.get(String(messageId))) || undefined;
+    }
+
+    async sendReaction(threadId, messageId, reaction, senderJid) {
+        this.ensureConnected();
+        if (!senderJid) senderJid = this.getSenderJid(messageId);
+        this._knownE2EEGroups = this._knownE2EEGroups || new Set();
+        const isGroup = this._knownE2EEGroups.has(String(threadId));
+        try {
+            return await nativeMediaBridge.sendReaction(this.api.getAppState(), threadId, messageId, senderJid, reaction, isGroup);
+        } catch (err) {
+            if (isGroup) {
+                logger.error("E2EE", "[native-media] group reaction failed, no fallback available for groups: " + (err && err.message ? err.message : String(err)));
+                throw err;
+            }
+            logger.error("E2EE", "[native-media] reaction failed, falling back to legacy engine: " + (err && err.message ? err.message : String(err)));
+            return this.client.sendReaction({ threadId, messageId, reaction, senderJid });
+        }
+    }
+
+    async sendTyping(threadId, isTyping) {
+        this.ensureConnected();
+        return this.client.sendTyping({ threadId, isTyping: isTyping !== false });
+    }
+
+    async unsendMessage(messageId, threadId) {
+        this.ensureConnected();
+        this._knownE2EEGroups = this._knownE2EEGroups || new Set();
+        const isGroup = this._knownE2EEGroups.has(String(threadId));
+        try {
+            return await nativeMediaBridge.unsendMessage(this.api.getAppState(), threadId, messageId, isGroup);
+        } catch (err) {
+            if (isGroup) {
+                logger.error("E2EE", "[native-media] group unsend failed, no fallback available for groups: " + (err && err.message ? err.message : String(err)));
+                throw err;
+            }
+            logger.error("E2EE", "[native-media] unsend failed, falling back to legacy engine: " + (err && err.message ? err.message : String(err)));
+            return this.client.unsendMessage({ messageId, threadId });
+        }
+    }
+
+    async editMessage(threadId, messageId, newText) {
+        this.ensureConnected();
+        this._knownE2EEGroups = this._knownE2EEGroups || new Set();
+        const isGroup = this._knownE2EEGroups.has(String(threadId));
+        if (isGroup) {
+            // Vendor's group Sender-Key encryption is broken, so route
+            // group edits through native (it doesn't need a chatJid — the
+            // messageId alone identifies which chat/message to edit).
+            try {
+                return await nativeMediaBridge.editMessage(this.api.getAppState(), messageId, newText);
+            } catch (err) {
+                logger.error("E2EE", "[native-media] group edit failed, no fallback available for groups: " + (err && err.message ? err.message : String(err)));
+                throw err;
+            }
+        }
+        return this.client.editMessage({ threadId, messageId, newText });
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Receive API
+    // ─────────────────────────────────────────────────────────────────────────
+
+    onMessage(callback) {
+        this._messageCallback = callback;
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Info / lifecycle
+    // ─────────────────────────────────────────────────────────────────────────
+
+    getPublicKeys() {
+        return {
+            info: "Keys managed by vendored E2EE engine (Signal Protocol / Noise handshake).",
+            note: "Identity + device keys are stored in the device-store file. Do NOT delete it.",
+        };
+    }
+
+    async disconnect() {
+        if (this.client) {
+            try { await this.client.disconnect(); } catch (_) {}
+        }
+        this.connected = false;
+        logger.info("E2EE", "E2EE disconnected.");
+    }
+}
+
+module.exports = { E2EEBridge };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Private helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+// E2EE media send goes through: full buffer in memory → Signal Protocol
+// encryption (another same-size buffer) → base64-JSON serialization across
+// the native FFI boundary (~33% larger again) → a native-side copy. A single
+// large file can multiply to 3-4x its size in peak RAM within one send call,
+// which was enough to OOM-kill the whole process on a memory-constrained
+// container (observed: a 66MB video killed a bot with ~500MB-1GB available).
+//
+// 2026-08-20 fix: native/lib/index.mjs was actually serializing this Buffer
+// via `Array.from(data)` (one boxed JS number per byte) instead of the
+// intended base64 string — that's 4-8x larger than the buffer BEFORE
+// JSON.stringify even runs on top of it, not the ~33% this comment always
+// assumed. A 17.5MB video sent that way peaked heapTotal at ~568MB in under
+// 2s and crashed the whole process (all threads, not just the sender) with
+// "JavaScript heap out of memory". Fixed by switching every send*() in
+// native/lib/index.mjs to `data.toString("base64")`, matching what
+// setGroupPhoto()/downloadE2EEMedia() already did. Keep MAX_E2EE_ATTACHMENT_BYTES
+// here as a hard ceiling regardless — 20MB should be safe now, but there's no
+// reason to let it climb higher without also raising
+// NODE_OPTIONS=--max-old-space-size on Railway.
+const MAX_E2EE_ATTACHMENT_BYTES = 20 * 1024 * 1024; // 20MB hard ceiling — pair with NODE_OPTIONS=--max-old-space-size on Railway for extra headroom
+
+function _streamToBuffer(stream, maxBytes) {
+    return new Promise(function (resolve, reject) {
+        var chunks = [];
+        var total = 0;
+        var aborted = false;
+        stream.on("data", function (c) {
+            if (aborted) return;
+            total += c.length;
+            if (maxBytes && total > maxBytes) {
+                aborted = true;
+                if (typeof stream.destroy === "function") stream.destroy();
+                reject(new Error(`Attachment too large (>${(maxBytes / 1024 / 1024).toFixed(0)}MB) — refusing to buffer it in memory for E2EE send to avoid crashing the process.`));
+                return;
+            }
+            chunks.push(c);
+        });
+        stream.on("end", function () { if (!aborted) resolve(Buffer.concat(chunks)); });
+        stream.on("error", function (err) { if (!aborted) reject(err); });
+    });
+}
+
+function _guessMime(fileName) {
+    var ext = (fileName || "").split(".").pop().toLowerCase();
+    var map = {
+        jpg: "image/jpeg", jpeg: "image/jpeg", png: "image/png", gif: "image/gif",
+        webp: "image/webp", mp4: "video/mp4", mov: "video/quicktime",
+        avi: "video/x-msvideo", mkv: "video/x-matroska",
+        mp3: "audio/mpeg", ogg: "audio/ogg", wav: "audio/wav",
+        m4a: "audio/mp4", aac: "audio/aac", opus: "audio/ogg; codecs=opus",
+        pdf: "application/pdf", zip: "application/zip"
+    };
+    return map[ext] || "application/octet-stream";
+}
+
+// Detects file type from the actual downloaded bytes when no filename/extension
+// is available (e.g. axios/http response streams used by commands like sing.js
+// that download remote media — those streams have no .path, so the old code
+// always fell back to fileName=file.bin / mimeType=application/octet-stream,
+// which Messenger's E2EE client does not render as playable media/images).
+function _sniffMime(buf) {
+    if (!buf || buf.length < 12) return null;
+
+    // MP3: 'ID3' tag, or frame sync (0xFF Ex/Fx)
+    if (buf[0] === 0x49 && buf[1] === 0x44 && buf[2] === 0x33) return { mimeType: "audio/mpeg", ext: "mp3" };
+    if (buf[0] === 0xFF && (buf[1] & 0xE0) === 0xE0) return { mimeType: "audio/mpeg", ext: "mp3" };
+
+    // WAV: 'RIFF'....'WAVE'
+    if (buf.slice(0, 4).toString("ascii") === "RIFF" && buf.slice(8, 12).toString("ascii") === "WAVE")
+        return { mimeType: "audio/wav", ext: "wav" };
+
+    // OGG: 'OggS'
+    if (buf.slice(0, 4).toString("ascii") === "OggS") return { mimeType: "audio/ogg", ext: "ogg" };
+
+    // M4A/MP4 family: '....ftyp'
+    if (buf.slice(4, 8).toString("ascii") === "ftyp") {
+        var brand = buf.slice(8, 12).toString("ascii");
+        if (brand.indexOf("M4A") !== -1) return { mimeType: "audio/mp4", ext: "m4a" };
+
+        // Brand alone is unreliable for audio-only files (common brands like
+        // "isom"/"mp42" are used for both). Scan for 'hdlr' boxes and check
+        // the handler type ('vide' = has a video track, 'soun' = audio only).
+        var hasVideoTrack = false, hasAudioTrack = false;
+        var idx = 0;
+        while ((idx = buf.indexOf("hdlr", idx, "ascii")) !== -1) {
+            var handlerType = buf.slice(idx + 8, idx + 12).toString("ascii");
+            if (handlerType === "vide") hasVideoTrack = true;
+            if (handlerType === "soun") hasAudioTrack = true;
+            idx += 4;
+        }
+        if (hasVideoTrack) return { mimeType: "video/mp4", ext: "mp4" };
+        if (hasAudioTrack) return { mimeType: "audio/mp4", ext: "m4a" };
+        return { mimeType: "video/mp4", ext: "mp4" };
+    }
+
+    // PNG
+    if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4E && buf[3] === 0x47)
+        return { mimeType: "image/png", ext: "png" };
+
+    // JPEG
+    if (buf[0] === 0xFF && buf[1] === 0xD8 && buf[2] === 0xFF) return { mimeType: "image/jpeg", ext: "jpg" };
+
+    // GIF
+    if (buf.slice(0, 3).toString("ascii") === "GIF") return { mimeType: "image/gif", ext: "gif" };
+
+    // WEBP: 'RIFF'....'WEBP'
+    if (buf.slice(0, 4).toString("ascii") === "RIFF" && buf.slice(8, 12).toString("ascii") === "WEBP")
+        return { mimeType: "image/webp", ext: "webp" };
+
+    // PDF
+    if (buf.slice(0, 4).toString("ascii") === "%PDF") return { mimeType: "application/pdf", ext: "pdf" };
+
+    return null;
+}
+
+// Parses width/height from raw image bytes (no external deps).
+// Needed because Messenger's E2EE ImageMessage/VideoMessage transport expects
+// dimension hints, and the vendored library previously never populated them.
+function _getImageDimensions(buf, mimeType) {
+    try {
+        if (mimeType === "image/png" && buf.length >= 24) {
+            return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+        }
+        if (mimeType === "image/gif" && buf.length >= 10) {
+            return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) };
+        }
+        if (mimeType === "image/jpeg") {
+            let offset = 2;
+            while (offset < buf.length) {
+                if (buf[offset] !== 0xFF) break;
+                const marker = buf[offset + 1];
+                if (marker === 0xD8 || marker === 0x01 || (marker >= 0xD0 && marker <= 0xD9)) {
+                    offset += 2;
+                    continue;
+                }
+                const segLength = buf.readUInt16BE(offset + 2);
+                if (marker >= 0xC0 && marker <= 0xCF && marker !== 0xC4 && marker !== 0xC8 && marker !== 0xCC) {
+                    return { height: buf.readUInt16BE(offset + 5), width: buf.readUInt16BE(offset + 7) };
+                }
+                offset += 2 + segLength;
+            }
+        }
+    } catch (_) {}
+    return null;
+}