jam.jwt

jwt

Modules:

Name	Description
lists	Module for managing white and black lists.
module
utils

Classes:

Name	Description
BaseJWT	Base JWT module.
JWT	JWT factory.

Functions:

Name	Description
create_instance	Create JWT instance.

BaseJWT

Bases: ABC

Base JWT module.

Methods:

Name	Description
decode	Decode token.
encode	Encode token.

decode abstractmethod

decode(
    token: str, public_key: Any | None = None
) -> dict[str, Any]

Decode token.

Parameters:

Name	Type	Description	Default
token	str	JWT	required
public_key	Any | None	Decode with public key if needed	None

Returns:

Name	Type	Description
dict	dict[str, Any]	Payload

encode abstractmethod

encode(payload: dict[str, Any]) -> str

Encode token.

Parameters:

Name	Type	Description	Default
payload	dict[str, Any]	JWT Payload	required

Returns:

Name	Type	Description
str	str	JWT

JWT

JWT(
    alg: str,
    secret: KeyLike = getenv("JAM_JWT_SECRET_KEY"),
    password: str | bytes | None = None,
    list: dict[str, Any] | None = None,
    serializer: BaseEncoder
    | type[BaseEncoder] = JsonEncoder,
    logger: BaseLogger = logger,
)

Bases: BaseJWT

JWT factory.

This class provides JWT encoding and decoding functionality with support for multiple signing algorithms. It is designed to be easily extensible through inheritance and algorithm customization.

Example

jwt = JWT(alg="HS256", secret="my-secret-key") token = jwt.encode({"sub": "user123"}) payload = jwt.decode(token)

Parameters:

Name	Type	Description	Default
alg	str	JWT algorithm name	required
secret	KeyLike	Secret key for signing/verification	getenv('JAM_JWT_SECRET_KEY')
password	str | bytes | None	Password for encrypted private keys	None
list	dict[str, Any] | None	List config	None
serializer	BaseEncoder | type[BaseEncoder]	JSON encoder/decoder	JsonEncoder
logger	BaseLogger	Logger instance	logger

Raises:

Type	Description
JamJWTUnsupportedAlgorithm	If algorithm is not supported or secret is invalid

Methods:

Name	Description
decode	Decode and verify token.
encode	Encode token.

decode

decode(
    token: str, public_key: KeyLike | None = None
) -> dict[str, Any]

Decode and verify token.

Parameters:

Name	Type	Description	Default
token	str	JWT token to decode	required
public_key	KeyLike | None	Optional public key for verification. If not provided, uses the secret from initialization.	None

Raises:

Type	Description
JamJWTValidationError	If token is invalid, malformed, or verification fails
JamJWTUnsupportedAlgorithm	If the token's algorithm is not supported

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Decoded payload

encode

encode(payload: dict[str, Any]) -> str

Encode token.

Parameters:

Name	Type	Description	Default
payload	dict[str, Any]	JWT payload	required

Returns:

Name	Type	Description
str	str	Encoded JWT token

Raises:

Type	Description
JamJWTValidationError	If encoding fails

create_instance

create_instance(
    alg: str,
    secret: KeyLike | None = None,
    secret_key: KeyLike | None = None,
    password: str | bytes | None = None,
    list: dict[str, Any] | None = None,
    logger: BaseLogger = logger,
    serializer: BaseEncoder
    | type[BaseEncoder] = JsonEncoder,
    **kwargs: Any,
) -> JWT

Create JWT instance.

Parameters:

Name	Type	Description	Default
alg	str	Algorithm (HS256, RS256, etc.)	required
secret	KeyLike | None	Secret key (or use secret_key for backward compatibility)	None
secret_key	KeyLike | None	Alias for secret (deprecated, use 'secret')	None
password	str | bytes | None	Password for encrypted keys	None
list	dict[str, Any] | None	List config	None
logger	BaseLogger	Logger instance	logger
serializer	BaseEncoder | type[BaseEncoder]	JSON encoder/decoder	JsonEncoder
**kwargs	Any	Additional params (e.g., custom_module)	{}

Returns:

Type	Description
JWT	JWT instance or custom module