@scallywag/validation 1.0.0 → 1.0.4

package/README.md

@@ -0,0 +1,1372 @@
+# Validation Module
+
+Production-grade validation framework built on Zod. Provides schema validation, input sanitization (XSS/SQL injection prevention), Next.js API middleware, environment variable validation, security middleware, rate limiting, and Zod-to-JSON-Schema conversion.
+
+## Directory Structure
+
+```
+packages/kernel/validation/
+├── index.ts                  # Central exports (re-exports middleware, schemas, types, validators, zod-schema-converter)
+├── types.ts                  # Type definitions and enums
+├── validators.ts             # Core validation functions and utilities
+├── schemas.ts                # Pre-built Zod schema collections
+├── sanitization.ts           # XSS/SQL injection prevention and string sanitization
+├── middleware.ts              # Next.js API route validation and security middleware
+├── env.ts                    # Environment variable validation and security scanning
+└── zod-schema-converter.ts   # Zod-to-JSON-Schema conversion utilities
+```
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                        VALIDATION SYSTEM                             │
+├──────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │                    Validators (Core)                            │  │
+│  │  validateData()           - Zod schema validation               │  │
+│  │  validateRequest()        - Request validation + sanitization   │  │
+│  │  validateFileUpload()     - File type/size validation           │  │
+│  │  batchValidate()          - Parallel validation                 │  │
+│  │  validateEnv()            - Environment variable validation     │  │
+│  │  parseAndValidateJSON()   - JSON parse + Zod validate           │  │
+│  │  createValidator()        - Type guard factory                  │  │
+│  │  createAsyncValidator()   - Async type guard factory            │  │
+│  │  createValidationDecorator() - Method decorator factory         │  │
+│  │  formatValidationErrors() - Error formatter for API responses   │  │
+│  │  hasErrorCode()           - Error code checker                  │  │
+│  │  getFieldErrors()         - Field-specific error extraction     │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+│                                                                      │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │                    Sanitization                                 │  │
+│  │  containsXssPatterns()    - XSS detection (no modification)     │  │
+│  │  sanitizeString()         - String sanitization with options     │  │
+│  │  sanitizeObjectStrings()  - Recursive deep object sanitization  │  │
+│  │  XSS_PATTERNS             - Regex patterns for XSS vectors      │  │
+│  │  SQL_PATTERNS             - Regex patterns for SQL injection     │  │
+│  │  HTML_ENTITIES            - Entity encoding map                  │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+│                                                                      │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │                   Pre-Built Schemas                             │  │
+│  │  primitiveSchemas   - email, url, uuid, dates, numbers          │  │
+│  │  securitySchemas    - safeString, safeFilename, strongPassword  │  │
+│  │  apiSchemas         - pagination, apiResponse, errorResponse    │  │
+│  │  authSchemas        - userRegistration, userLogin, jwtPayload   │  │
+│  │  fractalSchemas     - exportConfig, testConfig, cacheConfig     │  │
+│  │  envSchemas         - development, production                   │  │
+│  │  fileSchemas        - imageUpload, documentUpload               │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+│                                                                      │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │                    Middleware                                   │  │
+│  │  createValidationMiddleware() - Body/query/header/input         │  │
+│  │  createSecurityMiddleware()   - Bot/origin/auth checks          │  │
+│  │  createRateLimitMiddleware()  - Per-IP rate limiting             │  │
+│  │  createApiMiddleware()        - Comprehensive middleware stack   │  │
+│  │  withValidation()             - HOF for route handlers           │  │
+│  │  validateRoute()              - Method decorator for routes      │  │
+│  │  combineMiddleware()          - Middleware combinator            │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+│                                                                      │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │                Environment Validation                           │  │
+│  │  validateEnvironment()        - NODE_ENV-aware validation       │  │
+│  │  scanEnvironmentSecurity()    - Security issue scanning         │  │
+│  │  logEnvironmentValidation()   - Structured result logging       │  │
+│  │  initializeEnvironment()      - Startup validation (exits on    │  │
+│  │                                  failure)                        │  │
+│  │  processValidationResult()    - Result processing helper        │  │
+│  │  processValidationError()     - Error processing helper         │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+│                                                                      │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │              Zod Schema Converter                               │  │
+│  │  zodToJsonSchema()            - Zod -> JSON Schema              │  │
+│  │  safeZodToJsonSchema()        - Safe conversion (returns undef) │  │
+│  │  extractMethodSchemas()       - Input/output schema extraction  │  │
+│  │  isZodSchemaWithJsonSupport() - Runtime Zod 4 detection         │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## Type Definitions
+
+All types are defined in `types.ts`.
+
+### ValidationResult
+
+Discriminated union representing success or failure:
+
+```typescript
+type ValidationResult<T = unknown> =
+  | { success: true; data: T }
+  | { success: false; errors: ValidationError[] };
+```
+
+### ValidationError
+
+```typescript
+interface ValidationError {
+  field: string; // Dot-notation path (e.g. "address.city")
+  message: string; // Human-readable error message
+  code: string; // Zod error code or custom code
+  value?: unknown; // The received value (when available)
+}
+```
+
+### ValidationOptions
+
+```typescript
+interface ValidationOptions {
+  strict?: boolean; // Fail on unknown fields
+  stripUnknown?: boolean; // Remove unknown fields
+  errorMap?: z.ZodErrorMap; // Custom Zod error messages
+  async?: boolean; // Use parseAsync instead of parse
+}
+```
+
+### SanitizationOptions
+
+```typescript
+interface SanitizationOptions {
+  html?: boolean; // HTML entity encoding (default: false)
+  sql?: boolean; // SQL injection protection (default: true in sanitizeString)
+  xss?: boolean; // XSS pattern removal (default: true in sanitizeString)
+  trim?: boolean; // Trim whitespace (default: true in sanitizeString)
+  lowercase?: boolean; // Convert to lowercase
+  uppercase?: boolean; // Convert to uppercase
+}
+```
+
+### SecurityLevel
+
+```typescript
+enum SecurityLevel {
+  LOW = 'low', // No checks (pass-through)
+  MEDIUM = 'medium', // Bot detection
+  HIGH = 'high', // Bot + automated tool detection + origin required
+  CRITICAL = 'critical', // Bot + automated + scripting detection + origin + auth required
+}
+```
+
+### EndpointValidation
+
+Configuration for validation middleware. Supports two modes: unified input or legacy separate schemas.
+
+```typescript
+interface EndpointValidation {
+  input?: z.ZodSchema; // Unified: merges body + query + params into one validated object
+  output?: z.ZodSchema; // Response validation schema
+  body?: z.ZodSchema; // Legacy: request body schema
+  query?: z.ZodSchema; // Legacy: query parameter schema
+  params?: z.ZodSchema; // Legacy: URL parameter schema
+  headers?: z.ZodSchema; // Header validation schema (works with both modes)
+  response?: z.ZodSchema; // Response schema (alias for output)
+}
+```
+
+### FractalValidationContext
+
+```typescript
+interface FractalValidationContext {
+  interface: string; // e.g. 'api', 'cli', 'mcp', 'sdk'
+  method?: string; // HTTP method
+  path?: string; // Route path
+  securityLevel: SecurityLevel; // Required security level
+  userRole?: string; // Current user role
+  permissions?: string[]; // Current user permissions
+}
+```
+
+### FieldMetadata
+
+```typescript
+interface FieldMetadata {
+  required: boolean;
+  type: string;
+  description?: string;
+  examples?: unknown[];
+  constraints?: Record<string, unknown>;
+}
+```
+
+### SchemaMetadata
+
+```typescript
+interface SchemaMetadata {
+  name: string;
+  description: string;
+  version: string;
+  fields: Record<string, FieldMetadata>;
+}
+```
+
+### ValidationRule
+
+```typescript
+type ValidationRuleType =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'array'
+  | 'object'
+  | 'email'
+  | 'url'
+  | 'uuid'
+  | 'date'
+  | 'custom';
+
+interface ValidationRule {
+  field: string;
+  type: ValidationRuleType;
+  required: boolean;
+  constraints?: {
+    min?: number;
+    max?: number;
+    pattern?: string;
+    enum?: unknown[];
+    custom?: (value: unknown) => boolean | string;
+  };
+  message?: string;
+}
+```
+
+## Full API Surface
+
+### validators.ts
+
+#### `validateData<T>(schema, data, options?): Promise<ValidationResult<T>>`
+
+Core validation function. Parses data against a Zod schema, returning a typed discriminated union.
+
+- Uses `schema.parseAsync()` when `options.async` is true, otherwise `schema.parse()`
+- Maps `ZodError` issues to `ValidationError[]` with dot-notation field paths
+- Non-Zod errors produce a single error with field `'unknown'` and code `'unknown_error'`
+
+```typescript
+import { validateData } from '@scallywag/kernel/validation';
+import { z } from 'zod';
+
+const schema = z.object({
+  email: z.string().email(),
+  age: z.number().min(18),
+});
+
+const result = await validateData(schema, { email: 'a@b.com', age: 25 });
+if (result.success) {
+  // result.data: { email: string; age: number }
+}
+```
+
+#### `validateRequest<T>(schema, data, context?): Promise<ValidationResult<T>>`
+
+Validates data with automatic pre-sanitization. When data is an object, runs `sanitizeObjectStrings()` before validation. Sets `strict: true` when `context.securityLevel === 'critical'`.
+
+```typescript
+import { validateRequest, SecurityLevel } from '@scallywag/kernel/validation';
+
+const result = await validateRequest(userSchema, requestBody, {
+  interface: 'api',
+  securityLevel: SecurityLevel.HIGH,
+});
+```
+
+#### `validateFileUpload(file, allowedTypes, maxSize): ValidationResult<File>`
+
+Synchronous file validation. Checks:
+
+1. File is not null/undefined
+2. `file.type` is in `allowedTypes` array
+3. `file.size` does not exceed `maxSize` (bytes)
+
+Returns all applicable errors (not just the first).
+
+```typescript
+import { validateFileUpload } from '@scallywag/kernel/validation';
+
+const result = validateFileUpload(
+  file,
+  ['image/jpeg', 'image/png', 'image/webp'],
+  5 * 1024 * 1024
+);
+```
+
+#### `batchValidate<T>(schema, dataArray, options?): Promise<Array<ValidationResult<T>>>`
+
+Validates an array of values in parallel using `Promise.all`. Each element is independently validated against the same schema.
+
+```typescript
+const results = await batchValidate(userSchema, [user1, user2, user3]);
+const valid = results.filter((r) => r.success);
+const invalid = results.filter((r) => !r.success);
+```
+
+#### `validateEnv<T>(schema): T`
+
+Parses `process.env` against a Zod schema. Throws on failure with formatted error messages showing `path: message` per issue.
+
+```typescript
+const env = validateEnv(
+  z.object({
+    DATABASE_URL: z.string().url(),
+    PORT: z.coerce.number().default(3000),
+  })
+);
+```
+
+#### `createValidator<T>(schema): (data: unknown) => data is T`
+
+Creates a synchronous type guard function from a Zod schema.
+
+```typescript
+const isUser = createValidator(userSchema);
+
+if (isUser(unknownData)) {
+  // unknownData is narrowed to User type
+}
+```
+
+#### `createAsyncValidator<T>(schema): (data: unknown) => Promise<boolean>`
+
+Creates an async validator function. Returns `true`/`false` without throwing.
+
+```typescript
+const isValidAsync = createAsyncValidator(asyncSchema);
+const valid = await isValidAsync(data);
+```
+
+#### `createValidationDecorator<T>(schema, options?): MethodDecorator`
+
+Creates a method decorator that validates the first argument before calling the method. Replaces the first argument with the validated/parsed data. Throws on validation failure.
+
+```typescript
+class UserService {
+  @createValidationDecorator(createUserSchema)
+  async createUser(data: CreateUserInput) {
+    // data is guaranteed valid
+  }
+}
+```
+
+#### `parseAndValidateJSON<T>(schema, jsonString): T`
+
+Combines `JSON.parse()` with Zod validation. Throws `SyntaxError` for invalid JSON, `ZodError` for invalid data.
+
+```typescript
+const user = parseAndValidateJSON(
+  userSchema,
+  '{"email":"a@b.com","name":"Jo"}'
+);
+```
+
+#### `safeParseAndValidateJSON<T>(schema, jsonString): ValidationResult<T>`
+
+Safe version of `parseAndValidateJSON` that returns a `ValidationResult` instead of throwing. Distinguishes JSON parse errors (code `'invalid_json'`) from Zod validation errors.
+
+```typescript
+const result = safeParseAndValidateJSON(userSchema, rawJson);
+if (result.success) {
+  console.log(result.data);
+} else {
+  // result.errors[0].code might be 'invalid_json' or a Zod error code
+}
+```
+
+#### `formatValidationErrors(errors): Record<string, string[]>`
+
+Groups validation errors by field name into a field-to-messages map. Suitable for API error responses.
+
+```typescript
+// Input:  [{ field: 'email', message: 'Invalid', code: 'invalid_string' }]
+// Output: { email: ['Invalid'] }
+```
+
+#### `hasErrorCode(result, code): boolean`
+
+Checks if a failed `ValidationResult` contains a specific error code.
+
+```typescript
+if (hasErrorCode(result, 'too_small')) {
+  // Handle minimum length violation
+}
+```
+
+#### `getFieldErrors(result, field): ValidationError[]`
+
+Extracts all errors for a specific field from a `ValidationResult`.
+
+```typescript
+const emailErrors = getFieldErrors(result, 'email');
+```
+
+### sanitization.ts
+
+#### Constants
+
+```typescript
+// XSS detection patterns
+const XSS_PATTERNS = {
+  scriptTags: /<script[^>]*>.*?<\/script>/gi,
+  iframeTags: /<iframe[^>]*>.*?<\/iframe>/gi,
+  javascriptProtocol: /javascript:/gi,
+  vbscriptProtocol: /vbscript:/gi,
+  eventHandlers: /on\w+=/gi,
+};
+
+// SQL injection patterns
+const SQL_PATTERNS = {
+  specialChars: /['";\\]/g,
+  keywords: /\b(union|select|insert|update|delete|drop|exec|execute)\b/gi,
+};
+
+// HTML entity encoding map
+const HTML_ENTITIES: Record<string, string> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#x27;',
+};
+```
+
+#### `containsXssPatterns(value): boolean`
+
+Detection-only check. Returns `true` if string contains `<script` tags, event handlers (`on*=`), or `javascript:` protocol. Does not modify the string.
+
+```typescript
+if (containsXssPatterns(userInput)) {
+  // Reject input
+}
+```
+
+#### `sanitizeString(input, options?): string`
+
+Applies sanitization transforms in order:
+
+1. **Trim** (default on, disable with `trim: false`)
+2. **XSS removal** (default on, disable with `xss: false`) - strips script/iframe tags, javascript:/vbscript: protocols, event handlers
+3. **SQL removal** (default on, disable with `sql: false`) - strips quotes, semicolons, backslashes, SQL keywords
+4. **HTML encoding** (default off, enable with `html: true`) - encodes `& < > " '` to entities
+5. **Case transform** - `lowercase: true` or `uppercase: true` (mutually exclusive, lowercase checked first)
+
+```typescript
+const clean = sanitizeString('<script>alert("xss")</script>Hello', {
+  xss: true,
+  sql: true,
+  html: false,
+  trim: true,
+});
+// Result: "Hello"
+```
+
+#### `sanitizeObjectStrings(obj): unknown`
+
+Recursively walks an object/array structure and applies `sanitizeString()` with `{ xss: true, sql: true, trim: true }` to every string value. Non-string/non-object values pass through unchanged.
+
+```typescript
+const safe = sanitizeObjectStrings({
+  name: '  <script>xss</script>John  ',
+  tags: ['hello', '<iframe>bad</iframe>'],
+  count: 42,
+});
+// Result: { name: 'John', tags: ['hello', ''], count: 42 }
+```
+
+### schemas.ts
+
+All schemas are exported as named object collections.
+
+#### `primitiveSchemas`
+
+| Key              | Schema                                 | Description              |
+| ---------------- | -------------------------------------- | ------------------------ |
+| `nonEmptyString` | `z.string().min(1)`                    | Non-empty string         |
+| `email`          | `z.string().email()`                   | Email format             |
+| `url`            | `z.string().url()`                     | URL format               |
+| `uuid`           | `z.string().uuid()`                    | UUID format              |
+| `positiveInt`    | `z.number().int().positive()`          | Positive integer         |
+| `nonNegativeInt` | `z.number().int().min(0)`              | Non-negative integer     |
+| `percentage`     | `z.number().min(0).max(100)`           | 0-100 range              |
+| `isoDate`        | `z.string().datetime()`                | ISO 8601 datetime string |
+| `futureDate`     | `z.date().refine(d => d > new Date())` | Date in the future       |
+| `booleanString`  | `z.enum(['true','false']).transform()` | String to boolean        |
+
+#### `securitySchemas`
+
+| Key              | Description                                                                                   |
+| ---------------- | --------------------------------------------------------------------------------------------- |
+| `safeString`     | Rejects strings with `<script`, `javascript:`, `data:`, `vbscript:`, or `on*=` event handlers |
+| `safeFilename`   | Rejects `<>:"/\|?*` characters and `..` path traversal                                        |
+| `sqlSafeString`  | Rejects SQL keywords (union, select, insert, update, delete, drop, exec, execute)             |
+| `strongPassword` | Min 8 chars, requires uppercase + lowercase + digit + special character                       |
+
+#### `apiSchemas`
+
+| Key                       | Description                                                                                           |
+| ------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `pagination`              | `{ page, limit, sortBy?, sortOrder }` with coercion and defaults (page=1, limit=20, sortOrder='desc') |
+| `apiResponse(dataSchema)` | Generic wrapper: `{ success, data?, error?, timestamp, requestId }`                                   |
+| `errorResponse`           | `{ success: false, error, details?: [{ field, message, code }], timestamp, requestId }`               |
+
+#### `authSchemas`
+
+| Key                | Description                                                                   |
+| ------------------ | ----------------------------------------------------------------------------- |
+| `userRegistration` | `{ email, password(strong), firstName, lastName, acceptTerms(must be true) }` |
+| `userLogin`        | `{ email, password, rememberMe? }`                                            |
+| `jwtPayload`       | `{ sub(uuid), email, roles[], permissions[], iat, exp }`                      |
+
+#### `fractalSchemas`
+
+| Key                | Description                                                                                               |
+| ------------------ | --------------------------------------------------------------------------------------------------------- |
+| `exportConfig`     | `{ interfaces(api/cli/sdk/webhook), method?, path?, description, version?, authentication?, rateLimit? }` |
+| `testConfig`       | `{ categories[], priority, timeout?, retries, parallel }`                                                 |
+| `validationConfig` | `{ rules[], securityLevel, sanitize }`                                                                    |
+| `cacheConfig`      | `{ ttl, key, strategy, invalidateOn?, compress }`                                                         |
+| `authConfig`       | `{ roles[], permissions?, requireAll, allowAnonymous, sessionRequired }`                                  |
+
+#### `envSchemas`
+
+| Key           | Description                                                                                              |
+| ------------- | -------------------------------------------------------------------------------------------------------- |
+| `development` | `NODE_ENV='development'`, optional DATABASE_URL/API_KEY, DEBUG defaults true                             |
+| `production`  | `NODE_ENV='production'`, required DATABASE_URL, API_KEY(min 32), JWT_SECRET(min 32), DEBUG must be false |
+
+#### `fileSchemas`
+
+| Key              | Description                                                              |
+| ---------------- | ------------------------------------------------------------------------ |
+| `imageUpload`    | `{ filename(safe), mimetype(jpeg/png/gif/webp), size(max 5MB), buffer }` |
+| `documentUpload` | `{ filename(safe), mimetype(pdf/text/json), size(max 10MB), buffer }`    |
+
+### middleware.ts
+
+#### `createValidationMiddleware(config: EndpointValidation)`
+
+Returns an async function `(request, context?, params?) => NextResponse | { validatedData }`.
+
+Two validation modes:
+
+1. **Unified input** (`config.input`): Merges query params + URL params + body into one object, validates against `config.input`. Still validates `config.headers` separately.
+2. **Legacy** (`config.body`/`config.query`/`config.headers`): Validates each part independently.
+
+On failure: returns `NextResponse` with status 400, `{ success: false, error, details, timestamp }`.
+On success: returns `{ validatedData: { body?, query?, headers?, input? } }`.
+
+```typescript
+const middleware = createValidationMiddleware({
+  input: z.object({ title: z.string(), category: z.string() }),
+});
+
+const result = await middleware(request, undefined, { id: '123' });
+```
+
+#### `validateRoute(config: EndpointValidation)`
+
+Method decorator. Wraps a route handler method to run validation before execution. Extracts route params from the Next.js context argument automatically.
+
+```typescript
+class EventsController {
+  @validateRoute({ input: CreateEventSchema })
+  async POST(request: NextRequest, validatedData: Record<string, unknown>) {
+    // validatedData.input contains validated merged input
+  }
+}
+```
+
+#### `withValidation(config, handler)`
+
+Higher-order function wrapping a route handler with validation. Extracts route params from the context argument.
+
+```typescript
+export const POST = withValidation(
+  { body: createUserSchema },
+  async (request, validatedData, context) => {
+    const user = await createUser(validatedData['body']);
+    return NextResponse.json(user);
+  }
+);
+```
+
+#### `createSecurityMiddleware(securityLevel?): (request) => NextResponse | null`
+
+Returns synchronous middleware. Returns `null` to pass, or a 403 `NextResponse` on failure.
+
+| Level      | Checks                                                                                                    |
+| ---------- | --------------------------------------------------------------------------------------------------------- |
+| `LOW`      | Always passes                                                                                             |
+| `MEDIUM`   | Blocks bot/crawler/spider user agents                                                                     |
+| `HIGH`     | Blocks bot/crawler/spider/curl/wget + requires `Origin` header                                            |
+| `CRITICAL` | Blocks bot/crawler/spider/curl/wget/python/ruby/php + requires `Origin` + requires `Authorization` header |
+
+```typescript
+const security = createSecurityMiddleware(SecurityLevel.HIGH);
+const result = security(request);
+if (result) return result; // 403 response
+```
+
+#### `createRateLimitMiddleware(requests?, windowMs?)`
+
+IP-based rate limiting using `MemoryRateLimitStore`. Defaults: 100 requests per 60000ms. Extracts IP from `x-forwarded-for` or `x-real-ip` headers, falls back to `127.0.0.1`.
+
+Returns `null` to pass, or a 429 `NextResponse` with rate limit headers:
+
+- `X-RateLimit-Limit`
+- `X-RateLimit-Remaining`
+- `X-RateLimit-Reset`
+- `Retry-After`
+
+```typescript
+const rateLimit = createRateLimitMiddleware(50, 30000); // 50 req / 30s
+const result = rateLimit(request);
+if (result) return result; // 429 response
+```
+
+#### `combineMiddleware(...middlewares)`
+
+Composes multiple synchronous middleware functions. Runs each in order; returns the first non-null response (short-circuits).
+
+```typescript
+const combined = combineMiddleware(
+  createSecurityMiddleware(SecurityLevel.MEDIUM),
+  createRateLimitMiddleware(100, 60000)
+);
+const result = combined(request);
+if (result) return result;
+```
+
+#### `createApiMiddleware(options)`
+
+Comprehensive middleware stack combining security, rate limiting, and validation. Returns an async function `(request, handler, context?) => NextResponse`.
+
+```typescript
+const apiMiddleware = createApiMiddleware({
+  security: SecurityLevel.HIGH,
+  rateLimit: { requests: 100, windowMs: 60000 },
+  validation: { body: createEventSchema },
+});
+
+return apiMiddleware(request, async (req, validatedData) => {
+  return NextResponse.json({ success: true });
+});
+```
+
+#### `safeExtractValidatedData(result): Record<string, unknown>`
+
+Extracts `validatedData` from a middleware result object. Returns empty object if not present.
+
+### env.ts
+
+#### `validateEnvironment()`
+
+Validates `process.env` against the appropriate Zod schema based on `NODE_ENV`:
+
+- `'production'` -> `productionEnvSchema` (strict: DATABASE_URL required, JWT_SECRET min 32, DEBUG must be false)
+- `'development'` -> `developmentEnvSchema` (relaxed: optional fields, DEBUG defaults true)
+- `'test'` or other -> `baseEnvSchema`
+
+Also runs `scanEnvironmentSecurity()` and fails if security errors are found.
+
+Returns: `{ success, data?, errors?, securityScan }`
+
+#### `scanEnvironmentSecurity()`
+
+Scans all `process.env` entries for security issues:
+
+- **Production requirements**: checks DATABASE_URL and JWT_SECRET exist in production
+- **Weak secrets**: detects variables with names matching `/secret|password|pass|pwd|key|token|auth|api|private|credential/i` that have weak values (test, dev, default, 123456, admin, root) or short length (<16 chars)
+- **Recommendations**: always-present general security advice
+
+Returns: `{ warnings: string[], errors: string[], recommendations: string[] }`
+
+#### `logEnvironmentValidation(result)`
+
+Logs validation results using the structured logger:
+
+- Success/failure status
+- Security errors (error level)
+- Security warnings (warn level)
+- Recommendations (info level)
+
+#### `initializeEnvironment(): boolean`
+
+Runs `validateEnvironment()` and `logEnvironmentValidation()`. Calls `process.exit(1)` if validation fails. Returns `true` on success.
+
+#### `processValidationResult(validatedEnv, securityScan)`
+
+Helper that combines Zod validation result with security scan. Fails if security scan has errors.
+
+#### `processValidationError(error, securityScan)`
+
+Helper that formats validation errors into the standard result structure.
+
+### zod-schema-converter.ts
+
+#### `zodToJsonSchema(schema): JsonSchema`
+
+Converts a Zod schema to JSON Schema using Zod 4's native `toJSONSchema()` method. Throws if the schema doesn't support this method.
+
+```typescript
+const userSchema = z.object({ name: z.string(), age: z.number() });
+const jsonSchema = zodToJsonSchema(userSchema);
+// { type: 'object', properties: { name: { type: 'string' }, age: { type: 'number' } }, ... }
+```
+
+#### `safeZodToJsonSchema(schema?): JsonSchema | undefined`
+
+Safe wrapper around `zodToJsonSchema`. Returns `undefined` if schema is undefined or conversion fails.
+
+#### `extractMethodSchemas(inputSchema?, outputSchema?): MethodSchemas`
+
+Convenience function that converts both input and output Zod schemas to JSON Schema.
+
+```typescript
+interface MethodSchemas {
+  input?: JsonSchema | undefined;
+  output?: JsonSchema | undefined;
+}
+```
+
+#### `isZodSchemaWithJsonSupport(value): value is ZodSchema`
+
+Runtime check for whether a value is a Zod schema with `toJSONSchema()`, `parse()`, and `safeParse()` methods.
+
+## Error Handling Patterns
+
+### Discriminated Union Results
+
+All validation functions return `ValidationResult<T>`, a discriminated union. Always check `result.success` before accessing `.data` or `.errors`.
+
+```typescript
+const result = await validateData(schema, data);
+if (result.success) {
+  // TypeScript narrows: result.data is T
+  processData(result.data);
+} else {
+  // TypeScript narrows: result.errors is ValidationError[]
+  const formatted = formatValidationErrors(result.errors);
+  return NextResponse.json(
+    { success: false, details: formatted },
+    { status: 400 }
+  );
+}
+```
+
+### Middleware Error Responses
+
+Validation middleware returns structured JSON error responses:
+
+```json
+{
+  "success": false,
+  "error": "Validation failed",
+  "details": {
+    "email": ["Invalid email format"],
+    "age": ["Must be a positive integer"]
+  },
+  "timestamp": "2025-01-29T12:00:00.000Z"
+}
+```
+
+Security middleware returns:
+
+```json
+{
+  "success": false,
+  "error": "Security check failed",
+  "timestamp": "2025-01-29T12:00:00.000Z"
+}
+```
+
+Rate limit middleware returns (with headers):
+
+```json
+{
+  "success": false,
+  "error": "Rate limit exceeded",
+  "retryAfter": 45,
+  "timestamp": "2025-01-29T12:00:00.000Z"
+}
+```
+
+### Environment Validation Errors
+
+`validateEnvironment()` returns a structured result. `initializeEnvironment()` exits the process on failure, so callers never see the error.
+
+```typescript
+const result = validateEnvironment();
+if (!result.success) {
+  // result.errors: string[] - human-readable error messages
+  // result.securityScan.warnings: string[] - security warnings
+  // result.securityScan.recommendations: string[] - improvement suggestions
+}
+```
+
+## Use Cases
+
+### 1. Validate API Request Body
+
+```typescript
+import { validateData } from '@scallywag/kernel/validation';
+import { z } from 'zod';
+
+const CreateEventSchema = z.object({
+  title: z.string().min(1).max(200),
+  date: z.string().datetime(),
+  capacity: z.number().int().positive().max(10000),
+});
+
+async function handleRequest(body: unknown) {
+  const result = await validateData(CreateEventSchema, body);
+  if (!result.success) {
+    return { status: 400, errors: result.errors };
+  }
+  return createEvent(result.data);
+}
+```
+
+### 2. Sanitize User Input Before Storage
+
+```typescript
+import {
+  sanitizeString,
+  sanitizeObjectStrings,
+} from '@scallywag/kernel/validation';
+
+// Single field
+const safeName = sanitizeString(rawName, { xss: true, sql: true, trim: true });
+
+// Entire request body
+const safeBody = sanitizeObjectStrings(requestBody);
+```
+
+### 3. Validate and Sanitize Together
+
+```typescript
+import { validateRequest, SecurityLevel } from '@scallywag/kernel/validation';
+
+const result = await validateRequest(commentSchema, requestBody, {
+  interface: 'api',
+  securityLevel: SecurityLevel.HIGH,
+});
+// Body is sanitized (XSS/SQL stripped) THEN validated against schema
+```
+
+### 4. Validate File Uploads
+
+```typescript
+import { validateFileUpload } from '@scallywag/kernel/validation';
+
+const result = validateFileUpload(
+  uploadedFile,
+  ['image/jpeg', 'image/png', 'image/webp'],
+  5 * 1024 * 1024
+);
+if (!result.success) {
+  // result.errors may contain type AND size errors simultaneously
+}
+```
+
+### 5. Next.js API Route with Middleware
+
+```typescript
+import { withValidation } from '@scallywag/kernel/validation';
+import { z } from 'zod';
+
+const schema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+
+export const POST = withValidation(
+  { body: schema },
+  async (request, validatedData) => {
+    const { email, password } = validatedData['body'] as {
+      email: string;
+      password: string;
+    };
+    return NextResponse.json({ success: true });
+  }
+);
+```
+
+### 6. Unified Input Validation (Preferred for New Endpoints)
+
+```typescript
+import { createValidationMiddleware } from '@scallywag/kernel/validation';
+import { z } from 'zod';
+
+const middleware = createValidationMiddleware({
+  input: z.object({
+    id: z.string().uuid(), // from URL params
+    title: z.string().min(1), // from body
+    format: z.string().optional(), // from query string
+  }),
+});
+
+// Middleware merges query + params + body into one object
+const result = await middleware(request, undefined, { id: routeParamId });
+```
+
+### 7. Security Middleware
+
+```typescript
+import {
+  createSecurityMiddleware,
+  SecurityLevel,
+} from '@scallywag/kernel/validation';
+
+const security = createSecurityMiddleware(SecurityLevel.CRITICAL);
+
+export async function GET(request: NextRequest) {
+  const secResult = security(request);
+  if (secResult) return secResult; // 403 for bots, missing origin, missing auth
+  // ... handle request
+}
+```
+
+### 8. Rate Limiting
+
+```typescript
+import { createRateLimitMiddleware } from '@scallywag/kernel/validation';
+
+const rateLimit = createRateLimitMiddleware(100, 60000);
+
+export async function POST(request: NextRequest) {
+  const limited = rateLimit(request);
+  if (limited) return limited; // 429 with Retry-After
+  // ... handle request
+}
+```
+
+### 9. Combined Middleware Stack
+
+```typescript
+import {
+  combineMiddleware,
+  createSecurityMiddleware,
+  createRateLimitMiddleware,
+  SecurityLevel,
+} from '@scallywag/kernel/validation';
+
+const middleware = combineMiddleware(
+  createSecurityMiddleware(SecurityLevel.HIGH),
+  createRateLimitMiddleware(50, 30000)
+);
+
+const blocked = middleware(request);
+if (blocked) return blocked;
+```
+
+### 10. Full API Middleware
+
+```typescript
+import {
+  createApiMiddleware,
+  SecurityLevel,
+} from '@scallywag/kernel/validation';
+
+const api = createApiMiddleware({
+  security: SecurityLevel.HIGH,
+  rateLimit: { requests: 100, windowMs: 60000 },
+  validation: {
+    body: z.object({ name: z.string() }),
+    query: z.object({ page: z.coerce.number().default(1) }),
+  },
+});
+
+export async function POST(request: NextRequest) {
+  return api(request, async (req, validatedData) => {
+    return NextResponse.json({ data: validatedData });
+  });
+}
+```
+
+### 11. Batch Validation
+
+```typescript
+import { batchValidate } from '@scallywag/kernel/validation';
+
+const results = await batchValidate(userSchema, [user1, user2, user3]);
+const allValid = results.every((r) => r.success);
+```
+
+### 12. Type Guards from Schemas
+
+```typescript
+import {
+  createValidator,
+  createAsyncValidator,
+} from '@scallywag/kernel/validation';
+
+const isUser = createValidator(userSchema);
+const items: unknown[] = [
+  /* ... */
+];
+const users = items.filter(isUser); // User[]
+
+const isValidAsync = createAsyncValidator(asyncRefinedSchema);
+if (await isValidAsync(data)) {
+  // data passes async validation
+}
+```
+
+### 13. Validation Decorator on Class Methods
+
+```typescript
+import { createValidationDecorator } from '@scallywag/kernel/validation';
+
+class PaymentService {
+  @createValidationDecorator(paymentSchema)
+  async processPayment(input: PaymentInput) {
+    // input is guaranteed to be valid
+  }
+}
+```
+
+### 14. Route Decorator
+
+```typescript
+import { validateRoute } from '@scallywag/kernel/validation';
+
+class EventsController {
+  @validateRoute({
+    input: z.object({ title: z.string(), category: z.string() }),
+    headers: z.object({ 'x-api-key': z.string() }),
+  })
+  async POST(request: NextRequest, validatedData: Record<string, unknown>) {
+    const input = validatedData['input'];
+    const headers = validatedData['headers'];
+  }
+}
+```
+
+### 15. JSON String Parse + Validate
+
+```typescript
+import {
+  parseAndValidateJSON,
+  safeParseAndValidateJSON,
+} from '@scallywag/kernel/validation';
+
+// Throwing version
+try {
+  const user = parseAndValidateJSON(userSchema, jsonString);
+} catch (e) {
+  // SyntaxError or ZodError
+}
+
+// Safe version
+const result = safeParseAndValidateJSON(userSchema, jsonString);
+if (!result.success) {
+  // Check result.errors[0].code === 'invalid_json' for parse errors
+}
+```
+
+### 16. Environment Validation at Startup
+
+```typescript
+import { initializeEnvironment } from '@scallywag/kernel/validation/env';
+
+// Exits process if environment is invalid
+initializeEnvironment();
+```
+
+### 17. Manual Environment Validation
+
+```typescript
+import {
+  validateEnvironment,
+  logEnvironmentValidation,
+} from '@scallywag/kernel/validation/env';
+
+const result = validateEnvironment();
+logEnvironmentValidation(result);
+
+if (!result.success) {
+  console.error('Env errors:', result.errors);
+  console.warn('Security warnings:', result.securityScan.warnings);
+}
+```
+
+### 18. Environment Security Scan
+
+```typescript
+import { scanEnvironmentSecurity } from '@scallywag/kernel/validation/env';
+
+const scan = scanEnvironmentSecurity();
+if (scan.errors.length > 0) {
+  // Missing required production variables
+}
+if (scan.warnings.length > 0) {
+  // Weak secrets, short keys, etc.
+}
+```
+
+### 19. Using Pre-built Security Schemas
+
+```typescript
+import {
+  securitySchemas,
+  primitiveSchemas,
+} from '@scallywag/kernel/validation';
+
+const commentSchema = z.object({
+  author: securitySchemas.safeString.min(1).max(100),
+  body: securitySchemas.safeString.min(1).max(5000),
+  email: primitiveSchemas.email,
+});
+```
+
+### 20. Using Pre-built API Schemas
+
+```typescript
+import { apiSchemas } from '@scallywag/kernel/validation';
+
+// Pagination with coercion (query strings come as strings)
+const query = apiSchemas.pagination.parse({
+  page: '3', // coerced to 3
+  limit: '50', // coerced to 50
+});
+
+// Generic API response wrapper
+const responseSchema = apiSchemas.apiResponse(z.object({ id: z.string() }));
+```
+
+### 21. Zod to JSON Schema Conversion
+
+```typescript
+import {
+  zodToJsonSchema,
+  extractMethodSchemas,
+} from '@scallywag/kernel/validation';
+
+const inputSchema = z.object({ title: z.string() });
+const jsonSchema = zodToJsonSchema(inputSchema);
+// Use for OpenAPI docs, MCP tool definitions, etc.
+
+const schemas = extractMethodSchemas(inputSchema, outputSchema);
+// { input: JsonSchema, output: JsonSchema }
+```
+
+### 22. Error Inspection Utilities
+
+```typescript
+import {
+  hasErrorCode,
+  getFieldErrors,
+  formatValidationErrors,
+} from '@scallywag/kernel/validation';
+
+const result = await validateData(schema, data);
+if (!result.success) {
+  if (hasErrorCode(result, 'too_small')) {
+    // Handle minimum constraint violation
+  }
+
+  const emailErrors = getFieldErrors(result, 'email');
+  // All errors specifically for the 'email' field
+
+  const formatted = formatValidationErrors(result.errors);
+  // { email: ['Invalid email format'], name: ['Required'] }
+}
+```
+
+### 23. Using File Schemas
+
+```typescript
+import { fileSchemas } from '@scallywag/kernel/validation';
+
+const result = fileSchemas.imageUpload.safeParse({
+  filename: 'photo.jpg',
+  mimetype: 'image/jpeg',
+  size: 1024000,
+  buffer: fileBuffer,
+});
+```
+
+### 24. XSS Detection Without Modification
+
+```typescript
+import { containsXssPatterns } from '@scallywag/kernel/validation';
+
+// Pure detection - reject rather than sanitize
+if (containsXssPatterns(userInput)) {
+  throw new Error('Input contains unsafe patterns');
+}
+```
+
+## Testing Patterns
+
+Tests are located in `packages/kernel/__tests__/core/validation/`.
+
+### Testing Validation Functions
+
+```typescript
+import { validateData } from '@scallywag/kernel/validation';
+import { z } from 'zod';
+
+describe('validateData', () => {
+  const schema = z.object({
+    email: z.string().email(),
+    age: z.number().min(18),
+  });
+
+  it('returns success with valid data', async () => {
+    const result = await validateData(schema, { email: 'a@b.com', age: 25 });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.email).toBe('a@b.com');
+    }
+  });
+
+  it('returns errors with invalid data', async () => {
+    const result = await validateData(schema, { email: 'bad', age: 5 });
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.errors).toHaveLength(2);
+      expect(result.errors[0]?.field).toBe('email');
+    }
+  });
+});
+```
+
+### Testing Sanitization
+
+```typescript
+import {
+  sanitizeString,
+  containsXssPatterns,
+  sanitizeObjectStrings,
+} from '@scallywag/kernel/validation';
+
+describe('sanitizeString', () => {
+  it('removes script tags', () => {
+    expect(sanitizeString('<script>alert(1)</script>Hello')).toBe('Hello');
+  });
+
+  it('removes SQL special chars by default', () => {
+    expect(sanitizeString("Robert'; DROP TABLE users;--")).not.toContain("'");
+  });
+
+  it('encodes HTML entities when html option enabled', () => {
+    expect(
+      sanitizeString('<b>bold</b>', { html: true, xss: false, sql: false })
+    ).toBe('&lt;b&gt;bold&lt;/b&gt;');
+  });
+});
+
+describe('sanitizeObjectStrings', () => {
+  it('recursively sanitizes nested objects', () => {
+    const result = sanitizeObjectStrings({
+      nested: { value: '<script>xss</script>safe' },
+    });
+    expect(
+      (result as Record<string, Record<string, string>>).nested.value
+    ).toBe('safe');
+  });
+});
+```
+
+### Testing Middleware
+
+```typescript
+import {
+  createValidationMiddleware,
+  createSecurityMiddleware,
+  SecurityLevel,
+} from '@scallywag/kernel/validation';
+import { NextRequest } from 'next/server';
+import { z } from 'zod';
+
+describe('createValidationMiddleware', () => {
+  it('returns 400 for invalid body', async () => {
+    const middleware = createValidationMiddleware({
+      body: z.object({ name: z.string() }),
+    });
+
+    const request = new NextRequest('http://localhost/api/test', {
+      method: 'POST',
+      body: JSON.stringify({ name: 123 }),
+    });
+
+    const result = await middleware(request);
+    expect('status' in result && result.status).toBe(400);
+  });
+});
+
+describe('createSecurityMiddleware', () => {
+  it('blocks bot user agents at MEDIUM level', () => {
+    const security = createSecurityMiddleware(SecurityLevel.MEDIUM);
+    const request = new NextRequest('http://localhost/api/test', {
+      headers: { 'user-agent': 'Googlebot/2.1' },
+    });
+    const result = security(request);
+    expect(result).not.toBeNull();
+    expect(result?.status).toBe(403);
+  });
+});
+```
+
+### Testing Environment Validation
+
+```typescript
+import {
+  scanEnvironmentSecurity,
+  validateEnvironment,
+} from '@scallywag/kernel/validation/env';
+
+describe('scanEnvironmentSecurity', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  afterAll(() => {
+    process.env = originalEnv;
+  });
+
+  it('reports missing required vars in production', () => {
+    process.env['NODE_ENV'] = 'production';
+    delete process.env['DATABASE_URL'];
+    const result = scanEnvironmentSecurity();
+    expect(result.errors.length).toBeGreaterThan(0);
+  });
+});
+```
+
+### Testing Zod Schema Converter
+
+```typescript
+import {
+  zodToJsonSchema,
+  isZodSchemaWithJsonSupport,
+} from '@scallywag/kernel/validation';
+
+describe('zodToJsonSchema', () => {
+  it('throws for schemas without toJSONSchema', () => {
+    const fakeSchema = { parse: () => {}, safeParse: () => {} };
+    expect(() => zodToJsonSchema(fakeSchema as never)).toThrow();
+  });
+});
+```
+
+## Exports
+
+`index.ts` re-exports from:
+
+- `./middleware` - all middleware functions, `EndpointValidation`, `safeExtractValidatedData`
+- `./schemas` - all schema collections
+- `./types` - all type definitions and enums
+- `./validators` - all validation functions and sanitization re-exports
+- `./zod-schema-converter` - all JSON Schema conversion utilities
+
+Note: `./sanitization` is not directly re-exported from index but is re-exported through `./validators` (`sanitizeString`, `sanitizeObjectStrings`, `containsXssPatterns`, `XSS_PATTERNS`, `SQL_PATTERNS`, `HTML_ENTITIES`).
+
+Note: `./env` is NOT re-exported from index. Import directly from `@scallywag/kernel/validation/env`.