# 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)
```bash
chmod +x install.sh start.sh
./install.sh
```

### Manual Install
```bash
# 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
```bash
./start.sh
```
or
```bash
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

```javascript
{
  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](https://www.unrealircd.org/) and [Anope IRC Services](https://www.anope.org/), reimplemented from scratch in Node.js as a modern, unified IRC server.