Последние несколько месяцев я постепенно переделывал основную концепцию библиотеки. В итоге изменений накопилось достаточно много, поэтому 4.0 это не просто очередной набор новых фич, а довольно серьёзный пересмотр того, чем вообще должен быть Jam.

Если коротко: раньше Jam был скорее набором отдельных инструментов для authentication, а теперь постепенно превращается в полноценный authentication/authorization framework.

jam.Jam

Самое заметное изменение - полностью переделанный jam.Jam-фасад.

Раньше он был скорее удобной надстройкой над отдельными модулями:

from jam import Jam

jam = Jam(config=config)

jwt_token = jam.jwt_encode(payload={"sub": 1})
payload = jam.jwt_decode(token=jwt_token)

Это работало, но в таком API приложение всё равно фактически знает, что оно использует JWT.

В 4.0 я хотел уйти от этого уровня абстракции. Приложение должно работать с понятиями auth (x/z), а конкретный механизм: jose, paseto, session и тд - должен оставаться деталью реализации.

Поэтому теперь основной flow выглядит примерно так:

from dataclasses import dataclass

from jam import Jam, BaseSubject


@dataclass
class User(BaseSubject):
    id: int
    email: str
    role: str = "user"


jam = Jam(config=config)

user = User(
    id=1,
    email="some@mail.com",
)

# выпускаем credentials для пользователя
token = jam.issue(subject=user)

# аутентифицируем credentials
principal = jam.authenticate(token=token)

assert principal.subject.id == user.id

# и выполняем авторизацию
allowed = jam.authorize(
    principal=principal,
    permission="post:delete",
)

Здесь появляются две важные сущности: Subject и Principal.

Subject это сущность, от имени которой выполняется authentication. В простейшем случае это пользователь, но это не обязательно должен быть именно пользователь, например какая-то виртуальная машина, которая запрашивает доступы к определенным ресурсам.

Principal результат authentication. Он содержит subject и информацию, необходимую для дальнейшей авторизации.

Мне такой подход нравится гораздо больше: конкретный механизм authentication становится заменяемой деталью, а application code работает с единой моделью.

Интеграции с фреймворками

Вместе с этим переработал интеграции с фреймворками.

Например, с FastAPI теперь это выглядит так:

from typing import Annotated

from fastapi import Depends, FastAPI

from jam import Jam
from jam.authz import Principal
from jam.ext.fastapi import JamAuth


jam = Jam("config.toml")
auth = JamAuth(jam)

app = FastAPI()


@app.get("/me")
def me(
    principal: Annotated[
        Principal,
        Depends(auth), # получаем principal
    ],
):
    return principal.subject


@app.get("/landing")
def landing(
    principal: Annotated[
        Principal | None,
        Depends(auth.optional), # не обязательная аутенфикация
    ],
):
    return {
        "authenticated": principal is not None,
    }


@app.patch("/posts/{post_id}")
def edit_post(
    post_id: str,
    principal: Annotated[
        Principal,
        Depends(auth.require("post:edit")), # конкретный пермишен
    ],
):
    return {
        "post_id": post_id,
        "editor": principal.subject,
    }

При этом application code получает уже готовый Principal, а не разбирается с заголовками, токенами и конкретным механизмом authentication.

Можно просто получить текущего пользователя:

Depends(auth)

Можно разрешить anonymous access:

Depends(auth.optional)

А можно сразу потребовать permission:

Depends(auth.require("post:edit"))

То есть authorization можно достаточно естественно встроить прямо в application flow.

При этом отдельные механизмы никуда не делись

При всём этом я не хотел превращать Jam в монолит.

Отдельные модули по-прежнему можно использовать независимо друг от друга. Если вам нужен только конкретный механизм, можно работать с ним напрямую. Если же хочется построить поверх Jam полноценный authentication flow - для этого теперь есть Jam.

Для меня это довольно важная часть архитектуры: модули должны оставаться заменяемыми и не зависеть друг от друга больше необходимого.

Keychain

Но киллер-фичей этого релиза я всё-таки считаю keychain. Я уже писал про эту идею раньше, но за время реализации механизм немного переработал. Проблема, которую я хотел решить, довольно простая. Приложение не должно само заниматься хранением и ротацией криптографических ключей.

Например, для JWT можно указать keychain в конфигурации:

[jam.jose.jwt]
alg = "RS256"
keychain = "jose_keys"

[jam.keychains.jose_keys]
# Пока доступны только FileStorage и MemoryStorage.
# В будущем хочу добавить HashiCorp Vault,
# а остальные варианты можно будет реализовать
# через публичный интерфейс.
type = "FileStorage"
path = "/opt/keys"

После этого приложение работает уже с keychain:

from jam import Jam
from jam.keychain import FileStorage


jam = Jam(config="config.toml")

keychain: FileStorage = jam.keychains["jose_keys"]

# Добавляем ключ.
#
# Если material не передавать,
# Jam сам сгенерирует ключ
# исходя из конфигурации.
keychain.add(
    key_id="my-key-id",
)

# Получаем текущий ключ.
keychain.current(key_id="my-key-id")

# Выпускаем credentials.
token = jam.issue(
    subject={"sub": 1},
)

# Ротируем ключ.
keychain.rotate()

Здесь важна не столько сама возможность вызвать rotate(), сколько то, что приложение вообще не обязано знать, где физически хранятся ключи и какой из них сейчас используется.

Например, представим, что приложение несколько месяцев работает в production, а потом возникает необходимость заменить приватный ключ. Без keychain это легко превращается в ручную процедуру: найти файлы с ключами, заменить их, разобраться с уже выпущенными токенами и не сломать валидацию старых credentials. С keychain эта логика становится частью инфраструктуры authentication. Новый ключ можно сделать текущим, а старые ключи при этом оставить доступными для проверки уже выпущенных токенов.

То есть rotation не должен автоматически означать: старые токены перестали работать прямо сейчас.

Это особенно полезно для распределённых приложений, где несколько экземпляров сервиса могут какое-то время находиться на разных версиях конфигурации.

Управление через CLI

Keychain'ом можно так же управлять из консоли, во время запущенного приложения.

Например:

$ pip install jamlib[cli]

$ jam keychain --config jam.toml rotate jose_keys

$ jam keychain --config jam.toml list jose_keys

Это позволяет выполнять операции с ключами без необходимости писать отдельный deployment script или лезть непосредственно в storage.

Пока реализованы два storage:

• FileStorage
• MemoryStorage

Дальше хочу расширять эту часть. В частности, планирую добавить интеграцию с HashiCorp Vault.

При этом я не хочу делать отдельную реализацию для каждого возможного secret storage. Для остальных вариантов будет публичный интерфейс, через который можно будет реализовать собственный backend.

Что изменилось с точки зрения архитектуры

Наверное, самое важное изменение 4.0.0: Jam постепенно перестаёт быть просто библиотекой с набором auth-инструментов.

Условно раньше application code выглядел примерно так:

Application
    |
    +-- JWT
    +-- PASETO
    +-- Sessions
    +-- OAuth2
    +-- ...

Теперь я хочу двигаться к модели:

Application
    |
    +-- Jam
          |
          +-- Authentication
          |
          +-- Authorization
          |
          +-- JWT
          +-- PASETO
          +-- Sessions
          +-- OAuth2
          +-- ...

При этом конкретные механизмы остаются модулями, которые можно использовать независимо. Получается некоторый слой абстракции над authentication, но без попытки спрятать вообще всё за одним огромным классом.

Что дальше?

В ближайших планах:

• расширение keychain на другие модули
• hashicorp storage
• saml в основном фасаде jam.Jam
• macaroons + biscuits токены
• расширение возможности authz настроек

GitHub Release | Documentation

Я и сам давно сталкиваюсь с этой проблемой. Практически в каждом проекте приходится заново реализовывать ротацию ключей, хранение их истории, поддержку отозванных ключей и обработку ситуации, когда ключ уже заменён, но выпущенные ранее токены всё ещё должны считаться валидными.

JWT, PASETO и другие форматы токенов обычно решают задачу подписи и верификации данных, но управление самими ключами почти всегда остаётся на совести разработчика. В результате каждый проект изобретает собственный велосипед.

Со временем Jam перестал быть просто библиотекой для работы с токенами и постепенно превратился в полноценный auth-фреймворк: появились принципалы и субъекты аутентификации, собственный DSL для описания прав доступа (об этом после релиза уже :D ), унифицированные интерфейсы для различных механизмов авторизации. Поэтому появление keychain выглядело вполне логичным следующим шагом.

Основная идея проста: предоставить абстракцию хранилища ключей и единый интерфейс работы с ним. Пользователь может использовать встроенные реализации или написать собственную — например, для хранения ключей в PostgreSQL, HashiCorp Vault, AWS KMS, Redis или любом другом бэкенде.

На данный момент Jam поставляется с двумя реализациями:

• FileStorage: хранение ключей на файловой системе;
• MemoryStorage: хранение ключей в памяти процесса.

В текущей (ещё не выпущенной) версии Jam 4.0.0 это выглядит так.

Сначала в конфигурации создаётся один или несколько keychain'ов:

[jam.keychains.keychain_name]
type = "FileStorage"
path = "./keychain"

[jam.paseto]
version = "v4"
purpose = "local"
keychain = "keychain_name"

После этого PASETO или сам Jam будут автоматически получать ключи из указанного keychain'а.

Пример прямого использования PASETO:

from jam.paseto import PASETOv4

paseto = PASETOv4.key(
    config="config.toml"
)

token = paseto.encode(
    payload={
        "sub": "1",
        "role": "admin"
    },
    footer=None
)

Или через общий интерфейс Jam:

from jam import Jam

jam = Jam(config="config.toml")

token = jam.issue(
    sub={"sub": "1", "role": "admin"},
    via="paseto"
)

Возникает вопрос: а как добавлять новые ключи и выполнять их ротацию?

Для этого предусмотрены два способа. Первый подходит для встраивания в бизнес-логику приложения, второй — для администрирования через CLI.

Через Python API:

from jam.keychain import FileStorage

keychain = FileStorage(
    path="./keychain",
    name="keychain_name"
)

# добавить новый ключ
keychain.add(
    id="new-key-id"
)

# сделать его активным
keychain.current(
    id="new-key-id"
)

# выполнить ротацию
keychain.rotate()

# удалить ключ
keychain.remove(
    id="new-key-id"
)

Через Jam CLI:

# установить CLI
pip install jamlib[cli]

# добавить ключ
jam keychain --config config.toml add keychain_name new-key-id

# сделать активным
jam keychain --config config.toml current keychain_name new-key-id

# выполнить ротацию
jam keychain --config config.toml rotate keychain_name

# удалить ключ
jam keychain --config config.toml remove keychain_name new-key-id

Однако самое интересное здесь не встроенные реализации, а возможность написать собственный keychain.

Например, если ключи должны храниться в PostgreSQL:

from jam.keychain import BaseKeychain
from jam.keychain.models import Key


class PostgresKeychain(BaseKeychain):
    async def get(self, id: str) -> Key | None:
        ...

    async def add(self, key: Key) -> None:
        ...

    async def remove(self, id: str) -> None:
        ...

    async def list(self) -> list[Key]:
        ...

    async def current(self) -> Key:
        ...

    async def set_current(self, id: str) -> None:
        ...

После этого реализацию можно зарегистрировать в приложении и использовать в конфигурации точно так же, как встроенные FileStorage и MemoryStorage.

В результате Jam ничего не знает о том, где физически лежат ключи. Они могут храниться на диске, в базе данных, во внешнем секретном хранилище или в облачном KMS. Всё взаимодействие происходит через единый интерфейс keychain.

Самое приятное в таком подходе - то, что PASETO, JWT, сессионные токены и любые другие механизмы внутри Jam используют один и тот же keychain. Ротация ключей, управление жизненным циклом и история ключей настраиваются один раз и затем работают одинаково для всех типов токенов.

Пока это только первая версия функциональности, но мне кажется странным, что подобного механизма до сих пор нет во многих БОЛЬШИХ библиотека, как authx, flask-login, fastapi-users, django-allauth и прочих. Для работы с базами данных у нас есть ORM, для кэшей - готовые абстракции и драйверы, а управление криптографическими ключами зачастую до сих пор сводится к файлу в директории проекта и нескольким строчкам самописного кода. У нас есть JWKS-клиенты, но там все равно все ложится на плечи разработчика и происходит дублирование механизмов из проекта в проект.

Надеюсь, что в Jam этот пробел получится закрыть.

В итоге я стал инициатором и катализатором внедрения AI в разработку.

Поэтому решил рассказать про свой опыт и показать, как и что я делал, чтобы это можно было повторить и вам.

Из-за того, что это всё ещё кровавый энтерпрайз, встал вопрос о разворачивании LLM локально, внутри контура. Claude, Codex и прочие облачные решения были под тотальным запретом.

Что у меня было

После нескольких месяцев, как я ходил и всем говорил про ИИ, мне выдали машинку с Nvidia H100, и я пошёл разбираться, как всё это работает. До этого у меня был только опыт запуска моделей на домашнем компьютере, поэтому изначально казалось, что всё примерно одинаково. Но довольно быстро выяснилось, что корпоративная инфраструктура умеет подкидывать свои сюрпризы.

На моей карточке было всего 80 ГБ видеопамяти. По меркам современных моделей это не так уж много, поэтому выбирать приходилось осторожно.

Я рассматривал:

• DeepSeek
• Qwen3
• Qwen3.6
• Qwen3-Coder

После небольших тестов остановился на Qwen/Qwen3-Coder-30B-A3B-Instruct, потому что deepseek-ai/deepseek-coder-33b-base (единственный более-менее адекватный DeepSeek, который помещался в память) оказался откровенно слабоват, а Qwen3.6 вообще не завёлся из-за драйверов.

Но об этом чуть позже.

Первый запуск vLLM

Как и любой нормальный человек, я сначала просто поднял модель через vLLM и начал дёргать её напрямую через API.

mkdir vllm && cd vllm

pip install --upgrade pip
pip install uv

uv venv --python 3.12 --seed --managed-python
source ~/vllm/.venv/bin/activate

uv pip install -U \
  "transformers<5" \
  "vllm==0.10.2"

uv run vllm serve Qwen/Qwen3-Coder-30B-A3B-Instruct \
  --host 0.0.0.0 \
  --port 8000

И вот тут уже начались приключения.

Когда корпоративная инфраструктура встречается с LLM

Некоторые уже заметили, что версии vllm и transformers здесь далеко не самые свежие. Это не случайно. Карту мне выдали через MIG, а вместе с ней достался целый набор ограничений. Основная проблема была в драйверах. Обновить их я не мог, а из-за архитектурных и бюрократических особенностей администраторы тоже не смогли этого сделать.

Именно поэтому у меня так и не завёлся Qwen 3.6.

Но на этом веселье не закончилось.

Каждую ночь примерно в 2:00 MIG на несколько секунд исчезал из системы, а потом возвращался уже с новым UID. Разбираться, кто именно виноват, желания не было, поэтому я принял максимально инженерное решение:

Каждое утро в 5:00 сервер просто перезагружается.

В результате:

• появляется свежий UID;
• исчезают накопившиеся проблемы;
• получается профилактическая перезагрузка перед началом рабочего дня.

Да, костыль, но зато рабочий.

Почему одного vLLM недостаточно

Несколько дней я спокойно пользовался моделью сам. Но довольно быстро стало понятно, что такой подход подходит только для одного человека. Если моделью начнут пользоваться другие сотрудники, понадобится:

• веб-интерфейс;
• управление пользователями;
• интеграция с корпоративной авторизацией;
• возможность быстро отзывать доступы;
• OpenSource-решение, которое можно дорабатывать самостоятельно.

После небольшого исследования я остановился на OpenWebUI. Там оказалось всё, что мне было нужно, и даже больше.

OpenWebUI как точка входа

Сначала OpenWebUI жил на той же машине, что и vLLM. Но довольно быстро стало заметно, что он начинает отъедать ресурсы, которые хотелось бы оставить модели. Поэтому я поднял отдельную виртуальную машину. В итоге схема стала такой:

Пользователь работает с OpenWebUI, а уже OpenWebUI отправляет запросы в vLLM. Это оказалось удобно сразу по нескольким причинам:

• можно ограничивать доступ отдельным пользователям или группам;
• можно собирать статистику;
• можно собирать оценки ответов;
• можно централизованно управлять системными промптами.

Выжимаем максимум из 80 ГБ памяти

После этого я начал экспериментировать с настройками модели, первой мыслью было увеличить контекстное окно. Попробовал так:

uv run vllm serve Qwen/Qwen3-Coder-30B-A3B-Instruct \
  --max-model-len 120000

Не взлетело.

После серии экспериментов пришёл к такой конфигурации:

uv run vllm serve Qwen/Qwen3-Coder-30B-A3B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --dtype bfloat16 \
  --max-model-len 70000 \
  --gpu-memory-utilization 0.82 \
  --max-num-seqs 8 \
  --max-num-batched-tokens 8192 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_coder \
  --served-model-name Qwen-Coder \
  --enable-prefix-caching \
  --enable-chunked-prefill \
  --kv-cache-dtype fp8

Это позволило получить примерно 70 тысяч токенов контекста. Правда, довольно быстро выяснилось, что и этого мало.

Костыль 1: восстанавливаем кеш после перезагрузки

Самое очевидное решение - использовать prefix caching. Проблема была в том, что каждое утро сервер перезагружался, а вместе с ним исчезал и весь кеш.

Поэтому появился ещё один костыль. После запуска системы сервис автоматически отправляет модели заранее подготовленный набор популярных запросов.

# -*- coding: utf-8 -*-
# /opt/openwebui/scripts/token_recache_service.py

RECACHE_PROMPT: str = load_recache_data()

client.chat.completions.create(
    model="qwen",
    messages=[
        {"role": "system", "content": RECACHE_PROMPT},
        {"role": "user", "content": "warmup"}
    ]
)

Да, по сути я просто заставляю модель заново посчитать нужные токены. Список популярных запросов собирался совместно с агентом и постепенно пополняется.

Пока такого решения хватает.

Оборачиваем всё в сервис

Дальше уже пошла привычная инфраструктурная работа. Поднял PostgreSQL вместо SQLite, настроил nginx, выписал сертификаты и максимально закрыл доступ к серверу с vLLM.

К модели может обращаться только OpenWebUI.

services:
  postgres:
    image: postgres:17
    container_name: open-webui-postgres
    restart: unless-stopped

  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    restart: unless-stopped

Это сразу решило несколько задач.

• Во-первых, никто больше не может напрямую ходить в модель.
• Во-вторых, если мне нужно провести тесты или обслуживание, я просто отключаю модель в OpenWebUI.
• В-третьих, пользоваться системой теперь могут не только разработчики через VSCode, Zed или Opencode, но и любые другие сотрудники через обычный браузер.

Костыль 2: модель тоже хочет кофе

Через некоторое время я заметил интересную закономерность. Если модель долго никто не использовал, первые несколько запросов утром выполнялись заметно хуже. Она дольше думала, чаще галлюцинировала и в целом вела себя странно. После нескольких запросов всё приходило в норму.Сначала я решил, что видеокарта просто простаивает и "остывает".

Погуглил, убедился, что подобные наблюдения встречаются не только у меня, и написал простой скрипт для минимальной нагрузки GPU.

import time
import torch

DEVICE = "cuda"

a = torch.randn((2048, 2048), device=DEVICE, dtype=torch.float16)
b = torch.randn((2048, 2048), device=DEVICE, dtype=torch.float16)

while True:
    c = torch.matmul(a, b)
    torch.cuda.synchronize()
    time.sleep(10)

Работало.

Но было ощущение, что я просто зря трачу ресурсы.

Поэтому позже заменил его на другой вариант.

Теперь раз в несколько минут отправляется бессмысленный запрос к модели:

import os
import time
import requests

URL = os.getenv("LLM_API")
TIMEOUT = 300

while True:
    try:
        requests.post(
            URL,
            json={
                "model": "qwen",
                "messages": [
                    {"role": "user", "content": "ping"}
                ],
                "max_tokens": 1,
            },
            timeout=30,
        )
    except Exception:
        pass

    time.sleep(TIMEOUT)

В результате модель никогда не простаивает слишком долго, а первые реальные запросы пользователей отрабатывают заметно стабильнее.

Финальная схема

Последним штрихом мы вместе с девопсом настроили вход через FreeIPA, выписали внутренний сертификат и добавили сервис в корпоративный DNS.

В итоге получилась такая архитектура:

Что дальше?

Сейчас система уже активно используется внутри компании и постепенно обрастает дополнительными возможностями. Следующим шагом хочу вынести проектные знания в отдельный RAG-сервис и отдельно заняться долговременным хранением и восстановлением кешей. И в ближайшее время у меня появится машинка на H200, где я буду тестировать более умные модели.

Но это уже история для следующей статьи.

Я тут попал в whitelist Delta и немного попользовался им по рабочим и не очень рабочим делам. И мне очень понравилось - это именно то, чего мне не хватало. Это не уродское консольное нечто, написанное на JS и React, не кривой обрезанный экстеншен для Zed или VS Code. Это нативное быстрое приложение, которое много что умеет прямо из коробки.

Что там есть такого, чего нет в Claude Code, Codex и OpenCode?

Во-первых, очень крутое ревью

До этого я пользовался revdiff от Umputun'а, но, объективно, это прям костыль-костыль. Открывать через tmux и терминальные оверлеи какие-то TUI-программы, которые потом при выходе просто пишут номер_строки: комментарий, - ну такое себе.

Тут же ты ходишь по коду, оставляешь комментарии и потом одним действием отправляешь их агенту. Очень похоже на то, как мы делаем ревью в GitLab или GitHub. Очень круто.

Во-вторых, контроль работы через worktree

Чуваки из Atom, а именно они пилят Zed и Delta, давно топят за работу через Git worktree, ещё со времён Atom. Мне этот подход тоже нравится. Особенно во времена агентного кодинга не очень хочется пускать агента в рабочее дерево напрямую. Гораздо удобнее создать worktree от текущего состояния проекта и пусть агент там развлекается. После ревью изменения можно перенести в основную ветку.

Вот Delta так и делает: для каждого треда создаётся отдельный worktree, в котором происходит вся работа. Это и безопасно, и удобно, особенно когда параллельно работают несколько агентов.

В-третьих, довольно узкий кейс, но...

Совместная работа.

Я могу расшарить сессию и вместе с коллегой работать над задачей в реальном времени. Мне очень нравится эта фича в самом Zed. На работе я так периодически смотрю код с коллегами, и это гораздо удобнее, чем шарить экран в созвоне и пытаться что-то показывать. А когда работа из написания кода превратилась в погоню за ИИ-агентами, логично стало шарить уже не код, а сессию: с планами, рассуждениями и тем же самым кодом, но ещё и с diff'ами от агента.

Это мало кому нужно, но лично я считаю это одной из лучших фич как в Zed, так и в Delta.

В-четвёртых, НАТИВНОСТЬ

ДА БОЖЕ ДА!

Как же я устал от всего этого зоопарка на Electron, JS и TS. Зачем? Для чего? (Иронично, что именно создатели Zed когда-то создали Electron для Atom, а теперь стараются всё делать нативно. Замаливают грехи на 100%.) Вот зачем, например, Bitwarden писать на TypeScript? И десктопное приложение, и CLI. Зачем Claude Code писать на TypeScript? Да ещё и с React?

Electron в целом стал настоящим бичом современного десктопа, поэтому то, что Delta быстрая и нативная, - огромный плюс.

А чего реально не хватает?

В первую очередь, конечно, кастомных провайдеров.

Очень хочется подключить рабочую модель со своими токенами (в первую очередь, чтобы ИБ-шники не настучали по голове) и работать через неё. Возможно, этого пока нет просто потому, что Delta всё ещё находится в закрытой бете. Но в роудмапе я не увидел ни слова про кастомных провайдеров.

Потом, конечно, работа с Git.

Сейчас предлагают переносить изменения через stash или checkout коммитов из worktree в своём терминале вне Delta. В целом я не против, но хотелось бы делать это немного удобнее. К счастью, в роудмапе это уже есть, так что, скорее всего, допилят.

Ну и переключение агентов.

Хочется сначала построить план с read-only агентом, а потом уже отправить другого агента выполнять работу. Пока такой возможности нет, но посмотрим, как будет развиваться продукт.

В какой-то момент работы я поймал себя на мысли, что воспринимаю delta не как очередной инструмент для работы с ЫЫ и даже не как "агентскую IDE". С появлением полноценных агентов в нашей работе сам процесс разработки поменялся. Если раньше редактор кода был местом, где ты в основном писал код сам, то сейчас редактор кода открывается лишь для того, чтобы прочитать код за агентом и то очень редко, дифов в самом клод-коде / кодексе часто хватает. В delta все это есть, тут можно и прочитать весь код проекта, и если надо, руками его поредактировать, оставить комментарии для робота даже вне диффов.

Именно поэтому delta ощущается не как ещё один чатик, прикрученный к редактору, а как попытка построить редактор кода следующего поколения. Здесь агент становится не дополнением к привычному процессу, а одной из основных сущностей системы наряду с кодом (или даже выше), Git и разработчиком.

Кто? Что? И зачем?

Я с Ксюшей часто хожу на митапы, конференции и IT-сходки, и там мы очень любим холиварить. Вот я и подумал: а почему бы не вынести наши холивары, интересные (и не очень) темы в формат публичный_формат.mp3?

Будем обсуждать темы, которые нам нравятся и волнуют нас. Может быть, актуальные, может быть — не очень. Какой-то закреплённой тематики не будет, потому что потому.

В пилотном выпуске поговорим про "карательную литературу": Clean Code, DDD, паттерны и всё остальное, что портит людей.

А когда?

Ээээээ... не знаю. В максимально ближайшее время. Неделя, две, три. Возможно, по законам всех IT-проектов сроки ещё будут пересмотрены. Статус по задаче актуализирую, туда сюда

Где?

На популярных площадках для подкастов: Spotify, Apple Podcasts, Яндекс Музыка, YouTube, Pocket Casts и так далее. Если всё пойдёт по плану - там и появимся. Если не по плану - тоже появимся, просто позже.

Jam — это чисто проект для души, я делаю его в первую очередь для себя. Поэтому многие решения принимаются просто потому что мне так хочется.

Мне не нравится, как сейчас устроен главный инстанс jam.*.Jam. Сейчас это, по сути, ненужная надстройка над основными модулями. Например, PASETO можно сгенерировать двумя способами:

# через инстанс
from jam import Jam

config = {
    "paseto": {
        "version": "v4",
        "purpose": "local",
        "secret_key": "SOME_SECRET"
    }
}

jam = Jam(config=config)
paseto = jam.paseto_create(payload={"some": "body"})

# ---
# и через модуль
from jam.paseto import PASETOv4

paseto = PASETOv4.key(
    purpose="local",
    secret_key="SOME_SECRET"
).encode(payload={"some": "body"})

И мне это не нравится. Сейчас нет ни одной реальной причины использовать инстанс, кроме удобного описания конфига в YAML (или любом другом формате).

Поэтому я думаю добавить в каждый инстанс (в __init__) два новых аргумента: config: str | dict | None и pointer: str | None — то есть примерно как в jam.*.Jam. Тогда можно будет делать что-то вроде:

class JWT(BaseJWT):
    def __init__(
        self,
        config: str | dict[str, Any],
        pointer: str = "jam",
        *,
        alg: str | None = None,
        enc: str | None = None,
        secret_key: str | bytes | KeyLike | "JWK" | None = None,
        password: str | bytes | None = None,
        list: dict[str, Any] | None = None,
        serializer: BaseEncoder | type[BaseEncoder] = JsonEncoder,
        logger: BaseLogger = logger,
        jws: JWS | None = None,
        jwe: JWE | None = None,
    ) -> None: ...

То есть можно будет передавать как конфиг, так и отдельные параметры — кому как удобнее, и не дергать jam.*.Jam.

Ну а что делать с jam.*.Jam?

Полностью вырезать класс я точно не буду, но сама концепция сильно изменится.

Пока не могу точно сказать, каким он станет в итоге, но хочу сделать механизм для описания Subject'а (пользователя или любого другого объекта) и его авторизации.

Скорее всего, это будет выглядеть примерно так:

from jam import Jam, BaseSubject

# всё ниже чисто набросок по наитию, по вайбу
class User(BaseSubject):
    id: UUID
    email: str

class MyAuthorization(Jam):
    subject = User
    config = "config.toml"

# ---
# а тут уже начинается магия

auth = MyAuthorization()

user = User(id=uuid4(), email="someuser@mail.com")

auth.authorize(subject=user)

Наверное, что-то в таком духе. Пока всё это только обдумываю и проверяю разные идеи.

Сейчас я делаю для Jam механизмы SAML и не буду встраивать их в jam.*.Jam. SAML с самого начала будет существовать только как отдельный модуль.

Что нового

Полный JOSE-стек (RFC 7515–7519)

Добавлен модуль jam.jose с четырьмя компонентами:

• JWS — JSON Web Signature (RFC 7515), подпись данных с валидацией критических заголовков (crit)
• JWE — JSON Web Encryption (RFC 7516), шифрование с автоопределением алгоритма управления ключами (RSA -> RSA-OAEP, EC -> ECDH-ES, симметричные -> A256KW/A128KW)
• JWK / JWKSet — JSON Web Key (RFC 7517), работа с ключами
• JWT — JSON Web Token (RFC 7519), теперь через JOSE

Вложенный JWT (sign-then-encrypt) теперь работает по RFC 7519 с HKDF-выведением ключей.

Новые параметры jwt_decode в инстанс

• check_nbf — валидация nbf (not-before) claim
• include_headers — возврат заголовков вместе с payload

Безопасность

Алгоритм none теперь явно отключён. Тут решил нарушить спеку и жестко запретить, меньшее из зол.

GitHub Release | jam.makridenko.ru

Это текстовая версия моего доклада на Moscow Python №110

В веб-разработке широко распространена аутентификация на основе токенов. Наибольшей популярностью пользуются JWT - компактные токены, несущие закодированные JSON-декларации (claims), защищённые подписью и(или) шифрованием. JWT входят в семейство стандартов JOSE (JSON Object Signing and Encryption), которое включает механизмы JWS (подпись), JWE (шифрование), JWK (формат ключей), JWA (алгоритмы) и собственно JWT (токены).

Несмотря на это, JWT часто применяют неправильно. Многие разработчики вставляют их в любое приложение, стремясь к stateless-аутентификации(а на деле просто не зная что брать). Однако JWT не являются универсальным решением для всех задач авторизации. В данном докладе разберём JWT/JOSE и их недостатки, а затем посмотрим PASETO - более безопасную альтернативу с жёстким набором алгоритмов.

Что такое JWT и JOSE

JWT (JSON Web Token) - это компактный URL-безопасный токен, предназначенный для передачи набора утверждений (claims) между сторонами. Токен состоит из трёх частей (заголовок, тело, подпись), каждая кодируется base64url и разделяется точками. Заголовок содержит параметры подписи (алгоритм, тип), тело - JSON-объект с утверждениями (например, sub, iat, exp и др.), а третий фрагмент - подпись (или пустая строка для несекурного режима). JWT стандартизован в RFC 7519.

JOSE (JSON Object Signing and Encryption) - это совокупность стандартов IETF для криптографической защиты JSON-данных. JOSE включает: JWS - формат подписанных сообщений, JWE - шифрованных, JWK – описание ключей, JWA - набор криптоалгоритмов, а JWT как раз описывает формат токена, который можно обернуть в JWS или JWE. Иными словами, JWT - это лишь часть семейства JOSE, предназначенная для передачи «квитанций» (claims) между сервисами.

В норме JWT используется так: сервер аутентификации выпускает JWT и подписывает его своим секретным ключом (HS256/HMAC или RS256/RSA), клиент сохраняет этот токен и на каждый запрос к ресурсу отправляет его (например, в HTTP-заголовке). Сторона-приёмник проверяет подпись и срок жизни токена.

Однако уже на этом уровне скрываются некоторые «ловушки»: избыточная гибкость, необязательность проверки и тд., что и приводит к частым ошибкам.

В чем проблема JWT

JWT сами по себе не небезопасны – проблема в том, что спецификация JOSE даёт широкие возможности, которые легко неправильно использовать. Ключевые недостатки и уязвимости:

• Алгоритм none. Спецификация позволяет задать "alg":"none", означающий отсутствие подписи. Известная уязвимость: если сервер НЕ проверяет этот параметр или библиотека некорректно обрабатывает такой токен, злоумышленник может просто указать "alg":"none" и модифицировать содержимое без подписи. Многие ранние реализации принимали такие токены как валидные. Несмотря на фиксы в обновлённых библиотеках, уязвимость всё ещё встречается в устаревшем ПО.

• Конфуз алгоритмов (key confusion). JWT поддерживает как симметричные (HS256) так и асимметричные алгоритмы (RS256, ES256). Некоторые библиотеки при верификации опираются на поле alg из токена и на переданный ключ без жёсткой проверки типа. Вследствие этого случается атака: если сервис ожидал, что alg=RS256, но он явно передаёт в функцию верификации RSA-ключ, то злоумышленник может выдать токен с alg=HS256 и подписать его тем же открытым ключом (используя его как HMAC-секрет). Сервер же проверяет HMAC с этим секретом (который на самом деле открытый ключ) и принимает такой поддельный токен. В результате злоумышленник может подделать права в токене без знания приватного ключа. Эта атака на совмещение ключей (algorithm confusion) хорошо описана в исследованиях по безопасности JWT.

• Неправильная верификация. Самая грубая ошибка - просто не проверять подпись. Например, в JavaScript-библиотеке Node.js функция jwt.decode() только раскодирует тело, но не проверяет подпись. В документации OWASP отмечается, что если использовать decode вместо verify, можно читать данные токена без проверки подписи - это прямая уязвимость.

• Сложность и «дырки» в использовании. Спецификация JOSE большая и многослойная. Например, JWT поддерживает необязательные поля kid, jku (идентификатор или URL ключа) - их неверная обработка позволяет проводить атаки типа подмены ключей. Детали формата JWE (шифрование) сложны и редко корректно применяются - часто JSON Web Encryption вообще игнорируют. Массив возможностей приводит к тому, что разработчики могут невольно допустить уязвимость.

• Перенаправление токенов и отзыв. JWT изначально спроектированы как самодостаточные токены (stateless). Это означает, что верификация обычно сводится к проверке подписи и сроков. Если надо отозвать токен досрочно, приходится вводить дополнительные механизмы (чёрные списки), иначе токен жил до конца срока. Такой способ управления сеансом далеко не всегда подходит. JWT - это заявленные утверждения (claims) о субъекте. Если приложение хранит состояние в JWT, возникают сложности с отзывом прав, разлогином и т.п. Например, JWT часто применяют как сессии без остановки - нечего логицировать, токен валиден до exp и всё.

Подводя итог: гибкость JWT даёт много возможностей, но без строгого контроля легко наломать дров. Много стандартных библиотек JWT позволяли простые обходы аутентификации (вставка alg: none, игнорирование подписи, конфуз алгоритмов). Более того, по данным анализа, разработчики часто применяют JWT без особой надобности - просто из-за популярности и штампов.

Как и где JWT используют неправильно

Типичные паттерны неправильного применения JWT:

• JWT как сессионный токен. Многие воспринимают JWT как замену обычной серверной сессии. Однако JWT статичны: сам токен содержит все данные и верифицируется только локально по подписи. Если после выдачи токена администратор изменил права пользователя, JWT сам об этом не узнает. Это ведёт к неотзываемым сессиям, невозможности реализовать logout и тд.

• Хранение секретов в payload. Поскольку тело JWT обычно не шифруется (если использовать JWS), туда нередко кладут лишние данные. Разработчики могут запихать личные сведения или внутреннюю логику приложения в поля токена, считая его «закрытым». Но payload JWT открыт любому, у кого есть токен. Обнаружение секретных полей в чётко читаемом JSON - классика.

• Использование небезопасных алгоритмов. Иногда в качестве быстрых решений применяют устаревшие алгоритмы или слабые ключи. Например, использование HS256 с коротким симметричным ключом вообще не обеспечивает должную защиту. Если JWT подписан по HMAC, то секретный ключ должен быть достаточно длинным и случайным. В противном случае его можно подобрать. Или берутся неподходящие ключи RSA (RSA PKCS#1v1.5), которые считаются менее безопасными. Разработчик может просто указать любой алгоритм - спецификация не мешает. Всё это увеличивает риск взлома токена.

• Неправильная обработка ошибок. Если сервер по какой-то причине не может проверить подпись (например, нет ключа для верификации), встречается практика «просто пропустить» такую ошибку и вернуть payload. Это катастрофа: любой кривой токен принимается. Версия OWASP подчёркивает важность запрета любых JWT, для которых не прошла верификация подписи.

• Отправка JWT не по HTTPS. Несмотря на общие рекомендации, практикуется отправка токена в незащищённом канале (например, убрав HTTPS). Тогда подпись токена хоть и проверяется, но токен можно перехватить. Сразу же доказано неэффективность любого криптоалгоритма, если токен протаскивается по незащищённой сети.

• Необоснованная многословность. Некоторые компоненты умудряются поддерживать JWE (шифрование), JWS (подпись), JWK (ключи) и прочее. Разработчик путается, включает в конфиг всё подряд. На практике часто достаточно либо только подписи, либо только шифрования, но не нужно одновременно клеить всё. Слишком сложная схема - это повышенный риск ошибки.

В общем, наиболее частая ошибка - выбор JWT по причине: "НУ А ЧТО ЕСЛИ НЕ ДЖЕ ВЕ ТЕ?!", без анализа требований безопасности. Часто проще было бы завести на сервере сессионное хранилище или выпустить короткоживущий токен, чем пихать JWT и бороться с его сложностями.

Неочевидные проблемы JWT

Кроме перечисленных базовых уязвимостей, существуют и менее очевидные подводные камни:

• Шаблоны использования. JWT не предусматривает обновления (refresh) без выдачи нового токена, поскольку истечение (exp) встроено внутрь токена. Это затрудняет ротацию ключей или выдачу нового токена без потери сессии. То есть вы либо доверяете старому токену до конца срока, либо вынуждены выдавать новый, отслеживать, какие старые ещё валидны.

• Невалидные претензии (claims). JWT определяет набор зарезервированных полей (iss, sub, aud, exp и др.), но они не обязательны. Разработчики иногда по умолчанию полагаются только на exp, забывая проверять iss (издатель) и aud (аудитория), что позволяет смешивать токены из разных систем. Например, сервер может не проверять, что iss – это именно его издатель, и принять чужой JWT.

• Ключевой менеджмент. В JWT/JOSE ключи описываются через JWK (JSON Web Key) - громоздкая JSON-структура. Код, получающий токен, должен найти нужный ключ (по kid или URL), загрузить его и распарсить. Ошибки в этих шагах привели к атакам (например, jku - URL, откуда взять ключ), когда клиент мог указать свою jku. Сложная схема управления ключами - ещё одна точка отказа/атаки.

// пример EC P256 ключа в формате JWK
{
  "kty": "EC",
  "kid": "ec1",
  "use": "sig",
  "crv": "P-256",
  "alg": "ES256",
  "x": "f83OJ3D2xF4... (base64url координата x)",
  "y": "x_FEzRu9G6... (base64url координата y)"
}

• Размер токена. JWT часто хранятся в HTTP-заголовках или куки. Поскольку кодирование base64увеличивает размер, а payload обычно JSON-текст, токены могут быть довольно большими (сотни байт). Это снижает пропускную способность и может вызвать проблемы (например, превышение размера HTTP-заголовков или куки).

• Многофункциональность. JWT по стандарту может и шифроваться (JWE), и подписываться (JWS). Если начать комбинировать (подписать, затем зашифровать), то обратная сторона должна это поддерживать. На практике разработчики часто просто подписывают JWT, но формально спецификация разрешает и иные сценарии. Многозадачность системы увеличивает поверхность атаки - чем больше опций, тем больше багов.

Таким образом, даже неявные атрибуты JWT (алгоритмы, header-поля, зависимости от контекста) создают риск. Как отмечено в анализе PASETO, многие проблемы JWT связаны с избыточной гибкостью: разработчик выбирает алгоритмы и форматы и может ошибиться.

Что такое PASETO

PASETO (Platform-Agnostic SEcurity TOkens) – это предложенный Paragon Initiative стандарт токенов безопасности. Главная идея: предоставить токенную замену JWT, в которой из коробки используются только безопасные, современные алгоритмы, а разработчик лишён возможности выбрать бессмысленные варианты.

В PASETO токен имеет формат v{version}.{purpose}.{body}.{footer?}, где нет отдельного поля alg. Вместо этого:

• version (v1, v2, v3, v4) определяет криптографический протокол и алгоритмы (AES/GCM в v1–v2, XChaCha20-Poly1305 в v2–v4, EdDSA/ECDSA в v3–v4 и т.д.).
• purpose – режим: local (шифрование с симметричным ключом) или public (подпись с публичным ключом).

Например, токен v4.public. означает PASETO версии 4, режим публичной подписи (Ed25519). В этом случае тело токена подписывается приватным ED25519, а любой с соответствующим публичным ключом может проверить подпись. Если local, то токен шифруется симметричным ключом XChaCha20-Poly1305. Фактически PASETO предоставляет два варианта: шифрование (конфиденциальность) или подпись (целостность), как JWE/JWS, но с жёстко предопределёнными алгоритмами.

Ключевые отличия PASETO от JWT:

• Безопасность по умолчанию: Нельзя выбрать несесурный алгоритм. None-атака была забытым нейтральным вариантом в JWT; в PASETO её просто нет.
• Versioned Protocols: В JWT есть "алгоритмическая гибкость" (можно свободно переключаться между HS256, RS256, HS512 и пр.), что порождает ошибки. PASETO вместо этого задаёт версии, где каждому набору алгоритмов соответствует своя версия. Это исключает двусмысленность.
• Простота: PASETO убирает все нестандартные расширения JOSE. Нет kid/jku/jwk, нет разных типов контента – только JSON-поледательность и подпись/шифрование. Спецификация просто чище.
• Прозрачность: Структура токена очевидна по префиксу (v2/local или v4/public), не требуется дополнительная информация о ключах.

Важно понимать: ни JWT, ни PASETO не сами по себе не решают проблему без состояний. PASETO также не предусматривает механизмов предотвращения replay-атак – для этого всё равно нужны серверные слежения. Однако по безопасности PASETO зарекомендовал себя как способ не дать разработчику прострелить ногу. В спецификации PASETO прямо сказано, что задачи stateless-сессий лежат вне его ответственности; он просто гарантирует криптостойкость при передаче данных.

Как устроен PASETO (с примерами, jam.paseto)

Рассмотрим внутренности PASETO на примере версий v2 (XChaCha20+Ed25519, устаревшая) и v4 (libsodium-актуальные алгоритмы) на примере моей библиотеки Jam.

там кстати не только PASETO, там и JWT, и OTP, и серверные сессии, и OAuth2. Приходите ставьте звездочку все дела :)

from jam.paseto.v4 import PASETOv4
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
import secrets

# Симметрический режим (local)
# Генерируем 32-байтовый секрет
secret_key = secrets.token_bytes(32)
# Создаём PASETO-инстанс для шифрования (v4.local)
paseto_local = PASETOv4.key("local", secret_key)

# Кодируем токен с JSON-платёжкой и необязательным футером (footer)
token_local = paseto_local.encode(
    {"user": "meowl", "exp": "2030-01-01T00:00:00+00:00"},
    footer="service-identifier"
)
print("PASETO local:", token_local)

# Раскодируем и проверим токен
payload, footer = paseto_local.decode(token_local)
print("Payload:", payload)   # {'user': 'meowl', 'exp': '2030-01-01T00:00:00+00:00'}
print("Footer:", footer)     # 'service-identifier'

# Асимметрический режим (public)
# Генерируем ED25519-ключи
private_key = Ed25519PrivateKey.generate()
public_paseto = PASETOv4.key("public", private_key)

token_public = public_paseto.encode(
    {"user": "mewfish", "exp": "2030-01-01T00:00:00+00:00"}
)
print("PASETO public:", token_public)

payload_pub, _ = public_paseto.decode(token_public)
print("Payload:", payload_pub)  # {'user': 'mewfish', 'exp': '2030-01-01T00:00:00+00:00'}

В symmetic (local) режиме jam.paseto выполняет следующее (см. исходный код):

• Формирует ASCII-заголовок вида v4.local. (серийная строка версии и «назначения»).
• Генерирует 24-байтовый случайный nonce (четвёртая часть шифрования XChaCha20-Poly1305).
• Собирает AAD (additional authenticated data) как PAE([header, footer]) – специальная функция, объединяющая header и footer.
• Вызывает xchacha20poly1305_encrypt(secret, nonce, payload, aad), получая шифротекст. Затем токен = header + base64url(nonce+ciphertext). Если есть footer, он также кодируется base64 и добавляется через точку.
• При верификации происходит обратное: разбираются части, проверяется заголовок, расшифровывается с тем же secret и AAD. В случае повреждения или подделки недекодированный ciphertext приведёт к ошибке.

В asymmetric (public) режиме применяется Ed25519-подпись:

• Заголовок v4.public. конкатенируется с сериализованным JSON-пayload.
• Формируется pre_auth = PAE([header, payload, footer]).
• Приватный ключ Ed25519 подписывает pre_auth, получая подпись (64 байта).
• Токен = header + base64url(payload+signature) [+ опциональный .footer].
• При декодировании библиотека проверяет подпись публичным ключом Ed25519: public_key.verify(signature, pre_auth). Если проверка не проходит, бросается исключение о недопустимом токене.

Таким образом, PASETO устраняет два класса ошибок JWT: во‑первых, здесь нет флажка типа алгоритма в токене (всё определяется версией), а, во‑вторых, используются проверенные схемы AEAD (шифрование+аутентификация) и EdDSA, минимизирующие опасность криптографических заплат. Особенно важно, что злоумышленник не может просто указать свой алгоритм: либо у него есть секретный ключ (local) - тогда он может расшифровать и подпись, но не подделать защищённые биты, либо у него есть только публичный ключ (public) - он никак не сможет создать корректную подпись.

Код jam.paseto ясно иллюстрирует эти механизмы. Например, при шифровании используется xchacha20poly1305_encrypt со 192-битным nonce, а при верификации Ed25519 фиксирует каждую часть: PASETOv4.decode() проверит префикс v4.public., длину подписи 64 байта и вызовет verify на публичном ключе. Эти жёсткие проверки делают PASETO устойчивым к классическим JWT-атакующим паттернам.

Чем PASETO лучше JWT

Безопасность. В PASETO встроено использование только современных шифров и подписей: TLS-сервером заявлено, что PASETO мало вероятно использовать в небезопасном вид. Отсутствует alg:none и двусмысленность алгоритмов. В PASETOv4 для шифрования по умолчанию применяется XChaCha20-Poly1305 (AEAD-режим), а для подписи – Ed25519 (EdDSA), которые считаются стойкими. JWT, напротив, всё ещё допускает множество вариантов алгоритмов (HS*, RS*, PS*, ES*) и требует от разработчика самому грамотно их выбирать - что часто идёт не так.

Простота и надёжность. PASETO логически проще: только два режима (шифрование или подпись) и версии. JWT имеет JWS/JWE/JWK и тд - это делает его мощным, но и опасным. PASETO даже рекомендует: Лучше использовать PASETO правильно, чем дать свободу на выбор алгоритмов. Например, в PASETO нет полей jku или kid, поэтому атаки типа подмены ключей исключены априори.

Агностицизм к алгоритму. В JWT разработчик указывает "alg", и если у него избыточные права, он может допустить слабый вариант (например, ввести HMAC вместо RSA). В PASETO версия фиксирует алгоритм, и его нельзя поменять внутри токена. Этот принцип версионности (versioned protocols) описывается как контраст гибкости алгоритмов JWT - версионированные протоколы PASETO.

Размер токена. PASETO-токены обычно получаются немного короче JWT-аналогов той же нагрузки, потому что структура проще и нет JSON-сериализованного заголовка (вместо него короткий ascii-префикс v2.local. и т.д.). Меньший размер полезен при передаче в заголовках или куках.

Поддержка футеров. В PASETO можно использовать footer - доп. данные, не защищённые крипто-операциями (например, ID ключа или версия приложения). В jam.paseto footer передаётся явно при encode и обрабатывается (он подписывается вместе с payload). JWT имеет поле kid и другие расширения, но они менее стандартизированы и сложнее управляются.

Экосистема. JWT поддерживается практически всеми фреймворками и библиотеками (OpenID Connect, OAuth2, готовые клиенты и т.п.). PASETO еще молодой стандарт, но постепенно набирает популярность - есть реализации на многих языках. Для Python, конечно же Jam, плюс есть paseto и pyseto, но с ними надо быть аккуратно, они не строго следуют спецификации!

Ниже приведена сравнительная таблица основных характеристик JWT и PASETO:

Как видно из таблицы, PASETO жертвует некоторой гибкостью JWT ради безопасности и простоты. При этом он устраняет большинство описанных проблем JWT по умолчанию, но от сюда следует вот такая картина:

Мы видим, что в JWT из коробки больше паттернов для атаки, в PASETO мы всегда упираемся в подпись.

JWT – зрелый стандарт для веб-токенов, но с большой долей ответственности разработчика: он сам выбирает алгоритмы и опции, поэтому под неправильной рукой JWT легко превратить в большую дырку. Оценка рисков показывает: JWT легко использовать неверно – от alg:none до "просто decode" вместо verify - что может полностью скомпрометировать безопасность системы. К тому же JWT зачастую применяют там, где достаточно простого механизма аутентификации, усложняя архитектуру без выгоды.

PASETO предлагает более безопасный подход: чёткие версии, только современные алгоритмы, минимум конфигурации. Использование PASETO позволяет избежать типичных проблем: невозможно написать alg:none, библиотека сама корректно шифрует/подписывает и проверяет токен.

В итоге рекомендация для разработчиков: критически оценивать необходимость JWT. Если нужен простейший маркер авторизации, может быть достаточно короткого HMAC-токена или сессии с хранением на сервере. Если же требуется самодостаточный токен, стоит отдавать предпочтение PASETO или строго контролировать использование JWT (фиксировать алгоритмы, периодически ротировать ключи, проверять все поля).

Материал:

• спецификации JWT/JOSE
• анализ уязвимостей JWT (OWASP, PortSwigger) и PASETO
• Документация Jam: jam.makridenko.ru

Ну и: презентация

Это текстовая версия моего доклада для студентов ММА.

Языки с управляемой памятью (такие как Python) используют сборщик мусора (GC) для автоматического освобождения неиспользуемых объектов и предотвращения утечек памяти. Задачи GC – находить и освобождать память, не достижимую из «корней» (roots) программы, тем самым перераспределяя её для новых объектов. Несмотря на это, сборщики накладывают ограничения: они увеличивают накладные расходы (время и память), могут вызывать паузы исполнения и не гарантируют немедленного освобождения памяти (например, в случае циклических ссылок). Общая цель доклада – дать представление о необходимости GC: он делает программы надёжнее (нет забытых free), но требует понимания компромиссов между пропускной способностью и задержкой.

Ключевые задачи GC: вернуть память неиспользуемых объектов системе, минимизировать фрагментацию и издержки в производительности. Ограничения: паузы (stop-the-world), сложности с циклами, накладные расходы на хранение метаданных. В результате, GC – это баланс между надёжным управлением памятью и контролем производительности приложения.

Основные концепции GC на уровне памяти

Управление памятью: В процессе работы программа использует несколько сегментов памяти: статический (код и глобальные данные), кучу (динамические объекты) и стек (фреймы функций, локальные переменные). Сборщик мусора управляет только кучей – памятью, выделенной динамически. Память стека освобождается автоматически при выходе из функции; статические объекты и глобальные переменные живут в течении всего выполнения.

Корни (roots) и достижимость: «Корнем» называют объект, до которого виртуальная машина может добраться напрямую (без прохода через другие объекты). В качестве корней выступают, например, локальные переменные на стеке, глобальные объекты, содержимое регистров и стека выполнения. Объект называется достижимым, если от корня к нему ведёт цепочка ссылок. Невозможно достижимые объекты расцениваются как «мусор» и подлежат сбору. Таким образом, сборщик начинает с корней и помечает все объекты, до которых можно добраться, а затем удаляет все непромеченные.

Объекты и указатели: В управляемых языках объекты (все экземпляры) хранятся в куче, а переменные и поля объектов представляют собой указатели (ссылки) на эти объекты. Например, если объект A содержит ссылку на объект B, то в «графе объектов» есть ребро A → B. При выполнении сборки мусора строится ориентированный граф из всех объектов и отслеживаются ссылки.

Области видимости и граф объектов: Переменные, доступные из активного кода (локальные, глобальные, статику), являются корнями, а вся совокупность объектов и их ссылок образует граф.

В этом примере из корня доступны Obj1, Obj2, Obj3 (они достижимы). Любой объект вне такой цепочки (непомеченный) считается мусором. Достижимость определяется индукцией: корни достижимы по определению, а любой объект, на который указывает достижимый, тоже достижим.

Таким образом, сборщик мусора реализует обход объекта (обычно метка‑освобождение) от корней и освобождает всё, что не достигнуто. Этот основной принцип лежит в основе большинства алгоритмов GC.

Типы сборщиков

Существует несколько подходов к сборке мусора. Ниже приведена таблица ключевых типов GC с их принципом работы, плюсами, минусами и типичными сценариями применения:

Краткий вывод: Reference counting прост и оперативен, но не справляется с циклами. Метод «метка–сбор» надёжный и не требует доп. памяти, но может вызывать фрагментацию и паузы. Копирующие и поколенческие GC уменьшают паузы и фрагментацию за счёт перераспределения памяти и частичных сборок. Консервативные сборщики применимы в системах без информации о корнях (C/C++). В Python главным образом используется сочетание подсчёта ссылок (точный GC) и поколенческого алгоритма для циклов.

Алгоритмы и схемы

Ниже приведены алгоритмы основных схем GC с шагами их работы, схемами и оценками сложности.

Алгоритм «метка–сбор» (Mark–Sweep)

1. Метка (Mark): начинаем с корней, рекурсивно помечаем все достижимые объекты.
2. Сбор (Sweep): проходим по всей куче и освобождаем (удаляем) все объекты, не помеченные как достижимые.

Пример: Пусть корень ссылается на A, которое ссылается на B, и B на C, а объекты D и E изолированы. После метки A, B, C пометятся, а D и E будут собраны.

Сложность: Время – O(N) (сканирование всей кучи дважды: пометка и сбор). Память – минимальные накладные (обычно всего несколько бит для маркировки).

Алгоритм компакции (Mark–Compact)

Это вариация Mark–Sweep. После пометки живых объектов вместо удаления формируются компактные «уплотнённые» области:

1. Метка: как выше.
2. Компактирование: все помеченные объекты копируются в начало кучи (сохраняя относительный порядок), непромеченные объекты «сдвигаются» и вся свободная область становится непрерывной.

Сложность: Время – обычно больше, чем у простого Mark–Sweep (требуется перемещение, поиск новых адресов для указателей). Область памяти – дополнительная метка, но сама алгоритм не требует двойного пространства (в отличие от копирования).

Копирующий сборщик (Copying Collector)

Куча делится пополам на два полупространства. Алгоритм:

1. Пометка и копирование: из исходного полупространства (from-space) все достижимые объекты копируются в свободное полупространство (to-space). При этом удаляются объекты, не скопированные.
2. Перемещение: после копирования полупространства меняются ролями (now to-space становится активной кучей).

Сложность: Время пропорционально количеству живых объектов (если их мало, быстро). Недостаток – требуется дополнительное пространство (~двойной объём кучи) для второго полупространства. После копирования куча не фрагментируется.

Поколенческий сборщик (Generational GC)

Поколенческий GC объединяет «метка–сбор» с разделением кучи на поколения по возрасту объектов. Обычно реализуется так:

• Инициализация: объекты сначала попадают в молодое поколение. Когда выполняется сборка, проверяются только объекты в молодом поколении (minor GC).
• Продвижение: объекты, пережившие несколько сборок, переносятся в старшее поколение.
• Сбор старших: старшее поколение собирается реже (major GC) и часто вместе со всеми младшими.

Сложность: Ускоряет GC: большинству объектов не нужна частая проверка. Сбор малого поколения быстрый (обычно O(M) для небольшого M). Недостаток – сложная реализация (нужно отслеживать ссылки из старого в молодой, «барьеры записи»). CPython, начиная с версии 3.14, использует два поколения (молодое и старое). Молодое поколение собирается чаще, старшее – постепенно (обычно 1% при пороге по умолчанию).

Структура объекта в памяти

В управляемых языках объекты имеют заголовок с метаданными. В CPython (управляемой памятью) каждый объект на низком уровне представлен структурой C:

• ob_refcnt: счётчик ссылок на объект (тип Py_ssize_t), который увеличивается/уменьшается при присваивании/удалении ссылок.
• ob_type: указатель на дескриптор типа (структуру PyTypeObject), содержащую информацию о классе объекта.
• (для переменной длины) ob_size: если объект имеет переменный размер (например, списки), здесь хранится длина.

В официальной документации отмечено: «в обычной сборке релиза [PyObject] содержит только счётчик ссылок и указатель на соответствующий объект типа». Пример псевдокода C-структуры:

typedef struct {
    Py_ssize_t ob_refcnt;       // Счётчик ссылок
    PyTypeObject *ob_type;      // Указатель на тип объекта
    // ... далее поля объекта ...
} PyObject;

typedef struct {
    PyObject ob_base;           // базовая часть PyObject
    Py_ssize_t ob_size;         // размер для объектов переменной длины
    // ... далее поля списка или другого контейнера ...
} PyVarObject;

В урезанной реализации CPython (если объект учтён GC) перед этими полями выделяется скрытый заголовок PyGC_Head, который содержит указатели _gc_next и _gc_prev для двусвязного списка контейнеров GC. Этот заголовок позволяет генерационному GC отслеживать все объекты типа «контейнер» (например, списки, словари) в своих списках по поколениям.

Выравнивание адресов в CPython обычно соответствует размеру машинного слова (8 байт на 64-бит), поэтому сами поля выровнены. В итоге, указатель на объект (PyObject *) фактически указывает на начало этой структуры (включая ob_refcnt). Метаданные (тип объекта) в статической памяти содержат таблицы методов и размеры полей.

Таким образом, сборщик мусора знает, где находится счётчик ob_refcnt (он в начале объекта) и где тип, что позволяет ему корректно управлять ссылками и освобождать объект, когда счётчик падает до 0. Обратите внимание: поскольку объекты не перемещаются (их адрес не меняется после аллокации), ссылкой на объект выступает просто указатель PyObject*.

GC в CPython

CPython использует гибридную схему: базовый механизм – подсчёт ссылок, дополняющийся поколенческой сборкой циклов.

• Подсчёт ссылок: Каждый объект хранит поле ob_refcnt. Операции Py_INCREF/Py_DECREF автоматически выполняются при манипуляции ссылками. Когда ob_refcnt объекта достигает 0, CPython немедленно освобождает память этого объекта (вызывает деструктор и возвращает блок памяти). Это происходит во время исполнения программы, без дополнительных пауз.

• Генерационная сборка: Для обнаружения циклов CPython использует опциональный GC на основе поколения. Существуют связанные списки всех контейнерных объектов по поколениям (в CPython 3.14 их два – молодое и старое). Все новые объекты помещаются в молодое поколение. Периодически (по счётчику операций аллокации) выполняется сборка поколения 0 (малого); при этом объекты, пережившие несколько сборок, продвигаются в старшее поколение. При вызове gc.collect() без аргументов или с generation=2 выполняется полный сбор (молодое + старое), а с generation=0 – только молодого. Для сборки циклов CPython использует метод три-цветной маркировки, реализованный с сохранением копии счётчиков: сначала копируется ob_refcnt каждого проверяемого объекта в специальное поле GC-заголовка, затем уменьшаются внутренние ссылки внутри поколения (фазы subtract_refs), и те объекты, у которых скопированный счётчик стал ≤0, считаются недостижимыми и удаляются.

Диаграмма простого цикла в CPython:

Циклическая ссылка: оба объекта взаимно достижимы между собой, но после удаления всех внешних ссылок их счётчики не станут 0. Генерационный GC обнаружит такую группу.

В CPython 3.12 сборка циклов происходила при выполнении определённого числа операций аллокации. Начиная с CPython 3.12, механизм запуска GC изменён: теперь GC срабатывает не при каждой аллокации, а на каждые брейкер-флаги байткода (каждый шаг цикла eval-loop), а также при проверке сигналов PyErr_CheckSignals в длинноработающих C-расширениях. Это даёт более равномерные точки запуска GC и уменьшает влияние сборщика на производительность.

Примеры в CPython

Ниже показаны примеры на Python 3.12+ с комментариями, демонстрирующие подсчёт ссылок и GC циклов.

class A:
    def __init__(self, name):
        self.name = name
    def __del__(self):
        print(f"Deleted {self.name}")

print("=== Reference Counting ===")
a = A("a1")
print("Объект a создан")
del a
print("Удалили a, __del__ должен был сработать сразу")

Ожидаемый вывод:

=== Reference Counting ===
Объект a создан
Deleted a1
Удалили a, __del__ должен был сработать сразу

Объект a1 создаётся и у него ob_refcnt=1. После del a счётчик становится 0, и CPython сразу вызывает a.__del__(), выводя Deleted a1. Это демонстрирует детерминированное освобождение при подсчёте ссылок.

print("\n=== Циклическая ссылка без финализатора ===")
a = A("A")
b = A("B")
a.other = b
b.other = a
del a, b
print("Ссылки a и b удалены, вызываем сборку")
import gc
gc.collect()
print("GC завершён")

Ожидаемый вывод (Python 3.4+):

=== Циклическая ссылка без финализатора ===
Ссылки a и b удалены, вызываем сборку
Deleted A
Deleted B
GC завершён

Здесь мы создаём цикл A↔B. После del a, b внешних ссылок нет, но без GC у классов с __del__ цикл раньше не собирался. Начиная с Python 3.4 (PEP 442), CPython всё же собирает такие объекты и вызывает их __del__. Поэтому после gc.collect() оба объекта освобождаются и печатают свои сообщения. Если бы __del__ отсутствовал, объекты просто удалились бы без вывода.

print("\n=== Цикл со слабой ссылкой ===")
import weakref
class B:
    def __init__(self, name):
        self.name = name
    def __repr__(self):
        return f"<B {self.name}>"

e = B("e")
f = B("f")
e.f = f
f.e = e
wr = weakref.ref(e, lambda x: print(f"{x} collected"))
del e, f
print("После del e,f создаём цикл, weakref ждёт сборки")
gc.collect()
print("GC завершён, weakref вернул:", wr())

Ожидаемый вывод:

=== Цикл со слабой ссылкой ===
После del e,f создаём цикл, weakref ждёт сборки
<B e> collected
GC завершён, weakref вернул: None

Здесь создаётся цикл между e и f. Мы сохраняем слабую ссылку wr на объект e с колбэком, чтобы увидеть момент сбора. После del и gc.collect() цикл будет удалён, weakref вызовет колбэк (<B e> collected) и вернётся None. Это показывает, как weakref помогает обнаруживать освобождение объектов, избегая собственно цикла в Python-объектах.

Таким образом, на практике GC в CPython комбинирует немедленное удаление при refcount=0 и фоновый сбор циклов. При работе с ресурсами важно помнить о возможных циклах: либо избегать их, либо использовать weakref/gc модуль для контроля.

История и изменения в CPython 3.12→3.13→3.14

• Python 3.12: Сборщик циклов переведён на новый механизм запуска. Вместо проверки после каждой аллокации, GC теперь срабатывает на каждом байткод-брейкере (каждый шаг eval loop) и при проверке сигналов. Это сглаживает накладные расходы и устраняет «горячие точки» сборки, заметно снижая задержки в некоторых сценариях.

• Python 3.13: На предварительных релизах (3.13.0rc1) была введена экспериментальная инкрементальная сборка GC – сборщик разделял работу на небольшие части, чтобы ещё больше сократить паузы. Однако перед финальным релизом 3.13 эта инкрементальность была откочена из-за регрессий производительности (замедление Sphinx). Иными словами, в 3.13 изменений в механизме генерационной сборки не произошло, а новая функция была удалена («отложена» в 3.14). Также в 3.13 включён альтернативный аллокатор mimalloc, но это касается памяти, а не логики GC.

• Python 3.14: Поколенческий сборщик наконец стал инкрементальным по умолчанию. Это означает, что теперь сборка циклов может разбиваться на мелкие шаги во время исполнения, что значительно сокращает максимальные паузы и делает работу сборщика более предсказуемой. CPython 3.14 также упростил поколенческую модель: осталось два поколения (молодое и старое) вместо трёх. При этом генерация 1 (среднего возраста) фактически была удалена – в gc.get_objects() для 3.14 видно, что generation=1 не возвращает объектов. Кроме того, изменены пороги сборки: теперь threshold2 игнорируется, а параметры по умолчанию подобраны для инкрементального сбора (в т. ч. среднее сканирование старого поколения ≈1% за проход).

До/после:

• Было (до 3.12) – обычная поколенческая сборка при каждой N-й аллокации.
• Стало (3.12) – сборка на каждом байткоде и при сигнал-чеках (устранено влияние аллокаций).
• Добавлено (3.13 RC1) – инкрементальность (удалено).
• Возвращено (3.14) – инкрементальный (по шагам) GC для циклов, сокращены поколения, обновлены пороги.

Рекомендации при миграции: при переходе с 3.11→3.12 и далее важно проверять время работы коллектора и влияние на паузы. Например, профилировать критичные участки до/после 3.12 для подтверждения отсутствия новых «горячих точек». При переходе 3.13→3.14 следует особенно протестировать задержки GC: 3.14 по умолчанию даёт более равномерные по времени сборки, но при определённых нагрузках требуется перенастройка порогов gc.set_threshold() для оптимального баланса. Возможен регрессионный код, если он ожидал специфичного поведения GC (например, ручной gc.collect(1) в 3.14 уже не делает полноценного прохода).

Ниже приведена схема двух поколений в 3.14 и изменённого поведения gc.collect():

   [Ввод нового объекта] --> помещается в поколение 0 (молодое)

   Порог сборки поколения 0 превышен →
      Сборка: метка/сбор поколения 0 (и часть поколения 2) [по умолчанию 1%].

   Объекты, пережившие N сборок → продвигаются в поколение 2 (старое).

Если вручную вызвать gc.collect(0), сборится только молодое поколение; gc.collect(2) или без аргумента – полная сборка. В 3.14 параметр gc.collect(1) больше не существует (и игнорируется).

Практические советы и отладка

Инструменты Python:

• Модуль gc: позволяет включать/отключать сборку (gc.enable/disable()), менять пороги (gc.set_threshold()), вызывать сборку вручную (gc.collect()), получать статистику (gc.get_stats() возвращает количество сборов/объектов) и просматривать «трупы» (gc.garbage, содержит объекты, недоступные для освобождения). Также gc.get_referrers() помогает понять цепочки ссылок.
• tracemalloc: модуль для профилирования распределения памяти (отслеживает, где и сколько памяти выделено). Полезен для поиска утечек и «горячих» мест по выделению памяти.
• Внешние библиотеки: objgraph (визуализация графа объектов, поиск циклов), Heapy/Guppy (анализ размеров объектов), memory_profiler.
• Отладка: флаги gc.set_debug(gc.DEBUG_STATS|DEBUG_SAVEALL) выводят подробности о сборках (когда и что собрано, непригодные объекты попадают в gc.garbage). Это помогает находить, какие типы объектов создают циклы.

Советы при написании кода:

• Избегайте ненужных циклов: по возможности «разрывайте» циклические ссылки, особенно если задействуются объекты с __del__. Используйте слабые ссылки (weakref) там, где объекты могут ссылаться друг на друга (например, кэш, графы).
• Контекстные менеджеры: для ресурсов (файлы, соединения) используйте with, чтобы гарантировать освобождение, а не полагайтесь на GC.
• Явное удаление: del obj можно использовать для явного уменьшения счётчика и ускорения GC (особенно в циклах), однако в большинстве случаев достаточно просто потерять ссылку.
• Оптимальное использование builtins: некоторые встроенные типы имеют собственные free-листы (например, маленькие кортежи, списки) – очищайте их явным gc.collect(), если нужно уменьшить пиковое потребление.
• Низкоуровневое управление: при экстремальной оптимизации можно переключать аллокаторы (PYTHONMALLOC), но это выходит за рамки GC.

Профилирование GC: измерять время сборки можно вставкой таймеров вокруг gc.collect() или использовать gc.callbacks (Python 3.3+) для отслеживания начала/конца каждой сборки. Внешние профайлеры (например, PyInstrument) также могут показать влияние GC на общее время.

GC облегчает работу программиста, освобождая от ручного управления памятью, но требует понимания своих ограничений. Важно знать базовые понятия (достижимость, циклы) и архитектуру GC своего языка. В Python основной механизм – подсчёт ссылок – делает освобождение объектов почти мгновенным, а дополнительный поколенческий GC решает проблемы циклов (с низкими накладными). Современные версии CPython (3.12–3.14) оптимизируют запуск GC для сокращения пауз. Для углубления рекомендую следующие ресурсы:

• Memory Management — Python/C API reference manual, раздел Overview (официальная документация).
• Garbage Collector interface (gc module) – официальная документация Python 3.12+.
• What’s New in Python 3.12, 3.13, 3.14 – официальные релиз-ноты Python (главы про GC).
• Jones R., Lins R. Garbage Collection: Algorithms for Automatic Dynamic Memory Management (Wiley, 1996) – классический учебник по алгоритмам сборки мусора.
• Jones R., Hosking A., Moss E. The Garbage Collection Handbook: The Art of Automatic Memory Management (CRC Press, 2011).
• Насутити К. Отладка утечек памяти в Python – обзоры и статьи (например, про tracemalloc и objgraph).

Презентация тут.

• Регистрация: moscowpython.ru
• Прямой эфир и запись: youtube.com

Это репост моей статьи с Хабра

Относительно недавно приняли PEP-810 и началась ТОТАЛЬНАЯ ТРЯСКА, и я ее не понимаю.

PEP-810 - это нововведение, которое добавляет в Python поддержку явных ленивых импортов. Да-да, теперь можно писать:

lazy import jamlib

и модуль jamlib не будет загружен до тех пор, пока ты реально не воспользуешься им в коде. Это может казаться мелочью, но на самом деле - большое изменение для всей экосистемы Python.

Зачем и кому это надо?

Почти все, что написано на python страдает проблемой долгого старта, особенно CLI инструменты. Даже если делаешь some-cli --help это может затянуться, т.к. питон начнет подгружать ВСЕ что объявлено в импортах, даже если --help никак их не трогает. Ленивые импорты решают эту проблему:

• Не обращаешься к somelib - он не грузится
• Не используешь какой-то модуль - он не грузится в sys.modules
• Не используешь функцию - она не грузится в память
• gc не тратит 100 лет на выгребание всего этого мусора после старта

Получаем:

• быстрое время старта
• меньше поедаем памяти
• не исполняем код из импорта лишний раз

Как это работает?

В python введена новая синтаксическая конструкция lazy <import_action> <module>, например lazy import math или lazy from jamlib import Jam (Так же введен аргумент запуска python -X lazy_imports=all)

При этом:

• Ленивые импорты работают только на глобальном уровне, в функции и классы их не прокинуть,
• Импортированный объект сначала - это прокси, который при первом обращении делает реальный импорт и заменяет себя настоящим объектом.

Пример:

lazy import jamlib
print("jamlib" in sys.modules)  # False
print(jamlib.__version__)  # Модуль явно вызывается
print("jamlib" in sys.modules)  # True

И выглядит круто и на деле круто, но…

…в коммьюнити(особенно в русскоязычном) началась ТРЯСКА, я не буду тыкать пальцем в конкретных людей/каналы/посты, но я думаю вы видели этот поток возмущения, вот основные претензии:

Зачем нам ещё одно ключевое слово?!

Многие в сообществе возмутились, что lazy засоряет синтаксис. Мол, Python и так превращается в свалку ключевых слов (async, match, теперь ещё lazy...). Было предложение использовать defer import, import(lazy), или вообще ничего не менять и продолжать писать import внутри функции.

Но это смешно, не нужно - не используй. Вот и все.

Ошибки теперь будут позже

Если без lazy ошибка импорта выскочит сразу, при запуске, то с lazy только когда модуль будет явно использован.

О ужас, это же реально все меняет (нет)! Для такого аргумента у меня один и тот же ответ: пиши тесты и код проверяй перед тем как лить куда-то.

Импорты имеют побочные эффекты

Да, импорты могут делать что-то важное при инициализации, но просто не засовывай их в lazy и не будет проблем.

Сложность растет

УУУУ СТАЛО СЛОЖНО, это же целое ключевое слово, лишняя магия. Давайте тогда вообще язык не развивать? Про типы вне typing тоже вой стоял, а сейчас хлебом не корми, дай тайпинга насыпать.

Я лично считаю, что PEP-810 - очень аккуратное и мощное улучшение. Оно не навязывается, оно даёт реальную пользу в больших проектах, и оно не ломает обратную совместимость. Да, баги могут стать чуть менее предсказуемыми. Но зато это шаг к более эффективному и современному Python. Главное - не злоупотреблять, а использовать, когда действительно есть польза.

А тряска - ну, Python-сообщество традиционно очень активно и страстно холиварит без повода. Но мне кажется, что PEP-810 останется, и через год все будут писать lazy import так же спокойно, как async def.