anubis_vault/

lib.rs

//! # Anubis Vault - The World's Most Secure Secrets Manager
//!
//! [![Crates.io](https://img.shields.io/crates/v/anubis-vault.svg)](https://crates.io/crates/anubis-vault)
//! [![Documentation](https://docs.rs/anubis-vault/badge.svg)](https://docs.rs/anubis-vault)
//! [![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](https://github.com/AnubisQuantumCipher/anubis-vault)
//!
//! **Guardian of Secrets - Protected by Quantum-Resistant Cryptography**
//!
//! Like Anubis, the ancient Egyptian guardian who protected the gates of the underworld and weighed
//! the hearts of souls, **Anubis Vault** stands as the ultimate guardian of your digital secrets.
//! No one—not even quantum computers or nation-state actors—can breach its defenses.
//!
//! ## Quick Start
//!
//! Add Anubis Vault to your `Cargo.toml`:
//!
//! ```toml
//! [dependencies]
//! anubis-vault = "0.1"
//! ```
//!
//! ### Basic Usage
//!
//! ```rust,no_run
//! use anubis_vault::{Vault, Secret};
//!
//! # fn main() -> anubis_vault::Result<()> {
//! // Initialize a new vault
//! let vault_path = "~/.anubis-vault";
//! let master_password = "super-secret-password-123";
//!
//! // Create and initialize vault
//! let mut vault = Vault::new(vault_path)?;
//! vault.init(master_password)?;
//!
//! // Add a secret
//! let secret = Secret::new("API_KEY", "my-secret-api-key");
//! vault.add(secret)?;
//!
//! // Retrieve a secret
//! let secret = vault.get("API_KEY")?;
//! println!("API Key: {}", secret.reveal());
//!
//! // List all secrets
//! let secrets = vault.list()?;
//! for secret in secrets {
//!     println!("- {}", secret.name);
//! }
//! # Ok(())
//! # }
//! ```
//!
//! ## 5 Layers of Ultimate Security
//!
//! Anubis Vault provides **defense-in-depth security** with five independent layers:
//!
//! ### Layer 1: Classical Cryptography
//!
//! | Component | Algorithm | Parameters |
//! |-----------|-----------|-----------|
//! | **Encryption** | XChaCha20-Poly1305 | 256-bit key, 192-bit nonce, AEAD |
//! | **Key Derivation** | Argon2id | 64 MiB memory, 3 iterations, p=4 |
//! | **Key Exchange** | X25519 | Curve25519 ECDH |
//! | **Signatures** | Ed25519 | EdDSA on Curve25519 |
//! | **Hashing** | BLAKE3 | 256-bit output, Merkle trees |
//!
//! **Security Level:** 256-bit classical security
//!
//! ### Layer 2: Post-Quantum Cryptography
//!
//! | Component | Algorithm | Security Level |
//! |-----------|-----------|---------------|
//! | **Key Encapsulation** | ML-KEM-1024 | NIST Level 5 (256-bit quantum) |
//! | **Digital Signatures** | ML-DSA-87 | NIST Level 5 (256-bit quantum) |
//!
//! **Security Level:** 256-bit quantum security (NIST FIPS 203/204)
//!
//! ### Layer 3: Zero-Knowledge Proofs
//!
//! - **Framework:** Plonky3 (ultra-fast STARKs)
//! - **Performance:** 100x faster than Plonky2
//! - **Use Case:** Privacy-preserving audit trails
//!
//! ### Layer 4: Shamir Secret Sharing
//!
//! - **Scheme:** M-of-N threshold recovery
//! - **Security:** Information-theoretically secure
//! - **Use Case:** Distributed backup and multi-party authentication
//!
//! ### Layer 5: Memory Protection
//!
//! - **Unix/Linux:** `mlock()` prevents swap to disk
//! - **Windows:** `VirtualLock()` locks pages in memory
//! - **All Platforms:** Automatic zeroization, core dumps disabled
//!
//! ## Features
//!
//! ### Core Cryptography
//!
//! - **Zero-knowledge encryption**: All secrets encrypted locally before storage
//! - **Post-quantum ready**: ML-KEM-1024 and ML-DSA-87 (NIST standards)
//! - **Hybrid encryption**: Combines classical and post-quantum algorithms
//! - **Memory-hard KDF**: Argon2id with 64 MiB memory cost
//! - **Authenticated encryption**: XChaCha20-Poly1305 prevents tampering
//!
//! ### Advanced Security
//!
//! - **Cryptographic audit logs**: Blockchain-like tamper-proof audit trail
//! - **Threshold secret sharing**: Split secrets using Shamir's Secret Sharing
//! - **Memory protection**: Physical RAM locking and automatic zeroization
//! - **Zero-knowledge proofs**: Prove access without revealing secrets
//!
//! ### Developer Experience
//!
//! - **CI/CD integration**: Safely inject secrets into build pipelines
//! - **CLI-first design**: Built for developer workflows and automation
//! - **Multiple output formats**: JSON, plain text, clipboard
//! - **Cross-platform**: macOS, Linux, Windows
//!
//! ## Security Model
//!
//! ### Protected Against
//!
//! - ✅ Brute-force attacks (Argon2id makes it computationally infeasible)
//! - ✅ Quantum computer attacks (ML-KEM-1024, ML-DSA-87)
//! - ✅ Memory dumps (mlock + zeroization)
//! - ✅ Swap attacks (memory locking)
//! - ✅ Core dumps (disabled via RLIMIT_CORE)
//! - ✅ Timing attacks (constant-time operations)
//! - ✅ Tampering (Poly1305 MAC + Ed25519 signatures)
//! - ✅ Rainbow tables (unique salts per secret)
//!
//! ### Threat Model
//!
//! **Computational Security:**
//!
//! Breaking Anubis Vault would require:
//! - **2^256 operations** to brute-force the master password (with 64 MiB RAM per attempt)
//! - **2^256 quantum operations** against ML-KEM-1024
//! - **Time to crack:** 3.67 × 10^59 years (assuming 1 trillion attempts per second)
//!
//! **Verdict:** Computationally infeasible to crack, even with future quantum computers.
//!
//! ### What This Library Does NOT Protect Against
//!
//! - Physical access to unlocked device (use full-disk encryption)
//! - Keyloggers (use hardware security keys)
//! - Compromised operating system (use secure boot)
//!
//! ## Architecture
//!
//! Anubis Vault is organized into several modules:
//!
//! - [`crypto`] - Cryptographic primitives (encryption, KDF, signatures, post-quantum)
//! - [`vault`] - Vault storage, secret management, and audit logging
//! - [`memory`] - Memory protection (locking and zeroization)
//! - [`sharing`] - Shamir's Secret Sharing implementation
//! - [`error`] - Error types and results
//!
//! ## Standards Compliance
//!
//! - ✅ **NIST FIPS 203** (ML-KEM-1024)
//! - ✅ **NIST FIPS 204** (ML-DSA-87)
//! - ✅ **RFC 7539** (ChaCha20-Poly1305)
//! - ✅ **RFC 9106** (Argon2)
//! - ✅ **RFC 7748** (Curve25519)
//! - ✅ **OWASP** password hashing guidelines
//!
//! ## Performance
//!
//! | Operation | Time | Notes |
//! |-----------|------|-------|
//! | Init vault | ~500ms | Argon2id KDF (one-time) |
//! | Add secret | ~100ms | Includes encryption + audit log |
//! | Get secret | ~100ms | Includes decryption + verification |
//! | List secrets | ~50ms | Metadata only (no decryption) |
//!
//! ## Examples
//!
//! ### Generate Random Secrets
//!
//! ```rust,no_run
//! use anubis_vault::crypto::generate_secret;
//!
//! // Generate a 32-character random secret
//! let secret = generate_secret(32, true); // true = include symbols
//! println!("Generated: {}", secret);
//! ```
//!
//! ### Shamir Secret Sharing
//!
//! ```rust,no_run
//! use anubis_vault::sharing::{split_secret, recover_secret};
//!
//! # fn main() -> anubis_vault::Result<()> {
//! let secret = b"super-secret-master-password";
//!
//! // Split into 5 shares, requiring 3 to recover
//! let shares = split_secret(secret, 3, 5)?;
//!
//! // Recover from any 3 shares
//! let recovered = recover_secret(&shares[0..3])?;
//! assert_eq!(secret, &recovered[..]);
//! # Ok(())
//! # }
//! ```
//!
//! ### Memory Protection
//!
//! ```rust,no_run
//! use anubis_vault::memory::LockedMemory;
//!
//! # fn main() -> anubis_vault::Result<()> {
//! // Create locked memory buffer for sensitive data
//! let mut locked = LockedMemory::<32>::new()?;
//!
//! // Use the buffer
//! locked.as_mut().copy_from_slice(b"secret-key-data-here-32-bytes!!");
//!
//! // Memory is automatically locked in RAM and zeroized on drop
//! # Ok(())
//! # }
//! ```
//!
//! ## Related Projects
//!
//! Part of the **Anubis Quantum Cipher** security ecosystem:
//!
//! - [**Anubis Rage**](https://github.com/AnubisQuantumCipher/anubis-rage) - Post-quantum file encryption
//! - [**Anubis Wormhole**](https://github.com/AnubisQuantumCipher/anubis-wormhole) - Quantum-secure file transfer
//! - [**Quantum Sign**](https://github.com/AnubisQuantumCipher/quantum-sign) - Post-quantum digital signatures
//!
//! ## License
//!
//! Dual-licensed under **MIT OR Apache-2.0**.
//!
//! See [LICENSE-MIT](https://github.com/AnubisQuantumCipher/anubis-vault/blob/main/LICENSE-MIT)
//! and [LICENSE-APACHE](https://github.com/AnubisQuantumCipher/anubis-vault/blob/main/LICENSE-APACHE)
//! for details.
//!
//! ## Security
//!
//! For security vulnerabilities, please see
//! [SECURITY.md](https://github.com/AnubisQuantumCipher/anubis-vault/blob/main/SECURITY.md)
//! for responsible disclosure process.
//!
//! **Security Contact:** security@anubisquantumcipher.dev
//!
//! ---
//!
//! **"Like Anubis, the ancient guardian who protected the gates of the underworld and weighed
//! the hearts of souls, Anubis Vault stands watch over your secrets, ensuring they remain
//! hidden from all—even the gods themselves, even quantum computers of the future."**

#![warn(
    missing_docs,
    rust_2018_idioms,
    unused_qualifications,
    missing_debug_implementations
)]
// Note: unsafe code is used in memory.rs for platform-specific memory locking (mlock/VirtualLock)
// This is necessary for security and is carefully reviewed.

pub mod crypto;
pub mod error;
pub mod vault;
pub mod memory;
pub mod sharing;
pub mod zkp;

// Re-export common types for convenience
pub use error::{Error, Result};
pub use vault::{Vault, Secret};

/// Current vault format version
pub const VAULT_VERSION: u32 = 1;

/// Minimum supported vault format version
pub const MIN_VAULT_VERSION: u32 = 1;

/// Magic bytes identifying an Anubis Vault file - "ANBS" (Anubis)
/// In hex: 41 4E 42 53
pub const ANUBIS_MAGIC: [u8; 4] = *b"ANBS";

/// The sacred seal - Anubis Quantum Cipher signature
pub const ANUBIS_SIGNATURE: &str = "Guarded by Anubis - Quantum Cipher Division";

/// Version string with Anubis branding
pub const VERSION: &str = concat!(
    "Anubis Vault v",
    env!("CARGO_PKG_VERSION"),
    " - Guardian of Secrets"
);