Merge branch 'main' into feature/CCM-13009_update-docs-2

masl2 · web-flow · commit 9305dbebdb7f · 2025-11-24T10:22:08.000Z
diff --git a/.gitignore b/.gitignore
@@ -27,3 +27,4 @@ dist
 /sandbox/*.log
 /sandbox-staging
 /specification/api/components/examples
+/scripts/JWT/*.pem
diff --git a/Makefile b/Makefile
@@ -94,7 +94,7 @@ serve-swagger:
 	npm run serve-swagger-docs
 
 copy-examples:
-	cp -r ./sandbox/data/examples/. ./specification/api/components/examples
+	@scripts/build/copy-examples.sh
 
 config:: _install-dependencies version # Configure development environment (main) @Configuration
 	npm install
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -10,7 +10,7 @@
   },
   "devDependencies": {
     "@openapitools/openapi-generator-cli": "^2.21.4",
-    "@redocly/cli": "^1.34.5",
+    "@redocly/cli": "^2.11.1",
     "@tsconfig/node22": "^22.0.2",
     "@types/jest": "^30.0.0",
     "@types/js-yaml": "^4.0.9",
diff --git a/sandbox/data/examples/createMI/requests/createMI_request_INVALID.json b/sandbox/data/examples/createMI/requests/createMI_request_INVALID.json
diff --git a/sandbox/data/examples/createMI/requests/createMI_request_NOTFOUND.json b/sandbox/data/examples/createMI/requests/createMI_request_NOTFOUND.json
diff --git a/sandbox/data/examples/createMI/requests/createMI_request_SUCCESS.json b/sandbox/data/examples/createMI/requests/createMI_request_SUCCESS.json
diff --git a/sandbox/data/examples/createMI/responses/createMI_response_SUCCESS.json b/sandbox/data/examples/createMI/responses/createMI_response_SUCCESS.json
diff --git a/sandbox/utils/ResponseProvider.js b/sandbox/utils/ResponseProvider.js
@@ -101,9 +101,9 @@ async function postLettersResponse(request) {
 
 async function postMIResponse(request) {
   const postMIFileMap = {
-    'data/examples/createMI/requests/createMI_SUCCESS.json': {responsePath: 'data/examples/createMI/responses/createMI_SUCCESS.json', responseCode: 200},
-    'data/examples/createMI/requests/createMI_INVALID.json': {responsePath:'data/examples/errors/responses/badRequest.json',responseCode: 400},
-    'data/examples/createMI/requests/createMI_NOTFOUND.json': {responsePath:'data/examples/errors/responses/resourceNotFound.json',responseCode: 404},
+    'data/examples/createMI/requests/createMI_request_SUCCESS.json': {responsePath: 'data/examples/createMI/responses/createMI_response_SUCCESS.json', responseCode: 200},
+    'data/examples/createMI/requests/createMI_request_INVALID.json': {responsePath:'data/examples/errors/responses/badRequest.json',responseCode: 400},
+    'data/examples/createMI/requests/createMI_request_NOTFOUND.json': {responsePath:'data/examples/errors/responses/resourceNotFound.json',responseCode: 404},
   };
   return await mapExampleResponse(request, postMIFileMap);
 }
diff --git a/scripts/JWT/README.md b/scripts/JWT/README.md
@@ -0,0 +1,43 @@
+# Environments – Notify Supplier
+
+## Environment Matrix
+
+| Environment Name | Apigee Instance | Proxy URL | Application | Security Level | Private Key | KID | Notes / Env Code |
+|------------------|-----------------|-----------|--------------|----------------|--------------|------|------------------|
+| **Internal dev – PRs** | Internal | internal-dev.api.service.nhs.uk/nhs-notify-supplier-PR-XXX | Notify-Supplier-App-Restricted – Internal Dev 2 | level 0 | — | — | internal-dev PRs |
+| **Internal dev – Main** | Internal | internal-dev.api.service.nhs.uk/nhs-notify-supplier | Notify Supplier – Application Restricted – Internal Dev Main | level 3 | [internal-dev-test-1.pem](https://eu-west-2.console.aws.amazon.com/systems-manager/parameters/%252Fnhs%252Fjwt%252Fkeys%252Finternal-dev-test-1.pem/description?region=eu-west-2&tab=Table) | internal-dev-test-1 | dev |
+| **Ref** | Internal | ref.api.service.nhs.uk/nhs-notify-supplier | Notify Supplier – Application Restricted – Ref | level 3 | [ref-test-1.pem](https://eu-west-2.console.aws.amazon.com/systems-manager/parameters/%252Fnhs%252Fjwt%252Fkeys%252Fref-test-1.pem/description?region=eu-west-2&tab=Table) | ref-test-1 | prod |
+| **Int** | External | int.api.service.nhs.uk/nhs-notify-supplier | Notify Supplier – Integration Testing | level 3 | [int-test-1.pem](https://eu-west-2.console.aws.amazon.com/systems-manager/parameters/%252Fnhs%252Fint%252Fjwt%252Fint-test-1.pem/description?region=eu-west-2&tab=Table) | int-test-1 | int |
+
+---
+
+## How to Get the JWT Access Token
+
+1. Download the private key from AWS Systems Manager and save it locally as `$KID.pem`, for example `ref-test-1.pem`.
+
+2. Get the Apigee API key via one of the following:
+   - [Apigee Edge Console](https://apigee.com/edge)
+   - [Internal developer account](https://onboarding.prod.api.platform.nhs.uk/Index)
+   - [External developer account](https://dos-internal.ptl.api.platform.nhs.uk/Index)
+
+3. Run the Python script `get_bearer_token.py` with the parameters:
+
+   ```bash
+   python get_bearer_token.py --kid <KID> --env <ENVIRONMENT> --appid <APIKEY>
+   ```
+
+   Example:
+
+   ```bash
+   python get_bearer_token.py --kid ref-test-1 --env ref --appid 8Np3gFEw21JX7AGuokId0QEFTaOhG4Z2
+   ```
+
+4. The access token will be returned in the response
+
+5. Add the access token to your API requests as a header:
+
+   | Header Name | Header Value |
+   |--------------|--------------|
+   | Authorization | `Bearer <access token>` |
+
+---
diff --git a/scripts/JWT/get_bearer_token.py b/scripts/JWT/get_bearer_token.py
@@ -0,0 +1,66 @@
+import uuid
+import argparse
+from time import time
+import requests
+import jwt  # https://github.com/jpadilla/pyjwt
+
+ENV_TOKEN_URLS = {
+    "int":  "https://int.api.service.nhs.uk/oauth2/token",
+    "internal-dev":  "https://internal-dev.api.service.nhs.uk/oauth2-mock/token",
+    "prod": "https://api.service.nhs.uk/oauth2/token",
+    "ref": "https://ref.api.service.nhs.uk/oauth2/token",
+}
+
+def main():
+    ap = argparse.ArgumentParser(description="Fetch NHS access token using a signed client assertion (JWT).")
+    ap.add_argument("--kid", required=True,
+                    help="Base name used for both the private key file (<id>.pem) and the JWT header kid.")
+    ap.add_argument("--env", choices=ENV_TOKEN_URLS.keys(), required=True,
+                    help="Environment to hit: int, internal-dev, or prod.")
+    ap.add_argument("--appid", help="Apigee Application ID (used for both sub and iss).")
+    args = ap.parse_args()
+
+    kid = args.kid
+    private_key_file = f"{kid}.pem"
+    token_url = ENV_TOKEN_URLS[args.env]
+
+    with open(private_key_file, "r") as f:
+        private_key = f.read()
+
+    claims = {
+        "sub": args.appid,
+        "iss": args.appid,
+        "jti": str(uuid.uuid4()),
+        "aud": token_url,
+        "exp": int(time()) + 300, # 5mins in the future
+    }
+
+    additional_headers = {"kid": kid}
+
+    signed_jwt = jwt.encode(
+        claims, private_key, algorithm="RS512", headers=additional_headers
+    )
+# ----- 2) Exchange JWT for an access token -----
+    form = {
+        "grant_type": "client_credentials",
+        "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
+        "client_assertion": signed_jwt,
+    }
+
+    resp = requests.post(
+        token_url,
+        headers={"content-type": "application/x-www-form-urlencoded"},
+        data=form,
+        timeout=30,
+    )
+
+    # Raise for non-2xx responses, then print the token payload
+    resp.raise_for_status()
+    token_payload = resp.json()
+
+    print("access_token:", token_payload.get("access_token"))
+    print("expires_in:", token_payload.get("expires_in"))
+    print("token_type:", token_payload.get("token_type"))
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/build/copy-examples.sh b/scripts/build/copy-examples.sh
@@ -0,0 +1,6 @@
+find ./sandbox/data/examples -type f -name '*.json' \
+  | while read f; do \
+    out=./specification/api/components/examples/${f#./sandbox/data/examples/}; \
+    mkdir -p $(dirname $out); \
+    jq '{ value: . }' "$f" > "$out"; \
+  done
diff --git a/scripts/config/vale/styles/config/vocabularies/words/accept.txt b/scripts/config/vale/styles/config/vocabularies/words/accept.txt
@@ -5,15 +5,15 @@ Bitwarden
 bot
 Cognito
 Cyber
+[Dd]ev
 Dependabot
-Dev
 devcontainer
 draw.io
 drawio
+[Ee]nv
 endcapture
 endfor
 endraw
-env
 Git[Hh]ub
 Gitleaks
 Grype
diff --git a/scripts/devcontainer/postcreatecommand.sh b/scripts/devcontainer/postcreatecommand.sh
@@ -8,6 +8,8 @@ source ~/.zshrc
 make _install-dependencies # required before config to ensure python is available due to race between config:: make targets
 make config
 
+pip install --user requests pyjwt cryptography
+
 sudo gem install jekyll bundler
 jekyll --version && cd docs && bundle install
 
diff --git a/specification/api/components/requests/patchLetterRequest.yml b/specification/api/components/requests/patchLetterRequest.yml
@@ -10,53 +10,40 @@ content:
     examples:
       patch-letter-request-default:
         summary: Request for default (PENDING) update
-        value:
-          $ref: ../examples/patchLetter/requests/patchLetter_DEFAULT.json
+        $ref: ../examples/patchLetter/requests/patchLetter_DEFAULT.json
       patch-letter-request-pending:
         summary: Request for PENDING update
-        value:
-          $ref: ../examples/patchLetter/requests/patchLetter_PENDING.json
+        $ref: ../examples/patchLetter/requests/patchLetter_PENDING.json
       patch-letter-request-accepted:
         summary: Request for ACCEPTED update
-        value:
-          $ref: ../examples/patchLetter/requests/patchLetter_ACCEPTED.json
+        $ref: ../examples/patchLetter/requests/patchLetter_ACCEPTED.json
       patch-letter-request-rejected:
         summary: Request for REJECTED update
-        value:
-          $ref: ../examples/patchLetter/requests/patchLetter_REJECTED.json
+        $ref: ../examples/patchLetter/requests/patchLetter_REJECTED.json
       patch-letter-request-printed:
         summary: Request for PRINTED update
-        value:
-          $ref: ../examples/patchLetter/requests/patchLetter_PRINTED.json
+        $ref: ../examples/patchLetter/requests/patchLetter_PRINTED.json
       patch-letter-request-enclosed:
         summary: Request for ENCLOSED update
-        value:
-          $ref: ../examples/patchLetter/requests/patchLetter_ENCLOSED.json
+        $ref: ../examples/patchLetter/requests/patchLetter_ENCLOSED.json
       patch-letter-request-cancelled:
         summary: Request for CANCELLED update
-        value:
-          $ref: ../examples/patchLetter/requests/patchLetter_CANCELLED.json
+        $ref: ../examples/patchLetter/requests/patchLetter_CANCELLED.json
       patch-letter-request-dispatched:
         summary: Request for DISPATCHED update
-        value:
-          $ref: ../examples/patchLetter/requests/patchLetter_DISPATCHED.json
+        $ref: ../examples/patchLetter/requests/patchLetter_DISPATCHED.json
       patch-letter-request-delivered:
         summary: Request for DELIVERED update
-        value:
-          $ref: ../examples/patchLetter/requests/patchLetter_DELIVERED.json
+        $ref: ../examples/patchLetter/requests/patchLetter_DELIVERED.json
       patch-letter-request-failed:
         summary: Request for FAILED update
-        value:
-          $ref: ../examples/patchLetter/requests/patchLetter_FAILED.json
+        $ref: ../examples/patchLetter/requests/patchLetter_FAILED.json
       patch-letter-request-returned:
         summary: Request for RETURNED update
-        value:
-          $ref: ../examples/patchLetter/requests/patchLetter_RETURNED.json
+        $ref: ../examples/patchLetter/requests/patchLetter_RETURNED.json
       patch-letter-request-invalid:
         summary: Request for an invalid update
-        value:
-          $ref: ../examples/patchLetter/requests/patchLetter_INVALID.json
+        $ref: ../examples/patchLetter/requests/patchLetter_INVALID.json
       patch-letter-request-not-found:
         summary: Request for a non existant letter
-        value:
-          $ref: ../examples/patchLetter/requests/patchLetter_NOTFOUND.json
+        $ref: ../examples/patchLetter/requests/patchLetter_NOTFOUND.json
diff --git a/specification/api/components/requests/postLettersRequest.yml b/specification/api/components/requests/postLettersRequest.yml
@@ -11,5 +11,4 @@ content:
             $ref: ../schemas/letterUpdateItem.yml
     examples:
       post-letter-request:
-        value:
-          $ref: ../examples/postLetter/requests/postLetters.json
+        $ref: ../examples/postLetter/requests/postLetters.json
diff --git a/specification/api/components/requests/postMIRequest.yml b/specification/api/components/requests/postMIRequest.yml
@@ -5,13 +5,10 @@ content:
     examples:
       create-mi-request-success:
         summary: Request for successful MI record Creation
-        value:
-          $ref: "../examples/createMI/requests/createMI_SUCCESS.json"
+        $ref: "../examples/createMI/requests/createMI_request_SUCCESS.json"
       create-mi-request-invalid:
         summary: Invalid Request for MI record Creation
-        value:
-          $ref: "../examples/createMI/requests/createMI_INVALID.json"
+        $ref: "../examples/createMI/requests/createMI_request_INVALID.json"
       create-mi-request-notfound:
         summary: Request for MI record Creation for unknown spec
-        value:
-          $ref: "../examples/createMI/requests/createMI_NOTFOUND.json"
+        $ref: "../examples/createMI/requests/createMI_request_NOTFOUND.json"
diff --git a/specification/api/components/responses/errors/badRequest.yml b/specification/api/components/responses/errors/badRequest.yml
@@ -5,5 +5,4 @@ content:
       $ref: "../../schemas/errorResponse.yml"
     examples:
       error-bad-request:
-        value:
-          $ref: ../../examples/errors/responses/badRequest.json
+        $ref: ../../examples/errors/responses/badRequest.json
diff --git a/specification/api/components/responses/errors/listLetters/listLettersBadRequest.yml b/specification/api/components/responses/errors/listLetters/listLettersBadRequest.yml
@@ -5,8 +5,6 @@ content:
       $ref: "../../../schemas/errorResponse.yml"
     examples:
       error-bad-request-unknown-parameter:
-        value:
-          $ref: ../../../examples/errors/responses/getLetter/unknownParameter.json
+        $ref: ../../../examples/errors/responses/getLetter/unknownParameter.json
       error-bad-request-invalid-limit:
-        value:
-          $ref: ../../../examples/errors/responses/getLetter/limitInvalidValue.json
+        $ref: ../../../examples/errors/responses/getLetter/limitInvalidValue.json
diff --git a/specification/api/components/responses/errors/patchLetter/patchLetterBadRequest.yml b/specification/api/components/responses/errors/patchLetter/patchLetterBadRequest.yml
@@ -5,5 +5,4 @@ content:
       $ref: "../../../schemas/errorResponse.yml"
     examples:
       error-bad-request-invalid-request-body:
-        value:
-          $ref: ../../../examples/errors/responses/patchLetter/invalidBody.json
+        $ref: ../../../examples/errors/responses/patchLetter/invalidBody.json
diff --git a/specification/api/components/responses/errors/resourceNotFound.yml b/specification/api/components/responses/errors/resourceNotFound.yml
@@ -5,5 +5,4 @@ content:
       $ref: "../../schemas/errorResponse.yml"
     examples:
       error-not-found:
-        value:
-          $ref: ../../examples/errors/responses/resourceNotFound.json
+        $ref: ../../examples/errors/responses/resourceNotFound.json
diff --git a/specification/api/components/responses/errors/serverError.yml b/specification/api/components/responses/errors/serverError.yml
@@ -5,5 +5,4 @@ content:
       $ref: "../../schemas/errorResponse.yml"
     examples:
       error-server-error:
-        value:
-          $ref: ../../examples/errors/responses/serverError.json
+        $ref: ../../examples/errors/responses/serverError.json
diff --git a/specification/api/components/responses/errors/tooManyRequests.yml b/specification/api/components/responses/errors/tooManyRequests.yml
@@ -5,5 +5,4 @@ content:
       $ref: "../../schemas/errorResponse.yml"
     examples:
       error-too-many-requests:
-        value:
-          $ref: ../../examples/errors/responses/tooManyRequests.json
+        $ref: ../../examples/errors/responses/tooManyRequests.json
diff --git a/specification/api/components/responses/getLetter200.yml b/specification/api/components/responses/getLetter200.yml
@@ -10,5 +10,4 @@ content:
       $ref: "../schemas/letterStatusData.yml"
     examples:
       get-letters:
-        value:
-          $ref: ../examples/getLetter/responses/getLetter-24L5eYSWGzCHlGmzNxuqVusPxDg.json
+        $ref: ../examples/getLetter/responses/getLetter-24L5eYSWGzCHlGmzNxuqVusPxDg.json
diff --git a/specification/api/components/responses/getLetters200.yml b/specification/api/components/responses/getLetters200.yml
@@ -10,5 +10,4 @@ content:
       $ref: "../schemas/lettersListResponse.yml"
     examples:
       get-letters:
-        value:
-          $ref: ../examples/getLetters/responses/getLetters_pending.json
+        $ref: ../examples/getLetters/responses/getLetters_pending.json
diff --git a/specification/api/components/responses/postMI201.yml b/specification/api/components/responses/postMI201.yml
@@ -10,5 +10,4 @@ content:
       $ref: "../schemas/miResponse.yml"
     examples:
       create-mi-response:
-        value:
-          $ref: "../examples/createMI/responses/createMI_SUCCESS.json"
+        $ref: "../examples/createMI/responses/createMI_response_SUCCESS.json"
diff --git a/specification/api/components/security-schemes/security-schemes.yml b/specification/api/components/security-schemes/security-schemes.yml
@@ -1 +1 @@
-$ref: security-schemes-prod.yml
+$ref: security-schemes-internal-dev-pr.yml
diff --git a/specification/api/components/security/security.yml b/specification/api/components/security/security.yml
@@ -1 +1 @@
-$ref: security-prod.yml
+$ref: security-internal-dev-pr.yml
diff --git a/specification/api/components/x-nhsd-apim/access.yml b/specification/api/components/x-nhsd-apim/access.yml
@@ -1 +1 @@
-$ref: access-prod.yml
+$ref: access-internal-dev-pr.yml
diff --git a/specification/api/components/x-nhsd-apim/target-int.yml b/specification/api/components/x-nhsd-apim/target-int.yml
@@ -1,6 +1,6 @@
 type: external
 healthcheck: /_status
-url: https://suppliers.int.nhsnotify.national.nhs.uk
+url: https://main.suppliers.nonprod.nhsnotify.national.nhs.uk
 security:
   type: mtls
-  secret: nhs-notify-supplier-mtls-int
+  secret: notify-supplier-mtls-int
diff --git a/specification/api/components/x-nhsd-apim/target-ref.yml b/specification/api/components/x-nhsd-apim/target-ref.yml
@@ -1,6 +1,6 @@
 type: external
 healthcheck: /_status
-url: https://suppliers.ref.nhsnotify.national.nhs.uk
+url: https://main.suppliers.nonprod.nhsnotify.national.nhs.uk
 security:
   type: mtls
-  secret: nhs-notify-supplier-mtls-ref
+  secret: notify-supplier-mtls-ref
diff --git a/specification/api/components/x-nhsd-apim/target.yml b/specification/api/components/x-nhsd-apim/target.yml
@@ -1 +1 @@
-$ref: target-prod.yml
+$ref: target-internal-dev-pr.yml
