Skip to main content
The Palyra network layer employs a dual-protocol approach for remote node communication: a high-performance QUIC transport for event streaming and health checks, and an mTLS-secured gRPC Node RPC interface for management, registration, and capability execution. This architecture ensures that remote nodes (running via the CLI or as background services) can securely interact with the central daemon even across untrusted networks.

​
QUIC Transport Layer (palyra-transport-quic)

The palyra-transport-quic crate provides a specialized wrapper around the quinn library to implement a frame-based protocol over QUIC. It handles TLS 1.3 certificate validation, ALPN negotiation (palyra-quic-v1), and stream multiplexing crates/palyra-transport-quic/src/lib.rs#12-14.

​
Transport Implementation

The transport layer uses bidirectional streams to exchange JSON-serialized frames. Each frame is prefixed with its length to allow robust reading from the QUIC stream crates/palyra-transport-quic/src/lib.rs#149-152.

​
Connection Lifecycle

The QuicRuntime in the daemon manages the lifecycle of these connections, enforcing a concurrency limit (default 256) via a tokio::sync::Semaphore crates/palyra-daemon/src/quic_runtime.rs#16-91. QUIC Connection Data Flow Sources: crates/palyra-daemon/src/quic_runtime.rs#82-198, crates/palyra-transport-quic/src/lib.rs#120-176

​
Node RPC Interface

While QUIC handles the “fast path” of events, the NodeRpcServiceImpl provides a formal gRPC interface (defined in node.proto) for node orchestration. This service is typically exposed on a separate port and requires mTLS for all operations except initial pairing crates/palyra-daemon/src/node_rpc.rs#38-54.

​
Security and mTLS Enforcement

The Node RPC surface is hardened using certificate-bound identity:
  1. Fingerprint Validation: Every request’s TLS certificate is hashed (SHA-256) and checked against a RevocationIndex crates/palyra-daemon/src/node_rpc.rs#56-97.
  2. Device Binding: The enforce_cert_bound_device function ensures that the device_id provided in the gRPC metadata matches the identity strictly bound to the client certificate during the pairing process crates/palyra-daemon/src/node_rpc.rs#99-129.
  3. Revocation: If a node’s certificate is revoked via the IdentityManager, the RevocationAwareClientVerifier will terminate the TLS handshake before the gRPC layer is reached crates/palyra-identity/src/mtls.rs#80-105.

​
Key RPC Methods

MethodPurposeSource
RegisterNodeAnnounces node presence, platform, and capabilities.crates/palyra-daemon/src/node_rpc.rs#205
StreamEventsLong-polling or streaming channel for capability dispatch.crates/palyra-daemon/src/node_rpc.rs#230
SubmitCapabilityResultReturns the JSON output of a remote task execution.crates/palyra-daemon/src/node_rpc.rs#260
MintNodePairingCodeAdmin-only: generates a PIN/QR code for new nodes.crates/palyra-daemon/src/node_rpc.rs#330
Sources: crates/palyra-daemon/src/node_rpc.rs#38-280, crates/palyra-identity/src/mtls.rs#149-164

​
Node Pairing Handshake

Palyra uses a “Trust On First Use” (TOFU) pairing model with out-of-band verification (PIN or QR code). This process upgrades an unauthenticated connection to a fully mTLS-secured relationship.

​
Handshake Sequence

  1. Minting: An admin generates a DevicePairingCodeRecord crates/palyra-daemon/src/node_runtime.rs#48-54.
  2. Hello: The node sends a DevicePairingHello containing its ephemeral public key and the pairing proof (PIN) crates/palyra-identity/src/pairing/handshake.rs#111-118.
  3. Verification: The daemon verifies the proof and creates a VerifiedPairing object crates/palyra-identity/src/pairing/handshake.rs#129-137.
  4. Material Issuance: Once approved (either automatically or via palyra pairing approve), the daemon issues a client certificate signed by the Gateway CA crates/palyra-daemon/src/node_runtime.rs#79-87.
Pairing Code State Machine Sources: crates/palyra-daemon/src/node_runtime.rs#58-76, crates/palyra-identity/src/pairing/handshake.rs#83-154

​
Node Runtime and Inventory Management

The NodeRuntimeState manages the inventory of all registered remote nodes and handles the asynchronous dispatch of capabilities.

​
Remote Capability Dispatch

When the daemon needs to execute a tool on a remote node (e.g., a filesystem operation on a paired laptop), it uses the following flow:
  1. Queueing: The request is added to queued_by_device in the CapabilityRuntimeState crates/palyra-daemon/src/node_runtime.rs#165-170.
  2. Notification: The node, which is listening via StreamEvents (gRPC) or node.stream_events (QUIC), receives a CapabilityDispatchRecord crates/palyra-daemon/src/node_runtime.rs#151-156.
  3. Execution: The node executes the task and calls SubmitCapabilityResult crates/palyra-daemon/src/node_rpc.rs#260.
  4. Completion: The NodeRuntimeState matches the request_id and triggers a oneshot::Sender to return the result to the orchestrator crates/palyra-daemon/src/node_runtime.rs#169-170.

​
Persisted State

The node inventory and pairing history are persisted in node-runtime.v1.json within the state root crates/palyra-daemon/src/node_runtime.rs#19-22. This includes: Code Entity Mapping: Node Management
System ConceptCode Entity (Rust)Role
Node RegistryRegisteredNodeRecordStores device capabilities and metadata.
Pairing LogicIdentityManagerManages CA and certificate issuance.
Task QueueCapabilityRuntimeStateTracks in-flight remote requests and waiters.
CLI Clientrun_node_foregroundThe primary loop for a remote node instance.
Sources: crates/palyra-daemon/src/node_runtime.rs#124-203, crates/palyra-cli/src/commands/node.rs#173-215, crates/palyra-daemon/src/node_rpc.rs#187-200