Authentication and Authorization¶

import bcrypt
import secrets
import hmac
import hashlib
from datetime import datetime, timedelta
from typing import Optional, Dict, Any

class PasswordManager:
    """Secure password hashing and validation"""

    def __init__(self, pepper: bytes = None):
        self.pepper = pepper or secrets.token_bytes(32)
        self.cost_factor = 12  # bcrypt work factor
        self.min_length = 12
        self.max_length = 128

    def hash_password(self, password: str) -> str:
        """
        Hash password with salt and pepper

        Args:
            password: Plain text password

        Returns:
            Hashed password string safe for database storage
        """
        if not self._validate_password_length(password):
            raise ValueError(f"Password must be {self.min_length}-{self.max_length} characters")

        # Apply pepper before hashing
        peppered = self._apply_pepper(password)

        # Generate salt and hash with bcrypt
        salt = bcrypt.gensalt(rounds=self.cost_factor)
        hashed = bcrypt.hashpw(peppered.encode('utf-8'), salt)

        return hashed.decode('utf-8')

    def verify_password(self, password: str, hashed_password: str) -> bool:
        """
        Verify password against stored hash with timing attack protection

        Args:
            password: Plain text password to verify
            hashed_password: Stored hash from database

        Returns:
            True if password matches, False otherwise
        """
        try:
            peppered = self._apply_pepper(password)
            result = bcrypt.checkpw(
                peppered.encode('utf-8'), 
                hashed_password.encode('utf-8')
            )
            return result
        except Exception:
            # Prevent timing attacks by consuming similar time
            bcrypt.checkpw(b"dummy_password", b"$2b$12$dummy.hash.value.for.timing.protection")
            return False

    def validate_password_strength(self, password: str) -> Dict[str, Any]:
        """
        Validate password meets security requirements

        Returns:
            Dictionary with validation results and strength score
        """
        issues = []

        # Length check
        if len(password) < self.min_length:
            issues.append(f"Must be at least {self.min_length} characters")
        if len(password) > self.max_length:
            issues.append(f"Must not exceed {self.max_length} characters")

        # Complexity checks
        if not any(c.isupper() for c in password):
            issues.append("Must contain uppercase letters")
        if not any(c.islower() for c in password):
            issues.append("Must contain lowercase letters")
        if not any(c.isdigit() for c in password):
            issues.append("Must contain numbers")
        if not any(c in "!@#$%^&*()_+-=[]{}|;:,.<>?" for c in password):
            issues.append("Must contain special characters")

        # Check against common passwords (simplified)
        if password.lower() in self._get_common_passwords():
            issues.append("Password is too common")

        entropy = self._calculate_entropy(password)

        return {
            "valid": len(issues) == 0,
            "issues": issues,
            "entropy_bits": entropy,
            "strength": self._classify_strength(entropy)
        }

    def _apply_pepper(self, password: str) -> str:
        """Apply server-side secret (pepper) to password"""
        return hmac.new(
            self.pepper, 
            password.encode('utf-8'), 
            hashlib.sha256
        ).hexdigest()

    def _validate_password_length(self, password: str) -> bool:
        """Check if password length is within acceptable range"""
        return self.min_length <= len(password) <= self.max_length

    def _calculate_entropy(self, password: str) -> float:
        """Calculate password entropy in bits"""
        charset_size = 0
        if any(c.islower() for c in password):
            charset_size += 26
        if any(c.isupper() for c in password):
            charset_size += 26
        if any(c.isdigit() for c in password):
            charset_size += 10
        if any(c in "!@#$%^&*()_+-=[]{}|;:,.<>?" for c in password):
            charset_size += 32

        import math
        return len(password) * math.log2(charset_size) if charset_size > 0 else 0

    def _classify_strength(self, entropy: float) -> str:
        """Classify password strength based on entropy"""
        if entropy < 40:
            return "weak"
        elif entropy < 60:
            return "moderate"
        elif entropy < 80:
            return "strong"
        else:
            return "very_strong"

    def _get_common_passwords(self) -> set:
        """Return set of common passwords to reject (load from file in production)"""
        return {"password", "123456", "qwerty", "admin", "letmein"}

class PasswordResetService:
    """Secure password reset token management"""

    def __init__(self, storage):
        self.storage = storage
        self.token_expiry_minutes = 30
        self.max_attempts = 3

    def generate_reset_token(self, user_id: str, email: str) -> str:
        """
        Generate secure password reset token

        Args:
            user_id: User identifier
            email: User's email address

        Returns:
            Reset token to send to user
        """
        # Generate cryptographically secure token
        token = secrets.token_urlsafe(32)

        # Store token with metadata
        token_data = {
            "user_id": user_id,
            "email": email,
            "created_at": datetime.utcnow().isoformat(),
            "expires_at": (datetime.utcnow() + timedelta(minutes=self.token_expiry_minutes)).isoformat(),
            "used": False,
            "attempts": 0
        }

        # Hash token before storage
        token_hash = hashlib.sha256(token.encode()).hexdigest()
        self.storage.save_reset_token(token_hash, token_data)

        return token

    def verify_reset_token(self, token: str) -> Optional[Dict[str, Any]]:
        """
        Verify reset token and return user data if valid

        Args:
            token: Reset token from user

        Returns:
            User data if valid, None otherwise
        """
        token_hash = hashlib.sha256(token.encode()).hexdigest()
        token_data = self.storage.get_reset_token(token_hash)

        if not token_data:
            return None

        # Check if token is already used
        if token_data.get("used"):
            return None

        # Check expiration
        expires_at = datetime.fromisoformat(token_data["expires_at"])
        if datetime.utcnow() > expires_at:
            return None

        # Check attempt limit
        if token_data.get("attempts", 0) >= self.max_attempts:
            return None

        return token_data

    def mark_token_used(self, token: str):
        """Mark reset token as used to prevent reuse"""
        token_hash = hashlib.sha256(token.encode()).hexdigest()
        self.storage.mark_token_used(token_hash)

const bcrypt = require('bcrypt');
const crypto = require('crypto');

class PasswordManager {
    constructor(pepper = null) {
        this.pepper = pepper || crypto.randomBytes(32);
        this.saltRounds = 12;
        this.minLength = 12;
        this.maxLength = 128;
    }

    /**
     * Hash password with salt and pepper
     * @param {string} password - Plain text password
     * @returns {Promise<string>} Hashed password
     */
    async hashPassword(password) {
        if (!this._validatePasswordLength(password)) {
            throw new Error(`Password must be ${this.minLength}-${this.maxLength} characters`);
        }

        // Apply pepper before hashing
        const peppered = this._applyPepper(password);

        // Generate salt and hash with bcrypt
        const salt = await bcrypt.genSalt(this.saltRounds);
        const hashed = await bcrypt.hash(peppered, salt);

        return hashed;
    }

    /**
     * Verify password against stored hash
     * @param {string} password - Plain text password
     * @param {string} hashedPassword - Stored hash
     * @returns {Promise<boolean>} True if valid
     */
    async verifyPassword(password, hashedPassword) {
        try {
            const peppered = this._applyPepper(password);
            const result = await bcrypt.compare(peppered, hashedPassword);
            return result;
        } catch (error) {
            // Prevent timing attacks
            await bcrypt.compare('dummy_password', '$2b$12$dummy.hash.value.for.timing.protection');
            return false;
        }
    }

    /**
     * Validate password meets security requirements
     * @param {string} password - Password to validate
     * @returns {Object} Validation results
     */
    validatePasswordStrength(password) {
        const issues = [];

        // Length check
        if (password.length < this.minLength) {
            issues.push(`Must be at least ${this.minLength} characters`);
        }
        if (password.length > this.maxLength) {
            issues.push(`Must not exceed ${this.maxLength} characters`);
        }

        // Complexity checks
        if (!/[A-Z]/.test(password)) {
            issues.push('Must contain uppercase letters');
        }
        if (!/[a-z]/.test(password)) {
            issues.push('Must contain lowercase letters');
        }
        if (!/\d/.test(password)) {
            issues.push('Must contain numbers');
        }
        if (!/[!@#$%^&*()_+\-=\[\]{}|;:,.<>?]/.test(password)) {
            issues.push('Must contain special characters');
        }

        // Check against common passwords
        if (this._getCommonPasswords().has(password.toLowerCase())) {
            issues.push('Password is too common');
        }

        const entropy = this._calculateEntropy(password);

        return {
            valid: issues.length === 0,
            issues: issues,
            entropyBits: entropy,
            strength: this._classifyStrength(entropy)
        };
    }

    _applyPepper(password) {
        const hmac = crypto.createHmac('sha256', this.pepper);
        hmac.update(password);
        return hmac.digest('hex');
    }

    _validatePasswordLength(password) {
        return password.length >= this.minLength && password.length <= this.maxLength;
    }

    _calculateEntropy(password) {
        let charsetSize = 0;
        if (/[a-z]/.test(password)) charsetSize += 26;
        if (/[A-Z]/.test(password)) charsetSize += 26;
        if (/\d/.test(password)) charsetSize += 10;
        if (/[!@#$%^&*()_+\-=\[\]{}|;:,.<>?]/.test(password)) charsetSize += 32;

        return charsetSize > 0 ? password.length * Math.log2(charsetSize) : 0;
    }

    _classifyStrength(entropy) {
        if (entropy < 40) return 'weak';
        if (entropy < 60) return 'moderate';
        if (entropy < 80) return 'strong';
        return 'very_strong';
    }

    _getCommonPasswords() {
        return new Set(['password', '123456', 'qwerty', 'admin', 'letmein']);
    }
}

module.exports = PasswordManager;

class PasswordResetService {
    constructor(storage) {
        this.storage = storage;
        this.tokenExpiryMinutes = 30;
        this.maxAttempts = 3;
    }

    /**
     * Generate secure password reset token
     * @param {string} userId - User identifier
     * @param {string} email - User's email
     * @returns {Promise<string>} Reset token
     */
    async generateResetToken(userId, email) {
        // Generate cryptographically secure token
        const token = crypto.randomBytes(32).toString('base64url');

        // Store token with metadata
        const tokenData = {
            userId: userId,
            email: email,
            createdAt: new Date().toISOString(),
            expiresAt: new Date(Date.now() + this.tokenExpiryMinutes * 60000).toISOString(),
            used: false,
            attempts: 0
        };

        // Hash token before storage
        const tokenHash = crypto.createHash('sha256').update(token).digest('hex');
        await this.storage.saveResetToken(tokenHash, tokenData);

        return token;
    }

    /**
     * Verify reset token validity
     * @param {string} token - Reset token from user
     * @returns {Promise<Object|null>} User data if valid
     */
    async verifyResetToken(token) {
        const tokenHash = crypto.createHash('sha256').update(token).digest('hex');
        const tokenData = await this.storage.getResetToken(tokenHash);

        if (!tokenData) {
            return null;
        }

        // Check if already used
        if (tokenData.used) {
            return null;
        }

        // Check expiration
        if (new Date() > new Date(tokenData.expiresAt)) {
            return null;
        }

        // Check attempt limit
        if (tokenData.attempts >= this.maxAttempts) {
            return null;
        }

        return tokenData;
    }

    /**
     * Mark token as used
     * @param {string} token - Reset token
     */
    async markTokenUsed(token) {
        const tokenHash = crypto.createHash('sha256').update(token).digest('hex');
        await this.storage.markTokenUsed(tokenHash);
    }
}

module.exports = PasswordResetService;

import pyotp
import qrcode
import secrets
import hashlib
from io import BytesIO
from base64 import b64encode
from typing import List, Dict, Any, Optional
from datetime import datetime

class TOTPService:
    """Time-based One-Time Password implementation"""

    def __init__(self, storage, encryption_service):
        self.storage = storage
        self.encryption = encryption_service
        self.issuer_name = "YourCompany"

    def setup_totp(self, user_id: str, username: str) -> Dict[str, Any]:
        """
        Initialize TOTP for user

        Returns:
            Dictionary containing secret, QR code, and backup codes
        """
        # Generate secret
        secret = pyotp.random_base32()

        # Create TOTP instance
        totp = pyotp.TOTP(secret)

        # Generate provisioning URI for QR code
        provisioning_uri = totp.provisioning_uri(
            name=username,
            issuer_name=self.issuer_name
        )

        # Generate QR code
        qr = qrcode.QRCode(version=1, box_size=10, border=4)
        qr.add_data(provisioning_uri)
        qr.make(fit=True)

        img = qr.make_image(fill_color="black", back_color="white")
        buffer = BytesIO()
        img.save(buffer, format='PNG')
        qr_code = b64encode(buffer.getvalue()).decode()

        # Generate backup codes
        backup_service = BackupCodeService(self.storage)
        backup_codes = backup_service.generate_codes(user_id)

        # Encrypt and store secret
        encrypted_secret = self.encryption.encrypt(secret)
        self.storage.save_totp_secret(user_id, encrypted_secret)

        return {
            "secret": secret,  # Show once for manual entry
            "qr_code": qr_code,
            "provisioning_uri": provisioning_uri,
            "backup_codes": backup_codes
        }

    def verify_totp(self, user_id: str, token: str, window: int = 1) -> Dict[str, bool]:
        """
        Verify TOTP token with replay protection

        Args:
            user_id: User identifier
            token: 6-digit TOTP code
            window: Time window tolerance (±30s per window)

        Returns:
            Verification result
        """
        # Check replay protection
        if self._is_token_used(user_id, token):
            return {"valid": False, "reason": "token_reused"}

        # Retrieve and decrypt secret
        encrypted_secret = self.storage.get_totp_secret(user_id)
        if not encrypted_secret:
            return {"valid": False, "reason": "mfa_not_configured"}

        secret = self.encryption.decrypt(encrypted_secret)

        # Verify token
        totp = pyotp.TOTP(secret)
        is_valid = totp.verify(token, valid_window=window)

        if is_valid:
            # Mark token as used (valid for 90 seconds)
            self._mark_token_used(user_id, token, 90)
            self._log_mfa_event(user_id, "totp_success")
            return {"valid": True}
        else:
            self._log_mfa_event(user_id, "totp_failed")
            return {"valid": False, "reason": "invalid_code"}

    def _is_token_used(self, user_id: str, token: str) -> bool:
        """Check if token was recently used"""
        token_key = f"totp_used:{user_id}:{token}"
        return self.storage.exists(token_key)

    def _mark_token_used(self, user_id: str, token: str, ttl: int):
        """Mark token as used with TTL"""
        token_key = f"totp_used:{user_id}:{token}"
        self.storage.set_with_expiry(token_key, "1", ttl)

    def _log_mfa_event(self, user_id: str, event_type: str):
        """Log MFA events for monitoring"""
        import logging
        logger = logging.getLogger('security.mfa')
        logger.info(f"MFA event: {event_type} for user {user_id}")

class BackupCodeService:
    """Single-use backup code management"""

    def __init__(self, storage):
        self.storage = storage
        self.code_count = 10
        self.code_length = 8

    def generate_codes(self, user_id: str) -> List[str]:
        """
        Generate new backup codes for user

        Returns:
            List of backup codes (shown once to user)
        """
        codes = []
        hashed_codes = []

        for _ in range(self.code_count):
            # Generate random code
            code = ''.join(
                secrets.choice('ABCDEFGHJKLMNPQRSTUVWXYZ23456789')
                for _ in range(self.code_length)
            )
            codes.append(code)

            # Hash before storage
            hashed = hashlib.sha256(code.encode()).hexdigest()
            hashed_codes.append(hashed)

        # Store hashed codes
        self.storage.save_backup_codes(user_id, hashed_codes)

        return codes

    def verify_code(self, user_id: str, code: str) -> Dict[str, Any]:
        """
        Verify and consume backup code

        Returns:
            Verification result with remaining count
        """
        # Retrieve stored codes
        stored_codes = self.storage.get_backup_codes(user_id)
        if not stored_codes:
            return {"valid": False, "reason": "no_codes"}

        # Hash input code
        code_hash = hashlib.sha256(code.encode()).hexdigest()

        # Check if code exists and mark as used
        if code_hash in stored_codes:
            stored_codes.remove(code_hash)
            self.storage.save_backup_codes(user_id, stored_codes)

            remaining = len(stored_codes)
            if remaining <= 2:
                # Warn user to generate new codes
                self._send_low_codes_warning(user_id, remaining)

            return {
                "valid": True,
                "remaining_codes": remaining
            }

        return {"valid": False, "reason": "invalid_code"}

    def _send_low_codes_warning(self, user_id: str, remaining: int):
        """Notify user when backup codes are running low"""
        pass  # Implement notification logic

const speakeasy = require('speakeasy');
const QRCode = require('qrcode');
const crypto = require('crypto');

class TOTPService {
    constructor(storage, encryptionService) {
        this.storage = storage;
        this.encryption = encryptionService;
        this.issuerName = 'YourCompany';
    }

    /**
     * Initialize TOTP for user
     * @param {string} userId - User identifier
     * @param {string} username - Username for display
     * @returns {Promise<Object>} Setup information
     */
    async setupTOTP(userId, username) {
        // Generate secret
        const secret = speakeasy.generateSecret({
            length: 32,
            name: `${this.issuerName}:${username}`,
            issuer: this.issuerName
        });

        // Generate QR code
        const qrCodeDataUrl = await QRCode.toDataURL(secret.otpauth_url);

        // Generate backup codes
        const backupService = new BackupCodeService(this.storage);
        const backupCodes = await backupService.generateCodes(userId);

        // Encrypt and store secret
        const encryptedSecret = this.encryption.encrypt(secret.base32);
        await this.storage.saveTOTPSecret(userId, encryptedSecret);

        return {
            secret: secret.base32,  // Show once for manual entry
            qrCode: qrCodeDataUrl,
            otpauthUrl: secret.otpauth_url,
            backupCodes: backupCodes
        };
    }

    /**
     * Verify TOTP token with replay protection
     * @param {string} userId - User identifier
     * @param {string} token - 6-digit code
     * @returns {Promise<Object>} Verification result
     */
    async verifyTOTP(userId, token) {
        // Check replay protection
        if (await this._isTokenUsed(userId, token)) {
            return { valid: false, reason: 'token_reused' };
        }

        // Retrieve and decrypt secret
        const encryptedSecret = await this.storage.getTOTPSecret(userId);
        if (!encryptedSecret) {
            return { valid: false, reason: 'mfa_not_configured' };
        }

        const secret = this.encryption.decrypt(encryptedSecret);

        // Verify token with time window
        const isValid = speakeasy.totp.verify({
            secret: secret,
            encoding: 'base32',
            token: token,
            window: 1  // ±30 seconds tolerance
        });

        if (isValid) {
            // Mark token as used (90 seconds)
            await this._markTokenUsed(userId, token, 90);
            this._logMFAEvent(userId, 'totp_success');
            return { valid: true };
        } else {
            this._logMFAEvent(userId, 'totp_failed');
            return { valid: false, reason: 'invalid_code' };
        }
    }

    async _isTokenUsed(userId, token) {
        const tokenKey = `totp_used:${userId}:${token}`;
        return await this.storage.exists(tokenKey);
    }

    async _markTokenUsed(userId, token, ttl) {
        const tokenKey = `totp_used:${userId}:${token}`;
        await this.storage.setWithExpiry(tokenKey, '1', ttl);
    }

    _logMFAEvent(userId, eventType) {
        const logger = require('./logger');
        logger.info(`MFA event: ${eventType} for user ${userId}`);
    }
}

module.exports = TOTPService;

class BackupCodeService {
    constructor(storage) {
        this.storage = storage;
        this.codeCount = 10;
        this.codeLength = 8;
    }

    /**
     * Generate new backup codes
     * @param {string} userId - User identifier
     * @returns {Promise<Array<string>>} Backup codes
     */
    async generateCodes(userId) {
        const codes = [];
        const hashedCodes = [];

        for (let i = 0; i < this.codeCount; i++) {
            // Generate random code
            const code = this._generateRandomCode();
            codes.push(code);

            // Hash before storage
            const hash = crypto.createHash('sha256').update(code).digest('hex');
            hashedCodes.push(hash);
        }

        // Store hashed codes
        await this.storage.saveBackupCodes(userId, hashedCodes);

        return codes;
    }

    /**
     * Verify and consume backup code
     * @param {string} userId - User identifier
     * @param {string} code - Backup code
     * @returns {Promise<Object>} Verification result
     */
    async verifyCode(userId, code) {
        // Retrieve stored codes
        const storedCodes = await this.storage.getBackupCodes(userId);
        if (!storedCodes || storedCodes.length === 0) {
            return { valid: false, reason: 'no_codes' };
        }

        // Hash input code
        const codeHash = crypto.createHash('sha256').update(code).digest('hex');

        // Check if code exists
        const index = storedCodes.indexOf(codeHash);
        if (index !== -1) {
            // Remove used code
            storedCodes.splice(index, 1);
            await this.storage.saveBackupCodes(userId, storedCodes);

            const remaining = storedCodes.length;
            if (remaining <= 2) {
                this._sendLowCodesWarning(userId, remaining);
            }

            return {
                valid: true,
                remainingCodes: remaining
            };
        }

        return { valid: false, reason: 'invalid_code' };
    }

    _generateRandomCode() {
        const chars = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
        let code = '';
        for (let i = 0; i < this.codeLength; i++) {
            code += chars[crypto.randomInt(chars.length)];
        }
        return code;
    }

    _sendLowCodesWarning(userId, remaining) {
        // Implement notification logic
    }
}

module.exports = BackupCodeService;

import dev.samstevens.totp.code.*;
import dev.samstevens.totp.qr.*;
import dev.samstevens.totp.secret.SecretGenerator;
import dev.samstevens.totp.time.SystemTimeProvider;
import java.security.SecureRandom;
import java.security.MessageDigest;
import java.util.*;

public class TOTPService {
    private final TokenStorage storage;
    private final EncryptionService encryption;
    private final String issuerName = "YourCompany";

    private final SecretGenerator secretGenerator;
    private final CodeGenerator codeGenerator;
    private final CodeVerifier codeVerifier;

    public TOTPService(TokenStorage storage, EncryptionService encryption) {
        this.storage = storage;
        this.encryption = encryption;
        this.secretGenerator = new DefaultSecretGenerator();
        this.codeGenerator = new DefaultCodeGenerator();
        this.codeVerifier = new DefaultCodeVerifier(codeGenerator, new SystemTimeProvider());
    }

    /**
     * Initialize TOTP for user
     * @param userId User identifier
     * @param username Username for display
     * @return Setup information
     */
    public TOTPSetupResult setupTOTP(String userId, String username) throws Exception {
        // Generate secret
        String secret = secretGenerator.generate();

        // Generate QR code
        QrData qrData = new QrData.Builder()
            .label(username)
            .secret(secret)
            .issuer(issuerName)
            .algorithm(HashingAlgorithm.SHA1)
            .digits(6)
            .period(30)
            .build();

        QrGenerator qrGenerator = new ZxingPngQrGenerator();
        byte[] qrImage = qrGenerator.generate(qrData);
        String qrCodeBase64 = Base64.getEncoder().encodeToString(qrImage);

        // Generate backup codes
        BackupCodeService backupService = new BackupCodeService(storage);
        List<String> backupCodes = backupService.generateCodes(userId);

        // Encrypt and store secret
        String encryptedSecret = encryption.encrypt(secret);
        storage.saveTOTPSecret(userId, encryptedSecret);

        return new TOTPSetupResult(secret, qrCodeBase64, backupCodes);
    }

    /**
     * Verify TOTP token with replay protection
     * @param userId User identifier
     * @param token 6-digit code
     * @return Verification result
     */
    public VerificationResult verifyTOTP(String userId, String token) {
        // Check replay protection
        if (isTokenUsed(userId, token)) {
            return new VerificationResult(false, "token_reused");
        }

        // Retrieve and decrypt secret
        String encryptedSecret = storage.getTOTPSecret(userId);
        if (encryptedSecret == null) {
            return new VerificationResult(false, "mfa_not_configured");
        }

        String secret = encryption.decrypt(encryptedSecret);

        // Verify token with time window (±1 period)
        boolean isValid = codeVerifier.isValidCode(secret, token);

        if (isValid) {
            // Mark token as used (90 seconds)
            markTokenUsed(userId, token, 90);
            logMFAEvent(userId, "totp_success");
            return new VerificationResult(true, null);
        } else {
            logMFAEvent(userId, "totp_failed");
            return new VerificationResult(false, "invalid_code");
        }
    }

    private boolean isTokenUsed(String userId, String token) {
        String tokenKey = "totp_used:" + userId + ":" + token;
        return storage.exists(tokenKey);
    }

    private void markTokenUsed(String userId, String token, int ttlSeconds) {
        String tokenKey = "totp_used:" + userId + ":" + token;
        storage.setWithExpiry(tokenKey, "1", ttlSeconds);
    }

    private void logMFAEvent(String userId, String eventType) {
        // Implement logging
    }

    public static class TOTPSetupResult {
        private final String secret;
        private final String qrCode;
        private final List<String> backupCodes;

        public TOTPSetupResult(String secret, String qrCode, List<String> backupCodes) {
            this.secret = secret;
            this.qrCode = qrCode;
            this.backupCodes = backupCodes;
        }

        public String getSecret() { return secret; }
        public String getQrCode() { return qrCode; }
        public List<String> getBackupCodes() { return backupCodes; }
    }

    public static class VerificationResult {
        private final boolean valid;
        private final String reason;

        public VerificationResult(boolean valid, String reason) {
            this.valid = valid;
            this.reason = reason;
        }

        public boolean isValid() { return valid; }
        public String getReason() { return reason; }
    }
}

public class BackupCodeService {
    private final TokenStorage storage;
    private final int codeCount = 10;
    private final int codeLength = 8;
    private final String chars = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";

    public BackupCodeService(TokenStorage storage) {
        this.storage = storage;
    }

    /**
     * Generate new backup codes
     * @param userId User identifier
     * @return List of backup codes
     */
    public List<String> generateCodes(String userId) throws Exception {
        List<String> codes = new ArrayList<>();
        List<String> hashedCodes = new ArrayList<>();
        SecureRandom random = new SecureRandom();

        for (int i = 0; i < codeCount; i++) {
            // Generate random code
            StringBuilder code = new StringBuilder();
            for (int j = 0; j < codeLength; j++) {
                code.append(chars.charAt(random.nextInt(chars.length())));
            }
            String codeStr = code.toString();
            codes.add(codeStr);

            // Hash before storage
            MessageDigest digest = MessageDigest.getInstance("SHA-256");
            byte[] hash = digest.digest(codeStr.getBytes());
            hashedCodes.add(bytesToHex(hash));
        }

        // Store hashed codes
        storage.saveBackupCodes(userId, hashedCodes);

        return codes;
    }

    /**
     * Verify and consume backup code
     * @param userId User identifier
     * @param code Backup code
     * @return Verification result
     */
    public BackupCodeResult verifyCode(String userId, String code) throws Exception {
        // Retrieve stored codes
        List<String> storedCodes = storage.getBackupCodes(userId);
        if (storedCodes == null || storedCodes.isEmpty()) {
            return new BackupCodeResult(false, 0, "no_codes");
        }

        // Hash input code
        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        byte[] hash = digest.digest(code.getBytes());
        String codeHash = bytesToHex(hash);

        // Check if code exists
        if (storedCodes.contains(codeHash)) {
            storedCodes.remove(codeHash);
            storage.saveBackupCodes(userId, storedCodes);

            int remaining = storedCodes.size();
            if (remaining <= 2) {
                sendLowCodesWarning(userId, remaining);
            }

            return new BackupCodeResult(true, remaining, null);
        }

        return new BackupCodeResult(false, storedCodes.size(), "invalid_code");
    }

    private void sendLowCodesWarning(String userId, int remaining) {
        // Implement notification logic
    }

    private String bytesToHex(byte[] bytes) {
        StringBuilder result = new StringBuilder();
        for (byte b : bytes) {
            result.append(String.format("%02x", b));
        }
        return result.toString();
    }

    public static class BackupCodeResult {
        private final boolean valid;
        private final int remainingCodes;
        private final String reason;

        public BackupCodeResult(boolean valid, int remainingCodes, String reason) {
            this.valid = valid;
            this.remainingCodes = remainingCodes;
            this.reason = reason;
        }

        public boolean isValid() { return valid; }
        public int getRemainingCodes() { return remainingCodes; }
        public String getReason() { return reason; }
    }
}