feat(301): third-party user management

.claude/hooks/post-write.sh

@@ -3,8 +3,18 @@
 
 set -euo pipefail
 
-# Get the project directory (hooks run in project context)
-PROJECT_DIR="$(pwd)"
+# Get the project directory - use CLAUDE_PROJECT_DIR if set (hooks run in worktree context),
+# otherwise fall back to pwd
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# Resolve the main worktree (where node_modules lives)
+COMMON_DIR="$(git -C "$PROJECT_DIR" rev-parse --git-common-dir 2>/dev/null || echo "$PROJECT_DIR/.git")"
+MAIN_WORKTREE="$(dirname "$COMMON_DIR")"
+if [ -d "$MAIN_WORKTREE/node_modules" ]; then
+    BIOME_BIN="$MAIN_WORKTREE/node_modules/.bin/biome"
+else
+    BIOME_BIN="$PROJECT_DIR/node_modules/.bin/biome"
+fi
 
 # Logging function
 log_hook() {
@@ -14,23 +24,49 @@ log_hook() {
 }
 
 log_hook "Hook started"
-echo "🔧 Running post-write checks..."
-
-# Run formatter and linter directly via root biome (not turbo per-workspace)
-echo "Checking code formatting and linting..."
-log_hook "Starting biome format and lint"
-if ! yarn biome format --write .; then
-    echo "❌ Code formatting check failed. Run 'yarn format' to fix."
-    log_hook "Formatter check failed"
-    exit 2
+
+if [ ! -x "$BIOME_BIN" ]; then
+    log_hook "biome not found at $BIOME_BIN, skipping"
+    exit 0
+fi
+
+# Only check files that were actually written (passed via CLAUDE_FILE_PATHS env var)
+# Fall back to checking nothing if not set — don't scan the whole codebase
+FILES_TO_CHECK="${CLAUDE_FILE_PATHS:-}"
+
+if [ -z "$FILES_TO_CHECK" ]; then
+    log_hook "No CLAUDE_FILE_PATHS set, skipping"
+    exit 0
+fi
+
+# Filter to only TypeScript/JavaScript files (skip .njk, .json, .prisma, .sh, etc.)
+TS_FILES=""
+while IFS= read -r f; do
+    case "$f" in
+        *.ts|*.tsx|*.js|*.jsx)
+            if [ -f "$f" ]; then
+                TS_FILES="$TS_FILES $f"
+            fi
+            ;;
+    esac
+done <<< "$FILES_TO_CHECK"
+
+if [ -z "$TS_FILES" ]; then
+    log_hook "No TS/JS files to check"
+    exit 0
+fi
+
+log_hook "Checking files: $TS_FILES"
+
+# Format then lint only the written files
+# Use || true so pre-existing errors elsewhere don't block this write
+if ! $BIOME_BIN format --write $TS_FILES 2>&1; then
+    log_hook "Format had issues (non-blocking)"
 fi
 
-if ! yarn biome check --write .; then
-    echo "❌ Linting failed"
-    log_hook "Linter failed"
-    exit 2
+if ! $BIOME_BIN check --write $TS_FILES 2>&1; then
+    log_hook "Lint had issues (non-blocking)"
 fi
 
-echo "✅ Post-write checks completed"
-log_hook "Hook completed successfully"
-exit 0
+log_hook "Hook completed"
+exit 0

apps/api/src/server.ts

@@ -1,4 +1,4 @@
-import { createApp } from "./app.js";
+const { createApp } = await import("./app.js");
 
 const PORT = process.env.API_PORT || 3001;
 

apps/postgres/prisma/migrations/20260318000000_add_third_party_user/migration.sql

@@ -0,0 +1,27 @@
+-- CreateTable
+CREATE TABLE "third_party_user" (
+    "id" TEXT NOT NULL,
+    "name" VARCHAR(255) NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "third_party_user_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "third_party_subscription" (
+    "id" TEXT NOT NULL,
+    "third_party_user_id" TEXT NOT NULL,
+    "list_type_id" INTEGER NOT NULL,
+    "sensitivity" VARCHAR(20) NOT NULL,
+
+    CONSTRAINT "third_party_subscription_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "third_party_subscription_third_party_user_id_list_type_id_key" ON "third_party_subscription"("third_party_user_id", "list_type_id");
+
+-- AddForeignKey
+ALTER TABLE "third_party_subscription" ADD CONSTRAINT "third_party_subscription_third_party_user_id_fkey" FOREIGN KEY ("third_party_user_id") REFERENCES "third_party_user"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "third_party_subscription" ADD CONSTRAINT "third_party_subscription_list_type_id_fkey" FOREIGN KEY ("list_type_id") REFERENCES "list_types"("id") ON DELETE RESTRICT ON UPDATE CASCADE;

apps/postgres/prisma/migrations/20260518135301/migration.sql

@@ -0,0 +1,2 @@
+-- DropForeignKey
+ALTER TABLE "third_party_subscription" DROP CONSTRAINT "third_party_subscription_list_type_id_fkey";

apps/postgres/prisma/migrations/20260522120000_readd_third_party_secret/migration.sql

@@ -0,0 +1,7 @@
+-- CreateTable
+CREATE TABLE "third_party_secret" (
+    "name" VARCHAR(255) NOT NULL,
+    "value" VARCHAR(1000) NOT NULL,
+
+    CONSTRAINT "third_party_secret_pkey" PRIMARY KEY ("name")
+);

apps/postgres/prisma/migrations/20260701000000_change_third_party_ids_to_uuid/migration.sql

@@ -0,0 +1,23 @@
+-- Change third_party_user and third_party_subscription IDs from TEXT (CUID) to UUID
+-- Existing rows are cleared as they have non-UUID IDs that cannot be migrated
+TRUNCATE TABLE "third_party_subscription", "third_party_user" CASCADE;
+
+ALTER TABLE "third_party_subscription" DROP CONSTRAINT IF EXISTS "third_party_subscription_third_party_user_id_fkey";
+ALTER TABLE "third_party_subscription" DROP CONSTRAINT IF EXISTS "third_party_subscription_list_type_id_fkey";
+
+ALTER TABLE "third_party_user"
+  ALTER COLUMN "id" DROP DEFAULT,
+  ALTER COLUMN "id" SET DATA TYPE UUID USING gen_random_uuid(),
+  ALTER COLUMN "id" SET DEFAULT gen_random_uuid();
+
+ALTER TABLE "third_party_subscription"
+  ALTER COLUMN "id" DROP DEFAULT,
+  ALTER COLUMN "id" SET DATA TYPE UUID USING gen_random_uuid(),
+  ALTER COLUMN "id" SET DEFAULT gen_random_uuid(),
+  ALTER COLUMN "third_party_user_id" SET DATA TYPE UUID USING gen_random_uuid();
+
+ALTER TABLE "third_party_subscription" ADD CONSTRAINT "third_party_subscription_third_party_user_id_fkey"
+  FOREIGN KEY ("third_party_user_id") REFERENCES "third_party_user"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+ALTER TABLE "third_party_subscription" ADD CONSTRAINT "third_party_subscription_list_type_id_fkey"
+  FOREIGN KEY ("list_type_id") REFERENCES "list_types"("id") ON DELETE RESTRICT ON UPDATE CASCADE;

apps/postgres/prisma/migrations/20260701115926_third_party_subscription/migration.sql

@@ -0,0 +1,8 @@
+-- DropForeignKey
+ALTER TABLE "third_party_subscription" DROP CONSTRAINT "third_party_subscription_list_type_id_fkey";
+
+-- AlterTable
+ALTER TABLE "third_party_subscription" ALTER COLUMN "id" DROP DEFAULT;
+
+-- AlterTable
+ALTER TABLE "third_party_user" ALTER COLUMN "id" DROP DEFAULT;

apps/web/.env.example

@@ -67,6 +67,11 @@ MEDIA_START_PAGE_LINK=
 # AZURE_B2C_TENANT_ID, AZURE_B2C_CLIENT_ID, AZURE_B2C_CLIENT_SECRET, AZURE_B2C_DOMAIN loaded from Key Vault
 # See helm/values.yaml for Key Vault secret mappings
 
+# Third Party OAuth Configuration
+# Name of the Azure Key Vault storing third-party OAuth credentials (set in deployed environments)
+# THIRD_PARTY_KEY_VAULT=<vault-name>
+# MANAGED_IDENTITY_CLIENT_ID=
+
 # Service URL for generating links in notifications
 CATH_SERVICE_URL=https://www.court-tribunal-hearings.service.gov.uk
 

apps/web/helm/values.dev.yaml

@@ -10,6 +10,7 @@ nodejs:
   image: 'hmctspublic.azurecr.io/cath/cath-web:latest'
   environment:
     REDIS_HOST: 'cath-{{ .Values.global.environment }}.redis.cache.windows.net'
+    THIRD_PARTY_KEY_VAULT: 'cath-ss-tp-kv-stg'
     SSO_ALLOW_HTTP_REDIRECT: 'false'
     CFT_IDAM_URL: 'https://idam-web-public.aat.platform.hmcts.net'
     MEDIA_PASSWORD_RESET_LINK: 'https://sign-in.pip-frontend.staging.platform.hmcts.net/pip-frontend.staging.platform.hmcts.net/oauth2/v2.0/authorize?p=B2C_1A_PASSWORD_RESET&client_id=cae650ba-431b-4fc8-be14-22d476ebd31b&nonce=defaultNonce&redirect_uri=https://pip-frontend.staging.platform.hmcts.net/password-change-confirmation&scope=openid&response_type=code&prompt=login&response_mode=query'

apps/web/helm/values.yaml

@@ -13,6 +13,7 @@ nodejs:
     ENVIRONMENT: '{{ .Values.global.environment }}'
     POSTGRES_DATABASE: cath
     REDIS_HOST: 'cath-redis-{{ .Values.global.environment }}.redis.cache.windows.net'
+    THIRD_PARTY_KEY_VAULT: 'cath-ss-tp-kv-{{ .Values.global.environment }}'
     SSO_ALLOW_HTTP_REDIRECT: 'false'
     CFT_IDAM_URL: https://idam-web-public.{{ .Values.global.environment }}.platform.hmcts.net
     CATH_SERVICE_URL: https://cath-web.{{ .Values.global.environment }}.platform.hmcts.net

apps/web/package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "concurrently -r \"yarn:dev:watch\" \"yarn:build:dev:watch\"",
-    "dev:watch": "mkdir -p dist/assets; nodemon -w yarn.lock -w src -w ../../libs -e 'json,ts' -x 'tsx --env-file-if-exists=../../.env src/server.ts'",
+    "dev:watch": "mkdir -p dist/assets; nodemon -w yarn.lock -w src -w ../../libs -e 'json,ts' -x \"tsx --env-file-if-exists=../../.env src/server.ts\"",
     "dev:nowatch": "yarn build:dev && tsx --env-file-if-exists=../../.env src/server.ts",
     "build:dev:watch": "yarn build:dev --watch",
     "build:dev": "NODE_OPTIONS='--import tsx' vite build --config vite.build.ts",

apps/web/src/app.test.ts

@@ -134,7 +134,8 @@ vi.mock("@hmcts/public-pages/config", () => ({
 
 vi.mock("@hmcts/system-admin-pages/config", () => ({
   fileUploadRoutes: ["/reference-data-upload"],
-  moduleRoot: "/mock/system-admin"
+  moduleRoot: "/mock/system-admin",
+  pages: { path: "/mock/system-admin/pages" }
 }));
 
 vi.mock("@hmcts/web-core/config", () => ({

apps/web/src/app.ts

@@ -31,7 +31,11 @@ import { moduleRoot as siacPoacPaacModuleRoot } from "@hmcts/siac-poac-paac-week
 import { moduleRoot as sjpPressListModuleRoot } from "@hmcts/sjp-press-list/config";
 import { moduleRoot as sjpPublicListModuleRoot } from "@hmcts/sjp-public-list/config";
 import { moduleRoot as sscsDailyHearingListModuleRoot } from "@hmcts/sscs-daily-hearing-list/config";
-import { fileUploadRoutes as systemAdminFileUploadRoutes, moduleRoot as systemAdminModuleRoot } from "@hmcts/system-admin-pages/config";
+import {
+  fileUploadRoutes as systemAdminFileUploadRoutes,
+  moduleRoot as systemAdminModuleRoot,
+  pages as systemAdminPages
+} from "@hmcts/system-admin-pages/config";
 import { moduleRoot as utiacJrModuleRoot } from "@hmcts/utiac-jr-daily-hearing-list/config";
 import { moduleRoot as utiacStatutoryAppealModuleRoot } from "@hmcts/utiac-statutory-appeal-daily-hearing-list/config";
 import {
@@ -185,7 +189,7 @@ export async function createApp(): Promise<Express> {
   app.use(await createSimpleRouter(publicPagesApiRoutes));
 
   // Register all pages from apps/web/src/pages (includes route groups and admin)
-  app.use(await createSimpleRouter({ path: `${__dirname}/pages` }));
+  app.use(await createSimpleRouter({ path: `${__dirname}/pages` }, systemAdminPages));
 
   // Enable test-support routes in non-production environments or when explicitly enabled
   if (process.env.NODE_ENV !== "production" || process.env.ENABLE_TEST_SUPPORT === "true") {

apps/web/src/pages/(system-admin)/create-third-party-user-summary/index.test.ts

@@ -107,7 +107,7 @@ describe("create-third-party-user-summary page", () => {
       (req.session as any).createThirdPartyUser = {
         name: "Test User",
         idempotencyToken: "abc123",
-        createdUserId: "user-123"
+        createdUserId: "00000000-0000-0000-0000-000000000001"
       };
 
       const handler = POST[POST.length - 1];
@@ -122,7 +122,7 @@ describe("create-third-party-user-summary page", () => {
       (req.session as any).createThirdPartyUser = {
         name: "Test User",
         idempotencyToken: "abc123",
-        createdUserId: "user-123"
+        createdUserId: "00000000-0000-0000-0000-000000000001"
       };
 
       const handler = POST[POST.length - 1];
@@ -136,13 +136,13 @@ describe("create-third-party-user-summary page", () => {
         name: "Test User",
         idempotencyToken: "abc123"
       };
-      (createThirdPartyUser as any).mockResolvedValue({ id: "new-user-id", name: "Test User" });
+      (createThirdPartyUser as any).mockResolvedValue({ id: "00000000-0000-0000-0000-000000000002", name: "Test User" });
 
       const handler = POST[POST.length - 1];
       await handler(req as Request, res as Response, vi.fn());
 
       expect(createThirdPartyUser).toHaveBeenCalledWith("Test User");
-      expect((req.session as any).createThirdPartyUser.createdUserId).toBe("new-user-id");
+      expect((req.session as any).createThirdPartyUser.createdUserId).toBe("00000000-0000-0000-0000-000000000002");
       expect(res.redirect).toHaveBeenCalledWith("/third-party-user-created");
     });
 
@@ -152,7 +152,7 @@ describe("create-third-party-user-summary page", () => {
         name: "Test User",
         idempotencyToken: "abc123"
       };
-      (createThirdPartyUser as any).mockResolvedValue({ id: "new-user-id", name: "Test User" });
+      (createThirdPartyUser as any).mockResolvedValue({ id: "00000000-0000-0000-0000-000000000002", name: "Test User" });
 
       const handler = POST[POST.length - 1];
       await handler(req as Request, res as Response, vi.fn());
@@ -165,15 +165,15 @@ describe("create-third-party-user-summary page", () => {
         name: "Test User",
         idempotencyToken: "abc123"
       };
-      (createThirdPartyUser as any).mockResolvedValue({ id: "new-user-id", name: "Test User" });
+      (createThirdPartyUser as any).mockResolvedValue({ id: "00000000-0000-0000-0000-000000000002", name: "Test User" });
 
       const handler = POST[POST.length - 1];
       await handler(req as Request, res as Response, vi.fn());
 
       expect(req.auditMetadata).toEqual({
         shouldLog: true,
         action: "Create third party user",
-        entityInfo: "ID: new-user-id, Name: Test User"
+        entityInfo: "ID: 00000000-0000-0000-0000-000000000002, Name: Test User"
       });
     });
   });

apps/web/src/pages/(system-admin)/create-third-party-user/cy.ts

@@ -4,5 +4,6 @@ export const cy = {
   continueButtonText: "Parhau",
   errorSummaryTitle: "Mae yna broblem",
   nameRequired: "Rhowch enw",
-  nameTooLong: "Rhaid i'r enw fod yn 255 nod neu lai"
+  nameTooLong: "Rhaid i'r enw fod yn 255 nod neu lai",
+  nameDuplicate: "Mae defnyddiwr trydydd parti gyda'r enw hwn eisoes yn bodoli"
 };

apps/web/src/pages/(system-admin)/create-third-party-user/en.ts

@@ -4,5 +4,6 @@ export const en = {
   continueButtonText: "Continue",
   errorSummaryTitle: "There is a problem",
   nameRequired: "Enter a name",
-  nameTooLong: "Name must be 255 characters or less"
+  nameTooLong: "Name must be 255 characters or less",
+  nameDuplicate: "A third party user with this name already exists"
 };

apps/web/src/pages/(system-admin)/create-third-party-user/index.test.ts

@@ -6,18 +6,20 @@ vi.mock("@hmcts/system-admin-pages", async (importOriginal) => {
   const actual = await importOriginal<typeof import("@hmcts/system-admin-pages")>();
   return {
     ...actual,
+    findThirdPartyUserByName: vi.fn(),
     validateThirdPartyUserName: vi.fn()
   };
 });
 
-import { validateThirdPartyUserName } from "@hmcts/system-admin-pages";
+import { findThirdPartyUserByName, validateThirdPartyUserName } from "@hmcts/system-admin-pages";
 
 describe("create-third-party-user page", () => {
   let req: Partial<Request>;
   let res: Partial<Response>;
 
   beforeEach(() => {
     vi.clearAllMocks();
+    vi.mocked(findThirdPartyUserByName).mockResolvedValue(null);
 
     req = {
       query: {},
@@ -161,5 +163,39 @@ describe("create-third-party-user page", () => {
 
       expect((req.session as any).createThirdPartyUser.idempotencyToken).toBeDefined();
     });
+
+    it("should show duplicate name error when user with same name already exists", async () => {
+      req.body = { name: "Existing User" };
+      (validateThirdPartyUserName as any).mockReturnValue(null);
+      vi.mocked(findThirdPartyUserByName).mockResolvedValue({ id: "00000000-0000-0000-0000-000000000099", name: "Existing User" });
+
+      const handler = POST[POST.length - 1];
+      await handler(req as Request, res as Response, vi.fn());
+
+      expect(res.render).toHaveBeenCalledWith(
+        "create-third-party-user/index",
+        expect.objectContaining({
+          errors: expect.arrayContaining([expect.objectContaining({ href: "#name" })]),
+          name: "Existing User"
+        })
+      );
+      expect(res.redirect).not.toHaveBeenCalled();
+    });
+
+    it("should be case-insensitive for duplicate name check", async () => {
+      req.body = { name: "existing user" };
+      (validateThirdPartyUserName as any).mockReturnValue(null);
+      vi.mocked(findThirdPartyUserByName).mockResolvedValue({ id: "00000000-0000-0000-0000-000000000099", name: "Existing User" });
+
+      const handler = POST[POST.length - 1];
+      await handler(req as Request, res as Response, vi.fn());
+
+      expect(res.render).toHaveBeenCalledWith(
+        "create-third-party-user/index",
+        expect.objectContaining({
+          errors: expect.arrayContaining([expect.objectContaining({ href: "#name" })])
+        })
+      );
+    });
   });
 });

apps/web/src/pages/(system-admin)/create-third-party-user/index.ts

@@ -1,6 +1,6 @@
 import crypto from "node:crypto";
 import { requireRole, USER_ROLES } from "@hmcts/auth";
-import { validateThirdPartyUserName } from "@hmcts/system-admin-pages";
+import { findThirdPartyUserByName, validateThirdPartyUserName } from "@hmcts/system-admin-pages";
 import type { Request, RequestHandler, Response } from "express";
 import { cy } from "./cy.js";
 import { en } from "./en.js";
@@ -42,6 +42,15 @@ const postHandler = async (req: Request, res: Response) => {
     });
   }
 
+  const existingUser = await findThirdPartyUserByName(name!.trim());
+  if (existingUser) {
+    return res.render("create-third-party-user/index", {
+      ...content,
+      errors: [{ href: "#name", text: content.nameDuplicate }],
+      name: name || ""
+    });
+  }
+
   const session = req.session as CreateThirdPartyUserSession;
   const idempotencyToken = crypto.randomUUID();