@softeria/ms-365-mcp-server 0.150.3 → 0.152.0

package/dist/server.js

@@ -25,11 +25,16 @@ import {
   toOAuthErrorResponse
 } from "./lib/microsoft-auth.js";
 import { isAllowedRedirectUri, parseAllowlist } from "./lib/redirect-uri-validation.js";
+import { loadAttachmentUrlConfig, ATTACHMENT_ROUTE } from "./lib/attachment-url-config.js";
+import { AttachmentTicketStore } from "./lib/attachment-tickets.js";
+import { configureAttachmentMinting } from "./lib/attachment-minting.js";
+import { createAttachmentHandler } from "./attachment-route.js";
 import { getSecrets } from "./secrets.js";
 import { getCloudEndpoints } from "./cloud-config.js";
 import { requestContext } from "./request-context.js";
 import { dumpError } from "./crash-logging.js";
 import crypto from "node:crypto";
+import { isIP, isIPv6 } from "node:net";
 import OboClient from "./obo-client.js";
 function parseHttpOption(httpOption) {
   if (typeof httpOption === "boolean") {
@@ -45,12 +50,78 @@ function parseHttpOption(httpOption) {
   const port = parseInt(httpString) || 3e3;
   return { host: void 0, port };
 }
+function parseAttachmentPortOption(value) {
+  if (value === void 0 || value === null || value === "") return null;
+  const raw = String(value).trim();
+  if (!/^\d+$/.test(raw)) {
+    throw new Error(
+      `--attachment-port / MS365_MCP_ATTACHMENT_PORT must be a port number between 1 and 65535, got ${JSON.stringify(String(value))}`
+    );
+  }
+  const port = Number(raw);
+  if (port < 1 || port > 65535) {
+    throw new Error(
+      `--attachment-port / MS365_MCP_ATTACHMENT_PORT must be a port number between 1 and 65535, got ${port}`
+    );
+  }
+  return port;
+}
+const HOSTNAME_LABEL = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/;
+function isHostname(value) {
+  const name = value.endsWith(".") ? value.slice(0, -1) : value;
+  if (name.length === 0 || name.length > 253) return false;
+  return name.split(".").every((label) => label.length > 0 && label.length <= 63 && HOSTNAME_LABEL.test(label));
+}
+function parseAttachmentHostOption(value) {
+  if (value === void 0 || value === null || value === "") return null;
+  const raw = String(value).trim();
+  const reject = (reason) => {
+    throw new Error(
+      `--attachment-host / MS365_MCP_ATTACHMENT_HOST must be a bare IPv4 address, IPv6 address or hostname (${reason}), got ${JSON.stringify(String(value))}`
+    );
+  };
+  if (raw === "") reject("it is empty");
+  if (raw.startsWith("[") || raw.endsWith("]")) {
+    if (!raw.startsWith("[") || !raw.endsWith("]")) reject("unbalanced brackets");
+    const inner = raw.slice(1, -1);
+    if (!isIPv6(inner)) reject("the brackets do not contain an IPv6 address");
+    return inner;
+  }
+  if (isIP(raw) !== 0) return raw;
+  if (isHostname(raw)) return raw;
+  if (raw.includes(":")) {
+    reject("this takes a host only -- the port goes on --attachment-port");
+  }
+  return reject("not a valid address or hostname");
+}
+function isWildcardAddress(address) {
+  return address === "0.0.0.0" || address === "::" || address === "";
+}
+function formatAuthority(address, port) {
+  return isIPv6(address) ? `[${address}]:${port}` : `${address}:${port}`;
+}
+function describeBoundAddress(bound) {
+  const authority = formatAuthority(bound.address, bound.port);
+  if (isWildcardAddress(bound.address)) {
+    return { label: `all interfaces (${authority})`, authority: `localhost:${bound.port}` };
+  }
+  return { label: authority, authority };
+}
 const PKCE_MAX_AGE_MS = 60 * 60 * 1e3;
 class MicrosoftGraphServer {
   constructor(authManager, options = {}) {
     this.version = "0.0.0";
     this.multiAccount = false;
     this.accountNames = [];
+    /**
+     * Every HTTP listener `start()` opened, so `stop()` can close every one.
+     *
+     * A list rather than a field because `--attachment-port` makes it two, and an
+     * untracked listener cannot be closed at all: it holds the event loop open
+     * for the life of the process. One that is only *usually* two is worse than
+     * either, so nothing here special-cases the count.
+     */
+    this.httpServers = [];
     // Two-leg PKCE: stores client's code_challenge and server's code_verifier, keyed by OAuth state
     this.pkceStore = /* @__PURE__ */ new Map();
     this.authManager = authManager;
@@ -171,6 +242,28 @@ class MicrosoftGraphServer {
     if (this.options.readOnly) {
       logger.info("Server running in READ-ONLY mode. Write operations are disabled.");
     }
+    if (this.options.enableAttachmentUrls && !this.options.http) {
+      logger.warn(
+        "--enable-attachment-urls has no effect in stdio mode and is being ignored: the minted URL has to be reachable over HTTP. Start with --http to use it."
+      );
+    }
+    const attachmentPort = parseAttachmentPortOption(this.options.attachmentPort);
+    if (attachmentPort !== null && !this.options.enableAttachmentUrls) {
+      throw new Error(
+        "--attachment-port requires --enable-attachment-urls: on its own there is no attachment route to put on the second listener. Pass both, or neither."
+      );
+    }
+    const attachmentHost = parseAttachmentHostOption(this.options.attachmentHost);
+    if (attachmentHost !== null && attachmentPort === null) {
+      throw new Error(
+        "--attachment-host requires --attachment-port: without a second listener there is no separate interface to bind, and the attachment route stays on the MCP app."
+      );
+    }
+    if (attachmentPort !== null && !this.options.http) {
+      logger.warn(
+        "--attachment-port has no effect in stdio mode and is being ignored: there is no HTTP listener to split. Start with --http to use it."
+      );
+    }
     if (this.options.http) {
       const { host, port } = parseHttpOption(this.options.http);
       const app = express();
@@ -538,27 +631,88 @@ class MicrosoftGraphServer {
           }
         }
       );
+      const attachmentConfig = loadAttachmentUrlConfig(Boolean(this.options.enableAttachmentUrls));
+      const mintingAlwaysRefused = this.authManager?.isOAuthModeEnabled() === true || !this.options.trustProxyAuth;
+      if (attachmentConfig && mintingAlwaysRefused) {
+        logger.warn(
+          "--enable-attachment-urls is on, but this server takes its Graph identity from the request in plain --http mode, and minting is refused whenever it does (the URL is redeemed later with no Authorization header, so the bytes would be fetched as a different identity). get-download-url will keep answering with download-bytes. Server-minted URLs need --trust-proxy-auth, where the server uses its own token."
+        );
+      }
+      let attachmentApp = null;
+      if (attachmentConfig) {
+        const ticketStore = new AttachmentTicketStore(attachmentConfig.ttlSeconds);
+        configureAttachmentMinting({ store: ticketStore, config: attachmentConfig });
+        const dedicated = attachmentPort !== null;
+        attachmentApp = dedicated ? express() : app;
+        if (dedicated) {
+          attachmentApp.use(
+            helmet({
+              contentSecurityPolicy: false,
+              crossOriginEmbedderPolicy: false,
+              hsts: { maxAge: 31536e3, includeSubDomains: true, preload: true }
+            })
+          );
+        }
+        if (!rateLimitDisabled) {
+          attachmentApp.use(
+            ATTACHMENT_ROUTE,
+            rateLimit({
+              windowMs: 6e4,
+              max: 60,
+              standardHeaders: "draft-7",
+              legacyHeaders: false
+            })
+          );
+        }
+        attachmentApp.get(
+          ATTACHMENT_ROUTE,
+          createAttachmentHandler({
+            store: ticketStore,
+            getGraphClient: () => this.graphClient,
+            authManager: this.authManager
+          })
+        );
+        logger.info(
+          `  - Attachment URLs: ${attachmentConfig.base}${ATTACHMENT_ROUTE} (ttl ${attachmentConfig.ttlSeconds}s, key id ${attachmentConfig.keyId})`
+        );
+        if (dedicated) {
+          logger.info(
+            `  - Attachment listener: separate, port ${attachmentPort} (${ATTACHMENT_ROUTE} is NOT served on the MCP port; MS365_MCP_ATTACHMENT_URL_BASE must name this port)`
+          );
+        }
+      } else {
+        configureAttachmentMinting(null);
+      }
       app.get("/", (req, res) => {
         res.send("Microsoft 365 MCP Server is running");
       });
-      if (host) {
-        app.listen(port, host, () => {
-          logger.info(`Server listening on ${host}:${port}`);
-          logger.info(`  - MCP endpoint: http://${host}:${port}/mcp`);
-          logger.info(`  - OAuth endpoints: http://${host}:${port}/auth/*`);
-          logger.info(
-            `  - OAuth discovery: http://${host}:${port}/.well-known/oauth-authorization-server`
+      const mcpBound = await this.listen(app, port, host);
+      const mcp = describeBoundAddress(mcpBound);
+      logger.info(`Server listening on ${mcp.label}`);
+      logger.info(`  - MCP endpoint: http://${mcp.authority}/mcp`);
+      logger.info(`  - OAuth endpoints: http://${mcp.authority}/auth/*`);
+      logger.info(
+        `  - OAuth discovery: http://${mcp.authority}/.well-known/oauth-authorization-server`
+      );
+      if (attachmentApp && attachmentPort !== null) {
+        let attachmentBound;
+        try {
+          attachmentBound = await this.listen(
+            attachmentApp,
+            attachmentPort,
+            attachmentHost ?? host
           );
-        });
-      } else {
-        app.listen(port, () => {
-          logger.info(`Server listening on all interfaces (0.0.0.0:${port})`);
-          logger.info(`  - MCP endpoint: http://localhost:${port}/mcp`);
-          logger.info(`  - OAuth endpoints: http://localhost:${port}/auth/*`);
-          logger.info(
-            `  - OAuth discovery: http://localhost:${port}/.well-known/oauth-authorization-server`
+        } catch (error) {
+          await this.stop();
+          throw error;
+        }
+        const attachment = describeBoundAddress(attachmentBound);
+        logger.info(`Attachment listener on ${attachment.label} \u2014 serves ${ATTACHMENT_ROUTE} only`);
+        if (this.options.trustProxyAuth && this.listenersShareAnInterface(mcpBound, attachmentBound)) {
+          logger.warn(
+            `--attachment-port split ${ATTACHMENT_ROUTE} onto port ${attachmentBound.port}, but both listeners answer on the same interface (MCP ${mcp.label}, attachment ${attachment.label}), so the ports are not isolated from each other. With --trust-proxy-auth, /mcp requires no credential, so anything permitted to reach the attachment port can also call every tool. Bind them to different --http and --attachment-host addresses, or keep the MCP port off the network the attachment fetcher is on.`
           );
-        });
+        }
       }
     } else {
       const transport = new StdioServerTransport();
@@ -569,8 +723,86 @@ class MicrosoftGraphServer {
       logger.info("Server connected to stdio transport");
     }
   }
+  /**
+   * Bind one Express app and record the listener.
+   *
+   * Awaited rather than fire-and-forget, which is what `app.listen(...)` on its
+   * own was. Two consequences, both wanted. A bind failure (EADDRINUSE is the
+   * live one now that there is a second port to collide) rejects `start()`, so
+   * `index.ts` reports it and exits 1 instead of the `error` event reaching the
+   * process-wide `uncaughtException` handler as an unattributed dump. And the
+   * caller knows the port is actually accepting connections when this resolves,
+   * so the second bind cannot race the first.
+   *
+   * **The callback's argument is read, and that is not a formality.** Express 5
+   * wraps the callback passed to `app.listen` in `once()` and registers that
+   * same wrapper as the server's `error` handler (`application.js`), so a bind
+   * that fails does not skip the callback -- it calls it with an Error. The
+   * zero-argument `() => logger.info('Server listening on ...')` this replaces
+   * is the shape every example uses, and it announced a port the process had
+   * not got: on EADDRINUSE the server logged that it was listening and stayed
+   * up serving nothing.
+   */
+  async listen(app, port, host) {
+    let server;
+    await new Promise((resolve, reject) => {
+      const done = (error) => error ? reject(error) : resolve();
+      server = host ? app.listen(port, host, done) : app.listen(port, done);
+      server.once("error", reject);
+      this.httpServers.push(server);
+    });
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+      throw new Error(`Listener on port ${port} reported no TCP address`);
+    }
+    return address;
+  }
+  /**
+   * Whether the two listeners can be reached from a common interface.
+   *
+   * A wildcard on either side answers everywhere, so it overlaps whatever the
+   * other one bound -- and on Linux a dual-stack `::` accepts IPv4 too, so the
+   * families are not a distinction worth drawing here. Otherwise they overlap
+   * only if they bound the same address. Deliberately coarse in the direction of
+   * warning: `127.0.0.1` and `127.0.0.2` are two addresses on one interface,
+   * separate to `bind()` and to a container network, and a check that tried to
+   * reason about routes instead of addresses would be wrong more often than this.
+   */
+  listenersShareAnInterface(a, b) {
+    if (isWildcardAddress(a.address) || isWildcardAddress(b.address)) return true;
+    return a.address === b.address;
+  }
+  /**
+   * Close every listener this server opened.
+   *
+   * `close()` alone is not enough and the difference is not theoretical: it
+   * stops accepting but waits on established sockets, and a keep-alive client
+   * (Node's own `fetch` is one) holds one open by default, so the process hangs
+   * instead of exiting. `closeIdleConnections()` drops exactly those, while a
+   * transfer still in flight -- an attachment being streamed -- is allowed to
+   * finish.
+   *
+   * Minting is switched off at the same time. The tickets live in a store this
+   * server owns, and after this returns there is no listener left to redeem
+   * them on; continuing to hand out URLs for a dead route would be a lie the
+   * agent only discovers at fetch time.
+   */
+  async stop() {
+    const servers = this.httpServers.splice(0);
+    configureAttachmentMinting(null);
+    await Promise.all(
+      servers.map(
+        (server) => new Promise((resolve) => {
+          server.close(() => resolve());
+          server.closeIdleConnections();
+        })
+      )
+    );
+  }
 }
 var server_default = MicrosoftGraphServer;
 export {
-  server_default as default
+  server_default as default,
+  parseAttachmentHostOption,
+  parseAttachmentPortOption
 };

package/docs/deployment.md

@@ -213,7 +213,7 @@ The client automatically discovers OAuth endpoints and opens a browser for authe
 - **Tool filtering**: use `--enabled-tools <regex>` or `--preset <names>` to restrict available tools
 - **CORS**: configure `MS365_MCP_CORS_ORIGIN` to restrict allowed origins (defaults to `http://localhost:3000`); set explicitly when clients run on a different origin
 - **Disable Dynamic Client Registration**: when only a known client talks to the server, set `MS365_MCP_DISABLE_DCR=true` (or pass `--no-dynamic-registration`) to close the anonymous `/register` endpoint
-- **Structured audit log**: enabled by default. Every tool invocation that reaches Microsoft Graph emits one JSON line on stderr (captured by the container platform's log collector) and to `~/.ms-365-mcp-server/logs/audit.log` (mode `0o600`, or under `MS365_MCP_LOG_DIR` when set) with `{ event, request_id, user_principal_name, tool, http_method, http_status?, status, duration_ms, recipient_count?, recipient_domains?, recipient_domains_truncated?, graph_batch_subrequest_count?, graph_batch_http_status_counts?, graph_batch_error_code_counts?, target_resource?, error_type?, error_code? }`. A few refusals short-circuit before that and emit nothing: a confirm-gate rejection, an `account` param that contradicts the bearer identity, and a failure to resolve an account token. Policy-blocked tool attempts emit `event: "tool.denied"` with `status: "denied"`, `reason` (`allowed_scopes` or `tool_allowlist`), and `missing_scopes` when applicable. When an audited generated Microsoft Graph tool targets a derivable resource through an ID-like path parameter such as `{message-id}` or `{driveItem-id}`, `target_resource` is `{ type, id }`, where `id` is the Graph path up to that resource ID. Later path parameters such as `{path}`, query values, returned content, and Graph response bodies are NEVER recorded, and error messages are reduced to `error_type` / `error_code` so upstream library errors do not leak token fragments or query-string PII. Two things derived from tool parameters **are** recorded, both deliberately. First, `target_resource.id` substitutes ID-like path parameters into the resource path, so a tool on `/users/{user-id}/...` records whatever identifier the caller passed, which may be a full email address. Second, a request whose body carries `toRecipients` / `ccRecipients` / `bccRecipients` / `attendees` / `recipients`, at any casing and several levels down, including inside a `graph-batch` sub-request, records `recipient_count`, the number of entries in those arrays, and `recipient_domains`, the **domain part only** of their addresses and only where it parses as a plain hostname, never the local part and never a subject or message body. An entry that names someone without an address (a `driveRecipient` given as `alias` or `objectId`) counts but contributes no domain. It keys on body shape rather than on the endpoint, so it covers sends, forwards, invites and file shares but equally draft creation and edits, event updates and `findMeetingTimes`, and it reads high rather than low: an attached message's own recipients are counted too. `recipient_domains` holds at most 50 **distinct domains**, alphabetically, and sets `recipient_domains_truncated: true` when there were more; `recipient_count` is unaffected by the cap. All three are absent when the body carries no recipient array at all. A request that fails after reaching Graph still records recipients, since a timeout is not proof of non-delivery. Gaps remain, so absence proves nothing: a draft composed outside this server and sent by id, the original thread's recipients on a reply (Graph resolves those server-side), and a body nesting recipients deeper than the walker descends. This describes the structured audit log only; the operational logger is separate and does log tool parameters. Forms the "who accessed what, when" trail required for GDPR / HIPAA / PIPEDA / SOC 2 audit. Opt-out: `MS365_MCP_AUDIT_LOG=false`
+- **Structured audit log**: enabled by default. Every tool invocation that reaches Microsoft Graph emits one JSON line on stderr (captured by the container platform's log collector) and to `~/.ms-365-mcp-server/logs/audit.log` (mode `0o600`, or under `MS365_MCP_LOG_DIR` when set) with `{ event, request_id, user_principal_name, tool, http_method, http_status?, status, duration_ms, recipient_count?, recipient_domains?, recipient_domains_truncated?, graph_batch_subrequest_count?, graph_batch_http_status_counts?, graph_batch_error_code_counts?, result_count?, result_has_more?, response_bytes?, target_resource?, error_type?, error_code? }`. A few refusals short-circuit before that and emit nothing: a confirm-gate rejection, an `account` param that contradicts the bearer identity, and a failure to resolve an account token. Policy-blocked tool attempts emit `event: "tool.denied"` with `status: "denied"`, `reason` (`allowed_scopes` or `tool_allowlist`), and `missing_scopes` when applicable. When an audited generated Microsoft Graph tool targets a derivable resource through an ID-like path parameter such as `{message-id}` or `{driveItem-id}`, `target_resource` is `{ type, id }`, where `id` is the Graph path up to that resource ID. Later path parameters such as `{path}`, query values, returned content, and Graph response bodies are NEVER recorded, and error messages are reduced to `error_type` / `error_code` so upstream library errors do not leak token fragments or query-string PII. Response _metadata_ is recorded — `result_count`, `result_has_more` and `response_bytes` describe how much came back so that a bulk read is distinguishable from an ordinary one; none of them reveals any of its content. Two things derived from tool parameters **are** recorded, both deliberately. First, `target_resource.id` substitutes ID-like path parameters into the resource path, so a tool on `/users/{user-id}/...` records whatever identifier the caller passed, which may be a full email address. Second, a request whose body carries `toRecipients` / `ccRecipients` / `bccRecipients` / `attendees` / `recipients`, at any casing and several levels down, including inside a `graph-batch` sub-request, records `recipient_count`, the number of entries in those arrays, and `recipient_domains`, the **domain part only** of their addresses and only where it parses as a plain hostname, never the local part and never a subject or message body. An entry that names someone without an address (a `driveRecipient` given as `alias` or `objectId`) counts but contributes no domain. It keys on body shape rather than on the endpoint, so it covers sends, forwards, invites and file shares but equally draft creation and edits, event updates and `findMeetingTimes`, and it reads high rather than low: an attached message's own recipients are counted too. `recipient_domains` holds at most 50 **distinct domains**, alphabetically, and sets `recipient_domains_truncated: true` when there were more; `recipient_count` is unaffected by the cap. All three are absent when the body carries no recipient array at all. A request that fails after reaching Graph still records recipients, since a timeout is not proof of non-delivery. Gaps remain, so absence proves nothing: a draft composed outside this server and sent by id, the original thread's recipients on a reply (Graph resolves those server-side), and a body nesting recipients deeper than the walker descends. This describes the structured audit log only; the operational logger is separate and does log tool parameters. Forms the "who accessed what, when" trail required for GDPR / HIPAA / PIPEDA / SOC 2 audit. Opt-out: `MS365_MCP_AUDIT_LOG=false`
 - **Graph resilience**: every call to Microsoft Graph is wrapped with a fetch timeout (default 100 s via `MS365_MCP_GRAPH_TIMEOUT_MS`), retry-with-backoff on 429 / 503 / 504 / network errors (default 3 retries, full-jitter exponential backoff, honours `Retry-After`; 503 / 504 / network errors only retried for idempotent methods, 429 retried on all methods), and a process-wide circuit breaker that opens after 5 consecutive failures and cools down for 30 s (`MS365_MCP_GRAPH_CIRCUIT_THRESHOLD` / `MS365_MCP_GRAPH_CIRCUIT_COOLDOWN_MS`). Disable the breaker for trusted automation: `MS365_MCP_GRAPH_CIRCUIT_DISABLED=true`
 - **Confirm gate on destructive tools**: opt-in, **off by default**. Enable with `MS365_MCP_REQUIRE_CONFIRM=true`. When on, destructive tools (POST except `readOnly`, PATCH, PUT, DELETE — `delete-mail-message`, `send-mail`, `update-event`, etc.) return `{ "error": "confirmation_required" }` until the caller re-invokes them with `"confirm": true`. Mitigates accidental writes when an LLM misroutes a request or follows an injected instruction. Shipped opt-in so it is a non-breaking, additive layer that can coexist with client-side elicitation prompts (MCP Elicitation API) where the client supports them.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@softeria/ms-365-mcp-server",
   "mcpName": "io.github.Softeria/ms-365-mcp-server",
-  "version": "0.150.3",
+  "version": "0.152.0",
   "description": " A Model Context Protocol (MCP) server for interacting with Microsoft 365 and Office services through the Graph API",
   "type": "module",
   "main": "dist/index.js",