harden(handlers): route every path-taking handler through McpPathValidator

The strong traversal validator from #347 was wired into only filesystem and
script handlers; ~12 other path-taking handlers used a bare begins_with("res://")
check (which does not reject "..") or no check at all (relying solely on
ResourceLoader.exists/load). This unifies all of them on McpPathValidator and
extends the validator with two checks.

Validator (utils/path_validator.gd):
- Reject embedded null bytes (truncation trap — the path written could differ
  from the one validated).
- New for_write flag: write callers additionally refuse res://project.godot,
  the res://.godot/ metadata dir, and .import sidecars (overwriting these
  corrupts the project / import cache). Reads still permit inspecting them.
  Signature is backward-compatible (for_write defaults to false).

Writers now validate with for_write=true (closes the traversal-write primitive):
  resource_io.save_to_disk (backs resource/environment/texture/curve saves),
  scene create_scene/save_scene_as, material/theme save helpers, filesystem
  write_text, script create/patch.

Load/read sites now validate (closes the unvalidated-load surface, incl. the
@tool-script-execution risk from open_scene/create_node):
  resource load/assign + nested object-property loads, scene open_scene,
  script attach_script, node create_node scene_path + set_property resource
  values, audio set_stream + list root, material assign/shader/list,
  ui theme + stylebox, autoload path, curve set_points, particle mesh/
  material/texture, material_values.load_texture.

Path-validation rejections report VALUE_OUT_OF_RANGE (the code these handlers
already used for "must start with res://"), keeping the INVALID_PARAMS catch-all
count under the audit-v2 #21 ceiling enforced by test_error_code_distribution.
The four pre-existing validator sites that already wrapped errors as
INVALID_PARAMS (filesystem, script create/read/patch/find, resource_io save,
material _validate_material_path) are left unchanged.

set_stream and the other load handlers now reject user:// (consistent with the
validator's existing test_user_prefix_rejected policy); the audio test fixture
moves from user:// to a res:// .tres registered via EditorFileSystem.update_file.

Tests (run against live Godot 4.6.3): validator unit tests for null-byte +
write blocklist + read-allows; scene traversal/manifest-overwrite rejection.
All affected suites pass (path_validator/scene/resource/node/material/theme/
curve/particle/ui/audio/autoload/filesystem/script). test_error_code_distribution
passes. Parse check clean.

Addresses advisory GHSA-p5x8-v25q-qw69 (GH-1, GH-2, GH-3, GH-4).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: dsarno

plugin/addons/godot_ai/handlers/audio_handler.gd

@@ -101,6 +101,10 @@ func set_stream(params: Dictionary) -> Dictionary:
 	if stream_path.is_empty():
 		return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: stream_path")
 
+	var stream_path_err := McpPathValidator.validate_resource_path(stream_path)
+	if not stream_path_err.is_empty():
+		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, stream_path_err)
+
 	var resolved := _resolve_player(player_path)
 	if resolved.has("error"):
 		return resolved
@@ -259,8 +263,9 @@ func list_streams(params: Dictionary) -> Dictionary:
 	var root: String = params.get("root", "res://")
 	var include_duration: bool = bool(params.get("include_duration", true))
 
-	if not root.begins_with("res://"):
-		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "root must start with res://")
+	var root_err := McpPathValidator.validate_resource_path(root)
+	if not root_err.is_empty():
+		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, root_err)
 
 	var efs := EditorInterface.get_resource_filesystem()
 	if efs == null:

plugin/addons/godot_ai/handlers/autoload_handler.gd

@@ -33,8 +33,9 @@ func add_autoload(params: Dictionary) -> Dictionary:
 		return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: name")
 	if path.is_empty():
 		return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: path")
-	if not path.begins_with("res://"):
-		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Path must start with res:// (got: %s)" % path)
+	var path_err := McpPathValidator.validate_resource_path(path)
+	if not path_err.is_empty():
+		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, path_err)
 	if not FileAccess.file_exists(path):
 		return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "File not found: %s" % path)
 

plugin/addons/godot_ai/handlers/curve_handler.gd

@@ -38,6 +38,9 @@ func set_points(params: Dictionary) -> Dictionary:
 	var node: Node = null
 	var curve_created := false
 	if has_file_target:
+		var rpath_err := McpPathValidator.validate_resource_path(resource_path, true)
+		if not rpath_err.is_empty():
+			return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, rpath_err)
 		if not ResourceLoader.exists(resource_path):
 			return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Resource not found: %s" % resource_path)
 		# ResourceLoader.load() returns Godot's cached Resource. Duplicate

plugin/addons/godot_ai/handlers/filesystem_handler.gd

@@ -37,7 +37,7 @@ func write_file(params: Dictionary) -> Dictionary:
 	var path: String = params.get("path", "")
 	var content: String = params.get("content", "")
 
-	var path_err := McpPathValidator.validate_resource_path(path)
+	var path_err := McpPathValidator.validate_resource_path(path, true)
 	if not path_err.is_empty():
 		return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, path_err)
 

plugin/addons/godot_ai/handlers/material_handler.gd

@@ -67,6 +67,9 @@ func create_material(params: Dictionary) -> Dictionary:
 				ErrorCodes.INVALID_PARAMS,
 				"ShaderMaterial requires shader_path (res:// path to a .gdshader)"
 			)
+		var shader_path_err := McpPathValidator.validate_resource_path(shader_path)
+		if not shader_path_err.is_empty():
+			return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, shader_path_err)
 		if not ResourceLoader.exists(shader_path):
 			return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Shader not found: %s" % shader_path)
 		var shader_res := ResourceLoader.load(shader_path)
@@ -297,8 +300,9 @@ func list_materials(params: Dictionary) -> Dictionary:
 	var root: String = params.get("root", "res://")
 	var type_filter: String = params.get("type", "")
 
-	if not root.begins_with("res://"):
-		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "root must start with res://")
+	var root_err := McpPathValidator.validate_resource_path(root)
+	if not root_err.is_empty():
+		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, root_err)
 
 	var efs := EditorInterface.get_resource_filesystem()
 	if efs == null:
@@ -366,6 +370,9 @@ func assign_material(params: Dictionary) -> Dictionary:
 	var mat: Material = null
 	var material_created := false
 	if not resource_path.is_empty():
+		var rpath_err := McpPathValidator.validate_resource_path(resource_path)
+		if not rpath_err.is_empty():
+			return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, rpath_err)
 		if not ResourceLoader.exists(resource_path):
 			if create_if_missing:
 				# We'd need to create a new file here — refuse; callers should
@@ -668,8 +675,9 @@ static func _reverse_type_map() -> Dictionary:
 static func _validate_material_path(path: String, param_name: String) -> Variant:
 	if path.is_empty():
 		return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: %s" % param_name)
-	if not path.begins_with("res://"):
-		return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, "%s must start with res:// (got %s)" % [param_name, path])
+	var path_err := McpPathValidator.validate_resource_path(path, true)
+	if not path_err.is_empty():
+		return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, "%s: %s" % [param_name, path_err])
 	var has_suffix := false
 	for s in _SUPPORTED_SUFFIXES:
 		if path.ends_with(s):

plugin/addons/godot_ai/handlers/material_values.gd

@@ -153,10 +153,13 @@ static func parse_gradient(value: Variant) -> Variant:
 	return grad
 
 
-## Load a Texture2D from a res:// path. Returns null on failure.
+## Load a Texture2D from a res:// path. Returns null on failure (including a
+## path that fails res:// confinement / traversal validation).
 static func load_texture(path: String) -> Texture2D:
 	if path.is_empty():
 		return null
+	if not McpPathValidator.validate_resource_path(path).is_empty():
+		return null
 	if not ResourceLoader.exists(path):
 		return null
 	var res := ResourceLoader.load(path)

plugin/addons/godot_ai/handlers/node_handler.gd

@@ -39,8 +39,9 @@ func create_node(params: Dictionary) -> Dictionary:
 		# scene instance (foldout icon, the .tscn stores a reference instead of
 		# an exploded subtree). Descendants remain owned by their sub-scene;
 		# setting their owner to our scene_root would break the instance link.
-		if not scene_path.begins_with("res://"):
-			return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "scene_path must start with res://")
+		var scene_path_err := McpPathValidator.validate_resource_path(scene_path)
+		if not scene_path_err.is_empty():
+			return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, scene_path_err)
 		if not ResourceLoader.exists(scene_path):
 			return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Scene not found: %s" % scene_path)
 		var packed_scene = ResourceLoader.load(scene_path)
@@ -222,6 +223,9 @@ func set_property(params: Dictionary) -> Dictionary:
 		if value == "":
 			value = null
 		else:
+			var value_path_err := McpPathValidator.validate_resource_path(value)
+			if not value_path_err.is_empty():
+				return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, value_path_err)
 			if not ResourceLoader.exists(value):
 				return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Resource not found: %s" % value)
 			var loaded := ResourceLoader.load(value)

plugin/addons/godot_ai/handlers/particle_handler.gd

@@ -341,6 +341,9 @@ func _set_draw_pass_gpu_3d(node: GPUParticles3D, node_path: String, pass_idx: in
 	if int(node.draw_passes) >= pass_idx:
 		existing_mesh = node.get(property_name) as Mesh
 	if not mesh_path.is_empty():
+		var mesh_path_err := McpPathValidator.validate_resource_path(mesh_path)
+		if not mesh_path_err.is_empty():
+			return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, mesh_path_err)
 		if not ResourceLoader.exists(mesh_path):
 			return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Mesh not found: %s" % mesh_path)
 		var loaded := ResourceLoader.load(mesh_path)
@@ -357,6 +360,9 @@ func _set_draw_pass_gpu_3d(node: GPUParticles3D, node_path: String, pass_idx: in
 
 	var material: Material = null
 	if not material_path.is_empty():
+		var material_path_err := McpPathValidator.validate_resource_path(material_path)
+		if not material_path_err.is_empty():
+			return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, material_path_err)
 		if not ResourceLoader.exists(material_path):
 			return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Material not found: %s" % material_path)
 		var loaded_mat := ResourceLoader.load(material_path)
@@ -407,6 +413,9 @@ func _set_draw_pass_cpu_3d(node: CPUParticles3D, node_path: String, mesh_path: S
 	var mesh: Mesh = node.mesh
 	var old_mesh: Mesh = mesh
 	if not mesh_path.is_empty():
+		var mesh_path_err := McpPathValidator.validate_resource_path(mesh_path)
+		if not mesh_path_err.is_empty():
+			return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, mesh_path_err)
 		if not ResourceLoader.exists(mesh_path):
 			return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Mesh not found: %s" % mesh_path)
 		var loaded := ResourceLoader.load(mesh_path)
@@ -417,6 +426,9 @@ func _set_draw_pass_cpu_3d(node: CPUParticles3D, node_path: String, mesh_path: S
 	var material: Material = null
 	var old_material: Material = node.material_override
 	if not material_path.is_empty():
+		var material_path_err := McpPathValidator.validate_resource_path(material_path)
+		if not material_path_err.is_empty():
+			return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, material_path_err)
 		if not ResourceLoader.exists(material_path):
 			return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Material not found: %s" % material_path)
 		var loaded_mat := ResourceLoader.load(material_path)
@@ -447,6 +459,9 @@ func _set_draw_pass_cpu_3d(node: CPUParticles3D, node_path: String, mesh_path: S
 func _set_draw_pass_2d(node: Node, node_path: String, texture_path: String) -> Dictionary:
 	if texture_path.is_empty():
 		return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "2D particles require texture param")
+	var texture_path_err := McpPathValidator.validate_resource_path(texture_path)
+	if not texture_path_err.is_empty():
+		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, texture_path_err)
 	if not ResourceLoader.exists(texture_path):
 		return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Texture not found: %s" % texture_path)
 	var tex := ResourceLoader.load(texture_path)

plugin/addons/godot_ai/handlers/resource_handler.gd

@@ -64,8 +64,9 @@ func load_resource(params: Dictionary) -> Dictionary:
 	if path.is_empty():
 		return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: path")
 
-	if not path.begins_with("res://"):
-		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Path must start with res://")
+	var path_err := McpPathValidator.validate_resource_path(path)
+	if not path_err.is_empty():
+		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, path_err)
 
 	if not ResourceLoader.exists(path):
 		return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Resource not found: %s" % path)
@@ -112,6 +113,10 @@ func assign_resource(params: Dictionary) -> Dictionary:
 	if resource_path.is_empty():
 		return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: resource_path")
 
+	var rpath_err := McpPathValidator.validate_resource_path(resource_path)
+	if not rpath_err.is_empty():
+		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, rpath_err)
+
 	var _resolved := McpNodeValidator.resolve_or_error(node_path, "node_path")
 	if _resolved.has("error"):
 		return _resolved
@@ -248,6 +253,12 @@ static func _apply_resource_properties(res: Resource, properties: Dictionary) ->
 			if v == "":
 				v = null
 			else:
+				var vpath_err := McpPathValidator.validate_resource_path(v)
+				if not vpath_err.is_empty():
+					return ErrorCodes.make(
+						ErrorCodes.VALUE_OUT_OF_RANGE,
+						"%s (property '%s')" % [vpath_err, key]
+					)
 				var loaded := ResourceLoader.load(v)
 				if loaded == null:
 					return ErrorCodes.make(

plugin/addons/godot_ai/handlers/scene_handler.gd

@@ -90,8 +90,9 @@ func create_scene(params: Dictionary) -> Dictionary:
 	if path.is_empty():
 		return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: path")
 
-	if not path.begins_with("res://"):
-		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Path must start with res://")
+	var path_err := McpPathValidator.validate_resource_path(path, true)
+	if not path_err.is_empty():
+		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, path_err)
 
 	if not path.ends_with(".tscn") and not path.ends_with(".scn"):
 		path += ".tscn"
@@ -148,6 +149,10 @@ func open_scene(params: Dictionary) -> Dictionary:
 	if path.is_empty():
 		return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: path")
 
+	var path_err := McpPathValidator.validate_resource_path(path)
+	if not path_err.is_empty():
+		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, path_err)
+
 	if not ResourceLoader.exists(path):
 		return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Scene not found: %s" % path)
 
@@ -202,8 +207,9 @@ func save_scene_as(params: Dictionary) -> Dictionary:
 	if path.is_empty():
 		return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: path")
 
-	if not path.begins_with("res://"):
-		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Path must start with res://")
+	var path_err := McpPathValidator.validate_resource_path(path, true)
+	if not path_err.is_empty():
+		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, path_err)
 
 	if not path.ends_with(".tscn") and not path.ends_with(".scn"):
 		path += ".tscn"