@littlebearapps/outlook-assistant 3.13.0 → 3.14.0

package/auth/token-manager.js

@@ -3,6 +3,7 @@
  */
 const fs = require('fs');
 const config = require('../config');
+const { log } = require('../utils/logger');
 
 // Global variable to store tokens
 let cachedTokens = null;
@@ -38,11 +39,13 @@ function loadTokenCache() {
       cachedTokens = tokens;
       return tokens;
     } catch (parseError) {
-      console.error('Error parsing token file:', parseError.message);
+      log.note('auth', 'token-cache-unreadable');
+      log.debug('Error parsing token file:', parseError.message);
       return null;
     }
   } catch (error) {
-    console.error('Error loading token cache:', error.message);
+    log.note('auth', 'token-cache-unreadable');
+    log.debug('Error loading token cache:', error.message);
     return null;
   }
 }
@@ -64,7 +67,8 @@ function saveTokenCache(tokens) {
     cachedTokens = tokens;
     return true;
   } catch (error) {
-    console.error('Error saving token cache:', error);
+    log.note('auth', 'token-cache-save-failed');
+    log.debug('Error saving token cache:', error);
     return false;
   }
 }

package/auth/token-storage.js

@@ -3,8 +3,9 @@ const fsSync = require('fs');
 const path = require('path');
 const https = require('https');
 const querystring = require('querystring');
-const { describeAuthError } = require('./auth-errors');
+const { describeAuthError, authErrorLogLabel } = require('./auth-errors');
 const { resolveClientId } = require('./client-config');
+const { log } = require('../utils/logger');
 
 /**
  * Decide which scopes a refresh request should use. Prefer the scopes that were
@@ -108,7 +109,8 @@ class TokenStorage {
       return this.tokens;
     } catch (error) {
       if (error.code !== 'ENOENT') {
-        console.error('Error loading token cache:', error.message);
+        log.note('auth', 'token-cache-unreadable');
+        log.debug('Error loading token cache:', error.message);
       }
       this.tokens = null;
       return null;
@@ -126,7 +128,8 @@ class TokenStorage {
         { mode: 0o600 }
       );
     } catch (error) {
-      console.error('Error saving token cache:', error.message);
+      log.note('auth', 'token-cache-save-failed');
+      log.debug('Error saving token cache:', error.message);
       throw error;
     }
   }
@@ -161,19 +164,20 @@ class TokenStorage {
     await this.getTokens(); // Ensure tokens are loaded
 
     if (!this.tokens || !this.tokens.access_token) {
-      console.error('No access token available.');
+      log.debug('No access token available.');
       return null;
     }
 
     if (this.isTokenExpired()) {
-      console.error(
+      log.debug(
         'Access token expired or nearing expiration. Attempting refresh.'
       );
       if (this.tokens.refresh_token) {
         try {
           return await this.refreshAccessToken();
         } catch (refreshError) {
-          console.error('Failed to refresh access token:', refreshError);
+          log.note('auth', authErrorLogLabel('refresh-failed', refreshError));
+          log.debug('Failed to refresh access token:', refreshError);
           // Drop the in-memory tokens so callers re-authenticate. The save
           // below is intentionally a no-op — `_saveTokensToFile` returns early
           // when `tokens` is null — which is the behaviour we want: a transient
@@ -184,9 +188,8 @@ class TokenStorage {
           return null;
         }
       } else {
-        console.warn(
-          'No refresh token available. Cannot refresh access token.'
-        );
+        log.note('auth', 'no-refresh-token');
+        log.debug('No refresh token available. Cannot refresh access token.');
         // Same as above: clears memory, leaves the file alone. (#72)
         this.tokens = null;
         await this._saveTokensToFile();
@@ -205,7 +208,7 @@ class TokenStorage {
 
     // Prevent multiple concurrent refresh attempts
     if (this._refreshPromise) {
-      console.error('Refresh already in progress, returning existing promise.');
+      log.debug('Refresh already in progress, returning existing promise.');
       return this._refreshPromise.then((tokens) => tokens.access_token);
     }
 
@@ -213,7 +216,7 @@ class TokenStorage {
     // in refresh requests for tokens obtained via device code.
     // Browser flow (confidential client) requires client_secret.
     const isDeviceCode = this.tokens.auth_method === 'device-code';
-    console.error(
+    log.debug(
       `Attempting to refresh access token (auth_method: ${this.tokens.auth_method || 'browser'})...`
     );
 
@@ -259,12 +262,10 @@ class TokenStorage {
                   Date.now() + responseBody.expires_in * 1000;
                 try {
                   await this._saveTokensToFile();
-                  console.error(
-                    'Access token refreshed and saved successfully.'
-                  );
+                  log.debug('Access token refreshed and saved successfully.');
                   resolve(this.tokens);
                 } catch (saveError) {
-                  console.error('Failed to save refreshed tokens:', saveError);
+                  log.debug('Failed to save refreshed tokens:', saveError);
                   // Even if save fails, tokens are updated in memory.
                   // Depending on desired strictness, could reject here.
                   // For now, resolve with in-memory tokens but log critical error.
@@ -276,7 +277,7 @@ class TokenStorage {
                   );
                 }
               } else {
-                console.error('Error refreshing token:', responseBody);
+                log.debug('Error refreshing token:', responseBody);
                 reject(
                   new Error(
                     describeAuthError(
@@ -288,7 +289,7 @@ class TokenStorage {
               }
             } catch (e) {
               // Catch any error during parsing or saving
-              console.error(
+              log.debug(
                 'Error processing refresh token response or saving tokens:',
                 e
               );
@@ -300,7 +301,7 @@ class TokenStorage {
         }
       );
       req.on('error', (error) => {
-        console.error('HTTP error during token refresh:', error);
+        log.debug('HTTP error during token refresh:', error);
         reject(error);
         this._refreshPromise = null; // Clear promise on error
       });
@@ -318,7 +319,7 @@ class TokenStorage {
         'Client ID or Client Secret is not configured. Cannot exchange code for tokens.'
       );
     }
-    console.error('Exchanging authorization code for tokens...');
+    log.debug('Exchanging authorization code for tokens...');
     const requestedScopes = this.config.scopes;
     const postData = querystring.stringify({
       client_id: clientId,
@@ -366,10 +367,10 @@ class TokenStorage {
                 };
                 try {
                   await this._saveTokensToFile();
-                  console.error('Tokens exchanged and saved successfully.');
+                  log.debug('Tokens exchanged and saved successfully.');
                   resolve(this.tokens);
                 } catch (saveError) {
-                  console.error('Failed to save exchanged tokens:', saveError);
+                  log.debug('Failed to save exchanged tokens:', saveError);
                   // Similar to refresh, tokens are in memory but not persisted.
                   // Rejecting to indicate the operation wasn't fully successful.
                   reject(
@@ -379,10 +380,7 @@ class TokenStorage {
                   );
                 }
               } else {
-                console.error(
-                  'Error exchanging code for tokens:',
-                  responseBody
-                );
+                log.debug('Error exchanging code for tokens:', responseBody);
                 reject(
                   new Error(
                     describeAuthError(
@@ -394,7 +392,7 @@ class TokenStorage {
               }
             } catch (e) {
               // Catch any error during parsing or saving
-              console.error(
+              log.debug(
                 'Error processing token exchange response or saving tokens:',
                 e,
                 'Raw data:',
@@ -410,7 +408,7 @@ class TokenStorage {
         }
       );
       req.on('error', (error) => {
-        console.error('HTTP error during code exchange:', error);
+        log.debug('HTTP error during code exchange:', error);
         reject(error);
       });
       req.write(postData);
@@ -423,12 +421,12 @@ class TokenStorage {
     this.tokens = null;
     try {
       await fs.unlink(this.config.tokenStorePath);
-      console.error('Token file deleted successfully.');
+      log.debug('Token file deleted successfully.');
     } catch (error) {
       if (error.code === 'ENOENT') {
-        console.error('Token file not found, nothing to delete.');
+        log.debug('Token file not found, nothing to delete.');
       } else {
-        console.error('Error deleting token file:', error);
+        log.debug('Error deleting token file:', error);
       }
     }
   }

package/auth/tools.js

@@ -2,7 +2,7 @@
  * Authentication-related tools for the Outlook Assistant server
  */
 const config = require('../config');
-const { getAuthErrorHints } = require('./auth-errors');
+const { getAuthErrorHints, authErrorLogLabel } = require('./auth-errors');
 const fs = require('fs');
 const path = require('path');
 const tokenManager = require('./token-manager');
@@ -19,6 +19,9 @@ const {
   isScopeConsentError,
   isConsentRequiredError,
 } = require('./device-code');
+const { toolMetadata } = require('../utils/risk-classes');
+const { toolError } = require('../utils/tool-error');
+const { log } = require('../utils/logger');
 
 // Path for persisting device code state across MCP server restarts
 const DEVICE_CODE_STATE_PATH = path.join(
@@ -242,6 +245,7 @@ async function handleAbout() {
     `| Test Mode | ${testMode} |`,
     `| Rate Limit | ${rateLimit} |`,
     `| Recipient Allowlist | ${allowlist} |`,
+    `| Read-only mode | ${config.READ_ONLY ? 'On (OUTLOOK_READ_ONLY): only read tools and actions run' : 'Off (set OUTLOOK_READ_ONLY=true and restart to refuse every change)'} |`,
     `| Scopes | ${scopes.length} configured |`,
     `| Shared mailboxes | ${describeSharedMailboxStatus(granted)} |`,
     ``,
@@ -370,7 +374,7 @@ function saveDeviceCodeState(state) {
       fs.unlinkSync(DEVICE_CODE_STATE_PATH);
     }
   } catch (error) {
-    console.error(
+    log.debug(
       `[AUTH] Failed to ${state ? 'save' : 'clean up'} device code state: ${error.message}`
     );
   }
@@ -388,13 +392,13 @@ function loadDeviceCodeState() {
     }
     const state = JSON.parse(fs.readFileSync(DEVICE_CODE_STATE_PATH, 'utf8'));
     if (Date.now() > state.expiresAt) {
-      console.error('[AUTH] Persisted device code has expired, cleaning up');
+      log.debug('[AUTH] Persisted device code has expired, cleaning up');
       saveDeviceCodeState(null);
       return null;
     }
     return state;
   } catch (error) {
-    console.error(`[AUTH] Failed to load device code state: ${error.message}`);
+    log.debug(`[AUTH] Failed to load device code state: ${error.message}`);
     return null;
   }
 }
@@ -412,7 +416,7 @@ async function handleDeviceCodeAuth(prefix) {
     return buildMissingClientIdResponse();
   }
 
-  console.error('[AUTH] Starting device code flow...');
+  log.debug('[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.
@@ -449,7 +453,7 @@ async function initiateDeviceCode(scopes, scopesUsed, prefix) {
       !isConsentRequiredError(error) &&
       isScopeConsentError(error)
     ) {
-      console.error(
+      log.debug(
         '[AUTH] Shared-mailbox scopes rejected at device-code request; retrying with base scopes.'
       );
       return initiateDeviceCode(
@@ -473,8 +477,9 @@ async function initiateDeviceCode(scopes, scopesUsed, prefix) {
   };
   saveDeviceCodeState(pendingDeviceCode);
 
-  console.error(
-    `[AUTH] Device code (${scopesUsed} scopes): ${response.userCode}, expires in ${response.expiresIn}s`
+  // Never log the user code: it is for the user (via the tool result) only.
+  log.debug(
+    `[AUTH] Device code issued (${scopesUsed} scopes), expires in ${response.expiresIn}s`
   );
 
   const lines = [];
@@ -532,7 +537,8 @@ function buildDeviceCodeErrorResponse(error) {
     lines.push('', 'Suggested fixes:', ...hints.map((h) => `- ${h}`));
   }
 
-  console.error(`[AUTH] Device code initiation failed: ${msg}`);
+  log.note('auth', authErrorLogLabel('device-code-failed', error));
+  log.debug(`[AUTH] Device code initiation failed: ${msg}`);
 
   return {
     content: [{ type: 'text', text: lines.join('\n') }],
@@ -552,27 +558,17 @@ async function handleDeviceCodeComplete() {
   }
 
   if (!pendingDeviceCode) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'No pending device code flow. Call authenticate with method=device-code first.',
-        },
-      ],
-    };
+    return toolError('No pending device code flow.', {
+      nextStep: 'Start one with the `auth` tool with action=authenticate.',
+    });
   }
 
   if (Date.now() > pendingDeviceCode.expiresAt) {
     pendingDeviceCode = null;
     saveDeviceCodeState(null);
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Device code has expired. Please start a new authentication with action=authenticate.',
-        },
-      ],
-    };
+    return toolError(
+      'Device code has expired. Please start a new authentication with action=authenticate.'
+    );
   }
 
   // Poll with the client ID the code was issued to (older state files don't
@@ -593,7 +589,7 @@ async function handleDeviceCodeComplete() {
       : config.AUTH_CONFIG.scopes;
 
   try {
-    console.error('[AUTH] Polling for device code completion...');
+    log.debug('[AUTH] Polling for device code completion...');
     const tokenResponse = await pollForToken(
       clientId,
       pendingDeviceCode.deviceCode,
@@ -633,7 +629,7 @@ async function handleDeviceCodeComplete() {
     };
     await tokenStorage._saveTokensToFile();
 
-    console.error('[AUTH] Device code flow completed successfully.');
+    log.debug('[AUTH] Device code flow completed successfully.');
 
     return {
       content: [
@@ -656,7 +652,7 @@ async function handleDeviceCodeComplete() {
       !isConsentRequiredError(error) &&
       isScopeConsentError(error)
     ) {
-      console.error(
+      log.debug(
         '[AUTH] Shared-mailbox scopes rejected; falling back to base scopes.'
       );
       // Do NOT clear pendingDeviceCode — initiateDeviceCode replaces it.
@@ -677,19 +673,14 @@ async function handleDeviceCodeComplete() {
       } catch (reissueError) {
         pendingDeviceCode = null;
         saveDeviceCodeState(null);
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Authentication failed: ${reissueError.message}`,
-            },
-          ],
-        };
+        return toolError(`Authentication failed: ${reissueError.message}`);
       }
     }
 
     pendingDeviceCode = null;
     saveDeviceCodeState(null);
+    log.note('auth', authErrorLogLabel('device-code-complete-failed', error));
+    log.debug(`[AUTH] Device code completion failed: ${error.message}`);
 
     // Consent required (AADSTS65001) — remediable, so surface it instead of
     // silently downgrading to base scopes (which would strip shared-mailbox
@@ -697,30 +688,18 @@ async function handleDeviceCodeComplete() {
     // 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 toolError(
+        [
+          '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: [
-        {
-          type: 'text',
-          text: `Authentication failed: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Authentication failed: ${error.message}`);
   }
 }
 
@@ -729,7 +708,7 @@ async function handleDeviceCodeComplete() {
  * @returns {object} - MCP response
  */
 async function handleCheckAuthStatus() {
-  console.error('[CHECK-AUTH-STATUS] Starting authentication status check');
+  log.debug('[CHECK-AUTH-STATUS] Starting authentication status check');
 
   // Use TokenStorage for accurate status (includes refresh attempt)
   const TokenStorage = require('./token-storage');
@@ -744,7 +723,7 @@ async function handleCheckAuthStatus() {
   const accessToken = await tokenStorage.getValidAccessToken();
 
   if (!accessToken) {
-    console.error('[CHECK-AUTH-STATUS] No valid access token');
+    log.debug('[CHECK-AUTH-STATUS] No valid access token');
     const text =
       getClientIdSource() === 'none'
         ? `Not authenticated. No Azure Application (client) ID is configured yet: ask the user for the Application (client) ID of their Azure app registration, then call \`auth action=authenticate clientId=<id>\`. Setup guide: ${SETUP_GUIDE_URL}`
@@ -759,7 +738,7 @@ async function handleCheckAuthStatus() {
     ? Math.round((expiresAt - Date.now()) / 60000)
     : 'unknown';
 
-  console.error(
+  log.debug(
     `[CHECK-AUTH-STATUS] Authenticated, token expires in ~${expiresIn} min`
   );
 
@@ -778,13 +757,8 @@ const authTools = [
   {
     name: 'auth',
     description:
-      'Manage authentication with the Microsoft Graph API. action=`status` (default) returns the current auth state and auto-refreshes the access token if it\'s expired but the refresh token is still valid (~90-day window) — call this first to check before other tools. action=`authenticate` starts the OAuth flow: with `method: "device-code"` (default, works headlessly) it returns a code + URL for the user to visit; with `method: "browser"` it opens the local auth server on :3333 (run `npm run auth-server` first). Pass `force: true` to re-authenticate over an existing valid session. If sign-in reports that OUTLOOK_CLIENT_ID is not configured, ask the user for their Azure Application (client) ID and pass it as `clientId`. action=`device-code-complete` finishes device-code auth after the user enters the code in their browser — call this once authentication shows as successful in the browser. action=`about` returns server version, configured audience, scope list, and other diagnostic info. Tokens persist to `~/.outlook-assistant-tokens.json` and survive server restarts.',
-    annotations: {
-      title: 'Authentication',
-      readOnlyHint: false,
-      destructiveHint: false,
-      openWorldHint: false,
-    },
+      'Manage authentication with the Microsoft Graph API. action=`status` (default) returns the current auth state, refreshing an expired access token while the refresh token is still valid (~90 days); call it first to check before other tools. action=`authenticate` starts sign-in: `method: "device-code"` (default, works headlessly) returns a code + URL for the user to visit; `method: "browser"` uses the local auth server on :3333 (run `npm run auth-server` first). `force: true` re-authenticates over an existing valid session. If sign-in reports that OUTLOOK_CLIENT_ID is not configured, ask the user for their Azure Application (client) ID and pass it as `clientId`. action=`device-code-complete` finishes device-code sign-in once the browser shows it succeeded. action=`about` returns server version, configured audience, scope list and other diagnostics. Tokens persist to `~/.outlook-assistant-tokens.json` and survive server restarts.',
+    ...toolMetadata('auth', 'Authentication'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -825,14 +799,9 @@ const authTools = [
         case 'status':
           return handleCheckAuthStatus();
         default:
-          return {
-            content: [
-              {
-                type: 'text',
-                text: `Unknown action '${action}'. Valid actions: status, authenticate, device-code-complete, about.`,
-              },
-            ],
-          };
+          return toolError(
+            `Unknown action '${action}'. Valid actions: status, authenticate, device-code-complete, about.`
+          );
       }
     },
   },

package/calendar/attendees.js

@@ -9,6 +9,9 @@
  * new address. An explicit type always wins.
  */
 
+const { findBlockedRecipients } = require('../utils/safety');
+const { toolError } = require('../utils/tool-error');
+
 const ATTENDEE_TYPES = ['required', 'optional', 'resource'];
 const ATTENDEE_FIELDS = new Set(['email', 'type']);
 
@@ -93,8 +96,41 @@ function buildAttendees(list, current = []) {
   }));
 }
 
+/**
+ * Refuse an attendee list that OUTLOOK_ALLOWED_RECIPIENTS doesn't fully
+ * allow: Graph emails every attendee (rooms and resources included) an
+ * invitation or update carrying the event body. The whole call is refused,
+ * never sent with the blocked attendees dropped, and a dry run reports the
+ * refusal too. Needs no Graph call.
+ * @param {Array<{emailAddress: {address: string}}>} attendees - Graph attendees
+ * @param {{operation?: 'create'|'update', dryRun?: boolean}} [options]
+ * @returns {object|null} - toolError naming the blocked addresses, or null
+ */
+function checkAttendeeAllowlist(
+  attendees,
+  { operation = 'create', dryRun = false } = {}
+) {
+  if (!attendees || attendees.length === 0) return null;
+  const result = findBlockedRecipients(attendees);
+  if (!result) return null;
+
+  const subject = operation === 'update' ? 'Event update' : 'Event';
+  const lead = dryRun
+    ? `DRY RUN — ${subject.toLowerCase()} would be refused`
+    : `${subject} refused`;
+  const outcome = operation === 'update' ? 'changed' : 'created';
+  return toolError(
+    `${lead}: OUTLOOK_ALLOWED_RECIPIENTS does not allow attendee ${result.blocked.join(', ')} (allowed recipients/domains: ${result.allowed.join(', ')}). Graph emails every attendee, so nothing was ${outcome}; the call is refused whole rather than sent without them.`,
+    {
+      nextStep:
+        'Remove those attendees and retry, or ask the user to add them to OUTLOOK_ALLOWED_RECIPIENTS in the server configuration and restart the server.',
+    }
+  );
+}
+
 module.exports = {
   ATTENDEE_TYPES,
+  checkAttendeeAllowlist,
   normaliseAttendeeInput,
   normaliseAttendees,
   buildAttendees,

package/calendar/cancel.js

@@ -3,6 +3,8 @@
  */
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { previewCancelEvent } = require('./preview');
 
 /**
  * Cancel event handler
@@ -10,23 +12,19 @@ const { ensureAuthenticated } = require('../auth');
  * @returns {object} - MCP response
  */
 async function handleCancelEvent(args) {
-  const { eventId, comment } = args;
+  const { eventId, comment, dryRun = false } = args;
 
   if (!eventId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Event ID is required to cancel an event.',
-        },
-      ],
-    };
+    return toolError('Event ID is required to cancel an event.');
   }
 
   try {
     // Get access token
     const accessToken = await ensureAuthenticated();
 
+    // dryRun: read the event and say who would be emailed; send nothing.
+    if (dryRun) return await previewCancelEvent(accessToken, args);
+
     // Build API endpoint
     const endpoint = `me/events/${eventId}/cancel`;
 
@@ -49,24 +47,10 @@ async function handleCancelEvent(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error cancelling event: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error cancelling event: ${error.message}`);
   }
 }