@lenne.tech/nest-server 10.8.4 → 10.8.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "10.8.4",
+  "version": "10.8.6",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -75,6 +75,7 @@
     "@nestjs/passport": "10.0.3",
     "@nestjs/platform-express": "10.4.15",
     "@nestjs/schedule": "4.1.2",
+    "@nestjs/swagger": "8.1.1",
     "@nestjs/terminus": "10.3.0",
     "apollo-server-core": "3.13.0",
     "apollo-server-express": "3.13.0",

package/src/core/modules/auth/core-auth.controller.ts

@@ -1,5 +1,5 @@
-import { Body, Controller, Get, Param, ParseBoolPipe, Post, Res, UseGuards } from '@nestjs/common';
-import { Args } from '@nestjs/graphql';
+import { Body, Controller, Get, ParseBoolPipe, Post, Query, Res, UseGuards } from '@nestjs/common';
+import { ApiBody, ApiOperation, ApiResponse } from '@nestjs/swagger';
 import { Response as ResponseType } from 'express';
 
 import { CurrentUser } from '../../common/decorators/current-user.decorator';
@@ -29,14 +29,15 @@ export class CoreAuthController {
   /**
    * Logout user (from specific device)
    */
+  @ApiOperation({ description: 'Logs a user out from a specific device' })
+  @Get('logout')
   @Roles(RoleEnum.S_EVERYONE)
   @UseGuards(AuthGuard(AuthGuardStrategy.JWT))
-  @Get()
   async logout(
     @CurrentUser() currentUser: ICoreAuthUser,
     @Tokens('token') token: string,
-    @Res() res: ResponseType,
-    @Param('allDevices', ParseBoolPipe) allDevices?: boolean,
+    @Res({ passthrough: true }) res: ResponseType,
+    @Query('allDevices', ParseBoolPipe) allDevices?: boolean,
   ): Promise<boolean> {
     const result = await this.authService.logout(token, { allDevices, currentUser });
     return this.processCookies(res, result);
@@ -45,13 +46,14 @@ export class CoreAuthController {
   /**
    * Refresh token (for specific device)
    */
+  @ApiResponse({ type: CoreAuthModel })
+  @Get('refresh-token')
   @Roles(RoleEnum.S_EVERYONE)
   @UseGuards(AuthGuard(AuthGuardStrategy.JWT_REFRESH))
-  @Get()
   async refreshToken(
     @CurrentUser() user: ICoreAuthUser,
     @Tokens('refreshToken') refreshToken: string,
-    @Res() res: ResponseType,
+    @Res({ passthrough: true }) res: ResponseType,
   ): Promise<CoreAuthModel> {
     const result = await this.authService.refreshTokens(user, refreshToken);
     return this.processCookies(res, result);
@@ -60,9 +62,10 @@ export class CoreAuthController {
   /**
    * Sign in user via email and password (on specific device)
    */
+  @ApiOperation({ description: 'Sign in via email and password' })
+  @Post('signin')
   @Roles(RoleEnum.S_EVERYONE)
-  @Post()
-  async signIn(@Res() res: ResponseType, @Body('input') input: CoreAuthSignInInput): Promise<CoreAuthModel> {
+  async signIn(@Res({ passthrough: true }) res: ResponseType, @Body() input: CoreAuthSignInInput): Promise<CoreAuthModel> {
     const result = await this.authService.signIn(input);
     return this.processCookies(res, result);
   }
@@ -70,9 +73,11 @@ export class CoreAuthController {
   /**
    * Register a new user account (on specific device)
    */
+  @ApiBody({ type: CoreAuthSignUpInput })
+  @ApiOperation({ description: 'Sign up via email and password' })
+  @Post('signup')
   @Roles(RoleEnum.S_EVERYONE)
-  @Post()
-  async signUp(@Res() res: ResponseType, @Args('input') input: CoreAuthSignUpInput): Promise<CoreAuthModel> {
+  async signUp(@Res() res: ResponseType, @Body() input: CoreAuthSignUpInput): Promise<CoreAuthModel> {
     const result = await this.authService.signUp(input);
     return this.processCookies(res, result);
   }

package/src/core/modules/auth/core-auth.model.ts

@@ -1,4 +1,5 @@
 import { Field, ObjectType } from '@nestjs/graphql';
+import { ApiProperty } from '@nestjs/swagger';
 
 import { Restricted } from '../../common/decorators/restricted.decorator';
 import { RoleEnum } from '../../common/enums/role.enum';
@@ -16,24 +17,37 @@ export class CoreAuthModel extends CoreModel {
   // ===================================================================================================================
 
   /**
-   * JavaScript Web Token (JWT)
+   * JSON Web Token(JWT)
    */
+  @ApiProperty({
+    description: 'JSON Web Token(JWT) used for auth',
+    example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
+  })
+  @Field({ description: 'JSON Web Token(JWT)', nullable: true })
   @Restricted(RoleEnum.S_EVERYONE)
-  @Field({ description: 'JavaScript Web Token (JWT)', nullable: true })
   token?: string = undefined;
 
   /**
    * Refresh token
    */
-  @Restricted(RoleEnum.S_EVERYONE)
+  @ApiProperty({
+    description: 'Refresh JSON Web Token(JWT) used for auth',
+    example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
+  })
   @Field({ description: 'Refresh token', nullable: true })
+  @Restricted(RoleEnum.S_EVERYONE)
   refreshToken?: string = undefined;
 
   /**
    * Current user
    */
-  @Restricted(RoleEnum.S_EVERYONE)
+  @ApiProperty({
+    description: 'User who signed in',
+    required: true,
+    type: () => CoreUserModel,
+  })
   @Field({ description: 'Current user' })
+  @Restricted(RoleEnum.S_EVERYONE)
   user: CoreUserModel = undefined;
 
   // ===================================================================================================================

package/src/core/modules/auth/inputs/core-auth-sign-in.input.ts

@@ -1,4 +1,6 @@
 import { Field, InputType } from '@nestjs/graphql';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsEmail, IsNotEmpty, IsOptional, IsString } from 'class-validator';
 
 import { Restricted } from '../../../common/decorators/restricted.decorator';
 import { RoleEnum } from '../../../common/enums/role.enum';
@@ -14,19 +16,31 @@ export class CoreAuthSignInInput extends CoreInput {
   // Properties
   // ===================================================================================================================
 
-  @Restricted(RoleEnum.S_EVERYONE)
+  @ApiPropertyOptional({ description: 'Device ID (is created automatically if it is not set)' })
   @Field({ description: 'Device ID (is created automatically if it is not set)', nullable: true })
+  @IsOptional()
+  @IsString()
+  @Restricted(RoleEnum.S_EVERYONE)
   deviceId?: string = undefined;
 
-  @Restricted(RoleEnum.S_EVERYONE)
+  @ApiPropertyOptional({ description: 'Device description' })
   @Field({ description: 'Device description', nullable: true })
+  @IsOptional()
+  @IsString()
+  @Restricted(RoleEnum.S_EVERYONE)
   deviceDescription?: string = undefined;
 
-  @Restricted(RoleEnum.S_EVERYONE)
+  @ApiProperty()
   @Field({ description: 'Email', nullable: false })
+  @IsEmail()
+  @IsNotEmpty()
+  @Restricted(RoleEnum.S_EVERYONE)
   email: string = undefined;
 
-  @Restricted(RoleEnum.S_EVERYONE)
+  @ApiProperty()
   @Field({ description: 'Password', nullable: false })
+  @IsNotEmpty()
+  @IsString()
+  @Restricted(RoleEnum.S_EVERYONE)
   password: string = undefined;
 }

package/src/core/modules/user/core-user.model.ts

@@ -1,5 +1,6 @@
 import { Field, ObjectType } from '@nestjs/graphql';
 import { Schema as MongooseSchema, Prop, raw } from '@nestjs/mongoose';
+import { ApiProperty } from '@nestjs/swagger';
 import { IsOptional } from 'class-validator';
 import { Document } from 'mongoose';
 
@@ -24,60 +25,67 @@ export abstract class CoreUserModel extends CorePersistenceModel {
   /**
    * E-Mail address of the user
    */
-  @Restricted(RoleEnum.S_EVERYONE)
+  @ApiProperty()
   @Field({ description: 'Email of the user', nullable: true })
   @Prop({ index: true, lowercase: true, trim: true })
+  @Restricted(RoleEnum.S_EVERYONE)
   email: string = undefined;
 
   /**
    * First name of the user
    */
-  @Restricted(RoleEnum.S_EVERYONE)
+  @ApiProperty()
   @Field({ description: 'First name of the user', nullable: true })
   @IsOptional()
   @Prop()
+  @Restricted(RoleEnum.S_EVERYONE)
   firstName: string = undefined;
 
   /**
    * Last name of the user
    */
-  @Restricted(RoleEnum.S_EVERYONE)
+  @ApiProperty()
   @Field({ description: 'Last name of the user', nullable: true })
   @IsOptional()
   @Prop()
+  @Restricted(RoleEnum.S_EVERYONE)
   lastName: string = undefined;
 
   /**
    * Password of the user
    */
-  @Restricted(RoleEnum.S_NO_ONE)
+  @ApiProperty()
   @Prop()
+  @Restricted(RoleEnum.S_NO_ONE)
   password: string = undefined;
 
   /**
    * Roles of the user
    */
-  @Restricted(RoleEnum.S_EVERYONE)
+  @ApiProperty()
   @Field(type => [String], { description: 'Roles of the user', nullable: true })
   @IsOptional()
   @Prop([String])
+  @Restricted(RoleEnum.S_EVERYONE)
   roles: string[] = undefined;
 
   /**
    * Username of the user
    */
-  @Restricted(RoleEnum.S_EVERYONE)
+  @ApiProperty()
   @Field({ description: 'Username of the user', nullable: true })
   @IsOptional()
   @Prop()
+  @Restricted(RoleEnum.S_EVERYONE)
   username: string = undefined;
 
   /**
    * Password reset token of the user
    */
-  @Restricted(RoleEnum.S_NO_ONE)
+  @ApiProperty()
   @IsOptional()
   @Prop()
+  @Restricted(RoleEnum.S_NO_ONE)
   passwordResetToken: string = undefined;
 
   /**
@@ -85,42 +93,95 @@ export abstract class CoreUserModel extends CorePersistenceModel {
    * key: Token
    * value: TokenData
    */
-  @Restricted(RoleEnum.S_NO_ONE)
+  @ApiProperty({ isArray: true })
   @IsOptional()
   @Prop(raw({}))
+  @Restricted(RoleEnum.S_NO_ONE)
+  @ApiProperty({
+      additionalProperties: {
+      properties: {
+        deviceDescription: { description: 'Description of the device from which the token was generated', nullable: true, type: 'string' },
+        deviceId: { description: 'ID of the device from which the token was generated', nullable: true, type: 'string' },
+        tokenId: { description: 'Token ID to make sure that there is only one RefreshToken for each device', nullable: false, type: 'string' },
+      },
+      type: 'object',
+    },
+    description: 'Refresh tokens for devices (key: Token, value: TokenData)',
+    example: {
+        '49b5c7d6-94ae-4efe-b377-9b50d1a9c2cb': {
+          deviceDescription: null,
+          deviceId: '49b5c7d6-94ae-4efe-b377-9b50d1a9c2cb',
+          tokenId: '50937407-4282-480e-8679-14ecc113f9c7',
+        },
+        'e9e60a3e-2004-479f-8e79-13a0d1981d76': {
+          deviceDescription: null,
+          deviceId: 'e9e60a3e-2004-479f-8e79-13a0d1981d76',
+          tokenId: '0604aa59-4fc8-4848-9fe7-c12d9cdf6ec0',
+        },
+      },
+    type: 'object',
+  })
   refreshTokens: Record<string, CoreTokenData> = undefined;
 
   /**
    * Temporary token for parallel requests during the token refresh process
    * See sameTokenIdPeriod in configuration
    */
-  @Restricted(RoleEnum.S_NO_ONE)
+  @ApiProperty()
   @IsOptional()
   @Prop(raw({}))
+  @Restricted(RoleEnum.S_NO_ONE)
+  @ApiProperty({
+      additionalProperties: {
+      properties: {
+        createdAt: { description: 'Token Created At', example: 1740037703939, format: 'int64', nullable: true, type: 'number' },
+        deviceId: { description: 'ID of the device from which the token was generated', nullable: true, type: 'string' },
+        tokenId: { description: 'Token ID to make sure that there is only one RefreshToken for each device', nullable: false, type: 'string' },
+      },
+      type: 'object',
+    },
+    description: 'Temporary token for parallel requests during the token refresh process',
+    example: { // 👈 Add explicit example keys
+        '49b5c7d6-94ae-4efe-b377-9b50d1a9c2cb': {
+          createdAt: 1740037703939,
+          deviceId: '49b5c7d6-94ae-4efe-b377-9b50d1a9c2cb',
+          tokenId: '50937407-4282-480e-8679-14ecc113f9c7',
+        },
+        'f83ae5f6-90bf-4b4e-b318-651e0eaa67ae': {
+          createdAt: 1740037703940,
+          deviceId: 'f83ae5f6-90bf-4b4e-b318-651e0eaa67ae',
+          tokenId: '4f0dc3c5-e74e-41f4-9bd9-642869462c1e',
+        },
+      },
+    type: 'object',
+  })
   tempTokens: Record<string, { createdAt: number; deviceId: string; tokenId: string }> = undefined;
 
   /**
    * Verification token of the user
    */
-  @Restricted(RoleEnum.S_NO_ONE)
+  @ApiProperty()
   @IsOptional()
   @Prop()
+  @Restricted(RoleEnum.S_NO_ONE)
   verificationToken: string = undefined;
 
   /**
    * Verification of the user
    */
-  @Restricted(RoleEnum.S_EVERYONE)
+  @ApiProperty()
   @Field(type => Boolean, { description: 'Verification state of the user', nullable: true })
   @Prop({ type: Boolean })
+  @Restricted(RoleEnum.S_EVERYONE)
   verified: boolean = undefined;
 
   /**
    * Verification date
    */
-  @Restricted(RoleEnum.S_EVERYONE)
+  @ApiProperty()
   @Field({ description: 'Verified date', nullable: true })
   @Prop()
+  @Restricted(RoleEnum.S_EVERYONE)
   verifiedAt: Date = undefined;
 
   // ===================================================================================================================

package/src/server/modules/auth/auth.module.ts

@@ -20,7 +20,8 @@ export class AuthModule {
    */
   static forRoot(options: JwtModuleOptions): DynamicModule {
     return {
-      exports: [AuthController, AuthResolver, CoreAuthModule],
+      controllers: [AuthController],
+      exports: [AuthController, AuthResolver, CoreAuthModule, AuthService],
       imports: [
         CoreAuthModule.forRoot(UserModule, UserService, {
           ...options,

package/src/server/server.module.ts

@@ -8,6 +8,7 @@ import { DateScalar } from '../core/common/scalars/date.scalar';
 import { JSON } from '../core/common/scalars/json.scalar';
 import { CoreAuthService } from '../core/modules/auth/services/core-auth.service';
 import { CronJobs } from './common/services/cron-jobs.service';
+import { AuthController } from './modules/auth/auth.controller';
 import { AuthModule } from './modules/auth/auth.module';
 import { FileModule } from './modules/file/file.module';
 import { ServerController } from './server.controller';
@@ -20,7 +21,7 @@ import { ServerController } from './server.controller';
  */
 @Module({
   // Include REST controllers
-  controllers: [ServerController],
+  controllers: [ServerController, AuthController],
 
   // Export modules for reuse in other modules
   exports: [CoreModule, AuthModule, FileModule],