Skip to main content

taskfast_agent/
keystore.rs

1// SPDX-License-Identifier: MIT
2//! Encrypted wallet persistence.
3//!
4//! Default: Web3 Secret Storage v3 JSON (Foundry/Geth/MetaMask-interoperable),
5//! resolved under `$XDG_DATA_HOME/taskfast/wallets/` so a wallet generated here
6//! can be imported by `cast wallet import` without conversion.
7//!
8//! This module owns two concerns and nothing else:
9//!
10//! 1. Path resolution — XDG-compliant directory layout with `0700` perms on
11//!    the containing dir and `0600` perms on the keyfile.
12//! 2. Encrypt/decrypt — thin wrappers around
13//!    `PrivateKeySigner::encrypt_keystore` / `decrypt_keystore`, which
14//!    delegate to `eth-keystore` for the scrypt+AES-128-CTR pipeline.
15//!
16//! # Future: OS keychain
17//!
18//! `KeySource::Keychain` is reserved but not yet implemented. When it lands,
19//! it'll go behind a `keyring` cargo feature so the default build has no
20//! dbus/secret-service transitive deps. CLI sandboxes that need portable
21//! persistence should use the file backend; keychain support is targeted at
22//! interactive dev boxes.
23
24use std::fs;
25use std::path::{Path, PathBuf};
26
27use alloy_primitives::Address;
28use alloy_signer_local::PrivateKeySigner;
29use thiserror::Error as ThisError;
30
31/// Where a wallet private key is (or will be) stored.
32///
33/// Kept as an enum rather than a boolean flag so the CLI's `--keystore` /
34/// `--keychain` flags can desugar into a discriminated choice that the
35/// lower layers (and tests) can match on. Adding a `Keychain` variant
36/// later is additive: existing `File` users keep working.
37#[derive(Debug, Clone)]
38pub enum KeySource {
39    /// Encrypted JSON v3 at an explicit path (or resolved via
40    /// [`default_keyfile_path`]).
41    File { path: PathBuf },
42    // Keychain { service: String, account: String } — deferred behind a
43    // future `keyring` cargo feature; see module docs.
44}
45
46#[derive(Debug, ThisError)]
47pub enum KeystoreError {
48    #[error("home directory not found; set $HOME or $XDG_DATA_HOME")]
49    HomeNotFound,
50    #[error("failed to create keystore dir {path}: {source}")]
51    CreateDir {
52        path: PathBuf,
53        #[source]
54        source: std::io::Error,
55    },
56    #[error("keystore file not found: {0}")]
57    NotFound(PathBuf),
58    #[error("signer/keystore error: {0}")]
59    Signer(String),
60    #[error("I/O error: {0}")]
61    Io(#[from] std::io::Error),
62}
63
64/// Returns `$XDG_DATA_HOME/taskfast/wallets`, falling back to
65/// `$HOME/.local/share/taskfast/wallets` when XDG is unset.
66///
67/// Creates the directory if it doesn't exist and tightens perms to `0700`
68/// on unix. Keystore files are written `0600` after the fact by
69/// [`save_signer`].
70pub fn default_keystore_dir() -> Result<PathBuf, KeystoreError> {
71    let base = match std::env::var("XDG_DATA_HOME") {
72        Ok(xdg) if !xdg.is_empty() => PathBuf::from(xdg),
73        _ => home_fallback()?,
74    };
75    let dir = base.join("taskfast").join("wallets");
76    ensure_dir(&dir)?;
77    Ok(dir)
78}
79
80fn home_fallback() -> Result<PathBuf, KeystoreError> {
81    // XDG spec §4: when $XDG_DATA_HOME is unset/empty, default to
82    // $HOME/.local/share.
83    std::env::var_os("HOME")
84        .filter(|s| !s.is_empty())
85        .map(|home| PathBuf::from(home).join(".local").join("share"))
86        .ok_or(KeystoreError::HomeNotFound)
87}
88
89fn ensure_dir(dir: &Path) -> Result<(), KeystoreError> {
90    fs::create_dir_all(dir).map_err(|source| KeystoreError::CreateDir {
91        path: dir.to_path_buf(),
92        source,
93    })?;
94    // `0700` — private to the owner. No-op on non-unix; Windows ACLs are
95    // the OS-native equivalent and out of scope here.
96    #[cfg(unix)]
97    {
98        use std::os::unix::fs::PermissionsExt;
99        let mut perms = fs::metadata(dir)?.permissions();
100        perms.set_mode(0o700);
101        fs::set_permissions(dir, perms)?;
102    }
103    Ok(())
104}
105
106/// Canonical filename for a wallet keyed by its address: lowercase hex,
107/// no `0x` prefix, `.json` suffix. Matches the shape `cast wallet import`
108/// produces when given `--keystore-dir` without an explicit name.
109pub fn default_keyfile_name(address: Address) -> String {
110    let hex = hex::encode(address.as_slice());
111    format!("{hex}.json")
112}
113
114/// Resolves the default keyfile path for a given address under the default
115/// keystore dir.
116pub fn default_keyfile_path(address: Address) -> Result<PathBuf, KeystoreError> {
117    Ok(default_keystore_dir()?.join(default_keyfile_name(address)))
118}
119
120/// Encrypts `signer` with `password` and writes it to `path`, creating parent
121/// directories as needed. Overwrites any existing file at the same path —
122/// callers wanting idempotency should check [`Path::exists`] first.
123///
124/// On unix the final file is chmod'd to `0600`. Returns the absolute path
125/// actually written.
126pub fn save_signer(
127    signer: &PrivateKeySigner,
128    path: &Path,
129    password: &str,
130) -> Result<PathBuf, KeystoreError> {
131    let parent = path
132        .parent()
133        .ok_or_else(|| KeystoreError::NotFound(path.to_path_buf()))?;
134    ensure_dir(parent)?;
135
136    let file_name = path
137        .file_name()
138        .and_then(|s| s.to_str())
139        .ok_or_else(|| KeystoreError::NotFound(path.to_path_buf()))?;
140
141    let mut rng = rand::thread_rng();
142    // `encrypt_keystore` writes `{parent}/{name}` via eth-keystore's
143    // scrypt + AES-128-CTR pipeline. We pass the already-generated key's
144    // bytes so the saved file corresponds to an existing signer.
145    let pk_bytes = signer.to_bytes();
146    PrivateKeySigner::encrypt_keystore(parent, &mut rng, pk_bytes, password, Some(file_name))
147        .map_err(|e| KeystoreError::Signer(e.to_string()))?;
148
149    let written = parent.join(file_name);
150    #[cfg(unix)]
151    {
152        use std::os::unix::fs::PermissionsExt;
153        let mut perms = fs::metadata(&written)?.permissions();
154        perms.set_mode(0o600);
155        fs::set_permissions(&written, perms)?;
156    }
157    Ok(written)
158}
159
160/// Generates a fresh random signer, encrypts it, writes it to the default
161/// path for its address, and returns `(signer, path)`. The most common init
162/// flow: `taskfast init --generate-wallet`.
163pub fn generate_and_save(password: &str) -> Result<(PrivateKeySigner, PathBuf), KeystoreError> {
164    let signer = PrivateKeySigner::random();
165    let path = default_keyfile_path(signer.address())?;
166    save_signer(&signer, &path, password)?;
167    Ok((signer, path))
168}
169
170/// Decrypts the keystore at `path` with `password` and returns the signer.
171pub fn load_signer(path: &Path, password: &str) -> Result<PrivateKeySigner, KeystoreError> {
172    if !path.exists() {
173        return Err(KeystoreError::NotFound(path.to_path_buf()));
174    }
175    PrivateKeySigner::decrypt_keystore(path, password)
176        .map_err(|e| KeystoreError::Signer(e.to_string()))
177}
178
179/// Load a signer by [`KeySource`] — dispatches to the file backend today.
180/// Keychain support will slot in here under a cargo feature.
181pub fn load(source: &KeySource, password: &str) -> Result<PrivateKeySigner, KeystoreError> {
182    match source {
183        KeySource::File { path } => load_signer(path, password),
184    }
185}
186
187#[cfg(test)]
188mod tests {
189    use super::*;
190    use tempfile::TempDir;
191
192    #[test]
193    fn default_keyfile_name_is_lowercase_hex_without_prefix() {
194        // Deterministic check: bytes 0x01..0x14 → "0102..14.json".
195        let mut bytes = [0u8; 20];
196        for (i, b) in bytes.iter_mut().enumerate() {
197            *b = (i + 1) as u8;
198        }
199        let addr = Address::from(bytes);
200        let name = default_keyfile_name(addr);
201        assert_eq!(name, "0102030405060708090a0b0c0d0e0f1011121314.json");
202    }
203
204    #[test]
205    fn save_then_load_roundtrips_signer() {
206        let tmp = TempDir::new().unwrap();
207        let signer = PrivateKeySigner::random();
208        let expected = signer.address();
209
210        let path = tmp.path().join("wallet.json");
211        save_signer(&signer, &path, "s3kret").expect("save");
212        assert!(path.exists(), "keystore file must exist after save");
213
214        let loaded = load_signer(&path, "s3kret").expect("load");
215        assert_eq!(loaded.address(), expected);
216    }
217
218    #[test]
219    fn load_with_wrong_password_errors() {
220        let tmp = TempDir::new().unwrap();
221        let signer = PrivateKeySigner::random();
222        let path = tmp.path().join("wallet.json");
223        save_signer(&signer, &path, "correct").expect("save");
224
225        let err = load_signer(&path, "wrong").unwrap_err();
226        assert!(matches!(err, KeystoreError::Signer(_)));
227    }
228
229    #[test]
230    fn load_missing_file_reports_not_found() {
231        let tmp = TempDir::new().unwrap();
232        let missing = tmp.path().join("nope.json");
233        let err = load_signer(&missing, "pw").unwrap_err();
234        assert!(matches!(err, KeystoreError::NotFound(_)));
235    }
236
237    #[test]
238    fn save_creates_parent_dirs() {
239        let tmp = TempDir::new().unwrap();
240        let nested = tmp.path().join("a").join("b").join("wallet.json");
241        let signer = PrivateKeySigner::random();
242        save_signer(&signer, &nested, "pw").expect("save");
243        assert!(nested.exists());
244    }
245
246    #[cfg(unix)]
247    #[test]
248    fn saved_keyfile_has_0600_perms() {
249        use std::os::unix::fs::PermissionsExt;
250        let tmp = TempDir::new().unwrap();
251        let path = tmp.path().join("wallet.json");
252        let signer = PrivateKeySigner::random();
253        save_signer(&signer, &path, "pw").expect("save");
254        let mode = fs::metadata(&path).unwrap().permissions().mode() & 0o777;
255        assert_eq!(mode, 0o600, "keyfile must be owner-only readable/writable");
256    }
257
258    #[test]
259    fn key_source_file_dispatches_to_file_backend() {
260        let tmp = TempDir::new().unwrap();
261        let signer = PrivateKeySigner::random();
262        let expected = signer.address();
263        let path = tmp.path().join("wallet.json");
264        save_signer(&signer, &path, "pw").expect("save");
265
266        let loaded = load(&KeySource::File { path: path.clone() }, "pw").expect("load");
267        assert_eq!(loaded.address(), expected);
268    }
269}