Registry policy gates with type-safe configs (#4711)

Separate runner and registry policy gates with type-safe configs

The previous commit extracted PolicyGate to a shared pkg/policy package,
but this mixed runner and registry concerns in a single interface and
forced CheckCreateServer to use `any` to avoid a circular dependency.

Instead, keep each policy gate in the package it guards:
- pkg/runner keeps its original PolicyGate with type-safe *RunConfig
- pkg/registry gets a new PolicyGate with CheckUpdateRegistry and
  CheckDeleteRegistry, each receiving a dedicated config struct
  (UpdateRegistryConfig, DeleteRegistryConfig) that both CLI and API
  callers populate with the information available at their call site

The registry gate uses sync.RWMutex (read-heavy, write-once pattern),
NoopPolicyGate as the default (no separate allowAllGate), and exports
SnapshotPolicyGate for test cleanup across packages.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: aponcedeleonch

cmd/thv/app/config.go

@@ -7,6 +7,7 @@ import (
 	"errors"
 	"fmt"
 	"os"
+	"strings"
 
 	"github.com/spf13/cobra"
 
@@ -180,6 +181,19 @@ func unsetCACertCmdFunc(_ *cobra.Command, _ []string) error {
 func setRegistryCmdFunc(cmd *cobra.Command, args []string) error {
 	input := args[0]
 
+	cfg := &registry.UpdateRegistryConfig{
+		AllowPrivateIP: allowPrivateRegistryIp,
+		HasAuth:        registryAuthIssuer != "" && registryAuthClientID != "",
+	}
+	if strings.HasPrefix(input, "http://") || strings.HasPrefix(input, "https://") {
+		cfg.URL = input
+	} else {
+		cfg.LocalPath = input
+	}
+	if err := registry.ActivePolicyGate().CheckUpdateRegistry(cmd.Context(), cfg); err != nil {
+		return err
+	}
+
 	// Always clear existing auth when changing registry (security: prevents
 	// tokens from being sent to the wrong server).
 	provider := config.NewDefaultProvider()
@@ -236,7 +250,13 @@ func getRegistryCmdFunc(_ *cobra.Command, _ []string) error {
 	return nil
 }
 
-func unsetRegistryCmdFunc(_ *cobra.Command, _ []string) error {
+func unsetRegistryCmdFunc(cmd *cobra.Command, _ []string) error {
+	if err := registry.ActivePolicyGate().CheckDeleteRegistry(cmd.Context(), &registry.DeleteRegistryConfig{
+		Name: "default",
+	}); err != nil {
+		return err
+	}
+
 	service := registry.NewConfigurator()
 	err := service.UnsetRegistry()
 	if err != nil {

docs/server/docs.go

@@ -494,6 +494,7 @@ func (rr *RegistryRoutes) getRegistry(w http.ResponseWriter, r *http.Request) {
 //		@Param			body	body		UpdateRegistryRequest	true	"Registry configuration"
 //		@Success		200		{object}	UpdateRegistryResponse
 //		@Failure		400		{string}	string	"Bad Request"
+//		@Failure		403		{string}	string	"Forbidden - blocked by policy"
 //		@Failure		404		{string}	string	"Not Found"
 //		@Failure		502		{string}	string	"Bad Gateway - Registry validation failed"
 //		@Failure		504		{string}	string	"Gateway Timeout - Registry unreachable"
@@ -519,6 +520,11 @@ func (rr *RegistryRoutes) updateRegistry(w http.ResponseWriter, r *http.Request)
 		return
 	}
 
+	if err := regpkg.ActivePolicyGate().CheckUpdateRegistry(r.Context(), updateRegistryConfigFromRequest(&req)); err != nil {
+		http.Error(w, err.Error(), http.StatusForbidden)
+		return
+	}
+
 	// Process the registry URL/path update.
 	var responseType string
 	registryType, err := rr.processRegistryUpdate(&req)
@@ -588,6 +594,27 @@ func validateRegistryRequest(req *UpdateRegistryRequest) error {
 	return nil
 }
 
+// updateRegistryConfigFromRequest builds an UpdateRegistryConfig from the
+// parsed API request for policy evaluation.
+func updateRegistryConfigFromRequest(req *UpdateRegistryRequest) *regpkg.UpdateRegistryConfig {
+	cfg := &regpkg.UpdateRegistryConfig{
+		HasAuth: req.Auth != nil,
+	}
+	if req.URL != nil {
+		cfg.URL = *req.URL
+	}
+	if req.APIURL != nil {
+		cfg.APIURL = *req.APIURL
+	}
+	if req.LocalPath != nil {
+		cfg.LocalPath = *req.LocalPath
+	}
+	if req.AllowPrivateIP != nil {
+		cfg.AllowPrivateIP = *req.AllowPrivateIP
+	}
+	return cfg
+}
+
 // processAuthUpdate validates and applies OAuth configuration for registry auth.
 func (rr *RegistryRoutes) processAuthUpdate(ctx context.Context, authReq *UpdateRegistryAuthRequest) error {
 	if authReq.Issuer == "" || authReq.ClientID == "" {
@@ -654,11 +681,19 @@ func (rr *RegistryRoutes) processRegistryUpdate(req *UpdateRegistryRequest) (str
 //		@Produce		json
 //		@Param			name	path		string	true	"Registry name"
 //		@Success		204	{string}	string	"No Content"
+//		@Failure		403	{string}	string	"Forbidden - blocked by policy"
 //		@Failure		404	{string}	string	"Not Found"
 //		@Router			/api/v1beta/registry/{name} [delete]
 func (*RegistryRoutes) removeRegistry(w http.ResponseWriter, r *http.Request) {
 	name := chi.URLParam(r, "name")
 
+	if err := regpkg.ActivePolicyGate().CheckDeleteRegistry(r.Context(), &regpkg.DeleteRegistryConfig{
+		Name: name,
+	}); err != nil {
+		http.Error(w, err.Error(), http.StatusForbidden)
+		return
+	}
+
 	// Cannot remove the default registry
 	if name == defaultRegistryName {
 		http.Error(w, "Cannot remove the default registry", http.StatusBadRequest)

docs/server/swagger.json

@@ -6,6 +6,7 @@ package v1
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"net/http"
 	"net/http/httptest"
 	"os"
@@ -345,3 +346,92 @@ func TestRegistryAPI_PutEndpoint(t *testing.T) {
 		})
 	}
 }
+
+// denyRegistryGate is a test helper that blocks all registry mutations.
+type denyRegistryGate struct {
+	registry.NoopPolicyGate
+	err error
+}
+
+func (g *denyRegistryGate) CheckUpdateRegistry(_ context.Context, _ *registry.UpdateRegistryConfig) error {
+	return g.err
+}
+
+func (g *denyRegistryGate) CheckDeleteRegistry(_ context.Context, _ *registry.DeleteRegistryConfig) error {
+	return g.err
+}
+
+//nolint:paralleltest // Mutates global registry policy gate singleton
+func TestUpdateRegistry_BlockedByPolicyGate(t *testing.T) {
+	original := registry.ActivePolicyGate()
+	t.Cleanup(func() { registry.RegisterPolicyGate(original) })
+
+	sentinel := errors.New("[ToolHive Policy] Registry is managed by organization policy")
+	registry.RegisterPolicyGate(&denyRegistryGate{err: sentinel})
+
+	provider, cleanup := CreateTestConfigProvider(t, nil)
+	defer cleanup()
+	routes := NewRegistryRoutesWithProvider(provider)
+
+	body := `{"url":"https://example.com/registry.json"}`
+	req := httptest.NewRequest(http.MethodPut, "/default", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	rctx := chi.NewRouteContext()
+	rctx.URLParams.Add("name", "default")
+	req = req.WithContext(context.WithValue(req.Context(), chi.RouteCtxKey, rctx))
+
+	w := httptest.NewRecorder()
+	routes.updateRegistry(w, req)
+
+	assert.Equal(t, http.StatusForbidden, w.Code, "Blocked PUT should return 403")
+	assert.Contains(t, w.Body.String(), "organization policy")
+}
+
+//nolint:paralleltest // Mutates global registry policy gate singleton
+func TestRemoveRegistry_BlockedByPolicyGate(t *testing.T) {
+	original := registry.ActivePolicyGate()
+	t.Cleanup(func() { registry.RegisterPolicyGate(original) })
+
+	sentinel := errors.New("[ToolHive Policy] Registry is managed by organization policy")
+	registry.RegisterPolicyGate(&denyRegistryGate{err: sentinel})
+
+	routes := &RegistryRoutes{}
+
+	req := httptest.NewRequest(http.MethodDelete, "/default", nil)
+	rctx := chi.NewRouteContext()
+	rctx.URLParams.Add("name", "default")
+	req = req.WithContext(context.WithValue(req.Context(), chi.RouteCtxKey, rctx))
+
+	w := httptest.NewRecorder()
+	routes.removeRegistry(w, req)
+
+	assert.Equal(t, http.StatusForbidden, w.Code, "Blocked DELETE should return 403")
+	assert.Contains(t, w.Body.String(), "organization policy")
+}
+
+//nolint:paralleltest // Mutates global registry policy gate singleton
+func TestUpdateRegistry_AllowedByDefaultGate(t *testing.T) {
+	original := registry.ActivePolicyGate()
+	t.Cleanup(func() { registry.RegisterPolicyGate(original) })
+
+	// Reset to default (allow-all) gate
+	registry.RegisterPolicyGate(registry.NoopPolicyGate{})
+
+	provider, cleanup := CreateTestConfigProvider(t, nil)
+	defer cleanup()
+	routes := NewRegistryRoutesWithProvider(provider)
+
+	// Empty body resets registry — should return 200 when gate allows
+	body := `{}`
+	req := httptest.NewRequest(http.MethodPut, "/default", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	rctx := chi.NewRouteContext()
+	rctx.URLParams.Add("name", "default")
+	req = req.WithContext(context.WithValue(req.Context(), chi.RouteCtxKey, rctx))
+
+	w := httptest.NewRecorder()
+	routes.updateRegistry(w, req)
+
+	assert.NotEqual(t, http.StatusForbidden, w.Code,
+		"Default gate should not return 403")
+}

docs/server/swagger.yaml

@@ -0,0 +1,90 @@
+// SPDX-FileCopyrightText: Copyright 2026 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package registry
+
+import (
+	"context"
+	"sync"
+)
+
+// UpdateRegistryConfig contains the configuration for a registry update,
+// used by both CLI and API callers for policy evaluation. At most one of URL,
+// APIURL, or LocalPath is set.
+type UpdateRegistryConfig struct {
+	// URL is the remote registry file URL being set.
+	URL string
+	// APIURL is the MCP Registry API endpoint URL being set.
+	APIURL string
+	// LocalPath is the local registry file path being set.
+	LocalPath string
+	// AllowPrivateIP indicates whether private IP addresses are permitted.
+	AllowPrivateIP bool
+	// HasAuth indicates whether authentication is being configured.
+	HasAuth bool
+}
+
+// DeleteRegistryConfig contains the configuration for a registry deletion,
+// used by both CLI and API callers for policy evaluation.
+type DeleteRegistryConfig struct {
+	// Name is the registry name being removed (e.g. "default").
+	Name string
+}
+
+// PolicyGate is called before registry mutation operations to allow external
+// policy enforcement. Downstream implementations should embed NoopPolicyGate
+// to remain forward-compatible when new methods are added.
+//
+// Error messages returned from the check methods are surfaced directly to the
+// end user (HTTP response body or CLI stderr). The policy gate implementer is
+// responsible for producing clear, actionable messages.
+type PolicyGate interface {
+	// CheckUpdateRegistry is called before a registry is created or updated.
+	// Return a non-nil error to block the operation.
+	CheckUpdateRegistry(ctx context.Context, cfg *UpdateRegistryConfig) error
+
+	// CheckDeleteRegistry is called before a registry is deleted or unset.
+	// Return a non-nil error to block the operation.
+	CheckDeleteRegistry(ctx context.Context, cfg *DeleteRegistryConfig) error
+}
+
+// NoopPolicyGate is a policy gate that allows all registry mutations.
+// Downstream implementations should embed this struct to remain
+// forward-compatible when new methods are added to the PolicyGate interface.
+type NoopPolicyGate struct{}
+
+// CheckUpdateRegistry implements PolicyGate by allowing all updates.
+func (NoopPolicyGate) CheckUpdateRegistry(_ context.Context, _ *UpdateRegistryConfig) error {
+	return nil
+}
+
+// CheckDeleteRegistry implements PolicyGate by allowing all deletions.
+func (NoopPolicyGate) CheckDeleteRegistry(_ context.Context, _ *DeleteRegistryConfig) error {
+	return nil
+}
+
+// allowAllGate is the default policy gate used when no gate has been registered.
+type allowAllGate struct {
+	NoopPolicyGate
+}
+
+var (
+	regGateMu sync.RWMutex
+	regGate   PolicyGate = allowAllGate{}
+)
+
+// RegisterPolicyGate replaces the active registry policy gate with g. It is
+// safe to call from multiple goroutines, though it is intended to be called
+// once at program startup.
+func RegisterPolicyGate(g PolicyGate) {
+	regGateMu.Lock()
+	defer regGateMu.Unlock()
+	regGate = g
+}
+
+// ActivePolicyGate returns the currently registered registry policy gate.
+func ActivePolicyGate() PolicyGate {
+	regGateMu.RLock()
+	defer regGateMu.RUnlock()
+	return regGate
+}