fastapi-fullauth 0.7.0__tar.gz → 0.9.0__tar.gz

{fastapi_fullauth-0.7.0 → fastapi_fullauth-0.9.0}/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 0.9.0
+
+### Breaking changes
+
+- **Lockout now returns `401`** instead of `423 Locked`. Clients that branched on `423` to render a "your account is locked" UI will silently fall into the generic credentials-error path. The change is deliberate — see Security below.
+- **Email lookup is now case-insensitive.** On case-sensitive database collations (MySQL default, SQL Server), rows registered with mixed-case emails (`Alice@X.com`) will stop matching logins submitted in a different case. Run a one-off `UPDATE fullauth_users SET email = LOWER(TRIM(email))` before upgrading. PostgreSQL/SQLite with default collations are unaffected.
+
+### Security
+
+- Emails are now normalised (stripped + lowercased) on create, update, and lookup in both built-in adapters. Previously `Alice@X.com` and `alice@X.com` could register as separate accounts on case-sensitive collations (MySQL default, SQL Server).
+- Login now returns the same generic `401 Could not validate credentials` response for a locked account as for a wrong password. Previously a `423 Locked` status let an attacker distinguish "email exists and is locked out" from "wrong password" — an enumeration signal once they'd exhausted the lockout counter on a target email. The `AccountLockedError` message no longer includes the identifier (cleaner logs too).
+- Opt-in `PREVENT_REGISTRATION_ENUMERATION` setting (default `False`). When `True`, `/register` always responds `202` + `{"detail": "If this email isn't already registered, a verification email has been sent."}` whether the email was taken or not — attackers can't probe the user table through the registration endpoint. Off by default to keep the `201` + user / `409` conflict shape that most client apps expect.
+
+### Fixed
+
+- `BearerBackend` accepts any case of the `Bearer` auth scheme (`Bearer`, `bearer`, `BEARER`, mixed) per RFC 7235. Clients that sent a lowercase scheme were previously rejected with a 401.
+- `require_role` tolerates a `UserSchema` subclass with no `roles` field — returns a clean `403` instead of `AttributeError` / `500`. The default schema doesn't ship with `roles`; apps using RBAC still need to add it to their custom schema.
+- `hash_password(..., algorithm="bcrypt")` rejects passwords over 72 UTF-8 bytes with `InvalidPasswordError` instead of silently truncating. bcrypt's built-in truncation would otherwise cause subtle lockouts if an app later migrated to argon2id.
+- SQLModel `UserBase.hashed_password` column is now `Text`. Argon2id hashes are ~97 characters; MySQL / MSSQL default `VARCHAR(255)` was still fine but the column type is explicit now, matching the SQLAlchemy adapter.
+- `FullAuthConfig` validates passkey settings at construction time when `PASSKEY_ENABLED=True` — empty `PASSKEY_RP_ID` / `PASSKEY_ORIGINS`, RP ID with scheme or path, origin without scheme, and Redis backend without `REDIS_URL` all raise at config creation instead of surfacing as 500s at first request.
+
+## 0.8.0
+
+### Security
+
+- OAuth auto-link-by-email now requires `info.email_verified=True` from the provider when an account with that email already exists. Without this gate, any provider that returns an unverified email (e.g. GitHub secondary addresses) could be used to hijack an existing account by registering the provider with the victim's email.
+- Cookie backend's `delete_token` now matches the same `secure`/`samesite`/`path`/`domain` attributes used on set. Browsers ignore (or reject, for `SameSite=None`) a deletion that doesn't match — logout previously left the cookie in place on some setups.
+- Refresh-token revocation is now an atomic compare-and-swap (`UPDATE ... WHERE revoked=false`). Two concurrent refresh calls with the same token can no longer both succeed by racing the old stored-state check. `AbstractUserAdapter.revoke_refresh_token` now returns `bool` — custom adapters should honour the CAS semantics.
+- `create_user` catches `IntegrityError` from duplicate-email races and raises `UserAlreadyExistsError`. The register flow's pre-check only guards the common case; concurrent signups used to surface as 500s.
+- OAuth account table now has a composite unique constraint on `(provider, provider_user_id)`. Existing SQL users should autogenerate an Alembic migration to add it. `create_oauth_account` now returns the existing row on concurrent-insert collisions instead of erroring.
+- Password-reset and email-verification tokens now use their own TTLs (`PASSWORD_RESET_EXPIRE_MINUTES`, default 15; `EMAIL_VERIFY_EXPIRE_MINUTES`, default 1440) instead of inheriting `ACCESS_TOKEN_EXPIRE_MINUTES`. A production tweak to access-token lifetime for mobile clients no longer silently extends the window in which a stolen password-reset email grants an account takeover.
+
+### Breaking changes
+
+- **Models split into packages** — `adapters/sqlmodel/models.py` and `adapters/sqlalchemy/models.py` are now `models/` directories with `base.py`, `role.py`, `permission.py`, `oauth.py`. Old import paths (`from fastapi_fullauth.adapters.sqlmodel.models import ...`) still work via `__init__.py` re-exports. New selective imports: `from fastapi_fullauth.adapters.sqlmodel.models.base import UserBase, RefreshTokenRecord`.
+- **`roles` removed from default `UserSchema`** — apps that use roles should extend `UserSchema` with `roles: list[str] = Field(default_factory=list)`. Apps without roles are unaffected.
+- **Admin router auto-skipped** when adapter doesn't implement `RoleAdapterMixin`. OAuth/passkey routers auto-skipped similarly.
+- **`AbstractUserAdapter.revoke_refresh_token` now returns `bool`** — custom adapters need to return `True` only when the token actually transitioned from not-revoked to revoked (CAS semantics).
+
+### Added
+
+- **Composable models** — only imported model groups register tables. Apps that don't need roles/permissions/oauth skip those tables entirely.
+- **Selective migration helper** — `include_fullauth_models("sqlmodel", include=["base", "role"])` imports only specified model groups for Alembic.
+- **`exclude_routers` param on `init_app()`** — `fullauth.init_app(app, exclude_routers=["admin"])` to skip routers you don't need.
+- **`bind(app)` method** — bind FullAuth to a FastAPI app for composable router usage. Called automatically by `init_app()` and `init_middleware()`.
+- **`init_middleware()` method** — wire up middleware independently when using composable routers.
+- **`RouterName` type** — `Literal["auth", "profile", "verify", "admin", "oauth"]` for type-safe router exclusion.
+- **`AuthRateLimiter` class** — per-route auth rate limiting extracted from FullAuth into its own class.
+- **`exchange_oauth_code()`, `link_or_create_user()`, `issue_oauth_tokens()`** — OAuth callback split into composable flow functions. `oauth_callback()` still works as before (delegates to the three).
+- **`register_lockout_backend()`** — register custom lockout backends for `create_lockout()` factory.
+- **`register_rate_limiter_backend()`** — register custom rate limiter backends for `create_rate_limiter()` factory.
+- **Passkey (WebAuthn) authentication** — passwordless login with fingerprint, Face ID, security keys. Register, authenticate, list, and delete passkeys. Requires `pip install fastapi-fullauth[passkey]` and `PASSKEY_ENABLED=True`.
+- **`ChallengeStore`** — abstract challenge store with InMemory and Redis backends for WebAuthn flows.
+- **`PasskeyAdapterMixin`** — adapter mixin for passkey credential persistence.
+- **Adapter mixins** — `AbstractUserAdapter` split into composable interfaces: `RoleAdapterMixin`, `PermissionAdapterMixin`, `OAuthAdapterMixin`, `PasskeyAdapterMixin`. Custom adapters implement only what they need. Built-in adapters inherit all mixins (backward compatible).
+
+### Changed
+
+- Adapter model imports are lazy — importing the adapter no longer registers role/permission/oauth tables
+- Rate limiting extracted from FullAuth `__init__` into `AuthRateLimiter`
+- SQLModelAdapter `session_maker` type hint accepts both session types cleanly
+- `TokenClaimsBuilder` and `RouterName` moved to `types.py`
+- `init_app()` and `init_middleware()` are now idempotent. Calling either twice on the same FastAPI app emits a `UserWarning` and is a no-op. Previously a second call (e.g. `init_app(app)` followed by a stray `init_middleware(app)`) doubled the middleware stack — duplicate security headers, two rate-limiter instances halving the effective limit, and a CSRF layer validating another CSRF layer's cookies.
+- JWT decode now tolerates clock drift between services via `JWT_LEEWAY_SECONDS` (default 30). Eliminates sporadic 401s caused by ±30 s skew between client and server clocks or across load-balanced instances.
+- `FullAuthConfig` reads `.env` in the current working directory by default (`env_file=".env"`), and ignores unknown `FULLAUTH_*` vars instead of erroring (`extra="ignore"`). Local dev "just works" without passing `_env_file=".env"` explicitly. Cloud deployments are unaffected — pydantic-settings' precedence is init kwargs → `os.environ` → `.env` → defaults, so platform-injected env vars always win, and a missing `.env` is a silent no-op. Use `FullAuthConfig(_env_file="…")` or a `SettingsConfigDict` subclass to read a different file.
+
 ## 0.7.0
 
 ### Breaking changes
@@ -9,9 +75,6 @@
 - **OAuth providers passed as objects** — `FullAuth(providers=[GoogleOAuthProvider(...)])` replaces `OAUTH_PROVIDERS` dict in config. `OAuthProviderConfig` removed.
 - **`OAuthProvider` simplified** — only `redirect_uris: list[str]` (removed singular `redirect_uri`). `get_redirect_uri()` removed.
 - **`redirect_uri` required in authorize URL** — clients must pass `?redirect_uri=` in the OAuth authorize request.
-
-### Breaking changes (audit cleanup)
-
 - **`include_user_in_login` moved to config** — use `FullAuthConfig(INCLUDE_USER_IN_LOGIN=True)` or `FULLAUTH_INCLUDE_USER_IN_LOGIN=true` env var instead of `FullAuth(include_user_in_login=True)`.
 - **Login response always includes `user` field** — when `INCLUDE_USER_IN_LOGIN=False`, `user` is `null` (previously the key was absent). When `True`, `user` contains the full user schema object.
 
@@ -34,9 +97,8 @@
 - `InMemoryLockoutManager` replaces the old sync `LockoutManager`
 - `migrations/` package flattened to single `migrations.py` module (import paths unchanged)
 - 4 `type: ignore` comments fixed (replaced with `getattr`, assertions, `model_validate`)
-- Misplaced `type: ignore` comments moved inline
 - 204 routes (`delete_me`, `unlink_oauth_account`) no longer return unnecessary `Response` objects
-- Logout route return type corrected to `Response` (needs it for cookie deletion)
+- Logout route return type corrected to `Response`
 - All tests migrated from InMemory to SQLModel + SQLite
 - Tests regrouped: `test_auth`, `test_profile`, `test_config`, `test_hooks`, `test_security`, `test_rbac`
 - `UUID(payload.sub)` conversion at token boundaries (dependencies, router, flows)

{fastapi_fullauth-0.7.0 → fastapi_fullauth-0.9.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: fastapi-fullauth
-Version: 0.7.0
+Version: 0.9.0
 Summary: Production-grade, async-native authentication and authorization library for FastAPI
 Project-URL: Homepage, https://github.com/mdfarhankc/fastapi-fullauth
 Project-URL: Documentation, https://mdfarhankc.github.io/fastapi-fullauth
 Project-URL: Repository, https://github.com/mdfarhankc/fastapi-fullauth
 License-Expression: MIT
 License-File: LICENSE
-Keywords: argon2,async,authentication,authorization,bcrypt,csrf,fastapi,jwt,oauth2,password-hashing,pydantic,rbac,redis,refresh-token,role-based-access-control,security,sqlalchemy,sqlmodel
+Keywords: argon2,async,authentication,authorization,bcrypt,csrf,fastapi,jwt,oauth2,passkey,password-hashing,pydantic,rbac,redis,refresh-token,role-based-access-control,security,sqlalchemy,sqlmodel,webauthn
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: FastAPI
 Classifier: Intended Audience :: Developers
@@ -32,8 +32,11 @@ Requires-Dist: httpx>=0.25; extra == 'all'
 Requires-Dist: redis>=5.0; extra == 'all'
 Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'all'
 Requires-Dist: sqlmodel>=0.0.16; extra == 'all'
+Requires-Dist: webauthn>=2.0; extra == 'all'
 Provides-Extra: oauth
 Requires-Dist: httpx>=0.25; extra == 'oauth'
+Provides-Extra: passkey
+Requires-Dist: webauthn>=2.0; extra == 'passkey'
 Provides-Extra: redis
 Requires-Dist: redis>=5.0; extra == 'redis'
 Provides-Extra: sqlalchemy
@@ -78,6 +81,7 @@ Add a complete authentication and authorization system to your **FastAPI** proje
 - **Refresh token rotation** with reuse detection — revokes entire session family on replay
 - **Password hashing** via Argon2id (default) or bcrypt, with transparent rehashing
 - **Email verification** and **password reset** flows with event hooks
+- **Passkey (WebAuthn)** — passwordless login with fingerprint, Face ID, security keys
 - **OAuth2 social login** — Google and GitHub, with multi-redirect-URI support
 - **Role-based access control** — `CurrentUser`, `VerifiedUser`, `SuperUser`, `require_role()`
 - **Rate limiting** — per-route auth limits + global middleware (memory or Redis)
@@ -106,6 +110,9 @@ pip install fastapi-fullauth[sqlmodel,redis]
 # with OAuth2 social login
 pip install fastapi-fullauth[sqlmodel,oauth]
 
+# with passkey/WebAuthn
+pip install fastapi-fullauth[sqlmodel,passkey]
+
 # everything
 pip install fastapi-fullauth[all]
 ```
@@ -132,16 +139,21 @@ Omit `config` in dev and a random secret key is generated (tokens won't survive
 
 ### Composable routers
 
-Include only the route groups you need:
+Exclude routers you don't need:
+
+```python
+fullauth.init_app(app, exclude_routers=["admin"])
+```
+
+Or wire routers manually for full control:
 
 ```python
 app = FastAPI()
-app.state.fullauth = fullauth
+fullauth.bind(app)  # required for dependencies to work
 
-# pick what you want
 app.include_router(fullauth.auth_router, prefix="/api/v1/auth")
 app.include_router(fullauth.profile_router, prefix="/api/v1/auth")
-# skip verify, admin, oauth
+fullauth.init_middleware(app)
 ```
 
 | Router | Routes |
@@ -151,6 +163,7 @@ app.include_router(fullauth.profile_router, prefix="/api/v1/auth")
 | `verify_router` | email verification, password reset |
 | `admin_router` | assign/remove roles and permissions (superuser) |
 | `oauth_router` | OAuth provider routes (only if configured) |
+| `passkey_router` | Passkey register, authenticate, list, delete (only if enabled) |
 
 `fullauth.init_app(app)` includes all of them. Use individual routers for granular control.
 
@@ -186,9 +199,9 @@ Define your model and schemas — pass them explicitly to the adapter:
 ```python
 from sqlmodel import Field, Relationship
 from fastapi_fullauth import FullAuth, FullAuthConfig, UserSchema, CreateUserSchema
-from fastapi_fullauth.adapters.sqlmodel import (
-    UserBase, Role, UserRoleLink, RefreshTokenRecord, SQLModelAdapter,
-)
+from fastapi_fullauth.adapters.sqlmodel import SQLModelAdapter
+from fastapi_fullauth.adapters.sqlmodel.models.base import UserBase, RefreshTokenRecord
+from fastapi_fullauth.adapters.sqlmodel.models.role import Role, UserRoleLink
 
 class User(UserBase, table=True):
     __tablename__ = "fullauth_users"

{fastapi_fullauth-0.7.0 → fastapi_fullauth-0.9.0}/README.md

@@ -32,6 +32,7 @@ Add a complete authentication and authorization system to your **FastAPI** proje
 - **Refresh token rotation** with reuse detection — revokes entire session family on replay
 - **Password hashing** via Argon2id (default) or bcrypt, with transparent rehashing
 - **Email verification** and **password reset** flows with event hooks
+- **Passkey (WebAuthn)** — passwordless login with fingerprint, Face ID, security keys
 - **OAuth2 social login** — Google and GitHub, with multi-redirect-URI support
 - **Role-based access control** — `CurrentUser`, `VerifiedUser`, `SuperUser`, `require_role()`
 - **Rate limiting** — per-route auth limits + global middleware (memory or Redis)
@@ -60,6 +61,9 @@ pip install fastapi-fullauth[sqlmodel,redis]
 # with OAuth2 social login
 pip install fastapi-fullauth[sqlmodel,oauth]
 
+# with passkey/WebAuthn
+pip install fastapi-fullauth[sqlmodel,passkey]
+
 # everything
 pip install fastapi-fullauth[all]
 ```
@@ -86,16 +90,21 @@ Omit `config` in dev and a random secret key is generated (tokens won't survive
 
 ### Composable routers
 
-Include only the route groups you need:
+Exclude routers you don't need:
+
+```python
+fullauth.init_app(app, exclude_routers=["admin"])
+```
+
+Or wire routers manually for full control:
 
 ```python
 app = FastAPI()
-app.state.fullauth = fullauth
+fullauth.bind(app)  # required for dependencies to work
 
-# pick what you want
 app.include_router(fullauth.auth_router, prefix="/api/v1/auth")
 app.include_router(fullauth.profile_router, prefix="/api/v1/auth")
-# skip verify, admin, oauth
+fullauth.init_middleware(app)
 ```
 
 | Router | Routes |
@@ -105,6 +114,7 @@ app.include_router(fullauth.profile_router, prefix="/api/v1/auth")
 | `verify_router` | email verification, password reset |
 | `admin_router` | assign/remove roles and permissions (superuser) |
 | `oauth_router` | OAuth provider routes (only if configured) |
+| `passkey_router` | Passkey register, authenticate, list, delete (only if enabled) |
 
 `fullauth.init_app(app)` includes all of them. Use individual routers for granular control.
 
@@ -140,9 +150,9 @@ Define your model and schemas — pass them explicitly to the adapter:
 ```python
 from sqlmodel import Field, Relationship
 from fastapi_fullauth import FullAuth, FullAuthConfig, UserSchema, CreateUserSchema
-from fastapi_fullauth.adapters.sqlmodel import (
-    UserBase, Role, UserRoleLink, RefreshTokenRecord, SQLModelAdapter,
-)
+from fastapi_fullauth.adapters.sqlmodel import SQLModelAdapter
+from fastapi_fullauth.adapters.sqlmodel.models.base import UserBase, RefreshTokenRecord
+from fastapi_fullauth.adapters.sqlmodel.models.role import Role, UserRoleLink
 
 class User(UserBase, table=True):
     __tablename__ = "fullauth_users"

{fastapi_fullauth-0.7.0 → fastapi_fullauth-0.9.0}/docs/adapters/index.md

@@ -16,25 +16,35 @@ Adapters are the database layer for fastapi-fullauth. They implement `AbstractUs
 
 ## Custom adapters
 
-You can implement your own adapter for any database by subclassing `AbstractUserAdapter`:
+Subclass `AbstractUserAdapter` for core auth. Add mixins for roles, permissions, or OAuth:
 
 ```python
-from fastapi_fullauth.adapters.base import AbstractUserAdapter
-from fastapi_fullauth.types import CreateUserSchema, RefreshToken, UserSchema
-
-class MongoAdapter(AbstractUserAdapter):
-    async def get_user_by_id(self, user_id: str) -> UserSchema | None:
-        ...
-
-    async def get_user_by_email(self, email: str) -> UserSchema | None:
-        ...
-
-    async def create_user(self, data: CreateUserSchema, hashed_password: str) -> UserSchema:
-        ...
+from fastapi_fullauth.adapters.base import (
+    AbstractUserAdapter,
+    RoleAdapterMixin,
+    PermissionAdapterMixin,
+    OAuthAdapterMixin,
+)
 
-    # ... implement all abstract methods
+# Minimal — just auth
+class MyAdapter(AbstractUserAdapter):
+    async def get_user_by_id(self, user_id): ...
+    async def get_user_by_email(self, email): ...
+    async def create_user(self, data, hashed_password): ...
+    # ... core methods only
+
+# With roles and permissions
+class MyFullAdapter(AbstractUserAdapter, RoleAdapterMixin, PermissionAdapterMixin):
+    # ... core + role + permission methods
+    pass
 ```
 
+| Mixin | Methods | When to use |
+|-------|---------|-------------|
+| `RoleAdapterMixin` | `assign_role`, `remove_role`, `get_user_roles` | Role management |
+| `PermissionAdapterMixin` | `get_role_permissions`, `assign_permission_to_role`, `remove_permission_from_role` | RBAC permissions |
+| `OAuthAdapterMixin` | `get_oauth_account`, `create_oauth_account`, `update_oauth_account`, `delete_oauth_account`, `get_user_oauth_accounts` | OAuth providers |
+
 See the [source of AbstractUserAdapter](https://github.com/mdfarhankc/fastapi-fullauth/blob/main/fastapi_fullauth/adapters/base.py) for the full interface.
 
 ## Custom schemas
@@ -57,3 +67,10 @@ adapter = SQLModelAdapter(
     create_user_schema=MyCreateSchema,
 )
 ```
+
+If your app uses roles, add `roles` to your custom schema:
+
+```python
+class MyUserSchema(UserSchema):
+    roles: list[str] = Field(default_factory=list)
+```

{fastapi_fullauth-0.7.0 → fastapi_fullauth-0.9.0}/docs/adapters/sqlalchemy.md

@@ -15,9 +15,8 @@ pip install fastapi-fullauth[sqlalchemy]
 ```python
 from sqlalchemy import Boolean, Column, DateTime, String, Table, ForeignKey
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
-from fastapi_fullauth.adapters.sqlalchemy.models import (
-    FullAuthBase, RoleModel, UserBase, user_role_table,
-)
+from fastapi_fullauth.adapters.sqlalchemy.models.base import FullAuthBase, UserBase
+from fastapi_fullauth.adapters.sqlalchemy.models.role import RoleModel
 
 class User(UserBase):
     __tablename__ = "fullauth_users"
@@ -27,7 +26,9 @@ class User(UserBase):
     phone: Mapped[str] = mapped_column(String(20), default="")
 
     # required relationships
-    roles: Mapped[list[RoleModel]] = relationship(secondary=user_role_table)
+    roles: Mapped[list[RoleModel]] = relationship(
+        secondary="fullauth_user_roles", lazy="selectin",
+    )
 ```
 
 `UserBase` provides the same core fields as the SQLModel version: `id`, `email`, `hashed_password`, `is_active`, `is_verified`, `is_superuser`, `created_at`.

{fastapi_fullauth-0.7.0 → fastapi_fullauth-0.9.0}/docs/adapters/sqlmodel.md

@@ -14,9 +14,8 @@ pip install fastapi-fullauth[sqlmodel]
 
 ```python
 from sqlmodel import Field, Relationship
-from fastapi_fullauth.adapters.sqlmodel import (
-    UserBase, Role, UserRoleLink, RefreshTokenRecord,
-)
+from fastapi_fullauth.adapters.sqlmodel.models.base import UserBase, RefreshTokenRecord
+from fastapi_fullauth.adapters.sqlmodel.models.role import Role, UserRoleLink
 
 class User(UserBase, table=True):
     __tablename__ = "fullauth_users"
@@ -25,11 +24,13 @@ class User(UserBase, table=True):
     display_name: str = Field(default="", max_length=100)
     phone: str = Field(default="", max_length=20)
 
-    # required relationships
+    # relationships — import only what you need
     roles: list[Role] = Relationship(link_model=UserRoleLink)
     refresh_tokens: list[RefreshTokenRecord] = Relationship()
 ```
 
+Only tables for imported models are created. Skip `role` imports for apps that don't need roles.
+
 `UserBase` provides these fields:
 
 | Field | Type | Description |
@@ -96,15 +97,15 @@ fullauth = FullAuth(
 
 ## Tables created
 
-The SQLModel adapter uses these tables:
+Tables are created based on which model groups you import:
 
-| Table | Purpose |
-|-------|---------|
-| `fullauth_users` | User accounts (your model) |
-| `fullauth_roles` | Role definitions |
-| `fullauth_user_roles` | User-role link table |
-| `fullauth_refresh_tokens` | Stored refresh tokens |
-| `fullauth_oauth_accounts` | Linked OAuth provider accounts |
+| Group | Tables | Import from |
+|-------|--------|-------------|
+| Core (always) | `fullauth_users`, `fullauth_refresh_tokens` | `models.base` |
+| Roles | `fullauth_roles`, `fullauth_user_roles` | `models.role` |
+| Permissions | `fullauth_permissions`, `fullauth_role_permissions` | `models.permission` |
+| OAuth | `fullauth_oauth_accounts` | `models.oauth` |
+| Passkeys | `fullauth_passkeys` | `models.passkey` |
 
 ## Custom schemas
 
@@ -132,4 +133,4 @@ If you don't pass custom schemas, the base `UserSchema` and `CreateUserSchema` a
 
 ## OAuth support
 
-The SQLModel adapter includes full OAuth support. The `OAuthAccountRecord` model is included and the adapter implements all OAuth methods from `AbstractUserAdapter`.
+The SQLModel adapter implements `OAuthAdapterMixin`. Import `OAuthAccountRecord` from `models.oauth` to register the table.

{fastapi_fullauth-0.7.0 → fastapi_fullauth-0.9.0}/docs/api-reference.md

@@ -23,7 +23,9 @@ fullauth = FullAuth(
 
 | Method | Description |
 |--------|-------------|
-| `init_app(app, auto_middleware=True)` | Mount routes and middleware on a FastAPI app |
+| `init_app(app, *, auto_middleware=True, exclude_routers=None)` | Mount routes and middleware on a FastAPI app. Pass `exclude_routers=["admin"]` to skip specific routers. |
+| `bind(app)` | Bind FullAuth to a FastAPI app (sets `app.state.fullauth`). Required when using composable routers without `init_app()`. |
+| `init_middleware(app)` | Wire up middleware from config. Also calls `bind()` if not already done. |
 | `hooks.on(event, callback)` | Register an event hook |
 
 ### Properties
@@ -38,6 +40,7 @@ fullauth = FullAuth(
 | `verify_router` | `APIRouter` | Email verification and password reset routes |
 | `admin_router` | `APIRouter` | Role/permission management routes (superuser) |
 | `oauth_router` | `APIRouter` | OAuth provider routes |
+| `passkey_router` | `APIRouter` | Passkey WebAuthn routes |
 
 ## FullAuthConfig
 
@@ -70,7 +73,6 @@ class UserSchema(BaseModel):
     is_active: bool = True
     is_verified: bool = False
     is_superuser: bool = False
-    roles: list[str] = []
 
     PROTECTED_FIELDS: ClassVar[set[str]] = {
         "id", "email", "hashed_password", "is_active",

{fastapi_fullauth-0.7.0 → fastapi_fullauth-0.9.0}/docs/configuration.md

@@ -35,6 +35,60 @@ Pass config inline or as an object:
     fullauth = FullAuth(adapter=adapter)
     ```
 
+## Reading from a `.env` file
+
+`FullAuthConfig` reads a `.env` file in the current working directory by default (via pydantic-settings). Drop a `.env` next to your app entry point:
+
+```bash
+# .env
+FULLAUTH_SECRET_KEY=replace-me-with-32-random-bytes
+FULLAUTH_ACCESS_TOKEN_EXPIRE_MINUTES=15
+FULLAUTH_BLACKLIST_BACKEND=redis
+FULLAUTH_REDIS_URL=redis://localhost:6379/0
+```
+
+Then `FullAuthConfig()` picks it up — no extra wiring needed.
+
+### Precedence
+
+pydantic-settings resolves values in this order, first wins:
+
+1. Init kwargs — `FullAuthConfig(SECRET_KEY="...")`
+2. Process environment — `os.environ["FULLAUTH_SECRET_KEY"]`
+3. `.env` file
+4. Field defaults
+
+So anything you export in your shell, in `uvicorn --env-file`, or in Docker `env_file:` overrides the dotfile. The dotfile is only read if the variable isn't already in `os.environ`.
+
+### Using a different file
+
+Pass `_env_file` at construction:
+
+```python
+FullAuthConfig(_env_file=".env.production")
+```
+
+Or subclass once in your app:
+
+```python
+from fastapi_fullauth import FullAuthConfig
+from pydantic_settings import SettingsConfigDict
+
+class AppFullAuthConfig(FullAuthConfig):
+    model_config = SettingsConfigDict(
+        env_prefix="FULLAUTH_",
+        case_sensitive=True,
+        env_file=".env.local",
+        extra="ignore",
+    )
+```
+
+### Cloud / container deployments
+
+You don't need to change anything. Managed platforms (FastAPI Cloud, Fly, Railway, Render), Docker, and Kubernetes inject config as real environment variables — those end up in `os.environ` inside the container. The `.env` default simply doesn't find a file to read and falls through to the process env. No overhead, no surprises.
+
+If you want to be defensively explicit that no file is ever read, pass `FullAuthConfig(_env_file=None)` — but it's not required.
+
 ## Reference
 
 ### Core
@@ -51,6 +105,9 @@ Pass config inline or as an object:
 | `ACCESS_TOKEN_EXPIRE_MINUTES` | `int` | `30` | Access token lifetime. |
 | `REFRESH_TOKEN_EXPIRE_DAYS` | `int` | `30` | Refresh token lifetime. |
 | `REFRESH_TOKEN_ROTATION` | `bool` | `True` | Issue new refresh token on each refresh. |
+| `JWT_LEEWAY_SECONDS` | `int` | `30` | Tolerance (seconds) for clock drift between client and server when validating `exp`/`iat`. |
+| `PASSWORD_RESET_EXPIRE_MINUTES` | `int` | `15` | Password-reset token lifetime. Kept short — independent of `ACCESS_TOKEN_EXPIRE_MINUTES`. |
+| `EMAIL_VERIFY_EXPIRE_MINUTES` | `int` | `1440` | Email-verification token lifetime (24 h). |
 
 ### Passwords
 
@@ -75,12 +132,13 @@ Pass config inline or as an object:
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `RATE_LIMIT_ENABLED` | `bool` | `False` | Enable global rate limit middleware. |
-| `RATE_LIMIT_BACKEND` | `"memory" \| "redis"` | `"memory"` | Rate limiter storage backend. |
+| `RATE_LIMIT_BACKEND` | `"memory" \| "redis"` | `"memory"` | Rate limiter storage backend. Use `"redis"` in production — `"memory"` is per-process, so the effective limit is multiplied by the worker count. |
 | `TRUSTED_PROXY_HEADERS` | `list[str]` | `[]` | Headers to read real client IP from (e.g. `["X-Forwarded-For"]`). |
 | `AUTH_RATE_LIMIT_ENABLED` | `bool` | `True` | Enable per-route auth rate limits. |
 | `AUTH_RATE_LIMIT_LOGIN` | `int` | `5` | Max login attempts per window. |
 | `AUTH_RATE_LIMIT_REGISTER` | `int` | `3` | Max registrations per window. |
 | `AUTH_RATE_LIMIT_PASSWORD_RESET` | `int` | `3` | Max password reset requests per window. |
+| `AUTH_RATE_LIMIT_PASSKEY_AUTH` | `int` | `10` | Max passkey authenticate/begin requests per window. |
 | `AUTH_RATE_LIMIT_WINDOW_SECONDS` | `int` | `60` | Rate limit window in seconds. |
 
 ### Redis
@@ -94,7 +152,7 @@ Pass config inline or as an object:
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `BLACKLIST_ENABLED` | `bool` | `True` | Check blacklist on token decode. |
-| `BLACKLIST_BACKEND` | `"memory" \| "redis"` | `"memory"` | Blacklist storage backend. |
+| `BLACKLIST_BACKEND` | `"memory" \| "redis"` | `"memory"` | Blacklist storage backend. Use `"redis"` in production — `"memory"` is per-process, so a token revoked on one worker remains usable on others (logout won't actually revoke). |
 
 ### Middleware
 
@@ -120,6 +178,7 @@ Pass config inline or as an object:
 |--------|------|---------|-------------|
 | `OAUTH_STATE_EXPIRE_SECONDS` | `int` | `300` | OAuth state token TTL (5 min). |
 | `OAUTH_AUTO_LINK_BY_EMAIL` | `bool` | `True` | Auto-link OAuth accounts to existing users by email. |
+| `PREVENT_REGISTRATION_ENUMERATION` | `bool` | `False` | When `True`, `/register` always returns `202` + a generic message whether or not the email is already registered — an attacker can't use registration responses to probe the user table. Opt-in because the default `201` + user / `409` conflict behavior is simpler for client apps. |
 
 ### Routing
 
@@ -128,3 +187,15 @@ Pass config inline or as an object:
 | `API_PREFIX` | `str` | `"/api/v1"` | URL prefix for all routes. |
 | `AUTH_ROUTER_PREFIX` | `str` | `"/auth"` | Auth router sub-prefix. |
 | `ROUTER_TAGS` | `list[str]` | `["Auth"]` | OpenAPI tags for auth routes. |
+
+### Passkeys
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `PASSKEY_ENABLED` | `bool` | `False` | Enable passkey (WebAuthn) routes. |
+| `PASSKEY_RP_ID` | `str \| None` | `None` | Relying Party ID (your domain, e.g. `"example.com"`). |
+| `PASSKEY_RP_NAME` | `str \| None` | `None` | Relying Party display name (e.g. `"My App"`). |
+| `PASSKEY_ORIGINS` | `list[str]` | `[]` | Allowed origins (e.g. `["https://example.com", "https://m.example.com"]`). |
+| `PASSKEY_CHALLENGE_BACKEND` | `"memory" \| "redis"` | `"memory"` | Challenge store backend. Use `"redis"` in production — `"memory"` is per-process and breaks under `uvicorn --workers N` (begin and complete can land on different workers). |
+| `PASSKEY_CHALLENGE_TTL` | `int` | `60` | Challenge expiry in seconds. |
+| `PASSKEY_REQUIRE_USER_VERIFICATION` | `bool` | `True` | Require user verification (PIN/biometric) on register and authenticate. Set `False` only if you need to allow silent authenticators. |

{fastapi_fullauth-0.7.0 → fastapi_fullauth-0.9.0}/docs/getting-started.md

@@ -13,9 +13,8 @@ pip install fastapi-fullauth[sqlmodel]
 ```python
 # models.py
 from sqlmodel import Field, Relationship
-from fastapi_fullauth.adapters.sqlmodel import (
-    UserBase, Role, UserRoleLink, RefreshTokenRecord,
-)
+from fastapi_fullauth.adapters.sqlmodel.models.base import UserBase, RefreshTokenRecord
+from fastapi_fullauth.adapters.sqlmodel.models.role import Role, UserRoleLink
 
 class User(UserBase, table=True):
     __tablename__ = "fullauth_users"
@@ -94,15 +93,24 @@ uvicorn main:app --reload
 
 ### Composable routers
 
-`init_app()` registers all routes. If you want only specific route groups, include them manually:
+`init_app()` registers all routes. To exclude specific routers, use `exclude_routers`:
+
+```python
+# skip admin routes
+fullauth.init_app(app, exclude_routers=["admin"])
+```
+
+For full manual control, wire routers and middleware yourself:
 
 ```python
 app = FastAPI(lifespan=lifespan)
-app.state.fullauth = fullauth
+fullauth.bind(app)  # required for dependencies to work
 
-# only auth + profile, no verification/admin/oauth
 app.include_router(fullauth.auth_router, prefix="/api/v1/auth")
 app.include_router(fullauth.profile_router, prefix="/api/v1/auth")
+
+# optionally wire middleware from config
+fullauth.init_middleware(app)  # also calls bind() if not done
 ```
 
 | Router | Routes |
@@ -112,6 +120,7 @@ app.include_router(fullauth.profile_router, prefix="/api/v1/auth")
 | `verify_router` | email verification, password reset |
 | `admin_router` | assign/remove roles and permissions (superuser) |
 | `oauth_router` | OAuth provider routes (only if configured) |
+| `passkey_router` | Passkey register, authenticate, list, delete (only if enabled) |
 
 ## 5. Try it out
 

{fastapi_fullauth-0.7.0 → fastapi_fullauth-0.9.0}/docs/index.md

@@ -86,15 +86,21 @@ Omit `SECRET_KEY` in dev and a random one is generated (tokens won't survive res
 
 ### Composable routers
 
-Include only the route groups you need:
+Exclude routers you don't need:
+
+```python
+fullauth.init_app(app, exclude_routers=["admin"])
+```
+
+Or wire routers manually for full control:
 
 ```python
 app = FastAPI()
-app.state.fullauth = fullauth
+fullauth.bind(app)  # required for dependencies to work
 
 app.include_router(fullauth.auth_router, prefix="/api/v1/auth")
 app.include_router(fullauth.profile_router, prefix="/api/v1/auth")
-# skip verify, admin, oauth
+fullauth.init_middleware(app)
 ```
 
 | Router | Routes |
@@ -104,8 +110,9 @@ app.include_router(fullauth.profile_router, prefix="/api/v1/auth")
 | `verify_router` | email verification, password reset |
 | `admin_router` | assign/remove roles and permissions (superuser) |
 | `oauth_router` | OAuth provider routes (only if configured) |
+| `passkey_router` | Passkey register, authenticate, list, delete (only if enabled) |
 
-`fullauth.init_app(app)` includes all of them.
+`fullauth.init_app(app)` includes all of them. Use `exclude_routers` or individual routers for granular control.
 
 ## Routes