@openclaw/msteams 2026.3.13 → 2026.5.2-beta.1

package/src/attachments/bot-framework.ts

@@ -0,0 +1,362 @@
+import { Buffer } from "node:buffer";
+import { getMSTeamsRuntime } from "../runtime.js";
+import { ensureUserAgentHeader } from "../user-agent.js";
+import {
+  inferPlaceholder,
+  isUrlAllowed,
+  type MSTeamsAttachmentDownloadLogger,
+  type MSTeamsAttachmentFetchPolicy,
+  type MSTeamsAttachmentResolveFn,
+  resolveAttachmentFetchPolicy,
+  safeFetchWithPolicy,
+} from "./shared.js";
+import type {
+  MSTeamsAccessTokenProvider,
+  MSTeamsGraphMediaResult,
+  MSTeamsInboundMedia,
+} from "./types.js";
+
+/**
+ * Bot Framework Service token scope for requesting a token used against
+ * the Bot Connector (v3) REST endpoints such as `/v3/attachments/{id}`.
+ */
+const BOT_FRAMEWORK_SCOPE = "https://api.botframework.com";
+
+/**
+ * Detect Bot Framework personal chat ("a:") and MSA orgid ("8:orgid:") conversation
+ * IDs. These identifiers are not recognized by Graph's `/chats/{id}` endpoint, so we
+ * must fetch media via the Bot Framework v3 attachments endpoint instead.
+ *
+ * Graph-compatible IDs start with `19:` and are left untouched by this detector.
+ */
+export function isBotFrameworkPersonalChatId(conversationId: string | null | undefined): boolean {
+  if (typeof conversationId !== "string") {
+    return false;
+  }
+  const trimmed = conversationId.trim();
+  return trimmed.startsWith("a:") || trimmed.startsWith("8:orgid:");
+}
+
+type BotFrameworkView = {
+  viewId?: string | null;
+  size?: number | null;
+};
+
+type BotFrameworkAttachmentInfo = {
+  name?: string | null;
+  type?: string | null;
+  views?: BotFrameworkView[] | null;
+};
+
+function normalizeServiceUrl(serviceUrl: string): string {
+  // Bot Framework service URLs sometimes carry a trailing slash; normalize so
+  // we can safely append `/v3/attachments/...` below.
+  return serviceUrl.replace(/\/+$/, "");
+}
+
+async function fetchBotFrameworkAttachmentInfo(params: {
+  serviceUrl: string;
+  attachmentId: string;
+  accessToken: string;
+  policy: MSTeamsAttachmentFetchPolicy;
+  fetchFn?: typeof fetch;
+  resolveFn?: MSTeamsAttachmentResolveFn;
+  logger?: MSTeamsAttachmentDownloadLogger;
+}): Promise<BotFrameworkAttachmentInfo | undefined> {
+  const url = `${normalizeServiceUrl(params.serviceUrl)}/v3/attachments/${encodeURIComponent(params.attachmentId)}`;
+  // Use `safeFetchWithPolicy` instead of `fetchWithSsrFGuard`. The strict
+  // pinned undici dispatcher used by `fetchWithSsrFGuard` is incompatible
+  // with Node 24+'s built-in undici v7 and silently breaks Bot Framework
+  // attachment downloads (same root cause as the SharePoint fix in #63396).
+  // `safeFetchWithPolicy` already enforces hostname allowlist validation
+  // across every redirect hop, which is sufficient for these attachment
+  // service URLs.
+  let response: Response;
+  try {
+    response = await safeFetchWithPolicy({
+      url,
+      policy: params.policy,
+      fetchFn: params.fetchFn,
+      resolveFn: params.resolveFn,
+      requestInit: {
+        headers: ensureUserAgentHeader({ Authorization: `Bearer ${params.accessToken}` }),
+      },
+    });
+  } catch (err) {
+    params.logger?.warn?.("msteams botFramework attachmentInfo fetch failed", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return undefined;
+  }
+  if (!response.ok) {
+    params.logger?.warn?.("msteams botFramework attachmentInfo non-ok", {
+      status: response.status,
+    });
+    return undefined;
+  }
+  try {
+    return (await response.json()) as BotFrameworkAttachmentInfo;
+  } catch (err) {
+    params.logger?.warn?.("msteams botFramework attachmentInfo parse failed", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return undefined;
+  }
+}
+
+async function fetchBotFrameworkAttachmentView(params: {
+  serviceUrl: string;
+  attachmentId: string;
+  viewId: string;
+  accessToken: string;
+  maxBytes: number;
+  policy: MSTeamsAttachmentFetchPolicy;
+  fetchFn?: typeof fetch;
+  resolveFn?: MSTeamsAttachmentResolveFn;
+  logger?: MSTeamsAttachmentDownloadLogger;
+}): Promise<Buffer | undefined> {
+  const url = `${normalizeServiceUrl(params.serviceUrl)}/v3/attachments/${encodeURIComponent(params.attachmentId)}/views/${encodeURIComponent(params.viewId)}`;
+  // See `fetchBotFrameworkAttachmentInfo` for why this uses
+  // `safeFetchWithPolicy` instead of `fetchWithSsrFGuard` on Node 24+ (#63396).
+  let response: Response;
+  try {
+    response = await safeFetchWithPolicy({
+      url,
+      policy: params.policy,
+      fetchFn: params.fetchFn,
+      resolveFn: params.resolveFn,
+      requestInit: {
+        headers: ensureUserAgentHeader({ Authorization: `Bearer ${params.accessToken}` }),
+      },
+    });
+  } catch (err) {
+    params.logger?.warn?.("msteams botFramework attachmentView fetch failed", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return undefined;
+  }
+  if (!response.ok) {
+    params.logger?.warn?.("msteams botFramework attachmentView non-ok", {
+      status: response.status,
+    });
+    return undefined;
+  }
+  const contentLength = response.headers.get("content-length");
+  if (contentLength && Number(contentLength) > params.maxBytes) {
+    return undefined;
+  }
+  try {
+    const arrayBuffer = await response.arrayBuffer();
+    const buffer = Buffer.from(arrayBuffer);
+    if (buffer.byteLength > params.maxBytes) {
+      return undefined;
+    }
+    return buffer;
+  } catch (err) {
+    params.logger?.warn?.("msteams botFramework attachmentView body read failed", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return undefined;
+  }
+}
+
+/**
+ * Download media for a single attachment via the Bot Framework v3 attachments
+ * endpoint. Used for personal DM conversations where the Graph `/chats/{id}`
+ * path is not usable because the Bot Framework conversation ID (`a:...`) is
+ * not a valid Graph chat identifier.
+ */
+export async function downloadMSTeamsBotFrameworkAttachment(params: {
+  serviceUrl: string;
+  attachmentId: string;
+  tokenProvider?: MSTeamsAccessTokenProvider;
+  maxBytes: number;
+  allowHosts?: string[];
+  authAllowHosts?: string[];
+  fetchFn?: typeof fetch;
+  resolveFn?: MSTeamsAttachmentResolveFn;
+  fileNameHint?: string | null;
+  contentTypeHint?: string | null;
+  preserveFilenames?: boolean;
+  logger?: MSTeamsAttachmentDownloadLogger;
+}): Promise<MSTeamsInboundMedia | undefined> {
+  if (!params.serviceUrl || !params.attachmentId || !params.tokenProvider) {
+    return undefined;
+  }
+  const policy: MSTeamsAttachmentFetchPolicy = resolveAttachmentFetchPolicy({
+    allowHosts: params.allowHosts,
+    authAllowHosts: params.authAllowHosts,
+  });
+  const baseUrl = `${normalizeServiceUrl(params.serviceUrl)}/v3/attachments/${encodeURIComponent(params.attachmentId)}`;
+  if (!isUrlAllowed(baseUrl, policy.allowHosts)) {
+    return undefined;
+  }
+
+  let accessToken: string;
+  try {
+    accessToken = await params.tokenProvider.getAccessToken(BOT_FRAMEWORK_SCOPE);
+  } catch (err) {
+    params.logger?.warn?.("msteams botFramework token acquisition failed", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return undefined;
+  }
+  if (!accessToken) {
+    return undefined;
+  }
+
+  const info = await fetchBotFrameworkAttachmentInfo({
+    serviceUrl: params.serviceUrl,
+    attachmentId: params.attachmentId,
+    accessToken,
+    policy,
+    fetchFn: params.fetchFn,
+    resolveFn: params.resolveFn,
+    logger: params.logger,
+  });
+  if (!info) {
+    return undefined;
+  }
+
+  const views = Array.isArray(info.views) ? info.views : [];
+  // Prefer the "original" view when present, otherwise fall back to the first
+  // view the Bot Framework service returned.
+  const original = views.find((view) => view?.viewId === "original");
+  const candidateView = original ?? views.find((view) => typeof view?.viewId === "string");
+  const viewId =
+    typeof candidateView?.viewId === "string" && candidateView.viewId
+      ? candidateView.viewId
+      : undefined;
+  if (!viewId) {
+    return undefined;
+  }
+  if (
+    typeof candidateView?.size === "number" &&
+    candidateView.size > 0 &&
+    candidateView.size > params.maxBytes
+  ) {
+    return undefined;
+  }
+
+  const buffer = await fetchBotFrameworkAttachmentView({
+    serviceUrl: params.serviceUrl,
+    attachmentId: params.attachmentId,
+    viewId,
+    accessToken,
+    maxBytes: params.maxBytes,
+    policy,
+    fetchFn: params.fetchFn,
+    resolveFn: params.resolveFn,
+    logger: params.logger,
+  });
+  if (!buffer) {
+    return undefined;
+  }
+
+  const fileNameHint =
+    (typeof params.fileNameHint === "string" && params.fileNameHint) ||
+    (typeof info.name === "string" && info.name) ||
+    undefined;
+  const contentTypeHint =
+    (typeof params.contentTypeHint === "string" && params.contentTypeHint) ||
+    (typeof info.type === "string" && info.type) ||
+    undefined;
+
+  const mime = await getMSTeamsRuntime().media.detectMime({
+    buffer,
+    headerMime: contentTypeHint,
+    filePath: fileNameHint,
+  });
+
+  try {
+    const originalFilename = params.preserveFilenames ? fileNameHint : undefined;
+    const saved = await getMSTeamsRuntime().channel.media.saveMediaBuffer(
+      buffer,
+      mime ?? contentTypeHint,
+      "inbound",
+      params.maxBytes,
+      originalFilename,
+    );
+    return {
+      path: saved.path,
+      contentType: saved.contentType,
+      placeholder: inferPlaceholder({ contentType: saved.contentType, fileName: fileNameHint }),
+    };
+  } catch (err) {
+    params.logger?.warn?.("msteams botFramework save failed", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return undefined;
+  }
+}
+
+/**
+ * Download media for every attachment referenced by a Bot Framework personal
+ * chat activity. Returns all successfully fetched media along with diagnostics
+ * compatible with `downloadMSTeamsGraphMedia`'s result shape so callers can
+ * reuse the existing logging path.
+ */
+export async function downloadMSTeamsBotFrameworkAttachments(params: {
+  serviceUrl: string;
+  attachmentIds: string[];
+  tokenProvider?: MSTeamsAccessTokenProvider;
+  maxBytes: number;
+  allowHosts?: string[];
+  authAllowHosts?: string[];
+  fetchFn?: typeof fetch;
+  resolveFn?: MSTeamsAttachmentResolveFn;
+  fileNameHint?: string | null;
+  contentTypeHint?: string | null;
+  preserveFilenames?: boolean;
+  logger?: MSTeamsAttachmentDownloadLogger;
+}): Promise<MSTeamsGraphMediaResult> {
+  const seen = new Set<string>();
+  const unique: string[] = [];
+  for (const id of params.attachmentIds ?? []) {
+    if (typeof id !== "string") {
+      continue;
+    }
+    const trimmed = id.trim();
+    if (!trimmed || seen.has(trimmed)) {
+      continue;
+    }
+    seen.add(trimmed);
+    unique.push(trimmed);
+  }
+  if (unique.length === 0 || !params.serviceUrl || !params.tokenProvider) {
+    return { media: [], attachmentCount: unique.length };
+  }
+
+  const media: MSTeamsInboundMedia[] = [];
+  for (const attachmentId of unique) {
+    try {
+      const item = await downloadMSTeamsBotFrameworkAttachment({
+        serviceUrl: params.serviceUrl,
+        attachmentId,
+        tokenProvider: params.tokenProvider,
+        maxBytes: params.maxBytes,
+        allowHosts: params.allowHosts,
+        authAllowHosts: params.authAllowHosts,
+        fetchFn: params.fetchFn,
+        resolveFn: params.resolveFn,
+        fileNameHint: params.fileNameHint,
+        contentTypeHint: params.contentTypeHint,
+        preserveFilenames: params.preserveFilenames,
+        logger: params.logger,
+      });
+      if (item) {
+        media.push(item);
+      }
+    } catch (err) {
+      params.logger?.warn?.("msteams botFramework attachment download failed", {
+        error: err instanceof Error ? err.message : String(err),
+        attachmentId,
+      });
+    }
+  }
+
+  return {
+    media,
+    attachmentCount: unique.length,
+  };
+}

package/src/attachments/download.ts

@@ -1,3 +1,7 @@
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalString,
+} from "openclaw/plugin-sdk/text-runtime";
 import { getMSTeamsRuntime } from "../runtime.js";
 import { downloadAndStoreMSTeamsRemoteMedia } from "./remote-media.js";
 import {
@@ -6,12 +10,15 @@ import {
   isDownloadableAttachment,
   isRecord,
   isUrlAllowed,
+  type MSTeamsAttachmentDownloadLogger,
   type MSTeamsAttachmentFetchPolicy,
+  type MSTeamsAttachmentResolveFn,
   normalizeContentType,
   resolveMediaSsrfPolicy,
   resolveAttachmentFetchPolicy,
   resolveRequestUrl,
   safeFetchWithPolicy,
+  tryBuildGraphSharesUrlForSharedLink,
 } from "./shared.js";
 import type {
   MSTeamsAccessTokenProvider,
@@ -28,21 +35,20 @@ type DownloadCandidate = {
 
 function resolveDownloadCandidate(att: MSTeamsAttachmentLike): DownloadCandidate | null {
   const contentType = normalizeContentType(att.contentType);
-  const name = typeof att.name === "string" ? att.name.trim() : "";
+  const name = normalizeOptionalString(att.name) ?? "";
 
   if (contentType === "application/vnd.microsoft.teams.file.download.info") {
     if (!isRecord(att.content)) {
       return null;
     }
-    const downloadUrl =
-      typeof att.content.downloadUrl === "string" ? att.content.downloadUrl.trim() : "";
+    const downloadUrl = normalizeOptionalString(att.content.downloadUrl) ?? "";
     if (!downloadUrl) {
       return null;
     }
 
-    const fileType = typeof att.content.fileType === "string" ? att.content.fileType.trim() : "";
-    const uniqueId = typeof att.content.uniqueId === "string" ? att.content.uniqueId.trim() : "";
-    const fileName = typeof att.content.fileName === "string" ? att.content.fileName.trim() : "";
+    const fileType = normalizeOptionalString(att.content.fileType) ?? "";
+    const uniqueId = normalizeOptionalString(att.content.uniqueId) ?? "";
+    const fileName = normalizeOptionalString(att.content.fileName) ?? "";
 
     const fileHint = name || fileName || (uniqueId && fileType ? `${uniqueId}.${fileType}` : "");
     return {
@@ -57,22 +63,33 @@ function resolveDownloadCandidate(att: MSTeamsAttachmentLike): DownloadCandidate
     };
   }
 
-  const contentUrl = typeof att.contentUrl === "string" ? att.contentUrl.trim() : "";
+  const contentUrl = normalizeOptionalString(att.contentUrl) ?? "";
   if (!contentUrl) {
     return null;
   }
 
+  // OneDrive/SharePoint shared links (delivered in 1:1 DMs when the user
+  // picks "Attach > OneDrive") cannot be fetched directly — the URL returns
+  // an HTML landing page rather than the file bytes. Rewrite them to the
+  // Graph shares endpoint so the auth fallback attaches a Graph-scoped token
+  // and the response is the real file content.
+  const sharesUrl = tryBuildGraphSharesUrlForSharedLink(contentUrl);
+  const resolvedUrl = sharesUrl ?? contentUrl;
+  // Graph shares returns raw bytes without a declared content type we can
+  // trust for routing — let the downloader infer MIME from the buffer.
+  const resolvedContentTypeHint = sharesUrl ? undefined : contentType;
+
   return {
-    url: contentUrl,
+    url: resolvedUrl,
     fileHint: name || undefined,
-    contentTypeHint: contentType,
+    contentTypeHint: resolvedContentTypeHint,
     placeholder: inferPlaceholder({ contentType, fileName: name }),
   };
 }
 
 function scopeCandidatesForUrl(url: string): string[] {
   try {
-    const host = new URL(url).hostname.toLowerCase();
+    const host = normalizeLowercaseStringOrEmpty(new URL(url).hostname);
     const looksLikeGraph =
       host.endsWith("graph.microsoft.com") ||
       host.endsWith("sharepoint.com") ||
@@ -95,6 +112,7 @@ async function fetchWithAuthFallback(params: {
   tokenProvider?: MSTeamsAccessTokenProvider;
   fetchFn?: typeof fetch;
   requestInit?: RequestInit;
+  resolveFn?: MSTeamsAttachmentResolveFn;
   policy: MSTeamsAttachmentFetchPolicy;
 }): Promise<Response> {
   const firstAttempt = await safeFetchWithPolicy({
@@ -102,6 +120,7 @@ async function fetchWithAuthFallback(params: {
     policy: params.policy,
     fetchFn: params.fetchFn,
     requestInit: params.requestInit,
+    resolveFn: params.resolveFn,
   });
   if (firstAttempt.ok) {
     return firstAttempt;
@@ -131,6 +150,7 @@ async function fetchWithAuthFallback(params: {
           ...params.requestInit,
           headers: authHeaders,
         },
+        resolveFn: params.resolveFn,
       });
       if (authAttempt.ok) {
         return authAttempt;
@@ -162,8 +182,15 @@ export async function downloadMSTeamsAttachments(params: {
   allowHosts?: string[];
   authAllowHosts?: string[];
   fetchFn?: typeof fetch;
+  resolveFn?: MSTeamsAttachmentResolveFn;
   /** When true, embeds original filename in stored path for later extraction. */
   preserveFilenames?: boolean;
+  /**
+   * Optional logger used to surface inline data decode failures and remote
+   * media download errors. Errors that are not logged here are invisible at
+   * INFO level and block diagnosis of issues like #63396.
+   */
+  logger?: MSTeamsAttachmentDownloadLogger;
 }): Promise<MSTeamsInboundMedia[]> {
   const list = Array.isArray(params.attachments) ? params.attachments : [];
   if (list.length === 0) {
@@ -182,7 +209,10 @@ export async function downloadMSTeamsAttachments(params: {
     .map(resolveDownloadCandidate)
     .filter(Boolean) as DownloadCandidate[];
 
-  const inlineCandidates = extractInlineImageCandidates(list);
+  const inlineCandidates = extractInlineImageCandidates(list, {
+    maxInlineBytes: params.maxBytes,
+    maxInlineTotalBytes: params.maxBytes,
+  });
 
   const seenUrls = new Set<string>();
   for (const inline of inlineCandidates) {
@@ -227,8 +257,10 @@ export async function downloadMSTeamsAttachments(params: {
         contentType: saved.contentType,
         placeholder: inline.placeholder,
       });
-    } catch {
-      // Ignore decode failures and continue.
+    } catch (err) {
+      params.logger?.warn?.("msteams inline attachment decode failed", {
+        error: err instanceof Error ? err.message : String(err),
+      });
     }
   }
   for (const candidate of candidates) {
@@ -244,24 +276,36 @@ export async function downloadMSTeamsAttachments(params: {
         placeholder: candidate.placeholder,
         preserveFilenames: params.preserveFilenames,
         ssrfPolicy,
+        // `fetchImpl` below already validates each hop against the hostname
+        // allowlist via `safeFetchWithPolicy`, so skip `fetchRemoteMedia`'s
+        // strict SSRF dispatcher (incompatible with Node 24+ / undici v7;
+        // see issue #63396).
+        useDirectFetch: true,
         fetchImpl: (input, init) =>
           fetchWithAuthFallback({
             url: resolveRequestUrl(input),
             tokenProvider: params.tokenProvider,
             fetchFn: params.fetchFn,
             requestInit: init,
+            resolveFn: params.resolveFn,
             policy,
           }),
       });
       out.push(media);
-    } catch {
-      // Ignore download failures and continue with next candidate.
+    } catch (err) {
+      params.logger?.warn?.("msteams attachment download failed", {
+        error: err instanceof Error ? err.message : String(err),
+        host: safeHostForLog(candidate.url),
+      });
     }
   }
   return out;
 }
 
-/**
- * @deprecated Use `downloadMSTeamsAttachments` instead (supports all file types).
- */
-export const downloadMSTeamsImageAttachments = downloadMSTeamsAttachments;
+function safeHostForLog(url: string): string {
+  try {
+    return new URL(url).host;
+  } catch {
+    return "invalid-url";
+  }
+}