feat(sdk): AuthConfigs, JSON Schema, examples, and release checksum CI

Add craftlabs-auth-config.schema.json, Java AuthConfigs model with tests, example configs aligned to BP-10, C/Java/auth-config documentation, native header notes, RELEASING guide, and workflow to verify SDK artifact checksums on release tags. Made-with: Cursor
2026-06-09 10:00:30 +08:00 · 2026-04-06 21:05:12 +08:00
parent 65eb983035
commit f94f03bcc2
31 changed files with 1219 additions and 22 deletions
@@ -0,0 +1,93 @@
+# CraftLabs 授权 SDK — 发布与完整性
+
+对齐架构文档 [SYSTEM_ARCHITECTURE §9.8](../docs/engineering/SYSTEM_ARCHITECTURE.md)：官方渠道、**SHA-256 清单**、**GPG 签名（建议）**、`java` 与 `native` **同 Git tag**。
+
+## 1. 发布前检查
+
+- [ ] `mvn -f java/pom.xml verify` 通过（JDK 17+）。
+- [ ] `native` 已在各目标平台完成构建，且与本次 **同一 tag** 一并交付。
+- [ ] `CHANGELOG`（或发布说明）写明 **比特 SDK / 运行时** 兼容版本。
+
+## 2. 生成 SHA256SUMS（必做）
+
+在仓库根目录执行（会先 `mvn -DskipTests package`）：
+
+```bash
+chmod +x scripts/sdk-release-checksums.sh
+./scripts/sdk-release-checksums.sh --output dist/sdk-release
+```
+
+已构建过时跳过 Maven：
+
+```bash
+./scripts/sdk-release-checksums.sh --no-mvn --output dist/sdk-release
+```
+
+把 **本机构建出的 Native** 一并写入清单（路径相对于仓库根，便于客户校验）：
+
+```bash
+./scripts/sdk-release-checksums.sh --output dist/sdk-release --native-path "$(pwd)/native/build"
+```
+
+含完整测试的构建后再生成清单：
+
+```bash
+./scripts/sdk-release-checksums.sh --verify --output dist/sdk-release
+```
+
+输出：
+
+- `dist/sdk-release/SHA256SUMS` — 每行：`哈希  相对路径`
+- `dist/sdk-release/RELEASE-MANIFEST.txt` — 提交 SHA、UTC 时间
+
+**客户校验**（在克隆/解压后的仓库根或同目录结构下）：
+
+```bash
+sha256sum -c dist/sdk-release/SHA256SUMS
+```
+
+macOS：
+
+```bash
+shasum -a 256 -c dist/sdk-release/SHA256SUMS
+```
+
+对 `SHA256SUMS` 本身做 **分离签名**（本机已配置 GPG）：
+
+```bash
+SIGN=1 ./scripts/sdk-release-checksums.sh --no-mvn --output dist/sdk-release
+```
+
+生成 `SHA256SUMS.asc`；客户使用公布的公钥：`gpg --verify SHA256SUMS.asc SHA256SUMS`。
+
+## 3. Maven JAR 的 GPG 签名（强烈建议）
+
+父 POM 已配置 `maven-gpg-plugin`，**默认跳过**（`gpg.skip=true`），不影响日常 `verify`。
+
+发布前在已导入私钥的机器上：
+
+```bash
+gpg --version   # 确认可用
+mvn -f java/pom.xml -Prelease-sign verify
+```
+
+各 **可发布模块**（`craftlabs-auth-core`、`craftlabs-auth-bitanswer`、`craftlabs-auth-selfhosted`）的 `target/*.jar` 旁会出现 **`.asc`**。`craftlabs-auth-tests` 模块固定 **不签名**。
+
+若无私钥或未就绪，可只发 **SHA256SUMS**；待密钥就绪后再打开 `-Prelease-sign`。
+
+### CI / 无人值守（可选）
+
+在构建机配置 `MAVEN_GPG_PASSPHRASE` 等环境变量，或使用 `gpg-agent`；勿将私钥提交仓库。GitHub Actions 可用 `GPG_PRIVATE_KEY` secret + [crazy-max/ghaction-import-gpg](https://github.com/crazy-max/ghaction-import-gpg) 导入后再执行 `mvn -Prelease-sign verify`。
+
+## 4. GitHub Release 建议资产
+
+每个 **tag** 上传：
+
+1. 三个 **release JAR**（及对应 **.asc**，若已签名）
+2. 各平台 **Native** 压缩包
+3. **`SHA256SUMS`** 与 **`SHA256SUMS.asc`**
+4. 固定页面公布 **GPG 公钥指纹** 与下载说明
+
+---
+
+版权所有 © 广州创飞人工智能技术有限公司（以项目实际声明为准）。