feat(auth): add TokenFetcher interface and token abstraction

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

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

Three implementations land alongside the interface:

  - 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,
                              mirroring 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.

Test coverage in token_test.go is independent of the client; two new
client_test.go cases (TestClient_Do_Bearer_CustomTokenFetcher and
_Error) exercise the wiring end-to-end.

Signed-off-by: Terry Howe <terrylhowe@gmail.com>

Author: TerryHowe

registry/remote/auth/client.go

@@ -99,6 +99,11 @@ type Client struct {
 	// Reference: https://distribution.github.io/distribution/spec/auth/oauth/#getting-a-token
 	ClientID string
 
+	// TokenFetcher is an optional custom token fetcher for bearer
+	// authentication. If nil, the built-in token-fetching logic is used
+	// (see ForceAttemptOAuth2).
+	TokenFetcher TokenFetcher
+
 	// ForceAttemptOAuth2 controls whether to follow OAuth2 with password grant
 	// instead the distribution spec when authenticating using username and
 	// password.
@@ -285,6 +290,19 @@ func (c *Client) fetchBearerToken(ctx context.Context, registry, realm, service
 	if err != nil {
 		return "", err
 	}
+
+	// Use custom TokenFetcher if provided
+	if c.TokenFetcher != nil {
+		params := TokenParams{
+			Registry: registry,
+			Realm:    realm,
+			Service:  service,
+			Scopes:   scopes,
+		}
+		return c.TokenFetcher.FetchToken(ctx, params, cred)
+	}
+
+	// Fall back to original implementation
 	if cred.AccessToken != "" {
 		return cred.AccessToken, nil
 	}

registry/remote/auth/client_test.go

@@ -3977,3 +3977,126 @@ func TestClient_fetchBasicAuth(t *testing.T) {
 		t.Errorf("incorrect error: %v, expected %v", err, ErrBasicCredentialNotFound)
 	}
 }
+
+func TestClient_Do_Bearer_CustomTokenFetcher(t *testing.T) {
+	wantToken := "custom_fetcher_token"
+	var requestCount, wantRequestCount int64
+	var successCount, wantSuccessCount int64
+	var service string
+	scope := "repository:test:pull"
+
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		atomic.AddInt64(&requestCount, 1)
+		if r.Method != http.MethodGet || r.URL.Path != "/" {
+			t.Errorf("unexpected access: %s %s", r.Method, r.URL)
+			w.WriteHeader(http.StatusNotFound)
+			return
+		}
+		header := "Bearer " + wantToken
+		if auth := r.Header.Get("Authorization"); auth != header {
+			challenge := fmt.Sprintf("Bearer realm=%q,service=%q,scope=%q", "https://auth.example.com/token", service, scope)
+			w.Header().Set("Www-Authenticate", challenge)
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+		atomic.AddInt64(&successCount, 1)
+	}))
+	defer ts.Close()
+	uri, err := url.Parse(ts.URL)
+	if err != nil {
+		t.Fatalf("invalid test http server: %v", err)
+	}
+	service = uri.Host
+
+	// Custom token fetcher that always returns a fixed token.
+	customFetcher := &mockTokenFetcherForClient{token: wantToken}
+
+	client := &Client{
+		CredentialFunc: func(ctx context.Context, reg string) (credentials.Credential, error) {
+			return credentials.Credential{
+				Username: "user",
+				Password: "pass",
+			}, nil
+		},
+		TokenFetcher: customFetcher,
+	}
+
+	req, err := http.NewRequest(http.MethodGet, ts.URL, nil)
+	if err != nil {
+		t.Fatalf("failed to create test request: %v", err)
+	}
+	resp, err := client.Do(req)
+	if err != nil {
+		t.Fatalf("Client.Do() error = %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Errorf("Client.Do() = %v, want %v", resp.StatusCode, http.StatusOK)
+	}
+	if wantRequestCount += 2; requestCount != wantRequestCount {
+		t.Errorf("unexpected number of requests: %d, want %d", requestCount, wantRequestCount)
+	}
+	if wantSuccessCount++; successCount != wantSuccessCount {
+		t.Errorf("unexpected number of successful requests: %d, want %d", successCount, wantSuccessCount)
+	}
+
+	// Verify the custom fetcher was actually called.
+	if !customFetcher.called {
+		t.Error("custom TokenFetcher was not called")
+	}
+}
+
+func TestClient_Do_Bearer_CustomTokenFetcher_Error(t *testing.T) {
+	var service string
+	scope := "repository:test:pull"
+
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		challenge := fmt.Sprintf("Bearer realm=%q,service=%q,scope=%q", "https://auth.example.com/token", service, scope)
+		w.Header().Set("Www-Authenticate", challenge)
+		w.WriteHeader(http.StatusUnauthorized)
+	}))
+	defer ts.Close()
+	uri, err := url.Parse(ts.URL)
+	if err != nil {
+		t.Fatalf("invalid test http server: %v", err)
+	}
+	service = uri.Host
+
+	fetcherErr := errors.New("custom fetcher error")
+	client := &Client{
+		CredentialFunc: func(ctx context.Context, reg string) (credentials.Credential, error) {
+			return credentials.Credential{
+				Username: "user",
+				Password: "pass",
+			}, nil
+		},
+		TokenFetcher: &mockTokenFetcherForClient{err: fetcherErr},
+	}
+
+	req, err := http.NewRequest(http.MethodGet, ts.URL, nil)
+	if err != nil {
+		t.Fatalf("failed to create test request: %v", err)
+	}
+	_, err = client.Do(req)
+	if err == nil {
+		t.Fatal("Client.Do() expected error, got nil")
+	}
+	if !strings.Contains(err.Error(), "custom fetcher error") {
+		t.Errorf("Client.Do() error = %v, want error containing %q", err, "custom fetcher error")
+	}
+}
+
+// mockTokenFetcherForClient is a test helper that returns a fixed token and
+// tracks whether it was called.
+type mockTokenFetcherForClient struct {
+	token  string
+	err    error
+	called bool
+}
+
+func (m *mockTokenFetcherForClient) FetchToken(ctx context.Context, params TokenParams, cred credentials.Credential) (string, error) {
+	m.called = true
+	if m.err != nil {
+		return "", m.err
+	}
+	return m.token, nil
+}