​

Authentication & Security Architecture

​

Authentication Methods

​

1. Password Registration & Login

• Password hashing with Bcrypt utilizing unique salts and server-side peppers.
• Account lockout mechanism after multiple consecutive failed attempts.
• Password reset flow using timed, single-use JWT reset tokens delivered via Resend.

​

2. Social Authentication

• Supported providers: Google and Apple.
• Client sends third-party identity token; backend validates signature and retrieves profile details.
• Auto-provisions new user accounts or links existing profiles seamlessly.

​

3. Passwordless OTP

• Secure 6-digit OTP generated via cryptographically secure RNG.
• Configurable expiration window (default: 10 minutes) and max retry throttling.

​

4. Two-Factor Authentication (2FA / TOTP)

• Implemented with standard RFC 6238 TOTP (Google Authenticator, Authy).
• Generates QR code and emergency recovery backup codes.
• Required during login if enabled on the account.

​

Token Lifecycle Management

POST /api/v2/auth/refresh
Content-Type: application/json

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

​

Wallet PIN Security

• Salted and hashed independently from user passwords.
• Throttled attempts with OTP recovery flow (/api/v2/auth/reset-wallet-pin-otp).

​

Role-Based Access Control (RBAC)

• USER: Regular student account.
• CREATOR: Can author courses, questions, and content.
• MODERATOR: Can review contests and user submissions.
• VIEWER: Read-only administrative access for analytics.
• ADMIN: Content and user management access.
• SUPER_ADMIN: Full root system privileges and contract execution.