@littlebearapps/outlook-assistant 3.11.1 → 3.12.0

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

package/auth/tools.js

@@ -6,7 +6,12 @@ const { getAuthErrorHints } = require('./auth-errors');
 const fs = require('fs');
 const path = require('path');
 const tokenManager = require('./token-manager');
-const { initiateDeviceCodeFlow, pollForToken } = require('./device-code');
+const {
+  initiateDeviceCodeFlow,
+  pollForToken,
+  isScopeConsentError,
+  isConsentRequiredError,
+} = require('./device-code');
 
 // Path for persisting device code state across MCP server restarts
 const DEVICE_CODE_STATE_PATH = path.join(
@@ -20,6 +25,49 @@ function setToolCount(count) {
   _toolCount = count;
 }
 
+/**
+ * Scopes recorded as granted in a stored token object. Prefers the
+ * `granted_scopes` array; falls back to the token response's `scope` string
+ * (token files written before granted_scopes existed). Full-URI forms such as
+ * `https://graph.microsoft.com/Mail.Read` are reduced to the bare scope name.
+ * @param {object|null} tokens
+ * @returns {string[]|null} - null when no token is stored
+ */
+function grantedScopesOf(tokens) {
+  if (!tokens) return null;
+  let raw = [];
+  if (Array.isArray(tokens.granted_scopes) && tokens.granted_scopes.length) {
+    raw = tokens.granted_scopes;
+  } else if (typeof tokens.scope === 'string') {
+    raw = tokens.scope.split(' ');
+  }
+  return raw.map((scope) => String(scope).split('/').pop()).filter(Boolean);
+}
+
+/**
+ * Human-readable shared-mailbox status for `auth about`.
+ * @param {string[]|null} granted - Granted scopes, or null when signed out
+ * @returns {string}
+ */
+function describeSharedMailboxStatus(granted) {
+  if (config.SHARED_MAILBOX_MODE === 'off' || !config.SHARED_SCOPES.length) {
+    return 'Disabled (opt-in, work/school only: set `OUTLOOK_SHARED_MAILBOX=read` or `=true`, restart, then `auth action=authenticate force=true`)';
+  }
+  const lowerGranted = (granted || []).map((s) => s.toLowerCase());
+  const parts = config.SHARED_SCOPES.map(
+    (scope) =>
+      `${scope} ${lowerGranted.includes(scope.toLowerCase()) ? 'granted' : 'not granted'}`
+  );
+  let status = `Enabled (${config.SHARED_MAILBOX_MODE}): ${parts.join(', ')}`;
+  if (!granted) {
+    status += ' (not signed in)';
+  } else if (parts.some((p) => p.endsWith('not granted'))) {
+    status +=
+      ' (re-authenticate with `auth action=authenticate force=true`; personal accounts cannot be granted these)';
+  }
+  return status;
+}
+
 /**
  * About tool handler
  * @returns {object} - MCP response
@@ -43,6 +91,17 @@ async function handleAbout() {
   // GET /me round-trip when a valid token is available; degrades
   // gracefully when not authenticated.
   let identity = 'Not authenticated (run `auth action=authenticate`)';
+  // Granted scopes come from the stored token file (scope names only — the
+  // tokens themselves are never surfaced).
+  let granted = null;
+  try {
+    const { tokenStorage } = require('./index');
+    if (tokenStorage && typeof tokenStorage.getTokens === 'function') {
+      granted = grantedScopesOf(await tokenStorage.getTokens());
+    }
+  } catch (_e) {
+    // Leave granted as unknown
+  }
   try {
     const { ensureAuthenticated } = require('./index');
     const { callGraphAPI } = require('../utils/graph-api');
@@ -70,8 +129,10 @@ async function handleAbout() {
     `| Rate Limit | ${rateLimit} |`,
     `| Recipient Allowlist | ${allowlist} |`,
     `| Scopes | ${scopes.length} configured |`,
+    `| Shared mailboxes | ${describeSharedMailboxStatus(granted)} |`,
     ``,
-    `**Scopes**: ${scopes.join(', ')}`,
+    `**Configured scopes**: ${scopes.join(', ')}`,
+    `**Granted scopes**: ${granted ? granted.filter((s) => s !== 'offline_access').join(', ') || 'none recorded' : 'not signed in'}`,
   ];
 
   // F-1 / F-48: warn when no safety belts are wired up. AI-assisted
@@ -209,6 +270,23 @@ async function handleDeviceCodeAuth() {
   }
 
   console.error('[AUTH] Starting device code flow...');
+  // Attempt the configured scope set (base, plus `.Shared` when
+  // OUTLOOK_SHARED_MAILBOX opts in). If the account can't consent to
+  // `.Shared`, handleDeviceCodeComplete re-issues with base scopes.
+  return initiateDeviceCode(config.AUTH_CONFIG.scopes, 'full');
+}
+
+/**
+ * Shared helper: request a device code for a given scope set, persist the
+ * pending state (tagging which scope set was used so the completion step can
+ * decide whether a fallback is still available), and build the MCP response.
+ * @param {string[]} scopes - OAuth scopes to request
+ * @param {'full'|'base'} scopesUsed - Label recording which scope set was used
+ * @param {string} [prefix] - Optional leading line (used for the fallback case)
+ * @returns {Promise<object>} - MCP response
+ */
+async function initiateDeviceCode(scopes, scopesUsed, prefix) {
+  const clientId = config.AUTH_CONFIG.clientId;
 
   // #213 — initiation can throw (blocked network egress in a sandboxed
   // connector, AADSTS9002331 audience mismatch, invalid_client, non-JSON
@@ -218,11 +296,25 @@ async function handleDeviceCodeAuth() {
   // (handleDeviceCodeComplete) already has, and surface actionable hints.
   let response;
   try {
-    response = await initiateDeviceCodeFlow(
-      clientId,
-      config.AUTH_CONFIG.scopes
-    );
+    response = await initiateDeviceCodeFlow(clientId, scopes);
   } catch (error) {
+    // The `.Shared` scopes can also be rejected when the code is requested
+    // (before sign-in). Same single fallback as at completion.
+    if (
+      config.SHARED_SCOPES.length > 0 &&
+      scopesUsed === 'full' &&
+      !isConsentRequiredError(error) &&
+      isScopeConsentError(error)
+    ) {
+      console.error(
+        '[AUTH] Shared-mailbox scopes rejected at device-code request; retrying with base scopes.'
+      );
+      return initiateDeviceCode(
+        config.AUTH_CONFIG.fallbackScopes,
+        'base',
+        "Your account doesn't support shared-mailbox access; signing in with the standard scopes instead."
+      );
+    }
     return buildDeviceCodeErrorResponse(error);
   }
 
@@ -232,24 +324,31 @@ async function handleDeviceCodeAuth() {
     interval: response.interval,
     expiresIn: response.expiresIn,
     expiresAt: Date.now() + response.expiresIn * 1000,
+    scopesUsed,
   };
   saveDeviceCodeState(pendingDeviceCode);
 
   console.error(
-    `[AUTH] Device code: ${response.userCode}, expires in ${response.expiresIn}s`
+    `[AUTH] Device code (${scopesUsed} scopes): ${response.userCode}, expires in ${response.expiresIn}s`
+  );
+
+  const lines = [];
+  if (prefix) {
+    lines.push(prefix, '');
+  }
+  lines.push(
+    `## Device Code Authentication\n`,
+    `Visit: **${response.verificationUri}**`,
+    `Enter code: **${response.userCode}**\n`,
+    `The code expires in ${Math.floor(response.expiresIn / 60)} minutes.\n`,
+    `After entering the code and signing in, call this tool again with \`action=device-code-complete\` to finish authentication.`
   );
 
   return {
     content: [
       {
         type: 'text',
-        text: [
-          `## Device Code Authentication\n`,
-          `Visit: **${response.verificationUri}**`,
-          `Enter code: **${response.userCode}**\n`,
-          `The code expires in ${Math.floor(response.expiresIn / 60)} minutes.\n`,
-          `After entering the code and signing in, call this tool again with \`action=device-code-complete\` to finish authentication.`,
-        ].join('\n'),
+        text: lines.join('\n'),
       },
     ],
   };
@@ -332,6 +431,14 @@ async function handleDeviceCodeComplete() {
   }
 
   const clientId = config.AUTH_CONFIG.clientId;
+  // Capture which scope set this pending flow attempted, before any mutation.
+  const scopesUsed = pendingDeviceCode.scopesUsed || 'full';
+  // The scopes we attempted — used as the granted_scopes fallback when the
+  // token response omits `scope`.
+  const attemptedScopes =
+    scopesUsed === 'base'
+      ? config.AUTH_CONFIG.fallbackScopes
+      : config.AUTH_CONFIG.scopes;
 
   try {
     console.error('[AUTH] Polling for device code completion...');
@@ -355,12 +462,20 @@ async function handleDeviceCodeComplete() {
       tokenEndpoint: config.AUTH_CONFIG.tokenEndpoint,
     });
 
+    // Persist the GRANTED scopes so token refresh re-requests exactly what was
+    // granted (not the full configured set) — otherwise a base-only fallback
+    // would re-request `.Shared` on refresh ~1h later and log the user out.
+    const grantedScopes = tokenResponse.scope
+      ? tokenResponse.scope.split(' ').filter(Boolean)
+      : attemptedScopes;
+
     tokenStorage.tokens = {
       access_token: tokenResponse.access_token,
       refresh_token: tokenResponse.refresh_token,
       expires_in: tokenResponse.expires_in,
       expires_at: Date.now() + tokenResponse.expires_in * 1000,
       scope: tokenResponse.scope,
+      granted_scopes: grantedScopes,
       token_type: tokenResponse.token_type,
       auth_method: 'device-code',
     };
@@ -377,8 +492,75 @@ async function handleDeviceCodeComplete() {
       ],
     };
   } catch (error) {
+    // Scope-consent rejection while attempting the FULL set → re-issue with
+    // base scopes. This is the personal-account path: one extra device code.
+    // Only meaningful when shared-mailbox support is on: with the flag off the
+    // attempted set already IS the base set, so there is nothing to drop.
+    // Consent-required (AADSTS65001) is checked first: it is remediable and
+    // must surface below, never trigger a silent downgrade.
+    if (
+      config.SHARED_SCOPES.length > 0 &&
+      scopesUsed === 'full' &&
+      !isConsentRequiredError(error) &&
+      isScopeConsentError(error)
+    ) {
+      console.error(
+        '[AUTH] Shared-mailbox scopes rejected; falling back to base scopes.'
+      );
+      // Do NOT clear pendingDeviceCode — initiateDeviceCode replaces it.
+      try {
+        const fallbackResponse = await initiateDeviceCode(
+          config.AUTH_CONFIG.fallbackScopes,
+          'base',
+          "Your account doesn't support shared-mailbox access; enter this new code to finish signing in."
+        );
+        // initiateDeviceCode reports its own failures as { isError: true }
+        // instead of throwing. Clear the rejected full-scope pending state so
+        // a later completion attempt doesn't retry it.
+        if (fallbackResponse && fallbackResponse.isError) {
+          pendingDeviceCode = null;
+          saveDeviceCodeState(null);
+        }
+        return fallbackResponse;
+      } catch (reissueError) {
+        pendingDeviceCode = null;
+        saveDeviceCodeState(null);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Authentication failed: ${reissueError.message}`,
+            },
+          ],
+        };
+      }
+    }
+
     pendingDeviceCode = null;
     saveDeviceCodeState(null);
+
+    // Consent required (AADSTS65001) — remediable, so surface it instead of
+    // silently downgrading to base scopes (which would strip shared-mailbox
+    // access for every future refresh).
+    // Only when the shared scopes were requested — otherwise the generic
+    // path below (with its AADSTS hint table) is unchanged.
+    if (config.SHARED_SCOPES.length > 0 && isConsentRequiredError(error)) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: [
+              'Authentication failed: consent was not granted (AADSTS65001).',
+              '',
+              `An administrator may need to grant consent for the shared-mailbox scopes (${config.SHARED_SCOPES.join(', ')}), or re-run \`auth action=authenticate\` and approve every requested permission.`,
+              'If your organisation will not consent to them, unset OUTLOOK_SHARED_MAILBOX and restart the server to sign in with the standard scopes.',
+              'No scopes were changed — your configured capability is unchanged.',
+            ].join('\n'),
+          },
+        ],
+      };
+    }
+
     return {
       content: [
         {

package/calendar/index.js

@@ -13,7 +13,7 @@ const calendarTools = [
   {
     name: 'list-events',
     description:
-      'List upcoming calendar events for the signed-in user (read-only). Returns an array of events with id, subject, start/end, attendees, location, organiser, and webLink. Use `count` (default 10, max 50) to control page size; this tool does not filter — use the Outlook UI or specific date ranges via Graph for filtered queries. Each start/end is returned as a canonical UTC ISO-8601 instant (e.g. `2026-04-02T22:00:00.000Z`) followed by a labelled local rendering in the configured display timezone (default Australia/Melbourne; override with `OUTLOOK_DEFAULT_TIMEZONE`) — the UTC value is authoritative, so consumers never have to guess the zone.',
+      'List calendar events for the signed-in user (read-only). By default returns upcoming events (start ≥ now). Optional `startAfter`, `startBefore` and `subject` filters find past, current or specifically-named events; supplying any of them replaces the default "now" lower bound and the filters are AND-ed together. Results are oldest first, except when the search only looks backwards (`startBefore` without `startAfter`, or `subject` alone), where they are newest first. Returns an array of events with id, subject, start/end, attendees, location, organiser, and webLink. Use `count` (default 10, max 50) to control page size. Each start/end is returned as a canonical UTC ISO-8601 instant (e.g. `2026-04-02T22:00:00.000Z`) followed by a labelled local rendering in the configured display timezone (default Australia/Melbourne; override with `OUTLOOK_DEFAULT_TIMEZONE`) — the UTC value is authoritative, so consumers never have to guess the zone.',
     annotations: {
       title: 'List Calendar Events',
       readOnlyHint: true,
@@ -26,6 +26,24 @@ const calendarTools = [
           type: 'number',
           description: 'Number of events to retrieve (default: 10, max: 50)',
         },
+        startAfter: {
+          type: 'string',
+          format: 'date-time',
+          description:
+            'Optional ISO 8601 datetime with `Z` or a ±hh:mm offset (required). Only return events whose start is on or after this time. Replaces the default "now" lower bound when supplied. Example: "2026-01-01T00:00:00Z" or "2026-01-01T09:00:00+10:00".',
+        },
+        startBefore: {
+          type: 'string',
+          format: 'date-time',
+          description:
+            'Optional ISO 8601 datetime with `Z` or a ±hh:mm offset (required). Only return events whose start is strictly before this time. Combine with `startAfter` to bound a window; on its own, results are newest first. Example: "2026-02-01T00:00:00Z".',
+        },
+        subject: {
+          type: 'string',
+          description:
+            'Optional substring (max 255 characters) to match against the event subject, case-insensitive (Graph `contains()`). Useful for finding past or current events by name; on its own, results are newest first.',
+          maxLength: 255,
+        },
       },
       additionalProperties: false,
       required: [],