auth2fa 0.1.0__py3-none-any.whl

auth2fa/__init__.py

@@ -0,0 +1,19 @@
+"""
+auth2fa - TOTP-based Two-Factor Authentication Library
+
+A flexible and easy-to-use Python library for implementing TOTP-based
+two-factor authentication with support for multiple storage backends.
+"""
+
+from .core import TwoFactorAuth
+from .storage.base import BaseStorage
+from .storage.json_storage import JSONStorage
+from .storage.sql_storage import SQLStorage
+
+__version__ = '0.1.0'
+__all__ = [
+    'TwoFactorAuth',
+    'BaseStorage',
+    'JSONStorage',
+    'SQLStorage'
+]

auth2fa/core.py

@@ -0,0 +1,222 @@
+"""Core TOTP authentication logic for auth2fa."""
+import base64
+import pyotp
+import qrcode
+from io import BytesIO
+from datetime import datetime
+from typing import Optional, Dict
+from .storage.base import BaseStorage
+from .storage.json_storage import JSONStorage
+from .storage.sql_storage import SQLStorage
+from .recovery import generate_recovery_codes, verify_recovery_code
+
+
+class TwoFactorAuth:
+    """Main class for TOTP-based two-factor authentication."""
+
+    def __init__(self, issuer: str = "MyApp", storage_path: Optional[str] = None, sq=None):
+        """
+        Initialize TwoFactorAuth.
+
+        Args:
+            issuer: Name of the application/service for TOTP
+            storage_path: Path to JSON storage file (optional)
+            sq: sqloader instance for SQL storage (optional)
+
+        Initialization priority:
+        1. If sq is provided → SQLStorage
+        2. If storage_path is provided → JSONStorage with custom path
+        3. Otherwise → JSONStorage with default path ("./totp_data.json")
+        """
+        self.issuer = issuer
+
+        # Determine storage backend based on priority
+        if sq is not None:
+            self.storage = SQLStorage(sq)
+        elif storage_path is not None:
+            self.storage = JSONStorage(storage_path)
+        else:
+            self.storage = JSONStorage("./totp_data.json")
+
+    def setup(self, user_id: str, username: str = "") -> Dict:
+        """
+        Set up TOTP for a user.
+
+        Args:
+            user_id: Unique identifier for the user
+            username: Display name for the account (defaults to empty string)
+
+        Returns:
+            Dictionary containing:
+            {
+                "secret": "BASE32SECRET",
+                "qr_uri": "otpauth://totp/Issuer:username?secret=...&issuer=...",
+                "qr_image": "base64 encoded PNG QR image",
+                "recovery_codes": ["A3F8K2M1", ...]
+            }
+        """
+        user_id = str(user_id)  # Ensure user_id is string
+
+        if self.storage.exists(user_id):
+            raise ValueError(f"TOTP already configured for user: {user_id}")
+
+        # Generate secret and recovery codes
+        secret = pyotp.random_base32()
+        recovery_codes = generate_recovery_codes(count=8, length=8)
+
+        # Generate provisioning URI for QR code
+        account_name = username if username else user_id
+        totp = pyotp.TOTP(secret)
+        qr_uri = totp.provisioning_uri(
+            name=account_name,
+            issuer_name=self.issuer
+        )
+
+        # Generate QR code image
+        qr = qrcode.QRCode(version=1, box_size=10, border=5)
+        qr.add_data(qr_uri)
+        qr.make(fit=True)
+
+        img = qr.make_image(fill_color="black", back_color="white")
+        buffer = BytesIO()
+        img.save(buffer, format='PNG')
+        qr_image_bytes = buffer.getvalue()
+        qr_image_base64 = base64.b64encode(qr_image_bytes).decode('utf-8')
+
+        # Save to storage (not enabled yet)
+        data = {
+            'secret': secret,
+            'enabled': False,
+            'recovery_codes': recovery_codes,
+            'created_at': datetime.now().isoformat()
+        }
+        self.storage.save(user_id, data)
+
+        return {
+            "secret": secret,
+            "qr_uri": qr_uri,
+            "qr_image": qr_image_base64,
+            "recovery_codes": recovery_codes
+        }
+
+    def activate(self, user_id: str, code: str) -> bool:
+        """
+        Activate TOTP after user verifies the code from their app.
+
+        Args:
+            user_id: Unique identifier for the user
+            code: TOTP code from authenticator app
+
+        Returns:
+            True if activation successful, False if code is invalid
+        """
+        user_id = str(user_id)  # Ensure user_id is string
+
+        data = self.storage.get(user_id)
+        if not data:
+            raise ValueError(f"TOTP not configured for user: {user_id}")
+
+        if data['enabled']:
+            raise ValueError(f"TOTP already activated for user: {user_id}")
+
+        # Verify the token
+        secret = data['secret']
+        totp = pyotp.TOTP(secret)
+        if totp.verify(code, valid_window=1):
+            data['enabled'] = True
+            self.storage.save(user_id, data)
+            return True
+
+        return False
+
+    def verify(self, user_id: str, code: str) -> bool:
+        """
+        Verify TOTP code during login.
+
+        Args:
+            user_id: Unique identifier for the user
+            code: TOTP code or recovery code
+
+        Returns:
+            True if verification successful, False otherwise
+
+        Behavior:
+        - Unconfigured user → True (pass through)
+        - TOTP code verification (valid_window=1)
+        - If TOTP fails, try recovery code
+        - Recovery code used → automatically removed
+        """
+        user_id = str(user_id)  # Ensure user_id is string
+
+        data = self.storage.get(user_id)
+
+        # Unconfigured user → pass through
+        if not data:
+            return True
+
+        # Try TOTP code first
+        secret = data['secret']
+        totp = pyotp.TOTP(secret)
+        if totp.verify(code, valid_window=1):
+            return True
+
+        # TOTP failed, try recovery code
+        recovery_codes = data.get('recovery_codes', [])
+        is_valid, updated_codes = verify_recovery_code(recovery_codes, code)
+
+        if is_valid:
+            # Update storage with used code removed
+            data['recovery_codes'] = updated_codes
+            self.storage.save(user_id, data)
+            return True
+
+        return False
+
+    def disable(self, user_id: str) -> None:
+        """
+        Disable and remove TOTP configuration for a user.
+
+        Args:
+            user_id: Unique identifier for the user
+        """
+        user_id = str(user_id)  # Ensure user_id is string
+        self.storage.delete(user_id)
+
+    def is_enabled(self, user_id: str) -> bool:
+        """
+        Check if TOTP is enabled for a user.
+
+        Args:
+            user_id: Unique identifier for the user
+
+        Returns:
+            True if TOTP is enabled, False otherwise
+        """
+        user_id = str(user_id)  # Ensure user_id is string
+
+        data = self.storage.get(user_id)
+        if not data:
+            return False
+        return data.get('enabled', False)
+
+    def regenerate_recovery_codes(self, user_id: str) -> list:
+        """
+        Regenerate recovery codes for a user.
+
+        Args:
+            user_id: Unique identifier for the user
+
+        Returns:
+            List of new recovery codes
+        """
+        user_id = str(user_id)  # Ensure user_id is string
+
+        data = self.storage.get(user_id)
+        if not data:
+            raise ValueError(f"TOTP not configured for user: {user_id}")
+
+        new_codes = generate_recovery_codes(count=8, length=8)
+        data['recovery_codes'] = new_codes
+        self.storage.save(user_id, data)
+
+        return new_codes

auth2fa/recovery.py

@@ -0,0 +1,54 @@
+"""Recovery code generation and verification for auth2fa."""
+import secrets
+import string
+from typing import List, Tuple
+
+
+def generate_recovery_codes(count: int = 8, length: int = 8) -> List[str]:
+    """
+    Generate a list of random recovery codes.
+
+    Args:
+        count: Number of recovery codes to generate (default: 8)
+        length: Length of each recovery code (default: 8)
+
+    Returns:
+        List of recovery codes in format like ['A3F8K2M1', 'B7D2N4P9', ...]
+    """
+    codes = []
+    # Use alphanumeric characters excluding similar-looking ones (0, O, I, 1)
+    alphabet = string.ascii_uppercase + string.digits
+    alphabet = alphabet.replace('0', '').replace('O', '').replace('I', '').replace('1', '')
+
+    for _ in range(count):
+        code = ''.join(secrets.choice(alphabet) for _ in range(length))
+        codes.append(code)
+
+    return codes
+
+
+def verify_recovery_code(stored_codes: List[str], input_code: str) -> Tuple[bool, List[str]]:
+    """
+    Verify if a recovery code is valid and return updated code list.
+
+    Args:
+        stored_codes: List of valid recovery codes
+        input_code: The recovery code to verify
+
+    Returns:
+        Tuple of (is_valid, updated_codes):
+        - (True, codes with used code removed) if valid
+        - (False, original codes) if invalid
+
+    Recovery codes are single-use — successful verification removes the code.
+    """
+    # Case-insensitive comparison
+    input_upper = input_code.upper()
+    codes_upper = [rc.upper() for rc in stored_codes]
+
+    if input_upper in codes_upper:
+        # Remove the used code
+        updated_codes = [rc for rc in stored_codes if rc.upper() != input_upper]
+        return (True, updated_codes)
+    else:
+        return (False, stored_codes)

auth2fa/sql/totp_auth/create_table.sql

@@ -0,0 +1,13 @@
+-- Create TOTP authentication table
+CREATE TABLE IF NOT EXISTS totp_auth (
+    user_id VARCHAR(255) PRIMARY KEY,
+    secret VARCHAR(255) NOT NULL,
+    enabled BOOLEAN DEFAULT FALSE,
+    recovery_codes TEXT,
+    created_at DATETIME NOT NULL,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Create index for faster lookups
+CREATE INDEX IF NOT EXISTS idx_totp_auth_user_id ON totp_auth(user_id);
+CREATE INDEX IF NOT EXISTS idx_totp_auth_enabled ON totp_auth(enabled);

auth2fa/sql/totp_auth/delete.sql

@@ -0,0 +1,2 @@
+-- name: delete
+DELETE FROM totp_auth WHERE user_id = :user_id;

auth2fa/sql/totp_auth/insert.sql

@@ -0,0 +1,7 @@
+-- name: insert
+INSERT INTO totp_auth (user_id, secret, enabled, recovery_codes, created_at)
+VALUES (:user_id, :secret, :enabled, :recovery_codes, :created_at)
+ON CONFLICT (user_id) DO UPDATE
+SET secret = EXCLUDED.secret,
+    enabled = EXCLUDED.enabled,
+    recovery_codes = EXCLUDED.recovery_codes;

auth2fa/sql/totp_auth/select_by_user.sql

@@ -0,0 +1,2 @@
+-- name: select_by_user
+SELECT * FROM totp_auth WHERE user_id = :user_id;

auth2fa/sql/totp_auth/update.sql

@@ -0,0 +1,2 @@
+-- name: update
+UPDATE totp_auth SET enabled = :enabled, recovery_codes = :recovery_codes WHERE user_id = :user_id;

auth2fa/storage/__init__.py

@@ -0,0 +1,6 @@
+"""Storage modules for auth2fa."""
+from .base import BaseStorage
+from .json_storage import JSONStorage
+from .sql_storage import SQLStorage
+
+__all__ = ['BaseStorage', 'JSONStorage', 'SQLStorage']

auth2fa/storage/base.py

@@ -0,0 +1,60 @@
+"""Base storage interface for auth2fa."""
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+class BaseStorage(ABC):
+    """Abstract base class for TOTP storage implementations."""
+
+    @abstractmethod
+    def save(self, user_id: str, data: dict) -> None:
+        """
+        Save or update TOTP data for a user.
+
+        Args:
+            user_id: Unique identifier for the user
+            data: Dictionary containing TOTP data with structure:
+                {
+                    "secret": "BASE32SECRET",
+                    "enabled": False,
+                    "recovery_codes": ["A3F8K2M1", "B7D2N4P9", ...],
+                    "created_at": "2026-02-11T18:00:00"
+                }
+        """
+        pass
+
+    @abstractmethod
+    def get(self, user_id: str) -> Optional[dict]:
+        """
+        Retrieve TOTP data for a user.
+
+        Args:
+            user_id: Unique identifier for the user
+
+        Returns:
+            Dictionary containing TOTP data, or None if not found
+        """
+        pass
+
+    @abstractmethod
+    def delete(self, user_id: str) -> None:
+        """
+        Delete TOTP data for a user.
+
+        Args:
+            user_id: Unique identifier for the user
+        """
+        pass
+
+    @abstractmethod
+    def exists(self, user_id: str) -> bool:
+        """
+        Check if TOTP is configured for a user.
+
+        Args:
+            user_id: Unique identifier for the user
+
+        Returns:
+            True if TOTP data exists, False otherwise
+        """
+        pass

auth2fa/storage/json_storage.py

@@ -0,0 +1,131 @@
+"""JSON file-based storage implementation for auth2fa."""
+import json
+import time
+from pathlib import Path
+from typing import Optional
+from .base import BaseStorage
+
+
+class JSONStorage(BaseStorage):
+    """JSON file-based storage implementation with file locking."""
+
+    def __init__(self, storage_path: str = "./totp_data.json"):
+        """
+        Initialize JSON storage.
+
+        Args:
+            storage_path: Path to the JSON file for storing TOTP data
+        """
+        self.file_path = Path(storage_path)
+        self.lock_path = Path(str(self.file_path) + ".lock")
+        self._ensure_file_exists()
+
+    def _ensure_file_exists(self) -> None:
+        """Create the JSON file if it doesn't exist."""
+        if not self.file_path.exists():
+            self.file_path.parent.mkdir(parents=True, exist_ok=True)
+            self._write_data({})
+
+    def _acquire_lock(self, timeout: int = 5) -> None:
+        """
+        Acquire file lock using lock file.
+
+        Args:
+            timeout: Maximum time to wait for lock in seconds
+        """
+        start_time = time.time()
+        while self.lock_path.exists():
+            if time.time() - start_time > timeout:
+                raise TimeoutError("Failed to acquire file lock")
+            time.sleep(0.01)
+
+        # Create lock file
+        self.lock_path.touch()
+
+    def _release_lock(self) -> None:
+        """Release file lock by removing lock file."""
+        if self.lock_path.exists():
+            self.lock_path.unlink()
+
+    def _read_data(self) -> dict:
+        """Read all data from the JSON file."""
+        try:
+            with open(self.file_path, 'r', encoding='utf-8') as f:
+                return json.load(f)
+        except (json.JSONDecodeError, FileNotFoundError):
+            return {}
+
+    def _write_data(self, data: dict) -> None:
+        """Write all data to the JSON file."""
+        with open(self.file_path, 'w', encoding='utf-8') as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+
+    def save(self, user_id: str, data: dict) -> None:
+        """
+        Save or update TOTP data for a user.
+
+        Args:
+            user_id: Unique identifier for the user (converted to str)
+            data: Dictionary containing TOTP data
+        """
+        user_id = str(user_id)  # Ensure user_id is string
+        try:
+            self._acquire_lock()
+            all_data = self._read_data()
+            all_data[user_id] = data
+            self._write_data(all_data)
+        finally:
+            self._release_lock()
+
+    def get(self, user_id: str) -> Optional[dict]:
+        """
+        Retrieve TOTP data for a user.
+
+        Args:
+            user_id: Unique identifier for the user (converted to str)
+
+        Returns:
+            Dictionary containing TOTP data, or None if not found
+        """
+        user_id = str(user_id)  # Ensure user_id is string
+        try:
+            self._acquire_lock()
+            all_data = self._read_data()
+            return all_data.get(user_id)
+        finally:
+            self._release_lock()
+
+    def delete(self, user_id: str) -> None:
+        """
+        Delete TOTP data for a user.
+
+        Args:
+            user_id: Unique identifier for the user (converted to str)
+        """
+        user_id = str(user_id)  # Ensure user_id is string
+        try:
+            self._acquire_lock()
+            all_data = self._read_data()
+            if user_id in all_data:
+                del all_data[user_id]
+                self._write_data(all_data)
+        finally:
+            self._release_lock()
+
+    def exists(self, user_id: str) -> bool:
+        """
+        Check if TOTP is configured for a user.
+
+        Args:
+            user_id: Unique identifier for the user (converted to str)
+
+        Returns:
+            True if TOTP data exists, False otherwise
+        """
+        user_id = str(user_id)  # Ensure user_id is string
+        try:
+            self._acquire_lock()
+            all_data = self._read_data()
+            return user_id in all_data
+        finally:
+            self._release_lock()

auth2fa/storage/sql_storage.py

@@ -0,0 +1,105 @@
+"""SQL database storage implementation using sqloader."""
+import json
+from typing import Optional
+from .base import BaseStorage
+
+
+class SQLStorage(BaseStorage):
+    """SQL database storage implementation using sqloader."""
+
+    def __init__(self, sq, table_prefix: str = "totp_auth"):
+        """
+        Initialize SQL storage.
+
+        Args:
+            sq: sqloader instance (SQLite3 or MySQL)
+            table_prefix: SQL file directory name (default: totp_auth)
+        """
+        self.db = sq
+        self.table_prefix = table_prefix
+        self._ensure_table_exists()
+
+    def _ensure_table_exists(self) -> None:
+        """Create the TOTP table if it doesn't exist."""
+        # sqloader will execute the create_table.sql file
+        self.db.execute(f"{self.table_prefix}/create_table")
+
+    def save(self, user_id: str, data: dict) -> None:
+        """
+        Save or update TOTP data for a user.
+
+        Args:
+            user_id: Unique identifier for the user (converted to str)
+            data: Dictionary containing TOTP data
+        """
+        user_id = str(user_id)  # Ensure user_id is string
+
+        # Use INSERT with ON CONFLICT (UPSERT)
+        self.db.execute(
+            f"{self.table_prefix}/insert",
+            user_id=user_id,
+            secret=data.get('secret'),
+            enabled=data.get('enabled', False),
+            recovery_codes=json.dumps(data.get('recovery_codes', [])),
+            created_at=data.get('created_at')
+        )
+
+    def get(self, user_id: str) -> Optional[dict]:
+        """
+        Retrieve TOTP data for a user.
+
+        Args:
+            user_id: Unique identifier for the user (converted to str)
+
+        Returns:
+            Dictionary containing TOTP data, or None if not found
+        """
+        user_id = str(user_id)  # Ensure user_id is string
+
+        result = self.db.execute(
+            f"{self.table_prefix}/select_by_user",
+            user_id=user_id
+        )
+
+        if not result:
+            return None
+
+        row = result[0]
+        return {
+            'secret': row.get('secret'),
+            'enabled': bool(row.get('enabled')),
+            'recovery_codes': json.loads(row.get('recovery_codes', '[]')),
+            'created_at': row.get('created_at')
+        }
+
+    def delete(self, user_id: str) -> None:
+        """
+        Delete TOTP data for a user.
+
+        Args:
+            user_id: Unique identifier for the user (converted to str)
+        """
+        user_id = str(user_id)  # Ensure user_id is string
+
+        self.db.execute(
+            f"{self.table_prefix}/delete",
+            user_id=user_id
+        )
+
+    def exists(self, user_id: str) -> bool:
+        """
+        Check if TOTP is configured for a user.
+
+        Args:
+            user_id: Unique identifier for the user (converted to str)
+
+        Returns:
+            True if TOTP data exists, False otherwise
+        """
+        user_id = str(user_id)  # Ensure user_id is string
+
+        result = self.db.execute(
+            f"{self.table_prefix}/select_by_user",
+            user_id=user_id
+        )
+        return len(result) > 0