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.

Attributes:

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

---

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.

Parameters:

Name	Type	Description	Default
user_id	str	The user ID.	required
secret	str	Secret key for signing.	required
expires_at	float or None	Expiration timestamp. If None, token doesn't expire.	None

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
token	str	The session token.	required
secret	str	Secret key for verification.	required

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
widget_id	str	The widget ID.	required
secret	str	Secret key for signing.	required
ttl	int	Token TTL in seconds.	300

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
token	str	The widget token.	required
widget_id	str	Expected widget ID.	required
secret	str	Secret key for verification.	required

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
role	str	The role name.	required

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
session	UserSession or None	The user session.	required
permission	str	The required permission.	required

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
session	UserSession or None	The user session.	required

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
app	ASGI application	The wrapped application.	required
session_store	SessionStore	Session store for validation.	required
config	AuthConfig	Authentication configuration.	required
public_paths	set of str	Paths that do not require authentication (e.g., login/callback routes).	None

Functions