@openclaw/msteams 2026.3.1 → 2026.3.2

package/src/attachments/shared.ts

@@ -1,6 +1,8 @@
+import { lookup } from "node:dns/promises";
 import {
   buildHostnameAllowlistPolicyFromSuffixAllowlist,
   isHttpsUrlAllowedByHostnameSuffixAllowlist,
+  isPrivateIpAddress,
   normalizeHostnameSuffixAllowlist,
 } from "openclaw/plugin-sdk";
 import type { SsrFPolicy } from "openclaw/plugin-sdk";
@@ -264,10 +266,194 @@ export function resolveAuthAllowedHosts(input?: string[]): string[] {
   return normalizeHostnameSuffixAllowlist(input, DEFAULT_MEDIA_AUTH_HOST_ALLOWLIST);
 }
 
+export type MSTeamsAttachmentFetchPolicy = {
+  allowHosts: string[];
+  authAllowHosts: string[];
+};
+
+export function resolveAttachmentFetchPolicy(params?: {
+  allowHosts?: string[];
+  authAllowHosts?: string[];
+}): MSTeamsAttachmentFetchPolicy {
+  return {
+    allowHosts: resolveAllowedHosts(params?.allowHosts),
+    authAllowHosts: resolveAuthAllowedHosts(params?.authAllowHosts),
+  };
+}
+
 export function isUrlAllowed(url: string, allowlist: string[]): boolean {
   return isHttpsUrlAllowedByHostnameSuffixAllowlist(url, allowlist);
 }
 
+export function applyAuthorizationHeaderForUrl(params: {
+  headers: Headers;
+  url: string;
+  authAllowHosts: string[];
+  bearerToken?: string;
+}): void {
+  if (!params.bearerToken) {
+    params.headers.delete("Authorization");
+    return;
+  }
+  if (isUrlAllowed(params.url, params.authAllowHosts)) {
+    params.headers.set("Authorization", `Bearer ${params.bearerToken}`);
+    return;
+  }
+  params.headers.delete("Authorization");
+}
+
 export function resolveMediaSsrfPolicy(allowHosts: string[]): SsrFPolicy | undefined {
   return buildHostnameAllowlistPolicyFromSuffixAllowlist(allowHosts);
 }
+
+/**
+ * Returns true if the given IPv4 or IPv6 address is in a private, loopback,
+ * or link-local range that must never be reached from media downloads.
+ *
+ * Delegates to the SDK's `isPrivateIpAddress` which handles IPv4-mapped IPv6,
+ * expanded notation, NAT64, 6to4, Teredo, octal IPv4, and fails closed on
+ * parse errors.
+ */
+export const isPrivateOrReservedIP: (ip: string) => boolean = isPrivateIpAddress;
+
+/**
+ * Resolve a hostname via DNS and reject private/reserved IPs.
+ * Throws if the resolved IP is private or resolution fails.
+ */
+export async function resolveAndValidateIP(
+  hostname: string,
+  resolveFn?: (hostname: string) => Promise<{ address: string }>,
+): Promise<string> {
+  const resolve = resolveFn ?? lookup;
+  let resolved: { address: string };
+  try {
+    resolved = await resolve(hostname);
+  } catch {
+    throw new Error(`DNS resolution failed for "${hostname}"`);
+  }
+  if (isPrivateOrReservedIP(resolved.address)) {
+    throw new Error(`Hostname "${hostname}" resolves to private/reserved IP (${resolved.address})`);
+  }
+  return resolved.address;
+}
+
+/** Maximum number of redirects to follow in safeFetch. */
+const MAX_SAFE_REDIRECTS = 5;
+
+/**
+ * Fetch a URL with redirect: "manual", validating each redirect target
+ * against the hostname allowlist and optional DNS-resolved IP (anti-SSRF).
+ *
+ * This prevents:
+ * - Auto-following redirects to non-allowlisted hosts
+ * - DNS rebinding attacks when a lookup function is provided
+ */
+export async function safeFetch(params: {
+  url: string;
+  allowHosts: string[];
+  /**
+   * Optional allowlist for forwarding Authorization across redirects.
+   * When set, Authorization is stripped before following redirects to hosts
+   * outside this list.
+   */
+  authorizationAllowHosts?: string[];
+  fetchFn?: typeof fetch;
+  requestInit?: RequestInit;
+  resolveFn?: (hostname: string) => Promise<{ address: string }>;
+}): Promise<Response> {
+  const fetchFn = params.fetchFn ?? fetch;
+  const resolveFn = params.resolveFn;
+  const hasDispatcher = Boolean(
+    params.requestInit &&
+    typeof params.requestInit === "object" &&
+    "dispatcher" in (params.requestInit as Record<string, unknown>),
+  );
+  const currentHeaders = new Headers(params.requestInit?.headers);
+  let currentUrl = params.url;
+
+  if (!isUrlAllowed(currentUrl, params.allowHosts)) {
+    throw new Error(`Initial download URL blocked: ${currentUrl}`);
+  }
+
+  if (resolveFn) {
+    try {
+      const initialHost = new URL(currentUrl).hostname;
+      await resolveAndValidateIP(initialHost, resolveFn);
+    } catch {
+      throw new Error(`Initial download URL blocked: ${currentUrl}`);
+    }
+  }
+
+  for (let i = 0; i <= MAX_SAFE_REDIRECTS; i++) {
+    const res = await fetchFn(currentUrl, {
+      ...params.requestInit,
+      headers: currentHeaders,
+      redirect: "manual",
+    });
+
+    if (![301, 302, 303, 307, 308].includes(res.status)) {
+      return res;
+    }
+
+    const location = res.headers.get("location");
+    if (!location) {
+      return res;
+    }
+
+    let redirectUrl: string;
+    try {
+      redirectUrl = new URL(location, currentUrl).toString();
+    } catch {
+      throw new Error(`Invalid redirect URL: ${location}`);
+    }
+
+    // Validate redirect target against hostname allowlist
+    if (!isUrlAllowed(redirectUrl, params.allowHosts)) {
+      throw new Error(`Media redirect target blocked by allowlist: ${redirectUrl}`);
+    }
+
+    // Prevent credential bleed: only keep Authorization on redirect hops that
+    // are explicitly auth-allowlisted.
+    if (
+      currentHeaders.has("authorization") &&
+      params.authorizationAllowHosts &&
+      !isUrlAllowed(redirectUrl, params.authorizationAllowHosts)
+    ) {
+      currentHeaders.delete("authorization");
+    }
+
+    // When a pinned dispatcher is already injected by an upstream guard
+    // (for example fetchWithSsrFGuard), let that guard own redirect handling
+    // after this allowlist validation step.
+    if (hasDispatcher) {
+      return res;
+    }
+
+    // Validate redirect target's resolved IP
+    if (resolveFn) {
+      const redirectHost = new URL(redirectUrl).hostname;
+      await resolveAndValidateIP(redirectHost, resolveFn);
+    }
+
+    currentUrl = redirectUrl;
+  }
+
+  throw new Error(`Too many redirects (>${MAX_SAFE_REDIRECTS})`);
+}
+
+export async function safeFetchWithPolicy(params: {
+  url: string;
+  policy: MSTeamsAttachmentFetchPolicy;
+  fetchFn?: typeof fetch;
+  requestInit?: RequestInit;
+  resolveFn?: (hostname: string) => Promise<{ address: string }>;
+}): Promise<Response> {
+  return await safeFetch({
+    url: params.url,
+    allowHosts: params.policy.allowHosts,
+    authorizationAllowHosts: params.policy.authAllowHosts,
+    fetchFn: params.fetchFn,
+    requestInit: params.requestInit,
+    resolveFn: params.resolveFn,
+  });
+}

package/src/attachments.test.ts

@@ -1,5 +1,6 @@
 import type { PluginRuntime, SsrFPolicy } from "openclaw/plugin-sdk";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createPluginRuntimeMock } from "../../test-utils/plugin-runtime-mock.js";
 import {
   buildMSTeamsAttachmentPlaceholder,
   buildMSTeamsGraphMessageUrls,
@@ -46,7 +47,9 @@ type RemoteMediaFetchParams = {
 
 const detectMimeMock = vi.fn(async () => CONTENT_TYPE_IMAGE_PNG);
 const saveMediaBufferMock = vi.fn(async () => ({
+  id: "saved.png",
   path: SAVED_PNG_PATH,
+  size: Buffer.byteLength(PNG_BUFFER),
   contentType: CONTENT_TYPE_IMAGE_PNG,
 }));
 const readRemoteMediaResponse = async (
@@ -106,19 +109,17 @@ const fetchRemoteMediaMock = vi.fn(async (params: RemoteMediaFetchParams) => {
   throw new Error("too many redirects");
 });
 
-const runtimeStub = {
+const runtimeStub: PluginRuntime = createPluginRuntimeMock({
   media: {
-    detectMime: detectMimeMock as unknown as PluginRuntime["media"]["detectMime"],
+    detectMime: detectMimeMock,
   },
   channel: {
     media: {
-      fetchRemoteMedia:
-        fetchRemoteMediaMock as unknown as PluginRuntime["channel"]["media"]["fetchRemoteMedia"],
-      saveMediaBuffer:
-        saveMediaBufferMock as unknown as PluginRuntime["channel"]["media"]["saveMediaBuffer"],
+      fetchRemoteMedia: fetchRemoteMediaMock,
+      saveMediaBuffer: saveMediaBufferMock,
     },
   },
-} as unknown as PluginRuntime;
+});
 
 type DownloadAttachmentsParams = Parameters<typeof downloadMSTeamsAttachments>[0];
 type DownloadGraphMediaParams = Parameters<typeof downloadMSTeamsGraphMedia>[0];
@@ -164,7 +165,13 @@ const IMAGE_ATTACHMENT = { contentType: CONTENT_TYPE_IMAGE_PNG, contentUrl: TEST
 const PNG_BUFFER = Buffer.from("png");
 const PNG_BASE64 = PNG_BUFFER.toString("base64");
 const PDF_BUFFER = Buffer.from("pdf");
-const createTokenProvider = () => ({ getAccessToken: vi.fn(async () => "token") });
+const createTokenProvider = (
+  tokenOrResolver: string | ((scope: string) => string | Promise<string>) = "token",
+) => ({
+  getAccessToken: vi.fn(async (scope: string) =>
+    typeof tokenOrResolver === "function" ? await tokenOrResolver(scope) : tokenOrResolver,
+  ),
+});
 const asSingleItemArray = <T>(value: T) => [value];
 const withLabel = <T extends object>(label: string, fields: T): T & LabeledCase => ({
   label,
@@ -434,7 +441,9 @@ const ATTACHMENT_DOWNLOAD_SUCCESS_CASES: AttachmentDownloadSuccessCase[] = [
     beforeDownload: () => {
       detectMimeMock.mockResolvedValueOnce(CONTENT_TYPE_APPLICATION_PDF);
       saveMediaBufferMock.mockResolvedValueOnce({
+        id: "saved.pdf",
         path: SAVED_PDF_PATH,
+        size: Buffer.byteLength(PDF_BUFFER),
         contentType: CONTENT_TYPE_APPLICATION_PDF,
       });
     },
@@ -694,6 +703,121 @@ describe("msteams attachments", () => {
       runAttachmentAuthRetryCase,
     );
 
+    it("preserves auth fallback when dispatcher-mode fetch returns a redirect", async () => {
+      const redirectedUrl = createTestUrl("redirected.png");
+      const tokenProvider = createTokenProvider();
+      const fetchMock = vi.fn(async (url: string, opts?: RequestInit) => {
+        const hasAuth = Boolean(new Headers(opts?.headers).get("Authorization"));
+        if (url === TEST_URL_IMAGE) {
+          return hasAuth
+            ? createRedirectResponse(redirectedUrl)
+            : createTextResponse("unauthorized", 401);
+        }
+        if (url === redirectedUrl) {
+          return createBufferResponse(PNG_BUFFER, CONTENT_TYPE_IMAGE_PNG);
+        }
+        return createNotFoundResponse();
+      });
+
+      fetchRemoteMediaMock.mockImplementationOnce(async (params) => {
+        const fetchFn = params.fetchImpl ?? fetch;
+        let currentUrl = params.url;
+        for (let i = 0; i < MAX_REDIRECT_HOPS; i += 1) {
+          const res = await fetchFn(currentUrl, {
+            redirect: "manual",
+            dispatcher: {},
+          } as RequestInit);
+          if (REDIRECT_STATUS_CODES.includes(res.status)) {
+            const location = res.headers.get("location");
+            if (!location) {
+              throw new Error("redirect missing location");
+            }
+            currentUrl = new URL(location, currentUrl).toString();
+            continue;
+          }
+          return readRemoteMediaResponse(res, params);
+        }
+        throw new Error("too many redirects");
+      });
+
+      const media = await downloadAttachmentsWithFetch(
+        createImageAttachments(TEST_URL_IMAGE),
+        fetchMock,
+        { tokenProvider, authAllowHosts: [TEST_HOST] },
+      );
+
+      expectAttachmentMediaLength(media, 1);
+      expect(tokenProvider.getAccessToken).toHaveBeenCalledOnce();
+      expect(fetchMock.mock.calls.map(([calledUrl]) => String(calledUrl))).toContain(redirectedUrl);
+    });
+
+    it("continues scope fallback after non-auth failure and succeeds on later scope", async () => {
+      let authAttempt = 0;
+      const tokenProvider = createTokenProvider((scope) => `token:${scope}`);
+      const fetchMock = vi.fn(async (_url: string, opts?: RequestInit) => {
+        const auth = new Headers(opts?.headers).get("Authorization");
+        if (!auth) {
+          return createTextResponse("unauthorized", 401);
+        }
+        authAttempt += 1;
+        if (authAttempt === 1) {
+          return createTextResponse("upstream transient", 500);
+        }
+        return createBufferResponse(PNG_BUFFER, CONTENT_TYPE_IMAGE_PNG);
+      });
+
+      const media = await downloadAttachmentsWithFetch(
+        createImageAttachments(TEST_URL_IMAGE),
+        fetchMock,
+        { tokenProvider, authAllowHosts: [TEST_HOST] },
+      );
+
+      expectAttachmentMediaLength(media, 1);
+      expect(tokenProvider.getAccessToken).toHaveBeenCalledTimes(2);
+    });
+
+    it("does not forward Authorization to redirects outside auth allowlist", async () => {
+      const tokenProvider = createTokenProvider("top-secret-token");
+      const graphFileUrl = createUrlForHost(GRAPH_HOST, "file");
+      const seen: Array<{ url: string; auth: string }> = [];
+      const fetchMock = vi.fn(async (url: string, opts?: RequestInit) => {
+        const auth = new Headers(opts?.headers).get("Authorization") ?? "";
+        seen.push({ url, auth });
+        if (url === graphFileUrl && !auth) {
+          return new Response("unauthorized", { status: 401 });
+        }
+        if (url === graphFileUrl && auth) {
+          return new Response("", {
+            status: 302,
+            headers: { location: "https://attacker.azureedge.net/collect" },
+          });
+        }
+        if (url === "https://attacker.azureedge.net/collect") {
+          return new Response(Buffer.from("png"), {
+            status: 200,
+            headers: { "content-type": CONTENT_TYPE_IMAGE_PNG },
+          });
+        }
+        return createNotFoundResponse();
+      });
+
+      const media = await downloadMSTeamsAttachments(
+        buildDownloadParams([{ contentType: CONTENT_TYPE_IMAGE_PNG, contentUrl: graphFileUrl }], {
+          tokenProvider,
+          allowHosts: [GRAPH_HOST, AZUREEDGE_HOST],
+          authAllowHosts: [GRAPH_HOST],
+          fetchFn: asFetchFn(fetchMock),
+        }),
+      );
+
+      expectSingleMedia(media);
+      const redirected = seen.find(
+        (entry) => entry.url === "https://attacker.azureedge.net/collect",
+      );
+      expect(redirected).toBeDefined();
+      expect(redirected?.auth).toBe("");
+    });
+
     it("skips urls outside the allowlist", async () => {
       const fetchMock = vi.fn();
       const media = await downloadAttachmentsWithFetch(
@@ -744,6 +868,49 @@ describe("msteams attachments", () => {
   describe("downloadMSTeamsGraphMedia", () => {
     it.each<GraphMediaSuccessCase>(GRAPH_MEDIA_SUCCESS_CASES)("$label", runGraphMediaSuccessCase);
 
+    it("does not forward Authorization for SharePoint redirects outside auth allowlist", async () => {
+      const tokenProvider = createTokenProvider("top-secret-token");
+      const escapedUrl = "https://example.com/collect";
+      const seen: Array<{ url: string; auth: string }> = [];
+      const referenceAttachment = createReferenceAttachment();
+      const fetchMock = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+        const url = String(input);
+        const auth = new Headers(init?.headers).get("Authorization") ?? "";
+        seen.push({ url, auth });
+
+        if (url === DEFAULT_MESSAGE_URL) {
+          return createJsonResponse({ attachments: [referenceAttachment] });
+        }
+        if (url === `${DEFAULT_MESSAGE_URL}/hostedContents`) {
+          return createGraphCollectionResponse([]);
+        }
+        if (url === `${DEFAULT_MESSAGE_URL}/attachments`) {
+          return createGraphCollectionResponse([referenceAttachment]);
+        }
+        if (url.startsWith(GRAPH_SHARES_URL_PREFIX)) {
+          return createRedirectResponse(escapedUrl);
+        }
+        if (url === escapedUrl) {
+          return createPdfResponse();
+        }
+        return createNotFoundResponse();
+      });
+
+      const media = await downloadMSTeamsGraphMedia({
+        messageUrl: DEFAULT_MESSAGE_URL,
+        tokenProvider,
+        maxBytes: DEFAULT_MAX_BYTES,
+        allowHosts: [...DEFAULT_SHAREPOINT_ALLOW_HOSTS, "example.com"],
+        authAllowHosts: DEFAULT_SHAREPOINT_ALLOW_HOSTS,
+        fetchFn: asFetchFn(fetchMock),
+      });
+
+      expectAttachmentMediaLength(media.media, 1);
+      const redirected = seen.find((entry) => entry.url === escapedUrl);
+      expect(redirected).toBeDefined();
+      expect(redirected?.auth).toBe("");
+    });
+
     it("blocks SharePoint redirects to hosts outside allowHosts", async () => {
       const escapedUrl = "https://evil.example/internal.pdf";
       const { fetchMock, media } = await downloadGraphMediaWithMockOptions(

package/src/errors.test.ts

@@ -3,6 +3,7 @@ import {
   classifyMSTeamsSendError,
   formatMSTeamsSendErrorHint,
   formatUnknownError,
+  isRevokedProxyError,
 } from "./errors.js";
 
 describe("msteams errors", () => {
@@ -42,4 +43,28 @@ describe("msteams errors", () => {
     expect(formatMSTeamsSendErrorHint({ kind: "auth" })).toContain("msteams");
     expect(formatMSTeamsSendErrorHint({ kind: "throttled" })).toContain("throttled");
   });
+
+  describe("isRevokedProxyError", () => {
+    it("returns true for revoked proxy TypeError", () => {
+      expect(
+        isRevokedProxyError(new TypeError("Cannot perform 'set' on a proxy that has been revoked")),
+      ).toBe(true);
+      expect(
+        isRevokedProxyError(new TypeError("Cannot perform 'get' on a proxy that has been revoked")),
+      ).toBe(true);
+    });
+
+    it("returns false for non-TypeError errors", () => {
+      expect(isRevokedProxyError(new Error("proxy that has been revoked"))).toBe(false);
+    });
+
+    it("returns false for unrelated TypeErrors", () => {
+      expect(isRevokedProxyError(new TypeError("undefined is not a function"))).toBe(false);
+    });
+
+    it("returns false for non-error values", () => {
+      expect(isRevokedProxyError(null)).toBe(false);
+      expect(isRevokedProxyError("proxy that has been revoked")).toBe(false);
+    });
+  });
 });

package/src/errors.ts

@@ -174,6 +174,21 @@ export function classifyMSTeamsSendError(err: unknown): MSTeamsSendErrorClassifi
   };
 }
 
+/**
+ * Detect whether an error is caused by a revoked Proxy.
+ *
+ * The Bot Framework SDK wraps TurnContext in a Proxy that is revoked once the
+ * turn handler returns.  Any later access (e.g. from a debounced callback)
+ * throws a TypeError whose message contains the distinctive "proxy that has
+ * been revoked" string.
+ */
+export function isRevokedProxyError(err: unknown): boolean {
+  if (!(err instanceof TypeError)) {
+    return false;
+  }
+  return /proxy that has been revoked/i.test(err.message);
+}
+
 export function formatMSTeamsSendErrorHint(
   classification: MSTeamsSendErrorClassification,
 ): string | undefined {

package/src/messenger.test.ts

@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { SILENT_REPLY_TOKEN, type PluginRuntime } from "openclaw/plugin-sdk";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createPluginRuntimeMock } from "../../test-utils/plugin-runtime-mock.js";
 import type { StoredConversationReference } from "./conversation-store.js";
 const graphUploadMockState = vi.hoisted(() => ({
   uploadAndShareOneDrive: vi.fn(),
@@ -38,7 +39,7 @@ const chunkMarkdownText = (text: string, limit: number) => {
   return chunks;
 };
 
-const runtimeStub = {
+const runtimeStub: PluginRuntime = createPluginRuntimeMock({
   channel: {
     text: {
       chunkMarkdownText,
@@ -47,7 +48,7 @@ const runtimeStub = {
       convertMarkdownTables: (text: string) => text,
     },
   },
-} as unknown as PluginRuntime;
+});
 
 const createNoopAdapter = (): MSTeamsAdapter => ({
   continueConversation: async () => {},
@@ -291,6 +292,79 @@ describe("msteams messenger", () => {
       ).rejects.toMatchObject({ statusCode: 400 });
     });
 
+    it("falls back to proactive messaging when thread context is revoked", async () => {
+      const proactiveSent: string[] = [];
+
+      const ctx = {
+        sendActivity: async () => {
+          throw new TypeError("Cannot perform 'set' on a proxy that has been revoked");
+        },
+      };
+
+      const adapter: MSTeamsAdapter = {
+        continueConversation: async (_appId, _reference, logic) => {
+          await logic({
+            sendActivity: createRecordedSendActivity(proactiveSent),
+          });
+        },
+        process: async () => {},
+      };
+
+      const ids = await sendMSTeamsMessages({
+        replyStyle: "thread",
+        adapter,
+        appId: "app123",
+        conversationRef: baseRef,
+        context: ctx,
+        messages: [{ text: "hello" }],
+      });
+
+      // Should have fallen back to proactive messaging
+      expect(proactiveSent).toEqual(["hello"]);
+      expect(ids).toEqual(["id:hello"]);
+    });
+
+    it("falls back only for remaining thread messages after context revocation", async () => {
+      const threadSent: string[] = [];
+      const proactiveSent: string[] = [];
+      let attempt = 0;
+
+      const ctx = {
+        sendActivity: async (activity: unknown) => {
+          const { text } = activity as { text?: string };
+          const content = text ?? "";
+          attempt += 1;
+          if (attempt === 1) {
+            threadSent.push(content);
+            return { id: `id:${content}` };
+          }
+          throw new TypeError("Cannot perform 'set' on a proxy that has been revoked");
+        },
+      };
+
+      const adapter: MSTeamsAdapter = {
+        continueConversation: async (_appId, _reference, logic) => {
+          await logic({
+            sendActivity: createRecordedSendActivity(proactiveSent),
+          });
+        },
+        process: async () => {},
+      };
+
+      const ids = await sendMSTeamsMessages({
+        replyStyle: "thread",
+        adapter,
+        appId: "app123",
+        conversationRef: baseRef,
+        context: ctx,
+        messages: [{ text: "one" }, { text: "two" }, { text: "three" }],
+      });
+
+      expect(threadSent).toEqual(["one"]);
+      expect(proactiveSent).toEqual(["two", "three"]);
+      expect(ids).toEqual(["id:one", "id:two", "id:three"]);
+    });
+
     it("retries top-level sends on transient (5xx)", async () => {
       const attempts: string[] = [];