levix-bot 2.0.0

package/src/config/defaults.cjs

@@ -0,0 +1,91 @@
+// Shipped defaults for the command table.
+//
+// This used to be config.json. It is JavaScript now for one reason: the
+// database is the source of truth and the dashboard is how you change things,
+// so a JSON file sitting next to the code invited the opposite — editing a
+// file the operator would then lose on the next `git pull`.
+//
+// Nothing here is ever written to. Whatever the operator changes from the
+// dashboard is stored as an override in `bot_settings` and layered on top by
+// src/config/runtime-config.cjs, which means:
+//
+//   * an update that adds a new command still gets its default permission,
+//   * nothing has to rewrite a file that is checked into the repo,
+//   * a change is live on the very next message.
+//
+// Group sub-commands are addressed as "group:<name>" everywhere else; the
+// nesting here is only so the group entry can carry a default_permission.
+
+const PREFIX = "!";
+
+const COMMAND_PERMISSIONS = Object.freeze(
+  {
+    "ping": "MEMBERS",
+    "gemini": "MEMBERS",
+    "qr": "MEMBERS",
+    "shortlink": "MEMBERS",
+    "schedule": "ADMINS_OWNER",
+    "weather": "MEMBERS",
+    "prayer": "MEMBERS",
+    "tagadmins": "MEMBERS",
+    "help": "MEMBERS",
+    "score": "MEMBERS",
+    "stt": "MEMBERS",
+    "tts": "MEMBERS",
+    "todo": "MEMBERS",
+    "notes": "MEMBERS",
+    "debt": "MEMBERS",
+    "calc": "MEMBERS",
+    "loop": "MEMBERS",
+    "rand": "MEMBERS",
+    "poll": "MEMBERS",
+    "memory": "MEMBERS",
+    "mod": "ADMINS_OWNER",
+    "blacklist": "ADMINS_OWNER",
+    "listschedules": "ADMINS_OWNER",
+    "deleteschedule": "ADMINS_OWNER",
+    "autoschedule": "OWNER_ONLY",
+    "perm": "OWNER_ONLY",
+    "setprefix": "OWNER_ONLY",
+    "restart": "OWNER_ONLY",
+    "shutdown": "OWNER_ONLY",
+    "status": "OWNER_ONLY",
+    "block": "OWNER_ONLY",
+    "unblock": "OWNER_ONLY",
+    "group": {
+      "default_permission": "ADMINS_OWNER",
+      "sub_commands": {
+        "approveall": "ADMINS_OWNER",
+        "setname": "ADMINS_OWNER",
+        "setpp": "ADMINS_OWNER",
+        "kick": "ADMINS_OWNER",
+        "add": "ADMINS_OWNER",
+        "promote": "ADMINS_OWNER",
+        "demote": "ADMINS_OWNER",
+        "removeall": "OWNER_ONLY",
+        "setrules": "ADMINS_ONLY",
+        "antilink": "ADMINS_ONLY",
+        "media": "ADMINS_ONLY",
+        "setwarn": "ADMINS_ONLY",
+        "warn": "ADMINS_ONLY",
+        "warns": "ADMINS_OWNER",
+        "clearwarns": "ADMINS_ONLY",
+        "rules": "MEMBERS",
+        "notes": "MEMBERS",
+        "members": "MEMBERS",
+        "tagadmins": "MEMBERS",
+        "welcome": "ADMINS_OWNER",
+        "blacklist": "ADMINS_OWNER",
+        "save": "ADMINS_OWNER",
+        "deletenote": "ADMINS_OWNER",
+        "remove": "ADMINS_ONLY",
+        "all": "MEMBERS"
+      }
+    }
+  }
+);
+
+module.exports = {
+  prefix: PREFIX,
+  command_permissions: COMMAND_PERMISSIONS,
+};

package/src/config/lock.cjs

@@ -0,0 +1,110 @@
+// One bot process per data directory.
+//
+// A WhatsApp pairing is a single session. Two Levix processes on one database
+// would both hold the same Baileys credentials, overwrite each other's session
+// keys, and answer every message twice — and the second one would only fail
+// much later, when it tried to bind the panel's port, long after it had
+// touched the auth rows.
+//
+// So the bot claims the data directory before it does anything else. This is a
+// lock file with a pid in it, which is the simplest thing that works on a
+// single machine — which is the only place a WhatsApp pairing can run anyway.
+// No daemon, no distributed anything.
+//
+// The CLI's read-only and recovery commands (`where`, `reset-password`) do NOT
+// take this lock: they have to work while the bot is running, or when it is
+// wedged, which is the whole point of having them.
+
+const fs = require("node:fs");
+
+const { dataPath } = require("./paths.cjs");
+const logger = require("../utils/logger.cjs");
+
+const LOCK_FILE = dataPath("levix.lock");
+
+/** Is that pid a process that still exists? */
+function processAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    // Signal 0 checks for existence without delivering anything.
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM means it exists and belongs to somebody else — still alive.
+    return err.code === "EPERM";
+  }
+}
+
+function readLock() {
+  try {
+    const raw = fs.readFileSync(LOCK_FILE, "utf8");
+    const pid = Number.parseInt(String(raw).trim(), 10);
+    return Number.isFinite(pid) ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+let held = false;
+
+function release() {
+  if (!held) return;
+  held = false;
+  try {
+    // Only remove it if it is still ours — a stale-lock takeover elsewhere
+    // could have replaced it.
+    if (readLock() === process.pid) fs.unlinkSync(LOCK_FILE);
+  } catch {}
+}
+
+/**
+ * Claim the data directory for this process.
+ *
+ * @throws {Error} when another live Levix already holds it. The message is
+ *   written for whoever is reading the terminal, not for a stack trace.
+ */
+function acquireSingleInstanceLock() {
+  if (held) return LOCK_FILE;
+
+  const claim = () => {
+    // "wx" fails if the file exists — the check and the create are one
+    // syscall, so two processes starting together can't both win.
+    const handle = fs.openSync(LOCK_FILE, "wx");
+    fs.writeFileSync(handle, String(process.pid));
+    fs.closeSync(handle);
+  };
+
+  try {
+    claim();
+  } catch (err) {
+    if (err.code !== "EEXIST") throw err;
+
+    const owner = readLock();
+    if (owner !== null && owner !== process.pid && processAlive(owner)) {
+      const error = new Error(
+        `Another Levix (pid ${owner}) is already using this data directory.\n` +
+          `  ${LOCK_FILE}\n\n` +
+          `  Only one Levix can run per data directory — a WhatsApp pairing is a\n` +
+          `  single session. Stop the other one, or start this one with --data\n` +
+          `  pointing somewhere else.`
+      );
+      error.code = "ELEVIXLOCKED";
+      throw error;
+    }
+
+    // The holder is gone (a crash, a kill -9, a reboot). Take it over.
+    logger.warn(
+      `[lock] Removing a stale lock from pid ${owner ?? "unknown"} — that process is gone`
+    );
+    fs.rmSync(LOCK_FILE, { force: true });
+    claim();
+  }
+
+  held = true;
+  // Best effort: a SIGKILL or a power cut leaves the file behind, which the
+  // stale check above handles on the next start.
+  process.once("exit", release);
+  return LOCK_FILE;
+}
+
+module.exports = { acquireSingleInstanceLock, release, LOCK_FILE, processAlive };

package/src/config/paths.cjs

@@ -0,0 +1,90 @@
+// The one directory the bot writes to.
+//
+// Database, long-term memory, the editable AI persona, logs, temp media —
+// all of it lands under a single directory, so "back up the bot" means copying
+// one folder and a packaged or globally installed copy never writes next to
+// its own code.
+//
+// Resolution order:
+//
+//   1. `--data <dir>` on the command line
+//   2. LEVIX_DATA_DIR — how a container is told where its volume is. It is the
+//      one environment variable the bot reads, because a Docker volume has no
+//      other way to say it.
+//   3. `<repo>/data` when running from a clone (writable, not inside
+//      node_modules) — keeps a developer's data next to the code
+//   4. `~/.levix` — global installs, packaged binaries, read-only images
+//
+// This module deliberately has no dependencies: the logger and the database
+// both need it, and neither can wait for the other.
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const ROOT = path.join(__dirname, "..", "..");
+
+function argDataDir() {
+  const index = process.argv.indexOf("--data");
+  if (index !== -1 && process.argv[index + 1]) return process.argv[index + 1];
+  const inline = process.argv.find((arg) => arg.startsWith("--data="));
+  return inline ? inline.slice("--data=".length) : null;
+}
+
+function isWritable(dir) {
+  try {
+    fs.accessSync(dir, fs.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveDataDir() {
+  const explicit = argDataDir() || process.env.LEVIX_DATA_DIR;
+  if (explicit) return path.resolve(explicit);
+
+  const installed = ROOT.includes(`${path.sep}node_modules${path.sep}`);
+  if (!installed && isWritable(ROOT)) return path.join(ROOT, "data");
+
+  return path.join(os.homedir(), ".levix");
+}
+
+const DATA_DIR = resolveDataDir();
+fs.mkdirSync(DATA_DIR, { recursive: true });
+
+// Where the read-only files that ship with the bot live: views/, public/, the
+// persona template. Normally that is the package itself. A packaged build
+// (a single executable has no package directory) unpacks them somewhere the
+// filesystem can see and points this at that copy instead.
+let assetRoot = ROOT;
+
+function setAssetRoot(dir) {
+  assetRoot = dir;
+}
+
+/** A path to a file that ships with the bot and is never written to. */
+function assetPath(...parts) {
+  return path.join(assetRoot, ...parts);
+}
+
+/** A path inside the data directory. Creates nothing — callers do that. */
+function dataPath(...parts) {
+  return path.join(DATA_DIR, ...parts);
+}
+
+/** Same, but the directory is created first. */
+function ensureDataDir(...parts) {
+  const dir = dataPath(...parts);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+module.exports = {
+  DATA_DIR,
+  PACKAGE_ROOT: ROOT,
+  dataPath,
+  ensureDataDir,
+  assetPath,
+  setAssetRoot,
+};

package/src/config/runtime-config.cjs

@@ -0,0 +1,219 @@
+// The command table, changeable at runtime.
+//
+// src/config/defaults.cjs holds the DEFAULTS that ship with the bot. Whatever
+// the operator changes from the dashboard is stored as an override in the
+// `bot_settings` table and layered on top, so:
+//
+//   * an update that adds a new command still gets its default permission,
+//   * nothing has to rewrite a file that is checked into the repo,
+//   * a change is live on the very next message.
+//
+// Override keys in bot_settings:
+//   prefix               string
+//   command_permissions  { "<command>": "<LEVEL>", "group:<sub>": "<LEVEL>" }
+//   command_aliases      { "<command>": ["alias", ...] }
+//   disabled_commands    ["<command>", ...]
+
+const defaults = require("./defaults.cjs");
+const logger = require("../utils/logger.cjs");
+
+const PERMISSION_LEVELS = Object.freeze([
+  "MEMBERS",
+  "ADMINS_ONLY",
+  "ADMINS_OWNER",
+  "OWNER_ONLY",
+]);
+
+const KEY_PERMISSIONS = "command_permissions";
+const KEY_ALIASES = "command_aliases";
+const KEY_DISABLED = "disabled_commands";
+const KEY_PREFIX = "prefix";
+
+// Lazy require: runtime-config is pulled in by modules that load very early,
+// and this keeps the database open exactly once, from db.cjs.
+function store() {
+  return require("../utils/storage.cjs");
+}
+
+// A read that somehow lands before the database is open falls back to the
+// shipped defaults instead of throwing — the alternative is a boot-order crash
+// for a value we have a perfectly good default for.
+function readSetting(key, fallback) {
+  try {
+    const value = store().getBotSetting(key, undefined);
+    return value === undefined || value === null ? fallback : value;
+  } catch {
+    return fallback;
+  }
+}
+
+function writeSetting(key, value) {
+  store().saveBotSetting(key, value);
+}
+
+function isPlainObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+// --- prefix ---------------------------------------------------------------
+
+function getPrefix() {
+  const value = readSetting(KEY_PREFIX, defaults.prefix || "!");
+  return typeof value === "string" && value.trim() ? value : "!";
+}
+
+/** @throws {Error} when the prefix is empty, too long, or has whitespace. */
+function setPrefix(value) {
+  const prefix = String(value ?? "").trim();
+  if (!prefix) throw new Error("Prefix can't be empty");
+  if (prefix.length > 3) throw new Error("Prefix can't be longer than 3 characters");
+  if (/\s/.test(prefix)) throw new Error("Prefix can't contain whitespace");
+  writeSetting(KEY_PREFIX, prefix);
+  logger.info(`[config] prefix -> ${prefix}`);
+  return prefix;
+}
+
+// --- permissions ----------------------------------------------------------
+
+// Sub-commands of `group` are addressed as "group:kick" so one flat map can
+// hold both levels without nesting.
+function defaultPermission(commandKey) {
+  const [head, sub] = String(commandKey).split(":");
+  const table = defaults.command_permissions || {};
+
+  if (sub) {
+    const groupEntry = table[head];
+    if (isPlainObject(groupEntry)) {
+      return (
+        groupEntry.sub_commands?.[sub] ||
+        groupEntry.default_permission ||
+        "MEMBERS"
+      );
+    }
+    return "MEMBERS";
+  }
+
+  const entry = table[head];
+  if (typeof entry === "string") return entry;
+  if (isPlainObject(entry)) return entry.default_permission || "MEMBERS";
+  return "MEMBERS";
+}
+
+function permissionOverrides() {
+  const raw = readSetting(KEY_PERMISSIONS, {});
+  return isPlainObject(raw) ? raw : {};
+}
+
+function getPermission(commandKey) {
+  const override = permissionOverrides()[commandKey];
+  if (typeof override === "string" && PERMISSION_LEVELS.includes(override)) {
+    return override;
+  }
+  return defaultPermission(commandKey);
+}
+
+/**
+ * Set (or clear, with `level === null`) the permission of one command.
+ * @throws {Error} on an unknown level.
+ */
+function setPermission(commandKey, level) {
+  const overrides = { ...permissionOverrides() };
+
+  if (level === null || level === undefined || level === "") {
+    delete overrides[commandKey];
+  } else {
+    if (!PERMISSION_LEVELS.includes(level)) {
+      throw new Error(`Unknown permission level: ${level}`);
+    }
+    // Storing a value identical to the default would pin the command to
+    // today's default forever; drop it instead so it keeps following defaults.cjs.
+    if (level === defaultPermission(commandKey)) delete overrides[commandKey];
+    else overrides[commandKey] = level;
+  }
+
+  writeSetting(KEY_PERMISSIONS, overrides);
+  logger.info(`[config] permission ${commandKey} -> ${level || "(default)"}`);
+  return getPermission(commandKey);
+}
+
+// --- aliases --------------------------------------------------------------
+
+function aliasOverrides() {
+  const raw = readSetting(KEY_ALIASES, {});
+  return isPlainObject(raw) ? raw : {};
+}
+
+/** The effective aliases: the override if there is one, else what the command file declares. */
+function getAliases(commandName, declared = []) {
+  const override = aliasOverrides()[commandName];
+  return Array.isArray(override) ? override : declared;
+}
+
+function hasAliasOverride(commandName) {
+  return Array.isArray(aliasOverrides()[commandName]);
+}
+
+/**
+ * Replace a command's aliases. `null` restores whatever the command file declares.
+ * @throws {Error} on a malformed alias.
+ */
+function setAliases(commandName, aliases) {
+  const overrides = { ...aliasOverrides() };
+
+  if (aliases === null || aliases === undefined) {
+    delete overrides[commandName];
+  } else {
+    if (!Array.isArray(aliases)) throw new Error("Aliases must be a list");
+    const cleaned = [];
+    for (const raw of aliases) {
+      const alias = String(raw ?? "").trim().toLowerCase();
+      if (!alias) continue;
+      if (/\s/.test(alias)) throw new Error(`Alias "${alias}" can't contain spaces`);
+      if (alias.length > 20) throw new Error(`Alias "${alias}" is too long`);
+      if (!cleaned.includes(alias)) cleaned.push(alias);
+    }
+    if (cleaned.length > 10) throw new Error("At most 10 aliases per command");
+    overrides[commandName] = cleaned;
+  }
+
+  writeSetting(KEY_ALIASES, overrides);
+  logger.info(`[config] aliases ${commandName} -> ${JSON.stringify(overrides[commandName] ?? "(default)")}`);
+  return getAliases(commandName);
+}
+
+// --- enable / disable -----------------------------------------------------
+
+function disabledCommands() {
+  const raw = readSetting(KEY_DISABLED, []);
+  return Array.isArray(raw) ? raw.map(String) : [];
+}
+
+function isDisabled(commandName) {
+  return disabledCommands().includes(commandName);
+}
+
+function setEnabled(commandName, enabled) {
+  const current = new Set(disabledCommands());
+  if (enabled) current.delete(commandName);
+  else current.add(commandName);
+  writeSetting(KEY_DISABLED, [...current]);
+  logger.info(`[config] command ${commandName} -> ${enabled ? "enabled" : "disabled"}`);
+  return !current.has(commandName);
+}
+
+module.exports = {
+  PERMISSION_LEVELS,
+  getPrefix,
+  setPrefix,
+  defaultPermission,
+  permissionOverrides,
+  getPermission,
+  setPermission,
+  aliasOverrides,
+  getAliases,
+  hasAliasOverride,
+  setAliases,
+  disabledCommands,
+  isDisabled,
+  setEnabled,
+};

package/src/config/secrets.cjs

@@ -0,0 +1,130 @@
+// Secrets, generated rather than configured.
+//
+// There is no .env file. Anything that used to be a secret an operator had to
+// invent and paste — the session signing key, the dashboard password — is
+// either generated here on first start or set once from the browser.
+//
+// What is stored, and how:
+//
+//   secret:session   the express-session signing key. 48 random bytes, made on
+//                    first start and reused forever after. Nobody ever sees it.
+//   auth:password    the dashboard password as an scrypt hash + salt. The
+//                    password itself is never written anywhere.
+//
+// Both live in `bot_settings`, i.e. inside the same SQLite file as the rest of
+// the bot's state — so a backup of that one file is a backup of the login too.
+
+const crypto = require("node:crypto");
+
+const store = require("../db/store.cjs");
+const logger = require("../utils/logger.cjs");
+
+const SESSION_KEY = "secret:session";
+const PASSWORD_KEY = "auth:password";
+
+const MIN_PASSWORD_LENGTH = 8;
+const SCRYPT_KEYLEN = 64;
+
+// ===================================================================
+// --- Session signing key ---
+// ===================================================================
+
+/**
+ * The express-session secret. Generated on first call and persisted, so
+ * sessions survive a restart but nothing has to be configured by hand.
+ */
+function getSessionSecret() {
+  const existing = store.getBotSetting(SESSION_KEY, null);
+  if (typeof existing === "string" && existing.length >= 32) return existing;
+
+  const generated = crypto.randomBytes(48).toString("hex");
+  store.saveBotSetting(SESSION_KEY, generated);
+  logger.info("[secrets] Generated a new session signing key");
+  return generated;
+}
+
+// ===================================================================
+// --- Dashboard password ---
+// ===================================================================
+
+function hashPassword(plain, salt = crypto.randomBytes(16)) {
+  const hash = crypto.scryptSync(String(plain), salt, SCRYPT_KEYLEN);
+  return { salt: salt.toString("hex"), hash: hash.toString("hex") };
+}
+
+function hasDashboardPassword() {
+  const record = store.getBotSetting(PASSWORD_KEY, null);
+  return !!(record && record.hash && record.salt);
+}
+
+/**
+ * @throws {Error} when the password is too short — the dashboard holds a full
+ *   WhatsApp account, so this is not a place for a 3-character password.
+ */
+function setDashboardPassword(plain) {
+  const password = String(plain ?? "");
+  if (password.length < MIN_PASSWORD_LENGTH) {
+    throw new Error(
+      `Password must be at least ${MIN_PASSWORD_LENGTH} characters`
+    );
+  }
+
+  const { salt, hash } = hashPassword(password);
+  store.saveBotSetting(PASSWORD_KEY, { alg: "scrypt", salt, hash, updatedAt: Date.now() });
+  logger.info("[secrets] Dashboard password updated");
+}
+
+/** Constant-time check. False (never a throw) when no password is set yet. */
+function verifyDashboardPassword(candidate) {
+  const record = store.getBotSetting(PASSWORD_KEY, null);
+  if (!record?.hash || !record?.salt) return false;
+  if (typeof candidate !== "string") return false;
+
+  const expected = Buffer.from(record.hash, "hex");
+  const actual = crypto.scryptSync(
+    candidate,
+    Buffer.from(record.salt, "hex"),
+    expected.length
+  );
+  return crypto.timingSafeEqual(expected, actual);
+}
+
+// ===================================================================
+// --- First-run setup code ---
+// ===================================================================
+//
+// Until a password exists the dashboard shows a "choose your password" page.
+// From localhost that is all it asks — whoever is at the machine is the
+// operator. From anywhere else it also asks for this code, which is printed in
+// the terminal at startup, so a bot that comes up on a public IP can't be
+// claimed by the first stranger who finds the port.
+//
+// It is generated per process and never stored: restart the bot and you get a
+// new one.
+
+let setupCode = null;
+
+function getSetupCode() {
+  if (!setupCode) {
+    setupCode = crypto.randomBytes(4).toString("hex").toUpperCase();
+  }
+  return setupCode;
+}
+
+function setupCodeMatches(candidate) {
+  if (typeof candidate !== "string") return false;
+  const expected = Buffer.from(getSetupCode());
+  const actual = Buffer.from(candidate.trim().toUpperCase());
+  if (expected.length !== actual.length) return false;
+  return crypto.timingSafeEqual(expected, actual);
+}
+
+module.exports = {
+  MIN_PASSWORD_LENGTH,
+  getSessionSecret,
+  hasDashboardPassword,
+  setDashboardPassword,
+  verifyDashboardPassword,
+  getSetupCode,
+  setupCodeMatches,
+};