README.md

minimal peer-to-peer network protocol using QUIC transport and ed25519 identities.

Build and Development Commands

Building

cargo build                           # Debug build
cargo build --release                 # Release build with optimizations
cargo build --features webtransport   # Build with webtransport support

Running

cargo run -- -l              # Run server mode
cargo run -- localhost       # Run client mode
cargo run --example shell    # Run shell example
cargo run --example chat     # Run chat example
cargo run --features webtransport --example webtransport_chat

Architecture Overview

quicnet is a minimal peer-to-peer network protocol built on QUIC transport with Ed25519 identity-based authentication. The architecture binds cryptographic identities directly to the TLS layer, eliminating the need for certificate authorities.

Core Identity System

• PeerId: 32-byte Ed25519 public key, encoded in base256 format (with hex fallback)
• Identity: Ed25519 keypair stored in SSH-compatible format (default: ~/.quicnet/id_ed25519)
• TLS certificates are self-signed and derived from the Ed25519 identity
• The SPKI (Subject Public Key Info) in the X.509 certificate equals the PeerId, preventing MITM attacks
• Base256 encoding creates visually distinctive, copy-paste-only peer identifiers

Module Structure

Core Modules (src/)

• identity.rs: Ed25519 keypair management, SSH key parsing, PeerId generation with base256/hex encoding
• peer.rs: Unified peer implementation that can both dial and accept connections
• auth.rs: Symmetric application-layer challenge-response authentication protocol

Transport Layer (src/transport/)

• stream.rs: Authenticated bidirectional stream abstraction
• builder.rs: Peer configuration builders with rate limiting and audit options
• web_compat.rs: WebTransport compatibility layer (optional feature)

Security Features (src/security/)

• rate_limit.rs: Connection rate limiting per IP address
• audit.rs: Security event logging system

Peer Management

• authorized_peers.rs: Whitelist of allowed peer identities
• known_hosts.rs: Trust-on-first-use (TOFU) store for peer identities
• pending_peers.rs: Queue for peers awaiting authorization

Protocol Flow

1. Either peer initiates QUIC connection with self-signed Ed25519 certificate
2. Remote peer accepts with its own Ed25519 certificate
3. Both sides verify the peer's SPKI matches expected PeerId (if provided)
4. Symmetric application-layer challenge-response confirms mutual authentication
5. First bi-stream is opened for stdin/stdout piping

Key Design Decisions

• No central authority: Identities are cryptographic keys, not certificates from a CA
• Symmetric design: Single Peer type handles both dialing and accepting
• TLS binding: Prevents relay MITM attacks during handshake
• SSH compatibility: Reuses existing Ed25519 SSH keys when available
• URL-safe encoding: Base32 encoding works in URLs and is case-insensitive
• WebTransport ready: Optional feature for browser compatibility