@tnnevol/dsh-fnos 0.1.1-rc.2.0

package/lib/index.js

@@ -0,0 +1,800 @@
+import { settingsNamespace } from "@deepseek-ai/dsh-settings";
+import z from "@deepseek-ai/schemastery";
+import { constants } from "node:fs";
+import { access, readdir, realpath, stat } from "node:fs/promises";
+import { posix } from "node:path";
+import { request } from "node:http";
+//#region src/fnos-api.ts
+/** Minimal server-side client for the fnOS open API gateway. */
+const FNOS_API_SOCKET = "/var/run/trim_open_gateway_apiscope.socket";
+const FNOS_API_PATH = "/api/v1/trimapp";
+const RESPONSE_LIMIT = 131072;
+const REQUEST_TIMEOUT_MS = 1e4;
+var FnOsApiError = class extends Error {
+	apiCode;
+	constructor(apiCode, message) {
+		super(message);
+		this.apiCode = apiCode;
+		this.name = "FnOsApiError";
+	}
+};
+function apiMessage(value) {
+	return typeof value === "string" && value.trim().length > 0 ? value.trim().slice(0, 300) : "fnOS API request failed";
+}
+function requestId() {
+	return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+/** Call one fnOS API without persisting or exposing TRIM_API_TOKEN. */
+async function callFnOsApi(req, data = {}, options = {}) {
+	const token = (options.token ?? process.env.TRIM_API_TOKEN)?.trim();
+	if (token === void 0 || token.length === 0) throw new FnOsApiError(void 0, "fnOS API token is unavailable");
+	const appName = options.appName?.trim() || process.env.TRIM_APPNAME?.trim() || "fn-deepseek-harness";
+	const timeoutMs = options.timeoutMs ?? REQUEST_TIMEOUT_MS;
+	const payload = JSON.stringify({
+		reqId: requestId(),
+		req,
+		appName,
+		data
+	});
+	const response = await new Promise((resolve, reject) => {
+		const reqHandle = request({
+			socketPath: options.socketPath ?? FNOS_API_SOCKET,
+			path: FNOS_API_PATH,
+			method: "POST",
+			headers: {
+				accept: "application/json",
+				"content-type": "application/json",
+				"content-length": Buffer.byteLength(payload),
+				authorization: `Bearer ${token}`
+			}
+		}, (responseMessage) => {
+			let body = "";
+			let size = 0;
+			responseMessage.setEncoding("utf8");
+			responseMessage.on("data", (chunk) => {
+				size += Buffer.byteLength(chunk);
+				if (size <= RESPONSE_LIMIT) body += chunk;
+			});
+			responseMessage.on("end", () => {
+				if (size > RESPONSE_LIMIT) {
+					reject(new FnOsApiError(void 0, "fnOS API response is too large"));
+					return;
+				}
+				resolve({
+					statusCode: responseMessage.statusCode ?? 0,
+					body
+				});
+			});
+			responseMessage.on("error", reject);
+		});
+		reqHandle.setTimeout(timeoutMs, () => {
+			reqHandle.destroy(/* @__PURE__ */ new Error("fnOS API request timed out"));
+		});
+		reqHandle.on("error", reject);
+		reqHandle.end(payload);
+	});
+	if (response.statusCode < 200 || response.statusCode >= 300) throw new FnOsApiError(void 0, `fnOS API returned HTTP ${String(response.statusCode)}`);
+	let envelope;
+	try {
+		envelope = JSON.parse(response.body);
+	} catch {
+		throw new FnOsApiError(void 0, "fnOS API returned invalid JSON");
+	}
+	const code = typeof envelope.code === "number" ? envelope.code : void 0;
+	if (code !== 0) throw new FnOsApiError(code, apiMessage(envelope.msg));
+	return envelope.data;
+}
+//#endregion
+//#region src/authorized-directories-contract.ts
+/** Browser/Host contract for fnOS shared-directory management. */
+/** Settings namespace used to pair the Host namespace with the Client card. */
+const FNOS_AUTHORIZED_DIRECTORIES_SETTINGS_NAMESPACE = "dsh-fnos-authorized-directories";
+/** Same-origin route that lists the directories currently authorized for the app. */
+const FNOS_AUTHORIZED_DIRECTORIES_PATH = "/plugins/dsh-fnos/authorized-directories";
+/** Same-origin route that removes one application directory ACL. */
+const FNOS_AUTHORIZED_DIRECTORIES_DELETE_PATH = "/plugins/dsh-fnos/authorized-directories/delete";
+/** Same-origin route that converts internal fnOS paths to readable paths. */
+const FNOS_PATH_CONVERSION_PATH = "/plugins/dsh-fnos/paths/convert";
+/** Same-origin route that validates a DSH path before fnOS opens it. */
+const FNOS_PATH_OPEN_VALIDATION_PATH = "/plugins/dsh-fnos/paths/open/validate";
+/** Same-origin route that lists one level below an authorized NAS directory. */
+const FNOS_AUTHORIZED_ENTRIES_PATH = "/plugins/dsh-fnos/authorized-directories/entries";
+//#endregion
+//#region src/authorized-directories.ts
+const BODY_LIMIT = 65536;
+/** Paths removed during this process must not be reintroduced from a stale env snapshot. */
+const removedAccessiblePaths = /* @__PURE__ */ new Set();
+/** fnOS supplies user-authorized application paths through this variable. */
+const FNOS_ACCESSIBLE_PATHS_ENV = "TRIM_DATA_ACCESSIBLE_PATHS";
+/** fnOS supplies the application's declared shared data paths through this variable. */
+const FNOS_DATA_SHARE_PATHS_ENV = "TRIM_DATA_SHARE_PATHS";
+const AUTHORIZED_ENTRIES_LIMIT = 500;
+var AuthorizedEntriesError = class extends Error {
+	code;
+	status;
+	constructor(code, status, message = code) {
+		super(message);
+		this.code = code;
+		this.status = status;
+		this.name = "AuthorizedEntriesError";
+	}
+};
+function header(req, name) {
+	const value = req.headers[name];
+	return Array.isArray(value) ? value[0] : value;
+}
+/**
+* Read the user identity supplied by the fnOS unified gateway.
+*
+* `TRIM_UID` is the application service user and must not be used here. The
+* current browser user is carried by `X-Trim-Userid` on gateway requests.
+*/
+function gatewayUserId(req) {
+	const value = req === void 0 ? void 0 : header(req, "x-trim-userid")?.trim();
+	if (value === void 0 || !/^\d+$/u.test(value)) return void 0;
+	const uid = Number(value);
+	return Number.isSafeInteger(uid) && uid >= 0 ? uid : void 0;
+}
+function firstForwarded(value) {
+	return value?.split(",")[0]?.trim() || void 0;
+}
+function requestOrigin(req) {
+	const host = firstForwarded(header(req, "x-forwarded-host")) ?? header(req, "host");
+	if (host === void 0) return void 0;
+	const proto = firstForwarded(header(req, "x-forwarded-proto")) ?? (req.socket.encrypted === true ? "https" : "http");
+	try {
+		return new URL(`${proto}://${host}`).origin;
+	} catch {
+		return;
+	}
+}
+function normalizeOrigin(raw) {
+	try {
+		return new URL(raw).origin;
+	} catch {
+		return;
+	}
+}
+function localPeer(req) {
+	const remote = req.socket.remoteAddress;
+	return remote === "127.0.0.1" || remote === "::1" || remote === "::ffff:127.0.0.1";
+}
+/** Accept the NAS gateway's same-origin requests, but reject cross-site calls. */
+function trustedRequest(req) {
+	if (header(req, "sec-fetch-site")?.trim().toLowerCase() === "cross-site") return false;
+	const origin = header(req, "origin");
+	if (origin !== void 0) return requestOrigin(req) === normalizeOrigin(origin);
+	return localPeer(req);
+}
+function json(res, status, value) {
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"cache-control": "no-store",
+		"x-content-type-options": "nosniff"
+	});
+	res.end(JSON.stringify(value));
+}
+function readJsonBody(req) {
+	return new Promise((resolve, reject) => {
+		let body = "";
+		let size = 0;
+		let finished = false;
+		req.setEncoding("utf8");
+		req.on("data", (chunk) => {
+			if (finished) return;
+			size += Buffer.byteLength(chunk);
+			if (size > BODY_LIMIT) {
+				finished = true;
+				reject(/* @__PURE__ */ new Error("request body is too large"));
+				return;
+			}
+			body += chunk;
+		});
+		req.on("end", () => {
+			if (finished) return;
+			finished = true;
+			try {
+				resolve(JSON.parse(body));
+			} catch {
+				reject(/* @__PURE__ */ new Error("request body is not valid JSON"));
+			}
+		});
+		req.on("error", (error) => {
+			if (finished) return;
+			finished = true;
+			reject(error);
+		});
+	});
+}
+/** Normalize one fnOS volume path for display and exact delete matching. */
+function normalizeAuthorizedPath(value) {
+	if (typeof value !== "string") return void 0;
+	const path = value.trim();
+	if (path.length === 0 || !path.startsWith("/") || path.includes("\0")) return void 0;
+	if (path === "/") return path;
+	return path.replace(/\/+$/u, "");
+}
+/** Normalize a path used for the open authorization boundary. */
+function normalizePathForAuthorization(value) {
+	const path = normalizeAuthorizedPath(value);
+	if (path === void 0) return void 0;
+	return normalizeAuthorizedPath(posix.normalize(path));
+}
+/** Check a target path against authorized roots without confusing path prefixes. */
+function isPathWithinAuthorizedDirectory(pathValue, rootsValue) {
+	const path = normalizePathForAuthorization(pathValue);
+	if (path === void 0) return false;
+	return normalizeAuthorizedPaths(rootsValue).map(normalizePathForAuthorization).filter((root) => root !== void 0).some((root) => root === "/" || path === root || path.startsWith(`${root}/`));
+}
+/** Keep API order while removing malformed and duplicate paths. */
+function normalizeAuthorizedPaths(value) {
+	if (!Array.isArray(value)) return [];
+	const paths = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of value) {
+		const path = normalizeAuthorizedPath(entry);
+		if (path === void 0 || seen.has(path)) continue;
+		seen.add(path);
+		paths.push(path);
+	}
+	return paths;
+}
+function userAclEntries(value) {
+	if (Array.isArray(value)) return value.filter((entry) => typeof entry === "object" && entry !== null && !Array.isArray(entry));
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return [];
+	const record = value;
+	for (const key of [
+		"result",
+		"paths",
+		"data"
+	]) {
+		const entries = userAclEntries(record[key]);
+		if (entries.length > 0) return entries;
+	}
+	return [];
+}
+function userAclResult(value) {
+	const readable = /* @__PURE__ */ new Set();
+	for (const entry of userAclEntries(value)) {
+		if (entry.readable !== true) continue;
+		const path = normalizePathForAuthorization(entry.path);
+		if (path !== void 0) readable.add(path);
+	}
+	return {
+		available: true,
+		readable
+	};
+}
+/**
+* Check the current gateway user instead of treating an application ACL root
+* as proof that every user can read every child path.
+*
+* Direct localhost development requests do not carry a NAS user header. In
+* that case the real process-level fs check remains the only meaningful check
+* and the fnOS `openFile()` bridge is still the final host-side operation.
+*/
+const checkCurrentUserAcl = async (req, paths) => {
+	const uid = gatewayUserId(req);
+	const normalizedPaths = normalizeAuthorizedPaths(paths);
+	if (uid === void 0 || normalizedPaths.length === 0) return {
+		available: true,
+		readable: new Set(normalizedPaths)
+	};
+	try {
+		return userAclResult(await callFnOsApi("trim.file.checkUserACL", {
+			uid,
+			path: normalizedPaths.length === 1 ? normalizedPaths[0] : normalizedPaths
+		}));
+	} catch (error) {
+		console.warn("[dsh-fnos] unable to check current fnOS user ACL", error);
+		return {
+			available: false,
+			readable: /* @__PURE__ */ new Set()
+		};
+	}
+};
+/** Parse a fnOS colon-separated path environment variable. */
+function splitPathEnvironment(value) {
+	if (typeof value !== "string") return [];
+	return value.split(":").map((value) => value.trim()).filter((value) => value.length > 0);
+}
+/** Read user-authorized paths from the lifecycle environment and de-duplicate them. */
+function accessiblePathsFromEnvironment(env = process.env) {
+	return normalizeAuthorizedPaths(splitPathEnvironment(env[FNOS_ACCESSIBLE_PATHS_ENV]));
+}
+/** Read declared application data shares for display and de-duplicate them. */
+function dataSharePathsFromEnvironment(env = process.env) {
+	return normalizeAuthorizedPaths(splitPathEnvironment(env[FNOS_DATA_SHARE_PATHS_ENV]));
+}
+/** Combine path sources without changing the first-seen order. */
+function mergeAuthorizedPaths(...values) {
+	return normalizeAuthorizedPaths(values.flatMap((value) => Array.isArray(value) ? value : splitPathEnvironment(value)));
+}
+/** Keep a just-removed ACL out of the process-local merged configuration. */
+function markAuthorizedPathRemoved(value) {
+	const path = normalizeAuthorizedPath(value);
+	if (path !== void 0) removedAccessiblePaths.add(path);
+}
+function requestLanguage(req) {
+	const value = header(req, "accept-language")?.split(",")[0]?.trim().replace(/_/gu, "-");
+	if (value !== void 0 && /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})?$/u.test(value)) return value;
+	return "en-US";
+}
+function readableFallbackPath(path, language) {
+	const volume = /^\/vol(\d+)(?:\/(.*))?$/u.exec(path);
+	if (volume !== null) {
+		const prefix = language.toLowerCase().startsWith("zh") ? `存储空间${volume[1]}` : `Storage ${volume[1]}`;
+		return volume[2] === void 0 || volume[2].length === 0 ? prefix : `${prefix}/${volume[2]}`;
+	}
+	if (path === "/") return language.toLowerCase().startsWith("zh") ? "根目录" : "Root";
+	return path;
+}
+function convertedPathMap(value) {
+	const result = /* @__PURE__ */ new Map();
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return result;
+	const envelope = value;
+	const nested = typeof envelope.data === "object" && envelope.data !== null && !Array.isArray(envelope.data) ? envelope.data : void 0;
+	const entries = Array.isArray(envelope.result) ? envelope.result : nested?.result;
+	if (!Array.isArray(entries)) return result;
+	for (const entry of entries) {
+		if (typeof entry !== "object" || entry === null || Array.isArray(entry)) continue;
+		const path = normalizeAuthorizedPath(entry.path);
+		const rawSemanticPath = entry.semanticPath;
+		const semanticPath = typeof rawSemanticPath === "string" ? rawSemanticPath.trim() : "";
+		if (path !== void 0 && semanticPath.length > 0 && semanticPath !== path) result.set(path, semanticPath);
+	}
+	return result;
+}
+/** Pair internal paths with fnOS semantic paths, falling back per entry. */
+async function convertPathsForDisplay(pathsValue, language = "en-US") {
+	const paths = normalizeAuthorizedPaths(pathsValue);
+	if (paths.length === 0) return [];
+	let convertedValue;
+	try {
+		convertedValue = await callFnOsApi("trim.file.convertPath", {
+			path: paths,
+			language
+		});
+	} catch (error) {
+		console.warn("[dsh-fnos] unable to convert selected fnOS paths", error);
+	}
+	const converted = convertedPathMap(convertedValue);
+	return paths.map((path) => ({
+		path,
+		semanticPath: converted.get(path) ?? readableFallbackPath(path, language)
+	}));
+}
+/**
+* Query the current ACL. The environment is a fallback for hosts that expose
+* the ACL to the app process but temporarily reject the read API; a successful
+* API response remains authoritative so a just-removed path is not resurrected
+* from a stale process environment.
+*/
+async function loadAuthorizedDirectoryPaths() {
+	const environmentPaths = accessiblePathsFromEnvironment();
+	try {
+		const apiPaths = normalizeAuthorizedPaths((await callFnOsApi("trim.file.getSharedAccessibleFolders"))?.paths);
+		for (const path of apiPaths) removedAccessiblePaths.delete(path);
+		return mergeAuthorizedPaths(apiPaths, environmentPaths).filter((path) => !removedAccessiblePaths.has(path));
+	} catch (error) {
+		if (environmentPaths.length === 0) throw error;
+		console.warn("[dsh-fnos] using TRIM_DATA_ACCESSIBLE_PATHS because the fnOS ACL query failed");
+		return environmentPaths.filter((path) => !removedAccessiblePaths.has(path));
+	}
+}
+async function readablePathStat(path) {
+	try {
+		const pathStat = await stat(path);
+		const mode = pathStat.isDirectory() ? constants.R_OK | constants.X_OK : constants.R_OK;
+		await access(path, mode);
+		return pathStat;
+	} catch {
+		return;
+	}
+}
+async function existingAuthorizedRoots(rootsValue) {
+	const roots = normalizeAuthorizedPaths(rootsValue);
+	return (await Promise.all(roots.map(async (root) => {
+		try {
+			const resolvedRoot = normalizePathForAuthorization(await realpath(root));
+			if (resolvedRoot === void 0) return void 0;
+			return (await readablePathStat(resolvedRoot))?.isDirectory() === true ? resolvedRoot : void 0;
+		} catch {
+			return;
+		}
+	}))).filter((root) => root !== void 0);
+}
+async function currentAuthorizedRoots(options = {}) {
+	if (options.roots !== void 0) return existingAuthorizedRoots(options.roots);
+	return resolvedAuthorizedRoots();
+}
+async function validateReadableAuthorizedPath(req, path, roots, checkUserAcl) {
+	let pathStat;
+	try {
+		pathStat = await stat(path);
+	} catch {
+		return {
+			ok: false,
+			failure: "fnos-path-not-found"
+		};
+	}
+	try {
+		const mode = pathStat.isDirectory() ? constants.R_OK | constants.X_OK : constants.R_OK;
+		await access(path, mode);
+	} catch {
+		return {
+			ok: false,
+			failure: "fnos-path-not-readable"
+		};
+	}
+	if (!await isResolvedPathWithinAuthorizedRoots(path, roots)) return {
+		ok: false,
+		failure: "fnos-path-not-authorized"
+	};
+	const userAcl = await checkUserAcl(req, [path]);
+	if (!userAcl.available) return {
+		ok: false,
+		failure: "fnos-user-permission-unavailable"
+	};
+	if (!userAcl.readable.has(path)) return {
+		ok: false,
+		failure: "fnos-user-permission-denied"
+	};
+	return { ok: true };
+}
+/**
+* Validate a DSH file/directory target using all applicable permission layers:
+* the app's real shared roots, the process's actual fs access, and the
+* current NAS user ACL supplied by the unified gateway.
+*/
+async function validatePathForOpen(pathValue, req, options = {}) {
+	const path = normalizePathForAuthorization(pathValue);
+	if (path === void 0) return {
+		ok: false,
+		failure: "fnos-path-not-authorized"
+	};
+	return validateReadableAuthorizedPath(req, path, await currentAuthorizedRoots(options), options.checkUserAcl ?? checkCurrentUserAcl);
+}
+/** Backward-compatible boolean helper for callers that only need a verdict. */
+async function isAuthorizedPathForOpen(pathValue, req) {
+	return (await validatePathForOpen(pathValue, req)).ok;
+}
+async function convertDirectories(paths, language, readOnlyPaths = []) {
+	const readOnly = new Set(normalizeAuthorizedPaths(readOnlyPaths));
+	return (await convertPathsForDisplay(paths, language)).map((entry) => ({
+		...entry,
+		removable: !readOnly.has(entry.path)
+	}));
+}
+async function loadAuthorizedDirectories(req) {
+	const readOnlyPaths = dataSharePathsFromEnvironment();
+	let accessiblePaths = [];
+	try {
+		accessiblePaths = await loadAuthorizedDirectoryPaths();
+	} catch (error) {
+		if (readOnlyPaths.length === 0) throw error;
+		console.warn("[dsh-fnos] using TRIM_DATA_SHARE_PATHS because the fnOS ACL query failed", error);
+	}
+	return convertDirectories(mergeAuthorizedPaths(accessiblePaths, readOnlyPaths), requestLanguage(req), readOnlyPaths);
+}
+function errorResponse(res, error) {
+	if (error instanceof FnOsApiError && error.apiCode === 1) {
+		json(res, 403, { error: "fnos-authorized-directory-permission-denied" });
+		return;
+	}
+	json(res, 502, { error: "fnos-authorized-directory-request-failed" });
+}
+function deletePath(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	return normalizeAuthorizedPath(value.path);
+}
+function conversionPaths(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	const valuePaths = value.paths;
+	if (!Array.isArray(valuePaths)) return void 0;
+	return normalizeAuthorizedPaths(valuePaths);
+}
+function openPathValue(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	return normalizePathForAuthorization(value.path);
+}
+/** Read the optional directory field used by the authorized-entry listing. */
+function listingPathValue(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+	const raw = value.path;
+	if (raw === void 0) return void 0;
+	return normalizePathForAuthorization(raw) ?? null;
+}
+async function resolvedAuthorizedRoots() {
+	let roots;
+	try {
+		roots = mergeAuthorizedPaths(await loadAuthorizedDirectoryPaths(), dataSharePathsFromEnvironment());
+	} catch (error) {
+		const shares = dataSharePathsFromEnvironment();
+		if (shares.length === 0) throw error;
+		roots = shares;
+	}
+	return existingAuthorizedRoots(roots);
+}
+async function isResolvedPathWithinAuthorizedRoots(path, roots) {
+	try {
+		const resolvedPath = normalizePathForAuthorization(await realpath(path));
+		if (resolvedPath === void 0) return false;
+		return roots.some((root) => root === "/" || resolvedPath === root || resolvedPath.startsWith(`${root}/`));
+	} catch {
+		return false;
+	}
+}
+function authorizedEntriesErrorForValidation(result) {
+	switch (result.failure) {
+		case "fnos-path-not-found": return new AuthorizedEntriesError("authorized-directory-not-found", 404);
+		case "fnos-path-not-readable":
+		case "fnos-user-permission-denied": return new AuthorizedEntriesError("authorized-directory-not-readable", 403);
+		case "fnos-user-permission-unavailable": return new AuthorizedEntriesError("fnos-user-permission-check-unavailable", 503);
+		default: return new AuthorizedEntriesError("fnos-path-not-authorized", 403);
+	}
+}
+function sortAuthorizedEntries(entries) {
+	return entries.sort((left, right) => {
+		if (left.kind !== right.kind) return left.kind === "directory" ? -1 : 1;
+		return left.semanticPath.localeCompare(right.semanticPath, void 0, {
+			numeric: true,
+			sensitivity: "base"
+		});
+	});
+}
+/**
+* List only existing, readable authorized roots or one authorized directory
+* level. The app ACL root is only the first boundary: every returned entry is
+* also checked with the real filesystem and, when the request came through
+* the fnOS gateway, the current user's ACL.
+*/
+async function loadAuthorizedEntries(req, pathValue) {
+	const roots = await resolvedAuthorizedRoots();
+	if (pathValue === void 0) {
+		const userAcl = await checkCurrentUserAcl(req, roots);
+		if (!userAcl.available) throw new AuthorizedEntriesError("fnos-user-permission-check-unavailable", 503);
+		return { entries: (await convertPathsForDisplay(roots.filter((root) => userAcl.readable.has(root)), requestLanguage(req))).map((entry) => ({
+			...entry,
+			kind: "directory"
+		})) };
+	}
+	const pathValidation = await validateReadableAuthorizedPath(req, pathValue, roots, checkCurrentUserAcl);
+	if (!pathValidation.ok) throw authorizedEntriesErrorForValidation(pathValidation);
+	if (!(await stat(pathValue)).isDirectory()) throw new AuthorizedEntriesError("authorized-path-not-directory", 400);
+	let children;
+	try {
+		children = await readdir(pathValue, { withFileTypes: true });
+	} catch {
+		throw new AuthorizedEntriesError("authorized-directory-not-readable", 403);
+	}
+	const candidates = [];
+	for (const child of children) {
+		const childPath = normalizePathForAuthorization(posix.join(pathValue, child.name));
+		if (childPath === void 0) continue;
+		try {
+			const childStat = await readablePathStat(childPath);
+			if (childStat === void 0) continue;
+			if (!await isResolvedPathWithinAuthorizedRoots(childPath, roots)) continue;
+			const candidate = {
+				path: childPath,
+				kind: childStat.isDirectory() ? "directory" : "file",
+				modifiedAt: childStat.mtimeMs
+			};
+			if (childStat.isFile()) candidate.size = childStat.size;
+			candidates.push(candidate);
+		} catch {}
+	}
+	const userAcl = await checkCurrentUserAcl(req, candidates.map((entry) => entry.path));
+	if (!userAcl.available) throw new AuthorizedEntriesError("fnos-user-permission-check-unavailable", 503);
+	const readableCandidates = candidates.filter((entry) => userAcl.readable.has(entry.path));
+	const truncated = readableCandidates.length > AUTHORIZED_ENTRIES_LIMIT;
+	const selected = readableCandidates.slice(0, AUTHORIZED_ENTRIES_LIMIT);
+	const readable = await convertPathsForDisplay([pathValue, ...selected.map((entry) => entry.path)], requestLanguage(req));
+	const readableByPath = new Map(readable.map((entry) => [entry.path, entry.semanticPath]));
+	return {
+		directory: {
+			path: pathValue,
+			semanticPath: readableByPath.get(pathValue) ?? readableFallbackPath(pathValue, requestLanguage(req))
+		},
+		entries: sortAuthorizedEntries(selected.map((entry) => ({
+			...entry,
+			semanticPath: readableByPath.get(entry.path) ?? readableFallbackPath(entry.path, requestLanguage(req))
+		}))),
+		truncated
+	};
+}
+/**
+* Path conversion is a display helper, not an authorization bypass. Reject
+* arbitrary or stale paths before returning their semantic names.
+*/
+async function validatePathsForConversion(req, paths) {
+	const roots = await resolvedAuthorizedRoots();
+	const userAcl = await checkCurrentUserAcl(req, paths);
+	if (!userAcl.available) throw new AuthorizedEntriesError("fnos-user-permission-check-unavailable", 503);
+	let failure;
+	for (const path of paths) {
+		let pathStat;
+		try {
+			pathStat = await stat(path);
+		} catch {
+			failure ??= "fnos-path-not-found";
+			continue;
+		}
+		try {
+			const mode = pathStat.isDirectory() ? constants.R_OK | constants.X_OK : constants.R_OK;
+			await access(path, mode);
+		} catch {
+			failure ??= "fnos-path-not-readable";
+			continue;
+		}
+		if (!await isResolvedPathWithinAuthorizedRoots(path, roots)) {
+			failure ??= "fnos-path-not-authorized";
+			continue;
+		}
+		if (!userAcl.readable.has(path)) failure ??= "fnos-user-permission-denied";
+	}
+	if (failure !== void 0) throw authorizedEntriesErrorForValidation({
+		ok: false,
+		failure
+	});
+	return [...paths];
+}
+/** Register list/delete routes only on the DSH Web profile. */
+function registerAuthorizedDirectoryRoutes(ctx) {
+	ctx.effect(() => {
+		const authorize = (req, res) => {
+			if (trustedRequest(req)) return true;
+			json(res, 403, { error: "remote-web-origin-not-trusted" });
+			return false;
+		};
+		const routes = [
+			ctx.webServer.register({
+				kind: "exact",
+				path: FNOS_AUTHORIZED_DIRECTORIES_PATH,
+				handler: async (req, res) => {
+					if (req.method !== "GET") return json(res, 405, { error: "method not allowed" });
+					if (!authorize(req, res)) return;
+					try {
+						json(res, 200, { directories: await loadAuthorizedDirectories(req) });
+					} catch (error) {
+						errorResponse(res, error);
+					}
+				}
+			}),
+			ctx.webServer.register({
+				kind: "exact",
+				path: FNOS_AUTHORIZED_DIRECTORIES_DELETE_PATH,
+				handler: async (req, res) => {
+					if (req.method !== "POST") return json(res, 405, { error: "method not allowed" });
+					if (!authorize(req, res)) return;
+					try {
+						const path = deletePath(await readJsonBody(req));
+						if (path === void 0) return json(res, 400, { error: "invalid-authorized-directory-path" });
+						const directory = (await loadAuthorizedDirectories(req)).find((candidate) => candidate.path === path);
+						if (directory === void 0) return json(res, 409, { error: "authorized-directory-not-found" });
+						if (!directory.removable) return json(res, 409, { error: "authorized-directory-not-removable" });
+						if ((await callFnOsApi("trim.file.delSharedAccessibleFolder", { path }))?.suc === false) return json(res, 502, { error: "fnos-authorized-directory-request-failed" });
+						markAuthorizedPathRemoved(path);
+						json(res, 200, { ok: true });
+					} catch (error) {
+						errorResponse(res, error);
+					}
+				}
+			}),
+			ctx.webServer.register({
+				kind: "exact",
+				path: FNOS_PATH_CONVERSION_PATH,
+				handler: async (req, res) => {
+					if (req.method !== "POST") return json(res, 405, { error: "method not allowed" });
+					if (!authorize(req, res)) return;
+					try {
+						const paths = conversionPaths(await readJsonBody(req));
+						if (paths === void 0) return json(res, 400, { error: "invalid-fnos-paths" });
+						json(res, 200, { paths: await convertPathsForDisplay(await validatePathsForConversion(req, paths), requestLanguage(req)) });
+					} catch (error) {
+						if (error instanceof AuthorizedEntriesError) {
+							json(res, error.status, { error: error.code });
+							return;
+						}
+						errorResponse(res, error);
+					}
+				}
+			}),
+			ctx.webServer.register({
+				kind: "exact",
+				path: FNOS_PATH_OPEN_VALIDATION_PATH,
+				handler: async (req, res) => {
+					if (req.method !== "POST") return json(res, 405, { error: "method not allowed" });
+					if (!authorize(req, res)) return;
+					try {
+						const path = openPathValue(await readJsonBody(req));
+						if (path === void 0) return json(res, 400, { error: "invalid-fnos-path" });
+						const validation = await validatePathForOpen(path, req);
+						if (!validation.ok) return json(res, validation.failure === "fnos-path-not-found" ? 404 : validation.failure === "fnos-user-permission-unavailable" ? 503 : 403, { error: validation.failure });
+						json(res, 200, { ok: true });
+					} catch (error) {
+						errorResponse(res, error);
+					}
+				}
+			}),
+			ctx.webServer.register({
+				kind: "exact",
+				path: FNOS_AUTHORIZED_ENTRIES_PATH,
+				handler: async (req, res) => {
+					if (req.method !== "POST") return json(res, 405, { error: "method not allowed" });
+					if (!authorize(req, res)) return;
+					try {
+						const path = listingPathValue(await readJsonBody(req));
+						if (path === null) return json(res, 400, { error: "invalid-fnos-path" });
+						json(res, 200, await loadAuthorizedEntries(req, path));
+					} catch (error) {
+						if (error instanceof AuthorizedEntriesError) {
+							json(res, error.status, { error: error.code });
+							return;
+						}
+						errorResponse(res, error);
+					}
+				}
+			})
+		];
+		return () => {
+			for (const dispose of routes) dispose();
+		};
+	}, "dsh-fnos: authorized directory routes");
+}
+//#endregion
+//#region src/theme-contract.ts
+const FNOS_SYSTEM_THEME_FIELD = "systemTheme";
+function isFnosTheme(value) {
+	return value === "light" || value === "dark";
+}
+//#endregion
+//#region src/theme-bootstrap.ts
+/** Initial-theme helpers for the Host-side index transform. */
+/**
+* Resolve the cached preference that is safe to use before the Client tree
+* starts. Explicit DSH preferences remain authoritative and never use the
+* fnOS cache.
+*/
+function cachedFnosThemeForBoot(preference, systemTheme) {
+	if (preference !== "system" || !isFnosTheme(systemTheme)) return null;
+	return systemTheme;
+}
+/**
+* Replace the preference literal emitted by DSH's official ui-theme bootstrap.
+* The fnOS bundle is appended after ui-theme in the profile composition, so
+* the official script is already present when this transform runs.
+*/
+function injectCachedFnosTheme(html, preference, systemTheme) {
+	const cachedTheme = cachedFnosThemeForBoot(preference, systemTheme);
+	if (cachedTheme === null) return html;
+	return html.replace(/(const\s+preference\s*=\s*)"system"/, `$1${JSON.stringify(cachedTheme)}`);
+}
+//#endregion
+//#region src/index.ts
+/** Stable Host bundle name. */
+const name = "@tnnevol/dsh-fnos";
+/** Settings back the fnOS card and the cached pre-plugin theme bootstrap. */
+const FnosSettingsSchema = z.object({ [FNOS_SYSTEM_THEME_FIELD]: z.union(["light", "dark"]) });
+const FNOS_AUTHORIZED_DIRECTORIES_SETTINGS_NS = settingsNamespace(FNOS_AUTHORIZED_DIRECTORIES_SETTINGS_NAMESPACE);
+const DSH_THEME_SETTINGS_NS = settingsNamespace("ui-theme");
+/** Host services required by the fnOS settings namespace and Web routes. */
+const inject = ["webServer", "settings"];
+function apply(ctx) {
+	ctx.settings.register(FNOS_AUTHORIZED_DIRECTORIES_SETTINGS_NS, FnosSettingsSchema);
+	registerAuthorizedDirectoryRoutes(ctx);
+	ctx.inject(["webServer"], (httpCtx) => {
+		httpCtx.effect(() => httpCtx.webServer.tapIndex((html) => injectCachedFnosTheme(html, readDshThemePreference(ctx), readCachedFnosTheme(ctx))), "dsh-fnos: cached fnOS theme bootstrap");
+	});
+}
+function readDshThemePreference(ctx) {
+	const section = ctx.settings.get(DSH_THEME_SETTINGS_NS);
+	return section?.preference === "light" || section?.preference === "dark" || section?.preference === "system" ? section.preference : "system";
+}
+function readCachedFnosTheme(ctx) {
+	const section = ctx.settings.get(FNOS_AUTHORIZED_DIRECTORIES_SETTINGS_NS);
+	return isFnosTheme(section?.["systemTheme"]) ? section[FNOS_SYSTEM_THEME_FIELD] : null;
+}
+//#endregion
+export { FNOS_ACCESSIBLE_PATHS_ENV, FNOS_AUTHORIZED_DIRECTORIES_DELETE_PATH, FNOS_AUTHORIZED_DIRECTORIES_PATH, FNOS_AUTHORIZED_DIRECTORIES_SETTINGS_NAMESPACE, FNOS_AUTHORIZED_DIRECTORIES_SETTINGS_NS, FNOS_AUTHORIZED_ENTRIES_PATH, FNOS_DATA_SHARE_PATHS_ENV, FNOS_PATH_CONVERSION_PATH, FNOS_PATH_OPEN_VALIDATION_PATH, FnosSettingsSchema, accessiblePathsFromEnvironment, apply, convertPathsForDisplay, dataSharePathsFromEnvironment, gatewayUserId, inject, isAuthorizedPathForOpen, isPathWithinAuthorizedDirectory, loadAuthorizedEntries, markAuthorizedPathRemoved, mergeAuthorizedPaths, name, normalizeAuthorizedPath, normalizeAuthorizedPaths, normalizePathForAuthorization, splitPathEnvironment, validatePathForOpen };