taskfast-agent 0.16.1

Orchestration library for TaskFast agents: bootstrap, wallet, webhooks, events, signing, keystore.
Documentation
// SPDX-License-Identifier: MIT
//! Encrypted wallet persistence.
//!
//! Default: Web3 Secret Storage v3 JSON (Foundry/Geth/MetaMask-interoperable),
//! resolved under `$XDG_DATA_HOME/taskfast/wallets/` so a wallet generated here
//! can be imported by `cast wallet import` without conversion.
//!
//! This module owns two concerns and nothing else:
//!
//! 1. Path resolution โ€” XDG-compliant directory layout with `0700` perms on
//!    the containing dir and `0600` perms on the keyfile.
//! 2. Encrypt/decrypt โ€” thin wrappers around
//!    `PrivateKeySigner::encrypt_keystore` / `decrypt_keystore`, which
//!    delegate to `eth-keystore` for the scrypt+AES-128-CTR pipeline.
//!
//! # Future: OS keychain
//!
//! `KeySource::Keychain` is reserved but not yet implemented. When it lands,
//! it'll go behind a `keyring` cargo feature so the default build has no
//! dbus/secret-service transitive deps. CLI sandboxes that need portable
//! persistence should use the file backend; keychain support is targeted at
//! interactive dev boxes.

use std::fs;
use std::path::{Path, PathBuf};

use alloy_primitives::Address;
use alloy_signer_local::PrivateKeySigner;
use thiserror::Error as ThisError;

/// Where a wallet private key is (or will be) stored.
///
/// Kept as an enum rather than a boolean flag so the CLI's `--keystore` /
/// `--keychain` flags can desugar into a discriminated choice that the
/// lower layers (and tests) can match on. Adding a `Keychain` variant
/// later is additive: existing `File` users keep working.
#[derive(Debug, Clone)]
pub enum KeySource {
    /// Encrypted JSON v3 at an explicit path (or resolved via
    /// [`default_keyfile_path`]).
    File { path: PathBuf },
    // Keychain { service: String, account: String } โ€” deferred behind a
    // future `keyring` cargo feature; see module docs.
}

#[derive(Debug, ThisError)]
pub enum KeystoreError {
    #[error("home directory not found; set $HOME or $XDG_DATA_HOME")]
    HomeNotFound,
    #[error("failed to create keystore dir {path}: {source}")]
    CreateDir {
        path: PathBuf,
        #[source]
        source: std::io::Error,
    },
    #[error("keystore file not found: {0}")]
    NotFound(PathBuf),
    #[error("signer/keystore error: {0}")]
    Signer(String),
    #[error("I/O error: {0}")]
    Io(#[from] std::io::Error),
}

/// Returns `$XDG_DATA_HOME/taskfast/wallets`, falling back to
/// `$HOME/.local/share/taskfast/wallets` when XDG is unset.
///
/// Creates the directory if it doesn't exist and tightens perms to `0700`
/// on unix. Keystore files are written `0600` after the fact by
/// [`save_signer`].
pub fn default_keystore_dir() -> Result<PathBuf, KeystoreError> {
    let base = match std::env::var("XDG_DATA_HOME") {
        Ok(xdg) if !xdg.is_empty() => PathBuf::from(xdg),
        _ => home_fallback()?,
    };
    let dir = base.join("taskfast").join("wallets");
    ensure_dir(&dir)?;
    Ok(dir)
}

fn home_fallback() -> Result<PathBuf, KeystoreError> {
    // XDG spec ยง4: when $XDG_DATA_HOME is unset/empty, default to
    // $HOME/.local/share.
    std::env::var_os("HOME")
        .filter(|s| !s.is_empty())
        .map(|home| PathBuf::from(home).join(".local").join("share"))
        .ok_or(KeystoreError::HomeNotFound)
}

fn ensure_dir(dir: &Path) -> Result<(), KeystoreError> {
    fs::create_dir_all(dir).map_err(|source| KeystoreError::CreateDir {
        path: dir.to_path_buf(),
        source,
    })?;
    // `0700` โ€” private to the owner. No-op on non-unix; Windows ACLs are
    // the OS-native equivalent and out of scope here.
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let mut perms = fs::metadata(dir)?.permissions();
        perms.set_mode(0o700);
        fs::set_permissions(dir, perms)?;
    }
    Ok(())
}

/// Canonical filename for a wallet keyed by its address: lowercase hex,
/// no `0x` prefix, `.json` suffix. Matches the shape `cast wallet import`
/// produces when given `--keystore-dir` without an explicit name.
pub fn default_keyfile_name(address: Address) -> String {
    let hex = hex::encode(address.as_slice());
    format!("{hex}.json")
}

/// Resolves the default keyfile path for a given address under the default
/// keystore dir.
pub fn default_keyfile_path(address: Address) -> Result<PathBuf, KeystoreError> {
    Ok(default_keystore_dir()?.join(default_keyfile_name(address)))
}

/// Encrypts `signer` with `password` and writes it to `path`, creating parent
/// directories as needed. Overwrites any existing file at the same path โ€”
/// callers wanting idempotency should check [`Path::exists`] first.
///
/// On unix the final file is chmod'd to `0600`. Returns the absolute path
/// actually written.
pub fn save_signer(
    signer: &PrivateKeySigner,
    path: &Path,
    password: &str,
) -> Result<PathBuf, KeystoreError> {
    let parent = path
        .parent()
        .ok_or_else(|| KeystoreError::NotFound(path.to_path_buf()))?;
    ensure_dir(parent)?;

    let file_name = path
        .file_name()
        .and_then(|s| s.to_str())
        .ok_or_else(|| KeystoreError::NotFound(path.to_path_buf()))?;

    let written = parent.join(file_name);

    // Pre-create the target at `0600` *before* eth-keystore writes the
    // ciphertext. eth-keystore (0.5.0) writes via `File::create(dir/name)`,
    // whose `0o666` mode is honored only when the inode is *created* โ€” so it
    // reopens this existing `0600` inode and rewrites without widening the
    // mode. Relying on the post-write chmod alone leaves a window where the
    // encrypted key is `0o666 & ~umask` (e.g. `0664` under `umask 002`) and
    // world-readable. See gh#78.
    //
    // Note: no `.truncate(true)` here on purpose. Truncating would wipe an
    // existing keystore before `encrypt_keystore` writes the new ciphertext,
    // so a crash in between would leave an empty file and destroy recoverable
    // key material. `encrypt_keystore` performs its own truncate-on-write.
    #[cfg(unix)]
    {
        use std::os::unix::fs::{OpenOptionsExt, PermissionsExt};
        let f = fs::OpenOptions::new()
            .write(true)
            .create(true)
            .truncate(false) // deliberate: don't wipe an existing keystore (see above)
            .mode(0o600)
            .open(&written)?;
        // `.mode()` is a no-op when the file already existed (e.g. a stale
        // `0664` keystore from an older build); tighten it explicitly so the
        // overwrite path repairs broad perms too.
        let mut perms = f.metadata()?.permissions();
        perms.set_mode(0o600);
        f.set_permissions(perms)?;
    }

    let mut rng = rand::thread_rng();
    // `encrypt_keystore` writes `{parent}/{name}` via eth-keystore's
    // scrypt + AES-128-CTR pipeline. We pass the already-generated key's
    // bytes so the saved file corresponds to an existing signer.
    let pk_bytes = signer.to_bytes();
    PrivateKeySigner::encrypt_keystore(parent, &mut rng, pk_bytes, password, Some(file_name))
        .map_err(|e| KeystoreError::Signer(e.to_string()))?;

    // Backstop: re-assert `0600` after the write in case a future
    // eth-keystore changes its write strategy (e.g. temp-file + rename,
    // which would bypass the pre-created inode above).
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let mut perms = fs::metadata(&written)?.permissions();
        perms.set_mode(0o600);
        fs::set_permissions(&written, perms)?;
    }
    Ok(written)
}

/// Generates a fresh random signer, encrypts it, writes it to the default
/// path for its address, and returns `(signer, path)`. The most common init
/// flow: `taskfast init --generate-wallet`.
pub fn generate_and_save(password: &str) -> Result<(PrivateKeySigner, PathBuf), KeystoreError> {
    let signer = PrivateKeySigner::random();
    let path = default_keyfile_path(signer.address())?;
    save_signer(&signer, &path, password)?;
    Ok((signer, path))
}

/// True when `mode`'s group/other bits are set โ€” i.e. the file is readable
/// (or writable) by anyone but the owner. `0o600` and `0o400` are tight;
/// `0o640`/`0o664`/`0o644` are not.
#[cfg(unix)]
fn mode_is_too_open(mode: u32) -> bool {
    mode & 0o077 != 0
}

/// Decrypts the keystore at `path` with `password` and returns the signer.
///
/// On unix, warns (does not repair โ€” a read shouldn't silently mutate file
/// modes) when the keystore is group/world-accessible, so a leak written by
/// an older build or another tool is surfaced rather than ignored (gh#78).
pub fn load_signer(path: &Path, password: &str) -> Result<PrivateKeySigner, KeystoreError> {
    if !path.exists() {
        return Err(KeystoreError::NotFound(path.to_path_buf()));
    }
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let mode = fs::metadata(path)?.permissions().mode() & 0o777;
        if mode_is_too_open(mode) {
            tracing::warn!(
                keystore = %path.display(),
                mode = format!("{mode:o}"),
                "keystore is group/world-accessible (expected 0600) โ€” \
                 run `chmod 600` on it; it holds your encrypted private key"
            );
        }
    }
    PrivateKeySigner::decrypt_keystore(path, password)
        .map_err(|e| KeystoreError::Signer(e.to_string()))
}

/// Load a signer by [`KeySource`] โ€” dispatches to the file backend today.
/// Keychain support will slot in here under a cargo feature.
pub fn load(source: &KeySource, password: &str) -> Result<PrivateKeySigner, KeystoreError> {
    match source {
        KeySource::File { path } => load_signer(path, password),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use tempfile::TempDir;

    #[test]
    fn default_keyfile_name_is_lowercase_hex_without_prefix() {
        // Deterministic check: bytes 0x01..0x14 โ†’ "0102..14.json".
        let mut bytes = [0u8; 20];
        for (i, b) in bytes.iter_mut().enumerate() {
            *b = (i + 1) as u8;
        }
        let addr = Address::from(bytes);
        let name = default_keyfile_name(addr);
        assert_eq!(name, "0102030405060708090a0b0c0d0e0f1011121314.json");
    }

    #[test]
    fn save_then_load_roundtrips_signer() {
        let tmp = TempDir::new().unwrap();
        let signer = PrivateKeySigner::random();
        let expected = signer.address();

        let path = tmp.path().join("wallet.json");
        save_signer(&signer, &path, "s3kret").expect("save");
        assert!(path.exists(), "keystore file must exist after save");

        let loaded = load_signer(&path, "s3kret").expect("load");
        assert_eq!(loaded.address(), expected);
    }

    #[test]
    fn load_with_wrong_password_errors() {
        let tmp = TempDir::new().unwrap();
        let signer = PrivateKeySigner::random();
        let path = tmp.path().join("wallet.json");
        save_signer(&signer, &path, "correct").expect("save");

        let err = load_signer(&path, "wrong").unwrap_err();
        assert!(matches!(err, KeystoreError::Signer(_)));
    }

    #[test]
    fn load_missing_file_reports_not_found() {
        let tmp = TempDir::new().unwrap();
        let missing = tmp.path().join("nope.json");
        let err = load_signer(&missing, "pw").unwrap_err();
        assert!(matches!(err, KeystoreError::NotFound(_)));
    }

    #[test]
    fn save_creates_parent_dirs() {
        let tmp = TempDir::new().unwrap();
        let nested = tmp.path().join("a").join("b").join("wallet.json");
        let signer = PrivateKeySigner::random();
        save_signer(&signer, &nested, "pw").expect("save");
        assert!(nested.exists());
    }

    #[cfg(unix)]
    #[test]
    fn saved_keyfile_has_0600_perms() {
        use std::os::unix::fs::PermissionsExt;
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("wallet.json");
        let signer = PrivateKeySigner::random();
        save_signer(&signer, &path, "pw").expect("save");
        let mode = fs::metadata(&path).unwrap().permissions().mode() & 0o777;
        assert_eq!(mode, 0o600, "keyfile must be owner-only readable/writable");
    }

    #[cfg(unix)]
    #[test]
    fn overwriting_a_world_readable_keystore_tightens_to_0600() {
        // A stale 0664 keystore (older build / foreign umask) must be
        // repaired to 0600 when re-saved, not left wide. gh#78.
        use std::os::unix::fs::PermissionsExt;
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("wallet.json");
        fs::write(&path, b"stale").unwrap();
        fs::set_permissions(&path, fs::Permissions::from_mode(0o664)).unwrap();

        let signer = PrivateKeySigner::random();
        save_signer(&signer, &path, "pw").expect("save over existing file");

        let mode = fs::metadata(&path).unwrap().permissions().mode() & 0o777;
        assert_eq!(mode, 0o600, "overwrite must tighten 0664 -> 0600");
    }

    #[cfg(unix)]
    #[test]
    fn mode_is_too_open_flags_group_and_other_bits() {
        assert!(!mode_is_too_open(0o600));
        assert!(!mode_is_too_open(0o400));
        assert!(mode_is_too_open(0o640), "group-readable is too open");
        assert!(mode_is_too_open(0o604), "other-readable is too open");
        assert!(mode_is_too_open(0o664), "the observed leak mode");
    }

    #[test]
    fn key_source_file_dispatches_to_file_backend() {
        let tmp = TempDir::new().unwrap();
        let signer = PrivateKeySigner::random();
        let expected = signer.address();
        let path = tmp.path().join("wallet.json");
        save_signer(&signer, &path, "pw").expect("save");

        let loaded = load(&KeySource::File { path: path.clone() }, "pw").expect("load");
        assert_eq!(loaded.address(), expected);
    }
}