orionis.foundation.config.http.HTTPCsrf

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

Explore modules View classes

class documentation

class HTTPCsrf(BaseEntity): (source)

View In Hierarchy

CSRF protection configuration for web routes.

Method	`__post_init__`	Validate all CSRF configuration fields after dataclass construction.
Method	`__validateCookieDomain`	Validate that `cookie_domain` is a string or `None`.
Method	`__validateCookieName`	Validate that `cookie_name` is acceptable by the response cookie serializer.
Method	`__validateCookiePath`	Validate that `cookie_path` is a string.
Method	`__validateCookieSameSite`	Validate that `cookie_same_site` is a recognised SameSite value.
Method	`__validateEnabled`	Validate that `enabled` is a boolean.
Method	`__validateSessionKey`	Validate that `session_key` is a non-empty string.
Method	`__validateTokenLength`	Validate that `token_length` is a plain integer >= 32.
Method	`__validateXsrfCookie`	Validate that `xsrf_cookie` is a boolean.
Instance Variable	`cookie_domain`	`Domain` attribute for the XSRF cookie. `None` omits it. Defaults to `None`.
Instance Variable	`cookie_name`	Name of the XSRF cookie. Defaults to `"XSRF-TOKEN"`.
Instance Variable	`cookie_path`	`Path` attribute for the XSRF cookie. Defaults to `"/"`.
Instance Variable	`cookie_same_site`	`SameSite` attribute for the XSRF cookie. Defaults to `"lax"`.
Instance Variable	`cookie_secure`	Set the `Secure` attribute on the XSRF cookie. When `False`, the middleware automatically promotes the flag to `True` on HTTPS requests. Defaults to `False`.
Instance Variable	`enabled`	Enable or disable CSRF validation globally. Defaults to `True`.
Instance Variable	`session_key`	Session key under which the token is stored. Defaults to `"_csrf_token"`.
Instance Variable	`token_length`	Number of random bytes used to generate the token via `secrets.token_urlsafe`. 32 bytes yields 256 bits of entropy (43 URL-safe characters). Defaults to `32`.
Instance Variable	`xsrf_cookie`	When `True`, set a readable `XSRF-TOKEN` cookie on every response so that JavaScript clients (Angular, Axios) can forward it as `X-XSRF-Token`. Defaults to `False`.

Inherited from BaseEntity:

Class Method	`_cachedFieldMetadata`	Retrieve field definitions and normalized types cached by class.
Method	`getFields`	Describe field names, normalized types, defaults, and metadata.
Method	`toDict`	Convert the dataclass instance to a recursively copied dictionary.
Class Variable	`__slots__`	Undocumented

def __post_init__(self): (source) ¶

overrides orionis.support.entities.BaseEntity.__post_init__

Validate all CSRF configuration fields after dataclass construction.

Returns
`None`	No value is returned; validation runs as a side effect.

Raises
`TypeError`	If any field has an unexpected type.
`ValueError`	If `token_length` is below the minimum secure threshold or any string field is empty or otherwise invalid.

def __validateCookieDomain(self): (source) ¶

Validate that cookie_domain is a string or None.

Returns
`None`	No value is returned; raises on invalid input.

Raises
`TypeError`	If `cookie_domain` is neither a `str` nor `None`.

def __validateCookieName(self): (source) ¶

Validate that cookie_name is acceptable by the response cookie serializer.

Returns
`None`	No value is returned; raises on invalid input.

Raises
`ValueError`	If `cookie_name` is not valid.

def __validateCookiePath(self): (source) ¶

Validate that cookie_path is a string.

Returns
`None`	No value is returned; raises on invalid input.

Raises
`TypeError`	If `cookie_path` is not a `str` instance.

def __validateCookieSameSite(self): (source) ¶

Validate that cookie_same_site is a recognised SameSite value.

Returns
`None`	No value is returned; raises on invalid input.

Raises
`ValueError`	If `cookie_same_site` is not one of `"lax"`, `"strict"`, or `"none"`.

def __validateEnabled(self): (source) ¶

Validate that enabled is a boolean.

Returns
`None`	No value is returned; raises on invalid input.

Raises
`TypeError`	If `enabled` is not a `bool` instance.

def __validateSessionKey(self): (source) ¶

Validate that session_key is a non-empty string.

Returns
`None`	No value is returned; raises on invalid input.

Raises
`ValueError`	If `session_key` is not a string or is an empty string.

def __validateTokenLength(self): (source) ¶

Validate that token_length is a plain integer >= 32.

Returns
`None`	No value is returned; raises on invalid input.

Raises
`TypeError`	If `token_length` is not a plain `int` (`bool` subclass is excluded).
`ValueError`	If `token_length` is below 32 (minimum 256 bits of entropy).

def __validateXsrfCookie(self): (source) ¶

Validate that xsrf_cookie is a boolean.

Returns
`None`	No value is returned; raises on invalid input.

Raises
`TypeError`	If `xsrf_cookie` is not a `bool` instance.

cookie_domain: str | None = (source) ¶

Domain attribute for the XSRF cookie. None omits it. Defaults to None.

cookie_name: str = (source) ¶

Name of the XSRF cookie. Defaults to "XSRF-TOKEN".

cookie_path: str = (source) ¶

Path attribute for the XSRF cookie. Defaults to "/".

cookie_same_site: Literal["lax", "strict", "none"] = (source) ¶

SameSite attribute for the XSRF cookie. Defaults to "lax".

cookie_secure: bool = (source) ¶

Set the Secure attribute on the XSRF cookie. When False, the middleware automatically promotes the flag to True on HTTPS requests. Defaults to False.

enabled: bool = (source) ¶

Enable or disable CSRF validation globally. Defaults to True.

session_key: str = (source) ¶

Session key under which the token is stored. Defaults to "_csrf_token".

token_length: int = (source) ¶

Number of random bytes used to generate the token via secrets.token_urlsafe. 32 bytes yields 256 bits of entropy (43 URL-safe characters). Defaults to 32.

xsrf_cookie: bool = (source) ¶

When True, set a readable XSRF-TOKEN cookie on every response so that JavaScript clients (Angular, Axios) can forward it as X-XSRF-Token. Defaults to False.