defense-in-depth

Defense-in-Depth Validation

Overview

When you fix a bug caused by invalid data, adding validation at one place feels sufficient. But that single check can be bypassed by different code paths, refactoring, or mocks.

Core principle: Validate at EVERY layer data passes through. Make the bug structurally impossible.

Why Multiple Layers

Single validation: "We fixed the bug" Multiple layers: "We made the bug impossible"

Different layers catch different cases:

• Entry validation catches most bugs
• Business logic catches edge cases
• Environment guards prevent context-specific dangers
• Debug logging helps when other layers fail

Layer Implementation: Validation Point Discovery

For each layer, dispatch Explore agent with thoroughness: "very thorough"

Layer 1 - Entry Point Discovery:

Use Task tool:

# Invoke Task tool with:
subagent_type = "Explore"
model = "haiku"
prompt = """
Explore to find all entry points for [feature/module]:
1. API endpoints, route handlers, CLI commands
2. Event handlers, message queue consumers
3. Public class methods, exported functions
4. Form inputs, user interactions

Return: All entry points with file paths and signatures

**CRITICAL:** Do NOT create temporary files (/tmp, docs/, etc).
Aggregate all findings in memory and return complete report in your final message.
All results must appear in function_results - no file creation.

Thoroughness: very thorough
"""

Consuming Layer 1 Results (Entry Points):

After Task tool returns, entry point discovery report appears in function_results.

Read and extract:

• All entry points with file paths and signatures
• API endpoints, route handlers, CLI commands
• Event handlers, message queue consumers
• Public class methods, exported functions
• Form inputs, user interactions

Use for: Implementing validation at EVERY entry point found. No entry point missed.

Layer 2 - Business Logic Discovery:

# Invoke Task tool with:
subagent_type = "Explore"
model = "haiku"
prompt = """
Explore to find business logic validation points:
1. Service methods, domain logic functions
2. State transition validations
3. Business rule enforcement locations
4. Data consistency checks

Return: Business logic locations requiring validation

**CRITICAL:** Do NOT create temporary files (/tmp, docs/, etc).
Aggregate all findings in memory and return complete report in your final message.
All results must appear in function_results - no file creation.

Thoroughness: very thorough
"""

Consuming Layer 2 Results (Business Logic):

After Task tool returns, business logic validation points appear in function_results.

Read and extract:

• Service methods, domain logic functions
• State transition validations
• Business rule enforcement locations
• Data consistency checks

Use for: Implementing validation at EVERY business logic point found.

Layer 3 - Environment Discovery:

# Invoke Task tool with:
subagent_type = "Explore"
model = "haiku"
prompt = """
Explore to find environment interaction points:
1. Database queries, ORM operations
2. External API calls, HTTP clients
3. File system operations
4. Cache access, session management

Return: All boundary points with external systems

**CRITICAL:** Do NOT create temporary files (/tmp, docs/, etc).
Aggregate all findings in memory and return complete report in your final message.
All results must appear in function_results - no file creation.

Thoroughness: very thorough
"""

Consuming Layer 3 Results (Environment):

After Task tool returns, environment interaction points appear in function_results.

Read and extract:

• Database queries, ORM operations
• External API calls, HTTP clients
• File system operations
• Cache access, session management

Use for: Implementing validation at EVERY boundary point found. Complete coverage ensured.

Use findings to:

• Implement validation at EVERY identified point
• Ensure no gaps in validation coverage
• Add instrumentation for debugging at key boundaries

The Four Layers

Layer 1: Entry Point Validation

Purpose: Reject obviously invalid input at API boundary

function createProject(name: string, workingDirectory: string) {
  if (!workingDirectory || workingDirectory.trim() === '') {
    throw new Error('workingDirectory cannot be empty');
  }
  if (!existsSync(workingDirectory)) {
    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
  }
  if (!statSync(workingDirectory).isDirectory()) {
    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
  }
  // ... proceed
}

Layer 2: Business Logic Validation

Purpose: Ensure data makes sense for this operation

function initializeWorkspace(projectDir: string, sessionId: string) {
  if (!projectDir) {
    throw new Error('projectDir required for workspace initialization');
  }
  // ... proceed
}

Layer 3: Environment Guards

Purpose: Prevent dangerous operations in specific contexts

async function gitInit(directory: string) {
  // In tests, refuse git init outside temp directories
  if (process.env.NODE_ENV === 'test') {
    const normalized = normalize(resolve(directory));
    const tmpDir = normalize(resolve(tmpdir()));

    if (!normalized.startsWith(tmpDir)) {
      throw new Error(
        `Refusing git init outside temp dir during tests: ${directory}`
      );
    }
  }
  // ... proceed
}

Layer 4: Debug Instrumentation

Purpose: Capture context for forensics

async function gitInit(directory: string) {
  const stack = new Error().stack;
  logger.debug('About to git init', {
    directory,
    cwd: process.cwd(),
    stack,
  });
  // ... proceed
}

Applying the Pattern

When you find a bug:

1. Trace the data flow - Where does bad value originate? Where used?
2. Map all checkpoints - List every point data passes through
3. Add validation at each layer - Entry, business, environment, debug
4. Test each layer - Try to bypass layer 1, verify layer 2 catches it

Example from Session

Bug: Empty projectDir caused git init in source code

Data flow:

1. Test setup → empty string
2. Project.create(name, '')
3. WorkspaceManager.createWorkspace('')
4. git init runs in process.cwd()

Four layers added:

• Layer 1: Project.create() validates not empty/exists/writable
• Layer 2: WorkspaceManager validates projectDir not empty
• Layer 3: WorktreeManager refuses git init outside tmpdir in tests
• Layer 4: Stack trace logging before git init

Result: All 1847 tests passed, bug impossible to reproduce

Key Insight

All four layers were necessary. During testing, each layer caught bugs the others missed:

• Different code paths bypassed entry validation
• Mocks bypassed business logic checks
• Edge cases on different platforms needed environment guards
• Debug logging identified structural misuse

Don't stop at one validation point. Add checks at every layer.