keycloak init

auth/keycloak-architecture.md

@@ -0,0 +1,89 @@
+# Keycloak Architecture
+
+This repository generates a fullstack CRUD application with **default Keycloak authentication and authorization**. Authentication is not an optional add-on and must not be described as a manual post-generation task.
+
+---
+
+# Default Auth Model
+
+The generated application must use this runtime topology:
+
+- **Frontend:** SPA served by Vite + React Admin
+- **Backend:** NestJS API
+- **Auth transport:** `Authorization: Bearer <access_token>`
+- **Identity provider:** external Keycloak server
+
+The generated application must **not** use:
+
+- a BFF layer
+- cookie/session authentication
+- a custom in-app username/password login form
+
+The generated application must use **redirect-based Keycloak login** only.
+
+---
+
+# Auth Is Part of Default Generation
+
+The generator must produce:
+
+- authenticated frontend bootstrap and request flow
+- authenticated backend bootstrap and request guards
+- auth-aware env examples
+- auth-aware validation rules
+- a root-level Keycloak realm import artifact that describes the Keycloak realm/client bootstrap
+
+Repository defaults may use names such as `toir`, `toir-frontend`, `toir-backend`, and `toir-realm.json`, but future generations must parameterize realm name, client IDs, production URLs, and artifact filename from the generated project or explicit auth configuration.
+
+The generated application must not require a separate prompt step such as "now add auth manually".
+
+---
+
+# Public and Protected Routes
+
+The generated backend must keep:
+
+- `GET /health` — public
+
+All generated CRUD routes must be protected by default.
+
+Authorization must be role-based and must use **only** Keycloak realm roles from `realm_access.roles`.
+
+---
+
+# Default Role Policy
+
+Apply these RBAC defaults to generated CRUD controllers:
+
+- `GET` list/detail: `viewer`, `editor`, `admin`
+- `POST`, `PATCH`, `PUT`: `editor`, `admin`
+- `DELETE`: `admin`
+
+The frontend may use roles for display and permission awareness, but the backend remains the enforcement point.
+
+---
+
+# Token Contract
+
+Generated auth context must guarantee that access tokens used by the SPA and API reliably contain:
+
+- `sub`
+- `aud`
+- `realm_access.roles`
+
+The frontend client and backend audience/client must be documented explicitly. The generator must not rely on undocumented Keycloak defaults for these claims.
+
+---
+
+# Runtime Boundaries
+
+The repository's local runtime topology remains unchanged:
+
+- `docker-compose.yml` provisions PostgreSQL only
+- Keycloak remains external to this repo's Docker runtime
+
+The generator must therefore produce:
+
+- runtime documentation for importing/configuring the generated realm import artifact
+- env contracts for frontend and backend
+- validation rules that assume an external but reachable Keycloak server