jam.jose.jwt

jwt

Classes:

Name	Description
JWT	JWT (JSON Web Token) implementation - RFC 7519.

JWT

JWT(
    alg: str | None = None,
    enc: str | None = None,
    secret_key: str | bytes | KeyLike | JWK | None = None,
    password: str | bytes | None = None,
    list: dict[str, Any] | None = None,
    serializer: BaseEncoder
    | type[BaseEncoder] = JsonEncoder,
    logger: BaseLogger = logger,
    jws: JWS | None = None,
    jwe: JWE | None = None,
)

Bases: BaseJWT

JWT (JSON Web Token) implementation - RFC 7519.

Supports JWS (signed), JWE (encrypted), and JWS+JWE (sign then encrypt) tokens.

Parameters:

Name	Type	Description	Default
alg	str | None	JWT algorithm name for signing (JWS). Used if jws is not provided.	None
enc	str | None	JWE content encryption algorithm. If provided, creates encrypted JWT.	None
secret_key	str | bytes | KeyLike | JWK | None	Key for signing/encryption.	None
password	str | bytes | None	Password for encrypted private keys.	None
list	dict[str, Any] | None	List config for token storage.	None
serializer	BaseEncoder | type[BaseEncoder]	JSON encoder/decoder.	JsonEncoder
logger	BaseLogger	Logger instance.	logger
jws	JWS | None	Pre-built JWS instance. If provided, alg is ignored.	None
jwe	JWE | None	Pre-built JWE instance. If provided, enc and secret_key are ignored.	None

Raises:

Type	Description
ValueError	If neither alg/enc provided and no jws/jwe provided.
ValueError	If both alg and jws are provided.
ValueError	If both enc and jwe are provided.
JamJWTUnsupportedAlgorithm	If algorithm is not supported.

Methods:

Name	Description
decode	Decode the JWT and return the header and payload.
decrypt	Decrypt JWE or JWS+JWE token.
encode	Encode the JWT with the given expire, header, and payload (JWS).
encrypt	Encrypt payload using JWE.

Attributes:

Name	Type	Description
jti	str	The JWT ID.

jti property

jti: str

The JWT ID.

decode

decode(
    token: str, validate_claims: bool = True
) -> dict[str, Any]

Decode the JWT and return the header and payload.

Parameters:

Name	Type	Description	Default
token	str	JWT token.	required
validate_claims	bool	Whether to validate exp/nbf claims. Defaults to True.	True

Returns:

Type	Description
dict[str, Any]	dict with 'header' and 'payload' keys (both dicts).

Raises:

Type	Description
JamConfigurationError	If alg is not provided.
JamJWSVerificationError	If token has invalid type.
JamJWTExpired	If token is expired.
JamJWTNotYetValid	If token is not yet valid.

decrypt

decrypt(token: str) -> dict[str, Any] | bytes

Decrypt JWE or JWS+JWE token.

If token is JWS+JWE (sign then encrypt): 1. Decrypt JWE to get JWS compact serialization 2. Verify JWS to get original payload

Parameters:

Name	Type	Description	Default
token	str	Encrypted JWT token.	required

Returns:

Type	Description
dict[str, Any] | bytes	dict[str, Any]: Decrypted payload.

Raises:

Type	Description
JamConfigurationError	If enc is not provided.

encode

encode(
    iss: str | None = None,
    sub: str | None = None,
    aud: str | None = None,
    exp: int | None = None,
    nbf: int | None = None,
    jti: str | None = None,
    header: dict[str, Any] | None = None,
    payload: dict[str, Any] | None = None,
) -> str

Encode the JWT with the given expire, header, and payload (JWS).

Parameters:

Name	Type	Description	Default
exp	int | None	The expiration time in seconds.	None
nbf	int | None	The not-before time in seconds.	None
iss	str | None	The issuer.	None
sub	str | None	The subject.	None
aud	str | None	The audience.	None
jti	str | None	The JWT ID. If None, auto-generated.	None
header	dict[str, Any] | None	The header to include in the JWT.	None
payload	dict[str, Any] | None	The payload to include in the JWT.	None

Returns:

Name	Type	Description
str	str	The encoded JWT (JWS compact serialization).

Raises:

Type	Description
JamConfigurationError	If alg is not provided.

encrypt

encrypt(
    plaintext: bytes | str | dict[str, Any],
    header: dict[str, Any] | None = None,
) -> str

Encrypt payload using JWE.

If both jws and jwe are configured, creates JWS+JWE (sign then encrypt): 1. Create JWS compact serialization (sign) 2. Use JWS result as plaintext for JWE (encrypt)

Parameters:

Name	Type	Description	Default
plaintext	bytes | str | dict[str, Any]	Data to encrypt. If dict, will be JSON encoded.	required
header	dict[str, Any] | None	Additional JWE header.	None

Returns:

Name	Type	Description
str	str	Encrypted JWT (JWE or JWS+JWE).

Raises:

Type	Description
JamConfigurationError	If jwe is not configured.