hmpps-prison-permissions-lib

A Node.js client library to centralise the process of determining user permissions for prison services and data.

We welcome feedback on this library and README here in order to improve it.

Table of Contents

1. Introduction
2. What checks are made?
3. Where does the data come from?
4. How do I implement this library?

✨ Introduction

Determining whether a user has access to a particular resource (e.g. a service, or prisoner data) consists of a number of checks and is not necessarily just determined by what roles a user has been assigned.

This permissions library aims to share the logic centrally so that all services agree on what a user should and should not be able to access. It is used by the prisoner profile to determine if a user can access certain parts of the prisoner's profile for example.

🔎 What checks are made?

The permissions use a variety of checks, based on:

• The user's DPS roles
• The user's case load list (and active case load)
• The user's key worker status at a prison
• The prisoner's location (which prison they are at, or whether they are transferring or out of prison)
• The prisoner's restricted patient status

📊 Where does the data come from?

We do not yet have a centralised permissions service, so this library requires some input data to determine the user permissions.

We expect that the user's roles and case loads are already available at:

• res.locals.user.userRoles,
• res.locals.user.caseLoads,
• res.locals.user.activeCaseLoad,
• res.locals.user.activeCaseLoadId,

User roles are already part of the Typescript Template project here and the retrieval of case load data is available in hmpps-connect-dps-components middleware.

The library will make its own calls to Prison API to determine the user's key worker status, caching it in the user session and storing it at res.locals.user.keyWorkerAtPrisons.

Finally the library will also retrieve data about a prisoner from hmpps-prisoner-search and store it at req.middleware.prisonerData.

✍️ How do I implement this library?

1. Install the library

npm install @ministryofjustice/hmpps-prison-permissions-lib

2. Create the PermissionsService

The permissions service should be created just like any other of your services. It requires the following:

• prisonApiConfig: Prison API configuration conforming to the hmpps-typescript-lib's ApiConfig interface
• prisonerSearchConfig: Prisoner Search configuration conforming to the hmpps-typescript-lib's ApiConfig interface
• authenticationClient: An AuthenticationClient instance (see hmpps-typescript-lib) in order to make authorized client credentials calls to Prisoner Search.
• logger: Bunyan logger for logging permissions events. Defaults to using console.
• telemetryClient: Optional but recommended. Instead of just logging permissions events, this provides richer metadata to Application Insights.

e.g.

import { PermissionsService  } from '@ministryofjustice/hmpps-prison-permissions-lib'

...

const prisonPermissionsService = PermissionsService.create({
  prisonApiConfig: config.apis.prisonApi,
  prisonerSearchConfig: config.apis.prisonerSearchApi,
  authenticationClient: new AuthenticationClient(config.apis.hmppsAuth, logger, tokenStore),
  logger,
  telemetryClient,
})

3. Ensure your client has the role ROLE_VIEW_PRISONER_DATA...

...in order to be able to successfully call Prisoner Search (see Swagger docs).

4. Add the prisonerPermissionsGuard middleware to your service's routes:

e.g.

import { PrisonerBasePermission, prisonerPermissionsGuard } from '@ministryofjustice/hmpps-prison-permissions-lib'

...

get(
  `prisoner/{prisonerNumber}/somepage`,
  ...
  prisonerPermissionsGuard(permissionsService, { requestDependentOn: [PrisonerBasePermission.read] }),
  async (req, res, next) => {
    ...

5. Ensure you handle 403s as required

If the user does not have the required permissions listed in requestDependentOn, then the middleware will throw a PrisonerPermissionError with a status code of 403. The Typescript Template by default logs the user out when encountering an error status of 403, see here.

Change log