Add web administration

This commit is contained in:
Alexey Dudin
2026-11-09 15:42:27 +03:00
parent c778db6208
commit ecad6f183c
16 changed files with 1161 additions and 14 deletions
+39 -7
View File
@@ -25,7 +25,8 @@ site-engine/
├── Makefile Dockerfile # Dockerfile — для M2+ (админка, формы, MCP)
├── docs/ # ТЗ, ревью, журнал решений
├── examples/studio-site/ # сайт-пример из SiteMap.md (услуги, формы, коллекция, редирект)
├── tests/ # 62 теста: значения, разбор, маршруты, сборка, безопасность, запись
├── .env.example # переменные окружения для админки
├── tests/ # 112 тестов: ядро, сборка, безопасность, запись, вход в админку
└── src/site_engine/
├── cli.py # validate · build · preview · fragments
├── errors.py # Issue/Report: код, путь к полю, серьёзность, подсказка
@@ -40,26 +41,57 @@ site-engine/
├── build/pipeline.py # load → validate → render → релиз → атомарный current
├── parsing/ # безопасный YAML, front matter, Markdown (raw HTML выключен)
├── storage/ # safe_join, atomic_write, SiteLock, .engine/history
├── services/ # ContentService (if_match, история, синтаксис), publish; stubs: changeset, auth, forms
├── services/ # auth (вход админа), ContentService (if_match, история), publish; stubs: changeset, forms
├── builtin/ # base.css и 15 фрагментов ядра (ADR-006)
├── db/ # SQLAlchemy-модели служебных таблиц (M2)
├── web/ # FastAPI-фабрика, место для админки htmx (M1–M3)
├── web/ # FastAPI-фабрика; admin/: handlers (вход, выход, обзор), шаблоны, routes-адаптер
└── mcp/ # перечень инструментов MVP (M3)
```
## Вход в админку
Самый простой вариант: **один администратор, без ролей**, логин и хеш пароля задаются переменными окружения, БД для входа не нужна.
```bash
site-engine hash-password # спросит пароль (от 12 символов) и напечатает scrypt-хеш
site-engine gen-secret # ключ подписи сессий
cp .env.example .env # впишите SITE_ADMIN_PASSWORD_HASH и SITE_SECRET_KEY
SITE_COOKIE_SECURE=0 uvicorn site_engine.web.app:create_app --factory --env-file .env # локально по http
```
Без `SITE_ADMIN_PASSWORD_HASH` и `SITE_SECRET_KEY` (не короче 32 символов) `/admin/` не включается вообще: нет пароля — нет входа. После входа `/admin/` показывает страницы сайта со статусами, коллекции и результат проверки (только чтение; редактор — следующий шаг).
| Мера | Как сделано |
|---|---|
| Пароль | scrypt (N=2^15, r=8, p=1), соль на каждый хеш, сравнение за постоянное время |
| Сессия | Подписанная cookie `se_session`: HttpOnly, SameSite=Strict, Secure (выключается только `SITE_COOKIE_SECURE=0`), Path=/admin, срок `SITE_SESSION_HOURS` (по умолчанию 8) |
| Выход | Увеличивает «эпоху» в `.engine/auth_epoch`: все выданные cookie сразу недействительны, в том числе украденные |
| Перебор | 5 неудач за 15 минут блокируют IP (429 + Retry-After), общий порог 30 на все адреса; хеш считается и при неверном логине, поэтому по времени логин не угадать |
| CSRF | POST принимается только с Origin или Referer того же хоста; выход дополнительно требует токен, привязанный к сессии |
| Заголовки | CSP без inline, `frame-ancestors 'none'`, `no-store`, `X-Frame-Options: DENY`, `nosniff` |
| Аудит | `.engine/audit.jsonl`: вход, неудача, блокировка, выход; без паролей и без введённого логина |
Ограничения этого варианта:
- Один пользователь, роль всегда `admin`; таблицы `users` и `api_tokens` из `db/models.py` пока не используются.
- Окно попыток хранится в памяти процесса: при нескольких воркерах у каждого свой счётчик, после перезапуска он обнуляется.
- За обратным прокси `request.client.host` — адрес прокси, поэтому ограничение по IP работает как общее. Доверие к `X-Forwarded-For` нужно включать явно (задача M2).
- Выход завершает все сессии администратора сразу, отдельного списка устройств нет.
- Отдельная смена пароля: сгенерировать новый хеш и перезапустить сервис; чтобы разлогинить всех, поменяйте `SITE_SECRET_KEY`.
## Что реализовано
| Этап | Состояние |
|---|---|
| M0 Контракт и прототип | Готово: формат файлов, модель блоков, load → validate → render, CLI, 15 фрагментов, сайт-пример |
| M1 Публикуемый движок | Частично: маршруты, ссылки, редиректы, sitemap, атомарная публикация, откат (`services/publish.py`), превью страницы через CLI. Нет: превью по токену, 404-страница из коробки, тема |
| M2 Коллекции, заявки, доступ | Частично: коллекции, display templates, запросы, формы (разметка, версия формы в релизе). Нет: приём заявок, outbox, вход и роли, аудит |
| M3 MCP и редактор | `ContentService` с `if_match`, блокировкой и историей готов; нет `patch_page`, changeset, MCP-сервера, админки |
| M2 Коллекции, заявки, доступ | Частично: коллекции, display templates, запросы, формы (разметка, версия формы в релизе), **вход одного администратора с аудитом входов и обзорная страница админки**. Нет: роли, приём заявок, outbox, аудит правок |
| M3 MCP и редактор | `ContentService` с `if_match`, блокировкой и историей готов; нет редактора страниц, `patch_page`, changeset, MCP-сервера |
| M4 | Не начат |
## Что проверено, а что нет
Тесты и сборка примера выполнялись в окружении без сети: ядро (всё, что в `core/`, `build/`, `parsing/`, `storage/`, `services/content.py`) запущено и покрыто 62 тестами. Модули `db/`, `web/`, `mcp/` и `Dockerfile` проверены только компиляцией и чтением: SQLAlchemy, FastAPI и MCP SDK в окружении не было. Ядро намеренно не зависит от pydantic: ошибки должны нести путь к полю (`pages/index.md:regions.main[b_hero].props.title`), а валидация задаётся манифестами фрагментов. Pydantic нужен на границах API (web, mcp).
Тесты и сборка примера выполнялись в окружении без сети: ядро (`core/`, `build/`, `parsing/`, `storage/`, `services/`) и вся логика админки (`web/admin/handlers.py`, шаблоны, вход, CSRF, заголовки) запущены и покрыты 112 тестами. Тонкий FastAPI-адаптер `web/admin/routes.py` проверен на подставном модуле `fastapi`, а `web/app.py`, `db/`, `mcp/` и `Dockerfile` только компиляцией и чтением: FastAPI, SQLAlchemy и MCP SDK в окружении не было. Ядро намеренно не зависит от pydantic: ошибки должны нести путь к полю (`pages/index.md:regions.main[b_hero].props.title`), а валидация задаётся манифестами фрагментов. Pydantic нужен на границах API (web, mcp).
## Соответствие журналу решений
@@ -83,4 +115,4 @@ site-engine/
- Поле `props` в шаблоне — объект `Props`: `props.items` читает поле «items», а не метод словаря.
- `layout.extends` проверяется на существование, наследование шаблонов делается обычным `{% extends 'layout/<id>' %}`.
- CSS и JS собираются в один бандл с хешем в имени; минификации и изоляции по страницам пока нет.
- Нет приёма заявок, входа, MCP и админки: сетевая поверхность записи включается только вместе с контуром «вход, роли, аудит, лимиты» (ADR-006).
- Нет приёма заявок, редактора и MCP: сетевая поверхность записи включается только вместе с контуром «вход, роли, аудит, лимиты» (ADR-006). Вход уже есть, роли и аудит правок будут вместе с редактором.