Pre-Recorded Evidence Portal (pre-portal)

Table of Contents

• Introduction
  • Intro to Pre-Recorded Evidence System
  • Purpose
  • PRE System Diagram (Needs to be updated)
• Other PRE Repositories
• Running the application Locally
  • Prerequisites
  • Install Dependencies and Build
  • Start the Application
    • With the Command Line
    • With IntelliJ IDEA
• Developing for Pre Portal
  • Logging into the application
  • Code style
  • Running the tests
    • Unit Tests
    • Functional Tests
    • Accessibility Tests
  • Security
    • CSRF prevention
    • Helmet
  • Healthcheck
• Troubleshooting
  • Common issues
    • Error: checks.state argument is missing

Introduction

Intro to Pre-Recorded Evidence System

The Pre-Recorded Evidence (PRE) system is a service from HM Courts and Tribunal Service.

It allows the capturing of a video-recorded hearing or testimony. Recordings can be securely shared to advocates, or played back in court. You can learn more about the service here.

If you can access Gov Slack, you can find us on our Slack channel. Otherwise, please fill this contact form https://www.gov.uk/contact/govuk and ask for the issue to be referred to the Pre-Recorded Evidence technical team.

Purpose

This code repository contains the source code for the Pre-Recorded Evidence Portal. The Portal provides a secure interface for professional and judicial users to login, browse and watch recordings which have been shared with them.

PRE System Diagram (Needs to be updated)

This diagram gives an overview of the PRE system which the pre-portal connects to in its current state (not yet live).

    C4Context
      title System Context diagram for Pre-Recorded Evidence

      Person(adminUser, "Admin User", "")
      Person(judicialUser, "Judicial User", "")
      Person(professionalUser, "Professional User", "")


      System_Boundary(PowerPlatform, "Power Platform") {
        System(PowerApps, "Power Apps Forms", "User Authentication via MS Teams")
        System(PowerFlows, "Power Flows", "")
        SystemDb(Dataverse, "Dataverse", "")
      }

      Enterprise_Boundary(a0, "SDS Azure Tenant",) {
        System(Portal, "Portal", "User Authentication via Azure B2C")

        System_Boundary(api, "API") {
            System(api, "pre-api", "System Authentication via Azure APIm.<br/>User Authorisation via X-User-Id header")
            SystemDb(db, "API db")
        }

        System_Boundary(media, "Media") {
            SystemDb(blob, "Azure Blob Storage")
        }

      }

      Enterprise_Boundary(a1, "Media Kind Azure Tenant",) {
        System(mk, "Media Kind")
      }

      BiRel(judicialUser, Portal, "")
      BiRel(adminUser, Portal, "")
      BiRel(adminUser, PowerApps, "")
      BiRel(professionalUser, Portal, "")
      BiRel(PowerApps, PowerFlows, "")
      Rel(Portal, PowerFlows, "")
      Rel(Portal, api, "")
      BiRel(PowerFlows, Dataverse, "")
      Rel(PowerApps, api, "")
      BiRel(PowerFlows, api, "")
      Rel(api, db, "")

      Rel(Portal, mk, "")
      Rel(PowerApps, mk, "")
      Rel(PowerFlows, mk, "")
      Rel(api, mk, "")
      Rel(mk, blob, "")
      UpdateElementStyle(Portal,  $bgColor="green", $borderColor="black")
      UpdateElementStyle(PowerPlatform)
      UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

Loading

Other PRE Repositories

• PRE Power Platform Frontend
• PRE Shared Infrastructure
• PRE Function Apps
• PRE API

Running the application Locally

Prerequisites

Running the application requires the following tools to be installed in your environment:

• Node.js v22.15.0 or later (due to ESM and CJS compatibility)
• yarn
• Docker

Before running the application, you need to set up the environment variables. Create a .env file in the root of the project. You can get the variables and values to fill your .env file with from one of the PRE developers.

Pre Portal requires the Pre API to be running. You can run it locally by following the instructions in the pre-api repository. Or you can use the staging environment Pre API by setting the PRE_API_URL environment variable to the staging API URL in the .env file.

Install Dependencies and Build

You can install the dependencies using yarn package manager.

yarn install

Compile the Typescript files/assets and bundle the application using Webpack:

yarn webpack

Start the Application

With the Command Line

Load your environment variables from the .env file:

export $(grep -v '^#' .env | xargs -0)

Run the application:

yarn start:dev

The applications's home page will be available at https://localhost:4551

With IntelliJ IDEA

Copy the contents of the .env file.

Click on Modify Run Configuration.

Next to the Environment Variables field click on the clipboard icon and paste the contents of the .env file.

Open the package.json file and right-click on the start:dev script.

Click on the Run 'start:dev' button.

Developing for Pre Portal

Logging into the application

To access the portal you will need to login. When you start the application and go to home page you will be redirected to an Azure B2C login screen. The login credentials you use will need to have permission to use PRE Portal. A PRE developer should be able to provide you with a test user to login to the portal with. If you are not able to login, please contact one of the PRE developers

Code style

We use ESLint alongside sass-lint

Running the linting with auto fix:

yarn lint --write

Running the tests

This template app uses Jest as the test engine.

Important: Currently, Jest is incompatible with ESM modules. Babel has been implemented to transform ESM modules to enable compatibility.

You can run unit tests by executing the following command:

Unit Tests

yarn test:unit

Functional Tests

yarn test:functional

Accessibility Tests

Running accessibility tests:

yarn test:pa11y

Accessibility tests (see a11y.ts) make use of the accessibility library Pa11y. All paths in PRE Portal should be tested for accessibility issues.

Puppeteer Usage Over Playwright

The accessibility tests use Puppeteer to run a headless browser. This is because pa11y does not seem currently compatible with Playwright browser contexts and the current tests have complexities (conditional logic, dynamic IDs, etc) that make them difficult to convert to Pa11y actions.

These will be converted to Playwright in upcoming work.

Security

CSRF prevention

Cross-Site Request Forgery prevention has already been set up at the application level. However, you need to make sure that CSRF token is present in every HTML form that requires it. For that purpose you can use the csrfProtection macro, included in [csrf.njk](src/main/views/macros/csrf.njk). Your njk file would look like this:

{% from "macros/csrf.njk" import csrfProtection %}
...
<form ...>
  ...
    {{ csrfProtection(csrfToken) }}
  ...
</form>
...

Helmet

This application uses Helmet, which adds various security-related HTTP headers to the responses. Apart from default Helmet functions, following headers are set:

• Referrer-Policy
• Content-Security-Policy

There is a configuration section related with those headers, where you can specify:

• referrerPolicy - value of the Referrer-Policy header

Here's an example setup:

    "security": {
      "referrerPolicy": "origin"
    }

Make sure you have those values set correctly for your application.

Healthcheck

The application exposes a health endpoint (https://localhost:4551/health), created with the use of Nodejs Healthcheck library. This endpoint is defined in health.ts file. Make sure you adjust it correctly in your application. In particular, remember to replace the sample check with checks specific to your frontend app, e.g. the ones verifying the state of each service it depends on.

Altering the sign-in page

The sign in page is provided by Azure B2C. The code for it is in https://github.com/hmcts/pre-shared-infrastructure/tree/master/b2c. Make sure you read the README first.

Testing with the DEV instance of B2C

Sometimes you'll be making changes to B2C and you'll want a frontend available which points to it.

To point the pre-portal at the dev B2C instance you simply need to add the tag pr-values: devb2c to the GitHub PR you are working on. Instructions on how this works can be found here.

Troubleshooting

Common issues

Error: checks.state argument is missing

This error can occur when PRE API is not reachable. Make sure you have the API running and that the URL in the .env file is correct. You can check if the API is running by visiting the health endpoint in your browser: https://localhost:4551/health. If the API is running, you should see a JSON response with the status of "pre-api" being "UP".

License

This project is licensed under the MIT License - see the LICENSE file for details