feat: add security module

* feat: add models module

* docs: add models module

docs/module/exceptions.md

@@ -21,30 +21,37 @@ init_exceptions_handlers(app=app)
 This registers handlers for:
 
 - [`ApiException`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.ApiException) — all custom exceptions below
+- `HTTPException` — Starlette/FastAPI HTTP errors
 - `RequestValidationError` — Pydantic request validation (422)
 - `ResponseValidationError` — Pydantic response validation (422)
 - `Exception` — unhandled errors (500)
 
+It also patches `app.openapi()` to replace the default Pydantic 422 schema with a structured example matching the `ErrorResponse` format.
+
 ## Built-in exceptions
 
 | Exception | Status | Default message |
 |-----------|--------|-----------------|
 | [`UnauthorizedError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.UnauthorizedError) | 401 | Unauthorized |
 | [`ForbiddenError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.ForbiddenError) | 403 | Forbidden |
-| [`NotFoundError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.NotFoundError) | 404 | Not found |
+| [`NotFoundError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.NotFoundError) | 404 | Not Found |
 | [`ConflictError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.ConflictError) | 409 | Conflict |
-| [`NoSearchableFieldsError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.NoSearchableFieldsError) | 400 | No searchable fields |
-| [`InvalidFacetFilterError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidFacetFilterError) | 400 | Invalid facet filter |
+| [`NoSearchableFieldsError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.NoSearchableFieldsError) | 400 | No Searchable Fields |
+| [`InvalidFacetFilterError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidFacetFilterError) | 400 | Invalid Facet Filter |
+| [`InvalidOrderFieldError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidOrderFieldError) | 422 | Invalid Order Field |
+
+### Per-instance overrides
+
+All built-in exceptions accept optional keyword arguments to customise the response for a specific raise site without changing the class defaults:
+
+| Argument | Effect |
+|----------|--------|
+| `detail` | Overrides both `str(exc)` (log output) and the `message` field in the response body |
+| `desc` | Overrides the `description` field |
+| `data` | Overrides the `data` field |
 
 ```python
-from fastapi_toolsets.exceptions import NotFoundError
-
-@router.get("/users/{id}")
-async def get_user(id: int, session: AsyncSession = Depends(get_db)):
-    user = await UserCrud.first(session=session, filters=[User.id == id])
-    if not user:
-        raise NotFoundError
-    return user
+raise NotFoundError(detail="User 42 not found", desc="No user with that ID exists in the database.")
 ```
 
 ## Custom exceptions
@@ -58,12 +65,51 @@ from fastapi_toolsets.schemas import ApiError
 class PaymentRequiredError(ApiException):
     api_error = ApiError(
         code=402,
-        msg="Payment required",
+        msg="Payment Required",
         desc="Your subscription has expired.",
-        err_code="PAYMENT_REQUIRED",
+        err_code="BILLING-402",
     )
 ```
 
+!!! warning
+    Subclasses that do not define `api_error` raise a `TypeError` at **class creation time**, not at raise time.
+
+### Custom `__init__`
+
+Override `__init__` to compute `detail`, `desc`, or `data` dynamically, then delegate to `super().__init__()`:
+
+```python
+class OrderValidationError(ApiException):
+    api_error = ApiError(
+        code=422,
+        msg="Order Validation Failed",
+        desc="One or more order fields are invalid.",
+        err_code="ORDER-422",
+    )
+
+    def __init__(self, *field_errors: str) -> None:
+        super().__init__(
+            f"{len(field_errors)} validation error(s)",
+            desc=", ".join(field_errors),
+            data={"errors": [{"message": e} for e in field_errors]},
+        )
+```
+
+### Intermediate base classes
+
+Use `abstract=True` when creating a shared base that is not meant to be raised directly:
+
+```python
+class BillingError(ApiException, abstract=True):
+    """Base for all billing-related errors."""
+
+class PaymentRequiredError(BillingError):
+    api_error = ApiError(code=402, msg="Payment Required", desc="...", err_code="BILLING-402")
+
+class SubscriptionExpiredError(BillingError):
+    api_error = ApiError(code=402, msg="Subscription Expired", desc="...", err_code="BILLING-402-EXP")
+```
+
 ## OpenAPI response documentation
 
 Use [`generate_error_responses`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.generate_error_responses) to add error schemas to your endpoint's OpenAPI spec:
@@ -78,8 +124,7 @@ from fastapi_toolsets.exceptions import generate_error_responses, NotFoundError,
 async def get_user(...): ...
 ```
 
-!!! info
-    The pydantic validation error is automatically added by FastAPI.
+Multiple exceptions sharing the same HTTP status code are grouped under one entry, each appearing as a named example keyed by its `err_code`. This keeps the OpenAPI UI readable when several error variants map to the same status.
 
 ---
 

docs/module/models.md

@@ -0,0 +1,113 @@
+# Models
+
+!!! info "Added in `v2.0`"
+
+Reusable SQLAlchemy 2.0 mixins for common column patterns, designed to be composed freely on any `DeclarativeBase` model.
+
+## Overview
+
+The `models` module provides mixins that each add a single, well-defined column behaviour. They work with standard SQLAlchemy 2.0 declarative syntax and are fully compatible with `AsyncSession`.
+
+```python
+from fastapi_toolsets.models import UUIDMixin, TimestampMixin
+
+class Article(Base, UUIDMixin, TimestampMixin):
+    __tablename__ = "articles"
+
+    title: Mapped[str]
+    content: Mapped[str]
+```
+
+All timestamp columns are timezone-aware (`TIMESTAMPTZ`). All defaults are server-side, so they are also applied when inserting rows via raw SQL outside the ORM.
+
+## Mixins
+
+### [`UUIDMixin`](../reference/models.md#fastapi_toolsets.models.UUIDMixin)
+
+Adds a `id: UUID` primary key generated server-side by PostgreSQL using `gen_random_uuid()` (requires PostgreSQL 13+). The value is retrieved via `RETURNING` after insert, so it is available on the Python object immediately after `flush()`.
+
+```python
+from fastapi_toolsets.models import UUIDMixin
+
+class User(Base, UUIDMixin):
+    __tablename__ = "users"
+
+    username: Mapped[str]
+
+# id is None before flush
+user = User(username="alice")
+await session.flush()
+print(user.id)  # UUID('...')
+```
+
+### [`CreatedAtMixin`](../reference/models.md#fastapi_toolsets.models.CreatedAtMixin)
+
+Adds a `created_at: datetime` column set to `NOW()` on insert. The column has no `onupdate` hook — it is intentionally immutable after the row is created.
+
+```python
+from fastapi_toolsets.models import UUIDMixin, CreatedAtMixin
+
+class Order(Base, UUIDMixin, CreatedAtMixin):
+    __tablename__ = "orders"
+
+    total: Mapped[float]
+```
+
+### [`UpdatedAtMixin`](../reference/models.md#fastapi_toolsets.models.UpdatedAtMixin)
+
+Adds an `updated_at: datetime` column set to `NOW()` on insert and automatically updated to `NOW()` on every ORM-level update (via SQLAlchemy's `onupdate` hook).
+
+```python
+from fastapi_toolsets.models import UUIDMixin, UpdatedAtMixin
+
+class Post(Base, UUIDMixin, UpdatedAtMixin):
+    __tablename__ = "posts"
+
+    title: Mapped[str]
+
+post = Post(title="Hello")
+await session.flush()
+await session.refresh(post)
+
+post.title = "Hello World"
+await session.flush()
+await session.refresh(post)
+print(post.updated_at)
+```
+
+!!! note
+    `updated_at` is updated by SQLAlchemy at ORM flush time. If you update rows via raw SQL (e.g. `UPDATE posts SET ...`), the column will **not** be updated automatically — use a database trigger if you need that guarantee.
+
+### [`TimestampMixin`](../reference/models.md#fastapi_toolsets.models.TimestampMixin)
+
+Convenience mixin that combines [`CreatedAtMixin`](../reference/models.md#fastapi_toolsets.models.CreatedAtMixin) and [`UpdatedAtMixin`](../reference/models.md#fastapi_toolsets.models.UpdatedAtMixin). Equivalent to inheriting both.
+
+```python
+from fastapi_toolsets.models import UUIDMixin, TimestampMixin
+
+class Article(Base, UUIDMixin, TimestampMixin):
+    __tablename__ = "articles"
+
+    title: Mapped[str]
+```
+
+## Composing mixins
+
+All mixins can be combined in any order. The only constraint is that exactly one primary key must be defined — either via `UUIDMixin` or directly on the model.
+
+```python
+from fastapi_toolsets.models import UUIDMixin, TimestampMixin
+
+class Event(Base, UUIDMixin, TimestampMixin):
+    __tablename__ = "events"
+    name: Mapped[str]
+
+class Counter(Base, UpdatedAtMixin):
+    __tablename__ = "counters"
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    value: Mapped[int]
+```
+
+---
+
+[:material-api: API Reference](../reference/models.md)

docs/module/security.md

@@ -0,0 +1,267 @@
+# Security
+
+Composable authentication helpers for FastAPI that use `Security()` for OpenAPI documentation and accept user-provided validator functions with full type flexibility.
+
+## Overview
+
+The `security` module provides four auth source classes and a `MultiAuth` factory. Each class wraps a FastAPI security scheme for OpenAPI and accepts a validator function called as:
+
+```python
+await validator(credential, **kwargs)
+```
+
+where `kwargs` are the extra keyword arguments provided at instantiation (roles, permissions, enums, etc.). The validator returns the authenticated identity (e.g. a `User` model) which becomes the route dependency value.
+
+```python
+from fastapi import Security
+from fastapi_toolsets.security import BearerTokenAuth
+
+async def verify_token(token: str, *, role: str) -> User:
+    user = await db.get_by_token(token)
+    if not user or user.role != role:
+        raise UnauthorizedError()
+    return user
+
+bearer_admin = BearerTokenAuth(verify_token, role="admin")
+
+@app.get("/admin")
+async def admin_route(user: User = Security(bearer_admin)):
+    return user
+```
+
+## Auth sources
+
+### [`BearerTokenAuth`](../reference/security.md#fastapi_toolsets.security.BearerTokenAuth)
+
+Reads the `Authorization: Bearer <token>` header. Wraps `HTTPBearer` for OpenAPI.
+
+```python
+from fastapi_toolsets.security import BearerTokenAuth
+
+bearer = BearerTokenAuth(validator=verify_token)
+
+@app.get("/me")
+async def me(user: User = Security(bearer)):
+    return user
+```
+
+#### Token prefix
+
+The optional `prefix` parameter restricts a `BearerTokenAuth` instance to tokens
+that start with a given string. The prefix is **kept** in the value passed to the
+validator — store and compare tokens with their prefix included.
+
+This lets you deploy multiple `BearerTokenAuth` instances in the same application
+and disambiguate them efficiently in `MultiAuth`:
+
+```python
+user_bearer = BearerTokenAuth(verify_user, prefix="user_")  # matches "Bearer user_..."
+org_bearer  = BearerTokenAuth(verify_org,  prefix="org_")   # matches "Bearer org_..."
+```
+
+Use [`generate_token()`](#token-generation) to create correctly-prefixed tokens.
+
+#### Token generation
+
+`BearerTokenAuth.generate_token()` produces a secure random token ready to store
+in your database and return to the client. If a prefix is configured it is
+prepended automatically:
+
+```python
+bearer = BearerTokenAuth(verify_token, prefix="user_")
+
+token = bearer.generate_token()   # e.g. "user_Xk3mN..."
+await db.store_token(user_id, token)
+return {"access_token": token, "token_type": "bearer"}
+```
+
+The client sends `Authorization: Bearer user_Xk3mN...` and the validator receives
+the full token (prefix included) to compare against the stored value.
+
+### [`CookieAuth`](../reference/security.md#fastapi_toolsets.security.CookieAuth)
+
+Reads a named cookie. Wraps `APIKeyCookie` for OpenAPI.
+
+```python
+from fastapi_toolsets.security import CookieAuth
+
+cookie_auth = CookieAuth("session", validator=verify_session)
+
+@app.get("/me")
+async def me(user: User = Security(cookie_auth)):
+    return user
+```
+
+### [`OAuth2Auth`](../reference/security.md#fastapi_toolsets.security.OAuth2Auth)
+
+Reads the `Authorization: Bearer <token>` header and registers the token endpoint
+in OpenAPI via `OAuth2PasswordBearer`.
+
+```python
+from fastapi_toolsets.security import OAuth2Auth
+
+oauth2_auth = OAuth2Auth(token_url="/token", validator=verify_token)
+
+@app.get("/me")
+async def me(user: User = Security(oauth2_auth)):
+    return user
+```
+
+### [`OpenIDAuth`](../reference/security.md#fastapi_toolsets.security.OpenIDAuth)
+
+Reads the `Authorization: Bearer <token>` header and registers the OpenID Connect
+discovery URL in OpenAPI via `OpenIdConnect`. Token validation is fully delegated
+to your validator — use any OIDC / JWT library (`authlib`, `python-jose`, `PyJWT`).
+
+```python
+from fastapi_toolsets.security import OpenIDAuth
+
+async def verify_google_token(token: str, *, audience: str) -> User:
+    payload = jwt.decode(token, google_public_keys, algorithms=["RS256"],
+                         audience=audience)
+    return User(email=payload["email"], name=payload["name"])
+
+google_auth = OpenIDAuth(
+    "https://accounts.google.com/.well-known/openid-configuration",
+    verify_google_token,
+    audience="my-client-id",
+)
+
+@app.get("/me")
+async def me(user: User = Security(google_auth)):
+    return user
+```
+
+The discovery URL is used **only for OpenAPI documentation** — no requests are made
+to it by this class. You are responsible for fetching and caching the provider's
+public keys in your validator.
+
+Multiple providers work naturally with `MultiAuth`:
+
+```python
+multi = MultiAuth(google_auth, github_auth)
+
+@app.get("/data")
+async def data(user: User = Security(multi)):
+    return user
+```
+
+## Typed validator kwargs
+
+All auth classes forward extra instantiation keyword arguments to the validator.
+Arguments can be any type — enums, strings, integers, etc. The validator returns
+the authenticated identity, which FastAPI injects directly into the route handler.
+
+```python
+async def verify_token(token: str, *, role: Role, permission: str) -> User:
+    user = await decode_token(token)
+    if user.role != role or permission not in user.permissions:
+        raise UnauthorizedError()
+    return user
+
+bearer = BearerTokenAuth(verify_token, role=Role.ADMIN, permission="billing:read")
+```
+
+Each auth instance is self-contained — create a separate instance per distinct
+requirement instead of passing requirements through `Security(scopes=[...])`.
+
+### Using `.require()` inline
+
+If declaring a new top-level variable per role feels verbose, use `.require()` to
+create a configured clone directly in the route decorator. The original instance
+is not mutated:
+
+```python
+bearer = BearerTokenAuth(verify_token)
+
+@app.get("/admin/stats")
+async def admin_stats(user: User = Security(bearer.require(role=Role.ADMIN))):
+    return {"message": f"Hello admin {user.name}"}
+
+@app.get("/profile")
+async def profile(user: User = Security(bearer.require(role=Role.USER))):
+    return {"id": user.id, "name": user.name}
+```
+
+`.require()` kwargs are merged over existing ones — new values win on conflict.
+The `prefix` (for `BearerTokenAuth`) and cookie name (for `CookieAuth`) are
+always preserved.
+
+`.require()` instances work transparently inside `MultiAuth`:
+
+```python
+multi = MultiAuth(
+    user_bearer.require(role=Role.USER),
+    org_bearer.require(role=Role.ADMIN),
+)
+```
+
+## MultiAuth
+
+[`MultiAuth`](../reference/security.md#fastapi_toolsets.security.MultiAuth) combines
+multiple auth sources into a single callable. Sources are tried in order; the
+first one that finds a credential wins.
+
+```python
+from fastapi_toolsets.security import MultiAuth
+
+multi = MultiAuth(user_bearer, org_bearer, cookie_auth)
+
+@app.get("/data")
+async def data_route(user = Security(multi)):
+    return user
+```
+
+### Using `.require()` on MultiAuth
+
+`MultiAuth` also supports `.require()`, which propagates the kwargs to every
+source that implements it. Sources that do not (e.g. custom `AuthSource`
+subclasses) are passed through unchanged:
+
+```python
+multi = MultiAuth(bearer, cookie)
+
+@app.get("/admin")
+async def admin(user: User = Security(multi.require(role=Role.ADMIN))):
+    return user
+```
+
+This is equivalent to calling `.require()` on each source individually:
+
+```python
+# These two are identical
+multi.require(role=Role.ADMIN)
+
+MultiAuth(
+    bearer.require(role=Role.ADMIN),
+    cookie.require(role=Role.ADMIN),
+)
+```
+
+### Prefix-based dispatch
+
+Because `extract()` is pure string matching (no I/O), prefix-based source
+selection is essentially free. Only the matching source's validator (which may
+involve DB or network I/O) is ever called:
+
+```python
+user_bearer = BearerTokenAuth(verify_user, prefix="user_")
+org_bearer  = BearerTokenAuth(verify_org,  prefix="org_")
+
+multi = MultiAuth(user_bearer, org_bearer)
+
+# "Bearer user_alice" → only verify_user runs, receives "user_alice"
+# "Bearer org_acme"   → only verify_org runs, receives "org_acme"
+```
+
+Tokens are stored and compared **with their prefix** — use `generate_token()` on
+each source to issue correctly-prefixed tokens:
+
+```python
+user_token = user_bearer.generate_token()  # "user_..."
+org_token  = org_bearer.generate_token()   # "org_..."
+```
+
+---
+
+[:material-api: API Reference](../reference/security.md)

docs/reference/models.md

@@ -0,0 +1,22 @@
+# `models`
+
+Here's the reference for the SQLAlchemy model mixins provided by the `models` module.
+
+You can import them directly from `fastapi_toolsets.models`:
+
+```python
+from fastapi_toolsets.models import (
+    UUIDMixin,
+    CreatedAtMixin,
+    UpdatedAtMixin,
+    TimestampMixin,
+)
+```
+
+## ::: fastapi_toolsets.models.UUIDMixin
+
+## ::: fastapi_toolsets.models.CreatedAtMixin
+
+## ::: fastapi_toolsets.models.UpdatedAtMixin
+
+## ::: fastapi_toolsets.models.TimestampMixin

docs/reference/security.md

@@ -0,0 +1,28 @@
+# `security`
+
+Here's the reference for the authentication helpers provided by the `security` module.
+
+You can import them directly from `fastapi_toolsets.security`:
+
+```python
+from fastapi_toolsets.security import (
+    AuthSource,
+    BearerTokenAuth,
+    CookieAuth,
+    OAuth2Auth,
+    OpenIDAuth,
+    MultiAuth,
+)
+```
+
+## ::: fastapi_toolsets.security.AuthSource
+
+## ::: fastapi_toolsets.security.BearerTokenAuth
+
+## ::: fastapi_toolsets.security.CookieAuth
+
+## ::: fastapi_toolsets.security.OAuth2Auth
+
+## ::: fastapi_toolsets.security.OpenIDAuth
+
+## ::: fastapi_toolsets.security.MultiAuth

src/fastapi_toolsets/db.py

@@ -10,6 +10,8 @@ from sqlalchemy import text
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 from sqlalchemy.orm import DeclarativeBase
 
+from .exceptions import NotFoundError
+
 __all__ = [
     "LockMode",
     "create_db_context",
@@ -216,7 +218,7 @@ async def wait_for_row_change(
         The refreshed model instance with updated values
 
     Raises:
-        LookupError: If the row does not exist or is deleted during polling
+        NotFoundError: If the row does not exist or is deleted during polling
         TimeoutError: If timeout expires before a change is detected
 
     Example:
@@ -237,7 +239,7 @@ async def wait_for_row_change(
     """
     instance = await session.get(model, pk_value)
     if instance is None:
-        raise LookupError(f"{model.__name__} with pk={pk_value!r} not found")
+        raise NotFoundError(f"{model.__name__} with pk={pk_value!r} not found")
 
     if columns is not None:
         watch_cols = columns
@@ -261,7 +263,7 @@ async def wait_for_row_change(
         instance = await session.get(model, pk_value)
 
         if instance is None:
-            raise LookupError(f"{model.__name__} with pk={pk_value!r} was deleted")
+            raise NotFoundError(f"{model.__name__} with pk={pk_value!r} was deleted")
 
         current = {col: getattr(instance, col) for col in watch_cols}
         if current != initial:

src/fastapi_toolsets/exceptions/exceptions.py

@@ -6,32 +6,46 @@ from ..schemas import ApiError, ErrorResponse, ResponseStatus
 
 
 class ApiException(Exception):
-    """Base exception for API errors with structured response.
-
-    Subclass this to create custom API exceptions with consistent error format.
-    The exception handler will use api_error to generate the response.
-
-    Example:
-        ```python
-        class CustomError(ApiException):
-            api_error = ApiError(
-                code=400,
-                msg="Bad Request",
-                desc="The request was invalid.",
-                err_code="CUSTOM-400",
-            )
-        ```
-    """
+    """Base exception for API errors with structured response."""
 
     api_error: ClassVar[ApiError]
 
-    def __init__(self, detail: str | None = None):
+    def __init_subclass__(cls, abstract: bool = False, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if not abstract and not hasattr(cls, "api_error"):
+            raise TypeError(
+                f"{cls.__name__} must define an 'api_error' class attribute. "
+                "Pass abstract=True when creating intermediate base classes."
+            )
+
+    def __init__(
+        self,
+        detail: str | None = None,
+        *,
+        desc: str | None = None,
+        data: Any = None,
+    ) -> None:
         """Initialize the exception.
 
         Args:
-            detail: Optional override for the error message
+            detail: Optional human-readable message
+            desc: Optional per-instance override for the ``description`` field
+                in the HTTP response body.
+            data: Optional per-instance override for the ``data`` field in the
+                HTTP response body.
         """
-        super().__init__(detail or self.api_error.msg)
+        updates: dict[str, Any] = {}
+        if detail is not None:
+            updates["msg"] = detail
+        if desc is not None:
+            updates["desc"] = desc
+        if data is not None:
+            updates["data"] = data
+        if updates:
+            object.__setattr__(
+                self, "api_error", self.__class__.api_error.model_copy(update=updates)
+            )
+        super().__init__(self.api_error.msg)
 
 
 class UnauthorizedError(ApiException):
@@ -92,14 +106,15 @@ class NoSearchableFieldsError(ApiException):
         """Initialize the exception.
 
         Args:
-            model: The SQLAlchemy model class that has no searchable fields
+            model: The model class that has no searchable fields configured.
         """
         self.model = model
-        detail = (
+        super().__init__(
+            desc=(
                 f"No searchable fields found for model '{model.__name__}'. "
                 "Provide 'search_fields' parameter or set 'searchable_fields' on the CRUD class."
             )
-        super().__init__(detail)
+        )
 
 
 class InvalidFacetFilterError(ApiException):
@@ -116,16 +131,17 @@ class InvalidFacetFilterError(ApiException):
         """Initialize the exception.
 
         Args:
-            key: The unknown filter key provided by the caller
-            valid_keys: Set of valid keys derived from the declared facet_fields
+            key: The unknown filter key provided by the caller.
+            valid_keys: Set of valid keys derived from the declared facet_fields.
         """
         self.key = key
         self.valid_keys = valid_keys
-        detail = (
+        super().__init__(
+            desc=(
                 f"'{key}' is not a declared facet field. "
                 f"Valid keys: {sorted(valid_keys) or 'none — set facet_fields on the CRUD class'}."
             )
-        super().__init__(detail)
+        )
 
 
 class InvalidOrderFieldError(ApiException):
@@ -142,15 +158,14 @@ class InvalidOrderFieldError(ApiException):
         """Initialize the exception.
 
         Args:
-            field: The unknown order field provided by the caller
-            valid_fields: List of valid field names
+            field: The unknown order field provided by the caller.
+            valid_fields: List of valid field names.
         """
         self.field = field
         self.valid_fields = valid_fields
-        detail = (
-            f"'{field}' is not an allowed order field. Valid fields: {valid_fields}."
+        super().__init__(
+            desc=f"'{field}' is not an allowed order field. Valid fields: {valid_fields}."
         )
-        super().__init__(detail)
 
 
 def generate_error_responses(
@@ -158,44 +173,39 @@ def generate_error_responses(
 ) -> dict[int | str, dict[str, Any]]:
     """Generate OpenAPI response documentation for exceptions.
 
-    Use this to document possible error responses for an endpoint.
-
     Args:
-        *errors: Exception classes that inherit from ApiException
+        *errors: Exception classes that inherit from ApiException.
 
     Returns:
-        Dict suitable for FastAPI's responses parameter
-
-    Example:
-        ```python
-        from fastapi_toolsets.exceptions import generate_error_responses, UnauthorizedError, ForbiddenError
-
-        @app.get(
-            "/admin",
-            responses=generate_error_responses(UnauthorizedError, ForbiddenError)
-        )
-        async def admin_endpoint():
-            ...
-        ```
+        Dict suitable for FastAPI's ``responses`` parameter.
     """
     responses: dict[int | str, dict[str, Any]] = {}
 
     for error in errors:
         api_error = error.api_error
+        code = api_error.code
 
-        responses[api_error.code] = {
+        if code not in responses:
+            responses[code] = {
                 "model": ErrorResponse,
                 "description": api_error.msg,
                 "content": {
                     "application/json": {
-                    "example": {
+                        "examples": {},
+                    }
+                },
+            }
+
+        responses[code]["content"]["application/json"]["examples"][
+            api_error.err_code
+        ] = {
+            "summary": api_error.msg,
+            "value": {
                 "data": api_error.data,
                 "status": ResponseStatus.FAIL.value,
                 "message": api_error.msg,
                 "description": api_error.desc,
                 "error_code": api_error.err_code,
-                    }
-                }
             },
         }
 

src/fastapi_toolsets/exceptions/handler.py

@@ -1,10 +1,14 @@
 """Exception handlers for FastAPI applications."""
 
+from collections.abc import Callable
 from typing import Any
 
 from fastapi import FastAPI, Request, Response, status
-from fastapi.exceptions import RequestValidationError, ResponseValidationError
-from fastapi.openapi.utils import get_openapi
+from fastapi.exceptions import (
+    HTTPException,
+    RequestValidationError,
+    ResponseValidationError,
+)
 from fastapi.responses import JSONResponse
 
 from ..schemas import ErrorResponse, ResponseStatus
@@ -14,43 +18,20 @@ from .exceptions import ApiException
 def init_exceptions_handlers(app: FastAPI) -> FastAPI:
     """Register exception handlers and custom OpenAPI schema on a FastAPI app.
 
-    Installs handlers for :class:`ApiException`, validation errors, and
-    unhandled exceptions, and replaces the default 422 schema with a
-    consistent error format.
-
     Args:
-        app: FastAPI application instance
+        app: FastAPI application instance.
 
     Returns:
-        The same FastAPI instance (for chaining)
-
-    Example:
-        ```python
-        from fastapi import FastAPI
-        from fastapi_toolsets.exceptions import init_exceptions_handlers
-
-        app = FastAPI()
-        init_exceptions_handlers(app)
-        ```
+        The same FastAPI instance (for chaining).
     """
     _register_exception_handlers(app)
-    app.openapi = lambda: _custom_openapi(app)  # type: ignore[method-assign]
+    _original_openapi = app.openapi
+    app.openapi = lambda: _patched_openapi(app, _original_openapi)  # type: ignore[method-assign]
     return app
 
 
 def _register_exception_handlers(app: FastAPI) -> None:
-    """Register all exception handlers on a FastAPI application.
-
-    Args:
-        app: FastAPI application instance
-
-    Example:
-        from fastapi import FastAPI
-        from fastapi_toolsets.exceptions import init_exceptions_handlers
-
-        app = FastAPI()
-        init_exceptions_handlers(app)
-    """
+    """Register all exception handlers on a FastAPI application."""
 
     @app.exception_handler(ApiException)
     async def api_exception_handler(request: Request, exc: ApiException) -> Response:
@@ -62,12 +43,25 @@ def _register_exception_handlers(app: FastAPI) -> None:
             description=api_error.desc,
             error_code=api_error.err_code,
         )
-
         return JSONResponse(
             status_code=api_error.code,
             content=error_response.model_dump(),
         )
 
+    @app.exception_handler(HTTPException)
+    async def http_exception_handler(request: Request, exc: HTTPException) -> Response:
+        """Handle Starlette/FastAPI HTTPException with a consistent error format."""
+        detail = exc.detail if isinstance(exc.detail, str) else "HTTP Error"
+        error_response = ErrorResponse(
+            message=detail,
+            error_code=f"HTTP-{exc.status_code}",
+        )
+        return JSONResponse(
+            status_code=exc.status_code,
+            content=error_response.model_dump(),
+            headers=getattr(exc, "headers", None),
+        )
+
     @app.exception_handler(RequestValidationError)
     async def request_validation_handler(
         request: Request, exc: RequestValidationError
@@ -90,7 +84,6 @@ def _register_exception_handlers(app: FastAPI) -> None:
             description="An unexpected error occurred. Please try again later.",
             error_code="SERVER-500",
         )
-
         return JSONResponse(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             content=error_response.model_dump(),
@@ -105,11 +98,10 @@ def _format_validation_error(
     formatted_errors = []
 
     for error in errors:
-        field_path = ".".join(
-            str(loc)
-            for loc in error["loc"]
-            if loc not in ("body", "query", "path", "header", "cookie")
-        )
+        locs = error["loc"]
+        if locs and locs[0] in ("body", "query", "path", "header", "cookie"):
+            locs = locs[1:]
+        field_path = ".".join(str(loc) for loc in locs)
         formatted_errors.append(
             {
                 "field": field_path or "root",
@@ -131,34 +123,22 @@ def _format_validation_error(
     )
 
 
-def _custom_openapi(app: FastAPI) -> dict[str, Any]:
-    """Generate custom OpenAPI schema with standardized error format.
-
-    Replaces default 422 validation error responses with the custom format.
+def _patched_openapi(
+    app: FastAPI, original_openapi: Callable[[], dict[str, Any]]
+) -> dict[str, Any]:
+    """Generate the OpenAPI schema and replace default 422 responses.
 
     Args:
-        app: FastAPI application instance
+        app: FastAPI application instance.
+        original_openapi: The previous ``app.openapi`` callable to delegate to.
 
     Returns:
-        OpenAPI schema dict
-
-    Example:
-        from fastapi import FastAPI
-        from fastapi_toolsets.exceptions import init_exceptions_handlers
-
-        app = FastAPI()
-        init_exceptions_handlers(app)  # Automatically sets custom OpenAPI
+        Patched OpenAPI schema dict.
     """
     if app.openapi_schema:
         return app.openapi_schema
 
-    openapi_schema = get_openapi(
-        title=app.title,
-        version=app.version,
-        openapi_version=app.openapi_version,
-        description=app.description,
-        routes=app.routes,
-    )
+    openapi_schema = original_openapi()
 
     for path_data in openapi_schema.get("paths", {}).values():
         for operation in path_data.values():
@@ -168,7 +148,10 @@ def _custom_openapi(app: FastAPI) -> dict[str, Any]:
                         "description": "Validation Error",
                         "content": {
                             "application/json": {
-                                "example": {
+                                "examples": {
+                                    "VAL-422": {
+                                        "summary": "Validation Error",
+                                        "value": {
                                             "data": {
                                                 "errors": [
                                                     {
@@ -182,6 +165,8 @@ def _custom_openapi(app: FastAPI) -> dict[str, Any]:
                                             "message": "Validation Error",
                                             "description": "1 validation error(s) detected",
                                             "error_code": "VAL-422",
+                                        },
+                                    }
                                 }
                             }
                         },

src/fastapi_toolsets/models.py

@@ -0,0 +1,47 @@
+"""SQLAlchemy model mixins for common column patterns."""
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, Uuid, func, text
+from sqlalchemy.orm import Mapped, mapped_column
+
+__all__ = [
+    "UUIDMixin",
+    "CreatedAtMixin",
+    "UpdatedAtMixin",
+    "TimestampMixin",
+]
+
+
+class UUIDMixin:
+    """Mixin that adds a UUID primary key auto-generated by the database."""
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        Uuid,
+        primary_key=True,
+        server_default=text("gen_random_uuid()"),
+    )
+
+
+class CreatedAtMixin:
+    """Mixin that adds a ``created_at`` timestamp column."""
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+    )
+
+
+class UpdatedAtMixin:
+    """Mixin that adds an ``updated_at`` timestamp column."""
+
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+    )
+
+
+class TimestampMixin(CreatedAtMixin, UpdatedAtMixin):
+    """Mixin that combines ``created_at`` and ``updated_at`` timestamp columns."""

src/fastapi_toolsets/security/__init__.py

@@ -0,0 +1,14 @@
+"""Authentication helpers for FastAPI using Security()."""
+
+from .base import AuthSource
+from .multi import MultiAuth
+from .sources import BearerTokenAuth, CookieAuth, OAuth2Auth, OpenIDAuth
+
+__all__ = [
+    "AuthSource",
+    "BearerTokenAuth",
+    "CookieAuth",
+    "OAuth2Auth",
+    "OpenIDAuth",
+    "MultiAuth",
+]

src/fastapi_toolsets/security/base.py

@@ -0,0 +1,112 @@
+"""Abstract base class for authentication sources."""
+
+import inspect
+from abc import ABC, abstractmethod
+from typing import Any, Callable
+
+from fastapi import Request
+from fastapi.security import SecurityScopes
+
+from fastapi_toolsets.exceptions import UnauthorizedError
+
+
+class AuthSource(ABC):
+    """Abstract base class for authentication sources.
+
+    Subclass this to create a custom auth source that works with
+    :func:`~fastapi_toolsets.security.MultiAuth` and can be used directly
+    with :func:`fastapi.Security`.
+
+    Concrete subclasses must implement :meth:`extract` and
+    :meth:`authenticate`. The default :meth:`__call__` (set up in
+    :meth:`__init__`) wires them together for FastAPI dependency injection.
+
+    Custom subclasses with their own ``__init__`` **must** call
+    ``super().__init__()`` to activate the default dependency behaviour::
+
+        class JWTAuth(AuthSource):
+            def __init__(self, secret: str, *, role: str | None = None):
+                super().__init__()   # required
+                self._secret = secret
+                self._role = role
+
+            async def extract(self, request: Request) -> str | None:
+                auth = request.headers.get("Authorization", "")
+                if not auth.startswith("Bearer "):
+                    return None
+                return auth[7:] or None
+
+            async def authenticate(self, credential: str) -> User:
+                payload = jwt.decode(credential, self._secret)
+                if self._role and payload.get("role") != self._role:
+                    raise UnauthorizedError()
+                return User(**payload)
+
+        jwt_auth = JWTAuth(secret="mysecret")
+
+        @app.get("/me")
+        async def me(user: User = Security(jwt_auth)):
+            return user
+
+        # Works with MultiAuth too
+        multi = MultiAuth(jwt_auth, CookieAuth("session", verify_session))
+
+    .. note::
+        The default ``__call__`` does not register a security scheme in the
+        OpenAPI spec. Built-in sources (``BearerTokenAuth`` etc.) override
+        ``__call__`` using the ``__signature__`` trick to provide a FastAPI
+        security scheme for Swagger UI.
+    """
+
+    def __init__(self) -> None:
+        """Set up the default FastAPI dependency signature.
+
+        Creates a closure that FastAPI can introspect to inject
+        :class:`fastapi.Request` and :class:`fastapi.security.SecurityScopes`.
+        The :meth:`__signature__` attribute is set so that ``inspect.signature``
+        (which FastAPI uses internally) returns the correct parameter list.
+
+        Subclasses with their own ``__init__`` must call ``super().__init__()``.
+        Built-in subclasses (``BearerTokenAuth`` etc.) skip this and set up
+        their own ``_call_fn`` / ``__signature__`` directly.
+        """
+        source = self
+
+        async def _call(
+            request: Request,
+            security_scopes: SecurityScopes,  # noqa: ARG001
+        ) -> Any:
+            credential = await source.extract(request)
+            if credential is None:
+                raise UnauthorizedError()
+            return await source.authenticate(credential)
+
+        self._call_fn: Callable[..., Any] = _call
+        self.__signature__ = inspect.signature(_call)
+
+    @abstractmethod
+    async def extract(self, request: Request) -> str | None:
+        """Extract the raw credential from the request without validating.
+
+        Returns ``None`` if no credential is present for this source.
+        This method must be fast and free of I/O — it is called by
+        :func:`~fastapi_toolsets.security.MultiAuth` for every source on
+        every request.
+        """
+
+    @abstractmethod
+    async def authenticate(self, credential: str) -> Any:
+        """Validate a credential and return the authenticated identity.
+
+        Should raise :class:`~fastapi_toolsets.exceptions.UnauthorizedError`
+        (or any exception) when the credential is invalid. The return value
+        is injected into the route handler as the dependency value.
+        """
+
+    async def __call__(self, **kwargs: Any) -> Any:
+        """FastAPI dependency dispatch.
+
+        Delegates to the closure stored in ``_call_fn``, whose signature
+        (stored in ``__signature__``) tells FastAPI which parameters to inject.
+        """
+        return await self._call_fn(**kwargs)

src/fastapi_toolsets/security/multi.py

@@ -0,0 +1,98 @@
+"""MultiAuth: combine multiple authentication sources into a single callable."""
+
+import inspect
+from typing import Any, cast
+
+from fastapi import Request
+from fastapi.security import SecurityScopes
+
+from fastapi_toolsets.exceptions import UnauthorizedError
+
+from .base import AuthSource
+
+
+class MultiAuth:
+    """Combine multiple authentication sources into a single callable.
+
+    Sources are tried in order; the first one whose
+    :meth:`~AuthSource.extract` returns a non-``None`` credential wins.
+    Its :meth:`~AuthSource.authenticate` is called and the result returned.
+
+    If a credential is found but the validator raises, the exception propagates
+    immediately — the remaining sources are **not** tried. This prevents
+    silent fallthrough on invalid credentials.
+
+    If no source provides a credential,
+    :class:`~fastapi_toolsets.exceptions.UnauthorizedError` is raised.
+
+    The :meth:`~AuthSource.extract` method of each source performs only
+    string matching (no I/O), so prefix-based dispatch is essentially free.
+
+    Any :class:`~AuthSource` subclass — including user-defined ones — can be
+    passed as a source.
+
+    Args:
+        *sources: Auth source instances to try in order.
+
+    Example::
+
+        user_bearer = BearerTokenAuth(verify_user, prefix="user_")
+        org_bearer  = BearerTokenAuth(verify_org,  prefix="org_")
+        cookie      = CookieAuth("session", verify_session)
+
+        multi = MultiAuth(user_bearer, org_bearer, cookie)
+
+        @app.get("/data")
+        async def data_route(user = Security(multi)):
+            return user
+
+        # Apply a shared requirement to all sources at once
+        @app.get("/admin")
+        async def admin_route(user = Security(multi.require(role=Role.ADMIN))):
+            return user
+    """
+
+    def __init__(self, *sources: AuthSource) -> None:
+        self._sources = sources
+
+        _sources = sources
+
+        async def _call(
+            request: Request,
+            security_scopes: SecurityScopes,  # noqa: ARG001
+        ) -> Any:
+            for source in _sources:
+                credential = await source.extract(request)
+                if credential is not None:
+                    return await source.authenticate(credential)
+            raise UnauthorizedError()
+
+        self._call_fn = _call
+        self.__signature__ = inspect.signature(_call)
+
+    async def __call__(self, **kwargs: Any) -> Any:
+        return await self._call_fn(**kwargs)
+
+    def require(self, **kwargs: Any) -> "MultiAuth":
+        """Return a new :class:`MultiAuth` with kwargs forwarded to each source.
+
+        Calls ``.require(**kwargs)`` on every source that supports it. Sources
+        that do not implement ``.require()`` (e.g. custom :class:`~AuthSource`
+        subclasses) are passed through unchanged.
+
+        New kwargs are merged over each source's existing kwargs — new values
+        win on conflict::
+
+            multi = MultiAuth(bearer, cookie)
+
+            @app.get("/admin")
+            async def admin(user = Security(multi.require(role=Role.ADMIN))):
+                return user
+        """
+        new_sources = tuple(
+            cast(Any, source).require(**kwargs)
+            if hasattr(source, "require")
+            else source
+            for source in self._sources
+        )
+        return MultiAuth(*new_sources)

src/fastapi_toolsets/security/sources/__init__.py

@@ -0,0 +1,8 @@
+"""Built-in authentication source implementations."""
+
+from .bearer import BearerTokenAuth
+from .cookie import CookieAuth
+from .oauth2 import OAuth2Auth
+from .openid import OpenIDAuth
+
+__all__ = ["BearerTokenAuth", "CookieAuth", "OAuth2Auth", "OpenIDAuth"]

src/fastapi_toolsets/security/sources/bearer.py

@@ -0,0 +1,171 @@
+"""Bearer token authentication source."""
+
+import inspect
+import secrets
+from typing import Annotated, Any, Callable
+
+from fastapi import Depends
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer, SecurityScopes
+
+from fastapi_toolsets.exceptions import UnauthorizedError
+
+from ..base import AuthSource
+
+
+class BearerTokenAuth(AuthSource):
+    """Bearer token authentication source.
+
+    Wraps :class:`fastapi.security.HTTPBearer` for OpenAPI documentation.
+    The validator is called as ``await validator(credential, **kwargs)``
+    where ``kwargs`` are the extra keyword arguments provided at instantiation.
+
+    Args:
+        validator: Async callable that receives the credential and any extra
+            keyword arguments, and returns the authenticated identity (e.g. a
+            ``User`` model). Should raise
+            :class:`~fastapi_toolsets.exceptions.UnauthorizedError` on failure.
+        prefix: Optional token prefix (e.g. ``"user_"``). If set, only tokens
+            whose value starts with this prefix are matched. The prefix is
+            **kept** in the value passed to the validator — store and compare
+            tokens with their prefix included. Use :meth:`generate_token` to
+            create correctly-prefixed tokens. This enables multiple
+            ``BearerTokenAuth`` instances in the same app (e.g. ``"user_"``
+            for user tokens, ``"org_"`` for org tokens).
+        **kwargs: Extra keyword arguments forwarded to the validator on every
+            call (e.g. ``role=Role.ADMIN``).
+
+    Example::
+
+        async def verify_token(token: str, *, role: Role) -> User:
+            user = await db.get_by_token(token)   # token includes prefix
+            if not user or user.role != role:
+                raise UnauthorizedError()
+            return user
+
+        bearer_admin = BearerTokenAuth(verify_token, prefix="user_", role=Role.ADMIN)
+
+        # Generate a token to store in DB and return to the client:
+        token = bearer_admin.generate_token()   # e.g. "user_Xk3..."
+
+        @app.get("/admin")
+        async def admin_route(user: User = Security(bearer_admin)):
+            return user
+    """
+
+    def __init__(
+        self,
+        validator: Callable[..., Any],
+        *,
+        prefix: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._validator = validator
+        self._prefix = prefix
+        self._kwargs = kwargs
+        self._scheme = HTTPBearer(auto_error=False)
+
+        # Capture locals for the closure — self._scheme cannot be referenced
+        # inside the Annotated default because annotations are evaluated at
+        # function-definition time (no `from __future__ import annotations`).
+        _scheme = self._scheme
+        _validator = validator
+        _kwargs = kwargs
+        _prefix = prefix
+
+        async def _call(
+            # security_scopes is unused in the body but its presence in the
+            # signature tells FastAPI to aggregate scopes from Security() calls
+            # up the dependency chain and expose them in the OpenAPI schema.
+            security_scopes: SecurityScopes,  # noqa: ARG001
+            credentials: Annotated[
+                HTTPAuthorizationCredentials | None, Depends(_scheme)
+            ] = None,
+        ) -> Any:
+            if credentials is None:
+                raise UnauthorizedError()
+            token = credentials.credentials
+            if _prefix is not None and not token.startswith(_prefix):
+                raise UnauthorizedError()
+            return await _validator(token, **_kwargs)
+
+        # __call__ must be defined on the class (not the instance) so that
+        # callable(self) returns True. We expose the closure's signature via
+        # __signature__ so FastAPI resolves the correct sub-dependencies.
+        self._call_fn = _call
+        self.__signature__ = inspect.signature(_call)
+
+    async def __call__(self, **kwargs: Any) -> Any:
+        return await self._call_fn(**kwargs)
+
+    async def extract(self, request: Any) -> str | None:
+        """Extract the raw credential from the request without validating.
+
+        Returns ``None`` if no ``Authorization: Bearer`` header is present,
+        the token is empty, or the token does not match the configured prefix.
+        The prefix is included in the returned value.
+        """
+        auth = request.headers.get("Authorization", "")
+        if not auth.startswith("Bearer "):
+            return None
+        token = auth[7:]
+        if not token:
+            return None
+        if self._prefix is not None and not token.startswith(self._prefix):
+            return None
+        return token
+
+    async def authenticate(self, credential: str) -> Any:
+        """Validate a credential and return the identity.
+
+        Calls ``await validator(credential, **kwargs)`` where ``kwargs`` are
+        the extra keyword arguments provided at instantiation.
+        """
+        return await self._validator(credential, **self._kwargs)
+
+    def require(self, **kwargs: Any) -> "BearerTokenAuth":
+        """Return a new instance with additional (or overriding) validator kwargs.
+
+        Useful for specifying per-endpoint requirements inline without
+        declaring a new top-level variable::
+
+            bearer = BearerTokenAuth(verify_token)
+
+            @app.get("/admin")
+            async def admin(user: User = Security(bearer.require(role=Role.ADMIN))):
+                return user
+
+        The ``prefix`` is preserved. New kwargs are merged over existing ones
+        (new values win on conflict).
+        """
+        return BearerTokenAuth(
+            self._validator,
+            prefix=self._prefix,
+            **{**self._kwargs, **kwargs},
+        )
+
+    def generate_token(self, nbytes: int = 32) -> str:
+        """Generate a secure random token for this auth source.
+
+        Returns a URL-safe random token. If a prefix is configured it is
+        prepended — the returned value is what you store in your database
+        and return to the client as-is.
+
+        Args:
+            nbytes: Number of random bytes before base64 encoding. The
+                resulting string is ``ceil(nbytes * 4 / 3)`` characters
+                (43 chars for the default 32 bytes). Defaults to 32.
+
+        Returns:
+            A ready-to-use token string (e.g. ``"user_Xk3..."``).
+
+        Example::
+
+            bearer = BearerTokenAuth(verify_token, prefix="user_")
+            token = bearer.generate_token()   # "user_<random>"
+            await db.store_token(user_id, token)
+            return {"access_token": token, "token_type": "bearer"}
+        """
+        token = secrets.token_urlsafe(nbytes)
+        if self._prefix is not None:
+            return f"{self._prefix}{token}"
+        return token

src/fastapi_toolsets/security/sources/cookie.py

@@ -0,0 +1,94 @@
+"""Cookie-based authentication source."""
+
+import inspect
+from typing import Annotated, Any, Callable
+
+from fastapi import Depends, Request
+from fastapi.security import APIKeyCookie, SecurityScopes
+
+from fastapi_toolsets.exceptions import UnauthorizedError
+
+from ..base import AuthSource
+
+
+class CookieAuth(AuthSource):
+    """Cookie-based authentication source.
+
+    Wraps :class:`fastapi.security.APIKeyCookie` for OpenAPI documentation.
+
+    Args:
+        name: Cookie name to read the credential from.
+        validator: Async callable that receives the cookie value and any extra
+            keyword arguments, and returns the authenticated identity.
+        **kwargs: Extra keyword arguments forwarded to the validator on every
+            call.
+
+    Example::
+
+        async def verify_session(session_id: str) -> User:
+            user = await db.get_by_session(session_id)
+            if not user:
+                raise UnauthorizedError()
+            return user
+
+        cookie_auth = CookieAuth("session", verify_session)
+
+        @app.get("/me")
+        async def me(user: User = Security(cookie_auth)):
+            return user
+    """
+
+    def __init__(
+        self,
+        name: str,
+        validator: Callable[..., Any],
+        **kwargs: Any,
+    ) -> None:
+        self._name = name
+        self._validator = validator
+        self._kwargs = kwargs
+        self._scheme = APIKeyCookie(name=name, auto_error=False)
+
+        _scheme = self._scheme
+        _validator = validator
+        _kwargs = kwargs
+
+        async def _call(
+            security_scopes: SecurityScopes,  # noqa: ARG001
+            value: Annotated[str | None, Depends(_scheme)] = None,
+        ) -> Any:
+            if value is None:
+                raise UnauthorizedError()
+            return await _validator(value, **_kwargs)
+
+        self._call_fn = _call
+        self.__signature__ = inspect.signature(_call)
+
+    async def __call__(self, **kwargs: Any) -> Any:
+        return await self._call_fn(**kwargs)
+
+    async def extract(self, request: Request) -> str | None:
+        """Extract the cookie value from the request without validating."""
+        return request.cookies.get(self._name)
+
+    async def authenticate(self, credential: str) -> Any:
+        """Validate a credential and return the identity."""
+        return await self._validator(credential, **self._kwargs)
+
+    def require(self, **kwargs: Any) -> "CookieAuth":
+        """Return a new instance with additional (or overriding) validator kwargs.
+
+        The cookie name is preserved. New kwargs are merged over existing ones
+        (new values win on conflict)::
+
+            cookie = CookieAuth("session", verify_session)
+
+            @app.get("/admin")
+            async def admin(user: User = Security(cookie.require(role=Role.ADMIN))):
+                return user
+        """
+        return CookieAuth(
+            self._name,
+            self._validator,
+            **{**self._kwargs, **kwargs},
+        )

src/fastapi_toolsets/security/sources/oauth2.py

@@ -0,0 +1,96 @@
+"""OAuth2 password-bearer authentication source."""
+
+import inspect
+from typing import Annotated, Any, Callable
+
+from fastapi import Depends, Request
+from fastapi.security import OAuth2PasswordBearer, SecurityScopes
+
+from fastapi_toolsets.exceptions import UnauthorizedError
+
+from ..base import AuthSource
+
+
+class OAuth2Auth(AuthSource):
+    """OAuth2 password-bearer authentication source.
+
+    Wraps :class:`fastapi.security.OAuth2PasswordBearer` for OpenAPI
+    documentation.
+
+    Args:
+        token_url: URL of the token endpoint (used in OpenAPI docs).
+        validator: Async callable that receives the token and any extra keyword
+            arguments, and returns the authenticated identity.
+        **kwargs: Extra keyword arguments forwarded to the validator on every
+            call.
+
+    Example::
+
+        async def verify_token(token: str) -> User:
+            ...
+
+        oauth2_auth = OAuth2Auth(token_url="/token", validator=verify_token)
+
+        @app.get("/me")
+        async def me(user: User = Security(oauth2_auth)):
+            return user
+    """
+
+    def __init__(
+        self,
+        token_url: str,
+        validator: Callable[..., Any],
+        **kwargs: Any,
+    ) -> None:
+        self._token_url = token_url
+        self._validator = validator
+        self._kwargs = kwargs
+        self._scheme = OAuth2PasswordBearer(tokenUrl=token_url, auto_error=False)
+
+        _scheme = self._scheme
+        _validator = validator
+        _kwargs = kwargs
+
+        async def _call(
+            security_scopes: SecurityScopes,  # noqa: ARG001
+            token: Annotated[str | None, Depends(_scheme)] = None,
+        ) -> Any:
+            if token is None:
+                raise UnauthorizedError()
+            return await _validator(token, **_kwargs)
+
+        self._call_fn = _call
+        self.__signature__ = inspect.signature(_call)
+
+    async def __call__(self, **kwargs: Any) -> Any:
+        return await self._call_fn(**kwargs)
+
+    async def extract(self, request: Request) -> str | None:
+        """Extract the bearer token from the Authorization header."""
+        auth = request.headers.get("Authorization", "")
+        if not auth.startswith("Bearer "):
+            return None
+        token = auth[7:]
+        return token or None
+
+    async def authenticate(self, credential: str) -> Any:
+        """Validate a credential and return the identity."""
+        return await self._validator(credential, **self._kwargs)
+
+    def require(self, **kwargs: Any) -> "OAuth2Auth":
+        """Return a new instance with additional (or overriding) validator kwargs.
+
+        The token URL is preserved. New kwargs are merged over existing ones
+        (new values win on conflict)::
+
+            oauth2 = OAuth2Auth("/token", verify_token)
+
+            @app.get("/admin")
+            async def admin(user: User = Security(oauth2.require(role=Role.ADMIN))):
+                return user
+        """
+        return OAuth2Auth(
+            self._token_url,
+            self._validator,
+            **{**self._kwargs, **kwargs},
+        )

src/fastapi_toolsets/security/sources/openid.py

@@ -0,0 +1,127 @@
+"""OpenID Connect authentication source."""
+
+import inspect
+from typing import Annotated, Any, Callable
+
+from fastapi import Depends, Request
+from fastapi.security import OpenIdConnect, SecurityScopes
+
+from fastapi_toolsets.exceptions import UnauthorizedError
+
+from ..base import AuthSource
+
+
+class OpenIDAuth(AuthSource):
+    """OpenID Connect authentication source.
+
+    Wraps :class:`fastapi.security.OpenIdConnect` for OpenAPI documentation.
+    Token extraction reads the ``Authorization: Bearer <token>`` header;
+    validation is fully delegated to the user-supplied validator (use any
+    OIDC / JWT library such as ``authlib``, ``python-jose``, or ``PyJWT``).
+
+    Args:
+        openid_connect_url: URL of the OIDC discovery document
+            (``/.well-known/openid-configuration``). Used only for OpenAPI
+            documentation — no requests are made to this URL by this class.
+        validator: Async callable that receives the raw bearer token and any
+            extra keyword arguments, and returns the authenticated identity.
+            Should raise :class:`~fastapi_toolsets.exceptions.UnauthorizedError`
+            on failure.
+        **kwargs: Extra keyword arguments forwarded to the validator on every
+            call (e.g. ``audience="my-app"``).
+
+    Example — Google::
+
+        import jwt  # e.g. PyJWT or python-jose
+
+        async def verify_google_token(token: str, *, audience: str) -> User:
+            payload = jwt.decode(token, google_public_keys, algorithms=["RS256"],
+                                 audience=audience)
+            return User(email=payload["email"], name=payload["name"])
+
+        google_auth = OpenIDAuth(
+            "https://accounts.google.com/.well-known/openid-configuration",
+            verify_google_token,
+            audience="my-client-id",
+        )
+
+        @app.get("/me")
+        async def me(user: User = Security(google_auth)):
+            return user
+
+    Multiple providers with :func:`~fastapi_toolsets.security.MultiAuth`::
+
+        multi = MultiAuth(google_auth, github_auth)
+
+        @app.get("/data")
+        async def data(user: User = Security(multi)):
+            return user
+    """
+
+    def __init__(
+        self,
+        openid_connect_url: str,
+        validator: Callable[..., Any],
+        **kwargs: Any,
+    ) -> None:
+        self._openid_connect_url = openid_connect_url
+        self._validator = validator
+        self._kwargs = kwargs
+        self._scheme = OpenIdConnect(
+            openIdConnectUrl=openid_connect_url, auto_error=False
+        )
+
+        _scheme = self._scheme
+        _validator = validator
+        _kwargs = kwargs
+
+        async def _call(
+            security_scopes: SecurityScopes,  # noqa: ARG001
+            # OpenIdConnect (OAuth2 base) returns the full Authorization header
+            # value (e.g. "Bearer <token>"), unlike OAuth2PasswordBearer which
+            # strips the scheme prefix.
+            authorization: Annotated[str | None, Depends(_scheme)] = None,
+        ) -> Any:
+            if authorization is None:
+                raise UnauthorizedError()
+            if not authorization.startswith("Bearer "):
+                raise UnauthorizedError()
+            token = authorization[7:]
+            if not token:
+                raise UnauthorizedError()
+            return await _validator(token, **_kwargs)
+
+        self._call_fn = _call
+        self.__signature__ = inspect.signature(_call)
+
+    async def __call__(self, **kwargs: Any) -> Any:
+        return await self._call_fn(**kwargs)
+
+    async def extract(self, request: Request) -> str | None:
+        """Extract the bearer token from the Authorization header."""
+        auth = request.headers.get("Authorization", "")
+        if not auth.startswith("Bearer "):
+            return None
+        return auth[7:] or None
+
+    async def authenticate(self, credential: str) -> Any:
+        """Validate a credential and return the identity."""
+        return await self._validator(credential, **self._kwargs)
+
+    def require(self, **kwargs: Any) -> "OpenIDAuth":
+        """Return a new instance with additional (or overriding) validator kwargs.
+
+        The discovery URL is preserved. New kwargs are merged over existing ones
+        (new values win on conflict)::
+
+            google_auth = OpenIDAuth(discovery_url, verify_google_token, audience="app")
+
+            @app.get("/admin")
+            async def admin(user: User = Security(google_auth.require(role=Role.ADMIN))):
+                return user
+        """
+        return OpenIDAuth(
+            self._openid_connect_url,
+            self._validator,
+            **{**self._kwargs, **kwargs},
+        )

tests/test_crud_search.py

@@ -410,7 +410,7 @@ class TestNoSearchableFieldsError:
         from fastapi_toolsets.exceptions import NoSearchableFieldsError
 
         error = NoSearchableFieldsError(User)
-        assert "User" in str(error)
+        assert "User" in error.api_error.desc
         assert error.model is User
 
     def test_error_raised_when_no_fields(self):
@@ -434,7 +434,7 @@ class TestNoSearchableFieldsError:
             build_search_filters(NoStringModel, "test")
 
         assert exc_info.value.model is NoStringModel
-        assert "NoStringModel" in str(exc_info.value)
+        assert "NoStringModel" in exc_info.value.api_error.desc
 
 
 class TestGetSearchableFields:

tests/test_db.py

@@ -14,6 +14,7 @@ from fastapi_toolsets.db import (
     lock_tables,
     wait_for_row_change,
 )
+from fastapi_toolsets.exceptions import NotFoundError
 
 from .conftest import DATABASE_URL, Base, Role, RoleCrud, User
 
@@ -307,9 +308,9 @@ class TestWaitForRowChange:
 
     @pytest.mark.anyio
     async def test_nonexistent_row_raises(self, db_session: AsyncSession):
-        """Raises LookupError when the row does not exist."""
+        """Raises NotFoundError when the row does not exist."""
         fake_id = uuid.uuid4()
-        with pytest.raises(LookupError, match="not found"):
+        with pytest.raises(NotFoundError, match="not found"):
             await wait_for_row_change(db_session, Role, fake_id, interval=0.05)
 
     @pytest.mark.anyio
@@ -326,7 +327,7 @@ class TestWaitForRowChange:
 
     @pytest.mark.anyio
     async def test_deleted_row_raises(self, db_session: AsyncSession, engine):
-        """Raises LookupError when the row is deleted during polling."""
+        """Raises NotFoundError when the row is deleted during polling."""
         role = Role(name="delete_role")
         db_session.add(role)
         await db_session.commit()
@@ -340,6 +341,6 @@ class TestWaitForRowChange:
                 await other.commit()
 
         delete_task = asyncio.create_task(delete_later())
-        with pytest.raises(LookupError):
+        with pytest.raises(NotFoundError):
             await wait_for_row_change(db_session, Role, role.id, interval=0.05)
         await delete_task

tests/test_exceptions.py

@@ -2,6 +2,7 @@
 
 import pytest
 from fastapi import FastAPI
+from fastapi.exceptions import HTTPException
 from fastapi.testclient import TestClient
 
 from fastapi_toolsets.exceptions import (
@@ -36,8 +37,8 @@ class TestApiException:
         assert error.api_error.msg == "I'm a teapot"
         assert str(error) == "I'm a teapot"
 
-    def test_custom_detail_message(self):
-        """Custom detail overrides default message."""
+    def test_detail_overrides_msg_and_str(self):
+        """detail sets both str(exc) and api_error.msg; class-level msg is unchanged."""
 
         class CustomError(ApiException):
             api_error = ApiError(
@@ -47,8 +48,172 @@ class TestApiException:
                 err_code="BAD-400",
             )
 
-        error = CustomError("Custom message")
-        assert str(error) == "Custom message"
+        error = CustomError("Widget not found")
+        assert str(error) == "Widget not found"
+        assert error.api_error.msg == "Widget not found"
+        assert CustomError.api_error.msg == "Bad Request"  # class unchanged
+
+    def test_desc_override(self):
+        """desc kwarg overrides api_error.desc on the instance only."""
+
+        class MyError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+        err = MyError(desc="Custom desc.")
+        assert err.api_error.desc == "Custom desc."
+        assert MyError.api_error.desc == "Default."  # class unchanged
+
+    def test_data_override(self):
+        """data kwarg sets api_error.data on the instance only."""
+
+        class MyError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+        err = MyError(data={"key": "value"})
+        assert err.api_error.data == {"key": "value"}
+        assert MyError.api_error.data is None  # class unchanged
+
+    def test_desc_and_data_override(self):
+        """detail, desc and data can all be overridden together."""
+
+        class MyError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+        err = MyError("custom msg", desc="New desc.", data={"x": 1})
+        assert str(err) == "custom msg"
+        assert err.api_error.msg == "custom msg"  # detail also updates msg
+        assert err.api_error.desc == "New desc."
+        assert err.api_error.data == {"x": 1}
+        assert err.api_error.code == 400  # other fields unchanged
+
+    def test_class_api_error_not_mutated_after_instance_override(self):
+        """Raising with desc/data does not mutate the class-level api_error."""
+
+        class MyError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+        MyError(desc="Changed", data={"x": 1})
+        assert MyError.api_error.desc == "Default."
+        assert MyError.api_error.data is None
+
+    def test_subclass_uses_super_with_desc_and_data(self):
+        """Subclasses can delegate detail/desc/data to super().__init__()."""
+
+        class BuildValidationError(ApiException):
+            api_error = ApiError(
+                code=422,
+                msg="Build Validation Error",
+                desc="The build configuration is invalid.",
+                err_code="BUILD-422",
+            )
+
+            def __init__(self, *errors: str) -> None:
+                super().__init__(
+                    f"{len(errors)} validation error(s)",
+                    desc=", ".join(errors),
+                    data={"errors": [{"message": e} for e in errors]},
+                )
+
+        err = BuildValidationError("Field A is required", "Field B is invalid")
+        assert str(err) == "2 validation error(s)"
+        assert err.api_error.msg == "2 validation error(s)"  # detail set msg
+        assert err.api_error.desc == "Field A is required, Field B is invalid"
+        assert err.api_error.data == {
+            "errors": [
+                {"message": "Field A is required"},
+                {"message": "Field B is invalid"},
+            ]
+        }
+        assert err.api_error.code == 422  # other fields unchanged
+
+    def test_detail_desc_data_in_http_response(self):
+        """detail/desc/data overrides all appear correctly in the FastAPI HTTP response."""
+
+        class DynamicError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+            def __init__(self, message: str) -> None:
+                super().__init__(
+                    message,
+                    desc=f"Detail: {message}",
+                    data={"reason": message},
+                )
+
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/error")
+        async def raise_error():
+            raise DynamicError("something went wrong")
+
+        client = TestClient(app)
+        response = client.get("/error")
+
+        assert response.status_code == 400
+        body = response.json()
+        assert body["message"] == "something went wrong"
+        assert body["description"] == "Detail: something went wrong"
+        assert body["data"] == {"reason": "something went wrong"}
+
+
+class TestApiExceptionGuard:
+    """Tests for the __init_subclass__ api_error guard."""
+
+    def test_missing_api_error_raises_type_error(self):
+        """Defining a subclass without api_error raises TypeError at class creation time."""
+        with pytest.raises(
+            TypeError, match="must define an 'api_error' class attribute"
+        ):
+
+            class BrokenError(ApiException):
+                pass
+
+    def test_abstract_subclass_skips_guard(self):
+        """abstract=True allows intermediate base classes without api_error."""
+
+        class BaseGroupError(ApiException, abstract=True):
+            pass
+
+        # Concrete child must still define it
+        class ConcreteError(BaseGroupError):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Desc.", err_code="ERR-400"
+            )
+
+        err = ConcreteError()
+        assert err.api_error.code == 400
+
+    def test_abstract_child_still_requires_api_error_on_concrete(self):
+        """Concrete subclass of an abstract class must define api_error."""
+
+        class Base(ApiException, abstract=True):
+            pass
+
+        with pytest.raises(
+            TypeError, match="must define an 'api_error' class attribute"
+        ):
+
+            class Concrete(Base):
+                pass
+
+    def test_inherited_api_error_satisfies_guard(self):
+        """Subclass that inherits api_error from a parent does not need its own."""
+
+        class ConcreteError(NotFoundError):
+            pass
+
+        err = ConcreteError()
+        assert err.api_error.code == 404
 
 
 class TestBuiltInExceptions:
@@ -90,7 +255,7 @@ class TestGenerateErrorResponses:
         assert responses[404]["description"] == "Not Found"
 
     def test_generates_multiple_responses(self):
-        """Generates responses for multiple exceptions."""
+        """Generates responses for multiple exceptions with distinct status codes."""
         responses = generate_error_responses(
             UnauthorizedError,
             ForbiddenError,
@@ -101,15 +266,24 @@ class TestGenerateErrorResponses:
         assert 403 in responses
         assert 404 in responses
 
-    def test_response_has_example(self):
-        """Generated response includes example."""
+    def test_response_has_named_example(self):
+        """Generated response uses named examples keyed by err_code."""
         responses = generate_error_responses(NotFoundError)
-        example = responses[404]["content"]["application/json"]["example"]
+        examples = responses[404]["content"]["application/json"]["examples"]
 
-        assert example["status"] == "FAIL"
-        assert example["error_code"] == "RES-404"
-        assert example["message"] == "Not Found"
-        assert example["data"] is None
+        assert "RES-404" in examples
+        value = examples["RES-404"]["value"]
+        assert value["status"] == "FAIL"
+        assert value["error_code"] == "RES-404"
+        assert value["message"] == "Not Found"
+        assert value["data"] is None
+
+    def test_response_example_has_summary(self):
+        """Each named example carries a summary equal to api_error.msg."""
+        responses = generate_error_responses(NotFoundError)
+        example = responses[404]["content"]["application/json"]["examples"]["RES-404"]
+
+        assert example["summary"] == "Not Found"
 
     def test_response_example_with_data(self):
         """Generated response includes data when set on ApiError."""
@@ -124,9 +298,49 @@ class TestGenerateErrorResponses:
             )
 
         responses = generate_error_responses(ErrorWithData)
-        example = responses[400]["content"]["application/json"]["example"]
+        value = responses[400]["content"]["application/json"]["examples"]["BAD-400"][
+            "value"
+        ]
 
-        assert example["data"] == {"details": "some context"}
+        assert value["data"] == {"details": "some context"}
+
+    def test_two_errors_same_code_both_present(self):
+        """Two exceptions with the same HTTP code produce two named examples."""
+
+        class BadRequestA(ApiException):
+            api_error = ApiError(
+                code=400, msg="Bad A", desc="Reason A.", err_code="ERR-A"
+            )
+
+        class BadRequestB(ApiException):
+            api_error = ApiError(
+                code=400, msg="Bad B", desc="Reason B.", err_code="ERR-B"
+            )
+
+        responses = generate_error_responses(BadRequestA, BadRequestB)
+
+        assert 400 in responses
+        examples = responses[400]["content"]["application/json"]["examples"]
+        assert "ERR-A" in examples
+        assert "ERR-B" in examples
+        assert examples["ERR-A"]["value"]["message"] == "Bad A"
+        assert examples["ERR-B"]["value"]["message"] == "Bad B"
+
+    def test_two_errors_same_code_single_top_level_entry(self):
+        """Two exceptions with the same HTTP code produce exactly one top-level entry."""
+
+        class BadRequestA(ApiException):
+            api_error = ApiError(
+                code=400, msg="Bad A", desc="Reason A.", err_code="ERR-A"
+            )
+
+        class BadRequestB(ApiException):
+            api_error = ApiError(
+                code=400, msg="Bad B", desc="Reason B.", err_code="ERR-B"
+            )
+
+        responses = generate_error_responses(BadRequestA, BadRequestB)
+        assert len([k for k in responses if k == 400]) == 1
 
 
 class TestInitExceptionsHandlers:
@@ -250,13 +464,68 @@ class TestInitExceptionsHandlers:
         assert data["status"] == "FAIL"
         assert data["error_code"] == "SERVER-500"
 
-    def test_custom_openapi_schema(self):
-        """Customizes OpenAPI schema for 422 responses."""
+    def test_handles_http_exception(self):
+        """Handles starlette HTTPException with consistent ErrorResponse envelope."""
         app = FastAPI()
         init_exceptions_handlers(app)
 
+        @app.get("/protected")
+        async def protected():
+            raise HTTPException(status_code=403, detail="Forbidden")
+
+        client = TestClient(app)
+        response = client.get("/protected")
+
+        assert response.status_code == 403
+        data = response.json()
+        assert data["status"] == "FAIL"
+        assert data["error_code"] == "HTTP-403"
+        assert data["message"] == "Forbidden"
+
+    def test_handles_http_exception_404_from_route(self):
+        """HTTPException(404) raised inside a route uses the consistent ErrorResponse envelope."""
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/items/{item_id}")
+        async def get_item(item_id: int):
+            raise HTTPException(status_code=404, detail="Item not found")
+
+        client = TestClient(app)
+        response = client.get("/items/99")
+
+        assert response.status_code == 404
+        data = response.json()
+        assert data["status"] == "FAIL"
+        assert data["error_code"] == "HTTP-404"
+        assert data["message"] == "Item not found"
+
+    def test_handles_http_exception_forwards_headers(self):
+        """HTTPException with WWW-Authenticate header forwards it in the response."""
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/secure")
+        async def secure():
+            raise HTTPException(
+                status_code=401,
+                detail="Not authenticated",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+
+        client = TestClient(app)
+        response = client.get("/secure")
+
+        assert response.status_code == 401
+        assert response.headers.get("www-authenticate") == "Bearer"
+
+    def test_custom_openapi_schema(self):
+        """Customises OpenAPI schema for 422 responses using named examples."""
         from pydantic import BaseModel
 
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
         class Item(BaseModel):
             name: str
 
@@ -269,8 +538,128 @@ class TestInitExceptionsHandlers:
         post_op = openapi["paths"]["/items"]["post"]
         assert "422" in post_op["responses"]
         resp_422 = post_op["responses"]["422"]
-        example = resp_422["content"]["application/json"]["example"]
-        assert example["error_code"] == "VAL-422"
+        examples = resp_422["content"]["application/json"]["examples"]
+        assert "VAL-422" in examples
+        assert examples["VAL-422"]["value"]["error_code"] == "VAL-422"
+
+    def test_custom_openapi_preserves_app_metadata(self):
+        """_patched_openapi preserves custom FastAPI app-level metadata."""
+        app = FastAPI(
+            title="My API",
+            version="2.0.0",
+            description="Custom description",
+        )
+        init_exceptions_handlers(app)
+
+        schema = app.openapi()
+        assert schema["info"]["title"] == "My API"
+        assert schema["info"]["version"] == "2.0.0"
+
+    def test_handles_response_validation_error(self):
+        """Handles ResponseValidationError with a structured 422 response."""
+        from pydantic import BaseModel
+
+        class CountResponse(BaseModel):
+            count: int
+
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/broken", response_model=CountResponse)
+        async def broken():
+            return {"count": "not-a-number"}  # triggers ResponseValidationError
+
+        client = TestClient(app, raise_server_exceptions=False)
+        response = client.get("/broken")
+
+        assert response.status_code == 422
+        data = response.json()
+        assert data["status"] == "FAIL"
+        assert data["error_code"] == "VAL-422"
+        assert "errors" in data["data"]
+
+    def test_handles_validation_error_with_non_standard_loc(self):
+        """Validation error with empty loc tuple maps the field to 'root'."""
+        from fastapi.exceptions import RequestValidationError
+
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/root-error")
+        async def root_error():
+            raise RequestValidationError(
+                [
+                    {
+                        "type": "custom",
+                        "loc": (),
+                        "msg": "root level error",
+                        "input": None,
+                        "url": "",
+                    }
+                ]
+            )
+
+        client = TestClient(app)
+        response = client.get("/root-error")
+
+        assert response.status_code == 422
+        data = response.json()
+        assert data["data"]["errors"][0]["field"] == "root"
+
+    def test_openapi_schema_cached_after_first_call(self):
+        """app.openapi() returns the cached schema on subsequent calls."""
+        from pydantic import BaseModel
+
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        class Item(BaseModel):
+            name: str
+
+        @app.post("/items")
+        async def create_item(item: Item):
+            return item
+
+        schema_first = app.openapi()
+        schema_second = app.openapi()
+        assert schema_first is schema_second
+
+    def test_openapi_skips_operations_without_422(self):
+        """_patched_openapi leaves operations that have no 422 response unchanged."""
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/ping")
+        async def ping():
+            return {"ok": True}
+
+        schema = app.openapi()
+        get_op = schema["paths"]["/ping"]["get"]
+        assert "422" not in get_op["responses"]
+        assert "200" in get_op["responses"]
+
+    def test_openapi_skips_non_dict_path_item_values(self):
+        """_patched_openapi ignores non-dict values in path items (e.g. path-level parameters)."""
+        from fastapi_toolsets.exceptions.handler import _patched_openapi
+
+        app = FastAPI()
+
+        def fake_openapi() -> dict:
+            return {
+                "paths": {
+                    "/items": {
+                        "parameters": [
+                            {"name": "q", "in": "query"}
+                        ],  # list, not a dict
+                        "get": {"responses": {"200": {"description": "OK"}}},
+                    }
+                }
+            }
+
+        schema = _patched_openapi(app, fake_openapi)
+        # The list value was skipped without error; the GET operation is intact
+        assert schema["paths"]["/items"]["parameters"] == [{"name": "q", "in": "query"}]
+        assert "422" not in schema["paths"]["/items"]["get"]["responses"]
 
 
 class TestExceptionIntegration:
@@ -352,12 +741,12 @@ class TestInvalidOrderFieldError:
         assert error.field == "unknown"
         assert error.valid_fields == ["name", "created_at"]
 
-    def test_message_contains_field_and_valid_fields(self):
-        """Exception message mentions the bad field and valid options."""
+    def test_description_contains_field_and_valid_fields(self):
+        """api_error.desc mentions the bad field and valid options."""
         error = InvalidOrderFieldError("bad_field", ["name", "email"])
-        assert "bad_field" in str(error)
-        assert "name" in str(error)
-        assert "email" in str(error)
+        assert "bad_field" in error.api_error.desc
+        assert "name" in error.api_error.desc
+        assert "email" in error.api_error.desc
 
     def test_handled_as_422_by_exception_handler(self):
         """init_exceptions_handlers turns InvalidOrderFieldError into a 422 response."""

tests/test_models.py

@@ -0,0 +1,247 @@
+"""Tests for fastapi_toolsets.models mixins."""
+
+import uuid
+
+import pytest
+from sqlalchemy import String
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from fastapi_toolsets.models import (
+    CreatedAtMixin,
+    TimestampMixin,
+    UUIDMixin,
+    UpdatedAtMixin,
+)
+
+from .conftest import DATABASE_URL
+
+
+class MixinBase(DeclarativeBase):
+    pass
+
+
+class UUIDModel(MixinBase, UUIDMixin):
+    __tablename__ = "mixin_uuid_models"
+
+    name: Mapped[str] = mapped_column(String(50))
+
+
+class UpdatedAtModel(MixinBase, UpdatedAtMixin):
+    __tablename__ = "mixin_updated_at_models"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(String(50))
+
+
+class CreatedAtModel(MixinBase, CreatedAtMixin):
+    __tablename__ = "mixin_created_at_models"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(String(50))
+
+
+class TimestampModel(MixinBase, TimestampMixin):
+    __tablename__ = "mixin_timestamp_models"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(String(50))
+
+
+class FullMixinModel(MixinBase, UUIDMixin, UpdatedAtMixin):
+    __tablename__ = "mixin_full_models"
+
+    name: Mapped[str] = mapped_column(String(50))
+
+
+@pytest.fixture(scope="function")
+async def mixin_session():
+    engine = create_async_engine(DATABASE_URL, echo=False)
+    async with engine.begin() as conn:
+        await conn.run_sync(MixinBase.metadata.create_all)
+
+    session_factory = async_sessionmaker(engine, expire_on_commit=False)
+    session = session_factory()
+
+    try:
+        yield session
+    finally:
+        await session.close()
+        async with engine.begin() as conn:
+            await conn.run_sync(MixinBase.metadata.drop_all)
+        await engine.dispose()
+
+
+class TestUUIDMixin:
+    @pytest.mark.anyio
+    async def test_uuid_generated_by_db(self, mixin_session):
+        """UUID is generated server-side and populated after flush."""
+        obj = UUIDModel(name="test")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+
+        assert obj.id is not None
+        assert isinstance(obj.id, uuid.UUID)
+
+    @pytest.mark.anyio
+    async def test_uuid_is_primary_key(self):
+        """UUIDMixin adds id as primary key column."""
+        pk_cols = [c.name for c in UUIDModel.__table__.primary_key]
+        assert pk_cols == ["id"]
+
+    @pytest.mark.anyio
+    async def test_each_row_gets_unique_uuid(self, mixin_session):
+        """Each inserted row gets a distinct UUID."""
+        a = UUIDModel(name="a")
+        b = UUIDModel(name="b")
+        mixin_session.add_all([a, b])
+        await mixin_session.flush()
+
+        assert a.id != b.id
+
+    @pytest.mark.anyio
+    async def test_uuid_server_default_set(self):
+        """Column has gen_random_uuid() as server default."""
+        col = UUIDModel.__table__.c["id"]
+        assert col.server_default is not None
+        assert "gen_random_uuid" in str(col.server_default.arg)
+
+
+class TestUpdatedAtMixin:
+    @pytest.mark.anyio
+    async def test_updated_at_set_on_insert(self, mixin_session):
+        """updated_at is populated after insert."""
+        obj = UpdatedAtModel(name="initial")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert obj.updated_at is not None
+        assert obj.updated_at.tzinfo is not None  # timezone-aware
+
+    @pytest.mark.anyio
+    async def test_updated_at_changes_on_update(self, mixin_session):
+        """updated_at is updated when the row is modified."""
+        obj = UpdatedAtModel(name="initial")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        original_ts = obj.updated_at
+
+        obj.name = "modified"
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert obj.updated_at >= original_ts
+
+    @pytest.mark.anyio
+    async def test_updated_at_column_is_not_nullable(self):
+        """updated_at column is non-nullable."""
+        col = UpdatedAtModel.__table__.c["updated_at"]
+        assert not col.nullable
+
+    @pytest.mark.anyio
+    async def test_updated_at_has_server_default(self):
+        """updated_at column has a server-side default."""
+        col = UpdatedAtModel.__table__.c["updated_at"]
+        assert col.server_default is not None
+
+    @pytest.mark.anyio
+    async def test_updated_at_has_onupdate(self):
+        """updated_at column has an onupdate clause."""
+        col = UpdatedAtModel.__table__.c["updated_at"]
+        assert col.onupdate is not None
+
+
+class TestCreatedAtMixin:
+    @pytest.mark.anyio
+    async def test_created_at_set_on_insert(self, mixin_session):
+        """created_at is populated after insert."""
+        obj = CreatedAtModel(name="new")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert obj.created_at is not None
+        assert obj.created_at.tzinfo is not None  # timezone-aware
+
+    @pytest.mark.anyio
+    async def test_created_at_not_changed_on_update(self, mixin_session):
+        """created_at is not modified when the row is updated."""
+        obj = CreatedAtModel(name="original")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        original_ts = obj.created_at
+
+        obj.name = "updated"
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert obj.created_at == original_ts
+
+    @pytest.mark.anyio
+    async def test_created_at_column_is_not_nullable(self):
+        """created_at column is non-nullable."""
+        col = CreatedAtModel.__table__.c["created_at"]
+        assert not col.nullable
+
+    @pytest.mark.anyio
+    async def test_created_at_has_no_onupdate(self):
+        """created_at column has no onupdate clause."""
+        col = CreatedAtModel.__table__.c["created_at"]
+        assert col.onupdate is None
+
+
+class TestTimestampMixin:
+    @pytest.mark.anyio
+    async def test_both_columns_set_on_insert(self, mixin_session):
+        """created_at and updated_at are both populated after insert."""
+        obj = TimestampModel(name="new")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert obj.created_at is not None
+        assert obj.updated_at is not None
+
+    @pytest.mark.anyio
+    async def test_created_at_stable_updated_at_changes_on_update(self, mixin_session):
+        """On update: created_at stays the same, updated_at advances."""
+        obj = TimestampModel(name="original")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        original_created = obj.created_at
+        original_updated = obj.updated_at
+
+        obj.name = "modified"
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert obj.created_at == original_created
+        assert obj.updated_at >= original_updated
+
+    @pytest.mark.anyio
+    async def test_timestamp_mixin_has_both_columns(self):
+        """TimestampModel exposes both created_at and updated_at columns."""
+        col_names = {c.name for c in TimestampModel.__table__.columns}
+        assert "created_at" in col_names
+        assert "updated_at" in col_names
+
+
+class TestFullMixinModel:
+    @pytest.mark.anyio
+    async def test_combined_mixins_work_together(self, mixin_session):
+        """UUIDMixin and UpdatedAtMixin can be combined on the same model."""
+        obj = FullMixinModel(name="combined")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert isinstance(obj.id, uuid.UUID)
+        assert obj.updated_at is not None
+        assert obj.updated_at.tzinfo is not None

tests/test_security.py

@@ -0,0 +1,902 @@
+"""Tests for fastapi_toolsets.security."""
+
+import pytest
+from fastapi import FastAPI, Security
+from fastapi.testclient import TestClient
+
+from fastapi_toolsets.exceptions import UnauthorizedError, init_exceptions_handlers
+from fastapi_toolsets.security import (
+    AuthSource,
+    BearerTokenAuth,
+    CookieAuth,
+    MultiAuth,
+    OAuth2Auth,
+    OpenIDAuth,
+)
+
+
+def _app(*routes_setup_fns):
+    """Build a minimal FastAPI test app with exception handlers."""
+    app = FastAPI()
+    init_exceptions_handlers(app)
+    for fn in routes_setup_fns:
+        fn(app)
+    return app
+
+
+VALID_TOKEN = "secret"
+VALID_COOKIE = "session123"
+
+
+async def simple_validator(credential: str) -> dict:
+    if credential != VALID_TOKEN:
+        raise UnauthorizedError()
+    return {"user": "alice"}
+
+
+async def role_validator(credential: str, *, role: str) -> dict:
+    if credential != VALID_TOKEN:
+        raise UnauthorizedError()
+    return {"user": "alice", "role": role}
+
+
+async def cookie_validator(value: str) -> dict:
+    if value != VALID_COOKIE:
+        raise UnauthorizedError()
+    return {"session": value}
+
+
+class TestBearerTokenAuth:
+    def test_valid_token_returns_identity(self):
+        bearer = BearerTokenAuth(simple_validator)
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(bearer)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me", headers={"Authorization": f"Bearer {VALID_TOKEN}"})
+        assert response.status_code == 200
+        assert response.json() == {"user": "alice"}
+
+    def test_missing_header_returns_401(self):
+        bearer = BearerTokenAuth(simple_validator)
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(bearer)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me")
+        assert response.status_code == 401
+
+    def test_invalid_token_returns_401(self):
+        bearer = BearerTokenAuth(simple_validator)
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(bearer)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me", headers={"Authorization": "Bearer wrong"})
+        assert response.status_code == 401
+
+    def test_kwargs_forwarded_to_validator(self):
+        bearer = BearerTokenAuth(role_validator, role="admin")
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(bearer)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me", headers={"Authorization": f"Bearer {VALID_TOKEN}"})
+        assert response.status_code == 200
+        assert response.json() == {"user": "alice", "role": "admin"}
+
+    def test_prefix_matching_passes_full_token(self):
+        """Token with matching prefix: full token (with prefix) is passed to validator."""
+        received: list[str] = []
+
+        async def capturing_validator(credential: str) -> dict:
+            received.append(credential)
+            return {"user": "alice"}
+
+        bearer = BearerTokenAuth(capturing_validator, prefix="user_")
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(bearer)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me", headers={"Authorization": "Bearer user_abc123"})
+        assert response.status_code == 200
+        # Prefix is kept — validator receives the full token as stored in DB
+        assert received == ["user_abc123"]
+
+    def test_prefix_mismatch_returns_401(self):
+        bearer = BearerTokenAuth(simple_validator, prefix="user_")
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(bearer)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me", headers={"Authorization": "Bearer org_abc123"})
+        assert response.status_code == 401
+
+    # --- extract() ---
+
+    @pytest.mark.anyio
+    async def test_extract_no_header(self):
+        from starlette.requests import Request
+
+        bearer = BearerTokenAuth(simple_validator)
+        scope = {"type": "http", "method": "GET", "path": "/", "headers": []}
+        request = Request(scope)
+        assert await bearer.extract(request) is None
+
+    @pytest.mark.anyio
+    async def test_extract_empty_token(self):
+        from starlette.requests import Request
+
+        bearer = BearerTokenAuth(simple_validator)
+        scope = {
+            "type": "http",
+            "method": "GET",
+            "path": "/",
+            "headers": [(b"authorization", b"Bearer ")],
+        }
+        request = Request(scope)
+        assert await bearer.extract(request) is None
+
+    @pytest.mark.anyio
+    async def test_extract_no_prefix(self):
+        from starlette.requests import Request
+
+        bearer = BearerTokenAuth(simple_validator)
+        scope = {
+            "type": "http",
+            "method": "GET",
+            "path": "/",
+            "headers": [(b"authorization", b"Bearer mytoken")],
+        }
+        request = Request(scope)
+        assert await bearer.extract(request) == "mytoken"
+
+    @pytest.mark.anyio
+    async def test_extract_prefix_match(self):
+        from starlette.requests import Request
+
+        bearer = BearerTokenAuth(simple_validator, prefix="user_")
+        scope = {
+            "type": "http",
+            "method": "GET",
+            "path": "/",
+            "headers": [(b"authorization", b"Bearer user_abc")],
+        }
+        request = Request(scope)
+        assert await bearer.extract(request) == "user_abc"
+
+    @pytest.mark.anyio
+    async def test_extract_prefix_no_match(self):
+        from starlette.requests import Request
+
+        bearer = BearerTokenAuth(simple_validator, prefix="user_")
+        scope = {
+            "type": "http",
+            "method": "GET",
+            "path": "/",
+            "headers": [(b"authorization", b"Bearer org_abc")],
+        }
+        request = Request(scope)
+        assert await bearer.extract(request) is None
+
+    # --- generate_token() ---
+
+    def test_generate_token_no_prefix(self):
+        bearer = BearerTokenAuth(simple_validator)
+        token = bearer.generate_token()
+        assert isinstance(token, str)
+        assert len(token) > 0
+
+    def test_generate_token_with_prefix(self):
+        bearer = BearerTokenAuth(simple_validator, prefix="user_")
+        token = bearer.generate_token()
+        assert token.startswith("user_")
+
+    def test_generate_token_uniqueness(self):
+        bearer = BearerTokenAuth(simple_validator)
+        assert bearer.generate_token() != bearer.generate_token()
+
+    def test_generate_token_is_valid_credential(self):
+        """A generated token (with prefix) is accepted by the same auth source."""
+        stored: list[str] = []
+
+        async def storing_validator(credential: str) -> dict:
+            stored.append(credential)
+            return {"token": credential}
+
+        bearer = BearerTokenAuth(storing_validator, prefix="user_")
+        token = bearer.generate_token()
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(bearer)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me", headers={"Authorization": f"Bearer {token}"})
+        assert response.status_code == 200
+        assert stored == [token]
+
+
+class TestCookieAuth:
+    def test_valid_cookie_returns_identity(self):
+        cookie_auth = CookieAuth("session", cookie_validator)
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(cookie_auth)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me", cookies={"session": VALID_COOKIE})
+        assert response.status_code == 200
+        assert response.json() == {"session": VALID_COOKIE}
+
+    def test_missing_cookie_returns_401(self):
+        cookie_auth = CookieAuth("session", cookie_validator)
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(cookie_auth)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me")
+        assert response.status_code == 401
+
+    def test_invalid_cookie_returns_401(self):
+        cookie_auth = CookieAuth("session", cookie_validator)
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(cookie_auth)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me", cookies={"session": "wrong"})
+        assert response.status_code == 401
+
+    def test_kwargs_forwarded_to_validator(self):
+        async def session_validator(value: str, *, scope: str) -> dict:
+            if value != VALID_COOKIE:
+                raise UnauthorizedError()
+            return {"session": value, "scope": scope}
+
+        cookie_auth = CookieAuth("session", session_validator, scope="read")
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(cookie_auth)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me", cookies={"session": VALID_COOKIE})
+        assert response.status_code == 200
+        assert response.json() == {"session": VALID_COOKIE, "scope": "read"}
+
+    @pytest.mark.anyio
+    async def test_extract_no_cookie(self):
+        from starlette.requests import Request
+
+        auth = CookieAuth("session", cookie_validator)
+        scope = {"type": "http", "method": "GET", "path": "/", "headers": []}
+        request = Request(scope)
+        assert await auth.extract(request) is None
+
+    @pytest.mark.anyio
+    async def test_extract_cookie_present(self):
+        from starlette.requests import Request
+
+        auth = CookieAuth("session", cookie_validator)
+        scope = {
+            "type": "http",
+            "method": "GET",
+            "path": "/",
+            "headers": [(b"cookie", b"session=abc")],
+        }
+        request = Request(scope)
+        assert await auth.extract(request) == "abc"
+
+
+class TestOAuth2Auth:
+    def test_valid_token_returns_identity(self):
+        oauth = OAuth2Auth(token_url="/token", validator=simple_validator)
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(oauth)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me", headers={"Authorization": f"Bearer {VALID_TOKEN}"})
+        assert response.status_code == 200
+        assert response.json() == {"user": "alice"}
+
+    def test_missing_token_returns_401(self):
+        oauth = OAuth2Auth(token_url="/token", validator=simple_validator)
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(oauth)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me")
+        assert response.status_code == 401
+
+    @pytest.mark.anyio
+    async def test_extract_no_header(self):
+        from starlette.requests import Request
+
+        auth = OAuth2Auth("/token", simple_validator)
+        scope = {"type": "http", "method": "GET", "path": "/", "headers": []}
+        request = Request(scope)
+        assert await auth.extract(request) is None
+
+    @pytest.mark.anyio
+    async def test_extract_empty_token(self):
+        from starlette.requests import Request
+
+        auth = OAuth2Auth("/token", simple_validator)
+        scope = {
+            "type": "http",
+            "method": "GET",
+            "path": "/",
+            "headers": [(b"authorization", b"Bearer ")],
+        }
+        request = Request(scope)
+        assert await auth.extract(request) is None
+
+    @pytest.mark.anyio
+    async def test_extract_token(self):
+        from starlette.requests import Request
+
+        auth = OAuth2Auth("/token", simple_validator)
+        scope = {
+            "type": "http",
+            "method": "GET",
+            "path": "/",
+            "headers": [(b"authorization", b"Bearer mytoken")],
+        }
+        request = Request(scope)
+        assert await auth.extract(request) == "mytoken"
+
+    def test_in_multi_auth(self):
+        """OAuth2Auth.authenticate() is exercised when used inside MultiAuth."""
+        oauth = OAuth2Auth(token_url="/token", validator=simple_validator)
+        multi = MultiAuth(oauth)
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(multi)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me", headers={"Authorization": f"Bearer {VALID_TOKEN}"})
+        assert response.status_code == 200
+        assert response.json() == {"user": "alice"}
+
+
+class TestMultiAuth:
+    def test_first_source_matches(self):
+        bearer = BearerTokenAuth(simple_validator)
+        cookie = CookieAuth("session", cookie_validator)
+        multi = MultiAuth(bearer, cookie)
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(multi)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me", headers={"Authorization": f"Bearer {VALID_TOKEN}"})
+        assert response.status_code == 200
+        assert response.json() == {"user": "alice"}
+
+    def test_second_source_matches_when_first_absent(self):
+        bearer = BearerTokenAuth(simple_validator)
+        cookie = CookieAuth("session", cookie_validator)
+        multi = MultiAuth(bearer, cookie)
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(multi)):
+                return user
+
+        client = TestClient(_app(setup))
+        # No Authorization header — falls through to cookie
+        response = client.get("/me", cookies={"session": VALID_COOKIE})
+        assert response.status_code == 200
+        assert response.json() == {"session": VALID_COOKIE}
+
+    def test_no_source_matches_returns_401(self):
+        bearer = BearerTokenAuth(simple_validator)
+        cookie = CookieAuth("session", cookie_validator)
+        multi = MultiAuth(bearer, cookie)
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(multi)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me")
+        assert response.status_code == 401
+
+    def test_invalid_credential_does_not_fallthrough(self):
+        """If a credential is found but invalid, the next source is NOT tried."""
+        second_called: list[bool] = []
+
+        async def tracking_validator(credential: str) -> dict:
+            second_called.append(True)
+            return {"from": "second"}
+
+        bearer = BearerTokenAuth(simple_validator)  # raises on wrong token
+        cookie = CookieAuth("session", tracking_validator)
+        multi = MultiAuth(bearer, cookie)
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(multi)):
+                return user
+
+        client = TestClient(_app(setup))
+        # Bearer credential present but wrong — should NOT try cookie
+        response = client.get(
+            "/me",
+            headers={"Authorization": "Bearer wrong"},
+            cookies={"session": VALID_COOKIE},
+        )
+        assert response.status_code == 401
+        assert second_called == []  # cookie validator was never called
+
+    def test_prefix_routes_to_correct_source(self):
+        """Prefix-based dispatch: only the matching source's validator is called."""
+        user_calls: list[str] = []
+        org_calls: list[str] = []
+
+        async def user_validator(credential: str) -> dict:
+            user_calls.append(credential)
+            return {"type": "user", "id": credential}
+
+        async def org_validator(credential: str) -> dict:
+            org_calls.append(credential)
+            return {"type": "org", "id": credential}
+
+        user_bearer = BearerTokenAuth(user_validator, prefix="user_")
+        org_bearer = BearerTokenAuth(org_validator, prefix="org_")
+        multi = MultiAuth(user_bearer, org_bearer)
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(multi)):
+                return user
+
+        client = TestClient(_app(setup))
+
+        response = client.get("/me", headers={"Authorization": "Bearer user_alice"})
+        assert response.status_code == 200
+        assert response.json() == {"type": "user", "id": "user_alice"}
+        assert user_calls == ["user_alice"]
+        assert org_calls == []
+
+        user_calls.clear()
+
+        response = client.get("/me", headers={"Authorization": "Bearer org_acme"})
+        assert response.status_code == 200
+        assert response.json() == {"type": "org", "id": "org_acme"}
+        assert user_calls == []
+        assert org_calls == ["org_acme"]
+
+    def test_require_returns_new_multi_auth(self):
+        from fastapi_toolsets.security.multi import MultiAuth as MultiAuthClass
+
+        bearer = BearerTokenAuth(role_validator)
+        multi = MultiAuth(bearer)
+        derived = multi.require(role="admin")
+        assert isinstance(derived, MultiAuthClass)
+        assert derived is not multi
+
+    def test_require_forwards_kwargs_to_sources(self):
+        """multi.require() propagates to all sources that support it."""
+        bearer = BearerTokenAuth(role_validator)
+        multi = MultiAuth(bearer)
+
+        def setup(app: FastAPI):
+            @app.get("/admin")
+            async def admin(user=Security(multi.require(role="admin"))):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get(
+            "/admin", headers={"Authorization": f"Bearer {VALID_TOKEN}"}
+        )
+        assert response.status_code == 200
+        assert response.json() == {"user": "alice", "role": "admin"}
+
+    def test_require_skips_sources_without_require(self):
+        """Sources without require() are passed through unchanged."""
+        header_auth = _HeaderAuth(secret="s3cr3t")
+        multi = MultiAuth(header_auth)
+        derived = multi.require(role="admin")
+        assert derived._sources[0] is header_auth
+
+    def test_require_does_not_mutate_original(self):
+        bearer = BearerTokenAuth(role_validator, role="user")
+        multi = MultiAuth(bearer)
+        multi.require(role="admin")
+        assert bearer._kwargs == {"role": "user"}
+
+    def test_require_mixed_sources(self):
+        """require() applies to sources with require(), skips those without."""
+        from typing import cast
+
+        bearer = BearerTokenAuth(role_validator)
+        header_auth = _HeaderAuth(secret="s3cr3t")
+        multi = MultiAuth(bearer, header_auth)
+        derived = multi.require(role="admin")
+        # bearer got require() applied, header_auth passed through
+        assert cast(BearerTokenAuth, derived._sources[0])._kwargs == {"role": "admin"}
+        assert derived._sources[1] is header_auth
+
+
+class TestRequire:
+    def test_bearer_require_forwards_kwargs(self):
+        """require() creates a new instance that passes merged kwargs to validator."""
+        bearer = BearerTokenAuth(role_validator)
+
+        def setup(app: FastAPI):
+            @app.get("/admin")
+            async def admin(user=Security(bearer.require(role="admin"))):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get(
+            "/admin", headers={"Authorization": f"Bearer {VALID_TOKEN}"}
+        )
+        assert response.status_code == 200
+        assert response.json() == {"user": "alice", "role": "admin"}
+
+    def test_bearer_require_overrides_existing_kwarg(self):
+        """require() kwargs override kwargs set at instantiation."""
+        bearer = BearerTokenAuth(role_validator, role="user")
+
+        def setup(app: FastAPI):
+            @app.get("/admin")
+            async def admin(user=Security(bearer.require(role="admin"))):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get(
+            "/admin", headers={"Authorization": f"Bearer {VALID_TOKEN}"}
+        )
+        assert response.status_code == 200
+        assert response.json()["role"] == "admin"
+
+    def test_bearer_require_preserves_prefix(self):
+        """require() keeps the prefix of the original instance."""
+        bearer = BearerTokenAuth(role_validator, prefix="user_")
+        derived = bearer.require(role="admin")
+        assert derived._prefix == "user_"
+
+    def test_bearer_require_does_not_mutate_original(self):
+        """require() returns a new instance — original kwargs are unchanged."""
+        bearer = BearerTokenAuth(role_validator, role="user")
+        bearer.require(role="admin")
+        assert bearer._kwargs == {"role": "user"}
+
+    def test_cookie_require_forwards_kwargs(self):
+        async def scoped_validator(value: str, *, scope: str) -> dict:
+            if value != VALID_COOKIE:
+                raise UnauthorizedError()
+            return {"session": value, "scope": scope}
+
+        cookie = CookieAuth("session", scoped_validator)
+
+        def setup(app: FastAPI):
+            @app.get("/admin")
+            async def admin(user=Security(cookie.require(scope="admin"))):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/admin", cookies={"session": VALID_COOKIE})
+        assert response.status_code == 200
+        assert response.json() == {"session": VALID_COOKIE, "scope": "admin"}
+
+    def test_cookie_require_preserves_name(self):
+        cookie = CookieAuth("session", cookie_validator)
+        derived = cookie.require(scope="admin")
+        assert derived._name == "session"
+
+    def test_oauth2_require_forwards_kwargs(self):
+        oauth = OAuth2Auth("/token", role_validator)
+
+        def setup(app: FastAPI):
+            @app.get("/admin")
+            async def admin(user=Security(oauth.require(role="admin"))):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get(
+            "/admin", headers={"Authorization": f"Bearer {VALID_TOKEN}"}
+        )
+        assert response.status_code == 200
+        assert response.json() == {"user": "alice", "role": "admin"}
+
+    def test_oauth2_require_preserves_token_url(self):
+        oauth = OAuth2Auth("/token", simple_validator)
+        derived = oauth.require(role="admin")
+        assert derived._token_url == "/token"
+
+    def test_bearer_require_in_multi_auth(self):
+        """require() instances work seamlessly inside MultiAuth."""
+        PREFIXED_TOKEN = f"user_{VALID_TOKEN}"
+
+        async def prefixed_role_validator(credential: str, *, role: str) -> dict:
+            if credential != PREFIXED_TOKEN:
+                raise UnauthorizedError()
+            return {"user": "alice", "role": role}
+
+        bearer = BearerTokenAuth(prefixed_role_validator, prefix="user_")
+        multi = MultiAuth(bearer.require(role="admin"))
+
+        def setup(app: FastAPI):
+            @app.get("/admin")
+            async def admin(user=Security(multi)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get(
+            "/admin", headers={"Authorization": f"Bearer {PREFIXED_TOKEN}"}
+        )
+        assert response.status_code == 200
+        assert response.json() == {"user": "alice", "role": "admin"}
+
+
+class TestOpenIDAuth:
+    DISCOVERY_URL = "https://accounts.example.com/.well-known/openid-configuration"
+
+    def test_valid_token_returns_identity(self):
+        oidc = OpenIDAuth(self.DISCOVERY_URL, simple_validator)
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(oidc)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me", headers={"Authorization": f"Bearer {VALID_TOKEN}"})
+        assert response.status_code == 200
+        assert response.json() == {"user": "alice"}
+
+    def test_missing_token_returns_401(self):
+        oidc = OpenIDAuth(self.DISCOVERY_URL, simple_validator)
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(oidc)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me")
+        assert response.status_code == 401
+
+    def test_invalid_token_returns_401(self):
+        oidc = OpenIDAuth(self.DISCOVERY_URL, simple_validator)
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(oidc)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me", headers={"Authorization": "Bearer wrong"})
+        assert response.status_code == 401
+
+    def test_kwargs_forwarded_to_validator(self):
+        oidc = OpenIDAuth(self.DISCOVERY_URL, role_validator, role="admin")
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(oidc)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me", headers={"Authorization": f"Bearer {VALID_TOKEN}"})
+        assert response.status_code == 200
+        assert response.json() == {"user": "alice", "role": "admin"}
+
+    def test_require_forwards_kwargs(self):
+        oidc = OpenIDAuth(self.DISCOVERY_URL, role_validator)
+
+        def setup(app: FastAPI):
+            @app.get("/admin")
+            async def admin(user=Security(oidc.require(role="admin"))):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get(
+            "/admin", headers={"Authorization": f"Bearer {VALID_TOKEN}"}
+        )
+        assert response.status_code == 200
+        assert response.json() == {"user": "alice", "role": "admin"}
+
+    def test_require_preserves_discovery_url(self):
+        oidc = OpenIDAuth(self.DISCOVERY_URL, simple_validator)
+        derived = oidc.require(role="admin")
+        assert derived._openid_connect_url == self.DISCOVERY_URL
+
+    def test_require_does_not_mutate_original(self):
+        oidc = OpenIDAuth(self.DISCOVERY_URL, role_validator, role="user")
+        oidc.require(role="admin")
+        assert oidc._kwargs == {"role": "user"}
+
+    def test_is_auth_source(self):
+        oidc = OpenIDAuth(self.DISCOVERY_URL, simple_validator)
+        assert isinstance(oidc, AuthSource)
+
+    def test_in_multi_auth(self):
+        """OpenIDAuth works seamlessly inside MultiAuth."""
+        oidc = OpenIDAuth(self.DISCOVERY_URL, simple_validator)
+        multi = MultiAuth(oidc)
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(multi)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me", headers={"Authorization": f"Bearer {VALID_TOKEN}"})
+        assert response.status_code == 200
+        assert response.json() == {"user": "alice"}
+
+    @pytest.mark.anyio
+    async def test_extract_no_header(self):
+        from starlette.requests import Request
+
+        oidc = OpenIDAuth(self.DISCOVERY_URL, simple_validator)
+        scope = {"type": "http", "method": "GET", "path": "/", "headers": []}
+        request = Request(scope)
+        assert await oidc.extract(request) is None
+
+    @pytest.mark.anyio
+    async def test_extract_empty_token(self):
+        from starlette.requests import Request
+
+        oidc = OpenIDAuth(self.DISCOVERY_URL, simple_validator)
+        scope = {
+            "type": "http",
+            "method": "GET",
+            "path": "/",
+            "headers": [(b"authorization", b"Bearer ")],
+        }
+        request = Request(scope)
+        assert await oidc.extract(request) is None
+
+    @pytest.mark.anyio
+    async def test_extract_token(self):
+        from starlette.requests import Request
+
+        oidc = OpenIDAuth(self.DISCOVERY_URL, simple_validator)
+        scope = {
+            "type": "http",
+            "method": "GET",
+            "path": "/",
+            "headers": [(b"authorization", b"Bearer mytoken")],
+        }
+        request = Request(scope)
+        assert await oidc.extract(request) == "mytoken"
+
+
+# Minimal concrete subclass used only in tests below.
+class _HeaderAuth(AuthSource):
+    """Reads a custom X-Token header — no FastAPI security scheme."""
+
+    def __init__(self, secret: str) -> None:
+        super().__init__()
+        self._secret = secret
+
+    async def extract(self, request) -> str | None:
+        return request.headers.get("X-Token") or None
+
+    async def authenticate(self, credential: str) -> dict:
+        if credential != self._secret:
+            raise UnauthorizedError()
+        return {"token": credential}
+
+
+class TestAuthSource:
+    def test_cannot_instantiate_abstract_class(self):
+        with pytest.raises(TypeError):
+            AuthSource()
+
+    def test_builtin_classes_are_auth_sources(self):
+        bearer = BearerTokenAuth(simple_validator)
+        cookie = CookieAuth("session", cookie_validator)
+        oauth = OAuth2Auth("/token", simple_validator)
+        oidc = OpenIDAuth(
+            "https://example.com/.well-known/openid-configuration", simple_validator
+        )
+        assert isinstance(bearer, AuthSource)
+        assert isinstance(cookie, AuthSource)
+        assert isinstance(oauth, AuthSource)
+        assert isinstance(oidc, AuthSource)
+
+    def test_custom_source_standalone_valid(self):
+        """Default __call__ wires extract + authenticate via Request injection."""
+        auth = _HeaderAuth(secret="s3cr3t")
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(auth)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me", headers={"X-Token": "s3cr3t"})
+        assert response.status_code == 200
+        assert response.json() == {"token": "s3cr3t"}
+
+    def test_custom_source_standalone_missing_credential(self):
+        auth = _HeaderAuth(secret="s3cr3t")
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(auth)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me")  # no X-Token header
+        assert response.status_code == 401
+
+    def test_custom_source_standalone_invalid_credential(self):
+        auth = _HeaderAuth(secret="s3cr3t")
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(auth)):
+                return user
+
+        client = TestClient(_app(setup))
+        response = client.get("/me", headers={"X-Token": "wrong"})
+        assert response.status_code == 401
+
+    def test_custom_source_in_multi_auth(self):
+        """Custom AuthSource works transparently inside MultiAuth."""
+        header_auth = _HeaderAuth(secret="s3cr3t")
+        bearer = BearerTokenAuth(simple_validator)
+        multi = MultiAuth(bearer, header_auth)
+
+        def setup(app: FastAPI):
+            @app.get("/me")
+            async def me(user=Security(multi)):
+                return user
+
+        client = TestClient(_app(setup))
+
+        # Bearer matches first
+        response = client.get("/me", headers={"Authorization": f"Bearer {VALID_TOKEN}"})
+        assert response.status_code == 200
+        assert response.json() == {"user": "alice"}
+
+        # No bearer → falls through to custom header source
+        response = client.get("/me", headers={"X-Token": "s3cr3t"})
+        assert response.status_code == 200
+        assert response.json() == {"token": "s3cr3t"}