# IP WhiteList

> ⚠️ **В процессе разработки.** НЕ для production.

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

**[Полное техническое задание](docs/ТЗ.md)** · **[Отчёт о соответствии](docs/TZ-COMPLIANCE-REPORT.md)**

---

## Что делает

- **Клиент** авторизуется через Keycloak (OIDC) и управляет списком своих IPv4/CIDR: добавляет, редактирует, удаляет (soft delete)
- **Валидация** на сервере: маски /22–/32, запрет 14 приватных/служебных диапазонов, запрет дубликатов и пересечений внутри компании, нормализация host-битов
- **Лимиты:** глобальный (15 по умолчанию, настраивается через env) и индивидуальный на компанию (устанавливает админ)
- **Администратор** видит записи всех компаний, управляет лимитами, просматривает журнал аудита
- **Аудит:** все изменения (создание/редактирование/удаление) фиксируются — кто, когда, что было и что стало

## Роли

| Роль | Права |
|---|---|
| Клиент | CRUD своих записей в пределах лимита |
| Администратор (WZ01112) | CRUD всех записей, изменение лимитов, просмотр аудита |

## Как получить список для фильтрации

Агрегированный список всех активных CIDR в формате txt (одна строка — одна подсеть).

| Endpoint | Авторизация | Статус |
|---|---|---|
| `GET /export` | Bearer-токен | Будет основным (публичным по ТЗ) |
| `GET /exp` | **Нет** | Временный, работает сейчас |

После перевода `/export` на публичный доступ `/exp` будет удалён.

## Стек

Node.js 18+ / Express 4 / EJS (SSR) / PostgreSQL 17 / jsonwebtoken RS256

## Архитектура

```
Browser → UI (EJS, сессия) → REST API (Bearer JWT) → PostgreSQL
```

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

## Деплой

Nubes k8s. Редеплой — Nubes UI из Gitea после `git push`.
URL: `https://white.nodejsk8s.dev.nubes.ru`

## Разработка

Перед любой задачей читать [`AGENT.md`](AGENT.md) — руководство для агентов и разработчиков.
