feat: pluggable auth — AuthProvider contract + Keycloak OIDC module + bearer tokens

.github/workflows/pr.yml

@@ -147,6 +147,9 @@ jobs:
  SM_SECRET_KEY: ci-test-key
  SM_USERS_BOOTSTRAP_EMAIL: admin@example.com
  SM_USERS_BOOTSTRAP_PASSWORD: admin
+ # Exclude Keycloak module — SM020 prevents both users and keycloak
+ # from running simultaneously. E2E tests use the users module.
+ SM_MODULES_ENABLED: '["Auth","Users","Dashboard","Permissions","Settings","BackgroundTasks","FileStorage","FeatureFlags"]'
  E2E_BASE_URL: http://localhost:8000
  steps:
  - uses: actions/checkout@v6

CLAUDE.md

@@ -78,7 +78,7 @@ Standard mixins in `simple_module_db.mixins`: `AuditMixin`, `SoftDeleteMixin` (b
 
 ## Diagnostic codes
 
-Meaningful codes when reading `make doctor` output: `SM001` missing meta (error), `SM003` orphan page / `SM004` phantom render (warn), `SM007` module overrides no hooks (info), `SM008` duplicate name (error), `SM009` framework→plugin import (error), `SM010` DB revision behind head (error), `SM011` module table not in migration history (warn), `SM012` `register_settings` overridden but nothing on `app.state.<module>` (warn, fires at dev boot only), `SM013`–`SM016` locale issues, `SM017` module ships `.tsx` pages but is missing `package.json`/`tsconfig.json` (warn), `SM018` Inertia `router.{post,patch,put,delete}()` in a page targets a JSON `/api/*` endpoint (warn — Inertia rejects non-Inertia responses), `SM019` module registers view routes (non-empty `view_prefix` + overrides `register_routes`) but overrides neither `register_menu_items` nor `register_permissions` (warn — pages exist with no sidebar entry and no role-editor visibility; admins can't reach them through the UI). Modules whose views are sub-pages of another module typically register permissions to stay discoverable in the role editor without needing their own sidebar entry. In production, errors fail boot.
+Meaningful codes when reading `make doctor` output: `SM001` missing meta (error), `SM003` orphan page / `SM004` phantom render (warn), `SM007` module overrides no hooks (info), `SM008` duplicate name (error), `SM009` framework→plugin import (error), `SM010` DB revision behind head (error), `SM011` module table not in migration history (warn), `SM012` `register_settings` overridden but nothing on `app.state.<module>` (warn, fires at dev boot only), `SM013`–`SM016` locale issues, `SM017` module ships `.tsx` pages but is missing `package.json`/`tsconfig.json` (warn), `SM018` Inertia `router.{post,patch,put,delete}()` in a page targets a JSON `/api/*` endpoint (warn — Inertia rejects non-Inertia responses), `SM019` module registers view routes (non-empty `view_prefix` + overrides `register_routes`) but overrides neither `register_menu_items` nor `register_permissions` (warn — pages exist with no sidebar entry and no role-editor visibility; admins can't reach them through the UI). Modules whose views are sub-pages of another module typically register permissions to stay discoverable in the role editor without needing their own sidebar entry. `SM020` multiple auth provider modules installed (error), `SM021` no auth provider module installed (warn). In production, errors fail boot.
 
 ## Tests & fixtures
 

docs/framework-conventions.md

@@ -241,12 +241,31 @@ async def create_order(...): ...
 
 The `auth` module exposes a principal-resolver chain on
 `app.state.auth.principal_resolvers` — a list of async callables that
-`users.AuthMiddleware` consults after the session-cookie path. Use it to add
+`AuthMiddleware` consults after the session-cookie path. Use it to add
 non-cookie credential sources (Personal Access Tokens, API keys, JWTs)
 without forking the middleware. See
 [`docs/framework/principal-resolvers.md`](framework/principal-resolvers.md)
 for the contract, ordering rules, and a worked Bearer-token example.
 
+### Auth Provider Contract
+
+The framework supports swappable authentication backends. Exactly one auth provider
+module must be installed — either `simple-module-users` (local credentials + OAuth)
+or `simple-module-keycloak` (Keycloak OIDC). Both implement the `AuthProvider`
+protocol from `auth.contracts.provider`.
+
+**Module authors never import from `users` or `keycloak` directly.** Use only:
+- `from auth.deps import CurrentUser, require_permission`
+- `from auth.contracts.schemas import UserContext`
+
+The `AuthMiddleware` (in `auth/middleware.py`) delegates to the active provider's
+`resolve_user()` method, then falls through to the principal-resolver chain.
+API paths (`/api/*`) receive 401 JSON when unauthenticated; view paths receive
+a 302 redirect to the provider's login URL.
+
+Boot-time diagnostic `SM020` fails if multiple auth providers are installed.
+`SM021` warns if none is installed.
+
 ## Events
 
 Base class: `Event` from `simple_module_core.events`. Subclass per domain event:
@@ -290,6 +309,8 @@ Dispatch walks the event's MRO, so subscribing to a base class delivers subclass
 | SM014 | WARNING | Non-default locale missing keys present in the default |
 | SM015 | WARNING | Non-default locale has keys not in the default |
 | SM016 | ERROR | Locale JSON invalid or contains non-string leaves |
+| SM020 | ERROR | Multiple auth provider modules installed |
+| SM021 | WARNING | No auth provider module installed |
 
 Diagnostics run automatically at boot — warnings print to stderr in dev, errors abort startup in production. There's no separate "run diagnostics" step in a scaffolded app: just start the server.