palyra-identity crate, which serves as the security foundation for the Palyra ecosystem. It manages the internal Certificate Authority (CA), Ed25519 device keypairs, X.509 certificate issuance, and the multi-stage pairing protocol used to establish trust between the daemon and various clients (CLI, Desktop, Browser Extension, and Nodes).
Identity Architecture
Palyra uses a decentralized identity model where every component (daemon, node, or client) possesses a uniqueDeviceIdentity. Trust is established via a Root CA managed by the daemon’s IdentityManager.
Device Identity
ADeviceIdentity consists of an Ed25519 keypair used for signing and a unique ULID-based device ID.
- Key Generation: Uses
ed25519_dalekfor high-performance signing crates/palyra-identity/src/device.rs#1-20. - Identification: Devices are identified by a canonical ULID crates/palyra-identity/src/device.rs#25-30.
Certificate Authority (CA)
TheCertificateAuthority struct handles the lifecycle of the internal PKI.
- Root CA: Self-signed certificate generated upon first initialization crates/palyra-identity/src/ca.rs#41-62.
- Client Issuance: Issues short-lived leaf certificates for mTLS with
ExtendedKeyUsagePurpose::ClientAuthcrates/palyra-identity/src/ca.rs#64-78. - Server Issuance: Issues certificates for the daemon’s gRPC and QUIC endpoints, supporting SANs for
localhostand specific IP addresses crates/palyra-identity/src/ca.rs#80-116.
Secret Storage
Identity materials (private keys, CA state) are persisted using aSecretStore.
- FilesystemSecretStore: Encrypts sensitive keys at rest using ChaCha20-Poly1305 with a local master key crates/palyra-identity/src/store.rs#87-115.
- OS Hardening: On Windows, it uses SID-based ACLs; on Unix, it enforces
0o700directory permissions crates/palyra-identity/src/store.rs#98-114.
The Pairing Flow
The pairing flow is a Trust-On-First-Use (TOFU) mechanism that upgrades a shared secret (Pairing Code) into a pinned mTLS identity.Pairing Sequence Diagram
The following diagram illustrates the interaction between theIdentityManager and a new DeviceIdentity.
Key Functions
IdentityManager::start_pairing: Initializes a session, generating a random challenge and ephemeral X25519 keys crates/palyra-identity/src/pairing/handshake.rs#83-109.IdentityManager::build_device_hello: Called by the client to construct the response, including the proof and device signing public key crates/palyra-identity/src/pairing/handshake.rs#111-118.IdentityManager::verify_pairing: Validates the client’s proof against the active session and checks for revocation crates/palyra-identity/src/pairing/handshake.rs#129-137.
mTLS and Transport Security
Once paired, all node-to-daemon and client-to-daemon gRPC/QUIC communication is secured via mutual TLS (mTLS).QUIC Runtime
TheQuicRuntime in the daemon enforces certificate verification for all incoming connections.
- Verifier: Uses
rustls::server::danger::ClientCertVerifierto validate client certificates against the internal CA crates/palyra-daemon/src/quic_runtime.rs#19-25. - Connection Handling: Limits concurrent connections via a
Semaphoreto prevent resource exhaustion crates/palyra-daemon/src/quic_runtime.rs#86-102.
Node RPC mTLS
Thenode_rpc_mtls subsystem handles gRPC-over-HTTP/2 security.
- Enforcement: Clients without a valid certificate issued by the daemon’s CA are rejected with
Code::Unauthenticatedcrates/palyra-daemon/tests/node_rpc_mtls.rs#45-68. - Revocation: The daemon checks the
revoked_deviceslist during the handshake; revoked certificates returnCode::PermissionDeniedcrates/palyra-daemon/tests/node_rpc_mtls.rs#95-118.
Security Entity Mapping
| System Name | Code Entity | File |
|---|---|---|
| CA Manager | CertificateAuthority | crates/palyra-identity/src/ca.rs#34 |
| Identity Store | FilesystemSecretStore | crates/palyra-identity/src/store.rs#87 |
| Pairing Logic | IdentityManager | crates/palyra-identity/src/pairing/manager.rs#1 |
| QUIC Server | QuicRuntime | crates/palyra-daemon/src/quic_runtime.rs#19 |
| mTLS Config | QuicServerTlsConfig | crates/palyra-transport-quic/src/lib.rs#1 |
Implementation Details
Revocation and Pinning
Pairing is not permanent. TheIdentityManager maintains a list of revoked_devices.
- Revocation Check: Every pairing attempt and subsequent mTLS handshake checks the
revoked_devicesmap crates/palyra-identity/src/pairing/handshake.rs#158-160. - Persistence: Revocation state is stored in the encrypted
SecretStoreto prevent tampering crates/palyra-identity/src/pairing/handshake.rs#145-146.
Rate Limiting
To prevent brute-force attacks on pairing codes:- Session Limits: A maximum of
MAX_ACTIVE_PAIRING_SESSIONS(default 100) can exist simultaneously crates/palyra-identity/src/pairing/handshake.rs#98-102. - Rate Window: The
IdentityManagertracksrecent_pairing_startsand enforces a window-based limit crates/palyra-identity/src/pairing/handshake.rs#91-97.