IPWhiteList/docs/plan-working.md

Рабочий план — IP WhiteList

Автор: GitHub Copilot (Claude Sonnet 4.6) Дата: 2026-05-29 Стек: Node.js + Express + pg + EJS Деплой: nubes_nodejs + nubes_postgres (через веб-кабинет)

---

Что выяснили

Факт	Детали
API шлюз	lk-api-gateway.ngcloud.ru, за DDOS-Guard
JWT	iss: auth-api, claims: ClientID, company_id, company_name, email
Токен для dev	secrets.txt, tech-токен, долгий
Валидация JWT	Шлюз делает сам, нам не нужно
Деплой	Пользователь создаёт инстансы через веб-кабинет
isAdmin	❓ В JWT нет, нужно уточнить как передавать
Мульти-компании	❓ В JWT одна компания, список — в authData (localStorage)

---

Файлы проекта (всё в корне)

├── server.js          # Express: старт, роуты, middleware
├── db.js              # pg Pool
├── .env.example       # DB_DSN, PORT, DEFAULT_LIMIT, DEV_MODE
├── package.json
├── views/             # EJS-шаблоны
│   └── index.ejs      # таблица + форма
├── public/
│   └── style.css
├── sql/
│   └── schema.sql     # CREATE TABLE companies, whitelist_entries, audit_log
└── .gitignore

---

Схема БД

companies (id, client_id UNIQUE, name, custom_limit)
whitelist_entries (id, company_id FK, value_cidr, comment, created_by, created_at, updated_by, updated_at, deleted_by, deleted_at)
audit_log (id, user_email, company_id, action, old_value, new_value, created_at)

• deleted_at IS NULL = активная запись
• custom_limit IS NULL = использовать DEFAULT_LIMIT (15)

---

Порядок действий

Шаг 1 — Каркас

• package.json (express, pg, ejs, dotenv)
• server.js (Express, EJS, static, health check /healthz)
• db.js (pg Pool, SELECT 1 при старте)
• .env.example

Шаг 2 — Схема БД

• sql/schema.sql
• Запустить на своём PG

Шаг 3 — Валидатор IPv4

• Функция validateCIDR(input) → { cidr, wasNormalized } | error
• Правила: /32–/22, запрет серых, нормализация host-битов

Шаг 4 — CRUD (сырой pg, без ORM)

• Список записей компании
• Создание (проверка лимита, дубликатов, пересечений)
• Редактирование
• Soft-delete

Шаг 5 — Auth middleware

• DEV_MODE=true: читать заголовок X-Dev-User
• PROD: читать JWT из Authorization (шлюз уже проверил)

Шаг 6 — UI

• Таблица + форма создания/редактирования
• Индикатор лимита «X из N»
• Сообщения: нормализация, превышение, пересечение

Шаг 7 — Аудит

• Запись в audit_log при create/update/delete

Шаг 8 — Экспорт

• GET /api/v1/export — txt, все активные CIDR

Шаг 9 — Деплой

• Завести nubes_postgres и nubes_nodejs через кабинет
• Подключить к API-шлюзу (уточнить процедуру)

---

Что откладываем

• Keycloak OIDC (шлюз делает)
• Полноценный админ-интерфейс
• Переключатель компаний (multi-profile)
• Тонкая настройка прав