Add auth fields to PUT registry endpoint, ensure offline_access scope

- Add optional auth config (issuer, client_id, audience, scopes) to
  PUT /api/v1beta/registry/default so Studio can configure registry
  auth in one call
- Default scopes to openid + offline_access when none provided
- Always include offline_access in OAuth flow scopes to ensure the
  provider returns a refresh token for persistence
- Add test instructions file for manual verification

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ChrisJBurns

pkg/api/v1/registry.go

@@ -485,29 +485,50 @@ func (rr *RegistryRoutes) updateRegistry(w http.ResponseWriter, r *http.Request)
 		return
 	}
 
-	// Process the registry update
-	responseType, err := rr.processRegistryUpdate(&req)
-	if err != nil {
-		// Check if it's a connectivity error - return 504 Gateway Timeout
-		var connErr *connectivityError
-		if errors.As(err, &connErr) {
-			http.Error(w, connErr.Error(), http.StatusGatewayTimeout)
+	// Process the registry URL/path update.
+	// Call processRegistryUpdate when source fields are present, or when no fields
+	// at all are provided (which resets the registry to defaults).
+	hasSourceFields := req.URL != nil || req.APIURL != nil || req.LocalPath != nil
+	hasSourceUpdate := hasSourceFields || req.Auth == nil
+	var responseType string
+	if hasSourceUpdate {
+		var err error
+		responseType, err = rr.processRegistryUpdate(&req)
+		if err != nil {
+			// Check if it's a connectivity error - return 504 Gateway Timeout
+			var connErr *connectivityError
+			if errors.As(err, &connErr) {
+				http.Error(w, connErr.Error(), http.StatusGatewayTimeout)
+				return
+			}
+			// Check if it's a validation error - return 502 Bad Gateway
+			if isValidationError(err) {
+				http.Error(w, err.Error(), http.StatusBadGateway)
+				return
+			}
+			// Other errors - return 400 Bad Request
+			http.Error(w, err.Error(), http.StatusBadRequest)
 			return
 		}
-		// Check if it's a validation error - return 502 Bad Gateway
-		if isValidationError(err) {
-			http.Error(w, err.Error(), http.StatusBadGateway)
+	}
+
+	// Process auth configuration if provided
+	if req.Auth != nil {
+		if err := rr.processAuthUpdate(req.Auth); err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
 			return
 		}
-		// Other errors - return 400 Bad Request
-		http.Error(w, err.Error(), http.StatusBadRequest)
-		return
 	}
 
 	// Reset the registry provider cache to pick up configuration changes
-	// Note: The config singleton is already reset by the service
 	regpkg.ResetDefaultProvider()
 
+	// If no source update was performed, resolve the current type from config
+	if responseType == "" {
+		currentType, _ := rr.getRegistryInfo()
+		responseType = string(currentType)
+	}
+
 	response := UpdateRegistryResponse{
 		Type: responseType,
 	}
@@ -530,6 +551,18 @@ func validateRegistryRequest(req *UpdateRegistryRequest) error {
 	return nil
 }
 
+// processAuthUpdate validates and applies OAuth configuration for registry auth.
+func (rr *RegistryRoutes) processAuthUpdate(authReq *UpdateRegistryAuthRequest) error {
+	if authReq.Issuer == "" || authReq.ClientID == "" {
+		return fmt.Errorf("auth.issuer and auth.client_id are required")
+	}
+	authMgr := regpkg.NewAuthManager(rr.configProvider)
+	if err := authMgr.SetOAuthAuth(authReq.Issuer, authReq.ClientID, authReq.Audience, authReq.Scopes); err != nil {
+		return fmt.Errorf("failed to configure registry auth: %w", err)
+	}
+	return nil
+}
+
 // processRegistryUpdate processes the registry update based on request type
 func (rr *RegistryRoutes) processRegistryUpdate(req *UpdateRegistryRequest) (string, error) {
 	// Handle registry reset (unset)
@@ -818,6 +851,20 @@ type UpdateRegistryRequest struct {
 	LocalPath *string `json:"local_path,omitempty"`
 	// Allow private IP addresses for registry URL or API URL
 	AllowPrivateIP *bool `json:"allow_private_ip,omitempty"`
+	// OAuth authentication configuration (optional)
+	Auth *UpdateRegistryAuthRequest `json:"auth,omitempty"`
+}
+
+// UpdateRegistryAuthRequest contains OAuth configuration fields for registry auth.
+type UpdateRegistryAuthRequest struct {
+	// OIDC issuer URL
+	Issuer string `json:"issuer"`
+	// OAuth client ID
+	ClientID string `json:"client_id"`
+	// OAuth audience (optional)
+	Audience string `json:"audience,omitempty"`
+	// OAuth scopes (optional)
+	Scopes []string `json:"scopes,omitempty"`
 }
 
 // UpdateRegistryResponse represents the response for updating a registry

test-registry-auth-serve-mode.md

@@ -0,0 +1,144 @@
+# Testing Registry Auth Serve Mode (PR 2A)
+
+## Prerequisites
+
+- Go installed
+- ToolHive repo checked out on `feat/registry-auth-serve-mode` branch
+
+## Build
+
+```bash
+go build -o ./bin/thv ./cmd/thv/
+```
+
+## Scenario A: Public registry (no auth required)
+
+This uses the default embedded registry. No auth configuration needed.
+
+### Start the server
+
+```bash
+./bin/thv config set-registry ""
+./bin/thv serve --port 18080
+```
+
+In a separate terminal, run the curl commands below.
+
+### 1. List registries
+
+```bash
+curl -s http://localhost:18080/api/v1beta/registry | python3 -m json.tool
+```
+
+Expected: `auth_status` is `"none"` and `auth_type` is `""`.
+
+```json
+{
+    "registries": [
+        {
+            "name": "default",
+            "version": "1.0.0",
+            "last_updated": "...",
+            "server_count": 79,
+            "type": "default",
+            "source": "",
+            "auth_status": "none",
+            "auth_type": ""
+        }
+    ]
+}
+```
+
+### 2. Get default registry details
+
+```bash
+curl -s http://localhost:18080/api/v1beta/registry/default | python3 -m json.tool | head -15
+```
+
+Expected: Same `auth_status`/`auth_type` fields, plus full registry contents.
+
+### 3. List servers
+
+```bash
+curl -s http://localhost:18080/api/v1beta/registry/default/servers | python3 -m json.tool | head -40
+```
+
+Expected: Array of server objects with name, description, tools, image, permissions, etc.
+
+Stop the server with Ctrl+C.
+
+## Scenario B: Stacklok internal registry (auth required)
+
+This uses the Stacklok registry which requires authentication. Without credentials configured, all registry endpoints return a structured 503 error.
+
+### Configure the registry
+
+```bash
+./bin/thv config set-registry https://toolhive-registry.stacklok.dev/registry/toolhive
+```
+
+### Start the server
+
+```bash
+./bin/thv serve --port 18080
+```
+
+### 1. List registries — expect 503
+
+```bash
+curl -s -w "\nHTTP_CODE: %{http_code}" http://localhost:18080/api/v1beta/registry
+```
+
+Expected:
+
+```
+{"code":"registry_auth_required","message":"Registry authentication required. Run 'thv registry login' to authenticate."}
+
+HTTP_CODE: 503
+```
+
+### 2. Get default registry — expect 503
+
+```bash
+curl -s -w "\nHTTP_CODE: %{http_code}" http://localhost:18080/api/v1beta/registry/default
+```
+
+Expected: Same 503 response.
+
+### 3. List servers — expect 503
+
+```bash
+curl -s -w "\nHTTP_CODE: %{http_code}" http://localhost:18080/api/v1beta/registry/default/servers
+```
+
+Expected: Same 503 response.
+
+### What Studio sees
+
+Studio receives the JSON body with `code: "registry_auth_required"`. Currently it will display the error message. Once PR 2B lands with the login endpoint, Studio can detect this code and prompt the user to authenticate.
+
+### 4. Configure OAuth (sets auth_status to "configured")
+
+Stop the server, then:
+
+```bash
+./bin/thv config set-registry-auth --issuer https://auth.example.com --client-id my-client
+./bin/thv serve --port 18080
+```
+
+```bash
+curl -s http://localhost:18080/api/v1beta/registry | python3 -m json.tool
+```
+
+Expected: `auth_status` is `"configured"` and `auth_type` is `"oauth"`. The registry still returns a 503 because no token has been obtained yet.
+
+After a successful `thv registry login` (PR 2B, not yet implemented), `auth_status` would become `"authenticated"` and the registry endpoints would return data.
+
+## Cleanup
+
+```bash
+# Reset to default embedded registry
+./bin/thv config set-registry ""
+```
+
+Stop the server with Ctrl+C.