Add per-script execution timeout and fix chain order comment

Add a default 30s per-script execution timeout that bounds total
wall-clock time including all tool calls. Configurable via
scriptEngine.scriptTimeout in the vMCP config. The timeout is applied
via context.WithTimeout in executor.Execute, so tool Call closures
that respect context cancellation will abort when the deadline is
exceeded.

Fix the middleware chain order comment in server.go to accurately
reflect that script middleware runs before authz in the execution
path: auth establishes identity, but authz does not see the
execute_tool_script call itself. Inner tool calls from scripts do
flow through authz.

Part of #4742

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

Author: jerm-dro

cmd/vmcp/app/commands.go

@@ -669,7 +669,8 @@ func createScriptMiddleware(cfg *config.Config) func(http.Handler) http.Handler
 
 	slog.Info("code mode enabled — execute_tool_script virtual tool will be available")
 	return script.NewMiddleware(&script.Config{
-		StepLimit:   cfg.ScriptEngine.StepLimit,
-		ParallelMax: cfg.ScriptEngine.ParallelMax,
+		StepLimit:     cfg.ScriptEngine.StepLimit,
+		ParallelMax:   cfg.ScriptEngine.ParallelMax,
+		ScriptTimeout: time.Duration(cfg.ScriptEngine.ScriptTimeout),
 	})
 }

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

@@ -1666,6 +1666,15 @@ spec:
                           ParallelMax is the maximum number of concurrent worker goroutines that
                           parallel() can use. Zero means the worker count matches the task count.
                         type: integer
+                      scriptTimeout:
+                        default: 30s
+                        description: |-
+                          ScriptTimeout is the maximum wall-clock duration for a single script
+                          execution, including all tool calls. Bounds total execution time so a
+                          script with many slow tool calls cannot block indefinitely.
+                          Defaults to 30s if not specified or zero.
+                        pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
+                        type: string
                       stepLimit:
                         description: |-
                           StepLimit is the maximum number of Starlark execution steps per script.

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

@@ -1669,6 +1669,15 @@ spec:
                           ParallelMax is the maximum number of concurrent worker goroutines that
                           parallel() can use. Zero means the worker count matches the task count.
                         type: integer
+                      scriptTimeout:
+                        default: 30s
+                        description: |-
+                          ScriptTimeout is the maximum wall-clock duration for a single script
+                          execution, including all tool calls. Bounds total execution time so a
+                          script with many slow tool calls cannot block indefinitely.
+                          Defaults to 30s if not specified or zero.
+                        pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
+                        type: string
                       stepLimit:
                         description: |-
                           StepLimit is the maximum number of Starlark execution steps per script.

docs/operator/crd-api.md

@@ -25,6 +25,11 @@ type executor struct {
 
 // Execute runs a Starlark script against the bound tools.
 func (e *executor) Execute(ctx context.Context, script string, data map[string]interface{}) (*mcp.CallToolResult, error) {
+	// Apply per-script execution timeout to bound total wall-clock time
+	// including all tool calls.
+	ctx, cancel := context.WithTimeout(ctx, e.config.ScriptTimeout)
+	defer cancel()
+
 	globals := e.buildGlobals(ctx)
 
 	// Inject data arguments, rejecting any that shadow builtins or tools

pkg/script/executor.go

@@ -8,6 +8,7 @@ package script
 
 import (
 	"context"
+	"time"
 
 	"github.com/mark3labs/mcp-go/mcp"
 )
@@ -55,6 +56,10 @@ type Tool struct {
 	Call func(ctx context.Context, arguments map[string]interface{}) (*mcp.CallToolResult, error)
 }
 
+// DefaultScriptTimeout is the default maximum wall-clock duration for a
+// single script execution, including all tool calls.
+const DefaultScriptTimeout = 30 * time.Second
+
 // Config holds script execution parameters. A nil Config passed to New
 // uses sensible defaults for all fields.
 type Config struct {
@@ -66,6 +71,12 @@ type Config struct {
 	// ParallelMax is the maximum number of concurrent goroutines that
 	// parallel() can spawn. Zero means unlimited.
 	ParallelMax int
+
+	// ScriptTimeout is the maximum wall-clock duration for a single script
+	// execution, including all tool calls. Bounds total execution time so
+	// a script with many slow tool calls cannot block indefinitely.
+	// Zero uses DefaultScriptTimeout (30s).
+	ScriptTimeout time.Duration
 }
 
 // New creates an Executor bound to the given tools and configuration.
@@ -80,7 +91,10 @@ func New(tools []Tool, cfg *Config) Executor {
 
 func resolveConfig(cfg *Config) Config {
 	if cfg == nil {
-		return Config{StepLimit: DefaultStepLimit}
+		return Config{
+			StepLimit:     DefaultStepLimit,
+			ScriptTimeout: DefaultScriptTimeout,
+		}
 	}
 	c := *cfg
 	if c.StepLimit == 0 {
@@ -89,5 +103,8 @@ func resolveConfig(cfg *Config) Config {
 	if c.ParallelMax < 0 {
 		c.ParallelMax = 0
 	}
+	if c.ScriptTimeout == 0 {
+		c.ScriptTimeout = DefaultScriptTimeout
+	}
 	return c
 }

pkg/script/script.go

@@ -958,6 +958,14 @@ type ScriptEngineConfig struct {
 	// parallel() can use. Zero means the worker count matches the task count.
 	// +optional
 	ParallelMax int `json:"parallelMax,omitempty" yaml:"parallelMax,omitempty"`
+
+	// ScriptTimeout is the maximum wall-clock duration for a single script
+	// execution, including all tool calls. Bounds total execution time so a
+	// script with many slow tool calls cannot block indefinitely.
+	// Defaults to 30s if not specified or zero.
+	// +kubebuilder:default="30s"
+	// +optional
+	ScriptTimeout Duration `json:"scriptTimeout,omitempty" yaml:"scriptTimeout,omitempty"`
 }
 
 // Validator validates configuration.

pkg/vmcp/config/config.go

@@ -559,11 +559,16 @@ func (s *Server) Handler(_ context.Context) (http.Handler, error) {
 
 	// MCP endpoint - apply middleware chain (wrapping order, execution happens in reverse):
 	// Code wraps: auth+parser → audit → discovery → annotation-enrichment →
-	//   authz → script(+parser) → backend-enrichment → MCP-parsing → telemetry
+	//   script(+parser) → authz → backend-enrichment → MCP-parsing → telemetry
 	// Execution order: recovery → header-val → auth+parser → audit →
-	//   discovery → annotation-enrichment → authz → parser → script →
-	//   backend-enrichment → MCP-parsing → telemetry → handler
-	// Note: script middleware composes its own parser internally.
+	//   discovery → annotation-enrichment → parser → script →
+	//   authz → backend-enrichment → MCP-parsing → telemetry → handler
+	//
+	// Script middleware sits between annotation-enrichment and authz:
+	// - Auth (identity) runs before script — requests are authenticated
+	// - Authz runs AFTER script — execute_tool_script itself is not authorized,
+	//   but inner tool calls dispatched from scripts flow through authz
+	// - Script middleware composes its own parser internally
 
 	var mcpHandler http.Handler = streamableServer