Software Architecture

Backend Java WebSocket Gateway
Frontend JavaScript ES6+
Protocol IRC + IRCv3 Extensions
Extension Model Independent templates and optional plugins
Communication WebSocket (RFC 6455)

APIs & Protocols

This application implements and integrates various APIs and protocols:

  • IRC Protocol (RFC 1459, RFC 2812)
    Standard Internet Relay Chat protocol for messaging and channel management
  • IRCv3 Extensions
    • capability-negotiation: CAP LS 302 with LS, ACK, NAK, NEW, and DEL handling
    • message-tags: Preserves and forwards IRCv3 metadata to the web client
    • account-notify, away-notify, batch, cap-notify, chghost, extended-join
    • invite-notify, labeled-response, multi-prefix, server-time, userhost-in-names
    • SASL authentication via PLAIN, SCRAM-SHA-256, and SCRAM-SHA-512
  • SASL Authentication
    Server-configured authentication for IRC login with support for PLAIN, SCRAM-SHA-256, and SCRAM-SHA-512 depending on server capabilities
  • WebSocket API (RFC 6455)
    Full-duplex communication protocol for real-time bidirectional data transfer
  • WEBIRC Protocol
    Transparent client IP forwarding for IRC servers with HMAC authentication
  • Plugin API
    Optional frontend extensions can register independently from templates and target login, chat, or about pages
  • CTCP (Client-to-Client Protocol)
    Extended IRC commands: VERSION, PING, ACTION, TIME, CLIENTINFO

External APIs & Services

  • Cloudflare Turnstile API
    Privacy-first CAPTCHA alternative for bot protection
  • Google reCAPTCHA API (v2/v3/Enterprise)
    Advanced bot detection and abuse prevention service
  • Font Awesome Icons API
    Vector icon library via CDN (v6.5.1)

Libraries & Dependencies

Jakarta WebSocket API Jakarta Servlet API jQuery 3.x Bootstrap 5 JSP/JSTL HTML5 APIs CSS3 Variables Plugin Loader Template System

Backend: Java servlet container (Apache Tomcat, Jakarta EE compatible)
Frontend: Vanilla JavaScript ES6+, jQuery for DOM manipulation
Styling: Custom CSS with Bootstrap components

SASL & IRCv3 Details

  • SASL PLAIN - Fast baseline authentication using the IRC server's standard username and password flow
  • SCRAM-SHA-256 - Recommended salted challenge-response authentication with broad modern IRC server support
  • SCRAM-SHA-512 - Stronger challenge-response variant for servers that support the higher hash strength
  • Tagged IRCv3 events - Message tags, server-time, labeled-response, and batch support improve context and message ordering
  • Presence and identity updates - account-notify, away-notify, chghost, extended-join, and userhost-in-names reduce stale user state
  • Dynamic capability updates - cap-notify and capability negotiation allow runtime feature changes without reconnecting

Security Features

  • SASL Authentication - Secure account login before joining channels with server-side mechanism selection
  • SSL/TLS Support - Encrypted connection to IRC servers
  • CAPTCHA Integration - Cloudflare Turnstile, Google reCAPTCHA v2/v3/Enterprise
  • HMAC Validation - Secure client authentication
  • XSS Protection - HTML entity escaping with IRC control code preservation
  • IP Forwarding Security - Trusted proxy IP validation

Client Features

  • Modern web-based interface - no installation required
  • Real-time communication via persistent WebSocket connection
  • Full IRC formatting support (colors, bold, italic, underline, strikethrough, monospace)
  • Keyboard shortcuts for formatting (Ctrl+B, Ctrl+I, Ctrl+U, etc.)
  • Multiple channel support with tab-based navigation
  • Private messaging (query windows)
  • Emoji picker with search and categories
  • Typing indicators for active users (IRCv3 TAGMSG)
  • Modern IRCv3 capabilities including server-time, labeled-response, invite-notify, and extended-join
  • User list with status symbols (@, +, etc.)
  • Topic display and editing
  • Auto-reconnect on connection loss
  • Responsive design for mobile and desktop
  • Theme switching via the template system
  • Optional page-aware plugins for login, chat, and about views

Technology Stack

Backend Framework Jakarta EE / Java Servlets
Frontend Language JavaScript ES6+ / ECMAScript 2015+
Data Format JSON for WebSocket messages
Web Standards HTML5, CSS3, WebSocket API

License & Copyright

MIT License

Copyright © 2024-2026 Andreas Pschorn

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

Source code available at: github.com/WarPigs1602/jwebirc

Third-Party Acknowledgments

Getting Started

To connect to the IRC network:

  1. Enter your desired nickname on the login page
  2. Optionally specify channels to join (comma-separated)
  3. Complete any required CAPTCHA verification
  4. Click "Connect" to join the network

Once connected, you can use standard IRC commands like /join, /msg, /nick, and more.