@littlebearapps/outlook-assistant 3.11.2 → 3.12.0

package/folder/move.js

@@ -4,6 +4,7 @@
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { resolveFolder } = require('./resolve');
+const { buildMailboxPrefix } = require('../utils/mailbox');
 
 /**
  * Move emails handler
@@ -15,6 +16,7 @@ async function handleMoveEmails(args) {
   const targetFolder = args.targetFolder || '';
   const targetFolderId = args.targetFolderId || '';
   const sourceFolder = args.sourceFolder || '';
+  const sharedMailbox = args.sharedMailbox || args.email || null;
 
   if (!emailIds) {
     return {
@@ -63,7 +65,7 @@ async function handleMoveEmails(args) {
     const result = await moveEmailsToFolder(
       accessToken,
       ids,
-      { name: targetFolder, id: targetFolderId },
+      { name: targetFolder, id: targetFolderId, mailbox: sharedMailbox },
       sourceFolder
     );
 
@@ -74,6 +76,12 @@ async function handleMoveEmails(args) {
           text: result.message,
         },
       ],
+      _meta: {
+        // Graph assigns a NEW message ID on move (unless immutable IDs are
+        // enabled) — surface the mapping so callers can keep addressing them.
+        moved: result.results?.successful || [],
+        failed: result.results?.failed || [],
+      },
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
@@ -102,7 +110,7 @@ async function handleMoveEmails(args) {
  * Move emails to a folder
  * @param {string} accessToken - Access token
  * @param {Array<string>} emailIds - Array of email IDs to move
- * @param {{name?: string, id?: string}} targetSpec - Target folder name/path or ID
+ * @param {{name?: string, id?: string, mailbox?: string|null}} targetSpec - Target folder name/path or ID, plus optional shared mailbox
  * @param {string} sourceFolderName - Name of the source folder (optional)
  * @returns {Promise<object>} - Result object with status and message
  */
@@ -112,6 +120,7 @@ async function moveEmailsToFolder(
   targetSpec,
   _sourceFolderName
 ) {
+  const prefix = buildMailboxPrefix(targetSpec.mailbox);
   try {
     // Resolve the target folder (supports "Parent/Child" paths, aliases, and
     // explicit IDs — nested folders are now addressable). (#216)
@@ -133,12 +142,20 @@ async function moveEmailsToFolder(
     // Process each email one by one to handle errors independently
     for (const emailId of emailIds) {
       try {
-        // Move the email
-        await callGraphAPI(accessToken, 'POST', `me/messages/${emailId}/move`, {
-          destinationId: targetFolderId,
+        // Move the email. The response carries the moved message, whose id
+        // changes unless immutable IDs are enabled — keep it, the old id is
+        // dead afterwards.
+        const moved = await callGraphAPI(
+          accessToken,
+          'POST',
+          `${prefix}/messages/${emailId}/move`,
+          { destinationId: targetFolderId }
+        );
+
+        results.successful.push({
+          oldId: emailId,
+          newId: moved?.id || emailId,
         });
-
-        results.successful.push(emailId);
       } catch (error) {
         console.error(`Error moving email ${emailId}: ${error.message}`);
         results.failed.push({
@@ -153,6 +170,14 @@ async function moveEmailsToFolder(
 
     if (results.successful.length > 0) {
       message += `Successfully moved ${results.successful.length} email(s) to "${targetLabel}".`;
+      // Small batches: show the id mapping inline so the caller can address
+      // the moved messages without a re-search.
+      if (results.successful.length <= 5) {
+        message += '\n\nNew message IDs (old -> new):';
+        for (const { oldId, newId } of results.successful) {
+          message += `\n- ${oldId} -> ${newId}`;
+        }
+      }
     }
 
     if (results.failed.length > 0) {

package/folder/resolve.js

@@ -16,8 +16,14 @@
  *
  * `/` is the path separator, so a folder whose display name literally contains
  * `/` cannot be addressed by path — use its folderId (documented on the tool).
+ *
+ * Every function takes an optional `mailbox` (a shared/delegated mailbox email
+ * address). It only changes the Graph path prefix — `me` vs `users/{mailbox}` —
+ * so the same resolution logic reaches custom subfolders and localized folder
+ * names in a shared mailbox exactly as it does in the signed-in account.
  */
 const { callGraphAPI } = require('../utils/graph-api');
+const { buildMailboxPrefix } = require('../utils/mailbox');
 
 // Alias → Graph well-known folder name (usable directly as a path segment).
 const WELL_KNOWN = {
@@ -73,11 +79,17 @@ function ambiguousError(spec, candidates) {
  * @odata.nextLink so folders with many children resolve completely.
  * @returns {Promise<Array<{id, displayName, parentFolderId, childFolderCount}>>}
  */
-async function listChildFolders(accessToken, parentId, select = FOLDER_SELECT) {
+async function listChildFolders(
+  accessToken,
+  parentId,
+  select = FOLDER_SELECT,
+  mailbox = null
+) {
+  const prefix = buildMailboxPrefix(mailbox);
   const all = [];
   let path = parentId
-    ? `me/mailFolders/${parentId}/childFolders`
-    : 'me/mailFolders';
+    ? `${prefix}/mailFolders/${parentId}/childFolders`
+    : `${prefix}/mailFolders`;
   let params = { $top: 100, $select: select };
   // Follow pagination; nextLink already encodes params. Guard against a
   // repeated/malformed nextLink so a bad server response can't loop forever.
@@ -108,22 +120,22 @@ function toRecord(folder, path) {
   };
 }
 
-async function resolveWellKnown(accessToken, alias) {
+async function resolveWellKnown(accessToken, alias, mailbox) {
   const resp = await callGraphAPI(
     accessToken,
     'GET',
-    `me/mailFolders/${WELL_KNOWN[alias]}`,
+    `${buildMailboxPrefix(mailbox)}/mailFolders/${WELL_KNOWN[alias]}`,
     null,
     { $select: FOLDER_SELECT }
   );
   return toRecord(resp, resp.displayName);
 }
 
-async function resolveById(accessToken, id) {
+async function resolveById(accessToken, id, mailbox) {
   const resp = await callGraphAPI(
     accessToken,
     'GET',
-    `me/mailFolders/${id}`,
+    `${buildMailboxPrefix(mailbox)}/mailFolders/${id}`,
     null,
     { $select: FOLDER_SELECT }
   );
@@ -134,8 +146,9 @@ async function resolveById(accessToken, id) {
  * Build a flat list of every folder with its full path, breadth-first.
  * Accepts an already-fetched top-level list to avoid re-fetching.
  */
-async function buildTree(accessToken, topLevel) {
-  const top = topLevel || (await listChildFolders(accessToken, null));
+async function buildTree(accessToken, topLevel, mailbox = null) {
+  const top =
+    topLevel || (await listChildFolders(accessToken, null, undefined, mailbox));
   const out = [];
   const visited = new Set();
   const queue = top.map((f) => ({ folder: f, path: f.displayName, depth: 1 }));
@@ -164,7 +177,12 @@ async function buildTree(accessToken, topLevel) {
             'use an explicit folder path or folderId.'
         );
       }
-      const children = await listChildFolders(accessToken, folder.id);
+      const children = await listChildFolders(
+        accessToken,
+        folder.id,
+        undefined,
+        mailbox
+      );
       for (const child of children) {
         queue.push({
           folder: child,
@@ -186,8 +204,8 @@ function matchName(folders, name) {
  * Resolve a bare display name: a unique top-level match wins (fast path,
  * back-compat); otherwise search the whole tree, reporting ambiguity.
  */
-async function resolveByName(accessToken, name) {
-  const top = await listChildFolders(accessToken, null);
+async function resolveByName(accessToken, name, mailbox) {
+  const top = await listChildFolders(accessToken, null, undefined, mailbox);
   const topMatches = matchName(top, name);
   if (topMatches.length === 1) {
     return toRecord(topMatches[0], topMatches[0].displayName);
@@ -199,7 +217,7 @@ async function resolveByName(accessToken, name) {
     );
   }
   // Not top-level — search nested folders.
-  const tree = await buildTree(accessToken, top);
+  const tree = await buildTree(accessToken, top, mailbox);
   const matches = matchName(tree, name);
   if (matches.length === 0) {
     throw notFoundError(name);
@@ -213,13 +231,13 @@ async function resolveByName(accessToken, name) {
 /**
  * Resolve a path (segments already split/trimmed) by traversing childFolders.
  */
-async function resolvePath(accessToken, segments) {
+async function resolvePath(accessToken, segments, mailbox) {
   let current;
   const first = segments[0];
   if (WELL_KNOWN[first.toLowerCase()]) {
-    current = await resolveWellKnown(accessToken, first.toLowerCase());
+    current = await resolveWellKnown(accessToken, first.toLowerCase(), mailbox);
   } else {
-    const top = await listChildFolders(accessToken, null);
+    const top = await listChildFolders(accessToken, null, undefined, mailbox);
     const matches = matchName(top, first);
     if (matches.length === 0) {
       throw notFoundError(first);
@@ -235,7 +253,12 @@ async function resolvePath(accessToken, segments) {
 
   for (let i = 1; i < segments.length; i++) {
     const seg = segments[i];
-    const children = await listChildFolders(accessToken, current.id);
+    const children = await listChildFolders(
+      accessToken,
+      current.id,
+      undefined,
+      mailbox
+    );
     const matches = matchName(children, seg);
     if (matches.length === 0) {
       throw notFoundError(`${current.path}/${seg}`);
@@ -259,19 +282,34 @@ async function resolvePath(accessToken, segments) {
   return current;
 }
 
+/**
+ * Does a `folder` value look like a raw Graph folder ID rather than a display
+ * name or path? Graph IDs are long base64url-style tokens (`AAMkAG…`,
+ * `AQMkAD…`) with no spaces or `/`; display names that long without a space
+ * are vanishingly rare. Used where `folder` historically accepted raw IDs.
+ * @param {string} value
+ * @returns {boolean}
+ */
+function looksLikeFolderId(value) {
+  return (
+    typeof value === 'string' && /^[A-Za-z0-9_+=-]{60,}$/.test(value.trim())
+  );
+}
+
 /**
  * Resolve a folder from a name/path and/or explicit ID.
  * @param {string} accessToken
- * @param {{name?: string, id?: string}} spec
+ * @param {{name?: string, id?: string, mailbox?: string|null}} spec
  * @returns {Promise<{id: string, displayName: string, parentId: string|null, path: string}>}
  *   `path` is the full slash-separated path when resolved by name/path/alias;
  *   when resolved by ID it is the folder's display name only (ancestors are not
  *   fetched).
  */
 async function resolveFolder(accessToken, spec = {}) {
+  const mailbox = spec.mailbox || null;
   const id = (spec.id || '').trim();
   if (id) {
-    return resolveById(accessToken, id);
+    return resolveById(accessToken, id, mailbox);
   }
   const name = (spec.name || '').trim();
   if (!name) {
@@ -297,18 +335,19 @@ async function resolveFolder(accessToken, spec = {}) {
       );
     }
     if (segments.length === 1) {
-      return resolveFolder(accessToken, { name: segments[0] });
+      return resolveFolder(accessToken, { name: segments[0], mailbox });
     }
-    return resolvePath(accessToken, segments);
+    return resolvePath(accessToken, segments, mailbox);
   }
   if (WELL_KNOWN[name.toLowerCase()]) {
-    return resolveWellKnown(accessToken, name.toLowerCase());
+    return resolveWellKnown(accessToken, name.toLowerCase(), mailbox);
   }
-  return resolveByName(accessToken, name);
+  return resolveByName(accessToken, name, mailbox);
 }
 
 module.exports = {
   WELL_KNOWN,
+  looksLikeFolderId,
   resolveFolder,
   listChildFolders,
   buildTree,

package/folder/stats.js

@@ -7,6 +7,7 @@
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { resolveFolder } = require('./resolve');
+const { buildMailboxPrefix } = require('../utils/mailbox');
 const config = require('../config');
 
 const { VERBOSITY, DEFAULT_LIMITS } = config;
@@ -20,6 +21,8 @@ async function handleGetFolderStats(args) {
   const folderName = args.folder || 'inbox';
   const folderIdArg = args.folderId || '';
   const verbosity = args.outputVerbosity || VERBOSITY.STANDARD;
+  const sharedMailbox = args.sharedMailbox || args.email || null;
+  const prefix = buildMailboxPrefix(sharedMailbox);
 
   try {
     const accessToken = await ensureAuthenticated();
@@ -30,6 +33,7 @@ async function handleGetFolderStats(args) {
       resolved = await resolveFolder(accessToken, {
         name: folderName,
         id: folderIdArg,
+        mailbox: sharedMailbox,
       });
     } catch (resolveError) {
       return {
@@ -42,7 +46,7 @@ async function handleGetFolderStats(args) {
     const folder = await callGraphAPI(
       accessToken,
       'GET',
-      `me/mailFolders/${folderId}`,
+      `${prefix}/mailFolders/${folderId}`,
       null,
       {
         // Note: sizeInBytes is NOT available on mailFolder resource type
@@ -54,7 +58,7 @@ async function handleGetFolderStats(args) {
     // Get recent email dates for context
     let dateRange = null;
     if (verbosity !== VERBOSITY.MINIMAL && folder.totalItemCount > 0) {
-      dateRange = await getEmailDateRange(accessToken, folderId);
+      dateRange = await getEmailDateRange(accessToken, folderId, sharedMailbox);
     }
 
     // Format response based on verbosity
@@ -96,15 +100,17 @@ async function handleGetFolderStats(args) {
  * Get date range of emails in folder
  * @param {string} accessToken - Access token
  * @param {string} folderId - Folder ID
+ * @param {string|null} [mailbox] - Shared mailbox email, or null for the signed-in user
  * @returns {Promise<object|null>} - { oldest, newest } dates or null
  */
-async function getEmailDateRange(accessToken, folderId) {
+async function getEmailDateRange(accessToken, folderId, mailbox = null) {
+  const prefix = buildMailboxPrefix(mailbox);
   try {
     // Get newest email
     const newestResponse = await callGraphAPI(
       accessToken,
       'GET',
-      `me/mailFolders/${folderId}/messages`,
+      `${prefix}/mailFolders/${folderId}/messages`,
       null,
       {
         $select: 'receivedDateTime',
@@ -117,7 +123,7 @@ async function getEmailDateRange(accessToken, folderId) {
     const oldestResponse = await callGraphAPI(
       accessToken,
       'GET',
-      `me/mailFolders/${folderId}/messages`,
+      `${prefix}/mailFolders/${folderId}/messages`,
       null,
       {
         $select: 'receivedDateTime',

package/llms-install.md

@@ -21,7 +21,7 @@ Add to your MCP client configuration:
 
 ## Prerequisites
 
-1. **Node.js 18+** must be installed
+1. **Node.js 18.18 or newer** must be installed
 2. **Azure app registration** is required for authentication (free tier works)
 
 ## Getting the Client ID and Secret
@@ -46,16 +46,32 @@ Users must create an Azure app registration to get credentials:
 2. Add: `offline_access`, `User.Read`, `Mail.Read`, `Mail.ReadWrite`, `Mail.Send`, `Calendars.Read`, `Calendars.ReadWrite`, `Contacts.Read`, `Contacts.ReadWrite`, `People.Read`, `MailboxSettings.ReadWrite`
 3. Click "Add permissions"
 
+### Enable device code sign-in (the default auth method):
+1. Go to "Authentication" → "Add a platform" → "Mobile and desktop applications"
+2. Check `https://login.microsoftonline.com/common/oauth2/nativeclient` and click "Configure"
+3. Under "Advanced settings", set "Allow public client flows" to **Yes** and save
+
 ## First-Time Authentication
 
-After configuring the MCP server:
+After configuring the MCP server (device code flow, no auth server needed):
+
+1. Use the `auth` tool with `action=authenticate` — it returns a short code and the URL `https://microsoft.com/devicelogin`
+2. Open the URL on any device (a private/incognito window avoids cached sessions), enter the code, sign in and grant permissions
+3. Use the `auth` tool with `action=device-code-complete` — tokens are saved to `~/.outlook-assistant-tokens.json` and refresh automatically
+
+**Browser redirect flow (alternative)**: start the auth server with `npm run auth-server` from a source checkout, or `node "$(npm root -g)/@littlebearapps/outlook-assistant/outlook-auth-server.js"` from a global install, then call `auth` with `action=authenticate` and `method=browser`. The auth server reads `OUTLOOK_CLIENT_ID` and `OUTLOOK_CLIENT_SECRET` from the environment or a `.env` file in the directory you start it from.
+
+## Optional Settings
 
-1. Start the auth server: `npx @littlebearapps/outlook-assistant-auth` (or run `npm run auth-server` from source)
-2. Use the `auth` tool with `action=authenticate` to get an OAuth URL
-3. Open the URL in a browser, sign in with your Microsoft account
-4. Grant permissions — tokens are saved to `~/.outlook-assistant-tokens.json` and refresh automatically
+Add these to the same `env` block if needed:
 
-**Note**: The auth server needs `OUTLOOK_CLIENT_ID` and `OUTLOOK_CLIENT_SECRET` as environment variables. If running it separately from the MCP server, export them in your shell or create a `.env` file.
+| Variable | Purpose |
+|----------|---------|
+| `OUTLOOK_AUTH_AUDIENCE` | `consumers` for Azure apps registered as personal-accounts-only (fixes `AADSTS9002331`); `organizations` or a tenant GUID for work-only apps. Default `common` |
+| `OUTLOOK_DEFAULT_TIMEZONE` | IANA timezone for calendar times (default `Australia/Melbourne`) |
+| `OUTLOOK_MAX_EMAILS_PER_SESSION` | Cap on sends per server session |
+| `OUTLOOK_ALLOWED_RECIPIENTS` | Comma-separated allowlist of recipient domains/addresses |
+| `OUTLOOK_SHARED_MAILBOX` | Opt-in shared-mailbox support, work/school accounts only: `read` or `true` (read and organise). Also add `Mail.Read.Shared` (and `Mail.ReadWrite.Shared` for `true`) in Azure, restart, then run `auth` with `action=authenticate` and `force=true` |
 
 ## Configuration Files by Client
 
@@ -76,7 +92,8 @@ File: `~/.codeium/windsurf/mcp_config.json`
 ## Verify Installation
 
 After authentication, test with:
-- `auth` tool with `action=status` — should show "authenticated"
+- `auth` tool with `action=status` — should report "Authenticated and ready"
+- `auth` tool with `action=about` — shows the connected mailbox, version and granted scopes
 - `search-emails` with no parameters — should list recent inbox emails
 
 ## Troubleshooting
@@ -84,7 +101,9 @@ After authentication, test with:
 | Problem | Solution |
 |---------|----------|
 | "Invalid client secret" (AADSTS7000215) | Use the secret **Value**, not the Secret ID. Also check it hasn't expired. v3.11.0+ appends an explanation to Microsoft's raw error |
-| Auth URL doesn't work | Start the auth server first |
+| Auth URL doesn't work | Browser flow only: start the auth server first. With the default device code flow, use `microsoft.com/devicelogin` |
+| Device code "invalid_client" | Enable "Allow public client flows" in Azure → Authentication → Advanced settings |
+| "Shared-mailbox support is turned off" | Set `OUTLOOK_SHARED_MAILBOX`, restart, and re-authenticate with `force=true` (work/school accounts only) |
 | "EADDRINUSE :3333" | Run `npx kill-port 3333` then restart auth server |
 | Empty API responses | Run `auth` tool with `action=status` to check token |
 | Search returns no results (personal account) | Use `from`, `subject`, `to` filters instead of `query` |

package/llms.txt

@@ -9,7 +9,7 @@ Built by [Little Bear Apps](https://littlebearapps.com).
 - **Package**: `@littlebearapps/outlook-assistant` on npm
 - **Install**: `npm install -g @littlebearapps/outlook-assistant` or `npx @littlebearapps/outlook-assistant`
 - **License**: MIT
-- **Node.js**: >= 18.0.0
+- **Node.js**: >= 18.18.0 (development tooling: >= 22.22.1)
 - **Authentication**: OAuth 2.0 with Microsoft Graph API (requires Azure app registration)
 - **Tools**: 22 tools across 9 modules (reduced from 55 for optimal AI performance)
 
@@ -17,8 +17,9 @@ Built by [Little Bear Apps](https://littlebearapps.com).
 
 - Read, search, send, and export emails directly from Claude instead of switching apps
 - 8 email tools covering search, conversations, attachments, bulk export, pre-send mail tips, and draft management
-- Manage calendar events, contacts, rules, categories, and mailbox settings in one place
-- Export to multiple formats: MIME/EML, MBOX, Markdown, JSON, HTML
+- Manage calendar events (upcoming by default, or past and named events via `startAfter`/`startBefore`/`subject`), contacts, rules, categories, and mailbox settings in one place
+- Export to multiple formats: MIME/EML, MBOX, Markdown, JSON, HTML, CSV
+- Opt-in shared-mailbox read and organise support (`sharedMailbox`, work/school accounts, `OUTLOOK_SHARED_MAILBOX`); sending from a shared mailbox is not supported
 
 ## Key Differentiators
 
@@ -35,6 +36,8 @@ Built by [Little Bear Apps](https://littlebearapps.com).
 - **MCP safety annotations** on all 22 tools — AI clients auto-approve reads and prompt for destructive operations
 - **Send-email protections**: pre-send mail tips, dry-run preview, session rate limiting, recipient allowlist
 - **Rule protections**: dry-run preview on create/update, rate limiting, recipient allowlist on forward/redirect, no permanent-delete action
+- **Input and file hardening**: IDs with `.`/`..` path segments refused, the access token only ever sent to `graph.microsoft.com`, attachment downloads and exports confined to the output directory without overwriting
+- **Shared mailboxes off by default**: `.Shared` scopes are requested only when `OUTLOOK_SHARED_MAILBOX` is set (`read` keeps shared access read-only)
 - **Token-optimised**: 22 tools instead of 55 saves ~11,000 tokens per turn (~64% reduction), improving AI accuracy and context efficiency
 - These safeguards reduce risk but are not foolproof — always review actions before approving
 
@@ -59,15 +62,15 @@ Requires an Azure app registration with Microsoft Graph delegated permissions. S
 
 ## Tool Categories
 
-- **Authentication (1 tool)**: `auth` — OAuth flow, status, about
+- **Authentication (1 tool)**: `auth` — status, authenticate (device code by default), device-code-complete, about (version, granted scopes, shared-mailbox status)
 - **Email (8 tools)**: `search-emails`, `read-email`, `send-email`, `draft`, `update-email`, `attachments`, `export`, `get-mail-tips`
-- **Calendar (3 tools)**: `list-events`, `create-event`, `manage-event`
+- **Calendar (3 tools)**: `list-events` (`startAfter`, `startBefore`, `subject` filters), `create-event`, `manage-event` (update, decline, cancel, delete)
 - **Contacts (2 tools)**: `manage-contact`, `search-people`
 - **Folders (1 tool)**: `folders` — list, create, move, stats, delete; folders addressable by nested path (`Parent/Child`) or ID
 - **Rules (1 tool)**: `manage-rules` — list, create, update, reorder, delete
 - **Categories (3 tools)**: `manage-category`, `apply-category`, `manage-focused-inbox`
 - **Settings (1 tool)**: `mailbox-settings` — get, set auto-replies, set working hours
-- **Advanced (2 tools)**: `access-shared-mailbox`, `find-meeting-rooms`
+- **Advanced (2 tools)**: `access-shared-mailbox` (messages, `listFolders`, `folderId`, nested folder paths), `find-meeting-rooms`
 
 ## Documentation
 
@@ -76,9 +79,10 @@ Requires an Azure app registration with Microsoft Graph delegated permissions. S
 - [Connect Outlook to Claude](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/how-to/getting-started/connect-outlook-to-claude.md): Step-by-step setup guide for Claude Desktop / Claude Code
 - [Verify Your Connection](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/how-to/getting-started/verify-your-connection.md): Test and troubleshoot the connection after installation
 - [Azure Setup](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/guides/azure-setup.md): Azure app registration and API permissions walkthrough
+- [Troubleshooting](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/troubleshooting.md): Known errors and fixes — auth, search, export, shared mailboxes
 - [FAQ](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/faq/faq.md): Frequently asked questions — install, accounts, permissions, tokens, send safety, updates, uninstall (also at <https://littlebearapps.com/help/outlook-assistant/faq/>)
 - [CLAUDE.md](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CLAUDE.md): Quick reference for development
 - [CONTRIBUTING](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CONTRIBUTING.md): Contribution guidelines
-- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.11.2 — security release: attachment downloads confined to `outputDir` (GHSA-755c-c45g-69rv) and the access token only ever sent to Microsoft Graph (GHSA-mqfm-wfjq-jxq2), HTML-to-text entity double-decoding fixed, `npm audit` at 0. Preceded by v3.11.1 — search and export correctness: a search term combined with a date or boolean filter was silently overwritten, so the request carried only the date window and the whole window came back reported as a filtered result; batch export named files `<date>_<subject>`, so a same-day reply chain overwrote itself on disk while the summary reported `Failed 0` — filenames now carry the time, collisions get a numeric suffix instead of clobbering, and a manifest maps each requested ID to the file actually written; a truncated local scan is now disclosed when it matched, not only when it returned nothing; `query` versus `searchExpression` and the 500-message `to` scan cap documented. Preceded by v3.11.0 — fixes & polish: `--version`/`--help` CLI flags (#68), `AADSTS7000215` explaining the Secret ID vs Secret Value mistake via one shared AADSTS hint table (#69), token-refresh round trip covered end to end (#72), and all 17 development-dependency advisories cleared; and v3.10.0 — search correctness: field-scoped `searchExpression` translated to OData filters and retried on personal accounts (#217), two-filter searches no longer returning the single-filter superset (#229), `from`/`to` filter values OData-escaped (#230), no-results guidance derived from what was actually attempted (#231))
-- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.11.2 tool description audit, v3.8.x carry-over, v3.12.0+ new Graph APIs)
+- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.12.0 — opt-in shared-mailbox read and organise support via `sharedMailbox` and `OUTLOOK_SHARED_MAILBOX` (#228), `list-events` `startAfter`/`startBefore`/`subject` filters (#193), token refresh requesting the granted scopes plus `offline_access` (#241), and two security fixes: dot segments in resource paths rejected, `export` writes confined to the output directory. Preceded by v3.11.2 — security release: attachment downloads confined to `outputDir` (GHSA-755c-c45g-69rv) and the access token only ever sent to Microsoft Graph (GHSA-mqfm-wfjq-jxq2); v3.11.1 — search and export correctness (filters combined with dates no longer silently dropped, batch export no longer overwrites same-day reply chains); v3.11.0 — `--version`/`--help` CLI flags (#68) and the `AADSTS7000215` Secret ID vs Value explanation (#69); v3.10.0 — search correctness (#217, #229, #230, #231))
+- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.12.x tool description audit, v3.8.x carry-over, v3.13.0+ new Graph APIs)
 - [SECURITY](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/SECURITY.md): Security policy, token handling, and MCP safety controls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/outlook-assistant",
-  "version": "3.11.2",
+  "version": "3.12.0",
   "mcpName": "io.github.littlebearapps/outlook-assistant",
   "description": "Outlook Assistant — MCP server with 22 tools for email, calendar, contacts, and settings via Microsoft Graph API",
   "main": "index.js",
@@ -84,12 +84,12 @@
     "@commitlint/cli": "^20.4.3",
     "@commitlint/config-conventional": "^20.4.3",
     "@eslint/js": "^10.0.1",
-    "@modelcontextprotocol/inspector": "^0.21.1",
+    "@modelcontextprotocol/inspector": "^2.8.0",
     "eslint": "^10.0.2",
     "globals": "^17.4.0",
     "husky": "^9.1.7",
     "jest": "^30.2.0",
-    "lint-staged": "^16.3.2",
+    "lint-staged": "^17.6.0",
     "prettier": "^3.8.1",
     "supertest": "^7.2.2"
   },

package/utils/graph-api.js

@@ -37,6 +37,55 @@ function assertGraphUrl(url) {
   }
 }
 
+/**
+ * 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.
@@ -71,7 +120,10 @@ async function callGraphAPI(
       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('/')
@@ -292,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,
@@ -319,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
@@ -331,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 = {
@@ -434,6 +506,7 @@ async function callGraphAPIWithAuth(
 }
 
 module.exports = {
+  assertSafeResourcePath,
   callGraphAPI,
   callGraphAPIPaginated,
   callGraphAPIBatch,