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

fix(api-auth): stabilize unreadable secret recovery (#6653)

Ezra Elletteac16c2574690
diff --git a/crates/screenpipe-engine/src/auth_key.rs b/crates/screenpipe-engine/src/auth_key.rs
index b6982c613..cd01e8391 100644
--- a/crates/screenpipe-engine/src/auth_key.rs
+++ b/crates/screenpipe-engine/src/auth_key.rs
@@ -12,47 +12,64 @@
//! `db.sqlite` and breaking every cross-process reader with HTTP 403.
use anyhow::Result;
+use std::io::Write;
use std::path::{Path, PathBuf};
+const API_AUTH_RECOVERY_FILENAME: &str = "api-auth-recovery.json";
+
/// Resolve the API auth key. Priority:
///
/// 1. `SCREENPIPE_API_KEY` env var
/// 2. `settings_key` (non-empty)
/// 3. plaintext `api_auth_key` in the `db.sqlite` secret store
/// 4. legacy `~/.screenpipe/auth.json`
-/// 5. auto-generated `sp-<uuid8>`, persisted to the secret store before return
+/// 5. owner-only recovery file (only present after an encrypted row was unreadable)
+/// 6. auto-generated `sp-<uuid8>`, persisted to the secret store before return
pub async fn resolve_api_auth_key(data_dir: &Path, settings_key: Option<&str>) -> Result<String> {
let store = open_secret_store(data_dir).await.ok();
+ let env_key = std::env::var("SCREENPIPE_API_KEY")
+ .ok()
+ .filter(|key| !key.is_empty());
+ let legacy_key = read_legacy_auth_json();
+ resolve_api_auth_key_with_sources(data_dir, settings_key, env_key, legacy_key, store).await
+}
+async fn resolve_api_auth_key_with_sources(
+ data_dir: &Path,
+ settings_key: Option<&str>,
+ env_key: Option<String>,
+ legacy_key: Option<String>,
+ store: Option<screenpipe_secrets::SecretStore>,
+) -> Result<String> {
// Read the existing secret-store value once — used both as a fallback
// source and to avoid a no-op write when nothing has changed.
//
- // CRITICAL: distinguish "no row" from "row exists but unreadable". If
- // `get()` errors (decrypt failure, IO error), we MUST log loudly — the
- // chain below will fall through to "auto-generate" and silently rotate
- // the user's API key, breaking every consumer that cached the prior
- // value (webview, MCP, CLI). Concrete trigger: built-from-source dev
+ // CRITICAL: distinguish "no row" from "row exists but unreadable". A
+ // decrypt failure must preserve the authoritative encrypted blob and use
+ // one stable owner-only recovery key; a fresh key per process breaks every
+ // consumer that cached the prior value (webview, MCP, CLI). Concrete
+ // trigger: built-from-source dev
// build wrote an encrypted `api_auth_key` whose keychain ACL is scoped
// to the dev bundle id; user later switches to the prod build, which
// can read the secrets table but the keychain ACL denies the decrypt
// for `screenpi.pe`. Result: rotation, mismatched in-memory caches,
// 401 storms — observed for [email protected] 2026-05-06.
let mut stored_unreadable = false;
+ let mut stored_error = None;
let stored_key: Option<String> = if let Some(ref s) = store {
match s.get("api_auth_key").await {
- Ok(Some(bytes)) => String::from_utf8(bytes).ok().filter(|k| !k.is_empty()),
+ Ok(Some(bytes)) => match String::from_utf8(bytes).ok().filter(|key| !key.is_empty()) {
+ Some(key) => Some(key),
+ None => {
+ stored_unreadable = true;
+ stored_error = Some("stored api_auth_key is not valid non-empty UTF-8".into());
+ None
+ }
+ },
Ok(None) => None,
Err(e) => {
stored_unreadable = true;
- tracing::error!(
- "api auth: failed to read api_auth_key from secret store — \
- keeping the encrypted blob intact and minting a one-shot \
- ephemeral key for this process to avoid overwriting the \
- user's persisted key. Likely cause: keychain ACL mismatch \
- (dev↔prod bundle id, recent encryption toggle, or revoked \
- keychain item). Error: {}",
- e
- );
+ stored_error = Some(e.to_string());
None
}
}
@@ -60,15 +77,39 @@ pub async fn resolve_api_auth_key(data_dir: &Path, settings_key: Option<&str>) -
None
};
- let (key, source) = if let Ok(k) = std::env::var("SCREENPIPE_API_KEY") {
- if !k.is_empty() {
- (k, "SCREENPIPE_API_KEY env")
- } else {
- resolve_without_env(settings_key, &stored_key)
- }
+ let recovery_key = read_api_auth_recovery(data_dir);
+ let (mut key, mut source) = if let Some(key) = env_key {
+ (key, "SCREENPIPE_API_KEY env")
} else {
- resolve_without_env(settings_key, &stored_key)
+ resolve_without_env(settings_key, &stored_key, legacy_key, recovery_key)
};
+
+ if stored_unreadable && source == "auto-generated" {
+ match get_or_create_api_auth_recovery(data_dir, &key) {
+ Ok(stable_key) => {
+ key = stable_key;
+ source = "owner-only recovery file";
+ }
+ Err(error) => {
+ tracing::error!(
+ "api auth: encrypted api_auth_key is unreadable and a stable recovery key \
+ could not be persisted; keeping the encrypted blob intact and using a \
+ one-shot key for this process. Secret-store error: {}; recovery error: {}",
+ stored_error.as_deref().unwrap_or("unknown"),
+ error
+ );
+ }
+ }
+ }
+
+ if stored_unreadable && source != "auto-generated" {
+ tracing::warn!(
+ "api auth: encrypted api_auth_key is unreadable; keeping its blob intact and using \
+ {} so all processes retain a stable key. Secret-store error: {}",
+ source,
+ stored_error.as_deref().unwrap_or("unknown")
+ );
+ }
tracing::info!("api auth: key resolved via {}", source);
// Mirror the resolved key to the secret store so every cross-process
@@ -79,9 +120,9 @@ pub async fn resolve_api_auth_key(data_dir: &Path, settings_key: Option<&str>) -
// SAFETY: never persist when the existing row was unreadable. Writing
// would clobber the encrypted blob with a fresh plaintext key, silently
// rotating the user's API key (SCREENPIPE-APP-9Z: 25 events / 18 users,
- // including the Pattern.com whitelabel build). The in-memory key still
- // works for this process; the user can recover by clearing the secrets
- // table or restoring the keychain item.
+ // including the Pattern.com whitelabel build). The owner-only recovery
+ // file keeps sibling processes consistent without modifying that row; if
+ // Keychain access returns later, the original persisted key wins again.
if let Some(s) = store {
if !stored_unreadable && stored_key.as_deref() != Some(key.as_str()) {
if let Err(e) = s.set("api_auth_key", key.as_bytes()).await {
@@ -95,6 +136,8 @@ pub async fn resolve_api_auth_key(data_dir: &Path, settings_key: Option<&str>) -
fn resolve_without_env(
settings_key: Option<&str>,
stored_key: &Option<String>,
+ legacy_key: Option<String>,
+ recovery_key: Option<String>,
) -> (String, &'static str) {
if let Some(k) = settings_key.filter(|s| !s.is_empty()) {
return (k.to_string(), "settings");
@@ -102,13 +145,74 @@ fn resolve_without_env(
if let Some(k) = stored_key.as_ref() {
return (k.clone(), "secret store");
}
- if let Some(k) = read_legacy_auth_json() {
+ if let Some(k) = legacy_key {
return (k, "legacy auth.json");
}
+ if let Some(k) = recovery_key {
+ return (k, "owner-only recovery file");
+ }
let k = format!("sp-{}", &uuid::Uuid::new_v4().simple().to_string()[..8]);
(k, "auto-generated")
}
+fn api_auth_recovery_path(data_dir: &Path) -> PathBuf {
+ data_dir.join(API_AUTH_RECOVERY_FILENAME)
+}
+
+fn read_api_auth_recovery(data_dir: &Path) -> Option<String> {
+ let content = std::fs::read_to_string(api_auth_recovery_path(data_dir)).ok()?;
+ let json: serde_json::Value = serde_json::from_str(&content).ok()?;
+ json["token"]
+ .as_str()
+ .filter(|token| !token.is_empty())
+ .map(str::to_string)
+}
+
+fn get_or_create_api_auth_recovery(data_dir: &Path, candidate: &str) -> Result<String> {
+ if let Some(existing) = read_api_auth_recovery(data_dir) {
+ return Ok(existing);
+ }
+
+ std::fs::create_dir_all(data_dir)?;
+ let path = api_auth_recovery_path(data_dir);
+ let mut options = std::fs::OpenOptions::new();
+ options.write(true).create_new(true);
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::OpenOptionsExt;
+ options.mode(0o600);
+ }
+
+ match options.open(&path) {
+ Ok(mut file) => {
+ let payload = serde_json::to_vec(&serde_json::json!({ "token": candidate }))?;
+ if let Err(error) = file
+ .write_all(&payload)
+ .and_then(|_| file.write_all(b"\n"))
+ .and_then(|_| file.sync_all())
+ {
+ drop(file);
+ let _ = std::fs::remove_file(&path);
+ return Err(error.into());
+ }
+ Ok(candidate.to_string())
+ }
+ Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {
+ read_api_auth_recovery(data_dir).ok_or_else(|| {
+ anyhow::anyhow!(
+ "{} already exists but does not contain a valid token",
+ path.display()
+ )
+ })
+ }
+ Err(error) => Err(error.into()),
+ }
+}
+
+fn remove_api_auth_recovery(data_dir: &Path) {
+ let _ = std::fs::remove_file(api_auth_recovery_path(data_dir));
+}
+
/// Persist a user-supplied key to the secret store, replacing whatever was
/// there before. The running server keeps its in-memory key until restart.
pub async fn set_api_auth_key(data_dir: &Path, key: &str) -> Result<()> {
@@ -120,6 +224,7 @@ pub async fn set_api_auth_key(data_dir: &Path, key: &str) -> Result<()> {
.set("api_auth_key", key.as_bytes())
.await
.map_err(|e| anyhow::anyhow!("failed to persist api auth key: {e}"))?;
+ remove_api_auth_recovery(data_dir);
if let Some(legacy) = legacy_auth_json_path() {
let _ = std::fs::remove_file(legacy);
}
@@ -141,6 +246,7 @@ pub async fn regenerate_api_auth_key(data_dir: &Path) -> Result<String> {
} else {
anyhow::bail!("could not open secret store to persist regenerated key");
}
+ remove_api_auth_recovery(data_dir);
// Best-effort cleanup of legacy file so it doesn't shadow the new key.
if let Some(legacy) = legacy_auth_json_path() {
let _ = std::fs::remove_file(legacy);
@@ -198,7 +304,7 @@ fn read_legacy_auth_json() -> Option<String> {
}
/// Read-only counterpart to `resolve_api_auth_key`. Same priority chain
-/// (env → encrypted SecretStore → legacy file) but does NOT auto-generate
+/// (env → encrypted SecretStore → legacy file → recovery file) but does NOT auto-generate
/// or persist anything when no key is found — returns `None` instead.
///
/// Use this from CLI callers that need to *find* the running server's key,
@@ -235,7 +341,85 @@ pub async fn find_api_auth_key() -> Option<String> {
}
}
- read_legacy_auth_json()
+ read_legacy_auth_json().or_else(|| read_api_auth_recovery(&data_dir))
+}
+
+#[cfg(test)]
+mod local_api_auth_tests {
+ use super::*;
+
+ #[tokio::test]
+ async fn unreadable_encrypted_row_gets_stable_recovery_without_being_overwritten() {
+ let dir = tempfile::tempdir().unwrap();
+ let encryption_key = [7u8; 32];
+
+ let encrypted =
+ screenpipe_secrets::SecretStore::open_for_data_dir(dir.path(), Some(encryption_key))
+ .await
+ .unwrap();
+ encrypted.set("api_auth_key", b"sp-original").await.unwrap();
+ drop(encrypted);
+ screenpipe_secrets::close_all_secret_pools().await;
+
+ let unreadable = screenpipe_secrets::SecretStore::open_for_data_dir(dir.path(), None)
+ .await
+ .unwrap();
+ let first =
+ resolve_api_auth_key_with_sources(dir.path(), None, None, None, Some(unreadable))
+ .await
+ .unwrap();
+ assert!(first.starts_with("sp-"));
+ assert_ne!(first, "sp-original");
+ assert_eq!(
+ read_api_auth_recovery(dir.path()).as_deref(),
+ Some(first.as_str())
+ );
+
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::PermissionsExt;
+ let mode = std::fs::metadata(api_auth_recovery_path(dir.path()))
+ .unwrap()
+ .permissions()
+ .mode()
+ & 0o777;
+ assert_eq!(mode, 0o600);
+ }
+
+ screenpipe_secrets::close_all_secret_pools().await;
+ let unreadable_again = screenpipe_secrets::SecretStore::open_for_data_dir(dir.path(), None)
+ .await
+ .unwrap();
+ let second =
+ resolve_api_auth_key_with_sources(dir.path(), None, None, None, Some(unreadable_again))
+ .await
+ .unwrap();
+ assert_eq!(second, first);
+
+ screenpipe_secrets::close_all_secret_pools().await;
+ let recovered =
+ screenpipe_secrets::SecretStore::open_for_data_dir(dir.path(), Some(encryption_key))
+ .await
+ .unwrap();
+ assert_eq!(
+ recovered.get("api_auth_key").await.unwrap().as_deref(),
+ Some(&b"sp-original"[..])
+ );
+ screenpipe_secrets::close_all_secret_pools().await;
+ }
+
+ #[test]
+ fn invalid_recovery_file_is_preserved() {
+ let dir = tempfile::tempdir().unwrap();
+ let path = api_auth_recovery_path(dir.path());
+ std::fs::write(&path, b"user-owned invalid contents").unwrap();
+
+ assert!(get_or_create_api_auth_recovery(dir.path(), "sp-candidate").is_err());
+ assert_eq!(
+ std::fs::read(&path).unwrap(),
+ b"user-owned invalid contents"
+ );
+ }
}
// ---------------------------------------------------------------------------
diff --git a/crates/screenpipe-secrets/src/keychain.rs b/crates/screenpipe-secrets/src/keychain.rs
index f8983c859..f6d37b729 100644
--- a/crates/screenpipe-secrets/src/keychain.rs
+++ b/crates/screenpipe-secrets/src/keychain.rs
@@ -177,6 +177,12 @@ pub fn get_or_create_key() -> Option<[u8; 32]> {
let b64 = B64.encode(key);
if !set_password_in_keychain(&b64) {
+ // Another Screenpipe process may have won the create-only race.
+ // Re-read its key instead of replacing it: overwriting a key that has
+ // already encrypted a row would make that persisted secret unrecoverable.
+ if let KeyResult::Found(existing) = get_key() {
+ return Some(existing);
+ }
warn!("keychain: failed to store encryption key");
set_cached_key(None);
return None;
@@ -251,15 +257,9 @@ fn get_password_from_keychain() -> KeychainLookup {
}
#[cfg(target_os = "macos")]
-fn set_password_in_keychain(password: &str) -> bool {
- // Delete existing entry first (add-generic-password fails if it exists)
- let _ = std::process::Command::new("security")
- .args(["delete-generic-password", "-s", SERVICE, "-a", KEY_NAME])
- .stdout(std::process::Stdio::null())
- .stderr(std::process::Stdio::null())
- .status();
-
- let status = std::process::Command::new("security")
+fn macos_add_password_command(password: &str) -> std::process::Command {
+ let mut command = std::process::Command::new("security");
+ command
.args([
"add-generic-password",
"-s",
@@ -268,12 +268,23 @@ fn set_password_in_keychain(password: &str) -> bool {
KEY_NAME,
"-w",
password,
+ // Every macOS reader goes through this stable system executable.
+ // `security` explicitly documents `-T ""` as removing the
+ // creator's default access; that old spelling made the key usable
+ // only from the process cache and unreadable after restart.
"-T",
- "", // allow access from any application (no per-app ACL)
+ "/usr/bin/security",
])
.stdout(std::process::Stdio::null())
- .stderr(std::process::Stdio::null())
- .status();
+ .stderr(std::process::Stdio::null());
+ command
+}
+
+#[cfg(target_os = "macos")]
+fn set_password_in_keychain(password: &str) -> bool {
+ // Create only. Never delete or update an existing encryption key: another
+ // process may already have used it to seal persisted secrets.
+ let status = macos_add_password_command(password).status();
match status {
Ok(s) => s.success(),
@@ -305,3 +316,25 @@ fn set_password_in_keychain(password: &str) -> bool {
};
entry.set_password(password).is_ok()
}
+
+#[cfg(all(test, target_os = "macos"))]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn new_key_trusts_security_cli_without_opening_access_to_every_app() {
+ let command = macos_add_password_command("test-key");
+ let args: Vec<_> = command
+ .get_args()
+ .map(|arg| arg.to_string_lossy().into_owned())
+ .collect();
+
+ assert!(args
+ .windows(2)
+ .any(|pair| pair == ["-T", "/usr/bin/security"]));
+ assert!(!args.windows(2).any(|pair| pair == ["-T", ""]));
+ assert!(!args.iter().any(|arg| arg == "-A"));
+ assert!(!args.iter().any(|arg| arg == "-U"));
+ assert!(!args.iter().any(|arg| arg == "delete-generic-password"));
+ }
+}