feat(auth): initial implementation — authmw and rbac (v1.0.0)

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

doc.go

@@ -0,0 +1,59 @@
+// Package auth provides provider-agnostic HTTP authentication and authorization
+// middleware for the Einherjar framework.
+//
+// auth absorbs two micro-lib packages:
+//   - httpauth → sub-package authmw (middleware + identity enrichment)
+//   - rbac     → sub-package rbac   (permission provider implementations)
+//
+// Types that cross the full dependency graph (Identity, Permission, PermissionMask,
+// PermissionProvider) live in contracts/security, not here. This module provides
+// implementations and middleware, not type definitions.
+//
+// # Sub-packages
+//
+// [authmw] — HTTP middleware layer. Three functions compose the full auth chain:
+//
+//   - [authmw.SetTokenData] — integration contract called by provider packages
+//     (auth-jwt, auth-firebase) after token verification.
+//   - [authmw.EnrichmentMiddleware] — converts uid+claims into a security.Identity
+//     and stores it in context. The application provides the [authmw.IdentityEnricher]
+//     implementation that loads user data.
+//   - [authmw.AuthzMiddleware] — per-route permission gate. Takes a
+//     [security.PermissionProvider] and the required permission for the route.
+//
+// [rbac] — permission resolution. Three provider implementations satisfy
+// [security.PermissionProvider]:
+//
+//   - [rbac.NewClaimsPermissionProvider] — reads pre-computed bitmasks from JWT
+//     claims. Zero DB calls. Single-tenant fast-path.
+//   - [rbac.NewCachedPermissionProvider] — wraps any provider with a TTL cache.
+//     Cache keys are automatically scoped by TenantID when present.
+//   - [rbac.NewChainPermissionProvider] — tries providers in order; returns the
+//     first non-zero mask. Typical: claims fast-path → cached DB fallback.
+//
+// # Wiring Example
+//
+//	enricher := userservice.NewIdentityEnricher(userRepo)
+//
+//	permissions := rbac.NewChainPermissionProvider(
+//	    rbac.NewClaimsPermissionProvider("perms", authmw.GetClaims),
+//	    rbac.NewCachedPermissionProvider(dbProvider, valkeyCache, 5*time.Minute),
+//	)
+//
+//	// After provider AuthMiddleware (from auth-jwt or auth-firebase):
+//	srv.Use(authmw.EnrichmentMiddleware(logger, enricher))
+//
+//	// Per-route authorization:
+//	srv.With(authmw.AuthzMiddleware(logger, permissions, "orders", security.Permission(0))).
+//	    Get("/orders", ordersHandler)
+//
+// # Multi-tenant
+//
+// Pass the tenant identifier via a request header:
+//
+//	srv.Use(authmw.EnrichmentMiddleware(logger, enricher, authmw.WithTenantHeader("X-Tenant-ID")))
+//
+// [authmw.WithTenantHeader] populates [security.Identity.TenantID] from the header.
+// [rbac.NewCachedPermissionProvider] automatically scopes its cache keys by TenantID
+// when non-empty — no additional configuration required.
+package auth