From 9821aabf0b50d2487b07502d3d2cd89e7d62bdbe Mon Sep 17 00:00:00 2001
From: murilo ijanc
Date: Tue, 24 Mar 2026 15:04:03 -0300
Subject: Initial commit

NAT-aware Kademlia DHT library for peer-to-peer networks.

Features:
- Distributed key-value storage (iterative FIND_NODE, FIND_VALUE, STORE)
- NAT traversal via DTUN hole-punching and proxy relay
- Reliable Datagram Protocol (RDP) with 7-state connection machine
- Datagram transport with automatic fragmentation/reassembly
- Ed25519 packet authentication
- 256-bit node IDs (Ed25519 public keys)
- Rate limiting, ban list, and eclipse attack mitigation
- Persistence and metrics
- OpenBSD and Linux support
---
 src/lib.rs | 128 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 128 insertions(+)
 create mode 100644 src/lib.rs

(limited to 'src/lib.rs')

diff --git a/src/lib.rs b/src/lib.rs
new file mode 100644
index 0000000..f956f98
--- /dev/null
+++ b/src/lib.rs
@@ -0,0 +1,128 @@
+// Allow nested if-let until we migrate to let-chains
+#![allow(clippy::collapsible_if)]
+
+//! # tesseras-dht
+//!
+//! NAT-aware Kademlia DHT library for peer-to-peer
+//! networks.
+//!
+//! `tesseras-dht` provides:
+//!
+//! - **Distributed key-value storage** via Kademlia
+//!   (iterative FIND_NODE, FIND_VALUE, STORE)
+//! - **NAT traversal** via DTUN (hole-punching) and
+//!   proxy relay (symmetric NAT)
+//! - **Reliable transport** (RDP) over UDP
+//! - **Datagram transport** with automatic fragmentation
+//!
+//! ## Quick start
+//!
+//! ```rust,no_run
+//! use tesseras_dht::{Node, NatState};
+//!
+//! let mut node = Node::bind(10000).unwrap();
+//! node.set_nat_state(NatState::Global);
+//! node.join("bootstrap.example.com", 10000).unwrap();
+//!
+//! // Store and retrieve values
+//! node.put(b"key", b"value", 300, false);
+//!
+//! // Event loop
+//! loop {
+//!     node.poll().unwrap();
+//!     # break;
+//! }
+//! ```
+//!
+//! ## Architecture
+//!
+//! ```text
+//! ┌─────────────────────────────────────────┐
+//! │            Node (facade)              │
+//! │  ┌──────┐ ┌────────┐ ┌──────────────┐  │
+//! │  │ DHT  │ │Routing │ │   Storage    │  │
+//! │  │      │ │ Table  │ │  (DhtStorage)│  │
+//! │  └──────┘ └────────┘ └──────────────┘  │
+//! │  ┌──────┐ ┌────────┐ ┌──────────────┐  │
+//! │  │ DTUN │ │  NAT   │ │    Proxy     │  │
+//! │  │      │ │Detector│ │              │  │
+//! │  └──────┘ └────────┘ └──────────────┘  │
+//! │  ┌──────┐ ┌────────┐ ┌──────────────┐  │
+//! │  │ RDP  │ │ Dgram  │ │   Timers     │  │
+//! │  └──────┘ └────────┘ └──────────────┘  │
+//! │  ┌──────────────────────────────────┐   │
+//! │  │     NetLoop (mio / kqueue)      │   │
+//! │  └──────────────────────────────────┘   │
+//! └─────────────────────────────────────────┘
+//! ```
+//!
+//! ## Security (OpenBSD)
+//!
+//! Sandboxing with pledge(2) and unveil(2) is an
+//! application-level concern. Call them in your binary
+//! after binding the socket. The library only needs
+//! `"stdio inet dns"` promises.
+
+/// Address advertisement protocol.
+pub mod advertise;
+/// Ban list for misbehaving peers.
+pub mod banlist;
+/// Node configuration.
+pub mod config;
+/// Ed25519 identity and packet signing.
+pub mod crypto;
+/// Datagram transport with fragmentation/reassembly.
+pub mod dgram;
+/// Kademlia DHT storage and iterative queries.
+pub mod dht;
+/// Distributed tunnel for NAT traversal.
+pub mod dtun;
+/// Error types.
+pub mod error;
+/// Event types for typed callback integration.
+pub mod event;
+/// Packet dispatch and message handlers.
+mod handlers;
+/// 256-bit node identity.
+pub mod id;
+/// Node metrics and observability.
+pub mod metrics;
+/// Wire message body parsing and writing.
+pub mod msg;
+/// NAT type detection (STUN-like echo protocol).
+pub mod nat;
+/// Network send helpers and query management.
+mod net;
+/// Main facade: the [`Node`].
+pub mod node;
+/// Peer node database.
+pub mod peers;
+/// Persistence traits for data and routing table.
+pub mod persist;
+/// Proxy relay for symmetric NAT nodes.
+pub mod proxy;
+/// Per-IP rate limiting.
+pub mod ratelimit;
+/// Reliable Datagram Protocol (RDP).
+pub mod rdp;
+/// Kademlia routing table with k-buckets.
+pub mod routing;
+/// UDP I/O via mio (kqueue on OpenBSD).
+pub mod socket;
+/// Store acknowledgment tracking.
+pub mod store_track;
+/// OpenBSD arc4random_buf(3) for secure random bytes.
+pub mod sys;
+/// Timer wheel for scheduling callbacks.
+pub mod timer;
+/// On-the-wire binary protocol (header, message types).
+pub mod wire;
+
+// Re-export the main types for convenience.
+pub use error::Error;
+pub use id::NodeId;
+pub use nat::NatState;
+
+// Re-export sha2 for downstream crates.
+pub use sha2;
+pub use node::Node;
-- 
cgit v1.2.3