cap-mcp-guard 0.3.0 → 0.3.1

package/lib/adapters/cap.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const fs = require('fs');
 const path = require('path');
 
 const { attachInterceptor } = require('../core/interceptor');
@@ -7,23 +8,42 @@ const { loadConfig, NOT_CONFIGURED_PREFIX } = require('../policy/config');
 const { logAudit } = require('../audit/log');
 const { exportSpan } = require('../otel/exporter');
 
+// Versions before 0.3.0 read policy from this file instead of package.json. It is no
+// longer read at all — see resolvePolicyDefinition()'s legacy-file check below, which
+// exists specifically so an unmigrated project fails loudly instead of silently running
+// with zero enforcement.
+const LEGACY_YAML_FILENAME = 'cap-mcp-guard.yaml';
+
 /**
  * Loads the `"cap-mcp-guard"` key from the host CAP project's package.json.
  * A missing package.json or a missing key is a valid "not configured yet"
  * state — falls back to a pass-through PolicyDefinition (every entity is
- * opt-in, so this is equivalent to no policy at all). A config that exists
- * but fails to parse is a user mistake and is NOT swallowed — it propagates
- * so the bad config gets noticed rather than silently ignored.
+ * opt-in, so this is equivalent to no policy at all), UNLESS a legacy
+ * `cap-mcp-guard.yaml` is sitting right there (see LEGACY_YAML_FILENAME): that
+ * almost certainly means an unmigrated pre-0.3.0 project, and starting up
+ * silently unenforced would be worse than refusing to start. A config that
+ * exists but fails to parse is a user mistake and is NOT swallowed either —
+ * it propagates so the bad config gets noticed rather than silently ignored.
  *
  * @param {object} cds the @sap/cds module (used only for cds.root)
  */
 function resolvePolicyDefinition(cds) {
-  const configPath = path.join(cds.root || process.cwd(), 'package.json');
+  const root = cds.root || process.cwd();
+  const configPath = path.join(root, 'package.json');
 
   try {
     return loadConfig(configPath);
   } catch (err) {
     if (err.message.startsWith(NOT_CONFIGURED_PREFIX)) {
+      const legacyYamlPath = path.join(root, LEGACY_YAML_FILENAME);
+      if (fs.existsSync(legacyYamlPath)) {
+        throw new Error(
+          `[cap-mcp-guard] found "${LEGACY_YAML_FILENAME}" at ${legacyYamlPath}, but this file has not been read ` +
+            'since 0.3.0 — config now lives under the "cap-mcp-guard" key in package.json. Move its contents there ' +
+            '(or delete the file, if you no longer want a policy) before starting the server. Refusing to start ' +
+            'rather than run with zero enforcement silently.'
+        );
+      }
       console.warn('[cap-mcp-guard] no config found, running in pass-through mode (no policies enforced)');
       return { mode: 'observe', entities: {} };
     }
@@ -46,7 +66,10 @@ function resolvePolicyDefinition(cds) {
  *   `"cap-mcp-guard"` key in the project's package.json (see resolvePolicyDefinition)
  * @param {object|false} [options.audit] forwarded to logAudit()'s write
  *   options (`{ stdout, filePath }`); pass `false` to disable audit
- *   logging entirely.
+ *   logging entirely. When omitted, falls back to the `"audit"` key parsed
+ *   from package.json's `"cap-mcp-guard"` config (see lib/policy/config.js) —
+ *   this is what lets `audit.filePath` be set through config alone, without
+ *   hand-writing a registerCapMcpGuard() call.
  * @param {object|false} [options.otel] forwarded to exportSpan()'s options
  *   (`{ tracer }`); pass `false` to skip OTel span export entirely. With
  *   no host-configured OTel SDK this is already a harmless no-op, so the
@@ -70,7 +93,8 @@ function resolvePolicyDefinition(cds) {
  */
 function registerCapMcpGuard(cds, options = {}) {
   const policyDefinition = options.policyDefinition || resolvePolicyDefinition(cds);
-  const { onDecision: userOnDecision, audit, otel } = options;
+  const { onDecision: userOnDecision, otel } = options;
+  const audit = options.audit !== undefined ? options.audit : policyDefinition.audit;
 
   const pseudonymSecret = options.pseudonymSecret || process.env.CAP_MCP_GUARD_PSEUDONYM_SECRET;
   const usesPseudonymize = Object.values(policyDefinition.entities).some(

package/lib/core/interceptor.js

@@ -99,6 +99,67 @@ function applyPseudonymize(results, fieldsToPseudonymize, secret) {
   });
 }
 
+/**
+ * Finds the association/composition elements on a CAP entity definition, along with the
+ * (already service-qualified) entity name each one targets — e.g. for `Employees.department`,
+ * `{ name: 'department', targetEntity: 'CatalogService.Departments' }`. That target name is
+ * exactly what a request against `Departments` directly would resolve via resolveEntity(),
+ * so the same `policyDefinition.entities` keys apply to nested rows without any separate
+ * EDM/$metadata resolution — CAP's own compiled model already carries it.
+ *
+ * @param {object} target req.target — a linked CSN entity definition, or undefined
+ * @returns {{name: string, targetEntity: string}[]}
+ */
+function findAssociationElements(target) {
+  if (!target || !target.elements) return [];
+
+  return Object.entries(target.elements)
+    .filter(([, el]) => el && (el.type === 'cds.Association' || el.type === 'cds.Composition'))
+    .map(([name, el]) => ({
+      name,
+      targetEntity: (el._target && el._target.name) || el.target
+    }))
+    .filter((assoc) => assoc.targetEntity);
+}
+
+/**
+ * Applies each expanded association's own policy (mask/pseudonymize) to the nested
+ * row(s) hanging off of it — one level deep, matching what `$expand` actually returns.
+ * Mutates `results` in place, same convention as applyMask()/applyPseudonymize(). A no-op
+ * when the request's entity has no associations, or none of them were expanded (the nav
+ * property is simply absent from the row), or the target entity has no policy configured.
+ *
+ * @param {object|object[]} results
+ * @param {object} target req.target — see findAssociationElements()
+ * @param {object} policyDefinition see lib/policy/config.js
+ * @param {string} [pseudonymSecret] forwarded to applyPseudonymize() for nested fields
+ */
+function applyNestedPolicy(results, target, policyDefinition, pseudonymSecret) {
+  const associations = findAssociationElements(target);
+  if (!associations.length) return;
+
+  const rows = Array.isArray(results) ? results : [results];
+
+  for (const row of rows) {
+    if (!row || typeof row !== 'object') continue;
+
+    for (const { name, targetEntity } of associations) {
+      const navValue = row[name];
+      if (navValue === undefined || navValue === null) continue;
+
+      const entityConfig = policyDefinition.entities[targetEntity];
+      if (!entityConfig) continue;
+
+      if (entityConfig.mask && entityConfig.mask.length > 0) {
+        applyMask(navValue, entityConfig.mask);
+      }
+      if (entityConfig.pseudonymize && entityConfig.pseudonymize.length > 0) {
+        applyPseudonymize(navValue, entityConfig.pseudonymize, pseudonymSecret);
+      }
+    }
+  }
+}
+
 /**
  * Attaches request interception to a CAP service instance, producing a
  * guard context (see context.js) for every request that passes through it.
@@ -134,9 +195,47 @@ function attachInterceptor(srv, options = {}) {
   const { onContext, policyDefinition, onDecision, now, pseudonymSecret } = options;
   const clockDeps = now ? { now } : {};
 
+  function buildRequestContext(req, extra) {
+    return buildContext(
+      {
+        ...extractAgentInfo(req),
+        ...extractTraceContext(req),
+        entity: resolveEntity(req),
+        operation: resolveOperation(req),
+        tenant: req.tenant,
+        user: req.user && req.user.id,
+        session: req.id,
+        ...extra
+      },
+      clockDeps
+    );
+  }
+
   srv.before('*', (req) => {
     if (!req) return;
     req._mcpGuardStartedAt = process.hrtime.bigint();
+
+    if (!policyDefinition) return;
+
+    // allowTools is a gate, not a masking rule — it has to be enforced before the
+    // query runs, not after. rowCount/durationMs aren't known yet, but `allowed`
+    // never depends on either, so this decision is already final.
+    const context = buildRequestContext(req, {});
+    const decision = evaluate(context, policyDefinition);
+
+    if (decision.mode === 'enforce' && !decision.allowed) {
+      // req.reject() throws in real CAP requests, so srv.after('*') below never runs
+      // for a denied request — report it here instead, or the denial would never be
+      // audited/traced at all.
+      if (typeof onContext === 'function') onContext(context, req);
+      if (typeof onDecision === 'function') onDecision(decision, context, req);
+
+      if (typeof req.reject === 'function') {
+        req.reject(403, decision.reason);
+      } else {
+        throw new Error(decision.reason);
+      }
+    }
   });
 
   srv.after('*', (results, req) => {
@@ -147,20 +246,7 @@ function attachInterceptor(srv, options = {}) {
       ? undefined
       : Number(process.hrtime.bigint() - startedAt) / 1e6;
 
-    const context = buildContext(
-      {
-        ...extractAgentInfo(req),
-        ...extractTraceContext(req),
-        entity: resolveEntity(req),
-        operation: resolveOperation(req),
-        tenant: req.tenant,
-        user: req.user && req.user.id,
-        session: req.id,
-        rowCount: resolveRowCount(results),
-        durationMs
-      },
-      clockDeps
-    );
+    const context = buildRequestContext(req, { rowCount: resolveRowCount(results), durationMs });
 
     if (typeof onContext === 'function') {
       onContext(context, req);
@@ -177,6 +263,14 @@ function attachInterceptor(srv, options = {}) {
         applyPseudonymize(results, decision.fieldsToPseudonymize, pseudonymSecret);
       }
 
+      if (decision.mode === 'enforce' && decision.rowLimitExceeded && Array.isArray(results)) {
+        results.length = decision.maxRows;
+      }
+
+      if (decision.mode === 'enforce') {
+        applyNestedPolicy(results, req.target, policyDefinition, pseudonymSecret);
+      }
+
       if (typeof onDecision === 'function') {
         onDecision(decision, context, req);
       }

package/lib/policy/config.js

@@ -14,6 +14,31 @@ function typeOf(value) {
   return typeof value;
 }
 
+/**
+ * Validates the optional top-level `"audit"` key — the same shape
+ * lib/audit/log.js's writeAuditEntry() options take (`{ stdout, filePath }`).
+ * Exposing it in package.json is what lets audit-log persistence be turned on
+ * through config alone, without hand-writing a registerCapMcpGuard() call
+ * (see lib/adapters/cap.js, which forwards this to onDecision's audit option).
+ */
+function validateAuditConfig(raw) {
+  if (raw === undefined) return undefined;
+
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    throw new Error(`"audit" must be a mapping, got ${typeOf(raw)}`);
+  }
+
+  const { filePath, stdout } = raw;
+  if (filePath !== undefined && typeof filePath !== 'string') {
+    throw new Error(`"audit.filePath" must be a string, got ${typeOf(filePath)}`);
+  }
+  if (stdout !== undefined && typeof stdout !== 'boolean') {
+    throw new Error(`"audit.stdout" must be a boolean, got ${typeOf(stdout)}`);
+  }
+
+  return { ...(filePath !== undefined && { filePath }), ...(stdout !== undefined && { stdout }) };
+}
+
 function validatePseudonymizeEntry(entityName, entry) {
   if (typeof entry === 'string') {
     return { field: entry, type: 'opaque' };
@@ -91,7 +116,7 @@ function validateEntityConfig(name, raw) {
  * @param {object} [opts]
  * @param {string} [opts.source] label used in error messages (defaults to
  *   the conventional file name; loadConfig() passes the real path instead)
- * @returns {{ mode: 'enforce'|'observe', entities: object, services: (string[]|undefined), users: (string[]|undefined) }}
+ * @returns {{ mode: 'enforce'|'observe', entities: object, services: (string[]|undefined), users: (string[]|undefined), audit: (object|undefined) }}
  */
 function parseConfig(raw, opts = {}) {
   const { source = 'package.json' } = opts;
@@ -122,7 +147,9 @@ function parseConfig(raw, opts = {}) {
     throw new Error(`"users" must be an array, got ${typeOf(raw.users)}`);
   }
 
-  return { mode: raw.mode, entities, services: raw.services, users: raw.users };
+  const audit = validateAuditConfig(raw.audit);
+
+  return { mode: raw.mode, entities, services: raw.services, users: raw.users, audit };
 }
 
 /**
@@ -133,7 +160,7 @@ function parseConfig(raw, opts = {}) {
  * with a single startsWith() check and fall back to pass-through mode.
  *
  * @param {string} packageJsonPath
- * @returns {{ mode: 'enforce'|'observe', entities: object, services: (string[]|undefined), users: (string[]|undefined) }}
+ * @returns {{ mode: 'enforce'|'observe', entities: object, services: (string[]|undefined), users: (string[]|undefined), audit: (object|undefined) }}
  */
 function loadConfig(packageJsonPath) {
   let content;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cap-mcp-guard",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "A CDS plugin — the trust layer for AI agents accessing SAP CAP business data — request interception, policy enforcement, field masking/pseudonymization, and OpenTelemetry-native observability for MCP-enabled applications.",
   "main": "lib/index.js",
   "author": "Furkan Aksoy <furkanaksy838@gmail.com>",