spec-lite 1.1.0 → 1.1.2

package/skills/security-and-hardening/SKILL.md

@@ -0,0 +1,349 @@
+---
+name: security-and-hardening
+description: Hardens code against vulnerabilities. Use when handling user input, authentication, data storage, or external integrations. Use when building any feature that accepts untrusted data, manages user sessions, or interacts with third-party services.
+---
+
+# 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/skills/spec-brownfield-component/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: spec-brownfield-component
+description: Discover components từ code, generate crd.md + cdd.md cho từng component, điền Component Index vào prd.md. Phải chạy /spec-brownfield-init trước.
+---
+
+# spec-brownfield-component
+
+## Overview
+
+Tạo `specs/main/component/{C-XXX}-{component-name}/crd.md` và `cdd.md` cho các components trong brownfield project.
+
+Skill này **tự discover** component boundaries từ code (không dựa vào init), sau đó scan sâu từng component để extract responsibilities, entities, public interface, business rules. Khi hoàn thành, **điền Component Index vào prd.md** và **đề xuất Shared Entities cascade vào domain.md**.
+
+## When to Use
+
+- Sau khi `/spec-brownfield-init` đã chạy và `prd.md` tồn tại
+- Cần generate component artifacts cho brownfield project
+
+## When NOT to Use
+
+- `prd.md` chưa có → chạy `/spec-brownfield-init` trước
+- Greenfield project → component artifacts mọc dần qua cascade từ integrations (`/spec-new`)
+
+---
+
+## Process
+
+### Bước 1: Load context và xác định path
+
+**Path:** Nếu có ARGUMENT là path → dùng làm root. Nếu không → CWD.
+
+**Load:**
+- `specs/main/prd.md` — kiểm tra tồn tại; đọc problem statement và NFRs để hiểu business context
+- `specs/main/domain.md` — đọc Glossary để reuse business terms
+
+Nếu `prd.md` không tồn tại → dừng:
+> `prd.md` chưa có nội dung. Hãy chạy `/spec-brownfield-init` trước.
+
+**Attachments:**
+> Bạn có tài liệu bổ sung nào không? (API docs, architecture diagrams, design docs)
+> Nhập `không` để bỏ qua.
+
+---
+
+### Bước 2: Discover component boundaries
+
+Scan directory structure để tìm component candidates. Thử các patterns sau theo thứ tự:
+
+1. `src/modules/*/` — modular structure (NestJS, v.v.)
+2. `src/*/` — flat module structure (nếu có `service` hoặc `controller` bên trong)
+3. `services/*/` — microservices
+4. `packages/*/` — monorepo packages
+5. `apps/*/` — monorepo apps
+
+Với mỗi candidate directory, xác nhận đây là component bằng cách kiểm tra có ít nhất một trong: `*controller*`, `*service*`, `*repository*`, `*handler*`, `*module*` file bên trong.
+
+Ghi lại cho mỗi component candidate:
+- Directory path
+- File count
+- Patterns detected: controller / service / repository / event publisher / consumer
+
+---
+
+### Bước 3: Confirm component list
+
+Trình bày kết quả discovery cho user confirm:
+
+```
+Tôi phát hiện {N} components từ codebase:
+  [C-001] auth      → src/modules/auth/     (15 files: controller+service+repo)
+  [C-002] user      → src/modules/user/     (12 files: controller+service+repo)
+  [C-003] payment   → src/modules/payment/  (8 files: service+repo)
+  [C-004] notification → src/modules/notification/ (6 files: service+event)
+
+Điều chỉnh nếu cần:
+  - Đổi tên: "C-002 → profile" hoặc nhập tên khác
+  - Bỏ component: "bỏ C-004"
+  - Thêm component: "thêm reporting tại src/reporting/"
+  - Merge: "merge C-001 và C-002 thành auth-user"
+
+Confirm danh sách? [y] hoặc nhập điều chỉnh:
+```
+
+Sau khi confirm, assign C-XXX IDs theo thứ tự tăng dần.
+
+---
+
+### Bước 4: Scan sâu từng component
+
+Với mỗi component, đọc code files bên trong để extract:
+
+**4a. Responsibilities:**
+- Public method names trong service files
+- Class-level comments / JSDoc nếu có
+- Export declarations
+
+**4b. Owned Entities:**
+- Entity / model files trong component directory
+- Decorators: `@Entity()` (TypeORM), Prisma model blocks, `@Schema()` (Mongoose), SQLAlchemy models
+- Migration files gắn với component
+
+**4c. Public Interface:**
+- Controller files: HTTP method + path mỗi endpoint
+- Event publisher: `@EventPattern`, `eventEmitter.emit()`, message queue producers
+- Exported service methods nếu là shared library
+
+**4d. Dependencies:**
+- Import statements referencing other component directories
+- Injectable services từ other modules
+- HTTP client calls đến other services
+
+**4e. Business Rules:**
+- Validation decorators (`@Min`, `@Max`, `@IsEmail`, custom validators)
+- Guard conditions trong service (`if (!user.isActive) throw ...`)
+- Domain events và điều kiện trigger
+- Comments có từ khóa: "must", "should", "only", "never", "không được"
+
+**4f. Internal design (cho cdd.md):**
+- Module structure: list sub-modules / file groups
+- ORM/storage usage: repository pattern, raw queries, cache decorators
+- Internal service/repository interface contracts
+
+---
+
+### Bước 5: Identify cross-component entities
+
+Trong quá trình scan, ghi nhận các entities được **import hoặc reference từ nhiều hơn 1 component** → đây là candidate Shared Entities cho `domain.md`.
+
+Ví dụ: `Order` được dùng trong `payment/` và `inventory/` → candidate Shared Entity, cần xác định owner.
+
+---
+
+### Bước 6: Hỏi clarification — batch
+
+Sau khi scan xong tất cả components, hỏi một lần — tối đa **5 câu tổng cộng**. Ưu tiên những điểm ảnh hưởng đến component boundaries hoặc entity ownership.
+
+```
+Cần làm rõ {N} điểm:
+
+[C-001 auth]
+  Q1. Method `validateToken` được call từ cả auth/ và user/ —
+      đây là public interface hay internal helper?
+      [public / internal / skip]
+
+[cross-component]
+  Q2. Entity `Order` được dùng trong payment/ và inventory/ —
+      component nào sở hữu?
+      [payment / inventory / skip]
+
+Trả lời hoặc "skip all" để đánh dấu NEEDS_CLARIFY hết:
+```
+
+---
+
+### Bước 7: Generate artifacts
+
+Với mỗi component, generate 2 files dùng templates tương ứng:
+
+**`crd.md`** — WHAT (dùng `.claude/templates/main/component/crd-template.md`):
+- Role, Responsibilities, Owned Entities, Public Interface, Business Rules, Domain Events, Dependencies
+
+**`cdd.md`** — HOW (dùng `.claude/templates/main/component/cdd-template.md`):
+- Module structure, Internal data flow, Storage & persistence, Internal interfaces, Technical decisions
+
+**Nguyên tắc:**
+- Mọi phần không detect được → NEEDS_CLARIFY, không bịa
+- Business rules detect được từ code → đánh dấu `(detected from code)`
+- crd.md không chứa internal design; cdd.md không chứa public interface
+
+---
+
+### Bước 8: Cascade Proposals — domain.md
+
+Nếu có Shared Entities được phát hiện ở Bước 5:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SHARED ENTITIES DETECTED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Các entities sau được dùng bởi nhiều components.
+Đề xuất thêm vào specs/main/domain.md (Shared Entities):
+
+  Entity: Order (Owner: C-003-payment)
+    Dùng bởi: C-003-payment, C-005-inventory
+    Fields detected: id, userId, items[], status, totalAmount
+
+  Entity: User (Owner: C-001-auth)
+    Dùng bởi: C-001-auth, C-002-user, C-004-notification
+    Fields detected: id, email, role, isActive
+
+Apply cascade proposals vào domain.md? [y/n/edit]
+```
+
+Nếu `y` → update `specs/main/domain.md` Shared Entities section.
+Nếu `edit` → hỏi chỉnh sửa từng entity trước khi apply.
+
+---
+
+### Bước 9: Review và save artifacts
+
+```
+Sẽ tạo {N} components ({2N} files):
+  ✓ specs/main/component/C-001-auth/crd.md     (3 NEEDS_CLARIFY)
+  ✓ specs/main/component/C-001-auth/cdd.md     (1 NEEDS_CLARIFY)
+  ✓ specs/main/component/C-002-user/crd.md     (0 NEEDS_CLARIFY)
+  ✓ specs/main/component/C-002-user/cdd.md     (2 NEEDS_CLARIFY)
+  ...
+
+Ghi tất cả? [y] hoặc review từng file trước [r]:
+```
+
+- `y` → ghi tất cả
+- `r` → hiển thị lần lượt từng file, user confirm / skip / edit từng cái
+
+---
+
+### Bước 10: Điền Component Index vào prd.md
+
+Sau khi artifacts đã được ghi, update `specs/main/prd.md` Component Index với danh sách đã confirm:
+
+```
+Sẽ điền Component Index vào prd.md:
+  C-001 | auth         | Xác thực và phân quyền người dùng       | active
+  C-002 | user         | Quản lý thông tin người dùng             | active
+  C-003 | payment      | Xử lý thanh toán và giao dịch            | active
+  C-004 | notification | Gửi thông báo qua email/push             | active
+
+Apply? [y/n]
+```
+
+---
+
+### Bước 11: Summary
+
+```
+✓ Generated {N} components:
+  specs/main/component/C-001-auth/    (crd.md + cdd.md)
+  specs/main/component/C-002-user/    (crd.md + cdd.md)
+  ...
+
+✓ prd.md Component Index: {N} entries đã được điền
+
+{nếu có} ✓ domain.md Shared Entities: {N} entities đã được cascade
+
+NEEDS_CLARIFY summary — {total} items:
+  C-001-auth:  {n} — [business rules, domain events, ...]
+  C-002-user:  {n} — [entity ownership, ...]
+  ...
+
+Bước tiếp theo:
+  /spec-brownfield-feature → discover features, generate frd.md + fdd.md, điền Feature Index
+```
+
+---
+
+## Verification
+
+- [ ] Mỗi component có đủ crd.md + cdd.md
+- [ ] crd.md không chứa internal design (đã ở cdd.md)
+- [ ] cdd.md không chứa public interface (đã ở crd.md)
+- [ ] Mọi entity trong crd.md có đúng 1 owner component (hoặc NEEDS_CLARIFY)
+- [ ] Dependencies chỉ reference C-XXX IDs, không reference file paths
+- [ ] Business rules detect được đánh dấu `(detected from code)`
+- [ ] prd.md Component Index đã được update
+- [ ] Shared Entities đã được cascade vào domain.md (nếu có)
+- [ ] NEEDS_CLARIFY items được list đầy đủ trong summary