Refactor OAuth token persistence and fix Resource/Audience conflation

pkg/auth/remote/doc.go

@@ -1,18 +1,28 @@
 // SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-// Package remote provides authentication handling for remote MCP servers.
+// Package remote provides authentication handling for remote MCP servers,
+// as well as general-purpose OAuth token source utilities used across the codebase.
 //
-// This package implements OAuth/OIDC-based authentication with automatic
-// discovery support for remote MCP servers. It handles:
+// # Remote MCP server authentication
+//
+// Handler.Authenticate() is the main entry point: it takes a remote URL
+// and performs all necessary discovery and authentication steps, including:
 //   - OAuth issuer discovery (RFC 8414)
 //   - Protected resource metadata (RFC 9728)
 //   - OAuth flow execution (PKCE-based)
 //   - Token source creation for HTTP transports
 //
-// The main entry point is Handler.Authenticate() which takes a remote URL
-// and performs all necessary discovery and authentication steps.
-//
 // Configuration is defined in pkg/runner.RemoteAuthConfig as part of the
 // runner's RunConfig structure.
+//
+// # General-purpose token source utilities
+//
+// These types and functions are also used outside of remote MCP auth (e.g. registry auth):
+//   - PersistingTokenSource / NewPersistingTokenSource — wraps an oauth2.TokenSource
+//     and invokes a TokenPersister callback whenever tokens are refreshed.
+//   - CreateTokenSourceFromCached — restores an oauth2.TokenSource from a cached
+//     refresh token without requiring a new interactive flow.
+//   - TokenPersistenceManager / NewTokenPersistenceManager — retrieves a cached
+//     refresh token from a secrets provider and creates a token source from it.
 package remote

pkg/auth/remote/handler.go

@@ -237,14 +237,9 @@ func (h *Handler) tryRestoreFromCachedTokens(
 	scopes []string,
 	authServerInfo *discovery.AuthServerInfo,
 ) (oauth2.TokenSource, error) {
-	// Resolve the refresh token from the secret manager
-	if h.secretProvider == nil {
-		return nil, fmt.Errorf("secret provider not configured, cannot restore cached tokens")
-	}
-
-	refreshToken, err := h.secretProvider.GetSecret(ctx, h.config.CachedRefreshTokenRef)
+	mgr, err := NewTokenPersistenceManager(h.secretProvider)
 	if err != nil {
-		return nil, fmt.Errorf("failed to retrieve cached refresh token: %w", err)
+		return nil, fmt.Errorf("secret provider not configured, cannot restore cached tokens: %w", err)
 	}
 
 	// Resolve client credentials - prefer cached DCR credentials over config
@@ -284,12 +279,16 @@ func (h *Handler) tryRestoreFromCachedTokens(
 
 	// Create token source from cached refresh token.
 	// Passes resource for RFC 8707 compliance when configured.
-	baseSource := CreateTokenSourceFromCached(
+	baseSource, err := mgr.RestoreFromCache(
+		ctx,
+		h.config.CachedRefreshTokenRef,
 		oauth2Config,
-		refreshToken,
 		h.config.CachedTokenExpiry,
 		h.config.Resource,
 	)
+	if err != nil {
+		return nil, err
+	}
 
 	// Try to get a token to verify the cached tokens are valid
 	// This will trigger a refresh since we don't have an access token