Metadata-Version: 2.5
Name: vilna-privacy-gateway
Version: 0.1.0.dev0
Summary: On-device masking of personal data before a request leaves for a cloud model, with the real values put back into the answer
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# Шлюз приватності

Бібліотека, яка на пристрої знаходить і маскує чутливі дані, перш ніж запит піде у хмарну модель, і повертає справжні значення у відповідь. У Gloxi вона стоїть між маршрутизатором моделей і хмарою та увімкнена за замовчуванням.

Ліцензія — **Apache-2.0** (файл [`LICENSE`](LICENSE) у цій папці), щоб бібліотеку можна було використовувати поза Vilna. Див. [`LICENSING.md`](../LICENSING.md) і [ADR 0001](../docs/adr/0001-licensing.md).

## Як це працює

```python
from privacy_gateway import Masker

masker = Masker()  # один на розмову
masked = masker.mask("Напиши Олені на olena@example.com, тел. +380 67 123 45 67")
# 'Напиши Олені на [EMAIL_1], тел. [PHONE_1]'

answer = "Готово, лист для [EMAIL_1] складено."  # відповідь хмарної моделі
masker.unmask(answer)
# 'Готово, лист для olena@example.com складено.'
```

- Однакове значення завжди отримує той самий замінник, і нумерація не змінюється між репліками розмови. Модель бачить, що двічі згадано ту саму людину, але не бачить, хто це.
- Справжні значення живуть лише в пам'яті об'єкта `Masker` на пристрої. `repr(masker)` їх не показує, щоб вони не потрапили в журнали.
- `mask_messages()` маскує список повідомлень чату (формат OpenAI), не змінюючи оригінал. Якщо в запиті є замінники, він додає до системного повідомлення коротку вказівку копіювати їх без змін (`PLACEHOLDER_HINT`). За заміром на чотирьох постачальниках з нею значення зберігаються в усіх завданнях ([`bench/`](bench/README.md)); вимкнути можна через `hint=False`.
- `unmask_stream()` повертає значення в потокову відповідь, навіть якщо замінник розірвано між шматками (`[EMA` + `IL_1]`).
- `unmask()` повертає значення й тоді, коли модель трохи змінила замінник: інший регістр, дужки чи роздільник, одна-дві літери (`[Email_1]`, `{EMAIL 1}`, `[EMIAL_1]`). Відновлюються лише замінники з цієї розмови.
- `unresolved()` показує, що в відповіді схоже на замінник, але не відновилося. Gloxi тоді попереджає людину.
- Можна маскувати лише вибрані види: `Masker(kinds=[Kind.EMAIL, Kind.PHONE])`.

## Що знаходить

| Вид | Приклад (вигаданий) | Як перевіряється |
| --- | --- | --- |
| `SECRET` | ключі API (`sk-…`, `ghp_…`, `AKIA…`), токени `Bearer`, приватні ключі, `Пароль: …`, пароль у реченні («мій пароль від пошти Kvitka-7731», "my password is Hunter2!", 10 мов) | шаблон |
| `EMAIL` | `olena@example.com` | шаблон |
| `PHONE` | `+380 67 123 45 67`, `067-123-45-67` | 10–15 цифр, не дата і не сума |
| `IBAN` | `UA21 3223 1300 …` | контрольна сума mod 97 |
| `CARD` | `4111 1111 1111 1111` | алгоритм Луна |
| `TAX_ID` | РНОКПП `3000000008` | контрольна сума |
| `PASSPORT` | `КМ 123456`, `Паспорт: …` | шаблон |
| `NATIONAL_ID` | DNI/NIE `12345678Z` (es), PESEL (pl), Steuer-ID (de), NIR (fr), codice fiscale (it), CNP (ro), rodné číslo `905101/1002` (cs, sk), asmens kodas (lt) | контрольна сума кожного формату; де номер містить дату народження — ще й дата |
| `TAX_ID` (pl) | `NIP: 123-456-32-18` | контрольна сума, лише з підписом `NIP` |
| `IP` | `192.168.10.25` | діапазони октетів |
| `PROFILE` | `t.me/user`, `linkedin.com/in/user` | лише посилання на профіль, не на репозиторій чи допис |
| `NAME`, `BIRTH_DATE`, `ADDRESS` | `ПІБ: …`, `Дата народження: …`, `Адреса: …` | лише в підписаних полях |

Ховається лише саме значення, підпис лишається: з `Email: a@b.eu` виходить `Email: [EMAIL_1]`.

## Обмеження

- **Імена й місця у вільному тексті не знаходяться.** «Подзвони Олені» лишиться як є. Для цього потрібна мовна модель на пристрої; це наступний крок. Поки що ім'я ховається лише в підписаному полі.
- Правила налаштовані на українські й міжнародні формати та на номери особи й податкові номери країн [ADR 0009](../docs/adr/0009-languages.md). Номери інших країн поки не розпізнаються.
- **Голі числа — лише з прив'язкою до людини.** Номер особи, податковий номер чи телефон, записаний суцільними цифрами (`90010112349`, `0671234567`), сам по собі нікого не називає і часто є просто числом замовлення чи розрахунку. Тому він ховається, лише якщо поруч слово-ключ («PESEL», «тел.», «номер», «клієнт», «ID»… 10 мовами), у тому ж тексті є інші персональні дані (ім'я в полі, пошта, адреса, картка…), таких номерів кілька (список) або це значення вже ховали раніше в розмові. Картки, IBAN, ключі й номери з формою (літера, коса риска, пробіли, `+`) ховаються завжди.
- **Суворий режим** `Masker(strict=True)` / `detect(..., strict=True)` ховає кожне число, що проходить перевірку, з прив'язкою чи без. Gloxi вмикає його для звітів про збої й відгуків; у продуктах — для професій із таємницею і організацій.
- Число у формулі не ховається: якщо поруч знак дії (`= + − * / ^`) або слово-дія 10 мовами («плюс», «помножити на», «times», «razy», «geteilt durch»…) і ще одне число або це десяткова частина (`15! = 1307674368000`, `90010112349 + 1`), модель має бачити його, щоб порахувати. З назвою зліва (`PESEL = 90010112349`) номер ховається, як і раніше.
- Це мінімізація даних, а не гарантована анонімізація: якщо щось не впізнано, воно піде в хмару як є. Тому Gloxi завжди показує, куди йде запит.
- Якщо модель змінить замінник (наприклад, напише `EMAIL 1` без дужок), значення не повернеться і користувач побачить замінник.

## Заміри

Який формат замінників хмарні моделі повертають без змін і яка мала модель знаходить імена у вільному тексті: [`bench/`](bench/README.md).

## Розробка

```sh
uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .
```

Тестові дані — лише вигадані: адреси на `example.com`, тестові номери карток, ідентифікатори, які проходять контрольну суму, але нікому не належать.

Початкові шаблони перенесено з власних раніших напрацювань автора проєкту й переписано під загальний текст: оборотні нумеровані замінники замість однобічних позначок, контрольні суми, звужені правила.
