@winspan/claude-forge 8.41.0 → 8.51.0

package/docs/design/refactor-phase1-spec-20260515-1600.md

@@ -0,0 +1,543 @@
+# claude-forge 渐进式重构 - 第 1 迭代实施方案
+
+**文档版本**: v1.0  
+**生成时间**: 2026-05-15 16:00  
+**迭代周期**: 2 周（2026-05-15 ~ 2026-05-29）  
+**负责范围**: P0 安全漏洞 + 部分 P1 基础设施问题
+
+---
+
+## 1. 目标与范围
+
+### 1.1 迭代目标
+
+第 1 迭代聚焦于**安全加固**和**基础设施稳定性**，为后续重构奠定安全基础：
+
+1. **修复 P0 级安全漏洞**（3 个）
+   - 路径遍历漏洞（skills.ts、patch.ts）
+   - Git 命令注入漏洞（trace.ts）
+   - 类型安全缺失（storage/events.ts）
+
+2. **解决 P1 级基础设施问题**（选择 4 个）
+   - 添加缺失的数据库索引（性能优化）
+   - 补充核心模块单元测试（覆盖率从 0% → 50%）
+   - 统一错误处理（daemon 稳定性）
+   - 添加请求体大小限制（DoS 防护）
+
+3. **建立测试基础设施**
+   - 配置测试环境（Vitest + 覆盖率报告）
+   - 编写测试工具函数（mock storage、mock AI provider）
+   - 建立 CI 流程（GitHub Actions）
+
+### 1.2 不包括的内容（留到后续迭代）
+
+- ❌ 架构重构（模块拆分、依赖解耦）
+- ❌ 性能优化（N+1 查询、连接池）
+- ❌ 文档补全（API 文档、架构图）
+- ❌ P2 级问题（代码重复、命名规范）
+- ❌ 新功能开发
+
+---
+
+## 2. 问题清单与优先级
+
+### 2.1 P0 级问题（必须修复）
+
+| ID | 问题 | 影响 | 文件 |
+|---|---|---|---|
+| P0-1 | 路径遍历漏洞 | 攻击者可读取任意文件 | `src/web/routes/skills.ts`, `src/web/routes/patch.ts` |
+| P0-2 | Git 命令注入 | 攻击者可执行任意命令 | `src/web/routes/trace.ts` |
+| P0-3 | 类型安全缺失 | 运行时类型错误 | `src/core/storage/events.ts` |
+
+### 2.2 P1 级问题（本迭代处理）
+
+| ID | 问题 | 影响 | 文件 |
+|---|---|---|---|
+| P1-1 | 缺失数据库索引 | 查询性能差 | `src/core/storage/schema.sql` |
+| P1-2 | 0% 测试覆盖 | 重构风险高 | 全局 |
+| P1-3 | 错误处理不统一 | daemon 崩溃 | `src/daemon/router.ts`, `src/web/routes/*.ts` |
+| P1-4 | 请求体大小无限制 | DoS 攻击风险 | `src/web/server.ts` |
+
+---
+
+## 3. 改动文件清单
+
+### 3.1 安全修复（P0）
+
+| 文件 | 改动类型 | 预计行数 | 说明 |
+|---|---|---|---|
+| `src/web/routes/skills.ts` | 修改 | +15 | 添加文件名校验 |
+| `src/web/routes/patch.ts` | 修改 | +15 | 添加路径校验 |
+| `src/web/routes/trace.ts` | 修改 | +20 | 添加 projectPath 校验 |
+| `src/core/storage/events.ts` | 修改 | +30 | 添加 Zod 运行时校验 |
+| `tests/unit/security.test.ts` | 新增 | +100 | 安全漏洞回归测试 |
+
+### 3.2 基础设施改进（P1）
+
+| 文件 | 改动类型 | 预计行数 | 说明 |
+|---|---|---|---|
+| `src/core/storage/schema.sql` | 修改 | +15 | 添加复合索引 |
+| `src/daemon/router.ts` | 修改 | +30 | 添加错误边界 |
+| `src/web/server.ts` | 修改 | +5 | 添加请求体大小限制 |
+| `src/web/routes/error-handler.ts` | 新增 | +50 | 统一错误处理中间件 |
+| `tests/unit/storage.test.ts` | 新增 | +200 | Storage 单元测试 |
+| `tests/unit/router.test.ts` | 新增 | +150 | Router 单元测试 |
+| `tests/unit/type-guards.test.ts` | 新增 | +100 | 类型守卫测试 |
+| `tests/helpers/mock-storage.ts` | 新增 | +80 | 测试工具函数 |
+| `tests/helpers/mock-ai.ts` | 新增 | +60 | 测试工具函数 |
+
+### 3.3 CI/CD 配置
+
+| 文件 | 改动类型 | 预计行数 | 说明 |
+|---|---|---|---|
+| `.github/workflows/test.yml` | 新增 | +50 | CI 测试流程 |
+| `.github/workflows/security.yml` | 新增 | +40 | 安全扫描流程 |
+
+**总计**：
+- 新增文件：9 个
+- 修改文件：7 个
+- 预计改动行数：~960 行
+
+---
+
+## 4. 实施步骤（按依赖顺序）
+
+### Step 1: 修复 P0-1 路径遍历漏洞（1 天）
+
+**目标**：防止攻击者通过 `../../../etc/passwd` 等路径读取任意文件
+
+**改动**：
+
+1. **修复 skills.ts**（第 33 行）
+   ```typescript
+   // 当前代码
+   const filePath = path.join(skillsDir, `${name}.md`);
+   
+   // 修复后
+   if (name.includes('/') || name.includes('\\') || name.includes('..')) {
+     return res.status(400).json({ error: 'Invalid skill name' });
+   }
+   const safeName = name.replace(/[^a-zA-Z0-9_-]/g, '_');
+   const filePath = path.join(skillsDir, `${safeName}.md`);
+   ```
+
+2. **修复 patch.ts**（第 45 行）
+   ```typescript
+   function resolvePatchTarget(targetType: string, targetName: string): string {
+     // 添加路径校验
+     if (targetName.includes('/') || targetName.includes('\\') || targetName.includes('..')) {
+       throw new Error('Invalid target name');
+     }
+     
+     if (targetType === 'skill') {
+       return path.join(getSkillsDir(), `${targetName}.md`);
+     }
+     // ...
+   }
+   ```
+
+**验证方法**：
+```bash
+# 测试恶意输入
+curl http://localhost:3456/api/skills/../../../etc/passwd
+# 预期：返回 400 错误
+
+curl -X PUT http://localhost:3456/api/skills/../../../tmp/evil \
+  -H "Content-Type: application/json" \
+  -d '{"content": "malicious"}'
+# 预期：返回 400 错误
+```
+
+**回滚方案**：
+- Git revert 到修改前的 commit
+
+---
+
+### Step 2: 修复 P0-2 Git 命令注入漏洞（1 天）
+
+**目标**：防止攻击者通过恶意 projectPath 执行任意命令
+
+**改动**：
+
+1. **修复 trace.ts**（第 28 行）
+   ```typescript
+   // 当前代码
+   const projectPath = req.query.project as string | undefined;
+   
+   // 修复后
+   const projectPath = req.query.project as string | undefined;
+   
+   // 校验 projectPath
+   if (!projectPath) {
+     return res.status(400).json({ error: 'Missing project parameter' });
+   }
+   
+   if (!path.isAbsolute(projectPath)) {
+     return res.status(400).json({ error: 'Project path must be absolute' });
+   }
+   
+   if (!fs.existsSync(projectPath)) {
+     return res.status(404).json({ error: 'Project path does not exist' });
+   }
+   
+   if (!fs.existsSync(path.join(projectPath, '.git'))) {
+     return res.status(400).json({ error: 'Not a git repository' });
+   }
+   
+   // 继续执行 git 命令
+   ```
+
+**验证方法**：
+```bash
+# 测试恶意输入
+curl "http://localhost:3456/api/trace/HEAD?project=/tmp;%20rm%20-rf%20/"
+# 预期：返回 400 错误，不执行 rm 命令
+```
+
+**回滚方案**：
+- Git revert
+
+---
+
+### Step 3: 修复 P0-3 类型安全缺失（2 天）
+
+**目标**：在 storage 层添加运行时类型校验，防止数据库返回异常数据导致崩溃
+
+**改动**：
+
+1. **添加 Zod schema**（`src/core/storage/events.ts`）
+   ```typescript
+   import { z } from 'zod';
+   
+   const EventRowSchema = z.object({
+     event_id: z.string(),
+     session_id: z.string(),
+     project_path: z.string(),
+     timestamp: z.string(),
+     hook_type: z.enum(['PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'Stop', 'Notification']),
+     tool_name: z.string().optional(),
+     tool_input: z.string().optional(), // JSON string
+     tool_output: z.string().optional(), // JSON string
+     user_prompt: z.string().optional(),
+     ai_response: z.string().optional(),
+   });
+   
+   private rowToEvent(row: unknown): ForgeEvent {
+     // 运行时校验
+     const validated = EventRowSchema.parse(row);
+     
+     return {
+       event_id: validated.event_id,
+       session_id: validated.session_id,
+       project_path: validated.project_path,
+       timestamp: validated.timestamp,
+       hook_type: validated.hook_type,
+       tool_name: validated.tool_name,
+       tool_input: validated.tool_input ? JSON.parse(validated.tool_input) : undefined,
+       tool_output: validated.tool_output ? JSON.parse(validated.tool_output) : undefined,
+       user_prompt: validated.user_prompt,
+       ai_response: validated.ai_response,
+     };
+   }
+   ```
+
+2. **错误处理**
+   ```typescript
+   queryEvents(filter: EventFilter): ForgeEvent[] {
+     try {
+       const rows = this.db.prepare(sql).all(...params);
+       return rows.map(row => this.rowToEvent(row));
+     } catch (err) {
+       if (err instanceof z.ZodError) {
+         logger.error('[Storage] Invalid event row from database:', err.errors);
+         return []; // 返回空数组而非崩溃
+       }
+       throw err;
+     }
+   }
+   ```
+
+**验证方法**：
+```bash
+# 运行单元测试
+npx vitest run tests/unit/storage.test.ts
+
+# 手动测试：插入异常数据
+sqlite3 ~/.claude-forge/data.db "INSERT INTO events (event_id, session_id, hook_type) VALUES ('test', 'test', 'InvalidType');"
+# 预期：queryEvents 返回空数组，不崩溃
+```
+
+**回滚方案**：
+- 保留原 `rowToEvent` 为 `unsafeRowToEvent`
+- 如果 Zod 校验导致合法数据被拒绝，临时回退
+
+---
+
+### Step 4: 添加缺失的数据库索引（0.5 天）
+
+**目标**：优化高频查询性能
+
+**改动**：
+
+1. **添加索引**（`src/core/storage/schema.sql`）
+   ```sql
+   -- routing_events 表：obeyed 查询优化
+   CREATE INDEX IF NOT EXISTS idx_routing_events_obeyed_ts 
+   ON routing_events(obeyed, ts DESC);
+   
+   -- events 表：session + hook_type 复合查询优化
+   CREATE INDEX IF NOT EXISTS idx_events_session_hook 
+   ON events(session_id, hook_type, timestamp DESC);
+   
+   -- injections 表：session + handler 复合查询优化
+   CREATE INDEX IF NOT EXISTS idx_injections_session_handler 
+   ON injections(session_id, source_handler);
+   ```
+
+2. **迁移脚本**（`src/core/storage/base.ts`）
+   ```typescript
+   private runMigrations(): void {
+     // 添加索引（幂等操作）
+     this.db.exec(`
+       CREATE INDEX IF NOT EXISTS idx_routing_events_obeyed_ts ON routing_events(obeyed, ts DESC);
+       CREATE INDEX IF NOT EXISTS idx_events_session_hook ON events(session_id, hook_type, timestamp DESC);
+       CREATE INDEX IF NOT EXISTS idx_injections_session_handler ON injections(session_id, source_handler);
+     `);
+     logger.info('[SQLiteStorage] Performance indexes created');
+   }
+   ```
+
+**验证方法**：
+```bash
+# 检查索引
+sqlite3 ~/.claude-forge/data.db "SELECT name FROM sqlite_master WHERE type='index' AND name LIKE 'idx_%';"
+
+# 验证查询计划
+sqlite3 ~/.claude-forge/data.db "EXPLAIN QUERY PLAN SELECT * FROM routing_events WHERE obeyed IS NULL ORDER BY ts DESC;"
+# 预期：SEARCH routing_events USING INDEX idx_routing_events_obeyed_ts
+```
+
+---
+
+### Step 5: 补充核心模块单元测试（5 天）
+
+**目标**：测试覆盖率从 0% 提升到 50%
+
+**改动**：
+
+1. **测试工具函数**（`tests/helpers/mock-storage.ts`）
+   ```typescript
+   import Database from 'better-sqlite3';
+   import { SQLiteStorage } from '../../src/core/storage/sqlite.js';
+   import { tmpdir } from 'node:os';
+   import { join } from 'node:path';
+   import { randomUUID } from 'node:crypto';
+   
+   export function createMockStorage(): SQLiteStorage {
+     const dbPath = join(tmpdir(), `test-${randomUUID()}.db`);
+     return new SQLiteStorage(dbPath);
+   }
+   
+   export function cleanupMockStorage(storage: SQLiteStorage): void {
+     const dbPath = storage.getDbPath();
+     storage.close();
+     if (fs.existsSync(dbPath)) {
+       fs.unlinkSync(dbPath);
+     }
+   }
+   ```
+
+2. **Storage 测试**（`tests/unit/storage.test.ts`）
+   - 测试 `writeEvent` / `queryEvents` / `upsertSession`
+   - 测试事务处理
+   - 测试并发写入
+   - 测试索引生效
+
+3. **Router 测试**（`tests/unit/router.test.ts`）
+   - 测试事件路由逻辑
+   - 测试类型守卫
+   - 测试错误边界
+
+4. **Type Guards 测试**（`tests/unit/type-guards.test.ts`）
+   - 测试所有类型守卫函数
+   - 测试边界情况（缺失字段、错误类型）
+
+**验证方法**：
+```bash
+# 运行测试
+npm test
+
+# 生成覆盖率报告
+npm test -- --coverage
+
+# 检查覆盖率
+cat coverage/coverage-summary.json | jq '.total.lines.pct'
+# 预期：>= 50
+```
+
+---
+
+### Step 6: 统一错误处理 + 请求体限制（1 天）
+
+**目标**：提升 daemon 和 Web 服务稳定性
+
+**改动**：
+
+1. **添加错误边界**（`src/daemon/router.ts`）
+   ```typescript
+   export async function routeEvent(event: ForgeEvent, handlers: Handlers): Promise<HookResult | void> {
+     try {
+       if (isUserPromptSubmit(event)) return await handlers.UserPromptSubmit.handle(event);
+       if (isPostToolUse(event)) return await handlers.PostToolUse.handle(event);
+       if (isStop(event)) return await handlers.Stop.handle(event);
+     } catch (err) {
+       logger.error(`[Router] Handler failed for ${event.hook_type}:`, err);
+       return { allow: true }; // 默认放行，避免阻塞 Claude Code
+     }
+   }
+   ```
+
+2. **统一错误处理中间件**（`src/web/routes/error-handler.ts`）
+   ```typescript
+   export function errorHandler(err: Error, req: Request, res: Response, next: NextFunction) {
+     logger.error(`[API Error] ${req.method} ${req.path}:`, err);
+     
+     const statusCode = (err as any).statusCode || 500;
+     const errorCode = (err as any).code || 'INTERNAL_ERROR';
+     
+     res.status(statusCode).json({
+       error: {
+         code: errorCode,
+         message: err.message,
+       }
+     });
+   }
+   ```
+
+3. **请求体大小限制**（`src/web/server.ts`）
+   ```typescript
+   this.app.use(express.json({ limit: '1mb' }));
+   this.app.use(express.urlencoded({ extended: true, limit: '1mb' }));
+   ```
+
+**验证方法**：
+```bash
+# 测试大请求体
+curl -X POST http://localhost:3456/api/patch/preview \
+  -H "Content-Type: application/json" \
+  -d "$(python3 -c 'print("{\"data\": \"" + "A"*2000000 + "\"}")')"
+# 预期：返回 413 Payload Too Large
+```
+
+---
+
+## 5. 风险点与缓解措施
+
+### 5.1 高风险改动
+
+| 改动 | 风险 | 缓解措施 |
+|---|---|---|
+| 路径校验逻辑 | 可能拒绝合法路径 | 保留旧函数作为 fallback；充分测试 |
+| Zod 运行时校验 | 性能开销 | 仅在边界层使用；缓存 schema |
+| 错误边界 | 可能隐藏真实错误 | 详细日志记录；监控错误率 |
+
+### 5.2 回滚策略
+
+- 所有改动通过 Git 管理，可快速 revert
+- 关键改动保留旧代码为 `unsafe*` 或 `legacy*` 函数
+- 测试失败立即停止部署
+
+---
+
+## 6. 测试策略
+
+### 6.1 单元测试覆盖目标
+
+| 模块 | 当前覆盖率 | 目标覆盖率 | 优先级 |
+|---|---|---|---|
+| `src/core/storage/` | 0% | 60% | P0 |
+| `src/daemon/router.ts` | 0% | 70% | P0 |
+| `src/core/types.ts` (type guards) | 0% | 80% | P0 |
+| `src/web/routes/` | 0% | 40% | P1 |
+
+### 6.2 集成测试场景
+
+1. **端到端事件流**
+   - UserPromptSubmit → Router → Handler → Storage
+   - 验证事件正确写入数据库
+
+2. **安全漏洞回归测试**
+   - 路径遍历攻击
+   - Git 命令注入
+   - 类型错误注入
+
+3. **性能测试**
+   - 索引生效验证
+   - 并发写入测试
+
+---
+
+## 7. 验收标准
+
+### 7.1 功能验收
+
+- ✅ 所有现有功能正常（回归测试通过）
+- ✅ daemon 启动正常
+- ✅ Web 仪表盘正常访问
+- ✅ CLI 命令正常执行
+
+### 7.2 安全验收
+
+- ✅ 路径遍历攻击被拦截（返回 400）
+- ✅ Git 命令注入被拦截（返回 400）
+- ✅ 异常数据不导致崩溃（返回空数组或错误）
+
+### 7.3 性能验收
+
+- ✅ 索引创建成功（`EXPLAIN QUERY PLAN` 显示使用索引）
+- ✅ 查询性能提升（对比修改前后的查询时间）
+
+### 7.4 测试验收
+
+- ✅ 单元测试覆盖率 >= 50%
+- ✅ 所有测试通过
+- ✅ CI 流程正常运行
+
+---
+
+## 8. 时间估算
+
+| 步骤 | 工作量（天） | 依赖 |
+|---|---|---|
+| Step 1: 路径遍历漏洞 | 1 | 无 |
+| Step 2: Git 命令注入 | 1 | 无 |
+| Step 3: 类型安全 | 2 | 无 |
+| Step 4: 数据库索引 | 0.5 | 无 |
+| Step 5: 单元测试 | 5 | Step 1-4 完成后 |
+| Step 6: 错误处理 | 1 | 无 |
+| **总计** | **10.5 天** | - |
+
+**缓冲时间**：1.5 天（应对意外问题）  
+**总工作量**：12 天（约 2 周）
+
+---
+
+## 9. 里程碑
+
+| 日期 | 里程碑 | 交付物 |
+|---|---|---|
+| 2026-05-17 | P0 安全漏洞修复完成 | 3 个漏洞修复 + 回归测试 |
+| 2026-05-20 | 基础设施改进完成 | 索引 + 错误处理 + 请求体限制 |
+| 2026-05-27 | 单元测试完成 | 覆盖率 >= 50% |
+| 2026-05-29 | 第 1 迭代验收 | 所有验收标准通过 |
+
+---
+
+## 10. 下一步
+
+**Phase 1.5: User Review**
+
+请 review 本方案后回复：
+- **"批准"** / **"approve"** → spawn coder 开始实施
+- **"修改 [意见]"** → 调整 spec
+- **"取消"** → 停止任务