naeel
2194c1650f
- AGENT-GUIDE.md: убран IP ВМ, HTTP→HTTPS - copilot-instructions.md: Files/token.txt→.env.example - keycloak-auth-reference.md: убраны реальные client_id, URL gateway, email - deploy-keycloak.md: реальные параметры заменены на шаблоны - .env.example: русские значения→шаблоны - README.md: порт 3000, multi-company пример под mock
98 lines
4.6 KiB
Markdown
98 lines
4.6 KiB
Markdown
# IP WhiteList v0.5.14
|
||
|
||
Self-service портал для управления доверенными IPv4-адресами клиентов облачного провайдера.
|
||
Записи исключаются из блокировки системами фильтрации во время DDoS-атак.
|
||
|
||
**[Техническое задание](docs/ТЗ.md)** · **[DevOps — production deploy](docs/devops-deploy.md)**
|
||
|
||
---
|
||
|
||
## Возможности
|
||
|
||
- **Управление белым списком:** добавление, редактирование, удаление (soft delete) IPv4/CIDR
|
||
- **Валидация** на сервере: маски `/22`–`/32`, запрет 14 приватных/служебных диапазонов, запрет дубликатов и пересечений, нормализация host-битов
|
||
- **Лимиты:** глобальный (по умолчанию 15) и индивидуальный на компанию (настраивает админ)
|
||
- **Агрегированный экспорт** CIDR-списка для систем фильтрации (`GET /export`)
|
||
- **Мульти-компания:** один пользователь может управлять несколькими компаниями (clientId через запятую)
|
||
- **Аудит:** все изменения фиксируются — кто, когда, что было и что стало
|
||
- **Администрирование:** просмотр всех компаний, управление лимитами, журнал аудита
|
||
|
||
## Аутентификация
|
||
|
||
| Режим | Описание |
|
||
|---|---|
|
||
| **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](docs/devops-deploy.md).
|
||
|
||
## Стек
|
||
|
||
```
|
||
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
|
||
|
||
Пользователь может принадлежать нескольким компаниям. В JWT claim `ClientID` передаются значения через запятую:
|
||
```
|
||
ClientID: "WZ88888,WZ77777"
|
||
```
|
||
Первое значение — активная компания. Переключение компаний — через UI.
|
||
|
||
## Тесты
|
||
|
||
```bash
|
||
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)
|
||
|
||
```bash
|
||
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`](docs/devops-deploy.md) — nginx, HTTPS, PM2, Keycloak SSO.
|
||
|
||
## Документация
|
||
|
||
- [Техническое задание](docs/ТЗ.md)
|
||
- [Уточнения ТЗ](docs/ТЗ-плюс.md)
|
||
- [DevOps deployment guide](docs/devops-deploy.md) (англ.)
|
||
- [AI Agent Guide](.github/AGENT-GUIDE.md) (англ., для Copilot)
|
||
- [Copilot Instructions](.github/copilot-instructions.md) (правила для AI)
|
||
- [Keycloak/OIDC reference](docs/keycloak-auth-reference.md)
|
||
- [Deploy Keycloak](docs/deploy-keycloak.md)
|
||
|
||
## Текущий деплой
|
||
|
||
- **URL:** `https://italo.kube5s.ru`
|
||
- **Режим:** DEV_MODE=true (mock)
|
||
- **БД:** PostgreSQL на ВМ, localhost only
|