auth/README.md

einherjar/auth

Not every warrior who knocks at the gate deserves to pass. The Valkyries choose.

Provider-agnostic HTTP authentication and authorization middleware for the Einherjar framework.

Sub-packages

Package	Description
authmw	HTTP middleware: EnrichmentMiddleware, AuthzMiddleware, SetTokenData, BagEnricher
rbac	Permission providers: ClaimsPermissionProvider, CachedPermissionProvider, ChainPermissionProvider

Dependency graph

contracts/security ──► auth/authmw ──► auth/rbac
contracts/security ──► auth/rbac
core/xerrors       ──► auth/authmw
web/httputil       ──► auth/authmw

No external dependencies.

Wiring example

import (
    "code.nochebuena.dev/einherjar/auth/authmw"
    "code.nochebuena.dev/einherjar/auth/rbac"
    "code.nochebuena.dev/einherjar/contracts/security"
)

// Application implements IdentityEnricher to load user data.
enricher := userservice.NewIdentityEnricher(userRepo)

// Build permission resolution chain.
permissions := rbac.NewChainPermissionProvider(
    rbac.NewClaimsPermissionProvider("perms"),                                // JWT fast-path
    rbac.NewCachedPermissionProvider(dbProvider, valkeyCache, 5*time.Minute), // DB fallback
)

// Provider AuthMiddleware (from auth-jwt or auth-firebase) goes first.
// Then enrichment globally:
srv.Use(authmw.EnrichmentMiddleware(logger, enricher,
    authmw.WithTenantHeader("X-Tenant-ID"),
))

// Per-route authorization:
const ReadOrders = security.Permission(0)
srv.With(authmw.AuthzMiddleware(logger, permissions, "orders", ReadOrders)).
    Get("/orders", ordersHandler)

Custom enrichment

BagEnricher lets you attach any request attribute to the SecurityBag in context. Permission providers read it via bag.Get(key) — no scattered context keys.

const KeyHardwareID = "hardware_id"  // owned by your package; document the value type

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.WithTenantHeader("X-Tenant-ID"),
    authmw.WithBagEnricher(hwEnricher),
))

With a hardware-ID-bound permission model, override the cache key so the hardware ID is included — otherwise two hardware IDs for the same user share a cache entry:

cached := rbac.NewCachedPermissionProvider(dbProvider, cache, 5*time.Minute,
    rbac.WithCacheKey(func(bag security.SecurityBag, uid, resource string) string {
        hwID, _ := bag.Get(KeyHardwareID)
        return fmt.Sprintf("rbac:%s:%s:%v:%s", bag.Identity().TenantID, uid, hwID, resource)
    }),
)

Multi-tenant

// Read TenantID from header; CachedPermissionProvider scopes keys automatically.
srv.Use(authmw.EnrichmentMiddleware(logger, enricher, authmw.WithTenantHeader("X-Tenant-ID")))

• JWT carries "who are you" only — no per-tenant permission claims required
• WithTenantHeader populates security.Identity.TenantID from the request
• CachedPermissionProvider uses "rbac:{tenantID}:{uid}:{resource}" when TenantID is non-empty

Permission model

Permissions are a 63-bit set (security.Permission(0) through security.MaxPermission). Define application permissions as constants:

const (
    Read   = security.Permission(0)
    Write  = security.Permission(1)
    Delete = security.Permission(2)
    Admin  = security.Permission(3)
)

Issue tokens with embedded masks (via auth-jwt):

customClaims := map[string]any{
    "perms": map[string]any{
        "orders": int64(security.PermissionMask(0).Grant(Read).Grant(Write)),
    },
}

Environment variables

None. Auth middleware is wired in code, not configured via environment.

Install

go get code.nochebuena.dev/einherjar/auth@v1.0.0