keycloak init

generation/backend-generation.md

@@ -1,12 +1,14 @@
 # Backend Generation Process
 
-Backend generation follows a pipeline aligned with runtime and validation docs:
+Backend generation follows a pipeline aligned with runtime, auth, and validation docs:
 
 DSL
 ↓
 CLI scaffolding
 ↓
-code generation
+backend code generation
+↓
+auth generation
 ↓
 runtime infrastructure
 ↓
@@ -18,7 +20,18 @@ seed
 ↓
 validation
 
-Follow **backend/runtime-rules.md**, **backend/prisma-rules.md**, **backend/prisma-service.md**, **backend/database-runtime.md**, **backend/seed-rules.md**, and **backend/service-rules.md**.
+Follow:
+
+- `backend/architecture.md`
+- `backend/runtime-rules.md`
+- `backend/prisma-rules.md`
+- `backend/prisma-service.md`
+- `backend/database-runtime.md`
+- `backend/seed-rules.md`
+- `backend/service-rules.md`
+- `auth/keycloak-architecture.md`
+- `auth/backend-auth-rules.md`
+- `auth/keycloak-realm-template-rules.md`
 
 ---
 
@@ -27,10 +40,12 @@ Follow **backend/runtime-rules.md**, **backend/prisma-rules.md**, **backend/pris
 Read DSL inputs and extract:
 
 - entities
-- attributes (including primary key attribute name per entity)
+- attributes, including the actual primary key attribute per entity
 - enums
 - foreign keys
 
+The generator must treat auth as default runtime infrastructure, not as a DSL feature toggle.
+
 ---
 
 # Step 2 — CLI scaffolding
@@ -38,50 +53,118 @@ Read DSL inputs and extract:
 Use official CLIs before generating backend code:
 
 - NestJS project scaffold in `server/` (see `generation/scaffolding-rules.md`)
-- Install backend dependencies (`@prisma/client`, `prisma`, `@nestjs/config`, and seed runner when needed)
+- install backend dependencies:
+  - `@prisma/client`
+  - `prisma`
+  - `@nestjs/config`
+  - `jose`
+  - seed runner when needed by the chosen package tooling
+
+The generator must **not** use deprecated Keycloak-specific Node adapters such as `keycloak-connect`.
 
 ---
 
-# Step 3 — Code generation
+# Step 3 — Core backend code generation
 
 Generate backend source artifacts:
 
-1. **Prisma schema** (`server/prisma/schema.prisma`) from domain DSL:
+1. **Prisma schema** (`server/prisma/schema.prisma`) from the domain DSL:
    - attributes
    - primary keys
    - relations
    - enums
 2. **NestJS modules** per entity:
    - module
-   - controller (path params use actual PK name: `:id`, `:code`, etc.)
-   - service (must sanitize update payload before Prisma — see **backend/service-rules.md**)
+   - controller
+   - service
 3. **DTO files**:
    - `create-entity.dto.ts`
    - `update-entity.dto.ts`
    - `entity.response.dto.ts` (or equivalent)
 4. **PrismaService**:
-   - `OnModuleInit` + `await this.$connect()`
-   - no `beforeExit` hook
-5. **Service update methods**: Sanitize update payload before passing to Prisma (remove `id`, primary key, and readonly attributes from `data`). Do not pass the raw request body as `data` to `prisma.*.update()`.
+   - implement `OnModuleInit`
+   - call `await this.$connect()` in `onModuleInit()`
+   - do not use a `beforeExit` hook
+5. **Service update methods**:
+   - sanitize update payload before Prisma
+   - remove `id`, the entity primary key, and readonly attributes from `data`
+   - do not pass the raw request body directly to `prisma.*.update()`
 
 Use mapping rules from `backend/prisma-rules.md`:
+
 - DSL `decimal` -> DTO `string`
 - DSL `date` -> DTO `string` (ISO)
 
 ---
 
-# Step 4 — Runtime infrastructure
+# Step 4 — Backend auth generation
 
-Generate runtime config files:
+Generate auth infrastructure as part of the normal backend output. Auth must not be deferred to a manual post-step.
+
+Required generated auth artifacts:
+
+- `server/src/auth/auth.module.ts`
+- JWT auth guard
+- roles guard
+- `@Public()` decorator
+- `@Roles()` decorator
+- typed authenticated principal interface
+- typed auth-aware config validation in `server/src/config/`
+
+JWT verification rules:
+
+- verify JWTs with issuer, audience, and JWKS
+- use a standards-based library such as `jose`
+- resolve JWKS in this exact order:
+  1. explicit `KEYCLOAK_JWKS_URL`
+  2. OIDC discovery
+  3. `${issuer}/protocol/openid-connect/certs`
+
+RBAC rules:
+
+- extract authorization roles only from `realm_access.roles`
+- do not infer roles from other claims
+- apply CRUD defaults by HTTP method:
+  - `GET` -> `viewer`, `editor`, `admin`
+  - `POST`, `PATCH`, `PUT` -> `editor`, `admin`
+  - `DELETE` -> `admin`
+- mark `/health` as public with `@Public()`
+
+Controller generation rules:
+
+- generated CRUD controllers must receive auth decorators by default
+- path params must still use the actual entity primary key name (`:id`, `:code`, etc.)
+- public routes must be explicit rather than implicit
+
+---
+
+# Step 5 — Runtime infrastructure
+
+Generate backend runtime config files:
 
 - `server/.env`
 - `server/.env.example`
+- `server/src/config/*` typed validation helpers
 - `server/package.json` lifecycle:
   - `"postinstall": "prisma generate"`
 - `server/package.json` Prisma seed:
-  - `"prisma": { "seed": "ts-node prisma/seed.ts" }` (or `tsx` variant by project standard)
+  - `"prisma": { "seed": "ts-node prisma/seed.ts" }` (or `tsx` equivalent if that is the chosen project standard)
 
-Commands that must be supported/documented:
+The generated backend env contract must include:
+
+- `PORT`
+- `DATABASE_URL`
+- `CORS_ALLOWED_ORIGINS`
+- `KEYCLOAK_ISSUER_URL`
+- `KEYCLOAK_AUDIENCE`
+- `KEYCLOAK_JWKS_URL` (optional)
+
+Fail-fast config rule:
+
+- backend startup must fail fast when required auth or database env vars are missing
+- the generator must not silently fall back to production auth values in code
+
+Commands that must be supported and documented:
 
 - `npx prisma generate`
 - `npx prisma migrate dev`
@@ -89,9 +172,9 @@ Commands that must be supported/documented:
 
 ---
 
-# Step 5 — Database runtime
+# Step 6 — Database runtime
 
-Generator must create `docker-compose.yml` at the **project root** with PostgreSQL.
+Create `docker-compose.yml` at the **project root** with PostgreSQL only.
 
 Minimum required compose characteristics:
 
@@ -99,13 +182,15 @@ Minimum required compose characteristics:
 - `image: postgres:16`
 - `ports: ["5432:5432"]`
 
-Credentials/database in compose must match `DATABASE_URL`.
+Credentials and database name in compose must match `DATABASE_URL`.
+
+Keycloak must remain an external runtime dependency and must not be added to `docker-compose.yml` in this repository.
 
 ---
 
-# Step 6 — Migration
+# Step 7 — Migration
 
-Apply schema to development database:
+Apply schema to the development database:
 
 ```bash
 cd server
@@ -114,7 +199,7 @@ npx prisma migrate dev
 
 ---
 
-# Step 7 — Seed
+# Step 8 — Seed
 
 Run development seed:
 
@@ -127,12 +212,14 @@ Seed file location: `server/prisma/seed.ts`.
 
 ---
 
-# Step 8 — Validation
+# Step 9 — Validation
 
-Run runtime and contract checks from `generation/post-generation-validation.md`, including:
+Run runtime, auth, and contract checks from `generation/post-generation-validation.md`, including:
 
 - docker-compose exists and DB container starts
 - Prisma lifecycle commands succeed
 - seed runs
-- `/health` responds
-- React Admin receives `id` in every record
+- `/health` responds without auth
+- protected routes reject unauthenticated requests with `401`
+- authenticated users with insufficient role receive `403`
+- React Admin-compatible API responses include `id` for every record