@wrongstack/cli 0.297.0 → 0.298.0

package/dist/{chunk-7JABKXET.js → chunk-C5GH4YBL.js}

@@ -4,9 +4,9 @@ import {
 
 // src/hq-server.ts
 import { randomUUID as randomUUID4 } from "node:crypto";
-import * as fs4 from "node:fs/promises";
+import * as fs5 from "node:fs/promises";
 import * as http from "node:http";
-import * as path6 from "node:path";
+import * as path7 from "node:path";
 import {
   createMailboxHttpRouter,
   createProjectMailbox,
@@ -16,16 +16,20 @@ import {
   MailboxHttpRateLimiter
 } from "@wrongstack/core/coordination";
 import {
+  assessHqExposure as assessHqExposure2,
   createHqPersistence,
   HqAlertEngine,
   HqBootstrapCodeStore,
   HqCommandAuditLog,
+  hqTokenKey as hqTokenKey3,
+  hqTokenVerifier as hqTokenVerifier2,
   mintHqCookieSecret as mintHqCookieSecret2,
   mutateHqAuthFile as mutateHqAuthFile2,
   toAlertMessage,
   watchHqAuthFile
 } from "@wrongstack/core/hq";
 import { createCompatibilityTrustBoundary } from "@wrongstack/core/security";
+import { isLoopbackHost as isLoopbackHost3 } from "@wrongstack/core/hq";
 import { WebSocket as WebSocket3, WebSocketServer } from "ws";
 
 // src/hq-recovery-html.ts
@@ -55,8 +59,14 @@ var HQ_HTML = HQ_RECOVERY_HTML;
 // src/hq-server/auth.ts
 import { createHmac, timingSafeEqual } from "node:crypto";
 import { isIP } from "node:net";
+import { hqTokenVerifier, isLoopbackHost, isTokenExpired } from "@wrongstack/core/hq";
 var HQ_SESSION_COOKIE = "hq.session";
+var HQ_SESSION_COOKIE_SECURE = "__Host-hq.session";
+function cookieName(secure) {
+  return secure ? HQ_SESSION_COOKIE_SECURE : HQ_SESSION_COOKIE;
+}
 var HQ_SESSION_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1e3;
+var HQ_SESSION_IDLE_TIMEOUT_MS = 30 * 6e4;
 function setHqSecurityHeaders(res) {
   res.setHeader("X-Content-Type-Options", "nosniff");
   res.setHeader("X-Frame-Options", "DENY");
@@ -70,7 +80,7 @@ function setHqSecurityHeaders(res) {
       "object-src 'none'",
       "frame-ancestors 'none'",
       "form-action 'self'",
-      "script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval'",
+      "script-src 'self' 'wasm-unsafe-eval'",
       "style-src 'self' 'unsafe-inline'",
       "font-src 'self' data:",
       "img-src 'self' data:",
@@ -106,13 +116,13 @@ function hasTrustedRequestAuthority(req, boundHost, boundPort, trustedPublicOrig
     return false;
   }
 }
-function hasTrustedBrowserOrigin(req, boundHost, boundPort, trustedPublicOrigins = /* @__PURE__ */ new Set()) {
+function hasTrustedBrowserOrigin(req, boundHost, boundPort, trustedPublicOrigins = /* @__PURE__ */ new Set(), allowFileOrigin = false) {
   if (!hasTrustedRequestAuthority(req, boundHost, boundPort, trustedPublicOrigins)) return false;
   const origin = req.headers.origin;
   if (origin === void 0) return true;
   try {
     const parsed = new URL(origin);
-    if (parsed.protocol === "file:") return true;
+    if (parsed.protocol === "file:") return allowFileOrigin;
     if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
     const rawRequestHost = req.headers.host?.trim();
     if (!rawRequestHost) return false;
@@ -165,8 +175,9 @@ function parseCookieHeader(cookieHeader) {
   return out;
 }
 function setHqSessionCookie(res, value, secure) {
+  const name = cookieName(secure);
   const parts = [
-    `${HQ_SESSION_COOKIE}=${encodeURIComponent(value)}`,
+    `${name}=${encodeURIComponent(value)}`,
     "Path=/",
     "HttpOnly",
     "SameSite=Lax",
@@ -176,7 +187,8 @@ function setHqSessionCookie(res, value, secure) {
   res.setHeader("Set-Cookie", parts.join("; "));
 }
 function clearHqSessionCookie(res, secure) {
-  const parts = [`${HQ_SESSION_COOKIE}=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0`];
+  const name = cookieName(secure);
+  const parts = [`${name}=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0`];
   if (secure) parts.push("Secure");
   res.setHeader("Set-Cookie", parts.join("; "));
 }
@@ -186,18 +198,40 @@ function isTokenAuth(auth) {
 function isCookieAuth(auth) {
   return auth !== void 0 && auth.kind === "cookie";
 }
+function hqAuthRequired(mutableAuth, requireBrowserAuth) {
+  return requireBrowserAuth === true || mutableAuth.requireAuthFloor === true || mutableAuth.browserTokens.size > 0 || mutableAuth.passwordHash !== void 0;
+}
+function hqClientAuthRequired(mutableAuth) {
+  return mutableAuth.requireAuthFloor === true || mutableAuth.clientTokens.size > 0;
+}
 function extractBrowserToken(req, url) {
   const queryToken = url.searchParams.get("token");
   if (queryToken) {
+    const requestHost = (req.headers.host ?? "").trim();
+    let hostname = "";
+    try {
+      hostname = new URL(`http://${requestHost}`).hostname;
+    } catch {
+    }
+    if (hostname && isLoopbackHost(hostname)) {
+      console.warn(
+        JSON.stringify({
+          level: "warn",
+          event: "hq.token_from_query_param",
+          message: "Browser token accepted from URL query parameter \u2014 token can leak through browser history, server access logs, and Referer headers.",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        })
+      );
+      return queryToken;
+    }
     console.warn(
       JSON.stringify({
         level: "warn",
-        event: "hq.token_from_query_param",
-        message: "Browser token accepted from URL query parameter \u2014 token can leak through browser history, server access logs, and Referer headers.",
+        event: "hq.token_from_query_param_rejected",
+        message: "Browser token in URL query rejected on a non-loopback request \u2014 send it in the Authorization header instead.",
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       })
     );
-    return queryToken;
   }
   const auth = req.headers.authorization;
   if (typeof auth === "string" && auth.toLowerCase().startsWith("bearer ")) {
@@ -207,7 +241,7 @@ function extractBrowserToken(req, url) {
 }
 function timingSafeTokenMatch(tokens, supplied) {
   if (!supplied) return void 0;
-  const b = Buffer.from(supplied);
+  const b = Buffer.from(hqTokenVerifier(supplied));
   for (const candidate of tokens) {
     const a = Buffer.from(candidate);
     if (a.length === b.length && timingSafeEqual(a, b)) return candidate;
@@ -220,6 +254,7 @@ function authenticateBrowserRequest(req, url, mutableAuth, sessions) {
     const matchedToken = timingSafeTokenMatch(mutableAuth.browserTokens, token);
     if (matchedToken) {
       const obj = mutableAuth.browserTokenObjs.get(matchedToken);
+      if (isTokenExpired(obj)) return void 0;
       const ctx = {
         kind: "token",
         token: matchedToken,
@@ -231,12 +266,19 @@ function authenticateBrowserRequest(req, url, mutableAuth, sessions) {
   }
   if (mutableAuth.cookieSecret) {
     const cookies = parseCookieHeader(req.headers.cookie);
-    const raw = cookies[HQ_SESSION_COOKIE];
+    const raw = cookies[HQ_SESSION_COOKIE] ?? cookies["__Host-hq.session"];
     if (raw) {
       const sessionId = parseHqSessionCookie(raw, mutableAuth.cookieSecret);
       if (sessionId) {
         const session = sessions.get(sessionId);
-        if (session && Date.now() - session.createdAt < HQ_SESSION_MAX_AGE_MS) {
+        const now = Date.now();
+        if (session && now - session.createdAt < HQ_SESSION_MAX_AGE_MS) {
+          if (session.pending2fa) return void 0;
+          if (now - session.lastSeenAt > HQ_SESSION_IDLE_TIMEOUT_MS) {
+            sessions.delete(sessionId);
+            return void 0;
+          }
+          session.lastSeenAt = now;
           if (session.kind === "token" && session.tokenId !== void 0) {
             const liveToken = [...mutableAuth.browserTokenObjs.values()].find(
               (obj) => obj.id === session.tokenId
@@ -259,10 +301,16 @@ function authenticateBrowserRequest(req, url, mutableAuth, sessions) {
 }
 
 // src/hq-server/auth-state.ts
-import { DEFAULT_HQ_REDACTION_POLICY, hqAuthContentHash, isTokenExpired, logHqAuthAudit } from "@wrongstack/core/hq";
+import {
+  DEFAULT_HQ_REDACTION_POLICY,
+  hqAuthContentHash,
+  hqTokenKey,
+  isTokenExpired as isTokenExpired2,
+  logHqAuthAudit
+} from "@wrongstack/core/hq";
 var TOKEN_EXPIRY_WARNING_MS = 24 * 60 * 60 * 1e3;
 function liveTokens(list) {
-  return (list ?? []).filter((token) => !isTokenExpired(token));
+  return (list ?? []).filter((token) => !isTokenExpired2(token));
 }
 function createHqAuthState(authFile, dataDir) {
   let rawBrowserTokens = authFile.browserTokens ?? [];
@@ -270,12 +318,17 @@ function createHqAuthState(authFile, dataDir) {
   const mutableAuth = {
     operatorPolicy: { ...DEFAULT_HQ_REDACTION_POLICY, ...authFile.redactionPolicy ?? {} },
     operatorPolicyOverride: authFile.redactionPolicy,
-    browserTokens: new Set(liveTokens(authFile.browserTokens).map(({ token }) => token)),
-    clientTokens: new Set(liveTokens(authFile.clientTokens).map(({ token }) => token)),
+    browserTokens: new Set(liveTokens(authFile.browserTokens).map(hqTokenKey)),
+    clientTokens: new Set(liveTokens(authFile.clientTokens).map(hqTokenKey)),
     browserTokenObjs: browserTokenMap(authFile.browserTokens),
-    clientTokenObjs: new Map(liveTokens(authFile.clientTokens).map((token) => [token.token, token])),
+    clientTokenObjs: new Map(
+      liveTokens(authFile.clientTokens).map((token) => [hqTokenKey(token), token])
+    ),
     passwordHash: authFile.passwordHash,
     cookieSecret: authFile.cookieSecret,
+    totpSecret: authFile.totpSecret,
+    totpPendingSecret: authFile.totpPendingSecret,
+    totpRecoveryCodes: authFile.totpRecoveryCodes,
     alertRules: authFile.alertRules
   };
   return {
@@ -283,7 +336,7 @@ function createHqAuthState(authFile, dataDir) {
     tokenStats: () => {
       const now = Date.now();
       const all = [...rawBrowserTokens, ...rawClientTokens];
-      const live = all.filter((token) => !isTokenExpired(token, now));
+      const live = all.filter((token) => !isTokenExpired2(token, now));
       return {
         browserTotal: mutableAuth.browserTokens.size,
         clientTotal: mutableAuth.clientTokens.size,
@@ -307,14 +360,17 @@ function createHqAuthState(authFile, dataDir) {
         ...next.redactionPolicy ?? {}
       };
       mutableAuth.operatorPolicyOverride = next.redactionPolicy;
-      mutableAuth.browserTokens = new Set(liveTokens(next.browserTokens).map(({ token }) => token));
-      mutableAuth.clientTokens = new Set(liveTokens(next.clientTokens).map(({ token }) => token));
+      mutableAuth.browserTokens = new Set(liveTokens(next.browserTokens).map(hqTokenKey));
+      mutableAuth.clientTokens = new Set(liveTokens(next.clientTokens).map(hqTokenKey));
       mutableAuth.browserTokenObjs = browserTokenMap(next.browserTokens);
       mutableAuth.clientTokenObjs = new Map(
-        liveTokens(next.clientTokens).map((token) => [token.token, token])
+        liveTokens(next.clientTokens).map((token) => [hqTokenKey(token), token])
       );
       mutableAuth.passwordHash = next.passwordHash;
       mutableAuth.cookieSecret = next.cookieSecret;
+      mutableAuth.totpSecret = next.totpSecret;
+      mutableAuth.totpPendingSecret = next.totpPendingSecret;
+      mutableAuth.totpRecoveryCodes = next.totpRecoveryCodes;
       mutableAuth.alertRules = next.alertRules;
     }
   };
@@ -322,7 +378,7 @@ function createHqAuthState(authFile, dataDir) {
 function browserTokenMap(tokens) {
   return new Map(
     liveTokens(tokens).map((token) => [
-      token.token,
+      hqTokenKey(token),
       {
         id: token.id,
         ...token.capabilities !== void 0 ? { capabilities: token.capabilities } : {},
@@ -332,8 +388,12 @@ function browserTokenMap(tokens) {
   );
 }
 function auditPrunedTokens(scope, previous, next, authFile, dataDir) {
-  const previouslyLive = new Set(previous.filter((token) => !isTokenExpired(token)).map(({ id }) => id));
-  const prunedCount = next.filter((token) => isTokenExpired(token) && previouslyLive.has(token.id)).length;
+  const previouslyLive = new Set(
+    previous.filter((token) => !isTokenExpired2(token)).map(({ id }) => id)
+  );
+  const prunedCount = next.filter(
+    (token) => isTokenExpired2(token) && previouslyLive.has(token.id)
+  ).length;
   if (prunedCount === 0) return;
   const contentHash = hqAuthContentHash(authFile);
   logHqAuthAudit(dataDir, {
@@ -345,8 +405,159 @@ function auditPrunedTokens(scope, previous, next, authFile, dataDir) {
   });
 }
 
+// src/hq-server/login-attempt-store.ts
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { atomicWrite } from "@wrongstack/core/utils";
+import { restrictFilePermissions } from "@wrongstack/core/security";
+var LoginAttemptStore = class _LoginAttemptStore {
+  store = /* @__PURE__ */ new Map();
+  writeTimer;
+  dirty = false;
+  filePath;
+  debounceMs;
+  retentionMs;
+  constructor(dataDir, opts) {
+    this.filePath = path.join(dataDir, "login-attempts.json");
+    this.debounceMs = opts?.debounceMs ?? 500;
+    this.retentionMs = opts?.retentionMs ?? 15 * 6e4;
+  }
+  /**
+   * Load persisted state from disk and prune stale entries.
+   * Safe to call once at startup; subsequent calls reload from disk.
+   */
+  async load() {
+    try {
+      const raw = await fs.readFile(this.filePath, "utf8");
+      const parsed = JSON.parse(raw);
+      const cutoff = Date.now() - this.retentionMs;
+      for (const [key, entry] of Object.entries(parsed)) {
+        if (entry && typeof entry.lastAttempt === "number" && entry.lastAttempt > cutoff) {
+          this.store.set(key, entry);
+        }
+      }
+    } catch {
+    }
+  }
+  get(key) {
+    return this.store.get(key);
+  }
+  set(key, entry) {
+    this.store.set(key, entry);
+    this.scheduleWrite();
+  }
+  delete(key) {
+    if (this.store.delete(key)) {
+      this.scheduleWrite();
+    }
+  }
+  /**
+   * Compound rate-limit key for public-relay mode: IP + SHA-256(password).
+   * Limits how often the SAME password can be tried from different IPs,
+   * so a rotating-IP attacker can't bypass per-IP backoff.
+   */
+  static credentialKey(ip, password) {
+    const hash = createHash("sha256").update(password, "utf8").digest("hex").slice(0, 16);
+    return `cred:${ip}:${hash}`;
+  }
+  /**
+   * Check both IP and credential keys; return the stricter (later blockedUntil).
+   */
+  checkBlocked(ip, password) {
+    const ipEntry = this.store.get(ip);
+    const credKey = _LoginAttemptStore.credentialKey(ip, password);
+    const credEntry = this.store.get(credKey);
+    const now = Date.now();
+    const ipBlocked = ipEntry && ipEntry.blockedUntil > now ? ipEntry.blockedUntil : 0;
+    const credBlocked = credEntry && credEntry.blockedUntil > now ? credEntry.blockedUntil : 0;
+    const blockedUntil = Math.max(ipBlocked, credBlocked);
+    if (blockedUntil > now) {
+      return { blocked: true, retryAfter: Math.ceil((blockedUntil - now) / 1e3) };
+    }
+    return { blocked: false, retryAfter: 0 };
+  }
+  /**
+   * Record a failed attempt on both IP and credential keys.
+   * Returns the updated IP entry (for the response Retry-After header).
+   */
+  recordFailure(ip, password, maxBackoffMs = 16e3) {
+    const backoff = (prev) => {
+      const count = (prev?.count ?? 0) + 1;
+      return {
+        count,
+        blockedUntil: Date.now() + Math.min(2 ** count * 1e3, maxBackoffMs),
+        lastAttempt: Date.now()
+      };
+    };
+    this.set(ip, backoff(this.store.get(ip)));
+    const credKey = _LoginAttemptStore.credentialKey(ip, password);
+    this.set(credKey, backoff(this.store.get(credKey)));
+    return this.store.get(ip);
+  }
+  /**
+   * Clear both IP and credential entries on successful login.
+   */
+  clearOnSuccess(ip, password) {
+    this.delete(ip);
+    this.delete(_LoginAttemptStore.credentialKey(ip, password));
+  }
+  /** Number of tracked entries (for diagnostics). */
+  get size() {
+    return this.store.size;
+  }
+  /**
+   * Flush pending writes immediately. Called on server shutdown.
+   */
+  async flush() {
+    if (this.writeTimer) {
+      clearTimeout(this.writeTimer);
+      this.writeTimer = void 0;
+    }
+    if (this.dirty) {
+      await this.writeToDisk();
+    }
+  }
+  scheduleWrite() {
+    this.dirty = true;
+    if (this.writeTimer) return;
+    this.writeTimer = setTimeout(() => {
+      this.writeTimer = void 0;
+      void this.writeToDisk();
+    }, this.debounceMs);
+    this.writeTimer.unref?.();
+  }
+  async writeToDisk() {
+    this.dirty = false;
+    const now = Date.now();
+    const cutoff = now - this.retentionMs;
+    const obj = {};
+    for (const [key, entry] of this.store) {
+      if (entry.lastAttempt > cutoff) {
+        obj[key] = entry;
+      } else {
+        this.store.delete(key);
+      }
+    }
+    try {
+      await atomicWrite(this.filePath, JSON.stringify(obj, null, 2), { mode: 384 });
+      await restrictFilePermissions(this.filePath, { label: "hq-login-attempts" });
+    } catch {
+    }
+  }
+  /** Iterate entries (for cleanup timers). */
+  entries() {
+    return this.store.entries();
+  }
+};
+
 // src/hq-server/preflight.ts
-import { assessHqExposure, ensureHqFirstRunAuthFile, resolveHqDataDir } from "@wrongstack/core/hq";
+import {
+  assessHqExposure,
+  ensureHqFirstRunAuthFile,
+  isTokenExpired as isTokenExpired3,
+  resolveHqDataDir
+} from "@wrongstack/core/hq";
 import { HqInsecureExposureError } from "@wrongstack/core/hq";
 async function prepareHqServerStart(options, defaults) {
   const host = options.host ?? defaults.host;
@@ -366,18 +577,26 @@ async function prepareHqServerStart(options, defaults) {
     ...options.tokenTtlMs !== void 0 ? { tokenTtlMs: options.tokenTtlMs } : {}
   });
   const { authFile } = firstRunAuth;
-  if (options.requireBrowserAuth && (authFile.browserTokens ?? []).length === 0 && authFile.passwordHash === void 0) {
+  const rawBrowserTokens = authFile.browserTokens ?? [];
+  const liveBrowserTokens = rawBrowserTokens.filter((token) => !isTokenExpired3(token));
+  const hasPassword = authFile.passwordHash !== void 0;
+  const allTokensExpired = rawBrowserTokens.length > 0 && liveBrowserTokens.length === 0;
+  if (options.requireBrowserAuth && liveBrowserTokens.length === 0 && !hasPassword) {
     throw new HqInsecureExposureError(
-      "HQ public relay requires browser authentication. Set --password or create a browser token first."
+      allTokensExpired ? `HQ public relay requires browser authentication, but all ${rawBrowserTokens.length} browser token(s) in the auth file have expired. Create a fresh token or set --password.` : "HQ public relay requires browser authentication. Set --password or create a browser token first."
     );
   }
   const exposure = assessHqExposure({
     host,
-    hasBrowserTokens: (authFile.browserTokens ?? []).length > 0,
-    hasPassword: authFile.passwordHash !== void 0,
+    hasBrowserTokens: liveBrowserTokens.length > 0,
+    hasPassword,
     allowInsecure: options.allowInsecureOpen
   });
-  if (exposure.kind === "refuse") throw new HqInsecureExposureError(exposure.message);
+  if (exposure.kind === "refuse") {
+    throw new HqInsecureExposureError(
+      allTokensExpired ? `${exposure.message} (all ${rawBrowserTokens.length} browser token(s) in the auth file have expired)` : exposure.message
+    );
+  }
   if (exposure.kind === "warn") {
     console.warn(
       JSON.stringify({
@@ -394,16 +613,16 @@ async function prepareHqServerStart(options, defaults) {
 
 // src/hq-server/routes.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
-import * as path4 from "node:path";
+import * as path5 from "node:path";
 import { tokenHasCapability, validateHqCommand } from "@wrongstack/core/hq";
 import {
   resolveProjectDir
 } from "@wrongstack/core/coordination";
 
 // src/hq-static-serve.ts
-import * as fs from "node:fs";
+import * as fs2 from "node:fs";
 import { createRequire } from "node:module";
-import * as path from "node:path";
+import * as path2 from "node:path";
 var requireFromHere = createRequire(import.meta.url);
 var MIME = {
   ".html": "text/html; charset=utf-8",
@@ -423,22 +642,22 @@ function resolveHqDistDir() {
   if (cachedDistDir !== void 0) return cachedDistDir;
   try {
     const pkgJson = requireFromHere.resolve("@wrongstack/webui-hq/package.json");
-    const dist = path.join(path.dirname(pkgJson), "dist");
-    if (fs.existsSync(path.join(dist, "index.html"))) {
+    const dist = path2.join(path2.dirname(pkgJson), "dist");
+    if (fs2.existsSync(path2.join(dist, "index.html"))) {
       cachedDistDir = dist;
       return dist;
     }
   } catch {
   }
   try {
-    let dir = path.dirname(new URL(import.meta.url).pathname.replace(/^\/(\w:)/, "$1"));
+    let dir = path2.dirname(new URL(import.meta.url).pathname.replace(/^\/(\w:)/, "$1"));
     for (let i = 0; i < 8; i++) {
-      const candidate = path.join(dir, "node_modules", "@wrongstack", "webui-hq", "dist");
-      if (fs.existsSync(path.join(candidate, "index.html"))) {
+      const candidate = path2.join(dir, "node_modules", "@wrongstack", "webui-hq", "dist");
+      if (fs2.existsSync(path2.join(candidate, "index.html"))) {
         cachedDistDir = candidate;
         return candidate;
       }
-      const parent = path.dirname(dir);
+      const parent = path2.dirname(dir);
       if (parent === dir) break;
       dir = parent;
     }
@@ -448,8 +667,8 @@ function resolveHqDistDir() {
   return null;
 }
 function isInsideDist(filePath, distDir) {
-  const rel = path.relative(distDir, filePath);
-  return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+  const rel = path2.relative(distDir, filePath);
+  return rel !== "" && !rel.startsWith("..") && !path2.isAbsolute(rel);
 }
 function isMissingPath(error) {
   const code = error.code;
@@ -457,9 +676,9 @@ function isMissingPath(error) {
 }
 async function readRegularFile(filePath) {
   try {
-    const info = await fs.promises.stat(filePath);
+    const info = await fs2.promises.stat(filePath);
     if (!info.isFile()) return null;
-    return await fs.promises.readFile(filePath);
+    return await fs2.promises.readFile(filePath);
   } catch (error) {
     if (isMissingPath(error)) return null;
     throw error;
@@ -473,13 +692,13 @@ async function serveHqStatic(_req, res, urlPath, distDir) {
   } catch {
     return { handled: false };
   }
-  const filePath = path.join(distDir, decodedPath);
+  const filePath = path2.join(distDir, decodedPath);
   if (!isInsideDist(filePath, distDir)) {
     return { handled: false };
   }
   const data = await readRegularFile(filePath);
   if (data === null) {
-    const indexPath = path.join(distDir, "index.html");
+    const indexPath = path2.join(distDir, "index.html");
     const html = await readRegularFile(indexPath);
     if (html !== null) {
       res.writeHead(200, {
@@ -492,7 +711,7 @@ async function serveHqStatic(_req, res, urlPath, distDir) {
     }
     return { handled: false };
   }
-  const ext = path.extname(filePath).toLowerCase();
+  const ext = path2.extname(filePath).toLowerCase();
   const mime = MIME[ext] ?? "application/octet-stream";
   const cacheControl = decodedPath.startsWith("/assets/") ? "public, max-age=31536000, immutable" : ext === ".html" ? "no-cache" : "public, max-age=3600";
   res.writeHead(200, {
@@ -508,10 +727,11 @@ async function serveHqStatic(_req, res, urlPath, distDir) {
 import { WebSocket } from "ws";
 
 // src/hq-server/utils.ts
-import * as fs2 from "node:fs/promises";
+import * as fs3 from "node:fs/promises";
 import * as os from "node:os";
-import * as path2 from "node:path";
+import * as path3 from "node:path";
 import { resolveHqDataDir as resolveHqDataDir2 } from "@wrongstack/core/hq";
+import { sanitizeApiError, scrubErrorDetail } from "@wrongstack/core/security";
 var TRANSCRIPT_RING_MAX = 4e3;
 var MAX_TRANSCRIPT_SESSIONS = 400;
 var MAX_AGENT_RINGS = 800;
@@ -540,14 +760,17 @@ async function readLocalSubagentTranscript(sessionId, subagentId) {
   try {
     const { SessionRegistry } = await import("@wrongstack/core/storage");
     const { resolveWstackPaths, sessionScopedPath } = await import("@wrongstack/core/utils");
-    const globalRoot = path2.dirname(resolveHqDataDir2());
+    const globalRoot = path3.dirname(resolveHqDataDir2());
     const registry = new SessionRegistry(globalRoot);
     const entry = await registry.get(sessionId).catch(() => null);
     if (!entry) return null;
     const paths = resolveWstackPaths({ projectRoot: entry.projectRoot, globalRoot });
     const sessionDir = sessionScopedPath(paths.projectSessions, sessionId, "");
-    const file = path2.join(sessionDir, "subagents", "transcripts", subagentId, "transcript.jsonl");
-    const raw = await fs2.readFile(file, "utf8").catch(() => null);
+    if (!isSafePathSegment(subagentId)) return null;
+    const transcriptsRoot = path3.resolve(sessionDir, "subagents", "transcripts");
+    const file = path3.resolve(transcriptsRoot, subagentId, "transcript.jsonl");
+    if (!file.startsWith(transcriptsRoot + path3.sep)) return null;
+    const raw = await fs3.readFile(file, "utf8").catch(() => null);
     if (raw === null) return null;
     const out = [];
     for (const line of raw.split("\n")) {
@@ -564,11 +787,38 @@ async function readLocalSubagentTranscript(sessionId, subagentId) {
   }
 }
 function decodePathSegment(value) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+    return null;
+  }
+  return isSafePathSegment(decoded) ? decoded : null;
+}
+function decodeSessionId(value) {
+  let decoded;
   try {
-    return decodeURIComponent(value);
+    decoded = decodeURIComponent(value);
   } catch {
     return null;
   }
+  return isSafeSessionId(decoded) ? decoded : null;
+}
+var MAX_PATH_SEGMENT_LENGTH = 256;
+function isSafePathSegment(value) {
+  if (value.length === 0 || value.length > MAX_PATH_SEGMENT_LENGTH) return false;
+  if (value === "." || value === "..") return false;
+  if (value.includes("/") || value.includes("\\")) return false;
+  if (value.includes("\0")) return false;
+  if (value.includes(":")) return false;
+  return true;
+}
+function isSafeSessionId(value) {
+  if (value.length === 0 || value.length > MAX_PATH_SEGMENT_LENGTH) return false;
+  if (value.includes("\\") || value.includes("\0") || value.includes(":")) return false;
+  const parts = value.split("/");
+  if (parts.length > 2) return false;
+  return parts.every((p) => p.length > 0 && p !== "." && p !== "..");
 }
 function displayHost(host) {
   return host === "0.0.0.0" ? "127.0.0.1" : host;
@@ -576,7 +826,7 @@ function displayHost(host) {
 var RequestBodyTooLargeError = class extends Error {
 };
 function readRequestBody(req, maxBytes = 1e6) {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const chunks = [];
     let size = 0;
     let settled = false;
@@ -592,7 +842,7 @@ function readRequestBody(req, maxBytes = 1e6) {
       chunks.push(chunk);
     });
     req.on("end", () => {
-      if (!settled) resolve(Buffer.concat(chunks).toString("utf8"));
+      if (!settled) resolve2(Buffer.concat(chunks).toString("utf8"));
     });
     req.on("error", (error) => {
       if (!settled) reject(error);
@@ -620,7 +870,7 @@ function buildClientWsUrl(host, port, token) {
   return url.toString();
 }
 function hqRuntimeMarkerPath(dataDir) {
-  return path2.join(dataDir, "runtime.json");
+  return path3.join(dataDir, "runtime.json");
 }
 function lanIPv4Addresses() {
   const out = [];
@@ -667,20 +917,6 @@ function recordTimeseriesSignal(persistence, event) {
   } catch {
   }
 }
-function sanitizeApiError(err) {
-  const message = err instanceof Error ? err.message : String(err);
-  const lower = message.toLowerCase();
-  if (lower.includes("enoent") || lower.includes("no such file")) {
-    return "resource not found";
-  }
-  if (lower.includes("eacces") || lower.includes("permission")) {
-    return "permission denied";
-  }
-  if (lower.includes("json") && (lower.includes("parse") || lower.includes("unexpected"))) {
-    return "malformed data";
-  }
-  return "internal error";
-}
 
 // src/hq-server/snapshot.ts
 var HQ_SNAPSHOT_BROADCAST_DEBOUNCE_MS = 100;
@@ -719,6 +955,9 @@ function reapStaleClientState(clients, nowMs = Date.now()) {
     for (const [sessionId, tracked] of client.mcpSnapshots) {
       if (nowMs - tracked.receivedAt > HQ_STALE_SNAPSHOT_MS) client.mcpSnapshots.delete(sessionId);
     }
+    if (client.governanceSnapshot !== void 0 && nowMs - client.governanceSnapshot.receivedAt > HQ_STALE_SNAPSHOT_MS) {
+      delete client.governanceSnapshot;
+    }
   }
 }
 function buildSnapshot(clients, options) {
@@ -765,6 +1004,10 @@ function buildSnapshot(clients, options) {
     } else if (machineId && !project.machineIds.includes(machineId)) {
       project.machineIds = [...project.machineIds, machineId];
     }
+    const governance = client.governanceSnapshot?.payload;
+    if (governance !== void 0 && (project.governance === void 0 || Date.parse(governance.observedAt) >= Date.parse(project.governance.observedAt))) {
+      project.governance = governance;
+    }
     for (const tracked of client.sessions.values()) {
       const cutoff = Date.now() - 5 * 6e4;
       const agents = tracked.payload.agents.filter((agent) => {
@@ -1087,7 +1330,9 @@ function broadcastCommandStatus(command, browsers) {
 }
 
 // src/hq-server/trust-boundary.ts
-import { isTrustDecisionAllowed } from "@wrongstack/core/security";
+import {
+  isTrustDecisionAllowed
+} from "@wrongstack/core/security";
 async function authorizeHqCommand(input) {
   const { boundary, command, commandId, enqueuedBy, authMethod, target } = input;
   const subject = command.type === "run-command" ? {
@@ -1102,11 +1347,29 @@ async function authorizeHqCommand(input) {
   const request = {
     version: 1,
     requestId: commandId,
-    // This request is initiated by the authenticated HQ operator. Browser and
-    // target-client capability checks have already passed before this adapter
-    // is called, so classifying it as an unauthenticated remote client would
-    // make the compatibility policy deny every legitimate run-command.
-    actor: { kind: "user", id: enqueuedBy },
+    // WS-050: this was hardcoded to `kind: 'user'`, which made the
+    // compatibility policy's ONLY deny rule — `remote-client` + `critical` —
+    // unreachable from HQ. A boundary whose single rule can never fire is not
+    // defence in depth, it is decoration.
+    //
+    // The provenance is derived from how the caller authenticated, because
+    // that is the honest signal available here:
+    //
+    //   session cookie → `user`. The dashboard's primary flow is a bootstrap
+    //     code exchanged for an HttpOnly cookie, so this is a human at the
+    //     browser. NOTE: bootstrap sessions DO carry a `tokenId`, so a
+    //     "cookie without tokenId" test would have misclassified every normal
+    //     dashboard user as remote and denied them run-command. Checked before
+    //     writing this, not assumed.
+    //   raw bearer token → `remote-client`. The legacy `?token=` / manual-entry
+    //     path and any script calling the HTTP API directly. A credential that
+    //     can be copied into a script is not a person at a console.
+    //
+    // Consequence, deliberate: a bearer-token caller can no longer trigger
+    // `run-command` (the only `critical` capability here). `enqueue` is `high`
+    // and unaffected. The migration for automation that needs execute is the
+    // bootstrap exchange, which is the same thing the dashboard does.
+    actor: { kind: authMethod === "session" ? "user" : "remote-client", id: enqueuedBy },
     surface: "hq",
     capability: command.type === "run-command" ? "hq.control.execute" : "hq.control.enqueue",
     subject,
@@ -1137,18 +1400,29 @@ import { randomUUID } from "node:crypto";
 import {
   DEFAULT_HQ_REDACTION_POLICY as DEFAULT_HQ_REDACTION_POLICY2,
   hashHqPassword,
-  isLoopbackHost,
+  hqTokenKey as hqTokenKey2,
+  isLoopbackHost as isLoopbackHost2,
+  isTokenExpired as isTokenExpired4,
   mintHqCookieSecret,
   mutateHqAuthFile,
   verifyHqPassword
 } from "@wrongstack/core/hq";
+import {
+  buildOtpAuthUri,
+  generateRecoveryCodes,
+  generateTotpSecret,
+  hashRecoveryCode,
+  verifyRecoveryCode,
+  verifyTotp
+} from "@wrongstack/core/security";
+import { readHqAuthAuditTail } from "@wrongstack/core/hq";
 function isLoopbackRequest(req) {
   const address = req.socket.remoteAddress?.replace(/^::ffff:/, "");
-  return address !== void 0 && isLoopbackHost(address);
+  return address !== void 0 && isLoopbackHost2(address);
 }
 async function handleApiAuthStatus(req, res, url, mutableAuth, sessions, requireBrowserAuth, trustedPublicOrigins, secureCookies) {
   const auth = authenticateBrowserRequest(req, url, mutableAuth, sessions);
-  const openMode = mutableAuth.browserTokens.size === 0 && mutableAuth.passwordHash === void 0;
+  const openMode = mutableAuth.browserTokens.size === 0 && mutableAuth.passwordHash === void 0 && mutableAuth.requireAuthFloor !== true;
   const localOpenMode = openMode && !requireBrowserAuth && isLoopbackRequest(req);
   const publicOrigin = trustedPublicOrigins.values().next().value;
   res.writeHead(200, { "Content-Type": "application/json" });
@@ -1156,6 +1430,8 @@ async function handleApiAuthStatus(req, res, url, mutableAuth, sessions, require
     JSON.stringify({
       tokenMode: mutableAuth.browserTokens.size > 0,
       passwordMode: mutableAuth.passwordHash !== void 0,
+      totpEnabled: mutableAuth.totpSecret !== void 0,
+      recoveryCodesRemaining: mutableAuth.totpRecoveryCodes?.length ?? 0,
       publicRelay: requireBrowserAuth === true || publicOrigin !== void 0,
       ...publicOrigin !== void 0 ? { publicOrigin } : {},
       secureCookies: secureCookies === true,
@@ -1178,9 +1454,8 @@ async function handleApiLogin(req, res, mutableAuth, sessions, loginAttempts, se
     return;
   }
   const clientIp = req.socket.remoteAddress ?? "unknown";
-  const existing = loginAttempts.get(clientIp);
-  if (existing && existing.blockedUntil > Date.now()) {
-    const retryAfter = Math.ceil((existing.blockedUntil - Date.now()) / 1e3);
+  const { blocked, retryAfter } = loginAttempts.checkBlocked(clientIp, "");
+  if (blocked) {
     res.writeHead(429, {
       "Content-Type": "application/json",
       "Retry-After": String(retryAfter)
@@ -1204,30 +1479,36 @@ async function handleApiLogin(req, res, mutableAuth, sessions, loginAttempts, se
   }
   if (typeof body.password !== "string" || body.password.length === 0) {
     res.writeHead(400, { "Content-Type": "application/json" });
-    res.end(
-      JSON.stringify({ error: { code: "BAD_REQUEST", message: "password is required" } })
-    );
+    res.end(JSON.stringify({ error: { code: "BAD_REQUEST", message: "password is required" } }));
     return;
   }
   const ok = await verifyHqPassword(body.password, mutableAuth.passwordHash);
   if (!ok || !mutableAuth.cookieSecret) {
-    const prev = loginAttempts.get(clientIp);
-    const count = (prev?.count ?? 0) + 1;
-    const backoffMs = Math.min(2 ** count * 1e3, 16e3);
-    loginAttempts.set(clientIp, {
-      count,
-      blockedUntil: Date.now() + backoffMs,
-      lastAttempt: Date.now()
-    });
+    loginAttempts.recordFailure(clientIp, body.password);
     res.writeHead(401, { "Content-Type": "application/json" });
-    res.end(
-      JSON.stringify({ error: { code: "INVALID_PASSWORD", message: "Invalid password." } })
+    res.end(JSON.stringify({ error: { code: "INVALID_PASSWORD", message: "Invalid password." } }));
+    return;
+  }
+  if (mutableAuth.totpSecret) {
+    const pendingSessionId = randomUUID();
+    sessions.set(pendingSessionId, {
+      createdAt: Date.now(),
+      kind: "password",
+      pending2fa: true,
+      lastSeenAt: Date.now()
+    });
+    setHqSessionCookie(
+      res,
+      serializeHqSessionCookie(pendingSessionId, mutableAuth.cookieSecret),
+      secureCookies
     );
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ loggedIn: false, totpRequired: true }));
     return;
   }
-  loginAttempts.delete(clientIp);
+  loginAttempts.clearOnSuccess(clientIp, body.password);
   const sessionId = randomUUID();
-  sessions.set(sessionId, { createdAt: Date.now(), kind: "password" });
+  sessions.set(sessionId, { createdAt: Date.now(), kind: "password", lastSeenAt: Date.now() });
   setHqSessionCookie(
     res,
     serializeHqSessionCookie(sessionId, mutableAuth.cookieSecret),
@@ -1245,7 +1526,7 @@ async function handleApiLogout(req, res, mutableAuth, sessions, secureCookies) {
   );
   if (isCookieAuth(auth)) {
     const cookies = parseCookieHeader(req.headers.cookie);
-    const raw = cookies[HQ_SESSION_COOKIE];
+    const raw = cookies[HQ_SESSION_COOKIE] ?? cookies["__Host-hq.session"];
     if (raw) {
       const sessionId = parseHqSessionCookie(raw, mutableAuth.cookieSecret ?? "");
       if (sessionId) sessions.delete(sessionId);
@@ -1275,23 +1556,34 @@ async function handleApiPassword(req, res, mutableAuth, sessions, dataDir, secur
     );
     return;
   }
+  if (localOpenBootstrap) {
+    console.warn(
+      JSON.stringify({
+        level: "warn",
+        event: "hq.auth.password_claimed_unauthenticated",
+        message: "An unauthenticated loopback request set the HQ password on an open instance. If this was not you, stop HQ and remove passwordHash from auth.json.",
+        remoteAddress: req.socket.remoteAddress ?? "unknown",
+        dataDir,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      })
+    );
+  }
   let body = {};
   try {
     body = JSON.parse(await readRequestBody(req));
   } catch {
     res.writeHead(400, { "Content-Type": "application/json" });
-    res.end(
-      JSON.stringify({ error: { code: "BAD_REQUEST", message: "Invalid JSON body." } })
-    );
+    res.end(JSON.stringify({ error: { code: "BAD_REQUEST", message: "Invalid JSON body." } }));
     return;
   }
-  if (isCookieAuth(auth) && mutableAuth.passwordHash !== void 0) {
+  const hasAdminCapability = auth !== void 0 && "capabilities" in auth && auth.capabilities !== void 0 && auth.capabilities.includes("auth.admin");
+  if (!localOpenBootstrap && mutableAuth.passwordHash !== void 0 && !hasAdminCapability) {
     const currentPassword = typeof body.currentPassword === "string" ? body.currentPassword : "";
     if (!currentPassword || !await verifyHqPassword(currentPassword, mutableAuth.passwordHash)) {
       res.writeHead(403, { "Content-Type": "application/json" });
       res.end(
         JSON.stringify({
-          error: { code: "INVALID_CURRENT_PASSWORD", message: "Current password is invalid." }
+          error: { code: "INVALID_CURRENT_PASSWORD", message: "Current password is required to change or remove it." }
         })
       );
       return;
@@ -1314,6 +1606,9 @@ async function handleApiPassword(req, res, mutableAuth, sessions, dataDir, secur
       const updated = { ...current };
       delete updated.passwordHash;
       delete updated.cookieSecret;
+      delete updated.totpSecret;
+      delete updated.totpPendingSecret;
+      delete updated.totpRecoveryCodes;
       return updated;
     });
     applyAuthFile(mutableAuth, next2);
@@ -1334,7 +1629,10 @@ async function handleApiPassword(req, res, mutableAuth, sessions, dataDir, secur
     res.writeHead(400, { "Content-Type": "application/json" });
     res.end(
       JSON.stringify({
-        error: { code: "INVALID_PASSWORD", message: "New password must be between 8 and 1024 characters." }
+        error: {
+          code: "INVALID_PASSWORD",
+          message: "New password must be between 8 and 1024 characters."
+        }
       })
     );
     return;
@@ -1350,12 +1648,8 @@ async function handleApiPassword(req, res, mutableAuth, sessions, dataDir, secur
   sessions.clear();
   if (isCookieAuth(auth) || localOpenBootstrap) {
     const sessionId = randomUUID();
-    sessions.set(sessionId, { createdAt: Date.now(), kind: "password" });
-    setHqSessionCookie(
-      res,
-      serializeHqSessionCookie(sessionId, cookieSecret),
-      secureCookies
-    );
+    sessions.set(sessionId, { createdAt: Date.now(), kind: "password", lastSeenAt: Date.now() });
+    setHqSessionCookie(res, serializeHqSessionCookie(sessionId, cookieSecret), secureCookies);
   }
   res.writeHead(200, { "Content-Type": "application/json" });
   res.end(
@@ -1372,20 +1666,28 @@ function applyAuthFile(mutableAuth, next) {
     ...next.redactionPolicy ?? {}
   };
   mutableAuth.operatorPolicyOverride = next.redactionPolicy;
-  mutableAuth.browserTokens = new Set((next.browserTokens ?? []).map((t) => t.token));
-  mutableAuth.clientTokens = new Set((next.clientTokens ?? []).map((t) => t.token));
+  const liveBrowserTokens = (next.browserTokens ?? []).filter((t) => !isTokenExpired4(t));
+  mutableAuth.browserTokens = new Set(liveBrowserTokens.map(hqTokenKey2));
+  mutableAuth.clientTokens = new Set((next.clientTokens ?? []).map(hqTokenKey2));
   mutableAuth.browserTokenObjs = new Map(
-    (next.browserTokens ?? []).map((t) => [
-      t.token,
-      { id: t.id, ...t.capabilities !== void 0 ? { capabilities: t.capabilities } : {} }
+    liveBrowserTokens.map((t) => [
+      hqTokenKey2(t),
+      {
+        id: t.id,
+        ...t.capabilities !== void 0 ? { capabilities: t.capabilities } : {},
+        ...t.expiresAt !== void 0 ? { expiresAt: t.expiresAt } : {}
+      }
     ])
   );
   mutableAuth.clientTokenObjs = new Map(
-    (next.clientTokens ?? []).map((token) => [token.token, token])
+    (next.clientTokens ?? []).map((token) => [hqTokenKey2(token), token])
   );
   mutableAuth.passwordHash = next.passwordHash;
   mutableAuth.cookieSecret = next.cookieSecret;
   mutableAuth.alertRules = next.alertRules;
+  mutableAuth.totpSecret = next.totpSecret;
+  mutableAuth.totpPendingSecret = next.totpPendingSecret;
+  mutableAuth.totpRecoveryCodes = next.totpRecoveryCodes;
 }
 async function handleApiBootstrap(req, res, mutableAuth, sessions, secureCookies, bootstrapStore) {
   if (!mutableAuth.cookieSecret) {
@@ -1409,9 +1711,7 @@ async function handleApiBootstrap(req, res, mutableAuth, sessions, secureCookies
   }
   if (typeof body.code !== "string" || body.code.length === 0) {
     res.writeHead(400, { "Content-Type": "application/json" });
-    res.end(
-      JSON.stringify({ error: { code: "BAD_REQUEST", message: "code is required" } })
-    );
+    res.end(JSON.stringify({ error: { code: "BAD_REQUEST", message: "code is required" } }));
     return;
   }
   const entry = bootstrapStore.consume(body.code);
@@ -1445,6 +1745,7 @@ async function handleApiBootstrap(req, res, mutableAuth, sessions, secureCookies
   const sessionId = randomUUID();
   sessions.set(sessionId, {
     createdAt: Date.now(),
+    lastSeenAt: Date.now(),
     kind: "token",
     tokenId: entry.tokenId,
     ...entry.capabilities !== void 0 ? { capabilities: entry.capabilities } : {}
@@ -1457,12 +1758,406 @@ async function handleApiBootstrap(req, res, mutableAuth, sessions, secureCookies
   res.writeHead(200, { "Content-Type": "application/json" });
   res.end(JSON.stringify({ loggedIn: true }));
 }
+async function handleApiTokenUpgrade(req, res, url, mutableAuth, sessions, secureCookies) {
+  if (!mutableAuth.cookieSecret) {
+    res.writeHead(503, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({
+        error: {
+          code: "UPGRADE_UNAVAILABLE",
+          message: "Cookie signing is not configured on this HQ server."
+        }
+      })
+    );
+    return;
+  }
+  const auth = authenticateBrowserRequest(req, url, mutableAuth, sessions);
+  if (isCookieAuth(auth)) {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ loggedIn: true, upgraded: false }));
+    return;
+  }
+  if (!isTokenAuth(auth)) {
+    res.writeHead(401, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({
+        error: { code: "UNAUTHORIZED", message: "A valid browser token is required." }
+      })
+    );
+    return;
+  }
+  const tokenLive = [...mutableAuth.browserTokenObjs.values()].some((obj) => obj.id === auth.id);
+  if (!tokenLive) {
+    res.writeHead(409, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({
+        error: {
+          code: "TOKEN_NOT_UPGRADEABLE",
+          message: "This token has no server-side record to bind a session to."
+        }
+      })
+    );
+    return;
+  }
+  const sessionId = randomUUID();
+  sessions.set(sessionId, {
+    createdAt: Date.now(),
+    lastSeenAt: Date.now(),
+    kind: "token",
+    tokenId: auth.id,
+    ...auth.capabilities !== void 0 ? { capabilities: auth.capabilities } : {}
+  });
+  setHqSessionCookie(
+    res,
+    serializeHqSessionCookie(sessionId, mutableAuth.cookieSecret),
+    secureCookies
+  );
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ loggedIn: true, upgraded: true }));
+}
+var PENDING_2FA_TTL_MS = 5 * 6e4;
+var recoveryCodeLock = Promise.resolve();
+var MAX_2FA_VERIFY_FAILURES = 5;
+function recordVerifyFailure(loginAttempts, clientIp) {
+  const prev = loginAttempts.get(clientIp);
+  const count = (prev?.count ?? 0) + 1;
+  loginAttempts.recordFailure(clientIp, "");
+  return count;
+}
+async function handleApiLoginVerify(req, res, _url, mutableAuth, sessions, loginAttempts, dataDir, secureCookies) {
+  if (!mutableAuth.cookieSecret) {
+    res.writeHead(503, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: { code: "NO_COOKIE_SECRET" } }));
+    return;
+  }
+  const clientIp = req.socket.remoteAddress ?? "unknown";
+  const { blocked, retryAfter } = loginAttempts.checkBlocked(clientIp, "");
+  if (blocked) {
+    res.writeHead(429, { "Content-Type": "application/json", "Retry-After": String(retryAfter) });
+    res.end(JSON.stringify({ error: { code: "RATE_LIMITED", message: "Too many attempts. Try again later." } }));
+    return;
+  }
+  const cookies = parseCookieHeader(req.headers.cookie);
+  const raw = cookies[HQ_SESSION_COOKIE] ?? cookies["__Host-hq.session"];
+  const sessionId = raw ? parseHqSessionCookie(raw, mutableAuth.cookieSecret) : void 0;
+  if (!sessionId) {
+    res.writeHead(401, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: { code: "NO_PENDING_SESSION", message: "No pending 2FA session." } }));
+    return;
+  }
+  const session = sessions.get(sessionId);
+  if (!session || !session.pending2fa) {
+    res.writeHead(401, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: { code: "NO_PENDING_SESSION", message: "Session is not pending 2FA." } }));
+    return;
+  }
+  if (Date.now() - session.createdAt > PENDING_2FA_TTL_MS) {
+    sessions.delete(sessionId);
+    res.writeHead(401, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: { code: "TOTP_EXPIRED", message: "2FA session expired. Please log in again." } }));
+    return;
+  }
+  let body;
+  try {
+    body = JSON.parse(await readRequestBody(req));
+  } catch {
+    res.writeHead(400, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: { code: "BAD_REQUEST", message: "Invalid JSON body." } }));
+    return;
+  }
+  if (typeof body.code === "string" && body.code.length > 0) {
+    if (!mutableAuth.totpSecret) {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: { code: "TOTP_NOT_ENABLED", message: "2FA is not configured." } }));
+      return;
+    }
+    if (!verifyTotp(body.code, mutableAuth.totpSecret)) {
+      if (recordVerifyFailure(loginAttempts, clientIp) >= MAX_2FA_VERIFY_FAILURES) {
+        sessions.delete(sessionId);
+      }
+      res.writeHead(401, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: { code: "INVALID_TOTP", message: "Invalid authenticator code." } }));
+      return;
+    }
+    loginAttempts.clearOnSuccess(clientIp, "");
+    sessions.delete(sessionId);
+    const fullSessionId = randomUUID();
+    sessions.set(fullSessionId, { createdAt: Date.now(), kind: "password", lastSeenAt: Date.now() });
+    setHqSessionCookie(
+      res,
+      serializeHqSessionCookie(fullSessionId, mutableAuth.cookieSecret),
+      secureCookies
+    );
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ loggedIn: true }));
+    return;
+  }
+  if (typeof body.recoveryCode === "string" && body.recoveryCode.length > 0) {
+    const usedHash = hashRecoveryCode(body.recoveryCode);
+    const storedHashes = mutableAuth.totpRecoveryCodes ?? [];
+    if (storedHashes.length === 0) {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: { code: "NO_RECOVERY_CODES", message: "No recovery codes available." } }));
+      return;
+    }
+    if (!verifyRecoveryCode(body.recoveryCode, storedHashes)) {
+      if (recordVerifyFailure(loginAttempts, clientIp) >= MAX_2FA_VERIFY_FAILURES) {
+        sessions.delete(sessionId);
+      }
+      res.writeHead(401, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: { code: "INVALID_RECOVERY_CODE", message: "Invalid recovery code." } }));
+      return;
+    }
+    let consumed = false;
+    let remainingCount = 0;
+    await recoveryCodeLock;
+    let releaseLock = () => {
+    };
+    recoveryCodeLock = new Promise((resolve2) => {
+      releaseLock = resolve2;
+    });
+    try {
+      const next = await mutateHqAuthFile(dataDir, (current) => {
+        const diskHashes = current.totpRecoveryCodes ?? [];
+        const idx = diskHashes.indexOf(usedHash);
+        if (idx === -1) {
+          consumed = false;
+          remainingCount = diskHashes.length;
+          return current;
+        }
+        consumed = true;
+        const remaining = diskHashes.filter((_, i) => i !== idx);
+        remainingCount = remaining.length;
+        return { ...current, totpRecoveryCodes: remaining };
+      });
+      if (!consumed) {
+        res.writeHead(409, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: { code: "RECOVERY_CODE_ALREADY_USED", message: "This recovery code has already been used." } }));
+        return;
+      }
+      applyAuthFile(mutableAuth, next);
+    } finally {
+      releaseLock();
+    }
+    loginAttempts.clearOnSuccess(clientIp, "");
+    sessions.delete(sessionId);
+    const fullSessionId = randomUUID();
+    sessions.set(fullSessionId, { createdAt: Date.now(), kind: "password", lastSeenAt: Date.now() });
+    setHqSessionCookie(
+      res,
+      serializeHqSessionCookie(fullSessionId, mutableAuth.cookieSecret),
+      secureCookies
+    );
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ loggedIn: true, recoveryCodesRemaining: remainingCount }));
+    return;
+  }
+  res.writeHead(400, { "Content-Type": "application/json" });
+  res.end(
+    JSON.stringify({ error: { code: "BAD_REQUEST", message: "Provide a `code` or `recoveryCode`." } })
+  );
+}
+async function handleApiTotpSetup(req, res, mutableAuth, sessions, dataDir) {
+  const auth = authenticateBrowserRequest(
+    req,
+    new URL(req.url ?? "/", "http://localhost"),
+    mutableAuth,
+    sessions
+  );
+  if (!auth) {
+    res.writeHead(401, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: { code: "UNAUTHORIZED", message: "Authentication required." } }));
+    return;
+  }
+  if (mutableAuth.totpSecret) {
+    res.writeHead(409, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({ error: { code: "TOTP_ALREADY_ENABLED", message: "2FA is already active. Disable it first to re-enroll." } })
+    );
+    return;
+  }
+  const secret = generateTotpSecret();
+  const uri = buildOtpAuthUri(secret, "HQ");
+  const next = await mutateHqAuthFile(dataDir, (current) => ({
+    ...current,
+    totpPendingSecret: secret
+  }));
+  applyAuthFile(mutableAuth, next);
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ secret, uri, enabled: false }));
+}
+async function handleApiTotpEnable(req, res, mutableAuth, sessions, dataDir) {
+  const auth = authenticateBrowserRequest(
+    req,
+    new URL(req.url ?? "/", "http://localhost"),
+    mutableAuth,
+    sessions
+  );
+  if (!auth) {
+    res.writeHead(401, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: { code: "UNAUTHORIZED", message: "Authentication required." } }));
+    return;
+  }
+  if (mutableAuth.totpSecret) {
+    res.writeHead(409, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({ error: { code: "TOTP_ALREADY_ENABLED", message: "2FA is already active." } })
+    );
+    return;
+  }
+  const pendingSecret = mutableAuth.totpPendingSecret;
+  if (!pendingSecret) {
+    res.writeHead(400, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({ error: { code: "TOTP_NOT_SETUP", message: "Call /api/auth/totp/setup first." } })
+    );
+    return;
+  }
+  let body;
+  try {
+    body = JSON.parse(await readRequestBody(req));
+  } catch {
+    res.writeHead(400, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: { code: "BAD_REQUEST", message: "Invalid JSON body." } }));
+    return;
+  }
+  if (typeof body.code !== "string" || body.code.length === 0) {
+    res.writeHead(400, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: { code: "BAD_REQUEST", message: "code is required." } }));
+    return;
+  }
+  if (!verifyTotp(body.code, pendingSecret)) {
+    res.writeHead(401, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: { code: "INVALID_TOTP", message: "Invalid authenticator code." } }));
+    return;
+  }
+  const recoveryCodes = generateRecoveryCodes();
+  const recoveryHashes = recoveryCodes.map(hashRecoveryCode);
+  const next = await mutateHqAuthFile(dataDir, (current) => {
+    const updated = { ...current };
+    updated.totpSecret = pendingSecret;
+    delete updated.totpPendingSecret;
+    updated.totpRecoveryCodes = recoveryHashes;
+    return updated;
+  });
+  applyAuthFile(mutableAuth, next);
+  sessions.clear();
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ enabled: true, recoveryCodes }));
+}
+async function handleApiTotpDisable(req, res, mutableAuth, sessions, loginAttempts, dataDir) {
+  const auth = authenticateBrowserRequest(
+    req,
+    new URL(req.url ?? "/", "http://localhost"),
+    mutableAuth,
+    sessions
+  );
+  if (!auth) {
+    res.writeHead(401, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: { code: "UNAUTHORIZED", message: "Authentication required." } }));
+    return;
+  }
+  const clientIp = req.socket.remoteAddress ?? "unknown";
+  const { blocked, retryAfter } = loginAttempts.checkBlocked(clientIp, "");
+  if (blocked) {
+    res.writeHead(429, { "Content-Type": "application/json", "Retry-After": String(retryAfter) });
+    res.end(JSON.stringify({ error: { code: "RATE_LIMITED", message: "Too many attempts. Try again later." } }));
+    return;
+  }
+  let body;
+  try {
+    body = JSON.parse(await readRequestBody(req));
+  } catch {
+    res.writeHead(400, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: { code: "BAD_REQUEST", message: "Invalid JSON body." } }));
+    return;
+  }
+  let confirmed = false;
+  if (typeof body.password === "string" && body.password.length > 0 && mutableAuth.passwordHash) {
+    confirmed = await verifyHqPassword(body.password, mutableAuth.passwordHash);
+  }
+  if (!confirmed && typeof body.code === "string" && mutableAuth.totpSecret) {
+    confirmed = verifyTotp(body.code, mutableAuth.totpSecret);
+  }
+  if (!confirmed) {
+    recordVerifyFailure(loginAttempts, clientIp);
+    res.writeHead(403, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({ error: { code: "CONFIRMATION_REQUIRED", message: "Provide the current password or a TOTP code." } })
+    );
+    return;
+  }
+  loginAttempts.delete(clientIp);
+  const next = await mutateHqAuthFile(dataDir, (current) => {
+    const updated = { ...current };
+    delete updated.totpSecret;
+    delete updated.totpPendingSecret;
+    delete updated.totpRecoveryCodes;
+    return updated;
+  });
+  applyAuthFile(mutableAuth, next);
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ enabled: false }));
+}
+function handleApiAuthSessions(_req, res, mutableAuth, sessions) {
+  const now = Date.now();
+  const list = [];
+  for (const [id, session] of sessions) {
+    if (session.pending2fa) continue;
+    list.push({
+      // Truncated for display only — the client sends the full ID to revoke.
+      id,
+      shortId: id.slice(0, 8),
+      kind: session.kind,
+      createdAt: new Date(session.createdAt).toISOString(),
+      lastSeenAt: new Date(session.lastSeenAt).toISOString(),
+      ageMinutes: Math.round((now - session.createdAt) / 6e4),
+      idleMinutes: Math.round((now - session.lastSeenAt) / 6e4)
+    });
+  }
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(
+    JSON.stringify({
+      sessions: list,
+      idleTimeoutMinutes: Math.round(
+        (HQ_SESSION_IDLE_TIMEOUT_MS ?? 30 * 6e4) / 6e4
+      ),
+      maxAgeDays: Math.round(HQ_SESSION_MAX_AGE_MS / (24 * 60 * 6e4)),
+      passwordMode: mutableAuth.passwordHash !== void 0
+    })
+  );
+}
+async function handleApiAuthSessionsRevoke(_req, res, url, sessions) {
+  const pathParts = url.pathname.split("/").filter(Boolean);
+  const targetId = pathParts[3];
+  if (targetId) {
+    const session = sessions.get(targetId);
+    if (!session) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: { code: "NOT_FOUND", message: "Session not found." } }));
+      return;
+    }
+    sessions.delete(targetId);
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ revoked: 1 }));
+    return;
+  }
+  const count = sessions.size;
+  sessions.clear();
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ revoked: count }));
+}
+function handleApiAuthAudit(_req, res, dataDir) {
+  const entries = readHqAuthAuditTail(dataDir, 50);
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ entries }));
+}
 
 // src/hq-server/routes/system-handlers.ts
 async function handleApiSystemUpdate(res) {
   const [{ checkForUpdate }, { detectUpdatePackageName }] = await Promise.all([
     import("./update-check-UMYTOH7Z.js"),
-    import("./update-YC4TYW2Y.js")
+    import("./update-MV6TUACD.js")
   ]);
   const packageName = detectUpdatePackageName();
   const info = await checkForUpdate({ packageName });
@@ -1546,14 +2241,14 @@ async function handleApiAlerts(req, res, alertEngine) {
 }
 
 // src/hq-server/routes/session-handlers.ts
-import * as path3 from "node:path";
+import * as path4 from "node:path";
 import {
   buildTranscriptFromEvents,
   resolveHqDataDir as resolveHqDataDir3
 } from "@wrongstack/core/hq";
 async function handleApiSessions(res) {
   const { SessionRegistry } = await import("@wrongstack/core/storage");
-  const globalRoot = path3.dirname(resolveHqDataDir3());
+  const globalRoot = path4.dirname(resolveHqDataDir3());
   try {
     const registry = new SessionRegistry(globalRoot);
     const sessions = await registry.list();
@@ -1592,13 +2287,13 @@ async function handleApiSessionEvents(req, res, match, transcripts) {
   const full = url.searchParams.get("full") === "1";
   const rawLimit = Number.parseInt(url.searchParams.get("limit") ?? "200", 10);
   const limit = Math.min(5e3, Math.max(1, Number.isFinite(rawLimit) ? rawLimit : 200));
-  const sessionId = decodePathSegment(match[1]);
+  const sessionId = decodeSessionId(match[1]);
   if (sessionId === null) {
     res.writeHead(400, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ error: "invalid sessionId encoding" }));
     return;
   }
-  const globalRoot = path3.dirname(resolveHqDataDir3());
+  const globalRoot = path4.dirname(resolveHqDataDir3());
   try {
     const registry = new SessionRegistry(globalRoot);
     const entry = await registry.get(sessionId).catch(() => null);
@@ -1660,7 +2355,7 @@ async function handleApiSessionEvents(req, res, match, transcripts) {
 }
 async function handleApiSessionAgentMessages(req, res, match, agentMessages) {
   const url = new URL(req.url ?? "/", "http://localhost");
-  const sid = decodePathSegment(match[1]);
+  const sid = decodeSessionId(match[1]);
   const aid = decodePathSegment(match[2]);
   if (sid === null || aid === null) {
     res.writeHead(400, { "Content-Type": "application/json" });
@@ -1706,7 +2401,7 @@ function resolveHqProjectRoot(globalRoot, ids) {
         if (entry?.projectRoot) return entry.projectRoot;
       }
       if (typeof ids.projectId === "string") {
-        const { createHash } = await import("node:crypto");
+        const { createHash: createHash2 } = await import("node:crypto");
         const all = await registry.list().catch(() => []);
         const projectIds = /* @__PURE__ */ new Map();
         const projectIdForRoot = (projectRoot) => {
@@ -1717,7 +2412,7 @@ function resolveHqProjectRoot(globalRoot, ids) {
           return derived;
         };
         const match = all.find(
-          (e) => e.projectSlug === ids.projectId || projectIdForRoot(e.projectRoot) === ids.projectId || createHash("sha256").update(e.projectRoot).digest("hex").slice(0, 12) === ids.projectId
+          (e) => e.projectSlug === ids.projectId || projectIdForRoot(e.projectRoot) === ids.projectId || createHash2("sha256").update(e.projectRoot).digest("hex").slice(0, 12) === ids.projectId
         );
         if (match) return match.projectRoot;
       }
@@ -1734,6 +2429,7 @@ var hasTrustedBrowserOrigin2 = hasTrustedBrowserOrigin;
 var authenticateBrowserRequest2 = authenticateBrowserRequest;
 var isTokenAuth2 = isTokenAuth;
 var isCookieAuth2 = isCookieAuth;
+var hqAuthRequired2 = hqAuthRequired;
 var parseHqSessionCookie2 = parseHqSessionCookie;
 var parseCookieHeader2 = parseCookieHeader;
 var HQ_SESSION_COOKIE2 = HQ_SESSION_COOKIE;
@@ -1752,6 +2448,7 @@ function createHqRouter(deps) {
     host,
     listeningPort,
     trustedPublicOrigins,
+    allowFileOrigin,
     mutableAuth,
     sessions,
     loginAttempts,
@@ -1777,12 +2474,18 @@ function createHqRouter(deps) {
     try {
       const url = new URL(req.url ?? "/", `http://${host}:${listeningPort}`);
       setHqSecurityHeaders2(res);
-      if (!hasTrustedBrowserOrigin2(req, host, listeningPort, trustedPublicOrigins)) {
+      if (!hasTrustedBrowserOrigin2(
+        req,
+        host,
+        listeningPort,
+        trustedPublicOrigins,
+        allowFileOrigin
+      )) {
         res.writeHead(403, { "Content-Type": "application/json" });
         res.end(JSON.stringify({ error: "forbidden: untrusted request origin" }));
         return;
       }
-      if (url.pathname.startsWith("/api/") && url.pathname !== "/api/auth/status" && url.pathname !== "/api/login" && url.pathname !== "/api/auth/bootstrap" && (requireBrowserAuth || mutableAuth.browserTokens.size > 0 || mutableAuth.passwordHash)) {
+      if (url.pathname.startsWith("/api/") && url.pathname !== "/api/auth/status" && url.pathname !== "/api/login" && url.pathname !== "/api/login/verify" && url.pathname !== "/api/auth/bootstrap" && hqAuthRequired2(mutableAuth, requireBrowserAuth)) {
         const auth = authenticateBrowserRequest2(req, url, mutableAuth, sessions);
         if (!auth) {
           const tokenOnly = mutableAuth.browserTokens.size > 0 && !mutableAuth.passwordHash;
@@ -1813,6 +2516,18 @@ function createHqRouter(deps) {
         await handleApiAuthStatus(req, res, url, mutableAuth, sessions, requireBrowserAuth, trustedPublicOrigins, secureCookies);
         return;
       }
+      if (url.pathname === "/api/auth/audit" && req.method === "GET") {
+        handleApiAuthAudit(req, res, dataDir);
+        return;
+      }
+      if (url.pathname === "/api/auth/sessions" && req.method === "GET") {
+        handleApiAuthSessions(req, res, mutableAuth, sessions);
+        return;
+      }
+      if (url.pathname.startsWith("/api/auth/sessions") && req.method === "DELETE") {
+        await handleApiAuthSessionsRevoke(req, res, url, sessions);
+        return;
+      }
       if (url.pathname === "/api/login" && req.method === "POST") {
         await handleApiLogin(req, res, mutableAuth, sessions, loginAttempts, secureCookies);
         return;
@@ -1833,10 +2548,30 @@ function createHqRouter(deps) {
         }
         return;
       }
+      if (url.pathname === "/api/auth/upgrade" && req.method === "POST") {
+        await handleApiTokenUpgrade(req, res, url, mutableAuth, sessions, secureCookies);
+        return;
+      }
       if (url.pathname === "/api/logout" && req.method === "POST") {
         await handleApiLogout(req, res, mutableAuth, sessions, secureCookies);
         return;
       }
+      if (url.pathname === "/api/login/verify" && req.method === "POST") {
+        await handleApiLoginVerify(req, res, url, mutableAuth, sessions, loginAttempts, dataDir, secureCookies);
+        return;
+      }
+      if (url.pathname === "/api/auth/totp/setup" && req.method === "POST") {
+        await handleApiTotpSetup(req, res, mutableAuth, sessions, dataDir);
+        return;
+      }
+      if (url.pathname === "/api/auth/totp/enable" && req.method === "POST") {
+        await handleApiTotpEnable(req, res, mutableAuth, sessions, dataDir);
+        return;
+      }
+      if (url.pathname === "/api/auth/totp/disable" && req.method === "POST") {
+        await handleApiTotpDisable(req, res, mutableAuth, sessions, loginAttempts, dataDir);
+        return;
+      }
       if (url.pathname === "/api/auth/password" && (req.method === "POST" || req.method === "DELETE")) {
         await handleApiPassword(req, res, mutableAuth, sessions, dataDir, secureCookies, requireBrowserAuth);
         return;
@@ -1972,7 +2707,7 @@ async function handleMailboxGateway(_req, res, match, authorizeMailboxGateway, g
     );
     return;
   }
-  const gatewayGlobalRoot = path4.dirname(dataDir);
+  const gatewayGlobalRoot = path5.dirname(dataDir);
   const preliminaryAccess = authorizeMailboxGateway(_req, `project:${projectId}`);
   if (!preliminaryAccess.allowed) {
     res.writeHead(preliminaryAccess.status ?? 401, {
@@ -2044,14 +2779,12 @@ async function handleApiTrendsCost(req, res, persistence) {
 }
 async function handleApiCommand(req, res, url, mutableAuth, sessions, clients, browsers, auditLog, trustBoundary) {
   const auth = authenticateBrowserRequest2(req, url, mutableAuth, sessions);
-  const inBrowserTokenMode = mutableAuth.browserTokens.size > 0;
-  const inPasswordMode = mutableAuth.passwordHash !== void 0;
-  if ((inBrowserTokenMode || inPasswordMode) && !auth) {
+  if (hqAuthRequired2(mutableAuth) && !auth) {
     res.writeHead(401, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ error: "unauthorized" }));
     return;
   }
-  const canEnqueue = isCookieAuth2(auth) ? auth.tokenId === void 0 || auth.capabilities === void 0 || auth.capabilities.includes("control.enqueue") : isTokenAuth2(auth) ? auth.capabilities === void 0 || auth.capabilities.includes("control.enqueue") : !inBrowserTokenMode;
+  const canEnqueue = callerCanEnqueue(auth, mutableAuth);
   if (!canEnqueue) {
     res.writeHead(403, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ error: "forbidden: token lacks control.enqueue capability" }));
@@ -2153,7 +2886,12 @@ async function handleApiMailboxSend(_req, res, mutableAuth, sessions, dataDir, g
     mutableAuth,
     sessions
   );
-  const canEnqueue = isCookieAuth2(auth) ? auth.tokenId === void 0 || auth.capabilities === void 0 || auth.capabilities.includes("control.enqueue") : isTokenAuth2(auth) ? auth.capabilities === void 0 || auth.capabilities.includes("control.enqueue") : mutableAuth.browserTokens.size === 0;
+  if (hqAuthRequired2(mutableAuth) && !auth) {
+    res.writeHead(401, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: { code: "UNAUTHORIZED", message: "unauthorized" } }));
+    return;
+  }
+  const canEnqueue = callerCanEnqueue(auth, mutableAuth);
   if (!canEnqueue) {
     res.writeHead(403, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ error: "forbidden: token lacks control.enqueue capability" }));
@@ -2181,7 +2919,7 @@ async function handleApiMailboxSend(_req, res, mutableAuth, sessions, dataDir, g
     res.end(JSON.stringify({ error: "audience must be all or leaders" }));
     return;
   }
-  const mbGlobalRoot = path4.dirname(dataDir);
+  const mbGlobalRoot = path5.dirname(dataDir);
   const projectRoot = await resolveHqProjectRoot(mbGlobalRoot, {
     sessionId: mbody.sessionId,
     projectId: mbody.projectId
@@ -2239,10 +2977,35 @@ async function handleApiMailboxSend(_req, res, mutableAuth, sessions, dataDir, g
     );
   } catch (err) {
     res.writeHead(500, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ error: "mailbox write failed", detail: String(err) }));
+    res.end(JSON.stringify({ error: "mailbox write failed", detail: sanitizeApiError2(err) }));
   }
 }
-async function handleMailboxAction(_req, res, match, _mutableAuth, _sessions, dataDir, getMailboxGateway) {
+function callerCanEnqueue(auth, mutableAuth) {
+  if (isCookieAuth2(auth)) {
+    return auth.tokenId === void 0 || auth.capabilities === void 0 || auth.capabilities.includes("control.enqueue");
+  }
+  if (isTokenAuth2(auth)) {
+    return auth.capabilities === void 0 || auth.capabilities.includes("control.enqueue");
+  }
+  return !hqAuthRequired2(mutableAuth);
+}
+async function handleMailboxAction(_req, res, match, mutableAuth, sessions, dataDir, getMailboxGateway) {
+  const auth = authenticateBrowserRequest2(
+    _req,
+    new URL(_req.url ?? "/", "http://localhost"),
+    mutableAuth,
+    sessions
+  );
+  if (hqAuthRequired2(mutableAuth) && !auth) {
+    res.writeHead(401, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "unauthorized" }));
+    return;
+  }
+  if (!callerCanEnqueue(auth, mutableAuth)) {
+    res.writeHead(403, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "forbidden: token lacks control.enqueue capability" }));
+    return;
+  }
   const MAILBOX_ACTIONS = [
     "mark-read",
     "acknowledge",
@@ -2269,7 +3032,9 @@ async function handleMailboxAction(_req, res, match, _mutableAuth, _sessions, da
     res.end(JSON.stringify({ error: "unrecognized action", action: abody.action }));
     return;
   }
-  if (typeof abody.readerId !== "string" || abody.readerId.length === 0) {
+  const authenticatedReaderId = isCookieAuth2(auth) ? auth.tokenId ?? "hq-password-session" : isTokenAuth2(auth) ? auth.id : void 0;
+  const resolvedReaderId = authenticatedReaderId ?? abody.readerId;
+  if (typeof resolvedReaderId !== "string" || resolvedReaderId.length === 0) {
     res.writeHead(400, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ error: "missing readerId" }));
     return;
@@ -2279,7 +3044,7 @@ async function handleMailboxAction(_req, res, match, _mutableAuth, _sessions, da
     res.end(JSON.stringify({ error: "missing sessionId or projectId" }));
     return;
   }
-  const actGlobalRoot = path4.dirname(dataDir);
+  const actGlobalRoot = path5.dirname(dataDir);
   const projectRoot = await resolveHqProjectRoot(actGlobalRoot, {
     sessionId: abody.sessionId,
     projectId: abody.projectId
@@ -2293,7 +3058,7 @@ async function handleMailboxAction(_req, res, match, _mutableAuth, _sessions, da
     const { actionToAckInput } = await import("@wrongstack/core/coordination");
     const projectDir = resolveProjectDir(projectRoot, actGlobalRoot);
     const mailbox = getMailboxGateway(projectDir).mailbox;
-    const readerId = abody.readerId;
+    const readerId = resolvedReaderId;
     const message = action === "soft-delete" ? await mailbox.softDelete(mailId, readerId) : action === "restore" ? await mailbox.restore(mailId) : await mailbox.ack(actionToAckInput(action, { action, mailId, readerId }));
     if (message === null) {
       res.writeHead(404, { "Content-Type": "application/json" });
@@ -2314,8 +3079,8 @@ async function handleMailboxAction(_req, res, match, _mutableAuth, _sessions, da
 }
 
 // src/hq-server/startup.ts
-import * as fs3 from "node:fs/promises";
-import * as path5 from "node:path";
+import * as fs4 from "node:fs/promises";
+import * as path6 from "node:path";
 var hqRuntimeMarkerPath2 = hqRuntimeMarkerPath;
 async function writeHqRuntimeMarker(dataDir, url) {
   const file = hqRuntimeMarkerPath2(dataDir);
@@ -2324,17 +3089,17 @@ async function writeHqRuntimeMarker(dataDir, url) {
     null,
     2
   );
-  await fs3.mkdir(path5.dirname(file), { recursive: true });
-  await fs3.writeFile(file, `${payload}
+  await fs4.mkdir(path6.dirname(file), { recursive: true });
+  await fs4.writeFile(file, `${payload}
 `, { encoding: "utf8", mode: 384 });
 }
 async function clearHqRuntimeMarker(dataDir, url) {
   const file = hqRuntimeMarkerPath2(dataDir);
   try {
-    const raw = await fs3.readFile(file, "utf8");
+    const raw = await fs4.readFile(file, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed.url === url && parsed.pid === process.pid) {
-      await fs3.rm(file, { force: true });
+      await fs4.rm(file, { force: true });
     }
   } catch {
   }
@@ -2370,7 +3135,7 @@ HQ auth loaded from ${startup.dataDir}
   if (startup.clientEnv.WRONGSTACK_HQ_TOKEN) {
     write(`  WRONGSTACK_HQ_TOKEN=${startup.clientEnv.WRONGSTACK_HQ_TOKEN}
 `);
-    write(`Credentials are stored in ${path5.join(startup.dataDir, "auth.json")}
+    write(`Credentials are stored in ${path6.join(startup.dataDir, "auth.json")}
 `);
   }
   writeHqLanEndpoints(write, handle, void 0);
@@ -3050,6 +3815,17 @@ function handleClient(ws, clients, browsers, eventLog, auth, snapshotBroadcaster
         }
         return;
       }
+      if (event.type === "governance.snapshot" && client !== void 0) {
+        if (!client.isLeader) return;
+        const result = parseHqEventPayload(event.type, event.payload);
+        if (result.ok) {
+          const payload = result.payload;
+          if (payload.projectId !== client.projectId) return;
+          client.governanceSnapshot = { payload, receivedAt: Date.now() };
+          snapshotBroadcaster.broadcast();
+        }
+        return;
+      }
       if (event.type === "session.transcript" && client !== void 0) {
         const result = parseHqEventPayload(event.type, event.payload);
         if (result.ok) {
@@ -3154,7 +3930,7 @@ async function startHqServerWithAuth(options, host, port, dataDir, firstRunAuth)
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
     })
   );
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const trustedPublicOrigins = /* @__PURE__ */ new Set();
     let listeningPort = port;
     const clients = /* @__PURE__ */ new Map();
@@ -3173,31 +3949,45 @@ async function startHqServerWithAuth(options, host, port, dataDir, firstRunAuth)
       12e4
     );
     mailboxGatewayRateLimitCleanup.unref?.();
-    const loginAttempts = /* @__PURE__ */ new Map();
-    const LOGIN_ATTEMPT_RETENTION_MS = 15 * 6e4;
+    const loginAttempts = new LoginAttemptStore(dataDir);
+    void loginAttempts.load();
     const HQ_SESSION_MAX_AGE_MS2 = 7 * 24 * 60 * 60 * 1e3;
+    const HQ_SESSION_IDLE_TIMEOUT_MS2 = 30 * 6e4;
     const SESSION_CLEANUP_INTERVAL_MS = 6e4;
+    const PENDING_2FA_TTL_MS2 = 5 * 6e4;
     const sessionCleanupTimer = setInterval(() => {
-      const cutoff = Date.now() - HQ_SESSION_MAX_AGE_MS2;
+      const now = Date.now();
+      const maxAgeCutoff = now - HQ_SESSION_MAX_AGE_MS2;
+      const idleCutoff = now - HQ_SESSION_IDLE_TIMEOUT_MS2;
+      const pending2faCutoff = now - PENDING_2FA_TTL_MS2;
       for (const [id, session] of sessions) {
-        if (session.createdAt < cutoff) sessions.delete(id);
+        if (session.createdAt < maxAgeCutoff) {
+          sessions.delete(id);
+          continue;
+        }
+        if (session.pending2fa) {
+          if (session.createdAt < pending2faCutoff) sessions.delete(id);
+          continue;
+        }
+        if (session.lastSeenAt < idleCutoff) {
+          sessions.delete(id);
+        }
       }
-      const now = Date.now();
-      for (const [ip, entry] of loginAttempts) {
-        if (now - entry.lastAttempt > LOGIN_ATTEMPT_RETENTION_MS) loginAttempts.delete(ip);
+      for (const [ip, entry] of loginAttempts.entries()) {
+        if (now - entry.lastAttempt > 15 * 6e4) loginAttempts.delete(ip);
       }
     }, SESSION_CLEANUP_INTERVAL_MS);
     sessionCleanupTimer.unref?.();
     const persistence = createHqPersistence(dataDir);
     const auditLog = new HqCommandAuditLog(1e3, (entry) => persistence.commandLog.append(entry));
     void (async () => {
-      const projectsDir = path6.join(path6.dirname(dataDir), "projects");
-      const entries = await fs4.readdir(projectsDir, { withFileTypes: true }).catch(() => []);
+      const projectsDir = path7.join(path7.dirname(dataDir), "projects");
+      const entries = await fs5.readdir(projectsDir, { withFileTypes: true }).catch(() => []);
       await Promise.all(
         entries.filter((entry) => entry.isDirectory()).map(async (entry) => {
-          const projectDir = path6.join(projectsDir, entry.name);
-          const metadataPath = path6.join(projectDir, ".mailbox-server.json");
-          const ownerPid = await fs4.readFile(metadataPath, "utf8").then((raw) => JSON.parse(raw).pid).catch(() => void 0);
+          const projectDir = path7.join(projectsDir, entry.name);
+          const metadataPath = path7.join(projectDir, ".mailbox-server.json");
+          const ownerPid = await fs5.readFile(metadataPath, "utf8").then((raw) => JSON.parse(raw).pid).catch(() => void 0);
           if (ownerPid === void 0) return;
           let ownerAlive = false;
           try {
@@ -3207,7 +3997,7 @@ async function startHqServerWithAuth(options, host, port, dataDir, firstRunAuth)
             ownerAlive = false;
           }
           if (!ownerAlive) {
-            await fs4.rm(metadataPath, { force: true }).catch(() => {
+            await fs5.rm(metadataPath, { force: true }).catch(() => {
             });
             return;
           }
@@ -3227,8 +4017,7 @@ async function startHqServerWithAuth(options, host, port, dataDir, firstRunAuth)
       const requestUrl = new URL(req.url ?? "/", `http://${host}:${port}`);
       const auth = authenticateBrowserRequest2(req, requestUrl, mutableAuth, sessions);
       const tokenMode = mutableAuth.browserTokens.size > 0;
-      const passwordMode = mutableAuth.passwordHash !== void 0;
-      if ((tokenMode || passwordMode) && auth === void 0) {
+      if (hqAuthRequired(mutableAuth) && auth === void 0) {
         return {
           allowed: false,
           status: 401,
@@ -3383,6 +4172,7 @@ async function startHqServerWithAuth(options, host, port, dataDir, firstRunAuth)
       host,
       listeningPort,
       trustedPublicOrigins,
+      allowFileOrigin: options.allowFileOrigin,
       mutableAuth,
       sessions,
       loginAttempts,
@@ -3427,7 +4217,13 @@ async function startHqServerWithAuth(options, host, port, dataDir, firstRunAuth)
         socket.destroy();
         return;
       }
-      if (!hasTrustedBrowserOrigin2(req, host, listeningPort, trustedPublicOrigins)) {
+      if (!hasTrustedBrowserOrigin2(
+        req,
+        host,
+        listeningPort,
+        trustedPublicOrigins,
+        options.allowFileOrigin
+      )) {
         socket.write(
           "HTTP/1.1 403 Forbidden\r\nContent-Type: application/json\r\nConnection: close\r\n\r\n" + JSON.stringify({
             error: {
@@ -3440,19 +4236,43 @@ async function startHqServerWithAuth(options, host, port, dataDir, firstRunAuth)
         return;
       }
       const tokenSet = pathname === "/ws/browser" ? mutableAuth.browserTokens : mutableAuth.clientTokens;
-      const needsAuth = pathname === "/ws/browser" ? options.requireBrowserAuth || tokenSet.size > 0 || mutableAuth.passwordHash !== void 0 : tokenSet.size > 0;
+      const needsAuth = pathname === "/ws/browser" ? hqAuthRequired(mutableAuth, options.requireBrowserAuth) : hqClientAuthRequired(mutableAuth);
       if (needsAuth) {
-        const supplied = url.searchParams.get("token") ?? "";
+        let supplied = url.searchParams.get("token") ?? "";
+        if (supplied && pathname === "/ws/browser") {
+          const requestHost = (req.headers.host ?? "").trim();
+          let wsHostname = "";
+          try {
+            wsHostname = new URL(`http://${requestHost}`).hostname;
+          } catch {
+          }
+          if (wsHostname && !isLoopbackHost3(wsHostname)) {
+            console.warn(
+              JSON.stringify({
+                level: "warn",
+                event: "hq.ws_token_from_query_rejected",
+                message: "Browser token in WS query rejected on non-loopback \u2014 use session cookie instead.",
+                timestamp: (/* @__PURE__ */ new Date()).toISOString()
+              })
+            );
+            supplied = "";
+          }
+        }
         const tokenValid = timingSafeTokenMatch(tokenSet, supplied) !== void 0;
         const cookieValid = pathname === "/ws/browser" && mutableAuth.cookieSecret !== void 0 && (() => {
           const cookies = parseCookieHeader2(req.headers.cookie);
-          const raw = cookies[HQ_SESSION_COOKIE2];
+          const raw = cookies[HQ_SESSION_COOKIE2] ?? cookies["__Host-hq.session"];
           if (!raw) return false;
           const sessionId = parseHqSessionCookie2(raw, mutableAuth.cookieSecret);
           if (sessionId === void 0) return false;
           const session = sessions.get(sessionId);
           if (!session || Date.now() - session.createdAt >= HQ_SESSION_MAX_AGE_MS)
             return false;
+          const now2 = Date.now();
+          if (!session.pending2fa && now2 - session.lastSeenAt > HQ_SESSION_IDLE_TIMEOUT_MS)
+            return false;
+          session.lastSeenAt = now2;
+          if (session.pending2fa) return false;
           if (session.kind === "token" && session.tokenId !== void 0) {
             return [...mutableAuth.browserTokenObjs.values()].some(
               (obj) => obj.id === session.tokenId
@@ -3488,7 +4308,11 @@ async function startHqServerWithAuth(options, host, port, dataDir, firstRunAuth)
           browsers,
           eventLog,
           {
-            ...token ? { token: mutableAuth.clientTokenObjs.get(token) } : {},
+            // WS-044: `clientTokenObjs` is keyed on `hqTokenKey` — the verifier —
+            // so the presented secret is hashed before lookup. Indexing with the
+            // raw value silently returned undefined, which downgraded a scoped
+            // token to "no capabilities record" at the capability gate.
+            ...token ? { token: mutableAuth.clientTokenObjs.get(hqTokenVerifier2(token)) } : {},
             getOperatorPolicy: () => mutableAuth.operatorPolicyOverride
           },
           snapshotBroadcaster,
@@ -3503,7 +4327,26 @@ async function startHqServerWithAuth(options, host, port, dataDir, firstRunAuth)
       dataDir,
       (next) => {
         authState.apply(next);
-        if (options.requireBrowserAuth && mutableAuth.browserTokens.size === 0 && mutableAuth.passwordHash === void 0) {
+        const exposure = assessHqExposure2({
+          host,
+          hasBrowserTokens: mutableAuth.browserTokens.size > 0,
+          hasPassword: mutableAuth.passwordHash !== void 0,
+          allowInsecure: options.allowInsecureOpen
+        });
+        const previousFloor = mutableAuth.requireAuthFloor === true;
+        mutableAuth.requireAuthFloor = exposure.kind === "refuse";
+        if (mutableAuth.requireAuthFloor && !previousFloor) {
+          console.error(
+            JSON.stringify({
+              level: "error",
+              event: "hq.auth.open_mode_refused",
+              message: "Last HQ credential removed while bound to a non-loopback address. Refusing to serve unauthenticated: requests will return 401 until a token or password is configured, or HQ is restarted with --host 127.0.0.1.",
+              host,
+              timestamp: (/* @__PURE__ */ new Date()).toISOString()
+            })
+          );
+        }
+        if ((options.requireBrowserAuth || mutableAuth.requireAuthFloor) && mutableAuth.browserTokens.size === 0 && mutableAuth.passwordHash === void 0) {
           sessions.clear();
           for (const browser of browsers) browser.close(1008, "Browser authentication removed");
         }
@@ -3554,14 +4397,13 @@ async function startHqServerWithAuth(options, host, port, dataDir, firstRunAuth)
         const addr = httpServer.address();
         const actualPort = typeof addr === "object" && addr ? addr.port : port;
         listeningPort = actualPort;
-        const browserToken = firstRunAuth.browserToken?.token ?? authFile.browserTokens?.find((t) => t.token.trim().length > 0)?.token;
         const clientToken = firstRunAuth.clientToken?.token ?? authFile.clientTokens?.find((t) => t.token.trim().length > 0)?.token;
         const hqUrl = `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${actualPort}`;
         await writeHqRuntimeMarker(dataDir, hqUrl).catch(() => {
         });
-        const browserTokenObj = mutableAuth.browserTokenObjs.get(browserToken ?? "");
+        const browserTokenObj = (firstRunAuth.browserToken !== void 0 ? mutableAuth.browserTokenObjs.get(hqTokenKey3(firstRunAuth.browserToken)) : void 0) ?? mutableAuth.browserTokenObjs.values().next().value;
         let browserUrl;
-        if (browserToken && browserTokenObj) {
+        if (browserTokenObj) {
           const code = bootstrapStore.issue({
             tokenId: browserTokenObj.id,
             ...browserTokenObj.capabilities !== void 0 ? { capabilities: browserTokenObj.capabilities } : {}
@@ -3608,6 +4450,7 @@ async function startHqServerWithAuth(options, host, port, dataDir, firstRunAuth)
             clearInterval(mailboxGatewayRateLimitCleanup);
             clearInterval(mailboxGatewaySweepTimer);
             clearInterval(sessionCleanupTimer);
+            void loginAttempts.flush();
             stopAlertEngine();
             authWatcher.close();
             snapshotBroadcaster.close();
@@ -3638,7 +4481,7 @@ async function startHqServerWithAuth(options, host, port, dataDir, firstRunAuth)
           port: actualPort,
           firstRunSetup: startupInfo
         });
-        resolve(handle);
+        resolve2(handle);
       })();
     });
   });
@@ -3662,4 +4505,4 @@ export {
   startHqServer,
   HqInsecureExposureError2 as HqInsecureExposureError
 };
-//# sourceMappingURL=chunk-7JABKXET.js.map
+//# sourceMappingURL=chunk-C5GH4YBL.js.map