feat(setup): first-run operator intake + admin email login (trinity-enterprise#38, #82)

[vybe]

Summary

Two converging first-run features built on one email capture:

• trinity-enterprise#38 — at first-run setup, optionally collect operator email + company with an explicit, unchecked-by-default opt-in to "occasionally receive important security & product updates". On consent, it's submitted once to a new POST /v1/operator-intake endpoint on feat(ui): In-app bug reporting from the floating Help widget (hosted intake → GitHub issues) #1116's Cloudflare intake app (intake.abilityai.dev) — one added endpoint, same hosted app.
• Add email verification for admin login (email code + password) #82 (Phase 1) — that same email becomes the admin's sign-in identity: log in with email + password instead of the fixed admin.

The key design decision: no email is sent at setup

A fresh install has no Resend key, so we can't deliver a verification code during setup. Instead the email is bound to the admin account (not code-verified), and the intake is a plain HTTPS POST (not email) — both work offline-of-email. The code-based email second factor is Phase 2, deferred to the existing mfa_gate seam (#5/#388) — so this PR does not touch that call site.

Changes

• services/operator_intake_service.py — fire-and-forget httpx POST; at-most-once (operator_intake_submitted marker claimed before the POST); OPERATOR_INTAKE_ENABLED=false/DO_NOT_TRACK disables; owns installation_id (the feat(telemetry): installation telemetry — usage analytics from self-hosted deployments #758 seed); never raises, never logs the email.
• routers/setup.py — optional email/company/consent_updates; validates email shape before any write; binds admin email; schedules intake via BackgroundTasks (runs after the response).
• dependencies.authenticate_user — resolve admin by username or registered email; password-hash guard keeps email-code-only users out of the password path.
• routers/users.py — PUT /api/users/me/email (own-account, 409 on collision) for the existing-admin transition.
• Frontend — SetupPassword.vue (fields + consent), Login.vue ("Username or email"), Settings.vue (General → "Admin sign-in email" card).
• Config — OPERATOR_INTAKE_ENABLED / OPERATOR_INTAKE_URL + .env.example. CSP already allows intake.abilityai.dev (feat(ui): In-app bug reporting from the floating Help widget (hosted intake → GitHub issues) #1116) — no CSP change.
• Docs — requirements §43, architecture catalog, first-time-setup.md Flow 3 + Worker contract.

Test Plan

• 16 new unit tests pass (test_operator_intake.py, test_admin_email_login.py, test_setup_operator_profile.py): intake idempotency/disable/no-email/failure-swallow, email-login resolution + passwordless guard, setup capture/consent/invalid-email.
• Existing setup (bug: First-time setup token is per-worker — prod (--workers 2) onboarding still ~50% flaky after #858 #1165) and users-DB tests pass.
• Maintainers: deploy the /v1/operator-intake Worker endpoint (out-of-repo, sibling to /v1/report-bug) — contract in the feature flow.

Notes for review

• Cross-tracker: closes the private trinity-enterprise#38 (closed manually at release — keyword doesn't cross repos) and public #82.
• SetAdminPasswordRequest/UpdateMyEmailRequest kept inline per these routers' existing convention; _EMAIL_RE duplicated across two modules (small) — flag if you'd prefer centralizing.

Fixes abilityai/trinity-enterprise#38
Fixes #82

🤖 Generated with Claude Code

[dolho]

/review Report — automated structural review

Branch: feature/38-first-run-intake-admin-email → dev (diffed against merge-base)
Files: 16 (+927/−21) · Scope: CLEAN · Plan: AC met (admin email login + consent-gated operator intake)

Reviewed the auth/setup/intake surface in full (read whole files, not just hunks). This is a well-built PR — strong defensive posture. No critical findings.

Critical Findings (block merge)

None.

• Auth fallback is safe — dependencies.authenticate_user falls back to email lookup only when no username matches, then hard-gates on a password hash: if not user.get("password"): return False. Email-code-only accounts (no hash) can never password-authenticate, and a non-admin logging in by email gets their own role — no escalation. Directly covered by test_passwordless_email_user_cannot_password_login.
• Privacy posture is sound — outbound intake fires only on the affirmative consent_updates checkbox and a valid email, is OPERATOR_INTAKE_ENABLED / DO_NOT_TRACK gated, runs as a BackgroundTasks job (never delays/breaks setup), is at-most-once (marker claimed before POST), 5s timeout, and never logs the email (verified in operator_intake_service.py).
• ReDoS — already de-ambiguated in c16f7e0 ([^@\s.]+ TLD class); no polynomial backtracking. Clean.

Informational Findings (review recommended)

[I1] Auth: email-login uniqueness is app-layer only (Confidence: 6/10)
File: src/backend/dependencies.py:48 + src/backend/routers/users.py (/me/email)
Evidence: login does user = db.get_user_by_email(username.strip().lower()); users.email has no DB unique constraint (the UNIQUE indexes in db/schema.py are on other tables — email_whitelist, agent_sharing, etc.). Uniqueness is enforced only by the /me/email 409 check, which is a check-then-update (TOCTOU) with no backing constraint.
Issue: legacy data or a concurrent /me/email race could produce two accounts with the same email → ambiguous get_user_by_email → non-deterministic password login target.
Suggestion: add a partial unique index on lower(email) for password-bearing accounts (or assert single-row in get_user_by_email). Low real-world likelihood today (setup binds only admin; email-code users get unique emails), hence informational.

Clean Categories

• SQL/data safety — no raw SQL; all writes via db.* facade. Clean.
• Auth boundaries — /me/email uses get_current_user (self-service, correct) with a cross-account claim guard (409); users.py admin endpoints keep require_admin. Clean.
• Credential/PII exposure — intake logs only the install-id prefix, never the email; verified no secret/PII in log lines. Clean.
• Error handling — intake swallows all exceptions by design (fire-and-forget); setup wraps the email write in try/except so a profile write can't break setup. Clean.
• Test gaps — new auth path (username/email/normalization/passwordless-reject/unknown), intake (consent gating, at-most-once), and setup profile all covered by the 3 new test files. Clean.

Summary

• Critical: 0 — none found
• Informational: 1 — I1 (email uniqueness; recommend a DB constraint as hardening, not a blocker)
• Scope: CLEAN

Automated /review (structural pass — data safety, concurrency, auth boundaries, scope). Complements /validate-pr.