dsh-mobile 0.4.0 → 0.4.1

package/lib/index.d.mts

@@ -436,8 +436,10 @@ declare class MobileExtensionError extends Error {
   constructor(code: string, message: string, status?: number);
 }
 /** One host-side action exposed by an extension. */
+type CallableActionInput = (value?: never, options?: never) => unknown;
 interface MobileHostAction {
-  readonly input?: {
+  /** A callable Schemastery schema or an adapter exposing parse(). */
+  readonly input?: CallableActionInput | {
     parse(value: unknown): unknown;
   };
   readonly run: (context: MobileActionContext, input: unknown) => unknown | Promise<unknown>;

package/lib/index.mjs

@@ -389,7 +389,7 @@ var AccessController = class {
 };
 //#endregion
 //#region src/network.ts
-function parseIpv4(address) {
+function parseIpv4$1(address) {
 	const parts = address.split(".");
 	if (parts.length !== 4) throw new Error(`invalid IPv4 address ${JSON.stringify(address)}`);
 	let value = 0n;
@@ -403,7 +403,7 @@ function parseIpv4(address) {
 }
 function parseIpv6Part(part, address) {
 	if (part.includes(".")) {
-		const ipv4 = parseIpv4(part);
+		const ipv4 = parseIpv4$1(part);
 		return [Number(ipv4 >> 16n & 65535n), Number(ipv4 & 65535n)];
 	}
 	if (!/^[\da-f]{1,4}$/iu.test(part)) throw new Error(`invalid IPv6 address ${JSON.stringify(address)}`);
@@ -433,12 +433,12 @@ function parseIp(address) {
 	const mapped = mappedIpv4(unwrapped);
 	if (mapped !== void 0) return {
 		bits: 32,
-		value: parseIpv4(mapped)
+		value: parseIpv4$1(mapped)
 	};
 	const version = isIP(unwrapped.split("%", 1)[0] ?? unwrapped);
 	if (version === 4) return {
 		bits: 32,
-		value: parseIpv4(unwrapped)
+		value: parseIpv4$1(unwrapped)
 	};
 	if (version === 6) return {
 		bits: 128,
@@ -1079,6 +1079,46 @@ var MobileAccessGatewayController = class {
 	}
 };
 //#endregion
+//#region src/local-admin-host.ts
+/** Browser-safe desktop-admin Host checks. Do not import Node APIs here. */
+function unwrapBrackets(hostname) {
+	return hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+}
+function parseIpv4(hostname) {
+	const parts = hostname.split(".");
+	if (parts.length !== 4) return void 0;
+	const octets = [];
+	for (const part of parts) {
+		if (!/^(?:0|[1-9]\d{0,2})$/u.test(part)) return void 0;
+		const value = Number(part);
+		if (value > 255) return void 0;
+		octets.push(value);
+	}
+	return octets;
+}
+function isLoopbackIpv4(octets) {
+	return octets[0] === 127;
+}
+function isPrivateIpv4(octets) {
+	return octets[0] === 10 || octets[0] === 172 && octets[1] >= 16 && octets[1] <= 31 || octets[0] === 192 && octets[1] === 168;
+}
+function isLinkLocalIpv4(octets) {
+	return octets[0] === 169 && octets[1] === 254;
+}
+/**
+* Hostnames that may appear on the DSH desktop admin surface.
+* Loopback, RFC1918, and IPv4 link-local are accepted. Public IPs,
+* CGNAT, and arbitrary DNS names stay rejected so DNS rebinding
+* cannot reach `/api/mobile-access`.
+*/
+function isLocalAdminHostname(hostname) {
+	const host = unwrapBrackets(hostname).trim().toLowerCase();
+	if (host === "localhost" || host === "::1") return true;
+	const octets = parseIpv4(host);
+	if (octets === void 0) return false;
+	return isLoopbackIpv4(octets) || isPrivateIpv4(octets) || isLinkLocalIpv4(octets);
+}
+//#endregion
 //#region src/http-security.ts
 const DEVICE_COOKIE = "dsh_ma_device";
 const SESSION_COOKIE = "dsh_ma_session";
@@ -1122,26 +1162,43 @@ function parseRequestTarget(raw) {
 		search: parsed.search
 	});
 }
-/** Set the gateway-owned browser protections and non-cacheability. */
-function setSecurityHeaders(response, tls) {
+/**
+* The frame sources a proxied GUI document may embed: its own routes, blob:
+* (the PDF viewer's object URL) and external http(s) pages (the sidebar
+* browser tab). The framed document runs in the tab's existing sandbox
+* (opaque origin, no same-origin privileges), so this does not hand the
+* embedded page anything it did not already have.
+*/
+const PROXIED_FRAME_SRC = "frame-src 'self' blob: https: http:";
+/**
+* Set the gateway browser protections and non-cacheability.
+* @param response - the response to decorate.
+* @param tls - whether the connection is TLS (adds HSTS).
+* @param framing - the framing policy; defaults to the strict gateway one, so
+*   every existing call site keeps refusing to be framed. Only the two PROXIED
+*   forwarders pass `'proxied'`.
+*/
+function setSecurityHeaders(response, tls, framing = "gateway") {
+	const proxied = framing === "proxied";
 	response.setHeader("Cache-Control", "no-store");
 	response.setHeader("Content-Security-Policy", [
 		"default-src 'self'",
 		"base-uri 'none'",
 		"object-src 'none'",
-		"frame-ancestors 'none'",
+		proxied ? "frame-ancestors 'self'" : "frame-ancestors 'none'",
 		"form-action 'self'",
 		"script-src 'self' 'unsafe-inline' 'unsafe-eval'",
 		"style-src 'self' 'unsafe-inline'",
 		"img-src 'self' data: blob:",
 		"font-src 'self' data:",
 		"connect-src 'self'",
-		"worker-src 'self' blob:"
+		"worker-src 'self' blob:",
+		...proxied ? [PROXIED_FRAME_SRC] : []
 	].join("; "));
 	response.setHeader("Permissions-Policy", "camera=(), microphone=(), geolocation=(), payment=(), usb=()");
 	response.setHeader("Referrer-Policy", "no-referrer");
 	response.setHeader("X-Content-Type-Options", "nosniff");
-	response.setHeader("X-Frame-Options", "DENY");
+	response.setHeader("X-Frame-Options", proxied ? "SAMEORIGIN" : "DENY");
 	response.setHeader("Cross-Origin-Resource-Policy", "same-origin");
 	if (tls) response.setHeader("Strict-Transport-Security", "max-age=31536000");
 }
@@ -1238,7 +1295,7 @@ function localAuthority(header) {
 function assertLocalAdminTrust(request, requireBrowserOrigin) {
 	if (request.socket.remoteAddress === void 0 || !isLoopbackAddress(request.socket.remoteAddress)) throw new HttpError(403, "forbidden");
 	const host = localAuthority(request.headers.host);
-	if (host === void 0 || host.hostname !== "localhost" && !isLoopbackAddress(host.hostname)) throw new HttpError(403, "forbidden");
+	if (host === void 0 || !isLocalAdminHostname(host.hostname)) throw new HttpError(403, "forbidden");
 	const site = request.headers["sec-fetch-site"];
 	if (site !== void 0 && site !== "same-origin" && site !== "none") throw new HttpError(403, "forbidden");
 	const origin = request.headers.origin;
@@ -1249,7 +1306,8 @@ function assertLocalAdminTrust(request, requireBrowserOrigin) {
 		if (error instanceof HttpError) throw error;
 		throw new HttpError(403, "forbidden");
 	}
-	if (requireBrowserOrigin && site !== void 0 && (origin === void 0 || site !== "same-origin")) throw new HttpError(403, "forbidden");
+	if (requireBrowserOrigin && origin === void 0) throw new HttpError(403, "forbidden");
+	if (requireBrowserOrigin && site !== void 0 && site !== "same-origin") throw new HttpError(403, "forbidden");
 }
 //#endregion
 //#region src/version.ts
@@ -1641,6 +1699,12 @@ function combineSignalLifetime(first, second) {
 		cleanup
 	};
 }
+/** Validate and normalize an action input through either supported schema form. */
+function parseActionInput(schema, input) {
+	if (schema === void 0) return input;
+	if (typeof schema === "function") return schema(input);
+	return schema.parse(input) ?? input;
+}
 /** Host registry and service consumed by both npm plugins and local extensions. */
 var MobileAccessService = class extends Service {
 	registered = /* @__PURE__ */ new Map();
@@ -1772,9 +1836,9 @@ var MobileAccessService = class extends Service {
 		if (extension === void 0) throw new MobileExtensionError("extension_not_found", "extension not found", 404);
 		const action = ("host" in extension ? extension.host : extension).actions?.[actionName];
 		if (action === void 0) throw new MobileExtensionError("action_not_found", "action not found", 404);
-		let parsed = input;
+		let parsed;
 		try {
-			parsed = action.input?.parse(input) ?? input;
+			parsed = parseActionInput(action.input, input);
 		} catch {
 			throw new MobileExtensionError("invalid_action_input", "action input is invalid", 400);
 		}
@@ -3766,7 +3830,7 @@ var MobileAccessGateway = class {
 			delete headers["content-length"];
 			delete headers["content-encoding"];
 			delete headers.etag;
-			setSecurityHeaders(response, this.tlsEnabled);
+			setSecurityHeaders(response, this.tlsEnabled, "proxied");
 			response.writeHead(200, {
 				...headers,
 				"Content-Type": "text/html; charset=utf-8",
@@ -4018,7 +4082,7 @@ var MobileAccessGateway = class {
 				}
 				bodyDone.catch(reject);
 			});
-			setSecurityHeaders(response, this.tlsEnabled);
+			setSecurityHeaders(response, this.tlsEnabled, "proxied");
 			const headers = sanitizeResponseHeaders(proxied.headers, this.config.upstreamOrigin);
 			const cacheControl = revisionedStaticCacheControl(request$2);
 			if (cacheControl !== void 0) headers["cache-control"] = cacheControl;
@@ -6283,11 +6347,11 @@ const MOBILE_CUSTOMIZATION_GUIDE_BODY = `你在为用户定制 DSH Mobile 的手
 2. 电脑端能力 —— 手机需要读电脑文件、执行命令或访问硬件时，创建扩展：
    - 目录：$DSH_HOME/mobile-access/extensions/<id>/，id 用小写字母数字和连字符（如 media-remote）
    - extension.json：{"schemaVersion":1,"id":"<id>","name":"显示名","version":"0.1.0","description":"说明"}
-   - host.mjs：电脑端 Node.js 代码（可信本地代码，可读写文件、执行命令）。导出默认函数 (api) => { ... }，用 api.action('名称', { input, run }) 注册动作、api.route({ method, path, handle }) 注册路由、api.effect(fn) 注册清理
+   - host.mjs：电脑端 Node.js 代码（可信本地代码，可读写文件、执行命令）。导出默认函数 (api) => { ... }，用 api.action('名称', { input, run }) 注册动作、api.route({ method, path, handle }) 注册路由、api.effect(fn) 注册清理。input 可以直接使用 api.schema.object(...) 等 Schemastery schema，也可以传入带 parse(value) 的适配器；两种形式都会在动作执行前校验并规范化输入。
    - mobile.js：手机端脚本，用 window.dshMobile.define({ apiVersion:1, id:'<id>', activate(api) { ... } })，activate 返回清理函数
    - mobile.css：手机端样式（可选）
    - assets/：手机端静态资源（可选）
-   - mobile.js 里用 api.host.invoke('动作名', 输入) 调 host.mjs 的 action，api.host.fetch('/路由路径') 调 route，api.host.assetUrl('相对路径') 生成与当前版本绑定的资源地址
+   - mobile.js 里用 api.host.invoke('动作名', 输入) 调 host.mjs 的 action（请求会按 application/json 发送），api.host.fetch('/路由路径') 调 route，api.host.assetUrl('相对路径') 生成与当前版本绑定的资源地址
    - 也可以先用命令生成模板：dsh plugin --profile web exec dsh-mobile extension create <id> --name "<名称>"，再在模板上改
 
 安全约束：
@@ -8803,6 +8867,8 @@ const VIRTUAL_INTERFACE_MARKERS = [
 	"wsl",
 	"zerotier"
 ];
+/** Route inspection is advisory; never let a system command hold setup open indefinitely. */
+const ROUTE_COMMAND_TIMEOUT_MS = 5e3;
 function requiredString(value, name) {
 	if (typeof value !== "string" || value.length === 0) throw new Error(`${name} must be a non-empty string`);
 	return value;
@@ -8872,7 +8938,7 @@ function likelyVirtualInterface(name) {
 async function runRouteCommand(file, args) {
 	return (await execFileText(file, [...args], {
 		encoding: "utf8",
-		windowsHide: true
+		timeout: ROUTE_COMMAND_TIMEOUT_MS
 	})).stdout;
 }
 function uniqueLines(output) {