@orchestrator-claude/definitions 3.5.0

package/kb/validation-patterns.md

@@ -0,0 +1,589 @@
+---
+title: "Validation Patterns"
+category: "patterns"
+tier: "foundational"
+tags: ["api", "validation", "zod", "security"]
+template: "api"
+---
+
+# Validation Patterns
+
+## Overview
+
+This document defines validation patterns and best practices for ensuring data integrity and security in REST APIs using Zod for runtime type validation.
+
+**Project**: my-project
+**Template**: api
+
+---
+
+## 1. Why Validation Matters
+
+### Security
+
+- **Prevent injection attacks**: SQL, NoSQL, XSS
+- **Prevent buffer overflows**: Limit string/array sizes
+- **Type safety at runtime**: TypeScript only validates at compile time
+
+### Data Integrity
+
+- **Consistent data**: Enforce business rules at entry point
+- **Clear error messages**: Help clients fix invalid requests
+- **Fail fast**: Catch errors early in request lifecycle
+
+---
+
+## 2. Zod Schema Basics
+
+### Installation
+
+```bash
+npm install zod
+```
+
+### Basic Types
+
+```typescript
+import { z } from 'zod';
+
+// Primitives
+const stringSchema = z.string();
+const numberSchema = z.number();
+const booleanSchema = z.boolean();
+const dateSchema = z.date();
+
+// String validations
+const emailSchema = z.string().email();
+const urlSchema = z.string().url();
+const uuidSchema = z.string().uuid();
+const minMaxSchema = z.string().min(1).max(100);
+
+// Number validations
+const positiveSchema = z.number().positive();
+const intSchema = z.number().int();
+const rangeSchema = z.number().min(0).max(100);
+
+// Optional and nullable
+const optionalSchema = z.string().optional();
+const nullableSchema = z.string().nullable();
+
+// Arrays
+const arraySchema = z.array(z.string());
+const nonEmptyArraySchema = z.array(z.string()).nonempty();
+const minLengthArraySchema = z.array(z.string()).min(1).max(10);
+```
+
+---
+
+## 3. Object Schemas
+
+### Basic Object
+
+```typescript
+const UserSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email(),
+  age: z.number().int().positive().optional(),
+  role: z.enum(['user', 'admin', 'moderator']),
+  createdAt: z.date(),
+});
+
+// Infer TypeScript type from schema
+type User = z.infer<typeof UserSchema>;
+```
+
+### Nested Objects
+
+```typescript
+const AddressSchema = z.object({
+  street: z.string(),
+  city: z.string(),
+  state: z.string().length(2), // US state code
+  zipCode: z.string().regex(/^\d{5}$/),
+});
+
+const UserWithAddressSchema = z.object({
+  name: z.string(),
+  email: z.string().email(),
+  address: AddressSchema,
+});
+```
+
+### Partial and Pick
+
+```typescript
+// Make all fields optional
+const PartialUserSchema = UserSchema.partial();
+
+// Pick specific fields
+const UserLoginSchema = UserSchema.pick({
+  email: true,
+  password: true,
+});
+
+// Omit specific fields
+const UserWithoutPasswordSchema = UserSchema.omit({
+  password: true,
+});
+```
+
+---
+
+## 4. Request Validation Schemas
+
+### Create Schemas
+
+```typescript
+// POST /api/v1/users
+const CreateUserSchema = z.object({
+  name: z.string().min(1, 'Name is required').max(100),
+  email: z.string().email('Invalid email format'),
+  password: z
+    .string()
+    .min(8, 'Password must be at least 8 characters')
+    .regex(
+      /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/,
+      'Password must contain uppercase, lowercase, and number'
+    ),
+  role: z.enum(['user', 'admin']).default('user'),
+});
+
+type CreateUserInput = z.infer<typeof CreateUserSchema>;
+```
+
+### Update Schemas
+
+```typescript
+// PATCH /api/v1/users/:id
+const UpdateUserSchema = z.object({
+  name: z.string().min(1).max(100).optional(),
+  email: z.string().email().optional(),
+  age: z.number().int().positive().optional(),
+}).strict(); // Disallow unknown fields
+
+type UpdateUserInput = z.infer<typeof UpdateUserSchema>;
+```
+
+### Query Parameter Schemas
+
+```typescript
+// GET /api/v1/users?page=1&limit=20&role=admin
+const ListUsersQuerySchema = z.object({
+  page: z.coerce.number().int().positive().default(1),
+  limit: z.coerce.number().int().positive().max(100).default(20),
+  role: z.enum(['user', 'admin', 'moderator']).optional(),
+  sort: z.enum(['name', 'email', 'createdAt']).default('createdAt'),
+  order: z.enum(['asc', 'desc']).default('desc'),
+});
+
+type ListUsersQuery = z.infer<typeof ListUsersQuerySchema>;
+```
+
+### Path Parameter Schemas
+
+```typescript
+// GET /api/v1/users/:id
+const UserIdParamSchema = z.object({
+  id: z.string().uuid('Invalid user ID format'),
+});
+
+type UserIdParam = z.infer<typeof UserIdParamSchema>;
+```
+
+---
+
+## 5. Validation Middleware
+
+### Generic Validation Middleware
+
+```typescript
+// src/presentation/middleware/validate.ts
+import type { Request, Response, NextFunction } from 'express';
+import type { z } from 'zod';
+
+export type ValidateTarget = 'body' | 'query' | 'params';
+
+export function validate<T extends z.ZodSchema>(
+  schema: T,
+  target: ValidateTarget = 'body'
+) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const data = req[target];
+    const result = schema.safeParse(data);
+
+    if (!result.success) {
+      return res.status(400).json({
+        error: 'ValidationError',
+        message: 'Request validation failed',
+        details: result.error.issues.map(issue => ({
+          path: issue.path.join('.'),
+          message: issue.message,
+          code: issue.code,
+        })),
+        timestamp: new Date().toISOString(),
+        path: req.path,
+      });
+    }
+
+    // Replace with validated data (with defaults applied)
+    req[target] = result.data;
+    next();
+  };
+}
+```
+
+### Usage in Routes
+
+```typescript
+import { validate } from '../middleware/validate';
+import { CreateUserSchema, UpdateUserSchema, ListUsersQuerySchema } from '../schemas/user';
+
+// Create user
+router.post(
+  '/api/v1/users',
+  validate(CreateUserSchema, 'body'),
+  async (req, res, next) => {
+    // req.body is now validated and typed
+    const result = await createUserUseCase.execute(req.body);
+    res.status(201).json(result);
+  }
+);
+
+// Update user
+router.patch(
+  '/api/v1/users/:id',
+  validate(UserIdParamSchema, 'params'),
+  validate(UpdateUserSchema, 'body'),
+  async (req, res, next) => {
+    // req.params.id and req.body are validated
+    const result = await updateUserUseCase.execute({
+      userId: req.params.id,
+      ...req.body,
+    });
+    res.json(result);
+  }
+);
+
+// List users with query params
+router.get(
+  '/api/v1/users',
+  validate(ListUsersQuerySchema, 'query'),
+  async (req, res, next) => {
+    // req.query is validated with defaults
+    const result = await listUsersUseCase.execute(req.query);
+    res.json(result);
+  }
+);
+```
+
+---
+
+## 6. Custom Validations
+
+### Refine for Complex Rules
+
+```typescript
+const PasswordChangeSchema = z
+  .object({
+    oldPassword: z.string(),
+    newPassword: z.string().min(8),
+    confirmPassword: z.string(),
+  })
+  .refine((data) => data.newPassword === data.confirmPassword, {
+    message: "Passwords don't match",
+    path: ['confirmPassword'], // Error will be on confirmPassword field
+  })
+  .refine((data) => data.oldPassword !== data.newPassword, {
+    message: 'New password must be different from old password',
+    path: ['newPassword'],
+  });
+```
+
+### Transform Values
+
+```typescript
+const TrimmedStringSchema = z.string().transform((val) => val.trim());
+
+const LowercaseEmailSchema = z
+  .string()
+  .email()
+  .transform((val) => val.toLowerCase());
+
+const CreateUserSchema = z.object({
+  name: TrimmedStringSchema,
+  email: LowercaseEmailSchema,
+});
+```
+
+### Custom Validators
+
+```typescript
+function isValidCreditCard(value: string): boolean {
+  // Luhn algorithm implementation
+  return /^\d{16}$/.test(value); // Simplified
+}
+
+const PaymentSchema = z.object({
+  cardNumber: z.string().refine(isValidCreditCard, {
+    message: 'Invalid credit card number',
+  }),
+  cvv: z.string().regex(/^\d{3,4}$/),
+  expiry: z
+    .string()
+    .regex(/^\d{2}\/\d{2}$/)
+    .refine((val) => {
+      const [month, year] = val.split('/').map(Number);
+      const now = new Date();
+      const expiry = new Date(2000 + year, month - 1);
+      return expiry > now;
+    }, 'Card has expired'),
+});
+```
+
+---
+
+## 7. Sanitization
+
+### Input Sanitization
+
+```typescript
+import validator from 'validator';
+
+const SanitizedStringSchema = z
+  .string()
+  .transform((val) => validator.escape(val)); // Escape HTML entities
+
+const SafeUserInputSchema = z.object({
+  comment: z
+    .string()
+    .max(1000)
+    .transform((val) => validator.escape(val)),
+  username: z
+    .string()
+    .regex(/^[a-zA-Z0-9_-]+$/, 'Username can only contain alphanumeric characters, underscores, and hyphens'),
+});
+```
+
+---
+
+## 8. File Upload Validation
+
+### Multer + Zod
+
+```typescript
+import multer from 'multer';
+
+const upload = multer({
+  limits: {
+    fileSize: 5 * 1024 * 1024, // 5MB
+  },
+  fileFilter: (req, file, cb) => {
+    const allowedMimes = ['image/jpeg', 'image/png', 'image/gif'];
+
+    if (!allowedMimes.includes(file.mimetype)) {
+      return cb(new Error('Invalid file type'));
+    }
+
+    cb(null, true);
+  },
+});
+
+const FileUploadSchema = z.object({
+  title: z.string().min(1).max(100),
+  description: z.string().max(500).optional(),
+});
+
+router.post(
+  '/api/v1/uploads',
+  upload.single('file'),
+  validate(FileUploadSchema, 'body'),
+  async (req, res) => {
+    if (!req.file) {
+      return res.status(400).json({ error: 'File is required' });
+    }
+
+    // Process file and validated body
+    const result = await uploadFileUseCase.execute({
+      file: req.file,
+      ...req.body,
+    });
+
+    res.status(201).json(result);
+  }
+);
+```
+
+---
+
+## 9. Testing Validation
+
+### Test Valid Inputs
+
+```typescript
+import request from 'supertest';
+import { app } from '../src/server';
+
+describe('POST /api/v1/users - Validation', () => {
+  it('should accept valid user data', async () => {
+    const validUser = {
+      name: 'John Doe',
+      email: 'john@example.com',
+      password: 'SecureP@ss123',
+    };
+
+    await request(app)
+      .post('/api/v1/users')
+      .send(validUser)
+      .expect(201);
+  });
+
+  it('should reject invalid email', async () => {
+    const invalidUser = {
+      name: 'John Doe',
+      email: 'not-an-email',
+      password: 'SecureP@ss123',
+    };
+
+    const response = await request(app)
+      .post('/api/v1/users')
+      .send(invalidUser)
+      .expect(400);
+
+    expect(response.body.error).toBe('ValidationError');
+    expect(response.body.details).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          path: 'email',
+          message: expect.stringContaining('Invalid email'),
+        }),
+      ])
+    );
+  });
+
+  it('should reject weak password', async () => {
+    const invalidUser = {
+      name: 'John Doe',
+      email: 'john@example.com',
+      password: 'weak',
+    };
+
+    const response = await request(app)
+      .post('/api/v1/users')
+      .send(invalidUser)
+      .expect(400);
+
+    expect(response.body.details).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          path: 'password',
+          message: expect.stringContaining('at least 8 characters'),
+        }),
+      ])
+    );
+  });
+
+  it('should reject unknown fields when strict', async () => {
+    const userWithExtra = {
+      name: 'John Doe',
+      email: 'john@example.com',
+      password: 'SecureP@ss123',
+      extraField: 'should-not-be-here',
+    };
+
+    await request(app)
+      .post('/api/v1/users')
+      .send(userWithExtra)
+      .expect(400);
+  });
+});
+```
+
+---
+
+## 10. Best Practices
+
+### DO
+
+1. **Validate all inputs**: Body, query, params, headers
+2. **Use strict mode**: `.strict()` to reject unknown fields
+3. **Transform and sanitize**: Trim, lowercase, escape HTML
+4. **Provide clear error messages**: Help clients fix issues
+5. **Test edge cases**: Empty strings, negative numbers, large files
+6. **Set limits**: Max string length, array size, file size
+7. **Use enums**: For fixed sets of values
+
+### DON'T
+
+1. **Don't trust client input**: Always validate on server
+2. **Don't expose internal errors**: Sanitize error messages
+3. **Don't skip validation**: Even for "trusted" clients
+4. **Don't validate in use cases**: Validate at API boundary
+5. **Don't use regex for complex logic**: Use `.refine()`
+
+---
+
+## 11. Common Schemas
+
+### Email
+
+```typescript
+const EmailSchema = z
+  .string()
+  .email()
+  .transform((val) => val.toLowerCase());
+```
+
+### Password
+
+```typescript
+const PasswordSchema = z
+  .string()
+  .min(8, 'Password must be at least 8 characters')
+  .regex(
+    /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])/,
+    'Password must contain uppercase, lowercase, number, and special character'
+  );
+```
+
+### Phone Number
+
+```typescript
+const PhoneSchema = z
+  .string()
+  .regex(/^\+?[1-9]\d{1,14}$/, 'Invalid phone number format (E.164)');
+```
+
+### URL
+
+```typescript
+const URLSchema = z.string().url();
+```
+
+### Date Range
+
+```typescript
+const DateRangeSchema = z
+  .object({
+    startDate: z.coerce.date(),
+    endDate: z.coerce.date(),
+  })
+  .refine((data) => data.endDate > data.startDate, {
+    message: 'End date must be after start date',
+    path: ['endDate'],
+  });
+```
+
+---
+
+## References
+
+- [Zod Documentation](https://zod.dev/)
+- [OWASP Input Validation](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html)
+- [validator.js](https://github.com/validatorjs/validator.js)
+
+---
+
+**Generated for**: my-project
+**Template**: api
+**Constitution Preset**: orchestrator