feat: pre-serve static-analysis gate for preview deploys

[luthermonson]

What

Adds an opt-in pre-serve static-analysis gate to the preview-deployment daemon. After a PR's checkout is materialized and before the atomic swap makes the vhost routable — and before build:/seed: execute any of it — switchboard runs:

ephpm analyze <checkout> --config <operator-policy.yml> --format sarif

and refuses to publish on a bad verdict. On a redeploy the previous known-good container stays live (the swap simply never happens).

Insertion point

deployer::deploy_preview, new step (2b) — right after the framework/manifest load + validate_docroot, before materialize_env (step 3). This is deliberately before any external provisioning:

• before env injection, so the analyzer never scans switchboard's own resolved secrets (which secrets-scan would otherwise flag every gated deploy);
• before build:/seed:, so a composer-scripts finding blocks the code before its scripts run;
• before the atomic swap (the true go-live), so a block means the site is never served and a block needs no teardown — only the staging tree is removed.

Behavior

• Disabled unless --analyze-config is set (safe rollout default). Startup logs one WARN when off. The gate is live only when the config is set and --ephpm-bin supports analyze.
• --config is always explicit, overriding ephpm analyze's auto-discovery of a .ephpm-analyze.yml inside the checkout — a malicious PR can't ship enable: [] to neuter its own gate. The analyzer is never run with the checkout as cwd.
• Fail closed. Exit 0 publishes; 2 (quarantine) and 3 (deny) block; 1 (analyzer error), any other code, a timeout (--analyze-timeout-secs, default 180s), and a spawn failure all block.
• Blocked previews are reported. The verdict, finding count, and top ~10 findings (rule / file:line / message) are folded into the PR's sticky comment; the GitHub deployment status is set to failure; the job lands in claimed/ for inspection.

Config / docs

• New flags: --analyze-config (SWITCHBOARD_ANALYZE_CONFIG), --analyze-timeout-secs (SWITCHBOARD_ANALYZE_TIMEOUT_SECS, default 180). Reuses --ephpm-bin.
• docs/analyze-gate.example.yml: reviewed native-only policy (six fast analyzers). opcode-scan is documented as an opt-in per-node upgrade (compiles every file via Zend, +5–15s on a full WP tree). wp-vuln stays out of required (optional feed).
• README: new narrative section, config table, source-map row.

Tests

• analyze.rs: pure decide() exhaustively (0→proceed, 1/2/3/other→block, timeout→block, unrunnable→block); --analyze-config: None → Skipped without touching the binary; SARIF parsing incl. missing fields, cap-with-honest-total, unparseable input.
• config.rs: gate off by default, flags parse, zero-timeout floored.
• github.rs: blocked comment renders verdict + findings, caps at 10 with "Showing N of M", no-findings path, table-cell sanitization.

cargo fmt --all -- --check, cargo clippy --all-targets -- -D warnings, and cargo test (288 pass) all green.

Do not merge / do not deploy — this is outward-facing deploy infra for review first. The infra-side flag + config file are a separate follow-up in switchboard-infra.

[ephpm]

ePHPm Preview — removed

Preview deployment has been torn down.

[luthermonson]

Follow-up commit d77165c: dedup the verdict once per cluster instead of once per node.

Channel: ePHPm's per-site KV is gossip-replicated across the cluster (documented in kv.rs and reused by the existing share-link revoker), so it's a genuine cluster-shared store — no GitHub-polling hack needed. Reached over the RESP listener (--kv-addr) with the per-site AUTH <site> <HMAC(kv_secret,site)> scoping, available when --kv-secret-file is set.

Key: analyze:verdict:<repo>:<pr>:<head_sha>:<cfg_hash> where cfg_hash = SHA-256 fingerprint of the operator policy file contents (a policy edit re-scans everywhere). head_sha comes from the job (PreviewRequest::sha). Stored in the preview's own per-site keyspace with TTL --analyze-verdict-ttl-secs (default 1d; the SHA is the real invalidator).

Flow: cache hit → reuse the peer verdict, no scan; miss/unparseable/unavailable → scan then publish.

Fail-closed gate, fail-SAFE dedup: KV read error → scan locally; KV write error → proceed with the local verdict + warn. Coordination failure degrades to today's per-node scanning, never to serve-unscanned. No lock/lease/leader wait — a simultaneous double-miss just scans twice (identical result).

Cache-hit reconstructs the block comment by serializing the whole AnalyzeBlock (verdict + reason + findings + total) as CachedVerdict; a peer deserializes and into_result()s it, so format_block_comment renders byte-identically without re-scanning.

Security note: the verdict lives in the (untrusted) tenant's own keyspace, but it can't escalate — the first proceed for a SHA is always a real scan (the app can't run until a node has served it, which requires that node to have proceeded on its own scan), and the key is bound to the exact SHA + config fingerprint, so the app can't forge a future push's key.

Tests: pure plan_from_lookup (hit→reuse, miss/unavailable/unparseable→scan), CachedVerdict round-trip, verdict_key/config_fingerprint, and VerdictCache GET-hit/GET-miss/SET-EX/dead-addr against a fake RESP server. 304 tests green; fmt + clippy -D warnings clean. Still do not merge / do not deploy.

[luthermonson]

⚠️ Security correction (commit 0b7f0a7). My earlier note claimed the verdict cache in the preview's own keyspace was safe because the app "can't forge a future push's key." That was wrong and I've fixed it.

The hole: the running preview app can ephpm_kv_set a forged Passed verdict for a future malicious commit it authors — it knows repo/PR/SHA_B, and cfg_hash is a truncated SHA-256 of the operator policy file, which is effectively public (operators copy the shipped example). A peer would then GET the forged pass, skip the scan, and serve the payload. Gate bypassed.

The fix: verdicts now live in a switchboard-private KV namespace, VERDICT_STORE_SITE = "\x1fswitchboard-verdicts", that no preview tenant can authenticate to.

Disjointness argument: a tenant's ephpm_kv_* is auto-scoped server-side by ePHPm to the request's own resolved site key — a tenant never chooses an AUTH site, it only ever reaches its one keyspace. A resolvable site key is always a valid one ([a-z0-9._-], per is_valid_site_key). The reserved namespace leads with the gossip unit-separator \x1f, which is outside that charset, so it can never equal any preview site key ⇒ no tenant is ever scoped to it. switchboard holds kv_secret and can AUTH as any site string, so it alone addresses the namespace.

Cross-node dedup unaffected: all nodes' daemons AUTH as the same reserved site over the same gossip-replicated store, and the per-commit key (analyze:verdict:<repo>:<pr>:<sha>:<cfg_hash>) keeps distinct previews from colliding within it.

New tests: verdict_namespace_is_unreachable_by_any_tenant (reserved site is not a valid site key; disjoint from real site keys) and all_previews_share_one_verdict_namespace (fleet-wide dedup preserved). VerdictCache dropped its preview-site parameter. 306 tests green; fmt + clippy -D warnings clean. Still do not merge / do not deploy.

[luthermonson]

🔒 Comment-injection fix (commit dc29511) — addresses the "comment rendering injection-safe" review finding.

Bug: format_block_comment interpolated f.file and f.rule_id raw inside backtick code spans, and sanitize_cell (only ever applied to f.message) didn't neutralize backticks. f.file is fully attacker-controlled (a PR filename; ePHPm's SARIF artifactLocation.uri is unencoded, so newline/pipe/backtick pass through). A PR shipping a file like x<newline>## Approved [merge](http://evil)<newline>.php with malicious PHP is correctly blocked, but rendering the comment injected the attacker's markdown into switchboard's trusted-identity sticky comment (heading/link/table-breakout spoof — reviewer phishing).

Fix (no redesign):

• sanitize_cell now also replaces ` → ' (on top of \n/\r → space and | → \|).
• New sanitize_code helper for the two code-span fields; applied to f.file and f.rule_id. f.message keeps sanitize_cell. The :line is our own u64, untouched. Cap (MAX_COMMENT_FINDINGS = 10) unchanged.

Regression test blocked_comment_neutralizes_a_malicious_filename: builds a Finding whose file carries a real newline, a |, a backtick, and markdown ([merge](...), ## heading), renders the block comment, and asserts (a) exactly one table row per finding (newline didn't break the row), (b) backticks are balanced (no code span left hanging open), (c) no active injected markup (\n## Approved absent; the rule_id backtick can't close its span).

307 tests green; fmt + clippy -D warnings clean. Verdict/reason strings (switchboard-controlled) left as-is per the review scope. Still do not merge — over to you to verify the rendering and merge.