Skip to content

# Models

## `` jwtlib.models

### Summary

`jwtlib` Models: Structured Data for Authentication.

This package defines the core data models used by `jwtlib`. These models are categorized into request payloads, response objects, persistence documents, and security context.

### Model Categories

API Requests:

- `RegisterRequest`: Payload for creating new user accounts.
- `LoginRequest`: User credentials for issuing `JWT`s.
- `IntrospectRequest`: Internal payload for service-to-service token verification.

API Responses:

- `PublicUser`: A safe, non-sensitive projection of a user profile.
- `LoginResponse`: Contains the issued access token and the `PublicUser`.
- `LogoutResponse`: Instruction for clients to clear stateless session state.

Internal & Security:

- `User`: The MongoDB-backed persistence model (Confined to repository layer).
- `TokenPayload`: Decoded claims from a validated `JWT` (`sub`, `exp`).
- `IntrospectResponse`: Structured result of a token validity check.

### Usage

Validating an Auth Request:

    1
    2

    from jwtlib.models import LoginRequest
    auth_data = LoginRequest(username="tester", password="secure_password")

Projecting a User to Public View:

    1
    2

    from jwtlib.models import User, PublicUser
    user_profile = PublicUser.model_validate(db_user, from_attributes=True)

### Public API

This package re-exports all validated data models required by the authentication system. Consumers should import from this namespace to ensure type safety and consistency.

- `LoginRequest` / `LoginResponse`
- `RegisterRequest`
- `LogoutResponse`
- `PublicUser`
- `IntrospectRequest` / `IntrospectResponse`
- `User` (Persistence)
- `TokenPayload` (`JWT`)

### Classes

#### `` IntrospectRequest

Bases: `BaseModel`

Payload for requesting token introspection.

Attributes:

Name | Type | Description
--- | --- | ---
`token` | `str` | `JWT` access token to introspect.

#### `` IntrospectResponse

Bases: `BaseModel`

Result of a token introspection operation.

Attributes:

Name | Type | Description
--- | --- | ---
`active` | `bool` | Indicates whether the token is valid and active.
`user` | `Optional[PublicUser]` | Public user details if the token is valid; otherwise null.

#### `` LoginRequest

Bases: `IdentityMixin`, `PasswordMixin`

Payload for authenticating a user and issuing a `JWT`.

Attributes:

Name | Type | Description
--- | --- | ---
`username` | `str` | Username identifier.
`password` | `str` | Plain-text password to be verified.

#### `` LoginResponse

Bases: `BaseModel`

Response returned after successful authentication.

Attributes:

Name | Type | Description
--- | --- | ---
`access_token` | `str` | `JWT` access token for authenticated requests.
`user` | `PublicUser` | Public profile of the authenticated user.

#### `` LogoutResponse

Bases: `BaseModel`

Response returned after a logout operation.

Attributes:

Name | Type | Description
--- | --- | ---
`message` | `str` | Human-readable logout confirmation.

#### `` PublicUser

Bases: `IdentityMixin`, `ActiveStateMixin`

Public-facing user representation returned by authentication APIs.

Attributes:

Name | Type | Description
--- | --- | ---
`username` | `str` | Unique username identifier.
`email` | `EmailStr` | User's email address.
`is_active` | `bool` | Whether the user account is active.

#### `` RegisterRequest

Bases: `IdentityMixin`, `PasswordMixin`

Payload for registering a new user account.

Attributes:

Name | Type | Description
--- | --- | ---
`username` | `str` | Unique username identifier.
`email` | `EmailStr` | User's email address.
`password` | `str` | Plain-text password (to be hashed by the repository layer).

#### `` TokenPayload

Bases: `BaseModel`

Decoded `JWT` payload.

Attributes:

Name | Type | Description
--- | --- | ---
`sub` | `str` | Subject claim identifying the user (typically a username or user ID).
`exp` | `int` | Expiration time as a Unix timestamp (seconds since epoch).

Notes

Responsibilities:

    1
    2
    3

    - Represents the validated claims extracted from a `JWT` after
      signature verification. This model is used internally to enforce
      required claims and provide a typed interface to token data.

Guarantees:

    1
    2
    3

    - This model assumes the `JWT` signature has already been verified.
      No authorization decisions should be made solely on this model.
      Additional claims may exist but are intentionally ignored.

#### `` User

Bases: `BaseDocument`, `IdentityMixin`, `ActiveStateMixin`

Internal user persistence model.

Attributes:

Name | Type | Description
--- | --- | ---
`hashed_password` | `str` | Secure hash of the user's password.

Notes

Responsibilities:

    1
    2
    3

    - Represents a user record as stored in the database. Includes
      sensitive fields and is strictly confined to the persistence
      layer.

Guarantees:

    1
    2
    3

    - This model MUST NOT be returned from authentication APIs.
      Consumers should use `PublicUser` instead. Password verification
      is handled by the repository layer.