@softeria/ms-365-mcp-server 0.109.0 → 0.110.0

package/README.md

@@ -467,6 +467,32 @@ npx @softeria/ms-365-mcp-server --list-accounts
 - **100% backward compatible**: existing single-account setups work unchanged.
 - The `account` parameter accepts email address (e.g. `user@outlook.com`) or MSAL `homeAccountId`.
 
+### Strict Account Pinning
+
+Headless stdio deployments can pin the local MSAL cache to one expected Microsoft account:
+
+```bash
+# Username matching is case-insensitive
+MS365_MCP_EXPECTED_USERNAME=work@company.com npx @softeria/ms-365-mcp-server --login
+
+# Or pin the exact MSAL homeAccountId shown by --list-accounts
+npx @softeria/ms-365-mcp-server --expected-home-account-id <homeAccountId> --login
+```
+
+Use `--list-accounts` to discover `homeAccountId` values. The MCP `list-accounts` tool intentionally hides account IDs, so use the CLI for exact ID pinning.
+
+Pinning is opt-in and local-MSAL only:
+
+- CLI values (`--expected-username`, `--expected-home-account-id`) take precedence over `MS365_MCP_EXPECTED_USERNAME` and `MS365_MCP_EXPECTED_HOME_ACCOUNT_ID`.
+- Supplying an empty pin value fails at startup instead of being ignored.
+- Username pins are compared case-insensitively; `homeAccountId` pins are exact.
+- If both pins are set, they must resolve to the same cached account.
+- Local stdio startup fails fast when the expected account is not in the token cache. Bootstrap by setting the pin, running `--login`, then starting the headless server.
+- Device-code and browser logins reject a missing or mismatched account before persisting the selected account or token cache.
+- Pinning collapses the effective MCP mode to single-account: the server does not advertise an `account` parameter and MCP instructions do not suggest account switching.
+- `--http`, `--obo`, and `MS365_MCP_OAUTH_TOKEN` use request-provided tokens for Graph calls, so account pins are warning-only in those modes. If HTTP auth tools are enabled, the pin still applies to those local MSAL helper flows.
+- `--logout` clears all cached accounts, including the pinned account. For surgical cleanup, prefer `--remove-account <id>`.
+
 > **For MCP multiplexers (Legate, Governor):** Multi-account mode replaces the N-process pattern. Instead of spawning one server per account, a single instance handles all accounts via the `account` parameter, reducing tool duplication from N×110 to 110.
 
 ## Tool Presets
@@ -504,6 +530,8 @@ The following options can be used when running ms-365-mcp-server directly from t
 --force-work-scopes Backwards compatibility alias for --org-mode (deprecated)
 --cloud <type>    Microsoft cloud environment: global (default) or china (21Vianet)
 --allowed-scopes <scopes> Limit exposed tools to Graph scopes covered by this allowlist
+--expected-username <username> Require local MSAL auth to use this account username
+--expected-home-account-id <id> Require local MSAL auth to use this exact homeAccountId
 ```
 
 ### Server Options
@@ -543,6 +571,8 @@ Environment variables:
 - `MS365_MCP_KEYVAULT_URL`: Azure Key Vault URL for secrets management (see Azure Key Vault section)
 - `MS365_MCP_TOKEN_CACHE_PATH`: Custom file path for MSAL token cache (see Token Storage below)
 - `MS365_MCP_SELECTED_ACCOUNT_PATH`: Custom file path for selected account metadata (see Token Storage below)
+- `MS365_MCP_EXPECTED_USERNAME`: Require local MSAL auth to use this Microsoft account username (case-insensitive; CLI flag takes precedence)
+- `MS365_MCP_EXPECTED_HOME_ACCOUNT_ID`: Require local MSAL auth to use this exact MSAL homeAccountId (CLI flag takes precedence)
 
 ## Token Storage
 

package/dist/auth-tools.js

@@ -89,7 +89,15 @@ function registerAuthTools(server, authManager) {
     }
   });
   server.tool("verify-login", "Check current Microsoft authentication status", {}, async () => {
-    const testResult = await authManager.testLogin();
+    let testResult;
+    try {
+      testResult = await authManager.testLogin();
+    } catch (error) {
+      testResult = {
+        success: false,
+        message: `Login failed: ${error.message}`
+      };
+    }
     return {
       content: [
         {
@@ -112,6 +120,7 @@ function registerAuthTools(server, authManager) {
       try {
         const accounts = await authManager.listAccounts();
         const selectedAccountId = authManager.getSelectedAccountId();
+        const pinnedMode = authManager.hasExpectedAccount();
         const result = accounts.map((account) => ({
           email: account.username || "unknown",
           name: account.name,
@@ -124,7 +133,7 @@ function registerAuthTools(server, authManager) {
               text: JSON.stringify({
                 accounts: result,
                 count: result.length,
-                tip: "Pass the 'email' value as the 'account' parameter in any tool call to target a specific account."
+                tip: pinnedMode ? "Expected account pinning is configured; account parameters are disabled." : "Pass the 'email' value as the 'account' parameter in any tool call to target a specific account."
               })
             }
           ]

package/dist/auth.js

@@ -288,7 +288,7 @@ function buildScopeDiagnostics(toolScopes, allowedScopesInput) {
   };
 }
 class AuthManager {
-  constructor(config, scopes = []) {
+  constructor(config, scopes = [], expectedAccount) {
     logger.info(`And scopes are ${scopes.join(", ")}`, scopes);
     this.config = config;
     this.scopes = scopes;
@@ -297,6 +297,10 @@ class AuthManager {
     this.tokenExpiry = null;
     this.selectedAccountId = null;
     this.useInteractiveAuth = false;
+    this.expectedUsername = this.normalizeExpectedUsername(expectedAccount?.expectedUsername);
+    this.expectedHomeAccountId = this.normalizeExpectedHomeAccountId(
+      expectedAccount?.expectedHomeAccountId
+    );
     const oauthTokenFromEnv = process.env.MS365_MCP_OAUTH_TOKEN;
     this.oauthToken = oauthTokenFromEnv ?? null;
     this.isOAuthMode = oauthTokenFromEnv != null;
@@ -305,10 +309,10 @@ class AuthManager {
    * Creates an AuthManager instance with secrets loaded from the configured provider.
    * Uses Key Vault if MS365_MCP_KEYVAULT_URL is set, otherwise environment variables.
    */
-  static async create(scopes = []) {
+  static async create(scopes = [], expectedAccount) {
     const secrets = await getSecrets();
     const config = createMsalConfig(secrets);
-    return new AuthManager(config, scopes);
+    return new AuthManager(config, scopes, expectedAccount);
   }
   async loadTokenCache() {
     try {
@@ -411,6 +415,118 @@ class AuthManager {
       logger.error(`Error saving selected account: ${error.message}`);
     }
   }
+  normalizeExpectedUsername(value) {
+    if (value === void 0) {
+      return null;
+    }
+    const trimmed = value.trim();
+    if (trimmed === "") {
+      throw new Error("Expected Microsoft account username was provided but is empty.");
+    }
+    return trimmed.toLowerCase();
+  }
+  normalizeExpectedHomeAccountId(value) {
+    if (value === void 0) {
+      return null;
+    }
+    const trimmed = value.trim();
+    if (trimmed === "") {
+      throw new Error("Expected Microsoft account homeAccountId was provided but is empty.");
+    }
+    return trimmed;
+  }
+  hasExpectedAccount() {
+    return this.expectedUsername !== null || this.expectedHomeAccountId !== null;
+  }
+  expectedAccountLabel() {
+    const parts = [];
+    if (this.expectedUsername) {
+      parts.push(`username ${this.expectedUsername}`);
+    }
+    if (this.expectedHomeAccountId) {
+      parts.push(`homeAccountId ${this.expectedHomeAccountId}`);
+    }
+    return parts.join(" and ");
+  }
+  describeAccount(account) {
+    return account?.username || account?.name || "unknown";
+  }
+  describeCachedAccounts(accounts) {
+    if (accounts.length === 0) {
+      return "none";
+    }
+    return accounts.map((account) => this.describeAccount(account)).join(", ");
+  }
+  accountMatchesExpected(account) {
+    if (!this.hasExpectedAccount() || !account) {
+      return !this.hasExpectedAccount();
+    }
+    if (this.expectedUsername && account.username?.toLowerCase() !== this.expectedUsername) {
+      return false;
+    }
+    if (this.expectedHomeAccountId && account.homeAccountId !== this.expectedHomeAccountId) {
+      return false;
+    }
+    return true;
+  }
+  buildExpectedAccountMissingError(accounts) {
+    return new Error(
+      `Expected Microsoft account '${this.expectedAccountLabel()}' not found in token cache. Cached accounts: ${this.describeCachedAccounts(accounts)}. Run --login after configuring the expected account, or use --select-account to recover.`
+    );
+  }
+  resolveExpectedAccountFromAccounts(accounts) {
+    if (!this.hasExpectedAccount()) {
+      throw new Error("No expected Microsoft account is configured.");
+    }
+    const usernameMatch = this.expectedUsername ? accounts.find((account) => account.username?.toLowerCase() === this.expectedUsername) : void 0;
+    const homeAccountIdMatch = this.expectedHomeAccountId ? accounts.find((account) => account.homeAccountId === this.expectedHomeAccountId) : void 0;
+    if (this.expectedUsername && this.expectedHomeAccountId) {
+      if (!usernameMatch || !homeAccountIdMatch) {
+        throw this.buildExpectedAccountMissingError(accounts);
+      }
+      if (usernameMatch.homeAccountId !== homeAccountIdMatch.homeAccountId) {
+        throw new Error(
+          `Expected Microsoft account pins conflict: username ${this.expectedUsername} matched ${this.describeAccount(usernameMatch)}, but homeAccountId ${this.expectedHomeAccountId} matched ${this.describeAccount(homeAccountIdMatch)}.`
+        );
+      }
+      return usernameMatch;
+    }
+    const expectedAccount = usernameMatch ?? homeAccountIdMatch;
+    if (!expectedAccount) {
+      throw this.buildExpectedAccountMissingError(accounts);
+    }
+    return expectedAccount;
+  }
+  async assertExpectedAccountAvailable() {
+    if (!this.hasExpectedAccount()) {
+      return;
+    }
+    const accounts = await this.msalApp.getTokenCache().getAllAccounts();
+    this.resolveExpectedAccountFromAccounts(accounts);
+  }
+  async rejectUnexpectedLoginAccount(account) {
+    if (!this.hasExpectedAccount()) {
+      return;
+    }
+    if (this.accountMatchesExpected(account)) {
+      return;
+    }
+    this.accessToken = null;
+    this.tokenExpiry = null;
+    if (account) {
+      try {
+        await this.msalApp.getTokenCache().removeAccount(account);
+      } catch (error) {
+        logger.warn(`Failed to remove unexpected account from cache: ${error.message}`);
+      }
+      throw new Error(
+        `Authenticated Microsoft account '${this.describeAccount(account)}' does not match expected Microsoft account '${this.expectedAccountLabel()}'. Login was not persisted.`
+      );
+    }
+    throw new Error(
+      `Microsoft login did not return an account. Expected Microsoft account '${this.expectedAccountLabel()}'. Login was not persisted.`
+    );
+  }
   async setOAuthToken(token) {
     this.oauthToken = token;
     this.isOAuthMode = true;
@@ -443,6 +559,9 @@ class AuthManager {
   }
   async getCurrentAccount() {
     const accounts = await this.msalApp.getTokenCache().getAllAccounts();
+    if (this.hasExpectedAccount()) {
+      return this.resolveExpectedAccountFromAccounts(accounts);
+    }
     if (accounts.length === 0) {
       return null;
     }
@@ -480,6 +599,7 @@ class AuthManager {
       logger.info("Device code login successful");
       this.accessToken = response?.accessToken || null;
       this.tokenExpiry = response?.expiresOn ? new Date(response.expiresOn).getTime() : null;
+      await this.rejectUnexpectedLoginAccount(response?.account);
       if (!this.selectedAccountId && response?.account) {
         this.selectedAccountId = response.account.homeAccountId;
         await this.saveSelectedAccount();
@@ -521,6 +641,7 @@ class AuthManager {
       logger.info("Interactive browser login successful");
       this.accessToken = response?.accessToken || null;
       this.tokenExpiry = response?.expiresOn ? new Date(response.expiresOn).getTime() : null;
+      await this.rejectUnexpectedLoginAccount(response?.account);
       if (!this.selectedAccountId && response?.account) {
         this.selectedAccountId = response.account.homeAccountId;
         await this.saveSelectedAccount();
@@ -625,6 +746,11 @@ class AuthManager {
   }
   async selectAccount(identifier) {
     const account = await this.resolveAccount(identifier);
+    if (this.hasExpectedAccount() && !this.accountMatchesExpected(account)) {
+      throw new Error(
+        `Account '${identifier}' does not match expected Microsoft account '${this.expectedAccountLabel()}'.`
+      );
+    }
     this.selectedAccountId = account.homeAccountId;
     await this.saveSelectedAccount();
     this.accessToken = null;
@@ -686,6 +812,9 @@ class AuthManager {
    * Used to decide whether to inject the `account` parameter into tool schemas.
    */
   async isMultiAccount() {
+    if (this.hasExpectedAccount()) {
+      return false;
+    }
     const accounts = await this.msalApp.getTokenCache().getAllAccounts();
     return accounts.length > 1;
   }
@@ -706,7 +835,18 @@ class AuthManager {
       return this.oauthToken;
     }
     let targetAccount = null;
-    if (identifier) {
+    if (this.hasExpectedAccount()) {
+      const accounts = await this.msalApp.getTokenCache().getAllAccounts();
+      targetAccount = this.resolveExpectedAccountFromAccounts(accounts);
+      if (identifier) {
+        const requestedAccount = await this.resolveAccount(identifier);
+        if (requestedAccount.homeAccountId !== targetAccount.homeAccountId) {
+          throw new Error(
+            `Account '${identifier}' does not match expected Microsoft account '${this.expectedAccountLabel()}'.`
+          );
+        }
+      }
+    } else if (identifier) {
       targetAccount = await this.resolveAccount(identifier);
     } else {
       const accounts = await this.msalApp.getTokenCache().getAllAccounts();

package/dist/cli.js

@@ -8,7 +8,13 @@ const packageJsonPath = path.join(__dirname, "..", "package.json");
 const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
 const version = packageJson.version;
 const program = new Command();
-program.name("ms-365-mcp-server").description("Microsoft 365 MCP Server").version(version).option("-v", "Enable verbose logging").option("--login", "Login to Microsoft account").option("--logout", "Log out and clear saved credentials").option("--verify-login", "Verify login without starting the server").option("--list-accounts", "List all cached accounts").option("--select-account <accountId>", "Select a specific account by ID").option("--remove-account <accountId>", "Remove a specific account by ID").option("--read-only", "Start server in read-only mode, disabling write operations").option(
+program.name("ms-365-mcp-server").description("Microsoft 365 MCP Server").version(version).option("-v", "Enable verbose logging").option("--login", "Login to Microsoft account").option("--logout", "Log out and clear saved credentials").option("--verify-login", "Verify login without starting the server").option("--list-accounts", "List all cached accounts").option("--select-account <accountId>", "Select a specific account by ID").option("--remove-account <accountId>", "Remove a specific account by ID").option(
+  "--expected-username <username>",
+  "Require local MSAL authentication to use this Microsoft account username"
+).option(
+  "--expected-home-account-id <id>",
+  "Require local MSAL authentication to use this exact MSAL homeAccountId"
+).option("--read-only", "Start server in read-only mode, disabling write operations").option(
   "--http [address]",
   'Use Streamable HTTP transport instead of stdio. Format: [host:]port (e.g., "localhost:3000", ":3000", "3000"). Default: all interfaces on port 3000'
 ).option(
@@ -85,6 +91,32 @@ function parseArgs() {
     );
     process.exit(1);
   }
+  if (options.expectedUsername === void 0 && process.env.MS365_MCP_EXPECTED_USERNAME !== void 0) {
+    options.expectedUsername = process.env.MS365_MCP_EXPECTED_USERNAME;
+  }
+  if (options.expectedHomeAccountId === void 0 && process.env.MS365_MCP_EXPECTED_HOME_ACCOUNT_ID !== void 0) {
+    options.expectedHomeAccountId = process.env.MS365_MCP_EXPECTED_HOME_ACCOUNT_ID;
+  }
+  if (options.expectedUsername !== void 0) {
+    const expectedUsername = String(options.expectedUsername).trim();
+    if (expectedUsername === "") {
+      console.error(
+        "Error: --expected-username / MS365_MCP_EXPECTED_USERNAME was provided but is empty. Provide a Microsoft account username, or omit it to allow any cached account."
+      );
+      process.exit(1);
+    }
+    options.expectedUsername = expectedUsername;
+  }
+  if (options.expectedHomeAccountId !== void 0) {
+    const expectedHomeAccountId = String(options.expectedHomeAccountId).trim();
+    if (expectedHomeAccountId === "") {
+      console.error(
+        "Error: --expected-home-account-id / MS365_MCP_EXPECTED_HOME_ACCOUNT_ID was provided but is empty. Provide an MSAL homeAccountId, or omit it to allow any cached account."
+      );
+      process.exit(1);
+    }
+    options.expectedHomeAccountId = expectedHomeAccountId;
+  }
   if (options.enabledTools) {
     try {
       new RegExp(options.enabledTools, "i");

package/dist/index.js

@@ -4,6 +4,10 @@ import { parseArgs } from "./cli.js";
 import logger from "./logger.js";
 import AuthManager, { buildAllowedScopeDiagnostics, resolveAuthScopes } from "./auth.js";
 import MicrosoftGraphServer from "./server.js";
+import {
+  getExpectedAccountInertWarning,
+  shouldAssertExpectedAccountAtStartup
+} from "./startup-pinning.js";
 import { version } from "./version.js";
 async function main() {
   try {
@@ -37,12 +41,20 @@ async function main() {
       );
       process.exit(0);
     }
-    const authManager = await AuthManager.create(effectiveScopes);
+    const authManager = await AuthManager.create(effectiveScopes, {
+      expectedUsername: args.expectedUsername,
+      expectedHomeAccountId: args.expectedHomeAccountId
+    });
     await authManager.loadTokenCache();
     if (args.authBrowser) {
       authManager.setUseInteractiveAuth(true);
       logger.info("Browser-based interactive auth enabled");
     }
+    const expectedAccountWarning = getExpectedAccountInertWarning(args, authManager);
+    if (expectedAccountWarning) {
+      logger.warn(expectedAccountWarning);
+      console.error(expectedAccountWarning);
+    }
     if (args.login) {
       if (args.authBrowser) {
         await authManager.acquireTokenInteractive();
@@ -97,6 +109,9 @@ async function main() {
       }
       process.exit(0);
     }
+    if (shouldAssertExpectedAccountAtStartup(args, authManager)) {
+      await authManager.assertExpectedAccountAvailable();
+    }
     const server = new MicrosoftGraphServer(authManager, args);
     await server.initialize(version);
     await server.start();

package/dist/startup-pinning.js

@@ -0,0 +1,40 @@
+const LOCAL_ACCOUNT_COMMANDS = [
+  "login",
+  "logout",
+  "listAccounts",
+  "selectAccount",
+  "removeAccount",
+  "verifyLogin"
+];
+function getExpectedAccountInertWarning(args, authManager) {
+  if (!authManager.hasExpectedAccount()) {
+    return null;
+  }
+  const inertModes = [];
+  if (args.http) {
+    inertModes.push("--http");
+  }
+  if (args.obo) {
+    inertModes.push("--obo");
+  }
+  if (authManager.isOAuthModeEnabled()) {
+    inertModes.push("MS365_MCP_OAUTH_TOKEN");
+  }
+  if (inertModes.length === 0) {
+    return null;
+  }
+  return `Warning: expected account pinning is configured, but ${inertModes.join(", ")} uses request-provided tokens for Graph calls. The pin only guards local MSAL auth helpers.`;
+}
+function shouldAssertExpectedAccountAtStartup(args, authManager) {
+  if (!authManager.hasExpectedAccount()) {
+    return false;
+  }
+  if (getExpectedAccountInertWarning(args, authManager)) {
+    return false;
+  }
+  return !LOCAL_ACCOUNT_COMMANDS.some((key) => Boolean(args[key]));
+}
+export {
+  getExpectedAccountInertWarning,
+  shouldAssertExpectedAccountAtStartup
+};

package/docs/deployment.md

@@ -194,6 +194,7 @@ The client automatically discovers OAuth endpoints and opens a browser for authe
 ## Security Considerations
 
 - **Stateless**: the server does not store tokens — each request carries the user's Bearer token
+- **Account pinning**: `MS365_MCP_EXPECTED_USERNAME` and `MS365_MCP_EXPECTED_HOME_ACCOUNT_ID` protect local MSAL cache flows for headless stdio deployments. In `--http`, `--obo`, or `MS365_MCP_OAUTH_TOKEN` deployments they are warning-only because Graph calls use request-provided tokens.
 - **Admin consent**: grant tenant-wide consent to avoid per-user consent prompts
 - **Managed identity**: use managed identity for Key Vault access (no secrets in environment variables)
 - **Read-only mode**: use `--read-only` to disable all write operations (send, delete, update, create)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softeria/ms-365-mcp-server",
-  "version": "0.109.0",
+  "version": "0.110.0",
   "description": " A Model Context Protocol (MCP) server for interacting with Microsoft 365 and Office services through the Graph API",
   "type": "module",
   "main": "dist/index.js",