auth/docs/adr/index.md

Architecture Decision Records — einherjar/auth

ADR-001: No root factory

Status: Accepted

Context: Previous starters (web) expose a root New(logger, ...Config) factory that pre-wires a complete, opinionated stack for the common case. The same pattern was evaluated for auth.

Decision: auth exposes no root factory. The module is composition-only.

Rationale: web.New works because the right middleware stack is always the same (Recover → RequestID → RequestLogger → CORS). Auth has no equivalent universal default:

• The auth provider is application-specific (JWT vs Firebase vs custom)
• The IdentityEnricher is always application code
• AuthzMiddleware is per-route, not global
• The PermissionProvider chain depends on the application's permission model

A root factory would either be a thin wrapper (adds no value) or force premature architectural choices on the caller.

---

ADR-002: Logger added to both middleware functions

Status: Accepted

Context: micro-lib's EnrichmentMiddleware and AuthzMiddleware were logger-free — errors were written as HTTP responses with no log emission.

Decision: Both middleware functions accept logging.Logger and route all errors through httputil.Error(logger, w, r, err).

Rationale:

• An IdentityEnricher returning a 500 is a server-side failure. It must be logged — silent 500s are invisible in production.
• httputil.Error is the single error-processing point for the framework. Using it in auth keeps error response shape, log levels, and field enrichment identical to application handlers.
• 401 (missing token) and 403 (permission denied) log at Warn — client errors, not operator alerts.
• Log level routing is already handled by httputil.Error; no per-middleware logic needed.

---

ADR-003: auth depends on web for httputil.Error

Status: Accepted

Context: auth error responses could be written independently (custom JSON write, like micro-lib's WriteJSONError) to avoid a dependency on web.

Decision: auth depends on code.nochebuena.dev/einherjar/web solely for httputil.Error.

Rationale:

• Consistent error shape across the entire API surface — auth errors and handler errors are indistinguishable to clients.
• httputil.Error handles log level routing, error code extraction, and platform code inclusion. Duplicating this in auth would create two implementations that drift over time.
• The dependency is one-directional: web does not depend on auth. The dependency graph remains acyclic.

Trade-off accepted: auth cannot be used without web. This is acceptable — auth is an HTTP middleware layer and web is the HTTP layer. Separating them was never a goal.

---

ADR-004: BagEnricher chain over arbitrary context injection

Status: Accepted

Context: The original design used WithTenantHeader as the sole enrichment option, storing additional attributes via arbitrary context.WithValue calls. This made enrichment opaque — permission providers had no structured way to access request attributes like hardware IDs or grant codes without knowing the exact context key used elsewhere.

Decision: Enrichment is modeled as a chain of BagEnricher functions that transform a security.SecurityBag. EnrichmentMiddleware creates the bag from the base Identity, runs all registered BagEnricher functions in order, and stores the final bag via security.SetBagInContext. Permission providers retrieve the bag once with security.BagFromContext(ctx) and have access to all enriched attributes via bag.Get(key).

Rationale:

• Single structured object per request instead of scattered context.WithValue entries; easier to reason about what's in the security context at any point in the chain.
• Permission providers access any bag attribute in one call rather than knowing which context key to look up.
• WithCacheKey on CachedPermissionProvider receives the full bag — no new parameters needed to include extra dimensions (hardware IDs, grant codes) in the cache key.
• WithTenantHeader is now a thin wrapper over WithBagEnricher, so the same extension point covers all enrichment use cases.
• Framework-owned attributes remain typed fields on Identity. Only application-defined attributes go into the bag's string-keyed map. Callers define their own key constants to maintain compile-time safety at the type-assertion call site.

Trade-off accepted: Bag attributes are any — type assertions are required at read sites. This is inherent to a string-keyed heterogeneous map. The contract is: the package that writes an attribute owns the constant and documents the type; callers that read it perform the assertion.