# 🦀 🔮 CrabChat v1.0: The Equestrian & Goetic E2EE Grimoire

Welcome to **CrabChat**, a peer-to-peer (P2P) secure messaging web application forged in the sacred subterranean mushroom rings of Princess Pi and blessed by Prince Stolas's astral grimoires. Built for fuzzy paws, digital equestrians, and privacy-paranoid creatures alike, CrabChat establishes a zero-trust, end-to-end encrypted (E2EE) mesh network directly in your browser without central server snooping.

---

## 🌟 Features & The Magic Within

* **Zero-Knowledge Architecture:** No chat logs, databases, or transcripts touch the server. Messages flow strictly through encrypted WebRTC data channels peer-to-peer.
* **Argon2id Key Derivation:** Your cryptographic identity is protected by memory-hard Argon2id hashing, ensuring brute-force attempts bounce off your security barriers like armor on a royal guard pony.
* **Perfect Forward Secrecy (PFS):** Every peer connection negotiates fresh ephemeral keys signed by Ed25519 identity keys, ensuring past or future chats remain safe even if a key is ever compromised.
* **Encrypted File Transports:** Seamlessly drag and drop files up to 100MB, encrypted client-side with secretbox primitives before crossing the wire.
* **TURN Relay Fallback:** Easily plug in a TURN server configuration to punch through stubborn corporate firewalls or symmetric NATs when direct peer hole-punching fails.

---

## ⚖️ Pros and Cons

### Pros

* **Absolute Data Sovereignty:** Your keys never leave your device (stored safely via local storage or exported as JSON).
* **Decentralized Mesh:** Once peers connect via the lightweight Node.js signaling server, communication is entirely browser-to-browser.
* **Whimsical UX:** Fully colorized ANSI terminal background art, dynamic glowing favicons, and custom pastel themes fit for any royal court or den.

### Cons

* **Volatile Memory:** If you clear your browser data or lose your passphrase without exporting your identity key, your identity vanishes into the ether like a frightened forest faun.
* **Network Restrictions:** Strict enterprise or school firewalls may block direct P2P connections unless a dedicated TURN server is provided in the login panel.

---

## ⚙️ Technical Details

* **Cryptographic Engine:** `libsodium.js` (Ed25519 signature keys, X25519 boxes, secretbox stream encryption).
* **Key Derivation Function:** Argon2id (with an automatic fallback to WebCrypto PBKDF2-SHA256 if needed).
* **Transport Layer:** WebRTC `RTCDataChannel` running over SCTP, orchestrated via a minimal Node.js and Socket.io signaling backbone.
* **State Management:** Single-page application architecture featuring dynamic DOM manipulation and real-time packet verification.

---

## 🐾 How to Use the Web App

1. **Awaken Your Identity:** When you first open the portal, input a robust passphrase (minimum 20 characters, including uppercase, lowercase, numbers, and special symbols) to forge a new cryptographic identity under Princess Pi’s watch. If you already have a key file, use the **Import Key** button.
2. **Configure TURN (Optional):** If you or your peers are connecting across different external networks behind aggressive NAT routers, expand the TURN configuration panel and enter your relay server details (`turn:your-server.com:3478`, username, and credential).
3. **Unlock & Enter Room:** Click **Unlock / Generate** to enter the main chat interface. A unique room ID will be automatically generated, or you can specify one in the landing input.
4. **Invite Your Pack:** Click **Copy Link** to share the secure invite URL with your fellow creatures.
5. **Chat & Share Files:** Once the PFS cryptographic handshake completes successfully in the status feed, type encrypted messages or click **Send File** to beam files securely across the mesh.

---

## 🐧 Installing the Node Server on a Linux Box

Deploying your own CrabChat signaling node on a Debian-like Linux server (or Kali WSL environment) takes only a few moments. Follow these steps:

### 1. Update System & Install Node.js

Ensure your system packages are fresh and install Node.js and npm:

```bash
sudo apt update && sudo apt upgrade -y
sudo apt install nodejs npm -y

```

### 2. Create the Project Directory

Set up a clean home for your server and libsodium library dependencies:

```bash
mkdir -p /opt/crabchat/public
cd /opt/crabchat
npm init -y
npm install socket.io

```

### 3. Obtain Libsodium Assets

Copy or download the required libsodium browser distribution files (`libsodium.js` and `libsodium-wrappers.js`) and place them directly into your `public/` directory alongside your `index.html` file.

### 4. Create the Signaling Server (`server.js`)

Create a basic Express or HTTP socket server to handle room signaling. Create `server.js` in `/opt/crabchat/`:

```javascript
const express = require('express');
const http = require('http');
const { Server } = require('socket.io');
const path = require('path');

const app = express();
const server = http.createServer(app);
const io = new Server(server);

app.use(express.static(path.join(__dirname, 'public')));

io.on('connection', (socket) => {
  socket.on('join-room', (room) => {
    socket.join(room);
    socket.to(room).emit('user-joined', socket.id);

    socket.on('offer', (data) => {
      io.to(data.target).emit('offer', { sender: socket.id, offer: data.offer });
    });

    socket.on('answer', (data) => {
      io.to(data.target).emit('answer', { sender: socket.id, answer: data.answer });
    });

    socket.on('ice-candidate', (data) => {
      io.to(data.target).emit('ice-candidate', { sender: socket.id, candidate: data.candidate });
    });

    socket.on('disconnect', () => {
      socket.to(room).emit('user-disconnected', socket.id);
    });
  });
});

const PORT = process.env.PORT || 3000;
server.listen(PORT, () => {
  console.log(`[Stolas Grimoire Node] CrabChat server active on port ${PORT}`);
});

```

### 5. Launch the Server

Start your server directly or manage it with a process manager like PM2 to keep it running continuously in the background:

```bash
sudo npm install -g pm2
pm2 start server.js --name "crabchat"
pm2 startup
pm2 save

```

Your private, E2EE equestrian chat node is now online and ready to welcome encrypted connections!