New: [AEA-5947] - delegated access (#2147)

## Summary

- ✨ New Feature

### Details

- Adapt expected delegated access headers to Spine API

Author: tstephen-nhs

.devcontainer/devcontainer.json

@@ -35,7 +35,8 @@
         "timonwong.shellcheck",
         "mkhl.direnv",
         "github.vscode-github-actions",
-        "Orta.vscode-jest"
+        "Orta.vscode-jest",
+        "jebbs.plantuml"
       ],
       "settings": {
         "python.defaultInterpreterPath": "/workspaces/prescriptionsforpatients/.venv/bin/python",

docs/pfp-AEA-5947-proxy-access.puml

@@ -0,0 +1,78 @@
+@startuml
+title: AEA-5947: (TO BE) Proxy Access Flow for Get My Prescriptions
+
+participant User
+participant "NHS App" as App
+participant "NHS App Backend" as AppBackend
+participant "Apigee" as Apigee
+participant "ProxyRules" as ProxyRules
+participant "Step Functions StateMachine" as StateMachine
+participant "GetMyPrescriptions Lambda" as GmpLambda
+participant "psu Get Status Updates Lambda" as GsuLambda
+participant "EnrichPrescriptions Lambda" as EpLambda
+participant SpineClient
+participant Spine
+
+User -> App: Request
+App -> AppBackend: Request API
+AppBackend -> Apigee: Call PfP API
+Apigee -> ProxyRules: Forward request
+ProxyRules -> ProxyRules: Preflow
+note right #FF9999
+  Oauth token validation etc. is unchanged
+  NEW: Sets delegated-access.enabled and IgnoreUnresolvedVariables to true
+end note
+ProxyRules -> ProxyRules: AddPatientAccessHeader
+note right
+  Sets NHSD-NHSLogin-User to PX:JWT claim NHS number
+end note
+ProxyRules -> ProxyRules: AM-Add-Delegation-Headers
+note right #FF9999
+  NEW: Sets new headers, completely separate to NHSD-NHSLogin-User 
+end note
+ProxyRules -> ProxyRules: OverridePatientAccessHeader
+note right
+  Overwrites NHSD-NHSLogin-User with P9:request header X-NHS-NUMBER
+end note
+ProxyRules -> StateMachine: Forward request
+StateMachine -> GmpLambda: Forward request
+activate GmpLambda
+GmpLambda -> GmpLambda: adaptHeadersToSpine(headers)
+note right #FF9999
+  As well as the existing behaviour that sends spine the same values for
+  both NHSD-NHSLogin-User (actor) and nhsNumber (subject)
+  these are now separated if delegated-access.enabled is true
+end note
+GmpLambda -> SpineClient: getPrescriptions(*all* headers)
+SpineClient -> Spine: get request
+activate Spine
+Spine -> Spine: _createContext
+note right #FF9999
+  NEW: Add actor to context
+end note
+== other calls, not least the actual query ==
+Spine -> Spine: auditSarAccessRequest
+note right #FF9999
+  NEW: Add actor to SAR0001 log
+end note
+Spine -> SpineClient: Response
+deactivate Spine
+SpineClient -> GmpLambda
+GmpLambda -> StateMachine: Response
+deactivate GmpLambda
+StateMachine -> GsuLambda: Forward response
+GsuLambda -> SpineClient: getStatus(*all* headers)
+SpineClient -> Spine: get request
+Spine -> SpineClient: Response
+SpineClient -> StateMachine: Response
+GsuLambda -> StateMachine: 
+StateMachine -> EpLambda: Forward response
+EpLambda -> StateMachine: 
+StateMachine -> ProxyRules: Response
+note right #FF9999
+  NEW: This is happy path but we must add RaiseFault flow too 
+end note
+ProxyRules -> Apigee: Response
+Apigee -> App: Forward response
+App -> User: Display result
+@enduml

docs/pfp-AS-IS.puml

@@ -0,0 +1,61 @@
+@startuml
+title: AEA-5947: (AS IS) Proxy Access Flow for Get My Prescriptions
+
+participant User
+participant "NHS App" as App
+participant "NHS App Backend" as AppBackend
+participant "Apigee" as Apigee
+participant "ProxyRules" as ProxyRules
+participant "Step Functions StateMachine" as StateMachine
+participant "GetMyPrescriptions Lambda" as GmpLambda
+participant "psu Get Status Updates Lambda" as GsuLambda
+participant "EnrichPrescriptions Lambda" as EpLambda
+participant SpineClient
+participant "Spine Patient Facing Prescriptions" as Spine
+
+User -> App: Request
+App -> AppBackend: Request API
+AppBackend -> Apigee: Call PfP API
+Apigee -> ProxyRules: Forward request
+ProxyRules -> ProxyRules: Preflow
+note right
+  Includes OAuth token validation etc.
+end note
+ProxyRules -> ProxyRules: AddPatientAccessHeader
+note right
+  Sets NHSD-NHSLogin-User to PX:JWT claim NHS number
+end note
+ProxyRules -> ProxyRules: OverridePatientAccessHeader
+note right
+  Overwrites NHSD-NHSLogin-User with P9:request header X-NHS-NUMBER
+  TODO who sets X-NHS-NUMBER? Is it trusted?
+  TODO given this is within an Azure pipeline condition does it ever get called?
+end note
+ProxyRules -> StateMachine: Forward request
+StateMachine -> GmpLambda: Forward request
+activate GmpLambda
+GmpLambda -> GmpLambda: extractNHSNumber(headers["nhsd-nhslogin-user"])
+GmpLambda -> SpineClient: getPrescriptions(*all* headers)
+SpineClient -> Spine: get request
+activate Spine
+Spine -> Spine: _createContext
+== other calls, not least the actual query ==
+Spine -> Spine: auditSarAccessRequest
+Spine -> SpineClient: Response
+deactivate Spine
+SpineClient -> GmpLambda
+GmpLambda -> StateMachine: Response
+deactivate GmpLambda
+StateMachine -> GsuLambda: Forward response
+GsuLambda -> SpineClient: getStatus(*all* headers)
+SpineClient -> Spine: get request
+Spine -> SpineClient: Response
+SpineClient -> StateMachine: Response
+GsuLambda -> StateMachine: 
+StateMachine -> EpLambda: Forward response
+EpLambda -> StateMachine: 
+StateMachine -> ProxyRules: Response
+ProxyRules -> Apigee: Response
+Apigee -> App: Forward response
+App -> User: Display result
+@enduml

packages/getMyPrescriptions/src/extractNHSNumber.ts

@@ -20,6 +20,10 @@ export function extractNHSNumber(nhsloginUser: string | undefined): string {
   if (authLevel !== "P9") {
     throw new NHSNumberValidationError("Identity proofing level is not P9")
   }
+  return validateNHSNumber(nhsNumber)
+}
+
+export function validateNHSNumber(nhsNumber: string): string {
   // convert numbers to strings, for internal consistency
   if (Number.isInteger(nhsNumber)) {
     nhsNumber = nhsNumber.toString()
@@ -42,7 +46,7 @@ export function extractNHSNumber(nhsloginUser: string | undefined): string {
 
   // Do the check digits match?
   if (checkDigit !== Number(providedCheckDigit)) {
-    throw new NHSNumberValidationError("invalid check digit in NHS number")
+    throw new NHSNumberValidationError(`Invalid check digit in NHS number ${nhsNumber}`)
   }
   return nhsNumber
 }

packages/getMyPrescriptions/src/getMyPrescriptions.ts

@@ -23,7 +23,7 @@ import {
   TraceIDs,
   ResponseFunc
 } from "./responses"
-import {extractNHSNumber, NHSNumberValidationError} from "./extractNHSNumber"
+import {extractNHSNumber, NHSNumberValidationError, validateNHSNumber} from "./extractNHSNumber"
 import {deepCopy, hasTimedOut, jobWithTimeout} from "./utils"
 import {buildStatusUpdateData, shouldGetStatusUpdates} from "./statusUpdate"
 import {extractOdsCodes, isolateOperationOutcome} from "./fhirUtils"
@@ -38,6 +38,8 @@ const servicesCache: ServicesCache = {}
 const LAMBDA_TIMEOUT_MS = 10_000
 const SPINE_TIMEOUT_MS = 9_000
 const SERVICE_SEARCH_TIMEOUT_MS = 5_000
+export const DELEGATED_ACCESS_HDR = "delegatedaccess"
+export const DELEGATED_ACCESS_SUB_HDR = "x-nhsd-subject-nhs-number"
 
 type EventHeaders = Record<string, string | undefined>
 
@@ -75,19 +77,16 @@ async function eventHandler(
   successResponse: ResponseFunc,
   includeStatusUpdateData: boolean = false
 ): Promise<LambdaResult> {
-  const xRequestId = headers["x-request-id"]
-  const requestId = headers["apigw-request-id"]
-  const spineClient = params.spineClient
-
   const traceIDs: TraceIDs = {
     "nhsd-correlation-id": headers["nhsd-correlation-id"],
-    "x-request-id": xRequestId,
+    "x-request-id": headers["x-request-id"],
     "nhsd-request-id": headers["nhsd-request-id"],
     "x-correlation-id": headers["x-correlation-id"],
-    "apigw-request-id": requestId
+    "apigw-request-id": headers["apigw-request-id"]
   }
   logger.appendKeys(traceIDs)
 
+  const spineClient = params.spineClient
   const applicationName = headers["nhsd-application-name"] ?? "unknown"
 
   try {
@@ -96,10 +95,8 @@ async function eventHandler(
       return SPINE_CERT_NOT_CONFIGURED_RESPONSE
     }
 
-    const nhsNumber = extractNHSNumber(headers["nhsd-nhslogin-user"])
-    logger.info(`nhsNumber: ${nhsNumber}`, {nhsNumber})
-    headers["nhsNumber"] = nhsNumber
-    if (await params.pfpConfig.isTC008(nhsNumber)) {
+    headers = adaptHeadersToSpine(headers)
+    if (await params.pfpConfig.isTC008(headers["nhsNumber"]!)) {
       logger.info("Test NHS number corresponding to TC008 has been received. Returning a 500 response")
       return TC008_ERROR_RESPONSE
     }
@@ -111,7 +108,7 @@ async function eventHandler(
       return TIMEOUT_RESPONSE
     }
     const searchsetBundle: Bundle = response.data
-    searchsetBundle.id = xRequestId
+    searchsetBundle.id = traceIDs["x-request-id"] || "unknown"
 
     const operationOutcomes = isolateOperationOutcome(searchsetBundle)
     operationOutcomes.forEach((operationOutcome) => {
@@ -124,7 +121,8 @@ async function eventHandler(
       + "They have these relevant ODS codes, and the PfP request was made via this apigee application.",
       {
         ODSCodes,
-        nhsNumber,
+        actorNhsNumber: headers["nhsd-nhslogin-user"],
+        subjectNhsNumber: headers["nhsNumber"],
         applicationName
       }
     )
@@ -141,10 +139,15 @@ async function eventHandler(
         timeout: SERVICE_SEARCH_TIMEOUT_MS,
         message: `The request to the distance selling service timed out after ${SERVICE_SEARCH_TIMEOUT_MS}ms.`
       })
-      return await successResponse(logger, nhsNumber, searchsetBundle, traceIDs, params.pfpConfig, statusUpdateData)
+      return await successResponse(
+        logger, headers["nhsNumber"]!, searchsetBundle, traceIDs, params.pfpConfig, statusUpdateData
+      )
     }
 
-    return await successResponse(logger, nhsNumber, distanceSellingBundle, traceIDs, params.pfpConfig, statusUpdateData)
+    return await successResponse(
+      logger, headers["nhsNumber"]!, distanceSellingBundle, traceIDs,
+      params.pfpConfig, statusUpdateData
+    )
   } catch (error) {
     if (error instanceof NHSNumberValidationError) {
       return INVALID_NHS_NUMBER_RESPONSE
@@ -154,6 +157,28 @@ async function eventHandler(
   }
 }
 
+export function adaptHeadersToSpine(headers: EventHeaders): EventHeaders {
+  // AEA-3344 introduces delegated access using different headers
+  logger.debug("Testing if delegated access enabled", {headers})
+  if (!headers[DELEGATED_ACCESS_HDR] || headers[DELEGATED_ACCESS_HDR].toLowerCase() !== "true") {
+    logger.info("Subject access request detected")
+    headers["nhsNumber"] = extractNHSNumber(headers["nhsd-nhslogin-user"])
+  } else {
+    logger.info("Delegated access request detected")
+    let subjectNHSNumber = headers[DELEGATED_ACCESS_SUB_HDR]
+    if (!subjectNHSNumber) {
+      throw new NHSNumberValidationError(`${DELEGATED_ACCESS_SUB_HDR} header not present for delegated access`)
+    }
+    if (subjectNHSNumber.indexOf(":") > -1) {
+      logger.warn(`${DELEGATED_ACCESS_SUB_HDR} is not expected to be prefixed by proofing level, but is, removing it`)
+      subjectNHSNumber = subjectNHSNumber.split(":")[1]
+    }
+    headers["nhsNumber"] = validateNHSNumber(subjectNHSNumber)
+  }
+  logger.info(`after setting subject nhsNumber`, {headers})
+  return headers
+}
+
 type HandlerConfig<T> = {
   handlerFunction: (event: T, config: HandlerParams) => Promise<LambdaResult>
   middleware: Array<middy.MiddlewareObj>