Skip to content

armgit / muxin

Public Imported from GitHub
0

All your machines, one app. For you and your AI agents: agent sessions, desktops, files, logs and GitHub across your Macs, Linux and Windows machines, with an MCP server.

9.5 KB
Raw Blame
//! A share's link and what it proves: `https://<server>/s#1.<ticket>`, the
//! ticket being base64url of the share's id (16 bytes), secret (32) and
//! certificate fingerprint (32). Muxin also takes `muxin://join?server=
//! <server>#1.<ticket>` (the link's page opening the app).

use base64::Engine as _;
use base64::engine::general_purpose::URL_SAFE_NO_PAD;
use ring::hmac;
use ring::rand::{SecureRandom, SystemRandom};

const VERSION: &str = "1";

#[derive(Clone, PartialEq, Eq)]
pub struct Ticket {
    /// Where the two sides meet: `https://muxin.dev` (http only for
    /// this computer's own addresses, while developing).
    pub server: String,
    pub id: [u8; 16],
    pub secret: [u8; 32],
    /// SHA-256 of the share's DTLS certificate.
    pub fingerprint: [u8; 32],
}

impl std::fmt::Debug for Ticket {
    // Never the secret, in logs or errors.
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Ticket").field("server", &self.server).field("room", &self.room()).finish_non_exhaustive()
    }
}

impl Ticket {
    /// A new share's ticket, for a certificate with this fingerprint.
    pub fn new(server: &str, fingerprint: [u8; 32]) -> Result<Ticket, String> {
        let server = origin(server)?;
        let rng = SystemRandom::new();
        let (mut id, mut secret) = ([0u8; 16], [0u8; 32]);
        rng.fill(&mut id).map_err(|_| "no randomness")?;
        rng.fill(&mut secret).map_err(|_| "no randomness")?;
        Ok(Ticket { server, id, secret, fingerprint })
    }

    /// The link to give out.
    pub fn link(&self) -> String {
        format!("{}/s#{}", self.server, self.fragment())
    }

    /// The part after `#`.
    pub fn fragment(&self) -> String {
        let mut bytes = Vec::with_capacity(80);
        bytes.extend(self.id);
        bytes.extend(self.secret);
        bytes.extend(self.fingerprint);
        format!("{VERSION}.{}", URL_SAFE_NO_PAD.encode(bytes))
    }

    /// Reads a link (or the app's own form of one).
    pub fn parse(link: &str) -> Result<Ticket, String> {
        let link = link.trim();
        let (before, fragment) = link.split_once('#').ok_or("That isn't a Muxin share link.")?;
        let server = if let Some(query) = before.strip_prefix("muxin://join") {
            let query = query.trim_start_matches('/').trim_start_matches('?');
            let value = query.split('&').find_map(|kv| kv.strip_prefix("server=")).ok_or("That link doesn't say where to connect.")?;
            percent_decode(value)
        } else {
            let after_scheme = before.split_once("://").map(|(_, rest)| rest).ok_or("That isn't a Muxin share link.")?;
            let host = after_scheme.split('/').next().unwrap_or("");
            let scheme = before.split_once("://").map(|(s, _)| s).unwrap_or("");
            format!("{scheme}://{host}")
        };
        let server = origin(&server)?;
        let (version, data) = fragment.split_once('.').ok_or("That share link is cut short.")?;
        if version != VERSION {
            return Err("That share link is from a newer Muxin. Update Muxin to open it.".into());
        }
        let bytes = URL_SAFE_NO_PAD.decode(data.trim()).map_err(|_| "That share link is damaged.")?;
        if bytes.len() != 80 {
            return Err("That share link is cut short.".into());
        }
        let mut t = Ticket { server, id: [0; 16], secret: [0; 32], fingerprint: [0; 32] };
        t.id.copy_from_slice(&bytes[..16]);
        t.secret.copy_from_slice(&bytes[16..48]);
        t.fingerprint.copy_from_slice(&bytes[48..]);
        Ok(t)
    }

    /// The room the server knows the share by.
    pub fn room(&self) -> String {
        URL_SAFE_NO_PAD.encode(self.id)
    }

    /// The guest's proof that it has the link, bound to this connection's
    /// two certificates (fingerprints as lowercase hex).
    pub fn proof(&self, host_fp: &str, guest_fp: &str) -> String {
        let key = hmac::Key::new(hmac::HMAC_SHA256, &self.secret);
        hex(hmac::sign(&key, format!("muxin-share-v1\n{host_fp}\n{guest_fp}").as_bytes()).as_ref())
    }

    /// Whether a guest's proof is right (in constant time).
    pub fn check_proof(&self, host_fp: &str, guest_fp: &str, proof: &str) -> bool {
        let Some(tag) = unhex(proof) else { return false };
        let key = hmac::Key::new(hmac::HMAC_SHA256, &self.secret);
        hmac::verify(&key, format!("muxin-share-v1\n{host_fp}\n{guest_fp}").as_bytes(), &tag).is_ok()
    }

    /// The 6-digit code both sides show for a guest's connection.
    pub fn code(&self, guest_fp: &str) -> String {
        let key = hmac::Key::new(hmac::HMAC_SHA256, &self.secret);
        let tag = hmac::sign(&key, format!("muxin-share-code-v1\n{guest_fp}").as_bytes());
        let n = u32::from_be_bytes([tag.as_ref()[0], tag.as_ref()[1], tag.as_ref()[2], tag.as_ref()[3]]) % 1_000_000;
        format!("{n:06}")
    }
}

/// `scheme://host[:port]` of a server, refusing plain http except to this
/// computer (a server run while developing).
fn origin(server: &str) -> Result<String, String> {
    let s = server.trim().trim_end_matches('/');
    let (scheme, rest) = s.split_once("://").ok_or("The share server needs to be an https:// address.")?;
    let host = rest.split('/').next().unwrap_or("");
    if host.is_empty() || host.contains(['@', ' ', '?', '#']) {
        return Err("The share server's address isn't valid.".into());
    }
    let bare = match host.strip_prefix('[') {
        Some(v6) => v6.split(']').next().unwrap_or(""),
        None => host.rsplit_once(':').map(|(h, _)| h).unwrap_or(host),
    };
    let local = ["localhost", "127.0.0.1", "::1"].contains(&bare);
    match scheme.to_ascii_lowercase().as_str() {
        "https" => Ok(format!("https://{host}")),
        "http" if local => Ok(format!("http://{host}")),
        _ => Err("The share server needs to be an https:// address.".into()),
    }
}

/// A DTLS fingerprint as SDP writes it (`AB:CD:...`) as 32 bytes.
pub fn fingerprint_bytes(sdp_value: &str) -> Option<[u8; 32]> {
    let bytes = unhex(&sdp_value.replace(':', ""))?;
    bytes.try_into().ok()
}

pub fn hex(bytes: &[u8]) -> String {
    bytes.iter().map(|b| format!("{b:02x}")).collect()
}

fn unhex(s: &str) -> Option<Vec<u8>> {
    let s = s.trim();
    if s.len() % 2 != 0 {
        return None;
    }
    (0..s.len()).step_by(2).map(|i| u8::from_str_radix(s.get(i..i + 2)?, 16).ok()).collect()
}

fn percent_decode(s: &str) -> String {
    let bytes = s.as_bytes();
    let mut out = Vec::with_capacity(bytes.len());
    let mut i = 0;
    while i < bytes.len() {
        if bytes[i] == b'%' && let Some(b) = s.get(i + 1..i + 3).and_then(|h| u8::from_str_radix(h, 16).ok()) {
            out.push(b);
            i += 3;
        } else {
            out.push(bytes[i]);
            i += 1;
        }
    }
    String::from_utf8_lossy(&out).into_owned()
}

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

    fn sample() -> Ticket {
        Ticket { server: "https://share.example.com".into(), id: [1; 16], secret: [2; 32], fingerprint: [3; 32] }
    }

    #[test]
    fn links_round_trip() {
        let t = Ticket::new("https://share.example.com/", [9; 32]).unwrap();
        let link = t.link();
        assert!(link.starts_with("https://share.example.com/s#1."));
        assert_eq!(Ticket::parse(&link).unwrap(), t);
        let app = format!("muxin://join?server=https%3A%2F%2Fshare.example.com#{}", t.fragment());
        assert_eq!(Ticket::parse(&app).unwrap(), t);
    }

    #[test]
    fn refuses_plain_http_except_here() {
        assert!(Ticket::new("http://share.example.com", [0; 32]).is_err());
        assert!(Ticket::new("ftp://x", [0; 32]).is_err());
        let local = Ticket::new("http://127.0.0.1:8787", [0; 32]).unwrap();
        assert_eq!(local.server, "http://127.0.0.1:8787");
        assert!(Ticket::new("http://localhost:8787", [0; 32]).is_ok());
        assert!(Ticket::new("http://[::1]:8787", [0; 32]).is_ok());
        // A look-alike host isn't this computer.
        assert!(Ticket::new("http://localhost.evil.com", [0; 32]).is_err());
        let mut t = sample();
        t.server = "http://share.example.com".into();
        assert!(Ticket::parse(&format!("http://share.example.com/s#{}", t.fragment())).is_err());
    }

    #[test]
    fn rejects_damaged_links() {
        let t = sample();
        let link = t.link();
        assert!(Ticket::parse(&link[..link.len() - 4]).is_err());
        assert!(Ticket::parse(&link.replace("#1.", "#2.")).is_err());
        assert!(Ticket::parse("https://share.example.com/s").is_err());
        assert!(!format!("{t:?}").contains(&hex(&t.secret)));
    }

    #[test]
    fn proofs_bind_both_certificates() {
        let t = sample();
        let p = t.proof("aa", "bb");
        assert!(t.check_proof("aa", "bb", &p));
        assert!(!t.check_proof("aa", "cc", &p));
        assert!(!t.check_proof("ab", "bb", &p));
        assert!(!t.check_proof("aa", "bb", "zz"));
        let mut other = sample();
        other.secret = [7; 32];
        assert!(!other.check_proof("aa", "bb", &p));
    }

    #[test]
    fn codes_are_six_digits_per_guest() {
        let t = sample();
        let c = t.code("bb");
        assert_eq!(c.len(), 6);
        assert!(c.chars().all(|ch| ch.is_ascii_digit()));
        assert_eq!(c, t.code("bb"));
        assert_ne!(c, t.code("cc"));
    }

    #[test]
    fn reads_sdp_fingerprints() {
        let fp = fingerprint_bytes("CD:AC:9F:A6:01:82:0E:7F:6B:FD:50:50:57:35:CB:5D:54:8E:9F:82:AD:6E:90:1F:CC:05:89:FC:5E:B2:CD:B4").unwrap();
        assert_eq!(fp[0], 0xcd);
        assert!(fingerprint_bytes("CD:AC").is_none());
    }
}