@softeria/ms-365-mcp-server 0.146.1 → 0.147.0

package/README.md

@@ -667,6 +667,20 @@ Parent directories are created automatically. Files are written with `0600` perm
 
 **Without a credential store** (headless Linux, most containers) the key is written to `.cache-key` next to the cache file, with `0600` permissions. That stops the tokens showing up in a stray `cat`, a backup or an accidental commit. It does not protect against anyone who can already read the directory - the key is right there. Use `MS365_MCP_AUTH_CACHE_COMMAND` below if you need the cache in a real secret store.
 
+**Skipping the credential store on purpose:**
+
+```bash
+export MS365_MCP_USE_KEYTAR=0   # also accepts false, no or off
+```
+
+The key then goes to `.cache-key` on every platform, exactly as it does where no credential store exists, and nothing in the server calls keytar. Useful when the credential store prompts on each start - macOS re-asks whenever the calling binary changes, which under `npx` is every version bump - or when the native module misbehaves on your platform rather than simply failing to load. Any other value leaves the credential store in use, and an unrecognised one is warned about rather than passed over silently.
+
+Switching it off strands a cache that was encrypted under a key already in the credential store, since nothing can reach that key any more. The server says so and replaces that cache on the next sign-in, which signs out **every** account it held, not just the one you sign back in as. Unset the variable first if that cache is worth keeping.
+
+Only a cache that nothing on the machine can open is replaced. One that fails to decrypt while a usable key is sitting right there - a truncated file, a downgrade to an older build, a cache from somewhere else - is damage rather than a stranded cache, and is left alone exactly as it is by default.
+
+Two things it deliberately does not do. It never deletes what this server already put in the credential store, on logout or otherwise, because reaching the store is the thing you just asked it to stop doing - clear the `ms-365-mcp-server` entries by hand if you want them gone. And a `.cache-key` that exists but cannot be read (wrong owner on a bind-mounted config directory, say) is treated as recoverable rather than missing: the server refuses both to overwrite a cache and to mint a replacement key, and says so, rather than deleting a key that would work again once the permissions are fixed. Fix the permissions, or delete `.cache-key` yourself to start over - which does mean signing in again.
+
 If the cache cannot be decrypted - key lost, keychain locked, file modified - you are asked to sign in again rather than the server failing to start. The cache file is left exactly as it was: not deleted, and not overwritten by that new sign-in either. A keychain that is merely locked usually reads fine on the next start, and the cache is still there when it does.
 
 The cost is that the new session is not saved while this lasts, so each start asks you to sign in again. If the key is genuinely gone and the cache will never open, delete `.token-cache.json` to start over - the log says so, and names the path.

package/dist/auth-tools.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import logger from "./logger.js";
 import { getRequestTokens } from "./request-context.js";
 function registerAuthTools(server, authManager) {
   server.tool(
@@ -41,7 +42,10 @@ function registerAuthTools(server, authManager) {
           };
         }
         const text = await new Promise((resolve, reject) => {
-          authManager.acquireTokenByDeviceCode(resolve).catch(reject);
+          authManager.acquireTokenByDeviceCode(resolve).catch((error) => {
+            logger.error(`Device code login failed after the code was issued: ${error.message}`);
+            reject(error);
+          });
         });
         return {
           content: [

package/dist/auth.js

@@ -5,6 +5,9 @@ import { fileURLToPath } from "url";
 import path from "path";
 import { getSecrets } from "./secrets.js";
 import { getCloudEndpoints, getDefaultClientId } from "./cloud-config.js";
+import {
+  dedupeRefreshTokens
+} from "./lib/cache-dedupe.js";
 import {
   createTokenCacheStorage,
   DefaultTokenCacheStorage,
@@ -31,13 +34,104 @@ function createMsalConfig(secrets) {
     }
   };
 }
+const warnedDuplicateRefreshTokens = /* @__PURE__ */ new Set();
+let unresolvedDuplicateAccounts = /* @__PURE__ */ new Set();
+function resetRefreshTokenWarningsForTests() {
+  warnedDuplicateRefreshTokens.clear();
+  unresolvedDuplicateAccounts = /* @__PURE__ */ new Set();
+}
+function canonicalKeyResolver(tokenCache) {
+  const storage = tokenCache?.storage;
+  const generate = storage?.generateCredentialKey;
+  if (typeof generate !== "function") return void 0;
+  return (entity) => {
+    if (!entity.home_account_id || !entity.environment || !entity.client_id) return void 0;
+    try {
+      const key = generate.call(storage, {
+        homeAccountId: entity.home_account_id,
+        environment: entity.environment,
+        credentialType: "RefreshToken",
+        clientId: entity.client_id,
+        ...entity.family_id ? { familyId: entity.family_id } : {},
+        // Each of these owns a segment of the key. MSAL does not put them on refresh tokens
+        // today, but a serialized entity can carry them, and dropping them would map two
+        // different credentials onto one key - and then this deletes a live one
+        ...entity.realm ? { realm: entity.realm } : {},
+        ...entity.target ? { target: entity.target } : {},
+        ...entity.token_type ? { tokenType: entity.token_type } : {},
+        secret: entity.secret ?? ""
+      });
+      return typeof key === "string" ? key : void 0;
+    } catch {
+      return void 0;
+    }
+  };
+}
+function pruneDuplicateRefreshTokens(data, tokenCache) {
+  const result = dedupeRefreshTokens(
+    data,
+    tokenCache === void 0 ? void 0 : canonicalKeyResolver(tokenCache)
+  );
+  for (const drop of result.dropped) {
+    const signature = `${drop.environment}->${drop.keptEnvironment}`;
+    if (warnedDuplicateRefreshTokens.has(signature)) continue;
+    warnedDuplicateRefreshTokens.add(signature);
+    logger.warn(
+      `Dropped a stale refresh token cached under ${drop.environment}, keeping the one under ${drop.keptEnvironment}. MSAL treats those as the same account and spends whichever it finds first, which is what strands a sign-in on a months-old token (issue #648).`
+    );
+  }
+  unresolvedDuplicateAccounts = new Set(result.ambiguousAccounts);
+  if (result.ambiguous > 0 && !warnedDuplicateRefreshTokens.has("ambiguous")) {
+    warnedDuplicateRefreshTokens.add("ambiguous");
+    logger.warn(
+      `The auth cache holds ${result.ambiguous} set(s) of duplicate refresh tokens with nothing to say which is current, so they were left alone. If silent refresh keeps failing for an account, log out and sign in again to clear them.`
+    );
+  }
+  return result;
+}
+function dropFromKVStore(tokenCache, dropped) {
+  if (dropped.length === 0) return;
+  const store = tokenCache.getKVStore?.();
+  if (!store) return;
+  for (const drop of dropped) {
+    delete store[drop.key];
+  }
+}
+const PERSISTENCE_RECHECK_MS = 150;
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function persistedRefreshTokens(cacheJson, homeAccountId) {
+  let refreshTokens;
+  try {
+    const parsed = JSON.parse(cacheJson);
+    if (typeof parsed !== "object" || parsed === null) return void 0;
+    refreshTokens = parsed.RefreshToken;
+  } catch {
+    return void 0;
+  }
+  const secrets = /* @__PURE__ */ new Set();
+  if (typeof refreshTokens !== "object" || refreshTokens === null) return secrets;
+  for (const entity of Object.values(refreshTokens)) {
+    if (typeof entity !== "object" || entity === null) continue;
+    const credential = entity;
+    if (credential.home_account_id !== homeAccountId) continue;
+    if (credential.secret) secrets.add(credential.secret);
+  }
+  return secrets;
+}
 function buildDiskCoherencyCachePlugin(storage) {
   return {
     beforeCacheAccess: async (context) => {
       try {
         const cacheRaw = await storage.load("token-cache");
         if (cacheRaw) {
-          context.tokenCache.deserialize(unwrapCache(cacheRaw).data);
+          const pruned = pruneDuplicateRefreshTokens(
+            unwrapCache(cacheRaw).data,
+            context.tokenCache
+          );
+          context.tokenCache.deserialize(pruned.data);
+          dropFromKVStore(context.tokenCache, pruned.dropped);
         }
       } catch (error) {
         logger.error(`Error reloading token cache: ${error.message}`);
@@ -334,6 +428,12 @@ function describeAuthError(error) {
   }
   return error.message;
 }
+function duplicateRefreshTokenHint(account, unresolvedAccounts) {
+  if (!account || !unresolvedAccounts.has(account.homeAccountId)) {
+    return null;
+  }
+  return "The auth cache holds more than one refresh token for this account and nothing indicates which is current, so a stale one may be winning. Logging in again will not clear it - run logout first, then log in.";
+}
 const MSA_HOME_TENANT_ID = "9188040d-6c67-4c5b-b112-36a304b66dad";
 function consumersAuthorityHint(error, account, authority) {
   if (error instanceof AuthError && error.errorCode === "invalid_grant" && account?.tenantId === MSA_HOME_TENANT_ID && (!authority || /\/common\/?$/i.test(authority))) {
@@ -358,6 +458,7 @@ class AuthManager {
     this.tokenExpiry = null;
     this.selectedAccountId = null;
     this.useInteractiveAuth = false;
+    this.loginPersistence = null;
     this.expectedUsername = this.normalizeExpectedUsername(expectedAccount?.expectedUsername);
     this.expectedHomeAccountId = this.normalizeExpectedHomeAccountId(
       expectedAccount?.expectedHomeAccountId
@@ -380,7 +481,10 @@ class AuthManager {
     try {
       const cacheRaw = await this.storage.load("token-cache");
       if (cacheRaw) {
-        this.msalApp.getTokenCache().deserialize(unwrapCache(cacheRaw).data);
+        const tokenCache = this.msalApp.getTokenCache();
+        const pruned = pruneDuplicateRefreshTokens(unwrapCache(cacheRaw).data, tokenCache);
+        tokenCache.deserialize(pruned.data);
+        dropFromKVStore(tokenCache, pruned.dropped);
       }
       await this.loadSelectedAccount();
     } catch (error) {
@@ -531,6 +635,115 @@ class AuthManager {
       `Microsoft login did not return an account. Expected Microsoft account '${this.expectedAccountLabel()}'. Login was not persisted.`
     );
   }
+  async readPersistedRefreshTokens(homeAccountId) {
+    const cacheRaw = await this.storage.load("token-cache");
+    return cacheRaw ? persistedRefreshTokens(unwrapCache(cacheRaw).data, homeAccountId) : /* @__PURE__ */ new Set();
+  }
+  /**
+   * The cache as it stood before a sign-in, so the check afterwards can tell a write that
+   * never happened from one a sibling overwrote. The account is not known until the sign-in
+   * returns, so keep the whole blob and filter later. Best-effort.
+   */
+  async snapshotPersistedCache() {
+    try {
+      const cacheRaw = await this.storage.load("token-cache");
+      return cacheRaw ? unwrapCache(cacheRaw).data : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * Records why a sign-in could not be confirmed, then throws.
+   *
+   * The message has to outlive the throw. On the MCP `login` path the tool has already
+   * returned - it resolves as soon as there is a device code to show - so this rejection
+   * has nowhere to go, and `verify login` is where the user looks next. Clearing the
+   * in-memory token stops that check from answering out of memory and calling it a
+   * success (issue #648).
+   */
+  failLoginPersistence(account, reason) {
+    const message = `Signed in as '${this.describeAccount(account)}', but ${reason}`;
+    this.loginPersistence = { homeAccountId: account.homeAccountId, message };
+    this.accessToken = null;
+    this.tokenExpiry = null;
+    logger.error(message);
+    throw new Error(message);
+  }
+  /** Refresh token secrets MSAL holds for an account right now, before anything reloads. */
+  inMemoryRefreshTokens(homeAccountId) {
+    const secrets = /* @__PURE__ */ new Set();
+    const cache = this.msalApp.getTokenCache();
+    const store = cache.getKVStore?.();
+    if (!store) return secrets;
+    for (const entity of Object.values(store)) {
+      if (typeof entity !== "object" || entity === null) continue;
+      const credential = entity;
+      if (credential.credentialType !== "RefreshToken") continue;
+      if (credential.homeAccountId !== homeAccountId) continue;
+      if (credential.secret) secrets.add(credential.secret);
+    }
+    return secrets;
+  }
+  /**
+   * Confirms the refresh token MSAL just issued actually reached the cache.
+   *
+   * Persistence is best-effort by design: DefaultTokenCacheStorage is not fail-closed, so
+   * afterCacheAccess swallows a refused or failed write and the sign-in still reports
+   * success. The account then works for exactly one access token lifetime - the one held
+   * in memory - and every silent refresh afterwards falls back to whatever stale token is
+   * still on disk. Nothing surfaces that until it has been happening for weeks, by which
+   * point the stale token has aged past Entra's 90-day inactivity limit and the account is
+   * dead (issue #648). Cheaper to read the cache back once than to debug that later.
+   *
+   * `before` is the cache ahead of the sign-in. Demanding the issued token on disk is right
+   * until you remember the cache is last-writer-wins, not locked (issue #545): a sibling
+   * mid-refresh can rotate the same credential just after this one saved. That leaves a
+   * live token that isn't ours, which is a working account. The failure is a write that
+   * left no trace at all.
+   */
+  async assertLoginPersisted(account, before) {
+    this.loginPersistence = null;
+    if (!account) return;
+    const issued = this.inMemoryRefreshTokens(account.homeAccountId);
+    if (issued.size === 0) return;
+    let persisted;
+    try {
+      persisted = await this.readPersistedRefreshTokens(account.homeAccountId);
+      if (persisted && ![...issued].every((secret) => persisted.has(secret))) {
+        await delay(PERSISTENCE_RECHECK_MS);
+        persisted = await this.readPersistedRefreshTokens(account.homeAccountId);
+      }
+    } catch (error) {
+      this.failLoginPersistence(
+        account,
+        `the auth cache could not be read back (${error.message}), so the sign-in cannot be confirmed as saved. It would stop working when this access token expires. Fix the cache location, then log in again.`
+      );
+    }
+    if (persisted === void 0) {
+      this.failLoginPersistence(
+        account,
+        `the auth cache did not read back as a usable cache, so the sign-in cannot be confirmed as saved. It would stop working when this access token expires. Check the log for 'Not persisting token-cache'.`
+      );
+    }
+    if (![...issued].every((secret) => persisted.has(secret))) {
+      const beforeSecrets = before === void 0 ? void 0 : persistedRefreshTokens(before, account.homeAccountId);
+      const supersededByAnotherProcess = beforeSecrets !== void 0 && [...persisted].some((secret) => !beforeSecrets.has(secret));
+      if (!supersededByAnotherProcess) {
+        this.failLoginPersistence(
+          account,
+          `the refresh token was not written to the auth cache, so access would stop working when this access token expires. The log says why - look for 'Not persisting token-cache' or 'Error saving token cache'.`
+        );
+      }
+      logger.warn(
+        `Another process rewrote the auth cache for '${this.describeAccount(account)}' during sign-in. The refresh token on disk is not the one just issued, but it was not there before this sign-in either, so something wrote a live credential and the sign-in counts as saved (issue #545).`
+      );
+    }
+    if (persisted.size > 1) {
+      logger.warn(
+        `The auth cache holds ${persisted.size} refresh tokens for '${this.describeAccount(account)}'. MSAL spends whichever it finds first, so a stale one can win (issue #648). Log out and sign in again if silent refresh starts failing.`
+      );
+    }
+  }
   async setOAuthToken(token) {
     this.oauthToken = token;
     this.isOAuthMode = true;
@@ -554,7 +767,10 @@ class AuthManager {
         this.tokenExpiry = response.expiresOn ? new Date(response.expiresOn).getTime() : null;
         return this.accessToken;
       } catch (error) {
-        const hint = consumersAuthorityHint(error, currentAccount, this.config.auth.authority);
+        const hint = [
+          consumersAuthorityHint(error, currentAccount, this.config.auth.authority),
+          duplicateRefreshTokenHint(currentAccount, unresolvedDuplicateAccounts)
+        ].filter(Boolean).join(" ") || null;
         logger.error(
           `Silent token acquisition failed: ${describeAuthError(error)}${hint ? ` ${hint}` : ""}`
         );
@@ -602,12 +818,14 @@ class AuthManager {
     try {
       logger.info("Requesting device code...");
       logger.info(`Requesting scopes: ${this.scopes.join(", ")}`);
+      const before = await this.snapshotPersistedCache();
       const response = await this.msalApp.acquireTokenByDeviceCode(deviceCodeRequest);
       logger.info(`Granted scopes: ${response?.scopes?.join(", ") || "none"}`);
       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);
+      await this.assertLoginPersisted(response?.account, before);
       if (!this.selectedAccountId && response?.account) {
         this.selectedAccountId = response.account.homeAccountId;
         await this.saveSelectedAccount();
@@ -643,12 +861,14 @@ class AuthManager {
     try {
       logger.info("Requesting interactive browser login...");
       logger.info(`Requesting scopes: ${this.scopes.join(", ")}`);
+      const before = await this.snapshotPersistedCache();
       const response = await this.msalApp.acquireTokenInteractive(interactiveRequest);
       logger.info(`Granted scopes: ${response?.scopes?.join(", ") || "none"}`);
       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);
+      await this.assertLoginPersisted(response?.account, before);
       if (!this.selectedAccountId && response?.account) {
         this.selectedAccountId = response.account.homeAccountId;
         await this.saveSelectedAccount();
@@ -660,9 +880,25 @@ class AuthManager {
       throw error;
     }
   }
+  /**
+   * Whether the recorded failure is about the account this check would test.
+   *
+   * An explicit selection is the only thing that says "not asking about that sign-in".
+   * Resolving the account is not: a failed sign-in never reaches the auto-select and its
+   * account is usually missing from the cache anyway, so getCurrentAccount falls back to
+   * whichever is first and gives the neighbour a clean bill of health (issue #648).
+   */
+  loginPersistenceAppliesToCurrentAccount() {
+    if (!this.loginPersistence) return false;
+    return this.selectedAccountId === null || this.selectedAccountId === this.loginPersistence.homeAccountId;
+  }
   async testLogin() {
     try {
       logger.info("Testing login...");
+      if (this.loginPersistence && this.loginPersistenceAppliesToCurrentAccount()) {
+        logger.error(`Login test failed - ${this.loginPersistence.message}`);
+        return { success: false, message: this.loginPersistence.message };
+      }
       const token = await this.getToken();
       if (!token) {
         logger.error("Login test failed - no token received");
@@ -723,6 +959,7 @@ class AuthManager {
       this.accessToken = null;
       this.tokenExpiry = null;
       this.selectedAccountId = null;
+      this.loginPersistence = null;
       await this.storage.delete("token-cache");
       await this.storage.delete("selected-account");
       return true;
@@ -746,6 +983,9 @@ class AuthManager {
     await this.saveSelectedAccount();
     this.accessToken = null;
     this.tokenExpiry = null;
+    if (this.loginPersistence && this.loginPersistence.homeAccountId !== account.homeAccountId) {
+      this.loginPersistence = null;
+    }
     logger.info(`Selected account: ${account.username} (${account.homeAccountId})`);
     return true;
   }
@@ -753,6 +993,9 @@ class AuthManager {
     const account = await this.resolveAccount(identifier);
     try {
       await this.msalApp.getTokenCache().removeAccount(account);
+      if (this.loginPersistence?.homeAccountId === account.homeAccountId) {
+        this.loginPersistence = null;
+      }
       if (this.selectedAccountId === account.homeAccountId) {
         this.selectedAccountId = null;
         await this.saveSelectedAccount();
@@ -891,6 +1134,7 @@ export {
   consumersAuthorityHint,
   auth_default as default,
   describeAuthError,
+  duplicateRefreshTokenHint,
   getEndpointRequiredScopes,
   getEndpointScopeGroups,
   getMissingAllowedScopes,
@@ -899,6 +1143,7 @@ export {
   getTokenCachePath,
   parseAllowedScopes,
   pickNewest,
+  resetRefreshTokenWarningsForTests,
   resolveAuthScopes,
   unwrapCache,
   wrapCache

package/dist/lib/cache-dedupe.js

@@ -0,0 +1,126 @@
+function isDict(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isEntity(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function groupKey(homeAccountId, owner) {
+  return `${homeAccountId} ${owner}`;
+}
+function environmentPreferences(cache) {
+  const byOwner = /* @__PURE__ */ new Map();
+  if (isDict(cache.AccessToken)) {
+    for (const entity of Object.values(cache.AccessToken)) {
+      const home = entity?.home_account_id;
+      const environment = entity?.environment;
+      const client = entity?.client_id;
+      if (!home || !environment || !client) continue;
+      const cachedAt = Number(entity.cached_at);
+      if (!Number.isFinite(cachedAt)) continue;
+      const key = groupKey(home, client);
+      const best = byOwner.get(key);
+      if (!best || cachedAt > best.cachedAt) {
+        byOwner.set(key, { environment, cachedAt, tied: false });
+      } else if (cachedAt === best.cachedAt && environment !== best.environment) {
+        best.tied = true;
+      }
+    }
+  }
+  return byOwner;
+}
+function preferredEnvironment(preferences, group) {
+  const choice = preferences.get(groupKey(group.homeAccountId, group.owner));
+  if (!choice || choice.tied) return void 0;
+  return choice.environment;
+}
+function dropSupersededKeyFormats(refreshTokens, canonicalKeyFor) {
+  const byCanonical = /* @__PURE__ */ new Map();
+  for (const [key, entity] of Object.entries(refreshTokens)) {
+    if (!isEntity(entity)) continue;
+    const canonical = canonicalKeyFor(entity);
+    if (!canonical) continue;
+    byCanonical.set(canonical, [...byCanonical.get(canonical) ?? [], key]);
+  }
+  const dropped = [];
+  for (const [canonical, keys] of byCanonical) {
+    if (keys.length < 2 || !keys.includes(canonical)) continue;
+    for (const key of keys) {
+      if (key === canonical) continue;
+      dropped.push({
+        key,
+        environment: refreshTokens[key]?.environment ?? "unknown",
+        keptEnvironment: refreshTokens[canonical]?.environment ?? "unknown"
+      });
+    }
+  }
+  return dropped;
+}
+function dedupeRefreshTokens(cacheJson, canonicalKeyFor) {
+  const unchanged = {
+    data: cacheJson,
+    dropped: [],
+    ambiguous: 0,
+    ambiguousAccounts: []
+  };
+  let cache;
+  try {
+    const parsed = JSON.parse(cacheJson);
+    if (!isDict(parsed)) return unchanged;
+    cache = parsed;
+  } catch {
+    return unchanged;
+  }
+  const refreshTokens = cache.RefreshToken;
+  if (!isDict(refreshTokens)) return unchanged;
+  const supersededDrops = canonicalKeyFor ? dropSupersededKeyFormats(refreshTokens, canonicalKeyFor) : [];
+  for (const drop of supersededDrops) delete refreshTokens[drop.key];
+  const groups = /* @__PURE__ */ new Map();
+  for (const [key, entity] of Object.entries(refreshTokens)) {
+    if (!isEntity(entity)) continue;
+    const home = entity.home_account_id;
+    const owner = entity.family_id || entity.client_id;
+    if (!home || !owner) continue;
+    const group = groups.get(groupKey(home, owner));
+    if (group) group.keys.push(key);
+    else groups.set(groupKey(home, owner), { homeAccountId: home, owner, keys: [key] });
+  }
+  const duplicated = [...groups.values()].filter((group) => group.keys.length > 1);
+  if (duplicated.length === 0) {
+    return supersededDrops.length > 0 ? {
+      data: JSON.stringify(cache),
+      dropped: supersededDrops,
+      ambiguous: 0,
+      ambiguousAccounts: []
+    } : unchanged;
+  }
+  const preferences = environmentPreferences(cache);
+  const dropped = [...supersededDrops];
+  let ambiguous = 0;
+  const ambiguousAccounts = /* @__PURE__ */ new Set();
+  for (const group of duplicated) {
+    const keep = preferredEnvironment(preferences, group);
+    const winners = keep ? group.keys.filter((key) => refreshTokens[key]?.environment === keep) : [];
+    if (!keep || winners.length !== 1) {
+      ambiguous += 1;
+      ambiguousAccounts.add(group.homeAccountId);
+      continue;
+    }
+    for (const key of group.keys) {
+      if (key === winners[0]) continue;
+      dropped.push({
+        key,
+        environment: refreshTokens[key]?.environment ?? "unknown",
+        keptEnvironment: keep
+      });
+    }
+  }
+  const unranked = [...ambiguousAccounts];
+  if (dropped.length === 0) {
+    return { data: cacheJson, dropped, ambiguous, ambiguousAccounts: unranked };
+  }
+  for (const drop of dropped) delete refreshTokens[drop.key];
+  return { data: JSON.stringify(cache), dropped, ambiguous, ambiguousAccounts: unranked };
+}
+export {
+  dedupeRefreshTokens
+};

package/dist/token-cache-storage.js

@@ -18,6 +18,7 @@ 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 USE_KEYTAR_ENV = "MS365_MCP_USE_KEYTAR";
 const DEFAULT_AUTH_CACHE_COMMAND_TIMEOUT_MS = 1e4;
 const STDERR_LIMIT = 2048;
 const COMMAND_KILL_GRACE_MS = 1e3;
@@ -28,7 +29,33 @@ const CACHE_KEY_FILE = ".cache-key";
 const __filename = fileURLToPath(import.meta.url);
 const LEGACY_DIR = path.join(path.dirname(__filename), "..");
 let keytar = null;
+let loggedKeytarOptOut = false;
+let warnedKeytarValue = false;
+const KEYTAR_OFF_VALUES = /* @__PURE__ */ new Set(["0", "false", "no", "off"]);
+const KEYTAR_ON_VALUES = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
+function keytarEnabled() {
+  const raw = process.env[USE_KEYTAR_ENV];
+  if (raw === void 0) return true;
+  const value = raw.trim().toLowerCase();
+  if (KEYTAR_OFF_VALUES.has(value)) return false;
+  if (value !== "" && !KEYTAR_ON_VALUES.has(value) && !warnedKeytarValue) {
+    warnedKeytarValue = true;
+    logger.warn(
+      `${USE_KEYTAR_ENV} is set to ${JSON.stringify(raw)}, which is not a value this understands, so the system credential store stays in use. Set it to one of ${[...KEYTAR_OFF_VALUES].join(", ")} to turn it off.`
+    );
+  }
+  return true;
+}
 async function getKeytar() {
+  if (!keytarEnabled()) {
+    if (!loggedKeytarOptOut) {
+      loggedKeytarOptOut = true;
+      logger.info(
+        `${USE_KEYTAR_ENV} is off, using file-based credential storage. Anything this server previously stored under "${SERVICE_NAME}" in the system credential store is now left alone, including on logout, so clear it by hand if you want it gone.`
+      );
+    }
+    return null;
+  }
   if (keytar === void 0) {
     return null;
   }
@@ -172,6 +199,7 @@ function writeFileAtomically(filePath, value) {
 }
 let keyStatePromise;
 let encryptionKeyPromise;
+const mintedKeys = [];
 const legacyKeytarEntries = /* @__PURE__ */ new Set();
 const warnedUndecryptable = /* @__PURE__ */ new Set();
 function resetCacheKeyForTests() {
@@ -180,6 +208,9 @@ function resetCacheKeyForTests() {
   legacyKeytarEntries.clear();
   warnedUndecryptable.clear();
   legacyPathsMigrated = false;
+  loggedKeytarOptOut = false;
+  warnedKeytarValue = false;
+  mintedKeys.length = 0;
 }
 async function clearLegacyKeytarEntry(key) {
   if (!legacyKeytarEntries.delete(key)) return;
@@ -222,16 +253,26 @@ async function readCacheKeys() {
     }
   }
   let fileKeyIndex;
+  let fileKeyUnreadable = false;
   const keyPath = getCacheKeyPath();
-  if (existsSync(keyPath)) {
+  let raw;
+  try {
+    raw = readFileSync(keyPath, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      fileKeyUnreadable = true;
+      logger.warn(`Could not read the auth cache key file: ${error.message}`);
+    }
+  }
+  if (raw !== void 0) {
     try {
-      keys.push(parseCacheKey(readFileSync(keyPath, "utf8")));
+      keys.push(parseCacheKey(raw));
       fileKeyIndex = keys.length - 1;
     } catch (error) {
       logger.warn(`Ignoring unusable auth cache key file: ${error.message}`);
     }
   }
-  return { keys, fileKeyIndex, canUseKeychain };
+  return { keys, fileKeyIndex, canUseKeychain, fileKeyUnreadable };
 }
 function getEncryptionKey() {
   if (!encryptionKeyPromise) {
@@ -247,7 +288,13 @@ async function resolveEncryptionKey() {
   const state = await loadKeyState();
   const preferred = state.keys[state.fileKeyIndex ?? 0];
   if (preferred) return preferred;
+  if (state.fileKeyUnreadable) {
+    throw new Error(
+      `Refusing to replace the auth cache key at ${getCacheKeyPath()}: it exists but could not be read this run, and minting over it would strand every cache encrypted under it. Fix the permissions on that file, or delete it to start over.`
+    );
+  }
   const minted = await persistCacheKey(generateCacheKey(), state.canUseKeychain);
+  if (!mintedKeys.some((k) => k.equals(minted))) mintedKeys.push(minted);
   state.keys.unshift(minted);
   if (state.fileKeyIndex !== void 0) state.fileKeyIndex += 1;
   return minted;
@@ -278,8 +325,16 @@ async function persistCacheKey(key, canUseKeychain) {
     );
     return key;
   }
+  let existingRaw;
+  try {
+    existingRaw = readFileSync(keyPath, "utf8");
+  } catch (readError) {
+    throw new Error(
+      `Refusing to replace the auth cache key file at ${keyPath}: it could not be read (${readError.message}), so whether it holds a usable key is unknown.`
+    );
+  }
   try {
-    const existing = parseCacheKey(readFileSync(keyPath, "utf8"));
+    const existing = parseCacheKey(existingRaw);
     logger.info("Another process created the auth cache key file first, adopting it");
     return existing;
   } catch (parseError) {
@@ -333,12 +388,17 @@ async function readCacheFile(key, cachePath) {
   }
   if (onDisk === "") return { status: "absent" };
   if (isEncryptedCache(onDisk)) {
-    const { keys } = await loadKeyState();
-    const decrypted = decryptWithAnyKey(onDisk, keys, key);
+    const state = await loadKeyState();
+    const decrypted = decryptWithAnyKey(onDisk, state.keys, key);
     if (decrypted !== void 0) return { status: "decrypted", raw: decrypted };
     keyStatePromise = void 0;
     encryptionKeyPromise = void 0;
-    return { status: "unreadable", reason: "no known key opens it" };
+    const preExisting = state.keys.filter((k) => !mintedKeys.some((m) => m.equals(k)));
+    return {
+      status: "unreadable",
+      reason: state.fileKeyUnreadable ? "a key file is present but could not be read" : preExisting.length > 0 ? "the keys on hand do not open it" : "no known key opens it",
+      noKeyMatched: preExisting.length === 0 && !state.fileKeyUnreadable
+    };
   }
   if (isPlainCacheJson(onDisk)) return { status: "plaintext", raw: onDisk };
   return { status: "unreadable", reason: "not a recognisable auth cache" };
@@ -366,6 +426,15 @@ async function assertOverwritable(key, cachePath) {
     warnedUndecryptable.delete(key);
     return;
   }
+  if (state.noKeyMatched && !keytarEnabled()) {
+    if (!warnedUndecryptable.has(key)) {
+      warnedUndecryptable.add(key);
+      logger.warn(
+        `Replacing ${cachePath}: there is no auth cache key on this machine to open it with, and ${USE_KEYTAR_ENV} is off, so the key it was written under is most likely the one in the system credential store. Signing in again rewrites it against the key file instead. If that cache is worth keeping, stop the server and unset ${USE_KEYTAR_ENV} before signing in.`
+      );
+    }
+    return;
+  }
   if (!warnedUndecryptable.has(key)) {
     warnedUndecryptable.add(key);
     logger.warn(
@@ -614,6 +683,7 @@ export {
   getCacheKeyPath,
   getSelectedAccountPath,
   getTokenCachePath,
+  keytarEnabled,
   migrateLegacyPathsFrom,
   pickNewest,
   resetCacheKeyForTests,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@softeria/ms-365-mcp-server",
   "mcpName": "io.github.Softeria/ms-365-mcp-server",
-  "version": "0.146.1",
+  "version": "0.147.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",