username/bouncer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite all documentation for stealth connect and current state

Browse Source 
Update README, PROJECT, ROADMAP, TASKS, TODO, USAGE, CHEATSHEET,
INSTALL, and DEBUG to reflect stealth connect, probation window,
markov nick generation, local DNS resolution, and multi-IP failover.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
user
2026-02-19 18:31:20 +01:00
parent 845496f1b3
commit a58848395c
9 changed files with 402 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
PROJECT.md
View File

@@ -2,36 +2,55 @@
## Purpose
IRC bouncer that maintains persistent connections to IRC servers through a SOCKS5 proxy, allowing IRC clients to connect/disconnect while keeping the session alive and replaying missed messages.
IRC bouncer that maintains persistent connections to IRC servers through a
SOCKS5 proxy, allowing IRC clients to connect/disconnect while keeping the
session alive and replaying missed messages.
## Architecture
```
IRC Client(s) --> [bouncer:6667] --> Router --> [SOCKS5:1080] --> IRC Server(s)
|
Backlog
(SQLite)
|
Backlog
(SQLite)
```
### Connection State Machine
```
DISCONNECTED -> CONNECTING -> REGISTERING -> PROBATION (15s) -> READY
| | |
'--------------+--------------'
(failure = backoff + retry)
```
- **CONNECTING**: SOCKS5 + optional TLS handshake
- **REGISTERING**: Random nick/user/realname sent to server
- **PROBATION**: 15s window to detect K-lines before exposing real identity
- **READY**: Configured nick set, channels joined, clients served
### Components
| Module | Responsibility |
|--------|---------------|
| `irc.py` | IRC protocol parser/formatter (RFC 2812 subset) |
| `config.py` | TOML configuration loading and validation |
| `proxy.py` | SOCKS5 async connection wrapper |
| `network.py` | Persistent IRC server connection per network |
| `proxy.py` | SOCKS5 async connector with local DNS + multi-IP failover |
| `network.py` | Server connection state machine, stealth registration |
| `server.py` | TCP listener accepting IRC client connections |
| `client.py` | Per-client session and IRC handshake |
| `client.py` | Per-client session, PASS/NICK/USER handshake |
| `router.py` | Message routing between clients and networks |
| `backlog.py` | SQLite message storage and replay |
### Key Decisions
- **asyncio**: Single-threaded async for all I/O
- **python-socks**: Async SOCKS5 proxy support
- **aiosqlite**: Non-blocking SQLite for backlog
- **No IRC library**: Manual protocol handling (IRC is simple line-based)
- **asyncio**: single-threaded async for all I/O
- **python-socks**: async SOCKS5 proxy support
- **aiosqlite**: non-blocking SQLite for backlog
- **No IRC library**: manual protocol handling (IRC is line-based)
- **Markov nicks**: English bigram frequencies for pronounceable random nicks
- **Local DNS**: resolve before SOCKS5 to handle proxies without DNS support
- **Multi-IP**: try all resolved addresses, skip unreachable exit IPs
## Dependencies
@@ -43,4 +62,4 @@ IRC Client(s) --> [bouncer:6667] --> Router --> [SOCKS5:1080] --> IRC Server(s)
## Requirements
- Python 3.10+
- SOCKS5 proxy running on 127.0.0.1:1080
- SOCKS5 proxy on 127.0.0.1:1080