Security Architecture Overview
The security posture is divided into three primary layers:- Transport & Identity: Mutual TLS (mTLS) for all gRPC and QUIC traffic, anchored by a device-specific Certificate Authority (CA).
- Secret Management: A secure vault that uses
ringandchacha20_poly1305to encrypt data at rest. - Access Control: A principal-based authorization system that uses Cedar policies to govern tool execution and resource access.
Component Relationship
The following diagram illustrates how the security crates interact to provide a unified trust boundary. Security Subsystem Interaction Sources: crates/palyra-identity/src/device.rs#17-21, crates/palyra-vault/src/envelope.rs#14-24, crates/palyra-auth/src/lib.rs#10-21Identity, mTLS & Pairing
The foundation of Palyra’s security is theDeviceIdentity. Every installation generates a unique Ed25519 signing key and X25519 secret for cryptographic operations crates/palyra-identity/src/device.rs#17-21.
- Trust Model: Palyra uses a Trust-On-First-Use (TOFU) pairing handshake to establish connections between the daemon and new clients (CLI or Connectors).
- Transport Security: All internal gRPC communication is wrapped in mTLS using
rustlscrates/palyra-identity/Cargo.toml#18-18. - Fingerprinting: Identities are identified by a SHA-256 fingerprint of the signing public key crates/palyra-identity/src/device.rs#68-71.
Vault & Secret Management
Thepalyra-vault crate provides encrypted storage for sensitive data. It implements Envelope Encryption, where data is encrypted with a unique Data Encryption Key (DEK), and the DEK is itself encrypted with a Key Encryption Key (KEK) crates/palyra-vault/src/envelope.rs#26-47.
| Feature | Implementation |
|---|---|
| Algorithm | ChaCha20-Poly1305 (via ring) crates/palyra-vault/src/envelope.rs#4-4 |
| Storage | SQLite-backed encrypted blobs |
| Key Derivation | HKDF for deriving sub-keys crates/palyra-vault/Cargo.toml#12-12 |
| Payload Versioning | Versioned EnvelopePayload for migration support crates/palyra-vault/src/envelope.rs#15-15 |
Authentication & Access Control
Authentication in Palyra revolves around thePrincipal. A principal represents an authenticated entity (a user, a specific CLI instance, or a remote node) crates/palyra-auth/src/lib.rs#10-16.
- Auth Profiles: Managed by the
AuthProfileRegistry, these records define how the daemon authenticates with external providers like OpenAI or Anthropic crates/palyra-auth/src/lib.rs#21-21. - OAuth Lifecycle: The daemon handles complex OAuth2 flows, including PKCE challenge generation crates/palyra-daemon/src/openai_auth.rs#104-107 and automated token refreshing crates/palyra-auth/src/lib.rs#17-20.
- Policy Enforcement: Tool execution is gated by
palyra-policy, which utilizes the Cedar policy engine to evaluate if aPrincipalhas permission to perform an action on a resource crates/palyra-policy/Cargo.toml#9-9.
Security Gates & Governance
Palyra maintains a strict security posture through automated gates in the CI/CD pipeline:- Fuzzing: Nine
cargo-fuzztargets test parsers for A2UI, Webhooks, and Config paths. - Dependency Auditing:
cargo-denyandosv-scannerare used to prevent supply chain attacks. - Static Analysis: Gitleaks and CodeQL scan for secrets and vulnerabilities.