Skip to content

# 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:

    1
    2
    3
    4

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

Constraints:

    1
    2
    3
    4
    5

    - 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`

    1

    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`

    1

    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:

    1
    2
    3

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

Guarantees:

    1
    2
    3

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

#### `` login_user `async`

    1

    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`

    1

    logout_user() -> LogoutResponse

Perform a stateless logout.

Returns:

Name | Type | Description
--- | --- | ---
`LogoutResponse` | `LogoutResponse` | `LogoutResponse` containing a logout confirmation message.

Notes

Guarantees:

    1
    2
    3

    - 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`

    1

    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.