cap-mcp-guard 0.1.0 → 0.2.0

package/README.md

@@ -96,6 +96,44 @@ entities:
 
 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.
 
+## OData
+
+`registerCapMcpGuard` hooks CAP's own `before`/`after` service events, which only exists inside a Node CAP process. A lot of business data reaches an MCP agent over OData without ever passing through those hooks — a plain OData V2/V4 service, a CAP Java service, or an on-prem SAP Gateway/S/4HANA system fronted by a proxy route. `odataMcpGuard` runs the same Context → Decision → mask/audit/OTel pipeline against raw OData HTTP traffic instead, using one `cap-mcp-guard.yaml`:
+
+```js
+const express = require('express');
+const { odataMcpGuard } = require('cap-mcp-guard');
+
+const app = express();
+app.use('/odata', odataMcpGuard(), proxyToYourODataBackend);
+```
+
+- Mount it in front of any route that responds via `res.json(body)` — your own OData handler, or a reverse-proxy route rewriting a remote OData service's response.
+- Entity names are resolved from the URL path (`/odata/v4/browse/Books(201)` → `Books`), so `cap-mcp-guard.yaml` keys entities by the same name whichever adapter is in front of them. HTTP methods map onto the same operation vocabulary CAP requests use (`GET`→`READ`, `POST`→`CREATE`, `PUT`/`PATCH`→`UPDATE`, `DELETE`→`DELETE`), so `allowTools` rules are portable too.
+- **`$expand` is masked too.** `?$expand=author` on a `Books` read pulls the related `Author` row inline — without any extra config, its fields are masked under an `author` entity entry; nested `$expand=genre($expand=parent)` is masked at every level. One audit/OTel entry is produced per entity in the response (root + each expanded nav), not just one per HTTP request.
+- **Pass real `$metadata` for exact entity resolution.** By default, entity names are guessed from the URL/nav-property text itself (`Books(201)/author` → `author`, not the real target entity). Pass `metadataXml` (an already-fetched `$metadata` EDMX/CSDL document — this module never fetches it itself) or a pre-parsed `edm` (see `lib/core/edm.js`), and both deep paths and `$expand` resolve through the real navigation properties instead (`Books(201)/author` → `Authors`):
+
+  ```js
+  const metadataXml = fs.readFileSync('./service.edmx', 'utf8'); // or fetch it once at startup
+  app.use('/odata', odataMcpGuard({ metadataXml }), proxyToYourODataBackend);
+  ```
+
+- **`$batch` is decoded too, both wire formats** — each sub-request inside a batch is masked/audited/traced individually, exactly like a standalone request:
+  - **OData V4 JSON batch** (`{ requests: [...] }` request / `{ responses: [...] }` response) needs `req.body` to already be the parsed request JSON — mount a JSON body-parser (`express.json()`) before this middleware.
+  - **Classic OData V2 `multipart/mixed` batch** (including changesets — grouped write operations) needs `req.body` to already be the *raw* request body, and goes out via `res.send(rawBody)` rather than `res.json()`:
+
+    ```js
+    const express = require('express');
+    app.use(
+      '/sap/opu/odata',
+      express.raw({ type: 'multipart/mixed' }), // populates req.body for $batch requests
+      odataMcpGuard(),
+      proxyToYourODataBackend
+    );
+    ```
+
+  If a batch can't be decoded either way (missing/wrong `req.body`, no boundary, malformed MIME), it still produces one Context/Decision/audit entry (with an undefined entity) so it isn't silently unaccounted for — it's just unmasked.
+
 ## 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`.
@@ -113,7 +151,6 @@ npm start   # boots a real server at localhost:4004 — flip cap-mcp-guard.yaml
 - `@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

package/lib/adapters/odata.js

@@ -0,0 +1,366 @@
+'use strict';
+
+const path = require('path');
+
+const { buildContext } = require('../core/context');
+const { resolveEntityPath, resolveOperation, isBatchRequest, collectMaskableGroups } = require('../core/odata');
+const { parseMetadata, parseExpandOption } = require('../core/edm');
+const { extractBoundary, parseBatchRequests, parseBatchResponses, serializeBatchResponses } = require('../core/odata-batch');
+const { evaluate } = require('../policy/evaluator');
+const { maskFields } = require('../policy/masking');
+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 `cwd` — same convention and same file
+ * lib/adapters/cap.js reads, so one policy file covers both a CAP app's
+ * own service layer and any OData traffic this middleware fronts. A
+ * missing config is a valid "not configured yet" state (pass-through); a
+ * config that exists but fails to parse propagates (see cap.js for the
+ * same reasoning).
+ *
+ * @param {string} [cwd] defaults to process.cwd()
+ */
+function resolvePolicyDefinition(cwd) {
+  const configPath = path.join(cwd || 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;
+  }
+}
+
+/**
+ * OData has no MCP-runtime `_meta` bag to read (that's a CAP/CDS-side
+ * convention) — the wire-level equivalent is plain HTTP headers, which any
+ * proxying MCP runtime can set alongside a request it forwards.
+ */
+function extractTraceContext(req) {
+  const headers = (req && req.headers) || {};
+  return { traceparent: headers.traceparent, tracestate: headers.tracestate };
+}
+
+function extractAgentInfo(req) {
+  const headers = (req && req.headers) || {};
+  return {
+    agentId: headers['x-gen-ai-agent-id'],
+    agentName: headers['x-gen-ai-agent-name'],
+    model: headers['x-gen-ai-request-model']
+  };
+}
+
+function getExpandTree(url) {
+  const query = (url || '').split('?')[1];
+  if (!query) return {};
+
+  const expand = new URLSearchParams(query).get('$expand');
+  return parseExpandOption(expand);
+}
+
+/**
+ * Same in-place-mutation strategy as lib/core/interceptor.js's applyMask:
+ * maskFields() itself stays pure, this is the one place that turns its
+ * (immutable) output into a real effect on the rows already referenced
+ * inside the response body (see extractResultRows / collectMaskableGroups).
+ */
+function applyMask(rows, fieldsToMask) {
+  const masked = maskFields(rows, fieldsToMask);
+
+  rows.forEach((row, i) => {
+    if (!row || typeof row !== 'object') return;
+    for (const field of fieldsToMask) {
+      if (Object.prototype.hasOwnProperty.call(row, field)) {
+        row[field] = masked[i][field];
+      }
+    }
+  });
+}
+
+/**
+ * Builds an Express-compatible middleware `(req, res, next)` that runs the
+ * same Context → Decision → mask/audit/OTel pipeline as
+ * lib/adapters/cap.js, driven off raw OData HTTP request/response instead
+ * of CAP's before()/after() hooks. Mount it in front of ANY OData V2/V4
+ * traffic — a hand-rolled OData service, a proxy route to SAP Gateway or
+ * S/4HANA, a CAP Java service, or this same CAP Node app's own OData
+ * endpoint — regardless of what produced it, since it only ever looks at
+ * the HTTP request/response, never at a CDS model.
+ *
+ * Entity resolution is URL-path-based (lib/core/odata.js's
+ * resolveEntityPath()). Without `metadataXml`/`edm`, it's a last-path-
+ * segment heuristic, same as before; pass either one to resolve deep
+ * paths (`Books(201)/author`) and `$expand`'ed nested entities
+ * (`?$expand=author`) against the real EDM, so masking reaches nested
+ * data too, not just the top-level rows.
+ *
+ * `$batch` requests are decoded on BOTH wire formats, each sub-request
+ * masked/audited/traced individually exactly like a standalone request:
+ *   - OData V4 JSON batch (`{ requests: [...] }` request body /
+ *     `{ responses: [...] }` response body) — requires `req.body` to
+ *     already be the parsed JSON request (i.e. a JSON body-parser like
+ *     `express.json()` ran before this middleware).
+ *   - Classic OData V2 `multipart/mixed` batch (see lib/core/odata-batch.js)
+ *     — requires `req.body` to already be the raw request Buffer/string
+ *     (e.g. `express.raw({ type: 'multipart/mixed' })` ran before this
+ *     middleware) and goes out via `res.send(rawBody)`, not `res.json()`.
+ * If a batch can't be decoded either way (wrong/missing `req.body`,
+ * missing boundary, malformed MIME), it still produces one Context/
+ * Decision/audit entry (with an undefined entity) so it isn't silently
+ * unaccounted for — it's just unmasked.
+ *
+ * Response bodies are only inspected when the downstream handler calls
+ * `res.json(body)` (always) or, for a batch request specifically,
+ * `res.send(rawBody)` too — this middleware wraps those methods for the
+ * life of the request. If `res.json` isn't a function (a bare Node `http`
+ * response, or a framework that never provides it), the middleware warns
+ * once and passes every request through unguarded rather than throwing.
+ *
+ * @param {object} [options]
+ * @param {object} [options.policyDefinition] see lib/policy/config.js —
+ *   when omitted, loaded from cap-mcp-guard.yaml in options.cwd
+ * @param {string} [options.cwd] directory cap-mcp-guard.yaml is resolved
+ *   from when policyDefinition isn't supplied — defaults to process.cwd()
+ * @param {string} [options.metadataXml] a `$metadata` EDMX/CSDL document
+ *   (already fetched — this module never makes network calls itself),
+ *   parsed once via lib/core/edm.js's parseMetadata()
+ * @param {object} [options.edm] an already-parsed EDM (see
+ *   lib/core/edm.js parseMetadata()) — takes precedence over metadataXml
+ * @param {(context: object, req: object) => void} [options.onContext]
+ *   called with the built context after each request completes
+ * @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
+ * @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
+ * @param {() => string} [options.now] injectable clock, forwarded to buildContext
+ * @returns {(req: object, res: object, next: Function) => void}
+ */
+function odataMcpGuard(options = {}) {
+  const policyDefinition = options.policyDefinition || resolvePolicyDefinition(options.cwd);
+  const { onContext, onDecision: userOnDecision, audit, otel, now } = options;
+  const edm = options.edm || (options.metadataXml && parseMetadata(options.metadataXml));
+  const clockDeps = now ? { now } : {};
+
+  let warnedNoJson = false;
+
+  /**
+   * The full Context → Decision → mask/audit/OTel pipeline for one logical
+   * request — either the request as a whole, or (for a decoded $batch)
+   * one of its sub-requests. Mutates `rows` in place when enforcing.
+   */
+  function runPipeline({ req, entity, operation, rows, rowCount, durationMs }) {
+    const context = buildContext(
+      {
+        ...extractAgentInfo(req),
+        ...extractTraceContext(req),
+        entity,
+        operation,
+        tenant: req.headers && req.headers['sap-tenantid'],
+        user: req.user && (req.user.id || req.user.name),
+        session: req.headers && req.headers['x-request-id'],
+        rowCount,
+        durationMs
+      },
+      clockDeps
+    );
+
+    if (typeof onContext === 'function') onContext(context, req);
+    if (!policyDefinition) return;
+
+    const decision = evaluate(context, policyDefinition);
+
+    if (decision.mode === 'enforce' && decision.fieldsToMask.length > 0) {
+      applyMask(rows, decision.fieldsToMask);
+    }
+
+    if (audit !== false) logAudit(context, decision, audit);
+    if (otel !== false) exportSpan(context, decision, otel);
+    if (typeof userOnDecision === 'function') userOnDecision(decision, context, req);
+  }
+
+  /** Runs one sub-request's worth of the pipeline, grouping $expand-ed nested entities too. */
+  function runSubRequestPipeline(req, url, method, responseBody, durationMs) {
+    const entity = resolveEntityPath(url, edm);
+    const operation = resolveOperation(method);
+    const expandTree = getExpandTree(url);
+    const groups = collectMaskableGroups(responseBody, entity, expandTree, edm);
+
+    if (groups.length === 0) {
+      runPipeline({ req, entity, operation, rows: [], rowCount: responseBody === undefined ? undefined : 0, durationMs });
+      return;
+    }
+
+    for (const group of groups) {
+      runPipeline({ req, entity: group.entity, operation, rows: group.rows, rowCount: group.rows.length, durationMs });
+    }
+  }
+
+  /**
+   * Decodes and guards an OData V4 JSON batch: `req.body.requests` (each
+   * `{ id, method, url, ... }`) matched by `id` to `body.responses` (each
+   * `{ id, status, body, ... }`), so every sub-request is resolved,
+   * evaluated, and masked exactly like a standalone request would be.
+   * Returns false (nothing decoded — caller falls back to legacy
+   * pass-through) when either side isn't shaped like a V4 JSON batch.
+   */
+  function runJsonBatchPipeline(req, body, durationMs) {
+    const requests = req.body && Array.isArray(req.body.requests) ? req.body.requests : undefined;
+    const responses = body && Array.isArray(body.responses) ? body.responses : undefined;
+    if (!requests || !responses) return false;
+
+    const requestById = new Map(requests.map((r) => [r.id, r]));
+
+    for (const responseEntry of responses) {
+      const subRequest = requestById.get(responseEntry.id);
+      if (!subRequest || !subRequest.url) continue;
+
+      runSubRequestPipeline(req, subRequest.url, subRequest.method, responseEntry.body, durationMs);
+    }
+
+    return true;
+  }
+
+  /**
+   * Zips a parsed batch request tree to its response tree by position —
+   * each top-level (or changeset-nested) request corresponds to exactly
+   * one response in the same slot, per OData $batch semantics. Mismatched
+   * shapes (a 'single' lined up against a 'changeset', or a length
+   * mismatch) are skipped rather than crashing the response.
+   */
+  function zipClassicBatch(req, requestItems, responseItems, durationMs) {
+    const len = Math.min(requestItems.length, responseItems.length);
+
+    for (let i = 0; i < len; i++) {
+      const reqItem = requestItems[i];
+      const resItem = responseItems[i];
+
+      if (reqItem.kind === 'changeset' && resItem.kind === 'changeset') {
+        zipClassicBatch(req, reqItem.parts, resItem.parts, durationMs);
+        continue;
+      }
+      if (reqItem.kind !== 'single' || resItem.kind !== 'single') continue;
+
+      let parsedBody;
+      try {
+        parsedBody = resItem.body ? JSON.parse(resItem.body) : undefined;
+      } catch {
+        parsedBody = undefined;
+      }
+
+      runSubRequestPipeline(req, reqItem.url, reqItem.method, parsedBody, durationMs);
+      if (parsedBody !== undefined) resItem.body = JSON.stringify(parsedBody);
+    }
+  }
+
+  /**
+   * Decodes and guards a classic OData V2 `multipart/mixed` $batch: parses
+   * `req.body` (the raw request body — a JSON body-parser won't populate
+   * this for a multipart content-type, so the host needs something like
+   * `express.raw({ type: 'multipart/mixed' })` mounted first) and the raw
+   * response body about to be sent, zips requests to responses by
+   * position, masks each response's JSON in place, and returns the
+   * re-serialized response body. Returns false (caller falls back to
+   * legacy pass-through) when either side can't be decoded as multipart —
+   * missing boundary, `req.body` not pre-buffered, or malformed MIME.
+   */
+  function runClassicBatchPipeline(req, res, rawResponseBody, durationMs) {
+    const reqBoundary = extractBoundary(req.headers && req.headers['content-type']);
+    const resBoundary = extractBoundary(typeof res.getHeader === 'function' ? res.getHeader('content-type') : undefined);
+
+    const rawRequestBody = req.body;
+    const requestIsBufferLike = typeof rawRequestBody === 'string' || Buffer.isBuffer(rawRequestBody);
+    const responseIsBufferLike = typeof rawResponseBody === 'string' || Buffer.isBuffer(rawResponseBody);
+
+    if (!reqBoundary || !resBoundary || !requestIsBufferLike || !responseIsBufferLike) return false;
+
+    let requestItems;
+    let responseItems;
+    try {
+      requestItems = parseBatchRequests(rawRequestBody, reqBoundary);
+      responseItems = parseBatchResponses(rawResponseBody, resBoundary);
+    } catch {
+      return false; // malformed multipart — don't crash the response, fall back to legacy pass-through
+    }
+
+    zipClassicBatch(req, requestItems, responseItems, durationMs);
+    return serializeBatchResponses(responseItems, resBoundary);
+  }
+
+  return function odataMcpGuardMiddleware(req, res, next) {
+    if (typeof res.json !== 'function') {
+      if (!warnedNoJson) {
+        console.warn('[cap-mcp-guard] res.json is not available; OData responses will pass through unguarded');
+        warnedNoJson = true;
+      }
+      return next();
+    }
+
+    const startedAt = process.hrtime.bigint();
+    const operation = resolveOperation(req.method);
+    const batch = isBatchRequest(req.url);
+    const originalJson = res.json.bind(res);
+
+    // Shared between the res.json and res.send patches below: Express's
+    // real res.json() (captured as originalJson) internally calls
+    // this.send(...) — since that resolves to OUR patched res.send when
+    // `batch` is true, this flag stops the batch already handled by
+    // guardedJson from being processed a second time by guardedSend.
+    let handled = false;
+
+    res.json = function guardedJson(body) {
+      if (handled) return originalJson(body);
+      handled = true;
+
+      const durationMs = Number(process.hrtime.bigint() - startedAt) / 1e6;
+
+      if (batch) {
+        if (!runJsonBatchPipeline(req, body, durationMs)) {
+          // classic multipart/mixed batch that didn't go through res.send,
+          // or req.body wasn't pre-parsed: still audited, nothing masked
+          runPipeline({ req, entity: undefined, operation, rows: [], rowCount: undefined, durationMs });
+        }
+        return originalJson(body);
+      }
+
+      runSubRequestPipeline(req, req.url, req.method, body, durationMs);
+      return originalJson(body);
+    };
+
+    // Classic multipart/mixed $batch responses go out via res.send(rawBody),
+    // never res.json() — only patch res.send for batch requests, so the
+    // (already tested) non-batch path never touches it.
+    if (batch && typeof res.send === 'function') {
+      const originalSend = res.send.bind(res);
+
+      res.send = function guardedSend(bodyChunk) {
+        if (handled) return originalSend(bodyChunk);
+        handled = true;
+
+        const durationMs = Number(process.hrtime.bigint() - startedAt) / 1e6;
+        const newBody = runClassicBatchPipeline(req, res, bodyChunk, durationMs);
+
+        if (newBody !== false) return originalSend(newBody);
+
+        // couldn't decode as classic multipart batch either: still audited
+        runPipeline({ req, entity: undefined, operation, rows: [], rowCount: undefined, durationMs });
+        return originalSend(bodyChunk);
+      };
+    }
+
+    next();
+  };
+}
+
+module.exports = { odataMcpGuard };

package/lib/core/edm.js

@@ -0,0 +1,241 @@
+'use strict';
+
+/**
+ * A hand-rolled, regex-based reader for OData `$metadata` documents (EDMX/
+ * CSDL XML, V2 or V4) — not a general-purpose XML/EDM implementation, just
+ * enough structure (entity sets, entity types, navigation properties) to
+ * resolve a URL path or a `$expand` nav-property name down to the entity
+ * name cap-mcp-guard.yaml keys entities by. Good enough for the
+ * well-formed $metadata documents SAP/CAP services actually emit.
+ *
+ * Pure — no I/O. Fetching `$metadata` over the network is the caller's
+ * responsibility (see lib/adapters/odata.js's `metadataXml`/`edm` options);
+ * keeping that out of this module means it stays synchronous and
+ * dependency-free.
+ */
+
+function matchAll(pattern, text) {
+  const results = [];
+  const re = new RegExp(pattern, 'g');
+  let m;
+  while ((m = re.exec(text))) results.push(m);
+  return results;
+}
+
+function getAttr(tagAttrs, name) {
+  const m = new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`).exec(tagAttrs);
+  return m ? m[1] : undefined;
+}
+
+function unwrapCollection(type) {
+  const m = /^Collection\(([^)]+)\)$/.exec(type || '');
+  return m ? { target: m[1], isCollection: true } : { target: type, isCollection: false };
+}
+
+function unqualifiedName(fqName) {
+  if (!fqName) return fqName;
+  const idx = fqName.lastIndexOf('.');
+  return idx === -1 ? fqName : fqName.slice(idx + 1);
+}
+
+/**
+ * Parses an EDMX/CSDL XML string into a minimal EDM model.
+ *
+ * @param {string} xml
+ * @returns {{
+ *   entityTypes: Record<string, { navigationProperties: Record<string, { target: string, isCollection?: boolean }> }>,
+ *   entitySets: Record<string, string>,
+ *   entityTypeToSet: Record<string, string>
+ * }}
+ */
+function parseMetadata(xml) {
+  const entityTypes = {};
+  const entitySets = {};
+  const entityTypeToSet = {};
+
+  const schemaBlocks = matchAll('<Schema\\b([^>]*)>([\\s\\S]*?)</Schema>', xml);
+
+  for (const schemaMatch of schemaBlocks) {
+    const namespace = getAttr(schemaMatch[1], 'Namespace');
+    const schemaBody = schemaMatch[2];
+    if (!namespace) continue;
+
+    // V2 only: NavigationProperty indirects through Relationship/ToRole to
+    // an <Association>'s <End Role="..." Type="...">. V4 NavigationProperty
+    // carries its target Type directly, no association needed.
+    const associations = {};
+    for (const assocMatch of matchAll('<Association\\b[^>]*Name="([^"]*)"[^>]*>([\\s\\S]*?)</Association>', schemaBody)) {
+      const fqName = `${namespace}.${assocMatch[1]}`;
+      const roles = {};
+      for (const endMatch of matchAll('<End\\b([^>]*?)/?>', assocMatch[2])) {
+        const role = getAttr(endMatch[1], 'Role');
+        const type = getAttr(endMatch[1], 'Type');
+        if (role && type) roles[role] = type;
+      }
+      associations[fqName] = roles;
+    }
+
+    for (const entityTypeMatch of matchAll('<EntityType\\b([^>]*)>([\\s\\S]*?)</EntityType>', schemaBody)) {
+      const localName = getAttr(entityTypeMatch[1], 'Name');
+      if (!localName) continue;
+      const fqName = `${namespace}.${localName}`;
+      const body = entityTypeMatch[2];
+
+      const navigationProperties = {};
+      for (const navMatch of matchAll('<NavigationProperty\\b([^>]*?)/?>', body)) {
+        const attrs = navMatch[1];
+        const navName = getAttr(attrs, 'Name');
+        if (!navName) continue;
+
+        const typeAttr = getAttr(attrs, 'Type');
+        if (typeAttr) {
+          navigationProperties[navName] = unwrapCollection(typeAttr);
+          continue;
+        }
+
+        const relationship = getAttr(attrs, 'Relationship');
+        const toRole = getAttr(attrs, 'ToRole');
+        const target = relationship && toRole && associations[relationship] && associations[relationship][toRole];
+        if (target) {
+          navigationProperties[navName] = { target, isCollection: undefined };
+        }
+      }
+
+      entityTypes[fqName] = { navigationProperties };
+    }
+
+    for (const setMatch of matchAll('<EntitySet\\b([^>]*?)/?>', schemaBody)) {
+      const attrs = setMatch[1];
+      const setName = getAttr(attrs, 'Name');
+      const entityType = getAttr(attrs, 'EntityType');
+      if (!setName || !entityType) continue;
+
+      entitySets[setName] = entityType;
+      if (!entityTypeToSet[entityType]) entityTypeToSet[entityType] = setName;
+    }
+  }
+
+  return { entityTypes, entitySets, entityTypeToSet };
+}
+
+/** An entity set name when one maps to this type, else its bare local name. */
+function toDisplayName(edm, fqTypeName) {
+  return (edm.entityTypeToSet && edm.entityTypeToSet[fqTypeName]) || unqualifiedName(fqTypeName);
+}
+
+/**
+ * Resolves already-split, already-`(key)`-stripped, $-segment-free URL path
+ * segments against a parsed EDM, walking navigation properties hop by hop
+ * from the first segment that matches a known entity set (segments before
+ * that — a service mount path like `odata/v4/browse` — are ignored, so
+ * this works regardless of where the service is mounted).
+ *
+ * Falls back to the last path segment (matching lib/core/odata.js's
+ * no-metadata resolveEntitySet() heuristic) when no segment matches a
+ * known entity set, and to the raw segment name at any hop whose nav
+ * property isn't described in the EDM — a `$metadata` document that
+ * doesn't fully describe every segment shouldn't break resolution for the
+ * segments it DOES know about.
+ *
+ * @param {object} edm see parseMetadata()
+ * @param {string[]} segments
+ * @returns {string|undefined}
+ */
+function resolveEntityForPath(edm, segments) {
+  if (!segments.length) return undefined;
+
+  const startIndex = segments.findIndex((s) => Object.prototype.hasOwnProperty.call(edm.entitySets, s));
+  if (startIndex === -1) return segments[segments.length - 1];
+
+  let currentType = edm.entitySets[segments[startIndex]];
+  let displayName = toDisplayName(edm, currentType);
+
+  for (let i = startIndex + 1; i < segments.length; i++) {
+    const entityType = currentType && edm.entityTypes[currentType];
+    const nav = entityType && entityType.navigationProperties[segments[i]];
+
+    if (!nav) {
+      displayName = segments[i];
+      currentType = undefined;
+      continue;
+    }
+
+    currentType = nav.target;
+    displayName = toDisplayName(edm, currentType);
+  }
+
+  return displayName;
+}
+
+/**
+ * Resolves a `$expand`'ed navigation-property name to its target entity's
+ * policy-config-friendly name, given the (already-resolved) entity name of
+ * the row it hangs off of. Falls back to the raw nav-property name when
+ * the parent entity or the nav property itself isn't described in the EDM.
+ *
+ * @param {object} edm
+ * @param {string} parentEntityName as returned by resolveEntityForPath() or
+ *   a previous resolveExpandTarget() call
+ * @param {string} navPropName
+ * @returns {string}
+ */
+function resolveExpandTarget(edm, parentEntityName, navPropName) {
+  const parentType =
+    edm.entitySets[parentEntityName] ||
+    Object.keys(edm.entityTypes).find((fq) => toDisplayName(edm, fq) === parentEntityName);
+
+  const entityType = parentType && edm.entityTypes[parentType];
+  const nav = entityType && entityType.navigationProperties[navPropName];
+
+  return nav ? toDisplayName(edm, nav.target) : navPropName;
+}
+
+/**
+ * Parses an OData `$expand` query-option value into a tree of nav-property
+ * names to recurse into — e.g. `"author,genre($expand=parent)"` becomes
+ * `{ author: {}, genre: { parent: {} } }`. Only a nested `$expand=` option
+ * is honored inside a parenthesized nav property; other nested options
+ * (`$select`, `$filter`, ...) don't change which nested entities show up
+ * in the response body, so they're ignored.
+ *
+ * @param {string} expandParam raw (already URL-decoded) $expand value
+ * @returns {object} nested tree, `{}` for an empty/missing value
+ */
+function parseExpandOption(expandParam) {
+  const tree = {};
+  if (!expandParam) return tree;
+
+  const parts = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < expandParam.length; i++) {
+    const ch = expandParam[i];
+    if (ch === '(') depth++;
+    else if (ch === ')') depth--;
+    else if (ch === ',' && depth === 0) {
+      parts.push(expandParam.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(expandParam.slice(start));
+
+  for (const rawPart of parts) {
+    const part = rawPart.trim();
+    if (!part) continue;
+
+    const parenIdx = part.indexOf('(');
+    if (parenIdx === -1) {
+      tree[part] = tree[part] || {};
+      continue;
+    }
+
+    const navName = part.slice(0, parenIdx).trim();
+    const inner = part.slice(parenIdx + 1, part.lastIndexOf(')'));
+    const nestedExpandMatch = /\$expand=([^;]*)/.exec(inner);
+    tree[navName] = parseExpandOption(nestedExpandMatch ? nestedExpandMatch[1] : '');
+  }
+
+  return tree;
+}
+
+module.exports = { parseMetadata, resolveEntityForPath, resolveExpandTarget, parseExpandOption };

package/lib/core/odata-batch.js

@@ -0,0 +1,161 @@
+'use strict';
+
+/**
+ * A minimal reader/writer for the classic OData V2 `$batch` wire format:
+ * a `multipart/mixed` body whose parts are either a single embedded HTTP
+ * request/response (`Content-Type: application/http`) or a nested
+ * `multipart/mixed` "changeset" grouping several write operations
+ * atomically. Not a general-purpose MIME implementation — just enough
+ * structure to zip a batch's requests to its responses by position and
+ * mask each response's JSON body in place.
+ *
+ * Responses are re-serialized canonically (consistent CRLF line endings,
+ * consistent header ordering per part) rather than byte-for-byte
+ * preserved — that's syntactically equivalent multipart/mixed, which is
+ * all any compliant OData client relies on; it does not reproduce the
+ * exact original bytes.
+ *
+ * Pure — no I/O, no HTTP framework dependency.
+ */
+
+function toText(value) {
+  return Buffer.isBuffer(value) ? value.toString('utf8') : String(value ?? '');
+}
+
+/**
+ * @param {string} contentType a Content-Type header value
+ * @returns {string|undefined} the `boundary` parameter, unquoted
+ */
+function extractBoundary(contentType) {
+  const m = /boundary=("?)([^;"]+)\1/i.exec(contentType || '');
+  return m ? m[2] : undefined;
+}
+
+/** Splits a multipart body into its raw part strings, boundary markers stripped. */
+function splitMultipart(rawBody, boundary) {
+  const text = toText(rawBody);
+  const marker = `--${boundary}`;
+  const segments = text.split(marker);
+
+  const parts = [];
+  for (let i = 1; i < segments.length; i++) {
+    const segment = segments[i];
+    if (segment.startsWith('--')) break; // the closing "--boundary--" marker
+
+    const trimmed = segment.replace(/^\r?\n/, '').replace(/\r?\n$/, '');
+    if (trimmed.length) parts.push(trimmed);
+  }
+  return parts;
+}
+
+function splitHeadersAndBody(text) {
+  const m = /\r?\n\r?\n/.exec(text);
+  if (!m) return { headerBlock: text, body: '' };
+  return { headerBlock: text.slice(0, m.index), body: text.slice(m.index + m[0].length) };
+}
+
+function parseHeaderBlock(headerBlock) {
+  const headers = {};
+  for (const line of headerBlock.split(/\r?\n/)) {
+    const m = /^([^:]+):\s*(.*)$/.exec(line);
+    if (m) headers[m[1].trim().toLowerCase()] = m[2].trim();
+  }
+  return headers;
+}
+
+/** One embedded `application/http` part: a request-line/status-line, headers, and a body. */
+function parseHttpEnvelope(text, { isResponse }) {
+  const { headerBlock, body } = splitHeadersAndBody(text);
+  const [firstLine, ...headerLines] = headerBlock.split(/\r?\n/);
+
+  if (isResponse) {
+    const m = /^HTTP\/[\d.]+\s+(\d+)\s*(.*)$/.exec((firstLine || '').trim());
+    return {
+      kind: 'single',
+      status: m ? Number(m[1]) : 200,
+      statusText: m ? m[2].trim() : 'OK',
+      headerLines: headerLines.filter((l) => l.trim().length > 0),
+      body
+    };
+  }
+
+  const m = /^(\S+)\s+(\S+)\s+HTTP\/[\d.]+$/.exec((firstLine || '').trim());
+  return {
+    kind: 'single',
+    method: m ? m[1] : undefined,
+    url: m ? m[2] : undefined,
+    headerLines: headerLines.filter((l) => l.trim().length > 0),
+    body
+  };
+}
+
+/** Parses one top-level (or changeset-nested) batch part, recursing into changesets. */
+function parseBatchPart(rawPart, { isResponse }) {
+  const { headerBlock, body } = splitHeadersAndBody(rawPart);
+  const headers = parseHeaderBlock(headerBlock);
+  const contentType = headers['content-type'] || '';
+
+  if (/multipart\/mixed/i.test(contentType)) {
+    const nestedBoundary = extractBoundary(contentType);
+    return {
+      kind: 'changeset',
+      boundary: nestedBoundary,
+      parts: nestedBoundary ? splitMultipart(body, nestedBoundary).map((p) => parseBatchPart(p, { isResponse })) : []
+    };
+  }
+
+  return parseHttpEnvelope(body, { isResponse });
+}
+
+/**
+ * @param {string|Buffer} rawBody the $batch request body
+ * @param {string} boundary from the request's Content-Type header
+ * @returns {object[]} tree of `{ kind: 'single', method, url, ... } | { kind: 'changeset', boundary, parts }`
+ */
+function parseBatchRequests(rawBody, boundary) {
+  return splitMultipart(rawBody, boundary).map((p) => parseBatchPart(p, { isResponse: false }));
+}
+
+/**
+ * @param {string|Buffer} rawBody the $batch response body
+ * @param {string} boundary from the response's Content-Type header
+ * @returns {object[]} tree of `{ kind: 'single', status, statusText, headerLines, body } | { kind: 'changeset', boundary, parts }`
+ */
+function parseBatchResponses(rawBody, boundary) {
+  return splitMultipart(rawBody, boundary).map((p) => parseBatchPart(p, { isResponse: true }));
+}
+
+function serializeEnvelope(envelope) {
+  const startLine = `HTTP/1.1 ${envelope.status} ${envelope.statusText}`;
+  const headerText = envelope.headerLines.map((l) => `${l}\r\n`).join('');
+  return `${startLine}\r\n${headerText}\r\n${envelope.body}`;
+}
+
+/**
+ * Re-serializes a (possibly mutated) response tree — see parseBatchResponses()
+ * — back into a valid `multipart/mixed` body using `boundary`.
+ *
+ * @param {object[]} items as returned by parseBatchResponses()
+ * @param {string} boundary
+ * @returns {string}
+ */
+function serializeBatchResponses(items, boundary) {
+  let out = '';
+
+  for (const item of items) {
+    out += `--${boundary}\r\n`;
+
+    if (item.kind === 'changeset') {
+      out += `Content-Type: multipart/mixed; boundary=${item.boundary}\r\n\r\n`;
+      out += serializeBatchResponses(item.parts, item.boundary);
+    } else {
+      out += `Content-Type: application/http\r\nContent-Transfer-Encoding: binary\r\n\r\n`;
+      out += `${serializeEnvelope(item)}\r\n`;
+    }
+  }
+
+  out += `--${boundary}--\r\n`;
+  return out;
+}
+
+module.exports = { extractBoundary, splitMultipart, parseBatchRequests, parseBatchResponses, serializeBatchResponses };

package/lib/core/odata.js

@@ -0,0 +1,178 @@
+'use strict';
+
+const { resolveEntityForPath, resolveExpandTarget } = require('./edm');
+
+const ODATA_SYSTEM_SEGMENTS = new Set(['$metadata', '$batch']);
+
+const METHOD_TO_OPERATION = {
+  GET: 'READ',
+  POST: 'CREATE',
+  PUT: 'UPDATE',
+  PATCH: 'UPDATE',
+  MERGE: 'UPDATE',
+  DELETE: 'DELETE'
+};
+
+/**
+ * Resolves the OData entity-set (or navigation property) name a request
+ * targets, from its URL path alone — no service metadata ($metadata/CSDL)
+ * is consulted. Works for both OData V2 (`/sap/opu/odata/sap/ZGW_SRV/Products`)
+ * and V4 (`/odata/v4/browse/Books(201)`) path conventions: it's the last
+ * path segment, with any `(key)` predicate stripped.
+ *
+ * Returns undefined for OData system resources ($metadata, $batch) since
+ * those don't map to a single configurable entity.
+ *
+ * Pure function, no HTTP framework dependency.
+ *
+ * @param {string} url request path or full URL (query string is ignored)
+ * @returns {string|undefined}
+ */
+function resolveEntitySet(url) {
+  if (!url) return undefined;
+
+  const pathOnly = url.split('?')[0];
+  const segments = pathOnly.split('/').filter(Boolean);
+  if (segments.length === 0) return undefined;
+
+  const last = segments[segments.length - 1].replace(/\(.*$/, '');
+  if (!last || ODATA_SYSTEM_SEGMENTS.has(last) || last.startsWith('$')) return undefined;
+
+  return last;
+}
+
+/**
+ * Maps an HTTP method onto the same CQN-style operation vocabulary the
+ * guard already uses for CAP requests (READ/CREATE/UPDATE/DELETE, see
+ * lib/adapters/cap.js's resolveOperation) — so one cap-mcp-guard.yaml
+ * applies unchanged whether traffic arrives via CAP's before/after hooks
+ * or raw OData HTTP.
+ *
+ * @param {string} method
+ * @returns {string|undefined}
+ */
+function resolveOperation(method) {
+  return METHOD_TO_OPERATION[(method || '').toUpperCase()];
+}
+
+/**
+ * @param {string} url
+ * @returns {boolean} true for a $batch request (OData V2 and V4 both use
+ *   this convention). Its body is a multipart mix of sub-requests this
+ *   module does not decode, so per-entity masking does not reach inside it
+ *   — see README "Limitations".
+ */
+function isBatchRequest(url) {
+  if (!url) return false;
+  const pathOnly = url.split('?')[0];
+  return pathOnly.split('/').filter(Boolean).pop() === '$batch';
+}
+
+/**
+ * Extracts the row objects an OData JSON response body carries, regardless
+ * of whether it's a V2 collection (`{ d: { results: [...] } }`), a V2
+ * single entity (`{ d: {...} }`), a V4 collection (`{ value: [...] }`), or
+ * a V4 single entity (a bare entity object carrying `@odata.context`).
+ *
+ * The returned rows are the SAME object references found inside `body` —
+ * mutating a returned row mutates the response body in place, mirroring
+ * how CAP's `after` handlers mutate results in place (see
+ * lib/core/interceptor.js's applyMask).
+ *
+ * @param {*} body parsed JSON response body
+ * @returns {object[]} row objects (empty array if the shape is unrecognized)
+ */
+function extractResultRows(body) {
+  if (!body || typeof body !== 'object') return [];
+
+  if (Array.isArray(body.value)) return body.value;
+  if (body.d && Array.isArray(body.d.results)) return body.d.results;
+  if (body.d && typeof body.d === 'object') return [body.d];
+  if ('@odata.context' in body) return [body];
+
+  return [];
+}
+
+/**
+ * Resolves the FULL request path (every segment, not just the last) into
+ * a policy-config-friendly entity name. Without `edm`, this is exactly
+ * resolveEntitySet()'s single-last-segment heuristic — unchanged behavior.
+ * With `edm` (see lib/core/edm.js's parseMetadata()), the whole path is
+ * walked hop-by-hop through navigation properties, so a deep path like
+ * `Books(201)/author` resolves to `author`'s real target entity instead
+ * of the literal string `"author"`.
+ *
+ * @param {string} url
+ * @param {object} [edm] see lib/core/edm.js parseMetadata()
+ * @returns {string|undefined}
+ */
+function resolveEntityPath(url, edm) {
+  if (!edm) return resolveEntitySet(url);
+  if (!url) return undefined;
+
+  const pathOnly = url.split('?')[0];
+  const segments = pathOnly
+    .split('/')
+    .filter(Boolean)
+    .map((s) => s.replace(/\(.*$/, ''))
+    .filter((s) => s && !ODATA_SYSTEM_SEGMENTS.has(s) && !s.startsWith('$'));
+
+  return resolveEntityForPath(edm, segments);
+}
+
+function nestedRowsFor(row, navName) {
+  const value = row && typeof row === 'object' ? row[navName] : undefined;
+
+  if (Array.isArray(value)) return value;
+  if (value && Array.isArray(value.results)) return value.results; // OData V2 expand shape
+  if (value && typeof value === 'object' && !('__deferred' in value)) return [value];
+
+  return [];
+}
+
+/**
+ * Walks a parsed OData response body and groups every row it contains —
+ * the top-level collection/entity plus every `$expand`'ed nested
+ * entity/collection reachable through `expandTree` — by the entity name
+ * masking rules should be looked up under. Each group's rows are the SAME
+ * object references found inside `body` (see extractResultRows), so
+ * masking a group's rows mutates the response body in place.
+ *
+ * Without an `edm`, a nested entity's name is just its nav-property name
+ * as it appears in `$expand` — good enough when cap-mcp-guard.yaml happens
+ * to key an entity by that same name, but not a real entity-set/type
+ * resolution. Pass `edm` (see lib/core/edm.js) to resolve nav properties
+ * to their real target entity instead.
+ *
+ * @param {*} body parsed JSON response body
+ * @param {string} rootEntity entity name for the top-level rows
+ * @param {object} [expandTree] see lib/core/edm.js parseExpandOption()
+ * @param {object} [edm] see lib/core/edm.js parseMetadata()
+ * @returns {{ entity: string, rows: object[] }[]}
+ */
+function collectMaskableGroups(body, rootEntity, expandTree = {}, edm) {
+  const groups = [];
+
+  function walk(rows, entityName, tree) {
+    if (rows.length) groups.push({ entity: entityName, rows });
+
+    for (const [navName, subTree] of Object.entries(tree)) {
+      const nestedEntity = edm ? resolveExpandTarget(edm, entityName, navName) : navName;
+      const nestedRows = rows.flatMap((row) => nestedRowsFor(row, navName));
+
+      walk(nestedRows, nestedEntity, subTree);
+    }
+  }
+
+  walk(extractResultRows(body), rootEntity, expandTree);
+  return groups;
+}
+
+module.exports = {
+  resolveEntitySet,
+  resolveOperation,
+  isBatchRequest,
+  extractResultRows,
+  resolveEntityPath,
+  collectMaskableGroups
+};

package/lib/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cap-mcp-guard",
-  "version": "0.1.0",
+  "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>",
@@ -22,6 +22,7 @@
   "keywords": [
     "cap",
     "sap",
+    "odata",
     "mcp",
     "ai-agent",
     "policy",