[DRAFT] docs(authentication): add authentication layer enhancement proposal

[chadcrum]

Note: This enhancement could change depending outcome of architecture change discussion

Summary

Enhancement proposal for DCM's authentication layer — FLPATH-4194.

• Gateway auth via oauth2-proxy — Traefik ForwardAuth delegates to oauth2-proxy for JWT validation, JWKS caching, and OIDC lifecycle. No custom auth service needed.
• Actor middleware — shared Go package replaces NoopAuthenticationFunc in all services. Resolves JWT sub claim → actor DB lookup → request context (with LRU cache).
• Tenant isolation — TenantScope() query middleware with CI lint enforcement and Phase 3 tenant leak integration tests.
• Built-in local user store — username/password → DCM-issued JWT for bootstrap and testing, toggleable via DCM_BUILTIN_AUTH.
• Actor/tenant lifecycle — active, suspended, deactivated states with middleware enforcement.
• Four-phase migration — schema → permissive → tenant isolation → enforcing, each independently rollbackable.
• CLI authentication — dcm login via OIDC Device Authorization Grant.
• Keycloak as V1 identity provider, with Kuadrant/Authorino documented as a deferred alternative.

Jira

FLPATH-4194 (epic: FLPATH-3254)

Test plan

• Mermaid diagrams render correctly
• Cross-references to related enhancements are valid
• cspell passes
• Team review of open questions (1-5)

🤖 Generated with Claude Code