docs/mcp/py-jwt/modules/jwtlib.app.json

{
  "module": "jwtlib.app",
  "content": {
    "path": "jwtlib.app",
    "docstring": "# Summary\n\nApplication-level authentication logic.\n\nThis module contains **pure authentication and introspection logic** with no\nframework or transport coupling. It is intended to be used by HTTP adapters,\nCLIs, background workers, and other services that require `JWT`-based\nauthentication and user resolution.\n\nNotes:\n    **Responsibilities:**\n\n        - User registration and login.\n        - Stateless logout semantics.\n        - Current-user resolution from `JWT`s.\n        - Service-to-service token introspection.\n\n    **Constraints:**\n\n        - This module intentionally does NOT:\n            - Define HTTP routes.\n            - Manage sessions.\n            - Perform request parsing or response formatting.\n            - Handle transport-level concerns.",
    "objects": {
      "AuthError": {
        "name": "AuthError",
        "kind": "class",
        "path": "jwtlib.app.AuthError",
        "signature": null,
        "docstring": "Base authentication and authorization error.\n\nNotes:\n    **Guarantees:**\n\n        - All authentication-related exceptions raised by this library\n          inherit from this class.\n        - Consumers may catch this exception to handle all auth failures\n          uniformly."
      },
      "InvalidToken": {
        "name": "InvalidToken",
        "kind": "class",
        "path": "jwtlib.app.InvalidToken",
        "signature": null,
        "docstring": "Raised when a `JWT` is missing, malformed, expired, or invalid.\n\nNotes:\n    **Guarantees:**\n\n        - This error indicates that the provided token cannot be used to\n          authenticate a request."
      },
      "IntrospectResponse": {
        "name": "IntrospectResponse",
        "kind": "class",
        "path": "jwtlib.app.IntrospectResponse",
        "signature": null,
        "docstring": "Result of a token introspection operation.\n\nAttributes:\n    active (bool):\n        Indicates whether the token is valid and active.\n    user (Optional[PublicUser]):\n        Public user details if the token is valid; otherwise null.",
        "members": {
          "active": {
            "name": "active",
            "kind": "attribute",
            "path": "jwtlib.app.IntrospectResponse.active",
            "signature": null,
            "docstring": null
          },
          "user": {
            "name": "user",
            "kind": "attribute",
            "path": "jwtlib.app.IntrospectResponse.user",
            "signature": null,
            "docstring": null
          },
          "model_config": {
            "name": "model_config",
            "kind": "attribute",
            "path": "jwtlib.app.IntrospectResponse.model_config",
            "signature": null,
            "docstring": null
          },
          "jwt_error": {
            "name": "jwt_error",
            "kind": "function",
            "path": "jwtlib.app.IntrospectResponse.jwt_error",
            "signature": "jwt_error(error: Any)",
            "docstring": null
          },
          "no_username": {
            "name": "no_username",
            "kind": "function",
            "path": "jwtlib.app.IntrospectResponse.no_username",
            "signature": "no_username()",
            "docstring": null
          },
          "no_user": {
            "name": "no_user",
            "kind": "function",
            "path": "jwtlib.app.IntrospectResponse.no_user",
            "signature": "no_user()",
            "docstring": null
          },
          "valid_user": {
            "name": "valid_user",
            "kind": "function",
            "path": "jwtlib.app.IntrospectResponse.valid_user",
            "signature": "valid_user(user: Any)",
            "docstring": null
          }
        }
      },
      "LoginRequest": {
        "name": "LoginRequest",
        "kind": "class",
        "path": "jwtlib.app.LoginRequest",
        "signature": null,
        "docstring": "Payload for authenticating a user and issuing a `JWT`.\n\nAttributes:\n    username (str):\n        Username identifier.\n    password (str):\n        Plain-text password to be verified.",
        "members": {
          "model_config": {
            "name": "model_config",
            "kind": "attribute",
            "path": "jwtlib.app.LoginRequest.model_config",
            "signature": null,
            "docstring": null
          },
          "username": {
            "name": "username",
            "kind": "attribute",
            "path": "jwtlib.app.LoginRequest.username",
            "signature": null,
            "docstring": null
          },
          "password": {
            "name": "password",
            "kind": "attribute",
            "path": "jwtlib.app.LoginRequest.password",
            "signature": null,
            "docstring": null
          }
        }
      },
      "LoginResponse": {
        "name": "LoginResponse",
        "kind": "class",
        "path": "jwtlib.app.LoginResponse",
        "signature": null,
        "docstring": "Response returned after successful authentication.\n\nAttributes:\n    access_token (str):\n        `JWT` access token for authenticated requests.\n    user (PublicUser):\n        Public profile of the authenticated user.",
        "members": {
          "access_token": {
            "name": "access_token",
            "kind": "attribute",
            "path": "jwtlib.app.LoginResponse.access_token",
            "signature": null,
            "docstring": null
          },
          "user": {
            "name": "user",
            "kind": "attribute",
            "path": "jwtlib.app.LoginResponse.user",
            "signature": null,
            "docstring": null
          },
          "model_config": {
            "name": "model_config",
            "kind": "attribute",
            "path": "jwtlib.app.LoginResponse.model_config",
            "signature": null,
            "docstring": null
          }
        }
      },
      "LogoutResponse": {
        "name": "LogoutResponse",
        "kind": "class",
        "path": "jwtlib.app.LogoutResponse",
        "signature": null,
        "docstring": "Response returned after a logout operation.\n\nAttributes:\n    message (str):\n        Human-readable logout confirmation.",
        "members": {
          "message": {
            "name": "message",
            "kind": "attribute",
            "path": "jwtlib.app.LogoutResponse.message",
            "signature": null,
            "docstring": null
          },
          "model_config": {
            "name": "model_config",
            "kind": "attribute",
            "path": "jwtlib.app.LogoutResponse.model_config",
            "signature": null,
            "docstring": null
          }
        }
      },
      "PublicUser": {
        "name": "PublicUser",
        "kind": "class",
        "path": "jwtlib.app.PublicUser",
        "signature": null,
        "docstring": "Public-facing user representation returned by authentication APIs.\n\nAttributes:\n    username (str):\n        Unique username identifier.\n    email (EmailStr, optional):\n        User's email address.\n    is_active (bool):\n        Whether the user account is active.",
        "members": {
          "model_config": {
            "name": "model_config",
            "kind": "attribute",
            "path": "jwtlib.app.PublicUser.model_config",
            "signature": null,
            "docstring": null
          },
          "username": {
            "name": "username",
            "kind": "attribute",
            "path": "jwtlib.app.PublicUser.username",
            "signature": null,
            "docstring": null
          },
          "email": {
            "name": "email",
            "kind": "attribute",
            "path": "jwtlib.app.PublicUser.email",
            "signature": null,
            "docstring": null
          },
          "is_active": {
            "name": "is_active",
            "kind": "attribute",
            "path": "jwtlib.app.PublicUser.is_active",
            "signature": null,
            "docstring": null
          }
        }
      },
      "RegisterRequest": {
        "name": "RegisterRequest",
        "kind": "class",
        "path": "jwtlib.app.RegisterRequest",
        "signature": null,
        "docstring": "Payload for registering a new user account.\n\nAttributes:\n    username (str):\n        Unique username identifier.\n    email (EmailStr, optional):\n        User's email address.\n    password (str):\n        Plain-text password (to be hashed by the repository layer).",
        "members": {
          "model_config": {
            "name": "model_config",
            "kind": "attribute",
            "path": "jwtlib.app.RegisterRequest.model_config",
            "signature": null,
            "docstring": null
          },
          "username": {
            "name": "username",
            "kind": "attribute",
            "path": "jwtlib.app.RegisterRequest.username",
            "signature": null,
            "docstring": null
          },
          "email": {
            "name": "email",
            "kind": "attribute",
            "path": "jwtlib.app.RegisterRequest.email",
            "signature": null,
            "docstring": null
          },
          "password": {
            "name": "password",
            "kind": "attribute",
            "path": "jwtlib.app.RegisterRequest.password",
            "signature": null,
            "docstring": null
          }
        }
      },
      "UserRepository": {
        "name": "UserRepository",
        "kind": "class",
        "path": "jwtlib.app.UserRepository",
        "signature": "UserRepository()",
        "docstring": "MongoDB-backed repository for `User` documents.\n\nNotes:\n    **Responsibilities:**\n\n        - Manage user persistence (CRUD).\n        - Handle credential verification and token issuance.",
        "members": {
          "create": {
            "name": "create",
            "kind": "function",
            "path": "jwtlib.app.UserRepository.create",
            "signature": "create(user_create: RegisterRequest)",
            "docstring": "Create a new user record.\n\nArgs:\n    user_create (RegisterRequest):\n        Registration data including prospective password.\n\nReturns:\n    PublicUser:\n        A PublicUser representation of the created user."
          },
          "get_by_username": {
            "name": "get_by_username",
            "kind": "function",
            "path": "jwtlib.app.UserRepository.get_by_username",
            "signature": "get_by_username(username: str)",
            "docstring": "Retrieve a user by their unique username.\n\nArgs:\n    username (str):\n        The username to search for.\n\nReturns:\n    User | None:\n        The User document if found, otherwise None."
          },
          "get_by_email": {
            "name": "get_by_email",
            "kind": "function",
            "path": "jwtlib.app.UserRepository.get_by_email",
            "signature": "get_by_email(email: str)",
            "docstring": "Retrieve a user by their unique email address.\n\nArgs:\n    email (str):\n        The email address to search for.\n\nReturns:\n    User | None:\n        The User document if found, otherwise None."
          },
          "get_active_users": {
            "name": "get_active_users",
            "kind": "function",
            "path": "jwtlib.app.UserRepository.get_active_users",
            "signature": "get_active_users(skip: int = 0, limit: int = 100)",
            "docstring": "List all active users with pagination.\n\nArgs:\n    skip (int):\n        Number of records to skip.\n    limit (int):\n        Maximum number of records to return.\n\nReturns:\n    list[User]:\n        A list of active User documents."
          },
          "authenticate_user": {
            "name": "authenticate_user",
            "kind": "function",
            "path": "jwtlib.app.UserRepository.authenticate_user",
            "signature": "authenticate_user(user_auth: LoginRequest)",
            "docstring": "Verify user credentials and prepare a login response.\n\nArgs:\n    user_auth (LoginRequest):\n        Login credentials.\n\nReturns:\n    dict | None:\n        A dictionary containing the access token and public user if successful, otherwise None."
          }
        }
      },
      "get_current_user": {
        "name": "get_current_user",
        "kind": "function",
        "path": "jwtlib.app.get_current_user",
        "signature": "get_current_user(token: str, repo: UserRepository | None = None)",
        "docstring": "Validate token and return authenticated public user.\n\nArgs:\n    token (str):\n        The `JWT` string to validate.\n    repo (UserRepository | None):\n        The user repository to use for resolution.\n\nReturns:\n    PublicUser:\n        The resolved and validated user object.\n\nRaises:\n    InvalidToken:\n        If the token is missing, malformed, or invalid.\n    UserNotFound:\n        If the token is valid, but the user does not exist in the\n        repository."
      },
      "get_user_repository": {
        "name": "get_user_repository",
        "kind": "function",
        "path": "jwtlib.app.get_user_repository",
        "signature": "get_user_repository()",
        "docstring": "Return a singleton or new instance of the `UserRepository`.\n\nReturns:\n    UserRepository:\n        The user repository instance."
      },
      "get_validated_token_payload": {
        "name": "get_validated_token_payload",
        "kind": "function",
        "path": "jwtlib.app.get_validated_token_payload",
        "signature": "get_validated_token_payload(token: str)",
        "docstring": "Validate a `JWT` and return a typed payload.\n\nArgs:\n    token (str):\n        The `JWT` string to validate.\n\nReturns:\n    TokenPayload:\n        The validated and typed token payload.\n\nRaises:\n    JWTError:\n        If the token is invalid or malformed."
      },
      "register_user": {
        "name": "register_user",
        "kind": "function",
        "path": "jwtlib.app.register_user",
        "signature": "register_user(user: RegisterRequest, repo: UserRepository | None = None) -> PublicUser",
        "docstring": "Register a new user.\n\nArgs:\n    user (RegisterRequest):\n        Registration payload containing username, email, and password.\n    repo (UserRepository | None):\n        Optional user repository instance. If not provided, a default\n        repository is obtained via dependency utilities.\n\nReturns:\n    PublicUser:\n        The newly created user as a public user representation."
      },
      "login_user": {
        "name": "login_user",
        "kind": "function",
        "path": "jwtlib.app.login_user",
        "signature": "login_user(user: LoginRequest, repo: UserRepository | None = None) -> LoginResponse",
        "docstring": "Authenticate a user and issue an access token.\n\nArgs:\n    user (LoginRequest):\n        Login payload containing username and password.\n    repo (UserRepository | None):\n        Optional user repository instance. If not provided, a default\n        repository is obtained via dependency utilities.\n\nReturns:\n    LoginResponse:\n        `LoginResponse` containing the issued access token and related\n        metadata.\n\nRaises:\n    AuthError:\n        If the credentials are invalid."
      },
      "get_logged_in_user": {
        "name": "get_logged_in_user",
        "kind": "function",
        "path": "jwtlib.app.get_logged_in_user",
        "signature": "get_logged_in_user(token: str, repo: UserRepository | None = None) -> PublicUser",
        "docstring": "Resolve the currently authenticated user from a `JWT`.\n\nArgs:\n    token (str):\n        `JWT` access token.\n    repo (UserRepository | None):\n        Optional user repository instance. If not provided, a default\n        repository is obtained via dependency utilities.\n\nReturns:\n    PublicUser:\n        The authenticated user as a `PublicUser`.\n\nRaises:\n    InvalidToken:\n        If the token is missing, malformed, or invalid.\n    AuthError:\n        If the token is valid, but the user cannot be resolved."
      },
      "logout_user": {
        "name": "logout_user",
        "kind": "function",
        "path": "jwtlib.app.logout_user",
        "signature": "logout_user() -> LogoutResponse",
        "docstring": "Perform a stateless logout.\n\nReturns:\n    LogoutResponse:\n        `LogoutResponse` containing a logout confirmation message.\n\nNotes:\n    **Guarantees:**\n\n        - This function does not invalidate tokens server-side. Instead, it\n          provides a standardized response indicating that the client must\n          discard its token."
      },
      "introspect_token": {
        "name": "introspect_token",
        "kind": "function",
        "path": "jwtlib.app.introspect_token",
        "signature": "introspect_token(token: str, repo: UserRepository | None = None) -> IntrospectResponse",
        "docstring": "Introspect a `JWT` for service-to-service authentication.\n\nArgs:\n    token (str):\n        `JWT` access token to introspect.\n    repo (UserRepository | None):\n        Optional user repository instance. If not provided, a default\n        repository is obtained via dependency utilities.\n\nReturns:\n    IntrospectResponse:\n        `IntrospectResponse` indicating valid token with user, invalid\n        token, or valid token with no user.\n\nNotes:\n    **Responsibilities:**\n\n        - Validate the provided token and resolve the associated user,\n          returning a structured introspection response suitable for\n          internal service use.\n\n    **Guarantees:**\n\n        - This function never raises authentication exceptions. Instead, it\n          returns a typed response indicating token validity and user\n          presence."
      }
    }
  }
}