# Руководства

## Конфигурация
- **Keys**: передайте `Keys` с JWKS URL. Первая загрузка синхронная; далее автоматическое обновление по TTL.
- **ConfigSession.header**: должен содержать `alg` и `kid` для операций JWT/JWE.
- **ConfigSession.key**: приватный ключ для подписи и JWE дешифрования (PEM байты или `Key`).
- **Audience**: если задан, сеттер `Session.aud` принимает только значения из списка.

## Жизненный цикл claims
- При вызове `session.jwt`:
  - генерируется новый `jti`
  - `sid` генерируется один раз, если отсутствует
  - выставляются `iat`, `nbf`, `exp` согласно `expires`
  - `trace` вычисляется из `Trace` и `jti`

## Семантика слияния (`session + jwt_str`)
- Все декодированные claims копируются в текущую сессию.
- Claims из `Session.merge_attributes` сливаются (по умолчанию `("_payloads", "scope")`).
- Словари — глубокое слияние; списки — удаление дублей (порядок не гарантируется).

## Использование JWE
- `serialize(payload, header)` использует публичный ключ по `kid` из `Keys`.
- `deserialize(token)` требует `ConfigSession.private`.

## Опции валидации
- `Session.options` всегда включает:
  - фиксированный `version`
  - фиксированное `sid`, только когда `Session.sid` уже существует
  - проверку `trace` через `Trace.validate`
  - список допустимых `aud`, если сконфигурирован

## Эксплуатационные рекомендации
- Текущая реализация `Keys`:
  - Первая загрузка JWKS выполняется синхронно через `requests.get(self.url)` без таймаута.
  - Фоновое обновление выполняется через `aiohttp.ClientSession().get(self.url, ssl=...)`, где `ssl` управляется параметром `verify_tls`.
- Практические рекомендации (при необходимости адаптируйте под вашу среду):
  - Оборачивайте `Keys.load()` или наследуйтесь от `Keys`, чтобы добавить явные таймауты и ретраи для `requests` и `aiohttp`.
  - Включайте проверку TLS (`verify_tls=True`), если источник JWKS доступен по доверенному HTTPS; отключайте только для тестов.
  - В долгоживущих сервисах инициируйте раннее обновление ключей: вызовите `keys.load(background=True)` на старте, чтобы актуализировать JWKS в фоне.

## Безопасность
- Регулярно ротируйте ключи; используйте консервативные значения `expires`.
- Ограничивайте audience; валидируйте токены с `SessionClaims`.
- Не логируйте сырые JWT/JWE и чувствительные claims.
