133 lines
4.2 KiB
Markdown
133 lines
4.2 KiB
Markdown
# einherjar/auth
|
|
|
|
[](https://code.nochebuena.dev/einherjar/auth)
|
|
[](LICENSE)
|
|
[](https://go.dev)
|
|
|
|
> 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`](authmw/) | HTTP middleware: `EnrichmentMiddleware`, `AuthzMiddleware`, `SetTokenData`, `BagEnricher` |
|
|
| [`rbac`](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
|
|
|
|
```go
|
|
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", authmw.GetClaims), // 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.
|
|
|
|
```go
|
|
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:
|
|
|
|
```go
|
|
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
|
|
|
|
```go
|
|
// 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:
|
|
|
|
```go
|
|
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):
|
|
|
|
```go
|
|
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
|
|
|
|
```bash
|
|
go get code.nochebuena.dev/einherjar/auth@v1.1.2
|
|
```
|