dsh-mobile 0.6.6 → 0.6.8

package/lib/index.mjs

@@ -4,7 +4,7 @@ import { basename, dirname, extname, isAbsolute, join, relative, resolve, win32
 import { fileURLToPath, pathToFileURL } from "node:url";
 import z from "@deepseek-ai/schemastery";
 import { connect, createServer } from "node:net";
-import { chmod, copyFile, lstat, mkdir, mkdtemp, open, opendir, readFile, readdir, realpath, rename, rm, rmdir, stat, unlink, writeFile } from "node:fs/promises";
+import { chmod, copyFile, link, lstat, mkdir, mkdtemp, open, opendir, readFile, readdir, realpath, rename, rm, rmdir, stat, unlink, writeFile } from "node:fs/promises";
 import { performance as performance$1 } from "node:perf_hooks";
 import { execFile, spawn } from "node:child_process";
 import { createSocket } from "node:dgram";
@@ -144,10 +144,14 @@ var AccessController = class {
 	}
 	snapshot(devices) {
 		return Object.freeze({
-			version: 1,
+			version: 2,
 			devices: Object.freeze([...devices])
 		});
 	}
+	nativeIdentity(device) {
+		const nativeInstanceId = device.nativeInstanceId ?? this.options.legacyInstanceId ?? this.options.pairingInstanceId;
+		return nativeInstanceId === void 0 ? {} : { nativeInstanceId };
+	}
 	emitSessionEnded(session, reason) {
 		const authorization = Object.freeze({
 			sessionKey: session.key,
@@ -165,7 +169,7 @@ var AccessController = class {
 	pruneSessions(now) {
 		for (const [key, session] of this.sessions) if (session.expiresAt <= now) this.removeSession(key, "expired");
 	}
-	createSession(deviceId, now, deviceExpiresAt) {
+	createSession(device, now) {
 		this.pruneSessions(now);
 		if (this.sessions.size >= this.options.maxSessions) {
 			const oldest = [...this.sessions.values()].sort((left, right) => left.createdAt - right.createdAt)[0];
@@ -176,14 +180,15 @@ var AccessController = class {
 		const key = digestHex(sessionToken);
 		const record = Object.freeze({
 			key,
-			deviceId,
+			deviceId: device.id,
 			csrfDigest: digest$1(csrfToken),
 			createdAt: now,
-			expiresAt: Math.min(now + this.options.sessionTtlMs, deviceExpiresAt)
+			expiresAt: Math.min(now + this.options.sessionTtlMs, device.expiresAt)
 		});
 		this.sessions.set(key, record);
 		return Object.freeze({
-			deviceId,
+			...this.nativeIdentity(device),
+			deviceId: device.id,
 			sessionToken,
 			csrfToken,
 			sessionExpiresAt: record.expiresAt
@@ -228,12 +233,13 @@ var AccessController = class {
 				tokenDigest: digestHex(deviceToken),
 				createdAt: now,
 				expiresAt: now + this.options.deviceTtlMs,
-				lastSeenAt: now
+				lastSeenAt: now,
+				...this.options.pairingInstanceId === void 0 ? {} : { nativeInstanceId: this.options.pairingInstanceId }
 			});
 			const next = [...this.devices.filter((candidate) => candidate.revokedAt === void 0 && candidate.expiresAt > now), device];
 			await this.store.save(this.snapshot(next));
 			this.devices = next;
-			const session = this.createSession(device.id, now, device.expiresAt);
+			const session = this.createSession(device, now);
 			return Object.freeze({
 				...session,
 				deviceToken,
@@ -256,7 +262,7 @@ var AccessController = class {
 			next[index] = updated;
 			await this.store.save(this.snapshot(next));
 			this.devices = next;
-			return this.createSession(device.id, now, device.expiresAt);
+			return this.createSession(device, now);
 		});
 	}
 	/** Validate a persistent device credential without consuming a Session slot. */
@@ -275,6 +281,7 @@ var AccessController = class {
 			await this.store.save(this.snapshot(next));
 			this.devices = next;
 			return Object.freeze({
+				...this.nativeIdentity(device),
 				deviceId: device.id,
 				deviceExpiresAt: device.expiresAt
 			});
@@ -285,6 +292,7 @@ var AccessController = class {
 		this.requireInitialized();
 		const device = this.requireDevice(deviceToken, this.now());
 		return Object.freeze({
+			...this.nativeIdentity(device),
 			deviceId: device.id,
 			deviceExpiresAt: device.expiresAt
 		});
@@ -956,6 +964,8 @@ const Config = z.object({
 		keyFile: z.string(),
 		caFile: z.string()
 	}),
+	cpolarSubdomain: z.string(),
+	cpolarRegion: z.string(),
 	pairingTtlMs: z.natural(),
 	deviceTtlMs: z.natural(),
 	sessionTtlMs: z.natural(),
@@ -1991,6 +2001,13 @@ function attributeValue(tag, name) {
 function commentRanges(html) {
 	return [...html.matchAll(/<!--[\s\S]*?-->/gu)].map((match) => [match.index, match.index + match[0].length]);
 }
+/** Mark an authenticated Gateway document without changing its layout, transport or module selection. */
+function ensureMobileGatewayMarker(html) {
+	const comments = commentRanges(html);
+	const first = [...html.matchAll(/<script\b[^>]*>/giu)].find((match) => !comments.some(([start, end]) => match.index >= start && match.index < end));
+	if (first === void 0) return html;
+	return `${html.slice(0, first.index)}<meta name="dsh-mobile-gateway" content="authenticated">${html.slice(first.index)}`;
+}
 /**
 * Load the compatibility bundle synchronously, before the first DSH script.
 *
@@ -2010,6 +2027,16 @@ function ensureMobileCompatibility(html) {
 	const script = `<script src="${MOBILE_COMPAT_PATH}"${attribute}><\/script>`;
 	return `${html.slice(0, first.index)}${script}${html.slice(first.index)}`;
 }
+/** Maximum sizes enforced when reading local extension files. */
+const EXTENSION_LIMITS = Object.freeze({
+	manifest: 65536,
+	script: 1048576,
+	css: 524288,
+	asset: 8388608,
+	assetFiles: 256,
+	assetBytes: 33554432,
+	assetDepth: 8
+});
 //#endregion
 //#region src/http-cache.ts
 /** Entity-tag handling for authenticated GET and HEAD cache validation. */
@@ -3066,16 +3093,6 @@ var WorkerStreamBridge = class extends Readable {
 };
 //#endregion
 //#region src/extensions.ts
-/** Maximum sizes enforced at the local-extension filesystem boundary. */
-const EXTENSION_LIMITS = Object.freeze({
-	manifest: 65536,
-	script: 1048576,
-	css: 524288,
-	asset: 8388608,
-	assetFiles: 256,
-	assetBytes: 33554432,
-	assetDepth: 8
-});
 /** A misbehaving host activation must not wedge the local watcher forever. */
 const HOST_ACTIVATION_TIMEOUT_MS = 5e3;
 /** The previous Host outlives the hidden-page refresh interval and one timed refresh. */
@@ -4811,7 +4828,7 @@ function rewriteMobileIndexWithBatch(html, options = {}) {
 	const replacement = `${MOBILE_GATEWAY_REACHABILITY_BOOTSTRAP}${remoteSettings ? MOBILE_AUTHENTICATED_TRANSPORT_BOOTSTRAP : ""}${mobileCsrfFetchBootstrap(options.csrfCookie ?? "dsh_ma_csrf")}window.__DSH_MOBILE_FRONTEND__="dedicated";${plan.assignment}${JSON.stringify(plan.parsed)};`;
 	const rewritten = `${html.slice(0, plan.replaceStart)}${replacement}${html.slice(plan.replaceEnd)}`;
 	return Object.freeze({
-		html: ensureMobileViewport(ensureMobileCompatibility(rewriteMobileApplicationPreloads(rewritten, preloadReplacements))),
+		html: ensureMobileGatewayMarker(ensureMobileViewport(ensureMobileCompatibility(rewriteMobileApplicationPreloads(rewritten, preloadReplacements)))),
 		batches
 	});
 }
@@ -5280,6 +5297,8 @@ var MobileAccessGateway = class {
 		this.listenerTlsEnabled = config.tls.mode === "provided";
 		this.tlsEnabled = config.publicTls;
 		this.access = new AccessController(store, {
+			pairingInstanceId: config.instanceId,
+			...config.legacyInstanceId === void 0 ? {} : { legacyInstanceId: config.legacyInstanceId },
 			pairingTtlMs: config.pairingTtlMs,
 			deviceTtlMs: config.deviceTtlMs,
 			sessionTtlMs: config.sessionTtlMs,
@@ -5656,12 +5675,16 @@ var MobileAccessGateway = class {
 			sessionExpiresAt: result.sessionExpiresAt
 		}, this.tlsEnabled);
 	}
+	/** CA-backed entries retain their pin; public entries project the authenticated credential's identity. */
+	nativeResponseInstanceId(result) {
+		return this.config.pairingCaFile === void 0 ? result.nativeInstanceId ?? this.config.instanceId : this.config.instanceId;
+	}
 	async handleNativePair(request, response) {
 		const body = await readJsonObject(request, MAX_CONTROL_BODY_BYTES);
 		if (typeof body.token !== "string" || body.label !== void 0 && typeof body.label !== "string") throw new HttpError(400, "bad_request");
 		const result = await this.access.pair(request.socket.remoteAddress ?? "unknown", body.token, body.label);
 		sendJson(response, 201, {
-			instanceId: this.config.instanceId,
+			instanceId: this.nativeResponseInstanceId(result),
 			deviceId: result.deviceId,
 			deviceToken: result.deviceToken,
 			deviceExpiresAt: result.deviceExpiresAt,
@@ -5676,7 +5699,7 @@ var MobileAccessGateway = class {
 		if (typeof body.deviceToken !== "string") throw new HttpError(400, "bad_request");
 		const result = await this.access.renew(body.deviceToken);
 		sendJson(response, 200, {
-			instanceId: this.config.instanceId,
+			instanceId: this.nativeResponseInstanceId(result),
 			deviceId: result.deviceId,
 			sessionToken: result.sessionToken,
 			csrfToken: result.csrfToken,
@@ -5689,7 +5712,7 @@ var MobileAccessGateway = class {
 		if (typeof body.deviceToken !== "string") throw new HttpError(400, "bad_request");
 		const result = await this.access.probe(body.deviceToken);
 		sendJson(response, 200, {
-			instanceId: this.config.instanceId,
+			instanceId: this.nativeResponseInstanceId(result),
 			deviceId: result.deviceId,
 			deviceExpiresAt: result.deviceExpiresAt
 		}, this.tlsEnabled);
@@ -5986,8 +6009,9 @@ var MobileAccessGateway = class {
 		const stockFrontend = new URL(target.raw, this.address().origin).searchParams.get("frontend") === "stock";
 		const acceptsHtml = request.headers.accept?.split(",").some((value) => value.trim().split(";", 1)[0] === "text/html") ?? false;
 		const frontendDocument = target.decodedPathname === "/" || target.decodedPathname === "/index.html";
-		if (request.method === "GET" && frontendDocument && acceptsHtml && !stockFrontend) {
-			await this.proxyMobileIndex(request, response, authorization);
+		if (request.method === "GET" && frontendDocument && acceptsHtml) {
+			if (stockFrontend && target.decodedPathname === "/") request.url = "/";
+			await this.proxyMobileIndex(request, response, authorization, stockFrontend);
 			return;
 		}
 		if (stockFrontend && target.decodedPathname === "/") request.url = "/";
@@ -6378,6 +6402,8 @@ var MobileAccessGateway = class {
 			signal.throwIfAborted();
 			if (upstreamCookie !== void 0) headers.cookie = upstreamCookie;
 			headers["accept-encoding"] = "identity";
+			delete headers["if-none-match"];
+			delete headers["if-modified-since"];
 			const proxied = await new Promise((resolve, reject) => {
 				upstreamRequest = request({
 					protocol: "http:",
@@ -6417,7 +6443,7 @@ var MobileAccessGateway = class {
 			upstreamRequest?.destroy();
 		}
 	}
-	async proxyMobileIndex(request, response, authorization) {
+	async proxyMobileIndex(request, response, authorization, stockFrontend = false) {
 		const holder = {};
 		const operation = this.allocateRequest(authorization, response, holder);
 		const onClose = () => {
@@ -6427,50 +6453,53 @@ var MobileAccessGateway = class {
 		response.once("close", onClose);
 		try {
 			const index = await this.fetchAuthenticatedUpstreamIndex(operation.signal, request);
-			const preference = await this.clientModulePreferences.read(authorization.deviceId);
-			const excludedClientModules = preference.excludedClientModules;
 			let body;
-			try {
-				const html = index.html;
-				const plan = parseMobileBootPlan(html, excludedClientModules);
-				const options = plan.rewrittenBatchEntries === void 0 ? { excludedClientModules } : {
-					...await this.resolveMobileBootSizes(plan.rewrittenBatchEntries.flatMap((batch) => batch.entries), operation.signal),
-					excludedClientModules
-				};
-				const cookies = browserAuthCookies(request.headers.cookie);
-				const csrfCookie = this.tlsEnabled && cookies.has("__Host-dsh_ma_session") ? HOST_CSRF_COOKIE : CSRF_COOKIE;
-				const rewritten = rewriteMobileIndexWithBatch(html, {
-					...options,
-					csrfCookie
-				});
-				for (const batch of rewritten.batches) this.rememberMobileBootBatch(batch);
-				body = Buffer.from(rewritten.html);
-			} catch (error) {
-				if (error instanceof ExcludedClientModulesError) {
-					const detail = error.message.replace(/[\r\n]/gu, " ").slice(0, 512);
-					if (detail !== this.lastModuleExclusionError) {
-						this.lastModuleExclusionError = detail;
-						process.emitWarning(detail, { code: "DSH_MOBILE_MODULE_EXCLUSION_INVALID" });
-					}
-					if (preference.source === "device" || preference.source === "computer") {
-						operation.signal.throwIfAborted();
-						const locale = resolveAuthPageLocale(headerValue(request.headers, "accept-language"));
-						const recovery = Buffer.from(renderClientModuleRecoveryPage(locale));
-						setSecurityHeaders(response, this.tlsEnabled);
-						response.writeHead(200, {
-							"Content-Type": "text/html; charset=utf-8",
-							"Content-Length": recovery.byteLength
-						});
-						response.end(recovery);
+			if (stockFrontend) body = Buffer.from(ensureMobileGatewayMarker(index.html));
+			else {
+				const preference = await this.clientModulePreferences.read(authorization.deviceId);
+				const excludedClientModules = preference.excludedClientModules;
+				try {
+					const html = index.html;
+					const plan = parseMobileBootPlan(html, excludedClientModules);
+					const options = plan.rewrittenBatchEntries === void 0 ? { excludedClientModules } : {
+						...await this.resolveMobileBootSizes(plan.rewrittenBatchEntries.flatMap((batch) => batch.entries), operation.signal),
+						excludedClientModules
+					};
+					const cookies = browserAuthCookies(request.headers.cookie);
+					const csrfCookie = this.tlsEnabled && cookies.has("__Host-dsh_ma_session") ? HOST_CSRF_COOKIE : CSRF_COOKIE;
+					const rewritten = rewriteMobileIndexWithBatch(html, {
+						...options,
+						csrfCookie
+					});
+					for (const batch of rewritten.batches) this.rememberMobileBootBatch(batch);
+					body = Buffer.from(rewritten.html);
+				} catch (error) {
+					if (error instanceof ExcludedClientModulesError) {
+						const detail = error.message.replace(/[\r\n]/gu, " ").slice(0, 512);
+						if (detail !== this.lastModuleExclusionError) {
+							this.lastModuleExclusionError = detail;
+							process.emitWarning(detail, { code: "DSH_MOBILE_MODULE_EXCLUSION_INVALID" });
+						}
+						if (preference.source === "device" || preference.source === "computer") {
+							operation.signal.throwIfAborted();
+							const locale = resolveAuthPageLocale(headerValue(request.headers, "accept-language"));
+							const recovery = Buffer.from(renderClientModuleRecoveryPage(locale));
+							setSecurityHeaders(response, this.tlsEnabled);
+							response.writeHead(200, {
+								"Content-Type": "text/html; charset=utf-8",
+								"Content-Length": recovery.byteLength
+							});
+							response.end(recovery);
+							return;
+						}
+						sendJson(response, 409, {
+							error: "excluded_client_modules_invalid",
+							detail
+						}, this.tlsEnabled);
 						return;
 					}
-					sendJson(response, 409, {
-						error: "excluded_client_modules_invalid",
-						detail
-					}, this.tlsEnabled);
-					return;
+					throw new HttpError(502, "upstream_unavailable");
 				}
-				throw new HttpError(502, "upstream_unavailable");
 			}
 			operation.signal.throwIfAborted();
 			const headers = sanitizeResponseHeaders(index.headers, this.config.upstreamOrigin);
@@ -7352,6 +7381,7 @@ function parseDevice(value) {
 	if (typeof record.id !== "string" || !/^[a-f\d]{32}$/u.test(record.id)) throw new Error("device state contains an invalid id");
 	if (typeof record.label !== "string" || record.label.length < 1 || record.label.length > 64 || /[\u0000-\u001f\u007f]/u.test(record.label)) throw new Error("device state contains an invalid label");
 	if (typeof record.tokenDigest !== "string" || !/^[a-f\d]{64}$/u.test(record.tokenDigest)) throw new Error("device state contains an invalid credential digest");
+	if (record.nativeInstanceId !== void 0 && (typeof record.nativeInstanceId !== "string" || !/^[a-f\d]{64}$/u.test(record.nativeInstanceId))) throw new Error("device state contains an invalid native instance id");
 	assertInteger(record.createdAt, "createdAt");
 	assertInteger(record.expiresAt, "expiresAt");
 	assertInteger(record.lastSeenAt, "lastSeenAt");
@@ -7364,6 +7394,7 @@ function parseDevice(value) {
 		createdAt: record.createdAt,
 		expiresAt: record.expiresAt,
 		lastSeenAt: record.lastSeenAt,
+		...record.nativeInstanceId === void 0 ? {} : { nativeInstanceId: record.nativeInstanceId },
 		...record.revokedAt === void 0 ? {} : { revokedAt: record.revokedAt }
 	});
 }
@@ -7371,14 +7402,21 @@ function parseDevice(value) {
 function parseDeviceSnapshot(value, maximumDevices = 256) {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("device state must be an object");
 	const snapshot = value;
-	if (snapshot.version !== 1 || !Array.isArray(snapshot.devices) || snapshot.devices.length > maximumDevices) throw new Error("device state has an unsupported version or device count");
+	if (snapshot.version !== 1 && snapshot.version !== 2 || !Array.isArray(snapshot.devices) || snapshot.devices.length > maximumDevices) throw new Error("device state has an unsupported version or device count");
 	const devices = snapshot.devices.map(parseDevice);
 	if (new Set(devices.map((device) => device.id)).size !== devices.length || new Set(devices.map((device) => device.tokenDigest)).size !== devices.length) throw new Error("device state contains duplicate device identities");
 	return Object.freeze({
-		version: 1,
+		version: snapshot.version,
 		devices: Object.freeze(devices)
 	});
 }
+function snapshotForSave(snapshot, maximumDevices) {
+	const validated = parseDeviceSnapshot(snapshot, maximumDevices);
+	return Object.freeze({
+		version: 2,
+		devices: validated.devices
+	});
+}
 /** Atomic JSON implementation with symlink refusal and owner-only file creation. */
 var JsonDeviceStore = class {
 	file;
@@ -7409,7 +7447,7 @@ var JsonDeviceStore = class {
 		return parseDeviceSnapshot(parsed, this.maximumDevices);
 	}
 	async save(snapshot) {
-		const validated = parseDeviceSnapshot(snapshot, this.maximumDevices);
+		const validated = snapshotForSave(snapshot, this.maximumDevices);
 		const directory = dirname(this.file);
 		await mkdir(directory, {
 			recursive: true,
@@ -7453,7 +7491,7 @@ var MemoryDeviceStore = class {
 		return structuredClone(this.snapshot);
 	}
 	async save(snapshot) {
-		this.snapshot = structuredClone(parseDeviceSnapshot(snapshot));
+		this.snapshot = structuredClone(snapshotForSave(snapshot));
 	}
 	/** Return a defensive copy for assertions or administrative export. */
 	inspect() {
@@ -13281,11 +13319,11 @@ async function collectConnectionDiagnostics(snapshot, probes = {}) {
 //#region src/mobile-guide.ts
 /** Compose the guide with the current customization state injected. */
 function buildMobileGuide(state) {
-	const styleLine = state.hasCustomCss ? "存在（当前生效的自定义样式）" : "不存在（使用内置默认样式）";
-	const scriptLine = state.hasCustomJs ? "存在（当前生效的自定义脚本）" : "不存在（无自定义脚本）";
+	const styleLine = state.hasCustomCss ? "存在（已检测到文件，需在已配对页面验证加载）" : "不存在（使用内置默认样式）";
+	const scriptLine = state.hasCustomJs ? "存在（已检测到文件，需在已配对页面验证加载）" : "不存在（无自定义脚本）";
 	const extensionLines = state.extensions.length === 0 ? "（无）" : state.extensions.map((entry) => `- ${entry.id}（${entry.name} v${entry.version}）${entry.executionMode === void 0 ? "" : ` · ${entry.executionMode}${entry.executionState === "unavailable" ? " · 当前不可用，需要显式重启扩展" : ""}`}`).join("\n");
 	const failureLine = state.failedExtensionCount > 0 ? `注意：${state.failedExtensionCount} 个扩展的电脑端 host 激活失败，如改动相关扩展请先检查其 host.mjs 与 extension.json。` : "";
-	return `${`## 手机端当前状态（改动前必读，避免覆盖已有定制）
+	return `${`## 本机定制文件与扩展状态（改动前必读，避免覆盖已有定制）
 
 - 定制目录：${state.directory}（所有改动只允许在这里进行）
 - mobile.css：${styleLine}
@@ -13309,7 +13347,9 @@ const MOBILE_CUSTOMIZATION_GUIDE_BODY = `你在为用户定制 DSH Mobile 的手
 1. 界面与交互 —— 只改外观和交互，不需要碰电脑的文件或程序：
    - $DSH_HOME/mobile-access/mobile.css：手机端样式
    - $DSH_HOME/mobile-access/mobile.js：手机端脚本，用 window.dshMobile.register(({ root }) => { ... }) 把内容挂载到 root，返回清理函数
-   - 保存后手机端几秒内自动应用，无需重启
+   - 保存后已配对的 DSH Mobile 页面会自动检查并应用，无需重启；文件存在不表示某个页面已成功加载
+
+定制资源通过 DSH Mobile Gateway 的移动配对会话认证。普通 DSH 网页的登录凭据不等于移动配对凭据；直接打开普通 DSH 地址或仅用手机视口预览，不能据此验证 mobile.css / mobile.js。若扩展 manifest 返回 401，页面不会继续加载定制样式与脚本；先确认是通过“移动访问”配对入口进入，并检查实际请求与页面中的定制样式，不要盲改 CSS 或放松认证。核对 Cookie 时只确认是否存在，不读取或公开其值。
 
 动手前先读已有的定制文件。若要调整 DSH 自带的输入框、侧栏或设置等现有界面，先确认当前 DSH 版本与手机页面模式（专用移动页面或 ?frontend=stock），只读核对运行页面的 DOM、属性和样式；本机有同版本前端源码时可参考相应组件，没有源码时可查看已安装的客户端产物，不必下载源码。优先使用扩展 API、插槽和稳定的 data-* 标记，不凭猜测依赖构建类名。只读查看不改变前述写入范围。
 
@@ -14824,6 +14864,7 @@ const CPOLAR_HOST_SUFFIXES = Object.freeze([
 	".cpolar.top",
 	".cpolar.com"
 ]);
+const CPOLAR_SUBDOMAIN_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$/u;
 function publicStatus(status) {
 	return Object.freeze({
 		enabled: status.enabled,
@@ -14918,7 +14959,16 @@ var CpolarController = class {
 	constructor(options) {
 		this.options = options;
 		if (!isAbsolute(options.executable) || !isAbsolute(options.configFile)) throw new Error("cpolar paths must be absolute");
-		if (options.region !== void 0 && !/^[a-z][a-z0-9_]{0,31}$/u.test(options.region)) throw new Error("cpolar region is invalid");
+		const { subdomain: rawSubdomain, region: rawRegion, ...resources } = options;
+		const subdomain = rawSubdomain?.trim() || void 0;
+		const region = rawRegion?.trim() || void 0;
+		if (region !== void 0 && !/^[a-z][a-z0-9_]{0,31}$/u.test(region)) throw new Error("cpolar region is invalid");
+		if (subdomain !== void 0 && !CPOLAR_SUBDOMAIN_PATTERN.test(subdomain)) throw new Error("cpolar subdomain is invalid");
+		this.options = {
+			...resources,
+			...subdomain === void 0 ? {} : { subdomain },
+			...region === void 0 ? {} : { region }
+		};
 	}
 	/** Restore the remembered cpolar switch independently from LAN and Funnel state. */
 	async initialize(initialState) {
@@ -15068,6 +15118,7 @@ var CpolarController = class {
 		const args = [
 			"http",
 			`-config=${resolve(this.options.configFile)}`,
+			...this.options.subdomain === void 0 ? [] : [`-subdomain=${this.options.subdomain}`],
 			...this.options.region === void 0 ? [] : [`-region=${this.options.region}`],
 			"-inspect-addr=false",
 			"-redirect-https=true",
@@ -16663,23 +16714,75 @@ async function readInstallationId(file) {
 	await restrictPrivateFile(file);
 	return contents.slice(0, -1);
 }
-/** Keep one random plugin identity across setup changes, restarts, and FRP resets. */
+/** Keep one random plugin identity across setup changes, restarts, and FRP resets; creation requires hard-link support in the state directory. */
 async function loadOrCreateInstallationId(file) {
 	if (!isAbsolute(file)) throw new Error("installation ID path must be absolute");
 	const target = resolve(file);
-	await mkdir(dirname(target), {
-		recursive: true,
-		mode: 448
-	});
+	const directory = dirname(target);
+	await ensureManagedDirectory(directory, directory, "installation_id");
 	try {
-		await writeFile(target, `${randomBytes(32).toString("hex")}\n`, {
-			flag: "wx",
-			mode: 384
-		});
+		return await readInstallationId(target);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+	const temporary = join(directory, `.${basename(target)}.${randomBytes(12).toString("hex")}.tmp`);
+	let created = false;
+	let failure;
+	try {
+		await assertManagedParents(directory, temporary, "installation_id");
+		const handle = await open(temporary, "wx", 384);
+		created = true;
+		let writeFailure;
+		try {
+			await handle.writeFile(`${randomBytes(32).toString("hex")}\n`, "utf8");
+		} catch (error) {
+			writeFailure = error;
+			throw error;
+		} finally {
+			try {
+				await handle.close();
+			} catch (closeError) {
+				if (writeFailure !== void 0) throw new AggregateError([writeFailure, closeError], "installation ID candidate write and close failed");
+				throw closeError;
+			}
+		}
+		await restrictPrivateFile(temporary);
+		await assertManagedParents(directory, target, "installation_id");
+		try {
+			await link(temporary, target);
+		} catch (error) {
+			if (error.code !== "EEXIST") throw new Error("installation ID publication failed; the state filesystem must support hard links", { cause: error });
+		}
+		return await readInstallationId(target);
 	} catch (error) {
-		if (error.code !== "EEXIST") throw error;
+		failure = error;
+		throw error;
+	} finally {
+		if (created) try {
+			await assertManagedParents(directory, temporary, "installation_id");
+			await unlink(temporary);
+		} catch (cleanupError) {
+			if (failure !== void 0) throw new AggregateError([failure, cleanupError], "installation ID publication and temporary cleanup failed");
+			throw cleanupError;
+		}
 	}
-	return readInstallationId(target);
+}
+//#endregion
+//#region src/gateway-identity.ts
+/**
+* Use the persisted installation identity for an unpinned, automatically identified entry.
+* @param config - Validated gateway configuration containing the legacy identity.
+* @param installationId - Confirmed random identity read from this installation's state.
+* @param explicitIdentity - Whether the operator supplied the gateway identity.
+* @returns Configuration retaining certificate/operator identities or the new and legacy public identities.
+*/
+function withInstallationIdentity(config, installationId, explicitIdentity) {
+	if (config.pairingCaFile !== void 0 || explicitIdentity) return config;
+	return Object.freeze({
+		...config,
+		instanceId: installationId,
+		legacyInstanceId: config.instanceId
+	});
 }
 //#endregion
 //#region src/lan-setup.ts
@@ -16927,7 +17030,7 @@ async function stableInstanceId(loaded, template) {
 	if (loaded.kind !== "managed") return loaded.config.instanceId ?? template.instanceId;
 	return new X509Certificate(await readFile(loaded.setup.tls.caCertFile)).fingerprint256.replaceAll(":", "").toLowerCase();
 }
-function remoteGatewayConfig(template, publicOrigin, stateFile, instanceId, listenPort = 0) {
+function remoteGatewayConfig(template, publicOrigin, stateFile, instanceId, listenPort = 0, legacyInstanceId) {
 	const origin = new URL(publicOrigin);
 	if (origin.protocol !== "https:" || origin.username !== "" || origin.password !== "" || origin.pathname !== "/" || origin.search !== "" || origin.hash !== "") throw new Error("remote public origin must be an HTTPS origin");
 	const publicAuthority = origin.port === "" ? `${origin.hostname}:443` : origin.host;
@@ -16940,6 +17043,7 @@ function remoteGatewayConfig(template, publicOrigin, stateFile, instanceId, list
 		allowedCidrs: Object.freeze([parseCidr("127.0.0.0/8")]),
 		stateFile,
 		instanceId,
+		...legacyInstanceId === void 0 ? {} : { legacyInstanceId },
 		tls: Object.freeze({ mode: "disabled" }),
 		publicTls: true,
 		discovery: false
@@ -17000,11 +17104,11 @@ async function readFrpIngressTrustAnchor(settings, stateFile, ownedRoot = dirnam
 	}
 }
 /** Reuse remote HTTPS policy while binding a separately validated private HTTP origin. */
-function originGatewayConfig(template, settings, stateFile, instanceId, listenPort = settings.listenPort) {
+function originGatewayConfig(template, settings, stateFile, instanceId, listenPort = settings.listenPort, legacyInstanceId) {
 	const validated = parseOriginSettings(settings);
 	if (listenPort !== 0) validateOriginListenPort(listenPort);
 	return Object.freeze({
-		...remoteGatewayConfig(template, validated.publicOrigin, stateFile, instanceId, listenPort),
+		...remoteGatewayConfig(template, validated.publicOrigin, stateFile, instanceId, listenPort, legacyInstanceId),
 		listenHost: validated.listenHost,
 		allowedCidrs: Object.freeze(validated.allowedCidrs.map(parseCidr))
 	});
@@ -17087,6 +17191,7 @@ async function apply(ctx, config) {
 	const frpComponent = new FrpComponentManager({ stateDirectory });
 	await frpComponent.initialize();
 	const frpIdentity = await loadOrCreateInstallationId(join(stateDirectory, "installation-id"));
+	const remoteInstanceId = loaded.kind === "managed" ? frpIdentity : loaded.config.instanceId ?? frpIdentity;
 	const frpConfig = new FrpConfigStore(join(remoteDirectory, "frp", "config"), frpProxyName(frpIdentity), stateDirectory);
 	await frpConfig.initialize();
 	const originConfig = new OriginConfigStore(join(remoteDirectory, "origin", "config"), stateDirectory);
@@ -17138,10 +17243,10 @@ async function apply(ctx, config) {
 	let trustedNetworksWrite = Promise.resolve();
 	let adminClosing = false;
 	const startGateway = async (candidateConfig) => {
-		const resolved = parseGatewayConfig({
+		const resolved = withInstallationIdentity(parseGatewayConfig({
 			...candidateConfig,
 			upstreamOrigin: template.upstreamOrigin.origin
-		});
+		}), frpIdentity, candidateConfig.instanceId !== void 0);
 		const candidate = new MobileAccessGateway(resolved, new JsonDeviceStore(resolved.stateFile, resolved.maxDevices), mobileAccess, upstreamLoginUrl, webSocketPaths, blockedUpgradePaths, (source, code) => {
 			logger.warn("%s discovery degraded while DSH remains available: %s", source, code);
 		}, clientModulePreferences);
@@ -17199,7 +17304,7 @@ async function apply(ctx, config) {
 		}
 	}
 	const createRemoteGateway = async (publicOrigin, listenPort = 0) => {
-		const resolved = remoteGatewayConfig(template, publicOrigin, remoteDeviceFile, instanceId, listenPort);
+		const resolved = remoteGatewayConfig(template, publicOrigin, remoteDeviceFile, remoteInstanceId, listenPort, instanceId);
 		const candidate = new MobileAccessGateway(resolved, new JsonDeviceStore(resolved.stateFile, resolved.maxDevices), mobileAccess, upstreamLoginUrl, webSocketPaths, blockedUpgradePaths, void 0, clientModulePreferences);
 		await candidate.start();
 		return candidate;
@@ -17226,7 +17331,7 @@ async function apply(ctx, config) {
 		return candidate;
 	};
 	const createOriginGateway = async (settings) => {
-		const resolved = originGatewayConfig(template, settings, remoteDeviceFile, instanceId);
+		const resolved = originGatewayConfig(template, settings, remoteDeviceFile, remoteInstanceId, settings.listenPort, instanceId);
 		const candidate = new MobileAccessGateway(resolved, new JsonDeviceStore(resolved.stateFile, resolved.maxDevices), mobileAccess, upstreamLoginUrl, webSocketPaths, blockedUpgradePaths, void 0, clientModulePreferences);
 		try {
 			await candidate.start();
@@ -17245,7 +17350,7 @@ async function apply(ctx, config) {
 		store: createVolatileRemoteControlStore(),
 		component: caddyComponent,
 		config: caddyConfig,
-		instanceId,
+		instanceId: remoteInstanceId,
 		createGateway: (settings) => createRemoteGateway(settings.publicOrigin)
 	});
 	const originController = new ManagedOriginController({
@@ -17271,6 +17376,8 @@ async function apply(ctx, config) {
 			store: cpolarStore,
 			executable: cpolarComponent.executable,
 			configFile: cpolarComponent.configFile,
+			...config.cpolarSubdomain === void 0 ? {} : { subdomain: config.cpolarSubdomain },
+			...config.cpolarRegion === void 0 ? {} : { region: config.cpolarRegion },
 			createGateway: createRemoteGateway
 		}),
 		cloudflared: new CloudflaredController({
@@ -17283,7 +17390,7 @@ async function apply(ctx, config) {
 			store: frpStore,
 			executable: frpComponent.executable,
 			config: frpConfig,
-			instanceId,
+			instanceId: remoteInstanceId,
 			createGateway: createFrpGateway,
 			/**
 			* Hand the start-up self-check the CA the app itself pins.