refactor: rename alknet-secret to alknet-vault
Rename the crate from alknet-secret to alknet-vault to better reflect its purpose as a local key vault (seed management, key derivation, encryption) rather than a network service. Symbol renames: - SecretService → VaultService - SecretServiceHandle → VaultServiceHandle - SecretServiceActor → VaultServiceActor - SecretServiceError → VaultServiceError - SecretProtocol → VaultProtocol - SecretMessage → VaultMessage - ServiceLocked → VaultLocked - alknet_secret → alknet_vault (crate name) Update ADR-008 with vault access pattern: the vault is a capability source, not a service endpoint. The CLI injects derived/decrypted material into operation contexts — handlers never hold vault references.
This commit is contained in:
339
crates/alknet-vault/src/cache.rs
Normal file
339
crates/alknet-vault/src/cache.rs
Normal file
@@ -0,0 +1,339 @@
|
||||
//! TTL-based key cache with LRU eviction for VaultService.
|
||||
//!
|
||||
//! The `KeyCache` stores derived key material keyed by derivation path. Entries
|
||||
//! expire after a configurable TTL (default: 1 hour) and are evicted lazily on
|
||||
//! access. When the cache exceeds `max_entries` (default: 64), the least recently
|
||||
//! used entry is evicted. All entries are zeroized on removal per ADR-038.
|
||||
|
||||
use std::collections::HashMap;
|
||||
use std::time::{Duration, Instant};
|
||||
|
||||
use zeroize::Zeroize;
|
||||
|
||||
use crate::protocol::KeyType;
|
||||
|
||||
/// Default TTL for cached keys (1 hour).
|
||||
pub const DEFAULT_TTL: Duration = Duration::from_secs(3600);
|
||||
|
||||
/// Default maximum number of cache entries.
|
||||
pub const DEFAULT_MAX_ENTRIES: usize = 64;
|
||||
|
||||
/// A cached derived key with metadata for TTL and LRU tracking.
|
||||
///
|
||||
/// The `private_key` field is zeroized on drop via `#[zeroize(drop)]`.
|
||||
/// This is a separate internal type from `DerivedKey` — it holds the same
|
||||
/// data but is managed within the cache lifecycle.
|
||||
#[derive(Zeroize)]
|
||||
#[zeroize(drop)]
|
||||
pub struct CachedKey {
|
||||
/// When this key was derived (for TTL checking).
|
||||
#[zeroize(skip)]
|
||||
pub derived_at: Instant,
|
||||
/// The type of key that was derived.
|
||||
#[zeroize(skip)]
|
||||
pub key_type: KeyType,
|
||||
/// The private key bytes (sensitive — zeroized on drop).
|
||||
#[zeroize]
|
||||
pub private_key: Vec<u8>,
|
||||
/// The public key bytes.
|
||||
#[zeroize(skip)]
|
||||
pub public_key: Vec<u8>,
|
||||
/// Last access time for LRU ordering.
|
||||
#[zeroize(skip)]
|
||||
last_accessed: Instant,
|
||||
}
|
||||
|
||||
impl CachedKey {
|
||||
/// Create a new `CachedKey` from derived key material.
|
||||
pub fn new(key_type: KeyType, private_key: Vec<u8>, public_key: Vec<u8>) -> Self {
|
||||
let now = Instant::now();
|
||||
Self {
|
||||
derived_at: now,
|
||||
key_type,
|
||||
private_key,
|
||||
public_key,
|
||||
last_accessed: now,
|
||||
}
|
||||
}
|
||||
|
||||
/// Check whether this cached entry has expired.
|
||||
pub fn is_expired(&self, ttl: Duration) -> bool {
|
||||
Instant::now().duration_since(self.derived_at) > ttl
|
||||
}
|
||||
|
||||
/// Touch the entry to update its last-accessed time (for LRU).
|
||||
pub fn touch(&mut self) {
|
||||
self.last_accessed = Instant::now();
|
||||
}
|
||||
}
|
||||
|
||||
/// Configuration for the key cache.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct CacheConfig {
|
||||
/// Time-to-live for cached entries. Expired entries are evicted lazily on access.
|
||||
pub ttl: Duration,
|
||||
/// Maximum number of entries. When exceeded, the least recently used entry is evicted.
|
||||
pub max_entries: usize,
|
||||
}
|
||||
|
||||
impl Default for CacheConfig {
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
ttl: DEFAULT_TTL,
|
||||
max_entries: DEFAULT_MAX_ENTRIES,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl CacheConfig {
|
||||
/// Create a new `CacheConfig` with the given TTL and max entries.
|
||||
pub fn new(ttl: Duration, max_entries: usize) -> Self {
|
||||
Self { ttl, max_entries }
|
||||
}
|
||||
}
|
||||
|
||||
/// LRU key cache backed by a HashMap with access-order tracking.
|
||||
///
|
||||
/// The cache uses a `HashMap` for O(1) lookups and a separate ordering list
|
||||
/// for LRU eviction. For the default 64 entries, this is efficient enough
|
||||
/// without needing the `lru` crate.
|
||||
pub struct KeyCache {
|
||||
entries: HashMap<String, CachedKey>,
|
||||
/// Access order: most recently used at the back, least recently at the front.
|
||||
order: Vec<String>,
|
||||
config: CacheConfig,
|
||||
}
|
||||
|
||||
impl KeyCache {
|
||||
/// Create a new empty `KeyCache` with the given configuration.
|
||||
pub fn new(config: CacheConfig) -> Self {
|
||||
Self {
|
||||
entries: HashMap::new(),
|
||||
order: Vec::with_capacity(config.max_entries),
|
||||
config,
|
||||
}
|
||||
}
|
||||
|
||||
/// Create a new empty `KeyCache` with default configuration.
|
||||
pub fn with_defaults() -> Self {
|
||||
Self::new(CacheConfig::default())
|
||||
}
|
||||
|
||||
/// Get a cached entry by derivation path if it exists and is within TTL.
|
||||
///
|
||||
/// Returns `None` if the entry does not exist or has expired (expired entries
|
||||
/// are evicted). A successful get updates the LRU ordering.
|
||||
pub fn get(&mut self, path: &str) -> Option<&CachedKey> {
|
||||
if let Some(entry) = self.entries.get_mut(path) {
|
||||
if entry.is_expired(self.config.ttl) {
|
||||
self.remove_entry(path);
|
||||
return None;
|
||||
}
|
||||
entry.touch();
|
||||
self.move_to_back(path);
|
||||
Some(self.entries.get(path)?)
|
||||
} else {
|
||||
None
|
||||
}
|
||||
}
|
||||
|
||||
/// Insert a cached key by derivation path.
|
||||
///
|
||||
/// If the cache is at capacity, the least recently used entry is evicted
|
||||
/// (and zeroized). If an entry with the same path already exists, it is
|
||||
/// replaced (the old entry is zeroized on drop).
|
||||
pub fn insert(&mut self, path: &str, key: CachedKey) {
|
||||
if self.entries.contains_key(path) {
|
||||
self.remove_entry(path);
|
||||
} else if self.entries.len() >= self.config.max_entries {
|
||||
self.evict_lru();
|
||||
}
|
||||
self.entries.insert(path.to_string(), key);
|
||||
self.order.push(path.to_string());
|
||||
}
|
||||
|
||||
/// Remove all entries that have exceeded the TTL, zeroizing them.
|
||||
pub fn evict_expired(&mut self) {
|
||||
let ttl = self.config.ttl;
|
||||
let expired: Vec<String> = self
|
||||
.entries
|
||||
.iter()
|
||||
.filter(|(_, v)| v.is_expired(ttl))
|
||||
.map(|(k, _)| k.clone())
|
||||
.collect();
|
||||
|
||||
for path in expired {
|
||||
self.remove_entry(&path);
|
||||
}
|
||||
}
|
||||
|
||||
/// Clear all cache entries, zeroizing each one before removal.
|
||||
pub fn clear(&mut self) {
|
||||
self.entries.clear();
|
||||
self.order.clear();
|
||||
}
|
||||
|
||||
/// Returns the number of entries currently in the cache.
|
||||
pub fn len(&self) -> usize {
|
||||
self.entries.len()
|
||||
}
|
||||
|
||||
/// Returns `true` if the cache contains no entries.
|
||||
pub fn is_empty(&self) -> bool {
|
||||
self.entries.is_empty()
|
||||
}
|
||||
|
||||
fn remove_entry(&mut self, path: &str) {
|
||||
self.entries.remove(path);
|
||||
self.order.retain(|p| p != path);
|
||||
}
|
||||
|
||||
fn evict_lru(&mut self) {
|
||||
if let Some(lru_path) = self.order.first().cloned() {
|
||||
self.remove_entry(&lru_path);
|
||||
}
|
||||
}
|
||||
|
||||
fn move_to_back(&mut self, path: &str) {
|
||||
self.order.retain(|p| p != path);
|
||||
self.order.push(path.to_string());
|
||||
}
|
||||
}
|
||||
|
||||
impl Default for KeyCache {
|
||||
fn default() -> Self {
|
||||
Self::with_defaults()
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
fn make_cached_key(key_type: KeyType) -> CachedKey {
|
||||
CachedKey::new(key_type, vec![0xABu8; 32], vec![0xCDu8; 32])
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_cache_insert_and_get() {
|
||||
let mut cache = KeyCache::with_defaults();
|
||||
cache.insert("m/74'/0'/0'/0'", make_cached_key(KeyType::Ed25519));
|
||||
|
||||
let entry = cache.get("m/74'/0'/0'/0'").unwrap();
|
||||
assert_eq!(entry.key_type, KeyType::Ed25519);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_cache_miss_returns_none() {
|
||||
let mut cache = KeyCache::with_defaults();
|
||||
assert!(cache.get("m/74'/0'/0'/0'").is_none());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_cache_expired_entry_evicted_on_access() {
|
||||
let mut config = CacheConfig::default();
|
||||
config.ttl = Duration::from_millis(1);
|
||||
|
||||
let mut cache = KeyCache::new(config);
|
||||
cache.insert("m/74'/0'/0'/0'", make_cached_key(KeyType::Ed25519));
|
||||
|
||||
std::thread::sleep(Duration::from_millis(5));
|
||||
|
||||
assert!(cache.get("m/74'/0'/0'/0'").is_none());
|
||||
assert_eq!(cache.len(), 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_cache_lru_eviction() {
|
||||
let mut config = CacheConfig::default();
|
||||
config.max_entries = 3;
|
||||
|
||||
let mut cache = KeyCache::new(config);
|
||||
|
||||
cache.insert("path1", make_cached_key(KeyType::Ed25519));
|
||||
cache.insert("path2", make_cached_key(KeyType::Aes256Gcm));
|
||||
cache.insert("path3", make_cached_key(KeyType::Secp256k1));
|
||||
|
||||
assert_eq!(cache.len(), 3);
|
||||
|
||||
cache.insert("path4", make_cached_key(KeyType::Ed25519));
|
||||
|
||||
assert_eq!(cache.len(), 3);
|
||||
assert!(cache.get("path1").is_none());
|
||||
assert!(cache.get("path2").is_some());
|
||||
assert!(cache.get("path3").is_some());
|
||||
assert!(cache.get("path4").is_some());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_cache_lru_access_reorders() {
|
||||
let mut config = CacheConfig::default();
|
||||
config.max_entries = 3;
|
||||
|
||||
let mut cache = KeyCache::new(config);
|
||||
|
||||
cache.insert("path1", make_cached_key(KeyType::Ed25519));
|
||||
cache.insert("path2", make_cached_key(KeyType::Aes256Gcm));
|
||||
cache.insert("path3", make_cached_key(KeyType::Secp256k1));
|
||||
|
||||
cache.get("path1");
|
||||
|
||||
cache.insert("path4", make_cached_key(KeyType::Ed25519));
|
||||
|
||||
assert_eq!(cache.len(), 3);
|
||||
assert!(cache.get("path1").is_some());
|
||||
assert!(cache.get("path2").is_none());
|
||||
assert!(cache.get("path3").is_some());
|
||||
assert!(cache.get("path4").is_some());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_cache_clear_zeroizes_and_removes_all() {
|
||||
let mut cache = KeyCache::with_defaults();
|
||||
cache.insert("path1", make_cached_key(KeyType::Ed25519));
|
||||
cache.insert("path2", make_cached_key(KeyType::Aes256Gcm));
|
||||
|
||||
assert_eq!(cache.len(), 2);
|
||||
|
||||
cache.clear();
|
||||
|
||||
assert_eq!(cache.len(), 0);
|
||||
assert!(cache.is_empty());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_evict_expired_removes_only_expired() {
|
||||
let mut config = CacheConfig::default();
|
||||
config.ttl = Duration::from_millis(10);
|
||||
|
||||
let mut cache = KeyCache::new(config);
|
||||
cache.insert("path1", make_cached_key(KeyType::Ed25519));
|
||||
|
||||
std::thread::sleep(Duration::from_millis(20));
|
||||
|
||||
cache.insert("path2", make_cached_key(KeyType::Aes256Gcm));
|
||||
|
||||
cache.evict_expired();
|
||||
|
||||
assert_eq!(cache.len(), 1);
|
||||
assert!(cache.get("path2").is_some());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_cache_replace_existing_path() {
|
||||
let mut cache = KeyCache::with_defaults();
|
||||
cache.insert(
|
||||
"path1",
|
||||
CachedKey::new(KeyType::Ed25519, vec![1u8; 32], vec![2u8; 32]),
|
||||
);
|
||||
cache.insert(
|
||||
"path1",
|
||||
CachedKey::new(KeyType::Aes256Gcm, vec![3u8; 32], vec![4u8; 32]),
|
||||
);
|
||||
|
||||
let entry = cache.get("path1").unwrap();
|
||||
assert_eq!(entry.key_type, KeyType::Aes256Gcm);
|
||||
assert_eq!(entry.private_key, vec![3u8; 32]);
|
||||
assert_eq!(cache.len(), 1);
|
||||
}
|
||||
}
|
||||
300
crates/alknet-vault/src/derivation.rs
Normal file
300
crates/alknet-vault/src/derivation.rs
Normal file
@@ -0,0 +1,300 @@
|
||||
//! SLIP-0010 Ed25519 HD key derivation and path constants.
|
||||
//!
|
||||
//! This module provides hierarchical deterministic (HD) key derivation following
|
||||
//! SLIP-0010 for Ed25519 keys and BIP-0032 for secp256k1 keys. The `74'`
|
||||
//! coin type is unallocated per SLIP-0044 and reserved for alknet.
|
||||
//!
|
||||
//! # Derivation Paths
|
||||
//!
|
||||
//! | Path | Purpose | Curve/Algorithm |
|
||||
//! |------|---------|----------------|
|
||||
//! | `m/74'/0'/0'/0'` | Primary identity keypair | Ed25519 (alknet auth) |
|
||||
//! | `m/74'/0'/0'/{n}'` | Worker/device identity | Ed25519 |
|
||||
//! | `m/74'/0'/1'/0'` | SSH host key | Ed25519 |
|
||||
//! | `m/74'/1'/0'/{hash}'` | Site-specific password | Deterministic |
|
||||
//! | `m/74'/2'/0'/0'` | Encryption key for external credentials | AES-256-GCM |
|
||||
//! | `m/44'/60'/0'/0/0` | Ethereum signing key | secp256k1 |
|
||||
|
||||
use ed25519_bip32::XPrv;
|
||||
use hmac::{Hmac, Mac};
|
||||
use sha2::Sha512;
|
||||
use zeroize::Zeroize;
|
||||
|
||||
type HmacSha512 = Hmac<Sha512>;
|
||||
|
||||
/// Well-known derivation path constants for alknet key material.
|
||||
///
|
||||
/// These paths are defined once and referenced by both the vault service and
|
||||
/// external consumers that need to request specific key types.
|
||||
#[allow(non_snake_case)]
|
||||
pub mod PATHS {
|
||||
/// Primary identity keypair for alknet authentication.
|
||||
pub const IDENTITY: &str = "m/74'/0'/0'/0'";
|
||||
|
||||
/// Worker/device identity keypair (parameterized by device index).
|
||||
/// Use `device_path(n)` to construct the full path.
|
||||
pub const DEVICE_PREFIX: &str = "m/74'/0'/0'";
|
||||
|
||||
/// SSH host key.
|
||||
pub const SSH_HOST: &str = "m/74'/0'/1'/0'";
|
||||
|
||||
/// Encryption key for external credentials (AES-256-GCM).
|
||||
pub const ENCRYPTION: &str = "m/74'/2'/0'/0'";
|
||||
|
||||
/// Ethereum signing key.
|
||||
pub const ETHEREUM: &str = "m/44'/60'/0'/0/0";
|
||||
}
|
||||
|
||||
/// Construct a device identity derivation path with the given index.
|
||||
///
|
||||
/// Path: `m/74'/0'/0'/{n}'`
|
||||
pub fn device_path(index: u32) -> String {
|
||||
format!("m/74'/0'/0'/{}'", index)
|
||||
}
|
||||
|
||||
/// Construct a site-specific password derivation path with the given hash.
|
||||
///
|
||||
/// Path: `m/74'/1'/0'/{hash}'`
|
||||
pub fn site_password_path(site_hash: &str) -> String {
|
||||
format!("m/74'/1'/0'/{}'", site_hash)
|
||||
}
|
||||
|
||||
/// A derived extended private key with its public key.
|
||||
///
|
||||
/// Contains the private key bytes and public key bytes from
|
||||
/// SLIP-0010 Ed25519 derivation.
|
||||
#[derive(Clone, Zeroize)]
|
||||
#[zeroize(drop)]
|
||||
pub struct ExtendedPrivKey {
|
||||
/// The private key bytes (first 32 bytes of the extended key).
|
||||
private_key: Vec<u8>,
|
||||
/// The public key bytes (32 bytes).
|
||||
public_key: Vec<u8>,
|
||||
/// The chain code for child derivation (32 bytes).
|
||||
chain_code: Vec<u8>,
|
||||
/// The derivation path that produced this key.
|
||||
path: String,
|
||||
}
|
||||
|
||||
impl ExtendedPrivKey {
|
||||
/// Returns the private key bytes (32 bytes for Ed25519).
|
||||
pub fn private_key(&self) -> &[u8] {
|
||||
&self.private_key
|
||||
}
|
||||
|
||||
/// Returns the public key bytes (32 bytes for Ed25519).
|
||||
pub fn public_key(&self) -> &[u8] {
|
||||
&self.public_key
|
||||
}
|
||||
|
||||
/// Returns the derivation path string.
|
||||
pub fn path(&self) -> &str {
|
||||
&self.path
|
||||
}
|
||||
}
|
||||
|
||||
/// Derive an extended private key from a seed and derivation path.
|
||||
///
|
||||
/// This is the primary entry point for HD key derivation. Create a master key
|
||||
/// from the seed, then derive the specified path.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```
|
||||
/// use alknet_vault::derivation::{derive_path_from_seed, PATHS};
|
||||
/// use alknet_vault::mnemonic::Mnemonic;
|
||||
///
|
||||
/// let mnemonic = Mnemonic::generate(24).unwrap();
|
||||
/// let seed = mnemonic.to_seed(None);
|
||||
/// let identity_key = derive_path_from_seed(seed.as_bytes(), PATHS::IDENTITY).unwrap();
|
||||
/// assert!(!identity_key.private_key().is_empty());
|
||||
/// ```
|
||||
pub fn derive_path_from_seed(seed: &[u8], path: &str) -> Result<ExtendedPrivKey, DerivationError> {
|
||||
let indices = parse_derivation_path(path)?;
|
||||
let xprv = derive_master_key(seed)?;
|
||||
|
||||
let mut current = xprv;
|
||||
for index in indices {
|
||||
current = current.derive(ed25519_bip32::DerivationScheme::V2, index);
|
||||
}
|
||||
|
||||
let public_key = current.public();
|
||||
|
||||
Ok(ExtendedPrivKey {
|
||||
private_key: current.extended_secret_key_bytes()[..32].to_vec(),
|
||||
public_key: public_key.as_ref()[..32].to_vec(),
|
||||
chain_code: current.chain_code().to_vec(),
|
||||
path: path.to_string(),
|
||||
})
|
||||
}
|
||||
|
||||
/// Derive the SLIP-0010 Ed25519 master key from a seed.
|
||||
///
|
||||
/// Uses HMAC-SHA512 with key "ed25519 seed" over the seed bytes,
|
||||
/// following SLIP-0010 specification.
|
||||
fn derive_master_key(seed: &[u8]) -> Result<XPrv, DerivationError> {
|
||||
let mut mac = HmacSha512::new_from_slice(b"ed25519 seed")
|
||||
.map_err(|e| DerivationError::Hmac(e.to_string()))?;
|
||||
mac.update(seed);
|
||||
let result = mac.finalize().into_bytes();
|
||||
|
||||
// First 32 bytes: private key (kL in SLIP-0010)
|
||||
// Next 32 bytes: chain code
|
||||
let private_key_bytes = &result[..32];
|
||||
let chain_code_bytes = &result[32..];
|
||||
|
||||
// Construct XPrv from the HMAC result
|
||||
// ed25519-bip32 expects a 96-byte extended key:
|
||||
// [32 bytes: kL || 32 bytes: kR (extended secret key) || 32 bytes: chain code]
|
||||
// SLIP-0010 uses the first 32 bytes as kL and hashes through SHA-512
|
||||
// to get the full extended key. We use from_nonextended_force to handle this.
|
||||
let mut priv_bytes = [0u8; 32];
|
||||
priv_bytes.copy_from_slice(private_key_bytes);
|
||||
let mut cc_bytes = [0u8; 32];
|
||||
cc_bytes.copy_from_slice(chain_code_bytes);
|
||||
|
||||
Ok(XPrv::from_nonextended_force(&priv_bytes, &cc_bytes))
|
||||
}
|
||||
|
||||
/// Parse a derivation path string into child indices.
|
||||
///
|
||||
/// Path format: `m/74'/0'/0'/0'`
|
||||
/// Hardened indices have `'` or `h` suffix. Unhardened indices are allowed
|
||||
/// for BIP-0032 paths (e.g., Ethereum `m/44'/60'/0'/0/0`).
|
||||
pub fn parse_derivation_path(path: &str) -> Result<Vec<u32>, DerivationError> {
|
||||
if !path.starts_with('m') {
|
||||
return Err(DerivationError::InvalidPath(
|
||||
"path must start with 'm'".to_string(),
|
||||
));
|
||||
}
|
||||
|
||||
let mut indices = Vec::new();
|
||||
let parts: Vec<&str> = path.split('/').skip(1).collect(); // skip "m"
|
||||
|
||||
for part in parts {
|
||||
let hardened = part.ends_with('\'') || part.ends_with('h');
|
||||
let index_str = part.trim_end_matches('\'').trim_end_matches('h');
|
||||
let index: u32 = index_str
|
||||
.parse()
|
||||
.map_err(|_| DerivationError::InvalidPath(format!("invalid index: {part}")))?;
|
||||
|
||||
if hardened {
|
||||
indices.push(index + 0x80000000);
|
||||
} else {
|
||||
indices.push(index);
|
||||
}
|
||||
}
|
||||
|
||||
Ok(indices)
|
||||
}
|
||||
|
||||
/// Errors that can occur during key derivation.
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
pub enum DerivationError {
|
||||
#[error("invalid derivation path: {0}")]
|
||||
InvalidPath(String),
|
||||
#[error("HMAC error: {0}")]
|
||||
Hmac(String),
|
||||
#[error("key derivation error: {0}")]
|
||||
KeyDerivation(String),
|
||||
#[error("seed is not unlocked")]
|
||||
Locked,
|
||||
#[error("secp256k1 error: {0}")]
|
||||
Secp256k1(String),
|
||||
#[error("unsupported key type")]
|
||||
UnsupportedKeyType,
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_parse_derivation_path_hardened() {
|
||||
let indices = parse_derivation_path("m/74'/0'/0'/0'").unwrap();
|
||||
assert_eq!(
|
||||
indices,
|
||||
vec![0x80000000 + 74, 0x80000000, 0x80000000, 0x80000000]
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_parse_derivation_path_mixed() {
|
||||
// Ethereum path has unhardened indices
|
||||
let indices = parse_derivation_path("m/44'/60'/0'/0/0").unwrap();
|
||||
assert_eq!(
|
||||
indices,
|
||||
vec![0x80000000 + 44, 0x80000000 + 60, 0x80000000, 0, 0]
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_parse_rejects_no_m_prefix() {
|
||||
let result = parse_derivation_path("74'/0'/0'/0'");
|
||||
assert!(result.is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_path_constants() {
|
||||
assert_eq!(PATHS::IDENTITY, "m/74'/0'/0'/0'");
|
||||
assert_eq!(PATHS::ENCRYPTION, "m/74'/2'/0'/0'");
|
||||
assert_eq!(PATHS::SSH_HOST, "m/74'/0'/1'/0'");
|
||||
assert_eq!(PATHS::ETHEREUM, "m/44'/60'/0'/0/0");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_device_path() {
|
||||
assert_eq!(device_path(0), "m/74'/0'/0'/0'");
|
||||
assert_eq!(device_path(1), "m/74'/0'/0'/1'");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_site_password_path() {
|
||||
assert_eq!(site_password_path("abc123"), "m/74'/1'/0'/abc123'");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_derive_master_key_from_seed() {
|
||||
// Use a known 64-byte seed
|
||||
let seed = [0xABu8; 64];
|
||||
let result = derive_master_key(&seed);
|
||||
assert!(result.is_ok());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_derive_identity_key_from_random_seed() {
|
||||
let mnemonic = crate::mnemonic::Mnemonic::generate(24).unwrap();
|
||||
let seed = mnemonic.to_seed(None);
|
||||
let key = derive_path_from_seed(seed.as_bytes(), PATHS::IDENTITY);
|
||||
assert!(key.is_ok());
|
||||
|
||||
let key = key.unwrap();
|
||||
assert_eq!(key.private_key().len(), 32);
|
||||
assert_eq!(key.public_key().len(), 32);
|
||||
assert_eq!(key.path(), PATHS::IDENTITY);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_deterministic_derivation() {
|
||||
let mnemonic = crate::mnemonic::Mnemonic::generate(24).unwrap();
|
||||
let seed = mnemonic.to_seed(None);
|
||||
|
||||
let key1 = derive_path_from_seed(seed.as_bytes(), PATHS::IDENTITY).unwrap();
|
||||
let key2 = derive_path_from_seed(seed.as_bytes(), PATHS::IDENTITY).unwrap();
|
||||
|
||||
assert_eq!(key1.private_key(), key2.private_key());
|
||||
assert_eq!(key1.public_key(), key2.public_key());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_different_paths_different_keys() {
|
||||
let mnemonic = crate::mnemonic::Mnemonic::generate(24).unwrap();
|
||||
let seed = mnemonic.to_seed(None);
|
||||
|
||||
let identity = derive_path_from_seed(seed.as_bytes(), PATHS::IDENTITY).unwrap();
|
||||
let ssh = derive_path_from_seed(seed.as_bytes(), PATHS::SSH_HOST).unwrap();
|
||||
|
||||
assert_ne!(identity.private_key(), ssh.private_key());
|
||||
assert_ne!(identity.public_key(), ssh.public_key());
|
||||
}
|
||||
}
|
||||
248
crates/alknet-vault/src/encryption.rs
Normal file
248
crates/alknet-vault/src/encryption.rs
Normal file
@@ -0,0 +1,248 @@
|
||||
//! AES-256-GCM encryption and decryption for external credentials.
|
||||
//!
|
||||
//! External credentials (API keys, OAuth tokens) that cannot be derived from the
|
||||
//! seed are encrypted using a key derived from the seed at path `m/74'/2'/0'/0'`.
|
||||
//! The `EncryptedData` type stores the key version, salt, IV, and ciphertext.
|
||||
//!
|
||||
//! # Salt Field (Reserved for Future KDF-Based Key Derivation)
|
||||
//!
|
||||
//! The `salt` field in `EncryptedData` is **reserved for future KDF-based key
|
||||
//! derivation** (Phase B). In v1, the encryption key is derived directly from the
|
||||
//! seed at path `m/74'/2'/0'/0'` without using the salt. The salt is generated
|
||||
//! randomly (32 bytes) and stored in `EncryptedData.salt` for forward
|
||||
//! compatibility, but it plays no role in the v1 key derivation process.
|
||||
//!
|
||||
//! When key rotation is implemented in Phase B, the salt will be used as input to
|
||||
//! HKDF or PBKDF2 for stretch-based key derivation, allowing the same seed to
|
||||
//! produce different encryption keys without changing the derivation path. This
|
||||
//! design ensures that the wire format does not need to change — the `salt` field
|
||||
//! is already present and populated.
|
||||
//!
|
||||
//! # Wire Format
|
||||
//!
|
||||
//! The `EncryptedData` struct is the stable wire format shared with alknet-storage.
|
||||
//! This is type-level compatibility, not a crate dependency. Both crates must
|
||||
//! agree on the serialization format.
|
||||
//!
|
||||
//! # Key Versioning
|
||||
//!
|
||||
//! Key versioning allows re-encryption when the encryption key is rotated. The
|
||||
//! current key version is `1`. To rotate:
|
||||
//! 1. Derive a new key from a new derivation path or new seed
|
||||
//! 2. Decrypt all existing `EncryptedData` with key version 1
|
||||
//! 3. Re-encrypt with key version 2
|
||||
//! 4. Update storage
|
||||
|
||||
use aes_gcm::{
|
||||
aead::{Aead, KeyInit},
|
||||
Aes256Gcm, Nonce,
|
||||
};
|
||||
use serde::{Deserialize, Serialize};
|
||||
use zeroize::Zeroize;
|
||||
|
||||
/// Current default key version for encryption.
|
||||
pub const CURRENT_KEY_VERSION: u32 = 1;
|
||||
|
||||
/// Encrypted data blob stored in the metagraph.
|
||||
///
|
||||
/// This is the stable wire format shared with alknet-storage. The fields are
|
||||
/// Base64-encoded strings for JSON serialization compatibility.
|
||||
///
|
||||
/// # Compatibility
|
||||
///
|
||||
/// The Rust `EncryptedData` is a superset of the TypeScript `EncryptedDataSchema`
|
||||
/// from `@alkdev/storage`. Migration path: re-encrypt TypeScript-encrypted data
|
||||
/// using the Rust vault with a new key version.
|
||||
///
|
||||
/// See OQ-SVC-03 for the compatibility tracking.
|
||||
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
|
||||
pub struct EncryptedData {
|
||||
/// Key version for rotation support.
|
||||
pub key_version: u32,
|
||||
/// Base64-encoded random salt.
|
||||
///
|
||||
/// **Reserved for future KDF-based key derivation (Phase B).** In v1, the
|
||||
/// encryption key is derived directly from the seed at path `m/74'/2'/0'/0'`
|
||||
/// without using the salt. The salt is generated and stored for forward
|
||||
/// compatibility but does not participate in key derivation.
|
||||
pub salt: String,
|
||||
/// Base64-encoded initialization vector (12 bytes for AES-GCM).
|
||||
pub iv: String,
|
||||
/// Base64-encoded ciphertext (AES-256-GCM encrypted, includes auth tag).
|
||||
pub data: String,
|
||||
}
|
||||
|
||||
/// Encryption key material derived from the seed.
|
||||
///
|
||||
/// Holds the 32-byte AES-256-GCM key and its derivation metadata.
|
||||
/// Zeroized on drop per ADR-038.
|
||||
#[derive(Clone, Zeroize)]
|
||||
#[zeroize(drop)]
|
||||
pub struct EncryptionKey {
|
||||
key_bytes: [u8; 32],
|
||||
key_version: u32,
|
||||
}
|
||||
|
||||
impl EncryptionKey {
|
||||
/// Create a new encryption key from raw bytes and a version number.
|
||||
pub fn new(key_bytes: [u8; 32], key_version: u32) -> Self {
|
||||
Self {
|
||||
key_bytes,
|
||||
key_version,
|
||||
}
|
||||
}
|
||||
|
||||
/// Create a new encryption key from the first 32 bytes of derived key material.
|
||||
///
|
||||
/// The input is typically the private key bytes from derivation at path
|
||||
/// `m/74'/2'/0'/0'`.
|
||||
pub fn from_derived_bytes(bytes: &[u8], key_version: u32) -> Self {
|
||||
let mut key = [0u8; 32];
|
||||
key.copy_from_slice(&bytes[..32]);
|
||||
Self {
|
||||
key_bytes: key,
|
||||
key_version,
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns the key version.
|
||||
pub fn version(&self) -> u32 {
|
||||
self.key_version
|
||||
}
|
||||
}
|
||||
|
||||
/// Encrypt plaintext using an AES-256-GCM key.
|
||||
///
|
||||
/// Generates a random 12-byte IV and a random 32-byte salt for each encryption.
|
||||
/// The salt allows key rotation without re-deriving from the seed.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `plaintext` - The string to encrypt
|
||||
/// * `key` - The encryption key derived from the seed
|
||||
/// * `key_version` - The key version for rotation tracking
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// An `EncryptedData` struct suitable for storage in the metagraph.
|
||||
pub fn encrypt(plaintext: &str, key: &EncryptionKey) -> Result<EncryptedData, EncryptionError> {
|
||||
let cipher = Aes256Gcm::new_from_slice(&key.key_bytes)
|
||||
.map_err(|e| EncryptionError::Encryption(format!("invalid key length: {e}")))?;
|
||||
|
||||
// Generate random IV (12 bytes for AES-GCM)
|
||||
let iv_bytes: [u8; 12] = rand::random();
|
||||
let nonce = Nonce::from_slice(&iv_bytes);
|
||||
|
||||
// TODO(Phase B): Use salt in HKDF-based key derivation
|
||||
let salt_bytes: [u8; 32] = rand::random();
|
||||
|
||||
let ciphertext = cipher
|
||||
.encrypt(nonce, plaintext.as_bytes())
|
||||
.map_err(|e| EncryptionError::Encryption(e.to_string()))?;
|
||||
|
||||
Ok(EncryptedData {
|
||||
key_version: key.key_version,
|
||||
salt: base64::Engine::encode(&base64::engine::general_purpose::STANDARD, salt_bytes),
|
||||
iv: base64::Engine::encode(&base64::engine::general_purpose::STANDARD, iv_bytes),
|
||||
data: base64::Engine::encode(&base64::engine::general_purpose::STANDARD, &ciphertext),
|
||||
})
|
||||
}
|
||||
|
||||
/// Decrypt an `EncryptedData` blob back to plaintext.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `encrypted` - The encrypted data blob from storage
|
||||
/// * `key` - The encryption key derived from the seed (must match `key_version`)
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// The decrypted plaintext string.
|
||||
pub fn decrypt(encrypted: &EncryptedData, key: &EncryptionKey) -> Result<String, EncryptionError> {
|
||||
let cipher = Aes256Gcm::new_from_slice(&key.key_bytes)
|
||||
.map_err(|e| EncryptionError::Decryption(format!("invalid key length: {e}")))?;
|
||||
|
||||
let iv_bytes =
|
||||
base64::Engine::decode(&base64::engine::general_purpose::STANDARD, &encrypted.iv)
|
||||
.map_err(|e| EncryptionError::Decoding(e.to_string()))?;
|
||||
let nonce = Nonce::from_slice(&iv_bytes);
|
||||
|
||||
let ciphertext =
|
||||
base64::Engine::decode(&base64::engine::general_purpose::STANDARD, &encrypted.data)
|
||||
.map_err(|e| EncryptionError::Decoding(e.to_string()))?;
|
||||
|
||||
let plaintext = cipher
|
||||
.decrypt(nonce, ciphertext.as_ref())
|
||||
.map_err(|e| EncryptionError::Decryption(e.to_string()))?;
|
||||
|
||||
String::from_utf8(plaintext).map_err(|e| EncryptionError::Decryption(e.to_string()))
|
||||
}
|
||||
|
||||
/// Errors that can occur during encryption/decryption operations.
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
pub enum EncryptionError {
|
||||
#[error("encryption error: {0}")]
|
||||
Encryption(String),
|
||||
#[error("decryption error: {0}")]
|
||||
Decryption(String),
|
||||
#[error("base64 decoding error: {0}")]
|
||||
Decoding(String),
|
||||
#[error("key version mismatch: expected {expected}, got {actual}")]
|
||||
KeyVersionMismatch { expected: u32, actual: u32 },
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
fn make_test_key() -> EncryptionKey {
|
||||
let key_bytes = [42u8; 32];
|
||||
EncryptionKey::new(key_bytes, CURRENT_KEY_VERSION)
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_encrypt_decrypt_round_trip() {
|
||||
let key = make_test_key();
|
||||
let plaintext = "hello, world! this is a secret API key";
|
||||
|
||||
let encrypted = encrypt(plaintext, &key).unwrap();
|
||||
let decrypted = decrypt(&encrypted, &key).unwrap();
|
||||
|
||||
assert_eq!(decrypted, plaintext);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_encrypted_data_has_different_iv_each_time() {
|
||||
let key = make_test_key();
|
||||
let plaintext = "same input";
|
||||
|
||||
let encrypted1 = encrypt(plaintext, &key).unwrap();
|
||||
let encrypted2 = encrypt(plaintext, &key).unwrap();
|
||||
|
||||
// Same plaintext encrypted twice should have different IVs and ciphertexts
|
||||
assert_ne!(encrypted1.iv, encrypted2.iv);
|
||||
assert_ne!(encrypted1.data, encrypted2.data);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_encrypt_decrypt_with_key_version() {
|
||||
let key = EncryptionKey::new([7u8; 32], 2);
|
||||
let plaintext = "versioned encryption test";
|
||||
|
||||
let encrypted = encrypt(plaintext, &key).unwrap();
|
||||
assert_eq!(encrypted.key_version, 2);
|
||||
|
||||
let decrypted = decrypt(&encrypted, &key).unwrap();
|
||||
assert_eq!(decrypted, plaintext);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_decrypt_with_wrong_key_fails() {
|
||||
let key1 = EncryptionKey::new([1u8; 32], 1);
|
||||
let key2 = EncryptionKey::new([2u8; 32], 1);
|
||||
|
||||
let encrypted = encrypt("secret stuff", &key1).unwrap();
|
||||
let result = decrypt(&encrypted, &key2);
|
||||
assert!(result.is_err());
|
||||
}
|
||||
}
|
||||
246
crates/alknet-vault/src/ethereum.rs
Normal file
246
crates/alknet-vault/src/ethereum.rs
Normal file
@@ -0,0 +1,246 @@
|
||||
//! BIP-0032 secp256k1 HD key derivation for Ethereum keys.
|
||||
//!
|
||||
//! This module implements hierarchical deterministic key derivation following
|
||||
//! BIP-0032 for secp256k1 curves. It is gated behind the `secp256k1` feature flag.
|
||||
//!
|
||||
//! Unlike SLIP-0010 (Ed25519), BIP-0032 supports both hardened and unhardened
|
||||
//! child derivation and uses HMAC-SHA512 with the key "Bitcoin seed" (not
|
||||
//! "ed25519 seed").
|
||||
//!
|
||||
//! # Ethereum Path
|
||||
//!
|
||||
//! The standard Ethereum derivation path is `m/44'/60'/0'/0/0` (EIP-84).
|
||||
//! The last two indices (`0/0`) are unhardened, which SLIP-0010 cannot handle.
|
||||
|
||||
use hmac::{Hmac, Mac};
|
||||
use secp256k1::{PublicKey, Secp256k1, SecretKey};
|
||||
use sha2::Sha512;
|
||||
use zeroize::Zeroize;
|
||||
|
||||
use crate::derivation::{parse_derivation_path, DerivationError};
|
||||
|
||||
type HmacSha512 = Hmac<Sha512>;
|
||||
|
||||
const HARDENED_OFFSET: u32 = 0x80000000;
|
||||
|
||||
/// An extended private key for BIP-0032 secp256k1 derivation.
|
||||
///
|
||||
/// Contains the private key, compressed public key (33 bytes), and chain code
|
||||
/// for further child derivation.
|
||||
#[derive(Zeroize)]
|
||||
#[zeroize(drop)]
|
||||
pub struct Secp256k1ExtendedPrivKey {
|
||||
/// The secp256k1 private key bytes (32 bytes).
|
||||
#[zeroize]
|
||||
private_key: Vec<u8>,
|
||||
/// The compressed public key bytes (33 bytes).
|
||||
public_key: Vec<u8>,
|
||||
/// The chain code for child derivation (32 bytes).
|
||||
chain_code: Vec<u8>,
|
||||
}
|
||||
|
||||
impl Secp256k1ExtendedPrivKey {
|
||||
/// Returns the private key bytes (32 bytes).
|
||||
pub fn private_key(&self) -> &[u8] {
|
||||
&self.private_key
|
||||
}
|
||||
|
||||
/// Returns the compressed public key bytes (33 bytes).
|
||||
pub fn public_key(&self) -> &[u8] {
|
||||
&self.public_key
|
||||
}
|
||||
|
||||
/// Returns the chain code bytes (32 bytes).
|
||||
pub fn chain_code(&self) -> &[u8] {
|
||||
&self.chain_code
|
||||
}
|
||||
}
|
||||
|
||||
/// Derive the BIP-0032 secp256k1 master key from a seed.
|
||||
///
|
||||
/// Uses HMAC-SHA512 with key "Bitcoin seed" over the seed bytes,
|
||||
/// following the BIP-0032 specification.
|
||||
pub fn derive_secp256k1_master_key(
|
||||
seed: &[u8],
|
||||
) -> Result<Secp256k1ExtendedPrivKey, DerivationError> {
|
||||
let mut mac = HmacSha512::new_from_slice(b"Bitcoin seed")
|
||||
.map_err(|e| DerivationError::Hmac(e.to_string()))?;
|
||||
mac.update(seed);
|
||||
let result = mac.finalize().into_bytes();
|
||||
|
||||
let private_key_bytes = &result[..32];
|
||||
let chain_code_bytes = &result[32..];
|
||||
|
||||
let secp = Secp256k1::new();
|
||||
let secret_key = SecretKey::from_slice(private_key_bytes)
|
||||
.map_err(|e| DerivationError::Secp256k1(e.to_string()))?;
|
||||
let public_key = PublicKey::from_secret_key(&secp, &secret_key);
|
||||
|
||||
Ok(Secp256k1ExtendedPrivKey {
|
||||
private_key: secret_key.secret_bytes().to_vec(),
|
||||
public_key: public_key.serialize().to_vec(),
|
||||
chain_code: chain_code_bytes.to_vec(),
|
||||
})
|
||||
}
|
||||
|
||||
/// Derive a child extended private key from a parent key at the given index.
|
||||
///
|
||||
/// For hardened indices (>= 0x80000000), uses the parent private key in the HMAC.
|
||||
/// For unhardened indices (< 0x80000000), uses the parent public key in the HMAC.
|
||||
fn derive_child(
|
||||
parent: &Secp256k1ExtendedPrivKey,
|
||||
index: u32,
|
||||
) -> Result<Secp256k1ExtendedPrivKey, DerivationError> {
|
||||
let secp = Secp256k1::new();
|
||||
|
||||
let mut mac = HmacSha512::new_from_slice(parent.chain_code())
|
||||
.map_err(|e| DerivationError::Hmac(e.to_string()))?;
|
||||
|
||||
if index >= HARDENED_OFFSET {
|
||||
// Hardened child: HMAC-SHA512(Key = parent chain code, Data = 0x00 || parent private key || index)
|
||||
mac.update(&[0x00]);
|
||||
mac.update(parent.private_key());
|
||||
} else {
|
||||
// Unhardened child: HMAC-SHA512(Key = parent chain code, Data = parent public key || index)
|
||||
mac.update(parent.public_key());
|
||||
}
|
||||
mac.update(&index.to_be_bytes());
|
||||
|
||||
let result = mac.finalize().into_bytes();
|
||||
let child_key_bytes = &result[..32];
|
||||
let child_chain_code = &result[32..];
|
||||
|
||||
// Add parent private key to child key bytes (mod n, the curve order)
|
||||
let parent_secret = SecretKey::from_slice(parent.private_key())
|
||||
.map_err(|e| DerivationError::Secp256k1(e.to_string()))?;
|
||||
let child_key_raw = SecretKey::from_slice(child_key_bytes)
|
||||
.map_err(|e| DerivationError::Secp256k1(e.to_string()))?;
|
||||
|
||||
// Tweak: child_key = (parent_key + tweak) mod n
|
||||
let child_secret = parent_secret
|
||||
.add_tweak(&child_key_raw.into())
|
||||
.map_err(|e| DerivationError::Secp256k1(e.to_string()))?;
|
||||
|
||||
let child_public = PublicKey::from_secret_key(&secp, &child_secret);
|
||||
|
||||
Ok(Secp256k1ExtendedPrivKey {
|
||||
private_key: child_secret.secret_bytes().to_vec(),
|
||||
public_key: child_public.serialize().to_vec(),
|
||||
chain_code: child_chain_code.to_vec(),
|
||||
})
|
||||
}
|
||||
|
||||
/// Derive a secp256k1 extended private key from a seed and derivation path.
|
||||
///
|
||||
/// This is the primary entry point for BIP-0032 secp256k1 derivation.
|
||||
/// Supports both hardened and unhardened indices.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```ignore
|
||||
/// use alknet_vault::ethereum::derive_secp256k1_path;
|
||||
/// use alknet_vault::derivation::PATHS;
|
||||
///
|
||||
/// let key = derive_secp256k1_path(seed, PATHS::ETHEREUM).unwrap();
|
||||
/// assert_eq!(key.private_key().len(), 32);
|
||||
/// assert_eq!(key.public_key().len(), 33); // compressed
|
||||
/// ```
|
||||
pub fn derive_secp256k1_path(
|
||||
seed: &[u8],
|
||||
path: &str,
|
||||
) -> Result<Secp256k1ExtendedPrivKey, DerivationError> {
|
||||
let indices = parse_derivation_path(path)?;
|
||||
let master = derive_secp256k1_master_key(seed)?;
|
||||
|
||||
let mut current = master;
|
||||
for index in indices {
|
||||
current = derive_child(¤t, index)?;
|
||||
}
|
||||
|
||||
Ok(current)
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::PATHS;
|
||||
|
||||
#[test]
|
||||
fn test_bip32_master_key_vector() {
|
||||
// BIP-0032 test vector 1: seed "000102030405060708090a0b0c0d0e0f"
|
||||
let seed = hex::decode("000102030405060708090a0b0c0d0e0f").unwrap();
|
||||
let master = derive_secp256k1_master_key(&seed).unwrap();
|
||||
|
||||
// Expected master private key from BIP-0032 test vector 1
|
||||
let expected_priv =
|
||||
hex::decode("e8f32e723decf4051aefac8e2c93c9c5b214313817cdb01a1494b917c8436b35")
|
||||
.unwrap();
|
||||
assert_eq!(master.private_key(), expected_priv.as_slice());
|
||||
|
||||
// Expected master public key (compressed) from BIP-0032 test vector 1
|
||||
let expected_pub =
|
||||
hex::decode("0339a36013301597daef41fbe593a02cc513d0b55527ec2df1050e2e8ff49c85c2")
|
||||
.unwrap();
|
||||
assert_eq!(master.public_key(), expected_pub.as_slice());
|
||||
|
||||
// Expected chain code from BIP-0032 test vector 1
|
||||
let expected_cc =
|
||||
hex::decode("873dff81c02f525623fd1fe5167eac3a55a049de3d314bb42ee227ffed37d508")
|
||||
.unwrap();
|
||||
assert_eq!(master.chain_code(), expected_cc.as_slice());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_bip32_derive_m_44h_60h_0h_0_0() {
|
||||
let seed = hex::decode("000102030405060708090a0b0c0d0e0f").unwrap();
|
||||
let key = derive_secp256k1_path(&seed, "m/44'/60'/0'/0/0").unwrap();
|
||||
assert_eq!(key.private_key().len(), 32);
|
||||
assert_eq!(key.public_key().len(), 33);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_ethereum_keypair_is_valid() {
|
||||
let mnemonic = crate::mnemonic::Mnemonic::generate(24).unwrap();
|
||||
let seed = mnemonic.to_seed(None);
|
||||
let key = derive_secp256k1_path(seed.as_bytes(), PATHS::ETHEREUM).unwrap();
|
||||
|
||||
let secp = Secp256k1::new();
|
||||
let secret_key = SecretKey::from_slice(key.private_key()).unwrap();
|
||||
let public_key = PublicKey::from_secret_key(&secp, &secret_key);
|
||||
assert_eq!(key.public_key(), public_key.serialize().as_slice());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_ethereum_differs_from_ed25519() {
|
||||
let mnemonic = crate::mnemonic::Mnemonic::generate(24).unwrap();
|
||||
let seed = mnemonic.to_seed(None);
|
||||
|
||||
let eth_key = derive_secp256k1_path(seed.as_bytes(), PATHS::ETHEREUM).unwrap();
|
||||
let ed_key =
|
||||
crate::derivation::derive_path_from_seed(seed.as_bytes(), PATHS::ETHEREUM).unwrap();
|
||||
|
||||
assert_ne!(eth_key.private_key(), ed_key.private_key());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_deterministic_derivation() {
|
||||
let mnemonic = crate::mnemonic::Mnemonic::generate(24).unwrap();
|
||||
let seed = mnemonic.to_seed(None);
|
||||
|
||||
let key1 = derive_secp256k1_path(seed.as_bytes(), PATHS::ETHEREUM).unwrap();
|
||||
let key2 = derive_secp256k1_path(seed.as_bytes(), PATHS::ETHEREUM).unwrap();
|
||||
|
||||
assert_eq!(key1.private_key(), key2.private_key());
|
||||
assert_eq!(key1.public_key(), key2.public_key());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_compressed_public_key_is_33_bytes() {
|
||||
let mnemonic = crate::mnemonic::Mnemonic::generate(24).unwrap();
|
||||
let seed = mnemonic.to_seed(None);
|
||||
let key = derive_secp256k1_path(seed.as_bytes(), PATHS::ETHEREUM).unwrap();
|
||||
assert_eq!(key.public_key().len(), 33);
|
||||
// Compressed public key starts with 0x02 or 0x03
|
||||
assert!(key.public_key()[0] == 0x02 || key.public_key()[0] == 0x03);
|
||||
}
|
||||
}
|
||||
48
crates/alknet-vault/src/lib.rs
Normal file
48
crates/alknet-vault/src/lib.rs
Normal file
@@ -0,0 +1,48 @@
|
||||
//! # alknet-vault
|
||||
//!
|
||||
//! Local key vault: BIP39 mnemonic generation, SLIP-0010 Ed25519 HD key derivation,
|
||||
//! AES-256-GCM encryption for securing provider keys, credentials, and identity material.
|
||||
//!
|
||||
//! This crate is the only component that holds the master seed phrase. The CLI binary
|
||||
//! unlocks the vault at startup and injects derived/decrypted material into operation
|
||||
//! contexts. Other crates never access the vault directly — they receive keys through
|
||||
//! their operation context or via the call protocol.
|
||||
//!
|
||||
//! ## Crate Independence
|
||||
//!
|
||||
//! alknet-vault does **not** depend on alknet-core or any other alknet crate. It is
|
||||
//! fully independent and usable in contexts where QUIC networking doesn't exist (CLI
|
||||
//! tools, test harnesses, WASM key derivation).
|
||||
//!
|
||||
//! ## Security Model
|
||||
//!
|
||||
//! The seed phrase is never persisted to disk. It is entered at startup or via
|
||||
//! `Unlock` and held only in `Zeroize`-protected RAM (ADR-038). `Lock` purges
|
||||
//! the seed and all cached derived keys.
|
||||
//!
|
||||
//! ## Module Organization
|
||||
//!
|
||||
//! - [`mnemonic`] — BIP39 mnemonic generation, validation, and seed derivation
|
||||
//! - [`derivation`] — SLIP-0010 Ed25519 HD key derivation and path constants
|
||||
//! - [`encryption`] — AES-256-GCM encrypt/decrypt and `EncryptedData` type
|
||||
//! - [`protocol`] — `VaultProtocol` irpc message enum, `DerivedKey`, `KeyType`
|
||||
//! - [`service`] — `VaultService` implementation with Unlock/Lock lifecycle
|
||||
//! - [`ethereum`] — BIP-0032 secp256k1 HD key derivation (behind `secp256k1` feature)
|
||||
|
||||
pub mod cache;
|
||||
pub mod derivation;
|
||||
pub mod encryption;
|
||||
pub mod mnemonic;
|
||||
pub mod protocol;
|
||||
pub mod service;
|
||||
|
||||
#[cfg(feature = "secp256k1")]
|
||||
pub mod ethereum;
|
||||
|
||||
// Re-export primary public API
|
||||
pub use cache::CacheConfig;
|
||||
pub use derivation::{DerivationError, ExtendedPrivKey, PATHS};
|
||||
pub use encryption::{EncryptedData, EncryptionError};
|
||||
pub use mnemonic::{Language, Mnemonic, Seed};
|
||||
pub use protocol::{DerivedKey, KeyType, VaultMessage, VaultProtocol};
|
||||
pub use service::{VaultService, VaultServiceActor, VaultServiceError, VaultServiceHandle};
|
||||
161
crates/alknet-vault/src/mnemonic.rs
Normal file
161
crates/alknet-vault/src/mnemonic.rs
Normal file
@@ -0,0 +1,161 @@
|
||||
//! BIP39 mnemonic generation, validation, and seed derivation.
|
||||
//!
|
||||
//! This module handles the root of trust: the BIP39 mnemonic seed phrase. From
|
||||
//! a single mnemonic, all self-generated secrets can be derived on demand.
|
||||
//!
|
||||
//! # Security
|
||||
//!
|
||||
//! Seed material is protected with `Zeroize` to ensure it is overwritten in
|
||||
//! memory before deallocation (ADR-038). The seed is never written to disk.
|
||||
|
||||
use bip39::Mnemonic as Bip39Mnemonic;
|
||||
use zeroize::Zeroize;
|
||||
|
||||
/// BIP39 word list language.
|
||||
///
|
||||
/// Currently only English is supported, matching the BIP39 reference
|
||||
/// implementation and the vast majority of wallet software.
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum Language {
|
||||
English,
|
||||
}
|
||||
|
||||
impl From<Language> for bip39::Language {
|
||||
fn from(lang: Language) -> Self {
|
||||
match lang {
|
||||
Language::English => bip39::Language::English,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// A BIP39 mnemonic seed phrase.
|
||||
///
|
||||
/// Wraps the `bip39` crate's `Mnemonic` type and provides seed derivation.
|
||||
/// The internal phrase is zeroized on drop.
|
||||
#[derive(Debug)]
|
||||
pub struct Mnemonic {
|
||||
phrase: String,
|
||||
}
|
||||
|
||||
impl Mnemonic {
|
||||
/// Generate a new random mnemonic with the given word count.
|
||||
///
|
||||
/// Supported word counts: 12, 15, 18, 21, 24.
|
||||
pub fn generate(word_count: usize) -> Result<Self, MnemonicError> {
|
||||
let mnemonic: Bip39Mnemonic = Bip39Mnemonic::generate(word_count)
|
||||
.map_err(|e: bip39::Error| MnemonicError::Generation(e.to_string()))?;
|
||||
Ok(Self {
|
||||
phrase: mnemonic.to_string(),
|
||||
})
|
||||
}
|
||||
|
||||
/// Create a mnemonic from an existing phrase string.
|
||||
///
|
||||
/// Validates the phrase against the BIP39 word list and checksum.
|
||||
pub fn from_phrase(phrase: &str, _language: Language) -> Result<Self, MnemonicError> {
|
||||
let mnemonic: Bip39Mnemonic = Bip39Mnemonic::parse_normalized(phrase)
|
||||
.map_err(|e: bip39::Error| MnemonicError::InvalidPhrase(e.to_string()))?;
|
||||
Ok(Self {
|
||||
phrase: mnemonic.to_string(),
|
||||
})
|
||||
}
|
||||
|
||||
/// Derive the master seed from this mnemonic.
|
||||
///
|
||||
/// The optional passphrase is used as the BIP39 password for PBKDF2
|
||||
/// key derivation (BIP39 standard). An empty string means no passphrase.
|
||||
pub fn to_seed(&self, passphrase: Option<&str>) -> Seed {
|
||||
let mnemonic = Bip39Mnemonic::parse_normalized(&self.phrase).unwrap();
|
||||
let normalized_passphrase = passphrase.unwrap_or("");
|
||||
let seed_bytes = mnemonic.to_seed_normalized(normalized_passphrase);
|
||||
Seed {
|
||||
bytes: seed_bytes.to_vec(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns the mnemonic phrase as a string.
|
||||
///
|
||||
/// Handle with care — this is the root of trust for all derived keys.
|
||||
pub fn phrase(&self) -> &str {
|
||||
&self.phrase
|
||||
}
|
||||
}
|
||||
|
||||
impl Zeroize for Mnemonic {
|
||||
fn zeroize(&mut self) {
|
||||
self.phrase.zeroize();
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for Mnemonic {
|
||||
fn drop(&mut self) {
|
||||
self.zeroize();
|
||||
}
|
||||
}
|
||||
|
||||
/// A BIP39-derived master seed.
|
||||
///
|
||||
/// Contains the 64-byte seed material from which all HD keys are derived.
|
||||
/// Zeroized on drop per ADR-038.
|
||||
#[derive(Clone, Zeroize)]
|
||||
#[zeroize(drop)]
|
||||
pub struct Seed {
|
||||
bytes: Vec<u8>,
|
||||
}
|
||||
|
||||
impl Seed {
|
||||
/// Returns the seed bytes.
|
||||
///
|
||||
/// These bytes are the input to SLIP-0010 master key derivation.
|
||||
pub fn as_bytes(&self) -> &[u8] {
|
||||
&self.bytes
|
||||
}
|
||||
|
||||
/// Returns the length of the seed (always 64 bytes for BIP39).
|
||||
pub fn len(&self) -> usize {
|
||||
self.bytes.len()
|
||||
}
|
||||
|
||||
/// Returns whether the seed is empty.
|
||||
#[must_use]
|
||||
pub fn is_empty(&self) -> bool {
|
||||
self.bytes.is_empty()
|
||||
}
|
||||
}
|
||||
|
||||
/// Errors that can occur during mnemonic operations.
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
pub enum MnemonicError {
|
||||
#[error("failed to generate mnemonic: {0}")]
|
||||
Generation(String),
|
||||
#[error("invalid mnemonic phrase: {0}")]
|
||||
InvalidPhrase(String),
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_generate_mnemonic_24_words() {
|
||||
let mnemonic = Mnemonic::generate(24).unwrap();
|
||||
let words: Vec<&str> = mnemonic.phrase().split_whitespace().collect();
|
||||
assert_eq!(words.len(), 24);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_mnemonic_round_trip() {
|
||||
let original = Mnemonic::generate(12).unwrap();
|
||||
let phrase = original.phrase().to_string();
|
||||
let restored = Mnemonic::from_phrase(&phrase, Language::English).unwrap();
|
||||
assert_eq!(original.phrase(), restored.phrase());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_seed_derivation() {
|
||||
let mnemonic = Mnemonic::generate(24).unwrap();
|
||||
let seed = mnemonic.to_seed(None);
|
||||
assert_eq!(seed.len(), 64);
|
||||
assert!(!seed.is_empty());
|
||||
}
|
||||
}
|
||||
310
crates/alknet-vault/src/protocol.rs
Normal file
310
crates/alknet-vault/src/protocol.rs
Normal file
@@ -0,0 +1,310 @@
|
||||
//! VaultProtocol irpc message definition and associated types.
|
||||
//!
|
||||
//! This module defines the `VaultProtocol` enum for irpc-based message dispatch.
|
||||
//! The protocol supports unlock/lock lifecycle, key derivation,
|
||||
//! and encryption/decryption operations.
|
||||
//!
|
||||
//! # Protocol Operation
|
||||
//!
|
||||
//! The VaultProtocol follows a lifecycle: the vault starts in a **locked**
|
||||
//! state where no derivation or encryption operations are possible. The `Unlock`
|
||||
//! call loads the seed into memory (derived from the mnemonic passphrase). After
|
||||
//! that, derive and encrypt/decrypt operations are available. The `Lock` call
|
||||
//! purges the seed and all cached keys.
|
||||
//!
|
||||
//! # Wire Format
|
||||
//!
|
||||
//! For local (in-process) calls, the protocol uses tokio channels directly.
|
||||
//! For remote (in-cluster) calls, the protocol is serialized with postcard.
|
||||
//! For cross-node (call protocol) exposure, the vault is wrapped in an
|
||||
//! operation that serializes to JSON.
|
||||
|
||||
use std::fmt;
|
||||
|
||||
use irpc::rpc_requests;
|
||||
use serde::{Deserialize, Deserializer, Serialize, Serializer};
|
||||
use zeroize::Zeroize;
|
||||
|
||||
use crate::encryption::EncryptedData;
|
||||
|
||||
/// The type of a derived key.
|
||||
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
|
||||
pub enum KeyType {
|
||||
/// Ed25519 keypair (SLIP-0010 derivation).
|
||||
Ed25519,
|
||||
/// AES-256-GCM symmetric key (derived from seed, used for external credential encryption).
|
||||
Aes256Gcm,
|
||||
/// secp256k1 keypair (BIP-0032 derivation, for Ethereum signing).
|
||||
Secp256k1,
|
||||
}
|
||||
|
||||
/// A derived key pair (private key + public key).
|
||||
///
|
||||
/// The private key is sensitive material that is zeroized on drop (ADR-038).
|
||||
/// This type is **not** `Clone` — it is move-only. Consumers receive a
|
||||
/// `DerivedKey` by value and must zeroize it when done (handled automatically
|
||||
/// by `#[zeroize(drop)]`).
|
||||
///
|
||||
/// Serialization redacts the `private_key` field for human-readable formats
|
||||
/// (JSON) for safety, showing `"[REDACTED]"` instead of the key bytes. For
|
||||
/// binary formats (postcard, used by irpc), the actual bytes are serialized
|
||||
/// so that remote communication works correctly. Deserialization always reads
|
||||
/// the full bytes.
|
||||
#[derive(Zeroize, Deserialize)]
|
||||
#[zeroize(drop)]
|
||||
pub struct DerivedKey {
|
||||
/// The type of key that was derived.
|
||||
#[zeroize(skip)]
|
||||
pub key_type: KeyType,
|
||||
/// The private key bytes (sensitive — zeroized on drop).
|
||||
#[zeroize]
|
||||
#[serde(deserialize_with = "deserialize_private_key")]
|
||||
pub private_key: Vec<u8>,
|
||||
/// The public key bytes.
|
||||
#[zeroize(skip)]
|
||||
pub public_key: Vec<u8>,
|
||||
}
|
||||
|
||||
fn deserialize_private_key<'de, D: Deserializer<'de>>(d: D) -> Result<Vec<u8>, D::Error> {
|
||||
Vec::<u8>::deserialize(d)
|
||||
}
|
||||
|
||||
impl fmt::Debug for DerivedKey {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
f.debug_struct("DerivedKey")
|
||||
.field("key_type", &self.key_type)
|
||||
.field("private_key", &"[REDACTED]")
|
||||
.field("public_key", &self.public_key)
|
||||
.finish()
|
||||
}
|
||||
}
|
||||
|
||||
impl Serialize for DerivedKey {
|
||||
fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
|
||||
use serde::ser::SerializeStruct;
|
||||
if s.is_human_readable() {
|
||||
let mut state = s.serialize_struct("DerivedKey", 3)?;
|
||||
state.serialize_field("key_type", &self.key_type)?;
|
||||
state.serialize_field("private_key", "[REDACTED]")?;
|
||||
state.serialize_field("public_key", &self.public_key)?;
|
||||
state.end()
|
||||
} else {
|
||||
let mut state = s.serialize_struct("DerivedKey", 3)?;
|
||||
state.serialize_field("key_type", &self.key_type)?;
|
||||
state.serialize_field("private_key", &self.private_key)?;
|
||||
state.serialize_field("public_key", &self.public_key)?;
|
||||
state.end()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// VaultProtocol message definition.
|
||||
///
|
||||
/// This is the irpc protocol enum that defines all vault operations.
|
||||
/// The `#[rpc_requests]` macro generates:
|
||||
/// - **`VaultMessage`**: message enum with `WithChannels` wrappers for each variant
|
||||
/// - **`Channels<VaultProtocol>`** impls for each wrapper type
|
||||
/// - **`From`** impls for protocol enum and message enum conversions
|
||||
/// - **`Service`** and **`RemoteService`** trait impls for remote dispatch
|
||||
///
|
||||
/// # State Requirements
|
||||
///
|
||||
/// All operations except `Unlock` require the vault to be in an **unlocked**
|
||||
/// state. Calling derive/encrypt/decrypt on a locked vault returns an error.
|
||||
#[rpc_requests(message = VaultMessage, no_spans)]
|
||||
#[derive(Debug, Serialize, Deserialize)]
|
||||
pub enum VaultProtocol {
|
||||
/// Derive an Ed25519 keypair at the given path.
|
||||
///
|
||||
/// Path format: `m/74'/0'/0'/0'` (SLIP-0010 hardened-only notation).
|
||||
/// Returns a `DerivedKey` with `KeyType::Ed25519`.
|
||||
#[rpc(tx = irpc::channel::oneshot::Sender<Result<DerivedKey, crate::service::VaultServiceError>>)]
|
||||
#[wrap(DeriveEd25519)]
|
||||
DeriveEd25519 {
|
||||
/// SLIP-0010 derivation path (e.g., "m/74'/0'/0'/0'").
|
||||
path: String,
|
||||
},
|
||||
|
||||
/// Derive an AES-256-GCM encryption key at the given path.
|
||||
///
|
||||
/// The default encryption path is `m/74'/2'/0'/0'`.
|
||||
/// Returns a `DerivedKey` with `KeyType::Aes256Gcm`.
|
||||
#[rpc(tx = irpc::channel::oneshot::Sender<Result<DerivedKey, crate::service::VaultServiceError>>)]
|
||||
#[wrap(DeriveEncryptionKey)]
|
||||
DeriveEncryptionKey {
|
||||
/// SLIP-0010 derivation path for the encryption key.
|
||||
path: String,
|
||||
},
|
||||
|
||||
/// Derive a secp256k1 (Ethereum) keypair at the given path.
|
||||
///
|
||||
/// The default Ethereum path is `m/44'/60'/0'/0/0`.
|
||||
/// Returns a `DerivedKey` with `KeyType::Secp256k1`.
|
||||
#[rpc(tx = irpc::channel::oneshot::Sender<Result<DerivedKey, crate::service::VaultServiceError>>)]
|
||||
#[wrap(DeriveEthereumKey)]
|
||||
DeriveEthereumKey {
|
||||
/// BIP-0032 derivation path (e.g., "m/44'/60'/0'/0/0").
|
||||
path: String,
|
||||
},
|
||||
|
||||
/// Derive a deterministic password at the given path.
|
||||
///
|
||||
/// Path format: `m/74'/1'/0'/{hash}'` (SLIP-0010 hardened notation).
|
||||
/// The `length` parameter controls the output length.
|
||||
#[rpc(tx = irpc::channel::oneshot::Sender<Result<Vec<u8>, crate::service::VaultServiceError>>)]
|
||||
#[wrap(DerivePassword)]
|
||||
DerivePassword {
|
||||
/// SLIP-0010 derivation path for the password.
|
||||
path: String,
|
||||
/// Desired password length in bytes.
|
||||
length: usize,
|
||||
},
|
||||
|
||||
/// Encrypt plaintext using a derived encryption key.
|
||||
///
|
||||
/// The key is derived at the path `m/74'/2'/0'/0'` with the given version.
|
||||
/// Returns an `EncryptedData` blob suitable for storage.
|
||||
#[rpc(tx = irpc::channel::oneshot::Sender<Result<EncryptedData, crate::service::VaultServiceError>>)]
|
||||
#[wrap(Encrypt)]
|
||||
Encrypt {
|
||||
/// The plaintext string to encrypt.
|
||||
plaintext: String,
|
||||
/// The key version for rotation tracking.
|
||||
key_version: u32,
|
||||
},
|
||||
|
||||
/// Decrypt an `EncryptedData` blob back to plaintext.
|
||||
///
|
||||
/// The key is derived from the seed at the path indicated by the key version.
|
||||
#[rpc(tx = irpc::channel::oneshot::Sender<Result<String, crate::service::VaultServiceError>>)]
|
||||
#[wrap(Decrypt)]
|
||||
Decrypt {
|
||||
/// The encrypted data blob to decrypt.
|
||||
encrypted: EncryptedData,
|
||||
},
|
||||
|
||||
/// Lock the service, purging the seed and all cached derived keys.
|
||||
///
|
||||
/// After locking, no derive/encrypt/decrypt operations are possible
|
||||
/// until `Unlock` is called again. Calls `zeroize()` on all sensitive
|
||||
/// material (ADR-038).
|
||||
#[rpc(tx = irpc::channel::oneshot::Sender<Result<(), crate::service::VaultServiceError>>)]
|
||||
#[wrap(Lock)]
|
||||
Lock,
|
||||
|
||||
/// Unlock the service with a BIP39 mnemonic and optional passphrase.
|
||||
///
|
||||
/// The mnemonic is the space-separated BIP39 word list. The passphrase is
|
||||
/// the optional BIP39 password extension (the "25th word"). After unlocking,
|
||||
/// derive and encrypt/decrypt operations are available.
|
||||
#[rpc(tx = irpc::channel::oneshot::Sender<Result<(), crate::service::VaultServiceError>>)]
|
||||
#[wrap(Unlock)]
|
||||
Unlock {
|
||||
/// The BIP39 mnemonic phrase (space-separated word list).
|
||||
mnemonic: String,
|
||||
/// Optional BIP39 passphrase (the "25th word" password extension).
|
||||
passphrase: Option<String>,
|
||||
},
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
fn make_test_key() -> DerivedKey {
|
||||
DerivedKey {
|
||||
key_type: KeyType::Ed25519,
|
||||
private_key: vec![0xABu8; 32],
|
||||
public_key: vec![0xCDu8; 32],
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_derived_key_debug_redacts_private_key() {
|
||||
let key = make_test_key();
|
||||
let debug_output = format!("{:?}", key);
|
||||
assert!(
|
||||
!debug_output.contains("AB"),
|
||||
"Debug must not leak private_key bytes"
|
||||
);
|
||||
assert!(
|
||||
debug_output.contains("[REDACTED]"),
|
||||
"Debug must show [REDACTED] for private_key"
|
||||
);
|
||||
assert!(debug_output.contains("Ed25519"), "Debug must show key_type");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_derived_key_serialize_redacts_private_key_json() {
|
||||
let key = make_test_key();
|
||||
let json = serde_json::to_string(&key).unwrap();
|
||||
assert!(
|
||||
!json.contains("AB"),
|
||||
"JSON must not contain private_key bytes"
|
||||
);
|
||||
assert!(
|
||||
json.contains("[REDACTED]"),
|
||||
"JSON must show [REDACTED] for private_key"
|
||||
);
|
||||
assert!(json.contains("Ed25519"), "JSON must contain key_type");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_derived_key_serialize_preserves_bytes_postcard() {
|
||||
let key = make_test_key();
|
||||
let bytes = postcard::to_allocvec(&key).unwrap();
|
||||
let restored: DerivedKey = postcard::from_bytes(&bytes).unwrap();
|
||||
assert_eq!(
|
||||
restored.private_key,
|
||||
vec![0xABu8; 32],
|
||||
"postcard must preserve private_key bytes"
|
||||
);
|
||||
assert_eq!(
|
||||
restored.public_key,
|
||||
vec![0xCDu8; 32],
|
||||
"postcard must preserve public_key bytes"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_derived_key_deserialize_preserves_bytes() {
|
||||
let key = make_test_key();
|
||||
let bytes = postcard::to_allocvec(&key.private_key).unwrap();
|
||||
let restored: Vec<u8> = postcard::from_bytes(&bytes).unwrap();
|
||||
assert_eq!(
|
||||
restored,
|
||||
vec![0xABu8; 32],
|
||||
"Deserialization must preserve private_key bytes"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_derived_key_zeroize_on_drop() {
|
||||
let key = DerivedKey {
|
||||
key_type: KeyType::Aes256Gcm,
|
||||
private_key: vec![0xFFu8; 32],
|
||||
public_key: vec![0x00u8; 32],
|
||||
};
|
||||
drop(key);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_derived_key_not_clone() {
|
||||
let key = make_test_key();
|
||||
let _moved = key;
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_derived_key_zeroize_method_overwrites_private_key() {
|
||||
let mut key = make_test_key();
|
||||
assert_ne!(key.private_key, vec![0u8; 32]);
|
||||
assert!(!key.private_key.is_empty());
|
||||
|
||||
key.zeroize();
|
||||
|
||||
assert!(
|
||||
key.private_key.is_empty(),
|
||||
"zeroize() must clear the private_key Vec"
|
||||
);
|
||||
}
|
||||
}
|
||||
972
crates/alknet-vault/src/service.rs
Normal file
972
crates/alknet-vault/src/service.rs
Normal file
@@ -0,0 +1,972 @@
|
||||
//! VaultService implementation with Unlock/Lock lifecycle.
|
||||
//!
|
||||
//! The `VaultService` is the primary runtime interface for key management.
|
||||
//! It holds the master seed in `Zeroize`-protected memory and provides methods
|
||||
//! for the Unlock/Lock lifecycle, key derivation, and encryption/decryption.
|
||||
//!
|
||||
//! # Lifecycle
|
||||
//!
|
||||
//! ```text
|
||||
//! Unlock(passphrase)
|
||||
//! → validate mnemonic (if restoring) or generate new
|
||||
//! → derive master key from seed
|
||||
//! → store seed in SeedHolder (Zeroize-protected)
|
||||
//! → cache empty (keys derived on demand)
|
||||
//!
|
||||
//! DeriveEd25519/DeriveEncryptionKey/Encrypt/Decrypt
|
||||
//! → require unlocked state (VaultLocked error if locked)
|
||||
//! → derive key, return result
|
||||
//! → optionally cache derived key
|
||||
//!
|
||||
//! Lock
|
||||
//! → zeroize all cached derived keys
|
||||
//! → zeroize seed
|
||||
//! → drop all sensitive material
|
||||
//! → vault returns to locked state
|
||||
//! ```
|
||||
//!
|
||||
//! # Dispatch Paths
|
||||
//!
|
||||
//! There are two ways to interact with the vault:
|
||||
//!
|
||||
//! 1. **Local (in-process)**: `VaultServiceHandle` wraps `VaultServiceInner`
|
||||
//! behind `Arc<RwLock<>>` and provides direct method calls without serialization.
|
||||
//! 2. **Remote (in-cluster)**: `VaultServiceActor` processes `VaultMessage`
|
||||
//! variants from an mpsc channel and dispatches to the handle methods.
|
||||
//!
|
||||
//! # Assembly
|
||||
//!
|
||||
//! The `VaultService` is assembled by the CLI binary. The CLI unlocks the vault
|
||||
//! at startup and injects derived/decrypted material into operation contexts.
|
||||
//! No handler crate accesses the vault directly — they receive keys through
|
||||
//! their operation context or via the call protocol.
|
||||
|
||||
use std::sync::{Arc, RwLock};
|
||||
|
||||
use base64::engine::general_purpose::URL_SAFE_NO_PAD;
|
||||
use base64::Engine;
|
||||
use irpc::WithChannels;
|
||||
use serde::{Deserialize, Serialize};
|
||||
|
||||
use crate::cache::{CacheConfig, CachedKey, KeyCache};
|
||||
use crate::derivation::{self, DerivationError, PATHS};
|
||||
use crate::encryption::{self, EncryptedData, EncryptionKey};
|
||||
use crate::mnemonic::{Language, Mnemonic, Seed};
|
||||
use crate::protocol::{
|
||||
Decrypt, DeriveEd25519, DeriveEncryptionKey, DeriveEthereumKey, DerivePassword, Encrypt,
|
||||
VaultMessage, VaultProtocol, Unlock,
|
||||
};
|
||||
use crate::protocol::{DerivedKey, KeyType};
|
||||
|
||||
/// Handle to a running VaultService for local (in-process) use.
|
||||
///
|
||||
/// This is the primary API for local secret operations. It wraps the
|
||||
/// service state in an `Arc<RwLock<>>` for thread-safe access.
|
||||
#[derive(Clone)]
|
||||
pub struct VaultServiceHandle {
|
||||
inner: Arc<RwLock<VaultServiceInner>>,
|
||||
}
|
||||
|
||||
/// Internal state of the secret service.
|
||||
struct VaultServiceInner {
|
||||
/// The mnemonic phrase, if unlocked. None if locked.
|
||||
mnemonic: Option<Mnemonic>,
|
||||
/// The master seed, if unlocked. None if locked.
|
||||
seed: Option<Seed>,
|
||||
/// Whether the service is unlocked.
|
||||
unlocked: bool,
|
||||
/// TTL-based key cache with LRU eviction.
|
||||
cache: KeyCache,
|
||||
}
|
||||
|
||||
/// Errors that can occur during vault operations.
|
||||
#[derive(Debug, thiserror::Error, Serialize, Deserialize)]
|
||||
pub enum VaultServiceError {
|
||||
#[error("vault is locked; call Unlock first")]
|
||||
VaultLocked,
|
||||
#[error("vault is already unlocked")]
|
||||
AlreadyUnlocked,
|
||||
#[error("mnemonic error: {0}")]
|
||||
Mnemonic(String),
|
||||
#[error("derivation error: {0}")]
|
||||
Derivation(String),
|
||||
#[error("encryption error: {0}")]
|
||||
Encryption(String),
|
||||
#[error("invalid path: {0}")]
|
||||
InvalidPath(String),
|
||||
#[error("unsupported key type")]
|
||||
UnsupportedKeyType,
|
||||
}
|
||||
|
||||
impl From<crate::mnemonic::MnemonicError> for VaultServiceError {
|
||||
fn from(e: crate::mnemonic::MnemonicError) -> Self {
|
||||
VaultServiceError::Mnemonic(e.to_string())
|
||||
}
|
||||
}
|
||||
|
||||
impl From<DerivationError> for VaultServiceError {
|
||||
fn from(e: DerivationError) -> Self {
|
||||
VaultServiceError::Derivation(e.to_string())
|
||||
}
|
||||
}
|
||||
|
||||
impl From<encryption::EncryptionError> for VaultServiceError {
|
||||
fn from(e: encryption::EncryptionError) -> Self {
|
||||
VaultServiceError::Encryption(e.to_string())
|
||||
}
|
||||
}
|
||||
|
||||
impl VaultServiceHandle {
|
||||
/// Create a new VaultServiceHandle in the locked state with default cache config.
|
||||
pub fn new() -> Self {
|
||||
Self::with_cache_config(CacheConfig::default())
|
||||
}
|
||||
|
||||
/// Create a new VaultServiceHandle with the given cache configuration.
|
||||
pub fn with_cache_config(config: CacheConfig) -> Self {
|
||||
Self {
|
||||
inner: Arc::new(RwLock::new(VaultServiceInner {
|
||||
mnemonic: None,
|
||||
seed: None,
|
||||
unlocked: false,
|
||||
cache: KeyCache::new(config),
|
||||
})),
|
||||
}
|
||||
}
|
||||
|
||||
/// Unlock the service with an existing mnemonic phrase.
|
||||
///
|
||||
/// The passphrase is the BIP39 password (may be empty string for none).
|
||||
/// After unlocking, derive and encrypt/decrypt operations are available.
|
||||
pub fn unlock(&self, phrase: &str, passphrase: Option<&str>) -> Result<(), VaultServiceError> {
|
||||
let mut inner = self.inner.write().unwrap();
|
||||
if inner.unlocked {
|
||||
return Err(VaultServiceError::AlreadyUnlocked);
|
||||
}
|
||||
|
||||
let mnemonic = Mnemonic::from_phrase(phrase, Language::English)?;
|
||||
let seed = mnemonic.to_seed(passphrase);
|
||||
|
||||
inner.mnemonic = Some(mnemonic);
|
||||
inner.seed = Some(seed);
|
||||
inner.unlocked = true;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Unlock the service with a new randomly generated mnemonic.
|
||||
///
|
||||
/// Returns the generated mnemonic phrase. Store this phrase securely —
|
||||
/// it is the root of trust for all derived keys.
|
||||
pub fn unlock_new(&self, word_count: usize) -> Result<String, VaultServiceError> {
|
||||
let mut inner = self.inner.write().unwrap();
|
||||
if inner.unlocked {
|
||||
return Err(VaultServiceError::AlreadyUnlocked);
|
||||
}
|
||||
|
||||
let mnemonic = Mnemonic::generate(word_count)?;
|
||||
let seed = mnemonic.to_seed(None);
|
||||
let phrase = mnemonic.phrase().to_string();
|
||||
|
||||
inner.mnemonic = Some(mnemonic);
|
||||
inner.seed = Some(seed);
|
||||
inner.unlocked = true;
|
||||
Ok(phrase)
|
||||
}
|
||||
|
||||
/// Lock the service, purging the seed and all cached derived keys.
|
||||
///
|
||||
/// After locking, no derive/encrypt/decrypt operations are possible
|
||||
/// until `unlock` is called again. Calls `zeroize()` on all sensitive
|
||||
/// material per ADR-038.
|
||||
pub fn lock(&self) {
|
||||
let mut inner = self.inner.write().unwrap();
|
||||
inner.cache.clear();
|
||||
inner.seed = None;
|
||||
inner.mnemonic = None;
|
||||
inner.unlocked = false;
|
||||
}
|
||||
|
||||
/// Check whether the service is currently unlocked.
|
||||
pub fn is_unlocked(&self) -> bool {
|
||||
self.inner.read().unwrap().unlocked
|
||||
}
|
||||
|
||||
/// Derive an Ed25519 keypair at the given path.
|
||||
pub fn derive_ed25519(&self, path: &str) -> Result<DerivedKey, VaultServiceError> {
|
||||
let mut inner = self.inner.write().unwrap();
|
||||
if !inner.unlocked {
|
||||
return Err(VaultServiceError::VaultLocked);
|
||||
}
|
||||
|
||||
if let Some(cached) = inner.cache.get(path) {
|
||||
return Ok(DerivedKey {
|
||||
key_type: cached.key_type.clone(),
|
||||
private_key: cached.private_key.clone(),
|
||||
public_key: cached.public_key.clone(),
|
||||
});
|
||||
}
|
||||
|
||||
let seed = inner
|
||||
.seed
|
||||
.as_ref()
|
||||
.ok_or(VaultServiceError::VaultLocked)?;
|
||||
let key = derivation::derive_path_from_seed(seed.as_bytes(), path)?;
|
||||
let private_key = key.private_key().to_vec();
|
||||
let public_key = key.public_key().to_vec();
|
||||
let cached = CachedKey::new(KeyType::Ed25519, private_key.clone(), public_key.clone());
|
||||
inner.cache.insert(path, cached);
|
||||
Ok(DerivedKey {
|
||||
key_type: KeyType::Ed25519,
|
||||
private_key,
|
||||
public_key,
|
||||
})
|
||||
}
|
||||
|
||||
/// Derive an AES-256-GCM encryption key at the given path.
|
||||
pub fn derive_encryption_key(&self, path: &str) -> Result<DerivedKey, VaultServiceError> {
|
||||
let mut inner = self.inner.write().unwrap();
|
||||
if !inner.unlocked {
|
||||
return Err(VaultServiceError::VaultLocked);
|
||||
}
|
||||
|
||||
if let Some(cached) = inner.cache.get(path) {
|
||||
return Ok(DerivedKey {
|
||||
key_type: cached.key_type.clone(),
|
||||
private_key: cached.private_key.clone(),
|
||||
public_key: cached.public_key.clone(),
|
||||
});
|
||||
}
|
||||
|
||||
let seed = inner
|
||||
.seed
|
||||
.as_ref()
|
||||
.ok_or(VaultServiceError::VaultLocked)?;
|
||||
let key = derivation::derive_path_from_seed(seed.as_bytes(), path)?;
|
||||
let private_key = key.private_key().to_vec();
|
||||
let public_key = key.public_key().to_vec();
|
||||
let cached = CachedKey::new(KeyType::Aes256Gcm, private_key.clone(), public_key.clone());
|
||||
inner.cache.insert(path, cached);
|
||||
Ok(DerivedKey {
|
||||
key_type: KeyType::Aes256Gcm,
|
||||
private_key,
|
||||
public_key,
|
||||
})
|
||||
}
|
||||
|
||||
/// Derive a secp256k1 (Ethereum) keypair at the given path.
|
||||
///
|
||||
/// Uses BIP-0032 derivation (HMAC-SHA512 with "Bitcoin seed") when the
|
||||
/// `secp256k1` feature is enabled. Returns `UnsupportedKeyType` when the
|
||||
/// feature is disabled.
|
||||
pub fn derive_ethereum_key(&self, path: &str) -> Result<DerivedKey, VaultServiceError> {
|
||||
#[cfg(feature = "secp256k1")]
|
||||
{
|
||||
let mut inner = self.inner.write().unwrap();
|
||||
if !inner.unlocked {
|
||||
return Err(VaultServiceError::VaultLocked);
|
||||
}
|
||||
|
||||
if let Some(cached) = inner.cache.get(path) {
|
||||
return Ok(DerivedKey {
|
||||
key_type: cached.key_type.clone(),
|
||||
private_key: cached.private_key.clone(),
|
||||
public_key: cached.public_key.clone(),
|
||||
});
|
||||
}
|
||||
|
||||
let seed = inner
|
||||
.seed
|
||||
.as_ref()
|
||||
.ok_or(VaultServiceError::VaultLocked)?;
|
||||
|
||||
let key = crate::ethereum::derive_secp256k1_path(seed.as_bytes(), path)?;
|
||||
let private_key = key.private_key().to_vec();
|
||||
let public_key = key.public_key().to_vec();
|
||||
let cached =
|
||||
CachedKey::new(KeyType::Secp256k1, private_key.clone(), public_key.clone());
|
||||
inner.cache.insert(path, cached);
|
||||
Ok(DerivedKey {
|
||||
key_type: KeyType::Secp256k1,
|
||||
private_key,
|
||||
public_key,
|
||||
})
|
||||
}
|
||||
|
||||
#[cfg(not(feature = "secp256k1"))]
|
||||
{
|
||||
let _ = path;
|
||||
Err(VaultServiceError::UnsupportedKeyType)
|
||||
}
|
||||
}
|
||||
|
||||
pub fn derive_password(
|
||||
&self,
|
||||
path: &str,
|
||||
length: usize,
|
||||
) -> Result<Vec<u8>, VaultServiceError> {
|
||||
let inner = self.inner.read().unwrap();
|
||||
if !inner.unlocked {
|
||||
return Err(VaultServiceError::VaultLocked);
|
||||
}
|
||||
let seed = inner
|
||||
.seed
|
||||
.as_ref()
|
||||
.ok_or(VaultServiceError::VaultLocked)?;
|
||||
|
||||
let key = derivation::derive_path_from_seed(seed.as_bytes(), path)?;
|
||||
let private_key = key.private_key();
|
||||
let truncated_len = length.min(private_key.len());
|
||||
let result = private_key[..truncated_len].to_vec();
|
||||
Ok(result)
|
||||
}
|
||||
|
||||
pub fn derive_password_string(
|
||||
&self,
|
||||
path: &str,
|
||||
length: usize,
|
||||
) -> Result<String, VaultServiceError> {
|
||||
let bytes = self.derive_password(path, length)?;
|
||||
Ok(URL_SAFE_NO_PAD.encode(&bytes))
|
||||
}
|
||||
|
||||
/// Encrypt plaintext using the derived encryption key.
|
||||
///
|
||||
/// Uses the key at path `m/74'/2'/0'/0'` (PATHS::ENCRYPTION) by default.
|
||||
pub fn encrypt(
|
||||
&self,
|
||||
plaintext: &str,
|
||||
key_version: u32,
|
||||
) -> Result<EncryptedData, VaultServiceError> {
|
||||
let mut inner = self.inner.write().unwrap();
|
||||
if !inner.unlocked {
|
||||
return Err(VaultServiceError::VaultLocked);
|
||||
}
|
||||
|
||||
let private_key = if let Some(cached) = inner.cache.get(PATHS::ENCRYPTION) {
|
||||
cached.private_key.clone()
|
||||
} else {
|
||||
let seed = inner
|
||||
.seed
|
||||
.as_ref()
|
||||
.ok_or(VaultServiceError::VaultLocked)?;
|
||||
let derived = derivation::derive_path_from_seed(seed.as_bytes(), PATHS::ENCRYPTION)?;
|
||||
let pk = derived.private_key().to_vec();
|
||||
let pubk = derived.public_key().to_vec();
|
||||
let cached = CachedKey::new(KeyType::Aes256Gcm, pk.clone(), pubk);
|
||||
inner.cache.insert(PATHS::ENCRYPTION, cached);
|
||||
pk
|
||||
};
|
||||
|
||||
let enc_key = EncryptionKey::from_derived_bytes(&private_key, key_version);
|
||||
|
||||
encryption::encrypt(plaintext, &enc_key).map_err(|e| e.into())
|
||||
}
|
||||
|
||||
/// Decrypt an EncryptedData blob using the derived encryption key.
|
||||
pub fn decrypt(&self, encrypted: &EncryptedData) -> Result<String, VaultServiceError> {
|
||||
let mut inner = self.inner.write().unwrap();
|
||||
if !inner.unlocked {
|
||||
return Err(VaultServiceError::VaultLocked);
|
||||
}
|
||||
|
||||
let private_key = if let Some(cached) = inner.cache.get(PATHS::ENCRYPTION) {
|
||||
cached.private_key.clone()
|
||||
} else {
|
||||
let seed = inner
|
||||
.seed
|
||||
.as_ref()
|
||||
.ok_or(VaultServiceError::VaultLocked)?;
|
||||
let derived = derivation::derive_path_from_seed(seed.as_bytes(), PATHS::ENCRYPTION)?;
|
||||
let pk = derived.private_key().to_vec();
|
||||
let pubk = derived.public_key().to_vec();
|
||||
let cached = CachedKey::new(KeyType::Aes256Gcm, pk.clone(), pubk);
|
||||
inner.cache.insert(PATHS::ENCRYPTION, cached);
|
||||
pk
|
||||
};
|
||||
|
||||
let enc_key = EncryptionKey::from_derived_bytes(&private_key, encrypted.key_version);
|
||||
|
||||
encryption::decrypt(encrypted, &enc_key).map_err(|e| e.into())
|
||||
}
|
||||
}
|
||||
|
||||
impl Default for VaultServiceHandle {
|
||||
fn default() -> Self {
|
||||
Self::new()
|
||||
}
|
||||
}
|
||||
|
||||
/// The VaultService manages the lifecycle of the master seed and provides
|
||||
/// secret operations. This is the type used by the irpc service handler.
|
||||
///
|
||||
/// For local (in-process) use, prefer `VaultServiceHandle` which wraps
|
||||
/// this in thread-safe locks.
|
||||
pub struct VaultService {
|
||||
handle: VaultServiceHandle,
|
||||
}
|
||||
|
||||
impl VaultService {
|
||||
/// Create a new VaultService in the locked state.
|
||||
pub fn new() -> Self {
|
||||
Self {
|
||||
handle: VaultServiceHandle::new(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Get a handle for local (in-process) use.
|
||||
pub fn handle(&self) -> &VaultServiceHandle {
|
||||
&self.handle
|
||||
}
|
||||
}
|
||||
|
||||
impl Default for VaultService {
|
||||
fn default() -> Self {
|
||||
Self::new()
|
||||
}
|
||||
}
|
||||
|
||||
/// Actor that processes `VaultMessage` variants and dispatches to `VaultServiceHandle`.
|
||||
///
|
||||
/// The actor runs as a `tokio::task`, receives messages from an mpsc channel,
|
||||
/// dispatches to the handle methods, and sends responses through oneshot channels.
|
||||
///
|
||||
/// # Usage
|
||||
///
|
||||
/// ```ignore
|
||||
/// let handle = VaultServiceHandle::new();
|
||||
/// let (client, actor) = VaultServiceActor::spawn(handle);
|
||||
/// tokio::task::spawn(actor.run(rx));
|
||||
/// // Use client to send messages
|
||||
/// ```
|
||||
pub struct VaultServiceActor {
|
||||
handle: VaultServiceHandle,
|
||||
}
|
||||
|
||||
impl VaultServiceActor {
|
||||
/// Create a new actor wrapping the given handle.
|
||||
pub fn new(handle: VaultServiceHandle) -> Self {
|
||||
Self { handle }
|
||||
}
|
||||
|
||||
/// Run the actor message loop, processing `VaultMessage` variants.
|
||||
///
|
||||
/// This method runs until the receiver channel is closed. Each message
|
||||
/// variant is dispatched to the corresponding `VaultServiceHandle` method
|
||||
/// and the response is sent through the oneshot channel embedded in the message.
|
||||
pub async fn run(mut self, mut rx: tokio::sync::mpsc::Receiver<VaultMessage>) {
|
||||
while let Some(msg) = rx.recv().await {
|
||||
self.handle_message(msg);
|
||||
}
|
||||
}
|
||||
|
||||
/// Spawn the actor as a `tokio::task` and return a `Client<VaultProtocol>` for sending messages.
|
||||
///
|
||||
/// The actor runs on a tokio task and processes messages from the mpsc channel.
|
||||
/// The returned `Client<VaultProtocol>` can be used to send `VaultMessage` variants
|
||||
/// to the actor.
|
||||
pub fn spawn(
|
||||
handle: VaultServiceHandle,
|
||||
) -> (irpc::Client<VaultProtocol>, VaultServiceActor) {
|
||||
let (tx, rx) = tokio::sync::mpsc::channel(64);
|
||||
let client = irpc::Client::local(tx);
|
||||
let actor = Self::new(handle.clone());
|
||||
tokio::task::spawn(actor.run(rx));
|
||||
(client, Self::new(handle))
|
||||
}
|
||||
|
||||
/// Handle a single `VaultMessage` by dispatching to the appropriate handle method.
|
||||
fn handle_message(&mut self, msg: VaultMessage) {
|
||||
match msg {
|
||||
VaultMessage::DeriveEd25519(msg) => {
|
||||
let WithChannels { inner, tx, .. } = msg;
|
||||
let DeriveEd25519 { path } = inner;
|
||||
let result = self.handle.derive_ed25519(&path);
|
||||
tokio::spawn(async move {
|
||||
let _ = tx.send(result).await;
|
||||
});
|
||||
}
|
||||
VaultMessage::DeriveEncryptionKey(msg) => {
|
||||
let WithChannels { inner, tx, .. } = msg;
|
||||
let DeriveEncryptionKey { path } = inner;
|
||||
let result = self.handle.derive_encryption_key(&path);
|
||||
tokio::spawn(async move {
|
||||
let _ = tx.send(result).await;
|
||||
});
|
||||
}
|
||||
VaultMessage::DeriveEthereumKey(msg) => {
|
||||
let WithChannels { inner, tx, .. } = msg;
|
||||
let DeriveEthereumKey { path } = inner;
|
||||
let result = self.handle.derive_ethereum_key(&path);
|
||||
tokio::spawn(async move {
|
||||
let _ = tx.send(result).await;
|
||||
});
|
||||
}
|
||||
VaultMessage::DerivePassword(msg) => {
|
||||
let WithChannels { inner, tx, .. } = msg;
|
||||
let DerivePassword { path, length } = inner;
|
||||
let result = self.handle.derive_password(&path, length);
|
||||
tokio::spawn(async move {
|
||||
let _ = tx.send(result).await;
|
||||
});
|
||||
}
|
||||
VaultMessage::Encrypt(msg) => {
|
||||
let WithChannels { inner, tx, .. } = msg;
|
||||
let Encrypt {
|
||||
plaintext,
|
||||
key_version,
|
||||
} = inner;
|
||||
let result = self.handle.encrypt(&plaintext, key_version);
|
||||
tokio::spawn(async move {
|
||||
let _ = tx.send(result).await;
|
||||
});
|
||||
}
|
||||
VaultMessage::Decrypt(msg) => {
|
||||
let WithChannels { inner, tx, .. } = msg;
|
||||
let Decrypt { encrypted } = inner;
|
||||
let result = self.handle.decrypt(&encrypted);
|
||||
tokio::spawn(async move {
|
||||
let _ = tx.send(result).await;
|
||||
});
|
||||
}
|
||||
VaultMessage::Lock(msg) => {
|
||||
let WithChannels { inner: _, tx, .. } = msg;
|
||||
self.handle.lock();
|
||||
tokio::spawn(async move {
|
||||
let _ = tx.send(Ok(())).await;
|
||||
});
|
||||
}
|
||||
VaultMessage::Unlock(msg) => {
|
||||
let WithChannels { inner, tx, .. } = msg;
|
||||
let Unlock {
|
||||
mnemonic,
|
||||
passphrase,
|
||||
} = inner;
|
||||
let result = self.handle.unlock(&mnemonic, passphrase.as_deref());
|
||||
tokio::spawn(async move {
|
||||
let _ = tx.send(result).await;
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::protocol::Lock;
|
||||
use irpc::channel::oneshot;
|
||||
use irpc::WithChannels;
|
||||
|
||||
#[test]
|
||||
fn test_service_starts_locked() {
|
||||
let service = VaultServiceHandle::new();
|
||||
assert!(!service.is_unlocked());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_unlock_new_generates_mnemonic() {
|
||||
let service = VaultServiceHandle::new();
|
||||
let phrase = service.unlock_new(24).unwrap();
|
||||
assert!(!phrase.is_empty());
|
||||
assert!(service.is_unlocked());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_lock_purges_state() {
|
||||
let service = VaultServiceHandle::new();
|
||||
service.unlock_new(24).unwrap();
|
||||
assert!(service.is_unlocked());
|
||||
|
||||
service.lock();
|
||||
assert!(!service.is_unlocked());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_derive_on_locked_fails() {
|
||||
let service = VaultServiceHandle::new();
|
||||
let result = service.derive_ed25519(PATHS::IDENTITY);
|
||||
assert!(result.is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_encrypt_on_locked_fails() {
|
||||
let service = VaultServiceHandle::new();
|
||||
let result = service.encrypt("secret", 1);
|
||||
assert!(result.is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_full_lifecycle() {
|
||||
let service = VaultServiceHandle::new();
|
||||
|
||||
assert!(!service.is_unlocked());
|
||||
|
||||
assert!(service.derive_ed25519(PATHS::IDENTITY).is_err());
|
||||
|
||||
let _phrase = service.unlock_new(24).unwrap();
|
||||
assert!(service.is_unlocked());
|
||||
|
||||
let key = service.derive_ed25519(PATHS::IDENTITY).unwrap();
|
||||
assert!(!key.private_key.is_empty());
|
||||
|
||||
service.lock();
|
||||
assert!(!service.is_unlocked());
|
||||
|
||||
assert!(service.derive_ed25519(PATHS::IDENTITY).is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_unlock_with_known_phrase() {
|
||||
let service = VaultServiceHandle::new();
|
||||
|
||||
let phrase = service.unlock_new(24).unwrap();
|
||||
service.lock();
|
||||
|
||||
service.unlock(&phrase, None).unwrap();
|
||||
assert!(service.is_unlocked());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_double_unlock_fails() {
|
||||
let service = VaultServiceHandle::new();
|
||||
service.unlock_new(24).unwrap();
|
||||
|
||||
let result = service.unlock_new(12);
|
||||
assert!(result.is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_encrypt_decrypt_lifecycle() {
|
||||
let service = VaultServiceHandle::new();
|
||||
service.unlock_new(24).unwrap();
|
||||
|
||||
let plaintext = "my-api-key-12345";
|
||||
let encrypted = service.encrypt(plaintext, 1).unwrap();
|
||||
let decrypted = service.decrypt(&encrypted).unwrap();
|
||||
assert_eq!(decrypted, plaintext);
|
||||
|
||||
service.lock();
|
||||
assert!(service.decrypt(&encrypted).is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_derive_password_deterministic() {
|
||||
let service = VaultServiceHandle::new();
|
||||
service.unlock_new(24).unwrap();
|
||||
|
||||
let path = "m/74'/1'/0'/12345'";
|
||||
let pw1 = service.derive_password(path, 16).unwrap();
|
||||
let pw2 = service.derive_password(path, 16).unwrap();
|
||||
assert_eq!(pw1, pw2, "derive_password must be deterministic");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_derive_password_different_paths() {
|
||||
let service = VaultServiceHandle::new();
|
||||
service.unlock_new(24).unwrap();
|
||||
|
||||
let pw_a = service.derive_password("m/74'/1'/0'/100'", 16).unwrap();
|
||||
let pw_b = service.derive_password("m/74'/1'/0'/200'", 16).unwrap();
|
||||
assert_ne!(
|
||||
pw_a, pw_b,
|
||||
"different paths must produce different passwords"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_derive_password_length_truncation() {
|
||||
let service = VaultServiceHandle::new();
|
||||
service.unlock_new(24).unwrap();
|
||||
|
||||
let path = "m/74'/1'/0'/999'";
|
||||
let pw_full = service.derive_password(path, 32).unwrap();
|
||||
let pw_short = service.derive_password(path, 16).unwrap();
|
||||
|
||||
assert_eq!(pw_short.len(), 16);
|
||||
assert_eq!(pw_full.len(), 32);
|
||||
assert_eq!(
|
||||
&pw_full[..16],
|
||||
&pw_short[..],
|
||||
"truncated bytes must match prefix of full key"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_derive_password_locked_error() {
|
||||
let service = VaultServiceHandle::new();
|
||||
let result = service.derive_password("m/74'/1'/0'/1'", 16);
|
||||
assert!(matches!(result, Err(VaultServiceError::VaultLocked)));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_derive_password_string_base64url() {
|
||||
let service = VaultServiceHandle::new();
|
||||
service.unlock_new(24).unwrap();
|
||||
|
||||
let path = "m/74'/1'/0'/42'";
|
||||
let encoded = service.derive_password_string(path, 16).unwrap();
|
||||
|
||||
assert!(!encoded.contains('='), "Base64url must not contain padding");
|
||||
assert!(
|
||||
encoded
|
||||
.chars()
|
||||
.all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_'),
|
||||
"Base64url must only contain URL-safe characters"
|
||||
);
|
||||
|
||||
let raw_bytes = service.derive_password(path, 16).unwrap();
|
||||
let decoded = URL_SAFE_NO_PAD.decode(&encoded).unwrap();
|
||||
assert_eq!(raw_bytes, decoded);
|
||||
}
|
||||
|
||||
#[cfg(feature = "secp256k1")]
|
||||
#[test]
|
||||
fn test_derive_ethereum_key_bip32() {
|
||||
let service = VaultServiceHandle::new();
|
||||
service.unlock_new(24).unwrap();
|
||||
|
||||
let key = service.derive_ethereum_key(PATHS::ETHEREUM).unwrap();
|
||||
assert_eq!(key.key_type, KeyType::Secp256k1);
|
||||
assert_eq!(key.private_key.len(), 32);
|
||||
assert_eq!(key.public_key.len(), 33);
|
||||
}
|
||||
|
||||
#[cfg(feature = "secp256k1")]
|
||||
#[test]
|
||||
fn test_ethereum_key_differs_from_ed25519() {
|
||||
let service = VaultServiceHandle::new();
|
||||
service.unlock_new(24).unwrap();
|
||||
|
||||
let eth_key = service.derive_ethereum_key(PATHS::ETHEREUM).unwrap();
|
||||
let ed_key = service.derive_ed25519(PATHS::IDENTITY).unwrap();
|
||||
|
||||
assert_ne!(eth_key.private_key, ed_key.private_key);
|
||||
}
|
||||
|
||||
#[cfg(not(feature = "secp256k1"))]
|
||||
#[test]
|
||||
fn test_derive_ethereum_key_unsupported_without_feature() {
|
||||
let service = VaultServiceHandle::new();
|
||||
service.unlock_new(24).unwrap();
|
||||
|
||||
let result = service.derive_ethereum_key(PATHS::ETHEREUM);
|
||||
assert!(matches!(
|
||||
result,
|
||||
Err(VaultServiceError::UnsupportedKeyType)
|
||||
));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_cache_hit_avoids_re_derivation() {
|
||||
let service = VaultServiceHandle::new();
|
||||
service.unlock_new(24).unwrap();
|
||||
|
||||
let key1 = service.derive_ed25519(PATHS::IDENTITY).unwrap();
|
||||
let key2 = service.derive_ed25519(PATHS::IDENTITY).unwrap();
|
||||
|
||||
assert_eq!(key1.private_key, key2.private_key);
|
||||
assert_eq!(key1.public_key, key2.public_key);
|
||||
|
||||
let cache_len = service.inner.read().unwrap().cache.len();
|
||||
assert_eq!(cache_len, 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_cache_miss_derives_and_caches() {
|
||||
let service = VaultServiceHandle::new();
|
||||
service.unlock_new(24).unwrap();
|
||||
|
||||
assert_eq!(service.inner.read().unwrap().cache.len(), 0);
|
||||
|
||||
service.derive_ed25519(PATHS::IDENTITY).unwrap();
|
||||
|
||||
assert_eq!(service.inner.read().unwrap().cache.len(), 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_expired_entry_evicted_on_access() {
|
||||
let config = crate::cache::CacheConfig::new(std::time::Duration::from_millis(5), 64);
|
||||
let service = VaultServiceHandle::with_cache_config(config);
|
||||
service.unlock_new(24).unwrap();
|
||||
|
||||
let key1 = service.derive_ed25519(PATHS::IDENTITY).unwrap();
|
||||
assert_eq!(service.inner.read().unwrap().cache.len(), 1);
|
||||
|
||||
std::thread::sleep(std::time::Duration::from_millis(10));
|
||||
|
||||
let key2 = service.derive_ed25519(PATHS::IDENTITY).unwrap();
|
||||
assert_eq!(key1.private_key, key2.private_key);
|
||||
assert_eq!(service.inner.read().unwrap().cache.len(), 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_lru_eviction_when_over_max_entries() {
|
||||
let config = crate::cache::CacheConfig::new(std::time::Duration::from_secs(3600), 2);
|
||||
let service = VaultServiceHandle::with_cache_config(config);
|
||||
service.unlock_new(24).unwrap();
|
||||
|
||||
service.derive_ed25519(PATHS::IDENTITY).unwrap();
|
||||
service.derive_ed25519(PATHS::SSH_HOST).unwrap();
|
||||
assert_eq!(service.inner.read().unwrap().cache.len(), 2);
|
||||
|
||||
service.derive_ed25519(PATHS::ENCRYPTION).unwrap();
|
||||
assert_eq!(service.inner.read().unwrap().cache.len(), 2);
|
||||
|
||||
let mut inner = service.inner.write().unwrap();
|
||||
assert!(inner.cache.get(PATHS::IDENTITY).is_none());
|
||||
assert!(inner.cache.get(PATHS::SSH_HOST).is_some());
|
||||
assert!(inner.cache.get(PATHS::ENCRYPTION).is_some());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_lock_clears_all_cache_entries() {
|
||||
let service = VaultServiceHandle::new();
|
||||
service.unlock_new(24).unwrap();
|
||||
|
||||
service.derive_ed25519(PATHS::IDENTITY).unwrap();
|
||||
service.derive_ed25519(PATHS::SSH_HOST).unwrap();
|
||||
assert_eq!(service.inner.read().unwrap().cache.len(), 2);
|
||||
|
||||
service.lock();
|
||||
|
||||
assert_eq!(service.inner.read().unwrap().cache.len(), 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_encrypt_decrypt_uses_cached_encryption_key() {
|
||||
let service = VaultServiceHandle::new();
|
||||
service.unlock_new(24).unwrap();
|
||||
|
||||
let plaintext = "cached-encryption-test";
|
||||
let encrypted = service.encrypt(plaintext, 1).unwrap();
|
||||
assert_eq!(service.inner.read().unwrap().cache.len(), 1);
|
||||
|
||||
let decrypted = service.decrypt(&encrypted).unwrap();
|
||||
assert_eq!(decrypted, plaintext);
|
||||
|
||||
assert_eq!(service.inner.read().unwrap().cache.len(), 1);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_actor_unlock_responds_successfully() {
|
||||
let handle = VaultServiceHandle::new();
|
||||
let (tx, rx) = tokio::sync::mpsc::channel(64);
|
||||
let actor = VaultServiceActor::new(handle);
|
||||
tokio::task::spawn(actor.run(rx));
|
||||
|
||||
let (resp_tx, resp_rx) = oneshot::channel();
|
||||
let msg = VaultMessage::Unlock(WithChannels::from((
|
||||
Unlock {
|
||||
mnemonic: "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about".to_string(),
|
||||
passphrase: None,
|
||||
},
|
||||
resp_tx,
|
||||
)));
|
||||
tx.send(msg).await.unwrap();
|
||||
|
||||
let result = resp_rx.await.unwrap();
|
||||
assert!(result.is_ok(), "Unlock via actor must succeed");
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_actor_derive_ed25519_returns_key() {
|
||||
let handle = VaultServiceHandle::new();
|
||||
handle.unlock_new(24).unwrap();
|
||||
let (tx, rx) = tokio::sync::mpsc::channel(64);
|
||||
let actor = VaultServiceActor::new(handle);
|
||||
tokio::task::spawn(actor.run(rx));
|
||||
|
||||
let (resp_tx, resp_rx) = oneshot::channel();
|
||||
let msg = VaultMessage::DeriveEd25519(WithChannels::from((
|
||||
DeriveEd25519 {
|
||||
path: PATHS::IDENTITY.to_string(),
|
||||
},
|
||||
resp_tx,
|
||||
)));
|
||||
tx.send(msg).await.unwrap();
|
||||
|
||||
let result = resp_rx.await.unwrap();
|
||||
assert!(result.is_ok(), "DeriveEd25519 via actor must succeed");
|
||||
let key = result.unwrap();
|
||||
assert!(
|
||||
!key.private_key.is_empty(),
|
||||
"DerivedKey must have private_key"
|
||||
);
|
||||
assert_eq!(key.key_type, KeyType::Ed25519);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_actor_lock_clears_state() {
|
||||
let handle = VaultServiceHandle::new();
|
||||
handle.unlock_new(24).unwrap();
|
||||
let (tx, rx) = tokio::sync::mpsc::channel(64);
|
||||
let actor = VaultServiceActor::new(handle.clone());
|
||||
tokio::task::spawn(actor.run(rx));
|
||||
|
||||
let (resp_tx, resp_rx): (oneshot::Sender<Result<(), VaultServiceError>>, _) =
|
||||
oneshot::channel();
|
||||
let msg = VaultMessage::Lock(WithChannels::from((Lock, resp_tx)));
|
||||
tx.send(msg).await.unwrap();
|
||||
|
||||
let result = resp_rx.await.unwrap();
|
||||
assert!(result.is_ok(), "Lock via actor must succeed");
|
||||
assert!(!handle.is_unlocked(), "Handle must be locked after Lock");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_unlock_with_passphrase_produces_different_seed() {
|
||||
let service_a = VaultServiceHandle::new();
|
||||
let service_b = VaultServiceHandle::new();
|
||||
|
||||
let phrase = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
|
||||
|
||||
service_a.unlock(phrase, None).unwrap();
|
||||
let key_a = service_a.derive_ed25519(PATHS::IDENTITY).unwrap();
|
||||
|
||||
service_a.lock();
|
||||
|
||||
service_a.unlock(phrase, Some("TREZOR")).unwrap();
|
||||
let key_b = service_a.derive_ed25519(PATHS::IDENTITY).unwrap();
|
||||
|
||||
assert_ne!(
|
||||
key_a.private_key, key_b.private_key,
|
||||
"Unlock with passphrase must produce different seed than without"
|
||||
);
|
||||
|
||||
service_a.lock();
|
||||
|
||||
service_b.unlock(phrase, None).unwrap();
|
||||
let key_c = service_b.derive_ed25519(PATHS::IDENTITY).unwrap();
|
||||
|
||||
assert_eq!(
|
||||
key_a.private_key, key_c.private_key,
|
||||
"Unlock with None passphrase must produce same seed as another None passphrase unlock"
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_actor_unlock_with_passphrase() {
|
||||
let handle = VaultServiceHandle::new();
|
||||
let (tx, rx) = tokio::sync::mpsc::channel(64);
|
||||
let actor = VaultServiceActor::new(handle);
|
||||
tokio::task::spawn(actor.run(rx));
|
||||
|
||||
let mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
|
||||
|
||||
let (resp_tx, resp_rx) = oneshot::channel();
|
||||
let msg = VaultMessage::Unlock(WithChannels::from((
|
||||
Unlock {
|
||||
mnemonic: mnemonic.to_string(),
|
||||
passphrase: Some("TREZOR".to_string()),
|
||||
},
|
||||
resp_tx,
|
||||
)));
|
||||
tx.send(msg).await.unwrap();
|
||||
|
||||
let result = resp_rx.await.unwrap();
|
||||
assert!(
|
||||
result.is_ok(),
|
||||
"Unlock with passphrase via actor must succeed"
|
||||
);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user