Skip to main content

xtr-security-csrf

Cross-site request forgery protection: a manager that mints and checks tokens by id, and the session storage that keeps them.

python 3.11+ typed license MIT

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 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 is the bundle that wires the family into an application on xtr-dependency-injection.

Install

uv add xtr-security-csrf

Requires Python 3.11+. One sibling comes with it: 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:

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())
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 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 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.

Development

Developed in the 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.

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.

Metadata

Release files for xtr-security-csrf 6.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for xtr-security-csrf 6.6.0
File Size Uploaded Provenance Actions
xtr_security_csrf-6.6.0.tar.gz 13.9 kB With provenance Details for xtr_security_csrf-6.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for xtr-security-csrf 6.6.0
File Interpreter ABI Platform Actions
xtr_security_csrf-6.6.0-py3-none-any.whl Python 3 none any Details for xtr_security_csrf-6.6.0-py3-none-any.whl

Total release size: 33.0 kB

Release files / xtr_security_csrf-6.6.0.tar.gz

Download URL xtr_security_csrf-6.6.0.tar.gz
Size 13.9 kB
Tags Source
SHA-256 checksum
How to use checksums
d9d98cd76c5b0955fe650d313f00d300582d1f5e785217c79715c97713da4082
BLAKE2b-256 checksum
How to use checksums
e8e2552c75d13a787f5631a953e7944498d235ca17051aa74be9f493ae86cc6b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / xtr_security_csrf-6.6.0-py3-none-any.whl

Download URL xtr_security_csrf-6.6.0-py3-none-any.whl
Size 19.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
878186a5da0a79a8c1c4f26c77d0e469ee8ce8ee1fa7c7707320440fdde45608
BLAKE2b-256 checksum
How to use checksums
b9631516e69171d0f73a59570f1bd1206b74aafce427c085e52f97dcf90162d5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for xtr-security-csrf 6.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for xtr_security_csrf-6.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page