Основные концепции

Эта страница объясняет ключевые абстракции и модель проектирования CyberGo JWT, помогая построить общее понимание. Чтобы сразу перейти к практике, перейдите к Быстрому старту.

Processor — центральный тип

Processor — центральный тип библиотеки, создаваемый через jwt.New(cfg). Он инкапсулирует всю логику выдачи, проверки, обновления и отзыва токенов. Все методы потокобезопасны — один экземпляр можно разделять между горутинами.

Вызовите Close() после использования для безопасного очищения секретного ключа и освобождения ресурсов:

<!-- check-code: skip -->
cfg := jwt.DefaultConfig()
cfg.SecretKey = "your-32-byte-secret-key-here-minimum"

processor, err := jwt.New(cfg)
if err != nil {
    log.Fatal(err)
}
defer processor.Close()

Processor реализует интерфейс TokenManager, что позволяет использовать его для внедрения зависимостей и подмены в тестах.

Жизненный цикл токена

Токен проходит следующие этапы от выдачи до аннулирования:

Выдача  Create(claims)           → Токен доступа (краткосрочный)
        CreateRefresh(claims)     → Токен обновления (долгосрочный)

Проверка Validate(token)          → Claims (проверка подписи, срока, издателя, чёрного списка)

Обновление Refresh(refreshToken)  → Новый токен доступа

Отзыв   Revoke(token)             → Добавлен в чёрный список
Проверка IsRevoked(token)         → bool

Каждый этап возвращает сентинельные ошибки (например ErrTokenExpired, ErrTokenRevoked), которые можно точно сопоставить через errors.Is(). См. Обработка ошибок.

Двухуровневая модель токенов

CyberGo JWT использует дизайн с токеном доступа + токеном обновления:

	Токен доступа	Токен обновления
Назначение	Аутентификация API	Получение новых токенов доступа
TTL по умолчанию	15 минут	7 дней
Метод выдачи	Create	CreateRefresh
Метод обновления	—	Refresh

Зачем два уровня? Токены доступа живут недолго, поэтому окно риска при утечке невелико. Токены обновления живут долго, но используются только для получения новых токенов доступа, никогда — для прямой аутентификации API. Этот дизайн балансирует безопасность и пользовательский опыт: пользователям не нужно часто входить в систему, а токены доступа можно обновлять автоматически после истечения.

Семантика ротации

Refresh не отзывает токен обновления автоматически. Исходный токен обновления остаётся действительным до истечения срока или явного вызова Revoke. Для семантики одноразового использования (ротация токенов обновления) вызовите Revoke для старого токена обновления после успешного Refresh. См. Обновление и ротация токенов.

Структура Claims

Claims переносят данные идентификации пользователя внутри токена. CyberGo JWT предоставляет двухуровневую структуру:

RegisteredClaims (стандартные claims RFC 7519, автоматическое заполнение и проверка):

Поле	claim	Описание
Issuer	iss	Идентификатор издателя
Subject	sub	Идентификатор субъекта (также ключ ограничения скорости)
Audience	aud	Целевая аудитория
ExpiresAt	exp	Срок действия
NotBefore	nbf	Время начала действия
IssuedAt	iat	Время выдачи
ID	jti	Уникальный идентификатор (ключ чёрного списка)
TokenType	token_type	access или refresh

Claims (встроенные бизнес-claims, встраивает RegisteredClaims):

<!-- check-code: skip -->
type Claims struct {
    UserID      string         // ID пользователя
    Username    string         // Имя пользователя
    Role        string         // Роль
    Permissions []string       // Список разрешений
    Scopes      []string       // OAuth-области
    SessionID   string         // ID сессии
    ClientID    string         // ID клиента
    Extra       map[string]any // Дополнительные поля
    RegisteredClaims           // Стандартные claims (встраивание)
}

Все поля проходят проверку ввода: ограничение длины строки 256, ограничение массива 100, обнаружение шаблонов инъекций (сигнатуры XSS/SQLi).

Интерфейс CustomClaims

Когда встроенные Claims не отвечают бизнес-требованиям, реализуйте интерфейс CustomClaims для определения собственной структуры claims:

<!-- check-code: skip -->
type AppClaims struct {
    UserID string   `json:"user_id"`
    TeamID string   `json:"team_id"`
    Roles  []string `json:"roles,omitempty"`
    jwt.RegisteredClaims
}

func (c *AppClaims) GetRegisteredClaims() *jwt.RegisteredClaims {
    return &c.RegisteredClaims
}

func (c *AppClaims) Validate() error {
    if c.UserID == "" {
        return errors.New("user_id is required")
    }
    return nil
}

Пользовательские типы проверяются через ValidateInto и обновляются через RefreshInto — Processor разбирает токен и заполняет вашу структуру. См. Пользовательские Claims.

Обзор Config

Config — единая точка конфигурации Processor. Начните с DefaultConfig() для разумных значений по умолчанию, затем задайте ключ подписи:

Группа	Поля	Описание
Подпись	SecretKey / SigningKey / VerificationKey / SigningMethod	HMAC использует SecretKey; RSA/ECDSA использует SigningKey
Токен	AccessTokenTTL / RefreshTokenTTL	Время жизни токенов доступа и обновления
Проверка	Issuer / ExpectedAudience / RequireExpiration / ClockSkew	Издатель, аудитория, обязательный срок действия, допуск часов
Безопасность	Blacklist / EnableRateLimit	Хранилище отзывов и ограничение скорости
Расширение	Clock	Внедрение часов (для тестирования)

Выбор алгоритма см. в Алгоритмы подписи; полную документацию по полям — в Конфигурации.

Интерфейсы расширения

CyberGo JWT расширяется через интерфейсы:

Интерфейс	Назначение
TokenManager	Основной интерфейс, реализуемый Processor. Можно определить собственный подмножественный интерфейс (только Create + Validate) для внедрения зависимостей и слабой связанности
BlacklistStore	Пользовательский бэкенд чёрного списка (например, Redis). Реализуйте Add / Contains / Close для подключения внешнего хранилища
RateLimitProvider	Пользовательский ограничитель скорости. Реализуйте Allow / Reset / Close для замены встроенного алгоритма token bucket
ClockProvider	Внедрение часов. FixedClock возвращает фиксированное время для детерминированного контроля логики истечения и обновления в тестах

Следующие шаги

• Быстрый старт — Выпустите свой первый токен
• Алгоритмы подписи — Руководство по выбору HMAC, RSA, ECDSA
• Конфигурация — Полный справочник по полям и усилению безопасности
• Интеграция с веб-сервером — Middleware аутентификации и RBAC на практике