auth/README.md

# einherjar/auth

[![version](https://img.shields.io/badge/version-v1.0.0-5C4EE5?style=flat-square)](https://code.nochebuena.dev/einherjar/auth)
[![license](https://img.shields.io/badge/license-AGPL--3.0-22863A?style=flat-square)](LICENSE)
[![go](https://img.shields.io/badge/Go-1.26+-00ADD8?style=flat-square&logo=go&logoColor=white)](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"),                                // 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.0.0
```