cap-mcp-guard 0.3.1 → 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

@@ -96,11 +96,13 @@ function registerCapMcpGuard(cds, 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,9 +91,9 @@ 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);
       }
     }
   });

package/lib/policy/config.js

@@ -45,7 +45,7 @@ function validatePseudonymizeEntry(entityName, entry) {
   }
 
   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`);
@@ -55,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 };
   }
 

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.1",
+  "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>",