palyra-vault crate provides a secure, encrypted storage system for sensitive credentials (API keys, tokens, etc.) used by the Palyra daemon and CLI. It utilizes Envelope Encryption where individual secrets are encrypted with unique data keys, which are in turn protected by a Device Key Encryption Key (KEK) derived from the system’s identity.
Architecture Overview
The Vault is designed to be “zero-trust” regarding the underlying storage medium. Whether secrets are stored in a flat file or a system keychain, the payload is always encrypted before it leaves theVault boundary.
Data Flow & Encryption Logic
- Key Derivation: Upon initialization, the Vault locates the
palyra-identitystore. It extracts the CA private key material crates/palyra-vault/src/crypto.rs#50-78 and uses HKDF-SHA256 with a static salt (palyra.vault.kek.v1) to derive a 32-byte Device KEK crates/palyra-vault/src/crypto.rs#80-87. - Secret Insertion: When
put_secretis called, a random nonce is generated. The secret is encrypted using AES-GCM (viaring) with Additional Authenticated Data (AAD) that binds the secret to its specificVaultScopeandkeycrates/palyra-vault/src/crypto.rs#89-91. - Storage: The encrypted blob is passed to a
BlobBackend.
Entity Mapping: Natural Language to Code
| System Concept | Code Entity | File Path |
|---|---|---|
| Vault Instance | Vault struct | crates/palyra-vault/src/api.rs |
| Encryption Logic | derive_device_kek / seal | crates/palyra-vault/src/crypto.rs |
| Storage Interface | trait BlobBackend | crates/palyra-vault/src/backend.rs#88-93 |
| Scope Enforcement | enum VaultScope | crates/palyra-vault/src/scope.rs |
| Metadata Tracking | MetadataFile | crates/palyra-vault/src/metadata.rs |
Vault Scopes
Secrets are partitioned into scopes to prevent naming collisions and enforce logical separation between global configuration and workspace-specific credentials.| Scope | Storage String | Description |
|---|---|---|
Global | global | System-wide secrets (e.g., primary OpenAI key). |
Workspace | ws:{id} | Secrets tied to a specific project or workspace. |
Principal | pr:{id} | User-specific secrets for multi-tenant environments. |
Storage Backends
The Vault supports multiple backends via theBlobBackend trait. The selection is determined by BackendPreference (Auto vs. EncryptedFile) and the presence of a backend.kind marker file in the vault root crates/palyra-vault/src/backend.rs#95-133.
Backend Implementation Flow
Supported Backends
- EncryptedFile: Stores blobs as individual files in an
objects/directory. Even though the files are on disk, the content is already encrypted by the Vault’s internal crypto crates/palyra-vault/src/backend.rs#194-205. - MacOS Keychain: Utilizes the system
securityframework to store blobs as Generic Password items crates/palyra-vault/src/backend.rs#28-29. - Windows DPAPI: Uses
dpapi_protect_current_userto provide an additional layer of OS-level encryption on top of the Vault’s encryption crates/palyra-vault/src/backend.rs#15-16.
CLI Secret Commands
Thepalyra CLI provides a management interface for the vault, allowing users to set, get, and audit secrets.
Command Execution Logic
Key CLI Operations
set: Reads bytes from STDIN (to avoid shell history leaks) and stores them in the vault crates/palyra-cli/src/commands/secrets.rs#63-78.get: Retrieves a secret. By default, it redacts the output unless the--revealflag is provided crates/palyra-cli/src/commands/secrets.rs#79-101.audit: Scans configuration files (e.g.,palyra.toml) to ensure that sensitive fields usevault_ref(e.g.,global/my_key) instead of plaintext values crates/palyra-cli/src/commands/secrets.rs#147-162.configure: A helper that sets a secret in the vault and simultaneously updates the localpalyra.tomlto reference that secret crates/palyra-cli/tests/secrets_cli.rs#144-162.
Security Hardening
Memory Safety
TheSensitiveBytes wrapper is used for secret material in memory. It implements Drop to zero-fill the underlying buffer when the object goes out of scope, minimizing the window for memory forensics crates/palyra-vault/src/crypto.rs#156-174.
Filesystem Permissions
The Vault enforces strict ownership checks. Before opening a vault root or writing objects, it ensures that the directory is restricted to the current user (mode0700 on Unix) crates/palyra-vault/src/backend.rs#99-100.
Concurrency & Locking
To prevent corruption during simultaneous CLI and Daemon access, the Vault uses a file-based locking mechanism for metadata updates (.metadata.lock). It includes logic to reclaim “stale” locks if a process crashed while holding them crates/palyra-vault/src/metadata.rs#7-9.
Sources: crates/palyra-vault/src/crypto.rs#156-174, crates/palyra-vault/src/filesystem.rs#1-20, crates/palyra-vault/src/metadata.rs#34-37