Интеграция

Пакет для Go (julia-go)

Репозиторий
Интеграция сервисов на Go (1.25+) с помощью официального модуля git.cyberzone.dev/cyberzone/julia-go — проверка EdDSA JWT, права, HTTP/gRPC middleware и API-ключи.

Для сервисов на Go (1.25+) доступен официальный модуль git.cyberzone.dev/cyberzone/julia-go, закрывающий все задачи интеграции: валидацию EdDSA JWT, работу с моделью Principal, иерархическую проверку прав, net/http-middleware, клиентские и серверные gRPC-инструменты, интроспекцию и локальный парсинг API-ключей.

Модуль находится в статусе пре-релиза: актуальный тег — v0.1.0-rc.1 (ветка dev). Ветка main пока не содержит стабильного релиза, поэтому при установке указывайте тег @v0.1.0-rc.1 явно.

Ядро пакета не привязано к конкретному транспорту и разделено на несколько подпакетов:

ПакетНазначение
git.cyberzone.dev/cyberzone/julia-go (julia)Client, валидация EdDSA (Ed25519) JWT, Principal, проверка прав (Check, CheckInAnyScope, ResolveAccessLevel), интроспекция API-ключей и интерфейсы кэширования
.../juliahttpMiddleware формата func(http.Handler) http.Handler для net/http (stdlib, chi, gorilla; для gin и echo оборачивается одной строкой)
.../juliagrpcИсходящее подключение Dial с X-Api-Key и TLS по умолчанию, серверные интерцепторы UnaryServerInterceptor и StreamServerInterceptor
.../apikeyЛокальный парсинг, проверка контрольной суммы (Parse), маскирование (Hint) и хеширование (Hash, HashEqual) без сетевых вызовов
.../contracts/*Экспортированные gRPC-клиенты и типы (authpb, userpb, departmentpb, adminpb) + исходные .proto-файлы в каталоге proto/

Установка

export GOPRIVATE=git.cyberzone.dev
go get git.cyberzone.dev/cyberzone/[email protected]

Путь модуля заканчивается на julia-go, но имя корневого пакета — julia. Чтобы избежать расхождений в автоимпорте IDE, рекомендуется использовать явный алиас:

import julia "git.cyberzone.dev/cyberzone/julia-go"

Инициализация клиента

Создайте один экземпляр julia.Client на процесс — он хранит gRPC-соединение с Julia и закэшированный ключ подписи:

client, err := julia.New(julia.Config{
    Token: julia.TokenConfig{
        Issuer:   "https://auth.mirea.app",
        Audience: "cyberzone",
    },
    Upstream: julia.UpstreamConfig{
        Address: "julia.example:443",
        APIKey:  os.Getenv("JULIA_API_KEY"),
    },
})
if err != nil {
    return err
}
defer client.Close()
  • julia.New проверяет всю конфигурацию сразу и возвращает объединённую ошибку (каждая часть оборачивает julia.ErrInvalidConfig).
  • Соединение устанавливается лениво при первом вызове — недоступность Julia на старте не мешает запуску сервиса.
  • Принимается строго алгоритм EdDSA и по умолчанию только token_type == "access". Публичный ключ загружается из Keys.GetPublicKey и кэшируется с защитой от повторных запросов на неизвестные kid.
  • При необходимости ключ можно закрепить локально через julia.WithKeySource(...), переиспользовать готовое соединение через julia.WithConn(conn) или передать опции дозвона через julia.WithDialOptions(...) (например, grpc.WithTransportCredentials(insecure.NewCredentials()) для незашифрованного внутреннего канала).

HTTP-middleware (juliahttp)

Все middleware имеют стандартную сигнатуру func(http.Handler) http.Handler:

import (
    "net/http"

    julia "git.cyberzone.dev/cyberzone/julia-go"
    "git.cyberzone.dev/cyberzone/julia-go/juliahttp"
)

router := http.NewServeMux()

// Только аутентификация (Bearer JWT):
router.Handle("GET /profile", juliahttp.Authenticate(client)(profileHandler))

// Аутентификация + проверка права (Authenticate всегда идёт первым):
router.Handle("DELETE /users/{id}",
    juliahttp.Authenticate(client)(
        juliahttp.RequirePermission(client, "myservice.users:delete")(deleteUserHandler)))

// Анонимные запросы допускаются, валидный токен распознаётся (битый — отклоняется с 401):
router.Handle("GET /articles", juliahttp.Optional(client)(articlesHandler))

Получение субъекта в обработчике:

principal, ok := julia.PrincipalFromContext(r.Context())

Для проверки нескольких прав используйте juliahttp.RequireAny(client, []string{...}) и juliahttp.RequireAll(client, []string{...}) (передача пустого среза вызывает panic при инициализации, чтобы исключить случайно незащищённый маршрут). Цепочка из нескольких Require*-middleware запрашивает права пользователя один раз на запрос.

Приём API-ключей на HTTP-маршрутах

По умолчанию juliahttp принимает только Authorization: Bearer <jwt>. Приём X-Api-Key включается явно на нужных маршрутах через juliahttp.WithAPIKeyHeader():

router.Handle("POST /invoices",
    juliahttp.Authenticate(client,
        juliahttp.WithAPIKeyHeader(),
        // За прокси укажите доверенный источник IP клиента для проверки AllowedIps:
        juliahttp.WithClientIP(func(r *http.Request) string {
            return r.Header.Get("X-Real-Ip")
        }),
    )(createInvoiceHandler))
По умолчанию для проверки AllowedIps используется r.RemoteAddr (peer соединения), а заголовок X-Forwarded-For намеренно игнорируется, так как его может подделать клиент. Если в запросе переданы одновременно и Bearer JWT, и API-ключ, приоритет отдаётся Bearer-токену.

Коды HTTP-ответов

СтатусКогда возвращается
401Нет учётных данных или они не прошли проверку (с заголовком WWW-Authenticate)
403Субъект аутентифицирован, но не обладает требуемым правом
503Julia недоступна (ErrUpstream) — сбой ретраибелен и не сбрасывает сессию клиента
500Прочие внутренние ошибки (например, проверка прав без PermissionProvider)

По умолчанию тело ответа не раскрывает причину отказа; поведение настраивается через juliahttp.WithErrorHandler(...).


Проверка доступа к ресурсу и уровни доступа

Для маршрутов с идентификатором целевого ресурса используйте грубую проверку RequirePermissionInAnyScope на роутере и точную проверку экземпляра внутри обработчика:

router.Handle("GET /users/{id}/orders",
    juliahttp.Authenticate(client)(
        juliahttp.RequirePermissionInAnyScope(client, "myservice.orders:read")(listOrdersHandler)))

// Внутри listOrdersHandler, когда известен id целевого пользователя:
granted, err := client.Check(ctx, principal, "myservice.orders:read:"+id)

Если эндпоинт публичен и меняет объём ответа в зависимости от вызывающего, используйте client.ResolveAccessLevel:

level, err := client.ResolveAccessLevel(ctx, principal, ownerID, "myservice.users:read")
// Возвращает julia.AccessPublic, julia.AccessOwner или julia.AccessPrivileged

Владение (AccessOwner) проверяется до сетевого запроса прав и применяется только к пользователям (SubjectUser); сервисные субъекты (SubjectMachine) получают доступ исключительно через права.


gRPC (juliagrpc и contracts)

Исходящие вызовы к Julia

juliagrpc.Dial открывает TLS-соединение и автоматически добавляет метаданные X-Api-Key к каждому унарному и потоковому вызову. Сгенерированные клиенты лежат в contracts/:

import (
    "os"

    "git.cyberzone.dev/cyberzone/julia-go/contracts/departmentpb"
    "git.cyberzone.dev/cyberzone/julia-go/juliagrpc"
)

conn, err := juliagrpc.Dial("julia.example:443", os.Getenv("JULIA_API_KEY"))
if err != nil {
    return err
}
defer conn.Close()

departments := departmentpb.NewDepartmentsClient(conn)

Для локальной работы или внутреннего незашифрованного канала передайте grpc.WithTransportCredentials(insecure.NewCredentials()) в juliagrpc.Dial.

Защита собственного gRPC-сервера

import (
    "google.golang.org/grpc"

    "git.cyberzone.dev/cyberzone/julia-go/juliagrpc"
)

server := grpc.NewServer(
    grpc.ChainUnaryInterceptor(juliagrpc.UnaryServerInterceptor(client,
        juliagrpc.WithServerAPIKeys(), // опционально: принимать X-Api-Key в метаданных
        juliagrpc.WithAnonymousMethods("/grpc.health.v1.Health/Check"),
        juliagrpc.WithMethodPolicies(map[string]juliagrpc.MethodPolicy{
            "/billing.Invoices/Delete": {All: []string{"billing.invoices:delete"}},
            "/billing.Invoices/List":   {AnyScope: "billing.invoices:read"},
        }),
    )),
    grpc.ChainStreamInterceptor(juliagrpc.StreamServerInterceptor(client)),
)
Метод, не указанный в WithMethodPolicies, аутентифицируется и пропускается без проверки прав (как в .NET-интерцепторе без атрибута [RequirePermission]). Ошибки по умолчанию мапятся в Unauthenticated, PermissionDenied, Unavailable и Internal; маппинг переопределяется через juliagrpc.WithStatusMapper.

Кэширование прав и интроспекции

Модуль намеренно не реализует хранилище кэша (in-memory, Redis и т. д.), но предоставляет готовые интерфейсы с дедупликацией параллельных промахов (singleflight) и отказоустойчивым fallback при ошибках кэша:

client, err := julia.New(cfg,
    julia.WithPermissionCache(myPermissionCache, time.Minute),
    julia.WithAPIKeyCache(myAPIKeyCache),
)
  • julia.PermissionCache — кэширует PermissionSet по ключу субъекта (julia.PermissionCacheKey(subjectID)). Ручная инвалидация: client.ForgetPermissions(ctx, subjectID).
  • julia.APIKeyCache — кэширует APIKeyRecord по SHA-256 предъявленного ключа с учётом ip_unrestricted (APIKeyCacheKey и APIKeyCacheKeyAnyAddress). TTL передавать не нужно: клиент автоматически использует cache_ttl_seconds из ответа Julia и ограничивает его сроком expires_at. Ручная инвалидация: client.ForgetAPIKey(ctx, key, remoteIP).

Локальный разбор API-ключей (apikey)

Пакет apikey проверяет структуру и контрольную сумму ключа локально без соединения с Julia (зависит только от stdlib и google/uuid):

import "git.cyberzone.dev/cyberzone/julia-go/apikey"

ref, err := apikey.Parse(presentedKey)  // ref.TokenID, ref.Namespace, ref.Kind
hint, err := apikey.Hint(presentedKey)  // "cza-pat-019f***c349" — безопасно для логов и UI
hash := apikey.Hash(presentedKey)       // [32]byte SHA-256 для ключей кэша
equal := apikey.HashEqual(a, b)         // сравнение за постоянное время

Ошибки

Все ошибки оборачиваются и проверяются через errors.Is:

ОшибкаЗначение
julia.ErrInvalidTokenТокен или API-ключ не прошёл проверку (подпись, iss/aud, срок действия, тип токена, отказ Julia)
julia.ErrUnknownKeyПодпись ключом, которого нет в Julia (также матчится как ErrInvalidToken)
julia.ErrUpstreamСбой обращения к Julia — не ошибка аутентификации
julia.ErrForbiddenНедостаточно прав (возвращают транспорты; Check возвращает false, nil)
julia.ErrInvalidClaimsВалидный токен не содержит корректной структуры claims Julia
julia.ErrInvalidPermissionНекорректная строка права (при разборе через ParsePermission)
julia.ErrInvalidConfigОшибки конфигурации при вызове julia.New
julia.ErrNoPermissionProviderВызвана проверка прав на Client без PermissionProvider
julia.ErrNoIntrospectionПопытка проверить API-ключ на Client без подключения к Julia