stacklok
diff --git a/‎.gitignore‎
Lines changed: 1 addition & 0 deletions b/‎.gitignore‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎cmd/thv-operator/api/v1alpha1/types.go‎
Lines changed: 30 additions & 0 deletions b/‎cmd/thv-operator/api/v1alpha1/types.go‎
Lines changed: 30 additions & 0 deletions
diff --git a/‎cmd/thv-operator/api/v1alpha1/zz_generated.deepcopy.go‎
Lines changed: 59 additions & 0 deletions b/‎cmd/thv-operator/api/v1alpha1/zz_generated.deepcopy.go‎
Lines changed: 59 additions & 0 deletions
diff --git a/‎cmd/thv-operator/api/v1beta1/mcpauthzconfig_types.go‎
Lines changed: 147 additions & 0 deletions b/‎cmd/thv-operator/api/v1beta1/mcpauthzconfig_types.go‎
Lines changed: 147 additions & 0 deletions
diff --git a/‎cmd/thv-operator/api/v1beta1/mcpauthzconfig_types_test.go‎
Lines changed: 89 additions & 0 deletions b/‎cmd/thv-operator/api/v1beta1/mcpauthzconfig_types_test.go‎
Lines changed: 89 additions & 0 deletions
diff --git a/‎cmd/thv-operator/api/v1beta1/mcpremoteproxy_types.go‎
Lines changed: 21 additions & 1 deletion b/‎cmd/thv-operator/api/v1beta1/mcpremoteproxy_types.go‎
Lines changed: 21 additions & 1 deletion
@@ -50,3 +50,4 @@ cmd/vmcp/__debug_bin*
 
 # Superpowers planning artifacts
 docs/superpowers/
+.pr-review/
@@ -126,6 +126,35 @@ type MCPOIDCConfigList struct {
 	Items           []MCPOIDCConfig `json:"items"`
 }
 
+// ─── MCPAuthzConfig ──────────────────────────────────────────────────────────
+
+//+kubebuilder:object:root=true
+//+kubebuilder:deprecatedversion:warning="toolhive.stacklok.dev/v1alpha1 is deprecated; use v1beta1"
+//+kubebuilder:subresource:status
+//+kubebuilder:resource:shortName=authzcfg,categories=toolhive
+//+kubebuilder:printcolumn:name="Type",type=string,JSONPath=`.spec.type`
+//+kubebuilder:printcolumn:name="Valid",type=string,JSONPath=`.status.conditions[?(@.type=='Valid')].status`
+//+kubebuilder:printcolumn:name="References",type=integer,JSONPath=`.status.referenceCount`
+//+kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
+
+// MCPAuthzConfig is the deprecated v1alpha1 version of the MCPAuthzConfig resource.
+type MCPAuthzConfig struct {
+	metav1.TypeMeta   `json:",inline"` // nolint:revive
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec   v1beta1.MCPAuthzConfigSpec   `json:"spec,omitempty"`
+	Status v1beta1.MCPAuthzConfigStatus `json:"status,omitempty"`
+}
+
+//+kubebuilder:object:root=true
+
+// MCPAuthzConfigList contains a list of MCPAuthzConfig.
+type MCPAuthzConfigList struct {
+	metav1.TypeMeta `json:",inline"` // nolint:revive
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []MCPAuthzConfig `json:"items"`
+}
+
 // ─── MCPRegistry ─────────────────────────────────────────────────────────────
 
 // MCPRegistry is the deprecated v1alpha1 version of the MCPRegistry resource.
@@ -402,6 +431,7 @@ type VirtualMCPServerList struct {
 func init() {
 	SchemeBuilder.Register(
 		&EmbeddingServer{}, &EmbeddingServerList{},
+		&MCPAuthzConfig{}, &MCPAuthzConfigList{},
 		&MCPExternalAuthConfig{}, &MCPExternalAuthConfigList{},
 		&MCPGroup{}, &MCPGroupList{},
 		&MCPOIDCConfig{}, &MCPOIDCConfigList{},
 
@@ -0,0 +1,147 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package v1beta1
+
+import (
+	"fmt"
+
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	runtime "k8s.io/apimachinery/pkg/runtime"
+
+	"github.com/stacklok/toolhive/pkg/authz/authorizers"
+)
+
+// Condition type and reasons for MCPAuthzConfig status (RFC-0023)
+const (
+	// ConditionTypeAuthzConfigValid indicates whether the MCPAuthzConfig configuration is valid
+	ConditionTypeAuthzConfigValid = ConditionTypeValid
+
+	// ConditionReasonAuthzConfigValid indicates spec validation passed
+	ConditionReasonAuthzConfigValid = "ConfigValid"
+
+	// ConditionReasonAuthzConfigInvalid indicates spec validation failed
+	ConditionReasonAuthzConfigInvalid = "ConfigInvalid"
+)
+
+// MCPAuthzConfigSpec defines the desired state of MCPAuthzConfig.
+// MCPAuthzConfig resources are namespace-scoped and can only be referenced by
+// MCPServer, MCPRemoteProxy, or VirtualMCPServer resources in the same namespace.
+type MCPAuthzConfigSpec struct {
+	// Type identifies the authorizer backend (e.g., "cedarv1", "httpv1").
+	// Must match a registered authorizer type in the factory registry.
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:MinLength=1
+	Type string `json:"type"`
+
+	// Config contains the backend-specific authorization configuration.
+	// The structure depends on the Type field:
+	//   - cedarv1: policies ([]string), entities_json (string), primary_upstream_provider (string), group_claim_name (string)
+	//   - httpv1: http ({url, timeout, insecure_skip_verify}), context ({include_args, include_operation}), claim_mapping (string)
+	// +kubebuilder:pruning:PreserveUnknownFields
+	// +kubebuilder:validation:Type=object
+	Config runtime.RawExtension `json:"config"`
+}
+
+// MCPAuthzConfigStatus defines the observed state of MCPAuthzConfig
+type MCPAuthzConfigStatus struct {
+	// Conditions represent the latest available observations of the MCPAuthzConfig's state
+	// +listType=map
+	// +listMapKey=type
+	// +optional
+	Conditions []metav1.Condition `json:"conditions,omitempty"`
+
+	// ObservedGeneration is the most recent generation observed for this MCPAuthzConfig.
+	// +optional
+	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
+
+	// ConfigHash is a hash of the current configuration for change detection
+	// +optional
+	ConfigHash string `json:"configHash,omitempty"`
+
+	// ReferenceCount is the number of workloads referencing this config.
+	// +optional
+	ReferenceCount int32 `json:"referenceCount,omitempty"`
+
+	// ReferencingWorkloads is a list of workload resources that reference this MCPAuthzConfig.
+	// Each entry identifies the workload by kind and name. The map key is the
+	// (kind, name) pair so two workloads of different kinds that share a name
+	// (e.g., an MCPServer "foo" and a VirtualMCPServer "foo") are distinct
+	// entries rather than colliding under merge-patch semantics.
+	// +listType=map
+	// +listMapKey=kind
+	// +listMapKey=name
+	// +optional
+	ReferencingWorkloads []WorkloadReference `json:"referencingWorkloads,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+// +kubebuilder:storageversion
+// +kubebuilder:subresource:status
+// +kubebuilder:metadata:labels=toolhive.stacklok.dev/auto-migrate-storage-version=true
+// +kubebuilder:resource:shortName=authzcfg,categories=toolhive
+// +kubebuilder:printcolumn:name="Type",type=string,JSONPath=`.spec.type`
+// +kubebuilder:printcolumn:name="Valid",type=string,JSONPath=`.status.conditions[?(@.type=='Valid')].status`
+// +kubebuilder:printcolumn:name="References",type=integer,JSONPath=`.status.referenceCount`
+// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
+
+// MCPAuthzConfig is the Schema for the mcpauthzconfigs API.
+// MCPAuthzConfig resources are namespace-scoped and can only be referenced by
+// MCPServer, MCPRemoteProxy, or VirtualMCPServer resources within the same namespace.
+// Cross-namespace references are not supported for security and isolation reasons.
+type MCPAuthzConfig struct {
+	metav1.TypeMeta   `json:",inline"` // nolint:revive
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec   MCPAuthzConfigSpec   `json:"spec,omitempty"`
+	Status MCPAuthzConfigStatus `json:"status,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+
+// MCPAuthzConfigList contains a list of MCPAuthzConfig
+type MCPAuthzConfigList struct {
+	metav1.TypeMeta `json:",inline"` // nolint:revive
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []MCPAuthzConfig `json:"items"`
+}
+
+// MCPAuthzConfigReference references a shared MCPAuthzConfig resource.
+// The referenced MCPAuthzConfig must be in the same namespace as the referencing workload.
+type MCPAuthzConfigReference struct {
+	// Name is the name of the MCPAuthzConfig resource in the same namespace.
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:MinLength=1
+	Name string `json:"name"`
+}
+
+// Validate performs structural validation on the MCPAuthzConfig spec.
+// This method is called by the controller during reconciliation.
+//
+// Validate provides defense-in-depth alongside CEL validation rules: CEL catches
+// issues at API admission time, but this method also validates stored objects to
+// catch any that bypassed CEL or were stored before CEL rules were added.
+//
+// Validate consults the authorizer factory registry (pkg/authz/authorizers) to
+// reject spec.type values that no backend has registered. Backend-specific
+// schema validation (interpreting spec.config) still lives in the controller,
+// where the registered factory's ValidateConfig is invoked.
+func (r *MCPAuthzConfig) Validate() error {
+	if r.Spec.Type == "" {
+		return fmt.Errorf("type must not be empty")
+	}
+	if !authorizers.IsRegistered(r.Spec.Type) {
+		return fmt.Errorf(
+			"type %q is not a registered authorizer backend (registered: %v)",
+			r.Spec.Type, authorizers.RegisteredTypes(),
+		)
+	}
+	if len(r.Spec.Config.Raw) == 0 {
+		return fmt.Errorf("config must not be empty")
+	}
+	return nil
+}
+
+func init() {
+	SchemeBuilder.Register(&MCPAuthzConfig{}, &MCPAuthzConfigList{})
+}
@@ -0,0 +1,89 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package v1beta1
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	runtime "k8s.io/apimachinery/pkg/runtime"
+
+	// Blank-imported so authorizers.IsRegistered("cedarv1") returns true
+	// inside Validate(). Without this, every test case using a real backend
+	// type would hit the unregistered-type branch.
+	_ "github.com/stacklok/toolhive/pkg/authz/authorizers/cedar"
+)
+
+func TestMCPAuthzConfig_Validate(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name        string
+		spec        MCPAuthzConfigSpec
+		expectError bool
+		errContains string
+	}{
+		{
+			name: "valid spec passes",
+			spec: MCPAuthzConfigSpec{
+				Type:   "cedarv1",
+				Config: runtime.RawExtension{Raw: []byte(`{"policies":[]}`)},
+			},
+			expectError: false,
+		},
+		{
+			name: "empty type fails",
+			spec: MCPAuthzConfigSpec{
+				Type:   "",
+				Config: runtime.RawExtension{Raw: []byte(`{}`)},
+			},
+			expectError: true,
+			errContains: "type must not be empty",
+		},
+		{
+			name: "unregistered type fails",
+			spec: MCPAuthzConfigSpec{
+				Type:   "nope",
+				Config: runtime.RawExtension{Raw: []byte(`{"policies":[]}`)},
+			},
+			expectError: true,
+			errContains: `"nope" is not a registered authorizer backend`,
+		},
+		{
+			name: "empty config raw fails",
+			spec: MCPAuthzConfigSpec{
+				Type:   "cedarv1",
+				Config: runtime.RawExtension{Raw: []byte{}},
+			},
+			expectError: true,
+			errContains: "config must not be empty",
+		},
+		{
+			name: "nil config raw fails",
+			spec: MCPAuthzConfigSpec{
+				Type:   "cedarv1",
+				Config: runtime.RawExtension{Raw: nil},
+			},
+			expectError: true,
+			errContains: "config must not be empty",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			cfg := &MCPAuthzConfig{Spec: tt.spec}
+			err := cfg.Validate()
+			if tt.expectError {
+				assert.Error(t, err)
+				if tt.errContains != "" {
+					assert.ErrorContains(t, err, tt.errContains)
+				}
+			} else {
+				assert.NoError(t, err)
+			}
+		})
+	}
+}
@@ -36,6 +36,10 @@ type HeaderFromSecret struct {
 }
 
 // MCPRemoteProxySpec defines the desired state of MCPRemoteProxy
+//
+// +kubebuilder:validation:XValidation:rule="!(has(self.authzConfig) && has(self.authzConfigRef))",message="authzConfig and authzConfigRef are mutually exclusive; use authzConfigRef to reference a shared MCPAuthzConfig"
+//
+//nolint:lll // CEL validation rules exceed line length limit
 type MCPRemoteProxySpec struct {
 	// RemoteURL is the URL of the remote MCP server to proxy
 	// +kubebuilder:validation:Required
@@ -83,10 +87,26 @@ type MCPRemoteProxySpec struct {
 	// +optional
 	HeaderForward *HeaderForwardConfig `json:"headerForward,omitempty"`
 
-	// AuthzConfig defines authorization policy configuration for the proxy
+	// AuthzConfig defines authorization policy configuration for the proxy.
+	// AuthzConfig and AuthzConfigRef are mutually exclusive.
 	// +optional
 	AuthzConfig *AuthzConfigRef `json:"authzConfig,omitempty"`
 
+	// AuthzConfigRef references a shared MCPAuthzConfig resource for authorization.
+	// The referenced MCPAuthzConfig must exist in the same namespace as this MCPRemoteProxy.
+	// Mutually exclusive with authzConfig.
+	//
+	// TODO(#4778): remove the staging NOTE below once workload controllers
+	// resolve AuthzConfigRef into a runtime authz config.
+	//
+	// NOTE: this field is consumed by workload controllers in a follow-up PR.
+	// Until that lands, AuthzConfigRef is reference-tracked by the
+	// MCPAuthzConfig controller (deletion protection, status.referenceCount)
+	// but does NOT apply authorization to this MCPRemoteProxy. Use the
+	// inline AuthzConfig field in the meantime.
+	// +optional
+	AuthzConfigRef *MCPAuthzConfigReference `json:"authzConfigRef,omitempty"`
+
 	// Audit defines audit logging configuration for the proxy
 	// +optional
 	Audit *AuditConfig `json:"audit,omitempty"`
Original file line number	Diff line number	Diff line change
`@@ -50,3 +50,4 @@ cmd/vmcp/__debug_bin*`
`50`	`50`
`51`	`51`	`# Superpowers planning artifacts`
`52`	`52`	`docs/superpowers/`
	`53`	`+.pr-review/`