Authentication & Identity Bridge

Relevant source files

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

• ai_backend/api/public_api.py
• ai_backend/core/security.py
• README.md
• MISSING_INFO.md
• PROJECT_STRUCTURE.md
• GAPS_IMPLEMENTATION_SUMMARY.md

ClassMate utilizes a hybrid authentication architecture designed for scalability and production-grade security. The system combines external identity providers with an internal Identity Bridge to manage user synchronization and authorized access to AI processing resources. Identity is primarily managed via Firebase Authentication, which handles user credentials, while the backend maintains a local representation in PostgreSQL for session management and audit logging.

The Identity Bridge acts as the glue between the mobile/web clients and the internal backend services. It ensures that every request directed at the FastAPI backend is validated against a synchronized user record, facilitating role-based access control and secure data isolation.

Sources: README.md:9-11, README.md:46-51, PROJECT_STRUCTURE.md:144-149

Authentication Architecture

The system employs a multi-layered authentication strategy. Firebase Authentication handles the primary identity layer (Email/Password and Google OAuth), while the backend issues JWT tokens or validates API keys for specialized access.

Identity Providers

ClassMate supports two primary authentication methods for end-users:

• Email Authentication: Implemented using bcrypt for password hashing and internal JWT tokens for session maintenance.
• Google OAuth: Integrated for seamless mobile onboarding, utilizing SHA-1 fingerprints for Android/iOS package verification.

Sources: MISSING_INFO.md:23-45

The Identity Bridge & Synchronization

The Identity Bridge is responsible for "Hybrid Auth," where Firebase handles the identity and the bridge automatically syncs Firebase users to the internal PostgreSQL database. This ensures that metadata, such as roles and audit logs, can be associated with a local user record.

User Synchronization Logic

1. The client provides a Firebase ID token to the backend.
2. The backend verifies the token and extracts the Unique Identifier (UID).
3. The system checks for a matching record in the local users table.
4. If no record exists, the bridge creates a new user entity, effectively "bridging" the external identity into the internal ecosystem.

Sources: README.md:47-49, GAPS_IMPLEMENTATION_SUMMARY.md:145-149

API Key Management

For third-party integrations and public access, the system includes an APIKeyManager. This component handles the generation, storage, and validation of long-lived API keys.

Component	Description
Generation	Creates keys prefixed with cm_ using secrets.token_urlsafe.
Storage	Keys are stored as salted hashes in the APIKey table.
Validation	Constant-time comparison is used to verify submitted keys against stored hashes.
Permissions	JSON-encoded list of scopes (e.g., transcribe, generate-notes).

Sources: ai_backend/api/public_api.py:31-90

API Key Validation Flow

Security Hardening

The authentication system is supported by several security middlewares defined in the core security module. These prevent unauthorized access and protect against common web vulnerabilities.

Security Components Table

Feature	Implementation	Source
Rate Limiting	Per-IP tiers (e.g., 10 logins/min, 100 API requests/min).	ai_backend/core/security.py:46-53
Token Encryption	OAuth tokens are intended to be encrypted at rest using EncryptionService.	MISSING_INFO.md:7-12
CSRF Protection	Generation and constant-time verification of CSRF tokens.	ai_backend/core/security.py:214-222
Security Headers	Implementation of nosniff, X-Frame-Options: DENY, and strict CSP.	ai_backend/core/security.py:112-135

Sources: ai_backend/core/security.py:107-222, MISSING_INFO.md:7-12

Rate Limiting Logic

The RateLimitMiddleware enforces thresholds based on endpoint patterns. While currently utilizing an in-memory RateLimitStore, the architecture is designed to be "Redis-ready" for production clusters.

# ai_backend/core/security.py:46-53
RATE_LIMITS = {
    "/auth/login": (10, 60),          # 10 login attempts per minute
    "/auth/register": (5, 60),         # 5 registrations per minute
    "/api/v1/ai/": (30, 60),          # 30 AI requests per minute
    "/api/v1/transcribe": (10, 60),   # 10 transcriptions per minute
}

Sources: ai_backend/core/security.py:46-53

Data Models

The identity system relies on several key database models to track access and security.

APIKey Model Fields

Field	Type	Description
id	UUID	Primary identifier for the key record.
user_id	String	Link to the bridged internal user.
api_key_hash	String	Salted hash of the API key.
permissions	JSON	Scopes assigned to the key.
is_active	Boolean	Kill-switch for the API key.

Sources: ai_backend/api/public_api.py:39-49

Conclusion

The Authentication & Identity Bridge in ClassMate provides a robust framework for managing user identity across heterogeneous platforms. By offloading primary credentials to Firebase while maintaining a local Identity Bridge, the system achieves a balance between ease of use for end-users and strict administrative control for the backend. Future iterations focus on migrating OAuth token storage to an encrypted format and transitioning rate limiting to a distributed Redis store to support the target 100k+ user base.

Sources: README.md:1-5, MISSING_INFO.md:7-12, GAPS_IMPLEMENTATION_SUMMARY.md:215-220