@ministryofjustice/hmpps-prison-permissions-lib 0.0.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Change log
 
-## 0.0.1-alpha.1 to 0.0.1-alpha.3
+Please use this to capture reasoning behind changes:
 
-Pre-releases used sparingly in the prisoner profile for testing.
+## 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.

package/README.md

@@ -69,7 +69,8 @@ The permissions service should be created just like any other of your services.
 
 * `prisonerSearchConfig`: [Prisoner Search](https://github.com/ministryofjustice/hmpps-prisoner-search) configuration
   conforming to the `hmpps-typescript-lib`'
-  s `ApiConfig` [interface](https://github.com/ministryofjustice/hmpps-typescript-lib/blob/main/packages/rest-client/src/main/types/ApiConfig.ts)
+  s
+  `ApiConfig` [interface](https://github.com/ministryofjustice/hmpps-typescript-lib/blob/main/packages/rest-client/src/main/types/ApiConfig.ts)
 * `authenticationClient`: An `AuthenticationClient` instance (
   see [hmpps-typescript-lib](https://github.com/ministryofjustice/hmpps-typescript-lib/blob/main/packages/auth-clients/src/main/AuthenticationClient.ts))
   in order to make authorized client credentials calls to Prisoner Search.
@@ -121,7 +122,35 @@ throw a `PrisonerPermissionError` with a status code of 403. The Typescript Temp
 out when encountering an error status of 403,
 see [here](https://github.com/ministryofjustice/hmpps-template-typescript/blob/main/server/errorHandler.ts#L9).
 
+#### 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:
+
+```js
+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:
+
+```js
+// 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](readme/publishing.md)
 2. [Contributing to permissions](readme/contributing.md)
+3. [Versioning guidance](readme/versioning.md)

package/dist/contractTests/contactsUi/scenarios/InUsersCaseLoadAndUserHasRoleScenarios.d.ts

@@ -0,0 +1,2 @@
+import { Role } from '../../../types/internal/user/Role';
+export default function inUsersCaseLoadAndUserHasRoleScenarios(role: Role): import("../../../testUtils/TestScenario").TestScenarios;

package/dist/contractTests/contactsUi/scenarios/InUsersCaseLoadAndUserHasSomeRolesFromScenarios.d.ts

@@ -0,0 +1,3 @@
+import { Role } from '../../../types/internal/user/Role';
+import { TestScenarios } from '../../../testUtils/TestScenario';
+export default function inUsersCaseLoadAndUserHasSomeRolesFromScenarios(roles: Role[]): TestScenarios;

package/dist/contractTests/contactsUi/scenarios/baseCheck/BaseCheckScenarios.d.ts

@@ -0,0 +1,13 @@
+import { TestScenarios } from '../../../../testUtils/TestScenario';
+export declare const deniedRestrictedPatientCheckScenarios: TestScenarios;
+export declare const grantedRestrictedPatientCheckScenarios: TestScenarios;
+export declare const deniedReleasedPrisonerCheckScenarios: TestScenarios;
+export declare const grantedReleasedPrisonerCheckScenarios: TestScenarios;
+export declare const deniedTransferringPrisonerCheckScenarios: TestScenarios;
+export declare const grantedTransferringPrisonerCheckScenarios: TestScenarios;
+export declare const deniedCaseLoadCheckScenarios: TestScenarios;
+export declare const grantedCaseLoadCheckScenarios: TestScenarios;
+export declare const grantedGlobalSearchCheckScenarios: TestScenarios;
+export declare const deniedBaseCheckScenarios: TestScenarios;
+export declare const grantedBaseCheckScenarios: TestScenarios;
+export declare const baseCheckScenarios: TestScenarios;

package/dist/contractTests/prisonerProfile/scenarios/shared/InActiveCaseLoadAndUserHasSomeRolesFromScenarios.d.ts

@@ -0,0 +1,3 @@
+import { Role } from '../../../../types/internal/user/Role';
+import { TestScenarios } from '../../../../testUtils/TestScenario';
+export default function inActiveCaseLoadAndUserHasSomeRolesFromScenarios(roles: Role[]): TestScenarios;

package/dist/contractTests/prisonerProfile/scenarios/shared/InActiveCaseLoadScenarios.d.ts

@@ -0,0 +1 @@
+export declare const inActiveCaseLoadScenarios: import("../../../../testUtils/TestScenario").TestScenarios;

package/dist/contractTests/prisonerProfile/scenarios/shared/InUsersCaseLoadAndUserHasRoleScenarios.d.ts

@@ -0,0 +1,2 @@
+import { Role } from '../../../../types/internal/user/Role';
+export default function inUsersCaseLoadAndUserHasRoleScenarios(role: Role): import("../../../../testUtils/TestScenario").TestScenarios;

package/dist/contractTests/prisonerProfile/scenarios/shared/InUsersCaseLoadAndUserHasSomeRolesFromScenarios.d.ts

@@ -0,0 +1,3 @@
+import { Role } from '../../../../types/internal/user/Role';
+import { TestScenarios } from '../../../../testUtils/TestScenario';
+export default function inUsersCaseLoadAndUserHasSomeRolesFromScenarios(roles: Role[]): TestScenarios;

package/dist/contractTests/prisonerProfile/scenarios/shared/InUsersCaseLoadScenarios.d.ts

@@ -0,0 +1,2 @@
+import { TestScenarios } from '../../../../testUtils/TestScenario';
+export declare const inUsersCaseLoadScenarios: TestScenarios;

package/dist/contractTests/prisonerProfile/scenarios/shared/PrisonerProfileSensitiveEditCheckScenarios.d.ts

@@ -1,2 +1 @@
-import { TestScenarios } from '../../../../testUtils/TestScenario';
-export declare const prisonerProfileSensitiveEditCheckScenarios: TestScenarios;
+export declare const prisonerProfileSensitiveEditCheckScenarios: import("../../../../testUtils/TestScenario").TestScenarios;

package/dist/index.cjs

@@ -68,6 +68,8 @@ exports.Role = void 0;
     Role["ApproveCategorisation"] = "ROLE_APPROVE_CATEGORISATION";
     Role["CategorisationSecurity"] = "ROLE_CATEGORISATION_SECURITY";
     Role["CellMove"] = "ROLE_CELL_MOVE";
+    Role["ContactsAdministrator"] = "ROLE_CONTACTS_ADMINISTRATOR";
+    Role["ContactsAuthoriser"] = "ROLE_CONTACTS_AUTHORISER";
     Role["CreateCategorisation"] = "ROLE_CREATE_CATEGORISATION";
     Role["CreateRecategorisation"] = "ROLE_CREATE_RECATEGORISATION";
     Role["DeleteSensitiveCaseNotes"] = "ROLE_DELETE_SENSITIVE_CASE_NOTES";
@@ -84,6 +86,7 @@ exports.Role = void 0;
     Role["PathfinderStdProbation"] = "ROLE_PF_STD_PROBATION";
     Role["PathfinderUser"] = "ROLE_PF_USER";
     Role["PomUser"] = "ROLE_POM";
+    Role["PrisonerProfilePhotoUpload"] = "ROLE_PRISONER_PROFILE_PHOTO_UPLOAD";
     Role["PrisonerProfileSensitiveEdit"] = "ROLE_PRISONER_PROFILE_SENSITIVE_RW";
     Role["ReceptionUser"] = "ROLE_PRISON_RECEPTION";
     Role["ReleaseDatesCalculator"] = "ROLE_RELEASE_DATES_CALCULATOR";
@@ -232,7 +235,7 @@ exports.PrisonerMoneyPermission = void 0;
     PrisonerMoneyPermission["read"] = "prisoner:prisoner-money:read";
 })(exports.PrisonerMoneyPermission || (exports.PrisonerMoneyPermission = {}));
 
-function baseCheckAndInUsersCaseLoad(permission, request) {
+function inUsersCaseLoad(permission, request) {
     const { user, prisoner, baseCheckStatus } = request;
     const baseCheckPassed = baseCheckStatus === exports.PermissionCheckStatus.OK;
     const check = baseCheckPassed && isInUsersCaseLoad(prisoner.prisonId, user);
@@ -242,7 +245,7 @@ function baseCheckAndInUsersCaseLoad(permission, request) {
 }
 
 function prisonerMoneyReadCheck(request) {
-    return baseCheckAndInUsersCaseLoad(exports.PrisonerMoneyPermission.read, request);
+    return inUsersCaseLoad(exports.PrisonerMoneyPermission.read, request);
 }
 
 function prisonerMoneyCheck(request) {
@@ -441,7 +444,7 @@ exports.PrisonerVisitsAndVisitorsPermission = void 0;
 })(exports.PrisonerVisitsAndVisitorsPermission || (exports.PrisonerVisitsAndVisitorsPermission = {}));
 
 function prisonerVisitsAndVisitorsReadCheck(request) {
-    return baseCheckAndInUsersCaseLoad(exports.PrisonerVisitsAndVisitorsPermission.read, request);
+    return inUsersCaseLoad(exports.PrisonerVisitsAndVisitorsPermission.read, request);
 }
 
 function prisonerVisitsAndVisitorsCheck(request) {
@@ -624,28 +627,31 @@ exports.CorePersonRecordPermission = void 0;
     CorePersonRecordPermission["edit_distinguishing_marks"] = "prisoner:distinguishing-marks:edit";
 })(exports.CorePersonRecordPermission || (exports.CorePersonRecordPermission = {}));
 
-function baseCheckAndInActiveCaseLoad(permission, request) {
+function inActiveCaseLoadAndUserHasSomeRolesFrom(roles, permission, request) {
     const { user, prisoner, baseCheckStatus } = request;
     const baseCheckPassed = baseCheckStatus === exports.PermissionCheckStatus.OK;
-    const check = baseCheckPassed && isActiveCaseLoad(prisoner.prisonId, user);
+    const inActiveCaseLoad = isActiveCaseLoad(prisoner.prisonId, user);
+    const hasRole = userHasSomeRolesFrom(roles, user);
+    const check = baseCheckPassed && inActiveCaseLoad && hasRole;
     if (!check)
-        logDeniedPermissionCheck(permission, request, exports.PermissionCheckStatus.NOT_ACTIVE_CASELOAD);
+        logDeniedPermissionCheck(permission, request, inActiveCaseLoad ? exports.PermissionCheckStatus.ROLE_NOT_PRESENT : exports.PermissionCheckStatus.NOT_ACTIVE_CASELOAD);
     return check;
 }
 
+function inActiveCaseLoad(permission, request) {
+    return inActiveCaseLoadAndUserHasSomeRolesFrom([], permission, request);
+}
+
 function prisonerProfileEditCheck(permission, request) {
-    return baseCheckAndInActiveCaseLoad(permission, request);
+    return inActiveCaseLoad(permission, request);
+}
+
+function inActiveCaseLoadAndUserHasRole(role, permission, request) {
+    return inActiveCaseLoadAndUserHasSomeRolesFrom([role], permission, request);
 }
 
 function prisonerProfileSensitiveEditCheck(permission, request) {
-    const { user, prisoner, baseCheckStatus } = request;
-    const baseCheckPassed = baseCheckStatus === exports.PermissionCheckStatus.OK;
-    const inActiveCaseLoad = isActiveCaseLoad(prisoner.prisonId, user);
-    const hasRole = userHasRole(exports.Role.PrisonerProfileSensitiveEdit, user);
-    const check = baseCheckPassed && inActiveCaseLoad && hasRole;
-    if (!check)
-        logDeniedPermissionCheck(permission, request, inActiveCaseLoad ? exports.PermissionCheckStatus.ROLE_NOT_PRESENT : exports.PermissionCheckStatus.NOT_ACTIVE_CASELOAD);
-    return check;
+    return inActiveCaseLoadAndUserHasRole(exports.Role.PrisonerProfileSensitiveEdit, permission, request);
 }
 
 const permission$2 = exports.CorePersonRecordPermission.read_photo;
@@ -680,7 +686,7 @@ function checkPhotoAccess(request) {
 function corePersonRecordCheck(request) {
     return {
         [exports.CorePersonRecordPermission.read_photo]: photoReadCheck(request),
-        ...sensitiveEditCheck$2(exports.CorePersonRecordPermission.edit_photo, request),
+        [exports.CorePersonRecordPermission.edit_photo]: inActiveCaseLoadAndUserHasSomeRolesFrom([exports.Role.PrisonerProfileSensitiveEdit, exports.Role.PrisonerProfilePhotoUpload], exports.CorePersonRecordPermission.edit_photo, request),
         ...readCheck$4(exports.CorePersonRecordPermission.read_physical_characteristics, request),
         ...editCheck$4(exports.CorePersonRecordPermission.edit_physical_characteristics, request),
         ...readCheck$4(exports.CorePersonRecordPermission.read_place_of_birth, request),
@@ -757,14 +763,7 @@ exports.PersonHealthAndMedicationPermission = void 0;
 
 const permission$1 = exports.PersonHealthAndMedicationPermission.edit_diet;
 function dietEditCheck(request) {
-    const { user, prisoner, baseCheckStatus } = request;
-    const baseCheckPassed = baseCheckStatus === exports.PermissionCheckStatus.OK;
-    const inActiveCaseLoad = isActiveCaseLoad(prisoner.prisonId, user);
-    const hasRole = userHasRole(exports.Role.DietAndAllergiesEdit, user);
-    const check = baseCheckPassed && inActiveCaseLoad && hasRole;
-    if (!check)
-        logDeniedPermissionCheck(permission$1, request, inActiveCaseLoad ? exports.PermissionCheckStatus.ROLE_NOT_PRESENT : exports.PermissionCheckStatus.NOT_ACTIVE_CASELOAD);
-    return check;
+    return inActiveCaseLoadAndUserHasRole(exports.Role.DietAndAllergiesEdit, permission$1, request);
 }
 
 function personHealthAndMedicationCheck(request) {
@@ -786,23 +785,49 @@ function editCheck$2(permission, request) {
 
 exports.PersonalRelationshipsPermission = void 0;
 (function (PersonalRelationshipsPermission) {
-    // Next of kin & emergency contacts
-    PersonalRelationshipsPermission["read_emergency_contacts"] = "prisoner:emergency-contacts:read";
-    PersonalRelationshipsPermission["edit_emergency_contacts"] = "prisoner:emergency-contacts:edit";
     PersonalRelationshipsPermission["read_number_of_children"] = "prisoner:number-of-children:read";
     PersonalRelationshipsPermission["edit_number_of_children"] = "prisoner:number-of-children:edit";
     PersonalRelationshipsPermission["read_domestic_status"] = "prisoner:domestic-status:read";
     PersonalRelationshipsPermission["edit_domestic_status"] = "prisoner:domestic-status:edit";
+    // Next of kin & emergency contacts (via prisoner profile)
+    // This needs a review once both the contacts service and the
+    // profile edit have been rolled out wider:
+    PersonalRelationshipsPermission["read_emergency_contacts"] = "prisoner:emergency-contacts:read";
+    PersonalRelationshipsPermission["edit_emergency_contacts"] = "prisoner:emergency-contacts:edit";
+    // All social and official contacts:
+    PersonalRelationshipsPermission["read_contacts"] = "prisoner:contacts:read";
+    PersonalRelationshipsPermission["edit_contacts"] = "prisoner:contacts:edit";
+    PersonalRelationshipsPermission["edit_contact_restrictions"] = "prisoner:contact-restrictions:edit";
+    PersonalRelationshipsPermission["edit_contact_visit_approval"] = "prisoner:contact-visit-approval:edit";
 })(exports.PersonalRelationshipsPermission || (exports.PersonalRelationshipsPermission = {}));
 
+function inUsersCaseLoadAndUserHasSomeRolesFrom(roles, permission, request) {
+    const { user, prisoner, baseCheckStatus } = request;
+    const baseCheckPassed = baseCheckStatus === exports.PermissionCheckStatus.OK;
+    const inUsersCaseLoad = isInUsersCaseLoad(prisoner.prisonId, user);
+    const hasRole = userHasSomeRolesFrom(roles, user);
+    const check = baseCheckPassed && inUsersCaseLoad && hasRole;
+    if (!check)
+        logDeniedPermissionCheck(permission, request, inUsersCaseLoad ? exports.PermissionCheckStatus.ROLE_NOT_PRESENT : exports.PermissionCheckStatus.NOT_IN_CASELOAD);
+    return check;
+}
+
+function inUsersCaseLoadAndUserHasRole(role, permission, request) {
+    return inUsersCaseLoadAndUserHasSomeRolesFrom([role], permission, request);
+}
+
 function personalRelationshipsCheck(request) {
     return {
-        ...readCheck$1(exports.PersonalRelationshipsPermission.read_emergency_contacts, request),
-        ...sensitiveEditCheck(exports.PersonalRelationshipsPermission.edit_emergency_contacts, request),
         ...readCheck$1(exports.PersonalRelationshipsPermission.read_number_of_children, request),
         ...editCheck$1(exports.PersonalRelationshipsPermission.edit_number_of_children, request),
         ...readCheck$1(exports.PersonalRelationshipsPermission.read_domestic_status, request),
         ...editCheck$1(exports.PersonalRelationshipsPermission.edit_domestic_status, request),
+        ...readCheck$1(exports.PersonalRelationshipsPermission.read_emergency_contacts, request),
+        ...sensitiveEditCheck(exports.PersonalRelationshipsPermission.edit_emergency_contacts, request),
+        [exports.PersonalRelationshipsPermission.read_contacts]: inUsersCaseLoad(exports.PersonalRelationshipsPermission.read_contacts, request),
+        [exports.PersonalRelationshipsPermission.edit_contacts]: inUsersCaseLoadAndUserHasSomeRolesFrom([exports.Role.ContactsAdministrator, exports.Role.ContactsAuthoriser], exports.PersonalRelationshipsPermission.edit_contacts, request),
+        [exports.PersonalRelationshipsPermission.edit_contact_restrictions]: inUsersCaseLoadAndUserHasRole(exports.Role.ContactsAuthoriser, exports.PersonalRelationshipsPermission.edit_contact_restrictions, request),
+        [exports.PersonalRelationshipsPermission.edit_contact_visit_approval]: inUsersCaseLoadAndUserHasRole(exports.Role.ContactsAuthoriser, exports.PersonalRelationshipsPermission.edit_contact_visit_approval, request),
     };
 }
 function readCheck$1(permission, request) {
@@ -944,7 +969,7 @@ exports.PersonInterventionsPermission = void 0;
 })(exports.PersonInterventionsPermission || (exports.PersonInterventionsPermission = {}));
 
 function csipReadCheck(request) {
-    return baseCheckAndInUsersCaseLoad(exports.PersonInterventionsPermission.read_csip, request);
+    return inUsersCaseLoad(exports.PersonInterventionsPermission.read_csip, request);
 }
 
 function personInterventionsCheck(request) {
@@ -1175,12 +1200,16 @@ const personHealthAndMedicationPermissionPaths = {
 const basePath$1 = 'domainGroups.person.personalRelationships';
 // eslint-disable-next-line import/prefer-default-export
 const personalRelationshipsPermissionPaths = {
-    [exports.PersonalRelationshipsPermission.read_emergency_contacts]: `${basePath$1}.${exports.PersonalRelationshipsPermission.read_emergency_contacts}`,
-    [exports.PersonalRelationshipsPermission.edit_emergency_contacts]: `${basePath$1}.${exports.PersonalRelationshipsPermission.edit_emergency_contacts}`,
     [exports.PersonalRelationshipsPermission.read_number_of_children]: `${basePath$1}.${exports.PersonalRelationshipsPermission.read_number_of_children}`,
     [exports.PersonalRelationshipsPermission.edit_number_of_children]: `${basePath$1}.${exports.PersonalRelationshipsPermission.edit_number_of_children}`,
     [exports.PersonalRelationshipsPermission.read_domestic_status]: `${basePath$1}.${exports.PersonalRelationshipsPermission.read_domestic_status}`,
     [exports.PersonalRelationshipsPermission.edit_domestic_status]: `${basePath$1}.${exports.PersonalRelationshipsPermission.edit_domestic_status}`,
+    [exports.PersonalRelationshipsPermission.read_contacts]: `${basePath$1}.${exports.PersonalRelationshipsPermission.read_contacts}`,
+    [exports.PersonalRelationshipsPermission.edit_contacts]: `${basePath$1}.${exports.PersonalRelationshipsPermission.edit_contacts}`,
+    [exports.PersonalRelationshipsPermission.edit_contact_restrictions]: `${basePath$1}.${exports.PersonalRelationshipsPermission.edit_contact_restrictions}`,
+    [exports.PersonalRelationshipsPermission.edit_contact_visit_approval]: `${basePath$1}.${exports.PersonalRelationshipsPermission.edit_contact_visit_approval}`,
+    [exports.PersonalRelationshipsPermission.read_emergency_contacts]: `${basePath$1}.${exports.PersonalRelationshipsPermission.read_emergency_contacts}`,
+    [exports.PersonalRelationshipsPermission.edit_emergency_contacts]: `${basePath$1}.${exports.PersonalRelationshipsPermission.edit_emergency_contacts}`,
 };
 
 // eslint-disable-next-line import/prefer-default-export