@littlebearapps/outlook-assistant 3.11.2 → 3.12.0

package/calendar/list.js

@@ -4,6 +4,141 @@
 const config = require('../config');
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
+const {
+  escapeODataString,
+  buildODataFilter,
+} = require('../utils/odata-helpers');
+
+// An ISO 8601 instant with an explicit zone: `Z` or a ±hh:mm offset. A
+// zone-less value would be read in the server's local timezone by Date.parse,
+// so results would differ between machines; date-only values are rejected for
+// the same reason.
+const ISO_INSTANT =
+  /^(\d{4})-(\d{2})-(\d{2})T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})$/;
+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 s = typeof value === 'string' ? value.trim() : '';
+  const m = ISO_INSTANT.exec(s);
+  const parsed = m ? Date.parse(s) : NaN;
+  const valid =
+    m &&
+    !Number.isNaN(parsed) &&
+    Number(m[1]) >= 1900 &&
+    // Reject dates Date.parse would roll over, e.g. 2026-02-30 -> 2 March.
+    new Date(
+      Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]))
+    ).getUTCDate() === Number(m[3]);
+  if (!valid) {
+    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
@@ -91,6 +226,21 @@ function formatLocal(utcIso, tz) {
 async function handleListEvents(args) {
   const count = Math.min(args.count || 10, 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
     const accessToken = await ensureAuthenticated();
@@ -101,8 +251,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 +348,5 @@ handleListEvents.toUtcIso = toUtcIso;
 handleListEvents.formatLocal = formatLocal;
 
 module.exports = handleListEvents;
+module.exports.buildListEventsFilter = buildListEventsFilter;
+module.exports.listEventsOrderBy = listEventsOrderBy;

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,65 @@ 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
+];
+
 module.exports = {
   // Server information
   SERVER_NAME: 'outlook-assistant',
@@ -73,27 +131,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,

package/email/attachments.js

@@ -9,6 +9,7 @@ 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 MAX_FILENAME_LENGTH = 200;
 
@@ -77,6 +78,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 +97,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 +180,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 +197,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(
@@ -326,6 +331,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 +347,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 +442,8 @@ module.exports = {
   handleListAttachments,
   handleDownloadAttachment,
   handleGetAttachmentContent,
+  // Shared with email/export.js so exported attachments get the same
+  // GHSA-755c-c45g-69rv filename hardening.
+  safeAttachmentFilename,
+  writeUniqueFile,
 };

package/email/conversations.js

@@ -12,6 +12,8 @@ const {
 } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { getEmailFields } = require('../utils/field-presets');
+const { resolveFolderPath } = require('./folder-utils');
+const { buildMailboxPrefix } = require('../utils/mailbox');
 const {
   formatEmailContent,
   formatEmailsAsCSV,
@@ -59,6 +61,8 @@ async function handleListConversations(args) {
   const folder = args.folder || 'inbox';
   const count = Math.min(args.count || 20, 50);
   const verbosity = args.outputVerbosity || VERBOSITY.STANDARD;
+  // Optional: scope to a shared/delegated mailbox instead of the signed-in user.
+  const sharedMailbox = args.sharedMailbox || args.email || null;
 
   try {
     const accessToken = await ensureAuthenticated();
@@ -77,7 +81,13 @@ async function handleListConversations(args) {
       'bodyPreview',
     ].join(',');
 
-    const endpoint = `me/mailFolders/${folder}/messages`;
+    // resolveFolderPath handles well-known names, custom/localized names, nested
+    // paths, and raw IDs, scoped to the signed-in user or the shared mailbox.
+    const endpoint = await resolveFolderPath(
+      accessToken,
+      folder,
+      sharedMailbox
+    );
     const queryParams = {
       $select: selectFields,
       $orderby: 'receivedDateTime desc',
@@ -252,6 +262,8 @@ async function handleGetConversation(args) {
   const conversationId = args.conversationId;
   const includeHeaders = args.includeHeaders || false;
   const verbosity = args.outputVerbosity || VERBOSITY.STANDARD;
+  const sharedMailbox = args.sharedMailbox || args.email || null;
+  const prefix = buildMailboxPrefix(sharedMailbox);
 
   if (!conversationId) {
     return {
@@ -267,7 +279,7 @@ async function handleGetConversation(args) {
     const selectFields = getEmailFields(fieldPreset);
 
     // Search all folders for messages with this conversation ID
-    const endpoint = 'me/messages';
+    const endpoint = `${prefix}/messages`;
     const queryParams = {
       $select: selectFields,
       $filter: `conversationId eq '${conversationId}'`,
@@ -379,6 +391,8 @@ async function handleExportConversation(args) {
   const outputDir = args.outputDir || require('os').tmpdir();
   const _includeAttachments = args.includeAttachments !== false;
   const order = args.order || 'chronological';
+  const sharedMailbox = args.sharedMailbox || args.email || null;
+  const prefix = buildMailboxPrefix(sharedMailbox);
 
   if (!conversationId) {
     return {
@@ -403,7 +417,7 @@ async function handleExportConversation(args) {
 
     // Get all messages in conversation
     const selectFields = getEmailFields('export');
-    const endpoint = 'me/messages';
+    const endpoint = `${prefix}/messages`;
     const queryParams = {
       $select: selectFields,
       $filter: `conversationId eq '${conversationId}'`,
@@ -474,7 +488,11 @@ async function handleExportConversation(args) {
 
         for (let i = 0; i < messages.length; i++) {
           const msg = messages[i];
-          const mimeContent = await callGraphAPIRaw(accessToken, msg.id);
+          const mimeContent = await callGraphAPIRaw(
+            accessToken,
+            msg.id,
+            prefix
+          );
           const msgDate = formatDateForFilename(msg.receivedDateTime);
           const emlPath = path.join(
             emlDir,
@@ -493,7 +511,11 @@ async function handleExportConversation(args) {
         let mboxContent = '';
 
         for (const msg of messages) {
-          const mimeContent = await callGraphAPIRaw(accessToken, msg.id);
+          const mimeContent = await callGraphAPIRaw(
+            accessToken,
+            msg.id,
+            prefix
+          );
           const from = msg.from?.emailAddress?.address || 'unknown@unknown.com';
           const msgDate = new Date(msg.receivedDateTime);
           const mboxDate = msgDate.toUTCString().replace('GMT', '+0000');

package/email/delta.js

@@ -8,6 +8,60 @@ const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { formatEmailList, VERBOSITY } = require('../utils/response-formatter');
 const { getEmailFields } = require('../utils/field-presets');
+const { buildMailboxPrefix } = require('../utils/mailbox');
+const { resolveFolder, looksLikeFolderId } = require('../folder/resolve');
+
+/**
+ * Extract the mailbox segment (`me` or `users/{address}`) from a delta/
+ * continuation token URL. Returns null when the token carries no mailbox
+ * segment we can recognise (e.g. an opaque or relative value) — those are
+ * passed through untouched for backward compatibility.
+ * @param {string} token - Delta or continuation token (a full Graph URL)
+ * @returns {string|null} - Mailbox prefix found in the token path, or null
+ */
+function mailboxFromToken(token) {
+  let pathname = token;
+  try {
+    pathname = new URL(token).pathname;
+  } catch {
+    // Not an absolute URL — match against the raw value.
+  }
+  const match = pathname.match(/(?:^|\/)(me|users\/[^/]+)(?:\/|$)/i);
+  if (!match) {
+    return null;
+  }
+  // Token URLs carry the percent-encoded form; local prefixes are raw.
+  // Decode so the two compare on equal footing.
+  try {
+    return decodeURIComponent(match[1]);
+  } catch {
+    return match[1];
+  }
+}
+
+/**
+ * Decide whether a delta token's mailbox clearly differs from the target.
+ * Only identifiers of the same kind are compared: `me` against `me`, or an
+ * address against an address. Graph may hand back continuation links that
+ * name the mailbox by object ID (`users/<guid>`), which can't be matched to an
+ * address locally, so those are let through rather than wrongly rejected.
+ * @param {string} tokenMailbox - Mailbox segment from the token (`me` or `users/...`)
+ * @param {string} prefix - Mailbox prefix for this call (`me` or `users/...`)
+ * @returns {boolean} - True when the two identifiably name different mailboxes
+ */
+function mailboxesConflict(tokenMailbox, prefix) {
+  const token = tokenMailbox.toLowerCase();
+  const target = prefix.toLowerCase();
+  if (token === target) return false;
+  const isAddress = (p) => p.startsWith('users/') && p.includes('@');
+  if (token === 'me' || target === 'me') {
+    // `me` versus a named mailbox is a mismatch, unless the named one is an
+    // opaque object ID that could be the signed-in user.
+    const other = token === 'me' ? target : token;
+    return isAddress(other);
+  }
+  return isAddress(token) && isAddress(target);
+}
 
 /**
  * List emails delta handler - incremental sync
@@ -23,6 +77,10 @@ async function handleListEmailsDelta(args) {
   const deltaToken = args.deltaToken;
   const maxResults = Math.min(args.maxResults || 100, 200);
   const verbosity = args.outputVerbosity || 'standard';
+  // Optional: scope the delta sync to a shared/delegated mailbox rather than
+  // the signed-in account. Accepts a custom/localized folder name or path.
+  const sharedMailbox = args.sharedMailbox || args.email || null;
+  const prefix = buildMailboxPrefix(sharedMailbox);
 
   try {
     const accessToken = await ensureAuthenticated();
@@ -32,11 +90,39 @@ async function handleListEmailsDelta(args) {
     let queryParams = {};
 
     if (deltaToken) {
-      // Continue from previous sync - use deltaLink directly
+      // Continue from previous sync - use deltaLink directly. The token is
+      // authoritative: it already encodes the mailbox and folder, so the
+      // `folder`/`sharedMailbox` args are ignored. Reject a token from a
+      // different mailbox rather than silently syncing the wrong one.
+      const tokenMailbox = mailboxFromToken(deltaToken);
+      if (tokenMailbox && mailboxesConflict(tokenMailbox, prefix)) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text:
+                `Delta token mailbox mismatch: the token belongs to \`${tokenMailbox}\` but this call targets \`${prefix}\`.\n\n` +
+                'A delta token is bound to the mailbox and folder it was issued for. Use the token from that same mailbox/folder, or omit `deltaToken` to start a fresh initial sync here.',
+            },
+          ],
+        };
+      }
       endpoint = deltaToken;
     } else {
-      // Initial sync - start fresh
-      endpoint = `me/mailFolders/${folder}/messages/delta`;
+      // Initial sync - start fresh. Resolve the folder (well-known name,
+      // nested path, display name, or raw ID) within the target mailbox so
+      // custom subfolders work for shared mailboxes too.
+      // Resolution failures (not-found / ambiguous) carry their own actionable
+      // message; let them propagate to the handler's catch like any other error.
+      // A raw folder ID (accepted here before name resolution existed) is
+      // treated as an ID, not searched for as a display name.
+      const resolved = await resolveFolder(
+        accessToken,
+        looksLikeFolderId(folder)
+          ? { id: folder, mailbox: sharedMailbox }
+          : { name: folder, mailbox: sharedMailbox }
+      );
+      endpoint = `${prefix}/mailFolders/${resolved.id}/messages/delta`;
       queryParams = {
         $select: getEmailFields('delta'),
         $top: maxResults.toString(),
@@ -175,7 +261,11 @@ async function handleListEmailsDelta(args) {
       ],
       _meta: {
         syncType: isInitialSync ? 'initial' : 'incremental',
-        folder: folder,
+        mailbox: sharedMailbox || 'me',
+        // With a token the folder comes from the token, not the `folder` arg
+        // (which is ignored) — don't echo a value we didn't use.
+        folder: isInitialSync ? folder : null,
+        folderSource: isInitialSync ? 'argument' : 'deltaToken',
         itemCount: processedEmails.length,
         hasMoreChanges: hasMoreChanges,
         changesSummary: changesSummary,