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

package/src/fake-entities.js

@@ -0,0 +1,304 @@
+import { createHmac } from 'node:crypto';
+import { fakeName, fakeWord, wordProfile } from './fake-names.js';
+import { canonicalPerson } from './placeholders.js';
+import {
+  isGivenName,
+  isPatronymic,
+  russianNameRoles,
+} from './russian-names.js';
+import {
+  casesOf,
+  commonCase,
+  formOf,
+  governedCases,
+  russianNameForms,
+  russianNoun,
+} from './russian-declension.js';
+import {
+  organizationCore,
+  samePersonal,
+  wordPattern,
+} from './personal-variants.js';
+
+// Fictional but ordinary names. The lists are finite on purpose; callers can
+// replace them with `transformation.pools`.
+const vocabulary = {
+  ORGANIZATION: {
+    ru: 'Северный ветер|Альфа-Строй|Бета-Сервис|Гамма-Трейд|Меридиан|Горизонт|Гранит|Рассвет|Прогресс|Импульс|Орион|Азимут|Кристалл|Арсенал|Квант|Заря|Радуга|Волна|Орбита|Вершина|Искра|Тихая гавань|Новый горизонт|Белый парус|Золотой колос|Синяя птица',
+    latin:
+      'Northwind Trading|Bluebird Logistics|Silver Birch Partners|Harbor Lane Studio|Summit Ridge Supply|Clearwater Works|Redwood Systems|Maple Street Foods',
+  },
+  LOCATION: {
+    ru: 'Зареченск|Приморск|Светлогорск|Лесногорск|Березовка|Сосновка|Каменка|Покровка|Ольховка|Заречье|Краснополье',
+    latin: 'Riverton|Oakdale|Fairview|Lakewood|Brookfield|Greenville|Ashford',
+  },
+  EDUCATION: {
+    ru: 'Северный государственный университет|Приморский технический институт|Лесногорский гуманитарный университет|Зареченский экономический колледж|Светлогорская городская школа',
+    latin:
+      'Riverside University|Lakeview College|Oakdale Institute of Technology|Fairview State University',
+  },
+};
+const cyrillic = /\p{Script=Cyrillic}/u;
+const surfacesKey = Symbol('fakeSurfaces');
+const textKey = Symbol('fakeText');
+const surfaceLimit = 1000;
+
+// Lets each span see the other mentions of its document, as placeholders do.
+export function prepareFakeText(text, findings, options) {
+  const surfaces = new Map();
+  for (const finding of findings) {
+    if (
+      ['PERSON', 'ORGANIZATION', 'LOCATION', 'EDUCATION'].includes(finding.type)
+    ) {
+      const values = surfaces.get(finding.type) ?? new Set();
+      if (values.size < surfaceLimit) {
+        values.add(text.slice(finding.start, finding.end));
+      }
+      surfaces.set(finding.type, values);
+    }
+  }
+  return { ...options, [surfacesKey]: surfaces, [textKey]: text };
+}
+const wordCount = (value) => value.trim().split(/\s+/u).length;
+// The fullest form this mention belongs to, or the mention itself.
+function entityLemma(value, type, options) {
+  const known = [
+    ...(options.knownPersonal ?? []),
+    ...(options.confirmedPersonal ?? []),
+  ]
+    .filter((entry) => entry.type === type)
+    .map((entry) => entry.value);
+  const mentions = [...(options[surfacesKey]?.get(type) ?? [])];
+  for (const group of [known, mentions]) {
+    const matches = group.filter((other) => samePersonal(value, other, type));
+    const longest = Math.max(0, ...matches.map(wordCount));
+    const fullest = [
+      ...new Set(matches.filter((other) => wordCount(other) === longest)),
+    ];
+    // `Гранит` covers its own form `Граните`, so several forms share one lemma.
+    const lemma = fullest.filter((other) =>
+      fullest.every((form) => samePersonal(form, other, type))
+    );
+    if (lemma.length === 1) {
+      return lemma[0];
+    }
+  }
+  return type === 'PERSON' ? canonicalPerson(value, mentions) : value;
+}
+
+const applyStyle = (surface, output) =>
+  surface.length > 1 && surface === surface.toUpperCase()
+    ? output.toUpperCase()
+    : surface === surface.toLowerCase()
+      ? output.toLowerCase()
+      : output;
+const capitalize = (word) =>
+  word[0].toUpperCase() + word.slice(1).toLowerCase();
+function nameSlots(parts) {
+  const roles = russianNameRoles(parts);
+  if (roles) {
+    return parts.map((_part, i) =>
+      i === roles.surname
+        ? 'lastName'
+        : i === roles.patronymic
+          ? 'middleName'
+          : 'firstName'
+    );
+  }
+  if (parts.length === 1) {
+    return [wordProfile(parts[0]).role];
+  }
+  const given = parts.map((part) => isGivenName(part));
+  if (parts.length === 2 && given[0] !== given[1]) {
+    return given.map((isGiven) => (isGiven ? 'firstName' : 'lastName'));
+  }
+  return parts.map((_part, i) =>
+    i === 0 ? 'firstName' : i === parts.length - 1 ? 'lastName' : 'middleName'
+  );
+}
+function nameSex(parts, slots) {
+  const at = (slot) => parts[slots.indexOf(slot)];
+  const middle = at('middleName');
+  if (middle && (isPatronymic(middle) || /(?:вна|чна)$/iu.test(middle))) {
+    return /(?:вна|чна)$/iu.test(middle) ? 'female' : 'male';
+  }
+  const last = at('lastName');
+  if (last && /(?:ова|ева|ёва|ина|ына|ая|яя)$/iu.test(last)) {
+    return 'female';
+  }
+  if (last && /(?:ов|ев|ёв|ин|ын|ий|ой|ый)$/iu.test(last)) {
+    return 'male';
+  }
+  return wordProfile(at('firstName') ?? parts[0]).sex;
+}
+const letters = /[\p{L}\p{M}]+/gu;
+// One identity per lemma: each lemma word has one seeded fake, and the matched
+// surface only decides its case, its order and its letter case.
+function russianFakeName(surface, lemma, key, context) {
+  const parts = lemma.trim().split(/\s+/u);
+  const slots = nameSlots(parts);
+  const sex = nameSex(parts, slots);
+  const lemmaWords = parts.flatMap((part, i) =>
+    part.match(letters).map((word) => {
+      const slot = slots[i];
+      return {
+        slot,
+        lemmaForms: russianNameForms(word, slot, sex),
+        pattern: new RegExp(`^(?:${wordPattern(word, 'PERSON')})$`, 'iu'),
+        first: word[0].toLowerCase().replace('ё', 'е'),
+        fake: fakeWord(capitalize(word), key, slot, undefined, sex),
+      };
+    })
+  );
+  const matched = surface.match(letters).map((word) => {
+    const initial = word.length === 1;
+    const entry = lemmaWords.find(
+      (candidate) =>
+        !candidate.used &&
+        (initial
+          ? candidate.slot !== 'lastName' &&
+            candidate.first === word.toLowerCase().replace('ё', 'е')
+          : candidate.pattern.test(word))
+    );
+    if (entry) {
+      entry.used = true;
+    }
+    return { word, entry, initial };
+  });
+  const index = commonCase(
+    matched
+      .filter(({ entry, initial }) => entry && !initial)
+      .map(({ word, entry }) => casesOf(word, entry.lemmaForms)),
+    context
+  );
+  let position = 0;
+  return surface.replace(letters, () => {
+    const { word, entry, initial } = matched[position++];
+    if (!entry) {
+      return fakeWord(word, key);
+    }
+    if (initial) {
+      return entry.fake[0].toUpperCase();
+    }
+    const forms = russianNameForms(entry.fake, entry.slot, sex);
+    return applyStyle(word, capitalize(formOf(forms, index)));
+  });
+}
+const contextOf = (finding, options) =>
+  governedCases(options[textKey] ?? '', finding.start);
+export function fakePerson(value, finding, transform, options) {
+  const lemma = entityLemma(value, 'PERSON', options);
+  return cyrillic.test(lemma) &&
+    cyrillic.test(value) &&
+    !/\p{Script=Latin}/u.test(`${lemma}${value}`)
+    ? russianFakeName(value, lemma, transform.key, contextOf(finding, options))
+    : fakeName(value, transform.key);
+}
+
+const assigned = new WeakMap();
+const lemmaKey = (core) => core.toLowerCase().replaceAll('ё', 'е');
+const poolFor = (type, core, transform) =>
+  transform.pools?.[type] ??
+  vocabulary[type][cyrillic.test(core) ? 'ru' : 'latin'].split('|');
+function isReal(candidate, type, options) {
+  return [
+    ...(options.knownPersonal ?? []),
+    ...(options.confirmedPersonal ?? []),
+    ...[...(options[surfacesKey]?.get(type) ?? [])].map((value) => ({
+      type,
+      value,
+    })),
+  ].some(
+    (entry) => entry.type === type && samePersonal(candidate, entry.value, type)
+  );
+}
+// A deterministic start, then the next free name so that two entities of one
+// run never share a fake. An exhausted list continues with numbered names.
+function assignFake(core, type, transform, options) {
+  let state = assigned.get(transform);
+  if (!state) {
+    state = new Map();
+    assigned.set(transform, state);
+  }
+  const entityKey = `${type}\0${lemmaKey(core)}`;
+  if (state.has(entityKey)) {
+    return state.get(entityKey);
+  }
+  const taken = new Set(state.values());
+  const pool = poolFor(type, core, transform);
+  const start = createHmac('sha256', transform.key)
+    .update(`entity\0${entityKey}`)
+    .digest()
+    .readUInt32BE(0);
+  for (let attempt = 0; ; attempt++) {
+    const name = pool[(start + attempt) % pool.length];
+    const round = Math.floor(attempt / pool.length);
+    const candidate = round ? `${name}-${round + 1}` : name;
+    if (!taken.has(candidate) && !isReal(candidate, type, options)) {
+      state.set(entityKey, candidate);
+      return candidate;
+    }
+  }
+}
+const nounOptions = (word, phrase, position) => ({
+  animate: false,
+  sex: phrase.some((other) => /[ая]я$/u.test(other)) ? 'female' : undefined,
+  adjective:
+    !word.includes('-') &&
+    (/(?:ый|ая|яя)$/u.test(word) ||
+      (/(?:ий|ой|ое|ее)$/u.test(word) && position < phrase.length - 1)),
+});
+// Only the last part of a hyphenated name declines: в Альфа-Строе.
+const phraseForms = (phrase) => {
+  const words = phrase.toLowerCase().split(/\s+/u);
+  return words.map((word, position) => {
+    const head = word.slice(0, word.lastIndexOf('-') + 1);
+    const tail = word.slice(head.length);
+    return {
+      head,
+      forms: russianNoun(tail, nounOptions(word, words, position)),
+    };
+  });
+};
+function phraseCase(surface, lemma, context) {
+  const words = surface.split(/\s+/u);
+  const lemmaForms = phraseForms(lemma);
+  if (words.length !== lemmaForms.length) {
+    return 0;
+  }
+  return commonCase(
+    words.map((word, i) =>
+      casesOf(word.slice(word.lastIndexOf('-') + 1), lemmaForms[i].forms)
+    ),
+    context
+  );
+}
+function declinedPhrase(phrase, index) {
+  if (!cyrillic.test(phrase)) {
+    return phrase;
+  }
+  const original = phrase.split(/\s+/u);
+  return phraseForms(phrase)
+    .map(({ head, forms }, i) => {
+      const word = head + formOf(forms, index);
+      return original[i][0] === original[i][0].toUpperCase()
+        ? word.replace(
+            /(^|-)(\p{L})/gu,
+            (_m, gap, letter) => `${gap}${letter.toUpperCase()}`
+          )
+        : word;
+    })
+    .join(' ');
+}
+const decoration = /^((?:(?:ООО|АО|ПАО|ИП|ЗАО)[ \t]+)?[«“"]?)(.*?)([»”"]?)$/su;
+// `ООО «Ромашка»` keeps its legal form and quotes; only the name is replaced.
+export function fakeEntity(value, finding, transform, options) {
+  const { type } = finding;
+  const [, before, core, after] = decoration.exec(value);
+  const lemma = organizationCore(entityLemma(value, type, options));
+  const fake = assignFake(lemma, type, transform, options);
+  const output = cyrillic.test(core)
+    ? declinedPhrase(fake, phraseCase(core, lemma, contextOf(finding, options)))
+    : fake;
+  return `${before}${applyStyle(core, output)}${after}`;
+}

package/src/fake-names.js

@@ -146,6 +146,58 @@ function scriptLocale(value) {
 }
 export function fakeName(value, key) {
   indexNames();
+  const words = value.match(/[\p{L}\p{M}]+/gu) ?? [];
+  const roles = new Map();
+  let nameSex;
+  if (
+    /\p{Script=Cyrillic}/u.test(value) &&
+    words.length >= 2 &&
+    words.length <= 3
+  ) {
+    const middle = words.findIndex((w) =>
+      /(?:ович|евич|ична|овна|евна)$/iu.test(w)
+    );
+    const surname = words.findIndex(
+      (w, i) =>
+        i !== middle &&
+        /(?:ов|ев|ин|ский|ова|ева|ина|ская)$/iu.test(w) &&
+        !given.has(latinName(w))
+    );
+    const genderWord = words[middle >= 0 ? middle : surname];
+    if (genderWord) {
+      nameSex = /(?:ова|ева|ина|ская|овна|евна|ична)$/iu.test(genderWord)
+        ? 'female'
+        : 'male';
+    }
+    if (middle > 0) {
+      words.forEach((w, i) =>
+        roles.set(
+          w,
+          i === middle
+            ? 'middleName'
+            : i === middle - 1
+              ? 'firstName'
+              : 'lastName'
+        )
+      );
+    } else if (surname >= 0) {
+      words.forEach((w, i) =>
+        roles.set(w, i === surname ? 'lastName' : 'firstName')
+      );
+    } else {
+      // Ambiguous spans receive a complete name with the same token count.
+      words.forEach((w, i) =>
+        roles.set(
+          w,
+          i === 0
+            ? 'firstName'
+            : i === words.length - 1
+              ? 'lastName'
+              : 'middleName'
+        )
+      );
+    }
+  }
   return value.replace(/[\p{L}\p{M}]+/gu, (word) => {
     for (const locale of ['ja', 'zh', 'ko']) {
       const family = firstNames[locale]
@@ -158,10 +210,11 @@ export function fakeName(value, key) {
         );
       }
     }
-    return fakeWord(word, key);
+    return fakeWord(word, key, roles.get(word), undefined, nameSex);
   });
 }
-function wordProfile(word, forcedRole, forcedLocale) {
+export function wordProfile(word, forcedRole, forcedLocale) {
+  indexNames();
   const canonical = latinName(word);
   const patronymic = /(?:vich|vna|ichna|ogly|kyzy)$/.test(canonical);
   const slavic = /(?:ova|eva|ov|ev|in|ina|enko|sky|ski|skaya)$/.test(canonical);
@@ -188,12 +241,14 @@ function wordProfile(word, forcedRole, forcedLocale) {
         : 'lastName');
   return { canonical, locale, sex, role };
 }
-function fakeWord(word, key, forcedRole, forcedLocale) {
-  const { canonical, locale, sex, role } = wordProfile(
-    word,
-    forcedRole,
-    forcedLocale
-  );
+export function fakeWord(word, key, forcedRole, forcedLocale, forcedSex) {
+  const {
+    canonical,
+    locale,
+    sex: detectedSex,
+    role,
+  } = wordProfile(word, forcedRole, forcedLocale);
+  const sex = forcedSex ?? detectedSex;
   const faker = new Faker({ locale: [locales[locale] ?? en, en] });
   faker.seed(
     createHmac('sha256', key)

package/src/fake.js

@@ -1,3 +1,4 @@
+import { fakeEntity, fakePerson } from './fake-entities.js';
 import { createHmac } from 'node:crypto';
 import { parsePhoneNumberFromString } from 'libphonenumber-js/max';
 import { mrzCheck } from './identity.js';
@@ -487,7 +488,7 @@ function fakeTd1(parts, transform) {
     .padEnd(30, '<');
   return parts.join('');
 }
-export function realisticFake(value, finding, transform) {
+export function realisticFake(value, finding, transform, options = {}) {
   let output;
   if (finding.category === 'credential') {
     if (!transform.credentials) {
@@ -500,14 +501,9 @@ export function realisticFake(value, finding, transform) {
       .toString('hex')
       .slice(0, 8)}!`;
   } else if (finding.type === 'PERSON') {
-    output = fakeName(value, transform.key);
+    output = fakePerson(value, finding, transform, options);
   } else if (['ORGANIZATION', 'EDUCATION', 'LOCATION'].includes(finding.type)) {
-    const label = {
-      ORGANIZATION: 'Organization',
-      EDUCATION: 'School',
-      LOCATION: 'Location',
-    }[finding.type];
-    output = `Example ${label} ${digest(value, transform.key, finding.type).readUInt32BE(0)}`;
+    output = fakeEntity(value, finding, transform, options);
   } else if (/DATE|BIRTH/.test(finding.type)) {
     output = fakeDate(value, transform.key);
   } else if (finding.type === 'PASSPORT_MRZ') {

package/src/index.d.ts

@@ -42,6 +42,8 @@ export interface Detector {
 export interface SanitizerOptions {
   /** Preserve all personal/account data; credential findings still redact. */
   credentialsOnly?: boolean;
+  /** Replace only knownPersonal/knownSecrets and reused map values; skip automatic detectors. */
+  knownOnly?: boolean;
   profile?: 'publication' | 'documents';
   /** Opt in to bounded employer, school, city/region heuristics. */
   documentEntities?: boolean;
@@ -97,6 +99,8 @@ export interface SanitizedText {
   findings: Finding[];
   /** Number of disjoint replacements after overlapping detections are merged. */
   redactions: number;
+  /** Placeholder-mode replacements absent from the restore map (e.g. credentials). */
+  irreversibleRedactions?: number;
   /** Private personal data. Absent for map:false and non-placeholder modes. */
   map?: RestoreMap;
 }
@@ -246,6 +250,10 @@ export type Transformation =
       credentials?: boolean;
       /** Keep original MRZ issuer/nationality unless Utopia is requested. */
       mrzCountry?: 'UTO';
+      /** Caller-reviewed names that replace the generated entity vocabulary. */
+      pools?: Partial<
+        Record<'ORGANIZATION' | 'LOCATION' | 'EDUCATION', string[]>
+      >;
     }
   | { mode: 'date-shift'; days: number }
   | { mode: 'bucket'; size: number };

package/src/keywords.js

@@ -27,10 +27,27 @@ export function keywordMatcher(words) {
       queue.push(child);
     }
   }
+  // At the root, characters that cannot start any keyword need no state
+  // transitions. A native search skips large padding runs without Map work
+  // per character. Escape UTF-16 units so metacharacters retain literal meaning.
+  const starters = new RegExp(
+    `[${[...nodes[0].next.keys()]
+      .map((char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`)
+      .join('')}]`,
+    'g'
+  );
   return (text) => {
     const found = new Set();
     let state = 0;
     for (let i = 0; i < text.length; i++) {
+      if (!state && !nodes[0].output.length && !nodes[0].next.has(text[i])) {
+        starters.lastIndex = i + 1;
+        const next = starters.exec(text);
+        if (!next) {
+          break;
+        }
+        i = next.index;
+      }
       const char = text[i];
       while (state && !nodes[state].next.has(char)) {
         state = nodes[state].fail;

package/src/names.js

@@ -12,7 +12,7 @@ export const firstNames = {
   jaLatn: 'Yamada Sato Suzuki Takahashi Tanaka Ito Watanabe Nakamura Kobayashi',
   zhLatn:
     'Zhang Wang Li Zhao Liu Chen Yang Huang Zhou Wu Xu Sun Hu Zhu Gao Lin',
-  ru: 'Иван Пётр Петр Сергей Александр Алексей Дмитрий Михаил Николай Андрей Владимир Павел Виктор Олег Борис Евгений Василий Юрий Марина Анна Мария Елена Ольга Наталья Ирина Светлана Татьяна Екатерина Анастасия Юлия Ивану Ивана Иваном Сергея Сергею Александра Александру Анне Анну Елены',
+  ru: 'Данил Максим Алина Иван Пётр Петр Сергей Александр Алексей Дмитрий Михаил Николай Андрей Владимир Павел Виктор Олег Борис Евгений Василий Юрий Марина Анна Мария Елена Ольга Наталья Ирина Светлана Татьяна Екатерина Анастасия Юлия Ивану Ивана Иваном Сергея Сергею Александра Александру Анне Анну Елены',
   ja: '山田 佐藤 鈴木 高橋 田中 伊藤 渡辺 渡邊 中村 小林 加藤 吉田 松本 山本 井上 木村 林 清水 斎藤 斉藤',
   zh: '张 王 李 赵 刘 陈 杨 黄 周 吴 徐 孙 胡 朱 高 林 何 郭 马 罗 張 趙 劉 陳 楊 黃 吳 孫 馬 羅',
   ko: '김 이 박 최 정 강 조 윤 장 임 한 오 서 신 권 황 안 송 전 홍 유 고 문 양 손 배 백',

package/src/personal-context.js

@@ -2,7 +2,7 @@ import { collectMatches } from './detection.js';
 
 const birth =
   /(?<![\p{L}\p{N}_])(?:born|birth[ _-]?date|date[ _-]of[ _-]birth|DOB|дата рождения|д\.р\.|родился|родилась|Geburtsdatum|fecha de nacimiento|date de naissance)(?![\p{L}\p{N}_])/giu;
-const months =
+export const months =
   'January February March April May June July August September October November December Jan Feb Mar Apr Jun Jul Aug Sep Sept Oct Nov Dec января февраля марта апреля мая июня июля августа сентября октября ноября декабря январь февраль март апрель май июнь июль август сентябрь октябрь ноябрь декабрь'
     .split(' ')
     .join('|');

package/src/personal-variants.js

@@ -0,0 +1,184 @@
+import { escapePattern, failure } from './detection.js';
+import { russianNameRoles } from './russian-names.js';
+
+const boundary = '[\\p{L}\\p{M}\\p{N}_]';
+export function organizationCore(value) {
+  return value
+    .replace(/^(?:ООО|АО|ПАО|ИП|ЗАО)[ \t]+/u, '')
+    .replace(/^[«“"]|[»”"]$/gu, '')
+    .trim();
+}
+// `Вектор-1` also identifies its base name and numbered siblings like `Вектор-2`.
+export function organizationFamily(core) {
+  const base = /^(.{3,})-\d{1,9}$/u.exec(core)?.[1];
+  return base
+    ? {
+        base,
+        pattern: new RegExp(
+          `(?<!${boundary})${escapePattern(base)}(?:-\\d{1,9})?(?!${boundary}|-\\d)`,
+          'giu'
+        ),
+      }
+    : undefined;
+}
+// ё and е are one letter in ordinary Russian writing; the i flag covers Ё and Е.
+const foldYo = (pattern) => pattern.replace(/[еёЕЁ]/gu, '[её]');
+const fleeting = { павел: 'Павл', лев: 'Льв' };
+const hardCases = '(?:а|у|ом|е)';
+// Only caller-confirmed Russian words receive finite case alternatives. A
+// minimum three-letter stem avoids turning short names into broad matches.
+function cyrillicPattern(word, type) {
+  const endings = [
+    [/(?:ова|ева|ина)$/u, 1, '(?:а|ой|ою|у|е|ы)'],
+    [/(?:ая)$/u, 2, '(?:ая|ой|ою|ую)'],
+    [
+      /(?:ий|ый|ой)$/u,
+      2,
+      '(?:ий|ый|ой|ого|его|ому|ему|им|ым|ом|ем|ия|ию|ием|ии)',
+    ],
+    [/[аеуюя]й$/u, 1, '(?:й|я|ю|ем|е)'],
+    [/(?:ов|ев|ин)$/u, 0, '(?:а|у|ым|ом|е|ой)?'],
+    [/[жчшщц]$/u, 0, '(?:а|у|ем|ом|е)?'],
+    [/[жчшщц]а$/u, 1, '(?:а|и|е|у|ей|ею|ой|ою)'],
+    [/а$/u, 1, '(?:а|ы|и|е|у|ой|ою)'],
+    [/я$/u, 1, '(?:я|и|е|ю|ей|ею)'],
+    [/ь$/u, 1, '(?:ь|я|ю|ем|е|и|ью)'],
+  ];
+  const lower = word.toLowerCase();
+  if (fleeting[lower]) {
+    return `(?:${word}|${fleeting[lower]}${hardCases})`;
+  }
+  for (const [ending, remove, suffix] of endings) {
+    if (ending.test(lower) && word.length - remove >= 3) {
+      return escapePattern(remove ? word.slice(0, -remove) : word) + suffix;
+    }
+  }
+  if (/^[а-яё]{3,}[бвгджзклмнпрстфхцчшщ]$/u.test(lower)) {
+    // Plural forms would turn a given name into a surname: Петр and Петров.
+    return `${escapePattern(word)}${type === 'PERSON' ? `${hardCases}?` : '(?:а|у|ом|е|ы|ов|ам|ами|ах)?'}`;
+  }
+  return escapePattern(word);
+}
+export function wordPattern(word, type) {
+  return foldYo(
+    word
+      .split('-')
+      .map((part) =>
+        /^[а-яё]+$/iu.test(part)
+          ? cyrillicPattern(part, type)
+          : escapePattern(part)
+      )
+      .join('-')
+  );
+}
+const initialGap = '[ \\t\\u00a0]*';
+const initialPattern = (word) => `${foldYo(escapePattern(word[0]))}\\.`;
+// Everyday orders, partial forms and initials of a Russian full name, longest
+// first so that alternation prefers the complete form at each position.
+function russianForms(words, roles, type) {
+  const name = Object.fromEntries(
+    Object.entries(roles).map(([role, i]) => [role, words[i]])
+  );
+  const gap = '[ \\t]+';
+  const full = (...parts) =>
+    parts.map((part) => wordPattern(part, type)).join(gap);
+  if (name.surname === undefined) {
+    return [];
+  }
+  const initial = initialPattern(name.given);
+  const last = wordPattern(name.surname, type);
+  const short = [
+    full(name.surname, name.given),
+    full(name.given, name.surname),
+    `${last}${gap}${initial}`,
+    `${initial}[ \\t\\u00a0]+${last}`,
+  ];
+  if (name.patronymic === undefined) {
+    return short;
+  }
+  const initials = `${initial}${initialGap}${initialPattern(name.patronymic)}`;
+  return [
+    full(name.surname, name.given, name.patronymic),
+    full(name.given, name.patronymic, name.surname),
+    `${last}[ \\t\\u00a0]+${initials}`,
+    `${initials}[ \\t\\u00a0]+${last}`,
+    ...short,
+    full(name.given, name.patronymic),
+  ];
+}
+export function personalPatterns(value, type) {
+  if (value.length > 256) {
+    // Large explicit values still support literal matching without expansion.
+    return [escapePattern(value)];
+  }
+  const values = new Set([value]);
+  if (type === 'ORGANIZATION') {
+    const core = organizationCore(value);
+    if (core.length >= 3) {
+      values.add(core);
+    }
+  }
+  const patterns = new Set();
+  for (const surface of values) {
+    const parts = surface.split(/([ \t]+)/u);
+    const pattern = parts
+      .map((part, i) => (i % 2 ? '[ \\t]+' : wordPattern(part, type)))
+      .join('');
+    patterns.add(pattern);
+    if (type === 'PERSON') {
+      const words = parts.filter((_part, i) => i % 2 === 0);
+      const roles = russianNameRoles(words);
+      for (const form of roles ? russianForms(words, roles, type) : []) {
+        patterns.add(form);
+      }
+      if (words.length === 2) {
+        patterns.add(
+          [wordPattern(words[1], type), wordPattern(words[0], type)].join(
+            '[ \\t]+'
+          )
+        );
+      }
+    }
+  }
+  return [...patterns];
+}
+export function personalRegex(value, type) {
+  return new RegExp(
+    `(?<!${boundary})(?:${personalPatterns(value, type).join('|')})(?!${boundary})`,
+    'giu'
+  );
+}
+export function samePersonal(value, original, type) {
+  return personalPatterns(original, type).some((pattern) =>
+    new RegExp(`^(?:${pattern})$`, 'iu').test(value)
+  );
+}
+export function detectKnownPersonal(text, entries, rule, emit, options) {
+  let count = 0;
+  for (const entry of entries ?? []) {
+    const family =
+      rule === 'confirmed-personal' &&
+      options.documentEntities &&
+      !options.knownOnly &&
+      entry.type === 'ORGANIZATION' &&
+      organizationFamily(organizationCore(entry.value));
+    for (const pattern of [
+      personalRegex(entry.value, entry.type),
+      ...(family ? [family.pattern] : []),
+    ]) {
+      for (const match of text.matchAll(pattern)) {
+        if (++count > (options.maxFindings ?? 100000)) {
+          throw failure('ERR_LIMIT');
+        }
+        emit({
+          start: match.index,
+          end: match.index + match[0].length,
+          type: entry.type,
+          category: 'personal',
+          rule,
+          confidence: rule === 'known-personal' ? 0.85 : 0.9,
+        });
+      }
+    }
+  }
+}