Merge branch 'main' into worktree-redis-cluster-support-to-auth-server-storage

Author: reyortiz3

.github/workflows/security-scan.yml

@@ -32,7 +32,7 @@ jobs:
           fail-build: false
 
       - name: Upload Grype scan results to GitHub Security tab
-        uses: github/codeql-action/upload-sarif@95e58e9a2cdfd71adc6e0353d5c52f41a045d225 # v4
+        uses: github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7 # v4
         if: always()
         with:
           sarif_file: ${{ steps.grype-scan.outputs.sarif }}

cmd/thv-operator/api/v1alpha1/doc.go

@@ -1,18 +1,20 @@
 // SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-// Package v1alpha1 contains the deprecated v1alpha1 API types for the
-// toolhive.stacklok.dev group. These types exist solely to enable seamless
-// CRD graduation from v1alpha1 → v1beta1: the CRD serves both versions
-// (with conversion strategy "None"), so existing v1alpha1 resources continue
-// to work while users migrate their manifests to v1beta1.
+// Package v1alpha1 contains the v1alpha1 API types for the
+// toolhive.stacklok.dev group. Most types in this package exist to enable
+// seamless CRD graduation from v1alpha1 to v1beta1: the CRD serves both
+// versions (with conversion strategy "None"), so existing v1alpha1 resources
+// continue to work while users migrate their manifests to v1beta1.
+//
+// MCPWebhookConfig starts in v1alpha1 and is not deprecated.
 //
 // All Spec and Status types are imported from v1beta1 — the schemas are
 // identical. Only the root resource types and their List companions are
 // defined here so that controller-gen produces a multi-version CRD.
 //
-// This package will be removed in a future release once the v1alpha1
-// deprecation period ends.
+// The deprecated compatibility types in this package will be removed in a
+// future release once the v1alpha1 deprecation period ends.
 //
 // +kubebuilder:object:generate=true
 // +groupName=toolhive.stacklok.dev

cmd/thv-operator/api/v1alpha1/mcpwebhookconfig_types_test.go

@@ -0,0 +1,65 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package v1alpha1
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+	mcpv1beta1 "github.com/stacklok/toolhive/cmd/thv-operator/api/v1beta1"
+)
+
+func TestMCPWebhookConfig_Creation(t *testing.T) {
+	t.Parallel()
+
+	timeout := metav1.Duration{Duration: 5 * time.Second}
+
+	config := &MCPWebhookConfig{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      "test-webhook-config",
+			Namespace: "default",
+		},
+		Spec: mcpv1beta1.MCPWebhookConfigSpec{
+			Validating: []mcpv1beta1.WebhookSpec{
+				{
+					Name:          "test-validator",
+					URL:           "https://example.com/validate",
+					Timeout:       &timeout,
+					FailurePolicy: mcpv1beta1.WebhookFailurePolicyFail,
+					TLSConfig: &mcpv1beta1.WebhookTLSConfig{
+						InsecureSkipVerify: true,
+					},
+				},
+			},
+			Mutating: []mcpv1beta1.WebhookSpec{
+				{
+					Name:          "test-mutator",
+					URL:           "https://example.com/mutate",
+					Timeout:       &timeout,
+					FailurePolicy: mcpv1beta1.WebhookFailurePolicyIgnore,
+					HMACSecretRef: &mcpv1beta1.SecretKeyRef{
+						Name: "hmac-secret",
+						Key:  "key",
+					},
+				},
+			},
+		},
+	}
+
+	assert.NotNil(t, config)
+	assert.Equal(t, "test-webhook-config", config.Name)
+	assert.Len(t, config.Spec.Validating, 1)
+	assert.Len(t, config.Spec.Mutating, 1)
+
+	assert.Equal(t, "test-validator", config.Spec.Validating[0].Name)
+	assert.Equal(t, mcpv1beta1.WebhookFailurePolicyFail, config.Spec.Validating[0].FailurePolicy)
+	assert.True(t, config.Spec.Validating[0].TLSConfig.InsecureSkipVerify)
+
+	assert.Equal(t, "test-mutator", config.Spec.Mutating[0].Name)
+	assert.Equal(t, mcpv1beta1.WebhookFailurePolicyIgnore, config.Spec.Mutating[0].FailurePolicy)
+	assert.Equal(t, "hmac-secret", config.Spec.Mutating[0].HMACSecretRef.Name)
+}

cmd/thv-operator/api/v1alpha1/types.go

@@ -276,6 +276,34 @@ type MCPTelemetryConfigList struct {
 	Items           []MCPTelemetryConfig `json:"items"`
 }
 
+// ─── MCPWebhookConfig ────────────────────────────────────────────────────────
+
+//+kubebuilder:object:root=true
+//+kubebuilder:storageversion
+//+kubebuilder:subresource:status
+//+kubebuilder:resource:shortName=mwc,categories=toolhive
+//+kubebuilder:printcolumn:name="Valid",type=string,JSONPath=`.status.conditions[?(@.type=='Valid')].status`
+//+kubebuilder:printcolumn:name="References",type=string,JSONPath=`.status.referencingWorkloads`
+//+kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
+
+// MCPWebhookConfig is the Schema for the mcpwebhookconfigs API.
+type MCPWebhookConfig struct {
+	metav1.TypeMeta   `json:",inline"` // nolint:revive
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec   v1beta1.MCPWebhookConfigSpec   `json:"spec,omitempty"`
+	Status v1beta1.MCPWebhookConfigStatus `json:"status,omitempty"`
+}
+
+//+kubebuilder:object:root=true
+
+// MCPWebhookConfigList contains a list of MCPWebhookConfig.
+type MCPWebhookConfigList struct {
+	metav1.TypeMeta `json:",inline"` // nolint:revive
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []MCPWebhookConfig `json:"items"`
+}
+
 // ─── MCPToolConfig ───────────────────────────────────────────────────────────
 
 //+kubebuilder:object:root=true
@@ -378,6 +406,7 @@ func init() {
 		&MCPServer{}, &MCPServerList{},
 		&MCPServerEntry{}, &MCPServerEntryList{},
 		&MCPTelemetryConfig{}, &MCPTelemetryConfigList{},
+		&MCPWebhookConfig{}, &MCPWebhookConfigList{},
 		&MCPToolConfig{}, &MCPToolConfigList{},
 		&VirtualMCPCompositeToolDefinition{}, &VirtualMCPCompositeToolDefinitionList{},
 		&VirtualMCPServer{}, &VirtualMCPServerList{},

cmd/thv-operator/api/v1alpha1/zz_generated.deepcopy.go

@@ -86,12 +86,18 @@ const (
 const (
 	// ConditionTypeExternalAuthConfigValidated indicates whether the ExternalAuthConfig is valid
 	ConditionTypeExternalAuthConfigValidated = "ExternalAuthConfigValidated"
+
+	// ConditionTypeWebhookConfigValidated indicates whether the WebhookConfig is valid
+	ConditionTypeWebhookConfigValidated = "WebhookConfigValidated"
 )
 
 const (
 	// ConditionReasonExternalAuthConfigMultiUpstream indicates the ExternalAuthConfig has multiple upstreams,
 	// which is not supported for MCPServer (use VirtualMCPServer for multi-upstream).
 	ConditionReasonExternalAuthConfigMultiUpstream = "MultiUpstreamNotSupported"
+
+	// ConditionReasonWebhookConfigInvalid indicates the referenced webhook config is invalid or missing
+	ConditionReasonWebhookConfigInvalid = "WebhookConfigInvalid"
 )
 
 const (
@@ -287,6 +293,11 @@ type MCPServerSpec struct {
 	// +optional
 	ExternalAuthConfigRef *ExternalAuthConfigRef `json:"externalAuthConfigRef,omitempty"`
 
+	// WebhookConfigRef references a MCPWebhookConfig resource for webhook middleware configuration.
+	// The referenced MCPWebhookConfig must exist in the same namespace as this MCPServer.
+	// +optional
+	WebhookConfigRef *WebhookConfigRef `json:"webhookConfigRef,omitempty"`
+
 	// AuthServerRef optionally references a resource that configures an embedded
 	// OAuth 2.0/OIDC authorization server to authenticate MCP clients.
 	// Currently the only supported kind is MCPExternalAuthConfig (type: embeddedAuthServer).
@@ -717,6 +728,14 @@ type AuthServerRef struct {
 	Name string `json:"name"`
 }
 
+// WebhookConfigRef defines a reference to a MCPWebhookConfig resource.
+// The referenced MCPWebhookConfig must be in the same namespace as the MCPServer.
+type WebhookConfigRef struct {
+	// Name is the name of the MCPWebhookConfig resource
+	// +kubebuilder:validation:Required
+	Name string `json:"name"`
+}
+
 // ToolConfigRef defines a reference to a MCPToolConfig resource.
 // The referenced MCPToolConfig must be in the same namespace as the MCPServer.
 type ToolConfigRef struct {
@@ -828,6 +847,10 @@ type MCPServerStatus struct {
 	// +optional
 	TelemetryConfigHash string `json:"telemetryConfigHash,omitempty"`
 
+	// WebhookConfigHash is the hash of the referenced MCPWebhookConfig spec
+	// +optional
+	WebhookConfigHash string `json:"webhookConfigHash,omitempty"`
+
 	// URL is the URL where the MCP server can be accessed
 	// +optional
 	URL string `json:"url,omitempty"`

cmd/thv-operator/api/v1beta1/mcpserver_types.go

@@ -0,0 +1,113 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package v1beta1
+
+import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+// WebhookFailurePolicy defines how webhook errors are handled.
+type WebhookFailurePolicy string
+
+const (
+	// WebhookFailurePolicyFail denies the request on webhook error.
+	WebhookFailurePolicyFail WebhookFailurePolicy = "fail"
+	// WebhookFailurePolicyIgnore allows the request on webhook error.
+	WebhookFailurePolicyIgnore WebhookFailurePolicy = "ignore"
+)
+
+// WebhookTLSConfig contains TLS configuration for secure webhook connections
+type WebhookTLSConfig struct {
+	// CASecretRef references a Secret containing the CA certificate bundle used to verify the webhook server's certificate.
+	// Contains a bundle of PEM-encoded X.509 certificates.
+	// +optional
+	CASecretRef *SecretKeyRef `json:"caSecretRef,omitempty"`
+
+	// ClientCertSecretRef references a Secret containing the client certificate for mTLS authentication.
+	// The referenced key must contain a PEM-encoded client certificate.
+	// Use ClientKeySecretRef to provide the corresponding private key.
+	// +optional
+	ClientCertSecretRef *SecretKeyRef `json:"clientCertSecretRef,omitempty"`
+
+	// ClientKeySecretRef references a Secret containing the private key for the client certificate.
+	// Required when ClientCertSecretRef is set to enable mTLS.
+	// +optional
+	ClientKeySecretRef *SecretKeyRef `json:"clientKeySecretRef,omitempty"`
+
+	// InsecureSkipVerify disables server certificate verification.
+	// WARNING: This should only be used for development/testing and not in production environments.
+	// +optional
+	InsecureSkipVerify bool `json:"insecureSkipVerify,omitempty"`
+}
+
+// WebhookSpec defines the configuration for a single webhook middleware
+type WebhookSpec struct {
+	// Name is a unique identifier for this webhook
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=63
+	Name string `json:"name"`
+
+	// URL is the endpoint to call for this webhook. Must be an HTTP/HTTPS URL.
+	// +kubebuilder:validation:Format=uri
+	URL string `json:"url"`
+
+	// Timeout configures the maximum time to wait for the webhook to respond.
+	// Defaults to 10s if not specified. Maximum is 30s.
+	// +kubebuilder:validation:Type=string
+	// +kubebuilder:validation:Format=duration
+	// +optional
+	Timeout *metav1.Duration `json:"timeout,omitempty"`
+
+	// FailurePolicy defines how to handle errors when communicating with the webhook.
+	// Supported values: "fail", "ignore". Defaults to "fail".
+	// +kubebuilder:validation:Enum=fail;ignore
+	// +kubebuilder:default=fail
+	// +optional
+	FailurePolicy WebhookFailurePolicy `json:"failurePolicy,omitempty"`
+
+	// TLSConfig contains optional TLS configuration for the webhook connection.
+	// +optional
+	TLSConfig *WebhookTLSConfig `json:"tlsConfig,omitempty"`
+
+	// HMACSecretRef references a Kubernetes Secret containing the HMAC signing key
+	// used to sign the webhook payload. If set, the X-Toolhive-Signature header will be injected.
+	// +optional
+	HMACSecretRef *SecretKeyRef `json:"hmacSecretRef,omitempty"`
+}
+
+// MCPWebhookConfigSpec defines the desired state of MCPWebhookConfig
+// +kubebuilder:validation:XValidation:rule="(has(self.validating) ? size(self.validating) : 0) + (has(self.mutating) ? size(self.mutating) : 0) > 0",message="at least one validating or mutating webhook must be defined"
+//
+//nolint:lll // CEL validation rules exceed line length limit
+type MCPWebhookConfigSpec struct {
+	// Validating webhooks are called to approve or deny MCP requests.
+	// +optional
+	Validating []WebhookSpec `json:"validating,omitempty"`
+
+	// Mutating webhooks are called to transform MCP requests before processing.
+	// +optional
+	Mutating []WebhookSpec `json:"mutating,omitempty"`
+}
+
+// MCPWebhookConfigStatus defines the observed state of MCPWebhookConfig
+type MCPWebhookConfigStatus struct {
+	// Conditions represent the latest available observations
+	// +listType=map
+	// +listMapKey=type
+	// +optional
+	Conditions []metav1.Condition `json:"conditions,omitempty"`
+
+	// ObservedGeneration is the last observed generation corresponding to the current status
+	// +optional
+	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
+
+	// ConfigHash is a hash of the spec, used for detecting changes
+	// +optional
+	ConfigHash string `json:"configHash,omitempty"`
+
+	// ReferencingWorkloads is a list of workload resources that reference this MCPWebhookConfig.
+	// Each entry identifies the workload by kind and name.
+	// +listType=map
+	// +listMapKey=name
+	// +optional
+	ReferencingWorkloads []WorkloadReference `json:"referencingWorkloads,omitempty"`
+}