levix-bot 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdelrhman Diab (Leviro)
+
+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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# Levix
+
+A self-hosted personal WhatsApp bot: 55 commands, group moderation, an AI agent
+on Google Gemini, scheduled messages, and a web control panel that can change
+almost all of it while the bot runs.
+
+Built by Abdelrhman Diab (Leviro).
+
+```bash
+npm install -g levix-bot
+levix
+```
+
+The npm package is named `levix-bot`; the installed CLI command stays `levix`.
+
+On a desktop that opens the panel in your browser by itself. Pick a password,
+scan the QR, done — see [SETUP.md](SETUP.md) for the longer version, Docker,
+and running it as a service.
+
+```
+  levix                    start Levix with the web panel
+  levix headless           start Levix with no web UI at all
+  levix where              print the data directory
+  levix reset-password     reset the panel password
+  levix domain [name]      point a domain at Levix (may need sudo)
+```
+
+---
+
+## What it does
+
+**Commands** — `!ping`, `!help`, `!calc`, `!poll`, `!rand`, `!loop`, `!todo`,
+`!notes`, `!debt`, `!weather`, `!prayer`, `!tts`, `!stt`, `!shortlink`,
+`!qr`, `!score`… every one of them can be renamed, re-permissioned or turned
+off from the panel.
+
+**Group moderation** — welcome messages, anti-link, anti-spam, media rules,
+warnings with auto-kick, rules and notes, plus the usual `!group kick`,
+`promote`, `demote`, `add`, `tagadmins`.
+
+**An AI agent, not a chat box** — `!gemini` can search the web, open a page and
+read it, save something to its long-term memory and hand out bot roles, across
+several tool rounds, narrating the whole run inside a single message it keeps
+editing. Its personality is a Markdown file you can edit from the panel.
+
+**Long-term memory** — "remember that…" writes to `memory/global.md` or a
+per-chat file. Plain Markdown, hand-editable, injected into every prompt.
+
+**Scheduled messages** — one-off (`!schedule`) or recurring (`!autoschedule`),
+stored in the database and listed in the panel.
+
+**A panel you can also do without** — `levix headless` runs the bot with no
+Express, no socket.io and no port open at all; an unpaired install prints its
+QR straight to the terminal.
+
+**A domain, without a takeover** — `levix domain bot.example.com` looks at what
+the server already runs and works with it: it adds one nginx or Caddy site and
+validates the whole configuration before reloading, and on a panel-managed or
+containerised host it changes nothing and prints the exact reverse-proxy
+settings instead.
+
+---
+
+## How it is put together
+
+- **Node 24+**, ES modules and CommonJS side by side (see `CLAUDE.md`).
+- **[Baileys v7](https://github.com/WhiskeySockets/Baileys)** for WhatsApp,
+  including the LID system.
+- **SQLite through `node:sqlite`** — Node's own module, so the whole datastore
+  is one file and zero dependencies. No database server, nothing to compile.
+- **Express + EJS** for the panel. No framework, no CDN, no build step.
+- **Google Gemini** for the AI, with an optional Groq fallback.
+
+Three things follow from that, and they are the point of the design:
+
+**The database is the source of truth, the panel is how you edit it.** There is
+no `.env` file and no config file — the prefix, every permission, every API key
+and every tuning value is a row in `bot_settings`, and every read goes through
+an accessor at call time so a change applies to the next message.
+
+**Secrets are generated, not configured.** The session signing key is made on
+first start. The panel password is chosen once, in the browser, and stored as
+an scrypt hash.
+
+**Everything mutable lives in one directory** — database, WhatsApp session,
+memory files, logs. `levix where` prints it; copying it is a full backup.
+
+---
+
+## For developers
+
+```bash
+git clone https://github.com/Abdodiab2005/levix
+cd levix
+npm install
+npm start          # data lands in ./data
+```
+
+`CLAUDE.md` is the architecture document: module layout, the storage API, the
+message flow, and the rules a change has to respect. `PACKAGING.md` covers
+shipping it — npm, Docker, systemd, and the single-executable build.
+
+## License
+
+MIT.

package/SETUP.md

@@ -0,0 +1,242 @@
+# Setting up Levix
+
+Levix is a WhatsApp bot you run yourself. It links to your own WhatsApp account
+by scanning a QR code, exactly like WhatsApp Web, and everything after that is
+configured from a control panel in your browser.
+
+There is no configuration file to edit. There are no keys to generate. If a
+guide anywhere tells you to create a `.env` file, it is out of date.
+
+---
+
+## What you need
+
+- A computer or a small server that stays on. A Raspberry Pi is enough.
+- **Node.js 24 or newer** — [nodejs.org](https://nodejs.org), pick the LTS
+  button. (Or skip Node entirely and use Docker, below.)
+- A phone with WhatsApp, to scan the QR once.
+
+Levix stores everything in one file using SQLite, which Node 24 includes.
+Nothing is compiled, nothing else is installed, no database server is needed.
+
+---
+
+## The quickest way
+
+```bash
+npm install -g levix-bot
+levix
+```
+
+`levix-bot` is the npm package name. The command you run after installing it is
+still just `levix`.
+
+The terminal prints something like:
+
+```
+  Levix is running
+
+  Panel: http://localhost:3001/setup
+  Data:  ~/.levix
+
+  First run — that link asks you to pick a password.
+  Opening it from another machine also needs this code: 43CB5162
+
+  Opening Levix in your browser...
+
+  Press Ctrl+C to stop.
+```
+
+1. On a desktop the browser opens by itself. Otherwise open that address.
+2. Choose a password. (Opening the page from a *different* machine also asks
+   for the setup code above — that's what stops a stranger from claiming your
+   bot before you do.)
+3. You land on the control panel. Go to **Connection** and scan the QR with
+   WhatsApp → Settings → Linked devices → Link a device.
+4. Send `!ping` in any chat. The bot answers.
+
+Levix only opens a browser when there is one to open: over SSH, under systemd,
+in Docker or in CI it just prints the address and says why. `--no-open` turns
+it off anywhere.
+
+That's the whole setup. Keep the terminal open, or see *Keeping it running*.
+
+---
+
+## With Docker instead
+
+No Node install, nothing on your system but the container:
+
+```bash
+git clone https://github.com/Abdodiab2005/levix
+cd levix
+docker compose up -d
+```
+
+Then open <http://localhost:3001>. The setup code is in the logs:
+
+```bash
+docker compose logs levix | grep -A3 "Setup code"
+```
+
+Everything the bot owns lives in the `levix-data` volume.
+
+---
+
+## Running it without the web panel
+
+On a server you may not want a panel at all:
+
+```bash
+levix headless
+```
+
+That starts the bot and nothing else — no web interface, no port opened. If the
+bot has never been paired it prints the QR straight into the terminal:
+
+```
+  Levix — headless
+
+  No WhatsApp session found.
+
+  Scan this QR from:
+  WhatsApp -> Linked devices -> Link a device
+
+  [ the QR ]
+
+  ✓ WhatsApp connected
+  ✓ Levix is ready
+
+  55 commands loaded
+```
+
+You can switch modes freely: the data directory is the same either way.
+
+---
+
+## Putting it on a domain
+
+```bash
+sudo levix domain bot.example.com
+```
+
+Levix looks at what the server already runs and fits in with it:
+
+| What it finds | What it does |
+| --- | --- |
+| nginx (+ certbot) | adds one nginx site, runs `nginx -t`, reloads, offers HTTPS |
+| Caddy | adds one site file to the existing Caddy |
+| Apache | prints the reverse-proxy settings; changes nothing |
+| a hosting panel (Plesk, cPanel, CloudPanel, …) | prints the settings and where to enter them; changes nothing |
+| nothing at all | offers to install Caddy, which handles HTTPS by itself |
+| something unrecognised on :80/:443 | stops and tells you what is there |
+
+It never edits another site, never overwrites `nginx.conf`, and never reloads a
+configuration that failed validation. Running it twice does not create a second
+copy of anything.
+
+The bot itself never needs root — only this command does, and only when it is
+actually going to write to `/etc`.
+
+---
+
+## Turning on the parts that need a key
+
+The bot works out of the box. Two features need a free key, and both are set in
+**Settings** in the panel — never in a file:
+
+| Feature | Where to get the key |
+| --- | --- |
+| AI replies (`!gemini`, `!ai`) | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) |
+| Weather (`!weather`) | [openweathermap.org/api](https://openweathermap.org/api) |
+
+Paste the key, press Save. It applies to the next message — no restart.
+
+---
+
+## Keeping it running
+
+Closing the terminal stops the bot. Pick one:
+
+**Docker** — already handled; the container restarts by itself.
+
+**A Linux server** — the installer sets up a service that starts on boot:
+
+```bash
+curl -fsSL https://levix.leviro.net/install.sh | bash
+```
+
+Read the script first if you like — it is short, and it explains each step.
+
+That always installs the newest stable Levix. To stay on one version — the same
+script, pinned — use its own URL:
+
+```bash
+curl -fsSL https://levix.leviro.net/install/v2.0.0.sh | bash
+```
+
+**Your own machine** — `pm2` works well:
+
+```bash
+npm install -g pm2
+pm2 start levix --name levix
+pm2 save && pm2 startup
+```
+
+---
+
+## Where your data is
+
+One directory holds all of it: the database, the WhatsApp session, the bot's
+long-term memory, the logs.
+
+```bash
+levix where
+```
+
+- installed with npm: `~/.levix`
+- running from a git clone: `./data` inside the clone
+- Docker: the `levix-data` volume
+
+**Backing up** means copying that directory. **Moving to another machine**
+means copying it across and starting Levix there — including the WhatsApp
+session, so you don't even rescan the QR.
+
+---
+
+## When something goes wrong
+
+**"Port 3001 is already taken"** — Levix is already running, or something else
+holds that port. Open <http://localhost:3001> and see. To move it: Settings →
+Server → Control panel port, then restart.
+
+**Forgot the panel password**
+
+```bash
+levix reset-password
+```
+
+Then start it again and pick a new one. The WhatsApp link is untouched.
+
+**The bot stopped answering** — WhatsApp dropped the link, usually because the
+phone was offline for a long time. Open the panel; if it asks for a QR, scan it
+again.
+
+**"Levix needs Node 24 or newer"** — your Node is older. Install the LTS build
+from [nodejs.org](https://nodejs.org) and try again.
+
+**Start over completely** — stop the bot, delete the data directory
+(`levix where` prints it), start it again. That wipes everything: settings,
+memory, the WhatsApp link.
+
+---
+
+## Two things worth knowing
+
+**Whoever scans the QR owns the bot.** That account is the owner and can run
+every command. You can add more owners and admins from **Roles** in the panel.
+
+**The panel has no HTTPS of its own.** On your own machine that's fine. On a
+server reachable from the internet, run `sudo levix domain bot.example.com` —
+it puts a reverse proxy with a certificate in front, sets the proxy-hop count
+for you, and stops the panel listening publicly on its raw port.

package/app.cjs

@@ -0,0 +1,337 @@
+// file: app.cjs
+//
+// The control panel's HTTP surface. It is not optional: the panel is the only
+// place the bot is configured, so there is always a server and always a login.
+//
+// Nothing here reads a configuration file or an environment variable. The
+// session key is generated on first start (src/config/secrets.cjs), the
+// password is chosen once from the browser, and the handful of HTTP knobs
+// (port, proxy hops, extra origin) are settings in the database that the panel
+// itself can change.
+
+const http = require("node:http");
+const express = require("express");
+const { Server } = require("socket.io");
+const session = require("express-session");
+
+const logger = require("./src/utils/logger.cjs");
+const { assetPath } = require("./src/config/paths.cjs");
+const brand = require("./src/config/brand.cjs");
+const settings = require("./src/config/settings.cjs");
+const secrets = require("./src/config/secrets.cjs");
+const { getQrCode } = require("./src/utils/storage.cjs");
+const {
+  clientAddress,
+  isDirectLocalRequest,
+} = require("./src/utils/requestOrigin.cjs");
+
+const SESSION_COOKIE_NAME = "wa.sid";
+const SESSION_MAX_AGE_MS = 12 * 60 * 60 * 1000;
+
+const app = express();
+const server = http.createServer(app);
+
+// Origin check for the socket: socket.io's `cors` option only covers polling,
+// and the browser doesn't apply CORS to a websocket at all.
+function isAllowedOrigin(origin, host) {
+  if (!origin) return true; // curl / a mobile app: no browser to protect
+  const extra = settings.get("dashboard_origin");
+  if (extra && origin === extra) return true;
+  return origin === `http://${host}` || origin === `https://${host}`;
+}
+
+// serveClient reads the browser bundle out of node_modules on every request,
+// which a packaged build has no way to do. We vendor it in public/ instead —
+// same reason qrcode.min.js is there rather than on a CDN.
+const io = new Server(server, {
+  serveClient: false,
+  maxHttpBufferSize: 1e6,
+  allowRequest: (req, callback) => {
+    callback(null, isAllowedOrigin(req.headers.origin, req.headers.host));
+  },
+});
+
+app.disable("x-powered-by");
+
+// Behind a proxy (nginx / Cloudflare) this has to match the real number of
+// hops, or req.ip is the proxy's address — or worse, one the client forged.
+// Default: off, which is right when the panel is exposed directly.
+const trustProxy = settings.get("trust_proxy");
+// Remembered rather than re-read: whether a proxy is in front decides whether
+// the first-run page can ever skip the setup code, and that must not change
+// under us mid-process. See src/utils/requestOrigin.cjs.
+const PROXY_CONFIGURED = Boolean(trustProxy);
+if (PROXY_CONFIGURED) {
+  app.set("trust proxy", /^\d+$/.test(trustProxy) ? Number(trustProxy) : trustProxy);
+}
+
+app.use((req, res, next) => {
+  res.set("X-Content-Type-Options", "nosniff");
+  res.set("Referrer-Policy", "no-referrer");
+  res.set("X-Frame-Options", "DENY");
+  res.set("Content-Security-Policy", "frame-ancestors 'none'");
+  res.set("Cross-Origin-Opener-Policy", "same-origin");
+  next();
+});
+
+// 100 KB is plenty for the small dashboard mutations. The dashboard API is the
+// exception: it carries whole Markdown files (the AI persona, a memory file),
+// so src/index.js mounts `dashboardJson` in front of it and this parser skips
+// those paths.
+const jsonBody = express.json({ limit: "100kb" });
+const dashboardJson = express.json({ limit: "2mb" });
+
+app.use((req, res, next) => {
+  if (req.path.startsWith("/dashboard/api/")) return next();
+  return jsonBody(req, res, next);
+});
+
+// SameSite=lax closes the classic CSRF; this is a cheap check on top of it for
+// anything that changes state.
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+app.use((req, res, next) => {
+  if (SAFE_METHODS.has(req.method)) return next();
+  if (isAllowedOrigin(req.get("origin"), req.get("host"))) return next();
+  return res.status(403).json({ error: "Cross-origin request rejected" });
+});
+
+function requireLoginApi(req, res, next) {
+  if (req.session?.loggedIn) return next();
+  return res.status(401).json({ error: "Unauthorized" });
+}
+
+// The QR and the dashboard are sensitive: no-store so a proxy or the browser's
+// back button can't hand a signed-in page to someone else.
+function noStore(req, res, next) {
+  res.set("Cache-Control", "no-store");
+  next();
+}
+
+function requireLoginPage(req, res, next) {
+  if (req.session?.loggedIn) return next();
+  return res.redirect("/");
+}
+
+// Bind the engine by value rather than letting express require("ejs") lazily
+// by name: a packaged build has no module resolver to answer that call.
+app.engine("ejs", require("ejs").__express);
+app.set("view engine", "ejs");
+app.set("views", assetPath("views"));
+// Name, tagline and credit for every template. Frozen — see brand.cjs.
+app.locals.brand = brand;
+app.use(express.static(assetPath("public")));
+app.use(express.urlencoded({ extended: true, limit: "100kb" }));
+
+const sessionMiddleware = session({
+  name: SESSION_COOKIE_NAME,
+  secret: secrets.getSessionSecret(),
+  resave: false,
+  saveUninitialized: false,
+  cookie: {
+    httpOnly: true,
+    sameSite: "lax",
+    // "auto" = Secure only on an HTTPS request, so the same install works on
+    // http://localhost and behind a TLS proxy without a setting to get wrong.
+    secure: "auto",
+    path: "/",
+    maxAge: SESSION_MAX_AGE_MS,
+  },
+});
+
+app.use(sessionMiddleware);
+
+// Every socket receives the pairing QR, so it goes through the same session.
+io.engine.use(sessionMiddleware);
+io.use((socket, next) => {
+  if (socket.request.session?.loggedIn) return next();
+  next(new Error("unauthorized"));
+});
+
+// --- Attempt throttling ---------------------------------------------------
+// Shared by /login and /setup: both are a guess at a secret.
+//
+// Keyed on the TCP peer, never on `req.ip`: with `trust proxy` set, a client
+// picks its own `req.ip` by writing a header, so it could rotate the value and
+// never hit the limit.
+
+const ATTEMPT_WINDOW_MS = 15 * 60 * 1000;
+const MAX_ATTEMPTS = 5;
+const attempts = new Map();
+
+function blockedFor(ip) {
+  const now = Date.now();
+  for (const [key, entry] of attempts) {
+    if (now - entry.firstAt > ATTEMPT_WINDOW_MS) attempts.delete(key);
+  }
+  const entry = attempts.get(ip);
+  if (!entry || entry.count < MAX_ATTEMPTS) return 0;
+  const remaining = ATTEMPT_WINDOW_MS - (now - entry.firstAt);
+  return remaining > 0 ? Math.ceil(remaining / 1000) : 0;
+}
+
+function recordFailure(ip) {
+  const now = Date.now();
+  const entry = attempts.get(ip);
+  if (!entry || now - entry.firstAt > ATTEMPT_WINDOW_MS) {
+    attempts.set(ip, { count: 1, firstAt: now });
+    return;
+  }
+  entry.count += 1;
+}
+
+// --- First run ------------------------------------------------------------
+//
+// Until a password exists there is nothing to log into. The panel shows a
+// "choose your password" page instead.
+//
+// From a direct loopback connection that is all it asks: whoever is sitting at
+// the machine is the operator. Every other request — remote, proxied, or merely
+// carrying a forwarding header — also needs the setup code printed on the
+// server's console, so claiming the bot requires access to the machine rather
+// than to the port. See src/utils/requestOrigin.cjs for why this can't be
+// `req.ip`.
+
+function isLocalRequest(req) {
+  return isDirectLocalRequest(req, { proxyConfigured: PROXY_CONFIGURED });
+}
+
+function renderSetup(req, res, error, status = 200) {
+  res.status(status).render("setup", {
+    error,
+    needsCode: !isLocalRequest(req),
+    minLength: secrets.MIN_PASSWORD_LENGTH,
+  });
+}
+
+app.get("/setup", noStore, (req, res) => {
+  if (secrets.hasDashboardPassword()) return res.redirect("/");
+  renderSetup(req, res, null);
+});
+
+app.post("/setup", (req, res, next) => {
+  if (secrets.hasDashboardPassword()) return res.redirect("/");
+
+  const peer = clientAddress(req);
+  const retryAfter = blockedFor(peer);
+  if (retryAfter) {
+    res.set("Retry-After", String(retryAfter));
+    return renderSetup(req, res, "Too many attempts. Try again later.", 429);
+  }
+
+  const { password, confirm, code } = req.body || {};
+
+  if (!isLocalRequest(req) && !secrets.setupCodeMatches(code)) {
+    recordFailure(peer);
+    logger.warn({ ip: peer }, "[dashboard] Setup attempted with a wrong code");
+    return renderSetup(req, res, "Wrong setup code.", 401);
+  }
+
+  if (password !== confirm) {
+    return renderSetup(req, res, "The two passwords don't match.", 400);
+  }
+
+  try {
+    secrets.setDashboardPassword(password);
+  } catch (error) {
+    return renderSetup(req, res, error.message, 400);
+  }
+
+  attempts.delete(peer);
+  logger.info({ ip: peer }, "[dashboard] Password set — first run complete");
+
+  req.session.regenerate((err) => {
+    if (err) return next(err);
+    req.session.loggedIn = true;
+    req.session.save((saveErr) => {
+      if (saveErr) return next(saveErr);
+      res.redirect(303, "/");
+    });
+  });
+});
+
+// --- Routes ---------------------------------------------------------------
+
+app.get("/", noStore, (req, res) => {
+  if (!secrets.hasDashboardPassword()) return res.redirect("/setup");
+  if (req.session.loggedIn) return res.render("dashboard");
+  return res.render("login", { error: null });
+});
+
+app.post("/login", (req, res, next) => {
+  if (!secrets.hasDashboardPassword()) return res.redirect("/setup");
+
+  const peer = clientAddress(req);
+  const retryAfter = blockedFor(peer);
+  if (retryAfter) {
+    res.set("Retry-After", String(retryAfter));
+    return res.status(429).render("login", {
+      error: "Too many attempts. Try again later.",
+    });
+  }
+
+  if (!secrets.verifyDashboardPassword(req.body?.password)) {
+    recordFailure(peer);
+    logger.warn({ ip: peer }, "[dashboard] Failed login attempt");
+    return res.status(401).render("login", { error: "Incorrect Password" });
+  }
+
+  attempts.delete(peer);
+
+  // A fresh id after login, or the id an attacker planted beforehand still works.
+  req.session.regenerate((err) => {
+    if (err) return next(err);
+    req.session.loggedIn = true;
+    req.session.save((saveErr) => {
+      if (saveErr) return next(saveErr);
+      res.redirect(303, "/");
+    });
+  });
+});
+
+// POST, not GET: a link that changes state gets fired by an <img> or by the
+// browser's prefetch.
+app.post("/logout", (req, res, next) => {
+  req.session.destroy((err) => {
+    if (err) return next(err);
+    res.clearCookie(SESSION_COOKIE_NAME, {
+      httpOnly: true,
+      sameSite: "lax",
+      path: "/",
+    });
+    res.redirect(303, "/");
+  });
+});
+
+app.get("/qr", requireLoginPage, noStore, (req, res) => {
+  const qr = getQrCode();
+  res.render("qr", { qr: qr || "" });
+});
+
+// Unlink / restart / everything else live on the dashboard API
+// (/dashboard/api/*), registered in src/index.js once the socket exists.
+
+// The 404 and the error handler have to be registered after every route — put
+// them here and they would swallow the routes index.js adds later.
+function installFinalHandlers() {
+  app.use((req, res) => {
+    res.status(404).json({ error: "Not found" });
+  });
+
+  // eslint-disable-next-line no-unused-vars
+  app.use((err, req, res, next) => {
+    logger.error({ err, method: req.method, path: req.path }, "[http] Unhandled error");
+    if (res.headersSent) return;
+    res.status(err.statusCode || 500).json({ error: "Internal server error" });
+  });
+}
+
+module.exports = {
+  app,
+  server,
+  io,
+  dashboardJson,
+  requireLoginApi,
+  requireLoginPage,
+  noStore,
+  installFinalHandlers,
+};