@riceawa/dsh-lan-gateway 0.5.2 → 0.5.4

package/lib/index.js

@@ -1,4 +1,4 @@
-import { X509Certificate, createHmac, createSign, generateKeyPairSync, randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
+import { X509Certificate, createHmac, createSign, generateKeyPairSync, randomBytes, scrypt, scryptSync, timingSafeEqual } from "node:crypto";
 import z from "@deepseek-ai/schemastery";
 import http from "node:http";
 import https from "node:https";
@@ -73,9 +73,19 @@ function classifySource(remoteAddress, lanCidrs = DEFAULT_LAN_CIDR_STRINGS) {
 		return "internet";
 	}
 	if (address === "::1") return "loopback";
-	if (address.toLowerCase().startsWith("fe80:")) return "lan";
+	if (inIpv6LinkLocal(address)) return "lan";
 	return "internet";
 }
+/**
+* Whether a textual IPv6 address falls inside fe80::/10. The first ten bits are
+* `1111111010`, so the leading hextet spans fe80–febf; a `startsWith('fe80:')`
+* test covers only fe80::/16 and misclassifies fe90::–febf:: as internet.
+*/
+function inIpv6LinkLocal(address) {
+	const match = /^([0-9a-fA-F]{1,4}):/.exec(address);
+	if (match === null) return false;
+	return (Number.parseInt(match[1], 16) & 65472) === 65152;
+}
 /** Encode a byte buffer as URL-safe base64 without padding. */
 function base64url(input) {
 	return input.toString("base64url");
@@ -88,24 +98,29 @@ function base64url(input) {
 *   cookie whose epoch no longer matches the live state is rejected by
 *   {@link verifyCookie}. Defaults to 0 (epoch-less, legacy) for callers that
 *   do not participate in revocation.
+* @param sid - optional per-session id (see {@link SessionClaims.sid}).
 * @returns a `payload.signature` string suitable for the cookie value.
 */
-function signCookie(secret, expiresMs, epoch = 0) {
-	const payload = base64url(Buffer.from(JSON.stringify({
+function signCookie(secret, expiresMs, epoch = 0, sid) {
+	const claims = sid === void 0 ? {
 		exp: expiresMs,
 		epoch
-	})));
+	} : {
+		exp: expiresMs,
+		epoch,
+		sid
+	};
+	const payload = base64url(Buffer.from(JSON.stringify(claims)));
 	return `${payload}.${createHmac("sha256", secret).update(payload).digest("base64url")}`;
 }
 /**
-* Whether a cookie value is a valid, unexpired session signed with `secret`
-* and minted under `epoch`. Epoch-less cookies (legacy payloads) count as
-* epoch 0, so an upgrade from a pre-0.5.0 state does not log everyone out.
+* Verify a cookie's signature, expiry and epoch.
+* @returns the claims it carries, or undefined when it is not a valid session.
 */
-function verifyCookie(secret, value, now, epoch = 0) {
-	if (value === void 0) return false;
+function verifySession(secret, value, now, epoch = 0) {
+	if (value === void 0) return void 0;
 	const dot = value.indexOf(".");
-	if (dot === -1) return false;
+	if (dot === -1) return void 0;
 	const payload = value.slice(0, dot);
 	const sig = value.slice(dot + 1);
 	const expected = createHmac("sha256", secret).update(payload).digest();
@@ -113,16 +128,22 @@ function verifyCookie(secret, value, now, epoch = 0) {
 	try {
 		actual = Buffer.from(sig, "base64url");
 	} catch {
-		return false;
+		return;
 	}
-	if (expected.length !== actual.length) return false;
-	if (!timingSafeEqual(expected, actual)) return false;
+	if (expected.length !== actual.length) return void 0;
+	if (!timingSafeEqual(expected, actual)) return void 0;
 	try {
 		const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
-		if (typeof decoded.exp !== "number" || decoded.exp <= now) return false;
-		return (typeof decoded.epoch === "number" ? decoded.epoch : 0) === epoch;
+		if (typeof decoded.exp !== "number" || decoded.exp <= now) return void 0;
+		const cookieEpoch = typeof decoded.epoch === "number" ? decoded.epoch : 0;
+		if (cookieEpoch !== epoch) return void 0;
+		return {
+			exp: decoded.exp,
+			epoch: cookieEpoch,
+			...typeof decoded.sid === "string" ? { sid: decoded.sid } : {}
+		};
 	} catch {
-		return false;
+		return;
 	}
 }
 /**
@@ -143,10 +164,18 @@ function originMatchesHost(origin, host) {
 	}
 }
 /** A token bucket limiter keyed by source address. */
-var RateLimiter = class {
+var RateLimiter = class RateLimiter {
 	maxTokens;
 	windowMs;
+	/**
+	* Hard ceiling on tracked sources. Expiry alone only reclaims a bucket when
+	* `prune` runs, and a spray from many distinct addresses inside one window
+	* outruns it, so the map also sheds its soonest-expiring entries past this.
+	*/
+	static MAX_BUCKETS = 1e4;
 	buckets = /* @__PURE__ */ new Map();
+	/** Epoch millis at which the next opportunistic sweep is due. */
+	nextPruneAt = 0;
 	constructor(maxTokens, windowMs) {
 		this.maxTokens = maxTokens;
 		this.windowMs = windowMs;
@@ -158,24 +187,33 @@ var RateLimiter = class {
 	*/
 	allow(key) {
 		const now = Date.now();
-		const bucket = this.buckets.get(key);
-		if (bucket === void 0 || bucket.resetAt <= now) {
-			this.buckets.set(key, {
-				tokens: this.maxTokens - 1,
-				resetAt: now + this.windowMs
-			});
-			return true;
+		if (now >= this.nextPruneAt) {
+			this.prune(now);
+			this.nextPruneAt = now + this.windowMs;
 		}
-		if (bucket.tokens > 0) {
-			bucket.tokens -= 1;
+		const existing = this.buckets.get(key);
+		if (existing !== void 0 && existing.resetAt > now) {
+			if (existing.tokens <= 0) return false;
+			existing.tokens -= 1;
 			return true;
 		}
-		return false;
+		if (existing === void 0 && this.buckets.size >= RateLimiter.MAX_BUCKETS) this.evictSoonestToExpire();
+		this.buckets.set(key, {
+			tokens: this.maxTokens - 1,
+			resetAt: now + this.windowMs
+		});
+		return true;
 	}
-	/** Drop expired buckets to bound memory. */
+	/** Drop expired buckets to bound memory. Called from {@link allow}. */
 	prune(now = Date.now()) {
 		for (const [key, bucket] of this.buckets) if (bucket.resetAt <= now) this.buckets.delete(key);
 	}
+	/** Trim back to 90% of the ceiling, oldest expiry first. */
+	evictSoonestToExpire() {
+		const target = Math.floor(RateLimiter.MAX_BUCKETS * .9);
+		const byExpiry = [...this.buckets.entries()].sort((a, b) => a[1].resetAt - b[1].resetAt);
+		for (const [key] of byExpiry.slice(0, Math.max(0, this.buckets.size - target))) this.buckets.delete(key);
+	}
 };
 //#endregion
 //#region src/login.ts
@@ -282,13 +320,27 @@ function stateDir(home = homedir()) {
 	return join(home, ".dsh", "lan-gateway");
 }
 const STATE_FILENAME = "state.json";
-/** Whether a password is present and passes scrypt verification. */
-function verifyPassword(state, password) {
+/** Promise wrapper around the threaded `scrypt`, which runs off the main loop. */
+function deriveKey(password, salt, keylen) {
+	return new Promise((resolve, reject) => {
+		scrypt(password, salt, keylen, (error, derived) => {
+			if (error !== null) reject(error);
+			else resolve(derived);
+		});
+	});
+}
+/**
+* Whether a password is present and passes scrypt verification. Asynchronous
+* on purpose: `scryptSync` occupies the event loop for tens of milliseconds
+* per attempt, and that loop is shared with the dsh process the gateway is
+* forwarding to.
+*/
+async function verifyPassword(state, password) {
 	if (state.password === void 0) return false;
 	const { hash, salt } = state.password;
 	try {
 		const expected = Buffer.from(hash, "hex");
-		const actual = scryptSync(password, Buffer.from(salt, "hex"), expected.length);
+		const actual = await deriveKey(password, Buffer.from(salt, "hex"), expected.length);
 		return expected.length === actual.length && timingSafeEqual(expected, actual);
 	} catch {
 		return false;
@@ -301,13 +353,10 @@ function verifyPassword(state, password) {
 */
 function setPassword(state, password) {
 	const base = {
-		...state,
+		cookieSecret: state.cookieSecret,
 		sessionEpoch: state.sessionEpoch + 1
 	};
-	if (password === void 0) return {
-		cookieSecret: base.cookieSecret,
-		sessionEpoch: base.sessionEpoch
-	};
+	if (password === void 0) return base;
 	const salt = randomBytes(16);
 	const hash = scryptSync(password, salt, 64);
 	return {
@@ -318,12 +367,45 @@ function setPassword(state, password) {
 		}
 	};
 }
+/**
+* Record a session id as revoked.
+* @param expiresMs - the revoked cookie's own expiry. Past it the cookie is
+*   rejected on its own account, so the entry is no longer needed; dropping
+*   expired entries here is what keeps the list bounded.
+*/
+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);
@@ -337,6 +419,8 @@ function loadState(home = homedir()) {
 				sessionEpoch
 			};
 			if (parsed.password !== void 0) base.password = parsed.password;
+			const revoked = parseRevokedSessions(parsed.revokedSessions);
+			if (revoked !== void 0) base.revokedSessions = revoked;
 			return base;
 		}
 		return defaultState();
@@ -359,8 +443,9 @@ function saveState(state, home = homedir()) {
 //#endregion
 //#region src/gateway.ts
 /**
-* The reverse-proxy gateway: a `node:http(s)` server bound to `0.0.0.0` that
-* forwards every request to the loopback dsh web server.
+* The reverse-proxy gateway: a `node:http(s)` server bound to the unspecified
+* address (dual-stack, so IPv6 clients reach it too) that forwards every
+* request to the loopback dsh web server.
 *
 * Security model (post-QVD / session-base):
 * - Source is classified from `socket.remoteAddress` only (never
@@ -383,9 +468,10 @@ function saveState(state, home = homedir()) {
 *   authority-bound session cookie). The gateway therefore relays one shared
 *   upstream session acquired through the launch-token exchange and replays it
 *   on every forwarded request. See `upstream-session.ts`.
-* - Sessions carry a revocation epoch: a password change or secret rotation
-*   bumps the epoch, every previously issued cookie dies, and established
-*   WebSockets are torn down so the client re-authenticates.
+* - Sessions are revocable two ways. Each carries a random id, so signing out
+*   retires exactly that session and the WebSockets it opened; and each
+*   carries a revocation epoch, so a password change or secret rotation kills
+*   every session at once — cookie, socket, and all.
 *
 * @module @riceawa/dsh-lan-gateway/gateway
 */
@@ -398,14 +484,89 @@ const READ_ONLY_METHODS$1 = /* @__PURE__ */ new Set([
 	"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.
+*/
+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);
+}
+/**
+* Drop every `dsh-auth-*` pair from a Cookie header, returning the remainder
+* (possibly '').
+*
+* `attachUpstreamSession` appends the relay's session to the client's own
+* cookie, and upstream reads the FIRST name match. A client that holds any
+* `dsh-auth-<hash>` — typically one minted before dsh's signing secret was
+* reset, so still present but no longer verifying — would therefore shadow the
+* relay's session on every request. That draws a 401, the gateway reads the
+* 401 as "upstream revoked our session" and discards it, the next request
+* re-acquires, and the client's stale cookie shadows that one too: a loop that
+* never converges. Stripping the namespace makes the relay's copy the only one.
+*/
+function withoutUpstreamSessionPairs(cookie) {
+	return cookie.split(";").map((pair) => pair.trim()).filter((pair) => pair !== "" && !isUpstreamSessionPair(pair)).join("; ");
+}
 /** Prefixes the gateway owns and must never relay to dsh. */
 function isOwnedPath(pathname) {
 	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 pathname a request is routed by: the one dsh's router resolves it to
+* (WHATWG URL parsing, which strips the query and collapses dot segments),
+* with trailing slashes then removed for the gateway's own surface tests.
+*
+* The decision paths below (owned prefix, login, logout) must use this rather
+* than the raw request target. dsh normalizes before matching, so a raw-string
+* test disagrees with it on `/foo/../lan-gateway/config` — that is not an owned
+* path by string prefix, stays in the relay, and lands on the plugin's own
+* config route once Host has been rewritten to loopback. Forwarding still
+* relays the raw target: dsh applies the same normalization itself.
+*
+* WHATWG parsing does not drop a trailing slash, and neither does dsh's
+* router, so `/__login/` is not the login page to either of them. The gateway
+* recognizes its own surfaces there anyway: `/__logout/` must still sign out,
+* and `/lan-gateway/config/` must be refused rather than relayed into dsh's
+* single-page fallback. Blocking a trailing-slash spelling of an owned prefix
+* errs toward refusing, which costs nothing — no upstream route lives under it.
+*/
+function pathOf$1(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
@@ -418,8 +579,14 @@ 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();
+	/**
+	* 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;
@@ -439,7 +606,14 @@ var LanGateway = class {
 		if (state.sessionEpoch !== this.state.sessionEpoch) this.destroyActiveDuplexes();
 		this.state = state;
 	}
-	/** Start listening; rejects if the port is already in use. */
+	/**
+	* Start listening on the configured port. The listener is dual-stack: with
+	* no host given, node binds the unspecified IPv6 address `::` — which also
+	* accepts IPv4 clients, arriving as `::ffff:a.b.c.d` for the classifier to
+	* unwrap — when the host has IPv6, and falls back to `0.0.0.0` when it does
+	* not. Binding IPv4 only used to leave every IPv6 client (including `::1`)
+	* unable to reach a gateway that classifies them.
+	*/
 	async listen() {
 		return new Promise((resolve, reject) => {
 			const onError = (err) => {
@@ -452,9 +626,15 @@ var LanGateway = class {
 			};
 			this.server.once("error", onError);
 			this.server.once("listening", onListening);
-			this.server.listen(this.config.gatewayPort, "0.0.0.0");
+			this.server.listen(this.config.gatewayPort);
 		});
 	}
+	/** 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 upgraded sockets, and stop accepting connections. */
 	async close() {
 		if (this.disposed) return;
@@ -466,11 +646,19 @@ var LanGateway = class {
 		});
 	}
 	destroyActiveDuplexes() {
-		for (const socket of this.activeDuplexes) socket.destroy();
+		for (const socket of this.activeDuplexes.keys()) socket.destroy();
 		this.activeDuplexes.clear();
 	}
-	trackDuplex(socket) {
-		this.activeDuplexes.add(socket);
+	/** 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);
+			socket.destroy();
+		}
+	}
+	trackDuplex(socket, sid) {
+		this.activeDuplexes.set(socket, sid);
 		socket.on("close", () => {
 			this.activeDuplexes.delete(socket);
 		});
@@ -487,10 +675,21 @@ var LanGateway = class {
 			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);
+		if (cookie === void 0) return void 0;
+		const claims = verifySession(this.state.cookieSecret, cookie, Date.now(), this.state.sessionEpoch);
+		if (claims === void 0) return void 0;
+		return isSessionRevoked(this.state, claims.sid) ? void 0 : claims;
+	}
 	/** Whether a request carries a session valid under the current epoch. */
 	authorized(req) {
-		const cookie = this.sessionCookie(req);
-		return cookie !== void 0 && verifyCookie(this.state.cookieSecret, cookie, Date.now(), this.state.sessionEpoch);
+		return this.session(req) !== void 0;
 	}
 	/** Whether this source must present a gateway session (default: everyone). */
 	requiresLogin(source) {
@@ -539,7 +738,7 @@ var LanGateway = class {
 	/** Handle one HTTP request: anonymous allowlist → owned-path refuse → session gate → same-site gate → relay. */
 	async handleHttp(req, res) {
 		const url = req.url ?? "/";
-		const pathname = pathOf(url);
+		const pathname = pathOf$1(url);
 		const source = this.sourceOf(req);
 		if (pathname === "/__login") {
 			this.handleLogin(req, res);
@@ -582,7 +781,7 @@ var LanGateway = class {
 			this.serveLoginError(res, "Too many attempts — please wait a minute.");
 			return;
 		}
-		readBody(req, DEFAULT_BODY_LIMIT_BYTES, res).then((body) => {
+		readBody(req, DEFAULT_BODY_LIMIT_BYTES, res).then(async (body) => {
 			if (body === void 0) return;
 			let password;
 			try {
@@ -590,22 +789,36 @@ var LanGateway = class {
 			} catch {
 				password = void 0;
 			}
-			if (password === void 0 || !verifyPassword(this.state, password)) {
+			if (!(password !== void 0 && await verifyPassword(this.state, password))) {
 				this.serveLoginError(res, "Incorrect password.");
 				return;
 			}
 			const maxAgeSeconds = this.config.cookieMaxAgeDays * 86400;
 			const expiresMs = Date.now() + maxAgeSeconds * 1e3;
-			const cookie = signCookie(this.state.cookieSecret, expiresMs, this.state.sessionEpoch);
+			const cookie = signCookie(this.state.cookieSecret, expiresMs, this.state.sessionEpoch, newSessionId());
 			res.writeHead(302, {
 				location: "/",
 				...this.securityHeaders(),
 				"set-cookie": [this.sessionSetCookie(cookie, maxAgeSeconds)]
 			});
 			res.end();
+		}).catch(() => {
+			if (!res.headersSent) {
+				res.writeHead(500, this.securityHeaders());
+				res.end("login failed");
+			}
 		});
 	}
-	/** POST /__logout: sign an immediately-expired cookie and bounce to / . */
+	/**
+	* POST /__logout: revoke this session and clear the cookie.
+	*
+	* The session is stateless, so clearing the cookie only stops the browser
+	* that ran the sign-out; a copy of the same value held anywhere else would
+	* keep working until it expired. Revoking the id in the cookie retires that
+	* one session for good, and leaves the account's other sessions — other
+	* devices, other browsers — alone. Bumping the session epoch here would be
+	* the blunter instrument: it signs out every session there is.
+	*/
 	handleLogout(req, res) {
 		if (req.method !== "POST") {
 			res.writeHead(405, { allow: "POST" });
@@ -617,6 +830,12 @@ var LanGateway = class {
 			res.end("forbidden");
 			return;
 		}
+		const claims = this.session(req);
+		if (claims?.sid !== void 0) {
+			this.state = revokeSession(this.state, claims.sid, claims.exp);
+			this.config.onStateChange?.(this.state);
+			this.destroyDuplexesFor(claims.sid);
+		}
 		res.writeHead(302, {
 			location: "/",
 			...this.securityHeaders(),
@@ -634,6 +853,12 @@ var LanGateway = class {
 			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. */
@@ -646,6 +871,29 @@ var LanGateway = class {
 		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;
+	}
 	/** Forward an HTTP request to dsh, replaying the shared upstream session. */
 	async relayHttp(req, res, url) {
 		const session = this.config.upstreamSession;
@@ -660,7 +908,7 @@ var LanGateway = class {
 			headers
 		}, (proxyRes) => {
 			if (attached && session !== void 0 && proxyRes.statusCode === 401) session.invalidate();
-			res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+			res.writeHead(proxyRes.statusCode ?? 502, this.downstreamHeaders(proxyRes.headers));
 			proxyRes.pipe(res);
 		});
 		proxyReq.on("error", () => {
@@ -672,7 +920,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(url);
+		const pathname = pathOf$1(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`);
@@ -682,7 +930,8 @@ var LanGateway = class {
 			refuse(403);
 			return;
 		}
-		if (this.requiresLogin(source) && !this.authorized(req)) {
+		const claims = this.session(req);
+		if (this.requiresLogin(source) && claims === void 0) {
 			refuse(401);
 			return;
 		}
@@ -702,7 +951,7 @@ var LanGateway = class {
 			headers
 		});
 		proxyReq.on("upgrade", (proxyRes, proxySocket, proxyHead) => {
-			this.trackDuplex(socket);
+			this.trackDuplex(socket, claims?.sid);
 			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`);
@@ -982,6 +1231,29 @@ function loadOrCreateSelfSigned(opts, home = homedir()) {
 	};
 }
 /**
+* Load the self-signed material a listener should serve: generate it on first
+* use, reuse the persisted pair otherwise, and replace a persisted certificate
+* whose validity has already lapsed.
+*
+* Nothing renews a self-signed certificate in place, and a browser refuses a
+* lapsed one outright, so without this a certificate that ran out would keep
+* being served until an operator happened to read the expiry date out of
+* `status` and act on it. Renewing mints a fresh key, so a client that had
+* trusted the old certificate has to trust the new one — but that is the case
+* either way, the old one having lapsed.
+*/
+function loadOrRenewSelfSigned(opts, home = homedir()) {
+	const { material, created } = loadOrCreateSelfSigned(opts, home);
+	if (created || !isCertExpired(material.cert)) return {
+		material,
+		renewed: false
+	};
+	return {
+		material: regenerateSelfSigned(opts, home),
+		renewed: true
+	};
+}
+/**
 * Force-regenerate the self-signed certificate (new key + cert), replacing
 * the persisted files. Used by `lan_gateway tls-regenerate`.
 */
@@ -1041,6 +1313,15 @@ function loadCustomCert(certPath, keyPath) {
 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);
@@ -1155,6 +1436,18 @@ function nameValueOnly(setCookie) {
 	const semi = setCookie.indexOf(";");
 	return (semi === -1 ? setCookie : setCookie.slice(0, semi)).trim();
 }
+/**
+* The pathname of a URL, for logging. Never the whole URL: the authenticated
+* URL carries the launch token as a query parameter, and that token is a
+* bearer credential for the upstream harness.
+*/
+function pathOf(url) {
+	try {
+		return new URL(url).pathname;
+	} catch {
+		return "<unparseable>";
+	}
+}
 /** The cookie name of a `Set-Cookie` string (`''` when it is malformed). */
 function cookieNameOf(setCookie) {
 	const eq = setCookie.indexOf("=");
@@ -1183,12 +1476,13 @@ function maxAgeSeconds(setCookie) {
 * or no session cookie came back — e.g. an older base without browser
 * sessions).
 */
-function exchange(url, authority, port) {
+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;
 		}
@@ -1205,23 +1499,34 @@ function exchange(url, authority, port) {
 			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 raw = (Array.isArray(setCookies) ? setCookies : [setCookies]).find(isUpstreamSessionCookie);
+			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", () => resolve(void 0));
-		request.setTimeout(5e3, () => request.destroy(/* @__PURE__ */ new Error("upstream-session exchange timeout")));
+		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();
 	});
 }
@@ -1234,12 +1539,14 @@ 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() {
@@ -1251,6 +1558,7 @@ var UpstreamSessionRelay = class {
 		return this.held?.header;
 	}
 	invalidate() {
+		if (this.held !== void 0) this.log("invalidating held session (upstream rejected it)");
 		this.held = void 0;
 	}
 	async cookie() {
@@ -1267,9 +1575,16 @@ var UpstreamSessionRelay = class {
 	}
 	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;
+		if (url === void 0) {
+			this.log("authenticatedUrl() returned undefined; keeping current session");
+			return this.held?.header;
+		}
+		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;
 	}
 };
@@ -1310,7 +1625,8 @@ const Config = z.object({
 	tlsSelfSignedHosts: z.string().default("localhost"),
 	tlsCertMaxAgeDays: z.natural().min(1).max(3650).default(825),
 	allowInsecurePlaintext: z.boolean().default(false),
-	trustedTerminator: z.string()
+	trustedTerminator: z.string(),
+	secureCookies: z.boolean()
 });
 /**
 * The fail-closed problems that prevent a config from enabling the listener.
@@ -1324,17 +1640,34 @@ function gatewayStartProblems(cfg, facts) {
 	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 effective `Secure` attribute for the session cookie: an explicit
+* `secureCookies` always wins; unset falls back to automatic — Secure when the
+* gateway terminates TLS itself or a trusted terminator is declared. The
+* override exists for a trusted proxy that authenticates users but speaks plain
+* HTTP to browsers: `encryptedIngress` is a fair proxy for "a proxy is in front"
+* but not for "the browser leg is encrypted", and a Secure cookie on a plain
+* HTTP origin is silently dropped, looping the login.
+*
+* Exported for tests.
+*/
+function resolveSecureCookies(cfg) {
+	if (typeof cfg.secureCookies === "boolean") return cfg.secureCookies;
+	return cfg.tlsEnabled || cfg.trustedTerminator !== void 0;
+}
 /** Resolve the TLS material for a config, or undefined when TLS is off. */
 function resolveTls(cfg) {
 	if (!cfg.tlsEnabled) return void 0;
-	if (cfg.tlsMode === "custom") return loadCustomCert(cfg.tlsCertPath ?? "", cfg.tlsKeyPath ?? "");
+	if (cfg.tlsMode === "custom") return {
+		material: loadCustomCert(cfg.tlsCertPath ?? "", cfg.tlsKeyPath ?? ""),
+		renewed: false
+	};
 	const hosts = parseSelfSignedHosts(cfg.tlsSelfSignedHosts);
 	if (hosts.length === 0) throw new Error("tlsSelfSignedHosts must name at least one host (DNS name or IP)");
-	const { material } = loadOrCreateSelfSigned({
+	return loadOrRenewSelfSigned({
 		hosts,
 		days: cfg.tlsCertMaxAgeDays
 	});
-	return material;
 }
 /**
 * Config fields that require a listener restart when they change, plus whether
@@ -1360,6 +1693,7 @@ function listenerKey(cfg, relayAvailable) {
 		cfg.tlsCertMaxAgeDays,
 		cfg.allowInsecurePlaintext,
 		cfg.trustedTerminator,
+		cfg.secureCookies,
 		relayAvailable
 	]);
 }
@@ -1435,8 +1769,10 @@ function apply(ctx, config) {
 		if (state.password === void 0) problems.unshift("no password set — run `lan_gateway set-password` before enabling the listener");
 		if (problems.length > 0) throw new Error(`dsh-lan-gateway: cannot start — ${problems.join(" ")}`);
 		const dshPort = cfg.dshTargetPort ?? ctx.webServer.port;
-		const tls = resolveTls(cfg);
+		const resolved = resolveTls(cfg);
+		const tls = resolved?.material;
 		const encryptedIngress = cfg.tlsEnabled || cfg.trustedTerminator !== void 0;
+		const secureCookies = resolveSecureCookies(cfg);
 		const next = new LanGateway({
 			gatewayPort: cfg.gatewayPort,
 			dshPort,
@@ -1444,14 +1780,19 @@ function apply(ctx, config) {
 			lanPasswordless: cfg.lanPasswordless,
 			cookieMaxAgeDays: cfg.cookieMaxAgeDays,
 			cookieName: cfg.cookieName,
-			secureCookies: encryptedIngress,
+			secureCookies,
 			...tls !== void 0 ? { tls } : {},
-			...makeRelay !== void 0 ? { upstreamSession: makeRelay(dshPort) } : {}
+			...makeRelay !== void 0 ? { upstreamSession: makeRelay(dshPort) } : {},
+			onStateChange: (updated) => {
+				state = updated;
+				saveState(state);
+			}
 		}, state);
 		await next.listen();
 		gateway = next;
 		startedWith = listenerKey(cfg, makeRelay !== void 0);
-		ctx.logger.info(`dsh-lan-gateway: listening on 0.0.0.0:${cfg.gatewayPort}${tls !== void 0 ? " (TLS)" : ""} -> 127.0.0.1:${dshPort}${encryptedIngress ? "" : " (plaintext, explicit allowInsecurePlaintext)"}${makeRelay !== void 0 ? " [shared upstream session relay]" : " [no upstream session relay: base has no browser-session auth]"}`);
+		ctx.logger.info(`dsh-lan-gateway: listening on ${next.boundAddress()}${tls !== void 0 ? " (TLS)" : ""} -> 127.0.0.1:${dshPort}${encryptedIngress ? "" : " (plaintext, explicit allowInsecurePlaintext)"}${makeRelay !== void 0 ? " [shared upstream session relay]" : " [no upstream session relay: base has no browser-session auth]"}`);
+		if (resolved?.renewed === true) ctx.logger.warn("dsh-lan-gateway: the self-signed certificate had expired and was replaced with a fresh one — clients that had trusted the old certificate must trust the new one.");
 	};
 	const stopGateway = async () => {
 		const current = gateway;
@@ -1499,9 +1840,11 @@ function apply(ctx, config) {
 	});
 	ctx.inject(["connection"], (ccx) => {
 		upstreamSessionAvailable = true;
+		ctx.logger.info("dsh-lan-gateway: connection service attached; upstream session relay enabled");
 		makeRelay = (dshPort) => new UpstreamSessionRelay({
 			port: dshPort,
-			authenticatedUrl: () => ccx.connection.authenticatedUrl(`http://127.0.0.1:${dshPort}`)
+			authenticatedUrl: () => ccx.connection.authenticatedUrl(`http://127.0.0.1:${dshPort}`),
+			log: (message) => ctx.logger.info(`dsh-lan-gateway relay: ${message}`)
 		});
 		syncGateway("connection attach");
 	});
@@ -1594,7 +1937,7 @@ function apply(ctx, config) {
 			const encrypted = cfg.tlsEnabled || cfg.trustedTerminator !== void 0;
 			return {
 				ok: true,
-				message: `LAN gateway: ${gateway !== void 0 ? `LISTENING on 0.0.0.0:${cfg.gatewayPort}` : "stopped"}\n- dsh target: 127.0.0.1:${dshPort}\n- password: ${state.password !== void 0 ? "set" : "NOT SET"}\n- login required for all sources: true${cfg.lanPasswordless ? " (LAN/loopback exempt via lanPasswordless)" : ""}\n- session epoch: ${state.sessionEpoch}\n- upstream session relay: ${upstreamSessionAvailable ? "active (dsh browser-session auth present)" : "absent (older dsh base)"}\n- ingress: ${cfg.tlsEnabled ? `TLS (${tlsStatusLine(cfg)})` : cfg.trustedTerminator !== void 0 ? `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}` : "")
+				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}` : "")
 			};
 		},
 		async enable() {
@@ -1602,7 +1945,7 @@ function apply(ctx, config) {
 			await syncGateway("tool enable");
 			return gateway !== void 0 ? {
 				ok: true,
-				message: `Gateway enabled: listening on 0.0.0.0:${effective().gatewayPort}`
+				message: `Gateway enabled: listening on ${gateway.boundAddress()}`
 			} : {
 				ok: false,
 				message: `Failed to enable gateway: ${lastError ?? "unknown error"}`
@@ -1697,4 +2040,4 @@ function apply(ctx, config) {
 	}, "dsh-lan-gateway: listener lifecycle");
 }
 //#endregion
-export { Config, apply, gatewayStartProblems, inject, isTrustedConfigRequest, name };
+export { Config, apply, gatewayStartProblems, inject, isTrustedConfigRequest, name, resolveSecureCookies };