pywry.state.auth

Authentication, session management, and role-based access control (RBAC).

---

Configuration

pywry.state.auth.AuthConfig dataclass

AuthConfig(enabled: bool = False, session_cookie: str = 'pywry_session', auth_header: str = 'Authorization', token_secret: str = '', session_ttl: int = 86400, require_auth_for_widgets: bool = False)

Authentication configuration.

ATTRIBUTE	DESCRIPTION
enabled	Whether authentication is enabled. TYPE: bool
session_cookie	Name of the session cookie. TYPE: str
auth_header	HTTP header for bearer token authentication. TYPE: str
token_secret	Secret key for token signing. TYPE: str
session_ttl	Session TTL in seconds. TYPE: int
require_auth_for_widgets	Whether widgets require authentication to view. TYPE: bool

---

Session Tokens

pywry.state.auth.generate_session_token

generate_session_token(user_id: str, secret: str, expires_at: float | None = None) -> str

Generate a signed session token.

PARAMETER	DESCRIPTION
user_id	The user ID. TYPE: str
secret	Secret key for signing. TYPE: str
expires_at	Expiration timestamp. If None, token doesn't expire. TYPE: float or None DEFAULT: None

RETURNS	DESCRIPTION
str	Signed session token.

pywry.state.auth.validate_session_token

validate_session_token(token: str, secret: str) -> tuple[bool, str | None, str | None]

Validate a session token and extract user ID.

PARAMETER	DESCRIPTION
token	The session token. TYPE: str
secret	Secret key for verification. TYPE: str

RETURNS	DESCRIPTION
tuple[bool, str | None, str | None]	(is_valid, user_id, error_message)

---

Widget Tokens

pywry.state.auth.generate_widget_token

generate_widget_token(widget_id: str, secret: str, ttl: int = 300) -> str

Generate a short-lived token for widget authentication.

PARAMETER	DESCRIPTION
widget_id	The widget ID. TYPE: str
secret	Secret key for signing. TYPE: str
ttl	Token TTL in seconds. TYPE: int DEFAULT: 300

RETURNS	DESCRIPTION
str	Signed widget token.

pywry.state.auth.validate_widget_token

validate_widget_token(token: str, widget_id: str, secret: str) -> bool

Validate a widget authentication token.

PARAMETER	DESCRIPTION
token	The widget token. TYPE: str
widget_id	Expected widget ID. TYPE: str
secret	Secret key for verification. TYPE: str

RETURNS	DESCRIPTION
bool	True if token is valid for this widget.

---

RBAC

pywry.state.auth.get_role_permissions

get_role_permissions(role: str) -> set[str]

Get permissions for a role.

PARAMETER	DESCRIPTION
role	The role name. TYPE: str

RETURNS	DESCRIPTION
set[str]	Set of permissions for this role.

pywry.state.auth.has_permission

has_permission(session: UserSession | None, permission: str) -> bool

Check if a session has a specific permission via roles.

PARAMETER	DESCRIPTION
session	The user session. TYPE: UserSession or None
permission	The required permission. TYPE: str

RETURNS	DESCRIPTION
bool	True if the session has the permission.

pywry.state.auth.is_admin

is_admin(session: UserSession | None) -> bool

Check if a session has admin role.

PARAMETER	DESCRIPTION
session	The user session. TYPE: UserSession or None

RETURNS	DESCRIPTION
bool	True if the session has admin role.

---

Middleware

pywry.state.auth.AuthMiddleware

AuthMiddleware(app: Any, session_store: SessionStore, config: AuthConfig, public_paths: set[str] | None = None)

ASGI middleware for authentication.

Extracts session from requests and adds to request state.

Initialize the middleware.

PARAMETER	DESCRIPTION
app	The wrapped application. TYPE: ASGI application
session_store	Session store for validation. TYPE: SessionStore
config	Authentication configuration. TYPE: AuthConfig
public_paths	Paths that do not require authentication (e.g., login/callback routes). TYPE: set of str DEFAULT: None

Functions