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 JWTs.
  • 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.