# Auth Rules

<!-- prompt-version: 2.0 -->
<!-- applies-to: client/src/auth/, server/src/auth/, toir-realm.json -->
<!-- validated-by: tools/validate-generation.mjs §validateAuthChecks §validateRealmChecks -->

Use this document during the **Auth / Runtime / Realm** stage defined in `prompts/general-prompt.md`.

## Purpose

Generate and preserve the auth contracts that let the CRUD app run as a React Admin SPA backed by a NestJS API protected by external Keycloak.

## Mandatory Inputs

- `prompts/general-prompt.md`
- `prompts/runtime-rules.md`
- current repository auth/runtime defaults

## Expected Outputs

- `client/src/auth/`
- `client/src/dataProvider.ts`
- `server/src/auth/`
- `toir-realm.json`

## Frontend Auth Invariants

- use `keycloak-js` with redirect-based login only
- initialize Keycloak before rendering the SPA
- use Authorization Code Flow + PKCE (`S256`)
- keep `authProvider`, `dataProvider`, `getIdentity()`, `getPermissions()`, and `checkError()` as stable seams
- derive identity from token claims already present in the token
- do not call `loadUserProfile()`
- `401` forces re-authentication; `403` remains an authorization error
- keep token handling in memory with one shared in-flight refresh path

## Backend Auth Invariants

- verify JWTs with `jose`
- validate issuer, audience, and signature via JWKS
- resolve JWKS in this order:
  1. `KEYCLOAK_JWKS_URL`
  2. OIDC discovery at `/.well-known/openid-configuration`
  3. `${issuer}/protocol/openid-connect/certs`
- extract roles only from `realm_access.roles`
- keep `/health` public
- generated CRUD routes stay protected by default

## Working Runtime Defaults

Keep these defaults unless a task explicitly overrides them:

- `VITE_KEYCLOAK_URL=https://sso.greact.ru`
- `VITE_KEYCLOAK_REALM=toir`
- `VITE_KEYCLOAK_CLIENT_ID=toir-frontend`
- `KEYCLOAK_ISSUER_URL=https://sso.greact.ru/realms/toir`
- `KEYCLOAK_AUDIENCE=toir-backend`
- `CORS_ALLOWED_ORIGINS=http://localhost:5173,https://toir-frontend.greact.ru`

Anti-regression rule:

- do not revert shared examples to localhost Keycloak defaults unless a task explicitly requests a local Keycloak baseline

## Realm Artifact Contract

The root realm artifact is mandatory and must:

- be importable and versioned
- align with generated frontend/backend env contracts
- parameterize:
  - realm name
  - frontend client id
  - backend client id / audience
  - local and production frontend URLs
  - artifact filename
- explicitly deliver:
  - `sub`
  - `aud`
  - `realm_access.roles`
- define:
  - realm roles `admin`, `editor`, `viewer`
  - a public SPA client with PKCE S256
  - a bearer-only backend client
  - an explicit audience client scope
  - protocol mappers for baseline identity and role claims

## Completion Expectations

Auth/runtime generation is incomplete if any of the following is true:

- frontend and backend auth seams drift from each other
- JWKS resolution order changes
- `/health` stops being public
- shared Keycloak defaults regress to localhost examples
- the realm artifact no longer matches backend/frontend expectations