@littlebearapps/outlook-assistant 3.13.0 → 3.14.1

package/categories/index.js

@@ -6,6 +6,8 @@
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { buildMailboxPrefix } = require('../utils/mailbox');
+const { toolMetadata } = require('../utils/risk-classes');
+const { toolError, authRequiredError } = require('../utils/tool-error');
 
 // Category color presets (Outlook uses these names)
 const CATEGORY_COLORS = [
@@ -137,23 +139,9 @@ async function handleListCategories(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 listing categories: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error listing categories: ${error.message}`);
   }
 }
 
@@ -164,30 +152,18 @@ async function handleCreateCategory(args) {
   const { displayName, color } = args;
 
   if (!displayName) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Category name (displayName) is required.',
-        },
-      ],
-    };
+    return toolError('Category name (displayName) is required.');
   }
 
   // Validate color if provided
   if (color && !CATEGORY_COLORS.includes(color)) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Invalid color. Valid options: ${CATEGORY_COLORS.join(', ')}\n\nColor names: ${Object.entries(
-            COLOR_NAMES
-          )
-            .map(([k, v]) => `${k}=${v}`)
-            .join(', ')}`,
-        },
-      ],
-    };
+    return toolError(
+      `Invalid color. Valid options: ${CATEGORY_COLORS.join(', ')}\n\nColor names: ${Object.entries(
+        COLOR_NAMES
+      )
+        .map(([k, v]) => `${k}=${v}`)
+        .join(', ')}`
+    );
   }
 
   try {
@@ -220,35 +196,14 @@ async function handleCreateCategory(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('already exists')) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `A category named "${displayName}" already exists.`,
-          },
-        ],
-      };
+      return toolError(`A category named "${displayName}" already exists.`);
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error creating category: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error creating category: ${error.message}`);
   }
 }
 
@@ -261,37 +216,20 @@ async function handleUpdateCategory(args) {
   const { displayName, color } = args;
 
   if (!id) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Category ID is required. Use manage-category with action=list to find category IDs.',
-        },
-      ],
-    };
+    return toolError(
+      'Category ID is required. Use manage-category with action=list to find category IDs.'
+    );
   }
 
   if (!displayName && !color) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'At least one of displayName or color must be provided.',
-        },
-      ],
-    };
+    return toolError('At least one of displayName or color must be provided.');
   }
 
   // Validate color if provided
   if (color && !CATEGORY_COLORS.includes(color)) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Invalid color. Valid options: ${CATEGORY_COLORS.join(', ')}`,
-        },
-      ],
-    };
+    return toolError(
+      `Invalid color. Valid options: ${CATEGORY_COLORS.join(', ')}`
+    );
   }
 
   try {
@@ -343,23 +281,9 @@ async function handleUpdateCategory(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 updating category: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error updating category: ${error.message}`);
   }
 }
 
@@ -371,14 +295,9 @@ async function handleDeleteCategory(args) {
   const id = args.id || args.categoryId;
 
   if (!id) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Category ID is required. Use manage-category with action=list to find category IDs.',
-        },
-      ],
-    };
+    return toolError(
+      'Category ID is required. Use manage-category with action=list to find category IDs.'
+    );
   }
 
   try {
@@ -400,35 +319,16 @@ async function handleDeleteCategory(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('not found') || error.message.includes('404')) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Category not found. Use manage-category with action=list to see available categories.`,
-          },
-        ],
-      };
+      return toolError(
+        `Category not found. Use manage-category with action=list to see available categories.`
+      );
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error deleting category: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error deleting category: ${error.message}`);
   }
 }
 
@@ -443,39 +343,22 @@ async function handleApplyCategory(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.');
   }
 
   const applyAction = action || 'set'; // 'set', 'add', 'remove'
 
   if (!categories || !Array.isArray(categories)) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Categories array is required. Provide category display names.',
-        },
-      ],
-    };
+    return toolError(
+      'Categories array is required. Provide category display names.'
+    );
   }
 
   // Empty array is only valid for action=set (clears all categories)
   if (categories.length === 0 && applyAction !== 'set') {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Categories array cannot be empty for add/remove. Use action=set with an empty array to clear all categories.',
-        },
-      ],
-    };
+    return toolError(
+      'Categories array cannot be empty for add/remove. Use action=set with an empty array to clear all categories.'
+    );
   }
 
   try {
@@ -562,23 +445,9 @@ async function handleApplyCategory(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 applying categories: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error applying categories: ${error.message}`);
   }
 }
 
@@ -664,23 +533,9 @@ async function handleGetFocusedInboxOverrides(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 getting Focused Inbox overrides: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error getting Focused Inbox overrides: ${error.message}`);
   }
 }
 
@@ -693,26 +548,12 @@ async function handleSetFocusedInboxOverride(args) {
   const overrideAction = args.action;
 
   if (!emailAddress) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Email address is required.',
-        },
-      ],
-    };
+    return toolError('Email address is required.');
   }
 
   const classification = classifyAs || 'focused';
   if (!['focused', 'other'].includes(classification)) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: "classifyAs must be 'focused' or 'other'.",
-        },
-      ],
-    };
+    return toolError("classifyAs must be 'focused' or 'other'.");
   }
 
   try {
@@ -734,14 +575,7 @@ async function handleSetFocusedInboxOverride(args) {
     // Handle delete action
     if (overrideAction === 'delete') {
       if (!existing) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `No override found for ${emailAddress}.`,
-            },
-          ],
-        };
+        return toolError(`No override found for ${emailAddress}.`);
       }
 
       await callGraphAPI(
@@ -806,23 +640,9 @@ async function handleSetFocusedInboxOverride(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 Focused Inbox override: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error setting Focused Inbox override: ${error.message}`);
   }
 }
 
@@ -832,12 +652,7 @@ const categoriesTools = [
     name: 'manage-category',
     description:
       "Manage the user's master category list (the colour-coded labels available across mail/calendar/contacts). action=`list` (default) returns categories with id/displayName/color. action=`create` adds a new category — `displayName` required, `color` optional (preset0-preset24, e.g. preset0=Red, preset7=Blue). action=`update` (alias `set` — deprecated) changes name/colour by `id`. action=`delete` removes a category — this does NOT untag messages already labelled with it; existing messages retain the orphaned label until manually cleaned. Use `apply-category` to tag/untag specific messages.",
-    annotations: {
-      title: 'Master Categories',
-      readOnlyHint: false,
-      destructiveHint: false,
-      openWorldHint: false,
-    },
+    ...toolMetadata('manage-category', 'Master Categories'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -884,7 +699,15 @@ const categoriesTools = [
       switch (action) {
         case 'create':
           return handleCreateCategory(args);
-        case 'set': // deprecated alias
+        case 'set': {
+          // Deprecated alias: works, but say so (#306).
+          const result = await handleUpdateCategory(args);
+          if (!result.isError && result.content?.[0]?.text) {
+            result.content[0].text +=
+              '\n\nNote: action=`set` is a deprecated alias for `update`; use `update`.';
+          }
+          return result;
+        }
         case 'update':
           return handleUpdateCategory(args);
         case 'delete':
@@ -892,27 +715,17 @@ const categoriesTools = [
         case 'list':
           return handleListCategories(args);
         default:
-          return {
-            content: [
-              {
-                type: 'text',
-                text: `Unknown action '${action}'. Valid actions: list, create, update, delete.`,
-              },
-            ],
-          };
+          return toolError(
+            `Unknown action '${action}'. Valid actions: list, create, update, delete.`
+          );
       }
     },
   },
   {
     name: 'apply-category',
     description:
-      "Tag or untag email messages with master categories (those created via `manage-category`). action=`set` (default) replaces the message's category set with the supplied `categories` array. action=`add` appends categories to whatever's already on the message. action=`remove` removes only the named categories, leaving the rest. Accepts either `messageId` (single) or `messageIds` (batch via Graph `$batch`). `categories` are matched by display name — names must already exist in the target mailbox's master list. For your own mailbox, create them via `manage-category` first; for a shared mailbox, the names must already exist there (`manage-category` only manages the signed-in account's master list). Pass `sharedMailbox` (or alias `email`) to categorise messages in a shared/delegated mailbox instead of the signed-in account (requires Mail.ReadWrite.Shared + delegate access). Returns per-message confirmation.",
-    annotations: {
-      title: 'Apply Categories',
-      readOnlyHint: false,
-      destructiveHint: false,
-      openWorldHint: false,
-    },
+      "Tag or untag email messages with master categories (those created via `manage-category`). action=`set` (default) replaces the message's category set with the supplied `categories` array. action=`add` appends categories to whatever's already on the message. action=`remove` removes only the named categories, leaving the rest. Accepts either `messageId` (single) or `messageIds` (batch: one request per message). `categories` are matched by display name — names must already exist in the target mailbox's master list. For your own mailbox, create them via `manage-category` first; for a shared mailbox, the names must already exist there (`manage-category` only manages the signed-in account's master list). Pass `sharedMailbox` (or alias `email`) to categorise messages in a shared/delegated mailbox (default: the signed-in account; requires Mail.ReadWrite.Shared + delegate access). Returns per-message confirmation.",
+    ...toolMetadata('apply-category', 'Apply Categories'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -939,7 +752,7 @@ const categoriesTools = [
         sharedMailbox: {
           type: 'string',
           description:
-            'Email address of a shared/delegated mailbox whose messages to categorise instead of the signed-in account. Requires delegate access + Mail.ReadWrite.Shared. Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).',
+            'Email address of the shared/delegated mailbox whose messages to categorise (default: the signed-in account). Requires delegate access + Mail.ReadWrite.Shared. Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).',
         },
         email: {
           type: 'string',
@@ -955,12 +768,7 @@ const categoriesTools = [
     name: 'manage-focused-inbox',
     description:
       'Manage Focused Inbox sender overrides — explicit rules that force messages from a given sender into Focused or Other regardless of the ML classifier. action=`list` (default) returns existing overrides with id/sender/classifyAs. action=`set` creates or updates an override for `emailAddress` (optional `name`), routing future mail to `focused` (default) or `other`. action=`delete` removes the override for `emailAddress`. Note: this only works on accounts that have Focused Inbox enabled — personal Outlook.com accounts without it return an empty list.',
-    annotations: {
-      title: 'Focused Inbox',
-      readOnlyHint: false,
-      destructiveHint: false,
-      openWorldHint: false,
-    },
+    ...toolMetadata('manage-focused-inbox', 'Focused Inbox'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -1004,14 +812,9 @@ const categoriesTools = [
         case 'list':
           return handleGetFocusedInboxOverrides(args);
         default:
-          return {
-            content: [
-              {
-                type: 'text',
-                text: `Unknown action '${action}'. Valid actions: list, set, delete.`,
-              },
-            ],
-          };
+          return toolError(
+            `Unknown action '${action}'. Valid actions: list, set, delete.`
+          );
       }
     },
   },

package/config.js

@@ -15,6 +15,7 @@ const {
 } = require('./utils/field-presets');
 const { VERBOSITY, DEFAULT_LIMITS } = require('./utils/response-formatter');
 const { resolveClientId } = require('./auth/client-config');
+const { redact } = require('./utils/logger');
 
 // Ensure we have a home directory path — never fall back to /tmp (world-readable)
 const homeDir = process.env.HOME || process.env.USERPROFILE || os.homedir();
@@ -90,7 +91,8 @@ function parseSharedMailboxMode(raw) {
   if (['true', 'readwrite', '1'].includes(value)) return 'readwrite';
   if (value && !['false', '0', 'off', 'no'].includes(value)) {
     console.warn(
-      `[outlook-assistant] OUTLOOK_SHARED_MAILBOX="${raw}" is not a recognised value. ` +
+      // redact(): people sometimes put the shared mailbox's address here.
+      `[outlook-assistant] OUTLOOK_SHARED_MAILBOX="${redact(raw)}" is not a recognised value. ` +
         'Expected read, true/readwrite/1, or unset. Shared-mailbox support stays off.'
     );
   }
@@ -124,6 +126,27 @@ const BASE_SCOPES = [
   // 'Place.Read.All',     // find-meeting-rooms tool
 ];
 
+/**
+ * Parse OUTLOOK_READ_ONLY. On: true/1/yes/on; off: unset, empty,
+ * false/0/no/off (any case). Anything else fails closed (read-only on, with
+ * a warning), because whoever set the variable meant to restrict the server.
+ * @param {string|undefined} raw
+ * @returns {boolean}
+ */
+function parseReadOnly(raw) {
+  const value = String(raw ?? '')
+    .trim()
+    .toLowerCase();
+  if (['true', '1', 'yes', 'on'].includes(value)) return true;
+  if (['', 'false', '0', 'no', 'off'].includes(value)) return false;
+  // Redacted and capped: the value is echoed only to spot a typo.
+  console.warn(
+    `[outlook-assistant] OUTLOOK_READ_ONLY="${redact(String(raw).slice(0, 40))}" is not a recognised value. ` +
+      'Expected true, 1, yes or on to switch it on, or false, 0, no or off (or unset) to switch it off. Treating it as on: read-only mode is on.'
+  );
+  return true;
+}
+
 const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
 
 /**
@@ -155,6 +178,11 @@ module.exports = {
   // Test mode setting
   USE_TEST_MODE: process.env.USE_TEST_MODE === 'true',
 
+  // Read-only mode (OUTLOOK_READ_ONLY, #271): every tool call that isn't
+  // classified `read` in utils/risk-classes.js is refused before it runs.
+  READ_ONLY: parseReadOnly(process.env.OUTLOOK_READ_ONLY),
+  parseReadOnly,
+
   // OAuth scope sets (exported so tests + the fallback logic can reference them)
   BASE_SCOPES,
   // `.Shared` scopes requested at sign-in for the configured mode ([] = off)