@softeria/ms-365-mcp-server 0.112.2 → 0.114.0

package/dist/audit-log.js

@@ -0,0 +1,72 @@
+import winston from "winston";
+import path from "path";
+import fs from "fs";
+import os from "os";
+const logsDir = process.env.MS365_MCP_LOG_DIR || path.join(os.homedir(), ".ms-365-mcp-server", "logs");
+const FILE_MODE = 384;
+const auditLogPath = path.join(logsDir, "audit.log");
+try {
+  if (!fs.existsSync(logsDir)) {
+    fs.mkdirSync(logsDir, { recursive: true, mode: 448 });
+  }
+  if (fs.existsSync(auditLogPath)) {
+    fs.chmodSync(auditLogPath, FILE_MODE);
+  }
+} catch {
+}
+const auditLogger = winston.createLogger({
+  level: "info",
+  format: winston.format.combine(
+    winston.format.timestamp({ format: "YYYY-MM-DDTHH:mm:ss.SSSZ" }),
+    winston.format.json()
+  ),
+  defaultMeta: {
+    service: "ms-365-mcp-server",
+    stream: "audit"
+  },
+  transports: [
+    new winston.transports.Console({
+      // Route audit events to stderr so they don't collide with JSON-RPC on
+      // stdout when this server runs in stdio mode. Container platforms
+      // (Container Apps, App Service, Docker) capture both stdout and stderr
+      // and forward to Log Analytics, so the production audit sink is
+      // unaffected. Vitest sets `VITEST=true`; staying silent there avoids
+      // polluting unrelated tests that exercise the real graph-tools module.
+      stderrLevels: ["info"],
+      silent: process.env.SILENT === "true" || process.env.SILENT === "1" || process.env.VITEST === "true"
+    }),
+    new winston.transports.File({
+      filename: auditLogPath,
+      options: { flags: "a", mode: FILE_MODE }
+    })
+  ]
+});
+function isAuditLogEnabled() {
+  return process.env.MS365_MCP_AUDIT_LOG !== "false";
+}
+function auditLog(evt) {
+  if (!isAuditLogEnabled()) return;
+  auditLogger.info(evt);
+}
+function getUserIdentityForAudit(token) {
+  if (!token) return void 0;
+  try {
+    const parts = token.split(".");
+    if (parts.length < 2) return void 0;
+    let b64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const padNeeded = (4 - b64.length % 4) % 4;
+    b64 = b64 + "=".repeat(padNeeded);
+    const payload = JSON.parse(Buffer.from(b64, "base64").toString("utf-8"));
+    const candidate = payload.upn || payload.preferred_username || payload.email || payload.sub;
+    return typeof candidate === "string" ? candidate : void 0;
+  } catch {
+    return void 0;
+  }
+}
+const __testing = { auditLogger, auditLogPath };
+export {
+  __testing,
+  auditLog,
+  getUserIdentityForAudit,
+  isAuditLogEnabled
+};

package/dist/graph-client.js

@@ -2,6 +2,11 @@ import logger from "./logger.js";
 import { encode as toonEncode } from "@toon-format/toon";
 import { getCloudEndpoints } from "./cloud-config.js";
 import { getRequestTokens } from "./request-context.js";
+import {
+  fetchWithResilience,
+  getSharedBreaker,
+  loadResilienceConfig
+} from "./lib/graph-resilience.js";
 function isBinaryContentType(contentType) {
   if (!contentType) return false;
   const lower = contentType.toLowerCase().split(";")[0].trim();
@@ -102,12 +107,17 @@ class GraphClient {
       "Content-Type": "application/json",
       ...options.headers
     };
-    return fetch(url, {
-      method: options.method || "GET",
-      headers,
-      // Node's fetch accepts Buffer/Uint8Array; TS BodyInit doesn't.
-      body: options.body
-    });
+    return fetchWithResilience(
+      url,
+      {
+        method: options.method || "GET",
+        headers,
+        // Node's fetch accepts Buffer/Uint8Array; TS BodyInit doesn't.
+        body: options.body
+      },
+      loadResilienceConfig(),
+      getSharedBreaker()
+    );
   }
   serializeData(data, outputFormat, pretty = false) {
     if (outputFormat === "toon") {

package/dist/graph-tools.js

@@ -1,4 +1,6 @@
+import { randomUUID } from "crypto";
 import logger from "./logger.js";
+import { auditLog, getUserIdentityForAudit } from "./audit-log.js";
 import {
   getEndpointRequiredScopes,
   getMissingAllowedScopes,
@@ -151,6 +153,10 @@ function registerUtilityToolWithMcp(server, utility, ctx) {
 }
 async function executeGraphTool(tool, config, graphClient, params, authManager) {
   logger.info(`Tool ${tool.alias} called with params: ${JSON.stringify(params)}`);
+  const requestId = randomUUID();
+  const startTime = Date.now();
+  const upn = getUserIdentityForAudit(getRequestTokens()?.accessToken);
+  const httpMethod = tool.method.toUpperCase();
   try {
     let accountAccessToken;
     if (authManager && !authManager.isOAuthModeEnabled() && !getRequestTokens()) {
@@ -394,13 +400,34 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
       type: "text",
       text: item.text
     }));
+    auditLog({
+      event: "tool.call",
+      request_id: requestId,
+      user_principal_name: upn,
+      tool: tool.alias,
+      http_method: httpMethod,
+      status: response.isError ? "error" : "success",
+      duration_ms: Date.now() - startTime
+    });
     return {
       content,
       _meta: response._meta,
       isError: response.isError
     };
   } catch (error) {
+    const err = error;
     logger.error(`Error in tool ${tool.alias}: ${error.message}`);
+    auditLog({
+      event: "tool.call",
+      request_id: requestId,
+      user_principal_name: upn,
+      tool: tool.alias,
+      http_method: httpMethod,
+      status: "error",
+      duration_ms: Date.now() - startTime,
+      error_type: err?.name || "Error",
+      error_code: err?.status ?? err?.code
+    });
     return {
       content: [
         {

package/dist/lib/graph-resilience.js

@@ -0,0 +1,208 @@
+import logger from "../logger.js";
+function loadResilienceConfig() {
+  const intEnv = (name, fallback) => {
+    const raw = process.env[name];
+    if (raw === void 0 || raw === "") return fallback;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 0) {
+      logger.warn(`Ignoring invalid ${name}=${JSON.stringify(raw)} (use a non-negative integer)`);
+      return fallback;
+    }
+    return n;
+  };
+  return {
+    maxRetries: intEnv("MS365_MCP_GRAPH_MAX_RETRIES", 3),
+    baseBackoffMs: intEnv("MS365_MCP_GRAPH_BASE_BACKOFF_MS", 200),
+    maxBackoffMs: intEnv("MS365_MCP_GRAPH_MAX_BACKOFF_MS", 5e3),
+    fetchTimeoutMs: intEnv("MS365_MCP_GRAPH_TIMEOUT_MS", 1e5),
+    circuitFailureThreshold: intEnv("MS365_MCP_GRAPH_CIRCUIT_THRESHOLD", 5),
+    circuitCooldownMs: intEnv("MS365_MCP_GRAPH_CIRCUIT_COOLDOWN_MS", 3e4),
+    circuitDisabled: process.env.MS365_MCP_GRAPH_CIRCUIT_DISABLED === "true" || process.env.MS365_MCP_GRAPH_CIRCUIT_DISABLED === "1"
+  };
+}
+class CircuitOpenError extends Error {
+  constructor(cooldownMs) {
+    super(
+      `Graph circuit breaker is open (cooldown ${cooldownMs} ms). Upstream has failed repeatedly; refusing to flood it.`
+    );
+    this.code = "circuit_open";
+    this.name = "CircuitOpenError";
+    this.cooldownMs = cooldownMs;
+  }
+}
+class CircuitBreaker {
+  constructor(threshold, cooldownMs, disabled, now = () => Date.now()) {
+    this.threshold = threshold;
+    this.cooldownMs = cooldownMs;
+    this.disabled = disabled;
+    this.now = now;
+    this.failures = 0;
+    this.openedAt = null;
+  }
+  /**
+   * @returns the time-remaining (in ms) before the circuit can be probed,
+   *          or `null` if the circuit is closed and the call should proceed.
+   */
+  checkBeforeRequest() {
+    if (this.disabled) return null;
+    if (this.openedAt === null) return null;
+    const elapsed = this.now() - this.openedAt;
+    if (elapsed >= this.cooldownMs) {
+      return null;
+    }
+    return this.cooldownMs - elapsed;
+  }
+  recordSuccess() {
+    if (this.failures !== 0 || this.openedAt !== null) {
+      logger.info("Graph circuit: success \u2014 closing breaker");
+    }
+    this.failures = 0;
+    this.openedAt = null;
+  }
+  recordFailure() {
+    if (this.disabled) return;
+    this.failures += 1;
+    if (this.failures >= this.threshold && this.openedAt === null) {
+      this.openedAt = this.now();
+      logger.warn(
+        `Graph circuit: ${this.failures} consecutive failures \u2014 opening breaker for ${this.cooldownMs} ms`
+      );
+    } else if (this.openedAt !== null) {
+      this.openedAt = this.now();
+      logger.warn("Graph circuit: probe failed \u2014 extending cooldown");
+    }
+  }
+  /** Exposed for tests / metrics. */
+  getState() {
+    return {
+      failures: this.failures,
+      openedAt: this.openedAt,
+      open: this.checkBeforeRequest() !== null
+    };
+  }
+}
+function parseRetryAfterMs(header) {
+  if (!header) return null;
+  const trimmed = header.trim();
+  if (trimmed === "") return null;
+  const asInt = Number.parseInt(trimmed, 10);
+  if (Number.isFinite(asInt) && asInt >= 0 && String(asInt) === trimmed) {
+    return Math.min(asInt * 1e3, 6e4);
+  }
+  if (!/[-/:,]| GMT$/i.test(trimmed) && !/\s+\d/.test(trimmed)) {
+    return null;
+  }
+  const dateMs = Date.parse(trimmed);
+  if (Number.isFinite(dateMs)) {
+    const delta = dateMs - Date.now();
+    if (delta <= 0) return 0;
+    return Math.min(delta, 6e4);
+  }
+  return null;
+}
+function backoffDelayMs(attempt, baseMs, maxMs, rand = Math.random) {
+  const exp = Math.min(maxMs, baseMs * 2 ** attempt);
+  return Math.floor(rand() * exp);
+}
+function isRetriableStatus(status) {
+  return status === 429 || status === 503 || status === 504;
+}
+function isMethodIdempotent(method) {
+  const m = method.toUpperCase();
+  return m === "GET" || m === "HEAD" || m === "PUT" || m === "DELETE" || m === "OPTIONS" || m === "TRACE";
+}
+function isAbortError(err) {
+  return typeof err === "object" && err !== null && "name" in err && err.name === "AbortError";
+}
+async function fetchWithResilience(url, init, config, breaker, sleep = (ms) => new Promise((r) => setTimeout(r, ms))) {
+  const remainingCooldown = breaker.checkBeforeRequest();
+  if (remainingCooldown !== null) {
+    throw new CircuitOpenError(remainingCooldown);
+  }
+  const method = (init?.method ?? "GET").toString().toUpperCase();
+  const methodIsIdempotent = isMethodIdempotent(method);
+  let attempt = 0;
+  while (true) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), config.fetchTimeoutMs);
+    let response = null;
+    let networkError = null;
+    try {
+      response = await fetch(url, { ...init, signal: controller.signal });
+    } catch (err) {
+      networkError = err;
+    } finally {
+      clearTimeout(timer);
+    }
+    if (response !== null && !isRetriableStatus(response.status)) {
+      breaker.recordSuccess();
+      return response;
+    }
+    const is429 = response !== null && response.status === 429;
+    const retryAllowedByMethod = methodIsIdempotent || is429;
+    const canRetry = attempt < config.maxRetries && retryAllowedByMethod;
+    if (!canRetry) {
+      breaker.recordFailure();
+      if (response !== null) {
+        if (!retryAllowedByMethod && attempt === 0) {
+          logger.warn(
+            `Graph ${method} ${response.status}: not retried (non-idempotent method, side-effect may have landed)`
+          );
+        }
+        return response;
+      }
+      if (!retryAllowedByMethod && attempt === 0) {
+        logger.warn(
+          `Graph ${method} network error: not retried (non-idempotent method, side-effect may have landed)`
+        );
+      }
+      throw networkError ?? new Error("Graph fetch failed (unknown error)");
+    }
+    let delayMs;
+    if (response !== null && response.status === 429) {
+      const retryAfter = parseRetryAfterMs(response.headers.get("retry-after"));
+      delayMs = retryAfter !== null ? retryAfter : backoffDelayMs(attempt, config.baseBackoffMs, config.maxBackoffMs);
+    } else {
+      delayMs = backoffDelayMs(attempt, config.baseBackoffMs, config.maxBackoffMs);
+    }
+    const reason = response !== null ? `HTTP ${response.status}` : isAbortError(networkError) ? `timeout (${config.fetchTimeoutMs} ms)` : `network error: ${networkError?.message ?? "unknown"}`;
+    logger.warn(
+      `Graph retry ${attempt + 1}/${config.maxRetries} after ${reason} \u2014 sleeping ${delayMs} ms`
+    );
+    if (response !== null) {
+      try {
+        await response.arrayBuffer();
+      } catch {
+      }
+    }
+    breaker.recordFailure();
+    attempt += 1;
+    await sleep(delayMs);
+  }
+}
+let _sharedBreaker = null;
+function getSharedBreaker() {
+  if (_sharedBreaker === null) {
+    const cfg = loadResilienceConfig();
+    _sharedBreaker = new CircuitBreaker(
+      cfg.circuitFailureThreshold,
+      cfg.circuitCooldownMs,
+      cfg.circuitDisabled
+    );
+  }
+  return _sharedBreaker;
+}
+function __resetSharedBreakerForTests() {
+  _sharedBreaker = null;
+}
+export {
+  CircuitBreaker,
+  CircuitOpenError,
+  __resetSharedBreakerForTests,
+  backoffDelayMs,
+  fetchWithResilience,
+  getSharedBreaker,
+  isMethodIdempotent,
+  loadResilienceConfig,
+  parseRetryAfterMs
+};

package/docs/deployment.md

@@ -208,6 +208,8 @@ The client automatically discovers OAuth endpoints and opens a browser for authe
 - **Read-only mode**: use `--read-only` to disable all write operations (send, delete, update, create)
 - **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
+- **Structured audit log**: enabled by default. Every tool invocation emits one JSON line on stdout (captured by the container platform's log collector) and to `~/.ms-365-mcp-server/logs/audit.log` (mode `0o600`) with `{ event, request_id, user_principal_name, tool, http_method, status, duration_ms, error_type?, error_code? }`. The schema is intentionally narrow — tool parameters 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. 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`
 
 ## Exposed Endpoints
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softeria/ms-365-mcp-server",
-  "version": "0.112.2",
+  "version": "0.114.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",