docs: перенос документации из IPWhiteList + CONTEXT.md (резюме для нового чата)

docs/WhiteIPlist.txt

@@ -0,0 +1,156 @@
+Техническое задание
+Микросервис управления доверенными адресами клиентов
+Self-service портал для указания клиентами доверенных IPv4-адресов и подсетей,
+исключаемых из блокировки на стороне облачного провайдера во время DDoS-атак
+
+───────────────────────────────────────────────────────────────
+КРАТКОЕ ОПИСАНИЕ (пояснение к реализации)
+───────────────────────────────────────────────────────────────
+Сервис даёт клиентам облачного провайдера личный кабинет, где они сами указывают
+свои доверенные IPv4-адреса и подсети. Эти адреса провайдер не блокирует во время
+DDoS-атак — так легитимный трафик клиента не попадает под ложные срабатывания
+фильтрации.
+
+Что реализуется:
+
+Личный кабинет клиента. Клиент входит через привычную авторизацию (Keycloak),
+видит свой список доверенных адресов и управляет им сам: добавляет, редактирует,
+удаляет записи с комментариями. Если пользователь работает с несколькими
+компаниями — переключается между ними.
+
+Проверка вводимых данных. Форма принимает только корректные IPv4-адреса и подсети,
+отклоняет «серые» и служебные диапазоны, не допускает дубликатов и пересечений
+внутри одной компании.
+
+Ограничение по количеству. На компанию по умолчанию 15 записей. Лимит
+настраивается глобально, а для отдельной компании администратор может поднять или
+опустить его индивидуально.
+
+Режим администратора (сетевые инженеры провайдера). Единое окно, где видны записи
+всех компаний, с фильтрами и доступом к истории изменений. Администратор управляет
+лимитами и при необходимости любыми записями.
+
+История изменений (аудит). Каждое создание, изменение и удаление фиксируется: кто,
+когда, что именно изменил. Удаление — логическое, данные физически сохраняются.
+
+Выдача для систем фильтрации. Отдельный адрес, по которому системы защиты
+автоматически забирают итоговый сводный список всех доверенных адресов (одним
+txt-файлом, по строке на запись). Адреса при этом схлопываются в компактный общий
+перечень.
+───────────────────────────────────────────────────────────────
+1. Назначение и цели
+1.1. Назначение
+Микросервис предоставляет клиентам облачного провайдера web-интерфейс для самостоятельного управления списком доверенных IPv4-адресов и подсетей. Записи из этого списка исключаются из автоматической блокировки сетевого взаимодействия системами фильтрации и митигации провайдера, что снижает количество ложноположительных срабатываний для легитимного трафика клиента.
+1.2. Цели
+Дать клиентам возможность самостоятельно поддерживать актуальный список доверенных IPv4-адресов, которые будут исключаться из фильтрации во время DDoS-атак.
+Предоставить сетевым инженерам единую точку просмотра и управления списками доверенных клиентских белых IPv4-адресов.
+Обеспечить машиночитаемую выдачу агрегированного (суммаризированного) списка для систем фильтрации трафика.
+2. Объем работ
+Web-страница / закладка в личном кабинете для управления whitelist-записями.
+Авторизация через существующий экземпляр Keycloak (OIDC).
+Валидация формы на стороне клиента и сервера.
+Внешний endpoint выдачи агрегированного списка. Выдача txt-файлом с переносом строки. Одна строка – один объект.
+Хранение записей, журнал аудита.
+Административное управление лимитами по компаниям.
+3. Роли и права доступа
+Роли определяются на основании claims в OIDC-токене Keycloak. Соответствие claim → роль настраивается на этапе развёртывания.
+Роль
+Идентификация
+Видимость записей
+Права на изменение
+Клиент (client)
+clientId
+Только записи компаний, к которым принадлежит пользователь.
+Создание, редактирование и удаление записей своих компаний (в пределах лимита).
+Администратор (admin)
+clientId = WZ01112 (Нубес) и отдельный чек-бокс
+Записи всех компаний.
+Создание, редактирование, удаление всех записей. Изменение лимита для отдельных компаний.
+3.1. Принадлежность к компании
+Принадлежность пользователя к компании определяется из claim токена. Поддерживается сценарий, когда пользователь принадлежит нескольким компаниям: в этом случае в интерфейсе предусматривается переключатель активной компании, а все операции выполняются в контексте выбранной компании.
+Ожидаемые claims (имена согласуются с командой Keycloak):
+clientID — идентификатор компании
+email — идентификация пользователя для аудита
+4. Функциональные требования
+4.1. Просмотр списка записей
+Клиент видит таблицу записей активной компании; Администратор – записи всех компаний с фильтром по компании.
+Для каждой записи отображаются: значение (адрес/подсеть), комментарий (если есть), автор(email), дата создания, дата последнего изменения.
+Soft-deleted записи по умолчанию скрыты; для администратора предусмотрен фильтр для их отображения.
+Отображается текущее использование лимита: «использовано X из N».
+4.2. Создание записи
+Форма содержит поля: значение (IPv4-адрес или подсеть CIDR) и необязательный комментарий (до 255 символов).
+Значение проходит валидацию (см. раздел 5) на клиенте и обязательно повторно на сервере.
+Перед сохранением проверяется: соблюдение лимита компании, отсутствие пересечений и дубликатов внутри компании, отсутствие принадлежности к запрещённым диапазонам.
+При успешном сохранении создаётся запись аудита.
+4.3. Редактирование записи
+Редактирование значения и комментария доступно компании в рамках своих прав.
+При изменении значения повторно выполняется полный набор проверок валидации и пересечений.
+Изменение фиксируется в журнале аудита с сохранением прежнего и нового значения.
+4.4. Удаление записи (soft delete)
+Удаление выполняется как логическое (soft delete): запись помечается удалённой (deleted_at, deleted_by), но физически сохраняется.
+Удалённая запись освобождает место в лимите компании и исключается из внешней агрегированной выдачи.
+Действие фиксируется в журнале аудита.
+4.5. Лимит записей на компанию
+Действует глобальный лимит по умолчанию: 15 активных записей на компанию.
+Значение глобального лимита по умолчанию задаётся конфигурацией сервиса и может быть изменено без пересборки.
+Для отдельной компании администратор может задать индивидуальный лимит, переопределяющий глобальный (как в большую, так и в меньшую сторону).
+При попытке превысить лимит создание блокируется с понятным сообщением; в подсчёт идут только активные записи.
+Снижение лимита ниже текущего числа записей не удаляет существующие записи, но блокирует создание новых до приведения в соответствие.
+4.6. Журнал аудита
+Все изменяющие операции фиксируются неизменяемыми записями аудита.
+Каждая запись аудита содержит: кто (пользователь), когда (timestamp), компания, тип действия, прежнее и новое состояние.
+Журнал доступен для просмотра только администратору.
+4.7. Внешняя выдача агрегированного списка
+Подсети суммаризируются (агрегируются в минимальный набор CIDR) по всем компаниям совместно. Пересечения между разными компаниями допустимы.
+Предоставляется отдельный HTTP GET endpoint, отдающий полный суммаризированный список активных записей всех компаний файлом в формате txt.
+Авторизация: на старте endpoint может работать без авторизации (по сетевому ограничению / разрешенный список потребителей по ip).
+5. Требования к валидации
+Валидация выполняется на клиенте и обязательно дублируется на сервере. Серверная валидация является авторитетной.
+Правило
+Описание
+Формат IPv4
+Допускается одиночный адрес (например 203.0.113.10) или подсеть в нотации CIDR (например 203.0.113.0/24). Допускается использование масок /32 - /22. Маска /21 и больше не допускается.
+Только IPv4
+IPv6-значения или доменные имена отклоняются.
+Корректность подсети
+Введенный адрес с маской подсети должен нормализоваться к адресу подсети, все host-биты должны быть обнулены.
+Пользователь должен быть уведомлен, что ввел адрес из хостовой части, а не адрес подсети и произошла нормализация.
+Запрет серых адресов
+Адреса и подсети из частных диапазонов (Приложение А) запрещены к добавлению.
+Отсутствие дубликатов
+В пределах одной компании запрещены полностью совпадающие записи.
+Отсутствие пересечений
+В пределах одной компании запрещено добавление записи, пересекающейся с уже существующей (включая вложенность подсетей). Между разными компаниями пересечения допускаются. 
+Длина комментария
+Не более 255 символов; поле необязательное.
+Приложение А – Список запрещенных к созданию подсетей.
+Назначение
+Префикс
+Private (RFC1918)
+10.0.0.0/8
+Private (RFC1918)
+172.16.0.0/12
+Private (RFC1918)
+192.168.0.0/16
+CGNAT (RFC6598)
+100.64.0.0/10
+Loopback
+127.0.0.0/8
+Link-local (APIPA)
+169.254.0.0/16
+IANA special block
+192.0.0.0/24
+TEST-NET-1 (docs)
+192.0.2.0/24
+TEST-NET-2 (docs)
+198.51.100.0/24
+TEST-NET-3 (docs)
+203.0.113.0/24
+Benchmarking
+198.18.0.0/15
+Multicast
+224.0.0.0/4
+Reserved (Class E)
+240.0.0.0/4
+Limited broadcast
+255.255.255.255/32