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

{
  "module": "jwtlib.utils",
  "content": {
    "path": "jwtlib.utils",
    "docstring": "# Summary\n\nAuth Utilities: Token validation and user resolution.\n\nThis module provides high-level helpers for validating `JWT` payloads and\nresolving users, intended for use in dependency injection or middleware.",
    "objects": {
      "InvalidToken": {
        "name": "InvalidToken",
        "kind": "class",
        "path": "jwtlib.utils.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."
      },
      "UserNotFound": {
        "name": "UserNotFound",
        "kind": "class",
        "path": "jwtlib.utils.UserNotFound",
        "signature": null,
        "docstring": "Raised when a valid token does not map to an existing user.\n\nNotes:\n    **Guarantees:**\n\n        - Indicates that authentication succeeded at the token level, but\n          the associated user record could not be resolved."
      },
      "PublicUser": {
        "name": "PublicUser",
        "kind": "class",
        "path": "jwtlib.utils.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.utils.PublicUser.model_config",
            "signature": null,
            "docstring": null
          },
          "username": {
            "name": "username",
            "kind": "attribute",
            "path": "jwtlib.utils.PublicUser.username",
            "signature": null,
            "docstring": null
          },
          "email": {
            "name": "email",
            "kind": "attribute",
            "path": "jwtlib.utils.PublicUser.email",
            "signature": null,
            "docstring": null
          },
          "is_active": {
            "name": "is_active",
            "kind": "attribute",
            "path": "jwtlib.utils.PublicUser.is_active",
            "signature": null,
            "docstring": null
          }
        }
      },
      "TokenPayload": {
        "name": "TokenPayload",
        "kind": "class",
        "path": "jwtlib.utils.TokenPayload",
        "signature": null,
        "docstring": "Decoded `JWT` payload.\n\nAttributes:\n    sub (str):\n        Subject claim identifying the user (typically a username or user ID).\n    exp (int):\n        Expiration time as a Unix timestamp (seconds since epoch).\n\nNotes:\n    **Responsibilities:**\n\n        - Represents the validated claims extracted from a `JWT` after\n          signature verification. This model is used internally to enforce\n          required claims and provide a typed interface to token data.\n\n    **Guarantees:**\n\n        - This model assumes the `JWT` signature has already been verified.\n          No authorization decisions should be made solely on this model.\n          Additional claims may exist but are intentionally ignored.",
        "members": {
          "sub": {
            "name": "sub",
            "kind": "attribute",
            "path": "jwtlib.utils.TokenPayload.sub",
            "signature": null,
            "docstring": null
          },
          "exp": {
            "name": "exp",
            "kind": "attribute",
            "path": "jwtlib.utils.TokenPayload.exp",
            "signature": null,
            "docstring": null
          }
        }
      },
      "UserRepository": {
        "name": "UserRepository",
        "kind": "class",
        "path": "jwtlib.utils.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.utils.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.utils.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.utils.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.utils.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.utils.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_jwt_payload": {
        "name": "get_jwt_payload",
        "kind": "function",
        "path": "jwtlib.utils.get_jwt_payload",
        "signature": "get_jwt_payload(token: str)",
        "docstring": "Decode and validate a `JWT`, returning a strongly-typed payload.\n\nArgs:\n    token (str):\n        The `JWT` string to decode.\n\nReturns:\n    TokenPayload:\n        The decoded and typed token payload.\n\nRaises:\n    JWTError:\n        If the token is invalid, expired, or malformed."
      },
      "get_user_repository": {
        "name": "get_user_repository",
        "kind": "function",
        "path": "jwtlib.utils.get_user_repository",
        "signature": "get_user_repository() -> UserRepository",
        "docstring": "Return a singleton or new instance of the `UserRepository`.\n\nReturns:\n    UserRepository:\n        The user repository instance."
      },
      "get_current_user": {
        "name": "get_current_user",
        "kind": "function",
        "path": "jwtlib.utils.get_current_user",
        "signature": "get_current_user(token: str, repo: UserRepository | None = None) -> PublicUser",
        "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_validated_token_payload": {
        "name": "get_validated_token_payload",
        "kind": "function",
        "path": "jwtlib.utils.get_validated_token_payload",
        "signature": "get_validated_token_payload(token: str) -> TokenPayload",
        "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."
      }
    }
  }
}