# IP WhiteList

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

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

## Быстрый старт

```bash
npm install
cp .env.example .env   # заполнить переменные
npm start              # http://localhost:3000
npm test               # 104 API-теста
npm run test:stress    # 191 стресс-тест
```

## Переменные окружения

| Переменная | Назначение | По умолчанию |
|---|---|---|
| `DEV_MODE` | mock-аутентификация (`true` в dev, **запрещён** в prod) | — |
| `ADMIN_CLIENT_ID` | clientId администратора | `WZ01112` |
| `DEFAULT_LIMIT` | лимит записей на компанию | `15` |
| `DATABASE_URL` | строка подключения PostgreSQL | — |
| `SESSION_SECRET` | секрет сессий (**обязателен** в prod) | — |

[Полный список в AGENT.md](AGENT.md#4-переменные-окружения)

## Стек

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

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

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

Два слоя: SSR UI для браузера и JSON API для внешних потребителей.
API — Bearer-only (без сессий), UI — сессия + Bearer-токен внутри.

**[Подробная карта файлов в AGENT.md](AGENT.md#5-структура-файлов--карта-ответственности)**

## Роли

| Роль | clientId | Права |
|---|---|---|
| Клиент | Любой | CRUD своих записей в пределах лимита |
| Администратор | `WZ01112` | CRUD всех записей, изменение лимитов, аудит |

## Деплой

Платформа: Nubes k8s. Редеплой — через Nubes UI из Gitea после `git push`.
Production URL: `https://white.nodejsk8s.dev.nubes.ru`

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

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