docs: remove outdated UX API docs (superseded by OpenAPI /api/docs)
This commit is contained in:
@@ -1,75 +0,0 @@
|
|||||||
# UX 授权端接口说明
|
|
||||||
|
|
||||||
本文档描述 UX 服务当前定位：**仅提供底层密码学能力，不维护业务状态**。
|
|
||||||
|
|
||||||
## 1. 职责边界
|
|
||||||
|
|
||||||
- UX 只提供加密、解密、签名、ZIP 打包能力
|
|
||||||
- UX 不持有设备/任务等业务主数据，不读取业务数据库
|
|
||||||
- 调用方（工具箱）负责提供业务上下文与密钥材料
|
|
||||||
|
|
||||||
## 2. 核心接口
|
|
||||||
|
|
||||||
### 2.0 `config.get` / `config.setLicence`
|
|
||||||
|
|
||||||
- `config.get`：读取本地配置（`licence`、`fingerprint`）
|
|
||||||
- `config.setLicence`：写入本地 `licence`
|
|
||||||
- 说明：`fingerprint` 由 UX 本机计算并持久化，不由调用方传入
|
|
||||||
|
|
||||||
### 2.1 `crypto.encryptDeviceInfo`
|
|
||||||
|
|
||||||
- 输入：`platformPublicKey`
|
|
||||||
- 输出：`encrypted`（Base64）
|
|
||||||
- 说明：读取本地 `licence`/`fingerprint` 组装 JSON 后执行 RSA-OAEP 加密
|
|
||||||
|
|
||||||
### 2.2 `crypto.decryptTask`
|
|
||||||
|
|
||||||
- 输入：`encryptedData`
|
|
||||||
- 输出：`decrypted`（明文字符串）
|
|
||||||
- 说明：使用本地 `licence`/`fingerprint` 推导 `SHA256(licence + fingerprint)` 作为 AES-GCM 密钥
|
|
||||||
|
|
||||||
### 2.3 `crypto.encryptSummary`
|
|
||||||
|
|
||||||
- 输入：`salt`、`plaintext`
|
|
||||||
- 输出：`encrypted`（Base64）
|
|
||||||
- 说明：使用本地 `licence`/`fingerprint` 做 HKDF-SHA256 + AES-256-GCM 加密
|
|
||||||
|
|
||||||
### 2.4 `crypto.signAndPackReport`
|
|
||||||
|
|
||||||
- 输入：
|
|
||||||
- `rawZip`（multipart 文件）
|
|
||||||
- `pgpPrivateKey`
|
|
||||||
- `signingContext`
|
|
||||||
- `summaryJson`
|
|
||||||
- `outputFileName`（可选）
|
|
||||||
- 输出：签名后 ZIP 文件（二进制，`application/zip`）
|
|
||||||
|
|
||||||
`summary.json` 由 UX 生成，结构为：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"deviceSignature": "Base64...",
|
|
||||||
"signingContext": "...",
|
|
||||||
"payload": { "...": "调用方 summaryJson" },
|
|
||||||
"timestamp": 1734571234567
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
签名输出 ZIP 固定包含：
|
|
||||||
|
|
||||||
- `summary.json`
|
|
||||||
- `META-INF/manifest.json`
|
|
||||||
- `META-INF/signature.asc`
|
|
||||||
|
|
||||||
## 3. ZIP 安全约束
|
|
||||||
|
|
||||||
- 拒绝危险路径（防 Zip Slip）
|
|
||||||
- 原始 ZIP ≤ `50 MiB`
|
|
||||||
- 单个文件 ≤ `20 MiB`
|
|
||||||
- 总解压后大小 ≤ `60 MiB`
|
|
||||||
- ZIP 条目数量 ≤ `64`
|
|
||||||
|
|
||||||
## 4. OpenAPI
|
|
||||||
|
|
||||||
- 文档：`/api/docs`
|
|
||||||
- 规范：`/api/spec.json`
|
|
||||||
@@ -1,84 +0,0 @@
|
|||||||
# 第三方 OpenAPI 对接指南
|
|
||||||
|
|
||||||
本文档用于第三方系统对接 UX 底层能力服务。
|
|
||||||
|
|
||||||
## 1. 文档入口
|
|
||||||
|
|
||||||
- OpenAPI 文档（Scalar）：`/api/docs`
|
|
||||||
- OpenAPI 规范（JSON）：`/api/spec.json`
|
|
||||||
|
|
||||||
本地开发环境示例：
|
|
||||||
|
|
||||||
- `http://localhost:3000/api/docs`
|
|
||||||
- `http://localhost:3000/api/spec.json`
|
|
||||||
|
|
||||||
## 2. 服务边界
|
|
||||||
|
|
||||||
UX 仅提供底层加密/解密/签名能力，不维护业务实体（设备、任务、组织等）。
|
|
||||||
|
|
||||||
- 调用方负责提供业务上下文与必要签名材料（如 `platformPublicKey`、`pgpPrivateKey`）
|
|
||||||
- 调用方负责业务字段定义与存储
|
|
||||||
|
|
||||||
## 3. 核心接口
|
|
||||||
|
|
||||||
- `POST /api/config/get`
|
|
||||||
- operationId: `configGet`
|
|
||||||
- 作用：读取 UX 本地 `licence` 与 `fingerprint`
|
|
||||||
|
|
||||||
- `POST /api/config/set-licence`
|
|
||||||
- operationId: `configSetLicence`
|
|
||||||
- 作用：设置 UX 本地 `licence`（`fingerprint` 由 UX 本机计算并持久化）
|
|
||||||
|
|
||||||
- `POST /api/crypto/encrypt-device-info`
|
|
||||||
- operationId: `encryptDeviceInfo`
|
|
||||||
- 作用：使用本地身份（licence/fingerprint）与输入 `platformPublicKey` 生成授权密文
|
|
||||||
|
|
||||||
- `POST /api/crypto/decrypt-task`
|
|
||||||
- operationId: `decryptTask`
|
|
||||||
- 作用：基于 `SHA256(licence+fingerprint)` 解密 AES-GCM 密文
|
|
||||||
|
|
||||||
- `POST /api/crypto/encrypt-summary`
|
|
||||||
- operationId: `encryptSummary`
|
|
||||||
- 作用：基于 HKDF + AES-GCM 加密任意明文
|
|
||||||
|
|
||||||
- `POST /api/crypto/sign-and-pack-report`
|
|
||||||
- operationId: `signAndPackReport`
|
|
||||||
- 作用：上传原始 ZIP，生成 `summary.json` + `META-INF/manifest.json` + `META-INF/signature.asc`，返回签名后 ZIP 文件（二进制）
|
|
||||||
|
|
||||||
## 4. 文件上传接口（signAndPackReport）
|
|
||||||
|
|
||||||
调用顺序建议：
|
|
||||||
|
|
||||||
1. 先调用 `POST /api/config/set-licence` 写入本地 `licence`
|
|
||||||
2. 调用 `POST /api/config/get` 确认 `fingerprint` 已存在
|
|
||||||
3. 再调用各 `crypto/*` 能力接口
|
|
||||||
|
|
||||||
请求使用 `multipart/form-data`：
|
|
||||||
|
|
||||||
- `rawZip`：原始 ZIP 文件（`application/zip` / `application/x-zip-compressed`）
|
|
||||||
- `pgpPrivateKey`：签名材料
|
|
||||||
- `signingContext`：签名上下文字符串
|
|
||||||
- `summaryJson`：`summary.json` 的 JSON 文本
|
|
||||||
- `outputFileName`：可选，输出文件名
|
|
||||||
|
|
||||||
响应：
|
|
||||||
|
|
||||||
- `application/zip` 二进制文件（签名后 ZIP）
|
|
||||||
|
|
||||||
说明：响应 ZIP 中 `summary.json` 会包含 `timestamp`（服务端生成，毫秒时间戳）。
|
|
||||||
|
|
||||||
示例（curl）：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -X POST "http://localhost:3000/api/crypto/sign-and-pack-report" \
|
|
||||||
-F "pgpPrivateKey=-----BEGIN PGP PRIVATE KEY BLOCK-----..." \
|
|
||||||
-F "signingContext=TASK-20260115-4875|702286470691215417" \
|
|
||||||
-F "summaryJson={\"summary\":\"检查摘要\"}" \
|
|
||||||
-F "outputFileName=signed-report.zip" \
|
|
||||||
-F "rawZip=@./report-raw.zip;type=application/zip" \
|
|
||||||
--output signed-report.zip
|
|
||||||
```
|
|
||||||
|
|
||||||
## 5. 字段说明来源
|
|
||||||
|
|
||||||
所有接口名称、字段类型、必填项、描述均以 `/api/docs` 与 `/api/spec.json` 为准。
|
|
||||||
Reference in New Issue
Block a user