Vishesh 'ironeagle' Bangotra
9191de9dff
All checks were successful
continuous-integration/drone/push Build is passing
1 line
98 KiB
JSON
1 line
98 KiB
JSON
{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"jwtlib","text":"<ul> <li>Jwtlib</li> </ul>"},{"location":"#jwtlib","title":"jwtlib","text":"<p>jwtlib: A framework-agnostic JWT authentication library.</p>"},{"location":"#jwtlib--summary","title":"Summary","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--installation","title":"Installation","text":"<p>Install using pip:</p> <pre><code>pip install py-jwt\n</code></pre>"},{"location":"#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</code></pre>"},{"location":"#jwtlib--public-api","title":"Public API","text":"<p>This package re-exports the core authentication primitives. Consumers are encouraged to import from this namespace for high-level operations.</p> <p>Authentication: - register_user - login_user - logout_user - get_logged_in_user</p> <p>Introspection: - introspect_token - authenticate_request (logic-only)</p> <p>Models: - RegisterRequest / LoginRequest / LoginResponse / LogoutResponse - PublicUser - IntrospectRequest / IntrospectResponse - TokenPayload</p> <p>Exceptions: - AuthError - InvalidToken - UserNotFound</p>"},{"location":"#jwtlib-classes","title":"Classes","text":""},{"location":"#jwtlib.AuthError","title":"AuthError","text":"<p> Bases: <code>Exception</code></p> <p>Base authentication and authorization error.</p> Notes <p>Guarantees:</p> <pre><code>- All authentication-related exceptions raised by this library inherit from this class\n- Consumers may catch this exception to handle all auth failures uniformly\n</code></pre>"},{"location":"#jwtlib.IntrospectRequest","title":"IntrospectRequest","text":"<p> Bases: <code>BaseModel</code></p> <p>Payload for requesting token introspection.</p> <p>Attributes:</p> Name Type Description <code>token</code> <code>str</code> <p>JWT access token to introspect.</p>"},{"location":"#jwtlib.IntrospectResponse","title":"IntrospectResponse","text":"<p> Bases: <code>BaseModel</code></p> <p>Result of a token introspection operation.</p> <p>Attributes:</p> Name Type Description <code>active</code> <code>bool</code> <p>Indicates whether the token is valid and active.</p> <code>user</code> <code>Optional[PublicUser]</code> <p>Public user details if the token is valid; otherwise null.</p>"},{"location":"#jwtlib.InvalidToken","title":"InvalidToken","text":"<p> Bases: <code>AuthError</code></p> <p>Raised when a JWT is missing, malformed, expired, or invalid.</p> Notes <p>Guarantees:</p> <pre><code>- This error indicates that the provided token cannot be used to authenticate a request\n</code></pre>"},{"location":"#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>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Username identifier.</p> <code>password</code> <code>str</code> <p>Plain-text password to be verified.</p>"},{"location":"#jwtlib.LoginResponse","title":"LoginResponse","text":"<p> Bases: <code>BaseModel</code></p> <p>Response returned after successful authentication.</p> <p>Attributes:</p> Name Type Description <code>access_token</code> <code>str</code> <p>JWT access token for authenticated requests.</p> <code>user</code> <code>PublicUser</code> <p>Public profile of the authenticated user.</p>"},{"location":"#jwtlib.LogoutResponse","title":"LogoutResponse","text":"<p> Bases: <code>BaseModel</code></p> <p>Response returned after a logout operation.</p> <p>Attributes:</p> Name Type Description <code>message</code> <code>str</code> <p>Human-readable logout confirmation.</p>"},{"location":"#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>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Unique username identifier.</p> <code>email</code> <code>EmailStr</code> <p>User's email address.</p> <code>is_active</code> <code>bool</code> <p>Whether the user account is active.</p>"},{"location":"#jwtlib.RegisterRequest","title":"RegisterRequest","text":"<p> Bases: <code>IdentityMixin</code>, <code>PasswordMixin</code></p> <p>Payload for registering a new user account.</p> <p>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Unique username identifier.</p> <code>email</code> <code>EmailStr</code> <p>User's email address.</p> <code>password</code> <code>str</code> <p>Plain-text password (to be hashed by the repository layer).</p>"},{"location":"#jwtlib.TokenPayload","title":"TokenPayload","text":"<p> Bases: <code>BaseModel</code></p> <p>Decoded JWT payload.</p> <p>Attributes:</p> Name Type Description <code>sub</code> <code>str</code> <p>Subject claim identifying the user (typically a username or user ID).</p> <code>exp</code> <code>int</code> <p>Expiration time as a Unix timestamp (seconds since epoch).</p> Notes <p>Responsibilities:</p> <pre><code>- 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.\n</code></pre> <p>Guarantees:</p> <pre><code>- 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.\n</code></pre>"},{"location":"#jwtlib.User","title":"User","text":"<p> Bases: <code>BaseDocument</code>, <code>IdentityMixin</code>, <code>ActiveStateMixin</code></p> <p>Internal user persistence model.</p> <p>Attributes:</p> Name Type Description <code>hashed_password</code> <code>str</code> <p>Secure hash of the user's password.</p> Notes <p>Responsibilities:</p> <pre><code>- Represents a user record as stored in the database. Includes sensitive fields and is strictly confined to the persistence layer.\n</code></pre> <p>Guarantees:</p> <pre><code>- This model MUST NOT be returned from authentication APIs. Consumers should use `PublicUser` instead. Password verification is handled by the repository layer.\n</code></pre>"},{"location":"#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> Notes <p>Guarantees:</p> <pre><code>- Indicates that authentication succeeded at the token level, but the associated user record could not be resolved\n</code></pre>"},{"location":"#jwtlib-functions","title":"Functions","text":""},{"location":"#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]) -> Optional[PublicUser]\n</code></pre> <p>Authenticate an incoming request using 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>str | None</code> <p>JWT access token provided by the caller.</p> required <p>Returns:</p> Type Description <code>Optional[PublicUser]</code> <p>PublicUser | None: PublicUser if authentication succeeds; 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 <p>Responsibilities:</p> <pre><code>- Determines whether authentication should be skipped for the given request context and, if not, resolves the authenticated user via token introspection\n</code></pre> <p>Guarantees:</p> <pre><code>- This function does not parse Authorization headers; callers must supply the raw token. Access-control policy is externalized via `should_skip_authentication`.\n</code></pre>"},{"location":"#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) -> PublicUser\n</code></pre> <p>Resolve the currently authenticated user from a JWT.</p> <p>Parameters:</p> Name Type Description Default <code>token</code> <code>str</code> <p>JWT access token.</p> required <code>repo</code> <code>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> Name Type Description <code>PublicUser</code> <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.introspect_token","title":"introspect_token <code>async</code>","text":"<pre><code>introspect_token(token: str, repo: Optional[UserRepository] = None) -> IntrospectResponse\n</code></pre> <p>Introspect a JWT for service-to-service authentication.</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>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> Name Type Description <code>IntrospectResponse</code> <code>IntrospectResponse</code> <p>IntrospectResponse indicating valid token with user, invalid token, or valid token with no user.</p> Notes <p>Responsibilities:</p> <pre><code>- Validates the provided token and resolves the associated user, returning a structured introspection response suitable for internal service use\n</code></pre> <p>Guarantees:</p> <pre><code>- This function never raises authentication exceptions. Instead, it returns a typed response indicating token validity and user presence.\n</code></pre>"},{"location":"#jwtlib.login_user","title":"login_user <code>async</code>","text":"<pre><code>login_user(user: LoginRequest, repo: Optional[UserRepository] = None) -> LoginResponse\n</code></pre> <p>Authenticate a user and issue an access token.</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>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> Name Type Description <code>LoginResponse</code> <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.logout_user","title":"logout_user <code>async</code>","text":"<pre><code>logout_user() -> LogoutResponse\n</code></pre> <p>Perform a stateless logout.</p> <p>Returns:</p> Name Type Description <code>LogoutResponse</code> <code>LogoutResponse</code> <p>LogoutResponse containing a logout confirmation message.</p> Notes <p>Guarantees:</p> <pre><code>- This function does not invalidate tokens server-side. Instead, it provides a standardized response indicating that the client must discard its token.\n</code></pre>"},{"location":"#jwtlib.register_user","title":"register_user <code>async</code>","text":"<pre><code>register_user(user: RegisterRequest, repo: Optional[UserRepository] = None) -> PublicUser\n</code></pre> <p>Register a new user.</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>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> Name Type Description <code>PublicUser</code> <code>PublicUser</code> <p>The newly created user as a public user representation.</p>"},{"location":"app/","title":"App","text":""},{"location":"app/#jwtlib.app","title":"jwtlib.app","text":"<p>Application-level authentication logic.</p>"},{"location":"app/#jwtlib.app--summary","title":"Summary","text":"<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> Notes <p>Responsibilities:</p> <pre><code>- User registration and login\n- Stateless logout semantics\n- Current-user resolution from JWTs\n- Service-to-service token introspection\n</code></pre> <p>Constraints:</p> <pre><code>- This module intentionally does NOT: Define HTTP routes, manage sessions, perform request parsing or response formatting, or handle transport-level concerns.\n</code></pre>"},{"location":"app/#jwtlib.app-classes","title":"Classes","text":""},{"location":"app/#jwtlib.app-functions","title":"Functions","text":""},{"location":"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) -> PublicUser\n</code></pre> <p>Resolve the currently authenticated user from a JWT.</p> <p>Parameters:</p> Name Type Description Default <code>token</code> <code>str</code> <p>JWT access token.</p> required <code>repo</code> <code>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> Name Type Description <code>PublicUser</code> <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":"app/#jwtlib.app.introspect_token","title":"introspect_token <code>async</code>","text":"<pre><code>introspect_token(token: str, repo: Optional[UserRepository] = None) -> IntrospectResponse\n</code></pre> <p>Introspect a JWT for service-to-service authentication.</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>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> Name Type Description <code>IntrospectResponse</code> <code>IntrospectResponse</code> <p>IntrospectResponse indicating valid token with user, invalid token, or valid token with no user.</p> Notes <p>Responsibilities:</p> <pre><code>- Validates the provided token and resolves the associated user, returning a structured introspection response suitable for internal service use\n</code></pre> <p>Guarantees:</p> <pre><code>- This function never raises authentication exceptions. Instead, it returns a typed response indicating token validity and user presence.\n</code></pre>"},{"location":"app/#jwtlib.app.login_user","title":"login_user <code>async</code>","text":"<pre><code>login_user(user: LoginRequest, repo: Optional[UserRepository] = None) -> LoginResponse\n</code></pre> <p>Authenticate a user and issue an access token.</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>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> Name Type Description <code>LoginResponse</code> <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":"app/#jwtlib.app.logout_user","title":"logout_user <code>async</code>","text":"<pre><code>logout_user() -> LogoutResponse\n</code></pre> <p>Perform a stateless logout.</p> <p>Returns:</p> Name Type Description <code>LogoutResponse</code> <code>LogoutResponse</code> <p>LogoutResponse containing a logout confirmation message.</p> Notes <p>Guarantees:</p> <pre><code>- This function does not invalidate tokens server-side. Instead, it provides a standardized response indicating that the client must discard its token.\n</code></pre>"},{"location":"app/#jwtlib.app.register_user","title":"register_user <code>async</code>","text":"<pre><code>register_user(user: RegisterRequest, repo: Optional[UserRepository] = None) -> PublicUser\n</code></pre> <p>Register a new user.</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>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> Name Type Description <code>PublicUser</code> <code>PublicUser</code> <p>The newly created user as a public user representation.</p>"},{"location":"exceptions/","title":"Exceptions","text":""},{"location":"exceptions/#jwtlib.exceptions","title":"jwtlib.exceptions","text":"<p>Authentication and authorization exceptions.</p>"},{"location":"exceptions/#jwtlib.exceptions--summary","title":"Summary","text":"<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":"exceptions/#jwtlib.exceptions-classes","title":"Classes","text":""},{"location":"exceptions/#jwtlib.exceptions.AuthError","title":"AuthError","text":"<p> Bases: <code>Exception</code></p> <p>Base authentication and authorization error.</p> Notes <p>Guarantees:</p> <pre><code>- All authentication-related exceptions raised by this library inherit from this class\n- Consumers may catch this exception to handle all auth failures uniformly\n</code></pre>"},{"location":"exceptions/#jwtlib.exceptions.AuthServiceUnavailable","title":"AuthServiceUnavailable","text":"<p> Bases: <code>AuthError</code></p> <p>Raised when the authentication service cannot be reached.</p> Notes <p>Guarantees:</p> <pre><code>- Indicates a network failure, timeout, or unexpected error while communicating with the auth service\n</code></pre>"},{"location":"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> Notes <p>Guarantees:</p> <pre><code>- Indicates that the header is not present or does not follow the expected `Bearer <token>` format\n</code></pre>"},{"location":"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> Notes <p>Guarantees:</p> <pre><code>- This error indicates that the provided token cannot be used to authenticate a request\n</code></pre>"},{"location":"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> Notes <p>Guarantees:</p> <pre><code>- Typically used when attempting to access a protected operation without an authenticated user\n</code></pre>"},{"location":"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> Notes <p>Guarantees:</p> <pre><code>- Indicates that authentication succeeded at the token level, but the associated user record could not be resolved\n</code></pre>"},{"location":"introspection/","title":"Introspection","text":""},{"location":"introspection/#jwtlib.introspection","title":"jwtlib.introspection","text":"<p>Auth client and access-control utilities.</p>"},{"location":"introspection/#jwtlib.introspection--summary","title":"Summary","text":"<p>This module provides pure authentication and authorization logic for validating JWTs via service-to-service introspection and resolving authenticated users.</p> Notes <p>Responsibilities:</p> <pre><code>- Calling the auth service introspection endpoint\n- Translating introspection responses into typed user models\n- Enforcing access control decisions at the logic layer\n</code></pre> <p>Constraints:</p> <pre><code>- This module intentionally does NOT: Parse HTTP requests or headers, implement authentication policies, or perform JWT signature verification locally.\n</code></pre>"},{"location":"introspection/#jwtlib.introspection-classes","title":"Classes","text":""},{"location":"introspection/#jwtlib.introspection-functions","title":"Functions","text":""},{"location":"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]) -> Optional[PublicUser]\n</code></pre> <p>Authenticate an incoming request using 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>str | None</code> <p>JWT access token provided by the caller.</p> required <p>Returns:</p> Type Description <code>Optional[PublicUser]</code> <p>PublicUser | None: PublicUser if authentication succeeds; 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 <p>Responsibilities:</p> <pre><code>- Determines whether authentication should be skipped for the given request context and, if not, resolves the authenticated user via token introspection\n</code></pre> <p>Guarantees:</p> <pre><code>- This function does not parse Authorization headers; callers must supply the raw token. Access-control policy is externalized via `should_skip_authentication`.\n</code></pre>"},{"location":"introspection/#jwtlib.introspection.introspect_token","title":"introspect_token <code>async</code>","text":"<pre><code>introspect_token(token: str) -> dict[str, Any]\n</code></pre> <p>Introspect a JWT using the external authentication service.</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>dict[str, Any]: 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 <p>Guarantees:</p> <pre><code>- This function treats the auth service as the source of truth. No local JWT validation or signature checking is performed here. The returned payload is expected to be safe for public exposure.\n</code></pre>"},{"location":"repository/","title":"Repository","text":""},{"location":"repository/#jwtlib.repository","title":"jwtlib.repository","text":"<p>UserRepository: Persistence layer for authentication.</p>"},{"location":"repository/#jwtlib.repository--summary","title":"Summary","text":"<p>This module defines the MongoDB-backed repository for managing user records, including creation, lookup, and credential verification.</p>"},{"location":"repository/#jwtlib.repository-classes","title":"Classes","text":""},{"location":"repository/#jwtlib.repository.UserRepository","title":"UserRepository","text":"<pre><code>UserRepository()\n</code></pre> <p> Bases: <code>BaseRepository[User]</code></p> <p>MongoDB-backed repository for User documents.</p> Notes <p>Responsibilities:</p> <pre><code>- Managing user persistence (CRUD)\n- Credential verification and token issuance\n</code></pre>"},{"location":"repository/#jwtlib.repository.UserRepository-functions","title":"Functions","text":""},{"location":"repository/#jwtlib.repository.UserRepository.authenticate_user","title":"authenticate_user <code>async</code>","text":"<pre><code>authenticate_user(user_auth: LoginRequest) -> 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>dict | None: A dictionary containing the access token and public user if successful, otherwise None.</p>"},{"location":"repository/#jwtlib.repository.UserRepository.create","title":"create <code>async</code>","text":"<pre><code>create(user_create: RegisterRequest) -> 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> Name Type Description <code>PublicUser</code> <code>PublicUser</code> <p>A PublicUser representation of the created user.</p>"},{"location":"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) -> 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>List[User]: A list of active User documents.</p>"},{"location":"repository/#jwtlib.repository.UserRepository.get_by_email","title":"get_by_email <code>async</code>","text":"<pre><code>get_by_email(email: str) -> 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>Optional[User]: The User document if found, otherwise None.</p>"},{"location":"repository/#jwtlib.repository.UserRepository.get_by_username","title":"get_by_username <code>async</code>","text":"<pre><code>get_by_username(username: str) -> 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>Optional[User]: The User document if found, otherwise None.</p>"},{"location":"repository/#jwtlib.repository-functions","title":"Functions","text":""},{"location":"security/","title":"Security","text":""},{"location":"security/#jwtlib.security","title":"jwtlib.security","text":"<p>Security utilities: Password hashing and JWT management.</p>"},{"location":"security/#jwtlib.security--summary","title":"Summary","text":"<p>This module provides low-level cryptographic helpers for password hashing and JWT token lifecycle management. It serves as the cryptographic engine for the authentication library.</p>"},{"location":"security/#jwtlib.security-classes","title":"Classes","text":""},{"location":"security/#jwtlib.security-functions","title":"Functions","text":""},{"location":"security/#jwtlib.security.create_access_token","title":"create_access_token","text":"<pre><code>create_access_token(data: dict, expires_delta: Optional[timedelta] = None) -> 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>timedelta</code> <p>Optional expiration override.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>An encoded JWT string.</p>"},{"location":"security/#jwtlib.security.get_jwt_payload","title":"get_jwt_payload","text":"<pre><code>get_jwt_payload(token: str) -> TokenPayload\n</code></pre> <p>Decode and validate a JWT, returning a strongly-typed payload.</p> <p>Parameters:</p> Name Type Description Default <code>token</code> <code>str</code> <p>The JWT string to decode.</p> required <p>Returns:</p> Name Type Description <code>TokenPayload</code> <code>TokenPayload</code> <p>The decoded and typed token payload.</p> <p>Raises:</p> Type Description <code>JWTError</code> <p>If the token is invalid, expired, or malformed.</p>"},{"location":"security/#jwtlib.security.hash_password","title":"hash_password","text":"<pre><code>hash_password(password: str) -> 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> Name Type Description <code>str</code> <code>str</code> <p>The secure hash string.</p>"},{"location":"security/#jwtlib.security.verify_password","title":"verify_password","text":"<pre><code>verify_password(plain_password: str, hashed_password: str) -> 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> Name Type Description <code>bool</code> <code>bool</code> <p>True if the password is valid, False otherwise.</p>"},{"location":"utils/","title":"Utils","text":""},{"location":"utils/#jwtlib.utils","title":"jwtlib.utils","text":"<p>Auth Utilities: Token validation and user resolution.</p>"},{"location":"utils/#jwtlib.utils--summary","title":"Summary","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":"utils/#jwtlib.utils-classes","title":"Classes","text":""},{"location":"utils/#jwtlib.utils-functions","title":"Functions","text":""},{"location":"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) -> PublicUser\n</code></pre> <p>Validate token and return authenticated public user.</p> <p>Parameters:</p> Name Type Description Default <code>token</code> <code>str</code> <p>The JWT string to validate.</p> required <code>repo</code> <code>UserRepository</code> <p>The user repository to use for resolution.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>PublicUser</code> <code>PublicUser</code> <p>The resolved and validated user object.</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":"utils/#jwtlib.utils.get_user_repository","title":"get_user_repository","text":"<pre><code>get_user_repository() -> UserRepository\n</code></pre> <p>Return a singleton or new instance of the UserRepository.</p> <p>Returns:</p> Name Type Description <code>UserRepository</code> <code>UserRepository</code> <p>The user repository instance.</p>"},{"location":"utils/#jwtlib.utils.get_validated_token_payload","title":"get_validated_token_payload","text":"<pre><code>get_validated_token_payload(token: str) -> TokenPayload\n</code></pre> <p>Validate a JWT and return a typed payload.</p> <p>Parameters:</p> Name Type Description Default <code>token</code> <code>str</code> <p>The JWT string to validate.</p> required <p>Returns:</p> Name Type Description <code>TokenPayload</code> <code>TokenPayload</code> <p>The validated and typed token payload.</p> <p>Raises:</p> Type Description <code>JWTError</code> <p>If the token is invalid or malformed.</p>"},{"location":"jwtlib/","title":"Jwtlib","text":"<ul> <li>App</li> <li>Exceptions</li> <li>Introspection</li> <li>Models</li> <li>Repository</li> <li>Security</li> <li>Utils</li> </ul>"},{"location":"jwtlib/#jwtlib","title":"jwtlib","text":"<p>jwtlib: A framework-agnostic JWT authentication library.</p>"},{"location":"jwtlib/#jwtlib--summary","title":"Summary","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--installation","title":"Installation","text":"<p>Install using pip:</p> <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</code></pre>"},{"location":"jwtlib/#jwtlib--public-api","title":"Public API","text":"<p>This package re-exports the core authentication primitives. Consumers are encouraged to import from this namespace for high-level operations.</p> <p>Authentication: - register_user - login_user - logout_user - get_logged_in_user</p> <p>Introspection: - introspect_token - authenticate_request (logic-only)</p> <p>Models: - RegisterRequest / LoginRequest / LoginResponse / LogoutResponse - PublicUser - IntrospectRequest / IntrospectResponse - TokenPayload</p> <p>Exceptions: - AuthError - InvalidToken - UserNotFound</p>"},{"location":"jwtlib/#jwtlib-classes","title":"Classes","text":""},{"location":"jwtlib/#jwtlib.AuthError","title":"AuthError","text":"<p> Bases: <code>Exception</code></p> <p>Base authentication and authorization error.</p> Notes <p>Guarantees:</p> <pre><code>- All authentication-related exceptions raised by this library inherit from this class\n- Consumers may catch this exception to handle all auth failures uniformly\n</code></pre>"},{"location":"jwtlib/#jwtlib.IntrospectRequest","title":"IntrospectRequest","text":"<p> Bases: <code>BaseModel</code></p> <p>Payload for requesting token introspection.</p> <p>Attributes:</p> Name Type Description <code>token</code> <code>str</code> <p>JWT access token to introspect.</p>"},{"location":"jwtlib/#jwtlib.IntrospectResponse","title":"IntrospectResponse","text":"<p> Bases: <code>BaseModel</code></p> <p>Result of a token introspection operation.</p> <p>Attributes:</p> Name Type Description <code>active</code> <code>bool</code> <p>Indicates whether the token is valid and active.</p> <code>user</code> <code>Optional[PublicUser]</code> <p>Public user details if the token is valid; otherwise null.</p>"},{"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> Notes <p>Guarantees:</p> <pre><code>- This error indicates that the provided token cannot be used to authenticate a request\n</code></pre>"},{"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>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Username identifier.</p> <code>password</code> <code>str</code> <p>Plain-text password to be verified.</p>"},{"location":"jwtlib/#jwtlib.LoginResponse","title":"LoginResponse","text":"<p> Bases: <code>BaseModel</code></p> <p>Response returned after successful authentication.</p> <p>Attributes:</p> Name Type Description <code>access_token</code> <code>str</code> <p>JWT access token for authenticated requests.</p> <code>user</code> <code>PublicUser</code> <p>Public profile of the authenticated user.</p>"},{"location":"jwtlib/#jwtlib.LogoutResponse","title":"LogoutResponse","text":"<p> Bases: <code>BaseModel</code></p> <p>Response returned after a logout operation.</p> <p>Attributes:</p> Name Type Description <code>message</code> <code>str</code> <p>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>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Unique username identifier.</p> <code>email</code> <code>EmailStr</code> <p>User's email address.</p> <code>is_active</code> <code>bool</code> <p>Whether the user account is active.</p>"},{"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>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Unique username identifier.</p> <code>email</code> <code>EmailStr</code> <p>User's email address.</p> <code>password</code> <code>str</code> <p>Plain-text password (to be hashed by the repository layer).</p>"},{"location":"jwtlib/#jwtlib.TokenPayload","title":"TokenPayload","text":"<p> Bases: <code>BaseModel</code></p> <p>Decoded JWT payload.</p> <p>Attributes:</p> Name Type Description <code>sub</code> <code>str</code> <p>Subject claim identifying the user (typically a username or user ID).</p> <code>exp</code> <code>int</code> <p>Expiration time as a Unix timestamp (seconds since epoch).</p> Notes <p>Responsibilities:</p> <pre><code>- 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.\n</code></pre> <p>Guarantees:</p> <pre><code>- 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.\n</code></pre>"},{"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>Attributes:</p> Name Type Description <code>hashed_password</code> <code>str</code> <p>Secure hash of the user's password.</p> Notes <p>Responsibilities:</p> <pre><code>- Represents a user record as stored in the database. Includes sensitive fields and is strictly confined to the persistence layer.\n</code></pre> <p>Guarantees:</p> <pre><code>- This model MUST NOT be returned from authentication APIs. Consumers should use `PublicUser` instead. Password verification is handled by the repository layer.\n</code></pre>"},{"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> Notes <p>Guarantees:</p> <pre><code>- Indicates that authentication succeeded at the token level, but the associated user record could not be resolved\n</code></pre>"},{"location":"jwtlib/#jwtlib-functions","title":"Functions","text":""},{"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]) -> Optional[PublicUser]\n</code></pre> <p>Authenticate an incoming request using 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>str | None</code> <p>JWT access token provided by the caller.</p> required <p>Returns:</p> Type Description <code>Optional[PublicUser]</code> <p>PublicUser | None: PublicUser if authentication succeeds; 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 <p>Responsibilities:</p> <pre><code>- Determines whether authentication should be skipped for the given request context and, if not, resolves the authenticated user via token introspection\n</code></pre> <p>Guarantees:</p> <pre><code>- This function does not parse Authorization headers; callers must supply the raw token. Access-control policy is externalized via `should_skip_authentication`.\n</code></pre>"},{"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) -> PublicUser\n</code></pre> <p>Resolve the currently authenticated user from a JWT.</p> <p>Parameters:</p> Name Type Description Default <code>token</code> <code>str</code> <p>JWT access token.</p> required <code>repo</code> <code>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> Name Type Description <code>PublicUser</code> <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) -> IntrospectResponse\n</code></pre> <p>Introspect a JWT for service-to-service authentication.</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>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> Name Type Description <code>IntrospectResponse</code> <code>IntrospectResponse</code> <p>IntrospectResponse indicating valid token with user, invalid token, or valid token with no user.</p> Notes <p>Responsibilities:</p> <pre><code>- Validates the provided token and resolves the associated user, returning a structured introspection response suitable for internal service use\n</code></pre> <p>Guarantees:</p> <pre><code>- This function never raises authentication exceptions. Instead, it returns a typed response indicating token validity and user presence.\n</code></pre>"},{"location":"jwtlib/#jwtlib.login_user","title":"login_user <code>async</code>","text":"<pre><code>login_user(user: LoginRequest, repo: Optional[UserRepository] = None) -> LoginResponse\n</code></pre> <p>Authenticate a user and issue an access token.</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>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> Name Type Description <code>LoginResponse</code> <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() -> LogoutResponse\n</code></pre> <p>Perform a stateless logout.</p> <p>Returns:</p> Name Type Description <code>LogoutResponse</code> <code>LogoutResponse</code> <p>LogoutResponse containing a logout confirmation message.</p> Notes <p>Guarantees:</p> <pre><code>- This function does not invalidate tokens server-side. Instead, it provides a standardized response indicating that the client must discard its token.\n</code></pre>"},{"location":"jwtlib/#jwtlib.register_user","title":"register_user <code>async</code>","text":"<pre><code>register_user(user: RegisterRequest, repo: Optional[UserRepository] = None) -> PublicUser\n</code></pre> <p>Register a new user.</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>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> Name Type Description <code>PublicUser</code> <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>"},{"location":"jwtlib/app/#jwtlib.app--summary","title":"Summary","text":"<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> Notes <p>Responsibilities:</p> <pre><code>- User registration and login\n- Stateless logout semantics\n- Current-user resolution from JWTs\n- Service-to-service token introspection\n</code></pre> <p>Constraints:</p> <pre><code>- This module intentionally does NOT: Define HTTP routes, manage sessions, perform request parsing or response formatting, or handle transport-level concerns.\n</code></pre>"},{"location":"jwtlib/app/#jwtlib.app-classes","title":"Classes","text":""},{"location":"jwtlib/app/#jwtlib.app-functions","title":"Functions","text":""},{"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) -> PublicUser\n</code></pre> <p>Resolve the currently authenticated user from a JWT.</p> <p>Parameters:</p> Name Type Description Default <code>token</code> <code>str</code> <p>JWT access token.</p> required <code>repo</code> <code>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> Name Type Description <code>PublicUser</code> <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) -> IntrospectResponse\n</code></pre> <p>Introspect a JWT for service-to-service authentication.</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>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> Name Type Description <code>IntrospectResponse</code> <code>IntrospectResponse</code> <p>IntrospectResponse indicating valid token with user, invalid token, or valid token with no user.</p> Notes <p>Responsibilities:</p> <pre><code>- Validates the provided token and resolves the associated user, returning a structured introspection response suitable for internal service use\n</code></pre> <p>Guarantees:</p> <pre><code>- This function never raises authentication exceptions. Instead, it returns a typed response indicating token validity and user presence.\n</code></pre>"},{"location":"jwtlib/app/#jwtlib.app.login_user","title":"login_user <code>async</code>","text":"<pre><code>login_user(user: LoginRequest, repo: Optional[UserRepository] = None) -> LoginResponse\n</code></pre> <p>Authenticate a user and issue an access token.</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>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> Name Type Description <code>LoginResponse</code> <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() -> LogoutResponse\n</code></pre> <p>Perform a stateless logout.</p> <p>Returns:</p> Name Type Description <code>LogoutResponse</code> <code>LogoutResponse</code> <p>LogoutResponse containing a logout confirmation message.</p> Notes <p>Guarantees:</p> <pre><code>- This function does not invalidate tokens server-side. Instead, it provides a standardized response indicating that the client must discard its token.\n</code></pre>"},{"location":"jwtlib/app/#jwtlib.app.register_user","title":"register_user <code>async</code>","text":"<pre><code>register_user(user: RegisterRequest, repo: Optional[UserRepository] = None) -> PublicUser\n</code></pre> <p>Register a new user.</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>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> Name Type Description <code>PublicUser</code> <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>"},{"location":"jwtlib/exceptions/#jwtlib.exceptions--summary","title":"Summary","text":"<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-classes","title":"Classes","text":""},{"location":"jwtlib/exceptions/#jwtlib.exceptions.AuthError","title":"AuthError","text":"<p> Bases: <code>Exception</code></p> <p>Base authentication and authorization error.</p> Notes <p>Guarantees:</p> <pre><code>- All authentication-related exceptions raised by this library inherit from this class\n- Consumers may catch this exception to handle all auth failures uniformly\n</code></pre>"},{"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> Notes <p>Guarantees:</p> <pre><code>- Indicates a network failure, timeout, or unexpected error while communicating with the auth service\n</code></pre>"},{"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> Notes <p>Guarantees:</p> <pre><code>- Indicates that the header is not present or does not follow the expected `Bearer <token>` format\n</code></pre>"},{"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> Notes <p>Guarantees:</p> <pre><code>- This error indicates that the provided token cannot be used to authenticate a request\n</code></pre>"},{"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> Notes <p>Guarantees:</p> <pre><code>- Typically used when attempting to access a protected operation without an authenticated user\n</code></pre>"},{"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> Notes <p>Guarantees:</p> <pre><code>- Indicates that authentication succeeded at the token level, but the associated user record could not be resolved\n</code></pre>"},{"location":"jwtlib/introspection/","title":"Introspection","text":""},{"location":"jwtlib/introspection/#jwtlib.introspection","title":"jwtlib.introspection","text":"<p>Auth client and access-control utilities.</p>"},{"location":"jwtlib/introspection/#jwtlib.introspection--summary","title":"Summary","text":"<p>This module provides pure authentication and authorization logic for validating JWTs via service-to-service introspection and resolving authenticated users.</p> Notes <p>Responsibilities:</p> <pre><code>- Calling the auth service introspection endpoint\n- Translating introspection responses into typed user models\n- Enforcing access control decisions at the logic layer\n</code></pre> <p>Constraints:</p> <pre><code>- This module intentionally does NOT: Parse HTTP requests or headers, implement authentication policies, or perform JWT signature verification locally.\n</code></pre>"},{"location":"jwtlib/introspection/#jwtlib.introspection-classes","title":"Classes","text":""},{"location":"jwtlib/introspection/#jwtlib.introspection-functions","title":"Functions","text":""},{"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]) -> Optional[PublicUser]\n</code></pre> <p>Authenticate an incoming request using 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>str | None</code> <p>JWT access token provided by the caller.</p> required <p>Returns:</p> Type Description <code>Optional[PublicUser]</code> <p>PublicUser | None: PublicUser if authentication succeeds; 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 <p>Responsibilities:</p> <pre><code>- Determines whether authentication should be skipped for the given request context and, if not, resolves the authenticated user via token introspection\n</code></pre> <p>Guarantees:</p> <pre><code>- This function does not parse Authorization headers; callers must supply the raw token. Access-control policy is externalized via `should_skip_authentication`.\n</code></pre>"},{"location":"jwtlib/introspection/#jwtlib.introspection.introspect_token","title":"introspect_token <code>async</code>","text":"<pre><code>introspect_token(token: str) -> dict[str, Any]\n</code></pre> <p>Introspect a JWT using the external authentication service.</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>dict[str, Any]: 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 <p>Guarantees:</p> <pre><code>- This function treats the auth service as the source of truth. No local JWT validation or signature checking is performed here. The returned payload is expected to be safe for public exposure.\n</code></pre>"},{"location":"jwtlib/repository/","title":"Repository","text":""},{"location":"jwtlib/repository/#jwtlib.repository","title":"jwtlib.repository","text":"<p>UserRepository: Persistence layer for authentication.</p>"},{"location":"jwtlib/repository/#jwtlib.repository--summary","title":"Summary","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-classes","title":"Classes","text":""},{"location":"jwtlib/repository/#jwtlib.repository.UserRepository","title":"UserRepository","text":"<pre><code>UserRepository()\n</code></pre> <p> Bases: <code>BaseRepository[User]</code></p> <p>MongoDB-backed repository for User documents.</p> Notes <p>Responsibilities:</p> <pre><code>- Managing user persistence (CRUD)\n- Credential verification and token issuance\n</code></pre>"},{"location":"jwtlib/repository/#jwtlib.repository.UserRepository-functions","title":"Functions","text":""},{"location":"jwtlib/repository/#jwtlib.repository.UserRepository.authenticate_user","title":"authenticate_user <code>async</code>","text":"<pre><code>authenticate_user(user_auth: LoginRequest) -> 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>dict | None: A dictionary containing the access token and public user if successful, otherwise None.</p>"},{"location":"jwtlib/repository/#jwtlib.repository.UserRepository.create","title":"create <code>async</code>","text":"<pre><code>create(user_create: RegisterRequest) -> 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> Name Type Description <code>PublicUser</code> <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) -> 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>List[User]: 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) -> 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>Optional[User]: 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) -> 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>Optional[User]: The User document if found, otherwise None.</p>"},{"location":"jwtlib/repository/#jwtlib.repository-functions","title":"Functions","text":""},{"location":"jwtlib/security/","title":"Security","text":""},{"location":"jwtlib/security/#jwtlib.security","title":"jwtlib.security","text":"<p>Security utilities: Password hashing and JWT management.</p>"},{"location":"jwtlib/security/#jwtlib.security--summary","title":"Summary","text":"<p>This module provides low-level cryptographic helpers for password hashing and JWT token lifecycle management. It serves as the cryptographic engine for the authentication library.</p>"},{"location":"jwtlib/security/#jwtlib.security-classes","title":"Classes","text":""},{"location":"jwtlib/security/#jwtlib.security-functions","title":"Functions","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) -> 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>timedelta</code> <p>Optional expiration override.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>str</code> <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) -> TokenPayload\n</code></pre> <p>Decode and validate a JWT, returning a strongly-typed payload.</p> <p>Parameters:</p> Name Type Description Default <code>token</code> <code>str</code> <p>The JWT string to decode.</p> required <p>Returns:</p> Name Type Description <code>TokenPayload</code> <code>TokenPayload</code> <p>The decoded and typed token 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) -> 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> Name Type Description <code>str</code> <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) -> 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> Name Type Description <code>bool</code> <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":"<p>Auth Utilities: Token validation and user resolution.</p>"},{"location":"jwtlib/utils/#jwtlib.utils--summary","title":"Summary","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-classes","title":"Classes","text":""},{"location":"jwtlib/utils/#jwtlib.utils-functions","title":"Functions","text":""},{"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) -> PublicUser\n</code></pre> <p>Validate token and return authenticated public user.</p> <p>Parameters:</p> Name Type Description Default <code>token</code> <code>str</code> <p>The JWT string to validate.</p> required <code>repo</code> <code>UserRepository</code> <p>The user repository to use for resolution.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>PublicUser</code> <code>PublicUser</code> <p>The resolved and validated user object.</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_user_repository","title":"get_user_repository","text":"<pre><code>get_user_repository() -> UserRepository\n</code></pre> <p>Return a singleton or new instance of the UserRepository.</p> <p>Returns:</p> Name Type Description <code>UserRepository</code> <code>UserRepository</code> <p>The user repository instance.</p>"},{"location":"jwtlib/utils/#jwtlib.utils.get_validated_token_payload","title":"get_validated_token_payload","text":"<pre><code>get_validated_token_payload(token: str) -> TokenPayload\n</code></pre> <p>Validate a JWT and return a typed payload.</p> <p>Parameters:</p> Name Type Description Default <code>token</code> <code>str</code> <p>The JWT string to validate.</p> required <p>Returns:</p> Name Type Description <code>TokenPayload</code> <code>TokenPayload</code> <p>The validated and typed token 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":"<ul> <li>App</li> <li>Common</li> <li>Mongo</li> <li>Security</li> </ul>"},{"location":"jwtlib/models/#jwtlib.models","title":"jwtlib.models","text":"<p>jwtlib Models: Structured Data for Authentication.</p>"},{"location":"jwtlib/models/#jwtlib.models--summary","title":"Summary","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":"<p>API Requests: - <code>RegisterRequest</code>: Payload for creating new user accounts. - <code>LoginRequest</code>: User credentials for issuing JWTs. - <code>IntrospectRequest</code>: Internal payload for service-to-service token verification.</p> <p>API Responses: - <code>PublicUser</code>: A safe, non-sensitive projection of a user profile. - <code>LoginResponse</code>: Contains the issued access token and the PublicUser. - <code>LogoutResponse</code>: Instruction for clients to clear stateless session state.</p> <p>Internal & Security: - <code>User</code>: The MongoDB-backed persistence model (Confined to repository layer). - <code>TokenPayload</code>: Decoded claims from a validated JWT (sub, exp). - <code>IntrospectResponse</code>: Structured result of a token validity check.</p>"},{"location":"jwtlib/models/#jwtlib.models--usage","title":"Usage","text":"<p>Validating an Auth Request:</p> <pre><code>from jwtlib.models import LoginRequest\nauth_data = LoginRequest(username=\"tester\", password=\"secure_password\")\n</code></pre> <p>Projecting a User to Public View:</p> <pre><code>from jwtlib.models import User, PublicUser\nuser_profile = PublicUser.model_validate(db_user, from_attributes=True)\n</code></pre>"},{"location":"jwtlib/models/#jwtlib.models--public-api","title":"Public API","text":"<p>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.</p> <ul> <li>LoginRequest / LoginResponse</li> <li>RegisterRequest</li> <li>LogoutResponse</li> <li>PublicUser</li> <li>IntrospectRequest / IntrospectResponse</li> <li>User (Persistence)</li> <li>TokenPayload (JWT)</li> </ul>"},{"location":"jwtlib/models/#jwtlib.models-classes","title":"Classes","text":""},{"location":"jwtlib/models/#jwtlib.models.IntrospectRequest","title":"IntrospectRequest","text":"<p> Bases: <code>BaseModel</code></p> <p>Payload for requesting token introspection.</p> <p>Attributes:</p> Name Type Description <code>token</code> <code>str</code> <p>JWT access token to introspect.</p>"},{"location":"jwtlib/models/#jwtlib.models.IntrospectResponse","title":"IntrospectResponse","text":"<p> Bases: <code>BaseModel</code></p> <p>Result of a token introspection operation.</p> <p>Attributes:</p> Name Type Description <code>active</code> <code>bool</code> <p>Indicates whether the token is valid and active.</p> <code>user</code> <code>Optional[PublicUser]</code> <p>Public user details if the token is valid; otherwise null.</p>"},{"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>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Username identifier.</p> <code>password</code> <code>str</code> <p>Plain-text password to be verified.</p>"},{"location":"jwtlib/models/#jwtlib.models.LoginResponse","title":"LoginResponse","text":"<p> Bases: <code>BaseModel</code></p> <p>Response returned after successful authentication.</p> <p>Attributes:</p> Name Type Description <code>access_token</code> <code>str</code> <p>JWT access token for authenticated requests.</p> <code>user</code> <code>PublicUser</code> <p>Public profile of the authenticated user.</p>"},{"location":"jwtlib/models/#jwtlib.models.LogoutResponse","title":"LogoutResponse","text":"<p> Bases: <code>BaseModel</code></p> <p>Response returned after a logout operation.</p> <p>Attributes:</p> Name Type Description <code>message</code> <code>str</code> <p>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>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Unique username identifier.</p> <code>email</code> <code>EmailStr</code> <p>User's email address.</p> <code>is_active</code> <code>bool</code> <p>Whether the user account is active.</p>"},{"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>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Unique username identifier.</p> <code>email</code> <code>EmailStr</code> <p>User's email address.</p> <code>password</code> <code>str</code> <p>Plain-text password (to be hashed by the repository layer).</p>"},{"location":"jwtlib/models/#jwtlib.models.TokenPayload","title":"TokenPayload","text":"<p> Bases: <code>BaseModel</code></p> <p>Decoded JWT payload.</p> <p>Attributes:</p> Name Type Description <code>sub</code> <code>str</code> <p>Subject claim identifying the user (typically a username or user ID).</p> <code>exp</code> <code>int</code> <p>Expiration time as a Unix timestamp (seconds since epoch).</p> Notes <p>Responsibilities:</p> <pre><code>- 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.\n</code></pre> <p>Guarantees:</p> <pre><code>- 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.\n</code></pre>"},{"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>Attributes:</p> Name Type Description <code>hashed_password</code> <code>str</code> <p>Secure hash of the user's password.</p> Notes <p>Responsibilities:</p> <pre><code>- Represents a user record as stored in the database. Includes sensitive fields and is strictly confined to the persistence layer.\n</code></pre> <p>Guarantees:</p> <pre><code>- This model MUST NOT be returned from authentication APIs. Consumers should use `PublicUser` instead. Password verification is handled by the repository layer.\n</code></pre>"},{"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>"},{"location":"jwtlib/models/app/#jwtlib.models.app--summary","title":"Summary","text":"<p>This module defines all typed data models used by the authentication library for user registration, login, logout, and token introspection.</p> Notes <p>Model Categories:</p> <pre><code>- Request payloads used by authentication workflows\n- Public response models exposed to consumers\n- Introspection responses used for service-to-service authentication\n</code></pre> <p>Design Principles:</p> <pre><code>- Fully typed (Pydantic v2)\n- Serialization-safe\n- Framework-agnostic\n- Suitable for both internal logic and external adapters\n</code></pre>"},{"location":"jwtlib/models/app/#jwtlib.models.app-classes","title":"Classes","text":""},{"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>Attributes:</p> Name Type Description <code>token</code> <code>str</code> <p>JWT access token to introspect.</p>"},{"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>Attributes:</p> Name Type Description <code>active</code> <code>bool</code> <p>Indicates whether the token is valid and active.</p> <code>user</code> <code>Optional[PublicUser]</code> <p>Public user details if the token is valid; otherwise null.</p>"},{"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>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Username identifier.</p> <code>password</code> <code>str</code> <p>Plain-text password to be verified.</p>"},{"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>Attributes:</p> Name Type Description <code>access_token</code> <code>str</code> <p>JWT access token for authenticated requests.</p> <code>user</code> <code>PublicUser</code> <p>Public profile of the authenticated user.</p>"},{"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>Attributes:</p> Name Type Description <code>message</code> <code>str</code> <p>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>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Unique username identifier.</p> <code>email</code> <code>EmailStr</code> <p>User's email address.</p> <code>is_active</code> <code>bool</code> <p>Whether the user account is active.</p>"},{"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>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Unique username identifier.</p> <code>email</code> <code>EmailStr</code> <p>User's email address.</p> <code>password</code> <code>str</code> <p>Plain-text password (to be hashed by the repository layer).</p>"},{"location":"jwtlib/models/common/","title":"Common","text":""},{"location":"jwtlib/models/common/#jwtlib.models.common","title":"jwtlib.models.common","text":"<p>Common Pydantic mixins for authentication models.</p>"},{"location":"jwtlib/models/common/#jwtlib.models.common--summary","title":"Summary","text":"<p>This module provides reusable mixins for identity, password, and account state. These mixes ensure consistency across internal persistence models and public-facing projection models.</p>"},{"location":"jwtlib/models/common/#jwtlib.models.common-classes","title":"Classes","text":""},{"location":"jwtlib/models/common/#jwtlib.models.common.ActiveStateMixin","title":"ActiveStateMixin","text":"<p> Bases: <code>BaseModel</code></p> <p>Mixin for entities with an active status flag.</p> <p>Attributes:</p> Name Type Description <code>is_active</code> <code>bool</code> <p>Indicates whether the account is active and allowed to authenticate.</p>"},{"location":"jwtlib/models/common/#jwtlib.models.common.IdentityMixin","title":"IdentityMixin","text":"<p> Bases: <code>BaseModel</code></p> <p>Mixin for entities with a username and email.</p> <p>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Unique username used for authentication and display.</p> <code>email</code> <code>Optional[EmailStr]</code> <p>Primary email address associated with the account.</p>"},{"location":"jwtlib/models/common/#jwtlib.models.common.PasswordMixin","title":"PasswordMixin","text":"<p> Bases: <code>BaseModel</code></p> <p>Mixin for entities with a raw password field.</p> <p>Attributes:</p> Name Type Description <code>password</code> <code>str</code> <p>User password (minimum 6 characters).</p>"},{"location":"jwtlib/models/mongo/","title":"Mongo","text":""},{"location":"jwtlib/models/mongo/#jwtlib.models.mongo","title":"jwtlib.models.mongo","text":"<p>Persistence-layer user model for MongoDB.</p>"},{"location":"jwtlib/models/mongo/#jwtlib.models.mongo--summary","title":"Summary","text":"<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-classes","title":"Classes","text":""},{"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>Attributes:</p> Name Type Description <code>hashed_password</code> <code>str</code> <p>Secure hash of the user's password.</p> Notes <p>Responsibilities:</p> <pre><code>- Represents a user record as stored in the database. Includes sensitive fields and is strictly confined to the persistence layer.\n</code></pre> <p>Guarantees:</p> <pre><code>- This model MUST NOT be returned from authentication APIs. Consumers should use `PublicUser` instead. Password verification is handled by the repository layer.\n</code></pre>"},{"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>"},{"location":"jwtlib/models/security/#jwtlib.models.security--summary","title":"Summary","text":"<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-classes","title":"Classes","text":""},{"location":"jwtlib/models/security/#jwtlib.models.security.TokenPayload","title":"TokenPayload","text":"<p> Bases: <code>BaseModel</code></p> <p>Decoded JWT payload.</p> <p>Attributes:</p> Name Type Description <code>sub</code> <code>str</code> <p>Subject claim identifying the user (typically a username or user ID).</p> <code>exp</code> <code>int</code> <p>Expiration time as a Unix timestamp (seconds since epoch).</p> Notes <p>Responsibilities:</p> <pre><code>- 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.\n</code></pre> <p>Guarantees:</p> <pre><code>- 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.\n</code></pre>"},{"location":"models/","title":"Models","text":""},{"location":"models/#jwtlib.models","title":"jwtlib.models","text":"<p>jwtlib Models: Structured Data for Authentication.</p>"},{"location":"models/#jwtlib.models--summary","title":"Summary","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":"models/#jwtlib.models--model-categories","title":"Model Categories","text":"<p>API Requests: - <code>RegisterRequest</code>: Payload for creating new user accounts. - <code>LoginRequest</code>: User credentials for issuing JWTs. - <code>IntrospectRequest</code>: Internal payload for service-to-service token verification.</p> <p>API Responses: - <code>PublicUser</code>: A safe, non-sensitive projection of a user profile. - <code>LoginResponse</code>: Contains the issued access token and the PublicUser. - <code>LogoutResponse</code>: Instruction for clients to clear stateless session state.</p> <p>Internal & Security: - <code>User</code>: The MongoDB-backed persistence model (Confined to repository layer). - <code>TokenPayload</code>: Decoded claims from a validated JWT (sub, exp). - <code>IntrospectResponse</code>: Structured result of a token validity check.</p>"},{"location":"models/#jwtlib.models--usage","title":"Usage","text":"<p>Validating an Auth Request:</p> <pre><code>from jwtlib.models import LoginRequest\nauth_data = LoginRequest(username=\"tester\", password=\"secure_password\")\n</code></pre> <p>Projecting a User to Public View:</p> <pre><code>from jwtlib.models import User, PublicUser\nuser_profile = PublicUser.model_validate(db_user, from_attributes=True)\n</code></pre>"},{"location":"models/#jwtlib.models--public-api","title":"Public API","text":"<p>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.</p> <ul> <li>LoginRequest / LoginResponse</li> <li>RegisterRequest</li> <li>LogoutResponse</li> <li>PublicUser</li> <li>IntrospectRequest / IntrospectResponse</li> <li>User (Persistence)</li> <li>TokenPayload (JWT)</li> </ul>"},{"location":"models/#jwtlib.models-classes","title":"Classes","text":""},{"location":"models/#jwtlib.models.IntrospectRequest","title":"IntrospectRequest","text":"<p> Bases: <code>BaseModel</code></p> <p>Payload for requesting token introspection.</p> <p>Attributes:</p> Name Type Description <code>token</code> <code>str</code> <p>JWT access token to introspect.</p>"},{"location":"models/#jwtlib.models.IntrospectResponse","title":"IntrospectResponse","text":"<p> Bases: <code>BaseModel</code></p> <p>Result of a token introspection operation.</p> <p>Attributes:</p> Name Type Description <code>active</code> <code>bool</code> <p>Indicates whether the token is valid and active.</p> <code>user</code> <code>Optional[PublicUser]</code> <p>Public user details if the token is valid; otherwise null.</p>"},{"location":"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>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Username identifier.</p> <code>password</code> <code>str</code> <p>Plain-text password to be verified.</p>"},{"location":"models/#jwtlib.models.LoginResponse","title":"LoginResponse","text":"<p> Bases: <code>BaseModel</code></p> <p>Response returned after successful authentication.</p> <p>Attributes:</p> Name Type Description <code>access_token</code> <code>str</code> <p>JWT access token for authenticated requests.</p> <code>user</code> <code>PublicUser</code> <p>Public profile of the authenticated user.</p>"},{"location":"models/#jwtlib.models.LogoutResponse","title":"LogoutResponse","text":"<p> Bases: <code>BaseModel</code></p> <p>Response returned after a logout operation.</p> <p>Attributes:</p> Name Type Description <code>message</code> <code>str</code> <p>Human-readable logout confirmation.</p>"},{"location":"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>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Unique username identifier.</p> <code>email</code> <code>EmailStr</code> <p>User's email address.</p> <code>is_active</code> <code>bool</code> <p>Whether the user account is active.</p>"},{"location":"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>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Unique username identifier.</p> <code>email</code> <code>EmailStr</code> <p>User's email address.</p> <code>password</code> <code>str</code> <p>Plain-text password (to be hashed by the repository layer).</p>"},{"location":"models/#jwtlib.models.TokenPayload","title":"TokenPayload","text":"<p> Bases: <code>BaseModel</code></p> <p>Decoded JWT payload.</p> <p>Attributes:</p> Name Type Description <code>sub</code> <code>str</code> <p>Subject claim identifying the user (typically a username or user ID).</p> <code>exp</code> <code>int</code> <p>Expiration time as a Unix timestamp (seconds since epoch).</p> Notes <p>Responsibilities:</p> <pre><code>- 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.\n</code></pre> <p>Guarantees:</p> <pre><code>- 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.\n</code></pre>"},{"location":"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>Attributes:</p> Name Type Description <code>hashed_password</code> <code>str</code> <p>Secure hash of the user's password.</p> Notes <p>Responsibilities:</p> <pre><code>- Represents a user record as stored in the database. Includes sensitive fields and is strictly confined to the persistence layer.\n</code></pre> <p>Guarantees:</p> <pre><code>- This model MUST NOT be returned from authentication APIs. Consumers should use `PublicUser` instead. Password verification is handled by the repository layer.\n</code></pre>"},{"location":"models/app/","title":"App","text":""},{"location":"models/app/#jwtlib.models.app","title":"jwtlib.models.app","text":"<p>Authentication request and response models.</p>"},{"location":"models/app/#jwtlib.models.app--summary","title":"Summary","text":"<p>This module defines all typed data models used by the authentication library for user registration, login, logout, and token introspection.</p> Notes <p>Model Categories:</p> <pre><code>- Request payloads used by authentication workflows\n- Public response models exposed to consumers\n- Introspection responses used for service-to-service authentication\n</code></pre> <p>Design Principles:</p> <pre><code>- Fully typed (Pydantic v2)\n- Serialization-safe\n- Framework-agnostic\n- Suitable for both internal logic and external adapters\n</code></pre>"},{"location":"models/app/#jwtlib.models.app-classes","title":"Classes","text":""},{"location":"models/app/#jwtlib.models.app.IntrospectRequest","title":"IntrospectRequest","text":"<p> Bases: <code>BaseModel</code></p> <p>Payload for requesting token introspection.</p> <p>Attributes:</p> Name Type Description <code>token</code> <code>str</code> <p>JWT access token to introspect.</p>"},{"location":"models/app/#jwtlib.models.app.IntrospectResponse","title":"IntrospectResponse","text":"<p> Bases: <code>BaseModel</code></p> <p>Result of a token introspection operation.</p> <p>Attributes:</p> Name Type Description <code>active</code> <code>bool</code> <p>Indicates whether the token is valid and active.</p> <code>user</code> <code>Optional[PublicUser]</code> <p>Public user details if the token is valid; otherwise null.</p>"},{"location":"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>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Username identifier.</p> <code>password</code> <code>str</code> <p>Plain-text password to be verified.</p>"},{"location":"models/app/#jwtlib.models.app.LoginResponse","title":"LoginResponse","text":"<p> Bases: <code>BaseModel</code></p> <p>Response returned after successful authentication.</p> <p>Attributes:</p> Name Type Description <code>access_token</code> <code>str</code> <p>JWT access token for authenticated requests.</p> <code>user</code> <code>PublicUser</code> <p>Public profile of the authenticated user.</p>"},{"location":"models/app/#jwtlib.models.app.LogoutResponse","title":"LogoutResponse","text":"<p> Bases: <code>BaseModel</code></p> <p>Response returned after a logout operation.</p> <p>Attributes:</p> Name Type Description <code>message</code> <code>str</code> <p>Human-readable logout confirmation.</p>"},{"location":"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>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Unique username identifier.</p> <code>email</code> <code>EmailStr</code> <p>User's email address.</p> <code>is_active</code> <code>bool</code> <p>Whether the user account is active.</p>"},{"location":"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>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Unique username identifier.</p> <code>email</code> <code>EmailStr</code> <p>User's email address.</p> <code>password</code> <code>str</code> <p>Plain-text password (to be hashed by the repository layer).</p>"},{"location":"models/common/","title":"Common","text":""},{"location":"models/common/#jwtlib.models.common","title":"jwtlib.models.common","text":"<p>Common Pydantic mixins for authentication models.</p>"},{"location":"models/common/#jwtlib.models.common--summary","title":"Summary","text":"<p>This module provides reusable mixins for identity, password, and account state. These mixes ensure consistency across internal persistence models and public-facing projection models.</p>"},{"location":"models/common/#jwtlib.models.common-classes","title":"Classes","text":""},{"location":"models/common/#jwtlib.models.common.ActiveStateMixin","title":"ActiveStateMixin","text":"<p> Bases: <code>BaseModel</code></p> <p>Mixin for entities with an active status flag.</p> <p>Attributes:</p> Name Type Description <code>is_active</code> <code>bool</code> <p>Indicates whether the account is active and allowed to authenticate.</p>"},{"location":"models/common/#jwtlib.models.common.IdentityMixin","title":"IdentityMixin","text":"<p> Bases: <code>BaseModel</code></p> <p>Mixin for entities with a username and email.</p> <p>Attributes:</p> Name Type Description <code>username</code> <code>str</code> <p>Unique username used for authentication and display.</p> <code>email</code> <code>Optional[EmailStr]</code> <p>Primary email address associated with the account.</p>"},{"location":"models/common/#jwtlib.models.common.PasswordMixin","title":"PasswordMixin","text":"<p> Bases: <code>BaseModel</code></p> <p>Mixin for entities with a raw password field.</p> <p>Attributes:</p> Name Type Description <code>password</code> <code>str</code> <p>User password (minimum 6 characters).</p>"},{"location":"models/mongo/","title":"Mongo","text":""},{"location":"models/mongo/#jwtlib.models.mongo","title":"jwtlib.models.mongo","text":"<p>Persistence-layer user model for MongoDB.</p>"},{"location":"models/mongo/#jwtlib.models.mongo--summary","title":"Summary","text":"<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":"models/mongo/#jwtlib.models.mongo-classes","title":"Classes","text":""},{"location":"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>Attributes:</p> Name Type Description <code>hashed_password</code> <code>str</code> <p>Secure hash of the user's password.</p> Notes <p>Responsibilities:</p> <pre><code>- Represents a user record as stored in the database. Includes sensitive fields and is strictly confined to the persistence layer.\n</code></pre> <p>Guarantees:</p> <pre><code>- This model MUST NOT be returned from authentication APIs. Consumers should use `PublicUser` instead. Password verification is handled by the repository layer.\n</code></pre>"},{"location":"models/security/","title":"Security","text":""},{"location":"models/security/#jwtlib.models.security","title":"jwtlib.models.security","text":"<p>JWT token payload models.</p>"},{"location":"models/security/#jwtlib.models.security--summary","title":"Summary","text":"<p>This module defines typed representations of decoded JWT payloads used internally for token validation and user resolution.</p>"},{"location":"models/security/#jwtlib.models.security-classes","title":"Classes","text":""},{"location":"models/security/#jwtlib.models.security.TokenPayload","title":"TokenPayload","text":"<p> Bases: <code>BaseModel</code></p> <p>Decoded JWT payload.</p> <p>Attributes:</p> Name Type Description <code>sub</code> <code>str</code> <p>Subject claim identifying the user (typically a username or user ID).</p> <code>exp</code> <code>int</code> <p>Expiration time as a Unix timestamp (seconds since epoch).</p> Notes <p>Responsibilities:</p> <pre><code>- 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.\n</code></pre> <p>Guarantees:</p> <pre><code>- 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.\n</code></pre>"}]} |