Merge pull request #117 from bitloops/modernise/pnpm-frontend-foundation

Adopt Keycloak IAM and fixed to UI style issue

Author: danias

CHANGELOG.md

@@ -4,6 +4,43 @@ All notable changes to this project are documented in this file. The format is
 based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
 project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [1.0.1] - 2026-07-31
+
+### Added
+
+- Keycloak 26.7 with an imported development realm, isolated PostgreSQL
+  database, Compose services, and Kubernetes manifests.
+- OpenID Connect Authorization Code Flow with PKCE in the frontend and
+  standards-based RS256/JWKS access-token validation in the backend.
+- An IAM anti-corruption layer that maps Keycloak issuer/subject identities to
+  internal user UUIDs.
+- A transactional IAM outbox for user registration and email-change
+  integration events.
+- OIDC validation tests covering issuer, audience, authorised client, expiry,
+  verified email, and signing-key rotation, plus identity reconciliation
+  integration tests.
+- React 19.2 and React Router 8.3, including the patched router release for the
+  current RSC action security advisory.
+
+### Changed
+
+- Replaced application-owned credentials and sessions with Keycloak while
+  retaining the IAM bounded context and `/auth/me` reconciliation endpoint.
+- Kept browser access tokens in memory and limited session storage to transient
+  PKCE state.
+- Restored an existing Keycloak SSO session non-interactively when the
+  application opens in another browser window.
+- Regenerated the OpenAPI client after removing local authentication routes.
+- Aligned the root, backend, frontend, and frontend-test package versions at
+  `1.0.1`.
+
+### Removed
+
+- Passport strategies, password hashing, local registration/login commands,
+  locally issued JWTs, and the old `/auth/login` and `/auth/register` routes.
+
 ## [1.0.0] - 2026-07-31
 
 ### Added

K8s.md

@@ -1,45 +1,60 @@
 # Deploying on Kubernetes
 
-The manifests under `k8s` deploy the frontend, backend, PostgreSQL, NATS, and
-the observability services. MongoDB and the former Envoy/gRPC edge are no
-longer part of the deployment.
+The sample manifests under `k8s` deploy the frontend, backend, application
+PostgreSQL, NATS, Keycloak with its own PostgreSQL database, and the
+observability services. MongoDB and the former Envoy/gRPC edge are not part of
+the deployment.
 
-## Prepare images and secrets
+## Prepare images and identity settings
 
-Build and publish the application images, or load them into your local cluster:
+Build and publish the application images, or load them into a local cluster:
 
 ```bash
 docker build -f backend/Dockerfile -t todo-backend:latest .
-docker build -f frontend/Dockerfile -t todo-frontend:latest .
+docker build -f frontend/Dockerfile \
+  --build-arg VITE_API_BASE_URL=http://localhost:8080 \
+  --build-arg VITE_OIDC_AUTHORITY=http://localhost:8090/realms/bitloops \
+  --build-arg VITE_OIDC_CLIENT_ID=todo-frontend \
+  -t todo-frontend:latest .
 ```
 
-For a remote registry, change the image names in
-`k8s/deployment-todo-backend.yaml` and
-`k8s/deployment-todo-frontend.yaml` to immutable, registry-qualified tags.
+For a registry, change both deployment image references to immutable,
+registry-qualified tags. Before applying, replace every value in
+`k8s/secret-bl-postgres-secret.yaml` and
+`k8s/secret-bl-keycloak-secret.yaml`; production secrets belong in an external
+secret manager, not Git.
 
-Before applying the manifests, replace every development value in
-`k8s/secret-bl-postgres-secret.yaml`, especially `POSTGRES_PASSWORD` and
-`JWT_SECRET`. Do not commit production secrets. PostgreSQL is the sole
-application database and uses the `bitloops` database by default.
+The committed realm and hostnames are for local development. For an exposed
+cluster, update all of the following to the same public HTTPS identity origin:
+
+- `KC_HOSTNAME` in `deployment-bl-keycloak.yaml`;
+- `OIDC_ISSUER` in `deployment-todo-backend.yaml`;
+- the frontend `VITE_OIDC_AUTHORITY` build argument; and
+- redirect URIs, post-logout URIs, and web origins in the realm import.
+
+Keep `OIDC_JWKS_URI` on the cluster-internal Keycloak service. Enable realm
+email verification and `OIDC_REQUIRE_VERIFIED_EMAIL` together in production.
 
 ## Validate and apply
 
-Perform a client-side validation first:
+Perform client-side validation first:
 
 ```bash
 kubectl apply --dry-run=client --validate=false -f k8s
 ```
 
-Apply the namespace and resources in dependency order with:
+Apply resources in dependency order:
 
 ```bash
 ./apply_k8s_files.sh
 ```
 
-The application image currently initialises its schemas idempotently at
-startup. For a production deployment, introduce a dedicated migration job
-before scaling the backend beyond one replica.
+Keycloak health and metrics use management port `9000`; do not expose that
+port publicly in a production ingress. The sample uses one replica and a realm
+import for clarity. A production installation should use externally managed
+secrets, TLS, backups, suitable high availability, and a supported ingress
+configuration.
 
-Keycloak is not included in the 1.0.0 manifests. Its proposed database and
-deployment boundary are documented in
-[`docs/keycloak-iam-roadmap.md`](./docs/keycloak-iam-roadmap.md).
+The backend currently creates schemas idempotently at startup. Introduce a
+dedicated migration job before scaling it beyond one replica. More detail is
+in [Keycloak IAM architecture](./docs/keycloak-iam-roadmap.md).

README.md

@@ -4,9 +4,9 @@
 
 Complete working example of using Domain Driven Design (DDD), Hexagonal Architecture, CQRS, Event Sourcing (ES), Event Driven Architecture (EDA), Behaviour Driven Development (BDD) using TypeScript and NestJS.
 
-Current release: **1.0.0**. See the [changelog](./CHANGELOG.md), the
-[backend architecture](./docs/backend-architecture.md), and the proposed
-[Keycloak IAM roadmap](./docs/keycloak-iam-roadmap.md).
+Current release: **1.0.1**. See the [changelog](./CHANGELOG.md), the
+[backend architecture](./docs/backend-architecture.md), and the
+[Keycloak IAM architecture](./docs/keycloak-iam-roadmap.md).
 
 ![ddd-hexagonal-cqrs-es-eda](https://storage.googleapis.com/bitloops-github-assets/ddd-hexagonal-cqrs-es-eda-2.gif)
 
@@ -79,15 +79,15 @@ When a todo is completed, if this is the first completed todo, an email should b
 - **Easy switching between modular monolith and microservices**
 - **Authentication**
 - **Authorization** (Even at the repository level)
-- **Automatic JWT renewal**
+- **OpenID Connect session renewal**
 - **Automatic client code generation using OpenAPI**
 - **Event-sourced Todo aggregate with a transactional outbox**
 
 ## Technologies Used - Overview
 
 Here are listed some of the specific technologies used for the implementation of the project:
 
-- **Authentication**: Application-issued JWTs in 1.0.0, with a documented migration path to [Keycloak](./docs/keycloak-iam-roadmap.md)
+- **Authentication**: [Keycloak](https://www.keycloak.org/) through OpenID Connect Authorization Code Flow with PKCE
 - **Database - Persistence**: [PostgreSQL](https://www.postgresql.org/)
 - **Testing**: [JEST](https://jestjs.io/)
 - **External Communication Protocols**: [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) and server-sent events
@@ -143,6 +143,11 @@ from the terminal inside the project **in order to download and run the necessar
 
 Then the ReactJS front-end application will be visible at: `http://localhost:4173`.
 
+The development realm includes `demo@example.com` with password
+`Todo-Demo-2026!`. Keycloak runs at `http://localhost:8090`; its development
+admin credentials are `admin` / `admin-development-only`. These credentials
+must never be used outside local development.
+
 <p align="center" style="margin-bottom: 0px !important;">
   <img width="400" alt="image" src="https://github.com/bitloops/ddd-hexagonal-cqrs-es-eda/assets/1571105/4570473b-4e67-4050-9935-967acfe0b7c6" alt="Frontend application" align="center">  
 </p>
@@ -192,12 +197,12 @@ The problem in this case is that the email information belongs to the IAM bounde
 
 In this project the decision was to keep a local repository in the Marketing bounded context, of the users and their emails, updated by listening to integration events from the IAM bounded contexts (**user registered** and **user email changed**).
 
-Authentication is currently implemented inside the application for continuity
-with the original example. It is now treated as a transitional adapter rather
-than the intended long-term identity system. The next IAM tranche will move
-credential and session ownership to Keycloak while retaining the IAM bounded
-context and translating OIDC claims through an anti-corruption layer. See the
-[Keycloak IAM roadmap](./docs/keycloak-iam-roadmap.md).
+Keycloak owns credentials and browser sessions, while the IAM bounded context
+owns the application's user identity. An anti-corruption layer validates OIDC
+claims and maps Keycloak's issuer/subject pair to an internal UUID. IAM
+registration and email changes reach Marketing through an application-owned
+transactional outbox, so downstream contexts do not depend on Keycloak. See
+the [Keycloak IAM architecture](./docs/keycloak-iam-roadmap.md).
 
 # V. Running in development mode
 
@@ -243,7 +248,8 @@ cd ddd-hexagonal-cqrs-es-eda
   The frontend is then available at `http://localhost:4173` and the backend at `http://localhost:8080`.
 - For local backend development, start only its infrastructure dependencies:
   ```bash
-  docker compose -p bitloops-todo-app up -d bl-nats bl-postgres
+  docker compose -p bitloops-todo-app up -d \
+    bl-nats bl-postgres bl-keycloak-postgres bl-keycloak
   ```
 - For local backend development, copy `backend/.template-env` to `backend/.development.env` and replace the development-only values.
 - Run:
@@ -257,7 +263,9 @@ cd ddd-hexagonal-cqrs-es-eda
 ### Test the application is running
 
 In order to test the application is running we could use a client  
-The application uses **REST** for authentication and todo operations, with **server-sent events (SSE)** for realtime client updates.
+The application uses **OpenID Connect** with Keycloak for authentication,
+**REST** for Todo operations, and **server-sent events (SSE)** for realtime
+client updates.
 
 Those tools could be helpful in the development process as well.
 

apply_k8s_files.sh

@@ -8,21 +8,28 @@ kubectl apply -f namespace-bitloops.yaml
 
 # Apply ConfigMaps, Secrets, and Persistent Volume Claims
 kubectl apply -f configmap-bl-grafana-config.yaml
+kubectl apply -f configmap-bl-keycloak-realm.yaml
 kubectl apply -f secret-bl-postgres-secret.yaml
+kubectl apply -f secret-bl-keycloak-secret.yaml
 kubectl apply -f pvc-bl-nats-data.yaml
 kubectl apply -f pvc-bl-postgres-data.yaml
+kubectl apply -f pvc-bl-keycloak-postgres-data.yaml
 kubectl apply -f pvc-bl-prometheus-data.yaml
 kubectl apply -f pvc-bl-grafana-data.yaml
 
 # Apply Deployments and Services
-kubectl apply -f deployment-todo-frontend.yaml
-kubectl apply -f service-todo-frontend.yaml
-kubectl apply -f deployment-todo-backend.yaml
-kubectl apply -f service-todo-backend.yaml
 kubectl apply -f deployment-bl-nats.yaml
 kubectl apply -f service-bl-nats.yaml
 kubectl apply -f deployment-bl-postgres.yaml
 kubectl apply -f service-bl-postgres.yaml
+kubectl apply -f deployment-bl-keycloak-postgres.yaml
+kubectl apply -f service-bl-keycloak-postgres.yaml
+kubectl apply -f deployment-bl-keycloak.yaml
+kubectl apply -f service-bl-keycloak.yaml
+kubectl apply -f deployment-todo-backend.yaml
+kubectl apply -f service-todo-backend.yaml
+kubectl apply -f deployment-todo-frontend.yaml
+kubectl apply -f service-todo-frontend.yaml
 kubectl apply -f deployment-bl-prometheus-nats-exporter.yaml
 kubectl apply -f service-bl-prometheus-nats-exporter.yaml
 kubectl apply -f deployment-bl-jaeger.yaml

backend/.template-env

@@ -1,6 +1,10 @@
-# copy and rename this to .development.env to add your configurations
-JWT_SECRET=p2s5v8x/A?D(G+KbPeShVmYq3t6w9z$B # !!! replace this with your own secret
-JWT_LIFETIME_SECONDS=3600
+# Copy and rename this file to .development.env for local backend development.
+OIDC_ISSUER=http://localhost:8090/realms/bitloops
+OIDC_AUDIENCE=todo-api
+OIDC_CLIENT_ID=todo-frontend
+OIDC_JWKS_URI=http://localhost:8090/realms/bitloops/protocol/openid-connect/certs
+OIDC_REQUIRE_VERIFIED_EMAIL=false
+OIDC_CLOCK_TOLERANCE_SECONDS=5
 HTTP_IP=localhost
 PG_HOST=localhost
 PG_PORT=5432

backend/development-steps.md

@@ -6,7 +6,7 @@
 - Corepack with the repository-pinned pnpm version
 - Docker and Docker Compose
 
-Install the complete workspace from the repository root:
+Install the workspace from the repository root:
 
 ```bash
 corepack enable
@@ -15,44 +15,47 @@ pnpm install --frozen-lockfile
 
 ## Configuration and infrastructure
 
-Copy `backend/.template-env` to `backend/.development.env` and replace the
-development JWT secret. Start PostgreSQL and NATS:
+Copy `backend/.template-env` to `backend/.development.env`. Start the backend's
+dependencies, including the OIDC issuer:
 
 ```bash
-docker compose -p bitloops-todo-app up -d bl-postgres bl-nats
+docker compose -p bitloops-todo-app up -d \
+  bl-postgres bl-nats bl-keycloak-postgres bl-keycloak
 ```
 
-PostgreSQL is the only application database. The backend creates the IAM,
-Marketing, Todo event-store, projection, and outbox tables idempotently during
-startup.
+The default issuer is `http://localhost:8090/realms/bitloops`; the backend uses
+the internal Keycloak URL only for JWKS retrieval. PostgreSQL is the only
+application database. Keycloak owns a separate database that application code
+must not access.
 
 Start the backend in watch mode:
 
 ```bash
 pnpm --dir backend start:dev
 ```
 
-The REST API listens on `http://localhost:8080`, Swagger UI is available at
-`/api`, and the OpenAPI document at `/api-json`.
+The REST API listens on `http://localhost:8080`, Swagger UI is at `/api`, and
+the OpenAPI document is at `/api-json`.
 
 ## Module boundaries
 
 - `src/api` contains REST and SSE driving adapters.
 - `src/lib/bounded-contexts` contains application and domain code.
-- `src/bounded-contexts` contains PostgreSQL, NATS, and service adapters.
+- `src/bounded-contexts` contains OIDC, PostgreSQL, NATS, and service adapters.
 - `src/lib/infra` contains reusable NestJS infrastructure.
 
-Controllers dispatch commands and queries through NATS request/reply. The Todo
-write adapter reconstructs aggregates from `todo_events`, then commits events,
-the query projection, and outbox rows in one PostgreSQL transaction. See
-[`../docs/backend-architecture.md`](../docs/backend-architecture.md).
+The OIDC guard validates the external access token and the IAM repository
+reconciles it to an internal UUID. Controllers dispatch Todo commands and
+queries through NATS. The Todo write adapter reconstructs aggregates from
+`todo_events`, then commits events, projection updates, and outbox rows in one
+transaction. See [backend architecture](../docs/backend-architecture.md).
 
 ## Validation
 
 ```bash
-pnpm --dir backend run build
-pnpm --dir backend run lint
-pnpm --dir backend run test
+pnpm --dir backend build
+pnpm --dir backend lint
+pnpm --dir backend test
 ```
 
 Run the database integration lane against an isolated test database:
@@ -61,19 +64,16 @@ Run the database integration lane against an isolated test database:
 PG_DATABASE=bitloops_test \
 PG_USER=user \
 PG_PASSWORD=postgres \
-pnpm --dir backend run test:integration
+pnpm --dir backend test:integration
 ```
 
-## Tracing
+## IAM configuration
 
-Register `TracingModule` with the system message bus and apply `@Traceable` to
-async application or adapter methods. Tracing publication is deliberately
-isolated from business results: an observability outage must not turn a valid
-command into an HTTP failure.
+`OIDC_ISSUER`, `OIDC_AUDIENCE`, and `OIDC_CLIENT_ID` are mandatory.
+`OIDC_JWKS_URI` supports an internal JWKS endpoint while issuer validation
+continues to use the public URL. Enable `OIDC_REQUIRE_VERIFIED_EMAIL` in
+environments whose Keycloak realm enforces email verification.
 
-## IAM direction
-
-The application-owned password and JWT implementation is transitional. New IAM
-work should follow the
-[`../docs/keycloak-iam-roadmap.md`](../docs/keycloak-iam-roadmap.md) and keep
-Keycloak behind an OpenID Connect anti-corruption adapter.
+Keycloak remains behind `IdentityProviderPort`; application and domain code
+must not import Keycloak libraries or consume Keycloak database records. See
+[Keycloak IAM architecture](../docs/keycloak-iam-roadmap.md).