@schlessera/brain-ui-server 0.13.1 → 0.15.0

package/src/middleware/passkeys.ts

@@ -1,5 +1,6 @@
 import { Hono } from "hono";
 import type { Context } from "hono";
+import type { Database } from "bun:sqlite";
 import {
   generateAuthenticationOptions,
   generateRegistrationOptions,
@@ -13,13 +14,14 @@ import type {
 } from "@simplewebauthn/server";
 import {
   type AuthMode,
+  type AuthRuntime,
   issueSessionCookie,
   consumeLoginToken,
   LOGIN_RATE_LIMIT,
   GLOBAL_LOGIN_RATE_LIMIT,
 } from "./auth.js";
 import { clientIp } from "./tailscale.js";
-import { getDb } from "../db/client.js";
+import type { WebAuthnConfig } from "../config/env.js";
 
 /**
  * WebAuthn passkeys as an extension of `password` mode: the password bootstraps
@@ -27,27 +29,33 @@ import { getDb } from "../db/client.js";
  * login. A successful assertion mints the same session cookie as password login
  * (issueSessionCookie), so authGuard / isWsAuthorized / TTL are untouched.
  *
- * Self-contained on purpose — this module (plus its auth.ts imports) is slated
- * to move wholesale into @schlessera/ui-server.
+ * Everything environmental is injected as a {@link PasskeyContext} — the
+ * resolved WebAuthn identity, the auth runtime (for trust/proxy semantics and
+ * the cookie secret), the origin allowlist, and the app's own database.
  *
  * Credentials are RP-scoped: a credential registered on localhost does not
  * exist for the production domain and vice versa. Rows carry rp_id so all
  * environments share the table.
  */
 
+/** Injected per-app dependencies for every passkey route and helper. */
+export interface PasskeyContext {
+  db: Database;
+  webauthn: WebAuthnConfig;
+  auth: AuthRuntime;
+  /** ALLOWED_ORIGINS — split-topology origins also valid for ceremonies. */
+  allowedOrigins: string[];
+}
+
 const CHALLENGE_TTL_MS = 120_000; // > the 60s ceremony timeout
 // Pending challenges are unauthenticated state; cap and evict oldest-first so
 // login-options spam can't grow memory. Losing one costs a retried ceremony.
 const MAX_PENDING_CHALLENGES = 100;
 const OPTIONS_RATE_LIMIT = 10; // login-options per IP per minute (own bucket)
-// Branding/identity are config-injected with the historical values as
-// defaults, so existing deployments keep their credentials.
-function rpName(): string {
-  return process.env.WEBAUTHN_RP_NAME || "Brain UI";
-}
-// The single "user" every passkey belongs to. Stable across registrations so
-// an authenticator overwrites its existing entry instead of stacking
-// duplicates for the same site.
+
+// The single "user" every passkey belongs to (webauthn.userId). Stable across
+// registrations so an authenticator overwrites its existing entry instead of
+// stacking duplicates for the same site.
 //
 // WARNING: the user handle is part of the WebAuthn wire contract — it is
 // burned into every resident credential at registration. Changing
@@ -55,25 +63,20 @@ function rpName(): string {
 // (authenticators will present a handle the server no longer recognizes as
 // the same user and re-registration stacks a second entry). Set it before the
 // first passkey is registered and never change it.
-function userName(): string {
-  return process.env.WEBAUTHN_USER_NAME || "owner";
+function userId(webauthn: WebAuthnConfig): Uint8Array<ArrayBuffer> {
+  return new TextEncoder().encode(webauthn.userId) as Uint8Array<ArrayBuffer>;
 }
+
 /** WebAuthn caps `user.id` at 64 bytes; browsers reject anything longer. */
 const MAX_USER_ID_BYTES = 64;
 
-function userId(): Uint8Array<ArrayBuffer> {
-  return new TextEncoder().encode(
-    process.env.WEBAUTHN_USER_ID || "brain-ui-owner"
-  ) as Uint8Array<ArrayBuffer>;
-}
-
 /**
  * Refuse to boot on a WebAuthn user handle the browser would reject. Called
  * from createApp(): an oversized handle otherwise produces registration
  * options that look fine server-side and fail silently in every browser.
  */
-export function assertPasskeyConfig(): void {
-  const bytes = userId().byteLength;
+export function assertPasskeyConfig(webauthn: WebAuthnConfig): void {
+  const bytes = userId(webauthn).byteLength;
   if (bytes > MAX_USER_ID_BYTES) {
     throw new Error(
       `WEBAUTHN_USER_ID is ${bytes} bytes; WebAuthn allows at most ${MAX_USER_ID_BYTES}. ` +
@@ -136,13 +139,6 @@ function challengeFromResponse(response: {
 
 // --- RP / origin resolution ---
 
-function envList(name: string): string[] {
-  return (process.env[name] ?? "")
-    .split(",")
-    .map((s) => s.trim())
-    .filter(Boolean);
-}
-
 function isLoopbackHostname(hostname: string): boolean {
   return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
 }
@@ -153,7 +149,7 @@ function isLoopbackHostname(hostname: string): boolean {
  * unconfigured. WEBAUTHN_ORIGINS / WEBAUTHN_RP_ID remain as overrides for
  * proxies that rewrite Host.
  */
-function resolveRp(c: Context): { rpID: string; origin: string } | null {
+function resolveRp(c: Context, ctx: PasskeyContext): { rpID: string; origin: string } | null {
   const origin = c.req.header("origin");
   if (!origin) return null;
 
@@ -165,22 +161,21 @@ function resolveRp(c: Context): { rpID: string; origin: string } | null {
   }
 
   const allowed =
-    envList("WEBAUTHN_ORIGINS").includes(origin) ||
-    envList("ALLOWED_ORIGINS").includes(origin) ||
+    ctx.webauthn.origins.includes(origin) ||
+    ctx.allowedOrigins.includes(origin) ||
     url.host === c.req.header("host") ||
     // Dev escape hatch: the vite proxy sets changeOrigin, so the server sees
     // Host localhost:3000 but Origin http://localhost:5173. Opt-in via an
     // explicit flag — NOT NODE_ENV, whose absence must never widen the RP.
-    (process.env.BRAIN_UI_ALLOW_LOOPBACK_ORIGIN === "1" &&
-      isLoopbackHostname(url.hostname));
+    (ctx.webauthn.allowLoopbackOrigin && isLoopbackHostname(url.hostname));
   if (!allowed) return null;
 
-  return { rpID: process.env.WEBAUTHN_RP_ID ?? url.hostname, origin };
+  return { rpID: ctx.webauthn.rpId ?? url.hostname, origin };
 }
 
 /** rpID for endpoints where same-origin GETs legitimately omit Origin. */
-function rpIdForRead(c: Context): string {
-  if (process.env.WEBAUTHN_RP_ID) return process.env.WEBAUTHN_RP_ID;
+function rpIdForRead(c: Context, ctx: PasskeyContext): string {
+  if (ctx.webauthn.rpId) return ctx.webauthn.rpId;
   const origin = c.req.header("origin");
   if (origin) {
     try {
@@ -224,14 +219,14 @@ function toSummary(row: CredentialRow) {
   };
 }
 
-function credentialsForRp(rpID: string): CredentialRow[] {
-  return getDb()
+function credentialsForRp(db: Database, rpID: string): CredentialRow[] {
+  return db
     .query("SELECT * FROM passkey_credentials WHERE rp_id = ?")
     .all(rpID) as CredentialRow[];
 }
 
-function credentialById(id: string): CredentialRow | null {
-  return getDb()
+function credentialById(db: Database, id: string): CredentialRow | null {
+  return db
     .query("SELECT * FROM passkey_credentials WHERE id = ?")
     .get(id) as CredentialRow | null;
 }
@@ -263,11 +258,11 @@ function notEnabled(c: Context) {
  * until it has its own credential. Host-derived rpID is fine here: a forged
  * Host can at most re-enable password auth, which still requires the password.
  */
-export function passwordLoginDisabled(c: Context): boolean {
-  if (process.env.BRAIN_UI_ALLOW_PASSWORD === "1") return false;
-  const row = getDb()
+export function passwordLoginDisabled(c: Context, ctx: PasskeyContext): boolean {
+  if (ctx.auth.allowPassword) return false;
+  const row = ctx.db
     .query("SELECT COUNT(*) AS n FROM passkey_credentials WHERE rp_id = ?")
-    .get(rpIdForRead(c)) as { n: number };
+    .get(rpIdForRead(c, ctx)) as { n: number };
   return row.n > 0;
 }
 
@@ -275,7 +270,11 @@ export function passwordLoginDisabled(c: Context): boolean {
  * Unauthenticated passkey routes. Mount BEFORE the auth guard, next to
  * authRoutes.
  */
-export function passkeyPublicRoutes(mode: AuthMode, deps: PasskeyDeps = {}): Hono {
+export function passkeyPublicRoutes(
+  mode: AuthMode,
+  ctx: PasskeyContext,
+  deps: PasskeyDeps = {}
+): Hono {
   const verifyAuthentication = deps.verifyAuthenticationResponse ?? realVerifyAuthentication;
   const now = deps.now ?? Date.now;
   const app = new Hono();
@@ -286,21 +285,21 @@ export function passkeyPublicRoutes(mode: AuthMode, deps: PasskeyDeps = {}): Hon
     if (mode !== "password") {
       return c.json({ password: false, passkey: false });
     }
-    const row = getDb()
+    const row = ctx.db
       .query("SELECT COUNT(*) AS n FROM passkey_credentials WHERE rp_id = ?")
-      .get(rpIdForRead(c)) as { n: number };
-    return c.json({ password: !passwordLoginDisabled(c), passkey: row.n > 0 });
+      .get(rpIdForRead(c, ctx)) as { n: number };
+    return c.json({ password: !passwordLoginDisabled(c, ctx), passkey: row.n > 0 });
   });
 
   app.post("/auth/passkey/login-options", async (c) => {
     if (mode !== "password") return notEnabled(c);
-    const ip = clientIp(c, process.env.TRUST_PROXY === "1") || "unknown";
+    const ip = clientIp(c, ctx.auth.trustProxy, ctx.auth.trustProxyHops) || "unknown";
     // Own bucket: conditional-UI mounts fire this on every login-screen load
     // and must not starve real verify attempts of their shared budget.
     if (!consumeLoginToken(`pk-opt:${ip}`, OPTIONS_RATE_LIMIT)) {
       return c.json({ error: "Too many attempts. Try again in a minute." }, 429);
     }
-    const rp = resolveRp(c);
+    const rp = resolveRp(c, ctx);
     if (!rp) return c.json({ error: "Origin not allowed" }, 400);
 
     // Empty allowCredentials + discoverable credentials = usernameless login.
@@ -315,14 +314,14 @@ export function passkeyPublicRoutes(mode: AuthMode, deps: PasskeyDeps = {}): Hon
 
   app.post("/auth/passkey/login-verify", async (c) => {
     if (mode !== "password") return notEnabled(c);
-    const ip = clientIp(c, process.env.TRUST_PROXY === "1") || "unknown";
+    const ip = clientIp(c, ctx.auth.trustProxy, ctx.auth.trustProxyHops) || "unknown";
     // Same buckets as password login: one combined online-guess budget.
     const perIpOk = consumeLoginToken(`ip:${ip}`, LOGIN_RATE_LIMIT);
     const globalOk = consumeLoginToken("global", GLOBAL_LOGIN_RATE_LIMIT);
     if (!perIpOk || !globalOk) {
       return c.json({ error: "Too many attempts. Try again in a minute." }, 429);
     }
-    const rp = resolveRp(c);
+    const rp = resolveRp(c, ctx);
     if (!rp) return c.json({ error: "Origin not allowed" }, 400);
 
     let response: AuthenticationResponseJSON;
@@ -334,7 +333,8 @@ export function passkeyPublicRoutes(mode: AuthMode, deps: PasskeyDeps = {}): Hon
 
     const fail = () => c.json({ error: "Passkey verification failed" }, 401);
 
-    const row = typeof response?.id === "string" ? credentialById(response.id) : null;
+    const row =
+      typeof response?.id === "string" ? credentialById(ctx.db, response.id) : null;
     if (!row || row.rp_id !== rp.rpID) return fail();
 
     const challenge = challengeFromResponse(response);
@@ -351,7 +351,7 @@ export function passkeyPublicRoutes(mode: AuthMode, deps: PasskeyDeps = {}): Hon
         credential: toWebAuthnCredential(row),
       });
       if (!result.verified) return fail();
-      getDb()
+      ctx.db
         .prepare(
           "UPDATE passkey_credentials SET counter = ?, last_used_at = ? WHERE id = ?"
         )
@@ -371,7 +371,7 @@ export function passkeyPublicRoutes(mode: AuthMode, deps: PasskeyDeps = {}): Hon
       return fail();
     }
 
-    await issueSessionCookie(c);
+    await issueSessionCookie(c, ctx.auth);
     return c.json({ ok: true });
   });
 
@@ -382,24 +382,28 @@ export function passkeyPublicRoutes(mode: AuthMode, deps: PasskeyDeps = {}): Hon
  * Session-gated passkey routes. Mount AFTER the auth guard — gating comes from
  * mount position, not per-route checks.
  */
-export function passkeyManagementRoutes(mode: AuthMode, deps: PasskeyDeps = {}): Hono {
+export function passkeyManagementRoutes(
+  mode: AuthMode,
+  ctx: PasskeyContext,
+  deps: PasskeyDeps = {}
+): Hono {
   const verifyRegistration = deps.verifyRegistrationResponse ?? realVerifyRegistration;
   const now = deps.now ?? Date.now;
   const app = new Hono();
 
   app.post("/auth/passkey/register-options", async (c) => {
     if (mode !== "password") return notEnabled(c);
-    const rp = resolveRp(c);
+    const rp = resolveRp(c, ctx);
     if (!rp) return c.json({ error: "Origin not allowed" }, 400);
 
     const options = await generateRegistrationOptions({
-      rpName: rpName(),
+      rpName: ctx.webauthn.rpName,
       rpID: rp.rpID,
-      userName: userName(),
-      userID: userId(),
-      userDisplayName: rpName(),
+      userName: ctx.webauthn.userName,
+      userID: userId(ctx.webauthn),
+      userDisplayName: ctx.webauthn.rpName,
       attestationType: "none",
-      excludeCredentials: credentialsForRp(rp.rpID).map((row) => ({
+      excludeCredentials: credentialsForRp(ctx.db, rp.rpID).map((row) => ({
         id: row.id,
         transports: toWebAuthnCredential(row).transports,
       })),
@@ -415,7 +419,7 @@ export function passkeyManagementRoutes(mode: AuthMode, deps: PasskeyDeps = {}):
 
   app.post("/auth/passkey/register-verify", async (c) => {
     if (mode !== "password") return notEnabled(c);
-    const rp = resolveRp(c);
+    const rp = resolveRp(c, ctx);
     if (!rp) return c.json({ error: "Origin not allowed" }, 400);
 
     let body: { response?: RegistrationResponseJSON; label?: unknown };
@@ -444,7 +448,7 @@ export function passkeyManagementRoutes(mode: AuthMode, deps: PasskeyDeps = {}):
       const { credential, aaguid, credentialDeviceType, credentialBackedUp } =
         result.registrationInfo;
       const createdAt = now();
-      getDb()
+      ctx.db
         .prepare(
           `INSERT INTO passkey_credentials
              (id, public_key, counter, transports, rp_id, aaguid, device_type,
@@ -463,7 +467,7 @@ export function passkeyManagementRoutes(mode: AuthMode, deps: PasskeyDeps = {}):
           sanitizeLabel(body.label),
           createdAt
         );
-      const row = credentialById(credential.id);
+      const row = credentialById(ctx.db, credential.id);
       return c.json({ ok: true, credential: row ? toSummary(row) : null });
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -476,7 +480,7 @@ export function passkeyManagementRoutes(mode: AuthMode, deps: PasskeyDeps = {}):
   // delete stale localhost/dev credentials. The client badges foreign RPs.
   app.get("/auth/passkey/list", (c) => {
     if (mode !== "password") return notEnabled(c);
-    const rows = getDb()
+    const rows = ctx.db
       .query("SELECT * FROM passkey_credentials ORDER BY created_at DESC")
       .all() as CredentialRow[];
     return c.json({ credentials: rows.map(toSummary) });
@@ -490,7 +494,7 @@ export function passkeyManagementRoutes(mode: AuthMode, deps: PasskeyDeps = {}):
     } catch {
       return c.json({ error: "Invalid request body" }, 400);
     }
-    const result = getDb()
+    const result = ctx.db
       .prepare("UPDATE passkey_credentials SET label = ? WHERE id = ?")
       .run(sanitizeLabel(body.label), c.req.param("id"));
     if (result.changes === 0) return c.json({ error: "Unknown passkey" }, 404);
@@ -499,7 +503,7 @@ export function passkeyManagementRoutes(mode: AuthMode, deps: PasskeyDeps = {}):
 
   app.delete("/auth/passkey/:id", (c) => {
     if (mode !== "password") return notEnabled(c);
-    const result = getDb()
+    const result = ctx.db
       .prepare("DELETE FROM passkey_credentials WHERE id = ?")
       .run(c.req.param("id"));
     if (result.changes === 0) return c.json({ error: "Unknown passkey" }, 404);

package/src/middleware/tailscale.ts

@@ -6,21 +6,21 @@ import { getConnInfo } from "hono/bun";
  * localhost.
  *
  * SECURITY: header trust is OFF by default. An exposed port lets anyone spoof
- * `x-forwarded-for`, so the real socket address is used unless `TRUST_PROXY=1`
- * — set that ONLY when a trusted reverse proxy in front of brain-ui sets the
- * forwarding header.
+ * `x-forwarded-for`, so the real socket address is used unless the resolved
+ * config says `trustProxy` (TRUST_PROXY=1) — set that ONLY when a trusted
+ * reverse proxy in front of brain-ui sets the forwarding header.
  */
 export interface TailscaleGuardOptions {
-  /** Trust x-forwarded-for / x-real-ip. Defaults to `TRUST_PROXY === "1"`. */
-  trustProxy?: boolean;
+  /** Trust x-forwarded-for / x-real-ip. */
+  trustProxy: boolean;
+  /** How many trusted proxies front the app (default 1). */
+  trustProxyHops?: number;
 }
 
-export function tailscaleGuard(
-  options: TailscaleGuardOptions = {}
-): MiddlewareHandler {
-  const trustProxy = options.trustProxy ?? process.env.TRUST_PROXY === "1";
+export function tailscaleGuard(options: TailscaleGuardOptions): MiddlewareHandler {
+  const { trustProxy, trustProxyHops } = options;
   return async (c, next) => {
-    if (isTailscaleAllowed(c, trustProxy)) {
+    if (isTailscaleAllowed(c, trustProxy, trustProxyHops)) {
       await next();
     } else {
       return c.json({ error: "VPN access required" }, 403);
@@ -29,8 +29,12 @@ export function tailscaleGuard(
 }
 
 /** True when the request's client IP is a Tailscale or loopback address. */
-export function isTailscaleAllowed(c: Context, trustProxy: boolean): boolean {
-  const ip = clientIp(c, trustProxy);
+export function isTailscaleAllowed(
+  c: Context,
+  trustProxy: boolean,
+  trustProxyHops = 1
+): boolean {
+  const ip = clientIp(c, trustProxy, trustProxyHops);
   return isTailscaleIp(ip) || isLocalIp(ip);
 }
 
@@ -42,11 +46,12 @@ export function isTailscaleAllowed(c: Context, trustProxy: boolean): boolean {
  *
  * X-Forwarded-For is parsed RIGHT-TO-LEFT: each proxy appends the address it saw,
  * so the rightmost entries are the trusted hops we control and the leftmost is
- * client-controllable. `TRUST_PROXY_HOPS` (default 1) is how many proxies front
- * this app; the client IP is the entry just before them. Taking the leftmost
- * entry (the old behaviour) let a client spoof its address by pre-seeding XFF.
+ * client-controllable. `trustProxyHops` (TRUST_PROXY_HOPS, default 1) is how many
+ * proxies front this app; the client IP is the entry just before them. Taking the
+ * leftmost entry (the old behaviour) let a client spoof its address by
+ * pre-seeding XFF.
  */
-export function clientIp(c: Context, trustProxy: boolean): string {
+export function clientIp(c: Context, trustProxy: boolean, trustProxyHops = 1): string {
   if (trustProxy) {
     const forwarded = c.req.header("x-forwarded-for");
     if (forwarded) {
@@ -55,7 +60,7 @@ export function clientIp(c: Context, trustProxy: boolean): string {
         .map((part) => part.trim())
         .filter(Boolean);
       if (parts.length > 0) {
-        const hops = Math.max(1, Number(process.env.TRUST_PROXY_HOPS) || 1);
+        const hops = Math.max(1, trustProxyHops);
         const ip = parts[Math.max(0, parts.length - hops)];
         if (ip) return ip;
       }

package/src/routes/brain.ts

@@ -1,17 +1,21 @@
 import { Hono } from "hono";
 import { streamSSE } from "hono/streaming";
+import type { BrainClient } from "../brain/client.js";
+import { subprocessEnv } from "../config/env.js";
 import {
-  brainSearch,
-  brainBriefing,
-  brainStats,
-  brainList,
-  brainAdd,
-  brainCliCommand,
-} from "../brain/client.js";
-import { buildKeyterms, writeCache } from "../voice/keyterm-builder.js";
+  buildKeyterms,
+  writeCache,
+  type KeytermSettings,
+} from "../voice/keyterm-builder.js";
 import { existsSync } from "fs";
 import { join } from "path";
 
+export interface BrainRoutesDeps {
+  brain: BrainClient;
+  brainPath: string;
+  keyterms: KeytermSettings;
+}
+
 /**
  * Locate the brain repo's `whatsup` script, relative to the repo root.
  *
@@ -31,14 +35,17 @@ function findWhatsupScript(brainPath: string): string | null {
   return null;
 }
 
-export const brainRoutes = new Hono()
+export function createBrainRoutes(deps: BrainRoutesDeps): Hono {
+  const { brain, brainPath, keyterms } = deps;
+
+  return new Hono()
   .get("/brain/search", async (c) => {
     const q = c.req.query("q");
     if (!q) {
       return c.json({ error: "Query parameter 'q' is required" }, 400);
     }
     try {
-      const { results, warnings } = await brainSearch(q, {
+      const { results, warnings } = await brain.search(q, {
         type: c.req.query("type"),
         tag: c.req.query("tag"),
         limit: c.req.query("limit") ? Number(c.req.query("limit")) : undefined,
@@ -55,7 +62,7 @@ export const brainRoutes = new Hono()
 
   .get("/brain/briefing", async (c) => {
     try {
-      const content = await brainBriefing();
+      const content = await brain.briefing();
       return c.json({ content });
     } catch (err) {
       return c.json(
@@ -66,10 +73,6 @@ export const brainRoutes = new Hono()
   })
 
   .post("/brain/whatsup", async (c) => {
-    const BRAIN_PATH =
-      process.env.BRAIN_PATH ||
-      `${process.env.HOME || "/root"}/brain`;
-
     // Defeat reverse-proxy buffering for SSE
     c.header("X-Accel-Buffering", "no");
 
@@ -91,7 +94,7 @@ export const brainRoutes = new Hono()
       try {
         await send({ type: "start", text: "Running whatsup briefing..." });
 
-        const script = findWhatsupScript(BRAIN_PATH);
+        const script = findWhatsupScript(brainPath);
         if (!script) {
           // Terminate with the frames the client actually handles: it only
           // reads "progress" and "done", so an "error" type would leave the
@@ -109,10 +112,10 @@ export const brainRoutes = new Hono()
         // --claude backend uses --bare mode, which can't read the
         // CLAUDE_CODE_OAUTH_TOKEN either).
         const proc = Bun.spawn(["bun", script, "--gemini"], {
-          cwd: BRAIN_PATH,
+          cwd: brainPath,
           stdout: "pipe",
           stderr: "pipe",
-          env: { ...process.env, NO_COLOR: "1" },
+          env: subprocessEnv({ NO_COLOR: "1" }),
         });
 
         const reader = proc.stdout.getReader();
@@ -159,7 +162,7 @@ export const brainRoutes = new Hono()
 
   .get("/brain/stats", async (c) => {
     try {
-      const stats = await brainStats();
+      const stats = await brain.stats();
       return c.json(stats);
     } catch (err) {
       return c.json(
@@ -171,7 +174,7 @@ export const brainRoutes = new Hono()
 
   .get("/brain/list", async (c) => {
     try {
-      const results = await brainList({
+      const results = await brain.list({
         type: c.req.query("type"),
         tag: c.req.query("tag"),
         status: c.req.query("status"),
@@ -190,9 +193,6 @@ export const brainRoutes = new Hono()
   .post("/brain/sync", async (c) => {
     // Stream sync output via SSE so the client sees live progress.
     // brain sync spawns a nested Claude Code process that can take minutes.
-    const BRAIN_PATH =
-      process.env.BRAIN_PATH ||
-      `${process.env.HOME || "/root"}/brain`;
 
     return streamSSE(c, async (stream) => {
       const send = (data: {
@@ -212,17 +212,17 @@ export const brainRoutes = new Hono()
 
       // Merge stderr into stdout — brain sync spawns a nested Claude Code
       // process whose output goes to stderr. The command comes from
-      // brainCliCommand() (packaged bin or legacy vendored script), passed to
+      // brain.cliCommand() (packaged bin or legacy vendored script), passed to
       // bash as positional args rather than interpolated into the script, so a
       // BRAIN_PATH containing spaces or shell metacharacters stays inert.
-      const [cliBin, ...cliArgs] = brainCliCommand();
+      const [cliBin, ...cliArgs] = brain.cliCommand();
       const proc = Bun.spawn(
         ["bash", "-c", '"$0" "$@" 2>&1', cliBin!, ...cliArgs, "sync"],
         {
-          cwd: BRAIN_PATH,
+          cwd: brainPath,
           stdout: "pipe",
           stderr: "pipe",
-          env: { ...process.env, NO_COLOR: "1" },
+          env: subprocessEnv({ NO_COLOR: "1" }),
         }
       );
 
@@ -254,8 +254,8 @@ export const brainRoutes = new Hono()
       // Rebuild voice keyterms cache after a successful sync.
       if (exitCode === 0) {
         try {
-          const cache = buildKeyterms();
-          writeCache(cache);
+          const cache = buildKeyterms(keyterms);
+          writeCache(keyterms, cache);
           await send({
             type: "progress",
             text: `[voice] Rebuilt keyterms cache (${cache.count} terms)`,
@@ -290,7 +290,7 @@ export const brainRoutes = new Hono()
       return c.json({ error: "Field 'content' is required" }, 400);
     }
     try {
-      await brainAdd(body.content, {
+      await brain.add(body.content, {
         type: body.type,
         title: body.title,
         tags: body.tags,
@@ -303,3 +303,4 @@ export const brainRoutes = new Hono()
       );
     }
   });
+}

package/src/routes/files.ts

@@ -10,7 +10,6 @@ import {
   TooLargeError,
 } from "../files/walker.js";
 
-let wikilinkCache: { generatedAt: number; map: Record<string, string> } | null = null;
 const WIKILINK_TTL_MS = 30_000;
 
 function errorResponse(err: unknown): { body: { error: string; size?: number }; status: 400 | 404 | 413 | 500 } {
@@ -27,11 +26,14 @@ function errorResponse(err: unknown): { body: { error: string; size?: number };
   return { body: { error: err instanceof Error ? err.message : "internal_error" }, status: 500 };
 }
 
-export const filesRoutes = new Hono()
+export function createFilesRoutes(deps: { brainRoot: string }): Hono {
+  const { brainRoot } = deps;
+  let wikilinkCache: { generatedAt: number; map: Record<string, string> } | null = null;
+  return new Hono()
   .get("/files/tree", async (c) => {
     const path = c.req.query("path") ?? "";
     try {
-      const entries = await listDirectory(path);
+      const entries = await listDirectory(path, brainRoot);
       return c.json({ path, entries });
     } catch (err) {
       const { body, status } = errorResponse(err);
@@ -45,7 +47,7 @@ export const filesRoutes = new Hono()
     const raw = c.req.query("raw") === "1";
     try {
       if (raw) {
-        const { abs, mime, size } = await resolveForRaw(path);
+        const { abs, mime, size } = await resolveForRaw(path, brainRoot);
         const file = Bun.file(abs);
         return new Response(file, {
           status: 200,
@@ -59,7 +61,7 @@ export const filesRoutes = new Hono()
           },
         });
       }
-      const result = await readFileContent(path);
+      const result = await readFileContent(path, brainRoot);
       return c.json({ path, ...result });
     } catch (err) {
       const { body, status } = errorResponse(err);
@@ -71,7 +73,7 @@ export const filesRoutes = new Hono()
     const path = c.req.query("path");
     if (!path) return c.json({ error: "missing_path" }, 400);
     try {
-      const result = await resolveAncestors(path);
+      const result = await resolveAncestors(path, brainRoot);
       return c.json({ path, ...result });
     } catch (err) {
       const { body, status } = errorResponse(err);
@@ -84,7 +86,7 @@ export const filesRoutes = new Hono()
     const now = Date.now();
     try {
       if (refresh || !wikilinkCache || now - wikilinkCache.generatedAt > WIKILINK_TTL_MS) {
-        const map = await buildWikilinkMap();
+        const map = await buildWikilinkMap(brainRoot);
         wikilinkCache = { generatedAt: now, map };
       }
       return c.json({
@@ -97,3 +99,4 @@ export const filesRoutes = new Hono()
       return c.json(body, status);
     }
   });
+}