@riceawa/dsh-lan-gateway 0.5.3 → 0.5.5

package/lib/index.js

@@ -1,4 +1,4 @@
-import { X509Certificate, createHmac, createSign, generateKeyPairSync, randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
+import { X509Certificate, createHmac, createSign, generateKeyPairSync, randomBytes, scrypt, timingSafeEqual } from "node:crypto";
 import z from "@deepseek-ai/schemastery";
 import http from "node:http";
 import https from "node:https";
@@ -56,6 +56,13 @@ function normalizeAddress(raw) {
 }
 /**
 * Classify a source address string into one of the three trust tiers.
+*
+* The input is a *socket* address — `req.socket.remoteAddress`, unwrapped from
+* its `::ffff:` mapping — which is a different domain from the URL hostname
+* `isLoopbackHost` in `request-policy.ts` judges. The two agree on the common
+* inputs but are not interchangeable: this one never sees `[::1]`, and that one
+* never sees a mapped form. Both spans are documented where each lives.
+*
 * @param remoteAddress - the raw value of `req.socket.remoteAddress`.
 * @param lanCidrs - CIDR strings treated as trusted LAN space (IPv4).
 * @returns the classification. IPv4-mapped IPv6 addresses are unwrapped.
@@ -73,9 +80,19 @@ function classifySource(remoteAddress, lanCidrs = DEFAULT_LAN_CIDR_STRINGS) {
 		return "internet";
 	}
 	if (address === "::1") return "loopback";
-	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) {
+	const match = /^([0-9a-fA-F]{1,4}):/.exec(address);
+	if (match === null) return false;
+	return (Number.parseInt(match[1], 16) & 65472) === 65152;
+}
 /** Encode a byte buffer as URL-safe base64 without padding. */
 function base64url(input) {
 	return input.toString("base64url");
@@ -88,24 +105,29 @@ function base64url(input) {
 *   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.
 */
-function signCookie(secret, expiresMs, epoch = 0) {
-	const payload = base64url(Buffer.from(JSON.stringify({
+function signCookie(secret, expiresMs, epoch = 0, sid) {
+	const claims = sid === void 0 ? {
 		exp: expiresMs,
 		epoch
-	})));
+	} : {
+		exp: expiresMs,
+		epoch,
+		sid
+	};
+	const payload = base64url(Buffer.from(JSON.stringify(claims)));
 	return `${payload}.${createHmac("sha256", secret).update(payload).digest("base64url")}`;
 }
 /**
-* 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.
 */
-function verifyCookie(secret, value, now, epoch = 0) {
-	if (value === void 0) return false;
+function verifySession(secret, value, now, epoch = 0) {
+	if (value === void 0) return void 0;
 	const dot = value.indexOf(".");
-	if (dot === -1) return false;
+	if (dot === -1) return void 0;
 	const payload = value.slice(0, dot);
 	const sig = value.slice(dot + 1);
 	const expected = createHmac("sha256", secret).update(payload).digest();
@@ -113,16 +135,22 @@ function verifyCookie(secret, value, now, epoch = 0) {
 	try {
 		actual = Buffer.from(sig, "base64url");
 	} catch {
-		return false;
+		return;
 	}
-	if (expected.length !== actual.length) return false;
-	if (!timingSafeEqual(expected, actual)) return false;
+	if (expected.length !== actual.length) return void 0;
+	if (!timingSafeEqual(expected, actual)) return void 0;
 	try {
 		const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
-		if (typeof decoded.exp !== "number" || decoded.exp <= now) return false;
-		return (typeof decoded.epoch === "number" ? decoded.epoch : 0) === epoch;
+		if (typeof decoded.exp !== "number" || decoded.exp <= now) return void 0;
+		const cookieEpoch = typeof decoded.epoch === "number" ? decoded.epoch : 0;
+		if (cookieEpoch !== epoch) return void 0;
+		return {
+			exp: decoded.exp,
+			epoch: cookieEpoch,
+			...typeof decoded.sid === "string" ? { sid: decoded.sid } : {}
+		};
 	} catch {
-		return false;
+		return;
 	}
 }
 /**
@@ -143,10 +171,18 @@ function originMatchesHost(origin, host) {
 	}
 }
 /** A token bucket limiter keyed by source address. */
-var RateLimiter = class {
+var RateLimiter = class RateLimiter {
 	maxTokens;
 	windowMs;
+	/**
+	* 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.
+	*/
+	static MAX_BUCKETS = 1e4;
 	buckets = /* @__PURE__ */ new Map();
+	/** Epoch millis at which the next opportunistic sweep is due. */
+	nextPruneAt = 0;
 	constructor(maxTokens, windowMs) {
 		this.maxTokens = maxTokens;
 		this.windowMs = windowMs;
@@ -158,26 +194,114 @@ var RateLimiter = class {
 	*/
 	allow(key) {
 		const now = Date.now();
-		const bucket = this.buckets.get(key);
-		if (bucket === void 0 || bucket.resetAt <= now) {
-			this.buckets.set(key, {
-				tokens: this.maxTokens - 1,
-				resetAt: now + this.windowMs
-			});
-			return true;
+		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 !== void 0 && existing.resetAt > now) {
+			if (existing.tokens <= 0) return false;
+			existing.tokens -= 1;
 			return true;
 		}
-		return false;
+		if (existing === void 0 && 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 = Date.now()) {
 		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. */
+	evictSoonestToExpire() {
+		const target = Math.floor(RateLimiter.MAX_BUCKETS * .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);
+	}
 };
 //#endregion
+//#region src/config-fields.ts
+/**
+* The editable settings, in display order. Adding a config key means adding it
+* here (the host whitelist and the card's controls both follow), to the
+* `Config` schema in `index.ts`, and to `listenerKey` when it changes listener
+* behavior.
+*/
+const FIELDS = [
+	{
+		field: "enabled",
+		kind: "boolean"
+	},
+	{
+		field: "gatewayPort",
+		kind: "number"
+	},
+	{
+		field: "dshTargetPort",
+		kind: "number",
+		optional: true
+	},
+	{
+		field: "lanCidrs",
+		kind: "cidrs"
+	},
+	{
+		field: "lanPasswordless",
+		kind: "boolean"
+	},
+	{
+		field: "cookieMaxAgeDays",
+		kind: "number"
+	},
+	{
+		field: "tlsEnabled",
+		kind: "boolean"
+	},
+	{
+		field: "tlsMode",
+		kind: "select",
+		options: ["self-signed", "custom"]
+	},
+	{
+		field: "tlsSelfSignedHosts",
+		kind: "text"
+	},
+	{
+		field: "tlsCertPath",
+		kind: "text",
+		optional: true
+	},
+	{
+		field: "tlsKeyPath",
+		kind: "text",
+		optional: true
+	},
+	{
+		field: "tlsCertMaxAgeDays",
+		kind: "number"
+	},
+	{
+		field: "allowInsecurePlaintext",
+		kind: "boolean"
+	},
+	{
+		field: "trustedTerminator",
+		kind: "text",
+		optional: true
+	},
+	{
+		field: "secureCookies",
+		kind: "tristate"
+	}
+];
+/** Every settings key the config route accepts; anything else is ignored. */
+const CONFIG_FIELD_KEYS = new Set(FIELDS.map((def) => def.field));
+/** Keys an empty submitted value clears back to the composition layer. */
+const OPTIONAL_CONFIG_KEYS = new Set(FIELDS.filter((def) => def.optional === true).map((def) => def.field));
+//#endregion
 //#region src/login.ts
 /** Path the gateway owns and never forwards. */
 const LOGIN_PATH = "/__login";
@@ -268,6 +392,450 @@ function readBody(req, maxBytes, res) {
 	});
 }
 //#endregion
+//#region src/upstream-session.ts
+/**
+* Shared upstream session relay for session-capable dsh bases (>= 0.1.2).
+*
+* When dsh added browser-session authentication it stopped trusting a loopback
+* Host header alone: every `/api` request (and the remote WebSocket mux) must
+* now present a signed cookie bound to the authority it names
+* (`dsh-auth-<sha256(authority)>`), minted at the index route by exchanging the
+* process launch token. A reverse proxy that rewrites Host to loopback — which
+* is what this gateway does — therefore gets a 401 no matter how the Host is
+* forged. The gateway cannot mint that cookie itself (the signing secret lives
+* in dsh's credential provider), so it does exactly what a browser does: on the
+* loopback transport it visits the launch-token URL, keeps the Set-Cookie it
+* earns, and replays that one shared session on every request it forwards.
+*
+* Semantics match the pre-existing "single password = single operator" model:
+* whoever passes the gateway's own login rides this one upstream session. It is
+* not multi-user authorization, and upstream (which holds the secret) remains
+* the actual authority over what the session may do.
+*
+* The relay is a no-op on a base without browser sessions: acquisition fails
+* and `cookie()` returns undefined, so the gateway simply forwards without a
+* session cookie exactly as it did against an older dsh.
+*
+* @module @riceawa/dsh-lan-gateway/upstream-session
+*/
+/** The session-cookie name prefix upstream signs (`dsh-auth-<b64url(sha256)>`). */
+const UPSTREAM_COOKIE_PREFIX = "dsh-auth-";
+/** Split `name=value; Path=/; …` into the `name=value` request-Cookie fragment. */
+function nameValueOnly(setCookie) {
+	const semi = setCookie.indexOf(";");
+	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$1(url) {
+	try {
+		return new URL(url).pathname;
+	} catch {
+		return "<unparseable>";
+	}
+}
+/** The cookie name of a `Set-Cookie` string (`''` when it is malformed). */
+function cookieNameOf(setCookie) {
+	const eq = setCookie.indexOf("=");
+	return eq === -1 ? "" : setCookie.slice(0, eq).trim();
+}
+/**
+* Whether one `name=value` fragment of a request `Cookie` header names the
+* upstream session namespace, and so must be dropped before the relay's own
+* copy is appended. This is the *filter* rule: it matches the whole reserved
+* namespace, name only, whether or not the pair is a well-formed session.
+*/
+function isUpstreamCookiePair(pair) {
+	return pair.trim().startsWith(UPSTREAM_COOKIE_PREFIX);
+}
+/**
+* Whether a `Set-Cookie` string is the upstream browser-session cookie. The
+* name upstream mints is `dsh-auth-<base64url(sha256(authority))>`: the prefix
+* is followed by the authority hash, never by `=` itself, so the test is a
+* prefix plus at least one character — matching on `dsh-auth-=` finds nothing
+* and silently relays every request anonymously.
+*
+* This is the *accept* rule, and it is stricter than {@link isUpstreamCookiePair}
+* on purpose: filtering drops a whole namespace the gateway owns, whereas
+* accepting a session has to recognize the one cookie upstream actually mints.
+* Both live here because this module owns the protocol fact; a consumer that
+* re-derives it is how the two rules drifted apart before.
+*/
+function isUpstreamSessionCookie(setCookie) {
+	const name = cookieNameOf(setCookie);
+	return name.startsWith(UPSTREAM_COOKIE_PREFIX) && name.length > 9;
+}
+/** Pull the Max-Age attribute (seconds) out of a Set-Cookie string, if any. */
+function maxAgeSeconds(setCookie) {
+	const match = /\bMax-Age=(\d+)\b/i.exec(setCookie);
+	return match === null ? void 0 : Number(match[1]);
+}
+/**
+* Perform the token exchange over loopback: GET the launch-token URL with the
+* upstream authority as Host, read the Set-Cookie the index route mints, and
+* return its `name=value` plus expiry (or undefined when the exchange failed
+* or no session cookie came back — e.g. an older base without browser
+* sessions).
+*/
+function exchange(url, authority, port, log) {
+	return new Promise((resolve) => {
+		let target;
+		try {
+			target = new URL(url);
+		} catch {
+			log("exchange: authenticatedUrl is not parseable");
+			resolve(void 0);
+			return;
+		}
+		const request = http.request({
+			host: "127.0.0.1",
+			port,
+			method: "GET",
+			path: `${target.pathname}${target.search}`,
+			headers: {
+				host: authority,
+				accept: "text/html"
+			}
+		}, (response) => {
+			const setCookies = response.headers["set-cookie"];
+			response.resume();
+			if (setCookies === void 0) {
+				log(`exchange ${target.pathname} -> ${response.statusCode} (no set-cookie)`);
+				resolve(void 0);
+				return;
+			}
+			const all = Array.isArray(setCookies) ? setCookies : [setCookies];
+			const raw = all.find(isUpstreamSessionCookie);
+			if (raw === void 0) {
+				const names = all.map(cookieNameOf).filter((name) => name !== "");
+				log(`exchange ${target.pathname} -> ${response.statusCode} (no ${UPSTREAM_COOKIE_PREFIX}* cookie; got: ${names.join(", ") || "none"})`);
+				resolve(void 0);
+				return;
+			}
+			const header = nameValueOnly(raw);
+			const maxAge = maxAgeSeconds(raw);
+			log(`exchange ${target.pathname} -> ${response.statusCode} (got ${cookieNameOf(raw)}, maxAge=${maxAge ?? "n/a"})`);
+			resolve({
+				header,
+				expiresAt: Date.now() + (maxAge ?? 0) * 1e3
+			});
+		});
+		request.on("error", (error) => {
+			log(`exchange error: ${error.message}`);
+			resolve(void 0);
+		});
+		request.setTimeout(5e3, () => {
+			log("exchange timeout (5s)");
+			request.destroy(/* @__PURE__ */ new Error("upstream-session exchange timeout"));
+		});
+		request.end();
+	});
+}
+/**
+* A cached {@link UpstreamSession} acquired through the launch-token exchange.
+* Acquisition runs at most once concurrently and the result is cached until it
+* nears expiry or {@link invalidate} is called.
+*/
+var UpstreamSessionRelay = class {
+	port;
+	authority;
+	authenticatedUrl;
+	log;
+	held;
+	inflight;
+	constructor(options) {
+		this.port = options.port;
+		this.authority = options.authority ?? `127.0.0.1:${options.port}`;
+		this.authenticatedUrl = options.authenticatedUrl;
+		this.log = options.log ?? (() => {});
+	}
+	/** Whether the held session is still comfortably inside its lifetime. */
+	fresh() {
+		const held = this.held;
+		if (held === void 0) return false;
+		return Date.now() < held.expiresAt - 6e4;
+	}
+	invalidate() {
+		if (this.held !== void 0) this.log("invalidating held session (upstream rejected it)");
+		this.held = void 0;
+	}
+	async cookie() {
+		if (this.fresh()) return this.held?.header;
+		return this.acquire();
+	}
+	acquire() {
+		if (this.inflight !== void 0) return this.inflight;
+		const pending = this.doExchange().finally(() => {
+			this.inflight = void 0;
+		});
+		this.inflight = pending;
+		return pending;
+	}
+	async doExchange() {
+		const url = this.authenticatedUrl();
+		if (url === void 0) {
+			this.log("authenticatedUrl() returned undefined; keeping current session");
+			return this.held?.header;
+		}
+		this.log(`acquiring session from ${pathOf$1(url)}`);
+		const result = await exchange(url, this.authority, this.port, this.log);
+		if (result !== void 0) {
+			this.held = result;
+			this.log("session acquired and cached");
+		} else this.log("exchange failed; keeping current session");
+		return this.held?.header;
+	}
+};
+//#endregion
+//#region src/request-policy.ts
+/** Methods a browser never attaches a CSRF-meaningful body to; safe without an Origin. */
+const READ_ONLY_METHODS = /* @__PURE__ */ new Set([
+	"GET",
+	"HEAD",
+	"OPTIONS"
+]);
+/**
+* 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 = /* @__PURE__ */ new Set([
+	"connection",
+	"keep-alive",
+	"proxy-authenticate",
+	"proxy-authorization",
+	"proxy-connection",
+	"te",
+	"trailer",
+	"transfer-encoding",
+	"upgrade"
+]);
+/**
+* Hop-by-hop headers a successful upgrade must still carry: 101 is exactly the
+* exchange that negotiates Connection/Upgrade, so they survive there and
+* nowhere else.
+*/
+const UPGRADE_HANDSHAKE_HEADERS = /* @__PURE__ */ new Set(["connection", "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"
+];
+/** Prefixes the gateway owns and must never relay to dsh. */
+function isOwnedPath(pathname) {
+	return pathname === "/lan-gateway" || pathname.startsWith("/lan-gateway/");
+}
+/**
+* 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) {
+	try {
+		return new URL(url, "http://gateway.invalid").pathname.replace(/\/+$/, "") || "/";
+	} catch {
+		return url;
+	}
+}
+/**
+* Whether `hostname` is loopback (127/8, localhost, ::1).
+*
+* This validates a URL *hostname* — the loopback fence on the gateway's own
+* config route, where the input is the browser's Host header — so it accepts
+* the spellings a URL parser produces, `[::1]` included. `classifySource` in
+* `auth.ts` answers a different question about a different input (a socket
+* address, unwrapped from its `::ffff:` mapping, and including LAN space); the
+* two are related but not interchangeable, and neither should be rewritten in
+* terms of the other without moving its input domain too.
+*/
+function isLoopbackHost(hostname) {
+	if (hostname === "localhost" || hostname === "[::1]" || hostname === "::1") return true;
+	const parts = hostname.split(".");
+	return parts.length === 4 && parts[0] === "127" && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
+}
+/** Whether this source must present a gateway session (default: everyone). */
+function requiresLogin(source, lanPasswordless) {
+	return !(lanPasswordless && source !== "internet");
+}
+/** Parse the session cookie out of a Cookie header. */
+function sessionCookie(headers, cookieName) {
+	const header = headers.cookie;
+	if (typeof header !== "string") return void 0;
+	for (const part of header.split(";")) {
+		const trimmed = part.trim();
+		if (trimmed.startsWith(`${cookieName}=`)) return trimmed.slice(cookieName.length + 1);
+	}
+}
+/**
+* The cross-site test shared by every gateway-owned entry point, applied before
+* any Host/Origin rewriting: an explicit cross-site fetch, or an Origin that
+* does not name the authority the browser actually used.
+*
+* Only claims a cross-site page cannot suppress are read, which is what makes
+* this usable on the login POST too (see {@link loginOriginAllowed}).
+*/
+function isCrossSiteRequest(headers) {
+	if (headers["sec-fetch-site"] === "cross-site") return true;
+	const origin = headers.origin;
+	if (origin !== void 0 && !originMatchesHost(origin, headers.host)) return true;
+	return false;
+}
+/**
+* The gateway's own cross-site gate, shared by HTTP and WebSocket upgrades and
+* applied before any Host/Origin rewriting. Browsers attach Origin to
+* state-changing requests and to every WebSocket handshake; reads without an
+* Origin (navigations, non-browser clients holding a session) stay allowed.
+*/
+function sameSiteAllowed(req, upgrade) {
+	if (isCrossSiteRequest(req.headers)) return false;
+	const origin = req.headers.origin;
+	if (upgrade) return origin !== void 0;
+	if (!READ_ONLY_METHODS.has(req.method ?? "GET")) return origin !== void 0;
+	return true;
+}
+/**
+* The fence on the login POST. Issuing a session is as much a state change as
+* retiring one — and a cross-site form post burns the victim's source address
+* through the login rate limiter — so the login route runs the same cross-site
+* test as everything else.
+*
+* It deliberately stops short of {@link sameSiteAllowed}'s "a state-changing
+* request must carry an Origin" rule: a browser always sends an Origin on a
+* form POST, but curl, the dsh CLI and other non-browser clients legitimately
+* do not, and requiring one would lock them out of signing in. What remains is
+* what a cross-site page cannot forge or strip: `sec-fetch-site`, and an Origin
+* that disagrees with the Host the request names.
+*/
+function loginOriginAllowed(headers) {
+	return !isCrossSiteRequest(headers);
+}
+/**
+* Drop every `dsh-auth-*` pair from a Cookie header, returning the remainder
+* (possibly '').
+*
+* The relay's session is appended 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.
+*
+* This filters the namespace; `isUpstreamSessionCookie` decides which cookie may
+* be *accepted* from upstream. The two are deliberately different rules.
+*/
+function withoutUpstreamSessionPairs(cookie) {
+	return cookie.split(";").map((pair) => pair.trim()).filter((pair) => pair !== "" && !isUpstreamCookiePair(pair)).join("; ");
+}
+/**
+* Build the outbound headers for one relayed request: rewrite Host/Origin to
+* the loopback upstream, drop hop-by-hop and caller-supplied forwarding
+* headers, clear the upstream cookie namespace the relay owns, and attach the
+* relayed session.
+*/
+function upstreamRequestHeaders(headers, options) {
+	const out = { ...headers };
+	out.host = `127.0.0.1:${options.dshPort}`;
+	if (typeof out.origin === "string") out.origin = `http://127.0.0.1:${options.dshPort}`;
+	delete out["proxy-connection"];
+	if (!options.keepUpgrade) {
+		delete out.connection;
+		delete out.upgrade;
+	}
+	for (const name of FORWARDING_HEADERS) delete out[name];
+	if (typeof out.cookie === "string") {
+		const kept = withoutUpstreamSessionPairs(out.cookie);
+		if (kept === "") delete out.cookie;
+		else out.cookie = kept;
+	}
+	const relayed = options.upstreamCookie;
+	if (relayed !== void 0 && relayed !== "") {
+		const existing = out.cookie;
+		out.cookie = typeof existing === "string" && existing !== "" ? `${existing}; ${relayed}` : relayed;
+	}
+	return out;
+}
+/**
+* Filter one direction's worth of headers through the same cookie rule, so the
+* HTTP and WebSocket branches cannot drift apart on it.
+*/
+function stripUpstreamCookies(entry) {
+	return !isUpstreamSessionCookie(entry.trim());
+}
+/**
+* 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.
+*/
+function downstreamResponseHeaders(upstream) {
+	const headers = {};
+	for (const [key, value] of Object.entries(upstream)) {
+		if (value === void 0) 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(stripUpstreamCookies);
+			if (list.length > 0) headers[key] = list;
+			continue;
+		}
+		headers[key] = value;
+	}
+	return headers;
+}
+/**
+* The headers of a 101 Switching Protocols response, replayed to the client on
+* the socket the gateway just spliced.
+*
+* {@link downstreamResponseHeaders} cannot be reused verbatim here: a successful
+* upgrade has to keep Connection/Upgrade, which are hop-by-hop on every other
+* response. The cookie rule is not relaxed with them — the relay's session is
+* withheld on this path too, so upstream cannot hand a client a durable
+* credential by attaching it to the handshake.
+*/
+function upgradeResponseHeaders(upstream) {
+	const headers = {};
+	for (const [key, value] of Object.entries(upstream)) {
+		if (value === void 0) continue;
+		const lower = key.toLowerCase();
+		if (HOP_BY_HOP_HEADERS.has(lower) && !UPGRADE_HANDSHAKE_HEADERS.has(lower)) continue;
+		if (lower === "set-cookie") {
+			const list = (Array.isArray(value) ? value : [value]).filter(stripUpstreamCookies);
+			if (list.length > 0) headers[key] = list;
+			continue;
+		}
+		headers[key] = value;
+	}
+	return headers;
+}
+//#endregion
 //#region src/state.ts
 /**
 * Persistent runtime state for the LAN gateway: the cookie-signing secret and
@@ -282,13 +850,27 @@ function stateDir(home = homedir()) {
 	return join(home, ".dsh", "lan-gateway");
 }
 const STATE_FILENAME = "state.json";
-/** Whether a password is present and passes scrypt verification. */
-function verifyPassword(state, password) {
+/** Promise wrapper around the threaded `scrypt`, which runs off the main loop. */
+function deriveKey(password, salt, keylen) {
+	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.
+*/
+async function verifyPassword(state, password) {
 	if (state.password === void 0) 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;
@@ -298,18 +880,20 @@ function verifyPassword(state, password) {
 * 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.
+*
+* Deriving the key is asynchronous for the same reason
+* {@link verifyPassword} is: `scryptSync` occupies the event loop for tens of
+* milliseconds, and that loop is shared with the dsh process the gateway
+* forwards to. Every caller is already async.
 */
-function setPassword(state, password) {
+async function setPassword(state, password) {
 	const base = {
-		...state,
+		cookieSecret: state.cookieSecret,
 		sessionEpoch: state.sessionEpoch + 1
 	};
-	if (password === void 0) return {
-		cookieSecret: base.cookieSecret,
-		sessionEpoch: base.sessionEpoch
-	};
+	if (password === void 0) return base;
 	const salt = randomBytes(16);
-	const hash = scryptSync(password, salt, 64);
+	const hash = await deriveKey(password, salt, 64);
 	return {
 		...base,
 		password: {
@@ -318,12 +902,46 @@ function setPassword(state, password) {
 		}
 	};
 }
+/**
+* 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.
+* @param now - epoch millis to judge the existing entries against, injected so
+*   a test can age the list without fake timers.
+*/
+function revokeSession(state, sid, expiresMs, now = Date.now()) {
+	const revoked = {};
+	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. */
+function isSessionRevoked(state, sid) {
+	if (sid === void 0) return false;
+	return Object.hasOwn(state.revokedSessions ?? {}, sid);
+}
 function defaultState() {
 	return {
 		cookieSecret: randomBytes(32).toString("base64"),
 		sessionEpoch: 0
 	};
 }
+/** Keep the still-live entries of a persisted revocation list, or undefined. */
+function parseRevokedSessions(raw) {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return void 0;
+	const now = Date.now();
+	const out = {};
+	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 : void 0;
+}
 /** Load state; on first run (or a corrupt file) generate a fresh secret. */
 function loadState(home = homedir()) {
 	const dir = stateDir(home);
@@ -337,6 +955,8 @@ function loadState(home = homedir()) {
 				sessionEpoch
 			};
 			if (parsed.password !== void 0) base.password = parsed.password;
+			const revoked = parseRevokedSessions(parsed.revokedSessions);
+			if (revoked !== void 0) base.revokedSessions = revoked;
 			return base;
 		}
 		return defaultState();
@@ -359,8 +979,9 @@ function saveState(state, home = homedir()) {
 //#endregion
 //#region src/gateway.ts
 /**
-* 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
@@ -374,38 +995,34 @@ function saveState(state, home = homedir()) {
 *   or its login/logout paths; those are handled locally or refused.
 * - Because this gateway rewrites Origin to loopback, dsh's own CSRF fence is
 *   blinded — so the gateway runs its own origin check on every relayed
-*   request (HTTP and WebSocket upgrade) BEFORE rewriting: reject
-*   `sec-fetch-site: cross-site`, reject any Origin that does not name the
-*   gateway authority the browser actually used, and require an Origin on
-*   state-changing methods and on every WebSocket upgrade.
+*   request (HTTP and WebSocket upgrade) BEFORE rewriting. See
+*   `request-policy.ts`, which owns that decision along with every other
+*   header/path/server decision; this module owns the transport.
 * - Against a session-capable dsh base the Host/Origin rewrite alone would
 *   still earn a 401 (dsh no longer trusts a loopback Host; it demands its own
 *   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
 */
 const DEFAULT_BODY_LIMIT_BYTES = 65536;
 const LOGIN_ATTEMPTS_LIMIT = 5;
 const LOGIN_ATTEMPTS_WINDOW_MS = 6e4;
-/** Methods a browser never attaches a CSRF-meaningful body to; safe without an Origin. */
-const READ_ONLY_METHODS$1 = /* @__PURE__ */ new Set([
-	"GET",
-	"HEAD",
-	"OPTIONS"
-]);
-/** Prefixes the gateway owns and must never relay to dsh. */
-function isOwnedPath(pathname) {
-	return pathname === "/lan-gateway" || pathname.startsWith("/lan-gateway/");
-}
-/** The pathname of a request URL (query string stripped, not decoded). */
-function pathOf(url) {
-	const query = url.indexOf("?");
-	return query === -1 ? url : url.slice(0, query);
+/**
+* How long a half-open upstream WebSocket handshake may hang before the
+* gateway gives up on it. Without a deadline the client socket sits in the
+* pending table forever and never learns the upgrade failed — node's http
+* client would wait out its own socket timeout, which is measured in minutes.
+*/
+const UPGRADE_HANDSHAKE_TIMEOUT_MS = 15e3;
+/** A fresh per-session id: 128 random bits, URL-safe. */
+function newSessionId() {
+	return randomBytes(16).toString("base64url");
 }
 /**
 * The running gateway: owns the HTTP server and the auth state needed per
@@ -418,8 +1035,26 @@ var LanGateway = class {
 	loginLimiter = new RateLimiter(LOGIN_ATTEMPTS_LIMIT, LOGIN_ATTEMPTS_WINDOW_MS);
 	state;
 	disposed = false;
-	/** Established WebSockets (upgraded client sockets), torn down on session-epoch change. */
-	activeDuplexes = /* @__PURE__ */ new Set();
+	/**
+	* Every WebSocket this gateway is responsible for, keyed by the client
+	* socket: pending handshakes as well as established ones.
+	*
+	* 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. A handshake that is still waiting on the relay or on
+	* upstream's 101 is tracked from the moment it passes the gates, not from the
+	* moment it is spliced — otherwise a revocation that lands mid-handshake
+	* closes the map's contents and then watches the abandoned handshake finish
+	* and register itself as live.
+	*/
+	sockets = /* @__PURE__ */ new Map();
+	/**
+	* Bumped by every revocation (epoch change, per-session sign-out) and by
+	* disposal. A socket is retired when the generation moves past the one it was
+	* admitted under, which is what lets a pending handshake be judged by the
+	* rules in force when it *completes* rather than when it started.
+	*/
+	gate = 0;
 	constructor(config, state) {
 		this.config = config;
 		this.state = state;
@@ -436,10 +1071,20 @@ var LanGateway = class {
 	}
 	/** Replace the in-memory state; bumps of `sessionEpoch` revoke live sessions and sockets. */
 	setState(state) {
-		if (state.sessionEpoch !== this.state.sessionEpoch) this.destroyActiveDuplexes();
+		if (state.sessionEpoch !== this.state.sessionEpoch) {
+			this.gate += 1;
+			this.destroyAllSockets();
+		}
 		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() {
 		return new Promise((resolve, reject) => {
 			const onError = (err) => {
@@ -452,59 +1097,87 @@ var LanGateway = class {
 			};
 			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);
 		});
 	}
-	/** Close the server, drop upgraded sockets, and stop accepting connections. */
+	/** The address actually bound, for logs and status (never a claim about it). */
+	boundAddress() {
+		const address = this.server.address();
+		if (address === null || typeof address === "string") return `port ${this.config.gatewayPort}`;
+		return `${address.family === "IPv6" ? `[${address.address}]` : address.address}:${address.port}`;
+	}
+	/** Close the server, drop every socket, and stop accepting connections. */
 	async close() {
 		if (this.disposed) return;
 		this.disposed = true;
-		this.destroyActiveDuplexes();
+		this.gate += 1;
+		this.destroyAllSockets();
 		return new Promise((resolve) => {
 			this.server.close(() => resolve());
 			this.server.closeAllConnections();
 		});
 	}
-	destroyActiveDuplexes() {
-		for (const socket of this.activeDuplexes) socket.destroy();
-		this.activeDuplexes.clear();
+	destroyAllSockets() {
+		for (const socket of this.sockets.keys()) socket.destroy();
+		this.sockets.clear();
+	}
+	/** Close the sockets one session opened, so signing out ends its live streams too. */
+	destroySocketsFor(sid) {
+		for (const [socket, tracked] of this.sockets) {
+			if (tracked.sid !== sid) continue;
+			this.sockets.delete(socket);
+			socket.destroy();
+		}
 	}
-	trackDuplex(socket) {
-		this.activeDuplexes.add(socket);
+	/** Track a socket from admission to close. */
+	trackSocket(socket, sid) {
+		this.sockets.set(socket, {
+			sid,
+			gate: this.gate
+		});
 		socket.on("close", () => {
-			this.activeDuplexes.delete(socket);
+			this.sockets.delete(socket);
 		});
 	}
+	/** Whether a socket is still tracked, undisposed, and admitted under the current gate. */
+	stillAdmitted(socket) {
+		if (this.disposed) return false;
+		const tracked = this.sockets.get(socket);
+		return tracked !== void 0 && tracked.gate === this.gate;
+	}
 	sourceOf(req) {
 		return this.config.classifySource !== void 0 ? this.config.classifySource(req) : classifySource(req.socket.remoteAddress, this.config.lanCidrs);
 	}
-	/** Parse the session cookie out of a Cookie header. */
-	sessionCookie(req) {
-		const header = req.headers.cookie;
-		if (typeof header !== "string") return void 0;
-		for (const part of header.split(";")) {
-			const trimmed = part.trim();
-			if (trimmed.startsWith(`${this.config.cookieName}=`)) return trimmed.slice(this.config.cookieName.length + 1);
-		}
+	/**
+	* 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.
+	*/
+	session(req) {
+		const cookie = sessionCookie(req.headers, this.config.cookieName);
+		if (cookie === void 0) return void 0;
+		const claims = verifySession(this.state.cookieSecret, cookie, Date.now(), this.state.sessionEpoch);
+		if (claims === void 0) return void 0;
+		return isSessionRevoked(this.state, claims.sid) ? void 0 : claims;
 	}
 	/** Whether a request carries a session valid under the current epoch. */
 	authorized(req) {
-		const cookie = this.sessionCookie(req);
-		return cookie !== void 0 && verifyCookie(this.state.cookieSecret, cookie, Date.now(), this.state.sessionEpoch);
-	}
-	/** Whether this source must present a gateway session (default: everyone). */
-	requiresLogin(source) {
-		return !(this.config.lanPasswordless && source !== "internet");
+		return this.session(req) !== void 0;
 	}
-	serveUnauthorized(res, limited) {
+	/**
+	* Send an unauthorized caller to the login form. The rate limiter's refusal
+	* does not come through here: it is answered on the POST itself, where the
+	* banner can be rendered without a round trip.
+	*/
+	serveUnauthorized(res) {
 		res.writeHead(302, {
-			location: `${LOGIN_PATH}${limited ? "?limited=1" : ""}`,
+			location: LOGIN_PATH,
 			...this.securityHeaders()
 		});
 		res.end();
 	}
-	serveLoginError(res, message) {
-		const opts = { error: message };
+	serveLoginError(res, message, limited = false) {
+		const opts = limited ? { limited: true } : { error: message };
 		res.writeHead(401, {
 			"content-type": "text/html; charset=utf-8",
 			"cache-control": "no-store",
@@ -516,27 +1189,11 @@ var LanGateway = class {
 	securityHeaders() {
 		return this.config.tls === void 0 ? {} : { "strict-transport-security": "max-age=15552000" };
 	}
-	/**
-	* The gateway's own cross-site gate, shared by HTTP and WebSocket upgrades
-	* and applied before any Host/Origin rewriting. Browsers attach Origin to
-	* state-changing requests and to every WebSocket handshake; reads without an
-	* Origin (navigations, non-browser clients holding a session) stay allowed.
-	*/
-	sameSiteAllowed(req, upgrade) {
-		const headers = req.headers;
-		if (headers["sec-fetch-site"] === "cross-site") return false;
-		const origin = headers.origin;
-		const host = headers.host;
-		if (origin !== void 0 && !originMatchesHost(origin, host)) return false;
-		if (upgrade) return origin !== void 0;
-		if (!READ_ONLY_METHODS$1.has(req.method ?? "GET")) return origin !== void 0;
-		return true;
-	}
 	sessionSetCookie(value, maxAgeSeconds) {
 		const attributes = `Path=/; HttpOnly; SameSite=Strict; Max-Age=${maxAgeSeconds}`;
 		return `${this.config.cookieName}=${value}; ${attributes}${this.config.secureCookies ? "; Secure" : ""}`;
 	}
-	/** Handle one HTTP request: anonymous allowlist → owned-path refuse → session gate → same-site gate → relay. */
+	/** Handle one HTTP request: login surface → owned-path refuse → session gate → same-site gate → relay. */
 	async handleHttp(req, res) {
 		const url = req.url ?? "/";
 		const pathname = pathOf(url);
@@ -554,11 +1211,11 @@ var LanGateway = class {
 			res.end("forbidden");
 			return;
 		}
-		if (this.requiresLogin(source) && !this.authorized(req)) {
-			this.serveUnauthorized(res, false);
+		if (requiresLogin(source, this.config.lanPasswordless) && !this.authorized(req)) {
+			this.serveUnauthorized(res);
 			return;
 		}
-		if (!this.sameSiteAllowed(req, false)) {
+		if (!sameSiteAllowed(req, false)) {
 			res.writeHead(403, this.securityHeaders());
 			res.end("forbidden");
 			return;
@@ -567,7 +1224,6 @@ var LanGateway = class {
 	}
 	/** Handle the login GET form / POST submission. */
 	handleLogin(req, res) {
-		req.url?.includes("limited=1");
 		if (req.method === "GET" || req.method === "HEAD") {
 			serveLoginGet(res, this.securityHeaders());
 			return;
@@ -577,12 +1233,17 @@ var LanGateway = class {
 			res.end();
 			return;
 		}
+		if (!loginOriginAllowed(req.headers)) {
+			res.writeHead(403, this.securityHeaders());
+			res.end("forbidden");
+			return;
+		}
 		const key = req.socket.remoteAddress ?? "unknown";
 		if (!this.loginLimiter.allow(key)) {
-			this.serveLoginError(res, "Too many attempts — please wait a minute.");
+			this.serveLoginError(res, "Too many attempts — please wait a minute.", true);
 			return;
 		}
-		readBody(req, DEFAULT_BODY_LIMIT_BYTES, res).then((body) => {
+		readBody(req, DEFAULT_BODY_LIMIT_BYTES, res).then(async (body) => {
 			if (body === void 0) return;
 			let password;
 			try {
@@ -590,33 +1251,59 @@ var LanGateway = class {
 			} catch {
 				password = void 0;
 			}
-			if (password === void 0 || !verifyPassword(this.state, password)) {
+			const checked = this.state;
+			const accepted = password !== void 0 && await verifyPassword(checked, password);
+			if (this.state !== checked || this.disposed) {
+				this.serveLoginError(res, "Sign-in was interrupted — please try again.");
+				return;
+			}
+			if (!accepted) {
 				this.serveLoginError(res, "Incorrect password.");
 				return;
 			}
 			const maxAgeSeconds = this.config.cookieMaxAgeDays * 86400;
 			const expiresMs = Date.now() + maxAgeSeconds * 1e3;
-			const cookie = signCookie(this.state.cookieSecret, expiresMs, this.state.sessionEpoch);
+			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(() => {
+			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.
+	*/
 	handleLogout(req, res) {
 		if (req.method !== "POST") {
 			res.writeHead(405, { allow: "POST" });
 			res.end();
 			return;
 		}
-		if (!this.sameSiteAllowed(req, false)) {
+		if (!sameSiteAllowed(req, false)) {
 			res.writeHead(403, this.securityHeaders());
 			res.end("forbidden");
 			return;
 		}
+		const claims = this.session(req);
+		if (claims?.sid !== void 0) {
+			this.state = revokeSession(this.state, claims.sid, claims.exp);
+			this.config.onStateChange?.(this.state);
+			this.destroySocketsFor(claims.sid);
+		}
 		res.writeHead(302, {
 			location: "/",
 			...this.securityHeaders(),
@@ -624,34 +1311,20 @@ var LanGateway = class {
 		});
 		res.end();
 	}
-	/** Build the outbound headers: rewrite Host/Origin to the loopback upstream. */
-	upstreamHeaders(req, keepUpgrade) {
-		const headers = { ...req.headers };
-		headers.host = `127.0.0.1:${this.config.dshPort}`;
-		if (typeof headers.origin === "string") headers.origin = `http://127.0.0.1:${this.config.dshPort}`;
-		delete headers["proxy-connection"];
-		if (!keepUpgrade) {
-			delete headers.connection;
-			delete headers.upgrade;
-		}
-		return headers;
-	}
-	/** Attach the shared upstream session cookie to the outbound headers, if any. */
-	attachUpstreamSession(headers) {
-		const session = this.config.upstreamSession;
-		if (session === void 0) return false;
-		const cookie = session.peek();
-		if (cookie === void 0) return false;
-		const existing = headers.cookie;
-		headers.cookie = typeof existing === "string" && existing !== "" ? `${existing}; ${cookie}` : cookie;
-		return true;
+	/** The shared upstream session's cookie value, if the relay holds one. */
+	async upstreamCookie() {
+		return this.config.upstreamSession === void 0 ? void 0 : this.config.upstreamSession.cookie();
 	}
 	/** Forward an HTTP request to dsh, replaying the shared upstream session. */
 	async relayHttp(req, res, url) {
 		const session = this.config.upstreamSession;
-		if (session !== void 0) await session.cookie();
-		const headers = this.upstreamHeaders(req, false);
-		const attached = this.attachUpstreamSession(headers);
+		const relayed = await this.upstreamCookie();
+		const headers = upstreamRequestHeaders(req.headers, {
+			dshPort: this.config.dshPort,
+			keepUpgrade: false,
+			upstreamCookie: relayed
+		});
+		const attached = relayed !== void 0;
 		const proxyReq = http.request({
 			host: "127.0.0.1",
 			port: this.config.dshPort,
@@ -660,7 +1333,7 @@ var LanGateway = class {
 			headers
 		}, (proxyRes) => {
 			if (attached && session !== void 0 && proxyRes.statusCode === 401) session.invalidate();
-			res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+			res.writeHead(proxyRes.statusCode ?? 502, downstreamResponseHeaders(proxyRes.headers));
 			proxyRes.pipe(res);
 		});
 		proxyReq.on("error", () => {
@@ -682,18 +1355,30 @@ var LanGateway = class {
 			refuse(403);
 			return;
 		}
-		if (this.requiresLogin(source) && !this.authorized(req)) {
+		const claims = this.session(req);
+		if (requiresLogin(source, this.config.lanPasswordless) && claims === void 0) {
 			refuse(401);
 			return;
 		}
-		if (!this.sameSiteAllowed(req, true)) {
+		if (!sameSiteAllowed(req, true)) {
 			refuse(403);
 			return;
 		}
-		const session = this.config.upstreamSession;
-		if (session !== void 0) await session.cookie();
-		const headers = this.upstreamHeaders(req, true);
-		this.attachUpstreamSession(headers);
+		this.trackSocket(socket, claims?.sid);
+		const retire = () => {
+			if (!this.sockets.delete(socket)) return;
+			socket.destroy();
+		};
+		const relayed = await this.upstreamCookie();
+		if (!this.stillAdmitted(socket)) {
+			retire();
+			return;
+		}
+		const headers = upstreamRequestHeaders(req.headers, {
+			dshPort: this.config.dshPort,
+			keepUpgrade: true,
+			upstreamCookie: relayed
+		});
 		const proxyReq = http.request({
 			host: "127.0.0.1",
 			port: this.config.dshPort,
@@ -701,10 +1386,22 @@ var LanGateway = class {
 			path: url,
 			headers
 		});
+		const timer = setTimeout(() => {
+			proxyReq.destroy();
+			retire();
+		}, UPGRADE_HANDSHAKE_TIMEOUT_MS);
+		const settle = () => {
+			clearTimeout(timer);
+		};
 		proxyReq.on("upgrade", (proxyRes, proxySocket, proxyHead) => {
-			this.trackDuplex(socket);
+			settle();
+			if (!this.stillAdmitted(socket)) {
+				proxySocket.destroy();
+				retire();
+				return;
+			}
 			const statusLine = `HTTP/1.1 ${proxyRes.statusCode ?? 101} ${proxyRes.statusMessage ?? "Switching Protocols"}\r\n`;
-			const headerLines = Object.entries(proxyRes.headers).map(([key, value]) => `${key}: ${Array.isArray(value) ? value.join(", ") : value}\r\n`).join("");
+			const headerLines = Object.entries(upgradeResponseHeaders(proxyRes.headers)).flatMap(([key, value]) => (Array.isArray(value) ? value : [value]).map((entry) => `${key}: ${entry}\r\n`)).join("");
 			socket.write(`${statusLine}${headerLines}\r\n`);
 			if (head !== void 0 && head.length > 0) proxySocket.write(head);
 			proxySocket.pipe(socket).pipe(proxySocket);
@@ -712,7 +1409,22 @@ var LanGateway = class {
 			socket.on("error", () => proxySocket.destroy());
 			proxySocket.on("error", () => socket.destroy());
 		});
-		proxyReq.on("error", () => socket.destroy());
+		proxyReq.on("response", (proxyRes) => {
+			settle();
+			proxyRes.resume();
+			if (!this.stillAdmitted(socket)) {
+				retire();
+				return;
+			}
+			if (proxyRes.statusCode === 401 && relayed !== void 0) this.config.upstreamSession?.invalidate();
+			const body = `upstream refused the WebSocket upgrade (HTTP ${proxyRes.statusCode ?? 502})`;
+			socket.write(`HTTP/1.1 ${proxyRes.statusCode ?? 502} ${proxyRes.statusMessage ?? "Upstream Refused"}\r\nConnection: close\r\nContent-Type: text/plain; charset=utf-8\r\nContent-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`);
+			retire();
+		});
+		proxyReq.on("error", () => {
+			settle();
+			retire();
+		});
 		proxyReq.end();
 	}
 };
@@ -982,6 +1694,29 @@ function loadOrCreateSelfSigned(opts, home = homedir()) {
 	};
 }
 /**
+* 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.
+*/
+function loadOrRenewSelfSigned(opts, home = homedir()) {
+	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`.
 */
@@ -993,6 +1728,31 @@ function regenerateSelfSigned(opts, home = homedir()) {
 	privateWrite(join(dir, SELF_SIGNED_CERT_FILE), material.cert);
 	return material;
 }
+/**
+* Read the persisted self-signed certificate for a status report, or undefined
+* when none has been generated yet.
+*
+* Nothing is created or written here. The status path answers a question about
+* a listener that is already running (or was), and minting a key pair — an RSA
+* generation plus two file writes — to answer a read would both be slow and
+* leave material on disk for a gateway that never started. Generation belongs
+* to {@link loadOrRenewSelfSigned} and {@link regenerateSelfSigned}.
+* @param home - dsh home override (tests).
+* @returns the certificate material as persisted, or undefined.
+*/
+function readSelfSignedStatus(home = homedir()) {
+	const dir = tlsDir(home);
+	const certPath = join(dir, SELF_SIGNED_CERT_FILE);
+	const keyPath = join(dir, SELF_SIGNED_KEY_FILE);
+	if (!existsSync(certPath) || !existsSync(keyPath)) return void 0;
+	const cert = readFileSync(certPath, "utf8");
+	const key = readFileSync(keyPath, "utf8");
+	new X509Certificate(cert);
+	return {
+		cert,
+		key
+	};
+}
 function generateSelfSignedMaterial(opts) {
 	const hosts = opts.hosts.map((h) => h.trim()).filter((h) => h !== "");
 	if (hosts.length === 0) throw new Error("self-signed TLS needs at least one host in tlsSelfSignedHosts");
@@ -1006,295 +1766,130 @@ function generateSelfSignedMaterial(opts) {
 		key: keyPem
 	};
 }
-/**
-* Load a user-supplied certificate + key pair from PEM files.
-* @param certPath - path to the PEM certificate (or chain).
-* @param keyPath - path to the PEM private key.
-* @returns the material.
-*/
-function loadCustomCert(certPath, keyPath) {
-	if (certPath === "") throw new Error("tlsMode=custom requires tlsCertPath (PEM certificate)");
-	if (keyPath === "") throw new Error("tlsMode=custom requires tlsKeyPath (PEM private key)");
-	let cert;
-	try {
-		cert = readFileSync(certPath, "utf8");
-	} catch (error) {
-		throw new Error(`cannot read TLS certificate "${certPath}": ${errorMessage(error)}`);
-	}
-	let key;
-	try {
-		key = readFileSync(keyPath, "utf8");
-	} catch (error) {
-		throw new Error(`cannot read TLS private key "${keyPath}": ${errorMessage(error)}`);
-	}
-	try {
-		new X509Certificate(cert);
-	} catch {
-		throw new Error(`"${certPath}" does not contain a valid PEM certificate`);
-	}
-	return {
-		cert,
-		key
-	};
-}
-/** Parse the user-facing `tlsSelfSignedHosts` string into SAN entries. */
-function parseSelfSignedHosts(text) {
-	return (text ?? "").split(/[,;]/).map((host) => host.trim()).filter((host) => host !== "").slice(0, 32);
-}
-/** Describe a PEM certificate (throws on malformed input). */
-function describeCert(certPem) {
-	const cert = new X509Certificate(certPem);
-	return {
-		subject: cert.subject,
-		issuer: cert.issuer,
-		validFrom: cert.validFrom,
-		validTo: cert.validTo,
-		fingerprint256: cert.fingerprint256,
-		...cert.subjectAltName !== void 0 ? { san: cert.subjectAltName } : {}
-	};
-}
-function errorMessage(error) {
-	return error instanceof Error ? error.message : String(error);
-}
-//#endregion
-//#region src/tool.ts
-const LAN_GATEWAY_TOOL_NAME = "lan_gateway";
-/**
-* Build the `lan_gateway` tool over a controller interface implemented by the
-* plugin entry. Split so the tool stays testable and the plugin decides how
-* the controller mutates state.
-*/
-function lanGatewayTool(control) {
-	return defineTool({
-		name: LAN_GATEWAY_TOOL_NAME,
-		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 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 (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",
-				description: "Required for `set-password`: the new password (min 8 chars). Omit or pass empty to clear."
-			}
-		},
-		output: {
-			schema: {
-				type: "object",
-				additionalProperties: false,
-				properties: {
-					ok: {
-						type: "boolean",
-						required: true
-					},
-					message: {
-						type: "string",
-						required: true
-					}
-				}
-			},
-			render: (_args, value) => [{
-				type: "text",
-				text: value.message
-			}]
-		},
-		async execute(args, _exec) {
-			switch (args.command ?? "status") {
-				case "status": return control.status();
-				case "enable": return control.enable();
-				case "disable": return control.disable();
-				case "set-password": {
-					const password = args.password;
-					return control.setPassword(typeof password === "string" ? password : void 0);
-				}
-				case "rotate-secret": return control.rotateSecret();
-				case "tls-regenerate": return control.regenerateTls();
-			}
-		}
-	});
-}
-//#endregion
-//#region src/upstream-session.ts
-/**
-* Shared upstream session relay for session-capable dsh bases (>= 0.1.2).
-*
-* When dsh added browser-session authentication it stopped trusting a loopback
-* Host header alone: every `/api` request (and the remote WebSocket mux) must
-* now present a signed cookie bound to the authority it names
-* (`dsh-auth-<sha256(authority)>`), minted at the index route by exchanging the
-* process launch token. A reverse proxy that rewrites Host to loopback — which
-* is what this gateway does — therefore gets a 401 no matter how the Host is
-* forged. The gateway cannot mint that cookie itself (the signing secret lives
-* in dsh's credential provider), so it does exactly what a browser does: on the
-* loopback transport it visits the launch-token URL, keeps the Set-Cookie it
-* earns, and replays that one shared session on every request it forwards.
-*
-* Semantics match the pre-existing "single password = single operator" model:
-* whoever passes the gateway's own login rides this one upstream session. It is
-* not multi-user authorization, and upstream (which holds the secret) remains
-* the actual authority over what the session may do.
-*
-* The relay is a no-op on a base without browser sessions: acquisition fails
-* and `cookie()` returns undefined, so the gateway simply forwards without a
-* session cookie exactly as it did against an older dsh.
-*
-* @module @riceawa/dsh-lan-gateway/upstream-session
-*/
-/** The session-cookie name prefix upstream signs (`dsh-auth-<b64url(sha256)>`). */
-const UPSTREAM_COOKIE_PREFIX = "dsh-auth-";
-/** Split `name=value; Path=/; …` into the `name=value` request-Cookie fragment. */
-function nameValueOnly(setCookie) {
-	const semi = setCookie.indexOf(";");
-	return (semi === -1 ? setCookie : setCookie.slice(0, semi)).trim();
-}
-/** The cookie name of a `Set-Cookie` string (`''` when it is malformed). */
-function cookieNameOf(setCookie) {
-	const eq = setCookie.indexOf("=");
-	return eq === -1 ? "" : setCookie.slice(0, eq).trim();
-}
-/**
-* Whether a `Set-Cookie` string is the upstream browser-session cookie. The
-* name upstream mints is `dsh-auth-<base64url(sha256(authority))>`: the prefix
-* is followed by the authority hash, never by `=` itself, so the test is a
-* prefix plus at least one character — matching on `dsh-auth-=` finds nothing
-* and silently relays every request anonymously.
-*/
-function isUpstreamSessionCookie(setCookie) {
-	const name = cookieNameOf(setCookie);
-	return name.startsWith(UPSTREAM_COOKIE_PREFIX) && name.length > 9;
-}
-/** Pull the Max-Age attribute (seconds) out of a Set-Cookie string, if any. */
-function maxAgeSeconds(setCookie) {
-	const match = /\bMax-Age=(\d+)\b/i.exec(setCookie);
-	return match === null ? void 0 : Number(match[1]);
-}
-/**
-* Perform the token exchange over loopback: GET the launch-token URL with the
-* upstream authority as Host, read the Set-Cookie the index route mints, and
-* return its `name=value` plus expiry (or undefined when the exchange failed
-* or no session cookie came back — e.g. an older base without browser
-* sessions).
-*/
-function exchange(url, authority, port, log) {
-	return new Promise((resolve) => {
-		let target;
-		try {
-			target = new URL(url);
-		} catch {
-			log(`exchange: unparseable authenticatedUrl ${url}`);
-			resolve(void 0);
-			return;
-		}
-		const request = http.request({
-			host: "127.0.0.1",
-			port,
-			method: "GET",
-			path: `${target.pathname}${target.search}`,
-			headers: {
-				host: authority,
-				accept: "text/html"
-			}
-		}, (response) => {
-			const setCookies = response.headers["set-cookie"];
-			response.resume();
-			if (setCookies === void 0) {
-				log(`exchange ${target.pathname} -> ${response.statusCode} (no set-cookie)`);
-				resolve(void 0);
-				return;
-			}
-			const all = Array.isArray(setCookies) ? setCookies : [setCookies];
-			const raw = all.find(isUpstreamSessionCookie);
-			if (raw === void 0) {
-				const names = all.map(cookieNameOf).filter((name) => name !== "");
-				log(`exchange ${target.pathname} -> ${response.statusCode} (no ${UPSTREAM_COOKIE_PREFIX}* cookie; got: ${names.join(", ") || "none"})`);
-				resolve(void 0);
-				return;
-			}
-			const header = nameValueOnly(raw);
-			const maxAge = maxAgeSeconds(raw);
-			log(`exchange ${target.pathname} -> ${response.statusCode} (got ${cookieNameOf(raw)}, maxAge=${maxAge ?? "n/a"})`);
-			resolve({
-				header,
-				expiresAt: Date.now() + (maxAge ?? 0) * 1e3
-			});
-		});
-		request.on("error", (error) => {
-			log(`exchange error: ${error.message}`);
-			resolve(void 0);
-		});
-		request.setTimeout(5e3, () => {
-			log("exchange timeout (5s)");
-			request.destroy(/* @__PURE__ */ new Error("upstream-session exchange timeout"));
-		});
-		request.end();
-	});
-}
-/**
-* A cached {@link UpstreamSession} acquired through the launch-token exchange.
-* Acquisition runs at most once concurrently and the result is cached until it
-* nears expiry or {@link invalidate} is called.
+/**
+* Load a user-supplied certificate + key pair from PEM files.
+* @param certPath - path to the PEM certificate (or chain).
+* @param keyPath - path to the PEM private key.
+* @returns the material.
 */
-var UpstreamSessionRelay = class {
-	port;
-	authority;
-	authenticatedUrl;
-	log;
-	held;
-	inflight;
-	constructor(options) {
-		this.port = options.port;
-		this.authority = options.authority ?? `127.0.0.1:${options.port}`;
-		this.authenticatedUrl = options.authenticatedUrl;
-		this.log = options.log ?? (() => {});
-	}
-	/** Whether the held session is still comfortably inside its lifetime. */
-	fresh() {
-		const held = this.held;
-		if (held === void 0) return false;
-		return Date.now() < held.expiresAt - 6e4;
-	}
-	peek() {
-		return this.held?.header;
-	}
-	invalidate() {
-		if (this.held !== void 0) this.log("invalidating held session (upstream rejected it)");
-		this.held = void 0;
+function loadCustomCert(certPath, keyPath) {
+	if (certPath === "") throw new Error("tlsMode=custom requires tlsCertPath (PEM certificate)");
+	if (keyPath === "") throw new Error("tlsMode=custom requires tlsKeyPath (PEM private key)");
+	let cert;
+	try {
+		cert = readFileSync(certPath, "utf8");
+	} catch (error) {
+		throw new Error(`cannot read TLS certificate "${certPath}": ${errorMessage(error)}`);
 	}
-	async cookie() {
-		if (this.fresh()) return this.held?.header;
-		return this.acquire();
+	let key;
+	try {
+		key = readFileSync(keyPath, "utf8");
+	} catch (error) {
+		throw new Error(`cannot read TLS private key "${keyPath}": ${errorMessage(error)}`);
 	}
-	acquire() {
-		if (this.inflight !== void 0) return this.inflight;
-		const pending = this.doExchange().finally(() => {
-			this.inflight = void 0;
-		});
-		this.inflight = pending;
-		return pending;
+	try {
+		new X509Certificate(cert);
+	} catch {
+		throw new Error(`"${certPath}" does not contain a valid PEM certificate`);
 	}
-	async doExchange() {
-		const url = this.authenticatedUrl();
-		if (url === void 0) {
-			this.log("authenticatedUrl() returned undefined; keeping current session");
-			return this.held?.header;
+	return {
+		cert,
+		key
+	};
+}
+/** Parse the user-facing `tlsSelfSignedHosts` string into SAN entries. */
+function parseSelfSignedHosts(text) {
+	return (text ?? "").split(/[,;]/).map((host) => host.trim()).filter((host) => host !== "").slice(0, 32);
+}
+/**
+* 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.
+*/
+function isCertExpired(certPem, now = Date.now()) {
+	const expiresAt = Date.parse(new X509Certificate(certPem).validTo);
+	return Number.isFinite(expiresAt) && expiresAt <= now;
+}
+/** Describe a PEM certificate (throws on malformed input). */
+function describeCert(certPem) {
+	const cert = new X509Certificate(certPem);
+	return {
+		subject: cert.subject,
+		issuer: cert.issuer,
+		validFrom: cert.validFrom,
+		validTo: cert.validTo,
+		fingerprint256: cert.fingerprint256,
+		...cert.subjectAltName !== void 0 ? { san: cert.subjectAltName } : {}
+	};
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region src/tool.ts
+const LAN_GATEWAY_TOOL_NAME = "lan_gateway";
+/**
+* Build the `lan_gateway` tool over a controller interface implemented by the
+* plugin entry. Split so the tool stays testable and the plugin decides how
+* the controller mutates state.
+*/
+function lanGatewayTool(control) {
+	return defineTool({
+		name: LAN_GATEWAY_TOOL_NAME,
+		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 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 (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",
+				description: "Required for `set-password`: the new password (min 8 chars). Omit or pass empty to clear."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					ok: {
+						type: "boolean",
+						required: true
+					},
+					message: {
+						type: "string",
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.message
+			}]
+		},
+		async execute(args, _exec) {
+			switch (args.command ?? "status") {
+				case "status": return control.status();
+				case "enable": return control.enable();
+				case "disable": return control.disable();
+				case "set-password": {
+					const password = args.password;
+					return control.setPassword(typeof password === "string" ? password : void 0);
+				}
+				case "rotate-secret": return control.rotateSecret();
+				case "tls-regenerate": return control.regenerateTls();
+			}
 		}
-		this.log(`acquiring session from ${url}`);
-		const result = await exchange(url, this.authority, this.port, this.log);
-		if (result !== void 0) {
-			this.held = result;
-			this.log("session acquired and cached");
-		} else this.log("exchange failed; keeping current session");
-		return this.held?.header;
-	}
-};
+	});
+}
 //#endregion
 //#region src/index.ts
 /** Stable Cordis plugin name. */
@@ -1308,13 +1903,6 @@ const inject = ["webServer", "tools"];
 * 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 = /* @__PURE__ */ new Set([
-	"dshTargetPort",
-	"tlsCertPath",
-	"tlsKeyPath",
-	"trustedTerminator"
-]);
 /** Schemastery configuration validated by the Loader. */
 const Config = z.object({
 	enabled: z.boolean().default(false),
@@ -1365,14 +1953,16 @@ function resolveSecureCookies(cfg) {
 /** Resolve the TLS material for a config, or undefined when TLS is off. */
 function resolveTls(cfg) {
 	if (!cfg.tlsEnabled) return void 0;
-	if (cfg.tlsMode === "custom") return loadCustomCert(cfg.tlsCertPath ?? "", cfg.tlsKeyPath ?? "");
+	if (cfg.tlsMode === "custom") 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({
+	return loadOrRenewSelfSigned({
 		hosts,
 		days: cfg.tlsCertMaxAgeDays
 	});
-	return material;
 }
 /**
 * Config fields that require a listener restart when they change, plus whether
@@ -1402,32 +1992,26 @@ function listenerKey(cfg, relayAvailable) {
 		relayAvailable
 	]);
 }
-/** One-line TLS description for status output. */
+/**
+* One-line TLS description for status output.
+*
+* Never generates: this is the read path behind `GET /lan-gateway/config` and
+* `lan_gateway status`, and a status query that mints an RSA key and writes a
+* certificate to disk is not a read. The material is created when the listener
+* starts, or by `lan_gateway tls-regenerate`.
+*/
 function tlsStatusLine(cfg) {
 	if (!cfg.tlsEnabled) return "off";
 	if (cfg.tlsMode === "custom") return `custom (${cfg.tlsCertPath ?? "?"}, ${cfg.tlsKeyPath ?? "?"})`;
 	try {
-		const { material } = loadOrCreateSelfSigned({
-			hosts: parseSelfSignedHosts(cfg.tlsSelfSignedHosts),
-			days: cfg.tlsCertMaxAgeDays
-		});
-		const info = describeCert(material.cert);
+		const status = readSelfSignedStatus();
+		if (status === void 0) return "self-signed (not generated yet — created when the listener starts)";
+		const info = describeCert(status.cert);
 		return `self-signed [${info.subject}] exp ${info.validTo}`;
 	} catch (error) {
 		return `self-signed (unavailable: ${error instanceof Error ? error.message : String(error)})`;
 	}
 }
-/** Whether `hostname` is loopback (127/8, localhost, ::1). */
-function isLoopbackHost(hostname) {
-	if (hostname === "localhost" || hostname === "[::1]" || hostname === "::1") return true;
-	const parts = hostname.split(".");
-	return parts.length === 4 && parts[0] === "127" && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
-}
-const READ_ONLY_METHODS = /* @__PURE__ */ new Set([
-	"GET",
-	"HEAD",
-	"OPTIONS"
-]);
 /**
 * 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
@@ -1453,28 +2037,107 @@ function isTrustedConfigRequest(req) {
 	if (!READ_ONLY_METHODS.has(method) && origin === void 0) return false;
 	return true;
 }
+/**
+* Turn a submitted config patch into the next user section: only keys the card
+* can edit, only real values, and `null` (or an emptied optional) removes the
+* key rather than storing it.
+*
+* The patch is built from the *submitted* object, never from a schema call's
+* output. Schemastery fills defaults into whatever it validates and passes
+* unknown keys through, so deriving the section from `Config(submitted)` wrote
+* `authRequired: true` (a capability that exists only to be refused) and any
+* stray key into the user's settings on every save — and, because it also
+* materialized `cookieName`, reset an operator's custom cookie name to the
+* schema default.
+*
+* A `null` value is the card's clear: the key is dropped from the patch, which
+* leaves it absent from the section, so it re-inherits the composition layer.
+*/
+function buildConfigPatch(submitted) {
+	const patch = {};
+	const clear = [];
+	const unknown = [];
+	for (const [key, value] of Object.entries(submitted)) {
+		if (!CONFIG_FIELD_KEYS.has(key)) {
+			unknown.push(key);
+			continue;
+		}
+		if (value === null || value === void 0) {
+			clear.push(key);
+			continue;
+		}
+		if (typeof value === "string" && value === "" && OPTIONAL_CONFIG_KEYS.has(key)) {
+			clear.push(key);
+			continue;
+		}
+		patch[key] = value;
+	}
+	return {
+		patch,
+		clear,
+		unknown
+	};
+}
 function apply(ctx, config) {
 	let state = loadState();
 	let gateway;
 	let startedWith;
 	let lastError;
+	/**
+	* The operator's run intent, used only while no settings service is attached.
+	* With settings present, `enabled` in the settings section *is* the intent —
+	* the card and the tool write the same field, so there is one truth rather
+	* than two that disagree.
+	*/
 	let manualOverride;
 	/** Whether the base enforces browser-session auth; set once `connection` is seen. */
 	let upstreamSessionAvailable = false;
+	/**
+	* Identifies the current `connection` handler. A provider that detaches and a
+	* new one that attaches run their disposers in an order the plugin does not
+	* control, and a stale disposer clearing `makeRelay` would strand the live
+	* provider — so a disposer only acts if it is still the latest generation.
+	*/
+	let connectionGeneration = 0;
 	/** Builds a fresh shared-session relay for a dsh port, once the base supports sessions. */
 	let makeRelay;
 	/** The authoritative config: settings section when attached, else composition. */
 	let configSource = () => config;
-	/** Serializes listener start/stop/restart so settings changes cannot race. */
-	let syncing = Promise.resolve();
+	/** Whether writes go to the settings section rather than staying in memory. */
+	let settingsAttached = false;
+	/** The settings scope for the `lan-gateway` namespace, while one is attached. */
+	let settingsScope;
+	/**
+	* The settings provider, for the one write a scope cannot express: a section
+	* key must be *removed* to re-inherit the composition layer, and only the
+	* provider's path-addressed `mutate` can unset one.
+	*/
+	let settingsProvider;
+	/**
+	* One queue for every lifecycle side effect. Settings changes, tool commands,
+	* credential changes, TLS regeneration and plugin disposal all land here, so
+	* two of them can never interleave a stop with a start.
+	*/
+	let lifecycle = Promise.resolve();
+	/** Set by the dispose hook; a start that completes after it must undo itself. */
+	let disposed = false;
 	const effective = () => configSource();
+	/** Queue one lifecycle action behind every action already running. */
+	const enqueue = (reason, action) => {
+		lifecycle = lifecycle.then(action).catch((error) => {
+			lastError = error instanceof Error ? error.message : String(error);
+			ctx.logger.warn(`dsh-lan-gateway: ${reason}: ${lastError}`);
+		});
+		return lifecycle;
+	};
 	const startGateway = async (cfg) => {
 		if (gateway !== void 0) return;
 		const problems = gatewayStartProblems(cfg, { upstreamSessionAvailable });
 		if (state.password === void 0) 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 resolved = resolveTls(cfg);
+		const tls = resolved?.material;
 		const encryptedIngress = cfg.tlsEnabled || cfg.trustedTerminator !== void 0;
 		const secureCookies = resolveSecureCookies(cfg);
 		const next = new LanGateway({
@@ -1486,12 +2149,21 @@ function apply(ctx, config) {
 			cookieName: cfg.cookieName,
 			secureCookies,
 			...tls !== void 0 ? { tls } : {},
-			...makeRelay !== void 0 ? { upstreamSession: makeRelay(dshPort) } : {}
+			...makeRelay !== void 0 ? { upstreamSession: makeRelay(dshPort) } : {},
+			onStateChange: (updated) => {
+				state = updated;
+				saveState(state);
+			}
 		}, state);
 		await next.listen();
+		if (disposed) {
+			await next.close();
+			return;
+		}
 		gateway = next;
 		startedWith = listenerKey(cfg, makeRelay !== void 0);
-		ctx.logger.info(`dsh-lan-gateway: listening on 0.0.0.0:${cfg.gatewayPort}${tls !== void 0 ? " (TLS)" : ""} -> 127.0.0.1:${dshPort}${encryptedIngress ? "" : " (plaintext, explicit allowInsecurePlaintext)"}${makeRelay !== void 0 ? " [shared upstream session relay]" : " [no upstream session relay: base has no browser-session auth]"}`);
+		ctx.logger.info(`dsh-lan-gateway: listening on ${next.boundAddress()}${tls !== void 0 ? " (TLS)" : ""} -> 127.0.0.1:${dshPort}${encryptedIngress ? "" : " (plaintext, explicit allowInsecurePlaintext)"}${makeRelay !== void 0 ? " [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 () => {
 		const current = gateway;
@@ -1502,31 +2174,43 @@ function apply(ctx, config) {
 			ctx.logger.info("dsh-lan-gateway: stopped");
 		}
 	};
+	/** The config the listener should be running under, intent included. */
+	const desiredConfig = () => {
+		const cfg = effective();
+		if (settingsAttached) return cfg;
+		return manualOverride === void 0 ? cfg : {
+			...cfg,
+			enabled: manualOverride
+		};
+	};
 	/** Reconcile the listener with the effective config (start/stop/restart). */
 	const syncGateway = (reason) => {
-		syncing = syncing.then(async () => {
+		return enqueue(reason, async () => {
 			lastError = void 0;
-			const cfg = effective();
-			const shouldRun = manualOverride ?? cfg.enabled;
-			try {
-				if (gateway === void 0) {
-					if (shouldRun) await startGateway(cfg);
-				} else if (!shouldRun) await stopGateway();
-				else if (startedWith !== listenerKey(cfg, makeRelay !== void 0)) {
-					await stopGateway();
-					await startGateway(cfg);
-				}
-			} catch (error) {
-				lastError = error instanceof Error ? error.message : String(error);
-				ctx.logger.warn(`dsh-lan-gateway: ${reason}: ${lastError}`);
+			if (disposed) return;
+			const cfg = desiredConfig();
+			if (gateway === void 0) {
+				if (cfg.enabled) await startGateway(cfg);
+			} else if (!cfg.enabled) await stopGateway();
+			else if (startedWith !== listenerKey(cfg, makeRelay !== void 0)) {
+				await stopGateway();
+				await startGateway(cfg);
 			}
 		});
-		return syncing;
 	};
-	let settingsScope;
+	/** Record the run intent where it will survive: the settings section, or memory. */
+	const setRunIntent = async (enabled) => {
+		if (settingsAttached && settingsScope !== void 0) {
+			await settingsScope.update({ enabled });
+			return;
+		}
+		manualOverride = enabled;
+	};
 	ctx.inject(["settings"], (sctx) => {
 		const scope = sctx.settings.register(NS, Config, { base: config });
 		settingsScope = scope;
+		settingsProvider = sctx.settings;
+		settingsAttached = true;
 		configSource = () => scope.get();
 		sctx.effect(() => scope.watch(() => {
 			syncGateway("settings change");
@@ -1534,10 +2218,14 @@ function apply(ctx, config) {
 		sctx.effect(() => () => {
 			configSource = () => config;
 			settingsScope = void 0;
+			settingsProvider = void 0;
+			settingsAttached = false;
+			syncGateway("settings detach");
 		});
 		syncGateway("settings attach");
 	});
 	ctx.inject(["connection"], (ccx) => {
+		const generation = ++connectionGeneration;
 		upstreamSessionAvailable = true;
 		ctx.logger.info("dsh-lan-gateway: connection service attached; upstream session relay enabled");
 		makeRelay = (dshPort) => new UpstreamSessionRelay({
@@ -1545,9 +2233,26 @@ function apply(ctx, config) {
 			authenticatedUrl: () => ccx.connection.authenticatedUrl(`http://127.0.0.1:${dshPort}`),
 			log: (message) => ctx.logger.info(`dsh-lan-gateway relay: ${message}`)
 		});
+		ccx.effect(() => () => {
+			if (generation !== connectionGeneration) return;
+			makeRelay = void 0;
+			upstreamSessionAvailable = false;
+			syncGateway("connection detach");
+		});
 		syncGateway("connection attach");
 	});
 	const configRouteHandler = async (req, res) => {
+		const snapshot = () => {
+			const cfg = effective();
+			return {
+				config: cfg,
+				running: gateway !== void 0,
+				port: cfg.gatewayPort,
+				tls: tlsStatusLine(cfg),
+				upstreamSessionAvailable,
+				lastError: lastError ?? null
+			};
+		};
 		const send = (status, body) => {
 			res.writeHead(status, { "content-type": "application/json" });
 			res.end(JSON.stringify(body));
@@ -1557,15 +2262,7 @@ function apply(ctx, config) {
 			return;
 		}
 		if (req.method === "GET") {
-			const cfg = effective();
-			send(200, {
-				config: cfg,
-				running: gateway !== void 0,
-				port: cfg.gatewayPort,
-				tls: tlsStatusLine(cfg),
-				upstreamSessionAvailable,
-				lastError: lastError ?? null
-			});
+			send(200, snapshot());
 			return;
 		}
 		if (req.method !== "POST") {
@@ -1585,41 +2282,35 @@ function apply(ctx, config) {
 			send(400, { error: "body must be a config object" });
 			return;
 		}
-		let candidate;
-		try {
-			candidate = Config(submitted);
-		} catch (error) {
-			send(400, { error: error instanceof Error ? error.message : String(error) });
-			return;
-		}
-		if (settingsScope === void 0) {
+		if (settingsProvider === void 0) {
 			send(409, { error: "settings service unavailable — edit the profile patch (cordis.patch.yml) instead" });
 			return;
 		}
+		const { patch, clear, unknown } = buildConfigPatch(submitted);
+		const candidate = Config({
+			...effective(),
+			...patch
+		});
 		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;
 		}
-		const section = {};
-		for (const [key, value] of Object.entries(candidate)) {
-			if (value === null || value === void 0) continue;
-			if (typeof value === "string" && value === "" && OPTIONAL_CONFIG_KEYS.has(key)) continue;
-			section[key] = value;
-		}
 		try {
-			await settingsScope.replace(section);
+			const ops = [...Object.entries(patch).map(([key, value]) => ({
+				op: "set",
+				path: [key],
+				value
+			})), ...clear.map((key) => ({
+				op: "unset",
+				path: [key]
+			}))];
+			if (ops.length > 0) await settingsProvider.mutate(NS, ops);
 			await syncGateway("config route save");
-			const cfg = effective();
-			send(200, {
-				config: cfg,
-				running: gateway !== void 0,
-				port: cfg.gatewayPort,
-				tls: tlsStatusLine(cfg),
-				upstreamSessionAvailable,
-				lastError: lastError ?? null
-			});
+			const next = { ...snapshot() };
+			if (unknown.length > 0) next["ignored"] = unknown;
+			send(200, next);
 		} catch (error) {
 			send(409, { error: error instanceof Error ? error.message : String(error) });
 		}
@@ -1631,27 +2322,27 @@ function apply(ctx, config) {
 	}), "dsh-lan-gateway: config route");
 	ctx.tools.register(lanGatewayTool({
 		status() {
-			const cfg = effective();
+			const cfg = desiredConfig();
 			const dshPort = cfg.dshTargetPort ?? ctx.webServer.port;
 			const encrypted = cfg.tlsEnabled || cfg.trustedTerminator !== void 0;
 			return {
 				ok: true,
-				message: `LAN gateway: ${gateway !== void 0 ? `LISTENING on 0.0.0.0:${cfg.gatewayPort}` : "stopped"}\n- dsh target: 127.0.0.1:${dshPort}\n- password: ${state.password !== void 0 ? "set" : "NOT SET"}\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 !== void 0 ? `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 !== void 0 ? `\n- manual override: ${manualOverride ? "enabled" : "disabled"}` : "") + (lastError !== void 0 ? `\n- last error: ${lastError}` : "")
+				message: `LAN gateway: ${gateway !== void 0 ? `LISTENING on ${gateway.boundAddress()}` : "stopped"}\n- dsh target: 127.0.0.1:${dshPort}\n- password: ${state.password !== void 0 ? "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 !== void 0 ? `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 !== void 0 && !settingsAttached ? `\n- manual override: ${manualOverride ? "enabled" : "disabled"}` : "") + (lastError !== void 0 ? `\n- last error: ${lastError}` : "")
 			};
 		},
 		async enable() {
-			manualOverride = true;
+			await setRunIntent(true);
 			await syncGateway("tool enable");
 			return gateway !== void 0 ? {
 				ok: true,
-				message: `Gateway enabled: listening on 0.0.0.0:${effective().gatewayPort}`
+				message: `Gateway enabled: listening on ${gateway.boundAddress()}`
 			} : {
 				ok: false,
 				message: `Failed to enable gateway: ${lastError ?? "unknown error"}`
 			};
 		},
 		async disable() {
-			manualOverride = false;
+			await setRunIntent(false);
 			await syncGateway("tool disable");
 			return {
 				ok: true,
@@ -1664,23 +2355,21 @@ function apply(ctx, config) {
 				message: "Password must be at least 8 characters."
 			};
 			const setting = password !== void 0 && password.length > 0;
-			const previous = state;
-			state = setPassword(state, setting ? password : void 0);
+			const hadPassword = state.password !== void 0;
+			state = await setPassword(state, setting ? password : void 0);
 			saveState(state);
 			gateway?.setState(state);
 			if (!setting) {
-				manualOverride = false;
-				if (gateway !== void 0) {
-					await stopGateway();
+				await setRunIntent(false);
+				return enqueue("password cleared", async () => {
+					if (gateway !== void 0) await stopGateway();
 					lastError = "Password cleared — the gateway listener was stopped (a password is required to run).";
-					syncGateway("password cleared");
-				}
-				return {
+				}).then(() => ({
 					ok: true,
 					message: "Password cleared. Session epoch advanced and the gateway listener was stopped — set a password before enabling it again."
-				};
+				}));
 			}
-			previous === void 0 ? syncGateway("password set") : Promise.resolve();
+			if (!hadPassword) await syncGateway("password set");
 			return {
 				ok: true,
 				message: "Password set. Session epoch advanced — every previously issued session is now invalid; all sources must sign in again."
@@ -1711,32 +2400,38 @@ function apply(ctx, config) {
 				ok: false,
 				message: "tlsSelfSignedHosts must name at least one host (DNS name or IP)."
 			};
-			try {
-				regenerateSelfSigned({
-					hosts,
-					days: cfg.tlsCertMaxAgeDays
-				});
-				if (gateway !== void 0) {
-					await stopGateway();
-					await startGateway(effective());
+			let failure;
+			await enqueue("tls regenerate", async () => {
+				try {
+					regenerateSelfSigned({
+						hosts,
+						days: cfg.tlsCertMaxAgeDays
+					});
+					if (gateway !== void 0) {
+						await stopGateway();
+						await startGateway(effective());
+					}
 					lastError = void 0;
+				} catch (error) {
+					failure = error instanceof Error ? error.message : String(error);
 				}
-				return {
-					ok: true,
-					message: "Self-signed certificate regenerated (new key). Listener restarted with the new certificate."
-				};
-			} catch (error) {
-				return {
-					ok: false,
-					message: `Failed to regenerate TLS certificate: ${error instanceof Error ? error.message : String(error)}`
-				};
-			}
+			});
+			return failure === void 0 ? {
+				ok: true,
+				message: "Self-signed certificate regenerated (new key). Listener restarted with the new certificate."
+			} : {
+				ok: false,
+				message: `Failed to regenerate TLS certificate: ${failure}`
+			};
 		}
 	}));
 	ctx.effect(() => {
 		syncGateway("boot");
-		return stopGateway;
+		return async () => {
+			disposed = true;
+			await enqueue("dispose", stopGateway);
+		};
 	}, "dsh-lan-gateway: listener lifecycle");
 }
 //#endregion
-export { Config, apply, gatewayStartProblems, inject, isTrustedConfigRequest, name, resolveSecureCookies };
+export { Config, apply, buildConfigPatch, gatewayStartProblems, inject, isTrustedConfigRequest, name, resolveSecureCookies };