Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

18.0 KB
Raw Blame
//! Loopback origin resolution and validation.
//!
//! The shell navigates its only WebView to whatever this module accepts, so the
//! accepted set is deliberately tiny: plain `http` on the literal addresses
//! `127.0.0.1` or `[::1]`, with no credentials, path, query, or fragment.
//!
//! The hostname `localhost` is refused even though it is loopback. It resolves
//! to both `127.0.0.1` and `[::1]` on a normal machine, and the readiness probe and
//! the WebView resolve it independently — so a probe that succeeded over IPv4
//! could be followed by a navigation over IPv6 to nothing, since the Runtime
//! binds one literal address. The shell navigates to exactly the address it
//! proved healthy.

use std::fmt;
use std::net::{Ipv4Addr, Ipv6Addr};
use std::thread;
use std::time::{Duration, Instant};

use url::{Host, Url};

/// Port of the Vite dev server that serves the bootstrap UI during `npm run tauri dev`.
/// Must match `desktop/vite.config.ts` and `build.devUrl` in `tauri.conf.json`.
pub const DEV_SERVER_PORT: u16 = 1420;

/// The bundled WebView may report its initial document before Tauri's local
/// asset URL has committed. Keep setup bounded while allowing that transition
/// to complete.
pub const SHELL_UI_URL_TIMEOUT: Duration = Duration::from_secs(5);
const SHELL_UI_URL_POLL_INTERVAL: Duration = Duration::from_millis(10);

#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
pub enum OriginError {
    #[error("The desktop origin is empty.")]
    Empty,
    #[error("The desktop origin is not a valid absolute URL.")]
    Malformed,
    #[error("The desktop origin must use http://; https and custom schemes are not accepted.")]
    UnsupportedScheme,
    #[error("The desktop origin must be a literal loopback address: 127.0.0.1 or [::1].")]
    NonLoopbackHost,
    #[error("The desktop origin must not carry a username or password.")]
    CredentialsPresent,
    #[error("The desktop origin must be a bare origin, without a path, query, or fragment.")]
    NotBareOrigin,
    #[error("The desktop origin must not be the port reserved for the shell's own UI.")]
    ShellUiOrigin,
}

/// A validated loopback origin. Constructing one is the only way to get a URL
/// the shell is willing to navigate to.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LoopbackOrigin {
    url: Url,
    origin: String,
}

impl LoopbackOrigin {
    pub fn parse(raw: &str) -> Result<Self, OriginError> {
        let trimmed = raw.trim();
        if trimmed.is_empty() {
            return Err(OriginError::Empty);
        }

        let url = Url::parse(trimmed).map_err(|_| OriginError::Malformed)?;

        if url.scheme() != "http" {
            return Err(OriginError::UnsupportedScheme);
        }
        if !url.username().is_empty() || url.password().is_some() {
            return Err(OriginError::CredentialsPresent);
        }
        if !matches!(url.path(), "" | "/") || url.query().is_some() || url.fragment().is_some() {
            return Err(OriginError::NotBareOrigin);
        }
        // `url` follows the WHATWG parser and canonicalizes legacy IPv4 forms:
        // `127.1`, `2130706433`, and `0x7f000001` all become `127.0.0.1`.
        // The desktop contract is deliberately narrower, so validate the raw
        // authority as well as the parsed address.
        if !has_literal_loopback_authority(trimmed) || !is_loopback_host(&url) {
            return Err(OriginError::NonLoopbackHost);
        }
        // Tauri decides a WebView's ACL origin with `is_local_url`, which counts
        // any URL relative to `devUrl` as *local*. A Workbench served on the dev
        // server's port would therefore keep matching the shell's `local: true`
        // capability after navigation, and the page would keep the bootstrap
        // commands. Nothing legitimate listens there — Vite owns the port under
        // `strictPort` — so the whole port is refused, in every build profile,
        // rather than only in the one where the hazard is reachable.
        if url.port() == Some(DEV_SERVER_PORT) {
            return Err(OriginError::ShellUiOrigin);
        }

        let origin = url.origin().ascii_serialization();
        Ok(Self { url, origin })
    }

    /// The canonical origin string handed to the bootstrap UI, e.g. `http://127.0.0.1:5123`.
    pub fn as_str(&self) -> &str {
        &self.origin
    }

    /// Where the shell navigates the WebView once the Runtime is ready.
    pub fn navigation_url(&self) -> Url {
        self.url.clone()
    }

    /// Whether a navigation stays on this exact validated origin.
    ///
    /// Paths, queries, and fragments may vary because the Workbench and Show
    /// Pages route below the same listener. Scheme, address, and port may not.
    pub fn matches_url_origin(&self, url: &Url) -> bool {
        url.origin().ascii_serialization() == self.origin
    }

    /// The combined UI + Controller readiness endpoint.
    pub fn readiness_url(&self) -> Url {
        self.url
            .join("/ready")
            .expect("/ready is a valid path on a validated origin")
    }
}

impl fmt::Display for LoopbackOrigin {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.origin)
    }
}

fn is_loopback_host(url: &Url) -> bool {
    match url.host() {
        Some(Host::Ipv4(address)) => address == Ipv4Addr::LOCALHOST,
        Some(Host::Ipv6(address)) => address == Ipv6Addr::LOCALHOST,
        // Including `localhost`: see the module comment.
        Some(Host::Domain(_)) | None => false,
    }
}

fn has_literal_loopback_authority(raw: &str) -> bool {
    let Some((_, remainder)) = raw.split_once("://") else {
        return false;
    };
    // A path, query, or fragment has already been rejected. Removing the one
    // permitted trailing slash leaves only the raw authority.
    let authority = remainder.strip_suffix('/').unwrap_or(remainder);
    authority_matches(authority, "127.0.0.1") || authority_matches(authority, "[::1]")
}

fn authority_matches(authority: &str, host: &str) -> bool {
    if authority == host {
        return true;
    }
    authority
        .strip_prefix(host)
        .and_then(|remainder| remainder.strip_prefix(':'))
        .is_some_and(|port| !port.is_empty() && port.bytes().all(|byte| byte.is_ascii_digit()))
}

/// Whether a WebView URL belongs to the shell's own bootstrap page.
///
/// Tauri's capability files are the enforcing boundary; this is the second
/// layer, applied inside every command so that a page loaded from the Workbench
/// origin cannot reach shell commands even if a capability is later widened by
/// mistake.
pub fn is_shell_ui_url(url: &Url) -> bool {
    let host = url.host();
    match url.scheme() {
        // macOS and Linux serve bundled app assets from tauri://localhost.
        "tauri" => matches!(host, Some(Host::Domain(domain)) if domain.eq_ignore_ascii_case("localhost")),
        "http" => match host {
            // Windows (WebView2) serves the same assets from http://tauri.localhost.
            Some(Host::Domain(domain)) if domain.eq_ignore_ascii_case("tauri.localhost") => true,
            // The Vite dev server, in development builds only.
            Some(Host::Domain(domain)) if cfg!(debug_assertions) && domain.eq_ignore_ascii_case("localhost") => {
                url.port() == Some(DEV_SERVER_PORT)
            }
            _ => false,
        },
        _ => false,
    }
}

#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum ShellUiUrlWaitError {
    #[error("failed to read the desktop window URL: {0}")]
    Read(String),
    #[error("the Avibe desktop window did not load its bundled bootstrap page before timeout; last URL: {last_url}")]
    TimedOut { last_url: String },
}

/// Returns the first shell URL reported by a WebView, allowing transient
/// non-shell URLs while its bundled document commits.
///
/// The URL reader is injected so the timing contract can be tested without a
/// native WebView. A timeout still performs one final read, making the error
/// name the URL observed at the end of the bounded wait.
pub fn wait_for_shell_ui_url<F>(mut read_url: F, timeout: Duration) -> Result<Url, ShellUiUrlWaitError>
where
    F: FnMut() -> Result<Url, String>,
{
    let deadline = Instant::now() + timeout;

    loop {
        let url = read_url().map_err(ShellUiUrlWaitError::Read)?;
        if is_shell_ui_url(&url) {
            return Ok(url);
        }
        let last_url = display_url(&url);

        let remaining = deadline.saturating_duration_since(Instant::now());
        if remaining.is_zero() {
            return Err(ShellUiUrlWaitError::TimedOut { last_url });
        }
        thread::sleep(SHELL_UI_URL_POLL_INTERVAL.min(remaining));
    }
}

fn display_url(url: &Url) -> String {
    let mut display = url.clone();
    display.set_query(None);
    display.set_fragment(None);
    display.to_string()
}

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

    fn parse(raw: &str) -> Result<LoopbackOrigin, OriginError> {
        LoopbackOrigin::parse(raw)
    }

    #[test]
    fn builds_navigation_and_readiness_urls_from_a_valid_origin() {
        let origin = parse("http://127.0.0.1:5123").expect("the origin is accepted");
        assert_eq!(origin.as_str(), "http://127.0.0.1:5123");
        assert_eq!(origin.readiness_url().as_str(), "http://127.0.0.1:5123/ready");
        assert_eq!(origin.navigation_url().as_str(), "http://127.0.0.1:5123/");
    }

    #[test]
    fn navigation_matching_keeps_every_path_on_the_exact_listener() {
        let origin = parse("http://127.0.0.1:5123").expect("the origin is accepted");
        for raw in [
            "http://127.0.0.1:5123/",
            "http://127.0.0.1:5123/show/session/",
            "http://127.0.0.1:5123/?view=chat#latest",
        ] {
            let url = Url::parse(raw).expect("test URL parses");
            assert!(origin.matches_url_origin(&url), "{raw} stays on the listener");
        }
        for raw in [
            "http://127.0.0.1:5124/",
            "http://127.0.0.2:5123/",
            "http://192.168.1.10:5123/",
            "http://[::1]:5123/",
            "https://127.0.0.1:5123/",
            "https://avibe.bot/",
        ] {
            let url = Url::parse(raw).expect("test URL parses");
            assert!(!origin.matches_url_origin(&url), "{raw} leaves the listener");
        }
    }

    #[test]
    fn accepts_every_loopback_spelling_in_the_contract() {
        let cases = [
            ("http://127.0.0.1:5123", "http://127.0.0.1:5123"),
            ("http://[::1]:5123", "http://[::1]:5123"),
            ("http://127.0.0.1", "http://127.0.0.1"),
            ("http://127.0.0.1:5123/", "http://127.0.0.1:5123"),
            ("  http://127.0.0.1:5123  ", "http://127.0.0.1:5123"),
        ];
        for (raw, expected) in cases {
            let origin = parse(raw).unwrap_or_else(|error| panic!("{raw} should be accepted, got {error}"));
            assert_eq!(origin.as_str(), expected, "origin string for {raw}");
        }
    }

    /// `localhost` is loopback, and is still refused: it names two addresses, and
    /// the probe and the WebView would each pick one on their own. The shell
    /// navigates to the address it proved healthy, so it only ever handles
    /// literal ones.
    #[test]
    fn the_hostname_localhost_is_refused_however_it_is_spelled() {
        for raw in [
            "http://localhost:5123",
            "http://localhost",
            "http://LOCALHOST:5123",
            "http://localhost.:5123",
            "http://ip6-localhost:5123",
        ] {
            assert_eq!(parse(raw), Err(OriginError::NonLoopbackHost), "origin {raw:?}");
        }
    }

    #[test]
    fn canonicalized_loopback_spellings_are_not_literal_addresses() {
        for raw in [
            "http://127.1:5123",
            "http://2130706433:5123",
            "http://0x7f000001:5123",
            "http://017700000001:5123",
            "http://127.000.000.001:5123",
            "http://[0:0:0:0:0:0:0:1]:5123",
            "http://[::0001]:5123",
        ] {
            assert_eq!(parse(raw), Err(OriginError::NonLoopbackHost), "origin {raw:?}");
        }
    }

    #[test]
    fn rejects_everything_that_is_not_a_bare_loopback_http_origin() {
        let cases = [
            ("", OriginError::Empty),
            ("   ", OriginError::Empty),
            ("127.0.0.1:5123", OriginError::Malformed),
            ("not a url", OriginError::Malformed),
            ("https://127.0.0.1:5123", OriginError::UnsupportedScheme),
            ("file:///etc/passwd", OriginError::UnsupportedScheme),
            ("tauri://localhost", OriginError::UnsupportedScheme),
            ("ws://127.0.0.1:5123", OriginError::UnsupportedScheme),
            ("http://192.168.1.10:5123", OriginError::NonLoopbackHost),
            ("http://127.0.0.2:5123", OriginError::NonLoopbackHost),
            ("http://0.0.0.0:5123", OriginError::NonLoopbackHost),
            ("http://example.com", OriginError::NonLoopbackHost),
            ("http://localhost.example.com", OriginError::NonLoopbackHost),
            ("http://[::2]:5123", OriginError::NonLoopbackHost),
            ("http://[email protected]:5123", OriginError::CredentialsPresent),
            ("http://user:[email protected]:5123", OriginError::CredentialsPresent),
            ("http://127.0.0.1:5123/admin", OriginError::NotBareOrigin),
            ("http://127.0.0.1:5123/?next=/x", OriginError::NotBareOrigin),
            ("http://127.0.0.1:5123/#/chat", OriginError::NotBareOrigin),
            ("http://127.0.0.1:1420", OriginError::ShellUiOrigin),
            ("http://[::1]:1420", OriginError::ShellUiOrigin),
        ];
        for (raw, expected) in cases {
            assert_eq!(parse(raw), Err(expected), "origin {raw:?}");
        }
    }

    #[test]
    fn rejected_origins_explain_themselves_without_leaking_the_value() {
        let error = parse("https://example.com").expect_err("https is rejected");
        let message = error.to_string();
        assert!(message.contains("http://"), "message should name the accepted scheme");
        assert!(
            !message.contains("example.com"),
            "message must not echo the rejected value"
        );
    }

    #[test]
    fn shell_ui_urls_are_the_bundled_app_and_dev_server_only() {
        let shell = [
            "tauri://localhost/index.html",
            "tauri://localhost",
            "http://tauri.localhost/index.html",
        ];
        for raw in shell {
            let url = Url::parse(raw).expect("test url parses");
            assert!(is_shell_ui_url(&url), "{raw} is the shell's own page");
        }

        let not_shell = [
            // The Workbench origin: reachable in the same WebView after navigation.
            "http://127.0.0.1:5123/",
            "http://127.0.0.1:5123/show/abc/",
            "https://tauri.localhost/",
            "http://tauri.localhost.example.com/",
            "https://avibe.bot/",
            "file:///index.html",
        ];
        for raw in not_shell {
            let url = Url::parse(raw).expect("test url parses");
            assert!(!is_shell_ui_url(&url), "{raw} must not reach shell commands");
        }
    }

    #[test]
    fn the_vite_dev_server_is_shell_ui_only_in_development_builds() {
        let url = Url::parse(&format!("http://localhost:{DEV_SERVER_PORT}/")).expect("dev url parses");
        assert_eq!(is_shell_ui_url(&url), cfg!(debug_assertions));

        // A different loopback port is never the shell, in either build profile.
        let other = Url::parse("http://localhost:5123/").expect("test url parses");
        assert!(!is_shell_ui_url(&other));
    }

    #[test]
    fn an_already_committed_shell_url_proceeds_without_polling() {
        let shell = Url::parse("http://tauri.localhost/index.html").expect("test URL parses");
        let mut reads = 0;

        let result = wait_for_shell_ui_url(
            || {
                reads += 1;
                Ok(shell.clone())
            },
            Duration::from_secs(1),
        );

        assert_eq!(result, Ok(shell));
        assert_eq!(reads, 1);
    }

    #[test]
    fn a_transient_non_shell_url_is_rechecked_until_the_shell_commits() {
        let mut urls = [
            "about:blank",
            "http://127.0.0.1:5123/",
            "http://tauri.localhost/index.html",
        ]
        .into_iter()
        .map(|raw| Url::parse(raw).expect("test URL parses"));

        let result = wait_for_shell_ui_url(
            || Ok(urls.next().expect("the reader is called only until success")),
            Duration::from_secs(1),
        );

        assert_eq!(
            result,
            Ok(Url::parse("http://tauri.localhost/index.html").expect("test URL parses"))
        );
    }

    #[test]
    fn a_timeout_reports_the_last_url_without_query_or_fragment() {
        let last = Url::parse("http://127.0.0.1:5123/loading?token=secret#fragment").expect("test URL parses");

        let error = wait_for_shell_ui_url(|| Ok(last.clone()), Duration::from_millis(25))
            .expect_err("a non-shell URL must time out");

        assert_eq!(
            error,
            ShellUiUrlWaitError::TimedOut {
                last_url: "http://127.0.0.1:5123/loading".to_owned(),
            }
        );
    }

    /// The port the shell's own UI is served from is the one loopback port a
    /// Runtime must never be reached at: a page there would be classified as
    /// *local* by Tauri and would keep the bootstrap commands after navigation.
    /// The refusal is unconditional, so a release build cannot be the only thing
    /// standing between a misconfigured origin and a privileged Workbench.
    #[test]
    fn the_shells_own_port_is_refused_in_every_build_profile() {
        for host in ["127.0.0.1", "[::1]"] {
            let raw = format!("http://{host}:{DEV_SERVER_PORT}");
            assert_eq!(parse(&raw), Err(OriginError::ShellUiOrigin), "origin {raw:?}");

            // Neighbouring ports stay perfectly acceptable: it is one reserved
            // port, not a range.
            for port in [DEV_SERVER_PORT - 1, DEV_SERVER_PORT + 1] {
                let neighbour = format!("http://{host}:{port}");
                assert!(parse(&neighbour).is_ok(), "origin {neighbour:?} should be accepted");
            }
        }
    }
}