create-interview-cockpit 0.17.3 → 0.19.0

package/template/client/src/enterpriseLocalLab.ts

@@ -0,0 +1,921 @@
+import type { InfraLabWorkspace } from "./types";
+
+export const ENTERPRISE_LOCAL_AUTH_LAB: InfraLabWorkspace = {
+  version: 1,
+  label: "Enterprise BFF Auth Stack",
+  provider: "docker",
+  executionMode: "docker",
+  activeFile: "README.md",
+  files: {
+    "README.md": `# Enterprise BFF Auth Stack
+
+This lab is a local enterprise-style auth environment managed by Terraform.
+
+## What you deploy
+
+- A local Cognito-like OIDC provider container
+- A NestJS BFF container
+- A NestJS claims API container
+- A Redis session store container
+- A private Docker network connecting the services
+
+The browser only talks to the BFF. The BFF owns the auth code exchange, stores tokens server-side in Redis, and gives the browser an HttpOnly session cookie plus a readable CSRF cookie.
+Terraform builds the local Node service images with the Docker CLI, then the Docker provider starts the containers.
+
+## Prerequisites
+
+- Docker Desktop running
+- Terraform installed locally
+
+## Run it from the Infra Lab console
+
+1. terraform init
+2. terraform plan -out=tfplan
+3. terraform apply -auto-approve
+4. terraform output
+5. Open the BFF URL from the output, usually http://localhost:4300
+
+## Practice flow
+
+1. Click Sign in.
+2. The browser goes to the local OIDC provider.
+3. The BFF receives the callback and exchanges the code.
+4. The BFF stores tokens in Redis.
+5. The browser receives only cookies.
+6. Fetch a claim through /api/claims/CLM-1001.
+7. Add a note; the BFF checks CSRF before forwarding to the claims API.
+
+## Separate Next.js client lab
+
+Open **Labs → Next.js Labs → BFF Auth Client** to run a separate frontend shell.
+That Next.js lab talks to this Terraform-deployed BFF at http://localhost:4300.
+
+## Interview talking point
+
+This is intentionally close to a production BFF pattern: Authorization Code + PKCE, server-side session state, opaque browser cookies, CSRF protection for cookie-authenticated writes, and downstream API calls hidden behind the BFF.
+
+## Clean up
+
+terraform destroy -auto-approve
+
+If Terraform says the Docker network already exists, inspect and remove the stale empty network:
+
+docker context show
+docker network ls --filter name=enterprise-auth-lab
+docker network inspect enterprise-auth-lab
+docker network rm enterprise-auth-lab
+
+If Terraform already manages the network and you want to keep it instead, import it:
+
+terraform import docker_network.lab enterprise-auth-lab
+`,
+    "provider.tf": `terraform {
+  required_version = ">= 1.5.0"
+
+  required_providers {
+    docker = {
+      source  = "kreuzwerker/docker"
+      version = "~> 3.0"
+    }
+  }
+}
+
+provider "docker" {}
+`,
+    "variables.tf": `variable "name_prefix" {
+  description = "Prefix used for Docker images, containers, and the network."
+  type        = string
+  default     = "enterprise-auth-lab"
+}
+
+variable "bff_port" {
+  description = "Host port for the NestJS BFF."
+  type        = number
+  default     = 4300
+}
+
+variable "idp_port" {
+  description = "Host port for the Cognito-like local OIDC provider."
+  type        = number
+  default     = 4400
+}
+
+variable "claims_port" {
+  description = "Optional host port for directly inspecting the downstream claims API."
+  type        = number
+  default     = 4500
+}
+
+variable "redis_port" {
+  description = "Optional host port for directly inspecting Redis. The app containers use the Docker network name."
+  type        = number
+  default     = 6379
+}
+`,
+    "main.tf": `locals {
+  bff_origin         = "http://localhost:\${var.bff_port}"
+  idp_browser_origin = "http://localhost:\${var.idp_port}"
+
+  cognito_mock_image = "\${var.name_prefix}-cognito-mock:local"
+  claims_api_image   = "\${var.name_prefix}-claims-api:local"
+  bff_image          = "\${var.name_prefix}-bff:local"
+
+  cognito_mock_source_hash = sha1(join("", [for file_name in sort(fileset(path.module, "apps/cognito-mock/**")) : filesha1("\${path.module}/\${file_name}")]))
+  claims_api_source_hash   = sha1(join("", [for file_name in sort(fileset(path.module, "apps/claims-api/**")) : filesha1("\${path.module}/\${file_name}")]))
+  bff_source_hash          = sha1(join("", [for file_name in sort(fileset(path.module, "apps/bff/**")) : filesha1("\${path.module}/\${file_name}")]))
+}
+
+resource "docker_network" "lab" {
+  name = var.name_prefix
+}
+
+resource "docker_image" "redis" {
+  name         = "redis:7-alpine"
+  keep_locally = true
+}
+
+resource "terraform_data" "cognito_mock_image" {
+  input            = local.cognito_mock_image
+  triggers_replace = local.cognito_mock_source_hash
+
+  provisioner "local-exec" {
+    working_dir = path.module
+    command     = "docker build -t \${local.cognito_mock_image} apps/cognito-mock"
+  }
+}
+
+resource "terraform_data" "claims_api_image" {
+  input            = local.claims_api_image
+  triggers_replace = local.claims_api_source_hash
+
+  provisioner "local-exec" {
+    working_dir = path.module
+    command     = "docker build -t \${local.claims_api_image} apps/claims-api"
+  }
+}
+
+resource "terraform_data" "bff_image" {
+  input            = local.bff_image
+  triggers_replace = local.bff_source_hash
+
+  provisioner "local-exec" {
+    working_dir = path.module
+    command     = "docker build -t \${local.bff_image} apps/bff"
+  }
+}
+
+resource "docker_container" "redis" {
+  name  = "\${var.name_prefix}-redis"
+  image = docker_image.redis.image_id
+  wait  = true
+
+  wait_timeout = 120
+
+  networks_advanced {
+    name = docker_network.lab.name
+  }
+
+  ports {
+    internal = 6379
+    external = var.redis_port
+  }
+
+  healthcheck {
+    test         = ["CMD", "redis-cli", "ping"]
+    interval     = "5s"
+    timeout      = "3s"
+    start_period = "5s"
+    retries      = 20
+  }
+}
+
+resource "docker_container" "cognito_mock" {
+  name  = "\${var.name_prefix}-cognito-mock"
+  image = local.cognito_mock_image
+  wait  = true
+
+  wait_timeout = 120
+
+  networks_advanced {
+    name = docker_network.lab.name
+  }
+
+  labels {
+    label = "interview-cockpit/source-hash"
+    value = local.cognito_mock_source_hash
+  }
+
+  ports {
+    internal = 4000
+    external = var.idp_port
+  }
+
+  env = [
+    "PORT=4000",
+    "CLIENT_ID=enterprise-bff",
+    "REDIRECT_URI=\${local.bff_origin}/auth/callback",
+    "ISSUER_BROWSER=\${local.idp_browser_origin}"
+  ]
+
+  healthcheck {
+    test         = ["CMD", "node", "-e", "fetch('http://127.0.0.1:4000/.well-known/openid-configuration').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+    interval     = "5s"
+    timeout      = "3s"
+    start_period = "5s"
+    retries      = 20
+  }
+
+  depends_on = [terraform_data.cognito_mock_image]
+}
+
+resource "docker_container" "claims_api" {
+  name  = "\${var.name_prefix}-claims-api"
+  image = local.claims_api_image
+  wait  = true
+
+  wait_timeout = 120
+
+  networks_advanced {
+    name = docker_network.lab.name
+  }
+
+  labels {
+    label = "interview-cockpit/source-hash"
+    value = local.claims_api_source_hash
+  }
+
+  ports {
+    internal = 4000
+    external = var.claims_port
+  }
+
+  healthcheck {
+    test         = ["CMD", "node", "-e", "fetch('http://127.0.0.1:4000/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+    interval     = "5s"
+    timeout      = "3s"
+    start_period = "5s"
+    retries      = 20
+  }
+
+  depends_on = [terraform_data.claims_api_image]
+}
+
+resource "docker_container" "bff" {
+  name  = "\${var.name_prefix}-bff"
+  image = local.bff_image
+  wait  = true
+
+  wait_timeout = 120
+
+  networks_advanced {
+    name = docker_network.lab.name
+  }
+
+  labels {
+    label = "interview-cockpit/source-hash"
+    value = local.bff_source_hash
+  }
+
+  ports {
+    internal = 3000
+    external = var.bff_port
+  }
+
+  env = [
+    "PORT=3000",
+    "BFF_BASE_URL=\${local.bff_origin}",
+    "SESSION_COOKIE_NAME=local-session",
+    "COOKIE_SECURE=false",
+    "OIDC_CLIENT_ID=enterprise-bff",
+    "OIDC_REDIRECT_URI=\${local.bff_origin}/auth/callback",
+    "IDP_AUTHORIZE_URL=\${local.idp_browser_origin}/oauth2/authorize",
+    "IDP_TOKEN_URL=http://\${docker_container.cognito_mock.name}:4000/oauth2/token",
+    "IDP_USERINFO_URL=http://\${docker_container.cognito_mock.name}:4000/oauth2/userInfo",
+    "REDIS_URL=redis://\${docker_container.redis.name}:6379",
+    "CLAIMS_API_BASE_URL=http://\${docker_container.claims_api.name}:4000"
+  ]
+
+  healthcheck {
+    test         = ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+    interval     = "5s"
+    timeout      = "3s"
+    start_period = "5s"
+    retries      = 20
+  }
+
+  depends_on = [
+    terraform_data.bff_image,
+    docker_container.redis,
+    docker_container.cognito_mock,
+    docker_container.claims_api
+  ]
+}
+`,
+    "outputs.tf": `output "bff_url" {
+  value       = local.bff_origin
+  description = "Open this URL in the browser."
+}
+
+output "oidc_provider_url" {
+  value       = local.idp_browser_origin
+  description = "Local Cognito-like authorize server."
+}
+
+output "claims_api_debug_url" {
+  value       = "http://localhost:\${var.claims_port}"
+  description = "Direct downstream API URL for debugging. The browser app should still call the BFF."
+}
+`,
+    "apps/bff/Dockerfile": `FROM node:22-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm install
+COPY tsconfig.json ./
+COPY src ./src
+RUN npm run build
+EXPOSE 3000
+CMD ["npm", "start"]
+`,
+    "apps/bff/package.json": `{
+  "name": "enterprise-auth-bff",
+  "private": true,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/main.js"
+  },
+  "dependencies": {
+    "@nestjs/common": "^10.4.15",
+    "@nestjs/core": "^10.4.15",
+    "@nestjs/platform-express": "^10.4.15",
+    "cookie-parser": "^1.4.7",
+    "ioredis": "^5.4.2",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1"
+  },
+  "devDependencies": {
+    "@types/cookie-parser": "^1.4.8",
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}
+`,
+    "apps/bff/tsconfig.json": `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "esModuleInterop": true,
+    "strict": false,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*.ts"]
+}
+`,
+    "apps/bff/src/main.ts": `import "reflect-metadata";
+import { Body, Controller, Get, Headers, Module, Param, Post, Req, Res } from "@nestjs/common";
+import { NestFactory } from "@nestjs/core";
+import cookieParser from "cookie-parser";
+import Redis from "ioredis";
+import crypto from "crypto";
+import type { Request, Response } from "express";
+
+type TokenSet = {
+  access_token: string;
+  id_token?: string;
+  refresh_token?: string;
+  expires_in?: number;
+};
+
+type SessionRecord = {
+  user: { sub: string; email?: string; name?: string };
+  tokens: TokenSet & { expiresAt: number };
+  csrfToken: string;
+};
+
+type LoginChallenge = {
+  state: string;
+  nonce: string;
+  verifier: string;
+  returnTo: string;
+};
+
+const redis = new Redis(process.env.REDIS_URL || "redis://localhost:6379");
+const cookieSecure = process.env.COOKIE_SECURE === "true";
+const sessionCookie = process.env.SESSION_COOKIE_NAME || (cookieSecure ? "__Host-session" : "local-session");
+const loginCookie = "login-challenge";
+const clientId = process.env.OIDC_CLIENT_ID || "enterprise-bff";
+const redirectUri = process.env.OIDC_REDIRECT_URI || "http://localhost:4300/auth/callback";
+const bffBaseUrl = process.env.BFF_BASE_URL || "http://localhost:4300";
+const claimsBaseUrl = process.env.CLAIMS_API_BASE_URL || "http://localhost:4500";
+
+function randomToken(bytes = 32) {
+  return crypto.randomBytes(bytes).toString("base64url");
+}
+
+function pkceChallenge(verifier: string) {
+  return crypto.createHash("sha256").update(verifier).digest("base64url");
+}
+
+function cookieOptions(httpOnly: boolean, maxAge: number) {
+  return { httpOnly, secure: cookieSecure, sameSite: "lax" as const, path: "/", maxAge };
+}
+
+function isAllowedLocalOrigin(origin: string | undefined): boolean {
+  if (!origin) return true;
+  try {
+    const url = new URL(origin);
+    return (
+      (url.hostname === "localhost" || url.hostname === "127.0.0.1") &&
+      (url.protocol === "http:" || url.protocol === "https:")
+    );
+  } catch {
+    return false;
+  }
+}
+
+function safeReturnTo(value: unknown): string {
+  const candidate = typeof value === "string" ? value : "";
+  if (!candidate) return bffBaseUrl + "/";
+  try {
+    const url = new URL(candidate);
+    if (!isAllowedLocalOrigin(url.origin)) return bffBaseUrl + "/";
+    return url.toString();
+  } catch {
+    return bffBaseUrl + "/";
+  }
+}
+
+async function loadSession(req: Request): Promise<{ id: string; value: SessionRecord } | null> {
+  const id = String((req as any).cookies?.[sessionCookie] || "");
+  if (!id) return null;
+  const raw = await redis.get("sess:" + id);
+  if (!raw) return null;
+  return { id, value: JSON.parse(raw) as SessionRecord };
+}
+
+async function requireSession(req: Request, res: Response): Promise<SessionRecord | null> {
+  const session = await loadSession(req);
+  if (!session) {
+    res.status(401).json({ error: "Unauthorized" });
+    return null;
+  }
+  await redis.expire("sess:" + session.id, 30 * 60);
+  return session.value;
+}
+
+function assertCsrf(req: Request, res: Response, session: SessionRecord): boolean {
+  const token = String(req.headers["x-csrf-token"] || "");
+  if (!token || token !== session.csrfToken) {
+    res.status(403).json({ error: "Invalid CSRF token" });
+    return false;
+  }
+  return true;
+}
+
+function homeHtml() {
+  return [
+    "<!doctype html><html><head><meta charset='utf-8'><title>Enterprise BFF Lab</title>",
+    "<style>body{font-family:Inter,system-ui;background:#020617;color:#e2e8f0;margin:0;padding:32px}button{background:#06b6d4;border:0;border-radius:8px;padding:10px 14px;font-weight:700}pre,textarea{width:100%;box-sizing:border-box;background:#0f172a;color:#cbd5e1;border:1px solid #334155;border-radius:10px;padding:12px}section{max-width:900px;margin:auto}.card{border:1px solid #1e293b;border-radius:16px;padding:20px;margin:16px 0;background:#0f172a80}.muted{color:#94a3b8}</style></head><body><section>",
+    "<h1>Enterprise BFF Auth Lab</h1><p class='muted'>Browser stores cookies only. The BFF owns tokens and downstream API calls.</p>",
+    "<div class='card'><button onclick='login()'>Sign in</button> <button onclick='logout()'>Logout</button> <button onclick='me()'>/auth/me</button></div>",
+    "<div class='card'><button onclick='claim()'>Fetch claim CLM-1001 through BFF</button><pre id='out'>Ready.</pre></div>",
+    "<div class='card'><textarea id='note' rows='3'>Customer uploaded police report.</textarea><br><br><button onclick='addNote()'>Add note with CSRF header</button></div>",
+    "<script>",
+    "function login(){ location.href='/auth/login'; }",
+    "async function logout(){ await api('/auth/logout',{method:'POST'}); out('Logged out'); }",
+    "function csrf(){ const row=document.cookie.split('; ').find(x=>x.startsWith('XSRF-TOKEN=')); return row ? decodeURIComponent(row.split('=')[1]) : ''; }",
+    "async function api(path, init){ init=init||{}; const headers=new Headers(init.headers||{}); const method=(init.method||'GET').toUpperCase(); if(!['GET','HEAD','OPTIONS'].includes(method)){ headers.set('x-csrf-token', csrf()); } const res=await fetch(path,Object.assign({},init,{headers:headers,credentials:'include'})); const text=await res.text(); try{return {status:res.status, body:JSON.parse(text)}}catch{return {status:res.status, body:text}} }",
+    "function out(v){ document.getElementById('out').textContent=typeof v==='string'?v:JSON.stringify(v,null,2); }",
+    "async function me(){ out(await api('/auth/me')); }",
+    "async function claim(){ out(await api('/api/claims/CLM-1001')); }",
+    "async function addNote(){ out(await api('/api/claims/CLM-1001/notes',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({text:document.getElementById('note').value})})); }",
+    "me().then(out);",
+    "</script></section></body></html>"
+  ].join("");
+}
+
+@Controller()
+class HomeController {
+  @Get()
+  home(@Res() res: Response) {
+    res.type("html").send(homeHtml());
+  }
+}
+
+@Controller("auth")
+class AuthController {
+  @Get("login")
+  async login(@Req() req: Request, @Res() res: Response) {
+    const state = randomToken(24);
+    const nonce = randomToken(24);
+    const verifier = randomToken(48);
+    const loginId = randomToken(24);
+    const returnTo = safeReturnTo(req.query.returnTo);
+    await redis.setex("login:" + loginId, 300, JSON.stringify({ state, nonce, verifier, returnTo }));
+
+    const authorizeUrl = new URL(process.env.IDP_AUTHORIZE_URL || "http://localhost:4400/oauth2/authorize");
+    authorizeUrl.search = new URLSearchParams({
+      response_type: "code",
+      client_id: clientId,
+      redirect_uri: redirectUri,
+      scope: "openid email profile",
+      state,
+      nonce,
+      code_challenge: pkceChallenge(verifier),
+      code_challenge_method: "S256"
+    }).toString();
+
+    res.cookie(loginCookie, loginId, cookieOptions(true, 5 * 60 * 1000));
+    res.redirect(authorizeUrl.toString());
+  }
+
+  @Get("callback")
+  async callback(@Req() req: Request, @Res() res: Response) {
+    const code = String(req.query.code || "");
+    const state = String(req.query.state || "");
+    const loginId = String((req as any).cookies?.[loginCookie] || "");
+    const rawLogin = loginId ? await redis.get("login:" + loginId) : null;
+    if (!code || !rawLogin) return res.status(400).send("Missing login session");
+    const login = JSON.parse(rawLogin) as LoginChallenge;
+    if (state !== login.state) return res.status(400).send("Invalid state");
+
+    const tokenRes = await fetch(process.env.IDP_TOKEN_URL || "http://localhost:4400/oauth2/token", {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: redirectUri, client_id: clientId, code_verifier: login.verifier })
+    });
+    if (!tokenRes.ok) return res.status(502).send(await tokenRes.text());
+    const tokens = await tokenRes.json() as TokenSet;
+
+    const userRes = await fetch(process.env.IDP_USERINFO_URL || "http://localhost:4400/oauth2/userInfo", {
+      headers: { authorization: "Bearer " + tokens.access_token }
+    });
+    const user = await userRes.json() as { sub: string; email?: string; name?: string };
+    const sessionId = randomToken(32);
+    const csrfToken = randomToken(32);
+    const session: SessionRecord = {
+      user,
+      csrfToken,
+      tokens: { ...tokens, expiresAt: Math.floor(Date.now() / 1000) + (tokens.expires_in || 900) }
+    };
+
+    await redis.del("login:" + loginId);
+    await redis.setex("sess:" + sessionId, 30 * 60, JSON.stringify(session));
+    res.clearCookie(loginCookie, { path: "/" });
+    res.cookie(sessionCookie, sessionId, cookieOptions(true, 30 * 60 * 1000));
+    res.cookie("XSRF-TOKEN", csrfToken, cookieOptions(false, 30 * 60 * 1000));
+    res.redirect(login.returnTo || bffBaseUrl + "/");
+  }
+
+  @Get("me")
+  async me(@Req() req: Request, @Res() res: Response) {
+    const session = await loadSession(req);
+    if (!session) return res.status(401).json({ authenticated: false });
+    res.json({ authenticated: true, user: session.value.user });
+  }
+
+  @Post("logout")
+  async logout(@Req() req: Request, @Res() res: Response) {
+    const session = await loadSession(req);
+    if (session && !assertCsrf(req, res, session.value)) return;
+    if (session) await redis.del("sess:" + session.id);
+    res.clearCookie(sessionCookie, { path: "/" });
+    res.clearCookie("XSRF-TOKEN", { path: "/" });
+    res.status(204).send();
+  }
+}
+
+@Controller("api/claims")
+class ClaimsController {
+  @Get(":claimId")
+  async getClaim(@Param("claimId") claimId: string, @Req() req: Request, @Res() res: Response) {
+    const session = await requireSession(req, res);
+    if (!session) return;
+    const upstream = await fetch(claimsBaseUrl + "/claims/" + encodeURIComponent(claimId), {
+      headers: { authorization: "Bearer " + session.tokens.access_token, "x-correlation-id": crypto.randomUUID() }
+    });
+    res.status(upstream.status).send(await upstream.text());
+  }
+
+  @Post(":claimId/notes")
+  async addNote(@Param("claimId") claimId: string, @Body() body: unknown, @Req() req: Request, @Res() res: Response) {
+    const session = await requireSession(req, res);
+    if (!session || !assertCsrf(req, res, session)) return;
+    const upstream = await fetch(claimsBaseUrl + "/claims/" + encodeURIComponent(claimId) + "/notes", {
+      method: "POST",
+      headers: { authorization: "Bearer " + session.tokens.access_token, "content-type": "application/json", "x-correlation-id": crypto.randomUUID() },
+      body: JSON.stringify(body)
+    });
+    res.status(upstream.status).send(await upstream.text());
+  }
+}
+
+@Module({ controllers: [HomeController, AuthController, ClaimsController] })
+class AppModule {}
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule, { logger: ["error", "warn", "log"] });
+  app.enableCors({
+    origin(origin, callback) {
+      if (isAllowedLocalOrigin(origin)) return callback(null, true);
+      callback(new Error("Origin not allowed by local BFF lab CORS policy"), false);
+    },
+    credentials: true,
+    methods: ["GET", "POST", "OPTIONS"],
+    allowedHeaders: ["content-type", "x-csrf-token"],
+  });
+  app.use(cookieParser());
+  await app.listen(Number(process.env.PORT || 3000), "0.0.0.0");
+}
+
+bootstrap();
+`,
+    "apps/claims-api/Dockerfile": `FROM node:22-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm install
+COPY tsconfig.json ./
+COPY src ./src
+RUN npm run build
+EXPOSE 4000
+CMD ["npm", "start"]
+`,
+    "apps/claims-api/package.json": `{
+  "name": "claims-api",
+  "private": true,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/main.js"
+  },
+  "dependencies": {
+    "@nestjs/common": "^10.4.15",
+    "@nestjs/core": "^10.4.15",
+    "@nestjs/platform-express": "^10.4.15",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}
+`,
+    "apps/claims-api/tsconfig.json": `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "esModuleInterop": true,
+    "strict": false,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*.ts"]
+}
+`,
+    "apps/claims-api/src/main.ts": `import "reflect-metadata";
+import { Body, Controller, Get, Headers, Module, Param, Post, Res } from "@nestjs/common";
+import { NestFactory } from "@nestjs/core";
+import type { Response } from "express";
+
+const notes: Record<string, Array<{ text: string; createdAt: string }>> = {};
+
+function isAuthorized(value?: string) {
+  return Boolean(value && value.startsWith("Bearer "));
+}
+
+@Controller()
+class HealthController {
+  @Get("health")
+  health() {
+    return { ok: true, service: "claims-api" };
+  }
+}
+
+@Controller("claims")
+class ClaimsController {
+  @Get(":claimId")
+  getClaim(@Param("claimId") claimId: string, @Headers("authorization") authorization: string | undefined, @Res() res: Response) {
+    if (!isAuthorized(authorization)) return res.status(401).json({ error: "Missing bearer token" });
+    res.json({
+      id: claimId,
+      status: "IN_REVIEW",
+      policyNumber: "POL-8842-UK",
+      insuredPerson: "Ava Mensah",
+      lossDate: "2026-05-20",
+      notes: notes[claimId] || []
+    });
+  }
+
+  @Post(":claimId/notes")
+  addNote(@Param("claimId") claimId: string, @Body() body: { text?: string }, @Headers("authorization") authorization: string | undefined, @Res() res: Response) {
+    if (!isAuthorized(authorization)) return res.status(401).json({ error: "Missing bearer token" });
+    const note = { text: String(body?.text || ""), createdAt: new Date().toISOString() };
+    notes[claimId] = [...(notes[claimId] || []), note];
+    res.status(201).json({ claimId, note });
+  }
+}
+
+@Module({ controllers: [HealthController, ClaimsController] })
+class AppModule {}
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule, { logger: ["error", "warn", "log"] });
+  await app.listen(Number(process.env.PORT || 4000), "0.0.0.0");
+}
+
+bootstrap();
+`,
+    "apps/cognito-mock/Dockerfile": `FROM node:22-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm install
+COPY tsconfig.json ./
+COPY src ./src
+RUN npm run build
+EXPOSE 4000
+CMD ["npm", "start"]
+`,
+    "apps/cognito-mock/package.json": `{
+  "name": "local-cognito-mock",
+  "private": true,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/main.js"
+  },
+  "dependencies": {
+    "@nestjs/common": "^10.4.15",
+    "@nestjs/core": "^10.4.15",
+    "@nestjs/platform-express": "^10.4.15",
+    "express": "^4.21.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}
+`,
+    "apps/cognito-mock/tsconfig.json": `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "esModuleInterop": true,
+    "strict": false,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*.ts"]
+}
+`,
+    "apps/cognito-mock/src/main.ts": `import "reflect-metadata";
+import { Body, Controller, Get, Module, Post, Query, Req, Res } from "@nestjs/common";
+import { NestFactory } from "@nestjs/core";
+import crypto from "crypto";
+import express from "express";
+import type { Request, Response } from "express";
+
+type AuthCode = {
+  clientId: string;
+  redirectUri: string;
+  scope: string;
+  nonce: string;
+  codeChallenge: string;
+  expiresAt: number;
+};
+
+const codes = new Map<string, AuthCode>();
+const issuer = process.env.ISSUER_BROWSER || "http://localhost:4400";
+const expectedClientId = process.env.CLIENT_ID || "enterprise-bff";
+const expectedRedirectUri = process.env.REDIRECT_URI || "http://localhost:4300/auth/callback";
+const demoUser = { sub: "user-123", email: "ava.adjuster@example.com", name: "Ava Adjuster" };
+
+function randomToken(bytes = 32) {
+  return crypto.randomBytes(bytes).toString("base64url");
+}
+
+function sha256Base64Url(value: string) {
+  return crypto.createHash("sha256").update(value).digest("base64url");
+}
+
+function jsonPart(value: unknown) {
+  return Buffer.from(JSON.stringify(value)).toString("base64url");
+}
+
+function unsignedJwt(payload: Record<string, unknown>) {
+  return jsonPart({ alg: "none", typ: "JWT" }) + "." + jsonPart(payload) + ".";
+}
+
+function decodeJwt(token: string) {
+  const part = token.split(".")[1] || "";
+  return JSON.parse(Buffer.from(part, "base64url").toString("utf8"));
+}
+
+@Controller(".well-known")
+class DiscoveryController {
+  @Get("openid-configuration")
+  discovery() {
+    return {
+      issuer,
+      authorization_endpoint: issuer + "/oauth2/authorize",
+      token_endpoint: issuer + "/oauth2/token",
+      userinfo_endpoint: issuer + "/oauth2/userInfo",
+      response_types_supported: ["code"],
+      grant_types_supported: ["authorization_code", "refresh_token"],
+      code_challenge_methods_supported: ["S256"]
+    };
+  }
+}
+
+@Controller("oauth2")
+class OAuthController {
+  @Get("authorize")
+  authorize(@Query() query: Record<string, string>, @Res() res: Response) {
+    const clientId = String(query.client_id || "");
+    const redirectUri = String(query.redirect_uri || "");
+    const state = String(query.state || "");
+    const scope = String(query.scope || "openid email profile");
+    const nonce = String(query.nonce || "");
+    const codeChallenge = String(query.code_challenge || "");
+    if (clientId !== expectedClientId || redirectUri !== expectedRedirectUri || !state || !codeChallenge) {
+      return res.status(400).send("Invalid authorize request");
+    }
+
+    if (query.approve !== "1") {
+      const approve = new URL("/oauth2/authorize", issuer);
+      Object.entries(query).forEach(([key, value]) => approve.searchParams.set(key, String(value)));
+      approve.searchParams.set("approve", "1");
+      return res.type("html").send([
+        "<!doctype html><html><head><title>Local Cognito</title><style>body{font-family:Inter,system-ui;background:#111827;color:#f8fafc;padding:40px}main{max-width:640px;margin:auto;border:1px solid #334155;border-radius:16px;padding:24px;background:#0f172a}a{display:inline-block;background:#22c55e;color:#052e16;border-radius:8px;padding:12px 16px;text-decoration:none;font-weight:800}.muted{color:#94a3b8}</style></head><body><main>",
+        "<h1>Local Cognito Hosted UI</h1><p class='muted'>This mock approves a demo user so you can practice the BFF flow locally.</p>",
+        "<p>User: Ava Adjuster &lt;ava.adjuster@example.com&gt;</p><a href='" + approve.toString() + "'>Sign in as Ava</a>",
+        "</main></body></html>"
+      ].join(""));
+    }
+
+    const code = randomToken(24);
+    codes.set(code, { clientId, redirectUri, scope, nonce, codeChallenge, expiresAt: Date.now() + 5 * 60 * 1000 });
+    const callback = new URL(redirectUri);
+    callback.searchParams.set("code", code);
+    callback.searchParams.set("state", state);
+    res.redirect(callback.toString());
+  }
+
+  @Post("token")
+  token(@Body() body: Record<string, string>, @Res() res: Response) {
+    const code = String(body.code || "");
+    const record = codes.get(code);
+    if (!record || record.expiresAt < Date.now()) return res.status(400).json({ error: "invalid_grant" });
+    if (body.client_id !== record.clientId || body.redirect_uri !== record.redirectUri) return res.status(400).json({ error: "invalid_request" });
+    if (sha256Base64Url(String(body.code_verifier || "")) !== record.codeChallenge) return res.status(400).json({ error: "invalid_grant", error_description: "PKCE verification failed" });
+    codes.delete(code);
+
+    const now = Math.floor(Date.now() / 1000);
+    const common = { iss: issuer, aud: record.clientId, iat: now, exp: now + 900, scope: record.scope, ...demoUser };
+    res.json({
+      token_type: "Bearer",
+      expires_in: 900,
+      access_token: unsignedJwt(common),
+      id_token: unsignedJwt({ ...common, nonce: record.nonce }),
+      refresh_token: randomToken(32),
+      scope: record.scope
+    });
+  }
+
+  @Get("userInfo")
+  userInfo(@Req() req: Request, @Res() res: Response) {
+    const token = String(req.headers.authorization || "").replace(/^Bearer\s+/i, "");
+    if (!token) return res.status(401).json({ error: "missing_token" });
+    const payload = decodeJwt(token);
+    res.json({ sub: payload.sub, email: payload.email, name: payload.name });
+  }
+}
+
+@Module({ controllers: [DiscoveryController, OAuthController] })
+class AppModule {}
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule, { logger: ["error", "warn", "log"] });
+  app.use(express.urlencoded({ extended: false }));
+  await app.listen(Number(process.env.PORT || 4000), "0.0.0.0");
+}
+
+bootstrap();
+`,
+  },
+};