docs: add README, LICENSE files, and crate/module-level doc comments

Add top-level README.md with alpha status warning, quick start guide,
architecture overview, feature flags, transport modes, auth docs, and
Node.js API examples.

Add dual LICENSE-MIT and LICENSE-APACHE files.

Add comprehensive crate-level and module-level rustdoc to all three
crates (wraith-core, wraith, wraith-napi) and all public modules
(transport, client, server, auth, socks5, error). Add doc comments to
key public types (Transport, TransportAcceptor, ConnectOptions,
ClientSession, Server, ServeOptions, KeySource, ServerAuthConfig, etc).

Update Cargo.toml files with workspace-level package metadata
(version, edition, license, repository) and crate descriptions.

crates/wraith-core/Cargo.toml

@@ -1,7 +1,10 @@
 [package]
 name = "wraith-core"
-version = "0.1.0"
-edition = "2021"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+description = "Core library for Wraith: pluggable SSH tunnel transport, SOCKS5 proxy, port forwarding, and authentication"
+repository.workspace = true
 
 [lib]
 name = "wraith_core"

crates/wraith-core/src/auth/keys.rs

@@ -1,15 +1,29 @@
+//! Key loading and parsing for SSH authentication.
+//!
+//! Supports `KeySource` (file path or in-memory) for private keys, public keys,
+//! and certificate authority entries. All keys must be in OpenSSH format.
+//! PEM-encoded keys (PKCS#1, PKCS#8) are rejected with a clear error message.
+
 use std::path::PathBuf;
 
 use russh::keys::{PrivateKey, PublicKey, decode_secret_key, parse_public_key_base64};
 
 use crate::error::ConfigError;
 
+/// Source for key material — either a filesystem path or in-memory bytes.
+///
+/// Used throughout the API to accept keys without committing to a specific
+/// loading mechanism. In-memory keys are primarily for the NAPI wrapper.
 #[derive(Debug, Clone)]
 pub enum KeySource {
     File(PathBuf),
     Memory(Vec<u8>),
 }
 
+/// A certificate authority entry parsed from an `authorized_keys` file.
+///
+/// Contains the CA public key and its associated options (e.g., `cert-authority`,
+/// `permit-port-forwarding`). Used by `ServerAuthConfig` for certificate validation.
 #[derive(Debug, Clone)]
 pub struct CertAuthorityEntry {
     pub public_key: PublicKey,

crates/wraith-core/src/auth/mod.rs

@@ -1,3 +1,8 @@
+//! SSH authentication (Ed25519 public key and OpenSSH certificate authority).
+//!
+//! Supports file-path and in-memory key sources. No password authentication.
+//! See ADR-012 for the design rationale.
+
 pub mod client_auth;
 pub mod keys;
 pub mod server_auth;

crates/wraith-core/src/auth/server_auth.rs

@@ -1,3 +1,9 @@
+//! Server-side authentication configuration and validation.
+//!
+//! `ServerAuthConfig` holds the set of authorized public keys and optional certificate
+//! authority entries. Authentication is key-based only (Ed25519 + optional OpenSSH CA).
+//! No password authentication. See ADR-012.
+
 use std::collections::HashSet;
 use std::net::IpAddr;
 use std::str::FromStr;
@@ -10,6 +16,10 @@ use russh::keys::{Certificate, PublicKey};
 use super::keys::{CertAuthorityEntry, KeySource, load_cert_authority_entries, load_public_keys};
 use crate::error::AuthError;
 
+/// Server-side authentication configuration.
+///
+/// Holds authorized public keys (constant-time comparison) and optional certificate
+/// authority entries for validating OpenSSH certificates.
 #[derive(Debug, Clone)]
 pub struct ServerAuthConfig {
     pub authorized_keys: HashSet<PublicKey>,

crates/wraith-core/src/client/channel_manager.rs

@@ -1,3 +1,11 @@
+//! Channel manager with automatic reconnection.
+//!
+//! Owns the SSH session handle and provides `open_direct_tcpip()`,
+//! `request_tcpip_forward()`, and `cancel_tcpip_forward()`. Monitors
+//! the session for disconnect and attempts reconnection with exponential
+//! backoff (1s, 2s, 4s, ..., 30s cap). Re-registers remote forwards
+//! after successful reconnection.
+
 use std::collections::HashSet;
 use std::sync::Arc;
 use std::time::Duration;

crates/wraith-core/src/client/connect.rs

@@ -1,3 +1,9 @@
+//! Client session management and connection logic.
+//!
+//! `ClientSession` establishes an SSH connection over a transport, authenticates,
+//! starts a SOCKS5 proxy, sets up port forwards, and monitors for reconnection.
+//! `ConnectOptions` provides a builder-pattern API for programmatic configuration.
+
 use std::net::SocketAddr;
 use std::sync::Arc;
 use std::time::Duration;
@@ -17,6 +23,7 @@ use crate::transport::Transport;
 const DEFAULT_SOCKS5_ADDR: &str = "127.0.0.1:1080";
 const DRAIN_TIMEOUT: Duration = Duration::from_secs(2);
 
+/// Transport mode for the client connection.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum TransportMode {
     Tcp,
@@ -34,6 +41,22 @@ impl std::fmt::Display for TransportMode {
     }
 }
 
+/// Programmatic configuration for a wraith client session.
+///
+/// Construct with `ConnectOptions::new(key_source)` and chain builder methods.
+/// Call `validate()` before passing to `ClientSession::new()`.
+///
+/// ```
+/// use wraith_core::client::{ConnectOptions, TransportMode};
+/// use wraith_core::auth::keys::KeySource;
+///
+/// let opts = ConnectOptions::new(KeySource::File("/path/to/key".into()))
+///     .server("example.com:22")
+///     .transport_mode(TransportMode::Tcp)
+///     .socks5_addr("127.0.0.1:1080")
+///     .forward("5432:db.internal:5432");
+/// opts.validate().unwrap();
+/// ```
 #[derive(Clone)]
 pub struct ConnectOptions {
     pub server: Option<String>,
@@ -155,6 +178,11 @@ impl std::fmt::Debug for ConnectOptions {
     }
 }
 
+/// An active SSH client session over a transport.
+///
+/// Establishes the connection, authenticates, and runs a SOCKS5 proxy plus
+/// port forwards until shutdown or transport failure. On transport failure,
+/// attempts reconnection with exponential backoff (1s, 2s, 4s, ..., 30s cap).
 pub struct ClientSession<T: Transport> {
     opts: ConnectOptions,
     transport: Arc<T>,
@@ -489,6 +517,7 @@ fn build_remote_specs(opts: &ConnectOptions) -> Result<Vec<PortForwardSpec>, Con
     Ok(specs)
 }
 
+/// Errors that can occur during client connection setup and operation.
 #[derive(Debug, thiserror::Error)]
 pub enum ConnectError {
     #[error("connection failed")]

crates/wraith-core/src/client/forward.rs

@@ -1,3 +1,10 @@
+//! Local and remote port forwarding.
+//!
+//! `LocalForwarder` binds a local TCP listener and forwards each connection through
+//! an SSH `direct-tcpip` channel. `RemoteForwarder` requests `tcpip-forward` from
+//! the server and handles `forwarded-tcpip` channels. Specs follow the
+//! `bind_addr:bind_port:target_host:target_port` format.
+
 use std::net::SocketAddr;
 use std::sync::Arc;
 

crates/wraith-core/src/client/mod.rs

@@ -1,3 +1,13 @@
+//! Client-side SSH session management.
+//!
+//! Provides `ClientSession` for establishing an SSH connection over any transport,
+//! running a local SOCKS5 proxy, and managing port forwards. Also provides
+//! `ChannelManager` for programmatic channel management with automatic reconnection.
+//!
+//! The client always starts a SOCKS5 proxy (default `127.0.0.1:1080`) when running
+//! via `ClientSession::run()`. For VPN-like "route all traffic" behavior, use
+//! [tun2proxy](https://github.com/tun2proxy/tun2proxy) alongside the SOCKS5 proxy.
+
 pub mod channel_manager;
 pub mod connect;
 pub mod forward;

crates/wraith-core/src/error.rs

@@ -1,3 +1,12 @@
+//! Error types for wraith-core.
+//!
+//! Layered error hierarchy:
+//! - `TransportError` — connection/handshake/timeout errors (trigger reconnection on client)
+//! - `AuthError` — key rejection, certificate validation failures
+//! - `ChannelError` — per-channel failures (target unreachable, channel closed)
+//! - `ConfigError` — invalid configuration (flags, key files, bind failures)
+//! - `ForwardError` — port forward setup and connection failures
+
 use std::io;
 
 #[derive(Debug, thiserror::Error)]

crates/wraith-core/src/lib.rs

@@ -1,3 +1,55 @@
+//! # wraith-core
+//!
+//! Core library for [Wraith](https://github.com/alkdev/wraith), a self-hostable SSH-based
+//! tunnel tool. This crate provides the transport abstraction, SOCKS5 server, port forwarding,
+//! authentication, and server handler — everything needed to build a wraith client or server
+//! on top of pluggable transports.
+//!
+//! > **Alpha software.** This crate depends on solid libraries (russh, tokio, rustls, iroh)
+//! > for core functionality, but the integration layer has not been battle-tested. Use with
+//! > caution and report issues.
+//!
+//! # Key concepts
+//!
+//! - **Transport trait** — produces a duplex byte stream (`AsyncRead + AsyncWrite + Unpin + Send`)
+//!   that SSH consumes. Implementations: TCP, TLS, iroh (QUIC P2P).
+//! - **SOCKS5 server** — the primary client interface, listening on a local port and routing
+//!   traffic through SSH channels.
+//! - **Port forwarding** — `-L` local and `-R` remote port forwards over SSH channels.
+//! - **Authentication** — Ed25519 public key and OpenSSH certificate authority. No passwords.
+//! - **Server handler** — accepts SSH connections via a `TransportAcceptor` and proxies
+//!   `direct-tcpip` channel requests to targets (directly or via outbound proxy).
+//!
+//! # Feature flags
+//!
+//! | Feature | Default | Description |
+//! |---------|---------|-------------|
+//! | `tls` | yes | TLS transport via `tokio-rustls` |
+//! | `iroh` | yes | iroh QUIC P2P transport |
+//! | `acme` | no | ACME/Let's Encrypt auto-cert provisioning (implies `tls`) |
+//! | `testutil` | no | Test utilities (for internal use) |
+//!
+//! # Quick example
+//!
+//! ```no_run
+//! use std::sync::Arc;
+//! use wraith_core::transport::TcpTransport;
+//! use wraith_core::client::{ClientSession, ConnectOptions, TransportMode};
+//! use wraith_core::auth::keys::KeySource;
+//! use wraith_core::Transport;
+//!
+//! #[tokio::main]
+//! async fn main() -> anyhow::Result<()> {
+//!     let opts = ConnectOptions::new(KeySource::File("/path/to/key".into()))
+//!         .server("example.com:22")
+//!         .transport_mode(TransportMode::Tcp);
+//!     let transport = Arc::new(TcpTransport::new("example.com:22".parse()?));
+//!     let session = ClientSession::new(opts, transport).await?;
+//!     session.run().await?;
+//!     Ok(())
+//! }
+//! ```
+
 pub mod transport;
 pub mod client;
 pub mod server;

crates/wraith-core/src/server/channel_proxy.rs

@@ -1,3 +1,9 @@
+//! Outbound connection proxy for SSH channel targets.
+//!
+//! Connects to the requested `host:port` either directly, via SOCKS5 proxy, or
+//! via HTTP CONNECT proxy, then proxies bytes bidirectionally between the SSH
+//! channel and the outbound TCP stream.
+
 use std::net::SocketAddr;
 
 use tokio::io::{AsyncReadExt, AsyncWriteExt};

crates/wraith-core/src/server/control_channel.rs

@@ -1,3 +1,9 @@
+//! Control channel routing for reserved `wraith-*` destinations.
+//!
+//! SSH channels opened with a destination starting with `wraith-` are intercepted
+//! by the server and routed to a `ControlChannelHandler` instead of proxied to a
+//! TCP target. See ADR-018 for the design rationale.
+
 use std::io;
 
 use async_trait::async_trait;

crates/wraith-core/src/server/mod.rs

@@ -1,3 +1,12 @@
+//! Server-side SSH connection handling.
+//!
+//! Provides `Server` for accepting SSH connections over any transport and proxying
+//! `direct-tcpip` channel requests to targets. Supports Ed25519 and certificate-authority
+//! auth, connection rate limiting, auth attempt limiting, stealth mode (fake nginx 404),
+//! and outbound proxy routing (direct/SOCKS5/HTTP CONNECT).
+//!
+//! Destination hosts starting with `wraith-` are reserved for internal use (control channel, ADR-018).
+
 pub mod channel_proxy;
 pub mod control_channel;
 pub mod handler;

crates/wraith-core/src/server/rate_limit.rs

@@ -1,3 +1,10 @@
+//! Connection rate limiting and auth attempt limiting.
+//!
+//! `ConnectionRateLimiter` tracks per-IP active connections (thread-safe).
+//! `AuthAttemptLimiter` caps failed auth attempts per connection.
+//! These complement fail2ban on Linux and provide abuse protection on all platforms.
+//! See ADR-013.
+
 use std::collections::HashMap;
 use std::net::IpAddr;
 use std::sync::Mutex;

crates/wraith-core/src/server/serve.rs

@@ -1,3 +1,9 @@
+//! Server configuration and accept loop.
+//!
+//! `Server` binds to a transport acceptor and runs an accept loop, handling
+//! authentication, stealth mode protocol detection, and graceful shutdown.
+//! `ServeOptions` provides a builder-pattern API for programmatic configuration.
+
 use std::net::SocketAddr;
 use std::sync::Arc;
 use std::time::Duration;
@@ -16,6 +22,7 @@ use crate::server::stealth::{self, ProtocolDetection};
 const DEFAULT_LISTEN_ADDR: &str = "0.0.0.0:22";
 const DRAIN_TIMEOUT: Duration = Duration::from_secs(2);
 
+/// Transport mode for the server listener.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum ServeTransportMode {
     Tcp,
@@ -33,6 +40,22 @@ impl std::fmt::Display for ServeTransportMode {
     }
 }
 
+/// Programmatic configuration for a wraith server.
+///
+/// Construct with `ServeOptions::new(key_source)` and chain builder methods.
+/// Call `validate()` before passing to `Server::new()`.
+///
+/// ```
+/// use wraith_core::server::{ServeOptions, ServeTransportMode};
+/// use wraith_core::auth::keys::KeySource;
+///
+/// let opts = ServeOptions::new(KeySource::File("/path/to/host_key".into()))
+///     .transport_mode(ServeTransportMode::Tcp)
+///     .listen_addr("0.0.0.0:22")
+///     .max_connections_per_ip(5)
+///     .max_auth_attempts(3);
+/// opts.validate().unwrap();
+/// ```
 pub struct ServeOptions {
     pub key: KeySource,
     pub authorized_keys: Option<KeySource>,
@@ -180,6 +203,7 @@ impl std::fmt::Debug for ServeOptions {
     }
 }
 
+/// Errors that can occur during server setup and operation.
 #[derive(Debug, thiserror::Error)]
 pub enum ServeError {
     #[error("config error: {0}")]
@@ -197,6 +221,11 @@ struct ActiveSession {
     join: tokio::task::JoinHandle<()>,
 }
 
+/// The wraith SSH server.
+///
+/// Accepts connections over any `TransportAcceptor`, authenticates via Ed25519 keys
+/// or certificate authority, and proxies `direct-tcpip` channels to their targets.
+/// Supports stealth mode (TLS only), outbound proxy routing, and connection rate limiting.
 pub struct Server {
     config: Arc<server::Config>,
     auth_config: Arc<ServerAuthConfig>,

crates/wraith-core/src/server/stealth.rs

@@ -1,3 +1,11 @@
+//! Stealth mode: protocol detection on TLS connections.
+//!
+//! When stealth mode is enabled with TLS transport, the server peeks at the first
+//! bytes after the TLS handshake to determine whether the client is speaking SSH
+//! or HTTP. Non-SSH connections receive a fake nginx 404 response, making the
+//! server appear as an ordinary web server to port scanners and DPI systems.
+//! See ADR-017.
+
 use tokio::io::{AsyncBufReadExt, AsyncRead, AsyncWrite, AsyncWriteExt, BufReader};
 
 const SSH_BANNER_PREFIX: &[u8] = b"SSH-2.0-";

crates/wraith-core/src/socks5/mod.rs

@@ -1,3 +1,10 @@
+//! SOCKS5 proxy server.
+//!
+//! Listens on a local port and routes each SOCKS5 connection through an SSH
+//! `direct-tcpip` channel. Supports SOCKS5h (domain names resolved server-side)
+//! to prevent DNS leaks. Uses the `ChannelOpener` trait to abstract over the
+//! SSH channel mechanism, making it testable without a real SSH session.
+
 mod protocol;
 
 use std::net::SocketAddr;

crates/wraith-core/src/transport/mod.rs

@@ -1,3 +1,18 @@
+//! Pluggable transport layer for Wraith.
+//!
+//! The transport layer produces a duplex byte stream (`AsyncRead + AsyncWrite + Unpin + Send`)
+//! that SSH consumes. This is the core architectural abstraction — SSH never opens its own
+//! network connections; it runs entirely over whatever stream the transport provides.
+//!
+//! Available transports (feature-gated):
+//! - `TcpTransport` / `TcpAcceptor` — always available, direct TCP
+//! - `TlsTransport` / `TlsAcceptor` — behind the `tls` feature, TCP + rustls
+//! - `IrohTransport` / `IrohAcceptor` — behind the `iroh` feature, QUIC P2P via iroh
+//! - `AcmeTlsAcceptor` — behind the `acme` feature, auto-provision TLS certs via Let's Encrypt
+//!
+//! See [ADR-001](docs/architecture/decisions/001-pluggable-transport.md) and
+//! [ADR-004](docs/architecture/decisions/004-ssh-over-transport.md) for design rationale.
+
 mod tcp;
 #[cfg(feature = "iroh")]
 mod iroh_transport;
@@ -24,19 +39,33 @@ use anyhow::Result;
 use async_trait::async_trait;
 use tokio::io::{AsyncRead, AsyncWrite};
 
+/// Client-side transport trait. Produces a single duplex stream per connection.
+///
+/// Implementations connect to a remote endpoint and return a stream that SSH
+/// runs over via `russh::client::connect_stream()`. Each call to `connect()` creates
+/// a new stream — multiple sessions need multiple calls or multiple transports.
 #[async_trait]
 pub trait Transport: Send + Sync + 'static {
+    /// The duplex stream type produced by this transport.
     type Stream: AsyncRead + AsyncWrite + Unpin + Send + 'static;
 
+    /// Connect to the remote endpoint and return a duplex stream.
     async fn connect(&self) -> Result<Self::Stream>;
 
+    /// Return a human-readable description of this transport for logging.
     fn describe(&self) -> String;
 }
 
+/// Server-side transport acceptor. Accepts incoming connections and returns streams.
+///
+/// Implementations bind to a local endpoint and produce streams that SSH
+/// runs over via `russh::server::run_stream()`.
 #[async_trait]
 pub trait TransportAcceptor: Send + Sync + 'static {
+    /// The duplex stream type produced by this acceptor.
     type Stream: AsyncRead + AsyncWrite + Unpin + Send + 'static;
 
+    /// Accept an incoming connection and return a duplex stream with metadata.
     async fn accept(&self) -> Result<(Self::Stream, TransportInfo)>;
 }
 

crates/wraith-napi/Cargo.toml

@@ -1,7 +1,10 @@
 [package]
 name = "wraith-napi"
-version = "0.1.0"
-edition = "2021"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+description = "Node.js native addon for Wraith via napi-rs: connect() and serve() SSH tunnel functions"
+repository.workspace = true
 
 [lib]
 crate-type = ["cdylib"]

crates/wraith-napi/src/connect.rs

@@ -1,3 +1,9 @@
+//! NAPI `connect()` function and `WraithStream` type.
+//!
+//! Opens a single SSH channel as a duplex stream for programmatic use.
+//! Unlike the CLI client, this does not start a SOCKS5 server or port forwards —
+//! it provides a raw stream that JavaScript code can read from and write to.
+
 use std::net::SocketAddr;
 use std::sync::Arc;
 

crates/wraith-napi/src/lib.rs

@@ -1,3 +1,26 @@
+//! # wraith-napi
+//!
+//! Node.js native addon for [Wraith](https://github.com/alkdev/wraith) via napi-rs.
+//! Exposes `connect()` and `serve()` functions for programmatic SSH tunnel creation.
+//!
+//! > **Alpha software.** The NAPI interface may change between versions.
+//!
+//! # Quick example (Node.js)
+//!
+//! ```js
+//! const { connect, serve } = require('wraith-napi');
+//!
+//! // Client: open a duplex SSH stream
+//! const stream = await connect({
+//!   server: "example.com:22",
+//!   transport: "tcp",
+//!   identity: "/path/to/key",
+//! });
+//! await stream.write(Buffer.from("hello"));
+//! const data = await stream.read(1024);
+//! await stream.close();
+//! ```
+
 #[allow(unused_imports)]
 #[macro_use]
 extern crate napi_derive;

crates/wraith-napi/src/serve.rs

@@ -1,3 +1,9 @@
+//! NAPI `serve()` function and `WraithServer` type.
+//!
+//! Starts a TCP-based SSH server that emits new channel streams via a
+//! `ThreadsafeFunction` callback. Currently supports TCP transport only;
+//! TLS and iroh will be added in a future release.
+
 use std::net::SocketAddr;
 use std::sync::Arc;
 

crates/wraith/Cargo.toml

@@ -1,7 +1,10 @@
 [package]
 name = "wraith"
-version = "0.1.0"
-edition = "2021"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+description = "CLI binary for Wraith: self-hostable SSH tunnel tool with pluggable transports"
+repository.workspace = true
 
 [[bin]]
 name = "wraith"

crates/wraith/src/main.rs

@@ -1,3 +1,11 @@
+//! # wraith
+//!
+//! CLI binary for [Wraith](https://github.com/alkdev/wraith), a self-hostable SSH-based tunnel
+//! tool. Provides `wraith connect` (client) and `wraith serve` (server) subcommands with
+//! pluggable transports (TCP, TLS, iroh).
+//!
+//! > **Alpha software.** See `wraith-core` for library usage.
+
 use std::net::SocketAddr;
 use std::process;
 use std::sync::Arc;