docs/libs/py-jwt/site/search/search_index.json

{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"jwtlib/","title":"Jwtlib","text":""},{"location":"jwtlib/#jwtlib","title":"jwtlib","text":""},{"location":"jwtlib/#jwtlib--jwtlib-a-framework-agnostic-jwt-authentication-library","title":"jwtlib: A framework-agnostic JWT authentication library","text":"<p><code>jwtlib</code> provides a set of pure logic components for handling JWT discovery, user registration, login, and token introspection. It is designed to be decoupled from any specific web framework (like FastAPI or Flask).</p>"},{"location":"jwtlib/#jwtlib--features","title":"Features","text":"<ul> <li>Stateless Auth: Clean JWT-based authentication and logout.</li> <li>Service-to-Service: Built-in support for token introspection.</li> <li>Async-First: All core logic handlers are async-safe.</li> <li>Fully Typed: Use with <code>mypy</code> or <code>pyright</code> for static safety.</li> </ul>"},{"location":"jwtlib/#jwtlib--installation","title":"Installation","text":"<pre><code>pip install py-jwt\n</code></pre>"},{"location":"jwtlib/#jwtlib--quick-start","title":"Quick Start","text":"<pre><code>import asyncio\nfrom jwtlib import login_user, LoginRequest\n\nasync def main():\n    request = LoginRequest(username=\"admin\", password=\"password\")\n    response = await login_user(request)\n    print(f\"Access Token: {response.access_token}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n</code></pre>"},{"location":"jwtlib/#jwtlib.AuthError","title":"AuthError","text":"<p>               Bases: <code>Exception</code></p> <p>Base authentication and authorization error.</p> <p>All authentication-related exceptions raised by this library inherit from this class.</p> <p>Consumers may catch this exception to handle all auth failures uniformly, or catch more specific subclasses for finer control.</p>"},{"location":"jwtlib/#jwtlib.IntrospectRequest","title":"IntrospectRequest","text":"<p>               Bases: <code>BaseModel</code></p> <p>Payload for requesting token introspection.</p> <p>Used by internal services to verify the validity of a JWT and retrieve the associated public user information.</p> Fields <p>token: JWT access token to introspect.</p> Notes <ul> <li>Intended for service-to-service communication.</li> <li>Not meant for direct end-user consumption.</li> </ul>"},{"location":"jwtlib/#jwtlib.IntrospectResponse","title":"IntrospectResponse","text":"<p>               Bases: <code>BaseModel</code></p> <p>Result of a token introspection operation.</p> <p>This model communicates whether a JWT is valid and, if so, provides the associated public user information.</p> Fields <p>active: Indicates whether the token is valid and active. user: Public user details if the token is valid; otherwise null.</p> Notes <ul> <li>This model is designed to avoid raising exceptions.</li> <li>All introspection outcomes are represented as data.</li> </ul>"},{"location":"jwtlib/#jwtlib.InvalidToken","title":"InvalidToken","text":"<p>               Bases: <code>AuthError</code></p> <p>Raised when a JWT is missing, malformed, expired, or invalid.</p> <p>This error indicates that the provided token cannot be used to authenticate a request.</p>"},{"location":"jwtlib/#jwtlib.LoginRequest","title":"LoginRequest","text":"<p>               Bases: <code>IdentityMixin</code>, <code>PasswordMixin</code></p> <p>Payload for authenticating a user and issuing a JWT.</p> <p>This model is used to verify user credentials and request an access token.</p> Fields <p>username: Username identifier. password: Plain-text password to be verified.</p> Notes <ul> <li>Successful authentication results in a LoginResponse.</li> <li>Failed authentication raises an AuthError.</li> </ul>"},{"location":"jwtlib/#jwtlib.LoginResponse","title":"LoginResponse","text":"<p>               Bases: <code>BaseModel</code></p> <p>Response returned after successful authentication.</p> <p>Contains the issued JWT access token and the authenticated user's public profile.</p> Fields <p>access_token: JWT access token for authenticated requests. user: Public profile of the authenticated user.</p> Notes <ul> <li>The token is stateless and must be stored client-side.</li> <li>Token expiration and validation are handled elsewhere.</li> </ul>"},{"location":"jwtlib/#jwtlib.LogoutResponse","title":"LogoutResponse","text":"<p>               Bases: <code>BaseModel</code></p> <p>Response returned after a logout operation.</p> <p>Since logout is stateless, this response serves only as a confirmation message instructing the client to discard its token.</p> Fields <p>message: Human-readable logout confirmation.</p>"},{"location":"jwtlib/#jwtlib.PublicUser","title":"PublicUser","text":"<p>               Bases: <code>IdentityMixin</code>, <code>ActiveStateMixin</code></p> <p>Public-facing user representation returned by authentication APIs.</p> <p>This model represents a user profile that is safe to expose outside the authentication system.</p> Fields <p>username: Unique username identifier. email: User's email address. is_active: Whether the user account is active.</p> Notes <ul> <li>Contains no sensitive data.</li> <li>Can be constructed from persistence models via <code>from_attributes</code>.</li> </ul>"},{"location":"jwtlib/#jwtlib.RegisterRequest","title":"RegisterRequest","text":"<p>               Bases: <code>IdentityMixin</code>, <code>PasswordMixin</code></p> <p>Payload for registering a new user account.</p> <p>This model contains the minimum required identity and credential information to create a new user.</p> Fields <p>username: Unique username identifier. email: User's email address. password: Plain-text password (to be hashed by the repository layer).</p> Notes <ul> <li>Validation and normalization handled by mixins.</li> <li>This model is never returned in responses.</li> </ul>"},{"location":"jwtlib/#jwtlib.TokenPayload","title":"TokenPayload","text":"<p>               Bases: <code>BaseModel</code></p> <p>Decoded JWT payload.</p> <p>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.</p> Fields <p>sub: Subject claim identifying the user (typically a username or user ID). exp: Expiration time as a Unix timestamp (seconds since epoch).</p> Notes <ul> <li>This model assumes the JWT signature has already been verified.</li> <li>No authorization decisions should be made solely on this model.</li> <li>Additional claims may exist but are intentionally ignored.</li> </ul>"},{"location":"jwtlib/#jwtlib.User","title":"User","text":"<p>               Bases: <code>BaseDocument</code>, <code>IdentityMixin</code>, <code>ActiveStateMixin</code></p> <p>Internal user persistence model.</p> <p>Represents a user record as stored in the database. This model includes sensitive fields and is strictly confined to the persistence layer.</p> Fields <p>hashed_password: Secure hash of the user's password.</p> Notes <ul> <li>This model MUST NOT be returned from authentication APIs.</li> <li>Consumers should use <code>PublicUser</code> instead.</li> <li>Password verification is handled by the repository layer.</li> <li>Inherits identity and active-state behavior via mixins.</li> </ul>"},{"location":"jwtlib/#jwtlib.UserNotFound","title":"UserNotFound","text":"<p>               Bases: <code>AuthError</code></p> <p>Raised when a valid token does not map to an existing user.</p> <p>Indicates that authentication succeeded at the token level, but the associated user record could not be resolved.</p>"},{"location":"jwtlib/#jwtlib.authenticate_request","title":"authenticate_request  <code>async</code>","text":"<pre><code>authenticate_request(should_skip_authentication: Callable[[str, str], bool], *, method: str, path: str, authorization_token: Optional[str]) -&gt; Optional[PublicUser]\n</code></pre> <p>Authenticate an incoming request using token introspection.</p> <p>Determines whether authentication should be skipped for the given request context and, if not, resolves the authenticated user via token introspection.</p> <p>Parameters:</p> Name Type Description Default <code>should_skip_authentication</code> <code>Callable[[str, str], bool]</code> <p>Callable that decides whether authentication is required for a given HTTP method and path.</p> required <code>method</code> <code>str</code> <p>HTTP method of the incoming request.</p> required <code>path</code> <code>str</code> <p>Request path.</p> required <code>authorization_token</code> <code>Optional[str]</code> <p>JWT access token provided by the caller.</p> required <p>Returns:</p> Type Description <code>Optional[PublicUser]</code> <p>PublicUser if authentication succeeds.</p> <code>Optional[PublicUser]</code> <p>None if authentication is skipped.</p> <p>Raises:</p> Type Description <code>InvalidToken</code> <p>If authentication is required but the token is missing, invalid, or revoked.</p> <code>AuthServiceUnavailable</code> <p>If the auth service cannot be reached.</p> Notes <ul> <li>This function does not parse Authorization headers; callers must   supply the raw token.</li> <li>Access-control policy is externalized via <code>should_skip_authentication</code>.</li> <li>The returned PublicUser contains no sensitive information.</li> </ul>"},{"location":"jwtlib/#jwtlib.get_logged_in_user","title":"get_logged_in_user  <code>async</code>","text":"<pre><code>get_logged_in_user(token: str, repo: Optional[UserRepository] = None) -&gt; PublicUser\n</code></pre> <p>Resolve the currently authenticated user from a JWT.</p> <p>Validates the provided JWT, extracts its subject, and resolves the corresponding user from persistence.</p> <p>Parameters:</p> Name Type Description Default <code>token</code> <code>str</code> <p>JWT access token.</p> required <code>repo</code> <code>Optional[UserRepository]</code> <p>Optional user repository instance. If not provided, a default repository is obtained via dependency utilities.</p> <code>None</code> <p>Returns:</p> Type Description <code>PublicUser</code> <p>The authenticated user as a PublicUser.</p> <p>Raises:</p> Type Description <code>InvalidToken</code> <p>If the token is missing, malformed, or invalid.</p> <code>AuthError</code> <p>If the token is valid, but the user cannot be resolved.</p>"},{"location":"jwtlib/#jwtlib.introspect_token","title":"introspect_token  <code>async</code>","text":"<pre><code>introspect_token(token: str, repo: Optional[UserRepository] = None) -&gt; IntrospectResponse\n</code></pre> <p>Introspect a JWT for service-to-service authentication.</p> <p>Validates the provided token and resolves the associated user, returning a structured introspection response suitable for internal service use.</p> <p>This function never raises authentication exceptions. Instead, it returns a typed response indicating token validity and user presence.</p> <p>Parameters:</p> Name Type Description Default <code>token</code> <code>str</code> <p>JWT access token to introspect.</p> required <code>repo</code> <code>Optional[UserRepository]</code> <p>Optional user repository instance. If not provided, a default repository is obtained via dependency utilities.</p> <code>None</code> <p>Returns:</p> Type Description <code>IntrospectResponse</code> <p>IntrospectResponse indicating one of:</p> <code>IntrospectResponse</code> <ul> <li>Valid token with associated user</li> </ul> <code>IntrospectResponse</code> <ul> <li>Invalid token</li> </ul> <code>IntrospectResponse</code> <ul> <li>Valid token with no corresponding user</li> </ul>"},{"location":"jwtlib/#jwtlib.login_user","title":"login_user  <code>async</code>","text":"<pre><code>login_user(user: LoginRequest, repo: Optional[UserRepository] = None) -&gt; LoginResponse\n</code></pre> <p>Authenticate a user and issue an access token.</p> <p>Verifies the provided credentials and returns a JWT access token on success.</p> <p>Parameters:</p> Name Type Description Default <code>user</code> <code>LoginRequest</code> <p>Login payload containing username and password.</p> required <code>repo</code> <code>Optional[UserRepository]</code> <p>Optional user repository instance. If not provided, a default repository is obtained via dependency utilities.</p> <code>None</code> <p>Returns:</p> Type Description <code>LoginResponse</code> <p>LoginResponse containing the issued access token and related metadata.</p> <p>Raises:</p> Type Description <code>AuthError</code> <p>If the credentials are invalid.</p>"},{"location":"jwtlib/#jwtlib.logout_user","title":"logout_user  <code>async</code>","text":"<pre><code>logout_user() -&gt; LogoutResponse\n</code></pre> <p>Perform a stateless logout.</p> <p>This function does not invalidate tokens server-side. Instead, it provides a standardized response indicating that the client must discard its token.</p> <p>Returns:</p> Type Description <code>LogoutResponse</code> <p>LogoutResponse containing a logout confirmation message.</p>"},{"location":"jwtlib/#jwtlib.register_user","title":"register_user  <code>async</code>","text":"<pre><code>register_user(user: RegisterRequest, repo: Optional[UserRepository] = None) -&gt; PublicUser\n</code></pre> <p>Register a new user.</p> <p>Creates a new user record using the provided registration data.</p> <p>Parameters:</p> Name Type Description Default <code>user</code> <code>RegisterRequest</code> <p>Registration payload containing username, email, and password.</p> required <code>repo</code> <code>Optional[UserRepository]</code> <p>Optional user repository instance. If not provided, a default repository is obtained via dependency utilities.</p> <code>None</code> <p>Returns:</p> Type Description <code>PublicUser</code> <p>The newly created user as a public user representation.</p>"},{"location":"jwtlib/app/","title":"App","text":""},{"location":"jwtlib/app/#jwtlib.app","title":"jwtlib.app","text":"<p>Application-level authentication logic.</p> <p>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.</p> <p>Responsibilities: - User registration and login - Stateless logout semantics - Current-user resolution from JWTs - Service-to-service token introspection</p> <p>This module does NOT: - Define HTTP routes - Manage sessions - Perform request parsing or response formatting - Handle transport-level concerns</p> <p>All functions are async-safe and fully typed.</p>"},{"location":"jwtlib/app/#jwtlib.app.get_logged_in_user","title":"get_logged_in_user  <code>async</code>","text":"<pre><code>get_logged_in_user(token: str, repo: Optional[UserRepository] = None) -&gt; PublicUser\n</code></pre> <p>Resolve the currently authenticated user from a JWT.</p> <p>Validates the provided JWT, extracts its subject, and resolves the corresponding user from persistence.</p> <p>Parameters:</p> Name Type Description Default <code>token</code> <code>str</code> <p>JWT access token.</p> required <code>repo</code> <code>Optional[UserRepository]</code> <p>Optional user repository instance. If not provided, a default repository is obtained via dependency utilities.</p> <code>None</code> <p>Returns:</p> Type Description <code>PublicUser</code> <p>The authenticated user as a PublicUser.</p> <p>Raises:</p> Type Description <code>InvalidToken</code> <p>If the token is missing, malformed, or invalid.</p> <code>AuthError</code> <p>If the token is valid, but the user cannot be resolved.</p>"},{"location":"jwtlib/app/#jwtlib.app.introspect_token","title":"introspect_token  <code>async</code>","text":"<pre><code>introspect_token(token: str, repo: Optional[UserRepository] = None) -&gt; IntrospectResponse\n</code></pre> <p>Introspect a JWT for service-to-service authentication.</p> <p>Validates the provided token and resolves the associated user, returning a structured introspection response suitable for internal service use.</p> <p>This function never raises authentication exceptions. Instead, it returns a typed response indicating token validity and user presence.</p> <p>Parameters:</p> Name Type Description Default <code>token</code> <code>str</code> <p>JWT access token to introspect.</p> required <code>repo</code> <code>Optional[UserRepository]</code> <p>Optional user repository instance. If not provided, a default repository is obtained via dependency utilities.</p> <code>None</code> <p>Returns:</p> Type Description <code>IntrospectResponse</code> <p>IntrospectResponse indicating one of:</p> <code>IntrospectResponse</code> <ul> <li>Valid token with associated user</li> </ul> <code>IntrospectResponse</code> <ul> <li>Invalid token</li> </ul> <code>IntrospectResponse</code> <ul> <li>Valid token with no corresponding user</li> </ul>"},{"location":"jwtlib/app/#jwtlib.app.login_user","title":"login_user  <code>async</code>","text":"<pre><code>login_user(user: LoginRequest, repo: Optional[UserRepository] = None) -&gt; LoginResponse\n</code></pre> <p>Authenticate a user and issue an access token.</p> <p>Verifies the provided credentials and returns a JWT access token on success.</p> <p>Parameters:</p> Name Type Description Default <code>user</code> <code>LoginRequest</code> <p>Login payload containing username and password.</p> required <code>repo</code> <code>Optional[UserRepository]</code> <p>Optional user repository instance. If not provided, a default repository is obtained via dependency utilities.</p> <code>None</code> <p>Returns:</p> Type Description <code>LoginResponse</code> <p>LoginResponse containing the issued access token and related metadata.</p> <p>Raises:</p> Type Description <code>AuthError</code> <p>If the credentials are invalid.</p>"},{"location":"jwtlib/app/#jwtlib.app.logout_user","title":"logout_user  <code>async</code>","text":"<pre><code>logout_user() -&gt; LogoutResponse\n</code></pre> <p>Perform a stateless logout.</p> <p>This function does not invalidate tokens server-side. Instead, it provides a standardized response indicating that the client must discard its token.</p> <p>Returns:</p> Type Description <code>LogoutResponse</code> <p>LogoutResponse containing a logout confirmation message.</p>"},{"location":"jwtlib/app/#jwtlib.app.register_user","title":"register_user  <code>async</code>","text":"<pre><code>register_user(user: RegisterRequest, repo: Optional[UserRepository] = None) -&gt; PublicUser\n</code></pre> <p>Register a new user.</p> <p>Creates a new user record using the provided registration data.</p> <p>Parameters:</p> Name Type Description Default <code>user</code> <code>RegisterRequest</code> <p>Registration payload containing username, email, and password.</p> required <code>repo</code> <code>Optional[UserRepository]</code> <p>Optional user repository instance. If not provided, a default repository is obtained via dependency utilities.</p> <code>None</code> <p>Returns:</p> Type Description <code>PublicUser</code> <p>The newly created user as a public user representation.</p>"},{"location":"jwtlib/exceptions/","title":"Exceptions","text":""},{"location":"jwtlib/exceptions/#jwtlib.exceptions","title":"jwtlib.exceptions","text":"<p>Authentication and authorization exceptions.</p> <p>This module defines the exception hierarchy used throughout the authentication library to represent authentication, authorization, and service-level failures.</p> <p>All exceptions inherit from <code>AuthError</code>, allowing consumers to catch authentication-related failures broadly or handle specific cases selectively.</p>"},{"location":"jwtlib/exceptions/#jwtlib.exceptions.AuthError","title":"AuthError","text":"<p>               Bases: <code>Exception</code></p> <p>Base authentication and authorization error.</p> <p>All authentication-related exceptions raised by this library inherit from this class.</p> <p>Consumers may catch this exception to handle all auth failures uniformly, or catch more specific subclasses for finer control.</p>"},{"location":"jwtlib/exceptions/#jwtlib.exceptions.AuthServiceUnavailable","title":"AuthServiceUnavailable","text":"<p>               Bases: <code>AuthError</code></p> <p>Raised when the authentication service cannot be reached.</p> <p>Indicates a network failure, timeout, or unexpected error while communicating with the auth service.</p>"},{"location":"jwtlib/exceptions/#jwtlib.exceptions.InvalidAuthorizationHeader","title":"InvalidAuthorizationHeader","text":"<p>               Bases: <code>AuthError</code></p> <p>Raised when the Authorization header is missing or incorrectly formatted.</p> <p>Typically, indicates that the header is not present or does not follow the expected <code>Bearer &lt;token&gt;</code> format.</p>"},{"location":"jwtlib/exceptions/#jwtlib.exceptions.InvalidToken","title":"InvalidToken","text":"<p>               Bases: <code>AuthError</code></p> <p>Raised when a JWT is missing, malformed, expired, or invalid.</p> <p>This error indicates that the provided token cannot be used to authenticate a request.</p>"},{"location":"jwtlib/exceptions/#jwtlib.exceptions.NotAuthenticated","title":"NotAuthenticated","text":"<p>               Bases: <code>AuthError</code></p> <p>Raised when authentication is required but no user context is present.</p> <p>Typically used when attempting to access a protected operation without an authenticated user.</p>"},{"location":"jwtlib/exceptions/#jwtlib.exceptions.UserNotFound","title":"UserNotFound","text":"<p>               Bases: <code>AuthError</code></p> <p>Raised when a valid token does not map to an existing user.</p> <p>Indicates that authentication succeeded at the token level, but the associated user record could not be resolved.</p>"},{"location":"jwtlib/introspection/","title":"Introspection","text":""},{"location":"jwtlib/introspection/#jwtlib.introspection","title":"jwtlib.introspection","text":"<p>Auth client and access-control utilities.</p> <p>This module provides pure authentication and authorization logic for validating JWTs via service-to-service introspection and resolving authenticated users.</p> <p>Key characteristics: - No framework or HTTP routing dependencies - Async-first and fully typed - Designed for use by adapters (HTTP, CLI, background workers) - Delegates token validity decisions to an external auth service</p> <p>Responsibilities: - Calling the auth service introspection endpoint - Translating introspection responses into typed user models - Enforcing access control decisions at the logic layer</p> <p>This module does NOT: - Parse HTTP requests or headers - Implement authentication policies - Perform JWT signature verification locally</p>"},{"location":"jwtlib/introspection/#jwtlib.introspection.authenticate_request","title":"authenticate_request  <code>async</code>","text":"<pre><code>authenticate_request(should_skip_authentication: Callable[[str, str], bool], *, method: str, path: str, authorization_token: Optional[str]) -&gt; Optional[PublicUser]\n</code></pre> <p>Authenticate an incoming request using token introspection.</p> <p>Determines whether authentication should be skipped for the given request context and, if not, resolves the authenticated user via token introspection.</p> <p>Parameters:</p> Name Type Description Default <code>should_skip_authentication</code> <code>Callable[[str, str], bool]</code> <p>Callable that decides whether authentication is required for a given HTTP method and path.</p> required <code>method</code> <code>str</code> <p>HTTP method of the incoming request.</p> required <code>path</code> <code>str</code> <p>Request path.</p> required <code>authorization_token</code> <code>Optional[str]</code> <p>JWT access token provided by the caller.</p> required <p>Returns:</p> Type Description <code>Optional[PublicUser]</code> <p>PublicUser if authentication succeeds.</p> <code>Optional[PublicUser]</code> <p>None if authentication is skipped.</p> <p>Raises:</p> Type Description <code>InvalidToken</code> <p>If authentication is required but the token is missing, invalid, or revoked.</p> <code>AuthServiceUnavailable</code> <p>If the auth service cannot be reached.</p> Notes <ul> <li>This function does not parse Authorization headers; callers must   supply the raw token.</li> <li>Access-control policy is externalized via <code>should_skip_authentication</code>.</li> <li>The returned PublicUser contains no sensitive information.</li> </ul>"},{"location":"jwtlib/introspection/#jwtlib.introspection.introspect_token","title":"introspect_token  <code>async</code>","text":"<pre><code>introspect_token(token: str) -&gt; dict[str, Any]\n</code></pre> <p>Introspect a JWT using the external authentication service.</p> <p>Sends the provided JWT to the configured auth service introspection endpoint and validates the response.</p> <p>Parameters:</p> Name Type Description Default <code>token</code> <code>str</code> <p>JWT access token to introspect.</p> required <p>Returns:</p> Type Description <code>dict[str, Any]</code> <p>A dictionary containing the authenticated user's public payload.</p> <p>Raises:</p> Type Description <code>InvalidToken</code> <p>If the token is missing, invalid, inactive, or revoked.</p> <code>AuthServiceUnavailable</code> <p>If the auth service cannot be reached or fails unexpectedly.</p> Notes <ul> <li>This function treats the auth service as the source of truth.</li> <li>No local JWT validation or signature checking is performed here.</li> <li>The returned payload is expected to be safe for public exposure.</li> </ul>"},{"location":"jwtlib/repository/","title":"Repository","text":""},{"location":"jwtlib/repository/#jwtlib.repository","title":"jwtlib.repository","text":""},{"location":"jwtlib/repository/#jwtlib.repository--userrepository-persistence-layer-for-authentication","title":"UserRepository: Persistence layer for authentication","text":"<p>This module defines the MongoDB-backed repository for managing user records, including creation, lookup, and credential verification.</p>"},{"location":"jwtlib/repository/#jwtlib.repository.UserRepository","title":"UserRepository","text":"<pre><code>UserRepository()\n</code></pre> <p>               Bases: <code>BaseRepository[User]</code></p>"},{"location":"jwtlib/repository/#jwtlib.repository.UserRepository.authenticate_user","title":"authenticate_user  <code>async</code>","text":"<pre><code>authenticate_user(user_auth: LoginRequest) -&gt; Optional[dict]\n</code></pre> <p>Verify user credentials and prepare a login response.</p> <p>Parameters:</p> Name Type Description Default <code>user_auth</code> <code>LoginRequest</code> <p>Login credentials.</p> required <p>Returns:</p> Type Description <code>Optional[dict]</code> <p>A dictionary containing the access token and public user if successful,</p> <code>Optional[dict]</code> <p>otherwise None.</p>"},{"location":"jwtlib/repository/#jwtlib.repository.UserRepository.create","title":"create  <code>async</code>","text":"<pre><code>create(user_create: RegisterRequest) -&gt; PublicUser\n</code></pre> <p>Create a new user record.</p> <p>Parameters:</p> Name Type Description Default <code>user_create</code> <code>RegisterRequest</code> <p>Registration data including prospective password.</p> required <p>Returns:</p> Type Description <code>PublicUser</code> <p>A PublicUser representation of the created user.</p>"},{"location":"jwtlib/repository/#jwtlib.repository.UserRepository.get_active_users","title":"get_active_users  <code>async</code>","text":"<pre><code>get_active_users(skip: int = 0, limit: int = 100) -&gt; List[User]\n</code></pre> <p>List all active users with pagination.</p> <p>Parameters:</p> Name Type Description Default <code>skip</code> <code>int</code> <p>Number of records to skip.</p> <code>0</code> <code>limit</code> <code>int</code> <p>Maximum number of records to return.</p> <code>100</code> <p>Returns:</p> Type Description <code>List[User]</code> <p>A list of active User documents.</p>"},{"location":"jwtlib/repository/#jwtlib.repository.UserRepository.get_by_email","title":"get_by_email  <code>async</code>","text":"<pre><code>get_by_email(email: str) -&gt; Optional[User]\n</code></pre> <p>Retrieve a user by their unique email address.</p> <p>Parameters:</p> Name Type Description Default <code>email</code> <code>str</code> <p>The email address to search for.</p> required <p>Returns:</p> Type Description <code>Optional[User]</code> <p>The User document if found, otherwise None.</p>"},{"location":"jwtlib/repository/#jwtlib.repository.UserRepository.get_by_username","title":"get_by_username  <code>async</code>","text":"<pre><code>get_by_username(username: str) -&gt; Optional[User]\n</code></pre> <p>Retrieve a user by their unique username.</p> <p>Parameters:</p> Name Type Description Default <code>username</code> <code>str</code> <p>The username to search for.</p> required <p>Returns:</p> Type Description <code>Optional[User]</code> <p>The User document if found, otherwise None.</p>"},{"location":"jwtlib/security/","title":"Security","text":""},{"location":"jwtlib/security/#jwtlib.security","title":"jwtlib.security","text":""},{"location":"jwtlib/security/#jwtlib.security.create_access_token","title":"create_access_token","text":"<pre><code>create_access_token(data: dict, expires_delta: Optional[timedelta] = None) -&gt; str\n</code></pre> <p>Generate a new JWT access token.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>dict</code> <p>Subject data to include in the token payload.</p> required <code>expires_delta</code> <code>Optional[timedelta]</code> <p>Optional expiration override.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>An encoded JWT string.</p>"},{"location":"jwtlib/security/#jwtlib.security.get_jwt_payload","title":"get_jwt_payload","text":"<pre><code>get_jwt_payload(token: str) -&gt; TokenPayload\n</code></pre> <p>Decode and validate a JWT, returning a strongly-typed payload.</p> <p>Raises:</p> Type Description <code>JWTError</code> <p>if the token is invalid, expired, or malformed</p>"},{"location":"jwtlib/security/#jwtlib.security.hash_password","title":"hash_password","text":"<pre><code>hash_password(password: str) -&gt; str\n</code></pre> <p>Hash a plain-text password using the configured crypt context.</p> <p>Parameters:</p> Name Type Description Default <code>password</code> <code>str</code> <p>The plain-text password to hash.</p> required <p>Returns:</p> Type Description <code>str</code> <p>The secure hash string.</p>"},{"location":"jwtlib/security/#jwtlib.security.verify_password","title":"verify_password","text":"<pre><code>verify_password(plain_password: str, hashed_password: str) -&gt; bool\n</code></pre> <p>Verify a plain-text password against a stored hash.</p> <p>Parameters:</p> Name Type Description Default <code>plain_password</code> <code>str</code> <p>The unhashed password provided by the user.</p> required <code>hashed_password</code> <code>str</code> <p>The secure hash to verify against.</p> required <p>Returns:</p> Type Description <code>bool</code> <p>True if the password is valid, False otherwise.</p>"},{"location":"jwtlib/utils/","title":"Utils","text":""},{"location":"jwtlib/utils/#jwtlib.utils","title":"jwtlib.utils","text":""},{"location":"jwtlib/utils/#jwtlib.utils--auth-utilities-token-validation-and-user-resolution","title":"Auth Utilities: Token validation and user resolution","text":"<p>This module provides high-level helpers for validating JWT payloads and resolving users, intended for use in dependency injection or middleware.</p>"},{"location":"jwtlib/utils/#jwtlib.utils.get_current_user","title":"get_current_user  <code>async</code>","text":"<pre><code>get_current_user(token: str, repo: Optional[UserRepository] = None) -&gt; PublicUser\n</code></pre> <p>Validate token and return authenticated public user.</p> <p>Raises:</p> Type Description <code>InvalidToken</code> <p>If the token is missing, malformed, or invalid.</p> <code>UserNotFound</code> <p>If the token is valid, but the user does not exist in the repository.</p>"},{"location":"jwtlib/utils/#jwtlib.utils.get_validated_token_payload","title":"get_validated_token_payload","text":"<pre><code>get_validated_token_payload(token: str) -&gt; TokenPayload\n</code></pre> <p>Validate a JWT and return a typed payload.</p> <p>Raises:</p> Type Description <code>JWTError</code> <p>if the token is invalid or malformed</p>"},{"location":"jwtlib/models/","title":"Models","text":""},{"location":"jwtlib/models/#jwtlib.models","title":"jwtlib.models","text":""},{"location":"jwtlib/models/#jwtlib.models--jwtlib-models-structured-data-for-authentication","title":"jwtlib Models: Structured Data for Authentication","text":"<p>This package defines the core data models used by <code>jwtlib</code>. These models are categorized into request payloads, response objects, persistence documents,  and security context.</p>"},{"location":"jwtlib/models/#jwtlib.models--model-categories","title":"Model Categories","text":""},{"location":"jwtlib/models/#jwtlib.models--1-api-requests","title":"1. API Requests","text":"<ul> <li>RegisterRequest: Payload for creating new user accounts.</li> <li>LoginRequest: User credentials for issuing JWTs.</li> <li>IntrospectRequest: Internal payload for service-to-service token verification.</li> </ul>"},{"location":"jwtlib/models/#jwtlib.models--2-api-responses","title":"2. API Responses","text":"<ul> <li>PublicUser: A safe, non-sensitive projection of a user profile.</li> <li>LoginResponse: Contains the issued <code>access_token</code> and the <code>PublicUser</code>.</li> <li>LogoutResponse: Instruction for clients to clear stateless session state.</li> </ul>"},{"location":"jwtlib/models/#jwtlib.models--3-internal-security","title":"3. Internal &amp; Security","text":"<ul> <li>User: The MongoDB-backed persistence model (Confined to repository layer).</li> <li>TokenPayload: Decoded claims from a validated JWT (sub, exp).</li> <li>IntrospectResponse: Structured result of a token validity check.</li> </ul>"},{"location":"jwtlib/models/#jwtlib.models--usage-patterns","title":"Usage Patterns","text":""},{"location":"jwtlib/models/#jwtlib.models--validating-an-auth-request","title":"Validating an Auth Request","text":"<pre><code>from jwtlib.models import LoginRequest\nfrom pydantic import ValidationError\n\ntry:\n    auth_data = LoginRequest(username=\"tester\", password=\"secure_password\")\nexcept ValidationError as e:\n    print(f\"Invalid request data: {e.json()}\")\n</code></pre>"},{"location":"jwtlib/models/#jwtlib.models--projecting-a-user-to-public-view","title":"Projecting a User to Public View","text":"<pre><code>from jwtlib.models import User, PublicUser\n\n# Assuming 'db_user' is an instance of User fetched from MongoDB\nuser_profile = PublicUser.model_validate(db_user, from_attributes=True)\nprint(f\"Safe to return: {user_profile.username} ({user_profile.email})\")\n</code></pre> <p>All models are built on Pydantic v2 and provide full type safety for both static analysis (Mypy/Pyright) and runtime validation.</p>"},{"location":"jwtlib/models/#jwtlib.models.IntrospectRequest","title":"IntrospectRequest","text":"<p>               Bases: <code>BaseModel</code></p> <p>Payload for requesting token introspection.</p> <p>Used by internal services to verify the validity of a JWT and retrieve the associated public user information.</p> Fields <p>token: JWT access token to introspect.</p> Notes <ul> <li>Intended for service-to-service communication.</li> <li>Not meant for direct end-user consumption.</li> </ul>"},{"location":"jwtlib/models/#jwtlib.models.IntrospectResponse","title":"IntrospectResponse","text":"<p>               Bases: <code>BaseModel</code></p> <p>Result of a token introspection operation.</p> <p>This model communicates whether a JWT is valid and, if so, provides the associated public user information.</p> Fields <p>active: Indicates whether the token is valid and active. user: Public user details if the token is valid; otherwise null.</p> Notes <ul> <li>This model is designed to avoid raising exceptions.</li> <li>All introspection outcomes are represented as data.</li> </ul>"},{"location":"jwtlib/models/#jwtlib.models.LoginRequest","title":"LoginRequest","text":"<p>               Bases: <code>IdentityMixin</code>, <code>PasswordMixin</code></p> <p>Payload for authenticating a user and issuing a JWT.</p> <p>This model is used to verify user credentials and request an access token.</p> Fields <p>username: Username identifier. password: Plain-text password to be verified.</p> Notes <ul> <li>Successful authentication results in a LoginResponse.</li> <li>Failed authentication raises an AuthError.</li> </ul>"},{"location":"jwtlib/models/#jwtlib.models.LoginResponse","title":"LoginResponse","text":"<p>               Bases: <code>BaseModel</code></p> <p>Response returned after successful authentication.</p> <p>Contains the issued JWT access token and the authenticated user's public profile.</p> Fields <p>access_token: JWT access token for authenticated requests. user: Public profile of the authenticated user.</p> Notes <ul> <li>The token is stateless and must be stored client-side.</li> <li>Token expiration and validation are handled elsewhere.</li> </ul>"},{"location":"jwtlib/models/#jwtlib.models.LogoutResponse","title":"LogoutResponse","text":"<p>               Bases: <code>BaseModel</code></p> <p>Response returned after a logout operation.</p> <p>Since logout is stateless, this response serves only as a confirmation message instructing the client to discard its token.</p> Fields <p>message: Human-readable logout confirmation.</p>"},{"location":"jwtlib/models/#jwtlib.models.PublicUser","title":"PublicUser","text":"<p>               Bases: <code>IdentityMixin</code>, <code>ActiveStateMixin</code></p> <p>Public-facing user representation returned by authentication APIs.</p> <p>This model represents a user profile that is safe to expose outside the authentication system.</p> Fields <p>username: Unique username identifier. email: User's email address. is_active: Whether the user account is active.</p> Notes <ul> <li>Contains no sensitive data.</li> <li>Can be constructed from persistence models via <code>from_attributes</code>.</li> </ul>"},{"location":"jwtlib/models/#jwtlib.models.RegisterRequest","title":"RegisterRequest","text":"<p>               Bases: <code>IdentityMixin</code>, <code>PasswordMixin</code></p> <p>Payload for registering a new user account.</p> <p>This model contains the minimum required identity and credential information to create a new user.</p> Fields <p>username: Unique username identifier. email: User's email address. password: Plain-text password (to be hashed by the repository layer).</p> Notes <ul> <li>Validation and normalization handled by mixins.</li> <li>This model is never returned in responses.</li> </ul>"},{"location":"jwtlib/models/#jwtlib.models.TokenPayload","title":"TokenPayload","text":"<p>               Bases: <code>BaseModel</code></p> <p>Decoded JWT payload.</p> <p>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.</p> Fields <p>sub: Subject claim identifying the user (typically a username or user ID). exp: Expiration time as a Unix timestamp (seconds since epoch).</p> Notes <ul> <li>This model assumes the JWT signature has already been verified.</li> <li>No authorization decisions should be made solely on this model.</li> <li>Additional claims may exist but are intentionally ignored.</li> </ul>"},{"location":"jwtlib/models/#jwtlib.models.User","title":"User","text":"<p>               Bases: <code>BaseDocument</code>, <code>IdentityMixin</code>, <code>ActiveStateMixin</code></p> <p>Internal user persistence model.</p> <p>Represents a user record as stored in the database. This model includes sensitive fields and is strictly confined to the persistence layer.</p> Fields <p>hashed_password: Secure hash of the user's password.</p> Notes <ul> <li>This model MUST NOT be returned from authentication APIs.</li> <li>Consumers should use <code>PublicUser</code> instead.</li> <li>Password verification is handled by the repository layer.</li> <li>Inherits identity and active-state behavior via mixins.</li> </ul>"},{"location":"jwtlib/models/app/","title":"App","text":""},{"location":"jwtlib/models/app/#jwtlib.models.app","title":"jwtlib.models.app","text":"<p>Authentication request and response models.</p> <p>This module defines all typed data models used by the authentication library for user registration, login, logout, and token introspection.</p> <p>Model categories: - Request payloads used by authentication workflows - Public response models exposed to consumers - Introspection responses used for service-to-service authentication</p> <p>These models are: - Fully typed (Pydantic v2) - Serialization-safe - Framework-agnostic - Suitable for both internal logic and external adapters</p> <p>Persistence-layer models are intentionally excluded, except where explicitly adapted into public representations.</p>"},{"location":"jwtlib/models/app/#jwtlib.models.app.IntrospectRequest","title":"IntrospectRequest","text":"<p>               Bases: <code>BaseModel</code></p> <p>Payload for requesting token introspection.</p> <p>Used by internal services to verify the validity of a JWT and retrieve the associated public user information.</p> Fields <p>token: JWT access token to introspect.</p> Notes <ul> <li>Intended for service-to-service communication.</li> <li>Not meant for direct end-user consumption.</li> </ul>"},{"location":"jwtlib/models/app/#jwtlib.models.app.IntrospectResponse","title":"IntrospectResponse","text":"<p>               Bases: <code>BaseModel</code></p> <p>Result of a token introspection operation.</p> <p>This model communicates whether a JWT is valid and, if so, provides the associated public user information.</p> Fields <p>active: Indicates whether the token is valid and active. user: Public user details if the token is valid; otherwise null.</p> Notes <ul> <li>This model is designed to avoid raising exceptions.</li> <li>All introspection outcomes are represented as data.</li> </ul>"},{"location":"jwtlib/models/app/#jwtlib.models.app.LoginRequest","title":"LoginRequest","text":"<p>               Bases: <code>IdentityMixin</code>, <code>PasswordMixin</code></p> <p>Payload for authenticating a user and issuing a JWT.</p> <p>This model is used to verify user credentials and request an access token.</p> Fields <p>username: Username identifier. password: Plain-text password to be verified.</p> Notes <ul> <li>Successful authentication results in a LoginResponse.</li> <li>Failed authentication raises an AuthError.</li> </ul>"},{"location":"jwtlib/models/app/#jwtlib.models.app.LoginResponse","title":"LoginResponse","text":"<p>               Bases: <code>BaseModel</code></p> <p>Response returned after successful authentication.</p> <p>Contains the issued JWT access token and the authenticated user's public profile.</p> Fields <p>access_token: JWT access token for authenticated requests. user: Public profile of the authenticated user.</p> Notes <ul> <li>The token is stateless and must be stored client-side.</li> <li>Token expiration and validation are handled elsewhere.</li> </ul>"},{"location":"jwtlib/models/app/#jwtlib.models.app.LogoutResponse","title":"LogoutResponse","text":"<p>               Bases: <code>BaseModel</code></p> <p>Response returned after a logout operation.</p> <p>Since logout is stateless, this response serves only as a confirmation message instructing the client to discard its token.</p> Fields <p>message: Human-readable logout confirmation.</p>"},{"location":"jwtlib/models/app/#jwtlib.models.app.PublicUser","title":"PublicUser","text":"<p>               Bases: <code>IdentityMixin</code>, <code>ActiveStateMixin</code></p> <p>Public-facing user representation returned by authentication APIs.</p> <p>This model represents a user profile that is safe to expose outside the authentication system.</p> Fields <p>username: Unique username identifier. email: User's email address. is_active: Whether the user account is active.</p> Notes <ul> <li>Contains no sensitive data.</li> <li>Can be constructed from persistence models via <code>from_attributes</code>.</li> </ul>"},{"location":"jwtlib/models/app/#jwtlib.models.app.RegisterRequest","title":"RegisterRequest","text":"<p>               Bases: <code>IdentityMixin</code>, <code>PasswordMixin</code></p> <p>Payload for registering a new user account.</p> <p>This model contains the minimum required identity and credential information to create a new user.</p> Fields <p>username: Unique username identifier. email: User's email address. password: Plain-text password (to be hashed by the repository layer).</p> Notes <ul> <li>Validation and normalization handled by mixins.</li> <li>This model is never returned in responses.</li> </ul>"},{"location":"jwtlib/models/common/","title":"Common","text":""},{"location":"jwtlib/models/common/#jwtlib.models.common","title":"jwtlib.models.common","text":""},{"location":"jwtlib/models/mongo/","title":"Mongo","text":""},{"location":"jwtlib/models/mongo/#jwtlib.models.mongo","title":"jwtlib.models.mongo","text":"<p>Persistence-layer user model.</p> <p>This module defines the internal database representation of a user. It is used exclusively by the repository and persistence layers and must never be exposed directly to consumers.</p> <p>Public-facing user data is provided via dedicated projection models.</p>"},{"location":"jwtlib/models/mongo/#jwtlib.models.mongo.User","title":"User","text":"<p>               Bases: <code>BaseDocument</code>, <code>IdentityMixin</code>, <code>ActiveStateMixin</code></p> <p>Internal user persistence model.</p> <p>Represents a user record as stored in the database. This model includes sensitive fields and is strictly confined to the persistence layer.</p> Fields <p>hashed_password: Secure hash of the user's password.</p> Notes <ul> <li>This model MUST NOT be returned from authentication APIs.</li> <li>Consumers should use <code>PublicUser</code> instead.</li> <li>Password verification is handled by the repository layer.</li> <li>Inherits identity and active-state behavior via mixins.</li> </ul>"},{"location":"jwtlib/models/security/","title":"Security","text":""},{"location":"jwtlib/models/security/#jwtlib.models.security","title":"jwtlib.models.security","text":"<p>JWT token payload models.</p> <p>This module defines typed representations of decoded JWT payloads used internally for token validation and user resolution.</p>"},{"location":"jwtlib/models/security/#jwtlib.models.security.TokenPayload","title":"TokenPayload","text":"<p>               Bases: <code>BaseModel</code></p> <p>Decoded JWT payload.</p> <p>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.</p> Fields <p>sub: Subject claim identifying the user (typically a username or user ID). exp: Expiration time as a Unix timestamp (seconds since epoch).</p> Notes <ul> <li>This model assumes the JWT signature has already been verified.</li> <li>No authorization decisions should be made solely on this model.</li> <li>Additional claims may exist but are intentionally ignored.</li> </ul>"}]}