jam.jose.base¶

base ¶

Classes:

Name	Description
`BaseJWE`	Base JSON Web Encryption - RFC 7516.
`BaseJWK`	JSON Web Key - RFC 7517.
`BaseJWKSet`	JWK Set - RFC 7517 Section 5.
`BaseJWKStorage`	Base JWK Storage.
`BaseJWS`	Base JSON Web Signature - RFC 7515.
`BaseJWT`	Base JWT.

BaseJWE ¶

Bases: ABC

Base JSON Web Encryption - RFC 7516.

Methods:

Name	Description
`decrypt`	Decrypt JWE token.
`encrypt`	Encrypt plaintext.

decrypt `abstractmethod` ¶

decrypt(token: str) -> bytes

Decrypt JWE token.

Parameters:

Name	Type	Description	Default
`token`	`str`	JWE compact serialization string.	required

Returns:

Type	Description
`bytes`	Decrypted plaintext bytes.

Raises:

Type	Description
`JamJWEDecryptionError`	If decryption fails.

encrypt `abstractmethod` ¶

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

Encrypt plaintext.

Produces JWE Compact Serialization: BASE64URL(header).BASE64URL(encrypted_key).BASE64URL(iv).BASE64URL(ciphertext).BASE64URL(tag)

Parameters:

Name	Type	Description	Default
`plaintext`	`bytes \| str \| dict[str, Any]`	Data to encrypt. If str, will be encoded to UTF-8. If dict, will be JSON encoded.	required
`header`	`dict[str, Any] \| None`	JWE header (must include 'alg' and 'enc').	`None`

Returns:

Type	Description
`str`	JWE compact serialization string.

Raises:

Type	Description
`JamJWEEncryptionError`	If encryption fails.

BaseJWK ¶

Bases: ABC

JSON Web Key - RFC 7517.

Methods:

Name	Description
`from_dict`	Create JWK from dict.
`sign`	Sign data using JWK.
`to_dict`	Convert JWK to dict.
`validate`	Validate and create JWK from dict.
`verify`	Verify JWS token and return payload.

Attributes:

Name	Type	Description
`alg`	`str \| None`	Algorithm (alg) - RS256, ES256, etc.
`kid`	`str \| None`	Key ID (kid).
`kty`	`str`	Key type (kty) - RSA, EC, oct, etc.

alg `abstractmethod` `property` ¶

alg: str | None

Algorithm (alg) - RS256, ES256, etc.

kid `abstractmethod` `property` ¶

kid: str | None

Key ID (kid).

kty `abstractmethod` `property` ¶

kty: str

Key type (kty) - RSA, EC, oct, etc.

from_dict `abstractmethod` `classmethod` ¶

from_dict(data: dict[str, Any]) -> BaseJWK

Create JWK from dict.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	JWK dict.	required

Returns:

Type	Description
`BaseJWK`	JWK instance.

sign `abstractmethod` ¶

sign(data: bytes, alg: str | None = None) -> str

Sign data using JWK.

Parameters:

Name	Type	Description	Default
`data`	`bytes`	Data to sign.	required
`alg`	`str \| None`	Algorithm to use. If None, uses default for kty.	`None`

Returns:

Type	Description
`str`	JWS compact serialization string.

to_dict `abstractmethod` ¶

to_dict() -> dict[str, Any]

Convert JWK to dict.

Returns:

Type	Description
`dict[str, Any]`	JWK dict.

validate `abstractmethod` `staticmethod` ¶

validate(data: dict[str, Any]) -> BaseJWK

Validate and create JWK from dict.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	JWK dict to validate.	required

Returns:

Type	Description
`BaseJWK`	JWK instance.

Raises:

Type	Description
`ValueError`	If JWK is invalid.

verify `abstractmethod` ¶

verify(
    token: str, alg: str | None = None
) -> dict[str, Any]

Verify JWS token and return payload.

Parameters:

Name	Type	Description	Default
`token`	`str`	JWS compact serialization token.	required
`alg`	`str \| None`	Algorithm to use. If None, uses default for kty.	`None`

Returns:

Type	Description
`dict[str, Any]`	dict with 'header' and 'payload' keys.

BaseJWKSet ¶

Bases: ABC

JWK Set - RFC 7517 Section 5.

Methods:

Name	Description
`filter`	Filter JWKs by criteria.
`from_dict`	Create JWKSet from dict.
`get_by_kid`	Get JWK by key ID (kid).
`get_by_kty`	Get all JWKs by key type.
`to_dict`	Convert JWKSet to dict.

filter `abstractmethod` ¶

filter(**criteria: Any) -> list[dict[str, Any]]

Filter JWKs by criteria.

Parameters:

Name	Type	Description	Default
`**criteria`	`Any`	Filter criteria (kty, use, alg, key_ops, kid).	`{}`

Returns:

Type	Description
`list[dict[str, Any]]`	list[dict[str, Any]]: List of matching JWK dicts.

from_dict `abstractmethod` `classmethod` ¶

from_dict(data: dict[str, Any]) -> BaseJWKSet

Create JWKSet from dict.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	JWKSet dict with 'keys' array.	required

Returns:

Type	Description
`BaseJWKSet`	JWKSet instance.

get_by_kid `abstractmethod` ¶

get_by_kid(kid: str) -> dict[str, Any] | None

Get JWK by key ID (kid).

Parameters:

Name	Type	Description	Default
`kid`	`str`	Key ID to search for.	required

Returns:

Type	Description
`dict[str, Any] \| None`	dict[str, Any] \| None: JWK dict if found, None otherwise.

get_by_kty `abstractmethod` ¶

get_by_kty(kty: str) -> list[dict[str, Any]]

Get all JWKs by key type.

Parameters:

Name	Type	Description	Default
`kty`	`str`	Key type (RSA, EC, oct).	required

Returns:

Type	Description
`list[dict[str, Any]]`	list[dict[str, Any]]: List of matching JWK dicts.

to_dict `abstractmethod` ¶

to_dict() -> dict[str, Any]

Convert JWKSet to dict.

Returns:

Type	Description
`dict[str, Any]`	dict[str, Any]: JWKSet dict with 'keys' array.

BaseJWKStorage ¶

Bases: ABC

Base JWK Storage.

Methods:

Name	Description
`delete`	Delete a key by name.
`get`	Get a key by name.
`store`	Store a JWK with the given name.

delete `abstractmethod` ¶

delete(name: str) -> None

Delete a key by name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the key to delete.	required

get `abstractmethod` ¶

get(name: str) -> dict[str, Any] | None

Get a key by name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the key to retrieve.	required

Returns:

Type	Description
`dict[str, Any] \| None`	dict[str, Any] \| None: JWK dict if found.

store `abstractmethod` ¶

store(name: str, jwk: dict[str, Any]) -> None

Store a JWK with the given name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the key to store.	required
`jwk`	`dict[str, Any]`	JWK dict to store.	required

BaseJWS ¶

Bases: ABC

Base JSON Web Signature - RFC 7515.

Methods:

Name	Description
`deserialize_compact`	Parse JWS Compact Serialization.
`serialize_compact`	Create JWS Compact Serialization.
`sign`	Sign data and return JWS compact serialization.
`verify`	Verify JWS token and return header/payload.

deserialize_compact `abstractmethod` ¶

deserialize_compact(
    s: str, validate: bool = True
) -> dict[str, Any]

Parse JWS Compact Serialization.

Parameters:

Name	Type	Description	Default
`s`	`str`	JWS in compact serialization format.	required
`validate`	`bool`	Whether to validate signature. Defaults to True.	`True`

Returns:

Type	Description
`dict[str, Any]`	dict[str, Any]: Parsed JWS with keys: - header: Protected header dict - payload: Decoded payload bytes - signature: Raw signature bytes

Raises:

Type	Description
`JamJWSVerificationError`	If validation fails.

serialize_compact `abstractmethod` ¶

serialize_compact(
    protected: dict[str, Any], payload: bytes | str
) -> str

Create JWS Compact Serialization.

Parameters:

Name	Type	Description	Default
`protected`	`dict[str, Any]`	Protected header.	required
`payload`	`bytes \| str`	Payload to sign.	required

Returns:

Name	Type	Description
`str`	`str`	JWS in compact serialization format: BASE64URL(protected).BASE64URL(payload).BASE64URL(signature)

sign `abstractmethod` ¶

sign(
    header: dict[str, Any],
    data: bytes | str | dict[str, Any],
) -> str

Sign data and return JWS compact serialization.

Parameters:

Name	Type	Description	Default
`header`	`dict[str, Any]`	JWS header (must include 'alg').	required
`data`	`bytes \| str \| dict[str, Any]`	Data to sign. If dict, will be JSON encoded.	required

Returns:

Name	Type	Description
`str`	`str`	JWS compact serialization string.

verify `abstractmethod` ¶

verify(token: str, validate: bool = True) -> dict[str, Any]

Verify JWS token and return header/payload.

Parameters:

Name	Type	Description	Default
`token`	`str`	JWS compact serialization token.	required
`validate`	`bool`	Whether to validate signature. Defaults to True.	`True`

Returns:

Type	Description
`dict[str, Any]`	dict[str, Any]: Parsed JWS with 'header' and 'payload' keys.

Raises:

Type	Description
`JamJWSVerificationError`	If validation fails.

BaseJWT ¶

Bases: ABC

Base JWT.

Methods:

Name	Description
`decode`	Decode the JWT and return the header and payload.
`decrypt`	Decrypt JWE token.
`encode`	Encode the JWT with the given expire, header, and payload.
`encrypt`	Encrypt plaintext.

Attributes:

Name	Type	Description
`jti`	`str`	The JWT ID.

jti `abstractmethod` `property` ¶

jti: str

The JWT ID.

decode `abstractmethod` ¶

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	required
`validate_claims`	`bool`	Whether to validate exp/nbf claims.	`True`

Returns:

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

Raises:

Type	Description
`JamJWTExpired`	If token is expired.
`JamJWTNotYetValid`	If token is not yet valid.

decrypt `abstractmethod` ¶

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

Decrypt JWE token.

Parameters:

Name	Type	Description	Default
`token`	`str`	JWE compact serialization string.	required

Returns:

Name	Type	Description
`bytes`	`dict[str, Any] \| bytes`	Decrypted plaintext.

Raises:

Type	Description
`JamJWEDecryptionError`	If decryption fails.

encode `abstractmethod` ¶

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.

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.	`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.

encrypt `abstractmethod` ¶

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

Encrypt plaintext.

Produces JWE Compact Serialization: BASE64URL(header).BASE64URL(encrypted_key).BASE64URL(iv).BASE64URL(ciphertext).BASE64URL(tag)

Parameters:

Name	Type	Description	Default
`plaintext`	`bytes \| str \| dict[str, Any]`	Data to encrypt. If str, will be encoded to UTF-8. If dict, will be JSON encoded.	required
`header`	`dict[str, Any] \| None`	JWE header (must include 'alg' and 'enc').	`None`

Returns:

Type	Description
`str`	JWE compact serialization string.

Raises:

Type	Description
`JamJWEEncryptionError`	If encryption fails.

jam.jose.base¶

__base__ ¶

BaseJWE ¶

decrypt abstractmethod ¶

encrypt abstractmethod ¶

BaseJWK ¶

alg abstractmethod property ¶

kid abstractmethod property ¶

kty abstractmethod property ¶

from_dict abstractmethod classmethod ¶

sign abstractmethod ¶

to_dict abstractmethod ¶

validate abstractmethod staticmethod ¶

verify abstractmethod ¶

BaseJWKSet ¶

filter abstractmethod ¶

from_dict abstractmethod classmethod ¶

get_by_kid abstractmethod ¶

get_by_kty abstractmethod ¶

to_dict abstractmethod ¶

BaseJWKStorage ¶

delete abstractmethod ¶

get abstractmethod ¶

store abstractmethod ¶

BaseJWS ¶

deserialize_compact abstractmethod ¶

serialize_compact abstractmethod ¶

sign abstractmethod ¶

verify abstractmethod ¶

BaseJWT ¶

jti abstractmethod property ¶

decode abstractmethod ¶

decrypt abstractmethod ¶

encode abstractmethod ¶

encrypt abstractmethod ¶

base ¶

decrypt `abstractmethod` ¶

encrypt `abstractmethod` ¶

alg `abstractmethod` `property` ¶

kid `abstractmethod` `property` ¶

kty `abstractmethod` `property` ¶

from_dict `abstractmethod` `classmethod` ¶

sign `abstractmethod` ¶

to_dict `abstractmethod` ¶

validate `abstractmethod` `staticmethod` ¶

verify `abstractmethod` ¶

filter `abstractmethod` ¶

from_dict `abstractmethod` `classmethod` ¶

get_by_kid `abstractmethod` ¶

get_by_kty `abstractmethod` ¶

to_dict `abstractmethod` ¶

delete `abstractmethod` ¶

get `abstractmethod` ¶

store `abstractmethod` ¶

deserialize_compact `abstractmethod` ¶

serialize_compact `abstractmethod` ¶

sign `abstractmethod` ¶

verify `abstractmethod` ¶

jti `abstractmethod` `property` ¶

decode `abstractmethod` ¶

decrypt `abstractmethod` ¶

encode `abstractmethod` ¶

encrypt `abstractmethod` ¶