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

fastapi_fullauth-0.7.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,60 @@
+name: Bug Report
+description: Report a bug in fastapi-fullauth
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug! Please fill out the details below.
+
+  - type: input
+    id: version
+    attributes:
+      label: fastapi-fullauth version
+      placeholder: "0.5.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.12"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: adapter
+    attributes:
+      label: Adapter
+      options:
+        - SQLModel
+        - SQLAlchemy
+        - InMemory
+        - Custom
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened? What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: Minimal code or steps to reproduce the bug.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error output / traceback
+      description: Paste any relevant error messages or tracebacks.
+      render: shell

fastapi_fullauth-0.7.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,30 @@
+name: Feature Request
+description: Suggest a new feature for fastapi-fullauth
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please describe what you'd like.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem does this feature solve? What's the use case?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How would you like this to work? Code examples are welcome.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any workarounds or alternative approaches you've considered?

fastapi_fullauth-0.7.0/.github/pull_request_template.md

@@ -0,0 +1,17 @@
+## Summary
+
+<!-- What does this PR do? Keep it brief. -->
+
+## Changes
+
+<!-- Bullet list of what changed. -->
+
+-
+
+## Test plan
+
+<!-- How was this tested? -->
+
+- [ ] All existing tests pass
+- [ ] New tests added for new functionality
+- [ ] Lint and format clean (`ruff check .` + `ruff format --check .`)

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

@@ -1,5 +1,97 @@
 # Changelog
 
+## 0.7.0
+
+### Breaking changes
+
+- **InMemory adapter removed** — use SQLModel + SQLite for prototyping instead.
+- **`UserID` is now `UUID`** (was `str | int | UUID`) — all adapter methods, `RefreshToken.user_id`, `OAuthAccount.user_id`, and `RoleAssignment.user_id` are now `UUID`.
+- **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.
+
+### Added
+
+- **Redis lockout backend** — `LOCKOUT_BACKEND="redis"` for multi-worker deployments
+- `LOCKOUT_ENABLED` config — disable account lockout entirely (`False`)
+- `INCLUDE_USER_IN_LOGIN` config — include user object in login/OAuth callback response
+- `LoginResponse` dynamic model — login and OAuth callback routes now have proper `response_model` with typed `user` field matching the configured user schema
+- `validate_profile_updates` flow — profile field filtering extracted from router to `flows/update_profile.py`
+- `NoValidFieldsError`, `UnknownFieldsError` exceptions for profile update validation
+- `change_password` flow — business logic extracted from profile router
+- `PROTECTED_FIELDS` ClassVar on `UserSchema` — users can extend in subclasses
+- Password validation moved to flows (`register`, `reset_password`, `change_password`)
+- `Makefile` with `make check`, `make test`, `make lint`, `make format`, `make docs`, etc.
+
+### Changed
+
+- `LockoutManager` is now an abstract base class with async methods
+- `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)
+- 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)
+- Removed `isinstance` str-to-UUID guards from adapters
+- Removed `str(user.id)` / `str(row.user_id)` conversions — UUID used directly
+
+### Removed
+
+- `InMemoryAdapter` and `examples/memory_app/`
+- `OAuthProviderConfig` from config
+- `OAUTH_PROVIDERS` from `FullAuthConfig`
+- `FullAuth._build_oauth_providers()` and `_OAUTH_PROVIDER_REGISTRY`
+- `OAuthProvider.get_redirect_uri()` method
+- `rbac/` package (was empty, just re-exported from `dependencies`)
+
+## 0.6.0
+
+### Breaking changes
+
+- **Config-only API** — `FullAuth` no longer accepts `secret_key=`, `**config_kwargs`, or positional `config`. Pass `config=FullAuthConfig(SECRET_KEY="...")` or set `FULLAUTH_SECRET_KEY` env var. All params are keyword-only.
+- **`enabled_routes` removed** — replaced by composable routers. Include only the routers you need instead of filtering route names.
+- **`RouteName` type removed** — no longer needed with composable routers.
+- **`configure_hasher()` removed** — hash algorithm is now passed explicitly from config through flows. No more global mutable state.
+- **Schema auto-derivation removed** — `_derive_user_schema()` and `_resolve_create_schema()` deleted from all adapters and FullAuth. Define your own schemas extending `UserSchema` / `CreateUserSchema` and pass them to the adapter.
+- **`create_user_schema` moved to adapter** — pass it to the adapter, not FullAuth: `InMemoryAdapter(user_schema=MyUser, create_user_schema=MyCreate)`.
+
+### Added
+
+- **Generic type parameters** — `AbstractUserAdapter[UserSchemaType, CreateUserSchemaType]`, `FullAuth[UserSchemaType, CreateUserSchemaType]` with PEP 696 defaults for full type safety
+- **Composable routers** — `fullauth.auth_router`, `fullauth.profile_router`, `fullauth.verify_router`, `fullauth.admin_router`, `fullauth.oauth_router`. Each lazily created, include only what you need
+- **Typed dependency factories** — `get_current_user_dependency(MyUser)`, `get_verified_user_dependency(MyUser)`, `get_superuser_dependency(MyUser)` for custom schema type safety
+- `create_blacklist(config)` — extracted from FullAuth to `core/tokens.py`
+- `create_rate_limiter(config, max, window)` — extracted from FullAuth to `protection/ratelimit.py`
+- `UserSchemaType`, `CreateUserSchemaType` TypeVars exported from top-level package
+- `UserSchema`, `CreateUserSchema` base classes exported from top-level package
+
+### Changed
+
+- **Router split** — 613-line monolithic `create_auth_router()` split into `create_auth_router()` (login/register/logout/refresh), `create_profile_router()` (me/update/delete/change-password), `create_verify_router()` (email verify/password reset), `create_admin_router()` (roles/permissions)
+- **FullAuth slimmed** — factory methods extracted, composable router properties added, `_OAUTH_PROVIDER_REGISTRY` stays on class for now
+- `fullauth.router` still works as before (composes all sub-routers), `fullauth.init_app(app)` unchanged
+- `hash_password()` and `password_needs_rehash()` now accept explicit `algorithm` parameter (default `argon2id`)
+- Shared request/response models extracted to `router/_models.py`
+- RBAC permissions (`require_role`, `require_permission`) available via `fastapi_fullauth.dependencies`
+
+### Removed
+
+- `FullAuth._resolve_create_schema()` — auto-derivation of create schema from ORM model
+- `SQLModelAdapter._derive_user_schema()` — auto-derivation of user schema
+- `SQLAlchemyAdapter._derive_user_schema()` — auto-derivation of user schema
+- `_SA_TYPE_MAP` and `_get_sa_type_map()` — SQLAlchemy type mapping for auto-derivation
+- `FullAuth._create_blacklist()` — moved to `core/tokens.create_blacklist()`
+- `FullAuth._create_rate_limiter()` — moved to `protection.ratelimit.create_rate_limiter()`
+- `configure_hasher()` and `_algorithm` global from `core/crypto.py`
+
 ## 0.5.0
 
 ### Added

fastapi_fullauth-0.7.0/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to FastAPI FullAuth
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Development setup
+
+```bash
+git clone https://github.com/mdfarhankc/fastapi-fullauth.git
+cd fastapi-fullauth
+uv sync --dev --extra sqlalchemy --extra sqlmodel --extra redis --extra oauth
+```
+
+## Running tests
+
+```bash
+uv run pytest tests/ -v
+```
+
+## Linting and formatting
+
+```bash
+uv run ruff check .
+uv run ruff format .
+```
+
+Both must pass before submitting a PR. CI enforces this.
+
+## Making changes
+
+1. Fork the repo and create a branch from `main`
+2. Make your changes
+3. Add tests for new functionality
+4. Ensure all tests pass and lint is clean
+5. Submit a pull request
+
+## Branch naming
+
+- `feat/description` — new features
+- `fix/description` — bug fixes
+- `refactor/description` — code improvements
+- `docs/description` — documentation changes
+
+## Commit messages
+
+Keep them short and descriptive. Use imperative mood:
+
+- `add permission-based RBAC`
+- `fix OAuth state token TTL`
+- `update README with docs link`
+
+## What to contribute
+
+- Bug fixes
+- New OAuth providers (Apple, Discord, Microsoft, etc.)
+- Adapter implementations (MongoDB, Tortoise ORM, etc.)
+- Documentation improvements
+- Test coverage improvements
+- Performance improvements
+
+## Reporting bugs
+
+Use the [bug report template](https://github.com/mdfarhankc/fastapi-fullauth/issues/new?template=bug_report.yml) on GitHub Issues. Include:
+
+- Python version
+- fastapi-fullauth version
+- Minimal reproduction steps
+- Expected vs actual behavior
+
+## Requesting features
+
+Use the [feature request template](https://github.com/mdfarhankc/fastapi-fullauth/issues/new?template=feature_request.yml) on GitHub Issues.
+
+## Code style
+
+- Follow existing patterns in the codebase
+- Use type annotations
+- Keep functions focused and small
+- Log security-sensitive events via `logging.getLogger("fastapi_fullauth.*")`
+- Don't add docstrings/comments unless the logic isn't self-evident
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

fastapi_fullauth-0.7.0/Makefile

@@ -0,0 +1,64 @@
+.PHONY: install test lint format check fix clean build docs
+
+# Install dependencies
+install:
+	uv sync --dev --extra sqlalchemy --extra sqlmodel --extra oauth --extra redis
+
+# Run tests
+test:
+	uv run pytest tests/ -x --tb=short
+
+# Run tests with verbose output
+test-v:
+	uv run pytest tests/ -v
+
+# Run a specific test file
+# Usage: make test-file FILE=test_auth
+test-file:
+	uv run pytest tests/$(FILE).py -x --tb=short -v
+
+# Lint check (no changes)
+lint:
+	uv run ruff check .
+
+# Format check (no changes)
+format-check:
+	uv run ruff format --check .
+
+# Fix lint issues
+fix:
+	uv run ruff check --fix .
+
+# Format code
+format:
+	uv run ruff format .
+
+# Run all checks (format + lint + tests) — run before committing
+check: format-check lint test
+
+# Fix all issues then verify
+fix-all: format fix test
+
+# Build package
+build:
+	uv build
+
+# Serve docs locally
+docs:
+	uv run mkdocs serve
+
+# Build docs
+docs-build:
+	uv run mkdocs build
+
+# Run example apps
+run-sqlmodel:
+	uv run uvicorn examples.sqlmodel_app.main:app --reload
+
+run-sqlalchemy:
+	uv run uvicorn examples.sqlalchemy_app.main:app --reload
+
+# Clean build artifacts
+clean:
+	rm -rf dist/ build/ *.egg-info .pytest_cache .ruff_cache
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: fastapi-fullauth
-Version: 0.5.0
+Version: 0.7.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,authentication,authorization,fastapi,jwt,security
+Keywords: argon2,async,authentication,authorization,bcrypt,csrf,fastapi,jwt,oauth2,password-hashing,pydantic,rbac,redis,refresh-token,role-based-access-control,security,sqlalchemy,sqlmodel
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: FastAPI
 Classifier: Intended Audience :: Developers
@@ -82,8 +82,9 @@ Add a complete authentication and authorization system to your **FastAPI** proje
 - **Role-based access control** — `CurrentUser`, `VerifiedUser`, `SuperUser`, `require_role()`
 - **Rate limiting** — per-route auth limits + global middleware (memory or Redis)
 - **CSRF protection** and **security headers** middleware, auto-wired
-- **Pluggable adapters** — SQLModel, SQLAlchemy, or in-memory
-- **Auto-derived schemas** — custom user fields picked up automatically
+- **Pluggable adapters** — SQLModel or SQLAlchemy
+- **Generic type parameters** — define your own schemas with full IDE support and type safety
+- **Composable routers** — include only the route groups you need
 - **Event hooks** — `after_register`, `after_login`, `send_verification_email`, etc.
 - **Custom JWT claims** — embed app-specific data in tokens
 - **Structured logging** — all auth events, security violations, and failures logged
@@ -113,21 +114,45 @@ pip install fastapi-fullauth[all]
 
 ```python
 from fastapi import FastAPI
-from fastapi_fullauth import FullAuth
-from fastapi_fullauth.adapters.memory import InMemoryAdapter
+from fastapi_fullauth import FullAuth, FullAuthConfig
+from fastapi_fullauth.adapters.sqlmodel import SQLModelAdapter
 
 app = FastAPI()
 
 fullauth = FullAuth(
-    secret_key="your-secret-key",
-    adapter=InMemoryAdapter(),
+    adapter=SQLModelAdapter(session_maker=session_maker, user_model=User),
+    config=FullAuthConfig(SECRET_KEY="your-secret-key"),
 )
 fullauth.init_app(app)
 ```
 
-That's it — 15+ auth routes are registered under `/api/v1/auth/` automatically.
+That's it — all auth routes are registered under `/api/v1/auth/` automatically.
 
-Omit `secret_key` in dev and a random one is generated (tokens won't survive restarts).
+Omit `config` in dev and a random secret key is generated (tokens won't survive restarts).
+
+### Composable routers
+
+Include only the route groups you need:
+
+```python
+app = FastAPI()
+app.state.fullauth = fullauth
+
+# 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
+```
+
+| Router | Routes |
+|--------|--------|
+| `auth_router` | register, login, logout, refresh |
+| `profile_router` | me, verified-me, update profile, delete account, change password |
+| `verify_router` | email verification, password reset |
+| `admin_router` | assign/remove roles and permissions (superuser) |
+| `oauth_router` | OAuth provider routes (only if configured) |
+
+`fullauth.init_app(app)` includes all of them. Use individual routers for granular control.
 
 ## Routes
 
@@ -148,15 +173,19 @@ Omit `secret_key` in dev and a random one is generated (tokens won't survive res
 | `POST` | `/auth/password-reset/confirm` | Reset password |
 | `POST` | `/auth/admin/assign-role` | Assign role (superuser) |
 | `POST` | `/auth/admin/remove-role` | Remove role (superuser) |
+| `POST` | `/auth/admin/assign-permission` | Assign permission to role (superuser) |
+| `POST` | `/auth/admin/remove-permission` | Remove permission from role (superuser) |
+| `GET` | `/auth/admin/role-permissions/{role}` | List role's permissions (superuser) |
 
 With OAuth enabled, additional routes are registered under `/auth/oauth/`. All routes are prefixed with `/api/v1` by default.
 
-## Custom user fields
+## Custom user schemas
 
-Define your model — schemas are auto-derived:
+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,
 )
@@ -170,13 +199,37 @@ class User(UserBase, table=True):
     roles: list[Role] = Relationship(link_model=UserRoleLink)
     refresh_tokens: list[RefreshTokenRecord] = Relationship()
 
+class MyUserSchema(UserSchema):
+    display_name: str = ""
+    phone: str = ""
+
+class MyCreateSchema(CreateUserSchema):
+    display_name: str = ""
+
 fullauth = FullAuth(
-    secret_key="...",
-    adapter=SQLModelAdapter(session_maker, user_model=User),
+    adapter=SQLModelAdapter(
+        session_maker,
+        user_model=User,
+        user_schema=MyUserSchema,
+        create_user_schema=MyCreateSchema,
+    ),
+    config=FullAuthConfig(SECRET_KEY="..."),
 )
 ```
 
-Registration and response schemas pick up `display_name` and `phone` automatically. No separate schema classes needed.
+Full IDE autocompletion and type checking on custom fields. Use `get_current_user_dependency()` for typed dependencies:
+
+```python
+from typing import Annotated
+from fastapi import Depends
+from fastapi_fullauth.dependencies import get_current_user_dependency
+
+MyCurrentUser = Annotated[MyUserSchema, Depends(get_current_user_dependency(MyUserSchema))]
+
+@app.get("/profile")
+async def profile(user: MyCurrentUser):
+    return {"name": user.display_name}  # IDE knows this field exists
+```
 
 ## Protected routes
 
@@ -204,24 +257,28 @@ async def editor_panel(user=Depends(require_role("editor"))):
 ## OAuth2 social login
 
 ```python
+from fastapi_fullauth import FullAuth, FullAuthConfig
+from fastapi_fullauth.oauth.google import GoogleOAuthProvider
+from fastapi_fullauth.oauth.github import GitHubOAuthProvider
+
 fullauth = FullAuth(
-    secret_key="...",
     adapter=adapter,
-    oauth_providers={
-        "google": {
-            "client_id": "your-google-client-id",
-            "client_secret": "your-google-secret",
-            "redirect_uris": [
+    config=FullAuthConfig(SECRET_KEY="..."),
+    providers=[
+        GoogleOAuthProvider(
+            client_id="your-google-client-id",
+            client_secret="your-google-secret",
+            redirect_uris=[
                 "http://localhost:3000/auth/callback",
                 "https://myapp.com/auth/callback",
             ],
-        },
-        "github": {
-            "client_id": "your-github-client-id",
-            "client_secret": "your-github-secret",
-            "redirect_uri": "http://localhost:3000/auth/callback",
-        },
-    },
+        ),
+        GitHubOAuthProvider(
+            client_id="your-github-client-id",
+            client_secret="your-github-secret",
+            redirect_uris=["http://localhost:3000/auth/callback"],
+        ),
+    ],
 )
 ```
 
@@ -244,25 +301,36 @@ Events: `after_register`, `after_login`, `after_logout`, `after_password_change`
 
 ## Configuration
 
-Pass inline kwargs or a config object. All options read from env vars with `FULLAUTH_` prefix.
+Pass a `FullAuthConfig` object or set env vars with `FULLAUTH_` prefix.
 
 ```python
 fullauth = FullAuth(
-    secret_key="...",
     adapter=adapter,
-    access_token_expire_minutes=60,
-    api_prefix="/api/v2",
-    login_field="username",
-    password_hash_algorithm="bcrypt",
-    blacklist_backend="redis",
-    redis_url="redis://localhost:6379/0",
-    rate_limit_enabled=True,
-    trusted_proxy_headers=["X-Forwarded-For"],
+    config=FullAuthConfig(
+        SECRET_KEY="...",
+        ACCESS_TOKEN_EXPIRE_MINUTES=60,
+        API_PREFIX="/api/v2",
+        LOGIN_FIELD="username",
+        PASSWORD_HASH_ALGORITHM="bcrypt",
+        BLACKLIST_BACKEND="redis",
+        REDIS_URL="redis://localhost:6379/0",
+        AUTH_RATE_LIMIT_ENABLED=True,
+        TRUSTED_PROXY_HEADERS=["X-Forwarded-For"],
+    ),
 )
 ```
 
 See [Configuration docs](https://mdfarhankc.github.io/fastapi-fullauth/configuration/) for all options.
 
+## AI-friendly docs
+
+Using an AI coding assistant? Point it at our LLM-optimized docs:
+
+- **[llms.txt](https://mdfarhankc.github.io/fastapi-fullauth/llms.txt)** — concise overview with links to all doc pages
+- **[llms-full.txt](https://mdfarhankc.github.io/fastapi-fullauth/llms-full.txt)** — full documentation in a single file
+
+Works with Claude, Cursor, Copilot, and any tool that accepts a docs URL.
+
 ## Development
 
 ```bash
@@ -272,7 +340,6 @@ uv sync --dev --extra sqlalchemy --extra sqlmodel
 uv run pytest tests/ -v
 
 # run examples
-uv run uvicorn examples.memory_app.main:app --reload
 uv run uvicorn examples.sqlmodel_app.main:app --reload
 ```