@littlebearapps/outlook-assistant 3.11.2 → 3.12.1

package/calendar/list.js

@@ -4,6 +4,126 @@
 const config = require('../config');
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
+const {
+  escapeODataString,
+  buildODataFilter,
+} = require('../utils/odata-helpers');
+const { parseIsoInstant } = require('../utils/datetime');
+
+const MAX_SUBJECT_LENGTH = 255;
+
+/**
+ * Error raised for invalid list-events arguments, so the handler can report it
+ * as a tool error without touching the network.
+ */
+class ListEventsArgumentError extends Error {}
+
+/**
+ * Parse an ISO 8601 instant (with `Z` or a ±hh:mm offset) and return it as a
+ * UTC ISO string. Events are requested in UTC, so comparing against a UTC
+ * instant keeps the filter correct for offset inputs such as +10:00.
+ * The schema declares `format: "date-time"` but the MCP schema-coerce layer
+ * does not enforce JSON Schema `format`, so we enforce here at runtime.
+ */
+function toUtcIsoDateTime(value, paramName) {
+  const parsed = parseIsoInstant(value);
+  if (Number.isNaN(parsed)) {
+    throw new ListEventsArgumentError(
+      `Invalid ${paramName}: expected an ISO 8601 datetime with "Z" or a ±hh:mm offset, e.g. "2026-01-01T00:00:00Z" (got ${JSON.stringify(String(value).slice(0, 40))}).`
+    );
+  }
+  return new Date(parsed).toISOString();
+}
+
+/**
+ * Validate the subject filter: a non-empty-safe string of bounded length that
+ * can be URL-encoded (a lone surrogate would make encodeURIComponent throw).
+ */
+function assertValidSubject(subject) {
+  if (typeof subject !== 'string') {
+    throw new ListEventsArgumentError('Invalid subject: expected a string.');
+  }
+  if (subject.length > MAX_SUBJECT_LENGTH) {
+    throw new ListEventsArgumentError(
+      `Invalid subject: must be at most ${MAX_SUBJECT_LENGTH} characters.`
+    );
+  }
+  try {
+    encodeURIComponent(subject);
+  } catch (_e) {
+    throw new ListEventsArgumentError(
+      'Invalid subject: contains malformed Unicode.'
+    );
+  }
+}
+
+/**
+ * Build the $filter clause for the list-events Graph query.
+ *
+ * Backward-compatible behaviour: when no search args are supplied, the filter
+ * defaults to `start/dateTime ge '<now>'` so callers without parameters keep
+ * seeing only upcoming events. When ANY of startAfter/startBefore/subject are
+ * supplied, those replace the default and are AND-ed together.
+ *
+ * startAfter/startBefore must carry a zone and are normalised to UTC; invalid
+ * values raise before any Graph call is made. Single quotes in the subject are
+ * escaped via OData rules (`'` -> `''`) to prevent filter injection.
+ *
+ * Graph requires `$orderby` properties to lead the `$filter`, so a subject-only
+ * search gets a `start/dateTime ge '1900-…'` lead clause (which matches every
+ * event) to avoid an InefficientFilter error.
+ *
+ * @param {object} args - { startAfter?, startBefore?, subject? }
+ * @returns {string} - The complete $filter expression
+ */
+function buildListEventsFilter(args) {
+  const { startAfter, startBefore, subject } = args;
+  const hasAnyFilter = Boolean(startAfter || startBefore || subject);
+
+  const conditions = [];
+
+  if (hasAnyFilter) {
+    const after = startAfter
+      ? toUtcIsoDateTime(startAfter, 'startAfter')
+      : null;
+    const before = startBefore
+      ? toUtcIsoDateTime(startBefore, 'startBefore')
+      : null;
+    if (after && before && after >= before) {
+      throw new ListEventsArgumentError(
+        'Invalid range: startAfter must be earlier than startBefore.'
+      );
+    }
+    if (subject) assertValidSubject(subject);
+
+    if (after) conditions.push(`start/dateTime ge '${after}'`);
+    if (before) conditions.push(`start/dateTime lt '${before}'`);
+    if (!after && !before) {
+      conditions.push("start/dateTime ge '1900-01-01T00:00:00.000Z'");
+    }
+    if (subject) {
+      conditions.push(`contains(subject, '${escapeODataString(subject)}')`);
+    }
+  } else {
+    conditions.push(`start/dateTime ge '${new Date().toISOString()}'`);
+  }
+
+  return buildODataFilter(conditions);
+}
+
+/**
+ * Sort order for list-events: oldest first for upcoming or bounded windows;
+ * newest first when the search only looks backwards (an upper bound only, or a
+ * subject with no dates), so `$top` returns the most recent matches rather
+ * than the oldest events in the calendar.
+ * @param {object} args - { startAfter?, startBefore?, subject? }
+ * @returns {string} - The $orderby expression
+ */
+function listEventsOrderBy(args) {
+  const { startAfter, startBefore, subject } = args;
+  const newestFirst = !startAfter && Boolean(startBefore || subject);
+  return newestFirst ? 'start/dateTime desc' : 'start/dateTime';
+}
 
 /**
  * Normalise a Graph dateTimeTimeZone value to a canonical UTC ISO-8601 string
@@ -89,7 +209,28 @@ function formatLocal(utcIso, tz) {
  * @returns {object} - MCP response
  */
 async function handleListEvents(args) {
-  const count = Math.min(args.count || 10, config.MAX_RESULT_COUNT);
+  // Whole number in 1..MAX_RESULT_COUNT: Graph rejects $top below 1 or
+  // fractional, and the schema promises the cap.
+  const requested = args.count == null ? 10 : Math.floor(args.count);
+  const count = Math.min(
+    Math.max(Number.isFinite(requested) ? requested : 10, 1),
+    config.MAX_RESULT_COUNT
+  );
+
+  // Validate arguments before authenticating, so a bad argument is reported
+  // as such (and never reaches the network).
+  let filter;
+  try {
+    filter = buildListEventsFilter(args);
+  } catch (error) {
+    if (error instanceof ListEventsArgumentError) {
+      return {
+        content: [{ type: 'text', text: error.message }],
+        isError: true,
+      };
+    }
+    throw error;
+  }
 
   try {
     // Get access token
@@ -101,8 +242,8 @@ async function handleListEvents(args) {
     // Add query parameters
     const queryParams = {
       $top: count,
-      $orderby: 'start/dateTime',
-      $filter: `start/dateTime ge '${new Date().toISOString()}'`,
+      $orderby: listEventsOrderBy(args),
+      $filter: filter,
       $select: config.CALENDAR_SELECT_FIELDS,
     };
 
@@ -198,3 +339,5 @@ handleListEvents.toUtcIso = toUtcIso;
 handleListEvents.formatLocal = formatLocal;
 
 module.exports = handleListEvents;
+module.exports.buildListEventsFilter = buildListEventsFilter;
+module.exports.listEventsOrderBy = listEventsOrderBy;

package/calendar/update.js

@@ -11,7 +11,7 @@
  *   - subject
  *   - start          (ISO string or {dateTime, timeZone} object)
  *   - end            (same shape as start)
- *   - attendees      (full replacement list of emails)
+ *   - attendees      (full replacement list; email strings or {email, type})
  *   - body           (sent as HTML)
  *   - location       (displayName)
  *   - isOnlineMeeting
@@ -21,12 +21,16 @@
  *   - categories     (full replacement array of category names)
  *   - reminderMinutesBeforeStart
  *
- * `dryRun: true` returns a preview of the PATCH payload without calling
- * Graph — useful for confirming behaviour before mutating real data.
+ * `dryRun: true` returns a preview of the PATCH payload without changing
+ * anything — useful for confirming behaviour before mutating real data.
+ * When an attendee has no explicit type, the event's current attendees are
+ * read first (also on dryRun) so existing optional/resource attendees keep
+ * their type (#249).
  */
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { DEFAULT_TIMEZONE } = require('../config');
+const { normaliseAttendees, buildAttendees } = require('./attendees');
 
 const SENSITIVITY_VALUES = new Set([
   'normal',
@@ -82,6 +86,9 @@ async function handleUpdateEvent(args) {
   // Graph treats absent properties as "no change", so we never overwrite
   // something the user didn't intend to touch.
   const patch = {};
+  // Attendee entries without an explicit type, which need the event's
+  // current attendees to resolve (#249).
+  let untypedAttendees = null;
 
   if (subject !== undefined) patch.subject = subject;
 
@@ -102,10 +109,17 @@ async function handleUpdateEvent(args) {
   if (attendees !== undefined) {
     // Replaces the full attendee list — Graph PATCH on this property is
     // not additive. Caller must pass the desired complete list.
-    patch.attendees = (attendees || []).map((email) => ({
-      emailAddress: { address: email },
-      type: 'required',
-    }));
+    let entries;
+    try {
+      entries = normaliseAttendees(attendees || []);
+    } catch (error) {
+      return {
+        content: [{ type: 'text', text: error.message }],
+        isError: true,
+      };
+    }
+    patch.attendees = buildAttendees(entries);
+    if (entries.some((entry) => !entry.type)) untypedAttendees = entries;
   }
 
   if (body !== undefined) {
@@ -193,34 +207,52 @@ async function handleUpdateEvent(args) {
     };
   }
 
-  // dryRun: don't touch Graph; just show the caller what would be sent.
-  if (dryRun) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: [
-            `**Dry run** — would PATCH \`me/events/${eventId}\` with:`,
-            '',
-            '```json',
-            JSON.stringify(patch, null, 2),
-            '```',
-            '',
-            `Fields that would change: ${Object.keys(patch).join(', ')}`,
-          ].join('\n'),
+  try {
+    let accessToken;
+
+    // Keep the type of attendees already on the event: an entry without an
+    // explicit type takes its current type, so a room or optional attendee
+    // isn't turned into a required one. Runs before the dryRun return so the
+    // preview shows the resolved types.
+    if (untypedAttendees) {
+      accessToken = await ensureAuthenticated();
+      const current = await callGraphAPI(
+        accessToken,
+        'GET',
+        `me/events/${eventId}`,
+        null,
+        { $select: 'attendees' }
+      );
+      patch.attendees = buildAttendees(untypedAttendees, current?.attendees);
+    }
+
+    // dryRun: show the caller what would be sent without changing anything.
+    if (dryRun) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: [
+              `**Dry run** — would PATCH \`me/events/${eventId}\` with:`,
+              '',
+              '```json',
+              JSON.stringify(patch, null, 2),
+              '```',
+              '',
+              `Fields that would change: ${Object.keys(patch).join(', ')}`,
+            ].join('\n'),
+          },
+        ],
+        _meta: {
+          eventId,
+          dryRun: true,
+          patch,
+          fieldsChanged: Object.keys(patch),
         },
-      ],
-      _meta: {
-        eventId,
-        dryRun: true,
-        patch,
-        fieldsChanged: Object.keys(patch),
-      },
-    };
-  }
+      };
+    }
 
-  try {
-    const accessToken = await ensureAuthenticated();
+    accessToken = accessToken || (await ensureAuthenticated());
     const endpoint = `me/events/${eventId}`;
 
     const response = await callGraphAPI(accessToken, 'PATCH', endpoint, patch);

package/categories/index.js

@@ -5,6 +5,7 @@
  */
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
+const { buildMailboxPrefix } = require('../utils/mailbox');
 
 // Category color presets (Outlook uses these names)
 const CATEGORY_COLORS = [
@@ -436,6 +437,7 @@ async function handleDeleteCategory(args) {
  */
 async function handleApplyCategory(args) {
   const { messageId, messageIds, categories, action } = args;
+  const mailbox = args.sharedMailbox || args.email || null;
 
   // Support single ID or array
   const ids = messageIds || (messageId ? [messageId] : []);
@@ -477,6 +479,9 @@ async function handleApplyCategory(args) {
   }
 
   try {
+    // Inside the try so an invalid mailbox returns the handler's normal
+    // error object instead of a rejected promise.
+    const prefix = buildMailboxPrefix(mailbox);
     const accessToken = await ensureAuthenticated();
 
     const results = [];
@@ -491,7 +496,7 @@ async function handleApplyCategory(args) {
           const current = await callGraphAPI(
             accessToken,
             'GET',
-            `me/messages/${id}`,
+            `${prefix}/messages/${id}`,
             null,
             { $select: 'categories' }
           );
@@ -507,7 +512,7 @@ async function handleApplyCategory(args) {
           }
         }
 
-        await callGraphAPI(accessToken, 'PATCH', `me/messages/${id}`, {
+        await callGraphAPI(accessToken, 'PATCH', `${prefix}/messages/${id}`, {
           categories: newCategories,
         });
 
@@ -901,7 +906,7 @@ const categoriesTools = [
   {
     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 master list (create via `manage-category` first). Returns per-message confirmation.",
+      "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,
@@ -931,6 +936,15 @@ const categoriesTools = [
           description:
             'set (replace all), add (append), remove (remove specific). Default: set',
         },
+        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: {
+          type: 'string',
+          description: 'Alias for `sharedMailbox`.',
+        },
       },
       additionalProperties: false,
       required: ['categories'],

package/config.js

@@ -57,7 +57,6 @@ if (
   !VALID_AUDIENCE_LITERALS.has(AUTH_AUDIENCE) &&
   !TENANT_GUID_RE.test(AUTH_AUDIENCE)
 ) {
-  // eslint-disable-next-line no-console
   console.warn(
     `[outlook-assistant] OUTLOOK_AUTH_AUDIENCE="${AUTH_AUDIENCE}" is not a recognised value. ` +
       `Expected one of: common, consumers, organizations, or a tenant GUID. ` +
@@ -65,6 +64,88 @@ if (
   );
 }
 
+// Shared/delegated mailbox access is OPT-IN (work/school accounts only).
+// With OUTLOOK_SHARED_MAILBOX unset, sign-in requests exactly BASE_SCOPES —
+// nobody's consent prompt or token changes unless they enable it:
+//   OUTLOOK_SHARED_MAILBOX=read                 → Mail.Read.Shared
+//   OUTLOOK_SHARED_MAILBOX=true|readwrite|1     → Mail.Read.Shared + Mail.ReadWrite.Shared
+// Sending/drafts from a shared mailbox are out of scope (Mail.Send.Shared is
+// never requested). When enabled, the device-code flow falls back to
+// BASE_SCOPES only on errors proving the account can't use `.Shared` scopes
+// (see auth/device-code.js isScopeConsentError); consent-required errors
+// (AADSTS65001) surface remediation instead of downgrading.
+const ALL_SHARED_SCOPES = ['Mail.Read.Shared', 'Mail.ReadWrite.Shared'];
+
+/**
+ * Parse OUTLOOK_SHARED_MAILBOX into a mode.
+ * @param {string|undefined} raw
+ * @returns {'off'|'read'|'readwrite'}
+ */
+function parseSharedMailboxMode(raw) {
+  const value = String(raw || '')
+    .trim()
+    .toLowerCase();
+  if (value === 'read') return 'read';
+  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. ` +
+        'Expected read, true/readwrite/1, or unset. Shared-mailbox support stays off.'
+    );
+  }
+  return 'off';
+}
+
+const SHARED_MAILBOX_MODE = parseSharedMailboxMode(
+  process.env.OUTLOOK_SHARED_MAILBOX
+);
+const SHARED_SCOPES_BY_MODE = {
+  off: [],
+  read: ['Mail.Read.Shared'],
+  readwrite: [...ALL_SHARED_SCOPES],
+};
+const SHARED_SCOPES = SHARED_SCOPES_BY_MODE[SHARED_MAILBOX_MODE];
+
+// Base scopes consentable by ANY account type (personal + work/school).
+const BASE_SCOPES = [
+  'offline_access',
+  'User.Read',
+  'Mail.Read',
+  'Mail.ReadWrite',
+  'Mail.Send',
+  'Calendars.Read',
+  'Calendars.ReadWrite',
+  'Contacts.Read',
+  'Contacts.ReadWrite',
+  'People.Read',
+  'MailboxSettings.ReadWrite',
+  // Org-dependent scopes (work/school accounts only):
+  // 'Place.Read.All',     // find-meeting-rooms tool
+];
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
+
+/**
+ * Parse OUTLOOK_REQUEST_TIMEOUT_MS: per-attempt Graph inactivity timeout
+ * (ms with no data received). Unset or invalid → 60000 (invalid values warn).
+ * @param {string|undefined} raw
+ * @returns {number}
+ */
+function parseRequestTimeoutMs(raw) {
+  if (raw === undefined || String(raw).trim() === '') {
+    return DEFAULT_REQUEST_TIMEOUT_MS;
+  }
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value <= 0) {
+    console.warn(
+      `[outlook-assistant] OUTLOOK_REQUEST_TIMEOUT_MS="${raw}" is not a positive integer. ` +
+        `Using the default of ${DEFAULT_REQUEST_TIMEOUT_MS} ms.`
+    );
+    return DEFAULT_REQUEST_TIMEOUT_MS;
+  }
+  return value;
+}
+
 module.exports = {
   // Server information
   SERVER_NAME: 'outlook-assistant',
@@ -73,27 +154,25 @@ module.exports = {
   // Test mode setting
   USE_TEST_MODE: process.env.USE_TEST_MODE === 'true',
 
+  // 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)
+  SHARED_SCOPES,
+  ALL_SHARED_SCOPES,
+  // 'off' | 'read' | 'readwrite' — from OUTLOOK_SHARED_MAILBOX (opt-in)
+  SHARED_MAILBOX_MODE,
+  parseSharedMailboxMode,
+
   // Authentication configuration
   AUTH_CONFIG: {
     clientId: process.env.OUTLOOK_CLIENT_ID || '',
     clientSecret: process.env.OUTLOOK_CLIENT_SECRET || '',
     redirectUri: 'http://localhost:3333/auth/callback',
-    scopes: [
-      'offline_access',
-      'User.Read',
-      'Mail.Read',
-      'Mail.ReadWrite',
-      'Mail.Send',
-      'Calendars.Read',
-      'Calendars.ReadWrite',
-      'Contacts.Read',
-      'Contacts.ReadWrite',
-      'People.Read',
-      'MailboxSettings.ReadWrite',
-      // Org-dependent scopes (work/school accounts only):
-      // 'Mail.Read.Shared',   // access-shared-mailbox tool
-      // 'Place.Read.All',     // find-meeting-rooms tool
-    ],
+    // Base scopes, plus the `.Shared` scopes only when OUTLOOK_SHARED_MAILBOX
+    // opts in. With the flag on, device-code auth falls back to
+    // fallbackScopes (base only) when the account rejects `.Shared`.
+    scopes: [...BASE_SCOPES, ...SHARED_SCOPES],
+    fallbackScopes: BASE_SCOPES,
     tokenStorePath: path.join(homeDir, '.outlook-assistant-tokens.json'),
     authServerUrl: 'http://localhost:3333',
     audience: AUTH_AUDIENCE,
@@ -140,6 +219,13 @@ module.exports = {
   // Immutable IDs (opt-in: IDs persist through folder moves)
   USE_IMMUTABLE_IDS: process.env.OUTLOOK_IMMUTABLE_IDS === 'true',
 
+  // Per-attempt Graph inactivity timeout: an attempt that receives no data
+  // for this many ms is abandoned (not an overall deadline). Throttled and
+  // transient responses are retried by utils/graph-api.js.
+  REQUEST_TIMEOUT_MS: parseRequestTimeoutMs(
+    process.env.OUTLOOK_REQUEST_TIMEOUT_MS
+  ),
+
   // Timezone — IANA zone (e.g. "Australia/Melbourne", "Europe/London",
   // "America/New_York"). Override per-deployment via OUTLOOK_DEFAULT_TIMEZONE.
   // Default preserves the historic value for backwards compatibility.

package/contacts/index.js

@@ -8,6 +8,7 @@ const {
   callGraphAPIPaginated: _callGraphAPIPaginated,
 } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
+const { quoteSearchPhrase } = require('../utils/odata-helpers');
 
 /**
  * Contact field presets for different use cases
@@ -597,7 +598,7 @@ async function handleSearchPeople(args) {
 
     const endpoint = 'me/people';
     const queryParams = {
-      $search: `"${query}"`,
+      $search: quoteSearchPhrase(query),
       $top: count,
       $select:
         'id,displayName,scoredEmailAddresses,phones,companyName,jobTitle,department,userPrincipalName,personType',

package/email/attachments.js

@@ -9,6 +9,8 @@ const path = require('path');
 const _config = require('../config'); // Reserved for future use
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
+const { buildMailboxPrefix } = require('../utils/mailbox');
+const { writeClaimedFile } = require('../utils/safe-write');
 
 const MAX_FILENAME_LENGTH = 200;
 
@@ -37,38 +39,6 @@ function safeAttachmentFilename(name) {
   return base.slice(0, MAX_FILENAME_LENGTH - ext.length) + ext;
 }
 
-/**
- * Write a buffer into outputDir without ever overwriting an existing entry
- * or following a symlink: `wx` fails on any existing path (including a
- * dangling symlink), so collisions get a numbered suffix instead.
- * @param {string} outputDir - Target directory
- * @param {string} filename - Safe basename from safeAttachmentFilename
- * @param {Buffer} buffer - File contents
- * @returns {string} - Absolute path actually written
- */
-function writeUniqueFile(outputDir, filename, buffer) {
-  const root = path.resolve(outputDir);
-  const ext = path.extname(filename);
-  const stem = filename.slice(0, filename.length - ext.length);
-
-  for (let i = 0; i < 1000; i++) {
-    const candidate = path.join(
-      root,
-      i === 0 ? filename : `${stem}-${i}${ext}`
-    );
-    if (path.dirname(candidate) !== root) {
-      throw new Error('Refusing to write attachment outside outputDir');
-    }
-    try {
-      fs.writeFileSync(candidate, buffer, { flag: 'wx' });
-      return candidate;
-    } catch (error) {
-      if (error.code !== 'EEXIST') throw error;
-    }
-  }
-  throw new Error(`Too many files named ${filename} in ${root}`);
-}
-
 /**
  * List attachments for a specific email
  * @param {object} args - Tool arguments
@@ -77,6 +47,9 @@ function writeUniqueFile(outputDir, filename, buffer) {
  */
 async function handleListAttachments(args) {
   const messageId = args.messageId;
+  // Attachment IDs live under a mailbox-scoped message ID; route to the owning
+  // shared/delegated mailbox when supplied, else the signed-in account.
+  const prefix = buildMailboxPrefix(args.sharedMailbox || args.email || null);
 
   if (!messageId) {
     return {
@@ -93,7 +66,7 @@ async function handleListAttachments(args) {
     const accessToken = await ensureAuthenticated();
 
     // Call Graph API to get attachments
-    const endpoint = `/me/messages/${messageId}/attachments`;
+    const endpoint = `${prefix}/messages/${messageId}/attachments`;
     const params = {
       $select: 'id,name,contentType,size,isInline',
     };
@@ -176,6 +149,7 @@ async function handleDownloadAttachment(args) {
   // tree with downloaded files.
   const { messageId, attachmentId } = args;
   const savePath = args.outputDir || args.savePath;
+  const prefix = buildMailboxPrefix(args.sharedMailbox || args.email || null);
 
   if (!messageId || !attachmentId) {
     return {
@@ -192,7 +166,7 @@ async function handleDownloadAttachment(args) {
     const accessToken = await ensureAuthenticated();
 
     // First, get attachment metadata to get the filename and content
-    const metadataEndpoint = `/me/messages/${messageId}/attachments/${attachmentId}`;
+    const metadataEndpoint = `${prefix}/messages/${messageId}/attachments/${attachmentId}`;
     console.error(`Fetching attachment metadata: ${attachmentId}`);
 
     const metadata = await callGraphAPI(
@@ -243,9 +217,13 @@ async function handleDownloadAttachment(args) {
 
       // Decode base64 and save to file
       const buffer = Buffer.from(contentBytes, 'base64');
-      const outputPath = writeUniqueFile(
+      const safeName = safeAttachmentFilename(filename);
+      const ext = path.extname(safeName);
+      const outputPath = writeClaimedFile(
         outputDir,
-        safeAttachmentFilename(filename),
+        safeName.slice(0, safeName.length - ext.length),
+        ext.slice(1),
+        null,
         buffer
       );
 
@@ -326,6 +304,7 @@ async function handleDownloadAttachment(args) {
  */
 async function handleGetAttachmentContent(args) {
   const { messageId, attachmentId } = args;
+  const prefix = buildMailboxPrefix(args.sharedMailbox || args.email || null);
 
   if (!messageId || !attachmentId) {
     return {
@@ -341,7 +320,7 @@ async function handleGetAttachmentContent(args) {
   try {
     const accessToken = await ensureAuthenticated();
 
-    const endpoint = `/me/messages/${messageId}/attachments/${attachmentId}`;
+    const endpoint = `${prefix}/messages/${messageId}/attachments/${attachmentId}`;
     console.error(`Fetching attachment content: ${attachmentId}`);
 
     const response = await callGraphAPI(accessToken, 'GET', endpoint, null, {});
@@ -436,4 +415,7 @@ module.exports = {
   handleListAttachments,
   handleDownloadAttachment,
   handleGetAttachmentContent,
+  // Shared with email/export.js so exported attachments get the same
+  // GHSA-755c-c45g-69rv filename hardening.
+  safeAttachmentFilename,
 };