@littlebearapps/outlook-assistant 3.11.2 → 3.12.1

package/utils/mailbox.js

@@ -0,0 +1,77 @@
+/**
+ * Mailbox scoping helper.
+ *
+ * Every Graph path in this server is built as `${prefix}/...`. The prefix is
+ * `me` for the signed-in account, or `users/{email}` for a shared/delegated
+ * mailbox. Keeping the construction in one place is what lets the shared-mailbox
+ * parameter be threaded through readers, writers, and folder resolution without
+ * each call site re-deciding the shape.
+ */
+
+// Pragmatic SMTP address / UPN shape — deliberately not full RFC 5322. The
+// point is to keep caller input inside a single Graph path segment, so only
+// printable ASCII is accepted: RFC 5322 `atext` in the local part minus `#`
+// (a URL fragment delimiter), and dot-separated letters/digits/hyphens in the
+// domain. No whitespace, control characters, `/ ? # % \`, or non-ASCII
+// look-alikes (full-width `／`, zero-width spaces). The tool schemas advertise
+// an email address only, so bare user GUIDs are not accepted.
+const MAILBOX_PATTERN =
+  /^[A-Za-z0-9.!$&'*+=^_`{|}~-]+@[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$/;
+
+const config = require('../config');
+
+const SHARED_MAILBOX_DISABLED_MESSAGE =
+  'Shared-mailbox support is turned off. It is opt-in and work/school only: ' +
+  'set OUTLOOK_SHARED_MAILBOX=read (read) or OUTLOOK_SHARED_MAILBOX=true ' +
+  '(read and organise) in the MCP server environment, restart the server, then ' +
+  're-authenticate with `auth action=authenticate force=true` so the token ' +
+  'carries the shared-mailbox scopes.';
+
+/**
+ * Validate a mailbox and build its Graph resource prefix, WITHOUT checking
+ * whether shared-mailbox support is enabled. Only for paths that worked
+ * before the opt-in flag existed (access-shared-mailbox's direct read).
+ * @param {string|null} [mailbox] - Shared mailbox email address, or null/empty for the signed-in user
+ * @returns {string} - `me` or `users/{mailbox}`
+ * @throws {Error} If `mailbox` is non-empty but not a plausible email address
+ */
+function validateMailboxPrefix(mailbox) {
+  const trimmed = typeof mailbox === 'string' ? mailbox.trim() : mailbox;
+  if (!trimmed) {
+    return 'me';
+  }
+  if (trimmed === 'me') {
+    return 'me';
+  }
+  if (!MAILBOX_PATTERN.test(trimmed)) {
+    throw new Error(
+      `Invalid mailbox "${mailbox}" — expected a shared mailbox email address (e.g. "team@contoso.com").`
+    );
+  }
+  // Return the address raw: encoding happens exactly once, in the Graph
+  // client (`callGraphAPI` / `callGraphAPIRaw` encode each path segment).
+  // Pre-encoding here double-encoded addresses like `team+archive@…` into
+  // `%252B`. The pattern above already confines the value to one segment.
+  return `users/${trimmed}`;
+}
+
+/**
+ * Build the Graph resource prefix for a mailbox. A non-`me` mailbox requires
+ * shared-mailbox support to be enabled (OUTLOOK_SHARED_MAILBOX).
+ * @param {string|null} [mailbox] - Shared mailbox email address, or null/empty for the signed-in user
+ * @returns {string} - `me` or `users/{mailbox}`
+ * @throws {Error} If `mailbox` is invalid, or shared-mailbox support is off
+ */
+function buildMailboxPrefix(mailbox) {
+  const prefix = validateMailboxPrefix(mailbox);
+  if (prefix !== 'me' && config.SHARED_MAILBOX_MODE === 'off') {
+    throw new Error(SHARED_MAILBOX_DISABLED_MESSAGE);
+  }
+  return prefix;
+}
+
+module.exports = {
+  buildMailboxPrefix,
+  validateMailboxPrefix,
+  SHARED_MAILBOX_DISABLED_MESSAGE,
+};

package/utils/mock-data.js

@@ -47,6 +47,9 @@ function simulateGraphAPIResponse(method, path, _data, _queryParams) {
           hasAttachments: false,
           importance: 'normal',
           isRead: false,
+          // A draft, so draft update/send/delete pass the draft guard in
+          // test mode (they look the ID up before acting).
+          isDraft: true,
           internetMessageHeaders: [],
         };
       } else {

package/utils/odata-helpers.js

@@ -14,6 +14,28 @@ function escapeODataString(str) {
   return str.replace(/'/g, "''");
 }
 
+/**
+ * Escapes text for use inside a double-quoted Graph `$search` phrase.
+ * Graph requires `"` and `\` inside the phrase to be backslash-escaped;
+ * backslashes go first so the escapes added for quotes are not doubled. (#251)
+ * @param {string} str - Raw user text
+ * @returns {string} - Text safe to place between the phrase's quotes
+ */
+function escapeSearchPhrase(str) {
+  if (!str) return str;
+  return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+/**
+ * Wraps user text as a double-quoted Graph `$search` phrase, escaping it.
+ * Not for caller-written `$search` expressions, which pass through as-is.
+ * @param {string} str - Raw user text
+ * @returns {string} - e.g. `Sam "the man" Lee` → `"Sam \"the man\" Lee"`
+ */
+function quoteSearchPhrase(str) {
+  return `"${escapeSearchPhrase(str)}"`;
+}
+
 /**
  * Builds an OData filter from filter conditions
  * @param {Array<string>} conditions - Array of filter conditions
@@ -29,5 +51,7 @@ function buildODataFilter(conditions) {
 
 module.exports = {
   escapeODataString,
+  escapeSearchPhrase,
+  quoteSearchPhrase,
   buildODataFilter,
 };

package/utils/safe-write.js

@@ -0,0 +1,151 @@
+/**
+ * Safe output writes, shared by attachment download, message export and
+ * conversation export.
+ *
+ * Every file the server names itself is written with exclusive create (`wx`),
+ * so an existing file is never overwritten and a planted symlink — even a
+ * dangling one — is never followed. A clash gets a `-1`, `-2`, … suffix
+ * instead, and the result is always confined to `outputDir`.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const MAX_ATTEMPTS = 1000;
+
+/**
+ * Like fs.existsSync, but a dangling symlink counts as existing (existsSync
+ * follows the link and reports false).
+ * @param {string} candidate
+ * @returns {boolean}
+ */
+function pathEntryExists(candidate) {
+  try {
+    fs.lstatSync(candidate);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build `<base>[-N][.ext]` inside `root`, refusing anything that would land
+ * outside it. Names are built from sanitised parts, but confine defensively.
+ * @param {string} root - Resolved target directory
+ * @param {string} base - Name without extension
+ * @param {string} ext - Extension with its leading dot, or ''
+ * @param {number} suffix - 0 for the plain name, else the collision number
+ * @returns {string}
+ */
+function candidatePath(root, base, ext, suffix) {
+  const name = suffix === 0 ? `${base}${ext}` : `${base}-${suffix}${ext}`;
+  const candidate = path.join(root, name);
+  if (path.dirname(candidate) !== root) {
+    throw new Error('Refusing to write file outside outputDir');
+  }
+  return candidate;
+}
+
+/**
+ * Claim a not-yet-used path in `outputDir`: the plain name, else `-1`, `-2`, …
+ * until the name is free both on disk and among the paths already claimed in
+ * this batch.
+ *
+ * Silent overwrite is the dangerous part of the batch-export collision defect:
+ * the exporter reported `Successful N / Failed 0` while messages vanished.
+ * Never overwrite — disambiguate instead, and let the caller reconcile via the
+ * paths returned.
+ *
+ * The claim is synchronous, so it is atomic with respect to the event loop and
+ * safe under the batch exporter's 4-way concurrency.
+ *
+ * @param {string} outputDir - Target directory
+ * @param {string} base - Filename without extension
+ * @param {string} extension - Extension without a leading dot ('' for none)
+ * @param {Set<string>} claimed - Paths already claimed by this batch
+ * @returns {string} - An unused absolute path, now claimed
+ */
+function claimUniquePath(outputDir, base, extension, claimed) {
+  const root = path.resolve(outputDir);
+  const ext = extension ? `.${extension}` : '';
+  for (let suffix = 0; suffix < MAX_ATTEMPTS; suffix++) {
+    const candidate = candidatePath(root, base, ext, suffix);
+    if (!claimed.has(candidate) && !pathEntryExists(candidate)) {
+      claimed.add(candidate);
+      return candidate;
+    }
+  }
+  throw new Error(`Too many files named ${base}${ext} in ${root}`);
+}
+
+/**
+ * Best-effort removal of a file this call created before its write failed
+ * (e.g. ENOSPC/EIO), so no truncated file is left under the claimed name.
+ * Only called for non-EEXIST errors: with EEXIST the entry isn't ours.
+ * @param {string} candidate
+ */
+function removePartialFile(candidate) {
+  try {
+    fs.unlinkSync(candidate);
+  } catch {
+    // Already gone (ENOENT) or not removable; the original error matters more.
+  }
+}
+
+/**
+ * Claim a unique name in `outputDir` and write `data` to it exclusively. The
+ * `wx` flag fails on any existing entry — including a dangling symlink planted
+ * after the claim — so a write never overwrites a file or follows a link; on
+ * EEXIST the next suffix is claimed instead. Any other write error removes the
+ * partly written file before it is rethrown.
+ * @param {string} outputDir - Target directory (must already exist)
+ * @param {string} base - Filename without extension (already sanitised)
+ * @param {string} extension - Extension without a leading dot ('' for none)
+ * @param {Set<string>|null} claimed - Paths already claimed by this batch
+ * @param {string|Buffer} data - File contents
+ * @param {string} [encoding] - Encoding for string data
+ * @returns {string} - Absolute path actually written
+ */
+function writeClaimedFile(outputDir, base, extension, claimed, data, encoding) {
+  const seen = claimed || new Set();
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    const candidate = claimUniquePath(outputDir, base, extension, seen);
+    try {
+      fs.writeFileSync(candidate, data, { encoding, flag: 'wx' });
+      return candidate;
+    } catch (error) {
+      if (error.code !== 'EEXIST') {
+        removePartialFile(candidate);
+        throw error;
+      }
+    }
+  }
+  throw new Error(`Too many files named ${base} in ${outputDir}`);
+}
+
+/**
+ * Create a new, empty directory `<base>` (or `<base>-N`) inside `outputDir`.
+ * A non-recursive mkdir fails on any existing entry, so an export never writes
+ * into a directory it didn't just create — including a symlink pointing out of
+ * `outputDir`.
+ * @param {string} outputDir - Parent directory (must already exist)
+ * @param {string} base - Directory name (already sanitised)
+ * @returns {string} - Absolute path of the directory created
+ */
+function makeClaimedDir(outputDir, base) {
+  const root = path.resolve(outputDir);
+  for (let suffix = 0; suffix < MAX_ATTEMPTS; suffix++) {
+    const candidate = candidatePath(root, base, '', suffix);
+    try {
+      fs.mkdirSync(candidate);
+      return candidate;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+    }
+  }
+  throw new Error(`Too many directories named ${base} in ${root}`);
+}
+
+module.exports = {
+  writeClaimedFile,
+  makeClaimedDir,
+};

package/calendar/accept.js

@@ -1,72 +0,0 @@
-/**
- * Accept event functionality
- */
-const { callGraphAPI } = require('../utils/graph-api');
-const { ensureAuthenticated } = require('../auth');
-
-/**
- * Accept event handler
- * @param {object} args - Tool arguments
- * @returns {object} - MCP response
- */
-async function handleAcceptEvent(args) {
-  const { eventId, comment } = args;
-
-  if (!eventId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Event ID is required to accept an event.',
-        },
-      ],
-    };
-  }
-
-  try {
-    // Get access token
-    const accessToken = await ensureAuthenticated();
-
-    // Build API endpoint
-    const endpoint = `me/events/${eventId}/accept`;
-
-    // Request body
-    const body = {
-      comment: comment || 'Accepted via API',
-    };
-
-    // Make API call
-    await callGraphAPI(accessToken, 'POST', endpoint, body);
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Event with ID ${eventId} has been successfully accepted.`,
-        },
-      ],
-    };
-  } catch (error) {
-    if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
-    }
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error accepting event: ${error.message}`,
-        },
-      ],
-    };
-  }
-}
-
-module.exports = handleAcceptEvent;