Surface unauthenticated proxy default in logs and docs (#5488)

* Surface unauthenticated proxy default in logs and docs

When an MCPServer or MCPRemoteProxy is deployed without OIDCConfigRef
(or any other auth source), the proxy falls back to LocalUserMiddleware
and forwards every request under a synthetic local-user identity with no
credential check. This unauthenticated fallback is intentional, but it
was silent: the only signal was a debug log, and the README claimed
unconditional "identity enforcement per request" (GHSA-hfrv-94x5-85p2).

Make the state visible without changing the default behavior:
- Raise the no-auth fallback log in GetAuthenticationMiddleware from
  Debug to Warn, naming the consequence and how to enable auth.
- Document the unauthenticated default on the OIDCConfigRef field of
  both MCPServer and MCPRemoteProxy; regenerate the CRD API reference.
- Reword the README so identity enforcement is stated as conditional on
  configuring an authentication source.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Correct crdref-gen working directory in operator rule

The rule said to run `task crdref-gen` from `cmd/thv-operator/`, but the
task resolves its config path relative to the repo root and fails from
that directory. Document the correct invocation.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Regenerate operator CRD manifests

Propagate the OIDCConfigRef security note into the generated CRD YAML
descriptions for MCPServer and MCPRemoteProxy.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

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

Author: ChrisJBurns

.claude/rules/operator.md

@@ -36,7 +36,7 @@ See `cmd/thv-operator/DESIGN.md` for detailed decision guidelines.
 
 - Always run `task operator-generate` after modifying CRD types
 - Always run `task operator-manifests` after adding kubebuilder markers
-- Always run `task crdref-gen` from `cmd/thv-operator/` after CRD changes to regenerate API docs (uses relative paths)
+- Always run `task crdref-gen` from the repo root after CRD changes to regenerate API docs (running it from `cmd/thv-operator/` fails — the task resolves the config path relative to the repo root)
 - Use `envtest` for integration testing, not real clusters
 - Chainsaw tests require a real Kubernetes cluster
 - Status writes must go through `controllerutil.MutateAndPatchStatus` — see the Status Writes section below
@@ -65,7 +65,7 @@ task operator-generate        # Generate deepcopy, client code
 task operator-manifests       # Generate CRD YAML, RBAC
 task operator-test            # Run unit tests
 task operator-e2e-test        # Run e2e tests
-task crdref-gen              # Generate CRD API docs (run from cmd/thv-operator/)
+task crdref-gen              # Generate CRD API docs (run from the repo root)
 ```
 
 ## Spec / metadata patching

README.md

@@ -14,7 +14,7 @@
 
 ## Run any MCP server securely, instantly, anywhere.
 
-ToolHive runs every MCP server in an isolated container, enforces identity and access policy per request, and gives platform teams the observability they need to put MCP in production.
+ToolHive runs every MCP server in an isolated container, enforces identity and access policy per request when configured with an authentication source, and gives platform teams the observability they need to put MCP in production.
 
 ## Why ToolHive?
 
@@ -29,7 +29,7 @@ Here are some of the more common use cases for ToolHive:
   <tr valign="top">
     <td>Connect Claude Code, Cursor, GitHub Copilot, or your preferred client to MCP servers with a single click or command.<br><br>
     ToolHive wraps every MCP server in an isolated container with a minimal permission file (no local credentials) and uses semantic tool search to reduce your token usage by up to 85%.</td>
-    <td>Put an end to shadow MCP use by your developers, and give your security team the audit logs and identity enforcement they require.<br><br>
+    <td>Put an end to shadow MCP use by your developers, and give your security team the audit logs and configurable identity enforcement they require.<br><br>
     ToolHive includes a Kubernetes operator, so you can declare policies, integrate with your IdP and observability stack, emit OTel traces, and more … all with familiar tools and patterns.</td>
     <td>Most MCP solutions are SaaS, but your compliance requirements prohibit sensitive info from being processed by SaaS providers.<br><br>
     ToolHive is the exception that allows you to self-host your MCP registry, gateway, etc. You can pilot the entire platform, and when you’re ready to scale, Stacklok’s got the added capabilities and expert team ready!</td>

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

@@ -57,6 +57,12 @@ type MCPRemoteProxySpec struct {
 	// The referenced MCPOIDCConfig must exist in the same namespace as this MCPRemoteProxy.
 	// Per-server overrides (audience, scopes) are specified here; shared provider config
 	// lives in the MCPOIDCConfig resource.
+	//
+	// SECURITY: if this field is omitted and no other authentication source is configured,
+	// the proxy runs UNAUTHENTICATED. It accepts every request that can reach its port and
+	// forwards it to the remote MCP server under a synthetic local-user identity, with no
+	// token or credential check. Set this field to enforce identity-based access control
+	// per request.
 	// +optional
 	OIDCConfigRef *MCPOIDCConfigReference `json:"oidcConfigRef,omitempty"`
 

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

@@ -290,6 +290,11 @@ type MCPServerSpec struct {
 	// The referenced MCPOIDCConfig must exist in the same namespace as this MCPServer.
 	// Per-server overrides (audience, scopes) are specified here; shared provider config
 	// lives in the MCPOIDCConfig resource.
+	//
+	// SECURITY: if this field is omitted and no other authentication source is configured,
+	// the proxy runs UNAUTHENTICATED. It accepts every request that can reach its port and
+	// forwards it to the MCP server under a synthetic local-user identity, with no token or
+	// credential check. Set this field to enforce identity-based access control per request.
 	// +optional
 	OIDCConfigRef *MCPOIDCConfigReference `json:"oidcConfigRef,omitempty"`
 

deploy/charts/operator-crds/files/crds/toolhive.stacklok.dev_mcpremoteproxies.yaml

@@ -291,6 +291,12 @@ spec:
                   The referenced MCPOIDCConfig must exist in the same namespace as this MCPRemoteProxy.
                   Per-server overrides (audience, scopes) are specified here; shared provider config
                   lives in the MCPOIDCConfig resource.
+
+                  SECURITY: if this field is omitted and no other authentication source is configured,
+                  the proxy runs UNAUTHENTICATED. It accepts every request that can reach its port and
+                  forwards it to the remote MCP server under a synthetic local-user identity, with no
+                  token or credential check. Set this field to enforce identity-based access control
+                  per request.
                 properties:
                   audience:
                     description: |-
@@ -910,6 +916,12 @@ spec:
                   The referenced MCPOIDCConfig must exist in the same namespace as this MCPRemoteProxy.
                   Per-server overrides (audience, scopes) are specified here; shared provider config
                   lives in the MCPOIDCConfig resource.
+
+                  SECURITY: if this field is omitted and no other authentication source is configured,
+                  the proxy runs UNAUTHENTICATED. It accepts every request that can reach its port and
+                  forwards it to the remote MCP server under a synthetic local-user identity, with no
+                  token or credential check. Set this field to enforce identity-based access control
+                  per request.
                 properties:
                   audience:
                     description: |-

deploy/charts/operator-crds/files/crds/toolhive.stacklok.dev_mcpservers.yaml

@@ -288,6 +288,11 @@ spec:
                   The referenced MCPOIDCConfig must exist in the same namespace as this MCPServer.
                   Per-server overrides (audience, scopes) are specified here; shared provider config
                   lives in the MCPOIDCConfig resource.
+
+                  SECURITY: if this field is omitted and no other authentication source is configured,
+                  the proxy runs UNAUTHENTICATED. It accepts every request that can reach its port and
+                  forwards it to the MCP server under a synthetic local-user identity, with no token or
+                  credential check. Set this field to enforce identity-based access control per request.
                 properties:
                   audience:
                     description: |-
@@ -1205,6 +1210,11 @@ spec:
                   The referenced MCPOIDCConfig must exist in the same namespace as this MCPServer.
                   Per-server overrides (audience, scopes) are specified here; shared provider config
                   lives in the MCPOIDCConfig resource.
+
+                  SECURITY: if this field is omitted and no other authentication source is configured,
+                  the proxy runs UNAUTHENTICATED. It accepts every request that can reach its port and
+                  forwards it to the MCP server under a synthetic local-user identity, with no token or
+                  credential check. Set this field to enforce identity-based access control per request.
                 properties:
                   audience:
                     description: |-

deploy/charts/operator-crds/templates/toolhive.stacklok.dev_mcpremoteproxies.yaml

@@ -294,6 +294,12 @@ spec:
                   The referenced MCPOIDCConfig must exist in the same namespace as this MCPRemoteProxy.
                   Per-server overrides (audience, scopes) are specified here; shared provider config
                   lives in the MCPOIDCConfig resource.
+
+                  SECURITY: if this field is omitted and no other authentication source is configured,
+                  the proxy runs UNAUTHENTICATED. It accepts every request that can reach its port and
+                  forwards it to the remote MCP server under a synthetic local-user identity, with no
+                  token or credential check. Set this field to enforce identity-based access control
+                  per request.
                 properties:
                   audience:
                     description: |-
@@ -913,6 +919,12 @@ spec:
                   The referenced MCPOIDCConfig must exist in the same namespace as this MCPRemoteProxy.
                   Per-server overrides (audience, scopes) are specified here; shared provider config
                   lives in the MCPOIDCConfig resource.
+
+                  SECURITY: if this field is omitted and no other authentication source is configured,
+                  the proxy runs UNAUTHENTICATED. It accepts every request that can reach its port and
+                  forwards it to the remote MCP server under a synthetic local-user identity, with no
+                  token or credential check. Set this field to enforce identity-based access control
+                  per request.
                 properties:
                   audience:
                     description: |-

deploy/charts/operator-crds/templates/toolhive.stacklok.dev_mcpservers.yaml

@@ -291,6 +291,11 @@ spec:
                   The referenced MCPOIDCConfig must exist in the same namespace as this MCPServer.
                   Per-server overrides (audience, scopes) are specified here; shared provider config
                   lives in the MCPOIDCConfig resource.
+
+                  SECURITY: if this field is omitted and no other authentication source is configured,
+                  the proxy runs UNAUTHENTICATED. It accepts every request that can reach its port and
+                  forwards it to the MCP server under a synthetic local-user identity, with no token or
+                  credential check. Set this field to enforce identity-based access control per request.
                 properties:
                   audience:
                     description: |-
@@ -1208,6 +1213,11 @@ spec:
                   The referenced MCPOIDCConfig must exist in the same namespace as this MCPServer.
                   Per-server overrides (audience, scopes) are specified here; shared provider config
                   lives in the MCPOIDCConfig resource.
+
+                  SECURITY: if this field is omitted and no other authentication source is configured,
+                  the proxy runs UNAUTHENTICATED. It accepts every request that can reach its port and
+                  forwards it to the MCP server under a synthetic local-user identity, with no token or
+                  credential check. Set this field to enforce identity-based access control per request.
                 properties:
                   audience:
                     description: |-

docs/operator/crd-api.md

@@ -60,7 +60,10 @@ func ExtractBearerToken(r *http.Request) (string, error) {
 }
 
 // GetAuthenticationMiddleware returns the appropriate authentication middleware based on the configuration.
-// If OIDC config is provided, it returns JWT middleware. Otherwise, it returns local user middleware.
+// If OIDC config is provided, it returns JWT validation middleware. Otherwise it returns local-user
+// middleware and logs a WARNING: with no OIDC config, the proxy accepts every request and forwards it
+// under a synthetic local-user identity with no token or credential check. This unauthenticated fallback
+// is intended for local/development use; configure an OIDC provider to enforce authentication per request.
 func GetAuthenticationMiddleware(ctx context.Context, oidcConfig *TokenValidatorConfig, opts ...TokenValidatorOption,
 ) (func(http.Handler) http.Handler, http.Handler, error) {
 	if oidcConfig != nil {
@@ -76,7 +79,9 @@ func GetAuthenticationMiddleware(ctx context.Context, oidcConfig *TokenValidator
 		return jwtValidator.Middleware, authInfoHandler, nil
 	}
 
-	slog.Debug("oidc validation disabled, using local user authentication")
+	slog.Warn("no authentication configured: the proxy will accept every request unauthenticated and " +
+		"assign each a synthetic local-user identity with no token or credential check; " +
+		"configure an OIDC provider to enforce authentication per request")
 
 	// Get current OS user
 	currentUser, err := user.Current()