@riceawa/dsh-lan-gateway 0.5.4 → 0.6.0

package/lib/index.js

@@ -1,4 +1,4 @@
-import { X509Certificate, createHmac, createSign, generateKeyPairSync, randomBytes, scrypt, 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.
@@ -216,6 +223,85 @@ var RateLimiter = class RateLimiter {
 	}
 };
 //#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";
@@ -306,246 +392,257 @@ function readBody(req, maxBytes, res) {
 	});
 }
 //#endregion
-//#region src/state.ts
+//#region src/upstream-session.ts
 /**
-* Persistent runtime state for the LAN gateway: the cookie-signing secret and
-* the scrypt password hash. Lives in `~/.dsh/lan-gateway/state.json` (0600),
-* NOT in the schemastery Config — secrets must never surface in
-* `--dump-config` output. Writes are atomic (temp file + rename).
+* Shared upstream session relay for session-capable dsh bases (>= 0.1.2).
 *
-* @module @riceawa/dsh-lan-gateway/state
-*/
-/** The state directory: `~/.dsh/lan-gateway`. */
-function stateDir(home = homedir()) {
-	return join(home, ".dsh", "lan-gateway");
-}
-const STATE_FILENAME = "state.json";
-/** 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 = await deriveKey(password, Buffer.from(salt, "hex"), expected.length);
-		return expected.length === actual.length && timingSafeEqual(expected, actual);
-	} catch {
-		return false;
-	}
-}
-/**
-* 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.
+* 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
 */
-function setPassword(state, password) {
-	const base = {
-		cookieSecret: state.cookieSecret,
-		sessionEpoch: state.sessionEpoch + 1
-	};
-	if (password === void 0) return base;
-	const salt = randomBytes(16);
-	const hash = scryptSync(password, salt, 64);
-	return {
-		...base,
-		password: {
-			hash: hash.toString("hex"),
-			salt: salt.toString("hex")
-		}
-	};
+/** 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();
 }
 /**
-* 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.
+* 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 revokeSession(state, sid, expiresMs) {
-	const 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);
+function pathOf$1(url) {
 	try {
-		const raw = readFileSync(join(dir, STATE_FILENAME), "utf8");
-		const parsed = JSON.parse(raw);
-		if (typeof parsed?.cookieSecret === "string" && parsed.cookieSecret.length >= 16) {
-			const sessionEpoch = typeof parsed.sessionEpoch === "number" && Number.isSafeInteger(parsed.sessionEpoch) ? parsed.sessionEpoch : 0;
-			const base = {
-				cookieSecret: parsed.cookieSecret,
-				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();
+		return new URL(url).pathname;
 	} catch {
-		return defaultState();
+		return "<unparseable>";
 	}
 }
-/** Persist state atomically. */
-function saveState(state, home = homedir()) {
-	const dir = stateDir(home);
-	mkdirSync(dir, { recursive: true });
-	const target = join(dir, STATE_FILENAME);
-	const tmp = join(dir, `.state.${process.pid}.tmp`);
-	writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 384 });
-	renameSync(tmp, target);
-	try {
-		chmodSync(target, 384);
-	} catch {}
+/** 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();
 }
-//#endregion
-//#region src/gateway.ts
-/**
-* 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
-*   `X-Forwarded-For`). Classification alone grants nothing: by default every
-*   source — loopback, LAN, internet — must present a valid gateway session.
-*   `lanPasswordless` (an explicit opt-in, false by default) is the one way a
-*   LAN/loopback source skips the gateway login, and it is only ever allowed
-*   against a session-capable dsh base (enforced by the plugin, which owns the
-*   fail-closed guard).
-* - The gateway never forwards its own management surface (`/lan-gateway/*`)
-*   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.
-* - 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 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"
-]);
-/** The upstream browser-session cookie name prefix; the relay owns this namespace. */
-const UPSTREAM_COOKIE_PREFIX$1 = "dsh-auth-";
-/**
-* Headers a proxy must not forward in either direction (RFC 9110 §7.6.1), plus
-* the non-standard proxy-connection.
-*/
-const HOP_BY_HOP_HEADERS = /* @__PURE__ */ new Set([
-	"connection",
-	"keep-alive",
-	"proxy-authenticate",
-	"proxy-authorization",
-	"proxy-connection",
-	"te",
-	"trailer",
-	"transfer-encoding",
-	"upgrade"
-]);
 /**
-* Headers by which a client asserts where a request came from. The gateway
-* classifies on `socket.remoteAddress` and never reads these, so relaying a
-* caller's own values only hands the next hop a forgeable claim.
+* 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.
 */
-const FORWARDING_HEADERS = [
-	"forwarded",
-	"x-forwarded-for",
-	"x-forwarded-host",
-	"x-forwarded-port",
-	"x-forwarded-proto",
-	"x-real-ip"
-];
-/** Whether a Cookie fragment names the upstream session cookie. */
-function isUpstreamSessionPair(pair) {
-	return pair.startsWith(UPSTREAM_COOKIE_PREFIX$1);
+function isUpstreamCookiePair(pair) {
+	return pair.trim().startsWith(UPSTREAM_COOKIE_PREFIX);
 }
 /**
-* Drop every `dsh-auth-*` pair from a Cookie header, returning the remainder
-* (possibly '').
+* 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.
 *
-* `attachUpstreamSession` appends the relay's session to the client's own
-* cookie, and upstream reads the FIRST name match. A client that holds any
-* `dsh-auth-<hash>` — typically one minted before dsh's signing secret was
-* reset, so still present but no longer verifying — would therefore shadow the
-* relay's session on every request. That draws a 401, the gateway reads the
-* 401 as "upstream revoked our session" and discards it, the next request
-* re-acquires, and the client's stale cookie shadows that one too: a loop that
-* never converges. Stripping the namespace makes the relay's copy the only one.
+* 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 withoutUpstreamSessionPairs(cookie) {
-	return cookie.split(";").map((pair) => pair.trim()).filter((pair) => pair !== "" && !isUpstreamSessionPair(pair)).join("; ");
+function isUpstreamSessionCookie(setCookie) {
+	const name = cookieNameOf(setCookie);
+	return name.startsWith(UPSTREAM_COOKIE_PREFIX) && name.length > 9;
 }
-/** Prefixes the gateway owns and must never relay to dsh. */
-function isOwnedPath(pathname) {
-	return pathname === "/lan-gateway" || pathname.startsWith("/lan-gateway/");
+/** 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]);
 }
 /**
-* 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
+* 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.
@@ -557,131 +654,507 @@ function isOwnedPath(pathname) {
 * 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$1(url) {
+function pathOf(url) {
 	try {
 		return new URL(url, "http://gateway.invalid").pathname.replace(/\/+$/, "") || "/";
 	} catch {
 		return url;
 	}
 }
-/** 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
-* request. Created by the plugin on enable; torn down by the plugin on
-* disable or tree disposal.
+* 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.
 */
-var LanGateway = class {
-	config;
-	server;
-	loginLimiter = new RateLimiter(LOGIN_ATTEMPTS_LIMIT, LOGIN_ATTEMPTS_WINDOW_MS);
-	state;
-	disposed = false;
-	/**
-	* Established WebSockets (upgraded client sockets), each keyed by the session
-	* that opened it. A socket outlives the request that authenticated it, so it
-	* has to be closable by session: on an epoch bump every socket dies, and on
-	* sign-out only that session's. The value is undefined for a cookie minted
-	* before per-session ids existed, which only a wholesale revocation reaches.
-	*/
-	activeDuplexes = /* @__PURE__ */ new Map();
-	constructor(config, state) {
-		this.config = config;
-		this.state = state;
-		const handle = (req, res) => {
-			this.handleHttp(req, res);
-		};
-		this.server = this.config.tls !== void 0 ? https.createServer({
-			cert: this.config.tls.cert,
-			key: this.config.tls.key
-		}, handle) : http.createServer(handle);
-		this.server.on("upgrade", (req, socket, head) => {
-			this.handleUpgrade(req, socket, head);
-		});
+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);
 	}
-	/** Replace the in-memory state; bumps of `sessionEpoch` revoke live sessions and sockets. */
-	setState(state) {
-		if (state.sessionEpoch !== this.state.sessionEpoch) this.destroyActiveDuplexes();
-		this.state = state;
+}
+/**
+* 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;
 	}
-	/**
-	* 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) => {
-				this.server.off("listening", onListening);
-				reject(err);
-			};
-			const onListening = () => {
-				this.server.off("error", onError);
-				resolve();
-			};
-			this.server.once("error", onError);
-			this.server.once("listening", onListening);
-			this.server.listen(this.config.gatewayPort);
-		});
+	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;
 	}
-	/** 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}`;
+	const relayed = options.upstreamCookie;
+	if (relayed !== void 0 && relayed !== "") {
+		const existing = out.cookie;
+		out.cookie = typeof existing === "string" && existing !== "" ? `${existing}; ${relayed}` : relayed;
 	}
-	/** Close the server, drop upgraded sockets, and stop accepting connections. */
-	async close() {
-		if (this.disposed) return;
-		this.disposed = true;
-		this.destroyActiveDuplexes();
-		return new Promise((resolve) => {
+	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
+* the scrypt password hash. Lives in `~/.dsh/lan-gateway/state.json` (0600),
+* NOT in the schemastery Config — secrets must never surface in
+* `--dump-config` output. Writes are atomic (temp file + rename).
+*
+* @module @riceawa/dsh-lan-gateway/state
+*/
+/** The state directory: `~/.dsh/lan-gateway`. */
+function stateDir(home = homedir()) {
+	return join(home, ".dsh", "lan-gateway");
+}
+const STATE_FILENAME = "state.json";
+/** 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 = await deriveKey(password, Buffer.from(salt, "hex"), expected.length);
+		return expected.length === actual.length && timingSafeEqual(expected, actual);
+	} catch {
+		return false;
+	}
+}
+/**
+* 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.
+*/
+async function setPassword(state, password) {
+	const base = {
+		cookieSecret: state.cookieSecret,
+		sessionEpoch: state.sessionEpoch + 1
+	};
+	if (password === void 0) return base;
+	const salt = randomBytes(16);
+	const hash = await deriveKey(password, salt, 64);
+	return {
+		...base,
+		password: {
+			hash: hash.toString("hex"),
+			salt: salt.toString("hex")
+		}
+	};
+}
+/**
+* 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);
+	try {
+		const raw = readFileSync(join(dir, STATE_FILENAME), "utf8");
+		const parsed = JSON.parse(raw);
+		if (typeof parsed?.cookieSecret === "string" && parsed.cookieSecret.length >= 16) {
+			const sessionEpoch = typeof parsed.sessionEpoch === "number" && Number.isSafeInteger(parsed.sessionEpoch) ? parsed.sessionEpoch : 0;
+			const base = {
+				cookieSecret: parsed.cookieSecret,
+				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();
+	} catch {
+		return defaultState();
+	}
+}
+/** Persist state atomically. */
+function saveState(state, home = homedir()) {
+	const dir = stateDir(home);
+	mkdirSync(dir, { recursive: true });
+	const target = join(dir, STATE_FILENAME);
+	const tmp = join(dir, `.state.${process.pid}.tmp`);
+	writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 384 });
+	renameSync(tmp, target);
+	try {
+		chmodSync(target, 384);
+	} catch {}
+}
+//#endregion
+//#region src/gateway.ts
+/**
+* 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
+*   `X-Forwarded-For`). Classification alone grants nothing: by default every
+*   source — loopback, LAN, internet — must present a valid gateway session.
+*   `lanPasswordless` (an explicit opt-in, false by default) is the one way a
+*   LAN/loopback source skips the gateway login, and it is only ever allowed
+*   against a session-capable dsh base (enforced by the plugin, which owns the
+*   fail-closed guard).
+* - The gateway never forwards its own management surface (`/lan-gateway/*`)
+*   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. 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 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;
+/**
+* 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
+* request. Created by the plugin on enable; torn down by the plugin on
+* disable or tree disposal.
+*/
+var LanGateway = class {
+	config;
+	server;
+	loginLimiter = new RateLimiter(LOGIN_ATTEMPTS_LIMIT, LOGIN_ATTEMPTS_WINDOW_MS);
+	state;
+	disposed = false;
+	/**
+	* 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;
+		const handle = (req, res) => {
+			this.handleHttp(req, res);
+		};
+		this.server = this.config.tls !== void 0 ? https.createServer({
+			cert: this.config.tls.cert,
+			key: this.config.tls.key
+		}, handle) : http.createServer(handle);
+		this.server.on("upgrade", (req, socket, head) => {
+			this.handleUpgrade(req, socket, head);
+		});
+	}
+	/** Replace the in-memory state; bumps of `sessionEpoch` revoke live sessions and sockets. */
+	setState(state) {
+		if (state.sessionEpoch !== this.state.sessionEpoch) {
+			this.gate += 1;
+			this.destroyAllSockets();
+		}
+		this.state = state;
+	}
+	/**
+	* 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) => {
+				this.server.off("listening", onListening);
+				reject(err);
+			};
+			const onListening = () => {
+				this.server.off("error", onError);
+				resolve();
+			};
+			this.server.once("error", onError);
+			this.server.once("listening", onListening);
+			this.server.listen(this.config.gatewayPort);
+		});
+	}
+	/** 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.gate += 1;
+		this.destroyAllSockets();
+		return new Promise((resolve) => {
 			this.server.close(() => resolve());
 			this.server.closeAllConnections();
 		});
 	}
-	destroyActiveDuplexes() {
-		for (const socket of this.activeDuplexes.keys()) 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. */
-	destroyDuplexesFor(sid) {
-		for (const [socket, owner] of this.activeDuplexes) {
-			if (owner !== sid) continue;
-			this.activeDuplexes.delete(socket);
+	destroySocketsFor(sid) {
+		for (const [socket, tracked] of this.sockets) {
+			if (tracked.sid !== sid) continue;
+			this.sockets.delete(socket);
 			socket.destroy();
 		}
 	}
-	trackDuplex(socket, sid) {
-		this.activeDuplexes.set(socket, sid);
+	/** 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 = this.sessionCookie(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;
@@ -691,19 +1164,20 @@ var LanGateway = class {
 	authorized(req) {
 		return this.session(req) !== void 0;
 	}
-	/** Whether this source must present a gateway session (default: everyone). */
-	requiresLogin(source) {
-		return !(this.config.lanPasswordless && source !== "internet");
-	}
-	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",
@@ -715,30 +1189,14 @@ 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$1(url);
+		const pathname = pathOf(url);
 		const source = this.sourceOf(req);
 		if (pathname === "/__login") {
 			this.handleLogin(req, res);
@@ -753,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;
@@ -766,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;
@@ -776,9 +1233,14 @@ 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(async (body) => {
@@ -789,7 +1251,13 @@ var LanGateway = class {
 			} catch {
 				password = void 0;
 			}
-			if (!(password !== void 0 && await 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;
 			}
@@ -825,7 +1293,7 @@ var LanGateway = class {
 			res.end();
 			return;
 		}
-		if (!this.sameSiteAllowed(req, false)) {
+		if (!sameSiteAllowed(req, false)) {
 			res.writeHead(403, this.securityHeaders());
 			res.end("forbidden");
 			return;
@@ -834,7 +1302,7 @@ var LanGateway = class {
 		if (claims?.sid !== void 0) {
 			this.state = revokeSession(this.state, claims.sid, claims.exp);
 			this.config.onStateChange?.(this.state);
-			this.destroyDuplexesFor(claims.sid);
+			this.destroySocketsFor(claims.sid);
 		}
 		res.writeHead(302, {
 			location: "/",
@@ -843,63 +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;
-		}
-		for (const name of FORWARDING_HEADERS) delete headers[name];
-		if (typeof headers.cookie === "string") {
-			const kept = withoutUpstreamSessionPairs(headers.cookie);
-			if (kept === "") delete headers.cookie;
-			else headers.cookie = kept;
-		}
-		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 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.
-	*/
-	downstreamHeaders(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((entry) => !isUpstreamSessionPair(entry.trim()));
-				if (list.length > 0) headers[key] = list;
-				continue;
-			}
-			headers[key] = value;
-		}
-		return headers;
+	/** 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,
@@ -908,7 +1333,7 @@ var LanGateway = class {
 			headers
 		}, (proxyRes) => {
 			if (attached && session !== void 0 && proxyRes.statusCode === 401) session.invalidate();
-			res.writeHead(proxyRes.statusCode ?? 502, this.downstreamHeaders(proxyRes.headers));
+			res.writeHead(proxyRes.statusCode ?? 502, downstreamResponseHeaders(proxyRes.headers));
 			proxyRes.pipe(res);
 		});
 		proxyReq.on("error", () => {
@@ -920,7 +1345,7 @@ var LanGateway = class {
 	/** Forward a WebSocket upgrade through the same gates, splicing the duplex to dsh. */
 	async handleUpgrade(req, socket, head) {
 		const url = req.url ?? "/";
-		const pathname = pathOf$1(url);
+		const pathname = pathOf(url);
 		const source = this.sourceOf(req);
 		const refuse = (status) => {
 			socket.write(`HTTP/1.1 ${status} ${status === 401 ? "Unauthorized" : "Forbidden"}\r\nConnection: close\r\n\r\n`);
@@ -931,18 +1356,29 @@ var LanGateway = class {
 			return;
 		}
 		const claims = this.session(req);
-		if (this.requiresLogin(source) && claims === void 0) {
+		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,
@@ -950,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, claims?.sid);
+			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);
@@ -961,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();
 	}
 };
@@ -1150,444 +1613,283 @@ function generateSelfSignedCert(options) {
 		modulusLength: 2048,
 		publicExponent: 65537
 	});
-	const commonName = options.commonName?.trim() || hosts[0];
-	const serial = randomBytes(16);
-	serial[0] &= 127;
-	const issuer = derSeq(derSet(derSeq(derOid("2.5.4.3"), derUtf8String(commonName))));
-	const subject = issuer;
-	const notBefore = /* @__PURE__ */ new Date(Date.now() - 36e5);
-	const notAfter = new Date(notBefore.getTime() + options.days * 864e5);
-	const validity = derSeq(derUtcTime(notBefore), derUtcTime(notAfter));
-	const spki = publicKey.export({
-		type: "spki",
-		format: "der"
-	});
-	const extensionsWrapper = derTag(163, derSeq(derSeq(derOid("2.5.29.19"), derBoolean(true), derOctetString(derSeq())), derSeq(derOid("2.5.29.15"), derBoolean(true), derOctetString(derBitString(Buffer.from([160])))), derSeq(derOid("2.5.29.37"), derOctetString(derSeq(derOid("1.3.6.1.5.5.7.3.1")))), derSeq(derOid("2.5.29.17"), derOctetString(derSeq(...hosts.map(sanGeneralName))))));
-	const tbs = derSeq(derTag(160, derInt(Buffer.from([2]))), derInt(serial), sha256WithRsa(), issuer, validity, subject, spki, extensionsWrapper);
-	const signature = createSign("sha256").update(tbs).end().sign(privateKey);
-	const certDer = derSeq(tbs, sha256WithRsa(), derBitString(signature));
-	return {
-		certDer,
-		certPem: pemEncode("CERTIFICATE", certDer),
-		keyPem: privateKey.export({
-			type: "pkcs8",
-			format: "pem"
-		}).toString(),
-		publicKey,
-		privateKey
-	};
-}
-//#endregion
-//#region src/tls.ts
-/**
-* TLS material management for the gateway: self-signed certificates are
-* generated once and persisted under `~/.dsh/lan-gateway/tls/` (0600) so
-* restarts reuse the same certificate instead of minting a new one every
-* boot; custom certificates are read straight from user-supplied PEM paths.
-*
-* @module @riceawa/dsh-lan-gateway/tls
-*/
-/** The TLS state directory: `~/.dsh/lan-gateway/tls`. */
-function tlsDir(home = homedir()) {
-	return join(home, ".dsh", "lan-gateway", "tls");
-}
-const SELF_SIGNED_CERT_FILE = "selfsigned.crt";
-const SELF_SIGNED_KEY_FILE = "selfsigned.key";
-function privateWrite(path, content) {
-	writeFileSync(path, content, { mode: 384 });
-	try {
-		chmodSync(path, 384);
-	} catch {}
-}
-/**
-* Load the persisted self-signed certificate, generating it on first use.
-* @param opts - hosts / validity for a fresh certificate.
-* @param home - dsh home override (tests).
-* @returns the material and whether it was just created.
-*/
-function loadOrCreateSelfSigned(opts, 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)) try {
-		const cert = readFileSync(certPath, "utf8");
-		const key = readFileSync(keyPath, "utf8");
-		new X509Certificate(cert);
-		return {
-			material: {
-				cert,
-				key
-			},
-			created: false
-		};
-	} catch {}
-	const material = generateSelfSignedMaterial(opts);
-	mkdirSync(dir, { recursive: true });
-	privateWrite(keyPath, material.key);
-	privateWrite(certPath, material.cert);
-	return {
-		material,
-		created: true
-	};
-}
-/**
-* Load the self-signed material a listener should serve: generate it on first
-* use, reuse the persisted pair otherwise, and replace a persisted certificate
-* whose validity has already lapsed.
-*
-* Nothing renews a self-signed certificate in place, and a browser refuses a
-* lapsed one outright, so without this a certificate that ran out would keep
-* being served until an operator happened to read the expiry date out of
-* `status` and act on it. Renewing mints a fresh key, so a client that had
-* trusted the old certificate has to trust the new one — but that is the case
-* either way, the old one having lapsed.
-*/
-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`.
-*/
-function regenerateSelfSigned(opts, home = homedir()) {
-	const dir = tlsDir(home);
-	mkdirSync(dir, { recursive: true });
-	const material = generateSelfSignedMaterial(opts);
-	privateWrite(join(dir, SELF_SIGNED_KEY_FILE), material.key);
-	privateWrite(join(dir, SELF_SIGNED_CERT_FILE), material.cert);
-	return material;
-}
-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");
-	const { certPem, keyPem } = generateSelfSignedCert({
-		hosts,
-		days: opts.days,
-		...opts.commonName !== void 0 ? { commonName: opts.commonName } : {}
-	});
-	return {
-		cert: certPem,
-		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);
-}
-/**
-* 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();
-			}
-		}
+	const commonName = options.commonName?.trim() || hosts[0];
+	const serial = randomBytes(16);
+	serial[0] &= 127;
+	const issuer = derSeq(derSet(derSeq(derOid("2.5.4.3"), derUtf8String(commonName))));
+	const subject = issuer;
+	const notBefore = /* @__PURE__ */ new Date(Date.now() - 36e5);
+	const notAfter = new Date(notBefore.getTime() + options.days * 864e5);
+	const validity = derSeq(derUtcTime(notBefore), derUtcTime(notAfter));
+	const spki = publicKey.export({
+		type: "spki",
+		format: "der"
 	});
+	const extensionsWrapper = derTag(163, derSeq(derSeq(derOid("2.5.29.19"), derBoolean(true), derOctetString(derSeq())), derSeq(derOid("2.5.29.15"), derBoolean(true), derOctetString(derBitString(Buffer.from([160])))), derSeq(derOid("2.5.29.37"), derOctetString(derSeq(derOid("1.3.6.1.5.5.7.3.1")))), derSeq(derOid("2.5.29.17"), derOctetString(derSeq(...hosts.map(sanGeneralName))))));
+	const tbs = derSeq(derTag(160, derInt(Buffer.from([2]))), derInt(serial), sha256WithRsa(), issuer, validity, subject, spki, extensionsWrapper);
+	const signature = createSign("sha256").update(tbs).end().sign(privateKey);
+	const certDer = derSeq(tbs, sha256WithRsa(), derBitString(signature));
+	return {
+		certDer,
+		certPem: pemEncode("CERTIFICATE", certDer),
+		keyPem: privateKey.export({
+			type: "pkcs8",
+			format: "pem"
+		}).toString(),
+		publicKey,
+		privateKey
+	};
 }
 //#endregion
-//#region src/upstream-session.ts
+//#region src/tls.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.
+* TLS material management for the gateway: self-signed certificates are
+* generated once and persisted under `~/.dsh/lan-gateway/tls/` (0600) so
+* restarts reuse the same certificate instead of minting a new one every
+* boot; custom certificates are read straight from user-supplied PEM paths.
 *
-* @module @riceawa/dsh-lan-gateway/upstream-session
+* @module @riceawa/dsh-lan-gateway/tls
 */
-/** 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 TLS state directory: `~/.dsh/lan-gateway/tls`. */
+function tlsDir(home = homedir()) {
+	return join(home, ".dsh", "lan-gateway", "tls");
 }
-/**
-* The pathname of a URL, for logging. Never the whole URL: the authenticated
-* URL carries the launch token as a query parameter, and that token is a
-* bearer credential for the upstream harness.
-*/
-function pathOf(url) {
+const SELF_SIGNED_CERT_FILE = "selfsigned.crt";
+const SELF_SIGNED_KEY_FILE = "selfsigned.key";
+function privateWrite(path, content) {
+	writeFileSync(path, content, { mode: 384 });
 	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();
+		chmodSync(path, 384);
+	} catch {}
 }
 /**
-* 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.
+* Load the persisted self-signed certificate, generating it on first use.
+* @param opts - hosts / validity for a fresh certificate.
+* @param home - dsh home override (tests).
+* @returns the material and whether it was just created.
 */
-function isUpstreamSessionCookie(setCookie) {
-	const name = cookieNameOf(setCookie);
-	return name.startsWith(UPSTREAM_COOKIE_PREFIX) && name.length > 9;
+function loadOrCreateSelfSigned(opts, 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)) try {
+		const cert = readFileSync(certPath, "utf8");
+		const key = readFileSync(keyPath, "utf8");
+		new X509Certificate(cert);
+		return {
+			material: {
+				cert,
+				key
+			},
+			created: false
+		};
+	} catch {}
+	const material = generateSelfSignedMaterial(opts);
+	mkdirSync(dir, { recursive: true });
+	privateWrite(keyPath, material.key);
+	privateWrite(certPath, material.cert);
+	return {
+		material,
+		created: true
+	};
 }
-/** 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]);
+/**
+* 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
+	};
 }
 /**
-* 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).
+* Force-regenerate the self-signed certificate (new key + cert), replacing
+* the persisted files. Used by `lan_gateway tls-regenerate`.
 */
-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();
-	});
+function regenerateSelfSigned(opts, home = homedir()) {
+	const dir = tlsDir(home);
+	mkdirSync(dir, { recursive: true });
+	const material = generateSelfSignedMaterial(opts);
+	privateWrite(join(dir, SELF_SIGNED_KEY_FILE), material.key);
+	privateWrite(join(dir, SELF_SIGNED_CERT_FILE), material.cert);
+	return material;
 }
 /**
-* 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.
+* 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.
 */
-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 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");
+	const { certPem, keyPem } = generateSelfSignedCert({
+		hosts,
+		days: opts.days,
+		...opts.commonName !== void 0 ? { commonName: opts.commonName } : {}
+	});
+	return {
+		cert: certPem,
+		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)}`);
 	}
-	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 ${pathOf(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. */
@@ -1595,40 +1897,91 @@ const name = "dsh-lan-gateway";
 /** Requires the web server service (binds before this row's apply runs) and the tool registry. */
 const inject = ["webServer", "tools"];
 /**
-* The `lan-gateway` user-settings namespace, mirroring the composition schema.
-* A plain string literal: dsh-settings dropped the `settingsNamespace()` brand
-* helper in 0.1.2-rc.1 and `register` validates the literal itself, so this
-* shape works against both that release line and the older branded one.
+* Schemastery configuration validated by the Loader.
+*
+* Every field is `.volatile()`, which is what lets the Settings service write
+* it: 0.1.7 projects only volatile fields into forms and refuses an edit to any
+* other path (`not volatile`). The mark also changes the runtime shape — a
+* volatile field arrives as a reference (see `ConfigRefs`), never as the plain
+* value the rest of this file expects — so read it through `readConfig`.
 */
-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),
-	gatewayPort: z.natural().min(1).max(65535).default(3081),
-	dshTargetPort: z.natural().min(1).max(65535),
-	lanCidrs: z.array(String).default([...DEFAULT_LAN_CIDR_STRINGS]),
-	lanPasswordless: z.boolean().default(false),
-	authRequired: z.boolean().default(true),
-	cookieMaxAgeDays: z.natural().min(1).max(365).default(7),
-	cookieName: z.string().default("dsh_gw_auth"),
-	tlsEnabled: z.boolean().default(false),
-	tlsMode: z.union([z.const("self-signed"), z.const("custom")]).default("self-signed"),
-	tlsCertPath: z.string(),
-	tlsKeyPath: z.string(),
-	tlsSelfSignedHosts: z.string().default("localhost"),
-	tlsCertMaxAgeDays: z.natural().min(1).max(3650).default(825),
-	allowInsecurePlaintext: z.boolean().default(false),
-	trustedTerminator: z.string(),
-	secureCookies: z.boolean()
+	enabled: z.boolean().default(false).volatile(),
+	gatewayPort: z.natural().min(1).max(65535).default(3081).volatile(),
+	dshTargetPort: z.natural().min(1).max(65535).volatile(),
+	lanCidrs: z.array(String).default([...DEFAULT_LAN_CIDR_STRINGS]).volatile(),
+	lanPasswordless: z.boolean().default(false).volatile(),
+	authRequired: z.boolean().default(true).volatile(),
+	cookieMaxAgeDays: z.natural().min(1).max(365).default(7).volatile(),
+	cookieName: z.string().default("dsh_gw_auth").volatile(),
+	tlsEnabled: z.boolean().default(false).volatile(),
+	tlsMode: z.union([z.const("self-signed"), z.const("custom")]).default("self-signed").volatile(),
+	tlsCertPath: z.string().volatile(),
+	tlsKeyPath: z.string().volatile(),
+	tlsSelfSignedHosts: z.string().default("localhost").volatile(),
+	tlsCertMaxAgeDays: z.natural().min(1).max(3650).default(825).volatile(),
+	allowInsecurePlaintext: z.boolean().default(false).volatile(),
+	trustedTerminator: z.string().volatile(),
+	secureCookies: z.boolean().volatile()
 });
 /**
+* Unwrap the config references into the plain values every other function in
+* this file reads. Called on each access rather than once, because a settings
+* write updates the references in place.
+* @param refs - the config object handed to `apply`.
+* @returns one detached plain snapshot.
+*/
+function readConfig(refs) {
+	const dshTargetPort = refs.dshTargetPort?.get();
+	const authRequired = refs.authRequired?.get();
+	const tlsCertPath = refs.tlsCertPath?.get();
+	const tlsKeyPath = refs.tlsKeyPath?.get();
+	const tlsSelfSignedHosts = refs.tlsSelfSignedHosts?.get();
+	const trustedTerminator = refs.trustedTerminator?.get();
+	const secureCookies = refs.secureCookies?.get();
+	return {
+		enabled: refs.enabled.get(),
+		gatewayPort: refs.gatewayPort.get(),
+		lanCidrs: [...refs.lanCidrs.get()],
+		lanPasswordless: refs.lanPasswordless.get(),
+		cookieMaxAgeDays: refs.cookieMaxAgeDays.get(),
+		cookieName: refs.cookieName.get(),
+		tlsEnabled: refs.tlsEnabled.get(),
+		tlsMode: refs.tlsMode.get(),
+		tlsCertMaxAgeDays: refs.tlsCertMaxAgeDays.get(),
+		allowInsecurePlaintext: refs.allowInsecurePlaintext.get(),
+		...dshTargetPort !== void 0 ? { dshTargetPort } : {},
+		...authRequired !== void 0 ? { authRequired } : {},
+		...tlsCertPath !== void 0 ? { tlsCertPath } : {},
+		...tlsKeyPath !== void 0 ? { tlsKeyPath } : {},
+		...tlsSelfSignedHosts !== void 0 ? { tlsSelfSignedHosts } : {},
+		...trustedTerminator !== void 0 ? { trustedTerminator } : {},
+		...secureCookies !== void 0 ? { secureCookies } : {}
+	};
+}
+/**
+* Build the reference-shaped config `apply` receives, exactly as the Loader
+* builds it. Exported for tests that drive `apply` directly.
+* @param raw - a config object; missing fields take their schema defaults.
+* @returns one reference per volatile field.
+*/
+function configRefs(raw) {
+	return Config(raw);
+}
+/**
+* Validate a raw config object the way the Loader does, and unwrap it.
+*
+* `Config` marks every field volatile, so a validation hands the values back as
+* references (typed deeply-readonly by schemastery); this returns the plain
+* shape the rest of the file reads. Used to judge a config the Settings card is
+* about to save, before it is persisted.
+* @param raw - a config object; missing fields take their schema defaults.
+* @returns the validated plain config.
+*/
+function validateConfig(raw) {
+	return readConfig(configRefs(raw));
+}
+/**
 * The fail-closed problems that prevent a config from enabling the listener.
 * Returns every problem (not just the first) so the operator sees the full
 * migration at once. Exported for tests.
@@ -1697,32 +2050,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
@@ -1748,21 +2095,101 @@ 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();
-	const effective = () => configSource();
+	/** Whether the settings service is attached, so writes reach the profile entry. */
+	let settingsAttached = false;
+	/**
+	* This plugin's own Loader entry id. dsh 0.1.7 addresses a settings write by
+	* the *entry id* — the `lan-gateway` namespace this plugin used to register
+	* with is gone along with `settingsScope`.
+	*/
+	let settingsEntryId;
+	/**
+	* The settings service, for the one write a merge patch cannot express: a key
+	* must be *removed* to re-inherit the composition layer, and only its
+	* 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 = () => readConfig(config);
+	/** 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 });
@@ -1789,6 +2216,10 @@ function apply(ctx, config) {
 			}
 		}, 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 ${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]"}`);
@@ -1803,42 +2234,58 @@ 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 profile entry, or memory. */
+	const setRunIntent = async (enabled) => {
+		if (settingsAttached && settingsProvider !== void 0 && settingsEntryId !== void 0) {
+			await settingsProvider.update(settingsEntryId, { enabled });
+			return;
+		}
+		manualOverride = enabled;
+	};
 	ctx.inject(["settings"], (sctx) => {
-		const scope = sctx.settings.register(NS, Config, { base: config });
-		settingsScope = scope;
-		configSource = () => scope.get();
-		sctx.effect(() => scope.watch(() => {
+		const entryId = ctx.fiber.entry?.options.id;
+		if (entryId === void 0) return;
+		settingsEntryId = entryId;
+		settingsProvider = sctx.settings;
+		settingsAttached = true;
+		sctx.effect(() => sctx.settings.configure({ auto: false }, ctx.fiber));
+		sctx.effect(() => ctx.on("loader/volatile-update", () => {
 			syncGateway("settings change");
 		}));
 		sctx.effect(() => () => {
-			configSource = () => config;
-			settingsScope = void 0;
+			settingsEntryId = 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({
@@ -1846,9 +2293,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));
@@ -1858,15 +2322,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") {
@@ -1886,41 +2342,37 @@ 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) {
+		const settings = settingsProvider;
+		const entryId = settingsEntryId;
+		if (settings === void 0 || entryId === 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 = validateConfig({
+			...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 settings.mutate(entryId, 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) });
 		}
@@ -1932,16 +2384,16 @@ 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 ${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 ? `\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,
@@ -1952,7 +2404,7 @@ function apply(ctx, config) {
 			};
 		},
 		async disable() {
-			manualOverride = false;
+			await setRunIntent(false);
 			await syncGateway("tool disable");
 			return {
 				ok: true,
@@ -1965,23 +2417,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."
@@ -2012,32 +2462,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, configRefs, gatewayStartProblems, inject, isTrustedConfigRequest, name, readConfig, resolveSecureCookies, validateConfig };