Extract DCR resolver into pkg/auth/dcr

[tgrunnagle]

Summary

• Why: Issue Consolidate the two RFC 7591 DCR client implementations into pkg/auth/dcr #5145 calls for consolidating two parallel RFC 7591 Dynamic Client Registration (DCR) implementations (pkg/authserver/runner/dcr.go and pkg/auth/discovery::PerformOAuthFlow) into a single shared pkg/auth/dcr package, so review-derived behaviours (S256 PKCE gate, RFC 7591 §3.2.1 expiry refetch, redirect refusal, panic recovery, singleflight) cannot diverge between the embedded authserver and the CLI flow as future consumers land. The full migration is too large for a single PR, so this slice (sub-issue 4a) does the package extraction and migrates the embedded authserver only.
• What: Extracts the DCR resolver and credential store from pkg/authserver/runner into a new pkg/auth/dcr package and migrates EmbeddedAuthServer to consume it. File moves use git mv so the diff renders as renames rather than delete+add. Public symbols are renamed to drop the redundant DCR prefix on packagisation (e.g., DCRResolution → dcr.Resolution, DCRCredentialStore → dcr.CredentialStore, resolveDCRCredentials → dcr.ResolveCredentials). Adds a parallel TestResolveSecret suite mirroring the runner-package twin so any future drift between the two resolveSecret copies fails CI.

Closes #5220 (sub-issue 4a). Part of #5145 — does not close the parent. Sibling sub-issue #5219 (4b — CLI flow migration in pkg/auth/discovery::PerformOAuthFlow) closes #5145 when it lands; AC#1, AC#3, and AC#4 of the parent depend on it.

Stacking

This branch is stacked on PR #5196 (dcr-3c_issue_5185 — "Wire persistent DCRCredentialStore into EmbeddedAuthServer"), which is itself stacked on PRs #5186 and #5195. The earlier commits on this branch (c0fed523 through 781a0b97) implement sub-issues #5183 / #5184 / #5185 (the persistent DCR store and Redis backend) and are shown for context only — review against PR #5196 once it merges, or review the two commits unique to this branch in isolation:

• df84256f Extract DCR resolver into pkg/auth/dcr
• 633ed9ed Address code review feedback

Type of change

• Refactoring (no behavior change)

Test plan

• Unit tests (task test) — go test -count=1 -race ./pkg/auth/dcr/... ./pkg/authserver/... all pass
• Linting (task lint-fix) — 0 issues
• License check (task license-check) — clean

Changes

File	Change
pkg/auth/dcr/resolver.go	Renamed from pkg/authserver/runner/dcr.go; public symbols renamed to drop the DCR prefix; package doc updated with a # Concurrency section documenting the process-global singleflight; new flightKeyOf(Key) helper makes the canonical key shape inspectable; endpointsFromMetadata gains a defensive nil check and an oauthproto contract note.
pkg/auth/dcr/store.go	Renamed from pkg/authserver/runner/dcr_store.go; constructors renamed (NewInMemoryStore, NewStorageBackedStore); type renamed to CredentialStore.
pkg/auth/dcr/resolver_test.go	Renamed from pkg/authserver/runner/dcr_test.go; updated for new package boundary and renamed symbols.
pkg/auth/dcr/store_test.go	Renamed from pkg/authserver/runner/dcr_store_test.go; updated for new package boundary.
pkg/auth/dcr/secret_test.go	New parallel resolveSecret suite that mirrors the runner-package twin's observable contract so future drift between the two duplicated helpers fails CI on at least one side.
pkg/authserver/runner/embeddedauthserver.go	Migrated to consume pkg/auth/dcr; doc comments on buildUpstreamConfigs and DCRStore() updated to use the new public names.
pkg/authserver/runner/embeddedauthserver_test.go	Updated import paths and constructor names for the moved types.

Does this introduce a user-facing change?

No. This is an internal refactor. The embedded authserver's externally-observable DCR behaviour (registration, caching, error reporting, structured logging, expiry refetch, S256 gating) is unchanged.

Implementation plan

Approved implementation plan

Sub-issue 4a (#5220) of #5145 — extract the resolver into pkg/auth/dcr and migrate the embedded authserver only. Defer the pkg/auth/discovery::PerformOAuthFlow migration to sub-issue 4b (#5219) so this slice stays under the 400-line / 10-file PR-size limit.

Profile-neutral input shape: the package's API still takes embedded-authserver types directly. Designing a profile-neutral input type with only one consumer in hand would be speculative; the right design moment is when 4b lands the CLI flow as the second consumer. The package doc comment in pkg/auth/dcr/resolver.go calls this coupling out explicitly and labels the profile-agnostic framing as a target state for 4b rather than the current API shape.

Duplication of resolveSecret: deliberately duplicated across pkg/authserver/runner and pkg/auth/dcr because the DCR package must stay reachable-from-runner-but-not-back. Promoting to a shared helper is deferred until 4b lands a third call site. Drift between the two copies is guarded by parallel test suites with identical observable contracts.

Special notes for reviewers

• Why renames, not delete+add: file moves use git mv so the diff renders as renames. The percentage similarity in git log --stat --follow reflects that the bulk of the move is mechanical and the substantive deltas are confined to (a) the package doc rewrite at the top of resolver.go, (b) the flightKeyOf extraction and singleflight comment, (c) the endpointsFromMetadata nil guard, and (d) the import/symbol rename sweep in embeddedauthserver.go.
• Singleflight is process-global, not per-instance: documented at the package surface and on the dcrFlight var. The cross-consumer caveat ("third consumer with colliding redirect URI" failure mode) is named explicitly so the next migration cannot silently re-introduce a collision.
• Acceptance criteria status against Consolidate the two RFC 7591 DCR client implementations into pkg/auth/dcr #5145 (as per the commit message of df84256f):
  • AC#1 (pkg/auth/dcr exists, exports a stateful resolver, consumed by both call sites): partially met — package exists and is consumed by EmbeddedAuthServer. CLI flow migration is sub-issue 4b (Migrate CLI OAuth flow to pkg/auth/dcr resolver #5219).
  • AC#2 (stateless RFC 7591 helpers in pkg/oauthproto): met (already satisfied before this PR).
  • AC#3 (no direct oauthproto.RegisterClientDynamically calls outside pkg/auth/dcr): not yet met — pkg/auth/discovery still calls it. Resolved by sub-issue 4b (Migrate CLI OAuth flow to pkg/auth/dcr resolver #5219).
  • AC#4 (review-property behaviours apply to CLI flow): not yet met — same dependency on 4b (Migrate CLI OAuth flow to pkg/auth/dcr resolver #5219).

[codecov]

Codecov Report

❌ Patch coverage is 71.42857% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.17%. Comparing base (9211a36) to head (cf6e17c).
⚠️ Report is 25 commits behind head on main.

Files with missing lines	Patch %	Lines
pkg/auth/dcr/resolver.go	72.50%	8 Missing and 3 partials ⚠️
pkg/auth/dcr/store.go	75.00%	1 Missing and 1 partial ⚠️
pkg/authserver/runner/embeddedauthserver.go	71.42%	1 Missing and 1 partial ⚠️
pkg/authserver/server/handlers/dcr.go	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5198      +/-   ##
==========================================
+ Coverage   67.91%   68.17%   +0.25%     
==========================================
  Files         610      618       +8     
  Lines       62522    63146     +624     
==========================================
+ Hits        42464    43049     +585     
- Misses      16879    16885       +6     
- Partials     3179     3212      +33     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tgrunnagle]

Multi-Agent Consensus Review

Agents consulted: api-design, concurrency/refactor, security, test-quality, documentation, cross-cutting (codex skipped — CLI not installed)

Consensus Summary

#	Finding	Score	Severity	Action
1	NewInMemoryStore returns store whose cleanup goroutine cannot be stopped	9/10	MEDIUM	Fix
2	pkg/authserver/storage/types.go "Converter contract" doc points at deleted files/types	9/10	MEDIUM	Fix (out-of-diff)
3	dcrFlight doc names EmbeddedAuthServer.dcrStore field that no longer exists post-#5196	8/10	MEDIUM	Fix
4	Drift-guard cross-reference is one-way — runner-package twin lacks pointer back	8/10	MEDIUM	Fix
5	NewStorageBackedStore accepts nil backend silently; panics on first call	7/10	MEDIUM	Fix
6	SanitizeErrorForLog exported as a generic-looking URL sanitiser, only handles http(s)	8/10	LOW	Discuss
7	Stale path pkg/authserver/runner/dcr.go in handlers/dcr.go:109 comment	7/10	LOW	Fix (out-of-diff)
8	Package doc lists *authserver.DCRUpstreamConfig as parameter type; no exported function takes it	7/10	LOW	Fix
9	flightKeyOf doc cites RFC 6749 §3.3 (scope tokens) for the ScopesHash hex-digest field	7/10	LOW	Fix
10	Stale "DCRKey" mentions in embeddedauthserver_test.go comments and assertion messages	7/10	LOW	Fix
11	Singleflight global state will become a cross-consumer hazard once 4b lands	7/10	LOW	Discuss
12	dcr.resolveSecret has zero production callers; #nosec G304 staged ahead of caller	7/10	LOW	Discuss

Overall

This is a clean refactor that extracts the DCR resolver from pkg/authserver/runner into a new pkg/auth/dcr package, with public-symbol renames on packagisation. All reviewable behaviours — S256 PKCE gate, redirect refusal, RFC 7591 §3.2.1 expiry refetch, panic recovery, package-global singleflight semantics, URL log sanitisation — are preserved across the move and verified case-by-case by the specialist agents. The only genuinely new code in the diff is flightKeyOf (extraction of an inlined string concatenation, byte-identical output) and a defensive nil-guard in endpointsFromMetadata (catches a hypothetical oauthproto contract regression). Six specialist agents reviewed in parallel; no specialist dismissed another's concern in a way that triggered conflict resolution.

The 12 surviving consensus findings split between three buckets: (a) out-of-diff documentation debt — the rename sweep missed pkg/authserver/storage/types.go and pkg/authserver/server/handlers/dcr.go, both of which still name pre-rename paths or types; (b) constructor-validation hardening for NewInMemoryStore (resource leak — the cleanup goroutine cannot be stopped through the returned interface) and NewStorageBackedStore (silent nil acceptance); (c) forward-looking concerns for sub-issue 4b — the package-global singleflight, the duplicated resolveSecret with no production caller in this PR, and the SanitizeErrorForLog export of a function that reads as generic but only handles http(s).

None of the findings are blocking. The PR is in DRAFT status which is consistent with this state. Recommendation is COMMENT — the bucket-(a) and bucket-(b) items are easy to address in this PR (small, mechanical); bucket-(c) items are reasonable to defer to 4b with explicit tracking links.

Out-of-diff documentation debt

Three items live outside the PR's diff and need to be pulled in (or filed as a follow-up explicitly linked from this PR):

• pkg/authserver/storage/types.go:235-243 — DCRCredentials "Converter contract" doc names pkg/authserver/runner/dcr_store.go, *DCRResolution, and pkg/authserver/runner/dcr_store_test.go. After this PR, the converters live in pkg/auth/dcr/store.go and the test in pkg/auth/dcr/store_test.go. Update those three references to the new paths and to *dcr.Resolution. (Finding #2, MEDIUM)
• pkg/authserver/server/handlers/dcr.go:109 — comment names pkg/authserver/runner/dcr.go. The resolver now lives at pkg/auth/dcr/resolver.go. (Finding #7, LOW)
• pkg/authserver/runner/embeddedauthserver_test.go:289-374 — TestResolveSecret and TestResolveSecretWithEnvVar should carry a doc comment naming the new pkg/auth/dcr/secret_test.go twin so a future bug fix on the runner side has a proximate hint that the dcr-side parallel test must be updated too. The dcr-side comment already names the runner-side twin; the back-pointer is missing. (Inline comment on the dcr-side at secret_test.go:17 discusses this further.) (Finding #4, MEDIUM)

Items to keep in mind for sub-issue 4b

Three of the LOW findings are forward-looking and become more expensive once 4b lands the CLI flow:

• The package-global singleflight.Group will be shared across both consumers. Consider including a consumer identifier in the flight key now (cheap) or filing a tracking issue.
• dcr.resolveSecret has no production caller in this PR — either defer to 4b or extract into a shared helper (pkg/auth/secretref or similar) in this PR with both consumers migrated.
• SanitizeErrorForLog is exported as a generic-looking URL sanitiser but only handles http(s); a future caller wrapping a redis://user:pass@… error would silently leak credentials. Tighten the doc comment, move the helper to a small shared package, or keep it unexported behind a narrower SanitizeDCRError wrapper.

What's good

All specialists confirmed the refactor preserves observable behaviour. The rename sweep is exhaustive within the 9 diffed files (the misses are in three external files). flightKeyOf produces byte-identical output to the inlined concatenation. Singleflight semantics, panic recovery, and t.Cleanup placements are correct. The new defensive nil-guard in endpointsFromMetadata is well-documented and turns a future contract regression into a clean error rather than a nil-deref panic. The drift-guard tests for resolveSecret are observably equivalent to the runner-package twin (case-by-case audit). 25+ NO-ISSUES verifications across the specialists are recorded in the local review.

---

Generated with Claude Code

[tgrunnagle]

Addressing the two out-of-diff documentation-debt findings from the review body:

• Finding Do we want the container monitor? #2 — pkg/authserver/storage/types.go DCRCredentials Converter contract doc named the deleted pkg/authserver/runner/dcr_store.go path and *DCRResolution type. Fixed in 29c751a (paths updated to pkg/auth/dcr/store.go and pkg/auth/dcr/store_test.go; type updated to *dcr.Resolution).
• Finding Create proxy subcommand #7 — pkg/authserver/server/handlers/dcr.go:109 named the deleted pkg/authserver/runner/dcr.go path. Fixed in the same commit (updated to pkg/auth/dcr/resolver.go).

Both files were outside the original PR diff; pulling them in here rather than filing a follow-up since they are mechanical rename-sweep misses and small enough to live alongside the doc-sweep commit.

[jhrozek]

Approving. Solid refactor; the move preserves the security defences and the tests pin them.

One non-blocking suggestion inline on ConsumeResolution about the caller-mutation pattern. Fine to address in a follow-up before 4b lands.