cap-mcp-guard 0.2.0 → 0.3.1

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,91 @@ 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);
+      }
+    }
+  });
+}
+
+/**
+ * Finds the association/composition elements on a CAP entity definition, along with the
+ * (already service-qualified) entity name each one targets — e.g. for `Employees.department`,
+ * `{ name: 'department', targetEntity: 'CatalogService.Departments' }`. That target name is
+ * exactly what a request against `Departments` directly would resolve via resolveEntity(),
+ * so the same `policyDefinition.entities` keys apply to nested rows without any separate
+ * EDM/$metadata resolution — CAP's own compiled model already carries it.
+ *
+ * @param {object} target req.target — a linked CSN entity definition, or undefined
+ * @returns {{name: string, targetEntity: string}[]}
+ */
+function findAssociationElements(target) {
+  if (!target || !target.elements) return [];
+
+  return Object.entries(target.elements)
+    .filter(([, el]) => el && (el.type === 'cds.Association' || el.type === 'cds.Composition'))
+    .map(([name, el]) => ({
+      name,
+      targetEntity: (el._target && el._target.name) || el.target
+    }))
+    .filter((assoc) => assoc.targetEntity);
+}
+
+/**
+ * Applies each expanded association's own policy (mask/pseudonymize) to the nested
+ * row(s) hanging off of it — one level deep, matching what `$expand` actually returns.
+ * Mutates `results` in place, same convention as applyMask()/applyPseudonymize(). A no-op
+ * when the request's entity has no associations, or none of them were expanded (the nav
+ * property is simply absent from the row), or the target entity has no policy configured.
+ *
+ * @param {object|object[]} results
+ * @param {object} target req.target — see findAssociationElements()
+ * @param {object} policyDefinition see lib/policy/config.js
+ * @param {string} [pseudonymSecret] forwarded to applyPseudonymize() for nested fields
+ */
+function applyNestedPolicy(results, target, policyDefinition, pseudonymSecret) {
+  const associations = findAssociationElements(target);
+  if (!associations.length) return;
+
+  const rows = Array.isArray(results) ? results : [results];
+
+  for (const row of rows) {
+    if (!row || typeof row !== 'object') continue;
+
+    for (const { name, targetEntity } of associations) {
+      const navValue = row[name];
+      if (navValue === undefined || navValue === null) continue;
+
+      const entityConfig = policyDefinition.entities[targetEntity];
+      if (!entityConfig) continue;
+
+      if (entityConfig.mask && entityConfig.mask.length > 0) {
+        applyMask(navValue, entityConfig.mask);
+      }
+      if (entityConfig.pseudonymize && entityConfig.pseudonymize.length > 0) {
+        applyPseudonymize(navValue, entityConfig.pseudonymize, pseudonymSecret);
+      }
+    }
+  }
+}
+
 /**
  * Attaches request interception to a CAP service instance, producing a
  * guard context (see context.js) for every request that passes through it.
@@ -98,18 +184,58 @@ 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 } : {};
 
+  function buildRequestContext(req, extra) {
+    return buildContext(
+      {
+        ...extractAgentInfo(req),
+        ...extractTraceContext(req),
+        entity: resolveEntity(req),
+        operation: resolveOperation(req),
+        tenant: req.tenant,
+        user: req.user && req.user.id,
+        session: req.id,
+        ...extra
+      },
+      clockDeps
+    );
+  }
+
   srv.before('*', (req) => {
     if (!req) return;
     req._mcpGuardStartedAt = process.hrtime.bigint();
+
+    if (!policyDefinition) return;
+
+    // allowTools is a gate, not a masking rule — it has to be enforced before the
+    // query runs, not after. rowCount/durationMs aren't known yet, but `allowed`
+    // never depends on either, so this decision is already final.
+    const context = buildRequestContext(req, {});
+    const decision = evaluate(context, policyDefinition);
+
+    if (decision.mode === 'enforce' && !decision.allowed) {
+      // req.reject() throws in real CAP requests, so srv.after('*') below never runs
+      // for a denied request — report it here instead, or the denial would never be
+      // audited/traced at all.
+      if (typeof onContext === 'function') onContext(context, req);
+      if (typeof onDecision === 'function') onDecision(decision, context, req);
+
+      if (typeof req.reject === 'function') {
+        req.reject(403, decision.reason);
+      } else {
+        throw new Error(decision.reason);
+      }
+    }
   });
 
   srv.after('*', (results, req) => {
@@ -120,20 +246,7 @@ function attachInterceptor(srv, options = {}) {
       ? undefined
       : Number(process.hrtime.bigint() - startedAt) / 1e6;
 
-    const context = buildContext(
-      {
-        ...extractAgentInfo(req),
-        ...extractTraceContext(req),
-        entity: resolveEntity(req),
-        operation: resolveOperation(req),
-        tenant: req.tenant,
-        user: req.user && req.user.id,
-        session: req.id,
-        rowCount: resolveRowCount(results),
-        durationMs
-      },
-      clockDeps
-    );
+    const context = buildRequestContext(req, { rowCount: resolveRowCount(results), durationMs });
 
     if (typeof onContext === 'function') {
       onContext(context, req);
@@ -146,6 +259,18 @@ function attachInterceptor(srv, options = {}) {
         applyMask(results, decision.fieldsToMask);
       }
 
+      if (decision.mode === 'enforce' && decision.fieldsToPseudonymize.length > 0) {
+        applyPseudonymize(results, decision.fieldsToPseudonymize, pseudonymSecret);
+      }
+
+      if (decision.mode === 'enforce' && decision.rowLimitExceeded && Array.isArray(results)) {
+        results.length = decision.maxRows;
+      }
+
+      if (decision.mode === 'enforce') {
+        applyNestedPolicy(results, req.target, policyDefinition, pseudonymSecret);
+      }
+
       if (typeof onDecision === 'function') {
         onDecision(decision, context, req);
       }

package/lib/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,191 @@
-'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;
+}
+
+/**
+ * Validates the optional top-level `"audit"` key — the same shape
+ * lib/audit/log.js's writeAuditEntry() options take (`{ stdout, filePath }`).
+ * Exposing it in package.json is what lets audit-log persistence be turned on
+ * through config alone, without hand-writing a registerCapMcpGuard() call
+ * (see lib/adapters/cap.js, which forwards this to onDecision's audit option).
+ */
+function validateAuditConfig(raw) {
+  if (raw === undefined) return undefined;
+
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    throw new Error(`"audit" must be a mapping, got ${typeOf(raw)}`);
+  }
+
+  const { filePath, stdout } = raw;
+  if (filePath !== undefined && typeof filePath !== 'string') {
+    throw new Error(`"audit.filePath" must be a string, got ${typeOf(filePath)}`);
+  }
+  if (stdout !== undefined && typeof stdout !== 'boolean') {
+    throw new Error(`"audit.stdout" must be a boolean, got ${typeOf(stdout)}`);
+  }
+
+  return { ...(filePath !== undefined && { filePath }), ...(stdout !== undefined && { stdout }) };
+}
+
+function validatePseudonymizeEntry(entityName, entry) {
+  if (typeof entry === 'string') {
+    return { field: entry, type: 'opaque' };
+  }
+
+  if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
+    const { field, type = 'opaque' } = entry;
+
+    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), audit: (object|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)}`);
+  }
+
+  const audit = validateAuditConfig(raw.audit);
+
+  return { mode: raw.mode, entities, services: raw.services, users: raw.users, audit };
+}
+
+/**
+ * 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), audit: (object|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 };