Skip to content

YC (S26) | Open Computer History | Continuously record your company computer work, map your workflows, help you find work worth automating, and power your agents' context

feat(attribution): carry website acquisition into desktop signup (#7674)

Louis Beaumonte0e75f2f0bf3
diff --git a/apps/screenpipe-app-tauri/src-tauri/src/acquisition_handoff.rs b/apps/screenpipe-app-tauri/src-tauri/src/acquisition_handoff.rs
new file mode 100644
index 000000000..31cfd59c8
--- /dev/null
+++ b/apps/screenpipe-app-tauri/src-tauri/src/acquisition_handoff.rs
@@ -0,0 +1,552 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+
+//! Download possession -> authenticated account. Best effort, off the
+//! recording/startup path. The server owns authorization and attribution rules.
+use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
+use serde::{Deserialize, Serialize};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::Duration;
+use tauri::{AppHandle, Listener};
+
+static WAKE: tokio::sync::Notify = tokio::sync::Notify::const_new();
+static RETIREMENT: Retirement = Retirement::new();
+static STORAGE: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
+
+const SERVICE: &str = if cfg!(feature = "enterprise-build") {
+ "com.screenpipe.enterprise.acquisition.v1"
+} else { "com.screenpipe.acquisition.v1" };
+const PLACEHOLDER: &str = "00000000-0000-4000-8000-000000000000";
+
+#[derive(Clone, Serialize, Deserialize)]
+struct Pending {
+ grant: String,
+ request_id: String,
+ verifier: String,
+ created: i64,
+ account: Option<String>,
+ claimed: bool,
+ retired: bool,
+}
+
+fn uuid4(value: &str) -> bool {
+ uuid::Uuid::parse_str(value)
+ .map(|v| v.get_version_num() == 4 && v.get_variant() == uuid::Variant::RFC4122 && v.to_string() == value && value != PLACEHOLDER)
+ .unwrap_or(false)
+}
+
+// This is only a local account boundary. The API verifies the JWT signature.
+pub(crate) fn subject(token: &str) -> Option<String> {
+ let bytes = URL_SAFE_NO_PAD.decode(token.split('.').nth(1)?).ok()?;
+ let json: serde_json::Value = serde_json::from_slice(&bytes).ok()?;
+ let sub = json.get("sub")?.as_str()?;
+ (sub.starts_with("user_") && sub.len() <= 105 && sub[5..].chars().all(|c| c.is_ascii_alphanumeric()))
+ .then(|| sub.to_string())
+}
+
+impl Pending {
+ fn new(grant: String) -> Self {
+ // Two independent v4 UUIDs provide 244 random bits. Hashing keeps the
+ // verifier at the API's fixed 32-byte/base64url width.
+ use sha2::{Digest, Sha256};
+ let entropy = format!("{}{}", uuid::Uuid::new_v4(), uuid::Uuid::new_v4());
+ Self { grant, request_id: uuid::Uuid::new_v4().to_string(),
+ verifier: URL_SAFE_NO_PAD.encode(Sha256::digest(entropy.as_bytes())),
+ created: chrono::Utc::now().timestamp(), account: None, claimed: false, retired: false }
+ }
+ fn expired(&self, now: i64) -> bool {
+ self.created > now || now - self.created >= 30 * 24 * 3600
+ }
+ fn crossed_account(&self, current: Option<&str>) -> bool {
+ self.account.as_deref().is_some_and(|pinned| Some(pinned) != current)
+ }
+}
+
+#[cfg(target_os = "macos")]
+fn carrier() -> Option<String> {
+ use std::{ffi::CString, os::unix::ffi::OsStrExt};
+ let executable = std::env::current_exe().ok()?;
+ let bundle = executable.ancestors().find(|p| p.extension().is_some_and(|e| e == "app"))?;
+ let path = CString::new(bundle.as_os_str().as_bytes()).ok()?;
+ let name = CString::new("com.apple.application-instance").ok()?;
+ let mut bytes = [0u8; 36];
+ // Exact-size read; absent, truncated or oversized attributes are ignored.
+ let size = unsafe { libc::getxattr(path.as_ptr(), name.as_ptr(), bytes.as_mut_ptr().cast(), bytes.len(), 0, 0) };
+ if size != 36 { return None; }
+ let grant = String::from_utf8(bytes.to_vec()).ok()?.to_ascii_lowercase();
+ uuid4(&grant).then_some(grant)
+}
+
+fn storage_account(profile: &std::path::Path, origin: &str) -> String {
+ use sha2::{Digest, Sha256};
+ format!("profile-{:x}", Sha256::digest(format!("{}\n{}", profile.display(), origin).as_bytes()))
+}
+
+fn current_storage_account() -> String {
+ storage_account(crate::config::app_data_dir(), &crate::web_base::screenpipe_web_base())
+}
+
+fn tombstone() -> std::path::PathBuf {
+ crate::config::app_data_dir().join(format!("acquisition-retired-{}", current_storage_account()))
+}
+
+fn decode_pending(bytes: &[u8]) -> Result<Pending, ()> {
+ let p: Pending = serde_json::from_slice(bytes).map_err(|_| ())?;
+ if !uuid4(&p.grant) || !uuid4(&p.request_id) || p.verifier.len() != 43 { return Err(()); }
+ Ok(p)
+}
+
+#[cfg(target_os = "macos")]
+async fn load_saved() -> Result<Option<Pending>, ()> {
+ tauri::async_runtime::spawn_blocking(|| {
+ match security_framework::passwords::get_generic_password(SERVICE, &current_storage_account()) {
+ Ok(bytes) => decode_pending(&bytes).map(Some),
+ Err(e) if e.code() == -25300 => Ok(None),
+ Err(_) => Err(()), // A locked Keychain is not an empty one.
+ }
+ }).await.map_err(|_| ())?
+}
+
+#[cfg(target_os = "macos")]
+async fn save(pending: &Pending) -> Result<(), ()> {
+ let bytes = serde_json::to_vec(pending).map_err(|_| ())?;
+ tauri::async_runtime::spawn_blocking(move || {
+ security_framework::passwords::set_generic_password(SERVICE, &current_storage_account(), &bytes).map_err(|_| ())
+ }).await.map_err(|_| ())?
+}
+
+// Windows/Linux reuse the application's credential store and encryption policy.
+// This is a separate credential DB, never the recording database.
+async fn credential_store_at(profile: &std::path::Path, key: Option<[u8; 32]>) -> Result<screenpipe_secrets::SecretStore, ()> {
+ screenpipe_secrets::SecretStore::open_for_data_dir(profile, key).await.map_err(|_| ())
+}
+
+#[cfg(not(target_os = "macos"))]
+async fn credential_store() -> Result<screenpipe_secrets::SecretStore, ()> {
+ let key = match crate::secrets::get_key_if_encryption_enabled() {
+ crate::secrets::KeyResult::Found(k) => Some(k),
+ crate::secrets::KeyResult::NotFound | crate::secrets::KeyResult::Unavailable => None,
+ crate::secrets::KeyResult::AccessDenied => return Err(()),
+ };
+ credential_store_at(crate::config::app_data_dir(), key).await
+}
+
+#[cfg(not(target_os = "macos"))]
+async fn load_saved() -> Result<Option<Pending>, ()> {
+ let store = credential_store().await?;
+ store.get(&format!("{SERVICE}.{}", current_storage_account())).await.map_err(|_| ())?
+ .map(|bytes| decode_pending(&bytes)).transpose()
+}
+
+#[cfg(not(target_os = "macos"))]
+async fn save(pending: &Pending) -> Result<(), ()> {
+ let store = credential_store().await?;
+ store.set(&format!("{SERVICE}.{}", current_storage_account()), &serde_json::to_vec(pending).map_err(|_| ())?)
+ .await.map_err(|_| ())
+}
+
+async fn persist(pending: &Pending) -> Result<(), ()> {
+ let _guard = STORAGE.lock().await;
+ if (RETIREMENT.disabled(&tombstone()) || load_saved().await?.is_some_and(|old| old.retired || old.grant != pending.grant)) && !pending.retired { return Err(()); }
+ save(pending).await
+}
+
+/// Download filenames carry only a random capability, never a user/source ID.
+fn grant_from_filename(name: &str, extension: &str) -> Option<String> {
+ let grant = name.strip_prefix("screenpipe-")?.strip_suffix(extension)?;
+ uuid4(grant).then(|| grant.to_owned())
+}
+
+#[cfg(target_os = "windows")]
+fn carrier() -> Option<String> {
+ carrier_from(std::env::current_exe().ok()?.parent()?)
+}
+
+#[cfg(target_os = "windows")]
+fn carrier_from(directory: &std::path::Path) -> Option<String> {
+ // The installer writes this once. Keep the read bounded so an untrusted or
+ // corrupt install directory cannot turn startup into an unbounded read.
+ let path = directory.join("acquisition-grant");
+ let metadata = std::fs::metadata(&path).ok()?;
+ if metadata.len() != 36 { return None; }
+ use std::io::Read;
+ let mut bytes = Vec::with_capacity(37);
+ std::fs::File::open(path).ok()?.take(37).read_to_end(&mut bytes).ok()?;
+ if bytes.len() != 36 { return None; }
+ let grant = String::from_utf8(bytes).ok()?;
+ uuid4(&grant).then_some(grant)
+}
+
+#[cfg(target_os = "linux")]
+fn carrier() -> Option<String> {
+ // AppImages execute from a temporary mount; APPIMAGE is the original file.
+ let path = std::path::PathBuf::from(std::env::var_os("APPIMAGE")?);
+ grant_from_filename(path.file_name()?.to_str()?, ".AppImage")
+}
+
+// Retirement never waits for the optional credential store. A late credential
+// write cannot remove this separate marker or revive the process-local latch.
+struct Retirement {
+ retired: AtomicBool,
+ cancel: tokio::sync::Notify,
+}
+
+impl Retirement {
+ const fn new() -> Self {
+ Self { retired: AtomicBool::new(false), cancel: tokio::sync::Notify::const_new() }
+ }
+
+ fn is_retired(&self) -> bool { self.retired.load(Ordering::SeqCst) }
+
+ fn disabled(&self, marker: &std::path::Path) -> bool {
+ self.is_retired() || marker.exists()
+ }
+
+ fn retire(&self, marker: &std::path::Path) -> std::io::Result<()> {
+ self.retired.store(true, Ordering::SeqCst);
+ self.cancel.notify_waiters();
+ // Independent of STORAGE and Keychain, including when either is stalled.
+ // A failed marker write still fails closed for this process.
+ let file = std::fs::File::create(marker)?;
+ file.sync_all()
+ }
+
+ async fn until_retired<T>(&self, work: impl std::future::Future<Output = T>) -> Option<T> {
+ let cancellation = self.cancel.notified();
+ tokio::pin!(cancellation);
+ cancellation.as_mut().enable();
+ if self.is_retired() { return None; }
+ tokio::select! {
+ biased;
+ _ = &mut cancellation => None,
+ value = work => if self.is_retired() { None } else { Some(value) },
+ }
+ }
+}
+
+pub fn wake() { WAKE.notify_one(); }
+
+pub fn retire() {
+ if RETIREMENT.retire(&tombstone()).is_err() {
+ tracing::warn!("acquisition retirement marker unavailable; disabled for this process");
+ }
+}
+
+fn watch_settings<R: tauri::Runtime>(
+ app: &AppHandle<R>,
+ store_path: std::path::PathBuf,
+ retire: impl Fn() + Send + Sync + 'static,
+) {
+ // Store.set emits synchronously for both frontend and managed-policy writes.
+ // Inspect the event itself: rereading the store here would deadlock its lock,
+ // and a deferred read could miss a fast false -> true transition.
+ app.listen("store://change", move |event| {
+ let Ok(change) = serde_json::from_str::<serde_json::Value>(event.payload()) else { return; };
+ if change["key"] == "settings"
+ && change["path"].as_str().is_some_and(|path| std::path::Path::new(path) == store_path)
+ && change["value"]["analyticsEnabled"] == false {
+ retire();
+ }
+ });
+}
+
+pub fn spawn(app: AppHandle) {
+ watch_settings(&app, crate::config::app_data_dir().join("store.bin"), retire);
+ tauri::async_runtime::spawn(async move {
+ // Keychain/settings can be temporarily unavailable during startup.
+ for _ in 0..240 {
+ if run(app.clone()).await.is_ok() { return; }
+ tokio::select! {
+ _ = tokio::time::sleep(Duration::from_secs(30)) => {},
+ _ = WAKE.notified() => {},
+ }
+ }
+ });
+}
+
+async fn run(app: AppHandle) -> Result<(), ()> {
+ if RETIREMENT.disabled(&tombstone()) { return Ok(()); }
+ let mut p = match load_saved().await? {
+ Some(p) => p,
+ None => match carrier() { Some(grant) => Pending::new(grant), None => return Ok(()) },
+ };
+ if p.retired { return Ok(()); }
+ // Persist proof BEFORE first claim, including when its HTTP response is lost.
+ persist(&p).await?;
+ let origin = reqwest::Url::parse(&crate::web_base::screenpipe_web_base()).map_err(|_| ())?;
+ if origin.scheme() != "https" || !origin.username().is_empty() || origin.password().is_some()
+ || origin.query().is_some() || origin.fragment().is_some() || origin.path() != "/" { return Err(()); }
+ let client = reqwest::Client::builder().timeout(Duration::from_secs(5))
+ .redirect(reqwest::redirect::Policy::none()).build().map_err(|_| ())?;
+ let mut retry_seconds = 30;
+ loop {
+ let settings = crate::store::SettingsStore::get(&app).map_err(|_| ())?.ok_or(())?;
+ let token = crate::auth_token::cached_cloud_token();
+ let account = token.as_deref().and_then(subject);
+ let enabled = settings.recording.analytics_enabled && !screenpipe_engine::analytics::telemetry_disabled_by_env();
+ if !enabled || p.expired(chrono::Utc::now().timestamp()) || p.crossed_account(account.as_deref())
+ || RETIREMENT.is_retired() {
+ retire();
+ p.retired = true;
+ persist(&p).await?;
+ // Retire locally first. Failed cancellation never authorizes reuse.
+ if p.claimed { let _ = send(&client, &origin, "cancel", &p, None).await; }
+ return Ok(());
+ }
+ if p.account.is_none() && account.is_some() {
+ p.account = account;
+ persist(&p).await?;
+ }
+ let action = if !p.claimed { Some("claim") } else if token.is_some() && p.account.is_some() { Some("bind") } else { None };
+ if let Some(action) = action {
+ // Pin and permission reads precede EVERY request; no logged proof/JWT.
+ if RETIREMENT.is_retired() { continue; }
+ let latest = crate::store::SettingsStore::get(&app).map_err(|_| ())?.ok_or(())?;
+ let latest_token = crate::auth_token::cached_cloud_token();
+ if !latest.recording.analytics_enabled {
+ retire(); p.retired = true; persist(&p).await?; return Ok(());
+ }
+ if latest_token.as_deref().and_then(subject) != p.account {
+ // First login during persistence is progress, not an account
+ // switch. Loop to durably pin it before sending anything.
+ if p.account.is_none() { continue; }
+ retire(); p.retired = true; persist(&p).await?; return Ok(());
+ }
+ let Some(outcome) = RETIREMENT.until_retired(
+ send(&client, &origin, action, &p, latest_token.as_deref())
+ ).await else { return Ok(()); };
+ match outcome.as_deref() {
+ Some("redeemed") => { p.claimed = true; persist(&p).await?; retry_seconds = 30; continue; }
+ Some("bound" | "denied" | "expired" | "invalid_request") => {
+ retire(); p.retired = true; persist(&p).await?; return Ok(());
+ }
+ _ => { retry_seconds = (retry_seconds * 2).min(900); } // Same proof, bounded backoff.
+ }
+ }
+ tokio::select! {
+ _ = tokio::time::sleep(Duration::from_secs(retry_seconds)) => {},
+ _ = RETIREMENT.cancel.notified() => {},
+ _ = WAKE.notified() => {},
+ }
+ }
+}
+
+async fn send(client: &reqwest::Client, origin: &reqwest::Url, action: &str, p: &Pending, token: Option<&str>) -> Option<String> {
+ let url = origin.join(&format!("/api/attribution/download-handoff/{action}")).ok()?;
+ let mut body = serde_json::json!({"request_id":p.request_id,"verifier":p.verifier});
+ if action == "claim" { body["grant"] = p.grant.clone().into(); }
+ let mut request = client.post(url).json(&body);
+ if action == "bind" { request = request.bearer_auth(token?); }
+ let mut response = request.send().await.ok()?;
+ let status = response.status();
+ if !status.is_success() && status.as_u16() != 409 { return None; }
+ // The API's fixed response is tiny. Don't accept an unbounded body.
+ if response.content_length().is_some_and(|n| n > 2048) { return None; }
+ let mut bytes = Vec::new();
+ while let Some(chunk) = response.chunk().await.ok()? {
+ if bytes.len() + chunk.len() > 2048 { return None; }
+ bytes.extend_from_slice(&chunk);
+ }
+ let data: serde_json::Value = serde_json::from_slice(&bytes).ok()?;
+ let outcome = data.get("outcome")?.as_str()?;
+ if !status.is_success() && matches!(outcome, "redeemed" | "bound") { return None; }
+ if matches!(outcome, "redeemed" | "bound") && data.get("request_id")?.as_str()? != p.request_id { return None; }
+ Some(outcome.to_string())
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ #[test]
+ fn portable_filenames_reject_placeholders_and_ambiguous_names() {
+ let grant = "12345678-1234-4234-8234-123456789012";
+ for extension in [".exe", ".AppImage"] {
+ assert_eq!(grant_from_filename(&format!("screenpipe-{grant}{extension}"), extension), Some(grant.into()));
+ for name in [format!("screenpipe-{PLACEHOLDER}{extension}"), format!("screenpipe-{grant}.txt{extension}"), format!("../screenpipe-{grant}{extension}"), format!("screenpipe-{grant}{extension}.exe")] {
+ assert!(grant_from_filename(&name, extension).is_none());
+ }
+ }
+ }
+
+ #[cfg(target_os = "windows")]
+ #[test]
+ fn installed_windows_carrier_is_exact_and_bounded() {
+ let dir = tempfile::tempdir().unwrap();
+ let path = dir.path().join("acquisition-grant");
+ let grant = "12345678-1234-4234-8234-123456789012";
+ std::fs::write(&path, grant).unwrap();
+ assert_eq!(carrier_from(dir.path()), Some(grant.into()));
+ for invalid in [
+ PLACEHOLDER,
+ "12345678-1234-4234-7234-123456789012",
+ "12345678-1234-4234-C234-123456789012",
+ "12345678-1234-4234-8234-12345678901X",
+ ] {
+ std::fs::write(&path, invalid).unwrap();
+ assert!(carrier_from(dir.path()).is_none());
+ }
+ std::fs::write(&path, format!("{grant}\n")).unwrap();
+ assert!(carrier_from(dir.path()).is_none());
+ }
+
+ #[tokio::test]
+ async fn credential_store_preserves_proof_and_retirement_across_restart() {
+ let dir = tempfile::tempdir().unwrap();
+ let account = storage_account(dir.path(), "https://screenpipe.com");
+ let p = Pending::new(uuid::Uuid::new_v4().to_string());
+ {
+ let store = credential_store_at(dir.path(), Some([7; 32])).await.unwrap();
+ store.set(&account, &serde_json::to_vec(&p).unwrap()).await.unwrap();
+ }
+ let store = credential_store_at(dir.path(), Some([7; 32])).await.unwrap();
+ let mut saved = decode_pending(&store.get(&account).await.unwrap().unwrap()).unwrap();
+ assert_eq!(saved.verifier, p.verifier);
+ assert_eq!(saved.request_id, p.request_id);
+ assert!(store.get(&storage_account(dir.path(), "https://preview.example")).await.unwrap().is_none());
+ saved.retired = true;
+ store.set(&account, &serde_json::to_vec(&saved).unwrap()).await.unwrap();
+ assert!(decode_pending(&store.get(&account).await.unwrap().unwrap()).unwrap().retired);
+ }
+
+ #[test]
+ fn dev_e2e_and_preview_profiles_cannot_share_production_proof() {
+ let prod = storage_account(std::path::Path::new("/profile/prod"), "https://screenpipe.com");
+ assert_ne!(prod, storage_account(std::path::Path::new("/profile/dev"), "https://screenpipe.com"));
+ assert_ne!(prod, storage_account(std::path::Path::new("/profile/e2e"), "https://screenpipe.com"));
+ assert_ne!(prod, storage_account(std::path::Path::new("/profile/prod"), "https://preview.example"));
+ }
+ #[test]
+ fn proof_survives_restart_without_rotation() {
+ let p = Pending::new(uuid::Uuid::new_v4().to_string());
+ let copy: Pending = serde_json::from_slice(&serde_json::to_vec(&p).unwrap()).unwrap();
+ assert_eq!(p.verifier, copy.verifier);
+ assert_eq!(p.request_id, copy.request_id);
+ assert_eq!(URL_SAFE_NO_PAD.decode(p.verifier).unwrap().len(), 32);
+ }
+ #[test]
+ fn account_switch_logout_and_clock_rollback_retire() {
+ let mut p = Pending::new(uuid::Uuid::new_v4().to_string());
+ assert!(!p.crossed_account(None));
+ p.account = Some("user_A".into());
+ assert!(!p.crossed_account(Some("user_A")));
+ assert!(p.crossed_account(Some("user_B")));
+ assert!(p.crossed_account(None));
+ assert!(p.expired(p.created - 1));
+ assert!(p.expired(p.created + 30 * 24 * 3600));
+ }
+ #[test]
+ fn no_placeholder_or_untrusted_subject() {
+ assert!(!uuid4(PLACEHOLDER));
+ assert!(!uuid4("not-a-grant"));
+ assert!(subject("not-a-token").is_none());
+ }
+ async fn response_server(response: String) -> (reqwest::Client, reqwest::Url) {
+ use tokio::io::{AsyncReadExt, AsyncWriteExt};
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let address = listener.local_addr().unwrap();
+ tokio::spawn(async move {
+ let (mut socket, _) = listener.accept().await.unwrap();
+ let mut request = [0u8; 4096];
+ let _ = socket.read(&mut request).await;
+ let _ = socket.write_all(response.as_bytes()).await;
+ });
+ (reqwest::Client::new(), reqwest::Url::parse(&format!("http://{address}/")).unwrap())
+ }
+ #[tokio::test]
+ async fn retry_provisioning_and_reject_wrong_response_identity() {
+ let p = Pending::new(uuid::Uuid::new_v4().to_string());
+ let (client, origin) = response_server("HTTP/1.1 503 Service Unavailable\r\nContent-Length: 0\r\n\r\n".into()).await;
+ assert!(send(&client, &origin, "bind", &p, Some("synthetic")).await.is_none());
+ let body = r#"{"outcome":"bound","request_id":"wrong"}"#;
+ let (client, origin) = response_server(format!("HTTP/1.1 200 OK\r\nContent-Length: {}\r\n\r\n{}", body.len(), body)).await;
+ assert!(send(&client, &origin, "bind", &p, Some("synthetic")).await.is_none());
+ }
+ #[tokio::test]
+ async fn rejects_oversized_chunked_response() {
+ let p = Pending::new(uuid::Uuid::new_v4().to_string());
+ let response = format!("HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\n\r\n1000\r\n{}\r\n0\r\n\r\n", "x".repeat(4096));
+ let (client, origin) = response_server(response).await;
+ assert!(send(&client, &origin, "claim", &p, None).await.is_none());
+ }
+
+ #[tokio::test]
+ async fn retirement_does_not_wait_for_stalled_credential_storage() {
+ let dir = tempfile::tempdir().unwrap();
+ let marker = dir.path().join("retired");
+ let retirement = Retirement::new();
+ let _stalled_credentials = STORAGE.lock().await;
+ tokio::time::timeout(Duration::from_millis(200), async {
+ retirement.retire(&marker).unwrap();
+ }).await.expect("retirement must not block authentication on credentials");
+ assert!(retirement.disabled(&marker));
+ let store = credential_store_at(dir.path(), None).await.unwrap();
+ let pending = Pending::new(uuid::Uuid::new_v4().to_string());
+ store.set("late-proof", &serde_json::to_vec(&pending).unwrap()).await.unwrap();
+ assert!(Retirement::new().disabled(&marker), "restart must remain retired after late persistence");
+ }
+
+ #[test]
+ fn settings_event_retires_even_when_reenabled_before_worker_wakes() {
+ let dir = tempfile::tempdir().unwrap();
+ let store_path = dir.path().join("store.bin");
+ let marker = dir.path().join("retired");
+ let retirement = std::sync::Arc::new(Retirement::new());
+ let app = tauri::test::mock_builder()
+ .plugin(tauri_plugin_store::Builder::default().build())
+ .build(tauri::test::mock_context(tauri::test::noop_assets())).unwrap();
+ let state = retirement.clone();
+ let saved_marker = marker.clone();
+ watch_settings(app.handle(), store_path.clone(), move || {
+ state.retire(&saved_marker).unwrap();
+ });
+ let store = tauri_plugin_store::StoreBuilder::new(app.handle(), store_path)
+ .disable_auto_save().build().unwrap();
+ let other = tauri_plugin_store::StoreBuilder::new(app.handle(), dir.path().join("other.bin"))
+ .disable_auto_save().build().unwrap();
+ other.set("settings", serde_json::json!({"analyticsEnabled": false}));
+ store.set("unrelated", serde_json::json!({"analyticsEnabled": false}));
+ store.set("settings", serde_json::json!({"analyticsEnabled": true}));
+ assert!(!retirement.is_retired());
+ store.set("settings", serde_json::json!({"analyticsEnabled": false}));
+ store.set("settings", serde_json::json!({"analyticsEnabled": true}));
+ assert!(retirement.disabled(&marker));
+ assert!(Retirement::new().disabled(&marker));
+ }
+
+ #[tokio::test]
+ async fn retirement_cancels_stalled_http_and_prevents_another_request() {
+ use tokio::io::AsyncReadExt;
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let origin = reqwest::Url::parse(&format!("http://{}/", listener.local_addr().unwrap())).unwrap();
+ let (received, request_received) = tokio::sync::oneshot::channel();
+ let server = tokio::spawn(async move {
+ let (mut socket, _) = listener.accept().await.unwrap();
+ let mut request = [0u8; 4096];
+ socket.read(&mut request).await.unwrap();
+ received.send(()).unwrap();
+ std::future::pending::<()>().await;
+ });
+ let retirement = std::sync::Arc::new(Retirement::new());
+ let state = retirement.clone();
+ let worker = tokio::spawn(async move {
+ let p = Pending::new(uuid::Uuid::new_v4().to_string());
+ state.until_retired(send(&reqwest::Client::new(), &origin, "bind", &p, Some("synthetic"))).await
+ });
+ tokio::time::timeout(Duration::from_secs(2), request_received).await.unwrap().unwrap();
+ let dir = tempfile::tempdir().unwrap();
+ retirement.retire(&dir.path().join("retired")).unwrap();
+ assert!(tokio::time::timeout(Duration::from_millis(200), worker).await.unwrap().unwrap().is_none());
+ assert!(retirement.until_retired(async { panic!("retired proof must never start another request") }).await.is_none());
+ server.abort();
+ }
+
+ #[tokio::test]
+ async fn failed_marker_write_still_cancels_for_this_process() {
+ let dir = tempfile::tempdir().unwrap();
+ let retirement = Retirement::new();
+ assert!(retirement.retire(dir.path()).is_err());
+ assert!(retirement.is_retired());
+ assert!(retirement.until_retired(async { "must not run" }).await.is_none());
+ }
+
+}
diff --git a/apps/screenpipe-app-tauri/src-tauri/src/auth_token.rs b/apps/screenpipe-app-tauri/src-tauri/src/auth_token.rs
index c6b862c4b..72df0c567 100644
--- a/apps/screenpipe-app-tauri/src-tauri/src/auth_token.rs
+++ b/apps/screenpipe-app-tauri/src-tauri/src/auth_token.rs
@@ -122,7 +122,15 @@ async fn load_session_token_at(data_dir: &Path, key: Option<[u8; 32]>) -> Option
pub async fn store_cloud_token(token: Option<&str>) -> anyhow::Result<()> {
let normalized = normalize_cloud_token(token.map(str::to_string));
let token = normalized.as_deref();
+ let previous = cached_cloud_token().as_deref().and_then(crate::acquisition_handoff::subject);
+ let next = token.and_then(crate::acquisition_handoff::subject);
+ if token.is_none() || (previous.is_some() && previous != next) {
+ // Retire attribution before changing accounts. The worker cannot overwrite
+ // the independent retirement marker if an HTTP request is already in flight.
+ crate::acquisition_handoff::retire();
+ }
seed_cloud_token(normalized.clone());
+ crate::acquisition_handoff::wake();
let dir = crate::config::app_data_dir();
match token {
Some(t) => store_token_at(dir, write_encryption_key()?, Some(t)).await,
diff --git a/apps/screenpipe-app-tauri/src-tauri/src/main.rs b/apps/screenpipe-app-tauri/src-tauri/src/main.rs
index 689d2079a..c05223d8d 100644
--- a/apps/screenpipe-app-tauri/src-tauri/src/main.rs
+++ b/apps/screenpipe-app-tauri/src-tauri/src/main.rs
@@ -55,6 +55,7 @@ mod audio_exclusions;
#[cfg(all(test, target_os = "windows", feature = "vulkan"))]
mod whisper_vulkan_tests;
mod auth_token;
+mod acquisition_handoff;
mod brain_views;
mod calendar;
mod capture_session;
@@ -2334,6 +2335,8 @@ async fn main() {
))]
enterprise_autostart::spawn(&app_handle);
+ acquisition_handoff::spawn(app_handle.clone());
+
// Use persistent analytics_id for PostHog (consistent across frontend and backend)
let unique_id = store.recording.analytics_id.clone();
let email = store.user.email.unwrap_or_default();
diff --git a/apps/screenpipe-app-tauri/src-tauri/windows/hooks.nsh b/apps/screenpipe-app-tauri/src-tauri/windows/hooks.nsh
index 3ab61d8ee..7b8cec871 100644
--- a/apps/screenpipe-app-tauri/src-tauri/windows/hooks.nsh
+++ b/apps/screenpipe-app-tauri/src-tauri/windows/hooks.nsh
@@ -9,6 +9,88 @@
!include "x64.nsh"
!include "LogicLib.nsh"
+; Save a filename-carried acquisition grant once. This is deliberately a pure
+; NSIS parser: attribution is optional and never launches a shell or blocks an
+; install. Expected filename: screenpipe-<lowercase canonical UUID v4>.exe.
+!macro _SP_SaveAcquisitionGrant
+ Push $0
+ Push $1
+ Push $2
+ Push $3
+ ${IfNot} ${FileExists} "$INSTDIR\acquisition-grant"
+ StrLen $0 $EXEFILE
+ ${If} $0 == 51
+ StrCpy $1 $EXEFILE 11 0
+ StrCpy $2 $EXEFILE 4 47
+ ${If} $1 == "screenpipe-"
+ ${AndIf} $2 == ".exe"
+ StrCpy $1 $EXEFILE 36 11
+ ${If} $1 != "00000000-0000-4000-8000-000000000000"
+ StrCpy $2 $1 1 14
+ ${If} $2 == "4"
+ StrCpy $2 $1 1 19
+ ${If} $2 == "8"
+ ${OrIf} $2 == "9"
+ ${OrIf} $2 == "a"
+ ${OrIf} $2 == "b"
+ StrCpy $0 0
+ StrCpy $3 1
+ ${Do}
+ StrCpy $2 $1 1 $0
+ ${If} $0 == 8
+ ${OrIf} $0 == 13
+ ${OrIf} $0 == 18
+ ${OrIf} $0 == 23
+ ${If} $2 != "-"
+ StrCpy $3 0
+ ${ExitDo}
+ ${EndIf}
+ ${Else}
+ ${If} $2 != "0"
+ ${AndIf} $2 != "1"
+ ${AndIf} $2 != "2"
+ ${AndIf} $2 != "3"
+ ${AndIf} $2 != "4"
+ ${AndIf} $2 != "5"
+ ${AndIf} $2 != "6"
+ ${AndIf} $2 != "7"
+ ${AndIf} $2 != "8"
+ ${AndIf} $2 != "9"
+ ${AndIf} $2 != "a"
+ ${AndIf} $2 != "b"
+ ${AndIf} $2 != "c"
+ ${AndIf} $2 != "d"
+ ${AndIf} $2 != "e"
+ ${AndIf} $2 != "f"
+ StrCpy $3 0
+ ${ExitDo}
+ ${EndIf}
+ ${EndIf}
+ IntOp $0 $0 + 1
+ ${If} $0 >= 36
+ ${ExitDo}
+ ${EndIf}
+ ${Loop}
+ ${If} $3 == 1
+ ClearErrors
+ FileOpen $0 "$INSTDIR\acquisition-grant" w
+ ${IfNot} ${Errors}
+ FileWrite $0 $1
+ FileClose $0
+ ${EndIf}
+ ${EndIf}
+ ${EndIf}
+ ${EndIf}
+ ${EndIf}
+ ${EndIf}
+ ${EndIf}
+ ${EndIf}
+ Pop $3
+ Pop $2
+ Pop $1
+ Pop $0
+!macroend
+
; Stop the service through SCM without executing an installed helper. This is
; required when an administrator removed a hostile ProgramData namespace: old
; helpers logged from prepare-upgrade and could recreate that namespace with
@@ -262,6 +344,8 @@
!macroend
!macro NSIS_HOOK_POSTINSTALL
+ !insertmacro _SP_SaveAcquisitionGrant
+
; Binaries moved aside above. The orphan holding them has usually exited by
; now; whatever is left gets swept by the app on its next boot.
Delete "$INSTDIR\*.sp-old*"
diff --git a/docs/COVERAGE.md b/docs/COVERAGE.md
index e40fcd0c9..a35324f58 100644
--- a/docs/COVERAGE.md
+++ b/docs/COVERAGE.md
@@ -37,16 +37,16 @@ results and `cargo llvm-cov` data on top when judging release confidence.
### Core Engine
- Mapped suites: 37
-- Mapped Rust files: 394
-- Active test blocks: 3869
+- Mapped Rust files: 395
+- Active test blocks: 3872
- Ignored/manual test blocks: 181
-- Weighted coverage points: 3194.4
+- Weighted coverage points: 3197.1
| Platform | Suites | Active tests | Ignored tests | Weighted points | Layers | Flows | Critical score |
| --- | --- | --- | --- | --- | --- | --- | --- |
-| windows | 33 | 3721 | 166 | 3127.4 | 21 | 11 | 100% |
-| macos | 32 | 3749 | 142 | 3116.7 | 22 | 11 | 100% |
-| linux | 29 | 3299 | 141 | 2745.7 | 20 | 11 | 100% |
+| windows | 33 | 3724 | 166 | 3130.1 | 21 | 11 | 100% |
+| macos | 32 | 3752 | 142 | 3119.4 | 22 | 11 | 100% |
+| linux | 29 | 3302 | 141 | 2748.4 | 20 | 11 | 100% |
## Refresh
diff --git a/docs/coverage/CORE.md b/docs/coverage/CORE.md
index 40f8e7cf6..a51a90642 100644
--- a/docs/coverage/CORE.md
+++ b/docs/coverage/CORE.md
@@ -8,11 +8,11 @@ confidence, and criticality.
- Manifest: `docs/coverage/core-engine-map.json`
- Tracked crates: screenpipe-engine, screenpipe-db, screenpipe-sqlite-coordinator, screenpipe-audio, screenpipe-screen, screenpipe-a11y, screenpipe-fs
- Mapped suites: 37
-- Mapped Rust files: 394
-- Active test blocks: 3869
+- Mapped Rust files: 395
+- Active test blocks: 3872
- Ignored/manual test blocks: 181
-- Declared test blocks: 4050
-- Weighted coverage points: 3194.4
+- Declared test blocks: 4053
+- Weighted coverage points: 3197.1
Confidence weights: strong=1.0, partial=0.7, conditional=0.4, smoke=0.3.
Criticality weights: high=1.0, medium=0.7, low=0.4.
@@ -23,16 +23,16 @@ are explicitly enabled in a runtime lane.
| Platform | Suites | Active tests | Ignored tests | Weighted points | Layers | Flows | Critical score |
| --- | --- | --- | --- | --- | --- | --- | --- |
-| windows | 33 | 3721 | 166 | 3127.4 | 21 | 11 | 100% |
-| macos | 32 | 3749 | 142 | 3116.7 | 22 | 11 | 100% |
-| linux | 29 | 3299 | 141 | 2745.7 | 20 | 11 | 100% |
+| windows | 33 | 3724 | 166 | 3130.1 | 21 | 11 | 100% |
+| macos | 32 | 3752 | 142 | 3119.4 | 22 | 11 | 100% |
+| linux | 29 | 3302 | 141 | 2748.4 | 20 | 11 | 100% |
## Crate Summary
| Crate | Suites | Integration files | Source unit files | Active tests | Ignored tests | Weighted points | Flows |
| --- | --- | --- | --- | --- | --- | --- | --- |
| screenpipe-engine | 12 | 22 | 130 | 1856 | 53 | 1429.9 | 10 |
-| screenpipe-db | 5 | 68 | 27 | 626 | 31 | 596.7 | 9 |
+| screenpipe-db | 5 | 68 | 28 | 629 | 31 | 599.4 | 9 |
| screenpipe-sqlite-coordinator | 1 | 0 | 3 | 27 | 0 | 27.0 | 2 |
| screenpipe-audio | 8 | 29 | 53 | 695 | 53 | 606.9 | 5 |
| screenpipe-screen | 6 | 9 | 19 | 276 | 9 | 245.4 | 4 |
@@ -62,25 +62,25 @@ bun run coverage:core -- --llvm-cov-summary ../../docs/coverage/core-llvm-cov-su
| Layer | windows | macos | linux |
| --- | --- | --- | --- |
-| accessibility | 4 suites / 383 active / 35 ignored / 348.0 pts | 4 suites / 424 active / 11 ignored / 343.7 pts | 4 suites / 341 active / 7 ignored / 313.0 pts |
+| accessibility | 4 suites / 384 active / 35 ignored / 349.0 pts | 4 suites / 425 active / 11 ignored / 344.7 pts | 4 suites / 342 active / 7 ignored / 314.0 pts |
| audio | 10 suites / 833 active / 57 ignored / 744.9 pts | 9 suites / 827 active / 57 ignored / 740.7 pts | 8 suites / 748 active / 56 ignored / 685.4 pts |
| audio-device | 2 suites / 235 active / 7 ignored / 211.3 pts | 2 suites / 235 active / 7 ignored / 211.3 pts | 1 suites / 156 active / 6 ignored / 156.0 pts |
| configuration | 2 suites / 153 active / 3 ignored / 138.7 pts | 2 suites / 153 active / 3 ignored / 138.7 pts | 2 suites / 153 active / 3 ignored / 138.7 pts |
-| database | 7 suites / 583 active / 27 ignored / 553.7 pts | 7 suites / 583 active / 27 ignored / 553.7 pts | 7 suites / 583 active / 27 ignored / 553.7 pts |
-| db-search | 2 suites / 119 active / 9 ignored / 119.0 pts | 2 suites / 119 active / 9 ignored / 119.0 pts | 2 suites / 119 active / 9 ignored / 119.0 pts |
+| database | 7 suites / 585 active / 27 ignored / 555.4 pts | 7 suites / 585 active / 27 ignored / 555.4 pts | 7 suites / 585 active / 27 ignored / 555.4 pts |
+| db-search | 2 suites / 120 active / 9 ignored / 120.0 pts | 2 suites / 120 active / 9 ignored / 120.0 pts | 2 suites / 120 active / 9 ignored / 120.0 pts |
| engine-lifecycle | 6 suites / 270 active / 1 ignored / 242.0 pts | 6 suites / 270 active / 1 ignored / 242.0 pts | 6 suites / 266 active / 9 ignored / 241.1 pts |
| local-api | 3 suites / 479 active / 12 ignored / 339.2 pts | 3 suites / 479 active / 12 ignored / 339.2 pts | 3 suites / 479 active / 12 ignored / 339.2 pts |
| meeting | 6 suites / 1751 active / 32 ignored / 1433.0 pts | 6 suites / 1751 active / 32 ignored / 1433.0 pts | 4 suites / 1397 active / 28 ignored / 1102.7 pts |
-| ocr | 4 suites / 140 active / 7 ignored / 129.8 pts | 4 suites / 133 active / 7 ignored / 127.6 pts | 3 suites / 124 active / 6 ignored / 118.6 pts |
+| ocr | 4 suites / 141 active / 7 ignored / 130.8 pts | 4 suites / 134 active / 7 ignored / 128.6 pts | 3 suites / 125 active / 6 ignored / 119.6 pts |
| os-integration | 1 suites / 6 active / 0 ignored / 1.7 pts | 1 suites / 6 active / 0 ignored / 1.7 pts | - |
-| performance | 13 suites / 1682 active / 82 ignored / 1485.1 pts | 14 suites / 1792 active / 87 ignored / 1529.1 pts | 13 suites / 1682 active / 82 ignored / 1485.1 pts |
+| performance | 13 suites / 1685 active / 82 ignored / 1487.8 pts | 14 suites / 1795 active / 87 ignored / 1531.8 pts | 13 suites / 1685 active / 82 ignored / 1487.8 pts |
| pipes | 1 suites / 551 active / 3 ignored / 385.7 pts | 1 suites / 551 active / 3 ignored / 385.7 pts | 1 suites / 551 active / 3 ignored / 385.7 pts |
| privacy | 5 suites / 1013 active / 42 ignored / 816.8 pts | 5 suites / 1054 active / 18 ignored / 812.5 pts | 5 suites / 971 active / 14 ignored / 781.7 pts |
| real-app | - | 1 suites / 110 active / 5 ignored / 44.0 pts | - |
| speaker | 2 suites / 416 active / 18 ignored / 416.0 pts | 2 suites / 416 active / 18 ignored / 416.0 pts | 2 suites / 416 active / 18 ignored / 416.0 pts |
-| storage | 4 suites / 688 active / 41 ignored / 573.7 pts | 4 suites / 688 active / 41 ignored / 573.7 pts | 4 suites / 688 active / 41 ignored / 573.7 pts |
+| storage | 4 suites / 689 active / 41 ignored / 574.7 pts | 4 suites / 689 active / 41 ignored / 574.7 pts | 4 suites / 689 active / 41 ignored / 574.7 pts |
| sync | 1 suites / 551 active / 3 ignored / 385.7 pts | 1 suites / 551 active / 3 ignored / 385.7 pts | 1 suites / 551 active / 3 ignored / 385.7 pts |
-| timeline | 4 suites / 1236 active / 48 ignored / 1015.2 pts | 4 suites / 1236 active / 48 ignored / 1015.2 pts | 4 suites / 1236 active / 48 ignored / 1015.2 pts |
+| timeline | 4 suites / 1237 active / 48 ignored / 1016.2 pts | 4 suites / 1237 active / 48 ignored / 1016.2 pts | 4 suites / 1237 active / 48 ignored / 1016.2 pts |
| transcription | 7 suites / 890 active / 53 ignored / 696.6 pts | 6 suites / 884 active / 53 ignored / 692.4 pts | 6 suites / 884 active / 53 ignored / 692.4 pts |
| ui-events | 4 suites / 828 active / 34 ignored / 627.7 pts | 3 suites / 759 active / 5 ignored / 579.4 pts | 3 suites / 759 active / 5 ignored / 579.4 pts |
| vision-capture | 6 suites / 576 active / 32 ignored / 453.6 pts | 6 suites / 569 active / 32 ignored / 451.4 pts | 5 suites / 560 active / 31 ignored / 442.4 pts |
@@ -134,8 +134,8 @@ bun run coverage:core -- --llvm-cov-summary ../../docs/coverage/core-llvm-cov-su
| db-accessibility-ui-events | screenpipe-db | windows, macos, linux | database, configuration, accessibility, ui-events, performance | settings-to-engine-config, accessibility-ui-events, performance-liveness | medium | partial | integration | 7 | 28 | 2 | Elements bulk insert, on-screen filtering, UI event batching, DB tier config, and ignored heavy-read real-DB probes. |
| db-audio-meetings-speakers | screenpipe-db | windows, macos, linux | database, audio, meeting, speaker | audio-record-transcribe, audio-device-health, meeting-live-notes | high | strong | integration | 19 | 135 | 4 | Audio transcript dedupe, live meeting mirroring, end-generation and open-meeting invariants, liveness, and speaker reassignment coverage. |
| db-runtime-reliability | screenpipe-db | windows, macos, linux | database, performance | performance-liveness | high | partial | mixed | 17 | 51 | 6 | SQLite hard-fault classification, failpoint VFS injection, fresh-identity recovery verification with integrity/FK/write canaries, query cancellation, close-severs-connections regressions, multi-pool WAL parity, runtime version pinning, and WAL chaos plus memory-pressure probes, plus read-only quarantine self-heal verification for transient IOERR faults. |
-| db-search-indexing | screenpipe-db | windows, macos, linux | db-search, ocr, accessibility, performance | local-api-search, capture-ocr-pipeline, accessibility-ui-events, performance-liveness | high | strong | mixed | 14 | 106 | 4 | FTS, tokenizer, OCR snapshot search, query planning, ordering, accessibility search, and contention coverage. |
-| db-timeline-frames | screenpipe-db | windows, macos, linux | database, timeline, storage, performance | timeline-streaming, performance-liveness | high | strong | mixed | 39 | 307 | 15 | Frame/audio joins, timeline query shape, suggestions frames, write queue, DB primitives (src/db.rs split into src/db/ modules), feedback record upserts, media eviction anti-join regressions, SAF output registry, semantic storage, and timeline performance. |
+| db-search-indexing | screenpipe-db | windows, macos, linux | db-search, ocr, accessibility, performance | local-api-search, capture-ocr-pipeline, accessibility-ui-events, performance-liveness | high | strong | mixed | 14 | 107 | 4 | FTS, tokenizer, OCR snapshot search, query planning, ordering, accessibility search, and contention coverage. |
+| db-timeline-frames | screenpipe-db | windows, macos, linux | database, timeline, storage, performance | timeline-streaming, performance-liveness | high | strong | mixed | 39 | 308 | 15 | Frame/audio joins, timeline query shape, suggestions frames, write queue, DB primitives (src/db.rs split into src/db/ modules), feedback record upserts, media eviction anti-join regressions, SAF output registry, semantic storage, and timeline performance. |
| engine-api-routes | screenpipe-engine | windows, macos, linux | local-api, timeline, meeting, transcription | local-api-search, timeline-streaming, meeting-live-notes, audio-record-transcribe | high | partial | mixed | 45 | 430 | 7 | Route/unit coverage for search, health, streaming, meetings, time/timezone, and transcription. Legacy endpoint/websocket tests require local data and remain ignored. |
| engine-capture-timeline | screenpipe-engine | windows, macos, linux | vision-capture, timeline, storage, performance | capture-ocr-pipeline, timeline-streaming, performance-liveness | high | partial | mixed | 25 | 306 | 26 | Covers capture trigger logic, frame/audio linking, hot cache, timeline refresh regressions, fragmented MP4 extraction, and HD-mode control. Several real-data tests are intentionally ignored by default. |
| engine-config-lifecycle | screenpipe-engine | windows, macos, linux | configuration, engine-lifecycle, performance | settings-to-engine-config, engine-health-lifecycle, performance-liveness | high | strong | mixed | 13 | 125 | 1 | Fast logic coverage for the config bridge, health-endpoint identity, tray health debounce, sleep/power policies, and queue backpressure. |
@@ -284,7 +284,7 @@ bun run coverage:core -- --llvm-cov-summary ../../docs/coverage/core-llvm-cov-su
| db-timeline-frames | screenpipe-db | src/db/planner_stats_tests.rs | source | 6 | 0 | 6 |
| db-timeline-frames | screenpipe-db | src/db/setup.rs | source | 7 | 0 | 7 |
| db-timeline-frames | screenpipe-db | src/db/source_identity.rs | source | 3 | 0 | 3 |
-| db-search-indexing | screenpipe-db | src/db/starred.rs | source | 1 | 0 | 1 |
+| db-search-indexing | screenpipe-db | src/db/starred.rs | source | 2 | 0 | 2 |
| db-timeline-frames | screenpipe-db | src/db/tests.rs | source | 26 | 1 | 27 |
| db-timeline-frames | screenpipe-db | src/db/truncation_tests.rs | source | 1 | 0 | 1 |
| db-runtime-reliability | screenpipe-db | src/failpoint_vfs.rs | source | 4 | 0 | 4 |
diff --git a/docs/macos-acquisition-handoff.md b/docs/macos-acquisition-handoff.md
new file mode 100644
index 000000000..d43ae7c57
--- /dev/null
+++ b/docs/macos-acquisition-handoff.md
@@ -0,0 +1,77 @@
+# Acquisition handoff
+
+<!-- doc-covers: none -->
+
+The website companion saves the original, consented browser source and places
+an opaque download grant in a platform carrier. The app persists a verifier,
+claims the grant, and binds it using the verified Clerk session. This runs in a
+background task, independent of recording. All platforms use the same claim,
+retry, account-boundary, and retirement protocol.
+
+```text
+signed app + xattr -> ZIP -> website personalizes UUID and ZIP checksums
+ -> macOS extracts app -> Keychain proof -> claim -> authenticated bind
+
+signed screenpipe-<UUID>.exe -> NSIS validates filename -> installed token
+ -> Windows credential-store proof -> claim -> authenticated bind
+
+signed screenpipe-<UUID>.AppImage -> APPIMAGE filename -> credential-store proof
+ -> claim -> authenticated bind
+```
+
+Retries reuse the same request and verifier. Saved proof survives app updates
+that remove the xattr. Account switch/logout invalidates in-flight work and saves
+a retirement marker before changing accounts, without waiting for credential
+storage. The native settings-store listener also retires immediately on analytics
+opt-out, including rapid off/on toggles and requests already in flight. A late
+credential write cannot erase a persisted marker, so restart remains retired.
+If the filesystem rejects the marker write, retirement is guaranteed only for
+the current process. Same-account JWT refresh wakes the
+worker without retiring the acquisition. Missing account provisioning is retried.
+No token, source data or HTTP error body is logged.
+
+Prepare artifacts locally from an already signed/notarized app:
+
+```sh
+python3 scripts/package-attribution-carrier.py \
+ --app /path/to/screenpipe.app --platform macos-arm \
+ --release VERSION --output /path/to/new-output-directory
+```
+
+The script checks app version, architecture, signature and metadata round-trip,
+then writes `screenpipe-attribution.zip` and `screenpipe-attribution.json`.
+For Linux or Windows, pass the original versioned release artifact instead:
+
+```sh
+python3 scripts/package-attribution-carrier.py \
+ --artifact /path/to/versioned-installer \
+ --platform linux \
+ --release VERSION --output /path/to/new-output-directory
+```
+
+Linux writes `screenpipe-attribution.AppImage`; Windows and Windows ARM write
+`screenpipe-attribution.exe`. Each has a `screenpipe-attribution.json` manifest
+containing the original byte length and SHA-256. Windows preparation requires a
+Windows host and checks Authenticode, version metadata, and architecture evidence
+in the versioned release filename. The NSIS bootstrap PE machine is not treated
+as payload architecture. Filename personalization preserves the signed bytes.
+Use `--platform windows` for x86_64 and `--platform windows-arm` for ARM64.
+
+The script never uploads artifacts or changes publication pointers. Production
+activation and versioned-artifact publication have not been performed. Human
+publication remains required. An ordinary, unpersonalized download installs and
+runs normally without optional attribution. Renaming a personalized Windows or
+Linux download before its first install/launch can lose attribution.
+
+The signature-exempt xattr and ZIP extraction behavior are documented by
+[Apple Developer Technical Support](https://developer.apple.com/forums/thread/796303).
+There is no ZIP or user-supplied sidecar for Windows. NSIS saves the first valid
+grant beside the installed executable and updates never replace it. Linux reads
+only the original AppImage path supplied by `APPIMAGE`.
+
+Before enabling website carrier admission, verify actual production artifacts,
+app startup, restart, login/logout, trial/purchase, updater recovery, and provider
+readback. The macOS test uses an ad-hoc signed fixture; Windows NSIS tests exercise
+the real grant macro but mock installer signature/version metadata boundaries;
+Linux uses a synthetic AppImage header. These local tests do not prove the full
+production download or signing path.
diff --git a/scripts/package-attribution-carrier.py b/scripts/package-attribution-carrier.py
new file mode 100644
index 000000000..624c87b82
--- /dev/null
+++ b/scripts/package-attribution-carrier.py
@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+# screenpipe — AI that knows everything you've seen, said, or heard
+# https://screenpipe.com
+"""Prepare a versioned download carrier from a release artifact. Never uploads/publishes."""
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import plistlib
+import os
+import re
+import shutil
+import struct
+import subprocess
+import sys
+import tempfile
+import zipfile
+
+PLACEHOLDER = '00000000-0000-4000-8000-000000000000'
+
+
+def package(app, output, platform, release):
+ app, output = Path(app).resolve(), Path(output).resolve()
+ if app.suffix != '.app' or not re.fullmatch(r'\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?', release):
+ raise ValueError('signed .app and valid release required')
+ info = plistlib.loads((app / 'Contents/Info.plist').read_bytes())
+ if info.get('CFBundleShortVersionString') != release:
+ raise ValueError('release must match the app version')
+ executable = app / 'Contents/MacOS' / info['CFBundleExecutable']
+ expected_arch = {'macos-arm': 'arm64', 'macos-intel': 'x86_64'}[platform]
+ architectures = subprocess.check_output(['lipo', '-archs', str(executable)]).decode().split()
+ if not any(arch == expected_arch or (expected_arch == 'arm64' and arch == 'arm64e') for arch in architectures):
+ raise ValueError('platform does not match the signed executable')
+ subprocess.run(['codesign', '--verify', '--deep', '--strict', str(app)], check=True)
+ output.mkdir(parents=True, exist_ok=True)
+ archive = output / 'screenpipe-attribution.zip'
+ manifest = output / 'screenpipe-attribution.json'
+ if archive.exists() or manifest.exists():
+ raise ValueError('refusing to overwrite prepared artifacts')
+ with tempfile.TemporaryDirectory(prefix='screenpipe-carrier-') as tmp:
+ tmp = Path(tmp)
+ container = tmp / 'root'
+ container.mkdir()
+ copied = container / app.name
+ subprocess.run(['ditto', str(app), str(copied)], check=True)
+ subprocess.run(['xattr', '-w', 'com.apple.application-instance', PLACEHOLDER, str(copied)], check=True)
+ subprocess.run(['codesign', '--verify', '--deep', '--strict', str(copied)], check=True)
+ original = tmp / 'original.zip'
+ subprocess.run(['ditto', '-c', '-k', '--sequesterRsrc', str(container), str(original)], check=True)
+ member_name = '__MACOSX/._' + app.name
+ prepared = tmp / 'prepared.zip'
+ with zipfile.ZipFile(original) as src, zipfile.ZipFile(prepared, 'w', allowZip64=False) as dst:
+ for entry in src.infolist():
+ if entry.filename == member_name:
+ payload = src.read(entry)
+ if payload.count(PLACEHOLDER.encode()) != 1:
+ raise ValueError('ambiguous or absent xattr placeholder')
+ entry.compress_type = zipfile.ZIP_STORED
+ entry.extra = b''
+ entry.comment = b''
+ dst.writestr(entry, payload)
+ else:
+ with src.open(entry) as source, dst.open(entry, 'w') as target:
+ shutil.copyfileobj(source, target, 1024 * 1024)
+ with zipfile.ZipFile(prepared) as z:
+ entry = z.getinfo(member_name)
+ payload = z.read(entry)
+ central = z.start_dir
+ with prepared.open('rb') as f:
+ while True:
+ f.seek(central)
+ header = f.read(46)
+ if header[:4] != b'PK\x01\x02':
+ raise ValueError('missing carrier central entry')
+ namesize, extrasize, commentsize = struct.unpack_from('<HHH', header, 28)
+ name = f.read(namesize).decode('utf-8')
+ if name == member_name:
+ break
+ central += 46 + namesize + extrasize + commentsize
+ size = prepared.stat().st_size
+ if size > 2147483647:
+ raise ValueError('carrier exceeds the website streaming limit')
+ digest = hashlib.sha256()
+ with prepared.open('rb') as f:
+ for block in iter(lambda: f.read(1024 * 1024), b''):
+ digest.update(block)
+ result = dict(schema=1, platform=platform, release=release, size=size,
+ sha256=digest.hexdigest(), placeholder=PLACEHOLDER,
+ member=dict(name=member_name, data_offset=entry.header_offset+30+len(member_name.encode()),
+ data_length=len(payload), grant_offset=payload.index(PLACEHOLDER.encode()),
+ crc32=entry.CRC, local_crc_offset=entry.header_offset+14,
+ central_crc_offset=central+16))
+ # Check the actual archive extraction, including metadata and signature.
+ extracted = tmp / 'extracted'
+ subprocess.run(['ditto', '-x', '-k', str(prepared), str(extracted)], check=True)
+ extracted_app = extracted / app.name
+ received = subprocess.check_output(['xattr', '-p', 'com.apple.application-instance', str(extracted_app)]).decode().strip()
+ if received != PLACEHOLDER:
+ raise ValueError('archive lost the application instance attribute')
+ subprocess.run(['codesign', '--verify', '--deep', '--strict', str(extracted_app)], check=True)
+ shutil.copyfile(prepared, archive)
+ manifest.write_text(json.dumps(result, indent=2)+'\n')
+ return archive, manifest
+
+
+def package_filename(artifact, output, platform, release):
+ """Copy an immutable executable; only its delivered filename is personalized."""
+ artifact, output = Path(artifact).resolve(), Path(output).resolve()
+ if not re.fullmatch(r'\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?', release):
+ raise ValueError('valid release required')
+ if not re.search(r'(?:^|[_-])' + re.escape(release) + r'(?:[_-]|\.)', artifact.name):
+ raise ValueError('release must match the versioned artifact filename')
+ if platform not in ('linux', 'windows', 'windows-arm'):
+ raise ValueError('unsupported filename platform')
+ if platform == 'linux':
+ with artifact.open('rb') as source:
+ header = source.read(20)
+ if (artifact.suffix != '.AppImage' or header[:6] != b'\x7fELF\x02\x01' or
+ header[8:11] != b'AI\x02' or len(header) != 20 or struct.unpack_from('<H', header, 18)[0] != 62):
+ raise ValueError('Linux x86_64 type-2 AppImage required')
+ else:
+ if artifact.suffix.lower() != '.exe':
+ raise ValueError('Windows installer .exe required')
+ arch = (r'(?:^|[_-])(?:x64|x86_64|amd64)(?:[_-]|\.)' if platform == 'windows'
+ else r'(?:^|[_-])(?:arm64|aarch64)(?:[_-]|\.)')
+ if not re.search(arch, artifact.name, re.IGNORECASE):
+ raise ValueError('versioned release filename lacks target architecture evidence')
+ metadata = windows_metadata(artifact)
+ if metadata.get('Status') != 'Valid':
+ raise ValueError('installer must have a valid Authenticode signature')
+ versions = {str(metadata.get(key, '')).strip() for key in ('ProductVersion', 'FileVersion')}
+ if release not in versions:
+ raise ValueError('release must match Windows version metadata')
+ size = artifact.stat().st_size
+ if not 100 <= size <= 2147483647:
+ raise ValueError('carrier size outside streaming limit')
+ output.mkdir(parents=True, exist_ok=True)
+ target = output / ('screenpipe-attribution.exe' if platform.startswith('windows')
+ else 'screenpipe-attribution.AppImage')
+ manifest = output / 'screenpipe-attribution.json'
+ if target.exists() or manifest.exists():
+ raise ValueError('refusing to overwrite prepared artifacts')
+ digest = hashlib.sha256()
+ # Hash the exact bytes being copied, with exclusive creation.
+ with artifact.open('rb') as source, target.open('xb') as destination:
+ for block in iter(lambda: source.read(1024 * 1024), b''):
+ digest.update(block)
+ destination.write(block)
+ if target.stat().st_size != size:
+ target.unlink()
+ raise ValueError('artifact changed during copy')
+ target.chmod(artifact.stat().st_mode & 0o777)
+ with manifest.open('x') as destination:
+ json.dump(dict(schema=1, carrier='filename', platform=platform, release=release,
+ size=size, sha256=digest.hexdigest()), destination, indent=2)
+ destination.write('\n')
+ return target, manifest
+
+
+def windows_metadata(artifact):
+ """Read signature and version using Windows' supported PowerShell APIs."""
+ if sys.platform != 'win32':
+ raise ValueError('Windows packaging requires a Windows host')
+ script = ("$ErrorActionPreference='Stop';$p=$env:SCREENPIPE_ATTRIBUTION_ARTIFACT;"
+ "$s=Get-AuthenticodeSignature -LiteralPath $p;"
+ "$v=[Diagnostics.FileVersionInfo]::GetVersionInfo($p);"
+ "@{Status=[string]$s.Status;ProductVersion=$v.ProductVersion;"
+ "FileVersion=$v.FileVersion}|ConvertTo-Json -Compress")
+ output = subprocess.check_output([
+ 'powershell.exe', '-NoProfile', '-NonInteractive', '-Command', script
+ ], text=True, timeout=30, env={**os.environ, 'SCREENPIPE_ATTRIBUTION_ARTIFACT': str(artifact)})
+ return json.loads(output)
+
+
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser(description=__doc__)
+ inputs = parser.add_mutually_exclusive_group(required=True)
+ inputs.add_argument('--app')
+ inputs.add_argument('--artifact')
+ parser.add_argument('--output', required=True)
+ parser.add_argument('--platform', choices=['macos-arm', 'macos-intel', 'linux', 'windows', 'windows-arm'], required=True)
+ parser.add_argument('--release', required=True)
+ args = parser.parse_args()
+ prepare = package if args.app else package_filename
+ for artifact in prepare(args.app or args.artifact, args.output, args.platform, args.release):
+ print(artifact)
diff --git a/scripts/test_attribution_carrier.py b/scripts/test_attribution_carrier.py
new file mode 100644
index 000000000..7f9035790
--- /dev/null
+++ b/scripts/test_attribution_carrier.py
@@ -0,0 +1,155 @@
+# screenpipe — AI that knows everything you've seen, said, or heard
+# https://screenpipe.com
+"""Local attribution-carrier packaging regressions; never publish artifacts."""
+import importlib.util
+import hashlib
+import json
+import sys
+from pathlib import Path
+import plistlib
+import shutil
+import subprocess
+import tempfile
+import unittest
+from unittest import mock
+
+spec = importlib.util.spec_from_file_location('carrier', Path(__file__).with_name('package-attribution-carrier.py'))
+carrier = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(carrier)
+
+
+class CarrierTest(unittest.TestCase):
+ @unittest.skipUnless(sys.platform == "darwin", "requires macOS signing tools")
+ def test_signed_archive_metadata_and_overwrite_boundaries(self):
+ with tempfile.TemporaryDirectory(prefix='screenpipe-carrier-test-') as tmp:
+ root = Path(tmp)
+ app = root / 'Fixture.app'
+ executable = app / 'Contents/MacOS/Fixture'
+ executable.parent.mkdir(parents=True)
+ shutil.copyfile('/bin/echo', executable)
+ executable.chmod(0o755)
+ (app / 'Contents/Info.plist').write_bytes(plistlib.dumps(dict(
+ CFBundleIdentifier='com.screenpipe.carrier-fixture', CFBundleExecutable='Fixture',
+ CFBundleName='Fixture', CFBundlePackageType='APPL', CFBundleShortVersionString='0.3.100')))
+ subprocess.run(['codesign', '--force', '--sign', '-', str(app)], check=True)
+ architectures = subprocess.check_output(['lipo', '-archs', str(executable)]).decode()
+ platform = 'macos-arm' if 'arm64' in architectures else 'macos-intel'
+ output = root / 'output'
+ archive, manifest = carrier.package(app, output, platform, '0.3.100')
+ self.assertTrue(archive.is_file())
+ self.assertTrue(manifest.is_file())
+ # Packaging already verifies extraction, xattr preservation and the
+ # actual extracted signature. Also prove it never mutates the input.
+ attrs = subprocess.check_output(['xattr', str(app)]).decode()
+ self.assertNotIn('com.apple.application-instance', attrs)
+ with self.assertRaisesRegex(ValueError, 'overwrite'):
+ carrier.package(app, output, platform, '0.3.100')
+ with self.assertRaisesRegex(ValueError, 'version'):
+ carrier.package(app, root / 'wrong-version', platform, '0.3.101')
+
+ def test_appimage_bytes_unchanged_and_metadata_bounded(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ root = Path(tmp)
+ artifact = root / 'screenpipe_1.2.3_amd64.AppImage'
+ content = bytearray(1024)
+ content[:6] = b'\x7fELF\x02\x01'
+ content[8:11] = b'AI\x02'
+ content[18] = 62
+ artifact.write_bytes(content)
+ artifact.chmod(0o755)
+ prepared, manifest = carrier.package_filename(artifact, root / 'out', 'linux', '1.2.3')
+ self.assertEqual(prepared.read_bytes(), content)
+ self.assertEqual(artifact.read_bytes(), content)
+ data = json.loads(manifest.read_text())
+ self.assertEqual(data['sha256'], hashlib.sha256(content).hexdigest())
+ self.assertEqual(data['carrier'], 'filename')
+ with self.assertRaisesRegex(ValueError, 'overwrite'):
+ carrier.package_filename(artifact, root / 'out', 'linux', '1.2.3')
+ with self.assertRaisesRegex(ValueError, 'version'):
+ carrier.package_filename(artifact, root / 'bad-version', 'linux', '1.2.4')
+ content[18] = 183
+ artifact.write_bytes(content)
+ with self.assertRaisesRegex(ValueError, 'x86_64'):
+ carrier.package_filename(artifact, root / 'bad-arch', 'linux', '1.2.3')
+
+ def test_windows_bytes_metadata_architecture_and_overwrite_boundaries(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ root = Path(tmp)
+ content = b'MZ' + bytes(1022)
+ for platform, arch in [('windows', 'x64'), ('windows-arm', 'arm64')]:
+ artifact = root / f'screenpipe_1.2.3_{arch}-setup.exe'
+ artifact.write_bytes(content)
+ output = root / platform
+ metadata = dict(Status='Valid', ProductVersion='1.2.3', FileVersion='1.2.3')
+ with mock.patch.object(carrier, 'windows_metadata', return_value=metadata):
+ prepared, manifest = carrier.package_filename(artifact, output, platform, '1.2.3')
+ self.assertEqual(prepared.name, 'screenpipe-attribution.exe')
+ self.assertEqual(prepared.read_bytes(), content)
+ data = json.loads(manifest.read_text())
+ self.assertEqual(data['sha256'], hashlib.sha256(content).hexdigest())
+ self.assertEqual(data['carrier'], 'filename')
+ with self.assertRaisesRegex(ValueError, 'overwrite'):
+ carrier.package_filename(artifact, output, platform, '1.2.3')
+ wrong_arch = root / f'screenpipe_1.2.3_{"arm64" if arch == "x64" else "x64"}-setup.exe'
+ wrong_arch.write_bytes(content)
+ with self.assertRaisesRegex(ValueError, 'architecture'):
+ carrier.package_filename(wrong_arch, root / f'bad-{platform}', platform, '1.2.3')
+ with mock.patch.object(carrier, 'windows_metadata', return_value={**metadata, 'Status': 'NotSigned'}):
+ with self.assertRaisesRegex(ValueError, 'Authenticode'):
+ carrier.package_filename(artifact, root / f'unsigned-{platform}', platform, '1.2.3')
+ with mock.patch.object(carrier, 'windows_metadata', return_value={**metadata, 'ProductVersion': '1.2.4', 'FileVersion': '1.2.4'}):
+ with self.assertRaisesRegex(ValueError, 'version metadata'):
+ carrier.package_filename(artifact, root / f'version-{platform}', platform, '1.2.3')
+
+ @unittest.skipUnless(sys.platform == 'win32', 'requires Windows NSIS')
+ def test_actual_nsis_filename_grant_fixture(self):
+ makensis = shutil.which('makensis') or shutil.which('makensis.exe')
+ self.assertIsNotNone(makensis, 'makensis is required for the Windows fixture')
+ hooks = (Path(__file__).parents[1] / 'apps/screenpipe-app-tauri/src-tauri/windows/hooks.nsh').resolve()
+ with tempfile.TemporaryDirectory(prefix='screenpipe-nsis-attribution-') as tmp:
+ root = Path(tmp)
+ fixture = root / 'fixture.nsi'
+ fixture.write_text(
+ '; screenpipe — AI that knows everything you\'ve seen, said, or heard\n'
+ '; https://screenpipe.com\n'
+ 'Unicode true\nSilentInstall silent\nRequestExecutionLevel user\n'
+ f'!include "{hooks}"\n'
+ 'Name "Screenpipe attribution fixture"\nOutFile "fixture.exe"\nInstallDir "$TEMP\\screenpipe-attribution-fixture"\n'
+ 'Section\nCreateDirectory "$INSTDIR"\nFileOpen $0 "$INSTDIR\\installed" w\nFileWrite $0 "ok"\nFileClose $0\n'
+ '!insertmacro _SP_SaveAcquisitionGrant\nSectionEnd\n',
+ encoding='utf-8')
+ subprocess.run([makensis, '/V2', str(fixture)], cwd=root, check=True)
+
+ # Exercise the real PowerShell adapter, including a path whose
+ # spaces and metacharacters must remain data, never command text.
+ metadata_fixture = root / 'fixture $ [attribution].exe'
+ shutil.copyfile(root / 'fixture.exe', metadata_fixture)
+ self.assertEqual(carrier.windows_metadata(metadata_fixture)['Status'], 'NotSigned')
+
+ first = '12345678-1234-4234-8234-123456789012'
+ second = 'abcdefab-cdef-4abc-9def-abcdefabcdef'
+
+ def install(filename, directory):
+ installer = root / filename
+ shutil.copyfile(root / 'fixture.exe', installer)
+ subprocess.run([str(installer), '/S', f'/D={directory}'], check=True)
+ self.assertEqual((directory / 'installed').read_text(), 'ok')
+
+ valid_dir = root / 'valid'
+ install(f'screenpipe-{first}.exe', valid_dir)
+ self.assertEqual((valid_dir / 'acquisition-grant').read_text(), first)
+ install(f'screenpipe-{second}.exe', valid_dir)
+ self.assertEqual((valid_dir / 'acquisition-grant').read_text(), first)
+ for index, name in enumerate([
+ f'screenpipe-{carrier.PLACEHOLDER}.exe',
+ 'screenpipe-12345678-1234-4234-7234-123456789012.exe',
+ 'screenpipe-12345678-1234-4234-C234-123456789012.exe',
+ 'screenpipe.exe',
+ ]):
+ directory = root / f'invalid-{index}'
+ install(name, directory)
+ self.assertFalse((directory / 'acquisition-grant').exists())
+
+
+if __name__ == '__main__':
+ unittest.main()