# Validation Harness

## Purpose

This file is the direct answer to: what exactly are we validating, how are we validating it, and what evidence should exist afterward.

## Harnesses

### Unit Tests

Command:

```bash
npm test
```

What it validates:

- key generation helpers
- catalog signing and verification
- gateway and egress selection rules
- runtime security guardrails
- failover signature and freshness logic
- store-layer behavior
- control-plane integration paths
- static-site generation paths

What it does not validate:

- real kernel WireGuard traffic
- real cloud provider actions unless separately invoked

## Local Tracer Bullet

Command:

```bash
npm run tracer
```

What it validates:

- control plane starts
- gateway registers and heartbeats
- client generates local identity
- enrollment succeeds
- signed catalog is published
- client failover rewrites config
- gateway config renders
- orchestration plans are generated
- operator report artifact is emitted

Evidence:

- `data/tracer-device.json`
- `data/tracer-device.conf`
- `data/tracer-device-failover.conf`
- `data/tracer-catalog.json`
- `data/tracer-audit.json`
- `data/tracer-report.json`
- `data/tracer-gateway.conf`

## Control-Plane Failure Drill

Command:

```bash
bash scripts/drill-control-plane.sh
```

What it validates:

- baseline report generation after a normal enroll
- metering can suspend a device after quota exhaustion
- client bundling emits cross-platform onboarding output
- failover fails cleanly when no alternate front door remains
- stale heartbeat removes the gateway from the catalog
- new enrollments fail cleanly when no healthy gateway remains

Evidence:

- `data/drill-report-baseline.json`
- `data/drill-report-suspended.json`
- `data/drill-meter-response.json`
- `data/drill-failover.stderr.txt`
- `data/drill-catalog-stale.json`
- `data/drill-enroll-no-gateway.json`
- `data/drill-bundle/`

## Multi-Scenario Gauntlet

Command:

```bash
bash scripts/gauntlet-damm.sh
```

What it validates:

- same-gateway frontdoor failover using the signed catalog
- cross-gateway failover when the current gateway is withdrawn from fresh catalogs
- enrollment steering under asymmetric ingress headroom
- quota suspension under gateway metering
- clean failure when all gateways are stale or out of active frontdoors

Evidence:

- `data/gauntlet/01-frontdoor-loss/`
- `data/gauntlet/02-gateway-withdrawal/`
- `data/gauntlet/03-capacity-squeeze/`
- `data/gauntlet/04-quota-suspension/`
- `data/gauntlet/05-capacity-exhaustion/`
- `data/gauntlet/summary.json`

What it does not validate:

- real long-running internet latency under provider churn
- remote bootstrap of ephemeral gateways through the orchestrator
- hostile-network transport beyond standard DAMM WireGuard behavior

## Host WireGuard Smoke

Command:

```bash
bash scripts/host-wireguard-smoke.sh <left-host> <right-host>
```

What it validates:

- remote hosts can create WireGuard interfaces
- handshake completes
- bidirectional tunnel ping succeeds
- temporary interfaces are cleaned up afterward

Evidence:

- `data/host-smoke-*.txt`

What it does not validate:

- DAMM control-plane-driven remote gateway bootstrap
- long-running routing stability

## Host Workload Validation

Command:

```bash
OUT_FILE=data/host-workload-example.txt \
bash scripts/host-wireguard-workload.sh <left-host> <right-host>
```

What it validates:

- the WireGuard tunnel can carry actual application traffic, not just handshake and ICMP
- an HTTP workload can be served over the tunnel in both directions
- payload integrity holds through SHA-256 verification on both transfers
- transfer timing and download-rate metrics are captured for later review

Evidence:

- `data/host-workload-*.txt`

What it does not validate:

- long-run throughput over hours or days
- gateway-orchestrated tunnel management through the DAMM control plane

## Provider Smoke

Commands:

```bash
npm run smoke:hetzner -- locations --out ...
npm run smoke:hetzner -- ingress --region eu-central --out ...
npm run smoke:hetzner -- egress --region eu-central --out ...
```

What it validates:

- provider adapter wiring
- region and size mapping
- bootstrap payload generation
- cleanup planning

What it does not validate in plan mode:

- real server creation
- real network reachability

## Site Build

Command:

```bash
npm run build:site
```

What it validates:

- generated portfolio page
- generated VPN report page
- manifest output
- evidence publication paths

## Failure Paths Covered

The current integration suite covers:

- invalid enrollment token
- client private key submission rejection
- oversized request rejection
- heartbeat before registration rejection
- enrollment failure with no healthy gateways
- stale gateway removal from catalog
- revoked-device rotation rejection
- stale catalog rejection
- access-tier policy rejection
- metering-based suspension

## Current Gaps

- no live packet accounting imported from gateways yet
- no automated long-run churn test under repeated node replacement
- no real multi-gateway remote bootstrap flow yet
- no live Postgres proof on this host without a real `DATABASE_URL`