@kodelyth/msteams 2026.5.42 → 2026.6.1

package/src/attachments/bot-framework.ts

@@ -1,348 +0,0 @@
-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 saveBotFrameworkAttachmentView(params: {
-  serviceUrl: string;
-  attachmentId: string;
-  viewId: string;
-  accessToken: string;
-  maxBytes: number;
-  fileNameHint?: string;
-  contentTypeHint?: string;
-  preserveFilenames?: boolean;
-  policy: MSTeamsAttachmentFetchPolicy;
-  fetchFn?: typeof fetch;
-  resolveFn?: MSTeamsAttachmentResolveFn;
-  logger?: MSTeamsAttachmentDownloadLogger;
-}): Promise<{ path: string; contentType?: string } | 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 {
-    return await getMSTeamsRuntime().channel.media.saveResponseMedia(response, {
-      sourceUrl: url,
-      filePathHint: params.fileNameHint,
-      maxBytes: params.maxBytes,
-      fallbackContentType: params.contentTypeHint,
-      subdir: "inbound",
-      originalFilename: params.preserveFilenames ? params.fileNameHint : undefined,
-    });
-  } catch (err) {
-    params.logger?.warn?.("msteams botFramework attachmentView save 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 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 saved = await saveBotFrameworkAttachmentView({
-    serviceUrl: params.serviceUrl,
-    attachmentId: params.attachmentId,
-    viewId,
-    accessToken,
-    maxBytes: params.maxBytes,
-    fileNameHint,
-    contentTypeHint,
-    preserveFilenames: params.preserveFilenames,
-    policy,
-    fetchFn: params.fetchFn,
-    resolveFn: params.resolveFn,
-    logger: params.logger,
-  });
-  if (!saved) {
-    return undefined;
-  }
-
-  return {
-    path: saved.path,
-    contentType: saved.contentType,
-    placeholder: inferPlaceholder({ contentType: saved.contentType, fileName: fileNameHint }),
-  };
-}
-
-/**
- * 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,328 +0,0 @@
-import {
-  normalizeLowercaseStringOrEmpty,
-  normalizeOptionalLowercaseString,
-  normalizeOptionalString,
-} from "klaw/plugin-sdk/string-coerce-runtime";
-import { getMSTeamsRuntime } from "../runtime.js";
-import { downloadAndStoreMSTeamsRemoteMedia } from "./remote-media.js";
-import {
-  extractInlineImageCandidates,
-  inferPlaceholder,
-  isDownloadableAttachment,
-  isRecord,
-  isUrlAllowed,
-  type MSTeamsAttachmentDownloadLogger,
-  type MSTeamsAttachmentFetchPolicy,
-  type MSTeamsAttachmentResolveFn,
-  normalizeContentType,
-  resolveMediaSsrfPolicy,
-  resolveAttachmentFetchPolicy,
-  resolveRequestUrl,
-  safeFetchWithPolicy,
-  tryBuildGraphSharesUrlForSharedLink,
-} from "./shared.js";
-import type {
-  MSTeamsAccessTokenProvider,
-  MSTeamsAttachmentLike,
-  MSTeamsInboundMedia,
-} from "./types.js";
-
-type DownloadCandidate = {
-  url: string;
-  fileHint?: string;
-  contentTypeHint?: string;
-  placeholder: string;
-};
-
-function resolveDownloadCandidate(att: MSTeamsAttachmentLike): DownloadCandidate | null {
-  const contentType = normalizeContentType(att.contentType);
-  const name = normalizeOptionalString(att.name) ?? "";
-
-  if (contentType === "application/vnd.microsoft.teams.file.download.info") {
-    if (!isRecord(att.content)) {
-      return null;
-    }
-    const downloadUrl = normalizeOptionalString(att.content.downloadUrl) ?? "";
-    if (!downloadUrl) {
-      return null;
-    }
-
-    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 {
-      url: downloadUrl,
-      fileHint: fileHint || undefined,
-      contentTypeHint: undefined,
-      placeholder: inferPlaceholder({
-        contentType,
-        fileName: fileHint,
-        fileType,
-      }),
-    };
-  }
-
-  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: resolvedUrl,
-    fileHint: name || undefined,
-    contentTypeHint: resolvedContentTypeHint,
-    placeholder: inferPlaceholder({ contentType, fileName: name }),
-  };
-}
-
-function scopeCandidatesForUrl(url: string): string[] {
-  try {
-    const host = normalizeLowercaseStringOrEmpty(new URL(url).hostname);
-    const looksLikeGraph =
-      host.endsWith("graph.microsoft.com") ||
-      host.endsWith("sharepoint.com") ||
-      host.endsWith("1drv.ms") ||
-      host.includes("sharepoint");
-    return looksLikeGraph
-      ? ["https://graph.microsoft.com", "https://api.botframework.com"]
-      : ["https://api.botframework.com", "https://graph.microsoft.com"];
-  } catch {
-    return ["https://api.botframework.com", "https://graph.microsoft.com"];
-  }
-}
-
-function isRedirectStatus(status: number): boolean {
-  return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
-}
-
-async function resolveInlineDataImageMime(inline: {
-  data: Buffer;
-  contentType?: string;
-}): Promise<string | undefined> {
-  const detectedMime = await getMSTeamsRuntime().media.detectMime({
-    buffer: inline.data,
-    headerMime: inline.contentType,
-  });
-  const mime = normalizeOptionalLowercaseString(detectedMime ?? inline.contentType);
-  return mime?.startsWith("image/") ? mime : undefined;
-}
-
-async function fetchWithAuthFallback(params: {
-  url: string;
-  tokenProvider?: MSTeamsAccessTokenProvider;
-  fetchFn?: typeof fetch;
-  requestInit?: RequestInit;
-  resolveFn?: MSTeamsAttachmentResolveFn;
-  policy: MSTeamsAttachmentFetchPolicy;
-}): Promise<Response> {
-  const firstAttempt = await safeFetchWithPolicy({
-    url: params.url,
-    policy: params.policy,
-    fetchFn: params.fetchFn,
-    requestInit: params.requestInit,
-    resolveFn: params.resolveFn,
-  });
-  if (firstAttempt.ok) {
-    return firstAttempt;
-  }
-  if (!params.tokenProvider) {
-    return firstAttempt;
-  }
-  if (firstAttempt.status !== 401 && firstAttempt.status !== 403) {
-    return firstAttempt;
-  }
-  if (!isUrlAllowed(params.url, params.policy.authAllowHosts)) {
-    return firstAttempt;
-  }
-
-  const scopes = scopeCandidatesForUrl(params.url);
-  const fetchFn = params.fetchFn ?? fetch;
-  for (const scope of scopes) {
-    try {
-      const token = await params.tokenProvider.getAccessToken(scope);
-      const authHeaders = new Headers(params.requestInit?.headers);
-      authHeaders.set("Authorization", `Bearer ${token}`);
-      const authAttempt = await safeFetchWithPolicy({
-        url: params.url,
-        policy: params.policy,
-        fetchFn,
-        requestInit: {
-          ...params.requestInit,
-          headers: authHeaders,
-        },
-        resolveFn: params.resolveFn,
-      });
-      if (authAttempt.ok) {
-        return authAttempt;
-      }
-      if (isRedirectStatus(authAttempt.status)) {
-        // Redirects in guarded fetch mode must propagate to the outer guard.
-        return authAttempt;
-      }
-      if (authAttempt.status !== 401 && authAttempt.status !== 403) {
-        // Preserve scope fallback semantics for non-auth failures.
-        continue;
-      }
-    } catch {
-      // Try the next scope.
-    }
-  }
-
-  return firstAttempt;
-}
-
-/**
- * Download all file attachments from a Teams message (images, documents, etc.).
- * Renamed from downloadMSTeamsImageAttachments to support all file types.
- */
-export async function downloadMSTeamsAttachments(params: {
-  attachments: MSTeamsAttachmentLike[] | undefined;
-  maxBytes: number;
-  tokenProvider?: MSTeamsAccessTokenProvider;
-  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) {
-    return [];
-  }
-  const policy = resolveAttachmentFetchPolicy({
-    allowHosts: params.allowHosts,
-    authAllowHosts: params.authAllowHosts,
-  });
-  const allowHosts = policy.allowHosts;
-  const ssrfPolicy = resolveMediaSsrfPolicy(allowHosts);
-
-  // Download ANY downloadable attachment (not just images)
-  const downloadable = list.filter(isDownloadableAttachment);
-  const candidates: DownloadCandidate[] = downloadable
-    .map(resolveDownloadCandidate)
-    .filter(Boolean) as DownloadCandidate[];
-
-  const inlineCandidates = extractInlineImageCandidates(list, {
-    maxInlineBytes: params.maxBytes,
-    maxInlineTotalBytes: params.maxBytes,
-  });
-
-  const seenUrls = new Set<string>();
-  for (const inline of inlineCandidates) {
-    if (inline.kind === "url") {
-      if (!isUrlAllowed(inline.url, allowHosts)) {
-        continue;
-      }
-      if (seenUrls.has(inline.url)) {
-        continue;
-      }
-      seenUrls.add(inline.url);
-      candidates.push({
-        url: inline.url,
-        fileHint: inline.fileHint,
-        contentTypeHint: inline.contentType,
-        placeholder: inline.placeholder,
-      });
-    }
-  }
-  if (candidates.length === 0 && inlineCandidates.length === 0) {
-    return [];
-  }
-
-  const out: MSTeamsInboundMedia[] = [];
-  for (const inline of inlineCandidates) {
-    if (inline.kind !== "data") {
-      continue;
-    }
-    if (inline.data.byteLength > params.maxBytes) {
-      continue;
-    }
-    try {
-      const contentType = await resolveInlineDataImageMime(inline);
-      if (!contentType) {
-        continue;
-      }
-      // Data inline candidates (base64 data URLs) don't have original filenames
-      const saved = await getMSTeamsRuntime().channel.media.saveMediaBuffer(
-        inline.data,
-        contentType,
-        "inbound",
-        params.maxBytes,
-      );
-      out.push({
-        path: saved.path,
-        contentType: saved.contentType,
-        placeholder: inferPlaceholder({ contentType: saved.contentType ?? contentType }),
-      });
-    } catch (err) {
-      params.logger?.warn?.("msteams inline attachment decode failed", {
-        error: err instanceof Error ? err.message : String(err),
-      });
-    }
-  }
-  for (const candidate of candidates) {
-    if (!isUrlAllowed(candidate.url, allowHosts)) {
-      continue;
-    }
-    try {
-      const media = await downloadAndStoreMSTeamsRemoteMedia({
-        url: candidate.url,
-        filePathHint: candidate.fileHint ?? candidate.url,
-        maxBytes: params.maxBytes,
-        contentTypeHint: candidate.contentTypeHint,
-        placeholder: candidate.placeholder,
-        preserveFilenames: params.preserveFilenames,
-        ssrfPolicy,
-        // `fetchImpl` below already validates each hop against the hostname
-        // allowlist via `safeFetchWithPolicy`, so skip `readRemoteMediaBuffer`'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 (err) {
-      params.logger?.warn?.("msteams attachment download failed", {
-        error: err instanceof Error ? err.message : String(err),
-        host: safeHostForLog(candidate.url),
-      });
-    }
-  }
-  return out;
-}
-
-function safeHostForLog(url: string): string {
-  try {
-    return new URL(url).host;
-  } catch {
-    return "invalid-url";
-  }
-}