@kodelyth/msteams 2026.5.39 → 2026.5.42

package/src/thread-parent-context.ts

@@ -0,0 +1,159 @@
+// Parent-message context injection for Teams channel thread replies.
+//
+// When an inbound message arrives as a reply inside a Teams channel thread,
+// the triggering message often makes no sense on its own (for example, a
+// one-word "yes" or "go ahead"). Per-thread session isolation (PR #62713)
+// gives each thread its own session, but the first message in a brand-new
+// thread session still has no parent context.
+//
+// This module fetches the parent message via Graph and prepends a compact
+// `Replying to @sender: …` system event to the next agent turn so the agent
+// knows what is being responded to. Fetches are cached to avoid repeated
+// Graph calls within the same active thread, and per-session dedupe ensures
+// the same parent is not re-injected on every subsequent reply in the
+// thread.
+
+import { fetchChannelMessage, stripHtmlFromTeamsMessage } from "./graph-thread.js";
+import type { GraphThreadMessage } from "./graph-thread.js";
+
+// LRU cache for parent message fetches. Keyed by `teamId:channelId:parentId`.
+// 5-minute TTL and 100-entry cap keep active-thread chatter fast without
+// holding stale data when a thread goes quiet. Eviction uses Map insertion
+// order for LRU semantics (get() re-inserts on hit).
+const PARENT_CACHE_TTL_MS = 5 * 60 * 1000;
+const PARENT_CACHE_MAX = 100;
+
+type ParentCacheEntry = {
+  message: GraphThreadMessage | undefined;
+  expiresAt: number;
+};
+
+const parentCache = new Map<string, ParentCacheEntry>();
+
+// Per-session dedupe: remembers the most recent parent id we injected for a
+// given session key. When the same thread session sees another reply against
+// the same parent, we skip re-enqueueing the identical system event. We keep
+// a small LRU so idle sessions eventually drop out.
+const INJECTED_MAX = 200;
+const injectedParents = new Map<string, string>();
+
+type ThreadParentContextFetcher = (
+  token: string,
+  groupId: string,
+  channelId: string,
+  messageId: string,
+) => Promise<GraphThreadMessage | undefined>;
+
+function touchLru<K, V>(map: Map<K, V>, key: K, value: V, max: number): void {
+  if (map.has(key)) {
+    map.delete(key);
+  } else if (map.size >= max) {
+    // Drop the oldest (first-inserted) entry.
+    const firstKey = map.keys().next().value;
+    if (firstKey !== undefined) {
+      map.delete(firstKey);
+    }
+  }
+  map.set(key, value);
+}
+
+function buildParentCacheKey(groupId: string, channelId: string, parentId: string): string {
+  return `${groupId}\u0000${channelId}\u0000${parentId}`;
+}
+
+/**
+ * Fetch a channel parent message with an LRU+TTL cache.
+ *
+ * Uses the injected `fetchParent` (defaults to `fetchChannelMessage`) so
+ * tests can swap in a stub without mocking the Graph transport.
+ */
+export async function fetchParentMessageCached(
+  token: string,
+  groupId: string,
+  channelId: string,
+  parentId: string,
+  fetchParent: ThreadParentContextFetcher = fetchChannelMessage,
+): Promise<GraphThreadMessage | undefined> {
+  const key = buildParentCacheKey(groupId, channelId, parentId);
+  const now = Date.now();
+  const cached = parentCache.get(key);
+  if (cached && cached.expiresAt > now) {
+    // Refresh LRU ordering on hit.
+    parentCache.delete(key);
+    parentCache.set(key, cached);
+    return cached.message;
+  }
+  const message = await fetchParent(token, groupId, channelId, parentId);
+  touchLru(parentCache, key, { message, expiresAt: now + PARENT_CACHE_TTL_MS }, PARENT_CACHE_MAX);
+  return message;
+}
+
+type ParentContextSummary = {
+  /** Display name of the parent message author, or "unknown". */
+  sender: string;
+  /** Stripped, single-line parent body text (or empty if unresolved). */
+  text: string;
+};
+
+const PARENT_TEXT_MAX_CHARS = 400;
+
+/**
+ * Extract a compact summary (sender + plain-text body) from a Graph parent
+ * message. Returns undefined when the parent cannot be summarized (missing
+ * or blank body).
+ */
+export function summarizeParentMessage(
+  message: GraphThreadMessage | undefined,
+): ParentContextSummary | undefined {
+  if (!message) {
+    return undefined;
+  }
+  const sender =
+    message.from?.user?.displayName ?? message.from?.application?.displayName ?? "unknown";
+  const contentType = message.body?.contentType ?? "text";
+  const raw = message.body?.content ?? "";
+  const text =
+    contentType === "html" ? stripHtmlFromTeamsMessage(raw) : raw.replace(/\s+/g, " ").trim();
+  if (!text) {
+    return undefined;
+  }
+  return {
+    sender,
+    text:
+      text.length > PARENT_TEXT_MAX_CHARS ? `${text.slice(0, PARENT_TEXT_MAX_CHARS - 1)}…` : text,
+  };
+}
+
+/**
+ * Build the single-line `Replying to @sender: body` system event text.
+ * Callers should pass this text to `enqueueSystemEvent` together with a
+ * stable contextKey derived from the parent id.
+ */
+export function formatParentContextEvent(summary: ParentContextSummary): string {
+  return `Replying to @${summary.sender}: ${summary.text}`;
+}
+
+/**
+ * Decide whether a parent context event should be enqueued for the current
+ * session. Returns `false` when we already injected the same parent for this
+ * session recently (prevents re-prepending identical context on every reply
+ * in the thread).
+ */
+export function shouldInjectParentContext(sessionKey: string, parentId: string): boolean {
+  const key = sessionKey;
+  return injectedParents.get(key) !== parentId;
+}
+
+/**
+ * Record that `parentId` was just injected for `sessionKey` so subsequent
+ * replies with the same parent can short-circuit via `shouldInjectParentContext`.
+ */
+export function markParentContextInjected(sessionKey: string, parentId: string): void {
+  touchLru(injectedParents, sessionKey, parentId, INJECTED_MAX);
+}
+
+// Exported for test isolation.
+export function resetThreadParentContextCachesForTest(): void {
+  parentCache.clear();
+  injectedParents.clear();
+}

package/src/token-response.ts

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

package/src/token.test.ts

@@ -0,0 +1,268 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { readAccessToken } from "./token-response.js";
+import { hasConfiguredMSTeamsCredentials, resolveMSTeamsCredentials } from "./token.js";
+
+vi.mock("./secret-input.js", () => ({
+  normalizeSecretInputString: (v: unknown) =>
+    typeof v === "string" && v.trim() ? v.trim() : undefined,
+  normalizeResolvedSecretInputString: (opts: { value: unknown; path: string }) =>
+    typeof opts.value === "string" && opts.value.trim() ? opts.value.trim() : undefined,
+  hasConfiguredSecretInput: (v: unknown) => typeof v === "string" && v.trim().length > 0,
+}));
+
+const ENV_KEYS = [
+  "MSTEAMS_APP_ID",
+  "MSTEAMS_APP_PASSWORD",
+  "MSTEAMS_TENANT_ID",
+  "MSTEAMS_AUTH_TYPE",
+  "MSTEAMS_CERTIFICATE_PATH",
+  "MSTEAMS_CERTIFICATE_THUMBPRINT",
+  "MSTEAMS_USE_MANAGED_IDENTITY",
+  "MSTEAMS_MANAGED_IDENTITY_CLIENT_ID",
+] as const;
+
+let savedEnv: Record<string, string | undefined> = {};
+
+function saveAndClearEnv() {
+  savedEnv = {};
+  for (const key of ENV_KEYS) {
+    savedEnv[key] = process.env[key];
+    delete process.env[key];
+  }
+}
+
+function restoreEnv() {
+  for (const key of ENV_KEYS) {
+    if (savedEnv[key] !== undefined) {
+      process.env[key] = savedEnv[key];
+    } else {
+      delete process.env[key];
+    }
+  }
+}
+
+describe("token – secret credentials", () => {
+  beforeEach(saveAndClearEnv);
+  afterEach(restoreEnv);
+
+  it("returns true when appId + appPassword + tenantId are provided in config", () => {
+    const cfg = { appId: "app-id", appPassword: "app-pw", tenantId: "tenant-id" } as any;
+    expect(hasConfiguredMSTeamsCredentials(cfg)).toBe(true);
+  });
+
+  it("returns false when appPassword is missing", () => {
+    const cfg = { appId: "app-id", tenantId: "tenant-id" } as any;
+    expect(hasConfiguredMSTeamsCredentials(cfg)).toBe(false);
+  });
+
+  it("returns false when no config is given and no env vars set", () => {
+    expect(hasConfiguredMSTeamsCredentials(undefined)).toBe(false);
+  });
+
+  it("resolves secret credentials from config", () => {
+    const cfg = { appId: "app-id", appPassword: "app-pw", tenantId: "tenant-id" } as any;
+    const result = resolveMSTeamsCredentials(cfg);
+    expect(result).toEqual({
+      type: "secret",
+      appId: "app-id",
+      appPassword: "app-pw",
+      tenantId: "tenant-id",
+    });
+  });
+
+  it("resolves secret credentials from env vars", () => {
+    process.env.MSTEAMS_APP_ID = "env-app-id";
+    process.env.MSTEAMS_APP_PASSWORD = "env-app-pw";
+    process.env.MSTEAMS_TENANT_ID = "env-tenant-id";
+    const result = resolveMSTeamsCredentials(undefined);
+    expect(result).toEqual({
+      type: "secret",
+      appId: "env-app-id",
+      appPassword: "env-app-pw",
+      tenantId: "env-tenant-id",
+    });
+  });
+
+  it("returns undefined when appPassword is missing", () => {
+    const cfg = { appId: "app-id", tenantId: "tenant-id" } as any;
+    expect(resolveMSTeamsCredentials(cfg)).toBeUndefined();
+  });
+});
+
+describe("token – federated credentials (certificate)", () => {
+  beforeEach(saveAndClearEnv);
+  afterEach(restoreEnv);
+
+  it("hasConfigured returns true when certificate path is provided", () => {
+    const cfg = {
+      appId: "app-id",
+      tenantId: "tenant-id",
+      authType: "federated",
+      certificatePath: "/cert.pem",
+    } as any;
+    expect(hasConfiguredMSTeamsCredentials(cfg)).toBe(true);
+  });
+
+  it("hasConfigured returns false when neither cert nor MI is provided", () => {
+    const cfg = { appId: "app-id", tenantId: "tenant-id", authType: "federated" } as any;
+    expect(hasConfiguredMSTeamsCredentials(cfg)).toBe(false);
+  });
+
+  it("resolves federated credentials with certificate from config", () => {
+    const cfg = {
+      appId: "app-id",
+      tenantId: "tenant-id",
+      authType: "federated",
+      certificatePath: "/cert.pem",
+      certificateThumbprint: "AABBCCDD",
+    } as any;
+    const result = resolveMSTeamsCredentials(cfg);
+    expect(result).toEqual({
+      type: "federated",
+      appId: "app-id",
+      tenantId: "tenant-id",
+      certificatePath: "/cert.pem",
+      certificateThumbprint: "AABBCCDD",
+      useManagedIdentity: undefined,
+      managedIdentityClientId: undefined,
+    });
+  });
+
+  it("resolves federated credentials from env vars", () => {
+    process.env.MSTEAMS_AUTH_TYPE = "federated";
+    process.env.MSTEAMS_APP_ID = "env-app-id";
+    process.env.MSTEAMS_TENANT_ID = "env-tenant-id";
+    process.env.MSTEAMS_CERTIFICATE_PATH = "/env/cert.pem";
+    process.env.MSTEAMS_CERTIFICATE_THUMBPRINT = "EEFF0011";
+    const result = resolveMSTeamsCredentials(undefined);
+    expect(result).toEqual({
+      type: "federated",
+      appId: "env-app-id",
+      tenantId: "env-tenant-id",
+      certificatePath: "/env/cert.pem",
+      certificateThumbprint: "EEFF0011",
+      useManagedIdentity: undefined,
+      managedIdentityClientId: undefined,
+    });
+  });
+});
+
+describe("token – federated credentials (managed identity)", () => {
+  beforeEach(saveAndClearEnv);
+  afterEach(restoreEnv);
+
+  it("resolves managed identity from config", () => {
+    const cfg = {
+      appId: "app-id",
+      tenantId: "tenant-id",
+      authType: "federated",
+      useManagedIdentity: true,
+      managedIdentityClientId: "mi-client-id",
+    } as any;
+    const result = resolveMSTeamsCredentials(cfg);
+    expect(result).toEqual({
+      type: "federated",
+      appId: "app-id",
+      tenantId: "tenant-id",
+      certificatePath: undefined,
+      certificateThumbprint: undefined,
+      useManagedIdentity: true,
+      managedIdentityClientId: "mi-client-id",
+    });
+  });
+
+  it("resolves system-assigned managed identity (no clientId)", () => {
+    const cfg = {
+      appId: "app-id",
+      tenantId: "tenant-id",
+      authType: "federated",
+      useManagedIdentity: true,
+    } as any;
+    const result = resolveMSTeamsCredentials(cfg);
+    expect(result).toEqual({
+      type: "federated",
+      appId: "app-id",
+      tenantId: "tenant-id",
+      certificatePath: undefined,
+      certificateThumbprint: undefined,
+      useManagedIdentity: true,
+      managedIdentityClientId: undefined,
+    });
+  });
+
+  it("hasConfigured returns true for managed identity via env", () => {
+    process.env.MSTEAMS_AUTH_TYPE = "federated";
+    process.env.MSTEAMS_APP_ID = "env-app-id";
+    process.env.MSTEAMS_TENANT_ID = "env-tenant-id";
+    process.env.MSTEAMS_USE_MANAGED_IDENTITY = "true";
+    expect(hasConfiguredMSTeamsCredentials(undefined)).toBe(true);
+  });
+
+  it("config useManagedIdentity=false overrides env MSTEAMS_USE_MANAGED_IDENTITY=true", () => {
+    process.env.MSTEAMS_USE_MANAGED_IDENTITY = "true";
+    const cfg = {
+      appId: "app-id",
+      tenantId: "tenant-id",
+      authType: "federated",
+      certificatePath: "/cert.pem",
+      useManagedIdentity: false,
+    } as any;
+    const result = resolveMSTeamsCredentials(cfg);
+    expect(result).toEqual({
+      type: "federated",
+      appId: "app-id",
+      tenantId: "tenant-id",
+      certificatePath: "/cert.pem",
+      certificateThumbprint: undefined,
+      useManagedIdentity: undefined,
+      managedIdentityClientId: undefined,
+    });
+  });
+});
+
+describe("token – backward compatibility", () => {
+  beforeEach(saveAndClearEnv);
+  afterEach(restoreEnv);
+
+  it("defaults to secret when authType is absent", () => {
+    const cfg = { appId: "app-id", appPassword: "pw", tenantId: "tenant-id" } as any;
+    const result = resolveMSTeamsCredentials(cfg);
+    expect(result).toEqual({
+      type: "secret",
+      appId: "app-id",
+      appPassword: "pw",
+      tenantId: "tenant-id",
+    });
+  });
+
+  it("explicit authType=secret behaves same as absent", () => {
+    const cfg = {
+      appId: "app-id",
+      appPassword: "pw",
+      tenantId: "tenant-id",
+      authType: "secret",
+    } as any;
+    const result = resolveMSTeamsCredentials(cfg);
+    expect(result).toEqual({
+      type: "secret",
+      appId: "app-id",
+      appPassword: "pw",
+      tenantId: "tenant-id",
+    });
+  });
+});
+
+describe("readAccessToken", () => {
+  it("reads string and object token forms", () => {
+    expect(readAccessToken("abc")).toBe("abc");
+    expect(readAccessToken({ accessToken: "access-token" })).toBe("access-token");
+    expect(readAccessToken({ token: "fallback-token" })).toBe("fallback-token");
+  });
+
+  it("returns null for unsupported token payloads", () => {
+    expect(readAccessToken({ accessToken: 123 })).toBeNull();
+    expect(readAccessToken({ token: false })).toBeNull();
+    expect(readAccessToken(null)).toBeNull();
+    expect(readAccessToken(undefined)).toBeNull();
+  });
+});

package/src/token.ts

@@ -0,0 +1,194 @@
+import { readFileSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { privateFileStoreSync } from "klaw/plugin-sdk/security-runtime";
+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";
+
+// ── 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) &&
+    normalizeSecretInputString(cfg?.tenantId),
+  );
+}
+
+// ── 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);
+
+  if (!appPassword) {
+    return undefined;
+  }
+
+  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();
+  privateFileStoreSync(dirname(tokenPath)).writeJson(basename(tokenPath), tokens);
+}
+
+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;
+  }
+}