JWT Operations

def encode(payload: dict, key: str | bytes, algorithm: str = 'HS256', 
          headers: dict = None, json_encoder = None, sort_headers: bool = True) -> str:
    """
    Encode a payload as a JSON Web Token.

    Args:
        payload (dict): Claims to encode in the token
        key (str | bytes): Secret key or private key for signing
        algorithm (str): Signing algorithm ('HS256', 'RS256', etc.)
        headers (dict): Additional headers for the JWT
        json_encoder: Custom JSON encoder class
        sort_headers (bool): Sort header keys alphabetically

    Returns:
        str: Encoded JWT token

    Raises:
        TypeError: If payload is not a dictionary
        InvalidKeyError: If key is invalid for algorithm
    """

import jwt
from datetime import datetime, timedelta, timezone

# Simple payload
payload = {'user_id': 123, 'role': 'admin'}
token = jwt.encode(payload, 'secret', algorithm='HS256')

# With expiration and custom claims
payload = {
    'user_id': 123,
    'exp': datetime.now(tz=timezone.utc) + timedelta(hours=1),
    'iat': datetime.now(tz=timezone.utc),
    'aud': 'my-app',
    'iss': 'auth-service'
}
token = jwt.encode(payload, 'secret', algorithm='HS256')

# With custom headers
headers = {'kid': 'key-1', 'custom': 'value'}
token = jwt.encode(payload, 'secret', algorithm='HS256', headers=headers)

def decode(jwt: str | bytes, key: str | bytes = '', algorithms: list = None,
          options: dict = None, verify: bool = None, detached_payload: bytes = None,
          audience: str | list = None, issuer: str | list = None,
          subject: str = None, leeway: float | timedelta = 0) -> dict:
    """
    Decode and verify a JSON Web Token.

    Args:
        jwt (str | bytes): JWT token to decode
        key (str | bytes): Secret key or public key for verification
        algorithms (list): Allowed algorithms for verification
        options (dict): Verification options
        audience (str | list): Expected audience(s)
        issuer (str | list): Expected issuer(s)  
        subject (str): Expected subject
        leeway (float | timedelta): Clock skew tolerance in seconds

    Returns:
        dict: Decoded payload

    Raises:
        DecodeError: Token format errors
        InvalidSignatureError: Signature verification failed
        ExpiredSignatureError: Token has expired
        InvalidAudienceError: Audience validation failed
        InvalidIssuerError: Issuer validation failed
        MissingRequiredClaimError: Required claim missing
    """

def decode_complete(jwt: str | bytes, key: str | bytes = '', algorithms: list = None,
                   options: dict = None, audience: str | list = None,
                   issuer: str | list = None, subject: str = None,
                   leeway: float | timedelta = 0) -> dict:
    """
    Decode JWT returning header, payload, and signature.

    Returns:
        dict: {'header': dict, 'payload': dict, 'signature': bytes}
    """

import jwt
from jwt.exceptions import ExpiredSignatureError, InvalidTokenError

# Basic decoding
try:
    payload = jwt.decode(token, 'secret', algorithms=['HS256'])
    print(f"User: {payload['user_id']}")
except InvalidTokenError as e:
    print(f"Invalid token: {e}")

# With claim validation
try:
    payload = jwt.decode(
        token, 
        'secret', 
        algorithms=['HS256'],
        audience='my-app',
        issuer='auth-service',
        leeway=10  # 10 second clock skew tolerance
    )
except ExpiredSignatureError:
    print("Token expired")
except InvalidAudienceError:
    print("Wrong audience")

# Get complete token structure
decoded = jwt.decode_complete(token, 'secret', algorithms=['HS256'])
print(f"Header: {decoded['header']}")
print(f"Payload: {decoded['payload']}")

class PyJWT:
    def __init__(self, options: dict = None):
        """
        Initialize JWT instance with default options.

        Args:
            options (dict): Default verification options
        """

    def encode(self, payload: dict, key, algorithm: str = None, 
              headers: dict = None, json_encoder = None, 
              sort_headers: bool = True) -> str:
        """Encode JWT with instance options."""

    def decode(self, jwt: str | bytes, key = '', algorithms: list = None,
              options: dict = None, audience: str | list = None,
              issuer: str | list = None, subject: str = None,
              leeway: float | timedelta = 0) -> dict:
        """Decode JWT with instance options."""

    def decode_complete(self, jwt: str | bytes, key = '', 
                       algorithms: list = None, options: dict = None,
                       audience: str | list = None, issuer: str | list = None,
                       subject: str = None, leeway: float | timedelta = 0) -> dict:
        """Decode complete JWT with instance options."""

# Create instance with custom defaults
jwt_instance = jwt.PyJWT(options={
    'verify_exp': True,
    'verify_aud': True,
    'require': ['exp', 'aud']
})

# Use instance methods
token = jwt_instance.encode({'user_id': 123}, 'secret')
payload = jwt_instance.decode(token, 'secret', algorithms=['HS256'])

# Default verification options
{
    'verify_signature': True,  # Verify signature
    'verify_exp': True,        # Verify expiration time
    'verify_nbf': True,        # Verify not before time
    'verify_iat': True,        # Verify issued at time
    'verify_aud': True,        # Verify audience
    'verify_iss': True,        # Verify issuer
    'verify_sub': True,        # Verify subject
    'verify_jti': True,        # Verify JWT ID
    'require': []              # List of required claims
}

# Disable expiration checking
options = {'verify_exp': False}
payload = jwt.decode(token, 'secret', algorithms=['HS256'], options=options)

# Require specific claims
options = {'require': ['aud', 'iss', 'exp']}
payload = jwt.decode(token, 'secret', algorithms=['HS256'], options=options)