2 Commits

Author	SHA1	Message	Date
shankar0123	56e2ea1ad7	docs: v2.1.0 release polish — strip internal bundle/phase tags, update status for OIDC ship ... README: - Rewrite Status block: drop the stale 'federated identity not yet shipped' line; flag v2.1.0 OIDC + sessions + back-channel logout + break-glass as early-access; encourage GitHub issues for IdP rough edges. (A1 framing — keep early-access umbrella, no SAML/WebAuthn/JIT roadmap teaser.) - Add OIDC SSO bullet to 'What it does' covering per-IdP runbooks, group-claim → role mapping, AES-256-GCM client_secret encryption, JWKS auto-refresh, PKCE-S256, RFC 9700 §4.7.1 pre-login binding, RFC 9207 iss check, __Host- cookies, CSRF rotation, idle+absolute expiry, BCL, break-glass admin. - Update Security paragraph: three auth paths (API keys / OIDC / break-glass), HMAC-signed sessions, CSRF rotation, RFC OIDC BCL. - Correct CI coverage thresholds against .github/coverage-thresholds.yml (service 70%, handler 75%, crypto 88%, auth packages 85-95%); 'static analysis' replaces the inflated '11 linters' claim (actual count is 4 active). Docs B3 sweep — strip operator-facing 'Bundle N' / 'Phase N' tags: - docs/operator/auth-threat-model.md — rewrite intro; rename 5 H2 sections (API-key + RBAC defenses / OIDC + sessions + break-glass defenses / OIDC + sessions threat catalogue / Closed federated- identity threats / Future-work threats); clean ~12 H3/prose hits. - docs/operator/rbac.md — strip Bundle 1 framing from intro, scope_id deferral note, MCP tools section, day-0 bootstrap, and 'Where to look next'. - docs/operator/auth-benchmarks.md — drop 'Phase 14' framing from title intro, hardware floor caption, result table caption, methodology, and pre-merge audit section. - docs/operator/security.md — already cleaned earlier this session (RBAC / day-0 / approval-bypass / OIDC federation / sessions / OIDC first-admin / break-glass H3s). - docs/operator/oidc-runbooks/{index,keycloak,authentik,okta, azure-ad}.md — strip Auth Bundle 2 framing + Phase 10/3/4 references; replace with feature-name prose. - docs/operator/legacy-clients-tls-1.2.md — drop Bundle F / M-023 audit-reference framing; keep CWE-326. - docs/operator/database-tls.md — drop Bundle B / M-018 framing from intro + Helm section. - docs/operator/runbooks/disaster-recovery.md — drop 'Production hardening II Phase 10' status callout. - docs/migration/oidc-enable.md — retitle 'Enable OIDC SSO'; strip Bundle 1/2 framing from prereqs, troubleshooting, related docs; update __Host- cookie callout from 'audit MED-14' to v2.1.0-BREAKING. - docs/migration/api-keys-to-rbac.md — strip Bundle 1 framing from intro, migration table, IsAdmin section, and cross-references. - docs/migration/acme-from-cert-manager.md — strip residual 'Phase 5' tags from cert-manager integration test references. - docs/reference/configuration.md — retitle Auth section. - docs/reference/profiles.md — strip Bundle 1 Phase 9 framing from RequiresApproval section + Related list. - docs/reference/auth-standards-implemented.md — rewrite intro (API-key + RBAC + OIDC + sessions + back-channel logout + break-glass); rename 'Bundle 1 (RBAC) standards covered separately' H2; clean per-row Phase references. - docs/README.md — rewrite nav-table entries to drop Bundle 1/2 parentheticals; retitle 'Enable OIDC SSO' migration entry. No code or test changes; pure operator-facing prose polish for the v2.1.0 tag.	2026-05-11 16:54:07 +00:00
shankar0123	9b6294e83d	auth-bundle-2 Phase 14: session + OIDC validation benchmarks (steady-state + cold paths) + auth-benchmarks.md operator doc + Makefile targets ... Closes Phase 14 of cowork/auth-bundle-2-prompt.md. Ships four benchmarks producing four numbers + the operator-doc table; three default-tag benchmarks runnable on every CI runner, the fourth (cold-cache OIDC) runnable on operator-side Docker hosts via the new make target. Files ===== internal/auth/session/bench_test.go (NEW): * BenchmarkSession_SteadyState (target p99 < 1ms; measured 5µs). Warm in-memory repo + warm session row. Pure CPU: parseCookie + HMAC verify + map lookup + sentinel checks. * BenchmarkSession_ColdProcess (target p99 < 10ms; measured 7.1ms). Same pipeline but with a configurable per-call delay simulating a 1ms Postgres RTT on each repo call. Two repo calls per Validate (signing-key fetch + session-row fetch) = 2ms minimum; Go time.Sleep granularity adds ~1-2ms jitter. Documented why testcontainers Postgres isn't viable inside b.N: 30+ second container boot incompatible with per-iteration timing. * slowSessionRepo + slowKeyRepo wrappers add the per-call delay via time.Sleep; they delegate to the existing in-memory stubs. * reportPercentiles helper sorts + reports p50/p95/p99/max via b.ReportMetric (Go testing.B doesn't surface percentiles natively). internal/auth/oidc/bench_test.go (NEW): * BenchmarkOIDC_SteadyState (target p99 < 5ms; measured 1.5ms). Drives full HandleCallback against an in-process mockIdP (httptest.Server localhost loopback). Pre-warmed JWKS cache via RefreshKeys at setup. Pipeline: pre-login consume + state compare + token exchange (localhost ~50-200µs) + go-oidc Verify (RSA-2048 sig verify + alg pin) + service-layer iss/ aud/azp/at_hash/exp/iat/nonce re-checks + group-claim resolution + group→role mapping + user upsert + session mint. * The localhost-loopback /token call adds ~100-500µs of TCP overhead vs pure crypto; the prompt's "no network calls" steady-state framing accommodates this since the localhost loopback is the closest practical proxy for a same-region IdP /token call (which adds 5-15ms in production). internal/auth/oidc/bench_keycloak_test.go (NEW, //go:build integration): * BenchmarkOIDC_ColdCache (target p99 < 200ms; operator-runs). Drives RefreshKeys against a live Keycloak container from the Phase 10 testfixtures harness. Each iteration evicts the in-process cache + re-fetches discovery + re-fetches JWKS over real HTTP + re-runs the IdP-downgrade-attack defense. * Network-bounded: the cold path is dominated by HTTPS RTT to the IdP discovery endpoint, NOT crypto. The 200ms cap accommodates a geographically-distant IdP (~150ms RTT) plus the in-process JWKS fetch + downgrade-defense logic (~5ms locally). * Reuses the sharedKeycloak fixture from integration_keycloak_test.go (Phase 10) so the benchmark doesn't pay the 60-90s container boot cost separately. Skips with a clear message if invoked without the integration test setup. * Reports p50/p95/p99/max in MILLISECONDS (vs the microsecond-granularity steady-state benchmarks) since the cold path is two orders of magnitude slower. internal/auth/oidc/service_test.go (MODIFIED): * Refactored newMockIdP(t *testing.T) to delegate to a new newMockIdPWithTB(t testing.TB) sibling. Standard Go pattern for sharing test fixtures between *testing.T and *testing.B. No behavior change for existing service_test.go tests; the benchmark file in bench_test.go calls newMockIdPWithTB(b) to get the same fixture. docs/operator/auth-benchmarks.md (NEW): * Result table with all four benchmarks + targets + measured numbers + status markers. Four-row matrix for the default-tag benchmarks; the fourth row (cold-cache) is operator-recorded with an empty cell waiting for the first Docker-equipped run. * Hardware floor section pinning the 4 vCPU / 8 GiB RAM / Postgres 16 / Go 1.25 baseline. GitHub-hosted Ubuntu runners satisfy this; operators on weaker hardware re-record. * "What each benchmark covers (and what it doesn't)" section per benchmark, distinguishing the warm steady-state pipeline from the cold path's network-bounded budget. * "Cold-cache OIDC: how to run" subsection documenting the make target + the test+benchmark coupling needed to populate sharedKeycloak. Operator-recorded baseline table seeded empty for first runs. * "Why the cold path is bounded by network latency, not crypto" section explaining the budget breakdown: - TCP handshake (1 RTT) - TLS 1.3 handshake (1-2 RTTs) - 2 HTTPS GETs (discovery + JWKS, 1 RTT each) - In-process crypto on the certctl side (~5-10ms total) So the 200ms cap is operator-checkable: real measurement > 200ms means the IdP is slow OR network congestion OR DNS issues — the diagnosis is upstream of certctl. Real measurement < 200ms means the IdP is on a fast same-region link. * Methodology section pinning the per-iteration timing capture + sort + percentile-extract approach. * Pre-merge audit section for the Phase 14 exit gate: four benchmarks ran, four numbers recorded, steady-state targets met, cold path is operator-runnable + measurably-bounded. Makefile (MODIFIED): * Added `make benchmark-auth` (default-tag, runs three of four benchmarks at 2000 samples each). * Added `make benchmark-auth-coldcache` (integration-tagged, runs OIDC cold-cache against live Keycloak; requires Docker). * Both targets carry explanatory comment blocks. docs/README.md (MODIFIED): * Added the auth-benchmarks.md doc to the Operator nav table alongside performance-baselines.md. Measured baselines at Phase 14 close (linux/arm64, 4 vCPU) ========================================================== BenchmarkSession_SteadyState p99 = 5µs (target < 1ms) ✓ 200× under BenchmarkSession_ColdProcess p99 = 7.1ms (target < 10ms) ✓ BenchmarkOIDC_SteadyState p99 = 1.5ms (target < 5ms) ✓ 3× under BenchmarkOIDC_ColdCache operator-runs (Docker required) Verification ============ * gofmt -l on three new bench files: clean. * go vet ./internal/auth/session/... ./internal/auth/oidc/...: clean (default tag). * go vet -tags integration ./internal/auth/oidc/...: clean (integration tag covers the bench_keycloak_test.go file). * go test -short -count=1 across all 5 OIDC + session packages: green; the bench_*_test.go files compile but don't run under -short (testing.Short() guards + benchmarks are not selected by -run pattern). * All three runnable benchmarks executed and produce the numbers above; recorded in auth-benchmarks.md.	2026-05-10 16:51:28 +00:00