@riceawa/dsh-lan-gateway 0.5.3 → 0.5.4

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
@@ -259,17 +274,16 @@ export function resolveSecureCookies(
 }
 
 /** 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 })
 }
 
 /**
@@ -383,7 +397,8 @@ 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({
@@ -396,15 +411,28 @@ export function apply(ctx: Context, config: Config): void {
       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> => {
@@ -590,11 +618,12 @@ 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 ? `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)'}`
@@ -608,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> {

package/src/state.ts

@@ -9,7 +9,7 @@
 
 import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { randomBytes, scryptSync, timingSafeEqual } from 'node:crypto'
+import { randomBytes, scrypt, scryptSync, timingSafeEqual } from 'node:crypto'
 import { homedir } from 'node:os'
 
 /** The state directory: `~/.dsh/lan-gateway`. */
@@ -37,17 +37,43 @@ export interface GatewayState {
    * immediately. Old state files without the field load as epoch 0.
    */
   sessionEpoch: number
+  /**
+   * Revoked session ids, each mapped to the epoch millis at which that
+   * session's own cookie expires. Signing out revokes the single id the
+   * browser presented, so the account's other sessions keep working, and it
+   * has to be persisted: the cookie it names stays unforgeable until it
+   * expires, and a restart must not resurrect it. Entries lapse once the
+   * cookie they name could no longer be presented anyway, which bounds the
+   * list by the sessions that are still live somewhere. Absent on state
+   * written before 0.5.4.
+   */
+  revokedSessions?: Record<string, number>
 }
 
 const STATE_FILENAME = 'state.json'
 
-/** Whether a password is present and passes scrypt verification. */
-export function verifyPassword(state: GatewayState, password: string): boolean {
+/** Promise wrapper around the threaded `scrypt`, which runs off the main loop. */
+function deriveKey(password: string, salt: Buffer, keylen: number): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    scrypt(password, salt, keylen, (error, derived) => {
+      if (error !== null) reject(error)
+      else resolve(derived)
+    })
+  })
+}
+
+/**
+ * Whether a password is present and passes scrypt verification. Asynchronous
+ * on purpose: `scryptSync` occupies the event loop for tens of milliseconds
+ * per attempt, and that loop is shared with the dsh process the gateway is
+ * forwarding to.
+ */
+export async function verifyPassword(state: GatewayState, password: string): Promise<boolean> {
   if (state.password === undefined) return false
   const { hash, salt } = state.password
   try {
     const expected = Buffer.from(hash, 'hex')
-    const actual = scryptSync(password, Buffer.from(salt, 'hex'), expected.length)
+    const actual = await deriveKey(password, Buffer.from(salt, 'hex'), expected.length)
     return expected.length === actual.length && timingSafeEqual(expected, actual)
   } catch {
     return false
@@ -60,10 +86,14 @@ export function verifyPassword(state: GatewayState, password: string): boolean {
  * 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: base.cookieSecret, sessionEpoch: base.sessionEpoch }
+  // The new epoch invalidates every cookie on its own account, so the list of
+  // individually revoked sessions has nothing left to say: drop it rather than
+  // carry entries that can never match again.
+  const base: GatewayState = {
+    cookieSecret: state.cookieSecret,
+    sessionEpoch: state.sessionEpoch + 1,
   }
+  if (password === undefined) return base
   const salt = randomBytes(16)
   const hash = scryptSync(password, salt, 64)
   return {
@@ -72,10 +102,47 @@ export function setPassword(state: GatewayState, password: string | undefined):
   }
 }
 
+/**
+ * Record a session id as revoked.
+ * @param expiresMs - the revoked cookie's own expiry. Past it the cookie is
+ *   rejected on its own account, so the entry is no longer needed; dropping
+ *   expired entries here is what keeps the list bounded.
+ */
+export function revokeSession(state: GatewayState, sid: string, expiresMs: number): GatewayState {
+  const now = Date.now()
+  const revoked: Record<string, number> = {}
+  for (const [id, exp] of Object.entries(state.revokedSessions ?? {})) {
+    if (exp > now) revoked[id] = exp
+  }
+  revoked[sid] = expiresMs
+  return { ...state, revokedSessions: revoked }
+}
+
+/** Whether `sid` names a session that has been signed out. */
+export function isSessionRevoked(state: GatewayState, sid: string | undefined): boolean {
+  if (sid === undefined) return false
+  return Object.hasOwn(state.revokedSessions ?? {}, sid)
+}
+
 function defaultState(): GatewayState {
   return { cookieSecret: randomBytes(32).toString('base64'), sessionEpoch: 0 }
 }
 
+/** Keep the still-live entries of a persisted revocation list, or undefined. */
+function parseRevokedSessions(raw: unknown): Record<string, number> | undefined {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return undefined
+  const now = Date.now()
+  const out: Record<string, number> = {}
+  let anyLive = false
+  for (const [sid, exp] of Object.entries(raw)) {
+    if (typeof exp === 'number' && Number.isFinite(exp) && exp > now) {
+      out[sid] = exp
+      anyLive = true
+    }
+  }
+  return anyLive ? out : undefined
+}
+
 /** Load state; on first run (or a corrupt file) generate a fresh secret. */
 export function loadState(home: string = homedir()): GatewayState {
   const dir = stateDir(home)
@@ -91,6 +158,9 @@ export function loadState(home: string = homedir()): GatewayState {
         : 0
       const base: GatewayState = { cookieSecret: parsed.cookieSecret, sessionEpoch }
       if (parsed.password !== undefined) base.password = parsed.password
+      // Anything the file lists past its own expiry has lapsed on its own.
+      const revoked = parseRevokedSessions(parsed.revokedSessions)
+      if (revoked !== undefined) base.revokedSessions = revoked
       return base
     }
     return defaultState()

package/src/tls.ts

@@ -71,6 +71,27 @@ export function loadOrCreateSelfSigned(
   return { material, created: true }
 }
 
+/**
+ * Load the self-signed material a listener should serve: generate it on first
+ * use, reuse the persisted pair otherwise, and replace a persisted certificate
+ * whose validity has already lapsed.
+ *
+ * Nothing renews a self-signed certificate in place, and a browser refuses a
+ * lapsed one outright, so without this a certificate that ran out would keep
+ * being served until an operator happened to read the expiry date out of
+ * `status` and act on it. Renewing mints a fresh key, so a client that had
+ * trusted the old certificate has to trust the new one — but that is the case
+ * either way, the old one having lapsed.
+ */
+export function loadOrRenewSelfSigned(
+  opts: SelfSignedTlsOptions,
+  home: string = homedir(),
+): { material: TlsMaterial; renewed: boolean } {
+  const { material, created } = loadOrCreateSelfSigned(opts, home)
+  if (created || !isCertExpired(material.cert)) return { material, renewed: false }
+  return { material: regenerateSelfSigned(opts, home), renewed: true }
+}
+
 /**
  * Force-regenerate the self-signed certificate (new key + cert), replacing
  * the persisted files. Used by `lan_gateway tls-regenerate`.
@@ -146,6 +167,18 @@ export interface CertInfo {
   san?: string
 }
 
+/**
+ * Whether a PEM certificate's validity window has already closed. A lapsed
+ * certificate is a hard failure browsers will not let the user proceed past,
+ * so the listener replaces one rather than keep serving it.
+ */
+export function isCertExpired(certPem: string, now: number = Date.now()): boolean {
+  const expiresAt = Date.parse(new X509Certificate(certPem).validTo)
+  // An unparseable date reads as "not expired": serving the certificate we were
+  // handed beats discarding it over a date-parsing quirk.
+  return Number.isFinite(expiresAt) && expiresAt <= now
+}
+
 /** Describe a PEM certificate (throws on malformed input). */
 export function describeCert(certPem: string): CertInfo {
   const cert = new X509Certificate(certPem)

package/src/upstream-session.ts

@@ -73,6 +73,19 @@ function nameValueOnly(setCookie: string): string {
   return (semi === -1 ? setCookie : setCookie.slice(0, semi)).trim()
 }
 
+/**
+ * The pathname of a URL, for logging. Never the whole URL: the authenticated
+ * URL carries the launch token as a query parameter, and that token is a
+ * bearer credential for the upstream harness.
+ */
+function pathOf(url: string): string {
+  try {
+    return new URL(url).pathname
+  } catch {
+    return '<unparseable>'
+  }
+}
+
 /** The cookie name of a `Set-Cookie` string (`''` when it is malformed). */
 function cookieNameOf(setCookie: string): string {
   const eq = setCookie.indexOf('=')
@@ -121,7 +134,7 @@ function exchange(
     try {
       target = new URL(url)
     } catch {
-      log(`exchange: unparseable authenticatedUrl ${url}`)
+      log('exchange: authenticatedUrl is not parseable')
       resolve(undefined)
       return
     }
@@ -228,7 +241,9 @@ export class UpstreamSessionRelay implements UpstreamSession {
       this.log('authenticatedUrl() returned undefined; keeping current session')
       return this.held?.header
     }
-    this.log(`acquiring session from ${url}`)
+    // Log only the path: the URL carries the launch token in its query string,
+    // and that token is a bearer credential for the upstream harness.
+    this.log(`acquiring session from ${pathOf(url)}`)
     const result = await exchange(url, this.authority, this.port, this.log)
     if (result !== undefined) {
       this.held = result