alknet/docs/architecture/crates/vault/service.md

status, last_updated

status	last_updated
draft	2026-06-22-25

Service

The VaultServiceHandle runtime API: unlock/lock lifecycle, key derivation, encryption, caching, and the direct method-call dispatch path.

What

The service layer wraps the vault's cryptographic primitives in a stateful runtime with a clear lifecycle. It holds the master seed in Zeroize-protected memory and provides methods for the unlock/lock lifecycle, key derivation, and encryption/decryption.

This is the API the assembly layer (CLI binary) calls. No other component calls these methods directly (ADR-019). The vault is local-only by construction (ADR-025) — direct method calls, no actor, no message enum, no remote dispatch.

VaultServiceHandle

The primary API for local (in-process) use. Thread-safe via Arc<RwLock<VaultServiceInner>>.

#[derive(Clone)]
pub struct VaultServiceHandle {
    inner: Arc<RwLock<VaultServiceInner>>,
}

struct VaultServiceInner {
    mnemonic: Option<Mnemonic>,  // None if locked
    seed: Option<Seed>,         // None if locked
    unlocked: bool,
    cache: KeyCache,            // TTL + LRU, see Cache section
}

VaultServiceHandle is Clone — cloning shares the underlying state via Arc. This is how the actor and the assembly layer share the same vault.

Lifecycle

Locked (initial state)
  │
  │ unlock(phrase, passphrase) / unlock_new(word_count)
  ▼
Unlocked — derive, encrypt, decrypt available
  │
  │ lock()
  ▼
Locked — seed and cache purged

unlock(phrase, passphrase)

pub fn unlock(&self, phrase: &str, passphrase: Option<&str>) -> Result<(), VaultServiceError>;

Unlock with an existing mnemonic phrase. Validates the phrase against the BIP39 word list, derives the seed, and stores both in VaultServiceInner. Returns AlreadyUnlocked if the vault is already unlocked.

The passphrase is the BIP39 password extension (the "25th word"). None means no passphrase (equivalent to empty string). Different passphrases produce different seeds.

unlock_new(word_count) → phrase

pub fn unlock_new(&self, word_count: usize) -> Result<String, VaultServiceError>;

Generate a new random mnemonic, unlock with it, and return the phrase. Store the returned phrase securely — it is the root of trust. Supported word counts: 12, 15, 18, 21, 24.

This is the "first run" path — a new node generates its mnemonic, writes it down, and the vault is unlocked for the process lifetime.

lock()

pub fn lock(&self);

Purge the seed, mnemonic, and all cached derived keys. Calls zeroize() on all sensitive material. After locking, no derive/encrypt/decrypt operations are possible until unlock is called again.

lock() on an already-locked service is a no-op (not an error).

is_unlocked()

pub fn is_unlocked(&self) -> bool;

Check whether the vault is currently unlocked. Cheap (read lock only).

Derive Methods

All derive methods require an unlocked vault and return VaultServiceError::VaultLocked if called while locked.

derive_ed25519(path) → DerivedKey

pub fn derive_ed25519(&self, path: &str) -> Result<DerivedKey, VaultServiceError>;

Derive an Ed25519 keypair at the given SLIP-0010 path. Checks the cache first; on a miss, derives from the seed and caches the result. Returns a DerivedKey with KeyType::Ed25519.

derive_encryption_key(path) → DerivedKey

pub fn derive_encryption_key(&self, path: &str) -> Result<DerivedKey, VaultServiceError>;

Derive an AES-256-GCM encryption key at the given path. Same cache behavior as derive_ed25519. Returns a DerivedKey with KeyType::Aes256Gcm.

derive_encryption_key_for_version(version) → EncryptionKey

pub fn derive_encryption_key_for_version(&self, version: u32) -> Result<EncryptionKey, VaultServiceError>;

Derive the encryption key for a specific key version. Maps the version to its derivation path via encryption_path_for_version(version) (ADR-021): v2 → m/74'/2'/0'/0', v3 → m/74'/2'/0'/1', etc. Cached by path. This is the version-aware method that decrypt uses to select the correct key for each blob — see encryption.md and ADR-021.

derive_encryption_key(path) (above) remains as the path-based API for deriving at arbitrary paths. derive_encryption_key_for_version(version) is the version-aware API used by encrypt and decrypt. The two share the same cache (keyed by derivation path).

derive_ethereum_key(path) → DerivedKey (feature-gated)

pub fn derive_ethereum_key(&self, path: &str) -> Result<DerivedKey, VaultServiceError>;

Derive a secp256k1 keypair at the given BIP-0032 path. Returns UnsupportedKeyType when the secp256k1 feature is disabled. Returns a DerivedKey with KeyType::Secp256k1 (33-byte compressed public key).

derive_password(path, length) → Vec

pub fn derive_password(&self, path: &str, length: usize) -> Result<Vec<u8>, VaultServiceError>;
pub fn derive_password_string(&self, path: &str, length: usize) -> Result<String, VaultServiceError>;

Derive deterministic password bytes at the given path, truncated to length. This is not cached — password derivation is cheap and passwords are typically one-shot (derive, use, discard). The string variant base64url-encodes the bytes (URL-safe, no padding).

derive_password is the mechanism for per-site deterministic passwords: the same seed + path always produces the same password. The path includes a site hash (site_password_path(site_hash)) so different sites get different passwords.

Encrypt and Decrypt

encrypt(plaintext, key_version) → EncryptedData

pub fn encrypt(&self, plaintext: &str, key_version: u32) -> Result<EncryptedData, VaultServiceError>;

Encrypt plaintext using the encryption key derived at PATHS::ENCRYPTION. Derives (and caches) the encryption key on first call, then uses the cache for subsequent calls. See encryption.md for the cryptographic details.

decrypt(encrypted) → String

pub fn decrypt(&self, encrypted: &EncryptedData) -> Result<String, VaultServiceError>;

Decrypt an EncryptedData blob. Derives (and caches) the encryption key at the version-indexed path indicated by encrypted.key_version via derive_encryption_key_for_version (ADR-021). Each version maps to a distinct path (m/74'/2'/0'/{version-2}'), so old and new keys can coexist during partial rotation. See encryption.md.

rotate(encrypted, to_version) → EncryptedData

pub fn rotate(&self, encrypted: &EncryptedData, to_version: u32) -> Result<EncryptedData, VaultServiceError>;

Re-encrypt an EncryptedData blob from its current key version to a new version. Decrypts with the old version's key, re-encrypts with the new version's key. Returns the new EncryptedData — the caller replaces the blob in storage. No new mnemonic needed; the same seed produces all version keys via different derivation paths (ADR-021).

This is the rotation primitive. The assembly layer or a migration tool iterates stored blobs and calls rotate on each. The vault does not self-rotate — rotation is an operational action.

Cache

Derived keys are cached for performance — HD derivation involves HMAC operations that are not free. The cache is keyed by derivation path and has TTL-based expiry and LRU eviction.

pub struct KeyCache {
    entries: HashMap<String, CachedKey>,
    order: Vec<String>,         // LRU ordering
    config: CacheConfig,
}

pub struct CacheConfig {
    pub ttl: Duration,          // default: 1 hour
    pub max_entries: usize,     // default: 64
}

• TTL: entries expire after ttl (default 1 hour). Expired entries are evicted lazily on access (get checks expiry) or via evict_expired().
• LRU: when the cache exceeds max_entries (default 64), the least recently used entry is evicted. Access (get) updates the LRU order.
• Zeroized: CachedKey derives Zeroize and ZeroizeOnDrop. Evicted and cleared entries are zeroized — derived private keys do not linger in freed heap memory.
• Cleared on lock: lock() calls cache.clear(), which removes and zeroizes all entries.

What is and isn't cached

Operation	Cached?	Why
derive_ed25519	Yes	Derivation is expensive; keys are reused
derive_encryption_key	Yes	Same — encryption key reused across calls
derive_ethereum_key	Yes	Same
derive_password	No	Cheap derivation; passwords are one-shot
encrypt / decrypt	Key cached	The encryption key (at PATHS::ENCRYPTION) is cached; the plaintext is not

derive_password does not cache because it's a truncation of derived bytes, not a keypair that's reused. Caching it would grow the cache with unique paths (one per site hash) for no reuse benefit.

Dispatch

The vault uses direct method calls on VaultServiceHandle — no actor, no message enum, no channels, no serialization (ADR-025). The handle is Arc<RwLock<VaultServiceInner>> — clone it, share it, call methods directly. The RwLock provides concurrent reads (derive operations) and exclusive writes (unlock/lock).

Assembly layer (CLI binary):
  1. Create VaultServiceHandle
  2. Unlock with mnemonic (local, from secure prompt or file)
  3. Call derive/encrypt/decrypt methods directly
  4. Extract bytes, construct alknet-core types at the assembly boundary
  5. Inject into handler capabilities (ADR-014)

There is no VaultProtocol enum, no VaultServiceActor, no Client<S>, and no remote dispatch capability. The vault is local-only by construction (ADR-025). If remote vault access is ever needed, it requires a separate vault-server crate with its own ADR (OQ-021, ADR-025).

The pre-ADR-025 design had an actor path (mpsc channel + oneshot backchannels, using irpc's Service trait) that was described as "secondary" to direct calls. ADR-025 removed it — the actor existed only to make irpc's dispatch work, and the direct path was always preferred. The RwLock-based concurrency model is both simpler and better for throughput (concurrent reads vs. sequential processing).

Errors

#[derive(Debug, thiserror::Error)]
pub enum VaultServiceError {
    VaultLocked,          // called derive/encrypt/decrypt while locked
    AlreadyUnlocked,      // called unlock while already unlocked
    Mnemonic(String),     // mnemonic generation/validation failed
    Derivation(String),   // HD derivation failed (bad path, HMAC error)
    Encryption(String),    // AES-GCM encrypt/decrypt failed
    InvalidPath(String),   // derivation path is malformed
    UnsupportedKeyType,   // secp256k1 called without the feature
}

VaultServiceError is a plain thiserror::Error enum (ADR-025 dropped the Serialize/Deserialize derives that were needed for irpc dispatch). It wraps sub-errors as strings. The CLI binary converts vault errors to alknet-core error types at the assembly boundary (ADR-018).

Design Decisions

Decision	ADR	Summary
Assembly layer is the sole caller	ADR-019	Handlers never hold a vault reference
Encryption key via HD derivation	ADR-020	Seed-derived key at m/74'/2'/0'/0', not PBKDF2
Version-indexed paths for rotation	ADR-021	decrypt selects key by version; rotate re-encrypts
RwLock for thread safety	—	Multiple readers (derive), exclusive writer (unlock/lock)
TTL + LRU cache	—	Bounded memory, fresh keys, zeroized eviction
Direct method calls (no actor)	ADR-025	No irpc, no message enum, no remote dispatch capability
derive_password not cached	—	One-shot; caching grows cache with no reuse

Open Questions

See open-questions.md for full details.

• OQ-21 (resolved by ADR-025): Remote vault access is not a feature of the vault crate. The vault is local-only by construction — direct method calls on VaultServiceHandle, no remote dispatch capability. If remote access is ever needed, it requires a separate vault-server crate with its own ADR. See protocol.md → Local-Only by Construction.

Security Constraints

These are security-critical implementation requirements, not architectural decisions. They are documented here so implementation agents don't miss them.

• OsRng for IVs: AES-GCM IVs and any cryptographic nonces must use OsRng (or equivalent CSPRNG), not rand::random(). IV reuse under the same key is catastrophic for GCM (authenticity breaks, two-time-pad on plaintext). The current source uses rand::random() for IV generation in encryption::encrypt() — this is a known drift and must be corrected during implementation sync.
• Zeroized drop: Seed, Mnemonic, CachedKey, EncryptionKey, ExtendedPrivKey, Secp256k1ExtendedPrivKey, and DerivedKey all derive Zeroize and ZeroizeOnDrop. The cache must clear on drop, not just on explicit lock(). The current KeyCache::clear() removes entries but relies on CachedKey's Drop impl for zeroization — verify that HashMap::clear() actually drops the values (it does, but this is worth a test).
• No unwrap() or expect() outside tests: poisoned lock recovery uses unwrap_or_else(|e| e.into_inner()) or explicit error propagation. A panic in one vault operation must not brick the vault for all other operations. The current source uses unwrap() on every RwLock acquisition in VaultServiceHandle (lines 142, 161, 182, 191, 196, 227, 264, 307, 340, 367) — this is a known drift and must be corrected. A poisoned lock should be recovered with unwrap_or_else(|e| e.into_inner()), not panicked.
• DerivedKey is move-only, not Clone: DerivedKey does not derive Clone. It is move-only — consumers receive it by value and zeroize it when done (handled by #[zeroize(drop)]). This prevents accidental duplication of secret material. The current source does not derive Clone on DerivedKey — this is correct.
• Cache eviction zeroizes: when the cache evicts an entry (LRU or TTL), the CachedKey is dropped, which triggers ZeroizeOnDrop. Do not replace CachedKey with a type that doesn't zeroize.

References

• Implementation: crates/alknet-vault/src/service.rs, crates/alknet-vault/src/cache.rs
• Tests: crates/alknet-vault/tests/service_tests.rs, crates/alknet-vault/src/service.rs (unit tests), crates/alknet-vault/src/cache.rs (unit tests)
• protocol.md — DerivedKey and KeyType
• encryption.md — encrypt / decrypt cryptographic details