cap-mcp-guard 0.2.0 → 0.3.0

package/lib/core/interceptor.js

@@ -3,6 +3,7 @@
 const { buildContext } = require('./context');
 const { evaluate } = require('../policy/evaluator');
 const { maskFields } = require('../policy/masking');
+const { generatePseudonym } = require('../policy/pseudonym');
 
 /**
  * Reads W3C Trace Context fields propagated by the MCP runtime.
@@ -74,6 +75,30 @@ function applyMask(results, fieldsToMask) {
   });
 }
 
+/**
+ * Replaces each listed field's real value with a deterministic pseudonym (see
+ * lib/policy/pseudonym.js) — same real value always produces the same fake one, so an
+ * AI agent can still tell rows apart without ever seeing the real data. Mutates `results`
+ * in place, same convention as applyMask().
+ *
+ * @param {object|object[]} results
+ * @param {{field: string, type: string}[]} fieldsToPseudonymize
+ * @param {string} secret required whenever fieldsToPseudonymize is non-empty (see
+ *   lib/adapters/cap.js, which resolves and validates this before attachInterceptor runs)
+ */
+function applyPseudonymize(results, fieldsToPseudonymize, secret) {
+  const items = Array.isArray(results) ? results : [results];
+
+  items.forEach((item) => {
+    if (!item || typeof item !== 'object') return;
+    for (const { field, type } of fieldsToPseudonymize) {
+      if (Object.prototype.hasOwnProperty.call(item, field)) {
+        item[field] = generatePseudonym(field, item[field], type, secret);
+      }
+    }
+  });
+}
+
 /**
  * Attaches request interception to a CAP service instance, producing a
  * guard context (see context.js) for every request that passes through it.
@@ -98,13 +123,15 @@ function applyMask(results, fieldsToMask) {
  *   each request completes, regardless of mode — this is the extension
  *   point M5 (audit log) uses
  * @param {() => string} [options.now] injectable clock, forwarded to buildContext
+ * @param {string} [options.pseudonymSecret] required whenever any entity configures
+ *   `pseudonymize` — resolved and validated one layer up in lib/adapters/cap.js
  */
 function attachInterceptor(srv, options = {}) {
   if (!srv || typeof srv.before !== 'function' || typeof srv.after !== 'function') {
     throw new Error('attachInterceptor requires a CAP service exposing before()/after() hooks');
   }
 
-  const { onContext, policyDefinition, onDecision, now } = options;
+  const { onContext, policyDefinition, onDecision, now, pseudonymSecret } = options;
   const clockDeps = now ? { now } : {};
 
   srv.before('*', (req) => {
@@ -146,6 +173,10 @@ function attachInterceptor(srv, options = {}) {
         applyMask(results, decision.fieldsToMask);
       }
 
+      if (decision.mode === 'enforce' && decision.fieldsToPseudonymize.length > 0) {
+        applyPseudonymize(results, decision.fieldsToPseudonymize, pseudonymSecret);
+      }
+
       if (typeof onDecision === 'function') {
         onDecision(decision, context, req);
       }

package/lib/index.js

@@ -2,6 +2,5 @@
 
 const { buildContext } = require('./core/context');
 const { attachInterceptor } = require('./core/interceptor');
-const { odataMcpGuard } = require('./adapters/odata');
 
-module.exports = { buildContext, attachInterceptor, odataMcpGuard };
+module.exports = { buildContext, attachInterceptor };

package/lib/policy/config.js

@@ -1,106 +1,164 @@
-'use strict';
-
-const fs = require('fs');
-const yaml = require('js-yaml');
-
-const VALID_MODES = ['enforce', 'observe'];
-const DEFAULT_SOURCE = 'cap-mcp-guard.yaml';
-
-function typeOf(value) {
-  if (Array.isArray(value)) return 'array';
-  if (value === null) return 'null';
-  return typeof value;
-}
-
-function validateEntityConfig(name, raw) {
-  const config = raw ?? {};
-
-  if (typeof config !== 'object' || Array.isArray(config)) {
-    throw new Error(`entities.${name} must be a mapping, got ${typeOf(config)}`);
-  }
-
-  const { mask, maxRows, allowTools } = config;
-
-  if (mask !== undefined && !Array.isArray(mask)) {
-    throw new Error(`entities.${name}.mask must be an array, got ${typeOf(mask)}`);
-  }
-
-  if (allowTools !== undefined && !Array.isArray(allowTools)) {
-    throw new Error(`entities.${name}.allowTools must be an array, got ${typeOf(allowTools)}`);
-  }
-
-  if (maxRows !== undefined) {
-    if (typeof maxRows !== 'number' || Number.isNaN(maxRows)) {
-      throw new Error(`entities.${name}.maxRows must be a number, got ${typeOf(maxRows)}`);
-    }
-    if (maxRows < 0) {
-      throw new Error(`entities.${name}.maxRows must not be negative (got ${maxRows})`);
-    }
-  }
-
-  return { mask, maxRows, allowTools };
-}
-
-/**
- * Parses and validates a cap-mcp-guard.yaml document (already read into a
- * string) into a PolicyDefinition — the source-agnostic shape the policy
- * engine consumes. Pure: no filesystem access.
- *
- * @param {string} yamlString
- * @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 }}
- */
-function parseConfig(yamlString, opts = {}) {
-  const { source = DEFAULT_SOURCE } = opts;
-
-  let doc;
-  try {
-    doc = yaml.load(yamlString);
-  } catch (err) {
-    throw new Error(`Failed to parse ${source}: ${err.message}`);
-  }
-
-  if (doc === undefined || doc === null || typeof doc !== 'object' || Array.isArray(doc)) {
-    throw new Error(`${source}: root must be a mapping with a "mode" key`);
-  }
-
-  if (!VALID_MODES.includes(doc.mode)) {
-    throw new Error(`"mode" must be one of ${VALID_MODES.join(', ')} (got ${JSON.stringify(doc.mode)})`);
-  }
-
-  const rawEntities = doc.entities ?? {};
-  if (typeof rawEntities !== 'object' || Array.isArray(rawEntities)) {
-    throw new Error(`"entities" must be a mapping of entity name to config, got ${typeOf(rawEntities)}`);
-  }
-
-  const entities = {};
-  for (const [name, raw] of Object.entries(rawEntities)) {
-    entities[name] = validateEntityConfig(name, raw);
-  }
-
-  return { mode: doc.mode, entities };
-}
-
-/**
- * Reads cap-mcp-guard.yaml from disk and parses it via parseConfig().
- *
- * @param {string} path
- * @returns {{ mode: 'enforce'|'observe', entities: object }}
- */
-function loadConfig(path) {
-  let content;
-  try {
-    content = fs.readFileSync(path, 'utf8');
-  } catch (err) {
-    if (err.code === 'ENOENT') {
-      throw new Error(`cap-mcp-guard.yaml not found at ${path}`);
-    }
-    throw err;
-  }
-
-  return parseConfig(content, { source: path });
-}
-
-module.exports = { loadConfig, parseConfig };
+'use strict';
+
+const fs = require('fs');
+
+const { PSEUDONYM_TYPES } = require('./pseudonym');
+
+const VALID_MODES = ['enforce', 'observe'];
+const CONFIG_KEY = 'cap-mcp-guard';
+const NOT_CONFIGURED_PREFIX = 'cap-mcp-guard not configured';
+
+function typeOf(value) {
+  if (Array.isArray(value)) return 'array';
+  if (value === null) return 'null';
+  return typeof value;
+}
+
+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;
+
+    if (typeof field !== 'string' || !field) {
+      throw new Error(`entities.${entityName}.pseudonymize entries must have a "field" string`);
+    }
+    if (!PSEUDONYM_TYPES.includes(type)) {
+      throw new Error(
+        `entities.${entityName}.pseudonymize.${field}.type must be one of ${PSEUDONYM_TYPES.join(', ')} (got ${JSON.stringify(type)})`
+      );
+    }
+    return { field, type };
+  }
+
+  throw new Error(
+    `entities.${entityName}.pseudonymize entries must be a string or a {field, type} object, got ${typeOf(entry)}`
+  );
+}
+
+function validateEntityConfig(name, raw) {
+  const config = raw ?? {};
+
+  if (typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error(`entities.${name} must be a mapping, got ${typeOf(config)}`);
+  }
+
+  const { mask, maxRows, allowTools, pseudonymize: rawPseudonymize } = config;
+
+  if (mask !== undefined && !Array.isArray(mask)) {
+    throw new Error(`entities.${name}.mask must be an array, got ${typeOf(mask)}`);
+  }
+
+  if (allowTools !== undefined && !Array.isArray(allowTools)) {
+    throw new Error(`entities.${name}.allowTools must be an array, got ${typeOf(allowTools)}`);
+  }
+
+  if (maxRows !== undefined) {
+    if (typeof maxRows !== 'number' || Number.isNaN(maxRows)) {
+      throw new Error(`entities.${name}.maxRows must be a number, got ${typeOf(maxRows)}`);
+    }
+    if (maxRows < 0) {
+      throw new Error(`entities.${name}.maxRows must not be negative (got ${maxRows})`);
+    }
+  }
+
+  let pseudonymize;
+  if (rawPseudonymize !== undefined) {
+    if (!Array.isArray(rawPseudonymize)) {
+      throw new Error(`entities.${name}.pseudonymize must be an array, got ${typeOf(rawPseudonymize)}`);
+    }
+    pseudonymize = rawPseudonymize.map((entry) => validatePseudonymizeEntry(name, entry));
+
+    const maskedFields = new Set(mask ?? []);
+    for (const { field } of pseudonymize) {
+      if (maskedFields.has(field)) {
+        throw new Error(`entities.${name}: "${field}" cannot be listed in both "mask" and "pseudonymize"`);
+      }
+    }
+  }
+
+  return { mask, maxRows, allowTools, pseudonymize };
+}
+
+/**
+ * Validates an already-parsed `"cap-mcp-guard"` config object (the value of
+ * that key in package.json) into a PolicyDefinition — the source-agnostic
+ * shape the policy engine consumes. Pure: no filesystem access.
+ *
+ * @param {object} raw the parsed `"cap-mcp-guard"` value
+ * @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) }}
+ */
+function parseConfig(raw, opts = {}) {
+  const { source = 'package.json' } = opts;
+
+  if (raw === undefined || raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`${source}: "${CONFIG_KEY}" must be a mapping with a "mode" key`);
+  }
+
+  if (!VALID_MODES.includes(raw.mode)) {
+    throw new Error(`"mode" must be one of ${VALID_MODES.join(', ')} (got ${JSON.stringify(raw.mode)})`);
+  }
+
+  const rawEntities = raw.entities ?? {};
+  if (typeof rawEntities !== 'object' || Array.isArray(rawEntities)) {
+    throw new Error(`"entities" must be a mapping of entity name to config, got ${typeOf(rawEntities)}`);
+  }
+
+  const entities = {};
+  for (const [name, entityRaw] of Object.entries(rawEntities)) {
+    entities[name] = validateEntityConfig(name, entityRaw);
+  }
+
+  if (raw.services !== undefined && !Array.isArray(raw.services)) {
+    throw new Error(`"services" must be an array, got ${typeOf(raw.services)}`);
+  }
+
+  if (raw.users !== undefined && !Array.isArray(raw.users)) {
+    throw new Error(`"users" must be an array, got ${typeOf(raw.users)}`);
+  }
+
+  return { mode: raw.mode, entities, services: raw.services, users: raw.users };
+}
+
+/**
+ * Reads the host project's package.json and validates its `"cap-mcp-guard"`
+ * key via parseConfig(). Both "no package.json at this path" and "package.json
+ * exists but has no cap-mcp-guard key" are reported under the same
+ * NOT_CONFIGURED_PREFIX, so callers can treat either as "not configured yet"
+ * 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) }}
+ */
+function loadConfig(packageJsonPath) {
+  let content;
+  try {
+    content = fs.readFileSync(packageJsonPath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new Error(`${NOT_CONFIGURED_PREFIX}: no package.json found at ${packageJsonPath}`);
+    }
+    throw err;
+  }
+
+  let pkg;
+  try {
+    pkg = JSON.parse(content);
+  } catch (err) {
+    throw new Error(`Failed to parse ${packageJsonPath}: ${err.message}`);
+  }
+
+  const raw = pkg[CONFIG_KEY];
+  if (raw === undefined) {
+    throw new Error(`${NOT_CONFIGURED_PREFIX}: "${CONFIG_KEY}" key not found in ${packageJsonPath}`);
+  }
+
+  return parseConfig(raw, { source: packageJsonPath });
+}
+
+module.exports = { loadConfig, parseConfig, NOT_CONFIGURED_PREFIX };

package/lib/policy/evaluator.js

@@ -1,5 +1,19 @@
 'use strict';
 
+function passThroughDecision(context, policyDefinition) {
+  return {
+    mode: policyDefinition.mode,
+    allowed: true,
+    reason: null,
+    fieldsToMask: [],
+    fieldsToPseudonymize: [],
+    rowLimitExceeded: false,
+    maxRows: null,
+    entity: context.entity,
+    timestamp: context.timestamp
+  };
+}
+
 /**
  * Evaluates a request Context (lib/core/context.js) against a
  * PolicyDefinition (lib/policy/config.js) and produces a Decision — what
@@ -14,22 +28,22 @@
  * @returns {object} Decision
  */
 function evaluate(context, policyDefinition) {
+  // policyDefinition.users, when set, scopes enforcement to just those identities
+  // (context.user, populated from CAP's own verified req.user.id) — e.g. a technical
+  // user the MCP runtime authenticates as, distinct from a human UI user hitting the
+  // same service. A request from anyone not in the list is fully allowed/unmasked,
+  // as if this entity had no policy at all.
+  if (Array.isArray(policyDefinition.users) && !policyDefinition.users.includes(context.user)) {
+    return passThroughDecision(context, policyDefinition);
+  }
+
   const entityConfig = policyDefinition.entities[context.entity];
 
   if (!entityConfig) {
-    return {
-      mode: policyDefinition.mode,
-      allowed: true,
-      reason: null,
-      fieldsToMask: [],
-      rowLimitExceeded: false,
-      maxRows: null,
-      entity: context.entity,
-      timestamp: context.timestamp
-    };
+    return passThroughDecision(context, policyDefinition);
   }
 
-  const { allowTools, maxRows, mask } = entityConfig;
+  const { allowTools, maxRows, mask, pseudonymize } = entityConfig;
 
   let allowed = true;
   let reason = null;
@@ -46,6 +60,7 @@ function evaluate(context, policyDefinition) {
     allowed,
     reason,
     fieldsToMask: mask ?? [],
+    fieldsToPseudonymize: pseudonymize ?? [],
     rowLimitExceeded,
     maxRows: typeof maxRows === 'number' ? maxRows : null,
     entity: context.entity,

package/lib/policy/pseudonym.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const crypto = require('crypto');
+
+const PSEUDONYM_TYPES = ['opaque', 'iban'];
+
+const IBAN_SHAPE = /^[A-Z]{2}[0-9]{2}[A-Z0-9]+$/;
+
+function hmacHex(value, secret) {
+  return crypto.createHmac('sha256', secret).update(String(value)).digest('hex');
+}
+
+/**
+ * Generic fallback: a deterministic, opaque token — same field+value+secret always
+ * produces the same token, but the token carries no information about the real value
+ * and doesn't resemble any particular data format.
+ */
+function generateOpaquePseudonym(field, value, secret) {
+  const hex = hmacHex(`${field}:${value}`, secret);
+  return `${field}-${hex.slice(0, 12)}`;
+}
+
+/**
+ * Computes the 2-digit ISO 7064 MOD 97-10 check digits for an IBAN whose check-digit
+ * positions (chars 3-4) are currently '00'. Standard algorithm: move the first 4 chars
+ * to the end, map letters to numbers (A=10 .. Z=35), reduce mod 97 as a big integer via
+ * BigInt, check digits = 98 - remainder.
+ */
+function computeIbanCheckDigits(ibanWithZeroedCheckDigits) {
+  const rearranged = ibanWithZeroedCheckDigits.slice(4) + ibanWithZeroedCheckDigits.slice(0, 4);
+  const numeric = rearranged.replace(/[A-Z]/g, (letter) => String(letter.charCodeAt(0) - 55));
+  const remainder = BigInt(numeric) % 97n;
+  return String(98n - remainder).padStart(2, '0');
+}
+
+/**
+ * Deterministic, format-preserving fake IBAN: same country code and total length as the
+ * real value, digits derived from HMAC(value, secret), and a real, valid ISO 7064 MOD
+ * 97-10 check digit pair — so it passes standard IBAN checksum validation even though
+ * it's entirely fake. Falls back to generateOpaquePseudonym() for anything that doesn't
+ * look like an IBAN (defensive — real-world field content can't be validated ahead of
+ * time the way config shape can).
+ */
+function generateIbanPseudonym(value, secret) {
+  const normalized = String(value).replace(/\s+/g, '').toUpperCase();
+
+  if (!IBAN_SHAPE.test(normalized)) {
+    return generateOpaquePseudonym('IBAN', value, secret);
+  }
+
+  const countryCode = normalized.slice(0, 2);
+  const bbanLength = normalized.length - 4;
+
+  const hex = hmacHex(normalized, secret);
+  let digits = '';
+  for (let i = 0; digits.length < bbanLength; i++) {
+    const byte = parseInt(hex[i % hex.length], 16);
+    digits += String(byte % 10);
+  }
+  digits = digits.slice(0, bbanLength);
+
+  const withZeroedCheckDigits = `${countryCode}00${digits}`;
+  const checkDigits = computeIbanCheckDigits(withZeroedCheckDigits);
+
+  return `${countryCode}${checkDigits}${digits}`;
+}
+
+const GENERATORS = {
+  opaque: generateOpaquePseudonym,
+  iban: (field, value, secret) => generateIbanPseudonym(value, secret)
+};
+
+/**
+ * @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
+ * @returns {string}
+ */
+function generatePseudonym(field, value, type, secret) {
+  const generator = GENERATORS[type];
+  if (!generator) {
+    throw new Error(`Unknown pseudonym type "${type}"`);
+  }
+  return generator(field, value, secret);
+}
+
+module.exports = { generatePseudonym, PSEUDONYM_TYPES };

package/package.json

@@ -1,54 +1,56 @@
-{
-  "name": "cap-mcp-guard",
-  "version": "0.2.0",
-  "description": "The trust layer for AI agents accessing SAP CAP business data — request interception, policy enforcement, field masking, and OpenTelemetry-native observability for MCP-enabled applications.",
-  "main": "lib/index.js",
-  "author": "Furkan Aksoy <furkanaksy838@gmail.com>",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/furkanaksy838/mcp.git"
-  },
-  "homepage": "https://github.com/furkanaksy838/mcp#readme",
-  "bugs": {
-    "url": "https://github.com/furkanaksy838/mcp/issues"
-  },
-  "files": [
-    "lib",
-    "cds-plugin.js"
-  ],
-  "scripts": {
-    "test": "jest"
-  },
-  "keywords": [
-    "cap",
-    "sap",
-    "odata",
-    "mcp",
-    "ai-agent",
-    "policy",
-    "opentelemetry"
-  ],
-  "license": "MIT",
-  "engines": {
-    "node": ">=20"
-  },
-  "peerDependencies": {
-    "@sap/cds": ">=7"
-  },
-  "devDependencies": {
-    "@opentelemetry/core": "^2.9.0",
-    "@opentelemetry/sdk-trace-base": "^2.9.0",
-    "jest": "^30.4.2"
-  },
-  "jest": {
-    "testEnvironment": "node",
-    "testPathIgnorePatterns": [
-      "/node_modules/",
-      "/examples/"
-    ]
-  },
-  "dependencies": {
-    "@opentelemetry/api": "^1.9.1",
-    "js-yaml": "^5.2.1"
-  }
-}
+{
+  "name": "cap-mcp-guard",
+  "version": "0.3.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>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/furkanaksy838/mcp.git"
+  },
+  "homepage": "https://github.com/furkanaksy838/mcp#readme",
+  "bugs": {
+    "url": "https://github.com/furkanaksy838/mcp/issues"
+  },
+  "files": [
+    "lib",
+    "cds-plugin.js"
+  ],
+  "scripts": {
+    "test": "jest"
+  },
+  "keywords": [
+    "CAP",
+    "CDS",
+    "cds-plugin",
+    "cap",
+    "sap",
+    "odata",
+    "mcp",
+    "ai-agent",
+    "policy",
+    "opentelemetry"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@sap/cds": ">=7"
+  },
+  "devDependencies": {
+    "@opentelemetry/core": "^2.9.0",
+    "@opentelemetry/sdk-trace-base": "^2.9.0",
+    "jest": "^30.4.2"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "testPathIgnorePatterns": [
+      "/node_modules/",
+      "/examples/"
+    ]
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1"
+  }
+}