KitsuneIRC

Modern IRC server written in Node.js combining the full functionality of UnrealIRCd and Anope IRC Services into a single unified system, with a web-based administration panel.

Features

IRC Server (UnrealIRCd equivalent)

RFC 2812 compliant IRC protocol
IRCv3 extensions: multi-prefix, away-notify, account-notify, extended-join, account-tag, server-time, chghost, setname, cap-notify, message-tags, batch, echo-message, sasl, userhost-in-names
TLS/SSL support (port 6697) with self-signed or custom certificates
Channel modes: n, t, m, i, s, p, k, l, r, R, S, c, C, D, N, T, Q, O, z, f, G, M
Channel prefix modes: ~ (owner/q), & (protect/a), @ (op/o), % (halfop/h), + (voice/v)
User modes: i, o, w, x, r, s, D, G, B, R, T, W, Z, S, H, I, p, q
Ban lists: bans (b), exceptions (e), invite exceptions (I)
IP cloaking (HMAC-SHA256 based)
K-lines, G-lines, Z-lines (server bans)
Flood protection and connection throttling
DNSBL support (configurable)
Oper system with granular flags
SASL PLAIN authentication
Server password support
MOTD (Message of the Day)
All standard IRC commands: JOIN, PART, PRIVMSG, NOTICE, MODE, TOPIC, KICK, INVITE, NAMES, LIST, WHO, WHOIS, WHOWAS, ISON, USERHOST, AWAY, MOTD, LUSERS, VERSION, TIME, INFO, ADMIN, OPER, KILL, WALLOPS, KNOCK, SETNAME, CHGHOST, MAP, LINKS
Oper commands: SAJOIN, SAPART, SANICK, SAMODE, REHASH, RESTART, DIE

IRC Services (Anope equivalent)

NickServ - Nickname Registration

REGISTER, IDENTIFY/ID, LOGOUT, DROP
INFO, STATUS, LIST (oper)
SET: PASSWORD, EMAIL, ENFORCE, SECURE, PRIVATE, LANGUAGE, GREET, URL
GROUP / UNGROUP (nick grouping)
GHOST, RECOVER, RELEASE
CERT ADD/DEL/LIST (certificate fingerprint auth)
RESETPASS (oper)
Nick enforcement with configurable timeout
SASL integration
Account-notify capability support

ChanServ - Channel Registration

REGISTER, DROP, INFO, LIST (oper)
SET: KEEPTOPIC, TOPICLOCK, MLOCK, PEACE, PRIVATE, RESTRICTED, SECURE, SECUREOPS, SECUREFOUNDER, GUARD, FANTASY, DESCRIPTION, URL, EMAIL, ENTRYMSG, SUCCESSOR
ACCESS ADD/DEL/LIST (levels 0-5: VOP, HOP, AOP, SOP, Founder)
AKICK ADD/DEL/LIST
OP/DEOP, HALFOP/DEHALFOP, VOICE/DEVOICE, OWNER/DEOWNER, PROTECT/DEPROTECT
INVITE, UNBAN, KICK, BAN, TOPIC, MODE
CLEAR BANS/MODES/OPS/VOICES/USERS
ENTRYMSG, SUCCESSOR, TRANSFER, STATUS, SYNC, UP, DOWN
Fantasy commands: !op, !deop, !voice, !devoice, !kick, !ban, !topic, !mode, !invite, !unban, !info, !help

MemoServ - Memo System

SEND, LIST, READ (number/ALL/NEW)
DEL (number/ALL/READ)
CANCEL, CHECK, FORWARD
SENDALL (oper - send to all registered users)
Real-time notification on login

OperServ - Network Management

GLOBAL - Send global notices
STATS - Server statistics
KICK / KILL - Force disconnect users
KLINE / GLINE / AKILL / ZLINE - Ban management (ADD/DEL/LIST)
CLEARBANS - Clear all bans
CHANLIST / USERLIST - List channels/users
MODE - Force mode changes
DEFCON - Emergency restriction levels (1-5)
SET - Server runtime options
RELOAD - Reload configuration
SESSION - Session statistics
JUPE - Jupe servers/nicks
SQLINE / SNLINE - Nick/realname bans

BotServ - Channel Bots

BOTLIST - List available bots
ASSIGN / UNASSIGN - Assign bots to channels
INFO - Bot info for a channel
SAY / ACT - Make bots speak/act
CREATE / DELETE (oper) - Manage bot definitions
SET - Bot configuration

HostServ - Virtual Hosts

REQUEST - Request a vHost
ON / OFF - Activate/deactivate vHost
GROUP - Sync vHost to all grouped nicks
LIST / WAITING - List pending requests (oper)
APPROVE / ACTIVATE - Approve requests (oper)
REJECT - Reject requests (oper)
SET / SETALL - Set vHosts directly (oper)
DEL / DELALL - Remove vHosts (oper)

Web Administration Panel

Dashboard: Real-time server statistics, user counts, channel counts, uptime, DEFCON level
User Management: View online users, registered nicks, kill users, drop registrations
Channel Management: View active channels, registered channels, drop registrations
Ban Management: Add/remove K-lines, G-lines, Z-lines with duration support
vHost Management: Approve/reject vHost requests
Memo Viewer: Browse recent memos
Configuration Editor: JSON editor for full server config, MOTD editor
Admin Management: Manage web panel administrators
JWT Authentication with secure session handling
Modern dark-themed responsive UI

Requirements

Node.js 18.0 or higher
npm 8.0 or higher
Windows, Linux, or macOS

Installation

Quick Install (Windows)

install.bat

Quick Install (Linux/macOS)

chmod +x install.sh start.sh
./install.sh

Manual Install

# 1. Install dependencies
npm install

# 2. Run interactive setup
npm run setup

# 3. Generate TLS certificates
npm run generate-cert

# 4. Start the server
npm start

Starting the Server

Windows

start.bat

or

npm start

Linux/macOS

./start.sh

or

npm start

Configuration

Configuration is stored in config.js in the project root. It is generated during setup but can be edited manually.

Key Configuration Options

{
  server: {
    name: 'irc.kitsune.local',    // Server hostname
    network: 'KitsuneNet',         // Network name
    ports: [6667],                 // Plain IRC ports
    tlsPorts: [6697],              // TLS/SSL IRC ports
    host: '0.0.0.0',              // Bind address
    maxClients: 1024,              // Max concurrent connections
    pingTimeout: 120,              // Ping timeout (seconds)
    pingInterval: 30,              // Ping interval (seconds)
    password: null,                // Server-wide password (null = none)
  },
  
  tls: {
    cert: './certs/server.crt',    // TLS certificate path
    key: './certs/server.key',     // TLS private key path
  },

  opers: [
    {
      name: 'admin',               // Oper username
      password: 'password',        // Oper password (bcrypt hash or plain)
      host: '*@*',                 // Host mask restriction
      flags: 'oOaANrRDKGZCcdkbBnmMSqtUTHW',
    }
  ],

  services: {
    nickserv: { nick: 'NickServ', enabled: true },
    chanserv: { nick: 'ChanServ', enabled: true },
    memoserv: { nick: 'MemoServ', enabled: true },
    operserv: { nick: 'OperServ', enabled: true },
    botserv:  { nick: 'BotServ',  enabled: true },
    hostserv: { nick: 'HostServ', enabled: true },
  },

  security: {
    cloak: { enabled: true, key: 'random-key', prefix: 'kitsune' },
    flood: { maxPerInterval: 20, interval: 10 },
    throttle: { maxPerIP: 3, period: 60 },
    requireSASL: false,
  },

  webPanel: {
    enabled: true,
    port: 8080,
    host: '0.0.0.0',
    jwtSecret: 'auto-generated',
  },

  database: {
    path: './data/kitsune.db',
  },

  motd: [
    'Welcome to KitsuneNet!',
    'Powered by KitsuneIRC',
  ],
}

Connecting

IRC Client

Connect with any IRC client:

Plain: irc.kitsune.local:6667
TLS/SSL: irc.kitsune.local:6697 (accept self-signed cert)

Web Panel

Open in browser: http://localhost:8080

On first access, you'll be prompted to create an admin account.

Usage Guide

Registering a Nick

/msg NickServ REGISTER <password> <email>

Identifying

/msg NickServ IDENTIFY <password>

Or use SASL PLAIN in your client settings.

Registering a Channel

/msg ChanServ REGISTER <#channel>

Becoming an Operator

/oper <name> <password>

Sending a Memo

/msg MemoServ SEND <nick> <message>

Requesting a vHost

/msg HostServ REQUEST <your.custom.host>

Getting Help for Any Service

/msg NickServ HELP
/msg ChanServ HELP
/msg MemoServ HELP
/msg OperServ HELP
/msg BotServ HELP
/msg HostServ HELP

Database

KitsuneIRC uses SQLite (via better-sqlite3) with WAL mode for optimal performance.

Database tables:

accounts - User accounts and settings
nicknames - Registered nicknames
channels - Registered channels
channel_access - Channel access lists
channel_akick - Channel auto-kick lists
memos - User memos
server_bans - K/G/Z-lines
vhost_requests - vHost requests
bot_assignments - BotServ assignments
stats_log - Statistics log
web_admins - Web panel administrators

The database file is stored at data/kitsune.db by default.

Ports

Port	Protocol	Description
6667	TCP	Plain IRC
6697	TCP+TLS	Secure IRC
8080	HTTP	Web admin panel

All ports are configurable in config.js.

Security

TLS/SSL: Full TLS support for IRC connections
SASL: PLAIN mechanism for secure authentication
IP Cloaking: HMAC-SHA256 based hostname masking
Flood Protection: Rate limiting with configurable thresholds
Connection Throttling: Per-IP connection limits
Ban System: K-lines (local), G-lines (global), Z-lines (IP)
DEFCON Levels: Emergency restriction system (1-5)
bcrypt: Password hashing for oper and service passwords
JWT: Secure web panel authentication

Project Structure

KitsuneIRC/
├── src/
│   ├── index.js              # Entry point
│   ├── config/
│   │   └── ConfigManager.js  # Configuration management
│   ├── database/
│   │   └── Database.js       # SQLite database layer
│   ├── server/
│   │   ├── IRCServer.js      # Core IRC server
│   │   ├── Client.js         # Client connection handler
│   │   ├── Channel.js        # Channel management
│   │   ├── CommandHandler.js # IRC command processing
│   │   └── ModeHandler.js    # Mode processing
│   ├── services/
│   │   ├── ServiceManager.js # Service orchestration
│   │   ├── BaseService.js    # Base service class
│   │   ├── NickServ.js       # Nickname services
│   │   ├── ChanServ.js       # Channel services
│   │   ├── MemoServ.js       # Memo services
│   │   ├── OperServ.js       # Operator services
│   │   ├── BotServ.js        # Bot services
│   │   └── HostServ.js       # vHost services
│   ├── utils/
│   │   ├── IRCUtils.js       # IRC utilities & numerics
│   │   └── Logger.js         # Logging utility
│   └── web/
│       ├── WebPanel.js       # Express web server & API
│       └── public/
│           └── index.html    # Admin panel SPA
├── scripts/
│   ├── setup.js              # Interactive setup wizard
│   └── generate-cert.js      # TLS certificate generator
├── config.js                 # Server configuration
├── package.json
├── install.bat               # Windows installer
├── install.sh                # Linux/macOS installer
├── start.bat                 # Windows start script
├── start.sh                  # Linux/macOS start script
└── README.md

License

MIT

Credits

KitsuneIRC is inspired by UnrealIRCd and Anope IRC Services, reimplemented from scratch in Node.js as a modern, unified IRC server.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
certs		certs
client		client
data		data
plugins		plugins
scripts		scripts
src		src
.gitignore		.gitignore
README.md		README.md
checkbraces.js		checkbraces.js
config.js		config.js
install.bat		install.bat
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
start-dev.bat		start-dev.bat
start-dev.sh		start-dev.sh
start.bat		start.bat
start.sh		start.sh

Folders and files

Latest commit

History

Repository files navigation

KitsuneIRC

Features

IRC Server (UnrealIRCd equivalent)

IRC Services (Anope equivalent)

NickServ - Nickname Registration

ChanServ - Channel Registration

MemoServ - Memo System

OperServ - Network Management

BotServ - Channel Bots

HostServ - Virtual Hosts

Web Administration Panel

Requirements

Installation

Quick Install (Windows)

Quick Install (Linux/macOS)

Manual Install

Starting the Server

Windows

Linux/macOS

Configuration

Key Configuration Options

Connecting

IRC Client

Web Panel

Usage Guide

Registering a Nick

Identifying

Registering a Channel

Becoming an Operator

Sending a Memo

Requesting a vHost

Getting Help for Any Service

Database

Ports

Security

Project Structure

License

Credits

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages