@inetafrica/open-claudia 3.5.14 → 3.5.17

package/channels/kazee/adapter.js

@@ -8,10 +8,13 @@ const path = require("path");
 const https = require("https");
 const http = require("http");
 const crypto = require("crypto");
+const dns = require("dns");
+const net = require("net");
 const { pipeline } = require("stream/promises");
 const { Transform } = require("stream");
 const { URL } = require("url");
 const { TEMP_DIR, FILES_DIR } = require("../../core/config");
+const { safeJoin } = require("../../core/safe-filename");
 const { canonicalForChannel } = require("../../core/identity");
 const { inlineKeyboardToPortable } = require("../types");
 const { createKazeeSocket } = require("./socket");
@@ -52,14 +55,10 @@ const THREAD_FETCH_TIMEOUT_MS = 4000;
 // A thread whose root someone else posted is re-checked for the bot among its
 // participants at most this often (the answer is "no" until the bot replies).
 const THREAD_NOT_IN_TTL_MS = 60 * 1000;
-// Bots answering bots: once this many messages in a row (the newest one
-// included) came from bots, a bot's @-mention no longer engages the bot until
-// a person speaks again. OC_BOT_CHAIN_LIMIT overrides it (whole number >= 1).
-const BOT_CHAIN_LIMIT = 4;
-function botChainLimit() {
-  const value = parseInt(process.env.OC_BOT_CHAIN_LIMIT, 10);
-  return Number.isSafeInteger(value) && value >= 1 ? value : BOT_CHAIN_LIMIT;
-}
+// Bots handing work to each other (./bot-handoffs.js): what wakes a bot, when
+// the bots pause and check in with a person, and the tag check.
+const handoffs = require("./bot-handoffs");
+const { botChainLimit } = handoffs;
 // How many replies a thread's first turn carries as context.
 const THREAD_CONTEXT_LIMIT = 30;
 const THREAD_ROOT_BODY_LIMIT = 1000;
@@ -133,14 +132,72 @@ const MIME_EXT = {
   "application/zip": ".zip",
 };
 
+// Inbound media never goes past 200 MB. With KAZEE_MEDIA_HOSTS set (comma-
+// separated hosts or URLs), files are fetched only from those hosts and Kazee
+// itself (KAZEE_URL). Without it, Kazee's presigned links on its storage host
+// keep working: any public host is allowed, but never a private, loopback or
+// link-local address (checked when connecting), so a crafted link cannot
+// point the bot at internal services.
+const MAX_DOWNLOAD_BYTES = 200 * 1024 * 1024;
+const DOWNLOAD_IDLE_MS = 60 * 1000;
+
+function mediaHostList(mediaHosts) {
+  return (Array.isArray(mediaHosts) ? mediaHosts : String(mediaHosts || "").split(","))
+    .map((raw) => String(raw || "").trim())
+    .filter(Boolean);
+}
+
+function mediaHostSet(url, mediaHosts) {
+  const hosts = new Set();
+  for (const entry of [url, ...mediaHostList(mediaHosts)]) {
+    try { hosts.add((entry.includes("://") ? new URL(entry).host : entry).toLowerCase()); } catch (_) {}
+  }
+  return hosts;
+}
+
+const NON_PUBLIC = new net.BlockList();
+for (const [address, prefix] of [
+  ["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8], ["169.254.0.0", 16],
+  ["172.16.0.0", 12], ["192.0.0.0", 24], ["192.168.0.0", 16], ["198.18.0.0", 15], ["224.0.0.0", 4], ["240.0.0.0", 4],
+]) NON_PUBLIC.addSubnet(address, prefix, "ipv4");
+for (const [address, prefix] of [["::", 128], ["::1", 128], ["fc00::", 7], ["fe80::", 10], ["ff00::", 8]]) {
+  NON_PUBLIC.addSubnet(address, prefix, "ipv6");
+}
+
+function isPublicAddress(address) {
+  const family = net.isIP(String(address || ""));
+  if (!family) return false;
+  const mapped = family === 6 && /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address);
+  if (mapped) return !NON_PUBLIC.check(mapped[1], "ipv4");
+  return !NON_PUBLIC.check(address, family === 6 ? "ipv6" : "ipv4");
+}
+
+// dns.lookup for http(s).get that refuses names resolving to a non-public
+// address. It runs when connecting, so the answer cannot change in between.
+function publicOnlyLookup(hostname, options, callback) {
+  dns.lookup(hostname, options, (err, address, family) => {
+    if (err) return callback(err);
+    const answers = Array.isArray(address) ? address : [{ address, family }];
+    if (answers.some((a) => !isPublicAddress(a.address))) {
+      console.error(`Kazee download refused: ${hostname} resolves to a non-public address`);
+      return callback(Object.assign(new Error(`${hostname} resolves to a non-public address`), { code: "EMEDIAHOST" }));
+    }
+    callback(null, address, family);
+  });
+}
+
 class KazeeAdapter {
-  constructor({ id = "kazee", url, token, ownerUserId, botUserId, passiveGate = null }) {
+  constructor({ id = "kazee", url, token, ownerUserId, botUserId, mediaHosts = "", passiveGate = null, spawnUtilityAgent = null }) {
     this.id = id;
     this.type = "kazee";
     // KAZEE_URL is the root host (socket.io lives at /). REST routes are
     // mounted under /api on chat-central; we prepend that internally.
     this.url = url.replace(/\/$/, "");
     this.apiBase = this.url + "/api";
+    this._mediaHosts = mediaHostSet(this.url, mediaHosts);
+    this._mediaHostsListed = mediaHostList(mediaHosts).length > 0;
+    try { this._kazeeHost = new URL(this.url).host.toLowerCase(); } catch (_) { this._kazeeHost = ""; }
+    this._maxDownloadBytes = MAX_DOWNLOAD_BYTES;
     this.token = token;
     this.ownerUserId = ownerUserId || "";
     this.botUserId = botUserId || null;
@@ -166,6 +223,12 @@ class KazeeAdapter {
     // Groups set to "When they can help" (core/passive-replies.js); made on
     // first use, so a bot in no passive group never builds one.
     this._passive = passiveGate;
+    // Bot hand-offs (./bot-handoffs.js): messageId -> the bot ids it tagged,
+    // for messages this bot posted (so another bot's answer to one wakes it),
+    // and conversation key -> the check-in the gate asked this bot to post.
+    this._sentTags = new Map();
+    this._pauseNext = new Map();
+    this._spawnUtility = spawnUtilityAgent;
   }
 
   _passiveGate() {
@@ -197,11 +260,15 @@ class KazeeAdapter {
       const participants = (Array.isArray(chat.participants) ? chat.participants : [])
         .filter((p) => p && typeof p === "object");
       const self = participants.find((p) => String(p._id || p.id) === String(this.botUserId));
+      const bots = participants.filter((p) => p.type === "AI" || p.type === "Bot")
+        .map((p) => ({ id: String(p._id || p.id), name: String(p.name || "") }));
       const meta = {
         isGroupChat: !!chat.isGroupChat,
         assistantAction: String(chat.assistantAction || ""),
         name: String(chat.chatName || chat.name || ""),
-        botIds: participants.filter((p) => p.type === "AI" || p.type === "Bot").map((p) => String(p._id || p.id)),
+        botIds: bots.map((b) => b.id),
+        // The other bots, for the hand-off lines in a group turn's context.
+        bots: bots.filter((b) => b.id !== String(this.botUserId)),
         botName: self && self.name ? String(self.name) : "",
       };
       this._chatMetaCache.set(chatId, { meta, at: Date.now() });
@@ -394,6 +461,70 @@ class KazeeAdapter {
     return (id && this._sentMessages.get(id)) || null;
   }
 
+  // The bots a message this bot posted tagged (an answer to it wakes this bot).
+  _rememberTags(messageId, botIds) {
+    const id = String(messageId || "");
+    if (!id) return;
+    this._sentTags.delete(id);
+    this._sentTags.set(id, botIds.map(String));
+    if (this._sentTags.size > SENT_MESSAGE_MEMORY) this._sentTags.delete(this._sentTags.keys().next().value);
+  }
+
+  _rememberTagsSafely(messageId, botIds) {
+    try { this._rememberTags(messageId, botIds); }
+    catch (e) { console.error("Kazee: could not record a message's tags:", e.message); }
+  }
+
+  // Settle the bot tags of a post in place (body.content) and return the ids
+  // of the bots it still tags. A final answer the gate asked to be the
+  // exchange's check-in tags no bot, only the person, behind PAUSE_MARK. A
+  // final answer keeps a bot's tag when the tag check says yes; any other
+  // post never wakes a bot. 1:1 chats and posts without a tag are untouched.
+  async _settleBotTags(channelId, threadId, body, finalAnswer) {
+    const key = threadId ? `${channelId}#thread:${threadId}` : String(channelId);
+    let pause = finalAnswer ? this._pauseNext.get(key) || null : null;
+    if (pause) {
+      this._pauseNext.delete(key);
+      if (!(pause.until > Date.now())) pause = null;
+    }
+    if (!pause && !String(body.content || "").includes("@[")) return [];
+    const meta = await this._chatMeta(String(channelId));
+    if (!meta || !meta.isGroupChat) return [];
+    const others = (meta.botIds || []).filter((id) => id !== String(this.botUserId));
+    if (pause) {
+      let content = handoffs.stripTags(body.content, others).trim();
+      const person = pause.person;
+      if (person && person.id && !others.includes(person.id) && !content.includes(`](${person.id})`)) {
+        content = `@[${person.name || "there"}](${person.id}) ${content}`;
+      }
+      body.content = content.startsWith(handoffs.PAUSE_MARK) ? content : `${handoffs.PAUSE_MARK} ${content}`;
+      return [];
+    }
+    const tags = handoffs.findBotTags(body.content, meta.botIds, this.botUserId);
+    if (!tags.length) return [];
+    const ids = [...new Set(tags.map((t) => t.id))];
+    if (!finalAnswer) {
+      body.content = handoffs.stripTags(body.content, ids);
+      return [];
+    }
+    const verdict = await this._checkTags(channelId, threadId, body.content, tags, meta);
+    console.log(`[handoff] chat ${channelId}: tag ${tags.map((t) => t.name).join(", ")} ${verdict.tag ? "sent" : "written as a name"} (${verdict.reason || "no reason"})`);
+    if (verdict.tag) return ids;
+    body.content = handoffs.stripTags(body.content, ids);
+    return [];
+  }
+
+  // The tag check (./bot-handoffs.js checkTag) on the room's recent messages.
+  async _checkTags(channelId, threadId, draft, tags, meta) {
+    let messages = [];
+    try { messages = await this._passiveContext(String(channelId), threadId || null); }
+    catch (e) { messages = []; }
+    return handoffs.checkTag(
+      { botName: meta.botName, roomName: meta.name, messages, draft, targets: tags },
+      this._spawnUtility ? { spawnUtilityAgent: this._spawnUtility } : {},
+    );
+  }
+
   // GET a thread's root and replies (oldest first). Throws on failure or
   // after THREAD_FETCH_TIMEOUT_MS.
   async _fetchThread(chatId, rootId, limit) {
@@ -607,6 +738,9 @@ class KazeeAdapter {
             },
             messageId: m._id || m.id,
             media: this._mediaRefs(m, channelId, "Quoted message"),
+            // Who the quoted message tagged: another bot's answer to one of
+            // this bot's tags wakes it (./bot-handoffs.js).
+            mentions: (Array.isArray(m.mentions) ? m.mentions : []).map((x) => String(x?._id || x?.id || x)),
           };
         }
 
@@ -633,19 +767,37 @@ class KazeeAdapter {
           .map((m) => String(m?._id || m?.id || m));
         const mentioned = mentions.includes(botId);
         // Another bot (Sumeet, 3 Oct 2026: two bots in one chat "go on an
-        // infinite conversation"): only an explicit @-mention engages the bot,
-        // never a reply to its message, a thread it is in, a passive check or
-        // an every-message group; and never once the conversation is a chain
-        // of bots answering bots (_botChainTooLong) until a person speaks.
-        if ((meta.botIds || []).includes(String(senderId))) {
-          if (!mentioned) {
+        // infinite conversation"; 5 Oct: let them hand work to each other and
+        // decide themselves when to stop). It engages this bot only on
+        // purpose: by tagging it, or by answering (replying to) a message in
+        // which this bot tagged it. Never a reply to any other message, a
+        // thread it is in, a passive check or an every-message group. The
+        // exchange decides the rest (_botExchange): it goes on, this bot posts
+        // the one check-in, or it stays silent until a person writes.
+        const fromBot = (meta.botIds || []).includes(String(senderId));
+        if (fromBot) {
+          const answered = !mentioned && this._answersMyTag(envelope, senderId);
+          if (!mentioned && !answered) {
             console.log(`Kazee group gate: silent, another bot (chat=${channelId} from=${userId})`);
             return;
           }
-          if (await this._botChainTooLong(channelId, envelope.threadId || null, meta, msg)) {
-            console.log(`Kazee group gate: silent, bots answering bots (chat=${channelId} from=${userId})`);
+          const exchange = await this._botExchange(channelId, envelope.threadId || null, meta, msg);
+          if (exchange.silent) {
+            console.log(`Kazee group gate: silent, ${exchange.silent} (chat=${channelId} from=${userId})`);
             return;
           }
+          envelope.botHandoff = {
+            from: { id: String(senderId), name: baseFrom.name },
+            kind: mentioned ? "asked" : "answered",
+            person: exchange.person,
+            count: exchange.streak,
+            pause: exchange.pause || null,
+          };
+          if (exchange.pause) {
+            const key = envelope.threadId ? `${channelId}#thread:${envelope.threadId}` : channelId;
+            this._pauseNext.set(key, { until: Date.now() + handoffs.PAUSE_TTL_MS, person: exchange.person });
+            console.log(`[handoff] chat ${channelId}: check-in (${exchange.pause === "repeat" ? "a repeated ask" : `${exchange.streak} bot messages in a row`})`);
+          }
         }
         const replyToBot = String(envelope.reply?.from?.id || "") === botId;
         const freeReply = meta.assistantAction === "assistant_free_reply";
@@ -657,7 +809,7 @@ class KazeeAdapter {
           : false;
         // "@bot be quiet" / "you can talk again" in a passive group only switch
         // its unprompted replies off or on: no turn, just a one-line answer.
-        if (passive && (mentioned || replyToBot) && envelope.type === "text") {
+        if (passive && !fromBot && (mentioned || replyToBot) && envelope.type === "text") {
           const command = quietCommand(text, meta.botName);
           if (command) return this._passiveQuietCommand(channelId, command, envelope);
         }
@@ -698,31 +850,51 @@ class KazeeAdapter {
     this._emit("message", envelope);
   }
 
-  // Whether the conversation (a thread, or the main timeline) is already a
-  // chain of bots answering bots: its newest messages, this one included, all
-  // came from bots, botChainLimit() of them or more. A failed read counts as
-  // a chain: quiet is the safe side of a possible loop.
-  async _botChainTooLong(chatId, threadId, meta, msg) {
+  // Whether another bot's message answers one of this bot's tags: it replies
+  // to a message this bot posted in which it tagged that bot (remembered when
+  // it was posted, else read off the quoted message after a restart).
+  _answersMyTag(envelope, senderId) {
+    const reply = envelope.reply;
+    if (!reply || String(reply.from?.id || "") !== String(this.botUserId)) return false;
+    const sender = String(senderId);
+    const remembered = this._sentTags.get(String(reply.messageId || ""));
+    if (remembered) return remembered.includes(sender);
+    return (reply.mentions || []).includes(sender)
+      || handoffs.findBotTags(reply.text, [sender], this.botUserId).length > 0;
+  }
+
+  // Where a bot-to-bot exchange stands in this conversation (a thread, or the
+  // main timeline), read from its newest messages, the triggering one
+  // included (./bot-handoffs.js). { silent: why } when this bot must not
+  // answer: a person asked the bots to stop, the bots already checked in, or
+  // they went past the limit. Otherwise { streak, person, pause }: pause is
+  // "limit" when this message makes botChainLimit() bot messages in a row
+  // since a person wrote, "repeat" when it repeats an ask; this bot then posts
+  // the one check-in. A failed read means silent: quiet is the safe side.
+  async _botExchange(chatId, threadId, meta, msg) {
     const limit = botChainLimit();
-    const bots = new Set([...(meta.botIds || []), String(this.botUserId)]);
+    const bots = [...new Set([...(meta.botIds || []), String(this.botUserId)])];
     let recent;
     try {
       if (threadId) {
-        const data = await this._fetchThread(chatId, threadId, limit + 2);
+        const data = await this._fetchThread(chatId, threadId, limit + 4);
         recent = [...(data.root && typeof data.root === "object" ? [data.root] : []), ...(Array.isArray(data.replies) ? data.replies : [])];
       } else {
-        recent = await withTimeout(this._messagesSince(chatId, null, limit + 2), THREAD_FETCH_TIMEOUT_MS, "Kazee recent messages");
+        recent = await withTimeout(this._messagesSince(chatId, null, limit + 4), THREAD_FETCH_TIMEOUT_MS, "Kazee recent messages");
       }
     } catch (e) {
-      console.error(`Kazee bot chain check failed (chat=${chatId}):`, e.message);
-      return true;
+      console.error(`Kazee bot exchange check failed (chat=${chatId}):`, e.message);
+      return { silent: "could not read the conversation" };
     }
     const list = (Array.isArray(recent) ? recent : []).filter((m) => m && !m.isDeleted && m.type !== "system");
     const currentId = String(msg._id || msg.id || "");
     if (currentId && !list.some((m) => String(m._id || m.id || "") === currentId)) list.push(msg);
-    let streak = 0;
-    for (let i = list.length - 1; i >= 0 && bots.has(senderIdOf(list[i])); i -= 1) streak += 1;
-    return streak >= limit;
+    const state = handoffs.exchangeState(list, bots);
+    if (state.stopped) return { silent: "a person asked the bots to stop" };
+    if (state.paused) return { silent: "the bots are waiting for a person" };
+    if (state.streak > limit) return { silent: "bots answering bots" };
+    const pause = state.streak === limit ? "limit" : (state.repeat ? "repeat" : null);
+    return { streak: state.streak, person: state.person, pause };
   }
 
   // Whether an unaddressed message in a passive group is the bot's to judge:
@@ -819,8 +991,31 @@ class KazeeAdapter {
   // reply.
   //
   // A thread turn (DM or group) gets the THREAD's context instead: see
-  // _threadContext.
+  // _threadContext. A group turn also learns about the other bots in the room
+  // and, when one of them woke this bot, about that exchange (_handoffContext).
   async buildThreadContext(envelope) {
+    const base = await this._conversationContext(envelope);
+    const extra = await this._handoffContext(envelope);
+    if (!extra) return base;
+    return { contextBlock: [base?.contextBlock, extra].filter(Boolean).join("\n\n"), media: base?.media || [] };
+  }
+
+  // The bots this bot may hand work to (./bot-handoffs.js), for a group turn;
+  // "" for a 1:1 chat, a group with no other bot, or a failed read.
+  async _handoffContext(envelope) {
+    if (!envelope || !this.botUserId || envelope.surface !== "group") return "";
+    try {
+      const meta = await this._chatMeta(String(envelope.channelId || ""));
+      const bots = (meta && meta.isGroupChat && meta.bots) || [];
+      if (!bots.length && !envelope.botHandoff) return "";
+      return handoffs.contextLines({ bots, handoff: envelope.botHandoff || null }).join("\n");
+    } catch (e) {
+      console.error("kazee hand-off context:", e.message);
+      return "";
+    }
+  }
+
+  async _conversationContext(envelope) {
     if (!envelope || !this.botUserId) return null;
     if (envelope.threadId) return this._threadContext(envelope);
     if (envelope.surface !== "group") return null;
@@ -1028,6 +1223,13 @@ class KazeeAdapter {
     if (buttons) body.interactive = { buttons };
     const threadId = opts.threadId ? String(opts.threadId) : null;
     if (threadId) body.threadRootId = threadId;
+    // Tags of other bots (./bot-handoffs.js). chat-central reads mentions out
+    // of the text itself (@[Name](id)), so only a final answer (opts.botTags)
+    // may keep one, and only with the tag check's yes; anything else (a stream
+    // preview, a notice) writes a bot tag as a plain name.
+    let botTags = [];
+    try { botTags = await this._settleBotTags(channelId, threadId, body, opts.botTags === true); }
+    catch (e) { console.error("Kazee bot tags:", e.message); }
     // Set once the thread refused the reply and it went to the main timeline
     // (quoting the root) instead: "quote" while that quote is still on.
     let fallback = null;
@@ -1073,6 +1275,7 @@ class KazeeAdapter {
       // body.threadRootId is gone when the reply fell back to the main
       // timeline, so only a post that went INTO the thread marks it.
       this._rememberSentSafely(id, body.threadRootId || null, channelId);
+      if (id && botTags.length) this._rememberTagsSafely(id, botTags);
       if (id) return String(id);
       // POST returned 2xx but carried no message id (server fast-ack / payload
       // fallback path). Returning null makes the caller treat a delivered
@@ -1451,16 +1654,48 @@ class KazeeAdapter {
     const baseDir = media.type === "document" ? FILES_DIR : TEMP_DIR;
     const keepName = media.type === "document" && media.fileName;
     const nameSuffix = keepName && !path.extname(media.fileName) && ext !== ".bin" ? ext : "";
+    const generated = `kz-${Date.now()}-${crypto.randomBytes(4).toString("hex")}${ext}`;
     const localPath = keepName
-      ? path.join(baseDir, media.fileName + nameSuffix)
-      : path.join(baseDir, `kz-${Date.now()}-${crypto.randomBytes(4).toString("hex")}${ext}`);
+      ? safeJoin(baseDir, media.fileName + nameSuffix, generated)
+      : path.join(baseDir, generated);
     await this._downloadUrl(url, localPath);
     return localPath;
   }
 
+  // The parsed URL when it may be fetched; otherwise logs why and throws.
+  _checkedMediaUrl(raw) {
+    let url = null;
+    try { url = new URL(String(raw)); } catch (_) {}
+    if (!url || !["https:", "http:"].includes(url.protocol) || url.username || url.password) {
+      console.error("Kazee download refused: not an http(s) media URL");
+      throw new Error("Invalid media URL");
+    }
+    const host = url.host.toLowerCase();
+    if (this._mediaHostsListed) {
+      if (!this._mediaHosts.has(host)) {
+        console.error(`Kazee download refused: ${host} is not a Kazee media host (allowed: KAZEE_URL's host and KAZEE_MEDIA_HOSTS)`);
+        throw new Error(`${host} is not a Kazee media host`);
+      }
+    } else if (host !== this._kazeeHost) {
+      // Names are checked when connecting (publicOnlyLookup); IP literals never look up.
+      const literal = url.hostname.replace(/^\[|\]$/g, "");
+      if (net.isIP(literal) && !isPublicAddress(literal)) {
+        console.error(`Kazee download refused: ${host} is a non-public address`);
+        throw new Error(`${host} is a non-public address`);
+      }
+    }
+    return url;
+  }
+
+  // Request options for a checked media URL: without a KAZEE_MEDIA_HOSTS list,
+  // anything but Kazee's own host must resolve to public addresses only.
+  _mediaRequestOptions(url) {
+    if (this._mediaHostsListed || url.host.toLowerCase() === this._kazeeHost) return {};
+    return { lookup: publicOnlyLookup };
+  }
+
   async _downloadContextMedia(media) {
-    const url = new URL(media.fileId);
-    if (!["https:", "http:"].includes(url.protocol) || url.username || url.password) throw new Error("Invalid media URL");
+    const url = this._checkedMediaUrl(media.fileId);
     const candidateExt = path.extname(media.fileName || url.pathname).toLowerCase();
     const ext = /^\.[a-z0-9]{1,8}$/.test(candidateExt) ? candidateExt : MIME_EXT[media.mimeType] || ".bin";
     const key = crypto.createHash("sha256").update(media.contextKey).digest("hex");
@@ -1477,7 +1712,7 @@ class KazeeAdapter {
     const timer = setTimeout(() => req?.destroy(new Error("Media download timed out")), Math.min(media.timeoutMs || 8000, 8000));
     try {
       const res = await new Promise((resolve, reject) => {
-        req = (url.protocol === "https:" ? https : http).get(url, resolve);
+        req = (url.protocol === "https:" ? https : http).get(url, this._mediaRequestOptions(url), resolve);
         req.on("error", reject);
       });
       if (res.statusCode !== 200 || Number(res.headers["content-length"]) > maxBytes) {
@@ -1599,21 +1834,37 @@ class KazeeAdapter {
     });
   }
 
-  _downloadUrl(url, localPath) {
-    return new Promise((resolve, reject) => {
-      const lib = url.startsWith("https:") ? https : http;
-      const out = fs.createWriteStream(localPath);
-      lib.get(url, (res) => {
-        if (res.statusCode && res.statusCode >= 400) {
-          out.destroy();
-          reject(new Error(`Download ${url} → ${res.statusCode}`));
-          return;
-        }
-        res.pipe(out);
-        out.on("finish", () => { out.close(); resolve(); });
-      }).on("error", reject);
-    });
+  // Streams to a .part file next to localPath, counting bytes; over the cap
+  // (declared or actual) or idle too long, it aborts and deletes the part.
+  async _downloadUrl(rawUrl, localPath) {
+    const url = this._checkedMediaUrl(rawUrl);
+    const maxBytes = this._maxDownloadBytes;
+    const tooBig = () => new Error(`Kazee media exceeds the ${Math.round(maxBytes / 1024 / 1024)} MB size limit`);
+    const partial = `${localPath}.${crypto.randomUUID()}.part`;
+    let req;
+    try {
+      const res = await new Promise((resolve, reject) => {
+        req = (url.protocol === "https:" ? https : http).get(url, this._mediaRequestOptions(url), resolve);
+        req.on("error", reject);
+        req.setTimeout(DOWNLOAD_IDLE_MS, () => req.destroy(new Error("Kazee download stalled")));
+      });
+      if (res.statusCode < 200 || res.statusCode >= 300) {
+        res.resume();
+        throw new Error(`Download from ${url.host} → ${res.statusCode}`);
+      }
+      if (Number(res.headers["content-length"]) > maxBytes) { res.destroy(); throw tooBig(); }
+      let bytes = 0;
+      await pipeline(res, new Transform({ transform(chunk, enc, done) {
+        bytes += chunk.length;
+        done(bytes > maxBytes ? tooBig() : null, chunk);
+      } }), fs.createWriteStream(partial, { flags: "wx" }));
+      fs.renameSync(partial, localPath);
+    } catch (e) {
+      req?.destroy();
+      try { fs.unlinkSync(partial); } catch (_) {}
+      throw e;
+    }
   }
 }
 
-module.exports = { KazeeAdapter };
+module.exports = { KazeeAdapter, isPublicAddress, publicOnlyLookup };