fix(api): harden token handling after code review

Addresses seven findings from reviewing the client-verification feature:

- Percent-decode the ?token= query carrier. The web client escapes the
  token in the SSE URL, so a CCTRACE_API_TOKEN containing URL-reserved
  characters used to fail only on the EventSource path.
- Give the unpersisted fallback token its own source, "ephemeral", instead
  of reporting it as env-provided. Settings now explains that the token
  file could not be written rather than blaming CCTRACE_API_TOKEN, and
  Regenerate is disabled with an accurate message.
- Heal multi-process divergence: on a token mismatch the middleware
  re-reads the token file once and adopts a rotated value before
  rejecting, so a second cctrace process sharing the file no longer
  returns 401 until restarted. Happy-path requests never touch the disk.
- Rotate atomically via a 0600 temp file and rename, so concurrent readers
  (the TUI re-reads per request, Vite watches the file) never observe an
  empty file. The first-run reader also retries briefly while the O_EXCL
  creator is still writing.
- The Node helper no longer fabricates a token when the file exists but is
  empty; it retries briefly, then throws so Vite fails loudly instead of
  baking a token no backend accepts.
- MessageDetail drops the saved main-body scroll offset when a panel is
  replaced at the same depth, instead of restoring a stale position on the
  next unrelated push or pop.
- The static-fallback cookie middleware resolves the origin allowlist only
  for HTML responses, not for every asset request.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ARMV5uP7TQ9NyXsqAjpo2E

Author: claude

bin/api-token.mjs

@@ -43,6 +43,26 @@ function readToken(path) {
   }
 }
 
+/** Synchronous pause — Vite's `config` hook is synchronous, and the window
+ * between the backend's O_EXCL create and its write is a few milliseconds. */
+function pauseMs(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+const EMPTY_FILE_RETRIES = 10;
+const EMPTY_FILE_RETRY_MS = 20;
+
+/** Re-read a file another creator has just made, tolerating the moment
+ * between its create and its write. */
+function readTokenWithRetry(path) {
+  for (let attempt = 0; attempt <= EMPTY_FILE_RETRIES; attempt++) {
+    const t = readToken(path);
+    if (t) return t;
+    if (attempt < EMPTY_FILE_RETRIES) pauseMs(EMPTY_FILE_RETRY_MS);
+  }
+  return null;
+}
+
 /**
  * Resolve the token the web UI should send, or `null` when verification is
  * off. Creates the token file (mode 0600) when it does not exist yet.
@@ -63,7 +83,16 @@ export function resolveApiToken(opts = {}) {
     writeFileSync(path, `${fresh}\n`, { flag: "wx", mode: 0o600 });
     return fresh;
   } catch (err) {
-    if (err && err.code === "EEXIST") return readToken(path) ?? fresh;
+    if (err && err.code === "EEXIST") {
+      const winner = readTokenWithRetry(path);
+      if (winner) return winner;
+      // Never hand the UI a token no backend accepts: fail loudly instead, the
+      // same way the Rust side treats an empty token file.
+      throw new Error(
+        `api-token file exists but is empty: ${path} — delete it and restart, or set CCTRACE_API_TOKEN`,
+        { cause: err },
+      );
+    }
     throw err;
   }
 }

bin/api-token.test.mjs

@@ -19,6 +19,11 @@ const enoent = () => {
   e.code = "ENOENT";
   throw e;
 };
+const eexist = () => {
+  const e = new Error("EEXIST");
+  e.code = "EEXIST";
+  throw e;
+};
 
 beforeEach(() => {
   vi.clearAllMocks();
@@ -96,14 +101,26 @@ describe("resolveApiToken", () => {
 
   it("re-reads the winner's token when the backend created the file first (EEXIST)", () => {
     readFileSync.mockImplementationOnce(enoent).mockImplementation(() => "winner\n");
-    writeFileSync.mockImplementation(() => {
-      const e = new Error("EEXIST");
-      e.code = "EEXIST";
-      throw e;
-    });
+    writeFileSync.mockImplementation(eexist);
     expect(resolveApiToken({ ...opts, env: {} })).toBe("winner");
   });
 
+  it("waits for the winner to finish writing when the file is momentarily empty", () => {
+    readFileSync
+      .mockImplementationOnce(enoent) // initial probe: not there yet
+      .mockImplementationOnce(() => "") // EEXIST: created but not yet written
+      .mockImplementationOnce(() => "\n")
+      .mockImplementation(() => "winner\n");
+    writeFileSync.mockImplementation(eexist);
+    expect(resolveApiToken({ ...opts, env: {} })).toBe("winner");
+  });
+
+  it("throws instead of fabricating a token when the file stays empty", () => {
+    readFileSync.mockImplementationOnce(enoent).mockImplementation(() => "");
+    writeFileSync.mockImplementation(eexist);
+    expect(() => resolveApiToken({ ...opts, env: {} })).toThrow(/exists but is empty/);
+  });
+
   it("rethrows unexpected write errors", () => {
     writeFileSync.mockImplementation(() => {
       const e = new Error("EACCES");

specs/04-http-api.md

@@ -77,8 +77,9 @@ state (see [Authentication](#authentication)).
 }
 ```
 
-`api_token_source` is `"file"` (rotatable from Settings), `"env"` (`CCTRACE_API_TOKEN`, read-only)
-or `"disabled"` (`CCTRACE_API_AUTH=off`, `api_token` is `null`).
+`api_token_source` is `"file"` (rotatable from Settings), `"env"` (`CCTRACE_API_TOKEN`, read-only),
+`"ephemeral"` (the token file was unusable at startup; one-off, read-only) or `"disabled"`
+(`CCTRACE_API_AUTH=off`, `api_token` is `null`).
 
 ---
 
@@ -401,11 +402,18 @@ over IPC, never HTTP.
 
 Creation uses `O_EXCL`: in `cctrace --web`, Tauri starts Vite _before_ the Rust binary, and the
 Vite plugin (`bin/api-token.mjs`) may create the file first. Whichever side loses the race re-reads
-the winner's token, so both converge. If the file cannot be read or created the server fails
-**closed** — it runs with an unpersisted random token, never unauthenticated.
+the winner's token (retrying briefly while the winner is still writing), so both converge. If the
+file cannot be read or created the server fails **closed**: it runs with an unpersisted one-off token
+(`api_token_source: "ephemeral"`), never unauthenticated, and Settings says so rather than blaming
+`CCTRACE_API_TOKEN`. The Vite side throws instead, so the dev server fails loudly rather than baking
+a token no backend accepts.
 
 `AppState.api_auth: RwLock<ApiAuth>` holds the live value; the middleware reads it on every request
-so a rotation takes effect immediately.
+so a rotation takes effect immediately. Rotation writes a sibling temp file and renames it over the
+token file, so concurrent readers never see it empty. When a request's token does **not** match and
+the live token came from the file, the middleware re-reads the file once before rejecting: if another
+cctrace process (a background `--web` service next to the desktop app, say) rotated it, the live
+token heals on the spot instead of every client getting 401 until a restart.
 
 ### Accepted carriers (`auth::require_api_token`)
 
@@ -446,9 +454,10 @@ still 404 rather than 401.
 
 ### Settings UI
 
-`GET /api/settings` reports `api_auth_enabled`, `api_token_source` (`"file" | "env" | "disabled"`)
-and `api_token`. The Settings modal's **API access** section shows the token masked with Show /
-Copy / Regenerate; Regenerate is a two-click confirm and is disabled for `env` tokens.
+`GET /api/settings` reports `api_auth_enabled`, `api_token_source`
+(`"file" | "env" | "ephemeral" | "disabled"`) and `api_token`. The Settings modal's **API access**
+section shows the token masked with Show / Copy / Regenerate; Regenerate is a two-click confirm and
+is disabled for `env` and `ephemeral` tokens.
 `POST /api/settings/token/regenerate` (or the `regenerate_api_token` Tauri command) performs the
 rotation.