@lvxianchao/dsh-web-guard 2.0.1 → 2.1.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 2.1.1 — 2026-11-05
+
+### Docs
+
+- README and the admin page now describe the persisted session cache and the dead-session redirect; both still claimed sessions lived in memory and that a restart signed everyone out.
+- Screenshots re-shot with the corrected wording.
+
+
+## 2.1.0 — 2026-11-05
+
+### Added
+
+- **Sessions survive a restart.** The table is cached beside the password file (`dsh-web-guard-sessions-<port>.json`, mode 0600, atomic write), so upgrading or restarting DSH no longer signs every browser out — the open tab reconnects instead of hanging on "reconnecting". Rows that expired while the process was down are dropped on load.
+- **Dead-session redirect.** The injected client probes the new `/__guard/session` endpoint (200 = live, 401 = gone) when the tab becomes visible, when the browser comes back online, after a WebSocket close, and every 30s. A 401 sends the browser to the login page with `?next=`, so a genuine revocation (password change, sign-out-all) looks like a login prompt rather than a dead spinner.
+
+### Changed
+
+- Restarting the guard is no longer a way to sign everyone out. Use the admin page's "sign out all devices" — revocation is an explicit action now.
+
+### Security
+
+- The session cache stores SHA-256 hashes, never raw tokens. Neither the file nor a heap dump can mint a working cookie.
+
+
 ## 2.0.1 — 2026-11-05
 
 ### Internal

package/README.md

@@ -173,10 +173,21 @@ node -e "import('./lib/auth.js').then(m=>console.log(m.hashPassword(process.argv
 - Session tokens are stored server-side as SHA-256 digests; cookies are `HttpOnly`, `SameSite=Lax`, and `Secure` when TLS is on.
 - Login POSTs are checked for a same-hostname `Origin`. The session cookie's `SameSite` attribute is the primary CSRF defence.
 - Repeated failures from one IP trigger a temporary lock (in-memory, cleared on restart).
-- `/logout` ends the current browser session. To revoke everything, change the password and restart, or delete `$DSH_HOME/dsh-web-guard.json`.
+- **The session table is cached on disk** (`<profile>/data/dsh-web-guard-sessions-<port>.json`, mode `0600`, atomic tmp+rename), so **restarting DSH no longer signs signed-in browsers out**. The file holds SHA-256 digests, never tokens — neither the cache nor a heap dump can mint a working cookie. The filename carries the listener port, so a shadow instance cannot overwrite the live one.
+- `/logout` ends the current browser session. To revoke everything (a suspected leak, say), use the admin page's **sign out all devices** — **a restart is not a revocation any more**.
 
 **This is not multi-user.** One password, one privilege level. The harness agent can execute code, so anyone who gets in has code execution on that host — which is the product's design, not a bug in the gate.
 
+## When the session is gone
+
+If the session disappears (password changed, sign-out-all, or no activity within `sessionDays`), an open tab does not sit on "reconnecting" forever:
+
+- it probes `/__guard/session` when the tab becomes visible, when the network comes back, after a WebSocket close, and every 30 seconds
+- only an explicit **401** triggers a redirect — a failed fetch (offline, server restarting) never does
+- the redirect carries `?next=`, so you land back where you were after signing in
+
+Restarts (upgrades, config changes) are invisible: the session table is restored from disk and the page reconnects on its own.
+
 ## Admin page
 
 A shield button appears at the bottom-right of the harness UI once you are signed in. It opens `/__guard/admin` (bookmark the URL if you prefer):

package/README.zh.md

@@ -167,10 +167,21 @@ node -e "import('./lib/auth.js').then(m=>console.log(m.hashPassword(process.argv
 - 会话 token 服务端只存 SHA-256 摘要；cookie 是 `HttpOnly` + `SameSite=Lax`，启用 TLS 时加 `Secure`。
 - 登录 POST 校验 `Origin` 的 hostname 与请求 `Host` 一致（只比 hostname，因为反代常剥端口）。CSRF 的第一道防线仍是 `SameSite`。
 - 同一 IP 连续失败会临时锁定（内存计数，重启清零）。
-- `/logout` 只退当前浏览器；要全部吊销就改密码并重启，或删掉 `$DSH_HOME/dsh-web-guard.json`。
+- **会话表现在会落盘**（`<profile>/data/dsh-web-guard-sessions-<port>.json`，`0600`，临时文件 + rename 原子写入），所以**重启 DSH 不会把已登录的浏览器踢下线**。文件里存的同样是 SHA-256 摘要，不是 token——拿到这个文件或内存 dump 都无法伪造 cookie。文件名带监听端口，影子实例不会覆盖正式实例。
+- `/logout` 只退当前浏览器。要全部吊销（比如怀疑泄露），用管理页的**退出所有设备**：**重启不再等于吊销**。
 
 **这不是多用户系统**：一个密码，一个权限级别。DSH 的 agent 本身能执行代码，任何登录者都拥有该机器的执行权限——这是产品设计，不是闸门的缺陷。
 
+## 掉线之后
+
+会话没了（改过密码、点了退出所有设备、或超过 `sessionDays` 没活动）时，已经开着的标签页不会卡在"重新连接中"：
+
+- 切回标签页、网络恢复、WebSocket 断开、以及每 30 秒，页面都会向 `/__guard/session` 探一次
+- 只有拿到明确的 **401** 才跳转（断网导致的请求失败不会误判）
+- 跳转目标带 `?next=`，登录后回到原来那个地址
+
+需要重启（升级、改配置）则完全无感：会话表会从磁盘恢复，页面自己重连回来。
+
 ## 管理页
 
 登录后 DSH 界面右下角会出现一个盾牌按钮，点开就是 `/__guard/admin`（也可以直接把地址收藏起来）：

package/lib/auth.js

@@ -4,13 +4,17 @@
  * Design notes:
  * - Passwords are stored as scrypt `scrypt$N$r$p$salt$key` (same shape the
  *   Hermes dashboard uses) so a hash can be pasted into config.
- * - Sessions live in memory: the plugin restarts with dsh, and a restart
- *   should force a fresh login anyway. Tokens are stored hashed, so a heap
- *   dump does not hand out live sessions.
+ * - Sessions are hashed before they reach memory *and* the on-disk cache, so
+ *   neither a heap dump nor the state file can mint a working cookie. The
+ *   cache exists so a restart (upgrade, config change) does not sign everyone
+ *   out; revocation still goes through the admin page, and a session that
+ *   expired while the process was down is dropped on load.
  * - Every session carries its own expiry and last-seen stamp; the cookie
  *   lifetime is fixed at issue time, the server side slides on activity.
  */
 import { randomBytes, createHash, scryptSync, timingSafeEqual } from 'node:crypto'
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
 
 const SCRYPT_N = 16384
 const SCRYPT_R = 8
@@ -59,7 +63,7 @@ export class SessionStore {
    * @param {number} options.maxAttempts - failures before a temporary lock
    * @param {number} options.lockMinutes - lock duration in minutes
    */
-  constructor({ sessionDays = 7, maxAttempts = 5, lockMinutes = 5 } = {}) {
+  constructor({ sessionDays = 7, maxAttempts = 5, lockMinutes = 5, file } = {}) {
     this.sessionMs = Math.max(0, sessionDays) * 24 * 60 * 60 * 1000
     this.maxAttempts = Math.max(1, maxAttempts)
     this.lockMs = Math.max(1, lockMinutes) * 60 * 1000
@@ -67,10 +71,66 @@ export class SessionStore {
     this.sessions = new Map()
     /** @type {Map<string, {fails:number,until:number}>} */
     this.failures = new Map()
+    this.file = typeof file === 'string' && file.length > 0 ? file : ''
+    this.persistTimer = null
     this.timer = setInterval(() => this.sweep(), 10 * 60 * 1000)
     this.timer.unref?.()
   }
 
+  /**
+   * Restore the table a previous process wrote. A missing or corrupt file is
+   * treated as "no sessions" — a damaged cache must never block sign-in.
+   */
+  load() {
+    if (!this.file) return
+    let data
+    try {
+      data = JSON.parse(readFileSync(this.file, 'utf8'))
+    } catch {
+      return
+    }
+    if (data === null || typeof data !== 'object' || data.version !== 1) return
+    if (data.sessions === null || typeof data.sessions !== 'object') return
+    const now = Date.now()
+    const limit = this.sessionMs === 0 ? 12 * 60 * 60 * 1000 : this.sessionMs
+    for (const [key, row] of Object.entries(data.sessions)) {
+      if (!/^[0-9a-f]{64}$/.test(key)) continue
+      if (typeof row?.createdAt !== 'number' || typeof row?.lastSeen !== 'number') continue
+      if (now - row.lastSeen > limit) continue
+      this.sessions.set(key, {
+        createdAt: row.createdAt,
+        lastSeen: row.lastSeen,
+        ip: typeof row.ip === 'string' ? row.ip : '',
+        ua: typeof row.ua === 'string' ? row.ua : '',
+      })
+    }
+  }
+
+  /** Write the table atomically (tmp + rename); disk problems never block auth. */
+  persist() {
+    if (!this.file) return
+    try {
+      const sessions = {}
+      for (const [key, row] of this.sessions) sessions[key] = row
+      mkdirSync(dirname(this.file), { recursive: true })
+      const tmp = `${this.file}.${process.pid}.tmp`
+      writeFileSync(tmp, JSON.stringify({ version: 1, savedAt: Date.now(), sessions }), { mode: 0o600 })
+      renameSync(tmp, this.file)
+    } catch {
+      // Read-only data dir or full disk: this process keeps working from memory.
+    }
+  }
+
+  /** Coalesce a burst of changes into one write. */
+  touch() {
+    if (!this.file || this.persistTimer !== null) return
+    this.persistTimer = setTimeout(() => {
+      this.persistTimer = null
+      this.persist()
+    }, 500)
+    this.persistTimer.unref?.()
+  }
+
   /** Whether this client is currently locked out. */
   isLocked(ip) {
     const row = this.failures.get(ip)
@@ -102,6 +162,7 @@ export class SessionStore {
     const token = randomBytes(32).toString('base64url')
     const now = Date.now()
     this.sessions.set(sha256(token), { createdAt: now, lastSeen: now, ip, ua })
+    this.touch()
     return token
   }
 
@@ -115,14 +176,17 @@ export class SessionStore {
     const limit = this.sessionMs === 0 ? 12 * 60 * 60 * 1000 : this.sessionMs
     if (now - row.lastSeen > limit) {
       this.sessions.delete(key)
+      this.touch()
       return undefined
     }
     row.lastSeen = now
+    this.touch()
     return row
   }
 
   revoke(token) {
-    if (typeof token === 'string' && token.length > 0) this.sessions.delete(sha256(token))
+    if (typeof token !== 'string' || token.length === 0) return
+    if (this.sessions.delete(sha256(token))) this.touch()
   }
 
   /** List live sessions with a short opaque id (the hashed key prefix). */
@@ -143,6 +207,7 @@ export class SessionStore {
     for (const key of this.sessions.keys()) {
       if (key.slice(0, 16) === id) {
         this.sessions.delete(key)
+        this.touch()
         return true
       }
     }
@@ -157,21 +222,32 @@ export class SessionStore {
 
   revokeAll() {
     this.sessions.clear()
+    this.touch()
   }
 
   sweep() {
     const now = Date.now()
+    let dropped = false
     const limit = this.sessionMs === 0 ? 12 * 60 * 60 * 1000 : this.sessionMs
     for (const [key, row] of this.sessions) {
-      if (now - row.lastSeen > limit) this.sessions.delete(key)
+      if (now - row.lastSeen > limit) {
+        this.sessions.delete(key)
+        dropped = true
+      }
     }
     for (const [ip, row] of this.failures) {
       if (row.until > 0 && row.until < now) this.failures.delete(ip)
     }
+    if (dropped) this.touch()
   }
 
   dispose() {
     clearInterval(this.timer)
+    if (this.persistTimer !== null) {
+      clearTimeout(this.persistTimer)
+      this.persistTimer = null
+    }
+    this.persist()
     this.sessions.clear()
     this.failures.clear()
   }

package/lib/i18n.js

@@ -114,7 +114,7 @@ const ZH = {
   signOutAll: '退出所有设备',
   confirmSignOutAll: '将退出所有设备上的登录，包括当前这个。继续？',
   secSessions: '活跃会话',
-  hintSessions: '每个浏览器一条记录。会话存在内存里，重启 DSH 会全部失效。',
+  hintSessions: '每个浏览器一条记录。会话落盘保存，重启 DSH 不会把人踢下线；要全员下线请点「退出所有设备」。',
   colSource: '来源',
   colBrowser: '浏览器',
   colLastSeen: '最后活动',
@@ -169,7 +169,7 @@ const EN = {
   signOutAll: 'Sign out everywhere',
   confirmSignOutAll: 'This signs out every device, including this one. Continue?',
   secSessions: 'Active sessions',
-  hintSessions: 'One row per browser. Sessions live in memory and are cleared when DSH restarts.',
+  hintSessions: 'One row per browser. Sessions are persisted, so restarting DSH keeps everyone signed in — use "Sign out all devices" to revoke them.',
   colSource: 'Source',
   colBrowser: 'Browser',
   colLastSeen: 'Last seen',

package/lib/index.js

@@ -60,6 +60,15 @@ function statePath(profileDir) {
   return join(profileDir, 'data', 'dsh-web-guard.json')
 }
 
+/**
+ * Session cache lives beside the password but keyed by listener port: a shadow
+ * instance (dev.yml, port 3100) runs against the same profile and must not
+ * fight the live one over one file. Ports are exclusive, so this is a safe key.
+ */
+function sessionsPath(profileDir, port) {
+  return join(profileDir, 'data', `dsh-web-guard-sessions-${port}.json`)
+}
+
 function readState(profileDir) {
   for (const path of [statePath(profileDir), legacyStatePath()]) {
     try {
@@ -181,7 +190,11 @@ export function apply(ctx, config = {}) {
     sessionDays: Number(cfg.sessionDays),
     maxAttempts: Number(cfg.maxAttempts),
     lockMinutes: Number(cfg.lockMinutes),
+    file: sessionsPath(profileDir, cfg.listenPort),
   })
+  // Restore sessions from the previous process: a restart (upgrade, config
+  // change) must not sign every browser out. Expired rows are dropped on load.
+  sessions.load()
 
   // Locale follows the harness: its language picker writes `preference` into
   // the profile patch file. Uncached reads would hit the filesystem on every
@@ -396,6 +409,13 @@ export function apply(ctx, config = {}) {
 
     if (path === '/__guard/health') return json(res, 200, { ok: true, service: 'dsh-web-guard' })
 
+    // Authenticated probe: 200 when this browser still holds a live session,
+    // 401 when it does not. The injected client uses it to leave the
+    // "reconnecting" spinner for the login page instead of retrying forever.
+    if (path === '/__guard/session') {
+      return sessionOf(req) ? json(res, 200, { ok: true }) : json(res, 401, { ok: false })
+    }
+
     if (path === '/login' && req.method === 'GET') {
       if (sessionOf(req)) return redirect(res, '/')
       return html(res, 200, loginPage({ title: cfg.title, next: url.searchParams.get('next') ?? '/', repo: cfg.repo, locale }))

package/lib/inject.js

@@ -58,6 +58,40 @@ border:1px solid #24282e;background:#0b0d10;box-shadow:0 24px 80px rgba(0,0,0,.6
     document.body.style.overflow = "hidden";
   }
   fab.addEventListener("click", open);
+
+  // ── session watchdog ────────────────────────────────────────────────
+  // DSH only ever sees "WebSocket closed"; it does not know this gate exists.
+  // When the session is really gone (password change, revoke-all, expiry) we
+  // send the browser to the login page instead of spinning on reconnect.
+  // A 401 is the only trigger: a failed fetch means the network is down.
+  var probing = false;
+  function probe() {
+    if (probing) return;
+    probing = true;
+    fetch("/__guard/session", { cache: "no-store", credentials: "same-origin" })
+      .then(function (r) {
+        if (r.status === 401) {
+          location.href = "/login?next=" + encodeURIComponent(location.pathname + location.search);
+        }
+      })
+      .catch(function () {})
+      .then(function () { probing = false; });
+  }
+  document.addEventListener("visibilitychange", function () { if (!document.hidden) probe(); });
+  window.addEventListener("online", probe);
+  setInterval(probe, 30000);
+  var NativeWS = window.WebSocket;
+  if (NativeWS) {
+    window.WebSocket = function (url, protocols) {
+      var ws = protocols === undefined ? new NativeWS(url) : new NativeWS(url, protocols);
+      ws.addEventListener("close", function () { setTimeout(probe, 2000); });
+      return ws;
+    };
+    window.WebSocket.prototype = NativeWS.prototype;
+    ["CONNECTING", "OPEN", "CLOSING", "CLOSED"].forEach(function (k) {
+      window.WebSocket[k] = NativeWS[k];
+    });
+  }
   window.addEventListener("message", function (ev) {
     if (ev.origin !== location.origin) return;
     if (ev.data === "dsh-web-guard:close") close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lvxianchao/dsh-web-guard",
-  "version": "2.0.1",
+  "version": "2.1.1",
   "description": "Password login for the DeepSeek Harness Web UI, so it can be exposed on the internet: sign in from anywhere instead of chasing one-off tokens, with reverse-proxy quirks handled.",
   "type": "module",
   "main": "lib/index.js",