version: "1.0.1" name: defense-in-depth description: Use when invalid data causes failures deep in execution - validates at every layer data passes through to make bugs structurally impossible rather than temporarily fixed user-invocable: false

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.

When to Use

Use when:

• Invalid data caused a bug deep in the call stack
• Data crosses system boundaries (API → service → storage)
• Multiple code paths can reach the same vulnerable code
• Tests mock intermediate layers (bypassing validation)

Don't use when:

• Pure internal function with single caller (validate at caller)
• Data already validated by framework/library you trust
• Adding validation would duplicate identical checks at adjacent layers

The Four Layers

Layer 1: Entry Point Validation

Purpose: Reject invalid input at API/system boundary

function createProject(name: string, workingDirectory: string) {
  if (!workingDirectory?.trim()) {
    throw new Error('workingDirectory cannot be empty');
  }
  if (!existsSync(workingDirectory)) {
    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
  }
  // ... proceed
}

When needed: Always. This is your first line of defense.

Layer 2: Business Logic Validation

Purpose: Ensure data makes sense for this specific operation

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

When needed: When business rules differ from entry validation, or when mocks might bypass Layer 1.

Layer 3: Environment Guards

Purpose: Prevent dangerous operations in specific contexts

async function gitInit(directory: string) {
  if (process.env.NODE_ENV === 'test') {
    const normalized = normalize(resolve(directory));
    if (!normalized.startsWith(tmpdir())) {
      throw new Error(`Refusing git init outside temp dir in tests: ${directory}`);
    }
  }
  // ... proceed
}

When needed: When operation is destructive/irreversible, especially in test environments.

Layer 4: Debug Instrumentation

Purpose: Capture context for forensics when other layers fail

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

When needed: When debugging is difficult, or when you need to trace how bad data arrived.

Decision Heuristic

Applying the Pattern

When you find a bug caused by invalid data:

1. Trace the data flow - Where does the bad value originate? Where is it used?
2. Map checkpoints - List every function/layer the data passes through
3. Decide which layers - Use heuristic above
4. Add validation - Entry → business → environment → debug
5. Test each layer - Verify Layer 2 catches what bypasses Layer 1

Quick Reference

Common Mistakes

Key Insight

During testing, each layer catches bugs the others miss:

• Different code paths bypass entry validation
• Mocks bypass business logic checks
• Edge cases need environment guards
• Debug logging identifies structural misuse

Don't stop at one validation point. The bug isn't fixed until it's impossible.