Merge pull request #369 from red-kite-solutions/feature/openapi-specs

Feature/openapi specs

Author: lm-sec

devspace.yaml

@@ -362,6 +362,8 @@ deployments:
         repo: https://charts.bitnami.com/bitnami
         version: "13.9.1"
       values:
+        image:
+          repository: bitnamilegacy/mongodb
         architecture: replicaset
         nodeSelector: $(echo ${MONGO_K8S_NODE_SELECTOR})
         replicaCount: ${MONGO_REPLICA_SET_COUNT}
@@ -384,6 +386,10 @@ deployments:
           caKey: ${MONGO_CA_KEY}
           mTls:
             enabled: true
+          image:
+            registry: docker.io
+            repository: bitnamilegacy/nginx
+
         service:
           ports:
             mongodb: 27017
@@ -443,6 +449,8 @@ deployments:
         - --timeout
         - 1200s
       values:
+        image:
+          repository: bitnamilegacy/kafka
         controller:
           nodeSelector: $(echo ${KAFKA_K8S_NODE_SELECTOR})
           persistence:
@@ -688,6 +696,9 @@ dev:
     labelSelector:
       app.kubernetes.io/instance: kafka
 
+  # For devspace sync no space left on device error, if there is still space left
+  # on your device, increase Linux inotify count
+  # https://dev.to/rubiin/ubuntu-increase-inotify-watcher-file-watch-limit-kf4
   jobs-manager:
     labelSelector:
       app.kubernetes.io/component: jobs-manager

docs/docs/development/api.md

@@ -1,22 +1,31 @@
 # API
 
-Every frontend-available data and more is accessible through the API. Simply create your API key in your profile, and then add it as a header when querying the API.
+Every frontend-available data and more is accessible through the API. Simply create your API key in your profile, and then add it as a
+header when querying the API.
 
-The API is available at `/api/`. You can do an unauthenticated request at `/api/ping` that replies a simple string, and an authenticated request at `/api/` that gets the version.
+The API is available at `/api/`. You can do an unauthenticated request at `/api/ping` that replies a simple string, and an authenticated
+request at `/api/` that gets the version.
 
 Unauthenticated `GET` request to `/api/ping`:
 
 ```bash
 curl https://your-red-kite-url/api/ping
 ```
 
-# API Key
+## API Key
 
-Generate your API key in your profile page, giving it a meaningful name and an expiration date. Then, use it as a header in your following requests.
+Generate your API key in your profile page, giving it a meaningful name and an expiration date. Then, use it as a header in your following
+requests.
 
 Authenticated `GET` request to `/api/`:
 
 ```bash
 export MY_KEY="my key value"
 curl -H "x-api-key: $MY_KEY" https://your-red-kite-url/api/
 ```
+
+## Open API Documentation
+
+Your OpenAPI documentation is available in json format and through the swagger UI interface.
+
+The swagger UI is available at `/api/docs/`, while the JSON format is available at `/api/docs-json`.

packages/backend/jobs-manager/service/nest-cli.json

@@ -8,6 +8,16 @@
         "include": "**/*.mjml",
         "outDir": "dist/src"
       }
+    ],
+    "plugins": [
+      {
+        "name": "@nestjs/swagger",
+        "options": {
+          "classValidatorShim": true,
+          "introspectComments": true,
+          "skipAutoHttpCode": true
+        }
+      }
     ]
   }
 }

packages/backend/jobs-manager/service/package.json

@@ -24,18 +24,18 @@
     "test:cov": "jest --coverage"
   },
   "dependencies": {
-    "@nestjs/common": "^9.2.1",
-    "@nestjs/core": "^9.2.1",
-    "@nestjs/cqrs": "^9.0.1",
-    "@nestjs/jwt": "^10.0.1",
-    "@nestjs/microservices": "^9.2.1",
-    "@nestjs/mongoose": "^9.2.2",
-    "@nestjs/platform-express": "^9.2.1",
-    "@nestjs/platform-socket.io": "^9.2.1",
-    "@nestjs/schedule": "^2.1.0",
-    "@nestjs/swagger": "^8.1.0",
-    "@nestjs/websockets": "^9.2.1",
-    "@typegoose/typegoose": "^10.3.3",
+    "@nestjs/common": "^11.1.1",
+    "@nestjs/core": "^11.1.1",
+    "@nestjs/cqrs": "^11.0.3",
+    "@nestjs/jwt": "^11.0.0",
+    "@nestjs/microservices": "^11.1.1",
+    "@nestjs/mongoose": "^11.0.3",
+    "@nestjs/platform-express": "^11.1.1",
+    "@nestjs/platform-socket.io": "^11.1.1",
+    "@nestjs/schedule": "^6.0.0",
+    "@nestjs/swagger": "^11.2.0",
+    "@nestjs/websockets": "^11.1.1",
+    "@typegoose/typegoose": "^12.16.0",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.14.0",
     "cron-validator": "^1.3.1",
@@ -62,10 +62,10 @@
     "webpack": "^5.90.3"
   },
   "devDependencies": {
-    "@nestjs/cli": "^9.1.9",
-    "@nestjs/passport": "^9.0.0",
-    "@nestjs/schematics": "^9.0.4",
-    "@nestjs/testing": "^9.2.1",
+    "@nestjs/cli": "^11.0.7",
+    "@nestjs/passport": "^11.0.5",
+    "@nestjs/schematics": "^11.0.5",
+    "@nestjs/testing": "^11.1.1",
     "@types/express": "^4.17.16",
     "@types/jest": "^29.5.1",
     "@types/mjml": "^4",

packages/backend/jobs-manager/service/src/main.ts

@@ -1,12 +1,20 @@
 import { NestApplicationOptions, ValidationPipe } from '@nestjs/common';
 import { NestFactory } from '@nestjs/core';
 import { ExpressAdapter } from '@nestjs/platform-express';
+import {
+  DocumentBuilder,
+  SwaggerDocumentOptions,
+  SwaggerModule,
+} from '@nestjs/swagger';
 import { useContainer } from 'class-validator';
 import { json } from 'express';
 import { readFileSync } from 'node:fs';
 import { KeepAliveStrategy } from './keep-alive-strategy';
 import { isConsumerMode } from './modules/app.constants';
 import { AppModule } from './modules/app.module';
+import { DataSource } from './modules/database/data-source/data-source.model';
+import { JobParameter } from './modules/database/subscriptions/subscriptions.type';
+import { mapSecurityScopesToDescription } from './utils/swagger.utils';
 
 async function bootstrap() {
   const adapter = new ExpressAdapter();
@@ -37,6 +45,7 @@ async function bootstrap() {
     await workerApp.listen();
   } else {
     const app = await NestFactory.create(AppModule, adapter, options);
+
     app.enableCors({
       origin: process.env.RK_URL,
     });
@@ -48,6 +57,43 @@ async function bootstrap() {
         forbidNonWhitelisted: true,
       }),
     );
+
+    // OpenAPI Setup
+    const config = new DocumentBuilder()
+      .setTitle('Red Kite API')
+      .setDescription('The Red Kite external attack surface management API.')
+      .addApiKey(
+        {
+          type: 'apiKey',
+          name: 'x-api-key',
+          in: 'header',
+        },
+        'apiKey',
+      )
+      .addBearerAuth()
+      .setVersion(process.env.RK_VERSION)
+      .build();
+
+    const documentFactory = () => {
+      const options: SwaggerDocumentOptions = {
+        deepScanRoutes: true,
+        extraModels: [JobParameter, DataSource],
+      };
+      const doc = SwaggerModule.createDocument(app, config, options);
+
+      // Setting up ObjectIds in the OpenAPI documentation to string
+      doc.components = doc.components || {};
+      doc.components.schemas = doc.components.schemas || {};
+      doc.components.schemas.ObjectId = {
+        type: 'string',
+        example: '507f1f77bcf86cd799439011',
+        description: 'MongoDB ObjectId represented as string',
+      };
+
+      return mapSecurityScopesToDescription(doc);
+    };
+    SwaggerModule.setup('docs', app, documentFactory);
+
     useContainer(app.select(AppModule), { fallbackOnErrors: true });
     await app.listen(3000);
   }

packages/backend/jobs-manager/service/src/modules/app.controller.ts

@@ -1,7 +1,7 @@
 import { Controller, Get, UseGuards } from '@nestjs/common';
 import { AuthGuard } from '@nestjs/passport';
+import { ApiDefaultResponse } from '@nestjs/swagger';
 import { AppService } from './app.service';
-import { Role } from './auth/constants';
 import { Scopes } from './auth/decorators/scopes.decorator';
 import { ScopesGuard } from './auth/guards/scope.guard';
 import { ApiKeyStrategy } from './auth/strategies/api-key.strategy';
@@ -11,15 +11,29 @@ import { JwtStrategy } from './auth/strategies/jwt.strategy';
 export class AppController {
   constructor(private readonly appService: AppService) {}
 
+  /**
+   * Get the application version
+   *
+   * @remarks
+   * Get the application version from the `RK_VERSION` environment variable.
+   */
   @Scopes('manage:health:version')
   @UseGuards(AuthGuard([JwtStrategy.name, ApiKeyStrategy.name]), ScopesGuard)
   @Get()
   getVersion(): string {
     return this.appService.getVersion();
   }
 
+  /**
+   * Application health check
+   *
+   * @remarks
+   * Know if the application is running. This call is unauthenticated.
+   *
+   */
+  @ApiDefaultResponse({ example: 'pong' })
   @Get('ping')
-  ping(): string {
+  ping() {
     return 'pong';
   }
 }

packages/backend/jobs-manager/service/src/modules/auth/auth.controller.ts

@@ -24,18 +24,36 @@ interface RequestWithUser extends Request {
 export class AuthController {
   constructor(private readonly authService: AuthService) {}
 
+  /**
+   * Log in with credentials and get an access token.
+   *
+   * @remarks
+   * Log in to the API with your local credentials. After logging in, an access token will be issued.
+   */
   @UseGuards(LocalAuthGuard)
   @Post('login')
   async login(@Request() req) {
     return await this.loginCore(req);
   }
 
+  /**
+   * Log in with unique link.
+   *
+   * @remarks
+   * Log in to the API with your unique link. Used to reset your password.
+   */
   @UseGuards(MagicLinkAuthGuard)
   @Post('login-magic-link')
   async loginMagicLink(@Request() req: RequestWithUser) {
     return await this.loginCore(req);
   }
 
+  /**
+   * Refresh your access token with your refresh token.
+   *
+   * @remarks
+   * Use this call to get a new access token. This
+   */
   @UseGuards(JwtRefreshGuard)
   @Put('refresh')
   async refresh(@Request() req: RequestWithUser) {
@@ -44,6 +62,12 @@ export class AuthController {
     return { access_token: accessToken };
   }
 
+  /**
+   * Logout the current user.
+   *
+   * @remarks
+   * Logout the current user, deleting their refresh token.
+   */
   @UseGuards(JwtAuthGuard)
   @Delete('logout')
   async logOut(@Request() request: RequestWithUser, @Body() dto: LogoutDto) {
@@ -58,8 +82,10 @@ export class AuthController {
   }
 
   /**
-   * This function is left without authorizations on purpose
-   * It is used to anonymously know if the platform was properly initialized
+   * Anonymously know if the platform was properly initialized.
+   *
+   * @remarks
+   * Anonymous API call to check if the local authentication was setup.
    */
   @Get('setup')
   async getIsSetup(): Promise<any> {

packages/backend/jobs-manager/service/src/modules/auth/auth.dto.ts

@@ -4,3 +4,8 @@ export class LogoutDto {
   @IsOptional()
   refresh_token: string;
 }
+
+export class LocalAuthDto {
+  email: string;
+  password: string;
+}

packages/backend/jobs-manager/service/src/modules/auth/decorators/scopes.decorator.ts

@@ -1,4 +1,5 @@
-import { SetMetadata } from '@nestjs/common';
+import { applyDecorators, SetMetadata } from '@nestjs/common';
+import { ApiSecurity } from '@nestjs/swagger';
 import { ScopeActivationContext } from '../guards/scope-guard.utils';
 import { ApiScope, ExtendedScope, ScopeOptions } from '../scopes.constants';
 
@@ -20,5 +21,9 @@ export const Scopes = (
     scopeOptions: options,
   };
 
-  return SetMetadata(SCOPE_INFO_KEY, scopeInfo);
+  return applyDecorators(
+    ApiSecurity('apiKey', scopeInfo.scopes),
+    ApiSecurity('bearer', scopeInfo.scopes),
+    SetMetadata(SCOPE_INFO_KEY, scopeInfo),
+  );
 };

packages/backend/jobs-manager/service/src/modules/auth/strategies/api-key.strategy.ts

@@ -1,4 +1,4 @@
-import { Injectable } from '@nestjs/common';
+import { Injectable, UnauthorizedException } from '@nestjs/common';
 import { PassportStrategy } from '@nestjs/passport';
 import { HeaderAPIKeyStrategy } from 'passport-headerapikey';
 import { ApiKeyDocument } from '../../database/api-key/api-key.model';
@@ -11,23 +11,21 @@ export class ApiKeyStrategy extends PassportStrategy(
   'ApiKeyStrategy',
 ) {
   constructor(private authService: AuthService) {
-    super(
-      { header: 'x-api-key', prefix: '' },
-      true,
-      async (apikey, done, req) => {
-        const apiKeyDocument: ApiKeyDocument =
-          await authService.findValidApiKey(apikey);
+    super({ header: 'x-api-key', prefix: '' }, false);
+  }
+
+  async validate(apikey: string) {
+    const apiKeyDocument: ApiKeyDocument =
+      await this.authService.findValidApiKey(apikey);
 
-        if (!apiKeyDocument) return done(null, false);
+    if (!apiKeyDocument) throw new UnauthorizedException();
 
-        const user: UserAuthContext = {
-          id: apiKeyDocument.userId.toString(),
-          apiKeyId: apiKeyDocument._id.toString(),
-          scopes: apiKeyDocument.scopes,
-        };
+    const user: UserAuthContext = {
+      id: apiKeyDocument.userId.toString(),
+      apiKeyId: apiKeyDocument._id.toString(),
+      scopes: apiKeyDocument.scopes,
+    };
 
-        return done(null, user);
-      },
-    );
+    return user;
   }
 }