v0.5.14 — вход по токену, JWKS в mock-режиме, production deploy docs

- POST /login-token: принимает реальный JWT (не только clientId) - auth.js: verifyAnyToken — mock + JWKS (Keycloak Nubes) одновременно - auth.js: JWKS предзагружается всегда, даже в mock-режиме - devops-deploy.md: полная production-инструкция для DevOps - .env.example: production-ready шаблон - README.md: актуальный (v0.5.13, архитектура, тесты, ссылки) - .gitignore: очищен от дубликатов
2026-06-03 12:37:10 +03:00
parent 22beaa86a3
commit 38c7adf25d
7 changed files with 396 additions and 143 deletions
@@ -1,57 +1,97 @@
-# IP WhiteList
-
-> ⚠️ **В процессе разработки.** НЕ для production.
+# IP WhiteList v0.5.13

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

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

 ---

-## Что делает
+## Возможности

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

-## Роли
+## Аутентификация

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

-## Как получить список для фильтрации
-
-Агрегированный список всех активных CIDR в формате txt (одна строка — одна подсеть).
-
-| Endpoint | Авторизация | Статус |
-|---|---|---|
-| `GET /export` | Bearer-токен | Будет основным (публичным по ТЗ) |
-| `GET /exp` | **Нет** | Временный, работает сейчас |
-
-После перевода `/export` на публичный доступ `/exp` будет удалён.
+В production требуются `KC_CLIENT_ID` + `KC_CLIENT_SECRET` от DevOps. Подробнее — [deploy guide](docs/devops-deploy.md).

 ## Стек

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

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

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

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

-## Деплой
+## Multi-company

-Nubes k8s. Редеплой — Nubes UI из Gitea после `git push`.
-URL: `https://white.nodejsk8s.dev.nubes.ru`
+Пользователь может принадлежать нескольким компаниям. В JWT claim `ClientID` передаются значения через запятую:
+```
+ClientID: "WZ11125,WZ03816"
+```
+Первое значение — активная компания. Переключение компаний — через UI.

-## Разработка
+## Тесты

-Перед любой задачей читать [`AGENT.md`](AGENT.md) — руководство для агентов и разработчиков.
+```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:3001 + 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