# 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`