Struct Vault 

pub struct Vault { /* private fields */ }

Encrypted vault for persisting auth state inside reserved pager pages.

The vault key is derived from the certificate supplied via REDDB_CERTIFICATE (or its _FILE companion, expanded at process start). A random salt is generated on first write and persisted inside the vault page for format continuity.

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) -> Result<Self, VaultError>

Open or prepare a vault backed by reserved pager pages.

Key derivation requires REDDB_CERTIFICATE. If it is not 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.

Requires REDDB_CERTIFICATE.

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 for envelope framing. Certificate-based imports derive the same wrapping key from REDDB_CERTIFICATE. The blob is hex-encoded so it can live inside JSONL dumps.

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

Decrypt a logical export blob using the same certificate env var as normal vault open.

pub fn unseal_logical_export_with_certificate( blob_hex: &str, certificate_hex: &str, ) -> Result<VaultState, VaultError>

Deterministic 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).