@besales/anonymizer

Stateless обратимая псевдонимизация PII для besales/animaly.

detect → tokenize → mapping → detokenize. Реальные Иван Петров / +79161234567 → токены [PERSON_1] / [PHONE_1] перед отправкой в LLM; обратная подстановка реальных значений в ответе и в аргументах tool-call'ов (например, реальный email в поле CRM).

Чем это НЕ является

• Не сервис, а in-process библиотека. Чистые функции, без БД/сети/фреймворков/очередей. Вызывающий сам решает, где хранить MappingData (в этом проекте — request-scoped в памяти). В отличие от transcription-service, анонимайзер на горячем пути каждого LLM-вызова — сетевой round-trip недопустим.
• Не lossy-скраббер. В отличие от одностороннего [EMAIL]-маскирования, здесь маппинг токен→значение обратим и идемпотентен (один PII → один токен).

Установка

yarn add @besales/anonymizer

Публичный пакет на npm (как @besales/mcp) — токены/.npmrc не нужны.

Использование

import {
  anonymizeMessages,
  deanonymizeMessages,
  buildSystemPromptInstruction,
  getLocale,
  ENTITY_TYPE,
  DETECTION_CONTEXT,
  createEmptyMapping,
  type ProtectedEntity,
} from '@besales/anonymizer';

const contactName: ProtectedEntity = {
  type: ENTITY_TYPE.CONTACT_NAME,
  token: 'CONTACT_NAME_1',
  value: 'Раиса',
  aliases: ['Раисе', 'Раисы', 'Раисой'],
};

// Outbound: реальные messages → токены (накапливаем mapping)
const { messages: anon, mappingData } = anonymizeMessages(
  realMessages,
  DETECTION_CONTEXT.CHAT_MESSAGE,
  createEmptyMapping(),
  // chat-профиль: исключаем AMOUNT/COMPANY (ложная токенизация сумм в продажах)
  {
    locale: 'ru',
    excludeEntityTypes: [ENTITY_TYPE.AMOUNT, ENTITY_TYPE.COMPANY],
    protectedEntities: [contactName],
  },
);

// Инструкция в system, чтобы модель сохраняла токены как есть
const instruction = getLocale('ru').systemPrompt.buildInstruction(
  Object.keys(mappingData.tokens).map((k) => `[${k}]`),
);

// ... вызов LLM с anon + instruction ...

// Inbound: ответ модели (content + tool_calls.arguments + reasoning text) → реальные значения
const { messages: restored } = deanonymizeMessages(llmResponseMessages, mappingData);

Инструкция перечисляет только активные токены текущего mapping и не добавляет синтетические примеры: несуществующий токен из system-промпта модель могла бы повторить, а безопасно восстановить его без значения невозможно.

Для repair искажённых моделью токенов ([EMAIL1] → [EMAIL_1]) — autoFixMalformedTokens перед деанонимизацией. Поддержка Responses API — anonymizePayload / deanonymizePayload.

Если значение уже подтверждено текущим mapping, но встретилось повторно в динамическом тексте (например, внутри URL или описания инструмента), его можно закрыть без нового детекторного прохода:

import { replaceKnownValuesWithTokens } from '@besales/anonymizer';

replaceKnownValuesWithTokens('Клиент Раиса', [['CONTACT_NAME_1', 'Раиса']]);
// 'Клиент [CONTACT_NAME_1]'

Вызывающий код выбирает поля и передаёт пары [токен без скобок, значение]. Пустые и состоящие только из пробелов значения игнорируются.

Детектируемые типы

PERSON, FIRST_NAME, LAST_NAME, PATRONYMIC, PHONE, EMAIL, INN, PASSPORT, CARD, AMOUNT, DATE_OF_BIRTH, ADDRESS, COMPANY, ACCOUNT, SNILS, OGRN, OGRNIP, SOCIAL_ID. Локали: ru (имена — словарь; phone/email/card — языконезависимый regex; СНИЛС/ОГРН/ОГРНИП — по контрольной сумме, ловятся без слова-метки; SOCIAL_ID — VK/Telegram/Max @-хэндлы и ссылки на профиль). excludeEntityTypes сужает набор под профиль. Телефон распознаётся только как отдельное значение, поэтому цифры внутри UUID и других технических идентификаторов не становятся PHONE.

CONTACT_NAME не определяется эвристикой. Его создаёт только вызывающий код через protectedEntities, когда уже знает имя текущего контакта. Все переданные формы получают один фиксированный токен (например [CONTACT_NAME_1]), а пересекающиеся фамилия/отчество остаются закрыты обычными токенами. В строгом трёхчастном ФИО русские фамилии/отчества рядом с известным именем дополнительно распознаются по консервативным суффиксам, включая редкие фамилии вроде Плахова. Свободная пара слов больше не становится PERSON только из-за заглавных букв или капслока: составное имя требует полной словарной структуры имя + фамилия/отчество, а его части могут разделяться только пробелами. Поэтому МАРИНА, СПАСИБО, СВЕТЛАНА! Я ЗА ГОРОДОМ и ЗАБРАТЬ ПОДАРКИ остаются обычным текстом, но ИВАНОВ АЛЕКСАНДР СЕРГЕЕВИЧ распознаётся независимо от регистра. Это позволяет модели выбрать место обращения, не раскрывая ей реальное имя.

Имена, распознанные словарём, раскладываются на FIRST_NAME / LAST_NAME / PATRONYMIC (нераспознанные — остаются PERSON). excludeEntityTypes технически поддерживает эти типы для обратной совместимости, но security-sensitive потребители не должны исключать именные типы: персонализация должна идти через CONTACT_NAME.

Одиночные имена ловятся в контексте самопредставления. Явные конструкции меня зовут X, моё имя X, зовите меня X защищают и редкие имена вне словаря. Неоднозначная короткая форма я X требует точного словарного имени: я Никита токенизируется, а Я Хочу, Я Готова и Я Подтверждаю остаются обычным текстом. Произвольное одиночное имя без такого триггера или фамилии рядом не токенизируется, чтобы не повышать ложные срабатывания. После ролевых слов клиент, заказчик, покупатель имя должно начинаться сразу после роли (допускается :, тире или запятая): Клиент: Раиса Федоровна защищается, а Клиентка из Ростова-на-Дону не принимается за имя.

Для детерминированного разбора уже структурированного профильного поля экспортируется extractStructuredNameCandidates(). Он возвращает словарные роли отдельных слов, но не решает, какое из них принадлежит текущему контакту — это ответственность resolver'а потребителя.

Fail-closed проверка ответа

validateLlmResponse() считает невалидными не только искажённые, но и любые корректно оформленные токены, которых нет в текущем mapping. Это не позволяет модели подставить [FIRST_NAME_99] или другой выдуманный placeholder. Вызывающий код должен блокировать такой ответ или повторить генерацию, но не отправлять литеральный токен пользователю. Token-like варианты без канонического формата (CONTACT_NAME_1, [CONTACT NAME 1], [CONTACT-NAME-1]) также считаются malformed: уверенное искажение можно исправить через autoFixMalformedTokens, неуверенное необходимо блокировать.

Потребители

• ai-aniomaly — runtime-анонимизация чата (LLM-пайплайн).
• prompt-services — анонимизация CRM-диалогов в sandbox/ICP (план).
• leak-engine / dialogue-ingestion — анализ звонков/переписок (план).

Разработка

yarn install
yarn build        # tsc → dist + копирование CSV-словарей в dist/locales/ru/data
yarn test
yarn lint:errors