@zmice/zc 0.1.1 → 0.2.0

package/vendor/packages/toolkit/src/content/skills/security-and-hardening/body.md

@@ -0,0 +1,344 @@
+# Security and Hardening
+
+## Overview
+
+Security-first development practices for web applications. Treat every external input as hostile, every secret as sacred, and every authorization check as mandatory. Security isn't a phase — it's a constraint on every line of code that touches user data, authentication, or external systems.
+
+## When to Use
+
+- Building anything that accepts user input
+- Implementing authentication or authorization
+- Storing or transmitting sensitive data
+- Integrating with external APIs or services
+- Adding file uploads, webhooks, or callbacks
+- Handling payment or PII data
+
+## The Three-Tier Boundary System
+
+### Always Do (No Exceptions)
+
+- **Validate all external input** at the system boundary (API routes, form handlers)
+- **Parameterize all database queries** — never concatenate user input into SQL
+- **Encode output** to prevent XSS (use framework auto-escaping, don't bypass it)
+- **Use HTTPS** for all external communication
+- **Hash passwords** with bcrypt/scrypt/argon2 (never store plaintext)
+- **Set security headers** (CSP, HSTS, X-Frame-Options, X-Content-Type-Options)
+- **Use httpOnly, secure, sameSite cookies** for sessions
+- **Run `npm audit`** (or equivalent) before every release
+
+### Ask First (Requires Human Approval)
+
+- Adding new authentication flows or changing auth logic
+- Storing new categories of sensitive data (PII, payment info)
+- Adding new external service integrations
+- Changing CORS configuration
+- Adding file upload handlers
+- Modifying rate limiting or throttling
+- Granting elevated permissions or roles
+
+### Never Do
+
+- **Never commit secrets** to version control (API keys, passwords, tokens)
+- **Never log sensitive data** (passwords, tokens, full credit card numbers)
+- **Never trust client-side validation** as a security boundary
+- **Never disable security headers** for convenience
+- **Never use `eval()` or `innerHTML`** with user-provided data
+- **Never store sessions in client-accessible storage** (localStorage for auth tokens)
+- **Never expose stack traces** or internal error details to users
+
+## OWASP Top 10 Prevention
+
+### 1. Injection (SQL, NoSQL, OS Command)
+
+```typescript
+// BAD: SQL injection via string concatenation
+const query = `SELECT * FROM users WHERE id = '${userId}'`;
+
+// GOOD: Parameterized query
+const user = await db.query('SELECT * FROM users WHERE id = $1', [userId]);
+
+// GOOD: ORM with parameterized input
+const user = await prisma.user.findUnique({ where: { id: userId } });
+```
+
+### 2. Broken Authentication
+
+```typescript
+// Password hashing
+import { hash, compare } from 'bcrypt';
+
+const SALT_ROUNDS = 12;
+const hashedPassword = await hash(plaintext, SALT_ROUNDS);
+const isValid = await compare(plaintext, hashedPassword);
+
+// Session management
+app.use(session({
+  secret: process.env.SESSION_SECRET,  // From environment, not code
+  resave: false,
+  saveUninitialized: false,
+  cookie: {
+    httpOnly: true,     // Not accessible via JavaScript
+    secure: true,       // HTTPS only
+    sameSite: 'lax',    // CSRF protection
+    maxAge: 24 * 60 * 60 * 1000,  // 24 hours
+  },
+}));
+```
+
+### 3. Cross-Site Scripting (XSS)
+
+```typescript
+// BAD: Rendering user input as HTML
+element.innerHTML = userInput;
+
+// GOOD: Use framework auto-escaping (React does this by default)
+return <div>{userInput}</div>;
+
+// If you MUST render HTML, sanitize first
+import DOMPurify from 'dompurify';
+const clean = DOMPurify.sanitize(userInput);
+```
+
+### 4. Broken Access Control
+
+```typescript
+// Always check authorization, not just authentication
+app.patch('/api/tasks/:id', authenticate, async (req, res) => {
+  const task = await taskService.findById(req.params.id);
+
+  // Check that the authenticated user owns this resource
+  if (task.ownerId !== req.user.id) {
+    return res.status(403).json({
+      error: { code: 'FORBIDDEN', message: 'Not authorized to modify this task' }
+    });
+  }
+
+  // Proceed with update
+  const updated = await taskService.update(req.params.id, req.body);
+  return res.json(updated);
+});
+```
+
+### 5. Security Misconfiguration
+
+```typescript
+// Security headers (use helmet for Express)
+import helmet from 'helmet';
+app.use(helmet());
+
+// Content Security Policy
+app.use(helmet.contentSecurityPolicy({
+  directives: {
+    defaultSrc: ["'self'"],
+    scriptSrc: ["'self'"],
+    styleSrc: ["'self'", "'unsafe-inline'"],  // Tighten if possible
+    imgSrc: ["'self'", 'data:', 'https:'],
+    connectSrc: ["'self'"],
+  },
+}));
+
+// CORS — restrict to known origins
+app.use(cors({
+  origin: process.env.ALLOWED_ORIGINS?.split(',') || 'http://localhost:3000',
+  credentials: true,
+}));
+```
+
+### 6. Sensitive Data Exposure
+
+```typescript
+// Never return sensitive fields in API responses
+function sanitizeUser(user: UserRecord): PublicUser {
+  const { passwordHash, resetToken, ...publicFields } = user;
+  return publicFields;
+}
+
+// Use environment variables for secrets
+const API_KEY = process.env.STRIPE_API_KEY;
+if (!API_KEY) throw new Error('STRIPE_API_KEY not configured');
+```
+
+## Input Validation Patterns
+
+### Schema Validation at Boundaries
+
+```typescript
+import { z } from 'zod';
+
+const CreateTaskSchema = z.object({
+  title: z.string().min(1).max(200).trim(),
+  description: z.string().max(2000).optional(),
+  priority: z.enum(['low', 'medium', 'high']).default('medium'),
+  dueDate: z.string().datetime().optional(),
+});
+
+// Validate at the route handler
+app.post('/api/tasks', async (req, res) => {
+  const result = CreateTaskSchema.safeParse(req.body);
+  if (!result.success) {
+    return res.status(422).json({
+      error: {
+        code: 'VALIDATION_ERROR',
+        message: 'Invalid input',
+        details: result.error.flatten(),
+      },
+    });
+  }
+  // result.data is now typed and validated
+  const task = await taskService.create(result.data);
+  return res.status(201).json(task);
+});
+```
+
+### File Upload Safety
+
+```typescript
+// Restrict file types and sizes
+const ALLOWED_TYPES = ['image/jpeg', 'image/png', 'image/webp'];
+const MAX_SIZE = 5 * 1024 * 1024; // 5MB
+
+function validateUpload(file: UploadedFile) {
+  if (!ALLOWED_TYPES.includes(file.mimetype)) {
+    throw new ValidationError('File type not allowed');
+  }
+  if (file.size > MAX_SIZE) {
+    throw new ValidationError('File too large (max 5MB)');
+  }
+  // Don't trust the file extension — check magic bytes if critical
+}
+```
+
+## Triaging npm audit Results
+
+Not all audit findings require immediate action. Use this decision tree:
+
+```
+npm audit reports a vulnerability
+├── Severity: critical or high
+│   ├── Is the vulnerable code reachable in your app?
+│   │   ├── YES --> Fix immediately (update, patch, or replace the dependency)
+│   │   └── NO (dev-only dep, unused code path) --> Fix soon, but not a blocker
+│   └── Is a fix available?
+│       ├── YES --> Update to the patched version
+│       └── NO --> Check for workarounds, consider replacing the dependency, or add to allowlist with a review date
+├── Severity: moderate
+│   ├── Reachable in production? --> Fix in the next release cycle
+│   └── Dev-only? --> Fix when convenient, track in backlog
+└── Severity: low
+    └── Track and fix during regular dependency updates
+```
+
+**Key questions:**
+- Is the vulnerable function actually called in your code path?
+- Is the dependency a runtime dependency or dev-only?
+- Is the vulnerability exploitable given your deployment context (e.g., a server-side vulnerability in a client-only app)?
+
+When you defer a fix, document the reason and set a review date.
+
+## Rate Limiting
+
+```typescript
+import rateLimit from 'express-rate-limit';
+
+// General API rate limit
+app.use('/api/', rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100,                   // 100 requests per window
+  standardHeaders: true,
+  legacyHeaders: false,
+}));
+
+// Stricter limit for auth endpoints
+app.use('/api/auth/', rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 10,  // 10 attempts per 15 minutes
+}));
+```
+
+## Secrets Management
+
+```
+.env files:
+  ├── .env.example  → Committed (template with placeholder values)
+  ├── .env          → NOT committed (contains real secrets)
+  └── .env.local    → NOT committed (local overrides)
+
+.gitignore must include:
+  .env
+  .env.local
+  .env.*.local
+  *.pem
+  *.key
+```
+
+**Always check before committing:**
+```bash
+# Check for accidentally staged secrets
+git diff --cached | grep -i "password\|secret\|api_key\|token"
+```
+
+## Security Review Checklist
+
+```markdown
+### Authentication
+- [ ] Passwords hashed with bcrypt/scrypt/argon2 (salt rounds ≥ 12)
+- [ ] Session tokens are httpOnly, secure, sameSite
+- [ ] Login has rate limiting
+- [ ] Password reset tokens expire
+
+### Authorization
+- [ ] Every endpoint checks user permissions
+- [ ] Users can only access their own resources
+- [ ] Admin actions require admin role verification
+
+### Input
+- [ ] All user input validated at the boundary
+- [ ] SQL queries are parameterized
+- [ ] HTML output is encoded/escaped
+
+### Data
+- [ ] No secrets in code or version control
+- [ ] Sensitive fields excluded from API responses
+- [ ] PII encrypted at rest (if applicable)
+
+### Infrastructure
+- [ ] Security headers configured (CSP, HSTS, etc.)
+- [ ] CORS restricted to known origins
+- [ ] Dependencies audited for vulnerabilities
+- [ ] Error messages don't expose internals
+```
+## See Also
+
+For detailed security checklists and pre-commit verification steps, see `references/security-checklist.md`.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "This is an internal tool, security doesn't matter" | Internal tools get compromised. Attackers target the weakest link. |
+| "We'll add security later" | Security retrofitting is 10x harder than building it in. Add it now. |
+| "No one would try to exploit this" | Automated scanners will find it. Security by obscurity is not security. |
+| "The framework handles security" | Frameworks provide tools, not guarantees. You still need to use them correctly. |
+| "It's just a prototype" | Prototypes become production. Security habits from day one. |
+
+## Red Flags
+
+- User input passed directly to database queries, shell commands, or HTML rendering
+- Secrets in source code or commit history
+- API endpoints without authentication or authorization checks
+- Missing CORS configuration or wildcard (`*`) origins
+- No rate limiting on authentication endpoints
+- Stack traces or internal errors exposed to users
+- Dependencies with known critical vulnerabilities
+
+## Verification
+
+After implementing security-relevant code:
+
+- [ ] `npm audit` shows no critical or high vulnerabilities
+- [ ] No secrets in source code or git history
+- [ ] All user input validated at system boundaries
+- [ ] Authentication and authorization checked on every protected endpoint
+- [ ] Security headers present in response (check with browser DevTools)
+- [ ] Error responses don't expose internal details
+- [ ] Rate limiting active on auth endpoints

package/vendor/packages/toolkit/src/content/skills/security-and-hardening/meta.yaml

@@ -0,0 +1,21 @@
+kind: skill
+name: security-and-hardening
+title: 安全加固
+description: 加固代码免受常见漏洞影响。适用于处理用户输入、认证、数据存储或外部集成，也适用于任何接收不可信数据、管理会话或接入第三方服务的功能。
+tier: recommended
+audience: advanced
+stability: stable
+suggests:
+  - skill:safety-guardrails
+  - skill:verification-before-completion
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: agent-skills
+  strategy: adapted
+  origin_name: security-and-hardening
+  origin_path: skills/security-and-hardening/SKILL.md
+  origin_id: skill:security-and-hardening
+  notes: 沿用上游安全加固能力，并对齐本仓库审查维度。

package/vendor/packages/toolkit/src/content/skills/shipping-and-launch/body.md

@@ -0,0 +1,55 @@
+# 发布上线
+
+## 何时使用
+
+- 要把功能首次发布到生产环境时
+- 发布变更风险较高，需要灰度、监控和回滚方案时
+- 涉及数据迁移、基础设施调整或用户可见行为变更时
+
+## 输入前提
+
+- 实现和验证已经完成，进入发布准备阶段
+- 愿意把“能部署”与“能安全发布”区分开
+- 已知当前上线范围和风险点
+- 已识别发布会影响哪些说明、安装、升级或回滚文档
+
+## 执行步骤
+
+1. 完成发布前检查：质量、安全、性能、基础设施、文档
+2. 决定是否需要 feature flag、灰度或分阶段放量
+3. 定义监控指标、阈值和观察窗口
+4. 明确回滚条件和回滚路径
+5. 在发布 gate 中确认以下对外说明是否已就绪或已有明确补齐负责人：
+   - 发布说明和用户可见变更摘要
+   - 安装或升级指引
+   - 配置变更、默认值变化和兼容性说明
+   - 回滚步骤、回退条件和已知限制
+6. 发布后做观察和收尾，包括清理临时开关，并核对文档是否与真实发布状态一致
+
+## 成功标准
+
+- 发布是可回滚、可监控、可解释的
+- 风险较高的功能有分阶段上线策略
+- 关键指标和告警阈值是明确的
+- 上线后知道何时前进、何时暂停、何时回滚
+- 发布相关说明不会因为遗漏文档同步而让用户或内部团队误操作
+
+## 相关原则
+
+- 发布不是“把代码推上去”，而是受控变更管理
+- 高风险上线默认要有灰度和回滚方案
+- 监控和观察窗口是发布的一部分
+- 未同步的发布说明、安装升级指引和回滚说明，本质上也是发布风险
+
+## 与文档同步的边界
+
+- 本 skill 负责把文档同步纳入发布 gate，确保上线前后有明确责任和验收
+- `documentation-and-adrs` 负责长期记录、ADR 和 drift 触发判断
+- `release-documentation-sync` 负责发布后逐项核对 README、安装说明、行为变更记录等同步对象
+
+## 与其他技能的衔接
+
+- 通常接在 `verification-before-completion` 和 `code-review-and-quality` 之后
+- 与 `documentation-and-adrs` 配合，补发布说明和决策记录
+- 发布完成后如需做文档收尾，接 `release-documentation-sync`
+- 高风险上线时可结合 `safety-guardrails`

package/vendor/packages/toolkit/src/content/skills/shipping-and-launch/meta.yaml

@@ -0,0 +1,22 @@
+kind: skill
+name: shipping-and-launch
+title: 发布上线
+description: 为生产上线做准备。适用于部署前的检查清单、监控配置、分阶段发布策略与回滚方案规划，确保变更具备真正可发布性。
+tier: recommended
+audience: advanced
+stability: stable
+suggests:
+  - skill:safety-guardrails
+  - skill:documentation-and-adrs
+  - skill:release-documentation-sync
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: agent-skills
+  strategy: adapted
+  origin_name: shipping-and-launch
+  origin_path: skills/shipping-and-launch/SKILL.md
+  origin_id: skill:shipping-and-launch
+  notes: 基于上游发布准备能力整理，并补充发布说明与文档同步收尾 gate。

package/vendor/packages/toolkit/src/content/skills/source-driven-development/body.md

@@ -0,0 +1,186 @@
+# 基于官方文档的开发
+
+## 概述
+
+每个框架相关的代码决策都必须有官方文档支撑。不要凭记忆实现——验证、引用、让用户看到来源。训练数据会过时，API 会被弃用，最佳实践会演进。本技能确保用户得到可信赖的代码，因为每个模式都可以追溯到权威来源。
+
+## 何时使用
+
+- 用户需要遵循当前最佳实践的框架代码
+- 构建模板、脚手架或将被跨项目复制的模式
+- 用户明确要求有文档支撑的、经过验证的或"正确"的实现
+- 实现依赖框架推荐方式的功能（表单、路由、数据获取、状态管理、认证）
+- 审查或改进使用框架特定模式的代码
+- 任何你准备凭记忆编写框架特定代码的时候
+
+**不需要使用的场景：**
+
+- 正确性不依赖特定版本的操作（重命名变量、修复拼写、移动文件）
+- 在所有版本中行为一致的纯逻辑（循环、条件、数据结构）
+- 用户明确要求速度优先于验证（"快速搞定就行"）
+
+## 流程
+
+```
+检测 ──→ 拉取 ──→ 实现 ──→ 引用
+  │        │        │        │
+  ▼        ▼        ▼        ▼
+ 识别     获取     按照     标注
+ 技术栈   相关文档  文档模式  来源
+```
+
+### 步骤 1：检测技术栈和版本
+
+读取项目的依赖文件，识别精确版本：
+
+```
+package.json    → Node/React/Vue/Angular/Svelte
+composer.json   → PHP/Symfony/Laravel
+requirements.txt / pyproject.toml → Python/Django/Flask
+go.mod          → Go
+Cargo.toml      → Rust
+Gemfile         → Ruby/Rails
+```
+
+明确陈述发现：
+
+```
+技术栈检测结果：
+- React 19.1.0（来自 package.json）
+- Vite 6.2.0
+- Tailwind CSS 4.0.3
+→ 正在拉取相关模式的官方文档。
+```
+
+如果版本缺失或模糊，**向用户确认**。不要猜测——版本决定了哪些模式是正确的。
+
+### 步骤 2：拉取官方文档
+
+拉取你正在实现的功能对应的具体文档页面。不是首页，不是全部文档——是相关页面。
+
+**来源优先级（按权威性排序）：**
+
+| 优先级 | 来源 | 示例 |
+|--------|------|------|
+| 1 | 官方文档 | react.dev, docs.djangoproject.com, symfony.com/doc |
+| 2 | 官方博客/更新日志 | react.dev/blog, nextjs.org/blog |
+| 3 | Web 标准参考 | MDN, web.dev, html.spec.whatwg.org |
+| 4 | 浏览器/运行时兼容性 | caniuse.com, node.green |
+
+**不具权威性——不可作为主要来源引用：**
+
+- Stack Overflow 回答
+- 博客文章或教程（即使是热门的）
+- AI 生成的文档或摘要
+- 你自己的训练数据（这正是需要验证的——不要自引自证）
+
+**精确拉取：**
+
+```
+错误：拉取 React 首页
+正确：拉取 react.dev/reference/react/useActionState
+
+错误：搜索"django authentication best practices"
+正确：拉取 docs.djangoproject.com/en/6.0/topics/auth/
+```
+
+拉取后，提取关键模式并记录任何弃用警告或迁移指引。
+
+当官方来源之间相互矛盾时（如迁移指南与 API 参考不一致），向用户说明差异并针对检测到的版本验证哪个模式实际有效。
+
+### 步骤 3：按文档模式实现
+
+编写与文档一致的代码：
+
+- 使用文档中的 API 签名，而非凭记忆
+- 如果文档展示了新的做法，使用新做法
+- 如果文档弃用了某个模式，不要使用弃用版本
+- 如果文档没有覆盖某些内容，标记为未验证
+
+**当文档与现有项目代码冲突时：**
+
+```
+冲突检测：
+现有代码使用 useState 管理表单加载状态，
+但 React 19 文档推荐使用 useActionState 处理此场景。
+（来源：react.dev/reference/react/useActionState）
+
+选项：
+A) 使用现代模式（useActionState）—— 与当前文档一致
+B) 匹配现有代码（useState）—— 与代码库一致
+→ 你倾向哪种方式？
+```
+
+呈现冲突。不要默默选择。
+
+### 步骤 4：标注来源
+
+每个框架特定的模式都需要引用。用户必须能验证每个决策。
+
+**在代码注释中：**
+
+```typescript
+// React 19 表单处理 useActionState
+// 来源：https://react.dev/reference/react/useActionState#usage
+const [state, formAction, isPending] = useActionState(submitOrder, initialState);
+```
+
+**在对话中：**
+
+```
+我使用 useActionState 而非手动 useState 管理表单提交状态。
+React 19 用此 hook 替代了手动的 isPending/setIsPending 模式。
+
+来源：https://react.dev/blog/2024/12/05/react-19#actions
+"useTransition 现在支持异步函数 [...] 自动处理 pending 状态"
+```
+
+**引用规则：**
+
+- 完整 URL，不使用缩短链接
+- 尽可能使用带锚点的深链接（如 `/useActionState#usage` 优于 `/useActionState`）
+- 当支撑非显而易见的决策时，引用相关段落
+- 推荐平台特性时，附上浏览器/运行时兼容性数据
+- 如果找不到某个模式的文档，明确说明：
+
+```
+未验证：未找到此模式的官方文档。
+此实现基于训练数据，可能已过时。
+请在用于生产前自行验证。
+```
+
+诚实说明未能验证的内容，比虚假自信更有价值。
+
+## 常见借口
+
+| 借口 | 现实 |
+|------|------|
+| "我对这个 API 很有信心" | 信心不是证据。训练数据里充满了看起来正确但在当前版本会出错的过时模式。验证它。 |
+| "拉取文档浪费 token" | 编造 API 浪费更多。用户花一小时调试，才发现函数签名变了。一次拉取能省数小时返工。 |
+| "文档里不会有我需要的" | 如果文档没覆盖，这本身就是有价值的信息——该模式可能不是官方推荐的。 |
+| "我会注明可能已过时" | 免责声明没用。要么验证并引用，要么明确标记为未验证。模棱两可是最差选项。 |
+| "这是简单任务，不需要检查" | 使用错误模式的简单任务会变成模板。用户把你的弃用表单处理复制到十个组件后才发现有现代方案。 |
+
+## 危险信号
+
+- 编写框架代码前没有检查该版本的文档
+- 对 API 使用"我认为""应该是"而非引用来源
+- 实现模式时不知道它适用于哪个版本
+- 引用 Stack Overflow 或博客而非官方文档
+- 因为出现在训练数据中而使用弃用的 API
+- 实现前没有读 `package.json` / 依赖文件
+- 交付代码时没有为框架特定决策标注来源
+- 需要一个页面却拉取了整个文档站
+
+## 检查清单
+
+实现完成后自查：
+
+- [ ] 已从依赖文件中识别框架和库的版本
+- [ ] 已为框架特定模式拉取官方文档
+- [ ] 所有来源都是官方文档，不是博客或训练数据
+- [ ] 代码遵循当前版本文档中展示的模式
+- [ ] 非显而易见的决策包含带完整 URL 的来源引用
+- [ ] 未使用弃用 API（已对照迁移指南检查）
+- [ ] 文档与现有代码的冲突已向用户说明
+- [ ] 无法验证的内容已明确标记为未验证

package/vendor/packages/toolkit/src/content/skills/source-driven-development/meta.yaml

@@ -0,0 +1,18 @@
+kind: skill
+name: source-driven-development
+title: 官方文档实现
+description: 基于官方文档的实现规范。在使用任何框架或库编写代码时使用。确保每个实现决策都有官方文档支撑，杜绝凭记忆编码导致的过时模式。
+tier: recommended
+audience: advanced
+stability: stable
+suggests:
+  - skill:engineering-principles
+  - skill:verification-before-completion
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: toolkit-original
+  strategy: curated
+  notes: 本仓库强调基于官方文档实现的原生规范。