IP WhiteList v0.5.23

Self-service портал для управления доверенными IPv4-адресами клиентов облачного провайдера. Записи исключаются из блокировки системами фильтрации во время DDoS-атак.

[ТЗ] · [DevOps — production deploy] · [Кратко (без воды)]

---

Возможности

• Управление белым списком: добавление, редактирование, удаление (soft delete) IPv4/CIDR
• Валидация на сервере: маски /22–/32, запрет 14 приватных/служебных диапазонов, запрет дубликатов и пересечений, нормализация host-битов
• Лимиты: глобальный (по умолчанию 15) и индивидуальный на компанию (настраивает админ)
• Агрегированный экспорт CIDR-списка для систем фильтрации (GET /export)
• Мульти-компания: через IAM API — переключение между компаниями пользователя
• Аудит: все изменения фиксируются — кто, когда, что было и что стало
• Администрирование: просмотр всех компаний, управление лимитами, журнал аудита

Аутентификация

Режим	Описание
DEV_MODE=true (тесты/разработка)	Mock JWT, локальная RSA-пара. Вход через форму выбора пользователя или вставку Bearer-токена
DEV_MODE=false (production)	OIDC SSO через Keycloak Nubes. Редирект на Keycloak login → /callback → сессия

В production требуются KC_CLIENT_ID + KC_CLIENT_SECRET от DevOps. Подробнее — deploy guide.

Стек

Node.js 20+  →  Express 4  →  EJS (SSR)  →  PostgreSQL 16+
jsonwebtoken RS256 / JWKS (Keycloak Nubes)
express-session + connect-pg-simple

Архитектура

Browser → nginx:443 → Express:3001
                        ├── /export (публичный CIDR)
                        ├── /api/v1/* (REST API, Bearer JWT)
                        └── /* (UI, SSR EJS, сессия → api-client.js → API)

Два слоя: SSR UI для браузера, JSON API для внешних систем.

Multi-company

Пользователь может принадлежать нескольким компаниям. Список компаний и активная определяются через IAM API (GET /api/v1/auth/user → profiles[]). Переключение — через UI или POST /api/v1/user/switch-profile.

Тесты

npm test                # 121 API-тест (Bearer JWT, CRUD, изоляция, admin)
node tests/integration.js  # 68 UI-тестов (сессии, EJS)
node tests/tz-compliance.js # 47 тестов ТЗ
node tests/tz-full-compliance.js # 111 тестов (20 компаний × 100 CIDR)
node tests/stress.js    # 191 стресс-тест (concurrency, auth attacks, edge cases)

Все тесты требуют реального PostgreSQL.

Быстрый старт (dev)

git clone https://gitea.services.ngcloud.ru/Nail/ipwhitelist-app.git
cd ipwhitelist-app
cp .env.example .env    # заполнить DB_* и SESSION_SECRET
npm install
psql -U postgres -d ipwhitelist -f sql/schema.sql
npm start               # http://localhost:3000 + DEV_MODE=true

Production deploy

См. docs/devops-deploy.md — nginx, HTTPS, PM2, Keycloak SSO.

Документация

• Техническое задание
• Уточнения ТЗ
• DevOps — production deploy
• AI Agent Guide (англ., для Copilot)
• Copilot Instructions (правила для AI)
• Keycloak/OIDC reference
• Deploy Keycloak

Текущий деплой

• URL: https://italo.kube5s.ru
• Режим: DEV_MODE=true (mock)
• БД: PostgreSQL на ВМ, localhost only