@littlebearapps/outlook-assistant 3.13.0 → 3.14.1

package/email/draft.js

@@ -8,10 +8,14 @@ const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const {
   checkRateLimit,
+  releaseRateLimit,
   checkRecipientAllowlist,
+  findBlockedRecipients,
+  getRecipientAllowlist,
   formatDryRunPreview,
 } = require('../utils/safety');
 const { handleGetMailTips } = require('./mail-tips');
+const { toolError, authRequiredError } = require('../utils/tool-error');
 
 /**
  * Format comma-separated email string into Graph API recipient objects
@@ -25,6 +29,18 @@ function formatRecipients(recipientString) {
   }));
 }
 
+/** Graph fields holding a message's recipients. */
+const RECIPIENT_FIELDS = ['toRecipients', 'ccRecipients', 'bccRecipients'];
+
+/**
+ * Every to/cc/bcc recipient on a Graph message.
+ * @param {object} message - Graph message
+ * @returns {Array<{emailAddress: {address: string}}>}
+ */
+function recipientsOf(message) {
+  return RECIPIENT_FIELDS.flatMap((field) => message?.[field] || []);
+}
+
 /**
  * Auto-detect HTML vs plain text body
  * @param {string} body - Email body content
@@ -71,7 +87,7 @@ function buildMessageObject(args) {
 /**
  * Format a draft response with key details
  * @param {object} draft - Graph API message response
- * @param {string} actionLabel - Human-readable action (e.g. "created", "updated")
+ * @param {string} actionLabel - Heading, e.g. "Draft created" or "Reply draft created"
  * @returns {object} - MCP response
  */
 function formatDraftResponse(draft, actionLabel) {
@@ -79,7 +95,7 @@ function formatDraftResponse(draft, actionLabel) {
     .map((r) => r.emailAddress?.address)
     .join(', ');
 
-  let text = `Draft ${actionLabel}.\n\n`;
+  let text = `${actionLabel}.\n\n`;
   text += `**ID**: \`${draft.id}\`\n`;
   if (draft.subject) text += `**Subject**: ${draft.subject}\n`;
   if (to) text += `**To**: ${to}\n`;
@@ -108,9 +124,11 @@ class DraftGuardError extends Error {}
  * @param {string} accessToken - Graph access token
  * @param {string} id - Message id the caller passed as the draft id
  * @param {string} action - The draft action being guarded (for the message)
+ * @param {string[]} [extraFields] - Further fields to fetch in the same GET
+ * @returns {Promise<object>} The draft, with id, isDraft, subject and extraFields
  * @throws {DraftGuardError} If the id is not a draft or does not exist
  */
-async function assertIsDraft(accessToken, id, action) {
+async function assertIsDraft(accessToken, id, action, extraFields = []) {
   let message;
   try {
     message = await callGraphAPI(
@@ -119,7 +137,7 @@ async function assertIsDraft(accessToken, id, action) {
       `me/messages/${id}`,
       null,
       {
-        $select: 'id,isDraft,subject',
+        $select: ['id', 'isDraft', 'subject', ...extraFields].join(','),
       }
     );
   } catch (error) {
@@ -137,6 +155,7 @@ async function assertIsDraft(accessToken, id, action) {
       `Message \`${id}\`${subject} is not a draft, so draft action=${action} refused it and nothing was changed. update/send/delete only act on unsent drafts.`
     );
   }
+  return message;
 }
 
 /**
@@ -148,14 +167,9 @@ async function handleDraft(args) {
   const { action } = args;
 
   if (!action) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: "Action is required. Use 'create', 'update', 'send', 'delete', 'reply', 'reply-all', or 'forward'.",
-        },
-      ],
-    };
+    return toolError(
+      "Action is required. Use 'create', 'update', 'send', 'delete', 'reply', 'reply-all', or 'forward'."
+    );
   }
 
   switch (action) {
@@ -174,14 +188,9 @@ async function handleDraft(args) {
     case 'forward':
       return handleForwardDraft(args);
     default:
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Invalid action '${action}'. Use 'create', 'update', 'send', 'delete', 'reply', 'reply-all', or 'forward'.`,
-          },
-        ],
-      };
+      return toolError(
+        `Invalid action '${action}'. Use 'create', 'update', 'send', 'delete', 'reply', 'reply-all', or 'forward'.`
+      );
   }
 }
 
@@ -203,14 +212,16 @@ async function handleCreateDraft(args) {
     if (allowlistError) return allowlistError;
   }
 
-  // Pre-save recipient validation via mail-tips
+  // Pre-save recipient validation via mail-tips. The tips are returned
+  // with the result, never added to the draft payload (#272).
+  let tipsResult = null;
   if (doCheckRecipients && allRecipients.length > 0) {
     const allAddresses = allRecipients.map((r) => r.emailAddress.address);
-    const tipsResult = await handleGetMailTips({ recipients: allAddresses });
+    tipsResult = await handleGetMailTips({ recipients: allAddresses });
     const tipsText = tipsResult.content[0]?.text || '';
 
     if (dryRun) {
-      const preview = formatDryRunPreview({ message, saveToSentItems: true });
+      const preview = formatDryRunPreview({ message, isDraft: true });
       return {
         content: [
           {
@@ -228,7 +239,7 @@ async function handleCreateDraft(args) {
 
   // Dry-run mode: preview without saving
   if (dryRun) {
-    const preview = formatDryRunPreview({ message, saveToSentItems: true });
+    const preview = formatDryRunPreview({ message, isDraft: true });
     return {
       content: [
         {
@@ -254,7 +265,12 @@ async function handleCreateDraft(args) {
       'me/messages',
       message
     );
-    return formatDraftResponse(draft, 'created');
+    const response = formatDraftResponse(draft, 'Draft created');
+    if (tipsResult) {
+      response.content[0].text += `\n---\n\n${tipsResult.content[0]?.text || ''}`;
+      response._meta.mailTips = tipsResult._meta;
+    }
+    return response;
   } catch (error) {
     return handleError('creating draft', error);
   }
@@ -267,11 +283,7 @@ async function handleUpdateDraft(args) {
   const { id } = args;
 
   if (!id) {
-    return {
-      content: [
-        { type: 'text', text: 'Draft ID (id) is required for update.' },
-      ],
-    };
+    return toolError('Draft ID (id) is required for update.');
   }
 
   const message = buildMessageObject(args);
@@ -301,7 +313,7 @@ async function handleUpdateDraft(args) {
       `me/messages/${id}`,
       message
     );
-    return formatDraftResponse(draft, 'updated');
+    return formatDraftResponse(draft, 'Draft updated');
   } catch (error) {
     return handleError('updating draft', error);
   }
@@ -314,14 +326,29 @@ async function handleSendDraft(args) {
   const { id } = args;
 
   if (!id) {
-    return {
-      content: [{ type: 'text', text: 'Draft ID (id) is required for send.' }],
-    };
+    return toolError('Draft ID (id) is required for send.');
   }
 
   try {
     const accessToken = await ensureAuthenticated();
-    await assertIsDraft(accessToken, id, 'send');
+    // Fetch the recipients as they are now: the draft may have been edited
+    // (here or in Outlook) since it was created.
+    const draft = await assertIsDraft(
+      accessToken,
+      id,
+      'send',
+      RECIPIENT_FIELDS
+    );
+    const blocked = findBlockedRecipients(recipientsOf(draft));
+    if (blocked) {
+      return toolError(
+        `Draft not sent: it is addressed to ${blocked.blocked.join(', ')}, which OUTLOOK_ALLOWED_RECIPIENTS does not allow (allowed recipients/domains: ${blocked.allowed.join(', ')}). The draft is unchanged and still in Drafts.`,
+        {
+          nextStep:
+            'Remove those recipients from the draft (in Outlook, or with draft action=update), or ask the user to add them to OUTLOOK_ALLOWED_RECIPIENTS.',
+        }
+      );
+    }
 
     // Rate limit via send-email counter (shares limit with direct sends)
     const rateLimitError = checkRateLimit('send-email');
@@ -348,11 +375,7 @@ async function handleDeleteDraft(args) {
   const { id } = args;
 
   if (!id) {
-    return {
-      content: [
-        { type: 'text', text: 'Draft ID (id) is required for delete.' },
-      ],
-    };
+    return toolError('Draft ID (id) is required for delete.');
   }
 
   try {
@@ -379,25 +402,15 @@ async function handleReplyDraft(args, endpoint) {
   const { id, body, comment } = args;
 
   if (!id) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Message ID (id) is required for ${endpoint === 'createReplyAll' ? 'reply-all' : 'reply'}.`,
-        },
-      ],
-    };
+    return toolError(
+      `Message ID (id) is required for ${endpoint === 'createReplyAll' ? 'reply-all' : 'reply'}.`
+    );
   }
 
   if (comment && body) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Cannot use both comment and body. Use comment for a short prepended note, or body for full HTML/text content.',
-        },
-      ],
-    };
+    return toolError(
+      'Cannot use both comment and body. Use comment for a short prepended note, or body for full HTML/text content.'
+    );
   }
 
   const requestBody = {};
@@ -412,25 +425,106 @@ async function handleReplyDraft(args, endpoint) {
     };
   }
 
+  const actionName = endpoint === 'createReplyAll' ? 'reply-all' : 'reply';
+
+  // Taken before the draft is created, and given back only when nothing is
+  // definitely left behind (#299): Graph rejected the create with a 4xx, or
+  // the allowlist refused the reply and its draft was deleted again. A
+  // timeout, 5xx or failed delete may leave a draft, so the slot stays used.
+  const rateLimitError = checkRateLimit('draft');
+  if (rateLimitError) return rateLimitError;
+
+  let draft;
   try {
     const accessToken = await ensureAuthenticated();
-    const draft = await callGraphAPI(
+    draft = await callGraphAPI(
       accessToken,
       'POST',
       `me/messages/${id}/${endpoint}`,
       Object.keys(requestBody).length > 0 ? requestBody : null
     );
-    const label =
-      endpoint === 'createReplyAll'
-        ? 'reply-all draft created'
-        : 'reply draft created';
-    return formatDraftResponse(draft, label);
+
+    // Graph fills in the recipients from the original message, so they can
+    // only be checked once the draft exists.
+    const refusal = await refuseBlockedReply(accessToken, draft, actionName);
+    if (refusal) {
+      if (refusal.draftDeleted) releaseRateLimit('draft');
+      return refusal.error;
+    }
+
+    return formatDraftResponse(
+      draft,
+      `${actionName.charAt(0).toUpperCase()}${actionName.slice(1)} draft created`
+    );
+  } catch (error) {
+    // Only Graph's own rejection, read from the start of the error (the
+    // body after it is server text). 408 means it may have gone through.
+    const rejected = /^API call failed with status (4\d\d):/.exec(
+      error.message || ''
+    );
+    if (!draft && rejected && rejected[1] !== '408') {
+      releaseRateLimit('draft');
+    }
+    return handleError(`creating ${actionName} draft`, error);
+  }
+}
+
+/**
+ * When a recipient allowlist is configured, check the recipients Graph put
+ * on a new reply draft. If any is not allowed, delete the draft and return a
+ * refusal; otherwise return null.
+ * @param {string} accessToken - Graph access token
+ * @param {object} draft - The draft Graph returned from createReply/createReplyAll
+ * @param {string} actionName - 'reply' or 'reply-all'
+ * @returns {Promise<{error: object, draftDeleted: boolean}|null>} The
+ *   refusal and whether its draft was deleted, or null to keep the draft
+ */
+async function refuseBlockedReply(accessToken, draft, actionName) {
+  if (!getRecipientAllowlist()) return null;
+
+  let reason;
+  let nextStep;
+  try {
+    let message = draft;
+    if (!RECIPIENT_FIELDS.every((field) => Array.isArray(draft?.[field]))) {
+      message = await callGraphAPI(
+        accessToken,
+        'GET',
+        `me/messages/${draft.id}`,
+        null,
+        { $select: ['id', ...RECIPIENT_FIELDS].join(',') }
+      );
+    }
+    const blocked = findBlockedRecipients(recipientsOf(message));
+    if (!blocked) return null;
+    reason = `The ${actionName} draft would be addressed to ${blocked.blocked.join(', ')}, which OUTLOOK_ALLOWED_RECIPIENTS does not allow (allowed recipients/domains: ${blocked.allowed.join(', ')}).`;
+    nextStep =
+      'Reply only to allowed recipients (for example, action=reply rather than reply-all, or draft action=create addressed to them), or ask the user to add those recipients to OUTLOOK_ALLOWED_RECIPIENTS.';
+  } catch (error) {
+    // Unchecked recipients are treated like blocked ones.
+    reason = `The ${actionName} draft's recipients could not be checked against OUTLOOK_ALLOWED_RECIPIENTS (${error.message}).`;
+    nextStep = 'Try the call again.';
+  }
+
+  try {
+    await callGraphAPI(accessToken, 'DELETE', `me/messages/${draft.id}`);
   } catch (error) {
-    return handleError(
-      `creating ${endpoint === 'createReplyAll' ? 'reply-all' : 'reply'} draft`,
-      error
+    const stillThere = toolError(
+      `${reason} The draft Graph created could not be deleted (${error.message}), so it is still in Drafts with ID \`${draft.id}\`. Do not send it.`,
+      {
+        nextStep: `Delete it with draft action=delete id=${draft.id} (or in Outlook). ${nextStep}`,
+      }
     );
+    return { error: stillThere, draftDeleted: false };
   }
+
+  return {
+    error: toolError(
+      `${reason} The draft Graph created was deleted, so nothing was kept.`,
+      { nextStep }
+    ),
+    draftDeleted: true,
+  };
 }
 
 /**
@@ -440,33 +534,17 @@ async function handleForwardDraft(args) {
   const { id, to, body, comment } = args;
 
   if (!id) {
-    return {
-      content: [
-        { type: 'text', text: 'Message ID (id) is required for forward.' },
-      ],
-    };
+    return toolError('Message ID (id) is required for forward.');
   }
 
   if (!to) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Forward recipient (to) is required for forward.',
-        },
-      ],
-    };
+    return toolError('Forward recipient (to) is required for forward.');
   }
 
   if (comment && body) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Cannot use both comment and body. Use comment for a short prepended note, or body for full HTML/text content.',
-        },
-      ],
-    };
+    return toolError(
+      'Cannot use both comment and body. Use comment for a short prepended note, or body for full HTML/text content.'
+    );
   }
 
   const toRecipients = formatRecipients(to);
@@ -475,6 +553,9 @@ async function handleForwardDraft(args) {
   const allowlistError = checkRecipientAllowlist(toRecipients);
   if (allowlistError) return allowlistError;
 
+  const rateLimitError = checkRateLimit('draft');
+  if (rateLimitError) return rateLimitError;
+
   const requestBody = {
     toRecipients,
   };
@@ -498,7 +579,7 @@ async function handleForwardDraft(args) {
       `me/messages/${id}/createForward`,
       requestBody
     );
-    return formatDraftResponse(draft, 'forward draft created');
+    return formatDraftResponse(draft, 'Forward draft created');
   } catch (error) {
     return handleError('creating forward draft', error);
   }
@@ -516,24 +597,10 @@ function handleError(actionLabel, 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 ${actionLabel}: ${error.message}`,
-      },
-    ],
-  };
+  return toolError(`Error ${actionLabel}: ${error.message}`);
 }
 
 module.exports = handleDraft;