Add security validations and improve CDP event handling

[MarcosBrendonDePaula]

Summary

This PR enhances security by adding input validation for sensitive operations and improves the Chrome DevTools Protocol (CDP) event monitoring system. It also adds macOS support, better error handling, and type safety improvements across the codebase.

Key Changes

Security Enhancements

• URL validation: Added validateUrl() to restrict navigation to http://, https://, and file:// protocols only
• Path traversal prevention: Added validateFilePath() to block path traversal attacks (e.g., "../../etc/passwd") in file operations
• Environment variable protection: Added validateEnvKey() to block access to sensitive environment variables (AWS_*, tokens, secrets, passwords, private keys)
• Command allowlist: Implemented security allowlist for runCommand() restricting execution to safe commands (ls, cat, git, npm, node, etc.)

CDP Event Monitoring Improvements

• Refactored onConsoleMessage() and onNetworkRequest() to return unsubscribe functions via CDPEventSubscription interface
• Added proper event filtering and callback management with active state tracking
• Introduced ConsoleMessage and NetworkRequest exported interfaces for type-safe event handling
• Implemented browser.cdp.onEvent() callback registration for CDP event streaming

Platform Support

• Added macOS (darwin) support with proper browser paths for Chrome, Edge, and Firefox applications
• Updated Platform type to include 'darwin'

Type Safety & Error Handling

• Added IPCApi interface for better type definitions
• Improved FluxDesktopWindow interface with proper CDP event callback support
• Added CDP command timeout (30 seconds) with proper error handling and cleanup
• Better error messages when browser not found or fails to start
• Fixed return types (e.g., readJSONFile() returns unknown instead of any)
• Improved Bun.file().size type from Promise<number> to number

DevTools Management

• Enhanced openDevTools() and closeDevTools() with proper CDP Inspector domain support and F12 key fallback
• Better error handling with try-catch blocks

Utility Functions

• Added clearBrowserCache() export to reset cached browser paths at runtime
• Improved runCommand() implementation using Node.js child_process spawn with proper stdout/stderr handling
• Added validation calls to all file operation functions (saveFile, readTextFile, readJSONFile, fileExists, getFileSize)
• Added validation to navigate() and getEnv() functions

Memory & Resource Management

• Added cleanup in CDP connection close to prevent memory leaks from hanging promises
• Proper timeout handling for CDP commands with cleanup

Notable Implementation Details

• Event subscriptions use closure-based active state tracking for clean unsubscribe semantics
• Command allowlist uses a Set for O(1) lookup performance
• CDP timeout is configurable via CDP_TIMEOUT_MS constant
• File path validation uses normalized forward slashes for cross-platform consistency
• Environment variable validation checks both prefix and substring matches for sensitive keys

https://claude.ai/code/session_01PDJSn9vYhTxyaWDaKweBAG