mulmoclaude 0.1.0

package/server/agent/sandboxMounts.ts

@@ -0,0 +1,329 @@
+// Host-credential mounts for the Docker sandbox (#259).
+//
+// Two independent opt-in mechanisms, composable:
+//
+//   SANDBOX_SSH_AGENT_FORWARD=1
+//     Bind-mounts $SSH_AUTH_SOCK into the container and sets
+//     SSH_AUTH_SOCK to the container path. Private keys stay on the
+//     host — the agent on the host signs on behalf of the container.
+//
+//   SANDBOX_MOUNT_CONFIGS=gh,gitconfig
+//     CSV of allowlisted config mounts. Each name resolves to a fixed
+//     host path via the server-side ALLOWED_CONFIG_MOUNTS map; users
+//     cannot pass arbitrary paths.
+//
+// See docs/sandbox-credentials.md for the user-facing contract.
+
+import path from "node:path";
+import fs from "node:fs";
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { log } from "../system/logger/index.js";
+import { SUBPROCESS_PROBE_TIMEOUT_MS } from "../utils/time.js";
+
+// ── Config-mount allowlist ──────────────────────────────────────────
+
+export interface SandboxMountSpec {
+  /** The short name users type in SANDBOX_MOUNT_CONFIGS. */
+  name: string;
+  /** Absolute path on the host. Resolved from `$HOME` at lookup. */
+  hostPath: string;
+  /** Absolute path inside the container (must match where the tool looks). */
+  containerPath: string;
+  /** Whether the host path is expected to be a file or a directory. */
+  kind: "file" | "dir";
+  /** Short human description — shown in docs and in startup logs. */
+  description: string;
+}
+
+/**
+ * Build the allowlist. Parameterized on `home` so tests can inject a
+ * temp directory without touching the real filesystem.
+ *
+ * To add a new tool:
+ * 1. Append a row here with the host path the tool reads on startup
+ *    and the container path it should find the same file at.
+ * 2. Add a row in docs/sandbox-credentials.md.
+ * 3. That's it — no env var changes, no parser changes.
+ */
+export function buildAllowedConfigMounts(home: string = homedir()): Record<string, SandboxMountSpec> {
+  return {
+    gh: {
+      name: "gh",
+      hostPath: path.join(home, ".config", "gh"),
+      containerPath: "/home/node/.config/gh",
+      kind: "dir",
+      description: "GitHub CLI auth token + hosts config",
+    },
+    gitconfig: {
+      name: "gitconfig",
+      hostPath: path.join(home, ".gitconfig"),
+      containerPath: "/home/node/.gitconfig",
+      kind: "file",
+      description: "Git user identity (name, email, signing key)",
+    },
+  };
+}
+
+// ── Name parsing / validation ──────────────────────────────────────
+
+export interface ParsedMountList {
+  /** Names that resolved to a spec. Order preserved. */
+  resolved: SandboxMountSpec[];
+  /** Names the user requested that aren't in the allowlist. */
+  unknown: string[];
+  /** Names whose host path does not exist — silently skipped. */
+  missing: SandboxMountSpec[];
+}
+
+/**
+ * Parse a CSV list of mount names, resolve against the allowlist,
+ * check that each host path exists. The three output buckets let the
+ * caller decide what to error on (unknown) vs warn on (missing).
+ */
+export function resolveMountNames(names: readonly string[], allowed: Record<string, SandboxMountSpec> = buildAllowedConfigMounts()): ParsedMountList {
+  const resolved: SandboxMountSpec[] = [];
+  const unknown: string[] = [];
+  const missing: SandboxMountSpec[] = [];
+
+  for (const raw of names) {
+    const name = raw.trim();
+    if (!name) continue;
+    const spec = allowed[name];
+    if (!spec) {
+      unknown.push(name);
+      continue;
+    }
+    if (!hostPathExists(spec)) {
+      missing.push(spec);
+      continue;
+    }
+    resolved.push(spec);
+  }
+  return { resolved, unknown, missing };
+}
+
+function hostPathExists(spec: SandboxMountSpec): boolean {
+  try {
+    const stat = fs.statSync(spec.hostPath);
+    return spec.kind === "dir" ? stat.isDirectory() : stat.isFile();
+  } catch {
+    return false;
+  }
+}
+
+// ── Docker arg generation ──────────────────────────────────────────
+
+/**
+ * Return the `-v ...` argument pairs for the given resolved mounts.
+ * Always read-only. The caller splices these into the full docker
+ * argv in `buildDockerSpawnArgs`.
+ */
+export function configMountArgs(resolved: readonly SandboxMountSpec[]): string[] {
+  const args: string[] = [];
+  for (const spec of resolved) {
+    args.push("-v", `${toDockerPath(spec.hostPath)}:${spec.containerPath}:ro`);
+  }
+  return args;
+}
+
+// ── SSH agent forward ──────────────────────────────────────────────
+
+/** Absolute container path the agent socket is bound to. */
+export const SSH_AGENT_CONTAINER_SOCK = "/ssh-agent";
+
+export interface SshAgentForwardResult {
+  args: string[];
+  /** When null, forward was requested but not possible; caller decides
+   *  whether to log once (we always log in the production driver). */
+  skippedReason: string | null;
+}
+
+// Docker Desktop for Mac exposes the host SSH agent through a
+// well-known magic socket inside the VM. Direct bind-mounting the
+// macOS $SSH_AUTH_SOCK (/private/tmp/…) fails with "operation not
+// supported" because Docker's Linux VM can't mkdir a Unix socket.
+// Using the magic path sidesteps the issue entirely and works on
+// Docker Desktop ≥ 2.3.0 (2020+).
+const DOCKER_DESKTOP_MAC_SSH_SOCK = "/run/host-services/ssh-auth.sock";
+
+/**
+ * Return the docker argv fragment that forwards the host SSH agent
+ * into the container. On macOS + Docker Desktop, the built-in
+ * magic socket is used instead of a raw bind-mount. On Linux, the
+ * host `$SSH_AUTH_SOCK` is bind-mounted directly.
+ *
+ * Skipped (empty args + reason) when:
+ * - the flag is off
+ * - $SSH_AUTH_SOCK isn't set (no agent running on host) — on
+ *   non-macOS only; macOS always has the magic socket available
+ *   when Docker Desktop is running, regardless of $SSH_AUTH_SOCK
+ */
+export function sshAgentForwardArgs(
+  enabled: boolean,
+  sshAuthSock: string | undefined,
+  platform: typeof process.platform = process.platform,
+): SshAgentForwardResult {
+  if (!enabled) return { args: [], skippedReason: null };
+
+  // macOS + Docker Desktop: use the magic VM-internal socket.
+  if (platform === "darwin") {
+    return {
+      args: ["-v", `${DOCKER_DESKTOP_MAC_SSH_SOCK}:${SSH_AGENT_CONTAINER_SOCK}`, "-e", `SSH_AUTH_SOCK=${SSH_AGENT_CONTAINER_SOCK}`],
+      skippedReason: null,
+    };
+  }
+
+  // Linux / other: bind-mount the host socket directly.
+  if (!sshAuthSock || sshAuthSock.length === 0) {
+    return {
+      args: [],
+      skippedReason: "SSH_AUTH_SOCK not set on host",
+    };
+  }
+  if (!fs.existsSync(sshAuthSock)) {
+    return {
+      args: [],
+      skippedReason: `SSH_AUTH_SOCK=${sshAuthSock} not found on host`,
+    };
+  }
+  return {
+    args: ["-v", `${toDockerPath(sshAuthSock)}:${SSH_AGENT_CONTAINER_SOCK}`, "-e", `SSH_AUTH_SOCK=${SSH_AGENT_CONTAINER_SOCK}`],
+    skippedReason: null,
+  };
+}
+
+// ── Top-level resolver used by buildDockerSpawnArgs ────────────────
+
+export interface ResolvedSandboxAuth {
+  /** docker argv additions: a list of `-v` / `-e` tokens. */
+  args: string[];
+  /** Descriptions the caller can log once to show what got mounted. */
+  appliedDescriptions: string[];
+}
+
+export interface ResolveSandboxAuthParams {
+  sshAgentForward: boolean;
+  /** Comma-separated host whitelist for the SSH agent. Default
+   *  "github.com". Passed to the container as
+   *  `SANDBOX_SSH_ALLOWED_HOSTS` and consumed by the entrypoint
+   *  to generate a restrictive `~/.ssh/config`. */
+  sshAllowedHosts?: string;
+  configMountNames: readonly string[];
+  sshAuthSock?: string | undefined;
+  home?: string;
+}
+
+/**
+ * Combine the two mechanisms. Emits a `log.warn` for unknown names
+ * (configuration error the user should fix), a `log.info` for missing
+ * paths (expected when a user hasn't set up the tool), and a
+ * `log.info` line listing what actually got mounted so the startup
+ * log shows the sandbox's effective auth posture.
+ */
+export function resolveSandboxAuth(params: ResolveSandboxAuthParams): ResolvedSandboxAuth {
+  const home = params.home ?? homedir();
+  const allowed = buildAllowedConfigMounts(home);
+  const parsed = resolveMountNames(params.configMountNames, allowed);
+
+  if (parsed.unknown.length > 0) {
+    log.warn("sandbox", "unknown SANDBOX_MOUNT_CONFIGS entries ignored", {
+      unknown: parsed.unknown,
+      allowed: Object.keys(allowed),
+    });
+  }
+  for (const spec of parsed.missing) {
+    log.info("sandbox", "config mount skipped (host path missing)", {
+      name: spec.name,
+      hostPath: spec.hostPath,
+    });
+  }
+
+  const sshResult = sshAgentForwardArgs(params.sshAgentForward, params.sshAuthSock);
+  if (sshResult.skippedReason !== null) {
+    log.warn("sandbox", "SSH agent forward requested but skipped", {
+      reason: sshResult.skippedReason,
+    });
+  }
+
+  // Pass the allowed-hosts whitelist to the container so the
+  // entrypoint can generate a restrictive ~/.ssh/config. Only
+  // included when SSH agent forward is actually active.
+  const sshAllowedHostsArgs = sshResult.args.length > 0 && params.sshAllowedHosts ? ["-e", `SANDBOX_SSH_ALLOWED_HOSTS=${params.sshAllowedHosts}`] : [];
+
+  // gh CLI keyring fallback (#259 + #164). When the user opted in
+  // to `gh` via SANDBOX_MOUNT_CONFIGS but the file mount succeeded
+  // with a keyring-based token (macOS), the mounted hosts.yml won't
+  // contain the actual token. Detect this and inject GH_TOKEN env
+  // var instead. Only runs when "gh" was explicitly requested.
+  const ghTokenArgs = resolveGhTokenFallback(params.configMountNames, parsed);
+
+  const args = [...configMountArgs(parsed.resolved), ...sshResult.args, ...sshAllowedHostsArgs, ...ghTokenArgs.args];
+  const allowedHostsSuffix = sshResult.args.length > 0 && params.sshAllowedHosts ? ` → hosts: ${params.sshAllowedHosts}` : "";
+  const appliedDescriptions = [
+    ...parsed.resolved.map((s) => `${s.name} (${s.description})`),
+    ...(sshResult.args.length > 0 ? [`ssh-agent forward${allowedHostsSuffix}`] : []),
+    ...(ghTokenArgs.args.length > 0 ? ["gh CLI (GH_TOKEN fallback)"] : []),
+  ];
+
+  if (appliedDescriptions.length > 0) {
+    log.info("sandbox", "host credentials attached to container", {
+      mounts: appliedDescriptions,
+    });
+  }
+
+  return { args, appliedDescriptions };
+}
+
+// ── GitHub CLI token fallback ──────────────────────────────────────
+
+// When the user opted in to `gh` via SANDBOX_MOUNT_CONFIGS, the
+// file mount may not carry a usable token — macOS stores it in the
+// system keyring, not in ~/.config/gh/hosts.yml. In that case we
+// extract the token via `gh auth token` on the host and pass it as
+// GH_TOKEN env var. This only runs when "gh" was explicitly
+// requested (#259 opt-in principle).
+function resolveGhTokenFallback(requestedNames: readonly string[], parsed: ParsedMountList): { args: string[] } {
+  const ghRequested = requestedNames.some((n) => n.trim() === "gh");
+  if (!ghRequested) return { args: [] };
+
+  // If an explicit GH_TOKEN is already in the environment, pass it.
+  if (process.env.GH_TOKEN) {
+    return { args: ["-e", `GH_TOKEN=${process.env.GH_TOKEN}`] };
+  }
+
+  // If the file mount resolved (hosts.yml exists), the token might
+  // be in the file. Check if it's keyring-based by looking for
+  // "oauth_token" in the hosts.yml — if missing, fall back.
+  const ghResolved = parsed.resolved.some((s) => s.name === "gh");
+  const ghMissing = parsed.missing.some((s) => s.name === "gh");
+
+  // gh dir doesn't exist at all → try extracting from keyring
+  // gh dir exists (mounted) → still try, since keyring auth leaves
+  //   the file with no usable token
+  if (ghResolved || ghMissing || !ghResolved) {
+    try {
+      const token = execFileSync("gh", ["auth", "token"], {
+        encoding: "utf-8",
+        timeout: SUBPROCESS_PROBE_TIMEOUT_MS,
+      }).trim();
+      if (token.length > 0) {
+        log.info("sandbox", "gh token extracted from host keyring (GH_TOKEN fallback)");
+        return { args: ["-e", `GH_TOKEN=${token}`] };
+      }
+    } catch {
+      log.info("sandbox", "gh auth token failed — gh CLI may not work in sandbox");
+    }
+  }
+
+  return { args: [] };
+}
+
+// ── Utilities ──────────────────────────────────────────────────────
+
+// Docker accepts POSIX-style paths even on Windows when using
+// Docker Desktop, and the rest of the codebase already uses this
+// helper in buildDockerSpawnArgs.
+function toDockerPath(p: string): string {
+  return p.replace(/\\/g, "/");
+}

package/server/agent/stream.ts

@@ -0,0 +1,194 @@
+import { EVENT_TYPES } from "../../src/types/events.js";
+
+export type AgentEvent =
+  | { type: typeof EVENT_TYPES.status; message: string }
+  | { type: typeof EVENT_TYPES.text; message: string }
+  | { type: typeof EVENT_TYPES.toolResult; result: unknown }
+  | { type: typeof EVENT_TYPES.switchRole; roleId: string }
+  | { type: typeof EVENT_TYPES.error; message: string }
+  | {
+      type: typeof EVENT_TYPES.toolCall;
+      toolUseId: string;
+      toolName: string;
+      args: unknown;
+    }
+  | {
+      type: typeof EVENT_TYPES.toolCallResult;
+      toolUseId: string;
+      content: string;
+    }
+  | { type: typeof EVENT_TYPES.claudeSessionId; id: string };
+
+export interface ClaudeContentBlock {
+  type: string;
+  id?: string;
+  name?: string;
+  input?: unknown;
+  tool_use_id?: string;
+  content?: unknown;
+  /** Text content — present in `text` type blocks. */
+  text?: string;
+}
+
+export interface ClaudeMessage {
+  content?: ClaudeContentBlock[];
+}
+
+export type ClaudeStreamEvent =
+  | { type: "assistant"; message: ClaudeMessage }
+  | { type: "user"; message: ClaudeMessage }
+  | { type: "result"; result: string; session_id?: string };
+
+// stream_event sub-types emitted when --include-partial-messages is on.
+export interface StreamEventDelta {
+  type: "content_block_delta";
+  index: number;
+  delta: { type: string; text?: string };
+}
+
+export interface RawStreamEvent {
+  type: string;
+  message?: ClaudeMessage;
+  result?: string;
+  session_id?: string;
+  /** Present when type === "stream_event". Carries partial text
+   *  deltas for real-time streaming. */
+  event?: StreamEventDelta | { type: string };
+}
+
+export function blockToEvent(block: ClaudeContentBlock): AgentEvent | null {
+  if (block.type === "text" && typeof block.text === "string") {
+    return {
+      type: EVENT_TYPES.text,
+      message: block.text,
+    };
+  }
+  if (block.type === "tool_use" && block.id && block.name) {
+    return {
+      type: EVENT_TYPES.toolCall,
+      toolUseId: block.id,
+      toolName: block.name,
+      args: block.input,
+    };
+  }
+  if (block.type === "tool_result" && block.tool_use_id) {
+    const raw = block.content;
+    const content = typeof raw === "string" ? raw : raw === undefined ? "" : JSON.stringify(raw);
+    return {
+      type: EVENT_TYPES.toolCallResult,
+      toolUseId: block.tool_use_id,
+      content,
+    };
+  }
+  return null;
+}
+
+// Extract a text delta from a stream_event, or null if the event
+// isn't a text delta. Keeps the main parse function under the
+// cognitive-complexity cap.
+function extractTextDelta(event: RawStreamEvent): string | null {
+  if (event.type !== "stream_event" || !event.event) return null;
+  const inner = event.event;
+  if (inner.type !== "content_block_delta" || !("delta" in inner) || inner.delta.type !== "text_delta" || typeof inner.delta.text !== "string") {
+    return null;
+  }
+  return inner.delta.text;
+}
+
+// Filter assistant block events: when deltas already streamed the
+// text, remove text-type events to prevent duplication.
+function filterAssistantBlocks(blockEvents: AgentEvent[], deltaStreamed: boolean): AgentEvent[] {
+  return deltaStreamed ? blockEvents.filter((e) => e.type !== EVENT_TYPES.text) : blockEvents;
+}
+
+// Stateful parser that deduplicates text across the three stages
+// Claude CLI emits: stream_event deltas → assistant content blocks
+// → result full text. Uses two flags:
+//
+//   textStreamedFromDeltas — true once text_delta chunks have been
+//     emitted from stream_event. Controls whether the full-text
+//     `assistant` block is filtered as a duplicate of those chunks.
+//
+//   textEmitted — true once ANY text (delta or assistant block) has
+//     been emitted, so the `result` event can suppress its duplicate
+//     full-text copy. Prevents text loss when `assistant` arrives
+//     without preceding `stream_event` deltas (short replies, CLI
+//     version without `--include-partial-messages`, etc.).
+export function createStreamParser(): {
+  parse: (event: RawStreamEvent) => AgentEvent[];
+} {
+  let textStreamedFromDeltas = false;
+  let textEmitted = false;
+
+  function parse(event: RawStreamEvent): AgentEvent[] {
+    // Handle streaming text deltas from --include-partial-messages.
+    const delta = extractTextDelta(event);
+    if (delta !== null) {
+      textStreamedFromDeltas = true;
+      textEmitted = true;
+      return [{ type: EVENT_TYPES.text, message: delta }];
+    }
+    if (event.type === "stream_event") return [];
+
+    if (event.type === "result") {
+      const events: AgentEvent[] = [];
+      if (!textEmitted && event.result) {
+        events.push({ type: EVENT_TYPES.text, message: event.result });
+      }
+      if (event.session_id) {
+        events.push({
+          type: EVENT_TYPES.claudeSessionId,
+          id: event.session_id,
+        });
+      }
+      textStreamedFromDeltas = false;
+      textEmitted = false;
+      return events;
+    }
+
+    if (event.type !== "assistant" && event.type !== "user") {
+      return [];
+    }
+
+    const content = event.message?.content;
+    const blockEvents = Array.isArray(content) ? content.map(blockToEvent).filter((e): e is AgentEvent => e !== null) : [];
+
+    if (event.type === "assistant") {
+      const filtered = filterAssistantBlocks(blockEvents, textStreamedFromDeltas);
+      if (filtered.some((e) => e.type === EVENT_TYPES.text)) {
+        textEmitted = true;
+      }
+      return [{ type: EVENT_TYPES.status, message: "Thinking..." }, ...filtered];
+    }
+    return blockEvents;
+  }
+
+  return { parse };
+}
+
+// Stateless convenience — used by tests and one-off parsing.
+// For the agent loop, use createStreamParser() to get dedup.
+export function parseStreamEvent(event: RawStreamEvent): AgentEvent[] {
+  if (event.type === "result" && event.result) {
+    const events: AgentEvent[] = [{ type: EVENT_TYPES.text, message: event.result }];
+    if (event.session_id) {
+      events.push({
+        type: EVENT_TYPES.claudeSessionId,
+        id: event.session_id,
+      });
+    }
+    return events;
+  }
+
+  if (event.type !== "assistant" && event.type !== "user") {
+    return [];
+  }
+
+  const content = event.message?.content;
+  const blockEvents = Array.isArray(content) ? content.map(blockToEvent).filter((e): e is AgentEvent => e !== null) : [];
+
+  if (event.type === "assistant") {
+    return [{ type: EVENT_TYPES.status, message: "Thinking..." }, ...blockEvents];
+  }
+  return blockEvents;
+}

package/server/api/auth/bearerAuth.ts

@@ -0,0 +1,61 @@
+import { timingSafeEqual } from "crypto";
+
+function safeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+}
+
+// Bearer token middleware (#272). Reject any `/api/*` request whose
+// `Authorization: Bearer <token>` header doesn't match the current
+// server token.
+//
+// This is the local-process isolation layer. `csrfGuard.ts` handles
+// cross-origin browser attacks (layered on top, both must pass). This
+// middleware handles the case a sibling process on the same machine
+// (malicious program, another user, confused script) tries to hit
+// `/api/*`: without the startup-regenerated token, every request is
+// 401'd.
+//
+// Design choices:
+// - **One exemption**: `/api/files/*` is bearer-exempt because `<img>`
+//   tags in rendered markdown (`presentDocument`, wiki) can't attach
+//   an `Authorization` header — the browser makes a plain GET. These
+//   endpoints are still CSRF-guarded (origin check) and the server
+//   binds to loopback only, so the exposure is localhost-scoped.
+//   The exemption is applied via a regex in `server/index.ts`.
+// - **No token in logs**. Reject messages are generic ("unauthorized")
+//   so a leaked log line doesn't reveal whether "no header" vs
+//   "wrong token" — matches common auth-hardening guidance.
+// - **Token comparison is `===`**. These are 64-char hex strings of
+//   identical length, so early-exit timing on length is moot. A
+//   length-mismatched header is already caught at the shape check,
+//   leaving only equal-length compares for real candidates.
+
+import type { Request, Response, NextFunction } from "express";
+import { getCurrentToken } from "./token.js";
+import { unauthorized } from "../../utils/httpError.js";
+
+const BEARER_PREFIX = "Bearer ";
+
+export function bearerAuth(req: Request, res: Response, next: NextFunction): void {
+  const expected = getCurrentToken();
+  if (expected === null) {
+    // Server hasn't finished bootstrap. This can only happen if a
+    // request beats `generateAndWriteToken()` to completion — the
+    // server fixes that by generating before `app.listen`, but we
+    // still defend the middleware against out-of-order init.
+    unauthorized(res, "unauthorized");
+    return;
+  }
+  const header = req.headers.authorization;
+  if (typeof header !== "string" || !header.startsWith(BEARER_PREFIX)) {
+    unauthorized(res, "unauthorized");
+    return;
+  }
+  const provided = header.slice(BEARER_PREFIX.length);
+  if (!safeEqual(provided, expected)) {
+    unauthorized(res, "unauthorized");
+    return;
+  }
+  next();
+}

package/server/api/auth/token.ts

@@ -0,0 +1,98 @@
+// Bearer auth token (#272). One 32-byte hex token per server startup,
+// held in memory and mirrored to a 0600 file at
+// `WORKSPACE_PATHS.sessionToken`.
+//
+// **Why file-backed**: the token must travel out-of-process to (a) the
+// Vite dev server's `transformIndexHtml` plugin so it can embed the
+// token in the HTML Vue receives, and (b) CLI bridges (Phase 2) that
+// share the workspace but live in a different process. Memory-only
+// would force every reader to go through HTTP, which is the
+// chicken-and-egg problem bearer auth is trying to fix.
+//
+// **Lifecycle**: generate on startup, write atomic, delete on graceful
+// shutdown. A stale file after a crash is harmless — the next startup
+// generates a fresh in-memory token and overwrites, so a stolen stale
+// file value fails 401 against the running server.
+//
+// **Env override (#316)**: `MULMOCLAUDE_AUTH_TOKEN` (read via `env.ts`)
+// pins the token across restarts so long-running bridges don't need a
+// relaunch every time the server bounces. The client-side readers
+// (`@mulmobridge/client` token.ts, Vite plugin) already honour the same var;
+// setting it once on both sides survives restarts.
+
+import { randomBytes } from "crypto";
+import fs from "fs";
+import { writeFileAtomic } from "../../utils/files/index.js";
+import { log } from "../../system/logger/index.js";
+import { isNonEmptyString } from "../../utils/types.js";
+import { WORKSPACE_PATHS } from "../../workspace/paths.js";
+
+const TOKEN_BYTES = 32; // 64 hex chars
+// Below this length a random 32-byte token would be 64 hex chars;
+// anything shorter from the env override is almost certainly a
+// placeholder like "test" that leaked into production. Warn, don't
+// block — the operator might have reasons we don't see.
+const MIN_RECOMMENDED_CHARS = 32;
+
+let currentToken: string | null = null;
+
+/**
+ * The token the server is currently using. Null until
+ * `generateAndWriteToken` has been called. `bearerAuth` reads this on
+ * every request.
+ */
+export function getCurrentToken(): string | null {
+  return currentToken;
+}
+
+/**
+ * Generate (or take from the env override) the startup token, store
+ * it in memory, and mirror it to the workspace file (mode 0600,
+ * atomic).
+ *
+ * @param tokenPath Injected for tests so they can target a tmp
+ *   directory; production callers rely on the default
+ *   `WORKSPACE_PATHS.sessionToken`.
+ * @param override Injected for tests. Production callers pass
+ *   `env.authTokenOverride` from `server/env.ts`. When non-empty the
+ *   override is used verbatim instead of generating random bytes.
+ */
+export async function generateAndWriteToken(tokenPath: string = WORKSPACE_PATHS.sessionToken, override?: string): Promise<string> {
+  const token = resolveToken(override);
+  currentToken = token;
+  await writeFileAtomic(tokenPath, token, { mode: 0o600 });
+  return token;
+}
+
+function resolveToken(override: string | undefined): string {
+  if (isNonEmptyString(override)) {
+    if (override.length < MIN_RECOMMENDED_CHARS) {
+      // Visible on startup so a half-typed override doesn't silently
+      // become a security hole in dev.
+      log.warn("auth", "MULMOCLAUDE_AUTH_TOKEN is shorter than the recommended 32 characters", { length: override.length });
+    }
+    return override;
+  }
+  return randomBytes(TOKEN_BYTES).toString("hex");
+}
+
+/**
+ * Best-effort removal of the token file. Never throws; a missing file
+ * is a success for our purposes (nothing to clean up). Caller is
+ * responsible for not using the in-memory token after calling this.
+ */
+export async function deleteTokenFile(tokenPath: string = WORKSPACE_PATHS.sessionToken): Promise<void> {
+  try {
+    await fs.promises.unlink(tokenPath);
+  } catch {
+    /* already gone — nothing to do */
+  }
+}
+
+/**
+ * Test-only: reset module state so a suite can simulate fresh startup
+ * without reloading the module. Not exported to production callers.
+ */
+export function __resetForTests(): void {
+  currentToken = null;
+}