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.}