@liangjie559567/ultrapower 7.5.2 → 7.7.0

package/docs/security/path-traversal-scan-report.md

@@ -0,0 +1,229 @@
+# 路径遍历漏洞扫描报告
+
+**扫描日期**: 2026-03-16
+**扫描工具**: Grep pattern matching
+**扫描范围**: 所有 .ts 文件
+
+## 扫描摘要
+
+- **扫描文件数**: 47
+- **发现风险点**: 8
+- **高风险**: 4
+- **中风险**: 0
+- **低风险**: 4
+
+## 高风险点
+
+### 1. src/hooks/state/StateReader.ts:8
+
+```typescript
+const statePath = join(worktreeRoot, ".omc", "state", `${mode}-state.json`);
+```
+
+**风险等级**: 高
+**原因**: 直接使用未校验的 `mode` 参数进行路径拼接，可能导致路径遍历攻击
+**修复优先级**: P0
+**影响范围**: Hook 系统状态读取
+**建议修复**:
+```typescript
+import { assertValidMode } from '../../lib/validateMode.js';
+const validMode = assertValidMode(mode);
+const statePath = join(worktreeRoot, ".omc", "state", `${validMode}-state.json`);
+```
+
+---
+
+### 2. src/state/migration/integrity.ts:42
+
+```typescript
+const statePath = join(directory, '.omc', 'state', `${mode}-state.json`);
+```
+
+**风险等级**: 高
+**原因**: 迁移工具中未校验 `mode` 参数，可能在迁移过程中被利用
+**修复优先级**: P0
+**影响范围**: 状态迁移系统
+**建议修复**: 在函数入口处添加 `assertValidMode(mode)`
+
+---
+
+### 3. src/state/migration/integrity.ts:69
+
+```typescript
+const statePath = join(directory, '.omc', 'state', `${mode}-state.json`);
+```
+
+**风险等级**: 高
+**原因**: 回滚功能中未校验 `mode` 参数
+**修复优先级**: P0
+**影响范围**: 状态回滚系统
+**建议修复**: 在函数入口处添加 `assertValidMode(mode)`
+
+---
+
+### 4. src/state/migration/integrity.ts:87
+
+```typescript
+const statePath = join(directory, '.omc', 'state', `${mode}-state.json`);
+```
+
+**风险等级**: 高
+**原因**: 完整性验证中未校验 `mode` 参数
+**修复优先级**: P0
+**影响范围**: 状态完整性验证
+**建议修复**: 在函数入口处添加 `assertValidMode(mode)`
+
+---
+
+## 低风险点
+
+### 5. src/state/migration/index.ts:23
+
+```typescript
+const legacyPath = join(directory, '.omc', 'state', `${mode}-state.json`);
+```
+
+**风险等级**: 低
+**原因**: 函数签名使用 `ValidMode` 类型，但未在运行时校验
+**修复优先级**: P2
+**影响范围**: 状态迁移
+**建议修复**: 添加运行时校验 `assertValidMode(mode)` 以确保类型安全
+
+---
+
+### 6. src/state/migration/index.ts:60
+
+```typescript
+const statePath = join(directory, '.omc', 'state', `${mode}-state.json`);
+```
+
+**风险等级**: 低
+**原因**: 函数签名使用 `ValidMode` 类型，但未在运行时校验
+**修复优先级**: P2
+**影响范围**: 状态备份
+**建议修复**: 添加运行时校验
+
+---
+
+### 7. src/lib/state-adapter.ts:62
+
+```typescript
+return join(this.directory, '.omc', 'state', `${this.mode}-state.json`);
+```
+
+**风险等级**: 低
+**原因**: 构造函数中已通过 `assertValidMode(mode)` 校验，但 `this.mode` 可能被修改
+**修复优先级**: P3
+**影响范围**: 状态适配器
+**当前状态**: 已有部分防护（构造函数校验）
+**建议**: 将 `mode` 字段设为 `readonly` 防止修改
+
+---
+
+### 8. src/state/migration/integrity.ts:119
+
+```typescript
+const pattern = `${mode}-state.json.backup-`;
+```
+
+**风险等级**: 低
+**原因**: 用于文件名匹配模式，不直接用于路径拼接，但仍应校验
+**修复优先级**: P3
+**影响范围**: 备份清理
+**建议修复**: 添加 `assertValidMode(mode)` 确保一致性
+
+---
+
+## 已防护的安全实现（参考示例）
+
+以下文件已正确实现路径遍历防护：
+
+### src/tools/state-tools.ts
+
+```typescript
+// 正确示例：在函数入口处校验
+const validMode = assertValidMode(mode);
+// 后续使用 validMode 而非 mode
+```
+
+### src/lib/validateMode.ts
+
+提供了完整的校验工具：
+- `assertValidMode()`: 运行时校验并抛出异常
+- `isValidMode()`: 布尔检查
+- `ValidMode` 类型：编译时类型安全
+
+---
+
+## 修复优先级清单
+
+### P0 - 立即修复（高风险）
+
+1. **[P0]** src/hooks/state/StateReader.ts:8 - Hook 状态读取未校验
+2. **[P0]** src/state/migration/integrity.ts:42 - 迁移工具未校验
+3. **[P0]** src/state/migration/integrity.ts:69 - 回滚功能未校验
+4. **[P0]** src/state/migration/integrity.ts:87 - 完整性验证未校验
+
+### P2 - 短期修复（中风险）
+
+5. **[P2]** src/state/migration/index.ts:23 - 添加运行时校验
+6. **[P2]** src/state/migration/index.ts:60 - 添加运行时校验
+
+### P3 - 长期改进（低风险）
+
+7. **[P3]** src/lib/state-adapter.ts:62 - 将 mode 字段设为 readonly
+8. **[P3]** src/state/migration/integrity.ts:119 - 备份模式匹配校验
+
+---
+
+## 修复模板
+
+### 标准修复模式
+
+```typescript
+// 修复前
+function someFunction(mode: string, directory: string) {
+  const path = join(directory, '.omc', 'state', `${mode}-state.json`);
+  // ...
+}
+
+// 修复后
+import { assertValidMode } from './lib/validateMode.js';
+
+function someFunction(mode: string, directory: string) {
+  const validMode = assertValidMode(mode); // 添加校验
+  const path = join(directory, '.omc', 'state', `${validMode}-state.json`);
+  // ...
+}
+```
+
+---
+
+## 测试验证建议
+
+修复后应执行以下测试：
+
+1. **单元测试**: 验证非法 mode 值被正确拒绝
+2. **集成测试**: 确保合法 mode 值正常工作
+3. **安全测试**: 尝试路径遍历攻击（如 `../../../etc/passwd`）
+
+---
+
+## 附录：扫描方法
+
+### 搜索模式
+
+1. `\$\{mode\}` - 直接模板字符串插值
+2. `.omc/state/.*mode` - 状态路径模式
+3. `\$\{.*mode.*\}` - 包含 mode 的所有插值
+
+### 排除项
+
+- 测试文件中的示例代码（已标注）
+- 注释和文档中的示例
+- 日志输出和错误消息（非路径拼接）
+
+---
+
+**报告生成**: 自动化扫描
+**下一步行动**: 按优先级修复 P0 高风险点

package/docs/security/sensitive-data-inventory.md

@@ -0,0 +1,170 @@
+# 敏感数据清单
+
+## 敏感字段白名单
+
+| 字段名 | 类型 | 风险等级 | 加密要求 | 说明 |
+|--------|------|----------|----------|------|
+| apiKey | string | 高 | 必须 | API 密钥 |
+| token | string | 高 | 必须 | 认证令牌 |
+| credential | string | 高 | 必须 | 凭证信息 |
+| password | string | 高 | 必须 | 密码 |
+| secret | string | 高 | 必须 | 密钥 |
+| privateKey | string | 高 | 必须 | 私钥 |
+| accessToken | string | 高 | 必须 | 访问令牌 |
+| refreshToken | string | 高 | 必须 | 刷新令牌 |
+| sessionId | string | 中 | 推荐 | 会话标识 |
+| authToken | string | 高 | 必须 | 认证令牌 |
+| bearerToken | string | 高 | 必须 | Bearer 令牌 |
+| clientSecret | string | 高 | 必须 | 客户端密钥 |
+| encryptionKey | string | 高 | 必须 | 加密密钥 |
+| signingKey | string | 高 | 必须 | 签名密钥 |
+| webhookSecret | string | 高 | 必须 | Webhook 密钥 |
+
+## 扫描规则
+
+### 正则模式
+
+```typescript
+const SENSITIVE_PATTERNS = {
+  apiKey: /(api[_-]?key|apikey)/i,
+  token: /(token|bearer)/i,
+  credential: /(credential|cred)/i,
+  password: /(password|passwd|pwd)/i,
+  secret: /(secret|private[_-]?key|privatekey)/i,
+  accessToken: /(access[_-]?token|accesstoken)/i,
+  refreshToken: /(refresh[_-]?token|refreshtoken)/i,
+  authToken: /(auth[_-]?token|authtoken)/i,
+  clientSecret: /(client[_-]?secret|clientsecret)/i,
+  encryptionKey: /(encryption[_-]?key|encryptionkey)/i,
+  signingKey: /(signing[_-]?key|signingkey)/i,
+  webhookSecret: /(webhook[_-]?secret|webhooksecret)/i
+};
+```
+
+### 扫描范围
+
+- 状态文件 (`.omc/state/**/*.json`)
+- 配置文件 (`*.json`, `*.yaml`, `*.yml`)
+- 环境变量文件 (`.env*`)
+- 日志文件 (`*.log`)
+
+### 排除路径
+
+- `node_modules/`
+- `dist/`
+- `.git/`
+- `*.test.ts`
+- `*.spec.ts`
+
+## 加密策略
+
+### 算法规范
+
+- **算法**: AES-256-GCM
+- **密钥长度**: 256 位
+- **IV 长度**: 12 字节
+- **认证标签长度**: 16 字节
+
+### 密钥来源
+
+1. **主密钥**: 从环境变量 `OMC_ENCRYPTION_KEY` 读取
+2. **备用方案**: 使用 `crypto.scryptSync()` 从用户标识派生
+3. **密钥格式**: Base64 编码的 32 字节随机数据
+
+### 加密流程
+
+```typescript
+// 1. 生成随机 IV
+const iv = crypto.randomBytes(12);
+
+// 2. 创建加密器
+const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+
+// 3. 加密数据
+const encrypted = Buffer.concat([
+  cipher.update(plaintext, 'utf8'),
+  cipher.final()
+]);
+
+// 4. 获取认证标签
+const authTag = cipher.getAuthTag();
+
+// 5. 组合输出: iv + authTag + encrypted
+const result = Buffer.concat([iv, authTag, encrypted]).toString('base64');
+```
+
+## 密钥管理
+
+### 密钥轮换
+
+- **轮换周期**: 90 天
+- **触发条件**:
+  - 定期轮换到期
+  - 密钥泄露事件
+  - 安全审计要求
+- **轮换流程**:
+  1. 生成新密钥
+  2. 使用新密钥重新加密所有敏感数据
+  3. 安全销毁旧密钥
+  4. 更新环境变量
+
+### 密钥存储
+
+- **生产环境**: 使用密钥管理服务 (KMS)
+- **开发环境**: 环境变量 (`.env.local`, 不提交)
+- **CI/CD**: 加密的 secrets 存储
+
+### 密钥访问控制
+
+- 仅加密/解密模块可访问密钥
+- 密钥不得记录到日志
+- 密钥不得通过网络传输（除 KMS）
+
+## 检测与响应
+
+### 自动检测
+
+- **静态扫描**: 构建时扫描代码和配置文件
+- **运行时监控**: 检测未加密的敏感数据写入
+- **日志审计**: 定期扫描日志文件
+
+### 响应流程
+
+1. **检测到泄露**:
+   - 立即停止操作
+   - 记录泄露事件
+   - 通知管理员
+
+2. **修复措施**:
+   - 加密泄露的数据
+   - 轮换受影响的密钥
+   - 更新访问控制
+
+3. **事后审查**:
+   - 分析泄露原因
+   - 更新扫描规则
+   - 改进防护措施
+
+## 合规要求
+
+- **GDPR**: 个人数据必须加密存储
+- **PCI DSS**: 支付相关数据必须加密
+- **SOC 2**: 敏感数据访问必须审计
+- **HIPAA**: 健康数据必须加密传输和存储
+
+## 审计日志
+
+所有敏感数据操作必须记录：
+
+```typescript
+interface SensitiveDataAuditLog {
+  timestamp: string;
+  operation: 'encrypt' | 'decrypt' | 'access' | 'rotate';
+  fieldName: string;
+  userId?: string;
+  success: boolean;
+  errorMessage?: string;
+}
+```
+
+日志存储位置: `.omc/logs/sensitive-data-audit.log`