Module relay

zoe_relay

Module relay 

Source
Expand description

§Zoe Relay

A clean, minimal QUIC relay server with ed25519 bi-directional authentication for service routing.

§Features

  • QUIC Transport: High-performance transport with TLS 1.3 and ed25519 identity verification
  • Service Routing: Routes connections to different services based on a u8 service identifier
  • Bi-directional Streams: Full duplex communication between client and server
  • Ed25519 Authentication: Client identity verification via embedded public keys in certificates
  • Trait-based Design: Clean abstraction for implementing service handlers

§Architecture

The relay accepts QUIC connections, authenticates clients via ed25519 keys, reads the first byte of the stream to determine the service type, and routes the connection to the appropriate service handler:

Client → QUIC Connection → ed25519 Auth → Read Service ID (u8) → Route to Service
   ↓           ↓                ↓              ↓                    ↓
Certificate  TLS 1.3        Extract Key    First Byte        ServiceRouter::create_service

§Usage

§Implementing a Service Router

use zoe_relay::{RelayServer, ServiceRouter};
use ed25519_dalek::SigningKey;
use std::net::SocketAddr;
use zoe_wire_protocol::KeyPair;

let addr: SocketAddr = "127.0.0.1:4433".parse()?;
let server_keypair = KeyPair::generate_ml_dsa44(&mut rand::rngs::OsRng);
let router = MyServiceRouter; // Your ServiceRouter implementation

let server = RelayServer::new(addr, server_keypair, router)?;
println!("🚀 Relay server running on {}", addr);
server.run().await?;

For detailed service routing examples, see the router module documentation.

§Transport Details

§QUIC with Ed25519 Authentication

  • QUIC Protocol: Multiplexed, encrypted transport with connection-level authentication
  • TLS 1.3: Latest TLS with ed25519-derived certificates
  • Client Authentication: Client identity verification via ed25519 keys embedded in certificates
  • Certificate Embedding: Public keys embedded in X.509 certificate extensions

§Server Protocol Flow

  1. Connection Establishment: Client connects via QUIC with ed25519 certificate
  2. Mutual Authentication: Server and client verify each other’s ed25519 certificates
  3. Connection Handling: Server extracts client public key and connection metadata
  4. Service Delegation: Hands over streams and client info to the ServiceRouter

§Security Model

§Authentication Flow

  1. Certificate Generation: Ed25519 keys embedded in deterministic self-signed certificates
  2. QUIC Handshake: TLS authentication with client certificate verification
  3. Key Extraction: Server extracts client’s ed25519 public key from certificate
  4. Service Routing: Authenticated client streams are routed to appropriate services

§Identity and Trust

  • Certificate-based: Client identity is embedded in the certificate
  • Key-based identity: Identity is the ed25519 public key itself
  • Connection-scoped: Authentication valid for entire QUIC connection lifetime
  • Service-agnostic: Authentication happens once, all services trust the identity

Structs§

RelayServer
Main relay server that accepts QUIC connections with transport authentication
RelayServerBuilder

Enums§

RelayServerBuilderError
RelayServerError

Type Aliases§

FullRelayServer