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

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/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/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.111.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",