palyra-common crate serves as the foundational shared library for the Palyra ecosystem. It provides core utilities that must remain consistent across the daemon, CLI, and various connectors, including the configuration system, security primitives for webhooks, and the workspace patch protocol.
Configuration System
Palyra uses a versioned TOML-based configuration system. Theconfig_system module handles document parsing, key-path manipulation, automated migrations, and secure persistence with backup rotation.
Implementation Details
The system treats the configuration as atoml::Value tree. It supports “dot-notated” path access (e.g., daemon.port) to retrieve or modify specific nodes crates/palyra-common/src/config_system.rs#153-172.
Key features include:
- Version Management: Every config file is expected to have a
versionfield. The system automatically migrates older versions toCONFIG_VERSION_V1(currently 1) crates/palyra-common/src/config_system.rs#14-23. - Safe Path Parsing: Segments are validated against forbidden names like
__proto__orconstructorto prevent prototype pollution-style attacks during serialization/deserialization crates/palyra-common/src/config_system.rs#16-16. - Atomic Writes & Backups: When saving changes, the system can perform a rotation of existing files (e.g.,
.bak.1,.bak.2) up to a configurable limit (default 5) before writing the new content crates/palyra-common/src/config_system.rs#15-15. - Permission Preservation: On Unix systems, the library attempts to preserve the
0o600(owner-only) permissions of sensitive configuration files during updates crates/palyra-cli/tests/config_mutation.rs#107-146.
Config Data Flow
This diagram shows how a configuration change request from the CLI or API flows through theconfig_system.
Title: Config Mutation Logic
Sources: crates/palyra-common/src/config_system.rs#89-204, crates/palyra-cli/tests/config_mutation.rs#26-103
Redaction Engine
Theredaction module provides a robust set of utilities to prevent the accidental leakage of secrets (API keys, tokens, passwords) in logs, CLI output, and error messages.
- Sensitive Key Detection: A list of
SENSITIVE_KEY_MARKERS(e.g.,api_key,bearer,client_secret) is used to identify fields that should never be printed in plain text crates/palyra-common/src/redaction.rs#5-22. - URL Redaction: The
redact_urlfunction strips sensitive query parameters and userInfo (username:password) from URL strings crates/palyra-common/src/redaction.rs#63-86. - Contextual Redaction: The engine can scan text for patterns like
Bearer <token>and replace the following token with<redacted>crates/palyra-common/src/redaction.rs#89-111.
Webhook Security
Thewebhook module implements a secure envelope format and replay protection for incoming events from external connectors (Discord, Slack, etc.).
| Component | Responsibility |
|---|---|
WebhookEnvelope | Standardized JSON structure containing payload, signature, and nonce crates/palyra-common/src/lib.rs#26-29. |
WebhookSignatureVerifier | Validates HMAC-SHA256 signatures against a shared secret crates/palyra-common/src/lib.rs#26-29. |
ReplayProtection | Uses a ReplayNonceStore to ensure a specific webhook ID/nonce is only processed once within a time window crates/palyra-common/src/lib.rs#26-29. |
Workspace Patch Format
Theworkspace_patch module defines a custom multi-file patch format used by the daemon to apply file changes (Add, Update, Delete, Move) requested by AI models.
Implementation and Constraints
The patch execution is “fail-closed” and strictly governed byWorkspacePatchLimits:
- Path Confinement: All paths must be relative and stay within the specified
workspace_roots. Traversal (e.g.,../../) results in anInvalidPatchPatherror crates/palyra-common/src/workspace_patch.rs#113-116. - Resource Limits: Enforces
max_patch_bytes(default 256KB),max_files_touched(default 64), andmax_file_bytes(default 2MB) crates/palyra-common/src/workspace_patch.rs#30-39. - Atomic Operations: Patches are applied using a
PatchPlan. If any part of the plan fails, the system attempts a best-effort rollback crates/palyra-common/src/workspace_patch.rs#184-211.
Shared Primitives
Canonical IDs
Theids module provides validate_canonical_id, ensuring that all identifiers (Device IDs, Run IDs, Artifact IDs) follow a strict format (typically ULID-compatible) to prevent injection or malformed data from propagating through the system crates/palyra-common/src/lib.rs#24-24.
Context References
Thecontext_references module defines how different parts of the system refer to shared context, such as VaultRef for secrets or AttachmentRef for media crates/palyra-common/src/lib.rs#4-4.
Windows Security (DPAPI)
On Windows platforms, the library includeswindows_security which wraps the Data Protection API (DPAPI). This is used by the Vault to encrypt secrets using the current user’s credentials crates/palyra-vault/src/backend.rs#15-16, crates/palyra-common/src/lib.rs#13-14.
Sources: crates/palyra-common/src/lib.rs#1-36, crates/palyra-vault/src/backend.rs#15-16