GUI Attestation & Comment Engine — supersedes #8278

Dockerfile

@@ -31,6 +31,7 @@ RUN yarn build
 
 FROM $BASE_CONTAINER AS app
 
+# Default backend port — override with HEIMDALL_BACKEND_PORT env var
 EXPOSE 3000
 
 ARG NODE_ENV=production

README.md

@@ -457,8 +457,10 @@ If you would like to change Heimdall to your needs, you can use Heimdall's 'Deve
 
    You can also manually edit the `apps/backend/.env` file in a text editor and set additional optional configuration values. For more info on configuration values see [Enviroment Variables Configuration](https://github.com/mitre/heimdall2/wiki/Environment-Variables-Configuration).
 
+   **Port configuration:** The backend listen port is set via `HEIMDALL_BACKEND_PORT` (defaults to 3000). The frontend dev server port is set via `HEIMDALL_FRONTEND_PORT` in `apps/frontend/.env.development.local` (defaults to 8080). The legacy `PORT` env var is deprecated and will be removed in the next minor release — use `HEIMDALL_BACKEND_PORT` instead.
+
 > [!NOTE]
-> The .env file in the root repository is for the Docker deployment of the Heimdall application. Running a local build will use the .env file in the `apps/backend` directory for the database configurations.
+> The .env file in the root repository is for the Docker deployment of the Heimdall application. Running a local build will use the .env file in the `apps/backend` directory for the database configurations. The frontend dev server reads its own env from `apps/frontend/.env.development.local`.
 
 6. Build the project:
 

apps/backend/.env-example

@@ -8,10 +8,12 @@
 CLASSIFICATION_BANNER_TEXT=<If a sensitivity classification banner should be shown to users, for example FOUO (if nothing is provided, no banner is shown)>
 CLASSIFICATION_BANNER_TEXT_COLOR=<The color of the text on the sensitivity classification banner, if enabled (defaults to white)>
 CLASSIFICATION_BANNER_COLOR=<The color of the sensitivity classification banner, if enabled (defaults to red)>
+HEIMDALL_FRONTEND_PORT=<Dev server listen port (defaults to 8080). Set in apps/frontend/.env.development.local for local development.>
+HEIMDALL_SERVER_MODE=<Enable API proxy to backend in dev (defaults to false). Set in apps/frontend/.env.development.local.>
 
 ## Backend
 NODE_ENV=<development, production, or test (no default, must be set)>
-PORT=<Port that the app starts up on (if nothing is provided, defaults to 3000)>
+HEIMDALL_BACKEND_PORT=<Port that the backend listens on (defaults to 3000). Falls back to PORT for backward compatibility — PORT is DEPRECATED and will be removed in the next minor release.>
 ADMIN_EMAIL=<email for default admin user (if nothing is provided, defaults to admin@heimdall.local)>
 ADMIN_USES_EXTERNAL_AUTH=<if the default admin user uses alternative/external authentication (if nothing is provided, defaults to false)
 ADMIN_PASSWORD=<Password for admin user (if nothing is provided, defaults to a randomly generated password that will only be shown on initial setup)>

apps/backend/config/app_config.ts

@@ -1,37 +1,39 @@
+import {Logger} from '@nestjs/common';
 import * as dotenv from 'dotenv';
 import * as fs from 'fs';
 
 export default class AppConfig {
+  private static instance: AppConfig;
+  private readonly logger = new Logger(AppConfig.name);
   private envConfig: {[key: string]: string | undefined};
 
-  constructor() {
-    console.log('Attempting to read configuration file `.env`!');
+  private constructor() {
     try {
       this.envConfig = dotenv.parse(fs.readFileSync('.env'));
-      console.log('Read config!');
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
         this.envConfig = {};
-        // File probably does not exist
-        console.log('Unable to read configuration file `.env`!');
-        console.log('Falling back to environment or undefined values!');
+        this.logger.warn('.env not found, using environment variables only');
       } else {
         throw error;
       }
     }
-    if (this.parseDatabaseUrl()) {
-      console.log(
-        'DATABASE_URL parsed into smaller components (i.e. DATABASE_USER)'
-      );
+    this.parseDatabaseUrl();
+  }
+
+  static getInstance(): AppConfig {
+    if (!AppConfig.instance) {
+      AppConfig.instance = new AppConfig();
     }
+    return AppConfig.instance;
   }
 
   set(key: string, value: string | undefined): void {
     this.envConfig[key] = value;
   }
 
   get(key: string): string | undefined {
     return process.env[key] || this.envConfig[key];
   }
 
   getExternalUrl(): string {
@@ -91,8 +93,8 @@
         sslKey = this.get('DATABASE_SSL_KEY');
       } else {
         // Verify file exists
         if (fs.statSync(this.get('DATABASE_SSL_KEY')!).isFile()) {
           sslKey = fs.readFileSync(this.get('DATABASE_SSL_KEY')!);
         } else {
           throw new Error('SSL Key file does not exist');
         }
@@ -104,8 +106,8 @@
         sslCert = this.get('DATABASE_SSL_CERT');
       } else {
         // Verify file exists
         if (fs.statSync(this.get('DATABASE_SSL_CERT')!).isFile()) {
           sslCert = fs.readFileSync(this.get('DATABASE_SSL_CERT')!);
         } else {
           throw new Error('SSL Cert file does not exist');
         }
@@ -117,8 +119,8 @@
         sslCA = this.get('DATABASE_SSL_CA');
       } else {
         // Verify file exists
         if (fs.statSync(this.get('DATABASE_SSL_CA')!).isFile()) {
           sslCA = fs.readFileSync(this.get('DATABASE_SSL_CA')!);
         } else {
           throw new Error('SSL CA file does not exist');
         }
@@ -162,7 +164,7 @@
       return false;
     } else {
       const pattern =
         /^(?:([^:\/?#\s]+):\/{2})?(?:([^@\/?#\s]+)@)?([^\/?#\s]+)?(?:\/([^?#\s]*))?(?:[?]([^#\s]+))?\S*$/;
       const matches = url.match(pattern);
 
       if (matches === null) {

apps/backend/db/database.ts

@@ -1,5 +1,5 @@
 import AppConfig from '../config/app_config';
 
-const appConfig = new AppConfig();
+const appConfig = AppConfig.getInstance();
 
 module.exports = appConfig.getDbConfig();

apps/backend/package.json

@@ -3,6 +3,7 @@
   "version": "2.13.0",
   "license": "Apache-2.0",
   "description": "Heimdall's backend which allows for data persistence, authentication, RBAC, and API access",
+  "type": "commonjs",
   "repository": {
     "type": "git",
     "url": "https://github.com/mitre/heimdall2",
@@ -21,7 +22,7 @@
     "lint:ci": "eslint --max-warnings 0",
     "start": "node dist/src/main",
     "start:debug": "nest start --debug --watch",
-    "start:dev": "nest start --watch",
+    "start:dev": "dotenv -e .env -- nest start --watch",
     "test": "vitest",
     "test:ci": "vitest run"
   },

apps/backend/seeders/20200514154327-create-administrator.js

@@ -14,12 +14,9 @@ module.exports = {
     let envConfig = {};
     try {
       envConfig = dotenv.parse(fs.readFileSync('.env'));
-      console.log('Read config!');
     } catch (error) {
       if (error.code === 'ENOENT') {
-        // File probably does not exist
-        console.log('Unable to read configuration file `.env`!');
-        console.log('Falling back to environment or undefined values!');
+        console.warn('Seeder: .env not found, using environment variables only');
       } else {
         throw error;
       }

apps/backend/src/apikeys/apikey.controller.ts

@@ -1,4 +1,4 @@
-import {ForbiddenError} from '@casl/ability';
+import { ForbiddenError } from '@casl/ability';
 import {
   BadRequestException,
   Body,
@@ -11,67 +11,41 @@ import {
   Query,
   Request,
   UseGuards,
-  UseInterceptors
+  UseInterceptors,
 } from '@nestjs/common';
-import {AuthnService} from '../authn/authn.service';
-import {AuthzService} from '../authz/authz.service';
-import {Action} from '../casl/casl-ability.factory';
-import {GroupsService} from '../groups/groups.service';
-import {APIKeysEnabled} from '../guards/api-keys-enabled.guard';
-import {JwtAuthGuard} from '../guards/jwt-auth.guard';
-import {LoggingInterceptor} from '../interceptors/logging.interceptor';
-import {User} from '../users/user.model';
-import {UsersService} from '../users/users.service';
-import {ApiKeyService} from './apikey.service';
-import {APIKeyDto} from './dto/apikey.dto';
-import {CreateApiKeyDto} from './dto/create-apikey.dto';
-import {DeleteAPIKeyDto} from './dto/delete-apikey.dto';
-import {UpdateAPIKeyDto} from './dto/update-apikey.dto';
+import { AuthnService } from '../authn/authn.service';
+import { AuthzService } from '../authz/authz.service';
+import { Action } from '../casl/casl-ability.factory';
+import { GroupsService } from '../groups/groups.service';
+import { APIKeysEnabled } from '../guards/api-keys-enabled.guard';
+import { JwtAuthGuard } from '../guards/jwt-auth.guard';
+import { LoggingInterceptor } from '../interceptors/logging.interceptor';
+import { User } from '../users/user.model';
+import { UsersService } from '../users/users.service';
+import { ApiKeyService } from './apikey.service';
+import { APIKeyDto } from './dto/apikey.dto';
+import { CreateApiKeyDto } from './dto/create-apikey.dto';
+import { DeleteAPIKeyDto } from './dto/delete-apikey.dto';
+import { UpdateAPIKeyDto } from './dto/update-apikey.dto';
 
-@UseInterceptors(LoggingInterceptor)
-@UseGuards(APIKeysEnabled)
 @Controller('apikeys')
+@UseGuards(APIKeysEnabled)
+@UseInterceptors(LoggingInterceptor)
 export class ApiKeyController {
   constructor(
     private readonly authnService: AuthnService,
     private readonly apiKeyService: ApiKeyService,
     private readonly authz: AuthzService,
     private readonly usersService: UsersService,
-    private readonly groupsService: GroupsService
+    private readonly groupsService: GroupsService,
   ) {}
 
-  @UseGuards(JwtAuthGuard)
-  @Get()
-  async findAPIKeys(
-    @Request() request: {user: User},
-    @Query('userId') userId: string,
-    @Query('groupId') groupId: string
-  ): Promise<APIKeyDto[]> {
-    const abac = this.authz.abac.createForUser(request.user);
-
-    if (userId && groupId) {
-      throw new BadRequestException('Cannot specify both userId and groupId');
-    }
-
-    if (groupId) {
-      const group = await this.groupsService.findByPkBang(groupId);
-      ForbiddenError.from(abac).throwUnlessCan(Action.Read, group);
-      return this.apiKeyService.findAllForGroup(group);
-    } else {
-      const user = userId
-        ? await this.usersService.findById(userId)
-        : request.user;
-      ForbiddenError.from(abac).throwUnlessCan(Action.Read, user);
-      return this.apiKeyService.findAllForUser(user);
-    }
-  }
-
-  @UseGuards(JwtAuthGuard)
   @Post()
+  @UseGuards(JwtAuthGuard)
   async createAPIKey(
-    @Request() request: {user: User},
-    @Body() createApiKeyDto: CreateApiKeyDto
-  ): Promise<{id: string; apiKey: string}> {
+    @Request() request: { user: User },
+    @Body() createApiKeyDto: CreateApiKeyDto,
+  ): Promise<{ apiKey: string; id: string }> {
     const abac = this.authz.abac.createForUser(request.user);
 
     let target;
@@ -94,24 +68,24 @@ export class ApiKeyController {
     return this.apiKeyService.create(target, createApiKeyDto);
   }
 
-  @UseGuards(JwtAuthGuard)
   @Delete(':id')
+  @UseGuards(JwtAuthGuard)
   async deleteAPIKey(
-    @Request() request: {user: User},
+    @Request() request: { user: User },
     @Param('id') id: string,
-    @Body() deleteApiKeyDto: DeleteAPIKeyDto
+    @Body() deleteApiKeyDto: DeleteAPIKeyDto,
   ): Promise<APIKeyDto> {
     const apiKeyToDelete = await this.apiKeyService.findById(id);
     const abac = this.authz.abac.createForUser(request.user);
 
     if (apiKeyToDelete.type === 'user') {
       ForbiddenError.from(abac).throwUnlessCan(
         Action.Update,
-        apiKeyToDelete.user
+        apiKeyToDelete.user,
       );
     } else if (apiKeyToDelete.type === 'group') {
       const group = await this.groupsService.findByPkBang(
-        apiKeyToDelete.groupId
+        apiKeyToDelete.groupId,
       );
       ForbiddenError.from(abac).throwUnlessCan(Action.Update, group);
     } else {
@@ -124,24 +98,50 @@ export class ApiKeyController {
     return this.apiKeyService.remove(id);
   }
 
+  @Get()
   @UseGuards(JwtAuthGuard)
+  async findAPIKeys(
+    @Request() request: { user: User },
+    @Query('userId') userId: string,
+    @Query('groupId') groupId: string,
+  ): Promise<APIKeyDto[]> {
+    const abac = this.authz.abac.createForUser(request.user);
+
+    if (userId && groupId) {
+      throw new BadRequestException('Cannot specify both userId and groupId');
+    }
+
+    if (groupId) {
+      const group = await this.groupsService.findByPkBang(groupId);
+      ForbiddenError.from(abac).throwUnlessCan(Action.Read, group);
+      return this.apiKeyService.findAllForGroup(group);
+    } else {
+      const user = userId
+        ? await this.usersService.findById(userId)
+        : request.user;
+      ForbiddenError.from(abac).throwUnlessCan(Action.Read, user);
+      return this.apiKeyService.findAllForUser(user);
+    }
+  }
+
   @Put('/:id')
+  @UseGuards(JwtAuthGuard)
   async updateAPIKey(
-    @Request() request: {user: User},
+    @Request() request: { user: User },
     @Param('id') id: string,
-    @Body() updateApiKeyDto: UpdateAPIKeyDto
+    @Body() updateApiKeyDto: UpdateAPIKeyDto,
   ): Promise<APIKeyDto> {
     const apiKeyToUpdate = await this.apiKeyService.findById(id);
     const abac = this.authz.abac.createForUser(request.user);
     if (apiKeyToUpdate.type === 'group') {
       const group = await this.groupsService.findByPkBang(
-        apiKeyToUpdate.groupId
+        apiKeyToUpdate.groupId,
       );
       ForbiddenError.from(abac).throwUnlessCan(Action.Update, group);
     } else if (apiKeyToUpdate.type === 'user') {
       ForbiddenError.from(abac).throwUnlessCan(
         Action.Update,
-        apiKeyToUpdate.user
+        apiKeyToUpdate.user,
       );
     } else {
       throw new BadRequestException('Unknown API key type');

apps/backend/src/apikeys/apikey.model.ts

@@ -9,53 +9,49 @@ import {
   Model,
   PrimaryKey,
   Table,
-  UpdatedAt
+  UpdatedAt,
 } from 'sequelize-typescript';
-import {Group} from '../groups/group.model';
-import {User} from '../users/user.model';
+import { Group } from '../groups/group.model';
+import { User } from '../users/user.model';
 
 @Table
 export class ApiKey extends Model {
-  @PrimaryKey
-  @AutoIncrement
+  @Column(DataType.STRING)
+  declare apiKey: string;
+
   @AllowNull(false)
-  @Column(DataType.BIGINT)
-  declare id: string;
+  @Column(DataType.DATE)
+  @CreatedAt
+  declare createdAt: Date;
 
-  @ForeignKey(() => User)
-  @Column(DataType.BIGINT)
-  declare userId: string;
+  @BelongsTo(() => Group, { constraints: false })
+  declare group: Group;
 
-  @ForeignKey(() => Group)
   @Column(DataType.BIGINT)
+  @ForeignKey(() => Group)
   declare groupId: string;
 
-  @BelongsTo(() => User, {
-    constraints: false
-  })
-  declare user: User;
-
-  @BelongsTo(() => Group, {
-    constraints: false
-  })
-  declare group: Group;
+  @AllowNull(false)
+  @AutoIncrement
+  @Column(DataType.BIGINT)
+  @PrimaryKey
+  declare id: string;
 
   @Column(DataType.STRING)
   declare name: string;
 
-  @Column(DataType.STRING)
-  declare apiKey: string;
-
   @Column(DataType.STRING)
   declare type: string;
 
-  @CreatedAt
   @AllowNull(false)
   @Column(DataType.DATE)
-  declare createdAt: Date;
-
   @UpdatedAt
-  @AllowNull(false)
-  @Column(DataType.DATE)
   declare updatedAt: Date;
+
+  @BelongsTo(() => User, { constraints: false })
+  declare user: User;
+
+  @Column(DataType.BIGINT)
+  @ForeignKey(() => User)
+  declare userId: string;
 }