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

status, last_updated

status	last_updated
draft	2026-06-22-19

alknet-vault

Local key vault: BIP39 mnemonic generation, SLIP-0010 Ed25519 HD key derivation, BIP-0032 secp256k1 derivation (feature-gated), and AES-256-GCM encryption. Holds the master seed — the root of trust for all derived keys and encrypted credentials in the alknet system.

What This Crate Is

alknet-vault is a standalone crate with zero alknet crate dependencies (ADR-018). It provides the cryptographic primitives and runtime API for managing the root of trust. The CLI binary (the alknet crate) is the sole component that talks to the vault directly (ADR-019) — handlers receive derived/decrypted material through capabilities, never through a vault reference.

The vault is not a network service. It has no ALPN, no ProtocolHandler implementation, and no operations registered in the call protocol (ADR-008, ADR-014). The master seed and derived private keys never cross the network.

Documents

Document	Status	Description
mnemonic-derivation.md	draft	BIP39, SLIP-0010, BIP-0032, derivation paths, key types
encryption.md	draft	AES-256-GCM, EncryptedData, key versioning, HD derivation (ADR-020)
service.md	draft	VaultServiceHandle lifecycle, actor dispatch, cache, error model
protocol.md	draft	VaultProtocol irpc messages, DerivedKey redaction, serialization

Applicable ADRs

ADR	Title	Relevance
003	Crate Decomposition	alknet-vault's standalone position
006	ALPN String Convention	ALPN versioning pattern for potential alknet/vault/v2
005	irpc as Call Protocol Foundation	VaultProtocol uses irpc directly
008	Vault Integration Point	CLI-embedded, capability source
010	ALPN Router and Endpoint	Ed25519 as default curve for TLS raw key identity
014	Secret Material Flow and Capability Injection	Capabilities carry vault-derived material
018	Vault as Standalone Crate	Zero alknet crate dependencies
019	Vault Assembly-Layer-Only Access	The assembly layer is the sole caller
020	HD Derivation for Encryption Keys	SLIP-0010 derivation, not PBKDF2; salt unused in v2
021	Key Rotation via Version-Indexed Paths	Version-indexed paths; rotate re-encrypts

Relevant Open Questions

OQ	Title	Status	Relevance
OQ-20	Encryption key derivation	resolved (ADR-020)	HD derivation from seed; salt field unused in v2
OQ-21	Remote vault access	deferred	Protocol is remote-capable by construction; enabling = server-setup change with auth-wrapping handler; Unlock/Lock local-only
OQ-22	Key rotation mechanism	resolved (ADR-021)	Version-indexed paths; rotate method

Key Design Principles

1. Standalone: The vault depends on no alknet crate. It defines its own types, errors, and protocol. External crates depend on the vault; the vault depends on nothing in alknet.
2. Assembly-layer only: The vault's API is consumed by the CLI binary, not by handlers. Handlers receive material through capabilities (ADR-014). The vault is not on the wire.
3. Zeroize everything sensitive: The mnemonic, seed, derived private keys, encryption keys, and cached keys all implement Zeroize and ZeroizeOnDrop. Secret material does not linger in freed heap memory.
4. Deterministic derivation: The same mnemonic + passphrase + path always produces the same key. Derivation is reproducible across runs and across nodes.
5. OsRng for nonces: AES-GCM IVs and any cryptographic nonces use OsRng (or equivalent CSPRNG), never rand::random(). IV reuse under the same key is catastrophic for GCM.
6. No unwrap() or expect() outside tests: vault operations propagate errors. A poisoned lock is recovered with unwrap_or_else(|e| e.into_inner()), not unwrap(). A panic in one vault operation must not brick the vault for all other operations.

Security Constraints

These are security-critical implementation requirements, not architectural decisions (the architecture is locked by the ADRs above). They are documented here so implementation agents don't miss them. See service.md → Security Constraints for the full list.

• OsRng for IVs: AES-GCM IVs must use OsRng, not rand::random(). The current source uses rand::random() — this is a known drift from the spec and must be corrected during implementation sync.
• Zeroized drop: Seed, Mnemonic, ExtendedPrivKey, Secp256k1ExtendedPrivKey, EncryptionKey, CachedKey, and DerivedKey all derive Zeroize and ZeroizeOnDrop. The cache must clear on drop, not just on explicit lock().
• No unwrap() outside tests: poisoned lock recovery uses unwrap_or_else(|e| e.into_inner()) or explicit error propagation. The current source uses unwrap() in VaultServiceHandle methods — this is a known drift and must be corrected.
• DerivedKey redaction in JSON: DerivedKey serializes the private_key as "[REDACTED]" in human-readable formats (JSON) and as raw bytes in binary formats (postcard). The redaction is a defense-in- depth measure, not the primary control — the primary control is that DerivedKey never crosses the call protocol wire (ADR-014).

Known Source Drift

The vault crate carries over source from the POC. The following items are known divergences between the current source and the spec. All must be corrected during implementation sync. This table is the single source of truth for drift tracking — if an item is fixed in source, update this table.

#	Item	Current source behavior	Target behavior (per spec)	Source location	Spec reference
1	IV generation	rand::random()	OsRng (CSPRNG)	encryption.rs L133	encryption.md → Security Constraints, service.md → Security Constraints
2	RwLock unwrap()	unwrap() on every RwLock acquisition (L142, 161, 182, 191, 196, 227, 264, 307, 340, 367)	unwrap_or_else(|e| e.into_inner()) for poisoned lock recovery	service.rs (see line numbers)	service.md → Security Constraints
3	CURRENT_KEY_VERSION	1 (HD-derived, but v1 is reserved for TS PBKDF2 legacy per ADR-020)	2 (HD-derived, per ADR-020)	encryption.rs	encryption.md → Key Versioning, ADR-020
4	spawn() return value	Returns a fresh, unspawned VaultServiceActor as the second tuple element (the spawned actor is consumed by run)	Either drop the second return value (return only Client<VaultProtocol>) or restructure so the returned actor is the one that was spawned	service.rs VaultServiceActor::spawn()	service.md → Actor Dispatch
5	HashMap::clear zeroization	KeyCache::clear() removes entries and relies on CachedKey's Drop impl for zeroization	Verify HashMap::clear() actually drops values (it does, but worth a test)	cache.rs	service.md → Security Constraints

Public API

The vault re-exports its primary types from the crate root:

// Mnemonic and seed
pub use mnemonic::{Language, Mnemonic, Seed};

// Derivation
pub use derivation::{DerivationError, ExtendedPrivKey, PATHS};

// Encryption
pub use encryption::{EncryptedData, EncryptionError};

// Protocol (irpc messages)
pub use protocol::{DerivedKey, KeyType, VaultMessage, VaultProtocol};

// Service (runtime)
pub use service::{VaultService, VaultServiceActor, VaultServiceError, VaultServiceHandle};

// Cache
pub use cache::CacheConfig;

The secp256k1 feature flag gates Ethereum (BIP-0032) derivation:

#[cfg(feature = "secp256k1")]
pub mod ethereum;