@linxin666/dsh-remote-web-ui 0.3.12 → 0.3.13

package/lib/index.js

@@ -11,6 +11,7 @@ import { z as z$1 } from "zod";
 import http, { request } from "node:http";
 import { connect } from "node:net";
 import { spawn, spawnSync } from "node:child_process";
+import { EventEmitter } from "node:events";
 import { Tunnel, bin, install } from "cloudflared";
 //#region src/pairing.ts
 /**
@@ -86,6 +87,7 @@ var PairingService = class {
 	publicBase;
 	/** Auto-tunnel status, while the auto-tunnel feature is active. */
 	tunnelStatus;
+	relayStatus;
 	posture;
 	/** True when lastSeenAt changed since the last persist (flushed on sweep). */
 	dirty = false;
@@ -201,6 +203,11 @@ var PairingService = class {
 		this.tunnelStatus = status;
 		this.notify();
 	}
+	/** Set or clear the relay-registry status frame (undefined when not in play). */
+	setRelayStatus(status) {
+		this.relayStatus = status;
+		this.notify();
+	}
 	/** Set the latest /api posture probe result (see posture.ts). */
 	setPosture(snapshot) {
 		this.posture = snapshot;
@@ -349,6 +356,7 @@ var PairingService = class {
 			lanAddresses: [...this.lanBases.keys()],
 			...this.publicBase !== void 0 ? { publicUrl: this.publicBase } : {},
 			...this.tunnelStatus !== void 0 ? { tunnel: this.tunnelStatus } : {},
+			...this.relayStatus !== void 0 ? { relay: this.relayStatus } : {},
 			...this.posture !== void 0 ? { posture: this.posture } : {},
 			...token !== void 0 ? {
 				tokenId: token.record.id,
@@ -430,7 +438,7 @@ var PairingService = class {
 };
 /** Structural equality over the snapshot's wire fields. */
 function snapshotsEqual(a, b) {
-	return a.phase === b.phase && a.lanAvailable === b.lanAvailable && sameStrings(a.lanAddresses, b.lanAddresses) && a.publicUrl === b.publicUrl && tunnelEqual(a.tunnel, b.tunnel) && a.tokenId === b.tokenId && a.tokenExpiresAt === b.tokenExpiresAt && a.deviceCount === b.deviceCount && a.onlineCount === b.onlineCount && devicesEqual(a.devices, b.devices);
+	return a.phase === b.phase && a.lanAvailable === b.lanAvailable && sameStrings(a.lanAddresses, b.lanAddresses) && a.publicUrl === b.publicUrl && tunnelEqual(a.tunnel, b.tunnel) && relayEqual(a.relay, b.relay) && a.tokenId === b.tokenId && a.tokenExpiresAt === b.tokenExpiresAt && a.deviceCount === b.deviceCount && a.onlineCount === b.onlineCount && devicesEqual(a.devices, b.devices);
 }
 /** Per-device roster equality (order is pairing time). */
 function devicesEqual(a, b) {
@@ -443,6 +451,10 @@ function devicesEqual(a, b) {
 function tunnelEqual(a, b) {
 	return a === b || a !== void 0 && b !== void 0 && a.state === b.state && a.url === b.url && a.error === b.error;
 }
+/** Relay frame equality (same shape as the tunnel frame). */
+function relayEqual(a, b) {
+	return a === b || a !== void 0 && b !== void 0 && a.state === b.state && a.url === b.url && a.error === b.error;
+}
 /** Element-wise string list equality (interface order is meaningful). */
 function sameStrings(a, b) {
 	return a.length === b.length && a.every((value, index) => value === b[index]);
@@ -2308,6 +2320,224 @@ function writeLanBind(host, port, profile, home = dshHome()) {
 	renameSync(temp, file);
 }
 //#endregion
+//#region src/tunnel-plan.ts
+/**
+* Pure planner for the settings-sync tunnel branch: given the resolved
+* settings slice, decide which tunnel mode runs and with what target. Kept
+* free of cordis types so the precedence matrix is unit-testable without a
+* host context.
+*/
+/** Whether a configured public base is a parseable http(s) URL with a host. */
+function isHttpUrl(value) {
+	try {
+		const url = new URL(value);
+		return (url.protocol === "http:" || url.protocol === "https:") && url.hostname !== "";
+	} catch {
+		return false;
+	}
+}
+/**
+* Decide the tunnel mode and target from one resolved settings value.
+* Precedence: the quick tunnel wins when `autoTunnel` is on (anything else
+* configured is reported as ignored); the named tunnel runs only with a
+* token AND a valid public hostname (the token does not carry the hostname,
+* so the QR base and the fence trust would have no source without it);
+* otherwise no tunnel and the manual public base applies.
+* @param value - the resolved settings slice that drives the tunnel.
+* @param port - the local webServer port the tunnel forwards to.
+*/
+function tunnelPlanOf(value, port) {
+	if (value.autoTunnel === true) {
+		const ignored = [];
+		if (value.tunnelToken !== void 0 && value.tunnelToken !== "") ignored.push("tunnelToken");
+		if (value.publicBaseUrl !== void 0 && value.publicBaseUrl !== "") ignored.push("publicBaseUrl");
+		return {
+			mode: "quick",
+			targetUrl: `http://127.0.0.1:${String(port)}`,
+			ignored
+		};
+	}
+	if (value.tunnelToken !== void 0 && value.tunnelToken !== "") {
+		if (value.publicBaseUrl !== void 0 && isHttpUrl(value.publicBaseUrl)) return {
+			mode: "named",
+			token: value.tunnelToken,
+			publicUrl: value.publicBaseUrl
+		};
+		return { mode: "off" };
+	}
+	return { mode: "off" };
+}
+const RELAY_UNREGISTER_URL = "https://dsh-market.com/api/relay/unregister";
+/**
+* The public origin template: one stable single-label subdomain per
+* registration id. Single label on purpose — Universal SSL covers exactly
+* one subdomain level, so a two-level hostname would get no certificate.
+*/
+const RELAY_BASE_SUFFIX = ".dsh-market.com";
+const RELAY_ID_RE = /^[a-z0-9]{16}$/;
+const RELAY_SECRET_RE = /^[A-Za-z0-9_-]{43}$/;
+/** Registry storage layout: one file per profile under the relay directory. */
+function relayIdentityFile(profile, home = dshHome()) {
+	if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(profile)) throw new Error(`relay registry: profile ${JSON.stringify(profile)} is not a safe path segment`);
+	return join(home, "remote-web-ui-registry", `${profile}.json`);
+}
+/** Generate one identity pair (id: 8-byte hex slug; secret: 32-byte base64url). */
+function generateRelayIdentity(random = randomBytes) {
+	return {
+		id: random(8).toString("hex"),
+		secret: random(32).toString("base64url"),
+		fresh: true
+	};
+}
+/**
+* Load (or lazily mint) the per-profile relay identity. The file is written
+* owner-only on first mint; a corrupt file is reminted (the phone then
+* re-pairs once — the same cost as losing the devices file).
+*/
+function loadRelayIdentity(profile, home = dshHome(), random = randomBytes) {
+	const file = relayIdentityFile(profile, home);
+	try {
+		if (existsSync(file)) {
+			const parsed = JSON.parse(readFileSync(file, "utf8"));
+			if (typeof parsed.id === "string" && RELAY_ID_RE.test(parsed.id) && typeof parsed.secret === "string" && RELAY_SECRET_RE.test(parsed.secret)) return {
+				id: parsed.id,
+				secret: parsed.secret
+			};
+			console.warn(`relay registry: ${file} is malformed — reminting the identity (paired devices must scan the QR once more)`);
+		}
+	} catch (error) {
+		console.warn(`relay registry: could not read ${file} (${error instanceof Error ? error.message : String(error)}) — reminting`);
+	}
+	const identity = generateRelayIdentity(random);
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, JSON.stringify({
+		id: identity.id,
+		secret: identity.secret
+	}, null, 2) + "\n", { mode: 384 });
+	return identity;
+}
+/** Build the registration request body for one identity + tunnel target. */
+function registrationBody(identity, target) {
+	return JSON.stringify({
+		id: identity.id,
+		secret: identity.secret,
+		new_secret: identity.fresh === true ? identity.secret : void 0,
+		target
+	});
+}
+/** Best-effort removal of the mapping (used on disable; errors are swallowed). */
+async function unregisterRelay(identity, endpoint = RELAY_UNREGISTER_URL, fetchFn = fetch) {
+	await fetchFn(endpoint, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({
+			id: identity.id,
+			secret: identity.secret
+		})
+	});
+}
+/**
+* The stable relay base for one identity — the origin the QR and the phone
+* bookmark use while (or after) the registration is accepted.
+*/
+function relayBaseOf(identity) {
+	return `https://${identity.id}${RELAY_BASE_SUFFIX}`;
+}
+/**
+* Registration loop with capped exponential backoff. Re-registration happens
+* on every tunnel start (the quick URL can change after a crash-restart);
+* failures retry with backoff and surface the last error to the card.
+*/
+var RelayRegistrar = class {
+	identity;
+	setState;
+	options;
+	timer;
+	attempts = 0;
+	lastError;
+	disposed = false;
+	constructor(identity, setState, options = {}) {
+		this.identity = identity;
+		this.setState = setState;
+		this.options = options;
+	}
+	/** The stable relay base for the QR while registered. */
+	get baseUrl() {
+		return relayBaseOf(this.identity);
+	}
+	/** The last registration failure detail (undefined while healthy). */
+	get error() {
+		return this.lastError;
+	}
+	/** Push one tunnel target; resolves the stable base once accepted. */
+	async announce(target) {
+		if (this.disposed) return void 0;
+		if (this.timer !== void 0) {
+			clearTimeout(this.timer);
+			this.timer = void 0;
+		}
+		this.setState({ state: "registering" });
+		try {
+			const response = await (this.options.fetchFn ?? fetch)(this.options.registerUrl ?? "https://dsh-market.com/api/relay/register", {
+				method: "PUT",
+				headers: { "content-type": "application/json" },
+				body: registrationBody(this.identity, target)
+			});
+			if (!response.ok) {
+				const detail = await response.json().catch(() => void 0);
+				const error = detail && typeof detail.error === "string" ? detail.error : `HTTP ${String(response.status)}`;
+				throw new Error(error);
+			}
+			this.identity.fresh = false;
+			this.attempts = 0;
+			this.lastError = void 0;
+			this.setState({
+				state: "running",
+				url: this.baseUrl
+			});
+			return this.baseUrl;
+		} catch (error) {
+			this.lastError = error instanceof Error ? error.message : String(error);
+			if (this.lastError === "invalid-params" && this.identity.fresh !== true) this.identity.fresh = true;
+			this.setState({
+				state: "failed",
+				error: this.lastError
+			});
+			this.scheduleRetry(target);
+			return;
+		}
+	}
+	/** Best-effort removal of the registry row (the relay toggle turned off). */
+	async unregister() {
+		await unregisterRelay(this.identity, this.options.unregisterUrl, this.options.fetchFn);
+	}
+	scheduleRetry(target) {
+		if (this.disposed) return;
+		const base = this.options.baseDelayMs ?? 5e3;
+		const max = this.options.maxDelayMs ?? 6e4;
+		const delay = Math.min(base * 2 ** this.attempts, max);
+		this.attempts += 1;
+		const timerFn = this.options.timerFn ?? ((fn, ms) => {
+			const timer = setTimeout(fn, ms);
+			timer.unref?.();
+			return timer;
+		});
+		this.timer = timerFn(() => {
+			this.timer = void 0;
+			this.announce(target);
+		}, delay);
+	}
+	/** Stop retrying and clear the card state (tunnel stopped or disabled). */
+	dispose() {
+		this.disposed = true;
+		if (this.timer !== void 0) {
+			clearTimeout(this.timer);
+			this.timer = void 0;
+		}
+		this.setState({ state: "off" });
+	}
+};
+//#endregion
 //#region src/lan-bind-plan.ts
 /**
 * The bind host the managed block should pin: an explicit CLI --host wins,
@@ -2406,11 +2636,14 @@ function createInnerAuth(launchUrl, fetchImpl = fetch) {
 //#endregion
 //#region src/tunnel.ts
 /**
-* Auto-tunnel manager: spawns a Cloudflare quick tunnel (`cloudflared
-* tunnel --url <local>`) through the `cloudflared` npm package — its
-* postinstall downloads the platform binary, so no user-side tooling is
-* involved — surfaces the minted `https://xxx.trycloudflare.com` URL, and
-* restarts the process after unexpected exits with exponential backoff.
+* Auto-tunnel manager: spawns a Cloudflare tunnel through the `cloudflared`
+* npm package — its postinstall downloads the platform binary, so no
+* user-side tooling is involved — surfaces the public URL, and restarts the
+* process after unexpected exits with exponential backoff. Two modes: the
+* accountless quick tunnel (`https://xxx.trycloudflare.com`, hostname minted
+* per start) and an account named tunnel (`cloudflared tunnel run --token`,
+* fixed public hostname — the mode that lets a paired phone keep its
+* bookmark and pairing cookie across restarts).
 *
 * The cloudflared package's Tunnel is a thin spawn wrapper; this manager
 * owns the lifecycle policy (binary readiness, URL timeout, restart
@@ -2418,17 +2651,75 @@ function createInnerAuth(launchUrl, fetchImpl = fetch) {
 * timers — are injectable so the whole lifecycle is unit-testable without
 * a real binary or network.
 */
+/** Compare two targets for the start idempotence check. */
+function sameTarget(left, right) {
+	if (left === void 0) return false;
+	return JSON.stringify(left) === JSON.stringify(right);
+}
+/**
+* Wrap a named-tunnel process so it fits the quick-tunnel handle shape: the
+* fixed public URL is reported through the same `url` event once the first
+* edge connection registers (cloudflared fires `connected` per connection,
+* so only the first is taken), and exit/error pass through. The manager's
+* URL timeout, crash-restart backoff, and stop semantics then stay fully
+* mode-agnostic.
+* @param inner - the running named-tunnel process.
+* @param publicUrl - the fixed public hostname ingress maps to this server.
+* @returns a handle emitting `url` once the tunnel is reachable.
+*/
+function namedTunnelHandle(inner, publicUrl) {
+	const handle = new EventEmitter();
+	let registered = false;
+	const onConnected = () => {
+		if (registered) return;
+		registered = true;
+		handle.emit("url", publicUrl);
+	};
+	const onExit = (code, signal) => {
+		handle.emit("exit", code, signal);
+	};
+	const onError = (value) => {
+		handle.emit("error", value);
+	};
+	inner.on("connected", onConnected);
+	inner.on("exit", onExit);
+	inner.on("error", onError);
+	handle.stop = () => {
+		inner.off("connected", onConnected);
+		inner.off("exit", onExit);
+		inner.off("error", onError);
+		return inner.stop();
+	};
+	return handle;
+}
 /** Default binary readiness: download the platform binary on first use. */
 async function defaultEnsureBinary() {
 	if (existsSync(bin)) return;
 	await install(bin);
 }
-/** Default factory: the cloudflared package's quick tunnel (no account). */
-function defaultFactory(targetUrl) {
-	return Tunnel.quick(targetUrl, {
-		"--no-autoupdate": true,
-		"--protocol": "http2"
-	});
+/** The flags every tunnel mode shares (see the quick factory comment). */
+const SHARED_TUNNEL_FLAGS = {
+	"--no-autoupdate": true,
+	"--protocol": "http2"
+};
+/**
+* Spawn flags for one quick target. `originHostHeader` stamps the Host the
+* local webserver sees: the plugin's phone-facing fence trusts the configured
+* public host (the stable relay origin, Host-bound) and the harness
+* browser-auth binds cookies to the Host authority, while the Workers relay
+* cannot control the origin-side Host at all (fetch forces it to the URL
+* authority) — so the connector must restamp it with the stable origin.
+*/
+function quickTunnelFlags(originHostHeader) {
+	return originHostHeader === void 0 ? { ...SHARED_TUNNEL_FLAGS } : {
+		...SHARED_TUNNEL_FLAGS,
+		"--http-host-header": originHostHeader
+	};
+}
+/** Default factory: the cloudflared package's quick and named tunnels. */
+function defaultFactory(target) {
+	if (target.kind === "quick") return Tunnel.quick(target.targetUrl, quickTunnelFlags(target.originHostHeader));
+	return namedTunnelHandle(Tunnel.withToken(target.token, { ...SHARED_TUNNEL_FLAGS }), target.publicUrl);
 }
 /** Node timers. */
 const nodeTimer = {
@@ -2449,7 +2740,7 @@ var TunnelManager = class {
 	phase = "stopped";
 	url;
 	error;
-	targetUrl;
+	target;
 	handle;
 	urlTimer;
 	restartTimer;
@@ -2478,16 +2769,24 @@ var TunnelManager = class {
 		};
 	}
 	/**
-	* Start (or keep) a quick tunnel toward `targetUrl`. Restarting with a
-	* different target tears the old tunnel down first; restarting with the
-	* same target while running is a no-op.
-	* @param targetUrl - the local URL to expose, e.g. `http://127.0.0.1:3080`.
+	* Start (or keep) a tunnel toward `target`. Restarting with a different
+	* target tears the old tunnel down first; restarting with the same target
+	* while running is a no-op. A string is the quick mode's local target URL.
+	*
+	* In quick mode the URL surfaces when cloudflared mints the ephemeral
+	* trycloudflare hostname; in named mode the fixed `publicUrl` surfaces
+	* once the first edge connection registers (see {@link namedTunnelHandle}).
+	* @param target - what to run (a string means quick toward that local URL).
 	*/
-	start(targetUrl) {
-		if (this.targetUrl === targetUrl && (this.phase === "starting" || this.phase === "running")) return;
+	start(target) {
+		const resolved = typeof target === "string" ? {
+			kind: "quick",
+			targetUrl: target
+		} : target;
+		if (sameTarget(this.target, resolved) && (this.phase === "starting" || this.phase === "running")) return;
 		this.teardown();
 		this.stopping = false;
-		this.targetUrl = targetUrl;
+		this.target = resolved;
 		this.attempts = 0;
 		this.generation += 1;
 		this.attempt();
@@ -2496,7 +2795,7 @@ var TunnelManager = class {
 	stop() {
 		this.teardown();
 		this.stopping = false;
-		this.targetUrl = void 0;
+		this.target = void 0;
 		this.setPhase("stopped");
 	}
 	/** Alias of {@link stop} for plugin-effect disposal. */
@@ -2518,15 +2817,15 @@ var TunnelManager = class {
 		};
 	}
 	attempt() {
-		if (this.stopping || this.targetUrl === void 0) return;
+		if (this.stopping || this.target === void 0) return;
 		const gen = this.generation;
 		this.setPhase("starting");
 		this.handle = void 0;
 		this.url = void 0;
 		this.error = void 0;
 		this.ensureBinary().then(() => {
-			if (this.stopping || this.targetUrl === void 0 || gen !== this.generation) return;
-			const handle = this.factory(this.targetUrl);
+			if (this.stopping || this.target === void 0 || gen !== this.generation) return;
+			const handle = this.factory(this.target);
 			this.handle = handle;
 			this.urlTimer = this.timer.setTimeout(() => {
 				this.fail("timed out waiting for the tunnel URL");
@@ -2544,7 +2843,7 @@ var TunnelManager = class {
 				this.error = value instanceof Error ? value.message : String(value);
 			});
 		}).catch((value) => {
-			if (this.stopping || this.targetUrl === void 0 || gen !== this.generation) return;
+			if (this.stopping || this.target === void 0 || gen !== this.generation) return;
 			const message = value instanceof Error ? value.message : String(value);
 			this.fail(`could not obtain the cloudflared binary: ${message}`);
 		});
@@ -3418,6 +3717,8 @@ const Config = z.object({
 	publicBaseUrl: z.string(),
 	devicesFile: z.string(),
 	autoTunnel: z.boolean().default(false),
+	tunnelToken: z.string().role("secret"),
+	relay: z.boolean().default(true),
 	lanBind: z.boolean(),
 	profile: z.string().pattern(/^[A-Za-z0-9][A-Za-z0-9._-]*$/),
 	enabled: z.boolean().default(true)
@@ -3455,6 +3756,8 @@ const DEFAULTS = {
 	publicBaseUrl: void 0,
 	devicesFile: defaultDevicesFile(),
 	autoTunnel: false,
+	tunnelToken: void 0,
+	relay: true,
 	lanBind: void 0,
 	profile: process.env.DSH_PROFILE ?? "web",
 	enabled: true
@@ -3476,6 +3779,8 @@ function applyImpl(ctx, config) {
 		publicBaseUrl: config?.publicBaseUrl,
 		devicesFile: config?.devicesFile ?? DEFAULTS.devicesFile,
 		autoTunnel: config?.autoTunnel ?? DEFAULTS.autoTunnel,
+		tunnelToken: config?.tunnelToken,
+		relay: config?.relay ?? DEFAULTS.relay,
 		lanBind: config?.lanBind,
 		profile: config?.profile ?? process.env.DSH_PROFILE ?? DEFAULTS.profile,
 		enabled: config?.enabled ?? DEFAULTS.enabled
@@ -3493,6 +3798,8 @@ function applyImpl(ctx, config) {
 			publicBaseUrl: value.publicBaseUrl,
 			devicesFile: value.devicesFile ?? DEFAULTS.devicesFile,
 			autoTunnel: value.autoTunnel ?? DEFAULTS.autoTunnel,
+			tunnelToken: value.tunnelToken,
+			relay: value.relay ?? DEFAULTS.relay,
 			lanBind: value.lanBind,
 			profile: value.profile ?? process.env.DSH_PROFILE ?? DEFAULTS.profile,
 			enabled: value.enabled ?? DEFAULTS.enabled
@@ -3500,21 +3807,64 @@ function applyImpl(ctx, config) {
 	};
 	const service = new PairingService(pairingConfigOf(resolved));
 	const tunnel = new TunnelManager();
-	let autoTunnel = resolved.autoTunnel;
+	let relayRegistrar;
+	let relayUrl;
+	let rawTunnelUrl;
+	/** The tunnel target the registrar last announced (dedupes sync re-runs). */
+	let relayAnnouncedFor;
+	const setPublicBase = () => {
+		service.setPublicBaseUrl(relayUrl ?? rawTunnelUrl);
+	};
+	const disposeRelayRegistrar = (unregister = false) => {
+		const registrar = relayRegistrar;
+		relayRegistrar = void 0;
+		relayUrl = void 0;
+		relayAnnouncedFor = void 0;
+		if (registrar === void 0) return;
+		if (unregister) registrar.unregister().catch(() => void 0);
+		registrar.dispose();
+	};
+	const ensureRelayRegistrar = () => {
+		if (resolve().relay === false) return void 0;
+		if (relayRegistrar === void 0) try {
+			relayRegistrar = new RelayRegistrar(loadRelayIdentity(resolve().profile), (state) => {
+				service.setRelayStatus(state.state === "off" ? void 0 : state);
+				if (state.state === "running") relayUrl = state.url;
+				else if (state.state === "off") relayUrl = void 0;
+				else if (state.state === "failed") console.warn(`remote-web-ui: relay registration failed (${state.error}) — the stable origin may serve its offline page until the retry lands`);
+				setPublicBase();
+			});
+		} catch (error) {
+			console.warn(`remote-web-ui: relay registry unavailable (${error instanceof Error ? error.message : String(error)}) — the quick URL is the QR base`);
+		}
+		return relayRegistrar;
+	};
+	const announceRelay = (registrar, target) => {
+		if (relayAnnouncedFor === target) return;
+		relayAnnouncedFor = target;
+		registrar.announce(target);
+	};
+	let tunnelMode = resolved.autoTunnel ? "quick" : "off";
 	tunnel.onPhase((info) => {
-		if (!autoTunnel) return;
+		if (tunnelMode === "off") return;
 		if (info.phase === "running" && info.url !== void 0) {
-			service.setPublicBaseUrl(info.url);
+			rawTunnelUrl = info.url;
+			setPublicBase();
 			service.setTunnelStatus({
 				state: "running",
 				url: info.url
 			});
+			const registrar = tunnelMode === "quick" ? ensureRelayRegistrar() : void 0;
+			if (registrar !== void 0) announceRelay(registrar, info.url);
 			runPostureProbe();
 		} else if (info.phase === "starting") {
-			service.setPublicBaseUrl(void 0);
+			rawTunnelUrl = void 0;
+			relayUrl = void 0;
+			setPublicBase();
 			service.setTunnelStatus({ state: "starting" });
 		} else if (info.phase === "failed") {
-			service.setPublicBaseUrl(void 0);
+			rawTunnelUrl = void 0;
+			setPublicBase();
 			service.setTunnelStatus(info.error === void 0 ? { state: "failed" } : {
 				state: "failed",
 				error: info.error
@@ -3522,6 +3872,7 @@ function applyImpl(ctx, config) {
 		}
 	});
 	ctx.effect(() => () => {
+		disposeRelayRegistrar();
 		tunnel.dispose();
 	}, "remote-web-ui: auto tunnel");
 	if ((ctx.webServer.host === "0.0.0.0" || ctx.webServer.host === "127.0.0.1") && Number.isFinite(ctx.webServer.port)) {
@@ -3762,12 +4113,35 @@ function applyImpl(ctx, config) {
 				else console.error("remote-web-ui: the host firewall rule could not be updated (admin rights required on managed platforms)");
 			}
 		}
-		autoTunnel = value.autoTunnel === true;
-		if (autoTunnel) {
-			if (value.publicBaseUrl !== void 0) console.warn("remote-web-ui: autoTunnel is on — ignoring the manually configured publicBaseUrl");
-			tunnel.start(`http://127.0.0.1:${String(ctx.webServer.port)}`);
-		} else {
+		const plan = tunnelPlanOf(value, ctx.webServer.port);
+		tunnelMode = plan.mode;
+		if (plan.mode !== "quick") {
+			disposeRelayRegistrar();
+			if (plan.mode !== "named") setPublicBase();
+		} else if (value.relay === false) {
+			disposeRelayRegistrar(true);
+			setPublicBase();
+		} else if (rawTunnelUrl !== void 0) {
+			const registrar = ensureRelayRegistrar();
+			if (registrar !== void 0) announceRelay(registrar, rawTunnelUrl);
+		}
+		if (plan.mode === "quick") {
+			for (const ignored of plan.ignored) console.warn(`remote-web-ui: autoTunnel is on — ignoring the configured ${ignored}`);
+			const registrar = ensureRelayRegistrar();
+			const originHostHeader = registrar === void 0 ? void 0 : new URL(registrar.baseUrl).host;
+			tunnel.start(originHostHeader === void 0 ? plan.targetUrl : {
+				kind: "quick",
+				targetUrl: plan.targetUrl,
+				originHostHeader
+			});
+		} else if (plan.mode === "named") tunnel.start({
+			kind: "named",
+			token: plan.token,
+			publicUrl: plan.publicUrl
+		});
+		else {
 			tunnel.stop();
+			if (value.tunnelToken !== void 0 && value.tunnelToken !== "") console.warn("remote-web-ui: tunnelToken is set but publicBaseUrl is missing or not a valid URL — fill the fixed public hostname of the named tunnel (e.g. https://dsh.example.com) to run it");
 			if (value.publicBaseUrl !== void 0 && !isHttpUrl(value.publicBaseUrl)) {
 				console.warn(`remote-web-ui: ignoring malformed publicBaseUrl ${JSON.stringify(value.publicBaseUrl)} (expected https://host[:port])`);
 				service.setPublicBaseUrl(void 0);
@@ -3827,14 +4201,5 @@ function applyImpl(ctx, config) {
 	});
 	sync();
 }
-/** Whether a configured public base is a parseable http(s) URL with a host. */
-function isHttpUrl(value) {
-	try {
-		const url = new URL(value);
-		return (url.protocol === "http:" || url.protocol === "https:") && url.hostname !== "";
-	} catch {
-		return false;
-	}
-}
 //#endregion
 export { Config, REMOTE_WEB_UI_SETTINGS_NAMESPACE, apply, defaultDevicesFile, inject, name, pairingConfigOf };

package/lib/types/client/RemoteEntry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RemoteEntry.d.ts","sourceRoot":"","sources":["../../../src/client/RemoteEntry.tsx"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAA;AAQnE,0EAA0E;AAC1E,MAAM,MAAM,gBAAgB,GAAG,WAAW,CAAC,QAAQ,CAAC,GAAG;IACrD,oEAAoE;IACpE,IAAI,EAAE,OAAO,CAAA;CACd,CAAA;AA0BD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,gBAAgB,+BA2LxD"}
+{"version":3,"file":"RemoteEntry.d.ts","sourceRoot":"","sources":["../../../src/client/RemoteEntry.tsx"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAA;AAQnE,0EAA0E;AAC1E,MAAM,MAAM,gBAAgB,GAAG,WAAW,CAAC,QAAQ,CAAC,GAAG;IACrD,oEAAoE;IACpE,IAAI,EAAE,OAAO,CAAA;CACd,CAAA;AA2BD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,gBAAgB,+BA2LxD"}

package/lib/types/client/RemoteEntry.js

@@ -36,6 +36,7 @@ function mergeFrame(state, frame) {
         onlineCount: frame.onlineCount,
         devices: frame.devices ?? [],
         ...(frame.tunnel !== undefined ? { tunnel: frame.tunnel } : {}),
+        ...(frame.relay !== undefined ? { relay: frame.relay } : {}),
         ...(frame.posture !== undefined ? { posture: frame.posture } : {}),
     };
 }

package/lib/types/client/RemotePanel.d.ts

@@ -1,6 +1,6 @@
 import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
 import type { PairingPhase } from '../pairing.ts';
-import { type DeviceFrame, type PostureFrame, type TunnelStatusFrame } from './pair-api.ts';
+import { type DeviceFrame, type PostureFrame, type RelayStatusFrame, type TunnelStatusFrame } from './pair-api.ts';
 /** The panel's view state, owned by the entry component. */
 export type PanelState = {
     kind: 'lan-required';
@@ -29,6 +29,8 @@ export type PanelState = {
     publicBaseUrl?: string;
     /** Auto-tunnel status, while the auto-tunnel feature is active. */
     tunnel?: TunnelStatusFrame;
+    /** Relay-registry status, while the stable-origin relay is in play. */
+    relay?: RelayStatusFrame;
     /** Latest /api posture probe, once a round has completed. */
     posture?: PostureFrame;
 };

package/lib/types/client/RemotePanel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RemotePanel.d.ts","sourceRoot":"","sources":["../../../src/client/RemotePanel.tsx"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAA;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAA;AAItB,4DAA4D;AAC5D,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,MAAM,CAAC,EAAE,iBAAiB,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IACE,IAAI,EAAE,OAAO,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,YAAY,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,2DAA2D;IAC3D,OAAO,EAAE,WAAW,EAAE,CAAA;IACtB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAA;IACf,yDAAyD;IACzD,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,yEAAyE;IACzE,MAAM,EAAE,OAAO,CAAA;IACf,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mEAAmE;IACnE,MAAM,CAAC,EAAE,iBAAiB,CAAA;IAC1B,6DAA6D;IAC7D,OAAO,CAAC,EAAE,YAAY,CAAA;CACvB,CAAA;AAEL,qDAAqD;AACrD,MAAM,WAAW,gBAAgB;IAC/B,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAA;IACxB,KAAK,EAAE,UAAU,CAAA;IACjB,MAAM,EAAE,OAAO,CAAA;IACf,OAAO,IAAI,IAAI,CAAA;IACf,MAAM,IAAI,IAAI,CAAA;IACd,SAAS,IAAI,IAAI,CAAA;IACjB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,sDAAsD;IACtD,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACpC,oEAAoE;IACpE,YAAY,IAAI,IAAI,CAAA;IACpB,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CACjC;AAgBD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,QAAQ,EAAE,EAAE,gBAAgB,+BA+J5I"}
+{"version":3,"file":"RemotePanel.d.ts","sourceRoot":"","sources":["../../../src/client/RemotePanel.tsx"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAA;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAA;AAItB,4DAA4D;AAC5D,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,MAAM,CAAC,EAAE,iBAAiB,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IACE,IAAI,EAAE,OAAO,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,YAAY,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,2DAA2D;IAC3D,OAAO,EAAE,WAAW,EAAE,CAAA;IACtB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAA;IACf,yDAAyD;IACzD,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,yEAAyE;IACzE,MAAM,EAAE,OAAO,CAAA;IACf,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mEAAmE;IACnE,MAAM,CAAC,EAAE,iBAAiB,CAAA;IAC1B,uEAAuE;IACvE,KAAK,CAAC,EAAE,gBAAgB,CAAA;IACxB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,YAAY,CAAA;CACvB,CAAA;AAEL,qDAAqD;AACrD,MAAM,WAAW,gBAAgB;IAC/B,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAA;IACxB,KAAK,EAAE,UAAU,CAAA;IACjB,MAAM,EAAE,OAAO,CAAA;IACf,OAAO,IAAI,IAAI,CAAA;IACf,MAAM,IAAI,IAAI,CAAA;IACd,SAAS,IAAI,IAAI,CAAA;IACjB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,sDAAsD;IACtD,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACpC,oEAAoE;IACpE,YAAY,IAAI,IAAI,CAAA;IACpB,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CACjC;AAgBD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,QAAQ,EAAE,EAAE,gBAAgB,+BAuK5I"}