docs(ai): add scoped backend conventions

2026-09-09 16:23:03 +03:00
parent 320e8a04b0
commit a83e26e5ef
10 changed files with 377 additions and 36 deletions
@@ -0,0 +1,51 @@
+# Security и auth
+
+Читай при изменении session/token/cookie/guard, account access, encryption или
+sensitive logging; обычный data query без этой границы не требует всего документа.
+
+## Выбор владельца
+
+Identity/session — AuthService + strategy/guard; cookie transport — AuthController;
+account access/connection generation — TbankAccessService; token crypto —
+TbankTokenService/TbankCrypto. Расширяй существующую boundary, не добавляй
+второй JWT middleware, decrypt helper или refresh coordinator.
+
+[Authentication](../../../docs/features/authentication.md) и
+[ADR 006](../../../docs/adr/006-auth-session-policy.md)/[009](../../../docs/adr/009-concurrent-refresh-rotation-policy.md)
+задают session semantics. Access хранится только в памяти frontend; refresh
+передаётся httpOnly cookie. Source code конфигурации cookie —
+[AuthController](../../src/auth/auth.controller.ts); изменение flags/path требует
+проверки browser/HTTP поведения, не только TypeScript.
+
+Refresh rotation атомарна: один победитель, проигравший/superseded token получает
+401, но сам по себе не отзывает session победителя. Не вводи replay history/grace
+или иной security contract без текущей задачи. Logout идемпотентен; in-memory
+frontend session/cache очищается и при network failure.
+
+## Trust boundaries
+
+Verified JWT не доказывает доступ к accountId из URL. Используй user.sub и
+existing account access policy; не доверяй userId/token из клиента как authority.
+Cross-user, invalid/expired/superseded token и concurrent requests — обязательные
+cases для соответствующего изменения.
+
+T-Bank credentials остаются server-side и хранятся encrypted. Используй
+existing AES-256-GCM boundary с validated 32-byte key; не печатай plaintext,
+шифротекст, cookie, Authorization или connection generation в logs/errors/API.
+[Connection source](../../../docs/features/tbank-connection.md) определяет
+cache invalidation при замене/deletion и ограничение key rotation.
+
+Не передавай Prisma User/Session целиком наружу; выбирай public DTO. Пароль
+обрабатывает существующий bcrypt flow. Не копируй требования о нормализации
+или длине из tutorial: сверяй runtime DTO, tests и feature source.
+
+## Безопасный путь и проверка
+
+При неясной ownership/crypto/session семантике прочитай exact source до edits.
+Добавляй проверку на ответственной границе; не скрывай проблему общим catch,
+фиктивным success или log. Logger allowlist/redaction не делает произвольный
+message безопасным.
+
+Targeted auth/access/crypto/logging tests + [Testing](backend-testing.md).
+Cookie/guard/HTTP changes требуют configured HTTP proof; frontend Bearer/retry
+проверяется MSW. Schema parity не доказывает отсутствие утечки secret.