App

jwtlib.app

Summary

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.

Notes

Responsibilities:

- User registration and login.
- Stateless logout semantics.
- Current-user resolution from `JWT`s.
- Service-to-service token introspection.

Constraints:

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

Classes

Functions

get_logged_in_user async

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

Resolve the currently authenticated user from a JWT.

Parameters:

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

Returns:

Name	Type	Description
PublicUser	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.

Parameters:

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

Returns:

Name	Type	Description
IntrospectResponse	IntrospectResponse	IntrospectResponse indicating valid token with user, invalid token, or valid token with no user.

Notes

Responsibilities:

- Validate the provided token and resolve the associated user,
  returning a structured introspection response suitable for
  internal service use.

Guarantees:

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

login_user async

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

Authenticate a user and issue an access token.

Parameters:

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

Returns:

Name	Type	Description
LoginResponse	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.

Returns:

Name	Type	Description
LogoutResponse	LogoutResponse	LogoutResponse containing a logout confirmation message.

Notes

Guarantees:

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

register_user async

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

Register a new user.

Parameters:

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

Returns:

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