diff --git a/docs/UX-授权端接口说明.md b/docs/UX-授权端接口说明.md deleted file mode 100644 index c700d2e..0000000 --- a/docs/UX-授权端接口说明.md +++ /dev/null @@ -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` diff --git a/docs/第三方-OpenAPI-对接指南.md b/docs/第三方-OpenAPI-对接指南.md deleted file mode 100644 index 10d43af..0000000 --- a/docs/第三方-OpenAPI-对接指南.md +++ /dev/null @@ -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` 为准。