xtr-security-csrf 5.0.0__py3-none-any.whl

xtr_security_csrf/__init__.py

@@ -0,0 +1,45 @@
+"""Cross-site request forgery tokens, minted and checked by id.
+
+A manager mints a value per token id, masks what it hands out, and checks
+what comes back against what it stored; a storage keeps the values — in the
+session a request carries, or wherever the application points them. This
+module gathers the public surface so an application imports it from one
+place.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .csrf_token import CsrfToken
+from .csrf_token_manager import CsrfTokenManager
+from .csrf_token_manager_interface import CsrfTokenManagerInterface
+from .exception import CsrfError, InvalidArgumentError, TokenNotFoundError
+from .token_generator import TokenGeneratorInterface, UriSafeTokenGenerator
+from .token_storage import (
+    ClearableTokenStorageInterface,
+    SessionTokenStorage,
+    TokenStorageInterface,
+)
+
+__all__ = [
+    "ClearableTokenStorageInterface",
+    "CsrfError",
+    "CsrfToken",
+    "CsrfTokenManager",
+    "CsrfTokenManagerInterface",
+    "InvalidArgumentError",
+    "SessionTokenStorage",
+    "TokenGeneratorInterface",
+    "TokenNotFoundError",
+    "TokenStorageInterface",
+    "UriSafeTokenGenerator",
+    "__version__",
+]
+
+try:
+    __version__ = version("xtr-security-csrf")
+except PackageNotFoundError:  # pragma: no cover
+    # Running from a source tree with no installed metadata to read; having no
+    # version is better than refusing to import.
+    __version__ = "0+unknown"

xtr_security_csrf/csrf_token.py

@@ -0,0 +1,46 @@
+"""A cross-site request forgery token, as a caller holds one."""
+
+from __future__ import annotations
+
+from typing import final
+
+from typing_extensions import override
+
+__all__ = ["CsrfToken"]
+
+
+@final
+class CsrfToken:
+    """The id a token is known under, and the value that answers for it.
+
+    A token id names what the token guards — a form, an action, a listener —
+    and the value is what a request carries to prove that the page which
+    rendered it asked for it. The pair travels together: the id says which
+    stored value the carried one is checked against.
+    """
+
+    __slots__ = ("_id", "_value")
+
+    def __init__(self, token_id: str, value: str = "") -> None:
+        """Record the id and the value that answers for it.
+
+        Args:
+            token_id: What the token guards, chosen by whoever mints it.
+            value: The value that answers for the id; the empty value is
+                the token a caller holds before one has been minted.
+        """
+        self._id = token_id
+        self._value = value
+
+    def get_id(self) -> str:
+        """Return the id this token is known under."""
+        return self._id
+
+    def get_value(self) -> str:
+        """Return the value that answers for the id."""
+        return self._value
+
+    @override
+    def __str__(self) -> str:
+        """Return the value, so a token renders straight into a form or a header."""
+        return self._value

xtr_security_csrf/csrf_token_manager.py

@@ -0,0 +1,181 @@
+"""The default token manager: values minted per id, masked on the way out."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import secrets
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+
+from .csrf_token import CsrfToken
+from .csrf_token_manager_interface import CsrfTokenManagerInterface
+from .token_generator.uri_safe_token_generator import UriSafeTokenGenerator
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from .token_generator.token_generator_interface import TokenGeneratorInterface
+    from .token_storage.token_storage_interface import TokenStorageInterface
+
+__all__ = ["CsrfTokenManager"]
+
+# The key a handed-out value is masked with. Long enough that guessing it is
+# hopeless, short enough that masking costs nothing.
+_MASK_KEY_LENGTH: int = 32
+# A masked value is three dot-separated parts: the prefix, the key, the value.
+_MASKED_PARTS: int = 3
+
+
+@final
+class CsrfTokenManager(CsrfTokenManagerInterface):
+    """Mints a value per token id, stores it, and masks what it hands out.
+
+    What answers for an id is not the value that is stored: every value
+    handed out is masked with a fresh key, so two renders of the same form
+    carry different strings, and a page that compresses its response cannot
+    be made to leak a token by echoing one back. The masked value is all a
+    caller ever sees; the stored one is all the manager ever compares.
+
+    The id a value is stored under is the namespace followed by the token
+    id, so tokens minted for one origin do not answer for another.
+    """
+
+    __slots__ = ("_generator", "_namespace", "_storage")
+
+    def __init__(
+        self,
+        storage: TokenStorageInterface,
+        generator: TokenGeneratorInterface | None = None,
+        namespace: str | Callable[[], str] | None = None,
+    ) -> None:
+        """Record where values are kept, what mints them, and how ids are prefixed.
+
+        Args:
+            storage: Where token values are kept, by namespaced id.
+            generator: What mints a fresh value; a URI-safe generator when
+                nothing is given.
+            namespace: The prefix every stored id carries, so tokens minted
+                for one origin do not answer for another: a string used as
+                it is, or a callable asked each time — the scheme a request
+                arrived under can change between calls, so it is read per
+                call, not once. ``None`` prefixes nothing.
+        """
+        self._storage = storage
+        self._generator = generator if generator is not None else UriSafeTokenGenerator()
+        self._namespace = namespace
+
+    @override
+    async def get_token(self, token_id: str) -> CsrfToken:
+        """Return the token for ``token_id``, minting one where none is stored.
+
+        A value already stored is handed out again — masked anew, so the
+        string differs, but it answers for the same stored value.
+        """
+        namespaced_id = self._namespaced_id(token_id)
+        if await self._storage.has_token(namespaced_id):
+            value = await self._storage.get_token(namespaced_id)
+        else:
+            value = self._generator.generate_token()
+            await self._storage.set_token(namespaced_id, value)
+
+        return CsrfToken(token_id, self._randomize(value))
+
+    @override
+    async def refresh_token(self, token_id: str) -> CsrfToken:
+        """Mint a fresh value for ``token_id``, replacing whatever was stored."""
+        namespaced_id = self._namespaced_id(token_id)
+        value = self._generator.generate_token()
+        await self._storage.set_token(namespaced_id, value)
+
+        return CsrfToken(token_id, self._randomize(value))
+
+    @override
+    async def remove_token(self, token_id: str) -> str | None:
+        """Drop the value under ``token_id``, returning what it held."""
+        return await self._storage.remove_token(self._namespaced_id(token_id))
+
+    @override
+    async def is_token_valid(self, token: CsrfToken) -> bool:
+        """Tell whether ``token`` carries the value stored under its id.
+
+        The comparison is constant-time, and the value it is handed is never
+        trusted to be well-formed: one that does not read as a value this
+        manager minted is compared as it came, and does not check out.
+        """
+        namespaced_id = self._namespaced_id(token.get_id())
+        if not await self._storage.has_token(namespaced_id):
+            return False
+
+        stored = await self._storage.get_token(namespaced_id)
+        return hmac.compare_digest(
+            stored.encode(),
+            self._derandomize(token.get_value()).encode(),
+        )
+
+    def _namespaced_id(self, token_id: str) -> str:
+        """Return the id as it is stored: the namespace, then the id."""
+        namespace = self._namespace
+        if namespace is None:
+            return token_id
+        if isinstance(namespace, str):
+            return namespace + token_id
+        return namespace() + token_id
+
+    def _randomize(self, value: str) -> str:
+        """Mask ``value`` with a fresh key, so what is handed out differs every call.
+
+        The key travels with the masked value — there is nothing to keep
+        between calls — and a short hex prefix of key-derived length heads
+        the three parts, so two values of the same token are not even the
+        same length. The prefix is never read back; only the key and the
+        masked value are.
+        """
+        key = secrets.token_bytes(_MASK_KEY_LENGTH)
+        masked = _xor(value.encode(), key)
+        prefix = hashlib.sha256(key).hexdigest()[: 1 + key[0] % 32]
+        return f"{prefix}.{_encode(key)}.{_encode(masked)}"
+
+    def _derandomize(self, value: str) -> str:
+        """Return the stored value a handed-out string masks, or the string itself.
+
+        Anything that does not read as a masked value — not three parts, a
+        part that is not the encoding it claims, bytes that are not text —
+        is returned exactly as it came, and so fails the comparison that
+        follows. A caller's string is never trusted to be well-formed.
+        """
+        parts = value.split(".")
+        if len(parts) != _MASKED_PARTS:
+            return value
+
+        try:
+            key = _decode(parts[1])
+            if not key:
+                return value
+            masked = _decode(parts[2])
+            return _xor(masked, key).decode()
+        except ValueError:
+            return value
+
+
+def _xor(value: bytes, key: bytes) -> bytes:
+    """Return ``value`` masked with ``key``, byte for byte.
+
+    The key is repeated until it covers the value, and the result is as
+    long as the shorter of the two — the value, once it is.
+    """
+    if len(value) > len(key):
+        key = key * ((len(value) + len(key) - 1) // len(key))
+    return bytes(left ^ right for left, right in zip(value, key, strict=False))
+
+
+def _encode(data: bytes) -> str:
+    """Return ``data`` as URI-safe base64, without padding."""
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()
+
+
+def _decode(data: str) -> bytes:
+    """Return the bytes a URI-safe, unpadded value encodes."""
+    return base64.urlsafe_b64decode(data + "=" * (-len(data) % 4))

xtr_security_csrf/csrf_token_manager_interface.py

@@ -0,0 +1,56 @@
+"""The one surface every token manager answers."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from .csrf_token import CsrfToken
+
+__all__ = ["CsrfTokenManagerInterface"]
+
+
+@runtime_checkable
+class CsrfTokenManagerInterface(Protocol):
+    """Mints, renews, drops and checks tokens, by id.
+
+    Every member is awaited: a manager reaches a storage to answer any of
+    them, and one storage must be swappable for another — a remote one is
+    awaited — exactly as every matcher is awaited even when it only reads
+    the head of a request.
+    """
+
+    async def get_token(self, token_id: str) -> CsrfToken:
+        """Return the token for ``token_id``, minting one where none is stored.
+
+        A token already stored is returned with the value it holds — the
+        same stored value, though not the same string, since what is handed
+        out is masked per call — so asking twice answers two tokens that
+        both check out.
+        """
+        ...
+
+    async def refresh_token(self, token_id: str) -> CsrfToken:
+        """Mint a fresh value for ``token_id``, stored or not.
+
+        For once-only tokens, in places with high security needs: whatever
+        was stored under the id is replaced, independent of whether a value
+        existed before.
+        """
+        ...
+
+    async def remove_token(self, token_id: str) -> str | None:
+        """Drop the token under ``token_id``, if one is stored.
+
+        Returns:
+            The value the id held, or ``None`` when it held nothing.
+        """
+        ...
+
+    async def is_token_valid(self, token: CsrfToken) -> bool:
+        """Tell whether ``token`` carries the value stored under its id.
+
+        Never raises on the value it is handed: one that does not read as
+        a value this manager minted simply does not check out.
+        """
+        ...

xtr_security_csrf/exception/__init__.py

@@ -0,0 +1,19 @@
+"""Every error this library raises.
+
+All of them derive from :class:`CsrfError`, so one ``except`` catches
+anything minting or checking a token can go wrong with, and a narrower one
+handles a single cause. Each carries the data a caller needs as typed
+attributes rather than forcing a message to be parsed.
+"""
+
+from __future__ import annotations
+
+from .csrf_error import CsrfError
+from .invalid_argument_error import InvalidArgumentError
+from .token_not_found_error import TokenNotFoundError
+
+__all__ = [
+    "CsrfError",
+    "InvalidArgumentError",
+    "TokenNotFoundError",
+]

xtr_security_csrf/exception/csrf_error.py

@@ -0,0 +1,15 @@
+"""The root every error in this library derives from."""
+
+from __future__ import annotations
+
+__all__ = ["CsrfError"]
+
+
+class CsrfError(Exception):
+    """Base class for every error raised by this library.
+
+    Catch this to handle anything minting or checking a cross-site request
+    forgery token can go wrong with; catch a subclass to handle one cause.
+    Every subclass carries the data a caller needs as typed attributes and
+    composes its own message from them.
+    """

xtr_security_csrf/exception/invalid_argument_error.py

@@ -0,0 +1,16 @@
+"""Something was declared or configured in a way this library cannot work with."""
+
+from __future__ import annotations
+
+from .csrf_error import CsrfError
+
+__all__ = ["InvalidArgumentError"]
+
+
+class InvalidArgumentError(CsrfError, ValueError):
+    """A declaration, configuration or call was malformed.
+
+    A generator asked for less entropy than a byte holds — mistakes caught
+    where they are made. Also a :class:`ValueError`, so code guarding its
+    configuration with ``except ValueError`` keeps working.
+    """

xtr_security_csrf/exception/token_not_found_error.py

@@ -0,0 +1,33 @@
+"""A token was asked for under an id nothing is stored under."""
+
+from __future__ import annotations
+
+from .csrf_error import CsrfError
+
+__all__ = ["TokenNotFoundError"]
+
+
+class TokenNotFoundError(CsrfError):
+    """No token is stored under the id a caller asked to read.
+
+    The manager never raises it — where nothing is stored it mints — it is
+    the error a storage raises when its ``get_token`` is called directly for
+    an id that holds nothing.
+    """
+
+    __slots__: tuple[str, ...] = ("_token_id",)
+
+    _token_id: str
+
+    def __init__(self, token_id: str) -> None:
+        """Record which id was asked about and found empty.
+
+        Args:
+            token_id: The id whose stored value was asked for.
+        """
+        super().__init__(f"The CSRF token with ID {token_id} does not exist.")
+        self._token_id = token_id
+
+    def get_token_id(self) -> str:
+        """Return the id no token is stored under."""
+        return self._token_id

xtr_security_csrf/token_generator/__init__.py

@@ -0,0 +1,11 @@
+"""Generators that mint the values tokens answer with."""
+
+from __future__ import annotations
+
+from .token_generator_interface import TokenGeneratorInterface
+from .uri_safe_token_generator import UriSafeTokenGenerator
+
+__all__ = [
+    "TokenGeneratorInterface",
+    "UriSafeTokenGenerator",
+]

xtr_security_csrf/token_generator/token_generator_interface.py

@@ -0,0 +1,20 @@
+"""The one surface every token generator answers."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+__all__ = ["TokenGeneratorInterface"]
+
+
+@runtime_checkable
+class TokenGeneratorInterface(Protocol):
+    """Mints the value a token id is answered with.
+
+    Synchronous, and kept that way: minting is pure randomness, it reaches
+    nothing — the storage is what a caller waits on.
+    """
+
+    def generate_token(self) -> str:
+        """Return a fresh value, never seen before."""
+        ...

xtr_security_csrf/token_generator/uri_safe_token_generator.py

@@ -0,0 +1,50 @@
+"""A generator whose values carry no character a URI would have to encode."""
+
+from __future__ import annotations
+
+import base64
+import secrets
+from typing import Final, final
+
+from typing_extensions import override
+
+from xtr_security_csrf.exception import InvalidArgumentError
+
+from .token_generator_interface import TokenGeneratorInterface
+
+__all__ = ["UriSafeTokenGenerator"]
+
+# A value drawn from fewer than eight bits could be guessed.
+_MINIMUM_ENTROPY: Final = 8
+
+
+@final
+class UriSafeTokenGenerator(TokenGeneratorInterface):
+    """Mints URI-safe values: base64 with ``+``, ``/`` and ``=`` gone.
+
+    A value that carries none of the characters a URI encodes sits in a
+    query, a form field or a header as it is, without a reader having to
+    decode anything first — which is why the padding is stripped too.
+    """
+
+    __slots__ = ("_entropy",)
+
+    def __init__(self, entropy: int = 256) -> None:
+        """Record how much entropy each minted value carries.
+
+        Args:
+            entropy: The bits of randomness each value is drawn from.
+
+        Raises:
+            InvalidArgumentError: When ``entropy`` is 7 bits or fewer — a
+                value that short could be guessed.
+        """
+        if entropy < _MINIMUM_ENTROPY:
+            raise InvalidArgumentError("The entropy should be greater than 7.")
+        self._entropy = entropy
+
+    @override
+    def generate_token(self) -> str:
+        """Return a fresh URI-safe value of the configured entropy."""
+        raw = secrets.token_bytes(self._entropy // 8)
+        return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()

xtr_security_csrf/token_storage/__init__.py

@@ -0,0 +1,13 @@
+"""Storages that keep the values tokens answer with."""
+
+from __future__ import annotations
+
+from .clearable_token_storage_interface import ClearableTokenStorageInterface
+from .session_token_storage import SessionTokenStorage
+from .token_storage_interface import TokenStorageInterface
+
+__all__ = [
+    "ClearableTokenStorageInterface",
+    "SessionTokenStorage",
+    "TokenStorageInterface",
+]

xtr_security_csrf/token_storage/clearable_token_storage_interface.py

@@ -0,0 +1,24 @@
+"""A token storage that can drop every token it holds at once."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from .token_storage_interface import TokenStorageInterface
+
+__all__ = ["ClearableTokenStorageInterface"]
+
+
+@runtime_checkable
+class ClearableTokenStorageInterface(TokenStorageInterface, Protocol):
+    """A token storage that can also drop everything it holds.
+
+    The session strategy is the caller: when a re-authentication rotates
+    the session, the tokens minted under the old one must not answer for
+    the new — a value stolen before the rotation would otherwise still
+    check out after it.
+    """
+
+    async def clear(self) -> None:
+        """Drop every token this storage holds."""
+        ...

xtr_security_csrf/token_storage/session_token_storage.py

@@ -0,0 +1,120 @@
+"""A token storage that keeps its tokens in the session a request carries."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast, final
+
+from typing_extensions import override
+
+from xtr_security_csrf.exception import TokenNotFoundError
+
+from .clearable_token_storage_interface import ClearableTokenStorageInterface
+
+if TYPE_CHECKING:
+    from xtr_http_foundation import SessionInterface
+
+__all__ = ["SessionTokenStorage"]
+
+
+@final
+class SessionTokenStorage(ClearableTokenStorageInterface):
+    """Keeps token values in the session, under the id they answer for.
+
+    Each value lives under ``<namespace>/<token_id>``: the namespace keeps
+    the tokens out of the attributes the rest of the application keeps in
+    the same session, and lets two applications sharing one session keep
+    their tokens apart.
+
+    The storage also keeps the list of its ids under the namespace key
+    itself. The session offers no way to walk the attributes it carries, so
+    the list is what ``clear()`` drops them from — every token this storage
+    minted, and nothing the rest of the session holds. A value written
+    under the namespace by something else than this storage is not in the
+    list, and survives a clear.
+    """
+
+    __slots__ = ("_namespace", "_session")
+
+    def __init__(self, session: SessionInterface, namespace: str = "_csrf") -> None:
+        """Record the session the tokens travel in, and their namespace.
+
+        Args:
+            session: The session whose attributes carry the tokens.
+            namespace: The prefix every stored id carries.
+        """
+        self._session = session
+        self._namespace = namespace
+
+    @override
+    async def get_token(self, token_id: str) -> str:
+        """Return the value stored under ``token_id``.
+
+        Raises:
+            TokenNotFoundError: When no value is stored under the id.
+        """
+        name = self._key(token_id)
+        if not await self._session.has(name):
+            raise TokenNotFoundError(token_id)
+        return str(await self._session.get(name))
+
+    @override
+    async def set_token(self, token_id: str, token: str) -> None:
+        """Store ``token`` under ``token_id``, and remember the id."""
+        await self._session.set(self._key(token_id), token)
+        await self._remember(token_id)
+
+    @override
+    async def has_token(self, token_id: str) -> bool:
+        """Tell whether a value is stored under ``token_id``."""
+        return await self._session.has(self._key(token_id))
+
+    @override
+    async def remove_token(self, token_id: str) -> str | None:
+        """Drop the value under ``token_id``, returning what it held."""
+        value = await self._session.remove(self._key(token_id))
+        await self._forget(token_id)
+        return None if value is None else str(value)
+
+    @override
+    async def clear(self) -> None:
+        """Drop every token this storage minted, and nothing else.
+
+        The ids come from the list kept under the namespace key, so the
+        clear is complete across the requests that minted them — a token
+        stored two requests ago goes with one stored now. The session
+        strategy calls this when a re-authentication rotates the session:
+        the tokens minted under the old one must not answer for the new.
+        """
+        for token_id in await self._stored_ids():
+            _ = await self._session.remove(self._key(token_id))
+        _ = await self._session.remove(self._namespace)
+
+    def _key(self, token_id: str) -> str:
+        """Return the name the value for ``token_id`` is stored under."""
+        return f"{self._namespace}/{token_id}"
+
+    async def _stored_ids(self) -> tuple[str, ...]:
+        """Return every id this storage has minted a token under."""
+        ids = await self._session.get(self._namespace)
+        if not isinstance(ids, list):
+            return ()
+        # The list is written by this class, of the ids it minted; the cast
+        # says so once rather than at every element the loop reads.
+        return tuple(cast("list[str]", ids))
+
+    async def _remember(self, token_id: str) -> None:
+        """Add ``token_id`` to the ids a ``clear()`` drops, if it is not there."""
+        ids = await self._stored_ids()
+        if token_id not in ids:
+            await self._session.set(self._namespace, [*ids, token_id])
+
+    async def _forget(self, token_id: str) -> None:
+        """Take ``token_id`` out of the ids a ``clear()`` drops."""
+        ids = await self._stored_ids()
+        if token_id not in ids:
+            return
+        remaining = [stored for stored in ids if stored != token_id]
+        if remaining:
+            await self._session.set(self._namespace, remaining)
+        else:
+            _ = await self._session.remove(self._namespace)

xtr_security_csrf/token_storage/token_storage_interface.py

@@ -0,0 +1,41 @@
+"""The one surface every token storage answers."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+__all__ = ["TokenStorageInterface"]
+
+
+@runtime_checkable
+class TokenStorageInterface(Protocol):
+    """Keeps token values by id, wherever the application points them.
+
+    Every member is awaited: one storage must be swappable for another, and
+    a remote one is awaited — the session is only the one this library
+    ships a storage for.
+    """
+
+    async def get_token(self, token_id: str) -> str:
+        """Return the value stored under ``token_id``.
+
+        Raises:
+            TokenNotFoundError: When no value is stored under the id.
+        """
+        ...
+
+    async def set_token(self, token_id: str, token: str) -> None:
+        """Store ``token`` under ``token_id``, replacing what was there."""
+        ...
+
+    async def remove_token(self, token_id: str) -> str | None:
+        """Drop the value under ``token_id``.
+
+        Returns:
+            The value it held, or ``None`` when it held nothing.
+        """
+        ...
+
+    async def has_token(self, token_id: str) -> bool:
+        """Tell whether a value is stored under ``token_id``."""
+        ...

xtr_security_csrf-5.0.0.dist-info/METADATA

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: xtr-security-csrf
+Version: 5.0.0
+Summary: Cross-site request forgery protection for xtr applications: a manager that mints and checks tokens by id, and the session storage that keeps them.
+Keywords: security,csrf,tokens,session
+Author: Xterr
+Author-email: Xterr <me@xterr.dev>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Typing :: Typed
+Requires-Dist: typing-extensions>=4.12
+Requires-Dist: xtr-http-foundation>=5.0,<6
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# xtr-security-csrf
+
+**Cross-site request forgery protection: a manager that mints and checks tokens by id, and the session storage that keeps them.**
+
+<img alt="python 3.11+" src="https://img.shields.io/badge/python-%E2%89%A5%203.11-3776AB?logo=python&logoColor=white">
+<img alt="typed" src="https://img.shields.io/badge/typed-ty%20%2B%20basedpyright-1f6feb">
+<img alt="license MIT" src="https://img.shields.io/badge/license-MIT-blue">
+
+</div>
+
+---
+
+## Why?
+
+A browser submits a form because a page told it to — and a page on someone else's site can
+tell it to submit yours, carrying the user's cookies as though the request were the user's.
+A **cross-site request forgery token** breaks that: the page that renders a form mints a
+value into it, and the request that submits the form carries the value back, where it is
+checked against what was minted. Another site's page cannot read the value — it is on your
+origin's page, not theirs — so its forged submit does not check out.
+
+This package is that mechanism, in three small pieces:
+
+- 🎫 **A token** — `CsrfToken(token_id, value)`: the id names what the token guards, the
+  value answers for it.
+- 🖋️ **A manager** — `CsrfTokenManager(storage, generator=None, namespace=None)` mints a
+  value per id, stores it, and masks what it hands out: every value a caller sees is
+  masked with a fresh key, so two renders of one form carry different strings — and both
+  check out, because what is *stored* never changes until `refresh_token` replaces it.
+  `is_token_valid` compares in constant time and never raises on what it is handed.
+- 🗄️ **A storage** — `TokenStorageInterface` keeps values by id; `SessionTokenStorage`
+  keeps them in the [xtr-http-foundation](../xtr-http-foundation) session, under
+  `_csrf/<token_id>`, and `ClearableTokenStorageInterface.clear()` drops every token it
+  minted — the session strategy's call when a re-authentication rotates the session, so
+  a value stolen before the rotation cannot answer after it.
+
+It ships no bundle of its own: it is a library member of the security family —
+[xtr-security](../xtr-security) is the bundle that wires the family into an application on
+[xtr-dependency-injection](../xtr-dependency-injection).
+
+## Install
+
+```sh
+uv add xtr-security-csrf
+```
+
+Requires Python 3.11+. One sibling comes with it:
+[xtr-http-foundation](../xtr-http-foundation), whose session the storage keeps tokens in.
+
+## Quick start
+
+Everything below runs without a container: a session on the memory storage, the storage
+over it, the manager over that. Mint a token where a form renders, check it where the form
+submits:
+
+```python
+from __future__ import annotations
+
+import asyncio
+
+from xtr_http_foundation import MemorySessionStorage, Session
+from xtr_security_csrf import CsrfToken, CsrfTokenManager, SessionTokenStorage
+
+
+async def main() -> None:
+    session = Session(MemorySessionStorage())
+    manager = CsrfTokenManager(SessionTokenStorage(session))
+
+    # The page that renders the form mints the token into it.
+    token = await manager.get_token("newsletter")
+    print("render:", token.get_value())
+
+    # The request that submits the form carries the value back.
+    print("carried:", await manager.is_token_valid(token))
+
+    # A value nobody minted does not check out.
+    print("forged:", await manager.is_token_valid(CsrfToken("newsletter", "nope")))
+
+
+asyncio.run(main())
+```
+
+```console
+render: 3.kV3xtkP…  (masked anew on every run)
+carried: True
+forged: False
+```
+
+The manager's four calls:
+
+| Call | What it does |
+|---|---|
+| `await get_token(token_id)` | Returns the token for the id, minting one where none is stored |
+| `await refresh_token(token_id)` | Mints a fresh value for the id, stored or not — for once-only tokens |
+| `await remove_token(token_id)` | Drops the value, returning what it held, or `None` |
+| `await is_token_valid(token)` | Tells whether the token carries the value stored under its id |
+
+### The masked value
+
+What a caller receives is never the stored value: `get_token` masks it with a fresh random
+key every call — three dot-separated parts, a key-derived prefix, the key, the masked
+value. The manager unmasks what comes back before comparing, so any string a request
+carries can be handed to `is_token_valid` without a guard: one that does not read as a
+masked value is compared as it came, and does not check out.
+
+### The namespace
+
+Stored ids carry a prefix: `CsrfTokenManager(storage, namespace="https-")` stores under
+`https-<token_id>`, so tokens minted for one origin do not answer for another. A string is
+used as it is; a callable is asked each time — the scheme a request arrived under can
+change between calls. `None`, the default, prefixes nothing.
+
+### The storage
+
+`SessionTokenStorage(session, namespace="_csrf")` keeps each value under
+`<namespace>/<token_id>` in the session's attributes, and keeps the list of its ids under
+the namespace key itself — the session offers no way to walk its attributes, so the list
+is what `clear()` drops them from: every token this storage minted, and nothing the rest of
+the session holds. A token written under the namespace by something else than this storage
+is not in the list, and survives a clear.
+
+`clear()` is the session strategy's call, on the re-authentication that rotates the
+session: the tokens minted under the old one must not answer for the new. `remove_token`
+is the logout listener's — it drops the ids a listener knows by name.
+
+## Errors
+
+Everything this library raises derives from `CsrfError`, and carries what went wrong as
+typed attributes rather than only a message.
+
+| Error | Base (besides `CsrfError`) | Raised when |
+|---|---|---|
+| `InvalidArgumentError` | `ValueError` | a declaration, configuration or call was malformed — a generator asked for less entropy than a byte holds |
+| `TokenNotFoundError` | — | a value was asked for under an id that holds nothing; carries `get_token_id()` |
+
+## Layout
+
+```
+xtr_security_csrf/
+├── csrf_token.py                    CsrfToken, the id and the value a caller holds
+├── csrf_token_manager_interface.py CsrfTokenManagerInterface, the four calls
+├── csrf_token_manager.py           CsrfTokenManager, minting, masking, checking
+├── token_generator/
+│   ├── token_generator_interface.py  TokenGeneratorInterface, the minting seam
+│   └── uri_safe_token_generator.py   UriSafeTokenGenerator, URI-safe values
+├── token_storage/
+│   ├── token_storage_interface.py          TokenStorageInterface, values by id
+│   ├── clearable_token_storage_interface.py ClearableTokenStorageInterface, + clear()
+│   └── session_token_storage.py            SessionTokenStorage, in the session
+└── exception/                       CsrfError, the root of everything raised
+```
+
+## Testing
+
+The suite runs on `pytest` with `anyio`; the storages are exercised over a real
+[xtr-http-foundation](../xtr-http-foundation) `Session` on `MemorySessionStorage`, so the
+persist-and-reattach path a request actually takes is what the tests prove — not a mock
+of it.
+
+## In an application
+
+This package works on its own and ships no bundle. The
+[`xtr-security`](../xtr-security#use-in-an-application) bundle wires it: a firewall that
+asks for a token — a form login with `enable_csrf`, a logout's `enable_csrf` or
+`clear_csrf_tokens`, a switch-user's `enable_csrf`, or the firewall's
+`csrf_route_markers` for routes proving themselves with `IsCsrfTokenValid` — has the
+bundle build the manager over the session the request
+reattached, registered as the application's one `CsrfTokenManagerInterface` service. See
+that package's [Use in an application](../xtr-security#use-in-an-application).
+
+## Development
+
+Developed in the [python-xtr](https://github.com/xterr/python-xtr) monorepo, under
+`packages/xtr-security-csrf`; run the commands below from there. The `python-xtr-security-csrf`
+repository is a read-only copy, so send issues and pull requests to the monorepo.
+
+```sh
+uv sync
+uv run ruff check && uv run ruff format --check && uv run basedpyright && uv run ty check && uv run pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

xtr_security_csrf-5.0.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+xtr_security_csrf/__init__.py,sha256=YSIqDdt3kdDIUd9MI9iu_Hsl5cnOs-y-p-gLZHHfxH8,1486
+xtr_security_csrf/csrf_token.py,sha256=q7bnHKIRtBjzowFCxdycudwPxxPRYrEHggx-qbHjrbA,1422
+xtr_security_csrf/csrf_token_manager.py,sha256=RFAfpfG6djy74s0ZqNrx345YVE5HTw5BYHotgibgcTo,7244
+xtr_security_csrf/csrf_token_manager_interface.py,sha256=we3cx-pWakwwhiFPHr4cqWBmAyZ8ZsecLv2vWOFQ--U,1907
+xtr_security_csrf/exception/__init__.py,sha256=gEPvUT7lVok3qDCw7s5uSxYXD261-FBIKWWk5lALp-I,579
+xtr_security_csrf/exception/csrf_error.py,sha256=4ETPOn481Z90UPNJNd9lzSYGHx37qdDL8NLEfPmSr8s,480
+xtr_security_csrf/exception/invalid_argument_error.py,sha256=0mAu-l5wIwg-r8bJmQbfe9ivMHAJP6Chk_h2sT_sHtA,522
+xtr_security_csrf/exception/token_not_found_error.py,sha256=IuIwBMHVqQCN2ymOMJwH6CNJxAaL0al_oSZa5dAnT8E,967
+xtr_security_csrf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xtr_security_csrf/token_generator/__init__.py,sha256=BFC4ueg-ZftFKdFdtcGGqNdlD9eEQTHIlLQ6GWQ7AHA,293
+xtr_security_csrf/token_generator/token_generator_interface.py,sha256=Cmdnbx-4PpbNYTxYVVwEKxiuh1ziOWiakERC2wOiQ8U,534
+xtr_security_csrf/token_generator/uri_safe_token_generator.py,sha256=0DFT21UOyTatpNMJp_3KFdHXZ6TJVX97PvgYBUhsg9w,1611
+xtr_security_csrf/token_storage/__init__.py,sha256=DRCYy0_yo91LmAnpM9G3bDtUc9R1WE_fG5aDP7akdr0,394
+xtr_security_csrf/token_storage/clearable_token_storage_interface.py,sha256=SA1w7m9I0A-6Wsw9COTq34vZ52rptwvON7CX9CPt-_4,762
+xtr_security_csrf/token_storage/session_token_storage.py,sha256=Skojw3BAR0QOtQVApszaoZvw5QPrnu1bR1SswN45P5I,4794
+xtr_security_csrf/token_storage/token_storage_interface.py,sha256=rSzWMPJa9Gqg4WiPtR8EjlDCuihWIBk3JoIJxEykH5w,1210
+xtr_security_csrf-5.0.0.dist-info/licenses/LICENSE,sha256=N6mW05zc_GYFRdNovzY4zFuWyBKavZLcouPmDOBHK5o,1106
+xtr_security_csrf-5.0.0.dist-info/WHEEL,sha256=3NO1oYsF7mANFUWVdyEQLM-zmecczWWEmmF5rEbXrWk,80
+xtr_security_csrf-5.0.0.dist-info/METADATA,sha256=5pmMy_ktVCNnx7qc8pq99REuqJ38UfuvRPvFk-aWJjc,9044
+xtr_security_csrf-5.0.0.dist-info/RECORD,,

xtr_security_csrf-5.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.6
+Root-Is-Purelib: true
+Tag: py3-none-any

xtr_security_csrf-5.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 xterr
+Copyright (c) 2004-present Fabien Potencier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.