Authentication & Security
Relevant source files
The following files were used as context for generating this wiki page:
The Authentication & Security system in MoodTune Backend is designed to manage user identity and secure access to music analysis data. It utilizes Supabase for primary user authentication via JSON Web Tokens (JWT) and handles complex OAuth2 flows with Spotify to access external musical data. The system ensures that user-generated content, such as song and playlist analyses, remains isolated and protected through database-level security policies.
Sources: CLAUDE.md:6-9, README.md:1-5, TEST_PLAN.md:20-25
Core Authentication Architecture
The application implements a multi-layered authentication strategy. Primary identity is managed through Supabase Auth, which provides the JWTs required for accessing protected FastAPI routes. For musical data access, the system maintains a secondary layer of Spotify OAuth tokens.
Supabase JWT Integration
Protected routes within the FastAPI application utilize a dependency injection pattern (Depends(get_current_user)) to validate incoming Bearer tokens against Supabase.
Sources: CLAUDE.md:65-72, TEST_PLAN.md:38-45
User Isolation and Row Level Security (RLS)
Security is enforced at the database layer using Postgres Row Level Security. This ensures that even if an application-level bug occurs, a user can only select, insert, or delete records associated with their unique user_id.
| Table | Policy Name | Logic |
|---|---|---|
song_analyses | "Users can view own song analyses" | auth.uid() = user_id |
playlist_analyses | "Users can insert own playlist analyses" | auth.uid() = user_id |
Sources: db/song_analyses.sql:13-25, db/playlist_analyses.sql:13-25
Spotify OAuth & Token Management
Accessing Spotify data requires a separate OAuth2 flow. The backend handles the generation of authorization URLs, callback processing, and proactive token refreshing to prevent session expiration.
OAuth Flow
The system manages the state parameter to prevent Cross-Site Request Forgery (CSRF) during the Spotify handshake.
Automated Token Refresh
To maintain seamless access, the backend checks the expires_at timestamp of Spotify tokens. If a token is expired or nearing expiration, the spotify_api service automatically utilizes the stored refresh_token to obtain a new access_token before proceeding with the user's request.
Sources: TEST_PLAN.md:188-210, tests/test_spotify.py:30-100
API Security Controls
The backend implements standard web security practices to protect the API surface area.
CORS Configuration
Cross-Origin Resource Sharing is strictly controlled via environment variables to ensure only authorized frontend domains can interact with the API.
# app/main.py:33-39
app.add_middleware(
CORSMiddleware,
allow_origins=settings.BACKEND_CORS_ORIGINS,
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
Sources: app/main.py:33-39, README.md:10
Security Headers and Error Handling
- 401 Unauthorized: Returned when a JWT is invalid or expired.
- 403 Forbidden: Returned when an authenticated user attempts to access an analysis ID belonging to another user.
- 413 Payload Too Large: Enforced during audio uploads and catalog processing to prevent Denial of Service (DoS) via massive files.
Sources: TEST_PLAN.md:270-285, app/api/v1/song_analysis.py:145-150, app/api/v1/catalog.py:42-47
Summary
The Authentication & Security module provides a robust foundation for the MoodTune Backend by combining Supabase identity management with granular Spotify OAuth controls. By enforcing Row Level Security (RLS) and strict JWT validation, the system guarantees user data isolation while providing a seamless music analysis experience.
Sources: CLAUDE.md:6-9, TEST_PLAN.md:5-15