Metadata-Version: 2.1
Name: cryptolith
Version: 0.1.12
Summary: Advanced Python source code obfuscator and compiler protection.
Author-email: Massimo <massimo@example.com>
License: MIT
Project-URL: Homepage, https://github.com/Pietracoops/cryptolith
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyinstaller
Requires-Dist: click
Requires-Dist: astunparse
Requires-Dist: cryptography

# Cryptolith: High-Performance Python Compiler & Military-Grade Protection 🛡️🚀

**The Fastest Python Compiler that also makes your code impossible to reverse engineer.**

Cryptolith is the high-performance alternative to Nuitka and PyArmor. While others focus only on hiding code, Cryptolith focuses on **Speed** and **Defense-in-Depth**.

## 🏎️ Why Cryptolith?

- **Fastest Execution**: Native C compilation + **GIL-Unlock (Turbo mode)** allows Python to run up to **25x faster** than CPython by bypassing the Global Interpreter Lock.
- **Strongest Protection**: Polymorphic VM virtualization + Control Flow Flattening (CFF) defeats standard decompilers (pycdc, uncompyle6) and professional reverse engineers.
- **Zero Configuration**: One-click protected builds for complex libraries like `numpy`, `pandas`, and `tensorflow`.

---

## 🏎️ Benchmark Results (Head-to-Head)

*Workload: Multi-threaded CPU-bound mathematical loop (4 threads, 20M iterations total)*

| Engine | Execution Time | Binary Size | Protection |
| :--- | :---: | :---: | :--- |
| Python (Raw) | 4.59s | < 1 KB | None |
| Nuitka (Standalone) | 2.69s | 18.3 MB | Native |
| PyArmor (Standard) | 7.74s | 0.6 MB | Bytecode |
| **Cryptolith (Turbo)** | **0.18s** | **11.5 MB** | **Military Grade** |

Unlike Nuitka or PyArmor, which are still bound by the **Global Interpreter Lock (GIL)**, Cryptolith's **Turbo Mode** identifies performance-critical kernels and compiles them to native C with explicit **GIL release**, achieving a **25.5x speedup** on modern architecture.

- **True Parallelism**: While Nuitka threads fight for a single core, Cryptolith utilizes all available CPU cores simultaneously.
- **Micro-Optimization**: Our BCC compiler performs aggressive loop unrolling and SIMD-friendly math transpilation that exceeds standard CPython efficiency.

### 🛡️ Active Defense: Beyond Obfuscation

Standard tools offer *Passive Protection* (hiding code). Cryptolith offers **Active Defense** (detecting and misdirecting attackers).

- **Silent Corruption**: If a debugger or unauthorized environment is detected, Cryptolith doesn't just crash. It enters a "Hostile State" where VM calculations are subtly corrupted. Attackers waste weeks debugging "ghost bugs" while the actual logic remains safe.
- **Polymorphic Opcode Mapping**: Every single build of your project uses a unique, randomized instruction set. Dissecting one binary provides zero help in dissecting the next.

---

## 💎 Feature Matrix

| Feature | PyArmor | Nuitka | **Cryptolith** |
| :--- | :---: | :---: | :---: |
| **Bytecode Hiding** | Strong (VM) | Strong (Native) | **Strongest (Native + VM)** |
| **Logic Obfuscation** | Yes (CFF) | Weak/None | **Yes (Polymorphic CFF)** |
| **Performance** | Slower (Overhead) | Faster (Native) | **25x Faster (Turbo/No-GIL)** |
| **Competitive Advantage**| Security only | Compilation only | **Ultimate IP Performance** |

---

## 💠 Tiered Licensing Model

Cryptolith follows an **Open Core** strategy. We believe free users are our best evangelists.

### [Community Edition] (Free Forever)
**No watermarks.** Build professional, protected tools for small projects and open-source use.
- ✅ **Native Compilation**: Compiles Python to standalone machine code (Assembly).
- ✅ **Symbol Renaming**: Deep recursive renaming of functions, classes, and variables.
- ✅ **Full Scoping**: Fine-grained project control with `--include` and `--exclude`.
- ✅ **One-Click Bundling**: Produces clean, professional standalone binaries.

### [Pro Edition] (Professional)
The ultimate performance and security suite for enterprise-grade IP.
- 🚀 **Turbo Mode (GIL Unlock)**: Release the Global Interpreter Lock for true multi-threaded parallel performance.
- ⚛️ **Polymorphic VM**: Randomized instruction sets per build—unique signature every time.
- 🔐 **Control Flow Flattening (CFF)**: Logic spaghetti injection to defeat symbolic execution and human analysis.
- 💎 **String & Constant Encryption**: Automated encryption with stack-only decryption.
- 🛡️ **Hardware Binding**: Lock binaries to specific MAC, IP, or HWID.
- 📦 **Asset VFS**: Securely bundle AI models and data files with zero-footprint memory loading.

### 🔑 For Administrators: Generating Licenses
To generate a license for a customer, use the included helper script:

1.  **Generate Keys** (One-time):
    ```bash
    python scripts/admin_keygen.py generate-keys
    ```
2.  **Issue License**:
    ```bash
    python scripts/admin_keygen.py create-license --user "Customer Name" --tier "Pro" --private-key "YOUR_PRIVATE_KEY"
    ```
    To lock to hardware, add `--hardware-id "USER_HWID"`.

For full details, see the [Licensing Guide](docs/getting-started/licensing.md).

---

## 📚 Reading the Documentation

We have comprehensive, high-quality documentation for both Community and Pro users.

### Online/Local Website
To view the full documentation as a beautiful website with search and detailed guides:
1.  **Install dependencies**: `pip install mkdocs-material "mkdocstrings[python]"`
2.  **Serve locally**: `mkdocs serve`
3.  **View**: Open `http://127.0.0.1:8000` in your browser.

### Documentation Chapters
*   [**Getting Started**](docs/index.md): Introduction and value proposition.
*   [**Installation**](docs/getting-started/installation.md): Set up your environment for native compilation.
*   [**Obfuscation**](docs/features/obfuscation.md): Deep dive into renaming and control flow flattening.
*   [**Turbo Mode (BCC)**](docs/features/turbo-mode.md): Extreme performance and binary-locked kernels.
*   [**Advanced Security**](docs/features/security.md): Virtualization (VM), hardware binding, and asset protection.
*   [**CLI Reference**](docs/reference/cli.md): Complete list of all build and release flags.
*   [**API Reference**](docs/reference/api.md): Programmatic usage of the Cryptolith engine.
*   [**Examples**](docs/examples/web-apps.md): Templates for Web APIs, Data Science, and Licensing.

---

## 🛠️ Installation

```bash
pip install cryptolith
```

> [!NOTE]
> **Requirements**: BCC and Turbo modes require a C compiler (MSVC on Windows, GCC/Clang on Linux/macOS).

---

## 🚀 Quick Usage

### 1. Basic Build
The simplest way to protect a script and bundle it into an EXE:
```bash
cryptolith build main.py --output dist/protected
```

### 2. High-Performance Build (Pro)
Enable native transpilation and release the GIL:
```bash
cryptolith build app.py --enable-bcc --enable-turbo
```

### 3. Ultimate Security (Pro)
Enable virtualization and private mode to defeat all known decompilers:
```bash
cryptolith build app.py --enable-vm --private --license license.dat
```

### 4. Professional Licensing
If you have a professional license, specify it during the build:
```bash
cryptolith build main.py --license path/to/license.dat
```
Cryptolith will automatically verify the ED25519 signature and unlock all Pro features.

---

## 🧪 Verification Suite

Cryptolith includes a rigorous automated test runner that validates the entire stack:
```bash
cryptolith test
```

---

## 🚀 CI/CD & Releases

Automated builds and releases are managed via GitHub Actions. To trigger a new release (which builds wheels for Windows, Linux, and macOS and uploads them to GitHub Releases):

### 1. Tag the version
```bash
git tag -a v1.0.0 -m "Release version 1.0.0"
```

### 2. Push the tag
```bash
git push origin v1.0.0
```

The pipeline will automatically:
1.  **Build Wheels**: Compile cross-platform binaries for all supported Python versions.
2.  **Generate Source Dist**: Create a `.tar.gz` for source-based installations.
3.  **GitHub Release**: Create a new release and attach all binaries as assets.
4.  **PyPI Publish**: Attempt to publish to PyPI (requires valid token).

---

## ⚖️ License
Licensed under the MIT License. See `LICENSE` for details.

## Notes

- Go to your project on pypi.org.
- Go to Settings > Publishing > Add a GitHub Publisher.
- Enter your Repository name (cryptolith), the Workflow name (
publish.yml
), and the Environment name (pypi).
- Once connected, PyPI will automatically trust the tokens generated by your GitHub Actions runner.
