Pairing Lifecycle
The pairing process is a multi-step handshake that upgrades a short-lived proof (PIN or QR code) into a persistent mTLS identity. This process is orchestrated by theNodeRpcServiceImpl and the IdentityManager.
1. Code Minting
An administrator or a trusted session generates a pairing code. This code is associated with a specificPairingCodeMethod (Pin or Qr) and has a configurable TTL crates/palyra-daemon/src/node_runtime.rs#20-22.
- CLI Command:
palyra pairing code --method pincrates/palyra-cli/src/commands/pairing.rs#72-96. - Storage: Codes are held in
PersistedNodeRuntimeStatewithin theactive_pairing_codesmap crates/palyra-daemon/src/node_runtime.rs#141-148.
2. Pairing Request
The node client initiates a handshake by callingRegisterNode or a specialized pairing endpoint. It provides a DevicePairingHello which includes:
- An ephemeral X25519 public key for a key exchange crates/palyra-identity/src/pairing/handshake.rs#38-49.
- A signature over the handshake transcript using the device’s long-term signing key crates/palyra-identity/src/pairing/handshake.rs#185-195.
- The pairing proof (PIN/Token) crates/palyra-identity/src/pairing/handshake.rs#180-183.
3. Approval and Certificate Issuance
If the proof is valid, the daemon creates aDevicePairingRequestRecord in a PendingApproval state crates/palyra-daemon/src/node_runtime.rs#58-64.
- Approval: Once an administrator approves the request (via CLI or Web UI), the
IdentityManagerfinalizes the pairing. - CA Operation: The internal
CertificateAuthorityissues a client certificate bound to thedevice_idcrates/palyra-identity/src/ca.rs#64-78. - Material Delivery: The certificate and the Gateway CA public cert are returned to the node crates/palyra-daemon/src/node_runtime.rs#79-87.
Pairing Data Flow
The following diagram illustrates the transition from a pairing code to an established mTLS session. Diagram: Node Pairing Sequence Sources: crates/palyra-daemon/src/node_rpc.rs#187-205, crates/palyra-identity/src/pairing/handshake.rs#120-149, crates/palyra-identity/src/ca.rs#64-78Identity and CA Subsystem
Thepalyra-identity crate manages the Root CA and device certificates.
Certificate Authority (CA)
TheCertificateAuthority struct uses rcgen to manage an internal X.509 hierarchy.
- Root CA: Generated on first start. It signs both server certificates (for the daemon’s gRPC/QUIC endpoints) and client certificates (for nodes) crates/palyra-identity/src/ca.rs#40-62.
- Storage: The CA private key and certificate are stored in the
IdentityStore, typically backed by the filesystem viaFilesystemSecretStorecrates/palyra-identity/src/ca.rs#118-138.
Revocation
Palyra supports certificate revocation via fingerprints. TheIdentityManager maintains a revoked_devices map and a list of revoked_certificate_fingerprints crates/palyra-identity/src/pairing/handshake.rs#158-160. During mTLS handshakes, the NodeRpcServiceImpl checks the peer certificate’s SHA-256 fingerprint against this revocation list crates/palyra-daemon/src/node_rpc.rs#85-96.
Node Invocation and Capability Dispatch
Once paired, nodes maintain a persistent gRPC stream with the daemon. This stream is used to announce “Capabilities” (e.g., local shell access, specific tool execution) and receive execution requests.Capability Registry
Nodes register their available features inRegisterNodeRequest crates/palyra-daemon/tests/node_rpc_mtls.rs#159-167. These are stored in the NodeRuntimeState as RegisteredNodeRecord crates/palyra-daemon/src/node_runtime.rs#130-138.
Request Dispatching
When the Orchestration Engine needs to execute a task on a specific node:- It creates a
CapabilityDispatchRecordcontaining the input JSON crates/palyra-daemon/src/node_runtime.rs#151-156. - The record is queued in
CapabilityRuntimeStatecrates/palyra-daemon/src/node_runtime.rs#166-170. - The node, via its active stream, receives the dispatch, executes the task, and returns a
CapabilityExecutionResultcrates/palyra-daemon/src/node_runtime.rs#158-163.
mTLS Configuration
The daemon enforces mTLS on the Node RPC port by default.| Component | Responsibility | Code Reference |
|---|---|---|
| Server Config | Configures rustls to require client certs signed by the internal CA. | build_node_rpc_server_mtls_config in palyra-identity |
| Client Config | Configures nodes to present their issued cert and verify the daemon’s cert. | build_paired_device_client_mtls_config in palyra-identity |
| Enforcement | NodeRpcServiceImpl extracts TlsConnectInfo to verify device identity. | crates/palyra-daemon/src/node_rpc.rs#56-97 |
Security Opt-out
For local development or specialized network environments, mTLS enforcement can be disabled via therequire_mtls flag in NodeRpcServiceImpl crates/palyra-daemon/src/node_rpc.rs#42. When disabled, the daemon accepts connections without client certificates, though this is discouraged for production use crates/palyra-daemon/tests/node_rpc_mtls.rs#121-138.
Sources: crates/palyra-daemon/src/node_rpc.rs#38-54, crates/palyra-identity/tests/mtls_pairing_flow.rs#8-12, crates/palyra-daemon/tests/node_rpc_mtls.rs#72-92