Metadata-Version: 2.4
Name: kami-armor
Version: 0.1.0
Summary: 卡密 license-system client SDK + server-bound Python source protection (encrypt / obfuscate / Cython / one-command packaging)
Author: yuge666
License: MIT
Project-URL: Homepage, https://pypi.org/project/kami-armor/
Keywords: license,卡密,drm,obfuscation,source-protection,pyarmor-alternative,cython,activation
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=41.0
Requires-Dist: py-machineid>=0.6
Provides-Extra: harden
Requires-Dist: cython>=3.0; extra == "harden"
Requires-Dist: pyinstaller>=6.0; extra == "harden"
Requires-Dist: tomli; python_version < "3.11" and extra == "harden"
Dynamic: license-file

# kami-armor

**卡密（license）系统的 Python 客户端 SDK + 服务端绑定密钥的源码保护工具链。**

- 🔑 **客户端 SDK**（`kami_client`）：在线激活 / 校验 / 心跳 / 解绑、价值闸门调用、按授权解锁加密资源、完整性自测量——只内嵌**公钥**，离线验签，永远拿不到可伪造卡密的私钥。
- 🛡 **源码保护**（`kami_armor`）：把 Python 模块加密成密文随程序分发，**发布物里没有密钥**，运行时经服务器按授权下发密钥、内存解密导入。比 PyArmor 强在一个结构性维度——**密钥托管**（PyArmor 的密钥静态内嵌、可离线脱壳；这里密钥根本不在文件里，可吊销/溯源）。
- 🧩 **混淆 + 原生编译 + 一键打包**：自建免费的改名/字符串加密（symtable 保证不改坏代码）、Cython 原生编译皇冠模块、`kami-armor harden` 一条命令 混淆→Cython→加密→PyInstaller/Nuitka 出 exe。

> ⚠️ 这是**客户端库**，需要配合一个 **kami 授权服务器**（你自建/自部署的单文件 Go 服务）才能工作。SDK 只负责和你的服务器对话。

## 安装

```bash
pip install kami-armor
# 需要"一键打包/Cython"功能时（构建期工具）：
pip install "kami-armor[harden]"
```

## 客户端 SDK 快速上手

```python
from kami_client import KamiClient, LicenseError

client = KamiClient("https://license.example.com", "你的产品代号", "<服务器公钥HEX>")
try:
    lic = client.validate()              # 先用缓存/在线校验
except LicenseError:
    lic = client.activate(user_code)     # 首次激活（卡密）

if lic.has_feature("premium"):
    out, quota = client.gated("premium", {"k": "v"}, cost=1)   # 价值在服务端执行
    key = client.unlock("model")                               # 按授权拿密钥
    data = client.decrypt_resource(sealed_bytes, key)          # 仅内存解密
    client.attest("build-1")                                   # 可选：完整性证明

# 可选：后台心跳（实时在线 + 即时感知吊销/踢下线）
stop = client.start_heartbeat  # 见文档
```

## 源码保护（kami_armor）

```python
import kami_armor
# 构建期：加密模块 + 注册密钥（密钥不进发布物）
kami_armor.build([{"src": "core/algo.py", "module": "core.algo",
                   "resource": "algo_v1", "feature": "premium", "keep": ["compute"]}],
                 admin_url="https://license.example.com", token="<后台JWT>")
```
```python
# 运行期：装上加密导入
from kami_client import KamiClient
import kami_armor
client = KamiClient(url, product, pubkey); client.validate()
kami_armor.install(client, "dist_protected/manifest.json")
import core.algo            # ← 经服务器按授权解密后才能导入
```

命令行：

```bash
# 只做混淆（改名+字符串加密，供 Cython/Nuitka 用）
python -m kami_armor obfuscate core/algo.py -o core/algo_obf.py --keep run
# 一键：混淆→Cython→加密→打包出 exe
python -m kami_armor harden --config kami-harden.toml
```

## 诚实定位

客户端的混淆/加密只能**抬高破解成本**，不是绝对保密——解密后的代码运行时仍可能被持有效授权的攻击者内存 dump（CPython 的硬限制，所有方案都一样）。真正耐久的保护是：**把价值与密钥留在服务端**（价值闸门 + 按授权发密钥），并用**比 crack 传播更快的吊销与更新**让破解迅速过期。本库正是围绕这一原则设计。

## License

MIT © yuge666
