feat(auth): add e2e session endpoint for Cypress integration

- Introduced a new POST /e2e/session endpoint in AuthController for development use, allowing Cypress to obtain JWTs without UI login.
- Added validation to ensure the endpoint is only accessible in development mode with a valid E2E_AUTH_SECRET.
- Updated AuthService to issue session tokens for existing users based on email or userId.
- Enhanced unit tests to cover the new e2eSession functionality and its edge cases.
- Added E2E_AUTH_HEADER constant for consistent header usage across the application.

Author: tomast1337

apps/backend/.env.development.example

@@ -1,5 +1,9 @@
 NODE_ENV=
 
+# Optional: non-empty value enables `POST /v1/auth/e2e/session` (dev only) for Cypress —
+# same value as Cypress env `E2E_AUTH_SECRET` / `CYPRESS_E2E_AUTH_SECRET`.
+E2E_AUTH_SECRET=
+
 GITHUB_CLIENT_ID=
 GITHUB_CLIENT_SECRET=
 

apps/backend/src/auth/auth.controller.spec.ts

@@ -1,6 +1,10 @@
+import { BadRequestException, NotFoundException } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
 import { Test, TestingModule } from '@nestjs/testing';
 import type { Request, Response } from 'express';
 
+import { UserService } from '@server/user/user.service';
+
 import { AuthController } from './auth.controller';
 import { AuthService } from './auth.service';
 import { MagicLinkEmailStrategy } from './strategies/magicLinkEmail.strategy';
@@ -11,6 +15,16 @@ const mockAuthService = {
   discordLogin: jest.fn(),
   verifyToken: jest.fn(),
   loginWithEmail: jest.fn(),
+  issueSessionTokensForUser: jest.fn(),
+};
+
+const mockUserService = {
+  findByEmail: jest.fn(),
+  findByID: jest.fn(),
+};
+
+const mockConfigService = {
+  get: jest.fn(),
 };
 
 const mockMagicLinkEmailStrategy = {
@@ -36,6 +50,8 @@ describe('AuthController', () => {
           provide: MagicLinkEmailStrategy,
           useValue: mockMagicLinkEmailStrategy,
         },
+        { provide: UserService, useValue: mockUserService },
+        { provide: ConfigService, useValue: mockConfigService },
       ],
     }).compile();
 
@@ -192,4 +208,120 @@ describe('AuthController', () => {
       expect(authService.verifyToken).toHaveBeenCalledWith(req, res);
     });
   });
+
+  describe('e2eSession', () => {
+    it('returns 404 when not in development', async () => {
+      mockConfigService.get.mockImplementation((key: string) => {
+        if (key === 'NODE_ENV') return 'production';
+        if (key === 'E2E_AUTH_SECRET') return 'secret';
+        return undefined;
+      });
+
+      await expect(
+        controller.e2eSession('secret', { email: '[email protected]' }),
+      ).rejects.toBeInstanceOf(NotFoundException);
+    });
+
+    it('returns 404 when E2E_AUTH_SECRET is empty', async () => {
+      mockConfigService.get.mockImplementation((key: string) => {
+        if (key === 'NODE_ENV') return 'development';
+        if (key === 'E2E_AUTH_SECRET') return '';
+        return undefined;
+      });
+
+      await expect(
+        controller.e2eSession('secret', { email: '[email protected]' }),
+      ).rejects.toBeInstanceOf(NotFoundException);
+    });
+
+    it('returns 404 when header secret is wrong', async () => {
+      mockConfigService.get.mockImplementation((key: string) => {
+        if (key === 'NODE_ENV') return 'development';
+        if (key === 'E2E_AUTH_SECRET') return 'good';
+        return undefined;
+      });
+
+      await expect(
+        controller.e2eSession('bad', { email: '[email protected]' }),
+      ).rejects.toBeInstanceOf(NotFoundException);
+    });
+
+    it('returns 400 when both email and userId are provided', async () => {
+      mockConfigService.get.mockImplementation((key: string) => {
+        if (key === 'NODE_ENV') return 'development';
+        if (key === 'E2E_AUTH_SECRET') return 's';
+        return undefined;
+      });
+
+      await expect(
+        controller.e2eSession('s', { email: '[email protected]', userId: 'id' }),
+      ).rejects.toBeInstanceOf(BadRequestException);
+    });
+
+    it('returns 400 when neither email nor userId', async () => {
+      mockConfigService.get.mockImplementation((key: string) => {
+        if (key === 'NODE_ENV') return 'development';
+        if (key === 'E2E_AUTH_SECRET') return 's';
+        return undefined;
+      });
+
+      await expect(controller.e2eSession('s', {})).rejects.toBeInstanceOf(
+        BadRequestException,
+      );
+    });
+
+    it('returns tokens for existing user by email', async () => {
+      mockConfigService.get.mockImplementation((key: string) => {
+        if (key === 'NODE_ENV') return 'development';
+        if (key === 'E2E_AUTH_SECRET') return 's';
+        return undefined;
+      });
+      const user = { _id: 'u1', email: '[email protected]', username: 'u' };
+      mockUserService.findByEmail.mockResolvedValueOnce(user);
+      mockAuthService.issueSessionTokensForUser.mockResolvedValueOnce({
+        access_token: 'a',
+        refresh_token: 'r',
+      });
+
+      const out = await controller.e2eSession('s', { email: '[email protected]' });
+
+      expect(out).toEqual({ access_token: 'a', refresh_token: 'r' });
+      expect(mockUserService.findByEmail).toHaveBeenCalledWith('[email protected]');
+      expect(mockAuthService.issueSessionTokensForUser).toHaveBeenCalledWith(
+        user,
+      );
+    });
+
+    it('returns tokens for existing user by userId', async () => {
+      mockConfigService.get.mockImplementation((key: string) => {
+        if (key === 'NODE_ENV') return 'development';
+        if (key === 'E2E_AUTH_SECRET') return 's';
+        return undefined;
+      });
+      const user = { _id: 'u1', email: '[email protected]', username: 'u' };
+      mockUserService.findByID.mockResolvedValueOnce(user);
+      mockAuthService.issueSessionTokensForUser.mockResolvedValueOnce({
+        access_token: 'a',
+        refresh_token: 'r',
+      });
+
+      const out = await controller.e2eSession('s', { userId: 'abc' });
+
+      expect(out).toEqual({ access_token: 'a', refresh_token: 'r' });
+      expect(mockUserService.findByID).toHaveBeenCalledWith('abc');
+    });
+
+    it('returns 404 when user is not found', async () => {
+      mockConfigService.get.mockImplementation((key: string) => {
+        if (key === 'NODE_ENV') return 'development';
+        if (key === 'E2E_AUTH_SECRET') return 's';
+        return undefined;
+      });
+      mockUserService.findByEmail.mockResolvedValueOnce(null);
+
+      await expect(
+        controller.e2eSession('s', { email: '[email protected]' }),
+      ).rejects.toBeInstanceOf(NotFoundException);
+    });
+  });
 });

apps/backend/src/auth/auth.controller.ts

@@ -1,20 +1,34 @@
 import {
+  BadRequestException,
+  Body,
   Controller,
   Get,
+  Headers,
+  HttpCode,
   HttpException,
   HttpStatus,
   Inject,
   Logger,
+  NotFoundException,
   Post,
   Req,
   Res,
   UseGuards,
 } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
 import { AuthGuard } from '@nestjs/passport';
-import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
-import { Throttle } from '@nestjs/throttler';
+import {
+  ApiExcludeEndpoint,
+  ApiOperation,
+  ApiResponse,
+  ApiTags,
+} from '@nestjs/swagger';
+import { SkipThrottle, Throttle } from '@nestjs/throttler';
 import type { Request, Response } from 'express';
 
+import { E2E_AUTH_HEADER } from '@nbw/config';
+import { UserService } from '@server/user/user.service';
+
 import { AuthService } from './auth.service';
 import { MagicLinkEmailStrategy } from './strategies/magicLinkEmail.strategy';
 
@@ -27,6 +41,9 @@ export class AuthController {
     private readonly authService: AuthService,
     @Inject(MagicLinkEmailStrategy)
     private readonly magicLinkEmailStrategy: MagicLinkEmailStrategy,
+    @Inject(UserService)
+    private readonly userService: UserService,
+    private readonly configService: ConfigService,
   ) {}
 
   @Throttle({
@@ -119,6 +136,50 @@ export class AuthController {
     return this.authService.discordLogin(req, res);
   }
 
+  /**
+   * Development-only: mint JWT pair for an existing user so Cypress can `setCookie`
+   * without UI login. Disabled unless `NODE_ENV === 'development'` and
+   * `E2E_AUTH_SECRET` is non-empty; wrong/missing secret returns 404 to avoid
+   * advertising the route.
+   */
+  @Post('e2e/session')
+  @HttpCode(200)
+  @SkipThrottle()
+  @ApiExcludeEndpoint()
+  public async e2eSession(
+    @Headers(E2E_AUTH_HEADER) secret: string | undefined,
+    @Body() body: { email?: string; userId?: string },
+  ): Promise<{ access_token: string; refresh_token: string }> {
+    const nodeEnv = this.configService.get<string>('NODE_ENV');
+    const expectedSecret = this.configService.get<string>('E2E_AUTH_SECRET');
+    if (
+      nodeEnv !== 'development' ||
+      !expectedSecret ||
+      expectedSecret.length === 0
+    ) {
+      throw new NotFoundException();
+    }
+    if (!secret || secret !== expectedSecret) {
+      throw new NotFoundException();
+    }
+
+    const email = body?.email?.trim();
+    const userId = body?.userId?.trim();
+    if ((email ? 1 : 0) + (userId ? 1 : 0) !== 1) {
+      throw new BadRequestException('Provide exactly one of email or userId');
+    }
+
+    const user = email
+      ? await this.userService.findByEmail(email)
+      : await this.userService.findByID(userId!);
+
+    if (!user) {
+      throw new NotFoundException();
+    }
+
+    return this.authService.issueSessionTokensForUser(user);
+  }
+
   @Get('verify')
   @ApiOperation({ summary: 'Verify user token' })
   @ApiResponse({ status: 200, description: 'User token verified' })

apps/backend/src/auth/auth.service.spec.ts

@@ -185,6 +185,33 @@ describe('AuthService', () => {
     });
   });
 
+  describe('issueSessionTokensForUser', () => {
+    it('should delegate to createJwtPayload with user fields', async () => {
+      const user = {
+        _id: { toString: () => 'oid-1' },
+        email: '[email protected]',
+        username: 'user1',
+      } as unknown as UserDocument;
+
+      spyOn(authService as any, 'createJwtPayload').mockResolvedValueOnce({
+        access_token: 'a',
+        refresh_token: 'r',
+      });
+
+      const tokens = await authService.issueSessionTokensForUser(user);
+
+      expect(tokens).toEqual({
+        access_token: 'a',
+        refresh_token: 'r',
+      });
+      expect((authService as any).createJwtPayload).toHaveBeenCalledWith({
+        id: 'oid-1',
+        email: '[email protected]',
+        username: 'user1',
+      });
+    });
+  });
+
   describe('createJwtPayload', () => {
     it('should create access and refresh tokens', async () => {
       const payload = { id: 'user-id', username: 'testuser' };

apps/backend/src/auth/auth.service.ts

@@ -169,6 +169,17 @@ export class AuthService {
     return this.GenTokenRedirect(user, res);
   }
 
+  /** Mint access + refresh JWTs for an existing user (same payload shape as OAuth callbacks). */
+  public issueSessionTokensForUser(
+    user_registered: UserDocument,
+  ): Promise<Tokens> {
+    return this.createJwtPayload({
+      id: user_registered._id.toString(),
+      email: user_registered.email,
+      username: user_registered.username,
+    });
+  }
+
   public async createJwtPayload(payload: TokenPayload): Promise<Tokens> {
     const [accessToken, refreshToken] = await Promise.all([
       this.jwtService.signAsync<TokenPayload>(payload, {

packages/configs/src/e2e.ts

@@ -0,0 +1,9 @@
+/**
+ * Request header for `POST /v1/auth/e2e/session` (Nest, development only).
+ * Value must match backend env `E2E_AUTH_SECRET`.
+ */
+export const E2E_AUTH_HEADER = 'x-nbw-e2e-auth';
+
+/** First deterministic seed user (`deterministicSeedEmail(0)` in seed service). */
+export const DEFAULT_E2E_SEED_USER_EMAIL =
+  '[email protected]';

packages/configs/src/index.ts

@@ -1,4 +1,5 @@
 export * from './colors';
+export * from './e2e';
 export * from './seed';
 export * from './song';
 export * from './user';