Skip to main content
This section details the security infrastructure of Palyra, focusing on how secrets are stored, how nodes and devices establish identity, and the mechanisms used for secure, encrypted communication across the distributed system.

​
Palyra Vault: Secret Storage

The palyra-vault crate provides a secure, scoped storage system for sensitive data such as API keys, connector credentials, and private configuration. It abstracts over multiple platform-specific backends to ensure that secrets are protected by the operating system’s native security facilities whenever possible.

​
Architecture and Backends

The Vault uses a BlobBackend trait to perform CRUD operations on encrypted payloads. The system automatically selects the most secure backend available for the host platform.
Backend KindPlatformImplementation Detail
MacosKeychainmacOSUses the macOS Keychain via security CLI or API crates/palyra-vault/src/backend.rs#44-44.
LinuxSecretServiceLinuxIntegrates with libsecret or secret-tool crates/palyra-vault/src/backend.rs#46-46.
WindowsDpapiWindowsUses Data Protection API (DPAPI) for user-level encryption crates/palyra-vault/src/backend.rs#48-48.
EncryptedFileAllFallback using ring (ChaCha20-Poly1305) with a local key file crates/palyra-vault/src/backend.rs#42-42.

​
Scoping and Metadata

Secrets are organized using a VaultScope, which prevents one component (e.g., a specific agent or connector) from accessing secrets belonging to another. Sources: crates/palyra-vault/src/lib.rs#1-20, crates/palyra-vault/src/backend.rs#39-133, crates/palyra-vault/src/scope.rs#7-16

​
Identity and Device Management

The palyra-identity crate manages the cryptographic identity of the local node and the trust relationships with other devices. Every Palyra instance is identified by an Ed25519 keypair.

​
Identity Storage

Identities are stored in a SecretStore, which can be an InMemorySecretStore for testing or a FilesystemSecretStore for production crates/palyra-identity/src/store.rs#34-87.

​
Device Identity

A DeviceIdentity consists of a unique ULID and a public key crates/palyra-identity/src/device.rs. These identities are used to sign requests and establish mTLS sessions. Sources: crates/palyra-identity/src/lib.rs#1-25, crates/palyra-identity/src/store.rs#15-115

​
Node Pairing Handshake

Pairing is the process by which a new device (e.g., a mobile app or another daemon) is authorized to communicate with a Palyra node.

​
The Handshake Flow

Palyra supports multiple pairing methods, including PIN codes and QR codes. The process involves a multi-step handshake implemented in palyra-identity::pairing::handshake.
  1. Initiation: The user generates a pairing code via the CLI or Web UI using PairingCommand::Code crates/palyra-cli/src/commands/pairing.rs#72-96.
  2. Handshake: The joining device presents a proof (PIN/QR) and its public key.
  3. Approval: Pairing requests default to a deny_by_default state and require explicit human approval via PairingCommand::Approve crates/palyra-cli/src/commands/pairing.rs#97-109.
  4. Persistence: Upon success, the new device’s identity is stored in the IdentityManager crates/palyra-cli/src/commands/pairing.rs#168-177.

​
Pairing Implementation Diagram

The following diagram maps the CLI commands to the underlying identity logic. Title: Node Pairing Logic Flow Sources: crates/palyra-cli/src/commands/pairing.rs#7-178, crates/palyra-identity/src/store.rs#87-115, crates/palyra-cli/tests/pairing_flow.rs#17-108

​
mTLS and QUIC Transport Layer

Palyra uses Mutual TLS (mTLS) over QUIC for all node-to-node communication, ensuring that both the client and server are cryptographically verified.

​
QUIC Runtime

The palyra-daemon implements a QuicRuntime that handles incoming encrypted streams.

​
Transport Entity Mapping

Title: QUIC Transport and Identity Integration

​
Protocol Features

Sources: crates/palyra-daemon/src/quic_runtime.rs#1-122, crates/palyra-transport-quic/src/lib.rs, crates/palyra-identity/src/mtls.rs