Node Runtime and mTLS RPC

The Node Runtime and mTLS RPC system provides the infrastructure for distributed Palyra nodes to securely connect, authenticate, and execute capabilities. This subsystem ensures that any external device (CLI, Desktop, or remote Node) is cryptographically bound to the gateway via a Mutual TLS (mTLS) handshake and a multi-step pairing flow.

Node Runtime Architecture

The NodeRuntimeState manages the lifecycle of connected nodes, pairing requests, and the dispatching of capabilities to those nodes. It persists its state in a JSON file named node-runtime.v1.json within the daemon’s state root crates/palyra-daemon/src/node_runtime.rs#19-19.

Key Entities

Entity	Code Symbol	Description
Node Runtime	`NodeRuntimeState`	Central coordinator for node registration and capability dispatch crates/palyra-daemon/src/node_runtime.rs#177-182.
Registered Node	`RegisteredNodeRecord`	Metadata for a verified and connected node, including its platform and capabilities crates/palyra-daemon/src/node_runtime.rs#130-138.
Pairing Request	`DevicePairingRequestRecord`	Tracks the state of a device attempting to pair with the gateway crates/palyra-daemon/src/node_runtime.rs#106-121.
Capability Dispatch	`CapabilityDispatchRecord`	A queued request for a node to execute a specific function crates/palyra-daemon/src/node_runtime.rs#151-156.

Node Runtime Data Flow

The following diagram illustrates how NodeRuntimeState interacts with the NodeRpcServiceImpl to manage node lifecycle and capability execution. Diagram: Node Runtime and RPC Interaction Sources: crates/palyra-daemon/src/node_runtime.rs#177-182, crates/palyra-daemon/src/node_rpc.rs#38-43, crates/palyra-daemon/src/node_rpc.rs#326-335

mTLS and Identity Management

Palyra uses a private Certificate Authority (CA) managed by palyra-identity to secure node communication. Every paired node receives a unique client certificate signed by the Gateway CA.

Certificate Verification

The NodeRpcServiceImpl enforces mTLS by extracting the peer’s certificate fingerprint from the gRPC TlsConnectInfo crates/palyra-daemon/src/node_rpc.rs#60-68. This fingerprint is then validated against the IdentityManager to ensure:

The certificate is not revoked crates/palyra-daemon/src/node_rpc.rs#91-95.
The certificate is cryptographically bound to the device_id provided in the request crates/palyra-daemon/src/node_rpc.rs#116-122.

Revocation

Revocation is handled via the RevocationIndex trait crates/palyra-identity/src/mtls.rs#23-25. The RevocationAwareClientVerifier wraps the standard rustls verifier to perform fingerprint lookups during the TLS handshake crates/palyra-identity/src/mtls.rs#63-72. Diagram: mTLS Verification Pipeline Sources: crates/palyra-identity/src/mtls.rs#93-105, crates/palyra-daemon/src/node_rpc.rs#56-97, crates/palyra-daemon/src/node_rpc.rs#99-129

Node Pairing Flow

The pairing flow transitions a device from “unpaired” to “authenticated” using a multi-step handshake involving either a PIN or a QR code.

Initiation: The node generates a DeviceIdentity and sends a PairingMethod (PIN or QR) to the gateway via NodeRpcServiceImpl::start_pairing crates/palyra-daemon/src/node_rpc.rs#198-210.
Approval: The gateway creates an ApprovalPromptRecord in the JournalStore crates/palyra-daemon/src/node_rpc.rs#187-196. A human operator must approve the pairing request in the Web Console.
Material Exchange: Once approved, the node calls finish_pairing. The gateway issues a new client certificate and provides the Gateway CA certificate crates/palyra-daemon/src/node_runtime.rs#89-103.
Persistence: The node stores the certificate and private key locally (e.g., in node-mtls-client.json) for future mTLS connections crates/palyra-cli/src/commands/node.rs#38-38.

Sources: crates/palyra-daemon/src/node_rpc.rs#150-170, crates/palyra-daemon/src/node_rpc.rs#242-255, crates/palyra-cli/src/commands/node.rs#120-131

QUIC Transport Layer

In addition to gRPC, Palyra supports a QUIC-based transport for event streaming and health checks, implemented in quic_runtime.rs. This layer provides low-latency, multiplexed communication between nodes.

Endpoint Binding: The server binds to a SocketAddr using QuicServerTlsConfig, which requires the same Gateway CA and server certificates as the RPC layer crates/palyra-daemon/src/quic_runtime.rs#62-80.
Method Handling: Supports node.health and node.stream_events crates/palyra-daemon/src/quic_runtime.rs#13-14.
Frame Format: Uses a custom framing protocol with a DEFAULT_MAX_FRAME_BYTES of 512KB crates/palyra-transport-quic/src/lib.rs#13-13.

Sources: crates/palyra-daemon/src/quic_runtime.rs#124-142, crates/palyra-daemon/src/quic_runtime.rs#165-179

Node CLI Commands

The palyra CLI provides a suite of commands to manage the local node lifecycle.

Command	Function
`palyra node run`	Runs a node in the foreground, performing pairing if necessary crates/palyra-cli/src/commands/node.rs#120-134.
`palyra node install`	Configures the node and optionally starts it as a background process crates/palyra-cli/src/commands/node.rs#139-161.
`palyra node status`	Returns a JSON or text status of the local node, including PID and certificate expiry crates/palyra-cli/src/commands/node.rs#135-138.
`palyra node stop`	Terminates the background node process crates/palyra-cli/src/commands/node.rs#163-163.

Local Node Configuration

The CLI maintains a NodeHostConfig which tracks the grpc_url, device_id, and identity_store_dir crates/palyra-cli/src/commands/node.rs#48-56. Sources: crates/palyra-cli/src/commands/node.rs#113-171

​Node Runtime Architecture

​Key Entities

​Node Runtime Data Flow

​mTLS and Identity Management

​Certificate Verification

​Revocation

​Node Pairing Flow

​QUIC Transport Layer

​Node CLI Commands

​Local Node Configuration