优化数据表结构

pkg/password/pwd.py

@@ -1,55 +1,79 @@
 import secrets
+from loguru import logger
 from argon2 import PasswordHasher
+from argon2.exceptions import VerifyMismatchError
+from enum import StrEnum
+
+_ph = PasswordHasher()
+
+class PasswordStatus(StrEnum):
+    """密码校验状态枚举"""
+
+    VALID = "valid"
+    """密码校验通过"""
+
+    INVALID = "invalid"
+    """密码校验失败"""
+
+    EXPIRED = "expired"
+    """密码哈希已过时，建议重新哈希"""
 
 class Password:
-    
+    """密码处理工具类，包含密码生成、哈希和验证功能"""
+
     @staticmethod
     def generate(
-        length: int = 16,
-        url_safe: bool = False
-        ) -> str:
-        """
-        生成一个随机密码。
-        
-        :param length: 密码长度，默认为 `16` 个字符。
-        :param url_safe: 是否生成URL安全的密码，默认为 `False` 。
-        :return: 生成的随机密码字符串。
-        """
-        if url_safe:
-            return secrets.token_urlsafe(length)
-        return secrets.token_hex(length)
-    
-    @staticmethod
-    def hash(
-        password: str,
+            length: int = 8
     ) -> str:
         """
-        生成密码的Argon2哈希值。
-        
-        :param password: 要哈希的密码。
-        :return: 使用Argon2算法生成的密码哈希。
+        生成指定长度的随机密码。
+
+        :param length: 密码长度
+        :type length: int
+        :return: 随机密码
         :rtype: str
         """
-        ph = PasswordHasher()
-        return ph.hash(password)
-    
+        return secrets.token_hex(length)
+
+    @staticmethod
+    def hash(
+            password: str
+    ) -> str:
+        """
+        使用 Argon2 生成密码的哈希值。
+
+        返回的哈希字符串已经包含了所有需要验证的信息（盐、算法参数等）。
+
+        :param password: 需要哈希的原始密码
+        :return: Argon2 哈希字符串
+        """
+        return _ph.hash(password)
+
     @staticmethod
     def verify(
-        stored_password: str, 
-        provided_password: str, 
-    ) -> bool:
+            hash: str,
+            password: str
+    ) -> PasswordStatus:
         """
-        验证存储的Argon2密码哈希值与用户提供的密码是否匹配。
-        
-        :param stored_password: 存储的Argon2密码哈希值。
-        :param provided_password: 用户提供的密码。
-        
-        :return: 如果密码匹配返回 `True` ,否则返回 `False` 。
-        :rtype: bool
+        验证存储的 Argon2 哈希值与用户提供的密码是否匹配。
+
+        :param hash: 数据库中存储的 Argon2 哈希字符串
+        :param password: 用户本次提供的密码
+        :return: 如果密码匹配返回 True, 否则返回 False
         """
-        ph = PasswordHasher()
         try:
-            ph.verify(stored_password, provided_password)
-            return True
-        except:
-            return False
+            # verify 函数会自动解析 stored_password 中的盐和参数
+            _ph.verify(hash, password)
+
+            # 检查哈希参数是否已过时。如果返回True，
+            # 意味着你应该使用新的参数重新哈希密码并更新存储。
+            # 这是一个很好的实践，可以随着时间推移增强安全性。
+            if _ph.check_needs_rehash(hash):
+                logger.warning("密码哈希参数已过时，建议重新哈希并更新。")
+                return PasswordStatus.EXPIRED
+
+            return PasswordStatus.VALID
+        except VerifyMismatchError:
+            # 这是预期的异常，当密码不匹配时触发。
+            return PasswordStatus.INVALID
+        # 其他异常（如哈希格式错误）应该传播，让调用方感知系统问题