Input Validation

Input Validation

Validate and sanitize all untrusted input using Zod v4 and Pydantic.

Overview

• Processing user input
• Query parameters
• Form submissions
• API request bodies
• File uploads
• URL validation

Core Principles

1. Never trust user input 2. Validate on server-side (client-side is UX only) 3. Use allowlists (not blocklists) 4. Validate type, length, format, range

Quick Reference

Zod v4 Schema

import { z } from 'zod';

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2).max(100),
  age: z.coerce.number().int().min(0).max(150),
  role: z.enum(['user', 'admin']).default('user'),
});

const result = UserSchema.safeParse(req.body);
if (!result.success) {
  return res.status(400).json({ errors: result.error.flatten() });
}

Type Coercion (v4)

// Query params come as strings - coerce to proper types
z.coerce.number()  // "123" → 123
z.coerce.boolean() // "true" → true
z.coerce.date()    // "2024-01-01" → Date

Discriminated Unions

const ShapeSchema = z.discriminatedUnion('type', [
  z.object({ type: z.literal('circle'), radius: z.number() }),
  z.object({ type: z.literal('rectangle'), width: z.number(), height: z.number() }),
]);

Pydantic (Python)

from pydantic import BaseModel, EmailStr, Field

class User(BaseModel):
    email: EmailStr
    name: str = Field(min_length=2, max_length=100)
    age: int = Field(ge=0, le=150)

Anti-Patterns (FORBIDDEN)

// ❌ NEVER rely on client-side validation only
if (formIsValid) submit();  // No server validation

// ❌ NEVER use blocklists
const blocked = ['password', 'secret'];  // Easy to miss fields

// ❌ NEVER trust Content-Type header
if (file.type === 'image/png') {...}  // Can be spoofed

// ❌ NEVER build queries with string concat
"SELECT * FROM users WHERE name = '" + name + "'"  // SQL injection

// ✅ ALWAYS validate server-side
const result = schema.safeParse(req.body);

// ✅ ALWAYS use allowlists
const allowed = ['name', 'email', 'createdAt'];

// ✅ ALWAYS validate file magic bytes
const isPng = buffer[0] === 0x89 && buffer[1] === 0x50;

// ✅ ALWAYS use parameterized queries
db.query('SELECT * FROM users WHERE name = ?', [name]);

Key Decisions

Detailed Documentation

Related Skills

• owasp-top-10 - Injection prevention
• auth-patterns - User input in auth
• type-safety-validation - TypeScript patterns

Capability Details

schema-validation

Keywords: schema, validate, Zod, Pydantic, validation Solves:

• Validate input against schemas
• Define validation rules declaratively
• Handle validation errors gracefully

type-coercion

Keywords: coerce, coercion, type conversion, parse Solves:

• Automatically convert input types
• Parse strings to numbers/dates
• Handle type mismatches

allowlist-validation

Keywords: allowlist, whitelist, enum, literal, allowed values Solves:

• Validate against allowed values
• Prevent injection attacks
• Restrict input to safe options

html-sanitization

Keywords: sanitize, HTML, XSS, escape, DOMPurify Solves:

• Sanitize HTML input safely
• Prevent XSS attacks
• Allow safe HTML subset

file-validation

Keywords: file, upload, MIME type, file size, file type Solves:

• Validate file uploads securely
• Check file content not just extension
• Enforce size limits

error-formatting

Keywords: error, error message, validation error, user-friendly Solves:

• Format validation errors for users
• Avoid exposing internal details
• Provide actionable error messages

Input Validation Checklist

Core Principles

• [ ] Never trust user input - validate everything
• [ ] Validate server-side - client-side is UX only
• [ ] Use allowlists - not blocklists
• [ ] Validate type, length, format, range
• [ ] Sanitize output - escape when rendering

Schema Definition

• [ ] Define schema for all API endpoints
• [ ] Use strict types (no any)
• [ ] Set reasonable min/max lengths
• [ ] Use enums for fixed value sets
• [ ] Add custom error messages
• [ ] Handle optional vs required properly

String Validation

• [ ] Trim whitespace where appropriate
• [ ] Set maximum length (prevent DoS)
• [ ] Use regex for format validation
• [ ] Escape HTML for display
• [ ] Validate email with proper regex
• [ ] Validate URLs against allowlist domains

Number Validation

• [ ] Use integer for IDs
• [ ] Set min/max bounds
• [ ] Handle NaN and Infinity
• [ ] Use coercion for query params

File Validation

• [ ] Check file extension
• [ ] Validate MIME type
• [ ] Verify magic bytes (actual content)
• [ ] Set maximum file size
• [ ] Scan for malware (production)
• [ ] Generate new filename (no user input)

Database Query Safety

• [ ] Use parameterized queries
• [ ] Allowlist sort columns
• [ ] Validate pagination limits
• [ ] Escape identifiers if dynamic

Error Messages

• [ ] Generic errors for users
• [ ] Detailed errors in logs only
• [ ] Don't reveal system internals
• [ ] Don't reveal valid usernames/emails

Validation Libraries

TypeScript/JavaScript

import { z } from 'zod';
import { zodResolver } from '@hookform/resolvers/zod';
import DOMPurify from 'dompurify';

Python

from pydantic import BaseModel, EmailStr, Field
from markupsafe import escape

Common Patterns

Allowlist (✅ Do)

const allowed = ['name', 'email', 'createdAt'];
if (!allowed.includes(sortColumn)) throw new Error('Invalid');

Blocklist (❌ Don't)

const blocked = ['password', 'secret'];
if (blocked.includes(field)) throw new Error('Invalid');
// Problem: Forgets to block new sensitive fields

Type Coercion

• [ ] Use z.coerce.* for query parameters
• [ ] Handle empty strings appropriately
• [ ] Consider timezone for dates
• [ ] Parse numbers from strings safely

Async Validation

• [ ] Use for uniqueness checks (email, username)
• [ ] Rate limit async validations
• [ ] Cache validation results where appropriate
• [ ] Handle race conditions

Security Headers

Content-Security-Policy: default-src 'self'
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

Review Checklist

Before PR:

• [ ] All endpoints have input validation
• [ ] Server-side validation implemented
• [ ] Allowlists used instead of blocklists
• [ ] Error messages don't leak info
• [ ] File uploads validate content, not just extension
• [ ] SQL queries use parameterized statements
• [ ] HTML output is escaped
• [ ] Maximum lengths set on all strings

Common Vulnerabilities to Prevent

Input Validation Patterns

API Request Validation (TypeScript)

import { z } from 'zod';

// Request body schema
const CreateUserSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8).max(100),
  name: z.string().min(2).max(100).transform(s => s.trim()),
  role: z.enum(['user', 'admin']).default('user'),
  metadata: z.record(z.string()).optional(),
});

type CreateUserRequest = z.infer<typeof CreateUserSchema>;

// Express middleware
function validateBody<T extends z.ZodSchema>(schema: T) {
  return (req: Request, res: Response, next: NextFunction) => {
    const result = schema.safeParse(req.body);
    if (!result.success) {
      return res.status(400).json({
        error: 'Validation failed',
        details: result.error.flatten().fieldErrors,
      });
    }
    req.body = result.data;
    next();
  };
}

// Usage
app.post('/api/users', validateBody(CreateUserSchema), async (req, res) => {
  const user = req.body as CreateUserRequest;
  // user is fully typed and validated
});

Query Parameter Validation

const PaginationSchema = z.object({
  page: z.coerce.number().int().positive().default(1),
  limit: z.coerce.number().int().min(1).max(100).default(20),
  sort: z.enum(['name', 'email', 'createdAt']).default('createdAt'),
  order: z.enum(['asc', 'desc']).default('desc'),
});

function validateQuery<T extends z.ZodSchema>(schema: T) {
  return (req: Request, res: Response, next: NextFunction) => {
    const result = schema.safeParse(req.query);
    if (!result.success) {
      return res.status(400).json({
        error: 'Invalid query parameters',
        details: result.error.flatten().fieldErrors,
      });
    }
    req.query = result.data;
    next();
  };
}

app.get('/api/users', validateQuery(PaginationSchema), (req, res) => {
  const { page, limit, sort, order } = req.query;
  // All values are properly typed and defaulted
});

Discriminated Union for Polymorphic Data

const NotificationSchema = z.discriminatedUnion('type', [
  z.object({
    type: z.literal('email'),
    email: z.string().email(),
    subject: z.string().min(1),
    body: z.string().min(1),
  }),
  z.object({
    type: z.literal('sms'),
    phone: z.string().regex(/^\+[1-9]\d{1,14}$/),
    message: z.string().max(160),
  }),
  z.object({
    type: z.literal('push'),
    deviceToken: z.string().min(1),
    title: z.string().max(50),
    body: z.string().max(200),
  }),
]);

type Notification = z.infer<typeof NotificationSchema>;

// Type-safe handling
function sendNotification(notification: Notification) {
  switch (notification.type) {
    case 'email':
      return sendEmail(notification.email, notification.subject, notification.body);
    case 'sms':
      return sendSMS(notification.phone, notification.message);
    case 'push':
      return sendPush(notification.deviceToken, notification.title, notification.body);
  }
}

Allowlist Validation

// Only allow specific values
const SortColumnSchema = z.enum(['name', 'email', 'createdAt', 'updatedAt']);

// For dynamic allowlists
function createAllowlistSchema<T extends string>(allowed: readonly T[]) {
  return z.enum(allowed as [T, ...T[]]);
}

const allowedColumns = ['name', 'email', 'createdAt'] as const;
const DynamicSortSchema = createAllowlistSchema(allowedColumns);

File Upload Validation

const FileUploadSchema = z.object({
  file: z.object({
    name: z.string(),
    type: z.enum(['image/jpeg', 'image/png', 'image/webp', 'application/pdf']),
    size: z.number().max(5 * 1024 * 1024, 'File must be under 5MB'),
  }),
});

// Validate file content (magic bytes)
const imageMagicBytes: Record<string, number[]> = {
  'image/jpeg': [0xFF, 0xD8, 0xFF],
  'image/png': [0x89, 0x50, 0x4E, 0x47],
  'image/webp': [0x52, 0x49, 0x46, 0x46],
  'application/pdf': [0x25, 0x50, 0x44, 0x46],
};

function validateFileContent(buffer: Buffer, mimeType: string): boolean {
  const expected = imageMagicBytes[mimeType];
  if (!expected) return false;
  return expected.every((byte, i) => buffer[i] === byte);
}

URL Validation with Domain Allowlist

const ALLOWED_DOMAINS = ['api.example.com', 'cdn.example.com'] as const;

const UrlSchema = z.string()
  .url()
  .refine(
    (url) => {
      const { hostname, protocol } = new URL(url);
      return protocol === 'https:' && ALLOWED_DOMAINS.includes(hostname as any);
    },
    { message: 'URL must be HTTPS and from allowed domains' }
  );

// Usage
UrlSchema.parse('https://api.example.com/data'); // OK
UrlSchema.parse('https://evil.com/data');        // Error
UrlSchema.parse('http://api.example.com/data');  // Error (not HTTPS)

Python (Pydantic) Validation

from pydantic import BaseModel, EmailStr, Field, field_validator
from typing import Literal, Union

# Basic model
class UserCreate(BaseModel):
    email: EmailStr
    name: str = Field(min_length=2, max_length=100)
    age: int = Field(ge=0, le=150)
    
    @field_validator('name')
    @classmethod
    def strip_and_title(cls, v: str) -> str:
        return v.strip().title()

# Discriminated union
class EmailNotification(BaseModel):
    type: Literal['email']
    email: EmailStr
    subject: str
    body: str

class SMSNotification(BaseModel):
    type: Literal['sms']
    phone: str
    message: str = Field(max_length=160)

Notification = Union[EmailNotification, SMSNotification]

# Allowlist validation
ALLOWED_COLUMNS = frozenset(['name', 'email', 'created_at'])

def validate_sort_column(column: str) -> str:
    if column not in ALLOWED_COLUMNS:
        raise ValueError(f"Invalid sort column: {column}")
    return column

HTML Sanitization

from markupsafe import escape

@app.route('/comment', methods=['POST'])
def create_comment():
    # Escape HTML to prevent XSS
    content = escape(request.form['content'])
    db.execute("INSERT INTO comments (content) VALUES (?)", [content])

import DOMPurify from 'dompurify';

// Sanitize HTML input
const sanitizedHtml = DOMPurify.sanitize(userInput, {
  ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'a'],
  ALLOWED_ATTR: ['href'],
});

Form Validation with React Hook Form

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';

const SignupSchema = z.object({
  email: z.string().email('Invalid email'),
  password: z.string()
    .min(8, 'Password must be at least 8 characters')
    .regex(/[A-Z]/, 'Must contain uppercase')
    .regex(/[0-9]/, 'Must contain number'),
  confirmPassword: z.string(),
}).refine(data => data.password === data.confirmPassword, {
  message: "Passwords don't match",
  path: ['confirmPassword'],
});

type SignupForm = z.infer<typeof SignupSchema>;

function SignupForm() {
  const { register, handleSubmit, formState: { errors } } = useForm<SignupForm>({
    resolver: zodResolver(SignupSchema),
  });

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('email')} placeholder="Email" />
      {errors.email && <span className="error">{errors.email.message}</span>}
      
      <input {...register('password')} type="password" placeholder="Password" />
      {errors.password && <span className="error">{errors.password.message}</span>}
      
      <input {...register('confirmPassword')} type="password" placeholder="Confirm" />
      {errors.confirmPassword && <span className="error">{errors.confirmPassword.message}</span>}
      
      <button type="submit">Sign Up</button>
    </form>
  );
}

Zod v4 API Reference

Installation

npm install zod@latest

Basic Types

import { z } from 'zod';

// Primitives
const stringSchema = z.string();
const numberSchema = z.number();
const booleanSchema = z.boolean();
const dateSchema = z.date();
const bigintSchema = z.bigint();

// String validations
z.string().min(1)           // Non-empty
z.string().max(100)         // Max length
z.string().email()          // Email format
z.string().url()            // URL format
z.string().uuid()           // UUID format
z.string().regex(/pattern/) // Custom pattern
z.string().trim()           // Trim whitespace
z.string().toLowerCase()    // Lowercase

// Number validations
z.number().int()            // Integer only
z.number().positive()       // > 0
z.number().nonnegative()    // >= 0
z.number().min(0)           // >= 0
z.number().max(100)         // <= 100
z.number().finite()         // Not Infinity

Type Coercion (v4 Feature)

Automatically coerce input to desired type:

// Coerce to string
const stringSchema = z.coerce.string();
stringSchema.parse(123);        // "123"
stringSchema.parse(true);       // "true"

// Coerce to number
const numberSchema = z.coerce.number();
numberSchema.parse("123");      // 123
numberSchema.parse("3.14");     // 3.14

// Coerce to boolean
const booleanSchema = z.coerce.boolean();
booleanSchema.parse("true");    // true
booleanSchema.parse("1");       // true
booleanSchema.parse("");        // false

// Coerce to date
const dateSchema = z.coerce.date();
dateSchema.parse("2024-01-01"); // Date object
dateSchema.parse(1704067200000); // Date object

// Coerce to bigint
const bigintSchema = z.coerce.bigint();
bigintSchema.parse("9007199254740991"); // BigInt

Objects

const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string().min(2).max(100),
  age: z.number().int().positive().optional(),
  role: z.enum(['user', 'admin', 'moderator']),
  createdAt: z.coerce.date(),
});

// Infer TypeScript type
type User = z.infer<typeof UserSchema>;

// Parse and validate
const user = UserSchema.parse(data);

// Safe parse (no throw)
const result = UserSchema.safeParse(data);
if (result.success) {
  console.log(result.data);
} else {
  console.log(result.error.errors);
}

Discriminated Unions (Recommended)

More efficient than regular unions:

const ShapeSchema = z.discriminatedUnion('type', [
  z.object({
    type: z.literal('circle'),
    radius: z.number().positive(),
  }),
  z.object({
    type: z.literal('rectangle'),
    width: z.number().positive(),
    height: z.number().positive(),
  }),
  z.object({
    type: z.literal('triangle'),
    base: z.number().positive(),
    height: z.number().positive(),
  }),
]);

type Shape = z.infer<typeof ShapeSchema>;

// Usage
const circle = ShapeSchema.parse({ type: 'circle', radius: 5 });

Transforms

Transform data during validation:

// Transform to uppercase
const uppercaseSchema = z.string().transform(s => s.toUpperCase());
uppercaseSchema.parse("hello"); // "HELLO"

// Compute derived field
const UserInputSchema = z.object({
  firstName: z.string(),
  lastName: z.string(),
}).transform(data => ({
  ...data,
  fullName: `${data.firstName} ${data.lastName}`,
}));

// Parse string to object
const jsonSchema = z.string().transform((str, ctx) => {
  try {
    return JSON.parse(str);
  } catch {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: "Invalid JSON",
    });
    return z.NEVER;
  }
});

Refinements

Custom validation logic:

// Simple refinement
const passwordSchema = z.string()
  .min(8)
  .refine(
    (val) => /[A-Z]/.test(val),
    { message: "Must contain uppercase letter" }
  )
  .refine(
    (val) => /[0-9]/.test(val),
    { message: "Must contain number" }
  );

// Super refinement (multiple issues)
const formSchema = z.object({
  password: z.string().min(8),
  confirmPassword: z.string(),
}).superRefine((data, ctx) => {
  if (data.password !== data.confirmPassword) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: "Passwords don't match",
      path: ["confirmPassword"],
    });
  }
});

Async Refinements

For async validation (e.g., database checks):

const usernameSchema = z.string()
  .min(3)
  .refine(
    async (username) => {
      const exists = await checkUsernameExists(username);
      return !exists;
    },
    { message: "Username already taken" }
  );

// Must use parseAsync
const result = await usernameSchema.parseAsync("newuser");

Error Handling

import { z, ZodError } from 'zod';

try {
  UserSchema.parse(invalidData);
} catch (error) {
  if (error instanceof ZodError) {
    // Formatted errors
    console.log(error.format());
    
    // Flat errors
    console.log(error.flatten());
    
    // Issues array
    error.issues.forEach(issue => {
      console.log(issue.path, issue.message);
    });
  }
}

// Custom error map
const customErrorMap: z.ZodErrorMap = (issue, ctx) => {
  if (issue.code === z.ZodIssueCode.invalid_type) {
    return { message: `Expected ${issue.expected}, received ${issue.received}` };
  }
  return { message: ctx.defaultError };
};

z.setErrorMap(customErrorMap);

React Hook Form Integration

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';

const FormSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

type FormData = z.infer<typeof FormSchema>;

function MyForm() {
  const { register, handleSubmit, formState: { errors } } = useForm<FormData>({
    resolver: zodResolver(FormSchema),
  });

  const onSubmit = (data: FormData) => {
    console.log(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('email')} />
      {errors.email && <span>{errors.email.message}</span>}
      
      <input type="password" {...register('password')} />
      {errors.password && <span>{errors.password.message}</span>}
      
      <button type="submit">Submit</button>
    </form>
  );
}

Pydantic Comparison (Python)

from pydantic import BaseModel, EmailStr, Field, field_validator

class User(BaseModel):
    email: EmailStr
    name: str = Field(min_length=2, max_length=100)
    age: int = Field(ge=0, le=150)
    
    @field_validator('name')
    @classmethod
    def name_must_be_title_case(cls, v: str) -> str:
        return v.title()

# Usage
user = User(email="test@example.com", name="john doe", age=25)
print(user.name)  # "John Doe"

External Links

• Zod Documentation
• Zod v4 Changelog
• React Hook Form + Zod
• Pydantic Documentation