发布 0.2.1 并完善工具边界与安全性

README.zh-CN.md

@@ -4,21 +4,23 @@
 
 一个匿名访问、自托管的浏览器本地工具箱。支持多人同时使用；除全局导航顺序外，文本、密钥、文件、图片和计算结果均只存在于各自浏览器中，不会发送到服务端。
 
-当前应用版本：`0.1.0`。
+当前应用版本：`0.2.1`。
 
 ## 内置工具
 
-- ASCII/UTF-8 与 Hex 互转
+- UTF-8 与 Hex 互转，固定路径为 `/tools/utf8-hex`
 - Base64 与 Base64 URL 编码、解码，解码结果支持 UTF-8、连续 Hex 和代码字节数组
-- AES-128-CMAC（RFC 4493）
+- AES-CMAC，支持 AES-128、AES-192 和 AES-256 密钥
 - CRC-8/16/32/64 预设与自定义参数，支持 BIN 和多 block Intel HEX
 - 固件 SHA-256 / SHA-512，支持 Intel HEX 有效数据和带地址/长度的 Block 校验头
 - RSA 2048/3072/4096 位密钥对，导出 PEM，以及可分别复制的 N/E Hex 或代码字节数组
-- 密码学安全随机数，支持连续 Hex、空格 Hex 和代码字节数组
+- 密码学安全随机数，默认 16 字节，支持连续 Hex、空格 Hex 和代码字节数组
 - JSON 格式化、压缩、校验和语法着色
 - XML 格式化、压缩、校验和语法着色
 - PNG 转多尺寸 ICO
 
+首次部署且尚未保存过自定义配置时，默认分类顺序为“编码转换 → 校验计算 → 加密计算 → 格式化 → 图像处理”。已有 `data/navigation.json` 会保留用户排序，不会因升级被默认顺序覆盖。
+
 ## 交付物与源码
 
 容器交付 ZIP 同时包含源码、测试、生产构建结果和部署文件，不是只有压缩后的网页。主要目录如下：
@@ -29,7 +31,7 @@ src/                         Vue 3 前端源码
   lib/                       可测试的纯计算与浏览器辅助逻辑
   tools/                     每个工具一个独立 Vue 组件
   workers/                   大文件计算使用的浏览器后台线程
-  views/SettingView.vue      /setting 工具管理页
+  views/SettingView.vue      /tools/setting 工具管理页
 server/                      零依赖 Node.js 静态服务和导航配置 API
 shared/tool-catalog.json     工具与分类的权威元数据目录
 shared/default-navigation.json  新部署的默认分类和工具顺序
@@ -53,7 +55,7 @@ CHANGELOG.md                 版本变更、修复和验证记录
 - 路由和左侧导航由工具目录自动生成，增加普通工具时不得手工新增路由。
 - 工具输入只在浏览器内存中处理，不得发送给服务端、遥测服务或第三方接口。
 - 服务端只持久化导航顺序，文件为 `/data/navigation.json`，写入采用临时文件和原子替换。
-- `/setting` 是固定但不公开显示的管理入口；项目没有登录、收藏、赞助或用户系统。
+- `/tools/setting` 是固定但不公开显示的管理入口；项目没有登录、收藏、赞助或用户系统。
 - 页面必须保持统一 UI，并兼容桌面端和移动端竖屏。
 - 浏览器图标与左侧品牌标记保持一致。`favicon.svg` 是现代浏览器主图标，`favicon.ico` 内含 16/32/48 像素回退图，另提供 180 像素 Apple 图标、192/512 像素 Web App 图标和 512 像素 maskable 图标。
 
@@ -65,21 +67,22 @@ CHANGELOG.md                 版本变更、修复和验证记录
 
 以下行为属于已经发布的兼容性约束。修改时必须同步实现、页面提示、自动化测试和本文档，不能只调整界面文案。
 
-- ASCII/Hex 工具按 UTF-8 字节转换文本；Hex 输入接受连续形式，或以空白、英文逗号、中文逗号分隔的片段，并允许每个片段使用可选的 `0x` 前缀。无效 UTF-8 字节必须报错，不能静默替换字符。
+- UTF-8 / Hex 工具的固定 ID 为 `utf8-hex`，路径为 `/tools/utf8-hex`。它按 UTF-8 字节转换文本；Hex 输入接受连续形式，或以空白、英文逗号、中文逗号分隔的片段，并允许每个片段使用可选的 `0x` 前缀。无效 UTF-8 字节必须报错，不能静默替换字符。
 - Base64 支持标准和 URL-safe 形式；解码结果可显示为严格 UTF-8、连续 Hex 或 `0x48, 0x9F, ...` 字节数组。无效字符、错误填充和非规范编码必须报错。
-- AES-128-CMAC 密钥必须恰好为 16 字节。密钥和 Hex 消息接受连续 Hex，或空格、换行、英文/中文逗号分隔，并允许片段使用可选的 `0x` 前缀；计算语义遵循 RFC 4493。
-- CRC 支持 BIN 和多 block Intel HEX，提供 CRC-8/16/32/64 预设，并允许自定义 `Width`、`Poly`、`Init`、`XorOut`、`RefIn` 和 `RefOut`。总 CRC 对按地址升序拼接的有效数据计算，不填充地址空洞，同时输出每个 block 的结果。
+- AES-CMAC 密钥长度可选 128、192 或 256 位，默认 128 位，并分别严格要求 16、24 或 32 字节；不自动补零或截断。密钥和 Hex 消息接受连续 Hex，或空格、换行、英文/中文逗号分隔，并允许片段使用可选的 `0x` 前缀。CMAC 标签始终为 128 位；AES-128 向量遵循 RFC 4493，AES-192/256 向量遵循 NIST SP 800-38B。
+- CRC 支持 BIN 和多 block Intel HEX，提供 CRC-8/16/32/64 预设，并允许自定义 `Width`、`Poly`、`Init`、`XorOut`、`RefIn` 和 `RefOut`。`RefIn`/`RefOut` 在页面中标为输入/输出位反转，不表示字节顺序或整个数据倒序。总 CRC 对按地址升序拼接的有效数据计算，不填充地址空洞，同时输出每个 block 的结果。
 - 固件 Hash 只接受 Intel HEX，输出 SHA-256 和 SHA-512。“有效数据”与“Block 校验头”模式的确切字节流见“固件 Hash 固定语义”；默认校验头字节序为 Big Endian。
-- RSA 只允许 2048、3072、4096 位密钥，公钥指数固定为 65537。优先使用 Web Crypto，必要时使用由 `crypto.getRandomValues` 提供随机种子的 `node-forge` 回退；公钥为 SPKI PEM，私钥为 PKCS#8 PEM，N/E 可分别显示为连续 Hex 或代码字节数组。
-- 安全随机数必须来自浏览器 `crypto.getRandomValues`，长度为 1 至 65,536 字节，支持连续 Hex、空格 Hex 和代码字节数组；切换显示格式不得重新生成随机数据。
-- JSON/XML 的格式化、压缩和校验均在浏览器本地完成。语法着色超过资源限制时只能降级为完整纯文本，不能截断结果。
+- RSA 只允许 2048、3072、4096 位密钥，公钥指数固定为 65537。优先使用 Web Crypto，只有本地提供者不可用或失败时才动态加载 `node-forge` 回退，其随机种子仍只来自 `crypto.getRandomValues`；公钥为 SPKI PEM，私钥为 PKCS#8 PEM，N/E 可分别显示为连续 Hex 或代码字节数组。
+- 安全随机数必须来自浏览器 `crypto.getRandomValues`，默认 16 字节，允许长度为 1 至 65,536 字节，支持连续 Hex、空格 Hex 和代码字节数组；切换显示格式不得重新生成随机数据。安全随机源不可用或抛错时直接失败，不使用普通伪随机回退。
+- JSON/XML 的格式化、压缩和校验均在浏览器本地完成。合法 XML 可以使用 `parsererror` 作为元素名；只把浏览器专用解析错误命名空间中的节点视为解析失败。语法着色超过资源限制时只能降级为完整纯文本，不能截断结果。
 - 文件选择、文件更换、清空、模式切换和组件卸载都可能使异步任务失效。旧 Worker、旧图像解码和旧密钥生成结果不得覆盖当前输入或已清空状态。
 
 ## 多人使用与状态边界
 
 - 每个浏览器标签页拥有独立的 Vue 组件状态、文件对象、图像对象和 Web Worker。不同用户、浏览器或标签页不会共享工具输入与结果。
 - CRC、固件 Hash、RSA、AES-CMAC、随机数、PNG/ICO、编码转换和格式化都在浏览器中执行；服务端没有工具计算接口。
-- `/setting` 保存的是所有访问者共享的导航配置。并发保存没有版本冲突合并，最后完成原子替换的请求生效。
+- `/tools/setting` 保存的是所有访问者共享的导航配置。同一服务进程会按进入导航操作队列的顺序串行处理读写，最后排队的保存生效；不提供版本冲突合并。
+- 旧导航配置中的历史工具 ID `ascii-hex` 会在读取时原位迁移为 `utf8-hex`，保留原分类和排序；新配置和应用路由只使用 `utf8-hex`。
 - 原子替换保证读取者看到完整的旧配置或新配置，不会看到写到一半的 JSON；它不保证保留多个用户各自的排序修改。
 - 已打开的页面不会实时接收其他用户保存的新顺序，刷新或重新打开后才会读取。
 - 深浅主题保存在当前浏览器同源 `localStorage` 中；系统剪贴板由操作系统管理。这两项不会改变工具计算结果。
@@ -93,10 +96,11 @@ CHANGELOG.md                 版本变更、修复和验证记录
 | CRC 固件文件 | 最大 64 MiB | 选择时拒绝，不保留旧文件结果 |
 | Intel HEX 非空记录 | 最多 500,000 条 | Worker 停止解析并显示错误 |
 | Intel HEX 数据块 | 最多 1,024 个 block | Worker 停止解析并显示错误 |
+| Intel HEX 合并后的有效数据 | 最大 64 MiB | 合并分配前拒绝，Worker 停止解析并显示错误 |
 | 固件 Hash 文件及有效数据 | 文件最大 64 MiB，有效数据最大 64 MiB | 选择或计算时拒绝 |
 | PNG 压缩文件 | 最大 32 MiB | 创建预览前拒绝 |
 | PNG 尺寸 | 单边最大 16,384 像素，总计最大 32,000,000 像素 | 浏览器解码前拒绝 |
-| 安全随机数 | 每次 1 至 65,536 字节 | 拒绝无效长度 |
+| 安全随机数 | 默认 16 字节，每次 1 至 65,536 字节 | 拒绝无效长度或不安全回退 |
 | JSON/XML 语法着色 | 最大 100,000 字符且不超过 10,000 个 token | 结果仍完整显示，但降级为纯文本以减少 DOM 节点 |
 | 导航配置请求体 | 最大 64 KiB | 服务端返回 400 |
 
@@ -139,6 +143,12 @@ docker compose down
 
 健康检查地址：`http://服务器地址:9000/healthz`
 
+### Cloudflare 反向代理与 CSP
+
+服务端在每个响应的 `Content-Security-Policy` 中放入独立的 128 位密码学随机 nonce。Cloudflare JavaScript Detections 会从源站 CSP 响应头读取该 nonce，并把它加到代理注入的脚本上，因此 Bot Fight Mode 可在不启用 `'unsafe-inline'` 的情况下与严格 CSP 共存。不得把 nonce 改为固定值，也不得为消除控制台提示而放开 `'unsafe-inline'`。
+
+项目自身不添加 Web Analytics、遥测或第三方脚本。Cloudflare Web Analytics 是部署层可选的浏览器 RUM，不是 CDN、WAF、DDoS 或 Bot 防护的必要条件；默认保持关闭时，Cloudflare 边缘流量统计仍然可用。若未来明确启用 Web Analytics，必须单独评审 CSP 外部脚本来源和“无统计/无遥测”文档契约。
+
 ## Windows Server 部署（不使用 Docker）
 
 要求安装 Git、Node.js 22.12.0 或更高版本，并使用 PowerShell 5.1 或更高版本。以下示例假设项目位于 `C:\Services\WebTools`。
@@ -206,7 +216,7 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\web-tools.ps1 update
 2. 抽象静态资源读取方式，使 Node 服务既能读取开发时的文件系统，也能读取 EXE 内嵌资源。
 3. 增加 SEA 配置、注入工具（通常为 `postject`）、`build:exe` 脚本以及 Windows x64/ARM64 分架构构建。
 4. 继续把 `navigation.json` 放在 EXE 外部的可写数据目录，默认使用 `C:\ProgramData\WebTools\data`，升级 EXE 时不得覆盖它。
-5. 增加 Windows Server 启动、端口、静态资源、`/setting`、更新替换和杀毒软件兼容性冒烟测试。
+5. 增加 Windows Server 启动、端口、静态资源、`/tools/setting`、更新替换和杀毒软件兼容性冒烟测试。
 6. 正式对外分发时补充 EXE 图标/版本资源，并考虑 Authenticode 代码签名；未签名程序可能触发 SmartScreen 警告。
 
 这项改造对源码体积影响不大，通常只是数十 KB 级的入口、资源适配和构建脚本，并增加少量开发依赖；真正明显的是发布产物。每个架构的 EXE 会包含 Node.js 运行时，常见为约 60-100 MB 未压缩、约 30-60 MB 压缩，具体随 Node 版本和资源大小变化。EXE 和中间产物必须保持在 `.gitignore` 或发布目录中，不提交到 Git，因此仓库不会明显膨胀；增加的主要成本是分架构构建、签名、测试和更新维护。
@@ -223,7 +233,7 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\web-tools.ps1 update
 管理入口不显示在页面中，直接访问：
 
 ```text
-http://服务器地址:9000/setting
+http://服务器地址:9000/tools/setting
 ```
 
 可以调整分类顺序、分类内工具顺序及工具所属分类。保存时采用同目录临时文件和原子替换。
@@ -245,10 +255,10 @@ docker compose restart web-tools
 
 ## 离线镜像
 
-若交付目录包含 `personal-web-tools-0.1.0-amd64.tar`，可直接导入：
+若交付目录包含 `personal-web-tools-0.2.1-amd64.tar`，可直接导入：
 
 ```bash
-docker load -i personal-web-tools-0.1.0-amd64.tar
+docker load -i personal-web-tools-0.2.1-amd64.tar
 docker compose up -d --no-build
 ```
 
@@ -300,7 +310,7 @@ npm run check
 npm audit --audit-level=low
 ```
 
-`npm run check` 会依次运行全部 Vitest 测试、TypeScript/Vue 类型检查和生产构建。服务端测试使用随机本地端口验证 SPA 直达路由、静态资源 404、导航 API、请求大小限制及跨站写入拦截。
+`npm run check` 会依次运行全部 Vitest 测试、TypeScript/Vue 类型检查和生产构建。服务端测试使用随机本地端口验证 SPA 直达路由、静态资源 404 与缓存策略、导航 API、请求大小限制及跨源浏览器写入拦截。
 
 自动化测试还覆盖标准算法向量、Base64 规范性、Intel HEX 记录与 block 边界、固件 Hash 与大小端 Block 头向量、PNG 头部与像素限制、导航排序纯函数、目录/图标/懒加载组件一致性，以及原子写入失败后的临时文件清理。
 
@@ -392,7 +402,7 @@ npm audit --audit-level=low
 还应在真实浏览器中检查：
 
 - 新工具的默认路径 `/tools/<id>` 可以直接打开和刷新。
-- 左侧导航、搜索和 `/setting` 正常显示新工具。
+- 左侧导航、搜索和 `/tools/setting` 正常显示新工具。
 - 已保存的旧 `navigation.json` 在服务重启并首次读取后会自动补入新工具；仅重新构建 `dist` 不会刷新已经运行的 Node 进程。
 - 桌面端和约 `390 x 844` 的移动端竖屏布局正常。
 - 浏览器控制台无错误，工具内容没有发往服务端。
@@ -438,12 +448,14 @@ AI 不应仅修改 `dist/`；必须修改源码并重新构建。不得覆盖或
 
 ## 安全边界
 
-- 无登录、无统计、无遥测、无 CDN 和第三方网络请求。
-- `/setting` 是固定但不显示的入口，不构成身份认证；直接公开到互联网时任何访问者都可能修改排序。
+- 应用代码无登录、无统计、无遥测、无 CDN 资产和第三方网络请求；部署时可在外层使用 Cloudflare 反向代理。
+- `/tools/setting` 是固定但不显示的入口，不构成身份认证；直接公开到互联网时任何访问者都可能修改排序。
 - 工具内容仅在浏览器内存中处理，默认不会持久化。
 - 容器以非 root 用户运行，根文件系统只读，全部 Linux capabilities 已移除。
 - 服务端只接受不超过 64 KiB 的导航 JSON 配置。
 - 服务端只提供静态文件、`GET/PUT /api/navigation` 和 `GET /healthz`。
 - 只有无扩展名且明确请求 HTML 的前端路由会回退到 `index.html`；缺失的 JS、CSS 和其他资源返回 404。
+- 浏览器发起的导航配置写入只接受 `Sec-Fetch-Site: same-origin`；缺少该请求头的非浏览器客户端仍可写入，因此这项检查不能替代身份认证或外层访问控制。
 - JSON API 响应使用 `Cache-Control: no-store`，避免浏览器缓存导航和健康状态。
-- 安全响应头禁止第三方脚本、跨站嵌入、摄像头、麦克风和定位权限。
+- 只有文件名带构建指纹的 `dist/assets/` 资源使用一年 `immutable` 缓存；HTML、favicon、Manifest 和其他稳定文件名资源使用 `no-cache`，更新后会重新验证。
+- 安全响应头禁止第三方脚本、跨站嵌入、摄像头、麦克风和定位权限；每个响应的 CSP 使用独立 128 位 nonce 兼容 Cloudflare JavaScript Detections，不允许 `'unsafe-inline'`。