@softeria/ms-365-mcp-server 0.135.0 → 0.136.0

package/dist/__tests__/graph-tools.test.js

@@ -89,6 +89,10 @@ async function loadModule() {
   const mod = await import("../graph-tools.js");
   return mod;
 }
+async function spyOnAuditLogger() {
+  const { __testing } = await import("../audit-log.js");
+  return vi.spyOn(__testing.auditLogger, "info").mockImplementation(() => __testing.auditLogger);
+}
 function createMockServer() {
   const tools = /* @__PURE__ */ new Map();
   return {
@@ -139,6 +143,234 @@ describe("graph-tools", () => {
       expect(url).toContain("$count=true");
     });
   });
+  describe("audit target resources", () => {
+    it("adds target_resource to generated Graph tool audit events", async () => {
+      const endpoint = makeEndpoint({
+        alias: "get-drive-item",
+        path: "/drives/:driveId/items/:driveItemId",
+        parameters: [
+          { name: "driveId", type: "Path", schema: z.string() },
+          { name: "driveItemId", type: "Path", schema: z.string() }
+        ]
+      });
+      const config = makeConfig({
+        toolName: "get-drive-item",
+        pathPattern: "/drives/{drive-id}/items/{driveItem-id}",
+        scopes: ["Files.Read"]
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        { content: [{ type: "text", text: JSON.stringify({ id: "item-2" }) }] }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const auditSpy = await spyOnAuditLogger();
+      await server.tools.get("get-drive-item").handler({
+        driveId: "drive-1",
+        driveItemId: "item-2"
+      });
+      expect(auditSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event: "tool.call",
+          tool: "get-drive-item",
+          status: "success",
+          target_resource: {
+            type: "drive_item",
+            id: "/drives/drive-1/items/item-2"
+          }
+        })
+      );
+      auditSpy.mockRestore();
+    });
+    it("adds target_resource to failed generated Graph tool audit events", async () => {
+      const endpoint = makeEndpoint({
+        alias: "get-drive-item",
+        path: "/drives/:driveId/items/:driveItemId",
+        parameters: [
+          { name: "driveId", type: "Path", schema: z.string() },
+          { name: "driveItemId", type: "Path", schema: z.string() }
+        ]
+      });
+      const config = makeConfig({
+        toolName: "get-drive-item",
+        pathPattern: "/drives/{drive-id}/items/{driveItem-id}",
+        scopes: ["Files.Read"]
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient();
+      graphClient.graphRequest.mockRejectedValueOnce(
+        Object.assign(new Error("Forbidden"), { status: 403 })
+      );
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(
+        server,
+        graphClient
+      );
+      const auditSpy = await spyOnAuditLogger();
+      const result = await server.tools.get("get-drive-item").handler({
+        driveId: "drive-1",
+        driveItemId: "item-2"
+      });
+      expect(result.isError).toBe(true);
+      expect(auditSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event: "tool.call",
+          tool: "get-drive-item",
+          status: "error",
+          error_code: 403,
+          target_resource: {
+            type: "drive_item",
+            id: "/drives/drive-1/items/item-2"
+          }
+        })
+      );
+      auditSpy.mockRestore();
+    });
+    it("derives target_resource from generic ID path parameters", async () => {
+      const endpoint = makeEndpoint({
+        alias: "get-mail-message",
+        path: "/me/messages/:messageId",
+        parameters: [{ name: "messageId", type: "Path", schema: z.string() }]
+      });
+      const config = makeConfig({
+        toolName: "get-mail-message",
+        pathPattern: "/me/messages/{message-id}"
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        { content: [{ type: "text", text: JSON.stringify({ id: "message-1" }) }] }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const auditSpy = await spyOnAuditLogger();
+      await server.tools.get("get-mail-message").handler({
+        messageId: "message-1"
+      });
+      expect(auditSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event: "tool.call",
+          tool: "get-mail-message",
+          status: "success",
+          target_resource: {
+            type: "message",
+            id: "/me/messages/message-1"
+          }
+        })
+      );
+      auditSpy.mockRestore();
+    });
+    it("omits target_resource when an ID path parameter is missing", async () => {
+      const endpoint = makeEndpoint({
+        alias: "get-drive-item",
+        path: "/drives/:driveId/items/:driveItemId",
+        parameters: [
+          { name: "driveId", type: "Path", schema: z.string() },
+          { name: "driveItemId", type: "Path", schema: z.string() }
+        ]
+      });
+      const config = makeConfig({
+        toolName: "get-drive-item",
+        pathPattern: "/drives/{drive-id}/items/{driveItem-id}",
+        scopes: ["Files.Read"]
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        { content: [{ type: "text", text: JSON.stringify({ id: "item-2" }) }] }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const auditSpy = await spyOnAuditLogger();
+      await server.tools.get("get-drive-item").handler({
+        driveId: "drive-1"
+      });
+      const [payload] = auditSpy.mock.calls[0];
+      expect(payload).toMatchObject({
+        event: "tool.call",
+        tool: "get-drive-item",
+        status: "success"
+      });
+      expect(payload).not.toHaveProperty("target_resource");
+      auditSpy.mockRestore();
+    });
+    it("omits SharePoint path parameters from target_resource", async () => {
+      const endpoint = makeEndpoint({
+        alias: "get-sharepoint-site-by-path",
+        path: "/sites/:siteId/getByPath(path=':path')",
+        parameters: [
+          { name: "siteId", type: "Path", schema: z.string() },
+          { name: "path", type: "Path", schema: z.string() }
+        ]
+      });
+      const config = makeConfig({
+        toolName: "get-sharepoint-site-by-path",
+        pathPattern: "/sites/{site-id}:/{path}",
+        scopes: [["Sites.Read.All"], ["Sites.Selected"]]
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        { content: [{ type: "text", text: JSON.stringify({ id: "site-1" }) }] }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const auditSpy = await spyOnAuditLogger();
+      await server.tools.get("get-sharepoint-site-by-path").handler({
+        siteId: "contoso.sharepoint.com",
+        path: "/sites/Finance"
+      });
+      expect(auditSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event: "tool.call",
+          tool: "get-sharepoint-site-by-path",
+          status: "success",
+          target_resource: {
+            type: "site",
+            id: "/sites/contoso.sharepoint.com"
+          }
+        })
+      );
+      const [payload] = auditSpy.mock.calls[0];
+      expect(JSON.stringify(payload)).not.toContain("Finance");
+      auditSpy.mockRestore();
+    });
+    it("omits target_resource for generated broad list/search audit events", async () => {
+      const endpoint = makeEndpoint({
+        alias: "list-mail-messages",
+        path: "/me/messages"
+      });
+      const config = makeConfig({
+        toolName: "list-mail-messages",
+        pathPattern: "/me/messages"
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        { content: [{ type: "text", text: JSON.stringify({ value: [] }) }] }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const auditSpy = await spyOnAuditLogger();
+      await server.tools.get("list-mail-messages").handler({ search: "budget" });
+      const [payload] = auditSpy.mock.calls[0];
+      expect(payload).toMatchObject({
+        event: "tool.call",
+        tool: "list-mail-messages",
+        status: "success"
+      });
+      expect(payload).not.toHaveProperty("target_resource");
+      auditSpy.mockRestore();
+    });
+  });
   describe("fetchAllPages pagination", () => {
     it("should follow @odata.nextLink and combine results", async () => {
       const endpoint = makeEndpoint();

package/dist/audit-target-resource.js

@@ -0,0 +1,75 @@
+const CONTROL_PARAM_NAMES = /* @__PURE__ */ new Set([
+  "account",
+  "confirm",
+  "fetchAllPages",
+  "includeHeaders",
+  "excludeResponse",
+  "timezone",
+  "expandExtendedProperties"
+]);
+function toCamelCase(name) {
+  return name.replace(/-([a-zA-Z])/g, (_, c) => c.toUpperCase());
+}
+function toKebabCase(name) {
+  return name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+}
+function toSnakeCase(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[-\s]+/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "").toLowerCase();
+}
+function valueForPlaceholder(placeholderName, params) {
+  const candidates = [placeholderName, toCamelCase(placeholderName), toKebabCase(placeholderName)];
+  for (const candidate of candidates) {
+    if (CONTROL_PARAM_NAMES.has(candidate)) continue;
+    const value = params[candidate];
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      return encodeURIComponent(String(value)).replace(/%3D/g, "=");
+    }
+  }
+  return void 0;
+}
+function resolveGraphPathForAudit(pathPattern, params = {}) {
+  if (!pathPattern) return void 0;
+  let resolvedPath = pathPattern;
+  resolvedPath = resolvedPath.replace(/:([A-Za-z][A-Za-z0-9-]*)/g, (match, name) => {
+    return valueForPlaceholder(name, params) ?? match;
+  });
+  resolvedPath = resolvedPath.replace(/\{([^}]+)\}/g, (match, name) => {
+    return valueForPlaceholder(name, params) ?? match;
+  });
+  if (/:([A-Za-z][A-Za-z0-9-]*)|\{[^}]+\}/.test(resolvedPath)) {
+    return void 0;
+  }
+  return resolvedPath.startsWith("/") ? resolvedPath : `/${resolvedPath}`;
+}
+function idPlaceholderBase(name) {
+  const base = name.replace(/[-_]?id\d*$/i, "");
+  if (base === name || base.length === 0) return void 0;
+  return base;
+}
+function deriveTargetResource(input) {
+  const pathPattern = input.pathPattern;
+  if (!pathPattern) return void 0;
+  const placeholderPattern = /\{([^}]+)\}|:([A-Za-z][A-Za-z0-9-]*)/g;
+  let lastTarget;
+  for (const match of pathPattern.matchAll(placeholderPattern)) {
+    const name = match[1] ?? match[2];
+    const base = idPlaceholderBase(name);
+    if (!base) continue;
+    lastTarget = {
+      base,
+      end: match.index + match[0].length
+    };
+  }
+  if (!lastTarget) return void 0;
+  const targetPattern = pathPattern.slice(0, lastTarget.end);
+  const id = resolveGraphPathForAudit(targetPattern, input.params ?? {});
+  if (!id) return void 0;
+  return {
+    type: toSnakeCase(lastTarget.base),
+    id
+  };
+}
+export {
+  deriveTargetResource,
+  resolveGraphPathForAudit
+};

package/dist/graph-tools.js

@@ -20,6 +20,7 @@ import { TOOL_CATEGORIES } from "./tool-categories.js";
 import { getRequestTokens } from "./request-context.js";
 import { parseTeamsUrl } from "./lib/teams-url-parser.js";
 import { buildBM25Index, scoreQuery, tokenize } from "./lib/bm25.js";
+import { deriveTargetResource } from "./audit-target-resource.js";
 import { describeToolSchema, describeUtilityToolSchema } from "./lib/tool-schema.js";
 import {
   TOP_UNSUPPORTED_DELTA_TOOLS,
@@ -598,6 +599,7 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
   const startTime = Date.now();
   const upn = getUserIdentityForAudit(getRequestTokens()?.accessToken);
   const httpMethod = tool.method.toUpperCase();
+  let targetResource;
   try {
     const accountParam = params.account;
     const accountModeError = await checkAccountParamInBearerMode(accountParam, authManager);
@@ -815,6 +817,10 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
     if (accountAccessToken) {
       options.accessToken = accountAccessToken;
     }
+    targetResource = deriveTargetResource({
+      pathPattern: config?.pathPattern ?? tool.path,
+      params
+    });
     const { accessToken: _redacted, ...safeOptions } = options;
     logger.info(
       `Making graph request to ${path2} with options: ${JSON.stringify(safeOptions)}${_redacted ? " [accessToken=REDACTED]" : ""}`
@@ -915,7 +921,8 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
       tool: tool.alias,
       http_method: httpMethod,
       status: response.isError ? "error" : "success",
-      duration_ms: Date.now() - startTime
+      duration_ms: Date.now() - startTime,
+      ...targetResource ? { target_resource: targetResource } : {}
     });
     return {
       content,
@@ -933,6 +940,7 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
       http_method: httpMethod,
       status: "error",
       duration_ms: Date.now() - startTime,
+      ...targetResource ? { target_resource: targetResource } : {},
       error_type: err?.name || "Error",
       error_code: err?.status ?? err?.code
     });

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 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`
+- **Structured audit log**: enabled by default. Every tool invocation 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`) with `{ event, request_id, user_principal_name, tool, http_method, status, duration_ms, target_resource?, error_type?, error_code? }`. 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, tool parameters, 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. 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,6 +1,6 @@
 {
   "name": "@softeria/ms-365-mcp-server",
-  "version": "0.135.0",
+  "version": "0.136.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",