[GPCAPIM-287] Orange box by Vox-Ben · Pull Request #105 · NHSDigital/clinical-data-gateway-api

Vox-Ben · 2026-03-06T18:50:52Z

Description

This PR permits CDG to call the Orange Box GP Connect demonstrator

Note that it includes a call script. To call the orange box.

Spin up the dev container
Set $STUB_PROVIDER=false in your terminal
Set $BASE_URL=http://gateway-api:8080 in your terminal
make deploy
cd gateway-api
python src/scripts/call_gateway.py 9690937278

To revert to using the stub, repeat the above but unset STUB_PROVIDER before doing make deploy.

Context

This demonstrates that we can build a request that is acceptable to the Orange Box demonstrator for GP Connect and return the response that we get.

Type of changes

Refactoring (non-breaking change)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would change existing functionality)
Bug fix (non-breaking change which fixes an issue)

Checklist

I have followed the code style of the project
I have added tests to cover my changes
I have updated the documentation accordingly
This PR is a result of pair or mob programming
Exceptions/Exclusions to coding standards (e.g. #noqa or #NOSONAR) are included within this Pull Request.

Sensitive Information Declaration

To ensure the utmost confidentiality and protect your and others privacy, we kindly ask you to NOT including PII (Personal Identifiable Information) / PID (Personal Identifiable Data) or any other sensitive data in this PR (Pull Request) and the codebase changes. We will remove any PR that do contain any sensitive information. We really appreciate your cooperation in this matter.

I confirm that neither PII/PID nor sensitive data are included in this PR and the codebase changes.

Copilot

Pull request overview

This PR enables the gateway-api to construct and send GP Connect Access Record Structured requests that the Orange Box GP Connect demonstrator accepts, including updated stub data to “trigger” the Orange Box path and updated JWT claim structures/validation.

Changes:

Added stub SDS/PDS data (ODS/ASID/endpoint + patient) to route a specific NHS number to the Orange Box demonstrator.
Updated clinical JWT claim modeling (Device/Practitioner/Organization as dict payloads) and introduced a JWTValidator with unit tests.
Updated the GP provider client request URL path/headers and expanded error diagnostics (behind CDG_DEBUG), plus corresponding test updates and a new call script.

Reviewed changes

Copilot reviewed 24 out of 25 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
gateway-api/stubs/stubs/sds/stub.py	Adds dummy ODS/ASID/device + Orange Box endpoint seed data for SDS stub responses.
gateway-api/stubs/stubs/provider/stub.py	Adds strict header + JWT validation for stubbed provider access_record_structured handling.
gateway-api/stubs/stubs/pds/stub.py	Adds a test NHS number mapping to the new Orange Box trigger patient.
gateway-api/stubs/stubs/data/patients/patients.py	Registers the new Orange Box trigger patient fixture.
gateway-api/stubs/stubs/data/patients/orange_box_trigger_9690937278.json	Adds a Patient resource used to route to Orange Box via GP ODS.
gateway-api/src/gateway_api/test_controller.py	Updates controller JWT claim assertions to match new dict-based organization claim.
gateway-api/src/gateway_api/provider/test_client.py	Updates provider client tests for new endpoint path, headers, and stub signature.
gateway-api/src/gateway_api/provider/client.py	Changes provider endpoint path handling, content-type headers, and error reporting.
gateway-api/src/gateway_api/controller.py	Updates JWT generation to use dict claim objects (Device/Practitioner/Organization).
gateway-api/src/gateway_api/conftest.py	Adds a shared `valid_jwt` fixture for validator/client tests.
gateway-api/src/gateway_api/common/error.py	Introduces `JWTValidationError` for claim validation failures.
gateway-api/src/gateway_api/common/common.py	Adds `get_http_text()` helper for HTTP status phrase lookup.
gateway-api/src/gateway_api/clinical_jwt/validator.py	New JWTValidator implementing claim structure/timestamp validation.
gateway-api/src/gateway_api/clinical_jwt/test_validator.py	New unit tests for JWTValidator behavior.
gateway-api/src/gateway_api/clinical_jwt/test_practitioner.py	Updates Practitioner tests to use `to_dict()` output.
gateway-api/src/gateway_api/clinical_jwt/test_jwt.py	Updates JWT tests for dict-based claims and default algorithm behavior.
gateway-api/src/gateway_api/clinical_jwt/test_device.py	Updates Device tests to use `to_dict()` output.
gateway-api/src/gateway_api/clinical_jwt/practitioner.py	Refactors Practitioner to emit structured dict payloads (no JSON string building).
gateway-api/src/gateway_api/clinical_jwt/organization.py	Adds Organization claim model emitting dict payloads.
gateway-api/src/gateway_api/clinical_jwt/jwt.py	Changes JWT claim field types to dict payloads and sets default algorithm to `none`.
gateway-api/src/gateway_api/clinical_jwt/device.py	Refactors Device to emit structured dict payloads (no JSON string building).
gateway-api/src/gateway_api/clinical_jwt/init.py	Exposes Organization and JWTValidator from the clinical_jwt package.
gateway-api/scripts/call_gateway.py	Adds a CLI script for calling the gateway’s getstructuredrecord endpoint.
gateway-api/poetry.lock	Updates lockfile metadata (Poetry version and content hash).
Makefile	Passes stub/debug env vars into the docker container on `make deploy`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Makefile

gateway-api/src/gateway_api/clinical_jwt/validator.py

gateway-api/src/gateway_api/provider/client.py

gateway-api/src/gateway_api/common/common.py

gateway-api/src/gateway_api/controller.py

gateway-api/stubs/stubs/data/patients/orange_box_trigger_9690937278.json

gateway-api/scripts/call_gateway.py

gateway-api/src/gateway_api/conftest.py

davidhamill1-nhs · 2026-03-16T11:02:18Z

Spin up the dev container
Set $STUB_PROVIDER=false in your terminal
Set $BASE_URL=http://gateway-api:8080 in your terminal

The gateway api container has the STUB_PROVIDER env var hard coded in the infrastructure/images/gateway-api/Dockerfile, right?

gateway-api/src/gateway_api/clinical_jwt/jwt.py

gateway-api/src/gateway_api/clinical_jwt/validator.py

gateway-api/src/gateway_api/provider/test_client.py

gateway-api/src/scripts/call_gateway.py

gateway-api/src/gateway_api/clinical_jwt/validator.py

gateway-api/src/gateway_api/provider/client.py

gateway-api/tests/contract/test_consumer_contract.py

Makefile

Copilot

Pull request overview

Copilot reviewed 35 out of 37 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

gateway-api/src/gateway_api/clinical_jwt/test_practitioner.py

github-actions · 2026-03-17T10:50:22Z

✅ Trivy gate: no Critical/High issues.

Trivy IaC (Terraform) Summary

Severity	Count
CRITICAL	0
HIGH	0
MEDIUM	0
LOW	0
UNKNOWN	0

Findings (top 50)

Severity	ID	Title	File

github-actions · 2026-03-17T10:50:36Z

✅ Trivy gate: no Critical/High vulnerabilities.

Trivy Image Scan Summary

Image: 900119715266.dkr.ecr.eu-west-2.amazonaws.com/whoami:feature-gpcapim-287-orange-box

Severity	Count
CRITICAL	0
HIGH	0
MEDIUM	0
LOW	1
UNKNOWN	0

Findings (top 50)

Severity	ID	Package	Installed	Fixed	Source
LOW	CVE-2026-1703	pip	25.3	26.0	Python

sonarqubecloud · 2026-03-17T14:46:29Z

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

Copilot

Pull request overview

Copilot reviewed 35 out of 37 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

infrastructure/images/gateway-api/Dockerfile

+# Install required certificates for dev machines and upgrade packages.
+RUN cp -r /resources/dev-certificates/* /usr/local/share/ca-certificates/; \
+    update-ca-certificates; \
+    cp -r /resources/dev-certificates/* /etc/ssl/certs/; \
+    apk upgrade --no-cache; \
+    addgroup -S nonroot; \
+    adduser -S gateway_api_user -G nonroot


gateway-api/src/gateway_api/provider/client.py


-        endpoint_path = "/".join([ARS_FHIR_BASE, FHIR_RESOURCE, ARS_FHIR_OPERATION])
-        url = urljoin(self.provider_endpoint, endpoint_path)
+        url = urljoin(self.provider_endpoint, self.endpoint_path)


gateway-api/src/gateway_api/clinical_jwt/validator.py

+    def validate_device(device: dict[str, Any]) -> None:
+        """
+        Validate JWT requesting_device structure.
+
+        Raises:
+            JWTValidationError: If device structure is invalid.
+        """
+        device_errors = []
+        if device.get("resourceType") != "Device":
+            device_errors.append("resourceType must be 'Device'")
+        if not device.get("identifier") or not isinstance(
+            device.get("identifier"), list
+        ):
+            device_errors.append("Device identifier must be a non-empty list")
+        else:
+            identifier = device["identifier"][0]
+            if not identifier.get("system"):
+                device_errors.append("identifier[0].system is required")
+            if not identifier.get("value"):
+                device_errors.append("identifier[0].value is required")
+        if not device.get("model"):
+            device_errors.append("model is required")
+        if not device.get("version"):
+            device_errors.append("version is required")
+
+        if device_errors:
+            raise JWTValidationError(
+                error_details=f"Invalid requesting_device: {', '.join(device_errors)}"
+            )
+


github-actions · 2026-03-17T14:49:17Z

Deployment Complete

Preview URL: https://feature-gpcapim-287-orange-box.dev.endpoints.clinical-data-gateway.national.nhs.uk — Health endpoint
- Smoke Test: ✅ Passed (HTTP 200)
Proxy URL: https://internal-dev.api.service.nhs.uk/clinical-data-gateway-api-poc-pr-105
ECS Cluster: ecs-cluster
ECS Service: pr-feature-gpcapim-287-orange-box
ALB Target: arn:aws:elasticloadbalancing:eu-west-2:900119715266:targetgroup/gpcapim-287-orange-box/0cc545b84d290619

Vox-Ben force-pushed the feature/GPCAPIM-287-orange_box branch from e8c4acd to 335eb79 Compare March 12, 2026 12:58

Copilot AI mentioned this pull request Mar 12, 2026

[WIP] [GPCAPIM-287] Permit CDG to call Orange Box GP Connect demonstrator #110

Closed

Vox-Ben requested a review from Copilot March 12, 2026 13:02

Copilot started reviewing on behalf of Vox-Ben March 12, 2026 13:02 View session

NHSDigital deleted a comment from Copilot AI Mar 12, 2026

Copilot AI reviewed Mar 12, 2026

View reviewed changes

Vox-Ben marked this pull request as ready for review March 12, 2026 17:08

Vox-Ben requested a review from a team as a code owner March 12, 2026 17:08

davidhamill1-nhs reviewed Mar 16, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings March 16, 2026 23:09

Copilot started reviewing on behalf of Vox-Ben March 16, 2026 23:09 View session

Vox-Ben added 18 commits March 16, 2026 23:10

Add pyjwt, clinical_jwt, make ruff happy

6aa445d

Review comments

0193f8d

Make ruff happy, refactor controller JWT test

00721cc

Start of orange box connection

ed4a788

Orange box working with debug script

f60a679

Orange box connection working

b3da866

Pass $STUB_PROVIDER

95c0ec1

Pass STUB env vars

932fec3

Create call script

1515f7f

Fix algorithm string none

1ebab25

Tidy up error handling

f2bf4ec

Add request validation to provider stub

9470f2e

Fix rebase mess and tidy up

9d8fd47

Update TODO comment

3c196a0

Improve test coverage

373db76

Fix JWT default times and encoding value

49467f4

Move FHIR constants to single enum

a6cc0cf

Remove now-duplicate scripts dir

6c58250

Vox-Ben added 4 commits March 16, 2026 23:10

Change PROVIDER_STRING variable name

96503c9

Why is Ruff complaining about this now and not six weeks ago?

36c7a1a

Review comments

d181334

Put Any type back in

c56c3d1

Vox-Ben force-pushed the feature/GPCAPIM-287-orange_box branch from 9456e81 to c56c3d1 Compare March 16, 2026 23:10

Copilot AI reviewed Mar 16, 2026

View reviewed changes

gateway-api/src/gateway_api/clinical_jwt/test_practitioner.py Outdated Show resolved Hide resolved

Vox-Ben added 2 commits March 17, 2026 10:40

Fix Trivy error

c9fbb77

Copilot review None check

c28f8fb

Add certs, remove run script

e8ccff7

Copilot AI review requested due to automatic review settings March 17, 2026 14:42

Copilot started reviewing on behalf of Vox-Ben March 17, 2026 14:42 View session

Copilot AI reviewed Mar 17, 2026

View reviewed changes

Conversation

Vox-Ben commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Context

Type of changes

Checklist

Sensitive Information Declaration

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

davidhamill1-nhs commented Mar 16, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

github-actions bot commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Trivy IaC (Terraform) Summary

Uh oh!

github-actions bot commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Trivy Image Scan Summary

Uh oh!

sonarqubecloud bot commented Mar 17, 2026

Quality Gate passed

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

github-actions bot commented Mar 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Vox-Ben commented Mar 6, 2026 •

edited

Loading

github-actions bot commented Mar 17, 2026 •

edited

Loading

github-actions bot commented Mar 17, 2026 •

edited

Loading