@nsnanocat/preference-panes 1.1.1 → 1.1.2

package/README.md

@@ -1,6 +1,6 @@
 # @nsnanocat/preference-panes
 
-PreferencePanes 提供一个由 BoxJS JSON 驱动的通用设置前端，以及一个独立的代理持久化 API。业务模块只发布自己的 `/configs/{module}` 和 `/api/{module}`；通用 `/settings/**` 前端只需要安装一次。
+PreferencePanes 提供一个由 BoxJS JSON 驱动的通用设置前端，以及一个独立的代理配置与持久化 API。业务模块只发布自己的 `/configs/{module}`；通用 `/settings/**` 前端和 `/api/**` 后端分别只需要安装一次。
 
 在 Biliverse 中，Enhanced 是唯一安装 `web.js` 的模块。Global、Redirect、ADBlock 不携带 `web.js`，它们的设置页仍由同一份通用前端读取各自 BoxJS 后渲染。
 
@@ -16,7 +16,7 @@ interface MountedPreferences { destroy(): void }
 ```js
 import { mount } from "@nsnanocat/preference-panes/browser";
 
-const boxjs = await fetch("/configs/Module", {
+const boxjs = await fetch("/api/Module", {
     cache: "no-store",
     credentials: "omit",
 }).then(response => response.json());
@@ -39,29 +39,27 @@ preferences.destroy();
 - `GET /settings/assets/index.mjs`
 - `GET /settings/assets/navigation.mjs`
 
-模块页面从 URL 或 `ModuleFrame` 的模块标记取得模块名，直接读取同源 `/configs/{module}`，然后调用 `mount(boxjs)`。页面不接受 JSON/CSS 查询参数、私有请求头或兼容资源别名。
+模块页面从 URL 或 `ModuleFrame` 的模块标记取得模块名，通过同源 `/api/{module}` 读取原始 BoxJS，然后调用 `mount(boxjs)`。页面不接受 JSON/CSS 查询参数、私有请求头或兼容资源别名，也不直接访问 `/configs/**`。
 
 `api.js` 只处理：
 
 - `HEAD /api/{module}`：探测同源 `/configs/{module}`，透传状态与 `X-PreferencePanes-Version`。
-- `POST /api/{module}/get`：读取声明字段或 Settings、Caches、module 子树。
-- `POST /api/{module}/set`：写入当前 BoxJS 声明的字段。
-- `POST /api/{module}/delete`：删除声明字段或模块子树。
+- `GET /api/{module}`：原样返回同源 `/configs/{module}` 的 BoxJS JSON 与版本头。
+- `POST /api/get`：读取完整 `@root.path`。
+- `POST /api/set`：写入完整 `@root.path`。
+- `POST /api/delete`：删除完整 `@root.path` 或子树。
 
-`GET /api/{module}` 和其它未规定方法返回 `405`。API 每次动作都从 `/configs/{module}` 建立字段目录，只负责字段授权与 util `Storage` 读写，不解释控件、选项或默认值。
+模块 API 只转发业务配置；固定存储 API 不下载或解析 BoxJS。BoxJS 字段、控件、选项、默认值与写入值都由浏览器校验。
 
 ```js
-await fetch("/api/Enhanced/set", {
+await fetch("/api/set", {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-        key: "Enhanced.Settings.Home.Top_left",
-        value: "mine",
-    }),
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams([["@BiliBili.Enhanced.Settings.Home.Top_left", JSON.stringify("mine")]]),
 });
 ```
 
-页面初始化时只执行一次 `POST /api/{module}/get` 读取 Settings 子树。写入成功后仅更新当前页面快照；查看 Settings/Caches 时按需读取，清空和重置通过 delete 动作完成。
+页面初始化时只执行一次 `POST /api/get` 读取 Settings 子树。写入成功后仅更新当前页面快照；查看 Settings/Caches 时按需读取，清空和重置通过 `/api/delete` 完成。
 
 ## 宿主集成
 

package/dist/api.js

@@ -1921,11 +1921,9 @@
         return parts;
     }
 
-    const MISSING = Symbol("missing");
-
     /**
-     * PreferencePanes 后端 API，只处理模块数据和持久化请求。
-     * PreferencePanes backend API handling only module data and persistence requests.
+     * PreferencePanes 后端 API，只转发模块配置并提供通用持久化操作。
+     * PreferencePanes backend API only relaying module configurations and providing generic persistence operations.
      */
     class API {
         /**
@@ -1947,133 +1945,107 @@
         }
 
         /**
-         * 处理 `/api/{module}` 及其动作，不接管页面或静态资源。
-         * Handle `/api/{module}` and its actions without intercepting pages or static assets.
+         * 处理模块配置 API 与固定存储动作，不接管页面或静态资源。
+         * Handle module configuration APIs and fixed storage actions without intercepting pages or static assets.
          * @param {import("./index.js").SettingsRequest} request 代理请求 / Proxy request.
          * @returns {Promise<import("./index.js").SettingsResponse | undefined>} API 响应或未接管 / API response or pass-through.
          */
         async handle(request) {
             const url = new URL(request.url);
-            const match = /^\/api\/([a-zA-Z0-9_-]+)(?:\/(get|set|delete))?\/?$/.exec(url.pathname);
-            if (!match) return;
-            const [, module, action] = match;
-            const configuration = `${url.origin}/configs/${module}`;
-            switch (true) {
-                case !action && request.method === "HEAD":
-                    return this.#probe(request, configuration);
-                case Boolean(action) && request.method === "POST":
-                    return this.#action(request, module, action, configuration);
-                default:
-                    return this.#response(request, 405, { error: "Use HEAD for module probes and POST for module actions" });
-            }
+            const action = /^\/api\/(get|set|delete)\/?$/.exec(url.pathname)?.[1];
+            if (action) return this.#store(request, action);
+            const module = /^\/api\/([a-zA-Z0-9_-]+)\/?$/.exec(url.pathname)?.[1];
+            if (!module) return;
+            if (!["HEAD", "GET"].includes(request.method)) return this.#response(request, 405, { error: "Use GET or HEAD for module configuration" });
+            return this.#configuration(request, `${url.origin}/configs/${module}`);
         }
 
-        async #probe(request, configuration) {
+        /**
+         * 从同源业务配置响应模块探测或原始 BoxJS JSON。
+         * Respond to a module probe or raw BoxJS JSON from the same-origin business configuration.
+         * @param {import("./index.js").SettingsRequest} request 代理请求 / Proxy request.
+         * @param {string} configuration 同源配置地址 / Same-origin configuration URL.
+         * @returns {Promise<import("./index.js").SettingsResponse>} 配置响应 / Configuration response.
+         */
+        async #configuration(request, configuration) {
             let result;
             try {
-                result = await fetch({ url: configuration, method: "HEAD", timeout: 5000, headers: { Accept: "application/json" } });
+                result = await fetch({ url: configuration, method: request.method, timeout: 5000, headers: { Accept: "application/json" } });
             } catch (error) {
                 return this.#response(request, 502, { error: error.message });
             }
             const version = this.#header(result.headers, "x-preferencepanes-version");
-            return this.#response(request, result.statusCode ?? result.status, undefined, version ? { "X-PreferencePanes-Version": version } : {});
-        }
-
-        async #action(request, module, action, configuration) {
-            const payload = this.#jsonBody(request);
-            const target = await this.#load(module, configuration);
-            switch (action) {
-                case "get": {
-                    const value = Storage.getItem(payload?.scope ? this.#scopePath(target, payload.scope) : this.#storagePath(target, payload?.key), MISSING);
-                    return value === MISSING ? this.#response(request, 404, { error: "Stored path does not exist" }) : this.#response(request, 200, value);
-                }
-                case "set":
-                    if (!Object.hasOwn(payload ?? {}, "value")) throw Object.assign(new TypeError("A value is required"), { status: 400 });
-                    if (!Storage.setItem(this.#storagePath(target, payload.key), payload.value)) throw new Error("Storage write failed");
-                    return this.#response(request, 200, { saved: true });
-                case "delete": {
-                    const path = payload?.scope ? this.#scopePath(target, payload.scope) : this.#storagePath(target, payload?.key);
-                    if (!Storage.removeItem(path)) throw new Error("Storage write failed");
-                    return this.#response(request, 200, { deleted: true });
-                }
-            }
+            const contentType = this.#header(result.headers, "content-type") ?? "application/json; charset=utf-8";
+            return {
+                status: result.statusCode ?? result.status,
+                headers: { "Content-Type": contentType, "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff", ...(version ? { "X-PreferencePanes-Version": version } : {}) },
+                body: request.method === "HEAD" ? "" : typeof result.body === "string" ? result.body : new TextDecoder().decode(result.body),
+            };
         }
 
-        async #load(module, configuration) {
-            let result;
+        /**
+         * 使用唯一 form 字段中的完整 @root.path 执行存储操作。
+         * Execute a storage operation using the complete @root.path from the sole form field.
+         * @param {import("./index.js").SettingsRequest} request 代理请求 / Proxy request.
+         * @param {"get" | "set" | "delete"} action 存储动作 / Storage action.
+         * @returns {import("./index.js").SettingsResponse} 操作响应 / Operation response.
+         */
+        #store(request, action) {
+            const reply = (status, data) => this.#response(request, status, data);
+            if (request.method !== "POST") return reply(405, { error: "Use POST with a form body" });
+            const headers = Object.fromEntries(Object.entries(request.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
+            if (headers["content-type"]?.split(";")[0].trim().toLowerCase() !== "application/x-www-form-urlencoded") return reply(415, { error: "Expected application/x-www-form-urlencoded" });
+            if (typeof request.body !== "string" || request.body.length > 65536) return reply(400, { error: "Expected a form body up to 65536 characters" });
+            let parts, value;
             try {
-                result = await fetch({ url: configuration, method: "GET", timeout: 5000, headers: { Accept: "application/json" } });
+                const fields = request.body.split("&");
+                if (fields.length !== 1) throw new TypeError("Send exactly one storage key");
+                const separator = fields[0].indexOf("=");
+                if (separator < 0) throw new TypeError("Expected @root.path=value");
+                const key = decodeURIComponent(fields[0].slice(0, separator).replace(/\+/g, " "));
+                value = decodeURIComponent(fields[0].slice(separator + 1).replace(/\+/g, " "));
+                if (!key.startsWith("@")) throw new TypeError("Storage keys must start with @");
+                parts = validatePathParts(key.slice(1).split("."));
+                if (parts.length < 2) throw new TypeError("Specify a storage root and child path");
             } catch (error) {
-                throw Object.assign(new Error(`Configuration request failed: ${error.message}`), { status: 502 });
+                return reply(400, { error: error.message });
             }
-            const status = result.statusCode ?? result.status;
-            if (status !== 200) throw Object.assign(new Error(`Configuration HTTP ${status}`), { status });
-            try {
-                const body = typeof result.body === "string" ? result.body : new TextDecoder().decode(result.body);
-                const boxjs = JSON.parse(body);
-                const apps = Array.isArray(boxjs) ? [{ settings: boxjs }] : (boxjs.apps ?? [boxjs]);
-                if (!Array.isArray(apps)) throw new TypeError("Expected BoxJS apps array");
-                const entries = [];
-                let storageKey;
-                for (const app of apps) {
-                    if (!app || !Array.isArray(app.settings)) throw new TypeError("Expected BoxJS settings array");
-                    for (const entry of app.settings) {
-                        if (typeof entry.id !== "string") throw new TypeError("BoxJS settings require string IDs");
-                        if (!entry.id.startsWith("@")) {
-                            if (Array.isArray(boxjs)) throw new TypeError("BoxJS settings require @root.path IDs");
-                            continue;
-                        }
-                        const [root, ...parts] = entry.id.slice(1).split(".");
-                        if (!root || root.startsWith("@") || parts.length < 2) throw new TypeError("A BoxJS setting must be below a literal storage root and module");
-                        validatePathParts(parts);
-                        if (parts[0] !== module) continue;
-                        if (storageKey && storageKey !== root) throw new TypeError(`A module must use one storage root: ${module}`);
-                        storageKey = root;
-                        entries.push(entry);
-                    }
+            if (action === "set") {
+                try {
+                    value = JSON.parse(value);
+                } catch (error) {
+                    if (!(error instanceof SyntaxError)) throw error;
                 }
-                if (!entries.length) throw new TypeError(`No BoxJS settings for module: ${module}`);
-                return { entries, module, storageKey, version: this.#header(result.headers, "x-preferencepanes-version") };
-            } catch (error) {
-                throw Object.assign(new Error(`Invalid BoxJS: ${error.message}`), { status: 422 });
             }
-        }
-
-        #jsonBody(request) {
-            const headers = Object.fromEntries(Object.entries(request.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
-            if (headers["content-type"]?.split(";")[0].trim().toLowerCase() !== "application/json") throw Object.assign(new TypeError("Expected application/json"), { status: 415 });
-            if (typeof request.body !== "string" || request.body.length > 65536) throw Object.assign(new TypeError("Expected a JSON body up to 65536 characters"), { status: 400 });
+            const [storageKey, ...path] = parts;
             try {
-                return JSON.parse(request.body);
+                const root = Storage.getItem(storageKey, {});
+                if (!isRecord(root)) throw new TypeError("Stored root must be an object");
+                const parent = storageParent(root, path, action === "set");
+                const key = path.at(-1);
+                switch (action) {
+                    case "get": {
+                        const result = parent ? Lodash.get(parent, [key]) : undefined;
+                        return result === undefined ? reply(404, { error: "Stored path does not exist" }) : reply(200, result);
+                    }
+                    case "set":
+                        Lodash.set(parent, [key], value);
+                        break;
+                    case "delete":
+                        if (parent) Lodash.unset(parent, [key]);
+                        break;
+                }
+                if (!Storage.setItem(storageKey, root)) throw new Error("Storage write failed");
+                return reply(200, action === "set" ? { saved: true } : { deleted: true });
             } catch (error) {
-                throw Object.assign(error, { status: 400 });
-            }
-        }
-
-        #storagePath(target, key) {
-            if (typeof key !== "string") throw Object.assign(new TypeError("A BoxJS field path is required"), { status: 400 });
-            const path = `@${target.storageKey}.${key}`;
-            if (!target.entries.some(entry => entry.id === path)) throw Object.assign(new TypeError(`Unknown BoxJS field: ${key}`), { status: 400 });
-            return path;
-        }
-
-        #scopePath(target, scope) {
-            switch (scope) {
-                case "settings":
-                    return `@${target.storageKey}.${target.module}.Settings`;
-                case "caches":
-                    return `@${target.storageKey}.${target.module}.Caches`;
-                case "module":
-                    return `@${target.storageKey}.${target.module}`;
-                default:
-                    throw Object.assign(new TypeError("Scope must be settings, caches or module"), { status: 400 });
+                return reply(500, { error: error.message });
             }
         }
 
-        #response(request, status, body, extraHeaders = {}) {
+        #response(request, status, body) {
             return {
                 status,
-                headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff", ...extraHeaders },
+                headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" },
                 body: request.method === "HEAD" ? "" : JSON.stringify(body),
             };
         }
@@ -2084,6 +2056,44 @@
         }
     }
 
+    /**
+     * 判断存储根是否为普通对象。
+     * Determine whether a storage root is a plain object.
+     * @param {unknown} value 待检查值 / Value to inspect.
+     * @returns {boolean} 是否为普通对象 / Whether this is a plain object.
+     */
+    function isRecord(value) {
+        return value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype;
+    }
+
+    /**
+     * 遍历父路径，并解码旧存储中的 JSON 字符串中间节点。
+     * Traverse parent paths and decode legacy intermediate nodes stored as JSON strings.
+     * @param {Record<string, unknown>} root 存储根 / Storage root.
+     * @param {string[]} parts 完整路径 / Complete path.
+     * @param {boolean} create 是否创建缺失节点 / Whether to create missing parents.
+     * @returns {object | undefined} 父节点或 undefined / Parent node or undefined.
+     */
+    function storageParent(root, parts, create) {
+        let parent = root;
+        for (const part of parts.slice(0, -1)) {
+            let next = Lodash.get(parent, [part]);
+            switch (typeof next) {
+                case "undefined":
+                    if (!create) return;
+                    next = {};
+                    break;
+                case "string":
+                    next = JSON.parse(next);
+                    break;
+            }
+            if (!isRecord(next) && !Array.isArray(next)) throw new TypeError("Stored parent is not an object or array");
+            Lodash.set(parent, [part], next);
+            parent = next;
+        }
+        return parent;
+    }
+
     new API().run();
 
 })();

package/dist/module/index.html

@@ -9,6 +9,6 @@
     </head>
     <body>
         <main id="preferences"></main>
-        <script type="module" src="/settings/assets/index.mjs?v=1.1.1"></script>
+        <script type="module" src="/settings/assets/index.mjs?v=1.1.2"></script>
     </body>
 </html>