sdpy-kit 0.4.2__tar.gz → 0.4.3__tar.gz

{sdpy_kit-0.4.2 → sdpy_kit-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.4.2
+Version: 0.4.3
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT

{sdpy_kit-0.4.2 → sdpy_kit-0.4.3}/kit/__init__.py

@@ -23,7 +23,7 @@ Author: Clark Chang
 数据库访问通过 kit.db 子包提供（基于 SQLModel）。
 """
 
-__version__ = "0.4.2"
+__version__ = "0.4.3"
 
 from kit.db import (
     MYSQL,

{sdpy_kit-0.4.2 → sdpy_kit-0.4.3}/kit/license_kit.py

@@ -23,9 +23,9 @@ Author: Clark Chang
 面向单机分发场景的轻量授权体系（防君子定位）：应用以打包 exe 形式离线分发，
 无远端授权服务。工作流：
 
-1. 客户机 `export_fingerprint_file()` 导出 `.fp` 指纹文件；
-2. 签发方 `parse_fingerprint_file()` 解析，填入 `LicensePayload` 后
-   `sign()` 生成 `.lic` 授权文件回签；
+1. 客户机 `LicenseKit.export_fingerprint_file()` 导出 `.fp` 指纹文件；
+2. 签发方 `LicenseKit.parse_fingerprint_file()` 解析，填入 `LicensePayload`
+   后 `LicenseKit.sign()` 生成 `.lic` 授权文件回签；
 3. 客户机 `LicenseVerifier.verify()` 验签 + 绑定校验（product / 机器码 / 有效期）。
 
 安全边界（务必知悉）：
@@ -41,19 +41,20 @@ Author: Clark Chang
 规范化 JSON 序列化后签名，杜绝字段顺序 / 空白差异导致验签漂移。
 
 用法：
-    from kit.license_kit import (
-        LicensePayload, LicenseVerifier, export_fingerprint_file,
-        generate_keypair, parse_fingerprint_file, sign,
-    )
+    from kit.license_kit import LicenseKit, LicensePayload, LicenseVerifier
 
-    private_pem, public_pem = generate_keypair()
+    private_pem, public_pem = LicenseKit.generate_keypair()
     payload = LicensePayload(product="myapp", machine_code="0123456789abcdef",
                              issued_at=datetime.now(timezone.utc),
                              expires_at=None)
-    lic_text = sign(payload, private_pem)
+    lic_text = LicenseKit.sign(payload, private_pem)
 
     verifier = LicenseVerifier(public_pem, Path("license.lic"))
     info = verifier.verify(product="myapp", machine_code="0123456789abcdef")
+
+形态说明：0.4.2 为模块级函数，0.4.3 起收进静态工具类 `LicenseKit`
+（与 FileKit / LayaKit 等其它 kit 形态一致）；`LicenseVerifier` 因持有
+公钥缓存与验签上下文实例状态，保持独立类。
 """
 
 import base64
@@ -125,7 +126,7 @@ class LicenseExpiredError(LicenseError):
 
 
 # ---------------------------------------------------------------------------
-# 机器指纹（Windows 专属；winreg/ctypes 延迟导入保证模块可在任意平台 import）
+# 机器指纹私有实现（Windows 专属；winreg/ctypes 延迟导入保证模块任意平台可 import）
 # ---------------------------------------------------------------------------
 
 
@@ -175,118 +176,14 @@ def _collect_components() -> tuple[str, str]:
     return _read_machine_guid(), _read_volume_serial()
 
 
-def get_machine_code() -> str:
-    """计算本机机器码：组合指纹 SHA256 短码（16 hex 小写）
-
-    Returns:
-        str: 16 位十六进制机器码
-
-    Raises:
-        LicenseUnsupportedPlatformError: 非 Windows 平台
-        LicenseFormatError: 指纹组件读取失败
-    """
-    machine_guid, volume_serial = _collect_components()
+def _machine_code_of(machine_guid: str, volume_serial: str) -> str:
+    """由原始组件计算机器码短码（签发与导出共用，避免两处公式漂移）"""
     digest = hashlib.sha256(f"{machine_guid}|{volume_serial}".encode("utf-8"))
     return digest.hexdigest()[:MACHINE_CODE_LENGTH]
 
 
-def export_fingerprint_file(path: Path) -> Path:
-    """导出指纹文件（.fp）：机器码 + 原始组件 + 导出时间
-
-    原始组件仅用于报障诊断（作者侧可看出哪个组件不匹配），验签只比短码。
-
-    Args:
-        path: 指纹文件输出路径
-
-    Returns:
-        Path: 实际写入的文件路径
-
-    Raises:
-        LicenseUnsupportedPlatformError: 非 Windows 平台
-        LicenseFormatError: 指纹组件读取失败
-    """
-    machine_guid, volume_serial = _collect_components()
-    machine_code = hashlib.sha256(
-        f"{machine_guid}|{volume_serial}".encode("utf-8")
-    ).hexdigest()[:MACHINE_CODE_LENGTH]
-    document = {
-        "kind": _FINGERPRINT_KIND,
-        "format_version": FINGERPRINT_FORMAT_VERSION,
-        "machine_code": machine_code,
-        "components": {
-            "machine_guid": machine_guid,
-            "volume_serial": volume_serial,
-        },
-        "exported_at": datetime.now(timezone.utc).isoformat(),
-    }
-    target = Path(path)
-    target.parent.mkdir(parents=True, exist_ok=True)
-    target.write_text(
-        json.dumps(document, ensure_ascii=False, indent=2), encoding="utf-8"
-    )
-    logger.info("指纹文件已导出：%s（机器码 %s）", target, machine_code)
-    return target
-
-
-def parse_fingerprint_file(path: Path) -> str:
-    """解析指纹文件，返回机器码（签发侧使用；跨机器无法重算原文，只校验结构）
-
-    Args:
-        path: 指纹文件路径
-
-    Returns:
-        str: 16 位十六进制机器码
-
-    Raises:
-        LicenseFormatError: 文件缺失 / JSON 损坏 / 标识或版本不符 / 机器码格式非法
-    """
-    source = Path(path)
-    if not source.is_file():
-        raise LicenseFormatError(f"指纹文件不存在：{source}")
-    try:
-        document = json.loads(source.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
-        raise LicenseFormatError(f"指纹文件读取或解析失败：{exc}") from exc
-    if not isinstance(document, dict):
-        raise LicenseFormatError("指纹文件结构不合法（顶层应为 JSON 对象）")
-    if document.get("kind") != _FINGERPRINT_KIND:
-        raise LicenseFormatError("指纹文件标识不符（kind）")
-    version = document.get("format_version")
-    if not isinstance(version, int) or version > FINGERPRINT_FORMAT_VERSION:
-        raise LicenseFormatError(f"指纹文件格式版本不识别：{version!r}")
-    machine_code = document.get("machine_code")
-    if not isinstance(machine_code, str) or not _HEX16_RE.fullmatch(machine_code):
-        raise LicenseFormatError("指纹文件缺少合法机器码（16 hex）")
-    return machine_code
-
-
-# ---------------------------------------------------------------------------
-# 密钥
-# ---------------------------------------------------------------------------
-
-
-def generate_keypair() -> tuple[str, str]:
-    """生成 Ed25519 密钥对（一次性初始化用）
-
-    Returns:
-        tuple[str, str]: (private_pem, public_pem)，均为 PEM 文本；
-            私钥务必本机妥善保管（丢失 = 已发授权全部作废）
-    """
-    private_key = Ed25519PrivateKey.generate()
-    private_pem = private_key.private_bytes(
-        encoding=serialization.Encoding.PEM,
-        format=serialization.PrivateFormat.PKCS8,
-        encryption_algorithm=serialization.NoEncryption(),
-    ).decode("utf-8")
-    public_pem = private_key.public_key().public_bytes(
-        encoding=serialization.Encoding.PEM,
-        format=serialization.PublicFormat.SubjectPublicKeyInfo,
-    ).decode("utf-8")
-    return private_pem, public_pem
-
-
 # ---------------------------------------------------------------------------
-# 载荷与签名（格式唯一事实源——签发与验签共用本模块实现）
+# 载荷（签发与验签共用）
 # ---------------------------------------------------------------------------
 
 
@@ -340,39 +237,149 @@ def _canonical_bytes(payload: dict) -> bytes:
     ).encode("utf-8")
 
 
-def sign(payload: LicensePayload, private_key_pem: str) -> str:
-    """对载荷签名，返回 license 文件内容（JSON 文本，即 .lic）
+# ---------------------------------------------------------------------------
+# 静态工具类（与其它 kit 形态一致；格式唯一事实源——签发与验签共用本模块实现）
+# ---------------------------------------------------------------------------
 
-    Args:
-        payload: 授权载荷
-        private_key_pem: Ed25519 私钥 PEM（PKCS8）
 
-    Returns:
-        str: license 文件内容 `{"payload": {...}, "signature": "<b64>"}`
+class LicenseKit:
+    """license 授权静态工具类：指纹、密钥、签发"""
 
-    Raises:
-        LicenseFormatError: 私钥解析失败或类型不是 Ed25519
-    """
-    try:
-        private_key = serialization.load_pem_private_key(
-            private_key_pem.encode("utf-8"), password=None
+    @staticmethod
+    def get_machine_code() -> str:
+        """计算本机机器码：组合指纹 SHA256 短码（16 hex 小写）
+
+        Returns:
+            str: 16 位十六进制机器码
+
+        Raises:
+            LicenseUnsupportedPlatformError: 非 Windows 平台
+            LicenseFormatError: 指纹组件读取失败
+        """
+        machine_guid, volume_serial = _collect_components()
+        return _machine_code_of(machine_guid, volume_serial)
+
+    @staticmethod
+    def export_fingerprint_file(path: Path) -> Path:
+        """导出指纹文件（.fp）：机器码 + 原始组件 + 导出时间
+
+        原始组件仅用于报障诊断（作者侧可看出哪个组件不匹配），验签只比短码。
+
+        Args:
+            path: 指纹文件输出路径
+
+        Returns:
+            Path: 实际写入的文件路径
+
+        Raises:
+            LicenseUnsupportedPlatformError: 非 Windows 平台
+            LicenseFormatError: 指纹组件读取失败
+        """
+        machine_guid, volume_serial = _collect_components()
+        document = {
+            "kind": _FINGERPRINT_KIND,
+            "format_version": FINGERPRINT_FORMAT_VERSION,
+            "machine_code": _machine_code_of(machine_guid, volume_serial),
+            "components": {
+                "machine_guid": machine_guid,
+                "volume_serial": volume_serial,
+            },
+            "exported_at": datetime.now(timezone.utc).isoformat(),
+        }
+        target = Path(path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(
+            json.dumps(document, ensure_ascii=False, indent=2), encoding="utf-8"
         )
-    except (ValueError, TypeError) as exc:
-        raise LicenseFormatError(f"私钥 PEM 解析失败：{exc}") from exc
-    if not isinstance(private_key, Ed25519PrivateKey):
-        raise LicenseFormatError("私钥类型不是 Ed25519")
-    payload_dict = payload.model_dump(mode="json")
-    signature = private_key.sign(_canonical_bytes(payload_dict))
-    document = {
-        "payload": payload_dict,
-        "signature": base64.b64encode(signature).decode("ascii"),
-    }
-    logger.info(
-        "license 已签发：product=%s machine_code=%s",
-        payload.product,
-        payload.machine_code,
-    )
-    return json.dumps(document, ensure_ascii=False, indent=2)
+        logger.info("指纹文件已导出：%s（机器码 %s）", target, document["machine_code"])
+        return target
+
+    @staticmethod
+    def parse_fingerprint_file(path: Path) -> str:
+        """解析指纹文件，返回机器码（签发侧使用；跨机器无法重算原文，只校验结构）
+
+        Args:
+            path: 指纹文件路径
+
+        Returns:
+            str: 16 位十六进制机器码
+
+        Raises:
+            LicenseFormatError: 文件缺失 / JSON 损坏 / 标识或版本不符 / 机器码格式非法
+        """
+        source = Path(path)
+        if not source.is_file():
+            raise LicenseFormatError(f"指纹文件不存在：{source}")
+        try:
+            document = json.loads(source.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise LicenseFormatError(f"指纹文件读取或解析失败：{exc}") from exc
+        if not isinstance(document, dict):
+            raise LicenseFormatError("指纹文件结构不合法（顶层应为 JSON 对象）")
+        if document.get("kind") != _FINGERPRINT_KIND:
+            raise LicenseFormatError("指纹文件标识不符（kind）")
+        version = document.get("format_version")
+        if not isinstance(version, int) or version > FINGERPRINT_FORMAT_VERSION:
+            raise LicenseFormatError(f"指纹文件格式版本不识别：{version!r}")
+        machine_code = document.get("machine_code")
+        if not isinstance(machine_code, str) or not _HEX16_RE.fullmatch(machine_code):
+            raise LicenseFormatError("指纹文件缺少合法机器码（16 hex）")
+        return machine_code
+
+    @staticmethod
+    def generate_keypair() -> tuple[str, str]:
+        """生成 Ed25519 密钥对（一次性初始化用）
+
+        Returns:
+            tuple[str, str]: (private_pem, public_pem)，均为 PEM 文本；
+                私钥务必本机妥善保管（丢失 = 已发授权全部作废）
+        """
+        private_key = Ed25519PrivateKey.generate()
+        private_pem = private_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.NoEncryption(),
+        ).decode("utf-8")
+        public_pem = private_key.public_key().public_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PublicFormat.SubjectPublicKeyInfo,
+        ).decode("utf-8")
+        return private_pem, public_pem
+
+    @staticmethod
+    def sign(payload: LicensePayload, private_key_pem: str) -> str:
+        """对载荷签名，返回 license 文件内容（JSON 文本，即 .lic）
+
+        Args:
+            payload: 授权载荷
+            private_key_pem: Ed25519 私钥 PEM（PKCS8）
+
+        Returns:
+            str: license 文件内容 `{"payload": {...}, "signature": "<b64>"}`
+
+        Raises:
+            LicenseFormatError: 私钥解析失败或类型不是 Ed25519
+        """
+        try:
+            private_key = serialization.load_pem_private_key(
+                private_key_pem.encode("utf-8"), password=None
+            )
+        except (ValueError, TypeError) as exc:
+            raise LicenseFormatError(f"私钥 PEM 解析失败：{exc}") from exc
+        if not isinstance(private_key, Ed25519PrivateKey):
+            raise LicenseFormatError("私钥类型不是 Ed25519")
+        payload_dict = payload.model_dump(mode="json")
+        signature = private_key.sign(_canonical_bytes(payload_dict))
+        document = {
+            "payload": payload_dict,
+            "signature": base64.b64encode(signature).decode("ascii"),
+        }
+        logger.info(
+            "license 已签发：product=%s machine_code=%s",
+            payload.product,
+            payload.machine_code,
+        )
+        return json.dumps(document, ensure_ascii=False, indent=2)
 
 
 # ---------------------------------------------------------------------------
@@ -445,7 +452,7 @@ class LicenseVerifier:
 
         Args:
             product: 期望的应用标识
-            machine_code: 期望的机器码（本机 `get_machine_code()` 结果）
+            machine_code: 期望的机器码（本机 `LicenseKit.get_machine_code()` 结果）
             now: 判定"当前时间"；None 取 aware UTC 当前时刻；naive 按 UTC 处理
 
         Returns: