Auth: Email Login Flow

[Ayush8923]

Issue: ProjectTech4DevAI/kaapi-frontend#115

Summary:

• Add passwordless email login via magic link (POST /auth/magic-link → email → GET /auth/magic-link/verify).
• Add shared token generation/verification functions in services/auth.py for both invite and magic link tokens.
• Add SMTP email configuration and HTML email templates for both flows.

Checklist

Before submitting a pull request, please ensure that you mark these task.

• Ran fastapi run --reload app/main.py or docker compose up in the repository root and test.
• If you've fixed a bug or added code that is tested and has test cases.

Summary by CodeRabbit

• New Features

  • Added magic link authentication for passwordless login via email.
  • Added invitation verification endpoint for new user onboarding.
  • Email notifications for project invitations and magic link sign-in requests.

• Documentation

  • Added API documentation for magic link request/verification and invitation verification endpoints.

• Chores

  • Added SMTP and email configuration options (host, port, credentials, sender details).
  • Added frontend host configuration for email links.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e29790d7-778a-40df-b5e4-e5720bfd4641

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This pull request adds authentication via magic links and email invitations with SMTP configuration support. It introduces new authentication endpoints, token generation/verification services, email templates, configuration settings, and comprehensive test coverage for the new flows.

Changes

Cohort / File(s)	Summary
Configuration & Environment .env.example, backend/app/core/config.py	Added SMTP and email configuration variables (host, port, TLS, user, password), email sender settings (from email/name), frontend URL, and token expiration durations. Introduced computed property emails_enabled that checks SMTP and sender availability.
Authentication Routes backend/app/api/routes/auth.py	Added three new endpoints: GET /auth/invite/verify (validates invite token, activates user, returns JWT), POST /auth/magic-link (generates magic link token and sends email), and GET /auth/magic-link/verify (validates magic link token and returns JWT). Updated imports for token/email generation utilities.
User Invitation Email Integration backend/app/api/routes/user_project.py	Extended add_project_users to generate invitation tokens and send emails to newly added users after commit, with error handling per recipient and conditional sending based on email enablement.
Authentication Models & Services backend/app/models/auth.py, backend/app/models/__init__.py, backend/app/services/auth.py	Added MagicLinkRequest request model. Implemented token generation and verification functions (generate_email_token, verify_email_token, generate_invite_token, verify_invite_token, generate_magic_link_token, verify_magic_link_token) with type-specific and expiration handling.
Email Utilities & Templates backend/app/utils.py, backend/app/email-templates/build/*	Added email generation helpers (generate_invite_email, generate_magic_link_email) and corresponding HTML email templates for invitations and magic link sign-in with placeholder variables for dynamic content.
API Documentation backend/app/api/docs/auth/invite_verify.md, backend/app/api/docs/auth/magic_link.md, backend/app/api/docs/auth/magic_link_verify.md	Added endpoint documentation describing behavior, request/response parameters, validation steps, error responses, and HTTP status codes for invite and magic link verification flows.
Test Coverage backend/app/tests/api/test_auth.py, backend/app/tests/api/test_user_project.py	Added comprehensive test suites for magic link request/verify and invite verify endpoints, including error cases (invalid token, nonexistent user, inactive user), email sending verification, and token generation roundtrip validation. Added test for user project email invitation sending.

Sequence Diagram(s)

sequenceDiagram
actor User
participant Frontend
participant API
participant AuthService
participant EmailService
participant Database
User->>Frontend: Request magic link login
Frontend->>API: POST /auth/magic-link (email)
API->>Database: Lookup user by email
Database-->>API: User record
API->>AuthService: Generate magic link token
AuthService-->>API: Signed JWT token
API->>EmailService: Send magic link email
EmailService-->>User: Email with sign-in link
API-->>Frontend: Success response
User->>Frontend: Click link from email
Frontend->>API: GET /auth/magic-link/verify?token=...
API->>AuthService: Verify magic link token
AuthService-->>API: Decoded payload (email)
API->>Database: Lookup user by email
Database-->>API: User record
API->>Database: Activate user (if inactive)
Database-->>API: Updated user
API->>AuthService: Generate access JWT with project context
AuthService-->>API: Access token
API-->>Frontend: Access token + HTTP-only cookies
Frontend-->>User: Authenticated session

Loading

sequenceDiagram
actor User
participant Admin
participant API
participant AuthService
participant EmailService
participant Database
Admin->>API: POST /projects/{id}/users (add new user)
API->>Database: Commit new project user
Database-->>API: Success
API->>Database: Fetch organization & project
Database-->>API: Org/project records
API->>AuthService: Generate invite token
AuthService-->>API: Signed JWT token (org_id, project_id)
API->>EmailService: Generate & send invitation email
EmailService-->>User: Email with acceptance link
API-->>Admin: Success (user list)
User->>API: GET /auth/invite/verify?token=...
API->>AuthService: Verify invite token
AuthService-->>API: Decoded payload (email, org_id, project_id)
API->>Database: Lookup user by email
Database-->>API: User record
API->>Database: Activate user (if inactive)
Database-->>API: Updated user
API->>AuthService: Generate access JWT with org/project context
AuthService-->>API: Access token
API-->>User: Access token + HTTP-only cookies

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~28 minutes

Possibly related PRs

• Kaapi v1.0: Permissions Review and Authorization Cleanup #501 — Modifies authentication routes and models; likely interacts with the new invite/magic-link additions in this PR.

Suggested labels

enhancement, ready-for-review

Suggested reviewers

• AkhileshNegi
• Prajna1999
• vprashrex

Poem

🐰 With tokens signed and emails sent,
A magical link through which users went,
Invitations hop through the SMTP wire,
Fresh auth flows to take us higher!
The rabbit approves this grand design! 🌟

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: introducing an email-based login flow (magic link authentication) as a new feature.
Docstring Coverage	✅ Passed	Docstring coverage is 86.05% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/email-validation-flow

---

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 and usage tips.}