@kodelyth/msteams 2026.5.42 → 2026.6.1

package/src/sso.ts

@@ -1,300 +0,0 @@
-/**
- * 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

@@ -1,25 +0,0 @@
-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

@@ -1,42 +0,0 @@
-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

@@ -1,323 +0,0 @@
-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.",
-    );
-  });
-});