/defense-in-depth

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

| Situation | Layers Needed | |-----------|---------------| | Public API, simple validation | 1 only | | Data crosses multiple services | 1 + 2 | | Destructive operations (delete, init, write) | 1 + 2 + 3 | | Chasing a hard-to-reproduce bug | 1 + 2 + 3 + 4 | | Tests mock intermediate layers | At minimum: 1 + 3 |

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

| Layer | Question It Answers | Typical Check | |-------|---------------------|---------------| | Entry | Is input valid? | Non-empty, exists, correct type | | Business | Does it make sense here? | Required for this operation, within bounds | | Environment | Is this safe in this context? | Not in prod, inside temp dir, etc. | | Debug | How did we get here? | Log stack, cwd, inputs |

Common Mistakes

| Mistake | Fix | |---------|-----| | One validation point, call it done | Add at least entry + business layers | | Identical checks at adjacent layers | Make each layer check something different | | Environment guards only in prod | Add them in test too (prevent test pollution) | | Skipping debug logging | Add it during the bug hunt, keep it | | Validation but no useful error message | Include the bad value and expected format |

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.