@littlebearapps/outlook-assistant 3.11.1 → 3.12.0

package/utils/graph-api.js

@@ -5,6 +5,87 @@ const https = require('https');
 const config = require('../config');
 const mockData = require('./mock-data');
 
+/**
+ * Guard for caller-supplied full URLs (nextLink/deltaLink continuations).
+ * The bearer token is attached to every request, so only the configured
+ * Graph host over HTTPS on the default port is allowed (GHSA-mqfm-wfjq-jxq2).
+ * @param {string} url - Full URL about to be requested
+ * @throws {Error} If the URL is malformed or not the Graph host
+ */
+function assertGraphUrl(url) {
+  const allowed = new URL(config.GRAPH_API_ENDPOINT);
+  let target;
+  try {
+    target = new URL(url);
+  } catch {
+    target = null;
+  }
+
+  const ok =
+    target &&
+    target.protocol === 'https:' &&
+    target.hostname === allowed.hostname &&
+    target.port === '' &&
+    target.username === '' &&
+    target.password === '';
+
+  if (!ok) {
+    throw new Error(
+      'Refusing to call non-Graph URL: continuation links must be https://' +
+        `${allowed.hostname}/ (check the deltaToken or nextLink value)`
+    );
+  }
+}
+
+/**
+ * Fully percent-decode a value (bounded), so `%2e`, `%252e` etc. are seen as
+ * the characters they eventually stand for. Malformed escapes stop decoding.
+ * @param {string} value
+ * @returns {string}
+ */
+function decodeFully(value) {
+  let current = value;
+  for (let i = 0; i < 5; i++) {
+    let next;
+    try {
+      next = decodeURIComponent(current);
+    } catch {
+      return current;
+    }
+    if (next === current) return current;
+    current = next;
+  }
+  return current;
+}
+
+/**
+ * Is this path segment a dot segment (`.` or `..`) in any encoding?
+ * @param {string} segment
+ * @returns {boolean}
+ */
+function isDotSegment(segment) {
+  const decoded = decodeFully(String(segment)).trim();
+  return decoded === '.' || decoded === '..';
+}
+
+/**
+ * Reject relative Graph resource paths containing dot segments. Caller-supplied
+ * IDs (message, folder, attachment, delta tokens) are interpolated into these
+ * paths, and URL normalisation would otherwise let `..` walk the request to a
+ * different Graph resource (another mailbox, another API version) than the
+ * tool intended. Legitimate Graph IDs never contain a bare `.`/`..` segment.
+ * @param {string} resourcePath - Relative path (query string, if any, ignored)
+ * @throws {Error} If any segment is `.` or `..` (literal or percent-encoded)
+ */
+function assertSafeResourcePath(resourcePath) {
+  const pathOnly = String(resourcePath).split('?')[0];
+  if (pathOnly.split('/').some(isDotSegment)) {
+    throw new Error(
+      'Invalid resource path: IDs must not contain "." or ".." path segments'
+    );
+  }
+}
+
 /**
  * Makes a request to the Microsoft Graph API
  * In test mode (USE_TEST_MODE=true), routes to mock data instead of the real API.
@@ -36,9 +117,13 @@ async function callGraphAPI(
     let finalUrl;
     if (path.startsWith('http://') || path.startsWith('https://')) {
       // Path is already a full URL (from pagination nextLink)
+      assertGraphUrl(path);
       finalUrl = path;
     } else {
-      // Build URL from path and queryParams
+      // Build URL from path and queryParams. Refuse dot segments before
+      // encoding: encodeURIComponent leaves `..` intact, and the URL parser
+      // would then resolve it to a different resource.
+      assertSafeResourcePath(path);
       // Encode path segments properly
       const encodedPath = path
         .split('/')
@@ -259,6 +344,12 @@ async function callGraphAPIBatch(accessToken, requests) {
     }));
   }
 
+  // Batch sub-request URLs are resolved by Graph itself — apply the same
+  // dot-segment guard as single requests.
+  for (const req of requests) {
+    assertSafeResourcePath(req.url);
+  }
+
   const batchPayload = {
     requests: requests.map((req) => ({
       id: req.id,
@@ -286,11 +377,12 @@ async function callGraphAPIBatch(accessToken, requests) {
  * In test mode (USE_TEST_MODE=true), returns mock MIME content instead of calling the real API.
  * @param {string} accessToken - The access token for authentication
  * @param {string} emailId - The email ID to export
+ * @param {string} [mailboxPrefix] - Resource prefix (`me` or `users/{email}`) for shared mailboxes. Defaults to `me`.
  * @returns {Promise<string>} - Raw MIME content as string
  * @throws {Error} 'UNAUTHORIZED' if the server returns HTTP 401 (token expired or invalid)
  * @throws {Error} If the HTTP status is outside 2xx or a network error occurs
  */
-async function callGraphAPIRaw(accessToken, emailId) {
+async function callGraphAPIRaw(accessToken, emailId, mailboxPrefix = 'me') {
   // Test mode: return mock MIME content
   if (config.USE_TEST_MODE && accessToken.startsWith('test_access_token_')) {
     return mockData.getMockMimeContent
@@ -298,8 +390,21 @@ async function callGraphAPIRaw(accessToken, emailId) {
       : `MIME-Version: 1.0\nContent-Type: text/plain\n\nTest email content for ${emailId}`;
   }
 
+  // `emailId` is encoded as a single segment, but a bare `.`/`..` id would
+  // still be resolved as a dot segment — refuse it (and any in the prefix).
+  assertSafeResourcePath(`${mailboxPrefix}/messages`);
+  if (isDotSegment(emailId)) {
+    throw new Error(
+      'Invalid resource path: IDs must not contain "." or ".." path segments'
+    );
+  }
+
   return new Promise((resolve, reject) => {
-    const path = `me/messages/${encodeURIComponent(emailId)}/$value`;
+    const encodedPrefix = mailboxPrefix
+      .split('/')
+      .map((segment) => encodeURIComponent(segment))
+      .join('/');
+    const path = `${encodedPrefix}/messages/${encodeURIComponent(emailId)}/$value`;
     const finalUrl = `${config.GRAPH_API_ENDPOINT}${path}`;
 
     const options = {
@@ -401,6 +506,7 @@ async function callGraphAPIWithAuth(
 }
 
 module.exports = {
+  assertSafeResourcePath,
   callGraphAPI,
   callGraphAPIPaginated,
   callGraphAPIBatch,

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/response-formatter.js

@@ -467,20 +467,54 @@ function truncateText(text, maxLength) {
   return `${text.substring(0, maxLength - 3)}...`;
 }
 
+const HTML_ENTITIES = {
+  nbsp: ' ',
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  '#39': "'",
+};
+
+/**
+ * Removes tags in one linear scan: `<…>` with no `<` inside is dropped
+ * whole, and any other `<` (nested fragments such as `<scr<script>ipt>`,
+ * or an unterminated tag) is dropped on its own, so no markup can
+ * reassemble. A scanner rather than a repeated regex replace keeps deeply
+ * nested input like `<<<…x…>>>` linear.
+ * @param {string} text - HTML fragment
+ * @returns {string} - Text with no `<` remaining
+ */
+function removeTags(text) {
+  let out = '';
+  let i = 0;
+  while (i < text.length) {
+    const lt = text.indexOf('<', i);
+    if (lt === -1) {
+      out += text.slice(i);
+      break;
+    }
+    out += text.slice(i, lt);
+    // Scan only to the next '<' or '>', so each character is visited once.
+    let j = lt + 1;
+    while (j < text.length && text[j] !== '<' && text[j] !== '>') j++;
+    i = text[j] === '>' ? j + 1 : lt + 1;
+  }
+  return out;
+}
+
 /**
- * Strips HTML tags (simple implementation)
+ * Strips HTML tags (simple implementation), in linear time.
+ * Entities are decoded after tag removal, in a single pass, so `&amp;lt;`
+ * becomes `&lt;`, not `<`.
  */
 function stripHtml(html) {
   if (!html) return '';
-  return html
-    .replace(/<br\s*\/?>/gi, '\n')
-    .replace(/<\/p>/gi, '\n\n')
-    .replace(/<[^>]*>/g, '')
-    .replace(/&nbsp;/g, ' ')
-    .replace(/&amp;/g, '&')
-    .replace(/&lt;/g, '<')
-    .replace(/&gt;/g, '>')
-    .replace(/&quot;/g, '"')
+  return removeTags(
+    html.replace(/<br\s*\/?>/gi, '\n').replace(/<\/p>/gi, '\n\n')
+  )
+    .replace(/&(nbsp|amp|lt|gt|quot|apos|#39);/g, (_, e) => HTML_ENTITIES[e])
     .replace(/\n{3,}/g, '\n\n')
     .trim();
 }