Rene Nochebuena
8a306abed0
Introduces code.nochebuena.dev/einherjar/auth — the provider-agnostic HTTP
authentication and authorization layer of the Einherjar framework. Absorbs
two micro-lib packages (httpauth, rbac) as sub-packages, replacing the
Identity-only context model with a SecurityBag-native design and adding a
composable enrichment chain.
authmw:
- BagEnricher function type — enriches the request-scoped SecurityBag after
the base Identity is built; registered via WithBagEnricher; multiple
enrichers run in order, each receiving the bag from the previous
- IdentityEnricher interface — application-layer contract for loading user
data from uid+claims
- EnrichmentMiddleware — builds SecurityBag from uid+claims, runs enricher
chain, stores via security.SetBagInContext; 401 on missing uid, 500 on
enricher error; routes all errors through httputil.Error
- AuthzMiddleware — per-route permission gate; 401 on missing identity,
403 on provider error (fail-closed) or insufficient permissions
- EnrichOpt type + WithTenantHeader (reads TenantID from header, implemented
as a BagEnricher) + WithBagEnricher (registers custom enrichers for
hardware IDs, grant codes, or any bag attribute)
- SetTokenData / GetClaims — integration contract for auth-jwt / auth-firebase
rbac:
- NewClaimsPermissionProvider — reads flat JWT claim bitmasks from context;
wildcard "*" fallback; handles int64/float64/json.Number; zero DB calls
- NewCachedPermissionProvider — TTL cache wrapping any PermissionProvider;
default key "rbac:{uid}:{resource}" or "rbac:{tenantID}:{uid}:{resource}";
TenantID sourced from SecurityBag automatically; accepts ...CachedOpt
- CachedOpt type + WithCacheKey — overrides the key function for extra
dimensions (hardware IDs, grant codes read from bag attributes)
- NewChainPermissionProvider — tries providers in order; first non-zero wins;
errors short-circuit; typical pattern: claims → cached DB fallback
- Cache interface — pluggable backend satisfied by cache-valkey via duck typing
Compliance test (package auth_test) enforces CT-6 (≤1 exported TypeSpec/file),
compile-time interface satisfaction, and behavioural coverage across the full
middleware and provider surface: enrichment success/failure, tenant header,
custom BagEnricher, bag-in-context, authz allowed/denied/error, claims
hit/wildcard/missing/float64, cached hit/miss/error/tenant-key/custom-key,
chain first-non-zero/fallthrough/error.
Depends on contracts v1.0.0, core v1.0.0, web v1.0.0.
- identifiable.go: package-level Module variable (observability.Identifiable) for version
identification — auth is middleware-only; not registered with the launcher
45 lines
1.8 KiB
Go
45 lines
1.8 KiB
Go
// Package authmw provides provider-agnostic HTTP authentication and authorization
|
|
// middleware for the Einherjar framework.
|
|
//
|
|
// The middleware chain follows a three-step pattern:
|
|
//
|
|
// 1. A provider-specific AuthMiddleware (from auth-jwt or auth-firebase) verifies
|
|
// the token and calls [SetTokenData] to store uid and claims in the request context.
|
|
//
|
|
// 2. [EnrichmentMiddleware] reads uid+claims, calls the application-provided
|
|
// [IdentityEnricher] to build a [security.Identity], wraps it in a
|
|
// [security.SecurityBag], runs any registered [BagEnricher] functions to attach
|
|
// extra attributes (tenant ID, hardware IDs, grant codes), and stores the bag
|
|
// in context via [security.SetBagInContext].
|
|
//
|
|
// 3. [AuthzMiddleware] — mounted per route — reads the identity from context and
|
|
// checks the required permission against a [security.PermissionProvider].
|
|
//
|
|
// # Typical wiring
|
|
//
|
|
// enricher := userservice.NewIdentityEnricher(userRepo)
|
|
//
|
|
// // Provider AuthMiddleware is added first (from auth-jwt or auth-firebase).
|
|
// // Then, globally:
|
|
// srv.Use(authmw.EnrichmentMiddleware(logger, enricher))
|
|
//
|
|
// // Per route:
|
|
// const Read = security.Permission(0)
|
|
// srv.With(authmw.AuthzMiddleware(logger, permProvider, "orders", Read)).
|
|
// Get("/orders", ordersHandler)
|
|
//
|
|
// # Multi-tenant
|
|
//
|
|
// srv.Use(authmw.EnrichmentMiddleware(logger, enricher, authmw.WithTenantHeader("X-Tenant-ID")))
|
|
//
|
|
// # Custom bag enrichment
|
|
//
|
|
// const KeyHardwareID = "hardware_id"
|
|
//
|
|
// hwEnricher := authmw.BagEnricher(func(bag security.SecurityBag, r *http.Request) security.SecurityBag {
|
|
// return bag.With(KeyHardwareID, r.Header.Get("X-Hardware-ID"))
|
|
// })
|
|
//
|
|
// srv.Use(authmw.EnrichmentMiddleware(logger, enricher, authmw.WithBagEnricher(hwEnricher)))
|
|
package authmw
|