User Module

UserModule - User Authentication

UserModule provides complete user authentication with email/password, OAuth, sessions, and JWT tokens.

Quick Start

pythonCopy code
from myfy.core import Application
from myfy.data import DataModule
from myfy.web import WebModule
from myfy.web.auth import AuthModule
from myfy.user import UserModule, BaseUser
from sqlalchemy.orm import Mapped, mapped_column
from sqlalchemy import String

# Extend BaseUser with custom fields
class User(BaseUser):
    __tablename__ = "users"
    phone: Mapped[str | None] = mapped_column(String(20))

# Create module
user_module = UserModule(
    user_model=User,
    oauth_providers=["google", "github"],
    auto_create_tables=True,
)

# Set up application
app = Application()
app.add_module(DataModule())
app.add_module(WebModule())
app.add_module(AuthModule(
    authenticated_provider=user_module.get_authenticated_provider(),
))
app.add_module(user_module)

Configuration

Environment variables use the MYFY_USER_ prefix:

OAuth Configuration

bashCopy code
# Google OAuth
MYFY_USER_OAUTH_GOOGLE_CLIENT_ID=your-client-id
MYFY_USER_OAUTH_GOOGLE_CLIENT_SECRET=your-secret

# GitHub OAuth
MYFY_USER_OAUTH_GITHUB_CLIENT_ID=your-client-id
MYFY_USER_OAUTH_GITHUB_CLIENT_SECRET=your-secret

Module Options

pythonCopy code
UserModule(
    user_model=User,              # Custom user model (must extend BaseUser)
    oauth_providers=["google"],   # OAuth providers to enable
    auto_create_tables=True,      # Create tables on start
    enable_routes=True,           # Register auth routes
    enable_templates=True,        # Provide Jinja2 templates
)

Custom User Model

pythonCopy code
from myfy.user import BaseUser
from sqlalchemy.orm import Mapped, mapped_column
from sqlalchemy import String, Boolean

class User(BaseUser):
    __tablename__ = "users"

    # Custom fields
    phone: Mapped[str | None] = mapped_column(String(20))
    is_admin: Mapped[bool] = mapped_column(Boolean, default=False)
    company_id: Mapped[int | None] = mapped_column(ForeignKey("companies.id"))

    # Relationships
    company: Mapped["Company"] = relationship(back_populates="users")

BaseUser provides:

• id: Primary key
• email: Unique email address
• password_hash: Hashed password
• is_active: Account active status
• is_verified: Email verified status
• created_at, updated_at: Timestamps

Protected Routes

pythonCopy code
from myfy.web import route, Authenticated

@route.get("/profile")
async def profile(user: User) -> dict:
    # user is injected if authenticated
    # Returns 401 if not authenticated
    return {"email": user.email, "name": user.name}

@route.get("/admin")
async def admin_dashboard(user: User) -> dict:
    if not user.is_admin:
        abort(403, "Admin access required")
    return {"message": "Welcome, admin"}

Auth Routes

UserModule registers these routes by default:

Using UserService

pythonCopy code
from myfy.user import UserService

@route.post("/users")
async def create_user(body: CreateUserRequest, user_service: UserService) -> dict:
    user = await user_service.create(
        email=body.email,
        password=body.password,
    )
    return {"id": user.id}

@route.get("/users/{user_id}")
async def get_user(user_id: int, user_service: UserService) -> dict:
    user = await user_service.get_by_id(user_id)
    if not user:
        abort(404, "User not found")
    return {"email": user.email}

Session vs JWT

Session-Based (Web)

Default for web routes. Session ID stored in cookie.

pythonCopy code
@route.get("/dashboard")
async def dashboard(user: User) -> str:
    # Session cookie auto-validated
    return render_template("dashboard.html", user=user)

JWT-Based (API)

For API clients, use JWT tokens.

pythonCopy code
from myfy.user import JWTService

@route.post("/api/login")
async def api_login(body: LoginRequest, jwt_service: JWTService, user_service: UserService) -> dict:
    user = await user_service.authenticate(body.email, body.password)
    if not user:
        abort(401, "Invalid credentials")
    token = jwt_service.create_token(user)
    return {"token": token}

Client sends token in header:

Copy code
Authorization: Bearer <token>

OAuth Integration

Google OAuth

pythonCopy code
user_module = UserModule(
    user_model=User,
    oauth_providers=["google"],
)

Login link:

htmlCopy code
<a href="/auth/google" class="btn">Login with Google</a>

GitHub OAuth

pythonCopy code
user_module = UserModule(
    user_model=User,
    oauth_providers=["github"],
)

Login link:

htmlCopy code
<a href="/auth/github" class="btn">Login with GitHub</a>

Email Verification

Enable verification:

bashCopy code
MYFY_USER_REQUIRE_EMAIL_VERIFICATION=true

Users must verify email before full access. Verification link sent on registration.

Password Reset

1. User requests reset at /auth/forgot-password
2. Reset email sent with secure token
3. User clicks link to /auth/reset-password?token=...
4. User enters new password

Custom Templates

Override default templates by placing files in your templates directory:

Copy code
frontend/templates/auth/
  login.html
  register.html
  forgot-password.html
  reset-password.html
  verify-email.html

Best Practices

1. Set a strong SECRET_KEY - Use a long random string
2. Enable email verification - For production apps
3. Use OAuth where possible - Reduces password management burden
4. Extend BaseUser - Don't modify it directly
5. Use sessions for web, JWT for API - Different use cases
6. Hash passwords - UserService handles this automatically
7. Rate limit auth routes - Prevent brute force attacks