Models

jwtlib.models

jwtlib Models: Structured Data for Authentication.

Summary

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:

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

Projecting a User to Public View:

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:

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

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

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

Guarantees:

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