@riceawa/dsh-lan-gateway 0.5.2 → 0.5.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@riceawa/dsh-lan-gateway",
   "description": "LAN/internet reverse-proxy gateway for the DeepSeek Harness web GUI: binds 0.0.0.0 and forwards to the loopback dsh web server. Default-deny: every source (loopback, LAN, internet) must sign in with an HMAC session cookie unless lanPasswordless is explicitly enabled; against dsh >= 0.1.2-rc.1 the gateway relays one shared upstream browser session, so the harness's own authorization still gates every request. Fail-closed start guard (password required, plaintext needs an explicit opt-in), session revocation by epoch (password changes and secret rotation kill cookies and live WebSockets), same-site/Origin fence on HTTP and WebSocket upgrades, optional TLS (auto self-signed or user-supplied certs), and a Settings → Plugins card for live adjustment of port, CIDRs, auth, and TLS. Includes an insecure-origin UUID shim client bundle: on gateway-served plain-HTTP origins browsers lack crypto.randomUUID, so the client half patches a getRandomValues-backed randomUUID onto the Crypto prototype, fixing workspace open over LAN without touching DSH source.",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -86,5 +86,6 @@
   "bugs": {
     "url": "https://github.com/rice-awa/dsh-lan-gateway/issues"
   },
-  "homepage": "https://github.com/rice-awa/dsh-lan-gateway#readme"
+  "homepage": "https://github.com/rice-awa/dsh-lan-gateway#readme",
+  "packageManager": "pnpm@11.20.0"
 }

package/skills/lan-gateway.md

@@ -9,8 +9,9 @@ user-invocable: true
 
 The `dsh-lan-gateway` plugin lets the DeepSeek Harness web GUI be reached from the
 LAN and the wider internet. dsh itself binds only to loopback (the web CLI
-hard-refuses `0.0.0.0`), so this plugin runs its own reverse-proxy gateway on
-`0.0.0.0` that forwards to the loopback web server while rewriting Host/Origin.
+hard-refuses `0.0.0.0`), so this plugin runs its own reverse-proxy gateway on the
+unspecified address — both families, so IPv6 clients reach it too — forwarding to
+the loopback web server while rewriting Host/Origin.
 
 Since v0.5.0 the model is **default-deny** (post-QVD-2026-57410 hardening):
 
@@ -31,8 +32,8 @@ Since v0.5.0 the model is **default-deny** (post-QVD-2026-57410 hardening):
 Do not edit state files by hand — use the `lan_gateway` tool.
 
 - `lan_gateway` with `command: "status"` — is it listening, on which port, toward
-  which dsh port, password set?, session epoch, upstream-session relay state,
-  ingress encryption, last error.
+  which dsh port, password set?, session epoch, how many signed-out sessions are
+  still held, upstream-session relay state, ingress encryption, last error.
 - `lan_gateway` with `command: "enable"` — start listening. If it refuses (no
   password, legacy `authRequired: false`, plaintext without opt-in, `lanPasswordless`
   without a session-capable base), the message tells you what to change.
@@ -72,3 +73,6 @@ once (passwords and sessions travel in clear).
   without an Origin) does not.
 - Sessions don't survive a password change / `rotate-secret`: that is by design —
   the revocation epoch advanced and all cookies (and live WebSockets) were revoked.
+  Signing out is narrower: it revokes only the session that signed out, so that
+  session's cookie is dead even if a copy of it was kept elsewhere, while the
+  user's other devices stay signed in.

package/src/auth.ts

@@ -100,16 +100,40 @@ export function classifySource(
   }
 
   if (address === '::1') return 'loopback'
-  // Link-local IPv6 fe80::/10.
-  if (address.toLowerCase().startsWith('fe80:')) return 'lan'
+  if (inIpv6LinkLocal(address)) return 'lan'
   return 'internet'
 }
 
+/**
+ * Whether a textual IPv6 address falls inside fe80::/10. The first ten bits are
+ * `1111111010`, so the leading hextet spans fe80–febf; a `startsWith('fe80:')`
+ * test covers only fe80::/16 and misclassifies fe90::–febf:: as internet.
+ */
+function inIpv6LinkLocal(address: string): boolean {
+  const match = /^([0-9a-fA-F]{1,4}):/.exec(address)
+  if (match === null) return false
+  return (Number.parseInt(match[1]!, 16) & 0xffc0) === 0xfe80
+}
+
 /** Encode a byte buffer as URL-safe base64 without padding. */
 function base64url(input: Buffer): string {
   return input.toString('base64url')
 }
 
+/** The claims a verified session cookie carries. */
+export interface SessionClaims {
+  /** Epoch millis at which the session expires. */
+  exp: number
+  /** The revocation epoch the cookie was minted under. */
+  epoch: number
+  /**
+   * Per-session id. Present on cookies minted from 0.5.4 on, which is what
+   * lets one session be retired on its own (sign-out) instead of retiring
+   * every session the password authorized. Absent on older cookies.
+   */
+  sid?: string
+}
+
 /**
  * Issue a signed session cookie value.
  * @param secret - the HMAC signing secret (base64 string).
@@ -118,28 +142,29 @@ function base64url(input: Buffer): string {
  *   cookie whose epoch no longer matches the live state is rejected by
  *   {@link verifyCookie}. Defaults to 0 (epoch-less, legacy) for callers that
  *   do not participate in revocation.
+ * @param sid - optional per-session id (see {@link SessionClaims.sid}).
  * @returns a `payload.signature` string suitable for the cookie value.
  */
-export function signCookie(secret: string, expiresMs: number, epoch: number = 0): string {
-  const payload = base64url(Buffer.from(JSON.stringify({ exp: expiresMs, epoch })))
+export function signCookie(secret: string, expiresMs: number, epoch: number = 0, sid?: string): string {
+  const claims = sid === undefined ? { exp: expiresMs, epoch } : { exp: expiresMs, epoch, sid }
+  const payload = base64url(Buffer.from(JSON.stringify(claims)))
   const sig = createHmac('sha256', secret).update(payload).digest('base64url')
   return `${payload}.${sig}`
 }
 
 /**
- * Whether a cookie value is a valid, unexpired session signed with `secret`
- * and minted under `epoch`. Epoch-less cookies (legacy payloads) count as
- * epoch 0, so an upgrade from a pre-0.5.0 state does not log everyone out.
+ * Verify a cookie's signature, expiry and epoch.
+ * @returns the claims it carries, or undefined when it is not a valid session.
  */
-export function verifyCookie(
+export function verifySession(
   secret: string,
   value: string | undefined,
   now: number,
   epoch: number = 0,
-): boolean {
-  if (value === undefined) return false
+): SessionClaims | undefined {
+  if (value === undefined) return undefined
   const dot = value.indexOf('.')
-  if (dot === -1) return false
+  if (dot === -1) return undefined
   const payload = value.slice(0, dot)
   const sig = value.slice(dot + 1)
   const expected = createHmac('sha256', secret).update(payload).digest()
@@ -147,20 +172,39 @@ export function verifyCookie(
   try {
     actual = Buffer.from(sig, 'base64url')
   } catch {
-    return false
+    return undefined
   }
-  if (expected.length !== actual.length) return false
-  if (!timingSafeEqual(expected, actual)) return false
+  if (expected.length !== actual.length) return undefined
+  if (!timingSafeEqual(expected, actual)) return undefined
   try {
-    const decoded = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')) as { exp?: unknown; epoch?: unknown }
-    if (typeof decoded.exp !== 'number' || decoded.exp <= now) return false
+    const decoded = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')) as Partial<SessionClaims>
+    if (typeof decoded.exp !== 'number' || decoded.exp <= now) return undefined
     const cookieEpoch = typeof decoded.epoch === 'number' ? decoded.epoch : 0
-    return cookieEpoch === epoch
+    if (cookieEpoch !== epoch) return undefined
+    return {
+      exp: decoded.exp,
+      epoch: cookieEpoch,
+      ...(typeof decoded.sid === 'string' ? { sid: decoded.sid } : {}),
+    }
   } catch {
-    return false
+    return undefined
   }
 }
 
+/**
+ * Whether a cookie value is a valid, unexpired session signed with `secret`
+ * and minted under `epoch`. Epoch-less cookies (legacy payloads) count as
+ * epoch 0, so an upgrade from a pre-0.5.0 state does not log everyone out.
+ */
+export function verifyCookie(
+  secret: string,
+  value: string | undefined,
+  now: number,
+  epoch: number = 0,
+): boolean {
+  return verifySession(secret, value, now, epoch) !== undefined
+}
+
 /**
  * Whether a browser Origin header names the same authority (hostname:port) as
  * a request Host header. Both sides run through WHATWG URL parsing so case and
@@ -181,7 +225,15 @@ export function originMatchesHost(origin: string | undefined, host: string | und
 
 /** A token bucket limiter keyed by source address. */
 export class RateLimiter {
+  /**
+   * Hard ceiling on tracked sources. Expiry alone only reclaims a bucket when
+   * `prune` runs, and a spray from many distinct addresses inside one window
+   * outruns it, so the map also sheds its soonest-expiring entries past this.
+   */
+  private static readonly MAX_BUCKETS = 10_000
   private readonly buckets = new Map<string, { tokens: number; resetAt: number }>()
+  /** Epoch millis at which the next opportunistic sweep is due. */
+  private nextPruneAt = 0
   constructor(
     private readonly maxTokens: number,
     private readonly windowMs: number,
@@ -194,22 +246,42 @@ export class RateLimiter {
    */
   allow(key: string): boolean {
     const now = Date.now()
-    const bucket = this.buckets.get(key)
-    if (bucket === undefined || bucket.resetAt <= now) {
-      this.buckets.set(key, { tokens: this.maxTokens - 1, resetAt: now + this.windowMs })
-      return true
+    // Sweep on a rolling window. Without this, expired buckets are only
+    // replaced when their own key returns, so every address that ever posted
+    // to the login route keeps an entry for the life of the process.
+    if (now >= this.nextPruneAt) {
+      this.prune(now)
+      this.nextPruneAt = now + this.windowMs
     }
-    if (bucket.tokens > 0) {
-      bucket.tokens -= 1
+    const existing = this.buckets.get(key)
+    if (existing !== undefined && existing.resetAt > now) {
+      if (existing.tokens <= 0) return false
+      existing.tokens -= 1
       return true
     }
-    return false
+    // A new bucket. A spray of distinct addresses inside one window outruns
+    // expiry, so shed the closest-to-expiring entries first — they are the
+    // ones about to lapse anyway, so the eviction costs the least fidelity.
+    if (existing === undefined && this.buckets.size >= RateLimiter.MAX_BUCKETS) {
+      this.evictSoonestToExpire()
+    }
+    this.buckets.set(key, { tokens: this.maxTokens - 1, resetAt: now + this.windowMs })
+    return true
   }
 
-  /** Drop expired buckets to bound memory. */
+  /** Drop expired buckets to bound memory. Called from {@link allow}. */
   prune(now: number = Date.now()): void {
     for (const [key, bucket] of this.buckets) {
       if (bucket.resetAt <= now) this.buckets.delete(key)
     }
   }
+
+  /** Trim back to 90% of the ceiling, oldest expiry first. */
+  private evictSoonestToExpire(): void {
+    const target = Math.floor(RateLimiter.MAX_BUCKETS * 0.9)
+    const byExpiry = [...this.buckets.entries()].sort((a, b) => a[1].resetAt - b[1].resetAt)
+    for (const [key] of byExpiry.slice(0, Math.max(0, this.buckets.size - target))) {
+      this.buckets.delete(key)
+    }
+  }
 }

package/src/client/lan-gateway-card.tsx

@@ -46,6 +46,7 @@ export interface LanGatewaySettings {
   tlsCertMaxAgeDays?: number
   allowInsecurePlaintext?: boolean
   trustedTerminator?: string
+  secureCookies?: boolean
 }
 
 /** GET /lan-gateway/config response. */
@@ -80,6 +81,7 @@ interface Labels {
   lastError: string
   [key: `field.${string}`]: string
   [key: `hint.${string}`]: string
+  [key: `opt.${string}`]: string
 }
 
 const LABELS: Record<'zh' | 'en', Labels> = {
@@ -114,6 +116,11 @@ const LABELS: Record<'zh' | 'en', Labels> = {
     'hint.allowInsecurePlaintext': '危险：关闭 TLS 或受信终止代理时仍启动监听，密码与会话将以明文传输',
     'field.trustedTerminator': '受信 TLS 终止代理',
     'hint.trustedTerminator': '可选：声明前置代理标识，视为加密入口（如 nginx）。留空 = 未声明',
+    'field.secureCookies': '会话 cookie 的 Secure 属性',
+    'hint.secureCookies': '自动 = TLS 或已声明受信终止代理时加 Secure。受信代理只做明文鉴权、浏览器走 http 访问时须设为 false，否则浏览器拒收 Secure cookie，登录会无限弹回登录页',
+    'opt.auto': '自动',
+    'opt.true': '始终 Secure',
+    'opt.false': '不加 Secure（明文浏览器入口）',
     'field.cookieMaxAgeDays': '会话有效期（天）',
     'hint.cookieMaxAgeDays': '登录 cookie 的存活天数（默认 7）',
     'field.tlsEnabled': '启用 TLS（HTTPS）',
@@ -160,6 +167,11 @@ const LABELS: Record<'zh' | 'en', Labels> = {
     'hint.allowInsecurePlaintext': 'Dangerous: start the listener even without TLS or a trusted terminator; passwords and sessions travel in clear',
     'field.trustedTerminator': 'Trusted TLS terminator',
     'hint.trustedTerminator': 'Optional identifier for a front proxy (e.g. nginx) treated as the encrypted ingress. Empty = none declared',
+    'field.secureCookies': 'Session cookie Secure attribute',
+    'hint.secureCookies': 'Auto = Secure when TLS or a trusted terminator is declared. Set false when the trusted proxy only authenticates over plaintext and browsers reach it over http — otherwise browsers drop the Secure cookie and every login bounces back to the login page',
+    'opt.auto': 'Auto',
+    'opt.true': 'Always Secure',
+    'opt.false': 'No Secure (plaintext browser ingress)',
     'field.cookieMaxAgeDays': 'Session lifetime (days)',
     'hint.cookieMaxAgeDays': 'Login cookie lifetime (default 7)',
     'field.tlsEnabled': 'Enable TLS (HTTPS)',
@@ -186,7 +198,7 @@ function labels(): Labels {
 /* Field model                                                         */
 /* ------------------------------------------------------------------ */
 
-type FieldKind = 'boolean' | 'number' | 'text' | 'cidrs' | 'select'
+type FieldKind = 'boolean' | 'number' | 'text' | 'cidrs' | 'select' | 'tristate'
 
 interface FieldDef {
   field: keyof LanGatewaySettings
@@ -195,6 +207,18 @@ interface FieldDef {
   options?: readonly string[]
 }
 
+/**
+ * The card's field table and its two value codecs are exported for tests: the
+ * tri-state codec is the load-bearing part of the settings round-trip (an
+ * unset value must stay distinguishable from an explicit false, or the
+ * plaintext-proxy escape hatch silently reverts).
+ */
+export { TRISTATE_OPTIONS, FIELDS, formatValue, parseValue }
+export type { FieldDef, Write }
+
+/** The three states of a tri-state field, in display order. */
+const TRISTATE_OPTIONS = ['auto', 'true', 'false'] as const
+
 const FIELDS: readonly FieldDef[] = [
   { field: 'enabled', kind: 'boolean' },
   { field: 'gatewayPort', kind: 'number' },
@@ -210,6 +234,7 @@ const FIELDS: readonly FieldDef[] = [
   { field: 'tlsCertMaxAgeDays', kind: 'number' },
   { field: 'allowInsecurePlaintext', kind: 'boolean' },
   { field: 'trustedTerminator', kind: 'text', optional: true },
+  { field: 'secureCookies', kind: 'tristate' },
 ]
 
 function formatValue(def: FieldDef, value: unknown): string {
@@ -218,6 +243,8 @@ function formatValue(def: FieldDef, value: unknown): string {
     case 'number': return typeof value === 'number' ? String(value) : ''
     case 'cidrs': return Array.isArray(value) ? value.join(', ') : ''
     case 'select': return typeof value === 'string' ? value : (def.options?.[0] ?? '')
+    // Tri-state: an unset value is a distinct third state ("auto"), never "false".
+    case 'tristate': return value === true ? 'true' : value === false ? 'false' : 'auto'
     case 'text': return typeof value === 'string' ? value : ''
   }
 }
@@ -242,6 +269,13 @@ function parseValue(def: FieldDef, text: string): Write | undefined {
     }
     case 'select':
       return def.options?.includes(trimmed) ? { kind: 'set', value: trimmed } : undefined
+    case 'tristate':
+      // 'auto' clears the key so it re-inherits the composition layer (and the
+      // resolution rule), which is what an unset tri-state means.
+      if (trimmed === 'auto') return { kind: 'clear' }
+      if (trimmed === 'true') return { kind: 'set', value: true }
+      if (trimmed === 'false') return { kind: 'set', value: false }
+      return undefined
     case 'text':
       return trimmed === '' ? (def.optional ? { kind: 'clear' } : undefined) : { kind: 'set', value: trimmed }
   }
@@ -384,6 +418,11 @@ export function LanGatewayCard(_props: LanGatewayCardProps): ReactNode {
           </div>
         )
       case 'select':
+      case 'tristate': {
+        // A tri-state renders as a three-way select because neither a checkbox
+        // (cannot express "unset") nor a text field (cannot express false)
+        // distinguishes auto from an explicit false.
+        const options = def.kind === 'tristate' ? TRISTATE_OPTIONS : (def.options ?? [])
         return (
           <div style={styles.field}>
             <label style={styles.label} htmlFor={`lan-gw-${field}`}>{label}</label>
@@ -394,7 +433,11 @@ export function LanGatewayCard(_props: LanGatewayCardProps): ReactNode {
               disabled={saving}
               onChange={(e: ChangeEvent<HTMLSelectElement>) => stage(field, e.target.value)}
             >
-              {def.options?.map(option => <option key={option} value={option}>{option}</option>)}
+              {options.map(option => (
+                <option key={option} value={option}>
+                  {def.kind === 'tristate' ? t[`opt.${option}`] : option}
+                </option>
+              ))}
             </select>
             <span style={styles.hint}>{hint}</span>
             <button
@@ -407,6 +450,7 @@ export function LanGatewayCard(_props: LanGatewayCardProps): ReactNode {
             </button>
           </div>
         )
+      }
       default:
         return (
           <div style={styles.field}>