updating mock auth

Author: eddalmond1

docs/mock-authentication-how-to-use.md

@@ -0,0 +1,216 @@
+# Mock Authentication Script: How To Use
+
+This guide shows how to use the command line tool in [scripts/mock-authentication.py](../scripts/mock-authentication.py) to:
+
+- generate RSA keys and JWKS,
+- fetch an OAuth2 access token,
+- call an API endpoint with JWT-based app-restricted auth.
+
+## What this script does
+
+The script automates the JWT client assertion flow used by NHS application-restricted APIs:
+
+1. Creates an RSA key pair.
+2. Generates a JWKS document from the public key.
+3. Signs a JWT assertion with the private key.
+4. Exchanges the assertion for an access token.
+5. Calls an API using `Authorization: Bearer <token>`.
+
+## Prerequisites
+
+- Python 3.10+ (or compatible Python 3 version).
+- A valid NHS API key from the developer portal.
+- Your public key uploaded to the portal (or hosted JWKS URL configured for your app).
+
+Install required Python packages:
+
+```bash
+pip install "PyJWT[crypto]" requests cryptography
+```
+
+## Script location
+
+From repo root:
+
+```bash
+python3 scripts/mock-authentication.py --help
+```
+
+## Commands overview
+
+```bash
+python3 scripts/mock-authentication.py <command> [options]
+```
+
+Available commands:
+
+- `generate-keys` - Generate a private key, public key, and JWKS file.
+- `get-token` - Generate a JWT and exchange it for an access token.
+- `call-api` - Call an API endpoint using the access token.
+
+## 1) Generate keys and JWKS
+
+Generate a key pair and JWKS for integration environment:
+
+```bash
+python3 scripts/mock-authentication.py generate-keys \
+  --api-key YOUR_API_KEY \
+  --env int \
+  --output-dir ./.auth
+```
+
+Outputs:
+
+- `./.auth/int-1.pem` (private key)
+- `./.auth/int-1.pem.pub` (public key)
+- `./.auth/int-1.json` (JWKS)
+
+Use a custom key ID:
+
+```bash
+python3 scripts/mock-authentication.py generate-keys \
+  --api-key YOUR_API_KEY \
+  --env int \
+  --kid my-int-key-01 \
+  --output-dir ./.auth
+```
+
+## 2) Get an access token
+
+```bash
+python3 scripts/mock-authentication.py get-token \
+  --api-key YOUR_API_KEY \
+  --env int \
+  --private-key ./.auth/int-1.pem
+```
+
+Use `--kid` if you used a non-default KID:
+
+```bash
+python3 scripts/mock-authentication.py get-token \
+  --api-key YOUR_API_KEY \
+  --env int \
+  --kid my-int-key-01 \
+  --private-key ./.auth/my-int-key-01.pem
+```
+
+If `--kid` is omitted, the script now derives KID from the private key filename when it ends with `.pem`.
+For example, using `--private-key ./.auth/my-int-key-01.pem` will use `my-int-key-01` automatically.
+
+## 3) Call an API endpoint
+
+Basic GET call:
+
+```bash
+python3 scripts/mock-authentication.py call-api \
+  --api-key YOUR_API_KEY \
+  --env int \
+  --private-key ./.auth/int-1.pem \
+  --url https://int.api.service.nhs.uk/eligibility-signposting-api/patient-check/123
+```
+
+GET call including NHS number header and product ID header:
+
+```bash
+python3 scripts/mock-authentication.py call-api \
+  --api-key YOUR_API_KEY \
+  --env int \
+  --private-key ./.auth/int-1.pem \
+  --url https://int.api.service.nhs.uk/eligibility-signposting-api/patient-check/123 \
+  --nhs-number 1234567890
+```
+
+Call with extra headers:
+
+```bash
+python3 scripts/mock-authentication.py call-api \
+  --api-key YOUR_API_KEY \
+  --env int \
+  --private-key ./.auth/int-1.pem \
+  --url https://int.api.service.nhs.uk/some-api/endpoint \
+  --header "X-Correlation-ID: 7d8ff2e8-6a69-4cbe-a0f3-6f67e6fc2f91" \
+  --header "Accept: application/json"
+```
+
+Use another HTTP method:
+
+```bash
+python3 scripts/mock-authentication.py call-api \
+  --api-key YOUR_API_KEY \
+  --env int \
+  --private-key ./.auth/int-1.pem \
+  --method POST \
+  --url https://int.api.service.nhs.uk/some-api/endpoint \
+  --header "Content-Type: application/json"
+```
+
+## Environment options
+
+- `generate-keys` and `get-token` support: `dev`, `int`, `prod`
+- `call-api` supports: `dev`, `int`, `prod`, `sandbox`
+
+Note about `sandbox`:
+
+- For `call-api --env sandbox`, the script still uses the `int` OAuth token endpoint for token generation internally.
+- This is how the current script is implemented.
+
+## Typical end-to-end workflow
+
+```bash
+# 1) Generate keys and JWKS
+python3 scripts/mock-authentication.py generate-keys \
+  --api-key YOUR_API_KEY \
+  --env int \
+  --output-dir ./.auth
+
+# 2) Upload or host JWKS (manual step)
+#    File to publish: ./.auth/int-1.json
+
+# 3) Call target API
+python3 scripts/mock-authentication.py call-api \
+  --api-key YOUR_API_KEY \
+  --env int \
+  --private-key ./.auth/int-1.pem \
+  --url https://int.api.service.nhs.uk/eligibility-signposting-api/patient-check/123 \
+  --nhs-number 1234567890
+```
+
+## Troubleshooting
+
+### Missing dependencies
+
+If you see `Missing required dependencies`, run:
+
+```bash
+pip install "PyJWT[crypto]" requests cryptography
+```
+
+### Invalid environment
+
+If you see an invalid environment error, check command-specific supported values:
+
+- `generate-keys`, `get-token`: `dev|int|prod`
+- `call-api`: `dev|int|prod|sandbox`
+
+### Token request fails (401/403)
+
+Check:
+
+- API key is correct.
+- JWKS in portal matches the private key used by the script.
+- KID (`--kid`) matches what is configured.
+- System clock is in sync (JWTs are short-lived).
+
+### Invalid header format warning
+
+`--header` values must use this format:
+
+```text
+"Header-Name: value"
+```
+
+## Security notes
+
+- Never commit private keys (`*.pem`) to source control.
+- Store private keys in a secure location and rotate them periodically.
+- Treat access tokens as secrets.

scripts/mock-authentication.py

@@ -165,6 +165,9 @@ def generate_jwt(self, private_key_path: str, expires_in_minutes: int = 5) -> st
         Returns:
             Signed JWT string
         """
+        if expires_in_minutes <= 0:
+            raise ValueError("JWT expiry must be greater than 0 minutes")
+
         if expires_in_minutes > 5:
             raise ValueError("JWT expiry must not exceed 5 minutes")
 
@@ -173,10 +176,16 @@ def generate_jwt(self, private_key_path: str, expires_in_minutes: int = 5) -> st
             private_key = f.read()
 
         # Create claims
-        # Use slightly less than requested time to account for clock skew
-        # Subtract 10 seconds as a safety buffer
+        # Keep expiry comfortably below 5 minutes so minor clock skew does not
+        # push exp beyond the provider's strict validation threshold.
         current_time = int(time())
-        expiry_seconds = (expires_in_minutes * 60) - 10
+        requested_lifetime = expires_in_minutes * 60
+        clock_skew_buffer_seconds = 60
+        minimum_lifetime_seconds = 30
+        expiry_seconds = max(
+            minimum_lifetime_seconds,
+            requested_lifetime - clock_skew_buffer_seconds
+        )
 
         claims = {
             "sub": self.api_key,
@@ -203,6 +212,7 @@ def generate_jwt(self, private_key_path: str, expires_in_minutes: int = 5) -> st
         print(f"  Current time: {datetime.fromtimestamp(current_time)}")
         print(f"  Expiry time:  {exp_datetime}")
         print(f"  Time until expiry: {(claims['exp'] - current_time)} seconds")
+        print(f"  Clock skew buffer: {clock_skew_buffer_seconds} seconds")
 
         return signed_jwt
 
@@ -295,6 +305,18 @@ def call_api(self, api_url: str, private_key_path: str, method: str = 'GET',
 
 
 def main():
+    def resolve_kid(explicit_kid: Optional[str], private_key_path: Optional[str], env: str) -> str:
+        """Resolve KID from explicit arg, private key filename, or environment default."""
+        if explicit_kid:
+            return explicit_kid
+
+        if private_key_path:
+            private_key_name = Path(private_key_path).name
+            if private_key_name.endswith('.pem'):
+                return Path(private_key_path).stem
+
+        return f"{env}-1"
+
     parser = argparse.ArgumentParser(
         description='NHS API JWT Authentication Helper',
         formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -382,7 +404,11 @@ def main():
 
     # Handle get-token command
     elif args.command == 'get-token':
-        auth = NHSAPIAuth(args.api_key, args.env, args.kid)
+        resolved_kid = resolve_kid(args.kid, args.private_key, args.env)
+        if not args.kid:
+            print(f"Using KID: {resolved_kid}")
+
+        auth = NHSAPIAuth(args.api_key, args.env, resolved_kid)
         token = auth.get_access_token(args.private_key)
         print("\n" + "="*70)
         print(f"Access Token: {token}")
@@ -397,15 +423,19 @@ def main():
         else:
             env = args.env
 
-        auth = NHSAPIAuth(args.api_key, env, args.kid)
+        resolved_kid = resolve_kid(args.kid, args.private_key, env)
+        if not args.kid:
+            print(f"Using KID: {resolved_kid}")
+
+        auth = NHSAPIAuth(args.api_key, env, resolved_kid)
 
         # Build additional headers
         additional_headers = {}
 
         # Add NHS number header if provided
         if args.nhs_number:
             additional_headers['nhs-login-nhs-number'] = args.nhs_number
-            additional_headers['NHSE-Product-ID'] = 'P.XWA-VFF'
+            additional_headers['nhse_product_id'] = 'P.WTJ-FJT'
 
         # Add any custom headers
         if args.headers: