@openclaw/msteams 2026.1.29

package/src/resolve-allowlist.ts

@@ -0,0 +1,277 @@
+import { GRAPH_ROOT } from "./attachments/shared.js";
+import { loadMSTeamsSdkWithAuth } from "./sdk.js";
+import { resolveMSTeamsCredentials } from "./token.js";
+
+type GraphUser = {
+  id?: string;
+  displayName?: string;
+  userPrincipalName?: string;
+  mail?: string;
+};
+
+type GraphGroup = {
+  id?: string;
+  displayName?: string;
+};
+
+type GraphChannel = {
+  id?: string;
+  displayName?: string;
+};
+
+type GraphResponse<T> = { value?: T[] };
+
+export type MSTeamsChannelResolution = {
+  input: string;
+  resolved: boolean;
+  teamId?: string;
+  teamName?: string;
+  channelId?: string;
+  channelName?: string;
+  note?: string;
+};
+
+export type MSTeamsUserResolution = {
+  input: string;
+  resolved: boolean;
+  id?: string;
+  name?: string;
+  note?: string;
+};
+
+function readAccessToken(value: unknown): string | null {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object") {
+    const token =
+      (value as { accessToken?: unknown }).accessToken ?? (value as { token?: unknown }).token;
+    return typeof token === "string" ? token : null;
+  }
+  return null;
+}
+
+function stripProviderPrefix(raw: string): string {
+  return raw.replace(/^(msteams|teams):/i, "");
+}
+
+export function normalizeMSTeamsMessagingTarget(raw: string): string | undefined {
+  let trimmed = raw.trim();
+  if (!trimmed) return undefined;
+  trimmed = stripProviderPrefix(trimmed).trim();
+  if (/^conversation:/i.test(trimmed)) {
+    const id = trimmed.slice("conversation:".length).trim();
+    return id ? `conversation:${id}` : undefined;
+  }
+  if (/^user:/i.test(trimmed)) {
+    const id = trimmed.slice("user:".length).trim();
+    return id ? `user:${id}` : undefined;
+  }
+  return trimmed || undefined;
+}
+
+export function normalizeMSTeamsUserInput(raw: string): string {
+  return stripProviderPrefix(raw).replace(/^(user|conversation):/i, "").trim();
+}
+
+export function parseMSTeamsConversationId(raw: string): string | null {
+  const trimmed = stripProviderPrefix(raw).trim();
+  if (!/^conversation:/i.test(trimmed)) return null;
+  const id = trimmed.slice("conversation:".length).trim();
+  return id;
+}
+
+function normalizeMSTeamsTeamKey(raw: string): string | undefined {
+  const trimmed = stripProviderPrefix(raw).replace(/^team:/i, "").trim();
+  return trimmed || undefined;
+}
+
+function normalizeMSTeamsChannelKey(raw?: string | null): string | undefined {
+  const trimmed = raw?.trim().replace(/^#/, "").trim() ?? "";
+  return trimmed || undefined;
+}
+
+export function parseMSTeamsTeamChannelInput(raw: string): { team?: string; channel?: string } {
+  const trimmed = stripProviderPrefix(raw).trim();
+  if (!trimmed) return {};
+  const parts = trimmed.split("/");
+  const team = normalizeMSTeamsTeamKey(parts[0] ?? "");
+  const channel = parts.length > 1 ? normalizeMSTeamsChannelKey(parts.slice(1).join("/")) : undefined;
+  return {
+    ...(team ? { team } : {}),
+    ...(channel ? { channel } : {}),
+  };
+}
+
+export function parseMSTeamsTeamEntry(
+  raw: string,
+): { teamKey: string; channelKey?: string } | null {
+  const { team, channel } = parseMSTeamsTeamChannelInput(raw);
+  if (!team) return null;
+  return {
+    teamKey: team,
+    ...(channel ? { channelKey: channel } : {}),
+  };
+}
+
+function normalizeQuery(value?: string | null): string {
+  return value?.trim() ?? "";
+}
+
+function escapeOData(value: string): string {
+  return value.replace(/'/g, "''");
+}
+
+async function fetchGraphJson<T>(params: {
+  token: string;
+  path: string;
+  headers?: Record<string, string>;
+}): Promise<T> {
+  const res = await fetch(`${GRAPH_ROOT}${params.path}`, {
+    headers: {
+      Authorization: `Bearer ${params.token}`,
+      ...(params.headers ?? {}),
+    },
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`Graph ${params.path} failed (${res.status}): ${text || "unknown error"}`);
+  }
+  return (await res.json()) as T;
+}
+
+async function resolveGraphToken(cfg: unknown): Promise<string> {
+  const creds = resolveMSTeamsCredentials((cfg as { channels?: { msteams?: unknown } })?.channels?.msteams);
+  if (!creds) throw new Error("MS Teams credentials missing");
+  const { sdk, authConfig } = await loadMSTeamsSdkWithAuth(creds);
+  const tokenProvider = new sdk.MsalTokenProvider(authConfig);
+  const token = await tokenProvider.getAccessToken("https://graph.microsoft.com");
+  const accessToken = readAccessToken(token);
+  if (!accessToken) throw new Error("MS Teams graph token unavailable");
+  return accessToken;
+}
+
+async function listTeamsByName(token: string, query: string): Promise<GraphGroup[]> {
+  const escaped = escapeOData(query);
+  const filter = `resourceProvisioningOptions/Any(x:x eq 'Team') and startsWith(displayName,'${escaped}')`;
+  const path = `/groups?$filter=${encodeURIComponent(filter)}&$select=id,displayName`;
+  const res = await fetchGraphJson<GraphResponse<GraphGroup>>({ token, path });
+  return res.value ?? [];
+}
+
+async function listChannelsForTeam(token: string, teamId: string): Promise<GraphChannel[]> {
+  const path = `/teams/${encodeURIComponent(teamId)}/channels?$select=id,displayName`;
+  const res = await fetchGraphJson<GraphResponse<GraphChannel>>({ token, path });
+  return res.value ?? [];
+}
+
+export async function resolveMSTeamsChannelAllowlist(params: {
+  cfg: unknown;
+  entries: string[];
+}): Promise<MSTeamsChannelResolution[]> {
+  const token = await resolveGraphToken(params.cfg);
+  const results: MSTeamsChannelResolution[] = [];
+
+  for (const input of params.entries) {
+    const { team, channel } = parseMSTeamsTeamChannelInput(input);
+    if (!team) {
+      results.push({ input, resolved: false });
+      continue;
+    }
+    const teams =
+      /^[0-9a-fA-F-]{16,}$/.test(team) ? [{ id: team, displayName: team }] : await listTeamsByName(token, team);
+    if (teams.length === 0) {
+      results.push({ input, resolved: false, note: "team not found" });
+      continue;
+    }
+    const teamMatch = teams[0];
+    const teamId = teamMatch.id?.trim();
+    const teamName = teamMatch.displayName?.trim() || team;
+    if (!teamId) {
+      results.push({ input, resolved: false, note: "team id missing" });
+      continue;
+    }
+    if (!channel) {
+      results.push({
+        input,
+        resolved: true,
+        teamId,
+        teamName,
+        note: teams.length > 1 ? "multiple teams; chose first" : undefined,
+      });
+      continue;
+    }
+    const channels = await listChannelsForTeam(token, teamId);
+    const channelMatch =
+      channels.find((item) => item.id === channel) ??
+      channels.find(
+        (item) => item.displayName?.toLowerCase() === channel.toLowerCase(),
+      ) ??
+      channels.find(
+        (item) => item.displayName?.toLowerCase().includes(channel.toLowerCase() ?? ""),
+      );
+    if (!channelMatch?.id) {
+      results.push({ input, resolved: false, note: "channel not found" });
+      continue;
+    }
+    results.push({
+      input,
+      resolved: true,
+      teamId,
+      teamName,
+      channelId: channelMatch.id,
+      channelName: channelMatch.displayName ?? channel,
+      note: channels.length > 1 ? "multiple channels; chose first" : undefined,
+    });
+  }
+
+  return results;
+}
+
+export async function resolveMSTeamsUserAllowlist(params: {
+  cfg: unknown;
+  entries: string[];
+}): Promise<MSTeamsUserResolution[]> {
+  const token = await resolveGraphToken(params.cfg);
+  const results: MSTeamsUserResolution[] = [];
+
+  for (const input of params.entries) {
+    const query = normalizeQuery(normalizeMSTeamsUserInput(input));
+    if (!query) {
+      results.push({ input, resolved: false });
+      continue;
+    }
+    if (/^[0-9a-fA-F-]{16,}$/.test(query)) {
+      results.push({ input, resolved: true, id: query });
+      continue;
+    }
+    let users: GraphUser[] = [];
+    if (query.includes("@")) {
+      const escaped = escapeOData(query);
+      const filter = `(mail eq '${escaped}' or userPrincipalName eq '${escaped}')`;
+      const path = `/users?$filter=${encodeURIComponent(filter)}&$select=id,displayName,mail,userPrincipalName`;
+      const res = await fetchGraphJson<GraphResponse<GraphUser>>({ token, path });
+      users = res.value ?? [];
+    } else {
+      const path = `/users?$search=${encodeURIComponent(`"displayName:${query}"`)}&$select=id,displayName,mail,userPrincipalName&$top=10`;
+      const res = await fetchGraphJson<GraphResponse<GraphUser>>({
+        token,
+        path,
+        headers: { ConsistencyLevel: "eventual" },
+      });
+      users = res.value ?? [];
+    }
+    const match = users[0];
+    if (!match?.id) {
+      results.push({ input, resolved: false });
+      continue;
+    }
+    results.push({
+      input,
+      resolved: true,
+      id: match.id,
+      name: match.displayName ?? undefined,
+      note: users.length > 1 ? "multiple matches; chose first" : undefined,
+    });
+  }
+
+  return results;
+}

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setMSTeamsRuntime(next: PluginRuntime) {
+  runtime = next;
+}
+
+export function getMSTeamsRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("MSTeams runtime not initialized");
+  }
+  return runtime;
+}

package/src/sdk-types.ts

@@ -0,0 +1,19 @@
+import type { TurnContext } from "@microsoft/agents-hosting";
+
+/**
+ * Minimal public surface we depend on from the Microsoft SDK types.
+ *
+ * Note: we intentionally avoid coupling to SDK classes with private members
+ * (like TurnContext) in our own public signatures. The SDK's TS surface is also
+ * stricter than what the runtime accepts (e.g. it allows plain activity-like
+ * objects), so we model the minimal structural shape we rely on.
+ */
+export type MSTeamsActivity = TurnContext["activity"];
+
+export type MSTeamsTurnContext = {
+  activity: MSTeamsActivity;
+  sendActivity: (textOrActivity: string | object) => Promise<unknown>;
+  sendActivities: (
+    activities: Array<{ type: string } & Record<string, unknown>>,
+  ) => Promise<unknown>;
+};

package/src/sdk.ts

@@ -0,0 +1,33 @@
+import type { MSTeamsAdapter } from "./messenger.js";
+import type { MSTeamsCredentials } from "./token.js";
+
+export type MSTeamsSdk = typeof import("@microsoft/agents-hosting");
+export type MSTeamsAuthConfig = ReturnType<MSTeamsSdk["getAuthConfigWithDefaults"]>;
+
+export async function loadMSTeamsSdk(): Promise<MSTeamsSdk> {
+  return await import("@microsoft/agents-hosting");
+}
+
+export function buildMSTeamsAuthConfig(
+  creds: MSTeamsCredentials,
+  sdk: MSTeamsSdk,
+): MSTeamsAuthConfig {
+  return sdk.getAuthConfigWithDefaults({
+    clientId: creds.appId,
+    clientSecret: creds.appPassword,
+    tenantId: creds.tenantId,
+  });
+}
+
+export function createMSTeamsAdapter(
+  authConfig: MSTeamsAuthConfig,
+  sdk: MSTeamsSdk,
+): MSTeamsAdapter {
+  return new sdk.CloudAdapter(authConfig) as unknown as MSTeamsAdapter;
+}
+
+export async function loadMSTeamsSdkWithAuth(creds: MSTeamsCredentials) {
+  const sdk = await loadMSTeamsSdk();
+  const authConfig = buildMSTeamsAuthConfig(creds, sdk);
+  return { sdk, authConfig };
+}

package/src/send-context.ts

@@ -0,0 +1,156 @@
+import { resolveChannelMediaMaxBytes, type OpenClawConfig, type PluginRuntime } from "openclaw/plugin-sdk";
+import type { MSTeamsAccessTokenProvider } from "./attachments/types.js";
+import type {
+  MSTeamsConversationStore,
+  StoredConversationReference,
+} from "./conversation-store.js";
+import { createMSTeamsConversationStoreFs } from "./conversation-store-fs.js";
+import type { MSTeamsAdapter } from "./messenger.js";
+import { getMSTeamsRuntime } from "./runtime.js";
+import { createMSTeamsAdapter, loadMSTeamsSdkWithAuth } from "./sdk.js";
+import { resolveMSTeamsCredentials } from "./token.js";
+
+export type MSTeamsConversationType = "personal" | "groupChat" | "channel";
+
+export type MSTeamsProactiveContext = {
+  appId: string;
+  conversationId: string;
+  ref: StoredConversationReference;
+  adapter: MSTeamsAdapter;
+  log: ReturnType<PluginRuntime["logging"]["getChildLogger"]>;
+  /** The type of conversation: personal (1:1), groupChat, or channel */
+  conversationType: MSTeamsConversationType;
+  /** Token provider for Graph API / OneDrive operations */
+  tokenProvider: MSTeamsAccessTokenProvider;
+  /** SharePoint site ID for file uploads in group chats/channels */
+  sharePointSiteId?: string;
+  /** Resolved media max bytes from config (default: 100MB) */
+  mediaMaxBytes?: number;
+};
+
+/**
+ * Parse the target value into a conversation reference lookup key.
+ * Supported formats:
+ * - conversation:19:abc@thread.tacv2 → lookup by conversation ID
+ * - user:aad-object-id → lookup by user AAD object ID
+ * - 19:abc@thread.tacv2 → direct conversation ID
+ */
+function parseRecipient(to: string): {
+  type: "conversation" | "user";
+  id: string;
+} {
+  const trimmed = to.trim();
+  const finalize = (type: "conversation" | "user", id: string) => {
+    const normalized = id.trim();
+    if (!normalized) {
+      throw new Error(`Invalid target value: missing ${type} id`);
+    }
+    return { type, id: normalized };
+  };
+  if (trimmed.startsWith("conversation:")) {
+    return finalize("conversation", trimmed.slice("conversation:".length));
+  }
+  if (trimmed.startsWith("user:")) {
+    return finalize("user", trimmed.slice("user:".length));
+  }
+  // Assume it's a conversation ID if it looks like one
+  if (trimmed.startsWith("19:") || trimmed.includes("@thread")) {
+    return finalize("conversation", trimmed);
+  }
+  // Otherwise treat as user ID
+  return finalize("user", trimmed);
+}
+
+/**
+ * Find a stored conversation reference for the given recipient.
+ */
+async function findConversationReference(recipient: {
+  type: "conversation" | "user";
+  id: string;
+  store: MSTeamsConversationStore;
+}): Promise<{
+  conversationId: string;
+  ref: StoredConversationReference;
+} | null> {
+  if (recipient.type === "conversation") {
+    const ref = await recipient.store.get(recipient.id);
+    if (ref) return { conversationId: recipient.id, ref };
+    return null;
+  }
+
+  const found = await recipient.store.findByUserId(recipient.id);
+  if (!found) return null;
+  return { conversationId: found.conversationId, ref: found.reference };
+}
+
+export async function resolveMSTeamsSendContext(params: {
+  cfg: OpenClawConfig;
+  to: string;
+}): Promise<MSTeamsProactiveContext> {
+  const msteamsCfg = params.cfg.channels?.msteams;
+
+  if (!msteamsCfg?.enabled) {
+    throw new Error("msteams provider is not enabled");
+  }
+
+  const creds = resolveMSTeamsCredentials(msteamsCfg);
+  if (!creds) {
+    throw new Error("msteams credentials not configured");
+  }
+
+  const store = createMSTeamsConversationStoreFs();
+
+  // Parse recipient and find conversation reference
+  const recipient = parseRecipient(params.to);
+  const found = await findConversationReference({ ...recipient, store });
+
+  if (!found) {
+    throw new Error(
+      `No conversation reference found for ${recipient.type}:${recipient.id}. ` +
+        `The bot must receive a message from this conversation before it can send proactively.`,
+    );
+  }
+
+  const { conversationId, ref } = found;
+  const core = getMSTeamsRuntime();
+  const log = core.logging.getChildLogger({ name: "msteams:send" });
+
+  const { sdk, authConfig } = await loadMSTeamsSdkWithAuth(creds);
+  const adapter = createMSTeamsAdapter(authConfig, sdk);
+
+  // Create token provider for Graph API / OneDrive operations
+  const tokenProvider = new sdk.MsalTokenProvider(authConfig) as MSTeamsAccessTokenProvider;
+
+  // Determine conversation type from stored reference
+  const storedConversationType = ref.conversation?.conversationType?.toLowerCase() ?? "";
+  let conversationType: MSTeamsConversationType;
+  if (storedConversationType === "personal") {
+    conversationType = "personal";
+  } else if (storedConversationType === "channel") {
+    conversationType = "channel";
+  } else {
+    // groupChat, or unknown defaults to groupChat behavior
+    conversationType = "groupChat";
+  }
+
+  // Get SharePoint site ID from config (required for file uploads in group chats/channels)
+  const sharePointSiteId = msteamsCfg.sharePointSiteId;
+
+  // Resolve media max bytes from config
+  const mediaMaxBytes = resolveChannelMediaMaxBytes({
+    cfg: params.cfg,
+    resolveChannelLimitMb: ({ cfg }) => cfg.channels?.msteams?.mediaMaxMb,
+  });
+
+  return {
+    appId: creds.appId,
+    conversationId,
+    ref,
+    adapter: adapter as unknown as MSTeamsAdapter,
+    log,
+    conversationType,
+    tokenProvider,
+    sharePointSiteId,
+    mediaMaxBytes,
+  };
+}