@kodelyth/msteams 2026.5.39 → 2026.5.42

package/src/sso.ts

@@ -0,0 +1,300 @@
+/**
+ * Bot Framework OAuth SSO invoke handlers for Microsoft Teams.
+ *
+ * Handles two invoke activities Teams sends when the bot has presented
+ * an `oauthCard` or when the user completes an interactive sign-in:
+ *
+ * 1. `signin/tokenExchange`
+ *    The Teams client obtained an exchangeable token from the bot's
+ *    AAD app and forwards it to the bot. The bot exchanges that token
+ *    with the Bot Framework User Token service, which returns the real
+ *    delegated user token (for example, a Microsoft Graph access token
+ *    if the OAuth connection is set up for Graph).
+ *
+ * 2. `signin/verifyState`
+ *    Fallback for the magic-code flow: the user finishes sign-in in a
+ *    browser tab, receives a 6-digit code, and pastes it back into the
+ *    chat. The bot then asks the User Token service for the token
+ *    corresponding to that code.
+ *
+ * In both cases the bot must reply with an `invokeResponse` (HTTP 200)
+ * immediately or the Teams UI shows "Something went wrong". Callers of
+ * {@link handleSigninTokenExchangeInvoke} and
+ * {@link handleSigninVerifyStateInvoke} are responsible for sending
+ * that ack; these helpers encapsulate token exchange and persistence.
+ */
+
+import type { MSTeamsAccessTokenProvider } from "./attachments/types.js";
+import type { MSTeamsSsoTokenStore } from "./sso-token-store.js";
+import { buildUserAgent } from "./user-agent.js";
+
+/** Scope used to obtain a Bot Framework service token. */
+const BOT_FRAMEWORK_TOKEN_SCOPE = "https://api.botframework.com/.default";
+
+/** Bot Framework User Token service base URL. */
+const BOT_FRAMEWORK_USER_TOKEN_BASE_URL = "https://token.botframework.com";
+
+/**
+ * Response shape returned by the Bot Framework User Token service for
+ * `GetUserToken` and `ExchangeToken`.
+ *
+ * @see https://learn.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-connector-user-token-service
+ */
+type BotFrameworkUserTokenResponse = {
+  channelId?: string;
+  connectionName: string;
+  token: string;
+  expiration?: string;
+};
+
+export type MSTeamsSsoFetch = (
+  input: string,
+  init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+  },
+) => Promise<{
+  ok: boolean;
+  status: number;
+  json(): Promise<unknown>;
+  text(): Promise<string>;
+}>;
+
+export type MSTeamsSsoDeps = {
+  tokenProvider: MSTeamsAccessTokenProvider;
+  tokenStore: MSTeamsSsoTokenStore;
+  connectionName: string;
+  /** Override `fetch` for testing. */
+  fetchImpl?: MSTeamsSsoFetch;
+  /** Override the User Token service base URL (testing / sovereign clouds). */
+  userTokenBaseUrl?: string;
+};
+
+type MSTeamsSsoUser = {
+  /** Stable user identifier — AAD object ID when available. */
+  userId: string;
+  /** Bot Framework channel ID (default: "msteams"). */
+  channelId?: string;
+};
+
+type MSTeamsSsoResult =
+  | {
+      ok: true;
+      token: string;
+      expiresAt?: string;
+    }
+  | {
+      ok: false;
+      code:
+        | "missing_user"
+        | "missing_connection"
+        | "missing_token"
+        | "missing_state"
+        | "service_error"
+        | "unexpected_response";
+      message: string;
+      status?: number;
+    };
+
+type SigninTokenExchangeValue = {
+  id?: string;
+  connectionName?: string;
+  token?: string;
+};
+
+type SigninVerifyStateValue = {
+  state?: string;
+};
+
+/**
+ * Extract and validate the `signin/tokenExchange` activity value. Teams
+ * delivers `{ id, connectionName, token }`; any field may be missing on
+ * malformed invocations, so callers should check the parsed result.
+ */
+export function parseSigninTokenExchangeValue(value: unknown): SigninTokenExchangeValue | null {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const obj = value as Record<string, unknown>;
+  const id = typeof obj.id === "string" ? obj.id : undefined;
+  const connectionName = typeof obj.connectionName === "string" ? obj.connectionName : undefined;
+  const token = typeof obj.token === "string" ? obj.token : undefined;
+  return { id, connectionName, token };
+}
+
+/** Extract the `signin/verifyState` activity value `{ state }`. */
+export function parseSigninVerifyStateValue(value: unknown): SigninVerifyStateValue | null {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const obj = value as Record<string, unknown>;
+  const state = typeof obj.state === "string" ? obj.state : undefined;
+  return { state };
+}
+
+type UserTokenServiceCallParams = {
+  baseUrl: string;
+  path: string;
+  query: Record<string, string>;
+  method: "GET" | "POST";
+  body?: unknown;
+  bearerToken: string;
+  fetchImpl: MSTeamsSsoFetch;
+};
+
+async function callUserTokenService(
+  params: UserTokenServiceCallParams,
+): Promise<BotFrameworkUserTokenResponse | { error: string; status: number }> {
+  const qs = new URLSearchParams(params.query).toString();
+  const url = `${params.baseUrl.replace(/\/+$/, "")}${params.path}?${qs}`;
+  const headers: Record<string, string> = {
+    Accept: "application/json",
+    Authorization: `Bearer ${params.bearerToken}`,
+    "User-Agent": buildUserAgent(),
+  };
+  if (params.body !== undefined) {
+    headers["Content-Type"] = "application/json";
+  }
+  const response = await params.fetchImpl(url, {
+    method: params.method,
+    headers,
+    body: params.body === undefined ? undefined : JSON.stringify(params.body),
+  });
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    return { error: text || `HTTP ${response.status}`, status: response.status };
+  }
+  let parsed: unknown;
+  try {
+    parsed = await response.json();
+  } catch {
+    return { error: "invalid JSON from User Token service", status: response.status };
+  }
+  if (!parsed || typeof parsed !== "object") {
+    return { error: "empty response from User Token service", status: response.status };
+  }
+  const obj = parsed as Record<string, unknown>;
+  const token = typeof obj.token === "string" ? obj.token : undefined;
+  const connectionName = typeof obj.connectionName === "string" ? obj.connectionName : undefined;
+  const channelId = typeof obj.channelId === "string" ? obj.channelId : undefined;
+  const expiration = typeof obj.expiration === "string" ? obj.expiration : undefined;
+  if (!token || !connectionName) {
+    return { error: "User Token service response missing token/connectionName", status: 502 };
+  }
+  return { channelId, connectionName, token, expiration };
+}
+
+/**
+ * Exchange a Teams SSO token for a delegated user token via Bot
+ * Framework's User Token service, then persist the result.
+ */
+export async function handleSigninTokenExchangeInvoke(params: {
+  value: SigninTokenExchangeValue;
+  user: MSTeamsSsoUser;
+  deps: MSTeamsSsoDeps;
+}): Promise<MSTeamsSsoResult> {
+  const { value, user, deps } = params;
+  if (!user.userId) {
+    return { ok: false, code: "missing_user", message: "no user id on invoke activity" };
+  }
+  const connectionName = value.connectionName?.trim() || deps.connectionName;
+  if (!connectionName) {
+    return { ok: false, code: "missing_connection", message: "no OAuth connection name" };
+  }
+  if (!value.token) {
+    return { ok: false, code: "missing_token", message: "no exchangeable token on invoke" };
+  }
+
+  const bearer = await deps.tokenProvider.getAccessToken(BOT_FRAMEWORK_TOKEN_SCOPE);
+  const fetchImpl = deps.fetchImpl ?? (globalThis.fetch as unknown as MSTeamsSsoFetch);
+  const result = await callUserTokenService({
+    baseUrl: deps.userTokenBaseUrl ?? BOT_FRAMEWORK_USER_TOKEN_BASE_URL,
+    path: "/api/usertoken/exchange",
+    query: {
+      userId: user.userId,
+      connectionName,
+      channelId: user.channelId ?? "msteams",
+    },
+    method: "POST",
+    body: { token: value.token },
+    bearerToken: bearer,
+    fetchImpl,
+  });
+
+  if ("error" in result) {
+    return {
+      ok: false,
+      code: result.status >= 500 ? "service_error" : "unexpected_response",
+      message: result.error,
+      status: result.status,
+    };
+  }
+
+  await deps.tokenStore.save({
+    connectionName,
+    userId: user.userId,
+    token: result.token,
+    expiresAt: result.expiration,
+    updatedAt: new Date().toISOString(),
+  });
+
+  return { ok: true, token: result.token, expiresAt: result.expiration };
+}
+
+/**
+ * Finish a magic-code sign-in: look up the user token for the state
+ * code via Bot Framework's User Token service, then persist it.
+ */
+export async function handleSigninVerifyStateInvoke(params: {
+  value: SigninVerifyStateValue;
+  user: MSTeamsSsoUser;
+  deps: MSTeamsSsoDeps;
+}): Promise<MSTeamsSsoResult> {
+  const { value, user, deps } = params;
+  if (!user.userId) {
+    return { ok: false, code: "missing_user", message: "no user id on invoke activity" };
+  }
+  if (!deps.connectionName) {
+    return { ok: false, code: "missing_connection", message: "no OAuth connection name" };
+  }
+  const state = value.state?.trim();
+  if (!state) {
+    return { ok: false, code: "missing_state", message: "no state code on invoke" };
+  }
+
+  const bearer = await deps.tokenProvider.getAccessToken(BOT_FRAMEWORK_TOKEN_SCOPE);
+  const fetchImpl = deps.fetchImpl ?? (globalThis.fetch as unknown as MSTeamsSsoFetch);
+  const result = await callUserTokenService({
+    baseUrl: deps.userTokenBaseUrl ?? BOT_FRAMEWORK_USER_TOKEN_BASE_URL,
+    path: "/api/usertoken/GetToken",
+    query: {
+      userId: user.userId,
+      connectionName: deps.connectionName,
+      channelId: user.channelId ?? "msteams",
+      code: state,
+    },
+    method: "GET",
+    bearerToken: bearer,
+    fetchImpl,
+  });
+
+  if ("error" in result) {
+    return {
+      ok: false,
+      code: result.status >= 500 ? "service_error" : "unexpected_response",
+      message: result.error,
+      status: result.status,
+    };
+  }
+
+  await deps.tokenStore.save({
+    connectionName: deps.connectionName,
+    userId: user.userId,
+    token: result.token,
+    expiresAt: result.expiration,
+    updatedAt: new Date().toISOString(),
+  });
+
+  return { ok: true, token: result.token, expiresAt: result.expiration };
+}

package/src/storage.ts

@@ -0,0 +1,25 @@
+import path from "node:path";
+import { getMSTeamsRuntime } from "./runtime.js";
+
+type MSTeamsStorePathOptions = {
+  env?: NodeJS.ProcessEnv;
+  homedir?: () => string;
+  stateDir?: string;
+  storePath?: string;
+  filename: string;
+};
+
+export function resolveMSTeamsStorePath(params: MSTeamsStorePathOptions): string {
+  if (params.storePath) {
+    return params.storePath;
+  }
+  if (params.stateDir) {
+    return path.join(params.stateDir, params.filename);
+  }
+
+  const env = params.env ?? process.env;
+  const stateDir = params.homedir
+    ? getMSTeamsRuntime().state.resolveStateDir(env, params.homedir)
+    : getMSTeamsRuntime().state.resolveStateDir(env);
+  return path.join(stateDir, params.filename);
+}

package/src/store-fs.ts

@@ -0,0 +1,42 @@
+import { withFileLock as withPathLock } from "klaw/plugin-sdk/file-lock";
+import { readJsonFileWithFallback, writeJsonFileAtomically } from "klaw/plugin-sdk/json-store";
+import { pathExists } from "klaw/plugin-sdk/security-runtime";
+
+const STORE_LOCK_OPTIONS = {
+  retries: {
+    retries: 10,
+    factor: 2,
+    minTimeout: 100,
+    maxTimeout: 10_000,
+    randomize: true,
+  },
+  stale: 30_000,
+} as const;
+
+export async function readJsonFile<T>(
+  filePath: string,
+  fallback: T,
+): Promise<{ value: T; exists: boolean }> {
+  return await readJsonFileWithFallback(filePath, fallback);
+}
+
+export async function writeJsonFile(filePath: string, value: unknown): Promise<void> {
+  await writeJsonFileAtomically(filePath, value);
+}
+
+async function ensureJsonFile(filePath: string, fallback: unknown) {
+  if (!(await pathExists(filePath))) {
+    await writeJsonFile(filePath, fallback);
+  }
+}
+
+export async function withFileLock<T>(
+  filePath: string,
+  fallback: unknown,
+  fn: () => Promise<T>,
+): Promise<T> {
+  await ensureJsonFile(filePath, fallback);
+  return await withPathLock(filePath, STORE_LOCK_OPTIONS, async () => {
+    return await fn();
+  });
+}

package/src/streaming-message.test.ts

@@ -0,0 +1,323 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TeamsHttpStream } from "./streaming-message.js";
+
+async function flushStreamTimer(): Promise<void> {
+  await vi.advanceTimersByTimeAsync(1);
+}
+
+function requireMessageActivity(sent: unknown[]): Record<string, unknown> {
+  const activity = sent.find((entry) => (entry as Record<string, unknown>).type === "message") as
+    | Record<string, unknown>
+    | undefined;
+  if (!activity) {
+    throw new Error("expected final Teams message activity");
+  }
+  return activity;
+}
+
+function requireEntities(activity: Record<string, unknown>): Array<Record<string, unknown>> {
+  const entities = activity.entities;
+  if (!Array.isArray(entities)) {
+    throw new Error("expected Teams activity entities");
+  }
+  return entities as Array<Record<string, unknown>>;
+}
+
+function requireEntity(
+  activity: Record<string, unknown>,
+  predicate: (entity: Record<string, unknown>) => boolean,
+  label: string,
+): Record<string, unknown> {
+  const entity = requireEntities(activity).find(predicate);
+  if (!entity) {
+    throw new Error(`expected ${label} entity`);
+  }
+  return entity;
+}
+
+function requireSendActivity(
+  sendActivity: ReturnType<typeof vi.fn>,
+  predicate: (activity: Record<string, unknown>) => boolean,
+  label: string,
+): Record<string, unknown> {
+  const activity = sendActivity.mock.calls
+    .map(([sent]) => sent as Record<string, unknown>)
+    .find(predicate);
+  if (!activity) {
+    throw new Error(`expected ${label} sendActivity call`);
+  }
+  return activity;
+}
+
+describe("TeamsHttpStream", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("sends first chunk as typing activity with streaminfo", async () => {
+    vi.useFakeTimers();
+
+    const sent: unknown[] = [];
+    const stream = new TeamsHttpStream({
+      sendActivity: vi.fn(async (activity) => {
+        sent.push(activity);
+        return { id: "stream-1" };
+      }),
+      throttleMs: 1,
+    });
+
+    // Enough text to pass MIN_INITIAL_CHARS threshold
+    stream.update("Hello, this is a test response that is long enough.");
+    await flushStreamTimer();
+
+    expect(sent.length).toBeGreaterThanOrEqual(1);
+    const firstActivity = sent[0] as Record<string, unknown>;
+    expect(firstActivity.type).toBe("typing");
+    expect(typeof firstActivity.text).toBe("string");
+    expect(firstActivity.text as string).toContain("Hello");
+    // Should have streaminfo entity
+    const streamInfo = requireEntity(
+      firstActivity,
+      (entity) => entity.type === "streaminfo",
+      "streaminfo",
+    );
+    expect(streamInfo.streamType).toBe("streaming");
+  });
+
+  it("sends final message activity on finalize", async () => {
+    vi.useFakeTimers();
+
+    const sent: unknown[] = [];
+    const stream = new TeamsHttpStream({
+      sendActivity: vi.fn(async (activity) => {
+        sent.push(activity);
+        return { id: "stream-1" };
+      }),
+      throttleMs: 1,
+    });
+
+    stream.update("Hello, this is a complete response for finalization testing.");
+    await flushStreamTimer();
+
+    await stream.finalize();
+
+    // Find the final message activity
+    const finalActivity = requireMessageActivity(sent);
+
+    expect(finalActivity.text).toBe("Hello, this is a complete response for finalization testing.");
+    // No cursor in final
+    expect(finalActivity.text as string).not.toContain("\u258D");
+
+    // Should have AI-generated entity
+    const aiGenerated = requireEntity(
+      finalActivity,
+      (entity) =>
+        Array.isArray(entity.additionalType) &&
+        entity.additionalType.includes("AIGeneratedContent"),
+      "AI-generated content",
+    );
+    expect(aiGenerated.additionalType).toEqual(["AIGeneratedContent"]);
+
+    // Should have streaminfo with final type
+    const streamInfo = requireEntity(
+      finalActivity,
+      (entity) => entity.type === "streaminfo",
+      "streaminfo",
+    );
+    expect(streamInfo.streamType).toBe("final");
+  });
+
+  it("does not send below MIN_INITIAL_CHARS", async () => {
+    vi.useFakeTimers();
+
+    const sendActivity = vi.fn(async () => ({ id: "x" }));
+    const stream = new TeamsHttpStream({ sendActivity, throttleMs: 1 });
+
+    stream.update("Hi");
+    await flushStreamTimer();
+
+    expect(sendActivity).not.toHaveBeenCalled();
+  });
+
+  it("finalize with no content does nothing", async () => {
+    const sendActivity = vi.fn(async () => ({ id: "x" }));
+    const stream = new TeamsHttpStream({ sendActivity });
+
+    await stream.finalize();
+    expect(sendActivity).not.toHaveBeenCalled();
+  });
+
+  it("finalize sends content even if no chunks were streamed", async () => {
+    const sent: unknown[] = [];
+    const stream = new TeamsHttpStream({
+      sendActivity: vi.fn(async (activity) => {
+        sent.push(activity);
+        return { id: "msg-1" };
+      }),
+    });
+
+    // Short text — below MIN_INITIAL_CHARS, so no streaming chunk sent
+    stream.update("Short");
+    await stream.finalize();
+
+    // Should send final message even though no chunks were streamed
+    expect(sent.length).toBe(1);
+    const activity = sent[0] as Record<string, unknown>;
+    expect(activity.type).toBe("message");
+    expect(activity.text).toBe("Short");
+  });
+
+  it("sets feedbackLoopEnabled on final message", async () => {
+    vi.useFakeTimers();
+
+    const sent: unknown[] = [];
+    const stream = new TeamsHttpStream({
+      sendActivity: vi.fn(async (activity) => {
+        sent.push(activity);
+        return { id: "stream-1" };
+      }),
+      feedbackLoopEnabled: true,
+      throttleMs: 1,
+    });
+
+    stream.update("A response long enough to pass the minimum character threshold for streaming.");
+    await flushStreamTimer();
+    await stream.finalize();
+
+    const finalActivity = sent.find(
+      (a) => (a as Record<string, unknown>).type === "message",
+    ) as Record<string, unknown>;
+
+    const channelData = finalActivity.channelData as Record<string, unknown>;
+    expect(channelData.feedbackLoopEnabled).toBe(true);
+  });
+
+  it("sends informative update with streamType informative", async () => {
+    const sent: unknown[] = [];
+    const stream = new TeamsHttpStream({
+      sendActivity: vi.fn(async (activity) => {
+        sent.push(activity);
+        return { id: "stream-1" };
+      }),
+    });
+
+    await stream.sendInformativeUpdate("Thinking...");
+
+    expect(sent.length).toBe(1);
+    const activity = sent[0] as Record<string, unknown>;
+    expect(activity.type).toBe("typing");
+    expect(activity.text).toBe("Thinking...");
+    const streamInfo = requireEntity(
+      activity,
+      (entity) => entity.type === "streaminfo",
+      "streaminfo",
+    );
+    expect(streamInfo.streamType).toBe("informative");
+    expect(streamInfo.streamSequence).toBe(1);
+  });
+
+  it("informative update establishes streamId for subsequent chunks", async () => {
+    vi.useFakeTimers();
+
+    const sent: unknown[] = [];
+    const stream = new TeamsHttpStream({
+      sendActivity: vi.fn(async (activity) => {
+        sent.push(activity);
+        return { id: "stream-1" };
+      }),
+      throttleMs: 1,
+    });
+
+    await stream.sendInformativeUpdate("Working...");
+    stream.update("Hello, this is a long enough response for streaming to begin.");
+    await flushStreamTimer();
+
+    // Second activity (streaming chunk) should have the streamId from the informative update
+    expect(sent.length).toBeGreaterThanOrEqual(2);
+    const chunk = sent[1] as Record<string, unknown>;
+    const streamInfo = requireEntity(chunk, (entity) => entity.type === "streaminfo", "streaminfo");
+    expect(streamInfo.streamId).toBe("stream-1");
+  });
+
+  it("reports failure when replacing informative progress with final text fails", async () => {
+    const sendActivity = vi.fn(async (activity: Record<string, unknown>) => {
+      if (activity.type === "message") {
+        throw new Error("final send rejected");
+      }
+      return { id: "stream-1" };
+    });
+    const stream = new TeamsHttpStream({ sendActivity, throttleMs: 1 });
+
+    await stream.sendInformativeUpdate("Thinking");
+    const carried = await stream.replaceInformativeWithFinal(
+      "Final response long enough to stream before the final message send fails.",
+    );
+
+    expect(carried).toBe(false);
+    expect(stream.isFailed).toBe(true);
+    const finalSend = requireSendActivity(
+      sendActivity,
+      (activity) => activity.type === "message",
+      "final message",
+    );
+    expect(finalSend.type).toBe("message");
+    expect(finalSend.text).toBe(
+      "Final response long enough to stream before the final message send fails.",
+    );
+  });
+
+  it("hasContent is true after update", () => {
+    const stream = new TeamsHttpStream({
+      sendActivity: vi.fn(async () => ({ id: "x" })),
+    });
+
+    expect(stream.hasContent).toBe(false);
+    stream.update("some text");
+    expect(stream.hasContent).toBe(true);
+  });
+
+  it("double finalize is a no-op", async () => {
+    const sendActivity = vi.fn(async () => ({ id: "x" }));
+    const stream = new TeamsHttpStream({ sendActivity });
+
+    stream.update("A response long enough to pass the minimum character threshold.");
+    await stream.finalize();
+    const callCount = sendActivity.mock.calls.length;
+
+    await stream.finalize();
+    expect(sendActivity.mock.calls.length).toBe(callCount);
+  });
+
+  it("stops streaming before stream age timeout and finalizes with last good text", async () => {
+    vi.useFakeTimers();
+
+    const sent: unknown[] = [];
+    const sendActivity = vi.fn(async (activity) => {
+      sent.push(activity);
+      return { id: "stream-1" };
+    });
+    const stream = new TeamsHttpStream({ sendActivity, throttleMs: 1 });
+
+    stream.update("Hello, this is a long enough response for streaming to begin.");
+    await vi.advanceTimersByTimeAsync(1);
+
+    stream.update(
+      "Hello, this is a long enough response for streaming to begin. More text before timeout.",
+    );
+    await vi.advanceTimersByTimeAsync(1);
+
+    vi.setSystemTime(new Date(Date.now() + 45_001));
+    stream.update(
+      "Hello, this is a long enough response for streaming to begin. More text before timeout. Even more text after timeout.",
+    );
+    await vi.advanceTimersByTimeAsync(1);
+
+    expect(stream.isFailed).toBe(true);
+
+    const finalActivity = requireMessageActivity(sent);
+
+    expect(finalActivity.text).toBe(
+      "Hello, this is a long enough response for streaming to begin. More text before timeout.",
+    );
+  });
+});