@link-foundation/sensitive-data-sanitizer 0.13.0 → 0.15.0

package/src/personal.js

@@ -29,6 +29,9 @@ const ibanLengths = Object.fromEntries(
     .map((entry) => [entry.slice(0, 2), Number(entry.slice(2))])
 );
 
+// `@handle/jane@example.com` is a mention and an address, not a package path.
+const mentionedEmail =
+  /^\/[\p{L}\p{N}_.!#$%&'*+?^`{|}~-]+@[\p{L}\p{N}][\p{L}\p{N}.-]{0,252}\.\p{L}{2,63}(?![\p{L}\p{N}_-])/u;
 export function iban(value) {
   const compact = value.replace(/\s/g, '').toUpperCase();
   if (
@@ -179,7 +182,12 @@ const russianFull =
   /(?<![\p{L}])(?:[А-ЯЁ][а-яё]{2,30}[ \t]+){2}[А-ЯЁ][а-яё]{2,30}(?:вич|вна|ична)|(?<![\p{L}])(?:[А-ЯЁ][а-яё]{2,30}[ \t]+){2}(?:оглы|кызы)(?![\p{L}])/gu;
 export function detectPersonal(text, emit) {
   detectDocumentNames(text, emit);
-  for (const pattern of [latinPairs, slavicPairs, russianFull]) {
+  for (const pattern of [
+    latinPairs,
+    slavicPairs,
+    russianFull,
+    /(?<![\p{L}])(?:[А-ЯЁ][а-яё]{2,30}[ \t]+)[А-ЯЁ][а-яё]{2,30}(?:вич|вна|ична)[ \t]+[А-ЯЁ][а-яё]{2,30}(?![\p{L}])/gu,
+  ]) {
     collectMatches(
       text,
       pattern,
@@ -202,10 +210,11 @@ export function detectPersonal(text, emit) {
   }
   collectMatches(
     text,
-    /(?:компании|организации|company|organization|société|empresa|Firma)[ \t]+([\p{Lu}][\p{L}\p{M}&'-]{1,80})/gu,
+    /(?:компании|организации|company|organization|société|empresa|Firma)[ \t]+([\p{Lu}][\p{L}\p{M}&']{0,80}(?:-[\p{L}\p{M}\p{N}&']{1,40}){0,4})/gu,
     emit,
     details('ORGANIZATION', 'organization-context', 0.7),
-    1
+    1,
+    (value) => value.length >= 2
   );
   collectMatches(
     text,
@@ -231,10 +240,12 @@ export function detectPersonal(text, emit) {
     emit,
     details('USERNAME', 'messenger-handle', 0.65),
     0,
-    (_value, match) =>
-      !/^\/[a-z0-9][a-z0-9_.-]*/i.test(
-        text.slice(match.index + match[0].length)
-      )
+    (_value, match) => {
+      const rest = text.slice(match.index + match[0].length);
+      return (
+        !/^\/[a-z0-9][a-z0-9_.-]*/i.test(rest) || mentionedEmail.test(rest)
+      );
+    }
   );
   collectMatches(
     text,

package/src/placeholder-types.js

@@ -0,0 +1,33 @@
+import { catalogTypes } from './entities.js';
+
+// Native unlabelled types supplement the shared vendor-label catalog.
+export const reservedPlaceholderTypes = () => [
+  ...catalogTypes(),
+  'ADDRESS',
+  'AU_TFN',
+  'BRAZIL_CPF_NUMBER',
+  'CREDENTIAL',
+  'CREDIT_CARD',
+  'DATE',
+  'EDUCATION',
+  'EMAIL',
+  'ENCODED_SENSITIVE',
+  'IBAN',
+  'ID',
+  'IP_ADDRESS',
+  'KR_RRN',
+  'LOCATION',
+  'MAC_ADDRESS',
+  'ORGANIZATION',
+  'PASSPORT_MRZ',
+  'PASSPORT_NUMBER',
+  'PERSON',
+  'PHONE',
+  'PL_PESEL',
+  'RU_INN',
+  'RU_SNILS',
+  'SG_NRIC_FIN',
+  'STATE',
+  'USERNAME',
+  'US_HEALTHCARE_NPI',
+];

package/src/placeholders.js

@@ -1,4 +1,6 @@
 import { failure, REDACTED, escapePattern } from './detection.js';
+import { reservedPlaceholderTypes } from './placeholder-types.js';
+import { samePersonal } from './personal-variants.js';
 import { nameAliases } from './transliteration.js';
 import { createHash } from 'node:crypto';
 import { jsonStringLiterals } from './json-string-runs.js';
@@ -105,11 +107,29 @@ function aliases(value, type) {
     ),
   ];
 }
+// A bare name is the same entity as its numbered form, including maps saved
+// when the span stopped at the hyphen of `Вектор-99`.
+function numberedOrganization(value, entry) {
+  return (entry.values ?? []).some((original) => {
+    const base = original.replace(/-\d*$/u, '');
+    return base !== original && samePersonal(value, base, entry.type);
+  });
+}
 function related(value, entry) {
+  if (
+    (entry.values ?? []).some((original) =>
+      samePersonal(value, original, entry.type)
+    )
+  ) {
+    return true;
+  }
   const candidates = aliases(value, entry.type);
   if (candidates.some((alias) => entry.aliases.includes(alias))) {
     return true;
   }
+  if (entry.type === 'ORGANIZATION') {
+    return numberedOrganization(value, entry);
+  }
   if (entry.type !== 'PERSON') {
     return false;
   }
@@ -139,7 +159,7 @@ function related(value, entry) {
   return false;
 }
 export function placeholderNameFindings(text, findings, options) {
-  if (!hasPlaceholders(options)) {
+  if (!hasPlaceholders(options) || options.knownOnly) {
     return findings;
   }
   const people = [
@@ -199,12 +219,23 @@ export function preparePlaceholderText(text, findings, options) {
   if (!state || !hasPlaceholders(options)) {
     return;
   }
-  // Reserve the entire namespace, not only the numbers about to be allocated.
-  const template = state.map.format;
+  const types = new Set([
+    ...reservedPlaceholderTypes(),
+    ...findings.map((f) =>
+      f.category === 'credential' ? 'CREDENTIAL' : f.type
+    ),
+    ...(options.knownPersonal ?? []).map((e) => e.type),
+    ...state.map.entries.map((e) => e.type),
+  ]);
+  const [before, after] = state.map.format.split('{n}');
+  const tokens = [...types].map(
+    (type) =>
+      `${escapePattern(
+        placeholderToken(type, 1, before)
+      )}[1-9][0-9]*${escapePattern(placeholderToken(type, 1, after))}`
+  );
   const pattern = new RegExp(
-    escapePattern(template)
-      .replace(/\\\{(?:Type|TYPE|type)\\\}/, '[A-Za-z][A-Za-z0-9_]*')
-      .replace('\\{n\\}', '[1-9][0-9]*'),
+    `(?<![\\p{L}\\p{M}\\p{N}_])(?:${tokens.join('|')})(?![\\p{L}\\p{M}\\p{N}_])`,
     'u'
   );
   if (namespaceCollision(text, pattern)) {
@@ -237,7 +268,7 @@ function namespaceCollision(text, pattern) {
   return false;
 }
 
-function canonicalPerson(value, people) {
+export function canonicalPerson(value, people) {
   // Resolve components only when there is a unique compatible full name.
   const matches = people.filter((person) => {
     const words = person.match(/\p{L}+/gu) ?? [];
@@ -255,6 +286,18 @@ function canonicalPerson(value, people) {
   );
   return distinct.size === 1 ? [...distinct.values()][0] : value;
 }
+function canonicalKnown(value, type, options, state) {
+  const known = (options.knownPersonal ?? []).filter(
+    (e) => e.type === type && samePersonal(value, e.value, type)
+  );
+  // `Петров Данил` and `Петров Данил Сергеевич` are one person: the fullest wins.
+  const longest = Math.max(0, ...known.map((e) => e.value.length));
+  const fullest = known.filter((e) => e.value.length === longest);
+  if (fullest.length === 1) {
+    return fullest[0].value;
+  }
+  return type === 'PERSON' ? canonicalPerson(value, state.people ?? []) : value;
+}
 export function placeholderReplacement(value, finding, transform, options) {
   if (finding.category === 'credential' && !transform.credentials) {
     return REDACTED;
@@ -270,12 +313,16 @@ export function placeholderReplacement(value, finding, transform, options) {
       : finding.type === 'DATE_OF_BIRTH'
         ? 'DATE'
         : finding.type;
-  const canonical =
-    type === 'PERSON' ? canonicalPerson(value, state.people ?? []) : value;
+  const canonical = canonicalKnown(value, type, options, state);
   const candidates = map.entries.filter(
     (entry) => entry.type === type && related(canonical, entry)
   );
-  let entry = candidates.length === 1 ? candidates[0] : undefined;
+  // Several related entities are ambiguous, unless one holds this exact value.
+  const exact = candidates.filter((entry) =>
+    entry.values.some((original) => samePersonal(canonical, original, type))
+  );
+  const matches = candidates.length === 1 ? candidates : exact;
+  let entry = matches.length === 1 ? matches[0] : undefined;
   if (!entry) {
     if (map.entries.length >= (options.maxFindings ?? 100000)) {
       throw failure('ERR_LIMIT');

package/src/projection.js

@@ -27,8 +27,12 @@ export function projectText(input) {
     !/\x1b\[|\\u[\da-fA-F]{4}|[\u200b-\u200f\u202a-\u202e\u2060-\u206f\ufeff]/u.test(
       input
     ) &&
-    input.normalize('NFKC') === input &&
-    !/[^0-9]/.test(input.replace(/[^\p{Nd}]/gu, ''))
+    // ASCII already has normalized letters and digits. Avoid constructing a
+    // second multi-megabyte string just to check its decimal characters.
+    // eslint-disable-next-line no-control-regex -- Check the ASCII range.
+    (!/[^\x00-\x7f]/.test(input) ||
+      (input.normalize('NFKC') === input &&
+        !/[^0-9]/.test(input.replace(/[^\p{Nd}]/gu, ''))))
   ) {
     return { text: input, changed: false };
   }

package/src/propagation.js

@@ -1,5 +1,6 @@
 import { personalPattern, maxPropagationLength, failure } from './detection.js';
 import { actionable } from './confidence.js';
+import { organizationCore, organizationFamily } from './personal-variants.js';
 import { nameAliases } from './transliteration.js';
 
 function mrzSeeds(value, finding, seeds) {
@@ -32,11 +33,13 @@ function decodedValue(value) {
 
 function eligibleSeed(finding, options) {
   return (
+    !options.knownOnly &&
     finding.category === 'personal' &&
     finding.type !== 'ENCODED_SENSITIVE' &&
     !['confirmed-personal', 'document-propagation'].includes(finding.rule) &&
     actionable(finding, options) &&
-    (finding.confidence >= 0.85 ||
+    ((options.documentEntities && finding.type === 'ORGANIZATION') ||
+      finding.confidence >= 0.85 ||
       [
         'PERSON',
         'PASSPORT_NUMBER',
@@ -47,6 +50,18 @@ function eligibleSeed(finding, options) {
       ].includes(finding.type))
   );
 }
+function organizationSeed(text, value, finding, seeds, options) {
+  if (options.documentEntities && finding.type === 'ORGANIZATION') {
+    const core = organizationCore(value);
+    if (core.length >= 3) {
+      seeds.set(core, finding);
+    }
+    const family = organizationFamily(core);
+    for (const match of family ? text.matchAll(family.pattern) : []) {
+      seeds.set(match[0], finding);
+    }
+  }
+}
 // Only confirmed values seed propagation. A low-score numeric coincidence
 // must never turn every log occurrence into a high-score identity.
 export function confirmedSeeds(text, findings, options) {
@@ -71,6 +86,7 @@ export function confirmedSeeds(text, findings, options) {
       mrzSeeds(value, finding, seeds);
     } else if (value.length >= 2) {
       seeds.set(value, finding);
+      organizationSeed(text, value, finding, seeds, options);
       if (finding.type === 'PERSON') {
         for (const name of value.match(/\p{L}{2,}/gu) ?? []) {
           seeds.set(name, finding);

package/src/russian-declension.js

@@ -0,0 +1,167 @@
+// Finite Russian declension shared by fake names and fake entities. Case order:
+// nominative, genitive, dative, accusative, instrumental, prepositional.
+// `|` lists a rarer spelling, accepted when reading a form, never generated.
+const fleeting = { павел: 'павл', лев: 'льв', ветер: 'ветр' };
+const hush = /[жчшщц]$/u;
+const a = (stem) => [
+  'а',
+  /[гкхжчшщ]$/u.test(stem) ? 'и' : 'ы',
+  'е',
+  'у',
+  /[жчшщц]$/u.test(stem) ? 'ей|ею' : 'ой|ою',
+  'е',
+];
+const adjectives = [
+  [
+    /[ый]й$|ой$/u,
+    2,
+    (w) => [w.slice(-2), 'ого', 'ому', w.slice(-2), 'ым', 'ом'],
+  ],
+  [/[кгхжчшщ]ий$/u, 2, () => ['ий', 'ого', 'ому', 'ий', 'им', 'ом']],
+  [/ий$/u, 2, () => ['ий', 'его', 'ему', 'ий', 'им', 'ем']],
+  [/ая$/u, 2, () => ['ая', 'ой', 'ой', 'ую', 'ой|ою', 'ой']],
+  [/яя$/u, 2, () => ['яя', 'ей', 'ей', 'юю', 'ей|ею', 'ей']],
+  [/ое$/u, 2, () => ['ое', 'ого', 'ому', 'ое', 'ым', 'ом']],
+  [/ее$/u, 2, () => ['ее', 'его', 'ему', 'ее', 'им', 'ем']],
+];
+function noun(word, sex, animate) {
+  const accusative = (genitive, nominative = '') =>
+    animate ? genitive : nominative;
+  if (fleeting[word]) {
+    const hard = ['а', 'у', accusative('а'), 'ом', 'е'];
+    return [word, ...hard.map((ending) => fleeting[word] + ending)];
+  }
+  const table = [
+    [/ия$/u, 2, ['ия', 'ии', 'ии', 'ию', 'ией|иею', 'ии']],
+    [/ье$/u, 2, ['ье', 'ья', 'ью', 'ье', 'ьем', 'ье']],
+    [/ие$/u, 2, ['ие', 'ия', 'ию', 'ие', 'ием', 'ии']],
+    [/ий$/u, 2, ['ий', 'ия', 'ию', accusative('ия', 'ий'), 'ием', 'ии']],
+    [/й$/u, 1, ['й', 'я', 'ю', accusative('я', 'й'), 'ем', 'е']],
+    [/я$/u, 1, ['я', 'и', 'е', 'ю', 'ей|ею', 'е']],
+    [/а$/u, 1, a(word.slice(0, -1))],
+    [/о$/u, 1, ['о', 'а', 'у', 'о', 'ом', 'е']],
+  ];
+  for (const [ending, remove, cases] of table) {
+    if (ending.test(word)) {
+      return cases.map((suffix) => attach(word.slice(0, -remove), suffix));
+    }
+  }
+  if (word.endsWith('ь')) {
+    const stem = word.slice(0, -1);
+    const feminine = ['ь', 'и', 'и', 'ь', 'ью', 'и'];
+    const masculine = ['ь', 'я', 'ю', accusative('я', 'ь'), 'ем', 'е'];
+    const cases =
+      sex === 'female'
+        ? feminine
+        : sex === 'male'
+          ? masculine
+          : masculine.map((suffix, i) =>
+              suffix === feminine[i] ? suffix : `${suffix}|${feminine[i]}`
+            );
+    return cases.map((suffix) => attach(stem, suffix));
+  }
+  if (!/[бвгджзклмнпрстфхцчшщ]$/u.test(word)) {
+    return Array(6).fill(word); // Indeclinable: Шевченко, Сочи.
+  }
+  return [
+    '',
+    'а',
+    'у',
+    accusative('а'),
+    hush.test(word) ? 'ем' : 'ом',
+    'е',
+  ].map((suffix) => attach(word, suffix));
+}
+const attach = (stem, suffix) =>
+  suffix
+    .split('|')
+    .map((ending) => stem + ending)
+    .join('|');
+function adjective(word) {
+  for (const [ending, remove, cases] of adjectives) {
+    if (ending.test(word)) {
+      return cases(word).map((suffix) =>
+        attach(word.slice(0, -remove), suffix)
+      );
+    }
+  }
+  return undefined;
+}
+function surname(word, sex) {
+  if (/(?:ов|ев|ёв|ин|ын)$/u.test(word)) {
+    return ['', 'а', 'у', 'а', 'ым|ом', 'е'].map((s) => attach(word, s));
+  }
+  if (/(?:ова|ева|ёва|ина|ына)$/u.test(word)) {
+    const stem = word.slice(0, -1);
+    return ['а', 'ой', 'ой', 'у', 'ой|ою', 'ой'].map((s) => attach(stem, s));
+  }
+  const forms = adjective(word);
+  if (forms) {
+    return forms;
+  }
+  return sex === 'female' && !/[ая]$/u.test(word)
+    ? Array(6).fill(word)
+    : noun(word, sex, true);
+}
+export const russianNoun = (word, options) =>
+  options.adjective && adjective(word)
+    ? adjective(word)
+    : noun(word, options.sex, options.animate);
+// `kind` is the name slot: lastName, firstName or middleName.
+export function russianNameForms(word, kind, sex) {
+  const lower = word.toLowerCase();
+  if (kind === 'lastName') {
+    return surname(lower, sex);
+  }
+  if (kind === 'middleName' && /ич$/u.test(lower)) {
+    return ['', 'а', 'у', 'а', 'ем', 'е'].map((s) => attach(lower, s));
+  }
+  return noun(lower, sex, true);
+}
+const fold = (word) => word.toLowerCase().replaceAll('ё', 'е');
+// Every case a surface can stand for, in case order.
+export function casesOf(surface, forms) {
+  const wanted = fold(surface);
+  return forms.flatMap((form, index) =>
+    fold(form).split('|').includes(wanted) ? [index] : []
+  );
+}
+export const formOf = (forms, index) => forms[index].split('|')[0];
+// Cases governed by a preposition, in order of preference. Bare forms like
+// `Ромашке` (dative or prepositional) cannot be told apart without it.
+const governed = [
+  [/^(?:в|во|на|о|об|обо|при)$/u, [5, 3]],
+  [/^(?:к|ко|по)$/u, [2]],
+  [/^(?:с|со|над|под|перед|за)$/u, [4, 1, 3]],
+  [/^(?:у|от|до|из|без|для|около|после|кроме|вокруг|против)$/u, [1]],
+];
+const lastWord = /(?<![\p{L}\p{M}\p{N}_-])(\p{L}{1,7})[ \t\u00a0]+([«“"]?)$/u;
+// `в Лютике и Ромашке`: a conjunct takes the case of the word before it.
+const conjunct =
+  /[\p{L}\p{M}-]{1,32}[»”"]?(?:,|[ \t\u00a0]+(?:и|или))[ \t\u00a0]+[«“"]?$/u;
+export function governedCases(text, start) {
+  const before = text.slice(Math.max(0, start - 64), start);
+  const conjunction = conjunct.exec(before);
+  const source = conjunction ? before.slice(0, conjunction.index) : before;
+  const match = lastWord.exec(source.slice(-12));
+  if (!match) {
+    return { cases: [] };
+  }
+  const word = match[1].toLowerCase();
+  const rule = governed.find(([pattern]) => pattern.test(word));
+  return { cases: rule?.[1] ?? [], quoted: Boolean(match[2]) };
+}
+// Intersects the candidates of each word; a word that fits no case is ignored.
+// A quoted name in the nominative stays there: в «Вектор».
+export function commonCase(candidates, context = { cases: [] }) {
+  const present = candidates.filter((cases) => cases.length);
+  const common = [0, 1, 2, 3, 4, 5].filter((index) =>
+    present.every((cases) => cases.includes(index))
+  );
+  if (context.quoted && common.includes(0)) {
+    return 0;
+  }
+  return (
+    context.cases.find((index) => common.includes(index)) ?? common[0] ?? 0
+  );
+}

package/src/russian-names.js

@@ -0,0 +1,36 @@
+import { firstNames } from './names.js';
+
+// Finite Russian name grammar shared by known-value matching and fake mode.
+const patronymic = /(?:ич|овна|евна|ична|vich|ovna|evna)$/iu;
+const surname = /(?:ов|ев|ин|ын|ский|цкий|ова|ева|ина|ына|ская|цкая)$/iu;
+const fold = (word) => word.toLowerCase().replaceAll('ё', 'е');
+const givenNames = new Set(firstNames.ru.split(' ').map(fold));
+
+export const isPatronymic = (word) => patronymic.test(word);
+export const isGivenName = (word) => givenNames.has(fold(word));
+
+// Returns word indexes by role, or undefined when the roles are not evident.
+// `Имя Отчество Фамилия` is checked first so that surnames in -ич, as in
+// `Шостакович Дмитрий Дмитриевич`, are not mistaken for patronymics.
+export function russianNameRoles(words, known = isGivenName) {
+  if (words.length === 3) {
+    if (isPatronymic(words[1])) {
+      return { given: 0, patronymic: 1, surname: 2 };
+    }
+    return isPatronymic(words[2])
+      ? { surname: 0, given: 1, patronymic: 2 }
+      : undefined;
+  }
+  if (words.length !== 2) {
+    return undefined;
+  }
+  if (isPatronymic(words[1])) {
+    return { given: 0, patronymic: 1 };
+  }
+  const candidates = [0, 1].filter(
+    (i) => surname.test(words[i]) && !known(words[i])
+  );
+  return candidates.length === 1
+    ? { surname: candidates[0], given: 1 - candidates[0] }
+    : undefined;
+}

package/src/sanitizer.js

@@ -1,4 +1,5 @@
 import { generatedValues } from './fake.js';
+import { prepareFakeText } from './fake-entities.js';
 import { alignEscapes } from './escape-spans.js';
 import { actionable } from './confidence.js';
 import { propagate, confirmationOptions } from './propagation.js';
@@ -45,6 +46,7 @@ const publicTypes = new Set([
 ]);
 const optionNames = new Set([
   'credentialsOnly',
+  'knownOnly',
   'knownSecrets',
   'knownPersonal',
   'confirmedPersonal',
@@ -166,6 +168,7 @@ export function validateOptions(options = {}) {
   for (const key of [
     'paranoid',
     'credentialsOnly',
+    'knownOnly',
     'decode',
     'secretlint',
     'publicKnowledge',
@@ -690,11 +693,12 @@ export function redactResult(
 ) {
   options = applyProfile(options);
   const spans = validatedSpans(text, findings, options);
-  options = initializePlaceholders(options);
+  options = prepareFakeText(text, findings, initializePlaceholders(options));
   preparePlaceholderText(text, findings, options);
   const parts = [];
   const faked = [];
   const occurrences = [];
+  let irreversibleRedactions = 0;
   let outputLength = 0;
   let cursor = 0;
   for (const span of spans) {
@@ -716,6 +720,11 @@ export function redactResult(
     const transform =
       options.transformations?.[span.type] ?? options.transformation;
     if (retainedReplacement(transform, 'placeholder', span, replacement)) {
+      // `Organization-1` followed by `99` would read as a token that does not
+      // exist, so a span that ends there fails the run instead.
+      if (/\d$/.test(replacement) && /\d/.test(text[span.end] ?? '')) {
+        throw failure('ERR_RESIDUAL');
+      }
       occurrences.push({
         start: outputLength,
         end: outputLength + replacement.length,
@@ -723,6 +732,12 @@ export function redactResult(
         raw: text.slice(span.start, span.end),
       });
     }
+    if (
+      hasPlaceholders(options) &&
+      !retainedReplacement(transform, 'placeholder', span, replacement)
+    ) {
+      irreversibleRedactions++;
+    }
     outputLength += replacement.length;
     if (retainedReplacement(transform, 'fake', span, replacement)) {
       faked.push(span);
@@ -731,7 +746,11 @@ export function redactResult(
   }
   parts.push(text.slice(cursor));
   const result = finishPlaceholders(
-    { text: parts.join(''), redactions: spans.length },
+    {
+      text: parts.join(''),
+      redactions: spans.length,
+      ...(hasPlaceholders(options) ? { irreversibleRedactions } : {}),
+    },
     occurrences,
     options
   );
@@ -861,6 +880,13 @@ export function redactAgain(result, findings, options, round, rerun) {
   const merge = (next) => ({
     ...next,
     redactions: result.redactions + next.redactions,
+    ...(hasPlaceholders(options)
+      ? {
+          irreversibleRedactions:
+            (result.irreversibleRedactions ?? 0) +
+            (next.irreversibleRedactions ?? 0),
+        }
+      : {}),
     findings: auditFaked(findings, options, result),
   });
   const next = rerun({ ...options, findings: [] }, round + 1);

package/src/transforms.js

@@ -41,6 +41,22 @@ export function validateTransforms(options) {
 function positiveInteger(value) {
   return Number.isSafeInteger(value) && value > 0;
 }
+const poolTypes = new Set(['ORGANIZATION', 'LOCATION', 'EDUCATION']);
+function validPools(pools) {
+  return (
+    pools === undefined ||
+    (Boolean(pools) &&
+      typeof pools === 'object' &&
+      !Array.isArray(pools) &&
+      Object.entries(pools).every(
+        ([type, names]) =>
+          poolTypes.has(type) &&
+          Array.isArray(names) &&
+          names.length > 0 &&
+          names.every((name) => typeof name === 'string' && name.trim())
+      ))
+  );
+}
 function validateTransform(transform) {
   if (!transform || !modes.has(transform.mode)) {
     throw failure('ERR_CONFIG');
@@ -54,7 +70,8 @@ function validateTransform(transform) {
       Buffer.byteLength(transform.key) >= 16 &&
       (transform.credentials === undefined ||
         typeof transform.credentials === 'boolean') &&
-      (transform.mrzCountry === undefined || transform.mrzCountry === 'UTO'),
+      (transform.mrzCountry === undefined || transform.mrzCountry === 'UTO') &&
+      validPools(transform.pools),
     pseudonym: () =>
       typeof transform.key === 'string' &&
       Buffer.byteLength(transform.key) >= 16,
@@ -130,7 +147,7 @@ function masked(value, finding, transform) {
     ? REDACTED
     : `${chars.slice(0, start).join('')}${transform.marker ?? '*'.repeat(chars.length - start - end)}${end ? chars.slice(-end).join('') : ''}`;
 }
-function transformed(value, finding, transform) {
+function transformed(value, finding, transform, options) {
   if (!transform || transform.mode === 'redact') {
     return REDACTED;
   }
@@ -141,7 +158,7 @@ function transformed(value, finding, transform) {
       : REDACTED;
   }
   if (transform.mode === 'fake') {
-    return realisticFake(value, finding, transform);
+    return realisticFake(value, finding, transform, options);
   }
   if (finding.category === 'credential') {
     return REDACTED;
@@ -198,6 +215,6 @@ function renderValue(text, finding, transform, options) {
   const result =
     transform?.mode === 'placeholder'
       ? placeholderReplacement(raw, finding, transform, options)
-      : transformed(raw, finding, transform);
+      : transformed(raw, finding, transform, options);
   return jsonQuoted ? JSON.stringify(result).slice(1, -1) : result;
 }