@littlebearapps/outlook-assistant 3.11.2 → 3.12.1

package/advanced/index.js

@@ -11,7 +11,21 @@
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { FIELD_PRESETS } = require('../utils/field-presets');
-const { DEFAULT_TIMEZONE } = require('../config');
+const config = require('../config');
+const { DEFAULT_TIMEZONE } = config;
+const {
+  buildMailboxPrefix,
+  validateMailboxPrefix,
+  SHARED_MAILBOX_DISABLED_MESSAGE,
+} = require('../utils/mailbox');
+const { resolveFolder } = require('../folder/resolve');
+const { getAllFoldersHierarchy } = require('../folder/list');
+const {
+  InvalidDateTimeError,
+  toGraphDateTimeTimeZone,
+  zonedParts,
+  zonedWallTimeToUtcMs,
+} = require('../utils/datetime');
 
 /**
  * Format an email for display (simplified)
@@ -42,13 +56,25 @@ function formatEmail(email, verbosity = 'standard') {
 }
 
 /**
- * Access shared mailbox handler
- * Requires Mail.Read.Shared permission
+ * Shared-mailbox hint appended to access errors while OUTLOOK_SHARED_MAILBOX
+ * is off (the token then carries no `.Shared` scope).
+ */
+const ENABLE_SHARED_HINT =
+  '\n\nShared-mailbox scopes are not enabled. Reading a mailbox other than your own normally needs `Mail.Read.Shared`: set OUTLOOK_SHARED_MAILBOX=read (work/school accounts only), restart the server, and run `auth action=authenticate force=true`.';
+
+/**
+ * Access shared mailbox handler.
+ *
+ * With OUTLOOK_SHARED_MAILBOX off this behaves exactly as before the opt-in
+ * flag existed: `folder` (or `folderId`) is used as given — a well-known name
+ * or a folder ID — with whatever scopes the token already has. With the flag
+ * on, custom/localized names and nested paths are resolved, and
+ * `listFolders` is available.
  */
 async function handleAccessSharedMailbox(args) {
   // F-46: accept `email` as alias for `sharedMailbox`. The original
   // param name is awkward; most callers reach for `email` first.
-  const { folder, count, outputVerbosity } = args;
+  const { folder, folderId, count, outputVerbosity, listFolders } = args;
   const sharedMailbox = args.sharedMailbox || args.email;
 
   if (!sharedMailbox) {
@@ -62,6 +88,40 @@ async function handleAccessSharedMailbox(args) {
     };
   }
 
+  // Validate up front, through the same helper every other tool uses. The
+  // ungated variant keeps this tool's pre-opt-in behaviour when
+  // OUTLOOK_SHARED_MAILBOX is off; with it on, buildMailboxPrefix and
+  // validateMailboxPrefix agree.
+  let mailboxPrefix;
+  try {
+    mailboxPrefix = validateMailboxPrefix(sharedMailbox);
+  } catch (error) {
+    return { content: [{ type: 'text', text: error.message }] };
+  }
+  if (mailboxPrefix === 'me') {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'access-shared-mailbox reads another mailbox — pass its email address. To read your own mailbox, use `search-emails`.',
+        },
+      ],
+    };
+  }
+
+  // listFolders mode: enumerate the shared mailbox's folder tree so callers
+  // can discover custom subfolder names/IDs to read from.
+  const sharedEnabled = config.SHARED_MAILBOX_MODE !== 'off';
+
+  if (listFolders) {
+    if (!sharedEnabled) {
+      return {
+        content: [{ type: 'text', text: SHARED_MAILBOX_DISABLED_MESSAGE }],
+      };
+    }
+    return handleListSharedMailboxFolders(sharedMailbox, args);
+  }
+
   const mailFolder = folder || 'inbox';
   const pageSize = Math.min(count || 25, 50);
   const verbosity = outputVerbosity || 'standard';
@@ -69,8 +129,45 @@ async function handleAccessSharedMailbox(args) {
   try {
     const accessToken = await ensureAuthenticated();
 
+    // Resolve the requested folder to an ID/well-known segment scoped to the
+    // shared mailbox. A raw `folderId` (from `listFolders`) is used as-is;
+    // otherwise custom and localized folder names are resolved via the tree.
+    let resolvedFolder;
+    if (!sharedEnabled) {
+      // Pre-opt-in behaviour: no folder resolution.
+      resolvedFolder = folderId || mailFolder;
+    } else {
+      try {
+        const resolved = await resolveFolder(accessToken, {
+          id: folderId,
+          name: mailFolder,
+          mailbox: sharedMailbox,
+        });
+        resolvedFolder = resolved.id;
+      } catch (resolveError) {
+        // Only resolution failures get the discovery hint — a Graph error
+        // (access denied, 5xx) must fall through to the generic handler below
+        // rather than masquerading as "folder not found".
+        if (!/not found|ambiguous/i.test(resolveError.message)) {
+          throw resolveError;
+        }
+        return {
+          content: [
+            {
+              type: 'text',
+              text:
+                `${resolveError.message}\n\n` +
+                `Searched in ${sharedMailbox}. List its folders first to get exact names/IDs:\n` +
+                '- `access-shared-mailbox` with `listFolders: true`, or\n' +
+                `- \`folders\` tool with \`action: list\`, \`sharedMailbox: "${sharedMailbox}"\``,
+            },
+          ],
+        };
+      }
+    }
+
     // Build endpoint for shared mailbox
-    const endpoint = `users/${sharedMailbox}/mailFolders/${mailFolder}/messages`;
+    const endpoint = `${mailboxPrefix}/mailFolders/${resolvedFolder}/messages`;
     const fieldSet = verbosity === 'full' ? 'read' : 'list';
     const queryParams = {
       $top: pageSize.toString(),
@@ -165,7 +262,7 @@ async function handleAccessSharedMailbox(args) {
         content: [
           {
             type: 'text',
-            text: `Access denied to shared mailbox "${sharedMailbox}".\n\n**Possible causes:**\n- You don't have access to this shared mailbox\n- The Mail.Read.Shared permission is not granted\n- The shared mailbox address is incorrect`,
+            text: `Access denied to shared mailbox "${sharedMailbox}".\n\n**Possible causes:**\n- You don't have access to this shared mailbox\n- The Mail.Read.Shared permission is not granted\n- The shared mailbox address is incorrect${sharedEnabled ? '' : ENABLE_SHARED_HINT}`,
           },
         ],
       };
@@ -193,6 +290,173 @@ async function handleAccessSharedMailbox(args) {
   }
 }
 
+/**
+ * Enumerate a shared mailbox's folder hierarchy.
+ *
+ * Lists the full folder tree (recursively) of a shared/delegated mailbox so
+ * callers can discover custom subfolder names, paths, and IDs — the values
+ * needed to read or search those folders.
+ * @param {string} sharedMailbox - Shared mailbox email address
+ * @param {object} args - Tool arguments (outputVerbosity)
+ * @returns {object} - MCP response
+ */
+async function handleListSharedMailboxFolders(sharedMailbox, args) {
+  const verbosity = args.outputVerbosity || 'standard';
+
+  try {
+    const accessToken = await ensureAuthenticated();
+
+    const { folders, warnings } = await getAllFoldersHierarchy(
+      accessToken,
+      true,
+      sharedMailbox
+    );
+
+    if (!folders || folders.length === 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `No folders found in ${sharedMailbox}.\n\nNote: Make sure you have delegate access to this shared mailbox and the Mail.Read.Shared permission is granted.`,
+          },
+        ],
+      };
+    }
+
+    const output = [];
+    output.push(`# Shared Mailbox Folders: ${sharedMailbox}`);
+    output.push(
+      `**Folders**: ${folders.length}${warnings.length > 0 ? ' (partial)' : ''}\n`
+    );
+
+    folders.forEach((f) => {
+      const depth = f.path ? f.path.split('/').length - 1 : 0;
+      const indent = '  '.repeat(depth);
+      let line = `${indent}- ${f.displayName}`;
+      const total = f.totalItemCount || 0;
+      const unread = f.unreadItemCount || 0;
+      line += ` (${total} items${unread > 0 ? `, ${unread} unread` : ''})`;
+      output.push(line);
+      if (verbosity === 'full') {
+        output.push(`${indent}  path: \`${f.path}\``);
+        output.push(`${indent}  id: \`${f.id}\``);
+      }
+    });
+
+    if (warnings.length > 0) {
+      output.push(
+        `\n**Partial listing — ${warnings.length} branch(es) incomplete:**`
+      );
+      warnings.forEach((w) => output.push(`- ${w}`));
+    }
+
+    output.push(
+      '\nRead a folder with `access-shared-mailbox` using its name, ' +
+        'path (e.g. `Inbox/Subfolder`), or `folderId`.'
+    );
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: output.join('\n'),
+        },
+      ],
+      _meta: {
+        sharedMailbox,
+        folderCount: folders.length,
+        partial: warnings.length > 0,
+        warnings,
+        folders: folders.map((f) => ({
+          id: f.id,
+          displayName: f.displayName,
+          folderPath: f.path,
+          parentFolderId: f.parentFolderId,
+          totalItemCount: f.totalItemCount,
+          unreadItemCount: f.unreadItemCount,
+        })),
+      },
+    };
+  } catch (error) {
+    if (error.message === 'Authentication required') {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
+          },
+        ],
+      };
+    }
+
+    if (
+      error.message.includes('Access is denied') ||
+      error.message.includes('403')
+    ) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Access denied to shared mailbox "${sharedMailbox}".\n\n**Possible causes:**\n- You don't have delegate access to this shared mailbox\n- The Mail.Read.Shared permission is not granted\n- The shared mailbox address is incorrect`,
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Error listing shared mailbox folders: ${error.message}`,
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * Default follow-up start for a flag with only a due date: 09:00 in
+ * DEFAULT_TIMEZONE on the due's local date, or the due itself when the due is
+ * earlier than that (a start after the due would be nonsense).
+ */
+function deriveFlagStart(due) {
+  let wall;
+  if (due.timeZone === DEFAULT_TIMEZONE) {
+    wall = due.dateTime;
+  } else {
+    const parts = zonedParts(Date.parse(`${due.dateTime}Z`), DEFAULT_TIMEZONE);
+    if (!parts) return { ...due };
+    wall = `${parts.date}T${parts.time}`;
+  }
+  const nineAm = `${wall.slice(0, 10)}T09:00:00`;
+  // Same zone and fixed-width prefix, so string order is time order.
+  return wall < nineAm
+    ? { ...due }
+    : { dateTime: nineAm, timeZone: DEFAULT_TIMEZONE };
+}
+
+/**
+ * Describe a flag dateTimeTimeZone envelope as UTC plus DEFAULT_TIMEZONE,
+ * e.g. "2026-03-01 09:00 UTC (2026-03-01 20:00 Australia/Melbourne)".
+ */
+function describeFlagTime(envelope) {
+  const ms =
+    envelope.timeZone === 'UTC'
+      ? Date.parse(`${envelope.dateTime}Z`)
+      : zonedWallTimeToUtcMs(envelope.dateTime, envelope.timeZone);
+  const local = (date, time) =>
+    `${date} ${time.slice(0, 5)} ${DEFAULT_TIMEZONE}`;
+  if (Number.isNaN(ms)) {
+    // DEFAULT_TIMEZONE isn't an IANA zone Intl knows; show it as given.
+    return local(envelope.dateTime.slice(0, 10), envelope.dateTime.slice(11));
+  }
+  const iso = new Date(ms).toISOString();
+  const utc = `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC`;
+  const parts =
+    DEFAULT_TIMEZONE === 'UTC' ? null : zonedParts(ms, DEFAULT_TIMEZONE);
+  return parts ? `${utc} (${local(parts.date, parts.time)})` : utc;
+}
+
 /**
  * Set message flag handler
  */
@@ -204,6 +468,7 @@ async function handleSetMessageFlag(args) {
     startDateTime,
     reminderDateTime: _reminderDateTime,
   } = args;
+  const prefix = buildMailboxPrefix(args.sharedMailbox || args.email || null);
 
   // Support single ID or array
   const ids = messageIds || (messageId ? [messageId] : []);
@@ -219,43 +484,38 @@ async function handleSetMessageFlag(args) {
     };
   }
 
+  // Build flag object. Zoned values (Z/offset) are sent as the same instant in
+  // UTC; zone-less values are read in DEFAULT_TIMEZONE. Bad dates are refused
+  // here, before authenticating or calling Graph.
+  const flag = {
+    flagStatus: 'flagged',
+  };
   try {
-    const accessToken = await ensureAuthenticated();
-
-    // Build flag object
-    const flag = {
-      flagStatus: 'flagged',
-    };
-
+    if (startDateTime) {
+      flag.startDateTime = toGraphDateTimeTimeZone(
+        startDateTime,
+        'startDateTime'
+      );
+    }
     if (dueDateTime) {
-      // Graph API expects { dateTime, timeZone } envelope without trailing Z
-      // When timeZone is specified, the dateTime value is interpreted in that zone
-      const dueDt = dueDateTime.replace(/Z$/i, '');
-      flag.dueDateTime = {
-        dateTime: dueDt,
-        timeZone: DEFAULT_TIMEZONE,
-      };
-
-      // Graph API requires startDateTime when dueDateTime is set
-      // Default to start of the same day if not explicitly provided
-      if (startDateTime) {
-        flag.startDateTime = {
-          dateTime: startDateTime.replace(/Z$/i, ''),
-          timeZone: DEFAULT_TIMEZONE,
-        };
-      } else {
-        const startOfDay = `${dueDt.split('T')[0]}T09:00:00`;
-        flag.startDateTime = {
-          dateTime: startOfDay,
-          timeZone: DEFAULT_TIMEZONE,
-        };
+      flag.dueDateTime = toGraphDateTimeTimeZone(dueDateTime, 'dueDateTime');
+      // Graph requires startDateTime when dueDateTime is set.
+      if (!flag.startDateTime) {
+        flag.startDateTime = deriveFlagStart(flag.dueDateTime);
       }
-    } else if (startDateTime) {
-      flag.startDateTime = {
-        dateTime: startDateTime.replace(/Z$/i, ''),
-        timeZone: DEFAULT_TIMEZONE,
+    }
+  } catch (error) {
+    if (error instanceof InvalidDateTimeError) {
+      return {
+        content: [{ type: 'text', text: error.message }],
+        isError: true,
       };
     }
+    throw error;
+  }
+
+  try {
+    const accessToken = await ensureAuthenticated();
 
     // Process all messages
     const results = [];
@@ -263,7 +523,7 @@ async function handleSetMessageFlag(args) {
 
     for (const id of ids) {
       try {
-        await callGraphAPI(accessToken, 'PATCH', `me/messages/${id}`, {
+        await callGraphAPI(accessToken, 'PATCH', `${prefix}/messages/${id}`, {
           flag,
         });
         results.push({ id, success: true });
@@ -277,11 +537,11 @@ async function handleSetMessageFlag(args) {
     if (results.length > 0) {
       output.push(`Flagged ${results.length} message(s) for follow-up`);
 
-      if (dueDateTime) {
-        output.push(`**Due**: ${new Date(dueDateTime).toLocaleString()}`);
+      if (flag.dueDateTime) {
+        output.push(`**Due**: ${describeFlagTime(flag.dueDateTime)}`);
       }
-      if (startDateTime) {
-        output.push(`**Start**: ${new Date(startDateTime).toLocaleString()}`);
+      if (flag.startDateTime) {
+        output.push(`**Start**: ${describeFlagTime(flag.startDateTime)}`);
       }
     }
 
@@ -333,6 +593,7 @@ async function handleSetMessageFlag(args) {
  */
 async function handleClearMessageFlag(args) {
   const { messageId, messageIds, markComplete } = args;
+  const prefix = buildMailboxPrefix(args.sharedMailbox || args.email || null);
 
   // Support single ID or array
   const ids = messageIds || (messageId ? [messageId] : []);
@@ -370,7 +631,7 @@ async function handleClearMessageFlag(args) {
 
     for (const id of ids) {
       try {
-        await callGraphAPI(accessToken, 'PATCH', `me/messages/${id}`, {
+        await callGraphAPI(accessToken, 'PATCH', `${prefix}/messages/${id}`, {
           flag,
         });
         results.push({ id, success: true });
@@ -607,7 +868,7 @@ const advancedTools = [
   {
     name: 'access-shared-mailbox',
     description:
-      'List emails from a shared mailbox the signed-in user has been granted access to (read-only). Returns paged messages from the named `sharedMailbox` (or alias `email`) and `folder` (default `inbox`) with id/subject/from/receivedDateTime/preview — same shape as `search-emails` list mode. Requires that the shared mailbox has been delegated to the signed-in user in Exchange (admin-configured). Use `outputVerbosity` to control field count and `count` (default 25, max 50) for page size. For full search/filter capability over a shared mailbox, prefer `search-emails` with a folder path scoped to the shared mailbox.',
+      "List emails — or enumerate folders — from a shared mailbox the signed-in user has been granted access to (read-only). Returns paged messages from the named `sharedMailbox` (or alias `email`) and `folder` (default `inbox`) with id/subject/from/receivedDateTime/preview — same shape as `search-emails` list mode. `folder` accepts a well-known name (inbox, sent, archive…), a custom/localized folder display name (e.g. `Archiv`), a nested folder path (e.g. `Inbox/Vendors/Acme`), or pass a raw `folderId`. Set `listFolders: true` to enumerate the shared mailbox's full folder tree (names, paths, IDs, counts) — use this to discover custom subfolders before reading them. Requires that the shared mailbox has been delegated to the signed-in user in Exchange (admin-configured). Use `outputVerbosity` to control field count and `count` (default 25, max 50) for page size. For full search/filter capability over a shared mailbox, prefer `search-emails` with `sharedMailbox` set. Custom/localized names, nested paths and `listFolders` need the server opt-in setting OUTLOOK_SHARED_MAILBOX (work/school only); without it `folder` must be a well-known name or a folder ID, as before.",
     annotations: {
       title: 'Shared Mailbox',
       readOnlyHint: true,
@@ -629,7 +890,18 @@ const advancedTools = [
         },
         folder: {
           type: 'string',
-          description: 'Folder to read from (default: inbox)',
+          description:
+            'Folder to read from (default: inbox). Accepts a well-known name, a custom/localized display name, or a nested path like `Inbox/Subfolder`.',
+        },
+        folderId: {
+          type: 'string',
+          description:
+            'Exact Graph folder ID to read from (e.g. from `listFolders`). Skips name resolution; takes precedence over `folder`.',
+        },
+        listFolders: {
+          type: 'boolean',
+          description:
+            "Enumerate the shared mailbox's full folder tree (names, paths, IDs, item counts) instead of reading messages.",
         },
         count: {
           type: 'number',
@@ -690,6 +962,7 @@ const advancedTools = [
 module.exports = {
   advancedTools,
   handleAccessSharedMailbox,
+  handleListSharedMailboxFolders,
   handleSetMessageFlag,
   handleClearMessageFlag,
   handleFindMeetingRooms,

package/auth/device-code.js

@@ -73,10 +73,19 @@ async function initiateDeviceCodeFlow(clientId, scopes) {
   const { statusCode, body } = await postRequest(endpoint, postData);
 
   if (statusCode < 200 || statusCode >= 300) {
-    throw new Error(
+    const error = new Error(
       body.error_description ||
         `Device code request failed with status ${statusCode}`
     );
+    // Same classification payload as pollForToken, so a scope rejection at
+    // initiation can be recognised by isScopeConsentError.
+    error.oauth = {
+      error: body.error,
+      error_codes: body.error_codes,
+      suberror: body.suberror,
+      error_description: body.error_description,
+    };
+    throw error;
   }
 
   return {
@@ -133,11 +142,22 @@ async function pollForToken(clientId, deviceCode, interval, expiresIn) {
         throw new Error(
           'Device code expired. Please restart the authentication process.'
         );
-      default:
-        throw new Error(
+      default: {
+        // Attach the raw OAuth payload so callers (e.g. handleDeviceCodeComplete)
+        // can classify the failure — notably scope-consent rejections that should
+        // trigger a base-scopes fallback. Keep the existing message text.
+        const e = new Error(
           body.error_description ||
             `Token polling failed: ${body.error || `status ${statusCode}`}`
         );
+        e.oauth = {
+          error: body.error,
+          error_codes: body.error_codes,
+          suberror: body.suberror,
+          error_description: body.error_description,
+        };
+        throw e;
+      }
     }
   }
 
@@ -146,7 +166,84 @@ async function pollForToken(clientId, deviceCode, interval, expiresIn) {
   );
 }
 
+// AADSTS codes meaning "this scope value isn't supported for this account" —
+// the only signals that justify a SILENT, DURABLE downgrade to base scopes:
+//   650053 — "The application asked for scope '<x>' that doesn't exist on the
+//             resource" (the personal-account `.Shared` rejection)
+//   70011  — invalid scope value
+// Deliberately NOT here:
+//   65001  — consent required (remediable: user/admin consent) → see
+//             isConsentRequiredError; must not silently strip capability
+//   28000  — generic invalid request, not scope-specific
+//   invalid_grant (bare) — MFA/conditional access, revoked grant, tenant policy
+const SCOPE_UNSUPPORTED_AADSTS_CODES = ['650053', '70011'];
+const CONSENT_REQUIRED_AADSTS_CODES = ['65001'];
+
+/**
+ * Does `err` carry one of `codes` in `oauth.error_codes` (array) or as an
+ * `AADSTS<code>` substring in `oauth.error_description` / `err.message`?
+ * @param {Error & {oauth?: object}} err
+ * @param {string[]} codes
+ * @returns {boolean}
+ */
+// The OAuth error payload is attacker-influencable HTTP data — fields may
+// arrive as arrays or objects instead of strings. Coerce before substring
+// checks so `includes` is always String.prototype.includes.
+function asString(value) {
+  return typeof value === 'string' ? value : '';
+}
+
+function hasAadstsCode(err, codes) {
+  const oauth = err.oauth || {};
+  if (Array.isArray(oauth.error_codes)) {
+    const found = oauth.error_codes.map(String);
+    if (found.some((c) => codes.includes(c))) {
+      return true;
+    }
+  }
+  const haystack = `${asString(oauth.error_description)} ${asString(err.message)}`;
+  // Whole-code match: `AADSTS70011` must not match `AADSTS700110`.
+  return codes.some((code) =>
+    new RegExp(`AADSTS${code}(?!\\d)`).test(haystack)
+  );
+}
+
+/**
+ * Predicate: is this a "requested scope isn't supported for this account"
+ * rejection that warrants falling back to base scopes? Deliberately narrow —
+ * a false positive silently and permanently strips shared-mailbox access.
+ * @param {Error & {oauth?: object}} err
+ * @returns {boolean}
+ */
+function isScopeConsentError(err) {
+  if (!err) {
+    return false;
+  }
+  // Consent-required takes precedence: it is remediable, so it must surface
+  // rather than silently downgrade the scope set.
+  if (isConsentRequiredError(err)) {
+    return false;
+  }
+  const oauth = err.oauth || {};
+  return (
+    oauth.error === 'invalid_scope' ||
+    hasAadstsCode(err, SCOPE_UNSUPPORTED_AADSTS_CODES)
+  );
+}
+
+/**
+ * Predicate: consent required (AADSTS65001). Remediable via user/admin consent
+ * — surface it, never downgrade the scope set.
+ * @param {Error & {oauth?: object}} err
+ * @returns {boolean}
+ */
+function isConsentRequiredError(err) {
+  return Boolean(err) && hasAadstsCode(err, CONSENT_REQUIRED_AADSTS_CODES);
+}
+
 module.exports = {
   initiateDeviceCodeFlow,
   pollForToken,
+  isScopeConsentError,
+  isConsentRequiredError,
 };

package/auth/token-storage.js

@@ -5,6 +5,36 @@ const https = require('https');
 const querystring = require('querystring');
 const { describeAuthError } = require('./auth-errors');
 
+/**
+ * Decide which scopes a refresh request should use. Prefer the scopes that were
+ * actually GRANTED (so a base-only fallback never re-requests `.Shared` on
+ * refresh and gets logged out ~1h later). Falls back to the parsed `scope`
+ * string, then to the configured scopes for back-compat with token files
+ * written before granted_scopes existed.
+ *
+ * `offline_access` is always included. Microsoft's token responses list only
+ * the scopes the access token is valid for — `offline_access` is not among
+ * them — and the token endpoint issues a new refresh_token only when
+ * `offline_access` is requested. Refreshing with the bare granted list would
+ * stop refresh-token rotation and eventually log the user out.
+ * @param {object|null} tokens - Stored token object
+ * @param {string[]} configScopes - Configured scope set (back-compat fallback)
+ * @returns {string[]} - Scopes to send in the refresh request
+ */
+function resolveRefreshScopes(tokens, configScopes) {
+  let scopes = configScopes;
+  if (tokens) {
+    if (Array.isArray(tokens.granted_scopes) && tokens.granted_scopes.length) {
+      scopes = tokens.granted_scopes;
+    } else if (typeof tokens.scope === 'string' && tokens.scope.trim()) {
+      scopes = tokens.scope.split(' ').filter(Boolean);
+    }
+  }
+  return scopes.includes('offline_access')
+    ? scopes
+    : [...scopes, 'offline_access'];
+}
+
 class TokenStorage {
   constructor(config) {
     this.config = {
@@ -179,7 +209,9 @@ class TokenStorage {
       client_id: this.config.clientId,
       grant_type: 'refresh_token',
       refresh_token: this.tokens.refresh_token,
-      scope: this.config.scopes.join(' '),
+      // Use the GRANTED scopes, not the full configured set. After a base-only
+      // fallback, re-requesting `.Shared` here would fail and log the user out.
+      scope: resolveRefreshScopes(this.tokens, this.config.scopes).join(' '),
     };
     if (!isDeviceCode) {
       refreshParams.client_secret = this.config.clientSecret;
@@ -272,13 +304,14 @@ class TokenStorage {
       );
     }
     console.log('Exchanging authorization code for tokens...');
+    const requestedScopes = this.config.scopes;
     const postData = querystring.stringify({
       client_id: this.config.clientId,
       client_secret: this.config.clientSecret,
       grant_type: 'authorization_code',
       code: authCode,
       redirect_uri: this.config.redirectUri,
-      scope: this.config.scopes.join(' '),
+      scope: requestedScopes.join(' '),
     });
 
     const requestOptions = {
@@ -306,6 +339,14 @@ class TokenStorage {
                   expires_in: responseBody.expires_in,
                   expires_at: Date.now() + responseBody.expires_in * 1000,
                   scope: responseBody.scope,
+                  // Persist granted scopes so refresh re-requests exactly what
+                  // was granted (mirrors the device-code path). If the token
+                  // response omits `scope`, fall back to what we requested.
+                  granted_scopes:
+                    typeof responseBody.scope === 'string' &&
+                    responseBody.scope.trim()
+                      ? responseBody.scope.split(' ').filter(Boolean)
+                      : requestedScopes,
                   token_type: responseBody.token_type,
                 };
                 try {
@@ -379,4 +420,5 @@ class TokenStorage {
 }
 
 module.exports = TokenStorage;
+module.exports.resolveRefreshScopes = resolveRefreshScopes;
 // Adding a newline at the end of the file as requested by Gemini Code Assist