@hmcts/opal-frontend-common-node 0.0.2

package/.editorconfig

@@ -0,0 +1,16 @@
+# Editor configuration, see https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.ts]
+quote_type = single
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

package/.github/renovate.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["github>hmcts/.github//renovate/automerge-all", "local>hmcts/.github:renovate-config"],
+  "packageRules": [
+    {
+      "matchPackageNames": ["copy-webpack-plugin"],
+      "allowedVersions": "<=10",
+      "description": "https://canary.discord.com/channels/226791405589233664/1019534554073157642 and https://github.com/webpack-contrib/copy-webpack-plugin/issues/643 doesn't work even though issue closed"
+    }
+  ]
+}

package/.github/workflows/npm_build.yml

@@ -0,0 +1,67 @@
+name: Angular Library CI Pipeline
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  release:
+    types: [created]
+
+jobs:
+  ci:
+    name: Build, Test, and Analyse
+    if: github.event_name != 'release'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Lint code
+        run: yarn lint
+
+      - name: Audit vulnerabilities
+        run: yarn audit --production
+
+      - name: Analyze with SonarCloud
+        uses: SonarSource/sonarqube-scan-action@v5.1.0
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+
+      - name: Build library
+        run: yarn build
+
+  release:
+    name: Release and Publish
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository (Release)
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.target_commitish }}
+
+      - name: Validate and extract release information
+        id: release
+        uses: manovotny/github-releases-for-automated-package-publishing-action@v2.0.1
+
+      - name: Setup Node.js (Release)
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+          registry-url: 'https://registry.npmjs.org'
+          always-auth: true
+
+      - name: Install dependencies (Release)
+        run: yarn install --frozen-lockfile
+
+      - name: Build library (Release)
+        run: yarn build
+
+      - name: Publish version
+        run: yarn publish --new-version ${{ steps.release.outputs.version }} --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.npm_api_token }}

package/.prettierignore

@@ -0,0 +1,12 @@
+# third party
+dist
+.angular
+yarn.lock
+.yarn/
+
+.vscode
+coverage
+charts
+
+server/assets/*
+server/views/azuread-b2c-login.html

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "tabWidth": 2,
+  "useTabs": false,
+  "singleQuote": true,
+  "printWidth": 120,
+  "semi" : true
+}

package/.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "sonarlint.connectedMode.project": {
+        "connectionId": "HMCTS",
+        "projectKey": "hmcts_opal-frontend-common-node-lib"
+    }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 HM Courts & Tribunals Service
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# OPAL Frontend Common Node Library
+[![npm version](https://img.shields.io/npm/v/@hmcts/opal-frontend-common-node)](https://www.npmjs.com/package/@hmcts/opal-frontend-common-node)
+[![License](https://img.shields.io/npm/l/@hmcts/opal-frontend-common-node)](https://github.com/hmcts/opal-frontend-common-node-lib/blob/main/LICENSE)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=hmcts_opal-frontend-common-node-lib&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=hmcts_opal-frontend-common-node-lib)
+
+This is a shared Node.js library containing common middleware, configurations, and utilities used across OPAL backend services.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Scripts](#scripts)
+- [Build Process](#build-process)
+- [Linting and Formatting](#linting-and-formatting)
+- [Exports](#exports)
+- [Using This Library in a Node.js Application](#using-this-library-in-a-nodejs-application)
+
+## Getting Started
+
+### Prerequisites
+
+Ensure you have the following installed:
+
+- [Node.js](https://nodejs.org/) v18 or later
+- [Yarn](https://classic.yarnpkg.com/) v1.22.22 or later
+
+### Install Dependencies
+
+```bash
+yarn
+```
+
+## Scripts
+
+The following commands are available in the `package.json`:
+
+- `yarn build`  
+  Cleans the `dist/` folder, compiles TypeScript, and copies relevant files to `dist/`.
+
+- `yarn clean`  
+  Removes the `dist/` directory.
+
+- `yarn lint`  
+  Runs ESLint across the `src/` directory and checks formatting using Prettier.
+
+- `yarn prettier`  
+  Checks if files are formatted correctly.
+
+- `yarn prettier:fix`  
+  Automatically formats the codebase.
+
+## Build Process
+
+Run the following to build the project:
+
+```bash
+yarn build
+```
+
+The compiled output will be available in the `dist/` folder. It includes `index.js`, type declarations, and any exported modules listed in the `exports` field.
+
+## Linting and Formatting
+
+To lint and check formatting:
+
+```bash
+yarn lint
+```
+
+To fix formatting issues automatically:
+
+```bash
+yarn prettier:fix
+```
+
+## Exports
+
+This library exposes multiple entry points under the `exports` field of `package.json`. Example usage:
+
+```ts
+import { CSRFToken } from '@hmcts/opal-frontend-common-node/csrf-token';
+import { AppInsights } from '@hmcts/opal-frontend-common-node/app-insights';
+import { Helmet } from '@hmcts/opal-frontend-common-node/helmet';
+import { LaunchDarkly } from '@hmcts/opal-frontend-common-node/launch-darkly';
+import {
+  ExpiryConfiguration,
+  RoutesConfiguration,
+  SessionStorageConfiguration,
+  TransferServerState,
+} from '@hmcts/opal-frontend-common-node/interfaces';
+```
+
+Refer to the `exports` block in `package.json` for the full list of available modules.
+
+## Using This Library in a Node.js Application
+
+Install the published package using:
+
+```bash
+yarn add @hmcts/opal-frontend-common-node
+```
+
+If consuming from a local build:
+
+```bash
+yarn remove @hmcts/opal-frontend-common-node
+yarn add @hmcts/opal-frontend-common-node@file:../opal-frontend-common-node-lib/dist
+```
+
+Ensure paths reflect your actual local setup when using the `file:` specifier.

package/eslint.config.js

@@ -0,0 +1,22 @@
+// eslint.config.js
+import tseslint from 'typescript-eslint';
+import prettierPlugin from 'eslint-plugin-prettier';
+
+/** @type {import("eslint").Linter.FlatConfig[]} */
+export default [
+  // Recommended base config (no type-checking rules)
+  ...tseslint.configs.recommended,
+
+  // You can add stricter type-checking rules later:
+  // ...tseslint.configs['recommended-requiring-type-checking'],
+
+  {
+    files: ['**/*.ts'],
+    plugins: {
+      prettier: prettierPlugin,
+    },
+    rules: {
+      'prettier/prettier': 'error',
+    },
+  },
+];

package/package.json

@@ -0,0 +1,117 @@
+{
+  "name": "@hmcts/opal-frontend-common-node",
+  "type": "module",
+  "version": "0.0.2",
+  "description": "Common nodejs library components for opal",
+  "main": "dist/index",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": " yarn clean && tsc && cp package.json dist/ && cp src/*.d.ts dist/",
+    "clean": "rm -rf dist",
+    "lint": "eslint ./src --ext .ts && yarn prettier",
+    "prettier": "prettier --check \"./src/**/*.{ts,js,json}\"",
+    "prettier:fix": "prettier --write \"./src/**/*.{ts,js,json}\""
+  },
+  "dependencies": {
+    "@hmcts/info-provider": "^1.1.0",
+    "@hmcts/nodejs-healthcheck": "^1.8.5",
+    "@hmcts/nodejs-logging": "^4.0.4",
+    "@hmcts/properties-volume": "^1.1.0",
+    "applicationinsights": "~2.9.6",
+    "axios": "^1.6.2",
+    "body-parser": "^2.0.0",
+    "config": "^3.3.9",
+    "connect-redis": "^8.0.0",
+    "cookie-parser": "^1.4.6",
+    "csrf-csrf": "^3.0.6",
+    "express": "^4.15.2",
+    "express-session": "^1.17.3",
+    "helmet": "^8.0.0",
+    "http-proxy-middleware": "^3.0.0",
+    "luxon": "^3.4.3",
+    "prettier": "^3.0.3",
+    "redis": "^4.6.11",
+    "session-file-store": "^1.5.0",
+    "xml2js": "^0.6.2"
+  },
+  "devDependencies": {
+    "@types/config": "^3.3.3",
+    "@types/cookie-parser": "^1.4.6",
+    "@types/express": "^5.0.0",
+    "@types/luxon": "^3.4.2",
+    "@types/node": "^22.0.0",
+    "@types/session-file-store": "^1.2.5",
+    "@typescript-eslint/eslint-plugin": "8.29.1",
+    "@typescript-eslint/parser": "8.29.1",
+    "eslint": "^9.0.0",
+    "eslint-plugin-prettier": "^5.2.6",
+    "typescript": "~5.8.0",
+    "typescript-eslint": "^8.30.1"
+  },
+  "packageManager": "yarn@1.22.22",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "types": "./index.d.ts"
+    },
+    "./app-insights": {
+      "import": "./app-insights/index.js",
+      "types": "./app-insights/index.d.ts"
+    },
+    "./health": {
+      "import": "./health/index.js",
+      "types": "./health/index.d.ts"
+    },
+    "./helmet": {
+      "import": "./helmet/index.js",
+      "types": "./helmet/index.d.ts"
+    },
+    "./launch-darkly": {
+      "import": "./launch-darkly/index.js",
+      "types": "./launch-darkly/index.d.ts"
+    },
+    "./properties-volume": {
+      "import": "./properties-volume/index.js",
+      "types": "./properties-volume/index.d.ts"
+    },
+    "./csrf-token": {
+      "import": "./csrf-token/index.js",
+      "types": "./csrf-token/index.d.ts"
+    },
+    "./routes": {
+      "import": "./routes/index.js",
+      "types": "./routes/index.d.ts"
+    },
+    "./interfaces": {
+      "import": "./interfaces/index.js",
+      "types": "./interfaces/index.d.ts"
+    },
+    "./session": {
+      "import": "./session/index.js",
+      "types": "./session/index.d.ts"
+    },
+    "./session/session-storage": {
+      "import": "./session/session-storage/index.js",
+      "types": "./session/session-storage/index.d.ts"
+    },
+    "./session/session-expiry": {
+      "import": "./session/session-expiry/index.js",
+      "types": "./session/session-expiry/index.d.ts"
+    },
+    "./session/session-user-state": {
+      "import": "./session/session-user-state/index.js",
+      "types": "./session/session-user-state/index.d.ts"
+    },
+    "./proxy": {
+      "import": "./proxy/index.js",
+      "types": "./proxy/index.d.ts"
+    },
+    "./proxy/opal-api-proxy": {
+      "import": "./proxy/opal-api-proxy/index.js",
+      "types": "./proxy/opal-api-proxy/index.d.ts"
+    },
+    "./types": {
+      "types": "./global.d.ts"
+    }
+  }
+}

package/sonar-project.properties

@@ -0,0 +1,9 @@
+sonar.organization=hmcts
+sonar.projectKey=hmcts_opal-frontend-common-node-lib
+sonar.projectName=opal-frontend-common-node-lib
+sonar.projectVersion=0.0.1
+
+sonar.sources=src
+
+# Skip code coverage reporting
+sonar.coverage.exclusions=**/*

package/src/app-insights/app-insights-configuration.ts

@@ -0,0 +1,18 @@
+import AppInsightConfig from '../interfaces/app-insights-config';
+
+export default class AppInsightsConfiguration {
+  public enableFor(enabled: boolean, connectionString: string | null, cloudRoleName: string | null): AppInsightConfig {
+    const appInsightsConfig: AppInsightConfig = {
+      enabled: enabled,
+      connectionString: null,
+      cloudRoleName: null,
+    };
+
+    if (enabled && connectionString && cloudRoleName) {
+      appInsightsConfig.connectionString = connectionString;
+      appInsightsConfig.cloudRoleName = cloudRoleName;
+    }
+
+    return appInsightsConfig;
+  }
+}

package/src/app-insights/index.ts

@@ -0,0 +1,39 @@
+process.env['APPLICATIONINSIGHTS_CONFIGURATION_CONTENT'] = '{}';
+import * as appInsights from 'applicationinsights';
+import AppInsightConfig from '../interfaces/app-insights-config';
+import AppInsightsConfiguration from './app-insights-configuration';
+
+// As of 2.9.0 issue reading bundled applicationinsights.json
+// https://github.com/microsoft/ApplicationInsights-node.js/issues/1226
+// Define config below...
+
+export class AppInsights {
+  enable(enabled: boolean, connectionString: string | null, cloudRoleName: string | null): AppInsightConfig {
+    const appInsightsConfigInstance = new AppInsightsConfiguration();
+    const appInsightsConfig = appInsightsConfigInstance.enableFor(enabled, connectionString, cloudRoleName);
+
+    if (enabled && connectionString) {
+      appInsights
+        .setup(connectionString)
+        .setAutoCollectRequests(true)
+        .setAutoCollectPerformance(true, true)
+        .setAutoCollectExceptions(true)
+        .setAutoCollectDependencies(true)
+        .setAutoCollectConsole(true, false)
+        .setAutoCollectPreAggregatedMetrics(true)
+        .setSendLiveMetrics(true)
+        .setInternalLogging(false, true)
+        .enableWebInstrumentation(false)
+        .start();
+
+      if (cloudRoleName) {
+        appInsights.defaultClient.context.tags[appInsights.defaultClient.context.keys.cloudRole] = cloudRoleName;
+      }
+      appInsights.defaultClient.trackTrace({
+        message: 'App insights activated',
+      });
+    }
+
+    return appInsightsConfig;
+  }
+}

package/src/csrf-token/index.ts

@@ -0,0 +1,36 @@
+import { doubleCsrf } from 'csrf-csrf';
+import { Application, Request } from 'express';
+
+export class CSRFToken {
+  public enableFor(app: Application, secret: string, cookieName: string, sameSite: boolean, secure: boolean): void {
+    const ignore = ['/sso/login-callback'];
+
+    const { doubleCsrfProtection } = doubleCsrf({
+      getSecret: () => secret,
+      cookieName: cookieName,
+      cookieOptions: {
+        sameSite: sameSite,
+        secure: secure,
+        path: '/',
+      },
+      getTokenFromRequest: (req) => {
+        return req.cookies[cookieName].split('|')[0] ?? null;
+      },
+    });
+
+    app.use((req, res, next) => {
+      if (ignore.includes(req.url)) {
+        next();
+      } else {
+        doubleCsrfProtection(req, res, next);
+      }
+    });
+
+    app.use((req: Request, res, next) => {
+      if (req.csrfToken) {
+        req.csrfToken(true);
+      }
+      next();
+    });
+  }
+}

package/src/global.d.ts

@@ -0,0 +1,2 @@
+declare module '@hmcts/nodejs-logging';
+declare module '@hmcts/nodejs-healthcheck';

package/src/health/index.ts

@@ -0,0 +1,32 @@
+import os from 'os';
+import healthcheck from '@hmcts/nodejs-healthcheck';
+import { Application } from 'express';
+
+/**
+ * Sets up the HMCTS info and health endpoints
+ */
+export class HealthCheck {
+  public enableFor(app: Application, buildInfoName: string): void {
+    const redis = app.locals['redisClient']
+      ? healthcheck.raw(() => app.locals['redisClient'].ping().then(healthcheck.up).catch(healthcheck.down))
+      : null;
+
+    healthcheck.addTo(app, {
+      checks: {
+        ...(redis ? { redis } : {}),
+      },
+      ...(redis
+        ? {
+            readinessChecks: {
+              redis,
+            },
+          }
+        : {}),
+      buildInfo: {
+        name: buildInfoName,
+        host: os.hostname(),
+        uptime: process.uptime(),
+      },
+    });
+  }
+}

package/src/helmet/index.ts

@@ -0,0 +1,60 @@
+import * as express from 'express';
+import helmet from 'helmet';
+import { Logger } from '@hmcts/nodejs-logging';
+
+const logger = Logger.getLogger('helmet');
+const googleAnalyticsDomain = '*.google-analytics.com';
+const self = "'self'";
+const dynatraceDomain = '*.dynatrace.com';
+const LaunchDarklyDomain = '*.launchdarkly.com';
+const azureDomain = '*.azure.com';
+const applicationInsightsDomain = '*.applicationinsights.azure.com';
+/**
+ * Module that enables helmet in the application
+ */
+export class Helmet {
+  private readonly developmentMode: boolean;
+  constructor(developmentMode: boolean) {
+    this.developmentMode = developmentMode;
+  }
+
+  public enableFor(app: express.Express, enabled: boolean): void {
+    if (enabled) {
+      logger.info('Helmet enabled');
+      // include default helmet functions
+      const scriptSrc = [
+        self,
+        googleAnalyticsDomain,
+        dynatraceDomain,
+        "'sha256-+6WnXIl4mbFTCARd8N3COQmT3bJJmo32N8q8ZSQAIcU='",
+        "'unsafe-inline'",
+      ];
+
+      if (this.developmentMode) {
+        // Uncaught EvalError: Refused to evaluate a string as JavaScript because 'unsafe-eval'
+        // is not an allowed source of script in the following Content Security Policy directive:
+        // "script-src 'self' *.google-analytics.com 'sha256-+6WnXIl4mbFTCARd8N3COQmT3bJJmo32N8q8ZSQAIcU='".
+        // seems to be related to webpack
+        scriptSrc.push("'unsafe-eval'");
+      }
+
+      app.use(
+        helmet({
+          contentSecurityPolicy: {
+            directives: {
+              connectSrc: [self, dynatraceDomain, LaunchDarklyDomain, azureDomain, applicationInsightsDomain],
+              defaultSrc: ["'none'"],
+              fontSrc: [self, 'data:', 'https://fonts.gstatic.com'],
+              imgSrc: [self, googleAnalyticsDomain],
+              objectSrc: [self],
+              scriptSrc,
+              styleSrc: [self, "'unsafe-inline'", 'https://fonts.googleapis.com'],
+              scriptSrcAttr: ["'unsafe-inline'"],
+            },
+          },
+          referrerPolicy: { policy: 'origin' },
+        }),
+      );
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from './launch-darkly';
+export * from './app-insights';
+export * from './health';
+export * from './helmet';
+export * from './properties-volume';
+export * from './csrf-token';
+export * from './routes';
+
+// INTERFACES
+export * from './interfaces';

package/src/interfaces/app-insights-config.ts

@@ -0,0 +1,7 @@
+class AppInsightsConfig {
+  enabled!: boolean;
+  connectionString!: string | null;
+  cloudRoleName!: string | null;
+}
+
+export default AppInsightsConfig;

package/src/interfaces/index.ts

@@ -0,0 +1,23 @@
+import UserState from './userState';
+import SecurityToken from './securityToken';
+import launchDarklyConfig from './launch-darkly-config';
+import appInsightsConfig from './app-insights-config';
+import TransferServerState from './transfer-server-state';
+import ExpiryConfiguration from './session-expiry-config';
+import SessionStorageConfiguration from './session-storage-config';
+import RoutesConfiguration from './routes-config';
+import SsoConfiguration from './sso-config';
+import SessionConfiguration from './session-config';
+
+export {
+  UserState,
+  SecurityToken,
+  launchDarklyConfig,
+  appInsightsConfig,
+  TransferServerState,
+  ExpiryConfiguration,
+  SessionStorageConfiguration,
+  RoutesConfiguration,
+  SsoConfiguration,
+  SessionConfiguration,
+};

package/src/interfaces/launch-darkly-config.ts

@@ -0,0 +1,7 @@
+class LaunchDarklyConfig {
+  enabled!: boolean;
+  clientId!: string | null;
+  stream!: boolean;
+}
+
+export default LaunchDarklyConfig;

package/src/interfaces/routes-config.ts

@@ -0,0 +1,8 @@
+class RoutesConfiguration {
+  opalApiTarget!: string;
+  opalFinesServiceTarget!: string;
+  frontendHostname!: string;
+  prefix!: string;
+}
+
+export default RoutesConfiguration;

package/src/interfaces/securityToken.ts

@@ -0,0 +1,8 @@
+import UserState from './userState';
+
+class SecurityToken {
+  user_state: UserState | undefined;
+  access_token!: string;
+}
+
+export default SecurityToken;