palyra-vault crate provides a secure, platform-integrated mechanism for storing sensitive credentials such as API keys, tokens, and encryption keys. It abstracts away the complexities of OS-specific secret stores while providing a unified “Vault Reference” system used throughout the Palyra ecosystem to avoid persisting plaintext secrets in configuration files.
Vault Architecture and Backends
The Vault operates as a blob storage system where secrets are organized by Scopes and Keys. Access is managed through theVault struct, which delegates persistence to a BlobBackend crates/palyra-vault/src/backend.rs#88-93.
Backend Selection
Palyra supports multiple backends, defaulting to the most secure option available for the host operating system crates/palyra-vault/src/backend.rs#135-158:| Backend Kind | Platform | Implementation |
|---|---|---|
MacosKeychain | macOS | Uses the system Keychain via security CLI crates/palyra-vault/src/backend.rs#29-29. |
LinuxSecretService | Linux | Uses libsecret / secret-tool crates/palyra-vault/src/backend.rs#31-35. |
WindowsDpapi | Windows | Uses Data Protection API (DPAPI) to encrypt blobs for the current user crates/palyra-vault/src/backend.rs#16-16. |
EncryptedFile | All | Encrypted SQLite-style file backend (fallback or explicit preference) crates/palyra-vault/src/backend.rs#42-42. |
BackendKind is persisted in a backend.kind marker file within the vault root to ensure consistency across sessions crates/palyra-vault/src/backend.rs#24-24.
Logical Data Flow
The following diagram illustrates how theVault API interacts with the platform-specific backends.
Vault Backend Dispatch
Sources: crates/palyra-vault/src/backend.rs#88-191, crates/palyra-vault/src/api.rs#12-12
Vault Scopes and References
Scoping
Secrets are addressed using aVaultScope, which is a hierarchical identifier (e.g., global, plugins/github). Scopes prevent key collisions between different components of the system crates/palyra-vault/src/scope.rs#16-16.
Vault Refs (vault://)
A Vault Ref is a URI-like string formatted as vault://scope/key. Instead of storing an API key directly in palyra.toml, the configuration stores the reference.
- Daemon Resolution: When the daemon encounters a
vault_refin its config, it uses theVaultinstance to fetch theSensitiveBytesat runtime. - CLI Integration: The CLI command
secrets configureautomates the process of setting a secret in the vault and updating the configuration file with the corresponding reference crates/palyra-cli/src/commands/secrets.rs#144-184.
Filesystem Layout and Security
The vault enforces strict filesystem permissions to ensure that only the owner of the process can read the secret metadata or the encrypted blobs.- Root Directory: Typically located at
$PALYRA_VAULT_DIRor within the state root. - Permissions: The system uses
ensure_owner_only_dirandensure_owner_only_fileto set0700and0600permissions respectively on Unix-like systems crates/palyra-vault/src/filesystem.rs#15-15. - Object Storage: In the
EncryptedFilebackend, objects are stored in anobjects/directory, with filenames derived from a hash of the scope and key crates/palyra-vault/src/backend.rs#25-27.
CLI Secret Management
Thepalyra CLI provides a suite of commands for managing the vault via run_secrets crates/palyra-cli/src/commands/secrets.rs#61-61.
Common Operations
- Set:
palyra secrets set <scope> <key> --value-stdinreads secret bytes from stdin to avoid leaking them in shell history crates/palyra-cli/src/args/secrets.rs#5-10. - Get:
palyra secrets get <scope> <key> --revealretrieves the secret. Without the--revealflag, the CLI only confirms existence and prints metadata (byte count, timestamps) crates/palyra-cli/src/commands/secrets.rs#79-101. - Audit:
palyra secrets auditscans configuration files to identify plaintext secrets that should be moved to the vault and verifies that allvault://references are resolvable crates/palyra-cli/src/commands/secrets.rs#147-163.
Secret Management Data Flow
This diagram bridges the CLI command space to the internal Vault logic. CLI Secret Operation Flow Sources: crates/palyra-cli/src/commands/secrets.rs#61-78, crates/palyra-vault/src/api.rs#12-12, crates/palyra-vault/src/backend.rs#90-90Implementation Details
Envelope Format
When using theEncryptedFile backend, secrets are stored in an envelope that includes:
- Version: Protocol versioning for future-proofing.
- Nonce: Unique cryptographic nonce for AES-GCM.
- AAD (Additional Authenticated Data): Includes the scope and key to prevent “secret swapping” attacks where an attacker moves an encrypted blob from one key to another.
- Ciphertext: The actual secret data.
Key Functions
select_backend: Probes the environment and returns the appropriateBlobBackendcrates/palyra-vault/src/backend.rs#95-133.put_secret: High-level API to encrypt and store a secret crates/palyra-vault/src/api.rs#12-12.get_secret: High-level API to retrieve and decrypt a secret intoSensitiveBytes, which implementsDropto zeroize memory crates/palyra-vault/src/lib.rs#14-14.