@gakr-gakr/msteams 0.1.0

package/src/monitor-handler/access.ts

@@ -0,0 +1,136 @@
+import {
+  channelIngressRoutes,
+  resolveStableChannelMessageIngress,
+  type StableChannelIngressIdentityParams,
+} from "autobot/plugin-sdk/channel-ingress-runtime";
+import { normalizeOptionalLowercaseString } from "autobot/plugin-sdk/string-coerce-runtime";
+import {
+  DEFAULT_ACCOUNT_ID,
+  createChannelPairingController,
+  isDangerousNameMatchingEnabled,
+  resolveDefaultGroupPolicy,
+  type AutoBotConfig,
+} from "../../runtime-api.js";
+import { normalizeMSTeamsConversationId } from "../inbound.js";
+import { resolveMSTeamsRouteConfig } from "../policy.js";
+import { getMSTeamsRuntime } from "../runtime.js";
+import type { MSTeamsTurnContext } from "../sdk-types.js";
+
+const MSTEAMS_SENDER_NAME_KIND = "plugin:msteams-sender-name" as const;
+const msteamsIngressIdentity = {
+  key: "sender-id",
+  normalize: normalizeIngressValue,
+  aliases: [
+    {
+      key: "sender-name",
+      kind: MSTEAMS_SENDER_NAME_KIND,
+      normalizeEntry: normalizeIngressValue,
+      normalizeSubject: normalizeIngressValue,
+      dangerous: true,
+    },
+  ],
+  isWildcardEntry: (entry) => normalizeIngressValue(entry) === "*",
+  resolveEntryId: ({ entryIndex, fieldKey }) =>
+    `msteams-entry-${entryIndex + 1}:${fieldKey === "sender-name" ? "name" : "id"}`,
+} satisfies StableChannelIngressIdentityParams;
+
+function normalizeIngressValue(value?: string | null): string | null {
+  return normalizeOptionalLowercaseString(value) ?? null;
+}
+
+export async function resolveMSTeamsSenderAccess(params: {
+  cfg: AutoBotConfig;
+  activity: MSTeamsTurnContext["activity"];
+  hasControlCommand?: boolean;
+}) {
+  const activity = params.activity;
+  const msteamsCfg = params.cfg.channels?.msteams;
+  const conversationId = normalizeMSTeamsConversationId(activity.conversation?.id ?? "unknown");
+  const convType = normalizeOptionalLowercaseString(activity.conversation?.conversationType);
+  const isDirectMessage = convType === "personal" || (!convType && !activity.conversation?.isGroup);
+  const senderId = activity.from?.aadObjectId ?? activity.from?.id ?? "unknown";
+  const senderName = activity.from?.name ?? activity.from?.id ?? senderId;
+
+  const core = getMSTeamsRuntime();
+  const pairing = createChannelPairingController({
+    core,
+    channel: "msteams",
+    accountId: DEFAULT_ACCOUNT_ID,
+  });
+  const dmPolicy = msteamsCfg?.dmPolicy ?? "pairing";
+  const configuredDmAllowFrom = msteamsCfg?.allowFrom ?? [];
+  const groupAllowFrom = msteamsCfg?.groupAllowFrom;
+  const defaultGroupPolicy = resolveDefaultGroupPolicy(params.cfg);
+  const groupPolicy =
+    !isDirectMessage && msteamsCfg
+      ? (msteamsCfg.groupPolicy ?? defaultGroupPolicy ?? "allowlist")
+      : "disabled";
+  const allowNameMatching = isDangerousNameMatchingEnabled(msteamsCfg);
+  const channelGate = resolveMSTeamsRouteConfig({
+    cfg: msteamsCfg,
+    teamId: activity.channelData?.team?.id,
+    teamName: activity.channelData?.team?.name,
+    conversationId,
+    channelName: activity.channelData?.channel?.name,
+    allowNameMatching,
+  });
+
+  const resolved = await resolveStableChannelMessageIngress({
+    channelId: "msteams",
+    accountId: pairing.accountId,
+    identity: msteamsIngressIdentity,
+    cfg: params.cfg,
+    readStoreAllowFrom: pairing.readAllowFromStore,
+    subject: {
+      stableId: senderId,
+      aliases: { "sender-name": senderName },
+    },
+    conversation: {
+      kind: isDirectMessage ? "direct" : convType === "channel" ? "channel" : "group",
+      id: conversationId,
+      parentId: activity.channelData?.team?.id,
+    },
+    route: channelIngressRoutes(
+      !isDirectMessage &&
+        channelGate.allowlistConfigured && {
+          id: "msteams:team-channel",
+          kind: "nestedAllowlist",
+          allowed: channelGate.allowed,
+          precedence: 0,
+          matchId: "msteams-route",
+          ...(channelGate.allowed && groupPolicy === "allowlist"
+            ? {
+                senderPolicy: "deny-when-empty" as const,
+                senderAllowFromSource: "effective-group" as const,
+              }
+            : {}),
+        },
+    ),
+    dmPolicy,
+    groupPolicy,
+    policy: {
+      groupAllowFromFallbackToAllowFrom: true,
+      mutableIdentifierMatching: allowNameMatching ? "enabled" : "disabled",
+    },
+    allowFrom: configuredDmAllowFrom,
+    groupAllowFrom,
+    command: {
+      allowTextCommands: true,
+      hasControlCommand: params.hasControlCommand === true,
+      directGroupAllowFrom: isDirectMessage ? "effective" : "none",
+    },
+  });
+  return {
+    ...resolved,
+    pairing,
+    isDirectMessage,
+    conversationId,
+    senderId,
+    senderName,
+    msteamsCfg,
+    dmPolicy,
+    channelGate,
+    allowNameMatching,
+    groupPolicy,
+  };
+}

package/src/monitor-handler/inbound-media.ts

@@ -0,0 +1,180 @@
+import {
+  buildMSTeamsGraphMessageUrls,
+  downloadMSTeamsAttachments,
+  downloadMSTeamsBotFrameworkAttachments,
+  downloadMSTeamsGraphMedia,
+  extractMSTeamsHtmlAttachmentIds,
+  isBotFrameworkPersonalChatId,
+  type MSTeamsAccessTokenProvider,
+  type MSTeamsAttachmentLike,
+  type MSTeamsHtmlAttachmentSummary,
+  type MSTeamsInboundMedia,
+} from "../attachments.js";
+import type { MSTeamsTurnContext } from "../sdk-types.js";
+
+type MSTeamsLogger = {
+  debug?: (message: string, meta?: Record<string, unknown>) => void;
+  warn?: (message: string, meta?: Record<string, unknown>) => void;
+  error?: (message: string, meta?: Record<string, unknown>) => void;
+};
+
+export async function resolveMSTeamsInboundMedia(params: {
+  attachments: MSTeamsAttachmentLike[];
+  htmlSummary?: MSTeamsHtmlAttachmentSummary;
+  maxBytes: number;
+  allowHosts?: string[];
+  authAllowHosts?: string[];
+  tokenProvider: MSTeamsAccessTokenProvider;
+  conversationType: string;
+  conversationId: string;
+  conversationMessageId?: string;
+  serviceUrl?: string;
+  activity: Pick<MSTeamsTurnContext["activity"], "id" | "replyToId" | "channelData">;
+  log: MSTeamsLogger;
+  /** When true, embeds original filename in stored path for later extraction. */
+  preserveFilenames?: boolean;
+}): Promise<MSTeamsInboundMedia[]> {
+  const {
+    attachments,
+    htmlSummary,
+    maxBytes,
+    tokenProvider,
+    allowHosts,
+    conversationType,
+    conversationId,
+    conversationMessageId,
+    serviceUrl,
+    activity,
+    log,
+    preserveFilenames,
+  } = params;
+
+  let mediaList = await downloadMSTeamsAttachments({
+    attachments,
+    maxBytes,
+    tokenProvider,
+    allowHosts,
+    authAllowHosts: params.authAllowHosts,
+    preserveFilenames,
+    logger: log,
+  });
+
+  if (mediaList.length === 0) {
+    // Gate the Graph/Bot Framework media fallback on the presence of real
+    // `<attachment id="...">` tags inside any `text/html` attachment. Teams
+    // delivers @mention cards and other chrome as `text/html` attachments
+    // too, so keying off contentType alone produces spurious 404 diagnostics
+    // for every mention-only message and masks real file attachments (#58617).
+    const attachmentIds = extractMSTeamsHtmlAttachmentIds(attachments);
+    const hasHtmlFileAttachment = attachmentIds.length > 0;
+
+    // Personal DMs with the bot use Bot Framework conversation IDs (`a:...`
+    // or `8:orgid:...`) which Graph's `/chats/{id}` endpoint rejects with
+    // "Invalid ThreadId". Fetch media via the Bot Framework v3 attachments
+    // endpoint instead, which speaks the same identifier space.
+    if (hasHtmlFileAttachment && isBotFrameworkPersonalChatId(conversationId)) {
+      if (!serviceUrl) {
+        log.debug?.("bot framework attachment skipped (missing serviceUrl)", {
+          conversationType,
+          conversationId,
+        });
+      } else {
+        const bfMedia = await downloadMSTeamsBotFrameworkAttachments({
+          serviceUrl,
+          attachmentIds,
+          tokenProvider,
+          maxBytes,
+          allowHosts,
+          authAllowHosts: params.authAllowHosts,
+          preserveFilenames,
+        });
+        if (bfMedia.media.length > 0) {
+          mediaList = bfMedia.media;
+        } else {
+          log.debug?.("bot framework attachments fetch empty", {
+            conversationType,
+            attachmentCount: bfMedia.attachmentCount ?? attachmentIds.length,
+          });
+        }
+      }
+    }
+
+    if (
+      hasHtmlFileAttachment &&
+      mediaList.length === 0 &&
+      !isBotFrameworkPersonalChatId(conversationId)
+    ) {
+      const messageUrls = buildMSTeamsGraphMessageUrls({
+        conversationType,
+        conversationId,
+        messageId: activity.id ?? undefined,
+        replyToId: activity.replyToId ?? undefined,
+        conversationMessageId,
+        channelData: activity.channelData,
+      });
+      if (messageUrls.length === 0) {
+        log.debug?.("graph message url unavailable", {
+          conversationType,
+          hasChannelData: Boolean(activity.channelData),
+          messageId: activity.id ?? undefined,
+          replyToId: activity.replyToId ?? undefined,
+        });
+      } else {
+        const attempts: Array<{
+          url: string;
+          hostedStatus?: number;
+          attachmentStatus?: number;
+          hostedCount?: number;
+          attachmentCount?: number;
+          tokenError?: boolean;
+        }> = [];
+        for (const messageUrl of messageUrls) {
+          const graphMedia = await downloadMSTeamsGraphMedia({
+            messageUrl,
+            tokenProvider,
+            maxBytes,
+            allowHosts,
+            authAllowHosts: params.authAllowHosts,
+            preserveFilenames,
+            log,
+            logger: log,
+          });
+          attempts.push({
+            url: messageUrl,
+            hostedStatus: graphMedia.hostedStatus,
+            attachmentStatus: graphMedia.attachmentStatus,
+            hostedCount: graphMedia.hostedCount,
+            attachmentCount: graphMedia.attachmentCount,
+            tokenError: graphMedia.tokenError,
+          });
+          if (graphMedia.media.length > 0) {
+            mediaList = graphMedia.media;
+            break;
+          }
+          if (graphMedia.tokenError) {
+            break;
+          }
+        }
+        if (mediaList.length === 0) {
+          log.debug?.("graph media fetch empty", {
+            attempts,
+            attachmentIdCount: attachmentIds.length,
+          });
+        }
+      }
+    }
+  }
+
+  if (mediaList.length > 0) {
+    log.debug?.("downloaded attachments", { count: mediaList.length });
+  } else if (htmlSummary?.imgTags) {
+    log.debug?.("inline images detected but none downloaded", {
+      imgTags: htmlSummary.imgTags,
+      srcHosts: htmlSummary.srcHosts,
+      dataImages: htmlSummary.dataImages,
+      cidImages: htmlSummary.cidImages,
+    });
+  }
+
+  return mediaList;
+}

package/src/monitor-handler/message-handler-mock-support.test-support.ts

@@ -0,0 +1,28 @@
+import { vi } from "vitest";
+
+const runtimeApiMockState = vi.hoisted(() => ({
+  dispatchReplyFromConfigWithSettledDispatcher: vi.fn(async (params: { ctxPayload: unknown }) => ({
+    queuedFinal: false,
+    counts: {},
+    capturedCtxPayload: params.ctxPayload,
+  })),
+}));
+
+export function getRuntimeApiMockState() {
+  return runtimeApiMockState;
+}
+
+vi.mock("autobot/plugin-sdk/inbound-reply-dispatch", () => {
+  return {
+    dispatchReplyFromConfigWithSettledDispatcher:
+      runtimeApiMockState.dispatchReplyFromConfigWithSettledDispatcher,
+  };
+});
+
+vi.mock("../reply-dispatcher.js", () => ({
+  createMSTeamsReplyDispatcher: () => ({
+    dispatcher: {},
+    replyOptions: {},
+    markDispatchIdle: vi.fn(),
+  }),
+}));

package/src/monitor-handler/message-handler.test-support.ts

@@ -0,0 +1,102 @@
+import { vi } from "vitest";
+import type { AutoBotConfig, PluginRuntime, RuntimeEnv } from "../../runtime-api.js";
+import type { MSTeamsMessageHandlerDeps } from "../monitor-handler.js";
+import { installMSTeamsTestRuntime } from "../monitor-handler.test-helpers.js";
+
+export const channelConversationId = "19:general@thread.tacv2";
+
+type MessageHandlerDepsOptions = {
+  enqueueSystemEvent?: ReturnType<typeof vi.fn>;
+  readAllowFromStore?: ReturnType<typeof vi.fn>;
+  upsertPairingRequest?: ReturnType<typeof vi.fn>;
+  recordInboundSession?: ReturnType<typeof vi.fn>;
+  resolveAgentRoute?: (params: { peer: { kind: string; id: string } }) => unknown;
+  hasControlCommand?: PluginRuntime["channel"]["text"]["hasControlCommand"];
+};
+
+export function createMessageHandlerDeps(
+  cfg: AutoBotConfig,
+  options: MessageHandlerDepsOptions = {},
+) {
+  const enqueueSystemEvent = options.enqueueSystemEvent ?? vi.fn();
+  const readAllowFromStore = options.readAllowFromStore ?? vi.fn(async () => []);
+  const upsertPairingRequest = options.upsertPairingRequest ?? vi.fn(async () => null);
+  const recordInboundSession =
+    options.recordInboundSession ?? vi.fn(async (_params: { sessionKey: string }) => undefined);
+  const resolveAgentRoute =
+    options.resolveAgentRoute ??
+    vi.fn(({ peer }: { peer: { kind: string; id: string } }) => ({
+      sessionKey: `agent:main:msteams:${peer.kind}:${peer.id}`,
+      agentId: "main",
+      accountId: "default",
+      mainSessionKey: "agent:main:main",
+      lastRoutePolicy: "session" as const,
+      matchedBy: "default" as const,
+    }));
+
+  installMSTeamsTestRuntime({
+    enqueueSystemEvent,
+    readAllowFromStore,
+    upsertPairingRequest,
+    recordInboundSession,
+    resolveAgentRoute,
+    hasControlCommand: options.hasControlCommand,
+    resolveTextChunkLimit: () => 4000,
+    resolveStorePath: () => "/tmp/test-store",
+  });
+
+  const conversationStore = {
+    get: vi.fn(async () => null),
+    upsert: vi.fn(async () => undefined),
+    list: vi.fn(async () => []),
+    remove: vi.fn(async () => false),
+    findPreferredDmByUserId: vi.fn(async () => null),
+    findByUserId: vi.fn(async () => null),
+  } satisfies MSTeamsMessageHandlerDeps["conversationStore"];
+
+  const deps: MSTeamsMessageHandlerDeps = {
+    cfg,
+    runtime: { error: vi.fn() } as unknown as RuntimeEnv,
+    appId: "test-app",
+    adapter: {} as MSTeamsMessageHandlerDeps["adapter"],
+    tokenProvider: {
+      getAccessToken: vi.fn(async () => "token"),
+    },
+    textLimit: 4000,
+    mediaMaxBytes: 1024 * 1024,
+    conversationStore,
+    pollStore: {
+      recordVote: vi.fn(async () => null),
+    } as unknown as MSTeamsMessageHandlerDeps["pollStore"],
+    log: {
+      info: vi.fn(),
+      debug: vi.fn(),
+      error: vi.fn(),
+    } as unknown as MSTeamsMessageHandlerDeps["log"],
+  };
+
+  return {
+    conversationStore,
+    deps,
+    enqueueSystemEvent,
+    readAllowFromStore,
+    upsertPairingRequest,
+    recordInboundSession,
+    resolveAgentRoute,
+  };
+}
+
+export function buildChannelActivity(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "msg-1",
+    type: "message",
+    text: "hello",
+    from: { id: "user-id", aadObjectId: "user-aad", name: "Test User" },
+    recipient: { id: "bot-id", name: "Bot" },
+    conversation: { id: channelConversationId, conversationType: "channel" },
+    channelData: { team: { id: "team-1" } },
+    attachments: [],
+    entities: [{ type: "mention", mentioned: { id: "bot-id" } }],
+    ...overrides,
+  };
+}