palyra-vault crate provides a secure, platform-native abstraction for storing sensitive credentials (API keys, tokens, certificates) used by the Palyra daemon and CLI. It implements Envelope Encryption to ensure that even if the underlying storage is compromised, the secrets remain encrypted with keys protected by the operating system’s native secure enclave (e.g., macOS Keychain, Windows DPAPI, or Linux Secret Service).
Vault Architecture & Data Flow
TheVault struct is the primary entry point for secret operations crates/palyra-vault/src/api.rs#12-12. It abstracts over different BlobBackend implementations that handle the physical storage of encrypted blobs.
Secret Lifecycle Diagram
The following diagram illustrates the flow of a secret from the CLI into the platform-native storage. Title: Secret Storage Data Flow Sources: crates/palyra-cli/src/commands/secrets.rs#61-61, crates/palyra-vault/src/api.rs#12-12, crates/palyra-vault/src/backend.rs#88-93, crates/palyra-vault/src/envelope.rs#26-26Envelope Encryption Implementation
Palyra uses a two-tier encryption strategy:- DEK (Data Encryption Key): A unique, randomly generated 32-byte key used to encrypt the actual secret value using
CHACHA20_POLY1305crates/palyra-vault/src/envelope.rs#8-10. - KEK (Key Encryption Key): A platform-specific master key that encrypts the DEK.
- AAD (Additional Authenticated Data): The secret’s scope and key name are bound to the ciphertext to prevent “cut-and-paste” attacks where an encrypted blob is moved to a different key name crates/palyra-vault/src/crypto.rs#18-18.
Envelope Structure
TheEnvelopePayload contains all metadata required to reconstruct the secret, excluding the KEK crates/palyra-vault/src/envelope.rs#13-24.
| Field | Description |
|---|---|
version | Envelope version (currently 1) |
algorithm | chacha20_poly1305 |
aad_b64 | Base64 encoded Additional Authenticated Data |
secret_ciphertext_b64 | The actual secret encrypted with the DEK |
dek_ciphertext_b64 | The DEK encrypted with the platform KEK |
Storage Backends
Theselect_backend function determines which storage provider to use based on the operating system and availability crates/palyra-vault/src/backend.rs#95-133.
Backend Matrix
| Kind | Platform | Implementation Detail |
|---|---|---|
MacosKeychain | macOS | Uses security CLI or Security.framework to store keys crates/palyra-vault/src/backend.rs#44-44. |
WindowsDpapi | Windows | Uses CryptProtectData to bind secrets to the user’s login crates/palyra-vault/src/backend.rs#48-48. |
LinuxSecretService | Linux | Integrates with libsecret (Gnome Keyring/KWallet) crates/palyra-vault/src/backend.rs#46-46. |
EncryptedFile | All | Fallback that stores encrypted JSON files in ~/.palyra/vault/objects/ crates/palyra-vault/src/backend.rs#42-42. |
Filesystem Layout
When using theEncryptedFile backend or storing vault metadata, the following layout is used:
backend.kind: A marker file identifying the active backend crates/palyra-vault/src/backend.rs#24-24.objects/: Directory containing the encrypted blobs crates/palyra-vault/src/backend.rs#25-25.objects.store.json: Index of metadata for stored secrets crates/palyra-vault/src/backend.rs#26-26.
Scope Management
Secrets are partitioned into scopes to enforce isolation between different components (e.g., global settings vs. specific agent skills).VaultScope: A validated string representing the ownership of the secret crates/palyra-vault/src/scope.rs#7-7.global: Reserved for system-wide configuration (e.g.,openai_api_key) crates/palyra-cli/tests/secrets_cli.rs#63-63.skill:<id>: Scopes restricted to specific WASM plugins.
CLI Secret Commands
Thepalyra CLI provides a suite of commands for managing the vault. These commands interface with the Vault via the open_cli_vault() helper crates/palyra-cli/src/commands/secrets.rs#64-64.
Command Mapping
Title: CLI Secret Command Implementation Sources: crates/palyra-cli/src/commands/secrets.rs#61-147, crates/palyra-vault/src/api.rs#12-12Security Auditing
Thesecrets audit command crates/palyra-cli/src/commands/secrets.rs#147-163 scans configuration files for:
- Plaintext Secrets: Detecting hardcoded keys that should be in the vault.
- Broken References:
vault_refentries inpalyra.tomlthat point to missing vault keys crates/palyra-cli/tests/secrets_cli.rs#185-188. - Strict Mode: Can be used in CI/CD to fail builds if blocking findings are discovered crates/palyra-cli/src/commands/secrets.rs#156-161.