msflib.auth

Public modules of the msflib-auth package.

msflib.auth.config

msflib.auth.deps

get_account_dependencies(*, AccountModel: type[Any], oauth_token_url: str, secret_key: str, active_statuses: list[str | BaseEnum] | None = None, account_role_attr: str = 'role', session_dep: Callable, keystore_dep: Callable) -> DependencyNamespace

Return reusable dependencies for account authentication & authorization.

Parameters:

Name	Type	Description	Default
AccountModel	type[Any]	The SQLModel/ORM class representing an account row.	required
oauth_token_url	str	Token URL used by the OAuth2 password-bearer scheme (shown in docs).	required
secret_key	str	HMAC secret used to verify JWT signatures.	required
active_statuses	list[str | BaseEnum] | None	Statuses that are considered "active". Defaults to ["active", "online"]. Pass a list of enum members or plain strings to customise.	None
session_dep	Callable	FastAPI-injectable callable that yields a DB session.	required
keystore_dep	Callable	FastAPI-injectable callable that yields a :class:StoreInterface used for token revocation checks.	required

Returns:

Type	Description
DependencyNamespace exposing:	get_current_account — requires a valid, non-revoked token. get_current_account_or_none — same but returns None for unauthenticated requests (anonymous-safe). get_current_active_account — additionally validates account status. get_current_active_superuser— additionally validates role == "root". RoleCheck — callable class for role-based guards.

get_user_dependencies(*, UserModel: type[Any], WorkspaceModel: type[Any], session_dep: Callable, account_dependencies: DependencyNamespace, user_role_attr: str = 'type', current_workspace_attr: str = 'current_workspace_id', workspace_resolver: WorkspaceResolver | None = None) -> DependencyNamespace

Return reusable dependencies for workspace+user identity & authorization.

Parameters:

Name	Type	Description	Default
UserModel	type[Any]	The SQLModel/ORM class representing a workspace user/member row.	required
WorkspaceModel	type[Any]	The SQLModel/ORM class representing a workspace row.	required
session_dep	Callable	FastAPI-injectable callable that yields a DB session.	required
account_dependencies	DependencyNamespace	The namespace returned by :func:get_account_dependencies.	required
workspace_resolver	WorkspaceResolver | None	A :class:~msflib.auth.resolvers.WorkspaceResolver instance that determines how the workspace is identified from each request. Typically initialised once at app startup and reused. Example:: from msflib.auth.resolvers import PathParameterResolver resolver = PathParameterResolver()	None

Returns:

Type	Description
DependencyNamespace exposing:	get_current_workspace — requires authenticated account. get_current_workspace_anonymous — no authentication needed. get_current_user — resolves workspace member. get_current_active_user — additionally validates user status. WorkspaceRoleCheck — callable class for workspace role guards.

msflib.auth.eventbus

msflib.auth.models

msflib.auth.resolvers

Workspace resolution strategies for msflib.auth.

A WorkspaceResolver determines how the current workspace is identified from an incoming request. The strategy is chosen once at app startup and injected into get_user_dependencies().

Built-in resolvers

• PathParameterResolver — extracts a path parameter (default: workspace_slug). This matches the original hard-coded behaviour and is the recommended starting point.
• HttpHeaderResolver — reads a request header (default: X-Workspace). Useful for API clients or SPAs that send the active workspace as a header rather than encoding it in the URL.

Custom resolvers

Subclass WorkspaceResolver and implement resolve() to support any other strategy (request header, JWT claim, query param, etc.). See modules/auth/WORKSPACE_RESOLUTION.md for a full guide.

ResolverContext(session: Any, account: Any | None, path_params: dict = dict(), headers: dict = dict()) dataclass

Contextual data passed to a resolver for each request.

Attributes:

Name	Type	Description
session	Any	The active database session for the request.
account	Any | None	The resolved account for the request, or None for anonymous requests.
path_params	dict	A dict of FastAPI path parameters extracted from the URL (e.g. {"workspace_slug": "acme"}).
headers	dict	A dict of HTTP request headers. Values are strings as received.

WorkspaceResolver

Bases: ABC

Abstract base class for workspace resolution strategies.

Implement :meth:resolve to return a workspace identifier (typically a slug string) given request context. Return None to indicate that no workspace could be identified from the current request.

resolve(context: ResolverContext) -> str | None abstractmethod

Return a workspace identifier or None.

Parameters:

Name	Type	Description	Default
context	ResolverContext	The :class:ResolverContext for the current request.	required

Returns:

Type	Description
str | None	A workspace slug/identifier, or None if not found.

PathParameterResolver(param_name: str = 'workspace_slug')

Bases: WorkspaceResolver

Resolves the workspace from a FastAPI URL path parameter.

This is the default resolver and reproduces the original hard-coded behaviour of extracting workspace_slug from the request path.

Parameters:

Name	Type	Description	Default
param_name	str	The name of the path parameter to read. Defaults to "workspace_slug".	'workspace_slug'

Example

.. code-block:: python

resolver = PathParameterResolver()
# or with a custom param name:
resolver = PathParameterResolver(param_name="slug")

HttpHeaderResolver(header_name: str = 'X-Workspace')

Bases: WorkspaceResolver

Resolves the workspace from an HTTP request header.

Useful for API clients or single-page applications that send the active workspace identifier as a header rather than encoding it in the URL.

Parameters:

Name	Type	Description	Default
header_name	str	The name of the HTTP header to read. Defaults to "X-Workspace". Header lookup is case-insensitive (FastAPI normalises header names to lowercase, so "X-Workspace" is looked up as "x-workspace" in :attr:ResolverContext.headers).	'X-Workspace'

Example

.. code-block:: python

resolver = HttpHeaderResolver()
# or with a custom header name:
resolver = HttpHeaderResolver(header_name="X-Active-Workspace")

msflib.auth.router

check_active_status(account: AccountType, active_statuses: list[str | BaseEnum]) -> bool

Check whether an account has a status that is considered active.

Parameters:

Name	Type	Description	Default
account	AccountType	The account object to check.	required
active_statuses	list[str | BaseEnum]	A list of allowed statuses (string or enum).	required

Returns:

Name	Type	Description
bool	bool	True if the account's status is in active_statuses, False otherwise.

msflib.auth.services

email

send_reset_password_email(email_to: str, username: str, token: str, code: str, settings: SettingsBase, template_file: str = 'reset_password.html') -> None

Send a password recovery message using auth-specific settings.

The only real difference from the core wrapper is that the path used when constructing the client link lives in the AUTH namespace instead of the top-level configuration.

Parameters:

Name	Type	Description	Default
email_to	str	recipient address	required
username	str	the user name (or email) to display in the template	required
token	str	the JWT reset token	required
code	str	short code portion of the token used for verification	required
settings	SettingsBase	the root Settings object, used for both global and AUTH-scoped values.	required
template_file	str	name of the HTML template to render.	'reset_password.html'