fastapi-multiauth 0.7.0__tar.gz → 1.0.0__tar.gz

fastapi_multiauth-1.0.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: fastapi-multiauth
+Version: 1.0.0
+Summary: Composable authentication sources for FastAPI: bring your own validator, combine multiple schemes, correct OpenAPI by construction
+Keywords: fastapi,authentication,security,oauth,api-key,bearer,cookie
+Author: d3vyce
+Author-email: d3vyce <contact@d3vyce.fr>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Internet :: WWW/HTTP :: Session
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Dist: anyio>=3.7
+Requires-Dist: async-lru>=2.0
+Requires-Dist: fastapi>=0.123.0,!=0.137.0,!=0.137.1
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: itsdangerous>=2.1
+Requires-Dist: pyjwt[crypto]>=2.13.0 ; extra == 'jwt'
+Requires-Dist: httpx-oauth>=0.16 ; extra == 'oauth'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/d3vyce/fastapi-multiauth
+Project-URL: Documentation, https://fastapi-multiauth.d3vyce.fr/
+Project-URL: Repository, https://github.com/d3vyce/fastapi-multiauth
+Project-URL: Issues, https://github.com/d3vyce/fastapi-multiauth/issues
+Provides-Extra: jwt
+Provides-Extra: oauth
+Description-Content-Type: text/markdown
+
+# FastAPI MultiAuth
+
+Composable authentication sources for FastAPI: bring your own validator, combine multiple schemes with `MultiAuth`, and get correct OpenAPI documentation by construction.
+
+[![CI](https://github.com/d3vyce/fastapi-multiauth/actions/workflows/ci.yml/badge.svg)](https://github.com/d3vyce/fastapi-multiauth/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/d3vyce/fastapi-multiauth/graph/badge.svg)](https://codecov.io/gh/d3vyce/fastapi-multiauth)
+[![CodSpeed Badge](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/d3vyce/fastapi-multiauth?utm_source=badge)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+**Documentation**: [https://fastapi-multiauth.d3vyce.fr](https://fastapi-multiauth.d3vyce.fr)
+
+**Source Code**: [https://github.com/d3vyce/fastapi-multiauth](https://github.com/d3vyce/fastapi-multiauth)
+
+---
+
+You write the function that decides who a credential belongs to; the library extracts the credential, combines schemes, and declares them in OpenAPI. No user model, no database coupling, no ready-made login routes.
+
+## Installation
+
+```bash
+uv add fastapi-multiauth
+uv add "fastapi-multiauth[jwt]"    # JWTValidator, HTTPDPoPAuth
+uv add "fastapi-multiauth[oauth]"  # OAuth 2.0 / OIDC login helpers
+```
+
+## Quick start
+
+```python
+import os
+
+from fastapi import FastAPI, Security
+
+from fastapi_multiauth import (
+    APIKeyCookieAuth,
+    HTTPBearerAuth,
+    MultiAuth,
+    UnauthorizedError,
+    hash_token,
+)
+
+SECRET_KEY = os.environ["SECRET_KEY"]
+USERS = {"1": {"id": "1", "name": "alice"}}
+TOKENS = {hash_token("user_alice-token"): "1"}
+
+
+async def validate_token(token: str) -> dict:
+    user_id = TOKENS.get(hash_token(token))
+    if user_id is None:
+        raise UnauthorizedError()
+    return USERS[user_id]
+
+
+async def validate_session(user_id: str) -> dict:
+    if user_id not in USERS:
+        raise UnauthorizedError()
+    return USERS[user_id]
+
+
+bearer = HTTPBearerAuth(validator=validate_token, prefix="user_")
+session = APIKeyCookieAuth(
+    name="__Host-session", validator=validate_session, secret_key=SECRET_KEY
+)
+auth = MultiAuth(bearer, session)
+
+app = FastAPI()
+
+
+@app.get("/me")
+async def me(user: dict = Security(auth)):
+    return user
+```
+
+Set `SECRET_KEY` to at least 32 random bytes, for example the output of `python -c "import secrets; print(secrets.token_urlsafe(32))"`.
+
+## Features
+
+- **Every standard scheme**: bearer tokens with Stripe-style prefixes, signed cookie sessions, API keys, HTTP Basic, OAuth 2.0 and OpenID Connect.
+- **`MultiAuth`**: several schemes on one route, all documented in OpenAPI, plus `optional()` for routes that also serve anonymous callers.
+- **Stateless sessions**: HMAC-signed cookies with expiry, key rotation, opt-in revocable session ids, and `csrf=True` to refuse cross-origin requests.
+- **Tokens done right**: secure generation, hash-only storage, checksums, `JWTValidator` for provider JWTs (JWKS, rotation, `aud`/`iss`), `IntrospectionValidator` for opaque ones, and `HTTPDPoPAuth` for tokens bound to the client's key.
+- **Signed webhooks**: `HMACSignatureAuth` checks the sender's signature over the raw body, with timestamp tolerance and secret rotation.
+- **Scopes and step-up**: fail-closed scope checks, and `fresh()` / `stepped_up()` with RFC 9470 challenges for sensitive routes.
+- **Second factor**: TOTP helpers that refuse a replayed code, and the login level signed into the session cookie.
+- **OAuth login helpers**: discovery, CSRF `state`, PKCE, code exchange and ID token validation.
+- **Observable**: reason-coded security logs and `auth_surface(app)` to audit what guards every route.
+
+See the [comparison](https://fastapi-multiauth.d3vyce.fr/guide/comparison/) for how it sits next to `fastapi.security`, fastapi-users, AuthX and Authlib, and the [security model](https://fastapi-multiauth.d3vyce.fr/security-model/) for what it guarantees.
+
+## Contributing
+
+Contributions are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md). Report vulnerabilities privately, as the [security policy](SECURITY.md) describes.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

fastapi_multiauth-1.0.0/README.md

@@ -0,0 +1,101 @@
+# FastAPI MultiAuth
+
+Composable authentication sources for FastAPI: bring your own validator, combine multiple schemes with `MultiAuth`, and get correct OpenAPI documentation by construction.
+
+[![CI](https://github.com/d3vyce/fastapi-multiauth/actions/workflows/ci.yml/badge.svg)](https://github.com/d3vyce/fastapi-multiauth/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/d3vyce/fastapi-multiauth/graph/badge.svg)](https://codecov.io/gh/d3vyce/fastapi-multiauth)
+[![CodSpeed Badge](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/d3vyce/fastapi-multiauth?utm_source=badge)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+**Documentation**: [https://fastapi-multiauth.d3vyce.fr](https://fastapi-multiauth.d3vyce.fr)
+
+**Source Code**: [https://github.com/d3vyce/fastapi-multiauth](https://github.com/d3vyce/fastapi-multiauth)
+
+---
+
+You write the function that decides who a credential belongs to; the library extracts the credential, combines schemes, and declares them in OpenAPI. No user model, no database coupling, no ready-made login routes.
+
+## Installation
+
+```bash
+uv add fastapi-multiauth
+uv add "fastapi-multiauth[jwt]"    # JWTValidator, HTTPDPoPAuth
+uv add "fastapi-multiauth[oauth]"  # OAuth 2.0 / OIDC login helpers
+```
+
+## Quick start
+
+```python
+import os
+
+from fastapi import FastAPI, Security
+
+from fastapi_multiauth import (
+    APIKeyCookieAuth,
+    HTTPBearerAuth,
+    MultiAuth,
+    UnauthorizedError,
+    hash_token,
+)
+
+SECRET_KEY = os.environ["SECRET_KEY"]
+USERS = {"1": {"id": "1", "name": "alice"}}
+TOKENS = {hash_token("user_alice-token"): "1"}
+
+
+async def validate_token(token: str) -> dict:
+    user_id = TOKENS.get(hash_token(token))
+    if user_id is None:
+        raise UnauthorizedError()
+    return USERS[user_id]
+
+
+async def validate_session(user_id: str) -> dict:
+    if user_id not in USERS:
+        raise UnauthorizedError()
+    return USERS[user_id]
+
+
+bearer = HTTPBearerAuth(validator=validate_token, prefix="user_")
+session = APIKeyCookieAuth(
+    name="__Host-session", validator=validate_session, secret_key=SECRET_KEY
+)
+auth = MultiAuth(bearer, session)
+
+app = FastAPI()
+
+
+@app.get("/me")
+async def me(user: dict = Security(auth)):
+    return user
+```
+
+Set `SECRET_KEY` to at least 32 random bytes, for example the output of `python -c "import secrets; print(secrets.token_urlsafe(32))"`.
+
+## Features
+
+- **Every standard scheme**: bearer tokens with Stripe-style prefixes, signed cookie sessions, API keys, HTTP Basic, OAuth 2.0 and OpenID Connect.
+- **`MultiAuth`**: several schemes on one route, all documented in OpenAPI, plus `optional()` for routes that also serve anonymous callers.
+- **Stateless sessions**: HMAC-signed cookies with expiry, key rotation, opt-in revocable session ids, and `csrf=True` to refuse cross-origin requests.
+- **Tokens done right**: secure generation, hash-only storage, checksums, `JWTValidator` for provider JWTs (JWKS, rotation, `aud`/`iss`), `IntrospectionValidator` for opaque ones, and `HTTPDPoPAuth` for tokens bound to the client's key.
+- **Signed webhooks**: `HMACSignatureAuth` checks the sender's signature over the raw body, with timestamp tolerance and secret rotation.
+- **Scopes and step-up**: fail-closed scope checks, and `fresh()` / `stepped_up()` with RFC 9470 challenges for sensitive routes.
+- **Second factor**: TOTP helpers that refuse a replayed code, and the login level signed into the session cookie.
+- **OAuth login helpers**: discovery, CSRF `state`, PKCE, code exchange and ID token validation.
+- **Observable**: reason-coded security logs and `auth_surface(app)` to audit what guards every route.
+
+See the [comparison](https://fastapi-multiauth.d3vyce.fr/guide/comparison/) for how it sits next to `fastapi.security`, fastapi-users, AuthX and Authlib, and the [security model](https://fastapi-multiauth.d3vyce.fr/security-model/) for what it guarantees.
+
+## Contributing
+
+Contributions are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md). Report vulnerabilities privately, as the [security policy](SECURITY.md) describes.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

{fastapi_multiauth-0.7.0 → fastapi_multiauth-1.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-multiauth"
-version = "0.7.0"
+version = "1.0.0"
 description = "Composable authentication sources for FastAPI: bring your own validator, combine multiple schemes, correct OpenAPI by construction"
 readme = "README.md"
 license = "MIT"
@@ -16,7 +16,7 @@ keywords = [
     "cookie",
 ]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Framework :: AsyncIO",
     "Framework :: FastAPI",
     "Intended Audience :: Developers",
@@ -66,6 +66,8 @@ dev = [
 ]
 tests = [
     "coverage>=7.0.0",
+    "httpx2>=2.16",
+    "pyotp>=2.10.0",
     "pytest-anyio>=0.0.0",
     "pytest-codspeed>=5.0",
     "pytest-cov>=4.0.0",
@@ -74,33 +76,51 @@ tests = [
 ]
 docs = [
     "mkdocstrings-python>=2.0.2",
-    "zensical>=0.0.30",
+    "zensical>=0.0.71",
 ]
 
 [build-system]
 requires = ["uv_build>=0.11.21,<0.14.0"]
 build-backend = "uv_build"
 
+[tool.ruff]
+extend-exclude = ["docs"]
+
 [tool.ruff.lint]
 extend-select = [
+    "D",
     "S",
     "UP",
 ]
+ignore = [
+    "D105",
+    "D107",
+]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**" = [
+    "D",
     "S",
     "B008",
 ]
 "benchmarks/**" = [
+    "D",
+    "S",
+    "B008",
+]
+"docs_src/**" = [
+    "D",
     "S",
     "B008",
 ]
 
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+pythonpath = ["."]
 anyio_mode = "auto"
-filterwarnings = ["ignore::DeprecationWarning"]
 
 [tool.coverage.run]
 source = ["src/fastapi_multiauth"]

{fastapi_multiauth-0.7.0 → fastapi_multiauth-1.0.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-multiauth"
-version = "0.7.0"
+version = "1.0.0"
 description = "Composable authentication sources for FastAPI: bring your own validator, combine multiple schemes, correct OpenAPI by construction"
 readme = "README.md"
 license = "MIT"
@@ -11,7 +11,7 @@ authors = [
 ]
 keywords = ["fastapi", "authentication", "security", "oauth", "api-key", "bearer", "cookie"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Framework :: AsyncIO",
     "Framework :: FastAPI",
     "Intended Audience :: Developers",
@@ -61,6 +61,8 @@ dev = [
 ]
 tests = [
     "coverage>=7.0.0",
+    "httpx2>=2.16",
+    "pyotp>=2.10.0",
     "pytest-anyio>=0.0.0",
     "pytest-codspeed>=5.0",
     "pytest-cov>=4.0.0",
@@ -69,27 +71,33 @@ tests = [
 ]
 docs = [
     "mkdocstrings-python>=2.0.2",
-    "zensical>=0.0.30",
+    "zensical>=0.0.71",
 ]
 
 [build-system]
 requires = ["uv_build>=0.11.21,<0.14.0"]
 build-backend = "uv_build"
 
+[tool.ruff]
+extend-exclude = ["docs"]
+
 [tool.ruff.lint]
-# "S" = flake8-bandit security rules, scoped to the library source.
-extend-select = ["S", "UP"]
+# "D" = Google-style docstrings, "S" = flake8-bandit; both scoped to the library source.
+extend-select = ["D", "S", "UP"]
+ignore = ["D105", "D107"]
 
 [tool.ruff.lint.per-file-ignores]
-"tests/**" = ["S", "B008"]
-"benchmarks/**" = ["S", "B008"]
+"tests/**" = ["D", "S", "B008"]
+"benchmarks/**" = ["D", "S", "B008"]
+"docs_src/**" = ["D", "S", "B008"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+pythonpath = ["."]
 anyio_mode = "auto"
-filterwarnings = [
-    "ignore::DeprecationWarning",
-]
 
 [tool.coverage.run]
 source = ["src/fastapi_multiauth"]

fastapi_multiauth-1.0.0/src/fastapi_multiauth/__init__.py

@@ -0,0 +1,81 @@
+"""Composable authentication sources for FastAPI.
+
+The OAuth 2.0 / OpenID Connect login helpers live in the separate
+`fastapi_multiauth.oauth` namespace and need the `oauth` extra:
+
+```python
+from fastapi_multiauth.oauth import oauth_build_authorization_redirect
+```
+"""
+
+import logging
+
+from . import oauth
+from .abc import AuthSource
+from .amr import AuthenticationMethodReference
+from .exceptions import (
+    ForbiddenError,
+    InsufficientAuthenticationError,
+    StaleCredentialError,
+    UnauthorizedError,
+)
+from .introspection import IntrospectionValidator
+from .jwt import JWTValidator
+from .sources import (
+    APIKeyCookieAuth,
+    APIKeyHeaderAuth,
+    APIKeyQueryAuth,
+    HMACSignatureAuth,
+    HTTPBasicAuth,
+    HTTPBearerAuth,
+    HTTPDPoPAuth,
+    MultiAuth,
+    OAuth2AuthorizationCodeBearerAuth,
+    OAuth2PasswordBearerAuth,
+    OpenIdConnectAuth,
+)
+from .surface import RouteAuth, SchemeRequirement, auth_surface
+from .totp import totp_generate_secret, totp_provisioning_uri, totp_verify
+from .utils import (
+    checksum_token_generator,
+    hash_token,
+    verify_token_checksum,
+    verify_token_hash,
+)
+
+__version__ = "1.0.0"
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = [
+    "APIKeyCookieAuth",
+    "APIKeyHeaderAuth",
+    "APIKeyQueryAuth",
+    "AuthSource",
+    "AuthenticationMethodReference",
+    "ForbiddenError",
+    "HMACSignatureAuth",
+    "HTTPBasicAuth",
+    "HTTPBearerAuth",
+    "HTTPDPoPAuth",
+    "InsufficientAuthenticationError",
+    "IntrospectionValidator",
+    "JWTValidator",
+    "MultiAuth",
+    "OAuth2AuthorizationCodeBearerAuth",
+    "OAuth2PasswordBearerAuth",
+    "OpenIdConnectAuth",
+    "RouteAuth",
+    "SchemeRequirement",
+    "StaleCredentialError",
+    "UnauthorizedError",
+    "auth_surface",
+    "checksum_token_generator",
+    "hash_token",
+    "oauth",
+    "totp_generate_secret",
+    "totp_provisioning_uri",
+    "totp_verify",
+    "verify_token_checksum",
+    "verify_token_hash",
+]

{fastapi_multiauth-0.7.0 → fastapi_multiauth-1.0.0}/src/fastapi_multiauth/_http.py

@@ -1,7 +1,6 @@
 """Shared HTTP transport hygiene for the OAuth and JWT modules."""
 
 import contextlib
-import json
 from typing import Any
 from urllib.parse import urlsplit
 
@@ -14,7 +13,7 @@ DEFAULT_TIMEOUT = 10.0
 
 
 def _require_https(url: str, description: str) -> str:
-    """Reject non-string URLs and URLs that would send credentials over plaintext HTTP."""
+    """Reject a URL that is not a string, or would send credentials over HTTP."""
     if not isinstance(url, str):
         raise ValueError(f"{description} must be a string URL (got {url!r})")  # noqa: TRY004
     parsed = urlsplit(url)
@@ -25,26 +24,52 @@ def _require_https(url: str, description: str) -> str:
     raise ValueError(f"{description} must use https:// (got {url!r})")
 
 
-async def _get_json(
+async def _request_json(
+    method: str,
     url: str,
     *,
     timeout: float,
     error_cls: type[Exception],
     description: str,
     headers: dict[str, str] | None = None,
+    data: dict[str, str] | None = None,
     client: httpx.AsyncClient | None = None,
-) -> Any:
-    """GET *url* and decode the JSON body, mapping failures to *error_cls*."""
+) -> dict[str, Any]:
+    """Send a request and decode the JSON object body, mapping failures to `error_cls`."""
     async with (
         contextlib.nullcontext(client)
         if client is not None
         else httpx.AsyncClient(timeout=timeout)
     ) as http:
         try:
-            resp = await http.get(url, headers=headers)
+            resp = await http.request(method, url, headers=headers, data=data)
             resp.raise_for_status()
-            return resp.json()
+            body = resp.json()
         except httpx.HTTPError as exc:
             raise error_cls(f"failed to fetch {description}: {exc}") from exc
-        except json.JSONDecodeError as exc:
+        except ValueError as exc:
             raise error_cls(f"{description} is not valid JSON") from exc
+    if not isinstance(body, dict):
+        raise error_cls(f"{description} is not a JSON object")
+    return body
+
+
+async def _get_json(
+    url: str,
+    *,
+    timeout: float,
+    error_cls: type[Exception],
+    description: str,
+    headers: dict[str, str] | None = None,
+    client: httpx.AsyncClient | None = None,
+) -> dict[str, Any]:
+    """GET `url` and decode the JSON object body, mapping failures to `error_cls`."""
+    return await _request_json(
+        "GET",
+        url,
+        timeout=timeout,
+        error_cls=error_cls,
+        description=description,
+        headers=headers,
+        client=client,
+    )