@softeria/ms-365-mcp-server 0.161.4 → 0.162.0

package/README.md

@@ -809,16 +809,21 @@ is refused with the same 404 as any other bad ticket.
 
 ```
 MS365_MCP_ATTACHMENT_URL_BASE=http://m365-mcp:3000   # required
-MS365_MCP_ATTACHMENT_URL_KEY=...                     # required (or _KEY_FILE=/path)
-MS365_MCP_ATTACHMENT_URL_KEY_ID=1                    # optional, default 1
+MS365_MCP_ATTACHMENT_URL_KEY=...                     # optional (or _KEY_FILE=/path), see below
+MS365_MCP_ATTACHMENT_URL_KEY_ID=1                    # optional, default 1; needs a key
 MS365_MCP_ATTACHMENT_URL_TTL_S=120                   # optional, default 120, max 300
 ```
 
 `MS365_MCP_ATTACHMENT_URL_BASE` is deliberately **not** `MS365_MCP_PUBLIC_URL`: that one is
 browser-facing, for OAuth redirects, while this is fetched server-to-server and is
 commonly a container address. A missing or malformed setting fails at startup rather than
-per-request — a signing feature that comes up without a key would mint URLs nothing can
-verify, silently.
+per-request.
+
+The signing key is optional. Without one, minted URLs are just `/attachment?t=<ticket>` and
+any HTTP client can fetch them; the ticket alone authorises redemption. Set a key only if
+the fetcher verifies the `dgk`/`dgx`/`dgs` signature (see below), such as a docglean-mcp
+sidecar, which will refuse an unsigned URL. Setting `_KEY_ID` without a key, or a `_KEY_FILE` that is
+empty or unreadable, fails at startup.
 
 ### Splitting the attachment listener
 
@@ -904,9 +909,10 @@ directly.
 `--attachment-host` takes a bare IPv4 address, IPv6 address (bracketed `[::1]` or bare
 `::1`) or hostname. It is refused rather than coerced — `--attachment-host 10.0.0.5:3001`
 is an error naming `--attachment-port`, not a bind to something else. Note that
-`MS365_MCP_ATTACHMENT_URL_BASE` still must not be an IPv6 literal (the URL signature covers
-the host and the two implementations normalise IPv6 differently); if you bind the listener
-to an IPv6 address, name it in the base by hostname.
+with a signing key set, `MS365_MCP_ATTACHMENT_URL_BASE` must not be an IPv6 literal (the URL
+signature covers the host and the two implementations normalise IPv6 differently); if you
+bind the listener to an IPv6 address, name it in the base by hostname. Without a key there
+is no such restriction.
 
 Point `MS365_MCP_ATTACHMENT_URL_BASE` at the attachment port. The server cannot check this
 for you: the base is usually a container name on a network this process cannot resolve, so
@@ -915,7 +921,7 @@ base and the bound port are logged at startup, one line apart, for exactly that
 
 ### The signature, and who checks what
 
-`dgk`/`dgx`/`dgs` are **not** checked by this server on redemption, and that is deliberate.
+This server never checks `dgk`/`dgx`/`dgs` on redemption, and that is deliberate.
 They exist for the fetcher: a document-conversion sidecar that refuses to dial a private
 address unless the URL carries a valid HMAC from an origin it has been configured to trust.
 What authorises redemption _here_ is the ticket. Verifying the signature on the way back in

package/dist/cli.js

@@ -29,7 +29,7 @@ program.name("ms-365-mcp-server").description("Microsoft 365 MCP Server").versio
   "Enable login/logout tools when using HTTP mode (disabled by default in HTTP mode)"
 ).option(
   "--enable-attachment-urls",
-  "HTTP mode only. Let get-download-url mint a short-TTL, single-use URL served by this server for Graph byte resources that expose no pre-authenticated URL of their own (mail and event attachments, meeting recordings, other $value endpoints). Also adds get-download-url to any --preset that lacks it (except teams-write). Requires MS365_MCP_ATTACHMENT_URL_BASE and MS365_MCP_ATTACHMENT_URL_KEY (or _KEY_FILE)"
+  "HTTP mode only. Let get-download-url mint a short-TTL, single-use URL served by this server for Graph byte resources that expose no pre-authenticated URL of their own (mail and event attachments, meeting recordings, other $value endpoints). Also adds get-download-url to any --preset that lacks it (except teams-write). Requires MS365_MCP_ATTACHMENT_URL_BASE; MS365_MCP_ATTACHMENT_URL_KEY (or _KEY_FILE) is optional and adds an HMAC signature for fetchers that verify one"
 ).option(
   "--attachment-port <port>",
   "HTTP mode only. Serve the attachment download route on its own listener on this port instead of on the MCP app, so a caller that can fetch attachments cannot also reach /mcp. Requires --enable-attachment-urls, and MS365_MCP_ATTACHMENT_URL_BASE must name this port. A separate port only isolates the two surfaces if they also bind separate interfaces \u2014 see --attachment-host. Equivalent env var: MS365_MCP_ATTACHMENT_PORT."

package/dist/lib/attachment-tickets.js

@@ -5,6 +5,7 @@ const TICKET_PARAM = "t";
 function buildAttachmentUrl(config, ticketId, nowMs = Date.now()) {
   const url = new URL(ATTACHMENT_ROUTE, config.base);
   url.searchParams.set(TICKET_PARAM, ticketId);
+  if (!config.key) return url.toString();
   return signUrl(
     url.toString(),
     { key: config.key, keyId: config.keyId, ttlSeconds: config.ttlSeconds },

package/dist/lib/attachment-url-config.js

@@ -19,13 +19,20 @@ function pythonStrip(value) {
 function readKey(env) {
   const keyFile = env.MS365_MCP_ATTACHMENT_URL_KEY_FILE;
   if (keyFile) {
+    let key;
     try {
-      return pythonStrip(readFileSync(keyFile, "utf8"));
+      key = pythonStrip(readFileSync(keyFile, "utf8"));
     } catch {
       throw new AttachmentUrlConfigError(
         `MS365_MCP_ATTACHMENT_URL_KEY_FILE could not be read: ${keyFile}`
       );
     }
+    if (!key) {
+      throw new AttachmentUrlConfigError(
+        `MS365_MCP_ATTACHMENT_URL_KEY_FILE is empty: ${keyFile}. Unset it to mint unsigned URLs.`
+      );
+    }
+    return key;
   }
   return env.MS365_MCP_ATTACHMENT_URL_KEY ?? "";
 }
@@ -50,20 +57,26 @@ function loadAttachmentUrlConfig(enabled, env = process.env) {
       `MS365_MCP_ATTACHMENT_URL_BASE must be http or https, got ${parsedBase.protocol}`
     );
   }
-  if (parsedBase.hostname.startsWith("[")) {
-    throw new AttachmentUrlConfigError(
-      `MS365_MCP_ATTACHMENT_URL_BASE must not be an IPv6 literal: the URL signature covers the host, and this runtime and the verifying sidecar normalise IPv6 spellings differently, so every minted URL would be refused. Use a hostname (a container or service name) instead of ${parsedBase.hostname}.`
-    );
-  }
   if (parsedBase.search || parsedBase.hash) {
     throw new AttachmentUrlConfigError(
       "MS365_MCP_ATTACHMENT_URL_BASE must not carry a query string or fragment."
     );
   }
   const key = readKey(env);
-  if (!key) {
+  if (key && !key.trim()) {
+    throw new AttachmentUrlConfigError(
+      "MS365_MCP_ATTACHMENT_URL_KEY is whitespace only. Set a real key, or unset it to mint unsigned URLs."
+    );
+  }
+  if (key) {
+    if (parsedBase.hostname.startsWith("[")) {
+      throw new AttachmentUrlConfigError(
+        `MS365_MCP_ATTACHMENT_URL_BASE must not be an IPv6 literal: the URL signature covers the host, and this runtime and the verifying sidecar normalise IPv6 spellings differently, so every minted URL would be refused. Use a hostname (a container or service name) instead of ${parsedBase.hostname}.`
+      );
+    }
+  } else if (env.MS365_MCP_ATTACHMENT_URL_KEY_ID) {
     throw new AttachmentUrlConfigError(
-      "--enable-attachment-urls requires MS365_MCP_ATTACHMENT_URL_KEY or MS365_MCP_ATTACHMENT_URL_KEY_FILE -- the HMAC key shared with the sidecar that will verify the minted URL."
+      "MS365_MCP_ATTACHMENT_URL_KEY_ID is set but no signing key is: set MS365_MCP_ATTACHMENT_URL_KEY or MS365_MCP_ATTACHMENT_URL_KEY_FILE, or unset the key id."
     );
   }
   for (let index = 0; index < key.length; index += 1) {
@@ -92,7 +105,7 @@ function loadAttachmentUrlConfig(enabled, env = process.env) {
   }
   return {
     base: parsedBase.origin,
-    key,
+    key: key || void 0,
     keyId,
     ttlSeconds
   };

package/dist/server.js

@@ -730,7 +730,7 @@ class MicrosoftGraphServer {
         attachmentApp.get(ATTACHMENT_ROUTE, createAttachmentHandler(attachmentDeps));
         attachmentApp.put(ATTACHMENT_ROUTE, createAttachmentUploadHandler(attachmentDeps));
         logger.info(
-          `  - Attachment URLs: ${attachmentConfig.base}${ATTACHMENT_ROUTE} (ttl ${attachmentConfig.ttlSeconds}s, key id ${attachmentConfig.keyId})`
+          `  - Attachment URLs: ${attachmentConfig.base}${ATTACHMENT_ROUTE} (ttl ${attachmentConfig.ttlSeconds}s, ${attachmentConfig.key ? `signed, key id ${attachmentConfig.keyId}` : "unsigned"})`
         );
         if (dedicated) {
           logger.info(

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@softeria/ms-365-mcp-server",
   "mcpName": "io.github.Softeria/ms-365-mcp-server",
-  "version": "0.161.4",
+  "version": "0.162.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",