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

package/.env.example

@@ -51,4 +51,15 @@ MS365_MCP_TENANT_ID=common
 #   - Azure CLI credentials (for local development)
 #   - Environment variables (AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID)
 #
-# See README.md for detailed Azure Key Vault setup instructions.
+# See README.md for detailed Azure Key Vault setup instructions.
+
+# -------------------------------------------------------------------
+# External Auth Cache Storage (Optional)
+# -------------------------------------------------------------------
+# Headless local-MSAL deployments can store token-cache and selected-account
+# metadata with a provider-neutral executable wrapper. The value is a real
+# executable path, not a shell command string; put any provider-specific args
+# inside the wrapper script.
+#
+# MS365_MCP_AUTH_CACHE_COMMAND=/path/to/ms365-auth-cache-store
+# MS365_MCP_AUTH_CACHE_COMMAND_TIMEOUT_MS=10000

package/README.md

@@ -571,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_AUTH_CACHE_COMMAND`: External executable wrapper for provider-neutral auth-cache storage (see Token Storage below)
+- `MS365_MCP_AUTH_CACHE_COMMAND_TIMEOUT_MS`: Per-invocation timeout for `MS365_MCP_AUTH_CACHE_COMMAND` (default: `10000`)
 - `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)
 
@@ -593,6 +595,42 @@ Parent directories are created automatically. Files are written with `0600` perm
 
 > **Hosted/sandboxed environments** (e.g. Anthropic Cowork): Set `MS365_MCP_TOKEN_CACHE_PATH` and `MS365_MCP_SELECTED_ACCOUNT_PATH` to a persistent mount so tokens survive between sessions.
 
+### External auth-cache command
+
+Headless local-MSAL deployments can replace the built-in keytar/file storage with a provider-neutral external command:
+
+```bash
+export MS365_MCP_AUTH_CACHE_COMMAND="/path/to/ms365-auth-cache-store"
+export MS365_MCP_AUTH_CACHE_COMMAND_TIMEOUT_MS=10000
+```
+
+When `MS365_MCP_AUTH_CACHE_COMMAND` is set for a local auth flow, the server uses only that command for the MSAL token cache and selected-account metadata. It does not fall back to keytar or local files. If the command path is missing, not executable on POSIX, exits non-zero, times out, or returns malformed data, auth-cache operations fail closed with a sanitized error message.
+
+The value must be a real executable wrapper path. It is not a shell command string, and there is no companion args environment variable. Put any interpreter, region, profile, or provider-specific settings inside the wrapper. Windows users should point the variable at a wrapper executable or script that can be launched directly by Node without shell parsing.
+
+The server invokes the wrapper with:
+
+```text
+$MS365_MCP_AUTH_CACHE_COMMAND load token-cache
+$MS365_MCP_AUTH_CACHE_COMMAND save token-cache
+$MS365_MCP_AUTH_CACHE_COMMAND delete token-cache
+$MS365_MCP_AUTH_CACHE_COMMAND load selected-account
+$MS365_MCP_AUTH_CACHE_COMMAND save selected-account
+$MS365_MCP_AUTH_CACHE_COMMAND delete selected-account
+```
+
+Protocol v1:
+
+- `load <key>` reads no stdin. Exit `0` with `{"found":true,"value":"<stored envelope string>"}` when present. A miss is exit `0` with `{"found":false}` or empty stdout.
+- `save <key>` receives `{"value":"<stamped envelope string>"}` on stdin and must exit `0` only after the value is durably committed. There are no fire-and-forget or coalesced saves in v1.
+- `delete <key>` reads no stdin and exits `0` whether the key existed or not.
+- `<key>` is `token-cache` or `selected-account`.
+- Any non-zero exit is a storage error. Do not use exit code `2` for cache misses.
+- Stderr is captured and truncated in sanitized errors. Stdin and stdout payloads are never logged by the server.
+- Token-cache payloads can be large; wrappers should handle at least 256 KB values.
+
+Normal stateless HTTP Graph requests do not use local auth-cache storage. In HTTP mode, command storage is skipped at startup and per request unless local auth tools are explicitly enabled or a local account command such as `--login`, `--verify-login`, `--list-accounts`, `--select-account`, or `--logout` is used.
+
 ## Azure Key Vault Integration
 
 For production deployments, you can store secrets in Azure Key Vault instead of environment variables. This is particularly useful for Azure Container Apps with managed identity.

package/dist/auth.js

@@ -1,28 +1,19 @@
 import { PublicClientApplication } from "@azure/msal-node";
 import logger from "./logger.js";
-import fs, { existsSync, readFileSync } from "fs";
+import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 import path from "path";
 import { getSecrets } from "./secrets.js";
 import { getCloudEndpoints, getDefaultClientId } from "./cloud-config.js";
-let keytar = null;
-async function getKeytar() {
-  if (keytar === void 0) {
-    return null;
-  }
-  if (keytar === null) {
-    try {
-      const mod = await import("keytar");
-      keytar = mod.default ?? mod;
-      return keytar;
-    } catch (error) {
-      logger.info("keytar not available, using file-based credential storage");
-      keytar = void 0;
-      return null;
-    }
-  }
-  return keytar;
-}
+import {
+  createTokenCacheStorage,
+  DefaultTokenCacheStorage,
+  getSelectedAccountPath,
+  getTokenCachePath,
+  pickNewest,
+  unwrapCache,
+  wrapCache
+} from "./token-cache-storage.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const endpointsData = JSON.parse(
@@ -31,48 +22,6 @@ const endpointsData = JSON.parse(
 const endpoints = {
   default: endpointsData
 };
-const SERVICE_NAME = "ms-365-mcp-server";
-const TOKEN_CACHE_ACCOUNT = "msal-token-cache";
-const SELECTED_ACCOUNT_KEY = "selected-account";
-const FALLBACK_DIR = path.dirname(fileURLToPath(import.meta.url));
-const DEFAULT_TOKEN_CACHE_PATH = path.join(FALLBACK_DIR, "..", ".token-cache.json");
-const DEFAULT_SELECTED_ACCOUNT_PATH = path.join(FALLBACK_DIR, "..", ".selected-account.json");
-function getTokenCachePath() {
-  const envPath = process.env.MS365_MCP_TOKEN_CACHE_PATH?.trim();
-  return envPath || DEFAULT_TOKEN_CACHE_PATH;
-}
-function getSelectedAccountPath() {
-  const envPath = process.env.MS365_MCP_SELECTED_ACCOUNT_PATH?.trim();
-  return envPath || DEFAULT_SELECTED_ACCOUNT_PATH;
-}
-function ensureParentDir(filePath) {
-  const dir = path.dirname(filePath);
-  fs.mkdirSync(dir, { recursive: true, mode: 448 });
-}
-function wrapCache(data) {
-  return JSON.stringify({ _cacheEnvelope: true, data, savedAt: Date.now() });
-}
-function unwrapCache(raw) {
-  try {
-    const parsed = JSON.parse(raw);
-    if (parsed._cacheEnvelope && typeof parsed.data === "string") {
-      return { data: parsed.data, savedAt: parsed.savedAt };
-    }
-  } catch {
-  }
-  return { data: raw };
-}
-function pickNewest(keytarRaw, fileRaw) {
-  if (!keytarRaw && !fileRaw) return void 0;
-  if (keytarRaw && !fileRaw) return unwrapCache(keytarRaw).data;
-  if (!keytarRaw && fileRaw) return unwrapCache(fileRaw).data;
-  const kt = unwrapCache(keytarRaw);
-  const file = unwrapCache(fileRaw);
-  if (kt.savedAt === void 0 && file.savedAt === void 0) return kt.data;
-  if (kt.savedAt !== void 0 && file.savedAt === void 0) return kt.data;
-  if (kt.savedAt === void 0 && file.savedAt !== void 0) return file.data;
-  return kt.savedAt >= file.savedAt ? kt.data : file.data;
-}
 function createMsalConfig(secrets) {
   const cloudEndpoints = getCloudEndpoints(secrets.cloudType);
   return {
@@ -124,7 +73,7 @@ function buildScopesFromEndpoints(includeWorkAccountScopes = false, enabledTools
     try {
       enabledToolsRegex = new RegExp(enabledToolsPattern, "i");
       logger.info(`Building scopes with tool filter pattern: ${enabledToolsPattern}`);
-    } catch (error) {
+    } catch {
       logger.error(
         `Invalid tool filter regex pattern: ${enabledToolsPattern}. Building scopes without filter.`
       );
@@ -288,7 +237,7 @@ function buildScopeDiagnostics(toolScopes, allowedScopesInput) {
   };
 }
 class AuthManager {
-  constructor(config, scopes = [], expectedAccount) {
+  constructor(config, scopes = [], expectedAccount, storage) {
     logger.info(`And scopes are ${scopes.join(", ")}`, scopes);
     this.config = config;
     this.scopes = scopes;
@@ -301,6 +250,7 @@ class AuthManager {
     this.expectedHomeAccountId = this.normalizeExpectedHomeAccountId(
       expectedAccount?.expectedHomeAccountId
     );
+    this.storage = storage ?? new DefaultTokenCacheStorage();
     const oauthTokenFromEnv = process.env.MS365_MCP_OAUTH_TOKEN;
     this.oauthToken = oauthTokenFromEnv ?? null;
     this.isOAuthMode = oauthTokenFromEnv != null;
@@ -309,110 +259,61 @@ 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 = [], expectedAccount) {
+  static async create(scopes = [], expectedAccount, options = {}) {
     const secrets = await getSecrets();
     const config = createMsalConfig(secrets);
-    return new AuthManager(config, scopes, expectedAccount);
+    const storage = options.storage ?? await createTokenCacheStorage({ allowCommandStorage: false, logProvider: true });
+    return new AuthManager(config, scopes, expectedAccount, storage);
   }
   async loadTokenCache() {
     try {
-      let keytarRaw;
-      try {
-        const kt = await getKeytar();
-        if (kt) {
-          keytarRaw = await kt.getPassword(SERVICE_NAME, TOKEN_CACHE_ACCOUNT) ?? void 0;
-        }
-      } catch (keytarError) {
-        logger.warn(`Keychain access failed: ${keytarError.message}`);
-      }
-      let fileRaw;
-      const cachePath = getTokenCachePath();
-      if (existsSync(cachePath)) {
-        fileRaw = readFileSync(cachePath, "utf8");
-      }
-      const cacheData = pickNewest(keytarRaw, fileRaw);
-      if (cacheData) {
-        this.msalApp.getTokenCache().deserialize(cacheData);
+      const cacheRaw = await this.storage.load("token-cache");
+      if (cacheRaw) {
+        this.msalApp.getTokenCache().deserialize(unwrapCache(cacheRaw).data);
       }
       await this.loadSelectedAccount();
     } catch (error) {
       logger.error(`Error loading token cache: ${error.message}`);
+      if (this.storage.failClosed) {
+        throw error;
+      }
     }
   }
   async loadSelectedAccount() {
     try {
-      let keytarRaw;
-      try {
-        const kt = await getKeytar();
-        if (kt) {
-          keytarRaw = await kt.getPassword(SERVICE_NAME, SELECTED_ACCOUNT_KEY) ?? void 0;
-        }
-      } catch (keytarError) {
-        logger.warn(
-          `Keychain access failed for selected account: ${keytarError.message}`
-        );
-      }
-      let fileRaw;
-      const accountPath = getSelectedAccountPath();
-      if (existsSync(accountPath)) {
-        fileRaw = readFileSync(accountPath, "utf8");
-      }
-      const selectedAccountData = pickNewest(keytarRaw, fileRaw);
-      if (selectedAccountData) {
-        const parsed = JSON.parse(selectedAccountData);
+      const selectedAccountRaw = await this.storage.load("selected-account");
+      if (selectedAccountRaw) {
+        const parsed = JSON.parse(unwrapCache(selectedAccountRaw).data);
         this.selectedAccountId = parsed.accountId;
         logger.info(`Loaded selected account: ${this.selectedAccountId}`);
       }
     } catch (error) {
       logger.error(`Error loading selected account: ${error.message}`);
+      if (this.storage.failClosed) {
+        throw error;
+      }
     }
   }
   async saveTokenCache() {
     try {
       const stamped = wrapCache(this.msalApp.getTokenCache().serialize());
-      try {
-        const kt = await getKeytar();
-        if (kt) {
-          await kt.setPassword(SERVICE_NAME, TOKEN_CACHE_ACCOUNT, stamped);
-        } else {
-          const cachePath = getTokenCachePath();
-          ensureParentDir(cachePath);
-          fs.writeFileSync(cachePath, stamped, { mode: 384 });
-        }
-      } catch (keytarError) {
-        logger.warn(
-          `Keychain save failed, falling back to file storage: ${keytarError.message}`
-        );
-        const cachePath = getTokenCachePath();
-        ensureParentDir(cachePath);
-        fs.writeFileSync(cachePath, stamped, { mode: 384 });
-      }
+      await this.storage.save("token-cache", stamped);
     } catch (error) {
       logger.error(`Error saving token cache: ${error.message}`);
+      if (this.storage.failClosed) {
+        throw error;
+      }
     }
   }
   async saveSelectedAccount() {
     try {
       const stamped = wrapCache(JSON.stringify({ accountId: this.selectedAccountId }));
-      try {
-        const kt = await getKeytar();
-        if (kt) {
-          await kt.setPassword(SERVICE_NAME, SELECTED_ACCOUNT_KEY, stamped);
-        } else {
-          const accountPath = getSelectedAccountPath();
-          ensureParentDir(accountPath);
-          fs.writeFileSync(accountPath, stamped, { mode: 384 });
-        }
-      } catch (keytarError) {
-        logger.warn(
-          `Keychain save failed for selected account, falling back to file storage: ${keytarError.message}`
-        );
-        const accountPath = getSelectedAccountPath();
-        ensureParentDir(accountPath);
-        fs.writeFileSync(accountPath, stamped, { mode: 384 });
-      }
+      await this.storage.save("selected-account", stamped);
     } catch (error) {
       logger.error(`Error saving selected account: ${error.message}`);
+      if (this.storage.failClosed) {
+        throw error;
+      }
     }
   }
   normalizeExpectedUsername(value) {
@@ -717,23 +618,8 @@ class AuthManager {
       this.accessToken = null;
       this.tokenExpiry = null;
       this.selectedAccountId = null;
-      try {
-        const kt = await getKeytar();
-        if (kt) {
-          await kt.deletePassword(SERVICE_NAME, TOKEN_CACHE_ACCOUNT);
-          await kt.deletePassword(SERVICE_NAME, SELECTED_ACCOUNT_KEY);
-        }
-      } catch (keytarError) {
-        logger.warn(`Keychain deletion failed: ${keytarError.message}`);
-      }
-      const cachePath = getTokenCachePath();
-      if (fs.existsSync(cachePath)) {
-        fs.unlinkSync(cachePath);
-      }
-      const accountPath = getSelectedAccountPath();
-      if (fs.existsSync(accountPath)) {
-        fs.unlinkSync(accountPath);
-      }
+      await this.storage.delete("token-cache");
+      await this.storage.delete("selected-account");
       return true;
     } catch (error) {
       logger.error(`Error during logout: ${error.message}`);

package/dist/cli.js

@@ -47,6 +47,9 @@ program.name("ms-365-mcp-server").description("Microsoft 365 MCP Server").versio
 ).option(
   "--obo",
   "Enable On-Behalf-Of token exchange in HTTP mode. Exchanges the incoming bearer token for a Graph API token using the OBO flow. Requires MS365_MCP_CLIENT_SECRET."
+).option(
+  "--trust-proxy-auth",
+  "In HTTP mode, skip the built-in Bearer-token check on /mcp and ignore any forwarded Authorization header. All callers share the locally cached MSAL identity (same path stdio mode uses). Use only when an upstream reverse proxy has already authenticated the caller."
 ).addOption(
   // DEPRECATED: kept only so existing deployments that set --base-url or
   // MS365_MCP_BASE_URL do not crash at startup. Use --public-url /
@@ -149,6 +152,9 @@ function parseArgs() {
   if (process.env.MS365_MCP_OBO === "true" || process.env.MS365_MCP_OBO === "1") {
     options.obo = true;
   }
+  if (process.env.MS365_MCP_TRUST_PROXY_AUTH === "true" || process.env.MS365_MCP_TRUST_PROXY_AUTH === "1") {
+    options.trustProxyAuth = true;
+  }
   if (options.cloud) {
     process.env.MS365_MCP_CLOUD_TYPE = options.cloud;
   }

package/dist/generated/client.js

@@ -381,7 +381,9 @@ const microsoft_graph_chat = z.object({
   onlineMeetingInfo: microsoft_graph_teamworkOnlineMeetingInfo.optional(),
   originalCreatedDateTime: z.string().regex(
     /^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$/
-  ).datetime({ offset: true }).nullish(),
+  ).datetime({ offset: true }).describe(
+    "Timestamp of the original creation time for the chat. The value is null if the chat never entered migration mode."
+  ).nullish(),
   tenantId: z.string().describe("The identifier of the tenant in which the chat was created. Read-only.").nullish(),
   topic: z.string().describe("(Optional) Subject or topic for the chat. Only available for group chats.").nullish(),
   viewpoint: microsoft_graph_chatViewpoint.optional(),
@@ -1480,6 +1482,7 @@ const microsoft_graph_group = z.object({
   hideFromOutlookClients: z.boolean().describe(
     "True if the group isn't displayed in Outlook clients, such as Outlook for Windows and Outlook on the web; otherwise, false. The default value is false. Requires $select to retrieve. Supported only on the Get group API (GET /groups/{ID})."
   ).nullish(),
+  infoCatalogs: z.array(z.string()).optional(),
   isArchived: z.boolean().describe(
     "When a group is associated with a team, this property determines whether the team is in read-only mode.To read this property, use the /group/{groupId}/team endpoint or the Get team API. To update this property, use the archiveTeam and unarchiveTeam APIs."
   ).nullish(),
@@ -1504,9 +1507,6 @@ const microsoft_graph_group = z.object({
   ).nullish(),
   membershipRule: z.string().describe(
     "The rule that determines members for this group if the group is a dynamic group (groupTypes contains DynamicMembership). For more information about the syntax of the membership rule, see Membership Rules syntax. Returned by default. Supports $filter (eq, ne, not, ge, le, startsWith)."
-  ).nullish(),
-  membershipRuleProcessingState: z.string().describe(
-    "Indicates whether the dynamic membership processing is on or paused. Possible values are On or Paused. Returned by default. Supports $filter (eq, ne, not, in)."
   ).nullish()
 }).passthrough().passthrough();
 const microsoft_graph_groupCollectionResponse = z.object({
@@ -2759,7 +2759,9 @@ const microsoft_graph_channel = z.lazy(
     migrationMode: microsoft_graph_migrationMode.optional(),
     originalCreatedDateTime: z.string().regex(
       /^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$/
-    ).datetime({ offset: true }).nullish(),
+    ).datetime({ offset: true }).describe(
+      "Timestamp of the original creation time for the channel. The value is null if the channel never entered migration mode."
+    ).nullish(),
     summary: microsoft_graph_channelSummary.optional(),
     tenantId: z.string().describe("The ID of the Microsoft Entra tenant.").nullish(),
     webUrl: z.string().describe(
@@ -2854,7 +2856,7 @@ const microsoft_graph_team = z.lazy(
     ).nullish(),
     allChannels: z.array(microsoft_graph_channel).describe("List of channels either hosted in or shared with the team (incoming channels).").optional(),
     channels: z.array(microsoft_graph_channel).describe("The collection of channels and messages associated with the team.").optional(),
-    group: microsoft_graph_group.describe("[Note: Simplified from 74 properties to 25 most common ones]").optional(),
+    group: microsoft_graph_group.describe("[Note: Simplified from 75 properties to 25 most common ones]").optional(),
     incomingChannels: z.array(microsoft_graph_channel).describe("List of channels shared with the team.").optional(),
     installedApps: z.array(microsoft_graph_teamsAppInstallation).describe("The apps installed in this team.").optional(),
     members: z.array(microsoft_graph_conversationMember).describe("Members and owners of the team.").optional(),
@@ -6675,6 +6677,7 @@ You can search within a folder hierarchy, a whole drive, or files shared with th
           hideFromOutlookClients: z.boolean().describe(
             "True if the group isn't displayed in Outlook clients, such as Outlook for Windows and Outlook on the web; otherwise, false. The default value is false. Requires $select to retrieve. Supported only on the Get group API (GET /groups/{ID})."
           ).nullish(),
+          infoCatalogs: z.array(z.string()).optional(),
           isArchived: z.boolean().describe(
             "When a group is associated with a team, this property determines whether the team is in read-only mode.To read this property, use the /group/{groupId}/team endpoint or the Get team API. To update this property, use the archiveTeam and unarchiveTeam APIs."
           ).nullish(),
@@ -6699,9 +6702,6 @@ You can search within a folder hierarchy, a whole drive, or files shared with th
           ).nullish(),
           membershipRule: z.string().describe(
             "The rule that determines members for this group if the group is a dynamic group (groupTypes contains DynamicMembership). For more information about the syntax of the membership rule, see Membership Rules syntax. Returned by default. Supports $filter (eq, ne, not, ge, le, startsWith)."
-          ).nullish(),
-          membershipRuleProcessingState: z.string().describe(
-            "Indicates whether the dynamic membership processing is on or paused. Possible values are On or Paused. Returned by default. Supports $filter (eq, ne, not, in)."
           ).nullish()
         }).passthrough().passthrough()
       }
@@ -6790,6 +6790,7 @@ You can create or update the following types of group: By default, this operatio
           hideFromOutlookClients: z.boolean().describe(
             "True if the group isn't displayed in Outlook clients, such as Outlook for Windows and Outlook on the web; otherwise, false. The default value is false. Requires $select to retrieve. Supported only on the Get group API (GET /groups/{ID})."
           ).nullish(),
+          infoCatalogs: z.array(z.string()).optional(),
           isArchived: z.boolean().describe(
             "When a group is associated with a team, this property determines whether the team is in read-only mode.To read this property, use the /group/{groupId}/team endpoint or the Get team API. To update this property, use the archiveTeam and unarchiveTeam APIs."
           ).nullish(),
@@ -6814,9 +6815,6 @@ You can create or update the following types of group: By default, this operatio
           ).nullish(),
           membershipRule: z.string().describe(
             "The rule that determines members for this group if the group is a dynamic group (groupTypes contains DynamicMembership). For more information about the syntax of the membership rule, see Membership Rules syntax. Returned by default. Supports $filter (eq, ne, not, ge, le, startsWith)."
-          ).nullish(),
-          membershipRuleProcessingState: z.string().describe(
-            "Indicates whether the dynamic membership processing is on or paused. Possible values are On or Paused. Returned by default. Supports $filter (eq, ne, not, in)."
           ).nullish()
         }).passthrough().passthrough()
       }

package/dist/index.js

@@ -6,8 +6,10 @@ import AuthManager, { buildAllowedScopeDiagnostics, resolveAuthScopes } from "./
 import MicrosoftGraphServer from "./server.js";
 import {
   getExpectedAccountInertWarning,
-  shouldAssertExpectedAccountAtStartup
+  shouldAssertExpectedAccountAtStartup,
+  shouldUseLocalAuthStorage
 } from "./startup-pinning.js";
+import { createTokenCacheStorage } from "./token-cache-storage.js";
 import { version } from "./version.js";
 async function main() {
   try {
@@ -41,11 +43,22 @@ async function main() {
       );
       process.exit(0);
     }
-    const authManager = await AuthManager.create(effectiveScopes, {
-      expectedUsername: args.expectedUsername,
-      expectedHomeAccountId: args.expectedHomeAccountId
+    const useLocalAuthStorage = shouldUseLocalAuthStorage(args);
+    const storage = await createTokenCacheStorage({
+      allowCommandStorage: useLocalAuthStorage,
+      logProvider: useLocalAuthStorage
     });
-    await authManager.loadTokenCache();
+    const authManager = await AuthManager.create(
+      effectiveScopes,
+      {
+        expectedUsername: args.expectedUsername,
+        expectedHomeAccountId: args.expectedHomeAccountId
+      },
+      { storage }
+    );
+    if (useLocalAuthStorage) {
+      await authManager.loadTokenCache();
+    }
     if (args.authBrowser) {
       authManager.setUseInteractiveAuth(true);
       logger.info("Browser-based interactive auth enabled");

package/dist/lib/microsoft-auth.js

@@ -17,7 +17,11 @@ function isJwtExpired(token) {
     return false;
   }
 }
-const microsoftBearerTokenAuthMiddleware = (req, res, next) => {
+const microsoftBearerTokenAuthMiddleware = (opts = {}) => (req, res, next) => {
+  if (opts.trustProxyAuth) {
+    next();
+    return;
+  }
   const authHeader = req.headers.authorization;
   if (!authHeader || !authHeader.startsWith("Bearer ")) {
     res.status(401).set(
@@ -40,6 +44,43 @@ const microsoftBearerTokenAuthMiddleware = (req, res, next) => {
   req.microsoftAuth = { accessToken };
   next();
 };
+class OAuthUpstreamError extends Error {
+  constructor(status, raw, body) {
+    const suffix = body.error_description ? ` - ${body.error_description}` : "";
+    super(`OAuth upstream error: ${body.error}${suffix}`);
+    this.name = "OAuthUpstreamError";
+    this.status = status;
+    this.body = body;
+    this.raw = raw;
+  }
+}
+function parseUpstreamOAuthError(raw) {
+  try {
+    const json = JSON.parse(raw);
+    if (json !== null && typeof json === "object" && typeof json.error === "string") {
+      return json;
+    }
+  } catch {
+  }
+  return null;
+}
+function toOAuthErrorResponse(error) {
+  if (error instanceof OAuthUpstreamError) {
+    const body = {
+      error: error.body.error
+    };
+    if (error.body.error_description) body.error_description = error.body.error_description;
+    if (error.body.suberror) body.suberror = error.body.suberror;
+    return { status: 400, body };
+  }
+  return {
+    status: 500,
+    body: {
+      error: "server_error",
+      error_description: "Internal server error during token exchange"
+    }
+  };
+}
 async function exchangeCodeForToken(code, redirectUri, clientId, clientSecret, tenantId = "common", codeVerifier, cloudType = "global") {
   const cloudEndpoints = getCloudEndpoints(cloudType);
   const params = new URLSearchParams({
@@ -62,9 +103,20 @@ async function exchangeCodeForToken(code, redirectUri, clientId, clientSecret, t
     body: params
   });
   if (!response.ok) {
-    const error = await response.text();
-    logger.error(`Failed to exchange code for token: ${error}`);
-    throw new Error(`Failed to exchange code for token: ${error}`);
+    const raw = await response.text();
+    const parsed = parseUpstreamOAuthError(raw);
+    if (parsed) {
+      logger.warn(`Token endpoint upstream OAuth error: ${parsed.error}`, {
+        status: response.status,
+        error: parsed.error,
+        suberror: parsed.suberror,
+        error_codes: parsed.error_codes,
+        correlation_id: parsed.correlation_id
+      });
+      throw new OAuthUpstreamError(response.status, raw, parsed);
+    }
+    logger.error(`Failed to exchange code for token: ${raw}`);
+    throw new Error(`Failed to exchange code for token: ${raw}`);
   }
   return response.json();
 }
@@ -86,14 +138,27 @@ async function refreshAccessToken(refreshToken, clientId, clientSecret, tenantId
     body: params
   });
   if (!response.ok) {
-    const error = await response.text();
-    logger.error(`Failed to refresh token: ${error}`);
-    throw new Error(`Failed to refresh token: ${error}`);
+    const raw = await response.text();
+    const parsed = parseUpstreamOAuthError(raw);
+    if (parsed) {
+      logger.warn(`Token endpoint upstream OAuth error: ${parsed.error}`, {
+        status: response.status,
+        error: parsed.error,
+        suberror: parsed.suberror,
+        error_codes: parsed.error_codes,
+        correlation_id: parsed.correlation_id
+      });
+      throw new OAuthUpstreamError(response.status, raw, parsed);
+    }
+    logger.error(`Failed to refresh token: ${raw}`);
+    throw new Error(`Failed to refresh token: ${raw}`);
   }
   return response.json();
 }
 export {
+  OAuthUpstreamError,
   exchangeCodeForToken,
   microsoftBearerTokenAuthMiddleware,
-  refreshAccessToken
+  refreshAccessToken,
+  toOAuthErrorResponse
 };

package/dist/server.js

@@ -17,7 +17,9 @@ import { MicrosoftOAuthProvider } from "./oauth-provider.js";
 import {
   exchangeCodeForToken,
   microsoftBearerTokenAuthMiddleware,
-  refreshAccessToken
+  OAuthUpstreamError,
+  refreshAccessToken,
+  toOAuthErrorResponse
 } from "./lib/microsoft-auth.js";
 import { isAllowedRedirectUri, parseAllowlist } from "./lib/redirect-uri-validation.js";
 import { getSecrets } from "./secrets.js";
@@ -123,6 +125,11 @@ class MicrosoftGraphServer {
           "--obo requires MS365_MCP_CLIENT_SECRET to be set (confidential client required for On-Behalf-Of flow)."
         );
       }
+      if (this.options.trustProxyAuth) {
+        throw new Error(
+          "--obo cannot be combined with --trust-proxy-auth: the proxy-auth pass-through skips the incoming bearer token that OBO would exchange."
+        );
+      }
       this.oboClient = new OboClient(this.secrets);
       logger.info("On-Behalf-Of (OBO) flow enabled");
     }
@@ -399,11 +406,18 @@ class MicrosoftGraphServer {
             });
           }
         } catch (error) {
-          logger.error("Token endpoint error:", error);
-          res.status(500).json({
-            error: "server_error",
-            error_description: "Internal server error during token exchange"
-          });
+          if (error instanceof OAuthUpstreamError) {
+            logger.warn("Token endpoint: upstream OAuth error surfaced to client", {
+              upstream_status: error.status,
+              error: error.body.error,
+              suberror: error.body.suberror,
+              error_codes: error.body.error_codes
+            });
+          } else {
+            logger.error("Token endpoint error:", error);
+          }
+          const { status, body } = toOAuthErrorResponse(error);
+          res.status(status).json(body);
         }
       });
       app.use(
@@ -412,9 +426,12 @@ class MicrosoftGraphServer {
           issuerUrl: new URL(publicBase ?? `http://localhost:${port}`)
         })
       );
+      const mcpAuth = microsoftBearerTokenAuthMiddleware({
+        trustProxyAuth: this.options.trustProxyAuth
+      });
       app.get(
         "/mcp",
-        microsoftBearerTokenAuthMiddleware,
+        mcpAuth,
         async (req, res) => {
           const handler = async () => {
             const server = this.createMcpServer();
@@ -456,7 +473,7 @@ class MicrosoftGraphServer {
       );
       app.post(
         "/mcp",
-        microsoftBearerTokenAuthMiddleware,
+        mcpAuth,
         async (req, res) => {
           const handler = async () => {
             const server = this.createMcpServer();

package/dist/startup-pinning.js

@@ -34,7 +34,17 @@ function shouldAssertExpectedAccountAtStartup(args, authManager) {
   }
   return !LOCAL_ACCOUNT_COMMANDS.some((key) => Boolean(args[key]));
 }
+function shouldUseLocalAuthStorage(args) {
+  if (!args.http) {
+    return true;
+  }
+  if (args.enableAuthTools) {
+    return true;
+  }
+  return LOCAL_ACCOUNT_COMMANDS.some((key) => Boolean(args[key]));
+}
 export {
   getExpectedAccountInertWarning,
-  shouldAssertExpectedAccountAtStartup
+  shouldAssertExpectedAccountAtStartup,
+  shouldUseLocalAuthStorage
 };

package/dist/token-cache-storage.js

@@ -0,0 +1,336 @@
+import { spawn } from "node:child_process";
+import fs, { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import logger from "./logger.js";
+const SERVICE_NAME = "ms-365-mcp-server";
+const TOKEN_CACHE_ACCOUNT = "msal-token-cache";
+const SELECTED_ACCOUNT_KEY = "selected-account";
+const AUTH_CACHE_COMMAND_ENV = "MS365_MCP_AUTH_CACHE_COMMAND";
+const AUTH_CACHE_COMMAND_TIMEOUT_ENV = "MS365_MCP_AUTH_CACHE_COMMAND_TIMEOUT_MS";
+const DEFAULT_AUTH_CACHE_COMMAND_TIMEOUT_MS = 1e4;
+const STDERR_LIMIT = 2048;
+const COMMAND_KILL_GRACE_MS = 1e3;
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const FALLBACK_DIR = __dirname;
+const DEFAULT_TOKEN_CACHE_PATH = path.join(FALLBACK_DIR, "..", ".token-cache.json");
+const DEFAULT_SELECTED_ACCOUNT_PATH = path.join(FALLBACK_DIR, "..", ".selected-account.json");
+let keytar = null;
+async function getKeytar() {
+  if (keytar === void 0) {
+    return null;
+  }
+  if (keytar === null) {
+    try {
+      const mod = await import("keytar");
+      keytar = mod.default ?? mod;
+      return keytar;
+    } catch {
+      logger.info("keytar not available, using file-based credential storage");
+      keytar = void 0;
+      return null;
+    }
+  }
+  return keytar;
+}
+function wrapCache(data) {
+  return JSON.stringify({ _cacheEnvelope: true, data, savedAt: Date.now() });
+}
+function unwrapCache(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed._cacheEnvelope && typeof parsed.data === "string") {
+      return { data: parsed.data, savedAt: parsed.savedAt };
+    }
+  } catch {
+  }
+  return { data: raw };
+}
+function pickNewest(keytarRaw, fileRaw) {
+  const newest = pickNewestRaw(keytarRaw, fileRaw);
+  return newest ? unwrapCache(newest).data : void 0;
+}
+function pickNewestRaw(keytarRaw, fileRaw) {
+  if (!keytarRaw && !fileRaw) return void 0;
+  if (keytarRaw && !fileRaw) return keytarRaw;
+  if (!keytarRaw && fileRaw) return fileRaw;
+  const kt = unwrapCache(keytarRaw);
+  const file = unwrapCache(fileRaw);
+  if (kt.savedAt === void 0 && file.savedAt === void 0) return keytarRaw;
+  if (kt.savedAt !== void 0 && file.savedAt === void 0) return keytarRaw;
+  if (kt.savedAt === void 0 && file.savedAt !== void 0) return fileRaw;
+  return kt.savedAt >= file.savedAt ? keytarRaw : fileRaw;
+}
+function getTokenCachePath() {
+  const envPath = process.env.MS365_MCP_TOKEN_CACHE_PATH?.trim();
+  return envPath || DEFAULT_TOKEN_CACHE_PATH;
+}
+function getSelectedAccountPath() {
+  const envPath = process.env.MS365_MCP_SELECTED_ACCOUNT_PATH?.trim();
+  return envPath || DEFAULT_SELECTED_ACCOUNT_PATH;
+}
+function storageAccountForKey(key) {
+  assertValidKey(key);
+  return key === "token-cache" ? TOKEN_CACHE_ACCOUNT : SELECTED_ACCOUNT_KEY;
+}
+function filePathForKey(key) {
+  assertValidKey(key);
+  return key === "token-cache" ? getTokenCachePath() : getSelectedAccountPath();
+}
+function assertValidKey(key) {
+  if (key !== "token-cache" && key !== "selected-account") {
+    throw new Error(`Unknown auth cache storage key: ${String(key)}`);
+  }
+}
+function ensureParentDir(filePath) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true, mode: 448 });
+}
+function writeFileAtomically(filePath, value) {
+  ensureParentDir(filePath);
+  const tempPath = path.join(
+    path.dirname(filePath),
+    `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`
+  );
+  fs.writeFileSync(tempPath, value, { mode: 384 });
+  fs.renameSync(tempPath, filePath);
+}
+class DefaultTokenCacheStorage {
+  constructor() {
+    this.description = "default (keytar+file)";
+    this.failClosed = false;
+  }
+  async load(key) {
+    assertValidKey(key);
+    let keytarRaw;
+    try {
+      const kt = await getKeytar();
+      if (kt) {
+        keytarRaw = await kt.getPassword(SERVICE_NAME, storageAccountForKey(key)) ?? void 0;
+      }
+    } catch (error) {
+      logger.warn(`Keychain access failed for ${key}: ${error.message}`);
+    }
+    let fileRaw;
+    const cachePath = filePathForKey(key);
+    if (existsSync(cachePath)) {
+      fileRaw = readFileSync(cachePath, "utf8");
+    }
+    return pickNewestRaw(keytarRaw, fileRaw);
+  }
+  async save(key, value) {
+    assertValidKey(key);
+    try {
+      const kt = await getKeytar();
+      if (kt) {
+        await kt.setPassword(SERVICE_NAME, storageAccountForKey(key), value);
+        return;
+      }
+    } catch (error) {
+      logger.warn(
+        `Keychain save failed for ${key}, falling back to file storage: ${error.message}`
+      );
+    }
+    writeFileAtomically(filePathForKey(key), value);
+  }
+  async delete(key) {
+    assertValidKey(key);
+    try {
+      const kt = await getKeytar();
+      if (kt) {
+        await kt.deletePassword(SERVICE_NAME, storageAccountForKey(key));
+      }
+    } catch (error) {
+      logger.warn(`Keychain deletion failed for ${key}: ${error.message}`);
+    }
+    const cachePath = filePathForKey(key);
+    try {
+      if (fs.existsSync(cachePath)) {
+        fs.unlinkSync(cachePath);
+      }
+    } catch (error) {
+      logger.warn(`File deletion failed for ${key}: ${error.message}`);
+    }
+  }
+}
+class CommandTokenCacheStorage {
+  constructor(commandPath, timeoutMs = DEFAULT_AUTH_CACHE_COMMAND_TIMEOUT_MS, spawnCommand = spawn) {
+    this.commandPath = commandPath;
+    this.timeoutMs = timeoutMs;
+    this.spawnCommand = spawnCommand;
+    this.failClosed = true;
+    this.description = `command (${path.basename(commandPath)})`;
+  }
+  async load(key) {
+    assertValidKey(key);
+    const result = await this.invoke("load", key);
+    const trimmed = result.stdout.trim();
+    if (trimmed === "") {
+      return void 0;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      throw new Error(`Auth cache command returned invalid JSON for load ${key}.`);
+    }
+    if (!parsed || typeof parsed !== "object") {
+      throw new Error(`Auth cache command returned invalid JSON shape for load ${key}.`);
+    }
+    const response = parsed;
+    if (response.found === false) {
+      return void 0;
+    }
+    if (response.found === true && typeof response.value === "string") {
+      return response.value;
+    }
+    throw new Error(`Auth cache command returned invalid load response for ${key}.`);
+  }
+  async save(key, value) {
+    assertValidKey(key);
+    await this.invoke("save", key, JSON.stringify({ value }));
+  }
+  async delete(key) {
+    assertValidKey(key);
+    await this.invoke("delete", key);
+  }
+  async invoke(operation, key, stdinPayload) {
+    let result;
+    try {
+      result = await runCommand(
+        this.commandPath,
+        [operation, key],
+        stdinPayload,
+        this.timeoutMs,
+        this.spawnCommand
+      );
+    } catch (error) {
+      throw new Error(
+        `Auth cache command failed for ${operation} ${key}: ${error.message}`
+      );
+    }
+    if (result.timedOut) {
+      throw new Error(`Auth cache command timed out for ${operation} ${key}.`);
+    }
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `Auth cache command failed for ${operation} ${key} (exit ${result.exitCode ?? `signal ${result.signal ?? "unknown"}`})${formatStderr(
+          result.stderr
+        )}.`
+      );
+    }
+    return result;
+  }
+}
+function formatStderr(stderr) {
+  const trimmed = stderr.trim();
+  if (!trimmed) {
+    return "";
+  }
+  const truncated = trimmed.length > STDERR_LIMIT ? `${trimmed.slice(0, STDERR_LIMIT)}...` : trimmed;
+  return `: ${truncated}`;
+}
+function runCommand(commandPath, args, stdinPayload, timeoutMs, spawnCommand) {
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawnCommand(commandPath, args, { stdio: "pipe", shell: false });
+    } catch (error) {
+      reject(new Error(`could not be started: ${error.message}`));
+      return;
+    }
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let killTimer;
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      killTimer = setTimeout(() => {
+        child.kill("SIGKILL");
+      }, COMMAND_KILL_GRACE_MS);
+    }, timeoutMs);
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.stdin.on("error", () => {
+    });
+    child.once("error", (error) => {
+      clearTimeout(timeout);
+      if (killTimer) clearTimeout(killTimer);
+      reject(new Error(`could not be started: ${error.message}`));
+    });
+    child.once("close", (exitCode, signal) => {
+      clearTimeout(timeout);
+      if (killTimer) clearTimeout(killTimer);
+      resolve({ exitCode, signal, stdout, stderr, timedOut });
+    });
+    if (stdinPayload !== void 0) {
+      child.stdin.end(stdinPayload, "utf8");
+    } else {
+      child.stdin.end();
+    }
+  });
+}
+function parseTimeoutMs(value) {
+  if (value === void 0 || value.trim() === "") {
+    return DEFAULT_AUTH_CACHE_COMMAND_TIMEOUT_MS;
+  }
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`${AUTH_CACHE_COMMAND_TIMEOUT_ENV} must be a positive integer.`);
+  }
+  return parsed;
+}
+async function assertCommandUsable(commandPath) {
+  let stats;
+  try {
+    stats = await fs.promises.stat(commandPath);
+  } catch {
+    throw new Error(`${AUTH_CACHE_COMMAND_ENV} points to a path that does not exist.`);
+  }
+  if (!stats.isFile()) {
+    throw new Error(`${AUTH_CACHE_COMMAND_ENV} must point to an executable file.`);
+  }
+  if (process.platform !== "win32" && (stats.mode & 73) === 0) {
+    throw new Error(`${AUTH_CACHE_COMMAND_ENV} must point to an executable file.`);
+  }
+}
+async function createTokenCacheStorage(options = {}) {
+  const allowCommandStorage = options.allowCommandStorage ?? true;
+  const configuredCommand = process.env[AUTH_CACHE_COMMAND_ENV];
+  let storage;
+  if (allowCommandStorage && configuredCommand !== void 0) {
+    const commandPath = configuredCommand.trim();
+    if (commandPath === "") {
+      throw new Error(`${AUTH_CACHE_COMMAND_ENV} was provided but is empty.`);
+    }
+    await assertCommandUsable(commandPath);
+    storage = new CommandTokenCacheStorage(
+      commandPath,
+      parseTimeoutMs(process.env[AUTH_CACHE_COMMAND_TIMEOUT_ENV])
+    );
+  } else {
+    storage = new DefaultTokenCacheStorage();
+  }
+  if (options.logProvider) {
+    logger.info(`Auth cache storage provider: ${storage.description}`);
+  }
+  return storage;
+}
+export {
+  CommandTokenCacheStorage,
+  DefaultTokenCacheStorage,
+  createTokenCacheStorage,
+  getSelectedAccountPath,
+  getTokenCachePath,
+  pickNewest,
+  unwrapCache,
+  wrapCache
+};

package/docs/deployment.md

@@ -18,6 +18,14 @@ MCP Clients (Claude Desktop, Claude Code, Open WebUI, ...)
          Microsoft Graph API
 ```
 
+## Headless stdio auth-cache storage
+
+Production HTTP deployments are stateless: normal Graph requests carry a per-user bearer token, including On-Behalf-Of (`--obo`) deployments, and the server does not store MSAL token state for those requests.
+
+For headless stdio deployments that use local MSAL login (`--login`, `--verify-login`, auth tools, account selection, and regular stdio Graph calls), `MS365_MCP_AUTH_CACHE_COMMAND` can point at an external executable wrapper that stores the MSAL token cache and selected-account metadata in a deployment-approved backing store. The package only defines the provider-neutral command protocol; provider-specific scripts for AWS, Azure, GCP, Redis, databases, or other stores live outside this package.
+
+In HTTP mode, `MS365_MCP_AUTH_CACHE_COMMAND` is skipped at startup and per Graph request unless local auth tools are explicitly enabled with `--enable-auth-tools` or a local account command such as `--login`, `--verify-login`, `--list-accounts`, `--select-account`, `--remove-account`, or `--logout` is invoked.
+
 ## Docker
 
 A `Dockerfile` is included for containerized deployments:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softeria/ms-365-mcp-server",
-  "version": "0.110.0",
+  "version": "0.112.1",
   "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",
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@azure/msal-node": "^3.8.0",
+    "@azure/msal-node": "^5.2.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@toon-format/toon": "^0.8.0",
     "commander": "^11.1.0",
@@ -76,6 +76,6 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/softeria/ms-365-mcp-server.git"
+    "url": "https://github.com/Softeria/ms-365-mcp-server.git"
   }
 }