Upload folder using huggingface_hub

.dockerignore

@@ -0,0 +1,5 @@
+tests/
+scripts/
+__pycache__/
+*.pyc
+.env

Dockerfile

@@ -0,0 +1,18 @@
+# nova-connect: the Nova web page + room-ticket service. Hugging Face Docker
+# Space (port 7860) or any container host. Holds no models and no audio.
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PORT=7860
+# HF Spaces run the container as uid 1000.
+RUN useradd --create-home --uid 1000 app
+WORKDIR /home/app/nova-connect
+
+COPY --chown=app requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY --chown=app app.py token_service.py ./
+COPY --chown=app static ./static
+
+USER app
+EXPOSE 7860
+CMD ["python", "app.py"]

README.md

@@ -1,10 +1,76 @@
 ---
 title: Nova
-emoji: 📊
-colorFrom: gray
-colorTo: gray
+emoji: 🎙️
+colorFrom: indigo
+colorTo: purple
 sdk: docker
+app_port: 7860
 pinned: false
+short_description: Talk to an on-device voice agent on a Raspberry Pi
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# nova-connect
+
+Talk to **Nova** — a voice assistant whose speech recognition, speech synthesis and
+wake word run on a Raspberry Pi 5 with a Hailo NPU — from any browser, anywhere.
+
+This Space is only the front desk. It serves the page and signs a short-lived
+LiveKit ticket after a passcode check. It never touches audio and never talks to
+the Pi: the browser and the Pi each dial out to a LiveKit server and meet in a room.
+
+```
+browser ─ passcode ─► this Space ─► ticket (10 min, 1 room, dispatch nova-<pi>)
+   └──── WebRTC ────► LiveKit server ◄──── outbound, always on ──── Pi (all models local)
+```
+
+## Setting up a Pi
+
+On the Pi, in `edge/nova-hailo`:
+
+1. Install the extra: `uv sync --extra livekit` (plus any extras already in use).
+2. Add the LiveKit server to `.env`: `LIVEKIT_URL`, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET`.
+3. Turn the online door on in the active profile config:
+   ```yaml
+   livekit:
+     enabled: true
+   ```
+4. Start Nova as usual (`./scripts/run_demo_oem.sh`). The log prints the Pi's
+   agent name, taken from its hostname:
+   `LiveKit: registered as nova-<hostname>`.
+
+The LAN realtime API keeps working unchanged; one conversation at a time across
+both (a second caller hears "Nova is in use").
+
+## Setting up this Space
+
+1. Make a passcode: `python scripts/make_passcode.py` (shows the passcode once and
+   prints its hash).
+2. Space → Settings → **Secrets**:
+
+   | Secret | Value |
+   |---|---|
+   | `LIVEKIT_URL` | the LiveKit server, `wss://…` |
+   | `LIVEKIT_API_KEY` / `LIVEKIT_API_SECRET` | its key pair |
+   | `NOVA_AGENT_NAME` | exactly the name the Pi printed, e.g. `nova-conmod-integration1` |
+   | `NOVA_PASSCODE_HASH` | the `scrypt$…` line from step 1 |
+
+3. `GET /api/health` shows `{"configured": true, ...}` once all five are set.
+
+## Run locally
+
+```bash
+pip install -r requirements.txt
+export LIVEKIT_URL=... LIVEKIT_API_KEY=... LIVEKIT_API_SECRET=... \
+       NOVA_AGENT_NAME=nova-<hostname> NOVA_PASSCODE_HASH='scrypt$...'
+python app.py          # http://localhost:7860
+```
+
+Tests: `python -m pytest tests -q`.
+
+## Security notes
+
+- The LiveKit API secret lives only in Space secrets and on the Pi.
+- Tickets last 10 minutes, join one fresh room, may publish only the microphone
+  and data, and dispatch only the configured Pi.
+- Passcodes are checked against an scrypt hash; 5 attempts per 5 minutes per IP.
+- Media is encrypted in transit (DTLS-SRTP); the LiveKit server can see it.

app.py

@@ -0,0 +1,106 @@
+"""nova-connect: the web page and the room-ticket desk for a Nova Pi.
+
+Runs as a Hugging Face Docker Space (port 7860) or any container host. It serves
+the static UI and one endpoint: POST /api/session with the passcode returns a
+LiveKit URL and a 10-minute token. It holds the LiveKit API secret; the browser
+never sees it. Audio never passes through here -- browser and Pi meet at the SFU.
+
+Configuration (Space secrets / environment):
+  LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET  -- the SFU and its key pair
+  NOVA_AGENT_NAME     -- the Pi's agent name, printed by the Pi at startup
+                         ("LiveKit: registered as nova-<hostname>")
+  NOVA_PASSCODE_HASH  -- from scripts/make_passcode.py
+"""
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+import token_service as ts
+
+STATIC = Path(__file__).resolve().parent / "static"
+logger = logging.getLogger("nova-connect")
+
+
+@dataclass
+class Settings:
+    livekit_url: str
+    api_key: str
+    api_secret: str
+    agent_name: str
+    passcode_hash: str
+
+    @classmethod
+    def from_env(cls) -> Settings:
+        e = os.environ.get
+        return cls(
+            livekit_url=e("LIVEKIT_URL", ""),
+            api_key=e("LIVEKIT_API_KEY", ""),
+            api_secret=e("LIVEKIT_API_SECRET", ""),
+            agent_name=e("NOVA_AGENT_NAME", ""),
+            passcode_hash=e("NOVA_PASSCODE_HASH", ""),
+        )
+
+    @property
+    def configured(self) -> bool:
+        return all(
+            (self.livekit_url, self.api_key, self.api_secret, self.agent_name, self.passcode_hash)
+        )
+
+
+class SessionRequest(BaseModel):
+    passcode: str
+
+
+def _client_ip(request: Request) -> str:
+    # Behind the HF / reverse proxy the socket peer is the proxy; the first
+    # X-Forwarded-For hop is the caller.
+    fwd = request.headers.get("x-forwarded-for", "")
+    if fwd:
+        return fwd.split(",")[0].strip()
+    return request.client.host if request.client else "unknown"
+
+
+def create_app(settings: Settings | None = None, *, limiter: ts.RateLimiter | None = None) -> FastAPI:
+    settings = settings or Settings.from_env()
+    limiter = limiter or ts.RateLimiter()
+    app = FastAPI(title="nova-connect", docs_url=None, redoc_url=None)
+
+    @app.get("/api/health")
+    def health():
+        return {"configured": settings.configured, "agent": settings.agent_name or None}
+
+    @app.post("/api/session")
+    def session(req: SessionRequest, request: Request):
+        if not settings.configured:
+            return JSONResponse({"error": "not_configured"}, status_code=503)
+        if not limiter.allow(_client_ip(request)):
+            return JSONResponse({"error": "rate_limited"}, status_code=429)
+        if not ts.verify_passcode(req.passcode, settings.passcode_hash):
+            return JSONResponse({"error": "bad_passcode"}, status_code=401)
+        s = ts.mint_session(
+            api_key=settings.api_key, api_secret=settings.api_secret, agent_name=settings.agent_name
+        )
+        logger.info("session issued room=%s", s.room)
+        return {"url": settings.livekit_url, "token": s.token, "room": s.room, "expires_in": s.expires_in}
+
+    @app.get("/")
+    def index():
+        return FileResponse(STATIC / "index.html")
+
+    app.mount("/static", StaticFiles(directory=STATIC), name="static")
+    return app
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    logging.basicConfig(level=logging.INFO)
+    uvicorn.run(create_app(), host="0.0.0.0", port=int(os.environ.get("PORT", "7860")))

requirements.txt

@@ -0,0 +1,5 @@
+# Pinned to the versions the tests ran against.
+fastapi==0.115.6
+uvicorn==0.32.1
+pydantic==2.13.5
+livekit-api==1.2.1

scripts/make_passcode.py

@@ -0,0 +1,40 @@
+"""Create the passcode for the Nova page and the hash to store as a secret.
+
+    python scripts/make_passcode.py            # generates a random passcode
+    python scripts/make_passcode.py --ask      # type your own (not echoed)
+
+Paste the printed hash into the Space secret NOVA_PASSCODE_HASH. The passcode
+itself is shown once and stored nowhere -- share it only with people who
+should be able to talk to the Pi.
+"""
+from __future__ import annotations
+
+import argparse
+import getpass
+import secrets
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+import token_service  # noqa: E402
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--ask", action="store_true", help="type a passcode instead of generating one")
+    args = ap.parse_args()
+    if args.ask:
+        passcode = getpass.getpass("Passcode: ")
+        if passcode != getpass.getpass("Again: "):
+            sys.exit("passcodes differ")
+        if len(passcode) < 8:
+            sys.exit("use at least 8 characters")
+    else:
+        passcode = secrets.token_urlsafe(9)
+        print(f"Passcode (shown once): {passcode}")
+    print(f"NOVA_PASSCODE_HASH={token_service.hash_passcode(passcode)}")
+
+
+if __name__ == "__main__":
+    main()

static/index.html

@@ -0,0 +1,43 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+  <title>Nova</title>
+  <link rel="icon" href="data:,">
+  <link rel="stylesheet" href="/static/nova.css">
+</head>
+<body>
+  <main id="app" data-state="idle">
+    <header class="topbar">
+      <span class="brand">NOVA</span>
+      <button id="llm" class="chip" type="button" hidden title="Switch between the Pi's Hailo model and the cloud LLM">—</button>
+      <span id="phase" class="phase">Idle</span>
+    </header>
+
+    <section id="gate" class="gate">
+      <p class="lede">Talk to Nova on its Raspberry Pi — the speech models run on the device;
+        this page only connects you to it.</p>
+      <form id="login" autocomplete="off">
+        <label for="passcode">Passcode</label>
+        <input id="passcode" type="password" required autocomplete="current-password" placeholder="Enter passcode">
+        <button id="connect" type="submit">Connect</button>
+      </form>
+      <p id="gate-msg" class="msg" role="status"></p>
+    </section>
+
+    <section id="live" class="live" hidden>
+      <div class="orb-wrap"><canvas id="orb" width="320" height="320" aria-hidden="true"></canvas></div>
+      <p id="live-msg" class="msg" role="status"></p>
+      <ol id="transcript" class="transcript" aria-live="polite"></ol>
+      <footer class="controls">
+        <button id="mute" type="button" class="ghost">Mute</button>
+        <span id="metrics" class="metrics"></span>
+        <button id="hangup" type="button" class="danger">End</button>
+      </footer>
+    </section>
+  </main>
+  <script src="/static/vendor/livekit-client.umd.min.js"></script>
+  <script src="/static/nova.js"></script>
+</body>
+</html>

static/nova.css

@@ -0,0 +1,57 @@
+/* Palette and rhythm from the in-car Qt HMI (hmi_qt/NovaUI/Theme.qml). */
+:root {
+  --base: #07080b; --surface: #0e1016; --surface-hi: #151922; --hairline: #1e2330;
+  --cyan: #4cd6ff; --violet: #b66bff; --red: #ff5e7e; --green: #4dffb4; --yellow: #ffd84d;
+  --text-hi: #eef1f7; --text-mid: #8b93a7; --text-lo: #4d5566;
+  --idle: #2a3242; --accent: var(--idle);
+  --u: 8px; --radius: 14px;
+  --font: "SF Pro Text", Inter, Roboto, system-ui, sans-serif;
+  color-scheme: dark;
+}
+[data-state="listening"] { --accent: var(--cyan); }
+[data-state="thinking"]  { --accent: var(--violet); }
+[data-state="speaking"]  { --accent: var(--green); }
+[data-state="error"]     { --accent: var(--red); }
+
+* { box-sizing: border-box; }
+html, body { margin: 0; height: 100%; background: var(--base); color: var(--text-hi); font: 15px/1.45 var(--font); }
+#app { max-width: 560px; min-height: 100%; margin: 0 auto; padding: calc(2 * var(--u)); display: flex; flex-direction: column; }
+
+.topbar { display: flex; align-items: center; gap: var(--u); padding-block: var(--u); }
+.brand { font-weight: 700; letter-spacing: .28em; font-size: 14px; }
+.phase { margin-left: auto; font-size: 12px; letter-spacing: .14em; text-transform: uppercase; color: var(--accent); transition: color .3s; }
+[data-state="idle"] .phase { color: var(--text-lo); }
+
+button, input { font: inherit; color: inherit; }
+button { cursor: pointer; border: 1px solid var(--hairline); background: var(--surface-hi); border-radius: 999px; padding: 6px 14px; }
+button:hover:not(:disabled) { border-color: var(--text-lo); }
+button:disabled { opacity: .5; cursor: default; }
+button:focus-visible, input:focus-visible { outline: 2px solid var(--cyan); outline-offset: 2px; }
+.chip { font-size: 12px; color: var(--text-mid); padding: 3px 10px; }
+.chip[data-mode="local"] { color: var(--yellow); }
+.chip[data-mode="openrouter"] { color: var(--cyan); }
+.ghost { background: transparent; }
+.danger { border-color: #3a1d27; color: var(--red); }
+
+.gate { margin-top: 18vh; }
+.lede { color: var(--text-mid); margin: 0 0 calc(3 * var(--u)); }
+#login { display: flex; flex-wrap: wrap; gap: var(--u); align-items: center; }
+#login label { width: 100%; font-size: 12px; color: var(--text-mid); letter-spacing: .08em; text-transform: uppercase; }
+#passcode { flex: 1 1 200px; min-width: 0; background: var(--surface); border: 1px solid var(--hairline); border-radius: var(--radius); padding: 10px 14px; }
+#connect { background: var(--cyan); color: var(--base); border: 0; font-weight: 600; padding: 10px 20px; }
+.msg { min-height: 1.45em; color: var(--text-mid); font-size: 13px; }
+.msg.bad { color: var(--red); }
+
+.live { flex: 1; display: flex; flex-direction: column; }
+.orb-wrap { display: grid; place-items: center; padding-block: calc(2 * var(--u)); }
+#orb { width: min(260px, 60vw); aspect-ratio: 1; max-width: 100%; }
+.transcript { list-style: none; margin: 0; padding: 0; flex: 1; overflow-y: auto; max-height: 38vh; display: flex; flex-direction: column; gap: var(--u); }
+.transcript li { background: var(--surface); border: 1px solid var(--hairline); border-radius: var(--radius); padding: 8px 12px; max-width: 88%; }
+.transcript li.you { align-self: flex-end; color: var(--text-mid); }
+.transcript li.nova { align-self: flex-start; }
+.transcript li::before { display: block; font-size: 10px; letter-spacing: .14em; color: var(--text-lo); margin-bottom: 2px; }
+.transcript li.you::before { content: "YOU"; }
+.transcript li.nova::before { content: "NOVA"; }
+.controls { display: flex; align-items: center; gap: var(--u); padding-top: calc(2 * var(--u)); padding-bottom: env(safe-area-inset-bottom, 0px); }
+.metrics { flex: 1; text-align: center; font: 12px "SF Mono", "JetBrains Mono", monospace; color: var(--text-lo); }
+#mute[aria-pressed="true"] { color: var(--yellow); border-color: var(--yellow); }

static/nova.js

@@ -0,0 +1,230 @@
+// Nova web client: passcode -> room ticket -> LiveKit room with the Pi's agent.
+// Audio: WebRTC via livekit-client. Controls: JSON on data topic "nova.control",
+// the same nova.* messages the in-car HMI speaks on /v1/realtime.
+(() => {
+  "use strict";
+  const LK = window.LivekitClient;
+  const TOPIC = "nova.control";
+  const AGENT_JOIN_TIMEOUT_MS = 20000;
+  const $ = (id) => document.getElementById(id);
+  const app = $("app");
+
+  let room = null;
+  let agent = null;
+  let chimed = false;
+  let llmMode = null;
+  let joinTimer = null;
+  let analyser = null;
+  const chime = new Audio("/static/wake.mp3");
+
+  // ---- UI helpers ---------------------------------------------------------
+  const LABELS = { listening: "Listening", thinking: "Thinking", speaking: "Speaking", error: "Error" };
+  function setState(s) {
+    app.dataset.state = s;
+    $("phase").textContent = LABELS[s] || (s === "connecting" ? "Connecting" : "Idle");
+  }
+  function say(el, text, bad = false) { el.textContent = text; el.classList.toggle("bad", bad); }
+  function addLine(who, text) {
+    const li = document.createElement("li");
+    li.className = who;
+    li.textContent = text;
+    $("transcript").append(li);
+    li.scrollIntoView({ block: "end", behavior: "smooth" });
+  }
+  function showLlm(snap) {
+    llmMode = snap.mode;
+    const b = $("llm");
+    b.hidden = false;
+    b.dataset.mode = snap.mode;
+    b.textContent = snap.mode === "local" ? "Local Hailo" : `Cloud · ${snap.llm_backend || "llm"}`;
+    b.disabled = false;
+  }
+
+  // ---- control channel ----------------------------------------------------
+  function send(msg) {
+    if (!room) return;
+    const data = new TextEncoder().encode(JSON.stringify(msg));
+    room.localParticipant.publishData(data, { reliable: true, topic: TOPIC }).catch(() => {});
+  }
+  function onControl(msg) {
+    switch (msg.type) {
+      case "nova.settings": showLlm(msg); break;
+      case "nova.llm_status":
+        if (msg.status === "loading") { $("llm").disabled = true; $("llm").textContent = "Switching…"; }
+        if (msg.status === "error") { say($("live-msg"), `Model switch failed: ${msg.error}`, true); send({ type: "nova.settings.get" }); }
+        break;
+      case "nova.turn_metrics":
+        if (msg.ttfa_ms != null) $("metrics").textContent = `first audio ${Math.round(msg.ttfa_ms)} ms`;
+        break;
+      case "error":
+        if (msg.error?.type === "session_limit_reached") {
+          hangUp("Nova is in use right now (someone is talking to it in the car). Try again shortly.", true);
+        } else {
+          say($("live-msg"), msg.error?.message || "Error", true);
+        }
+        break;
+    }
+  }
+
+  // ---- orb: agent audio level ---------------------------------------------
+  function watchLevel(track) {
+    try {
+      const ctx = new (window.AudioContext || window.webkitAudioContext)();
+      const src = ctx.createMediaStreamSource(new MediaStream([track.mediaStreamTrack]));
+      analyser = ctx.createAnalyser();
+      analyser.fftSize = 256;
+      src.connect(analyser);
+    } catch { analyser = null; }
+  }
+  function drawOrb() {
+    const c = $("orb"), g = c.getContext("2d"), w = c.width, h = c.height;
+    const accent = getComputedStyle(app).getPropertyValue("--accent").trim() || "#2a3242";
+    let level = 0;
+    if (analyser) {
+      const buf = new Uint8Array(analyser.frequencyBinCount);
+      analyser.getByteFrequencyData(buf);
+      level = buf.reduce((a, b) => a + b, 0) / (buf.length * 255);
+    }
+    const t = performance.now() / 1000;
+    const r = w * 0.26 * (1 + 0.08 * Math.sin(t * 1.6) + 0.9 * level);
+    g.clearRect(0, 0, w, h);
+    const grad = g.createRadialGradient(w / 2, h / 2, r * 0.1, w / 2, h / 2, r * 1.5);
+    grad.addColorStop(0, accent);
+    grad.addColorStop(0.55, accent + "55");
+    grad.addColorStop(1, "transparent");
+    g.fillStyle = grad;
+    g.beginPath(); g.arc(w / 2, h / 2, r * 1.5, 0, Math.PI * 2); g.fill();
+    if (room) requestAnimationFrame(drawOrb);
+  }
+
+  // ---- room lifecycle -----------------------------------------------------
+  function isAgent(p) { return p && (p.kind === LK.ParticipantKind?.AGENT || p.identity?.startsWith("agent-")); }
+
+  function agentJoined(p) {
+    agent = p;
+    clearTimeout(joinTimer);
+    say($("live-msg"), "");
+    send({ type: "nova.settings.get" });
+    agentState(p.attributes?.["lk.agent.state"]);
+  }
+  function agentState(s) {
+    if (!s) return;
+    if (s === "listening" && !chimed) {
+      // Joining is the wake event online: one chime when Nova is first ready.
+      chimed = true;
+      chime.play().catch(() => {});
+    }
+    setState(s === "initializing" ? "connecting" : s);
+  }
+
+  async function connect(passcode) {
+    say($("gate-msg"), "Connecting…");
+    $("connect").disabled = true;
+    let ticket;
+    try {
+      const r = await fetch("/api/session", {
+        method: "POST", headers: { "content-type": "application/json" },
+        body: JSON.stringify({ passcode }),
+      });
+      const body = await r.json().catch(() => ({}));
+      if (r.status === 401) throw new Error("Wrong passcode.");
+      if (r.status === 429) throw new Error("Too many attempts — wait a few minutes.");
+      if (!r.ok) throw new Error(body.error === "not_configured" ? "This page is not configured yet." : `Server error (${r.status}).`);
+      ticket = body;
+    } catch (e) {
+      say($("gate-msg"), e.message, true);
+      $("connect").disabled = false;
+      return;
+    }
+
+    room = new LK.Room({ adaptiveStream: true, dynacast: true });
+    const E = LK.RoomEvent;
+    room.on(E.TrackSubscribed, (track, _pub, p) => {
+      if (track.kind !== "audio") return;
+      const el = track.attach();
+      el.hidden = true;
+      document.body.append(el);
+      if (isAgent(p)) watchLevel(track);
+    });
+    room.on(E.ParticipantConnected, (p) => { if (isAgent(p)) agentJoined(p); });
+    room.on(E.ParticipantDisconnected, (p) => {
+      if (p === agent) hangUp("Nova left the room.", true);
+    });
+    room.on(E.ParticipantAttributesChanged, (changed, p) => {
+      if (isAgent(p) && "lk.agent.state" in changed) agentState(changed["lk.agent.state"]);
+    });
+    room.on(E.DataReceived, (payload, _p, _kind, topic) => {
+      if (topic !== TOPIC) return;
+      try { onControl(JSON.parse(new TextDecoder().decode(payload))); } catch { /* ignore */ }
+    });
+    room.on(E.Disconnected, () => { if (room) hangUp("Disconnected.", false); });
+    room.registerTextStreamHandler("lk.transcription", async (reader, info) => {
+      const text = (await reader.readAll()).trim();
+      if (!text) return;
+      const final = reader.info?.attributes?.["lk.transcription_final"];
+      const mine = info.identity === room?.localParticipant.identity;
+      if (mine && final === "false") return; // show the user's settled words only
+      addLine(mine ? "you" : "nova", text);
+    });
+
+    try {
+      await room.connect(ticket.url, ticket.token);
+      await room.localParticipant.setMicrophoneEnabled(true);
+    } catch (e) {
+      const why = /permission|notallowed/i.test(String(e)) ? "Microphone permission was denied." : "Could not reach the voice server.";
+      room = null;
+      say($("gate-msg"), why, true);
+      $("connect").disabled = false;
+      return;
+    }
+
+    $("gate").hidden = true;
+    $("live").hidden = false;
+    setState("connecting");
+    say($("live-msg"), "Waiting for Nova to join from the Pi…");
+    requestAnimationFrame(drawOrb);
+    const already = [...room.remoteParticipants.values()].find(isAgent);
+    if (already) agentJoined(already);
+    else joinTimer = setTimeout(() => {
+      if (!agent) say($("live-msg"), "Nova hasn't joined — is the Pi on and online?", true);
+    }, AGENT_JOIN_TIMEOUT_MS);
+  }
+
+  function hangUp(message = "", bad = false) {
+    clearTimeout(joinTimer);
+    const r = room;
+    room = null; agent = null; chimed = false; analyser = null;
+    if (r) r.disconnect();
+    document.querySelectorAll("body > audio").forEach((a) => a.remove());
+    $("transcript").replaceChildren();
+    $("metrics").textContent = "";
+    $("llm").hidden = true;
+    $("live").hidden = true;
+    $("gate").hidden = false;
+    $("connect").disabled = false;
+    $("mute").setAttribute("aria-pressed", "false");
+    $("mute").textContent = "Mute";
+    setState("idle");
+    say($("gate-msg"), message, bad);
+  }
+
+  // ---- wiring -------------------------------------------------------------
+  $("login").addEventListener("submit", (e) => {
+    e.preventDefault();
+    chime.load(); // a user gesture: lets the chime play later on iOS/Safari
+    connect($("passcode").value);
+  });
+  $("hangup").addEventListener("click", () => hangUp());
+  $("mute").addEventListener("click", async () => {
+    if (!room) return;
+    const muted = $("mute").getAttribute("aria-pressed") === "true";
+    await room.localParticipant.setMicrophoneEnabled(muted);
+    $("mute").setAttribute("aria-pressed", String(!muted));
+    $("mute").textContent = muted ? "Mute" : "Unmute";
+  });
+  $("llm").addEventListener("click", () => {
+    const next = llmMode === "local" ? "openrouter" : "local";
+    send({ type: "nova.settings.set", settings: { mode: next } });
+  });
+  window.addEventListener("beforeunload", () => room?.disconnect());
+})();

token_service.py

@@ -0,0 +1,107 @@
+"""Passcode check, LiveKit room tokens, and a login rate limit.
+
+Pure functions, no network: signing a LiveKit token is local HMAC with the API
+secret, so this service never talks to the SFU or the Pi. The browser and the
+Pi meet at the SFU; this only hands the browser a ticket that (a) joins one
+fresh room and (b) asks the SFU to dispatch exactly one agent -- the Pi.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import secrets
+import time
+from collections import defaultdict, deque
+from dataclasses import dataclass
+from datetime import timedelta
+
+from livekit import api
+
+# scrypt cost: ~50 ms on a small CPU. The hash lives in a secret, not a public
+# database, so this is defence in depth rather than the only barrier.
+_SCRYPT = {"n": 2**14, "r": 8, "p": 1}
+TOKEN_TTL_S = 600
+
+
+def _b64(b: bytes) -> str:
+    return base64.urlsafe_b64encode(b).decode().rstrip("=")
+
+
+def _unb64(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+def hash_passcode(passcode: str) -> str:
+    """'scrypt$n$r$p$salt$hash' -- stored as the NOVA_PASSCODE_HASH secret."""
+    salt = secrets.token_bytes(16)
+    digest = hashlib.scrypt(passcode.encode(), salt=salt, dklen=32, **_SCRYPT)
+    return f"scrypt${_SCRYPT['n']}${_SCRYPT['r']}${_SCRYPT['p']}${_b64(salt)}${_b64(digest)}"
+
+
+def verify_passcode(passcode: str, stored: str | None) -> bool:
+    """Constant-time check. A malformed stored hash never verifies."""
+    try:
+        scheme, n, r, p, salt, want = (stored or "").split("$")
+        if scheme != "scrypt":
+            return False
+        want_b = _unb64(want)
+        got = hashlib.scrypt(
+            passcode.encode(), salt=_unb64(salt), dklen=len(want_b), n=int(n), r=int(r), p=int(p)
+        )
+    except (ValueError, TypeError):
+        return False
+    return hmac.compare_digest(got, want_b)
+
+
+@dataclass(frozen=True)
+class Session:
+    room: str
+    identity: str
+    token: str
+    expires_in: int
+
+
+def mint_session(*, api_key: str, api_secret: str, agent_name: str) -> Session:
+    room = f"nova-{secrets.token_hex(4)}"
+    identity = f"web-{secrets.token_hex(4)}"
+    token = (
+        api.AccessToken(api_key, api_secret)
+        .with_identity(identity)
+        .with_ttl(timedelta(seconds=TOKEN_TTL_S))
+        .with_grants(
+            api.VideoGrants(
+                room_join=True,
+                room=room,
+                can_subscribe=True,
+                can_publish=True,
+                # a voice session: the mic only -- no camera, no screen share
+                can_publish_sources=["microphone"],
+                can_publish_data=True,  # nova.control settings messages
+            )
+        )
+        .with_room_config(
+            api.RoomConfiguration(agents=[api.RoomAgentDispatch(agent_name=agent_name)])
+        )
+        .to_jwt()
+    )
+    return Session(room=room, identity=identity, token=token, expires_in=TOKEN_TTL_S)
+
+
+class RateLimiter:
+    """Sliding window per caller. In memory: one process, a demo-sized budget."""
+
+    def __init__(self, *, max_attempts: int = 5, window_s: float = 300.0) -> None:
+        self._max = max_attempts
+        self._window = window_s
+        self._hits: dict[str, deque[float]] = defaultdict(deque)
+
+    def allow(self, key: str, *, now: float | None = None) -> bool:
+        now = time.monotonic() if now is None else now
+        hits = self._hits[key]
+        while hits and now - hits[0] >= self._window:
+            hits.popleft()
+        if len(hits) >= self._max:
+            return False
+        hits.append(now)
+        return True