cap-mcp-guard 0.3.0 → 0.4.0

package/README.md

@@ -184,6 +184,32 @@ to load if it is). More typed generators (e.g. a Luhn-valid fake credit card num
 added later without changing this config shape — anything without a dedicated generator
 just falls back to `"opaque"`.
 
+Sometimes you don't want a *derived* fake value at all — just one fixed, human-chosen
+replacement, the same for every row (e.g. a shared support alias instead of each customer's
+real email). Use `type: "custom"` with a required `"value"`:
+
+```json
+{
+  "cap-mcp-guard": {
+    "mode": "enforce",
+    "entities": {
+      "Customers": {
+        "pseudonymize": [{ "field": "Email", "type": "custom", "value": "hidden@example.com" }]
+      }
+    }
+  }
+}
+```
+
+Unlike `"opaque"`/`"iban"`, `"custom"` doesn't derive anything from the real value or the
+pseudonym secret — every row gets the exact same literal, so it doesn't need
+`CAP_MCP_GUARD_PSEUDONYM_SECRET` at all (a config that mixes a `"custom"` entry with a
+non-`"custom"` one on the same or another entity still needs the secret, for the other
+entry). Because every real value maps to the same output, `"custom"` gives up the
+relational structure (telling two customers apart) that `"opaque"`/`"iban"` preserve — it's
+closer in effect to `mask`, just with your own replacement string instead of the fixed
+`'***MASKED***'`.
+
 **Requires a secret.** Set the `CAP_MCP_GUARD_PSEUDONYM_SECRET` environment variable (or
 pass `pseudonymSecret` directly to `registerCapMcpGuard`) — every pseudonym is derived from
 it via HMAC, so without it a fake value can't be reproduced or tied back to a real one.
@@ -194,7 +220,8 @@ fake one from then on) — this is expected, not a bug.
 
 ## What you get, per request
 
-- **Masking** — in `enforce` mode, fields listed under `mask` are replaced with `'***MASKED***'`, and fields under `pseudonymize` with a deterministic fake value (see above), in the real response. In `observe` mode nothing is touched; the guard only computes what *would* happen.
+- **Masking** — in `enforce` mode, fields listed under `mask` are replaced with `'***MASKED***'`, and fields under `pseudonymize` with a deterministic fake value (see above), in the real response. In `observe` mode nothing is touched; the guard only computes what *would* happen. Also applied one level deep to any `$expand`ed association whose target entity has its own policy.
+- **Tool/row enforcement** — in `enforce` mode, a request naming an operation outside `allowTools` is rejected with a 403 before it runs; a response exceeding `maxRows` is truncated to that limit. In `observe` mode both are only computed and reported, never applied.
 - **Audit log** — every request produces a structured JSON line (Context + Decision), to stdout and/or a file you choose.
 - **OpenTelemetry spans** — every request also becomes a real span via `@opentelemetry/api`. If your app already has an OTel SDK configured (any OTLP-compatible backend — Grafana, Jaeger, Datadog, SAP Cloud Logging), the guard's spans just show up there, correctly linked into the caller's trace via W3C Trace Context (`traceparent`/`tracestate`) when present — no extra mapping needed, because the context schema was built against OTel's GenAI semantic conventions (`gen_ai.*`) from the start.
 
@@ -217,7 +244,6 @@ npm start   # boots a real server at localhost:4004 — flip package.json's "cap
 - `@mcp.policy`-style CDS annotations as an alternative to the `"cap-mcp-guard"` package.json config
 - Approval workflows (human-in-the-loop for sensitive operations)
 - Rate limiting and a dashboard UI
-- Actually blocking a request when `allowTools`/`maxRows` is violated (today those are computed and reported, not enforced)
 
 ## Development
 

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,13 +93,16 @@ 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;
 
+  // type: "custom" is a fixed, operator-chosen literal, not a derived value — it needs no
+  // secret to reproduce, so a config using only "custom" entries can start without one.
   const pseudonymSecret = options.pseudonymSecret || process.env.CAP_MCP_GUARD_PSEUDONYM_SECRET;
-  const usesPseudonymize = Object.values(policyDefinition.entities).some(
-    (entityConfig) => entityConfig.pseudonymize && entityConfig.pseudonymize.length > 0
+  const needsPseudonymSecret = Object.values(policyDefinition.entities).some((entityConfig) =>
+    (entityConfig.pseudonymize || []).some((entry) => entry.type !== 'custom')
   );
-  if (usesPseudonymize && !pseudonymSecret) {
+  if (needsPseudonymSecret && !pseudonymSecret) {
     throw new Error(
       'CAP_MCP_GUARD_PSEUDONYM_SECRET env var (or options.pseudonymSecret) is required when "pseudonymize" is configured'
     );

package/lib/core/interceptor.js

@@ -91,14 +91,75 @@ function applyPseudonymize(results, fieldsToPseudonymize, secret) {
 
   items.forEach((item) => {
     if (!item || typeof item !== 'object') return;
-    for (const { field, type } of fieldsToPseudonymize) {
+    for (const { field, type, value: customValue } of fieldsToPseudonymize) {
       if (Object.prototype.hasOwnProperty.call(item, field)) {
-        item[field] = generatePseudonym(field, item[field], type, secret);
+        item[field] = generatePseudonym(field, item[field], type, secret, customValue);
       }
     }
   });
 }
 
+/**
+ * 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,13 +14,38 @@ 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' };
   }
 
   if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
-    const { field, type = 'opaque' } = entry;
+    const { field, type = 'opaque', value } = entry;
 
     if (typeof field !== 'string' || !field) {
       throw new Error(`entities.${entityName}.pseudonymize entries must have a "field" string`);
@@ -30,6 +55,15 @@ function validatePseudonymizeEntry(entityName, entry) {
         `entities.${entityName}.pseudonymize.${field}.type must be one of ${PSEUDONYM_TYPES.join(', ')} (got ${JSON.stringify(type)})`
       );
     }
+    if (type === 'custom') {
+      if (typeof value !== 'string' || !value) {
+        throw new Error(`entities.${entityName}.pseudonymize.${field}: type "custom" requires a non-empty "value" string`);
+      }
+      return { field, type, value };
+    }
+    if (value !== undefined) {
+      throw new Error(`entities.${entityName}.pseudonymize.${field}: "value" is only allowed with type "custom"`);
+    }
     return { field, type };
   }
 
@@ -91,7 +125,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 +156,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 +169,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/lib/policy/pseudonym.js

@@ -2,7 +2,7 @@
 
 const crypto = require('crypto');
 
-const PSEUDONYM_TYPES = ['opaque', 'iban'];
+const PSEUDONYM_TYPES = ['opaque', 'iban', 'custom'];
 
 const IBAN_SHAPE = /^[A-Z]{2}[0-9]{2}[A-Z0-9]+$/;
 
@@ -67,23 +67,29 @@ function generateIbanPseudonym(value, secret) {
 
 const GENERATORS = {
   opaque: generateOpaquePseudonym,
-  iban: (field, value, secret) => generateIbanPseudonym(value, secret)
+  iban: (field, value, secret) => generateIbanPseudonym(value, secret),
+  // Not actually a generator — every row gets the exact same operator-chosen literal
+  // instead of a derived fake value, so there's nothing to compute from value/secret.
+  custom: (field, value, secret, customValue) => customValue
 };
 
 /**
  * @param {string} field the field name being pseudonymized
  * @param {*} value the real value
  * @param {string} type one of PSEUDONYM_TYPES (validated by lib/policy/config.js)
- * @param {string} secret never embedded in the output; without it, the pseudonym can't
- *   be reproduced or (for the opaque case) traced back to a specific value
+ * @param {string} [secret] never embedded in the output; without it, the pseudonym can't
+ *   be reproduced or (for the opaque/iban case) traced back to a specific value. Unused
+ *   (and not required) for type "custom".
+ * @param {string} [customValue] the literal replacement value, required and used only
+ *   when type is "custom"
  * @returns {string}
  */
-function generatePseudonym(field, value, type, secret) {
+function generatePseudonym(field, value, type, secret, customValue) {
   const generator = GENERATORS[type];
   if (!generator) {
     throw new Error(`Unknown pseudonym type "${type}"`);
   }
-  return generator(field, value, secret);
+  return generator(field, value, secret, customValue);
 }
 
 module.exports = { generatePseudonym, PSEUDONYM_TYPES };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cap-mcp-guard",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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>",