@riceawa/dsh-lan-gateway 0.4.0 → 0.5.1

package/src/index.ts

@@ -5,18 +5,32 @@
  * dsh's web CLI hard-refuses `--host 0.0.0.0` (exposing remote code execution
  * to the network), so this plugin leaves dsh bound to 127.0.0.1 and starts its
  * own reverse-proxy gateway on 0.0.0.0 that forwards to the loopback dsh port,
- * rewriting Host/Origin so the `/api` trust fence passes. LAN and loopback
- * sources are proxied password-free; anything else must complete the login
- * page and present the HMAC cookie.
+ * rewriting Host/Origin so the request reaches the dsh web server as if it came
+ * from the loopback authority it names.
  *
- * The gateway listener can speak TLS: either a persisted auto-generated
- * self-signed certificate (`tlsMode: 'self-signed'`, hosts from
- * `tlsSelfSignedHosts`) or a user-supplied PEM pair (`tlsMode: 'custom'`,
- * `tlsCertPath` + `tlsKeyPath`).
+ * Security model (default-deny, post-QVD-2026-57410):
+ * - Every source — loopback, LAN, internet — must present a gateway session
+ *   before anything is forwarded. Classification by source IP grants nothing.
+ *   `lanPasswordless` is an explicit opt-in (false by default) that lets
+ *   LAN/loopback sources skip the gateway login; it is refused unless the dsh
+ *   base itself enforces browser-session auth (auto-detected in-process), so a
+ *   "trust my LAN" choice can never reinstall the original Host-trust hole.
+ * - Against such a base the gateway relays one shared upstream session (see
+ *   `upstream-session.ts`), so dsh's own authorization still gates every
+ *   request: the gateway only decides who may ride its shared session.
+ * - The listener refuses to run over plaintext unless TLS, a declared trusted
+ *   TLS-terminating proxy, or an explicit `allowInsecurePlaintext` opt-in is
+ *   present.
+ * - The gateway never relays its own surface (`/lan-gateway/*`, the login and
+ *   logout pages); sessions carry a revocation epoch that a password change or
+ *   secret rotation bumps, killing old cookies and established WebSockets.
  *
  * Every tunable is also exposed as the `lan-gateway` user-settings namespace
  * (`ctx.settings`), so the official DSH Settings → Plugins page can adjust
  * port, CIDRs, auth, and TLS live; the running listener restarts on change.
+ * The card reads/writes through the loopback-only `/lan-gateway/config` route;
+ * remote browsers get a 403 from the gateway for that prefix and manage the
+ * gateway through the `lan_gateway` tool instead.
  *
  * Disabled by default in the bundle patch (safe): the listener opens only
  * after `lan_gateway enable` or `enabled: true`.
@@ -28,8 +42,8 @@ import type { Context } from '@deepseek-ai/cordis'
 import { randomBytes } from 'node:crypto'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import z from '@deepseek-ai/schemastery'
-import { settingsNamespace, type SettingsScope } from '@deepseek-ai/dsh-settings'
-import { DEFAULT_LAN_CIDR_STRINGS } from './auth.ts'
+import type { SettingsScope } from '@deepseek-ai/dsh-settings'
+import { DEFAULT_LAN_CIDR_STRINGS, originMatchesHost } from './auth.ts'
 import { LanGateway } from './gateway.ts'
 import { readBody } from './login.ts'
 import {
@@ -47,6 +61,7 @@ import {
   type TlsMaterial,
 } from './tls.ts'
 import { lanGatewayTool } from './tool.ts'
+import { UpstreamSessionRelay, type UpstreamSession } from './upstream-session.ts'
 
 /** Stable Cordis plugin name. */
 export const name = 'dsh-lan-gateway'
@@ -65,9 +80,16 @@ export interface WebServerSurface {
   }): () => void
 }
 
+/** Minimal surface of the dsh client-connection service (session-capable bases). */
+export interface UpstreamConnectionSurface {
+  /** A root URL for the upstream origin carrying the process launch token. */
+  authenticatedUrl(baseUrl: string): string
+}
+
 declare module '@deepseek-ai/cordis' {
   interface Context {
     webServer: WebServerSurface
+    connection: UpstreamConnectionSurface
   }
 }
 
@@ -82,7 +104,7 @@ export interface GatewayController {
   status(): ToolResult
   enable(): Promise<ToolResult>
   disable(): Promise<ToolResult>
-  setPassword(password: string | undefined): ToolResult
+  setPassword(password: string | undefined): Promise<ToolResult>
   rotateSecret(): ToolResult
   regenerateTls(): Promise<ToolResult>
 }
@@ -95,10 +117,20 @@ export interface Config {
   gatewayPort: number
   /** Explicit dsh target port; defaults to the live `ctx.webServer.port`. */
   dshTargetPort?: number
-  /** LAN CIDRs treated as password-free. */
+  /** LAN CIDRs that may be treated as trusted when `lanPasswordless` is on. */
   lanCidrs: string[]
-  /** Whether non-LAN sources must authenticate. */
-  authRequired: boolean
+  /**
+   * Opt-in (default false): let LAN/loopback sources skip the gateway login.
+   * Only allowed against a session-capable dsh base, where upstream auth still
+   * gates every request via the relayed shared session.
+   */
+  lanPasswordless: boolean
+  /**
+   * Removed capability: authentication is always required. Retained only so an
+   * explicit legacy `authRequired: false` is rejected loudly instead of
+   * silently ignored.
+   */
+  authRequired?: boolean
   /** Session cookie lifetime in days. */
   cookieMaxAgeDays: number
   /** Cookie name. */
@@ -115,13 +147,29 @@ export interface Config {
   tlsSelfSignedHosts?: string
   /** Self-signed certificate validity in days (default 825 ≈ 27 months). */
   tlsCertMaxAgeDays: number
+  /**
+   * Escape hatch (default false): permit plaintext HTTP. Never derived from
+   * `X-Forwarded-Proto` — the operator declares it.
+   */
+  allowInsecurePlaintext: boolean
+  /**
+   * An identifier for a trusted TLS-terminating proxy in front of the gateway.
+   * Declaring one marks the ingress encrypted (Secure cookies, passes the
+   * encrypted-ingress gate) without this listener sending HSTS.
+   */
+  trustedTerminator?: string
 }
 
-/** The `lan-gateway` user-settings namespace, mirroring the composition schema. */
-const NS = settingsNamespace('lan-gateway')
+/**
+ * The `lan-gateway` user-settings namespace, mirroring the composition schema.
+ * A plain string literal: dsh-settings dropped the `settingsNamespace()` brand
+ * helper in 0.1.2-rc.1 and `register` validates the literal itself, so this
+ * shape works against both that release line and the older branded one.
+ */
+const NS = 'lan-gateway'
 
 /** Optional config keys: an empty submitted value clears them back to the composition layer. */
-const OPTIONAL_CONFIG_KEYS = new Set(['dshTargetPort', 'tlsCertPath', 'tlsKeyPath'])
+const OPTIONAL_CONFIG_KEYS = new Set(['dshTargetPort', 'tlsCertPath', 'tlsKeyPath', 'trustedTerminator'])
 
 /** Schemastery configuration validated by the Loader. */
 export const Config: z<Config> = z.object({
@@ -129,6 +177,7 @@ export const Config: z<Config> = z.object({
   gatewayPort: z.natural().min(1).max(65535).default(3081),
   dshTargetPort: z.natural().min(1).max(65535),
   lanCidrs: z.array(String).default([...DEFAULT_LAN_CIDR_STRINGS]),
+  lanPasswordless: z.boolean().default(false),
   authRequired: z.boolean().default(true),
   cookieMaxAgeDays: z.natural().min(1).max(365).default(7),
   cookieName: z.string().default('dsh_gw_auth'),
@@ -138,8 +187,46 @@ export const Config: z<Config> = z.object({
   tlsKeyPath: z.string(),
   tlsSelfSignedHosts: z.string().default('localhost'),
   tlsCertMaxAgeDays: z.natural().min(1).max(3650).default(825),
+  allowInsecurePlaintext: z.boolean().default(false),
+  trustedTerminator: z.string(),
 })
 
+/** Facts the fail-closed start guard needs to judge a config. */
+export interface StartFacts {
+  /** Whether the dsh base enforces browser-session auth (auto-detected). */
+  upstreamSessionAvailable: boolean
+}
+
+/**
+ * The fail-closed problems that prevent a config from enabling the listener.
+ * Returns every problem (not just the first) so the operator sees the full
+ * migration at once. Exported for tests.
+ */
+export function gatewayStartProblems(cfg: Config, facts: StartFacts): string[] {
+  const problems: string[] = []
+  if (cfg.authRequired === false) {
+    problems.push(
+      'authRequired=false is no longer supported — authentication is always required. '
+      + 'Remove `authRequired` (or set it true); for password-free LAN access set `lanPasswordless: true`.',
+    )
+  }
+  if (cfg.lanPasswordless && !facts.upstreamSessionAvailable) {
+    problems.push(
+      'lanPasswordless requires a dsh base with browser-session auth (>= 0.1.2-rc.1): the gateway '
+      + 'relaxes only its own login, never dsh authorization. Upgrade dsh, or set lanPasswordless: false.',
+    )
+  }
+  const encryptedIngress = cfg.tlsEnabled || cfg.trustedTerminator !== undefined
+  if (!encryptedIngress && !cfg.allowInsecurePlaintext) {
+    problems.push(
+      'Refusing to serve over plaintext HTTP: enable TLS (tlsEnabled: true), declare a trusted '
+      + 'TLS-terminating proxy (trustedTerminator), or set allowInsecurePlaintext: true to accept '
+      + 'the plaintext exposure (passwords and sessions would travel in clear).',
+    )
+  }
+  return problems
+}
+
 /** Resolve the TLS material for a config, or undefined when TLS is off. */
 function resolveTls(cfg: Config): TlsMaterial | undefined {
   if (!cfg.tlsEnabled) return undefined
@@ -160,7 +247,7 @@ function listenerKey(cfg: Config): string {
     cfg.gatewayPort,
     cfg.dshTargetPort,
     cfg.lanCidrs,
-    cfg.authRequired,
+    cfg.lanPasswordless,
     cfg.cookieMaxAgeDays,
     cfg.cookieName,
     cfg.tlsEnabled,
@@ -169,6 +256,8 @@ function listenerKey(cfg: Config): string {
     cfg.tlsKeyPath,
     cfg.tlsSelfSignedHosts,
     cfg.tlsCertMaxAgeDays,
+    cfg.allowInsecurePlaintext,
+    cfg.trustedTerminator,
   ])
 }
 
@@ -199,13 +288,17 @@ function isLoopbackHost(hostname: string): boolean {
   )
 }
 
+const READ_ONLY_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
+
 /**
- * Same-origin loopback fence for the config route (mirrors the fence the dsh
- * host uses for its own /api, and what dsh-lan-gateway's sibling plugins do):
- * the Host must be loopback (the gateway rewrites it), cross-site fetches are
- * refused, and any Origin must match the Host the browser actually used.
+ * Same-origin loopback fence for the native `/lan-gateway/config` route. The
+ * gateway refuses to relay this prefix, so the only way in is the native
+ * loopback listener itself (a genuine local user, or a local process that could
+ * already read `~/.dsh`). Host must be loopback (also blocks DNS rebinding),
+ * cross-site fetches are refused, an Origin must match the Host the browser
+ * used, and a state-changing method must carry that Origin. Exported for tests.
  */
-function isTrustedRequest(req: IncomingMessage): boolean {
+export function isTrustedConfigRequest(req: IncomingMessage): boolean {
   const host = req.headers?.host
   if (typeof host !== 'string' || host === '') return false
   let hostUrl: URL
@@ -217,12 +310,10 @@ function isTrustedRequest(req: IncomingMessage): boolean {
   if (!isLoopbackHost(hostUrl.hostname)) return false
   if (req.headers?.['sec-fetch-site'] === 'cross-site') return false
   const origin = req.headers?.origin
-  if (origin === undefined) return true
-  try {
-    return new URL(origin).host === hostUrl.host
-  } catch {
-    return false
-  }
+  if (origin !== undefined && !originMatchesHost(origin, host)) return false
+  const method = req.method ?? 'GET'
+  if (!READ_ONLY_METHODS.has(method) && origin === undefined) return false
+  return true
 }
 
 export function apply(ctx: Context, config: Config): void {
@@ -231,6 +322,10 @@ export function apply(ctx: Context, config: Config): void {
   let startedWith: string | undefined
   let lastError: string | undefined
   let manualOverride: boolean | undefined
+  /** Whether the base enforces browser-session auth; set once `connection` is seen. */
+  let upstreamSessionAvailable = false
+  /** Builds a fresh shared-session relay for a dsh port, once the base supports sessions. */
+  let makeRelay: ((dshPort: number) => UpstreamSession) | undefined
   /** The authoritative config: settings section when attached, else composition. */
   let configSource: () => Config = () => config
   /** Serializes listener start/stop/restart so settings changes cannot race. */
@@ -240,30 +335,34 @@ export function apply(ctx: Context, config: Config): void {
 
   const startGateway = async (cfg: Config): Promise<void> => {
     if (gateway !== undefined) return
-    if (cfg.authRequired && state.password === undefined) {
-      // A passwordless gateway exposed to non-LAN sources would be an open
-      // remote-code-execution door. Refuse to listen until a password is set.
-      throw new Error(
-        'dsh-lan-gateway: no password set — run `lan_gateway set-password` (or set '
-        + 'authRequired=false in the plugin config) before enabling.',
-      )
+    const problems = gatewayStartProblems(cfg, { upstreamSessionAvailable })
+    if (state.password === undefined) {
+      problems.unshift('no password set — run `lan_gateway set-password` before enabling the listener')
+    }
+    if (problems.length > 0) {
+      throw new Error(`dsh-lan-gateway: cannot start — ${problems.join(' ')}`)
     }
     const dshPort = cfg.dshTargetPort ?? ctx.webServer.port
     const tls = resolveTls(cfg)
+    const encryptedIngress = cfg.tlsEnabled || cfg.trustedTerminator !== undefined
     const next = new LanGateway({
       gatewayPort: cfg.gatewayPort,
       dshPort,
       lanCidrs: cfg.lanCidrs,
-      authRequired: cfg.authRequired,
+      lanPasswordless: cfg.lanPasswordless,
       cookieMaxAgeDays: cfg.cookieMaxAgeDays,
       cookieName: cfg.cookieName,
+      secureCookies: encryptedIngress,
       ...(tls !== undefined ? { tls } : {}),
+      ...(makeRelay !== undefined ? { upstreamSession: makeRelay(dshPort) } : {}),
     }, state)
     await next.listen()
     gateway = next
     startedWith = listenerKey(cfg)
     ctx.logger.info(
-      `dsh-lan-gateway: listening on 0.0.0.0:${cfg.gatewayPort}${tls !== undefined ? ' (TLS)' : ''} -> 127.0.0.1:${dshPort}`,
+      `dsh-lan-gateway: listening on 0.0.0.0:${cfg.gatewayPort}${tls !== undefined ? ' (TLS)' : ''}`
+      + ` -> 127.0.0.1:${dshPort}${encryptedIngress ? '' : ' (plaintext, explicit allowInsecurePlaintext)'}`
+      + `${makeRelay !== undefined ? ' [shared upstream session relay]' : ' [no upstream session relay: base has no browser-session auth]'}`,
     )
   }
 
@@ -321,16 +420,35 @@ export function apply(ctx: Context, config: Config): void {
     void syncGateway('settings attach')
   })
 
+  // A session-capable dsh base exposes the `connection` service (0.1.2+). The
+  // presence of that service both (a) tells the fail-closed guard that the base
+  // itself authenticates and (b) supplies the launch-token URL the shared-session
+  // relay exchanges. Optional: on an older base the callback never runs, the
+  // gateway forwards without a relay, and lanPasswordless stays refused.
+  ctx.inject(['connection'], (ccx) => {
+    upstreamSessionAvailable = true
+    makeRelay = (dshPort) => new UpstreamSessionRelay({
+      port: dshPort,
+      authenticatedUrl: () => ccx.connection.authenticatedUrl(`http://127.0.0.1:${dshPort}`),
+    })
+    // A listener that started before the connection service appeared must
+    // restart so it picks up the relay (and the now-correct fail-closed facts).
+    void syncGateway('connection attach')
+  })
+
   // The Settings → Plugins card reads and writes through this loopback-only
   // JSON route (ModLens-style: the browser never touches the settings seam
-  // directly, so the card has no service dependencies to resolve).
+  // directly, so the card has no service dependencies to resolve). The gateway
+  // refuses to relay this prefix, so only the native loopback listener can
+  // reach it — a genuine local user, or a local process that could already read
+  // ~/.dsh.
   const configRouteHandler = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     const send = (status: number, body: unknown): void => {
       res.writeHead(status, { 'content-type': 'application/json' })
       res.end(JSON.stringify(body))
     }
-    if (!isTrustedRequest(req)) {
-      send(403, { error: 'request refused: this route answers loopback-origin requests only' })
+    if (!isTrustedConfigRequest(req)) {
+      send(403, { error: 'request refused: this route answers same-origin loopback requests only' })
       return
     }
     if (req.method === 'GET') {
@@ -340,6 +458,7 @@ export function apply(ctx: Context, config: Config): void {
         running: gateway !== undefined,
         port: cfg.gatewayPort,
         tls: tlsStatusLine(cfg),
+        upstreamSessionAvailable,
         lastError: lastError ?? null,
       })
       return
@@ -374,6 +493,19 @@ export function apply(ctx: Context, config: Config): void {
       send(409, { error: 'settings service unavailable — edit the profile patch (cordis.patch.yml) instead' })
       return
     }
+    // Fail the save early (before persisting) when the candidate is unusable.
+    // A structural problem (legacy authRequired:false, lanPasswordless without
+    // a session-capable base) is invalid however it is reached; a start
+    // condition (plaintext without TLS/terminator/opt-in) only blocks a save
+    // that would actually enable the listener. This lets a disabled, dormant
+    // config be tuned without tripping the plaintext guard.
+    const structural = candidate.authRequired === false
+      || (candidate.lanPasswordless && !upstreamSessionAvailable)
+    const problems = gatewayStartProblems(candidate, { upstreamSessionAvailable })
+    if (structural || (candidate.enabled && problems.length > 0)) {
+      send(409, { error: `config cannot start: ${problems.join(' ')}` })
+      return
+    }
     // Build the next user section: drop null/undefined and empty optionals
     // (an empty path field re-inherits the composition layer).
     const section: Record<string, unknown> = {}
@@ -393,6 +525,7 @@ export function apply(ctx: Context, config: Config): void {
         running: gateway !== undefined,
         port: cfg.gatewayPort,
         tls: tlsStatusLine(cfg),
+        upstreamSessionAvailable,
         lastError: lastError ?? null,
       })
     } catch (error) {
@@ -408,16 +541,18 @@ export function apply(ctx: Context, config: Config): void {
     status(): ToolResult {
       const cfg = effective()
       const dshPort = cfg.dshTargetPort ?? ctx.webServer.port
+      const encrypted = cfg.tlsEnabled || cfg.trustedTerminator !== undefined
       return {
         ok: true,
         message:
           `LAN gateway: ${gateway !== undefined ? `LISTENING on 0.0.0.0:${cfg.gatewayPort}` : 'stopped'}`
           + `\n- dsh target: 127.0.0.1:${dshPort}`
           + `\n- password: ${state.password !== undefined ? 'set' : 'NOT SET'}`
-          + `\n- auth required for non-LAN: ${cfg.authRequired}`
-          + `\n- trusted LAN CIDRs: ${cfg.lanCidrs.join(', ') || '(none)'}`
+          + `\n- login required for all sources: true${cfg.lanPasswordless ? ' (LAN/loopback exempt via lanPasswordless)' : ''}`
+          + `\n- session epoch: ${state.sessionEpoch}`
+          + `\n- upstream session relay: ${upstreamSessionAvailable ? 'active (dsh browser-session auth present)' : 'absent (older dsh base)'}`
+          + `\n- ingress: ${cfg.tlsEnabled ? `TLS (${tlsStatusLine(cfg)})` : cfg.trustedTerminator !== undefined ? `TLS terminated by trusted proxy (${cfg.trustedTerminator})` : encrypted ? 'encrypted' : cfg.allowInsecurePlaintext ? 'PLAINTEXT (explicit allowInsecurePlaintext)' : 'plaintext — will not start'}`
           + `\n- session cookie: ${cfg.cookieName}, ${cfg.cookieMaxAgeDays}d`
-          + `\n- TLS: ${tlsStatusLine(cfg)}`
           + (manualOverride !== undefined
             ? `\n- manual override: ${manualOverride ? 'enabled' : 'disabled'}`
             : '')
@@ -436,30 +571,48 @@ export function apply(ctx: Context, config: Config): void {
       await syncGateway('tool disable')
       return { ok: true, message: 'Gateway disabled.' }
     },
-    setPassword(password: string | undefined): ToolResult {
+    async setPassword(password: string | undefined): Promise<ToolResult> {
       if (password !== undefined && password.length > 0 && password.length < 8) {
         return { ok: false, message: 'Password must be at least 8 characters.' }
       }
       const setting = password !== undefined && password.length > 0
+      const previous = state
       state = setPassword(state, setting ? password : undefined)
       saveState(state)
       gateway?.setState(state)
+      if (!setting) {
+        // Clearing the credential must not leave an open gateway serving
+        // sessions the old password authorized: stop the listener. A password
+        // is required to run, so a later enable fails closed.
+        manualOverride = false
+        if (gateway !== undefined) {
+          await stopGateway()
+          lastError = 'Password cleared — the gateway listener was stopped (a password is required to run).'
+          void syncGateway('password cleared')
+        }
+        return {
+          ok: true,
+          message: 'Password cleared. Session epoch advanced and the gateway listener was stopped — set a password before enabling it again.',
+        }
+      }
+      void (previous === undefined ? syncGateway('password set') : Promise.resolve())
       return {
         ok: true,
-        message: setting
-          ? 'Password set. Non-LAN access now requires it.'
-          : 'Password cleared. Non-LAN access is now password-free (only safe if authRequired is false or no non-LAN sources exist).',
+        message: 'Password set. Session epoch advanced — every previously issued session is now invalid; all sources must sign in again.',
       }
     },
     rotateSecret(): ToolResult {
-      const next: GatewayState = { cookieSecret: randomBytes(32).toString('base64') }
+      const next: GatewayState = {
+        cookieSecret: randomBytes(32).toString('base64'),
+        sessionEpoch: state.sessionEpoch + 1,
+      }
       if (state.password !== undefined) {
         next.password = state.password
       }
       state = next
       saveState(state)
       gateway?.setState(state)
-      return { ok: true, message: 'Session secret rotated. All existing login cookies are now invalid.' }
+      return { ok: true, message: 'Session secret rotated and epoch advanced. All existing login cookies and live WebSockets are now invalid.' }
     },
     async regenerateTls(): Promise<ToolResult> {
       const cfg = effective()
@@ -491,8 +644,8 @@ export function apply(ctx: Context, config: Config): void {
   ctx.tools.register(lanGatewayTool(controller))
 
   // Own the gateway lifecycle with the cordis tree.
-  ctx.effect(async () => {
-    await syncGateway('boot')
+  ctx.effect(() => {
+    void syncGateway('boot')
     return stopGateway
   }, 'dsh-lan-gateway: listener lifecycle')
 }

package/src/login.ts

@@ -11,6 +11,9 @@ import type { IncomingMessage, OutgoingHttpHeaders, ServerResponse } from 'node:
 /** Path the gateway owns and never forwards. */
 export const LOGIN_PATH = '/__login' as const
 
+/** Path the gateway owns and never forwards: signs the session out. */
+export const LOGOUT_PATH = '/__logout' as const
+
 /** The cookie name used for the signed session. */
 export const COOKIE_NAME = 'dsh_gw_auth' as const
 

package/src/state.ts

@@ -29,6 +29,14 @@ export interface GatewayState {
   cookieSecret: string
   /** scrypt password record, absent when no password is set. */
   password?: PasswordRecord
+  /**
+   * Session revocation epoch. Every issued login cookie carries the epoch it
+   * was signed under; a cookie whose epoch differs from the current one is
+   * rejected. Setting or clearing the password (and rotating the signing
+   * secret) increments the epoch so every previously issued session dies
+   * immediately. Old state files without the field load as epoch 0.
+   */
+  sessionEpoch: number
 }
 
 const STATE_FILENAME = 'state.json'
@@ -46,21 +54,26 @@ export function verifyPassword(state: GatewayState, password: string): boolean {
   }
 }
 
-/** Set (or clear) the password, re-salted on every write. */
+/**
+ * Set (or clear) the password, re-salted on every write. Both operations bump
+ * the session epoch so every cookie issued under the previous epoch dies — a
+ * password change must invalidate sessions the old password authorized.
+ */
 export function setPassword(state: GatewayState, password: string | undefined): GatewayState {
+  const base = { ...state, sessionEpoch: state.sessionEpoch + 1 }
   if (password === undefined) {
-    return { cookieSecret: state.cookieSecret }
+    return { cookieSecret: base.cookieSecret, sessionEpoch: base.sessionEpoch }
   }
   const salt = randomBytes(16)
   const hash = scryptSync(password, salt, 64)
   return {
-    ...state,
+    ...base,
     password: { hash: hash.toString('hex'), salt: salt.toString('hex') },
   }
 }
 
 function defaultState(): GatewayState {
-  return { cookieSecret: randomBytes(32).toString('base64') }
+  return { cookieSecret: randomBytes(32).toString('base64'), sessionEpoch: 0 }
 }
 
 /** Load state; on first run (or a corrupt file) generate a fresh secret. */
@@ -68,9 +81,17 @@ export function loadState(home: string = homedir()): GatewayState {
   const dir = stateDir(home)
   try {
     const raw = readFileSync(join(dir, STATE_FILENAME), 'utf8')
-    const parsed = JSON.parse(raw) as GatewayState
+    const parsed = JSON.parse(raw) as Partial<GatewayState>
     if (typeof parsed?.cookieSecret === 'string' && parsed.cookieSecret.length >= 16) {
-      return parsed
+      // Pre-0.5.0 files carry no sessionEpoch: treat them as epoch 0 so any
+      // cookie they issued (also epoch-less) still validates until the next
+      // password change or secret rotation bumps the epoch.
+      const sessionEpoch = typeof parsed.sessionEpoch === 'number' && Number.isSafeInteger(parsed.sessionEpoch)
+        ? parsed.sessionEpoch
+        : 0
+      const base: GatewayState = { cookieSecret: parsed.cookieSecret, sessionEpoch }
+      if (parsed.password !== undefined) base.password = parsed.password
+      return base
     }
     return defaultState()
   } catch {

package/src/tool.ts

@@ -27,20 +27,24 @@ export function lanGatewayTool(control: GatewayController): ToolDefinition {
     description:
       'Manage the LAN/internet gateway for this DeepSeek Harness web GUI. '
       + '`status` shows whether the gateway is listening, on which port, toward which dsh port, '
-      + 'whether a password is set, the trusted LAN CIDRs, and the TLS state. `enable` starts '
-      + 'listening on 0.0.0.0 (loopback and LAN sources need no password; anything else must sign '
-      + 'in). `disable` stops listening. `set-password` sets (or, with an empty password, clears) '
-      + 'the gateway password for non-LAN access. `rotate-secret` invalidates every issued login '
-      + 'cookie. `tls-regenerate` mints a fresh self-signed certificate (tlsMode must be '
-      + 'self-signed) and restarts the listener.',
+      + 'whether a password is set, the ingress/TLS state, and the upstream-session-relay state. '
+      + '`enable` starts listening on 0.0.0.0 — a password is required, and by default every source '
+      + '(loopback, LAN, internet) must sign in; set lanPasswordless to exempt LAN/loopback. The '
+      + 'listener also refuses to run over plaintext unless TLS, a declared trustedTerminator, or an '
+      + 'explicit allowInsecurePlaintext opt-in is present. `disable` stops listening. `set-password` '
+      + 'sets (or, with an empty password, clears) the gateway password; changing it revokes every '
+      + 'existing session, and clearing it stops the listener. `rotate-secret` invalidates every '
+      + 'issued login cookie and live WebSocket. `tls-regenerate` mints a fresh self-signed '
+      + 'certificate (tlsMode must be self-signed) and restarts the listener.',
     parameters: {
       command: {
         type: 'string',
         enum: ['status', 'enable', 'disable', 'set-password', 'rotate-secret', 'tls-regenerate'],
         description:
           '`status` (default) — report gateway state. `enable` / `disable` — start or stop the '
-          + 'listener. `set-password` — set or clear the login password. `rotate-secret` — '
-          + 'invalidate all existing sessions. `tls-regenerate` — mint a new self-signed certificate.',
+          + 'listener. `set-password` — set or clear the login password (setting revokes all '
+          + 'sessions; clearing stops the listener). `rotate-secret` — invalidate all existing '
+          + 'sessions. `tls-regenerate` — mint a new self-signed certificate.',
       },
       password: {
         type: 'string',