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

{
  "module": "jwtlib.introspection",
  "content": {
    "path": "jwtlib.introspection",
    "docstring": "# Summary\n\nAuth client and access-control utilities.\n\nThis module provides **pure authentication and authorization logic**\nfor validating JWTs via service-to-service introspection and resolving\nauthenticated users.\n\nNotes:\n    **Responsibilities:**\n\n        - Calling the auth service introspection endpoint\n        - Translating introspection responses into typed user models\n        - Enforcing access control decisions at the logic layer\n\n    **Constraints:**\n\n        - This module intentionally does NOT: Parse HTTP requests or headers, implement authentication policies, or perform JWT signature verification locally.",
    "objects": {
      "AuthServiceUnavailable": {
        "name": "AuthServiceUnavailable",
        "kind": "class",
        "path": "jwtlib.introspection.AuthServiceUnavailable",
        "signature": null,
        "docstring": "Raised when the authentication service cannot be reached.\n\nNotes:\n    **Guarantees:**\n\n        - Indicates a network failure, timeout, or unexpected error while\n          communicating with the auth service."
      },
      "InvalidToken": {
        "name": "InvalidToken",
        "kind": "class",
        "path": "jwtlib.introspection.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."
      },
      "PublicUser": {
        "name": "PublicUser",
        "kind": "class",
        "path": "jwtlib.introspection.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.introspection.PublicUser.model_config",
            "signature": null,
            "docstring": null
          },
          "username": {
            "name": "username",
            "kind": "attribute",
            "path": "jwtlib.introspection.PublicUser.username",
            "signature": null,
            "docstring": null
          },
          "email": {
            "name": "email",
            "kind": "attribute",
            "path": "jwtlib.introspection.PublicUser.email",
            "signature": null,
            "docstring": null
          },
          "is_active": {
            "name": "is_active",
            "kind": "attribute",
            "path": "jwtlib.introspection.PublicUser.is_active",
            "signature": null,
            "docstring": null
          }
        }
      },
      "JWT_SERVER": {
        "name": "JWT_SERVER",
        "kind": "attribute",
        "path": "jwtlib.introspection.JWT_SERVER",
        "signature": null,
        "docstring": null
      },
      "INTROSPECTION_URL": {
        "name": "INTROSPECTION_URL",
        "kind": "attribute",
        "path": "jwtlib.introspection.INTROSPECTION_URL",
        "signature": null,
        "docstring": null
      },
      "introspect_token": {
        "name": "introspect_token",
        "kind": "function",
        "path": "jwtlib.introspection.introspect_token",
        "signature": "introspect_token(token: str) -> dict[str, Any]",
        "docstring": "Introspect a JWT using the external authentication service.\n\nArgs:\n    token (str):\n        JWT access token to introspect.\n\nReturns:\n    dict[str, Any]:\n        A dictionary containing the authenticated user's public payload.\n\nRaises:\n    InvalidToken:\n        If the token is missing, invalid, inactive, or revoked.\n    AuthServiceUnavailable:\n        If the auth service cannot be reached or fails unexpectedly.\n\nNotes:\n    **Guarantees:**\n\n        - 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."
      },
      "authenticate_request": {
        "name": "authenticate_request",
        "kind": "function",
        "path": "jwtlib.introspection.authenticate_request",
        "signature": "authenticate_request(should_skip_authentication: Callable[[str, str], bool], *, method: str, path: str, authorization_token: str | None) -> PublicUser | None",
        "docstring": "Authenticate an incoming request using token introspection.\n\nArgs:\n    should_skip_authentication (Callable[[str, str], bool]):\n        Callable that decides whether authentication is required for a given HTTP method and path.\n    method (str):\n        HTTP method of the incoming request.\n    path (str):\n        Request path.\n    authorization_token (str | None):\n        JWT access token provided by the caller.\n\nReturns:\n    PublicUser | None:\n        PublicUser if authentication succeeds; None if authentication is skipped.\n\nRaises:\n    InvalidToken:\n        If authentication is required but the token is missing, invalid, or revoked.\n    AuthServiceUnavailable:\n        If the auth service cannot be reached.\n\nNotes:\n    **Responsibilities:**\n\n        - Determines whether authentication should be skipped for the given request context and, if not, resolves the authenticated user via token introspection\n\n    **Guarantees:**\n\n        - This function does not parse Authorization headers; callers must supply the raw token. Access-control policy is externalized via `should_skip_authentication`."
      }
    }
  }
}