# UX 授权端接口说明

本文档描述当前 UX 服务端实现的授权对接接口与职责边界。

## 1. 职责边界

- UX **只与工具箱交互**（HTTP RPC），不直接与手机 App 交互。
- 手机 App 仅承担扫码和与管理平台联网通信。
- 报告签名流程由工具箱上传原始 ZIP 到 UX，UX 返回已签名 ZIP。

## 2. 设备注册

`device.register`

- 输入：`licence`、`platformPublicKey`
- UX 在本机采集设备特征并计算 `fingerprint`
- UX 将 `licence + fingerprint + 公钥 + PGP 密钥对` 持久化到数据库

## 3. 核心加密接口

### 3.1 设备授权二维码密文

`crypto.encryptDeviceInfo`

- 使用平台公钥 RSA-OAEP 加密：`{ licence, fingerprint }`
- 返回 Base64 密文（工具箱用于生成二维码）

### 3.2 任务二维码解密

`crypto.decryptTask`

- 密钥：`SHA256(licence + fingerprint)`
- 算法：AES-256-GCM
- 输入：任务二维码中的 Base64 密文
- 输出：任务 JSON

### 3.3 摘要二维码加密

`crypto.encryptSummary`

- 密钥派生：HKDF-SHA256
  - `ikm = licence + fingerprint`
  - `salt = taskId`
  - `info = "inspection_report_encryption"`
- 算法：AES-256-GCM
- 输出：`{ taskId, encrypted }` JSON（工具箱用于生成二维码）

### 3.4 原始 ZIP 签名打包（最终报告）

`crypto.signAndPackReport`

- 输入：`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`）

## 4. 安全约束（签名打包）

- 拒绝危险 ZIP 路径（防 Zip Slip）
- 限制原始 ZIP 和单文件大小
- 强制存在以下文件：
  - `assets.json`
  - `vulnerabilities.json`
  - `weakPasswords.json`
  - `漏洞评估报告*.html`