fastapi-rtk 2.21.2__tar.gz → 2.22.0__tar.gz

{fastapi_rtk-2.21.2 → fastapi_rtk-2.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-rtk
-Version: 2.21.2
+Version: 2.22.0
 Summary: A package that provides a set of tools to build a FastAPI application with a Class-Based CRUD API.
 Project-URL: Homepage, https://codeberg.org/datatactics/fastapi-rtk
 Project-URL: Issues, https://codeberg.org/datatactics/fastapi-rtk/issues
@@ -50,6 +50,8 @@ Requires-Dist: pyinstrument>=5.1.2; extra == 'profiler'
 Provides-Extra: s3
 Requires-Dist: smart-open[s3]>=7.5.0; extra == 's3'
 Requires-Dist: urllib3>=2.7.0; extra == 's3'
+Provides-Extra: saml
+Requires-Dist: python3-saml>=1.16.0; extra == 'saml'
 Provides-Extra: test
 Requires-Dist: aiosqlite>=0.21.0; extra == 'test'
 Requires-Dist: pytest-asyncio>=1.3.0; extra == 'test'
@@ -351,6 +353,28 @@ A single adapter can also be swapped on the web `Provider` via `adapters={{ stor
 
 See the wiki page [React Native and Adapters](https://codeberg.org/datatactics/fastapi-rtk/wiki/06.04-React-Native-and-Adapters) for the full adapter reference (interfaces, per-adapter web/RN table, auth transports).
 
+## Signatures
+
+The wheel and sdist of every PyPI release and the tarball of every npm release are signed with [cosign](https://github.com/sigstore/cosign). These files and their signature bundles (`<file>.sigstore.json`) are attached to the [release on Codeberg](https://codeberg.org/datatactics/fastapi-rtk/releases). Verify a downloaded file against the public key in this repo ([`cosign.pub`](https://codeberg.org/datatactics/fastapi-rtk/src/branch/main/cosign.pub)):
+
+```sh
+pip download --no-deps fastapi-rtk==<version>
+cosign verify-blob --key cosign.pub \
+  --bundle fastapi_rtk-<version>-py3-none-any.whl.sigstore.json \
+  fastapi_rtk-<version>-py3-none-any.whl
+
+npm pack fastapi-rtk@<version>
+cosign verify-blob --key cosign.pub \
+  --bundle fastapi-rtk-<version>.tgz.sigstore.json \
+  fastapi-rtk-<version>.tgz
+```
+
+[`scripts/verify-release.sh`](https://codeberg.org/datatactics/fastapi-rtk/src/branch/main/scripts/verify-release.sh) runs that check for all three files of a release, downloading them from PyPI and npm and their bundles from the Codeberg release (needs `curl`, `jq` and `cosign`):
+
+```sh
+scripts/verify-release.sh <version>
+```
+
 ## License
 
 FastAPI-RTK is licensed under the [MIT license](https://codeberg.org/datatactics/fastapi-rtk/src/branch/main/LICENSE).

{fastapi_rtk-2.21.2 → fastapi_rtk-2.22.0}/README.md

@@ -292,6 +292,28 @@ A single adapter can also be swapped on the web `Provider` via `adapters={{ stor
 
 See the wiki page [React Native and Adapters](https://codeberg.org/datatactics/fastapi-rtk/wiki/06.04-React-Native-and-Adapters) for the full adapter reference (interfaces, per-adapter web/RN table, auth transports).
 
+## Signatures
+
+The wheel and sdist of every PyPI release and the tarball of every npm release are signed with [cosign](https://github.com/sigstore/cosign). These files and their signature bundles (`<file>.sigstore.json`) are attached to the [release on Codeberg](https://codeberg.org/datatactics/fastapi-rtk/releases). Verify a downloaded file against the public key in this repo ([`cosign.pub`](https://codeberg.org/datatactics/fastapi-rtk/src/branch/main/cosign.pub)):
+
+```sh
+pip download --no-deps fastapi-rtk==<version>
+cosign verify-blob --key cosign.pub \
+  --bundle fastapi_rtk-<version>-py3-none-any.whl.sigstore.json \
+  fastapi_rtk-<version>-py3-none-any.whl
+
+npm pack fastapi-rtk@<version>
+cosign verify-blob --key cosign.pub \
+  --bundle fastapi-rtk-<version>.tgz.sigstore.json \
+  fastapi-rtk-<version>.tgz
+```
+
+[`scripts/verify-release.sh`](https://codeberg.org/datatactics/fastapi-rtk/src/branch/main/scripts/verify-release.sh) runs that check for all three files of a release, downloading them from PyPI and npm and their bundles from the Codeberg release (needs `curl`, `jq` and `cosign`):
+
+```sh
+scripts/verify-release.sh <version>
+```
+
 ## License
 
 FastAPI-RTK is licensed under the [MIT license](https://codeberg.org/datatactics/fastapi-rtk/src/branch/main/LICENSE).

{fastapi_rtk-2.21.2 → fastapi_rtk-2.22.0}/fastapi_rtk/__init__.py

@@ -61,6 +61,9 @@ __all__ = [
     "BearerConfig",
     "CookieConfig",
     "StrategyConfig",
+    "SAMLClient",
+    "SAMLIdentity",
+    "SAMLResponseError",
     # .backends.generic
     "GenericPKAutoIncrement",
     "GenericUnset",
@@ -245,6 +248,7 @@ __all__ = [
     # .routers
     "get_auth_router",
     "get_oauth_router",
+    "get_saml_router",
     "get_oauth_associate_router",
     # .schemas
     "PRIMARY_KEY",

fastapi_rtk-2.22.0/fastapi_rtk/_version.py

@@ -0,0 +1 @@
+__version__ = "2.22.0"

{fastapi_rtk-2.21.2 → fastapi_rtk-2.22.0}/fastapi_rtk/agent_docs/guide/backend.md

@@ -714,6 +714,35 @@ The toolkit wires the login/callback routes; the frontend's OAuth sign-in hook k
 
 A `"backend": "jwt"` client (for clients without a browser cookie store, such as React Native; web apps default to `cookie` and can opt in) answers the callback with `{"access_token", "token_type": "bearer"}` JSON instead of a cookie, so the client has to make the callback request itself: point `redirect_url` (or `redirect_url_factory`) at the URL the app receives the redirect on (on React Native the same URL goes to `createReactNativeAdapters({ oauthRedirectUrl })`, and `oauthSignin` then completes the sign-in itself), or call `oauthCallback("<name>", redirectQuery)` from `useAuth()` with that URL's query string, which forwards `code` and `state` to `GET /api/v1/auth/oauth-authorized/<name>` and stores the returned token. A JWT client rejects `redirect_url_after_callback` with a `ValueError` at startup and a popup login (`?popup=true`) with 400 `OAUTH_POPUP_NOT_SUPPORTED`, since both would drop the token.
 
+Entry names must be unique across `OAUTH_CLIENTS`; a duplicate raises `ValueError` at startup.
+
+A SAML 2.0 IdP (Microsoft Entra ID, for example) is an ordinary entry whose `oauth_client` is a `SAMLClient` (`from fastapi_rtk import SAMLClient`, needs `pip install fastapi-rtk[saml]`). Give it `name`, `sp_entity_id`, and either `idp_metadata_url` or all of `idp_entity_id`, `idp_sso_url`, `idp_cert`; `account_id_attribute` / `email_attribute` name the assertion attributes to read (the NameID when `None`). The other entry keys keep their OAuth meaning: `redirect_url` is the ACS URL registered at the IdP, `backend` must be `cookie` (`jwt` raises `ValueError`, since the IdP posts to the browser), and the hooks receive `oauth_token={"attributes": {...}, "nameid": ..., "assertion_id": ...}`, so roles come from returning `role_keys`, e.g. the Entra groups claim. Routes: `GET /api/v1/auth/login/<name>` (popup supported, so `oauthSignin('<name>')` works unchanged) and the ACS `POST /api/v1/auth/oauth-authorized/<name>`, which answers 303 to `redirect_url_after_callback`. A failed validation is 400 `SAML_RESPONSE_INVALID`, a reused assertion 400 `SAML_ASSERTION_REPLAYED` (tracked in `g.cache` until the assertion expires). The default `InMemoryCacheStorage` is per process, so with several workers or replicas a replay that lands on another worker passes: such a deployment must set `CACHE` to a storage every worker shares (a custom `AbstractCacheStorage`, since the toolkit ships none). The check and the record are separate calls: the default in-memory storage never suspends between them, but with a storage whose `get` awaits a network round trip (Redis, say) two simultaneous posts of one assertion can both pass. IdP-initiated logins are rejected, and login CSRF is not prevented, as for OAuth.
+
+```python
+from fastapi_rtk import SAMLClient
+
+OAUTH_PROVIDERS = [
+    {
+        "oauth_client": SAMLClient(
+            name="entra",
+            sp_entity_id="my-app",
+            idp_entity_id="https://sts.windows.net/<tenant>/",
+            idp_sso_url="https://login.microsoftonline.com/<tenant>/saml2",
+            idp_cert="MIIC...",
+            account_id_attribute="http://schemas.microsoft.com/identity/claims/objectidentifier",
+            email_attribute="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
+        ),
+        "redirect_url": "https://<host>/api/v1/auth/oauth-authorized/entra",
+        "associate_by_email": True,
+        "on_before_login": lambda user, oauth_token: {
+            "role_keys": oauth_token["attributes"].get(
+                "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups", []
+            )
+        },
+    },
+]
+```
+
 ## 16. Migrations and user management CLI
 
 ```bash

{fastapi_rtk-2.21.2 → fastapi_rtk-2.22.0}/fastapi_rtk/auth/__init__.py

@@ -7,13 +7,17 @@ from .auth import (
     StrategyConfig,
 )
 from .password_helpers import FABPasswordHelper
+from .saml import SAMLClient, SAMLIdentity, SAMLResponseError
 
 __all__ = [
     "FABPasswordHelper",
-    "CookieConfig",
-    "BearerConfig",
-    "StrategyConfig",
-    "Auth",
     "Authenticator",
     "AuthConfigurator",
+    "Auth",
+    "BearerConfig",
+    "CookieConfig",
+    "StrategyConfig",
+    "SAMLClient",
+    "SAMLIdentity",
+    "SAMLResponseError",
 ]

fastapi_rtk-2.22.0/fastapi_rtk/auth/saml.py

@@ -0,0 +1,376 @@
+"""SAML 2.0 service provider client, registered as an `OAUTH_CLIENTS` entry."""
+
+import collections.abc
+import dataclasses
+import importlib
+import math
+import time
+import types
+import typing
+import urllib.parse
+
+from ..utils import smart_run
+
+if typing.TYPE_CHECKING:
+    import onelogin.saml2.settings
+
+__all__ = ["SAMLClient", "SAMLIdentity", "SAMLResponseError"]
+
+
+@dataclasses.dataclass
+class SAMLIdentity:
+    """
+    The identity read off a validated SAML response.
+    """
+
+    account_id: str
+    account_email: str | None
+    assertion_id: str
+    not_on_or_after: int | None
+    nameid: str
+    attributes: dict[str, list[str]]
+
+
+class SAMLResponseError(Exception):
+    """
+    A SAML response failed validation.
+    """
+
+    def __init__(self, errors: list[str], reason: str | None):
+        """
+        Create the error from python3-saml's error codes and reason.
+
+        Args:
+            errors: The python3-saml error codes.
+            reason: The python3-saml reason for the last error.
+        """
+        super().__init__(f"{', '.join(errors)}: {reason}")
+        self.errors = errors
+        self.reason = reason
+
+
+class SAMLClient:
+    """
+    A SAML 2.0 identity provider, used as the `oauth_client` of an `OAUTH_CLIENTS` entry.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        sp_entity_id: str,
+        idp_entity_id: str | None = None,
+        idp_sso_url: str | None = None,
+        idp_cert: str | None = None,
+        idp_metadata_url: str | None = None,
+        account_id_attribute: str | None = None,
+        email_attribute: str | None = None,
+    ):
+        """
+        Configure the client; IdP fields left None come from `idp_metadata_url`.
+
+        Args:
+            name: Provider name, the last path segment of the login and ACS routes.
+            sp_entity_id: Entity ID of this service provider at the IdP.
+            idp_entity_id: Entity ID (issuer) of the IdP.
+            idp_sso_url: HTTP-Redirect single sign-on URL of the IdP.
+            idp_cert: Base64 X.509 signing certificate of the IdP.
+            idp_metadata_url: IdP metadata URL, source of every IdP field left None.
+            account_id_attribute: Attribute holding the account id; the NameID when None.
+            email_attribute: Attribute holding the email; the NameID when None.
+
+        Raises:
+            ValueError: No metadata URL and one of the three IdP fields is missing.
+            ImportError: The `saml` extra is not installed.
+        """
+        if not idp_metadata_url and not (idp_entity_id and idp_sso_url and idp_cert):
+            raise ValueError(
+                f"SAML client {name!r} needs idp_metadata_url or all of "
+                "idp_entity_id, idp_sso_url and idp_cert"
+            )
+        self.name = name
+        self.sp_entity_id = sp_entity_id
+        self.idp_entity_id = idp_entity_id
+        self.idp_sso_url = idp_sso_url
+        self.idp_cert = idp_cert
+        self.idp_metadata_url = idp_metadata_url
+        self.account_id_attribute = account_id_attribute
+        self.email_attribute = email_attribute
+        self._idp: dict | None = None
+        # Fails at startup rather than at the first login when the extra is missing.
+        _onelogin("onelogin.saml2.settings")
+
+    async def get_authorization_url(
+        self, acs_url: str, relay_state: collections.abc.Callable[[str], str]
+    ) -> str:
+        """
+        Build the IdP redirect URL for a new AuthnRequest.
+
+        Args:
+            acs_url: The ACS URL the IdP posts the response to.
+            relay_state: Called with the AuthnRequest ID, returns the RelayState.
+
+        Returns:
+            str: The IdP URL to redirect the browser to.
+        """
+        return await smart_run(self._authorization_url, acs_url, relay_state)
+
+    async def process_response(
+        self, acs_url: str, post_data: dict[str, str], request_id: str
+    ) -> SAMLIdentity:
+        """
+        Validate a posted SAML response.
+
+        Args:
+            acs_url: The ACS URL the response must be addressed to.
+            post_data: The posted form fields, `SAMLResponse` included.
+            request_id: The AuthnRequest ID the response must answer.
+
+        Returns:
+            SAMLIdentity: The authenticated identity.
+
+        Raises:
+            SAMLResponseError: The response failed validation.
+        """
+        return await smart_run(self._process_response, acs_url, post_data, request_id)
+
+    def _authorization_url(
+        self, acs_url: str, relay_state: collections.abc.Callable[[str], str]
+    ) -> str:
+        """
+        Build the IdP redirect URL; the blocking half of `get_authorization_url`.
+
+        Args:
+            acs_url: The ACS URL the IdP posts the response to.
+            relay_state: Called with the AuthnRequest ID, returns the RelayState.
+
+        Returns:
+            str: The IdP URL to redirect the browser to.
+        """
+        authn_request_module = _onelogin("onelogin.saml2.authn_request")
+        utils = _onelogin("onelogin.saml2.utils")
+        settings = self._settings(acs_url)
+        authn_request = authn_request_module.OneLogin_Saml2_Authn_Request(settings)
+        return utils.OneLogin_Saml2_Utils.redirect(
+            settings.get_idp_sso_url(),
+            {
+                "SAMLRequest": authn_request.get_request(),
+                "RelayState": relay_state(authn_request.get_id()),
+            },
+        )
+
+    def _process_response(
+        self, acs_url: str, post_data: dict[str, str], request_id: str
+    ) -> SAMLIdentity:
+        """
+        Validate a posted SAML response; the blocking half of `process_response`.
+
+        Args:
+            acs_url: The ACS URL the response must be addressed to.
+            post_data: The posted form fields, `SAMLResponse` included.
+            request_id: The AuthnRequest ID the response must answer.
+
+        Returns:
+            SAMLIdentity: The authenticated identity.
+
+        Raises:
+            SAMLResponseError: The response failed validation.
+        """
+        response_module = _onelogin("onelogin.saml2.response")
+        settings = self._settings(acs_url)
+        try:
+            response = response_module.OneLogin_Saml2_Response(
+                settings, post_data.get("SAMLResponse", "")
+            )
+            valid = response.is_valid(_request_data(acs_url), request_id)
+        except Exception as e:
+            # The response is decoded and parsed in the constructor, so garbage raises here.
+            raise SAMLResponseError(["invalid_response"], repr(e)) from e
+        if not valid:
+            raise SAMLResponseError(["invalid_response"], response.get_error())
+        # The outer Response InResponseTo is unsigned, and python3-saml checks the signed one only when both are present.
+        signed_in_response_to = [
+            node.get("InResponseTo")
+            for node in response._query_assertion(
+                "/saml:Subject/saml:SubjectConfirmation/saml:SubjectConfirmationData"
+            )
+        ]
+        if request_id not in signed_in_response_to:
+            raise SAMLResponseError(
+                ["invalid_in_response_to"],
+                f"signed InResponseTo {signed_in_response_to!r} does not match {request_id!r}",
+            )
+        try:
+            # is_valid leaves NameID and duplicate-attribute checks to these getters.
+            attributes = response.get_attributes()
+            nameid = response.get_nameid()
+            assertion_id = response.get_assertion_id()
+            not_on_or_after = response.get_assertion_not_on_or_after()
+        except Exception as e:
+            raise SAMLResponseError(["invalid_response"], repr(e)) from e
+        account_id = nameid
+        if self.account_id_attribute:
+            account_id = _first(attributes, self.account_id_attribute)
+            if account_id is None:
+                raise SAMLResponseError(
+                    ["missing_account_id"],
+                    f"attribute {self.account_id_attribute!r} is missing",
+                )
+        return SAMLIdentity(
+            account_id=account_id,
+            account_email=_first(attributes, self.email_attribute)
+            if self.email_attribute
+            else nameid,
+            assertion_id=assertion_id,
+            not_on_or_after=not_on_or_after,
+            nameid=nameid,
+            attributes=attributes,
+        )
+
+    def _settings(
+        self, acs_url: str
+    ) -> "onelogin.saml2.settings.OneLogin_Saml2_Settings":
+        """
+        Build the python3-saml settings for one ACS URL.
+
+        Args:
+            acs_url: The ACS URL of this service provider.
+
+        Returns:
+            OneLogin_Saml2_Settings: The validated settings.
+        """
+        settings_module = _onelogin("onelogin.saml2.settings")
+        return settings_module.OneLogin_Saml2_Settings(
+            {
+                "strict": True,
+                "debug": False,
+                "sp": {
+                    "entityId": self.sp_entity_id,
+                    "assertionConsumerService": {
+                        "url": acs_url,
+                        "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
+                    },
+                    "NameIDFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
+                },
+                "idp": self._idp_data(),
+                "security": {
+                    "wantAssertionsSigned": True,
+                    "wantMessagesSigned": False,
+                    "wantNameId": True,
+                    "rejectDeprecatedAlgorithm": True,
+                    "requestedAuthnContext": False,
+                    "wantAttributeStatement": False,
+                    "allowSingleLabelDomains": True,
+                },
+            },
+            sp_validation_only=False,
+        )
+
+    def _idp_data(self) -> dict:
+        """
+        Return the python3-saml `idp` settings, fetching the metadata on first use.
+
+        Returns:
+            dict: The `idp` settings block, cached on the instance.
+        """
+        if self._idp is not None:
+            return self._idp
+        idp = {
+            "entityId": self.idp_entity_id,
+            "singleSignOnService": {
+                "url": self.idp_sso_url,
+                "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
+            },
+            "x509cert": self.idp_cert,
+        }
+        if not (self.idp_entity_id and self.idp_sso_url and self.idp_cert):
+            parser = _onelogin("onelogin.saml2.idp_metadata_parser")
+            metadata = parser.OneLogin_Saml2_IdPMetadataParser.parse_remote(
+                self.idp_metadata_url, timeout=10
+            )["idp"]
+            idp["entityId"] = self.idp_entity_id or metadata.get("entityId")
+            idp["x509cert"] = self.idp_cert or metadata.get("x509cert")
+            # Metadata listing several signing certificates (rollover) carries them here instead.
+            if not idp["x509cert"] and metadata.get("x509certMulti"):
+                idp["x509certMulti"] = metadata["x509certMulti"]
+                del idp["x509cert"]
+            # Raised before caching, so a later login fetches the metadata again.
+            if not (idp.get("x509cert") or idp.get("x509certMulti")):
+                raise ValueError(
+                    f"IdP metadata at {self.idp_metadata_url!r} lists no signing certificate"
+                )
+            if not self.idp_sso_url:
+                idp["singleSignOnService"] = metadata["singleSignOnService"]
+        self._idp = idp
+        return idp
+
+
+def seconds_until(timestamp: int | None) -> int:
+    """
+    Seconds from now until a unix timestamp.
+
+    Args:
+        timestamp: The unix timestamp; None means one hour.
+
+    Returns:
+        int: The seconds left, at least 1.
+    """
+    if timestamp is None:
+        return 3600
+    return max(1, math.ceil(timestamp - time.time()))
+
+
+def _first(attributes: dict[str, list[str]], name: str) -> str | None:
+    """
+    Return the first value of an assertion attribute.
+
+    Args:
+        attributes: The assertion attributes, name to values.
+        name: The attribute name.
+
+    Returns:
+        str | None: The first value, None when the attribute is absent or empty.
+    """
+    values = attributes.get(name) or []
+    return values[0] if values else None
+
+
+def _request_data(acs_url: str) -> dict:
+    """
+    Build the python3-saml request data for a response posted to the ACS URL.
+
+    Args:
+        acs_url: The ACS URL the IdP posted to.
+
+    Returns:
+        dict: The request data python3-saml validates `Destination` against.
+    """
+    # Built from the ACS URL, not the request: behind a proxy prefix the app sees a different path than the IdP posted to.
+    acs = urllib.parse.urlsplit(acs_url)
+    return {
+        "https": "on" if acs.scheme == "https" else "off",
+        "http_host": acs.netloc,
+        "script_name": acs.path,
+        "get_data": {},
+        "post_data": {},
+    }
+
+
+def _onelogin(module: str) -> types.ModuleType:
+    """
+    Import a python3-saml module, naming the extra when it is missing.
+
+    Args:
+        module: The dotted module name.
+
+    Returns:
+        types.ModuleType: The imported module.
+
+    Raises:
+        ImportError: The `saml` extra is not installed.
+    """
+    try:
+        return importlib.import_module(module)
+    except ImportError as e:
+        raise ImportError(
+            "SAML login needs the 'saml' extra: pip install fastapi-rtk[saml]"
+        ) from e

{fastapi_rtk-2.21.2 → fastapi_rtk-2.22.0}/fastapi_rtk/cli/decorators.py

@@ -68,7 +68,11 @@ def _current_command_path() -> str | None:
     Returns:
         str | None: The space-joined command names, or `None` when there is no active Click context.
     """
-    ctx = click.get_current_context(silent=True)
+    # typer >= 0.26 runs commands on its own vendored click, with its own context stack.
+    typer_get_current_context = getattr(typer.main, "get_current_context", None)
+    ctx = typer_get_current_context(silent=True) if typer_get_current_context else None
+    if ctx is None:
+        ctx = click.get_current_context(silent=True)
     if ctx is None:
         return None
     names = []

{fastapi_rtk-2.21.2 → fastapi_rtk-2.22.0}/fastapi_rtk/const.py

@@ -164,6 +164,8 @@ class ErrorCode(str, enum.Enum):
     FILE_NOT_FOUND = "FILE_NOT_FOUND"
     IMAGE_NOT_FOUND = "IMAGE_NOT_FOUND"
     OAUTH_POPUP_NOT_SUPPORTED = "OAUTH_POPUP_NOT_SUPPORTED"
+    SAML_RESPONSE_INVALID = "SAML_RESPONSE_INVALID"
+    SAML_ASSERTION_REPLAYED = "SAML_ASSERTION_REPLAYED"
     COLUMN_NOT_FOUND = "COLUMN_NOT_FOUND"