Struct Vault 

pub struct Vault { /* private fields */ }

Encrypted vault for persisting auth state inside reserved pager pages.

The vault key is derived from REDDB_VAULT_KEY env var or a provided passphrase. A random salt is generated on first write and persisted inside the vault page so that re-opening with the same passphrase produces the same derived key.

Implementations

impl Vault

pub fn has_saved_state(pager: &Pager) -> bool

Return true when the pager contains a written vault header.

pub fn open(pager: &Pager, passphrase: Option<&str>) -> Result<Self, VaultError>

Open or prepare a vault backed by reserved pager pages.

Key derivation: REDDB_VAULT_KEY env var takes priority, then the passphrase argument. If neither is set, returns NoKey.

If vault pages already exist in the pager, the salt is read from the existing page content. Otherwise a fresh salt is generated and will be written on the first save() call.

pub fn with_certificate( pager: &Pager, certificate_hex: &str, ) -> Result<Self, VaultError>

Open a vault using a certificate hex string (from bootstrap).

The certificate is used to derive the vault encryption key via Argon2id. This is the primary unseal mechanism introduced by the certificate-based seal system.

pub fn from_env(pager: &Pager) -> Result<Self, VaultError>

Open a vault from environment variables.

Precedence: REDDB_CERTIFICATE (primary) > REDDB_VAULT_KEY (fallback/deprecated).

pub fn with_certificate_bytes( pager: &Pager, certificate: &[u8], ) -> Result<Self, VaultError>

Create a vault keyed by a certificate (raw bytes, not hex).

Used during bootstrap when the certificate is freshly generated and not yet hex-encoded.

pub fn seal_logical_export( &self, state: &VaultState, ) -> Result<String, VaultError>

Encrypt a vault state into a self-contained logical export blob.

The source salt is embedded so passphrase-based imports can derive the same wrapping key without having access to the source .rdb pages. The blob is hex-encoded so it can live inside JSONL dumps.

pub fn unseal_logical_export( blob_hex: &str, passphrase: Option<&str>, ) -> Result<VaultState, VaultError>

Decrypt a logical export blob using the same key precedence as normal vault open: REDDB_CERTIFICATE, REDDB_VAULT_KEY, then the explicit passphrase argument.

pub fn unseal_logical_export_with_passphrase( blob_hex: &str, passphrase: &str, ) -> Result<VaultState, VaultError>

Deterministic test/helper path that ignores vault env vars.

pub fn save(&self, pager: &Pager, state: &VaultState) -> Result<(), VaultError>

Save the given auth state to the encrypted vault pages.

Order of operations is the only thing keeping this crash-safe:

1. Encrypt the serialized state under a fresh nonce.
2. Allocate (or reuse) the data-page chain and write every data page to disk.
3. Free any surplus pages that the previous chain owned.
4. Rewrite the header page in place — this is the commit point. After it lands, load() will follow the new chain.

A crash anywhere before step 4 leaves the existing header (and its chain) intact, so the previous vault snapshot is still readable on the next open.

pub fn load(&self, pager: &Pager) -> Result<Option<VaultState>, VaultError>

Load auth state from the encrypted vault pages.

Returns Ok(None) if the vault pages do not exist yet (fresh DB).