alvin-bot 4.20.0 → 4.20.2

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.20.2] — 2026-05-04
+
+### 🛡️ Security: Web UI loopback by default + Slack caller allowlist
+
+Two real attack surfaces closed.
+
+**Web UI binds to 127.0.0.1 by default.** Previous versions called `server.listen(port)` with no host argument, which Node interprets as "listen on all interfaces". Combined with an empty `WEB_PASSWORD` (which the login route silently treats as "anyone can log in"), this meant any device on the same LAN could log into the bot's Web UI and reach every authenticated endpoint — user list, memory contents, model switch, the WebSocket chat, etc. New default: bind to `127.0.0.1`. To restore LAN access, set `WEB_HOST=0.0.0.0` explicitly in `.env`. If both `WEB_HOST=0.0.0.0` and an empty `WEB_PASSWORD` are present, the bot logs a loud warning on startup.
+
+**Slack caller allowlist.** New `SLACK_ALLOWED_USERS` env var: comma-separated list of Slack user IDs allowed to talk to the bot (DMs, @mentions, slash commands). Empty list keeps the legacy behaviour — any workspace member can interact, which is safe iff the workspace is private to the operator. To find your Slack user ID: open your profile in Slack → "..." → "Copy member ID", or just message the bot once and read the line `[slack] caller discovered: user=U… — to lock the bot to specific users, add to .env: SLACK_ALLOWED_USERS=U…` from the logs (we log each unique caller once when the allowlist is empty).
+
+**`alvin-bot doctor` now reports both.** New `Web UI:` and `Slack:` sections flag insecure combos and show whether an allowlist is active.
+
+No schema or behaviour changes for users who already have `WEB_PASSWORD` set or only use the bot via Telegram. Telegram allowlist (`ALLOWED_USERS`) is unchanged.
+
+## [4.20.1] — 2026-05-03
+
+### 🛡️ Hardening for the v4.20.0 SQLite migration
+
+The v4.20 migration is fully automatic on first start, but a few things could go wrong on user installations that the maintainer instance never hits. v4.20.1 plugs each of them.
+
+- **Lazy native binary load.** `better-sqlite3` is now `require()`-d inside `embeddings.ts`, not at module import time. If the prebuilt isn't available for the user's platform and a build-from-source fails (exotic Node version, missing toolchain, glibc mismatch), the bot logs a single clear warning with the exact rebuild command, and **keeps running** — only semantic memory search is disabled until the user fixes their install. Previously this would have crashed bot startup.
+- **Pre-flight disk-space check.** Migration refuses to start unless the volume holding `~/.alvin-bot/memory/` has at least 2× the source JSON's size free (covers source + target + WAL during the transaction). Skipped migration leaves the JSON intact for retry on the next boot once space is free.
+- **Progress logging.** On indexes larger than ~5 000 entries, the migration logs `…migrated N / M entries (P %)` every 5 000 rows so the user can see it isn't stuck.
+- **Corrupt JSON recovery.** If `JSON.parse` of `.embeddings.json` throws, the file is moved aside to `.embeddings.json.broken.<timestamp>` and the next bot start treats this as a fresh install (rebuild-from-source on first search). No more boot-loop on a damaged index.
+- **`alvin-bot doctor` shows memory health.** New "Memory:" section reports: native binary loadable, vector-store entry count + size, or — for not-yet-migrated installs — the legacy JSON's size and a hint that the next start will migrate.
+- **Cleanup on failed migration.** WAL/SHM sidecars are removed alongside the half-written `.embeddings.db` so the next attempt starts from a clean slate.
+
+No schema or API changes — drop-in over v4.20.0.
+
 ## [4.20.0] — 2026-05-03
 
 ### 🚀 Embeddings: JSON → SQLite

package/bin/cli.js

@@ -17,7 +17,7 @@
  */
 
 import { createInterface } from "readline";
-import { existsSync, writeFileSync, readFileSync, mkdirSync, copyFileSync, readdirSync } from "fs";
+import { existsSync, writeFileSync, readFileSync, mkdirSync, copyFileSync, readdirSync, statSync } from "fs";
 import { resolve, join } from "path";
 import { homedir } from "os";
 import { execSync } from "child_process";
@@ -1361,6 +1361,83 @@ async function doctor() {
     console.log(`  ❌ ALLOWED_USERS not set (nobody can message the bot)`);
   }
 
+  // ── Web UI security ──
+  console.log("\n  Web UI:");
+  const webHost = getEnv("WEB_HOST") || "127.0.0.1";
+  const webPw = getEnv("WEB_PASSWORD");
+  if (webHost === "127.0.0.1" || webHost === "::1") {
+    console.log(`  ✅ WEB_HOST=${webHost} — loopback only (LAN unreachable)`);
+  } else if (webHost === "0.0.0.0" || webHost === "*") {
+    if (webPw) {
+      console.log(`  ✅ WEB_HOST=${webHost} (LAN-reachable) + WEB_PASSWORD set`);
+    } else {
+      console.log(`  ❌ WEB_HOST=${webHost} (LAN-reachable) WITHOUT WEB_PASSWORD — anyone on LAN can log in`);
+      console.log(`     Fix: set WEB_PASSWORD in .env, or set WEB_HOST=127.0.0.1`);
+    }
+  } else {
+    console.log(`  ℹ️  WEB_HOST=${webHost}${webPw ? " + WEB_PASSWORD set" : " — WEB_PASSWORD empty"}`);
+  }
+
+  // ── Slack caller allowlist ──
+  if (getEnv("SLACK_BOT_TOKEN")) {
+    console.log("\n  Slack:");
+    const slackAllow = getEnv("SLACK_ALLOWED_USERS");
+    if (slackAllow) {
+      const ids = slackAllow.split(",").map(s => s.trim()).filter(Boolean);
+      console.log(`  ✅ SLACK_ALLOWED_USERS: ${ids.length} user${ids.length === 1 ? "" : "s"} (caller allowlist active)`);
+    } else {
+      console.log(`  ⚠️  SLACK_ALLOWED_USERS not set — any workspace member can talk to the bot`);
+      console.log(`     Safe iff the Slack workspace is private to you. Otherwise add e.g.:`);
+      console.log(`     SLACK_ALLOWED_USERS=U0ABC123,U0DEF456`);
+    }
+  }
+
+  // ── Memory (semantic search backend) ──
+  console.log("\n  Memory:");
+  const embJson = resolve(DATA_DIR, "memory", ".embeddings.json");
+  const embDb = resolve(DATA_DIR, "memory", ".embeddings.db");
+  const embBakSqlite = resolve(DATA_DIR, "memory", ".embeddings.json.bak-pre-sqlite");
+
+  // better-sqlite3 native binary loadable?
+  let sqliteOk = false;
+  let sqliteErr = "";
+  try {
+    const req = (await import("module")).createRequire(import.meta.url);
+    req("better-sqlite3");
+    sqliteOk = true;
+  } catch (err) {
+    sqliteErr = err instanceof Error ? err.message : String(err);
+  }
+  if (sqliteOk) {
+    console.log(`  ✅ better-sqlite3 native binary loadable`);
+  } else {
+    console.log(`  ❌ better-sqlite3 native binary not loadable — semantic search disabled`);
+    console.log(`     Fix: cd $(npm root -g)/alvin-bot && npm rebuild better-sqlite3`);
+    console.log(`     Detail: ${sqliteErr.split("\n")[0]}`);
+  }
+
+  if (sqliteOk && existsSync(embDb)) {
+    try {
+      const req = (await import("module")).createRequire(import.meta.url);
+      const Database = req("better-sqlite3");
+      const db = new Database(embDb, { readonly: true });
+      const entries = db.prepare("SELECT COUNT(*) AS c FROM entries").get().c;
+      const files = db.prepare("SELECT COUNT(*) AS c FROM file_mtimes").get().c;
+      const sizeMb = (statSync(embDb).size / 1024 / 1024).toFixed(0);
+      db.close();
+      console.log(`  ✅ Vector store: ${entries} entries across ${files} sources (${sizeMb} MB SQLite)`);
+    } catch (err) {
+      console.log(`  ⚠️  Vector store exists but unreadable: ${err.message}`);
+    }
+  } else if (existsSync(embJson)) {
+    const sizeMb = (statSync(embJson).size / 1024 / 1024).toFixed(0);
+    console.log(`  ⚠️  Legacy JSON index found (${sizeMb} MB) — will auto-migrate to SQLite on next bot start`);
+  } else if (existsSync(embBakSqlite)) {
+    console.log(`  ✅ Migration to SQLite already done (legacy JSON kept as .bak-pre-sqlite)`);
+  } else {
+    console.log(`  ℹ️  No vector store yet — will be built on first message`);
+  }
+
   // ── Extras ──
   console.log("\n  Extras:");
 

package/dist/config.js

@@ -63,6 +63,20 @@ export const config = {
     sessionMode: (process.env.SESSION_MODE || "per-user"),
     webhookEnabled: process.env.WEBHOOK_ENABLED === "true",
     webhookToken: process.env.WEBHOOK_TOKEN || "",
+    // Web UI bind host. Default is 127.0.0.1 (loopback only) — set to "0.0.0.0"
+    // explicitly if you want LAN/external access. Combined with WEB_PASSWORD
+    // this is the safe default since v4.20.2; previous versions defaulted to
+    // listening on all interfaces with no auth required when WEB_PASSWORD was
+    // empty.
+    webHost: process.env.WEB_HOST || "127.0.0.1",
+    // Slack caller allowlist. Comma-separated Slack user IDs (e.g. "U0ABC123,U0DEF456").
+    // When non-empty, only these users can talk to the bot in Slack DMs and via @mention.
+    // When empty, the bot accepts any Slack workspace member (legacy behavior; safe iff
+    // the workspace is private to you).
+    slackAllowedUsers: (process.env.SLACK_ALLOWED_USERS || "")
+        .split(",")
+        .map(s => s.trim())
+        .filter(Boolean),
     // Browser
     cdpUrl: process.env.CDP_URL || "",
     browseServerPort: Number(process.env.BROWSE_SERVER_PORT) || 3800,

package/dist/platforms/slack.js

@@ -18,6 +18,32 @@
  */
 import fs from "fs";
 import { parseSlackSlashCommand } from "./slack-slash-parser.js";
+import { config } from "../config.js";
+/**
+ * v4.20.2 — Slack caller allowlist. When SLACK_ALLOWED_USERS is set in the
+ * environment (comma-separated Slack user IDs), only those users get past
+ * this gate. When the list is empty, fall back to legacy behaviour: any
+ * member of the workspace can talk to the bot. The empty-list case is safe
+ * iff the workspace is private to the operator.
+ *
+ * Slack user IDs are workspace-scoped (e.g. "U0ABC123"); rotate the list if
+ * you migrate workspaces.
+ */
+function isSlackUserAllowed(userId) {
+    if (config.slackAllowedUsers.length === 0) {
+        // No allowlist set — log each unique caller once so the operator can
+        // copy a known ID into SLACK_ALLOWED_USERS and lock the bot down.
+        if (userId && !discoveredCallers.has(userId)) {
+            discoveredCallers.add(userId);
+            console.warn(`[slack] caller discovered: user=${userId} — to lock the bot to specific users, ` +
+                `add to .env: SLACK_ALLOWED_USERS=${userId}` +
+                (discoveredCallers.size > 1 ? ` (or comma-separate multiple)` : ""));
+        }
+        return true;
+    }
+    return config.slackAllowedUsers.includes(userId);
+}
+const discoveredCallers = new Set();
 let _slackState = {
     status: "disconnected",
     botName: null,
@@ -148,6 +174,13 @@ export class SlackAdapter {
         const userId = message.user || "";
         const channelId = message.channel || "";
         const messageId = message.ts || "";
+        // v4.20.2 — caller allowlist. If SLACK_ALLOWED_USERS is set, silently
+        // ignore anyone not on the list. Empty list = legacy behaviour
+        // (any workspace member can talk to the bot — safe iff the workspace
+        // is private to the operator).
+        if (!isSlackUserAllowed(userId)) {
+            return;
+        }
         // Determine channel type
         // DMs (im) have channel_type "im", group DMs are "mpim", channels are "channel"/"group"
         const channelType = message.channel_type || "";
@@ -222,6 +255,10 @@ export class SlackAdapter {
         const channelId = command.channel_id || "";
         const userId = command.user_id || "";
         const userName = command.user_name || userId;
+        // v4.20.2 — caller allowlist for slash commands.
+        if (!isSlackUserAllowed(userId)) {
+            return;
+        }
         const incoming = {
             platform: "slack",
             messageId: `cmd-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
@@ -247,6 +284,10 @@ export class SlackAdapter {
         const userId = event.user || "";
         const channelId = event.channel || "";
         const messageId = event.ts || "";
+        // v4.20.2 — same caller allowlist as DMs.
+        if (!isSlackUserAllowed(userId)) {
+            return;
+        }
         // Strip the @mention from text
         text = text.replace(new RegExp(`<@${this.botUserId}>`, "g"), "").trim();
         if (!text)

package/dist/services/embeddings-migration.js

@@ -4,15 +4,25 @@
  * Triggered on startup if .embeddings.json exists but .embeddings.db does not.
  * Idempotent: skips silently if the DB is already populated.
  *
+ * Hardening (v4.20.1):
+ *  - Lazy require of better-sqlite3 — missing native binary degrades to a clear
+ *    warning + skip (bot keeps running, falls back to legacy JSON path until
+ *    the user fixes their install).
+ *  - Pre-flight disk-space check: refuses to start if free space < 2× source.
+ *  - Progress logging every 1 000 entries on large indexes.
+ *  - Corrupt source JSON is renamed to `.broken.<timestamp>` so the next run
+ *    doesn't loop on the same parse error.
+ *
  * Safety:
  *  - Source JSON is renamed to .embeddings.json.bak-pre-sqlite (kept on disk).
- *  - Entry counts are compared after import; mismatch → throw, leaving the bak
- *    file in place for manual recovery.
+ *  - Entry counts are compared after import; mismatch → throw, leaving the
+ *    half-written DB removed and the source JSON untouched.
  */
 import fs from "fs";
 import path from "path";
-import Database from "better-sqlite3";
+import { createRequire } from "module";
 import { EMBEDDINGS_IDX, EMBEDDINGS_DB } from "../paths.js";
+const cjsRequire = createRequire(import.meta.url);
 function vectorToBlob(v) {
     const f32 = new Float32Array(v);
     return Buffer.from(f32.buffer, f32.byteOffset, f32.byteLength);
@@ -20,14 +30,58 @@ function vectorToBlob(v) {
 export function shouldMigrateEmbeddingsToSqlite() {
     return fs.existsSync(EMBEDDINGS_IDX) && !fs.existsSync(EMBEDDINGS_DB);
 }
+/**
+ * Best-effort free-space probe. Returns Infinity if the platform has no
+ * statfs (which means we'll proceed without the safety check rather than
+ * blocking the migration). Node 18.15+ ships statfsSync on all major platforms.
+ */
+function freeBytesOnVolume(forPath) {
+    try {
+        const fsAny = fs;
+        if (typeof fsAny.statfsSync !== "function")
+            return Number.POSITIVE_INFINITY;
+        const stat = fsAny.statfsSync(forPath);
+        const bavail = typeof stat.bavail === "bigint" ? Number(stat.bavail) : stat.bavail;
+        const bsize = typeof stat.bsize === "bigint" ? Number(stat.bsize) : stat.bsize;
+        return bavail * bsize;
+    }
+    catch {
+        return Number.POSITIVE_INFINITY;
+    }
+}
 /**
  * Run the migration. Returns the entry count migrated, or null if skipped.
  */
 export function migrateEmbeddingsToSqlite() {
     if (!shouldMigrateEmbeddingsToSqlite())
         return null;
-    const t0 = Date.now();
+    // ── Pre-flight: better-sqlite3 loadable? ───────────────────────────────────
+    let Database;
+    try {
+        Database = cjsRequire("better-sqlite3");
+    }
+    catch (err) {
+        console.warn("⚠️ Embeddings migration skipped: better-sqlite3 native binary unavailable. " +
+            "Bot continues with legacy JSON index. Fix: `npm rebuild better-sqlite3` " +
+            "or reinstall alvin-bot. Underlying error:", err instanceof Error ? err.message : err);
+        return null;
+    }
     const sourceSize = fs.statSync(EMBEDDINGS_IDX).size;
+    // ── Pre-flight: enough free space? ─────────────────────────────────────────
+    const targetDir = path.dirname(EMBEDDINGS_DB);
+    fs.mkdirSync(targetDir, { recursive: true });
+    const free = freeBytesOnVolume(targetDir);
+    // We need source + about half of source for the SQLite file, plus headroom
+    // for WAL during the transaction. Demand 2× source size to be comfortable.
+    const required = sourceSize * 2;
+    if (free < required) {
+        console.warn(`⚠️ Embeddings migration skipped: insufficient free disk space on ${targetDir}. ` +
+            `Need ~${(required / 1024 / 1024).toFixed(0)} MB, have ${(free / 1024 / 1024).toFixed(0)} MB. ` +
+            `Free up some space and restart the bot to retry.`);
+        return null;
+    }
+    // ── Read & parse source ────────────────────────────────────────────────────
+    const t0 = Date.now();
     console.log(`📦 Migrating embeddings JSON (${(sourceSize / 1024 / 1024).toFixed(0)} MB) → SQLite...`);
     const raw = fs.readFileSync(EMBEDDINGS_IDX, "utf-8");
     let legacy;
@@ -35,10 +89,21 @@ export function migrateEmbeddingsToSqlite() {
         legacy = JSON.parse(raw);
     }
     catch (err) {
-        console.error("⚠️ Embeddings migration: source JSON is corrupt — skipping.", err);
+        // Move the broken JSON aside so we don't try to migrate it again next boot.
+        const broken = `${EMBEDDINGS_IDX}.broken.${Date.now()}`;
+        try {
+            fs.renameSync(EMBEDDINGS_IDX, broken);
+            console.error(`❌ Embeddings migration: source JSON is corrupt — renamed to ${path.basename(broken)} ` +
+                `and skipped. The bot will rebuild the index from scratch on first search ` +
+                `(this may incur Google API calls). Underlying parse error:`, err);
+        }
+        catch (renameErr) {
+            console.error("❌ Embeddings migration: source JSON is corrupt AND could not be renamed:", err, "Rename error:", renameErr);
+        }
         return null;
     }
-    fs.mkdirSync(path.dirname(EMBEDDINGS_DB), { recursive: true });
+    const validEntries = (legacy.entries ?? []).filter(e => Array.isArray(e.vector) && e.vector.length > 0);
+    // ── Write DB ───────────────────────────────────────────────────────────────
     const db = new Database(EMBEDDINGS_DB);
     try {
         db.pragma("journal_mode = WAL");
@@ -62,9 +127,9 @@ export function migrateEmbeddingsToSqlite() {
       CREATE INDEX IF NOT EXISTS idx_entries_source ON entries(source);
     `);
         const setMeta = db.prepare("INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value");
-        setMeta.run("model", legacy.model);
+        setMeta.run("model", legacy.model || "gemini-embedding-001");
         setMeta.run("schemaVersion", "1");
-        setMeta.run("lastReindex", String(legacy.lastReindex));
+        setMeta.run("lastReindex", String(legacy.lastReindex || 0));
         setMeta.run("migratedFromJson", String(Date.now()));
         const insMtime = db.prepare("INSERT INTO file_mtimes (source, mtime_ms) VALUES (?, ?) ON CONFLICT(source) DO UPDATE SET mtime_ms = excluded.mtime_ms");
         const writeMtimes = db.transaction((rows) => {
@@ -73,38 +138,52 @@ export function migrateEmbeddingsToSqlite() {
         });
         writeMtimes(Object.entries(legacy.fileMtimes ?? {}));
         const insEntry = db.prepare("INSERT INTO entries (id, source, text, vector, indexed_at) VALUES (?, ?, ?, ?, ?)");
-        const writeEntries = db.transaction((rows) => {
+        // Write entries in chunks of 1 000 so we can log progress on huge indexes.
+        const CHUNK = 1000;
+        const total = validEntries.length;
+        let written = 0;
+        const writeChunk = db.transaction((rows) => {
             for (const e of rows) {
-                if (!Array.isArray(e.vector) || e.vector.length === 0)
-                    continue;
                 insEntry.run(e.id, e.source, e.text, vectorToBlob(e.vector), e.indexedAt);
             }
         });
-        writeEntries(legacy.entries ?? []);
-        const written = db.prepare("SELECT COUNT(*) AS c FROM entries").get().c;
-        const expected = (legacy.entries ?? []).filter(e => Array.isArray(e.vector) && e.vector.length > 0).length;
-        if (written !== expected) {
-            throw new Error(`Entry-count mismatch after migration: expected ${expected}, got ${written}`);
+        for (let i = 0; i < total; i += CHUNK) {
+            const slice = validEntries.slice(i, i + CHUNK);
+            writeChunk(slice);
+            written += slice.length;
+            if (total > 5000 && (written === total || written % 5000 === 0)) {
+                console.log(`   …migrated ${written} / ${total} entries (${Math.round((written / total) * 100)} %)`);
+            }
+        }
+        const writtenCount = db.prepare("SELECT COUNT(*) AS c FROM entries").get().c;
+        if (writtenCount !== validEntries.length) {
+            throw new Error(`Entry-count mismatch after migration: expected ${validEntries.length}, got ${writtenCount}`);
         }
         db.close();
-        // Move source JSON aside so we never re-migrate.
+        // ── Move source JSON aside so we never re-migrate ────────────────────────
         const bak = `${EMBEDDINGS_IDX}.bak-pre-sqlite`;
         try {
             fs.renameSync(EMBEDDINGS_IDX, bak);
         }
         catch (err) {
-            console.warn("⚠️ Could not rename source JSON:", err);
+            console.warn("⚠️ Could not rename source JSON (migration still succeeded):", err);
         }
         const targetSize = fs.statSync(EMBEDDINGS_DB).size;
         const dt = Date.now() - t0;
-        console.log(`✅ Embeddings migrated: ${written} entries, ${(sourceSize / 1024 / 1024).toFixed(0)} MB JSON → ${(targetSize / 1024 / 1024).toFixed(0)} MB SQLite in ${dt} ms`);
-        return { entries: written, sourceMb: sourceSize / 1024 / 1024, targetMb: targetSize / 1024 / 1024 };
+        console.log(`✅ Embeddings migrated: ${writtenCount} entries, ${(sourceSize / 1024 / 1024).toFixed(0)} MB JSON → ${(targetSize / 1024 / 1024).toFixed(0)} MB SQLite in ${dt} ms`);
+        return { entries: writtenCount, sourceMb: sourceSize / 1024 / 1024, targetMb: targetSize / 1024 / 1024 };
     }
     catch (err) {
         db.close();
-        // Remove half-written DB so the next boot retries cleanly.
+        // Remove half-written DB so the next boot retries cleanly with the original JSON intact.
         try {
             fs.unlinkSync(EMBEDDINGS_DB);
+            // also unlink WAL/SHM if present
+            for (const ext of ["-wal", "-shm"]) {
+                const p = `${EMBEDDINGS_DB}${ext}`;
+                if (fs.existsSync(p))
+                    fs.unlinkSync(p);
+            }
         }
         catch {
             /* nothing to clean */

package/dist/services/embeddings.js

@@ -19,10 +19,36 @@ import fs from "fs";
 import path from "path";
 import { resolve } from "path";
 import os from "os";
-import Database from "better-sqlite3";
+import { createRequire } from "module";
 import { config } from "../config.js";
 import { MEMORY_DIR, MEMORY_FILE, EMBEDDINGS_DB } from "../paths.js";
 import { ASSETS_DIR, ASSETS_INDEX_MD } from "../paths.js";
+let SqliteClass = null;
+let sqliteLoadAttempted = false;
+let sqliteLoadError = null;
+const cjsRequire = createRequire(import.meta.url);
+function loadSqlite() {
+    if (sqliteLoadAttempted)
+        return SqliteClass;
+    sqliteLoadAttempted = true;
+    try {
+        SqliteClass = cjsRequire("better-sqlite3");
+        return SqliteClass;
+    }
+    catch (err) {
+        sqliteLoadError = err instanceof Error ? err : new Error(String(err));
+        console.warn("⚠️ better-sqlite3 native binary unavailable — embeddings disabled. " +
+            "Bot continues without semantic memory search. Fix: rebuild deps with " +
+            "`cd $(npm root -g)/alvin-bot && npm rebuild better-sqlite3` or reinstall " +
+            "alvin-bot. Underlying error: " +
+            sqliteLoadError.message);
+        return null;
+    }
+}
+export function getEmbeddingsBackendStatus() {
+    loadSqlite();
+    return { available: SqliteClass !== null, error: sqliteLoadError?.message ?? null };
+}
 // Hub memory directory (Claude Hub — read-only, additional context)
 const HUB_MEMORY_DIR = resolve(os.homedir(), ".claude", "hub", "MEMORY");
 // ── Constants ───────────────────────────────────────────
@@ -47,9 +73,16 @@ function blobToVector(b) {
 }
 // ── DB lifecycle ────────────────────────────────────────
 let dbInstance = null;
+/**
+ * Returns the live DB handle, or null when better-sqlite3 isn't loadable.
+ * Callers must handle the null case (treat as "search unavailable").
+ */
 function db() {
     if (dbInstance)
         return dbInstance;
+    const Database = loadSqlite();
+    if (!Database)
+        return null;
     // Ensure directory exists (handles fresh installs).
     fs.mkdirSync(path.dirname(EMBEDDINGS_DB), { recursive: true });
     dbInstance = new Database(EMBEDDINGS_DB);
@@ -88,25 +121,35 @@ export function closeEmbeddingsDb() {
         dbInstance = null;
     }
 }
+/** Sharper assertion for use inside helpers that require an open DB. */
+function dbOrThrow() {
+    const d = db();
+    if (!d) {
+        throw new Error("Embeddings DB unavailable — better-sqlite3 native module not loaded");
+    }
+    return d;
+}
 // ── Meta helpers ────────────────────────────────────────
 function getMeta(key) {
-    const row = db().prepare("SELECT value FROM meta WHERE key = ?").get(key);
+    const row = dbOrThrow().prepare("SELECT value FROM meta WHERE key = ?").get(key);
     return row?.value ?? null;
 }
 function setMeta(key, value) {
-    db()
+    dbOrThrow()
         .prepare("INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value")
         .run(key, value);
 }
 function getFileMtimes() {
-    const rows = db().prepare("SELECT source, mtime_ms FROM file_mtimes").all();
+    const rows = dbOrThrow()
+        .prepare("SELECT source, mtime_ms FROM file_mtimes")
+        .all();
     const out = {};
     for (const r of rows)
         out[r.source] = r.mtime_ms;
     return out;
 }
 function setFileMtime(source, mtimeMs) {
-    db()
+    dbOrThrow()
         .prepare("INSERT INTO file_mtimes (source, mtime_ms) VALUES (?, ?) ON CONFLICT(source) DO UPDATE SET mtime_ms = excluded.mtime_ms")
         .run(source, mtimeMs);
 }
@@ -310,14 +353,17 @@ function getStaleFiles() {
 }
 // ── Public API ──────────────────────────────────────────
 export async function reindexMemory(force = false) {
+    if (!loadSqlite()) {
+        return { indexed: 0, total: 0 };
+    }
     const filesToIndex = force ? getIndexableFiles() : getStaleFiles();
     if (filesToIndex.length === 0) {
-        const total = db().prepare("SELECT COUNT(*) AS c FROM entries").get().c;
+        const total = dbOrThrow().prepare("SELECT COUNT(*) AS c FROM entries").get().c;
         return { indexed: 0, total };
     }
     // Drop existing entries for files being reindexed (per-source DELETE is O(log n) thanks to idx).
-    const delStmt = db().prepare("DELETE FROM entries WHERE source = ?");
-    const dropOld = db().transaction((sources) => {
+    const delStmt = dbOrThrow().prepare("DELETE FROM entries WHERE source = ?");
+    const dropOld = dbOrThrow().transaction((sources) => {
         for (const s of sources)
             delStmt.run(s);
     });
@@ -339,7 +385,7 @@ export async function reindexMemory(force = false) {
     }
     if (allChunks.length === 0) {
         // Even with zero chunks, keep mtimes in sync so we don't re-walk on next run.
-        const updMtime = db().transaction((files) => {
+        const updMtime = dbOrThrow().transaction((files) => {
             for (const f of files) {
                 try {
                     setFileMtime(f.relativePath, fs.statSync(f.path).mtimeMs);
@@ -350,16 +396,16 @@ export async function reindexMemory(force = false) {
             }
         });
         updMtime(filesToIndex);
-        const total = db().prepare("SELECT COUNT(*) AS c FROM entries").get().c;
+        const total = dbOrThrow().prepare("SELECT COUNT(*) AS c FROM entries").get().c;
         return { indexed: 0, total };
     }
     // Get embeddings for all chunks (network).
     const texts = allChunks.map(c => c.text);
     const vectors = await getEmbeddings(texts);
     // Single transaction for all writes.
-    const insertStmt = db().prepare("INSERT INTO entries (id, source, text, vector, indexed_at) VALUES (?, ?, ?, ?, ?) " +
+    const insertStmt = dbOrThrow().prepare("INSERT INTO entries (id, source, text, vector, indexed_at) VALUES (?, ?, ?, ?, ?) " +
         "ON CONFLICT(id) DO UPDATE SET source=excluded.source, text=excluded.text, vector=excluded.vector, indexed_at=excluded.indexed_at");
-    const writeAll = db().transaction((rows) => {
+    const writeAll = dbOrThrow().transaction((rows) => {
         for (const r of rows) {
             insertStmt.run(r.id, r.source, r.text, r.vector, r.indexedAt);
         }
@@ -373,7 +419,7 @@ export async function reindexMemory(force = false) {
         indexedAt: now,
     })));
     // Update mtimes for the files we just (re-)indexed.
-    const updMtime = db().transaction((files) => {
+    const updMtime = dbOrThrow().transaction((files) => {
         for (const f of files) {
             try {
                 setFileMtime(f.relativePath, fs.statSync(f.path).mtimeMs);
@@ -385,20 +431,23 @@ export async function reindexMemory(force = false) {
     });
     updMtime(filesToIndex);
     setMeta("lastReindex", String(now));
-    const total = db().prepare("SELECT COUNT(*) AS c FROM entries").get().c;
+    const total = dbOrThrow().prepare("SELECT COUNT(*) AS c FROM entries").get().c;
     return { indexed: allChunks.length, total };
 }
 export async function searchMemory(query, topK = 5, minScore = 0.3) {
+    if (!loadSqlite()) {
+        return [];
+    }
     // Auto-index if empty.
-    const total = db().prepare("SELECT COUNT(*) AS c FROM entries").get().c;
+    const total = dbOrThrow().prepare("SELECT COUNT(*) AS c FROM entries").get().c;
     if (total === 0) {
         await reindexMemory();
-        const after = db().prepare("SELECT COUNT(*) AS c FROM entries").get().c;
+        const after = dbOrThrow().prepare("SELECT COUNT(*) AS c FROM entries").get().c;
         if (after === 0)
             return [];
     }
     const queryVector = Float32Array.from(await getQueryEmbedding(query));
-    const rows = db().prepare("SELECT id, source, text, vector FROM entries").all();
+    const rows = dbOrThrow().prepare("SELECT id, source, text, vector FROM entries").all();
     const scored = [];
     for (const row of rows) {
         const v = blobToVector(row.vector);
@@ -411,11 +460,14 @@ export async function searchMemory(query, topK = 5, minScore = 0.3) {
     return scored.slice(0, topK);
 }
 export async function initEmbeddings() {
+    if (!loadSqlite()) {
+        return; // already warned via loadSqlite
+    }
     try {
         db(); // Open & migrate schema.
         const stale = getStaleFiles();
         if (stale.length === 0) {
-            const total = db().prepare("SELECT COUNT(*) AS c FROM entries").get().c;
+            const total = dbOrThrow().prepare("SELECT COUNT(*) AS c FROM entries").get().c;
             if (total > 0)
                 return;
         }
@@ -433,9 +485,12 @@ export function getIndexStats() {
     let files = 0;
     let lastReindex = 0;
     let sizeBytes = 0;
+    if (!loadSqlite()) {
+        return { entries, files, lastReindex, sizeBytes };
+    }
     try {
-        entries = db().prepare("SELECT COUNT(*) AS c FROM entries").get().c;
-        files = db().prepare("SELECT COUNT(*) AS c FROM file_mtimes").get().c;
+        entries = dbOrThrow().prepare("SELECT COUNT(*) AS c FROM entries").get().c;
+        files = dbOrThrow().prepare("SELECT COUNT(*) AS c FROM file_mtimes").get().c;
         const meta = getMeta("lastReindex");
         if (meta)
             lastReindex = Number(meta);

package/dist/web/server.js

@@ -1566,7 +1566,11 @@ function scheduleBindAttempt(port, attempt) {
     // invalid backlog, kernel hiccup) can throw synchronously. Catch here
     // so the main routine never crashes during web-UI bind.
     try {
-        server.listen(port, () => {
+        // v4.20.2 — bind to config.webHost (default 127.0.0.1) so the Web UI
+        // is loopback-only unless the operator opts in by setting WEB_HOST=0.0.0.0.
+        // Empty/"*" maps to all interfaces.
+        const bindHost = (config.webHost === "*" || config.webHost === "") ? undefined : config.webHost;
+        server.listen(port, bindHost, () => {
             if (handled)
                 return; // Should be impossible; paranoia.
             handled = true;
@@ -1587,10 +1591,17 @@ function scheduleBindAttempt(port, attempt) {
             server.on("error", (err) => {
                 console.warn(`[web] post-bind server error (ignored): ${err.message}`);
             });
-            console.log(`🌐 Web UI: http://localhost:${actualWebPort}`);
+            const bindLabel = bindHost && bindHost !== "127.0.0.1" && bindHost !== "::1"
+                ? `http://${bindHost}:${actualWebPort}` + (bindHost === "0.0.0.0" ? " (LAN-reachable)" : "")
+                : `http://localhost:${actualWebPort}`;
+            console.log(`🌐 Web UI: ${bindLabel}`);
             if (actualWebPort !== originalPort) {
                 console.log(`   (Port ${originalPort} was busy, using ${actualWebPort} instead)`);
             }
+            if (bindHost === "0.0.0.0" && !process.env.WEB_PASSWORD) {
+                console.warn("⚠️ Web UI is bound to 0.0.0.0 but WEB_PASSWORD is empty — anyone on the LAN can log in. " +
+                    "Set WEB_PASSWORD in ~/.alvin-bot/.env or set WEB_HOST=127.0.0.1.");
+            }
         });
     }
     catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alvin-bot",
-  "version": "4.20.0",
+  "version": "4.20.2",
   "description": "Alvin Bot — Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
   "type": "module",
   "main": "dist/index.js",