Добавлена Яндекс.Капча

architectory/arch-03-docker-compose-blueprint.md

@@ -240,7 +240,7 @@ Identity provider. **Обязателен** в compose-контуре с пер
 - включены proxy settings для работы за `nginx`;
 - импорт realm в local/dev;
 - использует managed PostgreSQL, схема `keycloak` (см. раздел «Managed PostgreSQL» выше);
-- OTP mock / SMS SPI — см. arch-04; real mode вызывает только `sms-service` по сети `backend`, сам Keycloak к Direct/`egress` не подключён;
+- OTP mock / SMS SPI — см. arch-04; real mode вызывает `sms-service` по сети `backend`, а единственный утверждённый внешний вызов Keycloak через `egress` — server-side validation Yandex SmartCaptcha;
 - healthcheck;
 - взаимодействия — [`arch-02-api-contracts.md`](arch-02-api-contracts.md), «Frontend ↔ Keycloak», и [`arch-01-system-architecture.md`](arch-01-system-architecture.md), «Keycloak».
 
@@ -282,7 +282,7 @@ 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 — `sms-worker`, но не Keycloak. Production real mode требует фактический статический egress IP/NAT, записанный в inventory и переданный Direct для allowlist.
+- `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.
 
 Базы данных, Redis, Keycloak internal port и API internal port не должны публиковаться наружу. `message-safety` доступен только внутри сети `backend`. Основной пользовательский путь должен идти через `nginx` и HTTPS.

architectory/arch-04-settings-and-content.md

@@ -29,6 +29,7 @@ Managed PostgreSQL **поднимается до** развёртывания п
 - параметры **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 не попадает в тему/логи;
 - технические параметры сервисов, пока профильная спецификация не определила service-owned settings; для `sms-service` runtime-параметры уже вынесены в `sms.sms_setting`.
 
 **Запрещено в `.env` (→ только `app_settings`):**
@@ -226,6 +227,9 @@ 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
 
 # =============================================================================