Authentication & Authorization

Relevant source files

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

• apps/api/src/module/auth/auth.module.ts
• apps/api/src/module/auth/auth.controller.ts
• apps/api/src/module/auth/guards/auth.guard.ts
• apps/api/src/module/auth/services/authentication.service.ts
• apps/api/src/module/auth/services/google-auth.service.ts
• apps/api/src/module/auth/services/auth-orchestrator.service.ts
• apps/api/src/module/firebase/services/firebase-auth.service.ts
• apps/api/src/module/auth/services/user.service.ts
• apps/portal/app/services/auth.ts
• apps/api/src/module/atlassian/atlassian.controller.ts

The Authentication and Authorization system for the Ever Rec API is built using NestJS and relies heavily on Firebase for user management and authentication providers. It supports traditional email/password registration and login, as well as social login via Google. The system is designed around a central AuthModule which orchestrates various services to handle user creation, login, profile management, and securing API endpoints.

Authorization is managed through JWT (JSON Web Tokens) and NestJS Guards. After a successful login, the client receives an idToken and a refreshToken. The idToken is used to authenticate subsequent requests to protected endpoints, which are validated by the AuthGuard. The system also includes mechanisms for token refreshing, password resets, and email verification, providing a comprehensive security foundation for the application.

Core Architecture

The authentication system is modular, with responsibilities separated into distinct services. The AuthModule serves as the central hub, importing necessary modules like JwtModule and FirebaseModule, and providing the various services that make up the auth system.

Sources: apps/api/src/module/auth/auth.module.ts

Key Components

Component	Description	Source File
AuthModule	The main NestJS module that encapsulates all authentication-related logic, providers, and controllers.	apps/api/src/module/auth/auth.module.ts
AuthController	Exposes the authentication and user management endpoints (e.g., /login, /register, /user-data).	apps/api/src/module/auth/auth.controller.ts
AuthOrchestratorService	Acts as a facade, coordinating various authentication and user management tasks by delegating to more specialized services.	apps/api/src/module/auth/services/auth-orchestrator.service.ts
AuthenticationService	Handles the core logic for email/password registration and login.	apps/api/src/module/auth/services/authentication.service.ts
GoogleAuthService	Manages the Google OAuth login flow, including token exchange and user creation.	apps/api/src/module/auth/services/google-auth.service.ts
UserService	Interacts with Firebase Admin SDK to perform user-related operations like creating, fetching, updating, and deleting users.	apps/api/src/module/auth/services/user.service.ts
FirebaseAuthService	A wrapper around Firebase REST and Admin APIs for authentication tasks like signing up, logging in, and verifying tokens.	apps/api/src/module/firebase/services/firebase-auth.service.ts
AuthGuard	A NestJS guard that protects API endpoints by validating the JWT idToken present in the request headers.	apps/api/src/module/auth/guards/auth.guard.ts
TokenService	Manages JWT token refreshing.	apps/api/src/module/auth/services/tokens/token.service.ts
AtlassianController	Handles OAuth flows for third-party Atlassian integrations like Jira and Trello, demonstrating authorization for external services.	apps/api/src/module/atlassian/atlassian.controller.ts

Service Interaction Diagram

The following diagram illustrates the relationships and dependencies between the primary services in the AuthModule.

Authentication Flows

The system supports multiple authentication methods, each with a distinct flow.

Email & Password Registration

A new user can register with their email, password, and an optional username. The backend validates the data, creates a user in Firebase Authentication, and adds a corresponding user profile to the Firebase Realtime Database.

Email & Password Login

Registered users can log in using their email and password. The service checks if the account is associated with a social provider first. If not, it authenticates against Firebase and returns new tokens.

Google OAuth Login

Users can log in via their Google account. The frontend obtains a credential from Google, which is sent to the backend. The backend exchanges this credential for a Firebase session, creating a new user if one doesn't already exist.

Authorization

Authorization is handled by the AuthGuard, which protects specific routes and ensures that only authenticated users can access them.

AuthGuard

The AuthGuard is a NestJS CanActivate guard. For any request to a protected endpoint, it performs the following steps:

1. Extracts the idtoken and refreshtoken from the request headers.
2. Throws an UnauthorizedException if the idtoken is missing.
3. Verifies the idtoken using the TokenService.
4. If verification is successful, it attaches the decoded user payload to the request object, making it available in the controller.
5. If verification fails, it throws an UnauthorizedException.

This flow ensures that every request to a protected resource is properly authenticated.

JWT Configuration

The JwtModule is configured asynchronously within the AuthModule. It retrieves settings from environment variables, allowing for flexible configuration across different environments.

Setting	Environment Variable	Default Value	Description
secret	REC_JWT_SECRET	(none)	The secret key used to sign the JWT. Required.
expiresIn	REC_JWT_EXPIRES_IN	1h	The expiration time for the JWT.
audience	REC_JWT_AUDIENCE	ever-rec	The intended audience of the token.
issuer	REC_JWT_ISSUER	rec-service	The issuer of the token.

Source: apps/api/src/module/auth/auth.module.ts:18-34

API Endpoints

The AuthController defines the public-facing API for all authentication and user management operations.

Endpoint	Method	Guarded	Description
/api/v1/auth/register	POST	No	Registers a new user with email and password.
/api/v1/auth/login	POST	No	Logs in a user with email and password.
/api/v1/auth/login-google	POST	No	Logs in or registers a user using a Google credential.
/api/v1/auth/user-data	GET	Yes	Retrieves the authenticated user's profile data.
/api/v1/auth/user-data	PUT	Yes	Updates the authenticated user's display name.
/api/v1/auth/upload-avatar	POST	Yes	Uploads and updates the user's avatar.
/api/v1/auth/email	PUT	Yes	Changes the authenticated user's email address.
/api/v1/auth/password	PUT	Yes	Changes the authenticated user's password after verifying the old one.
/api/v1/auth/user	DELETE	Yes	Deletes the authenticated user's account and all associated data.
/api/v1/auth/refresh-token	GET	No	Refreshes an expired idToken using a valid refreshToken.
/api/v1/auth/send-password-reset-email	POST	No	Sends a password reset link to the specified email.
/api/v1/auth/send-email-verification	POST	No	Sends an email verification link. Requires a valid idToken in the body.

Source: apps/api/src/module/auth/auth.controller.ts (whole file)

Summary

The ever-rec authentication and authorization system is a robust, well-structured module that leverages the power of NestJS and Firebase. It provides a secure foundation by handling user identity through multiple providers, protecting API endpoints with JWT-based guards, and offering a clear set of services for managing the entire user lifecycle. The use of an orchestrator service simplifies the controller logic and promotes a clean separation of concerns, making the system maintainable and extensible.