1use 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
52pub 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
72pub async fn ensure() -> Result<PathBuf, AppError> {
74 ensure_state(state()?, VERSION).await
75}
76
77fn 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 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 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
156async 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
192fn 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
204async 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 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 return Err(invalid());
252 }
253 }
254 }
255 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
273fn 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 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 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 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}