ap_proxy/lib.rs
1//! WebSocket proxy server for secure peer-to-peer messaging.
2//!
3//! This crate provides the proxy server that accepts WebSocket connections,
4//! authenticates clients, and routes messages between them. The server is
5//! zero-knowledge and cannot decrypt client payloads.
6//!
7//! For the client library, see the `ap-proxy-client` crate.
8//! For shared protocol types, see the `ap-proxy-protocol` crate.
9//!
10//! # Architecture
11//!
12//! The proxy routes messages between authenticated clients:
13//!
14//! ```text
15//! Client A Proxy Server Client B
16//! | | |
17//! |---(1) WebSocket Connect---->| |
18//! |<--(2) Auth Challenge--------| |
19//! |---(3) Signed Response------>| |
20//! | |<---(1) WebSocket Connect----|
21//! | |----(2) Auth Challenge------>|
22//! | |<---(3) Signed Response------|
23//! | | |
24//! |---(4) Request Rendezvous--->| |
25//! |<--(5) Code: "ABC-DEF-GHI"---| |
26//! | | |
27//! | |<---(6) Lookup "ABC-DEF-GHI"-|
28//! | |----(7) Identity of A------->|
29//! | | |
30//! | |<---(8) Encrypted Message----|
31//! |<--(9) Relay Message---------| |
32//! ```
33//!
34//! ## Three-Phase Protocol
35//!
36//! ### Phase 1: Authentication
37//!
38//! When a client connects, the server sends a cryptographic challenge. The client signs this
39//! challenge with its identity key pair and sends the response back. The server verifies
40//! the signature to authenticate the client's identity. This proves possession of the private
41//! key without revealing it.
42//!
43//! ### Phase 2: Rendezvous (Optional)
44//!
45//! Clients can request temporary rendezvous codes (e.g., "ABC-DEF-GHI") that are valid for 5 minutes.
46//! Other clients can look up an identity by providing the code, enabling peer discovery without
47//! exchanging long-lived identifiers. Codes are single-use and expire automatically.
48//!
49//! ### Phase 3: Messaging
50//!
51//! Once authenticated, clients can send messages to other clients by their identity fingerprint.
52//! The proxy validates the source identity and routes messages to the destination. The proxy
53//! cannot decrypt message contents — clients should implement end-to-end encryption separately.
54//!
55//! # Running as a Binary
56//!
57//! ```bash
58//! cargo run --bin ap-proxy
59//! ```
60//!
61//! # Embedding in Your Application
62//!
63//! ```no_run
64//! use ap_proxy::server::ProxyServer;
65//! use std::net::SocketAddr;
66//!
67//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
68//! let addr: SocketAddr = "127.0.0.1:8080".parse()?;
69//! let server = ProxyServer::new(addr);
70//! server.run().await?;
71//! # Ok(())
72//! # }
73//! ```
74
75pub(crate) mod connection;
76pub mod server;