@openclaw/msteams 2026.3.13 → 2026.5.1-beta.1

package/src/token.ts

@@ -1,17 +1,75 @@
-import type { MSTeamsConfig } from "openclaw/plugin-sdk/msteams";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import type { MSTeamsConfig } from "../runtime-api.js";
+import type { MSTeamsDelegatedTokens } from "./oauth.shared.js";
+import { refreshMSTeamsDelegatedTokens } from "./oauth.token.js";
 import {
   hasConfiguredSecretInput,
   normalizeResolvedSecretInputString,
   normalizeSecretInputString,
 } from "./secret-input.js";
+import { resolveMSTeamsStorePath } from "./storage.js";
 
-export type MSTeamsCredentials = {
+// ── Credential types ───────────────────────────────────────────────────────
+
+export type MSTeamsSecretCredentials = {
+  type: "secret";
   appId: string;
   appPassword: string;
   tenantId: string;
 };
 
+export type MSTeamsFederatedCredentials = {
+  type: "federated";
+  appId: string;
+  tenantId: string;
+  certificatePath?: string;
+  certificateThumbprint?: string;
+  useManagedIdentity?: boolean;
+  managedIdentityClientId?: string;
+};
+
+export type MSTeamsCredentials = MSTeamsSecretCredentials | MSTeamsFederatedCredentials;
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function resolveAuthType(cfg?: MSTeamsConfig): "secret" | "federated" {
+  const fromCfg = cfg?.authType;
+  if (fromCfg === "secret" || fromCfg === "federated") {
+    return fromCfg;
+  }
+
+  const fromEnv = process.env.MSTEAMS_AUTH_TYPE;
+  if (fromEnv === "federated") {
+    return "federated";
+  }
+
+  return "secret";
+}
+
+// ── hasConfiguredMSTeamsCredentials ────────────────────────────────────────
+
 export function hasConfiguredMSTeamsCredentials(cfg?: MSTeamsConfig): boolean {
+  const authType = resolveAuthType(cfg);
+
+  const hasAppId = Boolean(
+    normalizeSecretInputString(cfg?.appId) ||
+    normalizeSecretInputString(process.env.MSTEAMS_APP_ID),
+  );
+  const hasTenantId = Boolean(
+    normalizeSecretInputString(cfg?.tenantId) ||
+    normalizeSecretInputString(process.env.MSTEAMS_TENANT_ID),
+  );
+
+  if (authType === "federated") {
+    const hasCert = Boolean(cfg?.certificatePath || process.env.MSTEAMS_CERTIFICATE_PATH);
+    const hasManagedIdentity =
+      cfg?.useManagedIdentity ?? process.env.MSTEAMS_USE_MANAGED_IDENTITY === "true";
+
+    return hasAppId && hasTenantId && (hasCert || hasManagedIdentity);
+  }
+
+  // "secret" (default) — original logic
   return Boolean(
     normalizeSecretInputString(cfg?.appId) &&
     hasConfiguredSecretInput(cfg?.appPassword) &&
@@ -19,22 +77,119 @@ export function hasConfiguredMSTeamsCredentials(cfg?: MSTeamsConfig): boolean {
   );
 }
 
+// ── resolveMSTeamsCredentials ─────────────────────────────────────────────
+
 export function resolveMSTeamsCredentials(cfg?: MSTeamsConfig): MSTeamsCredentials | undefined {
+  const authType = resolveAuthType(cfg);
+
   const appId =
     normalizeSecretInputString(cfg?.appId) ||
     normalizeSecretInputString(process.env.MSTEAMS_APP_ID);
+
+  const tenantId =
+    normalizeSecretInputString(cfg?.tenantId) ||
+    normalizeSecretInputString(process.env.MSTEAMS_TENANT_ID);
+
+  if (!appId || !tenantId) {
+    return undefined;
+  }
+
+  if (authType === "federated") {
+    const certificatePath =
+      cfg?.certificatePath || process.env.MSTEAMS_CERTIFICATE_PATH || undefined;
+
+    const certificateThumbprint =
+      cfg?.certificateThumbprint || process.env.MSTEAMS_CERTIFICATE_THUMBPRINT || undefined;
+
+    const useManagedIdentity =
+      cfg?.useManagedIdentity ?? process.env.MSTEAMS_USE_MANAGED_IDENTITY === "true";
+
+    const managedIdentityClientId =
+      cfg?.managedIdentityClientId || process.env.MSTEAMS_MANAGED_IDENTITY_CLIENT_ID || undefined;
+
+    // At least one federated mechanism must be configured.
+    if (!certificatePath && !useManagedIdentity) {
+      return undefined;
+    }
+
+    return {
+      type: "federated",
+      appId,
+      tenantId,
+      certificatePath,
+      certificateThumbprint,
+      useManagedIdentity: useManagedIdentity || undefined,
+      managedIdentityClientId,
+    };
+  }
+
+  // "secret" (default) — original logic
   const appPassword =
     normalizeResolvedSecretInputString({
       value: cfg?.appPassword,
       path: "channels.msteams.appPassword",
     }) || normalizeSecretInputString(process.env.MSTEAMS_APP_PASSWORD);
-  const tenantId =
-    normalizeSecretInputString(cfg?.tenantId) ||
-    normalizeSecretInputString(process.env.MSTEAMS_TENANT_ID);
 
-  if (!appId || !appPassword || !tenantId) {
+  if (!appPassword) {
     return undefined;
   }
 
-  return { appId, appPassword, tenantId };
+  return { type: "secret", appId, appPassword, tenantId };
+}
+
+// ---------------------------------------------------------------------------
+// Delegated token storage / resolution
+// ---------------------------------------------------------------------------
+
+const DELEGATED_TOKEN_FILENAME = "msteams-delegated.json";
+
+function resolveDelegatedTokenPath(): string {
+  return resolveMSTeamsStorePath({ filename: DELEGATED_TOKEN_FILENAME });
+}
+
+export function loadDelegatedTokens(): MSTeamsDelegatedTokens | undefined {
+  try {
+    const content = readFileSync(resolveDelegatedTokenPath(), "utf8");
+    return JSON.parse(content) as MSTeamsDelegatedTokens;
+  } catch {
+    return undefined;
+  }
+}
+
+export function saveDelegatedTokens(tokens: MSTeamsDelegatedTokens): void {
+  const tokenPath = resolveDelegatedTokenPath();
+  const dir = dirname(tokenPath);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(tokenPath, JSON.stringify(tokens, null, 2), "utf8");
+}
+
+export async function resolveDelegatedAccessToken(params: {
+  tenantId: string;
+  clientId: string;
+  clientSecret: string;
+}): Promise<string | undefined> {
+  const tokens = loadDelegatedTokens();
+  if (!tokens) {
+    return undefined;
+  }
+
+  // Token still valid (5-min buffer already baked into expiresAt)
+  if (tokens.expiresAt > Date.now()) {
+    return tokens.accessToken;
+  }
+
+  // Attempt refresh
+  try {
+    const refreshed = await refreshMSTeamsDelegatedTokens({
+      tenantId: params.tenantId,
+      clientId: params.clientId,
+      clientSecret: params.clientSecret,
+      refreshToken: tokens.refreshToken,
+      scopes: tokens.scopes,
+    });
+    saveDelegatedTokens(refreshed);
+    return refreshed.accessToken;
+  } catch {
+    return undefined;
+  }
 }

package/src/user-agent.test.ts

@@ -0,0 +1,86 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock the runtime before importing buildUserAgent
+const mockRuntime = {
+  version: "2026.3.19",
+};
+
+vi.mock("./runtime.js", () => ({
+  getMSTeamsRuntime: vi.fn(() => mockRuntime),
+}));
+
+import { fetchGraphJson } from "./graph.js";
+import { getMSTeamsRuntime } from "./runtime.js";
+import { buildUserAgent, ensureUserAgentHeader, resetUserAgentCache } from "./user-agent.js";
+
+describe("buildUserAgent", () => {
+  beforeEach(() => {
+    resetUserAgentCache();
+    vi.mocked(getMSTeamsRuntime).mockReturnValue(mockRuntime as never);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns teams.ts[apps]/<sdk> OpenClaw/<version> format", () => {
+    const ua = buildUserAgent();
+    expect(ua).toMatch(/^teams\.ts\[apps\]\/.+ OpenClaw\/2026\.3\.19$/);
+  });
+
+  it("reflects the runtime version", () => {
+    vi.mocked(getMSTeamsRuntime).mockReturnValue({ version: "1.2.3" } as never);
+    const ua = buildUserAgent();
+    expect(ua).toMatch(/OpenClaw\/1\.2\.3$/);
+  });
+
+  it("returns OpenClaw/unknown when runtime is not initialized", () => {
+    vi.mocked(getMSTeamsRuntime).mockImplementation(() => {
+      throw new Error("MSTeams runtime not initialized");
+    });
+    const ua = buildUserAgent();
+    expect(ua).toMatch(/OpenClaw\/unknown$/);
+    // SDK version should still be present
+    expect(ua).toMatch(/^teams\.ts\[apps\]\//);
+  });
+
+  it("sends the generated User-Agent in Graph requests by default", async () => {
+    const mockFetch = vi.fn().mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ value: [] }),
+    });
+    vi.stubGlobal("fetch", mockFetch);
+
+    await fetchGraphJson({ token: "test-token", path: "/groups" });
+
+    expect(mockFetch).toHaveBeenCalledOnce();
+    const [, init] = mockFetch.mock.calls[0];
+    expect(init.headers["User-Agent"]).toMatch(/^teams\.ts\[apps\]\/.+ OpenClaw\/2026\.3\.19$/);
+    expect(init.headers).toHaveProperty("Authorization", "Bearer test-token");
+  });
+
+  it("lets caller headers override the default Graph User-Agent", async () => {
+    const mockFetch = vi.fn().mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ value: [] }),
+    });
+    vi.stubGlobal("fetch", mockFetch);
+
+    await fetchGraphJson({
+      token: "test-token",
+      path: "/groups",
+      headers: { "User-Agent": "custom-agent/1.0" },
+    });
+
+    const [, init] = mockFetch.mock.calls[0];
+    expect(init.headers["User-Agent"]).toBe("custom-agent/1.0");
+  });
+
+  it("adds the generated User-Agent to Headers instances without overwriting callers", () => {
+    const generated = ensureUserAgentHeader();
+    expect(generated.get("User-Agent")).toMatch(/^teams\.ts\[apps\]\/.+ OpenClaw\/2026\.3\.19$/);
+
+    const custom = ensureUserAgentHeader({ "User-Agent": "custom-agent/2.0" });
+    expect(custom.get("User-Agent")).toBe("custom-agent/2.0");
+  });
+});

package/src/user-agent.ts

@@ -0,0 +1,53 @@
+import { createRequire } from "node:module";
+import { getMSTeamsRuntime } from "./runtime.js";
+
+let cachedUserAgent: string | undefined;
+
+function resolveTeamsSdkVersion(): string {
+  try {
+    const require = createRequire(import.meta.url);
+    const pkg = require("@microsoft/teams.apps/package.json") as { version?: string };
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+function resolveOpenClawVersion(): string {
+  try {
+    return getMSTeamsRuntime().version;
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Build a combined User-Agent string that preserves the Teams SDK identity
+ * and appends the OpenClaw version.
+ *
+ * Format: "teams.ts[apps]/<sdk-version> OpenClaw/<openclaw-version>"
+ * Example: "teams.ts[apps]/2.0.5 OpenClaw/2026.3.22"
+ *
+ * This lets the Teams backend track SDK usage while also identifying the
+ * host application.
+ */
+/** Reset the cached User-Agent (for testing). */
+export function resetUserAgentCache(): void {
+  cachedUserAgent = undefined;
+}
+
+export function buildUserAgent(): string {
+  if (cachedUserAgent) {
+    return cachedUserAgent;
+  }
+  cachedUserAgent = `teams.ts[apps]/${resolveTeamsSdkVersion()} OpenClaw/${resolveOpenClawVersion()}`;
+  return cachedUserAgent;
+}
+
+export function ensureUserAgentHeader(headers?: HeadersInit): Headers {
+  const nextHeaders = new Headers(headers);
+  if (!nextHeaders.has("User-Agent")) {
+    nextHeaders.set("User-Agent", buildUserAgent());
+  }
+  return nextHeaders;
+}

package/src/webhook-timeouts.ts

@@ -0,0 +1,27 @@
+import type { Server } from "node:http";
+
+const MSTEAMS_WEBHOOK_INACTIVITY_TIMEOUT_MS = 30_000;
+const MSTEAMS_WEBHOOK_REQUEST_TIMEOUT_MS = 30_000;
+const MSTEAMS_WEBHOOK_HEADERS_TIMEOUT_MS = 15_000;
+
+type ApplyMSTeamsWebhookTimeoutsOpts = {
+  inactivityTimeoutMs?: number;
+  requestTimeoutMs?: number;
+  headersTimeoutMs?: number;
+};
+
+export function applyMSTeamsWebhookTimeouts(
+  httpServer: Server,
+  opts?: ApplyMSTeamsWebhookTimeoutsOpts,
+): void {
+  const inactivityTimeoutMs = opts?.inactivityTimeoutMs ?? MSTEAMS_WEBHOOK_INACTIVITY_TIMEOUT_MS;
+  const requestTimeoutMs = opts?.requestTimeoutMs ?? MSTEAMS_WEBHOOK_REQUEST_TIMEOUT_MS;
+  const headersTimeoutMs = Math.min(
+    opts?.headersTimeoutMs ?? MSTEAMS_WEBHOOK_HEADERS_TIMEOUT_MS,
+    requestTimeoutMs,
+  );
+
+  httpServer.setTimeout(inactivityTimeoutMs);
+  httpServer.requestTimeout = requestTimeoutMs;
+  httpServer.headersTimeout = headersTimeoutMs;
+}

package/src/welcome-card.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import { buildMSTeamsPresentationCard } from "./presentation.js";
+import { buildGroupWelcomeText, buildWelcomeCard } from "./welcome-card.js";
+
+describe("buildMSTeamsPresentationCard", () => {
+  it("preserves message text when rendering presentation controls", () => {
+    expect(
+      buildMSTeamsPresentationCard({
+        text: "Deploy finished",
+        presentation: {
+          blocks: [
+            {
+              type: "buttons",
+              buttons: [{ label: "Open", value: "open" }],
+            },
+          ],
+        },
+      }),
+    ).toEqual({
+      type: "AdaptiveCard",
+      version: "1.4",
+      body: [{ type: "TextBlock", text: "Deploy finished", wrap: true }],
+      actions: [{ type: "Action.Submit", title: "Open", data: { value: "open", label: "Open" } }],
+    });
+  });
+});
+
+describe("buildWelcomeCard", () => {
+  it("builds card with default prompt starters", () => {
+    const card = buildWelcomeCard();
+    expect(card.type).toBe("AdaptiveCard");
+    expect(card.version).toBe("1.5");
+
+    const body = card.body as Array<{ text: string }>;
+    expect(body[0]?.text).toContain("OpenClaw");
+
+    const actions = card.actions as Array<{ title: string; data: unknown }>;
+    expect(actions.length).toBe(3);
+    expect(actions[0]?.title).toBe("What can you do?");
+  });
+
+  it("uses custom bot name", () => {
+    const card = buildWelcomeCard({ botName: "TestBot" });
+    const body = card.body as Array<{ text: string }>;
+    expect(body[0]?.text).toContain("TestBot");
+  });
+
+  it("uses custom prompt starters", () => {
+    const card = buildWelcomeCard({
+      promptStarters: ["Do X", "Do Y"],
+    });
+    const actions = card.actions as Array<{ title: string; data: unknown }>;
+    expect(actions.length).toBe(2);
+    expect(actions[0]?.title).toBe("Do X");
+    expect(actions[1]?.title).toBe("Do Y");
+
+    // Verify imBack data
+    const data = actions[0]?.data as { msteams: { type: string; value: string } };
+    expect(data.msteams.type).toBe("imBack");
+    expect(data.msteams.value).toBe("Do X");
+  });
+
+  it("falls back to defaults when promptStarters is empty", () => {
+    const card = buildWelcomeCard({ promptStarters: [] });
+    const actions = card.actions as Array<{ title: string }>;
+    expect(actions.length).toBe(3);
+  });
+});
+
+describe("buildGroupWelcomeText", () => {
+  it("includes bot name", () => {
+    const text = buildGroupWelcomeText("MyBot");
+    expect(text).toContain("MyBot");
+    expect(text).toContain("@MyBot");
+  });
+
+  it("defaults to OpenClaw", () => {
+    const text = buildGroupWelcomeText();
+    expect(text).toContain("OpenClaw");
+  });
+});

package/src/welcome-card.ts

@@ -0,0 +1,57 @@
+/**
+ * Builds an Adaptive Card for welcoming users when the bot is added to a conversation.
+ */
+
+const DEFAULT_PROMPT_STARTERS = [
+  "What can you do?",
+  "Summarize my last meeting",
+  "Help me draft an email",
+];
+
+type WelcomeCardOptions = {
+  /** Bot display name. Falls back to "OpenClaw". */
+  botName?: string;
+  /** Custom prompt starters. Falls back to defaults. */
+  promptStarters?: string[];
+};
+
+/**
+ * Build a welcome Adaptive Card for 1:1 personal chats.
+ */
+export function buildWelcomeCard(options?: WelcomeCardOptions): Record<string, unknown> {
+  const botName = options?.botName || "OpenClaw";
+  const starters = options?.promptStarters?.length
+    ? options.promptStarters
+    : DEFAULT_PROMPT_STARTERS;
+
+  return {
+    type: "AdaptiveCard",
+    version: "1.5",
+    body: [
+      {
+        type: "TextBlock",
+        text: `Hi! I'm ${botName}.`,
+        weight: "bolder",
+        size: "medium",
+      },
+      {
+        type: "TextBlock",
+        text: "I can help you with questions, tasks, and more. Here are some things to try:",
+        wrap: true,
+      },
+    ],
+    actions: starters.map((label) => ({
+      type: "Action.Submit",
+      title: label,
+      data: { msteams: { type: "imBack", value: label } },
+    })),
+  };
+}
+
+/**
+ * Build a brief welcome message for group chats (when the bot is @mentioned).
+ */
+export function buildGroupWelcomeText(botName?: string): string {
+  const name = botName || "OpenClaw";
+  return `Hi! I'm ${name}. Mention me with @${name} to get started.`;
+}

package/test-api.ts

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

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.package-boundary.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["./*.ts", "./src/**/*.ts"],
+  "exclude": [
+    "./**/*.test.ts",
+    "./dist/**",
+    "./node_modules/**",
+    "./src/test-support/**",
+    "./src/**/*test-helpers.ts",
+    "./src/**/*test-harness.ts",
+    "./src/**/*test-support.ts"
+  ]
+}

package/CHANGELOG.md

@@ -1,107 +0,0 @@
-# Changelog
-
-## 2026.3.13
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.12
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.11
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.10
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.9
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.8-beta.1
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.8
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.7
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.3
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.2
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.1
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.2.26
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.2.25
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.2.24
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.2.22
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.1.15
-
-### Features
-
-- Bot Framework gateway monitor (Express + JWT auth) with configurable webhook path/port and `/api/messages` fallback.
-- Onboarding flow for Azure Bot credentials (config + env var detection) and DM policy setup.
-- Channel capabilities: DMs, group chats, channels, threads, media, polls, and `teams` alias.
-- DM pairing/allowlist enforcement plus group policies with per-team/channel overrides and mention gating.
-- Inbound debounce + history context for room/group chats; mention tag stripping and timestamp parsing.
-- Proactive messaging via stored conversation references (file store with TTL/size pruning).
-- Outbound text/media send with markdown chunking, 4k limit, split/inline media handling.
-- Adaptive Card polls: build cards, parse votes, and persist poll state with vote tracking.
-- Attachment processing: placeholders + HTML summaries, inline image extraction (including data: URLs).
-- Media downloads with host allowlist, auth scope fallback, and Graph hostedContents/attachments fallback.
-- Retry/backoff on transient/throttled sends with classified errors + helpful hints.

package/src/file-lock.ts

@@ -1 +0,0 @@
-export { withFileLock } from "openclaw/plugin-sdk/msteams";