docs: align API docs with security-hardened public surface + VProtocol certificate

- Update ClusterConfig reference with allowedEnvVars and workerScriptAllowlist

- Update HealthCheckConfig reference with failure/success thresholds, allowedSchemes, allowedHosts, method, expectedBody

- Fix LOAD_BALANCING.md threshold names and add restrict-targets best practice

- Add verification-certificate.json and VERIFICATION.md from VProtocol run

Verdict: HumanReviewRecommended (size cap + monoculture ρ)

Author: jkyberneees

VERIFICATION.md

@@ -0,0 +1,49 @@
+## Verification Certificate
+
+### PR: #7 — security: red-team audit hardening
+
+**Classification:** GeneratedCode
+**Generator:** Kimi k1.5-code (Moonshot AI)
+**Pipeline diversity:** B=C=D=E=Kimi → **INSUFFICIENT** (monoculture fallback applied)
+**η:** 0.804 (signals o=0.95, b=0.90, s=1.00, t=1.00, d=1.00; ρ=0.15)
+**Cv/Ci ratio:** null (Ci zero — open-source contribution, human floor used)
+**Verification Gap (module):** 0.00 | **(repo):** 0.00
+
+### Axes Summary
+
+| Axis                         | Status | Key Finding                                                                                               |
+| ---------------------------- | ------ | --------------------------------------------------------------------------------------------------------- |
+| 2.1 Semantic Correctness     | ✅     | Initial target health preserves explicit `healthy: false`.                                                |
+| 2.2 Behavioral Contract Diff | ✅     | New `ClusterConfig`/`LoadBalancerConfig` fields are optional, no breaking changes.                        |
+| 2.3 Security Surface         | ✅     | Proxy sanitization, trusted client IP, health-check SSRF guards, JWT key/exp enforcement.                 |
+| 2.4 Structural Integrity     | ⚠️     | Load balancer module is large; consider future split.                                                     |
+| 2.5 Behavioral Exploration   | ✅     | Timeout/failure threshold scenarios covered; sandbox unavailable.                                         |
+| 2.6 Dependency Integrity     | ✅     | `@types/bun` pinned to safe range.                                                                        |
+| 2.7 Generator Provenance     | ⚠️     | `generator_identity` present; `prompt_lineage_manifest` not provided.                                     |
+| 2.8 Adversarial Surface      | ✅     | Pre-scan found no injection markers, bidi/zero-width anomalies, or unsafe sinks.                          |
+| 2.9 Documentation Coverage   | ✅     | Public API changes documented in `docs/API_REFERENCE.md`, `docs/CLUSTERING.md`, `docs/LOAD_BALANCING.md`. |
+
+### Verification Debt Contribution
+
+- **ΔDebt:** 0.9 hours
+- **Module class:** Active
+
+### Unverified Gaps
+
+- **Mutation testing** (axis 2.1) — no mutation framework available for Bun/TypeScript. Risk: medium.
+- **Replay sandbox / fuzz harness** (axis 2.5) — not configured. Risk: medium.
+
+### Attestation
+
+- **Signed by:** Kimi Code CLI (monoculture self-attestation)
+- **Certificate file:** `verification-certificate.json`
+- **Protocol version:** 5.2.7
+
+### Verdict
+
+- [ ] **Auto-Approve**
+- [x] **Human Review Recommended**
+- [ ] **Human Review REQUIRED**
+- [ ] **Cannot Verify**
+
+**Rationale:** PR size (4,621 LOC) triggers the §0.3 size-cap ceiling at `HumanReviewRecommended`. Monoculture pipeline (ρ = 0.15) also maps to `HumanReviewRecommended`. All axes pass after auto-remediation of documentation gaps; no 🔴 findings remain.

docs/API_REFERENCE.md

@@ -115,6 +115,8 @@ interface ClusterConfig {
   respawnThresholdTime?: number // Default: 60000ms
   shutdownTimeout?: number // Default: 30000ms
   exitOnShutdown?: boolean // Default: true
+  allowedEnvVars?: string[] // Allow-list of env vars forwarded to workers
+  workerScriptAllowlist?: string[] // Allow-list of worker script paths
 }
 ```
 
@@ -392,12 +394,17 @@ gateway.addRoute({
 ```typescript
 interface HealthCheckConfig {
   enabled: boolean
-  interval?: number // Default: 30000ms
-  timeout?: number // Default: 5000ms
+  interval?: number // Default: 30000ms, clamped to 1000ms–300000ms
+  timeout?: number // Default: 5000ms, must be less than interval
   path?: string // Default: '/health'
+  method?: 'GET' | 'HEAD' // Default: 'GET'
   expectedStatus?: number // Default: 200
-  unhealthyThreshold?: number // Default: 3
-  healthyThreshold?: number // Default: 2
+  expectedBody?: string // Optional body substring required for healthy status
+  failureThreshold?: number // Default: 3, max 20
+  successThreshold?: number // Default: 2, max 20
+  minHealthyTargets?: number // Default: 1
+  allowedSchemes?: string[] // Default: ['http', 'https']
+  allowedHosts?: string[] // CIDR or exact hosts allowed for health checks
   validator?: (response: Response) => Promise<boolean> | boolean
 }
 ```

docs/CLUSTERING.md

@@ -141,6 +141,14 @@ interface ClusterConfig {
   // Exit master process after shutdown (default: true)
   // Set to false for testing or embedded usage
   exitOnShutdown: boolean
+
+  // Allow-list of environment variable names forwarded to workers.
+  // If provided, only these variables (plus internal CLUSTER_* vars) are passed.
+  allowedEnvVars?: string[]
+
+  // Allow-list of worker script paths. The worker script must match one of
+  // these paths to prevent accidental execution of arbitrary files.
+  workerScriptAllowlist?: string[]
 }
 ```
 

docs/LOAD_BALANCING.md

@@ -401,8 +401,8 @@ gateway.addRoute({
       timeout: 5000, // 5 second timeout
       path: '/health', // Health check endpoint
       expectedStatus: 200, // Expected status code
-      unhealthyThreshold: 3, // Failures before marking unhealthy
-      healthyThreshold: 2, // Successes before marking healthy
+      failureThreshold: 3, // Failures before marking unhealthy
+      successThreshold: 2, // Successes before marking healthy
     },
   },
 })
@@ -594,7 +594,7 @@ gateway.addRoute({
       enabled: true,
       interval: 10000,
       path: '/health',
-      unhealthyThreshold: 2, // Fast failover
+      failureThreshold: 2, // Fast failover
     },
   },
 })
@@ -650,12 +650,29 @@ healthCheck: {
   interval: 15000,
   timeout: 5000,
   path: '/health',
-  unhealthyThreshold: 3,
-  healthyThreshold: 2,
+  failureThreshold: 3,
+  successThreshold: 2,
 }
 ```
 
-### 2. Use Circuit Breakers for External Services
+### 2. Restrict Health Check Targets
+
+For security, limit which schemes and hosts the load balancer may probe.
+
+```typescript
+healthCheck: {
+  enabled: true,
+  interval: 15000,
+  timeout: 5000,
+  path: '/health',
+  failureThreshold: 3,
+  successThreshold: 2,
+  allowedSchemes: ['http', 'https'],
+  allowedHosts: ['10.0.0.0/8', 'api.internal.example.com'],
+}
+```
+
+### 3. Use Circuit Breakers for External Services
 
 ```typescript
 circuitBreaker: {
@@ -666,7 +683,7 @@ circuitBreaker: {
 }
 ```
 
-### 3. Configure Timeouts
+### 4. Configure Timeouts
 
 ```typescript
 gateway.addRoute({
@@ -681,7 +698,7 @@ gateway.addRoute({
 })
 ```
 
-### 4. Monitor Target Health
+### 5. Monitor Target Health
 
 ```typescript
 import { PinoLogger } from 'bungate'
@@ -698,7 +715,7 @@ gateway.on('target-healthy', (target) => {
 })
 ```
 
-### 5. Use Appropriate Strategy
+### 6. Use Appropriate Strategy
 
 ```typescript
 // ❌ DON'T use IP hash for APIs behind NAT
@@ -714,7 +731,7 @@ loadBalancer: {
 }
 ```
 
-### 6. Plan for Capacity
+### 7. Plan for Capacity
 
 ```typescript
 // Configure weights based on actual capacity
@@ -728,7 +745,7 @@ loadBalancer: {
 }
 ```
 
-### 7. Test Failover Scenarios
+### 8. Test Failover Scenarios
 
 ```bash
 # Simulate server failure
@@ -781,7 +798,7 @@ targets: [
 healthCheck: {
   enabled: true,
   timeout: 10000, // Increase from 5000
-  unhealthyThreshold: 5, // Require more failures
+  failureThreshold: 5, // Require more failures
 }
 
 // 2. Check health endpoint performance