KIS-TOiR/prompts/auth-rules.md

Auth Rules

This repository keeps the current LLM-first CRUD generation architecture as the primary working baseline.

• Auth is part of the default generation path, not a post-generation addon.
• server/ is the active backend target output path.
• client/ is the active frontend target output path.
• The generated runtime stays SPA + API + external Keycloak + PostgreSQL only.

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 provider seams.
• Derive identity from token claims already present in the parsed token.
• Do not call loadUserProfile() and do not depend on /account for the baseline app.
• 401 must force re-authentication; 403 must stay an authorization error.
• Keep token handling in memory and refresh through one shared in-flight operation.

Working runtime defaults

Use the already working project defaults unless a prompt explicitly overrides them.

• Frontend Keycloak base URL example:
  • VITE_KEYCLOAK_URL=https://sso.greact.ru
• Frontend realm and client example:
  • VITE_KEYCLOAK_REALM=toir
  • VITE_KEYCLOAK_CLIENT_ID=toir-frontend
• Backend issuer and audience example:
  • KEYCLOAK_ISSUER_URL=https://sso.greact.ru/realms/toir
  • KEYCLOAK_AUDIENCE=toir-backend
• CORS example:
  • CORS_ALLOWED_ORIGINS=http://localhost:5173,https://toir-frontend.greact.ru

Anti-regression rule:

• Do not switch the baseline Keycloak example back to http://localhost:8080 in generated .env.example files unless the prompt explicitly asks for a local Keycloak runtime.
• Localhost Keycloak values may exist in private .env.local or .env overrides, but they are not the default project examples.

Backend auth invariants

• Verify JWTs with jose.
• Validate issuer + audience + 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 and all generated CRUD routes protected by default.

Auth anti-regression invariants

• The accepted JWKS resolution chain above is the only baseline truth path. Do not document one order and implement another.
• If auth implementation changes, prompts/auth-rules.md and prompts/validation-rules.md must be updated in the same change.
• Do not skip OIDC discovery when no explicit KEYCLOAK_JWKS_URL is provided.
• Do not switch role extraction to alternative claims unless the prompt explicitly changes the baseline contract.
• Do not reintroduce localhost Keycloak defaults into shared baseline examples.

Realm artifact contract

• A physical root-level *-realm.json artifact is mandatory output.
• The artifact must be importable, versioned, and aligned with generated backend/frontend env contracts.
• It must parameterize:
  • realm name
  • frontend client id
  • backend client id / audience
  • local and production frontend URLs
  • artifact filename
• It must explicitly deliver:
  • sub
  • aud
  • realm_access.roles
• It must define:
  • realm roles admin, editor, viewer
  • a public SPA client with PKCE S256
  • a bearer-only backend client
  • an explicit audience client scope
  • explicit protocol mappers for baseline identity and role claims