Automate HMAC secret management

Automatically generate and manage HMAC secrets when SessionManagementV2
is enabled in VirtualMCPServer resources, eliminating manual secret
creation.

Related-to: #3867

Author: taskbot

cmd/thv-operator/controllers/virtualmcpserver_controller.go

@@ -7,6 +7,8 @@ package controllers
 
 import (
 	"context"
+	"crypto/rand"
+	"encoding/base64"
 	"encoding/json"
 	"fmt"
 	"maps"
@@ -24,6 +26,7 @@ import (
 	"k8s.io/client-go/tools/record"
 	ctrl "sigs.k8s.io/controller-runtime"
 	"sigs.k8s.io/controller-runtime/pkg/client"
+	"sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
 	"sigs.k8s.io/controller-runtime/pkg/handler"
 	"sigs.k8s.io/controller-runtime/pkg/log"
 	"sigs.k8s.io/controller-runtime/pkg/reconcile"
@@ -101,7 +104,7 @@ type VirtualMCPServerReconciler struct {
 // +kubebuilder:rbac:groups="rbac.authorization.k8s.io",resources=roles,verbs=create;delete;get;list;patch;update;watch
 // +kubebuilder:rbac:groups="rbac.authorization.k8s.io",resources=rolebindings,verbs=create;delete;get;list;patch;update;watch
 // +kubebuilder:rbac:groups="",resources=events,verbs=create;patch
-// +kubebuilder:rbac:groups="",resources=secrets,verbs=get;list;watch
+// +kubebuilder:rbac:groups="",resources=secrets,verbs=create;get;list;watch
 // +kubebuilder:rbac:groups=apps,resources=deployments,verbs=create;delete;get;list;patch;update;watch
 // +kubebuilder:rbac:groups="",resources=serviceaccounts,verbs=create;delete;get;list;patch;update;watch
 // +kubebuilder:rbac:groups=toolhive.stacklok.dev,resources=embeddingservers,verbs=get;list;watch
@@ -593,6 +596,12 @@ func (r *VirtualMCPServerReconciler) ensureAllResources(
 		return ctrl.Result{}, err
 	}
 
+	// Ensure HMAC secret for session token binding (Session Management V2)
+	if err := r.ensureHMACSecret(ctx, vmcp); err != nil {
+		ctxLogger.Error(err, "Failed to ensure HMAC secret")
+		return ctrl.Result{}, err
+	}
+
 	// Ensure vmcp Config ConfigMap
 	if err := r.ensureVmcpConfigConfigMap(ctx, vmcp, workloadNames, statusManager); err != nil {
 		ctxLogger.Error(err, "Failed to ensure vmcp Config ConfigMap")
@@ -661,6 +670,161 @@ func (r *VirtualMCPServerReconciler) ensureRBACResources(
 	return err
 }
 
+// ensureHMACSecret ensures the HMAC secret exists for session token binding.
+// This secret is required when Session Management V2 is enabled.
+// The secret is automatically generated with a cryptographically secure random value.
+//
+// The secret follows this naming pattern: {vmcp-name}-hmac-secret
+// and contains a single key: hmac-secret with a 32-byte base64-encoded random value.
+func (r *VirtualMCPServerReconciler) ensureHMACSecret(
+	ctx context.Context,
+	vmcp *mcpv1alpha1.VirtualMCPServer,
+) error {
+	ctxLogger := log.FromContext(ctx)
+
+	// Only ensure HMAC secret if Session Management V2 is enabled
+	if vmcp.Spec.Config.Operational == nil || !vmcp.Spec.Config.Operational.SessionManagementV2 {
+		return nil
+	}
+
+	secretName := fmt.Sprintf("%s-hmac-secret", vmcp.Name)
+	secret := &corev1.Secret{}
+	err := r.Get(ctx, types.NamespacedName{Name: secretName, Namespace: vmcp.Namespace}, secret)
+
+	if errors.IsNotFound(err) {
+		// Generate a cryptographically secure 32-byte HMAC secret
+		hmacSecret, err := generateHMACSecret()
+		if err != nil {
+			ctxLogger.Error(err, "Failed to generate HMAC secret")
+			if r.Recorder != nil {
+				r.Recorder.Eventf(vmcp, corev1.EventTypeWarning, "HMACSecretGenerationFailed",
+					"Failed to generate HMAC secret: %v", err)
+			}
+			return fmt.Errorf("failed to generate HMAC secret: %w", err)
+		}
+
+		newSecret := &corev1.Secret{
+			ObjectMeta: metav1.ObjectMeta{
+				Name:      secretName,
+				Namespace: vmcp.Namespace,
+				Labels: map[string]string{
+					"app.kubernetes.io/name":       "virtualmcpserver",
+					"app.kubernetes.io/instance":   vmcp.Name,
+					"app.kubernetes.io/component":  "session-security",
+					"app.kubernetes.io/managed-by": "toolhive-operator",
+				},
+				Annotations: map[string]string{
+					"toolhive.stacklok.dev/purpose": "hmac-secret-for-session-token-binding",
+				},
+			},
+			Type: corev1.SecretTypeOpaque,
+			Data: map[string][]byte{
+				"hmac-secret": []byte(hmacSecret),
+			},
+		}
+
+		// Set VirtualMCPServer as owner so secret is automatically deleted when VMCP is deleted
+		if err := controllerutil.SetControllerReference(vmcp, newSecret, r.Scheme); err != nil {
+			ctxLogger.Error(err, "Failed to set controller reference for HMAC secret")
+			return fmt.Errorf("failed to set controller reference: %w", err)
+		}
+
+		ctxLogger.Info("Creating HMAC secret for session token binding", "Secret.Name", secretName)
+		if err := r.Create(ctx, newSecret); err != nil {
+			ctxLogger.Error(err, "Failed to create HMAC secret")
+			if r.Recorder != nil {
+				r.Recorder.Eventf(vmcp, corev1.EventTypeWarning, "HMACSecretCreationFailed",
+					"Failed to create HMAC secret: %v", err)
+			}
+			return fmt.Errorf("failed to create HMAC secret: %w", err)
+		}
+
+		// Record success event
+		if r.Recorder != nil {
+			r.Recorder.Event(vmcp, corev1.EventTypeNormal, "HMACSecretCreated",
+				"HMAC secret created for session token binding")
+		}
+		return nil
+	} else if err != nil {
+		ctxLogger.Error(err, "Failed to get HMAC secret")
+		return fmt.Errorf("failed to get HMAC secret: %w", err)
+	}
+
+	// Secret exists - validate ownership and structure before accepting it
+	if err := r.validateHMACSecret(ctx, vmcp, secret); err != nil {
+		ctxLogger.Error(err, "Existing HMAC secret is invalid", "Secret.Name", secretName)
+		if r.Recorder != nil {
+			r.Recorder.Eventf(vmcp, corev1.EventTypeWarning, "HMACSecretValidationFailed",
+				"Existing HMAC secret validation failed: %v", err)
+		}
+		return fmt.Errorf("existing HMAC secret validation failed: %w", err)
+	}
+
+	return nil
+}
+
+// validateHMACSecret validates that an existing HMAC secret has the correct ownership,
+// structure, and content. This prevents accepting stale, malformed, or attacker-controlled
+// secrets that could weaken session token signing or cause pod startup failures.
+func (*VirtualMCPServerReconciler) validateHMACSecret(
+	ctx context.Context,
+	vmcp *mcpv1alpha1.VirtualMCPServer,
+	secret *corev1.Secret,
+) error {
+	ctxLogger := log.FromContext(ctx)
+
+	// Verify the secret is owned by this VirtualMCPServer
+	// This prevents accepting secrets created by other actors
+	isOwned := false
+	for _, ownerRef := range secret.OwnerReferences {
+		if ownerRef.UID == vmcp.UID &&
+			ownerRef.Kind == "VirtualMCPServer" &&
+			ownerRef.Name == vmcp.Name {
+			isOwned = true
+			break
+		}
+	}
+	if !isOwned {
+		return fmt.Errorf("secret is not owned by VirtualMCPServer %s/%s", vmcp.Namespace, vmcp.Name)
+	}
+
+	// Verify the hmac-secret key exists
+	hmacSecretData, exists := secret.Data["hmac-secret"]
+	if !exists {
+		return fmt.Errorf("secret missing required 'hmac-secret' key")
+	}
+
+	// Verify it's valid base64 and decodes to exactly 32 bytes
+	hmacSecretBase64 := string(hmacSecretData)
+	if hmacSecretBase64 == "" {
+		return fmt.Errorf("hmac-secret is empty")
+	}
+
+	decoded, err := base64.StdEncoding.DecodeString(hmacSecretBase64)
+	if err != nil {
+		return fmt.Errorf("hmac-secret is not valid base64: %w", err)
+	}
+
+	if len(decoded) != 32 {
+		return fmt.Errorf("hmac-secret must be exactly 32 bytes, got %d bytes", len(decoded))
+	}
+
+	// Verify it's not all zeros (would indicate a weak/predictable key)
+	allZeros := true
+	for _, b := range decoded {
+		if b != 0 {
+			allZeros = false
+			break
+		}
+	}
+	if allZeros {
+		return fmt.Errorf("hmac-secret is all zeros (weak key)")
+	}
+
+	ctxLogger.V(1).Info("HMAC secret validation passed", "Secret.Name", secret.Name)
+	return nil
+}
+
 // getVmcpConfigChecksum fetches the vmcp Config ConfigMap checksum annotation.
 // This is used to trigger deployment rollouts when the configuration changes.
 //
@@ -2371,3 +2535,18 @@ func setAuthConfigConditions(
 	// auth config errors are non-fatal. The system can continue operating with
 	// the auth configs that are valid.
 }
+
+// generateHMACSecret generates a cryptographically secure 32-byte HMAC secret
+// encoded as base64. This secret is used for session token binding in Session Management V2.
+//
+// Returns a base64-encoded string suitable for use as VMCP_SESSION_HMAC_SECRET.
+func generateHMACSecret() (string, error) {
+	// Generate 32 bytes of cryptographically secure random data
+	secret := make([]byte, 32)
+	if _, err := rand.Read(secret); err != nil {
+		return "", fmt.Errorf("failed to generate random bytes: %w", err)
+	}
+
+	// Encode as base64 for safe storage and environment variable use
+	return base64.StdEncoding.EncodeToString(secret), nil
+}

cmd/thv-operator/controllers/virtualmcpserver_deployment.go

@@ -273,6 +273,11 @@ func (r *VirtualMCPServerReconciler) buildEnvVarsForVmcp(
 	// Mount outgoing auth secrets
 	env = append(env, r.buildOutgoingAuthEnvVars(ctx, vmcp, typedWorkloads)...)
 
+	// Mount HMAC secret for session token binding (Session Management V2)
+	if vmcp.Spec.Config.Operational != nil && vmcp.Spec.Config.Operational.SessionManagementV2 {
+		env = append(env, r.buildHMACSecretEnvVar(vmcp))
+	}
+
 	// Note: Other secrets (Redis passwords, service account credentials) may be added here in the future
 	// following the same pattern of mounting from Kubernetes Secrets as environment variables.
 
@@ -321,6 +326,25 @@ func (*VirtualMCPServerReconciler) buildOIDCEnvVars(vmcp *mcpv1alpha1.VirtualMCP
 	return env
 }
 
+// buildHMACSecretEnvVar builds environment variable for HMAC secret mounting.
+// This secret is used for session token binding in Session Management V2.
+// The operator automatically generates and manages this secret if it doesn't exist.
+func (*VirtualMCPServerReconciler) buildHMACSecretEnvVar(vmcp *mcpv1alpha1.VirtualMCPServer) corev1.EnvVar {
+	secretName := fmt.Sprintf("%s-hmac-secret", vmcp.Name)
+
+	return corev1.EnvVar{
+		Name: "VMCP_SESSION_HMAC_SECRET",
+		ValueFrom: &corev1.EnvVarSource{
+			SecretKeyRef: &corev1.SecretKeySelector{
+				LocalObjectReference: corev1.LocalObjectReference{
+					Name: secretName,
+				},
+				Key: "hmac-secret",
+			},
+		},
+	}
+}
+
 // buildOutgoingAuthEnvVars builds environment variables for outgoing auth secrets.
 func (r *VirtualMCPServerReconciler) buildOutgoingAuthEnvVars(
 	ctx context.Context,

cmd/thv-operator/controllers/virtualmcpserver_hmac_secret_test.go

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package controllers
+
+import (
+	"encoding/base64"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestGenerateHMACSecret tests the HMAC secret generation function.
+func TestGenerateHMACSecret(t *testing.T) {
+	t.Parallel()
+
+	t.Run("generates valid base64 encoded secret", func(t *testing.T) {
+		t.Parallel()
+
+		secret, err := generateHMACSecret()
+		require.NoError(t, err)
+		require.NotEmpty(t, secret)
+
+		// Verify it's valid base64
+		decoded, err := base64.StdEncoding.DecodeString(secret)
+		require.NoError(t, err)
+		assert.Len(t, decoded, 32, "decoded secret should be exactly 32 bytes")
+	})
+
+	t.Run("generates unique secrets", func(t *testing.T) {
+		t.Parallel()
+
+		secret1, err := generateHMACSecret()
+		require.NoError(t, err)
+
+		secret2, err := generateHMACSecret()
+		require.NoError(t, err)
+
+		// Two generated secrets should be different
+		assert.NotEqual(t, secret1, secret2, "consecutive secrets should be unique")
+	})
+
+	t.Run("generates cryptographically secure random data", func(t *testing.T) {
+		t.Parallel()
+
+		secret, err := generateHMACSecret()
+		require.NoError(t, err)
+
+		decoded, err := base64.StdEncoding.DecodeString(secret)
+		require.NoError(t, err)
+
+		// Check that it's not all zeros (would indicate failure of crypto/rand)
+		allZeros := make([]byte, 32)
+		assert.NotEqual(t, allZeros, decoded, "secret should not be all zeros")
+	})
+
+	t.Run("generates multiple valid secrets", func(t *testing.T) {
+		t.Parallel()
+
+		// Generate 100 secrets to ensure consistency
+		secrets := make(map[string]bool)
+		for i := 0; i < 100; i++ {
+			secret, err := generateHMACSecret()
+			require.NoError(t, err)
+
+			// Verify base64 decoding
+			decoded, err := base64.StdEncoding.DecodeString(secret)
+			require.NoError(t, err)
+			assert.Len(t, decoded, 32)
+
+			// Track uniqueness
+			secrets[secret] = true
+		}
+
+		// All secrets should be unique
+		assert.Len(t, secrets, 100, "all generated secrets should be unique")
+	})
+}

cmd/vmcp/README.md

@@ -237,7 +237,35 @@ spec:
               key: hmac-secret
 ```
 
-**Note**: Kubernetes deployments **require** `VMCP_SESSION_HMAC_SECRET` to be set (the server will fail to start without it). For non-Kubernetes environments (local development/testing), a default insecure secret is used as a fallback, but this is **NOT recommended for production**.
+**Note**: When **Session Management V2 is enabled**, Kubernetes deployments **require** `VMCP_SESSION_HMAC_SECRET` to be set (the server will fail to start without it). For non-Kubernetes environments (local development/testing), a default insecure secret is used as a fallback, but this is **NOT recommended for production**. If Session Management V2 is disabled, this environment variable is not required.
+
+### Automatic Secret Management (ToolHive Operator)
+
+When deploying vMCP via the **ToolHive operator** with Session Management V2 enabled, the HMAC secret is **automatically generated and managed** for you:
+
+```yaml
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: VirtualMCPServer
+metadata:
+  name: my-vmcp
+spec:
+  config:
+    operational:
+      sessionManagementV2: true  # Enables automatic HMAC secret creation
+    group: my-group
+```
+
+The operator will:
+
+- ✅ Automatically generate a cryptographically secure 32-byte HMAC secret
+- ✅ Store it in a Kubernetes Secret named `{vmcp-name}-hmac-secret`
+- ✅ Inject it into the vMCP deployment as `VMCP_SESSION_HMAC_SECRET`
+- ✅ Validate existing secrets (ownership, structure, and content)
+- ✅ Automatically delete the secret when the VirtualMCPServer is removed
+
+**No manual secret generation or management required!** The operator handles all of this automatically when you enable Session Management V2.
+
+> **Note**: The secret is generated once at creation time and persists for the lifetime of the VirtualMCPServer. Secret rotation is not currently supported but may be added in a future release.
 
 ## Tool Aggregation & Conflict Resolution