ADR-0028 Phase B Roadmap

Document ID: PHASE_B_ROADMAP Date: 2026-05-05 evening Status: In Progress Author: AI Agent (vibe/batch4-task-b-phase-b-roadmap)

Status as of 2026-05-05 evening

ADR-0028 Phase A complete (PRs #59-#63, #65)
Phase B.1 OIDC config (PR #64)
Phase B prep : pkg/auth skeleton (PR #69) + mkcert doc (PR #68)
Phase B.3 not yet started

Remaining work

Phase B delivers OpenID Connect Authorization Code flow with PKCE. Work is organized into 3 shippable phases, each deliverable as an independent PR.

Phase B.3 — OIDC client implementation

Goal: Implement the core OIDC client methods in pkg/auth/oidc.go
Tasks:
- Discover(): HTTP GET to /.well-known/openid-configuration, parse + cache discovery document
- RefreshJWKS(): HTTP GET to JWKS URI, parse RSA public keys, cache with TTL
- ExchangeCode(): POST to token endpoint with code + PKCE verifier, return TokenResponse
- ValidateIDToken(): Verify signature against JWKS, validate standard claims (iss, aud, exp, iat)
LOE: ~200 lines of Go + unit tests
Dependencies: None (uses standard library crypto/rsa, encoding/jwt)
Deliverable: 1 PR

Phase B.4 — OIDC HTTP handlers

Goal: Add OIDC flow endpoints and wire them into the server
Tasks:
- Create pkg/user/api/oidc_handler.go
- GET /api/v1/auth/oidc/start:
  - Generate state (CSRF protection) + PKCE verifier + challenge
  - Store state + verifier (cookie or short-lived in-memory store)
  - Redirect to provider's authorization endpoint
- GET /api/v1/auth/oidc/callback:
  - Validate state parameter matches stored state
  - Exchange code for tokens (calls B.3 client)
  - Validate id_token (calls B.3 client)
  - Issue internal JWT (reuse existing JWT manager from ADR-0021)
  - Return JWT in Set-Cookie + JSON body
- Wire routes in pkg/server/server.go
LOE: ~150 lines of Go + unit tests + integration tests
Dependencies: B.3 (client methods must be implemented)
Prerequisite: Run make cert (mkcert, from PR #68) before starting dev
Deliverable: 1 PR

Phase B.5 — BDD coverage

Goal: End-to-end OIDC testing
Tasks:
- Create features/auth/oidc.feature with scenarios:
  - Happy path: start → provider auth → callback → JWT issued
  - Error: state mismatch
  - Error: invalid code
  - Error: expired id_token
- Use mock OIDC provider (local in-process) OR deterministic test against Authelia/Keycloak in docker-compose
- Follow ADR-0030 parallel BDD strategy for email assertions
LOE: ~150 lines of Gherkin + step definitions
Dependencies: B.3 + B.4 (endpoints must be operational)
Deliverable: 1 PR

Dependencies and order

B.3 (OIDC client)
    ↓
B.4 (HTTP handlers) —— requires B.3
    ↓
B.5 (BDD coverage) —— requires B.3 + B.4

Note: mkcert (PR #68) is ready. When starting B.4 development, run make cert once to generate local HTTPS certificates.

Out of scope for Phase B (deferred)

Item	Target Phase	Rationale
Decommission password auth	Phase C	Separate ADR after B is in production
Multi-provider (Authelia + Google)	Phase B.6 (if needed)	Single provider sufficient for MVP
JWKS rotation mid-flight retry	B.3 enhancement	Handle in initial implementation
Token refresh flow	Future	Not required for auth code flow MVP

Risk register

Risk	Mitigation	Owner
JWKS rotation handling	Implement refresh + retry logic; key rotation must not break mid-flight validation	B.3 implementer
PKCE storage	Use signed cookie or short-lived in-memory store; document trade-offs in implementation PR	B.4 implementer
Testing without real provider	Use mock OIDC server for CI; local dev uses Authelia in docker-compose	B.5 implementer
State CSRF protection	Use cryptographically random state; store server-side with short TTL	B.4 implementer

Cross-references

Appendix: File inventory

Existing (merged):

pkg/auth/oidc.go — skeleton with TODO methods (PR #69)
pkg/auth/oidc_test.go — placeholder tests (PR #69)
documentation/MKCERT.md — mkcert setup guide (PR #68)
Makefile — includes make cert target (PR #68)

To be created:

pkg/auth/oidc.go — complete implementation (B.3)
pkg/user/api/oidc_handler.go — HTTP handlers (B.4)
pkg/server/server.go — route wiring (B.4)
features/auth/oidc.feature — BDD scenarios (B.5)
pkg/auth/oidc_test.go — expanded unit tests (B.3)
pkg/user/api/oidc_handler_test.go — handler tests (B.4)

5.8 KiB Raw Blame History