Eve library

Input Validation and Sanitization Guide

Guide

Revision 1

On this page

Overview#

Lilith implements comprehensive input validation and sanitization across all services to ensure data integrity, security, and compliance. The system uses JSON Schema validation with AJV, DOMPurify for HTML sanitization, and custom security checks to protect against common attack vectors.

Input Validation Middleware#

Basic Usage#

javascript
const {
  InputValidationMiddleware,
  VALIDATION_SCHEMAS,
} = require('@lilith/lib');

// Initialize validation middleware
const validation = new InputValidationMiddleware({
  serviceName: 'content-service',
  environment: process.env.ENVIRONMENT,
});

await validation.initialize();

// Apply validation to Fastify route
app.post(
  '/v1/content',
  {
    preHandler: validation.createValidationMiddleware('content', {
      sanitization: { max_length: 5000, strip_html: true },
      security: { xss: true, content_safety: true },
    }),
  },
  async (request, reply) => {
    // request.validatedInput contains sanitized and validated data
    const content = request.validatedInput;
    reply.send({ id: 'content-123', ...content });
  }
);

Validation Schemas#

User Data Schema#

javascript
const userSchema = {
  type: 'object',
  properties: {
    email: { type: 'string', format: 'email', maxLength: 254 },
    username: { type: 'string', pattern: '^[a-zA-Z0-9_-]{3,30}$' },
    password: { type: 'string', minLength: 8, maxLength: 128 },
    display_name: { type: 'string', minLength: 1, maxLength: 100 },
    phone: { type: 'string', pattern: '^\\+[1-9]\\d{1,14}$' },
    locale: { type: 'string', pattern: '^[a-z]{2}-[A-Z]{2}$' },
  },
  required: ['email', 'username', 'password'],
  additionalProperties: false,
};

Content Schema#

javascript
const contentSchema = {
  type: 'object',
  properties: {
    title: { type: 'string', minLength: 1, maxLength: 200 },
    description: { type: 'string', maxLength: 1000 },
    content_type: {
      type: 'string',
      enum: ['lecture', 'meditation', 'course', 'article'],
    },
    tradition: { type: 'string', enum: ['zen', 'stoic', 'sufi', 'general'] },
    language: { type: 'string', pattern: '^[a-z]{2}$' },
    duration_minutes: { type: 'integer', minimum: 1, maximum: 180 },
    difficulty_level: {
      type: 'string',
      enum: ['beginner', 'intermediate', 'advanced'],
    },
    tags: {
      type: 'array',
      items: { type: 'string', maxLength: 50 },
      maxItems: 20,
    },
  },
  required: ['title', 'content_type', 'tradition', 'language'],
  additionalProperties: false,
};

Message Schema#

javascript
const messageSchema = {
  type: 'object',
  properties: {
    thread_id: { type: 'string', format: 'uuid' },
    content: { type: 'string', minLength: 1, maxLength: 10000 },
    role: { type: 'string', enum: ['user', 'assistant', 'system'] },
    persona: { type: 'string', enum: ['zen', 'stoic', 'sufi', 'neutral'] },
    metadata: {
      type: 'object',
      properties: {
        tokens_used: { type: 'integer', minimum: 0 },
        safety_score: { type: 'number', minimum: 0, maximum: 1 },
      },
    },
  },
  required: ['content', 'role'],
  additionalProperties: false,
};

Sanitization Features#

Text Sanitization#

javascript
// Text sanitization rules
const textSanitization = {
  trim: true, // Remove leading/trailing whitespace
  normalize: true, // Unicode normalization (NFC)
  max_length: 10000, // Maximum character limit
  strip_html: true, // Remove all HTML tags
  escape_special_chars: false, // Escape HTML entities
};

// HTML content sanitization (for rich text)
const htmlSanitization = {
  trim: true,
  purify: true,
  allowed_tags: ['p', 'br', 'strong', 'em', 'u', 'ol', 'ul', 'li'],
  max_length: 50000,
};

// Search query sanitization
const searchSanitization = {
  trim: true,
  normalize: true,
  max_length: 200,
  escape_special_chars: true,
  strip_html: true,
};

File Upload Sanitization#

javascript
// File upload validation and sanitization
app.post(
  '/v1/upload',
  {
    preHandler: validation.createFileUploadValidation({
      size_limits: {
        image: 10485760, // 10MB
        audio: 104857600, // 100MB
        video: 1073741824, // 1GB
        document: 52428800, // 50MB
      },
      virus_scan: true,
      type_validation: true,
      sanitize_filename: true,
    }),
  },
  async (request, reply) => {
    // request.validatedFiles contains sanitized file data
    const files = request.validatedFiles;
    reply.send({ uploaded_files: files.length });
  }
);

Security Validation#

SQL Injection Protection#

The system automatically detects SQL injection patterns:

javascript
// Detected patterns include:
- UNION SELECT statements
- DROP/CREATE/ALTER TABLE commands
- OR/AND conditional injections
- Comment-based injections (--, /* */)
- Stored procedure execution attempts

XSS Protection#

javascript
// XSS detection includes:
- <script> tag injections
- JavaScript/VBScript protocol handlers
- Event handler injections (onload, onerror, onclick)
- iframe/object/embed tag injections
- Data URI scheme attacks

Command Injection Protection#

javascript
// Command injection detection:
- Shell metacharacters (;, &, |, `, $, (), {})
- Common Unix commands (rm, cat, ls, pwd, etc.)
- Network tools (wget, curl, nc, telnet)
- Path manipulation attempts

Path Traversal Protection#

javascript
// Path traversal detection:
- Directory traversal sequences (../, ..\)
- Absolute path references (/etc/, /bin/, C:\)
- URL-encoded traversal attempts (%2e%2e)
- Unicode normalization attacks

Service Integration Patterns#

Authentication Service Integration#

javascript
const {
  InputValidationMiddleware,
  AuthenticationMiddleware,
} = require('@lilith/lib');

const validation = new InputValidationMiddleware({ serviceName: 'auth' });
const auth = new AuthenticationMiddleware({ serviceName: 'auth' });

await validation.initialize();
await auth.initialize();

// User registration with comprehensive validation
app.post(
  '/v1/auth/signup',
  {
    preHandler: [
      auth.createFastifyMiddleware(PERMISSION_LEVELS.PUBLIC),
      validation.createValidationMiddleware('user', {
        sanitization: { body: { strip_html: true, max_length: 1000 } },
        security: { sql_injection: true, xss: true },
      }),
    ],
  },
  async (request, reply) => {
    const userData = request.validatedInput;
    // userData is sanitized and validated
    reply.send({ message: 'User created', user_id: 'user-123' });
  }
);

Content Service Integration#

javascript
// Content creation with rich text validation
app.post(
  '/v1/content',
  {
    preHandler: [
      auth.createFastifyMiddleware(PERMISSION_LEVELS.USER),
      validation.createValidationMiddleware('content', {
        sanitization: {
          body: {
            purify: true,
            allowed_tags: ['p', 'br', 'strong', 'em'],
            max_length: 50000,
          },
        },
        security: { xss: true, content_safety: true },
      }),
    ],
  },
  async (request, reply) => {
    const content = request.validatedInput;
    reply.send({ id: 'content-456', ...content });
  }
);

Conversation Service Integration#

javascript
// Message validation with safety checks
app.post(
  '/v1/conversations/messages',
  {
    preHandler: [
      auth.createFastifyMiddleware(PERMISSION_LEVELS.USER),
      validation.createValidationMiddleware('message', {
        sanitization: { body: { strip_html: true, profanity_filter: true } },
        security: { xss: true, content_safety: true },
      }),
    ],
  },
  async (request, reply) => {
    const message = request.validatedInput;
    reply.send({ message_id: 'msg-789', ...message });
  }
);

Common Validation Patterns#

Pre-configured Patterns#

javascript
const commonValidations = InputValidationMiddleware.createCommonValidations();

// User registration pattern
app.post(
  '/signup',
  {
    preHandler: validation.createRouteValidation(
      commonValidations.userRegistration
    ),
  },
  handler
);

// Content creation pattern
app.post(
  '/content',
  {
    preHandler: validation.createRouteValidation(
      commonValidations.contentCreation
    ),
  },
  handler
);

// Message posting pattern
app.post(
  '/messages',
  {
    preHandler: validation.createRouteValidation(commonValidations.messagePost),
  },
  handler
);

// Search query pattern
app.get(
  '/search',
  {
    preHandler: validation.createRouteValidation(commonValidations.searchQuery),
  },
  handler
);

// File upload pattern
app.post(
  '/upload',
  {
    preHandler: validation.createRouteValidation(commonValidations.fileUpload),
  },
  handler
);

Custom Validation Rules#

javascript
// Custom schema for specific endpoint
const customSchema = {
  type: 'object',
  properties: {
    meditation_duration: { type: 'integer', minimum: 1, maximum: 120 },
    tradition: { type: 'string', enum: ['zen', 'stoic', 'sufi'] },
    difficulty: {
      type: 'string',
      enum: ['beginner', 'intermediate', 'advanced'],
    },
  },
  required: ['tradition'],
  additionalProperties: false,
};

// Register custom schema
validation.ajv.addSchema(customSchema, 'custom-meditation');

// Use custom schema
app.post(
  '/v1/meditations',
  {
    preHandler: validation.createValidationMiddleware('custom-meditation'),
  },
  handler
);

Error Handling#

Validation Error Response#

json
{
  "error": "Input validation failed",
  "details": [
    {
      "field": "email",
      "message": "email must be a valid email",
      "value": "invalid-email",
      "constraint": "format"
    },
    {
      "field": "password",
      "message": "password must be at least 8 characters long",
      "value": "123",
      "constraint": "minLength"
    }
  ],
  "request_id": "req-123456789"
}

Security Validation Error#

json
{
  "error": "Security validation failed",
  "details": [
    {
      "type": "SQL injection",
      "field": "search_query",
      "value": "test'; DROP TABLE users; --",
      "pattern": "DROP.*TABLE"
    }
  ],
  "request_id": "req-123456789"
}

Content Type Error#

json
{
  "error": "Invalid content type",
  "allowed_types": ["application/json"],
  "request_id": "req-123456789"
}

File Upload Error#

json
{
  "error": "File too large",
  "max_size": 10485760,
  "actual_size": 15728640,
  "request_id": "req-123456789"
}

Performance Considerations#

Validation Caching#

javascript
// Validation results are cached to improve performance
const validation = new InputValidationMiddleware({
  cacheMaxAge: 60000, // 1 minute cache
  enableSanitization: true,
  enableSecurityChecks: true,
});

Schema Compilation#

javascript
// Schemas are pre-compiled for optimal performance
// This happens during middleware initialization
await validation.initialize(); // Compiles all schemas

Efficient Pattern Matching#

javascript
// Security patterns use compiled regex for efficiency
// Multiple patterns checked in single pass
// Early termination on first match

Monitoring and Logging#

Validation Logging#

javascript
// All validation events are logged with context
logger.warn('Input validation failed', {
  schema: 'user',
  errors: validationErrors,
  path: '/v1/auth/signup',
  method: 'POST',
  user_id: request.auth?.user?.id,
  request_id: request.id,
});

Security Event Logging#

javascript
// Security validation failures trigger alerts
logger.warn('Security validation failed', {
  issues: securityIssues,
  path: request.url,
  user_id: request.auth?.user?.id,
  request_id: request.id,
});

Health Monitoring#

javascript
// Validation middleware health check
const health = await validation.healthCheck();
// Returns: schemas_compiled, sanitization_enabled, cache_size, etc.

Testing#

Validation Testing#

bash
# Run input validation tests
npm test -- tests/input-validation-integration.spec.js

# Test specific validation patterns
npm test -- --testNamePattern="SQL injection"
npm test -- --testNamePattern="XSS"

Integration Testing#

javascript
// Test validation in service context
const testData = {
  title: 'Test Content',
  content_type: 'meditation',
  tradition: 'zen',
  language: 'en',
};

const response = await fetch('/v1/content', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(testData),
});

expect(response.status).toBe(200);

Security Best Practices#

Input Sanitization#

  1. Always sanitize user input before processing or storage
  2. Use allowlists for permitted content (tags, file types, etc.)
  3. Normalize Unicode to prevent encoding attacks
  4. Limit input length to prevent resource exhaustion
  5. Escape output when displaying user content

Validation Guidelines#

  1. Validate early - at the API boundary
  2. Use strict schemas - reject unknown properties
  3. Validate data types - ensure correct types and formats
  4. Check business rules - beyond just schema validation
  5. Log validation failures - for security monitoring

File Upload Security#

  1. Validate file types using MIME type verification
  2. Limit file sizes to prevent storage abuse
  3. Sanitize filenames to prevent path traversal
  4. Scan for viruses (when virus scanning service available)
  5. Store uploads securely with proper access controls

Configuration Examples#

Auth Service Configuration#

javascript
// Authentication service validation setup
const authValidation = new InputValidationMiddleware({
  serviceName: 'auth',
  enableSecurityChecks: true,
  enableSanitization: true,
});

const validationConfig = {
  signup: {
    body: 'user',
    sanitization: { body: { strip_html: true, max_length: 1000 } },
    security: { sql_injection: true, xss: true, content_safety: true },
  },
  login: {
    body: 'auth_request',
    sanitization: { body: { trim: true, normalize: true } },
    security: { sql_injection: true, command_injection: true },
  },
};

Content Service Configuration#

javascript
// Content service validation setup
const contentValidation = new InputValidationMiddleware({
  serviceName: 'content',
  enableSecurityChecks: true,
  enableSanitization: true,
});

const contentConfig = {
  create: {
    body: 'content',
    sanitization: {
      body: { purify: true, allowed_tags: ['p', 'br', 'strong'] },
    },
    security: { xss: true, content_safety: true },
  },
  search: {
    querystring: 'pagination',
    includeQuery: true,
    sanitization: { query: { escape_special_chars: true } },
    security: { sql_injection: true },
  },
};

Media Service Configuration#

javascript
// Media service validation setup
const mediaValidation = new InputValidationMiddleware({
  serviceName: 'media',
  enableSecurityChecks: true,
  enableSanitization: true,
});

const mediaConfig = {
  upload: {
    files: true,
    sanitization: {
      sanitize_filename: true,
      virus_scan: true,
      type_validation: true,
    },
    security: {
      virus_scan: true,
      type_validation: true,
    },
  },
  metadata: {
    body: 'media',
    sanitization: { body: { strip_html: true } },
    security: { xss: true },
  },
};

Advanced Features#

Custom Format Validators#

javascript
// Custom UUID format validation
validation.ajv.addFormat('uuid', {
  type: 'string',
  validate: (value) =>
    /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
      value
    ),
});

// Custom JWT format validation
validation.ajv.addFormat('jwt', {
  type: 'string',
  validate: (value) =>
    /^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$/.test(value),
});

Content Safety Integration#

javascript
// Integration with content safety service
const securityConfig = {
  content_safety: true, // Enable safety checks
  profanity_filter: true, // Filter profanity
  safety_check: true, // Check against safety policies
};

app.post(
  '/v1/content',
  {
    preHandler: validation.createValidationMiddleware('content', {
      security: securityConfig,
    }),
  },
  handler
);

Multi-layer Validation#

javascript
// Multiple validation layers for comprehensive security
app.post(
  '/v1/user/profile',
  {
    preHandler: [
      // Content type validation
      validation.createContentTypeValidation(['application/json']),

      // Authentication
      auth.createFastifyMiddleware(PERMISSION_LEVELS.USER),

      // Input validation and sanitization
      validation.createValidationMiddleware('user', {
        sanitization: { body: { strip_html: true, normalize: true } },
        security: { sql_injection: true, xss: true },
      }),

      // Authorization
      auth.createAuthorizationMiddleware(['user']),
    ],
  },
  handler
);

Troubleshooting#

Common Validation Issues#

  1. Schema compilation errors

    • Check schema syntax and format definitions
    • Ensure all required properties are defined
  2. Sanitization failures

    • Verify DOMPurify configuration
    • Check for circular references in objects
  3. Security check false positives

    • Review security patterns for overly broad matching
    • Adjust sensitivity based on use case
  4. Performance issues

    • Enable validation caching
    • Pre-compile schemas during initialization
    • Use schema composition for complex validations

Debugging Commands#

bash
# Check validation middleware health
curl "$SERVICE_URL/health"

# Test validation with invalid input
curl -X POST "$SERVICE_URL/v1/test" \
  -H "Content-Type: application/json" \
  -d '{"invalid": "data"}'

# Check validation logs
kubectl logs -n lilith deployment/content-service | grep "validation failed"

Last updated: ${new Date().toISOString()} For implementation details, see: services/lib/input-validation.js