[TASK][Backend] Complete auth security flows: verification, password reset, 2FA, and reCAPTCHA

[vugarsafarzada]

Source of Truth

• PRD: https://www.notion.so/3435ef9e213280eaa56ad864787cda02
• Repo: Reziphay/nodejs-app
• Task type: execution-ready backend task for AI/code agents
• Depends on: none
• Blocks: nextjs-app#6 and indirectly most protected-domain work

Current Codebase Snapshot

• src/routes/v1/auth.route.ts currently exposes register, login, refresh, and me.
• prisma/schema.prisma already stores email_verified and phone_verified on User.
• The backend does not yet implement email verification, phone OTP verification, forgot-password, optional 2FA, step-up auth, or reCAPTCHA validation.

Goal

Upgrade auth from a basic login/register layer into the canonical trust boundary for the product. After this task, every other domain should be able to trust auth for identity, verified-contact status, and high-risk re-authentication.

In Scope

• Email verification using single-use magic links with expiry and resend support.
• Phone verification using OTP with resend, TTL, and rate limiting.
• Forgot-password and reset-password using a single-use reset token with 1-hour TTL.
• Optional 2FA enrollment and login challenge flow.
• reCAPTCHA validation on register and login.
• Machine-readable restriction state for logged in but not fully verified users.
• Step-up auth for delete account, email change, phone change, and delete brand.
• Swagger/OpenAPI updates and automated tests.

Suggested Implementation Order

1. Extend Prisma with verification tokens, OTP challenges, password reset tokens, and 2FA enrollment/challenge tables.
2. Add services for token generation, hashing, expiry validation, single-use consumption, and rate limiting.
3. Add endpoints for verify/resend/reset/2FA setup and challenge flows.
4. Add middleware/helpers so downstream domains can enforce fully verified or step-up required consistently.
5. Add reCAPTCHA verification behind a small adapter so it can be mocked in tests.
6. Add integration tests for happy path, expiry, replay, rate limit, and invalid token cases.

Deliverables

• Prisma migration(s) and schema updates.
• New auth endpoints and service layer.
• Shared guard/helper for contact-verification and step-up requirements.
• Consistent error/response contract that frontend can consume without guessing.
• Test coverage for all security-sensitive flows.

Acceptance Criteria

• A newly registered user can verify email via magic link and phone via OTP.
• Non-verified users can authenticate but are blocked from non-User-domain actions via a consistent backend contract.
• Forgot-password works with single-use, expiring tokens.
• Optional 2FA can be enabled and challenged during login.
• High-risk actions require a recent step-up auth check.
• Register/login fail cleanly when reCAPTCHA verification fails.
• All tokens/challenges are single-use, expiring, and covered by tests.

Out of Scope

• Social login, passkeys, and full identity-provider integrations.
• Building an SMS/email provider from scratch beyond the adapter/hooks needed by this repo.