Skip to content

auth.md

Latest commit

 

History

History
89 lines (64 loc) · 3.52 KB

auth.md

File metadata and controls

89 lines (64 loc) · 3.52 KB

Authentication System Documentation

This document outlines the architecture, security features, and implementation details of the authentication system.

🏗️ Architecture

The authentication layer is built on top of Better Auth with a Drizzle ORM adapter, ensuring type-safe interaction with the PostgreSQL database.

Core Components:

  • Config: lib/auth.ts
  • API Route: app/api/auth/[...all]/route.ts (Custom logic wrappers)
  • Frontend: components/auth/*
  • Security Utilities: lib/security/*

🔐 Sign-Up Features

The registration process (/auth/sign-up) includes multiple layers of security to prevent bot automation and abuse:

  1. Rate Limiting:

    • Restricted to 10 registrations per hour per IP address.
    • Implementation: lib/security/ip-rate-limiter.ts.

  2. Cloudflare Turnstile CAPTCHA:

    • Requires a valid Turnstile token to proceed.
    • Verification is performed server-side with Cloudflare's API.
    • Secret keys are fetched dynamically from System Settings (system_config).

  3. Device Fingerprinting:

    • Uses thumbmarkjs to collect browser canvas and audio entropy.
    • A unique fingerprint hash is generated and stored with the user record.
    • Enforcement: Registration is blocked if the fingerprint is missing.

  4. Password Security:

    • Strength Meter: Real-time feedback on password complexity.
    • Breach Check: Verifies if the password exists in known data leaks (Pwned Passwords) before accepting it.

  5. Referral Tracking:

    • Captures referral codes from URL or LocalStorage.
    • Links the new user to the referrer (referredBy field).

🛡️ Sign-In Features

The login process (/auth/sign-in) is fortified with:

  1. Rate Limiting:

    • Restricted to 20 login attempts per 15 minutes per IP.
    • Temporary IP block for 30 minutes if exceeded.

  2. Turnstile CAPTCHA:

    • Integrated into the login form to stop brute-force attacks.

  3. VPN/Proxy Detection:

    • Checks the user's IP against known proxy lists.
    • Blocks login access if a high-risk VPN is detected.

  4. Ban Enforcement:

    • Checks userStatus (Status 2 = Banned) and bannedUntil timestamp.
    • Returns a detailed rejection message with the ban reason and expiry.

  5. Login Activity Logging:

    • Successful logins are recorded in the login_activity table.
    • Data Captured:
      • IP Address
      • User Agent (Browser, OS, Device Type via ua-parser-js)
      • Timestamp

💾 Database Schema

Users Table (users)

  • emailVerified (boolean): Tracks verification status.
  • twoFactorEnabled (boolean): Infrastructure ready for TOTP (Planned).
  • registrationFingerprint (string): Immutable device hash from sign-up.
  • suspiciousActivityScore (int): 0-100 score based on behavior.

Login Activity Table (login_activity)

  • Links to users.id.
  • Immutable log of all successful access events.

📧 Email Verification

  • Provider: SMTP / Nodemailer.
  • Flow: Sends a 6-digit OTP to the user's email.
  • Configuration: Settings are fetched from environment variables (SMTP_HOST, SMTP_USER, etc.).

🚀 Future Roadmap (Planned)

  • 2FA (Two-Factor Authentication): TOTP integration (Google Authenticator).
  • Passkey Support: WebAuthn biometric login.
  • Social Logins: Google & Discord OAuth providers.