feat(auth): add TokenFetcher interface and token abstraction

[TerryHowe]

Summary

Part 2 of 3 splitting #1141 into reviewable chunks.

Extract bearer-token acquisition from auth.Client into a pluggable TokenFetcher interface:

FetchToken(ctx, TokenParams, Credential) (string, error)

Three concrete implementations land in the same file:

Type	Purpose
DistributionTokenFetcher	GET against the distribution-spec token endpoint with optional basic auth
OAuth2TokenFetcher	POST OAuth2 password / refresh_token grant
CompositeTokenFetcher	Selects between the above based on credential shape and a LegacyMode toggle — mirrors the existing in-client logic

A new optional Client.TokenFetcher field lets callers inject a custom strategy (e.g. ECR/GCR-specific token exchange) without forking the client. When nil, the built-in fallback in fetchBearerToken preserves the existing behavior, so this is a purely additive change to the public API. ForceAttemptOAuth2 is unchanged.

Why split it out

Today the bearer-token strategy is hardcoded inside Client.fetchBearerToken. Callers who need a custom strategy have to fork or wrap the whole client. With TokenFetcher, they swap in one field.

The composite implementation is also easier to test in isolation than the inline logic — see token_test.go (805 lines) which exercises the strategies without spinning up an HTTP client at all.

This will replace https://github.com/oras-project/oras-go/blob/main/registry/remote/auth/client.go#L266:L400

Test plan

• go test -mod=mod ./registry/remote/auth/... — passes (existing tests + new TokenFetcher coverage)
• token_test.go covers all three fetcher implementations independently
• client_test.go adds TestClient_Do_Bearer_CustomTokenFetcher and _Error to verify wiring
• CI on this PR

Follow-ups in the split

• PR A (feat(auth)!: flip OAuth2 default and rename ForceAttemptOAuth2 to legacyMode #1180): feat(auth)!: flip OAuth2 default and rename ForceAttemptOAuth2 to legacyMode — separate breaking change, independent of this PR
• PR C (feat(auth): add ForceBasicAuth to override Bearer challenges #1182): feat(auth): add ForceBasicAuth to override Bearer challenges — independent

Replaces #1141 together with PRs A and C.

[codecov]

Codecov Report

❌ Patch coverage is 89.13043% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.19%. Comparing base (2b84d02) to head (2dd7136).

Files with missing lines	Patch %	Lines
registry/remote/auth/token.go	88.23%	5 Missing and 5 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1181      +/-   ##
==========================================
+ Coverage   83.09%   83.19%   +0.09%     
==========================================
  Files          82       83       +1     
  Lines        5834     5926      +92     
==========================================
+ Hits         4848     4930      +82     
- Misses        605      610       +5     
- Partials      381      386       +5     

☔ View full report in Codecov by Harness.
📢 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.

[gjenkins8]

LGTM

Perhaps a common HTTP client that does the work of DistributionTokenFetcher.send and OAuth2TokenFetcher.send could be introduced (and would establish common baseline for HTTP request sending)

[gjenkins8]

(Re) LGTM

In particular, the TokenFetcher interface w/ TokenParams representing the concrete registry details enables evolving how auth tokens are retrieved over time.