@thaut/claude-ide 0.0.0-stage → 1.0.0

package/bin/claude-ide.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const entry = path.join(root, "server", "index.ts");
+
+// Resolve tsx from this package's own dependencies, not from the user's cwd.
+const require = createRequire(import.meta.url);
+const tsxLoader = pathToFileURL(require.resolve("tsx")).href;
+
+const child = spawn(process.execPath, ["--import", tsxLoader, entry, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env: { ...process.env, NODE_ENV: process.env.NODE_ENV ?? "production" },
+  cwd: process.cwd(),
+});
+
+for (const sig of ["SIGINT", "SIGTERM"]) {
+  process.on(sig, () => child.kill(sig));
+}
+child.on("exit", (code, signal) => process.exit(code ?? (signal ? 1 : 0)));

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "@thaut/claude-ide",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Claude IDE: web UI for Claude Code sessions",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "dev": "concurrently -k -n server,web \"npm:dev:server\" \"vite\"",
+    "build": "tsc --noEmit -p . && vite build",
+    "start": "vite build && NODE_ENV=production tsx watch server/index.ts",
+    "typecheck": "tsc --noEmit -p .",
+    "test:e2e": "npm run test:unit && npm run build && (E2E_GROUP=parallel playwright test; a=$?; E2E_GROUP=serial playwright test; b=$?; exit $(( a != 0 || b != 0 )))",
+    "dev:server": "bash -c 'while true; do tsx watch server/index.ts; echo \"[dev] server exited, restarting in 2s\"; sleep 2; done'",
+    "test:e2e:live": "npm run build && E2E_MODE=live playwright test",
+    "e2e:fixtures": "tsx e2e/replay/build-fixtures.ts",
+    "test:e2e:record": "npm run build && E2E_MODE=record playwright test",
+    "test:unit": "node --import tsx --test 'server/**/*.test.ts' 'web/src/**/*.test.ts'",
+    "test:http-channels": "node --import tsx --test --test-concurrency=3 server/http-channel-registration.test.ts server/http-channel-pull.test.ts server/http-channel-push.test.ts",
+    "prepack": "vite build"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.296",
+    "@hono/node-server": "^1.19.17",
+    "@hono/node-ws": "^1.3.1",
+    "@tanstack/react-query": "^5.104.2",
+    "@tanstack/react-virtual": "^3.14.19",
+    "cron-parser": "^5.10.2",
+    "hast-util-to-html": "^9.0.6",
+    "hono": "^4.13.13",
+    "mdast-util-gfm": "^3.1.0",
+    "mdast-util-to-markdown": "^2.2.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "react-markdown": "^10.1.0",
+    "react-router": "^8.4.0",
+    "rehype-raw": "^7.0.0",
+    "rehype-sanitize": "^6.0.0",
+    "remark-gfm": "^4.0.1",
+    "shiki": "^4.5.0",
+    "web-push": "^3.6.7",
+    "zod": "^4.6.7",
+    "zustand": "^5.0.15",
+    "tsx": "^4.23.15"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.64.0",
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^26.6.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@types/web-push": "^3.6.4",
+    "@vitejs/plugin-react": "^6.1.2",
+    "concurrently": "^10.0.6",
+    "remark-parse": "^11.0.0",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^7.0.2",
+    "unified": "^11.0.5",
+    "vite": "^8.3.4"
+  },
+  "bin": {
+    "claude-ide": "bin/claude-ide.js"
+  },
+  "files": [
+    "bin/",
+    "server/",
+    "shared/",
+    "web/src/",
+    "web/dist/",
+    "README.md",
+    "package.json"
+  ]
+}

package/server/add-dirs.ts

@@ -0,0 +1,126 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { ExtraDir, ExtraDirSource, ExtraDirsInfo } from "../shared/project.ts";
+import { claudeDir } from "./cli-files.ts";
+import { deleteSessionDir, insertSessionDir, sessionCwd, sessionDirs } from "./session-dirs.ts";
+import { HttpError, sessions } from "./sessions.ts";
+import { withFileLock } from "./fs-queue.ts";
+
+/**
+ * /add-dir (see NOTES.md "CLI 配置文件"): directories outside the project a session may use.
+ * - Session-only dirs are kept in sqlite and handed to the CLI through the flag-settings layer
+ *   (`applyFlagSettings({permissions: {additionalDirectories}})`) at start and on every change,
+ *   which also works while the CLI process runs, removal included [实测 m4_add_dir.mjs].
+ * - "Remember" writes `permissions.additionalDirectories` of the session cwd's
+ *   `.claude/settings.local.json`, exactly as the CLI's /add-dir does.
+ */
+
+type SettingsFile = { permissions?: { additionalDirectories?: unknown } & Record<string, unknown> } & Record<string, unknown>;
+
+const localSettingsFile = (cwd: string) => path.join(cwd, ".claude", "settings.local.json");
+
+async function exists(p: string) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJson(file: string): Promise<SettingsFile | undefined> {
+  try {
+    const v = JSON.parse(await fs.readFile(file, "utf8"));
+    return v && typeof v === "object" ? v : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function dirsIn(file: string): Promise<string[]> {
+  const list = (await readJson(file))?.permissions?.additionalDirectories;
+  return Array.isArray(list) ? list.filter((x): x is string => typeof x === "string") : [];
+}
+
+/** Read-modify-write of settings.local.json, keeping every other key; written atomically. */
+function updateLocalDirs(cwd: string, fn: (dirs: string[]) => string[]) {
+  const file = localSettingsFile(cwd);
+  return withFileLock(file, async () => {
+    let data: SettingsFile = {};
+    if (await exists(file)) {
+      const parsed = await readJson(file);
+      if (!parsed) throw new HttpError(409, `${file} 不是有效的 JSON，请先修好它`);
+      data = parsed;
+    }
+    const next = fn(await dirsIn(file));
+    const permissions = { ...(data.permissions ?? {}) };
+    if (next.length) permissions.additionalDirectories = next;
+    else delete permissions.additionalDirectories;
+    data = { ...data, permissions };
+    if (Object.keys(permissions).length === 0) delete data.permissions;
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(data, null, 2) + "\n");
+    await fs.rename(tmp, file);
+  });
+}
+
+const expandHome = (p: string) => (p === "~" ? os.homedir() : p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p);
+
+/** Settings entries may be relative to the directory holding `.claude/`. */
+const resolveEntry = (base: string, p: string) => path.resolve(base, expandHome(p));
+
+export async function extraDirs(projectPath: string, sessionId: string): Promise<ExtraDirsInfo> {
+  const cwd = await sessionCwd(projectPath, sessionId);
+  const map = new Map<string, ExtraDirSource[]>();
+  const add = (p: string, s: ExtraDirSource) => {
+    const list = map.get(p) ?? [];
+    if (!list.includes(s)) list.push(s);
+    map.set(p, list);
+  };
+  for (const d of sessionDirs(sessionId)) add(d, "session");
+  for (const d of await dirsIn(localSettingsFile(cwd))) add(resolveEntry(cwd, d), "local");
+  for (const d of await dirsIn(path.join(cwd, ".claude", "settings.json"))) add(resolveEntry(cwd, d), "project");
+  for (const d of await dirsIn(path.join(claudeDir(), "settings.json"))) add(resolveEntry(os.homedir(), d), "user");
+  const dirs: ExtraDir[] = await Promise.all([...map].map(async ([p, sources]) => ({ path: p, sources, exists: await isDir(p) })));
+  return { cwd, dirs, localSettingsFile: localSettingsFile(cwd) };
+}
+
+async function isDir(p: string) {
+  try {
+    return (await fs.stat(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Push the session's list to its running CLI process (no-op when it is not running). */
+async function applyLive(sessionId: string) {
+  await sessions.get(sessionId)?.setAdditionalDirectories(sessionDirs(sessionId));
+}
+
+export async function addExtraDir(projectPath: string, sessionId: string, raw: string, remember: boolean): Promise<ExtraDirsInfo> {
+  const input = expandHome(raw.trim());
+  if (!input) throw new HttpError(400, "请填写目录路径");
+  if (!path.isAbsolute(input)) throw new HttpError(400, "请填写绝对路径");
+  if (!(await isDir(input))) throw new HttpError(400, "目录不存在");
+  const dir = await fs.realpath(input);
+  const cwd = await sessionCwd(projectPath, sessionId);
+  const rel = path.relative(await fs.realpath(cwd), dir);
+  if (!rel.startsWith("..") && !path.isAbsolute(rel)) throw new HttpError(400, "这个目录已经在会话的工作目录里了");
+  insertSessionDir(sessionId, dir);
+  if (remember) await updateLocalDirs(cwd, (dirs) => (dirs.some((d) => resolveEntry(cwd, d) === dir) ? dirs : [...dirs, dir]));
+  await applyLive(sessionId);
+  return extraDirs(projectPath, sessionId);
+}
+
+export async function removeExtraDir(projectPath: string, sessionId: string, dir: string): Promise<ExtraDirsInfo> {
+  const cwd = await sessionCwd(projectPath, sessionId);
+  deleteSessionDir(sessionId, dir);
+  if ((await dirsIn(localSettingsFile(cwd))).some((d) => resolveEntry(cwd, d) === dir)) {
+    await updateLocalDirs(cwd, (dirs) => dirs.filter((d) => resolveEntry(cwd, d) !== dir));
+  }
+  await applyLive(sessionId);
+  return extraDirs(projectPath, sessionId);
+}

package/server/auth.test.ts

@@ -0,0 +1,148 @@
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { Hono } from "hono";
+
+const dir = await fs.mkdtemp(path.join(os.tmpdir(), "cide-auth-unit-"));
+process.env.CLAUDE_IDE_DATA_DIR = dir;
+process.env.CLAUDE_IDE_PASSWORD = "unused-environment-override";
+const passwordFile = path.join(dir, "password");
+await fs.writeFile(passwordFile, "synthetic-initial\n", { mode: 0o600 });
+const { db } = await import("./db.ts");
+const { AUTH_COOKIE, login, isAuthed, isTokenValid, validateToken, refreshAuth, onAuthRevoked, watchPassword } = await import("./auth.ts");
+const app = new Hono();
+app.post("/login", async (c) => c.json({ ok: await login(c, await c.req.text()) }));
+app.get("/auth", async (c) => c.json({ authed: await isAuthed(c) }));
+async function signIn(password: string) {
+  const response = await app.request("/login", { method: "POST", body: password });
+  const body = await response.json() as { ok: boolean };
+  const cookie = response.headers.get("set-cookie")?.split(";")[0];
+  return { ok: body.ok, cookie, token: cookie?.slice(`${AUTH_COOKIE}=`.length) };
+}
+after(async () => { db.close(); await fs.rm(dir, { recursive: true, force: true }); });
+
+test("first credential initialization revokes unbound legacy tokens once; file overrides env", async () => {
+  db.prepare("INSERT INTO auth_tokens VALUES (?, ?, ?)").run("synthetic-legacy", 1, 1);
+  assert.equal(await refreshAuth(), true);
+  assert.equal(isTokenValid("synthetic-legacy"), false);
+  assert.equal((await signIn("unused-environment-override")).ok, false);
+  assert.equal((await signIn("synthetic-initial")).ok, true);
+});
+
+test("same password rewrites preserve tokens; atomic replacement rotates every device", async () => {
+  const first = await signIn("synthetic-initial"), second = await signIn("synthetic-initial");
+  assert.ok(first.token); assert.ok(second.token);
+  await fs.writeFile(passwordFile, "synthetic-initial\n\n");
+  assert.equal(await validateToken(first.token), true);
+  await fs.writeFile(`${passwordFile}.new`, "synthetic-initial\n");
+  await fs.rename(`${passwordFile}.new`, passwordFile);
+  assert.equal(await validateToken(second.token), true);
+  let revoked = 0;
+  const stop = onAuthRevoked(() => revoked++);
+  try {
+    await fs.writeFile(`${passwordFile}.new`, "synthetic-rotated\n");
+    await fs.rename(`${passwordFile}.new`, passwordFile);
+    const [oldLogin, newLogin] = await Promise.all([signIn("synthetic-initial"), signIn("synthetic-rotated")]);
+    assert.equal(oldLogin.ok, false); assert.equal(newLogin.ok, true);
+    assert.equal(isTokenValid(first.token), false); assert.equal(isTokenValid(second.token), false);
+    assert.equal(revoked, 1);
+    assert.equal(await validateToken(newLogin.token!), true);
+    const response = await app.request("/auth", { headers: { cookie: first.cookie! } });
+    assert.deepEqual(await response.json(), { authed: false });
+  } finally { stop(); }
+});
+
+test("confirmed missing, empty, and unreadable files revoke tokens without regenerating or reviving them", async () => {
+  const assertUnavailable = async (breakFile: () => Promise<void>, restore: () => Promise<void>) => {
+    const device = await signIn("synthetic-rotated");
+    assert.ok(device.token);
+    await breakFile();
+    assert.equal(await refreshAuth(), false);
+    assert.equal(isTokenValid(device.token), false);
+    assert.equal((await signIn("synthetic-rotated")).ok, false);
+    await restore();
+    assert.equal(await refreshAuth(), true);
+    assert.equal(isTokenValid(device.token), false, "restoring the same password cannot revive an old login");
+  };
+  await assertUnavailable(() => fs.unlink(passwordFile), async () => {
+    await assert.rejects(fs.stat(passwordFile), { code: "ENOENT" });
+    await fs.writeFile(passwordFile, "synthetic-rotated\n");
+  });
+  await assertUnavailable(() => fs.writeFile(passwordFile, " \n"), async () => {
+    assert.equal(await fs.readFile(passwordFile, "utf8"), " \n");
+    await fs.writeFile(passwordFile, "synthetic-rotated\n");
+  });
+  // EISDIR reliably exercises unreadability even when CI runs with root privileges.
+  await assertUnavailable(async () => {
+    await fs.unlink(passwordFile); await fs.mkdir(passwordFile);
+  }, async () => {
+    await fs.rmdir(passwordFile); await fs.writeFile(passwordFile, "synthetic-rotated\n");
+  });
+  if (process.getuid?.() !== 0) {
+    await assertUnavailable(() => fs.chmod(passwordFile, 0), () => fs.chmod(passwordFile, 0o600));
+  }
+});
+
+test("brief editor rename gap recovers within retries without revocation", async () => {
+  const device = await signIn("synthetic-rotated");
+  await fs.rename(passwordFile, `${passwordFile}.saved`);
+  const timer = setTimeout(() => { void fs.rename(`${passwordFile}.saved`, passwordFile); }, 10);
+  try { assert.equal(await validateToken(device.token!), true); }
+  finally { clearTimeout(timer); }
+});
+
+test("background polling revokes idle authenticated devices", async () => {
+  const device = await signIn("synthetic-rotated");
+  let revoke!: () => void;
+  const revoked = new Promise<void>((resolve) => { revoke = resolve; });
+  const unsubscribe = onAuthRevoked(revoke);
+  const stop = watchPassword(10);
+  try {
+    await fs.writeFile(passwordFile, "synthetic-background\n");
+    await Promise.race([revoked, new Promise<never>((_, reject) => {
+      const timer = setTimeout(() => reject(new Error("password poll did not revoke")), 2000); timer.unref();
+    })]);
+    assert.equal(isTokenValid(device.token!), false);
+    assert.equal((await signIn("synthetic-background")).ok, true);
+  } finally { stop(); unsubscribe(); }
+});
+
+test("persisted verifier keeps same-password restarts, revokes changed restarts, and never recreates missing deployed password", async () => {
+  const restartDir = await fs.mkdtemp(path.join(os.tmpdir(), "cide-auth-restart-"));
+  const run = promisify(execFile);
+  const authUrl = new URL("./auth.ts", import.meta.url).href;
+  const dbUrl = new URL("./db.ts", import.meta.url).href;
+  const configUrl = new URL("./config.ts", import.meta.url).href;
+  const script = `
+    import {refreshAuth,isTokenValid} from ${JSON.stringify(authUrl)};
+    import {db} from ${JSON.stringify(dbUrl)};
+    import {config} from ${JSON.stringify(configUrl)};
+    import fs from 'node:fs';
+    const ready = await refreshAuth();
+    const existingValid = isTokenValid('synthetic-restart-token');
+    if (process.env.AUDIT_INSERT === 'yes') db.prepare('INSERT INTO auth_tokens VALUES (?, ?, ?)').run('synthetic-restart-token',1,1);
+    console.log(JSON.stringify({ready,existingValid,fileExists:fs.existsSync(config.passwordFile)}));
+    db.close();
+  `;
+  const child = async (insert = false) => {
+    const { stdout } = await run(process.execPath, ["--import", "tsx", "--input-type=module", "-e", script], {
+      env: { ...process.env, CLAUDE_IDE_DATA_DIR: restartDir, CLAUDE_IDE_PASSWORD: "synthetic-seed", AUDIT_INSERT: insert ? "yes" : "no" },
+    });
+    return JSON.parse(stdout.trim()) as { ready: boolean; existingValid: boolean; fileExists: boolean };
+  };
+  try {
+    assert.deepEqual(await child(true), { ready: true, existingValid: false, fileExists: true });
+    assert.deepEqual(await child(), { ready: true, existingValid: true, fileExists: true });
+    await fs.writeFile(path.join(restartDir, "password"), "synthetic-restart-change\n");
+    assert.deepEqual(await child(), { ready: true, existingValid: false, fileExists: true });
+    await child(true);
+    await fs.unlink(path.join(restartDir, "password"));
+    assert.deepEqual(await child(), { ready: false, existingValid: false, fileExists: false });
+    await fs.writeFile(path.join(restartDir, "password"), "synthetic-restart-change\n");
+    assert.deepEqual(await child(), { ready: true, existingValid: false, fileExists: true });
+  } finally { await fs.rm(restartDir, { recursive: true, force: true }); }
+});

package/server/auth.ts

@@ -0,0 +1,235 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import { promisify } from "node:util";
+import type { Context, MiddlewareHandler } from "hono";
+import { getCookie, setCookie, deleteCookie } from "hono/cookie";
+import { config } from "./config.ts";
+import { db } from "./db.ts";
+
+export const AUTH_COOKIE = "cide_auth";
+const ONE_YEAR = 365 * 24 * 3600;
+const scrypt = promisify(crypto.scrypt);
+const revocationListeners = new Set<() => void>();
+let currentPassword: string | undefined;
+let available = false;
+let unavailableNotified = false;
+let queue: Promise<unknown> = Promise.resolve();
+
+// Refresh, validation, and token creation share one queue: a successful old-
+// password check can never register a token after a newer generation is loaded.
+function serialized<T>(operation: () => Promise<T>): Promise<T> {
+  const result = queue.then(operation);
+  queue = result.catch(() => {});
+  return result;
+}
+
+export function onAuthRevoked(listener: () => void): () => void {
+  revocationListeners.add(listener);
+  return () => { revocationListeners.delete(listener); };
+}
+
+function notifyRevoked() {
+  for (const listener of revocationListeners) listener();
+}
+
+function safeEqual(a: string, b: string): boolean {
+  const ha = crypto.createHash("sha256").update(a).digest();
+  const hb = crypto.createHash("sha256").update(b).digest();
+  return crypto.timingSafeEqual(ha, hb);
+}
+
+async function readPassword(): Promise<string> {
+  // Read by pathname every time, so both atomic replacement and in-place writes
+  // are observed. Brief editor rename/truncate windows get a bounded retry.
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      const password = (await fs.readFile(config.passwordFile, "utf8")).trim();
+      if (password) return password;
+    } catch {
+      // No cached-password fallback and no generation on credential read errors.
+    }
+    if (attempt < 2) await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  throw new Error("login password unavailable");
+}
+
+async function refreshCredential(): Promise<boolean> {
+  let password: string;
+  try {
+    password = await readPassword();
+  } catch {
+    available = false;
+    // After bounded retries, a missing/empty/unreadable file revokes devices.
+    // Keep only the verifier: restoring the same file must not revive tokens.
+    if (!unavailableNotified) {
+      db.prepare("DELETE FROM auth_tokens").run();
+      unavailableNotified = true;
+      notifyRevoked();
+    }
+    return false;
+  }
+  if (currentPassword !== undefined && safeEqual(password, currentPassword)) {
+    available = true;
+    unavailableNotified = false;
+    return true;
+  }
+  const saved = db.prepare("SELECT salt, verifier FROM auth_credential WHERE id = 1").get() as { salt: string; verifier: string } | undefined;
+  const salt = saved?.salt ?? crypto.randomBytes(32).toString("hex");
+  const verifier = (await scrypt(password, salt, 32) as Buffer).toString("hex");
+  const changed = !saved || !safeEqual(verifier, saved.verifier);
+  if (changed) {
+    db.exec("BEGIN IMMEDIATE");
+    try {
+      // On first upgrade no trustworthy old password identifier exists. Revoke
+      // legacy tokens once; ordinary same-password restarts preserve tokens.
+      db.prepare("DELETE FROM auth_tokens").run();
+      db.prepare("INSERT INTO auth_credential (id, salt, verifier) VALUES (1, ?, ?) ON CONFLICT(id) DO UPDATE SET salt=excluded.salt, verifier=excluded.verifier").run(salt, verifier);
+      db.exec("COMMIT");
+    } catch (err) {
+      db.exec("ROLLBACK");
+      throw err;
+    }
+  }
+  currentPassword = password;
+  available = true;
+  unavailableNotified = false;
+  if (changed) notifyRevoked();
+  return true;
+}
+
+async function refresh(): Promise<boolean> {
+  try {
+    return await refreshCredential();
+  } catch {
+    // Authentication errors must deny access, including verifier/database errors.
+    // Do not expose filesystem paths, credential material, or database details.
+    available = false;
+    if (!unavailableNotified) {
+      unavailableNotified = true;
+      notifyRevoked();
+    }
+    return false;
+  }
+}
+
+export function refreshAuth(): Promise<boolean> {
+  return serialized(refresh);
+}
+
+/** Polling also revokes idle sockets that have no incoming HTTP/WS traffic. */
+export function watchPassword(intervalMs = 500): () => void {
+  let stopped = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const poll = async () => {
+    try { await refreshAuth(); }
+    catch { console.error("Authentication refresh failed"); }
+    if (!stopped) {
+      timer = setTimeout(() => { void poll(); }, intervalMs);
+      timer.unref();
+    }
+  };
+  void poll();
+  return () => { stopped = true; if (timer) clearTimeout(timer); };
+}
+
+function issueToken(c: Context): void {
+  const token = crypto.randomBytes(32).toString("base64url");
+  const now = Date.now();
+  db.prepare("INSERT INTO auth_tokens (token, created_at, last_seen_at) VALUES (?, ?, ?)").run(token, now, now);
+  setCookie(c, AUTH_COOKIE, token, {
+    httpOnly: true,
+    sameSite: "Lax",
+    secure: c.req.url.startsWith("https:"),
+    path: "/",
+    maxAge: ONE_YEAR,
+  });
+}
+
+export function login(c: Context, candidate: string): Promise<boolean> {
+  return serialized(async () => {
+    if (!await refresh() || !safeEqual(candidate, currentPassword!)) return false;
+    // No await separates password validation from token insertion.
+    issueToken(c);
+    return true;
+  });
+}
+
+export function authToken(c: Context): string | undefined {
+  return getCookie(c, AUTH_COOKIE);
+}
+
+export function revokeToken(c: Context): string | undefined {
+  const token = getCookie(c, AUTH_COOKIE);
+  if (token) db.prepare("DELETE FROM auth_tokens WHERE token = ?").run(token);
+  deleteCookie(c, AUTH_COOKIE, { path: "/" });
+  return token;
+}
+
+// Synchronous admission check after an async handshake; it catches revocation
+// between Hono's upgrade callback and the socket's onOpen event.
+export function isTokenValid(token: string): boolean {
+  return available && !!db.prepare("SELECT token FROM auth_tokens WHERE token = ?").get(token);
+}
+
+export function validateToken(token: string): Promise<boolean> {
+  return serialized(async () => await refresh() && isTokenValid(token));
+}
+
+export async function isAuthed(c: Context): Promise<boolean> {
+  const token = getCookie(c, AUTH_COOKIE);
+  // Even unauthenticated probes observe password changes and revoke old sockets.
+  return serialized(async () => {
+    if (!await refresh() || !token || !isTokenValid(token)) return false;
+    db.prepare("UPDATE auth_tokens SET last_seen_at = ? WHERE token = ?").run(Date.now(), token);
+    return true;
+  });
+}
+
+export const requireAuth: MiddlewareHandler = async (c, next) => {
+  if (!await isAuthed(c)) return c.json({ error: "unauthorized" }, 401);
+  await next();
+};
+
+/**
+ * Requests from a page of another origin are refused (cross-site WebSocket hijacking, CSRF).
+ * SameSite=Lax cookies already keep most of them out; this is the second lock. Requests
+ * without an Origin header (curl, the CLI, tests) are not browser cross-site requests.
+ */
+export function sameOrigin(c: Context): boolean {
+  const origin = c.req.header("origin");
+  if (!origin) return true;
+  try {
+    const host = new URL(origin).host;
+    // Behind a reverse proxy (e.g. Tailscale serve) the original host arrives as X-Forwarded-Host.
+    return host === c.req.header("host") || host === c.req.header("x-forwarded-host");
+  } catch {
+    return false;
+  }
+}
+
+/** Failed logins per client address: after MAX_FAILS within WINDOW, refuse for LOCK. */
+const MAX_FAILS = 10;
+const WINDOW_MS = 15 * 60_000;
+const LOCK_MS = 15 * 60_000;
+const fails = new Map<string, { count: number; first: number; lockedUntil: number }>();
+
+export function clientAddress(c: Context): string {
+  const incoming = (c.env as { incoming?: { socket?: { remoteAddress?: string } } } | undefined)?.incoming;
+  return incoming?.socket?.remoteAddress ?? "unknown";
+}
+
+/** Seconds until this address may try again, or 0. */
+export function loginLockedFor(addr: string): number {
+  const f = fails.get(addr);
+  return f && f.lockedUntil > Date.now() ? Math.ceil((f.lockedUntil - Date.now()) / 1000) : 0;
+}
+
+export function recordLogin(addr: string, ok: boolean) {
+  if (ok) return void fails.delete(addr);
+  const now = Date.now();
+  const f = fails.get(addr);
+  const cur = f && now - f.first < WINDOW_MS ? f : { count: 0, first: now, lockedUntil: 0 };
+  cur.count++;
+  if (cur.count >= MAX_FAILS) cur.lockedUntil = now + LOCK_MS;
+  fails.set(addr, cur);
+}

package/server/bang.ts

@@ -0,0 +1,54 @@
+import { childEnv } from "./child-env.ts";
+import { spawn } from "node:child_process";
+
+/**
+ * `!command` from the composer: the server runs the command itself (like the CLI's bash mode)
+ * and the output is added to the conversation as a `shouldQuery: false` user message.
+ */
+
+const TIMEOUT_MS = 2 * 60_000;
+const MAX_CHARS = 30_000;
+
+export type BangResult = { stdout: string; stderr: string; code: number | null; timedOut: boolean };
+
+export function runBang(command: string, cwd: string): Promise<BangResult> {
+  return new Promise((resolve) => {
+    const child = spawn("bash", ["-lc", command], { cwd, stdio: ["ignore", "pipe", "pipe"], detached: true, env: childEnv() as NodeJS.ProcessEnv });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    const cap = (buf: string, chunk: Buffer) => (buf.length > MAX_CHARS * 2 ? buf : buf + chunk.toString("utf8"));
+    child.stdout.on("data", (c: Buffer) => (stdout = cap(stdout, c)));
+    child.stderr.on("data", (c: Buffer) => (stderr = cap(stderr, c)));
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        process.kill(-child.pid!, "SIGKILL"); // the whole process group
+      } catch {
+        child.kill("SIGKILL");
+      }
+    }, TIMEOUT_MS);
+    const done = (code: number | null) => {
+      clearTimeout(timer);
+      resolve({ stdout: truncate(stdout), stderr: truncate(stderr), code, timedOut });
+    };
+    child.on("error", (err) => {
+      stderr += String(err.message);
+      done(null);
+    });
+    child.on("close", done);
+  });
+}
+
+function truncate(s: string): string {
+  s = s.replace(/\n$/, "");
+  return s.length > MAX_CHARS ? `${s.slice(0, MAX_CHARS)}\n… [output truncated]` : s;
+}
+
+/** The transcript format the CLI's own bash mode uses. */
+export function bangMessage(command: string, r: BangResult): string {
+  let stderr = r.stderr;
+  if (r.timedOut) stderr += `${stderr ? "\n" : ""}[timed out after ${TIMEOUT_MS / 1000}s]`;
+  else if (r.code) stderr += `${stderr ? "\n" : ""}[exit code ${r.code}]`;
+  return `<bash-input>${command}</bash-input>\n<bash-stdout>${r.stdout}</bash-stdout><bash-stderr>${stderr}</bash-stderr>`;
+}