Authentication

NestForge Pro ships a complete authentication module supporting email/password registration, Google OAuth, and passwordless magic links. Tokens follow the access + refresh pattern with automatic rotation.

Endpoints

Method	Path	Auth	Description
POST	/auth/register	No	Create a new account
POST	/auth/login	No	Login with email and password
POST	/auth/refresh	No	Refresh the access token
POST	/auth/magic-link	No	Send a magic link email
GET	/auth/magic-link/verify	No	Verify a magic link token
GET	/auth/google	No	Initiate Google OAuth flow
GET	/auth/google/callback	No	Google OAuth callback (redirects)
GET	/auth/me	Yes	Get the current authenticated user
POST	/auth/switch-team	Yes	Switch active team context
POST	/auth/logout	Yes	Logout and invalidate tokens

Token Flow

1. On login or registration the API returns an accessToken (short-lived) and a refreshToken (long-lived).
2. The access token is sent as a Bearer token in the Authorization header.
3. When the access token expires, call POST /auth/refresh with the refresh token to obtain a new pair.

Refresh Token Security

• Refresh tokens are bcrypt-hashed before being stored in the database. The raw token is never persisted.
• Every successful refresh performs token rotation -- a new refresh token is issued and the old hash is replaced.
• Replay detection: after rotation, presenting the old refresh token fails because the stored hash no longer matches.

Guards

JwtAuthGuard

Validates the Authorization: Bearer <accessToken> header using the JWT_SECRET. Applied to any route that requires authentication.

GoogleAuthGuard

Wraps the Passport Google OAuth 2.0 strategy. Initiates the redirect to Google on GET /auth/google and handles the callback on GET /auth/google/callback. After a successful OAuth flow the user is redirected to the frontend at APP_URL/auth/callback with accessToken and refreshToken as query parameters.

Magic Links

1. The client calls POST /auth/magic-link with an email address.
2. The server generates a signed token and sends it via the email module.
3. The user clicks the link which hits GET /auth/magic-link/verify?token=....
4. On success the API returns access and refresh tokens.

Team Switching

POST /auth/switch-team accepts a teamId in the body. The server verifies membership and returns new tokens that include the active team context in the JWT payload. See the Teams module for details on team management.

Environment Variables

JWT_SECRET=your-secret
JWT_REFRESH_SECRET=your-refresh-secret
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
APP_URL=http://localhost:5173

Adding a New OAuth Provider

1. Install the Passport strategy package (e.g., passport-github2).
2. Create a new strategy file in apps/api/src/modules/auth/strategies/ following the pattern in google.strategy.ts.
3. Create a corresponding guard in apps/api/src/modules/auth/guards/.
4. Add two routes to AuthController -- one to initiate the redirect and one for the callback.
5. Implement a handleXxxLogin method in AuthService to upsert the user and issue tokens.
6. Add the required environment variables (XXX_CLIENT_ID, XXX_CLIENT_SECRET) to your config validation schema.