IPWhiteList/docs/plan.md

IP WhiteList — План разработки

Дата: 2026-05-30
Основание: WhiteIPlist.txt (ТЗ) + фактический код в ipwhitelist-app
Статус: каноничный — единственный актуальный план

---

1. Текущее состояние

Готово ✅

Слой	Файлы	Что есть
БД	sql/schema.sql	companies, whitelist_entries (soft delete), audit_log + индексы
Валидатор	src/validators.js	Все 14 запрещённых диапазонов Приложения А, /22–/32, нормализация host-битов, проверка пересечений
CRUD	src/queries.js	createEntry, updateEntry, deleteEntry (soft), listEntries, getExportCIDRs, getAudit, getLimit
UI	views/index.ejs	Список, форма добавления, кнопка удаления, стиль Nubes
Роуты	server.js	GET /, POST /add, POST /delete/:id, GET /export, GET /healthz

Написано в queries.js, но не подключено к роутам

• updateEntry — нет POST /update/:id, нет UI редактирования
• getAudit — нет страницы аудита
• listEntries(companyId, includeDeleted=true) — флаг есть, не используется

---

2. Что требует ТЗ, но отсутствует

#	Требование	Готовность
1	Редактирование записи из UI	❌ queries есть, роута нет
2	Админ-панель (все компании, лимиты, аудит, фильтры)	❌
3	OIDC Keycloak вместо base64-заглушки	❌
4	Суммаризация CIDR в /export	❌ отдаёт сырой список
5	Клиентская валидация (JS в форме)	❌
6	Переключатель компаний (multi-company)	❌
7	Просмотр soft-deleted записей админом	❌
8	Изменение custom_limit для компании	❌

---

3. Порядок реализации

Этап 1 — Пользовательский сценарий (client-flow)

• Валидатор IPv4/CIDR — полный
• Создание / удаление / экспорт
• Добавить POST /update/:id в server.js
• Добавить inline-форму редактирования в views/index.ejs
• Клиентская валидация (JS: формат, маска, длина комментария)

Этап 2 — Административная панель

• Определение admin-роли (clientId === 'WZ01112' + чекбокс)
• GET /admin — страница со всеми компаниями
• POST /admin/limit/:companyId — изменение custom_limit
• GET /admin/audit — журнал аудита
• Фильтр по компании + показ удалённых записей

Этап 3 — Авторизация Keycloak OIDC

• npm install openid-client
• Замена base64-decode на проверку подписи JWT
• Маппинг claims → req.user (clientId, email, role)
• Оставить DEV_MODE только для локальной разработки

Этап 4 — Экспорт и Multi-company

• npm install cidr-tools — суммаризация в GET /export
• Переключатель активной компании (если несколько clientId в claims)

Этап 5 — Завершение

• Автотесты (jest + supertest)
• Пагинация (если лимит > 50)
• Сверка всех пунктов ТЗ

---

4. Что НЕ делать

• ❌ Не переписывать на Python/FastAPI
• ❌ Не менять схему БД
• ❌ Не переписывать validators.js (он полный)
• ❌ Не переписывать queries.js
• ❌ Не делать SPA

---

5. Зависимости для установки

npm install cidr-tools openid-client
npm install --save-dev jest supertest

Всё остальное — в рамках Express + EJS + pg.

---

6. Риски

• Admin-роль: неясно как «отдельный чек-бокс» из ТЗ попадает в токен — требует уточнения с командой Keycloak
• Multi-company claims: ТЗ говорит о нескольких компаниях, но в claims только clientID — нужен реальный формат
• IP-ограничение /export: делать в приложении или на уровне ingress — решить при деплое