tsafe-core

Core library for the tsafe local secret vault.

Provides the encrypted vault (Argon2id KDF + XChaCha20-Poly1305 by default, AES-256-GCM via the fips feature), RBAC access profiles, an HMAC-chained audit log, CloudEvents eventing, OS keyring / biometric integration, and all foundational data types.

Should you depend on this directly?

Most users should install the CLI:

cargo install tsafe-cli

Depend on tsafe-core when you need programmatic vault access from Rust code — for example, tooling that reads or writes secrets as part of a build pipeline or a custom secret-rotation job.

Key types

Type	Purpose
`Vault`	Open, read, write, rotate, and snapshot an encrypted vault file
`VaultFile` / `SecretEntry`	On-disk serde types (schema `tsafe/vault/v1`)
`SafeError` / `SafeResult<T>`	Typed error enum; all fallible APIs return this
`AuditLog` / `AuditEntry`	Append-only HMAC-SHA256-chained audit trail (`.audit.jsonl`)
`RbacProfile`	`ReadOnly` vs `ReadWrite` access gating with role-scoped key derivation
`keyring_store`	OS credential store integration (Windows DPAPI / macOS Touch ID Keychain / libsecret)
`snapshot`	Point-in-time vault backups and restore
`gen`	Secure passphrase and token generation
`totp`	TOTP code computation
`events`	CloudEvents-compatible vault event emission
`contracts`	Authority contract evaluation (exec policy, network policy, trust levels)

Example

use std::path::Path;
use tsafe_core::vault::Vault;
use tsafe_core::errors::SafeResult;

fn read_secret(vault_path: &Path, password: &[u8], key: &str) -> SafeResult<String> {
    let vault = Vault::open(vault_path, password)?;
    vault.get(key)
}

fn write_secret(vault_path: &Path, password: &[u8], key: &str, value: &str) -> SafeResult<()> {
    let mut vault = Vault::open(vault_path, password)?;
    vault.set(key, value, &Default::default(), false)?;
    vault.save()?;
    Ok(())
}

Key names must start with a letter or underscore and may contain letters, digits, _, -, ., and / (no consecutive separators). Namespace-style keys like myapp/DB_PASSWORD and github.com.token are valid.

Vault encryption

Layer	Algorithm
KDF	Argon2id (m=65536 KiB, t=3, p=1 by default)
Cipher (default)	XChaCha20-Poly1305
Cipher (`fips` feature)	AES-256-GCM
Key schedule	HKDF-SHA256 (purpose-separated sub-keys)
Team vault wrapping	age X25519

The vault file is plain JSON with all secret values individually encrypted. Atomic writes (temp file + rename) prevent partial-write corruption.

Feature flags

Feature	What it adds	Default
`fips`	AES-256-GCM cipher via `aes-gcm`; XChaCha20-Poly1305 remains available	no
`nats`	NATS messaging backend for the events module	no
`biometric`	Activates the biometric-gated keyring path in `keyring_store` (macOS Touch ID / Windows Hello)	no

Logging

tsafe-core emits structured traces via the tracing crate. No output appears unless a subscriber is installed by the caller. All secret-bearing parameters (password, value, key) are skipped in every #[instrument] call site.

License

Licensed under either of MIT or Apache-2.0 at your option.

Repository: https://github.com/0ryant/tsafe

tsafe-core 1.0.12