ava-engine 0.0.0-stage → 0.2.0

package/lib/cli/setup-server.mjs

@@ -0,0 +1,195 @@
+// `ava-engine setup --web`: the setup wizard as a page in your browser.
+//
+// A small, separate server that runs only during setup:
+//  - listens on 127.0.0.1 only,
+//  - every API call needs the one-time token from the URL the CLI opens,
+//  - rejects requests whose Host isn't localhost (stops DNS-rebinding attacks),
+//  - serves a strict Content-Security-Policy.
+// When you press "Launch", it saves the settings, closes, and the CLI starts Ava.
+
+import http from "node:http";
+import { readFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { CONFIG_FILE, MODELS_DIR, DEFAULT_PORT, readConfig, writeConfig, checkOpenRouterKey, checkElevenLabsKey, portFree, suggestPassword } from "./config.mjs";
+import { buildConfig, validateAnswers, VOICES } from "./apply.mjs";
+import { MODEL_PACKS, installedPacks, fetchPack } from "../fetch-models.mjs";
+import { loadKokoro, kokoroInstalled, KOKORO_SIZE } from "../kokoro-model.mjs";
+
+const PUBLIC = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "public");
+const STATIC = new Map([
+  ["/setup", ["setup.html", "text/html; charset=utf-8"]],
+  ["/setup.js", ["setup.js", "text/javascript; charset=utf-8"]],
+  ["/setup.css", ["setup.css", "text/css; charset=utf-8"]],
+  ["/favicon.svg", ["favicon.svg", "image/svg+xml"]],
+  ["/fonts/inter-var.woff2", ["fonts/inter-var.woff2", "font/woff2"]],
+  ["/fonts/inter-tight-var.woff2", ["fonts/inter-tight-var.woff2", "font/woff2"]],
+  ["/fonts/plex-mono-400.woff2", ["fonts/plex-mono-400.woff2", "font/woff2"]],
+  ["/fonts/plex-mono-500.woff2", ["fonts/plex-mono-500.woff2", "font/woff2"]],
+]);
+const HEADERS = {
+  "X-Content-Type-Options": "nosniff",
+  "Referrer-Policy": "no-referrer",
+  "Cache-Control": "no-store",
+  "Content-Security-Policy": "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self' http://localhost:* http://127.0.0.1:*; frame-ancestors 'none'; base-uri 'none'; form-action 'self'",
+};
+
+const mask = (v) => (v ? `${v.slice(0, 6)}…${v.slice(-4)}` : "");
+
+async function findPort(preferred) {
+  for (let p = preferred; p < preferred + 20; p++) if (await portFree(p, "127.0.0.1")) return p;
+  return 0; // let the OS pick
+}
+
+/**
+ * Run the browser setup. Resolves { start: true, port } once you press Launch.
+ * onReady({ url }) is called when the page is ready to open.
+ */
+export async function runWebSetup({ preferredPort, formPort, onReady } = {}) {
+  process.env.AVA_MODELS_DIR ??= MODELS_DIR; // so Kokoro downloads land in ~/.ava-engine/models
+  const prev = readConfig() || {};
+  const token = randomBytes(24).toString("base64url");
+  const jobs = {}; // id → { label, state: "running" | "done" | "error", pct, error }
+
+  const okToken = (req) => {
+    const t = Buffer.from(String(req.headers["x-setup-token"] || ""));
+    const want = Buffer.from(token);
+    return t.length === want.length && timingSafeEqual(t, want);
+  };
+
+  function startJob(id) {
+    if (jobs[id]?.state === "running" || jobs[id]?.state === "done") return;
+    if (id === "kokoro") {
+      jobs[id] = { label: `Kokoro voice (${KOKORO_SIZE})`, state: "running", pct: 0 };
+      if (kokoroInstalled()) { jobs[id] = { ...jobs[id], state: "done", pct: 100 }; return; }
+      loadKokoro({ onProgress: ({ pct }) => { jobs[id].pct = pct; } })
+        .then(() => { jobs[id].state = "done"; jobs[id].pct = 100; })
+        .catch((e) => { jobs[id].state = "error"; jobs[id].error = e.message; });
+      return;
+    }
+    const spec = MODEL_PACKS[id];
+    jobs[id] = { label: `${spec.label} (${spec.size})`, state: "running", pct: 0 };
+    fetchPack(id, MODELS_DIR, (ev) => {
+      if (ev.phase === "download" && ev.total) jobs[id].pct = Math.min(99, Math.floor((ev.done / ev.total) * 100));
+      if (ev.phase === "extract") jobs[id].phase = "unpacking";
+    }).then(() => { jobs[id].state = "done"; jobs[id].pct = 100; })
+      .catch((e) => { jobs[id].state = "error"; jobs[id].error = e.message; });
+  }
+
+  function state() {
+    const c = readConfig() || prev;
+    return {
+      configFile: CONFIG_FILE,
+      current: {
+        openrouterKey: mask(c.OPENROUTER_API_KEY),
+        voice: VOICES[c.TTS_DEFAULT] ? c.TTS_DEFAULT : "kokoro",
+        elevenKey: mask(c.ELEVENLABS_API_KEY),
+        elevenVoice: c.ELEVEN_VOICE_ID || "",
+        audience: c.ACCESS_PASSWORD ? "others" : "me",
+        hasPassword: !!c.ACCESS_PASSWORD,
+        proxy: c.TRUST_PROXY === "1",
+        port: formPort || Number(c.PORT) || DEFAULT_PORT,
+      },
+      voices: VOICES,
+      kokoro: { installed: kokoroInstalled(), size: KOKORO_SIZE },
+      packs: Object.fromEntries(Object.entries(MODEL_PACKS).map(([id, m]) => [id, { label: m.label, size: m.size, hint: m.hint }])),
+      installedPacks: installedPacks(MODELS_DIR),
+      suggestedPassword: suggestPassword(),
+      jobs,
+    };
+  }
+
+  let finish;
+  const finished = new Promise((r) => { finish = r; });
+  let listenPort = 0;
+
+  const server = http.createServer(async (req, res) => {
+    const send = (code, body, type = "application/json") => {
+      res.writeHead(code, { ...HEADERS, "Content-Type": type });
+      res.end(typeof body === "string" || Buffer.isBuffer(body) ? body : JSON.stringify(body));
+    };
+    // DNS-rebinding guard: only answer requests addressed to this machine.
+    const host = String(req.headers.host || "");
+    if (!/^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i.test(host)) return send(403, { error: "forbidden host" });
+    let url;
+    try { url = new URL(req.url, "http://localhost"); } catch { return send(400, { error: "bad request" }); }
+
+    if (req.method === "GET" && STATIC.has(url.pathname)) {
+      const [file, type] = STATIC.get(url.pathname);
+      try { return send(200, await readFile(join(PUBLIC, file)), type); } catch { return send(404, "not found", "text/plain"); }
+    }
+    if (req.method === "GET" && url.pathname === "/") { res.writeHead(302, { Location: "/setup" }); return res.end(); }
+    if (!url.pathname.startsWith("/api/setup/")) return send(404, "not found", "text/plain");
+    if (!okToken(req)) return send(401, { error: "This setup link has expired. Run `npx ava-engine setup --web` for a new one." });
+
+    let body = {};
+    if (req.method === "POST") {
+      if (!/^application\/json\b/i.test(String(req.headers["content-type"] || ""))) return send(415, { error: "expected application/json" });
+      const chunks = []; let size = 0;
+      for await (const c of req) { size += c.length; if (size > 64 * 1024) return send(413, { error: "too large" }); chunks.push(c); }
+      try { body = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}"); } catch { return send(400, { error: "invalid JSON" }); }
+    }
+
+    try {
+      const route = `${req.method} ${url.pathname}`;
+      if (route === "GET /api/setup/state") return send(200, state());
+      if (route === "GET /api/setup/jobs") return send(200, { jobs, installedPacks: installedPacks(MODELS_DIR), kokoroInstalled: kokoroInstalled() });
+      if (route === "GET /api/setup/password") return send(200, { password: suggestPassword() });
+      if (route === "POST /api/setup/check") {
+        const key = String(body.key || "").trim();
+        if (key.length < 20) return send(200, { ok: false, error: "That doesn't look like a full key." });
+        const r = body.service === "elevenlabs" ? await checkElevenLabsKey(key) : await checkOpenRouterKey(key);
+        if (r.ok && r.label && /^sk-or/i.test(r.label)) delete r.label; // unnamed keys report a masked key as their label
+        return send(200, r);
+      }
+      if (route === "POST /api/setup/download") {
+        const id = String(body.id || "");
+        if (id !== "kokoro" && !MODEL_PACKS[id]) return send(400, { error: "unknown download" });
+        startJob(id);
+        return send(200, { ok: true, job: jobs[id] });
+      }
+      if (route === "POST /api/setup/save") {
+        const a = body.answers || {};
+        // "keep" means: leave the saved key as it is.
+        const answers = {
+          openrouterKey: a.mode === "mock" ? null : a.openrouterKey === "keep" ? undefined : String(a.openrouterKey || "") || null,
+          voice: a.voice,
+          elevenKey: a.elevenKey === "keep" ? undefined : a.elevenKey,
+          elevenVoice: a.elevenVoice,
+          audience: a.audience === "others" ? "others" : "me",
+          password: a.audience === "others" ? (a.password === "keep" ? prev.ACCESS_PASSWORD || readConfig()?.ACCESS_PASSWORD : a.password) : undefined,
+          proxy: !!a.proxy,
+          port: a.port,
+        };
+        const errors = validateAnswers(answers);
+        if (errors.length) return send(400, { error: errors.join(" ") });
+        const cfg = buildConfig(readConfig() || prev, answers);
+        const p = Number(cfg.PORT);
+        if (p !== listenPort && !(await portFree(p, cfg.HOST))) return send(409, { error: `Port ${p} is in use by another program. Pick another port.` });
+        writeConfig(cfg);
+        return send(200, { ok: true, port: p, url: `http://localhost:${p}/app`, configFile: CONFIG_FILE });
+      }
+      if (route === "POST /api/setup/finish") {
+        const cfg = readConfig();
+        if (!cfg) return send(400, { error: "Save your settings first." });
+        // Downloads still running (e.g. a voice you switched away from) keep going in
+        // this process after Ava starts; the page already waited for the ones you chose.
+        send(200, { ok: true, port: Number(cfg.PORT) || DEFAULT_PORT });
+        // let the response flush, then hand the port over to Ava
+        setTimeout(() => { server.closeAllConnections?.(); server.close(() => finish({ start: true, port: Number(cfg.PORT) || DEFAULT_PORT })); }, 150);
+        return;
+      }
+      return send(404, { error: "unknown endpoint" });
+    } catch (e) {
+      return send(500, { error: e.message });
+    }
+  });
+
+  listenPort = await findPort(preferredPort || Number(prev.PORT) || DEFAULT_PORT);
+  await new Promise((r) => server.listen(listenPort, "127.0.0.1", r));
+  listenPort = server.address().port;
+  const url = `http://localhost:${listenPort}/setup#token=${token}`;
+  onReady?.({ url, port: listenPort });
+  return finished;
+}

package/lib/cli/setup.mjs

@@ -0,0 +1,233 @@
+// `ava-engine setup` in the terminal: the guided wizard (and its non-interactive twin).
+// The browser version lives in setup-server.mjs; both save through apply.mjs.
+import * as p from "@clack/prompts";
+import { CONFIG_FILE, MODELS_DIR, DEFAULT_PORT, readConfig, writeConfig, checkOpenRouterKey, checkElevenLabsKey, portFree, suggestPassword } from "./config.mjs";
+import { buildConfig, VOICES } from "./apply.mjs";
+import { MODEL_PACKS, installedPacks, fetchPack } from "../fetch-models.mjs";
+import { loadKokoro, kokoroInstalled, KOKORO_SIZE } from "../kokoro-model.mjs";
+
+const mask = (v) => (v ? `${v.slice(0, 6)}…${v.slice(-4)}` : "");
+function bail(v) { if (p.isCancel(v)) { p.cancel("Setup cancelled. Nothing was changed."); process.exit(0); } return v; }
+
+/** Download speech model packs with a progress bar per pack. */
+export async function downloadPacks(packs) {
+  for (const pack of packs) {
+    const spec = MODEL_PACKS[pack];
+    let bar = null, last = 0;
+    try {
+      await fetchPack(pack, MODELS_DIR, (ev) => {
+        if (ev.phase === "skip") return;
+        if (ev.phase === "download") {
+          if (!bar) { bar = p.progress({ max: 100, style: "heavy" }); bar.start(`Downloading ${spec.label} (${spec.size})`); }
+          const pct = ev.total ? Math.floor((ev.done / ev.total) * 100) : 0;
+          if (pct > last) { bar.advance(pct - last, `Downloading ${spec.label}: ${pct}%`); last = pct; }
+        }
+        if (ev.phase === "extract" && bar) bar.message(`Unpacking ${spec.label}…`);
+      });
+      if (bar) bar.stop(`${spec.label} ready`); else p.log.success(`${spec.label} already installed`);
+    } catch (e) {
+      if (bar) bar.error(`${spec.label} failed`);
+      p.log.error(`${e.message}\nYou can retry later with: npx ava-engine models ${pack}`);
+    }
+  }
+}
+
+/** Download the Kokoro voice now, so the first call doesn't wait for it. */
+export async function downloadKokoro() {
+  process.env.AVA_MODELS_DIR ??= MODELS_DIR;
+  if (kokoroInstalled()) { p.log.success("Kokoro voice already installed"); return true; }
+  const bar = p.progress({ max: 100, style: "heavy" });
+  bar.start(`Downloading the Kokoro voice (${KOKORO_SIZE})`);
+  let last = 0;
+  try {
+    await loadKokoro({ onProgress: ({ pct }) => { if (pct > last) { bar.advance(pct - last, `Downloading the Kokoro voice: ${pct}%`); last = pct; } } });
+    bar.stop("Kokoro voice ready");
+    return true;
+  } catch (e) {
+    bar.error("Kokoro voice download failed");
+    p.log.error(`${e.message}\nAva will retry when it starts, or use the browser's voice meanwhile.`);
+    return false;
+  }
+}
+
+/**
+ * The interactive wizard. Returns { start: boolean, port }.
+ * Existing settings are kept unless you change them.
+ */
+export async function runSetup() {
+  process.env.AVA_MODELS_DIR ??= MODELS_DIR; // so "is Kokoro installed?" looks in ~/.ava-engine/models
+  const prev = readConfig() || {};
+  const answers = {};
+
+  console.log("");
+  p.intro(" ΛVΛ  Ava Engine setup ");
+  p.note(
+    "A screen-aware voice agent: it joins a call, sees the tab your\n" +
+    "customer shares, and talks them through it.\n\n" +
+    "This takes about 2 minutes. You can change anything later with\n" +
+    "`npx ava-engine setup`, or by editing " + CONFIG_FILE,
+    "Welcome",
+  );
+
+  // 1 · AI replies
+  const mode = bail(await p.select({
+    message: "How should Ava think?",
+    options: [
+      { value: "full", label: "With real AI", hint: "recommended; needs an OpenRouter key" },
+      { value: "mock", label: "Just look around first", hint: "no key; canned replies, everything else works" },
+    ],
+  }));
+  if (mode === "mock") {
+    answers.openrouterKey = null;
+    p.log.info("MOCK mode: Ava will use canned replies. Add a key any time with `npx ava-engine setup`.");
+  } else {
+    let key = prev.OPENROUTER_API_KEY;
+    if (key && !bail(await p.confirm({ message: `Keep your current OpenRouter key (${mask(key)})?`, initialValue: true }))) key = undefined;
+    while (!key) {
+      p.log.message("Ava's AI runs through OpenRouter: one key for every model.\nGet one at https://openrouter.ai/keys (set a credit limit on it).");
+      const entered = bail(await p.password({ message: "Paste your OpenRouter API key", validate: (v) => (!v || v.trim().length < 20 ? "That doesn't look like a full key" : undefined) })).trim();
+      const s = p.spinner(); s.start("Checking the key with OpenRouter");
+      const r = await checkOpenRouterKey(entered);
+      if (r.ok) {
+        const named = r.label && !/^sk-or/i.test(r.label) ? ` (${r.label})` : ""; // unnamed keys report a masked key as their label
+        s.stop(`Key works${named}${r.limit != null ? `, credit limit $${r.limit}` : ""}`);
+        key = entered;
+      } else {
+        s.error(r.error);
+        const next = bail(await p.select({
+          message: "What now?",
+          options: [
+            { value: "retry", label: "Try another key" },
+            ...(r.offline ? [{ value: "keep", label: "Save it anyway", hint: "I'm offline right now" }] : []),
+            { value: "mock", label: "Skip for now", hint: "MOCK mode" },
+          ],
+        }));
+        if (next === "keep") key = entered;
+        if (next === "mock") break;
+      }
+    }
+    answers.openrouterKey = key || null;
+  }
+
+  // 2 · voice (free and offline by default, so offered in every mode)
+  answers.voice = bail(await p.select({
+    message: "Which voice should Ava speak with?",
+    initialValue: VOICES[prev.TTS_DEFAULT] ? prev.TTS_DEFAULT : "kokoro",
+    options: Object.entries(VOICES).map(([value, v]) => ({ value, label: v.label, hint: value === "kokoro" && kokoroInstalled() ? "free, runs on this computer (installed)" : v.hint })),
+  }));
+  if (answers.voice === "kokoro") await downloadKokoro();
+  if (answers.voice === "elevenlabs") {
+    let ek = prev.ELEVENLABS_API_KEY;
+    if (ek && !bail(await p.confirm({ message: `Keep your current ElevenLabs key (${mask(ek)})?`, initialValue: true }))) ek = undefined;
+    while (!ek) {
+      const entered = bail(await p.password({ message: "Paste your ElevenLabs API key (elevenlabs.io → API keys)" })).trim();
+      const s = p.spinner(); s.start("Checking the key with ElevenLabs");
+      const r = await checkElevenLabsKey(entered);
+      if (r.ok || r.offline) { s.stop(r.ok ? "Key works" : `${r.error}; saved anyway`); ek = entered; }
+      else {
+        s.error(r.error);
+        if (!bail(await p.confirm({ message: "Try another key?", initialValue: true }))) { answers.voice = "kokoro"; await downloadKokoro(); break; }
+      }
+    }
+    if (ek) {
+      answers.elevenKey = ek;
+      answers.elevenVoice = bail(await p.text({ message: "ElevenLabs voice ID (Enter for the default voice, Matilda)", placeholder: "XrExE9yKIg1WjnnlVkGX", defaultValue: prev.ELEVEN_VOICE_ID || "" })).trim() || null;
+    }
+  }
+
+  // 3 · speech recognition (offered in every mode)
+  const have = installedPacks(MODELS_DIR);
+  const packs = bail(await p.multiselect({
+    message: "Download offline speech recognition? (space to toggle, enter to confirm)",
+    required: false,
+    initialValues: have.length ? have : ["english-small"],
+    options: Object.entries(MODEL_PACKS).map(([id, m]) => ({ value: id, label: `${m.label} · ${m.size}`, hint: have.includes(id) ? "installed" : m.hint })),
+  }));
+  const missing = packs.filter((x) => !have.includes(x));
+  if (missing.length) await downloadPacks(missing);
+  else if (!packs.length) p.log.info("No models: Ava will use the browser's speech recognition (Chrome). Add them later with `npx ava-engine models`.");
+
+  // 4 · who can reach it
+  answers.audience = bail(await p.select({
+    message: "Who will use this Ava?",
+    initialValue: prev.ACCESS_PASSWORD ? "others" : "me",
+    options: [
+      { value: "me", label: "Just me, on this computer", hint: "safest; reachable only at localhost" },
+      { value: "others", label: "My team or customers", hint: "over a network or the internet; needs a password" },
+    ],
+  }));
+  if (answers.audience === "others") {
+    const suggested = suggestPassword();
+    const how = bail(await p.select({
+      message: "Set an access password (every call spends your API credit)",
+      options: [
+        ...(prev.ACCESS_PASSWORD ? [{ value: "keep", label: "Keep the current password" }] : []),
+        { value: "gen", label: `Use a generated one: ${suggested}`, hint: "recommended; it's saved in the settings file" },
+        { value: "own", label: "Choose my own" },
+      ],
+    }));
+    answers.password = how === "keep" ? prev.ACCESS_PASSWORD : how === "gen" ? suggested
+      : bail(await p.password({ message: "Access password (at least 10 characters)", validate: (v) => (!v || v.length < 10 ? "Use at least 10 characters" : undefined) }));
+    answers.proxy = bail(await p.confirm({ message: "Will it run behind a proxy or host (Fly.io, Cloudflare, nginx, Render…)?", initialValue: prev.TRUST_PROXY === "1" }));
+  }
+
+  // 5 · port
+  const portStr = bail(await p.text({
+    message: "Port",
+    defaultValue: String(prev.PORT || DEFAULT_PORT),
+    placeholder: String(prev.PORT || DEFAULT_PORT),
+    validate: (v) => { if (!v) return undefined; const n = Number(v); return Number.isInteger(n) && n > 0 && n < 65536 ? undefined : "Use a number between 1 and 65535"; },
+  }));
+  answers.port = Number(portStr) || DEFAULT_PORT;
+
+  // 6 · save
+  const cfg = buildConfig(prev, answers);
+  if (!(await portFree(Number(cfg.PORT), cfg.HOST))) p.log.warn(`Port ${cfg.PORT} is in use right now. Stop that program, or run \`npx ava-engine start --port <other>\`.`);
+  writeConfig(cfg);
+  p.note(
+    [
+      `AI replies     ${cfg.OPENROUTER_API_KEY ? `OpenRouter (${mask(cfg.OPENROUTER_API_KEY)})` : "MOCK mode (canned replies)"}`,
+      `Voice          ${VOICES[cfg.TTS_DEFAULT]?.label || "Kokoro"}`,
+      `Speech models  ${installedPacks(MODELS_DIR).map((x) => MODEL_PACKS[x].label).join(", ") || "none (browser speech recognition)"}`,
+      `Access         ${cfg.HOST === "127.0.0.1" ? "this computer only" : `password protected${cfg.ACCESS_PASSWORD ? ` (${cfg.ACCESS_PASSWORD})` : ""}`}`,
+      `Address        http://localhost:${cfg.PORT}/app`,
+      "",
+      `Saved to ${CONFIG_FILE}`,
+    ].join("\n"),
+    "Your Ava",
+  );
+
+  const start = bail(await p.confirm({ message: "Start Ava now?", initialValue: true }));
+  p.outro(start ? "Starting Ava…" : "All set. Start Ava any time with: npx ava-engine");
+  return { start, port: Number(cfg.PORT) };
+}
+
+/**
+ * Non-interactive setup for scripts, servers and CI: settings come from the
+ * environment and flags, with safe defaults. Returns the written config.
+ */
+export async function runSetupNonInteractive({ models = [], port } = {}) {
+  const prev = readConfig() || {};
+  const env = process.env;
+  const pick = (k) => env[k] ?? prev[k];
+  const cfg = { ...prev };
+  for (const k of ["OPENROUTER_API_KEY", "ELEVENLABS_API_KEY", "ELEVEN_VOICE_ID", "TTS_DEFAULT", "ACCESS_PASSWORD", "TRUST_PROXY", "KOKORO"]) if (pick(k)) cfg[k] = pick(k);
+  cfg.PORT = String(port || pick("PORT") || DEFAULT_PORT);
+  if (!cfg.ACCESS_PASSWORD) cfg.HOST = pick("HOST") || "127.0.0.1"; // never expose an open server by default
+  else if (pick("HOST")) cfg.HOST = pick("HOST");
+  cfg.AVA_MODELS_DIR = MODELS_DIR;
+  writeConfig(cfg);
+  for (const pack of models) {
+    if (pack === "kokoro") {
+      process.env.AVA_MODELS_DIR ??= MODELS_DIR;
+      console.log("↓ Kokoro voice");
+      if (!kokoroInstalled()) await loadKokoro();
+      continue;
+    }
+    if (!MODEL_PACKS[pack]) throw new Error(`unknown model "${pack}" (choose: ${Object.keys(MODEL_PACKS).join(", ")}, kokoro)`);
+    console.log(`↓ ${MODEL_PACKS[pack].label}`);
+    await fetchPack(pack, MODELS_DIR);
+  }
+  console.log(`Saved ${CONFIG_FILE}${cfg.OPENROUTER_API_KEY ? "" : " (MOCK mode: no OPENROUTER_API_KEY)"}`);
+  return cfg;
+}

package/lib/fetch-models.mjs

@@ -0,0 +1,104 @@
+// Offline speech-to-text model downloads (sherpa-onnx). Dependency-free so the
+// Dockerfile and the CLI can both use it:
+//
+//   node lib/fetch-models.mjs [english-small|english|multilingual|all] [--dir <path>]
+//
+// Archives are extracted with the system `tar` (macOS, Linux and Windows 10+).
+
+import { createWriteStream, existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { spawn } from "node:child_process";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { fileURLToPath } from "node:url";
+
+const BASE = "https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models";
+
+/** What the CLI offers. `files` are fetched in order; `dir` marks a pack as installed. */
+export const MODEL_PACKS = {
+  "english-small": {
+    label: "English, fast", size: "122 MB",
+    hint: "Streaming English with live captions. A good default.",
+    files: [{ name: "sherpa-onnx-streaming-zipformer-en-20M-2023-02-17.tar.bz2", dir: "sherpa-onnx-streaming-zipformer-en-20M-2023-02-17" }],
+  },
+  english: {
+    label: "English, most accurate", size: "296 MB",
+    hint: "The larger streaming English model. Used instead of the small one when both are installed.",
+    files: [{ name: "sherpa-onnx-streaming-zipformer-en-2023-06-26.tar.bz2", dir: "sherpa-onnx-streaming-zipformer-en-2023-06-26" }],
+  },
+  multilingual: {
+    label: "Multilingual (zh/en/ja/ko/yue)", size: "1 GB",
+    hint: "SenseVoice with voice activity detection. Captions appear when the speaker pauses.",
+    files: [
+      { name: "sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17.tar.bz2", dir: "sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17" },
+      { name: "silero_vad.onnx", file: "silero_vad.onnx" },
+    ],
+  },
+};
+
+export function packInstalled(pack, dir) {
+  return MODEL_PACKS[pack].files.every((f) => existsSync(join(dir, f.dir || f.file)));
+}
+
+export function installedPacks(dir) {
+  return Object.keys(MODEL_PACKS).filter((p) => packInstalled(p, dir));
+}
+
+function untar(archive, cwd) {
+  return new Promise((res, rej) => {
+    const p = spawn("tar", ["xjf", archive], { cwd, stdio: ["ignore", "ignore", "pipe"] });
+    let err = "";
+    p.stderr.on("data", (d) => { err += d; });
+    p.on("error", (e) => rej(new Error(`couldn't run tar: ${e.message}`)));
+    p.on("close", (code) => (code === 0 ? res() : rej(new Error(`tar failed (${code}): ${err.trim()}`))));
+  });
+}
+
+async function download(url, dest, onProgress) {
+  const res = await fetch(url, { redirect: "follow" });
+  if (!res.ok || !res.body) throw new Error(`download failed: HTTP ${res.status} for ${url}`);
+  const total = Number(res.headers.get("content-length")) || 0;
+  let done = 0;
+  const body = Readable.fromWeb(res.body);
+  body.on("data", (c) => { done += c.length; onProgress?.(done, total); });
+  const tmp = dest + ".part";
+  await pipeline(body, createWriteStream(tmp));
+  renameSync(tmp, dest); // only a complete download gets the real name
+}
+
+/**
+ * Download and unpack one model pack into `dir`. Skips files already present.
+ * onProgress({ file, done, total, phase: "download" | "extract" | "skip" })
+ */
+export async function fetchPack(pack, dir, onProgress) {
+  const spec = MODEL_PACKS[pack];
+  if (!spec) throw new Error(`unknown model pack "${pack}" (choose: ${Object.keys(MODEL_PACKS).join(", ")})`);
+  mkdirSync(dir, { recursive: true });
+  for (const f of spec.files) {
+    const target = join(dir, f.dir || f.file);
+    if (existsSync(target)) { onProgress?.({ file: f.name, phase: "skip" }); continue; }
+    const dest = join(dir, f.name);
+    await download(`${BASE}/${f.name}`, dest, (done, total) => onProgress?.({ file: f.name, phase: "download", done, total }));
+    if (f.dir) {
+      onProgress?.({ file: f.name, phase: "extract" });
+      try { await untar(f.name, dir); } finally { rmSync(dest, { force: true }); }
+    }
+  }
+}
+
+// ── command line ──
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const args = process.argv.slice(2);
+  const di = args.indexOf("--dir");
+  const dir = resolve(di >= 0 ? args.splice(di, 2)[1] : join(dirname(fileURLToPath(import.meta.url)), "..", "models"));
+  const wanted = args[0] === "all" ? ["english", "multilingual"] : args.length ? args : ["english-small"];
+  for (const pack of wanted) {
+    let last = -1;
+    await fetchPack(pack, dir, (p) => {
+      if (p.phase === "skip") console.log(`✓ ${p.file} (already present)`);
+      else if (p.phase === "extract") console.log(`  unpacking ${p.file}…`);
+      else if (p.total) { const pct = Math.floor((p.done / p.total) * 100); if (pct !== last && pct % 10 === 0) { last = pct; console.log(`↓ ${p.file} ${pct}%`); } }
+    });
+  }
+  console.log(`Models are in ${dir}`);
+}

package/lib/guard.mjs

@@ -0,0 +1,92 @@
+// Abuse protection for a publicly reachable server. Every /api call can spend
+// the operator's model/voice credit, so a deploy should never be wide open.
+//
+//   ACCESS_PASSWORD  optional. When set, the app, specialist console, /api/* and
+//                    the WebSockets require it (HTTP Basic auth, then a cookie so
+//                    WebSocket upgrades are covered too). The landing page and
+//                    static assets stay public.
+//   TRUST_PROXY=1    take the client IP from Fly-Client-IP / X-Forwarded-For
+//                    (only behind a proxy you control — the header is spoofable).
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+const PASSWORD = process.env.ACCESS_PASSWORD || "";
+const TRUST_PROXY = process.env.TRUST_PROXY === "1";
+export const AUTH_ENABLED = !!PASSWORD;
+
+const COOKIE = "ava_auth";
+const cookieValue = PASSWORD ? createHmac("sha256", PASSWORD).update("ava-access-v1").digest("hex") : "";
+
+function safeEqual(a, b) {
+  const x = Buffer.from(String(a)), y = Buffer.from(String(b));
+  return x.length === y.length && timingSafeEqual(x, y);
+}
+
+function readCookie(req, name) {
+  for (const part of String(req.headers.cookie || "").split(";")) {
+    const i = part.indexOf("=");
+    if (i > 0 && part.slice(0, i).trim() === name) return part.slice(i + 1).trim();
+  }
+  return null;
+}
+
+/** True if the request carries a valid password (Basic auth) or auth cookie. */
+export function isAuthorized(req) {
+  if (!AUTH_ENABLED) return true;
+  const c = readCookie(req, COOKIE);
+  if (c && safeEqual(c, cookieValue)) return true;
+  const h = String(req.headers.authorization || "");
+  if (h.startsWith("Basic ")) {
+    const pass = Buffer.from(h.slice(6), "base64").toString("utf8").split(":").slice(1).join(":");
+    return safeEqual(pass, PASSWORD);
+  }
+  return false;
+}
+
+/** Headers that ask the browser for the password. */
+export function challengeHeaders() {
+  return { "WWW-Authenticate": 'Basic realm="Ava", charset="UTF-8"' };
+}
+
+/** Set-Cookie header that remembers a successful login (so WebSockets pass). */
+export function authCookieHeader(req) {
+  if (!AUTH_ENABLED || readCookie(req, COOKIE) === cookieValue) return {};
+  const secure = TRUST_PROXY || req.socket.encrypted ? "; Secure" : "";
+  return { "Set-Cookie": `${COOKIE}=${cookieValue}; Path=/; HttpOnly; SameSite=Strict; Max-Age=43200${secure}` };
+}
+
+export function clientIp(req) {
+  if (TRUST_PROXY) {
+    const fly = req.headers["fly-client-ip"];
+    if (fly) return String(fly);
+    const xff = req.headers["x-forwarded-for"];
+    if (xff) return String(xff).split(",")[0].trim();
+  }
+  return req.socket.remoteAddress || "?";
+}
+
+/** Reject cross-site WebSocket upgrades (browsers always send Origin). */
+export function sameOrigin(req) {
+  const origin = req.headers.origin;
+  if (!origin) return true; // non-browser client; still subject to auth
+  try { return new URL(origin).host === req.headers.host; } catch { return false; }
+}
+
+/**
+ * Fixed-window rate limiter: limiter("turn", 120, 60_000)(ip) → true if allowed.
+ * Buckets are swept as they expire, so memory stays bounded by active clients.
+ */
+export function limiter(name, max, windowMs) {
+  const hits = new Map();
+  setInterval(() => { const now = Date.now(); for (const [k, v] of hits) if (now >= v.reset) hits.delete(k); }, windowMs).unref();
+  const allow = (key) => {
+    const now = Date.now();
+    let b = hits.get(key);
+    if (!b || now >= b.reset) { b = { n: 0, reset: now + windowMs }; hits.set(key, b); }
+    b.n += 1;
+    return b.n <= max;
+  };
+  /** True while `key` is over the limit, without counting a new hit. */
+  allow.blocked = (key) => { const b = hits.get(key); return !!b && Date.now() < b.reset && b.n >= max; };
+  return allow;
+}