msteams-mcp 0.2.1

package/dist/auth/crypto.js

@@ -0,0 +1,66 @@
+/**
+ * Encryption utilities for credential storage.
+ *
+ * Uses machine-specific key derivation to encrypt sensitive data at rest.
+ * This is not foolproof security, but significantly raises the bar compared
+ * to plaintext storage.
+ */
+import * as crypto from 'crypto';
+import * as os from 'os';
+/** Algorithm for encryption. */
+const ALGORITHM = 'aes-256-gcm';
+/** Salt for key derivation. */
+const SALT = 'teams-mcp-credential-salt-v1';
+/** Derives an encryption key from machine-specific values. */
+function deriveKey() {
+    // Combine hostname and username for machine-specific key
+    const machineId = `${os.hostname()}:${os.userInfo().username}`;
+    return crypto.scryptSync(machineId, SALT, 32);
+}
+/**
+ * Encrypts a string value.
+ */
+export function encrypt(plaintext) {
+    const key = deriveKey();
+    const iv = crypto.randomBytes(16);
+    const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+    let encrypted = cipher.update(plaintext, 'utf8', 'hex');
+    encrypted += cipher.final('hex');
+    const tag = cipher.getAuthTag();
+    return {
+        iv: iv.toString('hex'),
+        content: encrypted,
+        tag: tag.toString('hex'),
+        version: 1,
+    };
+}
+/**
+ * Decrypts encrypted data.
+ *
+ * @throws Error if decryption fails (wrong machine, corrupted data, etc.)
+ */
+export function decrypt(data) {
+    if (data.version !== 1) {
+        throw new Error(`Unsupported encryption version: ${data.version}`);
+    }
+    const key = deriveKey();
+    const iv = Buffer.from(data.iv, 'hex');
+    const tag = Buffer.from(data.tag, 'hex');
+    const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
+    decipher.setAuthTag(tag);
+    let decrypted = decipher.update(data.content, 'hex', 'utf8');
+    decrypted += decipher.final('utf8');
+    return decrypted;
+}
+/**
+ * Checks if data looks like encrypted format.
+ */
+export function isEncrypted(data) {
+    if (!data || typeof data !== 'object')
+        return false;
+    const obj = data;
+    return (typeof obj.iv === 'string' &&
+        typeof obj.content === 'string' &&
+        typeof obj.tag === 'string' &&
+        typeof obj.version === 'number');
+}

package/dist/auth/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Auth module exports.
+ */
+export * from './session-store.js';
+export * from './token-extractor.js';
+export * from './token-refresh.js';
+export { encrypt, decrypt, isEncrypted, type EncryptedData } from './crypto.js';

package/dist/auth/index.js

@@ -0,0 +1,7 @@
+/**
+ * Auth module exports.
+ */
+export * from './session-store.js';
+export * from './token-extractor.js';
+export * from './token-refresh.js';
+export { encrypt, decrypt, isEncrypted } from './crypto.js';

package/dist/auth/session-store.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Secure session state storage.
+ *
+ * Handles reading and writing session state with:
+ * - Encryption at rest
+ * - Restricted file permissions
+ * - Automatic migration from plaintext
+ *
+ * Session files are stored in a user-specific config directory (~/.teams-mcp-server/)
+ * to ensure consistency regardless of how the server is invoked (npx, global install, etc.).
+ */
+export declare const PROJECT_ROOT: string;
+export declare const CONFIG_DIR: string;
+export declare const USER_DATA_DIR: string;
+export declare const SESSION_STATE_PATH: string;
+export declare const TOKEN_CACHE_PATH: string;
+/** Session state as stored by Playwright. */
+export interface SessionState {
+    cookies: Array<{
+        name: string;
+        value: string;
+        domain?: string;
+        path?: string;
+        expires?: number;
+        httpOnly?: boolean;
+        secure?: boolean;
+        sameSite?: 'Strict' | 'Lax' | 'None';
+    }>;
+    origins: Array<{
+        origin: string;
+        localStorage: Array<{
+            name: string;
+            value: string;
+        }>;
+    }>;
+}
+/** Token cache structure. */
+export interface TokenCache {
+    substrateToken: string;
+    substrateTokenExpiry: number;
+    extractedAt: number;
+}
+/**
+ * Ensures the user data directory exists.
+ */
+export declare function ensureUserDataDir(): void;
+/**
+ * Checks if session state file exists.
+ */
+export declare function hasSessionState(): boolean;
+/**
+ * Reads the session state.
+ */
+export declare function readSessionState(): SessionState | null;
+/**
+ * Writes the session state securely.
+ */
+export declare function writeSessionState(state: SessionState): void;
+/**
+ * Deletes the session state file.
+ */
+export declare function clearSessionState(): void;
+/**
+ * Gets the age of the session state in hours.
+ */
+export declare function getSessionAge(): number | null;
+/**
+ * Checks if session is likely expired (>12 hours old).
+ */
+export declare function isSessionLikelyExpired(): boolean;
+/**
+ * Reads the token cache.
+ */
+export declare function readTokenCache(): TokenCache | null;
+/**
+ * Writes the token cache securely.
+ */
+export declare function writeTokenCache(cache: TokenCache): void;
+/**
+ * Clears the token cache.
+ */
+export declare function clearTokenCache(): void;
+/**
+ * Gets the Teams origin from session state.
+ * Checks multiple known Teams domains to support government clouds.
+ */
+export declare function getTeamsOrigin(state: SessionState): SessionState['origins'][number] | null;

package/dist/auth/session-store.js

@@ -0,0 +1,230 @@
+/**
+ * Secure session state storage.
+ *
+ * Handles reading and writing session state with:
+ * - Encryption at rest
+ * - Restricted file permissions
+ * - Automatic migration from plaintext
+ *
+ * Session files are stored in a user-specific config directory (~/.teams-mcp-server/)
+ * to ensure consistency regardless of how the server is invoked (npx, global install, etc.).
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { encrypt, decrypt, isEncrypted } from './crypto.js';
+import { SESSION_EXPIRY_HOURS } from '../constants.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Gets the user's home directory with fallback.
+ * os.homedir() can throw in rare edge cases (missing env vars, broken passwd).
+ */
+function getHomeDirSafe() {
+    try {
+        return os.homedir();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Gets the user-specific config directory for teams-mcp-server.
+ * - Windows: %APPDATA%\teams-mcp-server\ (e.g., C:\Users\name\AppData\Roaming\teams-mcp-server\)
+ * - macOS/Linux: ~/.teams-mcp-server/
+ * - Fallback: ./teams-mcp-server-data/ relative to package (legacy behaviour)
+ */
+function getConfigDir() {
+    const homeDir = getHomeDirSafe();
+    if (process.platform === 'win32') {
+        const appData = process.env.APPDATA || (homeDir ? path.join(homeDir, 'AppData', 'Roaming') : null);
+        if (appData) {
+            return path.join(appData, 'teams-mcp-server');
+        }
+    }
+    else if (homeDir) {
+        return path.join(homeDir, '.teams-mcp-server');
+    }
+    // Fallback to package-relative directory if home directory unavailable
+    const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+    return path.join(projectRoot, 'teams-mcp-server-data');
+}
+export const PROJECT_ROOT = path.resolve(__dirname, '../..');
+export const CONFIG_DIR = getConfigDir();
+export const USER_DATA_DIR = path.join(CONFIG_DIR, '.user-data');
+export const SESSION_STATE_PATH = path.join(CONFIG_DIR, 'session-state.json');
+export const TOKEN_CACHE_PATH = path.join(CONFIG_DIR, 'token-cache.json');
+// Legacy paths for migration
+const LEGACY_SESSION_PATH = path.join(PROJECT_ROOT, 'session-state.json');
+const LEGACY_TOKEN_CACHE_PATH = path.join(PROJECT_ROOT, 'token-cache.json');
+/** File permission mode: owner read/write only. */
+const SECURE_FILE_MODE = 0o600;
+/**
+ * Ensures the config directory exists with secure permissions.
+ */
+function ensureConfigDir() {
+    if (!fs.existsSync(CONFIG_DIR)) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    }
+}
+/**
+ * Migrates a file from legacy location to new config directory.
+ * Only migrates if legacy exists and new location doesn't.
+ */
+function migrateIfNeeded(legacyPath, newPath) {
+    if (fs.existsSync(legacyPath) && !fs.existsSync(newPath)) {
+        ensureConfigDir();
+        try {
+            fs.copyFileSync(legacyPath, newPath);
+            fs.chmodSync(newPath, SECURE_FILE_MODE);
+            // Remove legacy file after successful copy
+            fs.unlinkSync(legacyPath);
+        }
+        catch (error) {
+            // Log migration errors for debugging, but continue - will just create new session
+            console.error(`Failed to migrate ${path.basename(legacyPath)}:`, error instanceof Error ? error.message : error);
+        }
+    }
+}
+/**
+ * Ensures the user data directory exists.
+ */
+export function ensureUserDataDir() {
+    ensureConfigDir();
+    if (!fs.existsSync(USER_DATA_DIR)) {
+        fs.mkdirSync(USER_DATA_DIR, { recursive: true, mode: 0o700 });
+    }
+}
+/**
+ * Writes data securely with encryption and file permissions.
+ */
+function writeSecure(filePath, data) {
+    const json = JSON.stringify(data, null, 2);
+    const encrypted = encrypt(json);
+    fs.writeFileSync(filePath, JSON.stringify(encrypted, null, 2), {
+        mode: SECURE_FILE_MODE,
+        encoding: 'utf8',
+    });
+}
+/**
+ * Reads data securely, handling both encrypted and legacy plaintext.
+ */
+function readSecure(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const parsed = JSON.parse(content);
+        // Check if this is encrypted data
+        if (isEncrypted(parsed)) {
+            const decrypted = decrypt(parsed);
+            return JSON.parse(decrypted);
+        }
+        // Legacy plaintext - migrate to encrypted
+        writeSecure(filePath, parsed);
+        return parsed;
+    }
+    catch (error) {
+        // If decryption fails (different machine, corrupted), return null
+        console.error(`Failed to read ${filePath}:`, error instanceof Error ? error.message : error);
+        return null;
+    }
+}
+/**
+ * Checks if session state file exists.
+ */
+export function hasSessionState() {
+    migrateIfNeeded(LEGACY_SESSION_PATH, SESSION_STATE_PATH);
+    return fs.existsSync(SESSION_STATE_PATH);
+}
+/**
+ * Reads the session state.
+ */
+export function readSessionState() {
+    migrateIfNeeded(LEGACY_SESSION_PATH, SESSION_STATE_PATH);
+    return readSecure(SESSION_STATE_PATH);
+}
+/**
+ * Writes the session state securely.
+ */
+export function writeSessionState(state) {
+    ensureConfigDir();
+    writeSecure(SESSION_STATE_PATH, state);
+}
+/**
+ * Deletes the session state file.
+ */
+export function clearSessionState() {
+    if (fs.existsSync(SESSION_STATE_PATH)) {
+        fs.unlinkSync(SESSION_STATE_PATH);
+    }
+}
+/**
+ * Gets the age of the session state in hours.
+ */
+export function getSessionAge() {
+    if (!hasSessionState()) {
+        return null;
+    }
+    const stats = fs.statSync(SESSION_STATE_PATH);
+    const ageMs = Date.now() - stats.mtimeMs;
+    return ageMs / (1000 * 60 * 60);
+}
+/**
+ * Checks if session is likely expired (>12 hours old).
+ */
+export function isSessionLikelyExpired() {
+    const age = getSessionAge();
+    if (age === null)
+        return true;
+    return age > SESSION_EXPIRY_HOURS;
+}
+/**
+ * Reads the token cache.
+ */
+export function readTokenCache() {
+    migrateIfNeeded(LEGACY_TOKEN_CACHE_PATH, TOKEN_CACHE_PATH);
+    return readSecure(TOKEN_CACHE_PATH);
+}
+/**
+ * Writes the token cache securely.
+ */
+export function writeTokenCache(cache) {
+    ensureConfigDir();
+    writeSecure(TOKEN_CACHE_PATH, cache);
+}
+/**
+ * Clears the token cache.
+ */
+export function clearTokenCache() {
+    if (fs.existsSync(TOKEN_CACHE_PATH)) {
+        fs.unlinkSync(TOKEN_CACHE_PATH);
+    }
+}
+/**
+ * Known Teams origins (commercial and government clouds).
+ * Used to find the correct origin in session state.
+ */
+const TEAMS_ORIGINS = [
+    'https://teams.microsoft.com', // Commercial
+    'https://teams.microsoft.us', // GCC-High
+    'https://dod.teams.microsoft.us', // DoD
+    'https://teams.cloud.microsoft', // New Teams URL
+];
+/**
+ * Gets the Teams origin from session state.
+ * Checks multiple known Teams domains to support government clouds.
+ */
+export function getTeamsOrigin(state) {
+    if (!state.origins)
+        return null;
+    // Try known Teams origins in priority order
+    for (const knownOrigin of TEAMS_ORIGINS) {
+        const origin = state.origins.find(o => o.origin === knownOrigin);
+        if (origin)
+            return origin;
+    }
+    // Fallback: find any origin containing 'teams.microsoft'
+    return state.origins.find(o => o.origin.includes('teams.microsoft') || o.origin.includes('teams.cloud')) ?? null;
+}

package/dist/auth/token-extractor.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Token extraction from session state.
+ *
+ * Extracts various authentication tokens from Playwright's saved session state.
+ * Teams stores MSAL tokens in localStorage; we parse these to get bearer tokens
+ * for various APIs (Substrate search, chatsvc messaging, etc.).
+ */
+import { clearTokenCache, type SessionState } from './session-store.js';
+import { type UserProfile } from '../utils/parsers.js';
+/** Substrate search token (for search/people APIs). */
+export interface SubstrateTokenInfo {
+    token: string;
+    expiry: Date;
+}
+/** Teams chat API token (for chatsvc). */
+export interface TeamsTokenInfo {
+    token: string;
+    expiry: Date;
+    userMri: string;
+}
+/** Cookie-based auth for messaging APIs. */
+export interface MessageAuthInfo {
+    skypeToken: string;
+    authToken: string;
+    userMri: string;
+}
+/**
+ * Extracts the Substrate search token from session state.
+ * This token is used for search and people APIs.
+ */
+export declare function extractSubstrateToken(state?: SessionState): SubstrateTokenInfo | null;
+/**
+ * Gets a valid Substrate token, either from cache or by extracting from session.
+ */
+export declare function getValidSubstrateToken(): string | null;
+/**
+ * Checks if we have a valid Substrate token.
+ */
+export declare function hasValidSubstrateToken(): boolean;
+/**
+ * Gets Substrate token status for diagnostics.
+ */
+export declare function getSubstrateTokenStatus(): {
+    hasToken: boolean;
+    expiresAt?: string;
+    minutesRemaining?: number;
+};
+/**
+ * Extracts the Teams chat API token from session state.
+ *
+ * Teams stores multiple tokens for different services. We prefer:
+ * 1. chatsvcagg.teams.microsoft.com (primary chat API)
+ * 2. api.spaces.skype.com (fallback)
+ */
+export declare function extractTeamsToken(state?: SessionState): TeamsTokenInfo | null;
+/**
+ * Extracts the Skype Spaces API token from session state.
+ *
+ * This token is required for the calendar/meetings API (mt/part endpoints).
+ * It has scope: https://api.spaces.skype.com/Authorization.ReadWrite
+ */
+export declare function extractSkypeSpacesToken(state?: SessionState): string | null;
+/** Region configuration from Teams discovery. */
+export interface RegionConfig {
+    /** Base region (e.g., "amer", "emea", "apac") - used by chatsvc, csa APIs. */
+    region: string;
+    /** Partition number (e.g., "02", "01") - only needed for mt/part APIs. */
+    partition: string;
+    /** Full region with partition (e.g., "amer-02") - for mt/part APIs. */
+    regionPartition: string;
+    /** Whether this tenant uses partitioned mt/part URLs. */
+    hasPartition: boolean;
+    /** Full middleTier URL (e.g., "https://teams.microsoft.com/api/mt/part/amer-02"). */
+    middleTierUrl: string;
+    /** Chat service URL base (e.g., "https://teams.microsoft.com/api/chatsvc/amer"). */
+    chatServiceUrl: string;
+    /** CSA service URL base (e.g., "https://teams.microsoft.com/api/csa/amer"). */
+    csaServiceUrl: string;
+    /** Teams base URL (e.g., "https://teams.microsoft.com" or "https://teams.microsoft.us" for GCC). */
+    teamsBaseUrl: string;
+}
+/**
+ * Extracts the user's region and partition from the Teams discovery config.
+ *
+ * Teams stores a DISCOVER-REGION-GTM config in localStorage that contains
+ * region-specific URLs for all APIs. There are two formats:
+ *
+ * **Partitioned (most Enterprise tenants):**
+ * - middleTier: "https://teams.microsoft.com/api/mt/part/amer-02"
+ * - chatServiceAfd: "https://teams.microsoft.com/api/chatsvc/amer"
+ *
+ * **Non-partitioned (some tenants, e.g., UK):**
+ * - middleTier: "https://teams.microsoft.com/api/mt/emea"
+ * - chatServiceAfd: "https://teams.microsoft.com/api/chatsvc/uk"
+ *
+ * We use the full URLs directly from config rather than reconstructing them,
+ * which ensures compatibility with GCC/GCC-High tenants that may use different
+ * base URLs (e.g., teams.microsoft.us).
+ */
+export declare function extractRegionConfig(state?: SessionState): RegionConfig | null;
+/** User details from DISCOVER-USER-DETAILS. */
+export interface UserDetails {
+    /** User's MRI (e.g., "8:orgid:abc..."). */
+    mri: string;
+    /** User's region (e.g., "amer", "emea"). */
+    region: string;
+    /** User's partition (e.g., "amer01"). */
+    userPartition: string;
+    /** Tenant's partition (e.g., "amer02"). */
+    tenantPartition: string;
+    /** License details. */
+    licenses: {
+        isFreemium: boolean;
+        isTrial: boolean;
+        isTeamsEnabled: boolean;
+        isCopilot: boolean;
+        isTranscriptEnabled: boolean;
+        isFrontline: boolean;
+    };
+}
+/**
+ * Extracts user details from DISCOVER-USER-DETAILS in localStorage.
+ *
+ * This provides user-specific info including:
+ * - User's MRI
+ * - Region and partition info
+ * - License details (Copilot, transcription, etc.)
+ */
+export declare function extractUserDetails(state?: SessionState): UserDetails | null;
+/**
+ * Extracts authentication info needed for messaging API.
+ * Unlike other APIs, messaging uses cookies rather than localStorage tokens.
+ */
+export declare function extractMessageAuth(state?: SessionState): MessageAuthInfo | null;
+/**
+ * Gets messaging token status for diagnostics.
+ * The skypetoken_asm cookie is a JWT with an exp claim.
+ */
+export declare function getMessageAuthStatus(): {
+    hasToken: boolean;
+    expiresAt?: string;
+    minutesRemaining?: number;
+};
+/**
+ * Extracts the CSA token for the conversationFolders API.
+ * This searches all origins, not just teams.microsoft.com.
+ */
+export declare function extractCsaToken(state?: SessionState): string | null;
+/**
+ * Gets the current user's profile from cached JWT tokens.
+ */
+export declare function getUserProfile(state?: SessionState): UserProfile | null;
+/**
+ * Gets user's display name from session state.
+ * Searches localStorage entries first, then falls back to JWT claims.
+ */
+export declare function getUserDisplayName(state?: SessionState): string | null;
+/**
+ * Checks if tokens in session state are expired.
+ */
+export declare function areTokensExpired(state?: SessionState): boolean;
+export { clearTokenCache };
+/**
+ * Discovered configuration from localStorage.
+ * Used for debugging and understanding what config is available.
+ */
+export interface DiscoveredConfig {
+    /** All DISCOVER-* keys with their parsed values. */
+    discoveryConfigs: Record<string, unknown>;
+    /** All keys that look like configuration (not tokens). */
+    configKeys: string[];
+    /** Content of interesting config keys (settings, flags). */
+    configContents: Record<string, unknown>;
+    /** Teams base URL extracted from discovery config. */
+    teamsBaseUrl: string | null;
+    /** Substrate URL if found in any config. */
+    substrateUrl: string | null;
+    /** All unique hosts found in config URLs. */
+    uniqueHosts: string[];
+}
+/**
+ * Extracts all configuration data from localStorage for debugging.
+ * This helps discover what config is available from different tenants.
+ */
+export declare function discoverConfig(state?: SessionState): DiscoveredConfig | null;