engramx 2.0.0 → 2.0.2

package/CHANGELOG.md

@@ -4,6 +4,125 @@ All notable changes to engram are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.2] — 2026-04-18 — Security hotfix: HTTP server auth & CORS
+
+**This is a security release. Upgrade immediately if you run `engram server`
+or `engram ui`.** Credit: [@gabiudrescu](https://github.com/gabiudrescu) for
+responsible disclosure ([#7](https://github.com/NickCirv/engram/issues/7)).
+
+### Security — fixed
+
+- **Graph exfiltration + persistent prompt injection via cross-origin browser
+  tabs.** The HTTP server previously shipped with `Access-Control-Allow-Origin: *`
+  on every response and defaulted to no authentication. A malicious page the
+  developer visited could `fetch('http://127.0.0.1:7337/query')` to steal the
+  local graph, then `POST /learn` (with `Content-Type: text/plain`, a
+  CORS-safelisted content type) to persist `bug:` / `fix:` patterns that the
+  v2 Sentinel handlers later re-injected into the user's coding agent on
+  SessionStart and on every Edit/Write of the named file. Severity: High —
+  confidentiality + persistent indirect prompt injection.
+
+  **Fix (four stacked defenses):**
+  1. **Fail-closed auth.** Every route except `/health` and `/favicon.ico`
+     now requires `Authorization: Bearer <token>` or an HttpOnly
+     `engram_token` cookie. A random 64-character token is auto-generated
+     on first server start and persisted to `~/.engram/http-server.token`
+     with mode `0600`. `ENGRAM_API_TOKEN` env var still overrides.
+  2. **No wildcard CORS.** `Access-Control-Allow-Origin: *` has been removed
+     from every response. By default no CORS headers are emitted — the
+     dashboard is same-origin. Additional origins opt in via
+     `ENGRAM_ALLOWED_ORIGINS=a.com,b.com`.
+  3. **Host + Origin validation** (DNS-rebinding defense). Requests with a
+     `Host` header other than `127.0.0.1|localhost|::1` on the bound port
+     return 400. Requests with an `Origin` not in the same-origin or env
+     allowlist return 403.
+  4. **`Content-Type: application/json` enforced on mutations.** POST / PUT /
+     DELETE without `application/json` return 415. This blocks the
+     `text/plain` CSRF vector from the PoC and forces CORS preflight for
+     any cross-origin writer.
+
+- **Timing side-channel on token comparison.** The previous
+  `header === \`Bearer ${token}\`` comparison was not constant-time.
+  Replaced with a length-first, constant-time `safeEqual()`.
+
+### Added
+
+- `src/server/auth.ts` — token management (get-or-create, safeEqual, cookie
+  parsing, Host/Origin validators).
+- `tests/server/security.test.ts` — PoC-style tests covering fail-closed
+  auth (including empty Bearer / empty cookie guards), env-downgrade
+  rejection (token is snapshot at start), cookie auth, wildcard-CORS
+  absence, same-origin echo, foreign-origin 403, Host header validation
+  (including no-port rejection + case-insensitive hostname), `text/plain`
+  rejection on `/learn`, the `/ui?token=` cross-site oracle defence via
+  `Sec-Fetch-Site` gating, and the end-to-end exploit chain from #7.
+- `SECURITY.md` at repo root with disclosure policy and scope.
+- `GET /ui?token=<t>` bootstrap path for the browser dashboard. The CLI
+  passes the token once; the server exchanges it for an HttpOnly cookie via
+  a 302 redirect and strips the token from the URL. Dashboard JS never sees
+  the raw token.
+
+### Changed
+
+- `createHttpServer(projectRoot, port)` now resolves to `Promise<TokenInfo>`
+  (previously `Promise<void>`). The returned object exposes the token source
+  (env / file / generated) and the token file path. The CLI uses this to
+  print a one-time banner pointing users at `~/.engram/http-server.token`
+  when a fresh token is minted.
+- `checkAuth` rewritten as fail-closed, accepts Bearer header OR
+  `engram_token` cookie, uses constant-time comparison.
+- Server-Sent Events endpoint (`/api/sse`) no longer emits wildcard CORS and
+  inherits the same origin-allowlist behavior as every other route.
+
+### Breaking
+
+- **External callers (curl, scripts, CI probes) must now send the token.**
+  Fix the one-liner on each caller:
+  ```bash
+  curl -H "Authorization: Bearer $(cat ~/.engram/http-server.token)" \
+       http://127.0.0.1:7337/stats
+  ```
+- Requests with `Host: something-else.com` are rejected 400 even if they
+  resolve to 127.0.0.1 locally. DNS rebinding defense — intended behavior.
+- Cross-origin requests (`Origin: https://example.com`) are rejected 403
+  unless the origin is in `ENGRAM_ALLOWED_ORIGINS`. No legitimate caller
+  should be affected.
+- `/ui` navigation from the browser now requires `?token=<t>` on first visit
+  (set automatically when you run `engram ui`) or a pre-existing
+  `engram_token` cookie.
+
+## [2.0.1] — 2026-04-17 — Windows CI + favicon route
+
+Patch release fixing two issues caught immediately after v2.0.0 shipped.
+
+### Fixed
+
+- **Windows cross-platform bug in the plugin loader.** `PLUGINS_DIR` was a
+  module-load-time constant that baked in `homedir()` at import time. Windows
+  uses `USERPROFILE` while Unix uses `HOME`, and a frozen constant meant any
+  runtime override (tests, future `--plugins-dir` flag, programmatic use)
+  couldn't take effect without a module reload. Windows CI failed on the
+  plugin-loader tests because `process.env.HOME` mutation had no effect.
+  Fixed by introducing `getPluginsDir()` that resolves on every call, and
+  accepting an optional `dir` parameter on `loadPlugins()`,
+  `getLoadedPlugins()`, and `ensurePluginsDir()`. The `PLUGINS_DIR` constant
+  is retained for back-compat but runtime paths now go through the getter.
+- **`/favicon.ico` returning 404 for clients that ignore `<link rel="icon">`.**
+  Added an explicit `GET /favicon.ico` route to the HTTP server that serves
+  a 238-byte inline SVG favicon with `Cache-Control: public, max-age=86400`.
+  The dashboard HTML still inlines the same favicon via `<link>` so modern
+  browsers avoid the request entirely.
+
+### Changed
+
+- Test count: 640 → 641 (+1 for the "plugins directory does not exist"
+  branch of `loadPlugins()`).
+
+### CI
+
+- Verified green on GitHub Actions matrix: Ubuntu + Windows × Node 20 + 22.
+  Commit `7c6001c`.
+
 ## [2.0.0] — 2026-04-17 — "Ecosystem"
 
 The biggest release since v1.0.0. Completes the v2.0 roadmap Phases 1–4:

package/dist/auth-KB2ZRMS3.js

@@ -0,0 +1,14 @@
+import {
+  getOrCreateToken,
+  isHostValid,
+  isOriginAllowed,
+  parseCookies,
+  safeEqual
+} from "./chunk-N6PPKOPK.js";
+export {
+  getOrCreateToken,
+  isHostValid,
+  isOriginAllowed,
+  parseCookies,
+  safeEqual
+};

package/dist/chunk-N6PPKOPK.js

@@ -0,0 +1,105 @@
+// src/server/auth.ts
+import { randomBytes } from "crypto";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync
+} from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var TOKEN_MIN_LEN = 32;
+var TOKEN_BYTES = 32;
+function tokenDir() {
+  return join(homedir(), ".engram");
+}
+function tokenPath() {
+  return join(tokenDir(), "http-server.token");
+}
+function getOrCreateToken() {
+  const envToken = process.env.ENGRAM_API_TOKEN;
+  if (envToken && envToken.length >= TOKEN_MIN_LEN) {
+    return { token: envToken, source: "env", path: null };
+  }
+  const path = tokenPath();
+  if (existsSync(path)) {
+    try {
+      const cached = readFileSync(path, "utf8").trim();
+      if (cached.length >= TOKEN_MIN_LEN) {
+        return { token: cached, source: "file", path };
+      }
+    } catch {
+    }
+  }
+  const fresh = randomBytes(TOKEN_BYTES).toString("hex");
+  const dir = tokenDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(path, fresh + "\n", { mode: 384 });
+  try {
+    chmodSync(path, 384);
+  } catch {
+  }
+  return { token: fresh, source: "generated", path };
+}
+function safeEqual(a, b) {
+  if (a.length === 0 || b.length === 0) return false;
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+function parseCookies(header) {
+  const out = {};
+  if (!header || typeof header !== "string") return out;
+  for (const pair of header.split(/;\s*/)) {
+    const eq = pair.indexOf("=");
+    if (eq < 0) continue;
+    const key = pair.slice(0, eq).trim();
+    const value = pair.slice(eq + 1).trim();
+    if (key) out[key] = value;
+  }
+  return out;
+}
+function isHostValid(hostHeader, port) {
+  if (!hostHeader) return false;
+  let hostname;
+  let portStr;
+  if (hostHeader.startsWith("[")) {
+    const close = hostHeader.indexOf("]");
+    if (close < 0) return false;
+    hostname = hostHeader.slice(1, close);
+    portStr = hostHeader.slice(close + 2);
+  } else {
+    const colon = hostHeader.lastIndexOf(":");
+    if (colon < 0) {
+      hostname = hostHeader;
+      portStr = "";
+    } else {
+      hostname = hostHeader.slice(0, colon);
+      portStr = hostHeader.slice(colon + 1);
+    }
+  }
+  const h = hostname.toLowerCase();
+  if (h !== "127.0.0.1" && h !== "localhost" && h !== "::1") return false;
+  if (portStr !== String(port)) return false;
+  return true;
+}
+function isOriginAllowed(origin, port) {
+  if (origin === `http://127.0.0.1:${port}`) return true;
+  if (origin === `http://localhost:${port}`) return true;
+  const env = process.env.ENGRAM_ALLOWED_ORIGINS;
+  if (!env) return false;
+  const list = env.split(",").map((s) => s.trim()).filter(Boolean);
+  return list.includes(origin);
+}
+
+export {
+  getOrCreateToken,
+  safeEqual,
+  parseCookies,
+  isHostValid,
+  isOriginAllowed
+};

package/dist/cli.js

@@ -1351,7 +1351,7 @@ var BUILTIN_PROVIDERS = [
 ];
 var BUILTIN_NAMES = new Set(BUILTIN_PROVIDERS.map((p) => p.name));
 async function getAllProviders() {
-  const { getLoadedPlugins } = await import("./plugin-loader-FCOMVOX7.js");
+  const { getLoadedPlugins } = await import("./plugin-loader-STTGYIL5.js");
   const { loaded } = await getLoadedPlugins();
   const safePlugins = loaded.filter((p) => !BUILTIN_NAMES.has(p.name));
   return [...BUILTIN_PROVIDERS, ...safePlugins];
@@ -3605,12 +3605,12 @@ program.command("stress-test").description("Run stress tests: memory, concurrenc
   }
 });
 program.command("server").description("Start engram HTTP REST server (binds to 127.0.0.1 only)").option("--http", "Enable HTTP server (default)").option("--port <port>", "HTTP port", "7337").option("-p, --project <path>", "Project directory", ".").action(async (opts) => {
-  const { startHttpServer } = await import("./server-VBRTTECZ.js");
+  const { startHttpServer } = await import("./server-KUG7U6SG.js");
   await startHttpServer(pathResolve(opts.project), parseInt(opts.port, 10));
 });
 program.command("ui").description("Open the web dashboard (auto-starts HTTP server if needed)").option("--port <port>", "HTTP port", "7337").option("-p, --project <path>", "Project directory", ".").option("--no-open", "Don't launch browser, just print the URL").action(async (opts) => {
   const port = parseInt(opts.port, 10);
-  const url = `http://127.0.0.1:${port}/ui`;
+  const publicUrl = `http://127.0.0.1:${port}/ui`;
   const projectRoot = pathResolve(opts.project);
   const { existsSync: existsSync10, readFileSync: readFileSync6 } = await import("fs");
   const pidPath = join9(projectRoot, ".engram", "http-server.pid");
@@ -3624,9 +3624,9 @@ program.command("ui").description("Open the web dashboard (auto-starts HTTP serv
     }
   }
   if (alreadyRunning) {
-    console.log(chalk2.dim(`engram server already running \u2014 opening ${url}`));
+    console.log(chalk2.dim(`engram server already running \u2014 opening ${publicUrl}`));
   } else {
-    console.log(chalk2.dim(`Starting engram server on ${url}...`));
+    console.log(chalk2.dim(`Starting engram server on ${publicUrl}...`));
     const { spawn } = await import("child_process");
     const child = spawn(
       process.argv[0],
@@ -3636,15 +3636,19 @@ program.command("ui").description("Open the web dashboard (auto-starts HTTP serv
     child.unref();
     await new Promise((r) => setTimeout(r, 500));
   }
-  console.log(chalk2.green(`\u2713 Dashboard: ${url}`));
+  const { getOrCreateToken } = await import("./auth-KB2ZRMS3.js");
+  const { token } = getOrCreateToken();
+  const bootUrl = `${publicUrl}?token=${encodeURIComponent(token)}`;
+  console.log(chalk2.green(`\u2713 Dashboard: ${publicUrl}`));
   if (opts.open !== false) {
     const { platform } = process;
     const opener = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
     try {
       const { execFile: execFile4 } = await import("child_process");
-      execFile4(opener, [url], { shell: platform === "win32" }, () => {
+      execFile4(opener, [bootUrl], { shell: platform === "win32" }, () => {
       });
     } catch {
+      console.log(chalk2.dim(`  Open manually: ${bootUrl}`));
     }
   }
 });
@@ -3798,13 +3802,14 @@ dbCmd.command("rollback").description("Roll back to an earlier schema version (D
 });
 var pluginCmd = program.command("plugin").description("Manage context provider plugins");
 pluginCmd.command("list").description("List installed provider plugins").action(async () => {
-  const { loadPlugins, PLUGINS_DIR, ensurePluginsDir } = await import("./plugin-loader-FCOMVOX7.js");
-  ensurePluginsDir();
-  const { loaded, failed } = await loadPlugins();
+  const { loadPlugins, getPluginsDir, ensurePluginsDir } = await import("./plugin-loader-STTGYIL5.js");
+  const dir = getPluginsDir();
+  ensurePluginsDir(dir);
+  const { loaded, failed } = await loadPlugins(dir);
   if (loaded.length === 0 && failed.length === 0) {
     console.log(chalk2.dim(`No plugins installed.`));
     console.log(chalk2.dim(`Install with: engram plugin install <file.mjs>`));
-    console.log(chalk2.dim(`Plugins directory: ${PLUGINS_DIR}`));
+    console.log(chalk2.dim(`Plugins directory: ${dir}`));
     return;
   }
   if (loaded.length > 0) {
@@ -3830,7 +3835,7 @@ pluginCmd.command("list").description("List installed provider plugins").action(
 pluginCmd.command("install").description("Install a plugin by copying its .mjs file into ~/.engram/plugins/").argument("<file>", "Path to plugin .mjs file").action(async (file) => {
   const { copyFileSync: copyFileSync2, statSync: statSync5 } = await import("fs");
   const { basename: basename6 } = await import("path");
-  const { PLUGINS_DIR, ensurePluginsDir, validatePlugin } = await import("./plugin-loader-FCOMVOX7.js");
+  const { getPluginsDir, ensurePluginsDir, validatePlugin } = await import("./plugin-loader-STTGYIL5.js");
   const { pathToFileURL } = await import("url");
   const absPath = pathResolve(file);
   if (!existsSync9(absPath)) {
@@ -3859,18 +3864,20 @@ pluginCmd.command("install").description("Install a plugin by copying its .mjs f
     console.error(chalk2.red(`Failed to load plugin: ${e.message}`));
     process.exit(1);
   }
-  ensurePluginsDir();
+  const pluginsDir = getPluginsDir();
+  ensurePluginsDir(pluginsDir);
   const destName = basename6(absPath);
-  const destPath = join9(PLUGINS_DIR, destName);
+  const destPath = join9(pluginsDir, destName);
   copyFileSync2(absPath, destPath);
   console.log(chalk2.green(`\u2713 Installed: ${destPath}`));
 });
 pluginCmd.command("remove").description("Remove an installed plugin by filename").argument("<filename>", "Plugin filename (e.g., my-provider.mjs)").action(async (filename) => {
-  const { PLUGINS_DIR } = await import("./plugin-loader-FCOMVOX7.js");
-  const target = join9(PLUGINS_DIR, filename);
+  const { getPluginsDir } = await import("./plugin-loader-STTGYIL5.js");
+  const pluginsDir = getPluginsDir();
+  const target = join9(pluginsDir, filename);
   if (!existsSync9(target)) {
     console.error(chalk2.red(`No such plugin: ${filename}`));
-    console.log(chalk2.dim(`Plugins directory: ${PLUGINS_DIR}`));
+    console.log(chalk2.dim(`Plugins directory: ${pluginsDir}`));
     process.exit(1);
   }
   unlinkSync(target);

package/dist/{plugin-loader-FCOMVOX7.js → plugin-loader-STTGYIL5.js}

@@ -3,10 +3,14 @@ import { existsSync, readdirSync, mkdirSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
 import { pathToFileURL } from "url";
-var PLUGINS_DIR = join(homedir(), ".engram", "plugins");
-function ensurePluginsDir() {
-  if (!existsSync(PLUGINS_DIR)) {
-    mkdirSync(PLUGINS_DIR, { recursive: true });
+function getPluginsDir() {
+  return join(homedir(), ".engram", "plugins");
+}
+var PLUGINS_DIR = getPluginsDir();
+function ensurePluginsDir(dir) {
+  const target = dir ?? getPluginsDir();
+  if (!existsSync(target)) {
+    mkdirSync(target, { recursive: true });
   }
 }
 function validatePlugin(mod) {
@@ -48,20 +52,21 @@ function validatePlugin(mod) {
   }
   return { plugin: candidate, reason: "" };
 }
-async function loadPlugins() {
+async function loadPlugins(dir) {
+  const pluginsDir = dir ?? getPluginsDir();
   const loaded = [];
   const failed = [];
-  if (!existsSync(PLUGINS_DIR)) {
+  if (!existsSync(pluginsDir)) {
     return { loaded, failed };
   }
   let files;
   try {
-    files = readdirSync(PLUGINS_DIR).filter((f) => f.endsWith(".mjs") || f.endsWith(".js"));
+    files = readdirSync(pluginsDir).filter((f) => f.endsWith(".mjs") || f.endsWith(".js"));
   } catch {
     return { loaded, failed };
   }
   for (const file of files) {
-    const fullPath = join(PLUGINS_DIR, file);
+    const fullPath = join(pluginsDir, file);
     try {
       const mod = await import(pathToFileURL(fullPath).href);
       const { plugin, reason } = validatePlugin(mod);
@@ -81,9 +86,9 @@ async function loadPlugins() {
   return { loaded, failed };
 }
 var _cache = null;
-async function getLoadedPlugins() {
+async function getLoadedPlugins(dir) {
   if (_cache === null) {
-    _cache = await loadPlugins();
+    _cache = await loadPlugins(dir);
   }
   return _cache;
 }
@@ -95,6 +100,7 @@ export {
   _resetPluginCache,
   ensurePluginsDir,
   getLoadedPlugins,
+  getPluginsDir,
   loadPlugins,
   validatePlugin
 };

package/dist/{server-VBRTTECZ.js → server-KUG7U6SG.js}

@@ -2,6 +2,13 @@ import {
   ContextCache,
   getContextCache
 } from "./chunk-CIQQ5Y3S.js";
+import {
+  getOrCreateToken,
+  isHostValid,
+  isOriginAllowed,
+  parseCookies,
+  safeEqual
+} from "./chunk-N6PPKOPK.js";
 import {
   getComponentStatus,
   summarizeHookLog
@@ -1006,6 +1013,14 @@ var PROVIDERS = [
   "context7",
   "obsidian"
 ];
+var serverToken = "";
+var serverPort = 0;
+function currentToken() {
+  return serverToken;
+}
+function authCookie(token) {
+  return `engram_token=${token}; HttpOnly; SameSite=Strict; Path=/`;
+}
 function parseUrl(req) {
   return new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
 }
@@ -1014,23 +1029,42 @@ async function readBody(req) {
   for await (const chunk of req) chunks.push(chunk);
   return Buffer.concat(chunks).toString("utf-8");
 }
-function json(res, status, data) {
+function corsHeaders(req) {
+  const origin = req.headers.origin;
+  if (!origin || !isOriginAllowed(origin, serverPort)) return {};
+  return {
+    "Access-Control-Allow-Origin": origin,
+    "Access-Control-Allow-Credentials": "true",
+    "Vary": "Origin"
+  };
+}
+function json(res, status, data, extraHeaders = {}) {
   res.writeHead(status, {
     "Content-Type": "application/json",
-    "Access-Control-Allow-Origin": "*",
-    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-    "Access-Control-Allow-Headers": "Authorization, Content-Type"
+    ...extraHeaders
   });
   res.end(JSON.stringify(data));
 }
 function checkAuth(req, res) {
-  const token = process.env.ENGRAM_API_TOKEN;
-  if (!token) return true;
-  const header = req.headers.authorization ?? "";
-  if (header === `Bearer ${token}`) return true;
+  const expected = currentToken();
+  const auth = req.headers.authorization ?? "";
+  if (auth.startsWith("Bearer ")) {
+    const presented = auth.slice(7).trim();
+    if (safeEqual(presented, expected)) return true;
+  }
+  const cookies = parseCookies(req.headers.cookie);
+  if (cookies.engram_token && safeEqual(cookies.engram_token, expected)) {
+    return true;
+  }
   json(res, 401, { error: "Unauthorized" });
   return false;
 }
+function requireJsonContentType(req, res) {
+  const ct = (req.headers["content-type"] ?? "").toLowerCase();
+  if (ct.startsWith("application/json")) return true;
+  json(res, 415, { error: "Content-Type must be application/json" });
+  return false;
+}
 function handleHealth(_req, res, startedAt) {
   json(res, 200, {
     ok: true,
@@ -1219,12 +1253,12 @@ async function handleGraphGodNodes(_req, res, projectRoot) {
 }
 var sseClients = /* @__PURE__ */ new Set();
 var hookLogWatcher = null;
-function handleSSE(_req, res, projectRoot) {
+function handleSSE(req, res, projectRoot) {
   res.writeHead(200, {
     "Content-Type": "text/event-stream",
     "Cache-Control": "no-cache",
     "Connection": "keep-alive",
-    "Access-Control-Allow-Origin": "*"
+    ...corsHeaders(req)
   });
   res.write('data: {"type":"connected"}\n\n');
   sseClients.add(res);
@@ -1277,23 +1311,73 @@ function removePid(projectRoot) {
 function createHttpServer(projectRoot, port) {
   return new Promise((resolve, reject) => {
     const startedAt = Date.now();
+    const tokenInfo = getOrCreateToken();
+    serverToken = tokenInfo.token;
+    serverPort = port;
     const server = createServer(async (req, res) => {
+      if (!isHostValid(req.headers.host, port)) {
+        res.writeHead(400);
+        res.end();
+        return;
+      }
+      const origin = req.headers.origin;
+      if (origin && !isOriginAllowed(origin, port)) {
+        res.writeHead(403);
+        res.end();
+        return;
+      }
+      if (origin && isOriginAllowed(origin, port)) {
+        res.setHeader("Access-Control-Allow-Origin", origin);
+        res.setHeader("Access-Control-Allow-Credentials", "true");
+        res.setHeader("Vary", "Origin");
+      }
       if (req.method === "OPTIONS") {
         res.writeHead(204, {
-          "Access-Control-Allow-Origin": "*",
           "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
           "Access-Control-Allow-Headers": "Authorization, Content-Type"
         });
         res.end();
         return;
       }
-      if (!checkAuth(req, res)) return;
       const url = parseUrl(req);
       const path = url.pathname;
+      if (req.method === "GET" && path === "/health") {
+        handleHealth(req, res, startedAt);
+        return;
+      }
+      if (req.method === "GET" && path === "/favicon.ico") {
+        const svg = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><rect width="100" height="100" rx="20" fill="#0a0a0b"/><text x="50" y="62" font-size="56" text-anchor="middle" fill="#10b981" font-family="Menlo,monospace">&#9670;</text></svg>';
+        res.writeHead(200, {
+          "Content-Type": "image/svg+xml",
+          "Cache-Control": "public, max-age=86400"
+        });
+        res.end(svg);
+        return;
+      }
+      if (req.method === "GET" && (path === "/ui" || path === "/ui/")) {
+        const queryToken = url.searchParams.get("token");
+        if (queryToken) {
+          const fetchSite = req.headers["sec-fetch-site"];
+          const siteOk = fetchSite === void 0 || fetchSite === "none" || fetchSite === "same-origin";
+          if (siteOk && safeEqual(queryToken, currentToken())) {
+            res.writeHead(302, {
+              Location: "/ui",
+              "Set-Cookie": authCookie(currentToken()),
+              "Referrer-Policy": "no-referrer",
+              "Cache-Control": "no-store",
+              "X-Content-Type-Options": "nosniff"
+            });
+            res.end();
+            return;
+          }
+        }
+      }
+      if (!checkAuth(req, res)) return;
+      if (req.method === "POST" || req.method === "PUT" || req.method === "DELETE") {
+        if (!requireJsonContentType(req, res)) return;
+      }
       try {
-        if (req.method === "GET" && path === "/health") {
-          handleHealth(req, res, startedAt);
-        } else if (req.method === "GET" && path === "/query") {
+        if (req.method === "GET" && path === "/query") {
           await handleQuery(req, res, projectRoot);
         } else if (req.method === "GET" && path === "/stats") {
           await handleStats(req, res, projectRoot);
@@ -1322,7 +1406,9 @@ function createHttpServer(projectRoot, port) {
         } else if (req.method === "GET" && (path === "/ui" || path === "/ui/")) {
           res.writeHead(200, {
             "Content-Type": "text/html; charset=utf-8",
-            "Cache-Control": "no-cache"
+            "Cache-Control": "no-cache",
+            "Set-Cookie": authCookie(currentToken()),
+            "X-Content-Type-Options": "nosniff"
           });
           res.end(buildDashboardHtml());
         } else {
@@ -1344,7 +1430,7 @@ function createHttpServer(projectRoot, port) {
       };
       process.on("SIGINT", cleanup);
       process.on("SIGTERM", cleanup);
-      resolve();
+      resolve(tokenInfo);
     });
   });
 }
@@ -1352,11 +1438,26 @@ function createHttpServer(projectRoot, port) {
 // src/server/index.ts
 var DEFAULT_PORT = 7337;
 async function startHttpServer(projectRoot, port = DEFAULT_PORT) {
-  await createHttpServer(projectRoot, port);
-  process.stdout.write(
-    `engram HTTP server listening on http://127.0.0.1:${port}
+  const tokenInfo = await createHttpServer(projectRoot, port);
+  const url = `http://127.0.0.1:${port}`;
+  process.stdout.write(`engram HTTP server listening on ${url}
+`);
+  if (tokenInfo.source === "env") {
+    process.stderr.write(
+      "engram: auth token from ENGRAM_API_TOKEN env var\n"
+    );
+  } else if (tokenInfo.source === "file") {
+    process.stderr.write(
+      `engram: auth token at ${tokenInfo.path}
+`
+    );
+  } else {
+    process.stderr.write(
+      `engram: auth token generated at ${tokenInfo.path} (0600)
+        curl -H "Authorization: Bearer $(cat ${tokenInfo.path})" ${url}/stats
 `
-  );
+    );
+  }
 }
 export {
   startHttpServer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engramx",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "The context spine for AI coding agents. 8 providers + pluggable context sources, 3-layer memory cache, web dashboard, multi-IDE support (Claude Code, Cursor, Continue, Zed, Aider, Windsurf, Neovim, Emacs). 88.1% measured session-level token savings. Local SQLite, zero native deps, zero cloud.",
   "repository": {
     "type": "git",