oqtopus_auth ¶

Authentication package: providers and configuration models (framework-agnostic).

Classes:

AuthConfig –

Top-level authentication configuration.
AuthContext –

Framework-agnostic authentication context passed to providers.
AuthProvider –

Abstract base for authentication providers.
AuthUser –

Authenticated user extracted from JWT claims.
AuthenticationError –

Raised by a provider when the request should be rejected with 403.
HeaderProvider –

Provider that extracts user and roles from JWT claims set by a reverse proxy.
HeaderProviderConfig –

Settings specific to the header-based authentication provider.
NoneProviderConfig –

Settings for the provider: none (disabled auth) mode.
NullProvider –

No-op provider for provider: none; grants every request admin access.
Permissions –

Framework-agnostic permission checker bound to a role-permissions mapping.
SignatureVerificationConfig –

JWT signature verification sub-config (under provider: header).

Functions:

build_provider –

Instantiate the appropriate provider based on the configuration.
has_permission –

Return True if the user holds any role that grants the given permission.
parse_auth_config –

Parse an AuthConfig from a raw dict (e.g., loaded from YAML).
parse_header_provider_config –

Parse a HeaderProviderConfig from a raw dict, raising on missing fields.
parse_none_provider_config –

Parse a NoneProviderConfig from a raw dict, raising on missing fields.
parse_role_permissions –

Parse a permissions config dict into a resolved role → permissions mapping.

AuthConfig ¶


              flowchart TD
              oqtopus_auth.AuthConfig[AuthConfig]

              

              click oqtopus_auth.AuthConfig href "" "oqtopus_auth.AuthConfig"

Top-level authentication configuration.

AuthContext ¶

AuthContext(context: Mapping[str, str])


              flowchart TD
              oqtopus_auth.AuthContext[AuthContext]

              

              click oqtopus_auth.AuthContext href "" "oqtopus_auth.AuthContext"

Framework-agnostic authentication context passed to providers.

Behaves as a read-only mapping so providers can call context.get(key) without depending on any web framework.

AuthProvider ¶


              flowchart TD
              oqtopus_auth.AuthProvider[AuthProvider]

              

              click oqtopus_auth.AuthProvider href "" "oqtopus_auth.AuthProvider"

Abstract base for authentication providers.

Methods:

authenticate –

Authenticate the request context.

authenticate `abstractmethod` `async` ¶

authenticate(context: AuthContext) -> AuthUser | None

Authenticate the request context.

Returns:

AuthUser | None –

AuthUser on success, or None if an implementation chooses
AuthUser | None –

to let anonymous requests through without a user identity.
AuthUser | None –

NullProvider (provider: none) does not use this — it
AuthUser | None –

always returns a synthetic AuthUser built from its config.

Raises:

AuthenticationError –

If the request should be rejected with 403.

AuthUser `dataclass` ¶

AuthUser(
    account: str,
    roles: list[str] = list(),
    raw_groups: list[str] = list(),
)

Authenticated user extracted from JWT claims.

Attributes:

role (str) –

The primary role, for backward-compatible single-role display.

role `property` ¶

role: str

The primary role, for backward-compatible single-role display.

AuthenticationError ¶

AuthenticationError(reason: str)


              flowchart TD
              oqtopus_auth.AuthenticationError[AuthenticationError]

              

              click oqtopus_auth.AuthenticationError href "" "oqtopus_auth.AuthenticationError"

Raised by a provider when the request should be rejected with 403.

HeaderProvider ¶

HeaderProvider(
    header_config: HeaderProviderConfig,
    role_mappings: dict[str, str],
)


              flowchart TD
              oqtopus_auth.HeaderProvider[HeaderProvider]
              oqtopus_auth.base.AuthProvider[AuthProvider]

                              oqtopus_auth.base.AuthProvider --> oqtopus_auth.HeaderProvider
                


              click oqtopus_auth.HeaderProvider href "" "oqtopus_auth.HeaderProvider"
              click oqtopus_auth.base.AuthProvider href "" "oqtopus_auth.base.AuthProvider"

Provider that extracts user and roles from JWT claims set by a reverse proxy.

Methods:

authenticate –

Extract user and roles from JWT claims, then optionally verify the signature.

authenticate `async` ¶

authenticate(context: AuthContext) -> AuthUser | None

Extract user and roles from JWT claims, then optionally verify the signature.

Returns:

AuthUser | None –

Authenticated AuthUser.

Raises:

AuthenticationError –

If the JWT is missing/invalid, no roles match, or signature verification fails.

HeaderProviderConfig ¶


              flowchart TD
              oqtopus_auth.HeaderProviderConfig[HeaderProviderConfig]

              

              click oqtopus_auth.HeaderProviderConfig href "" "oqtopus_auth.HeaderProviderConfig"

Settings specific to the header-based authentication provider.

NoneProviderConfig ¶


              flowchart TD
              oqtopus_auth.NoneProviderConfig[NoneProviderConfig]

              

              click oqtopus_auth.NoneProviderConfig href "" "oqtopus_auth.NoneProviderConfig"

Settings for the provider: none (disabled auth) mode.

NullProvider ¶

NullProvider(cfg: NoneProviderConfig)


              flowchart TD
              oqtopus_auth.NullProvider[NullProvider]
              oqtopus_auth.base.AuthProvider[AuthProvider]

                              oqtopus_auth.base.AuthProvider --> oqtopus_auth.NullProvider
                


              click oqtopus_auth.NullProvider href "" "oqtopus_auth.NullProvider"
              click oqtopus_auth.base.AuthProvider href "" "oqtopus_auth.base.AuthProvider"

No-op provider for provider: none; grants every request admin access.

Methods:

authenticate –

Return a virtual user built from the auth.none config section.

authenticate `async` ¶

authenticate(context: AuthContext) -> AuthUser | None

Return a virtual user built from the auth.none config section.

Returns:

AuthUser | None –

A synthetic AuthUser so that permission checks and
AuthUser | None –

template flags behave identically to a real session.

Permissions ¶

Permissions(role_permissions: dict[str, frozenset[str]])

Framework-agnostic permission checker bound to a role-permissions mapping.

Instantiate once with the resolved mapping and use :meth:has_permission in route handlers or templates.

For dependency-injection-based web frameworks, see the optional framework-specific extension modules (e.g. :mod:oqtopus_auth.fastapi for FastAPI), which extend this class with a :meth:require method.

Methods:

has_permission –

Return True if the user holds the given permission.

has_permission ¶

has_permission(
    user: AuthUser | None, permission: str
) -> bool

Return True if the user holds the given permission.

Returns:

bool –

True if the user has the permission, False otherwise.

SignatureVerificationConfig ¶


              flowchart TD
              oqtopus_auth.SignatureVerificationConfig[SignatureVerificationConfig]

              

              click oqtopus_auth.SignatureVerificationConfig href "" "oqtopus_auth.SignatureVerificationConfig"

JWT signature verification sub-config (under provider: header).

build_provider ¶

build_provider(cfg: AuthConfig) -> AuthProvider

Instantiate the appropriate provider based on the configuration.

Returns:

AuthProvider –

The configured AuthProvider instance.

Raises:

ValueError –

If the provider name is not recognized.

has_permission ¶

has_permission(
    user: AuthUser | None,
    permission: str,
    role_permissions: dict[str, frozenset[str]],
) -> bool

Return True if the user holds any role that grants the given permission.

Returns:

bool –

True if the user has the permission, False otherwise.

parse_auth_config ¶

parse_auth_config(raw: dict) -> AuthConfig

Parse an AuthConfig from a raw dict (e.g., loaded from YAML).

Delegates to parse_none_provider_config and parse_header_provider_config which raise ValueError when required fields are missing.

Returns:

AuthConfig –

A validated AuthConfig instance.

parse_header_provider_config ¶

parse_header_provider_config(
    raw: dict,
) -> HeaderProviderConfig

Parse a HeaderProviderConfig from a raw dict, raising on missing fields.

Returns:

HeaderProviderConfig –

A validated HeaderProviderConfig instance.

Raises:

ValueError –

If jwt_header or user_claim is missing.

parse_none_provider_config ¶

parse_none_provider_config(raw: dict) -> NoneProviderConfig

Parse a NoneProviderConfig from a raw dict, raising on missing fields.

Returns:

NoneProviderConfig –

A validated NoneProviderConfig instance.

Raises:

ValueError –

If default_account or default_roles is missing.

parse_role_permissions ¶

parse_role_permissions(
    raw: dict,
) -> dict[str, frozenset[str]]

Parse a permissions config dict into a resolved role → permissions mapping.

The _extends_ key defines single-level inheritance: a role listed there inherits all permissions of its parent role in addition to its own.

Returns:

dict[str, frozenset[str]] –

Mapping of role name to resolved frozenset of permission strings.

oqtopus_auth ¶

AuthConfig ¶

AuthContext ¶

AuthProvider ¶

authenticate abstractmethod async ¶

AuthUser dataclass ¶

role property ¶

AuthenticationError ¶

HeaderProvider ¶

authenticate async ¶

HeaderProviderConfig ¶

NoneProviderConfig ¶

NullProvider ¶

authenticate async ¶

Permissions ¶

has_permission ¶

SignatureVerificationConfig ¶

build_provider ¶

has_permission ¶

parse_auth_config ¶

parse_header_provider_config ¶

parse_none_provider_config ¶

parse_role_permissions ¶

authenticate `abstractmethod` `async` ¶

AuthUser `dataclass` ¶

role `property` ¶

authenticate `async` ¶

authenticate `async` ¶