App

jwtlib.app

Application-level authentication logic.

This module contains pure authentication and introspection logic with no framework or transport coupling. It is intended to be used by HTTP adapters, CLIs, background workers, and other services that require JWT-based authentication and user resolution.

Responsibilities: - User registration and login - Stateless logout semantics - Current-user resolution from JWTs - Service-to-service token introspection

This module does NOT: - Define HTTP routes - Manage sessions - Perform request parsing or response formatting - Handle transport-level concerns

All functions are async-safe and fully typed.

get_logged_in_user async

get_logged_in_user(token: str, repo: Optional[UserRepository] = None) -> PublicUser

Resolve the currently authenticated user from a JWT.

Validates the provided JWT, extracts its subject, and resolves the corresponding user from persistence.

Parameters:

Name	Type	Description	Default
token	str	JWT access token.	required
repo	Optional[UserRepository]	Optional user repository instance. If not provided, a default repository is obtained via dependency utilities.	None

Returns:

Type	Description
PublicUser	The authenticated user as a PublicUser.

Raises:

Type	Description
InvalidToken	If the token is missing, malformed, or invalid.
AuthError	If the token is valid, but the user cannot be resolved.

introspect_token async

introspect_token(token: str, repo: Optional[UserRepository] = None) -> IntrospectResponse

Introspect a JWT for service-to-service authentication.

Validates the provided token and resolves the associated user, returning a structured introspection response suitable for internal service use.

This function never raises authentication exceptions. Instead, it returns a typed response indicating token validity and user presence.

Parameters:

Name	Type	Description	Default
token	str	JWT access token to introspect.	required
repo	Optional[UserRepository]	Optional user repository instance. If not provided, a default repository is obtained via dependency utilities.	None

Returns:

Type	Description
IntrospectResponse	IntrospectResponse indicating one of:
IntrospectResponse	Valid token with associated user
IntrospectResponse	Invalid token
IntrospectResponse	Valid token with no corresponding user

login_user async

login_user(user: LoginRequest, repo: Optional[UserRepository] = None) -> LoginResponse

Authenticate a user and issue an access token.

Verifies the provided credentials and returns a JWT access token on success.

Parameters:

Name	Type	Description	Default
user	LoginRequest	Login payload containing username and password.	required
repo	Optional[UserRepository]	Optional user repository instance. If not provided, a default repository is obtained via dependency utilities.	None

Returns:

Type	Description
LoginResponse	LoginResponse containing the issued access token and related metadata.

Raises:

Type	Description
AuthError	If the credentials are invalid.

logout_user async

logout_user() -> LogoutResponse

Perform a stateless logout.

This function does not invalidate tokens server-side. Instead, it provides a standardized response indicating that the client must discard its token.

Returns:

Type	Description
LogoutResponse	LogoutResponse containing a logout confirmation message.

register_user async

register_user(user: RegisterRequest, repo: Optional[UserRepository] = None) -> PublicUser

Register a new user.

Creates a new user record using the provided registration data.

Parameters:

Name	Type	Description	Default
user	RegisterRequest	Registration payload containing username, email, and password.	required
repo	Optional[UserRepository]	Optional user repository instance. If not provided, a default repository is obtained via dependency utilities.	None

Returns:

Type	Description
PublicUser	The newly created user as a public user representation.