@riceawa/dsh-lan-gateway 0.3.0 → 0.5.0

package/lib/index.js

@@ -85,14 +85,25 @@ function base64url(input) {
 * Issue a signed session cookie value.
 * @param secret - the HMAC signing secret (base64 string).
 * @param expiresMs - epoch millis at which the session expires.
+* @param epoch - the session revocation epoch the cookie is minted under; a
+*   cookie whose epoch no longer matches the live state is rejected by
+*   {@link verifyCookie}. Defaults to 0 (epoch-less, legacy) for callers that
+*   do not participate in revocation.
 * @returns a `payload.signature` string suitable for the cookie value.
 */
-function signCookie(secret, expiresMs) {
-	const payload = base64url(Buffer.from(JSON.stringify({ exp: expiresMs })));
+function signCookie(secret, expiresMs, epoch = 0) {
+	const payload = base64url(Buffer.from(JSON.stringify({
+		exp: expiresMs,
+		epoch
+	})));
 	return `${payload}.${createHmac("sha256", secret).update(payload).digest("base64url")}`;
 }
-/** Whether a cookie value is a valid, unexpired session signed with `secret`. */
-function verifyCookie(secret, value, now) {
+/**
+* Whether a cookie value is a valid, unexpired session signed with `secret`
+* and minted under `epoch`. Epoch-less cookies (legacy payloads) count as
+* epoch 0, so an upgrade from a pre-0.5.0 state does not log everyone out.
+*/
+function verifyCookie(secret, value, now, epoch = 0) {
 	if (value === void 0) return false;
 	const dot = value.indexOf(".");
 	if (dot === -1) return false;
@@ -109,7 +120,25 @@ function verifyCookie(secret, value, now) {
 	if (!timingSafeEqual(expected, actual)) return false;
 	try {
 		const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
-		return typeof decoded.exp === "number" && decoded.exp > now;
+		if (typeof decoded.exp !== "number" || decoded.exp <= now) return false;
+		return (typeof decoded.epoch === "number" ? decoded.epoch : 0) === epoch;
+	} catch {
+		return false;
+	}
+}
+/**
+* Whether a browser Origin header names the same authority (hostname:port) as
+* a request Host header. Both sides run through WHATWG URL parsing so case and
+* an implicit scheme-default port never decide the match — the comparison the
+* gateway uses to tell same-origin browser requests from cross-site ones.
+* @param origin - the `Origin` header value, or undefined.
+* @param host - the `Host` header value, or undefined.
+* @returns true only when both parse and name the same host[:port].
+*/
+function originMatchesHost(origin, host) {
+	if (origin === void 0 || host === void 0) return false;
+	try {
+		return new URL(origin).host === new URL(`http://${host}`).host;
 	} catch {
 		return false;
 	}
@@ -266,13 +295,24 @@ function verifyPassword(state, password) {
 		return false;
 	}
 }
-/** Set (or clear) the password, re-salted on every write. */
+/**
+* Set (or clear) the password, re-salted on every write. Both operations bump
+* the session epoch so every cookie issued under the previous epoch dies — a
+* password change must invalidate sessions the old password authorized.
+*/
 function setPassword(state, password) {
-	if (password === void 0) return { cookieSecret: state.cookieSecret };
+	const base = {
+		...state,
+		sessionEpoch: state.sessionEpoch + 1
+	};
+	if (password === void 0) return {
+		cookieSecret: base.cookieSecret,
+		sessionEpoch: base.sessionEpoch
+	};
 	const salt = randomBytes(16);
 	const hash = scryptSync(password, salt, 64);
 	return {
-		...state,
+		...base,
 		password: {
 			hash: hash.toString("hex"),
 			salt: salt.toString("hex")
@@ -280,7 +320,10 @@ function setPassword(state, password) {
 	};
 }
 function defaultState() {
-	return { cookieSecret: randomBytes(32).toString("base64") };
+	return {
+		cookieSecret: randomBytes(32).toString("base64"),
+		sessionEpoch: 0
+	};
 }
 /** Load state; on first run (or a corrupt file) generate a fresh secret. */
 function loadState(home = homedir()) {
@@ -288,7 +331,15 @@ function loadState(home = homedir()) {
 	try {
 		const raw = readFileSync(join(dir, STATE_FILENAME), "utf8");
 		const parsed = JSON.parse(raw);
-		if (typeof parsed?.cookieSecret === "string" && parsed.cookieSecret.length >= 16) return parsed;
+		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;
+			return base;
+		}
 		return defaultState();
 	} catch {
 		return defaultState();
@@ -309,24 +360,54 @@ function saveState(state, home = homedir()) {
 //#endregion
 //#region src/gateway.ts
 /**
-* The reverse-proxy gateway: a `node:http` server bound to `0.0.0.0` that
-* forwards every request to the loopback dsh web server, rewriting Host and
-* Origin so the dsh `/api` trust fence (which only trusts loopback) passes.
+* The reverse-proxy gateway: a `node:http(s)` server bound to `0.0.0.0` that
+* forwards every request to the loopback dsh web server.
 *
-* Security model:
+* Security model (post-QVD / session-base):
 * - Source is classified from `socket.remoteAddress` only (never
-*   `X-Forwarded-For`). LAN/loopback sources are proxied without a password;
-*   anything else must present a valid signed cookie or complete the login.
+*   `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 `/api*` requests
-*   BEFORE rewriting (reject `sec-fetch-site: cross-site` and any Origin that
-*   does not match the gateway authority the browser actually used).
+*   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 carry a revocation epoch: a password change or secret rotation
+*   bumps the epoch, every previously issued cookie dies, and established
+*   WebSockets are torn down so the client re-authenticates.
 *
 * @module @riceawa/dsh-lan-gateway/gateway
 */
 const DEFAULT_BODY_LIMIT_BYTES = 65536;
 const LOGIN_ATTEMPTS_LIMIT = 5;
 const LOGIN_ATTEMPTS_WINDOW_MS = 6e4;
+/** Methods a browser never attaches a CSRF-meaningful body to; safe without an Origin. */
+const READ_ONLY_METHODS$1 = /* @__PURE__ */ new Set([
+	"GET",
+	"HEAD",
+	"OPTIONS"
+]);
+/** Prefixes the gateway owns and must never relay to dsh. */
+function isOwnedPath(pathname) {
+	return pathname === "/lan-gateway" || pathname.startsWith("/lan-gateway/");
+}
+/** The pathname of a request URL (query string stripped, not decoded). */
+function pathOf(url) {
+	const query = url.indexOf("?");
+	return query === -1 ? url : url.slice(0, query);
+}
 /**
 * 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
@@ -338,6 +419,8 @@ var LanGateway = class {
 	loginLimiter = new RateLimiter(LOGIN_ATTEMPTS_LIMIT, LOGIN_ATTEMPTS_WINDOW_MS);
 	state;
 	disposed = false;
+	/** Established WebSockets (upgraded client sockets), torn down on session-epoch change. */
+	activeDuplexes = /* @__PURE__ */ new Set();
 	constructor(config, state) {
 		this.config = config;
 		this.state = state;
@@ -352,8 +435,9 @@ var LanGateway = class {
 			this.handleUpgrade(req, socket, head);
 		});
 	}
-	/** Replace the in-memory state (e.g. after a password change). */
+	/** 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;
 	}
 	/** Start listening; rejects if the port is already in use. */
@@ -372,17 +456,28 @@ var LanGateway = class {
 			this.server.listen(this.config.gatewayPort, "0.0.0.0");
 		});
 	}
-	/** Close the server and stop accepting connections. */
+	/** 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) => {
 			this.server.close(() => resolve());
 			this.server.closeAllConnections();
 		});
 	}
-	sourceClass(req) {
-		return classifySource(req.socket.remoteAddress, this.config.lanCidrs);
+	destroyActiveDuplexes() {
+		for (const socket of this.activeDuplexes) socket.destroy();
+		this.activeDuplexes.clear();
+	}
+	trackDuplex(socket) {
+		this.activeDuplexes.add(socket);
+		socket.on("close", () => {
+			this.activeDuplexes.delete(socket);
+		});
+	}
+	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) {
@@ -393,10 +488,14 @@ var LanGateway = class {
 			if (trimmed.startsWith(`${this.config.cookieName}=`)) return trimmed.slice(this.config.cookieName.length + 1);
 		}
 	}
-	/** Whether a request carries a valid session for its source. */
+	/** Whether a request carries a session valid under the current epoch. */
 	authorized(req) {
 		const cookie = this.sessionCookie(req);
-		return cookie !== void 0 && verifyCookie(this.state.cookieSecret, cookie, Date.now());
+		return cookie !== void 0 && verifyCookie(this.state.cookieSecret, cookie, Date.now(), this.state.sessionEpoch);
+	}
+	/** Whether this source must present a gateway session (default: everyone). */
+	requiresLogin(source) {
+		return !(this.config.lanPasswordless && source !== "internet");
 	}
 	serveUnauthorized(res, limited) {
 		res.writeHead(302, {
@@ -414,47 +513,58 @@ var LanGateway = class {
 		});
 		res.end(renderLoginPage(opts));
 	}
-	/** HSTS when the listener is HTTPS (never sent on plain HTTP). */
+	/** HSTS when the listener itself is HTTPS (never sent on plain HTTP). */
 	securityHeaders() {
 		return this.config.tls === void 0 ? {} : { "strict-transport-security": "max-age=15552000" };
 	}
-	/** Handle one HTTP request: auth gate → CSRF fence → forward. */
+	/**
+	* 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. */
 	async handleHttp(req, res) {
-		const source = this.sourceClass(req);
 		const url = req.url ?? "/";
-		const pathname = url.split("?")[0] ?? "/";
+		const pathname = pathOf(url);
+		const source = this.sourceOf(req);
 		if (pathname === "/__login") {
 			this.handleLogin(req, res);
 			return;
 		}
-		if (source === "internet" && this.config.authRequired) {
-			if (!this.authorized(req)) {
-				this.serveUnauthorized(res, false);
-				return;
-			}
+		if (pathname === "/__logout") {
+			this.handleLogout(req, res);
+			return;
 		}
-		if (pathname === "/api" || pathname.startsWith("/api/")) {
-			if (!this.passesCsrfFence(req)) {
-				res.writeHead(403, this.securityHeaders());
-				res.end("forbidden");
-				return;
-			}
+		if (isOwnedPath(pathname)) {
+			res.writeHead(403, this.securityHeaders());
+			res.end("forbidden");
+			return;
 		}
-		this.forward(req, res, url);
-	}
-	/** Reject cross-site API traffic: the gateway's own origin check. */
-	passesCsrfFence(req) {
-		const headers = req.headers;
-		if (headers["sec-fetch-site"] === "cross-site") return false;
-		const origin = headers.origin;
-		if (origin === void 0) return true;
-		try {
-			const originHost = new URL(origin).host;
-			const requestHost = typeof headers.host === "string" ? headers.host : "";
-			return originHost === requestHost || originHost === stripDefaultPort(requestHost);
-		} catch {
-			return false;
+		if (this.requiresLogin(source) && !this.authorized(req)) {
+			this.serveUnauthorized(res, false);
+			return;
+		}
+		if (!this.sameSiteAllowed(req, false)) {
+			res.writeHead(403, this.securityHeaders());
+			res.end("forbidden");
+			return;
 		}
+		await this.relayHttp(req, res, url);
 	}
 	/** Handle the login GET form / POST submission. */
 	handleLogin(req, res) {
@@ -464,7 +574,7 @@ var LanGateway = class {
 			return;
 		}
 		if (req.method !== "POST") {
-			res.writeHead(405, { allow: "GET, POST" });
+			res.writeHead(405, { allow: "GET, HEAD, POST" });
 			res.end();
 			return;
 		}
@@ -485,24 +595,64 @@ var LanGateway = class {
 				this.serveLoginError(res, "Incorrect password.");
 				return;
 			}
-			const expiresMs = Date.now() + this.config.cookieMaxAgeDays * 864e5;
-			const cookie = signCookie(this.state.cookieSecret, expiresMs);
-			const secure = this.config.tls !== void 0 ? "; Secure" : "";
+			const maxAgeSeconds = this.config.cookieMaxAgeDays * 86400;
+			const expiresMs = Date.now() + maxAgeSeconds * 1e3;
+			const cookie = signCookie(this.state.cookieSecret, expiresMs, this.state.sessionEpoch);
 			res.writeHead(302, {
 				location: "/",
 				...this.securityHeaders(),
-				"set-cookie": [`${this.config.cookieName}=${cookie}; HttpOnly; SameSite=Lax; Path=/; Max-Age=${this.config.cookieMaxAgeDays * 86400}${secure}`]
+				"set-cookie": [this.sessionSetCookie(cookie, maxAgeSeconds)]
 			});
 			res.end();
 		});
 	}
-	/** Forward an HTTP request to dsh, rewriting Host/Origin to loopback. */
-	forward(req, res, url) {
+	/** POST /__logout: sign an immediately-expired cookie and bounce to / . */
+	handleLogout(req, res) {
+		if (req.method !== "POST") {
+			res.writeHead(405, { allow: "POST" });
+			res.end();
+			return;
+		}
+		if (!this.sameSiteAllowed(req, false)) {
+			res.writeHead(403, this.securityHeaders());
+			res.end("forbidden");
+			return;
+		}
+		res.writeHead(302, {
+			location: "/",
+			...this.securityHeaders(),
+			"set-cookie": [this.sessionSetCookie("", 0)]
+		});
+		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"];
-		delete headers.connection;
+		if (!keepUpgrade) {
+			delete headers.connection;
+			delete headers.upgrade;
+		}
+		return headers;
+	}
+	/** Attach the shared upstream session cookie to the outbound headers, if any. */
+	attachUpstreamSession(headers) {
+		const session = this.config.upstreamSession;
+		if (session === void 0) return false;
+		const cookie = session.peek();
+		if (cookie === void 0) return false;
+		const existing = headers.cookie;
+		headers.cookie = typeof existing === "string" && existing !== "" ? `${existing}; ${cookie}` : cookie;
+		return true;
+	}
+	/** 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 proxyReq = http.request({
 			host: "127.0.0.1",
 			port: this.config.dshPort,
@@ -510,6 +660,7 @@ var LanGateway = class {
 			path: url,
 			headers
 		}, (proxyRes) => {
+			if (attached && session !== void 0 && proxyRes.statusCode === 401) session.invalidate();
 			res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
 			proxyRes.pipe(res);
 		});
@@ -519,25 +670,40 @@ var LanGateway = class {
 		});
 		req.pipe(proxyReq);
 	}
-	/** Forward a WebSocket upgrade, splicing the raw duplex through to dsh. */
-	handleUpgrade(req, socket, head) {
-		if (this.sourceClass(req) === "internet" && this.config.authRequired && !this.authorized(req)) {
-			socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+	/** 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(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`);
 			socket.destroy();
+		};
+		if (pathname === "/__login" || pathname === "/__logout" || isOwnedPath(pathname)) {
+			refuse(403);
 			return;
 		}
-		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 (this.requiresLogin(source) && !this.authorized(req)) {
+			refuse(401);
+			return;
+		}
+		if (!this.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);
 		const proxyReq = http.request({
 			host: "127.0.0.1",
 			port: this.config.dshPort,
 			method: "GET",
-			path: req.url ?? "/",
+			path: url,
 			headers
 		});
 		proxyReq.on("upgrade", (proxyRes, proxySocket, proxyHead) => {
+			this.trackDuplex(socket);
 			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("");
 			socket.write(`${statusLine}${headerLines}\r\n`);
@@ -551,12 +717,6 @@ var LanGateway = class {
 		proxyReq.end();
 	}
 };
-/** Strip an explicit default port from a Host authority, if present. */
-function stripDefaultPort(host) {
-	const parsed = /^(.+?)(?::(\d+))?$/.exec(host);
-	if (parsed?.[2] === "80" || parsed?.[2] === "443") return parsed[1];
-	return host;
-}
 //#endregion
 //#region src/x509.ts
 /**
@@ -908,7 +1068,7 @@ const LAN_GATEWAY_TOOL_NAME = "lan_gateway";
 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 trusted LAN CIDRs, and the TLS state. `enable` starts listening on 0.0.0.0 (loopback and LAN sources need no password; anything else must sign in). `disable` stops listening. `set-password` sets (or, with an empty password, clears) the gateway password for non-LAN access. `rotate-secret` invalidates every issued login cookie. `tls-regenerate` mints a fresh self-signed certificate (tlsMode must be self-signed) and restarts the listener.",
+		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",
@@ -920,7 +1080,7 @@ function lanGatewayTool(control) {
 					"rotate-secret",
 					"tls-regenerate"
 				],
-				description: "`status` (default) — report gateway state. `enable` / `disable` — start or stop the listener. `set-password` — set or clear the login password. `rotate-secret` — invalidate all existing sessions. `tls-regenerate` — mint a new self-signed certificate."
+				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",
@@ -963,6 +1123,142 @@ function lanGatewayTool(control) {
 	});
 }
 //#endregion
+//#region src/upstream-session.ts
+/**
+* Shared upstream session relay for session-capable dsh bases (>= 0.1.2).
+*
+* When dsh added browser-session authentication it stopped trusting a loopback
+* Host header alone: every `/api` request (and the remote WebSocket mux) must
+* now present a signed cookie bound to the authority it names
+* (`dsh-auth-<sha256(authority)>`), minted at the index route by exchanging the
+* process launch token. A reverse proxy that rewrites Host to loopback — which
+* is what this gateway does — therefore gets a 401 no matter how the Host is
+* forged. The gateway cannot mint that cookie itself (the signing secret lives
+* in dsh's credential provider), so it does exactly what a browser does: on the
+* loopback transport it visits the launch-token URL, keeps the Set-Cookie it
+* earns, and replays that one shared session on every request it forwards.
+*
+* Semantics match the pre-existing "single password = single operator" model:
+* whoever passes the gateway's own login rides this one upstream session. It is
+* not multi-user authorization, and upstream (which holds the secret) remains
+* the actual authority over what the session may do.
+*
+* The relay is a no-op on a base without browser sessions: acquisition fails
+* and `cookie()` returns undefined, so the gateway simply forwards without a
+* session cookie exactly as it did against an older dsh.
+*
+* @module @riceawa/dsh-lan-gateway/upstream-session
+*/
+/** The session-cookie name prefix upstream signs (`dsh-auth-<b64url(sha256)>`). */
+const UPSTREAM_COOKIE_PREFIX = "dsh-auth-";
+/** Split `name=value; Path=/; …` into the `name=value` request-Cookie fragment. */
+function nameValueOnly(setCookie) {
+	const semi = setCookie.indexOf(";");
+	return (semi === -1 ? setCookie : setCookie.slice(0, semi)).trim();
+}
+/** Pull the Max-Age attribute (seconds) out of a Set-Cookie string, if any. */
+function maxAgeSeconds(setCookie) {
+	const match = /\bMax-Age=(\d+)\b/i.exec(setCookie);
+	return match === null ? void 0 : Number(match[1]);
+}
+/**
+* Perform the token exchange over loopback: GET the launch-token URL with the
+* upstream authority as Host, read the Set-Cookie the index route mints, and
+* return its `name=value` plus expiry (or undefined when the exchange failed
+* or no session cookie came back — e.g. an older base without browser
+* sessions).
+*/
+function exchange(url, authority, port) {
+	return new Promise((resolve) => {
+		let target;
+		try {
+			target = new URL(url);
+		} catch {
+			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) {
+				resolve(void 0);
+				return;
+			}
+			const raw = (Array.isArray(setCookies) ? setCookies : [setCookies]).find((value) => value.startsWith(`${UPSTREAM_COOKIE_PREFIX}=`));
+			if (raw === void 0) {
+				resolve(void 0);
+				return;
+			}
+			const header = nameValueOnly(raw);
+			const maxAge = maxAgeSeconds(raw);
+			resolve({
+				header,
+				expiresAt: Date.now() + (maxAge ?? 0) * 1e3
+			});
+		});
+		request.on("error", () => resolve(void 0));
+		request.setTimeout(5e3, () => 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;
+	held;
+	inflight;
+	constructor(options) {
+		this.port = options.port;
+		this.authority = options.authority ?? `127.0.0.1:${options.port}`;
+		this.authenticatedUrl = options.authenticatedUrl;
+	}
+	/** 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() {
+		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) return void 0;
+		const result = await exchange(url, this.authority, this.port);
+		if (result !== void 0) this.held = result;
+		return this.held?.header;
+	}
+};
+//#endregion
 //#region src/index.ts
 /** Stable Cordis plugin name. */
 const name = "dsh-lan-gateway";
@@ -974,7 +1270,8 @@ const NS = settingsNamespace("lan-gateway");
 const OPTIONAL_CONFIG_KEYS = /* @__PURE__ */ new Set([
 	"dshTargetPort",
 	"tlsCertPath",
-	"tlsKeyPath"
+	"tlsKeyPath",
+	"trustedTerminator"
 ]);
 /** Schemastery configuration validated by the Loader. */
 const Config = z.object({
@@ -982,6 +1279,7 @@ const Config = z.object({
 	gatewayPort: z.natural().min(1).max(65535).default(3081),
 	dshTargetPort: z.natural().min(1).max(65535),
 	lanCidrs: z.array(String).default([...DEFAULT_LAN_CIDR_STRINGS]),
+	lanPasswordless: z.boolean().default(false),
 	authRequired: z.boolean().default(true),
 	cookieMaxAgeDays: z.natural().min(1).max(365).default(7),
 	cookieName: z.string().default("dsh_gw_auth"),
@@ -990,8 +1288,22 @@ const Config = z.object({
 	tlsCertPath: z.string(),
 	tlsKeyPath: z.string(),
 	tlsSelfSignedHosts: z.string().default("localhost"),
-	tlsCertMaxAgeDays: z.natural().min(1).max(3650).default(825)
+	tlsCertMaxAgeDays: z.natural().min(1).max(3650).default(825),
+	allowInsecurePlaintext: z.boolean().default(false),
+	trustedTerminator: z.string()
 });
+/**
+* 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.
+*/
+function gatewayStartProblems(cfg, facts) {
+	const problems = [];
+	if (cfg.authRequired === false) problems.push("authRequired=false is no longer supported — authentication is always required. Remove `authRequired` (or set it true); for password-free LAN access set `lanPasswordless: true`.");
+	if (cfg.lanPasswordless && !facts.upstreamSessionAvailable) problems.push("lanPasswordless requires a dsh base with browser-session auth (>= 0.1.2-rc.1): the gateway relaxes only its own login, never dsh authorization. Upgrade dsh, or set lanPasswordless: false.");
+	if (!(cfg.tlsEnabled || cfg.trustedTerminator !== void 0) && !cfg.allowInsecurePlaintext) problems.push("Refusing to serve over plaintext HTTP: enable TLS (tlsEnabled: true), declare a trusted TLS-terminating proxy (trustedTerminator), or set allowInsecurePlaintext: true to accept the plaintext exposure (passwords and sessions would travel in clear).");
+	return problems;
+}
 /** Resolve the TLS material for a config, or undefined when TLS is off. */
 function resolveTls(cfg) {
 	if (!cfg.tlsEnabled) return void 0;
@@ -1010,7 +1322,7 @@ function listenerKey(cfg) {
 		cfg.gatewayPort,
 		cfg.dshTargetPort,
 		cfg.lanCidrs,
-		cfg.authRequired,
+		cfg.lanPasswordless,
 		cfg.cookieMaxAgeDays,
 		cfg.cookieName,
 		cfg.tlsEnabled,
@@ -1018,7 +1330,9 @@ function listenerKey(cfg) {
 		cfg.tlsCertPath,
 		cfg.tlsKeyPath,
 		cfg.tlsSelfSignedHosts,
-		cfg.tlsCertMaxAgeDays
+		cfg.tlsCertMaxAgeDays,
+		cfg.allowInsecurePlaintext,
+		cfg.trustedTerminator
 	]);
 }
 /** One-line TLS description for status output. */
@@ -1042,13 +1356,20 @@ function isLoopbackHost(hostname) {
 	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 config route (mirrors the fence the dsh
-* host uses for its own /api, and what dsh-lan-gateway's sibling plugins do):
-* the Host must be loopback (the gateway rewrites it), cross-site fetches are
-* refused, and any Origin must match the Host the browser actually used.
+* Same-origin loopback fence for the native `/lan-gateway/config` route. The
+* gateway refuses to relay this prefix, so the only way in is the native
+* loopback listener itself (a genuine local user, or a local process that could
+* already read `~/.dsh`). Host must be loopback (also blocks DNS rebinding),
+* cross-site fetches are refused, an Origin must match the Host the browser
+* used, and a state-changing method must carry that Origin. Exported for tests.
 */
-function isTrustedRequest(req) {
+function isTrustedConfigRequest(req) {
 	const host = req.headers?.host;
 	if (typeof host !== "string" || host === "") return false;
 	let hostUrl;
@@ -1060,12 +1381,10 @@ function isTrustedRequest(req) {
 	if (!isLoopbackHost(hostUrl.hostname)) return false;
 	if (req.headers?.["sec-fetch-site"] === "cross-site") return false;
 	const origin = req.headers?.origin;
-	if (origin === void 0) return true;
-	try {
-		return new URL(origin).host === hostUrl.host;
-	} catch {
-		return false;
-	}
+	if (origin !== void 0 && !originMatchesHost(origin, host)) return false;
+	const method = req.method ?? "GET";
+	if (!READ_ONLY_METHODS.has(method) && origin === void 0) return false;
+	return true;
 }
 function apply(ctx, config) {
 	let state = loadState();
@@ -1073,6 +1392,10 @@ function apply(ctx, config) {
 	let startedWith;
 	let lastError;
 	let manualOverride;
+	/** Whether the base enforces browser-session auth; set once `connection` is seen. */
+	let upstreamSessionAvailable = false;
+	/** Builds a fresh shared-session relay for a dsh port, once the base supports sessions. */
+	let makeRelay;
 	/** The authoritative config: settings section when attached, else composition. */
 	let configSource = () => config;
 	/** Serializes listener start/stop/restart so settings changes cannot race. */
@@ -1080,22 +1403,27 @@ function apply(ctx, config) {
 	const effective = () => configSource();
 	const startGateway = async (cfg) => {
 		if (gateway !== void 0) return;
-		if (cfg.authRequired && state.password === void 0) throw new Error("dsh-lan-gateway: no password set — run `lan_gateway set-password` (or set authRequired=false in the plugin config) before enabling.");
+		const problems = gatewayStartProblems(cfg, { upstreamSessionAvailable });
+		if (state.password === void 0) problems.unshift("no password set — run `lan_gateway set-password` before enabling the listener");
+		if (problems.length > 0) throw new Error(`dsh-lan-gateway: cannot start — ${problems.join(" ")}`);
 		const dshPort = cfg.dshTargetPort ?? ctx.webServer.port;
 		const tls = resolveTls(cfg);
+		const encryptedIngress = cfg.tlsEnabled || cfg.trustedTerminator !== void 0;
 		const next = new LanGateway({
 			gatewayPort: cfg.gatewayPort,
 			dshPort,
 			lanCidrs: cfg.lanCidrs,
-			authRequired: cfg.authRequired,
+			lanPasswordless: cfg.lanPasswordless,
 			cookieMaxAgeDays: cfg.cookieMaxAgeDays,
 			cookieName: cfg.cookieName,
-			...tls !== void 0 ? { tls } : {}
+			secureCookies: encryptedIngress,
+			...tls !== void 0 ? { tls } : {},
+			...makeRelay !== void 0 ? { upstreamSession: makeRelay(dshPort) } : {}
 		}, state);
 		await next.listen();
 		gateway = next;
 		startedWith = listenerKey(cfg);
-		ctx.logger.info(`dsh-lan-gateway: listening on 0.0.0.0:${cfg.gatewayPort}${tls !== void 0 ? " (TLS)" : ""} -> 127.0.0.1:${dshPort}`);
+		ctx.logger.info(`dsh-lan-gateway: listening on 0.0.0.0:${cfg.gatewayPort}${tls !== void 0 ? " (TLS)" : ""} -> 127.0.0.1:${dshPort}${encryptedIngress ? "" : " (plaintext, explicit allowInsecurePlaintext)"}${makeRelay !== void 0 ? " [shared upstream session relay]" : " [no upstream session relay: base has no browser-session auth]"}`);
 	};
 	const stopGateway = async () => {
 		const current = gateway;
@@ -1141,13 +1469,21 @@ function apply(ctx, config) {
 		});
 		syncGateway("settings attach");
 	});
+	ctx.inject(["connection"], (ccx) => {
+		upstreamSessionAvailable = true;
+		makeRelay = (dshPort) => new UpstreamSessionRelay({
+			port: dshPort,
+			authenticatedUrl: () => ccx.connection.authenticatedUrl(`http://127.0.0.1:${dshPort}`)
+		});
+		syncGateway("connection attach");
+	});
 	const configRouteHandler = async (req, res) => {
 		const send = (status, body) => {
 			res.writeHead(status, { "content-type": "application/json" });
 			res.end(JSON.stringify(body));
 		};
-		if (!isTrustedRequest(req)) {
-			send(403, { error: "request refused: this route answers loopback-origin requests only" });
+		if (!isTrustedConfigRequest(req)) {
+			send(403, { error: "request refused: this route answers same-origin loopback requests only" });
 			return;
 		}
 		if (req.method === "GET") {
@@ -1157,6 +1493,7 @@ function apply(ctx, config) {
 				running: gateway !== void 0,
 				port: cfg.gatewayPort,
 				tls: tlsStatusLine(cfg),
+				upstreamSessionAvailable,
 				lastError: lastError ?? null
 			});
 			return;
@@ -1189,6 +1526,12 @@ function apply(ctx, config) {
 			send(409, { error: "settings service unavailable — edit the profile patch (cordis.patch.yml) instead" });
 			return;
 		}
+		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;
@@ -1204,6 +1547,7 @@ function apply(ctx, config) {
 				running: gateway !== void 0,
 				port: cfg.gatewayPort,
 				tls: tlsStatusLine(cfg),
+				upstreamSessionAvailable,
 				lastError: lastError ?? null
 			});
 		} catch (error) {
@@ -1219,9 +1563,10 @@ function apply(ctx, config) {
 		status() {
 			const cfg = effective();
 			const dshPort = cfg.dshTargetPort ?? ctx.webServer.port;
+			const encrypted = cfg.tlsEnabled || cfg.trustedTerminator !== void 0;
 			return {
 				ok: true,
-				message: `LAN gateway: ${gateway !== void 0 ? `LISTENING on 0.0.0.0:${cfg.gatewayPort}` : "stopped"}\n- dsh target: 127.0.0.1:${dshPort}\n- password: ${state.password !== void 0 ? "set" : "NOT SET"}\n- auth required for non-LAN: ${cfg.authRequired}\n- trusted LAN CIDRs: ${cfg.lanCidrs.join(", ") || "(none)"}\n- session cookie: ${cfg.cookieName}, ${cfg.cookieMaxAgeDays}d\n- TLS: ${tlsStatusLine(cfg)}` + (manualOverride !== void 0 ? `\n- manual override: ${manualOverride ? "enabled" : "disabled"}` : "") + (lastError !== void 0 ? `\n- last error: ${lastError}` : "")
+				message: `LAN gateway: ${gateway !== void 0 ? `LISTENING on 0.0.0.0:${cfg.gatewayPort}` : "stopped"}\n- dsh target: 127.0.0.1:${dshPort}\n- password: ${state.password !== void 0 ? "set" : "NOT SET"}\n- login required for all sources: true${cfg.lanPasswordless ? " (LAN/loopback exempt via lanPasswordless)" : ""}\n- session epoch: ${state.sessionEpoch}\n- upstream session relay: ${upstreamSessionAvailable ? "active (dsh browser-session auth present)" : "absent (older dsh base)"}\n- ingress: ${cfg.tlsEnabled ? `TLS (${tlsStatusLine(cfg)})` : cfg.trustedTerminator !== void 0 ? `TLS terminated by trusted proxy (${cfg.trustedTerminator})` : encrypted ? "encrypted" : cfg.allowInsecurePlaintext ? "PLAINTEXT (explicit allowInsecurePlaintext)" : "plaintext — will not start"}\n- session cookie: ${cfg.cookieName}, ${cfg.cookieMaxAgeDays}d` + (manualOverride !== void 0 ? `\n- manual override: ${manualOverride ? "enabled" : "disabled"}` : "") + (lastError !== void 0 ? `\n- last error: ${lastError}` : "")
 			};
 		},
 		async enable() {
@@ -1243,29 +1588,46 @@ function apply(ctx, config) {
 				message: "Gateway disabled."
 			};
 		},
-		setPassword(password) {
+		async setPassword(password) {
 			if (password !== void 0 && password.length > 0 && password.length < 8) return {
 				ok: false,
 				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);
 			saveState(state);
 			gateway?.setState(state);
+			if (!setting) {
+				manualOverride = false;
+				if (gateway !== void 0) {
+					await stopGateway();
+					lastError = "Password cleared — the gateway listener was stopped (a password is required to run).";
+					syncGateway("password cleared");
+				}
+				return {
+					ok: true,
+					message: "Password cleared. Session epoch advanced and the gateway listener was stopped — set a password before enabling it again."
+				};
+			}
+			previous === void 0 ? syncGateway("password set") : Promise.resolve();
 			return {
 				ok: true,
-				message: setting ? "Password set. Non-LAN access now requires it." : "Password cleared. Non-LAN access is now password-free (only safe if authRequired is false or no non-LAN sources exist)."
+				message: "Password set. Session epoch advanced — every previously issued session is now invalid; all sources must sign in again."
 			};
 		},
 		rotateSecret() {
-			const next = { cookieSecret: randomBytes(32).toString("base64") };
+			const next = {
+				cookieSecret: randomBytes(32).toString("base64"),
+				sessionEpoch: state.sessionEpoch + 1
+			};
 			if (state.password !== void 0) next.password = state.password;
 			state = next;
 			saveState(state);
 			gateway?.setState(state);
 			return {
 				ok: true,
-				message: "Session secret rotated. All existing login cookies are now invalid."
+				message: "Session secret rotated and epoch advanced. All existing login cookies and live WebSockets are now invalid."
 			};
 		},
 		async regenerateTls() {
@@ -1301,10 +1663,10 @@ function apply(ctx, config) {
 			}
 		}
 	}));
-	ctx.effect(async () => {
-		await syncGateway("boot");
+	ctx.effect(() => {
+		syncGateway("boot");
 		return stopGateway;
 	}, "dsh-lan-gateway: listener lifecycle");
 }
 //#endregion
-export { Config, apply, inject, name };
+export { Config, apply, gatewayStartProblems, inject, isTrustedConfigRequest, name };