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

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