mini2fa 0.1.0__py3-none-any.whl

mini2fa/config.py

@@ -0,0 +1,50 @@
+"""
+配置管理
+"""
+import os
+from pathlib import Path
+
+
+# 数据目录（存储在用户主目录下的 .mini2fa）
+DATA_DIR = Path.home() / '.mini2fa'
+DB_PATH = DATA_DIR / 'mini2fa.db'
+KEY_PATH = DATA_DIR / 'master.key'
+BACKUP_DIR = DATA_DIR / 'backups'
+
+# 安全参数
+SALT_SIZE = 16          # 盐长度
+KEY_SIZE = 32           # 密钥长度（256-bit）
+ITERATIONS = 600_000    # PBKDF2 迭代次数（OWASP 推荐）
+NONCE_SIZE = 12         # GCM Nonce 长度
+
+# 默认 OTP 参数
+DEFAULT_ALGORITHM = 'SHA1'
+DEFAULT_DIGITS = 6
+DEFAULT_PERIOD = 30
+DEFAULT_CATEGORY = 'default'
+
+
+def init_data_dir():
+    """初始化数据目录"""
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    BACKUP_DIR.mkdir(exist_ok=True)
+
+
+def get_data_dir() -> Path:
+    """获取数据目录路径"""
+    return DATA_DIR
+
+
+def get_db_path() -> Path:
+    """获取数据库文件路径"""
+    return DB_PATH
+
+
+def get_key_path() -> Path:
+    """获取主密钥文件路径"""
+    return KEY_PATH
+
+
+def get_backup_dir() -> Path:
+    """获取备份目录路径"""
+    return BACKUP_DIR

mini2fa/crypto.py

@@ -0,0 +1,328 @@
+"""
+加密解密模块
+
+使用 AES-256-GCM 认证加密，PBKDF2-SHA256 派生密钥
+"""
+import os
+import json
+import base64
+import binascii
+from typing import Optional
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.backends import default_backend
+
+from .config import SALT_SIZE, KEY_SIZE, ITERATIONS, NONCE_SIZE
+
+
+class CryptoManager:
+    """加密管理器"""
+
+    def __init__(self, master_key_path: str):
+        """
+        初始化加密管理器
+
+        Args:
+            master_key_path: 主密钥文件路径
+        """
+        self.master_key_path = master_key_path
+        self.key = None  # 派生密钥
+
+    def initialize(self, master_password: str, hint: str = '') -> bool:
+        """
+        初始化或加载主密钥
+
+        Args:
+            master_password: 用户主密码
+            hint: 密保提示（首次设置时使用）
+
+        Returns:
+            是否成功
+        """
+        if os.path.exists(self.master_key_path):
+            # 加载现有密钥
+            return self._load_key(master_password)
+        else:
+            # 首次使用，创建新密钥
+            return self._create_key(master_password, hint)
+
+    def _create_key(self, master_password: str, hint: str = '') -> bool:
+        """创建新的主密钥文件"""
+        salt = os.urandom(SALT_SIZE)
+
+        # 派生密钥
+        kdf = PBKDF2HMAC(
+            algorithm=hashes.SHA256(),
+            length=KEY_SIZE,
+            salt=salt,
+            iterations=ITERATIONS,
+            backend=default_backend()
+        )
+        derived_key = kdf.derive(master_password.encode('utf-8'))
+
+        # 生成主密钥（随机）
+        master_key = os.urandom(KEY_SIZE)
+
+        # 用派生密钥加密主密钥
+        aesgcm = AESGCM(derived_key)
+        nonce = os.urandom(NONCE_SIZE)
+        encrypted_master = aesgcm.encrypt(nonce, master_key, None)
+
+        # 保存到文件
+        data = {
+            'salt': base64.b64encode(salt).decode(),
+            'nonce': base64.b64encode(nonce).decode(),
+            'encrypted_key': base64.b64encode(encrypted_master).decode(),
+            'hint': hint,  # 密保提示（明文存储）
+            'version': 1
+        }
+
+        with open(self.master_key_path, 'w') as f:
+            json.dump(data, f, indent=2)
+
+        self.key = master_key
+        return True
+
+    def get_hint(self) -> str:
+        """获取密保提示"""
+        if not os.path.exists(self.master_key_path):
+            return ''
+
+        try:
+            with open(self.master_key_path, 'r') as f:
+                data = json.load(f)
+            return data.get('hint', '')
+        except Exception:
+            return ''
+
+    def get_key_data(self) -> dict:
+        """
+        读取当前主密钥文件内容（导出备份用）
+
+        Returns:
+            主密钥文件内容 dict；文件不存在或损坏时返回 None
+        """
+        if not os.path.exists(self.master_key_path):
+            return None
+
+        try:
+            with open(self.master_key_path, 'r') as f:
+                return json.load(f)
+        except Exception:
+            return None
+
+    def decrypt_with_key(self, key: bytes, ciphertext_b64: str) -> str:
+        """
+        用指定密钥解密（不改变 self.key），供跨机导入重加密使用
+
+        Args:
+            key: 解密用的密钥（如备份的主密钥）
+            ciphertext_b64: Base64 编码的密文
+
+        Returns:
+            明文
+
+        Raises:
+            ValueError: key 无效或密文损坏（base64 解码失败或 AES-GCM 认证失败）
+        """
+        try:
+            combined = base64.b64decode(ciphertext_b64)
+            nonce = combined[:NONCE_SIZE]
+            ciphertext = combined[NONCE_SIZE:]
+
+            aesgcm = AESGCM(key)
+            plaintext = aesgcm.decrypt(nonce, ciphertext, None)
+            return plaintext.decode('utf-8')
+        except Exception:
+            raise ValueError("密钥不匹配或密文已损坏")
+
+    def _load_key(self, master_password: str) -> bool:
+        """从文件加载主密钥"""
+        try:
+            with open(self.master_key_path, 'r') as f:
+                data = json.load(f)
+
+            salt = base64.b64decode(data['salt'])
+            nonce = base64.b64decode(data['nonce'])
+            encrypted_master = base64.b64decode(data['encrypted_key'])
+
+            # 派生密钥
+            kdf = PBKDF2HMAC(
+                algorithm=hashes.SHA256(),
+                length=KEY_SIZE,
+                salt=salt,
+                iterations=ITERATIONS,
+                backend=default_backend()
+            )
+            derived_key = kdf.derive(master_password.encode('utf-8'))
+
+            # 解密主密钥
+            aesgcm = AESGCM(derived_key)
+            self.key = aesgcm.decrypt(nonce, encrypted_master, None)
+            return True
+        except Exception:
+            self.key = None
+            return False
+
+    def load_external_key(self, key_data: dict, master_password: str) -> Optional[bytes]:
+        """
+        用密码验证并解出备份文件中的主密钥（不改动 self.key）
+
+        Args:
+            key_data: 备份文件中嵌入的 master_key 内容 dict
+            master_password: 备份对应的主密码
+
+        Returns:
+            解出的备份主密钥 bytes；密码错误返回 None
+
+        Raises:
+            ValueError: key_data 字段缺失或 Base64 数据损坏（不是密码问题）
+        """
+        try:
+            salt = base64.b64decode(key_data['salt'])
+            nonce = base64.b64decode(key_data['nonce'])
+            encrypted_master = base64.b64decode(key_data['encrypted_key'])
+        except (KeyError, TypeError, ValueError, binascii.Error):
+            raise ValueError("备份文件中的主密钥数据损坏，无法读取")
+
+        try:
+            kdf = PBKDF2HMAC(
+                algorithm=hashes.SHA256(),
+                length=KEY_SIZE,
+                salt=salt,
+                iterations=ITERATIONS,
+                backend=default_backend()
+            )
+            derived_key = kdf.derive(master_password.encode('utf-8'))
+
+            aesgcm = AESGCM(derived_key)
+            return aesgcm.decrypt(nonce, encrypted_master, None)
+        except Exception:
+            return None  # 密码错误
+
+    def verify_password(self, password: str) -> bool:
+        """
+        验证密码是否正确（不改变 self.key）
+
+        与 initialize 不同：验证失败不会清空当前会话 key，
+        供会话内验证旧密码等场景使用。
+        """
+        saved_key = self.key
+        result = self._load_key(password)
+        if not result:
+            self.key = saved_key  # 失败时恢复，不污染会话
+        return result
+
+    def change_password(self, old_password: str, new_password: str, hint: str = '') -> bool:
+        """
+        修改主密码：验证旧密码 → 用新密码重新加密 master_key
+
+        数据库中的 secret_encrypted 不受影响（master_key 不变），
+        修改后旧密码立即失效（新 salt + 新 nonce）。
+
+        Args:
+            old_password: 当前主密码
+            new_password: 新主密码
+            hint: 新密保提示（传 '' 会清空，调用方负责保留原 hint）
+
+        Returns:
+            是否成功（旧密码错误返回 False）
+        """
+        # 1. 验证旧密码（解出当前 master_key；失败不污染会话 key）
+        if not self.verify_password(old_password):
+            return False
+        master_key = self.key
+
+        # 2. 用新密码派生新 KEK，重新加密 master_key
+        salt = os.urandom(SALT_SIZE)
+        kdf = PBKDF2HMAC(
+            algorithm=hashes.SHA256(),
+            length=KEY_SIZE,
+            salt=salt,
+            iterations=ITERATIONS,
+            backend=default_backend()
+        )
+        derived_key = kdf.derive(new_password.encode('utf-8'))
+
+        aesgcm = AESGCM(derived_key)
+        nonce = os.urandom(NONCE_SIZE)
+        encrypted_master = aesgcm.encrypt(nonce, master_key, None)
+
+        # 3. 写回 master.key
+        data = {
+            'salt': base64.b64encode(salt).decode(),
+            'nonce': base64.b64encode(nonce).decode(),
+            'encrypted_key': base64.b64encode(encrypted_master).decode(),
+            'hint': hint,
+            'version': 1
+        }
+        with open(self.master_key_path, 'w') as f:
+            json.dump(data, f, indent=2)
+
+        # 4. self.key 保持 master_key，会话内继续可用
+        return True
+
+    def adopt_external_key(self, external_key: bytes, key_data: dict) -> None:
+        """
+        跨机导入（空库）：用备份主密钥替换本机主密钥
+
+        写回本机 master.key 文件并更新内存中的 self.key，
+        此后本机使用备份对应的主密码登录。
+
+        Args:
+            external_key: 备份主密钥（已由 load_external_key 解出）
+            key_data: 备份内嵌的 master_key 内容 dict
+        """
+        with open(self.master_key_path, 'w') as f:
+            json.dump(key_data, f, indent=2)
+        self.key = external_key
+
+    def encrypt(self, plaintext: str) -> str:
+        """
+        加密字符串
+
+        Args:
+            plaintext: 明文
+
+        Returns:
+            Base64 编码的密文（含 nonce）
+        """
+        if not self.key:
+            raise RuntimeError("未初始化密钥")
+
+        aesgcm = AESGCM(self.key)
+        nonce = os.urandom(NONCE_SIZE)
+        ciphertext = aesgcm.encrypt(nonce, plaintext.encode('utf-8'), None)
+
+        # 合并 nonce 和密文
+        combined = nonce + ciphertext
+        return base64.b64encode(combined).decode()
+
+    def decrypt(self, ciphertext_b64: str) -> str:
+        """
+        解密字符串
+
+        Args:
+            ciphertext_b64: Base64 编码的密文
+
+        Returns:
+            明文
+
+        Raises:
+            RuntimeError: 未初始化密钥
+            ValueError: base64 解码失败或 AES-GCM 认证失败（密文损坏/密钥不匹配）
+        """
+        if not self.key:
+            raise RuntimeError("未初始化密钥")
+
+        try:
+            combined = base64.b64decode(ciphertext_b64)
+            nonce = combined[:NONCE_SIZE]
+            ciphertext = combined[NONCE_SIZE:]
+
+            aesgcm = AESGCM(self.key)
+            plaintext = aesgcm.decrypt(nonce, ciphertext, None)
+            return plaintext.decode('utf-8')
+        except Exception:
+            raise ValueError("密文已损坏或密钥不匹配")

mini2fa/models.py

@@ -0,0 +1,33 @@
+"""
+数据模型定义
+"""
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class Account:
+    """账号数据模型"""
+    id: int
+    issuer: str           # 服务提供商（如 Google、GitHub）
+    account: str          # 账号名（如 user@example.com）
+    secret_encrypted: str # 加密后的密钥
+    algorithm: str        # 算法：SHA1/SHA256/SHA512
+    digits: int           # 验证码位数
+    period: int           # 时间步长（秒）
+    category: str         # 分类
+    notes: str            # 备注
+    created_at: str       # 创建时间
+    updated_at: str       # 更新时间
+
+
+@dataclass
+class OTPAccountInfo:
+    """从二维码解析出的 OTP 账号信息"""
+    issuer: str           # 服务提供商
+    account: str          # 账号名
+    secret: str           # 明文密钥（Base32）
+    algorithm: str        # 哈希算法
+    digits: int           # 验证码位数
+    period: int           # 时间步长
+    otp_type: str         # OTP 类型：totp 或 hotp

mini2fa/scanner.py

@@ -0,0 +1,189 @@
+"""
+二维码扫描模块
+
+从图片文件中识别二维码并解析 OTP URI
+"""
+import os
+from typing import Optional
+from urllib.parse import urlparse, parse_qs
+
+from pyzbar.pyzbar import decode
+from PIL import Image, ImageEnhance
+
+from .models import OTPAccountInfo
+from .config import DEFAULT_ALGORITHM, DEFAULT_DIGITS, DEFAULT_PERIOD
+
+
+class UnsupportedOTPTypeError(Exception):
+    """OTP URI 类型不是 TOTP 时抛出（如 HOTP、STEAM 等）"""
+
+    def __init__(self, otp_type: str):
+        self.otp_type = otp_type
+        super().__init__(f"不支持的 OTP 类型: {otp_type}")
+
+
+def preprocess_image(image: Image.Image) -> Image.Image:
+    """
+    图片预处理，提高识别率
+
+    1. 转换为灰度图
+    2. 调整对比度
+    3. 缩放到合理尺寸（如果太大）
+
+    Args:
+        image: 原始图片
+
+    Returns:
+        预处理后的图片
+    """
+    # 转灰度
+    gray = image.convert('L')
+
+    # 增强对比度
+    enhancer = ImageEnhance.Contrast(gray)
+    enhanced = enhancer.enhance(2.0)
+
+    # 缩放（如果宽度超过1024）
+    if enhanced.width > 1024:
+        ratio = 1024 / enhanced.width
+        new_size = (1024, int(enhanced.height * ratio))
+        enhanced = enhanced.resize(new_size, Image.Resampling.LANCZOS)
+
+    return enhanced
+
+
+def parse_otp_uri(uri: str) -> Optional[OTPAccountInfo]:
+    """
+    解析 otpauth:// URI
+
+    Args:
+        uri: OTP URI 字符串
+
+    Returns:
+        OTPAccountInfo 对象，或 None（格式无效）
+
+    Raises:
+        UnsupportedOTPTypeError: URI 类型不是 totp（如 hotp、steam 等）
+
+    URI 格式示例:
+        otpauth://totp/Example:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example&algorithm=SHA1&digits=6&period=30
+    """
+    # 验证 URI 格式
+    if not uri.startswith('otpauth://'):
+        return None
+
+    try:
+        parsed = urlparse(uri)
+        params = parse_qs(parsed.query)
+
+        # 校验必要参数
+        if 'secret' not in params:
+            return None
+
+        # 校验 OTP 类型（仅支持 totp）
+        otp_type = parsed.netloc
+        if otp_type != 'totp':
+            raise UnsupportedOTPTypeError(otp_type)
+
+        # 提取标签（issuer:account 格式）
+        label = parsed.path.lstrip('/')
+        if ':' in label:
+            default_issuer, account = label.split(':', 1)
+        else:
+            default_issuer = ''
+            account = label
+
+        issuer = params.get('issuer', [default_issuer])[0] or default_issuer
+
+        return OTPAccountInfo(
+            issuer=issuer,
+            account=account,
+            secret=params['secret'][0],
+            algorithm=params.get('algorithm', [DEFAULT_ALGORITHM])[0],
+            digits=int(params.get('digits', [DEFAULT_DIGITS])[0]),
+            period=int(params.get('period', [DEFAULT_PERIOD])[0]),
+            otp_type=otp_type  # 仅 'totp'
+        )
+    except UnsupportedOTPTypeError:
+        raise  # 类型错误穿透，由调用方给出明确提示
+    except Exception:
+        return None
+
+
+def _extract_otp_info(decoded_objects) -> Optional[OTPAccountInfo]:
+    """从 pyzbar 解码结果中提取第一个可解析的 OTP URI 信息
+
+    若图片含多个二维码：优先返回 totp 类型；存在非 totp 类型时
+    记下第一个遇到的类型，全部非 totp 才抛出。
+    """
+    first_unsupported = None
+    for obj in decoded_objects:
+        data = obj.data.decode('utf-8')
+        if not data.startswith('otpauth://'):
+            continue
+        try:
+            return parse_otp_uri(data)
+        except UnsupportedOTPTypeError as e:
+            if first_unsupported is None:
+                first_unsupported = e.otp_type
+    if first_unsupported is not None:
+        raise UnsupportedOTPTypeError(first_unsupported)
+    return None
+
+
+def scan_qrcode(image_path: str) -> Optional[OTPAccountInfo]:
+    """
+    从图片文件中扫描二维码并解析 OTP URI
+
+    Args:
+        image_path: 图片文件路径
+
+    Returns:
+        OTPAccountInfo 对象，或 None（识别失败）
+
+    Raises:
+        FileNotFoundError: 文件不存在
+        UnsupportedOTPTypeError: 二维码是 HOTP 等非 TOTP 类型
+    """
+    if not os.path.exists(image_path):
+        raise FileNotFoundError(f"图片文件不存在: {image_path}")
+
+    try:
+        image = Image.open(image_path)
+
+        # 尝试直接识别
+        decoded_objects = decode(image)
+
+        # 如果直接识别失败，尝试预处理后识别
+        if not decoded_objects:
+            processed = preprocess_image(image)
+            decoded_objects = decode(processed)
+
+        return _extract_otp_info(decoded_objects)
+
+    except UnsupportedOTPTypeError:
+        raise
+    except Exception as e:
+        raise ValueError(f"扫描失败: {e}")
+
+
+def scan_qrcode_from_raw_data(data: bytes) -> Optional[OTPAccountInfo]:
+    """
+    从原始数据中解析二维码
+
+    Args:
+        data: 原始字节数据
+
+    Returns:
+        OTPAccountInfo 对象，或 None
+
+    Raises:
+        UnsupportedOTPTypeError: 数据是 HOTP 等非 TOTP 类型
+    """
+    try:
+        decoded_objects = decode(data)
+        return _extract_otp_info(decoded_objects)
+    except UnsupportedOTPTypeError:
+        raise
+    except Exception:
+        return None