@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);

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

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

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 сужает набор под профиль.

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

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

Одиночные имена ловятся только в сильном контексте самопредставления: меня зовут Никита, моё имя Никита, зовите меня Никита, я Никита. Произвольное одиночное имя без такого триггера или фамилии рядом не токенизируется, чтобы не повышать ложные срабатывания.

Для детерминированного разбора уже структурированного профильного поля экспортируется 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