# 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 — production deploy](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