Skip to main content

xtr-security

The security bundle for xtr applications: the family facade and the container wiring that configures it.

python 3.11+ typed license MIT

Why?

The security family is four libraries — xtr-security-core, xtr-security-http, xtr-security-csrf and xtr-password-hasher — each usable on its own. Wiring them together by hand is a lot of moving parts: a token storage per request, voters gathered into a decision manager, a user provider and a password hasher, and, per firewall, an authenticator over its own event dispatcher, an access map, an entry point and the OpenAPI scheme it shows.

This package is the one bundle of the family. An application lists SecurityBundle, writes one SecurityConfig, and the container owns the rest.

  • 🔥 Firewalls as configuration — a slice of the request space, how it authenticates, and the rules it enforces, in one frozen value.
  • 🧩 Open at the seams — a third-party bundle adds a kind of authenticator, token handler or user provider through the factory registries, without this package knowing it.
  • 🪪 The FastAPI surface stays FastAPI's — IsGranted and CurrentUser are dependencies and decorators; the firewall itself runs as a subscriber over the kernel lifecycle's events, before routing, and a route documents its security with the framework's own params.
  • 🔒 Scoped to the request — the token storage, the authorization checker and the Security facade are per-request; concurrent requests never share them.

Install

uv add xtr-security                    # the bundle, wiring core, http, csrf and the password hasher
uv add xtr-console                     # beside it: debug:firewall and security:hash-password
uv add "xtr-security-http[oidc]"       # + verifying third-party OIDC issuers' tokens

Requires Python 3.11+. The core, http-edge and password-hasher libraries come with the package; xtr-console, installed beside it, adds the commands. The forgery-token library comes with the package too — the bundle builds its manager itself where a firewall asks for a token — and so does the rate limiter, whose factories a throttled firewall's attempts count under. The oidc extra of xtr-security-http adds joserfc and httpx; the bundle registers the OIDC token handler, the userinfo handler and the OIDC login factories only when that extra is installed. Self-issued JSON Web Tokens are a separate package, xtr-security-jwt, which depends on this one and registers itself through the extension points.

Quick start

Write a token handler that turns a bearer token into a user, configure a firewall that uses it, and secure the routes — no JSON Web Tokens needed.

# app/security_handler.py
from xtr_dependency_injection import as_service
from xtr_security_core import InMemoryUser
from xtr_security_http import UserBadge
from xtr_security_http.access_token.access_token_handler_interface import (
    AccessTokenHandlerInterface,
)
from xtr_security_http.exception import InvalidAccessTokenError


@as_service
class MyTokenHandler(AccessTokenHandlerInterface):
    async def get_user_badge_from(self, access_token: str) -> UserBadge:
        if access_token != "s3cret":
            raise InvalidAccessTokenError("Unknown token.")
        return UserBadge("alice", user_loader=lambda i: InMemoryUser(i, roles=["ROLE_USER"]))
# app/config/packages/security.py
from xtr_dependency_injection import configure
from xtr_security.bundle import (
    AccessControlConfig,
    AccessTokenConfig,
    FirewallConfig,
    SecurityConfig,
    ServiceTokenHandlerConfig,
)

from app.security_handler import MyTokenHandler


@configure
def security() -> SecurityConfig:
    return SecurityConfig(
        firewalls={
            "api": FirewallConfig(
                pattern=r"^/api",
                authenticators=(
                    AccessTokenConfig(
                        token_handler=ServiceTokenHandlerConfig(MyTokenHandler),
                        realm="api",
                    ),
                ),
            ),
        },
        access_control=(AccessControlConfig(path=r"^/api", attribute="IS_AUTHENTICATED"),),
    )
# app/web.py
from typing import Annotated

from fastapi import FastAPI
from xtr_dependency_injection import Kernel
from xtr_http_kernel import setup
from xtr_security_core.user.user_interface import UserInterface
from xtr_security_http import CurrentUser, IsGranted

from app.bundles import BUNDLES

app = FastAPI()


@app.get("/api/me")
async def me(user: Annotated[UserInterface, CurrentUser()]) -> dict[str, str]:
    return {"user": user.get_user_identifier()}


@app.get("/api/books")
async def books() -> list[str]: ...


@app.delete("/api/books/{isbn}")
@IsGranted("ROLE_ADMIN")
async def delete_book(isbn: str) -> None: ...


kernel = Kernel("app", concurrent_scoped_access=True)
setup(app, kernel)
$ curl -i localhost:8000/api/me
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api"

$ curl -i -H 'Authorization: Bearer s3cret' localhost:8000/api/me
HTTP/1.1 200 OK

{"user":"alice"}

Configure

SecurityConfig is a frozen dataclass buildable with no arguments; every field has a default, so the zero-config path is no firewalls and the affirmative decision strategy.

Field Default What it is
firewalls {} The firewalls, keyed by name, matched in order — first match wins
providers {} The user providers, keyed by the name firewalls refer to
password_hashers {} The hasher each user class, "module:Class" string or name is hashed by
role_hierarchy {} The roles each role reaches, expanding a token's roles
access_control () The access-control rules, tried in order
access_decision_manager affirmative How the voters' answers become one decision
http_port 80 The port plain http answers on, spelled out in a channel redirect when it is not the default
https_port 443 The port https answers on, spelled out in a channel redirect when it is not the default
expose_security_errors NONE How much of an authentication failure reaches the client
trace_votes None Announce every vote as an event and log every decision; None follows kernel.debug
authenticator_factories built-ins The factories that build firewalls' authenticators
token_handler_factories built-ins The factories that build access-token handlers
user_provider_factories built-ins The factories that build user providers

The built-ins the zero-config path carries: eight authenticator factories — access token, form login, HTTP basic, JSON login, login link, remember me, remote user and X509 — joined by a ninth, the OIDC login, only when the oidc extra is installed; two token-handler factories — a service handler and the OAuth2 introspection one — joined by the OIDC and userinfo ones under the same extra; and three user-provider factories — in-memory, chain and service. Nothing else registers unconfigured: no firewall, no rule, no voter beyond the built-ins.

Firewalls

FirewallConfig claims a slice of the request space and says how it authenticates:

Field Default What it is
pattern None A regular expression matched against the request path
host None A regular expression matched against the request host
methods () The HTTP methods claimed; every method when empty
request_matcher None A callable (ServerRequestInterface) -> bool, tried last
security True False lets every request the firewall claims through untouched
stateless True Whether the firewall keeps no session. A stateful firewall (stateless=False) restores the token its session carries on every request, through the SessionStorageInterface service the application registers; with none registered the build fails naming it
context_key None The name the firewall's context is stored under in the session — the part after _security. — or None for the firewall's own name
session_strategy migrate What a successful login does to the session it reattached: migrate rotates its ID keeping its attributes, invalidate empties it, none leaves it alone. Meaningful on a stateful firewall only
session_cookie None The SessionCookieConfig the session ID travels in — name, path, domain, secure, httponly, samesite, lifetime — or None for the default: xtr_session on /, HttpOnly, SameSite=Lax, not Secure. Meaningful on a stateful firewall only
provider None The user provider the firewall loads users from; with none here and none configured at all, an authenticator that needs one gets a MissingUserProvider that fails, naming the firewall, when first used — and with none here but others configured, one that needs one fails the build, naming the firewall. The provider may be a service of the request (lifetime="scoped"), such as a repository over the session of the request's unit of work: everything the firewall builds over it is built per request too, so one request's services all use that request's instance
user_checker None A user-checker service type, or the default in-memory checker; it may be a service of the request too, and one no service provides fails the build, naming the firewall
entry_point None The authenticator whose challenge answers an unauthenticated request
access_denied_handler None A handler for a denied, fully-authenticated caller
scope_denied_handler None A handler service type answering a caller whose token lacks a scope a rule asks for — wrapped by the bundle's WWW-Authenticate answer
authenticators () The authenticator configurations the firewall runs
required_badges () Badge types every passport must carry
csrf_route_markers False Whether the firewall's routes prove themselves with IsCsrfTokenValid markers — wiring the forgery-token manager for them even when no login or logout asks; the tokens travel in the session, so a stateless firewall declaring them fails the build
logout None The logout the firewall's requests can ask for — see below
switch_user None The switch-user block the firewall's callers switch by — see below
login_throttling None How the firewall's logins are counted and refused — see below
re_authentication_entry_point None A service type starting a fresh proof for an already-authenticated caller — handed to the firewall's exception listener the way the denial handlers are, so a recency refusal is answered with a fresh proof instead of the plain 403
listeners () The qualifiers of the firewall's own listener chain, each naming a listener aliased under FirewallListenerInterface; the sorting pass orders them with the steps the bundle parks

The matchers those fields build come from xtr-http-foundation, and each of them — request_matcher's callable included — reads the request as a message. pattern matches the path below the application's mount, with per-cent escapes undone; host is matched without regard to case.

The firewalls run as the firewall — a subscriber SecurityBundle registers over the kernel lifecycle's events, before routing — so the routes carry no firewall dependency of their own: each request runs the first firewall whose matcher claims it, authenticated once, and a route documents its security with the framework's own params.

Stateful firewalls

A stateful firewall (stateless=False) carries a context step at the head of its chain — the ContextListener restoring the token its session holds, reloading the user it carries through the firewall's provider, and writing the token back on the response — registered by the bundle under <firewall>#context_listener and parked ahead of the authentication step. The session itself is the application's: the SessionStorageInterface service it registered (an in-memory one for a single process, a cache-pool one for a shared backend) is what the listener builds the session from, and a stateful firewall with none registered fails the build naming the service — the bundle never builds one silently, and a firewall the application asked to be stateful cannot quietly run as a stateless one.

A successful login hands the session to the firewall's session_strategy — migrate by default, rotating the session's ID so a fixation stops answering for the account the login named — through a SessionStrategyListener on the firewall's own dispatcher.

The response side is wired with the request side: the context step's response half stores the token the request authenticated back into the session it reattached, and a SaveSessionListener on the kernel's response event writes that session through the storage and stages the cookie that carries its ID — a fresh session, or one a login rotated. The save runs below every other response listener, so the token is in the session before the session is written, and a storage that fails fails the request loudly rather than losing the session quietly; the finish event saves what a request that failed without producing a response still wrote. The listener is registered while any stateful firewall is configured and carries the same remove-if-missing marker over the application's session storage as the context step it serves.

The session ID travels in the firewall's session_cookie, SessionCookieConfig(name="sid", secure=True) for an application served only over HTTPS; the default is xtr_session on /, HttpOnly, SameSite=Lax and not Secure. The context step is the only place the firewall's session is built, so the login's rotation and the logout's invalidation stage the same cookie, under a new ID with the same path and domain.

What the session keeps

A session holds JSON and nothing else, whatever storage keeps it — the memory one as much as a cache pool — so the firewall stores what it keeps there as envelopes, never as objects:

  • The token is {"v": 1, "kind": …, "state": …, "user": …}: the token's class as module:QualifiedName, the state its own to_session answers — the roles fixed at the login, the attributes, the firewall, a switch's original nested the same way — and the user. A user implementing SessionSerializableUserInterface (from xtr_security_core) — InMemoryUser and OidcUser do — is kept whole, as its own state; any other user is kept as a snapshot of its identifier, its roles and the password_digest of its password — a crc32c checksum, never the hash.
  • The last authentication error a failed login redirects with is its public half: the class, the message key and the message data that survive JSON. The internal message never reaches the store, so on the page that renders the form again str(error) is the key.

On the next request the token is rebuilt and its user reloaded through the firewall's provider, and who is handed what is fixed:

  • A user kept whole is rebuilt as its own class and handed to refresh_user(user), as before.
  • A snapshot is rebuilt as a SessionUser stand-in — a PasswordSessionUser when the user carried a password — and reloaded through load_user_by_identifier(identifier). The stand-in never reaches refresh_user, so a provider that merges what it is handed into an identity map is never handed one. The reload is weighed against the snapshot as ever: a changed password digest, a role granted or withdrawn, another identifier logs the user out.
  • A rebuilt user is a snapshot of what the session held — a digest where the hash was — so a provider reloads it, never persists it.

Most users need nothing for this: the snapshot is reloaded by the identifier, the way a provider loads a user at login. Implement SessionSerializableUserInterface for a user its provider cannot load by identifier alone, the way OidcUser is rebuilt from the claims it kept. Inherit it explicitly — the class a session names is found again among the subclasses of the contract, by inheritance — keep password_digest(...) of a password, never the hash, and make from_session pure: no I/O, every field's type checked, InvalidArgumentError for a malformed state.

from collections.abc import Mapping
from typing import Self

from xtr_security_core import InvalidArgumentError, SessionSerializableUserInterface


class Member(SessionSerializableUserInterface):
    def __init__(self, email: str, roles: tuple[str, ...]) -> None:
        self.email = email
        self.roles = roles

    def get_user_identifier(self) -> str:
        return self.email

    def get_roles(self) -> tuple[str, ...]:
        return self.roles

    def to_session(self) -> Mapping[str, object]:
        return {"email": self.email, "roles": list(self.roles)}

    @classmethod
    def from_session(cls, state: Mapping[str, object]) -> Self:
        email, roles = state.get("email"), state.get("roles")
        if not isinstance(email, str) or not isinstance(roles, list):
            raise InvalidArgumentError("A member kept in a session is malformed.")
        return cls(email, tuple(str(role) for role in roles))

A token class of your own is kept only when it defines from_session in its own class body — the rebuild must know every field the class adds — and the response that would store a token the session cannot keep fails loudly, naming the class: a token class without its own from_session, an attribute that does not come back from JSON as it went in (a tuple, a set, an object), or a user whose to_session answers one. A bearer token presented on every request is never stored, and defines none.

Reading never trusts the session. A kind is looked up only among the classes the process has already loaded — never imported — and a value that is no envelope of a class it knows (an object a session held before, a corrupt value, another version, a malformed state) reads as no token: the request goes on anonymous, with a warning. An envelope keeping no user fails the request with InvalidArgumentError, and a rebuilt user no provider supports with UnsupportedUserError.

The session store is the trust boundary: nothing in it is signed or encrypted, so the token's attributes — the OIDC login's ID, access and refresh tokens among them — a self-issued token's compact form and the user's state sit in it as plaintext JSON. Keep the store where only the application reaches it.

The authenticator family

A firewall's authenticators tuple lists what proves its callers, each entry matched to a registered factory by the factory's config_type. The built-ins:

Configuration Key Entry point Proves the caller by Asks for
AccessTokenConfig access_token fallback — answers alone when no real challenge runs a bearer token, validated by its token_handler nothing: the handler builds the user; stateless
HttpBasicConfig http_basic real — the browser's credential prompt the Authorization: Basic header a user provider
FormLoginConfig form_login real — the redirect to the login page a submitted form a user provider, a stateful firewall
JsonLoginConfig json_login none a JSON document a user provider
OidcLoginConfig oidc_login real — the redirect to the provider an authorization-code flow a user provider, a stateful firewall, the oidc extra
RememberMeConfig remember_me none the cookie a login left a user provider; the persistent handler also a TokenProviderInterface service
LoginLinkConfig login_link none a signed link it mints a user provider
RemoteUserConfig remote_user none the account the server in front named a user provider
X509Config x509 none the client's certificate a user provider

The factories order the authenticators they build by priority: the access-token and the pre-authenticated ones at 100, the interactive logins at 0, the remember-me at -100 — a request presenting several proofs is read by the freshest kind first. The entry point resolves by kind: a configured entry_point name wins (naming one of the firewall's authenticators, or the build fails naming it); with none configured, a single authenticator answers regardless of kind, the one real kind answers when there is exactly one, a fallback answers alone when nothing real runs — and a firewall with several authenticators, an access rule that needs authentication and no resolvable entry point fails the build, naming entry_point. A third-party factory that does not answer entry_point_kind is read as never challenging, so it never takes the resolution over.

HTTP basic

An HttpBasicConfig builds the HTTP basic login: no page, no session — the browser's own Authorization: Basic header is the proof, and the 401 carrying WWW-Authenticate: Basic realm="…" is both a failed attempt's answer and the firewall's entry point. The realm defaults to Secured and must not be empty.

OIDC login

An OidcLoginConfig builds the authorization-code login — behind the oidc extra, with a user provider, on a firewall that reattaches a session: the login parks its pending attempts in one, so on a stateless firewall it fails at use with MissingSessionError, not at build. The provider is discovered from issuer, the client named by client_id authenticates at the token endpoint by token_endpoint_auth_method — one of none, client_secret_basic (the default), client_secret_post, client_secret_jwt, private_key_jwt, tls_client_auth, self_signed_tls_client_auth. A secret-bearing method needs client_secret and a method that sends none refuses one; private_key_jwt signs its assertion with client_authentication_keyset; the TLS pair presents the certificate carried in certificate_options. PKCE is on, S256 by default; the user is read from the userinfo endpoint — its sub bound to the ID token's — or from the id_token claims, by user_data_source; signature_verifier_algorithms verifies the ID token's signature against the provider's keys, and None reads its claims without verifying. The callback answers on check_path (/oidc/callback by default), scope adds to the always-asked openid, max_age bounds how old an authentication may be, and authorization_params carries extra parameters — the ones the flow manages, response_type through dpop_jkt, are guarded so no configuration can set them.

The provider is sent an absolute redirect_uri, the URL it matches against the ones registered for the client. Set redirect_uri to that URL — an absolute URL of check_path, checked at build — and it is sent as it is; left None, check_path is anchored at the scheme and host the request reached the application on. Configure it behind a proxy that terminates TLS, or wherever the Host header is not to be trusted: a forged host only yields a URL the provider has not registered, which it refuses, but the configured URL never depends on the request at all.

A callback that fails — a refusal the provider sent back, a state matching no pending attempt, an ID token that does not check out — is redirected to failure_path, an absolute path checked at build. Left None, it goes to the failure handler's default login page, /login: an application that signs in with OIDC alone names a page of its own there.

Every request the login sends the provider — the discovery, the code exchange, the userinfo and the key fetch — goes through one HTTP client, a service of its own: HttpClientInterface qualified <firewall>#oidc_http_client, an HttpxHttpClient with a 10-second timeout by default, built on first use. Override that one service to serve the provider from a test, or to tune the client.

Three sub-blocks ride on the login. token_generator (OidcTokenGeneratorConfig) mints this application's own tokens through the security:oidc:generate-token command — see below. backchannel_logout and end_session wire the provider-pushed logout, documented under The OIDC back channel. And a token-refresh listener joins the firewall's chain, ordered after the context step, renewing the access token of a login whose expiry falls within the refresher's leeway — a refresh the provider no longer honors clears the token, so the request goes on anonymous.

Remember me

A RememberMeConfig builds the remember-me login: a request presenting the cookie a previous login left is logged back in, lazily — the factory's priority -100 puts it behind the interactive authenticators, so a fresher proof always wins. handler picks how the cookie is held: signature signs the value over the user's covered properties, so a changed password retires every cookie; persistent keeps a series per cookie through the application's TokenProviderInterface service, named by qualifier in token_provider — refused by name at wiring when the persistent handler is asked for without one. The cookie's shape — name (REMEMBERME), lifetime (a year), path, domain, secure, httponly, samesite — and the ask — always_remember_me, or the request's remember_me_parameter (_remember_me) — are the configuration's own fields; signature_properties names the user properties whose digest a persisted value carries (the password by default). The secret the signature rides on is a configuration field, read from the environment the way Secrets shows — never generated. On the firewall's dispatcher, a subscriber asks a successful login whether it asked to be remembered (at -32), and the cookie is set behind it (at -64) and cleared on a failed login, a logout or a deauthentication (at 0) by listeners resolved per call, since the handler they go through holds the firewall's provider; one response listener on the main dispatcher moves the staged cookie onto the response. The handler itself is a service of the request — SignatureRememberMeHandler or PersistentRememberMeHandler, qualified <firewall>#remember_me_handler — addressed with Target from a route, or any callable the container fills, wherever a cookie is minted or cleared by hand.

A LoginLinkConfig builds the login-link authenticator: a link minted through the firewall's own handler service signs its user in when followed. The handler — LoginLinkHandlerInterface, qualified <firewall>#login_link_handler — is what an application mints through: path is the literal path every minted link leads to and check_path the literal path a followed link arrives at, both required; lifetime counts 600 seconds by default; check_post_only demands a POST of the follow; signature_properties (the password by default) retires every link of a user when any of them changes. The secret the hash is signed with is a configuration field, read from the environment the way Secrets shows — never generated. The success and failure handlers follow the form login's pattern — the default pair, or the application's own named by service type.

Login throttling

A firewall's login_throttling block counts its login attempts: global_limit per global_interval from one client address, local_limit per local_interval from one account at one address — five per fifteen minutes each by default — the global count surviving any one account's success, so one client may not farm a whole directory. The counts live in the application's StorageInterface service (from xtr-rate-limiter), the same storage every other limiter of the application counts in, and the keys are HMAC prefixes over the block's secret, so a shared store keeps no readable account or address — the secret a configuration field, read from the environment the way Secrets shows, never generated. The listener runs on the firewall's dispatcher at 2080, ahead of the provider's 2048 — a request already over the limit is refused before any user is loaded or any password verified.

Switch user

A firewall's switch_user block parks the switch step on its chain, ordered after the manager's own through the step's FirewallListenerOrder declaration: a caller holding the block's role (ROLE_ALLOWED_TO_SWITCH by default, weighed against the target user as the subject) becomes another user by carrying parameter (_switch_user) — on any page the firewall claims, or on the dedicated path — and steps back out with the same parameter carrying _exit. enable_csrf asks for a forgery token under csrf_parameter and csrf_token_id (switch_user), refused on a stateless firewall, which has no session to keep the tokens in. One scoped ImpersonateUrlGenerator service renders the addresses a page switches by — the impersonation and exit paths, URLs and forms — reading the request's firewall's block through a lookup built from the firewall map.

The bundle hands the step the firewall's own dispatcher, so the SwitchUserEvent it announces — before a switch settles, and before an exit restores the original token — reaches the listeners of firewall_dispatcher_name(firewall) beside the firewall's other events.

Pre-authenticated

RemoteUserConfig and X509Config build the pre-authenticated logins, tagged apart by their type field: one reads the account the server in front wrote under user_key (REMOTE_USER by default), the other the certificate the server verified — the email under user_key (SSL_CLIENT_S_DN_Email), or the configured identifier out of the distinguished name under credentials_key when there is no email. Both need a user provider and both run at priority 100; neither answers a challenge, so a request they cannot read goes on anonymous to the next authenticator.

Form login

A FormLoginConfig builds the form login: the form rendered at login_path, submitted to check_path — a POST there, its fields read by the names the form gives them (username_parameter, password_parameter), a form content type demanded when form_only is set. A failed login stores its error on the session and redirects back to the page; a successful one is answered by the target ladder — the default pair of handlers, or the application's own pair, named by service type in success_handler and failure_handler, answered through the bundle's wrappers. The redirect to the login page is a real entry point: an unauthenticated request is sent there to prove itself.

The login is stateful — its errors travel in the session, its success rotates it — so it is refused on a stateless firewall, where it could only ever answer the one request that submitted it. It needs the firewall's user provider.

JSON login

A JsonLoginConfig builds the JSON login: the request's parsed body read by the dotted paths username_path and password_path, the path it is submitted to named by check_path — or None for every request carrying a JSON body. The login is stateless and never challenges: a failed login is answered with a plain 401 carrying the error's message, or the application's own handlers when success_handler and failure_handler name them. A firewall whose only login is this one resolves its entry point elsewhere.

Cross-site request forgery

The forgery machinery is opt-in: it is wired when a firewall's configuration asks for a token — a form login with enable_csrf, a logout with enable_csrf or clear_csrf_tokens, a switch_user block with enable_csrf — and nothing registers without an ask. A firewall whose routes prove themselves with IsCsrfTokenValid markers asks the same way, with csrf_route_markers — the marker's checker answers through the manager, so the declaration wires it; the tokens travel in the session the request reattached, so a stateless firewall declaring them fails the build. The bundle then builds the csrf package's manager over the session the request reattached, as the application's one CsrfTokenManagerInterface service: the route marker's checker survives on its arrival, and the passport check settles the badge a form login mints, ahead of the credential check, at the priority the landed listener declares. The tokens themselves travel in the session — the storage reads it anew on every call, so the machinery works whatever moment its services are built in — and a migration empties them with the session it rotates.

Logout

A firewall with a LogoutConfig carries a logout step on its context — the request asking for the configured path is logged out, its token cleared — and the logout event it announces is answered on the firewall's own dispatcher by the listeners the configuration turns on: the default redirect to target_path, the Clear-Site-Data header, the configured cookies cleared, and the session invalidated on a stateful firewall. One LogoutUrlGenerator service carries every firewall's registration, so whatever renders a page asks for a logout's address by the firewall's name — or with none, resolved over the current request's token, or over the firewall the request runs under: the bundle names the matched firewall on the generator per request, so an anonymous page under a firewall with a logout renders that logout's address too. The generator is scoped to the request, so what one request named never answers for the next.

The cross-site request forgery checks a logout can ask for are wired with the machinery above: enable_csrf has the step prove the request with the manager before it logs out, and clear_csrf_tokens drops every token the request's session minted on the logout event. Both need the session the tokens are stored in, so a stateless firewall asking for either fails the build saying so.

The OIDC back channel

An OIDC login can carry a backchannel_logout and an end_session block. The end-session listener joins the firewall's own logout listeners, redirecting the application's logout to the provider's end-session endpoint. The back-channel logout records the sessions the provider says have ended, into the CacheItemPoolInterface service the application registered — a pool shared by every server, never one the bundle builds — and refuses the logins they name through a listener on the refreshed-user check.

The route the provider pushes its logout tokens to is the application's to map: the bundle registers an OidcBackChannelLogoutHandler service, qualified by the firewall's name, and the application serves it at the path it configured as the block's route:

from typing import Annotated
from fastapi import Form
from xtr_dependency_injection import Target
from xtr_http_kernel.bridge import Response

from xtr_security import OidcBackChannelLogoutHandler


@app.post("/logout/backchannel")
async def backchannel_logout(
    logout_token: Annotated[str | None, Form()] = None,
    answer: Annotated[OidcBackChannelLogoutHandler, Target("main")] = None,
) -> Response:
    return await answer(logout_token)

The endpoint is public and unauthenticated by design — the request comes from the provider, carrying nothing of the browser that logged in — and a refusal answers the bare 400 with no detail: the reason is the verifier's to name in the log, not the caller's to read.

Firewall listeners

A firewall's listener chain — steps implementing the HTTP edge's FirewallListenerInterface, each declaring its get_priority() — is put in running order by the bundle's SortFirewallListenersPass: higher priority first, the gathering order for listeners that share one, and a listener's @FirewallListenerOrder(before=..., after=...) declaration settling how it stands against its neighbours within a shared priority — a constraint that would cross a priority fails the build, naming the firewall.

Every secured firewall's chain carries its own authentication step — the AuthenticatorManagerListener running that firewall's authenticator manager — registered by the bundle under firewall_manager_listener_name(firewall) and parked ahead of the listeners the listeners configuration names, so no application names it itself; a @FirewallListenerOrder constraint addresses it by that qualifier to stand against it. When the event dispatcher bundle traces, MakeFirewallsManagerListenerTraceablePass swaps the step for the traceable variant, so a traced firewall's chain explains its authentication.

The chain carries the firewall's access step the same way: an AccessListener over the request's token storage, the decision manager and the firewall's own access map, registered under firewall_access_listener_name(firewall) and ordered by its -255 priority after the authentication step.

Token handlers

An access-token authenticator (AccessTokenConfig) names a token_handler the bundle builds through a factory matched by its type:

Configuration Key Verifies
ServiceTokenHandlerConfig(service) id A handler the application registered as a service
Oauth2TokenHandlerConfig(introspection_base_uri, …) oauth2 A token by introspecting it with its authorization server (RFC 7662)
OidcTokenHandlerConfig(issuers, audience, …) oidc A third-party OIDC issuer's tokens (needs the oidc extra)
OidcUserInfoTokenHandlerConfig(userinfo_base_uri, …) oidc_user_info A token by presenting it to the issuer's userinfo endpoint (needs the oidc extra)

OidcTokenHandlerConfig takes exactly one key source — keyset (a JWKS document), discovery_uri (an issuer base URI the jwks_uri is discovered from) or jwks_uri — plus the issuers and audience a valid token must carry; algorithms default to ("RS256",), claim to "sub". A discovery_uri or jwks_uri handler fetches through an HttpClientInterface registered beside it, qualified <firewall>_oidc#http_client; override it as the login's client is.

Oauth2TokenHandlerConfig reaches the introspection endpoint through a scoped client over introspection_base_uri with this resource server's credentials, or through the client service the application registered; audiences and issuer are checked only when given, a cache service keeps active responses for cache_ttl seconds, and signed_response_algorithms asks for the response as a signed JWT — verified against signed_response_keyset or against the keys the issuer's metadata publishes, read through the signed_response_discovery_cache service (which needs issuer). A signed response needs the oidc extra, as the handler's own section in xtr-security-http notes. OidcUserInfoTokenHandlerConfig reads the endpoint from userinfo_base_uri — or from the issuer's discovery document through the discovery_cache service, kept under discovery_cache_key — and the identifier from claim (sub by default).

Access control

AccessControlConfig is a request pattern and the one attribute a matching request must hold — a role, "IS_AUTHENTICATED", "PUBLIC_ACCESS", or an OAUTH2_SCOPE(...) string. Rules are tried in order, so a narrow ^/api/admin rule comes before the broad ^/api. path matches below the application's mount with per-cent escapes undone, host without regard to case; an ips entry is an address or a network, written in CIDR or netmask form.

A rule may also name a channel — "https" or "http" — the request must arrive over; a matching request arriving over the wrong one is not decided at all but redirected, by the channel step below.

The channel

A firewall whose access rules carry a channel parks the channel step first on its chain — ahead of the context step and the manager's own, so nothing a request carries is restored, authenticated or decided before it arrives the way the rule demands. The step answers a request arriving over the wrong scheme with a 301 to the same request over the demanded one: the host, path and query kept, the target scheme's port spelled out from the configuration's http_port/https_port when it is not the scheme's default. The scheme a request is read by is its URI's own — there is no trusted-proxy machinery to weigh a forwarded header — so an application behind a proxy that terminates the encryption reads plain http here; a rule with no channel parks no step.

Secrets

Three configurations sign or derive with a secret: the remember-me cookie (secret), the login link (secret) and the login throttling (secret). Each is a plain configuration field, so the application's own configure reads it from the environment the way every other setting of the application is read:

from xtr_dependency_injection import configure, env
from xtr_security.bundle import FirewallConfig, FormLoginConfig, RememberMeConfig, SecurityConfig


@configure
def security() -> SecurityConfig:
    return SecurityConfig(
        firewalls={
            "main": FirewallConfig(
                stateless=False,
                authenticators=(
                    FormLoginConfig(login_path="/login"),
                    RememberMeConfig(secret=env("REMEMBER_ME_SECRET")),
                ),
            ),
        },
    )

The bundle never mints one: it builds and boots without any of them — the console still runs, so a secret can be generated or inspected — and the service that needs one fails the first time it is asked for, naming the setting: the login-link handler refusing secret on the login-link configuration, the throttling listener refusing secret on the login-throttling configuration, the remember-me handler the same on the remember-me configuration. An empty value reads as no secret at all.

Voters

The decision manager gathers every voter: the built-in role-hierarchy, authenticated, OAuth2 scope and closure voters, and every application voter — a class implementing VoterInterface, autoconfigured with the security.voter tag. When trace_votes is on, each is wrapped so its answer is announced as a VoteEvent, and AccessDecisionManagerInterface is a TraceableAccessDecisionManager built per request: it logs every decision, with the votes the bundle's VoteEvent listener feeds it, readable from get_decision_log() until the request ends.

Extending

A third-party bundle adds a kind of authenticator, token handler or user provider by prepending its factory onto the security config from its prepend_extension hook — the seam an OAuth2 server plugs into:

from xtr_dependency_injection import Bundle, as_bundle, required_bundle
from xtr_security.bundle import add_authenticator_factory, add_token_handler_factory
from xtr_security.bundle import SecurityBundle


@required_bundle(SecurityBundle)
@as_bundle("oauth2")
class OAuth2Bundle(Bundle):
    def prepend_extension(self, builder) -> None:
        builder.prepend_extension_config("security", add_authenticator_factory(OAuth2Factory()))
        builder.prepend_extension_config(
            "security", add_token_handler_factory(IntrospectionFactory())
        )

An AuthenticatorFactoryInterface carries a key, a priority, a config_type and create_authenticator(...); a firewall lists an instance of the factory's config_type under its authenticators, and the bundle matches it to the factory. TokenHandlerFactoryInterface and UserProviderFactoryInterface are the same shape for the other two registries. A factory whose authenticator can settle on a user without a provider — as the access-token one can, its handler building the user — inherits StatelessAuthenticatorFactoryInterface, and is handed no provider rather than a MissingUserProvider when the application configures none.

Use in an application

Everything adding this package to an application on xtr-dependency-injection takes — and, read backwards, what removing it undoes.

  • Install — uv add xtr-security; install xtr-console beside it for debug:firewall and security:hash-password — and security:oidc:generate-token when a firewall's OIDC login mints.
  • Recipe — uv run xtr-recipes recipes:sync does the Activate and Configure steps below: it lists SecurityBundle, which brings the event dispatcher and http-kernel bundles with it, and writes <app>/config/packages/security.py with the bundle's own defaults. There is no environment or ignore line to write; it prints the concurrent_scoped_access=True, setup(app, kernel) and firewall steps, which a recipe cannot make for you.
  • Activate — SecurityBundle: {"all": True} in BUNDLES in <app>/config/bundles.py, imported from xtr_security.bundle. Then call setup(app, kernel) where the application is built, and build the kernel with concurrent_scoped_access=True so concurrent requests keep their own token storage.
  • Brings along — the event dispatcher and http-kernel bundles always, because the firewalls dispatch through the one and answer on the other's exception event; the clock bundle, installed with the security core, whose clock the trust resolver measures recent authentication with; the logging and console bundles whenever those packages are installed.
  • Configure — the recipe writes <app>/config/packages/security.py holding the defaults: no firewall yet, and the affirmative strategy. Changing what its @configure function returns changes that — see Configure and Kernel / bundle.
  • Environment — nothing the recipe writes; an application reads its own secrets through env(...) in its configuration — the remember-me, login-link and throttling secret fields, as Secrets shows.
  • Ignore — nothing.
  • Remove — drop the BUNDLES entry; uv run xtr-recipes recipes:remove xtr-security deletes <app>/config/packages/security.py, unless you edited it, in which case it is moved aside to security.py.removed. Then uv remove xtr-security.
  • Check — debug:bundles shows security as listed and active, event_dispatcher, http_kernel and clock as required; debug:firewall lists the configured firewalls.

Kernel / bundle

# app/config/bundles.py
from xtr_security.bundle import SecurityBundle

BUNDLES = {SecurityBundle: {"all": True}}

SecurityBundle registers the token storage (scoped), the trust resolver over the clock bundle's clock, the role hierarchy, the voters and the decision manager (traceable per request when trace_votes is on), the authorization checker — also under UserAuthorizationCheckerInterface and GuestAuthorizationCheckerInterface — and the Security facade (both scoped), the password hasher factory and the user hasher, the user providers, and — per firewall — its own event dispatcher with the login listeners, its authenticators, its access map and its entry point, gathered into a FirewallMap. The bundle also registers the firewall itself — a subscriber over the kernel lifecycle's events, one listener per event, resolving the map per call from the request's scope — so every request the configuration's firewalls claim is authenticated before routing. A firewall's listeners configuration names the qualifiers of its listener chain; the bundle parks them on the firewall's context definition, where SortFirewallListenersPass orders them, and the context carries the ordered chain — with the firewall's own exception listener, built per firewall from its name, its entry point and its handlers, and, while the firewall configures none, no logout listener — so await firewall_map.get_listeners(message) answers the matched firewall's (chain, exception_listener, logout_listener). The exception listener turns a security error into a response on the http-kernel lifecycle, answering a request's failure the way the firewall that ran it would; a request no firewall matched is the kernel's to answer. Its zero-config path builds and boots with no configuration and touches no I/O until a request arrives.

Each firewall dispatches its security events — CheckPassportEvent, AuthenticationTokenCreatedEvent, AuthenticationSuccessEvent, InteractiveLoginEvent, LoginSuccessEvent, LoginFailureEvent, CheckRefreshedUserEvent, TokenDeauthenticatedEvent, SwitchUserEvent, LogoutEvent, OidcAuthorizationRequestEvent — on a dispatcher of its own, named by firewall_dispatcher_name(firewall). A listener of those events on the main dispatcher hears every firewall (RegisterGlobalSecurityEventListenersPass copies it onto each); one naming a firewall's dispatcher hears that firewall alone:

from xtr_event_dispatcher import as_event_listener
from xtr_security.bundle import firewall_dispatcher_name


@as_event_listener()  # every firewall
def audit_login(event: LoginSuccessEvent) -> None: ...


@as_event_listener(dispatcher=firewall_dispatcher_name("api"))  # the api firewall alone
def count_api_login(event: LoginSuccessEvent) -> None: ...

In debug mode MakeFirewallsEventDispatcherTraceablePass traces every firewall's dispatcher, as the event dispatcher bundle traces its own; debug:event-dispatcher --dispatcher security.event_dispatcher.api lists one firewall's listeners.

With a console bundle active it also registers debug:firewall [name], which lists the configured firewalls or describes one, and security:hash-password, which hashes a password with the configured factory. A firewall whose OIDC login carries a token_generator block adds a third: security:oidc:generate-token <user-identifier> mints a token through that firewall's generator — --firewall naming which when several mint, --algorithm and --issuer the choice when several are declared, --ttl and --not-before the token's lifetime and start — printed bare, ready to be presented. The command is registered only under both gates: a console active, and at least one firewall minting.

Errors

Everything the family raises derives from SecurityError (from xtr-security-core); this package adds one.

Error Raised when
InvalidConfigurationError A security configuration the bundle cannot turn into services — an unknown provider, a secured firewall with no authenticator, an authenticator with no factory, an entry point that resolves to nothing or names no authenticator of the firewall, a stateful firewall with no SessionStorageInterface registered, a form login or declared route markers on a stateless firewall, a back-channel logout on a stateless firewall, a switch asking for a forgery proof on a stateless firewall; also a ValueError

Layout

xtr_security/
├── security.py                the Security facade
├── firewall_config.py         FirewallConfig, the firewall an application writes
├── logout_config.py           LogoutConfig, the logout a firewall's requests ask for
├── login_throttling_config.py LoginThrottlingConfig, the counting a firewall's logins are refused by
├── switch_user_config.py      SwitchUserConfig, the switch a firewall's callers ask for
├── oidc_back_channel_logout_handler.py  answers the route a provider pushes logout tokens to
├── exception/                 InvalidConfigurationError
├── command/                   debug:firewall
├── factory/                   authenticator factory interface + the built-in factories,
│                              with add_authenticator_factory
├── access_token/              token-handler factory interface + built-ins,
│                              with add_token_handler_factory
├── user_provider/             user-provider factory interface + built-ins,
│                              with add_user_provider_factory
└── bundle/
    ├── security_bundle.py     SecurityBundle
    ├── security_config.py      SecurityConfig
    ├── firewall_context.py    FirewallContext, one firewall's runtime pieces (internal)
    ├── firewall_manager_listener_name.py  the qualifier of a firewall's manager listener
    ├── make_firewalls_manager_listener_traceable_pass.py  traces the manager listeners
    ├── refuse_stateful_firewalls_without_session_storage_pass.py  names the missing storage
    ├── register_per_call_listeners_pass.py  parks the request and wires the per-call listeners
    ├── sort_firewall_listeners_pass.py  orders each firewall's listener chain
    └── *_configs.py           the configs an application writes, incl. password_hasher_configs

Development

Developed in the python-xtr monorepo, under packages/xtr-security; run the commands below from there. The python-xtr-security repository is a read-only copy, so send issues and pull requests to the monorepo.

uv sync --all-packages --all-extras
uv run ruff check && uv run ruff format --check && uv run basedpyright && uv run ty check && uv run pytest --cov

License

MIT — see LICENSE.

Metadata

Release files for xtr-security 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 6.6.0
File Size Uploaded Provenance Actions
xtr_security-6.6.0.tar.gz 165.6 kB With provenance Details for xtr_security-6.6.0.tar.gz

Built distribution (wheel)

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

Total release size: 370.0 kB

Release files / xtr_security-6.6.0.tar.gz

Download URL xtr_security-6.6.0.tar.gz
Size 165.6 kB
Tags Source
SHA-256 checksum
How to use checksums
afc74816dc30a83c49af98cea893c785c7e2b6e2af7a62a6118a4aa22b582ccf
BLAKE2b-256 checksum
How to use checksums
79d4fc3fa6939d977012dafe83ac8eb2d36e2487741b05444c437b4d777a372c
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-6.6.0-py3-none-any.whl

Download URL xtr_security-6.6.0-py3-none-any.whl
Size 204.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2c4ef9db2c4e36c6ced384c8237c40fdb65b798aa1275d6b062b26b660b6f2ff
BLAKE2b-256 checksum
How to use checksums
6a81feafd431458bb881090b1c2cfd14089f22c0a418881a6ecf2fcc3374d08c
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 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-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