fastapi-startkit-auth 0.6.2__tar.gz → 0.6.3__tar.gz

fastapi_startkit_auth-0.6.3/CHANGELOG.md

@@ -0,0 +1,296 @@
+# Changelog
+
+All notable changes to `fastapi-startkit-auth` are documented in this file.
+
+Release notes are also published on
+[GitHub Releases](https://github.com/fastapi-startkit/fastapi-startkit-auth/releases).
+
+## [Unreleased]
+
+### Breaking changes and upgrade notes
+
+Each item lists what changed and what to do.
+
+- **Feature providers replace `Application` and `AuthServiceProvider`.**
+  Register `AuthProvider` first, then the features your guards use:
+  `AuthSessionProvider(SessionConfig)`, `AuthOAuth2Provider(OAuth2Config)` and
+  `AuthApiTokenProvider(ApiTokenConfig)`. Standalone apps call
+  `Provider(config).register(app)`; Startkit apps list the providers in the
+  application. *Migrate:* replace `Application([(AuthProvider, Config)])` with a
+  `FastAPI()` app plus the providers, and `AuthServiceProvider` with
+  `AuthProvider` + the feature providers.
+- **Feature settings moved off `AuthConfig`.** The `session`, `api_tokens` and
+  `spa` dicts are rejected at startup; use `SessionConfig`, `ApiTokenConfig`
+  (`stateful_origins` turns on SPA mode) instead. *Migrate:* move each dict's
+  keys onto the matching dataclass and pass it to its provider.
+- **OAuth settings moved to `OAuth2Config`.** `key`, `algorithm`, the `*_ttl`
+  values, `tokens`, `issuer`, `resources`, `scopes`, `pkce_methods` and
+  `require_pkce` now live on `OAuth2Config`. Setting them on `AuthConfig` still
+  works but emits a `DeprecationWarning`, and an explicit `OAuth2Config` value
+  wins. *Migrate:* move them to `OAuth2Config`; the fallback will be removed in a
+  future release.
+- **Password grant is opt-in.** `OAuth2Config.grant_types` defaults to
+  `["authorization_code", "client_credentials", "refresh_token"]`; `/oauth/token`
+  with `grant_type=password` and `/token` answer `unsupported_grant_type`.
+  *Migrate:* add `"password"` to `grant_types` to keep it.
+- **Client-less refresh tokens need the password grant.** Refresh tokens are now
+  bound to the issuing client: refreshing or revoking one requires that client's
+  authentication. Tokens without a client (issued by the password grant) are only
+  accepted while `"password"` is enabled, and client credentials sent alongside
+  one are authenticated (`invalid_client` if wrong). *Migrate:* send client credentials on
+  refresh; keep `"password"` enabled while old client-less tokens are in use.
+- **Consent is mandatory.** `POST /oauth/authorize` returns `access_denied`
+  unless the body has `"approved": true`, and always returns `iss` (body and
+  redirect, RFC 9207). `response_type` other than `code` fails with
+  `unsupported_response_type`. *Migrate:* send `approved: true` after the user
+  consents; `GET /oauth/authorize` validates a request for your consent screen.
+- **PKCE no longer defaults to S256.** A missing `code_challenge_method` means
+  `plain`, which the default `pkce_methods=["S256"]` refuses. RFC 7636 formats are
+  enforced: an S256 challenge is 43 base64url characters, a verifier 43–128
+  unreserved characters. *Migrate:* always send `code_challenge_method=S256` and
+  a verifier of at least 43 characters.
+- **`client_credentials` is for confidential clients only**; public, revoked or
+  grant-disallowed clients get `unauthorized_client` / `invalid_client`.
+  Confidential clients must authenticate on the code exchange. *Migrate:* give
+  machine clients a secret and list the grant (or leave `grant_types` empty).
+- **Introspection requires a confidential client.** *Migrate:* call
+  `/oauth/introspect` with a confidential client's credentials.
+- **`/oauth/clients` HTTP routes are removed.** *Migrate:* create clients with
+  `auth:oauth2:client` (Startkit) or `manager.client_repository.register(...)`.
+- **Password reset routes** move to their own router, mounted by `AuthProvider`
+  whenever `AuthConfig.passwords` is set (no OAuth needed). Paths are unchanged.
+- **Default guard changed** from `"api"` to `"web"` and `AuthConfig.guards`
+  defaults to empty. *Migrate:* set `default` and `guards` explicitly.
+- **CSRF is always on with sessions**, and also accepts the `_token` form field.
+  *Migrate:* send `X-XSRF-TOKEN` (or `_token`) on unsafe requests, or list paths
+  in `SessionConfig.csrf_exempt_paths`.
+- **OAuth client store defaults to `"database"`** (the ORM `oauth_clients`
+  table). *Migrate:* publish and run the migrations, or set
+  `OAuth2Config(clients=OAuthClientsConfig(store="memory"))`.
+- **The in-memory OAuth client store is async.** `InMemoryClientRepository`
+  methods (`register`, `add`, `find`, `all`, `authenticate`, `revoke`,
+  `delete`) are coroutines, like `OrmClientRepository`, and `store="memory"` now
+  makes the manager build the async refresh and authorization-code grants. A
+  synchronous custom store passed with `store="instance"` keeps the sync grants.
+  *Migrate:*
+  `await` client-store calls and the `handle` / `issue_code` of those grants.
+- **Persistent stores are named `"database"`.** `store="orm"` still works for
+  sessions, API tokens, OAuth tokens and OAuth clients, but emits a
+  `DeprecationWarning` and will be removed in a future release. *Migrate:*
+  replace `store="orm"` with `store="database"`.
+- **Custom token repositories** must implement `consume_refresh_token` and
+  `revoke_token_chain`, and `store_refresh_token` takes `family_id`.
+- Error responses carry `Cache-Control: no-store`; `invalid_client` challenges
+  with `WWW-Authenticate: Basic`.
+
+### Migrations
+
+All additive; the v0.6.x migrations are unchanged. Publish and run them when
+using the ORM stores:
+
+- `2026_10_04_000001_create_oauth_clients_table` — the `oauth_clients` table.
+- `2026_10_04_000002_add_family_id_to_oauth_refresh_tokens_table` — a nullable,
+  indexed `family_id` column on `oauth_refresh_tokens`.
+- `2026_10_05_000001_add_scopes_to_oauth_clients_table` — a nullable `scopes`
+  column on `oauth_clients`; existing rows (NULL) stay unrestricted.
+
+### Added
+
+- Refresh token families with reuse detection: replaying a rotated refresh token
+  revokes the whole family, whoever presents it: the owning client, another
+  authenticated client, or no client at all for unbound password-grant tokens.
+  Refresh tokens are introspectable.
+- `authentication.md`: the full authentication guide.
+- `POST /oauth/revoke` (RFC 7009) revokes the token and its access/refresh chain;
+  `GET`/`DELETE /oauth/tokens` and `DELETE /oauth/tokens/{jti}` let a user list
+  and revoke their OAuth tokens. `DELETE /oauth/personal-access-tokens` revokes
+  all personal access tokens, which also accept a `ttl`.
+- `/.well-known/oauth-authorization-server` metadata (RFC 8414).
+- `OAuth2Config.default_scopes`, `grant_types`, `require_redirect_uri` and
+  `authorization_guard`.
+- `OrmClientRepository` and the `auth:oauth2:client` command (`--public`,
+  `--name`, repeatable `--redirect-uri`).
+- Per-client scope restrictions: `Client.scopes` lists the scopes a client may
+  request (empty means any). A request outside the list, including
+  `default_scopes` applied to a request naming none, fails with `invalid_scope`
+  on `/oauth/authorize`, the `client_credentials` grant and the password grant
+  when a client authenticates. `"*"` is not expanded when matching the allow-list, but a token granted `"*"`
+  passes every `require_scopes` check, so never give a client `"*"` (the command
+  refuses it).
+  Set it with `auth:oauth2:client --scopes`; client repositories gain `revoke`.
+- `AuthMiddleware` and request-scoped facades: `Auth.user()`, `Session.token()`,
+  `ApiToken.create(...)` work on the class inside a request. `Auth.validate`
+  checks credentials without logging in.
+- `auth` dependency; token guards fall back to the SPA session cookie.
+- Guest sessions are persisted lazily, only when the response is sent.
+
+### Added (resource indicators, #27)
+
+- RFC 8707 resource indicators: `OAuth2Config.resources` lists the resources tokens
+  may be bound to. The token endpoint and `/oauth/authorize` accept `resource`;
+  the code and refresh token remember it and the access token carries it as `aud`.
+  Unknown or mismatched resources fail with `invalid_target`.
+- Guards accept an `audience`: a passport guard with `"audience": "<uri>"` only
+  accepts tokens bound to that resource, and resource-bound tokens are refused by
+  guards without it.
+- `OAuth2Config.issuer` stamps and verifies the `iss` claim.
+- `OAuth2Config.scopes` is a scope catalog: when set, grants refuse unknown scopes
+  with `invalid_scope`.
+- `OAuth2Config.pkce_methods` restricts `code_challenge_method` (e.g. `["S256"]`),
+  compared case-insensitively; an unknown `code_challenge_method` is now refused
+  at `/oauth/authorize` with `invalid_request`.
+- `OAuth2Config.require_pkce` demands a `code_challenge` from confidential clients
+  too (OAuth 2.1 / MCP).
+- A repeated `resource` parameter on the token endpoint fails with `invalid_target`.
+- Building a guard whose `audience` is not listed in `OAuth2Config.resources` emits
+  a `UserWarning`.
+- `GrantPolicy`, `InvalidScope` and `InvalidTarget` are exported; introspection
+  reports `aud` and `iss` when present.
+- Migration `add_resource_to_oauth_tables` adds a nullable `resource` column to
+  `oauth_auth_codes` and `oauth_refresh_tokens`; publish and run it when using the
+  ORM store.
+
+### Changed
+
+- **Breaking:** persistence now goes through the fastapi-startkit ORM with models
+  shipped in `fastapi_startkit_auth.orm`; no raw SQL remains. Use
+  `{"store": "orm"}` (optional ORM `connection` name) for sessions, API tokens and
+  OAuth tokens.
+- Requires `pyjwt>=2.10.1`.
+- **Security:** refresh tokens are bound to the client they were issued to
+  (RFC 6749 §6). `RefreshTokenGrant.handle` takes `client_id` and fails with
+  `invalid_grant` when it differs from the token's client; the token endpoint
+  passes the authenticated client. Callers refreshing a client-issued token must
+  now send that client's credentials.
+- **Breaking:** the `startkit` extra now requires `fastapi-startkit[database]>=0.60`.
+- Run the published migrations (`provider:publish -p auth`, then `migrate`) to
+  create the tables; stores no longer create tables themselves.
+
+### Removed
+
+- **Breaking:** the `sql` / `async_sql` stores and the `SqlSessionStore`,
+  `SqlApiTokenRepository`, `AsyncSql*` classes and database adapters.
+
+### Added
+
+- `Client.provider` (and `register(provider=...)`) binds an OAuth client to a
+  user provider. `AuthManager.owner_provider(client_id)` resolves it, falling
+  back to the default guard's provider.
+- `AuthManager.warm_up()` and `AsyncModelUserProvider.warm_up()`, run from the
+  app lifespan by `AuthProvider`, precompute the dummy hash at startup.
+
+### Fixed
+
+- Refresh, authorization-code exchange and introspection re-check the token
+  owner against the provider of the issuing client instead of always using the
+  default guard's provider. The password grant authenticates against the
+  client's provider, and `/oauth/authorize` rejects a client bound to another
+  provider.
+- `AsyncModelUserProvider.is_active` only uses the threadpool for a sync
+  callable hook. Attribute checks and `async def` hooks run inline.
+- The first unknown-user login no longer pays an extra bcrypt hash to create
+  the dummy hash.
+
+## [0.4.0]
+
+### Added
+
+- Async support for async ORMs and drivers, side by side with the sync API:
+  - `AsyncModelUserProvider` (provider driver `"async_model"`) for models whose
+    `find` / `where(...).first()` / `save` are coroutines; bcrypt runs in a
+    worker thread.
+  - `AsyncPassportGuard`, `AsyncSessionGuard`, `AsyncTokenGuard`,
+    `AsyncTokenService`, `AsyncApiTokenManager`, `AsyncPasswordBroker`, the
+    `Async*Grant` variants and the `AsyncAuth` facade.
+  - `AuthManager` picks the async variant automatically when any provider
+    method or store method is async; sync configurations keep getting the sync
+    classes. Sync collaborators used from the async classes run in the
+    threadpool.
+  - `"async_sql"` stores for sessions (`AsyncSqlSessionStore`), personal API
+    tokens (`AsyncSqlApiTokenRepository`) and a new `AuthConfig.tokens` block
+    for OAuth access/refresh tokens and authorization codes
+    (`AsyncSqlTokenRepository`). They accept an asyncpg pool/connection, an
+    aiosqlite connection, or a zero-arg (async) factory. Supported backends are
+    PostgreSQL and SQLite. Refresh tokens and authorization codes are stored as
+    SHA-256 hashes; refresh revocation and code redemption are atomic and use
+    only portable SQL. Expired rows are purged via `expires_at` indexes.
+  - `fastapi-startkit` migrations for the five tables, published to
+    `databases/migrations/` by `AuthServiceProvider`.
+- `password_key` provider option: the credentials key holding the plaintext
+  password, separate from the model column `password_field` (e.g.
+  `password_key="password"`, `password_field="hashed_password"`). Defaults to
+  `password_field`.
+- `is_active` provider option (attribute name or callable; `async def` with
+  the `async_model` driver). Inactive or deleted users are rejected by the
+  password grant, the refresh and authorization-code grants, `Auth.attempt` /
+  `AsyncAuth.attempt` and every guard, and introspect as inactive.
+- `AsyncMisconfiguration`: raised when a sync guard, grant, broker or `Auth`
+  receives an awaitable from a provider or store, so a half-async provider
+  fails closed. Sync providers reject an `async def` `is_active` hook.
+- CI runs the asyncpg store and flow tests against a Postgres service.
+- `Typing :: Typed` classifier (the package already ships `py.typed`).
+
+### Changed
+
+- **Breaking (signature):** `current_context` and `optional_user` are now
+  `async def` dependencies. `Depends(current_user)` and friends keep working
+  unchanged; code calling them directly as plain functions must now await
+  them. Sync guards still run in the threadpool.
+- The built-in OAuth, password-reset and SPA csrf-cookie routes await async
+  collaborators; `SessionMiddleware` accepts an async session store.
+- `Auth` (sync facade) raises `RuntimeError` for async session guards; use
+  `AsyncAuth` there.
+- Minimum supported Python is now 3.10. 0.3.0 advertised `>=3.9` but fails on
+  3.9 because runtime-evaluated annotations use `X | None` syntax.
+- The `startkit` extra is bounded to `fastapi-startkit>=0.51,<1.0`.
+- The package `__init__` imports its public API directly instead of through a
+  lazy export table.
+- The source distribution now ships the test suite and this changelog.
+- `bin/release.sh` uploads to PyPI with `twine upload`, matching
+  fastapi-startkit; the tag-triggered trusted-publishing workflow is removed.
+
+## [0.3.0]
+
+First release published to PyPI. Contains the 0.2.0 feature set, built with
+the `uv_build` backend; no functional changes.
+
+## [0.2.0]
+
+Adds three new authentication modes alongside the existing OAuth2/JWT server,
+so the package now covers the full Laravel-style auth surface.
+
+### Added
+
+- Guard-driver registry in `AuthManager`: guards resolve their driver
+  (`token`, `session`, …) from a pluggable registry, enabling multiple guard
+  types in one application (Phase 0).
+- Cookie/session authentication: `Auth` facade, `SessionGuard`, session
+  middleware, and in-memory + SQL session stores (Phase 1).
+- SPA authentication with CSRF protection: `/__auth__/csrf-cookie` endpoint,
+  double-submit-cookie middleware, and an `AuthServiceProvider` that publishes
+  the `config/cors.py` stub via `provider:publish -p auth` (Phase 2).
+- Sanctum-style API tokens: `TokenGuard`, opaque hashed tokens with abilities,
+  and in-memory + SQL token stores (Phase 3).
+
+### Security / Hardening
+
+- Session guard verifies against a constant-time dummy hash when no user is
+  found, closing a timing side-channel.
+- SQL session and API-token stores prune expired rows; purge cadence is
+  configurable.
+- CSRF cookie endpoint hardened; token repr for `NewApiToken` redacts the
+  plaintext value so it cannot leak into logs.
+- DB-API connection vs. connection-factory detection now probes `execute()`
+  instead of `callable()`, fixing misdetection of raw `sqlite3.Connection`
+  objects in the SQL session and API-token stores.
+
+## [0.1.0]
+
+Initial release.
+
+- Passport-style OAuth2 authorization server for FastAPI: authorization code
+  (with PKCE), password, client credentials, and refresh token grants
+- JWT access tokens with scopes, token guards, and route dependencies
+- Personal access tokens
+- Pluggable user/client providers (in-memory and Masonite ORM)
+- Password reset flow with throttling hardened against account enumeration

{fastapi_startkit_auth-0.6.2 → fastapi_startkit_auth-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-startkit-auth
-Version: 0.6.2
+Version: 0.6.3
 Summary: Laravel-style authentication for FastAPI: OAuth2/JWT authorization server, cookie/session guard, SPA + CSRF protection, and Sanctum-style API tokens.
 Keywords: fastapi,oauth2,jwt,auth,passport,sanctum,authentication,authorization,security,tokens,session,cookie,csrf,spa,starter-kit
 Author: Bedram Tamang
@@ -21,7 +21,7 @@ Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Dist: fastapi>=0.110
-Requires-Dist: pyjwt>=2.8
+Requires-Dist: pyjwt>=2.10.1
 Requires-Dist: bcrypt>=4.1
 Requires-Dist: pydantic>=2
 Requires-Dist: python-multipart>=0.0.9
@@ -51,17 +51,20 @@ to FastAPI: a config-driven guard/provider/passwords model layered on top of
 OAuth2 grants and signed JWT access tokens (per the
 [FastAPI security tutorial](https://fastapi.tiangolo.com/tutorial/security/oauth2-jwt/)).
 
+The full guide — providers, sessions, API tokens, the OAuth 2.1 server, stores
+and migrations — is in [authentication.md](authentication.md).
+
 ## Features
 
 | Area | What you get |
 | --- | --- |
-| **Config layer** | `AuthConfig` (`default` / `guards` / `providers` / `passwords`) + `AuthProvider` that registers into the app |
-| **Password grant** | OAuth2 password grant → signed JWT access tokens with expiry (`/oauth/token`, `/token`) |
-| **Refresh tokens** | Opaque refresh tokens with **rotation** and configurable TTL |
+| **Config layer** | `AuthConfig` (`default` / `guards` / `providers` / `passwords`) + `AuthProvider`, with `SessionConfig` / `OAuth2Config` / `ApiTokenConfig` feature providers |
+| **Password grant** | Opt-in legacy password grant → signed JWT access tokens (`/oauth/token`, `/token`) |
+| **Refresh tokens** | Client-bound opaque refresh tokens with **rotation** and reuse detection |
 | **Personal access tokens** | Named, long-lived tokens with scopes/abilities |
 | **Client credentials** | Machine-to-machine grant |
-| **Authorization code + PKCE** | Browser/SPA flow with S256 & plain PKCE |
-| **Clients** | Register / list / delete confidential & public clients |
+| **Authorization code + PKCE** | OAuth 2.1 flow with S256 PKCE, explicit consent and `iss` (RFC 9207) |
+| **Clients** | ORM client store and the `auth:oauth2:client` command |
 | **Revocation & introspection** | RFC 7009 revoke + RFC 7662 introspect |
 | **Password reset** | `password_reset_tokens` flow with configurable `expire` + `throttle` |
 | **Guards & deps** | `current_user`, `optional_user`, `require_scopes` FastAPI dependencies |
@@ -81,7 +84,7 @@ Optional extras:
 
 | Extra | Installs | Use when |
 | --- | --- | --- |
-| `startkit` | `fastapi-startkit[database]>=0.60,<1.0` (Python 3.12+) | Registering `AuthServiceProvider`, publishing its config stub and migrations via `provider:publish -p auth`, and the `"orm"` stores |
+| `startkit` | `fastapi-startkit[database]>=0.60,<1.0` (Python 3.12+) | Registering the auth providers in a Startkit app, publishing migrations via `provider:publish`, and the `"database"` stores |
 | `masoniteorm` | `masonite-orm` | Using the `masoniteorm` user provider driver |
 
 ```bash
@@ -98,16 +101,16 @@ pins `cleo<2` while `fastapi-startkit` requires `cleo>=2.1`.
 ## Quickstart
 
 ```python
-from fastapi import Depends
-from fastapi_startkit_auth import Application, AuthProvider, AuthConfig, current_user, require_scopes
+from fastapi import Depends, FastAPI
+from fastapi_startkit_auth import (
+    AuthConfig, AuthOAuth2Provider, AuthProvider, OAuth2Config, current_user, require_scopes,
+)
 from myapp.models import User  # any active-record-style model
 
 
 class Config(AuthConfig):
-    key = "change-me-to-a-long-random-secret"   # JWT signing key
-
     default = {"guard": "api", "passwords": "users"}
-    guards = {"api": {"driver": "passport", "provider": "users"}}
+    guards = {"api": {"driver": "oauth2", "provider": "users"}}
     providers = {"users": {"driver": "masoniteorm", "model": User}}
     passwords = {
         "users": {"provider": "users", "table": "password_reset_tokens",
@@ -115,49 +118,76 @@ class Config(AuthConfig):
     }
 
 
-app = Application([(AuthProvider, Config)])
-api = app.api  # the underlying FastAPI instance
+app = FastAPI()
+AuthProvider(Config).register(app)                      # always first
+AuthOAuth2Provider(OAuth2Config(key="change-me-to-a-long-random-secret")).register(app)
 
 
-@api.get("/me")
+@app.get("/me")
 def me(user=Depends(current_user)):
     return user
 
 
-@api.get("/reports")
+@app.get("/reports")
 def reports(ctx=Depends(require_scopes("reports:read"))):
     return {"ok": True}
 ```
 
-Serve it:
+`current_user`, `optional_user`, `auth` and `require_scopes` resolve the request
+through the default guard (`AuthConfig.default["guard"]`); use `Auth.user("name")`
+to read another guard.
 
-```bash
-uvicorn myapp:app        # Application is ASGI-callable
-uvicorn myapp:app.api    # or serve the FastAPI instance directly
+In a Startkit application, list `AuthProvider` and then the feature providers in
+the application's providers instead:
+
+```python
+from fastapi_startkit import Application
+
+app = Application(
+    providers=[
+        (AuthProvider, Config),
+        (AuthOAuth2Provider, OAuth2Config(key="change-me-to-a-long-random-secret")),
+    ]
+)
 ```
 
+See [Registering the providers](authentication.md#registering-the-providers).
+
 ## Configuration
 
-`AuthConfig` mirrors Laravel's `config/auth.php` and adds JWT/token knobs:
+`AuthConfig` mirrors Laravel's `config/auth.php`: guards, user providers and
+password brokers. Each feature has its own config, handed to its provider:
+
+| Provider | Config | Enables |
+| --- | --- | --- |
+| `AuthSessionProvider` | `SessionConfig` | cookie sessions (`"session"` guards), CSRF |
+| `AuthOAuth2Provider` | `OAuth2Config` | the OAuth 2.1 server (`"oauth2"` guards; `"passport"` is an alias) |
+| `AuthApiTokenProvider` | `ApiTokenConfig` | opaque API tokens (`"token"` guards), SPA mode |
 
 ```python
-class AuthConfig:
-    default   = {"guard": "api", "passwords": "users"}
-    guards    = {"api": {"driver": "passport", "provider": "users"}}
-    providers = {"users": {"driver": "masoniteorm", "model": User}}
-    passwords = {"users": {"provider": "users", "table": "password_reset_tokens",
-                            "expire": 60, "throttle": 60}}
-
-    # token settings (all optional, sensible defaults shown)
-    key                        = None          # JWT secret (required in production)
-    algorithm                  = "HS256"
-    access_token_ttl           = 3600          # seconds
-    refresh_token_ttl          = 60 * 60 * 24 * 14
-    personal_access_token_ttl  = 60 * 60 * 24 * 365
-    authorization_code_ttl     = 600
-    bcrypt_rounds              = 12
+OAuth2Config(
+    key=None,                     # JWT secret (required in production)
+    algorithm="HS256",
+    access_token_ttl=3600,
+    refresh_token_ttl=60 * 60 * 24 * 14,
+    authorization_code_ttl=600,
+    issuer=None,                  # stamps and verifies `iss`
+    resources=[],                 # RFC 8707 resource indicators
+    scopes={},                    # scope catalog; empty accepts any scope
+    default_scopes=[],
+    pkce_methods=["S256"],
+    require_pkce=True,
+    require_redirect_uri=True,
+    grant_types=["authorization_code", "client_credentials", "refresh_token"],
+    tokens=OAuthTokensConfig(store="memory"),
+    clients=OAuthClientsConfig(store="database"),  # the default; needs the migrations
+)
 ```
 
+Add `"password"` to `grant_types` to enable the legacy password grant (and the
+`/token` endpoint). The OAuth settings formerly on `AuthConfig` (`key`,
+`issuer`, `scopes`, ...) are still read from there with a `DeprecationWarning`.
+
 ### Provider drivers
 
 | driver | meaning |
@@ -204,7 +234,7 @@ introspection re-check the token owner against it. A client without a
 client bound to a different provider with `unauthorized_client`:
 
 ```python
-client, secret = manager.client_repository.register(name="admin-panel", provider="admins")
+client, secret = await manager.client_repository.register(name="admin-panel", provider="admins")
 ```
 
 ### ORM stores and migrations
@@ -217,20 +247,25 @@ in `fastapi-startkit[database]`). The package ships its own models
 (`fastapi_startkit_auth.orm`) and uses no raw SQL:
 
 ```python
-session = {"store": "orm"}
-api_tokens = {"store": "orm"}
-tokens = {"store": "orm", "connection": "auth"}  # optional ORM connection name
+SessionConfig(store="database")
+ApiTokenConfig(store="database")
+OAuth2Config(tokens=OAuthTokensConfig(store="database", connection="auth"))  # optional ORM connection name
 ```
 
+`"database"` is the persistent store for all four configs. Only
+`OAuthClientsConfig` uses it by default; `SessionConfig`, `ApiTokenConfig` and
+`OAuthTokensConfig` default to `"memory"`.
+
 `connection` names an entry of your database config; omit it to use the default
-connection. Publish and run the migrations once per app (they are reversible
-and create the `sessions`, `personal_api_tokens`, `oauth_access_tokens`,
-`oauth_refresh_tokens` and `oauth_auth_codes` tables with their indexes):
+connection. Publish and run the migrations once per app. Each provider
+publishes its own (all reversible and additive): sessions, personal API tokens,
+and the OAuth access/refresh token, auth code and client tables plus the
+`resource` and refresh `family_id` columns:
 
 ```bash
-python artisan provider:publish -p auth   # copies them to databases/migrations/
-python artisan migrate
-python artisan migrate:rollback           # drops them again
+python artisan provider:publish -p auth-oauth2   # copies them to databases/migrations/
+python artisan db:migrate
+python artisan db:migrate:rollback        # drops them again
 ```
 
 Single-use guarantees rely on conditional `UPDATE`/`DELETE` statements issued
@@ -238,7 +273,8 @@ through the ORM query builder: refresh-token rotation and authorization-code
 redemption each have exactly one winner under concurrency.
 
 The former `sql` and `async_sql` stores were removed; configuring them raises a
-`ValueError` pointing at `"orm"`. Use `"memory"` or an `"instance"` store for
+`ValueError` pointing at `"database"`. `"orm"` is a deprecated alias of
+`"database"` and emits a `DeprecationWarning`. Use `"memory"` or an `"instance"` store for
 sync setups.
 
 In mixed setups (async stores with a sync provider or a sync session store),
@@ -256,13 +292,15 @@ one bcrypt verify, the same as a wrong password.
 
 | Method & path | Purpose |
 | --- | --- |
-| `POST /oauth/token` | Unified token endpoint: `password`, `refresh_token`, `client_credentials`, `authorization_code` |
-| `POST /token` | Simple password grant (FastAPI-tutorial style) |
-| `POST /oauth/authorize` | Approve an auth-code request (requires an authenticated user) → returns `code` |
-| `POST /oauth/introspect` | RFC 7662 token introspection (**requires client authentication**) |
-| `POST /oauth/revoke` | RFC 7009 access/refresh token revocation (**requires client authentication**) |
-| `POST/GET /oauth/clients`, `DELETE /oauth/clients/{id}` | Client registration & management |
-| `POST/GET /oauth/personal-access-tokens`, `DELETE .../{jti}` | Personal access tokens |
+| `GET /.well-known/oauth-authorization-server` | RFC 8414 server metadata |
+| `POST /oauth/token` | Token endpoint: `authorization_code`, `refresh_token`, `client_credentials` (+ `password` when enabled) |
+| `POST /token` | Simple password grant (only when `"password"` is enabled) |
+| `GET /oauth/authorize` | Validate an auth-code request for your consent screen |
+| `POST /oauth/authorize` | Issue a code once the user consents (`"approved": true`) → `code`, `iss` |
+| `POST /oauth/introspect` | RFC 7662 introspection (**confidential client authentication**) |
+| `POST /oauth/revoke` | RFC 7009 revocation of a token and its chain (**client authentication**) |
+| `GET/DELETE /oauth/tokens`, `DELETE /oauth/tokens/{jti}` | The user's OAuth tokens |
+| `POST/GET/DELETE /oauth/personal-access-tokens`, `DELETE .../{jti}` | Personal access tokens |
 | `POST /password/email` | Trigger a password-reset token (delivered out-of-band; see below) |
 | `POST /password/reset` | Reset the password with a token |
 
@@ -278,12 +316,21 @@ class AuthConfig(BaseAuthConfig):
     # debug_expose_reset_token = True   # DEV ONLY: echo the token in the response
 ```
 
-The `code_challenge` for public clients is mandatory — a public (secretless)
-client cannot obtain an authorization code without PKCE, and codes are verified
-against the `code_verifier` at exchange.
+PKCE is required by default (`require_pkce=True`, `pkce_methods=["S256"]`):
+send `code_challenge_method=S256` with a 43-character challenge, and a verifier
+of 43–128 characters at exchange. A missing method means `plain`.
+
+Clients are created with `python artisan auth:oauth2:client --name app
+--redirect-uri https://app/cb [--public] [--scopes "read write"]` or
+`manager.client_repository.register(...)`; there are no `/oauth/clients` HTTP
+routes. Refresh tokens are bound to their client. Replaying a rotated refresh
+token revokes its whole family, whoever presents it; see
+[Refresh tokens](authentication.md#refresh-tokens).
 
 ### Example: password grant
 
+With `"password"` in `OAuth2Config.grant_types`:
+
 ```bash
 curl -X POST localhost:8000/oauth/token \
   -d grant_type=password -d username=ada@example.com -d password=secret -d scope="read write"
@@ -293,8 +340,8 @@ curl -X POST localhost:8000/oauth/token \
 
 ### Example: authorization code + PKCE
 
-1. `POST /oauth/authorize` with a bearer token and `code_challenge` → returns a single-use `code`.
-2. `POST /oauth/token` with `grant_type=authorization_code`, the `code`, and the `code_verifier`.
+1. `POST /oauth/authorize` as the signed-in user (resolved through `OAuth2Config.authorization_guard`, default: the default guard) with `client_id`, `redirect_uri`, `approved: true`, `code_challenge` and `code_challenge_method: S256` → returns a single-use `code` and `iss`.
+2. `POST /oauth/token` with `grant_type=authorization_code`, `client_id`, the `code`, `redirect_uri` and the `code_verifier` (plus the secret for a confidential client).
 
 ## Scopes / abilities