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?
5. For library developers

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 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 retrieve data about a prisoner from hmpps-prisoner-search and store it at req.middleware.prisonerData if it is not already provided there.

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:

• 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({
  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.

6. Make use of the permissions checking utility in your code

You can check if a particular permission is granted in your code simply by using the isGranted method, for example:

isGranted(PrisonerMoneyPermission.read, res.locals.prisonerPermissions)

7. Make use of the permissions checking utility directly in your nunjucks templates

You also can check permissions directly in nunjucks templates by:

• Configuring the nunjucks environment in your nunjucksSetup.ts file or equivalent:

// Enable permissions checking in templates:
setupNunjucksPermissions(njkEnv)

• Using the permissions check in the template, for example:

{% if isGranted(PrisonerMoneyPermission.read, res.locals.prisonerPermissions) %}
 ...
{% endif %}

For library developers:

1. Publishing to NPM
2. Contributing to permissions
3. Versioning guidance

Change log

Please use this to capture reasoning behind changes:

0.2.0

Incident response. We are introducing an additional role enabling staff to upload photos via DPS.

This is in addition to the existing sensitive edit role to allow rollout of the feature independently of Prisoner Profile edit.

0.1.0

Additional personal relationships (contacts) permissions introduced to enable hmpps-contacts-ui to make use of the library and for the Prisoner Profile and the Contacts UI to align on whether a user has access to a prisoner's contacts.

Connect DPS and the Contacts team have agreed to allow contacts read permission for anyone with the prisoner's prison in their caseload (rather than requiring an active caseload match as was initially implemented in the Contacts UI). Contacts, restrictions and visit approval edits adopt the same role checks as were implemented in the Contacts UI codebase.

We are keeping the divergence between the rules around editing Next of Kin and Emergency Contacts via the prisoner profile for now to enable the Profile Edit and Contacts to role out to users independently, but we will aim to unify these permissions once both rollouts are complete.

0.0.1

Initial release supporting the Prisoner Profile permissions.

0.0.1-alpha.1 to 0.0.1-alpha.15

Pre-releases used to incrementally replace the prisoner profile permissions logic.