palyra-vault crate provides a secure, multi-backend storage system for sensitive information such as API keys, OAuth tokens, and certificates. It implements Envelope Encryption to ensure that data remains encrypted at rest, even if the underlying storage medium is compromised.
Architecture and Design
The Vault is designed around a hierarchical scoping system and a pluggable backend architecture. It distinguishes between the storage of encrypted blobs and the management of secret metadata.Core Entities
| Entity | Description | File Reference |
|---|---|---|
Vault | The primary entry point for managing secrets. | crates/palyra-vault/src/api.rs#12-12 |
VaultScope | Defines the ownership/visibility of a secret (e.g., global, user, plugin). | crates/palyra-vault/src/scope.rs#16-16 |
SensitiveBytes | A wrapper for Vec<u8> that zeroizes memory on drop to prevent leakage. | crates/palyra-vault/src/crypto.rs#14-14 |
BackendKind | Enumeration of supported storage backends (Filesystem, Keychain, DPAPI). | crates/palyra-vault/src/backend.rs#41-49 |
EnvelopePayload | The serialized structure containing encrypted data and its wrapped DEK. | crates/palyra-vault/src/envelope.rs#14-24 |
Code Entity Space Mapping
The following diagram illustrates how natural language concepts map to specific code structures within thepalyra-vault crate.
Vault System Component Map
Sources: crates/palyra-vault/src/scope.rs#16-16, crates/palyra-vault/src/envelope.rs#14-24, crates/palyra-vault/src/backend.rs#88-93, crates/palyra-vault/src/api.rs#12-12
Envelope Encryption Flow
Palyra uses a two-tier encryption strategy:- Data Encryption Key (DEK): A unique, randomly generated 32-byte key used to encrypt the actual secret value using
CHACHA20_POLY1305crates/palyra-vault/src/envelope.rs#31-32. - Key Encryption Key (KEK): A master key used to encrypt the DEK. The KEK is derived or stored securely depending on the backend crates/palyra-vault/src/envelope.rs#33-33.
The seal and open Process
When a secret is stored:
- A new DEK is generated via
getrandomcrates/palyra-vault/src/envelope.rs#3-3. - The secret is encrypted with the DEK and Additional Authenticated Data (AAD) crates/palyra-vault/src/envelope.rs#32-32.
- The DEK itself is encrypted with the KEK and the same AAD crates/palyra-vault/src/envelope.rs#33-33.
- The resulting
EnvelopePayloadis stored by the backend.
Storage Backends
The vault supports multiple backends via theBlobBackend trait crates/palyra-vault/src/backend.rs#88-93. The system can automatically select the most secure available backend for the current platform crates/palyra-vault/src/backend.rs#135-158.
Supported Backends
| Kind | Platform | Description |
|---|---|---|
EncryptedFile | All | Stores encrypted JSON envelopes in the objects/ directory crates/palyra-vault/src/backend.rs#25-25. |
MacosKeychain | macOS | Uses the native macOS Security framework crates/palyra-vault/src/backend.rs#44-44. |
LinuxSecretService | Linux | Integrates with libsecret / DBus Secret Service crates/palyra-vault/src/backend.rs#46-46. |
WindowsDpapi | Windows | Uses Data Protection API (DPAPI) to bind secrets to the user’s login crates/palyra-vault/src/backend.rs#48-48. |
Backend Selection Logic
Theselect_backend function determines which backend to initialize. It checks for a backend.kind marker file in the vault root crates/palyra-vault/src/backend.rs#95-133. If no marker exists, it uses the BackendPreference (defaulting to Auto) to pick the best available option.
Sources: crates/palyra-vault/src/backend.rs#95-133, crates/palyra-vault/src/backend.rs#135-158
Integration with Daemon and CLI
Daemon Integration
Thepalyrad daemon initializes its vault during startup, typically pointing to a directory within the PALYRA_STATE_ROOT crates/palyra-daemon/tests/health_endpoint.rs#63-66. The daemon uses the vault to store:
- Model provider API keys.
- OAuth refresh tokens for auth profiles.
- Skill-specific configuration secrets.
CLI Commands
Thepalyra CLI provides a dedicated secrets command group for manual management crates/palyra-cli/src/commands/secrets.rs#61-61.
- Set: Reads from STDIN to avoid leaking secrets in shell history crates/palyra-cli/src/commands/secrets.rs#63-78.
- Get: Redacts output by default unless the
--revealflag is used crates/palyra-cli/src/commands/secrets.rs#79-101. - Audit: Inspects configuration files to ensure all required secret references are valid and present in the vault crates/palyra-cli/src/commands/secrets.rs#147-163.
Security Hardening
SensitiveBytes
TheSensitiveBytes struct crates/palyra-vault/src/crypto.rs#14-14 ensures that sensitive data is scrubbed from memory. It wraps a Vec<u8> and implements a custom Drop trait that fills the underlying buffer with zeros.
Filesystem Permissions
The vault enforces strict filesystem permissions. Both the root vault directory and individual secret files are checked to ensure they are owned by the current user and have restricted access (e.g.,0o700 for directories and 0o600 for files on Unix) crates/palyra-vault/src/filesystem.rs#15-15.
AAD (Additional Authenticated Data)
To prevent “secret substitution” attacks (where an attacker moves an encrypted blob from one key to another), the Vault includes theVaultScope and key name in the AAD during the encryption process crates/palyra-vault/src/crypto.rs#18-18. If a blob is moved to a different path, decryption will fail because the AAD won’t match.
Sources: crates/palyra-vault/src/crypto.rs#14-18, crates/palyra-vault/src/filesystem.rs#15-15, crates/palyra-vault/src/envelope.rs#26-30