feat: add validateShellPath export for robust shell validation

- Created validateShellPath as a public API for shell path validation
- Refactored internal validation logic into isShellAllowedInternal
- Added comprehensive test coverage for all edge cases
- Maintains backward compatibility with deprecated isShellAllowed
- Handles arrays, strings, null, undefined, and nested arrays gracefully

Author: roomote

src/utils/__tests__/shell.test.ts

@@ -361,4 +361,132 @@ describe("shell utilities", () => {
 			expect(result).toBe("C:\\Windows\\System32\\cmd.exe")
 		})
 	})
+
+	describe("validateShellPath", () => {
+		it("should validate string shell paths", async () => {
+			const { validateShellPath } = await import("../shell")
+
+			// Valid shells
+			expect(validateShellPath("/bin/bash")).toBe(true)
+			expect(validateShellPath("/bin/zsh")).toBe(true)
+			expect(validateShellPath("C:\\Windows\\System32\\cmd.exe")).toBe(true)
+			expect(validateShellPath("C:\\Program Files\\PowerShell\\7\\pwsh.exe")).toBe(true)
+
+			// Invalid shells
+			expect(validateShellPath("/usr/bin/malicious")).toBe(false)
+			expect(validateShellPath("C:\\malicious\\shell.exe")).toBe(false)
+		})
+
+		it("should validate array shell paths using first element", async () => {
+			const { validateShellPath } = await import("../shell")
+
+			// Valid array with allowed first element
+			expect(validateShellPath(["/bin/bash", "/bin/sh"])).toBe(true)
+			expect(validateShellPath(["C:\\Windows\\System32\\cmd.exe", "cmd"])).toBe(true)
+
+			// Invalid array with disallowed first element
+			expect(validateShellPath(["/usr/bin/malicious", "/bin/bash"])).toBe(false)
+			expect(validateShellPath(["C:\\malicious\\shell.exe", "C:\\Windows\\System32\\cmd.exe"])).toBe(false)
+		})
+
+		it("should handle empty arrays", async () => {
+			const { validateShellPath } = await import("../shell")
+
+			expect(validateShellPath([])).toBe(false)
+		})
+
+		it("should handle null and undefined", async () => {
+			const { validateShellPath } = await import("../shell")
+
+			expect(validateShellPath(null)).toBe(false)
+			expect(validateShellPath(undefined)).toBe(false)
+		})
+
+		it("should handle nested arrays (edge case)", async () => {
+			const { validateShellPath } = await import("../shell")
+
+			// Nested array - should recursively check first element
+			expect(validateShellPath([["/bin/bash"]] as any)).toBe(true)
+			expect(validateShellPath([["/usr/bin/malicious"]] as any)).toBe(false)
+			expect(validateShellPath([["C:\\Windows\\System32\\cmd.exe"]] as any)).toBe(true)
+		})
+
+		it("should handle empty strings", async () => {
+			const { validateShellPath } = await import("../shell")
+
+			expect(validateShellPath("")).toBe(false)
+			expect(validateShellPath([""])).toBe(false)
+		})
+
+		it("should handle case-insensitive comparison on Windows", async () => {
+			// Set platform to Windows
+			Object.defineProperty(process, "platform", {
+				value: "win32",
+				configurable: true,
+			})
+
+			const { validateShellPath } = await import("../shell")
+
+			// Different case variations should all be valid
+			expect(validateShellPath("c:\\windows\\system32\\cmd.exe")).toBe(true)
+			expect(validateShellPath("C:\\WINDOWS\\SYSTEM32\\CMD.EXE")).toBe(true)
+			expect(validateShellPath("C:\\Windows\\System32\\CMD.exe")).toBe(true)
+		})
+
+		it("should handle case-sensitive comparison on Unix", async () => {
+			// Set platform to Linux
+			Object.defineProperty(process, "platform", {
+				value: "linux",
+				configurable: true,
+			})
+
+			const { validateShellPath } = await import("../shell")
+
+			// Exact case match required
+			expect(validateShellPath("/bin/bash")).toBe(true)
+			expect(validateShellPath("/BIN/BASH")).toBe(false)
+			expect(validateShellPath("/Bin/Bash")).toBe(false)
+		})
+
+		it("should normalize paths before validation", async () => {
+			const { validateShellPath } = await import("../shell")
+
+			// Paths with extra slashes or dots should be normalized
+			expect(validateShellPath("/bin//bash")).toBe(true)
+			expect(validateShellPath("/bin/./bash")).toBe(true)
+
+			// Windows paths with backslashes
+			if (process.platform === "win32") {
+				expect(validateShellPath("C:/Windows/System32/cmd.exe")).toBe(true)
+			}
+		})
+
+		it("should handle arrays with mixed valid and invalid paths", async () => {
+			const { validateShellPath } = await import("../shell")
+
+			// Only the first element matters
+			expect(validateShellPath(["/bin/bash", "/usr/bin/malicious", "/bin/sh"])).toBe(true)
+			expect(validateShellPath(["/usr/bin/malicious", "/bin/bash", "/bin/sh"])).toBe(false)
+		})
+
+		it("should reject non-string, non-array types", async () => {
+			const { validateShellPath } = await import("../shell")
+
+			// Numbers, objects, etc. should be rejected
+			expect(validateShellPath(123 as any)).toBe(false)
+			expect(validateShellPath({ path: "/bin/bash" } as any)).toBe(false)
+			expect(validateShellPath(true as any)).toBe(false)
+		})
+
+		it("should handle arrays containing non-string elements", async () => {
+			const { validateShellPath } = await import("../shell")
+
+			// Array with null/undefined first element
+			expect(validateShellPath([null, "/bin/bash"] as any)).toBe(false)
+			expect(validateShellPath([undefined, "/bin/bash"] as any)).toBe(false)
+
+			// Array with number first element
+			expect(validateShellPath([123, "/bin/bash"] as any)).toBe(false)
+		})
+	})
 })

src/utils/shell.ts

@@ -289,16 +289,13 @@ function getShellFromEnv(): string | null {
 // -----------------------------------------------------
 
 /**
- * Validates if a shell path is in the allowlist to prevent arbitrary command execution.
- * Can handle both string and array inputs (arrays from VSCode API).
+ * Internal validation function that checks if a shell path is in the allowlist.
+ * This is the core validation logic that operates on normalized string paths.
  */
-function isShellAllowed(shellPath: string | string[]): boolean {
-	// Handle array input by checking the first element
-	const pathToCheck = Array.isArray(shellPath) ? (shellPath.length > 0 ? shellPath[0] : null) : shellPath
-
-	if (!pathToCheck) return false
+function isShellAllowedInternal(shellPath: string): boolean {
+	if (!shellPath) return false
 
-	const normalizedPath = path.normalize(pathToCheck)
+	const normalizedPath = path.normalize(shellPath)
 
 	// Direct lookup first
 	if (SHELL_ALLOWLIST.has(normalizedPath)) {
@@ -318,6 +315,62 @@ function isShellAllowed(shellPath: string | string[]): boolean {
 	return false
 }
 
+/**
+ * Proxy function that validates shell paths, handling both string and array inputs.
+ * This function serves as a robust interface for shell path validation that can
+ * handle various input types from VSCode API and other sources.
+ *
+ * @param shellPath - The shell path to validate. Can be:
+ *   - A string path to a shell executable
+ *   - An array of string paths (VSCode may return this)
+ *   - undefined or null
+ * @returns true if the shell path is allowed, false otherwise
+ *
+ * @example
+ * // String input
+ * validateShellPath("/bin/bash") // returns true
+ *
+ * @example
+ * // Array input (from VSCode API)
+ * validateShellPath(["/usr/local/bin/bash", "/bin/bash"]) // returns true if first is allowed
+ *
+ * @example
+ * // Empty or invalid input
+ * validateShellPath([]) // returns false
+ * validateShellPath(null) // returns false
+ */
+export function validateShellPath(shellPath: string | string[] | undefined | null): boolean {
+	// Handle null/undefined
+	if (!shellPath) {
+		return false
+	}
+
+	// Handle array input - validate the first element
+	if (Array.isArray(shellPath)) {
+		if (shellPath.length === 0) {
+			return false
+		}
+		// Recursively validate the first element (in case of nested arrays)
+		return validateShellPath(shellPath[0])
+	}
+
+	// Handle string input
+	if (typeof shellPath === "string") {
+		return isShellAllowedInternal(shellPath)
+	}
+
+	// Unknown type - reject for safety
+	return false
+}
+
+/**
+ * Legacy function for backward compatibility.
+ * @deprecated Use validateShellPath instead
+ */
+function isShellAllowed(shellPath: string | string[]): boolean {
+	return validateShellPath(shellPath)
+}
+
 /**
  * Returns a safe fallback shell based on the platform
  */