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 a telemetry provider. Provide a client satisfying the TelemetryClient interface that this library exports (requires only a trackEvent method). Compatible with @ministryofjustice/hmpps-azure-telemetry as-is. Compatible with applicationinsights if a wrapper is made to match the interface.
• readOnly: Optional boolean (defaults to false) which, if set to true, will only grant read permissions.

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 %}

To mock permissions in your tests, follow these instructions.

For library developers:

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