@littlebearapps/outlook-assistant 3.12.1 → 3.14.0

package/rules/create.js

@@ -3,16 +3,17 @@
  */
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
-const { checkRateLimit } = require('../utils/safety');
-const { formatRuleDryRunPreview } = require('../utils/safety');
+const { checkRateLimit, formatRuleDryRunPreview } = require('../utils/safety');
 const { getInboxRules } = require('./list');
 const {
   buildConditions,
   buildActions,
   buildExceptions,
+  checkRuleRecipients,
   hasAnyCondition,
   hasAnyAction,
 } = require('./rule-builder');
+const { toolError, authRequiredError } = require('../utils/tool-error');
 
 /**
  * Create rule handler
@@ -22,55 +23,31 @@ const {
 async function handleCreateRule(args) {
   const { name, isEnabled = true, sequence, dryRun } = args;
 
-  // Rate limit rule creation
-  const rateLimitError = checkRateLimit('manage-rules');
-  if (rateLimitError) return rateLimitError;
-
   // Validate sequence parameter
   if (sequence !== undefined && (isNaN(sequence) || sequence < 1)) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Sequence must be a positive number greater than zero.',
-        },
-      ],
-    };
+    return toolError('Sequence must be a positive number greater than zero.');
   }
 
   if (!name) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Rule name is required.',
-        },
-      ],
-    };
+    return toolError('Rule name is required.');
   }
 
   if (!hasAnyCondition(args)) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'At least one condition is required. Available conditions: fromAddresses, containsSubject, bodyContains, bodyOrSubjectContains, senderContains, recipientContains, sentToAddresses, hasAttachments, importance, sensitivity, sentToMe, sentOnlyToMe, sentCcMe, isAutomaticReply.',
-        },
-      ],
-    };
+    return toolError(
+      'At least one condition is required. Available conditions: fromAddresses, containsSubject, bodyContains, bodyOrSubjectContains, senderContains, recipientContains, sentToAddresses, hasAttachments, importance, sensitivity, sentToMe, sentOnlyToMe, sentCcMe, isAutomaticReply.'
+    );
   }
 
   if (!hasAnyAction(args)) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'At least one action is required. Available actions: moveToFolder, copyToFolder, markAsRead, markImportance, forwardTo, redirectTo, assignCategories, stopProcessingRules, deleteMessage.',
-        },
-      ],
-    };
+    return toolError(
+      'At least one action is required. Available actions: moveToFolder, copyToFolder, markAsRead, markImportance, forwardTo, redirectTo, assignCategories, stopProcessingRules, deleteMessage.'
+    );
   }
 
+  // Refuse the whole rule if the allowlist blocks any forwarding (#273)
+  const recipientError = checkRuleRecipients(args, { dryRun });
+  if (recipientError) return recipientError;
+
   try {
     const accessToken = await ensureAuthenticated();
 
@@ -87,14 +64,9 @@ async function handleCreateRule(args) {
     // Check for fatal warnings (folder not found = no valid action)
     const folderNotFound = actWarnings.some((w) => w.includes('not found'));
     if (folderNotFound && Object.keys(actions).length === 0) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: actWarnings.filter((w) => w.includes('not found')).join('\n'),
-          },
-        ],
-      };
+      return toolError(
+        actWarnings.filter((w) => w.includes('not found')).join('\n')
+      );
     }
 
     // Determine sequence
@@ -141,6 +113,10 @@ async function handleCreateRule(args) {
       };
     }
 
+    // Rate limit only real writes, so a dry run never uses up a slot (#273)
+    const rateLimitError = checkRateLimit('manage-rules');
+    if (rateLimitError) return rateLimitError;
+
     // Create the rule
     const response = await callGraphAPI(
       accessToken,
@@ -167,34 +143,15 @@ async function handleCreateRule(args) {
       };
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: "Failed to create rule. The server didn't return a rule ID.",
-        },
-      ],
-    };
+    return toolError(
+      "Failed to create rule. The server didn't return a rule ID."
+    );
   } 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 creating rule: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error creating rule: ${error.message}`);
   }
 }
 

package/rules/index.js

@@ -7,6 +7,8 @@ const handleUpdateRule = require('./update');
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { checkRateLimit } = require('../utils/safety');
+const { toolMetadata } = require('../utils/risk-classes');
+const { toolError, authRequiredError } = require('../utils/tool-error');
 
 /**
  * Delete rule handler
@@ -16,19 +18,8 @@ const { checkRateLimit } = require('../utils/safety');
 async function handleDeleteRule(args) {
   const { ruleName, ruleId } = args;
 
-  // Rate limit
-  const rateLimitError = checkRateLimit('manage-rules');
-  if (rateLimitError) return rateLimitError;
-
   if (!ruleName && !ruleId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Either ruleName or ruleId is required.',
-        },
-      ],
-    };
+    return toolError('Either ruleName or ruleId is required.');
   }
 
   try {
@@ -42,19 +33,17 @@ async function handleDeleteRule(args) {
       const rules = await getInboxRules(accessToken);
       const rule = rules.find((r) => r.displayName === ruleName);
       if (!rule) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Rule with name "${ruleName}" not found.`,
-            },
-          ],
-        };
+        return toolError(`Rule with name "${ruleName}" not found.`);
       }
       resolvedId = rule.id;
       displayName = ruleName;
     }
 
+    // Checked only once there is a rule to delete, so a bad call doesn't
+    // use up a slot (#279)
+    const rateLimitError = checkRateLimit('manage-rules');
+    if (rateLimitError) return rateLimitError;
+
     await callGraphAPI(
       accessToken,
       'DELETE',
@@ -71,23 +60,9 @@ async function handleDeleteRule(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 deleting rule: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error deleting rule: ${error.message}`);
   }
 }
 
@@ -100,25 +75,15 @@ async function handleEditRuleSequence(args) {
   const { ruleName, sequence } = args;
 
   if (!ruleName) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Rule name is required. Please specify the exact name of an existing rule.',
-        },
-      ],
-    };
+    return toolError(
+      'Rule name is required. Please specify the exact name of an existing rule.'
+    );
   }
 
   if (!sequence || isNaN(sequence) || sequence < 1) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'A positive sequence number is required. Lower numbers run first (higher priority).',
-        },
-      ],
-    };
+    return toolError(
+      'A positive sequence number is required. Lower numbers run first (higher priority).'
+    );
   }
 
   try {
@@ -127,16 +92,13 @@ async function handleEditRuleSequence(args) {
 
     const rule = rules.find((r) => r.displayName === ruleName);
     if (!rule) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Rule with name "${ruleName}" not found.`,
-          },
-        ],
-      };
+      return toolError(`Rule with name "${ruleName}" not found.`);
     }
 
+    // Reordering is a write, so it shares the manage-rules limit (#273)
+    const rateLimitError = checkRateLimit('manage-rules');
+    if (rateLimitError) return rateLimitError;
+
     await callGraphAPI(
       accessToken,
       'PATCH',
@@ -154,24 +116,10 @@ async function handleEditRuleSequence(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 rule sequence: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error updating rule sequence: ${error.message}`);
   }
 }
 
@@ -180,13 +128,8 @@ const rulesTools = [
   {
     name: 'manage-rules',
     description:
-      'Server-side inbox rule CRUD (destructive: covers `delete`; supports `dryRun` on create/update for preview). Rules run on the Exchange server regardless of which client is open. action=`list` (default) returns rules with id/name/sequence — pass `includeDetails: true` to expand conditions/actions/exceptions. action=`create` builds a new rule from condition params (12 supported: fromAddresses, containsSubject, bodyContains, hasAttachments, importance, sentTo, sensitivity, etc.), action params (9 supported: moveToFolder/copyToFolder — folder name, nested path like `Triage/Delete`, or ID — forwardTo, redirectTo, assignCategories, markAsRead, delete, etc.), and optional `except*` exceptions. action=`update` patches the named fields by `ruleId`. action=`reorder` changes execution priority via `sequence` (lower = earlier). action=`delete` removes a rule. Recipient allowlist applies to forwardTo/redirectTo. `permanentDelete` action is intentionally omitted (too dangerous for AI use — use the Outlook UI). Subject to session rate limits (`OUTLOOK_MAX_MANAGE_RULES_PER_SESSION`).',
-    annotations: {
-      title: 'Inbox Rules',
-      readOnlyHint: false,
-      destructiveHint: true,
-      openWorldHint: false,
-    },
+      'Server-side inbox rules (destructive: covers `delete`; `dryRun` previews create/update). Rules run on the Exchange server whichever client is open. action=`list` (default) returns rules with id/name/sequence; `includeDetails: true` adds conditions/actions/exceptions. action=`create` builds a rule from condition params (12, e.g. fromAddresses, containsSubject, bodyContains, hasAttachments, importance, sentTo, sensitivity), action params (9, e.g. moveToFolder/copyToFolder — folder name, nested path like `Triage/Delete`, or ID — forwardTo, redirectTo, assignCategories, markAsRead, delete) and optional `except*` exceptions. action=`update` patches fields by `ruleId` or `ruleName`. action=`reorder` changes priority via `sequence` (lower runs first). action=`delete` removes a rule. The recipient allowlist applies to forwardTo/redirectTo. There is deliberately no `permanentDelete` action (too dangerous for AI use; use the Outlook UI). Subject to session rate limits (`OUTLOOK_MAX_MANAGE_RULES_PER_SESSION`).',
+    ...toolMetadata('manage-rules', 'Inbox Rules'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -217,7 +160,7 @@ const rulesTools = [
         dryRun: {
           type: 'boolean',
           description:
-            'Preview rule without creating/updating (action=create, action=update)',
+            'Preview only (action=create or update): shows the rule without creating or changing it. Other actions refuse dryRun and change nothing. Default false.',
         },
         isEnabled: {
           type: 'boolean',
@@ -404,14 +347,9 @@ const rulesTools = [
         case 'list':
           return handleListRules(args);
         default:
-          return {
-            content: [
-              {
-                type: 'text',
-                text: `Unknown action '${action}'. Valid actions: list, create, update, reorder, delete.`,
-              },
-            ],
-          };
+          return toolError(
+            `Unknown action '${action}'. Valid actions: list, create, update, reorder, delete.`
+          );
       }
     },
   },

package/rules/list.js

@@ -3,6 +3,8 @@
  */
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { log } = require('../utils/logger');
 
 /**
  * List rules handler
@@ -27,24 +29,10 @@ async function handleListRules(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 rules: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error listing rules: ${error.message}`);
   }
 }
 
@@ -64,7 +52,7 @@ async function getInboxRules(accessToken) {
 
     return response.value || [];
   } catch (error) {
-    console.error(`Error getting inbox rules: ${error.message}`);
+    log.debug(`Error getting inbox rules: ${error.message}`);
     throw error;
   }
 }

package/rules/rule-builder.js

@@ -4,6 +4,7 @@
  */
 const { resolveFolder, looksLikeFolderId } = require('../folder/resolve');
 const { checkRecipientAllowlist } = require('../utils/safety');
+const { toolError } = require('../utils/tool-error');
 
 const VALID_IMPORTANCE = ['low', 'normal', 'high'];
 const VALID_SENSITIVITY = ['normal', 'personal', 'private', 'confidential'];
@@ -197,38 +198,35 @@ async function buildActions(args, accessToken) {
     }
   }
 
-  // Recipient-based actions (comma-separated emails → recipient objects)
+  // Recipient-based actions (comma-separated emails → recipient objects).
+  // create/update refuse blocked recipients up front (checkRuleRecipients);
+  // this is the backstop, so a blocked forward is never silently dropped.
   if (args.forwardTo) {
     const recipients = formatRecipientObjects(args.forwardTo);
     if (recipients.length > 0) {
-      // Check allowlist if configured
-      const allowlistError = checkRecipientAllowlist(recipients);
-      if (allowlistError) {
-        warnings.push(
-          `Forward recipients blocked by allowlist: ${args.forwardTo}`
-        );
-      } else {
-        actions.forwardTo = recipients;
-        warnings.push(
-          `This rule will forward all matching emails to: ${args.forwardTo}. Verify these addresses are correct.`
+      if (checkRecipientAllowlist(recipients)) {
+        throw new Error(
+          `forwardTo recipients blocked by OUTLOOK_ALLOWED_RECIPIENTS: ${args.forwardTo}`
         );
       }
+      actions.forwardTo = recipients;
+      warnings.push(
+        `This rule will forward all matching emails to: ${args.forwardTo}. Verify these addresses are correct.`
+      );
     }
   }
   if (args.redirectTo) {
     const recipients = formatRecipientObjects(args.redirectTo);
     if (recipients.length > 0) {
-      const allowlistError = checkRecipientAllowlist(recipients);
-      if (allowlistError) {
-        warnings.push(
-          `Redirect recipients blocked by allowlist: ${args.redirectTo}`
-        );
-      } else {
-        actions.redirectTo = recipients;
-        warnings.push(
-          `This rule will redirect all matching emails to: ${args.redirectTo}. The original sender will appear as the sender.`
+      if (checkRecipientAllowlist(recipients)) {
+        throw new Error(
+          `redirectTo recipients blocked by OUTLOOK_ALLOWED_RECIPIENTS: ${args.redirectTo}`
         );
       }
+      actions.redirectTo = recipients;
+      warnings.push(
+        `This rule will redirect all matching emails to: ${args.redirectTo}. The original sender will appear as the sender.`
+      );
     }
   }
 
@@ -240,6 +238,44 @@ async function buildActions(args, accessToken) {
   return { actions, warnings };
 }
 
+/** Rule actions that send matching mail to other people. */
+const RECIPIENT_ACTIONS = ['forwardTo', 'redirectTo'];
+
+/**
+ * Refuse a rule whose forwardTo/redirectTo includes an address that
+ * OUTLOOK_ALLOWED_RECIPIENTS blocks. The whole rule (or update) is refused,
+ * never saved with the blocked forwarding dropped, and a dry run reports the
+ * refusal too. Needs no Graph call, so it runs before sign-in. (#273)
+ * @param {object} args - Tool arguments
+ * @param {{operation?: 'create'|'update', dryRun?: boolean}} [options]
+ * @returns {object|null} - toolError naming the blocked addresses, or null
+ */
+function checkRuleRecipients(args, { operation = 'create', dryRun } = {}) {
+  const blocked = [];
+  for (const param of RECIPIENT_ACTIONS) {
+    const addresses = formatRecipientObjects(args[param])
+      .filter((recipient) => checkRecipientAllowlist([recipient]))
+      .map((recipient) => recipient.emailAddress.address);
+    if (addresses.length > 0) {
+      blocked.push(`${param}: ${addresses.join(', ')}`);
+    }
+  }
+  if (blocked.length === 0) return null;
+
+  const subject = operation === 'update' ? 'Rule update' : 'Rule';
+  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 ${blocked.join('; ')}. Nothing was ${outcome}; a rule is refused whole rather than saved without the blocked forwarding.`,
+    {
+      nextStep:
+        'Remove the blocked addresses from forwardTo/redirectTo and retry, or ask the user to add them to OUTLOOK_ALLOWED_RECIPIENTS in the server configuration and restart the server.',
+    }
+  );
+}
+
 /**
  * Build a Graph API exceptions object from except* prefixed parameters.
  * @param {object} args - Tool arguments
@@ -324,6 +360,7 @@ module.exports = {
   buildConditions,
   buildActions,
   buildExceptions,
+  checkRuleRecipients,
   hasAnyCondition,
   hasAnyAction,
 };

package/rules/update.js

@@ -9,7 +9,9 @@ const {
   buildConditions,
   buildActions,
   buildExceptions,
+  checkRuleRecipients,
 } = require('./rule-builder');
+const { toolError, authRequiredError } = require('../utils/tool-error');
 
 /**
  * Update rule handler — modify an existing rule by name or ID.
@@ -20,32 +22,23 @@ const {
 async function handleUpdateRule(args) {
   const { ruleName, ruleId, name, isEnabled, sequence, dryRun } = args;
 
-  // Rate limit
-  const rateLimitError = checkRateLimit('manage-rules');
-  if (rateLimitError) return rateLimitError;
-
   if (!ruleName && !ruleId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Either ruleName or ruleId is required to identify the rule to update.',
-        },
-      ],
-    };
+    return toolError(
+      'Either ruleName or ruleId is required to identify the rule to update.'
+    );
   }
 
   if (sequence !== undefined && (isNaN(sequence) || sequence < 1)) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Sequence must be a positive number greater than zero.',
-        },
-      ],
-    };
+    return toolError('Sequence must be a positive number greater than zero.');
   }
 
+  // Refuse the whole update if the allowlist blocks any forwarding (#273)
+  const recipientError = checkRuleRecipients(args, {
+    operation: 'update',
+    dryRun,
+  });
+  if (recipientError) return recipientError;
+
   try {
     const accessToken = await ensureAuthenticated();
 
@@ -63,14 +56,7 @@ async function handleUpdateRule(args) {
     }
 
     if (!currentRule) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Rule "${ruleName || ruleId}" not found.`,
-          },
-        ],
-      };
+      return toolError(`Rule "${ruleName || ruleId}" not found.`);
     }
 
     // Build PATCH payload — only include fields the user provided
@@ -107,14 +93,9 @@ async function handleUpdateRule(args) {
     // Check for fatal folder-not-found
     const folderNotFound = actWarnings.some((w) => w.includes('not found'));
     if (folderNotFound && Object.keys(actions).length === 0) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: actWarnings.filter((w) => w.includes('not found')).join('\n'),
-          },
-        ],
-      };
+      return toolError(
+        actWarnings.filter((w) => w.includes('not found')).join('\n')
+      );
     }
 
     // Build exceptions if any except* param was provided
@@ -126,14 +107,9 @@ async function handleUpdateRule(args) {
 
     // Check that something is actually being changed
     if (Object.keys(patch).length === 0) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `No changes specified for rule "${currentRule.displayName}". Provide at least one parameter to update (name, isEnabled, sequence, conditions, actions, or exceptions).`,
-          },
-        ],
-      };
+      return toolError(
+        `No changes specified for rule "${currentRule.displayName}". Provide at least one parameter to update (name, isEnabled, sequence, conditions, actions, or exceptions).`
+      );
     }
 
     // Dry-run: show before/after preview
@@ -153,6 +129,10 @@ async function handleUpdateRule(args) {
       };
     }
 
+    // Rate limit only real writes, so a dry run never uses up a slot (#273)
+    const rateLimitError = checkRateLimit('manage-rules');
+    if (rateLimitError) return rateLimitError;
+
     // Execute PATCH
     await callGraphAPI(
       accessToken,
@@ -197,24 +177,10 @@ async function handleUpdateRule(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 rule: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error updating rule: ${error.message}`);
   }
 }