IRCv3
xBNC negotiates with each server the capabilities it offers and xBNC wants, and offers each client its own. Each client only gets what it asked for: a classic client receives the usual messages (for example, the short JOIN and only the highest rank in the user list).
With the servers
| Capability | What for |
|---|---|
server-time | Real time of each message. |
message-tags | Tags on messages. |
multi-prefix | Every rank of a user (@+), not only the highest. |
extended-join | Joins carry the account and the real name. |
away-notify | Notices when someone goes away or comes back. |
account-notify | Notices when someone identifies or stops being identified. |
account-tag | Each message says the account of whoever sent it. |
chghost | Changes of user or host without leaving and joining. |
userhost-in-names | The user list with nick!user@host. |
invite-notify | Invitations of other people to your channels. |
setname | Real name changes. |
cap-notify | The server adds or removes capabilities on the fly. |
sasl | SASL identification (PLAIN and EXTERNAL towards the server; PLAIN from the clients). |
With the clients
| Capability | What for |
|---|---|
server-time | Real time of each message. |
message-tags | Tags on messages. |
echo-message | Your own messages come back confirmed by the server. |
batch | Groups of messages (history, playback). |
sasl | SASL identification (PLAIN and EXTERNAL towards the server; PLAIN from the clients). |
draft/chathistory | The client asks for the history it needs (CHATHISTORY). |
draft/event-playback | The history includes joins, parts, kicks and nick changes as real events. |
draft/read-marker | Read markers shared between devices. |
soju.im/bouncer-networks | All your networks in a single connection. |
soju.im/bouncer-networks-notify | Notices of changes in your networks. |
extended-join | Joins carry the account and the real name. |
away-notify | Notices when someone goes away or comes back. |
account-notify | Notices when someone identifies or stops being identified. |
account-tag | Each message says the account of whoever sent it. |
chghost | Changes of user or host without leaving and joining. |
multi-prefix | Every rank of a user (@+), not only the highest. |
userhost-in-names | The user list with nick!user@host. |
invite-notify | Invitations of other people to your channels. |
setname | Real name changes. |
cap-notify | The server adds or removes capabilities on the fly. |
With CAP LS 302, sasl=PLAIN is announced. If the server does not support a capability a client asks for, xBNC still offers it when it can build it itself (for example, the extended JOIN with the data it knows). The test report records, per network, what the server offers (caps_offered), what xBNC turned on (caps_acked) and what each client asked for.
Test report
In Your account → Test report → Download report (or GET /api/v1/diagnostics) you download a JSON file with what is needed to diagnose a problem with a network, without passwords, messages, other people's nicks or the IPs of your devices.
| Field | Contents |
|---|---|
report, format | xbnc-diagnostics, format version 1. |
version, brand | xBNC version and “xBNC v1.0.0 - https://xbnc.org”. |
os, arch, database | System, architecture and database (sqlite or postgresql). |
started_at, generated_at | When xBNC started and when the report was generated. |
timezone, language | Your time zone and language. |
counters | Server counters (traffic, messages, reconnections, logins). |
networks[] | Per network: name, host, port, tls, enabled, whether it has SASL or a server password, saved_channels, active modules and plugins, and live. |
networks[].live | state, server, network_name, connected_since, last_error, caps_offered, caps_acked, isupport, services_logged_in, host_hidden, channels_joined and clients (device and capabilities of each one). |
Architecture
xBNC is a single program (xbncd) with the panel built in. The code is split into crates/xbnc-proto (IRC protocol without I/O: parser and serialiser with IRCv3 tags, prefixes, casemapping, ISUPPORT and CTCP) and crates/xbncd (service, CLI, API and panel), plus the plugin SDKs in sdk/, the panel (React and TypeScript) in web/ and the translations in locales/.
How it works inside
- Each network of each user is an independent task that exclusively owns its connection to the server, the state of the network and the list of clients. Nobody else touches that state: there are no locks on the path of the messages.
- Each client is a reading task and a writing task, with a bounded queue. If a client does not read, it is disconnected instead of piling up memory; when it comes back it gets what was pending.
- The panel, the API and the command line never touch the IRC connections: they write to the database and send orders to the network tasks (state, control, join, part, reload, disconnect a client, alert, broadcast).
- Every database access goes through a separate thread pool. The messages of every network go through a single writer thread that stores everything waiting (up to 512) in one transaction, keeping each network's order.
- Modules are code of the program itself, called at specific points (server line, client command, timer, connection, client joining or leaving). Plugins receive their events from the network task and run in the blocking thread pool.
- When a message arrives: it is parsed, the state is updated (nick, channels, members, modes, topic), it is stored with the server's time and an identifier, and it is sent to each client adapted to its capabilities.
- Texts are looked up in the loaded languages (built in, plus the files of
locales_dir) by key, with English as the fallback.
Modules of the code
| Module (crates/xbncd/src) | What it does |
|---|---|
main.rs | The xbncd command: running the service and the command line (users, networks, backups, import, languages, releases, updates). |
config | Reading and validating xbnc.toml. |
db, sql | Storage: versioned migrations, users, networks, channels, messages, cursors, audit log and backups; sql gives SQLite (rusqlite) and PostgreSQL the same interface. |
crypto | Argon2id, XChaCha20-Poly1305 encryption of the stored credentials and a Secret type that is never printed. |
auth | The login format, password checks, the brute-force limiter and the masking of lines in the logs. |
util | IRC line codec (length limit, lossy UTF-8, protection against CR/LF injection) and time helpers. |
network/ | The task of each network of each user: connection to the IRC server, state, history and attached clients. mods.rs and extra.rs hold the behaviour of the modules, status.rs and status_more.rs the *status, *notes and *watch commands, plugins.rs delivers events to plugins, dcc.rs decides which DCC offers go through xBNC and readmark.rs keeps the read markers. |
downstream, bouncer, events | Client connections: registration, CAP, SASL, PASS and relaying to the network task; soju.im/bouncer-networks; notices to clients when a network changes. |
modules | Catalogue of the modules, schema and validation of their settings and the typed configuration per network. |
perform | Turns client-style commands (/msg, /mode…) into IRC, for the commands on connect, aliases and scheduled tasks. |
logs | Log files, written in a separate thread. |
certs | Client certificates (generation, validation and fingerprints) and trusted server certificates. |
fish | FiSH encryption: Blowfish ECB and CBC and the DH1080 key exchange. |
i18n | Languages: the built-in English and Spanish and the files of locales_dir. |
netinfo | Local network addresses and the address shown for 0.0.0.0. |
server, ha | Shared context, the registry of network tasks, TLS listeners, maintenance and reloading; active/standby high availability with PostgreSQL. |
rbac, settings | The five roles and their permissions; history settings and limits editable live (database over xbnc.toml). |
totp, webauthn, sso | Two-step verification (RFC 6238), passkeys, OpenID Connect and LDAP. |
tz | Time zones with daylight saving time, with the database built in. |
metrics, alerts | Traffic and message counters, process memory and CPU; alert rules checked every 30 s, with notices in the panel, over IRC and by webhook. |
notify, push | Notifications by Telegram, Discord, e-mail, your own web address and Web Push. |
plugins, plugin_dev, catalog | WebAssembly plugins: manifest, validation, the Wasmi engine with limits, instances and actions; development mode; the built-in catalogue and the signed remote one. |
dcc | Reading and rewriting DCC offers and the one-use relays. |
http | A minimal HTTP/1.1 client (verified TLS, bounded size and time) for webhooks, notifications, plugins with web access and update checks. |
updates, release | New version notices, downloading and checking packages, the xbncd apply-update helper and Ed25519 signatures. |
backup | Backups from the panel and restoring them. |
import | Migration from another bouncer: reading its configuration, module data, plan, applying it in one transaction and importing logs. |
web/ | HTTP server (axum): the /api/v1 API, WebSocket, sessions, CSRF, headers and the panel files built into the binary. |
The panel (web/) is a React and TypeScript application built with Vite. web/dist is built into the binary, so xBNC stays a single file. The official plugins are built into the binary too (crates/xbncd/catalog/).
State machines
They are kept separate:
- Connection to the network:
Disconnected → Registering → Connected. While registering, xBNC negotiates the IRCv3 capabilities, SASL and the nick (with an alternative if it is taken). Times: 30 s to connect, 60 s to register, a PING after 90 s of silence and disconnection at 180 s. Reconnection with growing delays from 5 s to 5 minutes with ±20 % random variation, and at least 2 minutes after a throttling notice. If a server fails and the network has backup servers, the next one is tried after 1 second. - Client session: registration (
CAP,PASSor SASL,NICK,USER) with a time limit, and then a session attached to a network. - User and bouncer: which network tasks exist and how many clients each user has.
The path of a message
- The network task reads a line from the server and parses it.
- It updates the state (nick, channels, members, modes, topic).
- If it is a PRIVMSG, NOTICE or ACTION from someone (or an event, with the Events module), it stores it in
messageswith the server's time (server-time) or the local one, and gives it the identifiermsgid = x<id>. - It sends it to each attached client adapted to its capabilities (removing the tags the client did not ask for) and moves each client's cursor forward.
What a client sends goes to the server, is stored as outgoing and is relayed to the user's other clients (and to the sender itself if it asked for echo-message).
History without duplicates
- Each device (
@devicein the login,defaultif it is not given) has a cursor per network inclient_cursors: the identifier of the last message delivered. - When it connects, it gets the messages after its cursor (up to
playback_max, 1,000 by default). A new device gets the most recentnew_client_playback(100 by default). - Cursors are saved when the device disconnects and every 5 seconds; they never go back.
- Clients with
draft/chathistoryget no automatic playback: they ask for what they need withCHATHISTORY. Messages already read on another device (draft/read-marker) are not played back again.
Database schema
| Table | Contents | Since migration |
|---|---|---|
users | User, Argon2id hash, role, limits and quotas, encrypted TOTP secret, language, time zone, bind host, last login and last connection. | 1 (2, 4, 8, 9, 10) |
networks | Server, port, TLS, nick, SASL, commands on connect, client certificate, backup servers and trusted certificates; passwords and keys encrypted. | 1 (3, 4, 10) |
channels | Saved channels per network, with an encrypted key, retention, disabled and position. | 1 (8, 10) |
messages | History: network, conversation, time, sender, command, text, outgoing and mention. | 1 (8) |
client_cursors | Last message delivered per network and device. | 1 |
audit_log | Administrative actions. | 1 |
web_sessions | Panel sessions (token hash, CSRF, IP, browser, expiry). | 2 |
settings | Settings changed from the panel. | 2 |
login_events | Login attempts over IRC and in the panel (10,000 at most). | 2 |
module_config | Modules per network: enabled and validated JSON settings. | 4 |
notes | Each user's notes. | 4 |
messages_fts | Full-text index of messages.text, kept in sync by triggers (SQLite; PostgreSQL uses its own text search). | 5 |
api_tokens | API tokens: SHA-256 hash, prefix, scope, expiry, last use and IP. | 6 |
plugins | Installed plugins: manifest, SHA-256, size, enabled on the server, approved web domains and the module itself. | 7 (8) |
plugin_config | Plugins per network: enabled, settings and saved state. | 7 |
plugin_kv | Each plugin's key-value store per network. | 8 |
notify_settings | Notification settings of each user. | 8 |
push_subscriptions | Web Push subscriptions of each user's browsers. | 8 |
read_markers | Last message read in each conversation. | 8 |
passkeys | Passkeys: credential, public key, counter, name and last use. | 8 |
user_identities | Outside identities (OpenID Connect, LDAP) linked to local users. | 8 |
PostgreSQL has the same schema; it is supported from version 8 of the schema (PG_MIGRATIONS), and every new migration is added to both lists. Channel events (JOIN, PART…) are stored in messages with their command. Passwords imported from another bouncer with SHA-256 are kept as legacy-sha256$<hash>$<salt> until the first correct login, when they are replaced by Argon2id. Migrations are applied at start inside a transaction, and a binary refuses to open a newer schema than it knows.
Threat model
What xBNC protects, from whom and with which measure at each point. It is the guide for the external audit and for reviewing each change.
What is protected
| Asset | Why it matters |
|---|---|
| Passwords of the xBNC accounts | They give access to the networks, the history and, for administrators, the whole server. |
| Network credentials (SASL, server password, channel keys, commands on connect, services passwords, FiSH keys, certificates) | They allow impersonating the user on the networks. |
| History and logs | Private conversations and channels: personal information. |
| Panel sessions and API tokens | As good as the password while valid. |
| The secret key (secret.key) | Decrypts every stored credential. |
| The availability of the service | If it goes down, users lose messages and presence. |
| The reputation of the server's IP | Every connection leaves from it. |
Who may attack
| Actor | What they control | What they try |
|---|---|---|
| Anyone on the internet | Connections to the IRC, panel and DCC ports | Guess passwords, exhaust resources, exploit the parser. |
| Someone on an IRC network | Messages, CTCP, DCC, channel names and nicks | Inject commands, make xBNC connect to internal networks, flood the history. |
| A malicious IRC server | Everything coming through a network's connection | The above, plus malformed answers, huge lines and disconnection loops. |
| An xBNC user | Their account, networks, modules and plugins | Read other people's data, escalate to administrator, abuse the server. |
| An administrator | Other people's users and networks | Escalate to superadministrator, change global settings. |
| The author of a plugin | The code a superadministrator installs | Escape the sandbox, read data, act without permission. |
| The author of a language file | A file an administrator copies to locales_dir | Inject IRC commands or HTML through the texts (refused: they are validated and treated as plain text). |
| A malicious website | The browser of a signed-in user | CSRF, session theft, WebSocket hijacking. |
| Whoever gets the backups | The .tar.gz files | Credentials and conversations. |
Out of scope: someone who is already root on the machine, the server provider and failures of the operating system or of the IRC networks.
IRC client connections (6697/6667)
| Threat | Measure |
|---|---|
| Password brute force | Per-IP blocking shared with the panel and tokens; Argon2id; the same cost for users that do not exist. |
| Exhausting connections or memory | Global connection limit, 16 unauthenticated per IP, clients per user, registration time and bounded queues. |
| Huge or binary lines | 8703-byte limit per line and lossy UTF-8. |
| Command injection with CR/LF | Any CR or LF cuts the line; texts of modules, plugins and language files are validated without control characters. |
| Plain text on the internet | Ports without TLS only accept the local network or require insecure = true. |
| Credentials in the logs | Masking of PASS, AUTHENTICATE, OPER and messages to services at every level. |
Connections to the IRC networks
| Threat | Measure |
|---|---|
| Server impersonation | TLS verified with the system store, with no option to turn it off; a trusted certificate only accepts its exact SHA-256 fingerprint. |
| Malformed answers | Own parser without unsafe, with tests and fuzzing. |
| History flooding | Configurable retention, optional events, bounded queues; the log module drops lines if the disk cannot keep up; hide flooding channels. |
| Disconnection loops | Growing delays with random variation and a minimum wait after throttling notices. |
| Being thrown out for flooding | Rate limiting on the output. |
| Theft of the services password | On networks without NickServ it is never sent in automatic mode. |
DCC
| Threat | Measure |
|---|---|
| Using the bouncer to reach internal networks (SSRF) | Offers to internal addresses or ports below 1024 refused unless the user allows them. |
| Making xBNC connect to a third party | For your own sends it only connects back to your device's IP. |
| Ports open indefinitely | One port per offer, a single connection, a timeout, closing when idle and a size limit. |
| Hijacking the transfer | When receiving, the port only accepts the client's IP. |
Web panel and API
| Threat | Measure |
|---|---|
| CSRF | CSRF token in a header, SameSite=Strict cookie and Origin check. |
| XSS | React escapes all content; CSP without external or inline scripts; IRC texts are never interpreted as HTML; translations are plain text. |
| Session theft | HttpOnly and Secure cookie; only the token's SHA-256 in the database; sliding expiry; changing the password closes the other sessions. |
| WebSocket hijacking | Origin check, the session revalidated every 30 s and no API tokens. |
| Privilege escalation | Permissions checked on the server in every route; nobody changes their own role; there is always a superadministrator. |
| Seeing other users' data | Other people's networks answer 404, not 403. |
| API abuse and slowloris | 20 requests/s per IP, bounded bodies, 64 connections per IP and 4,096 in total, closing after 2 minutes without traffic, 10 s for the TLS handshake. |
| Leaked tokens | Scope, expiry, last use and IP visible, immediate revocation, only their SHA-256 stored. |
| Stolen first access | One-time code, only in the service log. |
| Webhook to internal sites | Only a superadministrator configures it; no redirects, no credentials in the URL, 10 s at most. |
Plugins
| Threat | Measure |
|---|---|
| Escaping the sandbox | Wasmi interpreter without JIT, module validated when loaded, no WASI nor imports other than xbnc's, advanced WebAssembly features turned off. |
| Blocking or crashing the server | Fuel per event, limited memory, execution that never grows the native stack, calls in separate threads, stopping after five failures. |
| Acting without permission | Declarative actions checked against the permissions; dangerous commands always forbidden; maximum messages per event; web access only to approved domains and with limits. |
| Reading other people's data | Each instance only receives the events of its network; state and store separated per network. |
| File changed after installation | Its SHA-256 is stored and it is not loaded if it does not match; files 0600. |
| Malicious plugin installed | Only a superadministrator installs, seeing permissions and fingerprint; recorded in the audit log; signed remote catalogue. |
Import from another bouncer
| Threat | Measure |
|---|---|
| File crafted to create a superadministrator | The import never grants that role. |
| Weak inherited passwords | Salted SHA-256 compared in constant time and replaced by Argon2id; formats that cannot be checked get a random password. |
| Abusive paths or sizes | File up to 4 MB, limited nesting, validated names; logs are only read from the folders given. |
| Leaks in the preview | The preview includes no secrets. |
Updates from the panel
| Threat | Measure |
|---|---|
| Fake package (compromised download server, DNS or network) | Ed25519 signature over the package name and its SHA-256; the public key is only in xbnc.toml, owned by root. |
| Going back to a version with known flaws | Equal or older versions than the installed one are refused. |
A compromised xbnc process trying to install something as root | The helper (xbnc-update.service) trusts nothing in the service's folder: it copies the package to /run (0700), checks the signature and the version on that copy, never follows symbolic links, validates the file name and uses each request only once. |
| Fake update request | Only superadministrators, from a panel session (not with API tokens) and with CSRF; recorded in the audit log. |
| Endless downloads or redirects to plain text | 200 MB and 10 minutes at most; https:// only, 5 redirects at most. |
Data at rest and backups
| Threat | Measure |
|---|---|
| Theft of the database | Network credentials encrypted with XChaCha20-Poly1305; the key outside the database, with 0600 permissions checked at start. |
| Theft of a backup | 0600 file; it includes the key, so it must be stored encrypted. |
| Access from other users of the system | Service run as the unprivileged xbnc user, 0700 folders and systemd hardening. |
Accepted risks
- The history is stored unencrypted in the database: encrypting it would prevent search and playback. It is protected by the system's permissions.
- IRC clients have no second factor: the bouncer password is their only protection (hence per-IP blocking and Argon2id).
- A superadministrator can install a plugin with permission to send messages on behalf of whoever turns it on: it is a decision of trust that the panel shows before installing.
- Every connection to the networks leaves from the server's IP.
- FiSH is old cryptography (Blowfish, without integrity); decrypted messages are stored in the history like the rest.
Review
Each version reviews these tables: a new feature that opens a surface not listed here is added to them. The tests behind each measure are in crates/xbncd/tests/ and in the unit tests of each module; fuzzing covers the IRC parser, DCC, the imported configuration file, search, and the manifests and execution of plugins (see Test environment).
Internal review of version 0.7. The whole code was reviewed with these tables as a guide (it does not replace the external audit):
- SQL queries: all with bound parameters; the parts built with
format!are only fixed column lists and clauses. - API authorisation: every route checks the session or token and the permission; network routes check the owner. Fixed:
PATCH /users/{id}answered 404 or 403 to accounts without permission depending on whether the user existed. - External processes: the only one is
dpkgorrpmin the update helper, with fixed arguments and the package already checked. - File paths: logs, plugins and updates build paths only from validated names; the update helper never follows symbolic links.
- Denial of service: added the limit of unauthenticated IRC connections per IP, the panel's connection limits and idle time, and the limit of simultaneous Argon2id calculations.
- Plugins: the interpreter moved to the loop execution mode after fuzzing found that the chained-call mode could exhaust the native stack in unoptimised builds.
unsafecode: only one call tomalloptat start (memory allocator setting).- Dependencies:
cargo-denyin CI (licences and security advisories).
Internal review of version 1.0. The new code of 1.0 was reviewed and three points were fixed before publishing: on networks without services the password is never sent to whoever uses the nick “NickServ”; the FiSH key exchange has a limit of requests and stored keys; decrypted text cannot break lines. Language files are validated (placeholders, tags, no control characters or line breaks) and a text that fails is shown in English.
Performance
Load test (cargo run --release --example loadtest -- --users 1000 --clients 1 --rate 2 --seconds 60): a simulated IRC server sends messages to every network at once (the worst case) and each client measures how long it takes to receive them, going through the history, modules and plugins. Machine: 2 vCPU Xeon at 2.1 GHz, 7 GB of RAM, network disk, default configuration (SQLite).
| Users and networks | Clients | Messages/s delivered | CPU (of one core) | Memory | Latency p50 / p95 / p99 | Every network back after an outage |
|---|---|---|---|---|---|---|
| 500 | 500 | 492 | 5 % | 52 MB | 21 / 43 / 46 ms | 6.2 s |
| 500 | 500 | 4,847 | 43 % | 56 MB | 46 / 64 / 72 ms | 6.2 s |
| 1,000 | 1,000 | 1,951 | 17 % | 88 MB | 50 / 80 / 95 ms | 6.2 s |
| 1,000 | 2,000 | 1,968 | 11 % | 114 MB | 44 / 66 / 78 ms | 6.2 s |
| 2,000 | 2,000 | 1,968 | 19 % | 153 MB | 75 / 141 / 155 ms | 6.3 s |
- No message was lost in any test.
- Latency grows with the size of the burst: with 2,000 networks receiving the same message at once, the last one is delivered about 150 ms after the first. With real traffic, spread over time, it is a few milliseconds.
- Memory: about 45 KB per connected network and about 30 KB more per client, not counting the history (on disk).
- Client logins (Argon2id) go one at a time per CPU: 2,000 clients signing in together take about 27 s on 2 cores, without a memory spike.
- Disk: about 150 bytes per stored message, including the search index.
Sizing: a small server (1–2 vCPU, 1 GB of RAM) serves hundreds of users with several networks and thousands of messages per second. With many users, check limits.max_connections, the service's LimitNOFILE (65,536 by default) and the history retention.
How it is measured
The test (crates/xbncd/examples/loadtest.rs) starts, in a single process:
- a simulated IRC server with a channel
#xbnc; - xBNC with N users, each one with its network connected to that server and joined to
#xbnc; - one or more IRC clients per user connected to xBNC.
The server sends --rate messages per second to the channel, to every network at the same time (the worst case: simultaneous bursts). Each message carries the time it was sent, and each client measures how long it takes to arrive: IRC server → xBNC (stored in the history, modules, plugins) → client. At the end the server cuts every connection and the test measures how long it takes for every network to come back.
Memory and CPU are those of the whole process, so they include the simulated server and the test clients (xBNC alone uses a little less). The build is --release with the default configuration (history in SQLite with WAL).
Problems found and fixed with this test
| Problem | Before | After |
|---|---|---|
| Memory after many simultaneous logins: glibc kept in each thread the 19 MB of every Argon2id calculation. | 1,680 MB with 500 clients | 55 MB (util::tune_allocator, a fixed mmap threshold) |
| Hundreds of Argon2id calculations at once (also useful against floods of login attempts). | No limit | One per CPU (crypto::with_hash_slot) |
| One SQLite transaction per stored message. | p50 70 ms and 13 % CPU with 500 networks | p50 21 ms and 5 % CPU: a single writer thread stores everything waiting in one transaction (Db::insert_message) |
Still to do
- Repeat the test on dedicated hardware and with several networks per user.
- Measure with real IRC servers far away (the test uses a local one, without network latency).
To repeat it: cargo run --release --example loadtest -- --users 2000 --clients 1 --rate 1 --seconds 60. The options are --users, --clients (per user), --rate (messages per second to the channel) and --seconds.
Test environment
With Docker
testenv/ brings up xBNC with two different IRC servers (Ergo and InspIRCd) on an isolated network, all in plain text on purpose:
cd testenv
docker compose up -d --build
./setup.sh
# IRC: localhost:6667, password test/ergo@laptop:testpassword1
# Panel: http://localhost:8080 (user test, password testpassword1)
Do not publish those ports on a public interface.
Automatic tests
cargo test --workspace # every test
XBNC_TEST_POSTGRES=postgres://postgres@127.0.0.1/postgres cargo test --workspace # also with PostgreSQL
cargo clippy --workspace --all-targets -- -D warnings
cd web && npm run build && npm run i18n:check # panel and translations
xbncd locales check locales/*.json # language files
python3 ../xbnc-wiki/build.py --app . # the wiki (a separate project)
They cover the protocol, the units, the API against a real bouncer, IRC end to end, every *status command, the switch to a backup server, the trusted certificate with a real TLS handshake, a language added as a file, modules and plugins against a simulated IRC server, the panel, SSO and real IRC servers in CI (Ergo, InspIRCd, UnrealIRCd, Solanum and miniircd). Fuzzing (fuzz/) runs every week. testenv/ui/language_check.py checks in a real browser that every way of changing the language works.
Tests on real networks
The test plan per network, module and plugin is in testenv/real/PLAN.md. See Testing the beta.
The test sets
| Set | Where | What it covers |
|---|---|---|
| Protocol (16) | crates/xbnc-proto | Parser and serialiser, tag escaping, prefixes, casemapping, ISUPPORT, CTCP. |
| Units of the service (159) | crates/xbncd/src | Configuration, Argon2id, encryption and key permissions, database and migrations (SQLite and PostgreSQL, and upgrading an old schema), history and search, cursors, sessions, backups, login, brute-force limiter, log masking, codec, CAP, roles, settings, TOTP (RFC 6238 vectors), metrics, tokens, cookies, origin, IP behind a proxy, OpenAPI coverage, HTTP→HTTPS redirect, module catalogue and validation, globs, mentions, aliases, logs, client and trusted certificates (with a real TLS handshake), FiSH, time zones, languages (every key used exists, Spanish complete, files checked and loaded), plugins (permissions, limits, fuzzing regressions), DCC, HTTP client, release signatures, the update helper and connection limits, which names a TLS certificate is valid for, and the panel address shown after installing, and the texts of the installer (complete in English and Spanish, checked in any language file, and every key the scripts use exists). |
| API (13) | tests/api.rs | First run with a one-time code, login, sessions, CSRF, origin, headers, brute force, networks, channels, history, export, isolation between users, roles, live settings, 2FA, panel, OpenAPI, modules, certificates, notes, language, tokens, metrics, alerts, import and plugins. |
| End to end (16) | tests/e2e.rs | The whole bouncer against a simulated IRC server (scenarios below). |
| Modules (18 + 12) | tests/modules.rs, tests/modules_v1.rs | Each module against the simulated server: away and summary, keep nick, replies to the device that asked, events, CTCP, sticky channels, aliases, auto op, rejoin after a kick, watch words, MOTD and logs; and the modules of 1.0: IRCv3 extras only for clients that asked, services login (X with the hidden host and Login on Connect), invite, ignore and remove colours, FiSH in both directions and DH1080, detached channels, flooding channels, autocycle, Latin-1 and scheduled tasks. |
*status commands (12) | tests/status_commands.rs | Grouped help, other bouncers' command names, backup servers (added, jumped to, promoted and automatic switch), trusted fingerprints, bind hosts, disabled and ordered channels, buffers, MOTD and broadcast, permissions, networks from IRC and a language added as a file. |
| Plugins (2 + 5 + 7) | tests/plugins.rs, tests/plugins_v1.rs, tests/official_plugins.rs | Plugins answering on the network and to the user, and each official plugin: seen, trivia, greet, factoids, karma, quotes, games, badwords, web access only to approved sites, reminders, tell, polls, channel stats, anti-flood, dice and autoresponder. |
| Shared port (2) | tests/shared_port.rs | The panel and IRC on one TLS port: a browser gets the panel, an IRC client the bouncer, plain http:// is sent to https:// and an IRC client without SSL is told to turn it on. |
| Panel (3) | tests/panel.rs | Chat in the panel, mentions and channel history, plugin development mode and the one-click catalogue. |
| SSO (3) | tests/sso.rs | Passkeys, OpenID Connect and LDAP. |
| Command line (2) | tests/cli.rs | xbncd info run as a real process: the panel at the address given at installation, and no error when its output goes into head. |
| PostgreSQL (1) | tests/postgres.rs | Moving an SQLite database to PostgreSQL (with XBNC_TEST_POSTGRES). |
| Real IRC server (1) | tests/real_ircd.rs | A real xBNC against a real IRC server (see below). |
| Rust SDK (3) | sdk/rust | Events and answers of the SDK. |
End-to-end scenarios
- On connecting, the client gets the welcome, the network's ISUPPORT, its channels, the topic and the list of users.
- A message received with the client closed is played back on reconnecting, with its time; your own messages are not played back to the same device and a third connection gets no duplicates.
- Two devices connected at once stay in sync; a new device gets the recent history.
CHATHISTORYLATEST, AFTER and errors,batch, the server'sserver-timekept,msgidandecho-message; capabilities that are not implemented are not announced.- Login with SASL PLAIN.
- A wrong password is refused and the IP is blocked after three failures, even with the right password.
- Unknown network: the error lists the networks available.
- Server outage: the bouncer says so, reconnects with growing delays and joins the channels again.
*status, andPARTandJOINwith a key saved (the key is stored encrypted).- Commands on connect are sent before joining channels.
- Read markers are shared between devices.
soju.im/bouncer-networksfor modern clients.- With
/mode $nick +xin the commands on connect, no JOIN reaches the server (saved channels, those in the commands, a client's own) until the server hides the host (396). /msg *status joinnowjoins the held channels.- A wrong password gets the right format, and the address is blocked after the failures with the minutes left and where to unblock it.
- The example password (“YOUR_PASSWORD”) is explained and does not block the address.
Real IRC servers
tests/real_ircd.rs connects a real xBNC to a real IRC server (variable XBNC_IRCD=host:port) and checks the list of users, messages in both directions, sync between two devices, playback without duplicates with the client closed, a nick change, leaving a channel and staying connected to the network:
XBNC_IRCD=127.0.0.1:6667 cargo test -p xbncd --test real_ircd -- --ignored
CI runs it against Ergo, InspIRCd, UnrealIRCd, Solanum and miniircd (testenv/ci/start-ircd.sh builds or installs each one with a minimal configuration).
Fuzzing
fuzz/ has six libFuzzer targets:
| Target | What it receives |
|---|---|
irc_message | Arbitrary IRC lines: parser, serialiser and the round trip. |
dcc | DCC offers. |
import_config | Configuration files of another bouncer. |
search_query | Search queries against the full-text index. |
plugin_manifest | WebAssembly files with arbitrary manifests. |
plugin_runtime | Arbitrary WebAssembly modules loaded and run as plugins. |
cargo install cargo-fuzz # needs Rust nightly
cd fuzz && mkdir -p corpus/irc_message && cp seeds/irc_message/* corpus/irc_message/
cargo +nightly fuzz run irc_message corpus/irc_message -- -max_total_time=600
CI (.github/workflows/fuzz.yml) runs each target for 20 minutes every week, keeps the corpus between runs and first checks that the failures already found (fuzz/regressions/) are still fixed. The failures found so far, all fixed and with their test:
- The parser accepted CR, LF or NUL inside a line.
- The parser accepted commands that are not alphanumeric (
@ @). - DCC offers accepted control characters.
- Embedding a manifest overflowed with sections of impossible size.
- A plugin with a long loop exhausted the process's native stack in builds where the compiler does not turn the interpreter's calls into jumps: the interpreter now uses the loop execution mode, which never grows the stack.
Load tests
cargo run --release --example loadtest -- --users 2000 --rate 1 --seconds 60. Results and method in Performance.
The panel in a browser
The panel has been gone through in Chrome with Playwright against a real bouncer with a real IRC client connected: first run, network wizard, channels, history and search, users, security, settings, 2FA, modules, plugins (installation with the permissions preview, per-network settings), import from another bouncer, alerts, updates, backups, chat, the sign-in page, the light and dark themes and the phone, in English and in Spanish, with no errors in the console apart from the expected 401 before signing in. testenv/ui/language_check.py URL USER PASSWORD repeats in a real browser every way of changing the language (sign-in page, Your account, Settings, a language added as a file) and checks that no text is left in another language.
Manual checklist
Use it with testenv/ or with a real installation:
- The service starts and stops cleanly (
systemctl startandstop xbnc; the log shows xBNC stopped). - An administrator and several users are created with the command line.
- A user with two networks is connected to both at once.
- A classic client (HexChat, WeeChat, irssi or mIRC) connects with
user/network@device:password. - With the client closed, someone else writes in the channel and in private; on reconnecting those messages arrive exactly once.
- Two clients of the same user see what the other one writes.
docker compose restart ergo(or cutting the network): xBNC says so, reconnects and joins the channels again./msg *status statusshows the right state.- Five wrong passwords block the IP for 15 minutes.
scripts/backup.shandscripts/restore.shbring back users, networks and history.journalctl -u xbnccontains no passwords after logging in, SASL and/msg NickServ IDENTIFY.- From the panel: create a user, add a network with the wizard, join a channel and see the history.
- An ordinary user does not see Users, Security or Settings, nor other people's networks.
- Turn on two-step verification and sign in with the code.
- Change the retention in Settings and check in System that it applies without restarting.
- Memory use with 1 user and 2 networks (
systemctl status xbnc): note it down to compare in future versions.