From 707319ed23247077dc9e2e339bf5d5aa2cce1b30 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CNaeel=E2=80=9D?= Date: Sun, 31 May 2026 12:41:04 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E2=80=94=20=D0=B2=20=D0=BF?= =?UTF-8?q?=D1=80=D0=BE=D1=86=D0=B5=D1=81=D1=81=D0=B5=20=D1=80=D0=B0=D0=B7?= =?UTF-8?q?=D1=80=D0=B0=D0=B1=D0=BE=D1=82=D0=BA=D0=B8,=20=D0=BE=D0=BF?= =?UTF-8?q?=D0=B8=D1=81=D0=B0=D0=BD=D0=B8=D0=B5=20=D1=84=D1=83=D0=BD=D0=BA?= =?UTF-8?q?=D1=86=D0=B8=D0=BE=D0=BD=D0=B0=D0=BB=D0=B0,=20=D0=B1=D0=B5?= =?UTF-8?q?=D0=B7=20=D1=83=D1=81=D1=82=D0=B0=D0=BD=D0=BE=D0=B2=D0=BA=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 58 ++++++++++++++++++++++--------------------------------- 1 file changed, 23 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index cd40d42..2205d08 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,47 @@ # IP WhiteList -Self-service портал управления доверенными IPv4-адресами клиентов облачного провайдера. +> ⚠️ **В процессе разработки.** НЕ для production. + +Self-service портал для управления доверенными IPv4-адресами клиентов облачного провайдера. Записи исключаются из блокировки системами фильтрации во время DDoS-атак. -**[Техническое задание](docs/ТЗ.md)** · **[Отчёт о соответствии ТЗ](docs/TZ-COMPLIANCE-REPORT.md)** +**[Полное техническое задание](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 стресс-тест -``` +## Что делает -## Переменные окружения +- **Клиент** авторизуется через Keycloak (OIDC) и управляет списком своих IPv4/CIDR: добавляет, редактирует, удаляет (soft delete) +- **Валидация** на сервере: маски /22–/32, запрет 14 приватных/служебных диапазонов, запрет дубликатов и пересечений внутри компании, нормализация host-битов +- **Лимиты:** глобальный (15 по умолчанию, настраивается через env) и индивидуальный на компанию (устанавливает админ) +- **Администратор** видит записи всех компаний, управляет лимитами, просматривает журнал аудита +- **Аудит:** все изменения (создание/редактирование/удаление) фиксируются — кто, когда, что было и что стало +- **Экспорт:** агрегированный список всех активных CIDR в txt (для систем фильтрации трафика) -| Переменная | Назначение | По умолчанию | -|---|---|---| -| `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-переменные-окружения) +| Роль | Права | +|---|---| +| Клиент | CRUD своих записей в пределах лимита | +| Администратор (WZ01112) | CRUD всех записей, изменение лимитов, просмотр аудита | ## Стек -Node.js 18+ / Express 4 / EJS / PostgreSQL 17 / jsonwebtoken RS256 +Node.js 18+ / Express 4 / EJS (SSR) / PostgreSQL 17 / jsonwebtoken RS256 ## Архитектура ``` -Browser → UI (EJS, сессия) → api-client → REST API (Bearer JWT) → PostgreSQL +Browser → UI (EJS, сессия) → REST API (Bearer JWT) → PostgreSQL ``` -Два слоя: SSR UI для браузера и JSON API для внешних потребителей. -API — Bearer-only (без сессий), UI — сессия + Bearer-токен внутри. - -**[Подробная карта файлов в AGENT.md](AGENT.md#5-структура-файлов--карта-ответственности)** - -## Роли - -| Роль | clientId | Права | -|---|---|---| -| Клиент | Любой | CRUD своих записей в пределах лимита | -| Администратор | `WZ01112` | CRUD всех записей, изменение лимитов, аудит | +Два слоя: SSR UI для браузера, JSON API для внешних потребителей. ## Деплой -Платформа: Nubes k8s. Редеплой — через Nubes UI из Gitea после `git push`. -Production URL: `https://white.nodejsk8s.dev.nubes.ru` +Nubes k8s. Редеплой — Nubes UI из Gitea после `git push`. +URL: `https://white.nodejsk8s.dev.nubes.ru` ## Разработка -Перед любой задачей читать [`AGENT.md`](AGENT.md) — полное руководство для агентов и разработчиков. +Перед любой задачей читать [`AGENT.md`](AGENT.md) — руководство для агентов и разработчиков.