@gakr-gakr/msteams 0.1.0

package/api.ts

@@ -0,0 +1,3 @@
+export { msteamsPlugin } from "./src/channel.js";
+export { createMSTeamsSetupWizardBase, msteamsSetupAdapter } from "./src/setup-core.js";
+export { msteamsSetupWizard, openDelegatedOAuthUrl } from "./src/setup-surface.js";

package/autobot.plugin.json

@@ -0,0 +1,15 @@
+{
+  "id": "msteams",
+  "activation": {
+    "onStartup": false
+  },
+  "channels": ["msteams"],
+  "channelEnvVars": {
+    "msteams": ["MSTEAMS_APP_ID", "MSTEAMS_APP_PASSWORD", "MSTEAMS_TENANT_ID"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/channel-config-api.ts

@@ -0,0 +1 @@
+export { MSTeamsChannelConfigSchema } from "./src/config-schema.js";

package/channel-plugin-api.ts

@@ -0,0 +1,2 @@
+export { msteamsPlugin } from "./src/channel.js";
+export type { ChannelPlugin } from "./src/channel-api.js";

package/config-api.ts

@@ -0,0 +1,4 @@
+export {
+  buildChannelConfigSchema,
+  MSTeamsConfigSchema,
+} from "autobot/plugin-sdk/bundled-channel-config-schema";

package/contract-api.ts

@@ -0,0 +1,4 @@
+export {
+  collectRuntimeConfigAssignments,
+  secretTargetRegistryEntries,
+} from "./src/secret-contract.js";

package/index.ts

@@ -0,0 +1,20 @@
+import { defineBundledChannelEntry } from "autobot/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelEntry({
+  id: "msteams",
+  name: "Microsoft Teams",
+  description: "Microsoft Teams channel plugin (Bot Framework)",
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./channel-plugin-api.js",
+    exportName: "msteamsPlugin",
+  },
+  secrets: {
+    specifier: "./secret-contract-api.js",
+    exportName: "channelSecrets",
+  },
+  runtime: {
+    specifier: "./runtime-api.js",
+    exportName: "setMSTeamsRuntime",
+  },
+});

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@gakr-gakr/msteams",
+  "version": "0.1.0",
+  "description": "AutoBot Microsoft Teams channel plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/autobot/autobot"
+  },
+  "type": "module",
+  "dependencies": {
+    "@azure/identity": "4.13.1",
+    "@microsoft/teams.api": "2.0.11",
+    "@microsoft/teams.apps": "2.0.11",
+    "express": "5.2.1",
+    "jsonwebtoken": "9.0.3",
+    "jwks-rsa": "4.0.1",
+    "typebox": "1.1.38"
+  },
+  "devDependencies": {
+    "@gakr-gakr/plugin-sdk": "workspace:*",
+    "@gakr-gakr/autobot": "workspace:*",
+    "@types/jsonwebtoken": "9.0.10",
+    "autobot": "workspace:@gakr-gakr/autobot@*"
+  },
+  "peerDependencies": {
+    "@gakr-gakr/autobot": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@gakr-gakr/autobot": {
+      "optional": true
+    }
+  },
+  "autobot": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "setupEntry": "./setup-entry.ts",
+    "channel": {
+      "id": "msteams",
+      "label": "Microsoft Teams",
+      "selectionLabel": "Microsoft Teams (Teams SDK)",
+      "docsPath": "/channels/msteams",
+      "docsLabel": "msteams",
+      "blurb": "Teams SDK; enterprise support.",
+      "aliases": [
+        "teams"
+      ],
+      "order": 60,
+      "doctorCapabilities": {
+        "dmAllowFromMode": "topOnly",
+        "groupModel": "hybrid",
+        "groupAllowFromFallbackToAllowFrom": true,
+        "warnOnEmptyGroupSenderAllowlist": true
+      }
+    },
+    "install": {
+      "npmSpec": "@gakr-gakr/msteams",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.10"
+    },
+    "compat": {
+      "pluginApi": ">=2026.5.19"
+    },
+    "build": {
+      "autobotVersion": "2026.5.19"
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    }
+  }
+}

package/runtime-api.ts

@@ -0,0 +1,66 @@
+// Private runtime barrel for the bundled Microsoft Teams extension.
+// Keep this barrel thin and aligned with the local extension surface.
+
+export { DEFAULT_ACCOUNT_ID } from "autobot/plugin-sdk/account-id";
+export type { AllowlistMatch } from "autobot/plugin-sdk/allow-from";
+export {
+  mergeAllowlist,
+  resolveAllowlistMatchSimple,
+  summarizeMapping,
+} from "autobot/plugin-sdk/allow-from";
+export type {
+  BaseProbeResult,
+  ChannelDirectoryEntry,
+  ChannelGroupContext,
+  ChannelMessageActionName,
+  ChannelOutboundAdapter,
+} from "autobot/plugin-sdk/channel-contract";
+export type { ChannelPlugin } from "autobot/plugin-sdk/channel-core";
+export { logTypingFailure } from "autobot/plugin-sdk/channel-logging";
+export { createChannelPairingController } from "autobot/plugin-sdk/channel-pairing";
+export { resolveToolsBySender } from "autobot/plugin-sdk/channel-policy";
+export { createChannelMessageReplyPipeline } from "autobot/plugin-sdk/channel-message";
+export {
+  PAIRING_APPROVED_MESSAGE,
+  buildProbeChannelStatusSummary,
+  createDefaultChannelRuntimeState,
+} from "autobot/plugin-sdk/channel-status";
+export {
+  buildChannelKeyCandidates,
+  normalizeChannelSlug,
+  resolveChannelEntryMatchWithFallback,
+  resolveNestedAllowlistDecision,
+} from "autobot/plugin-sdk/channel-targets";
+export type {
+  GroupPolicy,
+  GroupToolPolicyConfig,
+  MSTeamsChannelConfig,
+  MSTeamsConfig,
+  MSTeamsReplyStyle,
+  MSTeamsTeamConfig,
+  MarkdownTableMode,
+  AutoBotConfig,
+} from "autobot/plugin-sdk/config-contracts";
+export { isDangerousNameMatchingEnabled } from "autobot/plugin-sdk/dangerous-name-runtime";
+export { resolveDefaultGroupPolicy } from "autobot/plugin-sdk/runtime-group-policy";
+export { withFileLock } from "autobot/plugin-sdk/file-lock";
+export { keepHttpServerTaskAlive } from "autobot/plugin-sdk/channel-lifecycle";
+export {
+  detectMime,
+  extensionForMime,
+  extractOriginalFilename,
+  getFileExtension,
+  resolveChannelMediaMaxBytes,
+} from "autobot/plugin-sdk/media-runtime";
+export { dispatchReplyFromConfigWithSettledDispatcher } from "autobot/plugin-sdk/inbound-reply-dispatch";
+export { loadOutboundMediaFromUrl } from "autobot/plugin-sdk/outbound-media";
+export { buildMediaPayload } from "autobot/plugin-sdk/reply-payload";
+export type { ReplyPayload } from "autobot/plugin-sdk/reply-payload";
+export type { PluginRuntime } from "autobot/plugin-sdk/runtime-store";
+export type { RuntimeEnv } from "autobot/plugin-sdk/runtime";
+export type { SsrFPolicy } from "autobot/plugin-sdk/ssrf-runtime";
+export { fetchWithSsrFGuard } from "autobot/plugin-sdk/ssrf-runtime";
+export { normalizeStringEntries } from "autobot/plugin-sdk/string-normalization-runtime";
+export { chunkTextForOutbound } from "autobot/plugin-sdk/text-chunking";
+export { DEFAULT_WEBHOOK_MAX_BODY_BYTES } from "autobot/plugin-sdk/webhook-ingress";
+export { setMSTeamsRuntime } from "./src/runtime.js";

package/secret-contract-api.ts

@@ -0,0 +1,5 @@
+export {
+  channelSecrets,
+  collectRuntimeConfigAssignments,
+  secretTargetRegistryEntries,
+} from "./src/secret-contract.js";

package/setup-entry.ts

@@ -0,0 +1,13 @@
+import { defineBundledChannelSetupEntry } from "autobot/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelSetupEntry({
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./setup-plugin-api.js",
+    exportName: "msteamsSetupPlugin",
+  },
+  secrets: {
+    specifier: "./secret-contract-api.js",
+    exportName: "channelSecrets",
+  },
+});

package/setup-plugin-api.ts

@@ -0,0 +1,3 @@
+// Keep bundled setup entry imports narrow so setup loads do not pull the
+// broader Teams channel plugin surface.
+export { msteamsSetupPlugin } from "./src/channel.setup.js";

package/src/ai-entity.ts

@@ -0,0 +1,7 @@
+/** AI-generated content entity added to every outbound AI message. */
+export const AI_GENERATED_ENTITY = {
+  type: "https://schema.org/Message",
+  "@type": "Message",
+  "@id": "",
+  additionalType: ["AIGeneratedContent"],
+};

package/src/approval-auth.ts

@@ -0,0 +1,44 @@
+import {
+  createResolvedApproverActionAuthAdapter,
+  resolveApprovalApprovers,
+} from "autobot/plugin-sdk/approval-auth-runtime";
+import { normalizeOptionalLowercaseString } from "autobot/plugin-sdk/string-coerce-runtime";
+import type { AutoBotConfig } from "../runtime-api.js";
+import { normalizeMSTeamsMessagingTarget } from "./resolve-allowlist.js";
+
+const MSTEAMS_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function normalizeMSTeamsApproverId(value: string | number): string | undefined {
+  const normalized = normalizeMSTeamsMessagingTarget(String(value));
+  if (!normalized?.startsWith("user:")) {
+    return undefined;
+  }
+  const id = normalizeOptionalLowercaseString(normalized.slice("user:".length));
+  if (!id) {
+    return undefined;
+  }
+  return MSTEAMS_ID_RE.test(id) ? id : undefined;
+}
+
+function resolveMSTeamsChannelConfig(cfg: AutoBotConfig) {
+  return cfg.channels?.msteams;
+}
+
+export const msTeamsApprovalAuth = createResolvedApproverActionAuthAdapter({
+  channelLabel: "Microsoft Teams",
+  resolveApprovers: ({ cfg }) => {
+    const channel = resolveMSTeamsChannelConfig(cfg);
+    return resolveApprovalApprovers({
+      allowFrom: channel?.allowFrom,
+      defaultTo: channel?.defaultTo,
+      normalizeApprover: normalizeMSTeamsApproverId,
+    });
+  },
+  normalizeSenderId: (value) => {
+    const trimmed = normalizeOptionalLowercaseString(value);
+    if (!trimmed) {
+      return undefined;
+    }
+    return MSTEAMS_ID_RE.test(trimmed) ? trimmed : undefined;
+  },
+});

package/src/attachments/bot-framework.ts

@@ -0,0 +1,348 @@
+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,
+  };
+}