# WEBIRC - Gateway Web-to-IRC

## 📋 CE ESTE WEBIRC?

**WebIRC** este un protocol care permite **gateway-urilor web-to-IRC** (clienți IRC în browser) să comunice **IP-ul real** al utilizatorilor către serverul IRC, în loc ca toți utilizatorii să apară cu IP-ul serverului web.

Este esențial pentru **integrarea IRC în pagini web** fără ca toți utilizatorii să fie văzuți ca provenind de pe același IP (care ar fi IP-ul serverului web).

---

## 🎯 SCOP

### **Problema FĂRĂ WebIRC:**

Când ai un **client IRC web** (ex: Kiwi IRC, TheLounge, etc.) pe site-ul tău:

```
User1 (România) → WebServer (10.0.0.50) → IRCd
User2 (SUA) → WebServer (10.0.0.50) → IRCd
User3 (Franța) → WebServer (10.0.0.50) → IRCd
```

**Ce vede IRCd-ul:**
```irc
[14:30] * Joins: User1 (user1@10.0.0.50)
[14:31] * Joins: User2 (user2@10.0.0.50)
[14:32] * Joins: User3 (user3@10.0.0.50)
#                        ^^^^^^^^^^^ TOȚI au același IP (serverul web)!
```

**Probleme:**
- ❌ Toți utilizatorii apar cu același IP (IP-ul serverului web)
- ❌ Limitele de conexiuni per IP (clone protection) blochează utilizatori legitimi
- ❌ Gline/Ban-uri afectează TOȚI utilizatorii web
- ❌ Imposibil de identificat abuza tori individuali
- ❌ GeoIP-ul arată locația serverului, nu a utilizatorului real

### **Soluția CU WebIRC:**

```
User1 (RO: 203.0.113.10) → WebServer → WEBIRC → IRCd
User2 (US: 198.51.100.25) → WebServer → WEBIRC → IRCd
User3 (FR: 192.0.2.15) → WebServer → WEBIRC → IRCd
```

**Ce vede IRCd-ul:**
```irc
[14:30] * Joins: User1 (user1@203.0.113.10)
[14:31] * Joins: User2 (user2@198.51.100.25)
[14:32] * Joins: User3 (user3@192.0.2.15)
#                        ^^^^^^^^^^^^^^^^ IP-uri REALE ale utilizatorilor!
```

**Avantaje:**
- ✅ Fiecare utilizator are IP-ul său real vizibil
- ✅ Clone protection funcționează normal
- ✅ Ban-uri afectează doar utilizatorul problematic
- ✅ GeoIP corect (arată țara reală)
- ✅ Identificare abuzatori individuali

---

## 🔧 CUM FUNCȚIONEAZĂ?

### **Protocolul WebIRC:**

1. **User** se conectează la **WebServer** (ex: https://chat.underchat.org)
2. **WebServer** (Kiwi IRC, etc.) se conectează la **IRCd**
3. **WebServer** trimite comanda **WEBIRC** ÎNAINTE de USER/NICK:
   ```
   WEBIRC parola_secreta cgiirc hostname.real 203.0.113.10
   ```
4. **IRCd** verifică:
   - Parola este corectă?
   - WebServer-ul este autorizat (în WebIRC block)?
   - IP-ul și hostname-ul sunt valide?
5. **IRCd** înlocuiește IP-ul WebServer-ului cu IP-ul real al utilizatorului
6. **User** apare pe IRC cu IP-ul său real!

---

## 📝 SINTAXĂ ÎN ircd.conf

### **Formatul de bază:**

```conf
WebIRC {
    host = "webserver@ip.address";
    password = "parola_secreta";
    description = "Kiwi IRC Gateway";
};
```

### **Parametri:**

| Parametru | Obligatoriu | Descriere |
|-----------|-------------|-----------|
| `host` | ✅ DA | Hostmask-ul serverului web autorizat (format: `user@host` sau `*@ip`) |
| `password` | ✅ DA | Parola secretă pentru autentificare (shared secret) |
| `description` | ❌ NU | Descriere afișată în WHOIS (ex: "Web User") |
| `ident` | ❌ NU | Ident fix pentru utilizatori web (ex: "webchat") |
| `userident` | ❌ NU | Folosește username-ul din USER ca ident (yes/no, default: no) |
| `ignoreident` | ❌ NU | Ignoră identd reply de la server web (yes/no, default: no) |
| `stripsslfp` | ❌ NU | Șterge SSL fingerprint de la web server (yes/no, default: no) |
| `enableoptions` | ❌ NU | Activează parsarea IRCv3 WEBIRC options (yes/no, default: no) |
| `trustaccount` | ❌ NU | Permite autentificare automată via WEBIRC (yes/no, default: no) |

---

## 💡 EXEMPLE PRACTICE

### **Exemplu 1: Configurare Simplă (Kiwi IRC)**

```conf
WebIRC {
    host = "*@203.0.113.50";
    password = "$PLAIN$k1w1_s3cr3t_p@ssw0rd";
    description = "Kiwi IRC Web Gateway";
};
```

**Explicație:**
- Orice conexiune de pe `203.0.113.50` (serverul unde rulează Kiwi IRC)
- Trebuie să furnizeze parola `k1w1_s3cr3t_p@ssw0rd`
- În WHOIS se va afișa: "Kiwi IRC Web Gateway"

**Configurare Kiwi IRC (config.ini):**
```ini
[webirc]
password = k1w1_s3cr3t_p@ssw0rd
```

---

### **Exemplu 2: Multiple Servere Web**

```conf
# Server Web Principal
WebIRC {
    host = "*@203.0.113.50";
    password = "$PLAIN$main_server_pass";
    description = "Main Web Chat";
};

# Server Web Backup
WebIRC {
    host = "*@203.0.113.51";
    password = "$PLAIN$backup_server_pass";
    description = "Backup Web Chat";
};

# Server Web Localhost (pentru testing)
WebIRC {
    host = "*@127.0.0.1";
    password = "$PLAIN$localhost_test";
    description = "Local Testing";
};
```

---

### **Exemplu 3: Cu Ident Custom și Opțiuni**

```conf
WebIRC {
    host = "*@203.0.113.50";
    password = "$PLAIN$web_password";
    description = "Web Chat";
    
    # Setări avansate
    ident = "webchat";          # Toți web users au ident "webchat"
    userident = no;             # Nu folosi username-ul ca ident
    ignoreident = yes;          # Ignoră identd de la webserver
    stripsslfp = yes;           # Șterge SSL fingerprint
    enableoptions = yes;        # Activează IRCv3 WEBIRC options
    trustaccount = no;          # Nu permite auto-auth
};
```

**Rezultat:**
```irc
/WHOIS WebUser
WebUser is webchat@203.0.113.10 * Real Name
#          ^^^^^^^ ident fix     ^^^^^^^^^^^ IP real
WebUser using Web Chat (Web Gateway)
#            ^^^^^^^^^ description
```

---

### **Exemplu 4: Rețea CIDR (Multiple IP-uri)**

```conf
# Permite tot subnet-ul 203.0.113.0/24
WebIRC {
    host = "*@203.0.113.*";
    password = "$PLAIN$subnet_password";
    description = "Web Gateway Farm";
};

# Sau cu CIDR notation:
WebIRC {
    host = "*@203.0.113.0/24";
    password = "$PLAIN$cidr_password";
    description = "Web Gateway CIDR";
};
```

---

### **Exemplu 5: TheLounge (Self-hosted IRC Client)**

```conf
WebIRC {
    host = "*@10.0.0.100";
    password = "$PLAIN$thelounge_secret";
    description = "TheLounge Web Client";
    ident = "lounge";
    userident = yes;
    ignoreident = yes;
};
```

**Configurare TheLounge (config.js):**
```javascript
webirc: {
    "underchat.org": {
        password: "thelounge_secret",
        server: "irc.underchat.org",
        port: 6667
    }
}
```

---

## 🎓 CAZURI DE UTILIZARE

### **1. Kiwi IRC pe site-ul tău**

```conf
WebIRC {
    host = "*@chat.underchat.org";
    password = "$PLAIN$kiwi_password";
    description = "UnderChat Web Client";
};
```

**Link-ul utilizatorilor:** https://chat.underchat.org/

---

### **2. IRCCloud / Hosted Services**

```conf
# IRCCloud folosește IP-uri specifice
WebIRC {
    host = "*@192.0.2.0/24";
    password = "$PLAIN$irccloud_pass";
    description = "IRCCloud Gateway";
};
```

---

### **3. Multiple Gateway-uri (Load Balancing)**

```conf
# Gateway 1
WebIRC {
    host = "*@gateway1.underchat.org";
    password = "$PLAIN$shared_password";
    description = "Web Gateway 1";
};

# Gateway 2
WebIRC {
    host = "*@gateway2.underchat.org";
    password = "$PLAIN$shared_password";
    description = "Web Gateway 2";
};

# Gateway 3
WebIRC {
    host = "*@gateway3.underchat.org";
    password = "$PLAIN$shared_password";
    description = "Web Gateway 3";
};
```

---

## ⚙️ CONFIGURARE COMPLETĂ ÎN ircd.conf

### **Exemplu pentru UnderChat:**

```conf
# ============================================================================
# SECȚIUNE: WEBIRC - Gateway-uri Web-to-IRC
# ============================================================================

# Kiwi IRC - Server Principal
WebIRC {
    host = "*@203.0.113.50";
    password = "$PLAIN$k1w1_Str0ng_P@ssw0rd_2026";
    description = "UnderChat Web Chat";
    ident = "webchat";
    userident = no;
    ignoreident = yes;
    stripsslfp = yes;
    enableoptions = yes;
    trustaccount = no;
};

# TheLounge - Self-hosted
WebIRC {
    host = "*@10.0.0.100";
    password = "$PLAIN$l0ung3_S3cr3t_K3y";
    description = "UnderChat Lounge";
    ident = "lounge";
    userident = yes;
    ignoreident = yes;
};

# Testing local
WebIRC {
    host = "*@127.0.0.1";
    password = "$PLAIN$localhost_test_123";
    description = "Local Testing";
};
```

---

## 🔍 VERIFICARE ȘI TESTARE

### **1. Verifică configurația:**

```bash
grep -A 5 'WebIRC {' /home/ircd/ircd/lib/ircd.conf
```

**Output așteptat:**
```conf
WebIRC {
    host = "*@203.0.113.50";
    password = "$PLAIN$password_here";
    description = "Web Gateway";
};
```

### **2. Testează conexiunea WebIRC:**

În **Kiwi IRC config** sau **TheLounge config**, adaugă parola WebIRC.

**Kiwi IRC (config.ini):**
```ini
[webirc]
password = k1w1_Str0ng_P@ssw0rd_2026
```

**TheLounge (config.js):**
```javascript
webirc: {
    "underchat.org": {
        password: "l0ung3_S3cr3t_K3y"
    }
}
```

### **3. Verifică în IRC:**

```irc
# Conectează-te prin web client
# Apoi verifică:

/WHOIS YourNick

# Ar trebui să vezi:
YourNick is webchat@YOUR_REAL_IP * Real Name
#           ^^^^^^^ ident  ^^^^^^^^^^^^^ IP-ul tău real!
YourNick using UnderChat Web Chat
#              ^^^^^^^^^^^^^^^^^^^ description
```

### **4. Verifică log-urile IRCd:**

```bash
tail -f /home/ircd/ircd/log/ircd.log | grep WEBIRC
```

**Output SUCCESS:**
```
WEBIRC Client host: from 203.0.113.50 [203.0.113.50] to user.isp.ro [198.51.100.25]
```

**Output ERROR:**
```
WEBIRC Attempt unauthorized from 203.0.113.50 [203.0.113.50]
# → IP-ul nu e în WebIRC block

WEBIRC Attempt with invalid password from 203.0.113.50
# → Parola greșită
```

---

## 📊 AVANTAJE vs DEZAVANTAJE

### ✅ **AVANTAJE:**

1. **IP-uri reale** - Fiecare user are IP-ul său vizibil
2. **Clone protection** - Funcționează normal (nu mai sunt toți pe același IP)
3. **GeoIP corect** - Arată țara reală a utilizatorului
4. **Ban-uri precise** - Afectează doar utilizatorul problematic
5. **Identificare** - Poți identifica abuzatori individuali
6. **Statistici** - GeoIP, conexiuni per țară, etc. sunt corecte

### ⚠️ **DEZAVANTAJE:**

1. **Configurare necesară** - Trebuie configurat în IRCd ȘI în web client
2. **Shared secret** - Parola trebuie păstrată secretă
3. **Securitate** - Dacă cineva află parola, poate spoofa IP-uri
4. **Trust** - Trebuie să ai încredere în gateway-ul web

---

## 🚨 SECURITATE - BEST PRACTICES

### **1. Folosește parole FOARTE PUTERNICE**

```conf
# ❌ SLAB:
password = "$PLAIN$123456";

# ❌ SLAB:
password = "$PLAIN$webirc";

# ✅ BINE:
password = "$PLAIN$W3b1RC_Str0ng_P@ssw0rd_2026_UnD3rCh@t";
```

### **2. Limitează la IP-uri SPECIFICE**

```conf
# ❌ PERICOL (oricine poate):
host = "*@*";

# ✅ SIGUR (doar server-ul tău):
host = "*@203.0.113.50";

# ✅ SIGUR (doar subnet-ul tău):
host = "*@203.0.113.0/24";
```

### **3. Folosește HTTPS pentru web client**

```
❌ http://chat.underchat.org (parola e trimisă în clar!)
✅ https://chat.underchat.org (parola e criptată)
```

### **4. Monitorizează încercări neautorizate**

```bash
# În ircd.conf, activează notificări:
Operator {
    # ...
    snomask = "+s +w";  # Include SNO_WEBIRC
};

# Vei primi notificări pentru:
# - Încercări cu parolă greșită
# - Încercări de pe IP-uri neautorizate
# - IP-uri/hostname-uri invalide
```

### **5. Rotează parolele regulat**

```
Schimbă parola WebIRC la fiecare 3-6 luni
Actualizează în:
- ircd.conf (pe server IRC)
- config web client (Kiwi/Lounge/etc.)
```

---

## 🔧 TROUBLESHOOTING

### **Problemă: WEBIRC nu funcționează**

**Cauze posibile:**

1. **WebIRC NU este configurat în ircd.conf**
   ```bash
   grep 'WebIRC {' /home/ircd/ircd/lib/ircd.conf
   # Dacă nu găsește → Trebuie adăugat
   ```

2. **Parola greșită în web client**
   ```bash
   # Log IRCd:
   tail -f /home/ircd/ircd/log/ircd.log | grep WEBIRC
   # Caută: "WEBIRC Attempt with invalid password"
   ```

3. **IP-ul web server-ului nu se potrivește**
   ```conf
   # Config:
   host = "*@203.0.113.50";
   
   # Dar web server-ul are IP: 203.0.113.51
   # → NU se potrivește → BLOCAT!
   ```

4. **Comanda WEBIRC trimisă prea târziu**
   ```
   WEBIRC trebuie trimisă ÎNAINTE de USER/NICK
   Ordinea corectă:
   1. WEBIRC password user host ip
   2. NICK nickname
   3. USER username 0 * :realname
   ```

### **Soluție generală:**

```bash
# 1. Adaugă WebIRC în ircd.conf
nano /home/ircd/ircd/lib/ircd.conf

# Adaugă:
WebIRC {
    host = "*@IP_WEB_SERVER";
    password = "$PLAIN$parola_aici";
    description = "Web Gateway";
};

# 2. Repornește IRCd
killall ircd
/home/ircd/ircd/bin/ircd -f /home/ircd/ircd/lib/ircd.conf

# 3. Configurează parola în web client (Kiwi/Lounge)

# 4. Testează conexiunea
```

---

## 📚 INTEGRARE CU CLIENȚI POPULARI

### **1. Kiwi IRC**

**Instalare:**
```bash
# Pe serverul web
cd /opt
git clone https://github.com/kiwiirc/kiwiirc.git
cd kiwiirc
npm install
```

**Configurare (config.ini):**
```ini
[webirc]
password = your_webirc_password

[connections]
default_server = irc.underchat.org
default_port = 6667
```

---

### **2. TheLounge**

**Instalare:**
```bash
npm install -g thelounge
thelounge start
```

**Configurare (config.js):**
```javascript
module.exports = {
    webirc: {
        "underchat.org": {
            password: "your_webirc_password",
            server: "irc.underchat.org",
            port: 6667
        }
    }
};
```

---

### **3. IRCCloud (Service Hosted)**

Contactează IRCCloud pentru a cere adăugarea rețelei tale.
Ei vor furniza IP-urile lor și parola WebIRC necesară.

---

## 🎯 REFERINȚE

- **Cod sursă:** `ircd/m_webirc.c`
- **Exemplu config:** `doc/example.conf` (liniile 1047-1089)
- **Specificație IRCv3:** https://ircv3.net/specs/extensions/webirc
- **Kiwi IRC:** https://kiwiirc.com/
- **TheLounge:** https://thelounge.chat/

---

## 🎯 CONCLUZIE

**WebIRC** = **Gateway Web-to-IRC cu IP-uri reale**

Transformă conexiuni web:
```
FĂRĂ: Toți → WebServer IP → IRCd (toți cu același IP)
CU:   User1 → WebServer → WEBIRC → IRCd (fiecare cu IP-ul său)
```

Este **ESENȚIAL** pentru:
- ✅ Clienți IRC web (Kiwi IRC, TheLounge)
- ✅ Integrare IRC pe site-uri
- ✅ GeoIP corect pentru web users
- ✅ Clone protection funcțional
- ✅ Ban-uri precise

---

**Data:** 14 Februarie 2026  
**Versiune:** 1.0  
**Pentru:** UnderChat IRCd v1.5.0+

---

## 🚀 QUICK START

**Pentru a adăuga WebIRC:**

```conf
# Adaugă în /home/ircd/ircd/lib/ircd.conf:

WebIRC {
    host = "*@IP_WEBSERVER_TĂU";
    password = "$PLAIN$parola_foarte_puternica_2026";
    description = "UnderChat Web Client";
    ident = "webchat";
    ignoreident = yes;
};
```

**În Kiwi IRC (config.ini):**
```ini
[webirc]
password = parola_foarte_puternica_2026
```

**Restart IRCd:**
```bash
killall ircd
/home/ircd/ircd/bin/ircd -f /home/ircd/ircd/lib/ircd.conf
```

**Testează:** Conectează-te prin web client și verifică `/WHOIS` - ar trebui să vezi IP-ul tău real!

**GATA!** ✅