Add CIMD document fetch/validate and extend SSRF protections

[amirejaz]

Summary

Phase 2 PR 1 of CIMD embedded AS support — closes part of #4825.

The embedded authorization server (Phase 2) will need to fetch and validate Client ID Metadata Documents when MCP clients present HTTPS URLs as client_id. This PR adds that foundation as a pure library layer with no server wiring — wiring comes in PR 2 (storage decorator) and PR 3 (config + discovery).

• FetchClientMetadataDocument fetches a CIMD document with the security controls required by the spec: HTTPS-only, 5 s timeout, 10 KB body cap, one-hop redirect limit, per-dial SSRF protection, Content-Type validation, and strict self-referential binding (client_id must exactly equal the serving URL).
• ValidateClientMetadataDocument checks required fields and allowed redirect URI schemes.
• ClientMetadataDocument struct matches draft-ietf-oauth-client-id-metadata-document fields.
• SSRF range extensions in pkg/networking: RFC6598 CGN (100.64.0.0/10) and RFC5737 documentation ranges added to the private IP block list.
• WithDisableKeepAlives on HttpClientBuilder so callers can prevent connection reuse from bypassing per-dial SSRF checks.

The SSRF check in cimd.go is implemented inline rather than via pkg/networking to preserve the oauthproto leaf-package invariant (documented in doc.go).

Type of change

• New feature (non-breaking)

Test plan

• Unit tests: go test ./pkg/oauthproto/... ./pkg/networking/... — all pass
• Fetch/validate tests cover: valid document, non-HTTPS rejection, non-200 status, 10 KB cap, Content-Type validation, application/*+json subtype, client_id mismatch, missing redirect_uris, SSRF private IP rejection
• New IP range tests: CGN and documentation ranges verified as private

Special notes for reviewers

The duplicate SSRF block list in cimd.go is intentional — see the comment referencing doc.go. If the leaf-package invariant is ever relaxed, cimdPrivateBlocks can be replaced with a call to networking.IsPrivateIP.

Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 71.42857% with 30 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.40%. Comparing base (8d22ac5) to head (9b4a77b).

Files with missing lines	Patch %	Lines
pkg/oauthproto/cimd/fetch.go	65.38%	16 Missing and 11 partials ⚠️
pkg/networking/http_client.go	25.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5320      +/-   ##
==========================================
- Coverage   68.41%   68.40%   -0.02%     
==========================================
  Files         621      622       +1     
  Lines       63278    63371      +93     
==========================================
+ Hits        43293    43349      +56     
- Misses      16757    16784      +27     
- Partials     3228     3238      +10     

☔ 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.

[Copilot]

Pull request overview

Adds foundational library support for Client ID Metadata Documents (CIMD) by introducing fetch + validation helpers in pkg/oauthproto, and extends SSRF protections in pkg/networking (additional blocked ranges + an option to disable HTTP keep-alives so per-dial SSRF checks can’t be bypassed via connection reuse).

Changes:

• Add ClientMetadataDocument model plus FetchClientMetadataDocument (HTTP fetch with guardrails) and ValidateClientMetadataDocument (field + redirect URI validation).
• Extend private/IP-block detection (CGN + RFC5737 documentation ranges + multicast) and add HttpClientBuilder.WithDisableKeepAlives.
• Add unit tests for CIMD fetch/validation behavior and for new private IP ranges.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
pkg/oauthproto/cimd.go	Adds CIMD document type, URL validation, SSRF-guarded fetcher, and document validation logic.
pkg/oauthproto/cimd_test.go	Adds tests for CIMD fetch/validation scenarios (status codes, content-type, body cap, redirect URIs, etc.).
pkg/networking/utilities.go	Extends private IP block list to include CGN + RFC5737 documentation ranges + multicast.
pkg/networking/utilities_test.go	Adds unit tests asserting the new private IP ranges are classified as private.
pkg/networking/http_client.go	Adds builder option to disable keep-alives (supports per-dial SSRF enforcement).

Comments suppressed due to low confidence (3)

pkg/oauthproto/cimd.go:313

• validateRedirectURI uses string prefix checks for loopback ("http://localhost", "http://127.0.0.1", "http://[::1]"). This can accept non-loopback hosts like "http://localhost.evil.com/callback" or "http://127.0.0.1.evil.com/callback". Parse the URI and validate scheme + host (including proper IPv6 bracket handling) to ensure only true loopback HTTP or HTTPS are allowed.

func validateRedirectURI(uri string) error {
	switch {
	case strings.HasPrefix(uri, "https://"):
		return nil
	case strings.HasPrefix(uri, "http://localhost"),
		strings.HasPrefix(uri, "http://127.0.0.1"),
		strings.HasPrefix(uri, "http://[::1]"):
		return nil

pkg/oauthproto/cimd.go:230

• Loopback addresses are explicitly allowed in the SSRF guard (!ip.IsLoopback()), meaning an HTTPS client_id whose hostname resolves to 127.0.0.1/::1 will be permitted. This contradicts the stated goal of blocking loopback/private ranges and makes localhost SSRF possible via DNS. If loopback should only be allowed for explicit loopback development URLs, gate it on the parsed URL host being loopback/localhost rather than allowing all loopback resolutions.

				// Loopback is allowed — it is already gated by the URL scheme check
				// (HTTP to loopback is explicitly permitted for development). All other
				// private ranges are rejected to prevent SSRF.
				if !ip.IsLoopback() && isPrivateForCIMD(ip) {
					return nil, fmt.Errorf("cimd: refusing connection to private address %s", ipStr)
				}

pkg/oauthproto/cimd.go:189

• Using io.LimitReader(resp.Body, maxBodyBytes) does not reliably enforce the 10KB cap: if valid JSON is fully contained within the first 10KB, the decoder will succeed and any remaining bytes will be ignored (and currently later drained). Consider limiting to maxBodyBytes+1 and returning an explicit error when the response exceeds the cap, or read with io.ReadAll using a max+1 limit.

	const maxBodyBytes = 10 * 1024
	limited := io.LimitReader(resp.Body, maxBodyBytes)
	var doc ClientMetadataDocument
	if err := json.NewDecoder(limited).Decode(&doc); err != nil {
		return nil, fmt.Errorf("failed to decode client metadata document: %w", err)
	}

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jhrozek]

I think the code itself is good, but I think we should reduce the code duplication

[jhrozek]

The FetchJSON refactor in ab8a5b8 cleaned up the duplication I was about to ask about — nice. Three small nits below, all non-blocking. Approve.