tsafe-core 1.0.12

Core runtime engine for tsafe — encrypted credential storage, process injection contracts, audit log, RBAC
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

# tsafe-core

Core library for the [tsafe](https://crates.io/crates/tsafe-cli) 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

```rust
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`](https://docs.rs/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](LICENSE-MIT) or
[Apache-2.0](LICENSE-APACHE) at your option.

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