User Management

​

User Roles

1. Regular Users: Can create quizzes, play games, manage their own content
2. Moderators: Can review and rate public quizzes
3. Admins: Full system access, including user deletion

​

User Model

class User:
    id: uuid.UUID
    email: str (unique)
    username: str (unique)
    password: str (hashed, nullable)
    verified: bool
    created_at: datetime
    auth_type: UserAuthTypes  # LOCAL, GOOGLE, GITHUB, CUSTOM
    storage_used: int  # Bytes used
    avatar: bytes  # Base64 encoded
    require_password: bool
    totp_secret: str  # 2FA secret
    backup_code: str  # Recovery code

​

Authentication Methods

​

Local Authentication

• Passwords are hashed before storage
• Email verification required (verified: bool)
• Verification key sent via email (verify_key)

​

OAuth Providers

​

Two-Factor Authentication

• totp_secret: 32-character secret for authenticator apps
• Used with Google Authenticator, Authy, etc.

• Hardware security keys (YubiKey, etc.)
• Stored in FidoCredentials table
• Supports multiple keys per user

• 64-character hex string (backup_code)
• Used when primary 2FA method unavailable
• Generated automatically on account creation

​

User Sessions

class UserSession:
    id: uuid.UUID
    user: User
    session_key: str (unique, 64 chars)
    created_at: datetime
    ip_address: str
    user_agent: str
    last_seen: datetime

​

Session Management

• Sessions expire after inactivity
• Users can view active sessions
• Admins can revoke sessions
• last_seen updated on each request

​

API Keys

class ApiKey:
    key: str (48 characters, primary key)
    user: User

• Provide full account access
• Don’t expire automatically
• Used with Authorization: Bearer <key> header
• Should be treated as securely as passwords

​

Admin Operations

​

Delete User by ID

curl -X DELETE \
  'https://your-instance.com/api/v1/admin/user/id?user_id=550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer ADMIN_TOKEN'

{
  "deleted": 1
}

​

Delete User by Username

curl -X DELETE \
  'https://your-instance.com/api/v1/admin/user/username?username=johndoe' \
  -H 'Authorization: Bearer ADMIN_TOKEN'

​

Delete User by Email

curl -X DELETE \
  'https://your-instance.com/api/v1/admin/user/[email protected]' \
  -H 'Authorization: Bearer ADMIN_TOKEN'

​

Cascade Deletion

• Quizzes: All quizzes created by the user
• Game Results: Historical game session data
• Sessions: Active and expired user sessions
• API Keys: All API keys for the user
• FIDO Credentials: Registered security keys
• QuizTivities: Interactive content created by user
• Storage Items: Uploaded images and files (set to NULL)
• Ratings: Quiz ratings from the user

​

Storage Quotas

# Check current usage
user.storage_used  # Bytes

# Check against limit
from classquiz.config import settings
if user.storage_used > settings.free_storage_limit:
    raise HTTPException(status_code=409, detail="Storage limit reached")

​

Storage Calculation

• Tracked in user.storage_used (BigInteger, bytes)
• Updated when uploading images
• Includes quiz images, cover images, and question images
• Checked before imports and uploads

if user.storage_used > settings.free_storage_limit:
    raise HTTPException(status_code=409, detail="Storage limit reached")

​

Moderator Tools

​

Authentication Guards

​

Regular User Authentication

from classquiz.auth import get_current_user

@router.get("/protected")
async def protected_route(user: User = Depends(get_current_user)):
    return {"user_id": user.id}

​

Moderator Authentication

from classquiz.auth import get_current_moderator

@router.get("/moderation/status")
async def mod_only(user: User = Depends(get_current_moderator)):
    return {"status": "ok"}

​

Admin Authentication

from classquiz.auth import get_admin_user

@router.delete("/admin/user/id")
async def delete_user(user_id: UUID, _: User = Depends(get_admin_user)):
    return {"deleted": await User.objects.delete(id=user_id)}

​

Best Practices

​

Account Security

​

User Management

1. Soft deletes: Consider marking users as inactive instead of hard deletion
2. Audit logs: Track admin actions for compliance
3. Data export: Provide GDPR-compliant data export
4. Storage alerts: Notify users approaching storage limits

​

User Avatar Management

class User:
    avatar: bytes = ormar.LargeBinary(
        max_length=25000,
        represent_as_base64_str=True
    )

• Maximum size: 25KB
• Automatically encoded/decoded as base64
• Displayed in game lobbies and quiz listings

​

Password Management

class UpdatePassword(BaseModel):
    old_password: str
    new_password: str

• password field is nullable
• require_password: false for OAuth-only accounts
• Cannot change password if not set

​

User Queries

​

Find users by authentication type

local_users = await User.objects.filter(auth_type=UserAuthTypes.LOCAL).all()
google_users = await User.objects.filter(auth_type=UserAuthTypes.GOOGLE).all()

​

Find unverified users

unverified = await User.objects.filter(verified=False).all()

​

Check storage usage

over_quota = await User.objects.filter(
    storage_used__gt=settings.free_storage_limit
).all()

​

Find users with 2FA enabled

totp_users = await User.objects.filter(
    totp_secret__isnull=False
).all()

​

Integration Points

• Quizzes: Quiz.user_id foreign key
• Game Results: GameResults.user foreign key
• Storage: StorageItem.user foreign key
• Sessions: UserSession.user foreign key
• Ratings: Rating.user foreign key
• Controllers: Controller.user foreign key (for game controllers)