The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
//! X25519 key agreement + HKDF-SHA256 directional subkey derivation +
//! XChaCha20-Poly1305 frame encryption for device tunnels.
//!
//! Wire format (frame v2): `version(1=0x02) || nonce(24) || ciphertext+tag`.
//! Frames produced with the previous `version=0x01` shape (single shared key,
//! same key in both directions, no KDF) are no longer accepted; peers MUST
//! upgrade before reconnecting. An upgraded client may reuse a valid pairing
//! profile and device key.
//!
//! Session key derivation (`derive_session_keys`):
//! ```text
//! ikm = static_dh(32) || eph_dh(32)
//! salt = client_eph_pub || server_eph_pub
//! c2s = HKDF-SHA256(ikm, salt, info = "openhuman-tunnel/v1/c2s", 32)
//! s2c = HKDF-SHA256(ikm, salt, info = "openhuman-tunnel/v1/s2c", 32)
//! ```
//! Each peer holds two `XChaCha20Poly1305` instances: one for its own
//! direction (seal) and one for the peer's (open). Static DH continues to
//! authenticate the peer via the paired QR-code provenance; the ephemeral
//! DH provides forward secrecy.
//!
//! Bootstrap messages use separate wire markers and HKDF domains:
//! `0x03 || client_handshake_eph_pub || nonce || ciphertext` authenticates
//! its 33-byte header and derives its key from the ephemeral-to-core DH,
//! salted by `client_handshake_eph_pub || core_static_pub`.
//! `0x04 || nonce || ciphertext` authenticates `0x04 || client_session_eph_pub`
//! and derives its key from static DH, salted by `client_session_eph_pub`.
//! Pre-upgrade raw-DH and plaintext handshakes are rejected.
//!
//! Replay protection still uses a sliding window over the last
//! `WINDOW_SIZE` raw nonces, applied per opener.
use chacha20poly1305::{
aead::{Aead, AeadCore, KeyInit, OsRng as ChaChaOsRng},
XChaCha20Poly1305, XNonce,
};
use hkdf::Hkdf;
use sha2::Sha256;
use std::collections::VecDeque;
use x25519_dalek::{PublicKey, StaticSecret};
/// Current frame version. Bumped from `0x01` to `0x02` for HKDF + directional
/// subkeys + ephemeral DH. v1 frames are rejected with
/// [`UnsupportedFrameVersion`].
pub const FRAME_VERSION: u8 = 0x02;
/// Previous frame version. Surfaced so callers can build a stable error
/// message when an older peer sends a v1 frame post-upgrade.
pub const LEGACY_FRAME_VERSION_V1: u8 = 0x01;
/// Bootstrap messages use distinct wire markers so a legacy handshake cannot
/// silently bypass the new key schedule.
pub const HANDSHAKE_VERSION: u8 = 0x03;
pub const HANDSHAKE_ACK_VERSION: u8 = 0x04;
pub const HKDF_INFO_HANDSHAKE: &[u8] = b"openhuman-tunnel/v3/handshake";
pub const HKDF_INFO_HANDSHAKE_ACK: &[u8] = b"openhuman-tunnel/v3/handshake-ack";
const NONCE_LEN: usize = 24; // XChaCha20-Poly1305 nonce = 192 bits
const WINDOW_SIZE: usize = 128; // replay protection window
/// HKDF info tags for the two directional subkeys. Pinned strings — peer
/// implementations MUST use byte-identical values. Versioned under `v1` so
/// a future KDF-tag change can land without disturbing the FRAME_VERSION
/// counter.
pub const HKDF_INFO_C2S: &[u8] = b"openhuman-tunnel/v1/c2s";
pub const HKDF_INFO_S2C: &[u8] = b"openhuman-tunnel/v1/s2c";
/// Extract and expand bootstrap DH material before using it with an AEAD.
/// The public salt binds the key to the exchange's ephemeral public key;
/// the info tag separates the two bootstrap directions and session traffic.
pub fn derive_bootstrap_key(dh: &[u8; 32], salt: &[u8], info: &[u8]) -> [u8; 32] {
let mut key = [0u8; 32];
Hkdf::<Sha256>::new(Some(salt), dh)
.expand(info, &mut key)
.expect("32-byte HKDF output fits SHA-256 limit");
key
}
// ---------------------------------------------------------------------------
// Key material
// ---------------------------------------------------------------------------
/// An X25519 keypair used as the core's static device-pairing key.
pub struct DeviceKeypair {
private: StaticSecret,
/// Base64url-encoded public key (returned in QR payload).
pub pubkey_b64: String,
}
impl DeviceKeypair {
/// Generate a fresh X25519 static keypair.
pub fn generate() -> Self {
let bytes: [u8; 32] = rand::random();
let private = StaticSecret::from(bytes);
let public = PublicKey::from(&private);
let pubkey_b64 = base64url_encode(public.as_bytes());
log::debug!(
"[devices/crypto] keypair generated pubkey_len={}",
pubkey_b64.len()
);
Self {
private,
pubkey_b64,
}
}
/// Perform X25519 DH with the peer's public key.
///
/// Returns raw DH material for an HKDF key schedule; it must never be
/// passed directly to an AEAD constructor.
pub fn derive_shared_secret(&self, peer_pubkey_b64: &str) -> Result<[u8; 32], String> {
let peer_bytes = base64url_decode(peer_pubkey_b64)
.map_err(|e| format!("[devices/crypto] bad peer pubkey: {e}"))?;
if peer_bytes.len() != 32 {
return Err(format!(
"[devices/crypto] peer pubkey must be 32 bytes, got {}",
peer_bytes.len()
));
}
let peer_arr: [u8; 32] = peer_bytes.try_into().unwrap();
let peer_public = PublicKey::from(peer_arr);
let dh = self.private.diffie_hellman(&peer_public);
if dh.as_bytes().iter().all(|&byte| byte == 0) {
return Err("[devices/crypto] non-contributory peer public key".into());
}
log::debug!("[devices/crypto] DH completed, shared secret derived");
Ok(*dh.as_bytes())
}
/// Serialize the private key bytes for persistence (store encrypted).
pub fn private_bytes(&self) -> [u8; 32] {
self.private.to_bytes()
}
}
// ---------------------------------------------------------------------------
// Session-key derivation (HKDF over static + ephemeral DH)
// ---------------------------------------------------------------------------
/// Two 32-byte directional subkeys derived from the static + ephemeral DH
/// pair. `c2s` (client-to-server) is the key the device uses to seal
/// outgoing frames; `s2c` (server-to-client) is the key the core uses for
/// the reverse direction. Each peer's `TunnelCipher` carries both — its own
/// direction as the `seal_cipher` and the peer's as the `open_cipher` — so
/// a frame the server emits can never replay into the server's own decryptor
/// (cross-direction reflection attack class).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SessionKeys {
pub c2s: [u8; 32],
pub s2c: [u8; 32],
}
/// Derive `(c2s, s2c)` from a static DH secret and an ephemeral DH secret.
///
/// `static_dh` authenticates the peer (it was negotiated against the
/// long-term, paired-via-QR-code keys). `eph_dh` is negotiated against
/// fresh ephemeral keypairs minted at session start — so even if the static
/// keys leak later, prior session traffic cannot be recovered.
///
/// `salt = client_eph_pub || server_eph_pub` (in that fixed order) binds
/// the derived keys to both halves of the ephemeral exchange so neither
/// side can unilaterally pin the salt.
///
/// HKDF-SHA256 is constant-time and produces independent-looking subkeys
/// for the two `info` tags even when the underlying IKM is the same.
pub fn derive_session_keys(
static_dh: &[u8; 32],
eph_dh: &[u8; 32],
client_eph_pub: &[u8; 32],
server_eph_pub: &[u8; 32],
) -> SessionKeys {
let mut ikm = [0u8; 64];
ikm[..32].copy_from_slice(static_dh);
ikm[32..].copy_from_slice(eph_dh);
let mut salt = [0u8; 64];
salt[..32].copy_from_slice(client_eph_pub);
salt[32..].copy_from_slice(server_eph_pub);
let h = Hkdf::<Sha256>::new(Some(&salt), &ikm);
let mut c2s = [0u8; 32];
let mut s2c = [0u8; 32];
h.expand(HKDF_INFO_C2S, &mut c2s)
.expect("hkdf expand c2s len=32 fits in Sha256 output budget");
h.expand(HKDF_INFO_S2C, &mut s2c)
.expect("hkdf expand s2c len=32 fits in Sha256 output budget");
log::debug!("[devices/crypto] derived directional session keys (HKDF-SHA256)");
SessionKeys { c2s, s2c }
}
/// Which side of the tunnel is operating the cipher. Drives the
/// seal/open subkey selection in [`TunnelCipher::for_role`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TunnelRole {
/// Mobile / iOS device — seals with `c2s`, opens `s2c`.
Client,
/// Desktop core — seals with `s2c`, opens `c2s`.
Server,
}
// ---------------------------------------------------------------------------
// Frame cipher
// ---------------------------------------------------------------------------
/// Stateful cipher for sealing / opening tunnel frames.
///
/// Holds two `XChaCha20Poly1305` instances: `seal_cipher` for the local
/// direction and `open_cipher` for the peer's. When both peers derive keys
/// via [`derive_session_keys`] and call [`TunnelCipher::for_role`] with
/// their respective [`TunnelRole`], a frame the server emits cannot decrypt
/// under the server's own opener (since that opener holds `c2s`, while the
/// server seals with `s2c`).
///
/// Maintains a replay-protection window of the last `WINDOW_SIZE` nonces.
/// Thread safety: wrap in a `Mutex` or `RwLock` at the call site.
pub struct TunnelCipher {
seal_cipher: XChaCha20Poly1305,
open_cipher: XChaCha20Poly1305,
seen_nonces: VecDeque<[u8; NONCE_LEN]>,
}
impl TunnelCipher {
/// Compatibility constructor for older unit fixtures. Production
/// sessions use [`Self::for_role`] with directional subkeys.
#[cfg(test)]
pub fn new(key: &[u8; 32]) -> Self {
let derived = derive_bootstrap_key(
key,
b"openhuman-tunnel/compat",
b"openhuman-tunnel/compat/symmetric",
);
let cipher = XChaCha20Poly1305::new((&derived).into());
Self {
seal_cipher: cipher.clone(),
open_cipher: cipher,
seen_nonces: VecDeque::with_capacity(WINDOW_SIZE + 1),
}
}
/// Construct a directional cipher for the given role.
///
/// `Client` seals with `c2s` and opens `s2c`; `Server` is the inverse.
/// A v2 frame the server emits will NOT decrypt under the server's own
/// opener (the opener holds `c2s`, the frame is sealed with `s2c`) —
/// closing the cross-direction reflection attack class.
pub fn for_role(role: TunnelRole, keys: &SessionKeys) -> Self {
let (seal_key, open_key) = match role {
TunnelRole::Client => (&keys.c2s, &keys.s2c),
TunnelRole::Server => (&keys.s2c, &keys.c2s),
};
log::debug!(
"[devices/crypto] TunnelCipher created role={:?} (directional subkeys)",
role
);
Self {
seal_cipher: XChaCha20Poly1305::new(seal_key.into()),
open_cipher: XChaCha20Poly1305::new(open_key.into()),
seen_nonces: VecDeque::with_capacity(WINDOW_SIZE + 1),
}
}
/// Seal `plaintext` into a framed ciphertext.
///
/// Returns `version(1=0x02) || nonce(24) || ciphertext+tag`.
pub fn seal(&self, plaintext: &[u8]) -> Result<Vec<u8>, String> {
let nonce = XChaCha20Poly1305::generate_nonce(&mut ChaChaOsRng);
let ciphertext = self
.seal_cipher
.encrypt(&nonce, plaintext)
.map_err(|e| format!("[devices/crypto] seal failed: {e}"))?;
let mut frame = Vec::with_capacity(1 + NONCE_LEN + ciphertext.len());
frame.push(FRAME_VERSION);
frame.extend_from_slice(nonce.as_slice());
frame.extend_from_slice(&ciphertext);
log::trace!(
"[devices/crypto] sealed plaintext_len={} frame_len={}",
plaintext.len(),
frame.len()
);
Ok(frame)
}
/// Open a framed ciphertext produced by `seal`.
///
/// Rejects frames with a wrong version byte, a replayed nonce, or
/// authentication failure (tampered ciphertext).
///
/// Frames with `version = 0x01` (the pre-upgrade single-key shape) are
/// rejected with an explicit `UnsupportedFrameVersion` message so peers
/// see a clear "client upgrade required" signal instead of a generic AEAD
/// failure.
pub fn open(&mut self, frame: &[u8]) -> Result<Vec<u8>, String> {
if frame.is_empty() {
return Err("[devices/crypto] empty frame".into());
}
if frame[0] == LEGACY_FRAME_VERSION_V1 {
return Err(
"[devices/crypto] UnsupportedFrameVersion: legacy v1 frame rejected — \
peer must upgrade to v2 directional subkeys before reconnecting"
.into(),
);
}
if frame[0] != FRAME_VERSION {
return Err(format!(
"[devices/crypto] unsupported frame version: 0x{:02x}",
frame[0]
));
}
if frame.len() < 1 + NONCE_LEN {
return Err("[devices/crypto] frame too short for nonce".into());
}
let nonce_bytes: [u8; NONCE_LEN] = frame[1..1 + NONCE_LEN].try_into().unwrap();
let ciphertext = &frame[1 + NONCE_LEN..];
// Replay protection: reject nonces we've already decrypted.
if self.seen_nonces.contains(&nonce_bytes) {
return Err("[devices/crypto] replayed nonce — frame rejected".into());
}
let nonce = XNonce::from(nonce_bytes);
let plaintext = self
.open_cipher
.decrypt(&nonce, ciphertext)
.map_err(|_| "[devices/crypto] authentication failed — tampered frame")?;
// Slide the window forward.
if self.seen_nonces.len() >= WINDOW_SIZE {
self.seen_nonces.pop_front();
}
self.seen_nonces.push_back(nonce_bytes);
log::trace!(
"[devices/crypto] opened frame_len={} plaintext_len={}",
frame.len(),
plaintext.len()
);
Ok(plaintext)
}
}
// ---------------------------------------------------------------------------
// Base64url helpers
// ---------------------------------------------------------------------------
pub fn base64url_encode(bytes: &[u8]) -> String {
use base64::Engine;
base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(bytes)
}
pub fn base64url_decode(s: &str) -> Result<Vec<u8>, String> {
use base64::Engine;
base64::engine::general_purpose::URL_SAFE_NO_PAD
.decode(s)
.map_err(|e| format!("base64url decode error: {e}"))
}
// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------
#[cfg(test)]
#[path = "crypto_tests.rs"]
mod tests;