Skip to main content

teams_cli/desktop/
install.rs

1//! Locates the Windows build that serves as the WSL helper, downloading the matching
2//! release on first use and verifying it against the release's SHA256SUMS.
3use crate::error::AppError;
4use sha2::{Digest, Sha256};
5use std::{
6    path::{Path, PathBuf},
7    time::Duration,
8};
9use tar_codec::{Archive as _, Member, MemberPayload as _, TarArchive};
10use tokio::io::AsyncReadExt as _;
11
12use super::helper::PROTOCOL;
13
14const VERSION: &str = env!("CARGO_PKG_VERSION");
15const OVERRIDE: &str = "TEAMS_DESKTOP_HELPER";
16const MAX_ARCHIVE: usize = 64 * 1024 * 1024;
17
18pub enum HelperState {
19    Override(PathBuf),
20    Installed(PathBuf),
21    Missing(PathBuf),
22}
23
24impl HelperState {
25    pub fn describe(&self) -> String {
26        match self {
27            Self::Override(path) => format!("{OVERRIDE}={}", path.display()),
28            Self::Installed(path) => format!("installed at {}", path.display()),
29            Self::Missing(_) if !release_has_helper(VERSION) => format!(
30                "not installed; v{VERSION} predates desktop helpers; {}",
31                development_remedy()
32            ),
33            Self::Missing(_) => format!(
34                "not installed; teams-cli {VERSION} for Windows downloads from the GitHub release on first use"
35            ),
36        }
37    }
38}
39
40pub fn state() -> Result<HelperState, AppError> {
41    if let Some(path) = std::env::var_os(OVERRIDE).filter(|p| !p.is_empty()) {
42        return Ok(HelperState::Override(PathBuf::from(path)));
43    }
44    let path = root()?.join(VERSION).join("teams.exe");
45    Ok(if path.is_file() {
46        HelperState::Installed(path)
47    } else {
48        HelperState::Missing(path)
49    })
50}
51
52/// How to get a helper that speaks this CLI's protocol, for whichever helper is in use.
53pub fn remedy() -> String {
54    if !release_has_helper(VERSION) {
55        return development_remedy();
56    }
57    match state() {
58        Ok(HelperState::Override(_)) => format!(
59            "point {OVERRIDE} at a teams.exe that speaks protocol {PROTOCOL}, such as teams-cli {VERSION} for Windows, or unset it to use the matching release"
60        ),
61        Ok(HelperState::Installed(path) | HelperState::Missing(path)) => {
62            let dir = path.parent().unwrap_or(&path);
63            format!(
64                "delete {} to download the matching release again, or run `make windows-helper` in a source checkout",
65                dir.display()
66            )
67        }
68        Err(error) => error.to_string(),
69    }
70}
71
72/// The helper's path, downloading and installing it if needed.
73pub async fn ensure() -> Result<PathBuf, AppError> {
74    ensure_state(state()?, VERSION).await
75}
76
77// This already-published alpha is diagnostics-only. Development checkouts still
78// carrying its version need a built helper, not its incompatible release binary.
79fn release_has_helper(version: &str) -> bool {
80    version != "0.1.9-alpha.1"
81}
82
83fn development_remedy() -> String {
84    format!(
85        "run `make windows-helper` in the source checkout or set {OVERRIDE} to a teams.exe that speaks protocol {PROTOCOL}"
86    )
87}
88
89async fn ensure_state(state: HelperState, version: &str) -> Result<PathBuf, AppError> {
90    let path = match state {
91        HelperState::Override(path) if path.is_file() => return Ok(path),
92        HelperState::Override(path) => {
93            return Err(AppError::Desktop(format!(
94                "{OVERRIDE} points to {}, which does not exist",
95                path.display()
96            )));
97        }
98        HelperState::Installed(path) => return Ok(path),
99        HelperState::Missing(path) => path,
100    };
101    if !release_has_helper(version) {
102        return Err(AppError::Desktop(format!(
103            "v{version} was published before desktop helpers; automatic helper download is unavailable for this source version; {}",
104            development_remedy()
105        )));
106    }
107    let asset = format!("teams-cli-v{version}-x86_64-pc-windows-msvc.tar.gz");
108    let release = format!("{}/releases/tag/v{version}", env!("CARGO_PKG_REPOSITORY"));
109    let base = format!(
110        "{}/releases/download/v{version}",
111        env!("CARGO_PKG_REPOSITORY")
112    );
113    // Whatever went wrong, the same archive can be fetched and pointed at by hand.
114    let by_hand = |problem: String| {
115        AppError::Desktop(format!(
116            "{problem}; download {asset} from {release}, unpack teams.exe and set {OVERRIDE} to its path, or run `make windows-helper` in a source checkout"
117        ))
118    };
119    let http = reqwest::Client::builder()
120        .timeout(Duration::from_secs(300))
121        .user_agent(concat!("teams-cli/", env!("CARGO_PKG_VERSION")))
122        .build()
123        .map_err(|_| AppError::Desktop("could not create the helper downloader".into()))?;
124    let sums = download(&http, &format!("{base}/SHA256SUMS"))
125        .await
126        .map_err(by_hand)?;
127    let archive = download(&http, &format!("{base}/{asset}"))
128        .await
129        .map_err(by_hand)?;
130    let expected = checksum(&String::from_utf8_lossy(&sums), &asset)
131        .ok_or_else(|| by_hand(format!("SHA256SUMS of v{version} does not list {asset}")))?;
132    if hex(&Sha256::digest(&archive)) != expected {
133        return Err(AppError::Desktop(format!(
134            "{asset} does not match its published checksum; nothing was installed"
135        )));
136    }
137    // Member payloads borrow the decoder across awaits. Parse on a blocking
138    // worker so the downloader remains Send on Rust 1.90, and decompression
139    // does not occupy an async runtime worker.
140    let helper = tokio::task::spawn_blocking(move || {
141        tokio::runtime::Handle::current().block_on(extract(&archive))
142    })
143    .await
144    .map_err(|_| AppError::Desktop("could not read the helper archive".into()))??;
145    install(&path, &helper)?;
146    Ok(path)
147}
148
149fn root() -> Result<PathBuf, AppError> {
150    Ok(dirs::cache_dir()
151        .ok_or_else(|| AppError::Desktop("no cache directory is available".into()))?
152        .join("teams-cli")
153        .join("windows-helper"))
154}
155
156/// The body at `url`, or what went wrong in words.
157async fn download(http: &reqwest::Client, url: &str) -> Result<Vec<u8>, String> {
158    let failed = |_| {
159        format!(
160            "could not download the Windows desktop helper for teams-cli {VERSION}; check the network connection"
161        )
162    };
163    let mut response = http.get(url).send().await.map_err(failed)?;
164    match response.status() {
165        status if status.is_success() => {}
166        reqwest::StatusCode::NOT_FOUND => {
167            return Err(format!(
168                "teams-cli {VERSION} has no published Windows desktop helper (a build that is not a release, or a release still being published)"
169            ));
170        }
171        status => {
172            return Err(format!(
173                "downloading the Windows desktop helper failed with HTTP {}",
174                status.as_u16()
175            ));
176        }
177    }
178    let mut bytes = Vec::new();
179    while let Some(chunk) = response.chunk().await.map_err(failed)? {
180        if bytes.len() + chunk.len() > MAX_ARCHIVE {
181            return Err("the helper download exceeds the size limit".into());
182        }
183        bytes.extend_from_slice(&chunk);
184    }
185    Ok(bytes)
186}
187
188fn hex(bytes: &[u8]) -> String {
189    bytes.iter().map(|b| format!("{b:02x}")).collect()
190}
191
192/// The digest listed for `name` in `sha256sum` output (`<hex>  ./<name>`).
193fn checksum(sums: &str, name: &str) -> Option<String> {
194    sums.lines().find_map(|line| {
195        let (digest, file) = line.split_once(char::is_whitespace)?;
196        let file = file.trim_start().trim_start_matches('*');
197        (file.strip_prefix("./").unwrap_or(file) == name
198            && digest.len() == 64
199            && digest.bytes().all(|b| b.is_ascii_hexdigit()))
200        .then(|| digest.to_ascii_lowercase())
201    })
202}
203
204/// Only one top-level `teams.exe` is accepted. Validate the entire archive
205/// before installing it, including entries after the executable and gzip CRC.
206async fn extract(archive: &[u8]) -> Result<Vec<u8>, AppError> {
207    let invalid = || AppError::Desktop("the helper archive is not valid".into());
208    if archive.len() > MAX_ARCHIVE {
209        return Err(invalid());
210    }
211    let mut reader =
212        async_compression::tokio::bufread::GzipDecoder::new(archive).take(MAX_ARCHIVE as u64 + 1);
213    let mut helper = None;
214    {
215        let mut entries = TarArchive::new(&mut reader).members();
216        let mut chunk = Vec::new();
217        while let Some(entry) = entries.next().await.map_err(|_| invalid())? {
218            if let Member::File {
219                metadata,
220                size,
221                mut payload,
222                ..
223            } = entry
224            {
225                // Match the release layout without normalizing away traversal.
226                let is_helper = matches!(metadata.path.as_str(), "teams.exe" | "./teams.exe");
227                if is_helper {
228                    if helper.is_some() || size > MAX_ARCHIVE as u64 {
229                        return Err(invalid());
230                    }
231                    let mut bytes = Vec::new();
232                    while payload
233                        .next_chunk(&mut chunk, 64 * 1024)
234                        .await
235                        .map_err(|_| invalid())?
236                    {
237                        if bytes.len() + chunk.len() > MAX_ARCHIVE {
238                            return Err(invalid());
239                        }
240                        bytes.extend_from_slice(&chunk);
241                    }
242                    if !bytes.starts_with(b"MZ") {
243                        return Err(invalid());
244                    }
245                    helper = Some(bytes);
246                } else {
247                    payload.skip().await.map_err(|_| invalid())?;
248                }
249            } else if !matches!(entry, Member::Directory { .. }) {
250                // Release packages contain only directories and regular files.
251                return Err(invalid());
252            }
253        }
254    }
255    // The tar end marker can precede padding and the gzip trailer. Reading to
256    // EOF also makes the decompressed-size budget cover ignored archive data.
257    let mut padding = [0; 8192];
258    loop {
259        let read = reader.read(&mut padding).await.map_err(|_| invalid())?;
260        if read == 0 {
261            break;
262        }
263        if padding[..read].iter().any(|&byte| byte != 0) {
264            return Err(invalid());
265        }
266    }
267    if reader.limit() == 0 || !reader.get_ref().get_ref().is_empty() {
268        return Err(invalid());
269    }
270    helper.ok_or_else(invalid)
271}
272
273/// Writes atomically, marks it executable for WSL interop, and removes other versions.
274fn install(path: &Path, bytes: &[u8]) -> Result<(), AppError> {
275    let dir = path
276        .parent()
277        .ok_or_else(|| AppError::Desktop("invalid helper location".into()))?;
278    std::fs::create_dir_all(dir)?;
279    let mut file = tempfile::NamedTempFile::new_in(dir)?;
280    std::io::Write::write_all(&mut file, bytes)?;
281    #[cfg(unix)]
282    {
283        use std::os::unix::fs::PermissionsExt;
284        file.as_file()
285            .set_permissions(std::fs::Permissions::from_mode(0o755))?;
286    }
287    file.persist(path).map_err(|e| AppError::Io(e.error))?;
288    if let Some(versions) = dir.parent()
289        && let Ok(entries) = std::fs::read_dir(versions)
290    {
291        for entry in entries.flatten() {
292            if entry.path() != dir {
293                let _ = std::fs::remove_dir_all(entry.path());
294            }
295        }
296    }
297    Ok(())
298}
299
300#[cfg(test)]
301mod tests {
302    use super::*;
303
304    #[test]
305    fn helper_downloader_can_be_sent_between_runtime_workers() {
306        fn assert_send(_: impl Send) {}
307        assert_send(ensure());
308    }
309
310    #[tokio::test]
311    async fn legacy_release_needs_a_built_helper_but_accepts_explicit_or_cached_builds() {
312        let temp = tempfile::tempdir().unwrap();
313        let path = temp.path().join("teams.exe");
314        let error = ensure_state(HelperState::Missing(path.clone()), "0.1.9-alpha.1")
315            .await
316            .unwrap_err()
317            .to_string();
318        assert!(
319            error.contains("published before desktop helpers")
320                && error.contains("make windows-helper")
321        );
322        assert!(!path.exists());
323        std::fs::write(&path, b"MZ fixture").unwrap();
324        for state in [
325            HelperState::Override(path.clone()),
326            HelperState::Installed(path.clone()),
327        ] {
328            assert_eq!(ensure_state(state, "0.1.9-alpha.1").await.unwrap(), path);
329        }
330    }
331
332    fn archive(files: &[(&str, &[u8])]) -> Vec<u8> {
333        let mut builder = tar::Builder::new(flate2::write::GzEncoder::new(
334            Vec::new(),
335            flate2::Compression::fast(),
336        ));
337        for (name, data) in files {
338            let mut header = tar::Header::new_gnu();
339            header.set_size(data.len() as u64);
340            header.set_mode(0o644);
341            header.set_cksum();
342            builder.append_data(&mut header, name, *data).unwrap();
343        }
344        builder.into_inner().unwrap().finish().unwrap()
345    }
346
347    #[test]
348    fn checksums_match_sha256sum_output_exactly() {
349        let digest = "a".repeat(64);
350        let sums = format!(
351            "{}  ./teams-cli-v1-x.tar.gz.bak\n{digest}  ./teams-cli-v1-x.tar.gz\n",
352            "b".repeat(64)
353        );
354        assert_eq!(checksum(&sums, "teams-cli-v1-x.tar.gz"), Some(digest));
355        assert_eq!(checksum(&sums, "other.tar.gz"), None);
356        assert_eq!(checksum("xyz  ./a.tar.gz", "a.tar.gz"), None);
357        assert_eq!(hex(&[0, 15, 255]), "000fff");
358    }
359
360    #[tokio::test]
361    async fn extracts_only_the_top_level_windows_executable() {
362        let exe = b"MZ fixture";
363        let bytes = archive(&[("./README.md", b"readme"), ("./teams.exe", exe)]);
364        assert_eq!(extract(&bytes).await.unwrap(), exe);
365        assert!(
366            extract(&archive(&[("./nested/teams.exe", exe)]))
367                .await
368                .is_err()
369        );
370        assert!(
371            extract(&archive(&[("./teams.exe", b"#!/bin/sh")]))
372                .await
373                .is_err()
374        );
375        assert!(extract(b"not an archive").await.is_err());
376    }
377
378    #[tokio::test]
379    async fn extracts_a_helper_across_multiple_payload_chunks() {
380        let mut exe = vec![0x5a; 3 * 64 * 1024 + 17];
381        exe[..2].copy_from_slice(b"MZ");
382        assert_eq!(
383            extract(&archive(&[("teams.exe", &exe)])).await.unwrap(),
384            exe
385        );
386    }
387
388    #[cfg(unix)]
389    #[tokio::test]
390    async fn accepts_the_release_workflows_system_tar_packaging() {
391        let temp = tempfile::tempdir().unwrap();
392        let package = temp.path().join("package");
393        std::fs::create_dir(&package).unwrap();
394        std::fs::write(package.join("teams.exe"), b"MZ release fixture").unwrap();
395        std::fs::write(package.join("README.md"), b"readme").unwrap();
396        let output = temp.path().join("helper.tar.gz");
397        // Match .github/workflows/release.yml, including the '.' root entry.
398        assert!(
399            std::process::Command::new("tar")
400                .arg("-C")
401                .arg(&package)
402                .arg("-czf")
403                .arg(&output)
404                .arg(".")
405                .status()
406                .unwrap()
407                .success()
408        );
409        assert_eq!(
410            extract(&std::fs::read(output).unwrap()).await.unwrap(),
411            b"MZ release fixture"
412        );
413    }
414
415    #[tokio::test]
416    async fn rejects_duplicate_helpers_and_damage_after_the_helper() {
417        let duplicate = archive(&[("teams.exe", b"MZ first"), ("./teams.exe", b"MZ second")]);
418        assert!(extract(&duplicate).await.is_err());
419
420        let mut damaged = archive(&[("teams.exe", b"MZ fixture")]);
421        let crc = damaged.len() - 8;
422        damaged[crc] ^= 1;
423        assert!(extract(&damaged).await.is_err(), "gzip CRC must be checked");
424        damaged.truncate(crc);
425        assert!(
426            extract(&damaged).await.is_err(),
427            "missing trailer must fail"
428        );
429
430        // A malformed second tar header must not be hidden by finding the
431        // executable first. Recompress so the gzip checksum remains valid.
432        use std::io::{Read as _, Write as _};
433        let valid = archive(&[("teams.exe", b"MZ fixture"), ("README.md", b"readme")]);
434        let mut raw = Vec::new();
435        flate2::read::GzDecoder::new(valid.as_slice())
436            .read_to_end(&mut raw)
437            .unwrap();
438        raw[1024] ^= 1;
439        let mut gz = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::fast());
440        gz.write_all(&raw).unwrap();
441        assert!(extract(&gz.finish().unwrap()).await.is_err());
442
443        let mut trailing = archive(&[("teams.exe", b"MZ fixture")]);
444        trailing.extend_from_slice(b"junk");
445        assert!(
446            extract(&trailing).await.is_err(),
447            "trailing compressed data must fail"
448        );
449
450        let mut concatenated = archive(&[("teams.exe", b"MZ first")]);
451        concatenated.extend_from_slice(&archive(&[("teams.exe", b"MZ second")]));
452        assert!(
453            extract(&concatenated).await.is_err(),
454            "multiple gzip streams must fail"
455        );
456    }
457
458    #[tokio::test]
459    async fn rejects_links_even_after_a_valid_helper() {
460        let mut builder = tar::Builder::new(flate2::write::GzEncoder::new(
461            Vec::new(),
462            flate2::Compression::fast(),
463        ));
464        let mut file = tar::Header::new_gnu();
465        file.set_size(2);
466        file.set_mode(0o644);
467        builder
468            .append_data(&mut file, "teams.exe", &b"MZ"[..])
469            .unwrap();
470        let mut link = tar::Header::new_gnu();
471        link.set_entry_type(tar::EntryType::Symlink);
472        link.set_size(0);
473        link.set_mode(0o777);
474        builder
475            .append_link(&mut link, "other", "teams.exe")
476            .unwrap();
477        let bytes = builder.into_inner().unwrap().finish().unwrap();
478        assert!(extract(&bytes).await.is_err());
479    }
480
481    #[tokio::test]
482    async fn bounds_decompressed_data_including_ignored_files_and_padding() {
483        // Compressed input is small, but ignored payloads still consume the
484        // same total budget as the helper itself.
485        let bytes = archive(&[("README.md", &vec![0; MAX_ARCHIVE]), ("teams.exe", b"MZ")]);
486        assert!(bytes.len() < MAX_ARCHIVE);
487        assert!(extract(&bytes).await.is_err());
488
489        use std::io::{Read as _, Write as _};
490        let valid = archive(&[("teams.exe", b"MZ")]);
491        let mut raw = Vec::new();
492        flate2::read::GzDecoder::new(valid.as_slice())
493            .read_to_end(&mut raw)
494            .unwrap();
495        raw.resize(MAX_ARCHIVE + 1, 0);
496        let mut gz = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::fast());
497        gz.write_all(&raw).unwrap();
498        assert!(extract(&gz.finish().unwrap()).await.is_err());
499    }
500
501    #[test]
502    fn installs_atomically_and_prunes_other_versions() {
503        let root = tempfile::tempdir().unwrap();
504        let old = root.path().join("0.0.1");
505        std::fs::create_dir_all(&old).unwrap();
506        std::fs::write(old.join("teams.exe"), b"MZ old").unwrap();
507        let path = root.path().join(VERSION).join("teams.exe");
508        install(&path, b"MZ new").unwrap();
509        assert_eq!(std::fs::read(&path).unwrap(), b"MZ new");
510        assert!(!old.exists());
511        #[cfg(unix)]
512        {
513            use std::os::unix::fs::PermissionsExt;
514            let mode = std::fs::metadata(&path).unwrap().permissions().mode();
515            assert_eq!(mode & 0o777, 0o755);
516        }
517    }
518}