Authentication Flow & Security

Relevant source files

The following files were used as context for generating this wiki page:

• backend/server.py
• frontend/src/App.js
• backend_test.py
• test_result.md
• frontend/src/App.css

The NEXUS platform implements a robust security architecture centered around JSON Web Token (JWT) authentication and secure password management. The system is designed as a digital command center, necessitating strict user isolation and protected access to sensitive data such as digital accounts, email addresses, and trial tracking information.

The security flow spans a FastAPI backend that handles identity management and a React-based frontend that maintains session state using a context provider. Security measures include salted password hashing, stateless token-based authorization, and glassmorphic UI elements that provide visual feedback on the system's security status.

Sources: backend/server.py, frontend/src/App.js, test_result.md

Backend Security Architecture

The backend leverages FastAPI and Motor (Async MongoDB driver) to manage user identities and secure resources. Authentication is stateless, using PyJWT for token generation and validation.

Identity Management & Password Hashing

User registration and login processes ensure that plain-text passwords are never stored. The system utilizes bcrypt for salting and hashing during the registration flow.

Function	Description	Implementation Detail
hash_password	Salts and hashes a plain string	bcrypt.hashpw(password.encode('utf-8'), bcrypt.gensalt())
verify_password	Compares plain text against stored hash	bcrypt.checkpw(plain_password.encode('utf-8'), hashed_password.encode('utf-8'))
create_access_token	Generates a JWT with expiration	Uses HS256 algorithm with a configurable SECRET_KEY

Sources: backend/server.py:186-200, backend/server.py:33-35

Authentication Data Flow

The following sequence diagram illustrates the process of a user obtaining an access token and using it to retrieve their profile.

Frontend Authentication Management

The frontend uses a React Context named AuthProvider to manage the global authentication state. This provider wraps the entire application, ensuring that user sessions persist through page refreshes by utilizing localStorage.

AuthProvider Logic

The provider maintains three primary state variables: user, token, and loading.

• Initialization: On mount, the provider checks localStorage for a token. If found, it sets the default Authorization header for axios and fetches user details.
• Login/Register: Upon successful response from the backend, the access_token is stored in both the local state and localStorage.
• Interceptors/Defaults: The Authorization header is updated globally: axios.defaults.headers.common['Authorization'] = 'Bearer <token>'.

Sources: frontend/src/App.js:14-88

Protected Route Enforcement

Access control is enforced via the ProtectedRoute component, which intercepts navigation attempts to the main application interface.

API Endpoints and Security Schemas

Authentication Endpoints

Endpoint	Method	Payload	Auth Required	Description
/api/register	POST	UserCreate	No	Registers new user and returns JWT
/api/login	POST	UserLogin	No	Validates credentials and returns JWT
/api/me	GET	None	Yes	Returns current user profile

Sources: backend/server.py:202-238, backend_test.py:20-25

User Data Model

class User(BaseModel):
    id: str  # UUID v4
    username: str
    email: EmailStr
    hashed_password: str
    created_at: datetime
    is_active: bool = True

Sources: backend/server.py:84-91

Security Center Features

The system includes a dedicated "Security Center" module designed to monitor the user's digital security posture. Although some metrics are currently placeholders, the architecture supports tracking specific security vulnerabilities.

• 2FA Tracking: Monitored via the two_fa_enabled boolean and two_fa_type enum (SMS, APP, HARDWARE) in the Account model.
• Email Security: Tracks the security_status of linked email addresses (SECURE, COMPROMISED, UNKNOWN).
• Security Score: A calculated metric returned by the dashboard API based on account settings.

Sources: backend/server.py:53-76, frontend/src/App.js:640-675, backend/server.py:382-390

Implementation Status

Based on internal testing, the core authentication system is fully implemented and operational on the backend, while the frontend currently experiences a routing issue post-login.

Task	Status	File
JWT Authentication System	✅ Working	backend/server.py
Cyberpunk Auth UI	✅ Working	frontend/src/App.js
Protected Route Access	✅ Working	backend/server.py
Dashboard Stats Auth	✅ Working	backend/server.py

Sources: test_result.md:104-124, test_result.md:230-245

The NEXUS Authentication Flow provides a stateless, secure foundation for managing trial and account data. By combining FastAPI security dependencies with a centralized React AuthProvider, the system ensures that user data remains isolated and protected against unauthorized access.