Skip to content

Tokens

reauth.tokens

GeneratedToken dataclass 

GeneratedToken(token: str, identifier: str, verifier: str)

token instance-attribute 

token: str

identifier instance-attribute 

identifier: str

verifier instance-attribute 

verifier: str

InvalidTokenException 

InvalidTokenException(message: str | None = None)

Bases: TokenException

Raised for malformed bearer tokens.

TokenException 

TokenException(message: str | None = None)

Bases: ReauthException

Base exception for token errors.

TokenGenerationException 

TokenGenerationException(message: str | None = None)

Bases: TokenException

Raised when token generation or verifier creation fails.

TokenIdentifierCollision 

TokenIdentifierCollision(message: str | None = None)

Bases: TokenException

Storage rejected an identifier; no credential was persisted.

TokenParts dataclass 

TokenParts(identifier: str, secret: str)

identifier instance-attribute 

identifier: str

secret instance-attribute 

secret: str

TokenProvider

Bases: Protocol

generate async 

generate() -> GeneratedToken

Generate credentials; raise TokenGenerationException on backend failure.

parse 

parse(token: str) -> TokenParts

Parse credentials; raise InvalidTokenException on malformed input.

verify_and_update async 

verify_and_update(
    secret: str, verifier: str
) -> tuple[bool, str | None]

Verify and optionally upgrade only on success.

Invalid secrets return (False, None). Operational failures, including malformed or unsupported stored verifiers, raise TokenVerificationException. Implementations translate expected backend errors with their cause and offload blocking SDK calls. Programming errors and cancellation propagate.

TokenVerificationException 

TokenVerificationException(message: str | None = None)

Bases: TokenException

Raised when verification or verifier upgrade cannot be completed.

TokenVerifier

Bases: Protocol

create async 

create(secret: str) -> str

Create a verifier; raise TokenGenerationException on backend failure.

verify_and_update async 

verify_and_update(
    secret: str, verifier: str
) -> tuple[bool, str | None]

Verify a secret and optionally return an upgraded verifier on success.

Return (False, None) for invalid secrets, (True, None) for current verifiers, or (True, replacement) for a successful match needing upgrade. Malformed/unsupported stored verifiers and expected backend or upgrade failures raise TokenVerificationException with the backend cause. Offload blocking SDK calls; programming errors and cancellation propagate.

ChecksummedTokenProvider 

ChecksummedTokenProvider(
    *, prefix: str, verifier: TokenVerifier
)

Fixed format: prefix, 16-character identifier, 32-character secret, CRC32.

CRC32 is a corruption check, not authentication. Change the prefix when introducing incompatible component lengths. Identifiers have ~95 bits of entropy; secrets have ~190 bits. Storage must enforce identifier uniqueness.

prefix instance-attribute 

prefix = prefix

verifier instance-attribute 

verifier = verifier

generate async 

generate() -> GeneratedToken

Generate independently random identifier and secret components.

Returns:

Type Description
GeneratedToken

The complete token, public identifier and opaque verifier.

parse 

parse(token: str) -> TokenParts

Validate the complete format and checksum before any storage lookup.

Returns:

Type Description
TokenParts

The public identifier and secret.

Raises:

Type Description
InvalidTokenException

If the prefix, length, alphabet or checksum differs.

verify_and_update async 

verify_and_update(
    secret: str, verifier: str
) -> tuple[bool, str | None]

Delegate secret verification and upgrades to the injected verifier.

Returns:

Type Description
tuple[bool, str | None]

Whether the secret matches, and an optional replacement verifier.

HMACTokenVerifier 

HMACTokenVerifier(
    *, current_key_id: str, keys: Mapping[str, bytes]
)

HMAC-SHA256 with explicitly retained keys and lazy key rotation.

Keys must be at least 32 bytes. Verifiers encode format, key ID and MAC as hmac-sha256$1$key_id$hex_mac. Unknown keys fail operationally, rather than being mistaken for invalid credentials. Key retirement is manual.

current_key_id instance-attribute 

current_key_id = current_key_id

create async 

create(secret: str) -> str

Create a verifier with the current key.

Returns:

Type Description
str

The opaque, versioned verifier.

Raises:

Type Description
TokenGenerationException

If the secret cannot be encoded.

verify_and_update async 

verify_and_update(
    secret: str, verifier: str
) -> tuple[bool, str | None]

Verify retained keys and upgrade successful matches to the current key.

Returns:

Type Description
tuple[bool, str | None]

Whether the secret matches and an optional current-key verifier.

Raises:

Type Description
TokenVerificationException

If the stored format or key is unavailable, or a successful verification cannot be upgraded.