Node Runtime and Remote Nodes

The Node Runtime and Remote Node subsystem enables the Palyra daemon to extend its capabilities by connecting to external devices (Nodes). This architecture facilitates secure, multi-device execution of tools and capabilities through a gRPC-based service layer protected by mutual TLS (mTLS).

Node Runtime Architecture

The NodeRuntimeState manages the lifecycle of remote nodes, including their registration, capability discovery, and pairing status. It persists state to a versioned JSON file (node-runtime.v1.json) within the daemon’s state root crates/palyra-daemon/src/node_runtime.rs#19-22.

Key Components

Component	Responsibility
`NodeRuntimeState`	Orchestrates pairing codes, active requests, and the registry of known nodes crates/palyra-daemon/src/node_runtime.rs#177-182.
`NodeRpcServiceImpl`	The gRPC implementation of `NodeService`, handling registration and event streaming crates/palyra-daemon/src/node_rpc.rs#38-43.
`CapabilityRuntimeState`	Manages in-flight and queued capability execution requests for specific devices crates/palyra-daemon/src/node_runtime.rs#165-170.
`QuicRuntime`	Provides a low-latency, framed transport for node health and event streaming crates/palyra-daemon/src/quic_runtime.rs#18-25.

Node System Data Flow

This diagram illustrates the relationship between the gRPC service, the runtime state, and the underlying identity manager. Title: Node Runtime Entity Mapping Sources: crates/palyra-daemon/src/node_rpc.rs#38-54, crates/palyra-daemon/src/node_runtime.rs#177-182, crates/palyra-identity/src/pairing/manager.rs#14-33

Device Pairing and mTLS

Palyra uses a secure pairing flow to establish trust between the daemon and a remote node. This flow results in the issuance of a device-specific client certificate used for mTLS authentication on the Node RPC endpoint.

Pairing Methods

Nodes can pair using two primary methods crates/palyra-daemon/src/node_runtime.rs#24-29:

PIN: A short numeric code entered on the device.
QR: A token-based approach typically used by mobile or desktop clients.

The Pairing Flow

Initiation: The daemon generates a DevicePairingCodeRecord with a TTL (default 10 minutes) crates/palyra-daemon/src/node_runtime.rs#20-22.
Request: The node submits a PairingMethod (PIN or QR) via RegisterNode.
Approval: A DevicePairingRequestRecord is created and requires operator approval via the Palyra policy engine crates/palyra-daemon/src/node_rpc.rs#187-210.
Issuance: Upon approval, the IdentityManager issues a client certificate bound to the device_id crates/palyra-identity/src/ca.rs#64-78.

mTLS Enforcement

The NodeRpcServiceImpl enforces mTLS by extracting the peer certificate fingerprint from the TlsConnectInfo crates/palyra-daemon/src/node_rpc.rs#56-68. It validates that:

The certificate is not revoked via is_revoked_certificate_fingerprint crates/palyra-daemon/src/node_rpc.rs#91-95.
The certificate fingerprint maps to the device_id provided in the request crates/palyra-daemon/src/node_rpc.rs#116-128.

Sources: crates/palyra-daemon/src/node_runtime.rs#48-54, crates/palyra-daemon/src/node_rpc.rs#56-97, crates/palyra-identity/src/ca.rs#64-78

Node RPC Service (`NodeService`)

The NodeService is the primary gRPC interface for remote nodes.

Principal RPCs

RegisterNode: Nodes announce their platform and capabilities (e.g., “filesystem”, “shell”) crates/palyra-daemon/src/node_rpc.rs#239-250.
StreamEvents: A server-streaming RPC where the daemon pushes CapabilityDispatchRecord tasks to the node crates/palyra-daemon/src/node_rpc.rs#341-355.
SubmitCapabilityResult: Nodes return the output or error of a dispatched task crates/palyra-daemon/src/node_rpc.rs#388-400.

Title: Capability Execution Sequence Sources: crates/palyra-daemon/src/node_rpc.rs#239-250, crates/palyra-daemon/src/node_rpc.rs#341-355, crates/palyra-daemon/src/node_rpc.rs#388-400

QUIC Transport (`palyra-transport-quic`)

The palyra-transport-quic crate provides the underlying transport for high-performance node communication. It implements a custom framing protocol over QUIC streams.

Protocol Features

ALPN: Uses a dedicated ALPN for Palyra node traffic.
Framing: Implements read_frame and write_frame to handle length-prefixed messages crates/palyra-transport-quic/src/lib.rs.
Pinned Fingerprints: Supports pinned_server_fingerprint_sha256 for strict “No-Trust” environments where CA validation is insufficient crates/palyra-transport-quic/tests/transport.rs#66-72.
Fallback: Provides TcpFallbackPolicy for environments where UDP/QUIC is blocked crates/palyra-transport-quic/tests/transport.rs#8-10.

QUIC Runtime

The QuicRuntime in the daemon handles incoming QUIC connections. It enforces a global concurrency limit via a Semaphore (default 256 connections) crates/palyra-daemon/src/quic_runtime.rs:16-17, 91-93. Sources: crates/palyra-transport-quic/src/lib.rs, crates/palyra-daemon/src/quic_runtime.rs#16-17, crates/palyra-daemon/src/quic_runtime.rs#91-103

CLI Node Commands

The palyra CLI provides tools for managing nodes and the pairing process.

Command	Function
`palyra nodes list`	Displays registered nodes, their platforms, and last-seen timestamps.
`palyra nodes pairing-code`	Generates a new PIN or QR code for a node to use during registration.
`palyra nodes approve <id>`	Manually approves a pending pairing request.
`palyra nodes remove <id>`	Unregisters a node and revokes its associated certificate.

Sources: crates/palyra-cli/src/commands/node.rs

​Node Runtime Architecture

​Key Components

​Node System Data Flow

​Device Pairing and mTLS

​Pairing Methods

​The Pairing Flow

​mTLS Enforcement

​Node RPC Service (NodeService)

​Principal RPCs

​QUIC Transport (palyra-transport-quic)

​Protocol Features

​QUIC Runtime

​CLI Node Commands