victauri_plugin/

lib.rs

#![deny(missing_docs)]
//! Victauri — full-stack introspection for Tauri apps via an embedded MCP server.
//!
//! Add this plugin to your Tauri app for AI-agent-driven testing and debugging:
//! DOM snapshots, IPC tracing, cross-boundary verification, and more tools —
//! all accessible over the Model Context Protocol.
//!
//! # Quick Start
//!
//! ```ignore
//! tauri::Builder::default()
//!     .plugin(victauri_plugin::init())
//!     .run(tauri::generate_context!())
//!     .unwrap();
//! ```
//!
//! In debug builds this starts an MCP server on port 7373. In release builds
//! the plugin is a no-op with zero overhead.
//!
//! # Configuration
//!
//! Authentication is disabled by default for zero-friction setup. The MCP server
//! listens on `127.0.0.1` only and is gated behind `#[cfg(debug_assertions)]`.
//! Use `.auth_token("...")` or `.auth_enabled()` to require a Bearer token.
//!
//! ```ignore
//! tauri::Builder::default()
//!     .plugin(
//!         victauri_plugin::VictauriBuilder::new()
//!             .port(8080)
//!             .strict_privacy_mode()
//!             .build(),
//!     )
//!     .run(tauri::generate_context!())
//!     .unwrap();
//! ```

/// Runtime-erased webview bridge trait and its Tauri implementation.
pub mod bridge;
/// Backend database access (`SQLite` read-only queries).
#[cfg(feature = "sqlite")]
pub mod database;
pub mod error;
/// JS bridge script generation for webview injection.
pub mod js_bridge;
/// MCP server, tool handler, and parameter types.
pub mod mcp;
mod memory;
/// Privacy controls: command allowlists, blocklists, and tool disabling.
pub mod privacy;
/// Output redaction for API keys, tokens, emails, and sensitive JSON keys.
pub mod redaction;
pub(crate) mod screenshot;
mod tools;

/// Bearer-token authentication, rate limiting, and security middlewares.
pub mod auth;

use std::collections::{HashMap, HashSet};
use std::sync::Arc;
use std::sync::atomic::{AtomicU16, AtomicU64};
use tauri::plugin::{Builder, TauriPlugin};
use tauri::{Manager, RunEvent, Runtime};
use tokio::sync::{Mutex, oneshot, watch};
use victauri_core::{CommandRegistry, EventLog, EventRecorder};

pub use error::BuilderError;
pub use privacy::PrivacyProfile;

pub use victauri_core::CommandInfo;
pub use victauri_macros::inspectable;

/// Register command schemas with the Victauri plugin at app setup time.
///
/// Pass the `__schema()` function calls generated by `#[inspectable]`.
/// This populates the `CommandRegistry` so that `get_registry`, `resolve_command`,
/// and `detect_ghost_commands` return real results.
///
/// # Example
///
/// ```rust,ignore
/// use victauri_plugin::register_commands;
///
/// .setup(|app| {
///     register_commands!(app,
///         greet__schema(),
///         increment__schema(),
///         add_todo__schema(),
///     );
///     Ok(())
/// })
/// ```
#[macro_export]
macro_rules! register_commands {
    ($app:expr, $($schema_call:expr),+ $(,)?) => {{
        let state = $app.state::<std::sync::Arc<$crate::VictauriState>>();
        $(
            state.registry.register($schema_call);
        )+
    }};
}

const DEFAULT_PORT: u16 = 7373;
const DEFAULT_EVENT_CAPACITY: usize = 10_000;
const DEFAULT_RECORDER_CAPACITY: usize = 50_000;
const DEFAULT_EVAL_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);
const MAX_EVENT_CAPACITY: usize = 1_000_000;
const MAX_RECORDER_CAPACITY: usize = 1_000_000;
const MAX_EVAL_TIMEOUT_SECS: u64 = 300;

/// Map of pending JavaScript eval callbacks, keyed by request ID.
/// Each entry holds a oneshot sender that resolves when the webview returns a result.
pub type PendingCallbacks = Arc<Mutex<HashMap<String, oneshot::Sender<String>>>>;

/// Runtime state shared between the MCP server and all tool handlers.
pub struct VictauriState {
    /// Ring-buffer event log for IPC calls, state changes, and DOM mutations.
    pub event_log: EventLog,
    /// Registry of all discovered Tauri commands with metadata.
    pub registry: CommandRegistry,
    /// TCP port the MCP server listens on (may differ from configured port if fallback was used).
    pub port: AtomicU16,
    /// Pending JavaScript eval callbacks awaiting webview responses.
    pub pending_evals: PendingCallbacks,
    /// Session recorder for time-travel debugging.
    pub recorder: EventRecorder,
    /// Privacy configuration (tool disabling, command filtering, output redaction).
    pub privacy: privacy::PrivacyConfig,
    /// Timeout for JavaScript eval operations.
    pub eval_timeout: std::time::Duration,
    /// Sends `true` to signal graceful MCP server shutdown.
    pub shutdown_tx: watch::Sender<bool>,
    /// Instant the plugin was initialized, for uptime tracking.
    pub started_at: std::time::Instant,
    /// Total number of MCP tool invocations since startup.
    pub tool_invocations: AtomicU64,
    /// Whether `file:` URLs are allowed in the `navigate` tool's `go_to` action.
    /// Defaults to `false` — only `http` and `https` are permitted unless opted in
    /// via [`VictauriBuilder::allow_file_navigation`].
    pub allow_file_navigation: bool,
}

/// Builder for configuring the Victauri plugin before adding it to a Tauri app.
///
/// Supports port selection, authentication, privacy controls, output redaction,
/// and capacity tuning. All settings have sensible defaults and can be overridden
/// via environment variables.
///
/// **Authentication is disabled by default** for zero-friction local development.
/// The server binds to `127.0.0.1` only and the entire plugin is `#[cfg(debug_assertions)]`.
/// Call [`auth_token()`](VictauriBuilder::auth_token) to set an explicit token,
/// [`auth_enabled()`](VictauriBuilder::auth_enabled) to auto-generate one, or set
/// the `VICTAURI_AUTH_TOKEN` environment variable.
pub struct VictauriBuilder {
    port: Option<u16>,
    event_capacity: usize,
    recorder_capacity: usize,
    eval_timeout: std::time::Duration,
    auth_token: Option<String>,
    auth_explicitly_enabled: bool,
    disabled_tools: Vec<String>,
    command_allowlist: Option<Vec<String>>,
    command_blocklist: Vec<String>,
    redaction_patterns: Vec<String>,
    redaction_enabled: bool,
    strict_privacy: bool,
    privacy_profile: Option<privacy::PrivacyProfile>,
    bridge_capacities: js_bridge::BridgeCapacities,
    on_ready: Option<Box<dyn FnOnce(u16) + Send + 'static>>,
    commands: Vec<victauri_core::CommandInfo>,
    allow_file_navigation: bool,
}

impl Default for VictauriBuilder {
    fn default() -> Self {
        Self {
            port: None,
            event_capacity: DEFAULT_EVENT_CAPACITY,
            recorder_capacity: DEFAULT_RECORDER_CAPACITY,
            eval_timeout: DEFAULT_EVAL_TIMEOUT,
            auth_token: None,
            auth_explicitly_enabled: false,
            disabled_tools: Vec::new(),
            command_allowlist: None,
            command_blocklist: Vec::new(),
            redaction_patterns: Vec::new(),
            redaction_enabled: false,
            strict_privacy: false,
            privacy_profile: None,
            bridge_capacities: js_bridge::BridgeCapacities::default(),
            on_ready: None,
            commands: Vec::new(),
            allow_file_navigation: false,
        }
    }
}

impl VictauriBuilder {
    /// Create a new builder with default settings.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Set the TCP port for the MCP server (default: 7373, env: `VICTAURI_PORT`).
    #[must_use]
    pub fn port(mut self, port: u16) -> Self {
        self.port = Some(port);
        self
    }

    /// Set the maximum number of events in the ring-buffer log (default: 10,000).
    #[must_use]
    pub fn event_capacity(mut self, capacity: usize) -> Self {
        self.event_capacity = capacity;
        self
    }

    /// Set the maximum events kept during session recording (default: 50,000).
    #[must_use]
    pub fn recorder_capacity(mut self, capacity: usize) -> Self {
        self.recorder_capacity = capacity;
        self
    }

    /// Set the timeout for JavaScript eval operations (default: 30s, env: `VICTAURI_EVAL_TIMEOUT`).
    #[must_use]
    pub fn eval_timeout(mut self, timeout: std::time::Duration) -> Self {
        self.eval_timeout = timeout;
        self
    }

    /// Set an explicit auth token for the MCP server (env: `VICTAURI_AUTH_TOKEN`).
    ///
    /// Setting a token implicitly enables authentication.
    #[must_use]
    pub fn auth_token(mut self, token: impl Into<String>) -> Self {
        self.auth_token = Some(token.into());
        self
    }

    /// Enable authentication with an auto-generated `UUID` v4 token.
    ///
    /// The token is printed to the log on startup and written to the discovery
    /// directory (`<temp>/victauri/<pid>/token`) for client auto-discovery.
    ///
    /// Authentication is disabled by default because the MCP server binds to
    /// `127.0.0.1` only and the plugin is `#[cfg(debug_assertions)]`-gated.
    /// Enable auth for shared machines or CI environments where multiple
    /// users may access the same host.
    #[must_use]
    pub fn auth_enabled(mut self) -> Self {
        self.auth_explicitly_enabled = true;
        self
    }

    /// Generate a random `UUID` v4 auth token (alias for [`auth_enabled`](Self::auth_enabled)).
    #[must_use]
    pub fn generate_auth_token(mut self) -> Self {
        self.auth_explicitly_enabled = true;
        self
    }

    /// No-op — authentication is already disabled by default since v0.4.0.
    ///
    /// Kept for backwards compatibility. Previously, auth was enabled by default
    /// and this method was needed to opt out. Now auth is off by default and
    /// [`auth_enabled()`](Self::auth_enabled) or [`auth_token()`](Self::auth_token)
    /// turn it on.
    #[must_use]
    pub fn auth_disabled(self) -> Self {
        self
    }

    /// Disable specific MCP tools by name (e.g., `["eval_js", "screenshot"]`).
    #[must_use]
    pub fn disable_tools(mut self, tools: &[&str]) -> Self {
        self.disabled_tools = tools.iter().map(std::string::ToString::to_string).collect();
        self
    }

    /// Only allow these Tauri commands to be invoked via MCP (positive allowlist).
    #[must_use]
    pub fn command_allowlist(mut self, commands: &[&str]) -> Self {
        self.command_allowlist = Some(
            commands
                .iter()
                .map(std::string::ToString::to_string)
                .collect(),
        );
        self
    }

    /// Block specific Tauri commands from being invoked via MCP.
    #[must_use]
    pub fn command_blocklist(mut self, commands: &[&str]) -> Self {
        self.command_blocklist = commands
            .iter()
            .map(std::string::ToString::to_string)
            .collect();
        self
    }

    /// Add a regex pattern for output redaction (e.g., `r"SECRET_\w+"`).
    #[must_use]
    pub fn add_redaction_pattern(mut self, pattern: impl Into<String>) -> Self {
        self.redaction_patterns.push(pattern.into());
        self
    }

    /// Enable output redaction with built-in patterns (API keys, emails, tokens).
    #[must_use]
    pub fn enable_redaction(mut self) -> Self {
        self.redaction_enabled = true;
        self
    }

    /// Enable strict privacy mode (equivalent to [`PrivacyProfile::Observe`]).
    ///
    /// Disables all mutation tools (`eval_js`, screenshot, interactions, input,
    /// storage writes, navigation, CSS injection) and enables output redaction.
    ///
    /// Prefer [`privacy_profile()`](Self::privacy_profile) for finer control.
    #[must_use]
    pub fn strict_privacy_mode(mut self) -> Self {
        self.strict_privacy = true;
        self.privacy_profile = Some(privacy::PrivacyProfile::Observe);
        self
    }

    /// Set the privacy profile tier.
    ///
    /// - [`Observe`](privacy::PrivacyProfile::Observe) — read-only (snapshots, logs, registry)
    /// - [`Test`](privacy::PrivacyProfile::Test) — observe + interactions + input + storage writes + recording
    /// - [`FullControl`](privacy::PrivacyProfile::FullControl) — everything (default)
    ///
    /// Profiles automatically enable redaction for `Observe` and `Test`.
    /// Use [`disable_tools()`](Self::disable_tools) to apply overrides on top of a profile.
    #[must_use]
    pub fn privacy_profile(mut self, profile: privacy::PrivacyProfile) -> Self {
        self.privacy_profile = Some(profile);
        if matches!(
            profile,
            privacy::PrivacyProfile::Observe | privacy::PrivacyProfile::Test
        ) {
            self.redaction_enabled = true;
        }
        self
    }

    /// Set the maximum console log entries kept in the JS bridge (default: 1000).
    #[must_use]
    pub fn console_log_capacity(mut self, capacity: usize) -> Self {
        self.bridge_capacities.console_logs = capacity;
        self
    }

    /// Set the maximum network log entries kept in the JS bridge (default: 1000).
    #[must_use]
    pub fn network_log_capacity(mut self, capacity: usize) -> Self {
        self.bridge_capacities.network_log = capacity;
        self
    }

    /// Set the maximum navigation log entries kept in the JS bridge (default: 200).
    #[must_use]
    pub fn navigation_log_capacity(mut self, capacity: usize) -> Self {
        self.bridge_capacities.navigation_log = capacity;
        self
    }

    /// Pre-register command schemas so `get_registry`, `resolve_command`, and
    /// `detect_ghost_commands` return real results from the moment the server starts.
    ///
    /// Pass the `__schema()` functions generated by `#[inspectable]`.
    ///
    /// ```rust,ignore
    /// VictauriBuilder::new()
    ///     .commands(&[
    ///         greet__schema(),
    ///         increment__schema(),
    ///         add_todo__schema(),
    ///     ])
    ///     .build()
    /// ```
    #[must_use]
    pub fn commands(mut self, schemas: &[victauri_core::CommandInfo]) -> Self {
        self.commands = schemas.to_vec();
        self
    }

    /// Register command names without full schemas.
    ///
    /// Use this when your commands are decorated with `#[tauri::command]` but not
    /// `#[inspectable]`. Ghost detection will recognize these commands as registered,
    /// eliminating false positives.
    ///
    /// ```rust,ignore
    /// VictauriBuilder::new()
    ///     .register_command_names(&[
    ///         "get_settings",
    ///         "save_settings",
    ///         "run_analysis",
    ///     ])
    ///     .build()
    /// ```
    #[must_use]
    pub fn register_command_names(mut self, names: &[&str]) -> Self {
        self.commands
            .extend(names.iter().map(|n| victauri_core::CommandInfo::new(*n)));
        self
    }

    /// Auto-discover all `#[inspectable]` commands in the binary.
    ///
    /// Uses `inventory` to collect every command marked with `#[inspectable]`
    /// at link time — no manual listing required. This replaces both
    /// `.commands(&[...])` and `register_commands!()`.
    ///
    /// ```rust,ignore
    /// tauri::Builder::default()
    ///     .plugin(
    ///         VictauriBuilder::new()
    ///             .auto_discover()
    ///             .build()
    ///             .unwrap(),
    ///     )
    /// ```
    #[must_use]
    pub fn auto_discover(mut self) -> Self {
        self.commands
            .extend(victauri_core::auto_discovered_commands());
        self
    }

    /// Allow `file:` URLs in the `navigate` tool's `go_to` action.
    ///
    /// By default, only `http` and `https` schemes are permitted. Calling this
    /// method opts in to `file:` navigation, which grants the MCP client access
    /// to local filesystem paths via the webview.
    ///
    /// **Warning:** Enabling this in untrusted environments exposes local files
    /// to any process that can reach the MCP server.
    #[must_use]
    pub fn allow_file_navigation(mut self) -> Self {
        self.allow_file_navigation = true;
        self
    }

    /// Register a callback invoked once the MCP server is listening.
    /// The callback receives the port number.
    #[must_use]
    pub fn on_ready(mut self, f: impl FnOnce(u16) + Send + 'static) -> Self {
        self.on_ready = Some(Box::new(f));
        self
    }

    fn resolve_port(&self) -> u16 {
        self.port
            .or_else(|| std::env::var("VICTAURI_PORT").ok()?.parse().ok())
            .unwrap_or(DEFAULT_PORT)
    }

    fn resolve_auth_token(&self) -> Option<String> {
        if let Some(ref token) = self.auth_token {
            return Some(token.clone());
        }
        if let Ok(token) = std::env::var("VICTAURI_AUTH_TOKEN") {
            return Some(token);
        }
        if self.auth_explicitly_enabled {
            return Some(auth::generate_token());
        }
        None
    }

    fn resolve_eval_timeout(&self) -> std::time::Duration {
        std::env::var("VICTAURI_EVAL_TIMEOUT")
            .ok()
            .and_then(|s| s.parse::<u64>().ok())
            .map_or(self.eval_timeout, std::time::Duration::from_secs)
    }

    fn build_privacy_config(&self) -> privacy::PrivacyConfig {
        let profile = self
            .privacy_profile
            .unwrap_or(privacy::PrivacyProfile::FullControl);

        let redaction_enabled = self.redaction_enabled
            || self.strict_privacy
            || matches!(
                profile,
                privacy::PrivacyProfile::Observe | privacy::PrivacyProfile::Test
            );

        privacy::PrivacyConfig {
            profile,
            command_allowlist: self
                .command_allowlist
                .as_ref()
                .map(|v| v.iter().cloned().collect::<HashSet<String>>()),
            command_blocklist: self.command_blocklist.iter().cloned().collect(),
            disabled_tools: self.disabled_tools.iter().cloned().collect(),
            redactor: redaction::Redactor::new(&self.redaction_patterns),
            redaction_enabled,
        }
    }

    fn validate(&self) -> Result<(), BuilderError> {
        let port = self.resolve_port();
        if port == 0 {
            return Err(BuilderError::InvalidPort {
                port,
                reason: "port 0 is reserved".to_string(),
            });
        }

        if self.event_capacity == 0 || self.event_capacity > MAX_EVENT_CAPACITY {
            return Err(BuilderError::InvalidEventCapacity {
                capacity: self.event_capacity,
                reason: format!("must be between 1 and {MAX_EVENT_CAPACITY}"),
            });
        }

        if self.recorder_capacity == 0 || self.recorder_capacity > MAX_RECORDER_CAPACITY {
            return Err(BuilderError::InvalidRecorderCapacity {
                capacity: self.recorder_capacity,
                reason: format!("must be between 1 and {MAX_RECORDER_CAPACITY}"),
            });
        }

        let timeout = self.resolve_eval_timeout();
        if timeout.as_secs() == 0 || timeout.as_secs() > MAX_EVAL_TIMEOUT_SECS {
            return Err(BuilderError::InvalidEvalTimeout {
                timeout_secs: timeout.as_secs(),
                reason: format!("must be between 1 and {MAX_EVAL_TIMEOUT_SECS} seconds"),
            });
        }

        Ok(())
    }

    /// Consume the builder and produce a Tauri plugin.
    ///
    /// In release builds this always succeeds. In debug builds the builder configuration is
    /// validated first.
    ///
    /// # Errors
    ///
    /// Returns [`BuilderError`] if the port, event capacity, recorder capacity, or eval
    /// timeout are outside their valid ranges (debug builds only).
    pub fn build<R: Runtime>(self) -> Result<TauriPlugin<R>, BuilderError> {
        #[cfg(not(debug_assertions))]
        {
            Ok(Builder::new("victauri").build())
        }

        #[cfg(debug_assertions)]
        {
            self.validate()?;

            let port = self.resolve_port();
            let event_capacity = self.event_capacity;
            let recorder_capacity = self.recorder_capacity;
            let eval_timeout = self.resolve_eval_timeout();
            let auth_token = self.resolve_auth_token();
            let privacy_config = self.build_privacy_config();
            let allow_file_navigation = self.allow_file_navigation;
            let on_ready = self.on_ready;
            let commands = self.commands;
            let js_init = js_bridge::init_script(&self.bridge_capacities);

            Ok(Builder::new("victauri")
                .setup(move |app, _api| {
                    let event_log = EventLog::new(event_capacity);
                    let registry = CommandRegistry::new();
                    let (shutdown_tx, shutdown_rx) = watch::channel(false);

                    let state = Arc::new(VictauriState {
                        event_log,
                        registry,
                        port: AtomicU16::new(port),
                        pending_evals: Arc::new(Mutex::new(HashMap::new())),
                        recorder: EventRecorder::new(recorder_capacity),
                        privacy: privacy_config,
                        eval_timeout,
                        shutdown_tx,
                        started_at: std::time::Instant::now(),
                        tool_invocations: AtomicU64::new(0),
                        allow_file_navigation,
                    });

                    app.manage(state.clone());

                    for cmd in commands {
                        state.registry.register(cmd);
                    }

                    if let Some(ref token) = auth_token {
                        tracing::info!(
                            "Victauri MCP server auth enabled — token: {}…{}",
                            &token[..8],
                            &token[token.len().saturating_sub(4)..]
                        );
                    } else {
                        tracing::info!(
                            "Victauri MCP server running without auth (localhost-only, debug build)"
                        );
                    }

                    let app_handle = app.clone();
                    let ready_state = state.clone();
                    tauri::async_runtime::spawn(async move {
                        match mcp::start_server_with_options(
                            app_handle,
                            state,
                            port,
                            auth_token,
                            shutdown_rx,
                        )
                        .await
                        {
                            Ok(()) => {
                                tracing::info!("Victauri MCP server stopped");
                            }
                            Err(e) => {
                                tracing::error!("Victauri MCP server failed: {e}");
                            }
                        }
                    });

                    if let Some(cb) = on_ready {
                        tauri::async_runtime::spawn(async move {
                            for _ in 0..50 {
                                tokio::time::sleep(std::time::Duration::from_millis(100)).await;
                                let actual_port =
                                    ready_state.port.load(std::sync::atomic::Ordering::Relaxed);
                                if tokio::net::TcpStream::connect(format!(
                                    "127.0.0.1:{actual_port}"
                                ))
                                .await
                                .is_ok()
                                {
                                    cb(actual_port);
                                    return;
                                }
                            }
                            let actual_port =
                                ready_state.port.load(std::sync::atomic::Ordering::Relaxed);
                            tracing::warn!(
                                "Victauri on_ready: server did not become ready within 5s"
                            );
                            cb(actual_port);
                        });
                    }

                    tracing::info!("Victauri plugin initialized — MCP server on port {port}");
                    Ok(())
                })
                .on_event(|app, event| {
                    if let RunEvent::Exit = event
                        && let Some(state) = app.try_state::<Arc<VictauriState>>()
                    {
                        let _ = state.shutdown_tx.send(true);
                        tracing::info!("Victauri shutdown signal sent");
                    }
                })
                .js_init_script(js_init)
                .invoke_handler(tauri::generate_handler![
                    tools::victauri_eval_js,
                    tools::victauri_eval_callback,
                    tools::victauri_get_window_state,
                    tools::victauri_list_windows,
                    tools::victauri_get_ipc_log,
                    tools::victauri_get_registry,
                    tools::victauri_get_memory_stats,
                    tools::victauri_dom_snapshot,
                    tools::victauri_verify_state,
                    tools::victauri_detect_ghost_commands,
                    tools::victauri_check_ipc_integrity,
                ])
                .build())
        }
    }
}

/// Initialize the Victauri plugin with default settings (port 7373 or `VICTAURI_PORT` env var).
///
/// In debug builds: starts the embedded MCP server, injects the JS bridge, and
/// registers all Tauri command handlers.
///
/// In release builds: returns a no-op plugin. The MCP server, JS bridge, and
/// all introspection tools are completely stripped — zero overhead, zero attack surface.
///
/// For custom configuration, use `VictauriBuilder::new().port(8080).build()`.
///
/// # Panics
///
/// Panics if the default builder configuration is invalid (this is a bug).
#[must_use]
pub fn init<R: Runtime>() -> TauriPlugin<R> {
    VictauriBuilder::new()
        .build()
        .expect("default Victauri configuration is always valid")
}

/// Initialize the Victauri plugin with auto-discovery of all `#[inspectable]` commands.
///
/// Equivalent to `VictauriBuilder::new().auto_discover().build()` — all commands
/// marked with `#[inspectable]` are registered automatically without manual listing.
///
/// # Panics
///
/// Panics if the default builder configuration is invalid (this is a bug).
#[must_use]
pub fn init_auto_discover<R: Runtime>() -> TauriPlugin<R> {
    VictauriBuilder::new()
        .auto_discover()
        .build()
        .expect("default Victauri configuration is always valid")
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn builder_default_values() {
        let builder = VictauriBuilder::new();
        assert_eq!(builder.event_capacity, DEFAULT_EVENT_CAPACITY);
        assert_eq!(builder.recorder_capacity, DEFAULT_RECORDER_CAPACITY);
        assert!(builder.auth_token.is_none());
        assert!(!builder.auth_explicitly_enabled);
        let resolved = builder.resolve_auth_token();
        assert!(resolved.is_none(), "auth should be disabled by default");
        assert!(builder.disabled_tools.is_empty());
        assert!(builder.command_allowlist.is_none());
        assert!(builder.command_blocklist.is_empty());
        assert!(!builder.redaction_enabled);
        assert!(!builder.strict_privacy);
    }

    #[test]
    fn builder_port_override() {
        let builder = VictauriBuilder::new().port(9090);
        assert_eq!(builder.resolve_port(), 9090);
    }

    #[test]
    #[allow(unsafe_code)]
    fn builder_default_port() {
        let builder = VictauriBuilder::new();
        // SAFETY: test-only — no concurrent env reads in this test binary.
        unsafe { std::env::remove_var("VICTAURI_PORT") };
        assert_eq!(builder.resolve_port(), DEFAULT_PORT);
    }

    #[test]
    fn builder_auth_token_explicit() {
        let builder = VictauriBuilder::new().auth_token("my-secret");
        assert_eq!(builder.resolve_auth_token(), Some("my-secret".to_string()));
    }

    #[test]
    fn builder_auth_enabled() {
        let builder = VictauriBuilder::new().auth_enabled();
        assert!(builder.auth_explicitly_enabled);
        let token = builder.resolve_auth_token().unwrap();
        assert_eq!(token.len(), 36, "auto-generated token should be a UUID");
    }

    #[test]
    fn builder_auth_generate_token() {
        let builder = VictauriBuilder::new().generate_auth_token();
        let token = builder.resolve_auth_token().unwrap();
        assert_eq!(token.len(), 36);
    }

    #[test]
    fn builder_auth_disabled_is_noop() {
        let builder = VictauriBuilder::new().auth_disabled();
        assert!(
            builder.resolve_auth_token().is_none(),
            "auth_disabled is a no-op, auth stays off by default"
        );
    }

    #[test]
    fn builder_auth_disabled_does_not_override_explicit_token() {
        let builder = VictauriBuilder::new()
            .auth_token("my-secret")
            .auth_disabled();
        assert_eq!(
            builder.resolve_auth_token(),
            Some("my-secret".to_string()),
            "auth_disabled is a no-op, explicit token should remain"
        );
    }

    #[test]
    fn builder_capacities() {
        let builder = VictauriBuilder::new()
            .event_capacity(500)
            .recorder_capacity(2000);
        assert_eq!(builder.event_capacity, 500);
        assert_eq!(builder.recorder_capacity, 2000);
    }

    #[test]
    fn builder_disable_tools() {
        let builder = VictauriBuilder::new().disable_tools(&["eval_js", "screenshot"]);
        assert_eq!(builder.disabled_tools.len(), 2);
        assert!(builder.disabled_tools.contains(&"eval_js".to_string()));
    }

    #[test]
    fn builder_command_allowlist() {
        let builder = VictauriBuilder::new().command_allowlist(&["greet", "increment"]);
        assert!(builder.command_allowlist.is_some());
        assert_eq!(builder.command_allowlist.as_ref().unwrap().len(), 2);
    }

    #[test]
    fn builder_command_blocklist() {
        let builder = VictauriBuilder::new().command_blocklist(&["dangerous_cmd"]);
        assert_eq!(builder.command_blocklist.len(), 1);
    }

    #[test]
    fn builder_redaction() {
        let builder = VictauriBuilder::new()
            .add_redaction_pattern(r"SECRET_\w+")
            .enable_redaction();
        assert!(builder.redaction_enabled);
        assert_eq!(builder.redaction_patterns.len(), 1);
    }

    #[test]
    fn builder_strict_privacy_config() {
        let builder = VictauriBuilder::new().strict_privacy_mode();
        let config = builder.build_privacy_config();
        assert!(config.redaction_enabled);
        assert_eq!(config.profile, crate::privacy::PrivacyProfile::Observe);
        assert!(!config.is_tool_enabled("eval_js"));
        assert!(!config.is_tool_enabled("screenshot"));
        assert!(!config.is_tool_enabled("interact"));
        assert!(config.is_tool_enabled("dom_snapshot"));
    }

    #[test]
    fn builder_normal_privacy_config() {
        let builder = VictauriBuilder::new()
            .command_blocklist(&["secret_cmd"])
            .disable_tools(&["eval_js"]);
        let config = builder.build_privacy_config();
        assert!(config.command_blocklist.contains("secret_cmd"));
        assert!(!config.is_tool_enabled("eval_js"));
        assert!(!config.redaction_enabled);
    }

    #[test]
    fn builder_strict_with_extra_blocklist() {
        let builder = VictauriBuilder::new()
            .strict_privacy_mode()
            .command_blocklist(&["extra_dangerous"]);
        let config = builder.build_privacy_config();
        assert!(config.command_blocklist.contains("extra_dangerous"));
        assert!(!config.is_tool_enabled("eval_js"));
    }

    #[test]
    fn builder_test_profile() {
        let builder = VictauriBuilder::new().privacy_profile(crate::privacy::PrivacyProfile::Test);
        let config = builder.build_privacy_config();
        assert_eq!(config.profile, crate::privacy::PrivacyProfile::Test);
        assert!(config.redaction_enabled);
        assert!(config.is_tool_enabled("interact"));
        assert!(config.is_tool_enabled("fill"));
        assert!(config.is_tool_enabled("recording"));
        assert!(!config.is_tool_enabled("eval_js"));
        assert!(!config.is_tool_enabled("screenshot"));
        assert!(!config.is_tool_enabled("navigate"));
    }

    #[test]
    fn builder_profile_with_extra_disables() {
        let builder = VictauriBuilder::new()
            .privacy_profile(crate::privacy::PrivacyProfile::Test)
            .disable_tools(&["interact"]);
        let config = builder.build_privacy_config();
        assert!(!config.is_tool_enabled("interact"));
        assert!(config.is_tool_enabled("fill"));
    }

    #[test]
    fn builder_bridge_capacities() {
        let builder = VictauriBuilder::new()
            .console_log_capacity(5000)
            .network_log_capacity(2000)
            .navigation_log_capacity(500);
        assert_eq!(builder.bridge_capacities.console_logs, 5000);
        assert_eq!(builder.bridge_capacities.network_log, 2000);
        assert_eq!(builder.bridge_capacities.navigation_log, 500);
        assert_eq!(builder.bridge_capacities.mutation_log, 500);
        assert_eq!(builder.bridge_capacities.dialog_log, 100);
    }

    #[test]
    fn builder_on_ready_sets_callback() {
        let builder = VictauriBuilder::new().on_ready(|_port| {});
        assert!(builder.on_ready.is_some());
    }

    #[test]
    fn builder_file_navigation_disabled_by_default() {
        let builder = VictauriBuilder::new();
        assert!(
            !builder.allow_file_navigation,
            "file navigation should be disabled by default"
        );
    }

    #[test]
    fn builder_allow_file_navigation() {
        let builder = VictauriBuilder::new().allow_file_navigation();
        assert!(builder.allow_file_navigation);
    }

    #[test]
    fn init_script_contains_custom_capacities() {
        let caps = js_bridge::BridgeCapacities {
            console_logs: 3000,
            mutation_log: 750,
            network_log: 5000,
            navigation_log: 400,
            dialog_log: 250,
            long_tasks: 200,
        };
        let script = js_bridge::init_script(&caps);
        assert!(script.contains("CAP_CONSOLE = 3000"));
        assert!(script.contains("CAP_MUTATION = 750"));
        assert!(script.contains("CAP_NETWORK = 5000"));
        assert!(script.contains("CAP_NAVIGATION = 400"));
        assert!(script.contains("CAP_DIALOG = 250"));
        assert!(script.contains("CAP_LONG_TASKS = 200"));
    }

    #[test]
    fn init_script_default_contains_standard_capacities() {
        let caps = js_bridge::BridgeCapacities::default();
        let script = js_bridge::init_script(&caps);
        assert!(script.contains("CAP_CONSOLE = 1000"));
        assert!(script.contains("CAP_NETWORK = 1000"));
        assert!(script.contains("window.__VICTAURI__"));
    }

    #[test]
    fn builder_validates_defaults() {
        let builder = VictauriBuilder::new();
        assert!(builder.validate().is_ok());
    }

    #[test]
    fn builder_rejects_zero_port() {
        let builder = VictauriBuilder::new().port(0);
        let err = builder.validate().unwrap_err();
        assert!(matches!(err, BuilderError::InvalidPort { port: 0, .. }));
    }

    #[test]
    fn builder_rejects_zero_event_capacity() {
        let builder = VictauriBuilder::new().event_capacity(0);
        let err = builder.validate().unwrap_err();
        assert!(matches!(
            err,
            BuilderError::InvalidEventCapacity { capacity: 0, .. }
        ));
    }

    #[test]
    fn builder_rejects_excessive_event_capacity() {
        let builder = VictauriBuilder::new().event_capacity(2_000_000);
        assert!(builder.validate().is_err());
    }

    #[test]
    fn builder_rejects_zero_recorder_capacity() {
        let builder = VictauriBuilder::new().recorder_capacity(0);
        assert!(builder.validate().is_err());
    }

    #[test]
    fn builder_rejects_zero_eval_timeout() {
        let builder = VictauriBuilder::new().eval_timeout(std::time::Duration::from_secs(0));
        assert!(builder.validate().is_err());
    }

    #[test]
    fn builder_rejects_excessive_eval_timeout() {
        let builder = VictauriBuilder::new().eval_timeout(std::time::Duration::from_secs(600));
        assert!(builder.validate().is_err());
    }

    #[test]
    fn builder_accepts_edge_values() {
        let builder = VictauriBuilder::new()
            .port(1)
            .event_capacity(1)
            .recorder_capacity(1)
            .eval_timeout(std::time::Duration::from_secs(1));
        assert!(builder.validate().is_ok());

        let builder = VictauriBuilder::new()
            .port(65535)
            .event_capacity(MAX_EVENT_CAPACITY)
            .recorder_capacity(MAX_RECORDER_CAPACITY)
            .eval_timeout(std::time::Duration::from_secs(MAX_EVAL_TIMEOUT_SECS));
        assert!(builder.validate().is_ok());
    }
}