docs: self-hosted licensing SDK design spec

2026-06-09 10:00:30 +08:00 · 2026-05-18 21:00:56 +08:00
parent dc74c19be4
commit d7469afee9
1 changed files with 477 additions and 0 deletions
@@ -0,0 +1,477 @@
+# 自研授权 SDK 设计方案
+
+> **日期**：2026-05-18
+> **背景**：比特安索授权云费用过高，决定优先推进自研授权方案。
+> **原则**：与比特安索双线共存，Provider 可扩展架构，后续可接入更多第三方授权方式。
+
+---
+
+## 目录
+
+1. [决策摘要](#1-决策摘要)
+2. [总体架构](#2-总体架构)
+3. [许可证协议与数据模型](#3-许可证协议与数据模型)
+4. [Rust 层核心逻辑](#4-rust-层核心逻辑)
+5. [平台后端变更](#5-平台后端变更)
+6. [安全设计](#6-安全设计)
+7. [实施阶段](#7-实施阶段)
+
+---
+
+## 1. 决策摘要
+
+| 决策项 | 选择 | 理由 |
+|--------|------|------|
+| 授权服务形态 | **混合模式** | 有网络时在线验证（心跳/租约续期），断网时本地缓存可用至离线宽限期 |
+| 加密体系 | **非对称签名 RSA-256 + AES-256-GCM 加密载荷** | 离线验签 + 内容加密防窥探，每个 license 独立 AES 密钥防批量破解 |
+| 授权粒度 | **完整属性**：有效期 + 终端限制 + 并发用户数 + 使用次数 + 特性开关 | 对齐现有比特业务属性，功能上不降级 |
+| 后端集成 | **复用 API + Webhook 双服务** | 签发走 API（管理操作需认证鉴权），SDK 交互走 Webhook（高频快速 2xx） |
+| 比特兼容 | **双线共存 + Provider 可扩展架构** | 后续可接入更多第三方 |
+| 终端识别 | **硬件指纹分层采集 + 稳定度评分兜底** | 强指纹精确匹配，弱指纹分配服务器 UUID，管理员可手动释放 |
+| Rust 架构 | **单 cdylib + trait 多 Provider** | 公共模块共享，扩展第三方只需增加 trait 实现 |
+| SDK 交互安全 | **Nonce + Timestamp + HMAC 签名防重放** | 简单有效，无需序列号同步 |
+
+---
+
+## 2. 总体架构
+
+### 2.1 全系统组件图
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         客户现场                                 │
+│  ┌──────────┐    ┌──────────────────┐    ┌──────────────────┐   │
+│  │ 客户应用   │───▶│ Java SDK         │    │ 许可证配置文件     │   │
+│  └──────────┘    │ AuthProvider impl │◀───│ ~/.craftlabs/     │   │
+│                  │ ┌──────────────┐ │    │   license_cache   │   │
+│                  │ │BitAnswerProv │ │    │   device_id       │   │
+│                  │ ├──────────────┤ │    └──────────────────┘   │
+│                  │ │SelfHostedPrv │ │                            │
+│                  │ └──────┬───────┘ │                            │
+│                  └────────┼────────┘                            │
+│                           │ JNI                                 │
+│                  ┌────────▼────────┐                            │
+│                  │ Rust craft-core │  libcraftlabs_auth_core    │
+│                  │ ◇ trait Provider│                            │
+│                  │ ┌─────────────┐ │                            │
+│                  │ │BitAnswer    │ │──────▶ 比特安索云           │
+│                  │ ├─────────────┤ │                            │
+│                  │ │SelfHosted   │ │──HTTPS▶ license-webhook    │
+│                  │ └─────────────┘ │                            │
+│                  │ device.rs      │ 硬件指纹分层采集              │
+│                  │ crypto.rs      │ HKDF+AES-GCM+RSA验签        │
+│                  │ security/      │ 反调试/完整性/混淆            │
+│                  └────────────────┘                            │
+└─────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────┐
+│                       创飞机房 / 云                              │
+│                                                                 │
+│  ┌──────────────────────────┐   ┌──────────────────────────┐    │
+│  │ license-webhook-ingress  │   │ delivery-platform-api    │    │
+│  │ :8081                    │   │ :8080                    │    │
+│  │ SDK 在线端点:             │   │ 许可证签发端点:            │    │
+│  │ /license/v1/activate     │◀──│ /api/v1/licenses         │    │
+│  │ /license/v1/heartbeat    │   │ /api/v1/licenses/{id}    │    │
+│  │ /license/v1/check        │   │ /api/v1/licenses/{id}/   │    │
+│  │ /license/v1/release      │   │   revoke                 │    │
+│  │                          │   │                          │    │
+│  │ 事件回调 ─────────────▶  │   │ 合同/SN/终端/审计         │    │
+│  └──────────────────────────┘   └──────────────────────────┘    │
+│              │                            │                      │
+│              └──────────┬─────────────────┘                      │
+│                         ▼                                       │
+│                  ┌──────────────┐                                │
+│                  │ PostgreSQL 15│                                │
+│                  └──────────────┘                                │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 Rust 层模块结构（改造后）
+
+```
+native/craft-core/src/
+├── lib.rs                     # cdylib 入口 + C ABI 路由
+├── trait_provider.rs           # Provider trait 定义 + select_provider
+│
+├── provider_bitanswer/         # 现有逻辑封装
+│   ├── mod.rs
+│   ├── activate.rs
+│   ├── license.rs
+│   └── heartbeat.rs
+│
+├── provider_selfhosted/        # ★ 本次核心交付
+│   ├── mod.rs                  # SelfHostedProvider impl Provider
+│   ├── activate.rs             # HTTPS POST → webhook:8081
+│   ├── license.rs              # 验签 + 解密 + 离线校验
+│   ├── heartbeat.rs            # HTTPS 心跳 + 租约续期
+│   ├── protocol.rs             # 请求/响应序列化
+│   └── cache.rs                # 许可证本地加密存储
+│
+├── device.rs                   # ★ 硬件指纹分层采集
+├── crypto.rs                   # ★ HKDF + AES-256-GCM + RSA 验签
+├── session.rs                  # 泛化 session（去 bit_handle）
+├── error.rs                    # 自研 + 比特错误码体系
+│
+└── security/                   # 不变
+    ├── mod.rs
+    ├── anti_debug.rs
+    ├── integrity.rs
+    ├── obfuscation.rs
+    └── string_encrypt.rs
+```
+
+### 2.3 Provider trait 契约
+
+```rust
+pub trait Provider: Send + Sync {
+    fn initialize(&mut self, ctx: &CraftContext, config: &AuthConfig) 
+        -> Result<(), LicenseError>;
+    fn activate(&self, ctx: &CraftContext, license_key: &str) 
+        -> Result<ActivateResponse, LicenseError>;
+    fn check_license(&self, ctx: &CraftContext) 
+        -> Result<LicenseStatus, LicenseError>;
+    fn heartbeat(&self, ctx: &CraftContext) 
+        -> Result<HeartbeatResponse, LicenseError>;
+    fn has_feature(&self, ctx: &CraftContext, name: &str) -> bool;
+    fn release(&mut self, ctx: &CraftContext) -> Result<(), LicenseError>;
+    fn get_license_info(&self, ctx: &CraftContext) -> LicenseInfoFFI;
+    fn close(&mut self);
+}
+```
+
+### 2.4 Java 层变更
+
+| 模块 | 变更 |
+|------|------|
+| `craftlabs-auth-core` | 接口不变；`SelfhostedConfigSection` 扩展 `offlineGraceDays`、`heartbeatIntervalHours` 等字段；`FeatureMapping` 扩展 `selfhostedFeatureKey` |
+| `craftlabs-auth-bitanswer` | **不变**（双线共存） |
+| `craftlabs-auth-selfhosted` | 从桩改为真实实现：`System.loadLibrary("craftlabs_auth_core")` |
+| `craftlabs-auth-tests` | 新增 `SelfHostedProviderTest`、`MultiProviderSmokeTest` |
+
+### 2.5 关键架构约束
+
+- **单一 cdylib**：`craftlabs_auth_core` 包含所有 provider，通过 trait 路由
+- **Java 侧无感知**：各 AuthProvider 均调 NativeBridge，路由在 Rust 层完成
+- **双线 classpath 隔离**：BitAnswer 和 SelfHosted 不同 Maven 模块
+- **契约不变**：AuthProvider 接口 7 方法不变、AuthConfig record 不变
+- **Schema 兼容**：selfhosted 段向后兼容扩展新字段
+
+---
+
+## 3. 许可证协议与数据模型
+
+### 3.1 License JSON 结构
+
+```jsonc
+{
+  "version": 1,
+  "license_id": "01JQXYZ...",       // ULID
+  "issued_at": "2026-05-18T10:00:00Z",
+  
+  // 载荷：AES-256-GCM 加密后的 Base64 密文
+  // 解密后为 LicensePayload：{ tenant_id, product, grant, constraints, features, custom }
+  "payload": "A8f3Kd9s...base64url...",
+  
+  "signature": {
+    "algorithm": "RS256",
+    "key_id": "kp_2026_q2",         // 支持密钥轮换
+    "value": "MEUCIQDx..."          // RS256 签名（对密文 payload 签名）
+  }
+}
+```
+
+### 3.2 LicensePayload（解密后明文）
+
+```jsonc
+{
+  "tenant_id": "craftlabs-wharf-prod",
+  "product": "wharf-inspection-v2",
+  
+  "grant": {
+    "type": "perpetual",              // perpetual | subscription | trial
+    "not_before": "2026-05-01T00:00:00Z",
+    "not_after": "2027-05-01T00:00:00Z",
+    "offline_grace_days": 7,
+    "heartbeat_interval_hours": 24
+  },
+  
+  "constraints": {
+    "max_devices": 5,
+    "max_concurrent_users": 0,        // 0=不限制
+    "max_activations": 0
+  },
+  
+  "features": {
+    "advanced_analytics": true,
+    "real_time_monitor": false,
+    "api_export": true
+  },
+  
+  "custom": {                         // 扩展字段
+    "contract_ref": "CT-2026-0042",
+    "project_id": "wharf-nansha-phase2"
+  }
+}
+```
+
+### 3.3 签发与校验流程
+
+```
+签发（服务器侧）:
+  LicensePayload 明文
+    → AES-256-GCM 加密（key = HKDF(编译期盐, license_id)）
+    → 密文 payload (Base64)
+    → RSA-SHA256 签名（对密文签名）
+    → 完整 license.json
+
+校验（Rust SDK 侧）:
+  license.json
+    → RSA 公钥验签（快速排除伪造）
+    → HKDF 派生 AES 密钥
+    → AES-256-GCM 解密
+    → 时间窗口校验（not_before ≤ now ≤ not_after + 离线宽限期）
+    → 特性/约束校验
+```
+
+### 3.4 在线交互协议
+
+端点：`license-webhook-ingress:8081/license/v1/*`
+
+| 端点 | 方法 | 请求体 | 成功响应 | 错误响应 |
+|------|------|--------|----------|----------|
+| `/activate` | POST | `{license_key, device_fingerprint}` | 200 `{status:"activated", device_id, license_payload}` | 409 终端满 / 403 已吊销 / 422 无效 |
+| `/heartbeat` | POST | `{license_key, device_hash, local_time}` | 200 `{status:"ok", lease_renewed_until}` | 410 已过期/吊销 |
+| `/check` | POST | `{license_key, device_hash}` | 200 `{status:"valid", features, not_after}` | 410 已过期/吊销 |
+| `/release` | POST | `{license_key, device_hash}` | 200 `{status:"released"}` | — |
+
+**防重放**：每个请求携带 `X-Craft-Nonce`、`X-Craft-Timestamp`、`X-Craft-Signature`（HMAC-SHA256），服务器时间窗口 5 分钟 + Nonce 去重。
+
+### 3.5 签发端点（API 侧）
+
+```
+POST   /api/v1/licenses              # 创建/签发许可证
+GET    /api/v1/licenses              # 分页查询
+GET    /api/v1/licenses/{licenseId}  # 详情
+POST   /api/v1/licenses/{id}/revoke  # 吊销
+GET    /api/v1/licenses/{id}/activations  # 激活记录
+POST   /api/v1/licenses/{id}/activations/{aid}/release  # 释放设备
+```
+
+### 3.6 数据库表（新增）
+
+| 表 | 用途 |
+|----|------|
+| `platform_licenses` | 许可证主表（license_id、有效期、约束、状态、签名快照） |
+| `platform_license_features` | 特性开关（license_id, feature_key, enabled） |
+| `platform_license_activations` | 终端激活记录（license_id, device_hash, stability_score, status） |
+| `platform_license_heartbeats` | 心跳审计（可选，视量级） |
+| `platform_license_keys` | RSA 密钥对管理（key_id, public_key, private_key） |
+| `platform_license_policies` | 策略模板（默认有效期、终端数、特性等） |
+
+---
+
+## 4. Rust 层核心逻辑
+
+### 4.1 新增依赖
+
+```toml
+reqwest = { version = "0.12", features = ["json", "rustls-tls"], default-features = false }
+rsa = { version = "0.9", features = ["sha2"] }
+aes-gcm = "0.10"
+hkdf = "0.12"
+base64 = "0.22"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+chrono = { version = "0.4", features = ["serde"] }
+```
+
+### 4.2 关键数据结构
+
+```rust
+pub struct DeviceFingerprint {
+    pub composite_hash: String,    // SHA-256(layer1|layer2|layer3|layer4)
+    pub stability_score: u8,       // 0~100，影响匹配策略
+    pub layers: Vec<FingerprintLayer>,
+}
+
+pub struct LicenseStatus {
+    pub licensed: bool,
+    pub not_after: Option<i64>,
+    pub features: HashMap<String, bool>,
+    pub device_count: u32,
+    pub max_devices: u32,
+    pub heartbeat_due: Option<i64>,
+}
+```
+
+### 4.3 硬件指纹分层采集
+
+| 层级 | 权重 | 来源 |
+|------|------|------|
+| Layer 1 硬件 | 40 | Linux: DMI product_uuid / Windows: SMBIOS UUID / macOS: IOPlatformUUID |
+| Layer 2 OS | 30 | Linux: /etc/machine-id / Windows: MachineGuid / macOS: 同 L1 |
+| Layer 3 存储 | 20 | 根文件系统 UUID (blkid/VolumeSerialNumber) |
+| Layer 4 网络 | 10 | 物理网卡 MAC（跳过 docker/tap/lo/veth） |
+
+**稳定度评分**：Layer1=有+Layer2=有 → 70（强指纹）；仅 Layer2 有 → 40；仅 Layer4 → 10。
+
+**兜底**：稳定度 < 20 时，服务器分配 UUID 并加密存储到 `~/.craftlabs/device_id`，管理员可手动吊销释放配额。
+
+### 4.4 离线宽限期
+
+```rust
+fn check_license离线(&self) -> Result<LicenseStatus, LicenseError> {
+    // 1. 加载缓存许可证
+    // 2. 检查距离上次在线心跳的天数
+    // 3. 超过 offline_grace_days → OfflineGraceExceeded
+    // 4. 未超过 → 时间窗口校验（not_before/not_after）
+    // 5. 返回 LicenseStatus（device_count=0 标记离线）
+}
+```
+
+### 4.5 错误码体系
+
+```rust
+pub enum LicenseError {
+    // 通用
+    Success, ConfigMissing, Network, NotInitialized,
+    // 签名/加密
+    InvalidFormat, InvalidSignature, SignatureMismatch, CryptoError,
+    DecryptionFailed, CorruptedPayload, LicenseIdMismatch,
+    // 许可状态
+    NotYetValid, Expired, NoCachedLicense,
+    OfflineGraceExceeded { days_offline, max_days },
+    InvalidLicense, LicenseRevoked,
+    DeviceLimitReached, ConcurrentUserLimitReached, ActivationLimitReached,
+    // 兼容比特
+    BitAnswerStatus(u32),
+    UnknownStatus(u16),
+}
+```
+
+### 4.6 本地缓存
+
+```
+~/.craftlabs/
+├── device_id              # 硬件指纹或服务器 UUID
+├── license_cache.json     # AES-256-GCM 加密的许可证副本
+│                          # 加密密钥 = SHA256(device_id + EMBEDDED_SALT)
+└── heartbeat_state.json   # { last_heartbeat, lease_until }
+```
+
+### 4.7 编译期公钥嵌入
+
+`build.rs` 读取 `native/craft-core/embedded/pubkey.pem`，生成 `const EMBEDDED_PUBLIC_KEY: &str = "..."`，`crypto.rs` 在 `initialize` 时解析为 `RsaPublicKey`。
+
+---
+
+## 5. 平台后端变更
+
+### 5.1 delivery-platform-api 新增模块
+
+```
+license/
+├── LicenseController.java        # REST /api/v1/licenses
+├── LicenseService.java            # 签发/吊销/查询
+├── LicenseSigner.java             # RSA+AES 签发
+└── LicenseKeyManager.java         # 密钥对管理
+
+persistence/license/
+├── PlatformLicense.java & Mapper
+├── PlatformLicenseFeature.java & Mapper
+├── PlatformLicenseActivation.java & Mapper
+├── PlatformLicenseKey.java & Mapper
+└── PlatformLicensePolicy.java & Mapper
+```
+
+新增角色：`LICENSE_OPS`，管理 `/api/v1/licenses/**` 的写权限。
+
+### 5.2 license-webhook-ingress 新增模块
+
+```
+license/
+├── LicenseController.java         # /license/v1/*
+├── LicenseActivateService.java    # 激活 + 终端匹配
+├── LicenseHeartbeatService.java   # 心跳 + 吊销检测
+├── LicenseCheckService.java       # 在线校验
+├── LicenseReleaseService.java     # 设备释放
+├── DeviceMatcher.java             # 分层指纹匹配
+└── NonceValidator.java            # 防重放
+```
+
+### 5.3 事件回调
+
+激活/心跳失败/到期/吊销等事件，沿现有 Webhook→API 异步投递链路通知 API 更新台账和审计。
+
+---
+
+## 6. 安全设计
+
+### 6.1 许可证防篡改
+
+| 措施 | 作用 |
+|------|------|
+| **载荷 AES-256-GCM 加密** | 阻止直接查看许可证内容（特性/期限/终端数），每个 license_id 独立密钥防批量破解 |
+| **密文 RSA-SHA256 签名** | 验签不通过 = 篡改，先行快速拒绝 |
+| **HKDF 密钥派生** | 盐编译期嵌入 + license_id，增加逆向提取难度 |
+| **公钥编译期嵌入** | 不在运行时从文件或网络加载，防替换攻击 |
+
+### 6.2 SDK 在线交互安全
+
+| 措施 | 说明 |
+|------|------|
+| **TLS** | 全链路 HTTPS，证书校验 |
+| **HMAC 签名** | 每个请求 X-Craft-Signature = HMAC-SHA256(nonce|ts|method|path|body, tenantKey) |
+| **Nonce 去重** | Redis SETNX + 时间窗口 5 分钟，防重放 |
+| **Authorization 头** | Bearer tenantKey 双向验证 |
+
+### 6.3 运行时保护
+
+Rust 侧复用现有 `security/` 模块：反调试检测、完整性校验、字符串混淆，适配自研路径。
+
+---
+
+## 7. 实施阶段
+
+### Phase 1：离线核心
+**目标**：管理员签发 → 文件交付 → SDK 本地验签解密
+
+- Rust: crypto.rs、license.rs、cache.rs、device.rs、error.rs
+- Java: SelfhostedConfigSection 扩展字段
+- 平台: 数据库迁移、LicenseSigner、LicenseController（签发/查询/吊销）
+- 验证: AES 往返测试、RSA 验签测试、过期拒绝测试
+
+### Phase 2：在线激活
+**目标**：SDK 网络激活获取许可证，终端配额限制
+
+- Rust: activate.rs、protocol.rs、trait_provider.rs、reqwest 集成
+- Webhook: LicenseController、ActivateService、DeviceMatcher、NonceValidator
+- 平台: 终端释放端点
+- 验证: Mock HTTP 测试、终端满 409 测试
+
+### Phase 3：心跳 + 离线兜底
+**目标**：心跳维持租约、离线宽限期降级、吊销远程生效
+
+- Rust: heartbeat.rs、check_license 离线逻辑
+- Webhook: HeartbeatService、CheckService、ReleaseService
+- 验证: 心跳成功更新租约、断网 8 天 OfflineGraceExceeded、吊销后 410
+
+### Phase 4：完善与生产加固
+**目标**：双 Provider 切换、CI/CD、文档
+
+- Rust: build.rs 公钥嵌入、security 模块适配
+- Java: MultiProviderSmokeTest、SelfHostedProviderTest
+- CI: ci-native.yml 适配、ci-platform.yml 新增
+- 文档: 集成指南、操作手册、CHANGELOG
+
+### 工作量估算
+
+| Phase | Rust | Java SDK | Platform API | Webhook | 合计 |
+|-------|------|----------|-------------|---------|------|
+| P1 | M | S | M | — | M~L |
+| P2 | M | — | S | M | M |
+| P3 | S | — | — | M | M |
+| P4 | S | S | — | — | S |
+
+（S=小，M=中，L=大）