cap-mcp-guard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Furkan Aksoy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# cap-mcp-guard
+
+CAP MCP Guard is 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.
+
+Today, organizations have only two options when exposing SAP CAP business data to AI agents: grant unrestricted access or deny access completely. CAP MCP Guard introduces a third option — controlled, observable, and policy-driven access, without requiring developers to hand-write authorization, masking, and audit logic for every entity.
+
+We give CAP developers a standardized, reusable way to enforce AI-agent security, observability, and policy — without hand-writing that logic for every entity. Convention over implementation, in the same spirit as CAP itself.
+
+## Why
+
+- **Field exposure.** When AI agents connect to CAP entities over MCP, sensitive fields (`CreditCardNo`, `Salary`, national ID numbers, ...) are visible to the agent unless someone filters them by hand, entity by entity.
+- **No visibility.** Which agent accessed which entity, when, how many rows, and how long it took isn't logged anywhere standard. There's no answer when someone asks for an audit trail.
+- **Excessive trust.** Even a "read-only" agent can technically reach every action/function a service exposes through the MCP layer, unless something enforces otherwise. Relying on the agent to "behave" isn't a control.
+- **Enterprise distrust.** Companies want AI agents connected to business data, but security teams block it because nobody can prove what the agent will actually do. CAP MCP Guard is the third option between "wide open" and "no access at all."
+
+## How it works
+
+```
+AI Request → Intercept → Evaluate Policy → Mask → Execute → Audit → Trace
+```
+
+```
+Claude / Joule / Copilot / Custom Agent
+              │
+        Any MCP Runtime
+   (gavdilabs/cap-mcp-plugin, a custom runtime, a future official SAP
+    solution — it doesn't matter which)
+              │
+    ┌─────────────────────────┐
+    │      cap-mcp-guard      │
+    │                         │
+    │  lib/core/              │
+    │   ├─ interceptor.js     │ → attaches to CAP's srv.before/srv.after hooks
+    │   └─ context.js         │ → builds an OTel gen_ai.*-shaped, framework-
+    │                         │   agnostic request context
+    │                         │
+    │  lib/policy/            │ → knows nothing about CAP. Plain JS: Context in,
+    │   ├─ config.js          │   Decision out.
+    │   ├─ evaluator.js       │
+    │   └─ masking.js         │
+    │                         │
+    │  lib/audit/             │
+    │   └─ log.js             │ → Context + Decision → structured JSON log line
+    │                         │
+    │  lib/otel/              │
+    │   └─ exporter.js        │ → Context + Decision → a real OTel span
+    │                         │
+    │  lib/adapters/          │
+    │   └─ cap.js             │ → the ONE place that knows @sap/cds.
+    │                         │   cds-plugin.js calls this.
+    └─────────────────────────┘
+              │
+         CAP Service
+```
+
+`lib/policy/` and `lib/core/context.js` never import `@sap/cds` — they only ever see a plain `Context` object and a plain `PolicyDefinition` object, regardless of where either one came from. That's what lets `cap-mcp-guard.yaml` be swapped out for a future CDS-annotation-based source later without touching the engine itself.
+
+## Install
+
+```bash
+npm install --save-dev cap-mcp-guard
+```
+
+CAP auto-discovers `cds-plugin.js` the moment the package is a dependency of your project — no wiring required. Drop a `cap-mcp-guard.yaml` in your project root and it's picked up automatically the next time your CAP server starts.
+
+## Configure
+
+```yaml
+# cap-mcp-guard.yaml
+mode: enforce   # or: observe (dry-run — logs/traces what would happen, blocks nothing)
+
+entities:
+  Orders:
+    mask:
+      - CreditCard
+      - Salary
+    maxRows: 100
+    allowTools:
+      - ReadOrders
+
+  Customers:
+    mask:
+      - Email
+      - Phone
+```
+
+- Entities not listed here are fully accessible — this is opt-in by design; you don't have to configure every entity up front.
+- No config file at all? The guard runs in pass-through mode (a `console.warn` tells you so) rather than crashing your server.
+- A config file that exists but fails to parse *does* fail loudly — a broken config shouldn't fail silently.
+
+## What you get, per request
+
+- **Masking** — in `enforce` mode, fields listed under `mask` are replaced with `'***MASKED***'` in the real response. In `observe` mode nothing is touched; the guard only computes what *would* happen.
+- **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.
+
+All three run independently and can each be disabled per-call (`audit: false`, `otel: false`) if you're wiring `registerCapMcpGuard` yourself instead of relying on auto-discovery.
+
+## Try it
+
+A full working example lives in [`examples/bookshop`](examples/bookshop) — SAP's own CAP getting-started sample, with `cap-mcp-guard` wired in and a `cap-mcp-guard.yaml` masking real fields on `CatalogService.Books`.
+
+```bash
+cd examples/bookshop
+npm install
+npm test    # runs enforce/observe/audit/OTel integration tests against a real CAP service
+npm start   # boots a real server at localhost:4004 — flip cap-mcp-guard.yaml to `mode: enforce`
+            # and hit /odata/v4/browse/Books to see masking happen live
+```
+
+## Coming soon (not in v1)
+
+- `@mcp.policy`-style CDS annotations as an alternative to `cap-mcp-guard.yaml`
+- Approval workflows (human-in-the-loop for sensitive operations)
+- Rate limiting and a dashboard UI
+- Adapters for frameworks other than CAP
+- Actually blocking a request when `allowTools`/`maxRows` is violated (today those are computed and reported, not enforced)
+
+## Development
+
+```bash
+npm test   # unit tests for lib/core, lib/policy, lib/audit, lib/otel, lib/adapters
+```
+
+## License
+
+MIT

package/cds-plugin.js

@@ -0,0 +1,8 @@
+'use strict';
+
+// CAP auto-discovers this file (SAP's "cds-plugin.js" convention) as soon as
+// cap-mcp-guard is a dependency of the host project — no wiring required.
+const cds = require('@sap/cds');
+const { registerCapMcpGuard } = require('./lib/adapters/cap');
+
+registerCapMcpGuard(cds);

package/lib/adapters/cap.js

@@ -0,0 +1,80 @@
+'use strict';
+
+const path = require('path');
+
+const { attachInterceptor } = require('../core/interceptor');
+const { loadConfig } = require('../policy/config');
+const { logAudit } = require('../audit/log');
+const { exportSpan } = require('../otel/exporter');
+
+const CONFIG_FILE_NAME = 'cap-mcp-guard.yaml';
+const NOT_FOUND_PREFIX = `${CONFIG_FILE_NAME} not found`;
+
+/**
+ * Loads cap-mcp-guard.yaml from the host CAP project's root. A missing
+ * config 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.
+ *
+ * @param {object} cds the @sap/cds module (used only for cds.root)
+ */
+function resolvePolicyDefinition(cds) {
+  const configPath = path.join(cds.root || process.cwd(), CONFIG_FILE_NAME);
+
+  try {
+    return loadConfig(configPath);
+  } catch (err) {
+    if (err.message.startsWith(NOT_FOUND_PREFIX)) {
+      console.warn('[cap-mcp-guard] no config found, running in pass-through mode (no policies enforced)');
+      return { mode: 'observe', entities: {} };
+    }
+    throw err;
+  }
+}
+
+/**
+ * The single CAP-specific connection point in this package. Everything
+ * under lib/core and lib/policy is framework-agnostic; this file is where
+ * @sap/cds concepts (served services, cds.ApplicationService, cds.root)
+ * are known.
+ *
+ * cds-plugin.js is the only caller of this function in production; tests
+ * call it directly against a real or fake CAP service.
+ *
+ * @param {object} cds the @sap/cds module (or a compatible facade)
+ * @param {object} [options] forwarded to attachInterceptor (see interceptor.js)
+ * @param {object} [options.policyDefinition] when omitted, loaded from
+ *   cap-mcp-guard.yaml at the project root (see resolvePolicyDefinition)
+ * @param {object|false} [options.audit] forwarded to logAudit()'s write
+ *   options (`{ stdout, filePath }`); pass `false` to disable audit
+ *   logging entirely.
+ * @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
+ *   default is to always attempt it.
+ * @param {(decision: object, context: object, req: object) => void} [options.onDecision]
+ *   called in addition to the built-in audit log and OTel export, not
+ *   instead of them — all that apply run for every request.
+ */
+function registerCapMcpGuard(cds, options = {}) {
+  const policyDefinition = options.policyDefinition || resolvePolicyDefinition(cds);
+  const { onDecision: userOnDecision, audit, otel } = options;
+
+  const onDecision = (decision, context, req) => {
+    if (audit !== false) logAudit(context, decision, audit);
+    if (otel !== false) exportSpan(context, decision, otel);
+    if (typeof userOnDecision === 'function') userOnDecision(decision, context, req);
+  };
+
+  cds.on('served', () => {
+    for (const srv of Object.values(cds.services)) {
+      if (srv instanceof cds.ApplicationService) {
+        attachInterceptor(srv, { ...options, policyDefinition, onDecision });
+      }
+    }
+  });
+}
+
+module.exports = { registerCapMcpGuard };

package/lib/audit/log.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const fs = require('fs');
+
+/**
+ * Builds the structured audit entry for a single request: the full guard
+ * Context (lib/core/context.js) alongside the Decision computed for it
+ * (lib/policy/evaluator.js). Pure — no I/O, no CAP dependency.
+ *
+ * @param {object} context
+ * @param {object} decision
+ * @returns {{ timestamp: string, context: object, decision: object }}
+ */
+function buildAuditEntry(context, decision) {
+  return {
+    timestamp: context.timestamp,
+    context,
+    decision
+  };
+}
+
+/**
+ * Writes an audit entry as a single line of JSON (one entry per line, so
+ * log files stay grep/tail-friendly). Always writes to stdout unless
+ * `stdout: false`; additionally appends to `filePath` if given. Plain
+ * Node `fs` — no CAP dependency.
+ *
+ * @param {object} entry see buildAuditEntry()
+ * @param {object} [options]
+ * @param {boolean} [options.stdout] defaults to true
+ * @param {string} [options.filePath] optional file to append the line to
+ */
+function writeAuditEntry(entry, options = {}) {
+  const { stdout = true, filePath } = options;
+  const line = JSON.stringify(entry);
+
+  if (stdout) {
+    console.log(line);
+  }
+
+  if (filePath) {
+    fs.appendFileSync(filePath, line + '\n');
+  }
+}
+
+/**
+ * Convenience combining buildAuditEntry() + writeAuditEntry() — the
+ * function lib/adapters/cap.js wires as the interceptor's onDecision
+ * callback by default.
+ *
+ * @param {object} context
+ * @param {object} decision
+ * @param {object} [options] see writeAuditEntry()
+ * @returns {object} the entry that was written
+ */
+function logAudit(context, decision, options = {}) {
+  const entry = buildAuditEntry(context, decision);
+  writeAuditEntry(entry, options);
+  return entry;
+}
+
+module.exports = { buildAuditEntry, writeAuditEntry, logAudit };

package/lib/core/context.js

@@ -0,0 +1,67 @@
+'use strict';
+
+/**
+ * Builds a framework-agnostic request context object, shaped after the
+ * OpenTelemetry GenAI semantic conventions (`gen_ai.*`) and the W3C Trace
+ * Context fields propagated via MCP `_meta` (SEP-414: traceparent/tracestate).
+ *
+ * Pure function: given the same `input` and `now`, it always returns the
+ * same shape. No CAP or OTel dependency lives here.
+ *
+ * @param {object} input
+ * @param {string} [input.agentId]
+ * @param {string} [input.agentName]
+ * @param {string} [input.model]
+ * @param {string} [input.traceparent]
+ * @param {string} [input.tracestate]
+ * @param {string} [input.entity]
+ * @param {string} [input.operation]
+ * @param {string} [input.tenant]
+ * @param {string} [input.user]
+ * @param {string} [input.session]
+ * @param {string} [input.timestamp]
+ * @param {number} [input.rowCount]
+ * @param {number} [input.durationMs]
+ * @param {object} [deps]
+ * @param {() => string} [deps.now] injectable clock, defaults to ISO now
+ * @returns {object} context object matching the guard's context schema
+ */
+function buildContext(input = {}, deps = {}) {
+  const { now = () => new Date().toISOString() } = deps;
+
+  const {
+    agentId,
+    agentName,
+    model,
+    traceparent,
+    tracestate,
+    entity,
+    operation,
+    tenant,
+    user,
+    session,
+    timestamp,
+    rowCount,
+    durationMs
+  } = input;
+
+  return {
+    'gen_ai.agent.id': agentId,
+    'gen_ai.agent.name': agentName,
+    'gen_ai.request.model': model,
+
+    traceparent,
+    tracestate,
+
+    entity,
+    operation,
+    tenant,
+    user,
+    session,
+    timestamp: timestamp || now(),
+    rowCount: typeof rowCount === 'number' ? rowCount : undefined,
+    durationMs: typeof durationMs === 'number' ? durationMs : undefined
+  };
+}
+
+module.exports = { buildContext };

package/lib/core/interceptor.js

@@ -0,0 +1,156 @@
+'use strict';
+
+const { buildContext } = require('./context');
+const { evaluate } = require('../policy/evaluator');
+const { maskFields } = require('../policy/masking');
+
+/**
+ * Reads W3C Trace Context fields propagated by the MCP runtime.
+ * SEP-414 carries these via `_meta.traceparent` / `_meta.tracestate`; HTTP
+ * transports may also set the headers directly. Missing values are fine —
+ * this never throws for a request that has neither.
+ */
+function extractTraceContext(req) {
+  const meta = (req && req._meta) || (req && req.data && req.data._meta) || {};
+  const headers = (req && req.http && req.http.req && req.http.req.headers) || {};
+
+  return {
+    traceparent: meta.traceparent || headers.traceparent,
+    tracestate: meta.tracestate || headers.tracestate
+  };
+}
+
+/**
+ * Reads AI-agent identity fields. Until an MCP runtime is wired in, these
+ * arrive (if at all) via the same `_meta` bag as the trace context.
+ */
+function extractAgentInfo(req) {
+  const meta = (req && req._meta) || (req && req.data && req.data._meta) || {};
+
+  return {
+    agentId: meta['gen_ai.agent.id'],
+    agentName: meta['gen_ai.agent.name'],
+    model: meta['gen_ai.request.model']
+  };
+}
+
+function resolveEntity(req) {
+  if (!req) return undefined;
+  if (typeof req.entity === 'string') return req.entity;
+  if (req.target && req.target.name) return req.target.name;
+  return undefined;
+}
+
+function resolveOperation(req) {
+  return (req && req.event) || undefined;
+}
+
+function resolveRowCount(results) {
+  if (Array.isArray(results)) return results.length;
+  if (results === undefined || results === null) return 0;
+  return 1;
+}
+
+/**
+ * Applies masked field values onto the live CAP results (single row or
+ * array of rows), mutating them in place — CAP reflects in-place edits
+ * made in an `after` handler back into the actual response. maskFields()
+ * itself stays pure; this is the one place that turns its (immutable)
+ * output into a real effect on the request.
+ */
+function applyMask(results, fieldsToMask) {
+  const masked = maskFields(results, fieldsToMask);
+  const items = Array.isArray(results) ? results : [results];
+  const maskedItems = Array.isArray(masked) ? masked : [masked];
+
+  items.forEach((item, i) => {
+    if (!item || typeof item !== 'object') return;
+    const maskedItem = maskedItems[i];
+    for (const field of fieldsToMask) {
+      if (Object.prototype.hasOwnProperty.call(item, field)) {
+        item[field] = maskedItem[field];
+      }
+    }
+  });
+}
+
+/**
+ * Attaches request interception to a CAP service instance, producing a
+ * guard context (see context.js) for every request that passes through it.
+ *
+ * If a `policyDefinition` is supplied, each context is also evaluated (see
+ * policy/evaluator.js) into a Decision. In `enforce` mode, any fields the
+ * Decision names in `fieldsToMask` are redacted on the real response before
+ * it reaches the caller. In `observe` mode the response is never touched —
+ * the Decision is still computed and handed to `onDecision`, but nothing
+ * about the request's outcome changes. Without a `policyDefinition`, this
+ * only observes and builds context — the M1 behavior.
+ *
+ * @param {object} srv a CAP service exposing before()/after() (duck-typed —
+ *   this module never imports @sap/cds)
+ * @param {object} [options]
+ * @param {(context: object, req: object) => void} [options.onContext]
+ *   called with the built context after each request completes
+ * @param {object} [options.policyDefinition] see lib/policy/config.js —
+ *   when omitted, no policy evaluation or masking happens
+ * @param {(decision: object, context: object, req: object) => void} [options.onDecision]
+ *   called with the Decision (and the Context it was computed from) after
+ *   each request completes, regardless of mode — this is the extension
+ *   point M5 (audit log) uses
+ * @param {() => string} [options.now] injectable clock, forwarded to buildContext
+ */
+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 clockDeps = now ? { now } : {};
+
+  srv.before('*', (req) => {
+    if (!req) return;
+    req._mcpGuardStartedAt = process.hrtime.bigint();
+  });
+
+  srv.after('*', (results, req) => {
+    if (!req) return;
+
+    const startedAt = req._mcpGuardStartedAt;
+    const durationMs = startedAt === undefined
+      ? 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
+    );
+
+    if (typeof onContext === 'function') {
+      onContext(context, req);
+    }
+
+    if (policyDefinition) {
+      const decision = evaluate(context, policyDefinition);
+
+      if (decision.mode === 'enforce' && decision.fieldsToMask.length > 0) {
+        applyMask(results, decision.fieldsToMask);
+      }
+
+      if (typeof onDecision === 'function') {
+        onDecision(decision, context, req);
+      }
+    }
+  });
+}
+
+module.exports = { attachInterceptor };

package/lib/index.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const { buildContext } = require('./core/context');
+const { attachInterceptor } = require('./core/interceptor');
+
+module.exports = { buildContext, attachInterceptor };

package/lib/otel/exporter.js

@@ -0,0 +1,104 @@
+'use strict';
+
+const { trace, context: otelContext, propagation, SpanStatusCode } = require('@opentelemetry/api');
+
+const TRACER_NAME = 'cap-mcp-guard';
+
+/**
+ * Maps a guard Context + Decision onto OTel span attributes. The Context's
+ * gen_ai.* keys are already valid OTel GenAI semantic-convention attribute
+ * names (that's why context.js was shaped this way back in M1) so they're
+ * passed through as-is; cap-mcp-guard's own fields get a namespaced prefix
+ * so they never collide with attributes a host app might already set.
+ *
+ * Pure — no OTel SDK calls, no I/O.
+ *
+ * @param {object} context see lib/core/context.js
+ * @param {object} decision see lib/policy/evaluator.js
+ * @returns {object} flat attribute map safe to pass to span.setAttributes()
+ */
+function buildSpanAttributes(context, decision) {
+  const attributes = {};
+
+  for (const [key, value] of Object.entries(context)) {
+    if (value === undefined) continue;
+    if (key === 'traceparent' || key === 'tracestate') continue;
+    attributes[key] = value;
+  }
+
+  attributes['cap_mcp_guard.mode'] = decision.mode;
+  attributes['cap_mcp_guard.allowed'] = decision.allowed;
+  attributes['cap_mcp_guard.fields_masked'] = decision.fieldsToMask;
+  attributes['cap_mcp_guard.row_limit_exceeded'] = decision.rowLimitExceeded;
+
+  if (decision.maxRows !== null && decision.maxRows !== undefined) {
+    attributes['cap_mcp_guard.max_rows'] = decision.maxRows;
+  }
+  if (decision.reason) {
+    attributes['cap_mcp_guard.reason'] = decision.reason;
+  }
+
+  return attributes;
+}
+
+/**
+ * Resolves the parent OTel context from the Context's W3C traceparent/
+ * tracestate (SEP-414), so a span started here links into whatever trace
+ * the calling MCP runtime is already part of. If the host application
+ * hasn't registered a propagator (or the request carried no traceparent),
+ * this is a harmless no-op and the span simply starts its own trace.
+ */
+function extractParentContext(context) {
+  if (!context.traceparent) return otelContext.active();
+
+  const carrier = { traceparent: context.traceparent };
+  if (context.tracestate) carrier.tracestate = context.tracestate;
+
+  return propagation.extract(otelContext.active(), carrier);
+}
+
+/**
+ * Records a single request's Context + Decision as a completed OTel span.
+ *
+ * Per OTel guidance for libraries (as opposed to applications), this never
+ * registers a global TracerProvider or exporter itself — it only calls
+ * trace.getTracer(), so it automatically ships spans through whatever OTLP
+ * exporter (or none at all) the host application has configured. Without a
+ * configured SDK, trace.getTracer() returns a no-op tracer and this is a
+ * safe no-op, consistent with the rest of the guard's "no config = pass
+ * through" behavior.
+ *
+ * The span is created retroactively with the request's real start/end
+ * time (derived from context.timestamp and context.durationMs) rather
+ * than wrapping the live request, since this runs from the `after` phase
+ * once the request has already completed.
+ *
+ * @param {object} context see lib/core/context.js
+ * @param {object} decision see lib/policy/evaluator.js
+ * @param {object} [options]
+ * @param {object} [options.tracer] injectable OTel tracer, defaults to
+ *   trace.getTracer('cap-mcp-guard')
+ * @returns {object} the ended span
+ */
+function exportSpan(context, decision, options = {}) {
+  const { tracer = trace.getTracer(TRACER_NAME) } = options;
+
+  const endTimeMs = Date.parse(context.timestamp);
+  const startTimeMs =
+    typeof context.durationMs === 'number' && Number.isFinite(endTimeMs)
+      ? endTimeMs - context.durationMs
+      : endTimeMs;
+
+  const spanName = [context.operation, context.entity].filter(Boolean).join(' ') || 'cap-mcp-guard.request';
+  const parentOtelContext = extractParentContext(context);
+
+  const span = tracer.startSpan(spanName, { startTime: startTimeMs }, parentOtelContext);
+
+  span.setAttributes(buildSpanAttributes(context, decision));
+  span.setStatus({ code: decision.allowed ? SpanStatusCode.OK : SpanStatusCode.ERROR });
+  span.end(endTimeMs);
+
+  return span;
+}
+
+module.exports = { buildSpanAttributes, exportSpan, TRACER_NAME };

package/lib/policy/config.js

@@ -0,0 +1,106 @@
+'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 };

package/lib/policy/evaluator.js

@@ -0,0 +1,56 @@
+'use strict';
+
+/**
+ * Evaluates a request Context (lib/core/context.js) against a
+ * PolicyDefinition (lib/policy/config.js) and produces a Decision — what
+ * *should* happen for this request. Nothing is enforced here: no fields are
+ * removed, no request is blocked, nothing is logged. Those are M4 (masking)
+ * and M5 (audit)'s job.
+ *
+ * Pure function: same inputs, same output. No CAP dependency.
+ *
+ * @param {object} context see lib/core/context.js buildContext() shape
+ * @param {object} policyDefinition see lib/policy/config.js parseConfig() shape
+ * @returns {object} Decision
+ */
+function evaluate(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
+    };
+  }
+
+  const { allowTools, maxRows, mask } = entityConfig;
+
+  let allowed = true;
+  let reason = null;
+  if (Array.isArray(allowTools) && !allowTools.includes(context.operation)) {
+    allowed = false;
+    reason = `tool '${context.operation}' not in allowTools for entity '${context.entity}'`;
+  }
+
+  const rowLimitExceeded =
+    typeof maxRows === 'number' && typeof context.rowCount === 'number' && context.rowCount > maxRows;
+
+  return {
+    mode: policyDefinition.mode,
+    allowed,
+    reason,
+    fieldsToMask: mask ?? [],
+    rowLimitExceeded,
+    maxRows: typeof maxRows === 'number' ? maxRows : null,
+    entity: context.entity,
+    timestamp: context.timestamp
+  };
+}
+
+module.exports = { evaluate };

package/lib/policy/masking.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const MASK_VALUE = '***MASKED***';
+
+function maskOne(item, fieldsToMask, maskValue) {
+  if (item === null || typeof item !== 'object' || Array.isArray(item)) return item;
+
+  const masked = { ...item };
+  for (const field of fieldsToMask) {
+    if (Object.prototype.hasOwnProperty.call(masked, field)) {
+      masked[field] = maskValue;
+    }
+  }
+  return masked;
+}
+
+/**
+ * Replaces the given fields' values with a mask placeholder. Pure and
+ * immutable: never mutates `data`, always returns a new object/array. No
+ * CAP dependency — operates on plain data.
+ *
+ * @param {object|object[]|null|undefined} data
+ * @param {string[]} fieldsToMask field names to redact (from Decision.fieldsToMask)
+ * @param {string} [maskValue] placeholder value, defaults to '***MASKED***'
+ * @returns {object|object[]|null|undefined} a new object/array with masked fields
+ */
+function maskFields(data, fieldsToMask, maskValue = MASK_VALUE) {
+  if (data === null || data === undefined) return data;
+
+  const fields = fieldsToMask || [];
+
+  if (Array.isArray(data)) {
+    return data.map((item) => maskOne(item, fields, maskValue));
+  }
+
+  return maskOne(data, fields, maskValue);
+}
+
+module.exports = { maskFields, MASK_VALUE };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "cap-mcp-guard",
+  "version": "0.1.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",
+    "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"
+  }
+}