docs: 更新 UX 本地身份配置流程与对接说明

docs/UX-授权端接口说明.md

@@ -1,71 +1,75 @@
 # UX 授权端接口说明
 
-本文档描述当前 UX 服务端实现的授权对接接口与职责边界。
+本文档描述 UX 服务当前定位：**仅提供底层密码学能力，不维护业务状态**。
 
 ## 1. 职责边界
 
-- UX **只与工具箱交互**（HTTP RPC），不直接与手机 App 交互。
-- 手机 App 仅承担扫码和与管理平台联网通信。
-- 报告签名流程由工具箱上传原始 ZIP 到 UX，UX 返回已签名 ZIP。
+- UX 只提供加密、解密、签名、ZIP 打包能力
+- UX 不持有设备/任务等业务主数据，不读取业务数据库
+- 调用方（工具箱）负责提供业务上下文与密钥材料
 
-## 2. 设备注册
+## 2. 核心接口
 
-`device.register`
+### 2.0 `config.get` / `config.setLicence`
 
-- 输入：`licence`、`platformPublicKey`
-- UX 在本机采集设备特征并计算 `fingerprint`
-- UX 将 `licence + fingerprint + 公钥 + PGP 密钥对` 持久化到数据库
+- `config.get`：读取本地配置（`licence`、`fingerprint`）
+- `config.setLicence`：写入本地 `licence`
+- 说明：`fingerprint` 由 UX 本机计算并持久化，不由调用方传入
 
-## 3. 核心加密接口
+### 2.1 `crypto.encryptDeviceInfo`
 
-### 3.1 设备授权二维码密文
+- 输入：`platformPublicKey`
+- 输出：`encrypted`（Base64）
+- 说明：读取本地 `licence`/`fingerprint` 组装 JSON 后执行 RSA-OAEP 加密
 
-`crypto.encryptDeviceInfo`
+### 2.2 `crypto.decryptTask`
 
-- 使用平台公钥 RSA-OAEP 加密：`{ licence, fingerprint }`
-- 返回 Base64 密文（工具箱用于生成二维码）
+- 输入：`encryptedData`
+- 输出：`decrypted`（明文字符串）
+- 说明：使用本地 `licence`/`fingerprint` 推导 `SHA256(licence + fingerprint)` 作为 AES-GCM 密钥
 
-### 3.2 任务二维码解密
+### 2.3 `crypto.encryptSummary`
 
-`crypto.decryptTask`
+- 输入：`salt`、`plaintext`
+- 输出：`encrypted`（Base64）
+- 说明：使用本地 `licence`/`fingerprint` 做 HKDF-SHA256 + AES-256-GCM 加密
 
-- 密钥：`SHA256(licence + fingerprint)`
-- 算法：AES-256-GCM
-- 输入：任务二维码中的 Base64 密文
-- 输出：任务 JSON
+### 2.4 `crypto.signAndPackReport`
 
-### 3.3 摘要二维码加密
+- 输入：
+  - `rawZip`（multipart 文件）
+  - `pgpPrivateKey`
+  - `signingContext`
+  - `summaryJson`
+  - `outputFileName`（可选）
+- 输出：签名后 ZIP 文件（二进制，`application/zip`）
 
-`crypto.encryptSummary`
+`summary.json` 由 UX 生成，结构为：
 
-- 密钥派生：HKDF-SHA256
-  - `ikm = licence + fingerprint`
-  - `salt = taskId`
-  - `info = "inspection_report_encryption"`
-- 算法：AES-256-GCM
-- 输出：`{ taskId, encrypted }` JSON（工具箱用于生成二维码）
+```json
+{
+  "deviceSignature": "Base64...",
+  "signingContext": "...",
+  "payload": { "...": "调用方 summaryJson" },
+  "timestamp": 1734571234567
+}
+```
 
-### 3.4 原始 ZIP 签名打包（最终报告）
+签名输出 ZIP 固定包含：
 
-`crypto.signAndPackReport`
+- `summary.json`
+- `META-INF/manifest.json`
+- `META-INF/signature.asc`
 
-- 输入：`rawZip`（`multipart/form-data` 文件字段） + `taskId` + `inspectionId` + `enterpriseId` + `summary`
-- UX 在服务端完成：
-  1. 校验并解包原始 ZIP
-  2. 计算文件 SHA-256
-  3. HKDF + HMAC 生成 `deviceSignature`
-  4. 生成 `summary.json`
-  5. 生成 `META-INF/manifest.json`
-  6. OpenPGP 分离签名生成 `META-INF/signature.asc`
-  7. 重新打包为 signed ZIP
-- 输出：签名后 ZIP 文件（二进制响应，`application/zip`）
+## 3. ZIP 安全约束
 
-## 4. 安全约束（签名打包）
+- 拒绝危险路径（防 Zip Slip）
+- 原始 ZIP ≤ `50 MiB`
+- 单个文件 ≤ `20 MiB`
+- 总解压后大小 ≤ `60 MiB`
+- ZIP 条目数量 ≤ `64`
 
-- 拒绝危险 ZIP 路径（防 Zip Slip）
-- 限制原始 ZIP 和单文件大小
-- 强制存在以下文件：
-  - `assets.json`
-  - `vulnerabilities.json`
-  - `weakPasswords.json`
-  - `漏洞评估报告*.html`
+## 4. OpenAPI
+
+- 文档：`/api/docs`
+- 规范：`/api/spec.json`