reauth 0.1.0__py3-none-any.whl

reauth/__init__.py

@@ -0,0 +1,3 @@
+"""The authentication toolkit for Python"""
+
+__version__ = "0.1.0"

reauth/amr.py

@@ -0,0 +1,96 @@
+"""Authentication Method Reference Values (amr) per RFC 8176.
+
+This module defines the standard Authentication Method Reference values
+as specified in RFC 8176 for use in JWT amr claims. These values represent
+the authentication methods used in an authentication event.
+
+See: https://datatracker.ietf.org/doc/html/rfc8176
+"""
+
+from enum import StrEnum
+
+
+class AuthenticationMethodReference(StrEnum):
+    """Standard Authentication Method Reference values (amr) per RFC 8176.
+
+    These values are used in the 'amr' claim of JSON Web Tokens (JWT) to
+    identify the authentication methods used in an authentication event.
+
+    Each value represents a family of closely related authentication methods.
+    The registry is maintained by IANA and is extensible.
+    """
+
+    # Biometric methods
+    FACE = "face"
+    """Facial recognition biometric authentication."""
+
+    FPT = "fpt"
+    """Fingerprint biometric authentication."""
+
+    IRIS = "iris"
+    """Iris scan biometric authentication."""
+
+    RETINA = "retina"
+    """Retina scan biometric authentication."""
+
+    VBM = "vbm"
+    """Voice biometric authentication."""
+
+    # Knowledge-based methods
+    KBA = "kba"
+    """Knowledge-based authentication (e.g., security questions)."""
+
+    PIN = "pin"
+    """Personal Identification Number or pattern authentication."""
+
+    PWD = "pwd"
+    """Password-based authentication."""
+
+    # Possession-based methods
+    HWK = "hwk"
+    """Proof-of-Possession of a hardware-secured key."""
+
+    OTP = "otp"
+    """One-time password (HOTP/TOTP)."""
+
+    SC = "sc"
+    """Smart card authentication."""
+
+    SWK = "swk"
+    """Proof-of-Possession of a software-secured key."""
+
+    # Out-of-band methods
+    SMS = "sms"
+    """SMS text message confirmation."""
+
+    TEL = "tel"
+    """Telephone call confirmation."""
+
+    EMAIL = "email"
+    """Email-based OTP or magic link authentication.
+
+    This is a custom extension to RFC 8176, not part of the standard.
+    """
+
+    # Multi-factor and risk-based methods
+    MFA = "mfa"
+    """Multiple-factor authentication."""
+
+    MCA = "mca"
+    """Multiple-channel authentication."""
+
+    RBA = "rba"
+    """Risk-based authentication."""
+
+    # Special purpose
+    GEO = "geo"
+    """Geolocation-based authentication."""
+
+    USER = "user"
+    """User presence test."""
+
+    WIA = "wia"
+    """Windows Integrated Authentication."""
+
+
+__all__ = ["AuthenticationMethodReference"]

reauth/authentication_session.py

@@ -0,0 +1,217 @@
+import abc
+import dataclasses
+import datetime
+import typing
+
+from .amr import AuthenticationMethodReference
+from .crypto import TokenHash, generate_token_hash_pair, get_token_hash
+from .exceptions import ReauthException
+from .factors import FactorBase
+from .timestamp import get_current_timestamp
+
+
+@dataclasses.dataclass
+class AuthenticationSession:
+    id: typing.Any | None
+    token_hash: TokenHash
+    expires_at: int
+    identity_id: typing.Any | None
+    amr: list[AuthenticationMethodReference] = dataclasses.field(default_factory=list)
+
+    def is_expired(self) -> bool:
+        """
+        Check if the session has expired.
+
+        Returns:
+            True if the session has expired, False otherwise.
+        """
+        return get_current_timestamp() >= self.expires_at
+
+
+class AuthenticationSessionException(ReauthException):
+    """Base exception for authentication session errors."""
+
+    pass
+
+
+class InvalidSessionTokenException(AuthenticationSessionException):
+    """Raised when a token is invalid or does not correspond to any session."""
+
+    pass
+
+
+class ExpiredSessionException(AuthenticationSessionException):
+    """Raised when a session has expired."""
+
+    pass
+
+
+class UnavailableFactorException(AuthenticationSessionException):
+    """Raised when trying to advance a session with a factor that is not available for the session."""
+
+    pass
+
+
+class AuthenticationSessionService(abc.ABC):
+    """
+    Abstract base class for managing authentication sessions.
+
+    An authentication session represents a pre-auth state that can be used to
+    authenticate a user, allowing to manage multi-factor authentication flows.
+    """
+
+    def __init__(
+        self,
+        *,
+        hash_secret: str,
+        factors: set[FactorBase],
+        token_prefix: str = "ls_",
+        lifetime: datetime.timedelta = datetime.timedelta(minutes=15),
+    ) -> None:
+        self.hash_secret = hash_secret
+        self.factors = factors
+        self.token_prefix = token_prefix
+        self.lifetime = lifetime
+
+    async def create(self) -> tuple[str, AuthenticationSession]:
+        """
+        Create a fresh authentication session.
+
+        Returns:
+            A tuple of (token, AuthenticationSession instance).
+        """
+        token, token_hash = generate_token_hash_pair(
+            secret=self.hash_secret, prefix=self.token_prefix
+        )
+        authentication_session = AuthenticationSession(
+            id=None,
+            token_hash=token_hash,
+            expires_at=get_current_timestamp() + int(self.lifetime.total_seconds()),
+            identity_id=None,
+        )
+        authentication_session.id = await self.insert(authentication_session)
+        return token, authentication_session
+
+    async def get_by_token(self, token: str) -> AuthenticationSession:
+        """
+        Validate a token and return the corresponding authentication session.
+
+        Args:
+            token: The token to validate.
+
+        Returns:
+            The corresponding AuthenticationSession instance.
+
+        Raises:
+            InvalidTokenException: If the token is invalid or does not correspond to any session.
+            ExpiredSessionException: If the session corresponding to the token has expired.
+        """
+        token_hash = get_token_hash(token, secret=self.hash_secret)
+        authentication_session = await self.get_by_token_hash(token_hash)
+        if authentication_session is None:
+            raise InvalidSessionTokenException()
+        if authentication_session.is_expired():
+            raise ExpiredSessionException()
+        return authentication_session
+
+    async def get_available_factors(
+        self, authentication_session: AuthenticationSession
+    ) -> set[FactorBase]:
+        """
+        Get the set of available factors for a given authentication session.
+
+        Args:
+            authentication_session: The AuthenticationSession instance to get available factors for.
+
+        Returns:
+            A set of FactorBase instances representing the available factors for the session.
+        """
+        available: set[FactorBase] = set()
+        for factor in self.factors:
+            # Already used?
+            if factor.AMR in authentication_session.amr:
+                continue
+            # Meets min_prior_factors?
+            if len(authentication_session.amr) < factor.min_prior_factors:
+                continue
+            # Enrolled for the identity in the session (if any)?
+            if authentication_session.identity_id is not None:
+                factor_enrollment = await factor.get_enrollment(
+                    authentication_session.identity_id
+                )
+                if factor_enrollment is None:
+                    continue
+            available.add(factor)
+        return available
+
+    async def advance(
+        self,
+        authentication_session: AuthenticationSession,
+        identity_id: typing.Any,
+        factor: FactorBase,
+    ) -> AuthenticationSession:
+        """
+        Advance an authentication session by marking a factor as completed.
+
+        Args:
+            authentication_session: The AuthenticationSession instance to advance.
+            identity_id: The ID of the identity that has completed the factor.
+            factor: The FactorBase instance representing the factor that has been completed.
+
+        Returns:
+            The updated AuthenticationSession instance.
+
+        Raises:
+            UnavailableFactorException: If the factor is not available for the session.
+        """
+        available_factors = await self.get_available_factors(authentication_session)
+        if factor not in available_factors:
+            raise UnavailableFactorException()
+
+        authentication_session.identity_id = identity_id
+        authentication_session.amr.append(factor.AMR)
+        await self.update(authentication_session)
+
+        return authentication_session
+
+    @abc.abstractmethod
+    async def insert(self, authentication_session: AuthenticationSession) -> typing.Any:
+        """
+        Insert an authentication session into a persistent store.
+
+        Implementers should implement this method.
+
+        Args:
+            authentication_session: The AuthenticationSession instance to insert.
+
+        Returns:
+            The ID of the inserted authentication session.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def get_by_token_hash(self, token_hash: str) -> AuthenticationSession | None:
+        """
+        Retrieve an authentication session by its token hash from the persistent store.
+
+        Implementers should implement this method.
+
+        Args:
+            token_hash: The hash of the token to look up.
+
+        Returns:
+            The corresponding AuthenticationSession instance, or None if not found.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def update(self, authentication_session: AuthenticationSession) -> None:
+        """
+        Update an authentication session in the persistent store.
+
+        Implementers should implement this method.
+
+        Args:
+            authentication_session: The AuthenticationSession instance to update.
+        """
+        ...

reauth/crypto.py

@@ -0,0 +1,112 @@
+"""A set of cryptographic utilities."""
+
+import hashlib
+import hmac
+import secrets
+import string
+import typing
+import zlib
+
+TokenHash = typing.NewType("TokenHash", str)
+
+
+def _crc32_to_base62(number: int) -> str:
+    characters = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+    base = len(characters)
+    encoded = ""
+    while number:
+        number, remainder = divmod(number, base)
+        encoded = characters[remainder] + encoded
+    return encoded.zfill(6)  # Ensure the checksum is 6 characters long
+
+
+def get_token_hash(token: str, *, secret: str) -> TokenHash:
+    """Compute HMAC-SHA256 hash of a token.
+
+    Args:
+        token: The token value to hash.
+        secret: The secret key used for HMAC computation.
+
+    Returns:
+        Hexadecimal string of the HMAC-SHA256 hash.
+    """
+    hash = hmac.new(secret.encode("ascii"), token.encode("ascii"), hashlib.sha256)
+    return TokenHash(hash.hexdigest())
+
+
+def generate_token(*, prefix: str = "") -> str:
+    """Generate a high-entropy random token with embedded checksum.
+
+    The token consists of a random string of 37 alphanumeric characters
+    followed by a 6-character base62-encoded CRC32 checksum.
+
+    The CRC32 checksum provides fast pre-validation to filter out malformed
+    or corrupted tokens before more expensive HMAC verification or database
+    lookups. It is NOT a cryptographic security mechanism.
+
+    Args:
+        prefix: Optional prefix prepended to the generated token.
+
+    Returns:
+        A token string with format: {prefix}{37_random_chars}{6_checksum_chars}.
+    """
+    # Generate a high entropy random token
+    token = "".join(
+        secrets.choice(string.ascii_letters + string.digits) for _ in range(37)
+    )
+
+    # Calculate a 32-bit CRC checksum
+    checksum = zlib.crc32(token.encode("utf-8")) & 0xFFFFFFFF
+    checksum_base62 = _crc32_to_base62(checksum)
+
+    # Concatenate the prefix, token, and checksum
+    return f"{prefix}{token}{checksum_base62}"
+
+
+def generate_token_hash_pair(*, secret: str, prefix: str = "") -> tuple[str, TokenHash]:
+    """Generate a token and its HMAC-SHA256 hash pair.
+
+    Generates a high-entropy token with embedded checksum and computes its
+    HMAC-SHA256 hash using the provided secret. This pattern allows storing
+    only the hash in the database while the raw token is provided to the user.
+
+    Args:
+        secret: The secret key used for HMAC computation.
+        prefix: Optional prefix prepended to the generated token.
+
+    Returns:
+        A tuple of (token, hash) where token is the raw value and hash is
+        its HMAC-SHA256 hexadecimal digest.
+    """
+    token = generate_token(prefix=prefix)
+    return token, get_token_hash(token, secret=secret)
+
+
+def generate_code_hash_pair(*, secret: str, length: int = 6) -> tuple[str, TokenHash]:
+    """Generate a 6-alphanumeric code and its HMAC-SHA256 hash pair.
+
+    This is useful for generating OTP codes where the raw code is sent to the
+    user and only the hash is stored for verification.
+
+    Args:
+        secret: The secret key used for HMAC computation.
+        length: The length of the numeric code to generate (default is 6).
+
+    Returns:
+        A tuple of (code, hash) where code is the raw code and hash is
+        its HMAC-SHA256 hexadecimal digest.
+    """
+    code = "".join(
+        secrets.choice(string.ascii_uppercase + string.digits) for _ in range(length)
+    )
+    code_hash = get_token_hash(code, secret=secret)
+    return code, code_hash
+
+
+__all__ = [
+    "TokenHash",
+    "get_token_hash",
+    "generate_code_hash_pair",
+    "generate_token",
+    "generate_token_hash_pair",
+]

reauth/exceptions.py

@@ -0,0 +1,9 @@
+class ReauthException(Exception):
+    """Base exception for reauth."""
+
+    def __init__(self, message: str | None = None) -> None:
+        self.message = message
+        super().__init__(message)
+
+
+__all__ = ["ReauthException"]

reauth/factors/__init__.py

@@ -0,0 +1,3 @@
+from .base import FactorBase
+
+__all__ = ["FactorBase"]

reauth/factors/base.py

@@ -0,0 +1,44 @@
+import abc
+import typing
+
+from ..amr import AuthenticationMethodReference
+
+
+class FactorEnrollment(typing.Protocol):
+    """
+    Protocol for factor enrollment objects,
+    which represent the state of an enrolled factor for a given identity.
+    """
+
+    id: typing.Any | None
+    identity_id: typing.Any
+
+
+class FactorBase(abc.ABC):
+    """Base abstract class for all factor services."""
+
+    AMR: typing.ClassVar[AuthenticationMethodReference]
+
+    def __init__(self, *, min_prior_factors: int = 0) -> None:
+        """
+        Initialize the factor base.
+
+        Args:
+            min_prior_factors: Minimum number of prior factors that must complete
+                before this factor can be used. Defaults to 0 (can be first factor).
+        """
+        self.min_prior_factors = min_prior_factors
+
+    @abc.abstractmethod
+    async def get_enrollment(self, identity_id: typing.Any) -> FactorEnrollment | None:
+        """
+        Get the enrollment information for a given identity.
+
+        Args:
+            identity_id: The ID of the identity to get the factor configuration for.
+
+        Returns:
+            The enrollment information for the factor,
+            or None if the factor is not enrolled for the identity.
+        """
+        ...

reauth/factors/email_otp.py

@@ -0,0 +1,198 @@
+import abc
+import dataclasses
+import datetime
+import typing
+
+from reauth.exceptions import ReauthException
+
+from ..amr import AuthenticationMethodReference
+from ..crypto import generate_code_hash_pair, get_token_hash
+from ..timestamp import get_current_timestamp
+from .base import FactorBase
+
+
+@dataclasses.dataclass
+class EmailOTPEnrollment:
+    id: typing.Any | None
+    identity_id: typing.Any
+    email: str
+
+
+@dataclasses.dataclass
+class EmailOTP:
+    id: typing.Any | None
+    identity_id: typing.Any
+    code_hash: str
+    expires_at: int
+    authentication_session_id: typing.Any
+
+    def is_expired(self) -> bool:
+        """
+        Check if the OTP has expired.
+
+        Returns:
+            True if the OTP has expired, False otherwise.
+        """
+        return get_current_timestamp() >= self.expires_at
+
+
+class EmailOTPException(ReauthException):
+    """Base exception for email OTP errors."""
+
+    pass
+
+
+class InvalidOTPException(EmailOTPException):
+    """Raised when an OTP code is invalid."""
+
+    pass
+
+
+class ExpiredOTPException(EmailOTPException):
+    """Raised when an OTP code has expired."""
+
+    pass
+
+
+class EmailOTPFactor(FactorBase, abc.ABC):
+    AMR: typing.ClassVar[AuthenticationMethodReference] = (
+        AuthenticationMethodReference.EMAIL
+    )
+
+    def __init__(
+        self,
+        *,
+        hash_secret: str,
+        code_length: int = 6,
+        lifetime: datetime.timedelta = datetime.timedelta(minutes=10),
+        min_prior_factors: int = 0,
+    ) -> None:
+        super().__init__(min_prior_factors=min_prior_factors)
+        self.hash_secret = hash_secret
+        self.code_length = code_length
+        self.lifetime = lifetime
+
+    async def create(
+        self, identity_id: typing.Any, authentication_session_id: typing.Any
+    ) -> tuple[str, EmailOTP]:
+        """
+        Create a new OTP for the given identity.
+
+        If an existing OTP for the same authentication session exists,
+        it's deleted and replaced with the new one.
+
+        Args:
+            identity_id: The ID of the identity to create the OTP for.
+            authentication_session_id: The ID of the authentication session this OTP is associated with.
+
+        Returns:
+            A tuple of (OTP code, EmailOTP instance).
+        """
+        await self.delete_by_authentication_session_id(authentication_session_id)
+
+        code, code_hash = generate_code_hash_pair(
+            secret=self.hash_secret, length=self.code_length
+        )
+        email_otp = EmailOTP(
+            id=None,
+            code_hash=code_hash,
+            expires_at=get_current_timestamp() + int(self.lifetime.total_seconds()),
+            identity_id=identity_id,
+            authentication_session_id=authentication_session_id,
+        )
+        email_otp.id = await self.insert(email_otp)
+
+        return code, email_otp
+
+    async def consume(self, code: str, authentication_session_id: object) -> None:
+        """
+        Consume an OTP code, deleting it from the persistent store if valid.
+
+        Args:
+            code: The OTP code to consume.
+            authentication_session_id: The ID of the authentication session this OTP is associated with.
+
+        Raises:
+            InvalidOTPException: If the code is invalid or does not correspond to any OTP.
+            ExpiredOTPException: If the OTP has expired.
+        """
+        code_hash = get_token_hash(code, secret=self.hash_secret)
+        email_otp = await self.get_by_code_hash_and_authentication_session_id(
+            code_hash, authentication_session_id
+        )
+        if email_otp is None:
+            raise InvalidOTPException()
+        if email_otp.is_expired():
+            raise ExpiredOTPException()
+        await self.delete(email_otp)
+
+    @abc.abstractmethod
+    async def insert(self, email_otp: EmailOTP) -> typing.Any:
+        """
+        Insert an EmailOTP instance into a persistent store.
+
+        Implementers should implement this method.
+
+        Args:
+            email_otp: The EmailOTP instance to insert.
+
+        Returns:
+            The ID of the inserted EmailOTP.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def get_by_code_hash_and_authentication_session_id(
+        self, code_hash: str, authentication_session_id: typing.Any
+    ) -> EmailOTP | None:
+        """
+        Retrieve an EmailOTP instance by its code hash from the persistent store.
+
+        Implementers should implement this method.
+
+        Args:
+            code_hash: The hash of the OTP code to retrieve.
+            authentication_session_id: The ID of the authentication session this OTP is associated with.
+
+        Returns:
+            The corresponding EmailOTP instance, or None if not found.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def update(self, email_otp: EmailOTP) -> None:
+        """
+        Update an EmailOTP instance in the persistent store.
+
+        Implementers should implement this method.
+
+        Args:
+            email_otp: The EmailOTP instance to update.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def delete(self, email_otp: EmailOTP) -> None:
+        """
+        Delete an EmailOTP instance from the persistent store.
+
+        Implementers should implement this method.
+
+        Args:
+            email_otp: The EmailOTP instance to delete.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def delete_by_authentication_session_id(
+        self, authentication_session_id: typing.Any
+    ) -> None:
+        """
+        Delete all EmailOTP instances associated with a given authentication session ID.
+
+        Implementers should implement this method.
+
+        Args:
+            authentication_session_id: The ID of the authentication session to delete OTPs for.
+        """
+        ...

reauth/factors/hotp.py

@@ -0,0 +1,164 @@
+import abc
+import base64
+import dataclasses
+import functools
+import secrets
+import typing
+
+from cryptography.hazmat.primitives.hashes import SHA1
+from cryptography.hazmat.primitives.twofactor import InvalidToken
+from cryptography.hazmat.primitives.twofactor.hotp import HOTP as CryptoHOTP
+
+from reauth.exceptions import ReauthException
+
+from ..amr import AuthenticationMethodReference
+from .base import FactorBase
+
+type HOTPAlgorithm = typing.Literal["sha1"]
+
+
+def _get_algorithm(algorithm: HOTPAlgorithm) -> SHA1:
+    match algorithm:
+        case "sha1":
+            return SHA1()
+
+
+@dataclasses.dataclass
+class HOTPEnrollment:
+    id: typing.Any | None
+    identity_id: typing.Any
+    secret: str
+    algorithm: HOTPAlgorithm
+    code_length: int
+    counter: int
+
+    @functools.cached_property
+    def _impl(self) -> CryptoHOTP:
+        return CryptoHOTP(
+            key=base64.b32decode(self.secret.encode("ascii")),
+            length=self.code_length,
+            algorithm=_get_algorithm(self.algorithm),
+        )
+
+    def get_provisioning_uri(
+        self, account_name: str, issuer_name: str | None = None
+    ) -> str:
+        """
+        Get the provisioning URI for this HOTP factor.
+
+        Args:
+            account_name: The name of the account (e.g., email or username).
+            issuer_name: The name of the issuer (e.g., your service name).
+
+        Returns:
+            The provisioning URI that can be used to generate a QR code for enrollment in an authenticator app.
+        """
+        return self._impl.get_provisioning_uri(account_name, self.counter, issuer_name)
+
+
+class HOTPException(ReauthException):
+    """Base exception for HOTP errors."""
+
+    pass
+
+
+class InvalidHOTPCodeException(HOTPException):
+    """Raised when an HOTP code is invalid."""
+
+    pass
+
+
+class HOTPFactor(FactorBase, abc.ABC):
+    AMR: typing.ClassVar[AuthenticationMethodReference] = (
+        AuthenticationMethodReference.OTP
+    )
+
+    def __init__(
+        self,
+        *,
+        code_length: int = 6,
+        algorithm: HOTPAlgorithm = "sha1",
+        look_ahead: int = 5,
+        min_prior_factors: int = 1,
+    ) -> None:
+        super().__init__(min_prior_factors=min_prior_factors)
+        self.code_length = code_length
+        self.algorithm: HOTPAlgorithm = algorithm
+        self.look_ahead = look_ahead
+
+    async def enroll(self, identity_id: typing.Any) -> HOTPEnrollment:
+        """
+        Enroll a new HOTP factor for a given identity.
+
+        Args:
+            identity_id: The ID of the identity to enroll the factor for.
+
+        Returns:
+            The enrolled HOTP factor.
+        """
+        secret = secrets.token_bytes(20)  # 160-bit secret key
+        hotp = HOTPEnrollment(
+            id=None,
+            secret=base64.b32encode(secret).decode("ascii"),
+            algorithm=self.algorithm,
+            code_length=self.code_length,
+            counter=0,
+            identity_id=identity_id,
+        )
+        hotp.id = await self.insert(hotp)
+        return hotp
+
+    async def verify(self, hotp: HOTPEnrollment, code: str) -> None:
+        """
+        Verify a provided OTP code against the expected value for the given HOTP factor.
+
+        On success, the counter is incremented and the HOTP factor is updated in the persistent store.
+
+        Args:
+            hotp: The HOTP factor to verify against.
+            code: The OTP code provided by the user.
+
+        Raises:
+            InvalidHOTPCodeException: If the provided code is invalid.
+        """
+        encoded_code = code.encode("ascii")
+        counter = hotp.counter
+
+        while True:
+            try:
+                hotp._impl.verify(encoded_code, counter)
+                break
+            except InvalidToken as e:
+                if counter - hotp.counter >= self.look_ahead:
+                    raise InvalidHOTPCodeException() from e
+                counter += 1
+
+        hotp.counter = counter + 1
+        await self.update(hotp)
+
+    @abc.abstractmethod
+    async def insert(self, hotp: HOTPEnrollment) -> typing.Any:
+        """
+        Insert an HOTP factor into a persistent store.
+
+        Implementers should implement this method.
+
+        Args:
+            hotp: The HOTP factor to insert.
+
+        Returns:
+            The ID of the inserted HOTP factor.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def update(self, hotp: HOTPEnrollment) -> None:
+        """
+        Update an HOTP factor in the persistent store.
+
+        Implementers should implement this method.
+
+        Args:
+            hotp: The HOTP factor to update.
+        """
+        ...

reauth/factors/totp.py

@@ -0,0 +1,174 @@
+import abc
+import base64
+import dataclasses
+import functools
+import secrets
+import time
+import typing
+
+from cryptography.hazmat.primitives.hashes import SHA1
+from cryptography.hazmat.primitives.twofactor import InvalidToken
+from cryptography.hazmat.primitives.twofactor.totp import TOTP as CryptoTOTP
+
+from reauth.exceptions import ReauthException
+
+from ..amr import AuthenticationMethodReference
+from .base import FactorBase
+
+type TOTPAlgorithm = typing.Literal["sha1", "sha256", "sha512"]
+
+
+def _get_algorithm(algorithm: TOTPAlgorithm) -> typing.Any:
+    match algorithm:
+        case "sha1":
+            return SHA1()
+        case "sha256":
+            from cryptography.hazmat.primitives.hashes import SHA256
+
+            return SHA256()
+        case "sha512":
+            from cryptography.hazmat.primitives.hashes import SHA512
+
+            return SHA512()
+
+
+@dataclasses.dataclass
+class TOTPEnrollment:
+    id: typing.Any | None
+    identity_id: typing.Any
+    secret: str
+    algorithm: TOTPAlgorithm
+    code_length: int
+    time_step: int
+    last_verified_time_step: int | None = None
+
+    @functools.cached_property
+    def _impl(self) -> CryptoTOTP:
+        return CryptoTOTP(
+            key=base64.b32decode(self.secret.encode("ascii")),
+            length=self.code_length,
+            algorithm=_get_algorithm(self.algorithm),
+            time_step=self.time_step,
+        )
+
+    def get_provisioning_uri(
+        self, account_name: str, issuer_name: str | None = None
+    ) -> str:
+        """
+        Get the provisioning URI for this TOTP factor.
+
+        Args:
+            account_name: The name of the account (e.g., email or username).
+            issuer_name: The name of the issuer (e.g., your service name).
+
+        Returns:
+            The provisioning URI that can be used to generate a QR code for enrollment in an authenticator app.
+        """
+        return self._impl.get_provisioning_uri(account_name, issuer_name)
+
+
+class TOTPException(ReauthException):
+    """Base exception for TOTP errors."""
+
+    pass
+
+
+class InvalidTOTPCodeException(TOTPException):
+    """Raised when a TOTP code is invalid."""
+
+    pass
+
+
+class TOTPFactor(FactorBase, abc.ABC):
+    AMR: typing.ClassVar[AuthenticationMethodReference] = (
+        AuthenticationMethodReference.OTP
+    )
+
+    def __init__(
+        self,
+        *,
+        code_length: int = 6,
+        algorithm: TOTPAlgorithm = "sha256",
+        time_step: int = 30,
+        drift_tolerance: int = 1,
+        min_prior_factors: int = 1,
+    ) -> None:
+        super().__init__(min_prior_factors=min_prior_factors)
+        self.code_length = code_length
+        self.algorithm: TOTPAlgorithm = algorithm
+        self.time_step = time_step
+        self.drift_tolerance = drift_tolerance
+
+    async def enroll(self, identity_id: typing.Any) -> TOTPEnrollment:
+        """
+        Enroll a new TOTP factor for a given identity.
+
+        Args:
+            identity_id: The ID of the identity to enroll the factor for.
+
+        Returns:
+            The enrolled TOTP factor.
+        """
+        secret = secrets.token_bytes(20)  # 160-bit secret key
+        totp = TOTPEnrollment(
+            id=None,
+            secret=base64.b32encode(secret).decode("ascii"),
+            algorithm=self.algorithm,
+            code_length=self.code_length,
+            time_step=self.time_step,
+            identity_id=identity_id,
+            last_verified_time_step=None,
+        )
+        totp.id = await self.insert(totp)
+        return totp
+
+    async def verify(self, totp: TOTPEnrollment, code: str) -> None:
+        """
+        Verify a provided OTP code against the expected value for the given TOTP factor.
+
+        Args:
+            totp: The TOTP factor to verify against.
+            code: The OTP code provided by the user.
+
+        Raises:
+            InvalidTOTPCodeException: If the provided code is invalid or has already been used.
+        """
+        encoded_code = code.encode("ascii")
+        current_time = int(time.time())
+        drift = -self.drift_tolerance
+
+        while True:
+            try:
+                # Calculate the actual Unix time for this drift step
+                check_time = current_time + drift * totp.time_step
+                # Calculate the time step for this check
+                check_time_step = check_time // totp.time_step
+
+                # Replay protection: reject if this time step has already been verified
+                if (
+                    totp.last_verified_time_step is not None
+                    and check_time_step <= totp.last_verified_time_step
+                ):
+                    drift += 1
+                    continue
+
+                totp._impl.verify(encoded_code, check_time)
+            except InvalidToken as e:
+                if drift > self.drift_tolerance:
+                    raise InvalidTOTPCodeException() from e
+                drift += 1
+            else:
+                # Update last verified time step and persist
+                totp.last_verified_time_step = check_time_step
+                await self.update(totp)
+                return
+
+    @abc.abstractmethod
+    async def insert(self, totp: TOTPEnrollment) -> typing.Any:
+        """Insert a TOTP factor into a persistent store."""
+        ...
+
+    @abc.abstractmethod
+    async def update(self, totp: TOTPEnrollment) -> None:
+        """Update a TOTP factor in the persistent store."""
+        ...

reauth/timestamp.py

@@ -0,0 +1,8 @@
+import datetime
+
+
+def get_current_timestamp() -> int:
+    return int(datetime.datetime.now(datetime.UTC).timestamp())
+
+
+__all__ = ["get_current_timestamp"]

reauth-0.1.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: reauth
+Version: 0.1.0
+Summary: The authentication toolkit for Python
+Project-URL: Documentation, https://frankie567.github.io/reauth/
+Project-URL: Source, https://github.com/frankie567/reauth
+Author-email: reauth <hello@fvoron.com>
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.14
+Requires-Dist: anyio
+Requires-Dist: cryptography<49.0.0,>=48.0.0
+Description-Content-Type: text/markdown
+
+# Reauth
+
+<p align="center">
+    <em>The authentication toolkit for Python</em>
+</p>
+
+[![build](https://github.com/frankie567/reauth/workflows/Build/badge.svg)](https://github.com/frankie567/reauth/actions)
+[![codecov](https://codecov.io/gh/frankie567/reauth/branch/master/graph/badge.svg)](https://codecov.io/gh/frankie567/reauth)
+[![PyPI version](https://badge.fury.io/py/reauth.svg)](https://badge.fury.io/py/reauth)
+
+---
+
+**Documentation**: <a href="https://frankie567.github.io/reauth/" target="_blank">https://frankie567.github.io/reauth/</a>
+
+**Source Code**: <a href="https://github.com/frankie567/reauth" target="_blank">https://github.com/frankie567/reauth</a>
+
+---
+
+> [!WARNING]
+> This is an early-stage project with many moving parts and mostly missing documentation. The API is not yet stable and breaking changes are expected.
+
+## Roadmap
+
+Our vision is to build a comprehensive, flexible authentication toolkit for Python that handles everything from low-level factor primitives to high-level OIDC server capabilities.
+
+### Short-term: Core Foundation
+
+- [ ] Factor primitives — building blocks for authentication factors
+    - [x] Email OTP
+    - [x] HOTP
+    - [x] TOTP
+    - [ ] Passwords
+    - [ ] Security keys
+    - [ ] Passkeys
+    - [ ] Social Login
+- [x] MFA authentication management — multi-factor authentication workflows
+
+### Mid-term: Integration Layer
+
+- [ ] Sessions management — robust session handling
+- [ ] ORM and web frameworks wrappers — seamless integration with popular frameworks
+
+### Long-term: Full Platform
+
+- [ ] OIDC server — complete OpenID Connect provider implementation
+- [ ] Team management — multi-user and organizational features
+- [ ] And more — expanding the ecosystem
+
+## Development
+
+### Setup environment
+
+We use [uv](https://docs.astral.sh/uv/) to manage the development environment and production build, and [just](https://github.com/casey/just) to manage command shortcuts. Ensure they are installed on your system.
+
+### Run unit tests
+
+You can run all the tests with:
+
+```bash
+just test
+```
+
+### Format the code
+
+Execute the following command to apply linting and check typing:
+
+```bash
+just lint
+```
+
+### Publish a new version
+
+You can bump the version, create a commit and associated tag with one command:
+
+```bash
+just version patch
+```
+
+```bash
+just version minor
+```
+
+```bash
+just version major
+```
+
+Your default Git text editor will open so you can add information about the release.
+
+When you push the tag on GitHub, the workflow will automatically publish it on PyPi and a GitHub release will be created as draft.
+
+## Serve the documentation
+
+You can serve the Mkdocs documentation with:
+
+```bash
+just docs-serve
+```
+
+It'll automatically watch for changes in your code.
+
+## License
+
+This project is licensed under the terms of the MIT license.

reauth-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+reauth/__init__.py,sha256=hX2ohrI4CjrfoZm7GU4qQq3M8FMAsxcLUlKSxNqXa-U,67
+reauth/amr.py,sha256=gffUu4AqBeQkO7YUZjAfqVsoVKAuANSCkxwUq7QNOtY,2421
+reauth/authentication_session.py,sha256=-2hwF8-SyKIGoT4jOJf7e2wKJE3JyVMbdc5uVDBTvLg,7169
+reauth/crypto.py,sha256=STsQ-PaiIcLqwft-yhpYvW3YoSCwkctr1F7DOGQrE_I,3635
+reauth/exceptions.py,sha256=dhbRca8XkfcXspVf47mFrKGIknhiesbt1o5viL1Hr7A,229
+reauth/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+reauth/timestamp.py,sha256=WgSMBAH9KA7KhysU7HkQgDG7b2SKCV7bKPHFDfuggdY,156
+reauth/factors/__init__.py,sha256=2SsYgK0xqpfVCddW8owL7Aio3QtynugCn7MTkOpum0k,55
+reauth/factors/base.py,sha256=1WmwNgOAnSF2up8VrdLMZsTfVLm9_0qQ624rl2YKVnk,1255
+reauth/factors/email_otp.py,sha256=1Tt0Ra-cS506-oWYQAzGQ3zvZdYGA5Qi_rel8hIRAVM,5768
+reauth/factors/hotp.py,sha256=-uWDfGUGutCfFUYRAhjaa1wtqb-k9qmmk33vJOJIbS0,4603
+reauth/factors/totp.py,sha256=fuf7_t6RVveEblx5eZ9h0Mhf3ZjiGrujKWjxD2gHfEc,5415
+reauth-0.1.0.dist-info/METADATA,sha256=Q5zJKNec99VNiR9Ofay9yxRf5kJyu8g2jkpTQLoGGmw,3346
+reauth-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+reauth-0.1.0.dist-info/licenses/LICENSE,sha256=nJKVyHWG779aFOFjAyk1dXYrhEdpZ9nMybIA6JsPJ7k,1074
+reauth-0.1.0.dist-info/RECORD,,

reauth-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

reauth-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026, François Voron
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+