@riceawa/dsh-lan-gateway 0.5.2 → 0.5.4

package/src/gateway.ts

@@ -1,6 +1,7 @@
 /**
- * The reverse-proxy gateway: a `node:http(s)` server bound to `0.0.0.0` that
- * forwards every request to the loopback dsh web server.
+ * The reverse-proxy gateway: a `node:http(s)` server bound to the unspecified
+ * address (dual-stack, so IPv6 clients reach it too) that forwards every
+ * request to the loopback dsh web server.
  *
  * Security model (post-QVD / session-base):
  * - Source is classified from `socket.remoteAddress` only (never
@@ -23,22 +24,25 @@
  *   authority-bound session cookie). The gateway therefore relays one shared
  *   upstream session acquired through the launch-token exchange and replays it
  *   on every forwarded request. See `upstream-session.ts`.
- * - Sessions carry a revocation epoch: a password change or secret rotation
- *   bumps the epoch, every previously issued cookie dies, and established
- *   WebSockets are torn down so the client re-authenticates.
+ * - Sessions are revocable two ways. Each carries a random id, so signing out
+ *   retires exactly that session and the WebSockets it opened; and each
+ *   carries a revocation epoch, so a password change or secret rotation kills
+ *   every session at once — cookie, socket, and all.
  *
  * @module @riceawa/dsh-lan-gateway/gateway
  */
 
 import http from 'node:http'
 import https from 'node:https'
+import { randomBytes } from 'node:crypto'
 import type { Duplex } from 'node:stream'
 import {
   classifySource,
   originMatchesHost,
   RateLimiter,
   signCookie,
-  verifyCookie,
+  verifySession,
+  type SessionClaims,
   type SourceClass,
 } from './auth.ts'
 import {
@@ -49,12 +53,17 @@ import {
   serveLoginGet,
   type LoginPageOptions,
 } from './login.ts'
-import { verifyPassword, type GatewayState } from './state.ts'
+import {
+  isSessionRevoked,
+  revokeSession,
+  verifyPassword,
+  type GatewayState,
+} from './state.ts'
 import type { UpstreamSession } from './upstream-session.ts'
 
 /** Configuration the gateway needs at listen time. */
 export interface GatewayConfig {
-  /** Port to bind on 0.0.0.0. */
+  /** Port to bind on the unspecified address (dual-stack; see {@link LanGateway.listen}). */
   gatewayPort: number
   /** The loopback dsh web server port to forward to. */
   dshPort: number
@@ -74,6 +83,12 @@ export interface GatewayConfig {
   classifySource?: (req: http.IncomingMessage) => SourceClass
   /** Optional shared upstream session relayed onto every forwarded request. */
   upstreamSession?: UpstreamSession
+  /**
+   * Called after the gateway revokes a session itself (sign-out), so the plugin
+   * can persist a state the gateway changed on its own. The gateway has already
+   * installed it locally by then.
+   */
+  onStateChange?: (state: GatewayState) => void
 }
 
 const DEFAULT_BODY_LIMIT_BYTES = 64 * 1024
@@ -83,15 +98,102 @@ const LOGIN_ATTEMPTS_WINDOW_MS = 60_000
 /** Methods a browser never attaches a CSRF-meaningful body to; safe without an Origin. */
 const READ_ONLY_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
 
+/** The upstream browser-session cookie name prefix; the relay owns this namespace. */
+const UPSTREAM_COOKIE_PREFIX = 'dsh-auth-'
+
+/**
+ * Headers a proxy must not forward in either direction (RFC 9110 §7.6.1), plus
+ * the non-standard proxy-connection.
+ */
+const HOP_BY_HOP_HEADERS = new Set([
+  'connection',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'proxy-connection',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+])
+
+/**
+ * Headers by which a client asserts where a request came from. The gateway
+ * classifies on `socket.remoteAddress` and never reads these, so relaying a
+ * caller's own values only hands the next hop a forgeable claim.
+ */
+const FORWARDING_HEADERS = [
+  'forwarded',
+  'x-forwarded-for',
+  'x-forwarded-host',
+  'x-forwarded-port',
+  'x-forwarded-proto',
+  'x-real-ip',
+]
+
+/** Whether a Cookie fragment names the upstream session cookie. */
+function isUpstreamSessionPair(pair: string): boolean {
+  return pair.startsWith(UPSTREAM_COOKIE_PREFIX)
+}
+
+/**
+ * Drop every `dsh-auth-*` pair from a Cookie header, returning the remainder
+ * (possibly '').
+ *
+ * `attachUpstreamSession` appends the relay's session to the client's own
+ * cookie, and upstream reads the FIRST name match. A client that holds any
+ * `dsh-auth-<hash>` — typically one minted before dsh's signing secret was
+ * reset, so still present but no longer verifying — would therefore shadow the
+ * relay's session on every request. That draws a 401, the gateway reads the
+ * 401 as "upstream revoked our session" and discards it, the next request
+ * re-acquires, and the client's stale cookie shadows that one too: a loop that
+ * never converges. Stripping the namespace makes the relay's copy the only one.
+ */
+function withoutUpstreamSessionPairs(cookie: string): string {
+  return cookie
+    .split(';')
+    .map((pair) => pair.trim())
+    .filter((pair) => pair !== '' && !isUpstreamSessionPair(pair))
+    .join('; ')
+}
+
 /** Prefixes the gateway owns and must never relay to dsh. */
 function isOwnedPath(pathname: string): boolean {
   return pathname === '/lan-gateway' || pathname.startsWith('/lan-gateway/')
 }
 
-/** The pathname of a request URL (query string stripped, not decoded). */
+/**
+ * The pathname a request is routed by: the one dsh's router resolves it to
+ * (WHATWG URL parsing, which strips the query and collapses dot segments),
+ * with trailing slashes then removed for the gateway's own surface tests.
+ *
+ * The decision paths below (owned prefix, login, logout) must use this rather
+ * than the raw request target. dsh normalizes before matching, so a raw-string
+ * test disagrees with it on `/foo/../lan-gateway/config` — that is not an owned
+ * path by string prefix, stays in the relay, and lands on the plugin's own
+ * config route once Host has been rewritten to loopback. Forwarding still
+ * relays the raw target: dsh applies the same normalization itself.
+ *
+ * WHATWG parsing does not drop a trailing slash, and neither does dsh's
+ * router, so `/__login/` is not the login page to either of them. The gateway
+ * recognizes its own surfaces there anyway: `/__logout/` must still sign out,
+ * and `/lan-gateway/config/` must be refused rather than relayed into dsh's
+ * single-page fallback. Blocking a trailing-slash spelling of an owned prefix
+ * errs toward refusing, which costs nothing — no upstream route lives under it.
+ */
 function pathOf(url: string): string {
-  const query = url.indexOf('?')
-  return query === -1 ? url : url.slice(0, query)
+  try {
+    return new URL(url, 'http://gateway.invalid').pathname.replace(/\/+$/, '') || '/'
+  } catch {
+    // Unparseable here means unparseable for dsh too; the raw target routes
+    // nowhere and is relayed as-is.
+    return url
+  }
+}
+
+/** A fresh per-session id: 128 random bits, URL-safe. */
+function newSessionId(): string {
+  return randomBytes(16).toString('base64url')
 }
 
 /**
@@ -104,8 +206,14 @@ export class LanGateway {
   private readonly loginLimiter = new RateLimiter(LOGIN_ATTEMPTS_LIMIT, LOGIN_ATTEMPTS_WINDOW_MS)
   private state: GatewayState
   private disposed = false
-  /** Established WebSockets (upgraded client sockets), torn down on session-epoch change. */
-  private readonly activeDuplexes = new Set<Duplex>()
+  /**
+   * Established WebSockets (upgraded client sockets), each keyed by the session
+   * that opened it. A socket outlives the request that authenticated it, so it
+   * has to be closable by session: on an epoch bump every socket dies, and on
+   * sign-out only that session's. The value is undefined for a cookie minted
+   * before per-session ids existed, which only a wholesale revocation reaches.
+   */
+  private readonly activeDuplexes = new Map<Duplex, string | undefined>()
 
   constructor(
     private readonly config: GatewayConfig,
@@ -131,7 +239,14 @@ export class LanGateway {
     this.state = state
   }
 
-  /** Start listening; rejects if the port is already in use. */
+  /**
+   * Start listening on the configured port. The listener is dual-stack: with
+   * no host given, node binds the unspecified IPv6 address `::` — which also
+   * accepts IPv4 clients, arriving as `::ffff:a.b.c.d` for the classifier to
+   * unwrap — when the host has IPv6, and falls back to `0.0.0.0` when it does
+   * not. Binding IPv4 only used to leave every IPv6 client (including `::1`)
+   * unable to reach a gateway that classifies them.
+   */
   async listen(): Promise<void> {
     return new Promise((resolve, reject) => {
       const onError = (err: Error): void => {
@@ -144,10 +259,18 @@ export class LanGateway {
       }
       this.server.once('error', onError)
       this.server.once('listening', onListening)
-      this.server.listen(this.config.gatewayPort, '0.0.0.0')
+      this.server.listen(this.config.gatewayPort)
     })
   }
 
+  /** The address actually bound, for logs and status (never a claim about it). */
+  boundAddress(): string {
+    const address = this.server.address()
+    if (address === null || typeof address === 'string') return `port ${this.config.gatewayPort}`
+    const host = address.family === 'IPv6' ? `[${address.address}]` : address.address
+    return `${host}:${address.port}`
+  }
+
   /** Close the server, drop upgraded sockets, and stop accepting connections. */
   async close(): Promise<void> {
     if (this.disposed) return
@@ -160,14 +283,23 @@ export class LanGateway {
   }
 
   private destroyActiveDuplexes(): void {
-    for (const socket of this.activeDuplexes) {
+    for (const socket of this.activeDuplexes.keys()) {
       socket.destroy()
     }
     this.activeDuplexes.clear()
   }
 
-  private trackDuplex(socket: Duplex): void {
-    this.activeDuplexes.add(socket)
+  /** Close the sockets one session opened, so signing out ends its live streams too. */
+  private destroyDuplexesFor(sid: string): void {
+    for (const [socket, owner] of this.activeDuplexes) {
+      if (owner !== sid) continue
+      this.activeDuplexes.delete(socket)
+      socket.destroy()
+    }
+  }
+
+  private trackDuplex(socket: Duplex, sid: string | undefined): void {
+    this.activeDuplexes.set(socket, sid)
     socket.on('close', () => {
       this.activeDuplexes.delete(socket)
     })
@@ -192,15 +324,27 @@ export class LanGateway {
     return undefined
   }
 
-  /** Whether a request carries a session valid under the current epoch. */
-  private authorized(req: http.IncomingMessage): boolean {
+  /**
+   * The session a request carries, or undefined when it presents none, presents
+   * one that no longer verifies under the current epoch, or presents one whose
+   * id has been signed out.
+   */
+  private session(req: http.IncomingMessage): SessionClaims | undefined {
     const cookie = this.sessionCookie(req)
-    return cookie !== undefined && verifyCookie(
+    if (cookie === undefined) return undefined
+    const claims = verifySession(
       this.state.cookieSecret,
       cookie,
       Date.now(),
       this.state.sessionEpoch,
     )
+    if (claims === undefined) return undefined
+    return isSessionRevoked(this.state, claims.sid) ? undefined : claims
+  }
+
+  /** Whether a request carries a session valid under the current epoch. */
+  private authorized(req: http.IncomingMessage): boolean {
+    return this.session(req) !== undefined
   }
 
   /** Whether this source must present a gateway session (default: everyone). */
@@ -312,7 +456,7 @@ export class LanGateway {
       return
     }
 
-    void readBody(req, DEFAULT_BODY_LIMIT_BYTES, res).then((body) => {
+    void readBody(req, DEFAULT_BODY_LIMIT_BYTES, res).then(async (body) => {
       if (body === undefined) return // response already sent (413/400)
       let password: string | undefined
       try {
@@ -321,23 +465,47 @@ export class LanGateway {
       } catch {
         password = undefined
       }
-      if (password === undefined || !verifyPassword(this.state, password)) {
+      const accepted = password !== undefined && await verifyPassword(this.state, password)
+      if (!accepted) {
         this.serveLoginError(res, 'Incorrect password.')
         return
       }
       const maxAgeSeconds = this.config.cookieMaxAgeDays * 86_400
       const expiresMs = Date.now() + maxAgeSeconds * 1000
-      const cookie = signCookie(this.state.cookieSecret, expiresMs, this.state.sessionEpoch)
+      // Every session gets its own id so signing out can retire this one alone.
+      const cookie = signCookie(
+        this.state.cookieSecret,
+        expiresMs,
+        this.state.sessionEpoch,
+        newSessionId(),
+      )
       res.writeHead(302, {
         location: '/',
         ...this.securityHeaders(),
         'set-cookie': [this.sessionSetCookie(cookie, maxAgeSeconds)],
       })
       res.end()
+    }).catch(() => {
+      // The body reader reports its own failures through the response; this
+      // catches the async verification path so it cannot become an unhandled
+      // rejection.
+      if (!res.headersSent) {
+        res.writeHead(500, this.securityHeaders())
+        res.end('login failed')
+      }
     })
   }
 
-  /** POST /__logout: sign an immediately-expired cookie and bounce to / . */
+  /**
+   * POST /__logout: revoke this session and clear the cookie.
+   *
+   * The session is stateless, so clearing the cookie only stops the browser
+   * that ran the sign-out; a copy of the same value held anywhere else would
+   * keep working until it expired. Revoking the id in the cookie retires that
+   * one session for good, and leaves the account's other sessions — other
+   * devices, other browsers — alone. Bumping the session epoch here would be
+   * the blunter instrument: it signs out every session there is.
+   */
   private handleLogout(req: http.IncomingMessage, res: http.ServerResponse): void {
     if (req.method !== 'POST') {
       res.writeHead(405, { allow: 'POST' })
@@ -350,6 +518,12 @@ export class LanGateway {
       res.end('forbidden')
       return
     }
+    const claims = this.session(req)
+    if (claims?.sid !== undefined) {
+      this.state = revokeSession(this.state, claims.sid, claims.exp)
+      this.config.onStateChange?.(this.state)
+      this.destroyDuplexesFor(claims.sid)
+    }
     res.writeHead(302, {
       location: '/',
       ...this.securityHeaders(),
@@ -371,6 +545,14 @@ export class LanGateway {
       delete headers.connection
       delete headers.upgrade
     }
+    // A caller's own forwarding claims are not ours to relay.
+    for (const name of FORWARDING_HEADERS) delete headers[name]
+    // The relay is the only authority on the upstream session cookie.
+    if (typeof headers.cookie === 'string') {
+      const kept = withoutUpstreamSessionPairs(headers.cookie)
+      if (kept === '') delete headers.cookie
+      else headers.cookie = kept
+    }
     return headers
   }
 
@@ -387,6 +569,31 @@ export class LanGateway {
     return true
   }
 
+  /**
+   * The headers to send back to the client: hop-by-hop headers dropped, and
+   * the upstream session cookie withheld. Upstream's one cookie-minting route
+   * is the launch-token exchange at `/`, so a client that already holds a
+   * gateway session could otherwise post the token through the gateway and
+   * walk away with a durable upstream credential the relay exists to keep on
+   * this side. Cookies from other routes (plugins) still pass through.
+   */
+  private downstreamHeaders(upstream: http.IncomingHttpHeaders): http.OutgoingHttpHeaders {
+    const headers: http.OutgoingHttpHeaders = {}
+    for (const [key, value] of Object.entries(upstream)) {
+      if (value === undefined) continue
+      const lower = key.toLowerCase()
+      if (HOP_BY_HOP_HEADERS.has(lower)) continue
+      if (lower === 'set-cookie') {
+        const list = (Array.isArray(value) ? value : [value])
+          .filter((entry) => !isUpstreamSessionPair(entry.trim()))
+        if (list.length > 0) headers[key] = list
+        continue
+      }
+      headers[key] = value
+    }
+    return headers
+  }
+
   /** Forward an HTTP request to dsh, replaying the shared upstream session. */
   private async relayHttp(req: http.IncomingMessage, res: http.ServerResponse, url: string): Promise<void> {
     const session = this.config.upstreamSession
@@ -407,7 +614,7 @@ export class LanGateway {
       if (attached && session !== undefined && proxyRes.statusCode === 401) {
         session.invalidate()
       }
-      res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers)
+      res.writeHead(proxyRes.statusCode ?? 502, this.downstreamHeaders(proxyRes.headers))
       proxyRes.pipe(res)
     })
     proxyReq.on('error', () => {
@@ -436,7 +643,10 @@ export class LanGateway {
       return
     }
 
-    if (this.requiresLogin(source) && !this.authorized(req)) {
+    // The session is read once: the socket this upgrade ends up holding stays
+    // attributable to it, so signing that session out can close the socket.
+    const claims = this.session(req)
+    if (this.requiresLogin(source) && claims === undefined) {
       refuse(401)
       return
     }
@@ -462,7 +672,7 @@ export class LanGateway {
       headers,
     })
     proxyReq.on('upgrade', (proxyRes, proxySocket, proxyHead) => {
-      this.trackDuplex(socket)
+      this.trackDuplex(socket, claims?.sid)
       // node's http client has already consumed the 101 response headers, so
       // reconstruct them on the client socket before splicing.
       const statusLine = `HTTP/1.1 ${proxyRes.statusCode ?? 101} ${proxyRes.statusMessage ?? 'Switching Protocols'}\r\n`

package/src/index.ts

@@ -4,7 +4,8 @@
  *
  * 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,
+ * own reverse-proxy gateway on the unspecified address — both families, so
+ * IPv6 clients reach it too — that forwards to the loopback dsh port,
  * rewriting Host/Origin so the request reaches the dsh web server as if it came
  * from the loopback authority it names.
  *
@@ -22,8 +23,10 @@
  *   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.
+ *   logout pages). Sessions are revocable: each carries a random id, so signing
+ *   out retires that one session and the WebSockets it opened, and each carries
+ *   a revocation epoch, so a password change or secret rotation kills every
+ *   session at once.
  *
  * Every tunable is also exposed as the `lan-gateway` user-settings namespace
  * (`ctx.settings`), so the official DSH Settings → Plugins page can adjust
@@ -56,6 +59,7 @@ import {
   describeCert,
   loadCustomCert,
   loadOrCreateSelfSigned,
+  loadOrRenewSelfSigned,
   parseSelfSignedHosts,
   regenerateSelfSigned,
   type TlsMaterial,
@@ -113,7 +117,7 @@ export interface GatewayController {
 export interface Config {
   /** Whether the gateway listener is started at boot. Default false (safe). */
   enabled: boolean
-  /** Port to bind on 0.0.0.0. */
+  /** Port to bind on the unspecified address, both address families. */
   gatewayPort: number
   /** Explicit dsh target port; defaults to the live `ctx.webServer.port`. */
   dshTargetPort?: number
@@ -145,7 +149,18 @@ export interface Config {
   tlsKeyPath?: string
   /** Self-signed mode: comma/space separated DNS names and IPs for the SANs. */
   tlsSelfSignedHosts?: string
-  /** Self-signed certificate validity in days (default 825 ≈ 27 months). */
+  /**
+   * Self-signed certificate validity in days (default 825 ≈ 27 months).
+   *
+   * 825 is the ceiling Apple states for TLS server certificates, and the
+   * well-known 398-day limit — which this default is sometimes mistaken for
+   * exceeding — applies only to certificates chaining to a root preinstalled
+   * by the platform: Apple exempts user- and administrator-added roots
+   * outright, and a self-signed certificate is always one of those. Since a
+   * self-signed certificate is either clicked through or trusted by hand,
+   * there is nothing to gain from the shorter window and a re-trust to lose
+   * every time it lapses.
+   */
   tlsCertMaxAgeDays: number
   /**
    * Escape hatch (default false): permit plaintext HTTP. Never derived from
@@ -158,6 +173,14 @@ export interface Config {
    * encrypted-ingress gate) without this listener sending HSTS.
    */
   trustedTerminator?: string
+  /**
+   * Explicit override for the session cookie's `Secure` attribute. Unset =
+   * automatic: Secure when the gateway serves TLS itself or a
+   * `trustedTerminator` is declared. Set `false` when the trusted proxy fronts
+   * a plaintext browser ingress — browsers refuse to store a Secure cookie over
+   * plain HTTP, so every login would bounce straight back to `/__login`.
+   */
+  secureCookies?: boolean
 }
 
 /**
@@ -189,6 +212,7 @@ export const Config: z<Config> = z.object({
   tlsCertMaxAgeDays: z.natural().min(1).max(3650).default(825),
   allowInsecurePlaintext: z.boolean().default(false),
   trustedTerminator: z.string(),
+  secureCookies: z.boolean(),
 })
 
 /** Facts the fail-closed start guard needs to judge a config. */
@@ -227,18 +251,39 @@ export function gatewayStartProblems(cfg: Config, facts: StartFacts): string[] {
   return problems
 }
 
+/**
+ * Resolve the effective `Secure` attribute for the session cookie: an explicit
+ * `secureCookies` always wins; unset falls back to automatic — Secure when the
+ * gateway terminates TLS itself or a trusted terminator is declared. The
+ * override exists for a trusted proxy that authenticates users but speaks plain
+ * HTTP to browsers: `encryptedIngress` is a fair proxy for "a proxy is in front"
+ * but not for "the browser leg is encrypted", and a Secure cookie on a plain
+ * HTTP origin is silently dropped, looping the login.
+ *
+ * Exported for tests.
+ */
+export function resolveSecureCookies(
+  cfg: Pick<Config, 'secureCookies' | 'tlsEnabled' | 'trustedTerminator'>,
+): boolean {
+  // Test for a real boolean, not just `!== undefined`: the settings route
+  // clears a key by posting null and schemastery passes that through rather
+  // than coercing it to undefined, so `null` reaches here on the save path.
+  // Only an explicit true/false overrides the automatic rule.
+  if (typeof cfg.secureCookies === 'boolean') return cfg.secureCookies
+  return cfg.tlsEnabled || cfg.trustedTerminator !== undefined
+}
+
 /** Resolve the TLS material for a config, or undefined when TLS is off. */
-function resolveTls(cfg: Config): TlsMaterial | undefined {
+function resolveTls(cfg: Config): { material: TlsMaterial; renewed: boolean } | undefined {
   if (!cfg.tlsEnabled) return undefined
   if (cfg.tlsMode === 'custom') {
-    return loadCustomCert(cfg.tlsCertPath ?? '', cfg.tlsKeyPath ?? '')
+    return { material: loadCustomCert(cfg.tlsCertPath ?? '', cfg.tlsKeyPath ?? ''), renewed: false }
   }
   const hosts = parseSelfSignedHosts(cfg.tlsSelfSignedHosts)
   if (hosts.length === 0) {
     throw new Error('tlsSelfSignedHosts must name at least one host (DNS name or IP)')
   }
-  const { material } = loadOrCreateSelfSigned({ hosts, days: cfg.tlsCertMaxAgeDays })
-  return material
+  return loadOrRenewSelfSigned({ hosts, days: cfg.tlsCertMaxAgeDays })
 }
 
 /**
@@ -265,6 +310,7 @@ function listenerKey(cfg: Config, relayAvailable: boolean): string {
     cfg.tlsCertMaxAgeDays,
     cfg.allowInsecurePlaintext,
     cfg.trustedTerminator,
+    cfg.secureCookies,
     relayAvailable,
   ])
 }
@@ -351,8 +397,10 @@ export function apply(ctx: Context, config: Config): void {
       throw new Error(`dsh-lan-gateway: cannot start — ${problems.join(' ')}`)
     }
     const dshPort = cfg.dshTargetPort ?? ctx.webServer.port
-    const tls = resolveTls(cfg)
+    const resolved = resolveTls(cfg)
+    const tls = resolved?.material
     const encryptedIngress = cfg.tlsEnabled || cfg.trustedTerminator !== undefined
+    const secureCookies = resolveSecureCookies(cfg)
     const next = new LanGateway({
       gatewayPort: cfg.gatewayPort,
       dshPort,
@@ -360,18 +408,31 @@ export function apply(ctx: Context, config: Config): void {
       lanPasswordless: cfg.lanPasswordless,
       cookieMaxAgeDays: cfg.cookieMaxAgeDays,
       cookieName: cfg.cookieName,
-      secureCookies: encryptedIngress,
+      secureCookies,
       ...(tls !== undefined ? { tls } : {}),
       ...(makeRelay !== undefined ? { upstreamSession: makeRelay(dshPort) } : {}),
+      onStateChange: (updated) => {
+        // The gateway retired a session itself (sign-out). Keep the plugin's
+        // copy and the state file in step, or a restart would resurrect a
+        // session the user signed out of.
+        state = updated
+        saveState(state)
+      },
     }, state)
     await next.listen()
     gateway = next
     startedWith = listenerKey(cfg, makeRelay !== undefined)
     ctx.logger.info(
-      `dsh-lan-gateway: listening on 0.0.0.0:${cfg.gatewayPort}${tls !== undefined ? ' (TLS)' : ''}`
+      `dsh-lan-gateway: listening on ${next.boundAddress()}${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]'}`,
     )
+    if (resolved?.renewed === true) {
+      ctx.logger.warn(
+        'dsh-lan-gateway: the self-signed certificate had expired and was replaced with a fresh one '
+        + '— clients that had trusted the old certificate must trust the new one.',
+      )
+    }
   }
 
   const stopGateway = async (): Promise<void> => {
@@ -435,9 +496,13 @@ export function apply(ctx: Context, config: Config): void {
   // gateway forwards without a relay, and lanPasswordless stays refused.
   ctx.inject(['connection'], (ccx) => {
     upstreamSessionAvailable = true
+    ctx.logger.info('dsh-lan-gateway: connection service attached; upstream session relay enabled')
     makeRelay = (dshPort) => new UpstreamSessionRelay({
       port: dshPort,
       authenticatedUrl: () => ccx.connection.authenticatedUrl(`http://127.0.0.1:${dshPort}`),
+      // The relay never throws, so a failing exchange is otherwise invisible
+      // and looks exactly like a base with no browser sessions.
+      log: (message) => ctx.logger.info(`dsh-lan-gateway relay: ${message}`),
     })
     // A listener that started before the connection service appeared must
     // restart so it picks up the relay (and the now-correct fail-closed facts).
@@ -553,14 +618,15 @@ export function apply(ctx: Context, config: Config): void {
       return {
         ok: true,
         message:
-          `LAN gateway: ${gateway !== undefined ? `LISTENING on 0.0.0.0:${cfg.gatewayPort}` : 'stopped'}`
+          `LAN gateway: ${gateway !== undefined ? `LISTENING on ${gateway.boundAddress()}` : 'stopped'}`
           + `\n- dsh target: 127.0.0.1:${dshPort}`
           + `\n- password: ${state.password !== undefined ? 'set' : 'NOT SET'}`
           + `\n- login required for all sources: true${cfg.lanPasswordless ? ' (LAN/loopback exempt via lanPasswordless)' : ''}`
           + `\n- session epoch: ${state.sessionEpoch}`
+          + `\n- signed-out sessions still held: ${Object.keys(state.revokedSessions ?? {}).length} (each drops when its own cookie would have expired)`
           + `\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- ingress: ${cfg.tlsEnabled ? `TLS (${tlsStatusLine(cfg)})` : cfg.trustedTerminator !== undefined ? `trusted proxy (${cfg.trustedTerminator}, ${resolveSecureCookies(cfg) ? 'TLS' : 'plaintext'} browser ingress)` : encrypted ? 'encrypted' : cfg.allowInsecurePlaintext ? 'PLAINTEXT (explicit allowInsecurePlaintext)' : 'plaintext — will not start'}`
+          + `\n- session cookie: ${cfg.cookieName}, ${cfg.cookieMaxAgeDays}d, ${resolveSecureCookies(cfg) ? 'Secure' : 'no Secure attribute (plaintext browser ingress)'}`
           + (manualOverride !== undefined
             ? `\n- manual override: ${manualOverride ? 'enabled' : 'disabled'}`
             : '')
@@ -571,7 +637,7 @@ export function apply(ctx: Context, config: Config): void {
       manualOverride = true
       await syncGateway('tool enable')
       return gateway !== undefined
-        ? { ok: true, message: `Gateway enabled: listening on 0.0.0.0:${effective().gatewayPort}` }
+        ? { ok: true, message: `Gateway enabled: listening on ${gateway.boundAddress()}` }
         : { ok: false, message: `Failed to enable gateway: ${lastError ?? 'unknown error'}` }
     },
     async disable(): Promise<ToolResult> {