Chore: [AEA-5803] - cli to debug Notify token exchange (#2441)

## Summary

- 🤖 Operational or Infrastructure Change

### Details

Refactor token exchange to permit a local cli to debug config issues.

Author: tstephen-nhs

.gitignore

@@ -7,6 +7,7 @@
 **/node_modules/
 .#*
 __pycache__/
+.env
 .envrc
 .idea
 .vscode/settings.json

packages/nhsNotifyLambda/cli/README.md

@@ -0,0 +1,23 @@
+# NHS Notify Token Exchange CLI
+
+CLI tool for testing the NHS Notify OAuth2 token exchange flow.
+
+## Usage
+
+```bash
+cd packages/nhsNotifyLambda
+npm run cli:test-token
+```
+
+## Required Environment Variables
+
+Set these before running the CLI:
+
+```bash
+export NHS_NOTIFY_HOST="https://int.api.service.nhs.uk"
+export NHS_NOTIFY_API_KEY="your-api-key-here"
+export NHS_NOTIFY_PRIVATE_KEY="-----BEGIN ...
+... key contents ...
+... -----"
+export NHS_NOTIFY_KID="your-key-id-here"
+```

packages/nhsNotifyLambda/cli/test-token-exchange.ts

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+/**
+ * CLI tool to test NHS Notify token exchange
+ *
+ * Usage:
+ *   npm run cli:test-token
+ *
+ * Required environment variables:
+ *   NOTIFY_API_BASE_URL - e.g., https://int.api.service.nhs.uk
+ *   NOTIFY_API_KEY - API key for NHS Notify
+ *   NOTIFY_PRIVATE_KEY - RSA private key (PEM format)
+ *   NOTIFY_KID - Key ID
+ */
+
+import {Logger} from "@aws-lambda-powertools/logger"
+import axios from "axios"
+import axiosRetry from "axios-retry"
+import {tokenExchange} from "../src/utils/auth.js"
+import {NotifySecrets} from "../src/utils/secrets.js"
+
+const logger = initLogger()
+const {host} = loadNotifyConfig(logger)
+const notifySecrets = loadNotifySecrets(logger)
+const axiosInstance = initAxiosInst(host)
+
+logger.info("Testing token exchange", {
+  host,
+  apiKeyPrefix: notifySecrets.apiKey.substring(0, 10) + "...",
+  kid: notifySecrets.kid
+})
+
+try {
+  // Perform token exchange
+  const accessToken = await tokenExchange(
+    logger,
+    axiosInstance,
+    host,
+    notifySecrets
+  )
+
+  logger.info("Token exchange successful!", {
+    tokenPrefix: accessToken.substring(0, 20) + "...",
+    tokenLength: accessToken.length
+  })
+  console.log("\n✅ SUCCESS!")
+
+  process.exit(0)
+
+} catch (error) {
+  logger.error("Token exchange failed", {error})
+  console.error("\n❌ FAILED!")
+  console.error(`\nError: ${error instanceof Error ? error.message : String(error)}\n`)
+  process.exit(1)
+}
+
+function initAxiosInst(host: string) {
+  const axiosInstance = axios.create({
+    baseURL: host,
+    timeout: 30000
+  })
+
+  // Add retry logic
+  axiosRetry(axiosInstance, {
+    retries: 2,
+    retryDelay: axiosRetry.exponentialDelay,
+    retryCondition: (error) => {
+      return axiosRetry.isNetworkOrIdempotentRequestError(error)
+          || error.response?.status === 429
+          || error.response?.status === 500
+    }
+  })
+  return axiosInstance
+}
+
+function initLogger() {
+  return new Logger({
+    serviceName: "token-exchange-cli",
+    logLevel: "INFO"
+  })
+}
+
+function loadNotifyConfig(logger: Logger): {host: string} {
+  const host = process.env.NOTIFY_API_BASE_URL
+  if (!host) {
+    logger.error("Missing required environment variable: NOTIFY_API_BASE_URL")
+    process.exit(1)
+  }
+  return {host}
+}
+
+function loadNotifySecrets(logger: Logger): NotifySecrets {
+  const apiKey = process.env.NOTIFY_API_KEY
+  const privateKey = process.env.NOTIFY_PRIVATE_KEY
+  const kid = process.env.NOTIFY_KID
+
+  if (!apiKey) {
+    logger.error("Missing required environment variable: NOTIFY_API_KEY")
+    process.exit(1)
+  }
+
+  if (!privateKey) {
+    logger.error("Missing required environment variable: NOTIFY_PRIVATE_KEY")
+    process.exit(1)
+  }
+
+  if (!kid) {
+    logger.error("Missing required environment variable: NOTIFY_KID")
+    process.exit(1)
+  }
+  return {apiKey, privateKey, kid}
+}

packages/nhsNotifyLambda/package.json

@@ -11,7 +11,8 @@
     "lint": "eslint  --max-warnings 0 --fix --config ../../eslint.config.mjs .",
     "compile": "tsc",
     "test": "npm run compile && npm run unit",
-    "check-licenses": "license-checker --failOn GPL --failOn LGPL --start ../.."
+    "check-licenses": "license-checker --failOn GPL --failOn LGPL --start ../..",
+    "cli:test-token": "npm run compile && node lib/cli/test-token-exchange.js"
   },
   "dependencies": {
     "@aws-lambda-powertools/commons": "^2.28.1",

packages/nhsNotifyLambda/src/utils/auth.ts

@@ -1,50 +1,37 @@
 import {Logger} from "@aws-lambda-powertools/logger"
-import {getSecret} from "@aws-lambda-powertools/parameters/secrets"
 import {AxiosInstance} from "axios"
-
 import {SignJWT, importPKCS8} from "jose"
 
+import {NotifySecrets} from "./secrets.js"
+
 /**
  * Exchange API key + JWT for a bearer token from NHS Notify.
  */
 export async function tokenExchange(
   logger: Logger,
   axiosInstance: AxiosInstance,
-  host: string
+  host: string,
+  notifySecrets: NotifySecrets
 ): Promise<string> {
-  const [apiKeyRaw, privateKeyRaw, kidRaw] = await Promise.all([
-    getSecret(process.env.API_KEY_SECRET!),
-    getSecret(process.env.PRIVATE_KEY_SECRET!),
-    getSecret(process.env.KID_SECRET!)
-  ])
-
-  const API_KEY = apiKeyRaw?.toString().trim()
-  const PRIVATE_KEY = privateKeyRaw?.toString().trim()
-  const KID = kidRaw?.toString().trim()
-
-  if (!API_KEY || !PRIVATE_KEY || !KID) {
-    throw new Error("Missing one of API_KEY, PRIVATE_KEY or KID from Secrets Manager")
-  }
-
   // create and sign the JWT
   const alg = "RS512"
   const now = Math.floor(Date.now() / 1000)
   const jti = crypto.randomUUID()
 
-  const key = await importPKCS8(PRIVATE_KEY, alg)
+  const key = await importPKCS8(notifySecrets.privateKey, alg)
 
   const jwt = await new SignJWT({
-    sub: API_KEY,
-    iss: API_KEY,
+    sub: notifySecrets.apiKey,
+    iss: notifySecrets.apiKey,
     jti,
     aud: `${host}/oauth2/token`
   })
-    .setProtectedHeader({alg, kid: KID, typ: "JWT"})
+    .setProtectedHeader({alg, kid: notifySecrets.kid, typ: "JWT"})
     .setIssuedAt(now)
     .setExpirationTime(now + 60) // 1 minute
     .sign(key)
 
-  logger.info("Exchanging JWT for access token", {host, jti})
+  logger.info("Exchanging JWT for access token", {jwt, host, jti})
 
   // Request the token
   const params = new URLSearchParams({

packages/nhsNotifyLambda/src/utils/index.ts

@@ -2,6 +2,7 @@ import {NotifyDataItemMessage} from "./types"
 import {checkCooldownForUpdate, addPrescriptionMessagesToNotificationStateStore} from "./dynamo"
 import {removeSQSMessages, drainQueue, reportQueueStatus} from "./sqs"
 import {handleNotifyRequests, makeRealNotifyRequest} from "./notify"
+import {tokenExchange} from "./auth"
 
 export {
   NotifyDataItemMessage,
@@ -11,5 +12,6 @@ export {
   drainQueue,
   reportQueueStatus,
   handleNotifyRequests,
-  makeRealNotifyRequest
+  makeRealNotifyRequest,
+  tokenExchange
 }

packages/nhsNotifyLambda/src/utils/notify.ts

@@ -11,9 +11,16 @@ import {
   MessageBatchItem
 } from "./types"
 import {loadConfig} from "./ssm"
+import {loadSecrets, NotifySecrets} from "./secrets"
 import {tokenExchange} from "./auth"
 import {NOTIFY_REQUEST_MAX_BYTES, NOTIFY_REQUEST_MAX_ITEMS, DUMMY_NOTIFY_DELAY_MS} from "./constants"
 
+export interface NotifyConfig {
+  routingPlanId: string
+  notifyApiBaseUrl: string
+  notifySecrets: NotifySecrets
+}
+
 /**
  * Returns the original array, chunked in batches of up to <size>
  *
@@ -52,8 +59,6 @@ export async function handleNotifyRequests(
     return []
   }
 
-  const configPromise = loadConfig()
-
   // Map the NotifyDataItems into the structure needed for notify
   const messages: Array<MessageBatchItem> = data.flatMap(item => {
     // Ignore messages with missing deduplication IDs (the field is possibly undefined)
@@ -70,15 +75,20 @@ export async function handleNotifyRequests(
     }]
   })
 
-  // Check if we should make real requests
-  const {makeRealNotifyRequestsFlag, notifyApiBaseUrlRaw} = await configPromise
-  if (!makeRealNotifyRequestsFlag || !notifyApiBaseUrlRaw) return await makeFakeNotifyRequest(logger, data, messages)
-
-  if (!notifyApiBaseUrlRaw) throw new Error("NOTIFY_API_BASE_URL is not defined in the environment variables!")
-  // Just to be safe, trim any whitespace. Also, secrets may be bytes, so make sure it's a string
-  const notifyBaseUrl = notifyApiBaseUrlRaw.trim()
-
-  return await makeRealNotifyRequest(logger, routingPlanId, notifyBaseUrl, data, messages)
+  const {makeRealNotifyRequestsFlag, notifyApiBaseUrl} = await loadConfig()
+  if (!makeRealNotifyRequestsFlag) {
+    return await makeFakeNotifyRequest(logger, data, messages)
+  } else if (!notifyApiBaseUrl) {
+    throw new Error("NOTIFY_API_BASE_URL is not defined in the environment variables!")
+  } else {
+    const notifySecrets = await loadSecrets()
+    const config: NotifyConfig = {
+      routingPlanId,
+      notifyApiBaseUrl,
+      notifySecrets
+    }
+    return await makeRealNotifyRequest(logger, config, data, messages)
+  }
 }
 
 /**
@@ -90,7 +100,6 @@ async function makeFakeNotifyRequest(
   data: Array<NotifyDataItemMessage>,
   messages: Array<MessageBatchItem>
 ): Promise<Array<NotifyDataItemMessage>> {
-
   logger.info("Not doing real Notify requests. Simply waiting for some time and returning success on all messages")
   await new Promise(f => setTimeout(f, DUMMY_NOTIFY_DELAY_MS))
 
@@ -146,13 +155,15 @@ function logNotificationRequest(logger: Logger,
  * Handles splitting large batches into smaller ones as needed.
  *
  * @param logger - AWS logging object
- * @param routingPlanId - The Notify routing plan ID with which to process the data
- * @param data - The details for the notification
+ * @param config - configuration for talking to NHS Notify
+ * @param data - PSU SQS messages to process
+ * @param messages - The data being sent to NHS Notify
+ * @param bearerToken - lazy initialised Bearer token to communicate with Notify
+ * @param axiosInstance - lazy initialised HTTP client
  */
 export async function makeRealNotifyRequest(
   logger: Logger,
-  routingPlanId: string,
-  notifyBaseUrl: string,
+  config: NotifyConfig,
   data: Array<NotifyDataItemMessage>,
   messages: Array<MessageBatchItem>,
   bearerToken?: string,
@@ -166,16 +177,16 @@ export async function makeRealNotifyRequest(
     data: {
       type: "MessageBatch" as const,
       attributes: {
-        routingPlanId,
+        routingPlanId: config.routingPlanId,
         messageBatchReference,
         messages
       }
     }
   }
 
   // Lazily get the bearer token and axios instance, so we only do it once even if we recurse
-  axiosInstance ??= setupAxios(logger, notifyBaseUrl)
-  bearerToken ??= await tokenExchange(logger, axiosInstance, notifyBaseUrl)
+  axiosInstance ??= setupAxios(logger, config.notifyApiBaseUrl)
+  bearerToken ??= await tokenExchange(logger, axiosInstance, config.notifyApiBaseUrl, config.notifySecrets)
 
   // Recursive split if too large
   if (messages.length >= NOTIFY_REQUEST_MAX_ITEMS || estimateSize(body) > NOTIFY_REQUEST_MAX_BYTES) {
@@ -188,13 +199,17 @@ export async function makeRealNotifyRequest(
 
     // send both halves in parallel
     const [res1, res2] = await Promise.all([
-      makeRealNotifyRequest(logger, routingPlanId, notifyBaseUrl, data, firstHalf, bearerToken, axiosInstance),
-      makeRealNotifyRequest(logger, routingPlanId, notifyBaseUrl, data, secondHalf, bearerToken, axiosInstance)
+      makeRealNotifyRequest(
+        logger, config, data, firstHalf, bearerToken, axiosInstance
+      ),
+      makeRealNotifyRequest(
+        logger, config, data, secondHalf, bearerToken, axiosInstance
+      )
     ])
     return [...res1, ...res2]
   }
 
-  logger.info("Making a request for notifications to NHS notify", {count: messages.length, routingPlanId})
+  logger.info("Request notifications of NHS notify", {count: messages.length, routingPlanId: config.routingPlanId})
 
   try {
     const headers = {

packages/nhsNotifyLambda/src/utils/secrets.ts

@@ -0,0 +1,22 @@
+import {getSecret} from "@aws-lambda-powertools/parameters/secrets"
+
+export interface NotifySecrets {
+  apiKey: string, privateKey: string, kid: string
+}
+
+export async function loadSecrets(): Promise<NotifySecrets> {
+  const [apiKeyRaw, privateKeyRaw, kidRaw] = await Promise.all([
+    getSecret(process.env.API_KEY_SECRET!),
+    getSecret(process.env.PRIVATE_KEY_SECRET!),
+    getSecret(process.env.KID_SECRET!)
+  ])
+
+  if (!apiKeyRaw || !privateKeyRaw || !kidRaw) {
+    throw new Error("Missing one of API_KEY, PRIVATE_KEY or KID from Secrets Manager")
+  }
+  return {
+    apiKey: apiKeyRaw.toString().trim(),
+    privateKey: privateKeyRaw.toString().trim(),
+    kid: kidRaw.toString().trim()
+  }
+}