[Initiative] Pluggable Identity and Access Contract (AuthN/AuthZ/UserDir)

[juliuskrah]

Summary

Define and ratify the pluggable identity and access contract for GitStore by separating Authentication (AuthN), Authorization (AuthZ), and User Management (UserDir), with provider-driven runtime selection.

Scope

In Scope

• Canonical internal Principal contract (subject, issuer, groups/roles/scopes, claims, auth method).
• Provider interfaces and capability model for AuthN, AuthZ, and UserDir.
• Config model for provider selection and execution order.
• Local, secure-local, and production reference profiles.
• Guardrails for explicit authn=none mode.
• Decision record for GraphQL-first login surface and deprecation target for REST login.

Out of Scope

• End-to-end implementation of every external provider adapter.
• Full user-account UX flows.
• Migration/backward compatibility guarantees (alpha stage).

Acceptance Criteria

• Architecture decision record defines AuthN/AuthZ/UserDir separation and ownership boundaries.
• Canonical Principal contract is documented and approved.
• Provider interfaces are specified for authn, authz, and userdir with capability flags.
• Runtime profile matrix is documented (local, secure-local, production).
• authn=none constraints are documented (explicit opt-in + production guardrail).
• Login API decision is documented: GraphQL is canonical for first-party login; REST login endpoint is deprecated.

Dependencies

• Related to [Initiative] Namespaces #39, Declarative Namespace Resource Contract (.spec/.status) #170, [Initiative] Controller Manager Reconciliation Loop for Core Resources and CRDs #165, [Initiative] GraphQL Status Subresource Contract for Controllers #166.
• This initiative should unblock policy-based authorization rollout for namespace and controller surfaces.

Implementation Plan

1. Finalize contract document and ADR.
2. Define configuration schema additions (authn, authz, userdir).
3. Define capability validation rules at startup.
4. Define migration sequence for resolver/service auth checks.

Tracking

• Design doc: docs/implementation/pluggable_auth_design.md
• Follow-up implementation initiative will depend on this item.