Пакет для Go (julia-go)
Для сервисов на 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-ключей и интерфейсы кэширования |
.../juliahttp | Middleware формата 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 | Субъект аутентифицирован, но не обладает требуемым правом |
503 | Julia недоступна (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 |