waybetter/crates/waybetter-host/src/backup.rs
CRT 8ff27a629f host: settings backup envelope and encrypted folder sync
backup: the versioned .waybetter envelope (format/version checks, only the
app's registered sections kept), secret-key scrubbing, the plugins /
customCss / accounts sections every app has, plugin import checks and
atomic writes. sync: Argon2id + XChaCha20-Poly1305 snapshots of the
settings backup in a folder the owner syncs, moved unchanged from the
wayBetter for X app with its tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 10:58:15 +07:00

290 lines
14 KiB
Rust

//! Settings backup: the versioned `.waybetter` JSON envelope, its import-side checks and the
//! sections every wayBetter app has (plugins, custom CSS, the account list). The app registers the
//! rest: which sections exist ([`parse_backup`] keeps only those) and how its own files map to
//! them. Pure (an app-data directory in, JSON out), unit-tested headless.
//!
//! Never included by these helpers: WebView profile folders (cookies, site sessions, local
//! storage), signing or sync keys, update state. [`strip_secrets`] removes secret-looking keys
//! from whatever is exported or imported as a second line of defence.
use crate::plugins::{valid_file_name, MAX_PLUGIN_BYTES};
use crate::profiles::{DEFAULT_COLOR, DEFAULT_PROFILE};
use serde::{Deserialize, Serialize};
use serde_json::{json, Map, Value};
use std::fs;
use std::path::Path;
pub const FORMAT: &str = "waybetter-backup";
pub const VERSION: u32 = 1;
pub const EXTENSION: &str = "waybetter";
/// Largest backup file accepted for import.
pub const MAX_BACKUP_BYTES: usize = 32 * 1024 * 1024;
pub const MAX_PLUGIN_FILES: usize = 64;
/// Largest JSON settings file a backup reads.
pub const MAX_JSON_FILE: usize = 8 * 1024 * 1024;
/// Keys that never leave (or enter) the app through a backup, compared case-insensitively with
/// `_`/`-` removed.
const SECRET_KEYS: [&str; 22] = [
"cookie", "cookies", "setcookie", "token", "tokens", "accesstoken", "authtoken", "refreshtoken", "idtoken", "ct0", "password",
"passphrase", "secret", "clientsecret", "session", "sessionid", "authorization", "bearer", "csrf", "csrftoken", "privatekey",
"signingkey",
];
fn secret_key(key: &str) -> bool {
let folded: String = key.chars().filter(|ch| *ch != '_' && *ch != '-').flat_map(char::to_lowercase).collect();
SECRET_KEYS.contains(&folded.as_str()) || folded.ends_with("secret") || folded.ends_with("token") || folded.ends_with("password")
}
/// Removes secret-looking keys anywhere in `value`; returns their JSON paths.
pub fn strip_secrets(value: &mut Value) -> Vec<String> {
fn walk(value: &mut Value, path: &str, removed: &mut Vec<String>) {
match value {
Value::Object(map) => {
let keys: Vec<String> = map.keys().cloned().collect();
for key in keys {
if secret_key(&key) {
map.remove(&key);
removed.push(format!("{path}.{key}"));
} else if let Some(child) = map.get_mut(&key) {
walk(child, &format!("{path}.{key}"), removed);
}
}
}
Value::Array(items) => {
for (index, item) in items.iter_mut().enumerate() {
walk(item, &format!("{path}[{index}]"), removed);
}
}
_ => {}
}
}
let mut removed = Vec::new();
walk(value, "$", &mut removed);
removed
}
/// A JSON settings file, if it exists, parses and is at most [`MAX_JSON_FILE`].
pub fn read_json_file(path: &Path) -> Option<Value> {
let raw = fs::read(path).ok()?;
if raw.len() > MAX_JSON_FILE {
return None;
}
serde_json::from_slice(&raw).ok()
}
/// A JSON object settings file, or `default` when it is missing, damaged or not an object.
pub fn object_section(path: &Path, default: Value) -> Value {
read_json_file(path).filter(Value::is_object).unwrap_or(default)
}
/// A plugin file of the owner's: `file` + `source`.
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct PluginFile {
pub file: String,
pub source: String,
}
/// The `plugins` section (enabled states + the owner's own plugin files) and the `customCss`
/// section, read from the plugin store folder. `shipped` are the plugin files the app writes
/// itself (bundled + example): untouched copies of those are left out.
pub fn plugin_sections(plugins_dir: &Path, shipped: &[(&str, &str)]) -> (Value, Value) {
let enabled: Vec<String> = read_json_file(&plugins_dir.join("enabled.json"))
.and_then(|value| serde_json::from_value::<Vec<String>>(value).ok())
.unwrap_or_default()
.into_iter()
.filter(|file| valid_file_name(file))
.collect();
let mut files: Vec<PluginFile> = Vec::new();
if let Ok(entries) = fs::read_dir(plugins_dir) {
let mut names: Vec<String> = entries.flatten().filter_map(|entry| entry.file_name().to_str().map(str::to_owned)).collect();
names.sort();
for file in names {
if !valid_file_name(&file) || files.len() >= MAX_PLUGIN_FILES {
continue;
}
let path = plugins_dir.join(&file);
let Ok(meta) = fs::metadata(&path) else { continue };
if !meta.is_file() || meta.len() > MAX_PLUGIN_BYTES {
continue;
}
let Ok(source) = fs::read_to_string(&path) else { continue };
if shipped.iter().any(|(name, content)| *name == file && *content == source) {
continue;
}
files.push(PluginFile { file, source });
}
}
let css = fs::read_to_string(plugins_dir.join("custom.css")).unwrap_or_default();
(json!({ "enabled": enabled, "files": files }), json!({ "css": css }))
}
/// The `accounts` section from the profiles file: profile ids, names and colors only. The site
/// account a profile is signed in to is observed by the tabs (never imported), and its login is
/// the WebView profile folder, which a backup never reads.
pub fn accounts_section(profiles_file: &Path) -> Value {
let profiles = read_json_file(profiles_file).unwrap_or(Value::Null);
let list: Vec<Value> = profiles
.get("profiles")
.and_then(Value::as_array)
.map(|items| {
items
.iter()
.filter_map(|profile| {
Some(json!({
"id": profile.get("id")?.as_str()?,
"name": profile.get("name").and_then(Value::as_str).unwrap_or(""),
"color": profile.get("color").and_then(Value::as_str).unwrap_or(DEFAULT_COLOR),
}))
})
.collect()
})
.unwrap_or_default();
let active = profiles.get("active").and_then(Value::as_str).unwrap_or(DEFAULT_PROFILE);
json!({ "profiles": list, "active": active })
}
/// Finishes collected sections: secret-looking keys removed anywhere.
pub fn scrubbed(sections: Map<String, Value>) -> Map<String, Value> {
let mut value = Value::Object(sections);
strip_secrets(&mut value);
match value {
Value::Object(map) => map,
_ => Map::new(),
}
}
/// Checks the envelope of a backup file and returns its sections (only the app's `sections`,
/// secret-looking keys removed).
pub fn parse_backup(bytes: &[u8], sections: &[&str]) -> Result<Map<String, Value>, String> {
if bytes.len() > MAX_BACKUP_BYTES {
return Err("BACKUP: the file is larger than 32 MB".into());
}
let mut value: Value = serde_json::from_slice(bytes).map_err(|error| format!("BACKUP: not a wayBetter backup (line {}: {error})", error.line()))?;
if value.get("format").and_then(Value::as_str) != Some(FORMAT) {
return Err("BACKUP: not a wayBetter backup".into());
}
let version = value.get("version").and_then(Value::as_u64).unwrap_or(0);
if version == 0 || version > u64::from(VERSION) {
return Err(format!("BACKUP: made by a newer wayBetter (backup version {version}); update the app first"));
}
strip_secrets(&mut value);
let found = value.get_mut("sections").and_then(Value::as_object_mut).ok_or("BACKUP: the backup has no sections")?;
found.retain(|key, _| sections.contains(&key.as_str()));
Ok(std::mem::take(found))
}
/// The plugins section of an import: file names checked, sizes capped, at most [`MAX_PLUGIN_FILES`].
pub fn plugins_section(value: &Value) -> Result<(Vec<String>, Vec<PluginFile>), String> {
let enabled: Vec<String> = serde_json::from_value(value.get("enabled").cloned().unwrap_or(json!([]))).map_err(|_| "BACKUP: invalid plugin list")?;
let files: Vec<PluginFile> = serde_json::from_value(value.get("files").cloned().unwrap_or(json!([]))).map_err(|_| "BACKUP: invalid plugin files")?;
if files.len() > MAX_PLUGIN_FILES || enabled.len() > 256 {
return Err("BACKUP: too many plugins".into());
}
for name in enabled.iter().chain(files.iter().map(|file| &file.file)) {
if !valid_file_name(name) {
return Err("BACKUP: invalid plugin file name".into());
}
}
if files.iter().any(|file| file.source.len() as u64 > MAX_PLUGIN_BYTES) {
return Err("BACKUP: a plugin file is larger than 2 MiB".into());
}
Ok((enabled, files))
}
/// Writes a file next to its final name and renames it over (a running tab never reads half).
pub fn write_atomic(path: &Path, bytes: &[u8]) -> Result<(), String> {
let temp = path.with_extension("importing");
fs::write(&temp, bytes).map_err(|error| format!("BACKUP: {error}"))?;
fs::rename(&temp, path).map_err(|error| {
let _ = fs::remove_file(&temp);
format!("BACKUP: {error}")
})
}
#[cfg(test)]
mod tests {
use super::*;
const SECTIONS: [&str; 3] = ["plugins", "customCss", "settings"];
fn write(dir: &Path, name: &str, text: &str) {
let path = dir.join(name);
fs::create_dir_all(path.parent().unwrap()).unwrap();
fs::write(path, text).unwrap();
}
#[test]
fn secret_keys_are_stripped_anywhere() {
let mut value = json!({ "a": { "Auth-Token": "t", "list": [{ "password": "p", "keep": 1 }] }, "sessionId": "s", "ok": true });
let removed = strip_secrets(&mut value);
assert_eq!(value, json!({ "a": { "list": [{ "keep": 1 }] }, "ok": true }));
assert_eq!(removed.len(), 3);
for key in ["clientSecret", "api_token", "refresh-token", "Bearer", "ct0", "signingKey", "PASSPHRASE"] {
assert!(secret_key(key), "{key}");
}
assert!(!secret_key("tokenizer") && !secret_key("homeUrl"));
}
#[test]
fn plugins_css_and_accounts_sections() {
let root = tempfile::tempdir().unwrap();
let dir = root.path();
write(dir, "plugins/enabled.json", r#"["mine.plugin.js","../bad.plugin.js"]"#);
write(dir, "plugins/mine.plugin.js", "mine");
write(dir, "plugins/shipped.plugin.js", "as shipped");
write(dir, "plugins/notes.txt", "not a plugin");
write(dir, "plugins/custom.css", "a{}");
write(dir, "profiles.json", r##"{"profiles":[{"id":"default","name":"Main","account":{"handle":"h"}},{"id":"w","color":"#000000","authToken":"t"}]}"##);
let (plugins, css) = plugin_sections(&dir.join("plugins"), &[("shipped.plugin.js", "as shipped")]);
assert_eq!(plugins, json!({ "enabled": ["mine.plugin.js"], "files": [{ "file": "mine.plugin.js", "source": "mine" }] }));
assert_eq!(css, json!({ "css": "a{}" }));
assert_eq!(
accounts_section(&dir.join("profiles.json")),
json!({ "profiles": [{ "id": "default", "name": "Main", "color": DEFAULT_COLOR }, { "id": "w", "name": "", "color": "#000000" }], "active": "default" })
);
assert_eq!(object_section(&dir.join("missing.json"), json!({})), json!({}));
assert_eq!(object_section(&dir.join("plugins/enabled.json"), json!({ "d": 1 })), json!({ "d": 1 }), "not an object");
}
#[test]
fn envelope_keeps_only_the_apps_sections_and_no_secret() {
assert!(parse_backup(b"not json", &SECTIONS).unwrap_err().contains("line 1"));
assert!(parse_backup(br#"{"format":"other","version":1,"sections":{}}"#, &SECTIONS).is_err());
assert!(parse_backup(br#"{"format":"waybetter-backup","version":0,"sections":{}}"#, &SECTIONS).is_err());
assert!(parse_backup(br#"{"format":"waybetter-backup","version":99,"sections":{}}"#, &SECTIONS).unwrap_err().contains("newer"));
assert!(parse_backup(br#"{"format":"waybetter-backup","version":1}"#, &SECTIONS).unwrap_err().contains("no sections"));
assert!(parse_backup(&vec![b' '; MAX_BACKUP_BYTES + 1], &SECTIONS).unwrap_err().contains("32 MB"));
let file = json!({ "format": FORMAT, "version": VERSION, "sections": {
"settings": { "homeUrl": "https://example.com/", "token": "t" }, "other": {}
} });
let parsed = parse_backup(&serde_json::to_vec(&file).unwrap(), &SECTIONS).unwrap();
assert_eq!(Value::Object(parsed), json!({ "settings": { "homeUrl": "https://example.com/" } }));
let collected = scrubbed(json!({ "settings": { "password": "p", "a": 1 } }).as_object().unwrap().clone());
assert_eq!(Value::Object(collected), json!({ "settings": { "a": 1 } }));
}
#[test]
fn plugin_imports_are_checked() {
assert!(plugins_section(&json!({ "files": [{ "file": "../evil.plugin.js", "source": "" }] })).is_err());
assert!(plugins_section(&json!({ "enabled": ["C:\\x.plugin.js"] })).is_err());
assert!(plugins_section(&json!({ "files": [{ "file": "a.plugin.js", "source": "", "extra": 1 }] })).is_err());
let big = "a".repeat(MAX_PLUGIN_BYTES as usize + 1);
assert!(plugins_section(&json!({ "files": [{ "file": "a.plugin.js", "source": big }] })).is_err());
let many: Vec<Value> = (0..=MAX_PLUGIN_FILES).map(|n| json!({ "file": format!("p{n}.plugin.js"), "source": "" })).collect();
assert!(plugins_section(&json!({ "files": many })).is_err());
let (enabled, files) = plugins_section(&json!({ "enabled": ["a.plugin.js"], "files": [{ "file": "a.plugin.js", "source": "x" }] })).unwrap();
assert_eq!((enabled.len(), files.len()), (1, 1));
}
#[test]
fn atomic_write_replaces_the_file() {
let root = tempfile::tempdir().unwrap();
let path = root.path().join("settings.json");
fs::write(&path, "old").unwrap();
write_atomic(&path, b"new").unwrap();
assert_eq!(fs::read_to_string(&path).unwrap(), "new");
assert!(!root.path().join("settings.importing").exists());
}
}