@chrrxs/robloxstudio-mcp 2.22.4 → 2.23.0

package/studio-plugin/src/modules/AssetSanitizationPolicy.ts

@@ -0,0 +1,127 @@
+export interface ImportedAssetInstance {
+	IsA(className: string): boolean;
+	GetDescendants(): ImportedAssetInstance[];
+}
+
+export interface ForbiddenImportScan {
+	scripts: ImportedAssetInstance[];
+	packageLinks: ImportedAssetInstance[];
+}
+
+export interface AssetSanitizationOperations {
+	forceUnparent: (root: ImportedAssetInstance) => boolean;
+	destroy: (instance: ImportedAssetInstance) => boolean;
+}
+
+export interface AssetSanitizationResult {
+	success: boolean;
+	removedScriptCount: number;
+	removedPackageLinkCount: number;
+	remainingScriptCount: number;
+	remainingPackageLinkCount: number;
+	error?: string;
+}
+
+function countInstances(instances: ImportedAssetInstance[]): number {
+	let count = 0;
+	for (const _instance of instances) count++;
+	return count;
+}
+
+export function scanForbiddenImportedInstances(root: ImportedAssetInstance): ForbiddenImportScan {
+	const scripts: ImportedAssetInstance[] = [];
+	const packageLinks: ImportedAssetInstance[] = [];
+
+	function inspect(instance: ImportedAssetInstance) {
+		// IsA("LuaSourceContainer") covers Script, LocalScript, ModuleScript,
+		// and any future script-bearing subclass. Names, source, creator,
+		// reputation, and hierarchy depth are deliberately irrelevant.
+		if (instance.IsA("LuaSourceContainer")) {
+			scripts.push(instance);
+		}
+		if (instance.IsA("PackageLink")) {
+			packageLinks.push(instance);
+		}
+	}
+
+	inspect(root);
+	// GetDescendants performs an engine-level, unlimited-depth traversal.
+	// Never replace this security scan with a depth-limited tree walk.
+	for (const descendant of root.GetDescendants()) {
+		inspect(descendant);
+	}
+
+	return { scripts, packageLinks };
+}
+
+export function sanitizeLoadedAsset(
+	root: ImportedAssetInstance,
+	operations: AssetSanitizationOperations,
+): AssetSanitizationResult {
+	if (!operations.forceUnparent(root)) {
+		operations.destroy(root);
+		return {
+			success: false,
+			removedScriptCount: 0,
+			removedPackageLinkCount: 0,
+			remainingScriptCount: 0,
+			remainingPackageLinkCount: 0,
+			error: "Loaded asset could not be kept unparented for sanitization.",
+		};
+	}
+
+	const firstScan = scanForbiddenImportedInstances(root);
+	const firstScriptCount = countInstances(firstScan.scripts);
+	const firstPackageLinkCount = countInstances(firstScan.packageLinks);
+
+	// A forbidden root cannot be removed while preserving an import wrapper.
+	// Destroy the whole load and fail closed.
+	if (root.IsA("LuaSourceContainer") || root.IsA("PackageLink")) {
+		const rootWasScript = root.IsA("LuaSourceContainer");
+		const rootWasPackageLink = root.IsA("PackageLink");
+		operations.destroy(root);
+		return {
+			success: false,
+			removedScriptCount: firstScriptCount,
+			removedPackageLinkCount: firstPackageLinkCount,
+			remainingScriptCount: rootWasScript ? 1 : 0,
+			remainingPackageLinkCount: rootWasPackageLink ? 1 : 0,
+			error: "Loaded asset root is a forbidden executable or package-link instance.",
+		};
+	}
+
+	let removedScriptCount = 0;
+	for (const scriptInstance of firstScan.scripts) {
+		if (operations.destroy(scriptInstance)) removedScriptCount++;
+	}
+
+	let removedPackageLinkCount = 0;
+	for (const packageLink of firstScan.packageLinks) {
+		if (operations.destroy(packageLink)) removedPackageLinkCount++;
+	}
+
+	// Mandatory second unlimited-depth scan. If any forbidden instance
+	// survived, destroy the entire imported root and insert nothing.
+	const verificationScan = scanForbiddenImportedInstances(root);
+	const remainingScriptCount = countInstances(verificationScan.scripts);
+	const remainingPackageLinkCount = countInstances(verificationScan.packageLinks);
+	if (remainingScriptCount > 0 || remainingPackageLinkCount > 0) {
+		operations.destroy(root);
+		return {
+			success: false,
+			removedScriptCount,
+			removedPackageLinkCount,
+			remainingScriptCount,
+			remainingPackageLinkCount,
+			error: "Asset sanitization verification failed; the entire imported asset was destroyed.",
+		};
+	}
+
+	return {
+		success: true,
+		removedScriptCount,
+		removedPackageLinkCount,
+		remainingScriptCount: 0,
+		remainingPackageLinkCount: 0,
+	};
+}

package/studio-plugin/src/modules/handlers/AssetHandlers.ts

@@ -1,5 +1,11 @@
 import Utils from "../Utils";
 import Recording from "../Recording";
+import {
+	sanitizeLoadedAsset,
+	scanForbiddenImportedInstances,
+	type AssetSanitizationOperations,
+	type ImportedAssetInstance,
+} from "../AssetSanitizationPolicy";
 
 const AssetService = game.GetService("AssetService");
 const ChangeHistoryService = game.GetService("ChangeHistoryService");
@@ -8,6 +14,41 @@ const Selection = game.GetService("Selection");
 const { getInstancePath, getInstanceByPath } = Utils;
 const { beginRecording, finishRecording } = Recording;
 
+const THIRD_PARTY_ASSET_SETTING_HINT =
+	'\nTo load public Creator Store assets that you do not own, enable "Allow Loading Third Party Assets" in Game Settings > Security.';
+
+function destroyImportedRoot(root: Instance) {
+	pcall(() => {
+		root.Destroy();
+	});
+}
+
+function formatAssetLoadFailure(assetId: number, loadError: unknown): string {
+	const [settingReadable, allowInsertFreeAssets] = pcall(() => {
+		return (AssetService as unknown as { AllowInsertFreeAssets: boolean }).AllowInsertFreeAssets;
+	});
+	const settingHint = settingReadable && allowInsertFreeAssets === true
+		? ""
+		: THIRD_PARTY_ASSET_SETTING_HINT;
+	return `Failed to load asset ${assetId}: ${tostring(loadError)}${settingHint}`;
+}
+
+const sanitizationOperations: AssetSanitizationOperations = {
+	forceUnparent: (root: ImportedAssetInstance) => {
+		const instance = root as Instance;
+		const [unparentedOk] = pcall(() => {
+			instance.Parent = undefined;
+		});
+		return unparentedOk && instance.Parent === undefined;
+	},
+	destroy: (instance: ImportedAssetInstance) => {
+		const [destroyed] = pcall(() => {
+			(instance as Instance).Destroy();
+		});
+		return destroyed;
+	},
+};
+
 function insertAsset(requestData: Record<string, unknown>) {
 	const assetId = requestData.assetId as number;
 	const parentPath = (requestData.parentPath as string) ?? "game.Workspace";
@@ -25,21 +66,29 @@ function insertAsset(requestData: Record<string, unknown>) {
 	const recordingId = beginRecording(`Insert asset ${assetId}`);
 
 	let wrapperModel: Instance | undefined;
+	const insertedInstances: Instance[] = [];
 	const [insertSuccess, insertResult] = pcall(() => {
-		const loadedWrapper = (AssetService as unknown as { LoadAssetAsync(id: number): Instance }).LoadAssetAsync(assetId);
+		const [loadSuccess, loadResult] = pcall(() => {
+			return (AssetService as unknown as { LoadAssetAsync(id: number): Instance }).LoadAssetAsync(assetId);
+		});
+		if (!loadSuccess || !loadResult) {
+			error(formatAssetLoadFailure(assetId, loadResult), 0);
+		}
+		const loadedWrapper = loadResult as Instance;
 		wrapperModel = loadedWrapper;
 
-		const insertedInstances: Instance[] = [];
-		const children = loadedWrapper.GetChildren();
-
-		for (const child of children) {
-			child.Parent = parentInstance;
-			insertedInstances.push(child);
+		const sanitization = sanitizeLoadedAsset(loadedWrapper, sanitizationOperations);
+		if (!sanitization.success) {
+			error(sanitization.error ?? "Asset sanitization failed.", 0);
 		}
 
+		const children = loadedWrapper.GetChildren();
+
+		// Position while every sanitized child is still contained by the
+		// unparented wrapper. Nothing reaches the DataModel before verification.
 		if (position) {
 			const pos = new Vector3(position.x ?? 0, position.y ?? 0, position.z ?? 0);
-			for (const inst of insertedInstances) {
+			for (const inst of children) {
 				if (inst.IsA("BasePart")) {
 					inst.Position = pos;
 				} else if (inst.IsA("Model")) {
@@ -55,6 +104,13 @@ function insertAsset(requestData: Record<string, unknown>) {
 			}
 		}
 
+		// This is the first point at which imported content is parented into
+		// Studio. Both unlimited-depth scans have already passed.
+		for (const child of children) {
+			child.Parent = parentInstance;
+			insertedInstances.push(child);
+		}
+
 		pcall(() => {
 			Selection.Set(insertedInstances);
 		});
@@ -71,9 +127,23 @@ function insertAsset(requestData: Record<string, unknown>) {
 			parentPath,
 			insertedCount: insertedInstances.size(),
 			instances: resultInstances,
+			sanitization: {
+				removedScriptCount: sanitization.removedScriptCount,
+				removedPackageLinkCount: sanitization.removedPackageLinkCount,
+				verifiedClean: true,
+			},
 		};
 	});
 
+	if (!insertSuccess) {
+		// Roll back any partially-parented children if a later operation failed.
+		for (const inserted of insertedInstances) {
+			pcall(() => {
+				inserted.Destroy();
+			});
+		}
+	}
+
 	if (wrapperModel) {
 		pcall(() => {
 			wrapperModel!.Destroy();
@@ -91,8 +161,8 @@ function insertAsset(requestData: Record<string, unknown>) {
 
 function previewAsset(requestData: Record<string, unknown>) {
 	const assetId = requestData.assetId as number;
-	const includeProperties = (requestData.includeProperties as boolean) ?? true;
-	const maxDepth = (requestData.maxDepth as number) ?? 10;
+	const includeProperties = (requestData.includeProperties as boolean) ?? false;
+	const maxDepth = (requestData.maxDepth as number) ?? 4;
 
 	if (!assetId) {
 		return { error: "assetId is required" };
@@ -103,27 +173,100 @@ function previewAsset(requestData: Record<string, unknown>) {
 	});
 
 	if (!loadSuccess || !wrapperModel) {
-		return { error: `Failed to load asset ${assetId}: ${tostring(wrapperModel)}` };
+		return { error: formatAssetLoadFailure(assetId, wrapperModel) };
+	}
+
+	// Previewed assets never enter the DataModel.
+	const [unparentedOk] = pcall(() => {
+		(wrapperModel as Instance).Parent = undefined;
+	});
+	if (!unparentedOk || (wrapperModel as Instance).Parent !== undefined) {
+		destroyImportedRoot(wrapperModel as Instance);
+		return { error: `Failed to keep asset ${assetId} unparented for preview` };
 	}
 
-	// Stats tracking
+	// Security and visual-capability tracking always scan the full descendant
+	// hierarchy. maxDepth only affects the display tree below.
 	let totalInstances = 0;
 	const classCounts: Record<string, number> = {};
-	let hasScripts = false;
 	let hasAnimations = false;
 	let hasSounds = false;
 	let hasParticles = false;
-
-	function buildHierarchy(instance: Instance, depth: number): Record<string, unknown> {
+	let hasVfx = false;
+	let hasDecalsOrTextures = false;
+	let hasMeshes = false;
+	let hasLights = false;
+	let hasAttachments = false;
+	const soundReferences: Record<string, unknown>[] = [];
+	const uniqueSoundContentIds = new Set<string>();
+
+	function recordSummary(instance: Instance) {
 		totalInstances++;
-
 		const className = instance.ClassName;
 		classCounts[className] = (classCounts[className] ?? 0) + 1;
 
-		if (instance.IsA("LuaSourceContainer")) hasScripts = true;
 		if (className === "Animation" || className === "AnimationController" || className === "Animator") hasAnimations = true;
-		if (instance.IsA("Sound")) hasSounds = true;
-		if (className === "ParticleEmitter" || className === "Fire" || className === "Smoke" || className === "Sparkles") hasParticles = true;
+		if (instance.IsA("Sound")) {
+			hasSounds = true;
+			const sound = instance as Sound;
+			const soundId = sound.SoundId;
+			if (soundId !== "") uniqueSoundContentIds.add(soundId);
+			soundReferences.push({
+				path: sound.GetFullName(),
+				name: sound.Name,
+				className,
+				soundId,
+				volume: sound.Volume,
+				playbackSpeed: sound.PlaybackSpeed,
+				looped: sound.Looped,
+				isLoaded: sound.IsLoaded,
+				timeLength: sound.TimeLength,
+				rollOffMode: tostring(sound.RollOffMode),
+				rollOffMinDistance: sound.RollOffMinDistance,
+				rollOffMaxDistance: sound.RollOffMaxDistance,
+			});
+		} else if (instance.IsA("AudioPlayer")) {
+			hasSounds = true;
+			const audioPlayer = instance as AudioPlayer;
+			const soundId = tostring(audioPlayer.Asset);
+			if (soundId !== "") uniqueSoundContentIds.add(soundId);
+			soundReferences.push({
+				path: audioPlayer.GetFullName(),
+				name: audioPlayer.Name,
+				className,
+				soundId,
+				volume: audioPlayer.Volume,
+				playbackSpeed: audioPlayer.PlaybackSpeed,
+				looped: audioPlayer.Looping,
+				autoPlay: audioPlayer.AutoPlay,
+				isLoaded: audioPlayer.IsReady,
+				timeLength: audioPlayer.TimeLength,
+			});
+		}
+		if (
+			instance.IsA("ParticleEmitter") ||
+			className === "Fire" ||
+			className === "Smoke" ||
+			className === "Sparkles"
+		) {
+			hasParticles = true;
+			hasVfx = true;
+		}
+		if (instance.IsA("Beam") || instance.IsA("Trail")) hasVfx = true;
+		if (instance.IsA("Decal") || instance.IsA("Texture")) hasDecalsOrTextures = true;
+		if (instance.IsA("MeshPart") || instance.IsA("SpecialMesh")) hasMeshes = true;
+		if (instance.IsA("Light")) hasLights = true;
+		if (instance.IsA("Attachment")) hasAttachments = true;
+	}
+
+	recordSummary(wrapperModel as Instance);
+	for (const descendant of (wrapperModel as Instance).GetDescendants()) {
+		recordSummary(descendant);
+	}
+	const forbiddenScan = scanForbiddenImportedInstances(wrapperModel as Instance);
+
+	function buildHierarchy(instance: Instance, depth: number): Record<string, unknown> {
+		const className = instance.ClassName;
 
 		const node: Record<string, unknown> = {
 			name: instance.Name,
@@ -155,15 +298,6 @@ function previewAsset(requestData: Record<string, unknown>) {
 				}
 			}
 
-			if (instance.IsA("LuaSourceContainer")) {
-				const [ok, src] = pcall(() => (instance as unknown as { Source: string }).Source);
-				if (ok && src) {
-					const preview = string.sub(src, 1, 200);
-					props.sourcePreview = preview;
-					props.sourceLength = src.size();
-				}
-			}
-
 			if (className === "Decal" || className === "Texture") {
 				const [ok, texId] = pcall(() => (instance as unknown as { Texture: string }).Texture);
 				if (ok) props.texture = texId;
@@ -171,6 +305,8 @@ function previewAsset(requestData: Record<string, unknown>) {
 
 			if (instance.IsA("Sound")) {
 				props.soundId = (instance as Sound).SoundId;
+			} else if (instance.IsA("AudioPlayer")) {
+				props.soundId = tostring((instance as AudioPlayer).Asset);
 			}
 
 			// Only include props if there are any
@@ -213,13 +349,27 @@ function previewAsset(requestData: Record<string, unknown>) {
 			success: true,
 			assetId,
 			hierarchy: hierarchyRoots,
+			sounds: soundReferences,
 			summary: {
 				totalInstances,
 				classCounts,
-				hasScripts,
+				hasScripts: forbiddenScan.scripts.size() > 0,
+				scriptCount: forbiddenScan.scripts.size(),
+				hasPackageLinks: forbiddenScan.packageLinks.size() > 0,
+				packageLinkCount: forbiddenScan.packageLinks.size(),
 				hasAnimations,
 				hasSounds,
+				soundCount: soundReferences.size(),
+				uniqueSoundContentIdCount: uniqueSoundContentIds.size(),
 				hasParticles,
+				hasVfx,
+				hasDecalsOrTextures,
+				hasMeshes,
+				hasLights,
+				hasAttachments,
+				securityScanDepth: "unlimited",
+				scriptSourceExposed: false,
+				insertPolicy: "All LuaSourceContainer and PackageLink instances are stripped and verified before insertion.",
 			},
 		};
 	});