gupt-sdk 0.1.0 → 0.2.1

package/README.md

@@ -2,8 +2,8 @@
 
 Node.js SDK for running end-to-end encrypted GUPT bots over user-selected relays.
 
-The SDK currently supports one-to-one text messages. Use a dedicated bot identity; never reuse a
-personal GUPT key.
+The SDK supports one-to-one text, file, and voice-note messages. Use a dedicated bot identity;
+never reuse a personal GUPT key.
 
 ```js
 import { GuptBot } from "gupt-sdk";
@@ -14,6 +14,14 @@ const bot = new GuptBot({
 });
 
 bot.onMessage(async (ctx) => {
+  if (ctx.file) {
+    const downloaded = await ctx.downloadFile();
+    await ctx.replyFile(downloaded.data, {
+      name: downloaded.name,
+      mime: downloaded.mime,
+    });
+    return;
+  }
   if (ctx.text.startsWith("/echo ")) await ctx.reply(ctx.text.slice(6));
 });
 
@@ -24,6 +32,54 @@ await bot.start();
 At least two distinct `wss://` bootstrap relays are required. The default Originless server is
 `https://originless.gupt.app`; pass `originless` as a URL or URL array to override it.
 
+File contents use a separate AES-256-GCM key and nonce that remain inside the encrypted DM payload.
+`ctx.file` exposes safe metadata without downloading anything. `ctx.downloadFile()` fetches the CID
+through the configured Originless/IPFS gateways, enforces the advertised size, and returns a
+`Uint8Array`. `ctx.replyFile()` accepts a file path, `Blob`, `Buffer`, `Uint8Array`, or
+`ArrayBuffer`. The default per-file limit is 100 MiB and can be changed with
+`mediaOptions.maxBytes`.
+
+```js
+await ctx.replyFile("./report.pdf", {
+  name: "report.pdf",
+  mime: "application/pdf",
+  onProgress(update) {
+    console.log(update.phase, update.status);
+  },
+});
+```
+
+## Encrypted ntfy.sh-style notifications
+
+A bot can initiate a message using only the recipient's GUPT public key; `reply()` and `replyFile()`
+do not require a preceding inbound message. This makes `gupt-sdk` useful as an end-to-end encrypted,
+self-hosted alternative to ntfy.sh for monitoring jobs, backups, CI, and server alerts.
+
+```js
+import { GuptBot } from "gupt-sdk";
+
+const bot = new GuptBot({
+  secretHex: process.env.GUPT_BOT_KEY,
+  relays: ["wss://relay-a.example", "wss://relay-b.example"],
+});
+
+await bot.start();
+
+await bot.reply(process.env.GUPT_USER_PUBKEY, "Backup completed successfully");
+await bot.replyFile(process.env.GUPT_USER_PUBKEY, "./backup-report.txt", {
+  mime: "text/plain",
+});
+```
+
+Unlike a public notification topic, the recipient public key identifies who can decrypt the
+notification. Events remain encrypted on relays and carry GUPT's standard 100-day expiration.
+
+Public keys do not contain relay addresses. For reliable delivery, configure at least one relay
+that the recipient also uses, or have the recipient message the bot first so it can learn their
+signed relay hint. Learned hints are currently memory-only and are rediscovered after a bot
+restart. GUPT retrieves stored notifications when it reconnects, but this is not an operating-system
+push wake-up mechanism while the app is fully closed.
+
 Inbound messages teach the bot both the ingress relay and the sender relay hint carried in the
 signed `p` tag. Learned hints are bounded and obvious local/private addresses are rejected. Replies
 try the ingress relay first, then the peer's learned relays and the configured bootstrap relays.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gupt-sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Node.js SDK for building end-to-end encrypted GUPT bots",
   "homepage": "https://github.com/besoeasy/gupt/tree/main/sdk#readme",
   "bugs": "https://github.com/besoeasy/gupt/issues",
@@ -17,6 +17,7 @@
   "exports": {
     ".": "./src/index.js",
     "./ingestion": "./src/ingestion.js",
+    "./media": "./src/media.js",
     "./queue": "./src/queue.js",
     "./relay-book": "./src/relayBook.js",
     "./wire": "./src/wire.js"

package/src/index.js

@@ -1,4 +1,10 @@
 import { IngestionPipeline, RECENCY_WINDOW_MS } from "./ingestion.js";
+import {
+  createMediaPayload,
+  downloadMediaPayload,
+  MAX_MEDIA_BYTES,
+  parseMediaPayload,
+} from "./media.js";
 import { RelayPool } from "./pool.js";
 import { SendQueue } from "./queue.js";
 import { normalizeRelayUrl, RelayBook } from "./relayBook.js";
@@ -51,6 +57,7 @@ export class GuptBot {
     WebSocketImpl = globalThis.WebSocket,
     onDrop = null,
     logger = console,
+    mediaOptions = {},
     poolOptions = {},
     queueOptions = {},
   } = {}) {
@@ -91,6 +98,13 @@ export class GuptBot {
     this.maxHandlerBacklog = Math.max(1, Number(maxHandlerBacklog) || 1);
     this.acceptBotMessages = Boolean(acceptBotMessages);
     this.logger = logger;
+    this.mediaOptions = {
+      fetchImpl: mediaOptions.fetchImpl || globalThis.fetch,
+      gateways: mediaOptions.gateways,
+      maxBytes: Math.max(1, Number(mediaOptions.maxBytes) || MAX_MEDIA_BYTES),
+      uploadTimeoutMs: mediaOptions.uploadTimeoutMs,
+      downloadTimeoutMs: mediaOptions.downloadTimeoutMs,
+    };
     this.status = "idle";
     this.handlers = new Set();
     this.errorHandlers = new Set();
@@ -181,8 +195,19 @@ export class GuptBot {
     }
 
     const { payload, senderPubkey } = message;
-    if (payload.type !== "text" || typeof payload.text !== "string") return;
-    if (!payload.text.trim() || payload.text.length > MAX_TEXT_LENGTH) return;
+    let attachment = null;
+    if (payload.type === "text") {
+      if (typeof payload.text !== "string") return;
+      if (!payload.text.trim() || payload.text.length > MAX_TEXT_LENGTH) return;
+    } else if (payload.type === "media" || payload.type === "voice") {
+      try {
+        attachment = parseMediaPayload(payload, { maxBytes: this.mediaOptions.maxBytes });
+      } catch {
+        return;
+      }
+    } else {
+      return;
+    }
     if (payload.bot === true && !this.acceptBotMessages) return;
     if (this.allowlist && !this.allowlist.has(senderPubkey)) return;
 
@@ -203,7 +228,7 @@ export class GuptBot {
     const previous = this.handlerChains.get(senderPubkey) || Promise.resolve();
     const next = previous
       .catch(() => {})
-      .then(() => this.dispatchMessage(message))
+      .then(() => this.dispatchMessage(message, attachment))
       .catch((error) =>
         this.emitError(error, { eventId: message.event.id, senderPubkey: message.senderPubkey }),
       )
@@ -219,15 +244,34 @@ export class GuptBot {
     this.handlerChains.set(senderPubkey, next);
   }
 
-  async dispatchMessage(message) {
+  async dispatchMessage(message, attachment = null) {
+    const payload = Object.freeze({
+      ...message.payload,
+      ...(message.payload.media ? { media: Object.freeze({ ...message.payload.media }) } : {}),
+    });
+    const file = attachment
+      ? Object.freeze({
+          type: attachment.type,
+          name: attachment.name,
+          mime: attachment.mime,
+          size: attachment.size,
+          cid: attachment.cid,
+          durationMs: attachment.durationMs,
+        })
+      : null;
     const context = Object.freeze({
       id: message.event.id,
       senderPubkey: message.senderPubkey,
-      text: message.payload.text,
-      payload: Object.freeze({ ...message.payload }),
+      type: message.payload.type,
+      text: message.payload.text || "",
+      payload,
+      file,
       relayUrl: message.relayUrl,
       receivedAt: message.receivedAt,
       reply: (text) => this.reply(message.senderPubkey, text, message.relayUrl),
+      replyFile: (input, options) =>
+        this.replyFile(message.senderPubkey, input, options, message.relayUrl),
+      downloadFile: (options) => this.downloadFile(message.payload, options),
     });
     for (const handler of this.handlers) await handler(context);
   }
@@ -242,15 +286,58 @@ export class GuptBot {
     }
     this.reserveReply(peer);
 
-    const event = buildDirectMessageEvent({
-      secretHex: this.secretHex,
-      recipientPubkey: peer,
-      payload: {
+    return this.sendPayload(
+      peer,
+      {
         type: "text",
         text: replyText,
         ts: Date.now(),
         bot: true,
       },
+      ingressRelay,
+    );
+  }
+
+  async replyFile(peerPubkey, input, options = {}, ingressRelay = null) {
+    if (this.status !== "running") throw new Error("Bot is not running");
+    const peer = normalizePubkey(peerPubkey);
+    this.reserveReply(peer);
+    const payload = await createMediaPayload(input, {
+      fetchImpl: this.mediaOptions.fetchImpl,
+      maxBytes: this.mediaOptions.maxBytes,
+      timeoutMs: this.mediaOptions.uploadTimeoutMs,
+      ...options,
+      originlessServers: this.originlessServers,
+      allowPrivateServers: this.allowPrivateRelays,
+    });
+    return this.sendPayload(
+      peer,
+      {
+        ...payload,
+        ts: Date.now(),
+        bot: true,
+      },
+      ingressRelay,
+    );
+  }
+
+  downloadFile(payload, options = {}) {
+    return downloadMediaPayload(payload, {
+      fetchImpl: this.mediaOptions.fetchImpl,
+      gateways: this.mediaOptions.gateways,
+      maxBytes: this.mediaOptions.maxBytes,
+      timeoutMs: this.mediaOptions.downloadTimeoutMs,
+      ...options,
+      originlessServers: this.originlessServers,
+      allowPrivateServers: this.allowPrivateRelays,
+    });
+  }
+
+  sendPayload(peer, payload, ingressRelay) {
+    const event = buildDirectMessageEvent({
+      secretHex: this.secretHex,
+      recipientPubkey: peer,
+      payload,
     });
     const targets = this.relayBook.replyRelays(peer, ingressRelay);
     return this.queue.enqueue({
@@ -296,6 +383,7 @@ export class GuptBot {
 }
 
 export * from "./ingestion.js";
+export * from "./media.js";
 export * from "./queue.js";
 export * from "./relayBook.js";
 export * from "./wire.js";

package/src/media.js

@@ -0,0 +1,477 @@
+import { readFile, stat } from "node:fs/promises";
+import { basename } from "node:path";
+
+import { gcm } from "@noble/ciphers/aes.js";
+
+export const MAX_MEDIA_BYTES = 100 * 1024 * 1024;
+export const MEDIA_FETCH_TIMEOUT_MS = 10_000;
+export const MEDIA_UPLOAD_BASE_TIMEOUT_MS = 30_000;
+export const MEDIA_UPLOAD_MIN_BYTES_PER_SEC = 50_000;
+export const MEDIA_UPLOAD_REDUNDANCY = 2;
+export const PUBLIC_IPFS_GATEWAYS = Object.freeze([
+  "https://ipfs.io/ipfs/",
+  "https://inbrowser.link/ipfs/",
+]);
+
+const BASE64_RE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+const CID_RE = /^[A-Za-z0-9]{10,200}$/;
+
+export class MediaError extends Error {
+  constructor(message, kind = "unknown", options) {
+    super(message, options);
+    this.name = "MediaError";
+    this.kind = kind;
+  }
+}
+
+function asBytes(value) {
+  if (value instanceof Uint8Array) {
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  }
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  }
+  return null;
+}
+
+function encodeBase64(value) {
+  return Buffer.from(value).toString("base64");
+}
+
+function decodeBase64(value, expectedLength, label) {
+  const encoded = String(value || "").trim();
+  if (!encoded || !BASE64_RE.test(encoded)) {
+    throw new MediaError(`Invalid media ${label}.`, "payload");
+  }
+  const bytes = Buffer.from(encoded, "base64");
+  if (bytes.length !== expectedLength) {
+    throw new MediaError(`Invalid media ${label} length.`, "payload");
+  }
+  return new Uint8Array(bytes);
+}
+
+function normalizeCid(value) {
+  const cid = String(value || "").trim();
+  if (!CID_RE.test(cid)) throw new MediaError("Invalid or missing media CID.", "payload");
+  return cid;
+}
+
+function normalizeName(value) {
+  const name = basename(String(value || "").trim()).slice(0, 255);
+  return name || "attachment.bin";
+}
+
+function normalizeMime(value) {
+  return (
+    String(value || "application/octet-stream")
+      .trim()
+      .slice(0, 200) || "application/octet-stream"
+  );
+}
+
+function normalizeSize(value, maxBytes) {
+  const size = Number(value);
+  if (!Number.isSafeInteger(size) || size < 0) {
+    throw new MediaError("Invalid media size.", "payload");
+  }
+  if (size > maxBytes) throw new MediaError(`Media exceeds the ${maxBytes}-byte limit.`, "size");
+  return size;
+}
+
+function normalizeServer(value, allowPrivate = false) {
+  try {
+    const url = new URL(String(value || "").trim());
+    if (url.username || url.password || url.search || url.hash) return null;
+    if (url.protocol !== "https:" && !(allowPrivate && url.protocol === "http:")) return null;
+    url.pathname = url.pathname.replace(/\/upload\/?$/i, "").replace(/\/+$/, "");
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    return null;
+  }
+}
+
+function normalizeGateway(value) {
+  try {
+    const url = new URL(String(value || "").trim());
+    if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) {
+      return null;
+    }
+    return url.toString().replace(/\/+$/, "") + "/";
+  } catch {
+    return null;
+  }
+}
+
+function pickUploadCid(payload) {
+  if (!payload || typeof payload !== "object") return null;
+  const direct = payload.cid || payload.CID || payload.hash || payload.Hash || payload.ipfs;
+  if (typeof direct === "string" && direct.trim()) return direct.trim();
+  return pickUploadCid(payload.value);
+}
+
+async function attachmentInput(input, options, maxBytes) {
+  let bytes;
+  let inferredName = "";
+  let inferredMime = "";
+
+  if (typeof input === "string") {
+    const details = await stat(input);
+    if (!details.isFile()) throw new MediaError("Attachment path must be a regular file.", "input");
+    if (details.size > maxBytes) {
+      throw new MediaError(`Media exceeds the ${maxBytes}-byte limit.`, "size");
+    }
+    bytes = new Uint8Array(await readFile(input));
+    inferredName = basename(input);
+  } else if (typeof Blob !== "undefined" && input instanceof Blob) {
+    if (input.size > maxBytes) {
+      throw new MediaError(`Media exceeds the ${maxBytes}-byte limit.`, "size");
+    }
+    bytes = new Uint8Array(await input.arrayBuffer());
+    inferredName = typeof input.name === "string" ? input.name : "";
+    inferredMime = input.type;
+  } else {
+    bytes = asBytes(input);
+  }
+
+  if (!bytes) {
+    throw new TypeError("File input must be a path, Blob, Buffer, Uint8Array, or ArrayBuffer");
+  }
+  if (bytes.byteLength > maxBytes) {
+    throw new MediaError(`Media exceeds the ${maxBytes}-byte limit.`, "size");
+  }
+
+  return {
+    bytes,
+    name: normalizeName(options.name || inferredName),
+    mime: normalizeMime(options.mime || inferredMime),
+  };
+}
+
+export function parseMediaPayload(payload, { maxBytes = MAX_MEDIA_BYTES } = {}) {
+  const type = String(payload?.type || "");
+  if (type !== "media" && type !== "voice") return null;
+  const media = payload?.media;
+  if (!media || typeof media !== "object" || Array.isArray(media)) {
+    throw new MediaError("Missing media payload.", "payload");
+  }
+
+  return {
+    type,
+    name: normalizeName(media.name || payload.text),
+    mime: normalizeMime(media.mime),
+    size: normalizeSize(media.size, maxBytes),
+    cid: normalizeCid(media.cid),
+    durationMs: Number.isFinite(Number(payload.durationMs))
+      ? Math.max(0, Number(payload.durationMs))
+      : 0,
+    key: decodeBase64(media.key, 32, "key"),
+    nonce: decodeBase64(media.nonce, 12, "nonce"),
+  };
+}
+
+export function encryptAttachmentBytes(value, options = {}) {
+  const bytes = asBytes(value);
+  if (!bytes) throw new TypeError("Attachment data must be bytes");
+  const key = options.key
+    ? Uint8Array.from(options.key)
+    : crypto.getRandomValues(new Uint8Array(32));
+  const nonce = options.nonce
+    ? Uint8Array.from(options.nonce)
+    : crypto.getRandomValues(new Uint8Array(12));
+  if (key.length !== 32) throw new TypeError("Media key must contain 32 bytes");
+  if (nonce.length !== 12) throw new TypeError("Media nonce must contain 12 bytes");
+  return {
+    encrypted: gcm(key, nonce).encrypt(bytes),
+    key,
+    nonce,
+  };
+}
+
+export function decryptAttachmentBytes(encrypted, key, nonce) {
+  const ciphertext = asBytes(encrypted);
+  if (!ciphertext) throw new TypeError("Encrypted attachment must be bytes");
+  try {
+    return gcm(Uint8Array.from(key), Uint8Array.from(nonce)).decrypt(ciphertext);
+  } catch (error) {
+    throw new MediaError("Unable to decrypt media attachment.", "decrypt", { cause: error });
+  }
+}
+
+function uploadTimeoutMs(size, override) {
+  if (override != null) return Math.max(1, Number(override) || 1);
+  return Math.max(
+    MEDIA_UPLOAD_BASE_TIMEOUT_MS,
+    Math.ceil((size / MEDIA_UPLOAD_MIN_BYTES_PER_SEC) * 1000),
+  );
+}
+
+async function uploadOne(server, encrypted, name, options) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+  const abort = () => controller.abort(options.signal?.reason);
+  options.signal?.addEventListener("abort", abort, { once: true });
+  if (options.signal?.aborted) abort();
+
+  try {
+    const form = new FormData();
+    form.append("file", new Blob([encrypted], { type: "application/octet-stream" }), `${name}.enc`);
+    const response = await options.fetchImpl(`${server}/upload`, {
+      method: "POST",
+      body: form,
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      const detail = (await response.text().catch(() => "")).trim().slice(0, 200);
+      throw new MediaError(
+        `Upload failed (${response.status})${detail ? `: ${detail}` : ""}`,
+        "upload",
+      );
+    }
+    const cid = normalizeCid(pickUploadCid(await response.json()));
+    return { cid, server };
+  } catch (error) {
+    if (error instanceof MediaError) throw error;
+    throw new MediaError(error?.message || "Media upload failed.", "upload", { cause: error });
+  } finally {
+    clearTimeout(timeout);
+    options.signal?.removeEventListener("abort", abort);
+  }
+}
+
+export async function uploadEncryptedAttachment(
+  encrypted,
+  {
+    name = "attachment.bin",
+    originlessServers,
+    fetchImpl = globalThis.fetch,
+    timeoutMs,
+    signal,
+    allowPrivateServers = false,
+    onProgress,
+  } = {},
+) {
+  if (typeof fetchImpl !== "function") throw new TypeError("A fetch implementation is required");
+  const bytes = asBytes(encrypted);
+  if (!bytes) throw new TypeError("Encrypted attachment must be bytes");
+  const servers = [
+    ...new Set(
+      (Array.isArray(originlessServers) ? originlessServers : [])
+        .map((server) => normalizeServer(server, allowPrivateServers))
+        .filter(Boolean),
+    ),
+  ];
+  if (!servers.length) throw new MediaError("No valid Originless server configured.", "upload");
+
+  const target = Math.min(MEDIA_UPLOAD_REDUNDANCY, servers.length);
+  const successes = [];
+  const failures = [];
+  let cursor = 0;
+
+  async function worker() {
+    while (cursor < servers.length && successes.length < target) {
+      const server = servers[cursor++];
+      onProgress?.({ phase: "uploading", status: "started", server });
+      try {
+        const result = await uploadOne(server, bytes, normalizeName(name), {
+          fetchImpl,
+          timeoutMs: uploadTimeoutMs(bytes.byteLength, timeoutMs),
+          signal,
+        });
+        successes.push(result);
+        onProgress?.({ phase: "uploading", status: "done", server });
+      } catch (error) {
+        failures.push(error);
+        onProgress?.({ phase: "uploading", status: "failed", server, error: error.message });
+      }
+    }
+  }
+
+  await Promise.all(Array.from({ length: target }, () => worker()));
+  if (!successes.length) {
+    throw new MediaError(
+      failures
+        .map((error) => error.message)
+        .filter(Boolean)
+        .join(" | ") || "Upload failed on all Originless servers.",
+      "upload",
+    );
+  }
+  return {
+    cid: successes[0].cid,
+    server: successes[0].server,
+    servers: successes.map((result) => result.server),
+    redundancyCount: successes.length,
+  };
+}
+
+export async function createMediaPayload(
+  input,
+  {
+    originlessServers,
+    type = "media",
+    name,
+    mime,
+    durationMs = 0,
+    maxBytes = MAX_MEDIA_BYTES,
+    fetchImpl = globalThis.fetch,
+    timeoutMs,
+    signal,
+    allowPrivateServers = false,
+    onProgress,
+  } = {},
+) {
+  if (type !== "media" && type !== "voice") {
+    throw new TypeError("Attachment type must be media or voice");
+  }
+  const attachment = await attachmentInput(input, { name, mime }, maxBytes);
+  onProgress?.({ phase: "encrypting", status: "started" });
+  const { encrypted, key, nonce } = encryptAttachmentBytes(attachment.bytes);
+  onProgress?.({ phase: "encrypting", status: "done" });
+  const uploaded = await uploadEncryptedAttachment(encrypted, {
+    name: attachment.name,
+    originlessServers,
+    fetchImpl,
+    timeoutMs,
+    signal,
+    allowPrivateServers,
+    onProgress,
+  });
+  return {
+    type,
+    text: attachment.name,
+    media: {
+      key: encodeBase64(key),
+      nonce: encodeBase64(nonce),
+      mime: attachment.mime,
+      name: attachment.name,
+      size: attachment.bytes.byteLength,
+      cid: uploaded.cid,
+    },
+    durationMs: Number.isFinite(Number(durationMs)) ? Math.max(0, Number(durationMs)) : 0,
+  };
+}
+
+async function readBoundedResponse(response, maxBytes) {
+  if (!response.ok) throw new MediaError(`Media fetch failed (${response.status}).`, "fetch");
+  const contentLength = Number(response.headers.get("content-length"));
+  if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+    throw new MediaError("Encrypted media response is too large.", "size");
+  }
+  if (!response.body?.getReader) {
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if (bytes.byteLength > maxBytes) {
+      throw new MediaError("Encrypted media response is too large.", "size");
+    }
+    return bytes;
+  }
+
+  const chunks = [];
+  let total = 0;
+  const reader = response.body.getReader();
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel();
+      throw new MediaError("Encrypted media response is too large.", "size");
+    }
+    chunks.push(value);
+  }
+  const result = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return result;
+}
+
+async function fetchEncrypted(url, options) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+  const abort = () => controller.abort(options.signal?.reason);
+  options.signal?.addEventListener("abort", abort, { once: true });
+  if (options.signal?.aborted) abort();
+  try {
+    const response = await options.fetchImpl(url, { signal: controller.signal });
+    return await readBoundedResponse(response, options.maxBytes);
+  } finally {
+    clearTimeout(timeout);
+    options.signal?.removeEventListener("abort", abort);
+  }
+}
+
+export async function downloadMediaPayload(
+  payload,
+  {
+    originlessServers = [],
+    gateways = PUBLIC_IPFS_GATEWAYS,
+    fetchImpl = globalThis.fetch,
+    timeoutMs = MEDIA_FETCH_TIMEOUT_MS,
+    maxBytes = MAX_MEDIA_BYTES,
+    signal,
+    allowPrivateServers = false,
+  } = {},
+) {
+  if (typeof fetchImpl !== "function") throw new TypeError("A fetch implementation is required");
+  const attachment = parseMediaPayload(payload, { maxBytes });
+  if (!attachment) throw new MediaError("Message does not contain a file.", "payload");
+
+  const originless = (Array.isArray(originlessServers) ? originlessServers : [])
+    .map((server) => normalizeServer(server, allowPrivateServers))
+    .filter(Boolean)
+    .map((server) => `${server}/ipfs/`);
+  const gatewayBases = (Array.isArray(gateways) ? gateways : [])
+    .map(normalizeGateway)
+    .filter(Boolean);
+  const urls = [...new Set([...originless, ...gatewayBases])].map(
+    (base) => `${base}${attachment.cid}`,
+  );
+  if (!urls.length) throw new MediaError("No media download gateway configured.", "fetch");
+
+  const controllers = urls.map(() => new AbortController());
+  const abortAll = () => controllers.forEach((controller) => controller.abort(signal?.reason));
+  signal?.addEventListener("abort", abortAll, { once: true });
+  if (signal?.aborted) abortAll();
+  try {
+    const result = await Promise.any(
+      urls.map(async (url, index) => {
+        const encrypted = await fetchEncrypted(url, {
+          fetchImpl,
+          timeoutMs,
+          maxBytes: attachment.size + 16,
+          signal: controllers[index].signal,
+        });
+        const data = decryptAttachmentBytes(encrypted, attachment.key, attachment.nonce);
+        if (data.byteLength !== attachment.size) {
+          throw new MediaError("Decrypted media size does not match its payload.", "decrypt");
+        }
+        controllers.forEach((controller, controllerIndex) => {
+          if (controllerIndex !== index) controller.abort();
+        });
+        return {
+          data,
+          name: attachment.name,
+          mime: attachment.mime,
+          size: attachment.size,
+          cid: attachment.cid,
+          type: attachment.type,
+          durationMs: attachment.durationMs,
+          sourceUrl: url,
+        };
+      }),
+    );
+    return result;
+  } catch (error) {
+    const reason = error instanceof AggregateError ? error.errors?.find(Boolean) : error;
+    if (reason instanceof MediaError) throw reason;
+    throw new MediaError(reason?.message || "Unable to download media.", "fetch", {
+      cause: reason,
+    });
+  } finally {
+    abortAll();
+    signal?.removeEventListener("abort", abortAll);
+  }
+}