PREWAVE-BE-096 — Verify Email Ownership Before Enabling Notification Delivery #797

Problem context

src/notifications/controllers/preferences.controller.ts contains a TODO to verify an email address before setting it. An authenticated user can currently update the notification email preference without a verification challenge.

Technical scope

Add a time-limited, single-use email ownership challenge with hashed token storage, resend throttling, verified/unverified state, safe address-change handling, and a confirmation endpoint. Do not enable email delivery to a newly supplied address until ownership is proven. Keep email change verification distinct from authentication or account recovery.

Required tests

• Valid, expired, replayed, revoked, and malformed token cases.
• Address change invalidates prior pending challenges.
• Rate limits and resend behavior.
• No token or full email address in logs.
• Unverified addresses cannot receive notification payloads.

Security and architecture constraints

• Contracts and finalized canonical events remain authoritative for protocol state.
• The API remains a projection/read and notification-delivery layer; it must not invent protocol outcomes.
• Fail closed on missing, stale, ambiguous, unauthorized, or incomplete state.
• Do not expose secrets, device tokens, email verification tokens, private evidence, or unnecessary personal data.
• Preserve strict typing, idempotency, privacy, observability redaction, and existing CI/security gates.

Acceptance criteria

• The identified placeholder or unsafe behavior is replaced by a production-quality implementation.
• Provider/recipient/ownership behavior is explicit and documented.
• Every required failure mode is covered by automated tests.
• No synthetic success, cross-user data exposure, or secret leakage remains in the affected path.
• The pull request links exactly this issue and maps evidence to every acceptance criterion.
• Exact-head required CI passes and independent human review is recorded.

Dependencies

• API PREWAVE-BE-025 — Validate Optional Notification Channel Configuration Fail Closed #621 — notification channel configuration and preference enforcement.

Non-goals

Changing login identity, password reset, or account recovery flows.

Complexity and points

• Medium — 150 points

Candidate only. Activation remains maintainer-controlled; do not apply Stellar Wave as part of implementation.