dsh-mobile 0.8.3 → 0.8.5

package/lib/index.mjs

@@ -4,7 +4,7 @@ import { basename, dirname, extname, isAbsolute, join, posix, relative, resolve,
 import { fileURLToPath, pathToFileURL } from "node:url";
 import z from "@deepseek-ai/schemastery";
 import { connect, createServer, isIP } from "node:net";
-import { chmod, copyFile, link, lstat, mkdir, mkdtemp, open, opendir, readFile, readdir, realpath, rename, rm, rmdir, stat, unlink, writeFile } from "node:fs/promises";
+import { access, 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";
@@ -25,7 +25,7 @@ import { connect as connect$1 } from "node:tls";
 import { generate } from "selfsigned";
 import { boundContextSummary, createUserMessage } from "@deepseek-ai/dsh-llm/message";
 import { lookup } from "node:dns/promises";
-import { constants } from "node:fs";
+import { constants, readFileSync } from "node:fs";
 import { z as z$1 } from "zod";
 import webPush from "web-push";
 // src/access.ts
@@ -1036,10 +1036,17 @@ const Config = z.object({
 	maxBodyBytes: z.natural(),
 	upstreamTimeoutMs: z.natural(),
 	upstreamApiTimeoutMs: z.natural(),
+	catalogCache: z.boolean(),
 	rateLimitWindowMs: z.natural(),
 	maxPairingAttempts: z.natural(),
 	maxRateLimitKeys: z.natural()
 });
+/** Resolve one optional boolean with an explicit default; reject other types. */
+function booleanValue(value, name, fallback) {
+	if (value === void 0) return fallback;
+	if (typeof value !== "boolean") throw new Error(`${name} must be a boolean`);
+	return value;
+}
 function integer(value, name, fallback, minimum, maximum) {
 	const resolved = value ?? fallback;
 	if (typeof resolved !== "number" || !Number.isSafeInteger(resolved) || resolved < minimum || resolved > maximum) throw new Error(`${name} must be an integer from ${String(minimum)} through ${String(maximum)}`);
@@ -1196,6 +1203,7 @@ function parseGatewayConfig(raw) {
 		maxBodyBytes: integer(value.maxBodyBytes, "maxBodyBytes", 167772160, 1024, 268435456),
 		upstreamTimeoutMs: integer(value.upstreamTimeoutMs, "upstreamTimeoutMs", 3e4, 1e3, 3e5),
 		upstreamApiTimeoutMs: integer(value.upstreamApiTimeoutMs, "upstreamApiTimeoutMs", 0, 0, 2147483647),
+		catalogCache: booleanValue(value.catalogCache, "catalogCache", true),
 		rateLimitWindowMs: integer(value.rateLimitWindowMs, "rateLimitWindowMs", 6e4, 1e3, 36e5),
 		maxPairingAttempts: integer(value.maxPairingAttempts, "maxPairingAttempts", 8, 1, 100),
 		maxRateLimitKeys: integer(value.maxRateLimitKeys, "maxRateLimitKeys", 256, 1, 4096)
@@ -2469,6 +2477,305 @@ var ApiLatencyRecorder = class {
 		}
 	}
 };
+// src/catalog-cache.ts
+/** Host RPCs whose successful completion can change catalog results. */
+const CATALOG_MUTATION_METHODS = /* @__PURE__ */ new Set([
+	"account/signOut",
+	"account/startSignIn",
+	"credentials/set",
+	"credentials/unset",
+	"pluginManager/installBundle",
+	"pluginManager/removeBundle",
+	"pluginManager/setBundleEnabled",
+	"pluginManager/setPluginEnabled",
+	"pluginManager/setVersionExemption",
+	"pluginManager/updateBundle",
+	"session/initializeDefaultModel",
+	"session/selectModel",
+	"settings/mutate",
+	"settings/replace",
+	"settings/update"
+]);
+const CATALOG_CACHE_METHODS = /* @__PURE__ */ new Set(["llm/listProviders", "session/modelCatalog"]);
+const DEFAULT_CATALOG_CACHE_LIMITS = Object.freeze({
+	freshMs: 5e3,
+	staleMs: 6e4,
+	maxEntries: 4,
+	maxEntryBytes: 2097152,
+	maxTotalBytes: 8388608,
+	maxInFlightFills: 2
+});
+const REQUEST_KEYS = /* @__PURE__ */ new Set([
+	"type",
+	"rpcId",
+	"method",
+	"payload"
+]);
+const RESPONSE_KEYS = /* @__PURE__ */ new Set([
+	"type",
+	"rpcId",
+	"result"
+]);
+const encoder = new TextEncoder();
+const isObject$1 = (value) => typeof value === "object" && value !== null;
+const hasExactKeys = (value, keys) => {
+	const present = Object.keys(value);
+	if (present.length !== keys.size) return false;
+	for (const key of present) if (!keys.has(key)) return false;
+	return true;
+};
+/**
+* Validate one catalog request against the captured wire contract.
+* @param routeMethod - The `/api/<method>` route segment.
+* @param bodyJson - The exact buffered request body.
+* @returns The eligible method and its live rpcId, or undefined for anything else.
+*/
+function checkCatalogRequest(routeMethod, bodyJson) {
+	if (!CATALOG_CACHE_METHODS.has(routeMethod)) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(bodyJson);
+	} catch {
+		return;
+	}
+	if (!isObject$1(parsed) || !hasExactKeys(parsed, REQUEST_KEYS)) return void 0;
+	if (parsed.type !== "client-request") return void 0;
+	if (parsed.method !== routeMethod) return void 0;
+	if (typeof parsed.rpcId !== "string" || parsed.rpcId.length === 0 || parsed.rpcId.length > 512) return void 0;
+	const payload = parsed.payload;
+	if (!isObject$1(payload) || !hasExactKeys(payload, /* @__PURE__ */ new Set(["args"]))) return void 0;
+	const args = payload.args;
+	if (!isObject$1(args) || Array.isArray(args) || Object.keys(args).length !== 0) return void 0;
+	return {
+		method: routeMethod,
+		rpcId: parsed.rpcId
+	};
+}
+/**
+* Validate a fill response against the captured success schema.
+* @param envelopeJson - The buffered upstream response body.
+* @param expectedRpcId - The gateway-generated rpcId the fill sent.
+* @returns Whether the envelope is the shareable success variant for that id.
+*/
+function validateCatalogEnvelope(envelopeJson, expectedRpcId) {
+	let parsed;
+	try {
+		parsed = JSON.parse(envelopeJson);
+	} catch {
+		return false;
+	}
+	if (!isObject$1(parsed) || !hasExactKeys(parsed, RESPONSE_KEYS)) return false;
+	if (parsed.type !== "server-response") return false;
+	if (parsed.rpcId !== expectedRpcId) return false;
+	const result = parsed.result;
+	if (!isObject$1(result)) return false;
+	return result.ok === true && "value" in result;
+}
+/**
+* Re-stamp a validated envelope for one caller.
+* @param envelopeJson - The cached upstream envelope.
+* @param expectedRpcId - The fill rpcId the envelope must carry.
+* @param liveRpcId - The caller's rpcId to serialize into the response.
+* @returns The per-caller JSON body, or undefined when validation fails.
+*/
+function restampEnvelope(envelopeJson, expectedRpcId, liveRpcId) {
+	let parsed;
+	try {
+		parsed = JSON.parse(envelopeJson);
+	} catch {
+		return;
+	}
+	if (!validateCatalogEnvelope(envelopeJson, expectedRpcId)) return void 0;
+	const body = parsed;
+	body.rpcId = liveRpcId;
+	return JSON.stringify(body);
+}
+/**
+* Generation-aware SWR cache over the injected fill transport.
+* @typeParam TUpstreamSnapshot - Opaque immutable upstream identity snapshot the gateway captures per request.
+*/
+var CatalogCache = class {
+	#limits;
+	#clock;
+	#fetchFill;
+	#entries = /* @__PURE__ */ new Map();
+	#flights = /* @__PURE__ */ new Map();
+	#identityDigest;
+	#epoch = 0;
+	#disposed = false;
+	constructor(deps) {
+		this.#fetchFill = deps.fetchFill;
+		this.#clock = deps.clock;
+		this.#limits = {
+			...DEFAULT_CATALOG_CACHE_LIMITS,
+			...deps.limits
+		};
+	}
+	get entryCount() {
+		return this.#entries.size;
+	}
+	get residentBytes() {
+		let total = 0;
+		for (const entry of this.#entries.values()) total += entry.bytes;
+		return total;
+	}
+	get inFlightFills() {
+		let active = 0;
+		for (const flight of this.#flights.values()) if (!flight.settled) active += 1;
+		return active;
+	}
+	/**
+	* Serve one eligible request from the current generation.
+	* @param input - Method, caller rpcId, current identity digest and its snapshot.
+	* @returns A per-caller replay, or passthrough when the ordinary path must run.
+	*/
+	async serve(input) {
+		if (this.#disposed) return { kind: "passthrough" };
+		if (!CATALOG_CACHE_METHODS.has(input.method)) return { kind: "passthrough" };
+		const method = input.method;
+		this.#syncIdentity(input.identityDigest);
+		const generation = this.#currentGeneration();
+		const key = `${input.identityDigest}\u0000${method}`;
+		const entry = this.#entries.get(key);
+		if (entry !== void 0) {
+			const age = this.#clock() - entry.completedAt;
+			if (age < this.#limits.freshMs) {
+				entry.lastServedAt = this.#clock();
+				const body = restampEnvelope(entry.envelopeJson, entry.upstreamRpcId, input.rpcId);
+				if (body !== void 0) return {
+					kind: "hit",
+					body,
+					generation,
+					validUntil: entry.validUntil
+				};
+			} else if (age < this.#limits.staleMs) {
+				entry.lastServedAt = this.#clock();
+				const body = restampEnvelope(entry.envelopeJson, entry.upstreamRpcId, input.rpcId);
+				if (body !== void 0) {
+					this.#startBackgroundFill(method, input.identityDigest, input.upstream);
+					return {
+						kind: "stale",
+						body,
+						generation,
+						validUntil: entry.validUntil
+					};
+				}
+			}
+		}
+		const flightKey = `${input.identityDigest}|${generation.epoch}|${method}`;
+		const existing = this.#flights.get(flightKey);
+		if (existing === void 0 && this.inFlightFills >= this.#limits.maxInFlightFills) return { kind: "passthrough" };
+		const outcome = await (existing ?? this.#createFlight(method, generation, input.upstream)).promise;
+		if (!outcome.shareable) return { kind: "passthrough" };
+		if (!this.#isCurrent(generation)) return { kind: "passthrough" };
+		if (!validateCatalogEnvelope(outcome.envelopeJson, outcome.upstreamRpcId)) return { kind: "passthrough" };
+		const body = restampEnvelope(outcome.envelopeJson, outcome.upstreamRpcId, input.rpcId);
+		if (body === void 0) return { kind: "passthrough" };
+		return {
+			kind: "replay",
+			body,
+			generation,
+			validUntil: this.#clock() + this.#limits.staleMs
+		};
+	}
+	/** Record the current upstream identity; a change clears entries and bumps the epoch. */
+	noteIdentity(identityDigest) {
+		this.#syncIdentity(identityDigest);
+	}
+	/** Invalidate every entry after a catalog-affecting mutation. */
+	noteCatalogMutation() {
+		this.#epoch += 1;
+		this.#entries.clear();
+	}
+	/** Whether a generation is still the current one. */
+	isCurrent(generation) {
+		return this.#isCurrent(generation);
+	}
+	/** Final pre-commit check for a replay result: generation, disposal and age. */
+	canCommit(result) {
+		if (this.#disposed) return false;
+		if (!this.#isCurrent(result.generation)) return false;
+		return this.#clock() < result.validUntil;
+	}
+	/** Invalidate everything and refuse new fills or publication. */
+	dispose() {
+		this.#disposed = true;
+		this.#entries.clear();
+	}
+	#isCurrent(generation) {
+		if (this.#disposed) return false;
+		return generation.identityDigest === this.#identityDigest && generation.epoch === this.#epoch;
+	}
+	#currentGeneration() {
+		return {
+			identityDigest: this.#identityDigest,
+			epoch: this.#epoch
+		};
+	}
+	#syncIdentity(identityDigest) {
+		if (identityDigest === this.#identityDigest) return;
+		this.#identityDigest = identityDigest;
+		this.#epoch += 1;
+		this.#entries.clear();
+	}
+	#createFlight(method, generation, upstream) {
+		const flightKey = `${generation.identityDigest}|${generation.epoch}|${method}`;
+		const invoke = async () => this.#fetchFill({
+			method,
+			generation,
+			upstream
+		});
+		const flight = {
+			generation,
+			method,
+			settled: false,
+			promise: invoke().catch(() => ({ shareable: false })).then((outcome) => {
+				flight.settled = true;
+				if (this.#flights.get(flightKey) === flight) this.#flights.delete(flightKey);
+				if (outcome.shareable && this.#isCurrent(generation)) this.#retain(method, generation, outcome);
+				return outcome;
+			})
+		};
+		this.#flights.set(flightKey, flight);
+		return flight;
+	}
+	#startBackgroundFill(method, identityDigest, upstream) {
+		if (this.#disposed) return;
+		const generation = this.#currentGeneration();
+		const flightKey = `${identityDigest}|${generation.epoch}|${method}`;
+		if (this.#flights.has(flightKey)) return;
+		if (this.inFlightFills >= this.#limits.maxInFlightFills) return;
+		this.#createFlight(method, generation, upstream).promise.catch(() => void 0);
+	}
+	#retain(method, generation, outcome) {
+		if (!validateCatalogEnvelope(outcome.envelopeJson, outcome.upstreamRpcId)) return;
+		const bytes = encoder.encode(outcome.envelopeJson).length;
+		if (bytes > this.#limits.maxEntryBytes) return;
+		const key = `${generation.identityDigest}\u0000${method}`;
+		const now = this.#clock();
+		if (this.#entries.has(key)) this.#entries.delete(key);
+		const evict = () => {
+			const candidates = [...this.#entries.entries()].sort(([, a], [, b]) => a.lastServedAt - b.lastServedAt);
+			for (const [candidateKey] of candidates) {
+				if (this.#entries.size < this.#limits.maxEntries && this.residentBytes + bytes <= this.#limits.maxTotalBytes) break;
+				this.#entries.delete(candidateKey);
+			}
+		};
+		evict();
+		if (this.#entries.size >= this.#limits.maxEntries) return;
+		if (this.residentBytes + bytes > this.#limits.maxTotalBytes) return;
+		this.#entries.set(key, {
+			identityDigest: generation.identityDigest,
+			method,
+			envelopeJson: outcome.envelopeJson,
+			upstreamRpcId: outcome.upstreamRpcId,
+			completedAt: now,
+			validUntil: now + this.#limits.staleMs,
+			bytes,
+			lastServedAt: now
+		});
+	}
+};
 // src/upstream-auth-log.ts
 const LOG_INTERVAL_MS = 3e4;
 /** Two fixed sampling slots keep a first failure visible even after a successful exchange. */
@@ -5387,6 +5694,9 @@ const MOBILE_LAYOUT_MODULE = "@deepseek-ai/dsh-client-ui-layout";
 const MOBILE_LAYOUT_PATH = `${AUTH_PREFIX}/mobile-layout.js`;
 const MOBILE_BOOT_BATCH_PREFIX = `${AUTH_PREFIX}/mobile-boot/`;
 const MOBILE_DOCUMENT_VIEW_HEADER = "x-dsh-mobile-view";
+const CATALOG_CACHE_MARKER = "x-dsh-mobile-catalog";
+/** Eligible catalog envelopes are small fixed-shape JSON; larger declared bodies keep the streaming path. */
+const CATALOG_CANDIDATE_BODY_LIMIT = 65536;
 const MOBILE_PUSH_CONFIG_PATH = `${AUTH_PREFIX}/push/config`;
 const MOBILE_PUSH_SUBSCRIPTION_PATH = `${AUTH_PREFIX}/push/subscription`;
 const MOBILE_PUSH_PREFERENCES_PATH = `${AUTH_PREFIX}/push/preferences`;
@@ -5869,7 +6179,7 @@ function splitMobileBootBatch(entries, sizes, passThrough) {
 	};
 	for (const entry of entries) {
 		const size = sizes.get(entry.url);
-		if ((passThrough.has(entry.url) || size !== void 0 && size >= MAX_MOBILE_BOOT_ENTRY_BYTES) && entry.id !== MOBILE_LAYOUT_MODULE) {
+		if ((passThrough.has(entry.url) || size !== void 0 && (size <= 0 || size >= MAX_MOBILE_BOOT_ENTRY_BYTES)) && entry.id !== MOBILE_LAYOUT_MODULE) {
 			rows.push({
 				phase: "application",
 				url: entry.url,
@@ -5878,7 +6188,7 @@ function splitMobileBootBatch(entries, sizes, passThrough) {
 			});
 			continue;
 		}
-		const bytes = (size ?? 0) + MOBILE_BOOT_SEPARATOR_BYTES;
+		const bytes = (size !== void 0 && size > 0 ? size : 0) + MOBILE_BOOT_SEPARATOR_BYTES;
 		if (chunk !== void 0 && chunk.entries.length > 0 && chunk.bytes + bytes > MOBILE_BOOT_CHUNK_BYTES) flush();
 		chunk ??= {
 			ids: [],
@@ -6482,6 +6792,18 @@ var MobileAccessGateway = class {
 	upstreamCookie;
 	upstreamCookieExpiresAt = 0;
 	upstreamCookieTask;
+	#catalogCache;
+	#upstreamIdentityRevision = 0;
+	#catalogFills = /* @__PURE__ */ new Set();
+	/** The catalog SWR cache, or undefined when `catalogCache` is disabled. */
+	get catalogCache() {
+		if (!this.config.catalogCache) return void 0;
+		this.#catalogCache ??= new CatalogCache({
+			fetchFill: (input) => this.catalogFill(input),
+			clock: () => performance.now()
+		});
+		return this.#catalogCache;
+	}
 	upstreamAuthRequest;
 	nextOperationId = 1;
 	closing = false;
@@ -7529,6 +7851,21 @@ var MobileAccessGateway = class {
 			return;
 		}
 		if (stockFrontend && target.decodedPathname === "/") request.url = "/";
+		const candidateContentType = String(request.headers["content-type"] ?? "").split(";", 1)[0]?.trim().toLowerCase();
+		const candidateDeclaredLength = request.headers["content-length"] === void 0 ? void 0 : Number(request.headers["content-length"]);
+		const catalogRouteMethod = this.config.catalogCache && documentView === void 0 && request.method === "POST" && target.search === "" && candidateContentType === "application/json" && candidateDeclaredLength !== void 0 && Number.isFinite(candidateDeclaredLength) && candidateDeclaredLength > 0 && candidateDeclaredLength <= CATALOG_CANDIDATE_BODY_LIMIT && (target.decodedPathname === "/api/llm/listProviders" || target.decodedPathname === "/api/session/modelCatalog") ? target.decodedPathname.slice(5) : void 0;
+		if (catalogRouteMethod !== void 0) {
+			const candidateBody = await this.readRequestBody(request, Math.min(CATALOG_CANDIDATE_BODY_LIMIT, this.config.maxBodyBytes));
+			const eligible = checkCatalogRequest(catalogRouteMethod, candidateBody.toString("utf8"));
+			if (eligible !== void 0 && this.catalogCache !== void 0) {
+				if (await this.serveCatalogCache(eligible, request, response, authorization)) return;
+				response.setHeader(CATALOG_CACHE_MARKER, "miss-passthrough");
+				await this.proxyHttp(request, response, authorization, documentView, candidateBody);
+				return;
+			}
+			await this.proxyHttp(request, response, authorization, documentView, candidateBody);
+			return;
+		}
 		await this.proxyHttp(request, response, authorization, documentView);
 	}
 	async handleExtensionRequest(targetInfo, target, request, response, authorization) {
@@ -7823,6 +8160,8 @@ var MobileAccessGateway = class {
 			if (pair === void 0 || pair.length > 4096 || !UPSTREAM_COOKIE_PAIR.test(pair) || !Number.isSafeInteger(expiresAt) || maxAgeSeconds <= 0) throw new HttpError(502, "upstream_unavailable");
 			this.upstreamCookie = pair;
 			this.upstreamCookieExpiresAt = expiresAt;
+			this.#upstreamIdentityRevision += 1;
+			this.catalogCache?.noteIdentity(createHash("sha256").update(pair).digest("hex"));
 			this.upstreamAuthDiagnostics.record(attempt, {
 				outcome: "accepted",
 				stage,
@@ -8244,7 +8583,7 @@ var MobileAccessGateway = class {
 				}
 			}
 			operation.signal.throwIfAborted();
-			const headers = sanitizeResponseHeaders(index.headers, this.config.upstreamOrigin);
+			const headers = sanitizeResponseHeaders(index.headers, new URL(request.url ?? "/", this.config.upstreamOrigin));
 			delete headers["content-length"];
 			delete headers["content-encoding"];
 			delete headers.etag;
@@ -8346,7 +8685,7 @@ var MobileAccessGateway = class {
 				const index = cursor++;
 				const source = candidates[index].url;
 				const size = await this.upstreamBundleSize(source, signal);
-				if (size === void 0 || size >= MAX_MOBILE_BOOT_ENTRY_BYTES) passThrough.add(source);
+				if (size === void 0 || size <= 0 || size >= MAX_MOBILE_BOOT_ENTRY_BYTES) passThrough.add(source);
 				else sizes.set(source, size);
 			}
 		};
@@ -8650,13 +8989,181 @@ var MobileAccessGateway = class {
 			}
 		};
 	}
+	/** Read one bounded request body verbatim; the caller owns replaying it upstream. */
+	readRequestBody(request, limitBytes) {
+		const declared = request.headers["content-length"];
+		if (declared !== void 0 && (!/^\d+$/u.test(declared) || Number(declared) > limitBytes)) throw new HttpError(413, "payload_too_large");
+		return new Promise((resolve, reject) => {
+			const chunks = [];
+			let received = 0;
+			let failed = false;
+			request.on("data", (chunk) => {
+				if (failed) return;
+				received += chunk.length;
+				if (received > limitBytes) {
+					failed = true;
+					reject(new HttpError(413, "payload_too_large"));
+					request.resume();
+					return;
+				}
+				chunks.push(chunk);
+			});
+			request.once("end", () => {
+				if (!failed) resolve(Buffer.concat(chunks));
+			});
+			request.once("error", (error) => {
+				if (!failed) reject(error);
+			});
+		});
+	}
+	/** One gateway-owned catalog fill: its own socket, rpcId, deadline and byte cap. */
+	async catalogFill(input) {
+		const rpcId = `dsh-mobile-catalog-${randomUUID()}`;
+		const body = JSON.stringify({
+			type: "client-request",
+			rpcId,
+			method: input.method,
+			payload: { args: {} }
+		});
+		return await new Promise((resolve) => {
+			let settled = false;
+			let upstreamRequest;
+			const finish = (outcome) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(absoluteDeadline);
+				this.#catalogFills.delete(upstreamRequest);
+				resolve(outcome);
+			};
+			upstreamRequest = request({
+				protocol: "http:",
+				hostname: stripIpv6Brackets(this.config.upstreamOrigin.hostname),
+				port: Number(this.config.upstreamOrigin.port),
+				method: "POST",
+				path: `/api/${input.method}`,
+				headers: {
+					host: this.config.upstreamOrigin.host,
+					"content-type": "application/json",
+					accept: "application/json",
+					"accept-encoding": "identity",
+					"content-length": String(Buffer.byteLength(body)),
+					...input.upstream.cookieHeader === void 0 ? {} : { cookie: input.upstream.cookieHeader }
+				},
+				agent: false
+			}, (response) => {
+				const status = response.statusCode ?? 0;
+				const rawContentType = String(response.headers["content-type"] ?? "");
+				const mediaType = rawContentType.split(";", 1)[0]?.trim().toLowerCase();
+				const charset = /charset\s*=\s*([^;]+)/iu.exec(rawContentType)?.[1]?.trim().toLowerCase();
+				if (status !== 200 || mediaType !== "application/json" || charset !== void 0 && charset !== "utf-8" && charset !== "utf8" || response.headers["set-cookie"] !== void 0 || response.headers["content-encoding"] !== void 0 && response.headers["content-encoding"] !== "identity") {
+					response.destroy();
+					finish({ shareable: false });
+					return;
+				}
+				const chunks = [];
+				let received = 0;
+				let overflowed = false;
+				response.on("data", (chunk) => {
+					if (overflowed) return;
+					received += chunk.length;
+					if (received > DEFAULT_CATALOG_CACHE_LIMITS.maxEntryBytes) {
+						overflowed = true;
+						response.destroy();
+						return;
+					}
+					chunks.push(chunk);
+				});
+				response.once("end", () => {
+					if (overflowed) {
+						finish({ shareable: false });
+						return;
+					}
+					try {
+						const envelopeJson = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
+						JSON.parse(envelopeJson);
+						finish({
+							shareable: true,
+							envelopeJson,
+							upstreamRpcId: rpcId
+						});
+					} catch {
+						finish({ shareable: false });
+					}
+				});
+				response.once("error", () => finish({ shareable: false }));
+				response.once("close", () => finish({ shareable: false }));
+			});
+			const absoluteDeadline = setTimeout(() => {
+				upstreamRequest.destroy(/* @__PURE__ */ new Error("catalog fill deadline"));
+			}, this.config.upstreamTimeoutMs);
+			upstreamRequest.setTimeout(this.config.upstreamTimeoutMs, () => {
+				upstreamRequest.destroy(/* @__PURE__ */ new Error("catalog fill idle timeout"));
+			});
+			upstreamRequest.once("error", () => finish({ shareable: false }));
+			this.#catalogFills.add(upstreamRequest);
+			upstreamRequest.end(body);
+		});
+	}
+	/**
+	* Serve one eligible catalog request from the SWR cache.
+	* @returns true when the response was committed here; false for the ordinary path.
+	*/
+	async serveCatalogCache(eligible, request, response, authorization) {
+		const cache = this.catalogCache;
+		if (cache === void 0) return false;
+		const operation = this.allocateRequest(authorization, response, {});
+		const onClose = () => {
+			operation.abort();
+			operation.release();
+		};
+		response.once("close", onClose);
+		try {
+			const snapshotRevision = this.#upstreamIdentityRevision;
+			const hadIdentityBefore = this.upstreamCookie !== void 0;
+			const cookieHeader = await waitForRequestTask(this.upstreamCookieHeader(), operation.signal);
+			operation.signal.throwIfAborted();
+			const superseded = hadIdentityBefore && snapshotRevision !== this.#upstreamIdentityRevision;
+			if (response.destroyed || superseded) return false;
+			const identityDigest = createHash("sha256").update(cookieHeader ?? "none").digest("hex");
+			cache.noteIdentity(identityDigest);
+			const result = await cache.serve({
+				method: eligible.method,
+				rpcId: eligible.rpcId,
+				identityDigest,
+				upstream: { cookieHeader }
+			});
+			operation.signal.throwIfAborted();
+			if (result.kind === "passthrough" || !cache.canCommit(result) || response.destroyed) return false;
+			const payload = Buffer.from(result.body, "utf8");
+			const headers = {
+				"content-type": "application/json",
+				"cache-control": "no-store",
+				[CATALOG_CACHE_MARKER]: result.kind
+			};
+			let body = payload;
+			if (acceptsGzip(request.headers["accept-encoding"]) && payload.length >= MIN_COMPRESSIBLE_BYTES) {
+				body = await gzipBuffer(payload);
+				headers["content-encoding"] = "gzip";
+				addVaryAcceptEncoding(headers);
+			}
+			if (!cache.canCommit(result) || response.destroyed) return false;
+			headers["content-length"] = body.length;
+			setSecurityHeaders(response, this.tlsEnabled, "proxied");
+			response.writeHead(200, headers);
+			response.end(body);
+			return true;
+		} finally {
+			response.removeListener("close", onClose);
+			operation.release();
+		}
+	}
 	/**
 	* Proxy one request, retrying transient failures for plugin and asset GETs.
 	* Only bodyless GETs can be replayed, before response headers reach the client.
 	* One request slot and cancellation signal cover attempts and backoff together.
 	* API requests and requests with bodies are forwarded once.
 	*/
-	async proxyHttp(request, response, authorization, documentView) {
+	async proxyHttp(request, response, authorization, documentView, bodyOverride) {
 		const declared = request.headers["content-length"];
 		if (declared !== void 0 && (!/^\d+$/u.test(declared) || Number(declared) > this.config.maxBodyBytes)) throw new HttpError(413, "payload_too_large");
 		const replayable = request.method === "GET" && request.headers["transfer-encoding"] === void 0 && (declared === void 0 || Number(declared) === 0) && (request.url?.split("?", 1)[0]?.startsWith("/plugins/") === true || request.url?.split("?", 1)[0]?.startsWith("/assets/") === true);
@@ -8684,7 +9191,7 @@ var MobileAccessGateway = class {
 			for (let attempt = 1; attempt <= attempts; attempt++) {
 				operation.signal.throwIfAborted();
 				try {
-					await this.proxyHttpOnce(request, response, holder, operation.signal, replayable, documentView);
+					await this.proxyHttpOnce(request, response, holder, operation.signal, replayable, documentView, bodyOverride);
 					return;
 				} catch (error) {
 					if (operation.signal.aborted || response.destroyed) return;
@@ -8705,7 +9212,7 @@ var MobileAccessGateway = class {
 			operation.release();
 		}
 	}
-	async proxyHttpOnce(request$2, response, holder, signal, replayable, documentView) {
+	async proxyHttpOnce(request$2, response, holder, signal, replayable, documentView, bodyOverride) {
 		let bodyDone;
 		const projections = /* @__PURE__ */ new Set();
 		try {
@@ -8736,7 +9243,8 @@ var MobileAccessGateway = class {
 				});
 				upstreamRequest.once("response", resolve);
 				upstreamRequest.once("error", reject);
-				if (replayable) upstreamRequest.end();
+				if (bodyOverride !== void 0) upstreamRequest.end(bodyOverride);
+				else if (replayable) upstreamRequest.end();
 				else {
 					bodyDone = pipeline(request$2, new ByteLimitTransform(this.config.maxBodyBytes), upstreamRequest);
 					bodyDone.catch(reject);
@@ -8749,7 +9257,7 @@ var MobileAccessGateway = class {
 			}
 			if (graphEvents) holder.request?.setTimeout(this.config.upstreamApiTimeoutMs);
 			setSecurityHeaders(response, this.tlsEnabled, "proxied");
-			const headers = sanitizeResponseHeaders(proxied.headers, this.config.upstreamOrigin);
+			const headers = sanitizeResponseHeaders(proxied.headers, new URL(request$2.url ?? "/", this.config.upstreamOrigin));
 			if (graphEvents) {
 				if (proxied.headers["content-encoding"] !== void 0 && proxied.headers["content-encoding"] !== "identity") throw new HttpError(502, "upstream_unavailable");
 				delete headers["content-length"];
@@ -8760,6 +9268,7 @@ var MobileAccessGateway = class {
 				delete headers["accept-ranges"];
 			}
 			const statusCode = proxied.statusCode ?? 502;
+			if (statusCode >= 200 && statusCode < 300 && this.catalogCache !== void 0 && pathname.startsWith("/api/") && CATALOG_MUTATION_METHODS.has(pathname.slice(5))) this.catalogCache.noteCatalogMutation();
 			this.httpFailures.recordUpstream(request$2.method, request$2.url?.split("?", 1)[0] ?? "", statusCode);
 			const cacheControl = graphEvents ? void 0 : revisionedStaticCacheControl(request$2, statusCode);
 			if (cacheControl !== void 0) headers["cache-control"] = cacheControl;
@@ -9186,6 +9695,9 @@ var MobileAccessGateway = class {
 	}
 	async performClose() {
 		this.closing = true;
+		this.#catalogCache?.dispose();
+		for (const fill of this.#catalogFills) fill.destroy(/* @__PURE__ */ new Error("gateway closing"));
+		this.#catalogFills.clear();
 		const detachPushOrigin = this.detachPushOrigin;
 		this.detachPushOrigin = void 0;
 		detachPushOrigin?.();
@@ -11907,7 +12419,7 @@ async function saveManagedSetup(setupFile, setup) {
 }
 function privateIpv4(value) {
 	const parts = value.split(".").map(Number);
-	return parts.length === 4 && parts.every((part) => Number.isInteger(part) && part >= 0 && part <= 255) && (parts[0] === 10 || parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31 || parts[0] === 192 && parts[1] === 168);
+	return parts.length === 4 && parts.every((part) => Number.isInteger(part) && part >= 0 && part <= 255) && (parts[0] === 10 || parts[0] === 100 && parts[1] >= 64 && parts[1] <= 127 || parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31 || parts[0] === 192 && parts[1] === 168);
 }
 function networkCidr(address, cidr) {
 	const prefix = Number(cidr.slice(cidr.lastIndexOf("/") + 1));
@@ -15429,11 +15941,23 @@ const PAIRING_DESCRIPTOR_LOCAL_PORT = DEFAULT_IROH_LOCAL_PORT;
 const READY_TIMEOUT_MS = 45e3;
 const IDENTITY_TIMEOUT_MS = 15e3;
 const IDENTITY_METADATA_MAX_BYTES = 8192;
+const IDENTITY_DIAGNOSTIC_MAX_BYTES = 4096;
 const PAIRING_TIMEOUT_MS = 15e3;
 const MAX_LINE_BYTES = 16384;
 /** Gateway pairing windows default to five minutes; the descriptor caps at ten. */
 const MAX_PAIRING_WINDOW_MS = 3e5;
 const MIN_PAIRING_WINDOW_MS = 1e4;
+/** Safe classified failure from the short-lived endpoint identity probe. */
+var IrohIdentityProbeError = class extends Error {
+	code;
+	diagnostic;
+	constructor(code, diagnostic) {
+		super(code);
+		this.code = code;
+		this.diagnostic = diagnostic;
+		this.name = "IrohIdentityProbeError";
+	}
+};
 function publicStatus$2(status) {
 	return Object.freeze({ ...status });
 }
@@ -15465,16 +15989,21 @@ async function defaultResolveIdentity(executable, dataDir, options = {}) {
 	}) : options.launch(executable, args);
 	options.onSpawn?.(child);
 	let output = Buffer.alloc(0);
+	let stderrOutput = Buffer.alloc(0);
 	let settled = false;
+	const diagnostic = () => {
+		const text = stderrOutput.toString("utf8").replaceAll(dataDir, "<data-dir>").trim().replace(/\s+/gu, " ");
+		return text === "" ? void 0 : text.slice(0, IDENTITY_DIAGNOSTIC_MAX_BYTES);
+	};
 	return await new Promise((resolve, reject) => {
 		const fail = (code) => {
 			if (settled) return;
 			settled = true;
 			clearTimeout(deadline);
 			terminateRemoteProcess(child).then(() => {
-				reject(new Error(code));
+				reject(new IrohIdentityProbeError(code, diagnostic()));
 			}, () => {
-				reject(new AggregateError([new Error(code), /* @__PURE__ */ new Error("iroh_probe_stop_failed")], "iroh_identity_cleanup_failed"));
+				reject(new AggregateError([new IrohIdentityProbeError(code, diagnostic()), /* @__PURE__ */ new Error("iroh_probe_stop_failed")], "iroh_identity_cleanup_failed"));
 			});
 		};
 		const deadline = setTimeout(() => {
@@ -15489,7 +16018,10 @@ async function defaultResolveIdentity(executable, dataDir, options = {}) {
 			}
 			output = Buffer.concat([output, chunk]);
 		});
-		child.stderr?.resume();
+		child.stderr?.on("data", (chunk) => {
+			const remaining = IDENTITY_DIAGNOSTIC_MAX_BYTES - stderrOutput.length;
+			if (remaining > 0) stderrOutput = Buffer.concat([stderrOutput, chunk.subarray(0, remaining)]);
+		});
 		child.once("error", () => {
 			fail("iroh_identity_failed");
 		});
@@ -15497,14 +16029,19 @@ async function defaultResolveIdentity(executable, dataDir, options = {}) {
 			clearTimeout(deadline);
 			if (settled) return;
 			settled = true;
+			const probeDiagnostic = diagnostic();
+			if (code !== 0 && probeDiagnostic !== void 0 && /private (?:Windows )?data directory is not secure|private path ACL grants/iu.test(probeDiagnostic)) {
+				reject(new IrohIdentityProbeError("iroh_data_directory_insecure", probeDiagnostic));
+				return;
+			}
 			let metadata;
 			try {
 				metadata = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(output));
 			} catch {
-				reject(/* @__PURE__ */ new Error("iroh_identity_invalid"));
+				reject(new IrohIdentityProbeError("iroh_identity_invalid", probeDiagnostic));
 				return;
 			}
-			if (code !== 0 || typeof metadata !== "object" || metadata === null || !("version" in metadata) || metadata.version !== 1 || !("endpointId" in metadata) || typeof metadata.endpointId !== "string" || !/^[0-9a-f]{64}$/u.test(metadata.endpointId)) reject(/* @__PURE__ */ new Error("iroh_identity_invalid"));
+			if (code !== 0 || typeof metadata !== "object" || metadata === null || !("version" in metadata) || metadata.version !== 1 || !("endpointId" in metadata) || typeof metadata.endpointId !== "string" || !/^[0-9a-f]{64}$/u.test(metadata.endpointId)) reject(new IrohIdentityProbeError("iroh_identity_invalid", probeDiagnostic));
 			else resolve(metadata.endpointId);
 		});
 	});
@@ -15691,9 +16228,15 @@ var IrohController = class {
 			this.options.onStatus?.(this.status());
 		} catch {}
 	}
-	async failGeneration(generation, errorCode, origin) {
+	async failGeneration(generation, errorCode, origin, diagnostic) {
 		if (generation !== this.generation) return;
 		this.generation += 1;
+		try {
+			this.options.onFailure?.({
+				errorCode,
+				...diagnostic === void 0 ? {} : { diagnostic }
+			});
+		} catch {}
 		this.publish({
 			enabled: this.enabled,
 			state: "error",
@@ -15778,7 +16321,9 @@ var IrohController = class {
 				});
 			} }) : await this.options.resolveIdentity(executable, this.options.dataDirectory);
 		} catch (error) {
-			await this.failGeneration(generation, error instanceof AggregateError ? "iroh_identity_cleanup_failed" : "iroh_identity_failed");
+			const code = error instanceof AggregateError ? "iroh_identity_cleanup_failed" : error instanceof IrohIdentityProbeError ? error.code : "iroh_identity_failed";
+			const diagnostic = error instanceof IrohIdentityProbeError ? error.diagnostic : error instanceof AggregateError && error.errors[0] instanceof IrohIdentityProbeError ? error.errors[0].diagnostic : void 0;
+			await this.failGeneration(generation, code, void 0, diagnostic);
 			return;
 		}
 		if (generation !== this.generation || !this.enabled) return;
@@ -16787,6 +17332,116 @@ async function collectConnectionDiagnostics(snapshot, probes = {}) {
 		})
 	});
 }
+// src/macos-file-access.ts
+/**
+* Reports whether this process already holds the macOS Full Disk Access grant.
+*
+* macOS shows a folder authorization dialog the first time a process reads a
+* protected location (Desktop, Documents, Downloads, external or network
+* volumes). While that dialog waits for a click, the calling thread stays
+* blocked, so an unattended machine can stall every request that needs the
+* file system. Granting Full Disk Access removes that class of dialog.
+*
+* The probe reads the per-user TCC database. That file is itself protected by
+* TCC, so opening it succeeds only for a process macOS already trusts with
+* Full Disk Access; a denied read fails immediately with EACCES/EPERM because
+* the grant can only be made in System Settings and can never be requested
+* through a dialog. The probe therefore never blocks on user input, unlike
+* reading one of the protected folders themselves.
+*/
+/** A final `ok` is sticky; only a non-ok result is retried, at most this often. */
+const DEFAULT_RETRY_MS = 2e3;
+/** A probe that never settles is treated as missing rather than awaited forever. */
+const DEFAULT_TIMEOUT_MS = 2e3;
+/**
+* Caches the Full Disk Access state so a status response can read it
+* synchronously while the file system check stays asynchronous.
+*/
+var MacFileAccessProbe = class {
+	platform;
+	home;
+	readAccess;
+	now;
+	retryMs;
+	timeoutMs;
+	statusValue = "missing";
+	checkedAt = Number.NEGATIVE_INFINITY;
+	activeProbe;
+	constructor(options = {}) {
+		this.platform = options.platform ?? process.platform;
+		this.home = options.home ?? homedir();
+		this.readAccess = options.readAccess ?? ((path) => access(path, constants.R_OK));
+		this.now = options.now ?? Date.now;
+		this.retryMs = options.retryMs ?? DEFAULT_RETRY_MS;
+		this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	}
+	/** Whether the probe applies to this platform at all. */
+	get applicable() {
+		return this.platform === "darwin";
+	}
+	/** Latest cached result. Never performs I/O. */
+	status() {
+		return this.applicable ? this.statusValue : "ok";
+	}
+	/**
+	* Refresh the cached result when it is not final yet.
+	* @returns The result after this call.
+	*/
+	async refresh() {
+		if (!this.applicable) return "ok";
+		if (this.statusValue === "ok") return "ok";
+		if (this.activeProbe !== void 0) return this.activeProbe;
+		const at = this.now();
+		if (at - this.checkedAt < this.retryMs) return this.statusValue;
+		this.checkedAt = at;
+		const pending = this.probe();
+		this.activeProbe = pending;
+		try {
+			this.statusValue = await pending;
+			return this.statusValue;
+		} finally {
+			if (this.activeProbe === pending) this.activeProbe = void 0;
+		}
+	}
+	/** Run one bounded access check and collapse every failure into `missing`. */
+	async probe() {
+		const database = join(this.home, "Library", "Application Support", "com.apple.TCC", "TCC.db");
+		let timer;
+		try {
+			await Promise.race([this.readAccess(database), new Promise((_resolve, reject) => {
+				timer = setTimeout(() => reject(/* @__PURE__ */ new Error("macos_file_access_probe_timeout")), this.timeoutMs);
+				timer.unref?.();
+			})]);
+			return "ok";
+		} catch {
+			return "missing";
+		} finally {
+			if (timer !== void 0) clearTimeout(timer);
+		}
+	}
+};
+/** System Settings deep link for the Full Disk Access pane. */
+const MAC_FULL_DISK_ACCESS_PANE = "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles";
+/** Absolute path so a GUI-launched process does not depend on PATH. */
+const OPEN_COMMAND = "/usr/bin/open";
+function runCommand(file, args) {
+	return new Promise((resolve, reject) => {
+		execFile(file, [...args], (error) => {
+			if (error === null) resolve();
+			else reject(error);
+		});
+	});
+}
+/**
+* Open the Full Disk Access pane from the host process.
+*
+* The desktop app's renderer refuses to navigate to a custom scheme, so the
+* button cannot use `window.open`; `open` runs on the Mac that owns the app.
+* @param run - Command runner, injectable for tests.
+*/
+async function openMacFullDiskAccessSettings(run = runCommand) {
+	await run(OPEN_COMMAND, [MAC_FULL_DISK_ACCESS_PANE]);
+}
 // src/mobile-guide.ts
 /** Compose the guide with the current customization state injected. */
 function buildMobileGuide(state) {
@@ -19926,11 +20581,33 @@ function launchedProfileName(argv) {
 	}
 	return "web";
 }
+function profileInstallingModule(dshHome, moduleUrl) {
+	let directory;
+	try {
+		directory = dirname(fileURLToPath(moduleUrl));
+	} catch {
+		return;
+	}
+	const profilesRoot = resolve(dshHome, "profiles");
+	for (let depth = 0; depth < 16; depth += 1) {
+		const candidate = resolve(directory);
+		const fromProfiles = relative(profilesRoot, candidate);
+		if (fromProfiles !== "" && !fromProfiles.startsWith("..") && !isAbsolute(fromProfiles)) try {
+			const manifest = JSON.parse(readFileSync(join(candidate, "package.json"), "utf8"));
+			if (typeof manifest.dependencies?.[PACKAGE_NAME] === "string" && typeof manifest.dsh?.profile === "object" && manifest.dsh.profile !== null) return candidate;
+		} catch {}
+		const parent = dirname(candidate);
+		if (parent === candidate) break;
+		directory = parent;
+	}
+}
 /** Resolve the launcher-owned Desktop profile, or the CLI profile outside Desktop. */
-function releaseProfileDirectory(ctx, dshHome, argv) {
+function releaseProfileDirectory(ctx, dshHome, argv, moduleUrl = import.meta.url) {
 	const desktopProfiles = ctx.get("desktopProfiles");
 	const desktopDirectory = desktopProfiles?.current?.dir;
 	if (typeof desktopDirectory === "string" && isAbsolute(desktopDirectory)) return desktopDirectory;
+	const installedProfile = profileInstallingModule(dshHome, moduleUrl);
+	if (installedProfile !== void 0) return installedProfile;
 	if (desktopProfiles !== void 0 || ctx.get("desktopRuntime") !== void 0) return void 0;
 	return join(dshHome, "profiles", launchedProfileName(argv));
 }
@@ -23377,34 +24054,71 @@ function withInstallationIdentity(config, installationId, explicitIdentity) {
 // src/lan-setup.ts
 const FIREWALL_TCP_RULE = "DSH Mobile HTTPS";
 const FIREWALL_UDP_RULE = "DSH Mobile Discovery";
+const MIN_MANAGED_PORT = 1024;
+const MAX_MANAGED_PORT = 65535;
+function assertManagedPort(port, name) {
+	if (!Number.isSafeInteger(port) || port < MIN_MANAGED_PORT || port > MAX_MANAGED_PORT) throw new Error(`${name} must be from ${String(MIN_MANAGED_PORT)} through ${String(MAX_MANAGED_PORT)}`);
+}
+function powerShellFailureDetail(error) {
+	if (!(error instanceof Error)) return "unknown failure";
+	const code = "code" in error && typeof error.code === "string" ? ` (${error.code})` : "";
+	const stderr = "stderr" in error && typeof error.stderr === "string" ? error.stderr.trim().replace(/\s+/gu, " ").slice(0, 512) : "";
+	return `${code}${stderr === "" ? "" : `: ${stderr}`}`;
+}
 async function runElevatedPowerShell(script) {
-	await execFileText("powershell.exe", [
-		"-NoProfile",
-		"-NonInteractive",
-		"-Command",
-		[
-			"$ErrorActionPreference = 'Stop'; $process = Start-Process -FilePath 'powershell.exe' -Verb RunAs -WindowStyle Hidden -Wait -PassThru",
-			`  -ArgumentList @('-NoProfile','-NonInteractive','-EncodedCommand','${Buffer.from(script, "utf16le").toString("base64")}')`,
-			"; exit $process.ExitCode"
-		].join(" ")
-	], { windowsHide: true });
-}
-/** Install the two Windows inbound rules used by the managed LAN listener. */
+	const launch = [
+		"$ErrorActionPreference = 'Stop'; $process = Start-Process -FilePath 'powershell.exe' -Verb RunAs -WindowStyle Hidden -Wait -PassThru",
+		`  -ArgumentList @('-NoProfile','-NonInteractive','-EncodedCommand','${Buffer.from(script, "utf16le").toString("base64")}')`,
+		"; exit $process.ExitCode"
+	].join(" ");
+	try {
+		await execFileText("powershell.exe", [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			launch
+		], { windowsHide: true });
+	} catch (error) {
+		throw new Error(`Windows firewall operation failed${powerShellFailureDetail(error)}`, { cause: error });
+	}
+}
+function firewallRuleScript(name, protocol, port) {
+	return [
+		`$rules = @(Get-NetFirewallRule -DisplayName '${name}' -ErrorAction SilentlyContinue)`,
+		"if ($rules.Count -eq 0) {",
+		`  New-NetFirewallRule -DisplayName '${name}' -Direction Inbound -Action Allow -Protocol ${protocol} -LocalPort ${String(port)} -RemoteAddress LocalSubnet -Profile Any | Out-Null`,
+		"} else {",
+		"  foreach ($rule in $rules) {",
+		"    $rule | Set-NetFirewallRule -Enabled True -Direction Inbound -Action Allow -Profile Any",
+		`    $rule | Get-NetFirewallPortFilter | Set-NetFirewallPortFilter -Protocol ${protocol} -LocalPort ${String(port)}`,
+		"    $rule | Get-NetFirewallAddressFilter | Set-NetFirewallAddressFilter -RemoteAddress LocalSubnet",
+		"  }",
+		"}",
+		`$verified = @(Get-NetFirewallRule -DisplayName '${name}' -Enabled True -Direction Inbound -Action Allow -Profile Any -ErrorAction Stop)`,
+		`$matchingPort = @($verified | Get-NetFirewallPortFilter | Where-Object { $_.Protocol -eq '${protocol}' -and $_.LocalPort -contains '${String(port)}' })`,
+		`$matchingAddress = @($verified | Get-NetFirewallAddressFilter | Where-Object { $_.RemoteAddress -contains 'LocalSubnet' })`,
+		`if ($verified.Count -eq 0 -or $matchingPort.Count -eq 0 -or $matchingAddress.Count -eq 0) { throw "DSH Mobile firewall rule '${name}' is not active with the expected scope" }`
+	];
+}
+/** Build the elevated Windows firewall script without removing a working rule first. */
+function windowsFirewallSetupScript(port) {
+	assertManagedPort(port, "Windows firewall port");
+	return [
+		"$ErrorActionPreference = 'Stop'",
+		...firewallRuleScript(FIREWALL_TCP_RULE, "TCP", port),
+		...firewallRuleScript(FIREWALL_UDP_RULE, "UDP", port)
+	].join("\n");
+}
+/** Install or update the two Windows inbound rules used by the managed LAN listener. */
 async function configureWindowsFirewall(port) {
 	if (process.platform !== "win32") return;
-	await runElevatedPowerShell([
-		"$ErrorActionPreference = 'Stop'",
-		`Get-NetFirewallRule -DisplayName '${FIREWALL_TCP_RULE}' -ErrorAction SilentlyContinue | Remove-NetFirewallRule`,
-		`Get-NetFirewallRule -DisplayName '${FIREWALL_UDP_RULE}' -ErrorAction SilentlyContinue | Remove-NetFirewallRule`,
-		`New-NetFirewallRule -DisplayName '${FIREWALL_TCP_RULE}' -Direction Inbound -Action Allow -Protocol TCP -LocalPort ${String(port)} -RemoteAddress LocalSubnet -Profile Any | Out-Null`,
-		`New-NetFirewallRule -DisplayName '${FIREWALL_UDP_RULE}' -Direction Inbound -Action Allow -Protocol UDP -LocalPort ${String(port)} -RemoteAddress LocalSubnet -Profile Any | Out-Null`
-	].join("; "));
+	await runElevatedPowerShell(windowsFirewallSetupScript(port));
 }
 /** Generate private TLS material and persist a managed setup selected by the user. */
 async function prepareManagedLanSetup(options) {
 	if (!isAbsolute(options.setupFile) || !isAbsolute(options.controlFile)) throw new Error("managed LAN setup paths must be absolute");
-	if (!Number.isSafeInteger(options.listenPort) || options.listenPort < 1024 || options.listenPort > 65535) throw new Error("managed LAN listenPort must be from 1024 through 65535");
-	if (!Number.isSafeInteger(options.dshPort) || options.dshPort < 1024 || options.dshPort > 65535) throw new Error("managed LAN dshPort must be from 1024 through 65535");
+	assertManagedPort(options.listenPort, "managed LAN listenPort");
+	assertManagedPort(options.dshPort, "managed LAN dshPort");
 	const directory = dirname(options.setupFile);
 	const tlsDirectory = join(directory, "tls");
 	await mkdir(tlsDirectory, {
@@ -24042,6 +24756,7 @@ async function apply(ctx, config) {
 	const cloudflaredComponent = new CloudflaredComponentManager({ stateDirectory });
 	await cloudflaredComponent.initialize();
 	const frpComponent = new FrpComponentManager({ stateDirectory });
+	const macFileAccess = new MacFileAccessProbe();
 	await frpComponent.initialize();
 	const irohComponent = new IrohComponentManager({
 		stateDirectory,
@@ -24301,6 +25016,9 @@ async function apply(ctx, config) {
 		component: irohComponent,
 		dataDirectory: join(remoteDirectory, "iroh", "sidecar"),
 		createGateway: (endpointId) => createIrohGateway(endpointId),
+		onFailure: ({ errorCode, diagnostic }) => {
+			logger.warn("iroh startup failed: %s%s", errorCode, diagnostic === void 0 ? "" : `; ${diagnostic}`);
+		},
 		/**
 		* Read the pairing CA the live gateway advertises. The fingerprint must
 		* match the gateway instance id, otherwise a rotated CA would mint QR
@@ -24389,7 +25107,10 @@ async function apply(ctx, config) {
 		originMode: originController.mode(),
 		caddyConfiguration: caddyConfig.status(),
 		caddyState: caddyController.status(),
-		...process.platform === "darwin" ? { macosHost: true } : {}
+		...macFileAccess.applicable ? {
+			macosHost: true,
+			macFileAccess: macFileAccess.status()
+		} : {}
 	});
 	const lanPayload = () => ({
 		...loaded.kind === "unconfigured" ? {
@@ -24713,9 +25434,16 @@ async function apply(ctx, config) {
 					return;
 				}
 				if (request.method === "GET" && target.decodedPathname === `/api/mobile-access/remote/control`) {
+					await macFileAccess.refresh();
 					sendJson(response, 200, remotePayload(), false);
 					return;
 				}
+				if (request.method === "POST" && target.decodedPathname === `/api/mobile-access/remote/macos-file-access/open-settings`) {
+					if (!macFileAccess.applicable) throw new HttpError(404, "not_found");
+					await openMacFullDiskAccessSettings();
+					sendJson(response, 200, { opened: true }, false);
+					return;
+				}
 				if (request.method === "POST" && target.decodedPathname === `/api/mobile-access/remote/provider`) {
 					const body = await readJsonObject(request, 4096);
 					if (body.provider !== "tailscale" && body.provider !== "cpolar" && body.provider !== "cloudflared" && body.provider !== "frp" && body.provider !== "origin" && body.provider !== "iroh") throw new HttpError(400, "bad_request");