jam.BaseJam

BaseJam

Bases: ABC

Abstract Instance object.

Methods:

Name	Description
build_module	Method for building module from config.
clear_sessions	Clear all sessions associated with a specific session key.
create_session	Create new session.
delete_session	Delete a session by its ID.
gen_jwt_token	Generate new JWT token.
get_otp_code	Generates a OTP code.
get_otp_uri	Generates an otpauth:// URI for Google Authenticator.
get_session	Retrieve session data by session ID.
jwt_create_token	Create JWT token.
jwt_make_payload	Make JWT-specific payload.
jwt_verify_token	Verify and decode JWT token.
make_payload	Generate new template.
oauth2_client_credentials_flow	Obtain access token using client credentials flow (no user interaction).
oauth2_fetch_token	Exchange authorization code for access token.
oauth2_get_authorized_url	Generate full OAuth2 authorization URL.
oauth2_refresh_token	Use refresh token to obtain a new access token.
otp_code	Generates an OTP.
otp_uri	Generates an otpauth:// URI for Google Authenticator.
otp_verify_code	Checks the OTP code, taking into account the acceptable window.
rework_session	Rework an existing session key to a new one.
session_clear	Delete all sessions by key.
session_create	Create new session.
session_delete	Delete session.
session_get	Get data from session.
session_rework	Rework session.
session_update	Update session data.
update_session	Update session data by session ID.
verify_jwt_token	Verify JWT token.
verify_otp_code	Verify TOTP code.

build_module

build_module(name: str, cfg: dict[str, Any])

Method for building module from config.

Parameters:

Name	Type	Description	Default
name	str	Module name	required
cfg	dict[str, Any]	Config	required

clear_sessions abstractmethod

clear_sessions(session_key: str) -> None

Clear all sessions associated with a specific session key.

create_session abstractmethod

create_session(session_key: str, data: dict) -> str

Create new session.

delete_session abstractmethod

delete_session(session_id: str) -> None

Delete a session by its ID.

gen_jwt_token abstractmethod

gen_jwt_token(payload) -> str

Generate new JWT token.

get_otp_code abstractmethod

get_otp_code(
    secret: str, factor: Optional[int] = None
) -> str

Generates a OTP code.

get_otp_uri abstractmethod

get_otp_uri(
    secret: str,
    name: Optional[str] = None,
    issuer: Optional[str] = None,
    counter: Optional[int] = None,
) -> str

Generates an otpauth:// URI for Google Authenticator.

get_session abstractmethod

get_session(session_id: str) -> Optional[dict]

Retrieve session data by session ID.

jwt_create_token abstractmethod

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

Create JWT token.

Parameters:

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

Returns:

Name	Type	Description
str	str	New token

Raises:

Type	Description
EmptySecretKey	If the HMAC algorithm is selected, but the secret key is None
EmtpyPrivateKey	If RSA algorithm is selected, but private key None

jwt_make_payload abstractmethod

jwt_make_payload(
    exp: Optional[int], data: dict[str, Any]
) -> dict[str, Any]

Make JWT-specific payload.

Parameters:

Name	Type	Description	Default
exp	int | None	Token expire, if None -> use default	required
data	dict[str, Any]	Data to payload	required

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Payload

jwt_verify_token abstractmethod

jwt_verify_token(
    token: str,
    check_exp: bool = True,
    check_list: bool = True,
) -> dict[str, Any]

Verify and decode JWT token.

Parameters:

Name	Type	Description	Default
token	str	JWT token	required
check_exp	bool	Check expire	True
check_list	bool	Check white/black list. Docs: https://jam.makridenko.ru/jwt/lists/what/	True

Returns:

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

Raises:

Type	Description
ValueError	If the token is invalid.
EmptySecretKey	If the HMAC algorithm is selected, but the secret key is None.
EmtpyPublicKey	If RSA algorithm is selected, but public key None.
NotFoundSomeInPayload	If 'exp' not found in payload.
TokenLifeTimeExpired	If token has expired.
TokenNotInWhiteList	If the list type is white, but the token is not there
TokenInBlackList	If the list type is black and the token is there

make_payload abstractmethod

make_payload(**payload) -> dict[str, Any]

Generate new template.

oauth2_client_credentials_flow abstractmethod

oauth2_client_credentials_flow(
    provider: str,
    scope: Optional[list[str]] = None,
    **extra_params: Any
) -> dict[str, Any]

Obtain access token using client credentials flow (no user interaction).

Parameters:

Name	Type	Description	Default
provider	str	Provider name	required
scope	list[str] | None	Auth scope	None
extra_params	Any	Extra auth params if needed	{}

Returns:

Name	Type	Description
dict	dict[str, Any]	JSON with access token

oauth2_fetch_token abstractmethod

oauth2_fetch_token(
    provider: str,
    code: str,
    grant_type: str = "authorization_code",
    **extra_params: Any
) -> dict[str, Any]

Exchange authorization code for access token.

Parameters:

Name	Type	Description	Default
provider	str	Provider name	required
code	str	OAuth2 code	required
grant_type	str	Type of oauth2 grant	'authorization_code'
extra_params	Any	Extra auth params if needed	{}

Returns:

Name	Type	Description
dict	dict[str, Any]	OAuth2 token

oauth2_get_authorized_url abstractmethod

oauth2_get_authorized_url(
    provider: str, scope: list[str], **extra_params: Any
) -> str

Generate full OAuth2 authorization URL.

Parameters:

Name	Type	Description	Default
provider	str	Provider name	required
scope	list[str]	Auth scope	required
extra_params	Any	Extra ath params	{}

Returns:

Name	Type	Description
str	str	Authorization url

oauth2_refresh_token abstractmethod

oauth2_refresh_token(
    provider: str,
    refresh_token: str,
    grant_type: str = "refresh_token",
    **extra_params: Any
) -> dict[str, Any]

Use refresh token to obtain a new access token.

Parameters:

Name	Type	Description	Default
provider	str	Provider name	required
refresh_token	str	Refresh token	required
grant_type	str	Grant type	'refresh_token'
extra_params	Any	Extra auth params if needed	{}

Returns:

Name	Type	Description
dict	dict[str, Any]	Refresh token

otp_code abstractmethod

otp_code(
    secret: Union[str, bytes], factor: Optional[int] = None
) -> str

Generates an OTP.

Parameters:

Name	Type	Description	Default
secret	str | bytes	User secret key.	required
factor	int | None	Unixtime for TOTP(if none, use now time) / Counter for HOTP.	None

Returns:

Name	Type	Description
str	str	OTP code (fixed-length string).

otp_uri abstractmethod

otp_uri(
    secret: str,
    name: Optional[str] = None,
    issuer: Optional[str] = None,
    counter: Optional[int] = None,
) -> str

Generates an otpauth:// URI for Google Authenticator.

Parameters:

Name	Type	Description	Default
secret	str	User secret key.	required
name	str	Account name (e.g., email).	None
issuer	str	Service name (e.g., "GitHub").	None
counter	int | None	Counter (for HOTP). Default is None.	None

Returns:

Name	Type	Description
str	str	A string of the form "otpauth://..."

otp_verify_code abstractmethod

otp_verify_code(
    secret: Union[str, bytes],
    code: str,
    factor: Optional[int] = None,
    look_ahead: Optional[int] = 1,
) -> bool

Checks the OTP code, taking into account the acceptable window.

Parameters:

Name	Type	Description	Default
secret	str | bytes	User secret key.	required
code	str	The code entered.	required
factor	int | None	Unixtime for TOTP(if none, use now time) / Counter for HOTP.	None
look_ahead	int	Acceptable deviation in intervals (±window(totp) / ±look ahead(hotp)). Default is 1.	1

Returns:

Name	Type	Description
bool	bool	True if the code matches, otherwise False.

rework_session abstractmethod

rework_session(old_session_key: str) -> str

Rework an existing session key to a new one.

session_clear abstractmethod

session_clear(session_key: str) -> None

Delete all sessions by key.

Parameters:

Name	Type	Description	Default
session_key	str	Key of session	required

session_create abstractmethod

session_create(
    session_key: str, data: dict[str, Any]
) -> str

Create new session.

Parameters:

Name	Type	Description	Default
session_key	str	Key for session	required
data	dict[str, Any]	Session data	required

Returns:

Name	Type	Description
str	str	New session ID

session_delete abstractmethod

session_delete(session_id: str) -> None

Delete session.

Parameters:

Name	Type	Description	Default
session_id	str	Session ID	required

session_get abstractmethod

session_get(session_id: str) -> Optional[dict[str, Any]]

Get data from session.

Parameters:

Name	Type	Description	Default
session_id	str	Session ID	required

Returns:

Type	Description
Optional[dict[str, Any]]	dict[str, Any] | None: Session data if exist

session_rework abstractmethod

session_rework(old_session_id: str) -> str

Rework session.

Parameters:

Name	Type	Description	Default
old_session_id	str	Old session id	required

Returns:

Name	Type	Description
str	str	New session id

session_update abstractmethod

session_update(
    session_id: str, data: dict[str, Any]
) -> None

Update session data.

Parameters:

Name	Type	Description	Default
session_id	str	Session ID	required
data	dict[str, Any]	New data	required

update_session abstractmethod

update_session(session_id: str, data: dict) -> None

Update session data by session ID.

verify_jwt_token abstractmethod

verify_jwt_token(
    token: str, check_exp: bool, check_list: bool
) -> dict[str, Any]

Verify JWT token.

verify_otp_code abstractmethod

verify_otp_code(
    secret: str,
    code: str,
    factor: Optional[int] = None,
    look_ahead: Optional[int] = None,
) -> bool

Verify TOTP code.