60 lines
2.7 KiB
Go
60 lines
2.7 KiB
Go
|
// Package auth provides provider-agnostic HTTP authentication and authorization
|
||
|
|
// middleware for the Einherjar framework.
|
||
|
|
//
|
||
|
|
// auth absorbs two micro-lib packages:
|
||
|
|
// - httpauth → sub-package authmw (middleware + identity enrichment)
|
||
|
|
// - rbac → sub-package rbac (permission provider implementations)
|
||
|
|
//
|
||
|
|
// Types that cross the full dependency graph (Identity, Permission, PermissionMask,
|
||
|
|
// PermissionProvider) live in contracts/security, not here. This module provides
|
||
|
|
// implementations and middleware, not type definitions.
|
||
|
|
//
|
||
|
|
// # Sub-packages
|
||
|
|
//
|
||
|
|
// [authmw] — HTTP middleware layer. Three functions compose the full auth chain:
|
||
|
|
//
|
||
|
|
// - [authmw.SetTokenData] — integration contract called by provider packages
|
||
|
|
// (auth-jwt, auth-firebase) after token verification.
|
||
|
|
// - [authmw.EnrichmentMiddleware] — converts uid+claims into a security.Identity
|
||
|
|
// and stores it in context. The application provides the [authmw.IdentityEnricher]
|
||
|
|
// implementation that loads user data.
|
||
|
|
// - [authmw.AuthzMiddleware] — per-route permission gate. Takes a
|
||
|
|
// [security.PermissionProvider] and the required permission for the route.
|
||
|
|
//
|
||
|
|
// [rbac] — permission resolution. Three provider implementations satisfy
|
||
|
|
// [security.PermissionProvider]:
|
||
|
|
//
|
||
|
|
// - [rbac.NewClaimsPermissionProvider] — reads pre-computed bitmasks from JWT
|
||
|
|
// claims. Zero DB calls. Single-tenant fast-path.
|
||
|
|
// - [rbac.NewCachedPermissionProvider] — wraps any provider with a TTL cache.
|
||
|
|
// Cache keys are automatically scoped by TenantID when present.
|
||
|
|
// - [rbac.NewChainPermissionProvider] — tries providers in order; returns the
|
||
|
|
// first non-zero mask. Typical: claims fast-path → cached DB fallback.
|
||
|
|
//
|
||
|
|
// # Wiring Example
|
||
|
|
//
|
||
|
|
// enricher := userservice.NewIdentityEnricher(userRepo)
|
||
|
|
//
|
||
|
|
// permissions := rbac.NewChainPermissionProvider(
|
||
|
|
// rbac.NewClaimsPermissionProvider("perms", authmw.GetClaims),
|
||
|
|
// rbac.NewCachedPermissionProvider(dbProvider, valkeyCache, 5*time.Minute),
|
||
|
|
// )
|
||
|
|
//
|
||
|
|
// // After provider AuthMiddleware (from auth-jwt or auth-firebase):
|
||
|
|
// srv.Use(authmw.EnrichmentMiddleware(logger, enricher))
|
||
|
|
//
|
||
|
|
// // Per-route authorization:
|
||
|
|
// srv.With(authmw.AuthzMiddleware(logger, permissions, "orders", security.Permission(0))).
|
||
|
|
// Get("/orders", ordersHandler)
|
||
|
|
//
|
||
|
|
// # Multi-tenant
|
||
|
|
//
|
||
|
|
// Pass the tenant identifier via a request header:
|
||
|
|
//
|
||
|
|
// srv.Use(authmw.EnrichmentMiddleware(logger, enricher, authmw.WithTenantHeader("X-Tenant-ID")))
|
||
|
|
//
|
||
|
|
// [authmw.WithTenantHeader] populates [security.Identity.TenantID] from the header.
|
||
|
|
// [rbac.NewCachedPermissionProvider] automatically scopes its cache keys by TenantID
|
||
|
|
// when non-empty — no additional configuration required.
|
||
|
|
package auth
|