devflow-kit 1.8.3 → 2.0.0

package/src/assets/skills/boundary-validation/references/detection.md

@@ -0,0 +1,283 @@
+# Validation Issue Detection
+
+Grep patterns and report templates for finding validation issues.
+
+## Quick Detection Commands
+
+### Find Unvalidated Request Body Usage
+
+```bash
+# Express/Node.js
+grep -rn "req\.body" --include="*.ts" --include="*.js" | grep -v "safeParse\|validate\|schema"
+
+# Look for direct property access without validation
+grep -rn "req\.body\.\w" --include="*.ts" --include="*.js"
+```
+
+### Find Unvalidated Parameters
+
+```bash
+# Path parameters
+grep -rn "req\.params\.\w" --include="*.ts" --include="*.js" | grep -v "safeParse\|validate"
+
+# Query parameters
+grep -rn "req\.query\.\w" --include="*.ts" --include="*.js" | grep -v "safeParse\|validate"
+```
+
+### Find SQL Injection Risks
+
+```bash
+# Template literals with SQL
+grep -rn '`.*SELECT.*\${' --include="*.ts" --include="*.js"
+grep -rn '`.*INSERT.*\${' --include="*.ts" --include="*.js"
+grep -rn '`.*UPDATE.*\${' --include="*.ts" --include="*.js"
+grep -rn '`.*DELETE.*\${' --include="*.ts" --include="*.js"
+
+# String concatenation in queries
+grep -rn "'\s*\+\s*.*\+\s*'" --include="*.ts" --include="*.js" | grep -i "select\|insert\|update\|delete"
+```
+
+### Find Unvalidated External Data
+
+```bash
+# JSON.parse without validation
+grep -rn "JSON\.parse" --include="*.ts" --include="*.js" | grep -v "safeParse\|try"
+
+# fetch responses used directly
+grep -rn "\.json()" --include="*.ts" --include="*.js" | grep -v "safeParse\|schema\|validate"
+```
+
+### Find Unvalidated Environment Variables
+
+```bash
+# Direct process.env usage
+grep -rn "process\.env\.\w" --include="*.ts" --include="*.js" | grep -v "safeParse\|validate\|ConfigSchema"
+```
+
+### Find Dangerous Functions
+
+```bash
+# eval and Function constructor
+grep -rn "eval\s*(" --include="*.ts" --include="*.js"
+grep -rn "new\s*Function\s*(" --include="*.ts" --include="*.js"
+
+# JWT decode without verify
+grep -rn "jwt\.decode" --include="*.ts" --include="*.js" | grep -v "jwt\.verify"
+```
+
+---
+
+## Validation Report Format
+
+When validation issues detected:
+
+```markdown
+# INPUT VALIDATION ISSUES DETECTED
+
+## CRITICAL - Missing Boundary Validation
+**File**: src/api/routes/users.ts:45
+**Issue**: API endpoint accepts unvalidated user input
+**Security Risk**: HIGH - Injection attacks, data corruption possible
+
+**Current Code**:
+```typescript
+app.post('/api/users', async (req, res) => {
+  const user = await createUser(req.body); // NO VALIDATION
+  res.json(user);
+});
+```
+
+**Required Fix**:
+```typescript
+const UserRequestSchema = z.object({
+  body: z.object({
+    email: z.string().email().max(255),
+    name: z.string().min(1).max(100),
+    age: z.number().int().min(0).max(150)
+  })
+});
+
+app.post('/api/users', async (req, res) => {
+  const validation = UserRequestSchema.safeParse(req);
+
+  if (!validation.success) {
+    return res.status(400).json({ error: validation.error });
+  }
+
+  const result = await createUser(validation.data.body);
+  // ... handle result
+});
+```
+
+**Impact**: Prevents malicious input, ensures data integrity
+
+## CRITICAL - Manual Validation Instead of Schema
+**File**: src/services/validation.ts:23
+**Issue**: Manual type checking instead of schema validation
+**Problem**: Scattered validation logic, incomplete checks
+
+**Current Code**:
+```typescript
+if (!data.email || typeof data.email !== 'string') {
+  throw new Error('Invalid email');
+}
+if (!data.age || typeof data.age !== 'number') {
+  throw new Error('Invalid age');
+}
+// ... 15 more manual checks
+```
+
+**Required Fix**:
+```typescript
+const UserSchema = z.object({
+  email: z.string().email().max(255),
+  age: z.number().int().min(0).max(150),
+  name: z.string().min(1).max(100),
+  // All validation rules in one place
+});
+
+const validation = UserSchema.safeParse(data);
+if (!validation.success) {
+  return { ok: false, error: validation.error };
+}
+```
+
+**Impact**: Centralized validation, type safety, better error messages
+
+## CRITICAL - SQL Injection Risk
+**File**: src/database/queries.ts:67
+**Issue**: String interpolation in SQL query
+**Security Risk**: CRITICAL - SQL injection possible
+
+**Current Code**:
+```typescript
+const query = `SELECT * FROM users WHERE email = '${email}'`;
+```
+
+**Required Fix**:
+```typescript
+// 1. Validate input
+const validation = EmailSchema.safeParse(email);
+if (!validation.success) {
+  return { ok: false, error: new Error('Invalid email') };
+}
+
+// 2. Use parameterized query
+const query = 'SELECT * FROM users WHERE email = $1';
+const result = await db.query(query, [validation.data]);
+```
+
+**Impact**: Prevents SQL injection attacks (critical security issue)
+
+## HIGH - External API Response Not Validated
+**File**: src/integrations/payment.ts:89
+**Issue**: Trusting external API response without validation
+**Risk**: Application crash if API changes structure
+
+**Current Code**:
+```typescript
+const data = await response.json();
+return data.amount; // No validation
+```
+
+**Required Fix**:
+```typescript
+const PaymentResponseSchema = z.object({
+  amount: z.number().positive(),
+  currency: z.string().length(3),
+  status: z.enum(['success', 'failed', 'pending'])
+});
+
+const validation = PaymentResponseSchema.safeParse(await response.json());
+if (!validation.success) {
+  return { ok: false, error: new Error('Invalid payment response') };
+}
+
+return { ok: true, value: validation.data.amount };
+```
+
+## Summary
+- **Critical**: X validation issues (Y missing, Z SQL injection risks)
+- **High**: X external data issues
+- **Security Risk**: CRITICAL/HIGH/MEDIUM
+- **Files affected**: X
+
+## SECURITY GATE FAILED
+
+These validation gaps create serious security vulnerabilities:
+1. SQL injection possible in X locations
+2. Unvalidated user input in Y API endpoints
+3. External data trusted without validation
+
+**DO NOT deploy until these are fixed.**
+
+## Required Actions
+
+1. **Immediate** (Security Critical):
+   - Fix SQL injection risks
+   - Add validation to all API endpoints
+
+2. **High Priority**:
+   - Validate all external API responses
+   - Validate environment variables on startup
+
+3. **Standard**:
+   - Replace manual validation with schemas
+   - Add validation tests
+
+## Implementation Guide
+
+**Step 1**: Install validation library
+```bash
+npm install zod  # or appropriate library
+```
+
+**Step 2**: Define schemas for all boundaries
+```typescript
+// src/validation/schemas.ts
+export const schemas = {
+  createUser: UserSchema,
+  updateUser: UpdateUserSchema,
+  searchQuery: SearchQuerySchema,
+  // ... all input shapes
+};
+```
+
+**Step 3**: Apply at boundaries
+```typescript
+// Validate at entry point
+const validation = schema.safeParse(input);
+// Check result and proceed
+```
+
+**Step 4**: Add tests
+```typescript
+// Verify validation catches invalid input
+```
+```
+
+---
+
+## Risk Classification
+
+| Issue Type | Risk Level | Fix Priority |
+|------------|------------|--------------|
+| SQL injection | CRITICAL | Immediate |
+| Command injection | CRITICAL | Immediate |
+| Path traversal | CRITICAL | Immediate |
+| Missing auth validation | CRITICAL | Immediate |
+| Unvalidated API input | HIGH | Same day |
+| Unvalidated external data | HIGH | Same day |
+| Manual validation | MEDIUM | This sprint |
+| Missing env validation | MEDIUM | This sprint |
+| Incomplete schemas | LOW | Next sprint |
+
+---
+
+## Integration Points
+
+This skill works with:
+
+- **devflow:software-design**: Ensures validation uses Result types, catches fake/incomplete validation
+- **devflow:testing**: Validates boundary tests exist
+- **devflow:security**: Broader security review context

package/src/assets/skills/boundary-validation/references/patterns.md

@@ -0,0 +1,283 @@
+# Boundary Validation — Correct Patterns
+
+Extended examples of proper validation patterns with literature citations.
+
+## Schema Validation at Boundary [1][5]
+
+Parse at the boundary, then trust the typed result downstream. The schema is the
+single source of truth for what valid data looks like.
+
+```typescript
+import { z } from 'zod';
+
+// Schema IS the type definition — no drift possible [5]
+const UserSchema = z.object({
+  email: z.string().email().max(255),
+  age: z.number().int().min(0).max(150),
+  name: z.string().min(1).max(100),
+});
+
+type User = z.infer<typeof UserSchema>;
+
+// Parse, don't validate: unknown → User | error [1]
+function createUser(data: unknown): Result<User, ValidationError> {
+  const parsed = UserSchema.safeParse(data);
+  if (!parsed.success) {
+    return { ok: false, error: new ValidationError('Invalid user data', parsed.error) };
+  }
+  return { ok: true, value: parsed.data };
+}
+```
+
+---
+
+## API Endpoint — Zero Trust Boundary [3][4]
+
+HTTP request data is always hostile. Parse the entire request shape, not just body.
+
+```typescript
+const CreateUserRequestSchema = z.object({
+  body: UserSchema,
+});
+
+app.post('/api/users', async (req, res) => {
+  const parsed = CreateUserRequestSchema.safeParse(req);
+  if (!parsed.success) {
+    return res.status(400).json({
+      error: 'Validation failed',
+      details: parsed.error.issues, // structured errors for client [5]
+    });
+  }
+  const result = await createUser(parsed.data.body);
+  if (!result.ok) return res.status(500).json({ error: result.error.message });
+  res.json(result.value);
+});
+```
+
+---
+
+## External API Response [2][3]
+
+External APIs can change without notice. Parse responses to detect contract violations
+before they propagate through your system.
+
+```typescript
+const ExternalUserSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+async function fetchUserData(userId: string): Promise<Result<UserData, Error>> {
+  try {
+    const response = await fetch(`https://api.example.com/users/${userId}`);
+    const parsed = ExternalUserSchema.safeParse(await response.json());
+    if (!parsed.success) {
+      return { ok: false, error: new Error('External API returned invalid data') };
+    }
+    return { ok: true, value: parsed.data };
+  } catch (error) {
+    return { ok: false, error: error as Error };
+  }
+}
+```
+
+---
+
+## Environment Variables — Fail Fast [8]
+
+Validate configuration on startup. A misconfigured environment should crash
+immediately, not fail subtly at 3am. [8]
+
+```typescript
+const ConfigSchema = z.object({
+  port: z.string().regex(/^\d+$/).transform(Number).pipe(z.number().min(1).max(65535)),
+  dbUrl: z.string().url().startsWith('postgresql://'),
+  apiKey: z.string().min(32).max(128),
+});
+
+function loadConfig(): Result<Config, Error> {
+  const parsed = ConfigSchema.safeParse({
+    port: process.env.PORT,
+    dbUrl: process.env.DATABASE_URL,
+    apiKey: process.env.API_KEY,
+  });
+  if (!parsed.success) {
+    return { ok: false, error: new Error(`Invalid config: ${parsed.error.message}`) };
+  }
+  return { ok: true, value: parsed.data };
+}
+
+// Startup: fail-fast pattern [8]
+const configResult = loadConfig();
+if (!configResult.ok) {
+  console.error('Failed to load configuration:', configResult.error);
+  process.exit(1);
+}
+const config = configResult.value; // typed, validated, safe
+```
+
+---
+
+## Database Query with Input Parsing [7][15]
+
+Parse input before query. Always use parameterized queries — never interpolate. [15]
+
+```typescript
+const EmailSchema = z.string().email().max(255);
+const SearchTermSchema = z.string().min(1).max(100).regex(/^[a-zA-Z0-9\s-]+$/);
+
+async function getUserByEmail(email: unknown): Promise<Result<User, Error>> {
+  const parsed = EmailSchema.safeParse(email);
+  if (!parsed.success) return { ok: false, error: new Error('Invalid email format') };
+  try {
+    const user = await db.query('SELECT * FROM users WHERE email = $1', [parsed.data]);
+    return { ok: true, value: user };
+  } catch (error) {
+    return { ok: false, error: error as Error };
+  }
+}
+```
+
+---
+
+## File Upload — Defense in Depth [4]
+
+Validate metadata, verify content type matches declared type, enforce size limits.
+
+```typescript
+const FileUploadSchema = z.object({
+  name: z.string().max(255).regex(/^[a-zA-Z0-9._-]+$/),
+  size: z.number().max(10 * 1024 * 1024), // 10MB max
+  mimetype: z.enum(['image/jpeg', 'image/png', 'application/pdf']),
+});
+
+async function handleUpload(file: unknown): Promise<Result<string, Error>> {
+  const parsed = FileUploadSchema.safeParse(file);
+  if (!parsed.success) return { ok: false, error: new Error('Invalid file') };
+
+  // Content sniffing: verify actual content matches declared type [4]
+  const buffer = await readFileBuffer(file);
+  const detectedType = await fileType.fromBuffer(buffer);
+  if (detectedType?.mime !== parsed.data.mimetype) {
+    return { ok: false, error: new Error('File type mismatch') };
+  }
+
+  const safeFilename = `${uuid()}_${parsed.data.name}`;
+  const safePath = path.join(UPLOAD_DIR, safeFilename);
+  await fs.writeFile(safePath, buffer);
+  return { ok: true, value: safeFilename };
+}
+```
+
+---
+
+## URL Parameters and Query Strings [3][4]
+
+```typescript
+const UserIdSchema = z.string().uuid();
+
+app.get('/users/:id', async (req, res) => {
+  const parsed = UserIdSchema.safeParse(req.params.id);
+  if (!parsed.success) return res.status(400).json({ error: 'Invalid user ID' });
+  const result = await getUserById(parsed.data);
+  if (!result.ok) return res.status(404).json({ error: 'User not found' });
+  res.json(result.value);
+});
+
+const SearchQuerySchema = z.object({
+  q: z.string().min(1).max(100),
+  page: z.coerce.number().int().min(1).default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  sort: z.enum(['name', 'date', 'relevance']).default('relevance'),
+});
+
+app.get('/search', async (req, res) => {
+  const parsed = SearchQuerySchema.safeParse(req.query);
+  if (!parsed.success) {
+    return res.status(400).json({ error: 'Invalid query', details: parsed.error.issues });
+  }
+  const { q, page, limit, sort } = parsed.data;
+  res.json(await searchService.search(q, { page, limit, sort }));
+});
+```
+
+---
+
+## Webhook — Verify Then Parse [4][9]
+
+Always verify signature before parsing payload. Signature verification prevents
+spoofed events; schema parsing prevents malformed data.
+
+```typescript
+const WebhookPayloadSchema = z.object({
+  event: z.enum(['payment.completed', 'payment.failed', 'subscription.created']),
+  data: z.object({ id: z.string(), amount: z.number().optional(), status: z.string() }),
+  timestamp: z.number(),
+});
+
+app.post('/webhook', async (req, res) => {
+  // Step 1: Verify signature [9]
+  const signature = req.headers['x-webhook-signature'];
+  const expected = crypto.createHmac('sha256', WEBHOOK_SECRET)
+    .update(JSON.stringify(req.body)).digest('hex');
+  if (!timingSafeEqual(Buffer.from(signature ?? ''), Buffer.from(expected))) {
+    return res.status(401).json({ error: 'Invalid signature' });
+  }
+
+  // Step 2: Parse payload [5]
+  const parsed = WebhookPayloadSchema.safeParse(req.body);
+  if (!parsed.success) return res.status(400).json({ error: 'Invalid payload' });
+
+  await processWebhookEvent(parsed.data);
+  res.sendStatus(200);
+});
+```
+
+---
+
+## Form Data Sanitization [3][4]
+
+Parse structure, then sanitize content. Output encoding prevents XSS.
+
+```typescript
+import DOMPurify from 'isomorphic-dompurify';
+
+const ProfileUpdateSchema = z.object({
+  bio: z.string().max(500).transform(s => DOMPurify.sanitize(s)),
+  website: z.string().url().optional(),
+  displayName: z.string().min(1).max(50),
+});
+
+app.post('/profile', async (req, res) => {
+  const parsed = ProfileUpdateSchema.safeParse(req.body);
+  if (!parsed.success) return res.status(400).json({ error: parsed.error });
+  await db.users.update(req.userId, parsed.data); // bio already sanitized
+  res.json({ success: true });
+});
+```
+
+---
+
+## GraphQL Input [3]
+
+```typescript
+const UserFilterSchema = z.object({
+  name: z.string().max(100).optional(),
+  email: z.string().email().optional(),
+  status: z.enum(['active', 'inactive']).optional(),
+  limit: z.number().int().min(1).max(100).default(20),
+});
+
+const resolvers = {
+  Query: {
+    users: async (_, { filter }) => {
+      const parsed = UserFilterSchema.safeParse(filter);
+      if (!parsed.success) {
+        throw new GraphQLError('Invalid filter', { extensions: { code: 'BAD_USER_INPUT' } });
+      }
+      return userService.findUsers(parsed.data);
+    },
+  },
+};
+```

package/src/assets/skills/boundary-validation/references/sources.md

@@ -0,0 +1,41 @@
+# Boundary Validation — Sources
+
+## Primary References
+
+| # | Source | Author(s) | Year | Access | Topics |
+|---|--------|-----------|------|--------|--------|
+| 1 | "Parse, don't validate" | Alexis King | 2019 | [Free](https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/) | Core principle: parsing vs validation, type-driven design |
+| 2 | "Secure by Design" Ch. 3–5 | Bernsmed, Deogun, Sawano | 2019 | Purchase | Domain primitives, trust boundaries, input validation architecture |
+| 3 | OWASP Input Validation Cheat Sheet | OWASP Foundation | 2024 | [Free](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html) | Allow-lists, deny-lists, canonicalization, validation strategies |
+| 4 | OWASP Top 10 (2021) | OWASP Foundation | 2021 | [Free](https://owasp.org/Top10/) | A03:Injection, A08:Software and Data Integrity Failures |
+| 5 | Zod Documentation | Colin McDonnell | 2024 | [Free](https://zod.dev) | TypeScript-first schema validation, safeParse, transforms, pipes |
+| 6 | "Railway Oriented Programming" | Scott Wlaschin | 2014 | [Free](https://fsharpforfunandprofit.com/rop/) | Result type composition, error handling as data flow |
+| 7 | CWE-20: Improper Input Validation | MITRE | 2024 | [Free](https://cwe.mitre.org/data/definitions/20.html) | Root cause taxonomy for input validation failures |
+| 8 | "The Twelve-Factor App" (III. Config) | Adam Wiggins | 2011 | [Free](https://12factor.net/config) | Environment-based config, strict separation, fail-fast startup |
+| 9 | OWASP Webhook Security | OWASP Foundation | 2024 | [Free](https://cheatsheetseries.owasp.org/cheatsheets/Webhook_Security_Cheat_Sheet.html) | Signature verification, replay protection, payload validation |
+| 10 | Pydantic Documentation | Samuel Colvin | 2024 | [Free](https://docs.pydantic.dev) | Python data validation, model_validate, strict mode, custom validators |
+| 11 | go-playground/validator | Dean Karn | 2024 | [Free](https://pkg.go.dev/github.com/go-playground/validator/v10) | Go struct validation, tag-based rules, custom validators |
+| 12 | Serde Documentation | David Tolnay | 2024 | [Free](https://serde.rs) | Rust serialization/deserialization framework |
+| 13 | validator (Rust crate) | Keats | 2024 | [Free](https://docs.rs/validator) | Derive-based Rust validation, struct-level and field-level rules |
+| 14 | Jakarta Bean Validation (JSR 380) | JCP | 2017 | [Free](https://beanvalidation.org/2.0/spec/) | Java annotation-based validation, constraint composition |
+| 15 | OWASP SQL Injection Prevention | OWASP Foundation | 2024 | [Free](https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html) | Parameterized queries, stored procedures, allow-list validation |
+
+## Standards & Specifications
+
+| # | Source | Org | Access | Topics |
+|---|--------|-----|--------|--------|
+| 16 | "Object-Oriented Software Construction" Ch. 11 | Bertrand Meyer | 1997 | Purchase | Design by Contract — preconditions, postconditions, invariants |
+| 17 | "Making illegal states unrepresentable" | Yaron Minsky | 2011 | [Free](https://blog.janestreet.com/effective-ml-video/) | Type-driven design, eliminating invalid states at compile time |
+| 18 | "Domain Modeling Made Functional" Ch. 3–4 | Scott Wlaschin | 2018 | Purchase | Constrained types, smart constructors, making invalid values impossible |
+| 19 | JSON Schema Specification | JSON Schema Org | 2020 | [Free](https://json-schema.org/specification) | Schema vocabulary, validation keywords, format annotations |
+| 20 | OpenAPI Specification 3.1 | OpenAPI Initiative | 2024 | [Free](https://spec.openapis.org/oas/latest.html) | API schema definitions, request/response validation |
+
+## Academic & Research
+
+| # | Source | Author(s) | Year | Access | Topics |
+|---|--------|-----------|------|--------|--------|
+| 21 | "The Emperor's Old Clothes" | C.A.R. Hoare | 1981 | [Free](https://dl.acm.org/doi/10.1145/358549.358561) | Billion-dollar mistake (null), importance of type safety |
+| 22 | "Propositions as Types" | Philip Wadler | 2015 | [Free](https://homepages.inf.ed.ac.uk/wadler/papers/propositions-as-types/propositions-as-types.pdf) | Curry-Howard correspondence — types as proofs of properties |
+| 23 | "Typestates for Objects" | Aldrich, Sunshine, Saini, Sparks | 2009 | [Free](https://www.cs.cmu.edu/~aldrich/papers/onward2009-state.pdf) | Typestate pattern — encoding protocol states in the type system |
+| 24 | NIST SP 800-53 Rev. 5 (SI-10) | NIST | 2020 | [Free](https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final) | Federal information input validation requirements |
+| 25 | "Robustness and Least Power" | Tim Berners-Lee | 2001 | [Free](https://www.w3.org/2001/tag/doc/leastPower.html) | Rule of Least Power — accept strictly, produce liberally (and when not to) |