Add Cypress e2e workspace, harden Docker/MinIO setup, and share deterministic seed config

CONTRIBUTING.md

@@ -21,22 +21,37 @@ You'll need the following installed on your machine:
 - [Docker](https://www.docker.com/)
 - [Docker Compose](https://docs.docker.com/compose/)
 
-We provide a `docker-compose-dev.yml` file that sets up:
+We provide [`docker-compose.yml`](docker-compose.yml) at the repository root. It defines:
 
-- A MongoDB instance
-- A local mail server (`maildev`)
-- An S3-compatible storage (`minio`)
-- A MinIO client
+- **MongoDB**
+- **MailDev** (SMTP + web UI for local email)
+- **MinIO** (S3-compatible storage)
+- A **MinIO client** job (profile `minio-init`) that creates buckets and CORS—**not** started by a plain `docker compose up`
 
-To start the services, run the following in the root directory:
+Start dependencies from the repo root in one of these ways:
+
+**Recommended** (waits for MongoDB and MinIO to be healthy, then runs bucket setup):
+
+```bash
+bun run docker:up
+```
+
+**Manual** (then create buckets once; uploads will fail with `NoSuchBucket` until you do):
+
+```bash
+docker compose up -d
+bun run docker:minio-init
+```
+
+To tear down volumes and start clean (still runs MinIO init after `up --wait`):
 
 ```bash
-docker-compose -f docker-compose.yml up -d
+bun run docker:reset:fresh
 ```
 
-> Remove the `-d` flag if you'd like to see container logs in your terminal.
+> Drop `-d` on `docker compose up -d` if you prefer logs attached to your terminal.
 
-You can find authentication details in the [`docker-compose.yml`](docker-compose.yml) file.
+Ports and default credentials (Mongo, MinIO, MailDev) are in [`docker-compose.yml`](docker-compose.yml). Match the MinIO bucket names and keys in your backend `.env` (see the example block under **Environment Variables** below).
 
 ---
 

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=
 
@@ -23,6 +27,15 @@ APP_DOMAIN=
 
 RECAPTCHA_KEY=
 
+# MinIO from repo docker-compose: after `docker compose up -d` (or `bun run docker:up`),
+# create buckets once with `bun run docker:minio-init` from the monorepo root (see root package.json).
+# Example local values (match docker-compose mc bucket names):
+# S3_ENDPOINT=http://localhost:9000
+# S3_BUCKET_SONGS=noteblockworld-songs
+# S3_BUCKET_THUMBS=noteblockworld-thumbs
+# S3_KEY=minioadmin
+# S3_SECRET=minioadmin
+# S3_REGION=us-east-1
 S3_ENDPOINT=
 S3_BUCKET_SONGS=
 S3_BUCKET_THUMBS=

apps/backend/package.json

@@ -27,6 +27,7 @@
     "@encode42/nbs.js": "^5.0.2",
     "@nbw/config": "workspace:*",
     "@nbw/database": "workspace:*",
+    "@nbw/validation": "workspace:*",
     "@nbw/song": "workspace:*",
     "@nbw/sounds": "workspace:*",
     "@nbw/thumbnail": "workspace:*",
@@ -44,10 +45,10 @@
     "axios": "^1.13.2",
     "bcryptjs": "^3.0.3",
     "class-transformer": "^0.5.1",
-    "class-validator": "^0.14.3",
     "esm": "^3.2.25",
     "express": "^5.2.1",
     "mongoose": "^9.0.1",
+    "nestjs-zod": "^5.0.1",
     "multer": "2.1.1",
     "nanoid": "^5.1.6",
     "passport": "^0.7.0",

apps/backend/scripts/build.ts

@@ -51,9 +51,6 @@ const build = async () => {
   await Bun.$`rm -rf dist`;
 
   const optionalRequirePackages = [
-    'class-transformer',
-    'class-transformer/storage',
-    'class-validator',
     '@nestjs/microservices',
     '@nestjs/websockets',
     '@fastify/static',
@@ -76,8 +73,11 @@ const build = async () => {
       }),
       '@nbw/config',
       '@nbw/database',
+      '@nbw/validation',
       '@nbw/song',
       '@nbw/sounds',
+      // @nestjs/swagger → @nestjs/mapped-types requires class-transformer metadata storage; bundler mis-resolves subpaths
+      'class-transformer',
     ],
     splitting: true,
   });

apps/backend/src/app.module.ts

@@ -1,13 +1,14 @@
 import { Logger, Module } from '@nestjs/common';
 import { ConfigModule, ConfigService } from '@nestjs/config';
-import { APP_GUARD } from '@nestjs/core';
+import { APP_GUARD, APP_PIPE } from '@nestjs/core';
 import { MongooseModule, MongooseModuleFactoryOptions } from '@nestjs/mongoose';
 import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';
+import { ZodValidationPipe } from 'nestjs-zod';
 import { MailerModule } from '@nestjs-modules/mailer';
 import { HandlebarsAdapter } from '@nestjs-modules/mailer/dist/adapters/handlebars.adapter';
 
 import { AuthModule } from './auth/auth.module';
-import { validate } from './config/EnvironmentVariables';
+import { validateEnv } from '@nbw/validation';
 import { EmailLoginModule } from './email-login/email-login.module';
 import { FileModule } from './file/file.module';
 import { ParseTokenPipe } from './lib/parseToken';
@@ -21,7 +22,7 @@ import { UserModule } from './user/user.module';
     ConfigModule.forRoot({
       isGlobal: true,
       envFilePath: ['.env.test', '.env.development', '.env.production'],
-      validate,
+      validate: validateEnv,
     }),
     //DatabaseModule,
     MongooseModule.forRootAsync({
@@ -82,6 +83,10 @@ import { UserModule } from './user/user.module';
   controllers: [],
   providers: [
     ParseTokenPipe,
+    {
+      provide: APP_PIPE,
+      useClass: ZodValidationPipe,
+    },
     {
       provide: APP_GUARD,
       useClass: ThrottlerGuard,

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: 'a@b.c' }),
+      ).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: 'a@b.c' }),
+      ).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: 'a@b.c' }),
+      ).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: 'a@b.c', 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: 'e@e.com', username: 'u' };
+      mockUserService.findByEmail.mockResolvedValueOnce(user);
+      mockAuthService.issueSessionTokensForUser.mockResolvedValueOnce({
+        access_token: 'a',
+        refresh_token: 'r',
+      });
+
+      const out = await controller.e2eSession('s', { email: 'e@e.com' });
+
+      expect(out).toEqual({ access_token: 'a', refresh_token: 'r' });
+      expect(mockUserService.findByEmail).toHaveBeenCalledWith('e@e.com');
+      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: 'e@e.com', 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: 'missing@x.com' }),
+      ).rejects.toBeInstanceOf(NotFoundException);
+    });
+  });
 });