protect: make fail-open observable; stop startup hanging on the rule API

[patchstackdave]

Two enforcement-visibility gaps raised by an external review.

1. Fail-open was silent

The guard deliberately passes traffic it can't inspect — a request body over the cap, a response over the screening cap, a live stream, a binary body, a read/decode failure, a DNS resolver failure (or no resolver on this runtime). Each of those is a real hole in enforcement, and nothing recorded it — so "always-on" read as "always inspected", and a secret-redaction rule could silently never apply.

Now every such bypass is counted and reported:

const p = await createProtection({ onSkip: ({ phase, reason, detail, count }) => metrics.inc(...) })
p.coverage() // { skipped: { 'response:body-cap': 3, 'response:live-stream': 12, 'egress:resolver-failed': 1 } }

• readTextResponse returns { text } | { skip: reason }, so the reason is precise (body-cap, live-stream, non-text-content-type, binary-body, read-failed, decode-failed, clone-failed).
• The node response path (cap overflow, non-text/binary passthrough), the node request path (body cap) and the egress resolver (resolver-failed / resolver-unavailable) all report through the same channel.
• A throwing onSkip can never affect request handling.

2. Startup could hang for 30 s

createProtection awaited the rule fetch with the client's full 30 s timeout, so a slow/hanging API delayed app boot — and hosted platforms fail a deploy whose health check is slow (Replit publishes fail past ~5 s). The initial load now gets a short budget — bootTimeoutMs, default 5 s — and falls back to last-known-good / bundled rules (already the existing fallback chain, so protection is retained). Refreshes keep the full budget (refreshTimeoutMs). Both rule clients accept timeoutMs.

Verified by test: a fetch that never resolves boots in ~300 ms and the guard is still enforcing the fallback ruleset.

Also

Documents the mode-default discrepancy honestly: this API defaults to dry-run, while the scaffolded guard passes mode: 'block' (dropping to dry-run only on PATCHSTACK_MODE=dry-run). Both intentional; previously the comment and the generated guard appeared to contradict each other.

Tests

tests/protect/coverage-skips.test.ts — cap/stream/binary skips are recorded and reported, repeats count, coverage stays empty when everything was inspected, a throwing onSkip is harmless, and the non-blocking-boot case. Full suite green (715), typecheck + build clean.

[coderbuds]

Adds observable fail-open coverage tracking and startup timeout for rule API fetches.

🎯 Quality: 100% Elite · 📦 Size: Medium

📈 This month: Your 52nd PR — above team average · Averaging Excellent

_{See how your team is trending →}

[patchstackdave]

/review