Security & Encryption

Relevant source files

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

• ai_backend/core/security.py
• ai_backend/services/encryption_service.py
• ai_backend/api/public_api.py
• README.md
• MISSING_INFO.md
• infra/terraform/main.tf

The ClassMate project employs a multi-layered security architecture designed to protect user data, ensure API integrity, and provide robust encryption for sensitive information. This system encompasses identity management through Firebase, infrastructure-level security via AWS, and application-level hardening including rate limiting, hybrid encryption, and request validation.

The security framework focuses on protecting "Identity & Access" and "Data Integrity," ensuring that all database mutations are tracked and sensitive data is encrypted both at rest and in transit.
Sources: README.md:57-80, ai_backend/core/security.py:1-12

API Hardening and Middleware

ClassMate implements several FastAPI middlewares to protect the backend from common web vulnerabilities and resource exhaustion. This is managed primarily through the setup_security function which initializes validation, security headers, and rate limiting.
Sources: ai_backend/core/security.py:220-227

Rate Limiting

The system uses a RateLimitMiddleware to prevent abuse. It currently utilizes an in-memory RateLimitStore to track per-IP requests against specific endpoint patterns. While the current implementation is in-memory, the architecture is designed to be "Redis-ready" for production clusters.
Sources: ai_backend/core/security.py:25-83

Endpoint Pattern	Max Requests	Window (Seconds)
/auth/login	10	60
/auth/register	5	60
/api/v1/ai/	30	60
/api/v1/transcribe	10	60
/api/v1/	100	60
/	200	60
Sources: ai_backend/core/security.py:44-51

Security Headers

The SecurityHeadersMiddleware enforces browser-level security policies by injecting specific HTTP headers into every response.
Sources: ai_backend/core/security.py:91-137

• X-Content-Type-Options: Set to nosniff to prevent MIME-type sniffing.
• X-Frame-Options: Set to DENY to prevent clickjacking.
• Content-Security-Policy: Restricts sources for scripts, styles, and connections to 'self'.
• Strict-Transport-Security: Enabled in production with a 1-year max-age.
• Permissions-Policy: Disables camera and geolocation while allowing microphone access for the application itself.
  Sources: ai_backend/core/security.py:99-130

Request Validation and Sanitization

The RequestValidationMiddleware inspects incoming requests for suspicious patterns, including SQL injection attempts (union select, drop table) and path traversal (../.., /etc/passwd).
Sources: ai_backend/core/security.py:146-188

Encryption Services

The EncryptionService provides comprehensive data protection using both symmetric and asymmetric cryptography. It handles master key management, user-specific key pairs, and hybrid encryption for large data like audio files.
Sources: ai_backend/services/encryption_service.py:18-35

Hybrid Audio Encryption

To secure audio recordings, the system uses hybrid encryption. A random AES-256-CBC key is generated to encrypt the audio data, and that AES key is then encrypted using the user's RSA-OAEP public key.
Sources: ai_backend/services/encryption_service.py:68-111

Sensitive Data and Session Security

The service also manages:

• Server-Side Encryption: Uses Fernet (symmetric) with a master key for sensitive data dictionaries.
• Secure Sharing: Generates share tokens containing session_id and user_id with an expiry, which are then encrypted.
• Password Hashing: Implements PBKDF2HMAC with SHA256 and 100,000 iterations for secure password storage.
  Sources: ai_backend/services/encryption_service.py:202-273

API Key Management

The APIKeyManager handles third-party integration security. Keys are generated as cm_ prefixed tokens, and their hashes (using PBKDF2HMAC) are stored in the database to prevent plain-text exposure in the event of a database breach.
Sources: ai_backend/api/public_api.py:21-30

Key Validation Flow

1. Extraction: Retrieve credentials via HTTPBearer.
2. Rate Limit Check: Verify client IP against limits (1000 requests per hour).
3. Database Lookup: Fetch active, non-expired keys.
4. Cryptographic Verification: Compare the provided key against the stored hash using encryption_service.verify_password.
   Sources: ai_backend/api/public_api.py:53-100

Infrastructure Security (AWS)

Production infrastructure is defined in Terraform with several security-centric configurations.
Sources: infra/terraform/main.tf:1-15

• Network Isolation: Uses Private Subnets for the RDS PostgreSQL database and ElastiCache Redis, ensuring they are not reachable from the public internet.
• Security Groups: Implements strict ingress rules, only allowing the API security group to access the database on port 5432 and Redis on port 6379.
• Storage Encryption: The S3 bucket and RDS instances have storage_encrypted = true and sse_algorithm = AES256.
  Sources: infra/terraform/main.tf:76-90, infra/terraform/main.tf:124-138, infra/terraform/main.tf:181-196

Summary

Security in ClassMate is a integrated concern ranging from low-level infrastructure isolation in AWS to high-level application logic. The use of hybrid encryption for audio ensures that even if backend storage is compromised, private recordings remain unreadable without user-specific private keys. Ongoing improvements identified in the project documentation include migrating OAuth tokens to the encryption service to move away from plaintext storage.
Sources: MISSING_INFO.md:7-14, README.md:82-88