@gakr-gakr/msteams 0.1.0

package/src/file-consent.ts

@@ -0,0 +1,223 @@
+/**
+ * FileConsentCard utilities for MS Teams large file uploads (>4MB) in personal chats.
+ *
+ * Teams requires user consent before the bot can upload large files. This module provides
+ * utilities for:
+ * - Building FileConsentCard attachments (to request upload permission)
+ * - Building FileInfoCard attachments (to confirm upload completion)
+ * - Parsing fileConsent/invoke activities
+ */
+
+import { lookup } from "node:dns/promises";
+import { isPrivateIpAddress } from "autobot/plugin-sdk/ssrf-policy";
+import { normalizeLowercaseStringOrEmpty } from "autobot/plugin-sdk/string-coerce-runtime";
+import { buildUserAgent } from "./user-agent.js";
+
+/**
+ * Allowlist of domains that are valid targets for file consent uploads.
+ * These are the Microsoft/SharePoint domains that Teams legitimately provides
+ * as upload destinations in the FileConsentCard flow.
+ */
+export const CONSENT_UPLOAD_HOST_ALLOWLIST = [
+  "sharepoint.com",
+  "sharepoint.us",
+  "sharepoint.de",
+  "sharepoint.cn",
+  "sharepoint-df.com",
+  "storage.live.com",
+  "onedrive.com",
+  "1drv.ms",
+  "graph.microsoft.com",
+  "graph.microsoft.us",
+  "graph.microsoft.de",
+  "graph.microsoft.cn",
+] as const;
+
+/**
+ * Returns true if the given IPv4 or IPv6 address is private, internal, or
+ * special-use and must never be reached via consent uploads.
+ */
+export const isPrivateOrReservedIP: (ip: string) => boolean = isPrivateIpAddress;
+
+/**
+ * Validate that a consent upload URL is safe to PUT to.
+ * Checks:
+ * 1. Protocol is HTTPS
+ * 2. Hostname matches the consent upload allowlist
+ * 3. Resolved IP is not in a private/reserved range (anti-SSRF)
+ *
+ * @throws Error if the URL fails validation
+ */
+export async function validateConsentUploadUrl(
+  url: string,
+  opts?: {
+    allowlist?: readonly string[];
+    resolveFn?: (hostname: string) => Promise<{ address: string } | { address: string }[]>;
+  },
+): Promise<void> {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error("Consent upload URL is not a valid URL");
+  }
+
+  // 1. Protocol check
+  if (parsed.protocol !== "https:") {
+    throw new Error(`Consent upload URL must use HTTPS, got ${parsed.protocol}`);
+  }
+
+  // 2. Hostname allowlist check
+  const hostname = normalizeLowercaseStringOrEmpty(parsed.hostname);
+  const allowlist = opts?.allowlist ?? CONSENT_UPLOAD_HOST_ALLOWLIST;
+  const hostAllowed = allowlist.some(
+    (entry) => hostname === entry || hostname.endsWith(`.${entry}`),
+  );
+  if (!hostAllowed) {
+    throw new Error(`Consent upload URL hostname "${hostname}" is not in the allowed domains`);
+  }
+
+  // 3. DNS resolution — reject private/reserved IPs.
+  // Check all resolved addresses to avoid SSRF bypass via mixed public/private answers.
+  const resolveFn = opts?.resolveFn ?? ((name: string) => lookup(name, { all: true }));
+  let resolved: { address: string }[];
+  try {
+    const result = await resolveFn(hostname);
+    resolved = Array.isArray(result) ? result : [result];
+  } catch {
+    throw new Error(`Failed to resolve consent upload URL hostname "${hostname}"`);
+  }
+
+  for (const entry of resolved) {
+    if (isPrivateOrReservedIP(entry.address)) {
+      throw new Error(`Consent upload URL resolves to a private/reserved IP (${entry.address})`);
+    }
+  }
+}
+
+interface FileConsentCardParams {
+  filename: string;
+  description?: string;
+  sizeInBytes: number;
+  /** Custom context data to include in the card (passed back in the invoke) */
+  context?: Record<string, unknown>;
+}
+
+interface FileInfoCardParams {
+  filename: string;
+  contentUrl: string;
+  uniqueId: string;
+  fileType: string;
+}
+
+/**
+ * Build a FileConsentCard attachment for requesting upload permission.
+ * Use this for files >= 4MB in personal (1:1) chats.
+ */
+export function buildFileConsentCard(params: FileConsentCardParams) {
+  return {
+    contentType: "application/vnd.microsoft.teams.card.file.consent",
+    name: params.filename,
+    content: {
+      description: params.description ?? `File: ${params.filename}`,
+      sizeInBytes: params.sizeInBytes,
+      acceptContext: { filename: params.filename, ...params.context },
+      declineContext: { filename: params.filename, ...params.context },
+    },
+  };
+}
+
+/**
+ * Build a FileInfoCard attachment for confirming upload completion.
+ * Send this after successfully uploading the file to the consent URL.
+ */
+export function buildFileInfoCard(params: FileInfoCardParams) {
+  return {
+    contentType: "application/vnd.microsoft.teams.card.file.info",
+    contentUrl: params.contentUrl,
+    name: params.filename,
+    content: {
+      uniqueId: params.uniqueId,
+      fileType: params.fileType,
+    },
+  };
+}
+
+interface FileConsentUploadInfo {
+  name: string;
+  uploadUrl: string;
+  contentUrl: string;
+  uniqueId: string;
+  fileType: string;
+}
+
+interface FileConsentResponse {
+  action: "accept" | "decline";
+  uploadInfo?: FileConsentUploadInfo;
+  context?: Record<string, unknown>;
+}
+
+/**
+ * Parse a fileConsent/invoke activity.
+ * Returns null if the activity is not a file consent invoke.
+ */
+export function parseFileConsentInvoke(activity: {
+  name?: string;
+  value?: unknown;
+}): FileConsentResponse | null {
+  if (activity.name !== "fileConsent/invoke") {
+    return null;
+  }
+
+  const value = activity.value as {
+    type?: string;
+    action?: string;
+    uploadInfo?: FileConsentUploadInfo;
+    context?: Record<string, unknown>;
+  };
+
+  if (value?.type !== "fileUpload") {
+    return null;
+  }
+
+  return {
+    action: value.action === "accept" ? "accept" : "decline",
+    uploadInfo: value.uploadInfo,
+    context: value.context,
+  };
+}
+
+/**
+ * Upload a file to the consent URL provided by Teams.
+ * The URL is provided in the fileConsent/invoke response after user accepts.
+ *
+ * @throws Error if the URL fails SSRF validation (non-HTTPS, disallowed host, private IP)
+ */
+export async function uploadToConsentUrl(params: {
+  url: string;
+  buffer: Buffer;
+  contentType?: string;
+  fetchFn?: typeof fetch;
+  /** Override for testing — custom allowlist and DNS resolver */
+  validationOpts?: {
+    allowlist?: readonly string[];
+    resolveFn?: (hostname: string) => Promise<{ address: string } | { address: string }[]>;
+  };
+}): Promise<void> {
+  await validateConsentUploadUrl(params.url, params.validationOpts);
+
+  const fetchFn = params.fetchFn ?? fetch;
+  const res = await fetchFn(params.url, {
+    method: "PUT",
+    headers: {
+      "User-Agent": buildUserAgent(),
+      "Content-Type": params.contentType ?? "application/octet-stream",
+      "Content-Range": `bytes 0-${params.buffer.length - 1}/${params.buffer.length}`,
+    },
+    body: new Uint8Array(params.buffer),
+  });
+
+  if (!res.ok) {
+    throw new Error(`File upload to consent URL failed: ${res.status} ${res.statusText}`);
+  }
+}

package/src/graph-chat.ts

@@ -0,0 +1,36 @@
+import { normalizeLowercaseStringOrEmpty } from "autobot/plugin-sdk/string-coerce-runtime";
+import type { DriveItemProperties } from "./graph-upload.js";
+
+export function buildTeamsFileInfoCard(file: DriveItemProperties): {
+  contentType: string;
+  contentUrl: string;
+  name: string;
+  content: {
+    uniqueId: string;
+    fileType: string;
+  };
+} {
+  // Extract unique ID from eTag (remove quotes, braces, and version suffix)
+  // Example eTag formats: "{GUID},version" or "\"{GUID},version\""
+  const rawETag = file.eTag;
+  const uniqueId =
+    rawETag
+      .replace(/^["']|["']$/g, "") // Remove outer quotes
+      .replace(/[{}]/g, "") // Remove curly braces
+      .split(",")[0] ?? rawETag; // Take the GUID part before comma
+
+  // Extract file extension from filename
+  const lastDot = file.name.lastIndexOf(".");
+  const fileType =
+    lastDot >= 0 ? normalizeLowercaseStringOrEmpty(file.name.slice(lastDot + 1)) : "";
+
+  return {
+    contentType: "application/vnd.microsoft.teams.card.file.info",
+    contentUrl: file.webDavUrl,
+    name: file.name,
+    content: {
+      uniqueId,
+      fileType,
+    },
+  };
+}

package/src/graph-group-management.ts

@@ -0,0 +1,168 @@
+import type { AutoBotConfig } from "../runtime-api.js";
+import { resolveConversationPath, resolveGraphConversationId } from "./graph-messages.js";
+import {
+  deleteGraphRequest,
+  escapeOData,
+  fetchGraphJson,
+  patchGraphJson,
+  postGraphJson,
+  resolveGraphToken,
+} from "./graph.js";
+
+// ---------------------------------------------------------------------------
+// Add Participant
+// ---------------------------------------------------------------------------
+
+type AddParticipantMSTeamsParams = {
+  cfg: AutoBotConfig;
+  to: string;
+  userId: string;
+  role?: string;
+};
+
+type AddParticipantMSTeamsResult = {
+  added: { userId: string; chatId: string };
+};
+
+type ConversationMemberRole = "member" | "owner";
+
+function normalizeConversationMemberRole(role: string | undefined): ConversationMemberRole {
+  const normalized = role?.trim().toLowerCase() ?? "";
+  if (!normalized) {
+    return "member";
+  }
+  if (normalized === "member" || normalized === "owner") {
+    return normalized;
+  }
+  throw new Error('MS Teams participant role must be "member" or "owner".');
+}
+
+/**
+ * Add a user to a chat or channel via Graph API.
+ */
+export async function addParticipantMSTeams(
+  params: AddParticipantMSTeamsParams,
+): Promise<AddParticipantMSTeamsResult> {
+  const token = await resolveGraphToken(params.cfg);
+  const conversationId = await resolveGraphConversationId(params.to);
+  const conv = resolveConversationPath(conversationId);
+
+  const body = {
+    "@odata.type": "#microsoft.graph.aadUserConversationMember",
+    roles: [normalizeConversationMemberRole(params.role)],
+    "user@odata.bind": `https://graph.microsoft.com/v1.0/users('${escapeOData(params.userId)}')`,
+  };
+
+  await postGraphJson<unknown>({
+    token,
+    path: `${conv.basePath}/members`,
+    body,
+  });
+
+  return { added: { userId: params.userId, chatId: conversationId } };
+}
+
+// ---------------------------------------------------------------------------
+// Remove Participant
+// ---------------------------------------------------------------------------
+
+type RemoveParticipantMSTeamsParams = {
+  cfg: AutoBotConfig;
+  to: string;
+  userId: string;
+};
+
+type RemoveParticipantMSTeamsResult = {
+  removed: { userId: string; chatId: string };
+};
+
+type GraphConversationMember = {
+  id?: string;
+  userId?: string;
+};
+
+type GraphConversationMemberResponse = {
+  value?: GraphConversationMember[];
+  "@odata.nextLink"?: string;
+};
+
+/**
+ * Remove a user from a chat or channel via Graph API.
+ * Lists members first to resolve the membership ID, then deletes.
+ */
+export async function removeParticipantMSTeams(
+  params: RemoveParticipantMSTeamsParams,
+): Promise<RemoveParticipantMSTeamsResult> {
+  const token = await resolveGraphToken(params.cfg);
+  const conversationId = await resolveGraphConversationId(params.to);
+  const conv = resolveConversationPath(conversationId);
+
+  // List members to find the membership ID for the target user. Graph can
+  // paginate large chats/channels, so walk `@odata.nextLink` before concluding
+  // the user is missing.
+  const MAX_PAGES = 10;
+  let nextPath: string | undefined = `${conv.basePath}/members`;
+  let page = 0;
+  let member: GraphConversationMember | undefined;
+  while (nextPath && page < MAX_PAGES && !member) {
+    const membersRes: GraphConversationMemberResponse =
+      await fetchGraphJson<GraphConversationMemberResponse>({
+        token,
+        path: nextPath,
+      });
+    member = (membersRes.value ?? []).find(
+      (candidate: GraphConversationMember) => candidate.userId === params.userId,
+    );
+    if (member) {
+      break;
+    }
+    const nextLink: string | undefined = membersRes["@odata.nextLink"];
+    nextPath = nextLink ? nextLink.replace("https://graph.microsoft.com/v1.0", "") : undefined;
+    page++;
+  }
+  if (!member?.id) {
+    throw new Error(`User ${params.userId} is not a member of this conversation`);
+  }
+
+  await deleteGraphRequest({
+    token,
+    path: `${conv.basePath}/members/${encodeURIComponent(member.id)}`,
+  });
+
+  return { removed: { userId: params.userId, chatId: conversationId } };
+}
+
+// ---------------------------------------------------------------------------
+// Rename Group
+// ---------------------------------------------------------------------------
+
+type RenameGroupMSTeamsParams = {
+  cfg: AutoBotConfig;
+  to: string;
+  name: string;
+};
+
+type RenameGroupMSTeamsResult = {
+  renamed: { chatId: string; newName: string };
+};
+
+/**
+ * Rename a chat (topic) or channel (displayName) via Graph API.
+ */
+export async function renameGroupMSTeams(
+  params: RenameGroupMSTeamsParams,
+): Promise<RenameGroupMSTeamsResult> {
+  const token = await resolveGraphToken(params.cfg);
+  const conversationId = await resolveGraphConversationId(params.to);
+  const conv = resolveConversationPath(conversationId);
+
+  const body = conv.kind === "chat" ? { topic: params.name } : { displayName: params.name };
+
+  await patchGraphJson<unknown>({
+    token,
+    path: conv.basePath,
+    body,
+  });
+
+  return { renamed: { chatId: conversationId, newName: params.name } };
+}

package/src/graph-members.ts

@@ -0,0 +1,48 @@
+import type { AutoBotConfig } from "../runtime-api.js";
+import { fetchGraphJson, resolveGraphToken } from "./graph.js";
+
+type GraphUserProfile = {
+  id?: string;
+  displayName?: string;
+  mail?: string;
+  jobTitle?: string;
+  userPrincipalName?: string;
+  officeLocation?: string;
+};
+
+type GetMemberInfoMSTeamsParams = {
+  cfg: AutoBotConfig;
+  userId: string;
+};
+
+type GetMemberInfoMSTeamsResult = {
+  user: {
+    id: string | undefined;
+    displayName: string | undefined;
+    mail: string | undefined;
+    jobTitle: string | undefined;
+    userPrincipalName: string | undefined;
+    officeLocation: string | undefined;
+  };
+};
+
+/**
+ * Fetch a user profile from Microsoft Graph by user ID.
+ */
+export async function getMemberInfoMSTeams(
+  params: GetMemberInfoMSTeamsParams,
+): Promise<GetMemberInfoMSTeamsResult> {
+  const token = await resolveGraphToken(params.cfg);
+  const path = `/users/${encodeURIComponent(params.userId)}?$select=id,displayName,mail,jobTitle,userPrincipalName,officeLocation`;
+  const user = await fetchGraphJson<GraphUserProfile>({ token, path });
+  return {
+    user: {
+      id: user.id,
+      displayName: user.displayName,
+      mail: user.mail,
+      jobTitle: user.jobTitle,
+      userPrincipalName: user.userPrincipalName,
+      officeLocation: user.officeLocation,
+    },
+  };
+}