@littlebearapps/outlook-assistant 3.12.1 → 3.14.0

package/advanced/index.js

@@ -26,6 +26,8 @@ const {
   zonedParts,
   zonedWallTimeToUtcMs,
 } = require('../utils/datetime');
+const { toolMetadata } = require('../utils/risk-classes');
+const { toolError, authRequiredError } = require('../utils/tool-error');
 
 /**
  * Format an email for display (simplified)
@@ -78,14 +80,9 @@ async function handleAccessSharedMailbox(args) {
   const sharedMailbox = args.sharedMailbox || args.email;
 
   if (!sharedMailbox) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: "Shared mailbox email address is required (e.g., 'shared@company.com').",
-        },
-      ],
-    };
+    return toolError(
+      "Shared mailbox email address is required (e.g., 'shared@company.com')."
+    );
   }
 
   // Validate up front, through the same helper every other tool uses. The
@@ -96,17 +93,12 @@ async function handleAccessSharedMailbox(args) {
   try {
     mailboxPrefix = validateMailboxPrefix(sharedMailbox);
   } catch (error) {
-    return { content: [{ type: 'text', text: error.message }] };
+    return toolError(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`.',
-        },
-      ],
-    };
+    return toolError(
+      '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
@@ -115,9 +107,7 @@ async function handleAccessSharedMailbox(args) {
 
   if (listFolders) {
     if (!sharedEnabled) {
-      return {
-        content: [{ type: 'text', text: SHARED_MAILBOX_DISABLED_MESSAGE }],
-      };
+      return toolError(SHARED_MAILBOX_DISABLED_MESSAGE);
     }
     return handleListSharedMailboxFolders(sharedMailbox, args);
   }
@@ -151,18 +141,12 @@ async function handleAccessSharedMailbox(args) {
         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}"\``,
-            },
-          ],
-        };
+        return toolError(
+          `${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}"\``
+        );
       }
     }
 
@@ -244,49 +228,25 @@ async function handleAccessSharedMailbox(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
     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 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}`,
-          },
-        ],
-      };
+      return toolError(
+        `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}`
+      );
     }
 
     if (error.message.includes('not found') || error.message.includes('404')) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Shared mailbox "${sharedMailbox}" not found. Please verify the email address.`,
-          },
-        ],
-      };
+      return toolError(
+        `Shared mailbox "${sharedMailbox}" not found. Please verify the email address.`
+      );
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error accessing shared mailbox: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error accessing shared mailbox: ${error.message}`);
   }
 }
 
@@ -379,38 +339,19 @@ async function handleListSharedMailboxFolders(sharedMailbox, args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
     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 toolError(
+        `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}`,
-        },
-      ],
-    };
+    return toolError(`Error listing shared mailbox folders: ${error.message}`);
   }
 }
 
@@ -474,14 +415,7 @@ async function handleSetMessageFlag(args) {
   const ids = messageIds || (messageId ? [messageId] : []);
 
   if (ids.length === 0) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Message ID (messageId) or IDs (messageIds) required.',
-        },
-      ],
-    };
+    return toolError('Message ID (messageId) or IDs (messageIds) required.');
   }
 
   // Build flag object. Zoned values (Z/offset) are sent as the same instant in
@@ -568,23 +502,9 @@ async function handleSetMessageFlag(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error setting message flag: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error setting message flag: ${error.message}`);
   }
 }
 
@@ -599,14 +519,7 @@ async function handleClearMessageFlag(args) {
   const ids = messageIds || (messageId ? [messageId] : []);
 
   if (ids.length === 0) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Message ID (messageId) or IDs (messageIds) required.',
-        },
-      ],
-    };
+    return toolError('Message ID (messageId) or IDs (messageIds) required.');
   }
 
   try {
@@ -671,23 +584,9 @@ async function handleClearMessageFlag(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error clearing message flag: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error clearing message flag: ${error.message}`);
   }
 }
 
@@ -735,14 +634,9 @@ async function handleFindMeetingRooms(args) {
         const explanation = isLikelyPersonal
           ? 'Meeting room search is M365-only. Personal Outlook.com accounts cannot use this feature — there are no rooms to find. Connect a Microsoft 365 work/school account to enable.'
           : 'This feature requires:\n- Places.Read.All permission\n- Meeting rooms configured in your organization';
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Unable to find meeting rooms.\n\n**Note**: ${explanation}\n\nError: ${errMsg}`,
-            },
-          ],
-        };
+        return toolError(
+          `Unable to find meeting rooms.\n\n**Note**: ${explanation}\n\nError: ${errMsg}`
+        );
       }
     }
 
@@ -843,23 +737,9 @@ async function handleFindMeetingRooms(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error finding meeting rooms: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error finding meeting rooms: ${error.message}`);
   }
 }
 
@@ -868,14 +748,8 @@ const advancedTools = [
   {
     name: 'access-shared-mailbox',
     description:
-      "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,
-      // openWorldHint: returns shared-mailbox messages authored by external
-      // senders. (#92)
-      openWorldHint: true,
-    },
+      "List emails or folders in a shared mailbox the signed-in user can access (read-only). Returns messages from `sharedMailbox` (alias `email`) and `folder` (default `inbox`) with id/subject/from/receivedDateTime/preview, the same shape as `search-emails` list mode. `folder` takes a well-known name (inbox, sent, archive…), a custom/localized display name (e.g. `Archiv`), a nested path (e.g. `Inbox/Vendors/Acme`), or pass a raw `folderId`. `listFolders: true` enumerates the shared mailbox's folder tree (names, paths, IDs, counts), to find custom subfolders before reading them. Needs the mailbox delegated to the signed-in user in Exchange (admin-configured). `outputVerbosity` sets field count and `count` (default 25, max 50) page size. For search and filters over a shared mailbox, use `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.",
+    ...toolMetadata('access-shared-mailbox', 'Shared Mailbox'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -901,7 +775,7 @@ const advancedTools = [
         listFolders: {
           type: 'boolean',
           description:
-            "Enumerate the shared mailbox's full folder tree (names, paths, IDs, item counts) instead of reading messages.",
+            "Enumerate the shared mailbox's full folder tree (names, paths, IDs, item counts) in place of reading messages.",
         },
         count: {
           type: 'number',
@@ -922,11 +796,7 @@ const advancedTools = [
     name: 'find-meeting-rooms',
     description:
       "Discover bookable meeting rooms in the user's organisation via the Graph rooms endpoint (read-only). Returns room resources with displayName, emailAddress, building, floor, capacity, and bookingType — suitable for piping into `create-event` as attendees. Filter by `query` (matches name/email), `building`, `floor`, or minimum `capacity`. Returns empty list on personal accounts (the rooms endpoint is M365-only). Use `outputVerbosity` to control field count.",
-    annotations: {
-      title: 'Meeting Rooms',
-      readOnlyHint: true,
-      openWorldHint: false,
-    },
+    ...toolMetadata('find-meeting-rooms', 'Meeting Rooms'),
     inputSchema: {
       type: 'object',
       properties: {

package/auth/auth-errors.js

@@ -86,4 +86,26 @@ function describeAuthError(input) {
   );
 }
 
-module.exports = { getAuthErrorHints, describeAuthError, AUTH_ERROR_HINTS };
+/**
+ * Short, PII-free label for the default log level (#278): `label` plus the
+ * first AADSTS code (or a network error code) found, never the description,
+ * which can carry the user's address.
+ * @param {string} label - e.g. 'refresh-failed'
+ * @param {Error|string|null|undefined} input
+ * @returns {string} - e.g. 'refresh-failed:AADSTS70008'
+ */
+function authErrorLogLabel(label, input) {
+  const aadsts = toMessage(input).match(/AADSTS\d+/);
+  if (aadsts) return `${label}:${aadsts[0]}`;
+  const code = input && input.code;
+  return typeof code === 'string' && /^[A-Z][A-Z_]{1,30}$/.test(code)
+    ? `${label}:${code}`
+    : label;
+}
+
+module.exports = {
+  getAuthErrorHints,
+  describeAuthError,
+  authErrorLogLabel,
+  AUTH_ERROR_HINTS,
+};

package/auth/client-config.js

@@ -0,0 +1,142 @@
+/**
+ * Runtime-supplied Azure Application (client) ID.
+ *
+ * Plugin marketplaces (GitHub Copilot, Cursor — Agent Plugins 1.0) ship a
+ * static `mcp.json` with no way to prompt for settings, so users there can't
+ * set OUTLOOK_CLIENT_ID. Device-code sign-in only needs the client ID (never
+ * the secret), so the `auth` tool accepts it at runtime and it's persisted to
+ * `~/.outlook-assistant-config.json`.
+ *
+ * Precedence: OUTLOOK_CLIENT_ID env → MS_CLIENT_ID env (legacy) → saved file.
+ *
+ * Deliberately does NOT require ../config (config.js requires this module).
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const CONFIG_FILE_NAME = '.outlook-assistant-config.json';
+
+// Azure Application (client) IDs are GUIDs.
+const CLIENT_ID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Path of the persisted config file. Resolved per call (not at load) so a
+ * changed HOME — e.g. in tests — is honoured.
+ * @returns {string}
+ */
+function getConfigPath() {
+  const homeDir = process.env.HOME || process.env.USERPROFILE || os.homedir();
+  return path.join(homeDir, CONFIG_FILE_NAME);
+}
+
+/**
+ * @param {unknown} id
+ * @returns {boolean} - true when `id` (trimmed) is a GUID
+ */
+function isValidClientId(id) {
+  return typeof id === 'string' && CLIENT_ID_RE.test(id.trim());
+}
+
+/**
+ * Read the whole config file. Never throws.
+ * @returns {object} - Parsed object, or {} when missing/unreadable/not an object
+ */
+function readConfigFile() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(getConfigPath(), 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? parsed
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The saved client ID, or '' when there is none or it isn't a valid GUID.
+ * Never throws.
+ * @returns {string}
+ */
+function loadSavedClientId() {
+  const { clientId } = readConfigFile();
+  return isValidClientId(clientId) ? clientId.trim() : '';
+}
+
+/**
+ * Validate and persist a client ID (mode 0600, temp file + rename), keeping
+ * any other keys already in the file.
+ * @param {string} id
+ * @returns {string} - The normalised (trimmed) ID that was saved
+ * @throws {Error} - When `id` isn't a GUID or the write fails
+ */
+function saveClientId(id) {
+  if (!isValidClientId(id)) {
+    throw new Error(
+      'Invalid client ID: expected the Application (client) ID GUID from your Azure app registration.'
+    );
+  }
+  const clientId = id.trim();
+  const filePath = getConfigPath();
+  const data = { ...readConfigFile(), clientId };
+  const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.writeFileSync(tmpPath, `${JSON.stringify(data, null, 2)}\n`, {
+      mode: 0o600,
+      flag: 'wx',
+    });
+    fs.renameSync(tmpPath, filePath);
+  } catch (error) {
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch {
+      // Temp file was never created or is already gone
+    }
+    throw error;
+  }
+  return clientId;
+}
+
+/**
+ * Which environment variable supplies the client ID, if any.
+ * @returns {{name: string, value: string}|null}
+ */
+function getEnvClientId() {
+  // Trimmed, and blank counts as unset: plugin managers pass "" (or stray
+  // whitespace) for an unset option, which must not hide a saved ID.
+  for (const name of ['OUTLOOK_CLIENT_ID', 'MS_CLIENT_ID']) {
+    const value = (process.env[name] || '').trim();
+    if (value) return { name, value };
+  }
+  return null;
+}
+
+/**
+ * Effective client ID: env (OUTLOOK_CLIENT_ID, then legacy MS_CLIENT_ID),
+ * then the saved file, then ''.
+ * @returns {string}
+ */
+function resolveClientId() {
+  const env = getEnvClientId();
+  return env ? env.value : loadSavedClientId();
+}
+
+/**
+ * @returns {'env'|'saved'|'none'} - Where the effective client ID comes from
+ */
+function getClientIdSource() {
+  if (getEnvClientId()) return 'env';
+  return loadSavedClientId() ? 'saved' : 'none';
+}
+
+module.exports = {
+  CONFIG_FILE_NAME,
+  getConfigPath,
+  isValidClientId,
+  loadSavedClientId,
+  saveClientId,
+  getEnvClientId,
+  resolveClientId,
+  getClientIdSource,
+};

package/auth/index.js

@@ -6,9 +6,11 @@ const TokenStorage = require('./token-storage');
 const config = require('../config');
 const { authTools, setToolCount } = require('./tools');
 
-// Singleton TokenStorage instance with auto-refresh support
+// Singleton TokenStorage instance with auto-refresh support. No clientId is
+// passed: TokenStorage resolves it on each use (env → saved config file), so
+// an ID saved at runtime via `auth action=authenticate clientId=…` applies
+// without a restart.
 const tokenStorage = new TokenStorage({
-  clientId: config.AUTH_CONFIG.clientId,
   clientSecret: config.AUTH_CONFIG.clientSecret,
   tokenStorePath: config.AUTH_CONFIG.tokenStorePath,
   scopes: config.AUTH_CONFIG.scopes,

package/auth/oauth-server.js

@@ -4,6 +4,9 @@ const _https = require('https'); // Reserved for future HTTPS support
 const _fs = require('fs'); // Reserved for future HTTPS support
 const crypto = require('crypto'); // Added for generating random string
 const TokenStorage = require('./token-storage'); // Assuming TokenStorage is in the same directory
+const { loadSavedClientId } = require('./client-config');
+const { authErrorLogLabel } = require('./auth-errors');
+const { log } = require('../utils/logger');
 
 // HTML templates
 function escapeHtml(unsafe) {
@@ -54,8 +57,11 @@ const templates = {
 
 function createAuthConfig(envPrefix = 'OUTLOOK_') {
   return {
+    // Env first; then the ID saved via `auth action=authenticate clientId=…`.
     clientId:
-      process.env[`${envPrefix}CLIENT_ID`] || process.env.MS_CLIENT_ID || '',
+      process.env[`${envPrefix}CLIENT_ID`] ||
+      process.env.MS_CLIENT_ID ||
+      loadSavedClientId(),
     clientSecret:
       process.env[`${envPrefix}CLIENT_SECRET`] ||
       process.env.MS_CLIENT_SECRET ||
@@ -193,7 +199,11 @@ function setupOAuthRoutes(
       await tokenStorage.exchangeCodeForTokens(code);
       res.send(templates.authSuccess);
     } catch (exchangeError) {
-      console.error('Token exchange error:', exchangeError);
+      log.note(
+        'auth',
+        authErrorLogLabel('token-exchange-failed', exchangeError)
+      );
+      log.debug('Token exchange error:', exchangeError);
       res.status(500).send(templates.tokenExchangeError(exchangeError));
     }
   });

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;
   }
 }