@openclaw/msteams 2026.3.13 → 2026.5.2-beta.1

package/src/attachments/remote-media.ts

@@ -1,10 +1,61 @@
-import type { SsrFPolicy } from "openclaw/plugin-sdk/msteams";
+import { readResponseWithLimit } from "openclaw/plugin-sdk/media-runtime";
+import type { SsrFPolicy } from "../../runtime-api.js";
 import { getMSTeamsRuntime } from "../runtime.js";
 import { inferPlaceholder } from "./shared.js";
 import type { MSTeamsInboundMedia } from "./types.js";
 
 type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 
+type FetchedRemoteMedia = {
+  buffer: Buffer;
+  contentType?: string;
+};
+
+/**
+ * Direct fetch path used when the caller's `fetchImpl` has already validated
+ * the URL against a hostname allowlist (for example `safeFetchWithPolicy`).
+ *
+ * Bypasses the strict SSRF dispatcher on `fetchRemoteMedia` because:
+ *   1. The pinned undici dispatcher used by `fetchRemoteMedia` is incompatible
+ *      with Node 24+'s built-in undici v7 (fails with "invalid onRequestStart
+ *      method"), which silently breaks SharePoint/OneDrive downloads. See
+ *      issue #63396.
+ *   2. SSRF protection is already enforced by the caller's `fetchImpl`
+ *      (`safeFetch` validates every redirect hop against the hostname
+ *      allowlist before following).
+ */
+async function fetchRemoteMediaDirect(params: {
+  url: string;
+  fetchImpl: FetchLike;
+  maxBytes: number;
+}): Promise<FetchedRemoteMedia> {
+  const response = await params.fetchImpl(params.url, { redirect: "follow" });
+  if (!response.ok) {
+    const statusText = response.statusText ? ` ${response.statusText}` : "";
+    throw new Error(`HTTP ${response.status}${statusText}`);
+  }
+
+  // Enforce the max-bytes cap before buffering the full body so a rogue
+  // response cannot drive RSS usage past the configured limit.
+  const contentLength = response.headers.get("content-length");
+  if (contentLength) {
+    const length = Number(contentLength);
+    if (Number.isFinite(length) && length > params.maxBytes) {
+      throw new Error(`content length ${length} exceeds maxBytes ${params.maxBytes}`);
+    }
+  }
+
+  const buffer = await readResponseWithLimit(response, params.maxBytes, {
+    onOverflow: ({ size, maxBytes }) =>
+      new Error(`payload size ${size} exceeds maxBytes ${maxBytes}`),
+  });
+
+  return {
+    buffer,
+    contentType: response.headers.get("content-type") ?? undefined,
+  };
+}
+
 export async function downloadAndStoreMSTeamsRemoteMedia(params: {
   url: string;
   filePathHint: string;
@@ -14,14 +65,30 @@ export async function downloadAndStoreMSTeamsRemoteMedia(params: {
   contentTypeHint?: string;
   placeholder?: string;
   preserveFilenames?: boolean;
+  /**
+   * Opt into a direct fetch path that bypasses `fetchRemoteMedia`'s strict
+   * SSRF dispatcher. Required for SharePoint/OneDrive downloads on Node 24+
+   * (see issue #63396). Only safe when the supplied `fetchImpl` has already
+   * validated the URL against a hostname allowlist.
+   */
+  useDirectFetch?: boolean;
 }): Promise<MSTeamsInboundMedia> {
-  const fetched = await getMSTeamsRuntime().channel.media.fetchRemoteMedia({
-    url: params.url,
-    fetchImpl: params.fetchImpl,
-    filePathHint: params.filePathHint,
-    maxBytes: params.maxBytes,
-    ssrfPolicy: params.ssrfPolicy,
-  });
+  let fetched: FetchedRemoteMedia;
+  if (params.useDirectFetch && params.fetchImpl) {
+    fetched = await fetchRemoteMediaDirect({
+      url: params.url,
+      fetchImpl: params.fetchImpl,
+      maxBytes: params.maxBytes,
+    });
+  } else {
+    fetched = await getMSTeamsRuntime().channel.media.fetchRemoteMedia({
+      url: params.url,
+      fetchImpl: params.fetchImpl,
+      filePathHint: params.filePathHint,
+      maxBytes: params.maxBytes,
+      ssrfPolicy: params.ssrfPolicy,
+    });
+  }
   const mime = await getMSTeamsRuntime().media.detectMime({
     buffer: fetched.buffer,
     headerMime: fetched.contentType ?? params.contentTypeHint,

package/src/attachments/shared.test.ts

@@ -1,6 +1,9 @@
 import { describe, expect, it, vi } from "vitest";
 import {
   applyAuthorizationHeaderForUrl,
+  encodeGraphShareId,
+  extractInlineImageCandidates,
+  isGraphSharedLinkUrl,
   isPrivateOrReservedIP,
   isUrlAllowed,
   resolveAndValidateIP,
@@ -10,6 +13,7 @@ import {
   resolveMediaSsrfPolicy,
   safeFetch,
   safeFetchWithPolicy,
+  tryBuildGraphSharesUrlForSharedLink,
 } from "./shared.js";
 
 const publicResolve = async () => ({ address: "13.107.136.10" });
@@ -216,7 +220,9 @@ describe("safeFetch", () => {
     const rebindingResolve = async () => {
       callCount++;
       // First call (initial URL) resolves to public IP
-      if (callCount === 1) return { address: "13.107.136.10" };
+      if (callCount === 1) {
+        return { address: "13.107.136.10" };
+      }
       // Second call (redirect target) resolves to private IP
       return { address: "169.254.169.254" };
     };
@@ -248,6 +254,18 @@ describe("safeFetch", () => {
     expect(fetchMock).not.toHaveBeenCalled();
   });
 
+  it("blocks private hosts with the default resolver", async () => {
+    const fetchMock = vi.fn();
+    await expect(
+      safeFetch({
+        url: "https://localhost/file.pdf",
+        allowHosts: ["localhost"],
+        fetchFn: fetchMock as unknown as typeof fetch,
+      }),
+    ).rejects.toThrow("Initial download URL blocked");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
   it("blocks when initial URL DNS resolution fails", async () => {
     const fetchMock = vi.fn();
     await expect(
@@ -391,3 +409,122 @@ describe("attachment fetch auth helpers", () => {
     expect(fetchMock).toHaveBeenCalledOnce();
   });
 });
+
+describe("Graph shared-link helpers", () => {
+  it.each([
+    ["https://contoso.sharepoint.com/personal/user/Documents/report.pdf", true],
+    ["https://contoso.sharepoint.us/sites/team/file.docx", true],
+    ["https://contoso.sharepoint.cn/file", true],
+    ["https://tenant-my.sharepoint.com/:b:/g/personal/file", true],
+    ["https://1drv.ms/b/s!AkxYabc", true],
+    ["https://onedrive.live.com/view.aspx?resid=ABC", true],
+    ["https://onedrive.com/share/abc", true],
+    ["https://graph.microsoft.com/v1.0/me", false],
+    ["https://smba.trafficmanager.net/amer/v3", false],
+    ["https://example.com/file.pdf", false],
+    ["not-a-url", false],
+  ])("isGraphSharedLinkUrl(%s) === %s", (url, expected) => {
+    expect(isGraphSharedLinkUrl(url)).toBe(expected);
+  });
+
+  it("encodeGraphShareId uses u! + base64url without padding", () => {
+    // Graph docs example: encoding "https://onedrive.live.com/redir?resid=..."
+    // should yield u!aHR0cHM6... (base64url, no '+', '/', or trailing '=').
+    const url = "https://contoso.sharepoint.com/sites/a/Shared Documents/file.pdf";
+    const shareId = encodeGraphShareId(url);
+    expect(shareId.startsWith("u!")).toBe(true);
+    const encoded = shareId.slice(2);
+    // base64url alphabet is A-Z, a-z, 0-9, '-', '_' (no padding).
+    expect(encoded).toMatch(/^[A-Za-z0-9_-]+$/);
+    // Round-trip check: decoding yields the original URL.
+    const decoded = Buffer.from(encoded, "base64url").toString("utf8");
+    expect(decoded).toBe(url);
+  });
+
+  it("encodeGraphShareId swaps '+' and '/' for '-' and '_'", () => {
+    // A URL whose standard base64 contains '+' and '/' chars.
+    // Choose an input that base64 encodes with those characters.
+    const url = "https://host.sharepoint.com/sites/path?x=???";
+    const shareId = encodeGraphShareId(url);
+    const encoded = shareId.slice(2);
+    expect(encoded).not.toContain("+");
+    expect(encoded).not.toContain("/");
+    expect(encoded).not.toContain("=");
+  });
+
+  it("tryBuildGraphSharesUrlForSharedLink rewrites SharePoint URLs", () => {
+    const url = "https://contoso.sharepoint.com/personal/user/Documents/report.pdf";
+    const result = tryBuildGraphSharesUrlForSharedLink(url);
+    expect(result).toBeDefined();
+    expect(result).toMatch(
+      /^https:\/\/graph\.microsoft\.com\/v1\.0\/shares\/u![A-Za-z0-9_-]+\/driveItem\/content$/,
+    );
+  });
+
+  it("tryBuildGraphSharesUrlForSharedLink rewrites OneDrive URLs", () => {
+    const url = "https://1drv.ms/b/s!AkxYabcdefg";
+    const result = tryBuildGraphSharesUrlForSharedLink(url);
+    expect(result).toBeDefined();
+    expect(result).toMatch(
+      /^https:\/\/graph\.microsoft\.com\/v1\.0\/shares\/u![A-Za-z0-9_-]+\/driveItem\/content$/,
+    );
+  });
+
+  it("tryBuildGraphSharesUrlForSharedLink returns undefined for non-shared URLs", () => {
+    expect(
+      tryBuildGraphSharesUrlForSharedLink("https://graph.microsoft.com/v1.0/me"),
+    ).toBeUndefined();
+    expect(tryBuildGraphSharesUrlForSharedLink("https://example.com/file.pdf")).toBeUndefined();
+    expect(tryBuildGraphSharesUrlForSharedLink("not-a-url")).toBeUndefined();
+  });
+});
+
+describe("msteams inline image limits", () => {
+  const smallPngDataUrl = "data:image/png;base64,aGVsbG8="; // "hello" (5 bytes)
+
+  it("rejects inline data images above per-image limit", () => {
+    const attachments = [
+      {
+        contentType: "text/html",
+        content: `<img src="${smallPngDataUrl}" />`,
+      },
+    ];
+    const out = extractInlineImageCandidates(attachments, { maxInlineBytes: 4 });
+    expect(out).toEqual([]);
+  });
+
+  it("accepts inline data images within limit", () => {
+    const attachments = [
+      {
+        contentType: "text/html",
+        content: `<img src="${smallPngDataUrl}" />`,
+      },
+    ];
+    const out = extractInlineImageCandidates(attachments, { maxInlineBytes: 10 });
+    expect(out.length).toBe(1);
+    expect(out[0]?.kind).toBe("data");
+    if (out[0]?.kind === "data") {
+      expect(out[0].data.byteLength).toBeGreaterThan(0);
+      expect(out[0].contentType).toBe("image/png");
+    }
+  });
+
+  it("enforces cumulative inline size limit across attachments", () => {
+    const attachments = [
+      {
+        contentType: "text/html",
+        content: `<img src="${smallPngDataUrl}" />`,
+      },
+      {
+        contentType: "text/html",
+        content: `<img src="${smallPngDataUrl}" />`,
+      },
+    ];
+    const out = extractInlineImageCandidates(attachments, {
+      maxInlineBytes: 10,
+      maxInlineTotalBytes: 6,
+    });
+    expect(out.length).toBe(1);
+    expect(out[0]?.kind).toBe("data");
+  });
+});

package/src/attachments/shared.ts

@@ -1,11 +1,17 @@
+import { Buffer } from "node:buffer";
 import { lookup } from "node:dns/promises";
 import {
   buildHostnameAllowlistPolicyFromSuffixAllowlist,
   isHttpsUrlAllowedByHostnameSuffixAllowlist,
   isPrivateIpAddress,
   normalizeHostnameSuffixAllowlist,
-} from "openclaw/plugin-sdk/msteams";
-import type { SsrFPolicy } from "openclaw/plugin-sdk/msteams";
+  type SsrFPolicy,
+} from "openclaw/plugin-sdk/ssrf-policy";
+import {
+  isRecord,
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalString,
+} from "openclaw/plugin-sdk/text-runtime";
 import type { MSTeamsAttachmentLike } from "./types.js";
 
 type InlineImageCandidate =
@@ -23,12 +29,17 @@ type InlineImageCandidate =
       placeholder: string;
     };
 
-export const IMAGE_EXT_RE = /\.(avif|bmp|gif|heic|heif|jpe?g|png|tiff?|webp)$/i;
+type InlineImageLimitOptions = {
+  maxInlineBytes?: number;
+  maxInlineTotalBytes?: number;
+};
+
+const IMAGE_EXT_RE = /\.(avif|bmp|gif|heic|heif|jpe?g|png|tiff?|webp)$/i;
 
 export const IMG_SRC_RE = /<img[^>]+src=["']([^"']+)["'][^>]*>/gi;
 export const ATTACHMENT_TAG_RE = /<attachment[^>]+id=["']([^"']+)["'][^>]*>/gi;
 
-export const DEFAULT_MEDIA_HOST_ALLOWLIST = [
+const DEFAULT_MEDIA_HOST_ALLOWLIST = [
   "graph.microsoft.com",
   "graph.microsoft.us",
   "graph.microsoft.de",
@@ -56,9 +67,12 @@ export const DEFAULT_MEDIA_HOST_ALLOWLIST = [
   "microsoft.com",
 ] as const;
 
-export const DEFAULT_MEDIA_AUTH_HOST_ALLOWLIST = [
+const DEFAULT_MEDIA_AUTH_HOST_ALLOWLIST = [
   "api.botframework.com",
   "botframework.com",
+  // Bot Framework Service URL (smba.trafficmanager.net) used for outbound
+  // replies and inbound attachment downloads (clipboard-pasted images).
+  "smba.trafficmanager.net",
   "graph.microsoft.com",
   "graph.microsoft.us",
   "graph.microsoft.de",
@@ -66,9 +80,114 @@ export const DEFAULT_MEDIA_AUTH_HOST_ALLOWLIST = [
 ] as const;
 
 export const GRAPH_ROOT = "https://graph.microsoft.com/v1.0";
+export { isRecord };
+
+// Keep this local; importing the broad media-runtime SDK barrel pulls image/audio runtimes into
+// hot MSTeams attachment tests for one tiny estimator.
+export function estimateBase64DecodedBytes(base64: string): number {
+  let effectiveLen = 0;
+  for (let i = 0; i < base64.length; i += 1) {
+    const code = base64.charCodeAt(i);
+    if (code <= 0x20) {
+      continue;
+    }
+    effectiveLen += 1;
+  }
+
+  if (effectiveLen === 0) {
+    return 0;
+  }
+
+  let padding = 0;
+  let end = base64.length - 1;
+  while (end >= 0 && base64.charCodeAt(end) <= 0x20) {
+    end -= 1;
+  }
+  if (end >= 0 && base64[end] === "=") {
+    padding = 1;
+    end -= 1;
+    while (end >= 0 && base64.charCodeAt(end) <= 0x20) {
+      end -= 1;
+    }
+    if (end >= 0 && base64[end] === "=") {
+      padding = 2;
+    }
+  }
+
+  const estimated = Math.floor((effectiveLen * 3) / 4) - padding;
+  return Math.max(0, estimated);
+}
+
+/**
+ * Host suffixes for SharePoint/OneDrive shared links that must be fetched via
+ * the Graph `/shares/{shareId}/driveItem/content` endpoint instead of directly.
+ *
+ * Direct fetches of SharePoint/OneDrive shared URLs return empty/HTML landing
+ * pages unless encoded as a Graph share id. See
+ * https://learn.microsoft.com/en-us/graph/api/shares-get for the encoding.
+ */
+const GRAPH_SHARED_LINK_HOST_SUFFIXES = [
+  ".sharepoint.com",
+  ".sharepoint.us",
+  ".sharepoint.de",
+  ".sharepoint.cn",
+  ".sharepoint-df.com",
+  "1drv.ms",
+  "onedrive.live.com",
+  "onedrive.com",
+] as const;
+
+/**
+ * Returns true when the URL points at a SharePoint or OneDrive host whose
+ * shared-link content must be fetched through the Graph shares API rather
+ * than directly.
+ */
+export function isGraphSharedLinkUrl(url: string): boolean {
+  let host: string;
+  try {
+    host = normalizeLowercaseStringOrEmpty(new URL(url).hostname);
+  } catch {
+    return false;
+  }
+  if (!host) {
+    return false;
+  }
+  return GRAPH_SHARED_LINK_HOST_SUFFIXES.some((suffix) => host === suffix || host.endsWith(suffix));
+}
 
-export function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+/**
+ * Encode a SharePoint/OneDrive URL as a Graph shareId using the documented
+ * `u!` + base64url (no padding) scheme:
+ * https://learn.microsoft.com/en-us/graph/api/shares-get#encoding-sharing-urls
+ */
+export function encodeGraphShareId(url: string): string {
+  // Buffer.from(...).toString("base64url") already returns base64url without
+  // padding, matching the Graph spec exactly.
+  return `u!${Buffer.from(url, "utf8").toString("base64url")}`;
+}
+
+/**
+ * When `url` is a SharePoint/OneDrive shared link, return the matching
+ * `GET /shares/{shareId}/driveItem/content` URL that actually yields the file
+ * bytes. Returns `undefined` for non-shared-link URLs so callers can fall
+ * through to the existing fetch path.
+ */
+export function tryBuildGraphSharesUrlForSharedLink(url: string): string | undefined {
+  if (!isGraphSharedLinkUrl(url)) {
+    return undefined;
+  }
+  return `${GRAPH_ROOT}/shares/${encodeGraphShareId(url)}/driveItem/content`;
+}
+
+export function readNestedString(value: unknown, keys: Array<string | number>): string | undefined {
+  let current: unknown = value;
+  for (const key of keys) {
+    if (!isRecord(current)) {
+      return undefined;
+    }
+    current = current[key as keyof typeof current];
+  }
+  return normalizeOptionalString(current);
 }
 
 export function resolveRequestUrl(input: RequestInfo | URL): string {
@@ -81,7 +200,11 @@ export function resolveRequestUrl(input: RequestInfo | URL): string {
   if (typeof input === "object" && input && "url" in input && typeof input.url === "string") {
     return input.url;
   }
-  return String(input);
+  try {
+    return JSON.stringify(input);
+  } catch {
+    return "";
+  }
 }
 
 export function normalizeContentType(value: unknown): string | undefined {
@@ -97,9 +220,9 @@ export function inferPlaceholder(params: {
   fileName?: string;
   fileType?: string;
 }): string {
-  const mime = params.contentType?.toLowerCase() ?? "";
-  const name = params.fileName?.toLowerCase() ?? "";
-  const fileType = params.fileType?.toLowerCase() ?? "";
+  const mime = normalizeLowercaseStringOrEmpty(params.contentType ?? "");
+  const name = normalizeLowercaseStringOrEmpty(params.fileName ?? "");
+  const fileType = normalizeLowercaseStringOrEmpty(params.fileType ?? "");
 
   const looksLikeImage =
     mime.startsWith("image/") || IMAGE_EXT_RE.test(name) || IMAGE_EXT_RE.test(`x.${fileType}`);
@@ -184,25 +307,44 @@ export function extractHtmlFromAttachment(att: MSTeamsAttachmentLike): string |
   return text;
 }
 
-function decodeDataImage(src: string): InlineImageCandidate | null {
+function isLikelyBase64Payload(value: string): boolean {
+  return /^[A-Za-z0-9+/=\r\n]+$/.test(value);
+}
+
+function decodeDataImageWithLimits(
+  src: string,
+  opts: { maxInlineBytes?: number },
+): { candidate: InlineImageCandidate | null; estimatedBytes: number } {
   const match = /^data:(image\/[a-z0-9.+-]+)?(;base64)?,(.*)$/i.exec(src);
   if (!match) {
-    return null;
+    return { candidate: null, estimatedBytes: 0 };
   }
-  const contentType = match[1]?.toLowerCase();
+  const contentType = normalizeLowercaseStringOrEmpty(match[1] ?? "");
   const isBase64 = Boolean(match[2]);
   if (!isBase64) {
-    return null;
+    return { candidate: null, estimatedBytes: 0 };
   }
   const payload = match[3] ?? "";
-  if (!payload) {
-    return null;
+  if (!payload || !isLikelyBase64Payload(payload)) {
+    return { candidate: null, estimatedBytes: 0 };
   }
+
+  const estimatedBytes = estimateBase64DecodedBytes(payload);
+  if (estimatedBytes <= 0) {
+    return { candidate: null, estimatedBytes: 0 };
+  }
+  if (typeof opts.maxInlineBytes === "number" && estimatedBytes > opts.maxInlineBytes) {
+    return { candidate: null, estimatedBytes };
+  }
+
   try {
     const data = Buffer.from(payload, "base64");
-    return { kind: "data", data, contentType, placeholder: "<media:image>" };
+    return {
+      candidate: { kind: "data", data, contentType, placeholder: "<media:image>" },
+      estimatedBytes,
+    };
   } catch {
-    return null;
+    return { candidate: null, estimatedBytes: 0 };
   }
 }
 
@@ -218,9 +360,11 @@ function fileHintFromUrl(src: string): string | undefined {
 
 export function extractInlineImageCandidates(
   attachments: MSTeamsAttachmentLike[],
+  limits?: InlineImageLimitOptions,
 ): InlineImageCandidate[] {
   const out: InlineImageCandidate[] = [];
-  for (const att of attachments) {
+  let totalEstimatedInlineBytes = 0;
+  outerLoop: for (const att of attachments) {
     const html = extractHtmlFromAttachment(att);
     if (!html) {
       continue;
@@ -231,8 +375,18 @@ export function extractInlineImageCandidates(
       const src = match[1]?.trim();
       if (src && !src.startsWith("cid:")) {
         if (src.startsWith("data:")) {
-          const decoded = decodeDataImage(src);
+          const { candidate: decoded, estimatedBytes } = decodeDataImageWithLimits(src, {
+            maxInlineBytes: limits?.maxInlineBytes,
+          });
           if (decoded) {
+            const nextTotal = totalEstimatedInlineBytes + estimatedBytes;
+            if (
+              typeof limits?.maxInlineTotalBytes === "number" &&
+              nextTotal > limits.maxInlineTotalBytes
+            ) {
+              break outerLoop;
+            }
+            totalEstimatedInlineBytes = nextTotal;
             out.push(decoded);
           }
         } else {
@@ -252,7 +406,7 @@ export function extractInlineImageCandidates(
 
 export function safeHostForUrl(url: string): string {
   try {
-    return new URL(url).hostname.toLowerCase();
+    return normalizeLowercaseStringOrEmpty(new URL(url).hostname);
   } catch {
     return "invalid-url";
   }
@@ -271,6 +425,19 @@ export type MSTeamsAttachmentFetchPolicy = {
   authAllowHosts: string[];
 };
 
+/**
+ * Logger surface for attachment download errors. Structured so callers can
+ * pass `MSTeamsMonitorLogger` directly without adapters. Optional `warn`/
+ * `error` methods prevent silent swallowing of fetch failures — see issue
+ * #63396 where empty `catch {}` blocks hid a Node 24+ undici incompatibility.
+ */
+export type MSTeamsAttachmentDownloadLogger = {
+  warn?: (message: string, meta?: Record<string, unknown>) => void;
+  error?: (message: string, meta?: Record<string, unknown>) => void;
+};
+
+export type MSTeamsAttachmentResolveFn = (hostname: string) => Promise<{ address: string }>;
+
 export function resolveAttachmentFetchPolicy(params?: {
   allowHosts?: string[];
   authAllowHosts?: string[];
@@ -322,7 +489,7 @@ export const isPrivateOrReservedIP: (ip: string) => boolean = isPrivateIpAddress
  */
 export async function resolveAndValidateIP(
   hostname: string,
-  resolveFn?: (hostname: string) => Promise<{ address: string }>,
+  resolveFn?: MSTeamsAttachmentResolveFn,
 ): Promise<string> {
   const resolve = resolveFn ?? lookup;
   let resolved: { address: string };
@@ -359,10 +526,10 @@ export async function safeFetch(params: {
   authorizationAllowHosts?: string[];
   fetchFn?: typeof fetch;
   requestInit?: RequestInit;
-  resolveFn?: (hostname: string) => Promise<{ address: string }>;
+  resolveFn?: MSTeamsAttachmentResolveFn;
 }): Promise<Response> {
   const fetchFn = params.fetchFn ?? fetch;
-  const resolveFn = params.resolveFn;
+  const resolveFn = params.resolveFn ?? lookup;
   const hasDispatcher = Boolean(
     params.requestInit &&
     typeof params.requestInit === "object" &&
@@ -446,7 +613,7 @@ export async function safeFetchWithPolicy(params: {
   policy: MSTeamsAttachmentFetchPolicy;
   fetchFn?: typeof fetch;
   requestInit?: RequestInit;
-  resolveFn?: (hostname: string) => Promise<{ address: string }>;
+  resolveFn?: MSTeamsAttachmentResolveFn;
 }): Promise<Response> {
   return await safeFetch({
     url: params.url,

package/src/attachments/types.ts

@@ -35,3 +35,13 @@ export type MSTeamsGraphMediaResult = {
   messageUrl?: string;
   tokenError?: boolean;
 };
+
+/**
+ * Narrow logger surface used by `downloadMSTeamsGraphMedia` for diagnostic
+ * events. Accepting an optional callback keeps the helper testable without
+ * pulling in the full channel logger type, while still allowing the monitor
+ * handler to forward its plugin logger.
+ */
+export type MSTeamsGraphMediaLogger = {
+  debug?: (message: string, meta?: Record<string, unknown>) => void;
+};