# AGE-VAULT TECHNICAL WIKI

## HOME / OVERVIEW

Age Vault is a Rust library (crate) that provides a secure, file-based vault for
managing identities and encrypting data using the age encryption format. It
wraps lower-level age-crypto, age-setup, and neuxdb crates to deliver a
batteries-included solution for applications needing encrypted account
management.

Key features:

- File-based vault: single database file, encrypted with a master password.
- Account management: create, list, remove accounts with unique names and roles.
- Age keypairs: each account owns an age public/secret keypair generated on
  creation. The secret key is encrypted with a Key Encryption Key (KEK) derived
  from the master password and a random salt.
- Multi-recipient encryption: encrypt arbitrary data for one or more accounts
  using age's native multi-recipient support.
- Decryption: decrypt data using an account's secret key, which is
  transparently decrypted by the vault's KEK.
- Strong cryptographic primitives: Argon2id for key derivation, age for
  authenticated encryption, secret zeroization for sensitive material.
- Error handling: unified error type covering I/O, database, cryptographic,
  serialization, and vault-specific failures.

The crate is intended for developers who need to embed a secure,
identity-oriented encryption layer in their Rust applications.

Quick Start:

    Command: cargo add age-vault

Then in your code:

    Code: Rust
    use age_vault::{Vault, Role};
    use std::path::PathBuf;

    fn main() -> Result<(), Box<dyn std::error::Error>> {
        let vault_path = PathBuf::from("my_vault.age");
        let master_password = "strong-master-password";

        // Create a new vault
        let mut vault = Vault::create(&vault_path, master_password)?;

        // Add accounts
        let alice = vault.add_account("alice", Role::Admin)?;
        let bob = vault.add_account("bob", Role::User)?;

        // Encrypt a message for multiple recipients
        let ciphertext = vault.encrypt_for(
            &["alice", "bob"],
            b"confidential data"
        )?;

        // Decrypt using Alice's identity
        let plaintext = vault.decrypt_with("alice", &ciphertext)?;
        assert_eq!(plaintext, b"confidential data");

        Ok(())
    }

# API REFERENCE

This section documents all public types, functions, and methods exposed by the
crate. Everything is re-exported from the crate root for convenience.

## Module: age_vault (crate root)

Public re-exports:

    * age_vault::Vault      (vault::Vault)
    * age_vault::Account    (account::Account)
    * age_vault::Role        (account::Role)
    * age_vault::Error       (error::Error)
    * age_vault::Result      (error::Result)

## Type: Role (enum)

Defined in account.rs. Represents the authorization role assigned to an
account.

Variants:

    * Admin         - Full privileges (default administrative role).
    * User          - Standard user.
    * Custom(String) - Arbitrary role defined by a string.

What: A simple tagged enum to categorize accounts. Currently the vault itself
does not enforce role-based access control (RBAC) on operations; this is left
to the consuming application. However, the enum supports serialization so roles
can be persisted and used in application-level authorization.

How: Construct directly:

    Code: Rust
    let admin = Role::Admin;
    let user = Role::User;
    let manager = Role::Custom("manager".into());

Why: Providing built-in roles and a custom variant gives flexibility for future
extensions without breaking the data model.

## Type: Account (struct)

Defined in account.rs. Represents a named identity with an age keypair stored
securely in the vault.

Fields (all public):

    Name                 Type     Description
    ----                 ----     -----------
    id                   String   Unique identifier (UUID v4).
    name                 String   Human-readable account name, must be unique
                                  within a single vault.
    role                 Role     Role assigned to the account.
    public_key           String   Age public key (e.g., "age1...") for
                                  encryption.
    encrypted_secret_key Vec<u8>  Age secret key encrypted with the vault's
                                  Key Encryption Key (KEK). Never stored in
                                  plaintext.
    enabled              bool     Whether the account is active. Disabled
                                  accounts are still stored but may be ignored
                                  by application logic.

What: An Account is the core identity object. It encapsulates everything needed
to encrypt data for this identity (via the public key) and, after KEK
decryption, decrypt data intended for it.

How: Usually created via Vault::add_account. Manual construction is possible
but requires generating a proper age keypair and encrypting the secret key
with the correct KEK.

Why: Separating the public key (plaintext) and encrypted secret key allows the
vault to list accounts and encrypt for them without exposing the master
password or KEK after opening. The secret key is only decrypted when needed for
a decryption operation, minimizing exposure time.

## Type: Vault (struct)

The primary entry point. A Vault instance holds a connection to an encrypted
database (neuxdb) and the derived Key Encryption Key (KEK) in memory.

Fields (internal):
_ db: neuxdb::Database - Embedded database file, encrypted with master pw.
_ kek: secrecy::SecretString - Key Encryption Key derived from master
password and salt. Zeroized on drop. \* salt: Vec<u8> - Random 16-byte salt for KEK derivation, also stored in DB.

Methods:

Method: Vault::create

```

Signature:
    pub fn create(
        db_path: impl Into<PathBuf>,
        master_password: &str
    ) -> Result<Self>

What: Creates a new vault file at db_path. The database is initialized with two
tables (accounts, _metadata), a random 16-byte salt is generated and stored in
_metadata, and the KEK is derived via Argon2id(password, salt). The accounts
table is created empty.

Parameters:
    Name               Type        Description
    ----               ----        -----------
    db_path            PathBuf     Path to the database file to create.
    master_password    &str        Master password; must be strong.
                                   Used to encrypt the database and derive KEK.

Returns: A Vault instance ready for account operations.

Errors: Error::Db (database creation), Error::Kdf (key derivation failure),
Error::Io.

Example:

    Code: Rust
    use age_vault::Vault;
    let vault = Vault::create("./vault.db", "secure_password")?;

Why: The design deliberately uses a random salt per vault so that even if the
same master password is reused across vaults, the derived KEK is different.
The KEK is used to protect account secret keys, while the database encryption
is handled by neuxdb's own password-based encryption (which may also use the
same master password). This provides defense-in-depth: an attacker who
compromises the database layer would still need the KEK (or master password) to
decrypt individual secret keys.

Method: Vault::open
~~~~~~~~~~~~~~~~~~~

Signature:
    pub fn open(
        db_path: impl Into<PathBuf>,
        master_password: &str
    ) -> Result<Self>

What: Opens an existing vault file. Reads the salt from the _metadata table,
re-derives the KEK from the master password and salt, and prepares the accounts
table for use.

Parameters:
    Name               Type     Description
    ----               ----     -----------
    db_path            PathBuf  Path to existing vault database file.
    master_password    &str     Master password (must match creation password).

Returns: Vault instance if password and salt are correct.

Errors: Error::Db (database open failure), Error::DecryptionFailed (salt not
found or base64 decode failure), Error::Kdf (key derivation failure),
Error::InvalidMasterPassword (indirectly, when later operations fail).

Example:

    Code: Rust
    use age_vault::Vault;
    let vault = Vault::open("./vault.db", "secure_password")?;

Why: The KEK is re-derived every time the vault is opened. No stored hash of
the master password is compared; correctness is validated implicitly when
decrypting account secret keys later. If the password is wrong, decryption of
any secret key will fail with Error::DecryptionFailed.

Method: Vault::add_account
```

Signature:
pub fn add_account(
&mut self,
name: &str,
role: Role
) -> Result<Account>

What: Generates a new age keypair, encrypts the secret key with the vault's
KEK, and stores the resulting Account in the database. Returns the newly
created account.

Parameters:
Name Type Description
---- ---- -----------
name &str Desired account name. Must be unique within the vault.
role Role Role to assign (e.g., Role::Admin, Role::User).

Returns: The created Account (with public_key, etc.).

Errors: Error::AccountExists if name is already in use. Error::KeyGen if age
keypair generation fails. Error::Crypto if secret key encryption fails.
Error::Db or serialization errors from store.

Example:

    Code: Rust
    let alice = vault.add_account("alice", Role::Admin)?;

Why: The secret key is encrypted immediately with the KEK and never stored in
plaintext. The KEK is held only in memory as a SecretString and is zeroized
on vault drop. This reduces the risk of secret key exposure.

Method: Vault::remove_account

```

Signature:
    pub fn remove_account(&mut self, name: &str) -> Result<()>

What: Deletes the account identified by name from the database.

Parameters:
    Name    Type    Description
    ----    ----    -----------
    name    &str    Name of the account to remove.

Returns: Ok(()) on success.

Errors: Error::AccountNotFound if name does not exist. Error::Db on deletion or
commit failure.

Example:

    Code: Rust
    vault.remove_account("bob")?;

Why: The method uses the account's unique ID (derived from the name lookup)
to delete the database row, ensuring that even if multiple accounts had the same
name (which is prevented by uniqueness), the correct one is removed.

Method: Vault::list_accounts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Signature:
    pub fn list_accounts(&self) -> Result<Vec<Account>>

What: Returns a vector of all accounts stored in the vault. The returned
accounts contain encrypted secret keys (still encrypted with KEK) and public
keys.

Parameters: None.

Returns: Vec<Account> of all accounts.

Errors: Error::Db, Error::Serde (deserialization), Error::DecryptionFailed
(base64 decoding issues).

Example:

    Code: Rust
    for acc in vault.list_accounts()? {
        println!("{}: {}", acc.name, acc.public_key);
    }

Why: The list is useful for displaying available recipients to a user. Note
that the encrypted secret keys are included in the returned structs; they
cannot be decrypted without the KEK, which is not exposed via this API.

Method: Vault::encrypt_for
~~~~~~~~~~~~~~~~~~~~~~~~~~

Signature:
    pub fn encrypt_for(
        &self,
        account_names: &[&str],
        plaintext: &[u8]
    ) -> Result<Vec<u8>>

What: Encrypts arbitrary bytes for one or more accounts using age's
multi-recipient encryption. Each named account's public key is fetched and used
as a recipient.

Parameters:
    Name             Type          Description
    ----             ----          -----------
    account_names    &[&str]       Slice of account names that will be able
                                   to decrypt.
    plaintext        &[u8]         Data to encrypt.

Returns: Ciphertext as Vec<u8>.

Errors: Error::AccountNotFound if any name does not exist. Error::Crypto if
age encryption fails.

Example:

    Code: Rust
    let cipher = vault.encrypt_for(
        &["alice", "bob"],
        b"top secret"
    )?;

Why: This abstracts away the complexity of mapping human-readable names to
public keys and calling age's multi-recipient encrypt. It ensures that the
ciphertext header contains all necessary recipient information.

Method: Vault::decrypt_with
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Signature:
    pub fn decrypt_with(
        &self,
        account_name: &str,
        ciphertext: &[u8]
    ) -> Result<Vec<u8>>

What: Decrypts ciphertext that was encrypted for the named account. The
account's encrypted secret key is first decrypted using the KEK, then the
resulting age identity is used to decrypt the ciphertext.

Parameters:
    Name             Type    Description
    ----             ----    -----------
    account_name     &str    Name of the account whose secret key will be used.
    ciphertext       &[u8]   Ciphertext produced by encrypt_for or any
                             age-compatible tool.

Returns: Plaintext as Vec<u8>.

Errors: Error::AccountNotFound, Error::DecryptionFailed (if secret key
decryption fails due to wrong password/corruption, or age decryption fails).

Example:

    Code: Rust
    let plain = vault.decrypt_with("alice", &ciphertext)?;

Why: The KEK is only used temporarily to decrypt the secret key; the plain
secret key is then immediately used for decryption and dropped. This minimizes
the window during which the secret key is in plaintext memory.

Module: crypto (public functions)
---------------------------------

The crypto module provides lower-level key derivation and key-wrapping
utilities. They are public for advanced usage but are typically used internally
by Vault.

Function: derive_kek
~~~~~~~~~~~~~~~~~~~~

Signature:
    pub fn derive_kek(
        master_password: &str,
        salt_bytes: &[u8]
    ) -> Result<SecretString>

What: Derives a Key Encryption Key (KEK) from a master password and salt using
Argon2id with default parameters (memory, iterations as per argon2 crate
defaults). The output is a SecretString that zeroizes on drop.

Parameters:
    Name               Type    Description
    ----               ----    -----------
    master_password    &str    Master password.
    salt_bytes         &[u8]   Salt (recommended 16 bytes).

Returns: SecretString containing the derived KEK.

Errors: Error::Kdf if salt encoding or Argon2 hashing fails.

Function: encrypt_secret_key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Signature:
    pub fn encrypt_secret_key(
        secret_key: &str,
        kek: &str
    ) -> Result<Vec<u8>>

What: Encrypts an age secret key (in its text representation) with a KEK using
age's passphrase encryption (age_crypto::encrypt_with_passphrase). The output
is a binary ciphertext that can be stored.

Parameters:
    Name          Type    Description
    ----          ----    -----------
    secret_key    &str    Plaintext age secret key (e.g., "AGE-SECRET-KEY-...").
    kek           &str    Key encryption key (derived from derive_kek).

Returns: Encrypted bytes.

Errors: Error::Crypto if age encryption fails.

Function: decrypt_secret_key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Signature:
    pub fn decrypt_secret_key(
        encrypted: &[u8],
        kek: &str
    ) -> Result<String>

What: Reverse of encrypt_secret_key. Decrypts using the KEK and returns the
UTF-8 secret key string.

Parameters:
    Name        Type    Description
    ----        ----    -----------
    encrypted   &[u8]   Encrypted secret key bytes.
    kek         &str    Key encryption key.

Returns: Decrypted age secret key string.

Errors: Error::Crypto if decryption fails (wrong KEK, corruption);
Error::DecryptionFailed if output is not valid UTF-8.

Module: store (public functions)
--------------------------------

The store module provides direct access to the underlying neuxdb database
operations. These are public but intended primarily for internal use by Vault.

Function: init_accounts_table
```

Signature: pub fn init_accounts_table(db: &mut Database) -> Result<()>
Creates the "accounts" table with columns (id, name, role, public_key,
encrypted_secret_key, enabled) if it doesn't exist. Idempotent.

Function: init_metadata_table

```

Signature: pub fn init_metadata_table(db: &mut Database) -> Result<()>
Creates the "_metadata" key-value table. Idempotent.

Function: save_account
~~~~~~~~~~~~~~~~~~~~~~

Signature: pub fn save_account(db: &mut Database, account: &Account) -> Result<()>
Serializes an account and inserts it into the accounts table. Role is stored as
JSON, encrypted secret key as base64.

Function: load_accounts
~~~~~~~~~~~~~~~~~~~~~~~

Signature: pub fn load_accounts(db: &Database) -> Result<Vec<Account>>
Reads all rows from accounts table, deserializing each.

Function: save_metadata_salt
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Signature: pub fn save_metadata_salt(db: &mut Database, salt: &[u8]) -> Result<()>
Stores the salt bytes (base64-encoded) under key "salt" in _metadata.

Function: load_metadata_salt
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Signature: pub fn load_metadata_salt(db: &Database) -> Result<Vec<u8>>
Retrieves and decodes the salt from _metadata.

Error Type: Error (enum)
-------------------------

Defined in error.rs. All operations return Result<T, Error>. The Error enum
provides both automatic conversion from dependency errors (via #[from]) and
explicit vault-specific variants.

Variants:

    * Io(std::io::Error)               - I/O error.
    * Db(neuxdb::Error)                - Database error.
    * Config(neuxcfg::NeuxcfgError)    - Configuration error.
    * Crypto(age_crypto::Error)        - Cryptographic error.
    * KeyGen(age_setup::Error)         - Key generation error.
    * Kdf(String)                      - Argon2 key derivation error.
    * Serde(serde_json::Error)         - Serialization error.
    * AccountNotFound(String)          - Account name missing.
    * AccountExists(String)            - Account name already present.
    * InvalidMasterPassword            - Master password invalid.
    * DecryptionFailed(String)         - Decryption failure.
    * EncryptionFailed(String)         - Encryption failure.

The error type implements std::error::Error and Display via thiserror. It is
Send + Sync, making it suitable for use in async contexts.

Result type alias:

    type Result<T> = std::result::Result<T, Error>;

ARCHITECTURE & INTERNALS
========================

This section explains the system design, data flow, and rationale behind key
decisions. The vault is a layered architecture where the Vault struct
orchestrates storage, cryptographic, and identity modules.

High-level component interaction diagram (text flow):

    User Application
        |
        | calls Vault::create, open, add_account, encrypt_for, decrypt_with
        |
    [Vault] -- holds Database, KEK, salt
        |  |
        |  | uses crypto::derive_kek, encrypt_secret_key, decrypt_secret_key
        |  |
        |  +---> [crypto module] -- argon2, age_crypto (passphrase encrypt)
        |  |
        |  +---> [store module] -- neuxdb (embedded database)
        |
        +-------> [account] struct and Role enum

Data Flow:

1. Vault Creation:
   - Generate 16 random bytes (salt).
   - Derive KEK = Argon2id(password, salt).
   - Create encrypted database file with the master password (neuxdb).
   - Init tables (accounts, _metadata).
   - Store salt in _metadata.
   - Commit.

2. Adding an Account:
   - Check for duplicate name.
   - Generate age keypair (age_setup::build_keypair).
   - Encrypt secret key: ciphertext = age_crypto::encrypt_with_passphrase(secret_key, KEK).
   - Build Account struct (id=UUIDv4, name, role, public_key, encrypted_secret_key, enabled=true).
   - Store via store::save_account (role -> JSON, enc_key -> base64, insert into neuxdb).
   - Commit.

3. Opening a Vault:
   - Open encrypted database with master password (neuxdb).
   - Load salt from _metadata.
   - Derive KEK = Argon2id(password, salt).
   - Accounts table is available for queries.

4. Encrypting Data for Recipients:
   - For each recipient name, fetch Account from DB (store::load_accounts, filter).
   - Collect public keys.
   - age_crypto::encrypt(plaintext, &public_keys) -> ciphertext.

5. Decrypting Data with an Account:
   - Fetch Account by name.
   - Decrypt secret key: age_crypto::decrypt_with_passphrase(encrypted_secret_key, KEK).
   - Use decrypted secret key to age_crypto::decrypt(ciphertext, &secret_key) -> plaintext.

Design Decisions:

* Defense-in-depth encryption: The vault uses two encryption layers: the neuxdb
  file is encrypted with the master password, and the account secret keys are
  encrypted with a separate KEK derived from the same password plus a unique
  salt. This means that even if the database encryption is bypassed (e.g., via
  a vulnerability in neuxdb), the attacker still needs to derive the KEK to
  recover the secret keys. The salt is stored in the _metadata table, so an
  offline attacker would need both the database file and the master password
  to access secret keys.

* Why Argon2id: Argon2id is the recommended password-hashing algorithm,
  combining resistance to side-channel and GPU attacks. Default parameters are
  used; future versions may expose tuning knobs for memory/iterations.

* Why base64 for encrypted secret keys and salt: Neuxdb stores text columns; to
  safely store arbitrary binary (ciphertext), base64 encoding ensures
  compatibility.

* Why a separate KEK: The master password is used for both the database
  encryption (neuxdb's internal mechanism) and the KEK derivation. Separating
  the KEK derivation with a salt means the key material used to protect the
  most sensitive items (age secret keys) is not directly the same as the
  database encryption key. This provides a security boundary even if the
  database's encryption key is extracted at runtime.

* The crate re-exports important types for ergonomics: users don't need to
  know the internal module structure.

GUIDES & TUTORIALS
==================

Basic Usage: Setting Up a Vault and Managing Accounts

Step 1: Create a new vault.

    Code: Rust
    use age_vault::Vault;
    let mut vault = Vault::create("identities.age", "my_master_pw")?;

Step 2: Add accounts for your users or devices.

    Code: Rust
    use age_vault::Role;
    let admin_acc = vault.add_account("admin", Role::Admin)?;
    let user_acc = vault.add_account("laptop", Role::User)?;

Step 3: Encrypt a confidential document for both admin and laptop.

    Code: Rust
    let doc = b"Quarterly financial report";
    let ciphertext = vault.encrypt_for(&["admin", "laptop"], doc)?;

Step 4: Later, decrypt the document using the admin identity.

    Code: Rust
    let recovered = vault.decrypt_with("admin", &ciphertext)?;
    assert_eq!(recovered, doc);

Step 5: Remove an account when no longer needed.

    Code: Rust
    vault.remove_account("laptop")?;

Step 6: List all current accounts.

    Code: Rust
    for acc in vault.list_accounts()? {
        println!("{} - {}", acc.name, acc.public_key);
    }

Configuration Reference
-----------------------

All configuration is currently done via compile-time feature flags or
dependency versions. The argon2 parameters are fixed to the crate's defaults;
if stronger parameters are needed, you might need to fork or propose a feature
to expose settings.

The vault database is a single neuxdb file; its path is determined at creation
time. You may want to place it in a suitable application data directory.

Troubleshooting FAQ
-------------------

Q: I get "Invalid master password" when opening a vault.
A: The vault does not store a password hash; it will only report
InvalidMasterPassword indirectly. Most likely you will receive a
DecryptionFailed error when trying to decrypt a secret key. Double-check the
password and ensure the vault file is not corrupted.

Q: An account name already exists. How can I handle it?
A: The add_account method returns Error::AccountExists. You can either remove
the existing account first or choose a different name.

Q: Can I rename an account?
A: Not directly. You can remove it and re-add with a new name, but note that
the new account will have a different keypair, so previously encrypted data for
the old account will be inaccessible.

Q: How do I change the master password?
A: Currently not supported natively. You would need to create a new vault,
iterate over all accounts, decrypt each secret key with the old KEK, re-encrypt
with the new KEK, and save them in the new vault. Future versions may add a
password change function.

CONTRIBUTING & DEVELOPMENT
==========================

This section is for developers who want to modify the crate itself.

Setup Instructions
------------------

1. Clone the repository (see repository URL in Cargo.toml).

2. Ensure you have a recent Rust toolchain (edition 2024, Rust >= 1.70 likely).

3. Build: Command: cargo build

4. Run tests: Command: cargo test

5. Generate local documentation: Command: cargo doc --open

Coding Standards
----------------

* Follow standard Rust conventions (rustfmt, clippy).
* All public items must have documentation comments (enforced by
  #![warn(missing_docs)] in lib.rs or Cargo.toml lints).
* Unsafe code is warned against; if absolutely necessary, document safety
  invariants.
* Use thiserror for error types, secrecy for sensitive strings, and keep the
  crate no_std-friendly (currently uses std, but might be considered).
* Lints: unsafe_code = "warn", missing_docs = "warn", unused = "warn",
  deprecated = "warn" (see Cargo.toml).

Testing Strategy
----------------

* Unit tests are located in each module (e.g., vault.rs) but not shown here;
  they likely use the test vault paths as seen in doc examples. The dev
  dependency `criterion` suggests benchmarks exist under benches/.
* Integration tests may exist under tests/ (excluded by package metadata).
* Run all tests: cargo test --all-features

Pull Request Process
--------------------

* Fork the repository.
* Create a feature branch: git checkout -b feat/your-feature
* Ensure all tests pass: cargo test
* If adding public API, update documentation accordingly.
* Submit a PR with a clear description.

License
=======

This crate is licensed under the MIT license. See the LICENSE file in the
repository root.

Repository: https://github.com/neuxdotdev/age-vault
Documentation: https://docs.rs/age-vault
Authors: neuxdotdev <neuxdev1@gmail.com>