palyrad) and various nodes (CLI, Desktop, Browser, or remote connectors)—possesses a unique cryptographic identity rooted in X.509 certificates issued by a transient, internal Certificate Authority (CA).
Identity Architecture
The identity system is managed by theIdentityManager in palyra-identity. It handles the lifecycle of the Gateway CA, device identities, and the secure storage of these credentials.
Certificate Authority (CA)
TheCertificateAuthority struct in palyra-identity is responsible for generating the root of trust.
- Root CA: Generated locally on the first run of
palyrad. It is self-signed and used to issue leaf certificates for the server and paired devices crates/palyra-identity/src/ca.rs#40-62. - Server Certificates: Issued to the
palyradgRPC/QUIC endpoints to identify the gateway to clients crates/palyra-identity/src/ca.rs#80-86. - Client Certificates: Issued to devices during the pairing process to enable mTLS authentication crates/palyra-identity/src/ca.rs#64-78.
Device Identity
ADeviceIdentity represents a unique installation or actor.
- Generation: Created using Ed25519 key pairs for signing and X25519 for key exchange crates/palyra-identity/src/device.rs#22-45.
- Identification: Devices are identified by a Canonical ULID crates/palyra-identity/src/device.rs#18-20.
- Persistence: Identity material is stored in a
SecretStore, typically theFilesystemSecretStore, which encrypts sensitive keys at rest crates/palyra-identity/src/lib.rs#18-22.
Code Entity Mapping: Identity Management
The following diagram illustrates the relationship between the management logic and the underlying storage entities. Sources: crates/palyra-identity/src/pairing/manager.rs#45-75, crates/palyra-identity/src/ca.rs#34-39, crates/palyra-identity/src/pairing/persistence.rs#16-20The Pairing Handshake (TOFU)
Pairing is the process by which an untrusted device establishes a permanent, mTLS-secured relationship with the Gateway. Palyra uses a multi-step handshake involving a shared secret (PIN or QR token).Handshake Sequence
- Initiation: The Gateway creates a
PairingSessioncontaining a challenge and an ephemeral public key crates/palyra-identity/src/pairing/handshake.rs#27-52. - Hello: The device responds with a
DevicePairingHello. This includes itsdevice_id, its own ephemeral public key, and a signature over the transcript crates/palyra-identity/src/pairing/models.rs#45-55. - Verification: The Gateway verifies the signature and the proof (PIN/QR). If valid, it generates a
VerifiedPairingcrates/palyra-identity/src/pairing/handshake.rs#129-137. - Approval: By default, pairing requires explicit administrative approval via the
ApprovalsServicecrates/palyra-daemon/src/node_rpc.rs#187-210. - Finalization: Once approved, the Gateway issues a client certificate to the device, which is then used for all subsequent mTLS connections crates/palyra-identity/src/pairing/handshake.rs#139-148.
Handshake Data Flow
Sources: crates/palyra-identity/src/pairing/handshake.rs#83-127, crates/palyra-daemon/src/node_rpc.rs#187-210, crates/palyra-cli/src/commands/pairing.rs#159-180mTLS Enforcement
Once paired, the communication between nodes and the daemon is secured via mTLS.Transport Layer Security
The system supports two primary secure transports:- gRPC (Tonic): Used for high-level service calls. The
NodeRpcServiceImplenforces mTLS by inspectingTlsConnectInfoand validating the peer certificate fingerprint against theIdentityManagercrates/palyra-daemon/src/node_rpc.rs#56-97. - QUIC (Quinn): Used for low-latency event streaming. The
quic_runtimeusesrustlswith a customClientCertVerifierto ensure only paired devices can connect crates/palyra-daemon/src/quic_runtime.rs#19-25.
Revocation
Certificates are not revoked via standard CRLs or OCSP. Instead, theIdentityManager maintains a list of revoked_devices. During the TLS handshake or at the application layer, the gateway checks if the certificate’s fingerprint belongs to a revoked device crates/palyra-daemon/src/node_rpc.rs#91-95.
| Component | Logic Location | Enforcement Mechanism |
|---|---|---|
| gRPC Server | node_rpc.rs | peer_certificate_fingerprint check in every RPC crates/palyra-daemon/src/node_rpc.rs#56-97 |
| QUIC Server | quic_runtime.rs | QuicServerTlsConfig with require_client_auth crates/palyra-daemon/src/quic_runtime.rs#67-80 |
| Identity Store | manager.rs | Fingerprint-to-Device mapping crates/palyra-identity/src/pairing/manager.rs#130-145 |
Pairing Manager & Node Runtime
TheNodeRuntimeState in palyra-daemon tracks the state of active pairing requests and registered nodes.
Persisted State
The runtime persists state tonode-runtime.v1.json, including:
- Active Pairing Codes: Valid PINs/QR tokens and their TTL crates/palyra-daemon/src/node_runtime.rs#141-143.
- Pairing Requests: The history and status of handshakes (Pending, Approved, Rejected) crates/palyra-daemon/src/node_runtime.rs#144-145.
- Registered Nodes: Metadata about paired devices, such as platform and capabilities crates/palyra-daemon/src/node_runtime.rs#146-147.
Capability Dispatch
Paired nodes can register “Capabilities” (e.g., a local shell or browser automation). TheNodeRuntimeState manages a queue of CapabilityDispatchRecord objects, allowing the gateway to route tasks to specific paired devices crates/palyra-daemon/src/node_runtime.rs#151-170.
Sources: crates/palyra-daemon/src/node_runtime.rs#177-203, crates/palyra-daemon/src/node_rpc.rs#38-54, crates/palyra-identity/src/lib.rs#1-15