CCM-24047: added mTLS instructions for client callbacks

Makefile

@@ -78,6 +78,14 @@ serve:
 	(sleep 5; python3 -m webbrowser http://127.0.0.1:5000) &
 	npm run serve
 
+#Serve the OAS specification with live reload on source edits
+serve-watch:
+	npm run publish
+	npm run watch & WATCH_PID=$$!; \
+	trap "kill $$WATCH_PID 2>/dev/null" EXIT INT TERM; \
+	(sleep 5; python3 -m webbrowser http://127.0.0.1:5000) & \
+	npm run serve
+
 #Check dependencies for licensing issues
 .check-licenses:
 	npm run check-licenses

README.md

@@ -108,6 +108,7 @@ There are `make` commands that alias some of this functionality:
 * `lint` -- Lints the spec and code
 * `publish` -- Outputs the specification as a **single file** into the `build/` directory
 * `serve` -- Serves a preview of the specification in human-readable format - your browser will automatically open the documentation
+* `serve-watch` -- Serves a preview of the specification in human-readable format that is updated as you make changes
 * `build-test-documentation` -- Builds the test documentation that is checked into the repository under `docs/tests`
 
 ## Testing

package.json

@@ -5,8 +5,9 @@
   "sourceType": "module",
   "scripts": {
     "lint": "redocly lint specification/communications-manager.yaml",
-    "publish": "mkdir -p build && redocly bundle specification/communications-manager.yaml --dereferenced --remove-unused-components --ext json | poetry run python scripts/set_version.py > build/communications-manager.json",
+    "publish": "mkdir -p build && redocly bundle specification/communications-manager.yaml --dereferenced --remove-unused-components --ext json | poetry run python scripts/set_version.py | poetry run python scripts/inline_assets.py > build/communications-manager.json.tmp && mv build/communications-manager.json.tmp build/communications-manager.json",
     "serve": "redocly preview-docs -p 5000 build/communications-manager.json",
+    "watch": "nodemon --watch specification --ext yaml,md,json --ignore build --exec \"npm run publish\"",
     "check-licenses": "node_modules/.bin/license-checker --failOn GPL --failOn LGPL --failOn AGPL",
     "sandbox-postman-collection": "newman run postman/NhsNotify.Sandbox.postman_collection.json",
     "integration-postman-collection": "poetry run python scripts/build_postman_environment.py && newman run postman/NhsNotify.Integration.postman_collection.json -e postman/Integration.test.postman_environment.json",
@@ -46,6 +47,7 @@
     "license-checker": "^25.0.1",
     "minimist": "^1.2.2",
     "newman": "^6.2.2",
+    "nodemon": "^3.1.0",
     "sinon": "^17.0.1",
     "typescript": "^5.5.4"
   },

scripts/inline_assets.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""
+inline_assets.py
+
+Reads an openapi spec on stdin, replaces asset tokens with base64 `data:`
+URIs so documentation download links are self-contained (no external
+hosting), then prints the spec on stdout.
+"""
+import sys
+import os
+import json
+import base64
+
+# Maps a token found in the spec (typically within info.description) to the
+# repo-relative asset whose base64-encoded contents replace it at build time.
+ASSET_TOKENS = {
+    "{{NONPROD_CA_B64}}": "specification/documentation/certs/nonprod-ca.crt",
+    "{{PROD_CA_B64}}": "specification/documentation/certs/prod-ca.crt",
+}
+
+
+def _repo_root():
+    return os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+
+
+def embed_inline_assets(spec):
+    """Replace asset tokens anywhere in the spec with base64 of the asset.
+
+    A token is only resolved if it is present in the serialised spec. If a
+    referenced asset file is missing, the build fails loudly.
+    """
+    serialised = json.dumps(spec)
+    for token, rel_path in ASSET_TOKENS.items():
+        if token not in serialised:
+            continue
+        path = os.path.join(_repo_root(), rel_path)
+        with open(path, "rb") as asset:
+            encoded = base64.b64encode(asset.read()).decode("ascii")
+        serialised = serialised.replace(token, encoded)
+    return json.loads(serialised)
+
+
+def main():
+    """Main entrypoint"""
+    data = json.loads(sys.stdin.read())
+    data = embed_inline_assets(data)
+    sys.stdout.write(json.dumps(data, indent=2))
+    sys.stdout.close()
+
+
+if __name__ == "__main__":
+    main()

specification/callbacks/channel_status.yaml

@@ -24,20 +24,7 @@ description: |-
   - need to know exactly how a message has performed in real time with each of your recipients
   - need to know what happened to a message sent using a <a href="https://notify.nhs.uk/using-nhs-notify/routing-plans#secondary-cascades" target="_new">secondary cascade (opens in a new tab)
 operationId: post-v1-channel-callbacks
-parameters:
-    - name: x-hmac-sha256-signature
-      in: header
-      description: Contains a HMAC-SHA256 signature of the request body using a
-          pre-agreed secret
-      schema:
-          type: string
-          example: 9ee8c6aab877a97600e5c0cd8419f52d3dcdc45002e35220873d11123db6486f
-    - name: x-api-key
-      in: header
-      description: Contains the pre-agreed API key.
-      schema:
-          type: string
-          example: 0bb04a0e-d005-42dd-8993-dacf37410a12
+security: []
 requestBody:
   content:
     application/vnd.api+json:
@@ -57,4 +44,4 @@ responses:
     '403':
         description: Forbidden
     '429':
-        $ref: ../responses/4xx/callbacks/429_TooManyRequests_Callbacks.yaml
+        $ref: ../responses/4xx/callbacks/429_TooManyRequests_Callbacks.yaml

specification/callbacks/message_status.yaml

@@ -22,20 +22,6 @@ description: |-
 
     If you need additional real time updates when the status of a channel changes, you can also use the channel and supplier status callback.
 operationId: post-v1-message-callbacks
-parameters:
-    - name: x-hmac-sha256-signature
-      in: header
-      description: Contains a HMAC-SHA256 signature of the request body using a
-          pre-agreed secret
-      schema:
-          type: string
-          example: 9ee8c6aab877a97600e5c0cd8419f52d3dcdc45002e35220873d11123db6486f
-    - name: x-api-key
-      in: header
-      description: Contains the pre-agreed API key.
-      schema:
-          type: string
-          example: 0bb04a0e-d005-42dd-8993-dacf37410a12
 requestBody:
   content:
     application/vnd.api+json: