Files

user a58848395c docs: rewrite all documentation for stealth connect and current state

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>

2026-02-19 18:31:20 +01:00

2.2 KiB

Raw Blame History

Project: bouncer

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.

Architecture

IRC Client(s) --> [bouncer:6667] --> Router --> [SOCKS5:1080] --> IRC Server(s)
                                       |
                                    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 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, 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 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

Package	Version	Purpose
python-socks[asyncio]	>=2.4	SOCKS5 proxy
aiosqlite	>=0.19	Async SQLite

Requirements

Python 3.10+
SOCKS5 proxy on 127.0.0.1:1080

2.2 KiB Raw Blame History