From 99605b1c779ca872d10d0b30e45e9e6a1fae1876 Mon Sep 17 00:00:00 2001 From: mi Date: Thu, 13 Aug 2026 18:52:42 +0300 Subject: [PATCH] =?UTF-8?q?=D0=A0=D0=B5=D0=B0=D0=BB=D0=B8=D0=B7=D0=BE?= =?UTF-8?q?=D0=B2=D0=B0=D0=BD=D1=8B=20=D1=81=D0=B5=D1=80=D0=B2=D0=B8=D1=81?= =?UTF-8?q?=D1=8B=20=D0=92=D0=9C2=20-=20=D0=BF=D1=80=D0=BE=D0=B2=D0=B5?= =?UTF-8?q?=D1=80=D0=BA=D0=B0=20=D1=81=D0=BE=D0=BE=D0=B1=D1=89=D0=B5=D0=BD?= =?UTF-8?q?=D0=B8=D0=B9=20=D0=B8=20=D1=81=D0=B8=D0=BD=D1=85=D1=80=D0=BE?= =?UTF-8?q?=D0=BD=D0=B8=D0=B7=D0=B0=D1=86=D0=B8=D1=8F=20=D1=81=20=D0=9124?= =?UTF-8?q?=20(=D0=B4=D0=B5=D0=BF=D0=BB=D0=BE=D0=B9=20=D0=B5=D1=89=D0=B5?= =?UTF-8?q?=20=D0=B1=D0=B5=D0=B7=20=D0=BF=D0=B5=D1=80=D0=B5=D0=B2=D0=BE?= =?UTF-8?q?=D0=B4=D0=B0=20=D0=B2=20=D0=B1=D0=BE=D0=B5=D0=B2=D0=BE=D0=B9=20?= =?UTF-8?q?=D1=80=D0=B5=D0=B6=D0=B8=D0=BC)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitattributes | 3 + architectory/README.md | 27 +- architectory/arch-00-glossary.md | 18 +- architectory/arch-01-system-architecture.md | 124 +- architectory/arch-02-api-contracts.md | 73 +- .../arch-03-docker-compose-blueprint.md | 308 +++-- architectory/arch-04-settings-and-content.md | 176 ++- .../arch-05-agent-development-process.md | 21 +- .../arch-06-service-hosting-security.md | 576 +++++++++ backlog.md | 142 +-- codebase/README.md | 12 +- codebase/Signoz/docs/BACKEND_OTLP.md | 11 +- codebase/Signoz/docs/NETWORK.md | 6 +- codebase/backend/api-backend/README.md | 11 +- .../versions/0011_module07_contract.py | 188 +++ .../versions/0012_safety_v2_checkpoint.py | 74 ++ codebase/backend/api-backend/app/db.py | 81 +- .../backend/api-backend/app/integrations.py | 137 ++- codebase/backend/api-backend/app/main.py | 17 +- .../api-backend/app/notification_models.py | 7 +- .../api-backend/app/notification_service.py | 33 +- codebase/backend/api-backend/app/services.py | 44 +- codebase/backend/api-backend/app/settings.py | 16 +- codebase/backend/api-backend/app/workers.py | 84 +- .../backend/api-backend/docker-compose.yml | 7 + .../tests/contract/test_clients.py | 80 +- .../backend/deployment/DEPLOYMENT_GUIDE.ru.md | 8 +- codebase/backend/deployment/RUNBOOK.md | 84 ++ .../deployment/docker-compose.jobs.yml | 5 +- .../seed-personal-notifications-test.sh | 3 + .../backend/infra/compose/application.yml | 8 +- codebase/services/.env.example | 42 + codebase/services/.gitignore | 7 + codebase/services/bitrix-sync/.env.example | 16 + codebase/services/bitrix-sync/Dockerfile | 18 + codebase/services/bitrix-sync/README.md | 72 ++ codebase/services/bitrix-sync/alembic.ini | 30 + codebase/services/bitrix-sync/alembic/env.py | 58 + .../versions/0000_legacy_sync_baseline.py | 20 + .../alembic/versions/0001_bitrix_sync_full.py | 356 ++++++ .../versions/0002_app_queue_contract.py | 85 ++ codebase/services/bitrix-sync/app/__init__.py | 1 + codebase/services/bitrix-sync/app/config.py | 137 +++ codebase/services/bitrix-sync/app/crm.py | 185 +++ codebase/services/bitrix-sync/app/domain.py | 106 ++ codebase/services/bitrix-sync/app/engine.py | 629 ++++++++++ codebase/services/bitrix-sync/app/main.py | 173 +++ codebase/services/bitrix-sync/app/mapping.py | 56 + .../bitrix-sync/app/reconciliation.py | 139 +++ .../services/bitrix-sync/app/repository.py | 533 ++++++++ codebase/services/bitrix-sync/app/security.py | 120 ++ codebase/services/bitrix-sync/app/worker.py | 78 ++ .../bitrix-sync/compose.fragment.yaml | 83 ++ codebase/services/bitrix-sync/openapi.yaml | 121 ++ codebase/services/bitrix-sync/pyproject.toml | 50 + .../services/bitrix-sync/tests/conftest.py | 25 + .../services/bitrix-sync/tests/test_config.py | 77 ++ .../services/bitrix-sync/tests/test_crm.py | 48 + .../services/bitrix-sync/tests/test_domain.py | 57 + .../tests/test_engine_boundaries.py | 72 ++ .../tests/test_webhook_security.py | 62 + codebase/services/deployment/RUNBOOK.md | 130 ++ codebase/services/deployment/RUNBOOK.ru.md | 821 +++++++++++++ .../deploy-message-safety-mode.sudoers | 3 + .../deployment/han-message-safety-mode | 114 ++ .../deployment/han-processing.service | 31 + codebase/services/deployment/preflight.sh | 192 +++ .../services/deployment/scripts/setup-vm.sh | 762 ++++++++++++ .../scripts/ssl-renew-deploy-hook.sh | 37 + .../deployment/secrets/config.example.json | 95 ++ .../services/deployment/secrets/han-compose | 10 + .../services/deployment/secrets/han-secrets | 114 ++ .../secrets/han-secrets-vm2.service | 41 + .../deployment/secrets/secrets_loader.py | 316 +++++ codebase/services/docker-compose.yml | 465 +++++++ codebase/services/message-safety/Dockerfile | 22 + codebase/services/message-safety/README.md | 59 + codebase/services/message-safety/alembic.ini | 30 + .../services/message-safety/alembic/env.py | 50 + .../versions/0001_message_safety_v2.py | 63 + .../services/message-safety/app/__init__.py | 1 + .../services/message-safety/app/adapters.py | 75 ++ codebase/services/message-safety/app/api.py | 235 ++++ .../app/artifacts/config.schema.json | 63 + .../app/artifacts/detector-manifest.json | 27 + .../rules/rules-2026-01-01/rules.yaml | 35 + .../app/artifacts/rules/rules.schema.json | 29 + .../app/artifacts/seed-config.yaml | 30 + .../services/message-safety/app/config.py | 51 + .../message-safety/app/config_admin.py | 111 ++ .../services/message-safety/app/contracts.py | 81 ++ codebase/services/message-safety/app/db.py | 271 ++++ .../message-safety/app/file_pipeline.py | 171 +++ .../message-safety/app/fingerprint.py | 41 + .../services/message-safety/app/hot_cache.py | 35 + codebase/services/message-safety/app/main.py | 71 ++ .../message-safety/app/normalization.py | 53 + .../services/message-safety/app/rate_limit.py | 37 + .../services/message-safety/app/repository.py | 325 +++++ codebase/services/message-safety/app/rules.py | 57 + .../services/message-safety/app/service.py | 367 ++++++ .../services/message-safety/app/settings.py | 88 ++ .../services/message-safety/app/url_policy.py | 107 ++ .../services/message-safety/app/worker.py | 173 +++ .../docker-compose.fragment.yml | 58 + .../services/message-safety/entrypoint.sh | 24 + codebase/services/message-safety/openapi.yaml | 161 +++ .../services/message-safety/pyproject.toml | 48 + .../services/message-safety/tests/conftest.py | 20 + .../message-safety/tests/test_api_contract.py | 190 +++ .../tests/test_config_and_schema.py | 76 ++ .../message-safety/tests/test_determinism.py | 40 + .../message-safety/tests/test_files.py | 73 ++ .../message-safety/tests/test_openapi.py | 29 + .../tests/test_rules_and_urls.py | 63 + .../allowlists/bitrix-webhook-allowlist.conf | 2 + .../bitrix-webhook-allowlist.conf.template | 5 + .../allowlists/private-caller-allowlist.conf | 3 + .../private-caller-allowlist.conf.template | 4 + .../nginx/allowlists/proxy-common.conf | 14 + codebase/services/nginx/allowlists/tls.conf | 5 + codebase/services/nginx/nginx.conf | 33 + .../nginx/templates/10-vm2.conf.template | 131 ++ .../observability/otel-collector.yaml | 76 ++ .../services/redis/redis-safety.acl.template | 5 + codebase/services/redis/redis.conf | 20 + faq.md | 20 +- .../chat-requirements.md | 50 +- .../notification-requirements.md | 6 +- .../user-requirements.md | 19 +- modules/Untitled | 1 + modules/module-01-api-backend.md | 109 +- modules/module-02-frontend-test-site.md | 12 +- modules/module-03-nginx.md | 62 +- modules/module-04-redis.md | 57 +- modules/module-05-message-safety.md | 761 +++++++++--- modules/module-06-bitrix-local-app.md | 2 +- modules/module-07-bitrix-sync.md | 1091 +++++++++++------ modules/module-09-observability.md | 29 +- modules/module-10-deployment-runbook.md | 264 ++-- modules/sync-service-concept.md | 140 +++ ops-monitoring/instructions.md | 20 +- ops-monitoring/Обновление clamav образа.md | 70 ++ releases/#1.1 VM-service-deploy.md | 893 ++++++++++++++ 144 files changed, 15295 insertions(+), 1120 deletions(-) create mode 100644 .gitattributes create mode 100644 architectory/arch-06-service-hosting-security.md create mode 100644 codebase/backend/api-backend/alembic/versions/0011_module07_contract.py create mode 100644 codebase/backend/api-backend/alembic/versions/0012_safety_v2_checkpoint.py create mode 100644 codebase/services/.env.example create mode 100644 codebase/services/.gitignore create mode 100644 codebase/services/bitrix-sync/.env.example create mode 100644 codebase/services/bitrix-sync/Dockerfile create mode 100644 codebase/services/bitrix-sync/README.md create mode 100644 codebase/services/bitrix-sync/alembic.ini create mode 100644 codebase/services/bitrix-sync/alembic/env.py create mode 100644 codebase/services/bitrix-sync/alembic/versions/0000_legacy_sync_baseline.py create mode 100644 codebase/services/bitrix-sync/alembic/versions/0001_bitrix_sync_full.py create mode 100644 codebase/services/bitrix-sync/alembic/versions/0002_app_queue_contract.py create mode 100644 codebase/services/bitrix-sync/app/__init__.py create mode 100644 codebase/services/bitrix-sync/app/config.py create mode 100644 codebase/services/bitrix-sync/app/crm.py create mode 100644 codebase/services/bitrix-sync/app/domain.py create mode 100644 codebase/services/bitrix-sync/app/engine.py create mode 100644 codebase/services/bitrix-sync/app/main.py create mode 100644 codebase/services/bitrix-sync/app/mapping.py create mode 100644 codebase/services/bitrix-sync/app/reconciliation.py create mode 100644 codebase/services/bitrix-sync/app/repository.py create mode 100644 codebase/services/bitrix-sync/app/security.py create mode 100644 codebase/services/bitrix-sync/app/worker.py create mode 100644 codebase/services/bitrix-sync/compose.fragment.yaml create mode 100644 codebase/services/bitrix-sync/openapi.yaml create mode 100644 codebase/services/bitrix-sync/pyproject.toml create mode 100644 codebase/services/bitrix-sync/tests/conftest.py create mode 100644 codebase/services/bitrix-sync/tests/test_config.py create mode 100644 codebase/services/bitrix-sync/tests/test_crm.py create mode 100644 codebase/services/bitrix-sync/tests/test_domain.py create mode 100644 codebase/services/bitrix-sync/tests/test_engine_boundaries.py create mode 100644 codebase/services/bitrix-sync/tests/test_webhook_security.py create mode 100644 codebase/services/deployment/RUNBOOK.md create mode 100644 codebase/services/deployment/RUNBOOK.ru.md create mode 100644 codebase/services/deployment/deploy-message-safety-mode.sudoers create mode 100644 codebase/services/deployment/han-message-safety-mode create mode 100644 codebase/services/deployment/han-processing.service create mode 100644 codebase/services/deployment/preflight.sh create mode 100644 codebase/services/deployment/scripts/setup-vm.sh create mode 100644 codebase/services/deployment/scripts/ssl-renew-deploy-hook.sh create mode 100644 codebase/services/deployment/secrets/config.example.json create mode 100644 codebase/services/deployment/secrets/han-compose create mode 100644 codebase/services/deployment/secrets/han-secrets create mode 100644 codebase/services/deployment/secrets/han-secrets-vm2.service create mode 100644 codebase/services/deployment/secrets/secrets_loader.py create mode 100644 codebase/services/docker-compose.yml create mode 100644 codebase/services/message-safety/Dockerfile create mode 100644 codebase/services/message-safety/README.md create mode 100644 codebase/services/message-safety/alembic.ini create mode 100644 codebase/services/message-safety/alembic/env.py create mode 100644 codebase/services/message-safety/alembic/versions/0001_message_safety_v2.py create mode 100644 codebase/services/message-safety/app/__init__.py create mode 100644 codebase/services/message-safety/app/adapters.py create mode 100644 codebase/services/message-safety/app/api.py create mode 100644 codebase/services/message-safety/app/artifacts/config.schema.json create mode 100644 codebase/services/message-safety/app/artifacts/detector-manifest.json create mode 100644 codebase/services/message-safety/app/artifacts/rules/rules-2026-01-01/rules.yaml create mode 100644 codebase/services/message-safety/app/artifacts/rules/rules.schema.json create mode 100644 codebase/services/message-safety/app/artifacts/seed-config.yaml create mode 100644 codebase/services/message-safety/app/config.py create mode 100644 codebase/services/message-safety/app/config_admin.py create mode 100644 codebase/services/message-safety/app/contracts.py create mode 100644 codebase/services/message-safety/app/db.py create mode 100644 codebase/services/message-safety/app/file_pipeline.py create mode 100644 codebase/services/message-safety/app/fingerprint.py create mode 100644 codebase/services/message-safety/app/hot_cache.py create mode 100644 codebase/services/message-safety/app/main.py create mode 100644 codebase/services/message-safety/app/normalization.py create mode 100644 codebase/services/message-safety/app/rate_limit.py create mode 100644 codebase/services/message-safety/app/repository.py create mode 100644 codebase/services/message-safety/app/rules.py create mode 100644 codebase/services/message-safety/app/service.py create mode 100644 codebase/services/message-safety/app/settings.py create mode 100644 codebase/services/message-safety/app/url_policy.py create mode 100644 codebase/services/message-safety/app/worker.py create mode 100644 codebase/services/message-safety/docker-compose.fragment.yml create mode 100644 codebase/services/message-safety/entrypoint.sh create mode 100644 codebase/services/message-safety/openapi.yaml create mode 100644 codebase/services/message-safety/pyproject.toml create mode 100644 codebase/services/message-safety/tests/conftest.py create mode 100644 codebase/services/message-safety/tests/test_api_contract.py create mode 100644 codebase/services/message-safety/tests/test_config_and_schema.py create mode 100644 codebase/services/message-safety/tests/test_determinism.py create mode 100644 codebase/services/message-safety/tests/test_files.py create mode 100644 codebase/services/message-safety/tests/test_openapi.py create mode 100644 codebase/services/message-safety/tests/test_rules_and_urls.py create mode 100644 codebase/services/nginx/allowlists/bitrix-webhook-allowlist.conf create mode 100644 codebase/services/nginx/allowlists/bitrix-webhook-allowlist.conf.template create mode 100644 codebase/services/nginx/allowlists/private-caller-allowlist.conf create mode 100644 codebase/services/nginx/allowlists/private-caller-allowlist.conf.template create mode 100644 codebase/services/nginx/allowlists/proxy-common.conf create mode 100644 codebase/services/nginx/allowlists/tls.conf create mode 100644 codebase/services/nginx/nginx.conf create mode 100644 codebase/services/nginx/templates/10-vm2.conf.template create mode 100644 codebase/services/observability/otel-collector.yaml create mode 100644 codebase/services/redis/redis-safety.acl.template create mode 100644 codebase/services/redis/redis.conf create mode 100644 modules/Untitled create mode 100644 modules/sync-service-concept.md create mode 100644 ops-monitoring/Обновление clamav образа.md create mode 100644 releases/#1.1 VM-service-deploy.md diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..886d9ff --- /dev/null +++ b/.gitattributes @@ -0,0 +1,3 @@ +*.sh text eol=lf +codebase/services/deployment/secrets/han-compose text eol=lf +codebase/services/deployment/han-message-safety-mode text eol=lf diff --git a/architectory/README.md b/architectory/README.md index 5b1b649..841f7e2 100644 --- a/architectory/README.md +++ b/architectory/README.md @@ -14,13 +14,14 @@ | [`arch-03-docker-compose-blueprint.md`](arch-03-docker-compose-blueprint.md) | Требования к Docker Compose, nginx, сетям, TLS и rate limits | | [`arch-04-settings-and-content.md`](arch-04-settings-and-content.md) | `.env` (infra), таблица `app_settings`, значения service-token переменных, типы файлов | | [`arch-05-agent-development-process.md`](arch-05-agent-development-process.md) | Правила разработки модулей отдельными агентами | +| [`arch-06-service-hosting-security.md`](arch-06-service-hosting-security.md) | Безопасность VM и деплоя: OS-роли, SSH, sudo/systemd, секреты, контейнеры, сеть и lockdown | ## Как читать 1. Начните с **arch-01** — общая картина и зафиксированные решения MVP. -2. При работе с API — **arch-02**; при деплое — **arch-03**; при настройках — **arch-04**. +2. При работе с API — **arch-02**; с Compose/nginx — **arch-03**; с настройками — **arch-04**; с VM, SSH, правами деплоя, секретами и host/container hardening — **arch-06**. 3. Спорные **имена** полей, id, enum, бакетов и базовая семантика enum/lifecycle — **arch-00**. Лимиты и правила реализации остаются в профильных arch-*. -4. Перед разработкой модуля — **arch-05** и релевантные разделы arch-01/arch-02. +4. Перед разработкой модуля — **arch-05**, релевантные разделы arch-01/arch-02 и arch-06, если меняются deployment, сети, volumes, capabilities или секреты. ## Приоритет документов @@ -29,9 +30,10 @@ 1. **arch-00** — **имена и базовая семантика** (поля, id, enum, бакеты, env, смысл статусов); не бизнес-лимиты и не детальная реализация. 2. **arch-01** — границы сервисов, сценарии, sync, безопасность. 3. **arch-02** — HTTP-контракты и направление вызовов. -4. **arch-03** — инфраструктура и nginx. -5. **arch-04** — env, `app_settings`, публичные DTO. -6. **arch-05** — процесс разработки. +4. **arch-06** — безопасность размещения на VM, OS-роли, SSH, secrets delivery, host/container hardening и production-деплой. +5. **arch-03** — Compose, сети контейнеров, nginx и TLS. +6. **arch-04** — non-secret env, secret references, `app_settings`, публичные DTO. +7. **arch-05** — процесс разработки. Профильные спецификации модулей уточняют реализацию внутри этих границ. Если границы не позволяют эффективно реализовать модуль, то агент, разрабатывающий модуль, может предложить внести изменения в архитектуру. @@ -41,6 +43,7 @@ - Endpoint или auth → **arch-02**, при необходимости arch-01/arch-03. - Новая интеграция → сначала **arch-02**. - Compose, nginx, TLS → **arch-03**. +- VM, SSH, sudo, systemd-деплой, secret delivery, container/host hardening → **arch-06**, затем синхронизация arch-03/arch-04 и runbook. ## В бэклоге (не MVP) @@ -48,7 +51,14 @@ |---|---| | Доставка документов компании из Bitrix24 в приложение (`bitrix-sync` → `api-backend`, уведомление клиента) | [`!Backlog.md`](../../HAN_chat/!Backlog.md), п. 9; arch-01 — заглушка UI «Документы» | | Интеграция с SMS-провайдерами (отправка OTP, отключение `KEYCLOAK_OTP_MOCK_*`) | Спецификация: [`module-11-idgtl-sms.md`](../modules/module-11-idgtl-sms.md) (доставка через Direct SMS API; проверка OTP — локально в Keycloak) | -| Изоляция `bitrix-sync` на отдельную VM | [`!Backlog.md`](../../HAN_chat/!Backlog.md), п. 8 | + +## Каноническое размещение production-контуров + +- **ВМ1 HAN Chat** — самостоятельная публичная точка входа приложения: nginx, `api-backend`, Keycloak, `bitrix-local-app`, SMS-контур, Redis DB0/DB1 и локальный OTEL Collector. +- **ВМ2 Processing** — самостоятельная service VM с отдельным public webhook host, private Message Safety ingress и постоянным ограниченным egress: `message-safety`, `bitrix-sync`, `clamd`/`freshclam`, отдельный Redis Safety, nginx и локальный OTEL Collector. +- На каждой VM действует один root Compose project и отдельный root-owned systemd deployment unit. «Единый Compose» означает один проект **на VM**, а не один общий project через несколько хостов. +- Bitrix24 вызывает CRM webhook напрямую на nginx ВМ2; ВМ1 в route не участвует. ВМ1 вызывает только Message Safety по private HTTPS. +- При росте нагрузки `bitrix-sync` может быть перенесён на ВМ3 без изменения API и границ схем PostgreSQL. ## Открытые пробелы @@ -56,15 +66,16 @@ | # | Пробел | Статус | |---|---|---| | G8 | Явный список `is_public=true` для ключей `app_settings` | Отложить до оформления сервисов; seed в модуле `database` | -| G9 | GRANT-модель `bitrix_sync_user` на `han_app`: таблицы, колонки, read/write границы | Уточнить в спецификации `database` и `bitrix-sync` | +| G9 | GRANT-модель `bitrix_sync_user` на `han_app`: таблицы, колонки, read/write границы | Закрыто в `module-07-bitrix-sync.md` §13; точный SQL реализуется migrations и проходит negative permission tests | | G10 | Полный DTO `GET /api/v1/public/app-config` и мэппинг `setting_key → response field` | Уточнить при оформлении OpenAPI `api-backend` | | G11 | Версионирование API/WS: deprecation policy, срок поддержки v1, `ws_protocol_version` | Уточнить перед публичным релизом API | | G12 | Масштабирование realtime: Redis Pub/Sub, sticky sessions, backpressure при нескольких репликах `api-backend` | Post-MVP / перед горизонтальным масштабированием | -| G13 | Contract tests между `api-backend`, `message-safety`, `bitrix-local-app`, `bitrix-sync` | Добавить в DoD модулей после появления OpenAPI | +| G13 | Contract tests между `api-backend`, `message-safety`, `bitrix-local-app`, `bitrix-sync` | Контракт sync зафиксирован в module-07 §18; общий межсервисный gate остаётся до появления всех OpenAPI | ## Обновление документации - Изменение MVP → arch-01 + arch-02 (+ arch-03/arch-04 при необходимости). - Новый env или ключ `app_settings` → arch-04. +- Новая VM, изменение сетевой доступности, прав `deploy`, sudo/systemd, capabilities, volumes или способа доставки секретов → arch-06 (+ arch-03/arch-04 и deployment runbook). - Новый термин / enum → arch-00, затем поиск по arch-*. - Закрытие пробела → убрать из «Открытые пробелы» и отразить решение в arch-*. diff --git a/architectory/arch-00-glossary.md b/architectory/arch-00-glossary.md index 5419827..48658de 100644 --- a/architectory/arch-00-glossary.md +++ b/architectory/arch-00-glossary.md @@ -27,9 +27,8 @@ | `Dialog` | `han_app` | Диалог клиента с Open Lines | | `Message` | `han_app` | Сообщение в диалоге | | `MessageAttachment` | `han_app` | Вложение к сообщению | -| `sync_queue` | `han_app` | Очередь sync App → Bitrix24 | +| `sync_queue` | `han_app` | Durable очередь бизнес-намерений App → Bitrix24 с lease/fencing | | `safety_tasks` | `han_app` | Checkpoint sync-wait Message Safety (`task_id`) для recovery | -| `entity_external_mapping` | `han_app` | Маппинг App entity ↔ Bitrix entity | | `app_settings` | `han_app` | Бизнес-настройки | | `text_resources` | `han_app` | Тексты UI по мнемоникам | | `popular_questions` | `han_app` | Популярные вопросы главного экрана | @@ -39,6 +38,10 @@ | `NotificationSource` | `han_app` | Продюсер Internal Notifications API; хранит hash индивидуального токена, не секрет | | `ClientDocument` | `han_app` | Отправленный клиентом проверенный документ; создаёт `document.client_uploaded` в `sync_queue` | | `dialog_sessions` | `bitrix_local` | Маппинг чата Open Lines | +| `entity_external_mapping` | `bitrix_sync` | Каноническая active/closed/broken история `user_id` ↔ Bitrix Contact | +| `workflow_instances` / `crm_commands` | `bitrix_sync` | Persisted сценарии CRM sync и конкретные Bitrix batch subcommands | +| `webhook_inbox` | `bitrix_sync` | Durable inbox событий Contact/smart process от Битрикс24 | +| `business_alerts` | `bitrix_sync` | Локальное состояние конфликтов, связанных со smart process Битрикс24 | | `sms_template` | `sms` | Версионируемый согласованный SMS-шаблон; active-версия уникальна для `code`+`channel`+`locale` | | `sms_setting` | `sms` | Технические runtime-настройки `sms-service`, не секреты и не OTP product settings | | `sms_outbound_message` | `sms` | Бессрочный журнал заказа, отправки и доставки SMS; источник истины provider status | @@ -53,7 +56,7 @@ | `phone_number` | Auth-телефон пользователя; master — Keycloak; в App DB пишется из JWT claims при `bootstrap`, не из body клиента | | `guest_session_id` | Опциональный локальный UUID на устройстве (UI); **не** auth и **не** открывает write API | | `ux_session_id` | UUID **аналитической UX-сессии**; заголовок `X-Ux-Session-Id` | -| `bitrix_contact_id` | ID Contact в Bitrix24 CRM | +| `b24_id` | ID Contact в Bitrix24 CRM; хранится только в schema `bitrix_sync` | | `bitrix_chat_id` | ID чата Open Lines в Bitrix24 | | `session_id` | ID сессии Open Lines (поле `dialog_sessions`; не путать с `ux_session_id`) | | `task_id` | ID async-проверки Message Safety | @@ -111,11 +114,13 @@ |---|---| | `Message.sender_type` | `client`, `company` | | `Message.safety_status` | `pending`, `allowed`, `blocked` (`needs_review` — зарезервирован, MVP не используется) | +| `Message.safety_processing_mode` | `standard`, `mock`; internal/audit field, не public DTO | +| `Message.safety_config_version` | версия service-owned Message Safety config, internal/audit field | | `Message.delivery_status` | `accepted`, `processing`, `delivered`, `rejected`, `failed` | | `Message.text` | текст сообщения; пустая строка для файлового сообщения | | `content_kind` (логическое) | `text`, `file` — тип исходящего сообщения клиента (MVP) | -Семантика `allow` / `deny` / `pending` в `message-safety` и HTTP-коды — [`arch-02-api-contracts.md`](arch-02-api-contracts.md). +Семантика `allow` / `deny` / `pending` в target Message Safety v2: `200` / `403` / `202 Accepted`; internal `202` скрыт api-backend от public API. `/internal/safety/v1/*`, `203` и `stub_final_error` — только legacy test stub до cutover. Полный контракт — [`arch-02-api-contracts.md`](arch-02-api-contracts.md). ### `Message.delivery_status` (смысл) @@ -135,6 +140,7 @@ Realtime-событие `message.status` передаёт актуальные ` |---|---| | `pending` | Файл в S3-quarantine, проверка не завершена | | `clean` | Проверка завершена, allow | +| `bypassed` | Forced allow в emergency MOCK; файл не проверялся | | `infected` | Проверка завершена, deny | | `failed` | Ошибка инфраструктуры проверки | @@ -152,7 +158,7 @@ Realtime-событие `message.status` передаёт актуальные ` ## Мнемоники internal API -Префикс: **`/internal/{service_mnemonic}/v1/`**. Health: **`/health/*`**. +Default-префикс: **`/internal/{service_mnemonic}/v1/`**. Approved exception: target Message Safety использует **`/internal/safety/v2/`**; `/v1` остаётся legacy stub до cutover. Health: **`/health/*`**. | `{service_mnemonic}` | Сервис | |---|---| @@ -163,6 +169,8 @@ Realtime-событие `message.status` передаёт актуальные ` | `sms` | `sms-service`; durable order/read API во внутренней сети | | `notifications` | Internal Create/Cancel уведомлений на `api-backend`; токен отдельный для каждого `source` | +Public safety deny: internal `403 reason_code=message_blocked` → public `422 message_blocked`; `rule_id` не раскрывается. Generic company-текст берётся из `text_resources` по мнемонике `safety.chat.blocked`. + ## Жизненный цикл уведомления - `lifecycle_status`: `active` / `closed`; бизнес-завершение, не soft delete. diff --git a/architectory/arch-01-system-architecture.md b/architectory/arch-01-system-architecture.md index 57ff18e..e285678 100644 --- a/architectory/arch-01-system-architecture.md +++ b/architectory/arch-01-system-architecture.md @@ -2,6 +2,7 @@ > Термины — в [`arch-00-glossary.md`](arch-00-glossary.md). > Приоритет документов — в [`README.md`](README.md). +> Безопасность размещения на VM, OS-роли, SSH, секреты и production-деплой — в [`arch-06-service-hosting-security.md`](arch-06-service-hosting-security.md). ## Назначение @@ -47,8 +48,8 @@ HAN Chat - приложение для мигрантов, где стартов - SMS Service: internal durable order API, шаблоны и бессрочный журнал SMS; отдельный worker вызывает i-Digital Direct, callback обновляет только журнал. - api-backend: Python-приложение с REST API, realtime-доставкой сообщений и бизнес-логикой. - Notification producers: сервисы приватной сети, создающие/отменяющие персональные уведомления через Internal API с отдельным Bearer token на `source`; `producer_test` используется только для smoke API. -- Nginx Reverse Proxy: единая публичная точка входа, HTTPS termination и маршрутизация на Keycloak/API/frontend web/Bitrix24. -- Message Safety Service: отдельный сервис проверки входящих сообщений; вызов из API → `200 allow` | `403 deny` | `203 pending` + `task_id` (при `203` api-backend синхронно поллит task до финального вердикта, без очереди анализа на api-backend). +- Nginx Reverse Proxy: независимые точки входа ВМ1 и ВМ2; ВМ1 обслуживает приложение/Open Lines, ВМ2 — CRM webhook `bitrix-sync` и private Message Safety API. +- Message Safety Service: отдельный сервис ВМ2 проверки исходящих сообщений; target v2 → `200 allow` | `403 deny` | `202 pending` + `Location`. - Bitrix24 Local App: локальное приложение, custom connector `han_mobile_app` для Bitrix24 Open Lines: чат, OAuth, webhook-события, маппинг `dialog_id` ↔ `bitrix_chat_id`. - Bitrix24 sync service: двусторонняя синхронизация App DB ↔ Битрикс24 CRM (Contact на MVP; маппинг ID, очередь через триггеры, webhook от роботов Bitrix24). - Managed PostgreSQL (приватная сеть, одна база): схемы `han_app`, `bitrix_sync`, `bitrix_local`, `keycloak`, `message_safety`, `sms` — отдельный DB-user на схему. @@ -59,26 +60,50 @@ HAN Chat - приложение для мигрантов, где стартов ## Инфраструктура развёртывания (зафиксировано) -На первом этапе весь backend-контур работает на **одной VM** в облаке провайдера: +Production-like backend разделён на два контура в одной private network/VPC: -- `nginx`, `api-backend`, `message-safety`, `keycloak`, `sms-service`/worker, `bitrix-sync`, `bitrix-local-app`, `redis`, `otel-collector` — в Docker Compose на VM; -- публичный доступ из интернета только через `nginx` (порты 80/443); -- внутренние сервисы общаются по Docker-сети на localhost VM. +- **ВМ1 HAN Chat**: edge `nginx`, `api-backend`, `keycloak`, `sms-service`/worker, `bitrix-local-app`, Redis DB0/DB1 и локальный `otel-collector`; +- **ВМ2 Processing**: собственный public/private `nginx`, `message-safety` API/worker, `clamd`/`freshclam`, `bitrix-sync`, отдельный Redis Safety и локальный `otel-collector`; +- каждая VM имеет один root Compose project и отдельный root-owned systemd deployment unit; +- ВМ1 и ВМ2 имеют независимые public DNS/TLS ingress на своих nginx; ВМ2 публикует только exact CRM webhook; +- ВМ1 вызывает ВМ2 по private HTTPS с проверкой internal CA, service token, cloud SG и host firewall; +- Битрикс24 вызывает public nginx ВМ2 напрямую; CRM webhook не проходит через ВМ1 и не создаёт на ней трафик/зависимость. + +ВМ2 является независимым контуром вспомогательных сервисов. При её недоступности отправка пользовательских сообщений и CRM sync приостанавливаются, но чтение истории, auth, realtime и приём сообщений оператора на ВМ1 продолжаются. Недоступность ВМ1 не мешает ВМ2 принимать CRM webhook и выполнять накопленные workflows. Fail-open для Message Safety запрещён. Базы данных — **managed PostgreSQL** того же провайдера в **том же облачном кластере/VPC**, **без публичного доступа** из интернета. VM подключается к БД только по приватной сети. +Размещение нескольких сервисов на одной VM не делает их одним доверенным контуром. Для каждого контейнера сохраняются least privilege, отдельные секреты, минимальные Docker networks и запрет доступа к Docker socket/host root. Обязательный baseline VM и контейнеров — [`arch-06-service-hosting-security.md`](arch-06-service-hosting-security.md). + Схема данных в managed PostgreSQL (перечень таблиц внутри схем — в модульных спецификациях, не в arch-*): | База / схема | Сервисы | Назначение схемы | |---|---|---| | одна база / `han_app` | `api-backend`, `bitrix-sync` (ограниченный GRANT) | прикладные данные приложения, очередь sync, audit | | одна база / `bitrix_sync` | `bitrix-sync` | worker state, retry/dead letter, sync audit | -| одна база / `message_safety` | `message-safety` | verdict cache, safety_task, rule config | +| одна база / `message_safety` | `message-safety` | verdict caches, safety tasks/audit, immutable versioned runtime config | | одна база / `bitrix_local` | `bitrix-local-app` | OAuth, inbox, `dialog_sessions` | | одна база / `keycloak` | Keycloak | учётные записи, realm, сессии IdP | | одна база / `sms` | `sms-service`, `sms-worker` | шаблоны, runtime settings, бессрочный журнал отправки/доставки SMS | -Redis на первом этапе остаётся на VM в Docker (ephemeral/coordination). Selectel S3 — внешнее object storage: три бакета (`han-chat-quarantine`, `han-chat-attachments`, `han-chat-documents`); см. [`arch-00-glossary.md`](arch-00-glossary.md). +Redis разделён по deployment boundary: DB0/DB1 остаются на ВМ1, отдельный Redis Safety находится на ВМ2. Оба являются ephemeral/coordination слоями; PostgreSQL остаётся durable source of truth. Selectel S3 — внешнее object storage: три бакета (`han-chat-quarantine`, `han-chat-attachments`, `han-chat-documents`); см. [`arch-00-glossary.md`](arch-00-glossary.md). + +```mermaid +flowchart LR + client[Client] --> edge[VM1_EdgeNginx] + edge --> api[VM1_ApiBackend] + bitrix[Bitrix24] -->|"CRM webhook HTTPS"| publicGateway[VM2_PublicNginx] + publicGateway --> sync[BitrixSync] + api -->|"HTTPS 8443 + service token"| privateGateway[VM2_PrivateListener] + privateGateway --> safety[MessageSafetyApi] + safety --> worker[SafetyWorker] + worker --> clamd[Clamd] + worker --> s3q[S3Quarantine] + worker --> pg[ManagedPostgreSQL] + sync --> pg + sync --> bitrix + collector[VM2_OtelCollector] --> signoz[PrivateSigNoz] +``` ## Контекстная схема @@ -179,10 +204,10 @@ Frontend не должен: - хранение истории диалогов; - запись данных профиля в App DB (синхронизация с Bitrix24 — триггеры → `sync_queue` → `bitrix-sync`, без участия api-backend); - выдачу **presigned URL** на загрузку в S3-quarantine, проверку объекта при `complete`, promote/delete после вердикта; -- синхронный вызов Message Safety Service (`POST /internal/safety/v1/messages/check`) и интерпретацию ответа: `200 allow`, `403 deny`, `203 pending` + `task_id`; +- вызов Message Safety v2 (`POST /internal/safety/v2/messages/check`) и интерпретацию `200 allow`, `403 deny`, `202 pending`; - при `200`: перенос файлов quarantine → S3-data, сохранение сообщения, отправка в Bitrix24; - при `403`: удаление файлов из quarantine, безопасный ответ клиенту; -- при `203`: api-backend **синхронно поллит** `GET /internal/safety/v1/messages/tasks/{task_id}` до финального `200`/`403` (timeout budget — arch-04), затем promote/Bitrix или cleanup, и только после этого отвечает клиенту финальным результатом; +- при `202`: api-backend **синхронно поллит** `Location` до финального `200`/`403`, terminal failed или timeout, затем promote/Bitrix или cleanup; - это **ожидание в рамках одного клиентского HTTP-соединения**, а не общая очередь: другие запросы обрабатываются параллельно (workers/async); - решение «быстрая проверка / долгая» принимает только `message-safety`; на api-backend **нет** очереди анализа сообщений; - запись checkpoint в `safety_tasks` (App DB) на время poll — для recovery при timeout/crash (I1); @@ -218,13 +243,15 @@ Frontend не должен: ### Bitrix24 sync service -Отвечает за **двустороннюю** синхронизацию данных между App DB и Битрикс24 CRM: +Отвечает за асинхронную двустороннюю синхронизацию данных между App DB и Битрикс24 CRM по контракту [`../modules/module-07-bitrix-sync.md`](../modules/module-07-bitrix-sync.md): -- **маппинг ID** сущностей приложения ↔ Bitrix24 (`bitrix_contact_id`, `entity_external_mapping`); -- **App DB → Bitrix24:** обработка очереди `sync_queue` (триггеры App DB) — map/create Contact по телефону, push обновлений полей; -- **Bitrix24 → App DB:** приём webhook от роботов Bitrix24, обновление профиля с GUC `han.sync_suppress`; -- реестр синхронизируемых сущностей (MVP: Contact; post-MVP: Lead, Deal, Document); -- повторные попытки, rate limiting Bitrix REST, dead letter; +- **канонический mapping** и его историю в `bitrix_sync.entity_external_mapping`; App DB не хранит CRM Contact ID; +- **App DB → Bitrix24:** durable workflow для `contact.map_or_create`, `contact.update`, `contact.deactivate`; +- **исправление связи:** audited административный запрос запускает `contact.rebind`; прямой `UPDATE` mapping запрещён; +- **Bitrix24 → App DB:** durable webhook inbox, coalescing и reconciliation; запись профиля с transaction-local GUC `han.sync_suppress`; +- mastership по полям: телефон — App/Keycloak, `NAME`/citizenship/email — Битрикс24; +- batch, общий portal rate limiter, leases/fencing, retry до 24 часов и technical DLQ; +- business conflicts через смарт-процесс Битрикс24, technical failures через SigNoz; - прямой доступ к схеме `han_app` и собственной `bitrix_sync`. Не отвечает за: @@ -290,12 +317,12 @@ Confidential **backend client** Keycloak (client credentials) в MVP **не об - HTTP-контракт для api-backend: - `200` — синхронная проверка завершена, **allow**; - `403` — синхронная проверка завершена, **deny**; - - `203` + `task_id` — нужна async-проверка (обычно файлы), сообщение в обработке; -- финальный вердикт async-задачи по `GET /internal/safety/v1/messages/tasks/{task_id}`: `200 allow` | `403 deny` | `203 pending`; + - `202` + `task_id`/`Location` — нужна async-проверка; +- task GET: `200 allow` | `403 deny` | `202 pending` | terminal failed `503`; - SHA-256 хеширование и lookup кэша вердиктов; - отдельный pipeline проверки ссылок; -- запись verdict cache, `safety_task` и audit в схеме `message_safety`; -- internal API: `POST /internal/safety/v1/messages/check`, `GET /internal/safety/v1/messages/tasks/{task_id}`. +- запись verdict caches, `safety_task`, audit и immutable `config_versions` в схеме `message_safety`; runtime role не активирует config; +- target internal API: `POST /internal/safety/v2/messages/check`, `GET /internal/safety/v2/messages/tasks/{task_id}`. Не отвечает за: @@ -423,7 +450,7 @@ api-backend не решает, sync или async нужна проверка в 1. Frontend вызывает `POST /api/v1/dialogs` (если `dialog_id` ещё нет), затем отправляет `POST /api/v1/dialogs/{dialog_id}/messages` с непустым `text` (без вложения). 2. Nginx и API применяют rate limits. -3. API **синхронно** вызывает Message Safety Service (`POST /internal/safety/v1/messages/check`) — шаги текст и ссылки. +3. API вызывает Message Safety v2 (`POST /internal/safety/v2/messages/check`) — шаги text/local links. 4. Далее — общая ветка вердикта (п. 5–8 ниже). **Файловое сообщение:** @@ -437,7 +464,7 @@ api-backend не решает, sync или async нужна проверка в 5. **`403 deny`**: API удаляет quarantine (если был файл), выставляет `safety_status=blocked`, `delivery_status=rejected`, возвращает клиенту безопасную ошибку; в Bitrix24 ничего не уходит. 6. **`200 allow`**: API переносит файл в S3-data attachments (если был), сохраняет сообщение (`safety_status=allowed`, `delivery_status=accepted`) и фиксирует задачу доставки в Open Lines. После успешной отправки через `bitrix-local-app` статус становится `delivery_status=delivered`, API подтверждает клиенту финальный результат; `Dialog.status` → `waiting_for_company`. Если Bitrix24/S3/dependency недоступны после allow, статус становится `delivery_status=failed`, клиент получает безопасную ошибку зависимости. -7. **`203 pending` + `task_id`**: api-backend пишет checkpoint в `safety_tasks` и **регулярно синхронно** вызывает `GET /internal/safety/v1/messages/tasks/{task_id}` (backoff), пока не получит финальный вердикт или не истечёт `MESSAGE_SAFETY_TASK_POLL_MAX_SEC`. Пока идёт poll, **этот** клиентский `POST .../messages` ещё не завершён (соединение ждёт). Параллельные запросы других клиентов **не** блокируются — общей очереди анализа на api-backend нет. +7. **`202 pending`**: api-backend пишет checkpoint с `Location` и синхронно поллит его с `Retry-After`, пока не получит финальный вердикт/terminal failure или не истечёт budget. Public POST остаётся открытым; другие запросы не блокируются. - финальный **`200 allow`** → как п. 6, затем ответ клиенту; - финальный **`403 deny`** → как п. 5, затем ответ клиенту; - timeout / недоступность safety → `delivery_status=failed`, безопасная ошибка клиенту (`503` / `504`), quarantine не promote; recovery по `safety_tasks` — зона модуля. @@ -448,7 +475,7 @@ api-backend не решает, sync или async нужна проверка в - Для доставки в Bitrix24 используется transactional outbox/checkpoint в App DB: запись `Message` и запись намерения доставки фиксируются атомарно, а повторная отправка в `bitrix-local-app` идемпотентна по `message_id` / `Idempotency-Key`. - `delivery_status=accepted` означает, что API принял сообщение и завершил safety allow, но ещё не получил подтверждение доставки в Open Lines. `delivery_status=delivered` выставляется только после успешного ответа `bitrix-local-app` о приёме сообщения для Bitrix24 Open Lines. -- Recovery по `han_app.safety_tasks` восстанавливает только сценарии, где Message Safety вернул `203 pending` и клиентский запрос оборвался из-за timeout/crash. Recovery job повторно опрашивает `message-safety` по `task_id`, затем идемпотентно выполняет promote/delete quarantine и обновляет `Message`/`MessageAttachment`. +- Recovery по `han_app.safety_tasks` восстанавливает сценарии `202 pending` после timeout/crash, опрашивает сохранённый `Location`, затем идемпотентно выполняет conditional promote/delete и обновляет App DB. - Объекты в S3-quarantine не удаляются при timeout safety до финального verdict; orphan-cleanup удаляет только просроченные объекты без активного `safety_tasks` или attachment metadata. ## Поток работы с чатом: Битрикс24 -> клиент @@ -495,11 +522,11 @@ Notification Center v1 регистрирует переданные продю App DB — **локальный кэш** для UI. Двусторонний sync — `bitrix-sync` (имена полей — [`arch-00-glossary.md`](arch-00-glossary.md)): -- **Auth-телефон:** master — Keycloak (`UserIdentity.phone_number`); изменения могут инициировать `contact.update` через триггеры. -- **Поля профиля для UI:** master — последнее успешно синхронизированное значение; основной входящий поток на MVP — правки сотрудником в Bitrix24 (webhook → App DB). -- **App → Bitrix:** триггеры `han_app` → `sync_queue` (`contact.update`). -- **Bitrix → App:** webhook робота → `bitrix-sync`; запись с GUC `han.sync_suppress` (без эхо в очередь). -- **Конфликт:** побеждает более позднее событие (`updated_at`, audit в `bitrix_sync`). +- **Auth-телефон:** master — Keycloak (`UserIdentity.phone_number`); только его фактическое изменение инициирует `contact.update`. +- **ФИО, гражданство, email:** master — Битрикс24; App хранит последний успешно полученный snapshot для UI и не отправляет эти поля обратно. +- **App → Bitrix:** триггеры `han_app` → `sync_queue` (`contact.map_or_create`, `contact.update`, `contact.deactivate`). +- **Bitrix → App:** durable webhook inbox + reconciliation; запись с `SET LOCAL han.sync_suppress='true'` без эхо. +- **Конфликт:** универсального правила «последнее событие побеждает» нет; применяется field mastership. Несовпадение identity/mapping создаёт business alert и не перезаписывает профиль. ## Аудит скачиваний @@ -530,6 +557,7 @@ App DB — **локальный кэш** для UI. Двусторонний syn ## Принципы безопасности - Все защищенные пользовательские API требуют валидный JWT. +- Компрометация одного сервиса не должна автоматически давать host root, Docker daemon, секреты или сетевой доступ соседних сервисов; требования к VM и production-деплою — в [`arch-06-service-hosting-security.md`](arch-06-service-hosting-security.md). - Без JWT доступны **только** read-only публичные endpoint: `GET /api/v1/public/*` (rate limit + CORS + кэш). Write-endpoint (`consents`, `session-start`, чат, профиль и т.д.) требуют JWT. - Все внешние пользовательские соединения работают через HTTPS. - HTTP допускается только для веб-домена как вход для редиректа на HTTPS. Для api домена HTTP не допускается. @@ -546,7 +574,7 @@ App DB — **локальный кэш** для UI. Двусторонний syn - Все публичные id создаются в формате UUID. - Сервисные API защищаются внутренней сетью Docker/VPC плюс service token (канонический контракт — [`arch-02-api-contracts.md`](arch-02-api-contracts.md), «Service tokens (internal API)»; значения переменных — [`arch-04-settings-and-content.md`](arch-04-settings-and-content.md)). - Rate limits применяются минимум на двух уровнях: edge-лимиты в `nginx` и пользовательские лимиты в API с состоянием в Redis. -- Входящие сообщения пользователя: синхронный `POST /internal/safety/v1/messages/check` → при `203` api-backend синхронно поллит `task_id` до финального `200`/`403` (или timeout); без очереди анализа на api-backend. +- Исходящие сообщения пользователя: internal `POST /internal/safety/v2/messages/check` → при `202` api-backend синхронно поллит `Location` до финального `200`/`403`, terminal failed `503` или timeout; public API не становится async. - Файлы пользователя до финального `allow` только в S3-quarantine; в S3-data — после `200 allow`. - У клиента **нет** постоянных S3 credentials. Загрузка — **presigned PUT** в S3-quarantine, выданный `api-backend`; скачивание — **presigned GET**. Байты файла **не** проксируются через `api-backend`. - `message-safety` — read-only к S3-quarantine, без прав записи в бакеты. @@ -559,13 +587,18 @@ App DB — **локальный кэш** для UI. Двусторонний syn ### Состав backend-контура -Минимальный целевой real-SMS контур на одной VM: `nginx`, `api-backend`, `message-safety`, `keycloak`, `sms-service`/worker, `bitrix-sync`, `bitrix-local-app`, `redis`, `otel-collector`. До SMS rollout сервисы SMS могут отсутствовать, но Keycloak обязан оставаться в mock mode. +Минимальный целевой real-SMS контур разделён на два stack: + +- ВМ1: `nginx`, `api-backend`, `keycloak`, `sms-service`/worker, `bitrix-local-app`, Redis DB0/DB1, `otel-collector`; +- ВМ2: nginx с public webhook/private internal server blocks, `message-safety` API/worker, `clamd`/`freshclam`, `bitrix-sync`, Redis Safety, `otel-collector`. + +До SMS rollout сервисы SMS могут отсутствовать, но Keycloak обязан оставаться в mock mode. ### Предлагаемая структура backend-репозитория ```text backend/ - docker-compose.yml # корневой compose: nginx + include сервисов + networks/volumes + docker-compose.yml # root compose ВМ1 .env.example nginx/ docker-compose.yml @@ -579,12 +612,6 @@ backend/ tests/ pyproject.toml Dockerfile - message-safety/ - app/ - docker-compose.yml - tests/ - pyproject.toml - Dockerfile bitrix-local-app/ app/ docker-compose.yml @@ -592,12 +619,6 @@ backend/ tests/ pyproject.toml Dockerfile - bitrix-sync/ - app/ - docker-compose.yml - tests/ - pyproject.toml - Dockerfile keycloak/ docker-compose.yml realm/ @@ -611,14 +632,23 @@ backend/ redis/ docker-compose.yml observability/ - docker-compose.yml # сервис otel-collector + docker-compose.yml # collector ВМ1 otel-collector.yaml + +processing/ + docker-compose.yml # root compose ВМ2 + nginx-internal/ + message-safety/ + bitrix-sync/ + clamav/ + redis/ + observability/ # collector ВМ2 ``` Детальная внутренняя структура каждого сервиса (`app/`, модули, миграции) определяется в профильных спецификациях модулей (TBD). -### Compose-контур +### Compose-контуры -Корневой `backend/docker-compose.yml` подключает сервисные compose-файлы через `include`. +`backend/docker-compose.yml` является единственным root Compose ВМ1; `processing/docker-compose.yml` — единственным root Compose ВМ2. Оба используют `include` и отдельные root-owned systemd units. Cross-host Docker network не используется. -Публикация портов наружу разрешена только `nginx` (`80/443`). Остальные сервисы доступны через Docker-сети и private VPC. +На каждой VM host ports публикует только её nginx. ВМ1 публикует `80/443` своего application host. ВМ2 публикует `80/443` отдельного webhook host и private `8443`; public server block ВМ2 допускает только exact CRM webhook, private listener доступен только SG ВМ1/ops. diff --git a/architectory/arch-02-api-contracts.md b/architectory/arch-02-api-contracts.md index ea45fd5..a27c1eb 100644 --- a/architectory/arch-02-api-contracts.md +++ b/architectory/arch-02-api-contracts.md @@ -22,7 +22,7 @@ | Переменная | Кто проверяет | Кто передаёт | Endpoint | Заголовок | |---|---|---|---|---| -| `MESSAGE_SAFETY_SERVICE_TOKEN` | `message-safety` | `api-backend` | `POST/GET /internal/safety/v1/*` | `X-Service-Token` | +| `MESSAGE_SAFETY_SERVICE_TOKEN` | `message-safety` | `api-backend` | `POST/GET /internal/safety/v2/*` | `X-Service-Token`, private TLS | | `BITRIX_INTERNAL_API_TOKEN` | `bitrix-local-app` | `api-backend` | `POST/GET /internal/openlines/v1/*` | `Authorization: Bearer` | | `BITRIX_LOCAL_APP_INTERNAL_TOKEN` | — | `api-backend` (исходящий) | то же | `Authorization: Bearer` | | `BITRIX_API_INBOX_TOKEN` | `api-backend` | `bitrix-local-app` | `POST /internal/openlines/v1/inbox` | `Authorization: Bearer` | @@ -47,7 +47,8 @@ | Переменная | Назначение | |---|---| | `BITRIX_APPLICATION_TOKEN` | проверка событий Bitrix24 → `bitrix-local-app` `/bitrix/handler` | -| `BITRIX_SYNC_WEBHOOK_TOKEN` | проверка webhook Bitrix24 → `bitrix-sync` `/bitrix/sync/webhook/contact` | +| `BITRIX_SYNC_CONTACT_RECEIVER_TOKEN` | query `token` штатного HTTP-webhook робота Contact → receiver `bitrix-sync`; дополнительно source IP CIDR allow-list | +| `BITRIX_SYNC_ALERT_RECEIVER_TOKEN` | query `token` штатного HTTP-webhook робота smart-process alert → receiver `bitrix-sync`; дополнительно source IP CIDR allow-list | ## Frontend ↔ api-backend @@ -121,6 +122,8 @@ | `503` | `dependency_unavailable` | Circuit open или недоступны safety/Bitrix/S3 | да | | `504` | `dependency_timeout` | Истёк timeout budget внешней зависимости | да | +`422 message_blocked` возвращает только стандартный public error envelope (`code`, generic `message`, `request_id`) без internal `rule_id`/`reason_code`. Пользовательский текст появляется отдельной локальной company-репликой из `text_resources` по мнемонике `safety.chat.blocked`. + Правило доступа к пользовательским ресурсам: для `dialog_id`, `message_id`, `attachment_id`, `document_id`, принадлежащих другому `user_id`, api-backend по умолчанию возвращает `404 not_found`, чтобы не раскрывать существование ресурса. `403 forbidden` используется только для операций, где сам факт ресурса уже известен пользователю или оператору. ### `POST /api/v1/auth/bootstrap` (после OTP) @@ -305,15 +308,17 @@ Post-MVP: допускается «текст + файлы» отдельной Байты файла идут **напрямую в S3-quarantine** по короткоживущему **presigned URL**. `api-backend` не проксирует тело файла: выдаёт URL, проверяет результат, управляет lifecycle (promote/delete). -1. `POST .../attachments/init` (JWT) → `{ attachment_id, upload_url, upload_headers?, expires_at }` — `upload_url` = **presigned PUT** (или POST policy) в **S3-quarantine**; ключ объекта и ограничения (bucket, key prefix, `Content-Type`, max size) задаёт `api-backend`. +1. `POST .../attachments/init` (JWT) → `{ attachment_id, upload_url, upload_headers, expires_at }` — **presigned PUT** в versioned S3-quarantine. Подпись обязательно включает `If-None-Match: *`, checksum header (`x-amz-checksum-sha256` либо подтверждённый эквивалент Selectel) и `Content-Type`; повторная запись того же key получает `412 Precondition Failed`. 2. Frontend загружает байты **напрямую в Selectel S3** по `upload_url` (не через `api-backend`). -3. `POST .../attachments/{attachment_id}/complete` с `checksum` (SHA-256) → api-backend проверяет наличие объекта в quarantine (HeadObject / размер / checksum), фиксирует metadata, `scan_status=pending`. +3. `POST .../attachments/{attachment_id}/complete` с `checksum` (SHA-256) → api-backend получает authoritative `version_id`, ETag, size и server checksum; сравнивает client checksum и атомарно фиксирует `{quarantine_object_key, version_id, etag, checksum}`, `scan_status=pending`. Complete с другой версией/ETag/checksum → `409 resource_state_conflict`. 4. `POST .../messages` с `attachment_id` + `checksum` → Message Safety. Правила безопасности: - у клиента **нет** постоянных S3 access keys — только одноразовый/короткий presigned URL; - presigned URL разрешает запись **только** в выделенный key в S3-quarantine (не в S3-data); +- bucket versioning включён; Safety читает только сохранённый `version_id` с conditional ETag match; +- allow-promote копирует именно эту version и использует conditional source ETag/checksum; mismatch запрещает delivery; - TTL URL короткий (константа модуля / `app_settings`, ориентир минуты); - скачивание из S3-data — отдельные **presigned GET** через `.../download-url` (с audit). @@ -492,27 +497,32 @@ Frontend не обращается напрямую к Keycloak DB и не хр | Контракт | Владелец | Потребитель | Назначение | Защита | |---|---|---|---|---| -| `POST /internal/safety/v1/messages/check` | `message-safety` | `api-backend` | Проверка текста, ссылок и файлов | internal network + `X-Service-Token` | -| `GET /internal/safety/v1/messages/tasks/{task_id}` | `message-safety` | `api-backend` | Опрос до финального вердикта **внутри** того же `POST .../messages` | internal network + `X-Service-Token` | +| `POST /internal/safety/v2/messages/check` | `message-safety` | `api-backend` | Проверка текста, ссылок и файлов | private HTTPS + internal CA + `X-Service-Token` | +| `GET /internal/safety/v2/messages/tasks/{task_id}` | `message-safety` | `api-backend` | Опрос до финального вердикта **внутри** того же public `POST .../messages` | private HTTPS + internal CA + `X-Service-Token` | | Read S3-quarantine | Selectel S3 | `message-safety` | Чтение файла worker-ом при cache miss | read-only key | -HTTP-семантика от `message-safety`: `200 allow`, `403 deny`, `203 pending`. +HTTP-семантика target v2 от `message-safety`: `200 allow`, `403 deny`, `202 Accepted/pending`. Текущие `/v1/*` и `203` относятся только к legacy stub и не являются production-контрактом. + +Normative details v2: каждый verdict/pending содержит `processing_mode=standard|mock` и `config_version`; `202` обязательно содержит `Location`, `Retry-After`, `task_id`, `expires_at` и существует только в standard mode; terminal `503 task_failed` — `terminal=true,retryable=false`; transient `503 dependency_unavailable` — `terminal=false,retryable=true`; `409 safety_request_conflict` — non-retryable caller invariant. Все domain deny имеют `reason_code=message_blocked`. + +Emergency MOCK включается только root-owned helper/restart на ВМ2. В MOCK нет content/link/file checks и `202`: `TEXT_FREE`/`FILE_FREE=true` → sync `200`, false → canonical sync `403`. Auth/DTO/idempotency/audit/rate limits сохраняются. Public API не раскрывает `processing_mode`. Поведение `api-backend`: 1. Синхронно вызывает `POST .../check`, получает один из трёх кодов. 2. При `200` / `403` — сразу завершает сценарий и отвечает клиенту. -3. При `203` — **не ставит задачу в свою очередь анализа**; регулярно и синхронно поллит `GET .../tasks/{task_id}` до `200`/`403` или timeout (`MESSAGE_SAFETY_TASK_POLL_MAX_SEC`), затем отвечает клиенту. +3. При `202` сохраняет `task_id`, `Location`, deadline и **не ставит задачу в свою очередь анализа**; синхронно поллит `Location`, соблюдая `Retry-After`, до `200`/`403`, terminal failed `503` или timeout. 4. Решение «проверка быстрая или долгая» — только у `message-safety`. Ожидание poll держит **одно** клиентское HTTP-соединение; это не блокирует обработку других запросов (параллельные workers/async). Checkpoint: на время poll — запись в **`safety_tasks`** (`han_app`) для recovery при crash/timeout (I1), не очередь анализа. Recovery contract для `han_app.safety_tasks`: -- запись создаётся, когда `message-safety` вернул `203 pending`, и содержит `task_id`, `message_id`, `attachment_id`, текущий `quarantine_object_key`, deadline и retry metadata; -- если клиентское HTTP-соединение оборвалось или api-backend упал, recovery job продолжает poll `GET /internal/safety/v1/messages/tasks/{task_id}`; +- запись создаётся, когда `message-safety` вернул `202 pending`, и содержит `task_id`, `Location`, `message_id`, `attachment_id`, текущие `quarantine_object_key/version_id/ETag`, deadline и retry metadata; +- если клиентское HTTP-соединение оборвалось или api-backend упал, recovery job продолжает poll `GET /internal/safety/v2/messages/tasks/{task_id}`; - final allow выполняет idempotent promote quarantine → S3-data и продолжает delivery checkpoint в Open Lines; - final deny выполняет idempotent delete quarantine и выставляет `safety_status=blocked`, `delivery_status=rejected`; +- при final deny создаётся локальная company-реплика с `text_resources.mnemonic=safety.chat.blocked`; она публикуется как `message.new`, но не отправляется в Open Lines; - timeout/circuit после recovery budget выставляет `delivery_status=failed`, оставляет audit trail и отдаёт объект на quarantine cleanup policy; - recovery job не принимает новых сообщений и не решает, sync или async нужна проверка: это остаётся ответственностью `message-safety`. @@ -522,8 +532,12 @@ Recovery contract для `han_app.safety_tasks`: |---|---|---|---| | `200` / `allow` | `allowed` | `accepted` до вызова Open Lines; `delivered` только после успешной отправки в Open Lines | да | | `403` / `deny` | `blocked` | `rejected` | да | -| `203` → затем `200`/`403` | как финальный | как финальный | да (после sync-wait) | -| timeout / circuit open | `pending` или `blocked` по политике модуля | `failed` | да (ошибка инфраструктуры) | +| `202` → затем `200`/`403` | как финальный | как финальный | да (после sync-wait) | +| terminal failed `503`, `retryable=false` | `pending` | `failed` | да: public `503`, не deny | +| `409 safety_request_conflict` | `pending` | `failed` | да: public `500` + alert, POST не повторять | +| timeout / circuit open | `pending` | `failed` | да: public `503/504`, не deny | + +Для mock file allow `MessageAttachment.scan_status=bypassed`; значение `clean` запрещено, так как фактической проверки не было. `Message.safety_processing_mode` и `Message.safety_config_version` хранятся для audit, но отсутствуют в public DTO. Circuit breaker + timeout budget (I2): при открытом circuit на `message-safety` — не слать сообщение в Bitrix; вернуть клиенту безопасную ошибку зависимости. @@ -580,7 +594,7 @@ Circuit breaker + timeout budget (I2): при открытом circuit на `mes - если `api-backend` недоступен, `bitrix-local-app` хранит событие во внутреннем inbox, повторяет forward с exponential backoff и после исчерпания retry переводит запись в DLQ со статусом `dead_letter`; - `bitrix-local-app` подтверждает доставку в Bitrix24 через `imconnector.send.status.delivery` только после успешного ответа `api-backend` или после идемпотентного duplicate-ack; - файлы оператора: api-backend скачивает по `download_url` (timeout budget) и сохраняет в **S3-data attachments** + `MessageAttachment`; в MVP применяются те же продуктовые лимиты `chat.attachments.allowed_*` и `chat.attachments.max_size_mb`, что и для клиентских файлов; -- сообщения и файлы оператора считаются доверенным Bitrix24-channel для Message Safety: они не проходят outbound moderation pipeline, но проходят MIME/size validation, antivirus policy модуля и audit скачивания; +- сообщения и файлы оператора считаются доверенным Bitrix24-channel: они **не** идут в quarantine и Message Safety, проходят только MIME/size validation и audit скачивания, затем сохраняются в S3-data. Остаточный malware-риск принят для MVP; UI/скачивание должны сохранять безопасный `Content-Disposition`/`Content-Type` и не исполнять active content. - пустой `text` и пустой `files` → reject события; - детальная JSON Schema — в `bitrix-local-app/openapi.yaml` и `api-backend/openapi.yaml`. @@ -592,26 +606,31 @@ Circuit breaker + timeout budget (I2): при открытом circuit на `mes | Контракт | Тип | Владелец | Потребитель | Назначение | |---|---|---|---|---| -| `han_app.sync_queue` | PostgreSQL | триггеры `han_app` (миграции App DB) | `bitrix-sync` | Асинхронная очередь App DB → Bitrix24: триггер ставит задачу при изменении отслеживаемых полей | +| `han_app.sync_queue` | PostgreSQL | триггеры `han_app` (миграции App DB) | `bitrix-sync` | Durable очередь App DB → Bitrix24 с lease/fencing и active-only dedup | | `han.sync_suppress` (GUC) | PostgreSQL session | `bitrix-sync` | триггеры `han_app` | Подавление эхо-задач при записи данных от Bitrix24 в App DB | -| `ClientProfile.bitrix_contact_id` | PostgreSQL | `bitrix-sync` | App DB | Маппинг профиля на CRM Contact после map/create | -| `han_app.entity_external_mapping` | PostgreSQL | `bitrix-sync` | App DB | Универсальный маппинг App entity ↔ Bitrix entity (MVP: Contact) | -| Обновление `sync_queue.status` | PostgreSQL | `bitrix-sync` | App DB | `processed` / `failed` / `dead_letter`, retry metadata | +| `bitrix_sync.entity_external_mapping` | PostgreSQL | `bitrix-sync` | `bitrix-sync` | Единственная каноническая active/closed/broken история `user_id` ↔ Contact; App DB не хранит `b24_id` | +| Обновление `sync_queue.status` | PostgreSQL | `bitrix-sync` | App DB | `pending/leased/retry_wait/processed/dead_letter/cancelled`, lease и safe error metadata | +| `bitrix_sync.workflow_instances` / `crm_commands` | PostgreSQL | `bitrix-sync` | `bitrix-sync` | Persisted scenario state и конкретные Bitrix batch subcommands | +| `bitrix_sync.webhook_inbox` | PostgreSQL | `bitrix-sync` | `bitrix-sync` | Durable приём, dedup и coalescing событий Битрикс24 | Типы задач MVP (`sync_queue.task_type`): -- `contact.map_or_create` — матчинг/создание Contact, запись `bitrix_contact_id`, флаг регистрации в Bitrix24; -- `contact.update` — push изменений профиля в Bitrix24. +- `contact.map_or_create` — матчинг/создание Contact, запись mapping в schema `bitrix_sync`, флаг регистрации в Bitrix24; +- `contact.update` — push только App-master телефона/служебных полей; +- `contact.deactivate` — flag `N`, закрытие active mapping без удаления Contact. + +`contact.rebind` не является задачей `han_app.sync_queue`: это audited административный workflow, создаваемый только через `bitrix_sync.request_bitrix_contact_rebind`. `bitrix-sync` **не создаёт** `UserIdentity` / `ClientProfile` в auth-flow; вход worker — задачи из `sync_queue`, созданные триггерами. +`entity_id` contact-задачи всегда равен `UserIdentity.id`; payload не содержит PII snapshot. Полный DDL/state-machine contract — [`../modules/module-07-bitrix-sync.md`](../modules/module-07-bitrix-sync.md), §§6–9. ### Internal HTTP `bitrix-sync` (ops, не hot path) | Контракт | Владелец | Потребитель | Назначение | Защита | |---|---|---|---|---| -| `GET /internal/sync/v1/status` | `bitrix-sync` | ops / мониторинг | Глубина очереди, dead letter, последний успешный run | internal network + `BITRIX_SYNC_SERVICE_TOKEN` | +| `GET /internal/sync/v1/status` | `bitrix-sync` | ops / мониторинг | Queue/workflow/webhook/reconciliation/limiter state без PII | internal network + `BITRIX_SYNC_SERVICE_TOKEN` | -Повтор dead letter и ручной replay в MVP — через БД/ops-процедуры; отдельный HTTP replay-endpoint — post-MVP. +Публичный/manual replay HTTP endpoint отсутствует. Controlled ops-действия используют утверждённые процедуры с audit; произвольный `UPDATE` mapping запрещён. ## bitrix-local-app ↔ Bitrix24 @@ -629,14 +648,16 @@ Circuit breaker + timeout budget (I2): при открытом circuit на `mes | Контракт | Направление | Назначение | |---|---|---| -| `crm.contact.get/list/add/update` | `bitrix-sync` → Bitrix24 | Поиск, создание и обновление Contact | -| `POST /bitrix/sync/webhook/contact` | Bitrix24 (робот) → `bitrix-sync` | Исходящий webhook при изменении полей Contact, зарегистрированного в приложении | -| PostgreSQL schema `bitrix_sync` | `bitrix-sync` ↔ PostgreSQL | Worker state, field mapping, retry/dead letter audit | -| PostgreSQL schema `han_app` | `bitrix-sync` ↔ PostgreSQL | Очередь `sync_queue`, маппинг ID, обновление профиля (Bitrix → App) | +| `crm.duplicate.findbycomm`, `crm.contact.get/add/update`, `crm.item.list`, `batch` | `bitrix-sync` → Bitrix24 | Первичный поиск, recovery, чтение, создание и точечное обновление Contact; reconciliation через `crm.item.list`, `entityTypeId=3`, `>=updatedTime`, `opened=1`, registration flag `=1` | +| Contact receiver URL `/bitrix/sync/webhook/contact?token=...` | HTTP-webhook робот Битрикс24 → `bitrix-sync` | `application/x-www-form-urlencoded`, query token, source IP CIDR allow-list, durable inbox; затем snapshot по ID | +| Alert receiver URL `/bitrix/sync/webhook/alert?token=...` | HTTP-webhook робот Битрикс24 → `bitrix-sync` | Form-urlencoded сигнал элемента smart process, query token и source IP CIDR allow-list | +| Smart process «Конфликты синхронизации» | `bitrix-sync` ↔ Bitrix24 | Business alerts с fingerprint, occurrence и SLA | +| PostgreSQL schema `bitrix_sync` | `bitrix-sync` ↔ PostgreSQL | Workflow/commands, inbox, snapshots, settings, alerts, reconciliation и technical DLQ | +| PostgreSQL schema `han_app` | `bitrix-sync` ↔ PostgreSQL | Очередь `sync_queue` и обновление профиля (Bitrix → App); canonical mapping хранится только в `bitrix_sync` | Очередь `han_app.sync_queue` и write-back — в разделе «api-backend ↔ bitrix-sync» выше. -`bitrix-sync` использует `BITRIX_SYNC_APP_DATABASE_URL` для `han_app` + `bitrix_sync`, только `BITRIX_SYNC_CRM_*` для Bitrix24 CRM REST и не читает OAuth-токены `bitrix-local-app`. +`bitrix-sync` использует отдельный secret DB URL с search path/access к `bitrix_sync` и точечными GRANT на `han_app`, отдельный входящий webhook технического пользователя для CRM REST и отдельные application tokens исходящих webhook. OAuth-токены `bitrix-local-app` не читает. ## api-backend ↔ внешние хранилища diff --git a/architectory/arch-03-docker-compose-blueprint.md b/architectory/arch-03-docker-compose-blueprint.md index 72bab66..4910e80 100644 --- a/architectory/arch-03-docker-compose-blueprint.md +++ b/architectory/arch-03-docker-compose-blueprint.md @@ -1,6 +1,6 @@ # arch-03. Docker Compose blueprint -> Термины (имена бакетов S3, идентификаторы) — в [`arch-00-glossary.md`](arch-00-glossary.md). Контракт Message Safety Service — в [`arch-02-api-contracts.md`](arch-02-api-contracts.md), раздел «api-backend ↔ message-safety». Переменные окружения и настройки — в [`arch-04-settings-and-content.md`](arch-04-settings-and-content.md). +> Термины (имена бакетов S3, идентификаторы) — в [`arch-00-glossary.md`](arch-00-glossary.md). Контракт Message Safety Service — в [`arch-02-api-contracts.md`](arch-02-api-contracts.md), раздел «api-backend ↔ message-safety». Переменные окружения и настройки — в [`arch-04-settings-and-content.md`](arch-04-settings-and-content.md). VM/SSH, OS-роли, секреты, systemd-деплой и hardening — в [`arch-06-service-hosting-security.md`](arch-06-service-hosting-security.md). ## Назначение @@ -8,31 +8,32 @@ Требования к безопасности на уровне приложения и данных — в [`arch-01-system-architecture.md`](arch-01-system-architecture.md), раздел **«Принципы безопасности»**. Настоящий документ описывает только инфраструктурную реализацию этих принципов в compose/nginx: TLS, маршрутизация, сетевые границы, rate limits на edge. Значения переменных окружения — в [`arch-04-settings-and-content.md`](arch-04-settings-and-content.md). Дублировать прикладные требования (JWT, валидация, CORS в API, PII в логах и т.п.) здесь не нужно — они остаются в `arch-01`. -## Единый compose-контур (обязательно) +## Один root Compose project на каждую VM (обязательно) Это зафиксированное архитектурное требование, а не рекомендация. -### Принцип единого входа +### Принцип независимого входа по VM -- Весь backend-контур поднимается **одной командой** `docker compose up -d` из корня репозитория (`backend/`). -- Корневой `docker-compose.yml` — единственный источник правды для production-like среды. Отдельных compose-файлов для production-деплоя отдельных сервисов не должно быть. -- **Один `nginx`** поднимается из корневого `docker-compose.yml` и является единой публичной точкой входа с маршрутизацией на все сервисы: +- ВМ1 и ВМ2 имеют по одному независимому root Compose project: `backend/docker-compose.yml` и `processing/docker-compose.yml`. +- Каждый project поднимается своим root-owned systemd-unit/deployment helper. Пользователь `deploy` запускает только конкретные units и не получает доступ к Docker daemon; канон — arch-06. +- Внутри одной VM её корневой `docker-compose.yml` — единственный источник правды. Cross-host Docker network и запуск одного Compose project на двух VM запрещены. +- **Nginx ВМ1** является публичной точкой входа только своего контура: - `/api/*` → `api-backend` (REST и `WS /api/v1/realtime`; отдельный path `/realtime/*` **не** используется); - `/auth/*` → `keycloak`; - `/bitrix/*` (public: `/bitrix/handler`, `/bitrix/install`, `/bitrix/placement`, `/health/*` для `bitrix-local-app`) → `bitrix-local-app`; - - `/bitrix/sync/*` (public: webhook CRM sync для `bitrix-sync`) → `bitrix-sync`; - exact `POST /callbacks/idgtl/sms` → `sms-service`; остальные методы и SMS paths не публикуются; - web-сборка frontend или прокси на dev-сервер; - - `/internal/openlines/*`, `/internal/safety/*`, `/internal/sync/*`, `/internal/sms/*`, `/internal/notifications/*` **не публикуются** наружу — доступны только из внутренней Docker-сети. -- Никакой другой `nginx` (ни в контейнере сервиса, ни на хосте) не терминирует внешний HTTPS для backend-контура. Site-конфиг `tohin.ru` на хосте, если используется, должен проксировать весь трафик на корневой `nginx` контейнера, а не на порты отдельных сервисов напрямую. + - `/internal/openlines/*`, `/internal/safety/*`, `/internal/sync/*`, `/internal/sms/*`, `/internal/notifications/*` **не публикуются** наружу. +- **Nginx ВМ2** независимо терминирует public HTTPS на отдельном host и публикует только exact Contact/alert webhook `bitrix-sync`. Отдельный private listener `8443` по internal CA маршрутизирует allow-listed Message Safety/internal paths. +- Между public route ВМ1 и ВМ2 нет reverse-proxy chain или fallback. Каждый nginx имеет собственные DNS, сертификат, rate limits и release lifecycle. -### Структура compose через `include` +### Структура Compose через `include` -Каждый сервис описывается в собственном `docker-compose.yml` внутри папки сервиса и подключается в корневой файл директивой `include`: +Каждый сервис описывается в собственном `docker-compose.yml` и подключается в root-файл своей VM директивой `include`: ```text backend/ - docker-compose.yml # корневой: nginx + include сервисов + общие networks/volumes + docker-compose.yml # root ВМ1 .env nginx/ docker-compose.yml # описание сервиса nginx (или секция в корневом) @@ -42,16 +43,21 @@ backend/ .gitkeep api-backend/ docker-compose.yml # описание сервиса api-backend - message-safety/ - docker-compose.yml # описание сервиса message-safety - bitrix-sync/ - docker-compose.yml # описание сервиса bitrix-sync bitrix-local-app/ docker-compose.yml # описание сервиса bitrix-local-app keycloak/ docker-compose.yml # описание сервиса keycloak (или секция в корневом) observability/ docker-compose.yml # otel-collector и т.п. + +processing/ + docker-compose.yml # root ВМ2 + nginx-internal/docker-compose.yml + message-safety/docker-compose.yml + bitrix-sync/docker-compose.yml + clamav/docker-compose.yml + redis/docker-compose.yml + observability/docker-compose.yml ``` Корневой `backend/docker-compose.yml` (принципиальная схема): @@ -62,8 +68,6 @@ name: han-chat include: - nginx/docker-compose.yml - api-backend/docker-compose.yml - - message-safety/docker-compose.yml - - bitrix-sync/docker-compose.yml - bitrix-local-app/docker-compose.yml - keycloak/docker-compose.yml - sms-service/docker-compose.yml @@ -81,14 +85,57 @@ volumes: nginx-certs: ``` +Root Compose ВМ2 включает собственный nginx с public/private server blocks, Message Safety API/worker, `clamd`/`freshclam`, `bitrix-sync`, Redis Safety и локальный OTEL Collector. Секреты, сети и volumes двух projects не общие. + ### Правила для сервисных compose-файлов -- Сервисный `docker-compose.yml` описывает **только** сервис(ы) своего модуля: образ, build context, `environment` (через `${VAR}` из корневого `.env`), порты (только внутренние, кроме случаев ниже), `depends_on`, healthcheck, подключение к сетям `public`/`backend`/`observability` (объявленным в корневом файле). +- Сервисный `docker-compose.yml` описывает **только** сервис(ы) своего модуля: образ, build context, non-secret `environment` (через `${VAR}` из корневого `.env`), secret files/credentials, порты (только внутренние, кроме случаев ниже), `depends_on`, healthcheck, подключение к сетям `public`/`backend`/`observability` (объявленным в корневом файле). - Сервисный файл **не объявляет** сети и volumes верхнего уровня — они объявляются в корневом `docker-compose.yml`. Сервис только ссылается на них через `networks:` / `volumes:` (external-стиль не нужен, т.к. `include` объединяет файлы в один проект). - Публикация портов наружу (`ports:`) разрешена **только** для `nginx` (80/443). Все остальные сервисы используют `expose:` для внутренних портов и общаются через Docker-сети. - `bitrix-local-app` не публикует `8080` на хост (даже на `127.0.0.1`) — он доступен `api-backend` и `nginx` через сеть `backend`/`public`. Ранее применявшийся `127.0.0.1:8080:8080` считаем устаревшим; проверки через curl на `127.0.0.1:8080` заменяются на `docker compose exec bitrix-local-app` или прокси через `nginx`. - Каждый сервисный compose-файл должен запускаться и в составе корневого контура, и автономно (`docker compose -f bitrix-local-app/docker-compose.yml up`) для локальной разработки сервиса — при условии, что переменные окружения заданы. Для автономного запуска сервис может объявлять заглушки сетей/volumes, но в составе корневого контура они переопределяются общими. +### Обязательный container hardening + +Для production-сервисов применяются требования [`arch-06-service-hosting-security.md`](arch-06-service-hosting-security.md): + +- непривилегированный `user`; +- `security_opt: [no-new-privileges:true]`; +- `cap_drop: [ALL]` с точечным возвратом документированных capabilities; +- `read_only: true`, а writable paths — отдельные volume/tmpfs; +- запрет `privileged`, host network/PID/IPC и Docker socket; +- CPU/memory/PID limits, healthcheck и pinned image version/digest; +- только необходимые Docker networks и read-only bind mounts. + +Если сервису нужен root, writable root filesystem, capability или host mount, исключение фиксируется в профильной спецификации вместе с риском и компенсирующей мерой. + +### Практическая валидация non-root/read-only image + +Для каждого pinned digest Compose фиксирует и проверяет: + +- фактические UID/GID основного процесса и entrypoint; +- vendor entrypoint для non-root режима, если он отличается от root-варианта; +- полный список writable paths: generated config, runtime/socket, cache/temp, + logs и persistent state; +- отдельный volume/tmpfs для каждого writable path с явными + `uid/gid/mode`, размером и mount flags; +- healthcheck именно того процесса, который реально запущен в контейнере; +- restart semantics: успешный one-shot exit не должен превращаться в + бесконечный restart/download loop. + +Tmpfs скрывает ownership каталога из image, поэтому одного корректного +`USER`/`chown` в Dockerfile недостаточно: ownership задаётся на самом tmpfs. +Ошибка `read-only file system` исправляется добавлением минимального writable +mount, а не `read_only: false`, root, `privileged` или broad capabilities. + +Compose file secrets с bind-backed `file:` могут игнорировать декларативные +`uid/gid/mode`. Их фактические host permissions создаёт secret materializer; +rollout проверяет owner/mode из контейнера и с host, не полагаясь на YAML. + +При сборке images необхоидмо добавлять нормализацию CRLF→LF +(например, RUN sed -i 's/\r$//' \ + && /bin/sh -n ) и использовать проверку синтаксиса entrypoint + ### Команды разработки ```text @@ -106,15 +153,25 @@ docker compose exec api-backend ruff format . ## Сервисы -### nginx +### nginx ВМ1 и ВМ2 -Reverse proxy и единственная публичная точка входа в Docker Compose контур. +На каждой VM работает собственный nginx в независимом root Compose. ВМ1 обслуживает frontend/API/auth/Open Lines/SMS; ВМ2 напрямую принимает CRM webhook и отдельно предоставляет private Message Safety ingress. Публичный трафик ВМ2 не проксируется через ВМ1. Требования: - публикует наружу только `80` и `443` (см. политику HTTP ниже); - принимает внешний HTTPS-трафик; - выполняет TLS termination на reverse proxy; внутренний HTTP между контейнерами — только в закрытой Docker-сети `backend`; +- non-root nginx получает writable tmpfs только для `/etc/nginx/conf.d`, + `/var/cache/nginx`, `/var/run` и `/tmp`; tmpfs задаёт явные UID/GID/mode и + `nofile` согласован с `worker_connections`; +- если image entrypoint выполняет `envsubst`, output directory обязан быть + writable целевому UID, а основной `nginx.conf` подключает конкретный + generated file, чтобы отсутствующий результат не дал ложный успешный + `nginx -t` через wildcard include; +- pre-start config test выполняет реальный image entrypoint. До запуска + upstream-контейнеров их host variables временно подменяются loopback IP + только в test container; production Compose сохраняет service DNS names; - **политика HTTP/HTTPS по доменам** (каноническое правило — [`arch-01-system-architecture.md`](arch-01-system-architecture.md), «Принципы безопасности»): - **веб-домен** (frontend, SPA, статика): `listen 80` допускается **только** для безусловного редиректа `301`/`308` на HTTPS; обработка бизнес-логики по HTTP запрещена; - **API-домен** (если выделен отдельный host, напр. `api.example.ru`): **не** слушает порт `80`; только `listen 443 ssl`; HTTP-запросы к API-домену недоступны; @@ -124,7 +181,7 @@ Reverse proxy и единственная публичная точка вход - маршрутизирует `/api/*` в `api-backend` (включая WebSocket upgrade для `/api/v1/realtime`); - маршрутизирует `/auth/*` в `keycloak` или проксирует отдельный auth-домен; - маршрутизирует публичные `/bitrix/*` endpoint в `bitrix-local-app`; -- маршрутизирует `/bitrix/sync/*` webhook endpoint в `bitrix-sync`; +- nginx ВМ2 маршрутизирует только exact `/bitrix/sync/webhook/contact` и `/bitrix/sync/webhook/alert` в локальный `bitrix-sync`; - маршрутизирует только exact `POST /callbacks/idgtl/sms` в `sms-service:8080`; применяет HTTPS, подтверждённый allowlist source IP Direct, body/rate limits и redaction Basic Authorization; - закрывает `/internal/*` (в т.ч. `bitrix-local-app`, `message-safety`, `bitrix-sync` ops) от публичного доступа — только private network Docker/VPC; - **не публикует** `message-safety` наружу; @@ -149,7 +206,7 @@ Python FastAPI backend. Требования: - запускается после доступности managed PostgreSQL, `keycloak`, `redis`; -- применяет настройки из `.env`; +- применяет non-secret настройки из `.env` и runtime secrets из явно смонтированных secret files; - отдает `/health/live` и `/health/ready`; - корректно работает за reverse proxy и доверяет proxy headers только от `nginx`; - применяет API-level rate limits с состоянием в Redis; @@ -165,38 +222,63 @@ Python FastAPI backend. ### message-safety -Отдельный backend-сервис проверки входящих сообщений пользователя. HTTP-контракт — в [`arch-02-api-contracts.md`](arch-02-api-contracts.md), раздел «api-backend ↔ message-safety». +Отдельный сервис ВМ2 для проверки исходящих сообщений пользователя. HTTP-контракт — в [`arch-02-api-contracts.md`](arch-02-api-contracts.md), раздел «api-backend ↔ message-safety». Требования: -- запускается после доступности managed PostgreSQL (схема `message_safety`), `redis`; -- **не публикуется** через `nginx` — доступен только из внутренней Docker-сети; -- отдаёт `/health/live` и `/health/ready` (ready проверяет PostgreSQL, Redis, workers, read-доступ к S3-quarantine); -- exposing endpoints: `POST /internal/safety/v1/messages/check`, `GET /internal/safety/v1/messages/tasks/{task_id}` (internal Docker network + `X-Service-Token` / `MESSAGE_SAFETY_SERVICE_TOKEN`); +- запускается после доступности managed PostgreSQL (схема `message_safety`) и Redis Safety; +- сам Message Safety наружу не публикуется; api-backend обращается через private listener nginx ВМ2 по HTTPS; +- отдаёт `/health/live` и capability-aware `/health/ready`: PostgreSQL/config — core gate, Redis/workers/S3/DNS влияют на отдельные capabilities; в MOCK normal capabilities показываются как `bypassed`, mode — `degraded`; +- target endpoints: `POST /internal/safety/v2/messages/check`, `GET /internal/safety/v2/messages/tasks/{task_id}` (private HTTPS + `X-Service-Token`); - read-only доступ к S3-quarantine (отдельный access key без прав записи); - использует отдельную схему `message_safety` в managed PostgreSQL и отдельный DB-user; -- использует Redis (отдельная DB, напр. `redis://redis:6379/2`) для verdict cache и rate limits; +- runtime role читает immutable active `message_safety.config_versions`; создавать/активировать config может только отдельный migration/config-admin job; +- использует локальный Redis Safety только для hot cache/rate/wakeup; PostgreSQL владеет task queue/leases; - запускает async workers для file scan из S3-quarantine; +- API container получает read-only root-owned `/etc/han-chat/message-safety-mode.env`; менять его и перезапускать stack может только fixed helper, разрешённый `deploy` через exact-argument sudoers; - экспортирует traces/logs в `otel-collector`; - таймауты: POST check 5 s, GET task 2 s, file scan 60 s (см. [`arch-04-settings-and-content.md`](arch-04-settings-and-content.md), переменные `MESSAGE_SAFETY_*`). +### ClamAV на ВМ2 + +`clamd` и `freshclam` используют один immutable image digest, но разные +security-профили: + +- оба запускаются через vendor `init-unprivileged`, а не root entrypoint; +- `clamd` читает volume signatures read-only, не подключён к signature CDN и + имеет healthcheck daemon socket; +- `freshclam` один пишет в signatures и имеет только разрешённый egress к CDN; +- `/run/clamav` — отдельный runtime volume, `/var/log/clamav` и `/tmp` — + ограниченные tmpfs с UID/GID ClamAV; +- `freshclam` работает как foreground daemon с заданным interval; inherited + healthcheck `clamd` отключён, потому что updater не поднимает daemon socket; +- работоспособность updater подтверждается состоянием `Up`, отсутствием + restart loop и отдельным контролем возраста/signature version, а не + искусственным container healthcheck. + +Смена digest ClamAV требует повторной проверки entrypoint, UID/GID, writable +paths, `clamd` health и фактического обновления signatures. Нельзя менять +только tag/digest, считая security contract image неизменным. + ### bitrix-sync -Python worker/service **двусторонней** синхронизации App DB ↔ Bitrix24 CRM. +Python API/worker service ВМ2 для durable двусторонней синхронизации App DB ↔ Bitrix24 CRM. Каноническая постановка — [`../modules/module-07-bitrix-sync.md`](../modules/module-07-bitrix-sync.md). Требования: -- запускается после готовности managed PostgreSQL, `redis`; +- запускается при доступном managed PostgreSQL; Redis не является зависимостью sync; - читает задачи из `han_app.sync_queue` (заполняется триггерами App DB); -- имеет прямой доступ к `han_app` (`BITRIX_SYNC_APP_DATABASE_URL`) и схеме `bitrix_sync`; -- выполняет map/create Contact по телефону (интервал `BITRIX_SYNC_CONTACT_MAP_INTERVAL_SEC`, default 60); -- push обновлений Contact (интервал `BITRIX_SYNC_CONTACT_UPDATE_INTERVAL_SEC`, default 30); -- принимает webhook `POST /bitrix/sync/webhook/contact` от роботов Bitrix24; -- при записи в App DB от Bitrix использует GUC `han.sync_suppress=true`; -- поддерживает graceful shutdown и rate limiting Bitrix REST; +- владеет схемой `bitrix_sync` и имеет только точечные GRANT на queue/profile/mapping в `han_app`; +- выполняет durable workflows `contact.map_or_create`, `contact.update`, `contact.deactivate` и административный `contact.rebind`; +- принимает `POST /bitrix/sync/webhook/contact` и `/bitrix/sync/webhook/alert`, durable сохраняет до `2xx`; +- выполняет Contact/alert reconciliation на случай потери обычного webhook; +- при записи в App DB от Bitrix использует `SET LOCAL han.sync_suppress='true'`; +- использует Bitrix `batch`, общий token bucket и bounded in-flight; default 2 HTTP requests/sec; +- поддерживает leases/fencing, graceful shutdown, retry до 24 часов, technical DLQ и business alerts; - не блокирует пользовательский API при ошибках Битрикс24; - не участвует в OTP-flow, не создаёт `UserIdentity`/`ClientProfile`; - **не участвует** в hot path чата Open Lines; +- принимает публичный CRM webhook после TLS termination/rate limit на собственном nginx ВМ2; ВМ1 в route не участвует; - включается/отключается флагом **`BITRIX_SYNC_ENABLED`** в `.env` (default `true`): при `false` сервис стартует в no-op/degraded режиме, но не обрабатывает `sync_queue` и не выполняет синхронизацию с Bitrix24 CRM. ### bitrix-local-app @@ -224,9 +306,16 @@ Python worker/service **двусторонней** синхронизации Ap - подключение только из приватной сети VPC (VM → managed PostgreSQL); - одна managed база: схемы `han_app`, `bitrix_sync`, `message_safety`, `bitrix_local`, `keycloak`, `sms`; -- отдельные DB-пользователи с доступом только к своей схеме; исключение: `bitrix_sync_user` дополнительно имеет ограниченный GRANT на `han_app` (`sync_queue`, `entity_external_mapping`, tracked columns профиля — детали схемы TBD в спецификации database); +- отдельные DB-пользователи с доступом только к своей схеме; исключение: `bitrix_sync_user` дополнительно имеет column/table GRANT на `han_app.sync_queue`, чтение необходимых identity/profile columns и controlled update CRM-master profile fields согласно module-07 §13; mapping/rebind находятся в собственной schema `bitrix_sync`; - TLS к managed PostgreSQL обязателен; -- миграции Alembic выполняются отдельной командой при деплое; +- миграции Alembic выполняются отдельным controlled job с migration URL, + который не попадает в runtime services; +- временные cross-schema `USAGE`/`SELECT` выдаёт owner/DB administrator на + конкретные объекты до migration gate и отзывает после успешного commit; + migration чужой схемы не выполняет `REVOKE`/`ALTER` её объектов; +- release image сохраняет все уже использованные Alembic revision IDs, в том + числе legacy/no-op baseline, чтобы `upgrade head` не требовал ручного + `stamp` production DB; - бэкапы и PITR — на стороне провайдера. ### keycloak @@ -265,7 +354,7 @@ Identity provider. **Обязателен** в compose-контуре с пер - хранить счетчики API-level rate limits и idempotency keys (`api-backend`); - поддерживать TTL для лимитных и idempotency ключей; - **не** хранить OTP counters для `api-backend` (OTP — зона Keycloak/SPI); -- sync_queue хранится в PostgreSQL (`han_app`), Redis может использоваться для wake-up/locking/queue optimization; +- sync_queue, leases, limiter coordination и durable wake-up fallback хранятся в PostgreSQL; `LISTEN/NOTIFY` — только optimization, Redis sync-service не использует; - разделение DB index (I4): см. arch-04 (`REDIS_URL`, `MESSAGE_SAFETY_REDIS_URL`). ### otel-collector @@ -282,27 +371,39 @@ Identity provider. **Обязателен** в compose-контуре с пер Рекомендуемые сети: -- `public`: `nginx`, `keycloak` (для прокси `/auth/*`), frontend static/dev access, внешний HTTPS entrypoint. -- `backend`: `api-backend`, `message-safety`, `bitrix-sync`, `bitrix-local-app`, `keycloak`, `redis` (managed PostgreSQL — вне compose, в VPC). -- `egress`: только сервисы с утверждёнными исходящими интеграциями; `sms-worker` обращается к Direct, Keycloak — только к `smartcaptcha.cloud.yandex.ru` для server-side validation. Production real mode требует фактический статический egress IP/NAT, записанный в inventory и переданный Direct для allowlist. -- `observability`: `otel-collector` + сервисы, экспортирующие telemetry. +- ВМ1 `public`: edge nginx, Keycloak proxy и frontend entrypoint. +- ВМ1 `backend`: `api-backend`, `bitrix-local-app`, Keycloak, SMS API и Redis DB0/DB1. +- ВМ2 `backend`: nginx, Safety API/worker, `bitrix-sync`, `clamd` и Redis Safety. +- `egress` подключается только к процессам с назначением: `freshclam` → signature CDN; `bitrix-sync` → утверждённый Bitrix portal; Safety worker → S3/PG/DNS; collector → private SigNoz. Общего internet egress у Safety API/clamd/Redis нет. +- `observability` существует отдельно на каждой VM и ведёт в её local collector. -Базы данных, Redis, Keycloak internal port и API internal port не должны публиковаться наружу. `message-safety` доступен только внутри сети `backend`. Основной пользовательский путь должен идти через `nginx` и HTTPS. +Базы данных, Redis, OTLP receivers и internal service ports не публикуются. Cross-host calls идут через private network, точные SG и TLS. ## Volumes -Минимальные volumes (production на одной VM): +Минимальные volumes: -- `redis-data` (опционально, если нужна персистентность); -- certbot / TLS volumes для `nginx`. +- ВМ1: Redis DB0/DB1 data, public TLS/ACME, local OTEL queue; +- ВМ2: Redis Safety data (rebuildable), ClamAV signatures и runtime, + internal TLS secrets, local OTEL queue. + +Public TLS и ACME на ВМ2 — не named volumes: Compose монтирует read-only host +staging `/var/lib/han-chat/public-tls` и ACME webroot +`/var/lib/han-chat/acme`. Internal TLS certificate/key передаются отдельными +Compose secrets и не объединяются с public TLS. Данные PostgreSQL **не** хранятся в Docker volumes — только managed PostgreSQL вне compose. +Persistent volume используется только для state, переживающего recreate. +Generated config, PID/socket, cache и logs без retention размещаются в +ограниченных tmpfs. Один writable volume не объединяет config/executable со +state. + ## Переменные окружения -Корневой `backend/.env` читается всеми сервисами compose через `${VAR}` в сервисных `docker-compose.yml`. Канонический `.env.example` и `app_settings` — в [`arch-04-settings-and-content.md`](arch-04-settings-and-content.md); контракты service tokens — в [`arch-02-api-contracts.md`](arch-02-api-contracts.md). +Каждая VM имеет свой allow-listed non-secret env manifest. Секреты доставляются отдельными service files согласно arch-04/06; общий env/secret bundle двух VM запрещён. -Для smoke-продюсера обязателен `NOTIFICATIONS_TOKEN_PRODUCER_TEST`; это secret, а не `app_settings`. Compose передаёт его только `api-backend` и notification workers. Зарегистрированные entrypoints: `han-notification-expire-worker` и `han-notification-draft-cleanup-worker`; выдуманный command без project script в deployment запрещён. +Для smoke-продюсера обязателен `NOTIFICATIONS_TOKEN_PRODUCER_TEST`; это runtime secret, а не `.env`/`app_settings`. Compose монтирует его только `api-backend` и notification workers. Зарегистрированные entrypoints: `han-notification-expire-worker` и `han-notification-draft-cleanup-worker`; выдуманный command без project script в deployment запрещён. ## HTTPS и TLS @@ -337,6 +438,13 @@ Identity provider. **Обязателен** в compose-контуре с пер - инструкция по установке всегда открывается новой вкладкой, поэтому CSP SPA задаёт `frame-src 'none'`; allow-list iframe для инструкций отсутствует; - секретный ключ сертификата не коммитится в репозиторий; - использовать сертификаты доверенного CA; автоматизировать выпуск и продление (Let's Encrypt + reload `nginx`); +- non-root nginx не монтирует root-only дерево Let's Encrypt целиком: + root deploy hook атомарно копирует только `fullchain.pem` и `privkey.pem` в + host staging `root:` (`0750`, файлы `0640`), а Compose + монтирует staging read-only; +- reload после renewal выполняется только после `openssl` certificate/key + match и полного `nginx -t`; internal TLS PEM также проверяется на raw PEM, + отсутствие literal `\n`/double-base64 и совпадение ключа; - закрыть прямой доступ к внутренним портам контейнеров извне. ## Nginx routing для Bitrix24 Local App @@ -356,13 +464,17 @@ Identity provider. **Обязателен** в compose-контуре с пер - для `/bitrix/*` callbacks кэширование отключено; - для `/bitrix/*` callbacks включены отдельные rate limits, но они не должны блокировать легитимные webhook-повторы Bitrix24. -## Nginx routing для bitrix-sync (CRM webhook) +## Nginx routing для bitrix-sync (CRM webhooks) -`nginx` маршрутизирует публичные webhook CRM sync в `bitrix-sync`: +Публичный nginx ВМ2 маршрутизирует только два exact webhook CRM sync в локальный `bitrix-sync`: -- `POST /bitrix/sync/webhook/contact` — исходящий webhook от роботов Bitrix24 при изменении Contact; -- проверка `BITRIX_SYNC_WEBHOOK_TOKEN` выполняется в `bitrix-sync`; -- кэширование отключено; rate limits не должны блокировать легитимные повторы Bitrix24; +- `POST /bitrix/sync/webhook/contact` — изменение Contact; +- `POST /bitrix/sync/webhook/alert` — изменение элемента smart process конфликтов; +- nginx до proxy проверяет source IP по version-controlled `BITRIX_WEBHOOK_ALLOWED_CIDRS`; автоматическое расширение allow-list запрещено; +- штатный робот передаёт отдельный Contact/alert receiver token в query и form-urlencoded document/auth fields; token, query и body не попадают в logs/traces; +- document/entity/domain/member fields проверяются в `bitrix-sync`; local app/event handler для CRM sync не используется; +- кэширование отключено; source IP/body/method/rate limits применяются до private proxy; IP rejects экспортируются в telemetry без IP label; +- при sync disabled/cutover route закрыт либо возвращает retryable `503`, а не `202 ignored`; - `/internal/sync/v1/*` не публикуется наружу (только internal network + `BITRIX_SYNC_SERVICE_TOKEN`). ## Rate limits и защита от abuse @@ -420,9 +532,9 @@ WAF не заменяет обязательные лимиты, валидац Минимальные проверки: - `nginx`: на веб-домене — `301` с `:80` на HTTPS; на API-домене (если выделен) — `:80` не слушает; `:443` — HTTP 200/301 и успешная TLS handshake; -- `api-backend`: `/health/live` проверяет процесс; `/health/ready` проверяет PostgreSQL `han_app`, Redis `/0` и `/1`, доступность JWKS/discovery Keycloak, S3 permissions для presign/promote и readiness `message-safety`; -- `message-safety`: HTTP 200 от `/health/ready` (проверяет PostgreSQL, Redis, workers, read S3-quarantine); -- `bitrix-sync`: `/health/live` проверяет процесс; `/health/ready` проверяет PostgreSQL, доступ к `sync_queue`, worker state и CRM webhook config; при `BITRIX_SYNC_ENABLED=false` ready возвращает degraded/not-ready с причиной `sync_disabled`; +- `api-backend`: `/health/live` проверяет процесс; `/health/ready` проверяет PostgreSQL `han_app`, Redis DB0/DB1, JWKS/discovery Keycloak и S3 permissions. Недоступность remote Message Safety отражается как degraded dependency и блокирует только send path, но не readiness read API; +- `message-safety`: `/health/ready` возвращает process/core status и capability map `text|links|files|worker`; ClamAV/S3 не выключают text, DNS не выключает text без ссылок, Redis hot cache не является core gate; +- `bitrix-sync`: `/health/live` проверяет процесс; `/health/ready` проверяет validated config/secrets, PostgreSQL/grants, worker/limiter state и CRM webhook config; invalid credential/config даёт not-ready, краткая CRM outage — degraded по stale policy; при `BITRIX_SYNC_ENABLED=false` ready возвращает not-ready `sync_disabled`; - `bitrix-local-app`: `/health/live` проверяет процесс; `/health/ready` показывает PostgreSQL, OAuth-токены после установки приложения, connector activation и возможность forward в API при включённом `BITRIX_API_FORWARD_URL`; - `keycloak`: health endpoint Keycloak; readiness — подключение к managed PostgreSQL; - `sms-service`: live — процесс; ready — schema/migrations, active approved template, sender/API key; Direct доступность — отдельный dependency status, не причина restart loop; @@ -430,31 +542,63 @@ WAF не заменяет обязательные лимиты, валидац Наружу через `nginx` публикуются только health endpoint, которые нужны Bitrix24 install/callback validation или внешнему мониторингу. Internal services (`message-safety`, internal `bitrix-sync`, Redis, otel) проверяются только из Docker/VPC-сети. +Healthcheck не копируется между разными commands одного image без проверки. +Если updater не запускает daemon, daemon-socket healthcheck для него +отключается. Freshness данных контролируется отдельной метрикой/проверкой +timestamp и версии, а `restart: unless-stopped` применяется только к +долгоживущему foreground process. + ## Порядок запуска -1. `redis` (managed PostgreSQL должна быть доступна до старта зависимых сервисов). -2. `otel-collector`. -3. `api-backend` и seed OTP settings. -4. `sms-service`/worker после migrations/seed (Keycloak пока mock). -5. `keycloak`. -6. `message-safety`. -7. `bitrix-local-app`. -8. `bitrix-sync`. -9. Notification expire/cleanup workers после готовности `api-backend` и регистрации их entrypoints. -10. `nginx`. +Общие prerequisites: managed PostgreSQL доступна из private network, +host-side secrets/TLS materialized, controlled migrations и seed завершены. + +ВМ2 запускается в порядке: + +1. `redis-safety` и local `otel-collector`; +2. `freshclam`, затем `clamd` до состояния healthy; +3. Message Safety API/worker и `bitrix-sync`; +4. nginx — последним, после успешного config test; +5. private HTTPS ВМ1→ВМ2 и capability health проверяются до cutover. + +ВМ1 запускается в порядке: + +1. Redis и `otel-collector`; +2. Keycloak, `sms-service`/worker, `api-backend` и `bitrix-local-app` с их + readiness-зависимостями; +3. notification expire/cleanup workers после готовности `api-backend`; +4. nginx — последним. Порядок rollout SMS подробнее задаёт module-11/module-10. Зависимости запуска не образуют цикл: Keycloak стартует при недоступном `sms-service`; это блокирует только новые real-mode orders, а verify уже active challenges продолжается по snapshot. -`depends_on` не заменяет проверку готовности. Сервисы должны уметь ждать зависимости или корректно завершаться с понятной ошибкой. `api-backend` должен ждать готовности `message-safety` (healthcheck), т.к. отправка сообщения синхронно зависит от `POST /internal/safety/v1/messages/check`. +`depends_on` не заменяет проверку готовности. Сервисы должны уметь ждать зависимости или корректно деградировать. `api-backend` может стать ready для read API до ВМ2, но send endpoint обязан fail-closed при недоступной требуемой capability Safety. -## Развёртывание на одной VM +## Развёртывание на ВМ1 и ВМ2 -Production-контур на `tohin.ru`: +1. ВМ1, ВМ2, SigNoz и managed PostgreSQL находятся в одной private network/VPC; ВМ1 и ВМ2 имеют независимые public DNS/TLS ingress. +2. Managed PostgreSQL не имеет public IP; SG разрешает каждой VM только нужные DB roles/schemas. +3. На каждой VM отдельный root-owned systemd unit выполняет её root Compose; `deploy` не входит в `docker`. +4. Public nginx ВМ2 публикует `80/443`; `80` используется только для ACME/redirect, `443` — только exact CRM webhook. Private `8443` разрешён только от SG ВМ1 и ops для Message Safety/internal access. +5. Deploy/cutover ВМ2 не требует изменения public routes ВМ1. Для `bitrix-sync` rollback закрывает webhook routes на nginx ВМ2 либо возвращает retryable `503`, останавливает claims и сохраняет durable tasks/mapping; возврат к фиктивному `202 ignored` запрещён. -1. VM и managed PostgreSQL в одном VPC/кластере провайдера. -2. Managed PostgreSQL без публичного IP; security group разрешает подключение только с VM. -3. `docker compose up -d` на VM поднимает все сервисы кроме БД. -4. Сервисы подключаются к managed PostgreSQL по приватному FQDN/IP. +Перед первым `up` и после смены любого image digest обязательны permission +gates: + +1. проверить LF/shebang и root ownership release-артефактов; +2. сверить UID/GID контейнеров с owner/mode host bind mounts, secret files и + TLS staging; +3. проверить доступ целевого UID и отказ постороннему UID; +4. выполнить PEM parse/key-match и Compose render; +5. запустить image-native config test/entrypoint с production hardening и + временными test-only upstream values; +6. выдать migration-role только необходимые временные cross-schema grants, + выполнить Alembic и отозвать grants владельцем; +7. после старта проверить отсутствие permission/restart loops, реальные + healthchecks и freshness updater data. + +Неуспех gate исправляется в ownership, mount/entrypoint contract или DB grants. +Временное ослабление `read_only`, запуск root, broad chmod, добавление в +`docker` group и расширение DB privileges запрещены. ## Production-замечания @@ -467,15 +611,15 @@ Production-контур на `tohin.ru`: Переменные — [`arch-04-settings-and-content.md`](arch-04-settings-and-content.md), блок «Frontend (nginx)». -Docker Compose на одной VM — production-контур первого этапа. Позже при росте нагрузки можно отдельно решить: +Два root Compose projects — production-контур первого этапа. Позже при росте можно отдельно решить: - вынос Redis в managed cache; -- managed object storage; -- secret manager; -- TLS, reverse proxy или managed ingress; -- backup и restore; -- централизованный мониторинг; -- горизонтальное масштабирование API и worker. +- перенос `bitrix-sync` на ВМ3; +- горизонтальное масштабирование Safety API/worker/scan lanes; +- managed internal load balancer/mTLS; +- HA ВМ2. + +Secret manager не является будущей опцией: для VM с утверждённым egress действует `han-secrets` + Selectel Secrets Manager, а для private/no-egress VM — контролируемая доставка root-owned secret files без сетевого secret-agent. Модель зафиксирована в arch-04 и arch-06. ### Backup, restore и cleanup diff --git a/architectory/arch-04-settings-and-content.md b/architectory/arch-04-settings-and-content.md index 71de07b..66c827d 100644 --- a/architectory/arch-04-settings-and-content.md +++ b/architectory/arch-04-settings-and-content.md @@ -1,6 +1,6 @@ # arch-04. Настройки и изменяемые параметры -> **`.env`** — инфраструктура и секреты. **`app_settings`** (App DB) — единственный источник бизнес-настроек. Имена полей и enum — [`arch-00-glossary.md`](arch-00-glossary.md). Docker Compose — [`arch-03-docker-compose-blueprint.md`](arch-03-docker-compose-blueprint.md). +> **`.env`** — только несекретная инфраструктурная конфигурация. Production-секреты доставляются отдельно по [`arch-06-service-hosting-security.md`](arch-06-service-hosting-security.md). **`app_settings`** (App DB) — единственный источник бизнес-настроек. Имена полей и enum — [`arch-00-glossary.md`](arch-00-glossary.md). Docker Compose — [`arch-03-docker-compose-blueprint.md`](arch-03-docker-compose-blueprint.md). ## Цель @@ -8,7 +8,8 @@ | Слой | Где | Что | |---|---|---| -| **Инфраструктура** | `.env` | подключения, URL, секреты, nginx/TLS, service tokens | +| **Инфраструктура** | `.env` | несекретные host/port/URL, nginx/TLS, режимы и технические параметры | +| **Production-секреты** | Selectel Secrets Manager → `/run/han-chat/secrets`; для no-egress VM — root-owned files | credential-bearing DSN, пароли, private keys, service/webhook tokens, provider credentials | | **Бизнес-логика** | таблица **`app_settings`** | лимиты, флаги, телефоны, типы файлов, CORS, consent URLs | | **Настройки SMS runtime** | таблица **`sms.sms_setting`** | sender default, provider timeouts, callback flag, worker intervals | | **Контент** | `text_resources`, `popular_questions` | тексты UI | @@ -17,22 +18,31 @@ Managed PostgreSQL **поднимается до** развёртывания п ## Источники настроек -### `.env` — только инфраструктура +### `.env` — только несекретная инфраструктура Корневой `backend/.env` читается сервисами compose. В репозитории — `.env.example`, не `.env`. **Допустимо в `.env`:** - URL сервисов, публичные endpoint, порты; -- строки подключения PostgreSQL, Redis, Keycloak DB; -- секреты: S3, Bitrix OAuth, service tokens, webhook-тokens; +- host/port/database/schema без паролей и токенов; - параметры **nginx/TLS** и edge rate limits (`NGINX_RATE_LIMIT_*`); - идентификация Keycloak: realm, audience, public/internal URL; -- переключатель и секрет временного OTP mock (`KEYCLOAK_OTP_MOCK_*`); mock обязателен до прохождения real-SMS rollout gates и запрещён как незаявленный fallback; -- переключатель и client/server keys Yandex SmartCaptcha (`KEYCLOAK_YANDEX_CAPTCHA_*`); сложность остаётся в Yandex Cloud, а server key не попадает в тему/логи; +- переключатели OTP mock и Yandex SmartCaptcha, а также публичный CAPTCHA client key; mock code и CAPTCHA server key являются секретами; +- `SECRETS_SOURCE=selectel|file`, который выбирает утверждённый механизм доставки, но не содержит secret value; - технические параметры сервисов, пока профильная спецификация не определила service-owned settings; для `sms-service` runtime-параметры уже вынесены в `sms.sms_setting`. -**Запрещено в `.env` (→ только `app_settings`):** +**Запрещено в `.env`:** + +- credential-bearing DSN/URL; +- пароли БД, Keycloak bootstrap password и OTP mock/HMAC secrets; +- S3 access/secret keys; +- Bitrix OAuth secrets и application/webhook tokens; +- service tokens внутренних API; +- SMS API key/callback credentials и OTLP auth header; +- TLS private keys и любые иные credentials. + +Они доставляются как Compose/systemd secret files по arch-06. Бизнес-параметры ниже хранятся только в `app_settings`: - включение/отключение OTP, OTP-лимиты для UI/продукта; - телефон оператора, consent URLs/versions; @@ -52,7 +62,13 @@ Managed PostgreSQL **поднимается до** развёртывания п ### `text_resources` / `popular_questions` -Контент UI — отдельные таблицы (не `app_settings`). Ключи MVP — TBD (спецификация frontend). +Контент UI — отдельные таблицы (не `app_settings`). Обязательная safety-мнемоника MVP: + +| mnemonic | Назначение | +|---|---| +| `safety.chat.blocked` | Generic company-реплика при любом Message Safety deny; текст locale-aware, без раскрытия `rule_id` | + +Миграция/seed обязаны создать активную запись минимум для `ru`. Изменение `text_value` не требует redeploy Safety и не меняет API/error code. --- @@ -131,6 +147,7 @@ chat.attachments.storage=selectel_s3 chat.attachments.upload_mode=presigned_put chat.attachments.safety_scan_required=true chat.attachments.presigned_upload_ttl_seconds=600 +messages.max_text_length=4000 rate_limit.message_send.per_user=30/minute rate_limit.message_send.per_dialog=20/minute @@ -174,21 +191,32 @@ worker.poll_interval_ms=500 worker.lease_seconds=90 ``` -В `.env` остаются только `SMS_DATABASE_URL`, URL внутренних/внешних сервисов, service tokens, Direct API key и callback credentials. Детальный контракт — `module-11-idgtl-sms.md`. +В `.env` остаются только несекретные URL внутренних/внешних сервисов и технические параметры. `SMS_DATABASE_URL`, service tokens, Direct API key и callback credentials входят в runtime secret catalog. Детальный контракт — `module-11-idgtl-sms.md`. `` — обязательный deployment placeholder, а не допустимое production-значение. Перед real mode должны существовать active approved template `auth_otp` с точными placeholders `code`/`ttl_min` и согласованный `senderName`. Отсутствие template/sender делает readiness false. --- +## Service-owned настройки `message-safety` + +Runtime policy хранится в версионированной `message_safety.config_versions`, а не в `.env` и не в `han_app.app_settings`. Сюда входят task lease/deadline/attempts, internal rate/pending limits, retention/cache TTL, URL/DNS pipeline limits, ClamAV policy timeout/signature age и enabled file MIME/size policy. Полный schema/seed/activation contract — module-05 §10.1 и §15. + +`han_app.app_settings:chat.attachments.*` остаётся бизнес-настройкой api-backend. Message Safety не получает cross-schema read к `han_app`; файл допускается только при пересечении business allow-list, active safety policy и immutable detector manifest. Active policy может сузить manifest, но не добавить parser и не увеличить hard limit. + +В env Message Safety остаются только bootstrap/topology/capacity (`APP_ENV`, worker concurrency, DNS resolver, ClamAV/S3/OTLP endpoints); credentials доставляются secret files. Rules/detector versions вычисляются/проверяются по immutable artifacts. Emergency MOCK остаётся в отдельном root-owned mode file и намеренно не переносится в БД. + +--- + ## Пример `.env.example` -Только инфраструктура. Бизнес-параметры — в seed `app_settings`. +Только несекретная инфраструктура и выбор secret source. Бизнес-параметры — в seed `app_settings`, а перечисленные ниже runtime secrets — в конфигурации `han-secrets`, не в этом файле. ```text # ============================================================================= # Общие # ============================================================================= APP_ENV=production-like +SECRETS_SOURCE=selectel API_PORT=8000 LOG_LEVEL=INFO @@ -199,14 +227,10 @@ HAN_PG_HOST= HAN_PG_PORT=5433 HAN_PG_DATABASE=han_chat -DATABASE_URL=postgresql+asyncpg://han_app:change-me@:/ -BITRIX_DATABASE_URL=postgresql://bitrix_local_app:change-me@:/ -BITRIX_SYNC_APP_DATABASE_URL=postgresql://bitrix_sync_user:change-me@:/ -BITRIX_SYNC_DATABASE_URL=postgresql://bitrix_sync_user:change-me@:/ -MESSAGE_SAFETY_DATABASE_URL=postgresql://message_safety_app:change-me@:/ -SMS_DATABASE_URL=postgresql://sms_user:change-me@:/ -KEYCLOAK_DB_URL=jdbc:postgresql://:/?user=keycloak_user&password=change-me¤tSchema=keycloak KC_DB_URL_PROPERTIES=currentSchema=keycloak +# Runtime secrets: DATABASE_URL, BITRIX_DATABASE_URL, +# BITRIX_SYNC_APP_DATABASE_URL, BITRIX_SYNC_DATABASE_URL, +# MESSAGE_SAFETY_DATABASE_URL, SMS_DATABASE_URL, KEYCLOAK_DB_URL. # Selectel PgBouncer 5433: pool_mode=session; search_path задаётся на уровне ролей. # Не добавлять options=-csearch_path: pooler отклоняет этот startup parameter. @@ -245,51 +269,45 @@ KEYCLOAK_INTERNAL_URL=http://keycloak:8080 KEYCLOAK_REALM=han-chat KEYCLOAK_AUDIENCE=han-chat-api KEYCLOAK_OTP_MOCK_ENABLED=true -KEYCLOAK_OTP_MOCK_CODE=1234 KEYCLOAK_YANDEX_CAPTCHA_ENABLED=false KEYCLOAK_YANDEX_CAPTCHA_CLIENT_KEY= -KEYCLOAK_YANDEX_CAPTCHA_SERVER_KEY= KEYCLOAK_SMS_SERVICE_URL=http://sms-service:8080 +# Runtime secrets: KEYCLOAK_OTP_MOCK_CODE, +# KEYCLOAK_YANDEX_CAPTCHA_SERVER_KEY and OTP HMAC/bootstrap credentials. # ============================================================================= -# Redis (I4: раздельные DB index) +# Redis ВМ1 (I4: раздельные DB index) # ============================================================================= # /0 — api-backend: rate limits, idempotency # /1 — api-backend realtime/coordination (опционально; можно совместить с /0) -# /2 — message-safety: verdict cache / workers REDIS_URL=redis://redis:6379/0 REDIS_REALTIME_URL=redis://redis:6379/1 -MESSAGE_SAFETY_REDIS_URL=redis://redis:6379/2 # ============================================================================= -# Service tokens (internal API) — все переменные только в backend/.env +# Service tokens (internal API) — runtime secret catalog, не .env # ============================================================================= -MESSAGE_SAFETY_SERVICE_TOKEN=change-me -BITRIX_LOCAL_APP_INTERNAL_TOKEN=change-me -BITRIX_API_INBOX_TOKEN=change-me -BITRIX_INTERNAL_API_TOKEN=change-me -BITRIX_API_FORWARD_TOKEN=change-me -BITRIX_SYNC_SERVICE_TOKEN=change-me -KEYCLOAK_SETTINGS_BRIDGE_TOKEN=change-me -SMS_SERVICE_TOKEN=change-me -KEYCLOAK_SMS_SERVICE_TOKEN=change-me -NOTIFICATIONS_TOKEN_PRODUCER_TEST=change-me +# MESSAGE_SAFETY_SERVICE_TOKEN, BITRIX_LOCAL_APP_INTERNAL_TOKEN, +# BITRIX_API_INBOX_TOKEN, BITRIX_INTERNAL_API_TOKEN, +# BITRIX_API_FORWARD_TOKEN, BITRIX_SYNC_SERVICE_TOKEN, +# KEYCLOAK_SETTINGS_BRIDGE_TOKEN, SMS_SERVICE_TOKEN, +# KEYCLOAK_SMS_SERVICE_TOKEN, NOTIFICATIONS_TOKEN_PRODUCER_TEST. # ============================================================================= -# SMS provider (URL и секреты; runtime-параметры — sms.sms_setting) +# SMS provider (секреты — runtime secret catalog; параметры — sms.sms_setting) # ============================================================================= IDGTL_SMS_BASE_URL=https://direct.i-dgtl.ru -IDGTL_SMS_API_KEY=change-me IDGTL_SMS_CALLBACK_PUBLIC_URL=https://tohin.ru/callbacks/idgtl/sms -IDGTL_SMS_CALLBACK_USERNAME=change-me -IDGTL_SMS_CALLBACK_PASSWORD=change-me +# Runtime secrets: IDGTL_SMS_API_KEY, IDGTL_SMS_CALLBACK_USERNAME, +# IDGTL_SMS_CALLBACK_PASSWORD. # ============================================================================= # api-backend (интеграции + resilience I2) # ============================================================================= BITRIX_LOCAL_APP_BASE_URL=http://bitrix-local-app:8080 BITRIX_API_INBOX_PATH=/internal/openlines/v1/inbox -MESSAGE_SAFETY_URL=http://message-safety:8080 +MESSAGE_SAFETY_URL=https://processing.internal:8443 +MESSAGE_SAFETY_CA_FILE=/run/han-chat/secrets/processing-internal-ca.crt +MESSAGE_SAFETY_API_PREFIX=/internal/safety/v2 MESSAGE_SAFETY_CIRCUIT_FAILURE_THRESHOLD=5 MESSAGE_SAFETY_CIRCUIT_OPEN_SEC=30 BITRIX_LOCAL_APP_CIRCUIT_FAILURE_THRESHOLD=5 @@ -300,35 +318,58 @@ BITRIX_LOCAL_APP_HTTP_TIMEOUT_SEC=10 # bitrix-sync # ============================================================================= BITRIX_SYNC_ENABLED=true -BITRIX_SYNC_CRM_BASE_URL=https://han0107.bitrix24.ru -BITRIX_SYNC_CRM_WEBHOOK_URL=change-me -BITRIX_SYNC_CONTACT_MAP_INTERVAL_SEC=60 -BITRIX_SYNC_CONTACT_UPDATE_INTERVAL_SEC=30 -BITRIX_SYNC_CRM_MAX_CONCURRENCY=2 -BITRIX_SYNC_CONTACT_LIST_BATCH_SIZE=50 -BITRIX_SYNC_WEBHOOK_TOKEN=change-me +BITRIX_SYNC_MODE=full +BITRIX_SYNC_PORTAL_HOST=han0107.bitrix24.ru +BITRIX_SYNC_PORTAL_MEMBER_ID= +BITRIX_SYNC_PUBLIC_BASE_URL=https://processing.example.ru +BITRIX_WEBHOOK_ALLOWED_CIDRS= +BITRIX_SYNC_CONTACT_USER_ID_FIELD=UF_CRM_... +BITRIX_SYNC_CONTACT_REGISTERED_FIELD=UF_CRM_1778692456 +BITRIX_SYNC_CONTACT_CITIZENSHIP_FIELD=UF_CRM_1768493029 +BITRIX_SYNC_HTTP_TIMEOUT_SEC=10 +BITRIX_SYNC_DB_POOL_SIZE=5 +# Hot worker/rate/retry/reconciliation/alert parameters: +# versioned bitrix_sync.settings, не env. +# Runtime secrets: BITRIX_SYNC_DATABASE_URL, +# BITRIX_SYNC_CRM_REST_WEBHOOK_URL, +# BITRIX_SYNC_CONTACT_RECEIVER_TOKEN, +# BITRIX_SYNC_ALERT_RECEIVER_TOKEN, +# BITRIX_SYNC_SERVICE_TOKEN. # ============================================================================= # bitrix-local-app # ============================================================================= -BITRIX_CLIENT_ID=change-me -BITRIX_CLIENT_SECRET=change-me BITRIX_CONNECTOR_ID=han_mobile_app BITRIX_CONNECTOR_NAME=HAN Mobile App BITRIX_OPEN_LINE_ID=8 BITRIX_PUBLIC_BASE_URL=https://tohin.ru/bitrix BITRIX_API_FORWARD_URL=http://api-backend:8000/internal/openlines/v1/inbox -BITRIX_APPLICATION_TOKEN=change-me +# Runtime secrets: BITRIX_CLIENT_ID, BITRIX_CLIENT_SECRET, +# BITRIX_APPLICATION_TOKEN and token encryption key. # ============================================================================= -# message-safety (technical) +# api-backend → Message Safety (ВМ1 caller) # ============================================================================= -# POST check timeout; poll interval/max — бюджет sync-wait внутри POST .../messages (G4) MESSAGE_SAFETY_POST_TIMEOUT_SEC=5 MESSAGE_SAFETY_TASK_POLL_INTERVAL_SEC=2 MESSAGE_SAFETY_TASK_POLL_MAX_SEC=300 -MESSAGE_SAFETY_FILE_SCAN_TIMEOUT_SEC=60 -MESSAGE_SAFETY_RULES_VERSION=2026-01-01 +QUARANTINE_ORPHAN_RETENTION_HOURS=48 +HAN_APP_SAFETY_CHECKPOINT_RETENTION_DAYS=7 +HAN_APP_SAFETY_RECOVERY_MAX_SEC=1200 + +# ============================================================================= +# message-safety (ВМ2 bootstrap/topology/capacity) +# ============================================================================= +# Service runtime policy находится в message_safety.config_versions. +# Runtime secrets: MESSAGE_SAFETY_DATABASE_URL, +# MESSAGE_SAFETY_REDIS_URL=redis://message_safety:@redis:6379/0, +# MESSAGE_SAFETY_SERVICE_TOKEN, S3 quarantine read credentials. +# Emergency mode находится только в root-owned +# /etc/han-chat/message-safety-mode.env и меняется approved helper-ом. +MESSAGE_SAFETY_WORKER_CONCURRENCY=5 +MESSAGE_SAFETY_DNS_RESOLVERS= +MESSAGE_SAFETY_CLAMAV_HOST=clamd +MESSAGE_SAFETY_CLAMAV_PORT=3310 # ============================================================================= # Frontend (nginx) @@ -344,14 +385,14 @@ SELECTEL_S3_ENDPOINT_URL=https://s3.storage.selcloud.ru SELECTEL_S3_BUCKET_DOCUMENTS=han-chat-documents SELECTEL_S3_BUCKET_ATTACHMENTS=han-chat-attachments SELECTEL_S3_BUCKET_QUARANTINE=han-chat-quarantine -SELECTEL_S3_ACCESS_KEY=change-me -SELECTEL_S3_SECRET_KEY=change-me -SELECTEL_S3_QUARANTINE_READ_ACCESS_KEY=change-me -SELECTEL_S3_QUARANTINE_READ_SECRET_KEY=change-me +# Runtime secrets: SELECTEL_S3_ACCESS_KEY, SELECTEL_S3_SECRET_KEY, +# SELECTEL_S3_QUARANTINE_READ_ACCESS_KEY, +# SELECTEL_S3_QUARANTINE_READ_SECRET_KEY. # ============================================================================= # Observability # ============================================================================= +# На каждой VM это local Docker DNS; ВМ2 не указывает collector ВМ1. OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317 OTEL_SERVICE_NAME_API=api-backend OTEL_SERVICE_NAME_SMS_API=sms-service @@ -359,28 +400,28 @@ OTEL_SERVICE_NAME_SMS_WORKER=sms-worker OTEL_TRACES_SAMPLER=always_on SMS_METRICS_PORT=9464 OTEL_REMOTE_ENDPOINT=192.168.0.5:4317 -OTEL_REMOTE_AUTH_HEADER= OTEL_REMOTE_TLS_INSECURE=true OTEL_QUEUE_SIZE=10000 +# Runtime secret when configured: OTEL_REMOTE_AUTH_HEADER. ``` S3-клиенты используют только virtual-hosted addressing (`https://.s3.storage.selcloud.ru/`). Это часть контракта presigned URL и CORS Selectel; path-style адресация не поддерживается приложением. -Все переменные — **только** в `backend/.env`. Отдельного хранилища нет. +Production использует отдельные allow-listed env manifests ВМ1 и ВМ2; не все переменные примера копируются на оба хоста. На ВМ2 `han-secrets` под отдельным IAM principal материализует отдельный root-owned файл каждому сервису в `/run/han-chat/secrets`; общий bundle ВМ1/ВМ2 запрещён. -Для production `change-me`, `<...>`, примерные sender/template/API key/callback credentials отклоняются `validate-env`. `IDGTL_SMS_API_KEY` — выданный Direct готовый `TOKEN_1` для Basic, без повторного Base64. Реальный статический egress IP хранится в deployment inventory, а не env; если он не обеспечен NAT/сетевой конфигурацией, `KEYCLOAK_OTP_MOCK_ENABLED=false` запрещён. +Для production placeholders и примерные sender/template/credentials отклоняются `validate-env` и runtime manifest validation. `IDGTL_SMS_API_KEY` в secret catalog — выданный Direct готовый `TOKEN_1` для Basic, без повторного Base64. Реальный статический egress IP хранится в deployment inventory, а не env; если он не обеспечен NAT/сетевой конфигурацией, `KEYCLOAK_OTP_MOCK_ENABLED=false` запрещён. -**Webhook-токены** (публичные callback, не service API): `BITRIX_APPLICATION_TOKEN`, `BITRIX_SYNC_WEBHOOK_TOKEN`. +**Webhook-токены:** `BITRIX_APPLICATION_TOKEN` относится только к `bitrix-local-app`. CRM sync не использует local app/event handler; штатные HTTP-webhook роботы передают отдельные `BITRIX_SYNC_CONTACT_RECEIVER_TOKEN` и `BITRIX_SYNC_ALERT_RECEIVER_TOKEN` в query, поскольку custom Bearer header недоступен. Токены остаются secret-manager values, query исключается из logs/traces, а nginx дополнительно применяет `BITRIX_WEBHOOK_ALLOWED_CIDRS`. `BITRIX_SYNC_CRM_REST_WEBHOOK_URL` — отдельный секрет исходящего CRM REST-доступа sync-service. -`NOTIFICATIONS_TOKEN_` — индивидуальный секрет продюсера Internal Notifications API. Для seed/smoke используется `NOTIFICATIONS_TOKEN_PRODUCER_TEST`; secret хранится только в deployment env/secret, а `notification_sources.token_hash` — только hash. Инструкция не имеет `notification.instruction.allowed_hosts`: она всегда открывается в новой вкладке, iframe-режима нет. +`NOTIFICATIONS_TOKEN_` — индивидуальный секрет продюсера Internal Notifications API. Для seed/smoke используется `NOTIFICATIONS_TOKEN_PRODUCER_TEST`; secret хранится только в secret store/runtime secret file, а `notification_sources.token_hash` — только hash. Инструкция не имеет `notification.instruction.allowed_hosts`: она всегда открывается в новой вкладке, iframe-режима нет. ## Namespace переменных Bitrix - `bitrix-local-app`: `BITRIX_CLIENT_*`, `BITRIX_CONNECTOR_*`, `BITRIX_PUBLIC_BASE_URL`, `BITRIX_DATABASE_URL`, `BITRIX_API_FORWARD_URL`, `BITRIX_APPLICATION_TOKEN` + service tokens. - `api-backend`: `BITRIX_LOCAL_APP_BASE_URL`, `MESSAGE_SAFETY_URL`, circuit/timeout vars, Redis `/0`/`/1` + service tokens; **бизнес-настройки** — из `app_settings`. OTP counters **не** ведёт. -- `bitrix-sync`: `BITRIX_SYNC_ENABLED`, `BITRIX_SYNC_*`, `BITRIX_SYNC_WEBHOOK_TOKEN`, `BITRIX_SYNC_SERVICE_TOKEN`. +- `bitrix-sync`: non-secret `BITRIX_SYNC_ENABLED/MODE/PORTAL_HOST/PORTAL_MEMBER_ID`, `BITRIX_WEBHOOK_ALLOWED_CIDRS`, custom field names и capacity bootstrap; runtime secrets — database/inbound CRM REST webhook URL, Contact/alert receiver tokens и service token; hot policy — в `bitrix_sync.settings`. - `bitrix-sync` не читает `BITRIX_CLIENT_ID` / `BITRIX_CLIENT_SECRET`. ### `BITRIX_SYNC_ENABLED` @@ -390,7 +431,13 @@ presigned URL и CORS Selectel; path-style адресация не поддер | `true` (default) | `bitrix-sync` обрабатывает `sync_queue` и принимает CRM webhook | | `false` | синхронизация с Bitrix24 CRM не выполняется; сервис стартует в no-op/degraded режиме; чат Open Lines через `bitrix-local-app` **не** затрагивается | -В MVP выбран режим **no-op service**: контейнер `bitrix-sync` стартует, `/health/live` отвечает успешно, `/health/ready` возвращает degraded/not-ready с явной причиной `sync_disabled`, worker не обрабатывает `sync_queue`, webhook CRM возвращает безопасный `503` или `202 ignored` по контракту модуля. Это сохраняет единый compose-контур и не влияет на чат Open Lines. +При `false` контейнер остаётся live, `/health/ready` возвращает `503 sync_disabled`, worker/reconciliation не claim-ят работу. Public webhook не должен безусловно подтверждать событие как обработанное: до cutover endpoint закрывается на edge либо возвращает retryable `503`. Это не влияет на чат Open Lines. + +### `bitrix_sync.settings` + +Versioned hot settings содержат batch size/wait, claim size, lease TTL, portal limiter refill/burst, max in-flight, retry base/max/horizon, Contact/alert reconciliation intervals, пороги всплеска Contact, восстановленных без webhook, и IDs/стадии/поля/SLA smart process. Новая версия активируется только после полной type/range/cross-field validation; невалидная версия не заменяет последнюю рабочую. + +Secrets, DSN, portal host/member ID, inbound source IP CIDR allow-list, custom Contact field names и cutover watermark не являются hot settings. Полный каталог и defaults — [`../modules/module-07-bitrix-sync.md`](../modules/module-07-bitrix-sync.md), §12. ## Keycloak settings bridge для OTP @@ -414,6 +461,7 @@ Challenge сохраняет snapshot TTL, длины кода и `settings_vers | `chat.attachments.allowed_extensions` | `jpg`, `jpeg`, `png`, `webp`, `heic`, `heif`, `pdf` | | `chat.attachments.allowed_mime_types` | `image/jpeg`, `image/png`, `image/webp`, `image/heic`, `image/heif`, `application/pdf` | | `chat.attachments.max_size_mb` | `5` | +| `messages.max_text_length` | `4000` (public/business limit; Safety hard ceiling остаётся `10000`) | Правило: файл принимается только если **и** расширение, **и** MIME в allow-list. Детальная проверка — модуль `message-safety`. diff --git a/architectory/arch-05-agent-development-process.md b/architectory/arch-05-agent-development-process.md index 0c66234..a3b4e3f 100644 --- a/architectory/arch-05-agent-development-process.md +++ b/architectory/arch-05-agent-development-process.md @@ -1,6 +1,6 @@ # arch-05. Правила разработки модулей отдельными агентами -> Термины — в [`arch-00-glossary.md`](arch-00-glossary.md). Настоящий документ описывает процесс разработки и не переопределяет архитектуру. Иерархия приоритета — в [`README.md`](README.md), раздел «Разрешение конфликтов». +> Термины — в [`arch-00-glossary.md`](arch-00-glossary.md). Безопасность VM и production-деплоя — в [`arch-06-service-hosting-security.md`](arch-06-service-hosting-security.md). Настоящий документ описывает процесс разработки и не переопределяет архитектуру. Иерархия приоритета — в [`README.md`](README.md), раздел «Разрешение конфликтов». ## Цель @@ -11,10 +11,19 @@ - Перед разработкой агент читает [`README.md`](README.md), архитектурные документы и профильный документ назначенного модуля. - Любое изменение публичного API сопровождается обновлением OpenAPI. - Любое изменение структуры данных сопровождается миграцией. -- Все **бизнес-параметры** — в таблице `app_settings`; **infra и секреты** — в `.env`. +- Все **бизнес-параметры** — в таблице `app_settings`; несекретная **infra** — в `.env`; production-секреты — только через механизм arch-06. - Нельзя hardcode-ить телефоны, лимиты, тексты, mime types, feature flags и параметры Битрикс24. - Модули, принимающие пользовательский ввод, должны учитывать rate limits и security/safety проверки. +## Размещение и production-деплой + +- Изменение deployment, VM topology, network exposure, volumes, Linux capabilities, OS/sudo-прав или способа доставки секретов требует impact analysis по arch-06. +- Агент не добавляет `deploy` в группу `docker` и не расширяет sudo wildcard-командами. Новое право оформляется как конкретная операция над конкретным systemd-unit с review и rollback. +- Production compose, systemd-units, deploy scripts и secret mappings остаются root-owned и недоступны `deploy` на запись. +- Для private/no-egress VM допустим временный bootstrap с SSH из trusted ops CIDR и ограниченным egress для пакетов/образов. +- Раскатка private/no-egress VM считается незавершённой, пока не выполнен lockdown: public ingress/SSH и общий egress закрыты, private access проверен, а недоступность снаружи зафиксирована. +- Повторное открытие ingress/egress после lockdown — документированная break-glass операция с обязательным возвратом в lockdown, а не штатный способ деплоя. + ## Правила базы данных - Перечень таблиц, полей, индексов и миграций **определяет модуль-владелец** (`database`, `api-backend`, `bitrix-sync`, `message-safety`, `bitrix-local-app`), а не arch-*. @@ -39,6 +48,7 @@ Правила: - endpoint naming должен следовать `arch-02-api-contracts.md`; +- cross-VM contract test обязан запускать caller и callee как разные network zones: private DNS, verified internal CA, service token, timeout/circuit и запрет plaintext; Docker hostname вынесенного сервиса не считается валидным remote test; - response schema не должна раскрывать внутренние поля; - ошибки возвращаются в едином формате; - для пользовательских данных всегда используется текущий user context из JWT; @@ -86,8 +96,13 @@ Raw OTP запрещено хранить в открытом виде: это - обновлены каталог ошибок в `arch-02` и contract tests, если менялась публичная или internal HTTP-семантика; - созданы миграции, если менялась БД; - обновлены seed `app_settings` и `.env.example`, если добавлялись настройки, service tokens, лимиты или feature flags; +- secret value не добавлен в `.env.example`; новый секрет включён только в runtime secret catalog и выдан минимальному набору сервисов; - добавлены тесты; -- сервис запускается в Docker Compose; +- сервис запускается в root Docker Compose своей VM; CI отдельно валидирует оба projects и отсутствие cross-host `depends_on`/Docker DNS; +- remote Message Safety contract tests покрывают v2 `202 + Location + Retry-After`, sticky final result, terminal failed `503`, `409` invariant mapping и legacy v1 migration adapter; +- container проверен по arch-06: non-root, `no-new-privileges`, capabilities, read-only filesystem/writable paths, volumes, networks и resource limits; +- изменение прав `deploy`, systemd, network exposure, capabilities, volumes или secret delivery отражено в arch-06 и deployment runbook; +- для private/no-egress VM выполнен и зафиксирован bootstrap→lockdown checklist; - worker, указанный в Compose/runbook, имеет реально зарегистрированный entrypoint в image; deployment не может заранее выдумывать имя команды; - все изменяемые параметры вынесены из кода; - логи содержат `request_id`, `trace_id` и **`ux_session_id`** (если передан в запросе); diff --git a/architectory/arch-06-service-hosting-security.md b/architectory/arch-06-service-hosting-security.md new file mode 100644 index 0000000..1b71853 --- /dev/null +++ b/architectory/arch-06-service-hosting-security.md @@ -0,0 +1,576 @@ +# arch-06. Стандарт безопасности размещения сервисов + +> Общие границы системы и прикладная безопасность — в [`arch-01-system-architecture.md`](arch-01-system-architecture.md). Docker Compose, nginx и сети контейнеров — в [`arch-03-docker-compose-blueprint.md`](arch-03-docker-compose-blueprint.md). Настройки и секреты — в [`arch-04-settings-and-content.md`](arch-04-settings-and-content.md). Процесс разработки и Definition of Done — в [`arch-05-agent-development-process.md`](arch-05-agent-development-process.md). + +## Назначение + +Документ задаёт обязательный минимальный стандарт размещения сервисов HAN на виртуальных машинах, подготовки VM и production-деплоя. + +Главная цель — ограничить последствия компрометации отдельного сервиса: захват процесса или контейнера не должен автоматически давать доступ к host OS, Docker daemon, соседним сервисам, чужим секретам или всей private network. + +Стандарт применяется к: + +- VM с публичной точкой входа; +- внутренним VM в private network; +- VM без постоянного доступа в интернет, включая SigNoz; +- пользователям `deploy`, `admin` и `tunnel`; +- systemd-юнитам, Docker Compose и deployment-артефактам. + +Если конкретный сервис не может выполнить требование, отклонение должно быть явно описано в его спецификации: причина, риск, компенсирующая мера, владелец и срок пересмотра. Молчаливое ослабление требований запрещено. + +## Модель угроз и границы доверия + +Базовое допущение: атакующий может добиться выполнения кода внутри одного прикладного контейнера. + +После этого он не должен получить: + +- доступ к Docker socket или Docker API; +- root на host OS; +- возможность менять compose-файлы, systemd-юниты, deployment-скрипты или `sudoers`; +- секреты сервисов, которые не нужны скомпрометированному процессу; +- произвольный доступ к PostgreSQL, S3 и другим VM; +- возможность публиковать новый host port или подключать host directories; +- постоянный канал управления через неограниченный исходящий трафик. + +Изоляция строится несколькими независимыми слоями: IAM и секреты, Unix-права, systemd/sudo, настройки контейнера, Docker networks, host firewall и cloud security groups. Один слой не считается заменой остальных. + +## Классы VM + +### VM с постоянным egress + +VM имеет только утверждённые исходящие направления, необходимые сервисам: Selectel Secrets Manager, S3, внешние API, package/image registry и DNS/NTP по принятой схеме. + +Постоянный egress не означает unrestricted internet access. Направления и назначение фиксируются в deployment inventory; лишние правила удаляются. + +### Private/no-egress VM + +В steady state VM: + +- не принимает соединения из интернета; +- не имеет общего выхода в интернет; +- принимает только явно разрешённый трафик из private network; +- администрируется через утверждённую private точку входа: bastion/основную VM или VPN. + +SigNoz относится к этому классу, если его UI, OTLP и SSH доступны только из private network. + +### Каноническая классификация ВМ2 Processing + +ВМ2 с `message-safety` и `bitrix-sync` — **самостоятельная service VM с минимальным public ingress и постоянным ограниченным egress**: + +- собственный public DNS/IP или dedicated LB направляет `80/443` только на nginx ВМ2; +- public `80` обслуживает только ACME challenge/HTTPS redirect; +- public `443` разрешает только exact `/bitrix/sync/webhook/contact` и `/bitrix/sync/webhook/alert`; остальные paths закрыты; +- private ingress `8443/tcp` разрешён только от security group ВМ1 и утверждённого ops path для Message Safety/internal API; +- ни один public запрос ВМ2 не проходит через nginx ВМ1; +- `freshclam` имеет egress только к утверждённым источникам сигнатур; +- `bitrix-sync` имеет HTTPS egress только к утверждённому порталу Bitrix24; +- Safety worker имеет доступ только к managed PostgreSQL, S3-quarantine и доверенному DNS resolver; +- локальный OTEL Collector имеет private egress к SigNoz; +- registry, package repositories и OS updates открываются только в bootstrap/controlled maintenance window. + +ВМ2 использует отдельный cloud IAM principal. `han-secrets` получает только секреты сервисов ВМ2 и материализует раздельные root-owned файлы на tmpfs; общий secret bundle с ВМ1 запрещён. На ВМ2 один root Compose project и отдельный root-owned systemd deployment unit. + +Для схемы `message_safety` разделяются DB roles: API/worker runtime читает active/исторические `config_versions`, но не создаёт и не активирует их; migration/config-admin role используется только controlled job и имеет право version activation. Config не содержит secrets, endpoint topology или MOCK flags. + +Public и private ingress ВМ2 завершаются разными server blocks одного nginx без общего fallback. Public block использует сертификат доверенного CA и до proxy ограничивает Contact/alert webhook version-controlled source IP CIDR allow-list. Штатный робот передаёт отдельный receiver token в query и `application/x-www-form-urlencoded` body; query/body исключаются из logs/traces, а upstream проверяет token и document/entity/domain/member fields. Server-to-server ingress `8443` использует внутренний CA и service token вторым слоем. mTLS не обязателен для MVP. + +## Lifecycle private/no-egress VM + +Этот lifecycle применяется к SigNoz и иным полностью private VM. Для ВМ2 обязательный public webhook ingress `80/443` после bootstrap не удаляется; вместо этого проверяются exact route и source IP CIDR allow-list, а SSH и все прочие public ports закрываются. Новый IP не добавляется автоматически: всплеск восстановлений Contact инкрементальной reconciliation инициирует проверку rejected-IP telemetry и controlled review allow-list. + +Для первичной раскатки применяется двухфазный процесс. + +```mermaid +flowchart LR + Bootstrap[Bootstrap_phase] + Verify[Verify_services_and_private_links] + Lockdown[Steady_state_lockdown] + Bootstrap -->|"temporary public SSH and package egress"| Verify + Verify -->|"remove public ingress and egress"| Lockdown +``` + +### Фаза bootstrap + +На ограниченное время разрешаются: + +- SSH из утверждённого trusted ops CIDR, а не из `0.0.0.0/0` - управляется через группу безопасности облачного провайдера; +- egress, необходимый для обновлений ОС, установки пакетов и получения pinned images/artifacts; +- доступ `deploy` и `admin` в пределах правил этого документа. + +До перехода в lockdown необходимо: + +1. установить обновления и минимальный набор пакетов; +2. установить и проверить host firewall и fail2ban; +3. развернуть сервисы и секреты; +4. проверить health/readiness; +5. проверить требуемые private-соединения в обоих направлениях; +6. подтвердить альтернативный private путь администрирования; +7. сохранить rollback-инструкцию и inventory разрешённых соединений. + +### Фаза lockdown + +После проверки: + +- public IP удаляется, если он больше не нужен; +- публичный SSH и любой иной internet ingress удаляются из cloud security group; +- host firewall принимает административный и прикладной трафик только из утверждённых private CIDR/SG; +- общий internet egress закрывается на cloud и host-уровне; +- временные bootstrap credentials, правила, installer-файлы и package caches удаляются, если они больше не нужны; +- с внешней сети проверяется недоступность SSH и сервисных портов; +- с VM проверяется запрет неразрешённого egress; +- из private network повторно проверяются SSH и обязательные service flows. + +Раскатка private/no-egress VM не завершена, пока lockdown и обе группы проверок не зафиксированы в deployment checklist. + +### Повторное открытие + +Временное открытие ingress/egress после lockdown — break-glass операция: + +1. фиксируются причина, исполнитель, окно работ и необходимые destination/ports; +2. правило ограничивается trusted CIDR и минимальным сроком; +3. после работ правила удаляются; +4. повторяются проверки lockdown; +5. факт закрытия фиксируется в runbook/журнале изменений. + +Постоянно оставлять bootstrap-доступ «для будущих обновлений» запрещено. + +## Пользователи host OS + +### `deploy` + +Используется для штатного деплоя. Пользователь: + +- не входит в группы `docker`, `root` и другие root-equivalent группы; +- не имеет общего `sudo`, shell root и `sudoedit`; +- не меняет compose-файлы, systemd-юниты, deployment-скрипты и конфигурацию секретов; +- может записывать только в выделенный incoming/staging-каталог; +- может запускать только заранее утверждённые операции над конкретными systemd-юнитами; +- на ВМ2 может запускать пять exact-argument вариантов root-owned Message Safety mode helper; +- читает только логи своего стека, без доступа к секретам других сервисов. + +Членство в группе `docker` считается эквивалентом root и запрещено. + +### `admin` + +Break-glass пользователь для восстановления: + +- не используется для штатного деплоя; +- имеет персональные SSH-ключи, а не общий ключ команды; +- доступен только из trusted ops network/VPN, а для private VM — только через private path после lockdown; +- расширенные sudo-права выдаются осознанно и аудируются; +- ключи хранятся отдельно от deploy credentials и регулярно пересматриваются. + +Доступ через cloud console/recovery mode также считается break-glass и должен быть ограничен ролями облачного проекта. + +### `tunnel` + +Отдельный пользователь основной/bastion VM для доступа к PostgreSQL и другим private endpoints: + +- не имеет sudo; +- не входит в deployment-группы; +- не получает доступ к секретам приложения; +- разрешает только local TCP forwarding; +- имеет allow-list конкретных `host:port` через `PermitOpen`; +- использует login shell `/usr/sbin/nologin` (после отдельной проверки, что forwarding-only соединение работает); +- не разрешает agent forwarding, X11 forwarding и TTY; +- ключ ограничивается теми же возможностями в `authorized_keys`. + +Произвольный SOCKS proxy и forwarding на неутверждённые адреса запрещены. Настройка должна быть проверена отдельной SSH-сессией до отключения старого пути. + +### Root + +- `PermitRootLogin no`; +- пароль root заблокирован (`passwd -l root`) как дополнительная мера; +- штатные операции выполняются через именных пользователей; +- прямой root допускается только механизмом recovery провайдера при инциденте. + +## SSH baseline + +Минимальные настройки production VM: + +```text +PermitRootLogin no +PasswordAuthentication no +KbdInteractiveAuthentication no +PubkeyAuthentication yes +MaxAuthTries 3 +AllowAgentForwarding no +X11Forwarding no +AllowUsers deploy admin tunnel +``` + +Дополнительно: + +- SSH для Private/no-egress VM разрешается cloud SG и host firewall только из trusted ops CIDR/VPN/private network; +- ключи пользователей индивидуальны; общий приватный ключ запрещён; +- устаревшие алгоритмы и пустые пароли запрещены; +- fail2ban включается на VM, где SSH хотя бы временно доступен из интернета; +- `AllowTcpForwarding no` задаётся по умолчанию, а исключение `local` — только в `Match User tunnel`; +- после изменения выполняется проверка конфигурации sshd и вход во второй независимой сессии; +- текущую рабочую сессию не закрывают до успешной проверки нового доступа. + +`AllowUsers` должен содержать только реально созданные учётные записи. Неиспользуемая роль не создаётся «на будущее». + +## Права `deploy` и production-деплой + +### Управление только через systemd + +`deploy` не запускает `docker`, `docker compose` или произвольные root-скрипты через sudo. Docker Compose запускается root-owned systemd-юнитом или root-owned deployment helper с фиксированным интерфейсом. + +Sudoers хранится только в `/etc/sudoers.d/deploy` и проверяется через `visudo`. `/etc/sudoers` напрямую не редактируется. + +Разрешения перечисляют полные команды и конкретные unit names без wildcard. Принципиальный пример: + +```sudoers +Cmnd_Alias HAN_STATUS = /usr/bin/systemctl --no-pager status han-stack.service +Cmnd_Alias HAN_DEPLOY = /usr/bin/systemctl start han-deploy.service, \ + /usr/bin/systemctl restart han-stack.service +Cmnd_Alias HAN_LOGS = /usr/bin/journalctl --no-pager -u han-stack.service +Cmnd_Alias HAN_SAFETY_MODE = /usr/local/sbin/han-message-safety-mode standard, \ + /usr/local/sbin/han-message-safety-mode mock --text-free true --file-free true, \ + /usr/local/sbin/han-message-safety-mode mock --text-free true --file-free false, \ + /usr/local/sbin/han-message-safety-mode mock --text-free false --file-free true, \ + /usr/local/sbin/han-message-safety-mode mock --text-free false --file-free false +deploy ALL=(root) NOPASSWD: HAN_STATUS, HAN_DEPLOY, HAN_LOGS, HAN_SAFETY_MODE +``` + +Фактические пути сверяются через `command -v`; разрешается только необходимый набор. Нельзя разрешать: + +- `systemctl *`, `journalctl *`, wildcard в unit name; +- `systemctl status`/`journalctl` с интерактивным pager (он может дать shell escape под root); +- shell, editor, package manager, `cp`, `mv`, `chmod`, `chown`; +- произвольный путь к compose-файлу или environment-файлу; +- команды с параметрами, позволяющими подменить unit, working directory, image или mount. + +`han-message-safety-mode` — исключение с конечным exact-argument allow-list, а не произвольный root-script. Он принадлежит `root:root`, недоступен `deploy` на запись, не принимает paths/commands/env expansion, атомарно меняет только `root:han-message-safety 0640` `/etc/han-chat/message-safety-mode.env`; dedicated host group имеет GID `10001`, совпадающий с primary GID non-root контейнера. Helper валидирует конфигурацию и выполняет только фиксированную Message Safety API recreate/restart operation внутри root Compose project. MOCK не имеет автоматического срока действия; выключение — отдельная явная команда `standard`. Все вызовы и old/new mode аудируются. + +### Ownership deployment-файлов + +Root-owned и недоступны `deploy` на запись: + +- `/etc/systemd/system/han-*.service`; +- production compose-файлы; +- deploy/helper scripts; +- `/etc/han-chat/message-safety-mode.env`; +- `/etc/sudoers.d/deploy`; +- secret mappings и credentials; +- active release manifest. + +`deploy` может загружать артефакты только в отдельный каталог, например `/var/lib/han-deploy/incoming`, без права менять его parent. Активация выполняется фиксированным root-owned процессом после проверок: + +- артефакт относится к ожидаемому проекту и версии; +- digest/signature соответствует approved release; +- отсутствуют symlink/path traversal; +- compose config прошёл валидацию; +- image reference pinned по version/digest; +- миграции и rollout соответствуют release manifest. + +Если такого валидатора пока нет, compose/unit changes выполняет `admin`, а `deploy` ограничивается запуском уже подготовленного релиза. Выдавать `deploy` запись в production compose — не допустимая замена автоматизации. + +Shell-артефакты (`*.sh`, entrypoint, hooks и helpers) обязаны поставляться с +LF line endings. Репозиторий фиксирует это через `.gitattributes`, а release +preflight проверяет отсутствие `CRLF` до активации. Ошибка вида +`cannot execute: required file not found` при существующем executable-файле +считается признаком некорректного shebang/line endings, а не основанием менять +права или запускать файл через обходной интерпретатор. + +## Изменение прав `deploy` + +Новая доработка не получает дополнительные права автоматически. В change request указываются: + +1. требуемая операция и конкретный systemd unit; +2. почему существующего интерфейса недостаточно; +3. полный executable path и фиксированные аргументы; +4. какие root-owned файлы читает или меняет операция; +5. возможность command/path/argument injection; +6. тест негативных сценариев; +7. способ отзыва права и rollback. + +Изменение: + +- проходит review владельца инфраструктуры/безопасности; +- вносится отдельным файлом в `/etc/sudoers.d`; +- проверяется `visudo`; +- сначала проверяется в production-like среде; +- отражается в этом документе и deployment runbook; +- после rollout подтверждается через `sudo -l`, что лишних прав нет. + +Wildcard, временный `NOPASSWD: ALL` и включение в `docker` group запрещены даже как «временное» решение. + +## Секреты + +### Общие требования + +- секреты не коммитятся и не хранятся в обычном `.env`; +- `.env` содержит только несекретную конфигурацию и ссылки/имена secret files; +- контейнер получает только необходимые ему секреты; +- общий файл со всеми секретами стека не монтируется во все контейнеры; +- секреты не передаются в command line, build args, image layers и логи; +- runtime secret files доступны только root и целевому process UID/GID; +- ротация не требует выдачи сервису доступа к чужим секретам; +- приложение не выступает сетевым прокси секретов для других VM. + +Значения `uid`, `gid` и `mode` в Compose file secrets нельзя считать +security boundary: Docker Compose при bind-backed secret может их игнорировать. +Фактические owner/mode задаются host-side materializer'ом и проверяются через +`stat` и негативный тест от постороннего UID. Предупреждение Compose об +игнорировании этих атрибутов не подавляется и не трактуется как подтверждение +прав. + +Структурированные секреты валидируются до старта потребителя. Для PEM это +означает проверку парсинга certificate/private key, отсутствие повторного +base64 или литеральных `\n`, соответствие public key и запрет зашифрованного +private key, если сервис не поддерживает non-interactive passphrase. + +### VM с egress: `han-secrets` + +На VM с утверждённым доступом к Selectel: + +- один host-side `han-secrets` запускается через systemd до старта стека; +- используется отдельный IAM principal на VM/контур; +- IAM разрешает чтение только секретов сервисов этой VM; +- контейнеры не получают cloud IAM credentials и сами не обращаются в Secrets Manager; +- materialized secrets размещаются в `/run/han-chat/secrets` на tmpfs; +- ошибка получения обязательного секрета блокирует rollout (fail closed); +- автоматический fallback с Selectel на локальный production-файл запрещён. + +Использование единой реализации `han-secrets` на нескольких VM допустимо; общая IAM-учётная запись и общий набор секретов — нет. + +### Private/no-egress VM + +Cloud sync не требуется. `admin` во время bootstrap: + +- получает минимальный набор секретов по защищённому каналу; +- размещает их в root-owned каталоге вне репозитория; +- задаёт каталогам `0700`, файлам `0400` или более узкие ACL для целевого UID; +- по возможности передаёт их процессу как systemd credentials или read-only secret files; +- удаляет временную копию и историю команд; +- фиксирует fingerprint/version секрета без его значения. + +Допускается `han-secrets` в локальном `file`-режиме как единый loader, но он не должен создавать egress или зависимость от основной app-VM. Для ротации используется повторная контролируемая provisioning-процедура. + +## DB roles и migration boundary + +Runtime, migration и config-admin роли разделяются для каждого сервиса. +Runtime-role не получает DDL, ownership схемы или право менять immutable +configuration. Migration-role монтируется только в controlled job и не +передаётся runtime-контейнерам. + +Cross-schema migration не получает постоянный broad access. Если ей нужно +однократно перенести legacy data: + +1. владелец исходной схемы или DB administrator выдаёт именованной + migration-role минимальные временные `USAGE` на schema и `SELECT` на + конкретную таблицу; +2. migration копирует данные и fail-closed проверяет полноту переноса; +3. владелец/администратор отзывает временные права после успешного commit. + +Migration-role не выполняет `REVOKE`, `ALTER` или `DROP` на объекте чужого +owner. Такие contract-операции принадлежат owner migration исходного сервиса +либо отдельной административной процедуре. Проверку существования объекта +нельзя реализовывать как «нет доступа — значит объекта нет»: permission error +должен блокировать rollout, иначе legacy data может быть молча пропущена. + +Alembic graph обязан сохранять известные ранее выданные revision IDs, включая +no-op baseline revisions. Удаление revision из нового image при наличии её в +`alembic_version` запрещено; совместимость обеспечивается bridge/no-op +revision, а не ручным `stamp` или правкой production DB. + +## Права на каталоги + +Базовая модель: + +| Путь | Владелец / режим | Назначение | +|---|---|---| +| `/opt/han-chat/releases/` | `root:root`, `0755`/файлы `0644` | immutable release | +| `/opt/han-chat/current` | `root:root` | active release link; меняет только deployment helper/admin | +| `/var/lib/han-deploy/incoming` | `deploy:deploy`, `0750` | загрузка неактивированных артефактов | +| `/etc/han` | `root:root`, `0750` или строже | конфигурация и secret mappings | +| `/run/han-chat/secrets` | `root:root`, `0700` | runtime secrets на tmpfs | +| `/var/lib/han-chat/public-tls` | `root:han-nginx-tls`, `0750`; key/cert `0640` | минимальный TLS staging для non-root edge | +| `/var/lib/han-chat/acme` | `root:root`, `0755` | ACME webroot без private key | +| `/var/lib/han-chat/` | UID сервиса, минимальные права | service state | +| `/var/log/han-chat` | root/service group, без world-read | host-side логи при необходимости | + +Требования: + +- world-writable каталоги в deployment path запрещены; +- setuid/setgid binaries не добавляются без обоснования; +- сервис не получает write к каталогу с executable/config, если ему нужен только state; +- bind mounts задаются read-only, кроме явно выделенных state/upload paths; +- backup-файлы и дампы получают не менее строгие права, чем исходные данные; +- symlinks из writable каталога не используются привилегированным helper без безопасной проверки. + +## Hardening контейнеров + +Для каждого production-контейнера обязательна оценка и, где применимо, конфигурация: + +```yaml +services: + service: + user: "10001:10001" + read_only: true + security_opt: + - no-new-privileges:true + cap_drop: + - ALL + tmpfs: + - /tmp:rw,noexec,nosuid,nodev +``` + +Базовые правила: + +- процесс запускается непривилегированным UID/GID; +- root в контейнере допускается только с документированным обоснованием; +- `privileged: true` запрещён; +- `network_mode: host`, `pid: host`, `ipc: host` и `userns_mode: host` запрещены; +- Docker socket/API не монтируется; +- Linux capabilities удаляются все, затем точечно возвращаются необходимые; +- root filesystem read-only; writable paths — отдельные volume/tmpfs; +- mount host paths минимален и read-only; +- default seccomp сохраняется; AppArmor/аналог провайдера включается, если доступен; +- задаются CPU/memory/PID limits, restart policy и healthcheck; +- сервис подключается только к необходимым Docker networks; +- внешний `ports:` разрешён только утверждённой edge-точке; +- image использует pinned version/digest, проходит vulnerability scan и не содержит package managers/compilers без необходимости; +- секреты не копируются в image и не доступны healthcheck-команде. + +Если контейнер не может работать с `read_only`, в спецификации перечисляются конкретные writable paths. Полное отключение `read_only` без анализа запрещено. + +### Проверка совместимости image с hardening + +Non-root UID сам по себе недостаточен. Для каждого pinned digest до rollout +составляется inventory всех путей, куда пишет entrypoint и процесс: +runtime/socket, cache/temp, generated config, logs и persistent state. Каждый +путь получает отдельный volume/tmpfs с минимальным размером и явными +`uid/gid/mode`; writable root filesystem, запуск root или возврат capabilities +не используются как универсальный workaround. + +Проверяется не только основной binary, но и image entrypoint. Если vendor image +имеет отдельный unprivileged entrypoint, при принудительном `user` используется +именно он. Root entrypoint, который делает `mkdir/chown`, несовместим с +non-root + `read_only`, даже если сам daemon способен работать без root. + +Изменение image digest повторяет эти проверки: tag/version, entrypoint, +writable-path inventory, healthcheck semantics и фактический UID/GID считаются +частью security contract образа. + +### TLS для non-root edge + +Root-only дерево ACME/Certbot не монтируется целиком в non-root nginx и не +делается world-readable. Host-side root hook атомарно копирует только +`fullchain.pem` и `privkey.pem` в выделенный staging-каталог с группой +`han-nginx-tls` (канонический GID `11001`); nginx получает этот каталог +read-only. Renewal hook сначала обновляет staged files, затем выполняет полный +config test и только после успеха отправляет reload. Права и соответствие +certificate/key проверяются preflight. + +### Daemon и updater как разные security-профили + +Если один vendor image используется для daemon и updater, им задаются разные +сети, mounts и health semantics. Проверенный паттерн ClamAV: + +- `clamd` не имеет signature-CDN egress, читает signatures read-only и имеет + healthcheck реального daemon socket; +- `freshclam` один получает ограниченный egress и write к signatures; +- оба используют vendor `init-unprivileged` и только выделенные writable + `/run/clamav`, `/var/log/clamav` и `/tmp`; +- updater запускается как постоянный foreground daemon, чтобы restart policy + не превращала успешный one-shot exit в download loop/rate limit; +- унаследованный healthcheck, проверяющий отсутствующий в updater-контейнере + daemon, отключается; updater контролируется по `Up`, restart count, логам и + возрасту сигнатур. + +Ошибки `read-only file system` устраняются точечным writable mount. Запрещено +лечить их глобальным `read_only: false`, root, `privileged` или broad +capability. + +## Сетевые ограничения + +### Cloud и host + +Используются одновременно: + +1. cloud security groups — граница между internet/VPC/managed services; +2. host firewall (UFW/nftables/iptables) — защита VM; +3. `DOCKER-USER` — защита от обхода UFW опубликованными Docker ports; +4. Docker networks — разделение сервисов внутри VM. + +Default policy для ingress — deny. Разрешение задаёт source, destination, protocol, port и назначение. Правила «вся private network на все порты» запрещены. + +Cloud SG для managed PostgreSQL разрешает TLS-подключения только от VM/SG сервисов, которым нужна соответствующая схема. PostgreSQL, Redis, OTLP receivers, admin UI и internal API не публикуются в интернет. + +### Egress + +- сервис без внешней интеграции не подключается к сети `egress`; +- внешние destination/ports фиксируются в inventory; +- DNS/NTP и package/image registry учитываются отдельно; +- временный bootstrap egress удаляется при lockdown; +- отсутствие технической возможности фильтровать по FQDN компенсируется NAT/proxy/provider firewall и мониторингом исходящих соединений. + +### Fail2ban + +Fail2ban обязателен для SSH, временно или постоянно доступного из интернета. Он дополняет allow-list trusted CIDR и key-only auth, а не заменяет их. + +Для VM без публичного ingress в steady state fail2ban можно оставить включённым, но основная защита — отсутствие внешнего маршрута и закрытые SG/firewall. + +## Минимизация host OS + +- используется поддерживаемый минимальный образ ОС; +- пакеты устанавливаются из доверенных репозиториев с проверкой подписи; +- компиляторы, отладчики, сетевые утилиты и installer dependencies не остаются без эксплуатационной необходимости; +- отключаются неиспользуемые daemon/socket units; +- автоматические security updates или утверждённое patch window обязательны; +- kernel и container runtime регулярно обновляются; +- удаление пакетов выполняется по утверждённому allow-list, а не слепым `autoremove`; +- старые images/releases удаляются только после сохранения необходимого rollback window; +- cleanup не удаляет active image, последний рабочий релиз, forensic data или backup. + +Для no-egress VM обновление выполняется в контролируемое окно через временный ограниченный egress либо проверенные offline packages/images. После обновления повторяется lockdown. + +## Логи, аудит и инциденты + +Аудируются: + +- входы `deploy`, `admin`, `tunnel`; +- sudo-вызовы и systemd deployment actions; +- изменение SG/firewall/SSH/sudoers; +- получение и ротация секретов без записи значений; +- открытие и закрытие break-glass доступа; +- версия/digest развернутого релиза. + +Секреты, токены, содержимое credentials и полные PII в логи не попадают. + +При подтверждённой компрометации контейнера: + +1. изолировать VM/контейнер сетевыми средствами; +2. не использовать скомпрометированную VM как доверенную точку восстановления; +3. ротировать доступные контейнеру секреты и service tokens; +4. проверить соседние сервисы по разрешённым network flows; +5. сохранить необходимые snapshot/log evidence; +6. пересоздать VM из доверенного образа вместо ручной «очистки», если затронут host; +7. задокументировать причину выхода за границу изоляции, если он произошёл. + +## Definition of Done для новой VM или сервиса + +- определён класс VM: egress или private/no-egress; +- составлена матрица ingress/egress; +- созданы отдельные OS users и IAM principal; +- root/password SSH отключены после проверки key access; +- `deploy` не состоит в `docker` и имеет только конкретные systemd-команды; +- production-файлы root-owned и недоступны `deploy` на запись; +- каждый контейнер проверен по hardening baseline; +- для каждого image digest проверены entrypoint, UID/GID и полный inventory + writable paths; +- секреты разделены по сервисам/VM и отсутствуют в обычном `.env`; +- bind-backed secrets и staged TLS проверены по фактическим owner/mode и + содержимому, а не только по декларации Compose; +- runtime/migration/config-admin DB roles разделены, временные cross-schema + grants выданы и отозваны владельцем; +- healthcheck проверяет процесс, реально присутствующий в контейнере, а + updater freshness контролируется отдельным сигналом; +- внутренние ports недоступны извне; +- backup/restore и rollback проверены в объёме релиза; +- для private/no-egress VM завершён и зафиксирован lockdown; +- проверена недоступность внешних портов и неразрешённого egress; +- отклонения имеют владельца, компенсирующую меру и срок пересмотра. diff --git a/backlog.md b/backlog.md index a6d6adb..b07d0ef 100644 --- a/backlog.md +++ b/backlog.md @@ -15,98 +15,68 @@ ## На главном экране две кнопки: чат и звонок оператору. На кнопке с чатом уведомление при наличии непрочитанных сообщений. # Закрыто 28.07-03.08 -## Подключить OTLP-провайдер -## Отправлять на UI информацию разные ошибки при попытках авторизации в зависимости от события: код неверен, истёк или уже использован; превышен лимит попыток авторизации, попробуйте через 24 часа (в случаях превышения otp.phone.max_send_attempts_per_24h); превышен лимит неуспешных авторизаций, начните процедуру заново (в случае превышения otp.phone.max_verify_attempts). -## При отрицательном результате проверки сообщения через message-safety, если сообщение отправлялось с главного экрана, то пользователь не переводится в чат, ему под окном главного экрана выпадает сообщение об ошибке. Не на всех устройствах это видно. Воспринимается как UX-дефект. Как надо: вне зависимости от решения message-safety, если пользователь отправил сообщение, то он переводится на экран с чатом. Далее, сейчас отрицательный результат message-safety выводится пользователю как техническая ошибка (красным цветом под полем ввода сообщения) и опять же воспринимается не как бизнес-логика, а как техническая ошибка. Это поведение нужно поменять. Если сообщение пользователя не прошло проверку, нужно ему в окне чата прислать ответ: Для сообщений: К сожалению, ваше сообщение не соответствует правилам данного чата и не может быть отправлено. Попробуйте переформулировать. Для документов: К сожалению, ваш документ не прошел проверку и не может быть доставлен. +## #MONITORING Подключить OTLP-провайдер (Signoz) +## #UI Отправлять на UI информацию разные ошибки при попытках авторизации в зависимости от события: код неверен, истёк или уже использован; превышен лимит попыток авторизации, попробуйте через 24 часа (в случаях превышения otp.phone.max_send_attempts_per_24h); превышен лимит неуспешных авторизаций, начните процедуру заново (в случае превышения otp.phone.max_verify_attempts). +## #UI При отрицательном результате проверки сообщения через message-safety, если сообщение отправлялось с главного экрана, то пользователь не переводится в чат, ему под окном главного экрана выпадает сообщение об ошибке. Не на всех устройствах это видно. Воспринимается как UX-дефект. Как надо: вне зависимости от решения message-safety, если пользователь отправил сообщение, то он переводится на экран с чатом. Далее, сейчас отрицательный результат message-safety выводится пользователю как техническая ошибка (красным цветом под полем ввода сообщения) и опять же воспринимается не как бизнес-логика, а как техническая ошибка. Это поведение нужно поменять. Если сообщение пользователя не прошло проверку, нужно ему в окне чата прислать ответ: Для сообщений: К сожалению, ваше сообщение не соответствует правилам данного чата и не может быть отправлено. Попробуйте переформулировать. Для документов: К сожалению, ваш документ не прошел проверку и не может быть доставлен. ## UX-дефект: frontend показывает «Не удалось завершить вход» при ошибке отправки отложенного сообщения, хотя вход завершён. Это следует исправить: завершать экран авторизации после bootstrap, а ошибку Bitrix показывать уже в чате (если сообщение отклонено сервисом message-safety, учесть реализацию предыдущего пункта) -## Ограничить кол-во символов в сообщении на фронте. Показывать в моменте счетчик: n/max, где n сколько символов уже напечатано, max сколько может быть отправлено. Максимальное кол-во символов - положить в app_settings. -## Убрать с экрана ввода номера телефона тексты согласий внизу экрана: Нажимая «Получить код», вы соглашаетесь с условиями использования и политикой конфиденциальности. Согласия пользователь дает ранее на отдельном экране. -## Перенести секреты из .env в KM Selectel. -## Провести аудит безопасности вм -## Унифицированы гостевые экраны Центра уведомлений, Профиля и Чата: единый стиль сообщения о необходимости входа и кнопка «Авторизоваться». +## #UI Ограничить кол-во символов в сообщении на фронте. Показывать в моменте счетчик: n/max, где n сколько символов уже напечатано, max сколько может быть отправлено. Максимальное кол-во символов - положить в app_settings. +## #UI Убрать с экрана ввода номера телефона тексты согласий внизу экрана: Нажимая «Получить код», вы соглашаетесь с условиями использования и политикой конфиденциальности. Согласия пользователь дает ранее на отдельном экране. +## #BACK_SECURE Перенести секреты из .env в KM Selectel. +## #BACK_SECURE Провести аудит безопасности вм +## #UI Унифицированы гостевые экраны Центра уведомлений, Профиля и Чата: единый стиль сообщения о необходимости входа и кнопка «Авторизоваться». +## #BACK_BUSINESS Архитектурное решение принято: `message-safety` и `bitrix-sync` выносятся на самостоятельную ВМ2 с одним root Compose/nginx; Message Safety доступен privately, CRM webhook приходит напрямую на отдельный public host ВМ2; реализация/cutover остаются в задачах 16–17. +## #BACK_SECURE Разработан архитектурный стандарт по безопасному деплою и размещению сервисов на ВМ. + +# Закрыто 04.08-10.08 +## #BACK_DEFECT Исправлены дублирующиеся триггеры на создание контакта для сервиса синхронизации. Исправлено создание в БД лишних задач на обновление контакта (каждый бустрап пользователя вызывал задачу на обновление контакта) # В разработку: -2. После интеграции с смс провайдером, реализовать debounce механизм при авторизации - каждая след. смс можно отправить через все большее окно. -5. Store-review вход: точечный bypass в Keycloak OTP SPI по номеру из `.env` (`STORE_REVIEW_ENABLED` / `STORE_REVIEW_PHONE` / `STORE_REVIEW_OTP`) — для этого телефона SMS не шлётся, verify принимает фиксированный OTP; остальные номера идут обычным OTP/SMS. Не путать с глобальным `KEYCLOAK_OTP_MOCK_*`. Учётные данные только в Review Notes стора (не в бинарнике/UI); пользователь с демо-контентом; в production включать только на время ревью. -6. Хранить историю устройств, с которых пользователь входил в ЛК (Ид юзера, идентификатор устройства, дата последнего входа, способ входа - веб\приложение) -9. Веб-пуши для PWA -10. На кнопке Чат отображать значок наличия непрочитанных уведомлений. Требуется синхронизация между устройствами (решение, например через Dialog.client_last_opened_at) -12. Описание бизнес сущностей: Пользователь -12. Описание бизнес сущностей: Сообщение -13. Вынести за пределы ВМ1 сервисы message-safety и sync-service. -14. Сделать страницу с инструкцией по установке приложения -15. Написать пользовательское соглашение. -16. Разработка message-safety -17. Разработка sync-service -18. Разработка notification-service -20. Поднять второй контур для продакшн -21. Спрятать сеть за балансировщиком нагрузки -22. Автопродление TLS падает при перезагрузке nginx; сертификат действует до 14.10.2026. (Исправить reload внутри контейнера и проверить systemctl start an-chat-ssl-renew.service до успешного завершения.) -23. WireGuard-only SSH. -26. Запрет входа под root: В /etc/ssh/sshd_config установите PermitRootLogin no. Заходите под обычным пользователем (например, deploy) и используйте sudo для админских задач. -27. Удалите все ненужные пакеты, компиляторы (gcc, make) и сервисы. Чем меньше программ на сервере, тем меньше потенциальных уязвимостей. -28. Монтирование с флагами безопасности: Разделы диска (особенно /tmp и /var/tmp) следует монтировать с флагами noexec (запрет запуска исполняемых файлов) и nosuid (игнорирование битов setuid). -29. Systemd-ограничения: используйте директивы в юните - NoNewPrivileges=yes # Запрещает повышение привилегий через setuid - ProtectSystem=strict # Делает всю ОС доступной только для чтения - PrivateTmp=yes # Дает процессу свой изолированный /tmp - ProtectHome=yes # Скрывает домашние директории пользователей -24. Добавить логи (Для Python-сервисов добавить OTLP Log Exporter: api-backend; sms-service; sms-worker. Подключить LoggerProvider, BatchLogRecordProcessor и bounded queue. Передавать resource attributes: service.name; service.version; deployment.environment; service.namespace=han-chat.) Экспортировать структурированные поля request_id, trace_id, span_id, severity и event name. Оставить stdout как аварийный локальный журнал. Добавить canary-тесты, запрещающие экспорт токенов, cookie, телефонов, email, текстов сообщений, SQL и object keys.). -25. Nginx metrics/tracing в signoz - - -На будущее (после доработки отдельных функциональностей): -1. Определение итогового перечня мнемоник, перевод фронтенда на мнемоники, seed заливка мнемоник в БД (?) -2. Моделирование профиля клиента. -4. Реализовать в полноценном `bitrix-sync` обработчик `document.client_uploaded`: claim/retry/DLQ, идемпотентность по `client_document_id`, группировка по `submission_id`; до этого stub задачи не claim-ит. - -На анализ: -debounce на отправку СМС (сейчас есть Фиксированный cooldownmin_seconds_between_attempts) +1 #BACK_SECURE После интеграции с смс провайдером, реализовать debounce механизм при авторизации - каждая след. смс можно отправить через все большее окно. (сейчас есть Фиксированный cooldownmin_seconds_between_attempts) +2. #MONITORING Настроить мониторинг в Signoz +3. #BACK_BUSINESS Хранить историю устройств, с которых пользователь входил в ЛК (Ид юзера, идентификатор устройства, дата последнего входа, способ входа - веб\приложение) +4. #BACK_BUSINESS Веб-пуши для PWA +5. #UI На кнопке Чат отображать значок наличия непрочитанных уведомлений. Требуется синхронизация между устройствами (решение, например через Dialog.client_last_opened_at) +6. #BACK_BUSINESS Описание бизнес сущностей: Пользователь +7. #BACK_BUSINESS Описание бизнес сущностей: Сообщение +8. #UI Сделать страницу с инструкцией по установке приложения +9. #LEGAL Написать пользовательское соглашение. +10. #BACK_BUSINESS Разработка Message Safety v2 по [`module-05`](modules/module-05-message-safety.md), §18 DoR/DoD и cutover gates [`module-10`](modules/module-10-deployment-runbook.md): + - API/OpenAPI v2, versioned `message_safety.config_versions`, configuration activation/validation и schema migrations; + - PostgreSQL queue/lease/fencing/deadline + Redis hot cache/rate/wakeup; + - Unicode normalization и versioned text rule bundle/corpus; + - local-only URL parser/IDNA/DNS/IP policy и cache split; + - immutable S3 version flow, file detectors и technical matrix; + - ClamAV/freshclam, signature rollback и EICAR tests; + - api-backend integration: `202` polling, M8, `safety.chat.blocked`, conditional promote; + - VM2 internal nginx/TLS/egress/collector/dashboards + root-owned emergency MOCK helper/alert; + - contract/security/failure/load acceptance и S3 negative gate; + - controlled v1→v2 cutover, rollback rehearsal и удаление stub references. +11. #BACK_BUSINESS Разработка sync-service +12. #INFRASTRUCTURE Перераскатить сервисы от деплоя +13. #INFRASTRUCTURE Поднять второй контур для продакшн +14. #INFRASTRUCTURE Спрятать сеть за балансировщиком нагрузки +15. #BACK_DEFECT Автопродление TLS падает при перезагрузке nginx; сертификат действует до 14.10.2026. (Исправить reload внутри контейнера и проверить systemctl start an-chat-ssl-renew.service до успешного завершения.) +16. #INFRASTRUCTURE WireGuard-only SSH. +17. #LEGAL Обновить документы по ПД - модель угроз и меры защиты. +18. #LEGAL Уведомление в РКН по БД обработки ПД. +19. #MONITORING Добавить логи (Для Python-сервисов добавить OTLP Log Exporter: api-backend; sms-service; sms-worker. Подключить LoggerProvider, BatchLogRecordProcessor и bounded queue. Передавать resource attributes: service.name; service.version; deployment.environment; service.namespace=han-chat.) Экспортировать структурированные поля request_id, trace_id, span_id, severity и event name. Оставить stdout как аварийный локальный журнал. Добавить canary-тесты, запрещающие экспорт токенов, cookie, телефонов, email, текстов сообщений, SQL и object keys.). +20. #MONITORING Nginx metrics/tracing в signoz +21. #BACK_SECURE Сформулировать требования для обработки персональных данных +22. #UI Скрыть раздел диагностики в профиле пользователя (наличие этого раздела в енв передать, как часть наследования продуктовой среды?) +23. #BACK_BUSINESS Разработка notification-service +24. #BACK_BUSINESS Store-review вход: точечный bypass в Keycloak OTP SPI по номеру из `.env` (`STORE_REVIEW_ENABLED` / `STORE_REVIEW_PHONE` / `STORE_REVIEW_OTP`) — для этого телефона SMS не шлётся, verify принимает фиксированный OTP; остальные номера идут обычным OTP/SMS. Не путать с глобальным `KEYCLOAK_OTP_MOCK_*`. Учётные данные только в Review Notes стора (не в бинарнике/UI); пользователь с демо-контентом; в production включать только на время ревью. +25. #UI Реализация мнемоник: Определение итогового перечня мнемоник, перевод фронтенда на мнемоники, seed заливка мнемоник в БД (?) +26. #INFRASTRUCTURE Развернуть Гит в облаке +27. #BACK_BUSINESS Синхронизация документов из битрикс24 в Приложение. +28. #INFRASTRUCTURE Зарегистрировать Conteiner registry Selectel +29. #BACK_BUSINESS Определить пул тестовых номеров, чтобы их было легко в Б24 отслеживать. +30. #INFRASTRUCTURE перевести взаимодействие с signoz на TLS (сейчас OTEL_REMOTE_TLS_INSECURE=true) # Критично для релиза: 1. Разработка message-safety 2. Разработка sync-service 3. Пользовательское соглашение -4. Разработка notification-service -5. Подключить OTLP-провайдер -6. Починить баги -7. Второй контур для продакшн - -# Переезд на тестовый домен -**Нет — одного `.env` и новых сертификатов недостаточно.** - -Нужно пройти цепочку: - -### 1. DNS -`A`-запись нового домена → IP ВМ (до выпуска сертификата). - -### 2. `.env` — не одно поле, а все публичные URL -- `PUBLIC_HOST`, `PUBLIC_WEB_URL`, `PUBLIC_API_URL`, `PUBLIC_AUTH_URL` -- `KEYCLOAK_PUBLIC_URL` -- `NGINX_TLS_CERTIFICATE` / `NGINX_TLS_CERTIFICATE_KEY` (путь `/etc/letsencrypt/live/<новый-домен>/...`) -- `BITRIX_PUBLIC_BASE_URL` -- `IDGTL_SMS_CALLBACK_PUBLIC_URL` (если SMS уже подключён) - -### 3. Сертификат -Certbot на новый `-d` / `--cert-name`, затем nginx с TLS. - -### 4. Пересборка / перезапуск сервисов -- **frontend-static** — URL зашиты на build (`EXPO_PUBLIC_*` из `PUBLIC_WEB_URL` / `PUBLIC_AUTH_URL`) -- **keycloak** — `KC_HOSTNAME` из `KEYCLOAK_PUBLIC_URL` -- **nginx**, **api-backend** и связанные сервисы — подхватить новый env - -### 5. Настройки в БД (seed / app-settings) -В `app-settings.production-like.yaml`: -- `security.cors.allowed_origins` → `https://новый-домен` -- `notification.instruction.allowed_hosts` → новый хост - -После правки — снова `deployment/scripts/seed.sh` (или ручное обновление в БД). - -### 6. Внешние системы -- **S3 CORS** (Selectel) — `Allowed origin: https://новый-домен` -- **Bitrix24** — URL установки/обработчика (`/bitrix/install`, `/bitrix/handler`) -- **Keycloak client** — redirect URIs / web origins (в realm сейчас зашиты конкретные домены вроде `chat.han0107.ru`) -- **i-Digital** — callback URL, если провайдер его фиксирует - -Итого: `.env` + сертификат — ядро, но без DNS, CORS (API + S3), rebuild frontend, Keycloak hostname/redirects, Bitrix URL и seed CORS логин/загрузки/интеграции сломаются. \ No newline at end of file +~~4. Подключить OTLP-провайдер~~ +~~5. Починить UI баги~~ +6. Второй контур для продакшн diff --git a/codebase/README.md b/codebase/README.md index 9d1b6e2..586bff2 100644 --- a/codebase/README.md +++ b/codebase/README.md @@ -2,6 +2,12 @@ Production-like MVP implementation described by `../architectory` and `../modules`. -The deployment entry point is `backend/docker-compose.yml`. Copy -`backend/.env.example` to `backend/.env`, provide external managed PostgreSQL, -Selectel S3 and Bitrix24 credentials, then follow `backend/deployment/RUNBOOK.md`. +The current executable entry point is `backend/docker-compose.yml`; it is the +legacy VM1/stub contour, not evidence that the VM2 cutover is complete. + +Target production has two independent root Compose projects/systemd units: +VM1 HAN Chat (`backend/`) and private VM2 Processing (`message-safety`, +`bitrix-sync`, ClamAV, Redis Safety, internal nginx and a local OTEL Collector). +Until the VM2 project is implemented, follow the existing backend guide only +for development/acceptance and the target runbook in +`../modules/module-10-deployment-runbook.md` for migration boundaries. diff --git a/codebase/Signoz/docs/BACKEND_OTLP.md b/codebase/Signoz/docs/BACKEND_OTLP.md index 21f9c82..c1fd93b 100644 --- a/codebase/Signoz/docs/BACKEND_OTLP.md +++ b/codebase/Signoz/docs/BACKEND_OTLP.md @@ -2,19 +2,24 @@ ## Схема -Приложения в Docker-сети отправляют OTLP локальному `otel-collector`: +Приложения на ВМ1 и ВМ2 отправляют OTLP только своему локальному `otel-collector`: ```text -HAN containers -> otel-collector:4317 -> 192.168.0.5:4317 -> SigNoz +VM1 containers -> VM1 otel-collector:4317 -> 192.168.0.5:4317 -> SigNoz +VM2 containers -> VM2 otel-collector:4317 -> 192.168.0.5:4317 -> SigNoz ``` Локальный Collector выполняет редактирование чувствительных атрибутов, добавляет `service.namespace=han-chat`, окружение и версию, сохраняет очередь на диск и пересылает данные в SigNoz. +Collectors имеют отдельные bounded persistent queue volumes. ВМ2 не использует +Docker hostname collector ВМ1. Недоступность SigNoz/Collector fail-open для +business/Safety readiness; переполнение очереди создаёт alert и controlled drop. + ## Настройка backend -В `codebase/backend/.env`: +В non-secret env manifest каждой VM: cd /opt/han-chat/backend ```dotenv diff --git a/codebase/Signoz/docs/NETWORK.md b/codebase/Signoz/docs/NETWORK.md index eec85e5..338cf34 100644 --- a/codebase/Signoz/docs/NETWORK.md +++ b/codebase/Signoz/docs/NETWORK.md @@ -70,8 +70,8 @@ ssh -i ~/.ssh/hansel-private root@192.168.0.5 Минимальные входящие правила для VM SigNoz: - TCP 22 от административного узла/подсети приватной сети; -- TCP 4317 от приватного IP backend; -- TCP 4318 от приватного IP backend только если планируется OTLP/HTTP; +- TCP 4317 от security groups/private IP ВМ1 и ВМ2; +- TCP 4318 от ВМ1/ВМ2 только если планируется OTLP/HTTP; - никаких входящих правил для 8080, 5432, 8123, 9000, 9181. Для текущего backend используется OTLP/gRPC, поэтому после проверки 4318 можно @@ -100,7 +100,7 @@ ssh -i C:\Users\MI\.ssh\hansel ` 1. Новая SSH-сессия к `192.168.0.5` через jump host открывается. 2. Туннель показывает UI SigNoz. 3. `scripts/30-verify-signoz.sh` проходит без ошибок. -4. С backend доступны `192.168.0.5:4317` и при необходимости `:4318`. +4. С ВМ1 и ВМ2 доступны `192.168.0.5:4317` и при необходимости `:4318`. 5. В SigNoz появился свежий trace сервиса HAN Chat. 6. Все контейнеры имеют статус `running`, healthcheck — `healthy`. 7. Создан snapshot диска ВМ. diff --git a/codebase/backend/api-backend/README.md b/codebase/backend/api-backend/README.md index f6a3d67..b481476 100644 --- a/codebase/backend/api-backend/README.md +++ b/codebase/backend/api-backend/README.md @@ -39,6 +39,7 @@ han-notification-draft-cleanup-worker - `KEYCLOAK_PUBLIC_URL`, `KEYCLOAK_INTERNAL_URL`, `KEYCLOAK_REALM`, `KEYCLOAK_AUDIENCE`; - `MESSAGE_SAFETY_URL`, `MESSAGE_SAFETY_SERVICE_TOKEN`, + `MESSAGE_SAFETY_CA_FILE`, `MESSAGE_SAFETY_API_PREFIX=/internal/safety/v2`, `MESSAGE_SAFETY_POST_TIMEOUT_SEC`, `MESSAGE_SAFETY_TASK_POLL_INTERVAL_SEC`, `MESSAGE_SAFETY_TASK_POLL_MAX_SEC`, `MESSAGE_SAFETY_CIRCUIT_FAILURE_THRESHOLD`, `MESSAGE_SAFETY_CIRCUIT_OPEN_SEC`; @@ -57,7 +58,9 @@ han-notification-draft-cleanup-worker Токены генерируются `openssl rand -hex 32`. S3 read-only credentials Message Safety не передаются этому контейнеру. В production подключение PostgreSQL должно использовать -TLS, а internal endpoints — быть доступны только из backend-сети. +TLS. Target `MESSAGE_SAFETY_URL=https://processing.internal:8443`; certificate +проверяется по internal CA, plaintext HTTP запрещён. Текущий Docker hostname +`message-safety` относится только к legacy stub до cutover. Smoke-сценарий `producer_test`: отправить `POST /internal/notifications/v1/notifications` с `Authorization: Bearer @@ -75,5 +78,7 @@ mypy app pytest ``` -`/health/live` проверяет процесс. `/health/ready` проверяет критические зависимости и -возвращает `503`, если сервис не может безопасно обслуживать protected API. +`/health/live` проверяет процесс. `/health/ready` проверяет критические +зависимости read API. Remote Message Safety не выключает чтение/общую readiness: +send endpoint отдельно проверяет требуемую capability и fail-closed возвращает +`503`, если ВМ2 недоступна. diff --git a/codebase/backend/api-backend/alembic/versions/0011_module07_contract.py b/codebase/backend/api-backend/alembic/versions/0011_module07_contract.py new file mode 100644 index 0000000..8fd8097 --- /dev/null +++ b/codebase/backend/api-backend/alembic/versions/0011_module07_contract.py @@ -0,0 +1,188 @@ +"""Expand module-07 queue and stage canonical Bitrix mapping. + +Revision ID: 0011_module07_contract +Revises: 0010_contact_map_dedup +Create Date: 2026-08-06 +""" + +from collections.abc import Sequence + +from alembic import op + +revision: str = "0011_module07_contract" +down_revision: str | None = "0010_contact_map_dedup" +branch_labels: str | Sequence[str] | None = None +depends_on: str | Sequence[str] | None = None + + +def upgrade() -> None: + # Expand first. Existing rows remain readable throughout the migration. + op.execute( + """ + ALTER TABLE han_app.sync_queue + ADD COLUMN IF NOT EXISTS locked_by varchar(128), + ADD COLUMN IF NOT EXISTS locked_until timestamptz, + ADD COLUMN IF NOT EXISTS lease_token uuid, + ADD COLUMN IF NOT EXISTS last_error_code varchar(64), + ADD COLUMN IF NOT EXISTS last_error_at timestamptz, + ADD COLUMN IF NOT EXISTS completed_at timestamptz, + ADD COLUMN IF NOT EXISTS cancel_reason varchar(255); + + UPDATE han_app.sync_queue + SET status = CASE status + WHEN 'processing' THEN 'pending' + WHEN 'failed' THEN 'retry_wait' + ELSE status + END + WHERE status IN ('processing', 'failed'); + + ALTER TABLE han_app.sync_queue + DROP CONSTRAINT IF EXISTS sync_queue_status_check; + ALTER TABLE han_app.sync_queue + ADD CONSTRAINT sync_queue_status_check CHECK ( + status IN ('pending','leased','processed','retry_wait','dead_letter','cancelled') + ) NOT VALID; + ALTER TABLE han_app.sync_queue + VALIDATE CONSTRAINT sync_queue_status_check; + + ALTER TABLE han_app.sync_queue + DROP CONSTRAINT IF EXISTS sync_queue_dedup_key_key; + DROP INDEX IF EXISTS han_app.ix_sync_queue_status_next; + CREATE INDEX IF NOT EXISTS ix_sync_queue_claim + ON han_app.sync_queue(status, next_attempt_at, created_at); + CREATE INDEX IF NOT EXISTS ix_sync_queue_expired_lease + ON han_app.sync_queue(locked_until) WHERE status = 'leased'; + CREATE INDEX IF NOT EXISTS ix_sync_queue_entity_history + ON han_app.sync_queue(entity_type, entity_id, created_at DESC); + CREATE UNIQUE INDEX IF NOT EXISTS uq_sync_queue_active_dedup + ON han_app.sync_queue(dedup_key) + WHERE status IN ('pending','leased','retry_wait'); + """ + ) + + # The bitrix-sync migration owns the canonical schema. If that migration + # already ran, copy and verify legacy rows here; otherwise its follow-up + # migration performs the same copy. The legacy table remains until the + # readers have switched and the contract migration is explicitly approved. + op.execute( + """ + DO $$ + BEGIN + IF to_regclass('bitrix_sync.entity_external_mapping') IS NOT NULL THEN + INSERT INTO bitrix_sync.entity_external_mapping ( + id, entity_type, entity_id, external_system, external_entity_type, + external_id, status, opened_at, created_at, updated_at + ) + SELECT id, entity_type, entity_id, 'bitrix24', 'contact', + external_id, 'active', created_at, created_at, created_at + FROM han_app.entity_external_mapping + ON CONFLICT DO NOTHING; + + IF EXISTS ( + SELECT 1 + FROM han_app.entity_external_mapping legacy + LEFT JOIN bitrix_sync.entity_external_mapping canonical + ON canonical.id = legacy.id + AND canonical.entity_type = legacy.entity_type + AND canonical.entity_id = legacy.entity_id + AND canonical.external_id = legacy.external_id + WHERE canonical.id IS NULL + ) THEN + RAISE EXCEPTION 'canonical mapping verification failed'; + END IF; + END IF; + END $$; + """ + ) + + op.execute( + """ + CREATE OR REPLACE FUNCTION han_app.enqueue_contact_sync() + RETURNS trigger + LANGUAGE plpgsql + SECURITY INVOKER + SET search_path = han_app, pg_temp + AS $$ + DECLARE + v_user_id uuid; + v_task_type varchar(64); + v_reason varchar(64); + v_dedup varchar(255); + v_source_updated_at timestamptz; + BEGIN + IF current_setting('han.sync_suppress', true) = 'true' THEN + RETURN NEW; + END IF; + + IF TG_TABLE_NAME = 'user_identities' THEN + v_user_id := NEW.id; + v_source_updated_at := NEW.updated_at; + IF TG_OP = 'INSERT' THEN + IF NEW.record_status <> 'A' THEN RETURN NEW; END IF; + v_task_type := 'contact.map_or_create'; + v_reason := 'identity_created'; + ELSIF OLD.record_status = 'A' AND NEW.record_status <> 'A' THEN + v_task_type := 'contact.deactivate'; + v_reason := 'identity_deactivated'; + ELSIF OLD.record_status <> 'A' AND NEW.record_status = 'A' THEN + v_task_type := 'contact.map_or_create'; + v_reason := 'identity_reactivated'; + ELSIF NEW.record_status = 'A' + AND NEW.phone_number IS DISTINCT FROM OLD.phone_number THEN + v_task_type := 'contact.update'; + v_reason := 'identity_phone_changed'; + ELSE + RETURN NEW; + END IF; + ELSE + v_user_id := NEW.user_id; + v_source_updated_at := NEW.updated_at; + IF TG_OP = 'INSERT' THEN + IF NEW.record_status <> 'A' THEN RETURN NEW; END IF; + v_task_type := 'contact.map_or_create'; + v_reason := 'profile_created'; + ELSIF OLD.record_status = 'A' AND NEW.record_status <> 'A' THEN + v_task_type := 'contact.deactivate'; + v_reason := 'profile_deactivated'; + ELSIF OLD.record_status <> 'A' AND NEW.record_status = 'A' THEN + v_task_type := 'contact.map_or_create'; + v_reason := 'profile_reactivated'; + ELSE + RETURN NEW; + END IF; + END IF; + + v_dedup := v_task_type || ':' || v_user_id::text; + INSERT INTO han_app.sync_queue ( + id, task_type, entity_type, entity_id, dedup_key, payload_json, + status, attempt_count, next_attempt_at, created_at, updated_at + ) VALUES ( + gen_random_uuid(), v_task_type, 'contact', v_user_id, v_dedup, + jsonb_build_object( + 'schema_version', 1, + 'user_id', v_user_id, + 'reason', v_reason, + 'source_updated_at', v_source_updated_at + ), + 'pending', 0, now(), now(), now() + ) + ON CONFLICT (dedup_key) + WHERE status IN ('pending','leased','retry_wait') + DO UPDATE SET + payload_json = EXCLUDED.payload_json, + updated_at = now(); + RETURN NEW; + END; + $$; + + DROP TRIGGER IF EXISTS trg_profile_contact_sync ON han_app.client_profiles; + CREATE TRIGGER trg_profile_contact_sync + AFTER INSERT OR UPDATE OF record_status + ON han_app.client_profiles + FOR EACH ROW EXECUTE FUNCTION han_app.enqueue_contact_sync(); + """ + ) + + +def downgrade() -> None: + raise RuntimeError("Module-07 staged contract migration is forward-only") diff --git a/codebase/backend/api-backend/alembic/versions/0012_safety_v2_checkpoint.py b/codebase/backend/api-backend/alembic/versions/0012_safety_v2_checkpoint.py new file mode 100644 index 0000000..2e7caab --- /dev/null +++ b/codebase/backend/api-backend/alembic/versions/0012_safety_v2_checkpoint.py @@ -0,0 +1,74 @@ +"""Persist Message Safety v2 evidence and recovery locations. + +Revision ID: 0012_safety_v2_checkpoint +Revises: 0011_module07_contract +Create Date: 2026-08-06 +""" + +from collections.abc import Sequence + +from alembic import op + +revision: str = "0012_safety_v2_checkpoint" +down_revision: str | None = "0011_module07_contract" +branch_labels: str | Sequence[str] | None = None +depends_on: str | Sequence[str] | None = None + + +def upgrade() -> None: + op.execute( + """ + ALTER TABLE han_app.messages + ADD COLUMN IF NOT EXISTS safety_processing_mode varchar(16), + ADD COLUMN IF NOT EXISTS safety_config_version bigint, + ADD COLUMN IF NOT EXISTS safety_rules_version varchar(128); + + ALTER TABLE han_app.message_attachments + ADD COLUMN IF NOT EXISTS quarantine_version_id varchar(1024), + ADD COLUMN IF NOT EXISTS quarantine_etag varchar(1024); + ALTER TABLE han_app.message_attachments + DROP CONSTRAINT IF EXISTS message_attachments_scan_status_check; + ALTER TABLE han_app.message_attachments + ADD CONSTRAINT message_attachments_scan_status_check + CHECK (scan_status IN ('pending','clean','bypassed','infected','failed')) NOT VALID; + ALTER TABLE han_app.message_attachments + VALIDATE CONSTRAINT message_attachments_scan_status_check; + + ALTER TABLE han_app.safety_tasks + ADD COLUMN IF NOT EXISTS poll_location varchar(1024), + ADD COLUMN IF NOT EXISTS processing_mode varchar(16), + ADD COLUMN IF NOT EXISTS config_version bigint, + ADD COLUMN IF NOT EXISTS rules_version varchar(128), + ADD COLUMN IF NOT EXISTS expires_at timestamptz; + UPDATE han_app.safety_tasks + SET poll_location = '/internal/safety/v2/messages/tasks/' || task_id, + expires_at = deadline_at + WHERE poll_location IS NULL OR expires_at IS NULL; + ALTER TABLE han_app.safety_tasks + ALTER COLUMN poll_location SET NOT NULL, + ALTER COLUMN expires_at SET NOT NULL; + """ + ) + + # Notification uploads use the same safety contract. + op.execute( + """ + ALTER TABLE han_app.client_upload_drafts + ADD COLUMN IF NOT EXISTS quarantine_version_id varchar(1024), + ADD COLUMN IF NOT EXISTS quarantine_etag varchar(1024), + ADD COLUMN IF NOT EXISTS safety_processing_mode varchar(16), + ADD COLUMN IF NOT EXISTS safety_config_version bigint, + ADD COLUMN IF NOT EXISTS safety_rules_version varchar(128); + ALTER TABLE han_app.client_upload_drafts + DROP CONSTRAINT IF EXISTS client_upload_drafts_scan_status_check; + ALTER TABLE han_app.client_upload_drafts + ADD CONSTRAINT client_upload_drafts_scan_status_check + CHECK (scan_status IN ('pending','clean','bypassed','infected','failed')) NOT VALID; + ALTER TABLE han_app.client_upload_drafts + VALIDATE CONSTRAINT client_upload_drafts_scan_status_check; + """ + ) + + +def downgrade() -> None: + raise RuntimeError("Safety v2 checkpoint migration is forward-only") diff --git a/codebase/backend/api-backend/app/db.py b/codebase/backend/api-backend/app/db.py index a9bb932..3d5c723 100644 --- a/codebase/backend/api-backend/app/db.py +++ b/codebase/backend/api-backend/app/db.py @@ -34,6 +34,10 @@ class Base(DeclarativeBase): type_annotation_map = {dict[str, Any]: JSON} +class BitrixBase(DeclarativeBase): + """Models owned by bitrix-sync, excluded from han_app create_all.""" + + class Common: id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) record_status: Mapped[str] = mapped_column(String(1), default="A", server_default="A") @@ -142,6 +146,9 @@ class Message(Common, Base): content_kind: Mapped[str] = mapped_column(String(16)) text: Mapped[str] = mapped_column(Text, default="") safety_status: Mapped[str] = mapped_column(String(16)) + safety_processing_mode: Mapped[str | None] = mapped_column(String(16)) + safety_config_version: Mapped[int | None] = mapped_column(BigInteger) + safety_rules_version: Mapped[str | None] = mapped_column(String(128)) delivery_status: Mapped[str] = mapped_column(String(16)) external_message_id: Mapped[str | None] = mapped_column(String(255)) client_idempotency_key: Mapped[str | None] = mapped_column(String(128)) @@ -152,7 +159,7 @@ class MessageAttachment(Common, Base): __tablename__ = "message_attachments" __table_args__ = ( CheckConstraint("direction IN ('client_upload','company_inbound')"), - CheckConstraint("scan_status IN ('pending','clean','infected','failed')"), + CheckConstraint("scan_status IN ('pending','clean','bypassed','infected','failed')"), CheckConstraint("size_bytes > 0"), {"schema": SCHEMA}, ) @@ -171,6 +178,8 @@ class MessageAttachment(Common, Base): storage_bucket: Mapped[str] = mapped_column(String(255)) object_key: Mapped[str] = mapped_column(String(1024)) quarantine_object_key: Mapped[str | None] = mapped_column(String(1024)) + quarantine_version_id: Mapped[str | None] = mapped_column(String(1024)) + quarantine_etag: Mapped[str | None] = mapped_column(String(1024)) upload_expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) @@ -193,10 +202,15 @@ class SafetyTask(Base): __table_args__ = ({"schema": SCHEMA},) id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) task_id: Mapped[str] = mapped_column(String(255), unique=True) + poll_location: Mapped[str] = mapped_column(String(1024)) message_id: Mapped[uuid.UUID] = mapped_column(ForeignKey(f"{SCHEMA}.messages.id"), unique=True) attachment_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True)) quarantine_object_key: Mapped[str | None] = mapped_column(String(1024)) status: Mapped[str] = mapped_column(String(16)) + processing_mode: Mapped[str | None] = mapped_column(String(16)) + config_version: Mapped[int | None] = mapped_column(BigInteger) + rules_version: Mapped[str | None] = mapped_column(String(128)) + expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) deadline_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) next_poll_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) attempt_count: Mapped[int] = mapped_column(Integer, default=0) @@ -321,18 +335,32 @@ class PopularQuestion(Common, Base): class SyncQueue(Base): __tablename__ = "sync_queue" - __table_args__ = ({"schema": SCHEMA},) + __table_args__ = ( + CheckConstraint( + "status IN ('pending','leased','processed','retry_wait','dead_letter','cancelled')" + ), + Index("ix_sync_queue_claim", "status", "next_attempt_at", "created_at"), + Index("ix_sync_queue_entity_history", "entity_type", "entity_id", "created_at"), + {"schema": SCHEMA}, + ) id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) task_type: Mapped[str] = mapped_column(String(64)) entity_type: Mapped[str] = mapped_column(String(64)) entity_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True)) - dedup_key: Mapped[str] = mapped_column(String(255), unique=True) + dedup_key: Mapped[str] = mapped_column(String(255)) payload_json: Mapped[dict[str, Any]] = mapped_column(JSON) status: Mapped[str] = mapped_column(String(16), default="pending") attempt_count: Mapped[int] = mapped_column(Integer, default=0) next_attempt_at: Mapped[datetime] = mapped_column( DateTime(timezone=True), server_default=func.now() ) + locked_by: Mapped[str | None] = mapped_column(String(128)) + locked_until: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + lease_token: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True)) + last_error_code: Mapped[str | None] = mapped_column(String(64)) + last_error_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + cancel_reason: Mapped[str | None] = mapped_column(String(255)) created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now()) updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now()) @@ -347,6 +375,53 @@ class EntityExternalMapping(Base): created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now()) +class BitrixEntityExternalMapping(BitrixBase): + __tablename__ = "entity_external_mapping" + __table_args__ = ({"schema": "bitrix_sync"},) + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + entity_type: Mapped[str] = mapped_column(String(64)) + entity_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True)) + external_system: Mapped[str] = mapped_column(String(32), default="bitrix24") + external_entity_type: Mapped[str] = mapped_column(String(32), default="contact") + external_id: Mapped[str] = mapped_column(String(128)) + status: Mapped[str] = mapped_column(String(16), default="active") + opened_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now()) + closed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + close_reason: Mapped[str | None] = mapped_column(String(64)) + workflow_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True)) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now()) + updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now()) + + +Index( + "uq_sync_queue_active_dedup", + SyncQueue.dedup_key, + unique=True, + postgresql_where=SyncQueue.status.in_(["pending", "leased", "retry_wait"]), +) +Index( + "ix_sync_queue_expired_lease", + SyncQueue.locked_until, + postgresql_where=SyncQueue.status == "leased", +) +Index( + "uq_external_mapping_active_entity", + BitrixEntityExternalMapping.external_system, + BitrixEntityExternalMapping.entity_type, + BitrixEntityExternalMapping.entity_id, + unique=True, + postgresql_where=BitrixEntityExternalMapping.status == "active", +) +Index( + "uq_external_mapping_active_external", + BitrixEntityExternalMapping.external_system, + BitrixEntityExternalMapping.external_entity_type, + BitrixEntityExternalMapping.external_id, + unique=True, + postgresql_where=BitrixEntityExternalMapping.status == "active", +) + + class Database: def __init__(self, url: str) -> None: self.engine: AsyncEngine = create_postgres_engine(url, pool_pre_ping=True) diff --git a/codebase/backend/api-backend/app/integrations.py b/codebase/backend/api-backend/app/integrations.py index dbd41a2..8e5b11d 100644 --- a/codebase/backend/api-backend/app/integrations.py +++ b/codebase/backend/api-backend/app/integrations.py @@ -6,6 +6,7 @@ import socket import time import uuid from dataclasses import dataclass +from datetime import datetime from typing import Any from urllib.parse import urlparse @@ -25,9 +26,19 @@ return {current, ttl} class DependencyFailure(Exception): - def __init__(self, code: str = "dependency_unavailable", timeout: bool = False) -> None: + def __init__( + self, + code: str = "dependency_unavailable", + timeout: bool = False, + *, + terminal: bool = False, + retryable: bool = True, + ) -> None: + super().__init__(code) self.code = code self.timeout = timeout + self.terminal = terminal + self.retryable = retryable @dataclass(slots=True) @@ -106,20 +117,37 @@ class SafetyClient: async def check(self, payload: dict[str, Any], request_id: str) -> dict[str, Any]: return await self._call( "POST", - "/internal/safety/v1/messages/check", + f"{self.settings.message_safety_api_prefix}/messages/check", request_id, json=payload, timeout=self.settings.message_safety_post_timeout_sec, ) - async def poll(self, task_id: str, request_id: str) -> dict[str, Any]: + async def poll(self, location: str, request_id: str) -> dict[str, Any]: + path = self._poll_path(location) return await self._call( "GET", - f"/internal/safety/v1/messages/tasks/{task_id}", + path, request_id, timeout=2, ) + def _poll_path(self, location: str) -> str: + expected_prefix = f"{self.settings.message_safety_api_prefix}/messages/tasks/" + parsed = urlparse(location) + if parsed.scheme or parsed.netloc or parsed.query or parsed.fragment: + raise DependencyFailure("invalid_safety_location", terminal=True, retryable=False) + if not parsed.path.startswith(expected_prefix): + raise DependencyFailure("invalid_safety_location", terminal=True, retryable=False) + task_id = parsed.path.removeprefix(expected_prefix) + try: + uuid.UUID(task_id) + except ValueError as exc: + raise DependencyFailure( + "invalid_safety_location", terminal=True, retryable=False + ) from exc + return parsed.path + async def _call(self, method: str, path: str, request_id: str, **kwargs: Any) -> dict[str, Any]: if not self.breaker.allow(): raise DependencyFailure() @@ -140,9 +168,31 @@ class SafetyClient: except httpx.HTTPError as exc: self.breaker.failure() raise DependencyFailure() from exc - if response.status_code == 401 or response.status_code >= 500: + if response.status_code >= 500: self.breaker.failure() - raise DependencyFailure() + code, terminal, retryable = "dependency_unavailable", False, True + try: + details = response.json().get("error", {}).get("details", {}) + code = response.json().get("error", {}).get("code", code) + terminal = details.get("terminal") is True + retryable = details.get("retryable") is not False + except (AttributeError, ValueError): + pass + raise DependencyFailure(code, terminal=terminal, retryable=retryable) + if response.status_code not in (200, 202, 403): + if response.status_code == 401: + self.breaker.failure() + code = "safety_request_rejected" + try: + code = response.json().get("error", {}).get("code", code) + except (AttributeError, ValueError): + pass + retryable = response.status_code in (404, 429) + raise DependencyFailure( + code, + terminal=not retryable, + retryable=retryable, + ) try: body = response.json() except ValueError as exc: @@ -151,10 +201,66 @@ class SafetyClient: if not isinstance(body, dict): self.breaker.failure() raise DependencyFailure() + status = response.status_code + expected_verdict = {200: "allow", 202: "pending", 403: "deny"}[status] + if ( + body.get("verdict") != expected_verdict + or body.get("processing_mode") not in ("standard", "mock") + or type(body.get("config_version")) is not int + or not body.get("rules_version") + ): + self.breaker.failure() + raise DependencyFailure("invalid_safety_response") + if status == 202: + location = response.headers.get("Location") + retry_after = response.headers.get("Retry-After") + if ( + body["processing_mode"] != "standard" + or not location + or not retry_after + or not body.get("task_id") + or not body.get("expires_at") + or type(body.get("poll_after_ms")) is not int + ): + self.breaker.failure() + raise DependencyFailure("invalid_safety_response") + try: + location_task_id = self._poll_path(location).rsplit("/", 1)[-1] + except DependencyFailure as exc: + self.breaker.failure() + raise DependencyFailure("invalid_safety_response") from exc + if body["task_id"] != location_task_id: + self.breaker.failure() + raise DependencyFailure("invalid_safety_response") + try: + if int(retry_after) <= 0 or body["poll_after_ms"] <= 0: + raise ValueError + datetime_value = body["expires_at"].replace("Z", "+00:00") + datetime.fromisoformat(datetime_value) + except (AttributeError, TypeError, ValueError) as exc: + self.breaker.failure() + raise DependencyFailure("invalid_safety_response") from exc + body["_location"] = location + body["_retry_after"] = retry_after + elif not body.get("rule_id") or ( + status == 403 and body.get("reason_code") != "message_blocked" + ): + self.breaker.failure() + raise DependencyFailure("invalid_safety_response") self.breaker.success() body["_status"] = response.status_code return body + async def ready(self) -> bool: + try: + response = await self.http.get( + f"{str(self.settings.message_safety_url).rstrip('/')}/health/ready", + timeout=2, + ) + return response.status_code == 200 + except httpx.HTTPError: + return False + class OpenLinesClient: def __init__(self, settings: Settings, http: httpx.AsyncClient) -> None: @@ -272,7 +378,14 @@ class S3Client: async def head(self, bucket: str, key: str) -> dict[str, Any]: return await asyncio.to_thread(self.client.head_object, Bucket=bucket, Key=key) - async def promote(self, source_key: str, destination_key: str) -> None: + async def promote( + self, + source_key: str, + destination_key: str, + *, + version_id: str, + etag: str, + ) -> None: await asyncio.to_thread( self.client.copy_object, Bucket=self.settings.selectel_s3_bucket_attachments, @@ -280,13 +393,13 @@ class S3Client: CopySource={ "Bucket": self.settings.selectel_s3_bucket_quarantine, "Key": source_key, + "VersionId": version_id, }, + CopySourceIfMatch=etag, ) - await asyncio.to_thread( - self.client.delete_object, - Bucket=self.settings.selectel_s3_bucket_quarantine, - Key=source_key, - ) + # Keep the immutable source version until quarantine lifecycle expiry. + # A crash after copy but before the DB checkpoint can then safely retry + # the same conditional copy without losing its source. async def delete_quarantine(self, key: str) -> None: await asyncio.to_thread( diff --git a/codebase/backend/api-backend/app/main.py b/codebase/backend/api-backend/app/main.py index aa6ae2d..73999ae 100644 --- a/codebase/backend/api-backend/app/main.py +++ b/codebase/backend/api-backend/app/main.py @@ -138,12 +138,15 @@ async def lifespan(app: FastAPI): app.state.settings = settings app.state.db = Database(settings.database_url) app.state.http = httpx.AsyncClient() + app.state.safety_http = httpx.AsyncClient( + verify=settings.message_safety_ca_file or True + ) app.state.redis = redis.from_url(settings.redis_url, decode_responses=True) app.state.redis_rt = redis.from_url(settings.redis_realtime_url, decode_responses=True) app.state.jwks = JWKSValidator(settings, app.state.http) app.state.rate_limiter = RateLimiter(app.state.redis) app.state.idempotency = RedisIdempotency(app.state.redis) - app.state.safety = SafetyClient(settings, app.state.http) + app.state.safety = SafetyClient(settings, app.state.safety_http) app.state.openlines = OpenLinesClient(settings, app.state.http) app.state.s3 = S3Client(settings) app.state.realtime = RealtimeFanout(app.state.redis_rt) @@ -168,6 +171,7 @@ async def lifespan(app: FastAPI): with suppress(asyncio.CancelledError): await task await app.state.http.aclose() + await app.state.safety_http.aclose() await app.state.redis.aclose() await app.state.redis_rt.aclose() await app.state.db.close() @@ -175,7 +179,7 @@ async def lifespan(app: FastAPI): telemetry.shutdown() -EXPECTED_API_DB_REVISION = "0010_contact_map_dedup" +EXPECTED_API_DB_REVISION = "0012_safety_v2_checkpoint" app = FastAPI( @@ -486,14 +490,7 @@ async def ready(request: Request, db: Session): except Exception: components[name] = "failed" components["jwks"] = "ok" if request.app.state.jwks.has_keys else "failed" - try: - safety_response = await request.app.state.http.get( - f"{str(request.app.state.settings.message_safety_url).rstrip('/')}/health/ready", - timeout=2, - ) - components["safety"] = "ok" if safety_response.is_success else "failed" - except httpx.HTTPError: - components["safety"] = "failed" + components["safety"] = "ok" if await request.app.state.safety.ready() else "failed" components["openlines"] = "ok" if await request.app.state.openlines.ready() else "degraded" components["s3"] = "ok" if await request.app.state.s3.ready() else "degraded" critical = {"postgres", "settings", "redis", "jwks", "safety"} diff --git a/codebase/backend/api-backend/app/notification_models.py b/codebase/backend/api-backend/app/notification_models.py index 83a3fd1..efc9c42 100644 --- a/codebase/backend/api-backend/app/notification_models.py +++ b/codebase/backend/api-backend/app/notification_models.py @@ -240,7 +240,7 @@ class ClientUploadDraft(Base): __table_args__ = ( CheckConstraint("context_type IN ('notification')"), CheckConstraint("size_bytes > 0"), - CheckConstraint("scan_status IN ('pending','clean','infected','failed')"), + CheckConstraint("scan_status IN ('pending','clean','bypassed','infected','failed')"), CheckConstraint("state IN ('draft','submitted','discarded')"), Index("ix_client_upload_drafts_context", "user_id", "context_type", "context_id"), Index("ix_client_upload_drafts_scan", "scan_status", "updated_at"), @@ -262,6 +262,11 @@ class ClientUploadDraft(Base): storage_bucket: Mapped[str] = mapped_column(String(255)) object_key: Mapped[str] = mapped_column(String(1024)) quarantine_object_key: Mapped[str | None] = mapped_column(String(1024)) + quarantine_version_id: Mapped[str | None] = mapped_column(String(1024)) + quarantine_etag: Mapped[str | None] = mapped_column(String(1024)) + safety_processing_mode: Mapped[str | None] = mapped_column(String(16)) + safety_config_version: Mapped[int | None] = mapped_column(BigInteger) + safety_rules_version: Mapped[str | None] = mapped_column(String(128)) upload_expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) state: Mapped[str] = mapped_column(String(16), default="draft") diff --git a/codebase/backend/api-backend/app/notification_service.py b/codebase/backend/api-backend/app/notification_service.py index d9eea7a..828df72 100644 --- a/codebase/backend/api-backend/app/notification_service.py +++ b/codebase/backend/api-backend/app/notification_service.py @@ -1004,7 +1004,14 @@ async def complete_upload( or metadata.get("ContentType") != draft.mime_type ): raise DomainError("attachment_invalid", 400, "Uploaded metadata differs") + version_id, etag = metadata.get("VersionId"), metadata.get("ETag") + if not version_id or not etag: + raise DomainError( + "dependency_unavailable", 503, "Versioned object metadata is unavailable" + ) draft.checksum_sha256 = checksum + draft.quarantine_version_id = str(version_id) + draft.quarantine_etag = str(etag) verdict = await safety.check( { "message_id": str(draft.id), @@ -1013,6 +1020,8 @@ async def complete_upload( "attachment": { "attachment_id": str(draft.id), "quarantine_object_key": draft.quarantine_object_key, + "quarantine_version_id": draft.quarantine_version_id, + "quarantine_etag": draft.quarantine_etag, "checksum": body.checksum, "mime_type": draft.mime_type, "size_bytes": draft.size_bytes, @@ -1020,25 +1029,33 @@ async def complete_upload( }, request_id, ) - if verdict["_status"] == 203: + if verdict["_status"] == 202: deadline = datetime.now(UTC) + timedelta( seconds=safety.settings.message_safety_task_poll_max_sec ) - while verdict["_status"] == 203 and datetime.now(UTC) < deadline: + while verdict["_status"] == 202 and datetime.now(UTC) < deadline: await asyncio.sleep(safety.settings.message_safety_task_poll_interval_sec) - verdict = await safety.poll(verdict["task_id"], request_id) + verdict = await safety.poll(verdict["_location"], request_id) + draft.safety_processing_mode = verdict.get("processing_mode") + draft.safety_config_version = verdict.get("config_version") + draft.safety_rules_version = verdict.get("rules_version") if verdict["_status"] == 200: destination = ( f"attachments/users/{user_id}/{draft.context_type}/{draft.context_id}/{draft.id}" ) - await s3.promote(draft.quarantine_object_key or draft.object_key, destination) + await s3.promote( + draft.quarantine_object_key or draft.object_key, + destination, + version_id=draft.quarantine_version_id or "", + etag=draft.quarantine_etag or "", + ) draft.storage_bucket = s3.settings.selectel_s3_bucket_attachments draft.object_key = destination draft.quarantine_object_key = None - draft.scan_status = "clean" - elif verdict["_status"] == 403 or ( - verdict["_status"] == 400 and verdict.get("verdict") == "deny" - ): + draft.scan_status = ( + "bypassed" if verdict["processing_mode"] == "mock" else "clean" + ) + elif verdict["_status"] == 403: if draft.quarantine_object_key: await s3.delete_quarantine(draft.quarantine_object_key) draft.scan_status = "infected" diff --git a/codebase/backend/api-backend/app/services.py b/codebase/backend/api-backend/app/services.py index d49ea59..b2c897c 100644 --- a/codebase/backend/api-backend/app/services.py +++ b/codebase/backend/api-backend/app/services.py @@ -737,7 +737,14 @@ async def complete_attachment( raise DomainError("dependency_unavailable", 503, "Object storage is unavailable") from exc if int(head["ContentLength"]) != item.size_bytes or head.get("ContentType") != item.mime_type: raise DomainError("attachment_checksum_mismatch", 400, "Uploaded metadata does not match") + version_id, etag = head.get("VersionId"), head.get("ETag") + if not version_id or not etag: + raise DomainError( + "dependency_unavailable", 503, "Versioned object metadata is unavailable" + ) item.checksum_sha256 = checksum + item.quarantine_version_id = str(version_id) + item.quarantine_etag = str(etag) item.completed_at = datetime.now(UTC) session.add( audit( @@ -886,6 +893,8 @@ async def send_message( payload["attachment"] = { "attachment_id": str(attachment.id), "quarantine_object_key": attachment.quarantine_object_key, + "quarantine_version_id": attachment.quarantine_version_id, + "quarantine_etag": attachment.quarantine_etag, "checksum": f"sha256:{attachment.checksum_sha256}", "mime_type": attachment.mime_type, "size_bytes": attachment.size_bytes, @@ -893,14 +902,20 @@ async def send_message( outbox: DeliveryOutbox | None = None try: verdict = await safety.check(payload, context.request_id) - if verdict["_status"] == 203: + task: SafetyTask | None = None + if verdict["_status"] == 202: task_id = verdict["task_id"] task = SafetyTask( task_id=task_id, + poll_location=verdict["_location"], message_id=message.id, attachment_id=attachment.id if attachment else None, quarantine_object_key=attachment.quarantine_object_key if attachment else None, status="polling", + processing_mode=verdict["processing_mode"], + config_version=verdict["config_version"], + rules_version=verdict["rules_version"], + expires_at=datetime.fromisoformat(verdict["expires_at"].replace("Z", "+00:00")), deadline_at=now + timedelta(seconds=settings.message_safety_task_poll_max_sec + 900), next_poll_at=now, @@ -910,16 +925,18 @@ async def send_message( deadline = time_monotonic() + settings.message_safety_task_poll_max_sec while time_monotonic() < deadline: await sleep(settings.message_safety_task_poll_interval_sec) - verdict = await safety.poll(task_id, context.request_id) - if verdict["_status"] != 203: + verdict = await safety.poll(task.poll_location, context.request_id) + if verdict["_status"] != 202: break + task.poll_location = verdict["_location"] else: raise DependencyFailure(timeout=True) - if verdict["_status"] == 403 or ( - verdict["_status"] == 400 - and verdict.get("error", {}).get("code") == "stub_final_error" - and verdict.get("verdict") == "deny" - ): + message.safety_processing_mode = verdict["processing_mode"] + message.safety_config_version = verdict["config_version"] + message.safety_rules_version = verdict["rules_version"] + if task: + task.status = "completed" + if verdict["_status"] == 403: message.text = "" message.safety_status = "blocked" message.delivery_status = "rejected" @@ -957,11 +974,18 @@ async def send_message( raise DependencyFailure() if attachment and attachment.quarantine_object_key: destination = f"attachments/dialogs/{dialog_id}/{attachment.id}" - await s3.promote(attachment.quarantine_object_key, destination) + await s3.promote( + attachment.quarantine_object_key, + destination, + version_id=attachment.quarantine_version_id or "", + etag=attachment.quarantine_etag or "", + ) attachment.storage_bucket = settings.selectel_s3_bucket_attachments attachment.object_key = destination attachment.quarantine_object_key = None - attachment.scan_status = "clean" + attachment.scan_status = ( + "bypassed" if verdict["processing_mode"] == "mock" else "clean" + ) message.safety_status = "allowed" outbox = DeliveryOutbox( message_id=message.id, diff --git a/codebase/backend/api-backend/app/settings.py b/codebase/backend/api-backend/app/settings.py index 3893a03..aa92cab 100644 --- a/codebase/backend/api-backend/app/settings.py +++ b/codebase/backend/api-backend/app/settings.py @@ -1,6 +1,7 @@ from functools import lru_cache +from typing import Literal -from pydantic import AnyHttpUrl, Field, SecretStr +from pydantic import AnyHttpUrl, Field, SecretStr, model_validator from pydantic_settings import BaseSettings, SettingsConfigDict @@ -25,6 +26,10 @@ class Settings(BaseSettings): message_safety_url: AnyHttpUrl = Field(alias="MESSAGE_SAFETY_URL") message_safety_service_token: SecretStr = Field(alias="MESSAGE_SAFETY_SERVICE_TOKEN") + message_safety_ca_file: str | None = Field(default=None, alias="MESSAGE_SAFETY_CA_FILE") + message_safety_api_prefix: Literal["/internal/safety/v2"] = Field( + default="/internal/safety/v2", alias="MESSAGE_SAFETY_API_PREFIX" + ) message_safety_post_timeout_sec: float = Field( default=5, alias="MESSAGE_SAFETY_POST_TIMEOUT_SEC" ) @@ -71,6 +76,15 @@ class Settings(BaseSettings): default=None, alias="NOTIFICATIONS_TOKEN_PRODUCER_TEST" ) + @model_validator(mode="after") + def require_safety_tls_in_deployed_environments(self) -> "Settings": + if self.app_env not in {"local", "test"}: + if str(self.message_safety_url).split(":", 1)[0] != "https": + raise ValueError("MESSAGE_SAFETY_URL must use HTTPS") + if not self.message_safety_ca_file: + raise ValueError("MESSAGE_SAFETY_CA_FILE is required") + return self + @property def issuer(self) -> str: return f"{str(self.keycloak_public_url).rstrip('/')}/realms/{self.keycloak_realm}" diff --git a/codebase/backend/api-backend/app/workers.py b/codebase/backend/api-backend/app/workers.py index 9d17d4b..13f5186 100644 --- a/codebase/backend/api-backend/app/workers.py +++ b/codebase/backend/api-backend/app/workers.py @@ -7,7 +7,15 @@ import redis.asyncio as redis import structlog from sqlalchemy import delete, select -from app.db import Database, DeliveryOutbox, Dialog, Message, MessageAttachment, SafetyTask +from app.db import ( + Database, + DeliveryOutbox, + Dialog, + Message, + MessageAttachment, + SafetyTask, + UserIdentity, +) from app.integrations import ( DependencyFailure, OpenLinesClient, @@ -107,7 +115,7 @@ async def safety_once( .where( SafetyTask.status.in_(["polling", "failed"]), SafetyTask.next_poll_at <= datetime.now(UTC), - SafetyTask.deadline_at > datetime.now(UTC), + SafetyTask.expires_at > datetime.now(UTC), ) .with_for_update(skip_locked=True) .limit(batch_size) @@ -127,7 +135,7 @@ async def safety_once( continue message = None try: - verdict = await safety.poll(task.task_id, f"worker-{worker_id}") + verdict = await safety.poll(task.poll_location, f"worker-{worker_id}") message = await session.get(Message, task.message_id) attachment = ( await session.get(MessageAttachment, task.attachment_id) @@ -135,16 +143,70 @@ async def safety_once( else None ) if verdict["_status"] == 200 and message: + message.safety_processing_mode = verdict["processing_mode"] + message.safety_config_version = verdict["config_version"] + message.safety_rules_version = verdict["rules_version"] if attachment and attachment.quarantine_object_key: destination = f"attachments/dialogs/{message.dialog_id}/{attachment.id}" - await s3.promote(attachment.quarantine_object_key, destination) + await s3.promote( + attachment.quarantine_object_key, + destination, + version_id=attachment.quarantine_version_id or "", + etag=attachment.quarantine_etag or "", + ) attachment.storage_bucket = s3.settings.selectel_s3_bucket_attachments attachment.object_key = destination attachment.quarantine_object_key = None - attachment.scan_status = "clean" + attachment.scan_status = ( + "bypassed" + if verdict["processing_mode"] == "mock" + else "clean" + ) message.safety_status = "allowed" task.status = "completed" + dialog = await session.get(Dialog, message.dialog_id) + user = ( + await session.get(UserIdentity, dialog.user_id) + if dialog + else None + ) + if dialog and user: + session.add( + DeliveryOutbox( + message_id=message.id, + external_chat_id=dialog.id, + payload_json={ + "message_id": str(message.id), + "external_chat_id": str(dialog.id), + "occurred_at": message.occurred_at.isoformat(), + "user": { + "id": str(user.id), + "display_name": user.phone_number, + }, + "message": { + "content_kind": message.content_kind, + "text": message.text, + "files": ( + [{ + "attachment_id": str(attachment.id), + "name": attachment.safe_file_name, + "mime_type": attachment.mime_type, + "size_bytes": attachment.size_bytes, + "_storage_bucket": attachment.storage_bucket, + "_object_key": attachment.object_key, + }] + if attachment + else [] + ), + }, + }, + next_attempt_at=datetime.now(UTC), + ) + ) elif verdict["_status"] == 403 and message: + message.safety_processing_mode = verdict["processing_mode"] + message.safety_config_version = verdict["config_version"] + message.safety_rules_version = verdict["rules_version"] message.text = "" message.safety_status = "blocked" message.delivery_status = "rejected" @@ -153,10 +215,18 @@ async def safety_once( attachment.scan_status = "infected" task.status = "completed" else: + if verdict["_status"] == 202: + task.poll_location = verdict["_location"] task.next_poll_at = datetime.now(UTC) + timedelta(seconds=2) - except DependencyFailure: + except DependencyFailure as exc: task.attempt_count += 1 - task.status = "failed" + terminal = exc.terminal or ( + exc.code == "task_not_found" and task.attempt_count >= 2 + ) + task.status = "terminal_failed" if terminal else "failed" + task.last_error_code = exc.code + if terminal and message: + message.delivery_status = "failed" task.next_poll_at = datetime.now(UTC) + timedelta( seconds=min(300, 2**task.attempt_count) ) diff --git a/codebase/backend/api-backend/docker-compose.yml b/codebase/backend/api-backend/docker-compose.yml index 98562bc..7ee140e 100644 --- a/codebase/backend/api-backend/docker-compose.yml +++ b/codebase/backend/api-backend/docker-compose.yml @@ -28,6 +28,8 @@ services: KEYCLOAK_REALM: ${KEYCLOAK_REALM} KEYCLOAK_AUDIENCE: ${KEYCLOAK_AUDIENCE} MESSAGE_SAFETY_URL: ${MESSAGE_SAFETY_URL} + MESSAGE_SAFETY_API_PREFIX: /internal/safety/v2 + MESSAGE_SAFETY_CA_FILE: /run/config/message-safety-internal-ca.pem MESSAGE_SAFETY_POST_TIMEOUT_SEC: ${MESSAGE_SAFETY_POST_TIMEOUT_SEC:-5} MESSAGE_SAFETY_TASK_POLL_INTERVAL_SEC: ${MESSAGE_SAFETY_TASK_POLL_INTERVAL_SEC:-2} MESSAGE_SAFETY_TASK_POLL_MAX_SEC: ${MESSAGE_SAFETY_TASK_POLL_MAX_SEC:-300} @@ -53,6 +55,11 @@ services: - selectel_s3_access_key - selectel_s3_secret_key - cursor_hmac_secret + volumes: + - type: bind + source: ${MESSAGE_SAFETY_CA_HOST_PATH} + target: /run/config/message-safety-internal-ca.pem + read_only: true healthcheck: test: - CMD diff --git a/codebase/backend/api-backend/tests/contract/test_clients.py b/codebase/backend/api-backend/tests/contract/test_clients.py index 22b7996..b36a1dd 100644 --- a/codebase/backend/api-backend/tests/contract/test_clients.py +++ b/codebase/backend/api-backend/tests/contract/test_clients.py @@ -63,17 +63,35 @@ async def test_s3_presigned_urls_use_virtual_hosted_addressing() -> None: @pytest.mark.asyncio async def test_safety_contract_status_and_service_token() -> None: + task_id = str(uuid.uuid4()) + async def handler(request: httpx.Request) -> httpx.Response: assert request.headers["X-Service-Token"] == "safety-token" - assert request.url.path == "/internal/safety/v1/messages/check" - return httpx.Response(203, json={"verdict": "pending", "task_id": "task-1"}) + assert request.url.path == "/internal/safety/v2/messages/check" + return httpx.Response( + 202, + headers={ + "Location": f"/internal/safety/v2/messages/tasks/{task_id}", + "Retry-After": "2", + }, + json={ + "verdict": "pending", + "processing_mode": "standard", + "config_version": 1, + "rules_version": "2026-01-01", + "task_id": task_id, + "poll_after_ms": 2000, + "expires_at": "2026-08-06T12:00:00Z", + }, + ) async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: result = await SafetyClient(settings(), http).check( {"message_id": str(uuid.uuid4()), "content_kind": "text", "text": "hello"}, "request-1", ) - assert result == {"verdict": "pending", "task_id": "task-1", "_status": 203} + assert result["_status"] == 202 + assert result["_location"] == f"/internal/safety/v2/messages/tasks/{task_id}" @pytest.mark.asyncio @@ -85,12 +103,23 @@ async def test_safety_file_body_uses_exact_attachment_schema() -> None: assert body["attachment"] == { "attachment_id": str(attachment_id), "quarantine_object_key": "quarantine/users/u/file", + "quarantine_version_id": "version-1", + "quarantine_etag": '"etag-1"', "mime_type": "application/pdf", "size_bytes": 42, "checksum": "sha256:" + "a" * 64, } assert "file" not in body - return httpx.Response(200, json={"verdict": "allow"}) + return httpx.Response( + 200, + json={ + "verdict": "allow", + "processing_mode": "standard", + "config_version": 1, + "rules_version": "2026-01-01", + "rule_id": "safety.all_checks_passed", + }, + ) payload = { "message_id": str(uuid.uuid4()), @@ -99,6 +128,8 @@ async def test_safety_file_body_uses_exact_attachment_schema() -> None: "attachment": { "attachment_id": str(attachment_id), "quarantine_object_key": "quarantine/users/u/file", + "quarantine_version_id": "version-1", + "quarantine_etag": '"etag-1"', "mime_type": "application/pdf", "size_bytes": 42, "checksum": "sha256:" + "a" * 64, @@ -121,6 +152,47 @@ async def test_safety_auth_failure_is_dependency_failure() -> None: ) +@pytest.mark.asyncio +async def test_safety_poll_uses_location_and_rejects_untrusted_location() -> None: + task_id = str(uuid.uuid4()) + + async def handler(request: httpx.Request) -> httpx.Response: + assert request.url.path == f"/internal/safety/v2/messages/tasks/{task_id}" + return httpx.Response( + 403, + json={ + "verdict": "deny", + "processing_mode": "standard", + "config_version": 2, + "rules_version": "2026-08-06", + "rule_id": "file.malware_detected", + "reason_code": "message_blocked", + }, + ) + + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = SafetyClient(settings(), http) + result = await client.poll( + f"/internal/safety/v2/messages/tasks/{task_id}", "request-1" + ) + assert result["_status"] == 403 + with pytest.raises(DependencyFailure, match="invalid_safety_location"): + await client.poll("https://attacker.example/task-1", "request-1") + + +@pytest.mark.asyncio +async def test_safety_fails_closed_on_malformed_success() -> None: + async def handler(_: httpx.Request) -> httpx.Response: + return httpx.Response(200, json={"verdict": "allow"}) + + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + with pytest.raises(DependencyFailure, match="invalid_safety_response"): + await SafetyClient(settings(), http).check( + {"message_id": str(uuid.uuid4()), "content_kind": "text", "text": "hello"}, + "request-1", + ) + + @pytest.mark.asyncio async def test_openlines_contract_uses_bearer_and_idempotency() -> None: message_id = uuid.uuid4() diff --git a/codebase/backend/deployment/DEPLOYMENT_GUIDE.ru.md b/codebase/backend/deployment/DEPLOYMENT_GUIDE.ru.md index 2b9569d..cd6f65a 100644 --- a/codebase/backend/deployment/DEPLOYMENT_GUIDE.ru.md +++ b/codebase/backend/deployment/DEPLOYMENT_GUIDE.ru.md @@ -1,7 +1,7 @@ # Подробная инструкция по развертыванию и запуску HAN Chat -Эта инструкция описывает первый запуск текущего проекта на одной виртуальной -машине с Ubuntu 24.04. Все команды на VM предполагают, что проект расположен в +Эта инструкция описывает первый запуск **текущего legacy/stub проекта ВМ1** на одной виртуальной +машине с Ubuntu 24.04. Она не разворачивает target ВМ2 Processing и не подтверждает production-готовность Message Safety v2. Все команды предполагают, что проект расположен в `/opt/han-chat/backend`, а команды Docker Compose выполняются из этого каталога. PostgreSQL и Selectel S3 не запускаются в Docker Compose: их необходимо создать @@ -25,6 +25,8 @@ PostgreSQL и Selectel S3 не запускаются в Docker Compose: их н Для первого тестового запуска допустимы mock OTP, заглушка Message Safety и заглушка bitrix-sync. Они не являются полноценными production-реализациями. +Целевой cutover выполняется по `modules/module-10-deployment-runbook.md`: самостоятельная ВМ2, root Compose/systemd unit, собственный nginx с public exact CRM webhook `80/443` и private Message Safety listener `8443`, раздельные TLS-контуры, secrets/IAM, egress allow-list и local OTEL Collector. Не переносите команды этого single-VM guide на ВМ2 без VM2-specific manifests. + ## 2. Первичный вход на VM Подключитесь к созданной VM облачным пользователем: @@ -667,7 +669,7 @@ curl -fsS \ Внутренний API не должен быть опубликован: ```sh -curl -i https://chat.example.ru/internal/safety/v1/messages/check +curl -i https://chat.example.ru/internal/safety/v2/messages/check ``` Ожидаемый статус — `404`. diff --git a/codebase/backend/deployment/RUNBOOK.md b/codebase/backend/deployment/RUNBOOK.md index 43e0584..cb128e7 100644 --- a/codebase/backend/deployment/RUNBOOK.md +++ b/codebase/backend/deployment/RUNBOOK.md @@ -4,6 +4,90 @@ This is the executable checklist for the single-VM contour. PostgreSQL and S3 are managed external services. Never use `docker compose down -v`, an Alembic downgrade, or a mutable image tag during deployment. +## VM2 Processing is a separate host + +Do not run this backend/VM1 setup script on VM2. VM2 has its own bootstrap: +`codebase/services/deployment/scripts/setup-vm.sh`, and its authoritative +operator checklist is `codebase/services/deployment/RUNBOOK.ru.md`. + +The VM2 ownership boundary is intentionally different from the legacy VM1 +script: `deploy` is **not** a member of the `docker` group. Root owns +`/opt/han-chat/services`, Compose, units, helpers, `.env`, allow-lists and +secret mappings. Deploy may write only to `/var/lib/han-deploy/incoming` and +may invoke exact systemd/safety-mode commands installed in sudoers. +The separate `admin` account is break-glass only: it has its own Ed25519 key +and a separate local sudo password. Root, deploy and admin keys must differ. + +Initial VM2 bootstrap commands: + +```sh +# Local operator workstation: upload only the reviewed setup script. +scp codebase/services/deployment/scripts/setup-vm.sh \ + root@:/root/setup-vm2.sh + +# VM2 root: install host packages/roles/firewalls; this does not start Compose. +chmod 0700 /root/setup-vm2.sh +DEPLOY_AUTHORIZED_KEY_FILE=/root/bootstrap/deploy.pub \ +ADMIN_AUTHORIZED_KEY_FILE=/root/bootstrap/admin.pub \ +OPS_CIDRS='/32' \ +VM1_PRIVATE_CIDRS='/32' \ +/root/setup-vm2.sh +``` + +Generate and upload the two public keys before this command; never copy the +root key into either account. Set the admin sudo password with `passwd admin`. +Keep the root session open and verify both key-based logins plus `sudo -v` as +admin in separate sessions. Only then rerun as VM2 root with +`HARDEN_SSH=true SKIP_APT_UPGRADE=true` to disable direct root SSH. + +Release transfer is performed as deploy, while activation and installation +remain root operations: + +```sh +# deploy: receive and inspect only. +cd /var/lib/han-deploy/incoming +sha256sum vm2-services-.tar.gz +tar -tzf vm2-services-.tar.gz + +# root: verify the operator-provided digest, activate root-owned files, +# then rerun setup-vm.sh so it installs fixed helpers and systemd units. +printf '%s %s\n' '' \ + /var/lib/han-deploy/incoming/vm2-services-.tar.gz | sha256sum --check - +ARCHIVE=/var/lib/han-deploy/incoming/vm2-services-.tar.gz +if tar -tzf "$ARCHIVE" | grep -Eq '(^/|(^|/)\.\.(/|$)|^services/\.env$)'; then exit 1; fi +if tar -tzf "$ARCHIVE" | grep -Ev '^services(/|$)' | grep -q .; then exit 1; fi +if tar -tvzf "$ARCHIVE" | awk '$1 ~ /^[lh]/ {found=1} END {exit !found}'; then exit 1; fi +STAGING="$(mktemp -d /opt/han-chat/.vm2-release.XXXXXX)" +tar -xzf "$ARCHIVE" \ + -C "$STAGING" --no-same-owner --no-same-permissions +test -f "$STAGING/services/docker-compose.yml" +rsync -a --delete --exclude=.env --chown=root:root --chmod=D755,F644 \ + "$STAGING/services/" /opt/han-chat/services/ +rm -rf -- "$STAGING" +OPS_CIDRS='/32' \ +VM1_PRIVATE_CIDRS='/32' \ +DEPLOY_AUTHORIZED_KEY_FILE=/root/bootstrap/deploy.pub \ +ADMIN_AUTHORIZED_KEY_FILE=/root/bootstrap/admin.pub \ +HARDEN_SSH=true SKIP_APT_UPGRADE=true \ +/root/setup-vm2.sh +``` + +After root configures `.env`, Selectel encrypted credentials, loader mapping, +TLS and CIDR allow-lists, root synchronizes secrets, runs preflight/migrations +and performs the first start. Subsequent routine operations available to +deploy are limited to: + +```sh +sudo systemctl restart han-secrets-vm2.service +sudo systemctl restart han-processing.service +sudo systemctl --no-pager status han-processing.service +sudo journalctl --no-pager -u han-processing.service +``` + +Exact archive activation, file installation, credential creation, migration +and first-start commands are documented in the VM2 Russian runbook referenced +above. They must not be replaced with direct Docker access for deploy. + ## Gate 0 — decisions and ownership - [ ] Release SHA/digests, maintenance window, on-call and rollback owner recorded. diff --git a/codebase/backend/deployment/docker-compose.jobs.yml b/codebase/backend/deployment/docker-compose.jobs.yml index 8388424..5ddd9ea 100644 --- a/codebase/backend/deployment/docker-compose.jobs.yml +++ b/codebase/backend/deployment/docker-compose.jobs.yml @@ -32,7 +32,9 @@ x-api-job-environment: &api-job-environment KEYCLOAK_INTERNAL_URL: ${KEYCLOAK_INTERNAL_URL:-http://keycloak:8080/auth} KEYCLOAK_REALM: ${KEYCLOAK_REALM:-han-chat} KEYCLOAK_AUDIENCE: ${KEYCLOAK_AUDIENCE:-han-chat-api} - MESSAGE_SAFETY_URL: ${MESSAGE_SAFETY_URL:-http://message-safety:8080} + MESSAGE_SAFETY_URL: ${MESSAGE_SAFETY_URL} + MESSAGE_SAFETY_API_PREFIX: /internal/safety/v2 + MESSAGE_SAFETY_CA_FILE: /run/config/message-safety-internal-ca.pem MESSAGE_SAFETY_POST_TIMEOUT_SEC: ${MESSAGE_SAFETY_POST_TIMEOUT_SEC:-5} MESSAGE_SAFETY_TASK_POLL_INTERVAL_SEC: ${MESSAGE_SAFETY_TASK_POLL_INTERVAL_SEC:-2} MESSAGE_SAFETY_TASK_POLL_MAX_SEC: ${MESSAGE_SAFETY_TASK_POLL_MAX_SEC:-300} @@ -127,6 +129,7 @@ services: && python -m app.cli.validate_settings volumes: - ${PG_CA_HOST_PATH}:/run/secrets/pg-ca.pem:ro + - ${MESSAGE_SAFETY_CA_HOST_PATH}:/run/config/message-safety-internal-ca.pem:ro - ./app-settings.production-like.yaml:/deployment/app-settings.production-like.yaml:ro networks: [backend, egress] restart: "no" diff --git a/codebase/backend/deployment/scripts/seed-personal-notifications-test.sh b/codebase/backend/deployment/scripts/seed-personal-notifications-test.sh index 27df693..3113d9f 100644 --- a/codebase/backend/deployment/scripts/seed-personal-notifications-test.sh +++ b/codebase/backend/deployment/scripts/seed-personal-notifications-test.sh @@ -236,6 +236,7 @@ write_payload urgent < +SECRETS_SOURCE=selectel +MESSAGE_SAFETY_IMAGE=/han-message-safety@sha256: +BITRIX_SYNC_IMAGE=/han-bitrix-sync@sha256: +NGINX_IMAGE=nginxinc/nginx-unprivileged@sha256: +REDIS_IMAGE=redis@sha256: +CLAMAV_IMAGE=clamav/clamav@sha256: +OTEL_COLLECTOR_IMAGE=otel/opentelemetry-collector-contrib@sha256: + +PROCESSING_PUBLIC_HOST= +PROCESSING_PRIVATE_BIND_ADDRESS= +PG_CA_HOST_PATH=/etc/han/ca/managed-postgresql-ca.pem + +MESSAGE_SAFETY_HOST=0.0.0.0 +MESSAGE_SAFETY_PORT=8080 +MESSAGE_SAFETY_WORKER_CONCURRENCY=5 +MESSAGE_SAFETY_DNS_RESOLVERS= +MESSAGE_SAFETY_CLAMAV_HOST=clamd +MESSAGE_SAFETY_CLAMAV_PORT=3310 +MESSAGE_SAFETY_ARTIFACTS_DIR=/app/app/artifacts +MESSAGE_SAFETY_MODE_FILE=/etc/han-chat/message-safety-mode.env + +SELECTEL_S3_ENDPOINT_URL=https://s3.storage.selcloud.ru +SELECTEL_S3_BUCKET_QUARANTINE= + +BITRIX_SYNC_ENABLED=false +BITRIX_SYNC_MODE=disabled +BITRIX_SYNC_CONTACT_USER_ID_FIELD=UF_CRM_ +BITRIX_SYNC_CONTACT_REGISTERED_FIELD=UF_CRM_ +BITRIX_SYNC_CONTACT_CITIZENSHIP_FIELD=UF_CRM_ +BITRIX_SYNC_PORTAL_HOST=.bitrix24.ru +BITRIX_SYNC_PORTAL_MEMBER_ID= +BITRIX_SYNC_PUBLIC_BASE_URL=https:// +BITRIX_WEBHOOK_ALLOWED_CIDRS= +BITRIX_SYNC_HTTP_TIMEOUT_SEC=10 +BITRIX_SYNC_DB_POOL_SIZE=5 + +OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317 +OTEL_REMOTE_ENDPOINT=:4317 +OTEL_REMOTE_TLS_INSECURE=true diff --git a/codebase/services/.gitignore b/codebase/services/.gitignore new file mode 100644 index 0000000..a01fe8f --- /dev/null +++ b/codebase/services/.gitignore @@ -0,0 +1,7 @@ +.env +*.local +nginx/allowlists/*.generated.conf +deployment/secrets/config.json +deployment/secrets/*.file.json +deployment/secrets/fallback/ +certs/ diff --git a/codebase/services/bitrix-sync/.env.example b/codebase/services/bitrix-sync/.env.example new file mode 100644 index 0000000..03bb32d --- /dev/null +++ b/codebase/services/bitrix-sync/.env.example @@ -0,0 +1,16 @@ +BITRIX_SYNC_ENABLED=false +BITRIX_SYNC_MODE=disabled +BITRIX_SYNC_DATABASE_URL_FILE=/run/secrets/bitrix_sync_database_url +BITRIX_SYNC_CRM_REST_WEBHOOK_URL_FILE=/run/secrets/bitrix_sync_crm_url +BITRIX_SYNC_CONTACT_RECEIVER_TOKEN_FILE=/run/secrets/bitrix_sync_contact_token +BITRIX_SYNC_ALERT_RECEIVER_TOKEN_FILE=/run/secrets/bitrix_sync_alert_token +BITRIX_SYNC_SERVICE_TOKEN_FILE=/run/secrets/bitrix_sync_service_token +BITRIX_SYNC_PORTAL_HOST=portal.example.bitrix24.ru +BITRIX_SYNC_PORTAL_MEMBER_ID=replace-with-member-id +BITRIX_SYNC_PUBLIC_BASE_URL=https://sync.example.ru +BITRIX_SYNC_CONTACT_USER_ID_FIELD=UF_CRM_100 +BITRIX_SYNC_CONTACT_REGISTERED_FIELD=UF_CRM_101 +BITRIX_SYNC_CONTACT_CITIZENSHIP_FIELD=UF_CRM_102 +BITRIX_SYNC_WEBHOOK_ALLOWED_CIDRS=203.0.113.0/24 +BITRIX_SYNC_HTTP_TIMEOUT_SEC=10 +BITRIX_SYNC_DB_POOL_SIZE=5 diff --git a/codebase/services/bitrix-sync/Dockerfile b/codebase/services/bitrix-sync/Dockerfile new file mode 100644 index 0000000..0fe6996 --- /dev/null +++ b/codebase/services/bitrix-sync/Dockerfile @@ -0,0 +1,18 @@ +ARG PYTHON_IMAGE=python:3.12.11-slim +FROM ${PYTHON_IMAGE} AS build +WORKDIR /build +COPY pyproject.toml ./ +COPY app ./app +RUN pip install --no-cache-dir --prefix=/install . + +FROM ${PYTHON_IMAGE} +ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PATH="/opt/venv/bin:${PATH}" +RUN groupadd --gid 10001 han && useradd --uid 10001 --gid 10001 --no-create-home han +COPY --from=build /install /usr/local +COPY --chown=10001:10001 app /srv/app +COPY --chown=10001:10001 alembic /srv/alembic +COPY --chown=10001:10001 alembic.ini openapi.yaml /srv/ +WORKDIR /srv +USER 10001:10001 +EXPOSE 8080 +ENTRYPOINT ["han-bitrix-sync-api"] diff --git a/codebase/services/bitrix-sync/README.md b/codebase/services/bitrix-sync/README.md new file mode 100644 index 0000000..ae66027 --- /dev/null +++ b/codebase/services/bitrix-sync/README.md @@ -0,0 +1,72 @@ +# bitrix-sync + +Изолированный Python 3.12 сервис durable-синхронизации Contact между `han_app` и +Битрикс24. Сервис не участвует в Open Lines и не имеет HTTP-зависимости от +`api-backend`. + +## Entrypoints + +- `han-bitrix-sync-api` — health, internal status и два bounded robot receiver; +- `han-bitrix-sync-worker` — queue/webhook/rebind workflows с lease fencing; +- `han-bitrix-sync-reconciliation` — один advisory-lock incremental run; +- `alembic upgrade head` — отдельная контролируемая миграция, не startup DDL. + +Disabled mode требует только `BITRIX_SYNC_ENABLED=false` и +`BITRIX_SYNC_MODE=disabled`, не читает БД и не принимает webhook. Full mode +валидирует весь каталог secret files, portal identity, custom fields, HTTPS host +lock и непустой CIDR allow-list до startup. + +## Границы безопасности + +- CRM credential URL используется как единый секрет; redirect выключен, TLS + проверяется, REST method выбирается только из закрытого allow-list. +- Receiver принимает только `application/x-www-form-urlencoded` с bounded + content length, числом и длиной полей. Query token сравнивается constant-time. +- nginx должен перезаписывать `X-Real-IP` из TCP peer, проверять CIDR до proxy и + не логировать `$request_uri`, args или body. Контейнер receiver недоступен + напрямую. +- DB хранит только hash CRM-master значений в snapshot; safe command projection + не содержит PII. URL credential, form body и token не логируются. +- Запись CRM-master полей выполняется в одной транзакции после + `SET LOCAL han.sync_suppress='true'`. + +## Локальные проверки + +Лёгкие проверки, не требующие Docker, сервиса или реального PostgreSQL: + +```text +python -m pytest +python -m ruff check app tests +``` + +PostgreSQL integration и Bitrix contract suites намеренно являются внешними +gates: локальный managed PostgreSQL не поднимается Compose-файлом. + +## External gates до `BITRIX_SYNC_ENABLED=true` + +1. Применить migrations migration-role и проверить grants runtime-role. +2. На disposable managed PostgreSQL проверить concurrent `SKIP LOCKED`, + lease expiry/fencing, active mapping uniqueness, rebind partial failure, + transaction-local GUC без утечки и crash после CRM success. +3. Подтвердить на целевом портале wire-контракты `duplicate.findbycomm`, + Contact add/get/update, mixed `batch`, custom fields, enum dictionary и + `crm.item.list` с `opened=1`, registration REST field `=1`. +4. Заполнить и активировать валидную `business_alerts` settings version: + entity/category/stage/field IDs и responsible party. Placeholder `null` + запрещает alert receiver. +5. Проверить least-privilege credential negative tests; credential администратора + запрещён. +6. Валидировать nginx exact routes, no-redirect HTTP policy, body/rate limits, + version-controlled CIDR и отсутствие query/body в access/error/traces. +7. Запустить synthetic webhook с реальным robot form contract, затем убедиться, + что durable inbox commit предшествует `202`. +8. Выполнить 10k incremental reconciliation/load gate, webhook-loss recovery, + 429/5xx/TLS/DNS/timeout/uncertain-create и restart-at-each-step tests. +9. Проверить container image digest, dependency/SBOM/vulnerability scan и + compose hardening; root Compose ВМ2 подключает этот fragment отдельно. +10. Зафиксировать cutover watermark, отменить только pre-cutover active tasks, + выполнить disabled preflight и затем controlled enablement. + +`compose.fragment.yaml` — сервисный фрагмент, не root Compose и не команда +развёртывания. Reconciliation entrypoint выполняет один run; расписание задаёт +root-owned scheduler/deployment layer. diff --git a/codebase/services/bitrix-sync/alembic.ini b/codebase/services/bitrix-sync/alembic.ini new file mode 100644 index 0000000..9d3809d --- /dev/null +++ b/codebase/services/bitrix-sync/alembic.ini @@ -0,0 +1,30 @@ +[alembic] +script_location = alembic +prepend_sys_path = . +sqlalchemy.url = postgresql+asyncpg://unused + +[loggers] +keys = root,sqlalchemy,alembic +[handlers] +keys = console +[formatters] +keys = generic +[logger_root] +level = WARN +handlers = console +qualname = +[logger_sqlalchemy] +level = WARN +handlers = +qualname = sqlalchemy.engine +[logger_alembic] +level = INFO +handlers = +qualname = alembic +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic +[formatter_generic] +format = %(levelname)-5.5s [%(name)s] %(message)s diff --git a/codebase/services/bitrix-sync/alembic/env.py b/codebase/services/bitrix-sync/alembic/env.py new file mode 100644 index 0000000..88a3815 --- /dev/null +++ b/codebase/services/bitrix-sync/alembic/env.py @@ -0,0 +1,58 @@ +from __future__ import annotations + +import asyncio +import os +from pathlib import Path + +from sqlalchemy import pool +from sqlalchemy.ext.asyncio import async_engine_from_config + +from alembic import context +from app.repository import postgres_ssl_context + + +def migration_url() -> str: + path = os.getenv("BITRIX_SYNC_MIGRATION_DATABASE_URL_FILE") + if not path: + raise RuntimeError("BITRIX_SYNC_MIGRATION_DATABASE_URL_FILE is required") + value = Path(path).read_text(encoding="utf-8").rstrip("\r\n") + if not value: + raise RuntimeError("Bitrix migration database URL file is empty") + return value + + +def run_migrations_offline() -> None: + context.configure( + url=migration_url(), + target_metadata=None, + literal_binds=True, + dialect_opts={"paramstyle": "named"}, + ) + with context.begin_transaction(): + context.run_migrations() + + +async def run_async_migrations() -> None: + configuration = context.config.get_section(context.config.config_ini_section) or {} + configuration["sqlalchemy.url"] = migration_url() + engine = async_engine_from_config( + configuration, + prefix="sqlalchemy.", + poolclass=pool.NullPool, + connect_args={"ssl": postgres_ssl_context()}, + ) + + def run_sync_migrations(connection) -> None: + context.configure(connection=connection, target_metadata=None, compare_type=True) + with context.begin_transaction(): + context.run_migrations() + + async with engine.connect() as connection: + await connection.run_sync(run_sync_migrations) + await engine.dispose() + + +if context.is_offline_mode(): + run_migrations_offline() +else: + asyncio.run(run_async_migrations()) diff --git a/codebase/services/bitrix-sync/alembic/versions/0000_legacy_sync_baseline.py b/codebase/services/bitrix-sync/alembic/versions/0000_legacy_sync_baseline.py new file mode 100644 index 0000000..1bf9448 --- /dev/null +++ b/codebase/services/bitrix-sync/alembic/versions/0000_legacy_sync_baseline.py @@ -0,0 +1,20 @@ +"""Preserve the legacy connectivity-stub Alembic revision. + +Revision ID: 0001_sync_baseline +Revises: +""" + +from collections.abc import Sequence + +revision: str = "0001_sync_baseline" +down_revision: str | None = None +branch_labels: str | Sequence[str] | None = None +depends_on: str | Sequence[str] | None = None + + +def upgrade() -> None: + """The legacy connectivity stub owned no runtime tables.""" + + +def downgrade() -> None: + """The legacy connectivity stub owned no runtime tables.""" diff --git a/codebase/services/bitrix-sync/alembic/versions/0001_bitrix_sync_full.py b/codebase/services/bitrix-sync/alembic/versions/0001_bitrix_sync_full.py new file mode 100644 index 0000000..ec108b4 --- /dev/null +++ b/codebase/services/bitrix-sync/alembic/versions/0001_bitrix_sync_full.py @@ -0,0 +1,356 @@ +"""Create durable bitrix_sync schema and contracts. + +Revision ID: 0001_bitrix_sync_full +Revises: 0001_sync_baseline +Create Date: 2026-08-06 +""" + +from collections.abc import Sequence + +from alembic import op + +revision: str = "0001_bitrix_sync_full" +down_revision: str | None = "0001_sync_baseline" +branch_labels: str | Sequence[str] | None = None +depends_on: str | Sequence[str] | None = None + + +def _execute_script(script: str) -> None: + """Execute simple DDL statements separately for asyncpg compatibility.""" + for statement in script.split(";"): + if statement.strip(): + op.execute(statement) + + +def upgrade() -> None: + op.execute("CREATE EXTENSION IF NOT EXISTS pgcrypto") + op.execute("CREATE SCHEMA IF NOT EXISTS bitrix_sync") + _execute_script( + """ + CREATE TABLE bitrix_sync.workflow_instances ( + id uuid PRIMARY KEY, + workflow_type varchar(64) NOT NULL CHECK (workflow_type IN + ('contact.map_or_create','contact.update','contact.deactivate','contact.rebind', + 'contact.webhook','contact.reconciliation','alert.reconciliation')), + user_id uuid, + external_id varchar(128), + state varchar(24) NOT NULL CHECK (state IN + ('created','running','waiting_crm','waiting_retry','waiting_manual', + 'succeeded','failed','cancelled')), + current_step varchar(64) NOT NULL, + source_task_id uuid UNIQUE, + deadline_at timestamptz NOT NULL, + outcome varchar(64), + completed_at timestamptz, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now() + ); + CREATE INDEX ix_workflow_claim + ON bitrix_sync.workflow_instances(state,updated_at) + WHERE state IN ('created','running','waiting_crm','waiting_retry'); + + CREATE TABLE bitrix_sync.entity_external_mapping ( + id uuid PRIMARY KEY, + entity_type varchar(64) NOT NULL, + entity_id uuid NOT NULL, + external_system varchar(32) NOT NULL DEFAULT 'bitrix24' + CHECK (external_system='bitrix24'), + external_entity_type varchar(32) NOT NULL DEFAULT 'contact' + CHECK (external_entity_type='contact'), + external_id varchar(128) NOT NULL, + status varchar(16) NOT NULL CHECK (status IN ('active','closed','broken')), + opened_at timestamptz NOT NULL, + closed_at timestamptz, + close_reason varchar(64), + workflow_id uuid REFERENCES bitrix_sync.workflow_instances(id), + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now(), + CHECK ((status='active' AND closed_at IS NULL) OR + (status IN ('closed','broken') + AND (closed_at IS NOT NULL OR close_reason IS NOT NULL))) + ); + CREATE UNIQUE INDEX uq_mapping_active_entity + ON bitrix_sync.entity_external_mapping(external_system,entity_type,entity_id) + WHERE status='active'; + CREATE UNIQUE INDEX uq_mapping_active_external + ON bitrix_sync.entity_external_mapping + (external_system,external_entity_type,external_id) + WHERE status='active'; + CREATE INDEX ix_mapping_history + ON bitrix_sync.entity_external_mapping(entity_id,opened_at DESC); + + CREATE TABLE bitrix_sync.crm_commands ( + id uuid PRIMARY KEY, + workflow_id uuid NOT NULL REFERENCES bitrix_sync.workflow_instances(id), + command_type varchar(40) NOT NULL CHECK (command_type IN + ('duplicate_find','contact_get','contact_add','contact_update', + 'citizenship_fields_get','contact_incremental_list', + 'alert_get','alert_add','alert_update', + 'rebind_target_get','rebind_old_get')), + safe_request jsonb NOT NULL DEFAULT '{}', + status varchar(24) NOT NULL CHECK (status IN + ('pending','leased','in_flight','succeeded','retry','retry_wait', + 'uncertain','reconcile','dead_letter','permanent','rate_limited')), + attempt_count integer NOT NULL DEFAULT 0 CHECK (attempt_count>=0), + next_attempt_at timestamptz NOT NULL DEFAULT now(), + locked_by varchar(128), + locked_until timestamptz, + lease_token uuid, + batch_id uuid, + correlation_id uuid, + safe_response jsonb, + safe_error_code varchar(64), + http_status integer, + completed_at timestamptz, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now() + ); + CREATE INDEX ix_crm_command_claim + ON bitrix_sync.crm_commands(status,next_attempt_at,created_at); + CREATE INDEX ix_crm_command_workflow + ON bitrix_sync.crm_commands(workflow_id,created_at); + + CREATE TABLE bitrix_sync.webhook_inbox ( + id uuid PRIMARY KEY, + receiver_type varchar(16) NOT NULL CHECK (receiver_type IN ('contact','alert')), + event_type varchar(64) NOT NULL, + event_id varchar(255), + source_timestamp timestamptz, + external_entity_id varchar(128) NOT NULL, + dedup_fingerprint varchar(64), + source_ip inet, + status varchar(16) NOT NULL CHECK (status IN + ('received','coalesced','processing','processed','retry_wait','dead_letter')), + coalesced_count integer NOT NULL DEFAULT 1, + attempt_count integer NOT NULL DEFAULT 0, + next_attempt_at timestamptz NOT NULL DEFAULT now(), + locked_by varchar(128), + locked_until timestamptz, + lease_token uuid, + received_at timestamptz NOT NULL, + last_received_at timestamptz NOT NULL, + processed_at timestamptz, + safe_error_code varchar(64) + ); + CREATE UNIQUE INDEX uq_webhook_event_id + ON bitrix_sync.webhook_inbox(receiver_type,event_id) WHERE event_id IS NOT NULL; + CREATE INDEX ix_webhook_claim + ON bitrix_sync.webhook_inbox(status,next_attempt_at,received_at); + CREATE UNIQUE INDEX uq_webhook_active_entity + ON bitrix_sync.webhook_inbox(receiver_type,external_entity_id) + WHERE status IN ('received','processing','retry_wait'); + """ + ) + _execute_script( + """ + CREATE SEQUENCE bitrix_sync.business_alert_number_seq; + CREATE TABLE bitrix_sync.business_alerts ( + id uuid PRIMARY KEY, + alert_number bigint NOT NULL DEFAULT nextval('bitrix_sync.business_alert_number_seq'), + fingerprint varchar(64) NOT NULL, + alert_type varchar(64) NOT NULL, + severity varchar(16) NOT NULL CHECK (severity IN ('info','warning','critical')), + app_user_id uuid, + current_external_id varchar(128), + selected_external_id varchar(128), + candidate_external_ids text[] NOT NULL DEFAULT '{}', + remote_item_id varchar(128), + remote_stage_id varchar(128), + previous_alert_id uuid REFERENCES bitrix_sync.business_alerts(id), + workflow_id uuid REFERENCES bitrix_sync.workflow_instances(id), + status varchar(24) NOT NULL CHECK (status IN + ('open','in_progress','resolved','closed_without_resolution','remote_missing')), + occurrence_count integer NOT NULL DEFAULT 1, + first_occurred_at timestamptz NOT NULL, + last_occurred_at timestamptz NOT NULL, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now() + ); + CREATE UNIQUE INDEX uq_business_alert_open + ON bitrix_sync.business_alerts(alert_type,fingerprint) WHERE status='open'; + CREATE INDEX ix_business_alert_remote + ON bitrix_sync.business_alerts(remote_item_id) WHERE remote_item_id IS NOT NULL; + + CREATE TABLE bitrix_sync.rebind_requests ( + id uuid PRIMARY KEY, + user_id uuid NOT NULL, + old_external_id varchar(128), + target_external_id varchar(128) NOT NULL, + reason varchar(500) NOT NULL, + operator_id varchar(128) NOT NULL, + workflow_id uuid NOT NULL UNIQUE REFERENCES bitrix_sync.workflow_instances(id), + status varchar(24) NOT NULL CHECK (status IN + ('pending','processing','retry_wait','succeeded','failed','cancelled')), + safe_error_code varchar(64), + requested_at timestamptz NOT NULL DEFAULT now(), + completed_at timestamptz, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now() + ); + CREATE INDEX ix_rebind_claim + ON bitrix_sync.rebind_requests(status,requested_at) + WHERE status IN ('pending','retry_wait'); + + CREATE TABLE bitrix_sync.contact_snapshots ( + id uuid PRIMARY KEY, + mapping_id uuid NOT NULL REFERENCES bitrix_sync.entity_external_mapping(id), + user_id uuid NOT NULL, + external_id varchar(128) NOT NULL, + full_name_hash varchar(64), + email_hash varchar(64), + phone_hash varchar(64), + citizenship_hash varchar(64), + citizenship_enum_id varchar(128), + citizenship_dictionary_loaded_at timestamptz, + source_updated_at timestamptz, + app_version varchar(128), + last_applied_source varchar(24) NOT NULL CHECK (last_applied_source IN + ('webhook','reconciliation','app_create','app_update')), + last_webhook_received_at timestamptz, + last_webhook_source_at timestamptz, + profile_stale boolean NOT NULL DEFAULT false, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now(), + UNIQUE(mapping_id) + ); + CREATE INDEX ix_contact_snapshot_source + ON bitrix_sync.contact_snapshots(source_updated_at); + + CREATE TABLE bitrix_sync.settings_versions ( + id uuid PRIMARY KEY, + version bigint NOT NULL UNIQUE, + validation_status varchar(16) NOT NULL + CHECK (validation_status IN ('pending','valid','invalid')), + validation_errors jsonb NOT NULL DEFAULT '[]', + active boolean NOT NULL DEFAULT false, + created_by varchar(128) NOT NULL, + created_at timestamptz NOT NULL DEFAULT now(), + activated_at timestamptz + ); + CREATE UNIQUE INDEX uq_settings_version_active + ON bitrix_sync.settings_versions(active) WHERE active=true; + + CREATE TABLE bitrix_sync.settings ( + id uuid PRIMARY KEY, + version_id uuid NOT NULL REFERENCES bitrix_sync.settings_versions(id), + key varchar(128) NOT NULL, + value_type varchar(16) NOT NULL + CHECK (value_type IN ('integer','number','boolean','object')), + value_json jsonb NOT NULL, + validation_status varchar(16) NOT NULL CHECK (validation_status IN ('valid','invalid')), + active boolean NOT NULL DEFAULT false, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now(), + UNIQUE(version_id,key) + ); + CREATE INDEX ix_settings_active ON bitrix_sync.settings(key) WHERE active=true; + + CREATE TABLE bitrix_sync.technical_dead_letters ( + id uuid PRIMARY KEY, + workflow_id uuid REFERENCES bitrix_sync.workflow_instances(id), + command_id uuid REFERENCES bitrix_sync.crm_commands(id), + operation varchar(64) NOT NULL, + safe_error_code varchar(64) NOT NULL, + attempt_count integer NOT NULL DEFAULT 0, + deadline_at timestamptz, + correlation_id uuid, + failed_at timestamptz NOT NULL, + created_at timestamptz NOT NULL DEFAULT now() + ); + CREATE INDEX ix_technical_dlq_failed + ON bitrix_sync.technical_dead_letters(failed_at DESC); + + CREATE TABLE bitrix_sync.reconciliation_cursors ( + job_type varchar(64) PRIMARY KEY, + watermark timestamptz NOT NULL, + overlap_seconds integer NOT NULL CHECK (overlap_seconds>=0), + last_success_at timestamptz, + last_scanned_count integer NOT NULL DEFAULT 0, + last_updated_count integer NOT NULL DEFAULT 0, + recovered_without_webhook_count integer NOT NULL DEFAULT 0, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now() + ); + + CREATE TABLE bitrix_sync.limiter_coordination ( + limiter_key varchar(128) PRIMARY KEY, + tokens numeric(12,6) NOT NULL, + capacity numeric(12,6) NOT NULL CHECK (capacity>0), + refill_per_second numeric(12,6) NOT NULL CHECK (refill_per_second>0), + updated_at timestamptz NOT NULL, + blocked_until timestamptz, + method_class_blocks jsonb NOT NULL DEFAULT '{}', + fencing_token bigint NOT NULL DEFAULT 0 + ); + + CREATE TABLE bitrix_sync.citizenship_dictionary ( + enum_id varchar(128) PRIMARY KEY, + display_value varchar(255) NOT NULL, + loaded_at timestamptz NOT NULL, + expires_at timestamptz NOT NULL + ); + """ + ) + op.execute( + """ + CREATE OR REPLACE FUNCTION bitrix_sync.request_bitrix_contact_rebind( + p_user_id uuid, + p_target_b24_id varchar, + p_reason varchar, + p_operator_id varchar + ) RETURNS uuid + LANGUAGE plpgsql + SECURITY DEFINER + SET search_path=bitrix_sync,pg_temp + AS $$ + DECLARE + v_old_id varchar(128); + v_request_id uuid := gen_random_uuid(); + v_workflow_id uuid := gen_random_uuid(); + BEGIN + IF p_target_b24_id !~ '^[1-9][0-9]*$' + OR length(trim(p_reason)) < 5 + OR length(trim(p_operator_id)) < 1 THEN + RAISE EXCEPTION 'invalid rebind request' USING ERRCODE='22023'; + END IF; + SELECT external_id INTO v_old_id + FROM bitrix_sync.entity_external_mapping + WHERE entity_id=p_user_id AND entity_type='contact' + AND external_system='bitrix24' AND status='active' + FOR UPDATE; + IF EXISTS ( + SELECT 1 FROM bitrix_sync.entity_external_mapping + WHERE external_system='bitrix24' AND external_entity_type='contact' + AND external_id=p_target_b24_id AND status='active' + AND entity_id<>p_user_id + ) THEN + RAISE EXCEPTION 'target contact has another active mapping' + USING ERRCODE='23505'; + END IF; + INSERT INTO bitrix_sync.workflow_instances + (id,workflow_type,user_id,external_id,state,current_step,deadline_at,created_at,updated_at) + VALUES + (v_workflow_id,'contact.rebind',p_user_id,p_target_b24_id,'created', + 'validate_contacts',now()+interval '24 hours',now(),now()); + INSERT INTO bitrix_sync.rebind_requests + (id,user_id,old_external_id,target_external_id,reason,operator_id, + workflow_id,status,requested_at,created_at,updated_at) + VALUES + (v_request_id,p_user_id,v_old_id,p_target_b24_id,trim(p_reason), + trim(p_operator_id),v_workflow_id,'pending',now(),now(),now()); + RETURN v_request_id; + END; + $$; + """ + ) + op.execute( + """ + REVOKE ALL ON FUNCTION + bitrix_sync.request_bitrix_contact_rebind(uuid,varchar,varchar,varchar) + FROM PUBLIC + """ + ) + + +def downgrade() -> None: + raise RuntimeError("bitrix_sync production migration is forward-only") diff --git a/codebase/services/bitrix-sync/alembic/versions/0002_app_queue_contract.py b/codebase/services/bitrix-sync/alembic/versions/0002_app_queue_contract.py new file mode 100644 index 0000000..a20872e --- /dev/null +++ b/codebase/services/bitrix-sync/alembic/versions/0002_app_queue_contract.py @@ -0,0 +1,85 @@ +"""Adopt the App queue contract and migrate legacy mappings. + +Revision ID: 0002_app_queue_contract +Revises: 0001_bitrix_sync_full +Create Date: 2026-08-06 +""" + +from collections.abc import Sequence + +from alembic import op + +revision: str = "0002_app_queue_contract" +down_revision: str | None = "0001_bitrix_sync_full" +branch_labels: str | Sequence[str] | None = None +depends_on: str | Sequence[str] | None = None + + +def upgrade() -> None: + op.execute( + """ + DO $$ + BEGIN + IF to_regclass('han_app.entity_external_mapping') IS NOT NULL THEN + EXECUTE $copy$ + INSERT INTO bitrix_sync.entity_external_mapping + (id,entity_type,entity_id,external_system,external_entity_type, + external_id,status,opened_at,closed_at,close_reason,created_at,updated_at) + SELECT id,entity_type,entity_id,'bitrix24','contact', + external_id,'active',coalesce(created_at,now()),NULL,NULL, + coalesce(created_at,now()),coalesce(created_at,now()) + FROM han_app.entity_external_mapping + ON CONFLICT DO NOTHING + $copy$; + IF EXISTS ( + SELECT 1 FROM han_app.entity_external_mapping old + LEFT JOIN bitrix_sync.entity_external_mapping new ON new.id=old.id + WHERE new.id IS NULL + ) THEN + RAISE EXCEPTION 'legacy mapping migration verification failed'; + END IF; + END IF; + END $$; + """ + ) + + op.execute( + """ + INSERT INTO bitrix_sync.settings_versions + (id,version,validation_status,active,created_by,created_at,activated_at) + VALUES ('00000000-0000-0000-0000-000000000001',1,'valid',true,'migration',now(),now()) + ON CONFLICT DO NOTHING + """ + ) + op.execute( + """ + INSERT INTO bitrix_sync.settings + (id,version_id,key,value_type,value_json,validation_status,active,created_at,updated_at) + VALUES + (gen_random_uuid(),'00000000-0000-0000-0000-000000000001','worker','object', + jsonb_build_object( + 'batch_size',20,'batch_wait_ms',200,'claim_size',20,'lease_seconds',60, + 'limiter_refill_per_sec',2,'limiter_burst',2,'max_in_flight',2, + 'retry_base_seconds',1,'retry_max_seconds',900,'retry_horizon_seconds',86400 + ), + 'valid',true,now(),now()), + (gen_random_uuid(),'00000000-0000-0000-0000-000000000001','reconciliation','object', + jsonb_build_object( + 'contact_interval_seconds',900,'alert_interval_seconds',3600, + 'overlap_seconds',300,'recovered_spike_threshold',20 + ), + 'valid',true,now(),now()), + (gen_random_uuid(),'00000000-0000-0000-0000-000000000001','business_alerts','object', + jsonb_build_object( + 'entity_type_id',NULL,'category_id',NULL,'stage_new',NULL, + 'stage_in_progress',NULL,'stage_resolved',NULL, + 'stage_closed_without_resolution',NULL,'sla_business_hours',8 + ), + 'valid',true,now(),now()) + ON CONFLICT DO NOTHING; + """ + ) + + +def downgrade() -> None: + raise RuntimeError("App queue contract migration is forward-only") diff --git a/codebase/services/bitrix-sync/app/__init__.py b/codebase/services/bitrix-sync/app/__init__.py new file mode 100644 index 0000000..b86bacf --- /dev/null +++ b/codebase/services/bitrix-sync/app/__init__.py @@ -0,0 +1 @@ +"""HAN Bitrix24 synchronization service.""" diff --git a/codebase/services/bitrix-sync/app/config.py b/codebase/services/bitrix-sync/app/config.py new file mode 100644 index 0000000..9915957 --- /dev/null +++ b/codebase/services/bitrix-sync/app/config.py @@ -0,0 +1,137 @@ +from __future__ import annotations + +import ipaddress +import re +from functools import cached_property +from pathlib import Path +from urllib.parse import urlsplit + +from pydantic import Field, SecretStr, model_validator +from pydantic_settings import BaseSettings, SettingsConfigDict + +FIELD_RE = re.compile(r"^UF_CRM_[0-9]+$") +MEMBER_RE = re.compile(r"^[A-Za-z0-9_-]{8,128}$") + + +def _read_secret(value: SecretStr | None, path: Path | None) -> SecretStr | None: + if value and value.get_secret_value(): + return value + if path: + text = path.read_text(encoding="utf-8").strip() + return SecretStr(text) if text else None + return None + + +class Settings(BaseSettings): + model_config = SettingsConfigDict(env_prefix="BITRIX_SYNC_", extra="ignore") + + enabled: bool = False + mode: str = "disabled" + database_url: SecretStr | None = None + database_url_file: Path | None = None + crm_rest_webhook_url: SecretStr | None = None + crm_rest_webhook_url_file: Path | None = None + contact_receiver_token: SecretStr | None = None + contact_receiver_token_file: Path | None = None + contact_receiver_previous_token: SecretStr | None = None + alert_receiver_token: SecretStr | None = None + alert_receiver_token_file: Path | None = None + alert_receiver_previous_token: SecretStr | None = None + service_token: SecretStr | None = None + service_token_file: Path | None = None + + portal_host: str | None = None + portal_member_id: str | None = None + public_base_url: str | None = None + contact_user_id_field: str | None = None + contact_registered_field: str | None = None + contact_citizenship_field: str | None = None + webhook_allowed_cidrs: str = "" + + http_timeout_sec: float = Field(default=10, ge=1, le=60) + db_pool_size: int = Field(default=5, ge=1, le=30) + webhook_max_body_bytes: int = Field(default=16_384, ge=1024, le=65_536) + webhook_max_fields: int = Field(default=24, ge=8, le=64) + lease_seconds: int = Field(default=60, ge=10, le=600) + claim_size: int = Field(default=20, ge=1, le=100) + batch_size: int = Field(default=20, ge=1, le=50) + batch_wait_ms: int = Field(default=200, ge=10, le=5000) + limiter_refill_per_sec: float = Field(default=2, gt=0, le=50) + limiter_burst: int = Field(default=2, ge=1, le=50) + max_in_flight: int = Field(default=2, ge=1, le=20) + retry_base_seconds: float = Field(default=1, ge=0.1, le=60) + retry_max_seconds: float = Field(default=900, ge=1, le=3600) + retry_horizon_seconds: int = Field(default=86_400, ge=60, le=604_800) + reconciliation_overlap_seconds: int = Field(default=300, ge=0, le=3600) + reconciliation_interval_seconds: int = Field(default=900, ge=60, le=86_400) + + @model_validator(mode="after") + def validate_mode(self) -> Settings: + self.database_url = _read_secret(self.database_url, self.database_url_file) + self.crm_rest_webhook_url = _read_secret( + self.crm_rest_webhook_url, self.crm_rest_webhook_url_file + ) + self.contact_receiver_token = _read_secret( + self.contact_receiver_token, self.contact_receiver_token_file + ) + self.alert_receiver_token = _read_secret( + self.alert_receiver_token, self.alert_receiver_token_file + ) + self.service_token = _read_secret(self.service_token, self.service_token_file) + + expected_mode = "full" if self.enabled else "disabled" + if self.mode != expected_mode: + raise ValueError(f"mode must be {expected_mode!r} when enabled={self.enabled}") + if not self.enabled: + return self + + required = { + "database_url": self.database_url, + "crm_rest_webhook_url": self.crm_rest_webhook_url, + "contact_receiver_token": self.contact_receiver_token, + "alert_receiver_token": self.alert_receiver_token, + "service_token": self.service_token, + "portal_host": self.portal_host, + "portal_member_id": self.portal_member_id, + "public_base_url": self.public_base_url, + "contact_user_id_field": self.contact_user_id_field, + "contact_registered_field": self.contact_registered_field, + "contact_citizenship_field": self.contact_citizenship_field, + } + missing = [name for name, value in required.items() if not value] + if missing: + raise ValueError("missing full-mode settings: " + ", ".join(missing)) + for name in ( + "contact_user_id_field", + "contact_registered_field", + "contact_citizenship_field", + ): + if not FIELD_RE.fullmatch(str(getattr(self, name))): + raise ValueError(f"{name} must match UF_CRM_") + if not MEMBER_RE.fullmatch(str(self.portal_member_id)): + raise ValueError("portal_member_id has invalid format") + + crm = urlsplit(self.crm_rest_webhook_url.get_secret_value()) + public = urlsplit(str(self.public_base_url)) + if crm.scheme != "https" or crm.hostname != self.portal_host or crm.port not in (None, 443): + raise ValueError("CRM URL must be HTTPS on the approved portal host") + if public.scheme != "https" or not public.hostname or public.query or public.fragment: + raise ValueError("public_base_url must be a query-free HTTPS origin") + if not self.allowed_networks: + raise ValueError("webhook_allowed_cidrs cannot be empty in full mode") + return self + + @cached_property + def allowed_networks(self) -> tuple[ipaddress.IPv4Network | ipaddress.IPv6Network, ...]: + values = [item.strip() for item in self.webhook_allowed_cidrs.split(",") if item.strip()] + return tuple(ipaddress.ip_network(item, strict=True) for item in values) + + @staticmethod + def rest_field_name(field: str) -> str: + if not FIELD_RE.fullmatch(field): + raise ValueError("invalid Bitrix custom field") + return "ufCrm_" + field.removeprefix("UF_CRM_") + + +def load_settings() -> Settings: + return Settings() diff --git a/codebase/services/bitrix-sync/app/crm.py b/codebase/services/bitrix-sync/app/crm.py new file mode 100644 index 0000000..4bf3f87 --- /dev/null +++ b/codebase/services/bitrix-sync/app/crm.py @@ -0,0 +1,185 @@ +from __future__ import annotations + +import asyncio +import ssl +from dataclasses import dataclass +from datetime import UTC, datetime +from enum import StrEnum +from typing import Any +from urllib.parse import urljoin, urlsplit + +import httpx + + +class CrmOutcome(StrEnum): + SUCCEEDED = "succeeded" + RETRY = "retry" + UNCERTAIN = "uncertain" + PERMANENT = "permanent" + RATE_LIMITED = "rate_limited" + + +@dataclass(frozen=True) +class CrmResult: + outcome: CrmOutcome + result: Any = None + error_code: str | None = None + http_status: int | None = None + retry_after: float | None = None + + +class CrmClient: + """Host-locked, verified-TLS Bitrix client; redirects are never followed.""" + + def __init__(self, credential_url: str, approved_host: str, timeout: float) -> None: + parsed = urlsplit(credential_url) + if parsed.scheme != "https" or parsed.hostname != approved_host: + raise ValueError("credential URL is outside approved Bitrix host") + self._base_url = credential_url.rstrip("/") + "/" + self._host = approved_host + self._client = httpx.AsyncClient( + timeout=httpx.Timeout(timeout), + verify=ssl.create_default_context(), + follow_redirects=False, + limits=httpx.Limits(max_connections=4, max_keepalive_connections=2), + headers={"Accept": "application/json"}, + ) + + async def close(self) -> None: + await self._client.aclose() + + async def call(self, method: str, params: dict[str, Any], *, mutating: bool) -> CrmResult: + if method not in ALLOWED_METHODS: + raise ValueError("unapproved CRM method") + url = urljoin(self._base_url, method + ".json") + if urlsplit(url).hostname != self._host: + raise ValueError("CRM host changed during URL construction") + try: + response = await self._client.post(url, json=params) + except (httpx.ConnectError, httpx.ReadError, httpx.RemoteProtocolError): + return CrmResult(CrmOutcome.RETRY, error_code="crm_network") + except httpx.TimeoutException: + outcome = CrmOutcome.UNCERTAIN if mutating else CrmOutcome.RETRY + return CrmResult(outcome, error_code="crm_timeout") + if response.is_redirect: + return CrmResult( + CrmOutcome.PERMANENT, + error_code="crm_redirect_rejected", + http_status=response.status_code, + ) + retry_after = _retry_after(response) + if response.status_code in (408, 429) or response.status_code >= 500: + return CrmResult( + CrmOutcome.RETRY, + error_code=f"crm_http_{response.status_code}", + http_status=response.status_code, + retry_after=retry_after, + ) + try: + payload = response.json() + except ValueError: + return CrmResult( + CrmOutcome.PERMANENT, + error_code="crm_malformed_response", + http_status=response.status_code, + ) + error = payload.get("error") + if error == "QUERY_LIMIT_EXCEEDED": + return CrmResult(CrmOutcome.RATE_LIMITED, error_code=error, retry_after=retry_after) + if error == "OPERATION_TIME_LIMIT": + return CrmResult(CrmOutcome.RETRY, error_code=error, retry_after=retry_after) + if error: + permanent = error in { + "ERROR_METHOD_NOT_FOUND", + "ERROR_WRONG_AUTH_TYPE", + "INVALID_CREDENTIALS", + "ACCESS_DENIED", + "ERROR_ARGUMENT", + } + return CrmResult( + CrmOutcome.PERMANENT if permanent else CrmOutcome.RETRY, + error_code=str(error)[:64], + http_status=response.status_code, + ) + return CrmResult(CrmOutcome.SUCCEEDED, result=payload.get("result")) + + async def batch(self, commands: list[tuple[str, dict[str, Any]]]) -> list[CrmResult]: + if not commands: + return [] + if len(commands) > 50: + raise ValueError("Bitrix batch limit exceeded") + cmd = { + str(index): f"{method}?{httpx.QueryParams(params)}" + for index, (method, params) in enumerate(commands) + if method in ALLOWED_METHODS + } + batch = await self.call("batch", {"halt": 0, "cmd": cmd}, mutating=True) + if batch.outcome != CrmOutcome.SUCCEEDED: + return [batch for _ in commands] + result = batch.result or {} + successes = result.get("result", {}) + errors = result.get("result_error", {}) + return [ + CrmResult(CrmOutcome.SUCCEEDED, result=successes.get(str(i))) + if str(i) in successes + else CrmResult(CrmOutcome.RETRY, error_code=str(errors.get(str(i), "batch_missing"))) + for i in range(len(commands)) + ] + + +ALLOWED_METHODS = frozenset( + { + "batch", + "crm.duplicate.findbycomm", + "crm.contact.get", + "crm.contact.add", + "crm.contact.update", + "crm.contact.userfield.list", + "crm.item.list", + "crm.item.get", + "crm.item.add", + "crm.item.update", + } +) + + +def _retry_after(response: httpx.Response) -> float | None: + value = response.headers.get("Retry-After") + if not value: + return None + try: + return max(0.0, float(value)) + except ValueError: + try: + retry_at = datetime.fromisoformat(value).astimezone(UTC) + return max(0.0, (retry_at - datetime.now(UTC)).total_seconds()) + except ValueError: + return None + + +class TokenBucket: + def __init__(self, refill_per_second: float, burst: int, max_in_flight: int) -> None: + self.refill_per_second = refill_per_second + self.burst = float(burst) + self.tokens = float(burst) + self.updated_at = asyncio.get_running_loop().time() + self._lock = asyncio.Lock() + self._slots = asyncio.Semaphore(max_in_flight) + + async def acquire(self) -> None: + await self._slots.acquire() + while True: + async with self._lock: + now = asyncio.get_running_loop().time() + self.tokens = min( + self.burst, self.tokens + (now - self.updated_at) * self.refill_per_second + ) + self.updated_at = now + if self.tokens >= 1: + self.tokens -= 1 + return + delay = (1 - self.tokens) / self.refill_per_second + await asyncio.sleep(delay) + + def release(self) -> None: + self._slots.release() diff --git a/codebase/services/bitrix-sync/app/domain.py b/codebase/services/bitrix-sync/app/domain.py new file mode 100644 index 0000000..8888a4b --- /dev/null +++ b/codebase/services/bitrix-sync/app/domain.py @@ -0,0 +1,106 @@ +from __future__ import annotations + +import hashlib +import random +import re +from dataclasses import dataclass +from datetime import UTC, datetime +from enum import StrEnum +from typing import Any + +PHONE_RE = re.compile(r"^\+7[0-9]{10}$") +EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$") + + +class WorkflowState(StrEnum): + CREATED = "created" + RUNNING = "running" + WAITING_CRM = "waiting_crm" + WAITING_RETRY = "waiting_retry" + WAITING_MANUAL = "waiting_manual" + SUCCEEDED = "succeeded" + FAILED = "failed" + CANCELLED = "cancelled" + + +TRANSITIONS: dict[WorkflowState, frozenset[WorkflowState]] = { + WorkflowState.CREATED: frozenset({WorkflowState.RUNNING, WorkflowState.CANCELLED}), + WorkflowState.RUNNING: frozenset( + { + WorkflowState.WAITING_CRM, + WorkflowState.WAITING_RETRY, + WorkflowState.WAITING_MANUAL, + WorkflowState.SUCCEEDED, + WorkflowState.FAILED, + WorkflowState.CANCELLED, + } + ), + WorkflowState.WAITING_CRM: frozenset( + { + WorkflowState.RUNNING, + WorkflowState.WAITING_RETRY, + WorkflowState.WAITING_MANUAL, + WorkflowState.FAILED, + } + ), + WorkflowState.WAITING_RETRY: frozenset( + {WorkflowState.RUNNING, WorkflowState.WAITING_MANUAL, WorkflowState.FAILED} + ), + WorkflowState.WAITING_MANUAL: frozenset( + {WorkflowState.RUNNING, WorkflowState.CANCELLED} + ), + WorkflowState.SUCCEEDED: frozenset(), + WorkflowState.FAILED: frozenset(), + WorkflowState.CANCELLED: frozenset(), +} + + +def assert_transition(current: WorkflowState, target: WorkflowState) -> None: + if target not in TRANSITIONS[current]: + raise ValueError(f"forbidden workflow transition {current} -> {target}") + + +@dataclass(frozen=True) +class ContactCandidate: + b24_id: str + created_at: datetime + crm_user_id: str | None + + +def validate_phone(value: str) -> str: + if not PHONE_RE.fullmatch(value): + raise ValueError("phone must be Russian E.164 +7XXXXXXXXXX") + return value + + +def choose_newest(candidates: list[ContactCandidate]) -> ContactCandidate | None: + if not candidates: + return None + return max(candidates, key=lambda item: (item.created_at, int(item.b24_id))) + + +def select_email(items: list[dict[str, Any]]) -> str | None: + valid = [ + item + for item in items + if isinstance(item.get("VALUE"), str) and EMAIL_RE.fullmatch(item["VALUE"]) + ] + work = next((item for item in valid if item.get("VALUE_TYPE") == "WORK"), None) + selected = work or (valid[0] if valid else None) + return selected["VALUE"] if selected else None + + +def safe_hash(value: str | None) -> str | None: + return hashlib.sha256(value.encode()).hexdigest() if value is not None else None + + +def full_jitter_delay( + attempt: int, base: float, maximum: float, *, rng: random.Random | None = None +) -> float: + ceiling = min(maximum, base * (2 ** max(0, attempt - 1))) + return (rng or random.SystemRandom()).uniform(0, ceiling) + + +def parse_crm_datetime(value: str) -> datetime: + parsed = datetime.fromisoformat(value.replace("Z", "+00:00")) + return parsed.astimezone(UTC) diff --git a/codebase/services/bitrix-sync/app/engine.py b/codebase/services/bitrix-sync/app/engine.py new file mode 100644 index 0000000..7cdcab8 --- /dev/null +++ b/codebase/services/bitrix-sync/app/engine.py @@ -0,0 +1,629 @@ +from __future__ import annotations + +import asyncio +import uuid +from dataclasses import dataclass, field +from typing import Any + +from sqlalchemy import text + +from app.config import Settings +from app.crm import CrmClient, CrmOutcome, CrmResult +from app.domain import ( + ContactCandidate, + choose_newest, + full_jitter_delay, + parse_crm_datetime, + select_email, + validate_phone, +) +from app.repository import LeasedTask, LeasedWebhook, Profile, Repository + + +class BusinessConflict(Exception): + def __init__(self, code: str, candidates: list[str] | None = None) -> None: + self.code = code + self.candidates = candidates or [] + super().__init__(code) + + +@dataclass +class WorkflowEngine: + repository: Repository + crm: CrmClient + settings: Settings + _in_flight: asyncio.Semaphore = field(init=False, repr=False) + + def __post_init__(self) -> None: + self._in_flight = asyncio.Semaphore(self.settings.max_in_flight) + + async def process(self, task: LeasedTask) -> None: + workflow_id = await self.repository.create_workflow(task) + profile = await self.repository.load_profile(task.user_id) + if profile is None: + await self._manual(workflow_id, "profile_missing", task.user_id) + await self.repository.complete_task(task, workflow_id) + return + try: + if task.task_type == "contact.map_or_create": + await self._map_or_create(workflow_id, profile) + elif task.task_type == "contact.update": + await self._update(workflow_id, profile) + elif task.task_type == "contact.deactivate": + await self._deactivate(workflow_id, profile) + else: + await self._technical_failure(workflow_id, "unknown_task_type") + await self.repository.complete_task(task, workflow_id) + except BusinessConflict as exc: + await self._alert(workflow_id, task.user_id, exc.code, exc.candidates) + await self._manual(workflow_id, exc.code, task.user_id) + await self.repository.complete_task(task, workflow_id) + except RetryableWorkflow as exc: + delay = exc.retry_after or full_jitter_delay( + task.attempt_count + 1, + self.settings.retry_base_seconds, + self.settings.retry_max_seconds, + ) + await self.repository.retry_task(task, exc.code, delay) + + async def process_webhook(self, item: LeasedWebhook) -> None: + if item.receiver_type == "alert": + await self.repository.complete_webhook(item) + return + user_id = await self.repository.mapped_user_for_external(item.external_id) + if user_id is None: + await self.repository.complete_webhook(item) + return + workflow_id = uuid.uuid4() + async with self.repository.transaction() as connection: + await connection.execute( + text( + """ + INSERT INTO bitrix_sync.workflow_instances + (id,workflow_type,user_id,external_id,state,current_step,deadline_at, + created_at,updated_at) + VALUES (:id,'contact.webhook',:user_id,:external_id,'running', + 'read_contact',now()+interval '24 hours',now(),now()) + """ + ), + {"id": workflow_id, "user_id": user_id, "external_id": item.external_id}, + ) + try: + result = await self._command( + workflow_id, + "contact_get", + "crm.contact.get", + {"id": item.external_id, "select": self._select_fields()}, + mutating=False, + ) + contact = result.result + if str(contact.get(self.settings.contact_user_id_field)) != str(user_id): + await self._alert( + workflow_id, + user_id, + "mapping_identity_mismatch", + [item.external_id], + ) + await self._manual(workflow_id, "mapping_identity_mismatch", user_id) + await self.repository.complete_webhook(item) + return + citizenship = await self._resolve_citizenship( + workflow_id, contact.get(self.settings.contact_citizenship_field) + ) + source_value = contact.get("DATE_MODIFY") or contact.get("updatedTime") + await self.repository.apply_crm_profile( + user_id, + item.external_id, + full_name=contact.get("NAME") or None, + citizenship=citizenship, + email=select_email(contact.get("EMAIL") or []), + source_updated_at=parse_crm_datetime(source_value) if source_value else None, + source="reconciliation" + if item.event_type == "contact.reconciliation" + else "webhook", + ) + await self.repository.complete_webhook(item) + async with self.repository.transaction() as connection: + await connection.execute( + text( + """ + UPDATE bitrix_sync.workflow_instances + SET state='succeeded',current_step='done', + completed_at=now(),updated_at=now() + WHERE id=:id + """ + ), + {"id": workflow_id}, + ) + except RetryableWorkflow: + raise + + async def _map_or_create(self, workflow_id: uuid.UUID, profile: Profile) -> None: + if profile.identity_status != "A" or profile.profile_status != "A": + await self._deactivate(workflow_id, profile) + return + validate_phone(profile.phone) + if mapped := await self.repository.active_mapping(profile.user_id): + await self._ensure_registered(workflow_id, mapped, profile.user_id) + return + + found = await self._command( + workflow_id, + "duplicate_find", + "crm.duplicate.findbycomm", + {"type": "PHONE", "values": [profile.phone], "entity_type": "CONTACT"}, + mutating=False, + ) + ids = _contact_ids(found.result) + contacts: list[dict[str, Any]] = [] + for contact_id in ids: + result = await self._command( + workflow_id, + "contact_get", + "crm.contact.get", + {"id": contact_id, "select": self._select_fields()}, + mutating=False, + ) + if isinstance(result.result, dict): + contacts.append(result.result) + + same_user = next( + ( + item + for item in contacts + if str(item.get(self.settings.contact_user_id_field)) == str(profile.user_id) + ), + None, + ) + alert_code: str | None = None + if same_user: + selected_id = str(same_user["ID"]) + elif not contacts: + selected_id = await self._create_contact(workflow_id, profile) + else: + candidates = [ + ContactCandidate( + str(item["ID"]), + parse_crm_datetime(item.get("CREATED_TIME", "1970-01-01T00:00:00Z")), + item.get(self.settings.contact_user_id_field), + ) + for item in contacts + ] + selected = choose_newest(candidates) + assert selected is not None + all_ids = [item.b24_id for item in candidates] + if selected.crm_user_id and selected.crm_user_id != str(profile.user_id): + selected_id = await self._create_contact(workflow_id, profile) + alert_code = "contact_owned_by_other_user" + else: + selected_id = selected.b24_id + await self._write_identity(workflow_id, selected_id, profile.user_id, active=True) + if len(candidates) > 1: + alert_code = "duplicate_contacts" + if alert_code: + await self._alert(workflow_id, profile.user_id, alert_code, all_ids) + await self._activate_mapping(workflow_id, profile.user_id, selected_id) + + async def _create_contact(self, workflow_id: uuid.UUID, profile: Profile) -> str: + result = await self._command( + workflow_id, + "contact_add", + "crm.contact.add", + { + "fields": { + "PHONE": [{"VALUE": profile.phone, "VALUE_TYPE": "WORK"}], + self.settings.contact_user_id_field: str(profile.user_id), + self.settings.contact_registered_field: "1", + } + }, + mutating=True, + ) + return str(result.result) + + async def _update(self, workflow_id: uuid.UUID, profile: Profile) -> None: + validate_phone(profile.phone) + mapping = await self.repository.active_mapping(profile.user_id) + if mapping is None: + await self._coalesce_map_or_create(profile.user_id) + return + await self._command( + workflow_id, + "contact_update", + "crm.contact.update", + { + "id": mapping, + "fields": {"PHONE": [{"VALUE": profile.phone, "VALUE_TYPE": "WORK"}]}, + }, + mutating=True, + ) + + async def _deactivate(self, workflow_id: uuid.UUID, profile: Profile) -> None: + mapping = await self.repository.active_mapping(profile.user_id) + if mapping is None: + return + await self._write_identity(workflow_id, mapping, profile.user_id, active=False) + async with self.repository.transaction() as connection: + await connection.execute( + text( + """ + UPDATE bitrix_sync.entity_external_mapping + SET status='closed', closed_at=now(), close_reason='deactivated', + workflow_id=:workflow_id, updated_at=now() + WHERE entity_id=:user_id AND external_id=:external_id AND status='active' + """ + ), + { + "workflow_id": workflow_id, + "user_id": profile.user_id, + "external_id": mapping, + }, + ) + + async def process_rebind(self, request_id: uuid.UUID) -> None: + async with self.repository.transaction() as connection: + request = ( + await connection.execute( + text( + """ + SELECT id,user_id,old_external_id,target_external_id,workflow_id + FROM bitrix_sync.rebind_requests + WHERE id=:id AND status IN ('pending','retry_wait') + FOR UPDATE + """ + ), + {"id": request_id}, + ) + ).mappings().first() + if not request: + return + await connection.execute( + text( + """ + UPDATE bitrix_sync.rebind_requests + SET status='processing',updated_at=now() WHERE id=:id + """ + ), + {"id": request_id}, + ) + target = await self._command( + request["workflow_id"], + "rebind_target_get", + "crm.contact.get", + {"id": request["target_external_id"], "select": self._select_fields()}, + mutating=False, + ) + target_user = target.result.get(self.settings.contact_user_id_field) + if target_user and target_user != str(request["user_id"]): + raise BusinessConflict("rebind_target_owned", [request["target_external_id"]]) + await self._write_identity( + request["workflow_id"], request["target_external_id"], request["user_id"], active=True + ) + if request["old_external_id"]: + old = await self._command( + request["workflow_id"], + "rebind_old_get", + "crm.contact.get", + {"id": request["old_external_id"], "select": self._select_fields()}, + mutating=False, + ) + if old.result.get(self.settings.contact_user_id_field) == str(request["user_id"]): + await self._write_identity( + request["workflow_id"], + request["old_external_id"], + request["user_id"], + active=False, + ) + async with self.repository.transaction() as connection: + await connection.execute( + text( + """ + UPDATE bitrix_sync.entity_external_mapping + SET status='closed',closed_at=now(),close_reason='rebind', + workflow_id=:workflow_id,updated_at=now() + WHERE entity_id=:user_id AND status='active' + """ + ), + { + "workflow_id": request["workflow_id"], + "user_id": request["user_id"], + }, + ) + await connection.execute( + text( + """ + INSERT INTO bitrix_sync.entity_external_mapping + (id,entity_type,entity_id,external_system,external_entity_type, + external_id,status,opened_at,workflow_id,created_at,updated_at) + VALUES (gen_random_uuid(),'contact',:user_id,'bitrix24','contact', + :target,'active',now(),:workflow_id,now(),now()) + """ + ), + { + "workflow_id": request["workflow_id"], + "user_id": request["user_id"], + "target": request["target_external_id"], + }, + ) + await connection.execute( + text( + """ + UPDATE bitrix_sync.rebind_requests + SET status='succeeded',completed_at=now(),updated_at=now() + WHERE id=:request_id + """ + ), + { + "request_id": request_id, + }, + ) + + async def _ensure_registered( + self, workflow_id: uuid.UUID, external_id: str, user_id: uuid.UUID + ) -> None: + contact = await self._command( + workflow_id, + "contact_get", + "crm.contact.get", + {"id": external_id, "select": self._select_fields()}, + mutating=False, + ) + if str(contact.result.get(self.settings.contact_registered_field)) not in {"1", "Y"}: + await self._write_identity(workflow_id, external_id, user_id, active=True) + + async def _resolve_citizenship( + self, workflow_id: uuid.UUID, enum_id: str | int | None + ) -> str | None: + if enum_id in (None, ""): + return None + async with self.repository.transaction() as connection: + value = ( + await connection.execute( + text( + """ + SELECT display_value FROM bitrix_sync.citizenship_dictionary + WHERE enum_id=:enum_id AND expires_at>now() + """ + ), + {"enum_id": str(enum_id)}, + ) + ).scalar_one_or_none() + if value is not None: + return value + result = await self._command( + workflow_id, + "citizenship_fields_get", + "crm.contact.userfield.list", + {"filter": {"FIELD_NAME": self.settings.contact_citizenship_field}}, + mutating=False, + ) + fields = result.result if isinstance(result.result, list) else [] + entries = fields[0].get("LIST", []) if fields else [] + async with self.repository.transaction() as connection: + for entry in entries: + if entry.get("ID") is None or not isinstance(entry.get("VALUE"), str): + continue + await connection.execute( + text( + """ + INSERT INTO bitrix_sync.citizenship_dictionary + (enum_id,display_value,loaded_at,expires_at) + VALUES (:id,:value,now(),now()+interval '1 hour') + ON CONFLICT (enum_id) DO UPDATE + SET display_value=excluded.display_value,loaded_at=now(), + expires_at=excluded.expires_at + """ + ), + {"id": str(entry["ID"]), "value": entry["VALUE"]}, + ) + match = next( + ( + entry["VALUE"] + for entry in entries + if str(entry.get("ID")) == str(enum_id) + ), + None, + ) + if match is None: + raise BusinessConflict("unknown_citizenship_enum", [str(enum_id)]) + return match + + async def _write_identity( + self, workflow_id: uuid.UUID, external_id: str, user_id: uuid.UUID, *, active: bool + ) -> None: + fields: dict[str, Any] = {self.settings.contact_registered_field: "1" if active else "0"} + fields[self.settings.contact_user_id_field] = str(user_id) if active else "" + await self._command( + workflow_id, + "contact_update", + "crm.contact.update", + {"id": external_id, "fields": fields}, + mutating=True, + ) + + async def _command( + self, + workflow_id: uuid.UUID, + command_type: str, + method: str, + params: dict[str, Any], + *, + mutating: bool, + ) -> CrmResult: + command_id = uuid.uuid4() + async with self.repository.transaction() as connection: + await connection.execute( + text( + """ + INSERT INTO bitrix_sync.crm_commands + (id,workflow_id,command_type,safe_request,status,attempt_count, + next_attempt_at,created_at,updated_at) + VALUES (:id,:workflow_id,:type,:safe_request,'in_flight',1,now(),now(),now()) + """ + ), + { + "id": command_id, + "workflow_id": workflow_id, + "type": command_type, + "safe_request": {"keys": sorted(params), "method_class": method.split(".")[-1]}, + }, + ) + while True: + limiter_delay = await self.repository.reserve_limiter_token( + self.settings.limiter_refill_per_sec, self.settings.limiter_burst + ) + if limiter_delay <= 0: + break + await asyncio.sleep(limiter_delay) + async with self._in_flight: + result = await self.crm.call(method, params, mutating=mutating) + status = result.outcome.value + async with self.repository.transaction() as connection: + await connection.execute( + text( + """ + UPDATE bitrix_sync.crm_commands + SET status=:status,safe_error_code=:error,http_status=:http_status, + safe_response=:safe_response, + completed_at=CASE WHEN :terminal THEN now() END, + updated_at=now() + WHERE id=:id + """ + ), + { + "id": command_id, + "status": status, + "error": result.error_code, + "http_status": result.http_status, + "safe_response": {"has_result": result.result is not None}, + "terminal": result.outcome in {CrmOutcome.SUCCEEDED, CrmOutcome.PERMANENT}, + }, + ) + if result.outcome == CrmOutcome.SUCCEEDED: + return result + if result.outcome == CrmOutcome.PERMANENT: + await self._technical_failure(workflow_id, result.error_code or "crm_permanent") + raise BusinessConflict("technical_configuration_failure") + raise RetryableWorkflow(result.error_code or result.outcome.value, result.retry_after) + + async def _activate_mapping( + self, workflow_id: uuid.UUID, user_id: uuid.UUID, external_id: str + ) -> None: + async with self.repository.transaction() as connection: + await connection.execute( + text( + """ + INSERT INTO bitrix_sync.entity_external_mapping + (id,entity_type,entity_id,external_system,external_entity_type, + external_id,status,opened_at,workflow_id,created_at,updated_at) + VALUES (gen_random_uuid(),'contact',:user_id,'bitrix24','contact', + :external_id,'active',now(),:workflow_id,now(),now()) + ON CONFLICT DO NOTHING + """ + ), + { + "workflow_id": workflow_id, + "user_id": user_id, + "external_id": external_id, + }, + ) + + async def _coalesce_map_or_create(self, user_id: uuid.UUID) -> None: + async with self.repository.transaction() as connection: + await connection.execute( + text( + """ + INSERT INTO han_app.sync_queue + (id,task_type,entity_type,entity_id,dedup_key,payload_json,status, + attempt_count,next_attempt_at,created_at,updated_at) + VALUES (gen_random_uuid(),'contact.map_or_create','contact',:user_id, + 'contact.map_or_create:'||:user_id::text, + jsonb_build_object('schema_version',1,'user_id',:user_id), + 'pending',0,now(),now(),now()) + ON CONFLICT DO NOTHING + """ + ), + {"user_id": user_id}, + ) + + async def _alert( + self, workflow_id: uuid.UUID, user_id: uuid.UUID, alert_type: str, candidates: list[str] + ) -> None: + fingerprint = f"{alert_type}:{user_id}" + async with self.repository.transaction() as connection: + await connection.execute( + text( + """ + INSERT INTO bitrix_sync.business_alerts + (id,fingerprint,alert_type,severity,app_user_id,candidate_external_ids, + workflow_id,status,occurrence_count,first_occurred_at,last_occurred_at, + created_at,updated_at) + VALUES (gen_random_uuid(),encode(digest(:fingerprint,'sha256'),'hex'), + :type,'warning',:user_id,:candidates,:workflow_id,'open',1, + now(),now(),now(),now()) + ON CONFLICT (alert_type,fingerprint) WHERE status='open' + DO UPDATE SET occurrence_count=business_alerts.occurrence_count+1, + last_occurred_at=now(),updated_at=now() + """ + ), + { + "fingerprint": fingerprint, + "type": alert_type, + "user_id": user_id, + "candidates": candidates, + "workflow_id": workflow_id, + }, + ) + + async def _manual(self, workflow_id: uuid.UUID, code: str, user_id: uuid.UUID) -> None: + async with self.repository.transaction() as connection: + await connection.execute( + text( + """ + UPDATE bitrix_sync.workflow_instances + SET state='waiting_manual',outcome=:code,updated_at=now() + WHERE id=:id + """ + ), + {"id": workflow_id, "code": code}, + ) + + async def _technical_failure(self, workflow_id: uuid.UUID, code: str) -> None: + async with self.repository.transaction() as connection: + await connection.execute( + text( + """ + INSERT INTO bitrix_sync.technical_dead_letters + (id,workflow_id,operation,safe_error_code,failed_at,created_at) + VALUES (gen_random_uuid(),:workflow_id,'crm_command',:code,now(),now()) + """ + ), + {"workflow_id": workflow_id, "code": code[:64]}, + ) + + def _select_fields(self) -> list[str]: + return [ + "ID", + "NAME", + "PHONE", + "EMAIL", + "CREATED_TIME", + "DATE_MODIFY", + self.settings.contact_user_id_field, + self.settings.contact_registered_field, + self.settings.contact_citizenship_field, + ] + + +class RetryableWorkflow(Exception): + def __init__(self, code: str, retry_after: float | None = None) -> None: + self.code = code + self.retry_after = retry_after + super().__init__(code) + + +def _contact_ids(result: Any) -> list[str]: + if isinstance(result, dict): + values = result.get("CONTACT", []) + else: + values = result or [] + return sorted({str(value) for value in values if str(value).isdigit()}, key=int) diff --git a/codebase/services/bitrix-sync/app/main.py b/codebase/services/bitrix-sync/app/main.py new file mode 100644 index 0000000..8134ef9 --- /dev/null +++ b/codebase/services/bitrix-sync/app/main.py @@ -0,0 +1,173 @@ +from __future__ import annotations + +import hmac +from contextlib import asynccontextmanager +from typing import Annotated + +import uvicorn +from fastapi import Depends, FastAPI, Header, HTTPException, Query, Request, Response +from fastapi.responses import JSONResponse +from sqlalchemy import text + +from app.config import Settings, load_settings +from app.repository import Repository +from app.security import WebhookValidationError, parse_bounded_form, validate_webhook + + +@asynccontextmanager +async def lifespan(app: FastAPI): + settings = load_settings() + app.state.settings = settings + app.state.repository = ( + Repository(settings.database_url.get_secret_value(), settings.db_pool_size) + if settings.enabled and settings.database_url + else None + ) + yield + if app.state.repository: + await app.state.repository.close() + + +app = FastAPI( + title="HAN Bitrix Sync", + version="0.1.0", + docs_url=None, + redoc_url=None, + lifespan=lifespan, +) + + +def settings(request: Request) -> Settings: + return request.app.state.settings + + +def repository(request: Request) -> Repository: + repo = request.app.state.repository + if repo is None: + raise HTTPException(status_code=503, detail="sync_disabled") + return repo + + +async def require_service_token( + request: Request, + authorization: Annotated[str | None, Header()] = None, +) -> None: + configured = settings(request).service_token + expected = f"Bearer {configured.get_secret_value()}" if configured else "" + if not authorization or not hmac.compare_digest(authorization, expected): + raise HTTPException(status_code=401, detail="unauthorized") + + +@app.get("/health/live", include_in_schema=True) +async def live() -> dict[str, str]: + return {"status": "live"} + + +@app.get("/health/ready", include_in_schema=True) +async def ready(request: Request) -> Response: + config = settings(request) + if not config.enabled: + return JSONResponse( + status_code=503, + content={"status": "not_ready", "reason": "sync_disabled"}, + ) + repo = repository(request) + if not await repo.ping(): + return JSONResponse(status_code=503, content={"status": "not_ready", "reason": "database"}) + return JSONResponse({"status": "ready", "mode": config.mode}) + + +@app.get( + "/internal/sync/v1/status", + dependencies=[Depends(require_service_token)], + include_in_schema=True, +) +async def sync_status(request: Request) -> dict: + result = await repository(request).status() + result["mode"] = settings(request).mode + return result + + +@app.post("/bitrix/sync/webhook/contact", status_code=202, include_in_schema=True) +async def contact_webhook( + request: Request, + token: Annotated[str | None, Query(max_length=256)] = None, + ID: Annotated[str | None, Query(pattern=r"^[1-9][0-9]{0,19}$")] = None, # noqa: N803 +) -> Response: + return await _receive(request, "contact", {"token": token or "", "ID": ID or ""}) + + +@app.post("/bitrix/sync/webhook/alert", status_code=202, include_in_schema=True) +async def alert_webhook( + request: Request, + token: Annotated[str | None, Query(max_length=256)] = None, + ID: Annotated[str | None, Query(pattern=r"^[1-9][0-9]{0,19}$")] = None, # noqa: N803 +) -> Response: + return await _receive(request, "alert", {"token": token or "", "ID": ID or ""}) + + +async def _receive(request: Request, receiver: str, query: dict[str, str]) -> Response: + config = settings(request) + if not config.enabled: + raise HTTPException(status_code=503, detail="sync_disabled") + if request.headers.get("content-type", "").split(";", 1)[0].lower() != ( + "application/x-www-form-urlencoded" + ): + raise HTTPException(status_code=400, detail="invalid_content_type") + content_length = request.headers.get("content-length") + if content_length and ( + not content_length.isdigit() or int(content_length) > config.webhook_max_body_bytes + ): + raise HTTPException(status_code=413, detail="body_too_large") + body = await request.body() + if len(body) > config.webhook_max_body_bytes: + raise HTTPException(status_code=413, detail="body_too_large") + form = parse_bounded_form(body, max_fields=config.webhook_max_fields) + # The container is reachable only from the trusted VM2 nginx network. + # nginx overwrites X-Real-IP from the TCP peer after its CIDR check. + source_ip = request.headers.get("x-real-ip") or (request.client.host if request.client else "") + alert_entity_type_id = ( + await _alert_entity_type(repository(request)) if receiver == "alert" else None + ) + try: + event = validate_webhook( + receiver, + query, + form, + source_ip, + config, + alert_entity_type_id=alert_entity_type_id, + ) + except PermissionError as exc: + raise HTTPException(status_code=403, detail="forbidden") from exc + except WebhookValidationError as exc: + raise HTTPException(status_code=400, detail="malformed_webhook") from exc + await repository(request).insert_webhook( + event.receiver_type, event.event_type, event.entity_id, event.source_ip + ) + return Response(status_code=202) + + +async def _alert_entity_type(repo: Repository) -> int | None: + async with repo.engine.connect() as connection: + value = ( + await connection.execute( + text( + """ + SELECT (value_json->>'entity_type_id')::integer + FROM bitrix_sync.settings + WHERE key='business_alerts' AND active=true AND validation_status='valid' + """ + ) + ) + ).scalar_one_or_none() + return value + + +def run() -> None: + uvicorn.run( + "app.main:app", + host="0.0.0.0", # noqa: S104 - container-only port, not host-published + port=8080, + proxy_headers=False, + ) diff --git a/codebase/services/bitrix-sync/app/mapping.py b/codebase/services/bitrix-sync/app/mapping.py new file mode 100644 index 0000000..33959b1 --- /dev/null +++ b/codebase/services/bitrix-sync/app/mapping.py @@ -0,0 +1,56 @@ +from __future__ import annotations + +from dataclasses import dataclass +from datetime import UTC, datetime, timedelta +from typing import Any + +from app.domain import select_email + + +class UnknownCitizenship(ValueError): + pass + + +@dataclass(frozen=True) +class CitizenshipEntry: + enum_id: str + display_value: str + loaded_at: datetime + + +class CitizenshipDictionary: + def __init__(self, ttl_seconds: int = 3600) -> None: + self.ttl = timedelta(seconds=ttl_seconds) + self._entries: dict[str, CitizenshipEntry] = {} + self.loaded_at: datetime | None = None + + def load(self, values: list[dict[str, Any]], now: datetime | None = None) -> None: + loaded_at = now or datetime.now(UTC) + self._entries = { + str(item["ID"]): CitizenshipEntry( + str(item["ID"]), str(item["VALUE"]), loaded_at + ) + for item in values + if item.get("ID") is not None and isinstance(item.get("VALUE"), str) + } + self.loaded_at = loaded_at + + def resolve(self, enum_id: str | int | None, now: datetime | None = None) -> str | None: + if enum_id in (None, ""): + return None + entry = self._entries.get(str(enum_id)) + if entry is None: + raise UnknownCitizenship(str(enum_id)) + if (now or datetime.now(UTC)) - entry.loaded_at > self.ttl: + raise UnknownCitizenship(str(enum_id)) + return entry.display_value + + +def crm_master_projection( + contact: dict[str, Any], citizenship: CitizenshipDictionary, citizenship_field: str +) -> dict[str, str | None]: + return { + "full_name": contact.get("NAME") or None, + "email": select_email(contact.get("EMAIL") or []), + "citizenship": citizenship.resolve(contact.get(citizenship_field)), + } diff --git a/codebase/services/bitrix-sync/app/reconciliation.py b/codebase/services/bitrix-sync/app/reconciliation.py new file mode 100644 index 0000000..fb71df2 --- /dev/null +++ b/codebase/services/bitrix-sync/app/reconciliation.py @@ -0,0 +1,139 @@ +from __future__ import annotations + +import asyncio +from datetime import UTC, datetime, timedelta +from typing import Any + +from sqlalchemy import text + +from app.config import load_settings +from app.crm import CrmClient, CrmOutcome +from app.repository import Repository + + +class IncrementalReconciler: + def __init__(self, repository: Repository, crm: CrmClient, registered_rest_field: str) -> None: + self.repository = repository + self.crm = crm + self.registered_rest_field = registered_rest_field + + async def run_once(self, overlap_seconds: int) -> int: + async with self.repository.transaction() as connection: + acquired = ( + await connection.execute( + text( + """ + SELECT pg_try_advisory_xact_lock( + hashtext('bitrix-contact-reconciliation') + ) + """ + ) + ) + ).scalar_one() + if not acquired: + return 0 + cursor = ( + await connection.execute( + text( + """ + SELECT watermark FROM bitrix_sync.reconciliation_cursors + WHERE job_type='contact_incremental' FOR UPDATE + """ + ) + ) + ).scalar_one_or_none() + started_at = datetime.now(UTC) + since = (cursor or datetime(1970, 1, 1, tzinfo=UTC)) - timedelta(seconds=overlap_seconds) + start = 0 + scanned: list[str] = [] + while True: + result = await self.crm.call( + "crm.item.list", + { + "entityTypeId": 3, + "select": ["id"], + "filter": { + ">=updatedTime": since.replace(tzinfo=None).isoformat(timespec="seconds"), + "opened": 1, + self.registered_rest_field: 1, + }, + "start": start, + }, + mutating=False, + ) + if result.outcome != CrmOutcome.SUCCEEDED: + raise RuntimeError(result.error_code or "reconciliation_failed") + payload: dict[str, Any] = result.result or {} + items = payload.get("items", payload if isinstance(payload, list) else []) + scanned.extend(str(item["id"]) for item in items if "id" in item) + next_start = payload.get("next") + if next_start is None: + break + start = int(next_start) + await self._enqueue_changed(scanned) + async with self.repository.transaction() as connection: + await connection.execute( + text( + """ + INSERT INTO bitrix_sync.reconciliation_cursors + (job_type,watermark,overlap_seconds,last_success_at,last_scanned_count, + created_at,updated_at) + VALUES ('contact_incremental',:watermark,:overlap,now(),:count,now(),now()) + ON CONFLICT (job_type) DO UPDATE + SET watermark=excluded.watermark,overlap_seconds=excluded.overlap_seconds, + last_success_at=now(),last_scanned_count=excluded.last_scanned_count, + updated_at=now() + """ + ), + {"watermark": started_at, "overlap": overlap_seconds, "count": len(scanned)}, + ) + return len(scanned) + + async def _enqueue_changed(self, external_ids: list[str]) -> None: + if not external_ids: + return + async with self.repository.transaction() as connection: + await connection.execute( + text( + """ + INSERT INTO bitrix_sync.webhook_inbox + (id,receiver_type,event_type,external_entity_id,status,coalesced_count, + received_at,last_received_at) + SELECT gen_random_uuid(),'contact','contact.reconciliation',id,'received',1, + now(),now() + FROM unnest(CAST(:ids AS text[])) id + WHERE NOT EXISTS ( + SELECT 1 FROM bitrix_sync.webhook_inbox w + WHERE w.receiver_type='contact' AND w.external_entity_id=id + AND w.status IN ('received','processing','retry_wait') + ) + """ + ), + {"ids": external_ids}, + ) + + +async def reconciliation_main() -> None: + settings = load_settings() + if not settings.enabled: + return + assert settings.database_url and settings.crm_rest_webhook_url and settings.portal_host + assert settings.contact_registered_field + repository = Repository(settings.database_url.get_secret_value(), settings.db_pool_size) + crm = CrmClient( + settings.crm_rest_webhook_url.get_secret_value(), + settings.portal_host, + settings.http_timeout_sec, + ) + reconciler = IncrementalReconciler( + repository, crm, settings.rest_field_name(settings.contact_registered_field) + ) + try: + await reconciler.run_once(settings.reconciliation_overlap_seconds) + finally: + await crm.close() + await repository.close() + + +def run() -> None: + asyncio.run(reconciliation_main()) diff --git a/codebase/services/bitrix-sync/app/repository.py b/codebase/services/bitrix-sync/app/repository.py new file mode 100644 index 0000000..5c6822d --- /dev/null +++ b/codebase/services/bitrix-sync/app/repository.py @@ -0,0 +1,533 @@ +from __future__ import annotations + +import os +import ssl +import uuid +from collections.abc import AsyncIterator +from contextlib import asynccontextmanager +from dataclasses import dataclass +from datetime import UTC, datetime +from typing import Any + +from sqlalchemy import text +from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine, create_async_engine + + +def postgres_ssl_context() -> ssl.SSLContext: + ca_file = os.environ.get("PG_CA_FILE") + if not ca_file: + raise RuntimeError("PG_CA_FILE is required") + context = ssl.create_default_context(cafile=ca_file) + context.check_hostname = True + context.verify_mode = ssl.CERT_REQUIRED + return context + + +@dataclass(frozen=True) +class LeasedTask: + id: uuid.UUID + task_type: str + user_id: uuid.UUID + lease_token: uuid.UUID + attempt_count: int + + +@dataclass(frozen=True) +class LeasedWebhook: + id: uuid.UUID + receiver_type: str + event_type: str + external_id: str + lease_token: uuid.UUID + attempt_count: int + + +@dataclass(frozen=True) +class Profile: + user_id: uuid.UUID + phone: str + identity_status: str + profile_status: str + + +class Repository: + def __init__(self, database_url: str, pool_size: int = 5) -> None: + self.engine: AsyncEngine = create_async_engine( + database_url, + pool_size=pool_size, + pool_pre_ping=True, + connect_args={"ssl": postgres_ssl_context()}, + ) + + async def close(self) -> None: + await self.engine.dispose() + + @asynccontextmanager + async def transaction(self) -> AsyncIterator[AsyncConnection]: + async with self.engine.begin() as connection: + yield connection + + async def ping(self) -> bool: + try: + async with self.engine.connect() as connection: + await connection.execute(text("SELECT 1")) + return True + except Exception: + return False + + async def claim_tasks( + self, worker_id: str, limit: int, lease_seconds: int + ) -> list[LeasedTask]: + sql = text( + """ + WITH candidates AS ( + SELECT id + FROM han_app.sync_queue + WHERE status IN ('pending','retry_wait') + AND next_attempt_at <= now() + AND (locked_until IS NULL OR locked_until < now()) + ORDER BY next_attempt_at, created_at + FOR UPDATE SKIP LOCKED + LIMIT :limit + ) + UPDATE han_app.sync_queue q + SET status='leased', locked_by=:worker_id, + locked_until=now() + make_interval(secs => :lease_seconds), + lease_token=gen_random_uuid(), updated_at=now() + FROM candidates c + WHERE q.id=c.id + RETURNING q.id, q.task_type, q.entity_id, q.lease_token, q.attempt_count + """ + ) + async with self.engine.begin() as connection: + rows = ( + await connection.execute( + sql, + {"worker_id": worker_id, "limit": limit, "lease_seconds": lease_seconds}, + ) + ).mappings() + return [ + LeasedTask( + row["id"], + row["task_type"], + row["entity_id"], + row["lease_token"], + row["attempt_count"], + ) + for row in rows + ] + + async def load_profile(self, user_id: uuid.UUID) -> Profile | None: + sql = text( + """ + SELECT i.id user_id, i.phone_number phone, i.record_status identity_status, + p.record_status profile_status + FROM han_app.user_identities i + JOIN han_app.client_profiles p ON p.user_id=i.id + WHERE i.id=:user_id + """ + ) + async with self.engine.connect() as connection: + row = (await connection.execute(sql, {"user_id": user_id})).mappings().first() + return Profile(**row) if row else None + + async def active_mapping(self, user_id: uuid.UUID) -> str | None: + sql = text( + """ + SELECT external_id FROM bitrix_sync.entity_external_mapping + WHERE external_system='bitrix24' AND entity_type='contact' + AND entity_id=:user_id AND status='active' + """ + ) + async with self.engine.connect() as connection: + return (await connection.execute(sql, {"user_id": user_id})).scalar_one_or_none() + + async def create_workflow(self, task: LeasedTask) -> uuid.UUID: + workflow_id = uuid.uuid4() + sql = text( + """ + INSERT INTO bitrix_sync.workflow_instances + (id, workflow_type, user_id, state, current_step, source_task_id, + deadline_at, created_at, updated_at) + VALUES (:id, :workflow_type, :user_id, 'created', 'load_profile', :task_id, + now() + interval '24 hours', now(), now()) + ON CONFLICT (source_task_id) DO UPDATE SET updated_at=now() + RETURNING id + """ + ) + async with self.engine.begin() as connection: + return ( + await connection.execute( + sql, + { + "id": workflow_id, + "workflow_type": task.task_type, + "user_id": task.user_id, + "task_id": task.id, + }, + ) + ).scalar_one() + + async def complete_task(self, task: LeasedTask, workflow_id: uuid.UUID) -> bool: + async with self.engine.begin() as connection: + result = await connection.execute( + text( + """ + UPDATE han_app.sync_queue + SET status='processed', completed_at=now(), locked_by=NULL, + locked_until=NULL, lease_token=NULL, updated_at=now() + WHERE id=:id AND status='leased' AND lease_token=:lease_token + """ + ), + {"id": task.id, "lease_token": task.lease_token}, + ) + if result.rowcount != 1: + return False + await connection.execute( + text( + """ + UPDATE bitrix_sync.workflow_instances + SET state='succeeded', current_step='done', outcome='processed', + completed_at=now(), updated_at=now() + WHERE id=:workflow_id AND state NOT IN ('succeeded','failed','cancelled') + """ + ), + {"workflow_id": workflow_id}, + ) + return True + + async def retry_task( + self, task: LeasedTask, safe_code: str, delay_seconds: float + ) -> bool: + sql = text( + """ + UPDATE han_app.sync_queue + SET status='retry_wait', attempt_count=attempt_count+1, + next_attempt_at=now() + make_interval(secs => :delay), + last_error_code=:code, last_error_at=now(), + locked_by=NULL, locked_until=NULL, lease_token=NULL, updated_at=now() + WHERE id=:id AND status='leased' AND lease_token=:lease_token + """ + ) + async with self.engine.begin() as connection: + result = await connection.execute( + sql, + { + "id": task.id, + "lease_token": task.lease_token, + "code": safe_code[:64], + "delay": delay_seconds, + }, + ) + return result.rowcount == 1 + + async def insert_webhook( + self, + receiver_type: str, + event_type: str, + entity_id: str, + source_ip: str, + ) -> uuid.UUID: + inbox_id = uuid.uuid4() + async with self.engine.begin() as connection: + existing = await connection.execute( + text( + """ + SELECT id FROM bitrix_sync.webhook_inbox + WHERE receiver_type=:receiver AND external_entity_id=:entity_id + AND status IN ('received','processing','retry_wait') + FOR UPDATE + """ + ), + {"receiver": receiver_type, "entity_id": entity_id}, + ) + if row := existing.first(): + await connection.execute( + text( + """ + UPDATE bitrix_sync.webhook_inbox + SET coalesced_count=coalesced_count+1, last_received_at=now() + WHERE id=:id + """ + ), + {"id": row[0]}, + ) + return row[0] + await connection.execute( + text( + """ + INSERT INTO bitrix_sync.webhook_inbox + (id, receiver_type, event_type, external_entity_id, source_ip, + status, coalesced_count, received_at, last_received_at) + VALUES (:id,:receiver,:event,:entity_id,CAST(:source_ip AS inet), + 'received',1,now(),now()) + """ + ), + { + "id": inbox_id, + "receiver": receiver_type, + "event": event_type, + "entity_id": entity_id, + "source_ip": source_ip, + }, + ) + return inbox_id + + async def claim_webhooks( + self, worker_id: str, limit: int, lease_seconds: int + ) -> list[LeasedWebhook]: + sql = text( + """ + WITH candidates AS ( + SELECT id FROM bitrix_sync.webhook_inbox + WHERE status IN ('received','retry_wait') AND next_attempt_at<=now() + AND (locked_until IS NULL OR locked_until:lease_seconds), + lease_token=gen_random_uuid() + FROM candidates c WHERE w.id=c.id + RETURNING w.id,w.receiver_type,w.event_type,w.external_entity_id, + w.lease_token,w.attempt_count + """ + ) + async with self.engine.begin() as connection: + rows = ( + await connection.execute( + sql, + {"worker_id": worker_id, "limit": limit, "lease_seconds": lease_seconds}, + ) + ).mappings() + return [ + LeasedWebhook( + row["id"], + row["receiver_type"], + row["event_type"], + row["external_entity_id"], + row["lease_token"], + row["attempt_count"], + ) + for row in rows + ] + + async def mapped_user_for_external(self, external_id: str) -> uuid.UUID | None: + async with self.engine.connect() as connection: + return ( + await connection.execute( + text( + """ + SELECT entity_id FROM bitrix_sync.entity_external_mapping + WHERE external_system='bitrix24' AND external_entity_type='contact' + AND external_id=:external_id AND status='active' + """ + ), + {"external_id": external_id}, + ) + ).scalar_one_or_none() + + async def apply_crm_profile( + self, + user_id: uuid.UUID, + external_id: str, + *, + full_name: str | None, + citizenship: str | None, + email: str | None, + source_updated_at: datetime | None, + source: str, + ) -> None: + async with self.engine.begin() as connection: + await connection.execute(text("SET LOCAL han.sync_suppress='true'")) + await connection.execute( + text( + """ + UPDATE han_app.client_profiles + SET full_name=:full_name,citizenship=:citizenship,email=:email,updated_at=now() + WHERE user_id=:user_id AND record_status='A' + """ + ), + { + "user_id": user_id, + "full_name": full_name, + "citizenship": citizenship, + "email": email, + }, + ) + await connection.execute( + text( + """ + INSERT INTO bitrix_sync.contact_snapshots + (id,mapping_id,user_id,external_id,full_name_hash,email_hash, + citizenship_hash,source_updated_at,last_applied_source, + last_webhook_received_at,created_at,updated_at) + SELECT gen_random_uuid(),m.id,:user_id,:external_id, + encode(digest(coalesce(:full_name,''),'sha256'),'hex'), + encode(digest(coalesce(:email,''),'sha256'),'hex'), + encode(digest(coalesce(:citizenship,''),'sha256'),'hex'), + :source_updated_at,:source, + CASE WHEN :source='webhook' THEN now() END,now(),now() + FROM bitrix_sync.entity_external_mapping m + WHERE m.entity_id=:user_id AND m.external_id=:external_id AND m.status='active' + ON CONFLICT (mapping_id) DO UPDATE + SET full_name_hash=excluded.full_name_hash,email_hash=excluded.email_hash, + citizenship_hash=excluded.citizenship_hash, + source_updated_at=excluded.source_updated_at, + last_applied_source=excluded.last_applied_source, + last_webhook_received_at=coalesce( + excluded.last_webhook_received_at, + bitrix_sync.contact_snapshots.last_webhook_received_at), + updated_at=now() + """ + ), + { + "user_id": user_id, + "external_id": external_id, + "full_name": full_name, + "citizenship": citizenship, + "email": email, + "source_updated_at": source_updated_at, + "source": source, + }, + ) + + async def complete_webhook(self, item: LeasedWebhook) -> bool: + async with self.engine.begin() as connection: + result = await connection.execute( + text( + """ + UPDATE bitrix_sync.webhook_inbox + SET status='processed',processed_at=now(),locked_by=NULL, + locked_until=NULL,lease_token=NULL + WHERE id=:id AND status='processing' AND lease_token=:lease_token + """ + ), + {"id": item.id, "lease_token": item.lease_token}, + ) + return result.rowcount == 1 + + async def retry_webhook( + self, item: LeasedWebhook, safe_code: str, delay_seconds: float + ) -> bool: + async with self.engine.begin() as connection: + result = await connection.execute( + text( + """ + UPDATE bitrix_sync.webhook_inbox + SET status='retry_wait',attempt_count=attempt_count+1, + next_attempt_at=now()+make_interval(secs=>:delay), + safe_error_code=:code,locked_by=NULL,locked_until=NULL,lease_token=NULL + WHERE id=:id AND status='processing' AND lease_token=:lease_token + """ + ), + { + "id": item.id, + "lease_token": item.lease_token, + "code": safe_code[:64], + "delay": delay_seconds, + }, + ) + return result.rowcount == 1 + + async def pending_rebind_ids(self, limit: int) -> list[uuid.UUID]: + async with self.engine.connect() as connection: + rows = await connection.execute( + text( + """ + SELECT id FROM bitrix_sync.rebind_requests + WHERE status IN ('pending','retry_wait') + ORDER BY requested_at LIMIT :limit + """ + ), + {"limit": limit}, + ) + return list(rows.scalars()) + + async def reserve_limiter_token(self, refill_per_second: float, burst: int) -> float: + async with self.engine.begin() as connection: + row = ( + await connection.execute( + text( + """ + SELECT tokens,capacity,refill_per_second, + extract(epoch FROM now()-updated_at) elapsed, + greatest(0,extract(epoch FROM blocked_until-now())) blocked + FROM bitrix_sync.limiter_coordination + WHERE limiter_key='bitrix24:portal' + FOR UPDATE + """ + ) + ) + ).mappings().first() + if row is None: + await connection.execute( + text( + """ + INSERT INTO bitrix_sync.limiter_coordination + (limiter_key,tokens,capacity,refill_per_second,updated_at,fencing_token) + VALUES ('bitrix24:portal',:tokens,:capacity,:refill,now(),1) + """ + ), + {"tokens": max(0, burst - 1), "capacity": burst, "refill": refill_per_second}, + ) + return 0 + blocked = float(row["blocked"] or 0) + tokens = min( + float(burst), + float(row["tokens"]) + float(row["elapsed"] or 0) * refill_per_second, + ) + if blocked > 0: + delay = blocked + elif tokens >= 1: + tokens -= 1 + delay = 0 + else: + delay = (1 - tokens) / refill_per_second + await connection.execute( + text( + """ + UPDATE bitrix_sync.limiter_coordination + SET tokens=:tokens,capacity=:capacity,refill_per_second=:refill, + updated_at=now(),fencing_token=fencing_token+1 + WHERE limiter_key='bitrix24:portal' + """ + ), + { + "tokens": tokens, + "capacity": burst, + "refill": refill_per_second, + }, + ) + return delay + + async def status(self) -> dict[str, Any]: + queries = { + "queue": "SELECT status, count(*) count FROM han_app.sync_queue GROUP BY status", + "workflows": ( + "SELECT state, count(*) count FROM bitrix_sync.workflow_instances GROUP BY state" + ), + "commands": ( + "SELECT status, count(*) count " + "FROM bitrix_sync.crm_commands GROUP BY status" + ), + "webhook_lag_seconds": ( + "SELECT coalesce(extract(epoch from now()-min(received_at)),0) " + "FROM bitrix_sync.webhook_inbox WHERE status IN ('received','retry_wait')" + ), + "settings_version": ( + "SELECT version FROM bitrix_sync.settings_versions " + "WHERE active=true AND validation_status='valid' ORDER BY activated_at DESC LIMIT 1" + ), + } + output: dict[str, Any] = {} + async with self.engine.connect() as connection: + for key, sql in queries.items(): + result = await connection.execute(text(sql)) + if key in {"queue", "workflows", "commands"}: + output[key] = {row.status: row.count for row in result} + else: + output[key] = result.scalar_one_or_none() + output["generated_at"] = datetime.now(UTC).isoformat() + return output diff --git a/codebase/services/bitrix-sync/app/security.py b/codebase/services/bitrix-sync/app/security.py new file mode 100644 index 0000000..839c04b --- /dev/null +++ b/codebase/services/bitrix-sync/app/security.py @@ -0,0 +1,120 @@ +from __future__ import annotations + +import hmac +import ipaddress +import re +from collections.abc import Mapping +from dataclasses import dataclass +from urllib.parse import parse_qsl + +from app.config import Settings + +SECRET_PATTERNS = ( + re.compile(r"(?i)(token|authorization|password|secret)=([^&\s]+)"), + re.compile(r"https://[^/\s]+/rest/[0-9]+/[^/\s]+/"), +) + + +def token_matches(received: str | None, current: str, previous: str | None = None) -> bool: + candidate = (received or "").encode() + current_match = hmac.compare_digest(candidate, current.encode()) + previous_match = hmac.compare_digest(candidate, (previous or "").encode()) + return current_match or (previous is not None and previous_match) + + +def redact(value: object) -> str: + text = str(value) + for pattern in SECRET_PATTERNS: + text = pattern.sub( + lambda match: ( + f"{match.group(1)}=[REDACTED]" + if match.lastindex == 2 + else "https://[REDACTED]/" + ), + text, + ) + if "@" in text or re.search(r"\+7[0-9]{10}", text): + return "[PII_REDACTED]" + return text[:512] + + +@dataclass(frozen=True) +class WebhookEvent: + receiver_type: str + entity_id: str + event_type: str + source_ip: str + + +class WebhookValidationError(ValueError): + pass + + +def parse_bounded_form(body: bytes, *, max_fields: int) -> dict[str, str]: + try: + pairs = parse_qsl(body.decode("utf-8"), keep_blank_values=True, max_num_fields=max_fields) + except (UnicodeDecodeError, ValueError) as exc: + raise WebhookValidationError("malformed form") from exc + if len(pairs) > max_fields: + raise WebhookValidationError("too many form fields") + data: dict[str, str] = {} + for key, value in pairs: + if len(key) > 128 or len(value) > 512: + raise WebhookValidationError("form field too long") + data[key] = value + return data + + +def validate_webhook( + receiver: str, + query: Mapping[str, str], + form: Mapping[str, str], + source_ip: str, + settings: Settings, + *, + alert_entity_type_id: int | None, +) -> WebhookEvent: + try: + ip = ipaddress.ip_address(source_ip) + except ValueError as exc: + raise WebhookValidationError("invalid source address") from exc + if not any(ip in network for network in settings.allowed_networks): + raise PermissionError("source_ip") + + configured = ( + settings.contact_receiver_token if receiver == "contact" else settings.alert_receiver_token + ) + previous = ( + settings.contact_receiver_previous_token + if receiver == "contact" + else settings.alert_receiver_previous_token + ) + if not configured or not token_matches( + query.get("token"), + configured.get_secret_value(), + previous.get_secret_value() if previous else None, + ): + raise PermissionError("token") + if form.get("auth[domain]", "").lower() != str(settings.portal_host).lower(): + raise WebhookValidationError("portal mismatch") + if form.get("auth[member_id]") != settings.portal_member_id: + raise WebhookValidationError("member mismatch") + if form.get("document_id[0]") != "crm": + raise WebhookValidationError("invalid document module") + + document_type = form.get("document_id[1]") + document_id = form.get("document_id[2]", "") + if receiver == "contact": + match = re.fullmatch(r"CONTACT_([1-9][0-9]*)", document_id) + if document_type != "CCrmDocumentContact" or not match: + raise WebhookValidationError("invalid contact document") + else: + match = re.fullmatch(r"DYNAMIC_([1-9][0-9]*)_([1-9][0-9]*)", document_id) + if not match or not document_type or "Dynamic" not in document_type: + raise WebhookValidationError("invalid alert document") + if alert_entity_type_id is None or int(match.group(1)) != alert_entity_type_id: + raise WebhookValidationError("alert entity type mismatch") + entity_id = match.group(match.lastindex or 1) + if query.get("ID") != entity_id: + raise WebhookValidationError("query/document ID mismatch") + return WebhookEvent(receiver, entity_id, f"{receiver}.changed", source_ip) diff --git a/codebase/services/bitrix-sync/app/worker.py b/codebase/services/bitrix-sync/app/worker.py new file mode 100644 index 0000000..22e0527 --- /dev/null +++ b/codebase/services/bitrix-sync/app/worker.py @@ -0,0 +1,78 @@ +from __future__ import annotations + +import asyncio +import signal +import socket +import uuid + +from app.config import load_settings +from app.crm import CrmClient +from app.domain import full_jitter_delay +from app.engine import RetryableWorkflow, WorkflowEngine +from app.repository import Repository + + +async def worker_main() -> None: + settings = load_settings() + if not settings.enabled: + return + assert settings.database_url and settings.crm_rest_webhook_url and settings.portal_host + repository = Repository(settings.database_url.get_secret_value(), settings.db_pool_size) + crm = CrmClient( + settings.crm_rest_webhook_url.get_secret_value(), + settings.portal_host, + settings.http_timeout_sec, + ) + engine = WorkflowEngine(repository, crm, settings) + stop = asyncio.Event() + loop = asyncio.get_running_loop() + for event in (signal.SIGINT, signal.SIGTERM): + try: + loop.add_signal_handler(event, stop.set) + except NotImplementedError: + pass + worker_id = f"{socket.gethostname()}:{uuid.uuid4()}" + try: + while not stop.is_set(): + tasks = await repository.claim_tasks( + worker_id, settings.claim_size, settings.lease_seconds + ) + webhooks = await repository.claim_webhooks( + worker_id, settings.claim_size, settings.lease_seconds + ) + rebind_ids = await repository.pending_rebind_ids(settings.claim_size) + if not tasks and not webhooks and not rebind_ids: + try: + await asyncio.wait_for(stop.wait(), timeout=1) + except TimeoutError: + continue + for task in tasks: + if stop.is_set(): + break + await engine.process(task) + for item in webhooks: + if stop.is_set(): + break + try: + await engine.process_webhook(item) + except RetryableWorkflow as exc: + delay = exc.retry_after or full_jitter_delay( + item.attempt_count + 1, + settings.retry_base_seconds, + settings.retry_max_seconds, + ) + await repository.retry_webhook(item, exc.code, delay) + for request_id in rebind_ids: + if stop.is_set(): + break + try: + await engine.process_rebind(request_id) + except RetryableWorkflow: + continue + finally: + await crm.close() + await repository.close() + + +def run() -> None: + asyncio.run(worker_main()) diff --git a/codebase/services/bitrix-sync/compose.fragment.yaml b/codebase/services/bitrix-sync/compose.fragment.yaml new file mode 100644 index 0000000..c23140e --- /dev/null +++ b/codebase/services/bitrix-sync/compose.fragment.yaml @@ -0,0 +1,83 @@ +services: + bitrix-sync: + build: . + image: han-bitrix-sync:${BITRIX_SYNC_IMAGE_TAG:-local} + command: ["han-bitrix-sync-api"] + user: "10001:10001" + read_only: true + security_opt: ["no-new-privileges:true"] + cap_drop: ["ALL"] + tmpfs: ["/tmp:rw,noexec,nosuid,nodev,size=16m"] + expose: ["8080"] + environment: &sync_environment + BITRIX_SYNC_ENABLED: ${BITRIX_SYNC_ENABLED:-false} + BITRIX_SYNC_MODE: ${BITRIX_SYNC_MODE:-disabled} + BITRIX_SYNC_DATABASE_URL_FILE: /run/secrets/bitrix_sync_database_url + BITRIX_SYNC_CRM_REST_WEBHOOK_URL_FILE: /run/secrets/bitrix_sync_crm_url + BITRIX_SYNC_CONTACT_RECEIVER_TOKEN_FILE: /run/secrets/bitrix_sync_contact_token + BITRIX_SYNC_ALERT_RECEIVER_TOKEN_FILE: /run/secrets/bitrix_sync_alert_token + BITRIX_SYNC_SERVICE_TOKEN_FILE: /run/secrets/bitrix_sync_service_token + BITRIX_SYNC_PORTAL_HOST: ${BITRIX_SYNC_PORTAL_HOST:-} + BITRIX_SYNC_PORTAL_MEMBER_ID: ${BITRIX_SYNC_PORTAL_MEMBER_ID:-} + BITRIX_SYNC_PUBLIC_BASE_URL: ${BITRIX_SYNC_PUBLIC_BASE_URL:-} + BITRIX_SYNC_CONTACT_USER_ID_FIELD: ${BITRIX_SYNC_CONTACT_USER_ID_FIELD:-} + BITRIX_SYNC_CONTACT_REGISTERED_FIELD: ${BITRIX_SYNC_CONTACT_REGISTERED_FIELD:-} + BITRIX_SYNC_CONTACT_CITIZENSHIP_FIELD: ${BITRIX_SYNC_CONTACT_CITIZENSHIP_FIELD:-} + BITRIX_SYNC_WEBHOOK_ALLOWED_CIDRS: ${BITRIX_WEBHOOK_ALLOWED_CIDRS:-} + volumes: &sync_secrets + - /run/han-chat/secrets/bitrix-sync/database-url:/run/secrets/bitrix_sync_database_url:ro + - /run/han-chat/secrets/bitrix-sync/crm-rest-webhook-url:/run/secrets/bitrix_sync_crm_url:ro + - /run/han-chat/secrets/bitrix-sync/contact-receiver-token:/run/secrets/bitrix_sync_contact_token:ro + - /run/han-chat/secrets/bitrix-sync/alert-receiver-token:/run/secrets/bitrix_sync_alert_token:ro + - /run/han-chat/secrets/bitrix-sync/service-token:/run/secrets/bitrix_sync_service_token:ro + networks: [backend, egress, observability] + pids_limit: 128 + mem_limit: 256m + cpus: 0.50 + restart: unless-stopped + healthcheck: + test: + ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/live',timeout=2)"] + interval: 30s + timeout: 3s + retries: 3 + + bitrix-sync-worker: + image: han-bitrix-sync:${BITRIX_SYNC_IMAGE_TAG:-local} + command: ["han-bitrix-sync-worker"] + user: "10001:10001" + read_only: true + security_opt: ["no-new-privileges:true"] + cap_drop: ["ALL"] + tmpfs: ["/tmp:rw,noexec,nosuid,nodev,size=16m"] + environment: *sync_environment + volumes: *sync_secrets + networks: [egress, observability] + pids_limit: 128 + mem_limit: 256m + cpus: 0.75 + restart: unless-stopped + + bitrix-sync-reconciliation: + image: han-bitrix-sync:${BITRIX_SYNC_IMAGE_TAG:-local} + command: ["han-bitrix-sync-reconciliation"] + user: "10001:10001" + read_only: true + security_opt: ["no-new-privileges:true"] + cap_drop: ["ALL"] + tmpfs: ["/tmp:rw,noexec,nosuid,nodev,size=16m"] + environment: *sync_environment + volumes: *sync_secrets + networks: [egress, observability] + pids_limit: 128 + mem_limit: 192m + cpus: 0.50 + restart: "no" + +networks: + backend: + external: true + egress: + external: true + observability: + external: true diff --git a/codebase/services/bitrix-sync/openapi.yaml b/codebase/services/bitrix-sync/openapi.yaml new file mode 100644 index 0000000..de18130 --- /dev/null +++ b/codebase/services/bitrix-sync/openapi.yaml @@ -0,0 +1,121 @@ +openapi: 3.1.0 +info: + title: HAN Bitrix Sync + version: 0.1.0 +paths: + /health/live: + get: + operationId: healthLive + responses: + "200": + description: Process is alive + /health/ready: + get: + operationId: healthReady + responses: + "200": + description: Full-mode configuration and database are ready + "503": + description: Disabled or a core dependency is not ready + /internal/sync/v1/status: + get: + operationId: syncStatus + security: + - bearerAuth: [] + responses: + "200": + description: Low-cardinality operational status without PII + "401": + description: Missing or invalid service token + /bitrix/sync/webhook/contact: + post: + operationId: receiveContactRobot + parameters: + - $ref: "#/components/parameters/ReceiverToken" + - $ref: "#/components/parameters/EntityId" + requestBody: + required: true + content: + application/x-www-form-urlencoded: + schema: + $ref: "#/components/schemas/RobotForm" + responses: + "202": + description: Event durably stored + "400": + description: Malformed robot contract + "403": + description: Receiver authentication rejected + "413": + description: Body too large + "503": + description: Sync is disabled + /bitrix/sync/webhook/alert: + post: + operationId: receiveAlertRobot + parameters: + - $ref: "#/components/parameters/ReceiverToken" + - $ref: "#/components/parameters/EntityId" + requestBody: + required: true + content: + application/x-www-form-urlencoded: + schema: + $ref: "#/components/schemas/RobotForm" + responses: + "202": + description: Event durably stored + "400": + description: Malformed robot contract + "403": + description: Receiver authentication rejected + "413": + description: Body too large + "503": + description: Sync is disabled +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + parameters: + ReceiverToken: + name: token + in: query + required: true + schema: + type: string + maxLength: 256 + description: Secret receiver token; MUST be excluded from logs and traces. + EntityId: + name: ID + in: query + required: true + schema: + type: string + pattern: "^[1-9][0-9]{0,19}$" + schemas: + RobotForm: + type: object + additionalProperties: false + required: + - document_id[0] + - document_id[1] + - document_id[2] + - auth[domain] + - auth[member_id] + properties: + document_id[0]: + type: string + document_id[1]: + type: string + document_id[2]: + type: string + auth[domain]: + type: string + auth[member_id]: + type: string + auth[client_endpoint]: + type: string + auth[server_endpoint]: + type: string diff --git a/codebase/services/bitrix-sync/pyproject.toml b/codebase/services/bitrix-sync/pyproject.toml new file mode 100644 index 0000000..ccc7171 --- /dev/null +++ b/codebase/services/bitrix-sync/pyproject.toml @@ -0,0 +1,50 @@ +[project] +name = "han-bitrix-sync" +version = "0.1.0" +description = "Durable HAN App to Bitrix24 Contact synchronization" +requires-python = ">=3.12" +dependencies = [ + "alembic>=1.16,<2", + "asyncpg>=0.30,<1", + "fastapi>=0.116,<1", + "httpx>=0.28,<1", + "pydantic-settings>=2.10,<3", + "python-multipart>=0.0.20,<1", + "sqlalchemy[asyncio]>=2.0.41,<3", + "structlog>=25,<26", + "uvicorn[standard]>=0.35,<1", +] + +[project.optional-dependencies] +dev = [ + "pytest>=8.4,<9", + "pytest-asyncio>=1.0,<2", + "ruff>=0.12,<1", +] + +[project.scripts] +han-bitrix-sync-api = "app.main:run" +han-bitrix-sync-worker = "app.worker:run" +han-bitrix-sync-reconciliation = "app.reconciliation:run" + +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + +[tool.hatch.build.targets.wheel] +packages = ["app"] + +[tool.pytest.ini_options] +asyncio_mode = "auto" +testpaths = ["tests"] + +[tool.ruff] +target-version = "py312" +line-length = 100 + +[tool.ruff.lint] +select = ["E", "F", "I", "UP", "B", "ASYNC", "S"] +ignore = ["S101"] + +[tool.ruff.lint.per-file-ignores] +"tests/**" = ["S106", "S311"] diff --git a/codebase/services/bitrix-sync/tests/conftest.py b/codebase/services/bitrix-sync/tests/conftest.py new file mode 100644 index 0000000..55ef3da --- /dev/null +++ b/codebase/services/bitrix-sync/tests/conftest.py @@ -0,0 +1,25 @@ +from __future__ import annotations + +import pytest + +from app.config import Settings + + +@pytest.fixture +def full_settings() -> Settings: + return Settings( + enabled=True, + mode="full", + database_url="postgresql+asyncpg://user:pass@db/han", + crm_rest_webhook_url="https://portal.example/rest/1/credential/", + contact_receiver_token="contact-token-value-32-characters", + alert_receiver_token="alert-token-value-32-characters---", + service_token="service-token-value-32-characters-", + portal_host="portal.example", + portal_member_id="member_12345678", + public_base_url="https://sync.example", + contact_user_id_field="UF_CRM_100", + contact_registered_field="UF_CRM_101", + contact_citizenship_field="UF_CRM_102", + webhook_allowed_cidrs="203.0.113.0/24", + ) diff --git a/codebase/services/bitrix-sync/tests/test_config.py b/codebase/services/bitrix-sync/tests/test_config.py new file mode 100644 index 0000000..6ef7f91 --- /dev/null +++ b/codebase/services/bitrix-sync/tests/test_config.py @@ -0,0 +1,77 @@ +from __future__ import annotations + +import ast +import re +from pathlib import Path + +import pytest +from pydantic import ValidationError + +from app.config import Settings + + +def test_disabled_mode_needs_no_secrets() -> None: + settings = Settings(enabled=False, mode="disabled") + assert settings.enabled is False + + +def test_full_mode_rejects_portal_host_mismatch() -> None: + with pytest.raises(ValidationError, match="approved portal host"): + Settings( + enabled=True, + mode="full", + database_url="postgresql+asyncpg://u:p@db/han", + crm_rest_webhook_url="https://evil.example/rest/1/token/", + contact_receiver_token="contact", + alert_receiver_token="alert", + service_token="service", + portal_host="portal.example", + portal_member_id="member_12345678", + public_base_url="https://sync.example", + contact_user_id_field="UF_CRM_1", + contact_registered_field="UF_CRM_2", + contact_citizenship_field="UF_CRM_3", + webhook_allowed_cidrs="203.0.113.0/24", + ) + + +def test_rest_field_conversion_is_deterministic() -> None: + assert Settings.rest_field_name("UF_CRM_1778692456") == "ufCrm_1778692456" + with pytest.raises(ValueError): + Settings.rest_field_name("uf_crm_1") + + +def test_alembic_chain_preserves_legacy_baseline() -> None: + versions = Path(__file__).parents[1] / "alembic" / "versions" + revisions: dict[str, str | None] = {} + + for migration in versions.glob("*.py"): + assignments = { + node.target.id: node.value.value + for node in ast.parse(migration.read_text(encoding="utf-8")).body + if isinstance(node, ast.AnnAssign) + and isinstance(node.target, ast.Name) + and node.target.id in {"revision", "down_revision"} + and isinstance(node.value, ast.Constant) + } + revisions[assignments["revision"]] = assignments["down_revision"] + + assert revisions == { + "0001_sync_baseline": None, + "0001_bitrix_sync_full": "0001_sync_baseline", + "0002_app_queue_contract": "0001_bitrix_sync_full", + } + + +def test_app_queue_migration_does_not_revoke_foreign_schema_privileges() -> None: + migration = ( + Path(__file__).parents[1] + / "alembic" + / "versions" + / "0002_app_queue_contract.py" + ) + source = migration.read_text(encoding="utf-8") + + assert "FROM han_app.entity_external_mapping" in source + assert "REVOKE" not in source + assert re.search(r'"[^"]+"\s*:', source) is None diff --git a/codebase/services/bitrix-sync/tests/test_crm.py b/codebase/services/bitrix-sync/tests/test_crm.py new file mode 100644 index 0000000..9a12c3e --- /dev/null +++ b/codebase/services/bitrix-sync/tests/test_crm.py @@ -0,0 +1,48 @@ +from __future__ import annotations + +import httpx +import pytest + +from app.crm import CrmClient, CrmOutcome + + +def make_client(handler) -> CrmClient: + client = CrmClient.__new__(CrmClient) + client._base_url = "https://portal.example/rest/1/token/" + client._host = "portal.example" + client._client = httpx.AsyncClient( + transport=httpx.MockTransport(handler), follow_redirects=False + ) + return client + + +@pytest.mark.asyncio +async def test_crm_success_and_no_redirect() -> None: + client = make_client( + lambda request: httpx.Response(200, json={"result": {"ID": "42"}}, request=request) + ) + result = await client.call("crm.contact.get", {"id": "42"}, mutating=False) + assert result.outcome == CrmOutcome.SUCCEEDED + assert result.result["ID"] == "42" + await client.close() + + redirecting = make_client( + lambda request: httpx.Response( + 302, headers={"Location": "https://evil.example/"}, request=request + ) + ) + result = await redirecting.call("crm.contact.get", {"id": "42"}, mutating=False) + assert result.outcome == CrmOutcome.PERMANENT + assert result.error_code == "crm_redirect_rejected" + await redirecting.close() + + +@pytest.mark.asyncio +async def test_mutating_timeout_is_uncertain() -> None: + def timeout(request): + raise httpx.ReadTimeout("timed out", request=request) + + client = make_client(timeout) + result = await client.call("crm.contact.add", {"fields": {}}, mutating=True) + assert result.outcome == CrmOutcome.UNCERTAIN + await client.close() diff --git a/codebase/services/bitrix-sync/tests/test_domain.py b/codebase/services/bitrix-sync/tests/test_domain.py new file mode 100644 index 0000000..005eff6 --- /dev/null +++ b/codebase/services/bitrix-sync/tests/test_domain.py @@ -0,0 +1,57 @@ +from __future__ import annotations + +import random +from datetime import UTC, datetime, timedelta + +import pytest + +from app.domain import ( + ContactCandidate, + WorkflowState, + assert_transition, + choose_newest, + full_jitter_delay, + select_email, + validate_phone, +) +from app.mapping import CitizenshipDictionary, UnknownCitizenship + + +def test_contact_choice_has_numeric_id_tie_breaker() -> None: + created = datetime(2026, 8, 6, tzinfo=UTC) + selected = choose_newest( + [ + ContactCandidate("9", created, None), + ContactCandidate("10", created, None), + ] + ) + assert selected and selected.b24_id == "10" + + +def test_phone_email_and_citizenship_mapping() -> None: + assert validate_phone("+79001234567") == "+79001234567" + with pytest.raises(ValueError): + validate_phone("8 900 123-45-67") + assert ( + select_email( + [ + {"VALUE": "home@example.test", "VALUE_TYPE": "HOME"}, + {"VALUE": "work@example.test", "VALUE_TYPE": "WORK"}, + ] + ) + == "work@example.test" + ) + dictionary = CitizenshipDictionary(ttl_seconds=60) + now = datetime(2026, 8, 6, tzinfo=UTC) + dictionary.load([{"ID": "7", "VALUE": "Казахстан"}], now) + assert dictionary.resolve("7", now + timedelta(seconds=30)) == "Казахстан" + with pytest.raises(UnknownCitizenship): + dictionary.resolve("8", now) + + +def test_state_machine_and_retry_bounds() -> None: + assert_transition(WorkflowState.CREATED, WorkflowState.RUNNING) + with pytest.raises(ValueError): + assert_transition(WorkflowState.SUCCEEDED, WorkflowState.RUNNING) + delay = full_jitter_delay(4, 1, 5, rng=random.Random(1)) + assert 0 <= delay <= 5 diff --git a/codebase/services/bitrix-sync/tests/test_engine_boundaries.py b/codebase/services/bitrix-sync/tests/test_engine_boundaries.py new file mode 100644 index 0000000..845cf1f --- /dev/null +++ b/codebase/services/bitrix-sync/tests/test_engine_boundaries.py @@ -0,0 +1,72 @@ +from __future__ import annotations + +import uuid +from contextlib import asynccontextmanager + +import pytest + +from app.crm import CrmOutcome, CrmResult +from app.engine import WorkflowEngine +from app.repository import Profile + + +class Result: + rowcount = 1 + + +class Connection: + async def execute(self, statement, params=None): + return Result() + + +class FakeRepository: + def __init__(self) -> None: + self.mapping = None + self.statements: list[str] = [] + + @asynccontextmanager + async def transaction(self): + yield Connection() + + async def active_mapping(self, user_id): + return self.mapping + + async def reserve_limiter_token(self, refill_per_second, burst): + return 0 + + +class FakeCrm: + def __init__(self, user_id: uuid.UUID) -> None: + self.user_id = user_id + self.calls: list[tuple[str, dict]] = [] + + async def call(self, method, params, *, mutating): + self.calls.append((method, params)) + if method == "crm.duplicate.findbycomm": + return CrmResult(CrmOutcome.SUCCEEDED, {"CONTACT": ["9", "10"]}) + if method == "crm.contact.get": + contact_id = str(params["id"]) + return CrmResult( + CrmOutcome.SUCCEEDED, + { + "ID": contact_id, + "CREATED_TIME": "2026-08-06T10:00:00Z", + "UF_CRM_100": None, + }, + ) + return CrmResult(CrmOutcome.SUCCEEDED, True) + + +@pytest.mark.asyncio +async def test_multiple_contacts_choose_numeric_newest(full_settings) -> None: + user_id = uuid.uuid4() + repository = FakeRepository() + crm = FakeCrm(user_id) + engine = WorkflowEngine(repository, crm, full_settings) + await engine._map_or_create( + uuid.uuid4(), + Profile(user_id=user_id, phone="+79001234567", identity_status="A", profile_status="A"), + ) + updates = [params for method, params in crm.calls if method == "crm.contact.update"] + assert updates[0]["id"] == "10" + assert not any(method == "crm.contact.add" for method, _ in crm.calls) diff --git a/codebase/services/bitrix-sync/tests/test_webhook_security.py b/codebase/services/bitrix-sync/tests/test_webhook_security.py new file mode 100644 index 0000000..f0e27f6 --- /dev/null +++ b/codebase/services/bitrix-sync/tests/test_webhook_security.py @@ -0,0 +1,62 @@ +from __future__ import annotations + +import pytest + +from app.security import ( + WebhookValidationError, + parse_bounded_form, + redact, + token_matches, + validate_webhook, +) + + +def test_contact_webhook_contract(full_settings) -> None: + event = validate_webhook( + "contact", + {"token": "contact-token-value-32-characters", "ID": "42"}, + { + "document_id[0]": "crm", + "document_id[1]": "CCrmDocumentContact", + "document_id[2]": "CONTACT_42", + "auth[domain]": "portal.example", + "auth[member_id]": "member_12345678", + "auth[client_endpoint]": "https://attacker.invalid/rest/", + }, + "203.0.113.10", + full_settings, + alert_entity_type_id=None, + ) + assert event.entity_id == "42" + + +def test_webhook_rejects_document_query_mismatch(full_settings) -> None: + with pytest.raises(WebhookValidationError, match="mismatch"): + validate_webhook( + "contact", + {"token": "contact-token-value-32-characters", "ID": "41"}, + { + "document_id[0]": "crm", + "document_id[1]": "CCrmDocumentContact", + "document_id[2]": "CONTACT_42", + "auth[domain]": "portal.example", + "auth[member_id]": "member_12345678", + }, + "203.0.113.10", + full_settings, + alert_entity_type_id=None, + ) + + +def test_bounded_form_and_constant_time_token_helpers() -> None: + assert parse_bounded_form(b"a=1&b=2", max_fields=2) == {"a": "1", "b": "2"} + with pytest.raises(WebhookValidationError): + parse_bounded_form(b"a=1&b=2&c=3", max_fields=2) + assert token_matches("old", "new", "old") + assert not token_matches("other", "new", "old") + + +def test_redaction_removes_pii_and_secrets() -> None: + assert "secret-value" not in redact("token=secret-value") + assert redact("user@example.test") == "[PII_REDACTED]" + assert redact("+79001234567") == "[PII_REDACTED]" diff --git a/codebase/services/deployment/RUNBOOK.md b/codebase/services/deployment/RUNBOOK.md new file mode 100644 index 0000000..8792cbd --- /dev/null +++ b/codebase/services/deployment/RUNBOOK.md @@ -0,0 +1,130 @@ +# VM2 Processing deployment runbook + +This directory is the independent VM2 foundation. It does not deploy VM1 or +`codebase/backend`. All commands below are operator commands; repository +creation does not execute them. + +## Production blockers before first start + +1. Replace every `.env` placeholder with reviewed non-secret values. Keep + `BITRIX_SYNC_ENABLED=false` until migrations, grants, portal fields, robot + contracts and cutover are signed off. +2. Fill every `*_IMAGE` variable with a reviewed registry digest. Root Compose + rejects missing image references; mutable tags are not production evidence. +3. Install production files as `root:root`; `deploy` must not be in `docker` + and must not be able to write Compose, units, helpers, allow-lists or secret + mappings. +4. Populate separate reviewed active CIDR files from the two `.template` + files. Their committed active versions are intentionally `deny all`. +5. Provision public ACME material under host `/etc/letsencrypt` and the managed + PostgreSQL CA under `/etc/han/ca`. Provision an internal-CA certificate whose + SAN matches the private VM2 name. Permit host port `8443` only from VM1 SG + and, when needed, approved private/VPN ops CIDRs. +6. Create a dedicated VM2 Selectel IAM principal. It may read only names in + `deployment/secrets/config.example.json`. Never reuse the VM1 principal. +7. `REDIS_SAFETY_ACL` is the complete ACL file, not merely a password. It must + expose unauthenticated `PING` only for health and a password-protected + `safety` user limited to required `han:safety:*` keys/commands. The password + in `MESSAGE_SAFETY_REDIS_URL` must match. Start from + `redis/redis-safety.acl.template`, replace + `REPLACE_WITH_LONG_RANDOM_PASSWORD`, and never commit the password. +8. Provision distinct runtime and migration DB credentials. + `MESSAGE_SAFETY_CONFIG_ADMIN_DATABASE_URL` may migrate/activate policy while + `MESSAGE_SAFETY_DATABASE_URL` cannot; `BITRIX_SYNC_MIGRATION_DATABASE_URL` + owns DDL while `BITRIX_SYNC_DATABASE_URL` is the least-privilege runtime + role. Migration credentials are mounted only into the `ops` profile jobs. +9. The setup script leaves UFW egress open for bootstrap. Before production, + constrain egress through Selectel SG/NAT/proxy to the approved PostgreSQL, + S3, Secrets Manager, Bitrix24, DNS/NTP, SigNoz and ClamAV destinations. + Registry/package access exists only during controlled maintenance windows. + +## Install + +- Bootstrap a fresh Ubuntu 24.04 VM as root with + `deployment/scripts/setup-vm.sh`, supplying `VM1_PRIVATE_CIDRS`, optional + private/VPN `OPS_CIDRS`, and separate Ed25519 public-key files for deploy and + break-glass admin. SSH is publicly reachable but key-only and protected by + fail2ban; the CIDR variables apply only to private port `8443`. The script + installs host packages/firewalls and roles but never starts Compose. Set a + separate admin sudo password; verify deploy login, admin login and admin sudo + in independent sessions before rerunning with `HARDEN_SSH=true`. + Root/deploy/admin key reuse is rejected. +- Checkout an immutable release under `/opt/han-chat/services`. +- Copy `.env.example` to root-owned mode `0600` `.env`. +- Install `secrets_loader.py` and `han-secrets` under + `/usr/local/lib/han-secrets-vm2/`, root-owned and non-writable. +- Install `han-compose` as `/usr/local/sbin/han-vm2-compose`. +- Install `han-secrets-vm2.service` and `han-processing.service` under + `/etc/systemd/system/`. +- Install `han-message-safety-mode` as root-owned `0755` and the sudoers + template as `/etc/sudoers.d/deploy-message-safety-mode` mode `0440`; validate + with `visudo -cf`. Create the dedicated host group `han-message-safety` with + GID `10001`. Before the first Compose validation, create + `/etc/han-chat/message-safety-mode.env` as + `root:han-message-safety 0640` with all three flags `false` (or invoke the + helper's `standard` transition after the fixed launcher is installed). +- Install loader config using the exact `APP_ENV` suffix. With the committed + example (`APP_ENV=production-like`) the path is + `/etc/han/secrets/vm2-production-like.selectel.json` mode `0600`. For + controlled no-provider recovery use an explicit `file` + config pointing to a root-only `0700` directory containing exactly one file + per configured key. Selectel failure never falls back automatically. + +## Preflight and startup + +Run `deployment/preflight.sh` first. Then, through the approved root units: + +1. synchronize secrets; any missing/oversized/invalid secret blocks startup; +2. validate resolved Compose without storing its output; +3. run the two `ops` migration jobs and create/activate the reviewed initial + Message Safety config before starting either runtime; +4. validate nginx config and both certificate chains; +5. start Redis/Collector, ClamAV, application API/workers, then nginx; +6. verify that only nginx publishes `80`, `443`, and private-bound `8443`; +7. verify all non-exact public paths return `404`, HTTP webhook paths return + `426` without redirect/query reflection, wrong methods fail, and wrong + source CIDRs are rejected before upstream; +8. verify private Safety check/task/status and sync status only from approved + callers; verify public `/internal/*` is `404`; +9. canary telemetry with a fake token marker and prove query, form body, + Authorization, DSN, S3 key and object key are absent from logs/traces. + +Do not open webhook traffic while `bitrix-sync` is disabled. A disabled or +failed receiver must return retryable `503`/closed routing, never successful +`2xx ignored`. + +## Failure policy + +- Safety dependency failure is fail-closed: VM1 must not send/promote content. +- Stale/unavailable ClamAV signatures disable file capability only; they never + convert a scan error to allow. +- Redis loss may remove acceleration but PostgreSQL remains authoritative. +- OTEL outage queues within the bounded volume and must not change verdicts. +- Rollback does not downgrade schemas, delete durable tasks/mappings, or run + `docker compose down -v`. + +## Emergency MOCK + +Only these five sudo commands are allowed: + +```text +han-message-safety-mode standard +han-message-safety-mode mock --text-free true --file-free true +han-message-safety-mode mock --text-free true --file-free false +han-message-safety-mode mock --text-free false --file-free true +han-message-safety-mode mock --text-free false --file-free false +``` + +The helper atomically writes only +`/etc/han-chat/message-safety-mode.env`, recreates only the Safety API, checks +health, and restores the previous mode on failure. MOCK has no timeout: keep a +high-severity alert active until explicit `standard`, then verify normal +text/link/file capabilities and an EICAR canary. + +## Known image exceptions + +ClamAV images may require UID/path adjustments after validating the exact +digest. Do not weaken `read_only`, capabilities or mounts globally: document +the smallest writable signature/runtime paths and compensate with network and +resource limits. `freshclam` alone receives signature-CDN egress; `clamd` +receives none. diff --git a/codebase/services/deployment/RUNBOOK.ru.md b/codebase/services/deployment/RUNBOOK.ru.md new file mode 100644 index 0000000..8a21b77 --- /dev/null +++ b/codebase/services/deployment/RUNBOOK.ru.md @@ -0,0 +1,821 @@ +# Ранбук развёртывания Processing на VM2 + +Этот каталог — независимая основа VM2. Он не разворачивает VM1 и не +затрагивает `codebase/backend`. Все команды ниже — операторские; создание +репозитория их не выполняет. + +## Блокеры production перед первым запуском + +1. Замените каждый плейсхолдер в `.env` на проверенные несекретные значения. + Держите `BITRIX_SYNC_ENABLED=false`, пока не подписаны миграции, гранты, + поля портала, контракты роботов и cutover. + (для этого нужно еще образы отправить в conteiner registry, пункт 2) +2. Заполните каждую переменную `*_IMAGE` проверенным digest из registry. + Корневой Compose отклоняет отсутствующие ссылки на образы; изменяемые + теги не являются доказательством для production. +3. Устанавливайте production-файлы от `root:root`; пользователь `deploy` не + должен входить в группу `docker` и не должен иметь возможность писать + Compose, unit-файлы, хелперы, allow-list’ы или маппинги секретов. + (смысл: заходим под админом, sudo -i) +4. Заполните отдельные проверенные активные CIDR-файлы из двух `.template`. + Их закоммиченные активные версии намеренно содержат `deny all`. + (в services/nginx/allowlist прописываем разрешенные адреса - адрес ВМ1 и адрес битрикса) +5. Выпустите публичный ACME-сертификат в host-каталог `/etc/letsencrypt`. + Разместите CA управляемой PostgreSQL в `/etc/han/ca`. Выпустите + сертификат внутренней CA, SAN которого совпадает с приватным именем VM2. + Разрешайте хостовый порт `8443` только из SG VM1 и, при необходимости, + одобренных приватных/VPN-сетей операторов. + (выпуск сертификатов) +6. Создайте отдельный IAM-принципал Selectel для VM2. Он может читать только + имена из `deployment/secrets/config.example.json`. Никогда не + переиспользуйте принципал VM1. + (отдельный проект в селектел, туда отдельного сервисного пользователя с ролью member) +7. `REDIS_SAFETY_ACL` — полный ACL-файл, а не просто пароль. Он должен + открывать неаутентифицированный `PING` только для health и + защищённого паролем пользователя `safety`, ограниченного необходимыми + ключами/командами `han:safety:*`. + (Пароль в `MESSAGE_SAFETY_REDIS_URL` должен совпадать. Используйте `redis/redis-safety.acl.template`, заменив `REPLACE_WITH_LONG_RANDOM_PASSWORD) +8. Выделите отдельные учётные данные БД для runtime и миграций. + `MESSAGE_SAFETY_CONFIG_ADMIN_DATABASE_URL` может мигрировать/активировать + политику, а `MESSAGE_SAFETY_DATABASE_URL` — нет; `BITRIX_SYNC_MIGRATION_DATABASE_URL` + владеет DDL, а `BITRIX_SYNC_DATABASE_URL` — runtime-роль с минимальными + привилегиями. Учётные данные миграций монтируются только в jobs профиля + `ops`. +9. Setup оставляет исходящий трафик UFW открытым на bootstrap-окно. До + production ограничьте egress правилами Selectel SG/NAT/proxy до + утверждённых PostgreSQL, S3, Secrets Manager, Bitrix24, DNS/NTP, SigNoz и + источников ClamAV. Registry/package repositories оставляйте только на + controlled maintenance window. + +## Кто что выполняет + +- **Локальный компьютер оператора:** создаёт архив релиза и передаёт его на + VM2. Локальные команды ниже показаны для PowerShell. +- **`root` на VM2:** только bootstrap host OS, активация проверенного релиза, + установка root-owned файлов, настройка `.env`, secret mapping, credentials, + TLS/allow-list, миграции и первый старт. +- **`deploy` на VM2:** принимает релиз только в + `/var/lib/han-deploy/incoming`, проверяет статус/логи и запускает уже + установленные fixed systemd operations через точные sudo-правила. + `deploy` не запускает `docker`, не редактирует `/opt/han-chat/services` и не + входит в группу `docker`. +- **`admin` на VM2:** персональная break-glass роль с отдельным SSH-ключом и + отдельным локальным паролем для `sudo`. Не используется для штатного деплоя, + не входит в `docker`/`lxd`; каждый вход и sudo-вызов считается инцидентной + операцией. + +## 1. Bootstrap свежей VM2 + +На локальном компьютере один раз создайте **два разных** ключа. Закрытые части +остаются только у соответствующих операторов и никогда не передаются на VM: + +```powershell +ssh-keygen -t ed25519 -a 100 -f C:\Users\MI\.ssh\han_vm2_deploy ` + -C "han-vm2-deploy" +ssh-keygen -t ed25519 -a 100 -f C:\Users\MI\.ssh\han_vm2_admin ` + -C "han-vm2-break-glass-admin" +``` + +Для production ключ `admin` должен принадлежать отдельному назначенному +break-glass оператору и храниться отдельно от deploy key. Если команды +выполняет один человек на этапе bootstrap, это всё равно две разные key pairs +с раздельной последующей передачей/ротацией. + +Скопируйте setup-скрипт и только публичные части ключей во временный root +каталог: + +```powershell +scp -i C:\Users\MI\.ssh\hansel ` + .\HAN_chat_specification\codebase\services\deployment\scripts\setup-vm.sh ` + root@:/root/setup-vm2.sh +scp -i C:\Users\MI\.ssh\hansel ` + C:\Users\MI\.ssh\han_vm2_deploy.pub ` + C:\Users\MI\.ssh\han_vm2_admin.pub ` + root@:/root/ +``` + +На VM2 в текущей root-сессии задайте приватный CIDR VM1. `/0` скрипт отклоняет: + +```sh +install -d -m 0700 -o root -g root /root/bootstrap +install -m 0600 -o root -g root /root/han_vm2_deploy.pub /root/bootstrap/deploy.pub +install -m 0600 -o root -g root /root/han_vm2_admin.pub /root/bootstrap/admin.pub +chmod 0700 /root/setup-vm2.sh +DEPLOY_AUTHORIZED_KEY_FILE=/root/bootstrap/deploy.pub \ +ADMIN_AUTHORIZED_KEY_FILE=/root/bootstrap/admin.pub \ +VM1_PRIVATE_CIDRS='/32' \ +/root/setup-vm2.sh +``` + +Скрипт устанавливает Ubuntu-пакеты, Docker Engine + Compose plugin, UFW, +fail2ban, unattended upgrades, swap, sysctl и цепочку `DOCKER-USER`; создаёт +`deploy`, break-glass `admin`, staging и root-owned production-каталог. Скрипт +не запускает Compose/контейнеры. `80/443` и SSH открываются публично; SSH +остаётся key-only и защищён fail2ban. `8443` доступен только на приватном IP +VM2 из `VM1_PRIVATE_CIDRS`. Если оператору нужен прямой доступ к внутреннему +API через приватный маршрут или VPN, дополнительно передайте необязательный +`OPS_CIDRS=''`. + +В текущей root-сессии задайте `admin` отдельный сложный sudo-пароль. Он не +разрешает password SSH: пароль нужен только после входа по admin key: + +```sh +passwd admin +``` + +Не закрывая root-сессию, на локальном компьютере проверьте оба входа: + +```powershell +ssh -i C:\Users\MI\.ssh\han_vm2_deploy deploy@ +ssh -i C:\Users\MI\.ssh\han_vm2_admin admin@ +``` + +В admin-сессии проверьте запрос именно admin-пароля и получение root shell, +после чего сразу выйдите из него: + +```sh +sudo -v +sudo -i +id +exit +``` + +Только после успешной проверки `deploy`, `admin` и `sudo` повторите на VM2 +под `root`: + +```sh +DEPLOY_AUTHORIZED_KEY_FILE=/root/bootstrap/deploy.pub \ +ADMIN_AUTHORIZED_KEY_FILE=/root/bootstrap/admin.pub \ +VM1_PRIVATE_CIDRS='/32' \ +HARDEN_SSH=true \ +SKIP_APT_UPGRADE=true \ +/root/setup-vm2.sh +``` + +Это добавит `PermitRootLogin no` и `AllowUsers deploy admin`. Ещё раз откройте +обе новые SSH-сессии после reload и только затем закрывайте старую root. +Публичные bootstrap-копии после проверки можно удалить под `admin`: + +```sh +sudo rm -f /root/han_vm2_deploy.pub /root/han_vm2_admin.pub +``` + +## 2. Передача релиза под `deploy` + +На локальном компьютере из каталога `HAN_chat_specification`: + +```powershell +$Release = "" +tar --exclude=services/.env ` + --exclude='services/**/__pycache__' ` + --exclude='services/**/.pytest_cache' ` + --exclude='services/**/.ruff_cache' ` + -czf "vm2-services-$Release.tar.gz" -C .\codebase services +Get-FileHash "vm2-services-$Release.tar.gz" -Algorithm SHA256 +scp -i C:\Users\MI\.ssh\hansel "vm2-services-$Release.tar.gz" ` + deploy@:/var/lib/han-deploy/incoming/ +``` + +Под `deploy` на VM2 вычислите checksum. Значение должно совпасть с локальным: + +```sh +RELEASE='' +cd /var/lib/han-deploy/incoming +sha256sum "vm2-services-${RELEASE}.tar.gz" +tar -tzf "vm2-services-${RELEASE}.tar.gz" +``` + +На этом действия `deploy` с файлами заканчиваются. Не распаковывайте релиз +через `sudo` и не копируйте его в production от имени `deploy`. + +## 3. Активация и установка файлов под `root` + +Под `root` ещё раз сверьте ожидаемый SHA-256 и список архива. Не продолжайте, +если архив содержит абсолютные пути, `..`, symlink/hardlink или лишний проект: + +```sh +RELEASE='' +EXPECTED_SHA256='' +ARCHIVE="/var/lib/han-deploy/incoming/vm2-services-${RELEASE}.tar.gz" +printf '%s %s\n' "$EXPECTED_SHA256" "$ARCHIVE" | sha256sum --check - +tar -tvzf "$ARCHIVE" +if tar -tzf "$ARCHIVE" | grep -Eq '(^/|(^|/)\.\.(/|$)|^services/\.env$)'; then + echo 'ОШИБКА: архив содержит небезопасный путь или .env' >&2 + exit 1 +fi +if tar -tzf "$ARCHIVE" | grep -Ev '^services(/|$)' | grep -q .; then + echo 'ОШИБКА: архив содержит файлы вне каталога services' >&2 + exit 1 +fi +if tar -tvzf "$ARCHIVE" | awk '$1 ~ /^[lh]/ { found=1 } END { exit !found }'; then + echo 'ОШИБКА: архив содержит symlink или hardlink' >&2 + exit 1 +fi +install -d -m 0755 -o root -g root /opt/han-chat/services +STAGING="$(mktemp -d /opt/han-chat/.vm2-release.XXXXXX)" +tar --extract --gzip --file "$ARCHIVE" \ + --directory "$STAGING" --no-same-owner --no-same-permissions +test -f "$STAGING/services/docker-compose.yml" +rsync -a --delete --exclude=.env \ + --chown=root:root --chmod=D755,F644 \ + "$STAGING/services/" /opt/han-chat/services/ +rm -rf -- "$STAGING" +chmod 0755 /opt/han-chat/services/deployment/preflight.sh +``` + +Повторите setup под `root`: теперь он установит helpers и units из активного +релиза. Приложение всё ещё не запускается: + +```sh +DEPLOY_AUTHORIZED_KEY_FILE=/root/bootstrap/deploy.pub \ +ADMIN_AUTHORIZED_KEY_FILE=/root/bootstrap/admin.pub \ +VM1_PRIVATE_CIDRS='/32' \ +HARDEN_SSH=true \ +SKIP_APT_UPGRADE=true \ +/root/setup-vm2.sh +``` + +Скрипт устанавливает: + +- `/usr/local/lib/han-secrets-vm2/{secrets_loader.py,han-secrets}`; +- `/usr/local/sbin/han-vm2-compose`; +- `/usr/local/sbin/han-message-safety-mode`; +- `/etc/letsencrypt/renewal-hooks/deploy/han-processing-nginx`; +- `/etc/systemd/system/{han-secrets-vm2,han-processing}.service`; +- `/etc/sudoers.d/{han-vm2-deploy,deploy-message-safety-mode}`; +- группу `han-message-safety` с GID `10001`; +- стандартный `/etc/han-chat/message-safety-mode.env` с правами + `root:han-message-safety 0640`. + +## 4. Несекретная конфигурация и Selectel под `root` + +`APP_ENV` определяет имя loader config. При значении из `.env.example` +`APP_ENV=production-like` файл обязан называться +`/etc/han/secrets/vm2-production-like.selectel.json`: + +```sh +cd /opt/han-chat/services +install -m 0600 -o root -g root .env.example .env +editor .env + +install -m 0600 -o root -g root \ + deployment/secrets/config.example.json \ + /etc/han/secrets/vm2-production-like.selectel.json +editor /etc/han/secrets/vm2-production-like.selectel.json +``` + +В `.env` заменяются только несекретные плейсхолдеры и image digests. Значения +DSN, token, password, access/secret key туда не записываются. Для Selectel +создайте отдельный VM2 IAM principal с read-only доступом только к remote names +из mapping. + +Зашифруйте пароль Selectel service user через systemd credentials, не помещая +его в аргументы или history: + +```sh +read -rsp 'Selectel VM2 service-user password: ' SELECTEL_PASSWORD; echo +printf '%s' "$SELECTEL_PASSWORD" | systemd-creds encrypt \ + --name=selectel-service-user-password - \ + /etc/han/credentials/vm2.selectel-password.cred +unset SELECTEL_PASSWORD +chown root:root /etc/han/credentials/vm2.selectel-password.cred +chmod 0600 /etc/han/credentials/vm2.selectel-password.cred +``` + +Активные nginx allow-list файлы редактирует только `root`; последней строкой +обязательно остаётся `deny all;`. До cutover Bitrix public allow-list должен +оставаться закрытым: + +```sh +editor /opt/han-chat/services/nginx/allowlists/private-caller-allowlist.conf +editor /opt/han-chat/services/nginx/allowlists/bitrix-webhook-allowlist.conf +chown root:root /opt/han-chat/services/nginx/allowlists/*.conf +chmod 0644 /opt/han-chat/services/nginx/allowlists/*.conf +``` + +Для контролируемого восстановления без провайдера используйте явный `file` +config и root-only каталог `0700` с одним файлом на ключ. При сбое Selectel +автоматический fallback запрещён. + +## 5. Сертификат PostgreSQL и первоначальный выпуск public TLS + +### CA управляемой PostgreSQL + +Скачайте CA-сертификат кластера из панели провайдера и передайте его на VM2 во +временный путь. Под `root` установите сертификат вне каталога релиза: + +```sh +install -d -m 0755 -o root -g root /etc/han/ca +install -m 0644 -o root -g root \ + /tmp/ \ + /etc/han/ca/managed-postgresql-ca.pem +openssl x509 -in /etc/han/ca/managed-postgresql-ca.pem \ + -noout -subject -issuer -dates +rm -f /tmp/ +``` + +В `.env` должно быть: + +```dotenv +PG_CA_HOST_PATH=/etc/han/ca/managed-postgresql-ca.pem +``` + +Compose монтирует этот файл read-only во все runtime и migration контейнеры как +`/run/config/postgresql-ca.pem`. DB-клиенты создают обязательный TLS context с +проверкой цепочки и имени сервера по этому CA. Не добавляйте libpq-параметры +`sslmode`/`sslrootcert` в SQLAlchemy `postgresql+asyncpg` URL: asyncpg получает +SSL context отдельно, а такие query-параметры могут быть переданы как +неподдерживаемые keyword arguments. DSN в Secrets Manager имеет обычный вид: + +```text +postgresql+asyncpg://:@:/ +``` + +### Первоначальный выпуск Let's Encrypt + +`PROCESSING_PUBLIC_HOST` должен быть DNS-именем, A-запись которого уже указывает +на публичный IP VM2. Сертификат на IP-адрес этим порядком не выпускается. Порт +`80` должен быть разрешён в cloud firewall/UFW и пока не занят nginx. + +Под `root` задайте значения только для текущей shell-сессии и подготовьте +постоянный webroot: + +```sh +PUBLIC_HOST='' +ACME_EMAIL='' +install -d -m 0755 -o root -g root /var/lib/han-chat/acme +getent ahostsv4 "$PUBLIC_HOST" +ss -lntp | grep -E ':80[[:space:]]' && { + echo 'Порт 80 уже занят; остановите listener перед standalone-проверкой' >&2 + exit 1 +} || true +``` + +Сначала проверьте ACME через staging CA. Этот сертификат nginx не использует: + +```sh +certbot certonly --standalone --preferred-challenges http \ + --staging \ + -d "$PUBLIC_HOST" \ + --cert-name "${PUBLIC_HOST}-staging" \ + --email "$ACME_EMAIL" \ + --agree-tos --no-eff-email --non-interactive +certbot delete --cert-name "${PUBLIC_HOST}-staging" --non-interactive +``` + +После успешного staging-теста выпустите production-сертификат: + +```sh +certbot certonly --standalone --preferred-challenges http \ + -d "$PUBLIC_HOST" \ + --cert-name "$PUBLIC_HOST" \ + --email "$ACME_EMAIL" \ + --agree-tos --no-eff-email --non-interactive +certbot certificates +test -s "/etc/letsencrypt/live/${PUBLIC_HOST}/fullchain.pem" +test -s "/etc/letsencrypt/live/${PUBLIC_HOST}/privkey.pem" + +getent group han-nginx-tls +test -d /var/lib/han-chat/public-tls +install -m 0640 -o root -g han-nginx-tls \ + "/etc/letsencrypt/live/${PUBLIC_HOST}/fullchain.pem" \ + /var/lib/han-chat/public-tls/fullchain.pem +install -m 0640 -o root -g han-nginx-tls \ + "/etc/letsencrypt/live/${PUBLIC_HOST}/privkey.pem" \ + /var/lib/han-chat/public-tls/privkey.pem +``` + +Nginx с primary GID `11001` получает только подготовленные public certificate +и private key из `/var/lib/han-chat/public-tls` с host read-only. Исходный +`/etc/letsencrypt` остаётся доступен только root/Certbot. Не копируйте private +key в каталог релиза и не делайте его world-readable. + +## 6. Preflight, миграции и первый запуск под `root` + +Сначала синхронизируйте секреты. Затем выполните статический preflight: + +```sh +systemctl start han-secrets-vm2.service +/opt/han-chat/services/deployment/preflight.sh +/usr/local/sbin/han-vm2-compose config --quiet +``` + +До runtime выполните миграции отдельными DB roles и активируйте начальный +Message Safety config: + +Перед первым `bitrix-sync-migrate` владелец `han_app` или администратор БД +выдаёт Bitrix migration-role временный read-only доступ к legacy mapping: + +```sql +GRANT USAGE ON SCHEMA han_app TO ; +GRANT SELECT ON TABLE han_app.entity_external_mapping + TO ; +``` + +```sh +/usr/local/sbin/han-vm2-compose --profile ops run --rm message-safety-migrate +/usr/local/sbin/han-vm2-compose --profile ops run --rm bitrix-sync-migrate + +/usr/local/sbin/han-vm2-compose --profile ops run --rm \ + --entrypoint message-safety-config message-safety-migrate \ + create /app/app/artifacts/seed-config.yaml --version 1 --actor '' +/usr/local/sbin/han-vm2-compose --profile ops run --rm \ + --entrypoint message-safety-config message-safety-migrate \ + activate --version 1 --approved-by '' +``` + +После успешного `bitrix-sync-migrate` администратор БД отзывает временные +права. Право `USAGE` отзывайте только если оно не требуется этой роли для +других согласованных операций: + +```sql +REVOKE SELECT ON TABLE han_app.entity_external_mapping + FROM ; +REVOKE USAGE ON SCHEMA han_app FROM ; +``` + +Первый запуск и enable выполняет `root` только после прохождения gates: +(внутри gate5) + +```sh +systemctl enable han-secrets-vm2.service han-processing.service +systemctl start han-processing.service +systemctl --no-pager status han-processing.service +journalctl --no-pager -u han-processing.service +``` + +Дальнейшие штатные операции может выполнить `deploy`: + +```sh +sudo systemctl restart han-secrets-vm2.service +sudo systemctl restart han-processing.service +sudo systemctl --no-pager status han-processing.service +sudo journalctl --no-pager -u han-processing.service +``` + +Установка/редактирование unit, Compose, `.env`, secret mapping, credential, +TLS, allow-list и запуск migration jobs остаются операциями `root`. + +### Gate 1 — секреты материализованы + +Под `root` на VM2: + +```sh +systemctl restart han-secrets-vm2.service +systemctl is-active han-secrets-vm2.service +journalctl --no-pager -u han-secrets-vm2.service +test -s /run/han-chat/secrets/manifest +cut -d= -f1 /run/han-chat/secrets/manifest | sort +``` + +Ожидается `active`; журнал не содержит значений секретов; последняя команда +показывает только имена всех ключей из mapping. Не выполняйте `cat` файлов +секретов и не вставляйте реальные значения в terminal history. + +### Gate 2 — статический preflight и Compose + +Под `root` на VM2: + +```sh +cd /opt/han-chat/services +deployment/preflight.sh +/usr/local/sbin/han-vm2-compose config --quiet +/usr/local/sbin/han-vm2-compose config --services +/usr/local/sbin/han-vm2-compose config --images +``` + +Все команды должны завершиться с кодом `0`. В списке services нет PostgreSQL, +а все production images содержат `@sha256:`. Вывод полного resolved Compose в +файл не сохраняйте. + +### Gate 3 — миграции и активный Message Safety config + +Команды миграций из предыдущего раздела выполняются под `root`. После них: + +```sh +/usr/local/sbin/han-vm2-compose --profile ops run --rm \ + message-safety-migrate current +/usr/local/sbin/han-vm2-compose --profile ops run --rm \ + bitrix-sync-migrate current +``` + +Ожидается по одной head revision каждого сервиса. `create --version 1` +выполняется только при первом развёртывании. Для следующего конфига используйте +новый монотонный номер и отдельные значения `--actor`/`--approved-by`; повторно +активировать старую версию нельзя. Alembic downgrade запрещён. + +### Gate 4 — конфигурация nginx до запуска + +После выпуска public TLS в `/etc/letsencrypt` и материализации internal TLS +secrets. В Selectel значения `VM2_INTERNAL_TLS_CERTIFICATE` и +`VM2_INTERNAL_TLS_PRIVATE_KEY` сохраняются как исходный PEM с настоящими +переводами строк, не как повторный base64 и не как строка с литералами `\n`. +После изменения remote secret перезапустите `han-secrets-vm2.service`; preflight +проверит формат PEM и соответствие certificate/key без вывода их содержимого: + +```sh +/opt/han-chat/services/deployment/preflight.sh +/usr/local/sbin/han-vm2-compose run --rm --no-deps \ + -e MESSAGE_SAFETY_UPSTREAM_HOST=127.0.0.1 \ + -e BITRIX_SYNC_UPSTREAM_HOST=127.0.0.1 \ + nginx \ + nginx -t -c /etc/nginx/nginx.conf +``` + +Базовый `nginx.conf` подключает обязательный +`/etc/nginx/conf.d/10-vm2.conf`, поэтому команда завершится ошибкой, если +entrypoint не создал конфигурацию из шаблона. Временные значения upstream +нужны только для проверки до первого запуска backend-контейнеров; production +Compose подставляет DNS-имена сервисов. Ожидается `syntax is ok` и `test is +successful`; ошибок `conf.d is not writable` и предупреждения о превышении +open-file limit быть не должно. Ошибка отсутствующего сертификата является +блокером, а не основанием временно убрать TLS. + +### Gate 5 — упорядоченный первый запуск + +Под `root` на VM2: + +```sh +/usr/local/sbin/han-vm2-compose up -d redis-safety otel-collector +/usr/local/sbin/han-vm2-compose up -d freshclam clamd +/usr/local/sbin/han-vm2-compose up -d \ + message-safety-api message-safety-worker +/usr/local/sbin/han-vm2-compose up -d \ + bitrix-sync bitrix-sync-worker bitrix-sync-reconciliation +/usr/local/sbin/han-vm2-compose up -d nginx +/usr/local/sbin/han-vm2-compose ps +``` + +`otel-collector` автоматически запускает одноразовый `otel-queue-init`. Он +выставляет владельца persistent queue `10001:10001` и завершается с кодом `0`; +сам Collector стартует только после этого. + +Healthcheck nginx использует встроенный `nginx -t`: утверждённый +`nginx-unprivileged` image не содержит `wget`/`curl`. `ExitCode 127` с +сообщением `wget: not found` означает, что на VM2 остался старый Compose. + +Если запуск выполнялся со старым релизом и Message Safety уже попал в +permission/restart loop, после активации исправленного релиза под `root` +восстановите контракт файла и пересоздайте затронутые контейнеры: + +```sh +getent group 10001 >/dev/null || + groupadd --system --gid 10001 han-message-safety +test "$(getent group han-message-safety | cut -d: -f3)" = 10001 +chown root:han-message-safety /etc/han-chat/message-safety-mode.env +chmod 0640 /etc/han-chat/message-safety-mode.env +install -m 0755 -o root -g root \ + /opt/han-chat/services/deployment/han-message-safety-mode \ + /usr/local/sbin/han-message-safety-mode + +/opt/han-chat/services/deployment/preflight.sh +/usr/local/sbin/han-vm2-compose up -d --force-recreate \ + otel-queue-init otel-collector +/usr/local/sbin/han-vm2-compose up -d --force-recreate \ + message-safety-api message-safety-worker +/usr/local/sbin/han-vm2-compose ps +``` + +Не заменяйте это на `chmod 0644/0666`, запуск контейнеров от root или +рекурсивный `chown` Docker volumes. Если после восстановления прав nginx +остаётся в `Restarting`, это отдельная ошибка конфигурации/TLS, а не права +Message Safety; проверьте её без вывода секретов: + +```sh +/usr/local/sbin/han-vm2-compose logs --tail 100 nginx otel-collector +``` + +Дождитесь `healthy` у сервисов с healthcheck. Не продолжайте при +`Restarting`, `unhealthy`, OOM или неожиданном `Exited`. После успешного +первого запуска передайте дальнейший lifecycle systemd: + +```sh +systemctl enable han-secrets-vm2.service han-processing.service +systemctl start han-processing.service +systemctl --no-pager status han-processing.service +``` + +### Gate 6 — host ports и сертификаты + +Под `root` на VM2: + +```sh +ss -lntp | grep -E ':(80|443|8443|6379|8080|4317|4318)[[:space:]]' +/usr/local/sbin/han-vm2-compose ps --format json | jq . +``` + +Ожидаются host listeners только nginx: public `80`, `443` и private-bound +`8443` на `PROCESSING_PRIVATE_BIND_ADDRESS`. `6379`, container `8080` и OTLP +`4317/4318` на host отсутствуют. + +С доверенной рабочей станции проверьте public chain: + +```sh +openssl s_client -connect :443 \ + -servername \ + -verify_hostname -verify_return_error :8443 \ + -servername \ + -verify_hostname \ + -CAfile -verify_return_error /not-a-route +curl -sS -o /dev/null -w '%{http_code}\n' \ + https:///not-a-route +curl -sS -o /dev/null -w '%{http_code}\n' \ + http:///bitrix/sync/webhook/contact +curl -sS -o /dev/null -w '%{http_code}\n' \ + https:///internal/safety/status +curl -sS -o /dev/null -w '%{http_code}\n' -X GET \ + https:///bitrix/sync/webhook/contact +``` + +Ожидаемые коды по порядку: `308`, `404`, `426`, `404`, `405`. Для HTTPS +используйте только валидный public certificate, без `-k`. + +POST к webhook с адреса вне Bitrix allow-list должен получить `403`; если +cloud firewall настроен на drop, допустим timeout. Затем повторите с +разрешённого source IP и заведомо неверным receiver token: upstream должен +ответить `403`, не `2xx`. + +### Gate 8 — private API только с VM1/ops + +Следующие команды выполняются **на VM1** или approved ops host, не на VM2. +Используйте private DNS/SAN и внутреннюю CA. + +Safety status: + +```sh +curl --fail --silent --show-error \ + --cacert \ + https://:8443/internal/safety/status +``` + +Benign text check через тот же private listener: + +```sh +SAFETY_TOKEN="$(cat )" +MESSAGE_ID="$(uuidgen)" +curl --silent --show-error --write-out '\nHTTP %{http_code}\n' --config - </bitrix/sync/webhook/contact?token=${CANARY}" +``` + +На VM2 под `root`: + +```sh +CANARY='<ЗНАЧЕНИЕ_CANARY_С_ТЕСТОВОЙ_МАШИНЫ>' +if /usr/local/sbin/han-vm2-compose logs --no-color \ + nginx bitrix-sync message-safety-api otel-collector | + grep -F -- "$CANARY"; then + echo 'FAIL: canary попал в логи' >&2 + exit 1 +fi +unset CANARY +``` + +В SigNoz выполните поиск этого же marker по logs и span attributes за окно +теста: результат должен быть пустым. Отдельными фейковыми markers повторите +проверку для DSN-подобной строки, S3 key и object key. Реальные secrets для +такой проверки не используйте. + +Не открывайте webhook-трафик, пока `bitrix-sync` отключён. Отключённый или +упавший receiver должен возвращать retryable `503`/закрытую маршрутизацию, +никогда успешный `2xx ignored`. + +## Политика отказов + +- Отказ зависимости Safety — fail-closed: VM1 не должна отправлять/продвигать + контент. +- Устаревшие/недоступные сигнатуры ClamAV отключают только файловую + capability; ошибка сканирования никогда не превращается в allow. +- Потеря Redis может убрать ускорение, но PostgreSQL остаётся источником + истины. +- Сбой OTEL ставит в очередь в пределах ограниченного тома и не должен + менять вердикты. +- Rollback не понижает схемы, не удаляет durable tasks/mappings и не + запускает `docker compose down -v`. + +## Аварийный MOCK + +Разрешены только эти пять sudo-команд: + +```text +han-message-safety-mode standard +han-message-safety-mode mock --text-free true --file-free true +han-message-safety-mode mock --text-free true --file-free false +han-message-safety-mode mock --text-free false --file-free true +han-message-safety-mode mock --text-free false --file-free false +``` + +Хелпер атомарно пишет только +`/etc/han-chat/message-safety-mode.env`, пересоздаёт только Safety API, +проверяет health и при сбое восстанавливает предыдущий режим. У MOCK нет +таймаута: держите high-severity alert активным до явного `standard`, затем +проверьте нормальные text/link/file capabilities и EICAR-canary. + +## Известные исключения по образам + +Образы ClamAV могут потребовать корректировок UID/path после валидации +точного digest. Не ослабляйте `read_only`, capabilities или mounts глобально: +задокументируйте минимальные writable пути для сигнатур/runtime и +компенсируйте сетевыми и ресурсными лимитами. Egress к signature-CDN +получает только `freshclam`; `clamd` — нет. diff --git a/codebase/services/deployment/deploy-message-safety-mode.sudoers b/codebase/services/deployment/deploy-message-safety-mode.sudoers new file mode 100644 index 0000000..e79f39f --- /dev/null +++ b/codebase/services/deployment/deploy-message-safety-mode.sudoers @@ -0,0 +1,3 @@ +# Install as root:root 0440 and validate with visudo -cf. +# The root-owned wrapper strictly validates the complete argument list. +deploy ALL=(root) NOPASSWD: /usr/local/sbin/han-message-safety-mode diff --git a/codebase/services/deployment/han-message-safety-mode b/codebase/services/deployment/han-message-safety-mode new file mode 100644 index 0000000..37f2705 --- /dev/null +++ b/codebase/services/deployment/han-message-safety-mode @@ -0,0 +1,114 @@ +#!/bin/sh +# Install as root:root 0755 at /usr/local/sbin/han-message-safety-mode. +set -eu + +MODE_FILE=/etc/han-chat/message-safety-mode.env +COMPOSE=/usr/local/sbin/han-vm2-compose +LOCK=/run/lock/han-message-safety-mode.lock +MODE_GROUP=han-message-safety + +if [ "$#" -eq 1 ] && [ "$1" = standard ]; then + mock=false + text=false + file=false +elif [ "$#" -eq 5 ] && + [ "$1" = mock ] && + [ "$2" = --text-free ] && + { [ "$3" = true ] || [ "$3" = false ]; } && + [ "$4" = --file-free ] && + { [ "$5" = true ] || [ "$5" = false ]; }; then + mock=true + text=$3 + file=$5 +else + echo "usage: han-message-safety-mode standard | mock --text-free true|false --file-free true|false" >&2 + exit 64 +fi + +[ "$(id -u)" -eq 0 ] || { + echo "must run through approved sudo rule" >&2 + exit 77 +} +[ -x "$COMPOSE" ] || { + echo "fixed compose launcher is unavailable" >&2 + exit 69 +} + +exec 9>"$LOCK" +/usr/bin/flock -n 9 || { + echo "another mode transition is active" >&2 + exit 75 +} + +directory=$(dirname "$MODE_FILE") +/usr/bin/install -d -o root -g root -m 0700 "$directory" +temporary=$(/usr/bin/mktemp "$directory/.message-safety-mode.XXXXXX") +backup=$(/usr/bin/mktemp "$directory/.message-safety-mode.backup.XXXXXX") +cleanup() { + /usr/bin/rm -f "$temporary" "$backup" +} +trap cleanup EXIT HUP INT TERM + +if [ -f "$MODE_FILE" ]; then + /usr/bin/cp --preserve=mode,ownership "$MODE_FILE" "$backup" +else + : >"$backup" + /usr/bin/chmod 0600 "$backup" +fi +old_mode=$(/usr/bin/awk -F= ' + $1 == "MESSAGE_SAFETY_MOCK_ENABLED" {mock=$2} + $1 == "MESSAGE_SAFETY_MOCK_TEXT_FREE" {text=$2} + $1 == "MESSAGE_SAFETY_MOCK_FILE_FREE" {file=$2} + END {printf "mock=%s,text=%s,file=%s", mock, text, file} +' "$backup") + +{ + printf 'MESSAGE_SAFETY_MOCK_ENABLED=%s\n' "$mock" + printf 'MESSAGE_SAFETY_MOCK_TEXT_FREE=%s\n' "$text" + printf 'MESSAGE_SAFETY_MOCK_FILE_FREE=%s\n' "$file" +} >"$temporary" +/usr/bin/chown root:"$MODE_GROUP" "$temporary" +/usr/bin/chmod 0640 "$temporary" +/usr/bin/mv -fT "$temporary" "$MODE_FILE" + +restart_api() { + "$COMPOSE" config --quiet && + "$COMPOSE" up -d --no-deps --force-recreate message-safety-api +} + +healthy=false +if restart_api; then + attempt=0 + while [ "$attempt" -lt 30 ]; do + container=$("$COMPOSE" ps -q message-safety-api) + if [ -n "$container" ]; then + status=$(/usr/bin/docker inspect --format '{{if .State.Health}}{{.State.Health.Status}}{{else}}{{.State.Status}}{{end}}' "$container") + if [ "$status" = healthy ]; then + healthy=true + break + fi + fi + attempt=$((attempt + 1)) + /usr/bin/sleep 2 + done +fi + +if [ "$healthy" != true ]; then + if [ -s "$backup" ]; then + /usr/bin/cp "$backup" "$temporary" + else + printf '%s\n' \ + 'MESSAGE_SAFETY_MOCK_ENABLED=false' \ + 'MESSAGE_SAFETY_MOCK_TEXT_FREE=false' \ + 'MESSAGE_SAFETY_MOCK_FILE_FREE=false' >"$temporary" + fi + /usr/bin/chown root:"$MODE_GROUP" "$temporary" + /usr/bin/chmod 0640 "$temporary" + /usr/bin/mv -fT "$temporary" "$MODE_FILE" + restart_api || true + /usr/bin/logger -p authpriv.err -t han-message-safety-mode "transition failed; previous policy restored" + exit 1 +fi + +/usr/bin/logger -p authpriv.notice -t han-message-safety-mode \ + "transition succeeded old=$old_mode new=mock=$mock,text=$text,file=$file actor=${SUDO_USER:-root}" diff --git a/codebase/services/deployment/han-processing.service b/codebase/services/deployment/han-processing.service new file mode 100644 index 0000000..a073275 --- /dev/null +++ b/codebase/services/deployment/han-processing.service @@ -0,0 +1,31 @@ +[Unit] +Description=HAN Processing VM2 root Compose stack +Requires=docker.service han-secrets-vm2.service +After=docker.service han-secrets-vm2.service network-online.target + +[Service] +Type=oneshot +RemainAfterExit=yes +User=root +Group=root +WorkingDirectory=/opt/han-chat/services +ExecStart=/usr/local/sbin/han-vm2-compose up -d --remove-orphans +ExecReload=/usr/local/sbin/han-vm2-compose up -d --remove-orphans +ExecStop=/usr/local/sbin/han-vm2-compose stop +TimeoutStartSec=300 +TimeoutStopSec=120 +UMask=0077 +NoNewPrivileges=yes +PrivateTmp=yes +ProtectHome=yes +ProtectKernelTunables=yes +ProtectKernelModules=yes +ProtectKernelLogs=yes +ProtectControlGroups=yes +RestrictRealtime=yes +RestrictSUIDSGID=yes +LockPersonality=yes +LimitCORE=0 + +[Install] +WantedBy=multi-user.target diff --git a/codebase/services/deployment/preflight.sh b/codebase/services/deployment/preflight.sh new file mode 100644 index 0000000..594c9ac --- /dev/null +++ b/codebase/services/deployment/preflight.sh @@ -0,0 +1,192 @@ +#!/bin/sh +set -eu + +ROOT=${1:-/opt/han-chat/services} +ENV_FILE=${2:-$ROOT/.env} +MANIFEST=${3:-/run/han-chat/secrets/manifest} +failures=0 + +fail() { + echo "FAIL: $*" >&2 + failures=$((failures + 1)) +} + +[ "$(id -u)" -eq 0 ] || fail "preflight must inspect production files as root" +[ -f "$ROOT/docker-compose.yml" ] || fail "root docker-compose.yml is missing" +[ -d "$ROOT/message-safety" ] || fail "message-safety artifact directory is missing" +[ -d "$ROOT/bitrix-sync" ] || fail "bitrix-sync artifact directory is missing" +[ -f "$ENV_FILE" ] || fail ".env is missing" +[ -f "$MANIFEST" ] || fail "runtime secret manifest is missing" +[ -f /etc/han-chat/message-safety-mode.env ] || + fail "root-owned Message Safety mode file is missing; initialize standard mode" +/usr/bin/getent group han-message-safety | /usr/bin/awk -F: '$3 == 10001 {found=1} END {exit !found}' || + fail "han-message-safety group with GID 10001 is missing" + +public_tls_dir=/var/lib/han-chat/public-tls +/usr/bin/getent group han-nginx-tls | /usr/bin/awk -F: '$3 == 11001 {found=1} END {exit !found}' || + fail "han-nginx-tls group with GID 11001 is missing" +[ -d "$public_tls_dir" ] || fail "public TLS staging directory is missing" +for tls_file in fullchain.pem privkey.pem; do + path="$public_tls_dir/$tls_file" + [ -s "$path" ] || { + fail "public TLS file is missing or empty: $path" + continue + } + [ "$(/usr/bin/stat -c '%U:%G:%a' "$path")" = "root:han-nginx-tls:640" ] || + fail "public TLS file must be root:han-nginx-tls 0640: $path" +done + +if [ -f "$ENV_FILE" ]; then + if /usr/bin/grep -Eq '(^|_)(PASSWORD|SECRET|TOKEN|DATABASE_URL|REDIS_URL|PRIVATE_KEY|ACCESS_KEY)=' "$ENV_FILE"; then + fail ".env contains a secret-shaped key" + fi + if /usr/bin/grep -Eq '=<[^>]+>|change-me|example\.(com|org|net)' "$ENV_FILE"; then + fail ".env still contains placeholders" + fi + bitrix_enabled=$(/usr/bin/awk -F= '$1 == "BITRIX_SYNC_ENABLED" {print $2}' "$ENV_FILE") + bitrix_mode=$(/usr/bin/awk -F= '$1 == "BITRIX_SYNC_MODE" {print $2}' "$ENV_FILE") + case "$bitrix_enabled" in + true|false) ;; + *) fail "BITRIX_SYNC_ENABLED must be exactly true or false" ;; + esac + if { [ "$bitrix_enabled" = true ] && [ "$bitrix_mode" != full ]; } || + { [ "$bitrix_enabled" = false ] && [ "$bitrix_mode" != disabled ]; }; then + fail "BITRIX_SYNC_MODE must be full when enabled and disabled otherwise" + fi + otel_tls_insecure=$(/usr/bin/awk -F= \ + '$1 == "OTEL_REMOTE_TLS_INSECURE" {print $2}' "$ENV_FILE") + case "$otel_tls_insecure" in + true|false) ;; + *) fail "OTEL_REMOTE_TLS_INSECURE must be exactly true or false" ;; + esac + for image_key in MESSAGE_SAFETY_IMAGE BITRIX_SYNC_IMAGE NGINX_IMAGE REDIS_IMAGE CLAMAV_IMAGE OTEL_COLLECTOR_IMAGE; do + image=$(/usr/bin/awk -F= -v key="$image_key" '$1 == key {print substr($0, index($0, "=") + 1)}' "$ENV_FILE") + echo "$image" | /usr/bin/grep -Eq '@sha256:[0-9a-f]{64}$' || + fail "$image_key must be pinned by sha256 digest" + done + private_bind=$(/usr/bin/awk -F= '$1 == "PROCESSING_PRIVATE_BIND_ADDRESS" {print $2}' "$ENV_FILE") + case "$private_bind" in + ""|0.0.0.0|::|127.*) fail "private 8443 bind address is unsafe" ;; + esac +fi + +bitrix_allowlist="$ROOT/nginx/allowlists/bitrix-webhook-allowlist.conf" +private_allowlist="$ROOT/nginx/allowlists/private-caller-allowlist.conf" +for allowlist in "$bitrix_allowlist" "$private_allowlist"; do + [ -f "$allowlist" ] || { + fail "allow-list is missing: $allowlist" + continue + } + [ "$(/usr/bin/tail -n 1 "$allowlist" | /usr/bin/tr -d '[:space:]')" = "denyall;" ] || + fail "allow-list must end in deny all: $allowlist" +done + +if [ "${bitrix_enabled:-}" = true ]; then + /usr/bin/grep -Eq '^[[:space:]]*allow[[:space:]]+[^;]+;' "$bitrix_allowlist" || + fail "enabled bitrix-sync requires reviewed webhook CIDRs" +else + ! /usr/bin/grep -Eq '^[[:space:]]*allow[[:space:]]+[^;]+;' "$bitrix_allowlist" || + fail "disabled bitrix-sync must keep public webhook allow-list closed" +fi +/usr/bin/grep -Eq '^[[:space:]]*allow[[:space:]]+[^;]+;' "$private_allowlist" || + fail "private 8443 requires reviewed VM1/ops CIDRs" + +required_secrets=' +MESSAGE_SAFETY_DATABASE_URL +MESSAGE_SAFETY_CONFIG_ADMIN_DATABASE_URL +MESSAGE_SAFETY_REDIS_URL +MESSAGE_SAFETY_SERVICE_TOKEN +SELECTEL_S3_QUARANTINE_READ_ACCESS_KEY +SELECTEL_S3_QUARANTINE_READ_SECRET_KEY +VM2_INTERNAL_TLS_CERTIFICATE +VM2_INTERNAL_TLS_PRIVATE_KEY +BITRIX_SYNC_DATABASE_URL +BITRIX_SYNC_MIGRATION_DATABASE_URL +BITRIX_SYNC_CRM_REST_WEBHOOK_URL +BITRIX_SYNC_CONTACT_RECEIVER_TOKEN +BITRIX_SYNC_ALERT_RECEIVER_TOKEN +BITRIX_SYNC_SERVICE_TOKEN +REDIS_SAFETY_ACL' + +if [ -f "$MANIFEST" ]; then + old_ifs=$IFS + IFS=' +' + for name in $required_secrets; do + [ -n "$name" ] || continue + path=$(/usr/bin/awk -F= -v key="$name" '$1 == key {print substr($0, index($0, "=") + 1)}' "$MANIFEST") + [ -n "$path" ] || { + fail "manifest is missing $name" + continue + } + [ -f "$path" ] || fail "secret file is missing for $name" + done + IFS=$old_ifs + + internal_cert=$(/usr/bin/awk -F= \ + '$1 == "VM2_INTERNAL_TLS_CERTIFICATE" {print substr($0, index($0, "=") + 1)}' \ + "$MANIFEST") + internal_key=$(/usr/bin/awk -F= \ + '$1 == "VM2_INTERNAL_TLS_PRIVATE_KEY" {print substr($0, index($0, "=") + 1)}' \ + "$MANIFEST") + cert_valid=false + key_valid=false + if [ -f "$internal_cert" ] && + /usr/bin/openssl x509 -in "$internal_cert" -noout >/dev/null 2>&1; then + cert_valid=true + else + fail "internal TLS certificate is not valid PEM" + fi + if [ -f "$internal_key" ] && + /usr/bin/openssl pkey -in "$internal_key" -passin pass: \ + -noout -check >/dev/null 2>&1; then + key_valid=true + else + fail "internal TLS private key is not valid unencrypted PEM" + fi + if [ "$cert_valid" = true ] && [ "$key_valid" = true ]; then + cert_public=$( + /usr/bin/openssl x509 -in "$internal_cert" -pubkey -noout | + /usr/bin/openssl pkey -pubin -outform DER 2>/dev/null | + /usr/bin/sha256sum | /usr/bin/awk '{print $1}' + ) + key_public=$( + /usr/bin/openssl pkey -in "$internal_key" -passin pass: -pubout -outform DER 2>/dev/null | + /usr/bin/sha256sum | /usr/bin/awk '{print $1}' + ) + [ "$cert_public" = "$key_public" ] || + fail "internal TLS certificate and private key do not match" + fi +fi + +mode_file=/etc/han-chat/message-safety-mode.env +if [ -f "$mode_file" ]; then + [ "$(/usr/bin/stat -c '%U:%G:%a' "$mode_file")" = root:han-message-safety:640 ] || + fail "Message Safety mode file must be root:han-message-safety 0640" + mode_lines=$(/usr/bin/sort "$mode_file") + case "$mode_lines" in + *MESSAGE_SAFETY_MOCK_ENABLED=*MESSAGE_SAFETY_MOCK_FILE_FREE=*MESSAGE_SAFETY_MOCK_TEXT_FREE=*) ;; + *) fail "Message Safety mode file is incomplete" ;; + esac +fi + +for protected in \ + "$ROOT/docker-compose.yml" \ + "$ROOT/deployment/han-message-safety-mode" \ + "$ROOT/deployment/han-processing.service" +do + [ -f "$protected" ] || continue + owner=$(/usr/bin/stat -c '%U:%G' "$protected") + [ "$owner" = root:root ] || fail "$protected must be root:root" + mode=$(/usr/bin/stat -c '%A' "$protected") + case "$mode" in + ??????w???|????????w?) fail "$protected is writable by group/other" ;; + esac +done + +if [ "$failures" -ne 0 ]; then + echo "preflight: $failures failure(s); deployment remains closed" >&2 + exit 1 +fi + +echo "preflight: static VM2 gates passed; run compose/nginx/TLS probes separately" diff --git a/codebase/services/deployment/scripts/setup-vm.sh b/codebase/services/deployment/scripts/setup-vm.sh new file mode 100644 index 0000000..c54d6bd --- /dev/null +++ b/codebase/services/deployment/scripts/setup-vm.sh @@ -0,0 +1,762 @@ +#!/usr/bin/env bash +# Первичная подготовка Ubuntu 24.04 для HAN Chat VM2 Processing. +# +# Скрипт устанавливает host-зависимости, Docker/Compose, создаёт непривилегированную +# роль deploy, настраивает SSH/UFW/fail2ban/DOCKER-USER/swap и устанавливает +# root-owned deployment helpers, если релиз уже размещён в DEPLOY_DIR. +# +# PostgreSQL, S3, Selectel IAM, DNS, TLS, образы, .env и значения секретов +# скрипт не создаёт. Он не запускает Compose и прикладные контейнеры. +# +# Первый запуск на свежей VM выполняется root: +# DEPLOY_AUTHORIZED_KEY_FILE=/root/bootstrap/deploy.pub \ +# ADMIN_AUTHORIZED_KEY_FILE=/root/bootstrap/admin.pub \ +# VM1_PRIVATE_CIDRS=10.10.1.5/32 \ +# bash deployment/scripts/setup-vm.sh +# +# После задания sudo-пароля admin и проверки обоих входов: +# DEPLOY_AUTHORIZED_KEY_FILE=/root/bootstrap/deploy.pub \ +# ADMIN_AUTHORIZED_KEY_FILE=/root/bootstrap/admin.pub \ +# VM1_PRIVATE_CIDRS=10.10.1.5/32 \ +# HARDEN_SSH=true SKIP_APT_UPGRADE=true \ +# bash deployment/scripts/setup-vm.sh +# +# Параметры: +# DEPLOY_USER=deploy +# ADMIN_USER=admin +# DEPLOY_AUTHORIZED_KEY_FILE=/root/bootstrap/deploy.pub +# ADMIN_AUTHORIZED_KEY_FILE=/root/bootstrap/admin.pub +# DEPLOY_DIR=/opt/han-chat/services +# INCOMING_DIR=/var/lib/han-deploy/incoming +# SSH_PORT=22 +# OPS_CIDRS=10.20.0.0/24 # необязательные приватные/VPN-сети для API 8443 +# VM1_PRIVATE_CIDRS=10.10.1.5/32 +# TIMEZONE=Europe/Moscow +# SWAP_SIZE_GB=4 +# EXTERNAL_IF=ens3 +# HARDEN_SSH=false +# LOCK_ACCOUNT_PASSWORDS=true +# RESET_UFW=true +# SKIP_APT_UPGRADE=false + +set -Eeuo pipefail +IFS=$'\n\t' + +DEPLOY_USER="${DEPLOY_USER:-deploy}" +ADMIN_USER="${ADMIN_USER:-admin}" +DEPLOY_AUTHORIZED_KEY_FILE="${DEPLOY_AUTHORIZED_KEY_FILE:-}" +ADMIN_AUTHORIZED_KEY_FILE="${ADMIN_AUTHORIZED_KEY_FILE:-}" +DEPLOY_DIR="${DEPLOY_DIR:-/opt/han-chat/services}" +INCOMING_DIR="${INCOMING_DIR:-/var/lib/han-deploy/incoming}" +SSH_PORT="${SSH_PORT:-22}" +OPS_CIDRS="${OPS_CIDRS:-}" +VM1_PRIVATE_CIDRS="${VM1_PRIVATE_CIDRS:-}" +TIMEZONE="${TIMEZONE:-Europe/Moscow}" +SWAP_SIZE_GB="${SWAP_SIZE_GB:-4}" +EXTERNAL_IF="${EXTERNAL_IF:-}" +HARDEN_SSH="${HARDEN_SSH:-false}" +LOCK_ACCOUNT_PASSWORDS="${LOCK_ACCOUNT_PASSWORDS:-true}" +RESET_UFW="${RESET_UFW:-true}" +SKIP_APT_UPGRADE="${SKIP_APT_UPGRADE:-false}" +LOG_FILE="${LOG_FILE:-/var/log/han-chat-vm2-setup.log}" + +log() { + printf '[%s] %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "$*" | tee -a "$LOG_FILE" +} + +step() { + log "" + log "==> $*" +} + +die() { + log "ОШИБКА: $*" + exit 1 +} + +on_error() { + local exit_code=$? + log "ОШИБКА: команда завершилась с кодом ${exit_code}, строка ${BASH_LINENO[0]}" + exit "$exit_code" +} +trap on_error ERR + +require_root() { + [[ "${EUID:-$(id -u)}" -eq 0 ]] || die "Запустите скрипт от root" +} + +is_true_or_false() { + [[ "$1" == "true" || "$1" == "false" ]] +} + +validate_cidr_list() { + local label=$1 + local value=$2 + local item + local octet + local prefix + [[ -n "$value" ]] || die "${label} обязателен и не может быть пустым" + IFS=',' read -ra items <<<"$value" + for item in "${items[@]}"; do + [[ "$item" =~ ^([0-9]{1,3}\.){3}[0-9]{1,3}/([0-9]{1,2})$ ]] \ + || die "${label} содержит некорректный IPv4 CIDR: ${item}" + prefix="${item##*/}" + ((10#$prefix >= 1 && 10#$prefix <= 32)) \ + || die "${label}: префикс должен быть от /1 до /32: ${item}" + IFS='.' read -ra octets <<<"${item%/*}" + for octet in "${octets[@]}"; do + ((10#$octet <= 255)) || die "${label} содержит некорректный IPv4 CIDR: ${item}" + done + done +} + +validate_parameters() { + [[ "$DEPLOY_USER" =~ ^[a-z_][a-z0-9_-]*$ ]] || die "Некорректный DEPLOY_USER" + [[ "$DEPLOY_USER" == "deploy" ]] \ + || die "VM2 units/sudoers используют фиксированную роль deploy" + [[ "$ADMIN_USER" == "admin" ]] || die "VM2 break-glass роль должна называться admin" + [[ "$DEPLOY_AUTHORIZED_KEY_FILE" =~ ^/[A-Za-z0-9._/-]+$ ]] \ + || die "DEPLOY_AUTHORIZED_KEY_FILE должен быть безопасным абсолютным путём" + [[ "$ADMIN_AUTHORIZED_KEY_FILE" =~ ^/[A-Za-z0-9._/-]+$ ]] \ + || die "ADMIN_AUTHORIZED_KEY_FILE должен быть безопасным абсолютным путём" + [[ "$DEPLOY_AUTHORIZED_KEY_FILE" != "$ADMIN_AUTHORIZED_KEY_FILE" ]] \ + || die "deploy и admin должны использовать разные public key files" + [[ "$DEPLOY_DIR" =~ ^/[A-Za-z0-9._/-]+$ ]] \ + || die "DEPLOY_DIR должен быть безопасным абсолютным путём" + [[ "$INCOMING_DIR" =~ ^/[A-Za-z0-9._/-]+$ ]] \ + || die "INCOMING_DIR должен быть безопасным абсолютным путём" + [[ "$DEPLOY_DIR" != "$INCOMING_DIR" ]] || die "DEPLOY_DIR и INCOMING_DIR должны различаться" + [[ "$TIMEZONE" =~ ^[A-Za-z0-9_+/-]+$ ]] || die "Некорректный TIMEZONE" + [[ -z "$EXTERNAL_IF" || "$EXTERNAL_IF" =~ ^[A-Za-z0-9_.:-]+$ ]] \ + || die "Некорректный EXTERNAL_IF" + [[ "$SSH_PORT" =~ ^[0-9]+$ ]] || die "SSH_PORT должен быть числом" + ((SSH_PORT >= 1 && SSH_PORT <= 65535)) || die "SSH_PORT вне диапазона" + [[ "$SWAP_SIZE_GB" =~ ^[0-9]+$ ]] || die "SWAP_SIZE_GB должен быть целым числом" + is_true_or_false "$HARDEN_SSH" || die "HARDEN_SSH должен быть true или false" + is_true_or_false "$LOCK_ACCOUNT_PASSWORDS" \ + || die "LOCK_ACCOUNT_PASSWORDS должен быть true или false" + if [[ "$HARDEN_SSH" == "true" && "$LOCK_ACCOUNT_PASSWORDS" != "true" ]]; then + die "HARDEN_SSH=true требует LOCK_ACCOUNT_PASSWORDS=true" + fi + is_true_or_false "$RESET_UFW" || die "RESET_UFW должен быть true или false" + is_true_or_false "$SKIP_APT_UPGRADE" || die "SKIP_APT_UPGRADE должен быть true или false" + if [[ -n "$OPS_CIDRS" ]]; then + validate_cidr_list OPS_CIDRS "$OPS_CIDRS" + fi + validate_cidr_list VM1_PRIVATE_CIDRS "$VM1_PRIVATE_CIDRS" +} + +check_os() { + step "Проверка операционной системы" + [[ -r /etc/os-release ]] || die "Не найден /etc/os-release" + # shellcheck disable=SC1091 + source /etc/os-release + [[ "${ID:-}" == "ubuntu" ]] || die "Поддерживается только Ubuntu" + [[ "${VERSION_ID%%.*}" -ge 24 ]] || die "Требуется Ubuntu 24.04 или новее" + log "Обнаружена ${PRETTY_NAME}" +} + +update_system() { + step "Обновление системы и установка host-пакетов" + export DEBIAN_FRONTEND=noninteractive + apt-get update + if [[ "$SKIP_APT_UPGRADE" != "true" ]]; then + apt-get dist-upgrade -y + fi + apt-get install -y --no-install-recommends \ + ca-certificates \ + certbot \ + curl \ + fail2ban \ + git \ + gnupg \ + iptables \ + jq \ + logrotate \ + netcat-openbsd \ + openssh-client \ + openssl \ + python3 \ + rsync \ + sudo \ + unattended-upgrades \ + ufw \ + util-linux +} + +configure_time() { + step "Настройка времени" + timedatectl set-timezone "$TIMEZONE" + timedatectl set-ntp true +} + +install_authorized_key() { + local user=$1 + local source=$2 + local target="/home/${user}/.ssh/authorized_keys" + [[ -f "$source" && ! -L "$source" ]] || die "Не найден обычный public key file: ${source}" + [[ "$(wc -l <"$source")" -eq 1 ]] || die "${source} должен содержать ровно один public key" + ssh-keygen -l -f "$source" >/dev/null || die "Некорректный SSH public key: ${source}" + grep -Eq '^ssh-ed25519[[:space:]]+[A-Za-z0-9+/=]+([[:space:]].*)?$' "$source" \ + || die "Для ${user} разрешён только отдельный Ed25519 public key" + install -d -m 0700 -o "$user" -g "$user" "/home/${user}/.ssh" + install -m 0600 -o "$user" -g "$user" "$source" "$target" +} + +create_host_roles() { + step "Создание ролей deploy и break-glass admin" + if ! id "$DEPLOY_USER" >/dev/null 2>&1; then + useradd --create-home --shell /bin/bash "$DEPLOY_USER" + log "Создан пользователь ${DEPLOY_USER}" + fi + if ! id "$ADMIN_USER" >/dev/null 2>&1; then + useradd --create-home --shell /bin/bash "$ADMIN_USER" + log "Создан break-glass пользователь ${ADMIN_USER}" + fi + + install_authorized_key "$DEPLOY_USER" "$DEPLOY_AUTHORIZED_KEY_FILE" + install_authorized_key "$ADMIN_USER" "$ADMIN_AUTHORIZED_KEY_FILE" + + local deploy_key + local admin_key + deploy_key="$(awk '{print $2}' "$DEPLOY_AUTHORIZED_KEY_FILE")" + admin_key="$(awk '{print $2}' "$ADMIN_AUTHORIZED_KEY_FILE")" + [[ "$deploy_key" != "$admin_key" ]] || die "deploy и admin не могут использовать один SSH key" + if [[ -s /root/.ssh/authorized_keys ]] && + { grep -Fq "$deploy_key" /root/.ssh/authorized_keys || + grep -Fq "$admin_key" /root/.ssh/authorized_keys; }; then + die "Ключ deploy/admin совпадает с одним из root authorized_keys" + fi + + # Deploy получает только точные sudoers-команды, без широких групп. + local forbidden_group + for forbidden_group in docker sudo lxd adm systemd-journal; do + if getent group "$forbidden_group" >/dev/null && + id -nG "$DEPLOY_USER" | tr ' ' '\n' | grep -qx "$forbidden_group"; then + gpasswd -d "$DEPLOY_USER" "$forbidden_group" + fi + done + + # Admin — персональная break-glass роль: sudo требует отдельный локальный пароль. + usermod -aG sudo "$ADMIN_USER" + for forbidden_group in docker lxd; do + if getent group "$forbidden_group" >/dev/null && + id -nG "$ADMIN_USER" | tr ' ' '\n' | grep -qx "$forbidden_group"; then + gpasswd -d "$ADMIN_USER" "$forbidden_group" + fi + done +} + +configure_account_passwords() { + step "Блокировка root/deploy и проверка break-glass admin" + if [[ "$LOCK_ACCOUNT_PASSWORDS" != "true" ]]; then + log "LOCK_ACCOUNT_PASSWORDS=false: пароли root/deploy не изменены" + else + passwd --lock root + passwd --lock "$DEPLOY_USER" + fi + local admin_password_status + admin_password_status="$(passwd --status "$ADMIN_USER" | awk '{print $2}')" + if [[ "$HARDEN_SSH" == "true" && "$admin_password_status" != "P" ]]; then + die "Перед HARDEN_SSH=true задайте отдельный sudo-пароль: passwd ${ADMIN_USER}" + fi + if [[ "$admin_password_status" != "P" ]]; then + log "ПРЕДУПРЕЖДЕНИЕ: admin пока без sudo-пароля; выполните passwd ${ADMIN_USER}" + fi +} + +configure_layout() { + step "Создание каталогов и границ владения" + install -d -m 0755 -o root -g root /opt/han-chat + install -d -m 0755 -o root -g root "$DEPLOY_DIR" + install -d -m 0755 -o root -g root /var/lib/han-deploy + install -d -m 0750 -o "$DEPLOY_USER" -g "$DEPLOY_USER" "$INCOMING_DIR" + install -d -m 0700 -o root -g root \ + /etc/han \ + /etc/han/secrets \ + /etc/han/credentials \ + /etc/han-chat + + if [[ -f "${DEPLOY_DIR}/.env" ]]; then + chown root:root "${DEPLOY_DIR}/.env" + chmod 0600 "${DEPLOY_DIR}/.env" + fi +} + +configure_swap() { + step "Настройка swap" + if ((SWAP_SIZE_GB == 0)); then + log "Создание swap отключено" + return + fi + if ! swapon --show=NAME --noheadings | grep -qx '/swapfile'; then + if [[ ! -f /swapfile ]]; then + fallocate -l "${SWAP_SIZE_GB}G" /swapfile + chmod 0600 /swapfile + mkswap /swapfile + fi + swapon /swapfile + fi + grep -q '^/swapfile ' /etc/fstab \ + || printf '/swapfile none swap sw 0 0\n' >>/etc/fstab + printf 'vm.swappiness = 10\n' >/etc/sysctl.d/99-han-chat-vm2-swappiness.conf +} + +configure_sysctl() { + step "Настройка сетевого стека" + cat >/etc/sysctl.d/99-han-chat-vm2-hardening.conf <<'EOF' +net.ipv4.ip_forward = 1 +net.ipv4.tcp_syncookies = 1 +net.ipv4.conf.all.accept_redirects = 0 +net.ipv4.conf.default.accept_redirects = 0 +net.ipv4.conf.all.send_redirects = 0 +net.ipv4.conf.default.send_redirects = 0 +net.ipv4.conf.all.rp_filter = 1 +net.ipv4.conf.default.rp_filter = 1 +net.ipv4.icmp_echo_ignore_broadcasts = 1 +net.ipv4.tcp_fin_timeout = 30 +EOF + sysctl --system >/dev/null +} + +install_docker() { + step "Установка Docker Engine и Compose plugin" + if ! command -v docker >/dev/null 2>&1; then + install -m 0755 -d /etc/apt/keyrings + curl -fsSL https://download.docker.com/linux/ubuntu/gpg \ + | gpg --dearmor --yes -o /etc/apt/keyrings/docker.gpg + chmod a+r /etc/apt/keyrings/docker.gpg + # shellcheck disable=SC1091 + source /etc/os-release + printf '%s\n' \ + "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu ${VERSION_CODENAME} stable" \ + >/etc/apt/sources.list.d/docker.list + apt-get update + apt-get install -y --no-install-recommends \ + docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin + fi + + install -d -m 0755 /etc/docker + cat >/etc/docker/daemon.json <<'EOF' +{ + "live-restore": true, + "log-driver": "json-file", + "log-opts": { + "max-size": "50m", + "max-file": "5" + }, + "userland-proxy": false +} +EOF + systemctl enable --now docker + systemctl restart docker + docker compose version >/dev/null || die "Docker Compose plugin не установлен" + log "$(docker --version)" + log "$(docker compose version)" +} + +for_each_cidr() { + local value=$1 + local callback=$2 + local item + [[ -n "$value" ]] || return 0 + IFS=',' read -ra items <<<"$value" + for item in "${items[@]}"; do + "$callback" "$item" + done +} + +allow_private_api() { + ufw allow from "$1" to any port 8443 proto tcp comment 'HAN VM2 private API' +} + +configure_ufw() { + step "Настройка UFW" + if [[ "$RESET_UFW" == "true" ]]; then + ufw --force reset + else + log "ПРЕДУПРЕЖДЕНИЕ: RESET_UFW=false сохраняет ранее созданные UFW allow rules" + fi + ufw default deny incoming + ufw default allow outgoing + ufw allow "${SSH_PORT}/tcp" comment 'HAN VM2 SSH' + for_each_cidr "$OPS_CIDRS" allow_private_api + for_each_cidr "$VM1_PRIVATE_CIDRS" allow_private_api + ufw allow 80/tcp comment 'HAN VM2 public ACME' + ufw allow 443/tcp comment 'HAN VM2 public Bitrix webhooks' + ufw logging medium + ufw --force enable +} + +configure_fail2ban() { + step "Настройка fail2ban" + cat >/etc/fail2ban/jail.d/han-chat-vm2.local </etc/apt/apt.conf.d/51han-chat-vm2-unattended <<'EOF' +Unattended-Upgrade::Remove-Unused-Dependencies "true"; +Unattended-Upgrade::Automatic-Reboot "false"; +EOF + dpkg-reconfigure -f noninteractive unattended-upgrades + systemctl enable --now unattended-upgrades +} + +configure_docker_firewall() { + step "Фильтрация опубликованных Docker-портов" + cat >/etc/default/han-chat-vm2-docker-firewall </usr/local/sbin/han-chat-vm2-docker-firewall <<'FIREWALL' +#!/usr/bin/env bash +set -Eeuo pipefail +# shellcheck disable=SC1091 +source /etc/default/han-chat-vm2-docker-firewall + +external_if="${EXTERNAL_IF:-}" +if [[ -z "$external_if" ]]; then + external_if="$(ip -4 route show default | awk '{print $5; exit}')" +fi +[[ -n "$external_if" ]] || { + echo "Не удалось определить внешний интерфейс" >&2 + exit 1 +} + +iptables -N HAN-CHAT-VM2 2>/dev/null || true +iptables -F HAN-CHAT-VM2 +iptables -A HAN-CHAT-VM2 -m conntrack --ctstate RELATED,ESTABLISHED -j RETURN +iptables -A HAN-CHAT-VM2 -i lo -j RETURN +iptables -A HAN-CHAT-VM2 -i "$external_if" -p tcp \ + -m conntrack --ctorigdstport 80 -j RETURN +iptables -A HAN-CHAT-VM2 -i "$external_if" -p tcp \ + -m conntrack --ctorigdstport 443 -j RETURN + +allow_private_8443() { + local list=$1 + local cidr + [[ -n "$list" ]] || return 0 + IFS=',' read -ra cidrs <<<"$list" + for cidr in "${cidrs[@]}"; do + iptables -A HAN-CHAT-VM2 -p tcp -s "$cidr" \ + -m conntrack --ctorigdstport 8443 -j RETURN + done +} +allow_private_8443 "$OPS_CIDRS" +allow_private_8443 "$VM1_PRIVATE_CIDRS" +iptables -A HAN-CHAT-VM2 -p tcp \ + -m conntrack --ctorigdstport 8443 -j DROP + +iptables -A HAN-CHAT-VM2 -i "$external_if" -o docker+ -j DROP +iptables -A HAN-CHAT-VM2 -i "$external_if" -o br+ -j DROP +iptables -A HAN-CHAT-VM2 -j RETURN + +while iptables -C DOCKER-USER -j HAN-CHAT-VM2 2>/dev/null; do + iptables -D DOCKER-USER -j HAN-CHAT-VM2 +done +iptables -I DOCKER-USER 1 -j HAN-CHAT-VM2 +FIREWALL + chmod 0750 /usr/local/sbin/han-chat-vm2-docker-firewall + + cat >/etc/systemd/system/han-chat-vm2-docker-firewall.service <<'EOF' +[Unit] +Description=HAN Chat VM2 firewall for Docker published ports +After=docker.service network-online.target +Wants=docker.service network-online.target + +[Service] +Type=oneshot +ExecStart=/usr/local/sbin/han-chat-vm2-docker-firewall +RemainAfterExit=yes + +[Install] +WantedBy=multi-user.target +EOF + install -d -m 0755 /etc/systemd/system/docker.service.d + cat >/etc/systemd/system/docker.service.d/han-chat-vm2-firewall.conf <<'EOF' +[Service] +ExecStartPost=-/usr/local/sbin/han-chat-vm2-docker-firewall +EOF + systemctl daemon-reload + systemctl enable han-chat-vm2-docker-firewall.service + systemctl restart han-chat-vm2-docker-firewall.service +} + +configure_ssh() { + step "Настройка SSH" + [[ -s "/home/${DEPLOY_USER}/.ssh/authorized_keys" ]] \ + || die "Нельзя включить key-only SSH без ключа deploy" + [[ -s "/home/${ADMIN_USER}/.ssh/authorized_keys" ]] \ + || die "Нельзя включить SSH hardening без отдельного ключа admin" + cat >/etc/ssh/sshd_config.d/00-han-chat-vm2.conf <>/etc/ssh/sshd_config.d/00-han-chat-vm2.conf </etc/sudoers.d/han-vm2-deploy </dev/null \ + || die "Некорректный sudoers для deploy" +} + +install_release_helpers_if_possible() { + step "Установка root-owned VM2 helpers и systemd units" + local deployment="${DEPLOY_DIR}/deployment" + local secret_source="${deployment}/secrets" + local safety_sudoers + local tls_group=han-nginx-tls + local tls_gid=11001 + local safety_group=han-message-safety + local safety_gid=10001 + if [[ ! -f "${DEPLOY_DIR}/docker-compose.yml" || + ! -f "${secret_source}/secrets_loader.py" || + ! -f "${secret_source}/han-secrets" ]]; then + log "Активный релиз ещё не установлен; повторите скрипт после root-активации файлов" + return + fi + + if find "$DEPLOY_DIR" -type l -print -quit | grep -q .; then + die "Активный релиз содержит symlink; установка helpers запрещена" + fi + chown -R root:root "$DEPLOY_DIR" + chmod -R go-w "$DEPLOY_DIR" + if getent group "$tls_group" >/dev/null; then + [[ "$(getent group "$tls_group" | cut -d: -f3)" == "$tls_gid" ]] \ + || die "Группа ${tls_group} существует с неожиданным GID" + elif getent group "$tls_gid" >/dev/null; then + die "GID ${tls_gid} уже занят другой группой" + else + groupadd --system --gid "$tls_gid" "$tls_group" + fi + if getent group "$safety_group" >/dev/null; then + [[ "$(getent group "$safety_group" | cut -d: -f3)" == "$safety_gid" ]] \ + || die "Группа ${safety_group} существует с неожиданным GID" + elif getent group "$safety_gid" >/dev/null; then + die "GID ${safety_gid} уже занят другой группой" + else + groupadd --system --gid "$safety_gid" "$safety_group" + fi + install -d -m 0750 -o root -g "$tls_group" /var/lib/han-chat/public-tls + install -d -m 0755 -o root -g root /usr/local/lib/han-secrets-vm2 + install -m 0750 -o root -g root \ + "${secret_source}/secrets_loader.py" \ + /usr/local/lib/han-secrets-vm2/secrets_loader.py + install -m 0750 -o root -g root \ + "${secret_source}/han-secrets" \ + /usr/local/lib/han-secrets-vm2/han-secrets + install -m 0750 -o root -g root \ + "${secret_source}/han-compose" \ + /usr/local/sbin/han-vm2-compose + install -m 0755 -o root -g root \ + "${deployment}/han-message-safety-mode" \ + /usr/local/sbin/han-message-safety-mode + install -d -m 0755 -o root -g root /etc/letsencrypt/renewal-hooks/deploy + install -m 0755 -o root -g root \ + "${deployment}/scripts/ssl-renew-deploy-hook.sh" \ + /etc/letsencrypt/renewal-hooks/deploy/han-processing-nginx + install -m 0644 -o root -g root \ + "${secret_source}/han-secrets-vm2.service" \ + /etc/systemd/system/han-secrets-vm2.service + install -m 0644 -o root -g root \ + "${deployment}/han-processing.service" \ + /etc/systemd/system/han-processing.service + safety_sudoers="$(mktemp)" + sed 's/\r$//' "${deployment}/deploy-message-safety-mode.sudoers" >"$safety_sudoers" + chmod 0440 "$safety_sudoers" + if ! visudo -cf "$safety_sudoers" >/dev/null; then + rm -f "$safety_sudoers" + die "Некорректный исходный sudoers Message Safety mode" + fi + install -m 0440 -o root -g root \ + "$safety_sudoers" \ + /etc/sudoers.d/deploy-message-safety-mode + rm -f "$safety_sudoers" + visudo -cf /etc/sudoers.d/deploy-message-safety-mode >/dev/null \ + || die "Некорректный sudoers Message Safety mode" + + if [[ ! -e /etc/han/secrets/vm2-production-like.selectel.json.example ]]; then + install -m 0600 -o root -g root \ + "${secret_source}/config.example.json" \ + /etc/han/secrets/vm2-production-like.selectel.json.example + fi + if [[ ! -e /etc/han-chat/message-safety-mode.env ]]; then + cat >/etc/han-chat/message-safety-mode.env <<'EOF' +MESSAGE_SAFETY_MOCK_ENABLED=false +MESSAGE_SAFETY_MOCK_TEXT_FREE=false +MESSAGE_SAFETY_MOCK_FILE_FREE=false +EOF + fi + chown root:"$safety_group" /etc/han-chat/message-safety-mode.env + chmod 0640 /etc/han-chat/message-safety-mode.env + chmod 0755 "${deployment}/preflight.sh" + systemctl daemon-reload + log "Helpers и units установлены, но application units не включены и не запущены" +} + +verify() { + step "Проверка host baseline" + local failed=0 + local effective_external_if="${EXTERNAL_IF:-}" + if [[ -z "$effective_external_if" ]]; then + effective_external_if="$(ip -4 route show default | awk '{print $5; exit}')" + fi + systemctl is-active --quiet docker \ + || { log "FAIL: Docker не активен"; failed=1; } + systemctl is-active --quiet fail2ban \ + || { log "FAIL: fail2ban не активен"; failed=1; } + ufw status | grep -q 'Status: active' \ + || { log "FAIL: UFW не активен"; failed=1; } + iptables -C DOCKER-USER -j HAN-CHAT-VM2 2>/dev/null \ + || { log "FAIL: HAN-CHAT-VM2 не подключена к DOCKER-USER"; failed=1; } + iptables -C HAN-CHAT-VM2 -i "$effective_external_if" -p tcp \ + -m conntrack --ctorigdstport 80 -j RETURN 2>/dev/null \ + || { log "FAIL: DOCKER-USER не разрешает original host port 80"; failed=1; } + iptables -C HAN-CHAT-VM2 -i "$effective_external_if" -p tcp \ + -m conntrack --ctorigdstport 443 -j RETURN 2>/dev/null \ + || { log "FAIL: DOCKER-USER не разрешает original host port 443"; failed=1; } + iptables -C HAN-CHAT-VM2 -p tcp \ + -m conntrack --ctorigdstport 8443 -j DROP 2>/dev/null \ + || { log "FAIL: DOCKER-USER не закрывает original host port 8443"; failed=1; } + docker compose version >/dev/null \ + || { log "FAIL: Compose plugin недоступен"; failed=1; } + if id -nG "$DEPLOY_USER" | tr ' ' '\n' | + grep -Eq '^(docker|sudo|lxd|adm|systemd-journal)$'; then + log "FAIL: deploy состоит в запрещённой привилегированной группе" + failed=1 + fi + id -nG "$ADMIN_USER" | tr ' ' '\n' | grep -qx sudo \ + || { log "FAIL: break-glass admin не состоит в sudo"; failed=1; } + if id -nG "$ADMIN_USER" | tr ' ' '\n' | grep -Eq '^(docker|lxd)$'; then + log "FAIL: admin не должен иметь прямой Docker/LXD доступ" + failed=1 + fi + [[ "$(stat -c '%U:%G' "$DEPLOY_DIR")" == "root:root" ]] \ + || { log "FAIL: DEPLOY_DIR не принадлежит root"; failed=1; } + if [[ -f "${DEPLOY_DIR}/docker-compose.yml" ]]; then + [[ "$(getent group han-nginx-tls | cut -d: -f3)" == "11001" ]] \ + || { log "FAIL: группа han-nginx-tls с GID 11001 отсутствует"; failed=1; } + [[ "$(getent group han-message-safety | cut -d: -f3)" == "10001" ]] \ + || { log "FAIL: группа han-message-safety с GID 10001 отсутствует"; failed=1; } + [[ "$(stat -c '%U:%G:%a' /var/lib/han-chat/public-tls)" == \ + "root:han-nginx-tls:750" ]] \ + || { log "FAIL: неверные права public TLS staging"; failed=1; } + [[ "$(stat -c '%U:%G:%a' /etc/han-chat/message-safety-mode.env)" == \ + "root:han-message-safety:640" ]] \ + || { log "FAIL: неверные права Message Safety mode file"; failed=1; } + fi + [[ "$(stat -c '%U:%G' "$INCOMING_DIR")" == "${DEPLOY_USER}:${DEPLOY_USER}" ]] \ + || { log "FAIL: INCOMING_DIR не принадлежит deploy"; failed=1; } + ((failed == 0)) || die "Проверка VM2 baseline не пройдена" + log "VM2 host baseline пройден" +} + +summary() { + step "Подготовка VM2 завершена" + cat </dev/null + +staging=$(mktemp -d "${TLS_DIR}/.renew.XXXXXX") +trap 'rm -rf -- "$staging"' EXIT HUP INT TERM +install -m 0640 -o root -g "$TLS_GROUP" \ + "$lineage/fullchain.pem" "$staging/fullchain.pem" +install -m 0640 -o root -g "$TLS_GROUP" \ + "$lineage/privkey.pem" "$staging/privkey.pem" +mv -f "$staging/fullchain.pem" "$TLS_DIR/fullchain.pem" +mv -f "$staging/privkey.pem" "$TLS_DIR/privkey.pem" +rmdir "$staging" +trap - EXIT HUP INT TERM + +container=$("$COMPOSE" ps --status running --quiet nginx) +[ -n "$container" ] || { + echo "HAN VM2 nginx is not running" >&2 + exit 1 +} + +if ! nginx_test_output=$( + "$COMPOSE" exec -T nginx nginx -t -c /etc/nginx/nginx.conf 2>&1 +); then + printf '%s\n' "$nginx_test_output" >&2 + exit 1 +fi +/usr/bin/docker kill --signal HUP "$container" >/dev/null diff --git a/codebase/services/deployment/secrets/config.example.json b/codebase/services/deployment/secrets/config.example.json new file mode 100644 index 0000000..41df51a --- /dev/null +++ b/codebase/services/deployment/secrets/config.example.json @@ -0,0 +1,95 @@ +{ + "version": 1, + "mode": "selectel", + "runtime_dir": "/run/han-chat/secrets", + "http": { + "timeout_seconds": 10, + "retries": 3, + "max_response_bytes": 1048576 + }, + "selectel": { + "account_id": "", + "username": "han-vm2-secrets-reader", + "project_name": "", + "region": "", + "interface": "public", + "password_file": "selectel-service-user-password" + }, + "secrets": { + "MESSAGE_SAFETY_DATABASE_URL": { + "remote": "vm2/MESSAGE_SAFETY_DATABASE_URL", + "consumers": ["message-safety-api", "message-safety-worker"], + "max_bytes": 4096 + }, + "MESSAGE_SAFETY_CONFIG_ADMIN_DATABASE_URL": { + "remote": "vm2/MESSAGE_SAFETY_CONFIG_ADMIN_DATABASE_URL", + "consumers": ["message-safety-migrate", "message-safety-config"], + "max_bytes": 4096 + }, + "MESSAGE_SAFETY_REDIS_URL": { + "remote": "vm2/MESSAGE_SAFETY_REDIS_URL", + "consumers": ["message-safety-api", "message-safety-worker"], + "max_bytes": 4096 + }, + "MESSAGE_SAFETY_SERVICE_TOKEN": { + "remote": "vm2/MESSAGE_SAFETY_SERVICE_TOKEN", + "consumers": ["message-safety-api"], + "max_bytes": 1024 + }, + "SELECTEL_S3_QUARANTINE_READ_ACCESS_KEY": { + "remote": "vm2/SELECTEL_S3_QUARANTINE_READ_ACCESS_KEY", + "consumers": ["message-safety-worker"], + "max_bytes": 1024 + }, + "SELECTEL_S3_QUARANTINE_READ_SECRET_KEY": { + "remote": "vm2/SELECTEL_S3_QUARANTINE_READ_SECRET_KEY", + "consumers": ["message-safety-worker"], + "max_bytes": 1024 + }, + "VM2_INTERNAL_TLS_CERTIFICATE": { + "remote": "vm2/VM2_INTERNAL_TLS_CERTIFICATE", + "consumers": ["nginx"], + "max_bytes": 16384 + }, + "VM2_INTERNAL_TLS_PRIVATE_KEY": { + "remote": "vm2/VM2_INTERNAL_TLS_PRIVATE_KEY", + "consumers": ["nginx"], + "max_bytes": 16384 + }, + "BITRIX_SYNC_DATABASE_URL": { + "remote": "vm2/BITRIX_SYNC_DATABASE_URL", + "consumers": ["bitrix-sync", "bitrix-sync-worker", "bitrix-sync-reconciliation"], + "max_bytes": 4096 + }, + "BITRIX_SYNC_MIGRATION_DATABASE_URL": { + "remote": "vm2/BITRIX_SYNC_MIGRATION_DATABASE_URL", + "consumers": ["bitrix-sync-migrate"], + "max_bytes": 4096 + }, + "BITRIX_SYNC_CRM_REST_WEBHOOK_URL": { + "remote": "vm2/BITRIX_SYNC_CRM_REST_WEBHOOK_URL", + "consumers": ["bitrix-sync", "bitrix-sync-worker", "bitrix-sync-reconciliation"], + "max_bytes": 4096 + }, + "BITRIX_SYNC_CONTACT_RECEIVER_TOKEN": { + "remote": "vm2/BITRIX_SYNC_CONTACT_RECEIVER_TOKEN", + "consumers": ["bitrix-sync", "bitrix-sync-worker", "bitrix-sync-reconciliation"], + "max_bytes": 1024 + }, + "BITRIX_SYNC_ALERT_RECEIVER_TOKEN": { + "remote": "vm2/BITRIX_SYNC_ALERT_RECEIVER_TOKEN", + "consumers": ["bitrix-sync", "bitrix-sync-worker", "bitrix-sync-reconciliation"], + "max_bytes": 1024 + }, + "BITRIX_SYNC_SERVICE_TOKEN": { + "remote": "vm2/BITRIX_SYNC_SERVICE_TOKEN", + "consumers": ["bitrix-sync", "bitrix-sync-worker", "bitrix-sync-reconciliation"], + "max_bytes": 1024 + }, + "REDIS_SAFETY_ACL": { + "remote": "vm2/REDIS_SAFETY_ACL", + "consumers": ["redis-safety"], + "max_bytes": 4096 + } + } +} diff --git a/codebase/services/deployment/secrets/han-compose b/codebase/services/deployment/secrets/han-compose new file mode 100644 index 0000000..3a9b592 --- /dev/null +++ b/codebase/services/deployment/secrets/han-compose @@ -0,0 +1,10 @@ +#!/bin/sh +set -eu + +DEPLOY_DIR=/opt/han-chat/services +CONFIG_FILE=/opt/han-chat/services/.env +LAUNCHER=/usr/local/lib/han-secrets-vm2/han-secrets + +cd "$DEPLOY_DIR" +exec /usr/bin/python3 "$LAUNCHER" run --config "$CONFIG_FILE" -- \ + /usr/bin/docker compose --env-file "$CONFIG_FILE" "$@" diff --git a/codebase/services/deployment/secrets/han-secrets b/codebase/services/deployment/secrets/han-secrets new file mode 100644 index 0000000..de9110e --- /dev/null +++ b/codebase/services/deployment/secrets/han-secrets @@ -0,0 +1,114 @@ +#!/usr/bin/env python3 +"""Synchronize VM2 runtime secrets, then execute a command with paths only.""" + +from __future__ import annotations + +import argparse +import json +import os +import subprocess +import sys +import tempfile +from pathlib import Path + +from secrets_loader import LoaderError, load_json, run + + +def public_config(path: Path) -> dict[str, str]: + result: dict[str, str] = {} + for number, raw in enumerate(path.read_text(encoding="utf-8").splitlines(), 1): + line = raw.strip() + if not line or line.startswith("#"): + continue + if "=" not in line: + raise LoaderError(f"invalid non-secret config at line {number}") + key, value = line.split("=", 1) + if not key or key in result: + raise LoaderError(f"invalid/duplicate non-secret key at line {number}") + result[key] = value + return result + + +def selected_config(public: dict[str, str], explicit: Path | None) -> tuple[str, Path]: + source = public.get("SECRETS_SOURCE") + if source not in {"selectel", "file"}: + raise LoaderError("SECRETS_SOURCE must explicitly be selectel or file") + if explicit: + return source, explicit + environment = public.get("APP_ENV", "production") + return source, Path(f"/etc/han/secrets/vm2-{environment}.{source}.json") + + +def prepare(config_path: Path, source: str, synchronize: bool) -> dict[str, str]: + document = load_json(config_path) + if document.get("mode") != source: + raise LoaderError("loader mode does not match SECRETS_SOURCE") + runtime = Path(str(document.get("runtime_dir", ""))) + state_path = runtime / "state.json" + if synchronize: + run(config_path) + descriptor, temporary = tempfile.mkstemp(prefix=".state.", dir=runtime) + with os.fdopen(descriptor, "w", encoding="utf-8") as stream: + json.dump( + {"version": 1, "source": source, "loader_config": str(config_path.resolve())}, + stream, + separators=(",", ":"), + ) + stream.write("\n") + stream.flush() + os.fsync(stream.fileno()) + os.chmod(temporary, 0o600) + os.replace(temporary, state_path) + if not state_path.is_file(): + raise LoaderError("runtime secrets are not synchronized") + state = load_json(state_path) + if state != { + "version": 1, + "source": source, + "loader_config": str(config_path.resolve()), + }: + raise LoaderError("runtime secret state does not match selected configuration") + manifest = runtime / "manifest" + entries: dict[str, str] = {} + for line in manifest.read_text(encoding="utf-8").splitlines(): + key, separator, value = line.partition("=") + if not separator or key in entries or not Path(value).is_file(): + raise LoaderError("runtime secret manifest is invalid") + entries[key] = value + if set(entries) != set(document.get("secrets", {})): + raise LoaderError("runtime secret manifest does not match configuration") + child = dict(os.environ) + child["HAN_SECRETS_ACTIVE"] = "1" + child["HAN_RUNTIME_SECRET_DIR"] = str(runtime) + child["HAN_RUNTIME_SECRET_MANIFEST"] = str(manifest) + for key, value in entries.items(): + child[f"{key}_FILE"] = value + return child + + +def main() -> int: + parser = argparse.ArgumentParser() + parser.add_argument("action", choices=("sync", "run")) + parser.add_argument("--config", type=Path, default=Path(".env")) + parser.add_argument("--loader-config", type=Path) + arguments, command = parser.parse_known_args() + if command and command[0] == "--": + command.pop(0) + if arguments.action == "run" and not command: + parser.error("run requires a command after --") + try: + source, config = selected_config(public_config(arguments.config), arguments.loader_config) + child = prepare(config, source, arguments.action == "sync") + except (LoaderError, OSError, ValueError, json.JSONDecodeError) as exc: + print(f"han-secrets-vm2: {exc}", file=sys.stderr) + return 1 + if arguments.action == "sync": + return 0 + if os.name == "nt": + return subprocess.call(command, env=child) + os.execvpe(command[0], command, child) + return 127 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/codebase/services/deployment/secrets/han-secrets-vm2.service b/codebase/services/deployment/secrets/han-secrets-vm2.service new file mode 100644 index 0000000..937cbaf --- /dev/null +++ b/codebase/services/deployment/secrets/han-secrets-vm2.service @@ -0,0 +1,41 @@ +[Unit] +Description=Materialize HAN Processing VM2 service secrets +Wants=network-online.target +After=network-online.target +Before=han-processing.service + +[Service] +Type=oneshot +User=root +Group=root +UMask=0077 +RuntimeDirectory=han-chat/secrets +RuntimeDirectoryMode=0700 +ExecStart=/usr/bin/python3 /usr/local/lib/han-secrets-vm2/han-secrets sync --config /opt/han-chat/services/.env +LoadCredentialEncrypted=selectel-service-user-password:/etc/han/credentials/vm2.selectel-password.cred +RemainAfterExit=yes +StandardOutput=null +StandardError=journal +SyslogIdentifier=han-secrets-vm2 +NoNewPrivileges=yes +PrivateTmp=yes +PrivateDevices=yes +ProtectSystem=strict +ProtectHome=yes +ProtectKernelTunables=yes +ProtectKernelModules=yes +ProtectKernelLogs=yes +ProtectControlGroups=yes +ProtectClock=yes +RestrictRealtime=yes +RestrictSUIDSGID=yes +LockPersonality=yes +MemoryDenyWriteExecute=yes +LimitCORE=0 +SystemCallArchitectures=native +RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 +CapabilityBoundingSet= +AmbientCapabilities= + +[Install] +WantedBy=multi-user.target diff --git a/codebase/services/deployment/secrets/secrets_loader.py b/codebase/services/deployment/secrets/secrets_loader.py new file mode 100644 index 0000000..e3f6803 --- /dev/null +++ b/codebase/services/deployment/secrets/secrets_loader.py @@ -0,0 +1,316 @@ +#!/usr/bin/env python3 +"""Fail-closed VM2 adaptation of the reviewed HAN Selectel secrets loader.""" + +from __future__ import annotations + +import argparse +import base64 +import binascii +import json +import os +import random +import re +import ssl +import stat +import sys +import tempfile +import time +import urllib.error +import urllib.parse +import urllib.request +from pathlib import Path +from typing import Any, Mapping + +IDENTITY_URL = "https://cloud.api.selcloud.ru/identity/v3/auth/tokens" +NAME_RE = re.compile(r"^[A-Z][A-Z0-9_]*$") +CONSUMER_RE = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9_.-]*$") +RETRYABLE = {408, 425, 429, 500, 502, 503, 504} +MAX_CONFIG = 1_048_576 + + +class LoaderError(Exception): + """Expected error whose text contains no provider response or secret value.""" + + +def fail(message: str) -> None: + raise LoaderError(message) + + +def private_file(path: Path, label: str) -> None: + try: + metadata = path.lstat() + except OSError as exc: + fail(f"cannot inspect {label}: {exc.__class__.__name__}") + if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISREG(metadata.st_mode): + fail(f"{label} must be a regular non-symlink file") + if os.name != "nt" and stat.S_IMODE(metadata.st_mode) & 0o077: + fail(f"{label} must not be accessible by group or other users") + + +def read_limited(path: Path, limit: int, label: str) -> bytes: + try: + with path.open("rb") as stream: + value = stream.read(limit + 1) + except OSError as exc: + fail(f"cannot read {label}: {exc.__class__.__name__}") + if len(value) > limit: + fail(f"{label} exceeds configured limit") + return value + + +def object_value(value: Any, label: str) -> dict[str, Any]: + if not isinstance(value, dict): + fail(f"{label} must be an object") + return value + + +def load_json(path: Path) -> dict[str, Any]: + try: + return object_value(json.loads(read_limited(path, MAX_CONFIG, "configuration")), "configuration") + except (UnicodeDecodeError, json.JSONDecodeError): + fail("configuration is not valid UTF-8 JSON") + + +def required_string(value: Mapping[str, Any], key: str, label: str) -> str: + result = value.get(key) + if not isinstance(result, str) or not result: + fail(f"{label}.{key} must be a non-empty string") + return result + + +class NoRedirect(urllib.request.HTTPRedirectHandler): + def redirect_request(self, req: Any, fp: Any, code: int, msg: str, headers: Any, newurl: str) -> None: + return None + + +class Client: + def __init__(self, timeout: float, retries: int, maximum: int, ca_file: str | None) -> None: + context = ssl.create_default_context(cafile=ca_file) + self.opener = urllib.request.build_opener( + urllib.request.HTTPSHandler(context=context), NoRedirect() + ) + self.timeout, self.retries, self.maximum = timeout, retries, maximum + + def request( + self, method: str, url: str, expected: set[int], headers: Mapping[str, str] | None = None, body: bytes | None = None + ) -> tuple[Mapping[str, str], bytes]: + parsed = urllib.parse.urlsplit(url) + if parsed.scheme != "https" or not parsed.netloc or parsed.username or parsed.password: + fail("provider endpoint must be credential-free HTTPS") + request = urllib.request.Request(url, data=body, headers=dict(headers or {}), method=method) + for attempt in range(self.retries + 1): + try: + with self.opener.open(request, timeout=self.timeout) as response: + if int(response.headers.get("Content-Length", 0)) > self.maximum: + fail("provider response exceeds configured limit") + response_body = response.read(self.maximum + 1) + if len(response_body) > self.maximum: + fail("provider response exceeds configured limit") + if response.status not in expected: + fail(f"provider request failed with HTTP {response.status}") + return response.headers, response_body + except urllib.error.HTTPError as exc: + if exc.code not in RETRYABLE or attempt == self.retries: + fail(f"provider request failed with HTTP {exc.code}") + except (urllib.error.URLError, TimeoutError, OSError): + if attempt == self.retries: + fail("provider request failed after retries") + time.sleep(min(8.0, 0.25 * (2**attempt)) * (0.5 + random.random())) + fail("provider request failed") + + +def credential(selectel: Mapping[str, Any], environ: Mapping[str, str]) -> str: + configured = Path(required_string(selectel, "password_file", "selectel")) + if not configured.is_absolute(): + directory = environ.get("CREDENTIALS_DIRECTORY") + if not directory: + fail("relative password_file requires CREDENTIALS_DIRECTORY") + configured = Path(directory) / configured + private_file(configured, "Selectel credential") + try: + value = read_limited(configured, 16_384, "Selectel credential").decode().rstrip("\r\n") + except UnicodeDecodeError: + fail("Selectel credential is not UTF-8") + if not value or "\n" in value or "\r" in value: + fail("Selectel credential must contain one non-empty line") + return value + + +def decode_document(raw: bytes, label: str) -> dict[str, Any]: + try: + return object_value(json.loads(raw.decode()), label) + except (UnicodeDecodeError, json.JSONDecodeError): + fail(f"{label} is not valid JSON") + + +def fetch_values(config: Mapping[str, Any], specs: Mapping[str, Mapping[str, Any]], environ: Mapping[str, str]) -> dict[str, bytes]: + selectel = object_value(config.get("selectel"), "selectel") + http = object_value(config.get("http", {}), "http") + client = Client( + float(http.get("timeout_seconds", 10)), + int(http.get("retries", 3)), + int(http.get("max_response_bytes", MAX_CONFIG)), + selectel.get("ca_file"), + ) + account = required_string(selectel, "account_id", "selectel") + auth = { + "auth": { + "identity": {"methods": ["password"], "password": {"user": { + "name": required_string(selectel, "username", "selectel"), + "domain": {"name": account}, + "password": credential(selectel, environ), + }}}, + "scope": {"project": { + "name": required_string(selectel, "project_name", "selectel"), + "domain": {"name": account}, + }}, + } + } + headers, body = client.request( + "POST", + str(selectel.get("identity_url", IDENTITY_URL)), + {201}, + {"Content-Type": "application/json", "Accept": "application/json"}, + json.dumps(auth, separators=(",", ":")).encode(), + ) + token = headers.get("X-Subject-Token") + identity = decode_document(body, "identity response").get("token") + if not token or not isinstance(identity, dict) or not isinstance(identity.get("project"), dict): + fail("identity token is missing or not project-scoped") + matches: list[str] = [] + for service in identity.get("catalog", []): + if isinstance(service, dict) and service.get("type") == "secrets-manager": + for endpoint in service.get("endpoints", []): + if ( + isinstance(endpoint, dict) + and endpoint.get("region") == selectel.get("region") + and endpoint.get("interface") == selectel.get("interface", "public") + and isinstance(endpoint.get("url"), str) + ): + matches.append(endpoint["url"].rstrip("/")) + if len(matches) != 1: + fail("service catalog has no unique matching Secrets Manager endpoint") + values: dict[str, bytes] = {} + for name, spec in specs.items(): + remote = required_string(spec, "remote", f"secrets.{name}") + _, secret_body = client.request( + "GET", + matches[0] + "/v1/" + urllib.parse.quote(remote, safe=""), + {200}, + {"X-Auth-Token": str(token), "Accept": "application/json"}, + ) + document = decode_document(secret_body, f"secret {name} response") + payload = document.get("version") if isinstance(document.get("version"), dict) else document + encoded = payload.get("value") + try: + value = base64.b64decode(encoded, validate=True) + except (TypeError, ValueError, binascii.Error): + fail(f"secret {name} has invalid encoding") + maximum = int(spec.get("max_bytes", 65_536)) + if not value or len(value) > maximum or b"\x00" in value: + fail(f"secret {name} is empty, unsafe, or exceeds its limit") + values[name] = value + return values + + +def file_values(config: Mapping[str, Any], specs: Mapping[str, Mapping[str, Any]]) -> dict[str, bytes]: + source = Path(required_string(object_value(config.get("file"), "file"), "path", "file")) + if not source.is_absolute(): + fail("file.path must be absolute") + try: + metadata = source.lstat() + except OSError as exc: + fail(f"cannot inspect fallback secret directory: {exc.__class__.__name__}") + if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISDIR(metadata.st_mode): + fail("fallback secret directory must be a non-symlink directory") + if os.name != "nt" and stat.S_IMODE(metadata.st_mode) & 0o077: + fail("fallback secret directory must be mode 0700 or stricter") + expected = set(specs) + actual = {entry.name for entry in source.iterdir()} + if actual != expected: + fail("fallback secret directory does not exactly match configured keys") + values: dict[str, bytes] = {} + for name, spec in specs.items(): + path = source / name + private_file(path, f"fallback secret {name}") + value = read_limited(path, int(spec.get("max_bytes", 65_536)), f"fallback secret {name}") + if not value or b"\x00" in value: + fail(f"fallback secret {name} is empty or unsafe") + values[name] = value + return values + + +def materialize(runtime: Path, specs: Mapping[str, Mapping[str, Any]], values: Mapping[str, bytes]) -> list[str]: + runtime.mkdir(parents=True, exist_ok=True, mode=0o700) + if runtime.is_symlink(): + fail("runtime directory must not be a symlink") + os.chmod(runtime, 0o700) + paths: dict[str, Path] = {} + for name, value in values.items(): + descriptor, temporary = tempfile.mkstemp(prefix=f".{name}.", dir=runtime) + temporary_path = Path(temporary) + with os.fdopen(descriptor, "wb") as stream: + stream.write(value) + stream.flush() + os.fsync(stream.fileno()) + os.chmod(temporary_path, 0o444) + destination = runtime / name + os.replace(temporary_path, destination) + paths[name] = destination + consumers = sorted({consumer for spec in specs.values() for consumer in spec["consumers"]}) + for consumer in consumers: + lines = [ + f'{name}_FILE="{paths[name].resolve()}"\n' + for name, spec in sorted(specs.items()) + if consumer in spec["consumers"] + ] + destination = runtime / f"{consumer}.env" + destination.write_text("".join(lines), encoding="utf-8") + os.chmod(destination, 0o600) + manifest = runtime / "manifest" + manifest.write_text("".join(f"{name}={path.resolve()}\n" for name, path in sorted(paths.items())), encoding="utf-8") + os.chmod(manifest, 0o600) + return consumers + + +def run(config_path: Path, environ: Mapping[str, str] | None = None) -> list[str]: + os.umask(0o077) + config = load_json(config_path) + if config.get("version") != 1 or config.get("mode") not in {"selectel", "file"}: + fail("configuration version/mode is invalid") + runtime = Path(required_string(config, "runtime_dir", "configuration")) + if not runtime.is_absolute(): + fail("runtime_dir must be absolute") + raw_specs = object_value(config.get("secrets"), "secrets") + specs: dict[str, Mapping[str, Any]] = {} + for name, spec_value in raw_specs.items(): + spec = object_value(spec_value, f"secrets.{name}") + consumers = spec.get("consumers") + if ( + not NAME_RE.fullmatch(name) + or not isinstance(consumers, list) + or not consumers + or any(not isinstance(item, str) or not CONSUMER_RE.fullmatch(item) for item in consumers) + ): + fail("secret name or consumer list is invalid") + specs[name] = spec + environment = os.environ if environ is None else environ + values = fetch_values(config, specs, environment) if config["mode"] == "selectel" else file_values(config, specs) + return materialize(runtime, specs, values) + + +def main() -> int: + parser = argparse.ArgumentParser() + parser.add_argument("--config", required=True, type=Path) + args = parser.parse_args() + try: + consumers = run(args.config) + except (LoaderError, OSError, ValueError) as exc: + print(f"secrets-loader: {exc}", file=sys.stderr) + return 1 + print(f"secrets-loader: materialized {len(consumers)} VM2 consumer scopes", file=sys.stderr) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/codebase/services/docker-compose.yml b/codebase/services/docker-compose.yml new file mode 100644 index 0000000..fd5301c --- /dev/null +++ b/codebase/services/docker-compose.yml @@ -0,0 +1,465 @@ +name: han-processing + +x-hardening: &hardening + read_only: true + security_opt: + - no-new-privileges:true + cap_drop: + - ALL + restart: unless-stopped + +x-postgres-ca-volume: &postgres-ca-volume + type: bind + source: ${PG_CA_HOST_PATH:?set PostgreSQL CA host path} + target: /run/config/postgresql-ca.pem + read_only: true + +x-message-safety-environment: &message-safety-environment + APP_ENV: ${APP_ENV:?set APP_ENV} + MESSAGE_SAFETY_HOST: ${MESSAGE_SAFETY_HOST:-0.0.0.0} + MESSAGE_SAFETY_PORT: ${MESSAGE_SAFETY_PORT:-8080} + MESSAGE_SAFETY_WORKER_CONCURRENCY: ${MESSAGE_SAFETY_WORKER_CONCURRENCY:-5} + MESSAGE_SAFETY_DNS_RESOLVERS: ${MESSAGE_SAFETY_DNS_RESOLVERS:?set trusted DNS resolvers} + MESSAGE_SAFETY_CLAMAV_HOST: ${MESSAGE_SAFETY_CLAMAV_HOST:-clamd} + MESSAGE_SAFETY_CLAMAV_PORT: ${MESSAGE_SAFETY_CLAMAV_PORT:-3310} + MESSAGE_SAFETY_ARTIFACTS_DIR: ${MESSAGE_SAFETY_ARTIFACTS_DIR:-/app/app/artifacts} + MESSAGE_SAFETY_MODE_FILE: /etc/han-chat/message-safety-mode.env + PG_CA_FILE: /run/config/postgresql-ca.pem + SELECTEL_S3_ENDPOINT_URL: ${SELECTEL_S3_ENDPOINT_URL:?set S3 endpoint} + SELECTEL_S3_BUCKET_QUARANTINE: ${SELECTEL_S3_BUCKET_QUARANTINE:?set quarantine bucket} + OTEL_EXPORTER_OTLP_ENDPOINT: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://otel-collector:4317} + MESSAGE_SAFETY_DATABASE_URL_FILE: /run/secrets/message_safety_database_url + MESSAGE_SAFETY_REDIS_URL_FILE: /run/secrets/message_safety_redis_url + MESSAGE_SAFETY_SERVICE_TOKEN_FILE: /run/secrets/message_safety_service_token + SELECTEL_S3_QUARANTINE_READ_ACCESS_KEY_FILE: /run/secrets/s3_quarantine_read_access_key + SELECTEL_S3_QUARANTINE_READ_SECRET_KEY_FILE: /run/secrets/s3_quarantine_read_secret_key + +x-bitrix-sync-environment: &bitrix-sync-environment + APP_ENV: ${APP_ENV:?set APP_ENV} + BITRIX_SYNC_ENABLED: ${BITRIX_SYNC_ENABLED:-false} + BITRIX_SYNC_MODE: ${BITRIX_SYNC_MODE:-disabled} + BITRIX_SYNC_PORTAL_HOST: ${BITRIX_SYNC_PORTAL_HOST:?set approved portal} + BITRIX_SYNC_PORTAL_MEMBER_ID: ${BITRIX_SYNC_PORTAL_MEMBER_ID:?set member id} + BITRIX_SYNC_PUBLIC_BASE_URL: ${BITRIX_SYNC_PUBLIC_BASE_URL:?set public base URL} + BITRIX_SYNC_CONTACT_USER_ID_FIELD: ${BITRIX_SYNC_CONTACT_USER_ID_FIELD:?set contact field} + BITRIX_SYNC_CONTACT_REGISTERED_FIELD: ${BITRIX_SYNC_CONTACT_REGISTERED_FIELD:?set registration field} + BITRIX_SYNC_CONTACT_CITIZENSHIP_FIELD: ${BITRIX_SYNC_CONTACT_CITIZENSHIP_FIELD:?set citizenship field} + BITRIX_SYNC_WEBHOOK_ALLOWED_CIDRS: ${BITRIX_WEBHOOK_ALLOWED_CIDRS:-} + BITRIX_SYNC_HTTP_TIMEOUT_SEC: ${BITRIX_SYNC_HTTP_TIMEOUT_SEC:-10} + BITRIX_SYNC_DB_POOL_SIZE: ${BITRIX_SYNC_DB_POOL_SIZE:-5} + PG_CA_FILE: /run/config/postgresql-ca.pem + OTEL_EXPORTER_OTLP_ENDPOINT: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://otel-collector:4317} + BITRIX_SYNC_DATABASE_URL_FILE: /run/secrets/bitrix_sync_database_url + BITRIX_SYNC_CRM_REST_WEBHOOK_URL_FILE: /run/secrets/bitrix_sync_crm_rest_webhook_url + BITRIX_SYNC_CONTACT_RECEIVER_TOKEN_FILE: /run/secrets/bitrix_sync_contact_receiver_token + BITRIX_SYNC_ALERT_RECEIVER_TOKEN_FILE: /run/secrets/bitrix_sync_alert_receiver_token + BITRIX_SYNC_SERVICE_TOKEN_FILE: /run/secrets/bitrix_sync_service_token + +services: + nginx: + <<: *hardening + image: ${NGINX_IMAGE:?set immutable nginx image digest} + user: "101:11001" + environment: + PROCESSING_PUBLIC_HOST: ${PROCESSING_PUBLIC_HOST:?set PROCESSING_PUBLIC_HOST} + MESSAGE_SAFETY_UPSTREAM_HOST: message-safety-api + BITRIX_SYNC_UPSTREAM_HOST: bitrix-sync + ports: + - "80:8080" + - "443:8444" + - "${PROCESSING_PRIVATE_BIND_ADDRESS:?set private bind IP}:8443:8443" + volumes: + - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro + - ./nginx/templates:/etc/nginx/templates:ro + - ./nginx/allowlists:/etc/nginx/allowlists:ro + - /var/lib/han-chat/public-tls:/run/public-tls:ro + - /var/lib/han-chat/acme:/var/www/certbot:ro + secrets: + - source: internal_tls_certificate + target: internal_tls_certificate + mode: 0444 + - source: internal_tls_private_key + target: internal_tls_private_key + mode: 0444 + tmpfs: + - /tmp:rw,noexec,nosuid,nodev,size=64m + - /var/cache/nginx:rw,noexec,nosuid,nodev,size=64m,uid=101,gid=11001,mode=0750 + - /var/run:rw,noexec,nosuid,nodev,size=8m,uid=101,gid=11001,mode=0750 + - /etc/nginx/conf.d:rw,noexec,nosuid,nodev,size=8m,uid=101,gid=11001,mode=0750 + ulimits: + nofile: + soft: 4096 + hard: 4096 + networks: [public, backend] + depends_on: + message-safety-api: + condition: service_started + bitrix-sync: + condition: service_started + healthcheck: + test: ["CMD", "nginx", "-t", "-q", "-c", "/etc/nginx/nginx.conf"] + interval: 15s + timeout: 3s + retries: 3 + start_period: 10s + pids_limit: 200 + mem_limit: 256m + cpus: 1.0 + + redis-safety: + <<: *hardening + image: ${REDIS_IMAGE:?set immutable Redis image digest} + user: "999:999" + command: ["redis-server", "/usr/local/etc/redis/redis.conf"] + volumes: + - ./redis/redis.conf:/usr/local/etc/redis/redis.conf:ro + - redis-safety-data:/data + secrets: + - source: redis_safety_acl + target: redis-safety.acl + mode: 0444 + networks: [backend] + expose: ["6379"] + healthcheck: + test: ["CMD", "redis-cli", "--no-auth-warning", "PING"] + interval: 15s + timeout: 3s + retries: 3 + pids_limit: 100 + mem_limit: 640m + cpus: 1.0 + + clamd: + <<: *hardening + image: ${CLAMAV_IMAGE:?set immutable ClamAV image digest} + entrypoint: ["/init-unprivileged"] + user: "100:101" + command: ["clamd", "--foreground=true"] + volumes: + - clamav-signatures:/var/lib/clamav:ro + - clamav-runtime:/run/clamav + tmpfs: + - /tmp:rw,noexec,nosuid,nodev,size=64m + - /var/log/clamav:rw,noexec,nosuid,nodev,size=32m,uid=100,gid=101,mode=0750 + networks: [backend] + expose: ["3310"] + healthcheck: + test: ["CMD-SHELL", "clamdscan --ping 1 >/dev/null 2>&1"] + interval: 30s + timeout: 5s + retries: 5 + start_period: 60s + pids_limit: 300 + mem_limit: 2g + cpus: 2.0 + + freshclam: + <<: *hardening + image: ${CLAMAV_IMAGE:?set immutable ClamAV image digest} + entrypoint: ["/init-unprivileged"] + user: "100:101" + command: ["freshclam", "--daemon", "--foreground", "--checks=12"] + volumes: + - clamav-signatures:/var/lib/clamav + - clamav-runtime:/run/clamav + tmpfs: + - /tmp:rw,noexec,nosuid,nodev,size=64m + - /var/log/clamav:rw,noexec,nosuid,nodev,size=32m,uid=100,gid=101,mode=0750 + healthcheck: + disable: true + networks: [signature-egress] + pids_limit: 100 + mem_limit: 256m + cpus: 0.5 + + otel-queue-init: + <<: *hardening + image: ${REDIS_IMAGE:?set immutable Redis image digest} + entrypoint: ["sh", "-c"] + command: ["chown 10001:10001 /queue && chmod 0700 /queue"] + user: "0:0" + restart: "no" + network_mode: none + volumes: + - otel-queue:/queue + cap_add: + - CHOWN + - FOWNER + pids_limit: 20 + mem_limit: 32m + cpus: 0.1 + + otel-collector: + <<: *hardening + image: ${OTEL_COLLECTOR_IMAGE:?set immutable Collector image digest} + user: "10001:10001" + command: ["--config=/etc/otelcol-contrib/config.yaml"] + environment: + APP_ENV: ${APP_ENV:?set APP_ENV} + RELEASE_VERSION: ${RELEASE_VERSION:?set RELEASE_VERSION} + OTEL_REMOTE_ENDPOINT: ${OTEL_REMOTE_ENDPOINT:?set private OTLP endpoint} + OTEL_REMOTE_TLS_INSECURE: ${OTEL_REMOTE_TLS_INSECURE:?set OTLP TLS mode} + volumes: + - ./observability/otel-collector.yaml:/etc/otelcol-contrib/config.yaml:ro + - otel-queue:/var/lib/otelcol/queue + networks: + observability: {} + telemetry-egress: + gw_priority: 1 + depends_on: + otel-queue-init: + condition: service_completed_successfully + expose: ["4317", "4318"] + healthcheck: + test: ["CMD", "/otelcol-contrib", "components"] + interval: 30s + timeout: 5s + retries: 3 + pids_limit: 200 + mem_limit: 512m + cpus: 1.0 + + message-safety-api: + <<: *hardening + image: ${MESSAGE_SAFETY_IMAGE:?set immutable message-safety image digest} + command: ["message-safety"] + user: "10001:10001" + environment: + <<: *message-safety-environment + MESSAGE_SAFETY_PROCESS_ROLE: api + volumes: + - /etc/han-chat/message-safety-mode.env:/etc/han-chat/message-safety-mode.env:ro + - *postgres-ca-volume + tmpfs: + - /tmp:rw,noexec,nosuid,nodev,size=64m + networks: + backend: {} + observability: {} + safety-egress: + gw_priority: 1 + expose: ["8080"] + secrets: + - message_safety_database_url + - message_safety_redis_url + - message_safety_service_token + depends_on: + redis-safety: + condition: service_healthy + healthcheck: + test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/live',timeout=2)"] + interval: 15s + timeout: 3s + retries: 3 + start_period: 20s + pids_limit: 200 + mem_limit: 512m + cpus: 1.0 + + message-safety-worker: + <<: *hardening + image: ${MESSAGE_SAFETY_IMAGE:?set immutable message-safety image digest} + command: ["message-safety-worker"] + user: "10001:10001" + environment: + <<: *message-safety-environment + MESSAGE_SAFETY_PROCESS_ROLE: worker + volumes: + - /etc/han-chat/message-safety-mode.env:/etc/han-chat/message-safety-mode.env:ro + - *postgres-ca-volume + tmpfs: + - /tmp:rw,noexec,nosuid,nodev,size=256m + networks: + backend: {} + observability: {} + safety-egress: + gw_priority: 1 + secrets: + - message_safety_database_url + - message_safety_redis_url + - s3_quarantine_read_access_key + - s3_quarantine_read_secret_key + depends_on: + redis-safety: + condition: service_healthy + clamd: + condition: service_healthy + pids_limit: 400 + mem_limit: 2g + cpus: 2.0 + + message-safety-migrate: + <<: *hardening + image: ${MESSAGE_SAFETY_IMAGE:?set immutable message-safety image digest} + entrypoint: ["alembic"] + command: ["upgrade", "head"] + user: "10001:10001" + restart: "no" + profiles: ["ops"] + environment: + MESSAGE_SAFETY_CONFIG_ADMIN_DATABASE_URL_FILE: /run/secrets/message_safety_config_admin_database_url + PG_CA_FILE: /run/config/postgresql-ca.pem + volumes: + - *postgres-ca-volume + networks: + safety-egress: + gw_priority: 1 + secrets: + - message_safety_config_admin_database_url + tmpfs: + - /tmp:rw,noexec,nosuid,nodev,size=32m + pids_limit: 100 + mem_limit: 256m + cpus: 0.5 + + bitrix-sync: + <<: *hardening + image: ${BITRIX_SYNC_IMAGE:?set immutable bitrix-sync image digest} + command: ["han-bitrix-sync-api"] + user: "10001:10001" + environment: *bitrix-sync-environment + volumes: + - *postgres-ca-volume + networks: + backend: {} + observability: {} + bitrix-egress: + gw_priority: 1 + expose: ["8080"] + secrets: + - bitrix_sync_database_url + - bitrix_sync_crm_rest_webhook_url + - bitrix_sync_contact_receiver_token + - bitrix_sync_alert_receiver_token + - bitrix_sync_service_token + tmpfs: + - /tmp:rw,noexec,nosuid,nodev,size=32m + healthcheck: + test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/live',timeout=2)"] + interval: 15s + timeout: 3s + retries: 3 + start_period: 20s + pids_limit: 200 + mem_limit: 384m + cpus: 1.0 + + bitrix-sync-worker: + <<: *hardening + image: ${BITRIX_SYNC_IMAGE:?set immutable bitrix-sync image digest} + command: ["han-bitrix-sync-worker"] + user: "10001:10001" + environment: *bitrix-sync-environment + volumes: + - *postgres-ca-volume + networks: + observability: {} + bitrix-egress: + gw_priority: 1 + secrets: + - bitrix_sync_database_url + - bitrix_sync_crm_rest_webhook_url + - bitrix_sync_contact_receiver_token + - bitrix_sync_alert_receiver_token + - bitrix_sync_service_token + tmpfs: + - /tmp:rw,noexec,nosuid,nodev,size=32m + pids_limit: 200 + mem_limit: 512m + cpus: 1.0 + + bitrix-sync-reconciliation: + <<: *hardening + image: ${BITRIX_SYNC_IMAGE:?set immutable bitrix-sync image digest} + command: ["han-bitrix-sync-reconciliation"] + user: "10001:10001" + environment: *bitrix-sync-environment + volumes: + - *postgres-ca-volume + networks: + observability: {} + bitrix-egress: + gw_priority: 1 + secrets: + - bitrix_sync_database_url + - bitrix_sync_crm_rest_webhook_url + - bitrix_sync_contact_receiver_token + - bitrix_sync_alert_receiver_token + - bitrix_sync_service_token + tmpfs: + - /tmp:rw,noexec,nosuid,nodev,size=32m + pids_limit: 150 + mem_limit: 384m + cpus: 0.75 + + bitrix-sync-migrate: + <<: *hardening + image: ${BITRIX_SYNC_IMAGE:?set immutable bitrix-sync image digest} + entrypoint: ["alembic"] + command: ["upgrade", "head"] + user: "10001:10001" + restart: "no" + profiles: ["ops"] + environment: + BITRIX_SYNC_MIGRATION_DATABASE_URL_FILE: /run/secrets/bitrix_sync_migration_database_url + PG_CA_FILE: /run/config/postgresql-ca.pem + volumes: + - *postgres-ca-volume + networks: + bitrix-egress: + gw_priority: 1 + secrets: + - bitrix_sync_migration_database_url + tmpfs: + - /tmp:rw,noexec,nosuid,nodev,size=32m + pids_limit: 100 + mem_limit: 256m + cpus: 0.5 + +networks: + public: + backend: + internal: true + observability: + internal: true + safety-egress: + bitrix-egress: + signature-egress: + telemetry-egress: + +volumes: + redis-safety-data: + clamav-signatures: + clamav-runtime: + otel-queue: + +secrets: + message_safety_database_url: + file: /run/han-chat/secrets/MESSAGE_SAFETY_DATABASE_URL + message_safety_config_admin_database_url: + file: /run/han-chat/secrets/MESSAGE_SAFETY_CONFIG_ADMIN_DATABASE_URL + message_safety_redis_url: + file: /run/han-chat/secrets/MESSAGE_SAFETY_REDIS_URL + message_safety_service_token: + file: /run/han-chat/secrets/MESSAGE_SAFETY_SERVICE_TOKEN + s3_quarantine_read_access_key: + file: /run/han-chat/secrets/SELECTEL_S3_QUARANTINE_READ_ACCESS_KEY + s3_quarantine_read_secret_key: + file: /run/han-chat/secrets/SELECTEL_S3_QUARANTINE_READ_SECRET_KEY + internal_tls_certificate: + file: /run/han-chat/secrets/VM2_INTERNAL_TLS_CERTIFICATE + internal_tls_private_key: + file: /run/han-chat/secrets/VM2_INTERNAL_TLS_PRIVATE_KEY + bitrix_sync_database_url: + file: /run/han-chat/secrets/BITRIX_SYNC_DATABASE_URL + bitrix_sync_migration_database_url: + file: /run/han-chat/secrets/BITRIX_SYNC_MIGRATION_DATABASE_URL + bitrix_sync_crm_rest_webhook_url: + file: /run/han-chat/secrets/BITRIX_SYNC_CRM_REST_WEBHOOK_URL + bitrix_sync_contact_receiver_token: + file: /run/han-chat/secrets/BITRIX_SYNC_CONTACT_RECEIVER_TOKEN + bitrix_sync_alert_receiver_token: + file: /run/han-chat/secrets/BITRIX_SYNC_ALERT_RECEIVER_TOKEN + bitrix_sync_service_token: + file: /run/han-chat/secrets/BITRIX_SYNC_SERVICE_TOKEN + redis_safety_acl: + file: /run/han-chat/secrets/REDIS_SAFETY_ACL diff --git a/codebase/services/message-safety/Dockerfile b/codebase/services/message-safety/Dockerfile new file mode 100644 index 0000000..8e76142 --- /dev/null +++ b/codebase/services/message-safety/Dockerfile @@ -0,0 +1,22 @@ +FROM python:3.12.11-slim-bookworm AS builder +ENV PIP_DISABLE_PIP_VERSION_CHECK=1 PIP_NO_CACHE_DIR=1 +WORKDIR /build +COPY pyproject.toml . +COPY app ./app +RUN python -m venv /venv && /venv/bin/pip install --upgrade pip && /venv/bin/pip install . + +FROM python:3.12.11-slim-bookworm +ENV PATH=/venv/bin:$PATH PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 +RUN groupadd --gid 10001 safety && useradd --uid 10001 --gid safety --no-create-home safety +COPY --from=builder /venv /venv +WORKDIR /app +COPY --chown=10001:10001 app ./app +COPY --chown=10001:10001 alembic ./alembic +COPY --chown=10001:10001 alembic.ini openapi.yaml ./ +COPY --chmod=0555 entrypoint.sh /usr/local/bin/message-safety-entrypoint +RUN sed -i 's/\r$//' /usr/local/bin/message-safety-entrypoint \ + && /bin/sh -n /usr/local/bin/message-safety-entrypoint +USER 10001:10001 +EXPOSE 8080 +ENTRYPOINT ["message-safety-entrypoint"] +CMD ["message-safety"] diff --git a/codebase/services/message-safety/README.md b/codebase/services/message-safety/README.md new file mode 100644 index 0000000..c3319a8 --- /dev/null +++ b/codebase/services/message-safety/README.md @@ -0,0 +1,59 @@ +# HAN Message Safety v2 + +Production-oriented internal FastAPI service for deterministic text, URL and quarantined-file +safety checks. PostgreSQL is the durable source of truth for idempotency, tasks, leases, fencing, +caches, audit and immutable config snapshots. Redis is intentionally optional and may only +accelerate hot-cache/rate/wakeup paths. + +## Local verification + +Python 3.12 is required. These commands do not start services: + +```sh +python -m pip install -e ".[dev]" +pytest +ruff check . +message-safety-config validate app/artifacts/seed-config.yaml +``` + +Migrations and config administration require +`MESSAGE_SAFETY_CONFIG_ADMIN_DATABASE_URL_FILE`. Runtime secrets are accepted only through +`*_FILE`; the entrypoint rejects missing/empty files without printing their values. + +```sh +alembic upgrade head +message-safety-config create app/artifacts/seed-config.yaml --version 1 --actor migration +message-safety-config activate --version 1 --approved-by security-owner +``` + +## Deployment boundary + +`docker-compose.fragment.yml` is an include fragment for the root VM2 Compose. It publishes no +host port, runs API and worker as UID 10001 with a read-only filesystem, drops all capabilities, +and mounts only service-specific secret files. The root project owns networks/secrets and the +root-owned emergency mode file. + +## External release gates + +The following cannot be proven by repository-only tests and must remain fail-closed until the +target environment verifies them: + +- Selectel S3 supports version-specific `GetObject`, signed conditional ETag behavior, bucket + versioning, checksum metadata, virtual-host addressing and a read-only IAM policy without + list/write/delete. +- ClamAV engine/signature metadata is supplied to readiness and task cache keys; freshclam + activate/reload, signature-age alarms and clean/EICAR/malformed corpora pass on VM2. +- HEIF native decoding and PDF parser sandbox resource limits pass the approved corpus. The + in-process detector is bounded by 5 MiB and validates active/encrypted PDF markers, but OS-level + CPU/memory/wall-time isolation must be enforced by the worker container and target runtime. +- Managed PostgreSQL role grants prove runtime cannot migrate or activate config, while the + config-admin role can; migration constraint, concurrent activation, lease and fencing tests run + against PostgreSQL (not SQLite). +- Trusted resolver, DNS rebinding corpus, S3 canary and worker heartbeat are wired into production + readiness probes. +- Image dependencies are resolved to a reviewed lock/SBOM and the final image is pinned by digest + in the root Compose release manifest. +- Target load gates (10 text checks/s, 2 file checks/s, 100 pending tasks, five worker slots) and + privacy/log redaction are verified in production-like infrastructure. + +No HTTP fetch, redirect following or rendering of user-provided URLs exists in this service. diff --git a/codebase/services/message-safety/alembic.ini b/codebase/services/message-safety/alembic.ini new file mode 100644 index 0000000..43d8236 --- /dev/null +++ b/codebase/services/message-safety/alembic.ini @@ -0,0 +1,30 @@ +[alembic] +script_location = alembic +prepend_sys_path = . +sqlalchemy.url = postgresql+asyncpg://invalid/invalid + +[loggers] +keys = root,sqlalchemy,alembic +[handlers] +keys = console +[formatters] +keys = generic +[logger_root] +level = WARN +handlers = console +qualname = +[logger_sqlalchemy] +level = WARN +handlers = +qualname = sqlalchemy.engine +[logger_alembic] +level = INFO +handlers = +qualname = alembic +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic +[formatter_generic] +format = %(levelname)-5.5s [%(name)s] %(message)s diff --git a/codebase/services/message-safety/alembic/env.py b/codebase/services/message-safety/alembic/env.py new file mode 100644 index 0000000..ed8b65e --- /dev/null +++ b/codebase/services/message-safety/alembic/env.py @@ -0,0 +1,50 @@ +from __future__ import annotations + +import asyncio + +from sqlalchemy import pool +from sqlalchemy.ext.asyncio import async_engine_from_config + +from alembic import context +from app.db import Base, postgres_ssl_context +from app.settings import _secret + +config = context.config +target_metadata = Base.metadata + + +def offline() -> None: + context.configure( + url=_secret("MESSAGE_SAFETY_CONFIG_ADMIN_DATABASE_URL"), + target_metadata=target_metadata, + literal_binds=True, + dialect_opts={"paramstyle": "named"}, + ) + with context.begin_transaction(): + context.run_migrations() + + +async def online() -> None: + section = config.get_section(config.config_ini_section) or {} + section["sqlalchemy.url"] = _secret("MESSAGE_SAFETY_CONFIG_ADMIN_DATABASE_URL") + engine = async_engine_from_config( + section, + prefix="sqlalchemy.", + poolclass=pool.NullPool, + connect_args={"ssl": postgres_ssl_context()}, + ) + async with engine.connect() as connection: + + def migrate(conn) -> None: + context.configure(connection=conn, target_metadata=target_metadata) + with context.begin_transaction(): + context.run_migrations() + + await connection.run_sync(migrate) + await engine.dispose() + + +if context.is_offline_mode(): + offline() +else: + asyncio.run(online()) diff --git a/codebase/services/message-safety/alembic/versions/0001_message_safety_v2.py b/codebase/services/message-safety/alembic/versions/0001_message_safety_v2.py new file mode 100644 index 0000000..f1a32a6 --- /dev/null +++ b/codebase/services/message-safety/alembic/versions/0001_message_safety_v2.py @@ -0,0 +1,63 @@ +"""message safety v2 normative schema + +Revision ID: 0001_message_safety_v2 +""" + +from alembic import op +from app.db import Base + +revision = "0001_message_safety_v2" +down_revision = None +branch_labels = None +depends_on = None + + +def upgrade() -> None: + op.execute("CREATE SCHEMA IF NOT EXISTS message_safety") + Base.metadata.create_all(bind=op.get_bind()) + op.execute( + """ + CREATE OR REPLACE FUNCTION message_safety.guard_config_immutable() + RETURNS trigger LANGUAGE plpgsql AS $$ + BEGIN + IF OLD.version IS DISTINCT FROM NEW.version + OR OLD.schema_version IS DISTINCT FROM NEW.schema_version + OR OLD.config IS DISTINCT FROM NEW.config + OR OLD.config_sha256 IS DISTINCT FROM NEW.config_sha256 THEN + RAISE EXCEPTION 'immutable config fields cannot be changed'; + END IF; + RETURN NEW; + END $$; + """ + ) + op.execute( + """ + CREATE TRIGGER config_immutable + BEFORE UPDATE ON message_safety.config_versions + FOR EACH ROW EXECUTE FUNCTION message_safety.guard_config_immutable(); + """ + ) + op.execute( + """ + CREATE OR REPLACE FUNCTION message_safety.guard_terminal_task() + RETURNS trigger LANGUAGE plpgsql AS $$ + BEGIN + IF OLD.status IN ('allowed','denied','failed') + AND ROW(OLD.*) IS DISTINCT FROM ROW(NEW.*) THEN + RAISE EXCEPTION 'terminal safety task is immutable'; + END IF; + RETURN NEW; + END $$; + """ + ) + op.execute( + """ + CREATE TRIGGER task_terminal_immutable + BEFORE UPDATE ON message_safety.safety_tasks + FOR EACH ROW EXECUTE FUNCTION message_safety.guard_terminal_task(); + """ + ) + + +def downgrade() -> None: + op.execute("DROP SCHEMA message_safety CASCADE") diff --git a/codebase/services/message-safety/app/__init__.py b/codebase/services/message-safety/app/__init__.py new file mode 100644 index 0000000..3a530f4 --- /dev/null +++ b/codebase/services/message-safety/app/__init__.py @@ -0,0 +1 @@ +"""HAN Message Safety v2.""" diff --git a/codebase/services/message-safety/app/adapters.py b/codebase/services/message-safety/app/adapters.py new file mode 100644 index 0000000..79d2599 --- /dev/null +++ b/codebase/services/message-safety/app/adapters.py @@ -0,0 +1,75 @@ +from __future__ import annotations + +import asyncio +import ipaddress +from collections.abc import AsyncIterator + +import boto3 +import dns.asyncresolver +from botocore.config import Config +from botocore.exceptions import BotoCoreError, ClientError + +from app.contracts import Attachment +from app.file_pipeline import DependencyFailure, ObjectChanged +from app.url_policy import DnsError, DnsNxDomain + + +class TrustedDnsResolver: + def __init__(self, nameservers: list[str]) -> None: + self._resolver = dns.asyncresolver.Resolver(configure=not nameservers) + if nameservers: + self._resolver.nameservers = nameservers + + async def resolve( + self, hostname: str + ) -> tuple[ipaddress.IPv4Address | ipaddress.IPv6Address, ...]: + found: list[ipaddress.IPv4Address | ipaddress.IPv6Address] = [] + try: + for kind in ("A", "AAAA"): + try: + answer = await self._resolver.resolve(hostname, kind, lifetime=1.0) + found.extend(ipaddress.ip_address(item.address) for item in answer) + except dns.resolver.NoAnswer: + pass + except dns.resolver.NXDOMAIN as exc: + raise DnsNxDomain from exc + except dns.exception.DNSException as exc: + raise DnsError from exc + if not found: + raise DnsNxDomain + return tuple(found) + + +class S3VersionReader: + def __init__(self, endpoint_url: str, bucket: str, access_key: str, secret_key: str) -> None: + self.bucket = bucket + self.client = boto3.client( + "s3", + endpoint_url=endpoint_url, + aws_access_key_id=access_key, + aws_secret_access_key=secret_key, + config=Config(s3={"addressing_style": "virtual"}, retries={"max_attempts": 2}), + ) + + async def stream(self, attachment: Attachment) -> AsyncIterator[bytes]: + try: + response = await asyncio.to_thread( + self.client.get_object, + Bucket=self.bucket, + Key=attachment.quarantine_object_key, + VersionId=attachment.quarantine_version_id, + IfMatch=attachment.quarantine_etag, + ) + body = response["Body"] + while True: + chunk = await asyncio.to_thread(body.read, 65_536) + if not chunk: + break + yield chunk + except ClientError as exc: + code = exc.response.get("Error", {}).get("Code") + if code in {"PreconditionFailed", "NoSuchKey", "NoSuchVersion"}: + raise ObjectChanged("version or ETag changed") from exc + raise DependencyFailure("S3 dependency unavailable") from exc + except BotoCoreError as exc: + raise DependencyFailure("S3 dependency unavailable") from exc diff --git a/codebase/services/message-safety/app/api.py b/codebase/services/message-safety/app/api.py new file mode 100644 index 0000000..1b3670e --- /dev/null +++ b/codebase/services/message-safety/app/api.py @@ -0,0 +1,235 @@ +from __future__ import annotations + +import hmac +import json +import uuid +from typing import Annotated + +from fastapi import Depends, FastAPI, Header, Request +from fastapi.responses import JSONResponse +from pydantic import TypeAdapter, ValidationError + +from app.contracts import CheckRequest, ErrorBody, ErrorEnvelope, Pending, Verdict +from app.db import TaskStatus +from app.rate_limit import RateLimited +from app.repository import ConflictError +from app.service import CapabilityUnavailable, SafetyService, TaskFailed + +CHECK_ADAPTER = TypeAdapter(CheckRequest) +MAX_BODY = 16_384 + + +def error( + status: int, code: str, request_id: str, details: dict[str, object] | None = None +) -> JSONResponse: + body = ErrorEnvelope( + error=ErrorBody( + code=code, + message={ + "validation_error": "Request is invalid", + "service_unauthorized": "Service authentication failed", + }.get(code, "Request could not be completed"), + request_id=request_id, + details=details or {}, + ) + ) + return JSONResponse(status_code=status, content=body.model_dump(mode="json")) + + +def create_app(service: SafetyService, token: str) -> FastAPI: + app = FastAPI(title="HAN Message Safety", version="2.0.0", docs_url=None, redoc_url=None) + + async def authenticate( + request: Request, + provided: Annotated[str | None, Header(alias="X-Service-Token")] = None, + ) -> None: + if not provided or not hmac.compare_digest(provided.encode(), token.encode()): + request.state.auth_failed = True + raise PermissionError + + @app.exception_handler(PermissionError) + async def auth_error(request: Request, _: PermissionError) -> JSONResponse: + return error(401, "service_unauthorized", request.state.request_id) + + @app.middleware("http") + async def request_context(request: Request, call_next): + supplied = request.headers.get("X-Request-ID") + try: + request.state.request_id = str(uuid.UUID(supplied)) if supplied else str(uuid.uuid4()) + except ValueError: + request.state.request_id = str(uuid.uuid4()) + response = await call_next(request) + response.headers["X-Request-ID"] = request.state.request_id + response.headers["Cache-Control"] = "no-store" + return response + + @app.get("/health/live") + async def live() -> dict[str, str]: + return {"status": "ok"} + + @app.get("/health/ready") + async def ready() -> JSONResponse: + mode = "mock" if service.mode.mock else "standard" + components = { + "postgres": "ok", + "redis": "degraded", + "s3_quarantine": "bypassed" + if service.mode.mock + else ("ok" if service.files_ready else "down"), + "worker": "bypassed" if service.mode.mock else "ok", + "antivirus": "bypassed" + if service.mode.mock + else ("ok" if service.files_ready else "down"), + "dns": "bypassed" if service.mode.mock else ("ok" if service.links_ready else "down"), + "rules": "bypassed" if service.mode.mock else "ok", + } + capabilities = { + "text": "ready", + "links": "bypassed" + if service.mode.mock + else ("ready" if service.links_ready else "unavailable"), + "files": "bypassed" + if service.mode.mock + else ("ready" if service.files_ready else "unavailable"), + "worker": "bypassed" if service.mode.mock else "ready", + } + body: dict[str, object] = { + "status": "degraded" + if service.mode.mock or "degraded" in components.values() + else "ok", + "processing_mode": mode, + "config_version": service.config.version, + "components": components, + "capabilities": capabilities, + } + if service.mode.mock: + body["mock_policy"] = { + "text": "allow" if service.mode.text_free else "deny", + "file": "allow" if service.mode.file_free else "deny", + } + return JSONResponse(content=body) + + @app.post("/internal/safety/v2/messages/check", dependencies=[Depends(authenticate)]) + async def check(request: Request) -> JSONResponse: + content_type = request.headers.get("content-type", "").lower().replace(" ", "") + if content_type not in {"application/json", "application/json;charset=utf-8"}: + return error( + 400, + "validation_error", + request.state.request_id, + {"field": "content-type", "constraint": "application/json; charset=utf-8"}, + ) + body = await request.body() + if len(body) > MAX_BODY: + return error( + 400, + "validation_error", + request.state.request_id, + {"field": "body", "constraint": "max_bytes"}, + ) + try: + payload = CHECK_ADAPTER.validate_json(body, strict=True) + result = await service.check(payload) + except (ValidationError, json.JSONDecodeError, ValueError): + return error( + 400, + "validation_error", + request.state.request_id, + {"field": "body", "constraint": "strict_dto"}, + ) + except ConflictError: + message_id = "unknown" + try: + message_id = str(json.loads(body).get("message_id", "unknown")) + except (ValueError, AttributeError): + pass + return error( + 409, + "safety_request_conflict", + request.state.request_id, + {"message_id": message_id, "terminal": True, "retryable": False}, + ) + except CapabilityUnavailable as exc: + return error( + 503, + "dependency_unavailable", + request.state.request_id, + {"dependency_category": exc.category, "terminal": False, "retryable": True}, + ) + except RateLimited as exc: + response = error( + 429, + "rate_limit_exceeded", + request.state.request_id, + {"retryable": True, "retry_after_sec": exc.retry_after}, + ) + response.headers["Retry-After"] = str(exc.retry_after) + return response + except TaskFailed as exc: + return error( + 503, + "task_failed", + request.state.request_id, + { + "task_id": str(exc.task_id), + "task_status": "failed", + "terminal": True, + "retryable": False, + }, + ) + status = 202 if isinstance(result, Pending) else (200 if result.verdict == "allow" else 403) + response = JSONResponse(status_code=status, content=result.model_dump(mode="json")) + if isinstance(result, Pending): + response.headers["Location"] = f"/internal/safety/v2/messages/tasks/{result.task_id}" + response.headers["Retry-After"] = str(result.poll_after_ms // 1000) + return response + + @app.get("/internal/safety/v2/messages/tasks/{task_id}", dependencies=[Depends(authenticate)]) + async def get_task(request: Request, task_id: str) -> JSONResponse: + try: + parsed = uuid.UUID(task_id) + except ValueError: + return error( + 400, + "validation_error", + request.state.request_id, + {"field": "task_id", "constraint": "uuid"}, + ) + task = await service.repository.task(parsed) + if not task: + return error(404, "task_not_found", request.state.request_id) + if task.status == TaskStatus.failed: + return error( + 503, + "task_failed", + request.state.request_id, + { + "task_id": str(task.id), + "task_status": "failed", + "terminal": True, + "retryable": False, + }, + ) + if task.status in {TaskStatus.pending, TaskStatus.processing}: + result: Pending | Verdict = Pending( + config_version=task.config_version, + task_id=task.id, + expires_at=task.expires_at, + rules_version=task.rules_version, + ) + else: + result = service._verdict( + task.status == TaskStatus.allowed, + task.processing_mode, + task.rule_id or "safety.all_checks_passed", + task.rules_version, + config_version=task.config_version, + ) + status = 202 if isinstance(result, Pending) else (200 if result.verdict == "allow" else 403) + response = JSONResponse(status_code=status, content=result.model_dump(mode="json")) + if isinstance(result, Pending): + response.headers["Location"] = str(request.url.path) + response.headers["Retry-After"] = "2" + return response + + return app diff --git a/codebase/services/message-safety/app/artifacts/config.schema.json b/codebase/services/message-safety/app/artifacts/config.schema.json new file mode 100644 index 0000000..8f5db07 --- /dev/null +++ b/codebase/services/message-safety/app/artifacts/config.schema.json @@ -0,0 +1,63 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "additionalProperties": false, + "required": ["schema_version", "rules_bundle_ref", "detector_manifest_ref", "task", "rate", "retention", "cache", "link", "clamav", "file_policy"], + "properties": { + "schema_version": {"const": 1}, + "rules_bundle_ref": {"type": "string", "pattern": "^rules-[0-9]{4}-[0-9]{2}-[0-9]{2}$"}, + "detector_manifest_ref": {"const": "detector-2026-08-03"}, + "task": { + "type": "object", "additionalProperties": false, + "required": ["file_scan_timeout_sec", "lease_sec", "heartbeat_sec", "max_attempts", "execution_deadline_sec", "max_pending"], + "properties": { + "file_scan_timeout_sec": {"type": "integer", "minimum": 1, "maximum": 300}, + "lease_sec": {"type": "integer", "minimum": 10, "maximum": 600}, + "heartbeat_sec": {"type": "integer", "minimum": 1, "maximum": 300}, + "max_attempts": {"type": "integer", "minimum": 1, "maximum": 10}, + "execution_deadline_sec": {"type": "integer", "minimum": 60, "maximum": 7200}, + "max_pending": {"type": "integer", "minimum": 1, "maximum": 10000} + } + }, + "rate": { + "type": "object", "additionalProperties": false, "required": ["text_rps", "file_rps"], + "properties": {"text_rps": {"type": "integer", "minimum": 1}, "file_rps": {"type": "integer", "minimum": 1}} + }, + "retention": { + "type": "object", "additionalProperties": false, "required": ["task_days", "audit_days"], + "properties": {"task_days": {"type": "integer", "minimum": 1}, "audit_days": {"type": "integer", "minimum": 1}} + }, + "cache": { + "type": "object", "additionalProperties": false, + "required": ["file_verdict_ttl_sec", "text_rule_ttl_sec", "link_ttl_sec", "dns_max_ttl_sec", "dns_negative_ttl_sec"], + "properties": { + "file_verdict_ttl_sec": {"type": "integer", "minimum": 1}, + "text_rule_ttl_sec": {"type": "integer", "minimum": 1}, + "link_ttl_sec": {"type": "integer", "minimum": 1}, + "dns_max_ttl_sec": {"type": "integer", "minimum": 1, "maximum": 3600}, + "dns_negative_ttl_sec": {"type": "integer", "minimum": 1, "maximum": 300} + } + }, + "link": { + "type": "object", "additionalProperties": false, + "required": ["max_per_message", "url_max_length", "dns_lookup_timeout_sec", "pipeline_timeout_sec"], + "properties": { + "max_per_message": {"type": "integer", "minimum": 0, "maximum": 5}, + "url_max_length": {"type": "integer", "minimum": 1, "maximum": 2048}, + "dns_lookup_timeout_sec": {"type": "number", "exclusiveMinimum": 0, "maximum": 2}, + "pipeline_timeout_sec": {"type": "number", "exclusiveMinimum": 0, "maximum": 5} + } + }, + "clamav": { + "type": "object", "additionalProperties": false, "required": ["scan_timeout_sec", "max_signature_age_hours"], + "properties": {"scan_timeout_sec": {"type": "integer", "minimum": 1, "maximum": 120}, "max_signature_age_hours": {"type": "integer", "minimum": 1, "maximum": 168}} + }, + "file_policy": { + "type": "object", "additionalProperties": false, "required": ["enabled_mime_types", "max_size_bytes"], + "properties": { + "enabled_mime_types": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string"}}, + "max_size_bytes": {"type": "integer", "minimum": 1, "maximum": 5242880} + } + } + } +} diff --git a/codebase/services/message-safety/app/artifacts/detector-manifest.json b/codebase/services/message-safety/app/artifacts/detector-manifest.json new file mode 100644 index 0000000..b4443a2 --- /dev/null +++ b/codebase/services/message-safety/app/artifacts/detector-manifest.json @@ -0,0 +1,27 @@ +{ + "schema_version": 1, + "bundle": "detector-2026-08-03", + "implementation": { + "python": "3.12", + "pillow": "runtime-pinned-lock-required", + "pillow_heif": "runtime-pinned-lock-required" + }, + "supported_mime_types": [ + "image/jpeg", + "image/png", + "image/webp", + "image/heic", + "image/heif", + "application/pdf" + ], + "hard_limits": { + "max_size_bytes": 5242880, + "max_pixels": 25000000, + "max_dimension": 10000, + "max_webp_frames": 100, + "max_heif_items": 100, + "max_pdf_pages": 500, + "max_pdf_objects": 100000, + "max_decoded_bytes": 104857600 + } +} diff --git a/codebase/services/message-safety/app/artifacts/rules/rules-2026-01-01/rules.yaml b/codebase/services/message-safety/app/artifacts/rules/rules-2026-01-01/rules.yaml new file mode 100644 index 0000000..7a7416a --- /dev/null +++ b/codebase/services/message-safety/app/artifacts/rules/rules-2026-01-01/rules.yaml @@ -0,0 +1,35 @@ +schema_version: 1 +rules_version: "2026-01-01" +rules: + - rule_id: text.prompt_instruction_override + reason_code: monitor + severity: medium + scope: text + action: monitor + pattern: '(?]{0,512}\bon[a-z]{2,32}\s*=|(?:javascript|vbscript|data\s*:\s*text/html)\s*:)' + positive: ["", "", "javascript:alert(1)"] + negative: ["Use the word script in documentation", "https://example.org/javascript-guide"] diff --git a/codebase/services/message-safety/app/artifacts/rules/rules.schema.json b/codebase/services/message-safety/app/artifacts/rules/rules.schema.json new file mode 100644 index 0000000..a044a1e --- /dev/null +++ b/codebase/services/message-safety/app/artifacts/rules/rules.schema.json @@ -0,0 +1,29 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "additionalProperties": false, + "required": ["schema_version", "rules_version", "rules"], + "properties": { + "schema_version": {"const": 1}, + "rules_version": {"type": "string", "minLength": 1, "maxLength": 128}, + "rules": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "additionalProperties": false, + "required": ["rule_id", "reason_code", "severity", "scope", "action", "pattern", "positive", "negative"], + "properties": { + "rule_id": {"type": "string", "pattern": "^[a-z][a-z0-9_.-]+$"}, + "reason_code": {"enum": ["message_blocked", "monitor"]}, + "severity": {"enum": ["low", "medium", "high", "critical"]}, + "scope": {"enum": ["text", "url", "file_metadata"]}, + "action": {"enum": ["deny", "monitor"]}, + "pattern": {"type": "string", "minLength": 1, "maxLength": 1000}, + "positive": {"type": "array", "minItems": 1, "items": {"type": "string"}}, + "negative": {"type": "array", "minItems": 1, "items": {"type": "string"}} + } + } + } + } +} diff --git a/codebase/services/message-safety/app/artifacts/seed-config.yaml b/codebase/services/message-safety/app/artifacts/seed-config.yaml new file mode 100644 index 0000000..68a43b2 --- /dev/null +++ b/codebase/services/message-safety/app/artifacts/seed-config.yaml @@ -0,0 +1,30 @@ +schema_version: 1 +rules_bundle_ref: rules-2026-01-01 +detector_manifest_ref: detector-2026-08-03 +task: + file_scan_timeout_sec: 60 + lease_sec: 90 + heartbeat_sec: 30 + max_attempts: 3 + execution_deadline_sec: 1200 + max_pending: 100 +rate: {text_rps: 10, file_rps: 2} +retention: {task_days: 30, audit_days: 180} +cache: + file_verdict_ttl_sec: 2592000 + text_rule_ttl_sec: 172800 + link_ttl_sec: 172800 + dns_max_ttl_sec: 900 + dns_negative_ttl_sec: 60 +link: + max_per_message: 5 + url_max_length: 2048 + dns_lookup_timeout_sec: 1 + pipeline_timeout_sec: 2 +clamav: + scan_timeout_sec: 45 + max_signature_age_hours: 24 +file_policy: + enabled_mime_types: + [image/jpeg, image/png, image/webp, image/heic, image/heif, application/pdf] + max_size_bytes: 5242880 diff --git a/codebase/services/message-safety/app/config.py b/codebase/services/message-safety/app/config.py new file mode 100644 index 0000000..b0d8ec0 --- /dev/null +++ b/codebase/services/message-safety/app/config.py @@ -0,0 +1,51 @@ +from __future__ import annotations + +import hashlib +import json +from dataclasses import dataclass +from pathlib import Path +from typing import Any + +from jsonschema import validate + +from app.file_pipeline import DetectorManifest +from app.rules import RuleBundle + + +@dataclass(frozen=True) +class ActiveConfig: + version: int + document: dict[str, Any] + rules: RuleBundle + detector: DetectorManifest + + @property + def rules_version(self) -> str: + return self.rules.version + + +def canonical_config(document: dict[str, Any]) -> bytes: + return json.dumps(document, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode() + + +def validate_config( + document: dict[str, Any], artifacts: Path +) -> tuple[RuleBundle, DetectorManifest, bytes]: + schema = json.loads((artifacts / "config.schema.json").read_text(encoding="utf-8")) + validate(document, schema) + task = document["task"] + if not task["heartbeat_sec"] < task["lease_sec"] < task["execution_deadline_sec"]: + raise ValueError("heartbeat_sec < lease_sec < execution_deadline_sec is required") + rules_ref = document["rules_bundle_ref"] + rules = RuleBundle.load( + artifacts / "rules" / rules_ref / "rules.yaml", + artifacts / "rules" / "rules.schema.json", + ) + detector = DetectorManifest.load(artifacts / "detector-manifest.json") + enabled = set(document["file_policy"]["enabled_mime_types"]) + if not enabled <= detector.supported: + raise ValueError("file policy is not a detector manifest subset") + if document["file_policy"]["max_size_bytes"] > detector.max_size: + raise ValueError("file policy exceeds detector hard limit") + digest = hashlib.sha256(canonical_config(document)).digest() + return rules, detector, digest diff --git a/codebase/services/message-safety/app/config_admin.py b/codebase/services/message-safety/app/config_admin.py new file mode 100644 index 0000000..174fd4b --- /dev/null +++ b/codebase/services/message-safety/app/config_admin.py @@ -0,0 +1,111 @@ +from __future__ import annotations + +import argparse +import asyncio +import json +import os +import uuid +from datetime import UTC, datetime, timedelta +from pathlib import Path + +import yaml +from sqlalchemy import select, text, update + +from app.config import validate_config +from app.db import ConfigVersion, SafetyAudit, engine_and_sessions +from app.settings import _secret + + +async def execute(args: argparse.Namespace) -> None: + url = _secret("MESSAGE_SAFETY_CONFIG_ADMIN_DATABASE_URL") + assert url + artifacts = Path(os.getenv("MESSAGE_SAFETY_ARTIFACTS_DIR", "/app/app/artifacts")) + document = ( + yaml.safe_load(await asyncio.to_thread(Path(args.file).read_text, encoding="utf-8")) + if args.file + else None + ) + if document: + _, _, digest = validate_config(document, artifacts) + engine, sessions = engine_and_sessions(url) + try: + if args.command == "validate": + print(json.dumps({"valid": True, "config_sha256": digest.hex()})) + return + async with sessions.begin() as session: + await session.execute( + text("SELECT pg_advisory_xact_lock(hashtext('message_safety.config_activation'))") + ) + if args.command == "create": + exists = await session.scalar( + select(ConfigVersion.id).where(ConfigVersion.version == args.version) + ) + if exists: + raise ValueError("config version already exists") + session.add( + ConfigVersion( + version=args.version, + schema_version=document["schema_version"], + state="draft", + config=document, + config_sha256=digest, + created_by=args.actor, + created_at=datetime.now(UTC), + ) + ) + elif args.command == "activate": + row = await session.scalar( + select(ConfigVersion) + .where(ConfigVersion.version == args.version) + .with_for_update() + ) + if not row or row.state != "draft": + raise ValueError("only a draft config can be activated") + validate_config(row.config, artifacts) + now = datetime.now(UTC) + await session.execute( + update(ConfigVersion) + .where(ConfigVersion.state == "active") + .values(state="retired", retired_at=now) + ) + row.state = "active" + row.approved_by = args.approved_by + row.approved_at = now + row.activated_at = now + session.add( + SafetyAudit( + id=uuid.uuid4(), + event="config_activated", + processing_mode="standard", + config_version=row.version, + created_at=now, + purge_after=now + timedelta(days=180), + ) + ) + print(json.dumps({"ok": True, "version": args.version})) + finally: + await engine.dispose() + + +def parser() -> argparse.ArgumentParser: + result = argparse.ArgumentParser() + commands = result.add_subparsers(dest="command", required=True) + validate = commands.add_parser("validate") + validate.add_argument("file") + create = commands.add_parser("create") + create.add_argument("file") + create.add_argument("--version", type=int, required=True) + create.add_argument("--actor", required=True) + activate = commands.add_parser("activate") + activate.add_argument("--version", type=int, required=True) + activate.add_argument("--approved-by", required=True) + activate.set_defaults(file=None) + return result + + +def main() -> None: + asyncio.run(execute(parser().parse_args())) + + +if __name__ == "__main__": + main() diff --git a/codebase/services/message-safety/app/contracts.py b/codebase/services/message-safety/app/contracts.py new file mode 100644 index 0000000..e55f6f8 --- /dev/null +++ b/codebase/services/message-safety/app/contracts.py @@ -0,0 +1,81 @@ +from __future__ import annotations + +import re +from datetime import datetime +from typing import Annotated, Literal +from uuid import UUID + +from pydantic import BaseModel, ConfigDict, Field, StringConstraints, model_validator + +Checksum = Annotated[str, StringConstraints(pattern=r"^sha256:[0-9a-f]{64}$")] + + +class StrictModel(BaseModel): + model_config = ConfigDict(extra="forbid", strict=True) + + +class Attachment(StrictModel): + attachment_id: UUID + quarantine_object_key: Annotated[str, StringConstraints(min_length=1, max_length=1024)] + quarantine_version_id: Annotated[str, StringConstraints(min_length=1, max_length=512)] + quarantine_etag: Annotated[str, StringConstraints(min_length=1, max_length=512)] + mime_type: Annotated[str, StringConstraints(min_length=1, max_length=127)] + size_bytes: int = Field(ge=1, le=5_242_880) + checksum: Checksum + + @model_validator(mode="after") + def canonical_key(self) -> Attachment: + uuid = r"[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}" + pattern = rf"^quarantine/users/{uuid}/dialogs/{uuid}/{uuid}$" + if not self.quarantine_object_key.isascii() or not re.fullmatch( + pattern, self.quarantine_object_key + ): + raise ValueError("quarantine_object_key is not canonical") + return self + + +class TextCheck(StrictModel): + message_id: UUID + content_kind: Literal["text"] + text: Annotated[str, StringConstraints(min_length=1, max_length=10_000)] + attachment: None = None + + +class FileCheck(StrictModel): + message_id: UUID + content_kind: Literal["file"] + text: Literal[""] + attachment: Attachment + + +CheckRequest = Annotated[TextCheck | FileCheck, Field(discriminator="content_kind")] + + +class Verdict(StrictModel): + verdict: Literal["allow", "deny"] + processing_mode: Literal["standard", "mock"] + config_version: int + rule_id: str + rules_version: str + reason_code: Literal["message_blocked"] | None = None + + +class Pending(StrictModel): + verdict: Literal["pending"] = "pending" + processing_mode: Literal["standard"] = "standard" + config_version: int + task_id: UUID + poll_after_ms: int = 2000 + expires_at: datetime + rules_version: str + + +class ErrorBody(StrictModel): + code: str + message: str + request_id: str + details: dict[str, object] = Field(default_factory=dict) + + +class ErrorEnvelope(StrictModel): + error: ErrorBody diff --git a/codebase/services/message-safety/app/db.py b/codebase/services/message-safety/app/db.py new file mode 100644 index 0000000..a5d31d1 --- /dev/null +++ b/codebase/services/message-safety/app/db.py @@ -0,0 +1,271 @@ +from __future__ import annotations + +import os +import ssl +import uuid +from datetime import datetime +from enum import StrEnum +from typing import Any + +from sqlalchemy import ( + BigInteger, + CheckConstraint, + DateTime, + Enum, + ForeignKey, + Index, + Integer, + LargeBinary, + String, + Text, + UniqueConstraint, + text, +) +from sqlalchemy.dialects.postgresql import ARRAY, JSONB, UUID +from sqlalchemy.ext.asyncio import AsyncAttrs, AsyncEngine, async_sessionmaker, create_async_engine +from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column + +SCHEMA = "message_safety" + + +def postgres_ssl_context() -> ssl.SSLContext: + ca_file = os.environ.get("PG_CA_FILE") + if not ca_file: + raise RuntimeError("PG_CA_FILE is required") + context = ssl.create_default_context(cafile=ca_file) + context.check_hostname = True + context.verify_mode = ssl.CERT_REQUIRED + return context + + +class Base(AsyncAttrs, DeclarativeBase): + pass + + +class TaskStatus(StrEnum): + pending = "pending" + processing = "processing" + allowed = "allowed" + denied = "denied" + failed = "failed" + + +class SafetyRequest(Base): + __tablename__ = "safety_requests" + __table_args__ = ( + CheckConstraint("octet_length(request_fingerprint)=32", name="ck_request_fingerprint"), + CheckConstraint("verdict IN ('allow','deny','pending')", name="ck_request_verdict"), + CheckConstraint("processing_mode IN ('standard','mock')", name="ck_request_mode"), + Index("ix_request_purge", "purge_after"), + {"schema": SCHEMA}, + ) + message_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True) + request_fingerprint: Mapped[bytes] = mapped_column(LargeBinary(32)) + processing_mode: Mapped[str] = mapped_column(String(16)) + config_version: Mapped[int] = mapped_column( + BigInteger, ForeignKey(f"{SCHEMA}.config_versions.version", ondelete="RESTRICT") + ) + verdict: Mapped[str] = mapped_column(String(8)) + task_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True)) + rule_id: Mapped[str | None] = mapped_column(String(128)) + reason_code: Mapped[str | None] = mapped_column(String(64)) + rules_version: Mapped[str] = mapped_column(String(128)) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + purge_after: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + + +class ConfigVersion(Base): + __tablename__ = "config_versions" + __table_args__ = ( + CheckConstraint("state IN ('draft','active','retired')", name="ck_config_state"), + Index( + "uq_config_one_active", "state", unique=True, postgresql_where=text("state = 'active'") + ), + {"schema": SCHEMA}, + ) + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + version: Mapped[int] = mapped_column(BigInteger, unique=True) + schema_version: Mapped[int] = mapped_column(Integer) + state: Mapped[str] = mapped_column(String(16)) + config: Mapped[dict[str, Any]] = mapped_column(JSONB) + config_sha256: Mapped[bytes] = mapped_column(LargeBinary(32)) + created_by: Mapped[str] = mapped_column(String(128)) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + approved_by: Mapped[str | None] = mapped_column(String(128)) + approved_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + activated_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + retired_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + + +class SafetyTask(Base): + __tablename__ = "safety_tasks" + __table_args__ = ( + CheckConstraint("octet_length(request_fingerprint)=32", name="ck_task_fingerprint"), + CheckConstraint("octet_length(content_sha256)=32", name="ck_task_sha"), + CheckConstraint("processing_mode='standard'", name="ck_task_standard"), + CheckConstraint("attempt_count>=0 AND lease_generation>=0", name="ck_task_counts"), + CheckConstraint( + "(status='allowed' AND verdict='allow') OR " + "(status='denied' AND verdict='deny' AND reason_code='message_blocked') OR " + "(status='failed' AND verdict IS NULL) OR " + "(status IN ('pending','processing') AND verdict IS NULL)", + name="ck_task_terminal", + ), + Index("ix_task_queue", "status", "next_attempt_at", "created_at"), + Index("ix_task_lease", "status", "lease_until"), + Index("ix_task_retention", "finished_at"), + {"schema": SCHEMA}, + ) + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + message_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), unique=True) + attachment_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True)) + request_fingerprint: Mapped[bytes] = mapped_column(LargeBinary(32)) + content_sha256: Mapped[bytes] = mapped_column(LargeBinary(32)) + processing_mode: Mapped[str] = mapped_column(String(16), default="standard") + config_version: Mapped[int] = mapped_column( + BigInteger, ForeignKey(f"{SCHEMA}.config_versions.version", ondelete="RESTRICT") + ) + status: Mapped[TaskStatus] = mapped_column(Enum(TaskStatus, name="task_status", schema=SCHEMA)) + attempt_count: Mapped[int] = mapped_column(Integer, default=0) + lease_generation: Mapped[int] = mapped_column(Integer, default=0) + lease_owner: Mapped[str | None] = mapped_column(String(128)) + lease_until: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + next_attempt_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + quarantine_object_key: Mapped[str] = mapped_column(Text) + quarantine_version_id: Mapped[str] = mapped_column(String(512)) + quarantine_etag: Mapped[str] = mapped_column(String(512)) + declared_mime: Mapped[str] = mapped_column(String(127)) + declared_size_bytes: Mapped[int] = mapped_column(BigInteger) + declared_checksum: Mapped[str] = mapped_column(String(71)) + verdict: Mapped[str | None] = mapped_column(String(8)) + rule_id: Mapped[str | None] = mapped_column(String(128)) + reason_code: Mapped[str | None] = mapped_column(String(64)) + rules_version: Mapped[str] = mapped_column(String(128)) + detector_version: Mapped[str] = mapped_column(String(128)) + scanner_engine: Mapped[str] = mapped_column(String(32)) + signatures_version: Mapped[str] = mapped_column(String(128)) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + finished_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + purge_after: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + + +class FileVerdictCache(Base): + __tablename__ = "file_verdict_cache" + __table_args__ = ( + UniqueConstraint( + "content_sha256", + "config_version", + "rules_version", + "detector_version", + "scanner_engine", + "signatures_version", + name="uq_file_cache_key", + ), + CheckConstraint("verdict IN ('allow','deny')", name="ck_file_cache_verdict"), + CheckConstraint("octet_length(content_sha256)=32", name="ck_file_cache_sha"), + Index("ix_file_cache_expiry", "expires_at"), + {"schema": SCHEMA}, + ) + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + content_sha256: Mapped[bytes] = mapped_column(LargeBinary(32)) + config_version: Mapped[int] = mapped_column( + BigInteger, ForeignKey(f"{SCHEMA}.config_versions.version", ondelete="RESTRICT") + ) + rules_version: Mapped[str] = mapped_column(String(128)) + detector_version: Mapped[str] = mapped_column(String(128)) + scanner_engine: Mapped[str] = mapped_column(String(32)) + signatures_version: Mapped[str] = mapped_column(String(128)) + verdict: Mapped[str] = mapped_column(String(8)) + rule_id: Mapped[str] = mapped_column(String(128)) + reason_code: Mapped[str | None] = mapped_column(String(64)) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + + +class TextRulesCache(Base): + __tablename__ = "text_rules_cache" + __table_args__ = ( + UniqueConstraint("analysis_sha256", "rules_version", name="uq_text_cache_key"), + CheckConstraint("result IN ('allow','deny')", name="ck_text_cache_result"), + CheckConstraint("octet_length(analysis_sha256)=32", name="ck_text_cache_sha"), + Index("ix_text_cache_expiry", "expires_at"), + {"schema": SCHEMA}, + ) + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + analysis_sha256: Mapped[bytes] = mapped_column(LargeBinary(32)) + rules_version: Mapped[str] = mapped_column(String(128)) + result: Mapped[str] = mapped_column(String(8)) + deny_rule_id: Mapped[str | None] = mapped_column(String(128)) + monitor_rule_ids: Mapped[list[str]] = mapped_column(ARRAY(String(128)), default=list) + normalization_flags: Mapped[list[str]] = mapped_column(ARRAY(String(32)), default=list) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + + +class LinkVerdictCache(Base): + __tablename__ = "link_verdict_cache" + __table_args__ = ( + UniqueConstraint( + "canonical_url_sha256", "rules_version", "config_version", name="uq_link_key" + ), + CheckConstraint("verdict IN ('allow','deny')", name="ck_link_verdict"), + Index("ix_link_cache_expiry", "expires_at"), + {"schema": SCHEMA}, + ) + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + canonical_url_sha256: Mapped[bytes] = mapped_column(LargeBinary(32)) + rules_version: Mapped[str] = mapped_column(String(128)) + config_version: Mapped[int] = mapped_column( + BigInteger, ForeignKey(f"{SCHEMA}.config_versions.version", ondelete="RESTRICT") + ) + verdict: Mapped[str] = mapped_column(String(8)) + rule_id: Mapped[str | None] = mapped_column(String(128)) + reason_code: Mapped[str | None] = mapped_column(String(64)) + first_seen_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + last_seen_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + hit_count: Mapped[int] = mapped_column(BigInteger, default=1) + expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + + +class SafetyAudit(Base): + __tablename__ = "safety_audit" + __table_args__ = ( + CheckConstraint( + "event IN ('received','task_created','rule_hit','rule_hit_monitor'," + "'scan_completed','dependency_failed','mock_forced_allow'," + "'mock_forced_deny','config_activated')", + name="ck_audit_event", + ), + CheckConstraint("processing_mode IN ('standard','mock')", name="ck_audit_mode"), + Index("ix_audit_purge", "purge_after"), + Index("ix_audit_message", "message_id", "created_at"), + {"schema": SCHEMA}, + ) + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + request_id: Mapped[str | None] = mapped_column(String(64)) + message_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True)) + task_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True)) + event: Mapped[str] = mapped_column(String(32)) + processing_mode: Mapped[str] = mapped_column(String(16)) + config_version: Mapped[int] = mapped_column( + BigInteger, ForeignKey(f"{SCHEMA}.config_versions.version", ondelete="RESTRICT") + ) + verdict: Mapped[str | None] = mapped_column(String(8)) + rule_id: Mapped[str | None] = mapped_column(String(128)) + rules_version: Mapped[str | None] = mapped_column(String(128)) + normalization_flags: Mapped[list[str]] = mapped_column(ARRAY(String(32)), default=list) + duration_ms: Mapped[int | None] = mapped_column(Integer) + error_category: Mapped[str | None] = mapped_column(String(64)) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + purge_after: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + + +def engine_and_sessions(url: str) -> tuple[AsyncEngine, async_sessionmaker]: + engine = create_async_engine( + url, + pool_pre_ping=True, + connect_args={"ssl": postgres_ssl_context()}, + ) + return engine, async_sessionmaker(engine, expire_on_commit=False) diff --git a/codebase/services/message-safety/app/file_pipeline.py b/codebase/services/message-safety/app/file_pipeline.py new file mode 100644 index 0000000..7aa3b4f --- /dev/null +++ b/codebase/services/message-safety/app/file_pipeline.py @@ -0,0 +1,171 @@ +from __future__ import annotations + +import asyncio +import hashlib +import io +import json +import struct +from collections.abc import AsyncIterator +from dataclasses import dataclass +from pathlib import Path +from typing import Protocol + +from PIL import Image, UnidentifiedImageError +from pillow_heif import register_heif_opener + +from app.contracts import Attachment + +register_heif_opener() + + +class ObjectChanged(RuntimeError): + pass + + +class DependencyFailure(RuntimeError): + pass + + +class ObjectReader(Protocol): + async def stream(self, attachment: Attachment) -> AsyncIterator[bytes]: ... + + +class Antivirus(Protocol): + async def scan(self, chunks: AsyncIterator[bytes]) -> str | None: ... + + +@dataclass(frozen=True) +class DetectorManifest: + version: str + supported: frozenset[str] + max_size: int + + @classmethod + def load(cls, path: Path) -> DetectorManifest: + raw = path.read_bytes() + data = json.loads(raw) + version = "sha256:" + hashlib.sha256(raw).hexdigest() + return cls( + version, frozenset(data["supported_mime_types"]), data["hard_limits"]["max_size_bytes"] + ) + + +def validate_metadata( + attachment: Attachment, manifest: DetectorManifest, enabled: set[str] +) -> str | None: + if attachment.mime_type not in manifest.supported or attachment.mime_type not in enabled: + return "file.unsupported_mime" + if attachment.size_bytes > manifest.max_size: + return "file.size_limit" + return None + + +def detect_format(data: bytes, declared: str) -> str | None: + matches: list[str] = [] + if data.startswith(b"\xff\xd8\xff") and data.endswith(b"\xff\xd9"): + matches.append("image/jpeg") + if data.startswith(b"\x89PNG\r\n\x1a\n") and b"IEND" in data[-64:]: + matches.append("image/png") + if len(data) >= 12 and data[:4] == b"RIFF" and data[8:12] == b"WEBP": + matches.append("image/webp") + if len(data) >= 12 and data[4:8] == b"ftyp": + brand = data[8:12] + if brand in {b"heic", b"heix", b"hevc", b"hevx"}: + matches.append("image/heic") + if brand in {b"mif1", b"msf1"}: + matches.append("image/heif") + if data.startswith(b"%PDF-") and b"%%EOF" in data[-1024:]: + matches.append("application/pdf") + if len(matches) != 1: + return "file.polyglot_or_ambiguous" + if matches[0] != declared: + return "file.format_mismatch" + if declared == "application/pdf": + lowered = data.lower() + if b"/encrypt" in lowered: + return "file.encrypted_content" + if any( + token in lowered + for token in (b"/javascript", b"/openaction", b"/launch", b"/xfa", b"/embeddedfile") + ): + return "file.active_content" + else: + try: + with Image.open(io.BytesIO(data)) as image: + width, height = image.size + if width > 10_000 or height > 10_000 or width * height > 25_000_000: + return "file.parser_limit" + image.verify() + except (UnidentifiedImageError, OSError, ValueError): + return "file.format_mismatch" + return None + + +async def collect_and_hash( + reader: ObjectReader, attachment: Attachment, *, max_size: int +) -> tuple[bytes, bytes]: + digest = hashlib.sha256() + body = bytearray() + async for chunk in reader.stream(attachment): + if len(body) + len(chunk) > max_size: + raise ObjectChanged("object exceeds bounded size") + digest.update(chunk) + body.extend(chunk) + expected = bytes.fromhex(attachment.checksum.removeprefix("sha256:")) + if len(body) != attachment.size_bytes or digest.digest() != expected: + raise ObjectChanged("authoritative object metadata mismatch") + return bytes(body), digest.digest() + + +class ClamAvInstream: + def __init__(self, host: str, port: int, timeout: float = 45.0) -> None: + self.host, self.port, self.timeout = host, port, timeout + + async def scan(self, chunks: AsyncIterator[bytes]) -> str | None: + async def operation() -> str | None: + reader, writer = await asyncio.open_connection(self.host, self.port) + try: + writer.write(b"zINSTREAM\0") + async for chunk in chunks: + writer.write(struct.pack(">I", len(chunk)) + chunk) + await writer.drain() + writer.write(struct.pack(">I", 0)) + await writer.drain() + result = await reader.readuntil(b"\0") + text = result.rstrip(b"\0").decode("utf-8", "replace") + if text.endswith(" OK"): + return None + if text.endswith(" FOUND"): + return text.rsplit(": ", 1)[-1].removesuffix(" FOUND") + raise DependencyFailure("invalid ClamAV response") + finally: + writer.close() + await writer.wait_closed() + + try: + return await asyncio.wait_for(operation(), self.timeout) + except (OSError, TimeoutError) as exc: + raise DependencyFailure("ClamAV unavailable") from exc + + async def signatures_version(self) -> str: + try: + reader, writer = await asyncio.wait_for( + asyncio.open_connection(self.host, self.port), 2.0 + ) + try: + writer.write(b"zVERSION\0") + await writer.drain() + raw = await asyncio.wait_for(reader.readuntil(b"\0"), 2.0) + finally: + writer.close() + await writer.wait_closed() + except (OSError, TimeoutError) as exc: + raise DependencyFailure("ClamAV unavailable") from exc + value = raw.rstrip(b"\0") + if not value.startswith(b"ClamAV ") or len(value) > 512: + raise DependencyFailure("invalid ClamAV version response") + return "sha256:" + hashlib.sha256(value).hexdigest() + + +async def one_chunk(data: bytes) -> AsyncIterator[bytes]: + yield data diff --git a/codebase/services/message-safety/app/fingerprint.py b/codebase/services/message-safety/app/fingerprint.py new file mode 100644 index 0000000..4230315 --- /dev/null +++ b/codebase/services/message-safety/app/fingerprint.py @@ -0,0 +1,41 @@ +from __future__ import annotations + +import hashlib +import json +import math +from typing import Any + +from pydantic import BaseModel + + +def _jcs(value: Any) -> str: + """Deterministic JSON close to RFC 8785 for this integer/string DTO domain.""" + if value is None: + return "null" + if value is True: + return "true" + if value is False: + return "false" + if isinstance(value, str): + return json.dumps(value, ensure_ascii=False, separators=(",", ":")) + if isinstance(value, int): + return str(value) + if isinstance(value, float): + if not math.isfinite(value): + raise ValueError("non-finite numbers are not JSON canonicalizable") + raise TypeError("floating point values are forbidden in safety fingerprints") + if isinstance(value, list): + return "[" + ",".join(_jcs(item) for item in value) + "]" + if isinstance(value, dict): + keys = sorted(value, key=lambda key: key.encode("utf-16be")) + return "{" + ",".join(f"{_jcs(key)}:{_jcs(value[key])}" for key in keys) + "}" + raise TypeError(f"unsupported fingerprint type: {type(value).__name__}") + + +def canonical_json(model: BaseModel | dict[str, Any]) -> bytes: + value = model.model_dump(mode="json") if isinstance(model, BaseModel) else model + return _jcs(value).encode("utf-8") + + +def fingerprint(model: BaseModel | dict[str, Any]) -> bytes: + return hashlib.sha256(canonical_json(model)).digest() diff --git a/codebase/services/message-safety/app/hot_cache.py b/codebase/services/message-safety/app/hot_cache.py new file mode 100644 index 0000000..cfdb946 --- /dev/null +++ b/codebase/services/message-safety/app/hot_cache.py @@ -0,0 +1,35 @@ +from __future__ import annotations + +import json +from typing import Any + +from redis.asyncio import Redis +from redis.exceptions import RedisError + + +class RedisHotCache: + """Best-effort accelerator; callers must always retain a PostgreSQL fallback.""" + + def __init__(self, client: Redis | None) -> None: + self.client = client + + async def get(self, key: str) -> dict[str, Any] | None: + if not self.client: + return None + try: + value = await self.client.get(f"han:safety:{key}") + return json.loads(value) if value else None + except (RedisError, ValueError, TypeError): + return None + + async def put(self, key: str, value: dict[str, Any], ttl: int) -> None: + if not self.client: + return + try: + await self.client.set( + f"han:safety:{key}", + json.dumps(value, separators=(",", ":"), sort_keys=True), + ex=ttl, + ) + except RedisError: + return diff --git a/codebase/services/message-safety/app/main.py b/codebase/services/message-safety/app/main.py new file mode 100644 index 0000000..318929a --- /dev/null +++ b/codebase/services/message-safety/app/main.py @@ -0,0 +1,71 @@ +from __future__ import annotations + +import asyncio + +import uvicorn + +from app.adapters import TrustedDnsResolver +from app.api import create_app +from app.config import ActiveConfig, validate_config +from app.db import engine_and_sessions +from app.file_pipeline import ClamAvInstream, DependencyFailure +from app.repository import Repository +from app.service import SafetyService +from app.settings import BootstrapSettings, EmergencyMode + + +async def build_runtime() -> tuple[object, object]: + settings = BootstrapSettings() + assert settings.database_url and settings.service_token + engine, sessions = engine_and_sessions(settings.database_url.get_secret_value()) + repository = Repository(sessions) + row = await repository.active_config() + rules, detector, digest = validate_config(row.config, settings.artifacts_dir) + if digest != row.config_sha256: + raise RuntimeError("active config hash mismatch") + config = ActiveConfig(row.version, row.config, rules, detector) + mode = EmergencyMode.from_file(settings.mode_file) + resolver = TrustedDnsResolver( + [item.strip() for item in settings.dns_resolvers.split(",") if item.strip()] + ) + clamav = ClamAvInstream(settings.clamav_host, settings.clamav_port) + if mode.mock: + signatures_version = "unavailable" + files_ready = False + else: + try: + signatures_version = await clamav.signatures_version() + files_ready = True + except DependencyFailure: + signatures_version = "unavailable" + files_ready = False + service = SafetyService( + repository, + config, + mode, + resolver, + files_ready=files_ready, + signatures_version=signatures_version, + ) + app = create_app(service, settings.service_token.get_secret_value()) + return app, engine + + +async def serve() -> None: + settings = BootstrapSettings() + app, engine = await build_runtime() + try: + server = uvicorn.Server( + uvicorn.Config(app, host=settings.host, port=settings.port, proxy_headers=False) + ) + await server.serve() + finally: + await engine.dispose() + + +def run() -> None: + asyncio.run(serve()) + + +if __name__ == "__main__": + run() diff --git a/codebase/services/message-safety/app/normalization.py b/codebase/services/message-safety/app/normalization.py new file mode 100644 index 0000000..ca043be --- /dev/null +++ b/codebase/services/message-safety/app/normalization.py @@ -0,0 +1,53 @@ +from __future__ import annotations + +import hashlib +import unicodedata +from dataclasses import dataclass + +_BIDI = {"RLE", "LRE", "RLO", "LRO", "PDF", "RLI", "LRI", "FSI", "PDI"} + + +@dataclass(frozen=True) +class NormalizedText: + display: str + analysis: str + analysis_sha256: bytes + flags: tuple[str, ...] + + +def normalize_text(raw: str) -> NormalizedText: + display = unicodedata.normalize("NFKC", raw.replace("\r\n", "\n").replace("\r", "\n")) + if len(display) > 10_000: + raise ValueError("text exceeds 10000 normalized code points") + flags: set[str] = set() + analysis: list[str] = [] + scripts: set[str] = set() + for char in display: + category = unicodedata.category(char) + bidi = unicodedata.bidirectional(char) + name = unicodedata.name(char, "") + if bidi in _BIDI: + flags.add("bidi_control") + continue + if category == "Cf": + flags.add("default_ignorable") + if char in {"\u200b", "\u200c", "\u200d", "\ufeff"}: + flags.add("zero_width") + continue + if char.isspace(): + analysis.append(" " if char != "\n" else "\n") + else: + analysis.append(char) + if "LATIN" in name: + scripts.add("latin") + elif "CYRILLIC" in name: + scripts.add("cyrillic") + if len(scripts) > 1: + flags.add("mixed_script") + analysis_form = "".join(analysis) + return NormalizedText( + display=display, + analysis=analysis_form, + analysis_sha256=hashlib.sha256(analysis_form.encode()).digest(), + flags=tuple(sorted(flags)), + ) diff --git a/codebase/services/message-safety/app/rate_limit.py b/codebase/services/message-safety/app/rate_limit.py new file mode 100644 index 0000000..125663c --- /dev/null +++ b/codebase/services/message-safety/app/rate_limit.py @@ -0,0 +1,37 @@ +from __future__ import annotations + +import asyncio +import time +from dataclasses import dataclass + + +@dataclass +class Bucket: + tokens: float + updated: float + + +class RateLimited(RuntimeError): + def __init__(self, retry_after: int = 1) -> None: + self.retry_after = retry_after + + +class ConservativeRateLimiter: + """Process-local fallback. Redis may accelerate this, never own correctness.""" + + def __init__(self, text_rps: int, file_rps: int) -> None: + self.rates = {"text": text_rps, "file": file_rps} + now = time.monotonic() + self.buckets = {kind: Bucket(float(rate), now) for kind, rate in self.rates.items()} + self.lock = asyncio.Lock() + + async def acquire(self, kind: str) -> None: + async with self.lock: + now = time.monotonic() + bucket = self.buckets[kind] + rate = self.rates[kind] + bucket.tokens = min(float(rate), bucket.tokens + (now - bucket.updated) * rate) + bucket.updated = now + if bucket.tokens < 1: + raise RateLimited + bucket.tokens -= 1 diff --git a/codebase/services/message-safety/app/repository.py b/codebase/services/message-safety/app/repository.py new file mode 100644 index 0000000..0173d39 --- /dev/null +++ b/codebase/services/message-safety/app/repository.py @@ -0,0 +1,325 @@ +from __future__ import annotations + +import uuid +from datetime import UTC, datetime, timedelta + +from sqlalchemy import func, select, text, update +from sqlalchemy.dialects.postgresql import insert +from sqlalchemy.ext.asyncio import async_sessionmaker + +from app.db import ( + ConfigVersion, + FileVerdictCache, + LinkVerdictCache, + SafetyAudit, + SafetyRequest, + SafetyTask, + TaskStatus, + TextRulesCache, +) + + +class ConflictError(RuntimeError): + pass + + +class QueueFull(RuntimeError): + pass + + +class Repository: + def __init__(self, sessions: async_sessionmaker) -> None: + self.sessions = sessions + + async def active_config(self) -> ConfigVersion: + async with self.sessions() as session: + rows = ( + await session.scalars(select(ConfigVersion).where(ConfigVersion.state == "active")) + ).all() + if len(rows) != 1: + raise RuntimeError("exactly one active config is required") + return rows[0] + + async def config_version(self, version: int) -> ConfigVersion: + async with self.sessions() as session: + row = await session.scalar( + select(ConfigVersion).where(ConfigVersion.version == version) + ) + if not row: + raise RuntimeError("task config snapshot is missing") + return row + + async def get_request(self, message_id: uuid.UUID) -> SafetyRequest | None: + async with self.sessions() as session: + return await session.get(SafetyRequest, message_id) + + async def text_cache(self, digest: bytes, rules_version: str) -> TextRulesCache | None: + async with self.sessions() as session: + return await session.scalar( + select(TextRulesCache).where( + TextRulesCache.analysis_sha256 == digest, + TextRulesCache.rules_version == rules_version, + TextRulesCache.expires_at > func.now(), + ) + ) + + async def put_text_cache(self, row: TextRulesCache) -> None: + async with self.sessions.begin() as session: + await session.execute( + insert(TextRulesCache) + .values( + analysis_sha256=row.analysis_sha256, + rules_version=row.rules_version, + result=row.result, + deny_rule_id=row.deny_rule_id, + monitor_rule_ids=row.monitor_rule_ids, + normalization_flags=row.normalization_flags, + created_at=row.created_at, + expires_at=row.expires_at, + ) + .on_conflict_do_nothing(constraint="uq_text_cache_key") + ) + + async def file_cache( + self, digest: bytes, config: object, signatures_version: str + ) -> FileVerdictCache | None: + async with self.sessions() as session: + return await session.scalar( + select(FileVerdictCache).where( + FileVerdictCache.content_sha256 == digest, + FileVerdictCache.config_version == config.version, + FileVerdictCache.rules_version == config.rules_version, + FileVerdictCache.detector_version == config.detector.version, + FileVerdictCache.scanner_engine == "clamav", + FileVerdictCache.signatures_version == signatures_version, + FileVerdictCache.expires_at > func.now(), + ) + ) + + async def put_file_cache(self, row: FileVerdictCache) -> None: + async with self.sessions.begin() as session: + await session.execute( + insert(FileVerdictCache) + .values( + content_sha256=row.content_sha256, + config_version=row.config_version, + rules_version=row.rules_version, + detector_version=row.detector_version, + scanner_engine=row.scanner_engine, + signatures_version=row.signatures_version, + verdict=row.verdict, + rule_id=row.rule_id, + reason_code=row.reason_code, + created_at=row.created_at, + expires_at=row.expires_at, + ) + .on_conflict_do_nothing(constraint="uq_file_cache_key") + ) + + async def link_cache( + self, digest: bytes, rules_version: str, config_version: int + ) -> LinkVerdictCache | None: + async with self.sessions.begin() as session: + row = await session.scalar( + select(LinkVerdictCache).where( + LinkVerdictCache.canonical_url_sha256 == digest, + LinkVerdictCache.rules_version == rules_version, + LinkVerdictCache.config_version == config_version, + LinkVerdictCache.expires_at > func.now(), + ) + ) + if row: + row.last_seen_at = datetime.now(UTC) + row.hit_count += 1 + return row + + async def put_link_cache(self, row: LinkVerdictCache) -> None: + async with self.sessions.begin() as session: + await session.execute( + insert(LinkVerdictCache) + .values( + canonical_url_sha256=row.canonical_url_sha256, + rules_version=row.rules_version, + config_version=row.config_version, + verdict=row.verdict, + rule_id=row.rule_id, + reason_code=row.reason_code, + first_seen_at=row.first_seen_at, + last_seen_at=row.last_seen_at, + hit_count=row.hit_count, + expires_at=row.expires_at, + ) + .on_conflict_do_nothing(constraint="uq_link_key") + ) + + async def reserve_request( + self, + record: SafetyRequest, + task: SafetyTask | None = None, + *, + max_pending: int | None = None, + ) -> tuple[SafetyRequest, bool]: + async with self.sessions.begin() as session: + if task is not None: + await session.execute( + text( + "SELECT pg_advisory_xact_lock(hashtext('message_safety.pending_capacity'))" + ) + ) + pending = await session.scalar( + select(func.count()) + .select_from(SafetyTask) + .where(SafetyTask.status.in_([TaskStatus.pending, TaskStatus.processing])) + ) + if max_pending is not None and pending >= max_pending: + raise QueueFull + statement = ( + insert(SafetyRequest) + .values( + message_id=record.message_id, + request_fingerprint=record.request_fingerprint, + processing_mode=record.processing_mode, + config_version=record.config_version, + verdict=record.verdict, + task_id=record.task_id, + rule_id=record.rule_id, + reason_code=record.reason_code, + rules_version=record.rules_version, + created_at=record.created_at, + purge_after=record.purge_after, + ) + .on_conflict_do_nothing(index_elements=["message_id"]) + ) + result = await session.execute(statement.returning(SafetyRequest.message_id)) + created = result.scalar_one_or_none() is not None + existing = await session.get(SafetyRequest, record.message_id, with_for_update=True) + assert existing + if existing.request_fingerprint != record.request_fingerprint: + raise ConflictError + if created and task is not None: + session.add(task) + return existing, created + + async def add_task(self, task: SafetyTask) -> SafetyTask: + async with self.sessions.begin() as session: + session.add(task) + return task + + async def task(self, task_id: uuid.UUID) -> SafetyTask | None: + async with self.sessions.begin() as session: + task = await session.get(SafetyTask, task_id, with_for_update=True) + if ( + task + and task.status in {TaskStatus.pending, TaskStatus.processing} + and task.expires_at <= datetime.now(UTC) + ): + task.status = TaskStatus.failed + task.finished_at = datetime.now(UTC) + task.purge_after = task.finished_at + timedelta(days=30) + return task + + async def claim(self, owner: str) -> SafetyTask | None: + async with self.sessions.begin() as session: + row = ( + await session.execute( + text( + """ + WITH candidate AS ( + SELECT t.id, (c.config->'task'->>'lease_sec')::integer AS lease_sec + FROM message_safety.safety_tasks t + JOIN message_safety.config_versions c ON c.version=t.config_version + WHERE (t.status='pending' AND COALESCE(t.next_attempt_at, now()) <= now()) + OR (t.status='processing' AND t.lease_until < now()) + ORDER BY t.created_at FOR UPDATE OF t SKIP LOCKED LIMIT 1 + ) + UPDATE message_safety.safety_tasks t + SET status='processing', lease_owner=:owner, + lease_until=now() + make_interval(secs => candidate.lease_sec), + lease_generation=lease_generation+1, + attempt_count=attempt_count+1, updated_at=now() + FROM candidate WHERE t.id=candidate.id RETURNING t.id + """ + ), + {"owner": owner}, + ) + ).scalar_one_or_none() + return await session.get(SafetyTask, row) if row else None + + async def heartbeat( + self, task_id: uuid.UUID, owner: str, generation: int, lease_sec: int + ) -> bool: + async with self.sessions.begin() as session: + result = await session.execute( + update(SafetyTask) + .where( + SafetyTask.id == task_id, + SafetyTask.status == TaskStatus.processing, + SafetyTask.lease_owner == owner, + SafetyTask.lease_generation == generation, + ) + .values(lease_until=func.now() + text(f"interval '{int(lease_sec)} seconds'")) + ) + return result.rowcount == 1 + + async def finish( + self, task_id: uuid.UUID, owner: str, generation: int, *, allow: bool, rule_id: str + ) -> bool: + now = datetime.now(UTC) + async with self.sessions.begin() as session: + result = await session.execute( + update(SafetyTask) + .where( + SafetyTask.id == task_id, + SafetyTask.status == TaskStatus.processing, + SafetyTask.lease_owner == owner, + SafetyTask.lease_generation == generation, + SafetyTask.lease_until > func.now(), + ) + .values( + status=TaskStatus.allowed if allow else TaskStatus.denied, + verdict="allow" if allow else "deny", + rule_id=rule_id, + reason_code=None if allow else "message_blocked", + finished_at=now, + purge_after=now + timedelta(days=30), + updated_at=now, + lease_owner=None, + lease_until=None, + ) + ) + if result.rowcount == 1: + await session.execute( + update(SafetyRequest) + .where(SafetyRequest.task_id == task_id) + .values( + verdict="allow" if allow else "deny", + rule_id=rule_id, + reason_code=None if allow else "message_blocked", + ) + ) + return result.rowcount == 1 + + async def retry_or_fail(self, task: SafetyTask, max_attempts: int) -> None: + async with self.sessions.begin() as session: + terminal = task.attempt_count >= max_attempts or task.expires_at <= datetime.now(UTC) + await session.execute( + update(SafetyTask) + .where( + SafetyTask.id == task.id, + SafetyTask.lease_owner == task.lease_owner, + SafetyTask.lease_generation == task.lease_generation, + ) + .values( + status=TaskStatus.failed if terminal else TaskStatus.pending, + lease_owner=None, + lease_until=None, + next_attempt_at=None + if terminal + else datetime.now(UTC) + timedelta(seconds=2**task.attempt_count), + finished_at=datetime.now(UTC) if terminal else None, + ) + ) + + async def audit(self, event: SafetyAudit) -> None: + async with self.sessions.begin() as session: + session.add(event) diff --git a/codebase/services/message-safety/app/rules.py b/codebase/services/message-safety/app/rules.py new file mode 100644 index 0000000..8f1bbb8 --- /dev/null +++ b/codebase/services/message-safety/app/rules.py @@ -0,0 +1,57 @@ +from __future__ import annotations + +import re +from dataclasses import dataclass +from pathlib import Path + +import yaml +from jsonschema import validate + + +@dataclass(frozen=True) +class RuleResult: + deny_rule: str | None + monitor_rules: tuple[str, ...] + + +@dataclass(frozen=True) +class CompiledRule: + rule_id: str + action: str + pattern: re.Pattern[str] + + +class RuleBundle: + def __init__(self, version: str, rules: tuple[CompiledRule, ...]) -> None: + self.version = version + self.rules = rules + + @classmethod + def load(cls, bundle_path: Path, schema_path: Path) -> RuleBundle: + bundle = yaml.safe_load(bundle_path.read_text(encoding="utf-8")) + schema = yaml.safe_load(schema_path.read_text(encoding="utf-8")) + validate(bundle, schema) + compiled: list[CompiledRule] = [] + ids: set[str] = set() + for rule in bundle["rules"]: + if rule["rule_id"] in ids: + raise ValueError("duplicate rule_id") + ids.add(rule["rule_id"]) + pattern = re.compile(rule["pattern"], re.IGNORECASE) + compiled_rule = CompiledRule(rule["rule_id"], rule["action"], pattern) + for sample in rule["positive"]: + if not pattern.search(sample): + raise ValueError(f"positive vector failed: {rule['rule_id']}") + for sample in rule["negative"]: + if pattern.search(sample): + raise ValueError(f"negative vector failed: {rule['rule_id']}") + compiled.append(compiled_rule) + return cls(bundle["rules_version"], tuple(compiled)) + + def evaluate(self, text: str) -> RuleResult: + deny: list[str] = [] + monitor: list[str] = [] + for rule in self.rules: + if rule.pattern.search(text): + (deny if rule.action == "deny" else monitor).append(rule.rule_id) + return RuleResult(min(deny) if deny else None, tuple(sorted(monitor))) diff --git a/codebase/services/message-safety/app/service.py b/codebase/services/message-safety/app/service.py new file mode 100644 index 0000000..87bd7f8 --- /dev/null +++ b/codebase/services/message-safety/app/service.py @@ -0,0 +1,367 @@ +from __future__ import annotations + +import uuid +from datetime import UTC, datetime, timedelta + +from app.config import ActiveConfig +from app.contracts import CheckRequest, FileCheck, Pending, TextCheck, Verdict +from app.db import ( + LinkVerdictCache, + SafetyAudit, + SafetyRequest, + SafetyTask, + TaskStatus, + TextRulesCache, +) +from app.file_pipeline import validate_metadata +from app.fingerprint import fingerprint +from app.normalization import normalize_text +from app.rate_limit import ConservativeRateLimiter +from app.repository import QueueFull, Repository +from app.settings import EmergencyMode +from app.url_policy import DnsError, Resolver, canonicalize, check_url, extract_urls + + +class CapabilityUnavailable(RuntimeError): + def __init__(self, category: str) -> None: + self.category = category + + +class TaskFailed(RuntimeError): + def __init__(self, task_id: uuid.UUID) -> None: + self.task_id = task_id + + +class SafetyService: + def __init__( + self, + repository: Repository, + config: ActiveConfig, + mode: EmergencyMode, + resolver: Resolver, + *, + links_ready: bool = True, + files_ready: bool = True, + signatures_version: str = "unverified", + ) -> None: + self.repository = repository + self.config = config + self.mode = mode + self.resolver = resolver + self.links_ready = links_ready + self.files_ready = files_ready + self.signatures_version = signatures_version + self.rate_limiter = ConservativeRateLimiter( + config.document["rate"]["text_rps"], config.document["rate"]["file_rps"] + ) + + def _verdict( + self, + allow: bool, + mode: str, + rule: str, + rules_version: str, + *, + config_version: int | None = None, + ) -> Verdict: + return Verdict( + verdict="allow" if allow else "deny", + processing_mode=mode, + config_version=self.config.version if config_version is None else config_version, + rule_id=rule, + reason_code=None if allow else "message_blocked", + rules_version=rules_version, + ) + + async def check(self, request: CheckRequest) -> Verdict | Pending: + digest = fingerprint(request) + existing = await self.repository.get_request(request.message_id) + if existing: + if existing.request_fingerprint != digest: + from app.repository import ConflictError + + raise ConflictError + return await self._replay(existing) + await self.rate_limiter.acquire(request.content_kind) + if self.mode.mock: + free = self.mode.text_free if request.content_kind == "text" else self.mode.file_free + verdict = self._verdict( + free, + "mock", + "safety.mock_forced_allow" if free else "safety.mock_forced_deny", + "mock", + ) + return await self._persist_sync(request, digest, verdict) + if isinstance(request, TextCheck): + return await self._check_text(request, digest) + return await self._check_file(request, digest) + + async def _check_text(self, request: TextCheck, digest: bytes) -> Verdict: + normalized = normalize_text(request.text) + cache = await self.repository.text_cache( + normalized.analysis_sha256, self.config.rules_version + ) + if cache: + deny_rule = cache.deny_rule_id + else: + result = self.config.rules.evaluate(normalized.analysis) + deny_rule = result.deny_rule + now = datetime.now(UTC) + await self.repository.put_text_cache( + TextRulesCache( + analysis_sha256=normalized.analysis_sha256, + rules_version=self.config.rules_version, + result="deny" if deny_rule else "allow", + deny_rule_id=deny_rule, + monitor_rule_ids=list(result.monitor_rules), + normalization_flags=list(normalized.flags), + created_at=now, + expires_at=now + + timedelta(seconds=self.config.document["cache"]["text_rule_ttl_sec"]), + ) + ) + if deny_rule: + return await self._persist_sync( + request, + digest, + self._verdict(False, "standard", deny_rule, self.config.rules_version), + ) + urls = extract_urls( + normalized.analysis, + maximum=self.config.document["link"]["max_per_message"], + max_length=self.config.document["link"]["url_max_length"], + ) + if urls and not self.links_ready: + raise CapabilityUnavailable("dns") + for raw in urls: + try: + canonical = canonicalize(raw) + except PermissionError as exc: + return await self._persist_sync( + request, + digest, + self._verdict(False, "standard", str(exc), self.config.rules_version), + ) + cached_link = await self.repository.link_cache( + canonical.digest, self.config.rules_version, self.config.version + ) + if cached_link and cached_link.verdict == "deny": + return await self._persist_sync( + request, + digest, + self._verdict( + False, + "standard", + cached_link.rule_id or "url.malformed", + self.config.rules_version, + ), + ) + try: + _, rule = await check_url( + raw, self.resolver, self.config.document["link"]["dns_lookup_timeout_sec"] + ) + except DnsError as exc: + raise CapabilityUnavailable("dns") from exc + if rule != "url.nxdomain" and not cached_link: + now = datetime.now(UTC) + await self.repository.put_link_cache( + LinkVerdictCache( + canonical_url_sha256=canonical.digest, + rules_version=self.config.rules_version, + config_version=self.config.version, + verdict="deny" if rule else "allow", + rule_id=rule, + reason_code="message_blocked" if rule else None, + first_seen_at=now, + last_seen_at=now, + hit_count=1, + expires_at=now + + timedelta(seconds=self.config.document["cache"]["link_ttl_sec"]), + ) + ) + if rule and rule != "url.nxdomain": + return await self._persist_sync( + request, + digest, + self._verdict(False, "standard", rule, self.config.rules_version), + ) + return await self._persist_sync( + request, + digest, + self._verdict(True, "standard", "safety.all_checks_passed", self.config.rules_version), + ) + + async def _check_file(self, request: FileCheck, digest: bytes) -> Verdict | Pending: + if not self.files_ready: + raise CapabilityUnavailable("files") + rule = validate_metadata( + request.attachment, + self.config.detector, + set(self.config.document["file_policy"]["enabled_mime_types"]), + ) + if rule: + return await self._persist_sync( + request, digest, self._verdict(False, "standard", rule, self.config.rules_version) + ) + content_digest = bytes.fromhex(request.attachment.checksum[7:]) + cached = await self.repository.file_cache( + content_digest, self.config, self.signatures_version + ) + if cached: + return await self._persist_sync( + request, + digest, + self._verdict( + cached.verdict == "allow", + "standard", + cached.rule_id, + cached.rules_version, + ), + ) + now = datetime.now(UTC) + task_id = uuid.uuid4() + task = SafetyTask( + id=task_id, + message_id=request.message_id, + attachment_id=request.attachment.attachment_id, + request_fingerprint=digest, + content_sha256=content_digest, + processing_mode="standard", + config_version=self.config.version, + status=TaskStatus.pending, + attempt_count=0, + lease_generation=0, + expires_at=now + + timedelta(seconds=self.config.document["task"]["execution_deadline_sec"]), + quarantine_object_key=request.attachment.quarantine_object_key, + quarantine_version_id=request.attachment.quarantine_version_id, + quarantine_etag=request.attachment.quarantine_etag, + declared_mime=request.attachment.mime_type, + declared_size_bytes=request.attachment.size_bytes, + declared_checksum=request.attachment.checksum, + rules_version=self.config.rules_version, + detector_version=self.config.detector.version, + scanner_engine="clamav", + signatures_version=self.signatures_version, + created_at=now, + updated_at=now, + ) + row = SafetyRequest( + message_id=request.message_id, + request_fingerprint=digest, + processing_mode="standard", + config_version=self.config.version, + verdict="pending", + task_id=task_id, + rules_version=self.config.rules_version, + created_at=now, + purge_after=now + timedelta(days=30), + ) + try: + stored, created = await self.repository.reserve_request( + row, task, max_pending=self.config.document["task"]["max_pending"] + ) + except QueueFull as exc: + raise CapabilityUnavailable("queue_capacity") from exc + if created: + await self._audit( + request.message_id, + "task_created", + "standard", + "pending", + None, + task_id=task.id, + ) + return await self._replay(stored) + + async def _persist_sync( + self, request: CheckRequest, digest: bytes, verdict: Verdict + ) -> Verdict: + now = datetime.now(UTC) + row = SafetyRequest( + message_id=request.message_id, + request_fingerprint=digest, + processing_mode=verdict.processing_mode, + config_version=verdict.config_version, + verdict=verdict.verdict, + rule_id=verdict.rule_id, + reason_code=verdict.reason_code, + rules_version=verdict.rules_version, + created_at=now, + purge_after=now + timedelta(days=30), + ) + stored, created = await self.repository.reserve_request(row) + if created: + event = ( + f"mock_forced_{verdict.verdict}" + if verdict.processing_mode == "mock" + else ("rule_hit" if verdict.verdict == "deny" else "received") + ) + await self._audit( + request.message_id, + event, + verdict.processing_mode, + verdict.verdict, + verdict.rule_id, + ) + replay = await self._replay(stored) + assert isinstance(replay, Verdict) + return replay + + async def _replay(self, row: SafetyRequest) -> Verdict | Pending: + if row.verdict == "pending": + assert row.task_id + task = await self.repository.task(row.task_id) + if task and task.status in {TaskStatus.allowed, TaskStatus.denied}: + return self._verdict( + task.status == TaskStatus.allowed, + task.processing_mode, + task.rule_id or "safety.all_checks_passed", + task.rules_version, + config_version=task.config_version, + ) + if task and task.status == TaskStatus.failed: + raise TaskFailed(task.id) + assert task + return Pending( + config_version=task.config_version, + task_id=task.id, + expires_at=task.expires_at, + rules_version=task.rules_version, + ) + return Verdict( + verdict=row.verdict, + processing_mode=row.processing_mode, + config_version=row.config_version, + rule_id=row.rule_id or "safety.all_checks_passed", + reason_code=row.reason_code, + rules_version=row.rules_version, + ) + + async def _audit( + self, + message_id: uuid.UUID, + event: str, + mode: str, + verdict: str, + rule_id: str | None, + *, + task_id: uuid.UUID | None = None, + ) -> None: + now = datetime.now(UTC) + await self.repository.audit( + SafetyAudit( + id=uuid.uuid4(), + message_id=message_id, + task_id=task_id, + event=event, + processing_mode=mode, + config_version=self.config.version, + verdict=verdict, + rule_id=rule_id, + rules_version=self.config.rules_version if mode == "standard" else "mock", + normalization_flags=[], + created_at=now, + purge_after=now + timedelta(days=self.config.document["retention"]["audit_days"]), + ) + ) diff --git a/codebase/services/message-safety/app/settings.py b/codebase/services/message-safety/app/settings.py new file mode 100644 index 0000000..61026fa --- /dev/null +++ b/codebase/services/message-safety/app/settings.py @@ -0,0 +1,88 @@ +from __future__ import annotations + +import os +from pathlib import Path + +from pydantic import Field, SecretStr, model_validator +from pydantic_settings import BaseSettings, SettingsConfigDict + + +def _secret(name: str, *, required: bool = True) -> str | None: + """Read a secret only from NAME_FILE; values never enter repr/log output.""" + file_name = os.getenv(f"{name}_FILE") + if not file_name: + if required: + raise ValueError(f"{name}_FILE is required") + return None + path = Path(file_name) + value = path.read_text(encoding="utf-8").rstrip("\r\n") + if not value or value.startswith("<"): + raise ValueError(f"{name}_FILE contains an invalid value") + return value + + +class BootstrapSettings(BaseSettings): + model_config = SettingsConfigDict(extra="ignore", populate_by_name=True) + + app_env: str = Field(default="development", alias="APP_ENV") + process_role: str = Field(default="api", alias="MESSAGE_SAFETY_PROCESS_ROLE") + host: str = Field(default="0.0.0.0", alias="MESSAGE_SAFETY_HOST") # noqa: S104 + port: int = Field(default=8080, alias="MESSAGE_SAFETY_PORT") + worker_concurrency: int = Field( + default=5, ge=1, le=32, alias="MESSAGE_SAFETY_WORKER_CONCURRENCY" + ) + dns_resolvers: str = Field(default="", alias="MESSAGE_SAFETY_DNS_RESOLVERS") + clamav_host: str = Field(default="clamd", alias="MESSAGE_SAFETY_CLAMAV_HOST") + clamav_port: int = Field(default=3310, ge=1, le=65535, alias="MESSAGE_SAFETY_CLAMAV_PORT") + s3_endpoint_url: str = Field(alias="SELECTEL_S3_ENDPOINT_URL") + s3_bucket: str = Field(alias="SELECTEL_S3_BUCKET_QUARANTINE") + artifacts_dir: Path = Field( + default=Path("/app/app/artifacts"), alias="MESSAGE_SAFETY_ARTIFACTS_DIR" + ) + mode_file: Path = Field( + default=Path("/etc/han-chat/message-safety-mode.env"), + alias="MESSAGE_SAFETY_MODE_FILE", + ) + database_url: SecretStr | None = None + redis_url: SecretStr | None = None + service_token: SecretStr | None = None + s3_access_key: SecretStr | None = None + s3_secret_key: SecretStr | None = None + + @model_validator(mode="after") + def load_secret_files(self) -> BootstrapSettings: + self.database_url = SecretStr(_secret("MESSAGE_SAFETY_DATABASE_URL")) + self.redis_url = SecretStr(_secret("MESSAGE_SAFETY_REDIS_URL", required=False) or "") + if self.process_role == "api": + self.service_token = SecretStr(_secret("MESSAGE_SAFETY_SERVICE_TOKEN")) + elif self.process_role == "worker": + self.s3_access_key = SecretStr(_secret("SELECTEL_S3_QUARANTINE_READ_ACCESS_KEY")) + self.s3_secret_key = SecretStr(_secret("SELECTEL_S3_QUARANTINE_READ_SECRET_KEY")) + else: + raise ValueError("MESSAGE_SAFETY_PROCESS_ROLE must be api or worker") + return self + + +class EmergencyMode(BaseSettings): + model_config = SettingsConfigDict(extra="forbid", populate_by_name=True) + mock: bool = Field(default=False, alias="MESSAGE_SAFETY_MOCK_ENABLED") + text_free: bool = Field(default=False, alias="MESSAGE_SAFETY_MOCK_TEXT_FREE") + file_free: bool = Field(default=False, alias="MESSAGE_SAFETY_MOCK_FILE_FREE") + + @model_validator(mode="after") + def valid_flags(self) -> EmergencyMode: + if not self.mock and (self.text_free or self.file_free): + raise ValueError("free flags require MOCK=true") + return self + + @classmethod + def from_file(cls, path: Path) -> EmergencyMode: + values: dict[str, str] = {} + if path.exists(): + for line in path.read_text(encoding="utf-8").splitlines(): + if line and not line.startswith("#"): + key, sep, value = line.partition("=") + if not sep or key in values: + raise ValueError("invalid emergency mode file") + values[key] = value + return cls.model_validate(values) diff --git a/codebase/services/message-safety/app/url_policy.py b/codebase/services/message-safety/app/url_policy.py new file mode 100644 index 0000000..f9c5cb2 --- /dev/null +++ b/codebase/services/message-safety/app/url_policy.py @@ -0,0 +1,107 @@ +from __future__ import annotations + +import asyncio +import hashlib +import ipaddress +import re +from dataclasses import dataclass +from typing import Protocol +from urllib.parse import quote, unquote, urlsplit, urlunsplit + +import idna + +URL_CANDIDATE = re.compile(r"(?i)\b(?:[a-z][a-z0-9+.-]*://)[^\s<>{}\[\]\"']+") +METADATA = { + ipaddress.ip_address("169.254.169.254"), + ipaddress.ip_address("100.100.100.200"), + ipaddress.ip_address("fd00:ec2::254"), +} + + +class DnsError(RuntimeError): + pass + + +class DnsNxDomain(DnsError): + pass + + +class Resolver(Protocol): + async def resolve( + self, hostname: str + ) -> tuple[ipaddress.IPv4Address | ipaddress.IPv6Address, ...]: ... + + +@dataclass(frozen=True) +class CanonicalUrl: + value: str + digest: bytes + hostname: str + literal_ip: ipaddress.IPv4Address | ipaddress.IPv6Address | None + + +def extract_urls(text: str, *, maximum: int = 5, max_length: int = 2048) -> tuple[str, ...]: + values = tuple(match.group(0).rstrip(".,;:!?)]") for match in URL_CANDIDATE.finditer(text)) + if len(values) > maximum or any(len(value) > max_length for value in values): + raise ValueError("URL limits exceeded") + return values + + +def canonicalize(raw: str) -> CanonicalUrl: + parsed = urlsplit(raw) + if parsed.scheme.lower() not in {"http", "https"}: + raise PermissionError("url.forbidden_scheme") + if not parsed.hostname or parsed.username is not None or parsed.password is not None: + raise PermissionError("url.credentials_present" if parsed.username else "url.malformed") + try: + host = idna.encode(parsed.hostname, uts46=True, transitional=False).decode("ascii").lower() + except idna.IDNAError as exc: + raise PermissionError("url.confusable_host") from exc + try: + literal = ipaddress.ip_address(host) + if isinstance(literal, ipaddress.IPv6Address) and literal.ipv4_mapped: + literal = literal.ipv4_mapped + except ValueError: + literal = None + try: + parsed_port = parsed.port + except ValueError as exc: + raise PermissionError("url.malformed") from exc + port = ( + f":{parsed_port}" + if parsed_port and parsed_port != (443 if parsed.scheme == "https" else 80) + else "" + ) + path = quote(unquote(parsed.path or "/"), safe="/:@-._~!$&'()*+,;=") + query = quote(unquote(parsed.query), safe="=&/:?@-._~!$'()*+,;") + canonical = urlunsplit((parsed.scheme.lower(), host + port, path, query, "")) + return CanonicalUrl(canonical, hashlib.sha256(canonical.encode()).digest(), host, literal) + + +def classify_ip(address: ipaddress.IPv4Address | ipaddress.IPv6Address) -> str | None: + if isinstance(address, ipaddress.IPv6Address) and address.ipv4_mapped: + address = address.ipv4_mapped + if address in METADATA or address.is_private or address.is_loopback or address.is_link_local: + return "url.private_destination" + if address.is_multicast or address.is_unspecified or address.is_reserved: + return "url.reserved_destination" + return None + + +async def check_url( + raw: str, resolver: Resolver, timeout_sec: float = 1.0 +) -> tuple[CanonicalUrl, str | None]: + canonical = canonicalize(raw) + if canonical.literal_ip: + return canonical, classify_ip(canonical.literal_ip) + try: + addresses = await asyncio.wait_for(resolver.resolve(canonical.hostname), timeout_sec) + except DnsNxDomain: + return canonical, "url.nxdomain" + except (TimeoutError, DnsError) as exc: + raise DnsError("DNS dependency unavailable") from exc + for address in addresses: + denied = classify_ip(address) + if denied: + return canonical, denied + return canonical, None diff --git a/codebase/services/message-safety/app/worker.py b/codebase/services/message-safety/app/worker.py new file mode 100644 index 0000000..c9b49ce --- /dev/null +++ b/codebase/services/message-safety/app/worker.py @@ -0,0 +1,173 @@ +from __future__ import annotations + +import asyncio +import socket +import uuid +from datetime import UTC, datetime, timedelta + +from app.adapters import S3VersionReader +from app.config import validate_config +from app.contracts import Attachment +from app.db import FileVerdictCache, SafetyAudit, engine_and_sessions +from app.file_pipeline import ( + ClamAvInstream, + DependencyFailure, + ObjectChanged, + collect_and_hash, + detect_format, + one_chunk, +) +from app.repository import Repository +from app.settings import BootstrapSettings + + +class Worker: + def __init__( + self, repository: Repository, reader: S3VersionReader, antivirus: ClamAvInstream, artifacts + ) -> None: + self.repository, self.reader, self.antivirus, self.artifacts = ( + repository, + reader, + antivirus, + artifacts, + ) + self.owner = f"{socket.gethostname()}:{uuid.uuid4()}" + + async def once(self) -> bool: + task = await self.repository.claim(self.owner) + if not task: + return False + row = await self.repository.config_version(task.config_version) + rules, detector, digest = validate_config(row.config, self.artifacts) + if digest != row.config_sha256: + await self.repository.retry_or_fail(task, row.config["task"]["max_attempts"]) + return True + stop = asyncio.Event() + heartbeat = asyncio.create_task( + self._heartbeat( + task.id, + task.lease_generation, + row.config["task"]["heartbeat_sec"], + row.config["task"]["lease_sec"], + stop, + ) + ) + attachment = Attachment( + attachment_id=task.attachment_id, + quarantine_object_key=task.quarantine_object_key, + quarantine_version_id=task.quarantine_version_id, + quarantine_etag=task.quarantine_etag, + mime_type=task.declared_mime, + size_bytes=task.declared_size_bytes, + checksum=task.declared_checksum, + ) + try: + body, _ = await collect_and_hash( + self.reader, attachment, max_size=row.config["file_policy"]["max_size_bytes"] + ) + rule = detect_format(body, attachment.mime_type) + if not rule: + malware = await self.antivirus.scan(one_chunk(body)) + rule = "file.malware_detected" if malware else None + finished = await self.repository.finish( + task.id, + self.owner, + task.lease_generation, + allow=rule is None, + rule_id=rule or "safety.all_checks_passed", + ) + if finished: + now = datetime.now(UTC) + await self.repository.put_file_cache( + FileVerdictCache( + content_sha256=task.content_sha256, + config_version=task.config_version, + rules_version=task.rules_version, + detector_version=task.detector_version, + scanner_engine=task.scanner_engine, + signatures_version=task.signatures_version, + verdict="allow" if rule is None else "deny", + rule_id=rule or "safety.all_checks_passed", + reason_code=None if rule is None else "message_blocked", + created_at=now, + expires_at=now + + timedelta(seconds=row.config["cache"]["file_verdict_ttl_sec"]), + ) + ) + await self.repository.audit( + SafetyAudit( + id=uuid.uuid4(), + message_id=task.message_id, + task_id=task.id, + event="scan_completed", + processing_mode="standard", + config_version=task.config_version, + verdict="allow" if rule is None else "deny", + rule_id=rule or "safety.all_checks_passed", + rules_version=task.rules_version, + normalization_flags=[], + created_at=now, + purge_after=now + timedelta(days=row.config["retention"]["audit_days"]), + ) + ) + except ObjectChanged: + await self.repository.finish( + task.id, + self.owner, + task.lease_generation, + allow=False, + rule_id="file.object_changed", + ) + except DependencyFailure: + await self.repository.retry_or_fail(task, row.config["task"]["max_attempts"]) + finally: + stop.set() + await heartbeat + return True + + async def _heartbeat( + self, task_id, generation: int, interval: int, lease: int, stop: asyncio.Event + ) -> None: + while True: + try: + await asyncio.wait_for(stop.wait(), interval) + return + except TimeoutError: + if not await self.repository.heartbeat(task_id, self.owner, generation, lease): + return + + async def loop(self) -> None: + while True: + if not await self.once(): + await asyncio.sleep(0.5) + + +async def serve() -> None: + settings = BootstrapSettings() + assert settings.database_url and settings.s3_access_key and settings.s3_secret_key + engine, sessions = engine_and_sessions(settings.database_url.get_secret_value()) + worker = Worker( + Repository(sessions), + S3VersionReader( + settings.s3_endpoint_url, + settings.s3_bucket, + settings.s3_access_key.get_secret_value(), + settings.s3_secret_key.get_secret_value(), + ), + ClamAvInstream(settings.clamav_host, settings.clamav_port), + settings.artifacts_dir, + ) + try: + async with asyncio.TaskGroup() as group: + for _ in range(settings.worker_concurrency): + group.create_task(worker.loop()) + finally: + await engine.dispose() + + +def run() -> None: + asyncio.run(serve()) + + +if __name__ == "__main__": + run() diff --git a/codebase/services/message-safety/docker-compose.fragment.yml b/codebase/services/message-safety/docker-compose.fragment.yml new file mode 100644 index 0000000..0e0b2d1 --- /dev/null +++ b/codebase/services/message-safety/docker-compose.fragment.yml @@ -0,0 +1,58 @@ +services: + message-safety: + build: . + image: han/message-safety:${MESSAGE_SAFETY_IMAGE_TAG} + command: ["message-safety"] + user: "10001:10001" + read_only: true + init: true + restart: unless-stopped + expose: ["8080"] + env_file: + - /etc/han-chat/message-safety-bootstrap.env + - /etc/han-chat/message-safety-mode.env + environment: + MESSAGE_SAFETY_PROCESS_ROLE: api + MESSAGE_SAFETY_DATABASE_URL_FILE: /run/secrets/database_url + MESSAGE_SAFETY_REDIS_URL_FILE: /run/secrets/redis_url + MESSAGE_SAFETY_SERVICE_TOKEN_FILE: /run/secrets/service_token + secrets: [database_url, redis_url, service_token] + tmpfs: ["/tmp:rw,noexec,nosuid,nodev,size=64m"] + security_opt: ["no-new-privileges:true"] + cap_drop: [ALL] + pids_limit: 128 + mem_limit: 512m + cpus: 1.0 + networks: [backend, observability] + healthcheck: + test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/live', timeout=2)"] + interval: 10s + timeout: 3s + retries: 3 + + message-safety-worker: + image: han/message-safety:${MESSAGE_SAFETY_IMAGE_TAG} + command: ["message-safety-worker"] + user: "10001:10001" + read_only: true + init: true + restart: unless-stopped + env_file: + - /etc/han-chat/message-safety-bootstrap.env + - /etc/han-chat/message-safety-mode.env + environment: + MESSAGE_SAFETY_PROCESS_ROLE: worker + MESSAGE_SAFETY_DATABASE_URL_FILE: /run/secrets/database_url + MESSAGE_SAFETY_REDIS_URL_FILE: /run/secrets/redis_url + SELECTEL_S3_QUARANTINE_READ_ACCESS_KEY_FILE: /run/secrets/s3_access_key + SELECTEL_S3_QUARANTINE_READ_SECRET_KEY_FILE: /run/secrets/s3_secret_key + secrets: [database_url, redis_url, s3_access_key, s3_secret_key] + tmpfs: ["/tmp:rw,noexec,nosuid,nodev,size=64m"] + security_opt: ["no-new-privileges:true"] + cap_drop: [ALL] + pids_limit: 256 + mem_limit: 1536m + cpus: 2.0 + networks: [backend, egress, observability] + +# Root VM2 Compose owns these secret mappings and networks. diff --git a/codebase/services/message-safety/entrypoint.sh b/codebase/services/message-safety/entrypoint.sh new file mode 100644 index 0000000..787dfc5 --- /dev/null +++ b/codebase/services/message-safety/entrypoint.sh @@ -0,0 +1,24 @@ +#!/bin/sh +# Keep this executable LF-only: CRLF corrupts the Linux shebang. +set -eu +umask 077 + +required="MESSAGE_SAFETY_DATABASE_URL_FILE" +case "${MESSAGE_SAFETY_PROCESS_ROLE:-api}" in + api) required="$required MESSAGE_SAFETY_SERVICE_TOKEN_FILE" ;; + worker) + required="$required +SELECTEL_S3_QUARANTINE_READ_ACCESS_KEY_FILE +SELECTEL_S3_QUARANTINE_READ_SECRET_KEY_FILE" + ;; + *) echo "invalid MESSAGE_SAFETY_PROCESS_ROLE" >&2; exit 78 ;; +esac +for name in $required; do + eval "path=\${$name:-}" + if [ -z "$path" ] || [ ! -r "$path" ] || [ ! -s "$path" ]; then + echo "required secret file is unavailable: $name" >&2 + exit 78 + fi +done + +exec "$@" diff --git a/codebase/services/message-safety/openapi.yaml b/codebase/services/message-safety/openapi.yaml new file mode 100644 index 0000000..11a74ec --- /dev/null +++ b/codebase/services/message-safety/openapi.yaml @@ -0,0 +1,161 @@ +openapi: 3.1.0 +info: {title: HAN Message Safety Internal API, version: 2.0.0} +servers: [{url: https://processing.internal:8443}] +security: [{ServiceToken: []}] +paths: + /internal/safety/v2/messages/check: + post: + operationId: checkMessage + parameters: [{$ref: '#/components/parameters/RequestId'}, {$ref: '#/components/parameters/Traceparent'}] + requestBody: + required: true + content: + application/json: + schema: {$ref: '#/components/schemas/CheckRequest'} + responses: + '200': {$ref: '#/components/responses/Allow'} + '202': {$ref: '#/components/responses/Pending'} + '400': {$ref: '#/components/responses/Error'} + '401': {$ref: '#/components/responses/Error'} + '403': {$ref: '#/components/responses/Deny'} + '409': {$ref: '#/components/responses/Error'} + '429': {$ref: '#/components/responses/Error'} + '500': {$ref: '#/components/responses/Error'} + '503': {$ref: '#/components/responses/Error'} + /internal/safety/v2/messages/tasks/{task_id}: + get: + operationId: getMessageSafetyTask + parameters: + - {name: task_id, in: path, required: true, schema: {type: string, format: uuid}} + - {$ref: '#/components/parameters/RequestId'} + - {$ref: '#/components/parameters/Traceparent'} + responses: + '200': {$ref: '#/components/responses/Allow'} + '202': {$ref: '#/components/responses/Pending'} + '400': {$ref: '#/components/responses/Error'} + '401': {$ref: '#/components/responses/Error'} + '403': {$ref: '#/components/responses/Deny'} + '404': {$ref: '#/components/responses/Error'} + '429': {$ref: '#/components/responses/Error'} + '500': {$ref: '#/components/responses/Error'} + '503': {$ref: '#/components/responses/Error'} + /health/live: + get: + security: [] + responses: + '200': + description: Process is alive + content: {application/json: {schema: {type: object, additionalProperties: false, required: [status], properties: {status: {const: ok}}}}} + /health/ready: + get: + security: [] + responses: + '200': {$ref: '#/components/responses/Health'} + '503': {$ref: '#/components/responses/Health'} +components: + securitySchemes: + ServiceToken: {type: apiKey, in: header, name: X-Service-Token} + parameters: + RequestId: {name: X-Request-ID, in: header, required: false, schema: {type: string, format: uuid}} + Traceparent: {name: traceparent, in: header, required: false, schema: {type: string, maxLength: 256}} + schemas: + Attachment: + type: object + additionalProperties: false + required: [attachment_id, quarantine_object_key, quarantine_version_id, quarantine_etag, mime_type, size_bytes, checksum] + properties: + attachment_id: {type: string, format: uuid} + quarantine_object_key: {type: string, minLength: 1, maxLength: 1024} + quarantine_version_id: {type: string, minLength: 1, maxLength: 512} + quarantine_etag: {type: string, minLength: 1, maxLength: 512} + mime_type: {enum: [image/jpeg, image/png, image/webp, image/heic, image/heif, application/pdf]} + size_bytes: {type: integer, minimum: 1, maximum: 5242880} + checksum: {type: string, pattern: '^sha256:[0-9a-f]{64}$'} + TextCheck: + type: object + additionalProperties: false + required: [message_id, content_kind, text, attachment] + properties: + message_id: {type: string, format: uuid} + content_kind: {const: text} + text: {type: string, minLength: 1, maxLength: 10000} + attachment: {type: 'null'} + FileCheck: + type: object + additionalProperties: false + required: [message_id, content_kind, text, attachment] + properties: + message_id: {type: string, format: uuid} + content_kind: {const: file} + text: {const: ''} + attachment: {$ref: '#/components/schemas/Attachment'} + CheckRequest: + oneOf: [{$ref: '#/components/schemas/TextCheck'}, {$ref: '#/components/schemas/FileCheck'}] + discriminator: {propertyName: content_kind, mapping: {text: '#/components/schemas/TextCheck', file: '#/components/schemas/FileCheck'}} + Verdict: + type: object + additionalProperties: false + required: [verdict, processing_mode, config_version, rule_id, rules_version] + properties: + verdict: {enum: [allow, deny]} + processing_mode: {enum: [standard, mock]} + config_version: {type: integer, minimum: 1} + rule_id: {type: string} + reason_code: {enum: [message_blocked]} + rules_version: {type: string} + Pending: + type: object + additionalProperties: false + required: [verdict, processing_mode, config_version, task_id, poll_after_ms, expires_at, rules_version] + properties: + verdict: {const: pending} + processing_mode: {const: standard} + config_version: {type: integer} + task_id: {type: string, format: uuid} + poll_after_ms: {type: integer, minimum: 1} + expires_at: {type: string, format: date-time} + rules_version: {type: string} + Error: + type: object + additionalProperties: false + required: [error] + properties: + error: + type: object + additionalProperties: false + required: [code, message, request_id, details] + properties: + code: {enum: [validation_error, service_unauthorized, task_not_found, safety_request_conflict, rate_limit_exceeded, dependency_unavailable, task_failed, internal_error]} + message: {type: string} + request_id: {type: string} + details: {type: object} + Health: + type: object + required: [status, processing_mode, config_version, components, capabilities] + properties: + status: {enum: [ok, degraded, not_ready]} + processing_mode: {enum: [standard, mock]} + config_version: {type: integer} + components: {type: object, additionalProperties: {enum: [ok, degraded, down, bypassed]}} + capabilities: {type: object, additionalProperties: {enum: [ready, unavailable, bypassed]}} + mock_policy: {type: object, additionalProperties: {enum: [allow, deny]}} + responses: + Allow: + description: Sticky allow verdict + content: {application/json: {schema: {$ref: '#/components/schemas/Verdict'}}} + Deny: + description: Sticky domain deny + content: {application/json: {schema: {$ref: '#/components/schemas/Verdict'}}} + Pending: + description: Asynchronous file check + headers: + Location: {required: true, schema: {type: string}} + Retry-After: {required: true, schema: {type: integer}} + Cache-Control: {required: true, schema: {const: no-store}} + content: {application/json: {schema: {$ref: '#/components/schemas/Pending'}}} + Error: + description: Error envelope + content: {application/json: {schema: {$ref: '#/components/schemas/Error'}}} + Health: + description: Capability-aware readiness + content: {application/json: {schema: {$ref: '#/components/schemas/Health'}}} diff --git a/codebase/services/message-safety/pyproject.toml b/codebase/services/message-safety/pyproject.toml new file mode 100644 index 0000000..ab9f5ed --- /dev/null +++ b/codebase/services/message-safety/pyproject.toml @@ -0,0 +1,48 @@ +[project] +name = "han-message-safety" +version = "0.1.0" +requires-python = ">=3.12" +dependencies = [ + "alembic>=1.13", + "asyncpg>=0.29", + "boto3>=1.34", + "dnspython>=2.6", + "fastapi>=0.115", + "httpx>=0.27", + "idna>=3.7", + "jsonschema>=4.23", + "pillow>=10.4", + "pillow-heif>=0.18", + "pydantic-settings>=2.5", + "pyyaml>=6.0", + "redis>=5.0", + "sqlalchemy[asyncio]>=2.0", + "uvicorn>=0.30", +] + +[project.optional-dependencies] +dev = ["pytest>=8.3", "pytest-asyncio>=0.24", "ruff>=0.6"] + +[project.scripts] +message-safety = "app.main:run" +message-safety-worker = "app.worker:run" +message-safety-config = "app.config_admin:main" + +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + +[tool.hatch.build.targets.wheel] +packages = ["app"] + +[tool.pytest.ini_options] +asyncio_mode = "auto" +testpaths = ["tests"] + +[tool.ruff] +target-version = "py312" +line-length = 100 + +[tool.ruff.lint] +select = ["E", "F", "I", "B", "UP", "ASYNC", "S"] +ignore = ["S101"] diff --git a/codebase/services/message-safety/tests/conftest.py b/codebase/services/message-safety/tests/conftest.py new file mode 100644 index 0000000..5251184 --- /dev/null +++ b/codebase/services/message-safety/tests/conftest.py @@ -0,0 +1,20 @@ +from __future__ import annotations + +from pathlib import Path + +import pytest +import yaml + +from app.config import ActiveConfig, validate_config + + +@pytest.fixture +def artifacts() -> Path: + return Path(__file__).parents[1] / "app" / "artifacts" + + +@pytest.fixture +def active_config(artifacts: Path) -> ActiveConfig: + document = yaml.safe_load((artifacts / "seed-config.yaml").read_text(encoding="utf-8")) + rules, detector, _ = validate_config(document, artifacts) + return ActiveConfig(1, document, rules, detector) diff --git a/codebase/services/message-safety/tests/test_api_contract.py b/codebase/services/message-safety/tests/test_api_contract.py new file mode 100644 index 0000000..691a0a1 --- /dev/null +++ b/codebase/services/message-safety/tests/test_api_contract.py @@ -0,0 +1,190 @@ +from __future__ import annotations + +from uuid import uuid4 + +import httpx +import pytest + +from app.api import create_app +from app.db import TaskStatus +from app.repository import ConflictError +from app.service import SafetyService +from app.settings import EmergencyMode + + +class FakeRepository: + def __init__(self) -> None: + self.requests = {} + self.text = {} + self.tasks = {} + self.audits = [] + + async def get_request(self, message_id): + return self.requests.get(message_id) + + async def reserve_request(self, row, task=None, **kwargs): + existing = self.requests.get(row.message_id) + if existing: + if existing.request_fingerprint != row.request_fingerprint: + raise ConflictError + return existing, False + self.requests[row.message_id] = row + if task: + self.tasks[task.id] = task + return row, True + + async def text_cache(self, digest, version): + return self.text.get((digest, version)) + + async def put_text_cache(self, row): + self.text[(row.analysis_sha256, row.rules_version)] = row + + async def file_cache(self, digest, config, signatures_version): + return None + + async def task(self, task_id): + return self.tasks.get(task_id) + + async def audit(self, row): + self.audits.append(row) + + +class ForbiddenResolver: + async def resolve(self, hostname): + raise AssertionError("MOCK must not call DNS") + + +def body(kind: str, message_id=None) -> dict: + value = { + "message_id": str(message_id or uuid4()), + "content_kind": kind, + "text": "hello" if kind == "text" else "", + "attachment": None, + } + if kind == "file": + value["attachment"] = { + "attachment_id": str(uuid4()), + "quarantine_object_key": ( + "quarantine/users/00000000-0000-4000-8000-000000000001/" + "dialogs/00000000-0000-4000-8000-000000000002/" + "00000000-0000-4000-8000-000000000003" + ), + "quarantine_version_id": "v1", + "quarantine_etag": '"e"', + "mime_type": "application/pdf", + "size_bytes": 10, + "checksum": "sha256:" + "0" * 64, + } + return value + + +@pytest.mark.parametrize( + "text_free,file_free,kind,status", + [ + (True, True, "text", 200), + (True, True, "file", 200), + (True, False, "text", 200), + (True, False, "file", 403), + (False, True, "text", 403), + (False, True, "file", 200), + (False, False, "text", 403), + (False, False, "file", 403), + ], +) +async def test_mock_2x2_is_sync(active_config, text_free, file_free, kind, status) -> None: + repo = FakeRepository() + service = SafetyService( + repo, + active_config, + EmergencyMode(mock=True, text_free=text_free, file_free=file_free), + ForbiddenResolver(), + ) + async with httpx.AsyncClient( + transport=httpx.ASGITransport(app=create_app(service, "secret")), + base_url="http://test", + headers={"X-Service-Token": "secret"}, + ) as client: + response = await client.post("/internal/safety/v2/messages/check", json=body(kind)) + assert response.status_code == status + assert response.json()["processing_mode"] == "mock" + assert response.json()["verdict"] in {"allow", "deny"} + assert len(repo.audits) == 1 + + +async def test_auth_strict_dto_idempotency_and_conflict(active_config) -> None: + repo = FakeRepository() + service = SafetyService(repo, active_config, EmergencyMode(), ForbiddenResolver()) + app = create_app(service, "secret") + message_id = uuid4() + async with httpx.AsyncClient( + transport=httpx.ASGITransport(app=app), base_url="http://test" + ) as client: + assert ( + await client.post("/internal/safety/v2/messages/check", json=body("text")) + ).status_code == 401 + invalid = body("text") + invalid["unknown"] = True + assert ( + await client.post( + "/internal/safety/v2/messages/check", + json=invalid, + headers={"X-Service-Token": "secret"}, + ) + ).status_code == 400 + headers = {"X-Service-Token": "secret"} + first = await client.post( + "/internal/safety/v2/messages/check", json=body("text", message_id), headers=headers + ) + replay = await client.post( + "/internal/safety/v2/messages/check", json=body("text", message_id), headers=headers + ) + changed = body("text", message_id) + changed["text"] = "different" + conflict = await client.post( + "/internal/safety/v2/messages/check", json=changed, headers=headers + ) + assert first.status_code == replay.status_code == 200 + assert first.json() == replay.json() + assert conflict.status_code == 409 + + +async def test_standard_text_deny_and_file_pending(active_config) -> None: + repo = FakeRepository() + service = SafetyService(repo, active_config, EmergencyMode(), ForbiddenResolver()) + async with httpx.AsyncClient( + transport=httpx.ASGITransport(app=create_app(service, "secret")), + base_url="http://test", + headers={"X-Service-Token": "secret"}, + ) as client: + denied = body("text") + denied["text"] = "" + deny_response = await client.post("/internal/safety/v2/messages/check", json=denied) + pending_response = await client.post( + "/internal/safety/v2/messages/check", json=body("file") + ) + task_response = await client.get(pending_response.headers["Location"]) + assert deny_response.status_code == 403 + assert deny_response.json()["rule_id"] == "text.active_script" + assert pending_response.status_code == task_response.status_code == 202 + assert pending_response.json() == task_response.json() + assert pending_response.headers["Retry-After"] == "2" + + +async def test_final_task_response_keeps_task_config_snapshot(active_config) -> None: + repo = FakeRepository() + service = SafetyService(repo, active_config, EmergencyMode(), ForbiddenResolver()) + async with httpx.AsyncClient( + transport=httpx.ASGITransport(app=create_app(service, "secret")), + base_url="http://test", + headers={"X-Service-Token": "secret"}, + ) as client: + pending = await client.post("/internal/safety/v2/messages/check", json=body("file")) + task = repo.tasks[next(iter(repo.tasks))] + task.status = TaskStatus.allowed + task.verdict = "allow" + task.rule_id = "safety.all_checks_passed" + task.config_version = 99 + final = await client.get(pending.headers["Location"]) + + assert final.status_code == 200 + assert final.json()["config_version"] == 99 diff --git a/codebase/services/message-safety/tests/test_config_and_schema.py b/codebase/services/message-safety/tests/test_config_and_schema.py new file mode 100644 index 0000000..e724bf7 --- /dev/null +++ b/codebase/services/message-safety/tests/test_config_and_schema.py @@ -0,0 +1,76 @@ +from __future__ import annotations + +import ast +import copy +import re +from pathlib import Path + +import pytest +import yaml + +from app.config import validate_config +from app.db import Base + + +def seed(artifacts: Path): + return yaml.safe_load((artifacts / "seed-config.yaml").read_text(encoding="utf-8")) + + +def test_seed_config_and_artifact_hashes(artifacts: Path) -> None: + rules, detector, digest = validate_config(seed(artifacts), artifacts) + assert rules.version == "2026-01-01" + assert detector.version.startswith("sha256:") + assert len(digest) == 32 + + +def test_config_cross_field_and_manifest_subset(artifacts: Path) -> None: + bad = copy.deepcopy(seed(artifacts)) + bad["task"]["heartbeat_sec"] = bad["task"]["lease_sec"] + with pytest.raises(ValueError): + validate_config(bad, artifacts) + bad = copy.deepcopy(seed(artifacts)) + bad["file_policy"]["enabled_mime_types"].append("application/zip") + with pytest.raises(ValueError): + validate_config(bad, artifacts) + + +def test_normative_tables_are_in_service_schema() -> None: + expected = { + "safety_requests", + "safety_tasks", + "file_verdict_cache", + "text_rules_cache", + "link_verdict_cache", + "safety_audit", + "config_versions", + } + assert expected <= {table.name for table in Base.metadata.tables.values()} + assert {table.schema for table in Base.metadata.tables.values()} == {"message_safety"} + + +def test_migration_executes_asyncpg_statements_separately() -> None: + migration = ( + Path(__file__).parents[1] + / "alembic" + / "versions" + / "0001_message_safety_v2.py" + ) + tree = ast.parse(migration.read_text(encoding="utf-8")) + upgrade = next( + node + for node in tree.body + if isinstance(node, ast.FunctionDef) and node.name == "upgrade" + ) + statements = [ + call.args[0].value + for call in ast.walk(upgrade) + if isinstance(call, ast.Call) + and isinstance(call.func, ast.Attribute) + and call.func.attr == "execute" + and call.args + and isinstance(call.args[0], ast.Constant) + and isinstance(call.args[0].value, str) + ] + + assert len(statements) == 5 + assert all(re.search(r"\$\$;\s+\S", statement) is None for statement in statements) diff --git a/codebase/services/message-safety/tests/test_determinism.py b/codebase/services/message-safety/tests/test_determinism.py new file mode 100644 index 0000000..4a68844 --- /dev/null +++ b/codebase/services/message-safety/tests/test_determinism.py @@ -0,0 +1,40 @@ +from __future__ import annotations + +from uuid import UUID + +import pytest + +from app.contracts import TextCheck +from app.fingerprint import canonical_json, fingerprint +from app.normalization import normalize_text + + +def test_jcs_field_order_and_unicode_are_deterministic() -> None: + left = {"z": None, "а": "е\u0301", "a": 1} + right = {"a": 1, "z": None, "а": "е\u0301"} + assert canonical_json(left) == canonical_json(right) + assert fingerprint(left) == fingerprint(right) + assert canonical_json(left).decode() == '{"a":1,"z":null,"а":"е́"}' + + +def test_dto_fingerprint_contains_explicit_null() -> None: + dto = TextCheck( + message_id=UUID("00000000-0000-4000-8000-000000000001"), + content_kind="text", + text="hello", + attachment=None, + ) + assert b'"attachment":null' in canonical_json(dto) + assert len(fingerprint(dto)) == 32 + + +def test_normalization_nfkc_whitespace_and_flags() -> None: + result = normalize_text("Ａ\r\nB\u200b\u202e C") + assert result.display.startswith("A\nB") + assert result.analysis == "A\nB C" + assert result.flags == ("bidi_control", "default_ignorable", "zero_width") + + +def test_normalization_hard_limit() -> None: + with pytest.raises(ValueError): + normalize_text("x" * 10_001) diff --git a/codebase/services/message-safety/tests/test_files.py b/codebase/services/message-safety/tests/test_files.py new file mode 100644 index 0000000..f70809e --- /dev/null +++ b/codebase/services/message-safety/tests/test_files.py @@ -0,0 +1,73 @@ +from __future__ import annotations + +import hashlib +import io +from uuid import UUID + +import pytest +from PIL import Image + +from app.contracts import Attachment +from app.file_pipeline import ObjectChanged, collect_and_hash, detect_format + + +def image_bytes(format_name: str) -> bytes: + output = io.BytesIO() + Image.new("RGB", (2, 2), "white").save(output, format=format_name) + return output.getvalue() + + +@pytest.mark.parametrize( + "format_name,mime", + [("JPEG", "image/jpeg"), ("PNG", "image/png"), ("WEBP", "image/webp")], +) +def test_bounded_image_detector(format_name: str, mime: str) -> None: + assert detect_format(image_bytes(format_name), mime) is None + assert detect_format(image_bytes(format_name), "application/pdf") == "file.format_mismatch" + + +def test_pdf_active_encrypted_and_malformed() -> None: + clean = b"%PDF-1.7\n1 0 obj <<>> endobj\nstartxref\n0\n%%EOF" + assert detect_format(clean, "application/pdf") is None + assert ( + detect_format(clean.replace(b"<<>>", b"<>"), "application/pdf") + == "file.encrypted_content" + ) + assert ( + detect_format(clean.replace(b"<<>>", b"<>"), "application/pdf") + == "file.active_content" + ) + assert detect_format(b"%PDF-1.7 no eof", "application/pdf") == "file.polyglot_or_ambiguous" + + +class Reader: + def __init__(self, data: bytes) -> None: + self.data = data + + async def stream(self, attachment): + yield self.data[:2] + yield self.data[2:] + + +def attachment(data: bytes, *, size: int | None = None) -> Attachment: + return Attachment( + attachment_id=UUID("00000000-0000-4000-8000-000000000003"), + quarantine_object_key=( + "quarantine/users/00000000-0000-4000-8000-000000000001/" + "dialogs/00000000-0000-4000-8000-000000000002/" + "00000000-0000-4000-8000-000000000003" + ), + quarantine_version_id="v1", + quarantine_etag='"etag"', + mime_type="application/pdf", + size_bytes=size or len(data), + checksum="sha256:" + hashlib.sha256(data).hexdigest(), + ) + + +async def test_authoritative_stream_hash_and_size() -> None: + data = b"content" + body, digest = await collect_and_hash(Reader(data), attachment(data), max_size=100) + assert body == data and digest == hashlib.sha256(data).digest() + with pytest.raises(ObjectChanged): + await collect_and_hash(Reader(data), attachment(data, size=len(data) + 1), max_size=100) diff --git a/codebase/services/message-safety/tests/test_openapi.py b/codebase/services/message-safety/tests/test_openapi.py new file mode 100644 index 0000000..35bc5b9 --- /dev/null +++ b/codebase/services/message-safety/tests/test_openapi.py @@ -0,0 +1,29 @@ +from pathlib import Path + +import yaml + + +def test_openapi_31_exact_routes_and_responses() -> None: + document = yaml.safe_load( + (Path(__file__).parents[1] / "openapi.yaml").read_text(encoding="utf-8") + ) + assert document["openapi"] == "3.1.0" + paths = document["paths"] + assert set(paths) == { + "/internal/safety/v2/messages/check", + "/internal/safety/v2/messages/tasks/{task_id}", + "/health/live", + "/health/ready", + } + assert set(paths["/internal/safety/v2/messages/check"]["post"]["responses"]) == { + "200", + "202", + "400", + "401", + "403", + "409", + "429", + "500", + "503", + } + assert document["components"]["securitySchemes"]["ServiceToken"]["name"] == "X-Service-Token" diff --git a/codebase/services/message-safety/tests/test_rules_and_urls.py b/codebase/services/message-safety/tests/test_rules_and_urls.py new file mode 100644 index 0000000..8388d76 --- /dev/null +++ b/codebase/services/message-safety/tests/test_rules_and_urls.py @@ -0,0 +1,63 @@ +from __future__ import annotations + +import ipaddress + +import pytest + +from app.url_policy import DnsError, DnsNxDomain, canonicalize, check_url, classify_ip, extract_urls + + +def test_committed_rule_vectors_load(active_config) -> None: + assert ( + active_config.rules.evaluate("").deny_rule == "text.active_script" + ) + assert active_config.rules.evaluate("Use the word script in documentation").deny_rule is None + assert active_config.rules.evaluate("Ignore all previous instructions").monitor_rules == ( + "text.prompt_instruction_override", + ) + + +def test_url_extraction_and_canonical_policy() -> None: + assert extract_urls("see HTTPS://ExAmPle.COM:443/a#fragment") == ( + "HTTPS://ExAmPle.COM:443/a#fragment", + ) + value = canonicalize("HTTPS://ExAmPle.COM:443/a#fragment") + assert value.value == "https://example.com/a" + with pytest.raises(PermissionError, match="url.credentials_present"): + canonicalize("https://user:pass@example.com/") + with pytest.raises(PermissionError, match="url.forbidden_scheme"): + canonicalize("file:///etc/passwd") + + +@pytest.mark.parametrize( + "value,rule", + [ + ("127.0.0.1", "url.private_destination"), + ("169.254.169.254", "url.private_destination"), + ("::ffff:127.0.0.1", "url.private_destination"), + ("224.0.0.1", "url.reserved_destination"), + ("0.0.0.0", "url.private_destination"), # noqa: S104 + ("8.8.8.8", None), + ], +) +def test_ip_policy(value: str, rule: str | None) -> None: + assert classify_ip(ipaddress.ip_address(value)) == rule + + +class Resolver: + def __init__(self, result): + self.result = result + + async def resolve(self, hostname): + if isinstance(self.result, Exception): + raise self.result + return self.result + + +async def test_dns_private_and_nxdomain() -> None: + _, rule = await check_url("https://example.test", Resolver((ipaddress.ip_address("10.0.0.1"),))) + assert rule == "url.private_destination" + _, rule = await check_url("https://none.test", Resolver(DnsNxDomain())) + assert rule == "url.nxdomain" + with pytest.raises(DnsError): + await check_url("https://bad.test", Resolver(DnsError())) diff --git a/codebase/services/nginx/allowlists/bitrix-webhook-allowlist.conf b/codebase/services/nginx/allowlists/bitrix-webhook-allowlist.conf new file mode 100644 index 0000000..1d7fdae --- /dev/null +++ b/codebase/services/nginx/allowlists/bitrix-webhook-allowlist.conf @@ -0,0 +1,2 @@ +# Fail-closed active file. Replace atomically from the reviewed .template file. +deny all; diff --git a/codebase/services/nginx/allowlists/bitrix-webhook-allowlist.conf.template b/codebase/services/nginx/allowlists/bitrix-webhook-allowlist.conf.template new file mode 100644 index 0000000..20c44b1 --- /dev/null +++ b/codebase/services/nginx/allowlists/bitrix-webhook-allowlist.conf.template @@ -0,0 +1,5 @@ +# Copy to bitrix-webhook-allowlist.conf only after ownership verification. +# One reviewed directive per confirmed Bitrix24 source CIDR: +# allow 192.0.2.10/32; +# allow 2001:db8::10/128; +deny all; diff --git a/codebase/services/nginx/allowlists/private-caller-allowlist.conf b/codebase/services/nginx/allowlists/private-caller-allowlist.conf new file mode 100644 index 0000000..1219329 --- /dev/null +++ b/codebase/services/nginx/allowlists/private-caller-allowlist.conf @@ -0,0 +1,3 @@ +# Fail-closed active file. Replace atomically from the reviewed .template file. +allow 192.168.0.1; +deny all; diff --git a/codebase/services/nginx/allowlists/private-caller-allowlist.conf.template b/codebase/services/nginx/allowlists/private-caller-allowlist.conf.template new file mode 100644 index 0000000..e5ca655 --- /dev/null +++ b/codebase/services/nginx/allowlists/private-caller-allowlist.conf.template @@ -0,0 +1,4 @@ +# VM1 and approved ops private source CIDRs only: +# allow 10.20.0.10/32; +# allow 10.20.1.0/28; +deny all; diff --git a/codebase/services/nginx/allowlists/proxy-common.conf b/codebase/services/nginx/allowlists/proxy-common.conf new file mode 100644 index 0000000..a59a091 --- /dev/null +++ b/codebase/services/nginx/allowlists/proxy-common.conf @@ -0,0 +1,14 @@ +proxy_http_version 1.1; +proxy_set_header Connection ""; +proxy_set_header Host $host; +proxy_set_header X-Real-IP $remote_addr; +proxy_set_header X-Forwarded-For $remote_addr; +proxy_set_header X-Forwarded-Proto https; +proxy_set_header X-Forwarded-Host $host; +proxy_set_header X-Forwarded-Port $server_port; +proxy_set_header X-Request-ID $request_id; +proxy_connect_timeout 3s; +proxy_send_timeout 15s; +proxy_request_buffering on; +proxy_buffering off; +proxy_intercept_errors off; diff --git a/codebase/services/nginx/allowlists/tls.conf b/codebase/services/nginx/allowlists/tls.conf new file mode 100644 index 0000000..e33afcf --- /dev/null +++ b/codebase/services/nginx/allowlists/tls.conf @@ -0,0 +1,5 @@ +ssl_protocols TLSv1.2 TLSv1.3; +ssl_session_cache shared:TLS:10m; +ssl_session_timeout 10m; +ssl_session_tickets off; +ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256; diff --git a/codebase/services/nginx/nginx.conf b/codebase/services/nginx/nginx.conf new file mode 100644 index 0000000..ecc7d1a --- /dev/null +++ b/codebase/services/nginx/nginx.conf @@ -0,0 +1,33 @@ +worker_processes auto; +pid /tmp/nginx.pid; +error_log /dev/stderr warn; + +events { + worker_connections 2048; +} + +http { + include /etc/nginx/mime.types; + default_type application/octet-stream; + server_tokens off; + + log_format safe_json escape=json + '{"time":"$time_iso8601","request_id":"$request_id","remote_addr":"$remote_addr",' + '"host":"$host","method":"$request_method","uri":"$uri","status":$status,' + '"bytes":$body_bytes_sent,"duration":$request_time,' + '"upstream_status":"$upstream_status","upstream_time":"$upstream_response_time"}'; + access_log /dev/stdout safe_json; + + limit_req_status 429; + limit_req_zone $binary_remote_addr zone=bitrix_webhooks:10m rate=30r/m; + limit_conn_zone $binary_remote_addr zone=per_ip:10m; + + client_body_temp_path /tmp/client_body; + proxy_temp_path /tmp/proxy; + client_header_timeout 10s; + client_body_timeout 15s; + keepalive_timeout 30s; + send_timeout 30s; + + include /etc/nginx/conf.d/10-vm2.conf; +} diff --git a/codebase/services/nginx/templates/10-vm2.conf.template b/codebase/services/nginx/templates/10-vm2.conf.template new file mode 100644 index 0000000..248391e --- /dev/null +++ b/codebase/services/nginx/templates/10-vm2.conf.template @@ -0,0 +1,131 @@ +upstream message_safety_api { + server ${MESSAGE_SAFETY_UPSTREAM_HOST}:8080; + keepalive 16; +} + +upstream bitrix_sync { + server ${BITRIX_SYNC_UPSTREAM_HOST}:8080; + keepalive 16; +} + +server { + listen 8081; + location = /nginx-health/live { + access_log off; + return 200 "ok\n"; + } + location / { + return 404; + } +} + +server { + listen 8080; + server_name ${PROCESSING_PUBLIC_HOST}; + + location ^~ /.well-known/acme-challenge/ { + root /var/www/certbot; + try_files $uri =404; + } + + location = /bitrix/sync/webhook/contact { + return 426; + } + location = /bitrix/sync/webhook/alert { + return 426; + } + location / { + return 308 https://$host$request_uri; + } +} + +server { + listen 8444 ssl; + http2 on; + server_name ${PROCESSING_PUBLIC_HOST}; + + ssl_certificate /run/public-tls/fullchain.pem; + ssl_certificate_key /run/public-tls/privkey.pem; + include /etc/nginx/allowlists/tls.conf; + + add_header Strict-Transport-Security "max-age=31536000" always; + add_header X-Content-Type-Options nosniff always; + add_header Referrer-Policy no-referrer always; + add_header Cache-Control no-store always; + + location = /bitrix/sync/webhook/contact { + # Core error logs include the raw request line and cannot redact query. + error_log /dev/null crit; + if ($request_method != POST) { return 405; } + include /etc/nginx/allowlists/bitrix-webhook-allowlist.conf; + limit_req zone=bitrix_webhooks burst=20 nodelay; + limit_conn per_ip 10; + client_max_body_size 128k; + proxy_pass http://bitrix_sync; + include /etc/nginx/allowlists/proxy-common.conf; + proxy_read_timeout 60s; + } + + location = /bitrix/sync/webhook/alert { + # Rejections remain visible in query-free access logs and metrics. + error_log /dev/null crit; + if ($request_method != POST) { return 405; } + include /etc/nginx/allowlists/bitrix-webhook-allowlist.conf; + limit_req zone=bitrix_webhooks burst=20 nodelay; + limit_conn per_ip 10; + client_max_body_size 128k; + proxy_pass http://bitrix_sync; + include /etc/nginx/allowlists/proxy-common.conf; + proxy_read_timeout 60s; + } + + location / { + return 404; + } +} + +server { + listen 8443 ssl; + server_name _; + + ssl_certificate /run/secrets/internal_tls_certificate; + ssl_certificate_key /run/secrets/internal_tls_private_key; + include /etc/nginx/allowlists/tls.conf; + + include /etc/nginx/allowlists/private-caller-allowlist.conf; + client_max_body_size 256k; + add_header Cache-Control no-store always; + add_header X-Content-Type-Options nosniff always; + + location = /internal/safety/v2/messages/check { + if ($request_method != POST) { return 405; } + proxy_pass http://message_safety_api; + include /etc/nginx/allowlists/proxy-common.conf; + proxy_read_timeout 10s; + } + + location ~ "^/internal/safety/v2/messages/tasks/[0-9a-fA-F-]{36}$" { + if ($request_method != GET) { return 405; } + proxy_pass http://message_safety_api; + include /etc/nginx/allowlists/proxy-common.conf; + proxy_read_timeout 5s; + } + + location = /internal/safety/status { + if ($request_method != GET) { return 405; } + proxy_pass http://message_safety_api/health/ready; + include /etc/nginx/allowlists/proxy-common.conf; + proxy_read_timeout 60s; + } + + location = /internal/sync/v1/status { + if ($request_method != GET) { return 405; } + proxy_pass http://bitrix_sync; + include /etc/nginx/allowlists/proxy-common.conf; + proxy_read_timeout 60s; + } + + location / { + return 404; + } +} diff --git a/codebase/services/observability/otel-collector.yaml b/codebase/services/observability/otel-collector.yaml new file mode 100644 index 0000000..361aa57 --- /dev/null +++ b/codebase/services/observability/otel-collector.yaml @@ -0,0 +1,76 @@ +extensions: + health_check: + endpoint: 0.0.0.0:13133 + file_storage: + directory: /var/lib/otelcol/queue + +receivers: + otlp: + protocols: + grpc: + endpoint: 0.0.0.0:4317 + http: + endpoint: 0.0.0.0:4318 + +processors: + memory_limiter: + check_interval: 1s + limit_mib: 384 + spike_limit_mib: 96 + resource/vm2: + attributes: + - {key: service.namespace, value: han-processing, action: upsert} + - {key: deployment.environment, value: "${env:APP_ENV}", action: upsert} + - {key: service.version, value: "${env:RELEASE_VERSION}", action: upsert} + attributes/redact: + actions: + - {key: http.request.header.authorization, action: delete} + - {key: http.request.header.cookie, action: delete} + - {key: url.query, action: delete} + - {key: url.full, action: delete} + - {key: http.target, action: delete} + - {key: http.request.body, action: delete} + - {key: http.response.body, action: delete} + - {key: db.statement, action: delete} + - {key: db.query.text, action: delete} + - {key: enduser.id, action: delete} + - {key: user.phone, action: delete} + - {key: user.email, action: delete} + - {key: messaging.message.body, action: delete} + - {key: aws.s3.key, action: delete} + - {key: s3.object.key, action: delete} + batch: + timeout: 5s + send_batch_size: 1024 + send_batch_max_size: 2048 + +exporters: + otlp/remote: + endpoint: "${env:OTEL_REMOTE_ENDPOINT}" + tls: + insecure: "${env:OTEL_REMOTE_TLS_INSECURE}" + sending_queue: + enabled: true + storage: file_storage + queue_size: 10000 + retry_on_failure: + enabled: true + initial_interval: 5s + max_interval: 30s + max_elapsed_time: 0s + +service: + extensions: [health_check, file_storage] + pipelines: + traces: + receivers: [otlp] + processors: [memory_limiter, resource/vm2, attributes/redact, batch] + exporters: [otlp/remote] + metrics: + receivers: [otlp] + processors: [memory_limiter, resource/vm2, attributes/redact, batch] + exporters: [otlp/remote] + logs: + receivers: [otlp] + processors: [memory_limiter, resource/vm2, attributes/redact, batch] + exporters: [otlp/remote] diff --git a/codebase/services/redis/redis-safety.acl.template b/codebase/services/redis/redis-safety.acl.template new file mode 100644 index 0000000..bc5fe94 --- /dev/null +++ b/codebase/services/redis/redis-safety.acl.template @@ -0,0 +1,5 @@ +# Public healthcheck: unauthenticated PING only, no key access. +user default reset on nopass -@all +ping + +# Runtime cache user: replace the placeholder with a long random password. +user safety reset on >REPLACE_WITH_LONG_RANDOM_PASSWORD ~han:safety:* -@all +ping +get +set diff --git a/codebase/services/redis/redis.conf b/codebase/services/redis/redis.conf new file mode 100644 index 0000000..94aaf9b --- /dev/null +++ b/codebase/services/redis/redis.conf @@ -0,0 +1,20 @@ +bind 0.0.0.0 +protected-mode yes +port 6379 +aclfile /run/secrets/redis-safety.acl + +appendonly yes +appendfsync everysec +save 900 1 +save 300 10 +dir /data + +maxmemory 512mb +maxmemory-policy allkeys-lru +timeout 0 +tcp-keepalive 60 + +rename-command FLUSHALL "" +rename-command FLUSHDB "" +rename-command CONFIG "" +rename-command DEBUG "" diff --git a/faq.md b/faq.md index 7e4285d..70d7608 100644 --- a/faq.md +++ b/faq.md @@ -3,8 +3,6 @@ docker compose --env-file .env logs --tail 100 keycloak docker compose --env-file .env logs --tail 100 api-backend docker compose --env-file .env logs --tail 100 keycloak - - # Пересобрать образы и поднять всё заново Из каталога проекта на ВМ: cd /opt/han-chat/backend @@ -25,4 +23,20 @@ docker compose --env-file .env up -d --force-recreate cd /opt/han-chat/backend docker compose --env-file .env up -d --build --force-recreate Проверка -docker compose --env-file .env ps \ No newline at end of file +docker compose --env-file .env ps + +# Изменение маппинга пользователя приложения на CRM (Проект) +bitrix_sync.request_bitrix_contact_rebind( + user_id, + target_b24_id, + reason, + operator_id +) + +# Копирование проекта на ВМ + + + + +# Копирование отдельного файла на ВМ + diff --git a/functional_blocks (business logic)/chat-requirements.md b/functional_blocks (business logic)/chat-requirements.md index 6dfde8a..dd739ca 100644 --- a/functional_blocks (business logic)/chat-requirements.md +++ b/functional_blocks (business logic)/chat-requirements.md @@ -23,7 +23,7 @@ | Направление | `sender_type` | Кто инициирует | Проверка Message Safety | Доставка | |---|---|---|---|---| | **C→O. Клиент → оператор** | `client` | Frontend (JWT) | **Обязательна** до Open Lines | `api-backend` → `bitrix-local-app` → Open Lines | -| **O→C. Оператор → клиент** | `company` | Bitrix24 webhook → `bitrix-local-app` → inbox API | **Нет** outbound moderation (доверенный канал); MIME/size/antivirus policy модуля | App DB + WS / polling | +| **O→C. Оператор → клиент** | `company` | Bitrix24 webhook → `bitrix-local-app` → inbox API | **Нет** Message Safety/AV; только MIME/size, residual risk принят | App DB + WS / polling | Правила: @@ -65,7 +65,7 @@ - Push / deep link в чат (модель может быть push-ready позже). - Админ-модерация очереди `needs_review` (enum зарезервирован, в MVP не создаётся). - CRM Contact sync в hot path чата (`bitrix-sync` **не** участвует в Open Lines delivery). -- Реальная антивирус/LLM-модерация: в MVP допускается stub `message-safety` с фиксированными правилами теста; канонический контракт вердиктов — arch-02 (`200/203/403`). +- До production cutover допускается только явно маркированный stub v1; target Message Safety v2 имеет `200/202/403`, local-only URL checks и file scan. --- @@ -162,12 +162,13 @@ |---|---| | `pending` | В quarantine, проверка не завершена | | `clean` | Allow, файл в S3-data (после promote) | +| `bypassed` | Forced allow в emergency MOCK; файл перенесён, но не проверялся | | `infected` | Deny | | `failed` | Ошибка инфраструктуры проверки | `direction`: `client_upload` \| `company_inbound`. -Клиентский файл до allow живёт **только** в S3-quarantine. Постоянных access keys у клиента нет — только короткий presigned PUT/GET. +Клиентский файл до allow живёт **только** в versioned S3-quarantine. Presigned PUT подписывает `If-None-Match: *` и checksum; один object key нельзя перезаписать. Постоянных access keys у клиента нет. ### 5.5. Идентификаторы @@ -229,12 +230,12 @@ ### 6.3. Исходящий файл -1. `POST .../attachments/init` → presigned PUT в **S3-quarantine**. -2. Frontend грузит байты **напрямую в S3** (не через api-backend). -3. `POST .../attachments/{id}/complete` + checksum → HeadObject, metadata, `scan_status=pending`. +1. `POST .../attachments/init` → presigned PUT в versioned **S3-quarantine** со signed `If-None-Match: *`, checksum и `Content-Type`. +2. Frontend грузит байты напрямую; повторная запись key получает `412`. +3. `POST .../attachments/{id}/complete` + checksum → фиксация authoritative `version_id + ETag + checksum`, `scan_status=pending`. 4. `POST .../messages` с `content_kind=file`, `attachment_id`, `checksum`. -5. Safety (файл); при `203 pending` api-backend sync-poll `task_id` внутри того же HTTP-запроса клиента. -6. Allow → promote quarantine → S3-data attachments → delivery Open Lines (`message.files` signed URL, `message.text` пустой). +5. Safety (файл); при `202 pending` api-backend sync-poll `Location` внутри того же HTTP-запроса клиента. +6. Allow → conditional promote сохранённой S3 version (source ETag/checksum match) → S3-data attachments → delivery Open Lines. 7. Deny → quarantine delete, `blocked`/`rejected`. Пока идёт poll safety, **это** клиентское соединение ждёт; параллельные запросы других клиентов не блокируются. @@ -266,6 +267,8 @@ Лимиты MIME/size для файлов оператора в MVP — те же `chat.attachments.*`. +Файл оператора считается данными доверенного Bitrix24-channel: он не загружается в quarantine и не проходит Message Safety/ClamAV. Выполняются только MIME/size validation, безопасная выдача download response и audit. Остаточный malware-риск для MVP принят явно. + ### 6.6. Закрытие диалога Inbox `dialog.closed` → `Dialog.status=closed`. Frontend получает `dialog.status` по WS или при следующем GET. Новый активный — только новым `POST /dialogs`. @@ -293,7 +296,7 @@ Inbox `dialog.closed` → `Dialog.status=closed`. Frontend получает `dia |---|---|---|---|---| | `200 allow` | `allowed` | `delivered` после успешной отправки; иначе `failed` | да (после allow) | `201` или `503`/`504` | | `403 deny` | `blocked` | `rejected` | нет | `422 message_blocked` | -| `203 pending` → затем allow/deny | как финал | как финал | только после allow | финальный код после poll | +| `202 pending` → затем allow/deny | как финал | как финал | только после allow | финальный код после poll | | timeout / circuit open | по политике модуля | `failed` | нет | `503`/`504` | Клиенту **не** отдаётся промежуточный `processing` как успешный ответ `POST .../messages`. @@ -370,8 +373,8 @@ Inbox `dialog.closed` → `Dialog.status=closed`. Frontend получает `dia | Метод и путь | Кто → кто | Назначение | |---|---|---| -| `POST /internal/safety/v1/messages/check` | api-backend → message-safety | Проверка | -| `GET /internal/safety/v1/messages/tasks/{task_id}` | api-backend → message-safety | Poll вердикта | +| `POST /internal/safety/v2/messages/check` | api-backend → message-safety | Проверка | +| `GET /internal/safety/v2/messages/tasks/{task_id}` | api-backend → message-safety | Poll вердикта; pending = `202` | | `POST /internal/openlines/v1/messages` | api-backend → bitrix-local-app | Исходящая доставка | | `GET /internal/openlines/v1/dialogs/{external_chat_id}` | api-backend → bitrix-local-app | Reconciliation | | `POST /internal/openlines/v1/inbox` | bitrix-local-app → api-backend | Входящие события | @@ -441,6 +444,8 @@ Partial unique: один active dialog на `user_id`. | `content_kind` | `text` \| `file` | | `text` | непустой для text; `''` для file | | `safety_status` / `delivery_status` | §5.3 | +| `safety_processing_mode` | `standard | mock`, internal/audit only | +| `safety_config_version` | версия active Message Safety config, internal/audit only | | `external_message_id` | Bitrix id для inbound | | `client_idempotency_key` | опционально/связка с Idempotency-Key | | `occurred_at` | | @@ -452,7 +457,7 @@ Partial unique: один active dialog на `user_id`. ### 10.3. `message_attachments` -Поля: `id`, `dialog_id`, `message_id NULL` до привязки, `owner_user_id`, `direction`, имена/MIME/size/checksum, `scan_status`, storage keys (working + quarantine), timestamps, common fields. +Поля: `id`, `dialog_id`, `message_id NULL` до привязки, `owner_user_id`, `direction`, имена/MIME/size/checksum, `scan_status`, storage keys, `quarantine_version_id`, `quarantine_etag`, timestamps, common fields. MVP: unique partial — не более одного active attachment на `message_id`. @@ -480,7 +485,7 @@ attachments/... # проверенные вложения чата (clie | Процесс | Владелец | Назначение | |---|---|---| -| Safety recovery worker | api-backend | Доводит `203 pending` после обрыва клиентского HTTP | +| Safety recovery worker | api-backend | Доводит `202 pending` после обрыва клиентского HTTP | | Delivery outbox worker | api-backend | Retry доставки в local app / Open Lines | | Quarantine orphan cleanup | api-backend / ops | Удаляет просроченные объекты без active task/attachment | | Inbox retry / DLQ | bitrix-local-app | Надёжность webhook → API | @@ -551,6 +556,8 @@ Application-код **не** обходит outbox «в обход» для по Этот документ собирает бизнес-смысл обмена сообщениями для аналитики и смежных фич; детальные алгоритмы — в module-спеках. +Для Safety: Product Owner принимает generic UX; Safety Service Owner — v2 contract/cutover; Rule Pack Owner — rules/corpus; Security Owner — monitor→deny и risks; Operations Owner — VM2/incident/restore. Назначения ролей фиксируются в release checklist. + --- ## 16. Критерии приёмки @@ -570,6 +577,16 @@ Application-код **не** обходит outbox «в обход» для по 13. Кнопка «Оператор» берёт номер только из `operator.call.phone`. 14. Популярный вопрос не имеет отдельного API — только text message. 15. Ownership: чужие dialog/attachment → `404`. +16. Любой Safety deny создаёт ровно одну company-реплику с mnemonic `safety.chat.blocked`; исходный blocked text редактируется, internal `rule_id` не виден клиенту. +17. В emergency MOCK normal checks не выполняются: отдельные fixed policy для text/file дают только sync allow/deny. Mode не виден клиенту; mock file allow хранится как `scan_status=bypassed`, а включение доступно `deploy` только через root-owned helper/restart и не имеет auto-expiry. +17. Semantic prompt-injection RU/EN возвращает allow + monitor audit; active content, URL policy и malware остаются hard deny. +18. `files=unavailable` не ломает text-only чат; `links=unavailable` блокирует только text с URL; Redis Safety outage не выключает core. +19. File async проходит `202` внутри api-backend до sticky final; public pending клиенту не возвращается. +20. EICAR, malformed/polyglot/encrypted/active PDF дают deny; dependency timeout даёт `503`, а не blocked. +21. Link pipeline не выполняет HTTP fetch; NXDOMAIN разрешяется с monitor, private/metadata IP блокируется. +22. S3 overwrite получает `412`; wrong version/ETag и conditional promote mismatch запрещают delivery. +23. Load acceptance module-05 §15.4 проходит: 10 text/s, 2 file/s, 5 slots, ≤100 pending; availability SLO в MVP не задаётся. +24. VM2 cutover/rollback gates module-10 пройдены; v1 stub не считается production control. --- @@ -591,6 +608,10 @@ Application-код **не** обходит outbox «в обход» для по | D10 | Популярный вопрос = обычный text send | §5.7 | | D11 | Presigned upload напрямую в S3; api-backend не проксирует байты | §6.3 | | D12 | `chat.attachments.*` — единые лимиты для чата (и reuse уведомлениями) | §5.6 | +| D13 | Generic Safety deny: company-реплика `safety.chat.blocked`, blocked text redacted, rule не раскрывается | §6.2, module-01 M8 | +| D14 | Emergency MOCK: независимые forced text/file allow/deny, root-owned helper для `deploy`, без auto-expiry | module-05 §2.3, module-10 | +| D14 | Semantic rules monitor-only; NXDOMAIN monitor allow | module-05 | +| D15 | Performance acceptance без availability SLO: 10 text/s, 2 file/s, 5 slots, 100 pending | module-05 §15.4 | ### 17.2. Открытые вопросы @@ -598,9 +619,8 @@ Application-код **не** обходит outbox «в обход» для по |---|---|---|---| | Q1 | Индикатор непрочитанных сообщений чата + sync между устройствами (backlog 23–24) | Поле вроде `Dialog.client_last_opened_at` / `last_read_message_id` + WS/REST counter; **не** тип уведомления `message` | Новая мини-постановка | | Q2 | Точный HTTP-код send в уже `closed` dialog | Зафиксировать в OpenAPI (`409 resource_state_conflict` или `422`) | Клиентский UX | -| Q3 | Политика показа blocked-сообщения в ленте (полный текст vs redacted) | Минимизация PII в хранении blocked (M8 module-01) + нейтральный UI | DB + frontend | | Q4 | Создание нового dialog сразу после `closed` — всегда разрешено или по бизнес-правилу «сессия поддержки» | MVP: разрешить, пока соблюдён unique active | Продукт / поддержка | -| Q5 | Stub `message-safety` с `400` на GET task vs канон arch-02 `403` | Для prod — только канон `200/203/403`; stub не расширяет публичный контракт | module-05 / contract tests | +| Q5 | Stub v1 расходится с target v2 | Для production — только `200/202/403` и terminal failed `503`; stub изолирован adapter-ом до cutover | module-05 / contract tests | | Q6 | Смешанный content text+files | Отдельный API version post-MVP | arch-02 breaking | | Q7 | Unread badge на кнопке «Чат» vs бейдж колокольчика уведомлений | Развести визуально и в данных | UI + Q1 | diff --git a/functional_blocks (business logic)/notification-requirements.md b/functional_blocks (business logic)/notification-requirements.md index c58b7b9..f41bfe3 100644 --- a/functional_blocks (business logic)/notification-requirements.md +++ b/functional_blocks (business logic)/notification-requirements.md @@ -65,7 +65,7 @@ - **Новые механики CTA и новые кнопки деталки** сверх перечисленных в §5.3 и §5.4: их добавление требует кода и планируется отдельно. - Раздел профиля «Документы» / архив оплат — не заменяются уведомлениями. Но документы компании из уведомлений **регистрируются в таблице `documents`**, чтобы будущий раздел профиля собрал их без миграции файлов. - Запись в `sync_queue` из application-кода: только **триггер БД** (§10.8). -- **Фактическая доставка документов в Bitrix24.** `bitrix-sync` в текущем состоянии — no-op stub, очередь не обрабатывает. В scope этого релиза — только корректная постановка задачи в `sync_queue`; обработка — отдельная работа по `module-07`. +- **Фактическая доставка документов в Bitrix24.** Полный `bitrix-sync` первого релиза по module-07 обрабатывает только Contact; `document.client_uploaded` остаётся вне его scope и не claim-ится. В scope notification-релиза — только корректная постановка задачи в `sync_queue`. - SMS/email поверх ЛК. - История чатов как UI-раздел — deprecated; backend API диалогов этим ТЗ не удаляется. - **Архив `lifecycle_status = closed` в UI v1 — нет.** Записи хранятся в БД бессрочно; ретенция и архивирование закрытых уведомлений не выполняются (§13). @@ -904,7 +904,7 @@ Unique active `(notification_id, document_id)`. Сами файлы описыв | `mime_type` | varchar(128) | | `size_bytes` | bigint, CHECK > 0 | | `checksum_sha256` | char(64) | -| `scan_status` | varchar(16), CHECK `pending` \| `clean` \| `infected` \| `failed` | +| `scan_status` | varchar(16), CHECK `pending` \| `clean` \| `bypassed` \| `infected` \| `failed`; `bypassed` — только Message Safety MOCK forced allow | | `storage_bucket` / `object_key` | varchar | | `quarantine_object_key` | varchar NULL | | `upload_expires_at` / `completed_at` | timestamptz | @@ -940,7 +940,7 @@ Unique active `(storage_bucket, object_key)`; unique `source_draft_id`; инде - Действует общее правило подавления: при `current_setting('han.sync_suppress', true)='true'` задача не создаётся. - Триггер и бизнес-транзакция — в одной транзакции. Application-код в `sync_queue` не пишет. - `bitrix_sync_user` получает GRANT на чтение `client_documents` дополнительно к существующим (arch-03). -- Что именно происходит с задачей на стороне CRM — предмет `module-07`; в этом релизе `bitrix-sync` работает как no-op stub, задачи накапливаются в очереди (§3.2). +- Обработка `document.client_uploaded` — отдельное post-MVP расширение module-07; Contact worker не должен claim/ack такие задачи, они продолжают накапливаться в очереди (§3.2). ### 10.9. `notification_sources` diff --git a/functional_blocks (business logic)/user-requirements.md b/functional_blocks (business logic)/user-requirements.md index 0f1c276..4c086cb 100644 --- a/functional_blocks (business logic)/user-requirements.md +++ b/functional_blocks (business logic)/user-requirements.md @@ -85,8 +85,8 @@ |---|---|---|---| | **IdP user** | Keycloak (`keycloak` schema) | Realm user, phone verified, sessions, tokens | Keycloak | | **UserIdentity** | App DB `user_identities` | Локальный `user_id`, связь `keycloak_sub`, кэш auth-телефона, `last_login_at` | Keycloak для телефона/`sub`; App DB для бизнес-FK | -| **ClientProfile** | App DB `client_profiles` | Кэш полей UI + `bitrix_contact_id` | UI-поля — последнее успешно синхронизированное значение (входящий поток MVP — Bitrix24); auth-телефон инициирует sync, но master телефона — Keycloak | -| **Bitrix Contact** | CRM Bitrix24 | Карточка клиента в CRM | Bitrix24 для CRM-полей; связь через `bitrix_contact_id` / `entity_external_mapping` | +| **ClientProfile** | App DB `client_profiles` | Кэш полей UI без CRM-идентификаторов | UI-поля — последнее успешно синхронизированное значение (входящий поток MVP — Bitrix24); auth-телефон инициирует sync, но master телефона — Keycloak | +| **Bitrix Contact** | CRM Bitrix24 | Карточка клиента в CRM | Bitrix24 для CRM-полей; связь `user_id ↔ b24_id` хранится только в `bitrix_sync.entity_external_mapping` | | **Гость** | Только устройство | UI-state, локальные согласия до OTP, опционально `guest_session_id` | Нет серверной записи | **Инвариант:** один verified phone ↔ один active Keycloak `sub`. Один `sub` ↔ одна active `UserIdentity`. Один `user_id` ↔ один `ClientProfile`. @@ -266,8 +266,9 @@ | `sub` / существование IdP user | Keycloak | `user_identities.keycloak_sub` | | Auth-телефон | Keycloak | `user_identities.phone_number`, seed `client_profiles.russian_phone` | | Согласия (версия + accepted) | App DB `user_consents` | — | -| ФИО, гражданство, email, foreign_phone | Последний успешный sync (MVP: Bitrix → App) | `client_profiles` | -| `bitrix_contact_id` | Результат `bitrix-sync` | `client_profiles` | +| ФИО, гражданство, email | Последний успешный sync (MVP: Bitrix → App) | `client_profiles` | +| `foreign_phone` | Не синхронизируется в первом релизе | `client_profiles` | +| Связь с Contact | `bitrix-sync` | Только `bitrix_sync.entity_external_mapping`; в App DB не кэшируется | | Tokens / auth session | Keycloak | secure storage на клиенте | | `ux_session_id` | App DB + память клиента | заголовок запросов | @@ -293,7 +294,7 @@ Application-код **не** пишет в `sync_queue`: задачи созда | `phone_number` | Auth-телефон E.164 | | `guest_session_id` | Локальный UUID устройства; не auth | | `ux_session_id` | Аналитическая сессия | -| `bitrix_contact_id` | Contact в CRM (после sync) | +| `b24_id` | Внутренний идентификатор Contact; используется только `bitrix-sync` | | `device_id` | Opaque id устройства в bootstrap / session-start; в audit/log не копируется как PII | Публичные id — **UUID** (в App DB предпочтительно UUID v7, как в остальных доменах). @@ -395,7 +396,6 @@ Unique `(user_id, consent_type, document_version)`. Записи immutable. |---|---|---| | `id` | uuid PK | | | `user_id` | uuid UNIQUE FK | 1:1 с identity | -| `bitrix_contact_id` | varchar/nullable | После успешного map | | `full_name` | varchar NULL | | | `citizenship` | varchar NULL | | | `russian_phone` | varchar NULL | Seed из auth-телефона | @@ -404,7 +404,7 @@ Unique `(user_id, consent_type, document_version)`. Записи immutable. | `source_updated_at` | timestamptz NULL | Метка источника sync | | common fields | обязательны | | -Partial unique на `bitrix_contact_id` среди active. PII не попадает в логи и generic audit payload. +CRM Contact ID и mapping в `client_profiles` отсутствуют. PII не попадает в логи и generic audit payload. ### 10.4. `ux_sessions` @@ -427,7 +427,8 @@ Partial unique на `bitrix_contact_id` среди active. PII не попада |---|---|---| | OTP challenge / counters / expiry | Keycloak SPI | До появления App user | | SMS order / delivery journal | `sms-service` | Только доставка кода | -| `contact.map_or_create` / `contact.update` | `bitrix-sync` | После bootstrap / изменения профиля | +| `contact.map_or_create` / `contact.update` / `contact.deactivate` | `bitrix-sync` | После bootstrap / изменения телефона / деактивации | +| `contact.rebind` | `bitrix-sync` | Audited административное исправление ошибочного mapping | | Token refresh / logout | Frontend + Keycloak | Не трогает App DB identity | | Retention UX-сессий (если введён) | ops / module | Не удаляет `UserIdentity` | @@ -445,7 +446,7 @@ Partial unique на `bitrix_contact_id` среди active. PII не попада В audit **нет:** полного phone/email/name в свободном тексте логов общего контура, OTP raw code, tokens, presigned URL. -Метрики (минимум): число bootstrap/сутки, доля `consents_required`, доля `phone_claim_missing`, latency map Contact, доля пользователей без `bitrix_contact_id` спустя N минут после входа. +Метрики (минимум): число bootstrap/сутки, доля `consents_required`, доля `phone_claim_missing`. Latency map Contact и доля пользователей без active mapping спустя N минут считаются `bitrix-sync` по собственной схеме. --- diff --git a/modules/Untitled b/modules/Untitled new file mode 100644 index 0000000..08e8bdc --- /dev/null +++ b/modules/Untitled @@ -0,0 +1 @@ +bitrix_local \ No newline at end of file diff --git a/modules/module-01-api-backend.md b/modules/module-01-api-backend.md index 98899f9..6c7242a 100644 --- a/modules/module-01-api-backend.md +++ b/modules/module-01-api-backend.md @@ -318,7 +318,7 @@ COMMIT return stable user_id ``` -Повторный bootstrap безопасен: уникальный ключ согласия не создаёт дубль; `last_login_at` обновляется. Триггеры на `UserIdentity`/`ClientProfile` создают `contact.map_or_create`/`contact.update` в `sync_queue`; application code задач не вставляет. +Повторный bootstrap безопасен: уникальный ключ согласия не создаёт дубль; `last_login_at` обновляется. Триггеры на `UserIdentity`/`ClientProfile` создают `contact.map_or_create`/`contact.update`/`contact.deactivate` в `sync_queue`; application code задач не вставляет. Полный trigger/dedup/lease contract задан в [`module-07-bitrix-sync.md`](module-07-bitrix-sync.md), §6. #### `POST /api/v1/consents` @@ -430,7 +430,7 @@ Success `201` возвращает финальный `MessageResponse`: } ``` -На safety deny — `422 message_blocked`; blocked message допустимо сохранять для аудита, но его текст должен храниться по политике минимизации данных (см. решение M8). В той же транзакции backend создаёт отдельную локальную `company`-реплику с безопасным бизнес-текстом для сообщения или документа; эта реплика публикуется в realtime, но не отправляется в Open Lines. На dependency failure — `503/504`; если Message уже создан, его `delivery_status=failed`. +На safety deny — `422 message_blocked`; исходный blocked text не сохраняется: применяется M8. В той же транзакции backend создаёт отдельную локальную `company`-реплику с текстом из `text_resources.mnemonic=safety.chat.blocked`; internal `rule_id` клиенту не передаётся. Реплика публикуется как `message.new`, но не отправляется в Open Lines. На dependency failure — `503/504`; если Message уже создан, его `delivery_status=failed`. ### 6.7. Attachments @@ -615,9 +615,9 @@ CHECK consent type: `personal_data | user_agreement | marketing`. Unique `(user_ ### 9.5. `client_profiles` -`id`, `user_id` UNIQUE FK, `bitrix_contact_id NULL`, `full_name`, `citizenship`, `russian_phone`, `foreign_phone`, `email`, `source_updated_at`, common fields. +`id`, `user_id` UNIQUE FK, `full_name`, `citizenship`, `russian_phone`, `foreign_phone`, `email`, `source_updated_at`, common fields. CRM Contact ID в App DB не хранится; canonical mapping принадлежит schema `bitrix_sync`. -Индексы: unique active `user_id`; partial unique `bitrix_contact_id WHERE bitrix_contact_id IS NOT NULL AND record_status='A'`; `updated_at`. PII поля не включаются в логи и generic audit payload. +Индексы: unique active `user_id`; `updated_at`. PII поля не включаются в логи и generic audit payload. ### 9.6. `dialogs` @@ -647,7 +647,7 @@ WHERE record_status='A'; ### 9.7. `messages` -Поля: `id`, `dialog_id`, `sender_type`, `content_kind`, `text`, `safety_status`, `delivery_status`, `external_message_id NULL`, `client_idempotency_key NULL`, `occurred_at`, common fields. +Поля: `id`, `dialog_id`, `sender_type`, `content_kind`, `text`, `safety_status`, `safety_processing_mode` (`standard | mock`), `safety_config_version` bigint, `delivery_status`, `related_message_id NULL` (self-FK), `external_message_id NULL`, `client_idempotency_key NULL`, `occurred_at`, common fields. Safety mode/config version — internal audit fields и не входят в public DTO. CHECK: @@ -655,24 +655,25 @@ CHECK: - content: `text | file`; - safety: `pending | allowed | blocked` (`needs_review` зарезервирован, не создаётся); - delivery: `accepted | processing | delivered | rejected | failed`; -- text message: `text <> ''`; +- text message: `text <> ''`, кроме blocked client message после M8 redaction (`text=''` допустим только при `sender_type=client AND safety_status=blocked`); - file message: `text = ''`; - company message: `safety_status='allowed'`; +- synthetic safety company-replica: `related_message_id` указывает на blocked client message, `content_kind=text`, `delivery_status=delivered`, `external_message_id=NULL`; - rejected → blocked; delivered → allowed. -Индексы: `(dialog_id, created_at, id) WHERE record_status='A'`; `(delivery_status, updated_at)` для recovery; unique `(dialog_id, external_message_id)` where external id not null; unique `(dialog_id, client_idempotency_key)` where not null. +Индексы: `(dialog_id, created_at, id) WHERE record_status='A'`; `(delivery_status, updated_at)` для recovery; unique `(dialog_id, external_message_id)` where external id not null; unique `(dialog_id, client_idempotency_key)` where not null; unique `(related_message_id) WHERE sender_type='company' AND related_message_id IS NOT NULL`. **Решение M3:** исходящее сообщение создаётся до safety со статусами `pending/accepted`, чтобы `safety_tasks` всегда имел FK и crash checkpoint. При начале poll delivery может стать `processing`; клиенту этот промежуточный ответ не отдаётся. ### 9.8. `message_attachments` -Поля: `id`, `dialog_id`, `message_id NULL`, `owner_user_id`, `direction` (`client_upload | company_inbound`), `original_file_name`, `safe_file_name`, `mime_type`, `size_bytes`, `checksum_sha256`, `scan_status`, `storage_bucket`, `object_key`, `quarantine_object_key NULL`, `upload_expires_at`, `completed_at`, common fields. +Поля: `id`, `dialog_id`, `message_id NULL`, `owner_user_id`, `direction` (`client_upload | company_inbound`), `original_file_name`, `safe_file_name`, `mime_type`, `size_bytes`, `checksum_sha256`, `scan_status`, `storage_bucket`, `object_key`, `quarantine_object_key NULL`, `quarantine_version_id NULL`, `quarantine_etag NULL`, `upload_expires_at`, `completed_at`, common fields. Ограничения: - `size_bytes > 0`; - SHA-256 — 64 lowercase hex; -- scan: `pending | clean | infected | failed`; +- scan: `pending | clean | bypassed | infected | failed`; `bypassed` допустим только для file allow с `safety_processing_mode=mock`; - до allow client file находится только в quarantine; - attachment связывается максимум с одним message; - для MVP у message максимум одно active attachment: unique partial `message_id`. @@ -691,12 +692,15 @@ Reserved MVP table: `id`, `user_id`, `name`, `mime_type`, `size_bytes`, `checksu - `message_id` UNIQUE; - `attachment_id NULL`; - `quarantine_object_key NULL`; +- `quarantine_version_id NULL`, `quarantine_etag NULL`; +- `task_location`; +- `processing_mode`, `config_version`, `rules_version NULL`, `last_poll_http_status NULL`; - `status`: `polling | finalizing | completed | failed`; - `deadline_at`, `next_poll_at`, `attempt_count`, `last_error_code`; - `locked_at`, `locked_by`; - timestamps. -Индексы: `(status, next_poll_at)`, `(deadline_at)`. Worker забирает `FOR UPDATE SKIP LOCKED`. Это не очередь анализа и не заменяет `message-safety`. +Индексы: `(status, next_poll_at)`, `(deadline_at)`. Worker забирает `FOR UPDATE SKIP LOCKED`. Это не очередь анализа и не заменяет `message-safety`. Checkpoints `completed|failed` удаляются через 7 дней; active checkpoints — только после terminal reconciliation. ### 9.11. `delivery_outbox` @@ -747,7 +751,9 @@ Append-only: `id`, `event_type`, `actor_type`, `user_id NULL`, `ux_session_id NU - `app_settings` — поля и правила из arch-04; - `text_resources`: `id`, `mnemonic`, `locale`, `text_value`, `sort_order`, common fields; unique active `(mnemonic, locale)`; - `popular_questions`: `id`, `mnemonic`, `locale`, `question_text`, `sort_order`, common fields; unique active `(mnemonic, locale)`; -- `sync_queue`, `entity_external_mapping` — shared contract с `bitrix-sync`. +- `sync_queue` — shared contract с `bitrix-sync`: migrations и trigger-функция принадлежат App DB/module-01, runtime claim выполняет `bitrix-sync` через минимальные GRANT. +- `bitrix_sync.entity_external_mapping` и rebind workflow принадлежат исключительно `bitrix-sync`; `api-backend` их не читает и не изменяет. +- существующие `han_app.entity_external_mapping`, `ClientProfile.bitrix_contact_id` и partial index удаляются expand/contract migration после переноса mapping и проверки отсутствия readers. ## 10. Alembic и транзакции @@ -842,30 +848,36 @@ validate current consents and content union enforce rate limits and idempotency for file: lock attachment, require completed/pending and checksum equality create Message(pending, accepted) -call POST /internal/safety/v1/messages/check +call POST /internal/safety/v2/messages/check if 200 allow: - finalize_allow() + persist response.processing_mode, response.config_version + finalize_allow(processing_mode, config_version) elif 403 deny: - finalize_deny() -elif 203 pending: - persist safety_tasks(task_id, deadline) + persist response.processing_mode, response.config_version + finalize_deny(processing_mode, config_version) +elif 202 pending: + persist safety_tasks(task_id, Location, deadline, processing_mode=standard, config_version) while monotonic_now < request_deadline: sleep(backoff_with_jitter) - poll GET /internal/safety/v1/messages/tasks/{task_id} - if 200 allow: finalize_allow() and return - if 403 deny: finalize_deny() and return - if 400 and code=stub_final_error and verdict=deny and details.terminal=true: - finalize_deny() and return + poll GET Location + if 200 allow: persist processing_mode/config_version; finalize_allow(...) and return + if 403 deny: persist processing_mode/config_version; finalize_deny(...) and return + if 503 and terminal=true and retryable=false: + mark failed and return 503 if other 4xx/5xx: return mapped dependency error mark failed, retain checkpoint/quarantine return 504 +elif 409 and code=safety_request_conflict: + alert invariant violation, mark failed, return 500, do not repeat POST else: mark failed return mapped dependency error ``` -Polling interval начинается с `MESSAGE_SAFETY_TASK_POLL_INTERVAL_SEC`, допускает capped exponential backoff и jitter, но не превышает общий `MESSAGE_SAFETY_TASK_POLL_MAX_SEC`. Клиенту не возвращается `203`. Terminal `400 stub_final_error` — намеренное test-only расширение `module-05`; оно преобразуется в публичный `422 message_blocked`, не считается infrastructure failure и не смешивается с malformed `400`. +Polling interval начинается с server `Retry-After`, допускает capped exponential backoff и jitter, но не превышает caller env `MESSAGE_SAFETY_TASK_POLL_MAX_SEC`. Каждый v2 verdict/pending содержит `processing_mode` и `config_version`; MOCK возвращает только sync `200/403`. Клиенту internal mode/config/`202` не возвращаются: public POST сохраняет синхронную семантику. Legacy stub `/v1` с `203`/`stub_final_error` поддерживается только временным adapter-ом до cutover и не является target production path. + +Capability snapshot `/health/ready` допускается кэшировать не дольше 5 с для fast-fail: file требует `files`, text с URL — `links`, text без URL — `text`. При `processing_mode=mock` normal capabilities имеют состояние `bypassed` и не применяются как fast-fail gate. Snapshot не является correctness gate: definitive capability повторно проверяет `POST /check`. При unavailable в standard mode api-backend возвращает public `503 dependency_unavailable`, не создаёт delivery outbox и не меняет status на blocked. ### 13.2. Final allow @@ -874,13 +886,20 @@ Polling interval начинается с `MESSAGE_SAFETY_TASK_POLL_INTERVAL_SEC` 1. проверить checkpoint; 2. copy quarantine object в attachments bucket с conditional/idempotent key; 3. HeadObject destination, сверить checksum/size; -4. в транзакции изменить attachment на `clean`, storage location на S3-data; message на `allowed/accepted`; создать delivery outbox; +4. в транзакции изменить attachment на `clean` для standard mode или `bypassed` для MOCK, storage location на S3-data; message на `allowed/accepted` с фактическим `safety_processing_mode`; создать delivery outbox; 5. удалить quarantine object best-effort; при сбое cleanup повторит; 6. попытаться синхронно доставить outbox, чтобы исходный POST вернул финальный `delivered`. ### 13.3. Final deny -В транзакции: `blocked/rejected`, attachment `infected`; затем delete quarantine best-effort. В Open Lines ничего не отправляется. Realtime `message.status` публикуется, если message уже мог быть виден этому клиенту. +В одной транзакции: + +1. client message → `blocked/rejected`, `text` заменяется пустой строкой/безопасным marker по M8; +2. attachment при наличии → `infected`; +3. создаётся ровно одна synthetic company-replica, связанная `related_message_id`, с `text` из active `text_resources(safety.chat.blocked, locale)`, `allowed/delivered`; +4. сохраняются только hash, internal rule/verdict/version в audit. + +После commit quarantine удаляется best-effort. В Open Lines ничего не отправляется. Realtime публикует `message.status` исходного сообщения и `message.new` company-реплики. Public `422` содержит generic error envelope без `rule_id`. ### 13.4. Timeout/crash recovery @@ -892,13 +911,13 @@ claim with lease poll safety by task_id if pending before recovery deadline: schedule next_poll_at if allow: idempotent promote + delivery checkpoint -if deny (canonical 403 or test-only terminal 400): idempotent delete + reject +if deny (canonical 403): idempotent delete + reject + company replica if budget exhausted: mark task failed, message failed, preserve audit ``` HTTP disconnect не отменяет durable recovery. Клиентский retry с тем же idempotency key получает восстановленный результат либо текущую dependency error. Recovery не принимает решение о типе анализа. -**Решение M5:** после client-facing timeout recovery budget продолжается ещё 15 минут как техническая константа модуля; до production-load test значение должно быть вынесено в infra env и добавлено в arch-04. Пока это **TBD-2**, код обязан иметь безопасный default и метрику. +**Решение M5:** `deadline_at = min(message_safety.expires_at, checkpoint.created_at + HAN_APP_SAFETY_RECOVERY_MAX_SEC)`, initial env = 1200 с. Client-facing wait остаётся 300 с; recovery продолжает без открытого клиентского соединения. Terminal Safety `503 retryable=false` немедленно завершает checkpoint как failed. ## 14. S3 attachment lifecycle @@ -914,23 +933,23 @@ Lifecycle: 1. `init`: allow-list extension + declared MIME + size; create metadata; presign exact key, MIME, max size, TTL; 2. direct PUT client → S3-quarantine; -3. `complete`: HeadObject, size/MIME/checksum metadata; checksum при отсутствии trustworthy S3 checksum вычисляется safety service при scan; +3. `complete`: HeadObject конкретной version, size/MIME/server checksum; атомарно фиксирует `version_id + ETag + authoritative checksum`; 4. message send: attachment ownership/state/checksum; -5. allow: copy + verify + DB finalize + quarantine delete; +5. allow: conditional copy сохранённой source version с ETag/checksum match + verify + DB finalize + quarantine delete; 6. deny: quarantine delete + infected metadata; -7. abandoned/failed: cleanup only if expired and no active safety task; +7. abandoned/failed: cleanup через 48 ч, только если нет active safety task; 8. download: owner check → audit commit → short presigned GET. Extension и MIME оба должны быть разрешены; server normalizes filename and sets safe `Content-Disposition`. S3 credentials never reach frontend. -**Допущение A3:** Selectel S3 может не предоставлять SHA-256 в `HeadObject`; `complete` сверяет клиентский checksum с signed metadata, а authoritative checksum подтверждает Message Safety. Если storage поддерживает checksum header, он обязателен. +Presigned PUT обязательно подписывает `If-None-Match: *`, checksum header и `Content-Type`; versioning quarantine включён. Повторный PUT того же key получает `412`. При отсутствии подтверждённой поддержки этих условий выбранным S3 adapter production upload блокируется, а не деградирует до overwrite. Inbound operator file: - validate count/size/MIME and URL scheme/host policy; - protect against SSRF: no redirects to private/link-local ranges, DNS rebinding checks, max bytes streaming; - download with timeout to temporary stream, never local persistent disk; -- optional antivirus policy; Message Safety outbound pipeline не вызывается; +- Message Safety/ClamAV не вызываются; остаточный malware-риск доверенного Bitrix24-channel принят для MVP; - upload directly to S3-data attachments; - only then atomically save attachment/message and ack inbox. @@ -973,13 +992,19 @@ Outbox worker и synchronous first attempt используют один dispatc Миграции создают triggers: -- insert active `UserIdentity`/`ClientProfile` без mapping → `contact.map_or_create`; -- изменение tracked profile/auth-phone fields → `contact.update`; -- trigger строит deterministic dedup key; +- insert active `UserIdentity`/`ClientProfile` → coalesced `contact.map_or_create`; trigger не читает schema `bitrix_sync`, наличие mapping проверяет worker; +- фактическое изменение App-master `UserIdentity.phone_number` → `contact.update`; +- переход `UserIdentity` или `ClientProfile` из active в inactive/deleted → `contact.deactivate`; +- возврат active записи → coalesced `contact.map_or_create`; +- изменения CRM-master `full_name`, `citizenship`, `email` не создают App→CRM задачу; +- trigger проверяет значения через `IS DISTINCT FROM`, а не только факт присутствия колонки в `UPDATE OF`; +- trigger строит deterministic dedup key, уникальный только среди активных queue rows; завершённая/cancelled/dead-letter запись не блокирует новое событие; - при `current_setting('han.sync_suppress', true)='true'` задача не создаётся; - trigger и business update находятся в одной транзакции. -`bitrix-sync` получает ограниченные GRANT. Ошибка CRM не откатывает bootstrap и chat. Open Lines не зависит от CRM mapping. +`entity_id` всех contact-задач — `UserIdentity.id`; payload содержит только `schema_version`, `user_id`, безопасную причину и source timestamp, но не PII snapshot. Worker перечитывает актуальные identity/profile. + +`bitrix-sync` получает ограниченные column/table GRANT, заданные module-07. Ошибка CRM не откатывает bootstrap и chat. Open Lines не зависит от CRM mapping. ## 17. Realtime @@ -1197,6 +1222,8 @@ Open Lines недоступность отображается как component **Решение M8:** blocked message text не нужен продукту после deny. В `messages.text` хранится пустая строка/безопасный redacted marker, а audit хранит только rule/verdict id и hash содержимого. Если регуляторно требуется исходный текст, это отдельное согласованное изменение retention/security. +Оценка monitor-only semantic rules выполняется контролируемой, аудируемой выборкой из App DB: доступ только у утверждённой роли, выборка ограничена по времени/объёму, purpose фиксируется в audit. Текст не копируется в schema/логи Message Safety; там остаются hash, `rule_id` и version. + ## 24. Docker/runtime Service compose: @@ -1205,7 +1232,7 @@ Service compose: - networks: `backend`, `observability`; - env только через `${VAR}` из root `.env`; - healthcheck `/health/live` для процесса; root orchestration учитывает readiness; -- depends_on health для Redis/Keycloak/message-safety, но приложение само retry startup dependencies; +- depends_on health только для локальных Redis/Keycloak; remote Message Safety не является Compose dependency и проверяется capability-aware на send path; - managed PostgreSQL вне compose, TLS обязателен; - stateless container, без persistent volume; - init process для signal forwarding; @@ -1251,7 +1278,7 @@ Frontend выполняет refresh token grant. API не обновляет tok ### 25.3. Файловое сообщение -create/reuse dialog → init → direct PUT quarantine → complete → send file message → safety `203` poll → allow promote → delivery outbox → Open Lines → delivered. При deny quarantine удаляется, Bitrix не вызывается. +create/reuse dialog → init → direct immutable PUT quarantine → complete with version/ETag/checksum → send file message → safety `202` poll → allow conditional promote → delivery outbox → Open Lines → delivered. При deny quarantine удаляется, Bitrix не вызывается. ### 25.4. Ответ оператора @@ -1289,7 +1316,7 @@ Bitrix event → local app durable inbox → `POST /internal/openlines/v1/inbox` ### 26.3. Contract - generated FastAPI OpenAPI matches committed `api-backend/openapi.yaml`; -- Message Safety POST `200/203/403`, task poll `203/200/403` и test-only terminal `400 stub_final_error`; проверены различение malformed `400` и mapping terminal `400` → public `422`; +- Message Safety v2 POST `200/202/403`, task poll `202/200/403`, terminal failed `503` и conflict `409`; legacy stub adapter тестируется отдельно до cutover; - Open Lines message idempotency and inbox schemas; - settings bridge DTO/token; - common request-id/trace propagation; @@ -1368,15 +1395,15 @@ Bitrix event → local app durable inbox → `POST /internal/openlines/v1/inbox` - **A1:** locale API зарезервирован, MVP фактически `ru`. - **A2:** inbox получит стабильный `event_id`; временно возможен deterministic fingerprint. -- **A3:** authoritative SHA-256 может подтверждаться Message Safety, если S3 HeadObject его не отдаёт. +- **A3:** production S3 adapter подтверждает signed checksum headers, versioning и conditional requests; иначе immutable upload не включается. ### Требуют согласования - **TBD-1:** единый код для protected endpoint до bootstrap (`409` предложен). -- **TBD-2:** extended recovery budget после `MESSAGE_SAFETY_TASK_POLL_MAX_SEC`. +- **Решение M5:** extended recovery ограничен `HAN_APP_SAFETY_RECOVERY_MAX_SEC=1200` и Safety `expires_at`. - **TBD-3:** добавить `event_id`/`occurred_at` в WS events и `event_id` в inbox OpenAPI. - **TBD-4:** production SLO, RPS, concurrency, RPO/RTO и retention. -- **TBD-5:** antivirus policy для файлов оператора, которые не проходят outbound Message Safety. +- **Решение M9:** файлы оператора не проходят Message Safety/AV в MVP; только MIME/size/audit, residual malware risk принят. - **TBD-6:** legal retention/erasure для PII, audit, blocked messages и S3-data. - **TBD-7:** точный max WS connections/subscriptions/frame и queue size. - **TBD-8:** G10 — окончательный DTO/mapping public app-config при оформлении OpenAPI. diff --git a/modules/module-02-frontend-test-site.md b/modules/module-02-frontend-test-site.md index 16d1dd6..f9afd88 100644 --- a/modules/module-02-frontend-test-site.md +++ b/modules/module-02-frontend-test-site.md @@ -90,7 +90,7 @@ Resend запускает новое Keycloak action, блокирует double - сообщения сортируются по `created_at asc`, дубли объединяются по `message_id`; - `waiting_for_company`, `waiting_for_client`, `closed` отображаются русскими подписями; - завершённая беседа readonly; CTA «Продолжить общение» повторно открывает текущий чат через `POST /dialogs`; -- промежуточный safety `203` клиенту не показывается: send request остаётся в progress до финального ответа. +- internal safety `202` клиенту не показывается: send request остаётся in progress до финального ответа. ### 5.4. Профиль @@ -146,7 +146,7 @@ Bootstrap повторяем безопасно после неопределё 3. `POST /dialogs` с idempotency key, сохранить `dialog_id` и перейти на экран чата до отправки. 4. Экран чата выполняет `POST /dialogs/{id}/messages` с отдельным стабильным key. 5. Блокировать повторный click только для того же intent; другие действия не замораживать. -6. На `201` merge `MessageResponse`; на `422 message_blocked` не показывать красную техническую ошибку, а обновить историю с сохранённой backend `company`-репликой; на `503/504` предложить retry с тем же key. +6. На `201` merge `MessageResponse`; на `422 message_blocked` не показывать internal reason/rule и не строить собственный текст: получить/merge backend `company`-реплику (`message.new`) с контентом мнемоники `safety.chat.blocked`; на `503/504` предложить retry с тем же key. 7. Composer показывает счётчик `n/max`, где `max` приходит как `messages.max_text_length` из public app-config; сверх лимита отправка блокируется без обрезки ввода. ## 11. Файловый flow @@ -156,11 +156,11 @@ MVP допускает ровно один файл, только allow-list ext 1. Локальная prevalidation. 2. Создать/reuse dialog. 3. `POST .../attachments/init` с filename, MIME, size. -4. Выполнить прямой `PUT upload_url` с точно выданными `upload_headers`; API domain при этом не используется. -5. Вычислить SHA-256, вызвать `complete`. +4. Вычислить SHA-256 до upload и выполнить прямой `PUT upload_url` с **точно** выданными `upload_headers`, включая `If-None-Match: *` и checksum; заголовки являются частью подписи. +5. Вызвать `complete` с тем же checksum; backend фиксирует authoritative S3 version/ETag/checksum. 6. Отправить file message с `attachment_id` и `sha256:`. -Presigned URL не сохраняется и редактируется из диагностик. Abort позволяет отменить PUT; orphan очищает backend. При expiry init выполняется повторно в рамках согласованного состояния. CORS S3 должен разрешать origin сайта, PUT и необходимые headers. +Presigned URL не сохраняется и редактируется из диагностик. `412` означает, что immutable key уже записан: frontend не повторяет PUT в тот же key, а запрашивает новый init. Abort позволяет отменить PUT; orphan очищает backend через 48 ч. При expiry init выполняется повторно в рамках согласованного состояния. CORS S3 разрешает origin сайта, PUT и только необходимые signed headers. ## 12. Realtime и polling @@ -292,4 +292,4 @@ Browsers: Chromium, Firefox, WebKit; viewport desktop/mobile. В CI исполь - F3: web storage policy refresh token перед production security review; - F4: окончательный DTO app-config (G10); - F5: WS `event_id`/protocol version (TBD module-01/G11); -- F6: продуктовые тексты всех error states по мнемоникам. +- F6 для Safety закрыт: generic deny использует `safety.chat.blocked`; остальные error-state мнемоники остаются в frontend content backlog. diff --git a/modules/module-03-nginx.md b/modules/module-03-nginx.md index df51c14..02f148e 100644 --- a/modules/module-03-nginx.md +++ b/modules/module-03-nginx.md @@ -1,39 +1,68 @@ # module-03. Проектная спецификация корневого `nginx` -> Статус: целевая спецификация полностью рабочего edge-контура MVP. +> Статус: целевая спецификация независимых nginx-контуров ВМ1 и ВМ2. > Источники: [`README.md`](README.md), [`arch-00-glossary.md`](arch-00-glossary.md), [`arch-01-system-architecture.md`](arch-01-system-architecture.md), [`arch-02-api-contracts.md`](arch-02-api-contracts.md), [`arch-03-docker-compose-blueprint.md`](arch-03-docker-compose-blueprint.md), [`arch-04-settings-and-content.md`](arch-04-settings-and-content.md), [`arch-05-agent-development-process.md`](arch-05-agent-development-process.md), [`module-01-api-backend.md`](module-01-api-backend.md). ## 1. Назначение и обязательная топология -В production-like контуре существует ровно один корневой nginx. Только он публикует host-порты `80/443`, завершает TLS, раздаёт SPA и проксирует публичные маршруты. Контейнеры API, Keycloak, Redis, Safety, Bitrix и OTEL используют только `expose`/Docker networks. +В production-like контуре каждая VM имеет собственный nginx в своём root Compose и собственный deployment lifecycle: -Если перед VM есть внешний WAF/LB, доверенные proxy CIDR задаются явно; nginx не доверяет произвольному `X-Forwarded-For`. Другой nginx на host не должен маршрутизировать сервисы по отдельности. +- nginx ВМ1 обслуживает frontend/API/auth/Open Lines/SMS; +- nginx ВМ2 напрямую обслуживает публичные CRM webhook `bitrix-sync` и private Message Safety API; +- публичный трафик ВМ2 не проходит через ВМ1; +- отказ или deploy ВМ1 не прерывает приём CRM webhook на ВМ2. + +Контейнеры приложений не публикуют host ports. На каждой VM наружу смотрит только её nginx. Если перед конкретной VM есть WAF/LB, trusted proxy CIDR задаются отдельно. ## 2. Routing matrix -Порядок location критичен: exact/longest public routes до общего `/bitrix/`. +Порядок location критичен. Публичные route разделены по host/VM. + +### ВМ1 | Внешний путь | Upstream | Режим | |---|---|---| | `/api/` | `api-backend:8000` | REST; `/api/v1/realtime` WS | | `/auth/` | `keycloak:8080` | OIDC/OTP, prefix/hostname согласован с issuer | | exact `/callbacks/idgtl/sms` | `sms-service:8080` | public HTTPS POST Direct; IP allowlist + Basic auth в upstream | -| `/bitrix/sync/webhook/contact` | `bitrix-sync:8080` | public HTTPS POST, no cache; отсутствует, пока действует stub module-07 | | `/bitrix/handler`, `/bitrix/install`, `/bitrix/placement` | `bitrix-local-app:8080` | public HTTPS | | exact `/health/live`, `/health/ready` | `bitrix-local-app:8080` | по умолчанию не публикуются; только при явно выбранной ops/monitoring policy | | `/` | static SPA либо Expo dev upstream | `try_files` fallback | -Notification paths внутри `/api/` имеют отдельные edge-зоны: public catalog/campaigns, JWT read, actions, uploads и downloads. `/internal/`, `/_internal/`, Redis/OTLP/admin/status/config files запрещены exact prefix response `404` (допустим `403`, но единообразно выбран `404`). Никакого fallback internal path в SPA или общий proxy. `message-safety`, `/internal/sms/*` и `/internal/notifications/*` не имеют публичного route. +### ВМ2 + +| Внешний путь | Upstream | Режим | +|---|---|---| +| exact `/bitrix/sync/webhook/contact` | `bitrix-sync:8080` | public HTTPS Contact event; source IP CIDR/method/body/rate limits, query-token auth в upstream | +| exact `/bitrix/sync/webhook/alert` | `bitrix-sync:8080` | public HTTPS smart-process event; те же ограничения | + +Notification paths внутри `/api/` ВМ1 имеют отдельные edge-зоны. На обоих public hosts `/internal/`, `/_internal/`, Redis/OTLP/admin/status/config files возвращают `404`; fallback на другую VM или SPA запрещён. До full sync cutover оба exact webhook route ВМ2 закрыты либо возвращают retryable `503`; успешный `2xx ignored` запрещён. + +Query не участвует в exact location matching: URL штатного робота `/bitrix/sync/webhook/?token=...&ID=...` попадает в соответствующий exact route. До proxy nginx проверяет непосредственный source IP по version-controlled `BITRIX_WEBHOOK_ALLOWED_CIDRS`; пустой/невалидный список при enabled receiver блокирует deployment. Адрес из недоверенного `X-Forwarded-For` не используется. При внешнем LB сначала настраиваются его trusted CIDR и нормализация real IP. + +Запрос вне allow-list получает generic `403` без proxy. В безопасном журнале с ограниченным retention сохраняются только timestamp, source IP, route class и outcome; query/body не сохраняются. Telemetry pipeline экспортирует `webhook_rejected_total{receiver,reason="source_ip"}` без IP label. Allow-list не расширяется автоматически: всплеск Contact, восстановленных инкрементальной reconciliation, инициирует проверку rejected-IP журнала, подтверждение принадлежности адреса Битрикс24 и reviewed reload конфигурации. ## 3. Upstreams -Именованные upstream: `api_backend`, `keycloak`, `sms_service`, `bitrix_local`, `bitrix_sync`, опционально `frontend_dev`. Для одной replica допустим `server service:port`; `keepalive` включён. Docker DNS resolver задаётся с коротким `valid` и `resolve` там, где поддерживает выбранная nginx edition; иначе контейнер перезапускается при смене IP upstream. +Именованные upstream ВМ1: `api_backend`, `keycloak`, `sms_service`, `bitrix_local`, опционально `frontend_dev`, а также private `processing_gateway` только для вызовов Message Safety из api-backend. + +Nginx ВМ2 имеет независимые server blocks: + +- public `80/443` на отдельном DNS host: ACME/redirect и два exact CRM webhook; +- private `8443` с сертификатом internal CA: только server-to-server Message Safety и approved ops. + +| Path | Local upstream | Caller | +|---|---|---| +| `/internal/safety/v2/*` | `message-safety-api:8080` | api-backend ВМ1 | +| `/internal/sync/v1/*` | `bitrix-sync:8080` | ops/allow-listed service | + +Public и private server blocks не имеют общего fallback. Все прочие paths/methods возвращают `404/405`. Private listener доверяет forwarded headers только от allow-listed private caller; public listener применяет собственную trusted proxy policy. Upstream failures не перенаправляются на другой сервис и не попадают в SPA. API возвращает `502/504` с безопасным nginx body и `X-Request-ID`; custom JSON error допустим для `/api`, но не имитирует backend domain code. ## 4. HTTP/HTTPS и TLS -- единый web host `:80` обслуживает только ACME challenge и `308 https://$host$request_uri`; +- public host каждой VM на `:80` обслуживает только ACME challenge и `308 https://$host$request_uri`; исключение — `/bitrix/sync/webhook/contact|alert`, которые возвращают generic `404/426` без redirect и отражения query token; - выделенный API host, если появится, не имеет listener `:80`; - `:443 ssl http2`, TLS 1.2/1.3, современные cipher suites, session tickets по ops policy; - сертификат доверенного CA, private key read-only и недоступен приложению; @@ -134,7 +163,7 @@ traceparent: входной валидный либо новый согласн - `ws_connect`: handshake; - `connections`: `limit_conn`. -Ответ превышения — `429`, `Retry-After` (статический/вычисляемый для зоны) и request id. Edge не реализует user-level бизнес-лимит; это делает API/Redis. OPTIONS не должен расходовать auth budget чрезмерно. Bitrix webhook retries имеют отдельный достаточный burst и всё равно проверяют application token в сервисе. +Ответ превышения — `429`, `Retry-After` (статический/вычисляемый для зоны) и request id. Edge не реализует user-level бизнес-лимит; это делает API/Redis. OPTIONS не должен расходовать auth budget чрезмерно. Bitrix webhook retries имеют отдельный достаточный burst, проходят source IP allow-list и проверяют query receiver token в сервисе. ## 10. Static SPA и dev mode @@ -195,7 +224,7 @@ Bitrix placement может требовать embedding: для exact `/bitrix/ ## 14. Логи и OTEL correlation -JSON access log: timestamp, request_id, trace_id (если извлечён), remote IP/hashed policy, host, method, route class, normalized URI без sensitive query, status, bytes, duration, upstream addr/status/time, cache status, TLS protocol/cipher, user agent при принятой retention. +JSON access log: timestamp, request_id, trace_id (если извлечён), remote IP/hashed policy, host, method, route class, normalized URI на основе `$uri` без `$request_uri`/`$args`, status, bytes, duration, upstream addr/status/time, cache status, TLS protocol/cipher, user agent при принятой retention. Не логируются Authorization, cookies, request/response body, OTP, tokens, query token, presigned query, PII. Error log структурирован настолько, насколько позволяет nginx; debug выключен production. @@ -253,7 +282,7 @@ docker compose exec nginx nginx -t curl -I http://tohin.ru/ curl -vk https://tohin.ru/api/v1/public/app-config openssl s_client -connect tohin.ru:443 -servername tohin.ru -curl -i https://tohin.ru/internal/safety/v1/messages/check +curl -i https://tohin.ru/internal/safety/v2/messages/check ``` Автоматические тесты: @@ -271,15 +300,20 @@ curl -i https://tohin.ru/internal/safety/v1/messages/check - CSP/CORS preflight и Bitrix placement exception; - upstream down/timeout, failed reload, renewal rehearsal; - logs не содержат secrets/query tokens. +- CRM webhook exact routes принимают query без изменения location matching; allowed source IP проксируется, wrong IP получает `403` до upstream; +- HTTP webhook URL с query token не перенаправляется на HTTPS и не отражает query в `Location`/error; +- source-IP rejects попадают в безопасный bounded-retention журнал и low-cardinality telemetry без query/body/IP label; - allowed Direct callback проходит; wrong IP/method и любой `/internal/sms/*` отклоняются; Authorization отсутствует в логах. - `/internal/notifications/*` снаружи всегда `404`; notification read/action/upload/public routes используют свои зоны и возвращают `429`. - CSP содержит `frame-src 'none'`; инструкция проверяется как новая вкладка без embedded content. ## 19. Definition of Done -- единственный root nginx публикует только 80/443; +- на каждой VM ровно один nginx; ВМ1 и ВМ2 независимо публикуют только свои утверждённые `80/443`, ВМ2 дополнительно слушает private `8443`; - TLS/ACME bootstrap, renewal и safe reload испытаны; - routing matrix и route precedence покрыты; +- CRM webhook достигает ВМ2 напрямую и продолжает приниматься при остановленном nginx ВМ1; +- CRM webhook ограничен version-controlled source IP CIDR allow-list; query token и form body отсутствуют в access/error logs и traces; - internal endpoints/ports извне недоступны; - WS работает на `/api/v1/realtime`; - message timeout равен safety max + минимум 30 секунд; @@ -293,8 +327,8 @@ curl -i https://tohin.ru/internal/safety/v1/messages/check ## 20. Решения, допущения и TBD -**Решения:** один nginx; njs/module для UUID; internal → 404; webroot ACME; отдельная CSP для Bitrix placement; public cache только allow-listed endpoints. +**Решения:** независимые public nginx ВМ1/ВМ2; CRM webhook приходит прямо на ВМ2 через source IP CIDR allow-list; private `8443` ВМ2 используется только server-to-server; njs/module для UUID; public internal paths → 404; webroot ACME; отдельная CSP для Bitrix placement; public cache только allow-listed endpoints. -**Допущения:** MVP использует единый host `tohin.ru`; upstream service names стабильны в Compose; S3 CORS настраивается отдельно. +**Допущения:** ВМ1 и ВМ2 используют разные public hosts и сертификаты; upstream service names стабильны внутри каждого Compose; S3 CORS настраивается отдельно. **TBD:** N1 доверенные WAF CIDR; N2 production cipher suite/OCSP; N3 нужен ли публичный health; N4 точный CSP Expo build; N5 Bitrix frame ancestor domains; N6 финальные burst/connection limits; N7 certbot vs другой ACME client после ops review. diff --git a/modules/module-04-redis.md b/modules/module-04-redis.md index ea1cfa2..2294958 100644 --- a/modules/module-04-redis.md +++ b/modules/module-04-redis.md @@ -1,15 +1,15 @@ # module-04. Проектная спецификация Redis -> Статус: целевая спецификация Redis в едином Docker Compose MVP. +> Статус: целевая спецификация Redis для двух Compose-контуров; legacy DB2 stub описан только до cutover. > Источники: [`README.md`](README.md), [`arch-00-glossary.md`](arch-00-glossary.md), [`arch-01-system-architecture.md`](arch-01-system-architecture.md), [`arch-02-api-contracts.md`](arch-02-api-contracts.md), [`arch-03-docker-compose-blueprint.md`](arch-03-docker-compose-blueprint.md), [`arch-04-settings-and-content.md`](arch-04-settings-and-content.md), [`arch-05-agent-development-process.md`](arch-05-agent-development-process.md), [`module-01-api-backend.md`](module-01-api-backend.md). ## 1. Назначение и инварианты -Один Redis-контейнер предоставляет быстрые ephemeral функции трём логическим DB: +Redis разделён по deployment/security boundary: -- DB0 — `api-backend`: idempotency fast layer и API rate limits; -- DB1 — realtime и coordination; -- DB2 — `message-safety` stub tasks/cache. +- Redis ВМ1: DB0 (`api-backend` idempotency/rate) и DB1 (realtime/coordination); +- Redis Safety ВМ2: отдельный instance для hot cache, rate limiting и optional worker wake-up; +- legacy DB2 ВМ1 существует только для test stub v1 до cutover и после него удаляется. Redis не является бизнес-очередью, source of truth сообщений, sync tasks, audit, профилей или delivery checkpoint. Надёжные состояния остаются в managed PostgreSQL/S3. Потеря Redis может ухудшить сервис, но не должна создавать потерю подтверждённых сообщений либо дубль side effect: durable idempotency/outbox/checkpoint api-backend описаны в module-01. @@ -17,9 +17,9 @@ OTP counters api-backend в Redis не хранит; они принадлежа ## 2. Версия и topology -Redis 7.x, image закреплён по digest. Одна primary instance на VM без replica/Sentinel в MVP. Клиенты используют connection pool, bounded timeouts и не выполняют опасные команды. +Redis 7.x, image закреплён по digest. На каждой VM одна нужная primary instance без replica/Sentinel в MVP. Клиенты используют connection pool, bounded timeouts и не выполняют опасные команды. -Logical DB — изоляция имён, не security boundary и не независимый memory quota. При росте или разных eviction/SLA DB2 и DB0 выносятся в отдельные instances. +Logical DB — изоляция имён, не security boundary. Safety уже вынесен в отдельный instance ВМ2; DB0/DB1 остаются на ВМ1. ## 3. Общие правила ключей @@ -81,18 +81,20 @@ Redis Streams не используются как бизнес queue. Если Acquire: `SET key owner NX PX ttl`; extend/release — Lua compare owner. Worker обязан опираться также на PostgreSQL row lease/`FOR UPDATE SKIP LOCKED`; Redis lock — оптимизация, не единственная защита. Fencing token рекомендуется для внешнего side effect, а уникальные DB constraints/idempotency остаются финальной защитой. -## 8. DB2: Message Safety stub +## 8. Redis Safety ВМ2 | Key | Тип/value | TTL | |---|---|---| -| `han:safety:task:{task_id}` | HASH/JSON v1: created, polls, optional seed/context | `MESSAGE_SAFETY_TASK_TTL_SEC` | -| `han:safety:tasklock:{task_id}` | owner token | 5–30s | | `han:safety:rl:service:{caller}:{window}` | counter | window+jitter | -| `han:safety:verdict:{content_hash}:{rules_version}` | optional cache | bounded technical TTL | +| `han:safety:text:{analysis_hash}:{rules_version}` | hot text-rules result, monitor rule ids без raw text | active config, seed ≤48h | +| `han:safety:verdict:{content_hash}:{config_version}:{detector_bundle}` | hot file verdict cache | active config, seed ≤30d | +| `han:safety:link:{url_hash}:{rules_version}:{config_version}` | stable local policy cache | active config, seed ≤48h | +| `han:safety:dns:{host_hash}:{rrtype}` | DNS answer; classification повторяется под текущей policy | actual TTL, active hard max seed 900s | +| `han:safety:wakeup` | Pub/Sub notification only | no storage | -Для требуемой заглушки task — ephemeral contract state. Истечение task возвращает безопасный `404 task_not_found/expired` по internal error semantics. В production safety authoritative audit/cache может находиться в PostgreSQL `message_safety`; Redis DB2 не заменяет его. +PostgreSQL `message_safety.safety_tasks` — единственный queue/lease source (`FOR UPDATE SKIP LOCKED`, fencing generation). Redis не хранит authoritative task state, locks или leases. Cache loss/restart безопасно восстанавливается из PostgreSQL; Redis outage не выключает core Safety. -Random verdict каждого GET по заданию независим; Redis хранит существование/TTL и счётчик polls для observability, но не предопределяет финал. В deterministic tests seed/RNG injected на уровне сервиса. +Legacy v1 stub может временно использовать DB2 ВМ1 для random task state. Этот namespace не используется production v2 и удаляется вместе со stub. ## 9. Serialization и limits @@ -112,8 +114,10 @@ Random verdict каждого GET по заданию независим; Redis | rate limit | window + 10–30% deterministic jitter | | realtime connection | 90s; set membership 120s | | coordination lock | 30s | -| safety task | default 15m, обязательно > API poll max 300s + recovery margin | -| safety cache | default 5–60m по rules version | +| safety file hot cache | ≤30d; authoritative row/version в PostgreSQL | +| safety text-rules cache | 48h; invalidation by rules version | +| safety stable link policy cache | 48h | +| safety DNS cache | actual DNS TTL, hard max 900s | Новый key без TTL запрещён contract test, кроме Pub/Sub channel (не key) и ops metadata с явным обоснованием. @@ -155,18 +159,18 @@ Eviction MVP: `volatile-lru`/`volatile-ttl`, так как все application ke DB0 rate = peak identities × routes × active windows × bytes/key DB0 idem = mutating requests/24h × avg sanitized record DB1 = peak connections × connection metadata + Pub/Sub buffers -DB2 = safety tasks within TTL × avg task metadata -total × 1.5 allocator/fragmentation × 1.3 growth reserve +Redis Safety = hot verdict/link/DNS entries + rate windows + Pub/Sub buffers +each instance total × 1.5 allocator/fragmentation × 1.3 growth reserve ``` Pub/Sub output buffers и slow consumers имеют hard/soft limits. Load test фиксирует peak RPS, WS connections, idempotency response size и AOF rewrite headroom. ## 15. Auth, ACL и network boundary -Redis не публикует `6379` на host, подключён только к Docker `backend`. `protected-mode yes`, bind container interface, default user отключён. ACL users: +Оба Redis не публикуют `6379` на host и подключены только к local Docker `backend` своей VM. `protected-mode yes`, default user отключён. ACL users: - `api_backend`: DB0/DB1 key prefixes, нужные command categories; -- `message_safety`: только DB2 prefixes; +- `message_safety`: только Redis Safety prefixes; - `ops_health`: `PING`, ограниченный `INFO`; Важно: Redis ACL не ограничивает logical DB напрямую надёжно; key-prefix patterns и разные credentials обязательны. `SELECT` запрещается, клиент URL сразу задаёт DB, но ACL prefix остаётся основной защитой. @@ -195,10 +199,10 @@ URL: ```text REDIS_URL=redis://api_backend:@redis:6379/0 REDIS_REALTIME_URL=redis://api_backend:@redis:6379/1 -MESSAGE_SAFETY_REDIS_URL=redis://message_safety:@redis:6379/2 +MESSAGE_SAFETY_REDIS_URL=redis://message_safety:@redis:6379/0 ``` -Добавление credential env требует обновления arch-04 `.env.example`; до этого имена credential variables — TBD, URL может содержать injected secret. +Первые два URL существуют только на ВМ1. На ВМ2 `MESSAGE_SAFETY_REDIS_URL=redis://message_safety:@redis:6379/0`; credential доставляется secret file и не входит в общий `.env`. ## 17. Health и degraded behavior @@ -211,7 +215,8 @@ MESSAGE_SAFETY_REDIS_URL=redis://message_safety:@redis:6379/2 - profile/history GET могут работать под edge limits; - public GET использует bounded local conservative limiter/cache; - realtime cross-instance publish/coordination деградирует; REST/polling остаётся source of truth; -- safety stub для digit task не может гарантировать GET task state — check возвращает `503`, а существующие task GET — `503`; синхронные text allow/deny могут работать только если policy явно разрешает Redis-independent path; +- production Safety продолжает task claim/poll через PostgreSQL; hot cache/rate/wakeup деградируют и прогреваются после восстановления Redis; +- legacy stub v1 может стать недоступным при потере своей DB2 до cutover; - internal inbox не теряется из-за Redis, так как durable receipt в PostgreSQL. При latency выше threshold clients используют short timeout/circuit, не создают бесконечные retry storms. Reconnect — exponential backoff+jitter. @@ -224,7 +229,7 @@ Redis backup не используется для бизнес restore. Runbook: 2. при целостном AOF/RDB восстановить на отдельном instance и проверить; 3. иначе поднять пустой Redis; 4. api-backend прогревает idempotency по durable records, realtime восстанавливается reconnect/polling; -5. незавершённые safety tasks обрабатываются по service semantics/expire; api-backend durable `safety_tasks` сообщает dependency error/recovery. +5. production safety tasks продолжают обрабатываться из PostgreSQL; Redis Safety прогревается лениво. Не копировать Redis dump в небезопасное место: keys содержат UUID и hashed identifiers. @@ -240,7 +245,7 @@ Redis backup не используется для бизнес restore. Runbook: - script errors/NOSCRIPT/slowlog; - rate limit decisions, idempotency hit/conflict/fallback; - Pub/Sub subscribers/output buffer/slow disconnect; -- safety task create/get/expire. +- Safety hot-cache hit/miss, DNS TTL cap и wakeup subscribers. Alerts: unavailable, p99 latency, >80/90% memory, any sustained evictions, AOF error, no recent persistence, client buffer pressure, unexpected keys without TTL. @@ -252,7 +257,7 @@ Alerts: unavailable, p99 latency, >80/90% memory, any sustained evictions, AOF e - idempotency same/different fingerprint, lock ownership, expiry, Redis loss + PostgreSQL fallback; - realtime heartbeat cleanup, duplicate disconnect, Pub/Sub loss + REST recovery; - locks expiry/late owner/fencing; -- safety task TTL, concurrent polls и missing task; +- Safety cache loss/rebuild, DNS TTL cap и доказательство отсутствия task/lease state в Redis; - `NOSCRIPT` reload; - all application keys имеют TTL; - max value/invalid serialization; @@ -279,6 +284,6 @@ Alerts: unavailable, p99 latency, >80/90% memory, any sustained evictions, AOF e **Решения:** один instance/три DB MVP; AOF everysec + RDB; Pub/Sub best effort; PostgreSQL durable fallback; prefix ACL; все application keys с TTL. -**Допущения:** одна VM и одна replica API на старте; Redis loss допустим без потери business truth. +**Допущения:** по одной Redis instance на ВМ1/ВМ2 и одна Safety API replica на старте; Redis loss допустим без потери business truth. **TBD:** R1 точный maxmemory после load profile; R2 eviction policy после измерений; R3 credential env names в arch-04; R4 Safety task TTL/recovery margin; R5 TLS при изменении network topology; R6 момент разделения DB на instances; R7 RPO/RTO ops target. diff --git a/modules/module-05-message-safety.md b/modules/module-05-message-safety.md index f9bb917..1d59cba 100644 --- a/modules/module-05-message-safety.md +++ b/modules/module-05-message-safety.md @@ -1,6 +1,6 @@ # module-05. Проектная спецификация `message-safety` -> Статус: целевая production-спецификация MVP. +> Статус: нормативная постановка целевой production-реализации v2, готовая к разработке после прохождения Definition of Ready (§18). Текущий v1 stub остаётся test-only до отдельного cutover. > Канонические источники: [`README.md`](../architectory/README.md), [`arch-00-glossary.md`](../architectory/arch-00-glossary.md), [`arch-01-system-architecture.md`](../architectory/arch-01-system-architecture.md), [`arch-02-api-contracts.md`](../architectory/arch-02-api-contracts.md), [`arch-03-docker-compose-blueprint.md`](../architectory/arch-03-docker-compose-blueprint.md), [`arch-04-settings-and-content.md`](../architectory/arch-04-settings-and-content.md), [`arch-05-agent-development-process.md`](../architectory/arch-05-agent-development-process.md), [`module-01-api-backend.md`](module-01-api-backend.md). ## 1. Назначение и приоритет @@ -9,27 +9,39 @@ Сервис закрывает угрозы, поступающие через пользовательское сообщение: -- управляющие и prompt-injection конструкции, направленные на оператора или последующую автоматическую обработку; +- semantic prompt-injection конструкции, которые в MVP только наблюдаются и не блокируют сообщение; - опасные URL-схемы, URL с credentials и ссылки на private/link-local/metadata адреса; - HTML/script-like payloads, способные стать активным содержимым при небезопасном отображении; - подмену типа файла, несоответствие заявленного MIME фактическому формату и checksum; - вредоносные файлы, обнаруживаемые антивирусными сигнатурами. -Спецификация детализирует архитектуру, но не меняет её. При конфликте приоритет имеют `arch-00`…`arch-05`. Канонические domain outcomes: +Спецификация детализирует обновлённую двух-VM архитектуру. При конфликте приоритет имеют `arch-00`…`arch-06`. Канонические domain outcomes v2: - `200 allow`; - `403 deny`; -- `203 pending` с последующим sticky `200` или `403`. +- `202 Accepted` с `Location`/`Retry-After` и последующим sticky `200` или `403`. Test-only правила по первому символу, случайные verdict и terminal `400 stub_final_error` в production-контракт не входят. +### 1.1. Владение решениями + +| Роль | Ответственность | +|---|---| +| Product Owner | бизнес-приёмка generic deny UX и мнемоники `safety.chat.blocked` | +| Safety Service Owner | lifecycle v2, API/data contracts, service-owned config, capacity и cutover sign-off | +| Rule Pack Owner | версия rules bundle, corpus, monitor rollout и release notes | +| Security Owner | approval `monitor → deny` и config changes, ослабляющих policy; threat model, egress/secrets и risk acceptance | +| Operations Owner | VM2, ClamAV signatures, alerts, rollback/reprovision и restore rehearsal | + +Один человек может выполнять несколько ролей, но для каждого production release роли и approvals должны быть записаны в release checklist. + ## 2. Границы ответственности ### 2.1. Сервис отвечает за - строгую валидацию internal DTO; - нормализацию и rule-based проверку текста; -- извлечение и проверку ссылок; +- извлечение и local-only проверку ссылок с versioned link cache; - валидацию file metadata и фактического формата; - чтение файла из S3-quarantine по read-only credentials; - вычисление authoritative SHA-256; @@ -37,7 +49,8 @@ Test-only правила по первому символу, случайные - выбор sync/async режима; - создание и исполнение async safety tasks; - sticky final verdict, verdict cache и audit в схеме `message_safety`; -- task coordination/cache/rate limits в Redis DB2; +- versioned text-rules cache по hash analysis form без хранения текста; +- PostgreSQL task queue/leases; Redis Safety только hot cache/rate/wakeup; - internal API, health, метрики, трассировку и безопасные JSON-логи. ### 2.2. Сервис не отвечает за @@ -53,20 +66,48 @@ Test-only правила по первому символу, случайные Этими операциями владеет `api-backend` или соответствующий архитектурный модуль. +### 2.3. Аварийный режим MOCK + +Режим предназначен для ручного controlled bypass при поломке или неприемлемой деградации полного pipeline. + +| Настройки | Text result | File result | +|---|---|---| +| `MOCK=false` | стандартный pipeline этого документа | стандартный pipeline этого документа | +| `MOCK=true`, `TEXT_FREE=true`, `FILE_FREE=true` | forced `200 allow` | forced `200 allow` | +| `MOCK=true`, `TEXT_FREE=true`, `FILE_FREE=false` | forced `200 allow` | forced `403 deny` | +| `MOCK=true`, `TEXT_FREE=false`, `FILE_FREE=true` | forced `403 deny` | forced `200 allow` | +| `MOCK=true`, `TEXT_FREE=false`, `FILE_FREE=false` | forced `403 deny` | forced `403 deny` | + +При `MOCK=true` не выполняются normalization/rules, URL extraction/DNS, S3 read/checksum/format/ClamAV, verdict caches, task creation и async worker. Service authentication, body-size/JSON/strict DTO validation, idempotency conflict protection, PostgreSQL audit и rate limits остаются обязательными controls. + +Forced allow использует `rule_id=safety.mock_forced_allow`; forced deny — `rule_id=safety.mock_forced_deny`, `reason_code=message_blocked`. Mock никогда не возвращает `202`. Internal response содержит `processing_mode=mock`; `api-backend` не раскрывает mode/rule клиенту. Mode фиксируется при первом принятии `message_id`: ранее созданный standard task/idempotency result не переклассифицируется и завершается в standard, а новый mock request не создаёт task. Это исключает смену verdict посередине обработки. + +MOCK не включается HTTP endpoint-ом. Root-owned helper атомарно меняет защищённый config и перезапускает фиксированную Message Safety API operation внутри root Compose project; пользователь `deploy` может через sudo запускать только этот helper, без доступа к Docker/config: + +```text +sudo /usr/local/sbin/han-message-safety-mode standard +sudo /usr/local/sbin/han-message-safety-mode mock --text-free true|false --file-free true|false +``` + +Helper принимает только указанные enum/boolean arguments, не принимает пути/commands/env expansion, пишет `/etc/han-chat/message-safety-mode.env` как `root:han-message-safety 0640` (dedicated GID `10001` совпадает с primary GID контейнера), проверяет config, выполняет restart и health verification. Ошибка включает rollback к предыдущему файлу. Ограничения по времени нет: MOCK действует до явного `standard`, но всё время формирует audit/метрики и active alert. +Команда `standard` атомарно записывает `MOCK=false`, `TEXT_FREE=false`, `FILE_FREE=false`; скрыто сохранять предыдущие free flags запрещено. + ## 3. Threat model MVP ### 3.1. Текст и ссылки | Угроза | Контроль | Результат | |---|---|---| -| Prompt/control injection | Версионированные Unicode-aware rules | `403 deny` | -| Попытка выдать текст за system/developer instruction | Нормализация + rule pack | `403 deny` | +| Prompt/control injection | Версионированные RU/EN semantic rules | `200 allow` + monitor audit/metric | +| Попытка выдать текст за system/developer instruction | Нормализация + monitor rule pack | `200 allow` + monitor audit/metric | | Script/active-content payload | Правила для script, event-handler и опасных embedding-конструкций | `403 deny` | | Опасная URL-схема | Разрешены только `http` и `https` для распознанных web URL | `403 deny` | | URL с userinfo/credentials | Запрет `user:password@host` | `403 deny` | | SSRF-ссылка | DNS/IP classification, запрет private, loopback, link-local, multicast, unspecified и metadata endpoints | `403 deny` | +| Известный phishing/malware URL | Внешний reputation provider в MVP отсутствует; риск явно принят | Вне покрытия MVP | | Обход Unicode/whitespace | NFKC, CRLF→LF, Unicode whitespace handling | Проверка нормализованного текста | -| ReDoS/DoS правилами | Линейные/ограниченные regex, лимиты текста, URL и времени | `400` или dependency error | +| ReDoS/DoS правилами | Линейные/ограниченные regex, лимиты текста, URL и времени | invalid limits → `400`; internal rule timeout → `500` | +| SSRF через fetch содержимого | **Запрет** HTTP GET/HEAD/render/redirect follow к пользовательским URL | Не выполняется | Rules не заменяют безопасный rendering. Frontend и Bitrix integration обязаны экранировать текст; safety является дополнительным барьером, а не HTML sanitizer. @@ -76,13 +117,13 @@ Rules не заменяют безопасный rendering. Frontend и Bitrix i |---|---|---| | Недопустимый размер/MIME | Сверка DTO с allow-list и лимитами | `403 deny` | | Подмена MIME | Magic-byte/content sniffing, сверка declared MIME | `403 deny` | -| Подмена содержимого после complete | Полный SHA-256 против DTO checksum | `403 deny` | +| Подмена содержимого после complete | Version-specific read + ETag + полный SHA-256 | `403 deny` | | Malware | ClamAV scan актуальными сигнатурами | `403 deny` | | Архивная бомба/ресурсное истощение | Лимиты размера, stream scan, ClamAV limits/timeouts | deny при policy hit; error при сбое | | Polyglot/неоднозначный формат | Строгий формат detector и deny при mismatch/ambiguity | `403 deny` | | Повтор известного файла | Cache по SHA-256 + versions | Sticky cached verdict | -MVP принимает только типы из `chat.attachments.allowed_extensions` и `chat.attachments.allowed_mime_types`, при `chat.attachments.max_size_mb`. Расширение проверяет `api-backend` до вызова safety; `message-safety` независимо проверяет MIME и фактический формат байтов. Internal DTO не содержит имени файла, поэтому сервис не выводит расширение из object key. +`api-backend` применяет изменяемый бизнес allow-list `han_app.app_settings:chat.attachments.*`. `message-safety` не читает чужую схему `han_app`: он применяет active `message_safety.config_versions.file_policy` и immutable detector manifest §7.4. Эффективный allow — пересечение business allow-list, enabled MIME active safety config и форматов detector manifest; MIME/size в DTO должны пройти все слои. Config может только отключить MIME или ужесточить limits относительно manifest hard limits, но не добавить неподдерживаемый формат и не увеличить hard limit. Internal DTO не содержит имени файла, поэтому сервис не выводит расширение из object key. ### 3.3. Вне threat model MVP @@ -90,22 +131,51 @@ MVP принимает только типы из `chat.attachments.allowed_exte - OCR изображений и semantic analysis PDF; - password-protected/encrypted containers: в MVP они запрещаются, если содержимое нельзя полностью проверить; - DLP/поиск персональных данных, токсичности и запрещённой тематики; -- переход по пользовательской ссылке и анализ удалённой страницы. +- загрузка HTML/ресурсов страницы по пользовательской ссылке (browser-like fetch, redirect follow, screenshot, headless render); +- phishing/malware reputation URL без внешнего threat feed. ## 4. Общий pipeline ```mermaid flowchart TD - postCheck[POST_check] --> auth[Auth_and_DTO] - auth --> kind{content_kind} + postCheck[POST_check] --> auth[Auth_DTO_Idempotency] + auth --> mockMode{MOCK_enabled} + mockMode -->|true| mockKind{content_kind} + mockKind -->|text| mockText{TEXT_FREE} + mockKind -->|file| mockFile{FILE_FREE} + mockText -->|true| allow200[200_allow] + mockText -->|false| deny403[403_deny] + mockFile -->|true| allow200 + mockFile -->|false| deny403 + mockMode -->|false| kind{content_kind} kind -->|text| normalizeText[Normalize_text] - normalizeText --> textRules[Text_rules] - textRules --> linkRules[Link_pipeline] - linkRules --> syncVerdict[200_or_403] + normalizeText --> textCache{Text_rules_cache} + textCache -->|deny_hit| deny403 + textCache -->|allow_or_monitor_hit| replayMonitor[Replay_monitor_audit] + textCache -->|miss| textRules[Text_rules] + textRules -->|deny| deny403 + textRules -->|allow_or_monitor| persistTextCache[Persist_text_rules_result] + replayMonitor --> extractUrls[Extract_URLs] + persistTextCache --> extractUrls + extractUrls --> hasUrls{URLs_found} + hasUrls -->|no| allow200 + hasUrls -->|yes| linkCache{Link_cache} + linkCache -->|allow_hit| refreshDns[Refresh_DNS_if_expired] + linkCache -->|deny_hit| deny403 + linkCache -->|miss| linkChecks[Local_URL_checks] + refreshDns --> linkResult{Link_result} + linkChecks --> dnsClassify[DNS_IP_classification] + dnsClassify --> linkResult + linkResult -->|allow_or_monitor| allow200 + linkResult -->|policy_deny| deny403 + linkResult -->|dependency_error| error503[503_dependency] kind -->|file| metadata[Metadata_validation] metadata --> cache{SHA256_cache} cache -->|hit| cached[Sticky_200_or_403] - cache -->|miss| task[203_and_task] + cached --> cachedFileResult{Cached_file_verdict} + cachedFileResult -->|allow| allow200 + cachedFileResult -->|deny| deny403 + cache -->|miss| task[202_and_task] task --> worker[File_worker] worker --> objectRead[S3_stream_and_SHA256] objectRead --> formatCheck[Format_validation] @@ -118,10 +188,11 @@ flowchart TD 1. service authentication, body/content-type/size и DTO validation; 2. idempotency/fingerprint conflict; -3. нормализация; -4. обязательные проверки для соответствующего `content_kind`; -5. любой deny имеет приоритет над allow; -6. инфраструктурная ошибка не превращается ни в allow, ни в domain deny. +3. mode snapshot: MOCK forced result либо standard pipeline; +4. нормализация; +5. обязательные проверки для соответствующего `content_kind`; +6. любой deny имеет приоритет над allow; +7. инфраструктурная ошибка не превращается ни в allow, ни в domain deny. ## 5. Текстовый pipeline @@ -132,16 +203,24 @@ Pipeline детерминирован: 1. принять только JSON UTF-8; 2. заменить `CRLF`/`CR` на `LF`; 3. Unicode normalization `NFKC`; -4. удалить leading Unicode whitespace; -5. сохранить исходный регистр и punctuation для rules; -6. ограничить текст internal DTO до 10 000 Unicode code points; -7. вычислить SHA-256 нормализованного текста для correlation/cache без хранения текста. +4. построить analysis form: унифицировать Unicode whitespace, удалить/маркировать default-ignorable и zero-width controls, отдельно выявить bidi controls; +5. построить TR39 confusable skeleton и mixed-script signal только для detection; mixed-script сам по себе не является deny; +6. сохранить display form, исходный регистр и punctuation без изменения пользовательского текста; +7. применить IDNA2008/UTS-46 non-transitional к hostname; +8. применить абсолютный hard ceiling **10 000 Unicode code points**; значение не может быть увеличено runtime-настройкой, даже если бизнес-лимит станет больше; +9. вычислить SHA-256 analysis form для correlation/cache без хранения текста. -`content_kind=text` требует поле `text`; пустой текст отклоняется upstream `api-backend`. `content_kind=file` допускает пустой `text`; текстовые rules тогда не запускаются. +Превышение 10 000 code points после normalization → `400 validation_error`, `details.field=text`. Flags `default_ignorable`, `zero_width`, `bidi_control`, `mixed_script` записываются только как bounded `normalization_flags[]` в audit/metrics и не влияют на verdict MVP. + +Strict union проверяется повторно независимо от upstream: + +- `content_kind=text` требует непустой `text` и `attachment=null`; +- `content_kind=file` требует `text==""` и непустой `attachment`; +- mixed/unknown shape → `400 validation_error` до создания task или idempotency side effect. ### 5.2. Rule engine -Rules поставляются как статический read-only bundle приложения. Динамический код, regex или rule definitions из запроса запрещены. +Rules поставляются как статический read-only bundle `app/rules/{rules_version}/rules.yaml`, валидируемый committed JSON Schema. Динамический код, regex или rule definitions из запроса запрещены. Каждое правило содержит: @@ -149,45 +228,139 @@ Rules поставляются как статический read-only bundle п - `reason_code`; - severity; - scope (`text`, `url`, `file_metadata`); -- action (`deny`); +- action (`deny` | `monitor`); - `rules_version`; - тестовые positive/negative cases. -Начальный rule pack MVP: +Нормативный каталог MVP: -- `text.prompt_instruction_override` — конструкции вида «игнорируй предыдущие инструкции» и эквиваленты на поддерживаемых языках; -- `text.prompt_role_impersonation` — попытка обозначить пользовательский фрагмент как system/developer/tool instruction; -- `text.prompt_secret_extraction` — запрос раскрыть system prompt, credentials, tokens или внутренние инструкции; -- `text.active_script` — `