feat(dev): DEV_AUTH_BYPASS flag to skip guest gates for headless testing

[thewrz]

Why

Headless testing of guest flows (collect/join/kiosk submit, vote, profile) is blocked by the human-verification (wrzdj_human cookie) and email-verification gates — the external API suite and Playwright can't easily mint those. Turnstile already self-disables in dev; these two gates had no dev escape hatch. (This is exactly what blocked 16 checks in the ~/wrzdj-testing suite — all 401/403 gate rejections.)

What

Adds DEV_AUTH_BYPASS (default off). When set in a non-production env, the three guest gates (require_verified_human, require_verified_human_soft, require_email_verified) resolve a real guest identity — the request's wrzdj_guest cookie if present, else a stable lazily-created dev guest — and skip the cookie/email checks. So tests need no cookies at all. Admin/DJ auth is unchanged (JWT).

Prod-safety (by construction)

• auth_bypass_enabled gates on not is_production → inert even if the flag leaks into a prod environment.
• validate_settings refuses to boot (SystemExit(1)) if DEV_AUTH_BYPASS is set with ENV=production.
• A loud WARNING is logged whenever it's active in dev.

Testing

• Property matrix: dev+flag active / prod+flag inert / off-by-default
• Prod refuses to boot when set; clean prod still boots; dev warns (not raises)
• Live integration: GET /collect/{code}/profile (hard gate) → 403 without bypass, 200 with it
• No regression across gate suites (104 passing: config, human-verification, collect, votes, bypass)
• ruff/format/bandit clean
• CI green

🤖 Co-authored by Claude Opus 4.8.

[coderabbitai]

Warning

Review limit reached

@thewrz, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 29 minutes and 26 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 63b1ef4e-dd4f-41e2-8365-14886dfde890

📥 Commits

Reviewing files that changed from the base of the PR and between 4543b2f and 199ea84.

📒 Files selected for processing (6)

• .env.example
• server/app/api/deps.py
• server/app/api/guest.py
• server/app/core/config.py
• server/app/core/rate_limit.py
• server/tests/test_dev_auth_bypass.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/dev-auth-bypass

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[thewrz]

Adversarial security review (Codex GPT-5.5 xhigh) — 3 passes to convergence

Per the requirement that this dev flag cannot weaken production hardening via any path:

• Pass 1 → [P1]: the bypass flag was prod-safe, but the dev guest row (fixed public token + pre-set verified_email) was a latent backdoor if it leaked into a prod DB — the normal cookie lookup resolved it before any bypass check, then it passed the email gate. Fixed (a8883e7): reject the reserved token in get_guest_id when bypass off + dev guest no longer pre-verified.
• Pass 2 → [P2]: /guest/identify doesn't use get_guest_id, so it could still claim/re-tokenize a leaked dev row. Fixed (199ea84): shared is_inert_dev_token guard applied at /identify too; dev row has no fingerprint so reconciliation can't reach it once the cookie path is closed.
• Pass 3 → clean: "No [P1]/[P2] findings." Verified directly that ENV=production DEV_AUTH_BYPASS=1 → auth_bypass_enabled=False → startup aborts. No endpoint/header/cookie/query/body/DB-setting can toggle the flag. _dev_bypass_guest_id is reachable only when bypass is true. Admin/DJ JWT, ownership, kiosk trust, rate limiting, and last-admin protection are all untouched.

Prod-safety invariant: inert in production by construction (dev_auth_bypass and not is_production, env is a 2-value Literal) and the app refuses to boot if the flag is set with ENV=production. 14 dev tests + 104 gate-regression tests green.

🤖 Reviewed via Codex (GPT-5.5 xhigh, 3 passes) + manual analysis.