duck.contrib.jwt

JWT utilities for Duck’s auth system.

Provides token encoding, decoding, issuance, and rotation. Requires PyJWT — install with: pip install PyJWT

Package Contents

Functions

decode_token	Decode and verify a signed JWT token.
encode_token	Encode a signed JWT token from the given payload.
get_access_lifetime	Retrieve the access token lifetime from Duck settings.
get_algorithm	Retrieve the JWT signing algorithm from Duck settings.
get_jwt_lib	Import and return the PyJWT module.
get_refresh_lifetime	Retrieve the refresh token lifetime from Duck settings.
get_secret_key	Retrieve the secret key from Duck settings.
issue_token_pair	Issue both an access and a refresh token for a user.

API

exception duck.contrib.jwt.JWTError

Bases: Exception

Base class for JWT-related errors.

Initialization

Initialize self. See help(type(self)) for accurate signature.

exception duck.contrib.jwt.JWTExpired

Bases: duck.contrib.jwt.JWTError

Raised when a JWT has expired.

Initialization

Initialize self. See help(type(self)) for accurate signature.

exception duck.contrib.jwt.JWTInvalid

Bases: duck.contrib.jwt.JWTError

Raised when a JWT cannot be decoded or is structurally invalid.

Initialization

Initialize self. See help(type(self)) for accurate signature.

duck.contrib.jwt.decode_token(token: str, verify_expiry: bool = True) → Dict[str, Any]

Decode and verify a signed JWT token.

Parameters:

• token – The raw JWT string to decode.

• verify_expiry – Whether to verify. If True, JWTExpired may be raised on expiry.

Returns:

The decoded payload as a dict.

Raises:

• JWTExpired – If the token’s exp claim has passed.

• JWTInvalid – If the token is malformed, tampered with, or the signature does not match.

duck.contrib.jwt.encode_token(payload: dict[str, Any], token_type: str = 'access') → str

Encode a signed JWT token from the given payload.

Parameters:

• payload – Data to embed in the token (e.g. {"user_id": 1}).

• token_type – Either "access" or "refresh". Controls the default expiry when expires_in is not given.

• expires_in – Custom expiry duration. Overrides settings-based defaults.

Returns:

A signed JWT string.

duck.contrib.jwt.get_access_lifetime() → datetime.timedelta

Retrieve the access token lifetime from Duck settings.

Defaults to 60 minutes if JWT_ACCESS_LIFETIME is not set.

Returns:

Seconds representing the access token lifetime.

duck.contrib.jwt.get_algorithm() → str

Retrieve the JWT signing algorithm from Duck settings.

Defaults to HS256 if JWT_ALGORITHM is not set.

Returns:

The algorithm string (e.g. "HS256").

duck.contrib.jwt.get_jwt_lib()

Import and return the PyJWT module.

Returns:

The imported jwt module.

Raises:

ImportError – If the PyJWT package is not installed.

duck.contrib.jwt.get_refresh_lifetime() → float

Retrieve the refresh token lifetime from Duck settings.

Defaults to 7 days in seconds if JWT_REFRESH_LIFETIME is not set.

Returns:

Seconds representing the refresh token lifetime.

duck.contrib.jwt.get_secret_key() → str

Retrieve the secret key from Duck settings.

Returns:

The SECRET_KEY string from settings.

duck.contrib.jwt.issue_token_pair(payload: dict[str, Any] | None = None) → dict[str, str]

Issue both an access and a refresh token for a user.

Parameters:

payload – Additional claims embedded in both tokens.

Returns:

A dict with "access" and "refresh" JWT strings.