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

package/dist/graph-tools.js

@@ -4,6 +4,12 @@ import logger from "./logger.js";
 import { auditLog, getUserIdentityForAudit } from "./audit-log.js";
 import { isDestructiveOperation } from "./lib/destructive-ops.js";
 import { describePathParam } from "./lib/path-params.js";
+import { getAttachmentMinting } from "./lib/attachment-minting.js";
+import {
+  buildAttachmentUrl,
+  isPlainGraphPath,
+  TicketStoreFullError
+} from "./lib/attachment-tickets.js";
 import {
   anyFieldPresent,
   isTransportEnvelope,
@@ -250,7 +256,13 @@ function graphResponseAuditFields(response) {
   const graphBatchErrorCodeCounts = auditStringNumberMap(
     response._meta?.graph_batch_error_code_counts
   );
+  const resultCount = auditNonNegativeInteger(response._meta?.result_count);
+  const responseBytes = auditNonNegativeInteger(response._meta?.response_bytes);
+  const resultHasMore = typeof response._meta?.result_has_more === "boolean" ? response._meta.result_has_more : void 0;
   return {
+    ...resultCount !== void 0 ? { result_count: resultCount } : {},
+    ...resultHasMore !== void 0 ? { result_has_more: resultHasMore } : {},
+    ...responseBytes !== void 0 ? { response_bytes: responseBytes } : {},
     ...httpStatus !== void 0 ? { http_status: httpStatus } : {},
     ...errorCode !== void 0 ? { error_code: errorCode } : {},
     ...graphBatchSubrequestCount !== void 0 ? { graph_batch_subrequest_count: graphBatchSubrequestCount } : {},
@@ -475,6 +487,68 @@ async function checkAccountParamInBearerMode(accountParam, authManager) {
   if (bearerIdentity && bearerIdentity.toLowerCase() === accountParam.toLowerCase()) return null;
   return `The 'account' parameter is not supported in HTTP/OAuth mode: every request uses the identity of the connecting client's bearer token` + (bearerIdentity ? ` ('${bearerIdentity}')` : "") + `, so account switching is not possible. To act as '${accountParam}', reconnect the MCP client authenticated as that account, or run the server in stdio mode (or HTTP with --trust-proxy-auth) where cached accounts are available.`;
 }
+async function mintDownloadUrl(target, accountParam, authManager) {
+  const minting = getAttachmentMinting();
+  if (!minting) return null;
+  if (authManager?.isOAuthModeEnabled() || getRequestTokens()) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: "Server-minted download URLs are unavailable when Graph identity comes from the request (OAuth, OBO, or bearer mode): the URL is redeemed later without an Authorization header, so the bytes would be fetched as a different identity than the one that asked for them. Use download-bytes."
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+  const accountModeError = await checkAccountParamInBearerMode(accountParam, authManager);
+  if (accountModeError) {
+    return {
+      content: [{ type: "text", text: JSON.stringify({ error: accountModeError }) }],
+      isError: true
+    };
+  }
+  if (!isPlainGraphPath(target)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: 'target must be a plain relative Graph path: no fragment, no query, no "." or ".." segments, and no percent-encoded separators.'
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+  let ticket;
+  try {
+    ticket = minting.store.mint(target, accountParam);
+  } catch (error) {
+    if (error instanceof TicketStoreFullError) {
+      return {
+        content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+        isError: true
+      };
+    }
+    throw error;
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          downloadUrl: buildAttachmentUrl(minting.config, ticket.id),
+          expiresAt: new Date(ticket.expiresAtMs).toISOString(),
+          singleUse: true,
+          note: "Served by this server, not by Microsoft Graph. Valid for one fetch until it expires."
+        })
+      }
+    ]
+  };
+}
 const UTILITY_TOOLS = [
   {
     name: "parse-teams-url",
@@ -702,7 +776,14 @@ const UTILITY_TOOLS = [
               })
             }
           ],
-          ...result.httpStatus !== void 0 ? { _meta: { http_status: result.httpStatus } } : {}
+          // response_bytes must describe the file written, not this receipt.
+          // Streaming to disk means the payload never appears in the response,
+          // so without this the most extraction-shaped tool in the server would
+          // audit a 250MB download at the size of an error message.
+          _meta: {
+            ...result.httpStatus !== void 0 ? { http_status: result.httpStatus } : {},
+            ...typeof result.contentLength === "number" ? { response_bytes: result.contentLength } : {}
+          }
         };
       } catch (error) {
         const metadata = thrownErrorAuditFields(error);
@@ -719,7 +800,7 @@ const UTILITY_TOOLS = [
     method: "GET",
     path: "tool:get-download-url",
     searchKeywords: "download file download drive file download onedrive file sharepoint file download large drive file large sharepoint file large file out-of-band download pre-authenticated url",
-    description: "Resolve a short-lived, pre-authenticated download URL for Microsoft Graph binary content that exposes one (drive/SharePoint file content). The returned URL streams the bytes with NO Authorization header, so the client can fetch it straight to disk (e.g. curl) without round-tripping base64 through the agent context. Prefer this over download-bytes for any file above a few KB or any bulk download. Returns { downloadUrl, name?, size?, contentType? }. NOTE: mail file attachments (/messages/{id}/attachments/{id}/$value) and meeting recordings do NOT expose a pre-authenticated URL \u2014 Graph offers no such link for them; use download-bytes for small ones.",
+    description: "Resolve a short-lived, pre-authenticated download URL for Microsoft Graph binary content that exposes one (drive/SharePoint file content). The returned URL streams the bytes with NO Authorization header, so the client can fetch it straight to disk (e.g. curl) without round-tripping base64 through the agent context. Prefer this over download-bytes for any file above a few KB or any bulk download. Returns { downloadUrl, name?, size?, contentType? }. Mail file attachments (/messages/{id}/attachments/{id}/$value), meeting recordings and other $value byte endpoints have no pre-authenticated URL from Graph itself, but call this tool for them anyway: a server running with --enable-attachment-urls mints its own single-use URL for them, and one without it answers with the reason and points at download-bytes.",
     readOnlyHint: true,
     openWorldHint: true,
     buildSchema: (ctx) => {
@@ -778,6 +859,8 @@ const UTILITY_TOOLS = [
       }
       const pathPart = target.replace(/\/+$/, "");
       if (/^(\/me|\/users\/[^/]+)\/messages\/[^/]+\/attachments\//.test(pathPart) || /^(\/me|\/users\/[^/]+)\/events\/[^/]+\/attachments\//.test(pathPart) || /^\/groups\/[^/]+\/messages\/[^/]+\/attachments\//.test(pathPart) || /^\/groups\/[^/]+\/events\/[^/]+\/attachments\//.test(pathPart)) {
+        const minted = await mintDownloadUrl(pathPart, accountParam, authManager);
+        if (minted) return minted;
         return {
           content: [
             {
@@ -793,6 +876,8 @@ const UTILITY_TOOLS = [
       if (/^(\/me|\/users\/[^/]+)\/onlineMeetings\/[^/]+\/recordings\/[^/]+(?:\/content)?$/.test(
         pathPart
       ) || /^\/communications\/calls\/[^/]+\/recordings\/[^/]+(?:\/content)?$/.test(pathPart)) {
+        const minted = await mintDownloadUrl(pathPart, accountParam, authManager);
+        if (minted) return minted;
         return {
           content: [
             {
@@ -806,6 +891,8 @@ const UTILITY_TOOLS = [
         };
       }
       if (pathPart.endsWith("/$value")) {
+        const minted = await mintDownloadUrl(pathPart, accountParam, authManager);
+        if (minted) return minted;
         return {
           content: [
             {
@@ -875,6 +962,8 @@ const UTILITY_TOOLS = [
         }
         const downloadUrl = item?.["@microsoft.graph.downloadUrl"];
         if (!downloadUrl) {
+          const minted = await mintDownloadUrl(`${itemPath}/content`, accountParam, authManager);
+          if (minted) return minted;
           return {
             content: [
               {
@@ -1300,6 +1389,7 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
           let allItems = firstValue;
           let nextLink = combinedResponse["@odata.nextLink"];
           let pageCount = 1;
+          let totalResponseBytes = response._meta?.response_bytes;
           const maxPages = positiveIntFromEnv("MS365_MCP_MAX_PAGES", DEFAULT_MAX_PAGES);
           const maxItems = positiveIntFromEnv("MS365_MCP_MAX_ITEMS", DEFAULT_MAX_ITEMS);
           let deltaLink = combinedResponse["@odata.deltaLink"];
@@ -1320,6 +1410,9 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
                 allItems = allItems.concat(nextJsonResponse.value);
               }
               nextLink = nextJsonResponse["@odata.nextLink"];
+              if (typeof totalResponseBytes === "number" && typeof nextResponse._meta?.response_bytes === "number") {
+                totalResponseBytes += nextResponse._meta.response_bytes;
+              }
               if (nextJsonResponse["@odata.deltaLink"]) {
                 deltaLink = nextJsonResponse["@odata.deltaLink"];
               }
@@ -1342,6 +1435,12 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
               combinedResponse["@odata.count"] = allItems.length;
             }
             delete combinedResponse["@odata.nextLink"];
+            response._meta = {
+              ...response._meta,
+              result_count: allItems.length,
+              result_has_more: Boolean(nextLink),
+              ...totalResponseBytes !== void 0 ? { response_bytes: totalResponseBytes } : {}
+            };
             if (deltaLink) {
               combinedResponse["@odata.deltaLink"] = deltaLink;
             }

package/dist/lib/attachment-minting.js

@@ -0,0 +1,15 @@
+let current = null;
+function configureAttachmentMinting(minting) {
+  current = minting;
+}
+function getAttachmentMinting() {
+  return current;
+}
+function resetAttachmentMinting() {
+  current = null;
+}
+export {
+  configureAttachmentMinting,
+  getAttachmentMinting,
+  resetAttachmentMinting
+};

package/dist/lib/attachment-tickets.js

@@ -0,0 +1,89 @@
+import { randomBytes } from "node:crypto";
+import { ATTACHMENT_ROUTE } from "./attachment-url-config.js";
+import { signUrl } from "./url-signing.js";
+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);
+  return signUrl(
+    url.toString(),
+    { key: config.key, keyId: config.keyId, ttlSeconds: config.ttlSeconds },
+    nowMs
+  );
+}
+const PROBE_ORIGIN = "https://graph.invalid";
+const PROBE_PREFIX = "/v1.0";
+function isPlainGraphPath(target) {
+  if (!target.startsWith("/")) return false;
+  if (target.includes("//")) return false;
+  let resolved;
+  try {
+    resolved = new URL(PROBE_ORIGIN + PROBE_PREFIX + target);
+  } catch {
+    return false;
+  }
+  return resolved.origin === PROBE_ORIGIN && resolved.search === "" && resolved.hash === "" && resolved.pathname === PROBE_PREFIX + target;
+}
+const MAX_LIVE_TICKETS = 256;
+const TICKET_BYTES = 32;
+class TicketStoreFullError extends Error {
+  constructor(limit) {
+    super(`No ticket slots available (limit ${limit}); retry once outstanding tickets expire.`);
+    this.limit = limit;
+    this.name = "TicketStoreFullError";
+  }
+}
+class AttachmentTicketStore {
+  constructor(ttlSeconds) {
+    this.ttlSeconds = ttlSeconds;
+    this.tickets = /* @__PURE__ */ new Map();
+  }
+  /** Drop every expired ticket. Called before each mint and each redemption. */
+  sweep(nowMs) {
+    for (const [id, ticket] of this.tickets) {
+      if (ticket.expiresAtMs <= nowMs) this.tickets.delete(id);
+    }
+  }
+  mint(target, accountName, nowMs = Date.now()) {
+    this.sweep(nowMs);
+    if (this.tickets.size >= MAX_LIVE_TICKETS) {
+      throw new TicketStoreFullError(MAX_LIVE_TICKETS);
+    }
+    const id = randomBytes(TICKET_BYTES).toString("base64url");
+    const expiresAtMs = nowMs + this.ttlSeconds * 1e3;
+    this.tickets.set(id, { target, accountName, expiresAtMs });
+    return { id, expiresAtMs };
+  }
+  /**
+   * Return the ticket and burn it, or undefined.
+   *
+   * One `undefined` for every failure -- unknown id, already redeemed, expired.
+   * The caller answers 404 to all three, so a probe cannot use the response to
+   * tell "never existed" from "already used", which would confirm a guessed id.
+   *
+   * The delete happens before the value is returned rather than in the caller,
+   * so an exception on the streaming path cannot leave a redeemed ticket live.
+   */
+  redeem(id, nowMs = Date.now()) {
+    this.sweep(nowMs);
+    const ticket = this.tickets.get(id);
+    if (!ticket) return void 0;
+    this.tickets.delete(id);
+    return ticket;
+  }
+  /** Live ticket count, for tests and diagnostics. Never logged with ids. */
+  size(nowMs = Date.now()) {
+    this.sweep(nowMs);
+    return this.tickets.size;
+  }
+  clear() {
+    this.tickets.clear();
+  }
+}
+export {
+  AttachmentTicketStore,
+  TICKET_PARAM,
+  TicketStoreFullError,
+  buildAttachmentUrl,
+  isPlainGraphPath
+};

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

@@ -0,0 +1,104 @@
+import { readFileSync } from "node:fs";
+const ATTACHMENT_ROUTE = "/attachment";
+const DEFAULT_TTL_SECONDS = 120;
+const MAX_TTL_SECONDS = 300;
+class AttachmentUrlConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AttachmentUrlConfigError";
+  }
+}
+const PYTHON_WHITESPACE = "	\n\v\f\r \x85\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200A\u2028\u2029\u202F\u205F\u3000";
+function pythonStrip(value) {
+  let start = 0;
+  let end = value.length;
+  while (start < end && PYTHON_WHITESPACE.includes(value[start])) start += 1;
+  while (end > start && PYTHON_WHITESPACE.includes(value[end - 1])) end -= 1;
+  return value.slice(start, end);
+}
+function readKey(env) {
+  const keyFile = env.MS365_MCP_ATTACHMENT_URL_KEY_FILE;
+  if (keyFile) {
+    try {
+      return pythonStrip(readFileSync(keyFile, "utf8"));
+    } catch {
+      throw new AttachmentUrlConfigError(
+        `MS365_MCP_ATTACHMENT_URL_KEY_FILE could not be read: ${keyFile}`
+      );
+    }
+  }
+  return env.MS365_MCP_ATTACHMENT_URL_KEY ?? "";
+}
+function loadAttachmentUrlConfig(enabled, env = process.env) {
+  if (!enabled) return null;
+  const base = env.MS365_MCP_ATTACHMENT_URL_BASE ?? "";
+  if (!base) {
+    throw new AttachmentUrlConfigError(
+      "--enable-attachment-urls requires MS365_MCP_ATTACHMENT_URL_BASE (the origin a document-conversion sidecar will fetch, e.g. http://m365-mcp:3000). This is deliberately not MS365_MCP_PUBLIC_URL: that one is browser-facing for OAuth, while this is reached server-to-server and is commonly a container address. With --attachment-port, name that port here, not the --http one: the route is not served on the MCP port at all in that mode."
+    );
+  }
+  let parsedBase;
+  try {
+    parsedBase = new URL(base);
+  } catch {
+    throw new AttachmentUrlConfigError(
+      `MS365_MCP_ATTACHMENT_URL_BASE is not a valid absolute URL: ${base}`
+    );
+  }
+  if (parsedBase.protocol !== "http:" && parsedBase.protocol !== "https:") {
+    throw new AttachmentUrlConfigError(
+      `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) {
+    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."
+    );
+  }
+  for (let index = 0; index < key.length; index += 1) {
+    const code = key.charCodeAt(index);
+    if (code < 32 || code === 127) {
+      throw new AttachmentUrlConfigError(
+        `The attachment URL signing key contains a control character at offset ${index} (value not shown).`
+      );
+    }
+  }
+  const keyId = env.MS365_MCP_ATTACHMENT_URL_KEY_ID || "1";
+  const ttlRaw = env.MS365_MCP_ATTACHMENT_URL_TTL_S;
+  let ttlSeconds = DEFAULT_TTL_SECONDS;
+  if (ttlRaw !== void 0 && ttlRaw !== "") {
+    if (!/^\d+$/.test(ttlRaw)) {
+      throw new AttachmentUrlConfigError(
+        `MS365_MCP_ATTACHMENT_URL_TTL_S must be a positive integer, got ${JSON.stringify(ttlRaw)}`
+      );
+    }
+    ttlSeconds = Number(ttlRaw);
+    if (ttlSeconds <= 0 || ttlSeconds > MAX_TTL_SECONDS) {
+      throw new AttachmentUrlConfigError(
+        `MS365_MCP_ATTACHMENT_URL_TTL_S must be between 1 and ${MAX_TTL_SECONDS}, got ${ttlSeconds}`
+      );
+    }
+  }
+  return {
+    base: parsedBase.origin,
+    key,
+    keyId,
+    ttlSeconds
+  };
+}
+export {
+  ATTACHMENT_ROUTE,
+  AttachmentUrlConfigError,
+  loadAttachmentUrlConfig
+};

package/dist/lib/url-signing.js

@@ -0,0 +1,81 @@
+import { createHmac } from "node:crypto";
+function quoteAll(value) {
+  return Array.from(new TextEncoder().encode(value)).map((byte) => {
+    const char = String.fromCharCode(byte);
+    if (/[A-Za-z0-9_.\-~]/.test(char)) return char;
+    return "%" + byte.toString(16).toUpperCase().padStart(2, "0");
+  }).join("");
+}
+function unquotePlus(value) {
+  const withSpaces = value.replace(/\+/g, " ");
+  const bytes = [];
+  for (let i = 0; i < withSpaces.length; i += 1) {
+    const char = withSpaces[i];
+    if (char === "%" && /^[0-9A-Fa-f]{2}$/.test(withSpaces.slice(i + 1, i + 3))) {
+      bytes.push(parseInt(withSpaces.slice(i + 1, i + 3), 16));
+      i += 2;
+      continue;
+    }
+    for (const byte of new TextEncoder().encode(char)) bytes.push(byte);
+  }
+  return new TextDecoder("utf-8", { fatal: false }).decode(new Uint8Array(bytes));
+}
+function compareByCodePoint(a, b) {
+  const left = Array.from(a);
+  const right = Array.from(b);
+  const shared = Math.min(left.length, right.length);
+  for (let i = 0; i < shared; i += 1) {
+    const diff = left[i].codePointAt(0) - right[i].codePointAt(0);
+    if (diff !== 0) return diff;
+  }
+  return left.length - right.length;
+}
+const RESERVED_PARAMS = /* @__PURE__ */ new Set(["dgk", "dgx", "dgs"]);
+function parseQsl(query) {
+  const pairs = [];
+  for (const field of query.split("&")) {
+    if (!field) continue;
+    const eq = field.indexOf("=");
+    const rawName = eq === -1 ? field : field.slice(0, eq);
+    const rawValue = eq === -1 ? "" : field.slice(eq + 1);
+    pairs.push([unquotePlus(rawName), unquotePlus(rawValue)]);
+  }
+  return pairs;
+}
+function canonicalQuery(query) {
+  const pairs = parseQsl(query).filter(([name]) => !RESERVED_PARAMS.has(name));
+  pairs.sort((a, b) => compareByCodePoint(a[0], b[0]) || compareByCodePoint(a[1], b[1]));
+  return pairs.map(([name, value]) => `${quoteAll(name)}=${quoteAll(value)}`).join("&");
+}
+function canonicalString(url, expiry) {
+  const parsed = new URL(url);
+  const scheme = parsed.protocol.replace(/:$/, "").toLowerCase();
+  const host = parsed.hostname.toLowerCase().replace(/^\[(.+)\]$/, "$1");
+  const port = parsed.port === "" ? scheme === "https" ? 443 : 80 : Number(parsed.port);
+  const path = parsed.pathname === "" ? "/" : parsed.pathname;
+  const query = canonicalQuery(parsed.search.replace(/^\?/, ""));
+  return ["v1", scheme, host, String(port), path, query, expiry].join("\n");
+}
+function digest(key, message) {
+  return createHmac("sha256", Buffer.from(key, "utf8")).update(Buffer.from(message, "utf8")).digest("base64url");
+}
+function signUrl(url, config, nowMs = Date.now()) {
+  const expiry = String(Math.floor(nowMs / 1e3) + config.ttlSeconds);
+  const signature = digest(config.key, canonicalString(url, expiry));
+  const parsed = new URL(url);
+  const kept = parseQsl(parsed.search.replace(/^\?/, "")).filter(
+    ([name]) => !RESERVED_PARAMS.has(name)
+  );
+  kept.push(["dgk", config.keyId], ["dgx", expiry], ["dgs", signature]);
+  parsed.search = kept.map(([name, value]) => `${quoteAll(name)}=${quoteAll(value)}`).join("&");
+  return parsed.toString();
+}
+export {
+  canonicalString,
+  compareByCodePoint,
+  digest,
+  parseQsl,
+  quoteAll,
+  signUrl,
+  unquotePlus
+};