orionis.auth.guards.SessionGuard

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 SessionGuard(ISessionGuard): (source)

Constructor: SessionGuard(app, identities)

View In Hierarchy

Resolve the identity of web requests from the HTTP session.

The guard never implements its own session storage: it reads and writes the session started by StartSessionMiddleware and reachable through request.state.session.

Concurrency

The guard is stateless and safe as a singleton. All per request state lives in the session object owned by the request itself.

Static Method	`__session`	Return the session attached to a request, when present.
Method	`__init__`	Initialise the guard from the authentication configuration.
Async Method	`__restoreRemembered`	Restore an identity from a persistent credential.
Async Method	`attempt`	Validate credentials and start an authenticated session.
Method	`login`	Persist an identity in the session of the current request.
Async Method	`logout`	Drop the authenticated state from the session.
Async Method	`resolve`	Resolve the identity remembered in the session.
Class Variable	`__slots__`	Undocumented
Instance Variable	`__csrf_key`	Undocumented
Instance Variable	`__csrf_length`	Undocumented
Instance Variable	`__identities`	Undocumented
Instance Variable	`__password_key`	Undocumented
Instance Variable	`__remember`	Undocumented
Instance Variable	`__session_key`	Undocumented
Property	`name`	Return the configuration name of this guard.

@staticmethod

def __session(request: Request) -> ISession | None: (source) ¶

Return the session attached to a request, when present.

Parameters
request:`Request`	Incoming HTTP request.

Returns
`ISession \| None`	Session started by the web pipeline, or `None` for routes that do not start one.

def __init__(self, app: IApplication, identities: IIdentityProvider): (source) ¶

Initialise the guard from the authentication configuration.

Parameters
app:`IApplication`	Application exposing the `auth.session` configuration.
identities:`IIdentityProvider`	Provider turning a stored identifier into an identity.

Returns
`None`	Only the session key and the provider are retained.

async def __restoreRemembered(self, request: Request) -> GuardResult | None: (source) ¶

Restore an identity from a persistent credential.

Parameters
request:`Request`	Incoming request carrying the remember-me credential.

Returns
`GuardResult \| None`	Authenticated session result, or `None` if restoration fails.

async def attempt(self, request: Request, credentials: Mapping[str, object], *, remember: bool = False) -> IAuthenticatable | None: (source) ¶

Validate credentials and start an authenticated session.

Parameters
request:`Request`	Incoming HTTP request owning the session.
credentials:`Mapping[str, object]`	Submitted credentials.
remember:`bool, optional`	Persist a revocable login credential after password verification.

Returns
`IAuthenticatable \| None`	Authenticated identity, or `None` when the credentials do not match. The answer never reveals whether the account exists or the password was wrong.

def login(self, request: Request, identity: IAuthenticatable): (source) ¶

Persist an identity in the session of the current request.

Parameters
request:`Request`	Incoming HTTP request owning the session.
identity:`IAuthenticatable`	Identity to remember for subsequent requests.

Returns
`None`	The session is mutated as a side effect.

Raises
`AuthException`	When the request has no session, which means the route is not part of the web pipeline, or the identity has no persisted key.

async def logout(self, request: Request): (source) ¶

Drop the authenticated state from the session.

Parameters
request:`Request`	Incoming HTTP request owning the session.

Returns
`None`	The persistent credential is revoked before invalidating the session and clearing both cookies through the web pipeline.

async def resolve(self, request: Request) -> GuardResult | None: (source) ¶

Resolve the identity remembered in the session.

A session pointing at an identity that no longer exists is cleaned up so the next request starts as a guest.

Parameters
request:`Request`	Incoming HTTP request.

Returns
`GuardResult \| None`	Resolved identity, or `None` when the request is anonymous.

__slots__: tuple[str, ...] = (source) ¶

Undocumented

__csrf_key: str = (source) ¶

Undocumented

__csrf_length: int = (source) ¶

Undocumented

__identities = (source) ¶

Undocumented

__password_key: str = (source) ¶

Undocumented

__remember = (source) ¶

Undocumented

__session_key: str = (source) ¶

Undocumented

@property

name: str = (source) ¶

Return the configuration name of this guard.

Returns
`str`	Always `"session"`.