Metadata-Version: 2.4
Name: hypercrypto
Version: 0.1.3
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security :: Cryptography
Classifier: License :: OSI Approved :: MIT License
License-File: LICENSE
Summary: Ultra-fast Next-Generation MTProto 2.0 Cryptographic Engine for Telegram
Keywords: telegram,mtproto,crypto,aes-ige,aes-ctr,kdf
Author: alreadydead0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# HyperCrypto

Ultra high-performance, memory-efficient cryptographic extensions for Telegram MTProto 2.0 written in Rust with PyO3.

## Features

- **MTProto 2.0 Compliant**: Full bit-for-bit compatibility with official Telegram MTProto specifications.
- **Hardware Accelerated**: Optimized for AES-NI, AVX2, SHA-NI on x86_64 and ARMv8 Crypto / NEON on ARM64 with automatic safe software fallback on older processors.
- **Zero-Copy Architecture**: Uses Python's buffer protocol and single-pass allocations (`PyBytes::new_with`) to eliminate intermediate heap buffers.
- **Multi-Platform Support**: Pre-built binary wheels for Windows, Linux (manylinux/musllinux x86_64 and aarch64), and macOS (Intel & Apple Silicon).

## Installation

```bash
pip install hypercrypto
```

No Rust compiler or external C dependencies required for installation.

## API Reference

### 1. AES-256-IGE (RPC & Packet Encryption)
```python
import hypercrypto

# Immutable Bytes API
ciphertext = hypercrypto.ige256_encrypt(data: bytes, key: bytes, iv: bytes) -> bytes
plaintext = hypercrypto.ige256_decrypt(ciphertext: bytes, key: bytes, iv: bytes) -> bytes

# Zero-Allocation In-Place API (Accepts bytearray)
hypercrypto.ige256_encrypt_inplace(buffer: bytearray, key: bytes, iv: bytes) -> None
hypercrypto.ige256_decrypt_inplace(buffer: bytearray, key: bytes, iv: bytes) -> None
```

### 2. AES-256-CTR (High-Throughput File Streaming & Downloads)
```python
# Immutable Bytes API (supports stream state tracking)
encrypted = hypercrypto.ctr256_encrypt(data: bytes, key: bytes, iv: bytearray | bytes, state: bytearray = None) -> bytes
decrypted = hypercrypto.ctr256_decrypt(data: bytes, key: bytes, iv: bytearray | bytes, state: bytearray = None) -> bytes

# Zero-Allocation In-Place API
hypercrypto.ctr256_encrypt_inplace(buffer: bytearray, key: bytes, iv: bytearray | bytes, state: bytearray = None) -> None
hypercrypto.ctr256_decrypt_inplace(buffer: bytearray, key: bytes, iv: bytearray | bytes, state: bytearray = None) -> None
```

### 3. MTProto 2.0 KDF (Key Derivation Function)
```python
aes_key, aes_iv = hypercrypto.kdf(auth_key: bytes, msg_key: bytes, is_outgoing: bool) -> tuple[bytes, bytes]

# Zero-Allocation In-Place API
hypercrypto.kdf_into(auth_key, msg_key, is_outgoing, key_out: bytearray, iv_out: bytearray) -> None
```

### 4. End-to-End MTProto Packet Assembly
```python
packed_packet = hypercrypto.pack_message(auth_key: bytes, message: bytes, is_outgoing: bool) -> bytes
unpacked_payload = hypercrypto.unpack_message(auth_key: bytes, encrypted_packet: bytes, is_outgoing: bool) -> bytes
```

## Measured Benchmark Results

> **Test Environment**:
> - OS: Windows 11 Pro 64-bit / Linux x86_64
> - CPU: AMD Athlon Silver 3050U (AES-NI, AVX2, SHA-NI)
> - Python: Python 3.13 (Anaconda 64-bit)
> - Direct Comparison: **TgCrypto** vs **WarpCrypto** vs **HyperCrypto v0.1.3**

### 1. AES-256-IGE RPC & Small Packet Latency
| Payload Size | TgCrypto | WarpCrypto | **HyperCrypto v0.1.3** | Speedup vs Warp |
| :--- | :--- | :--- | :--- | :--- |
| **64 B (Ping/Ack)** | 1.55 µs | 1.06 µs | **449.9 ns** | **2.4x faster** |
| **1 KB (Message)** | 11.31 µs | 2.86 µs | **2.09 µs** | **1.4x faster** |
| **64 KB (Payload)** | 669.38 µs | 125.69 µs | **107.29 µs (582 MB/s)** | **1.2x faster** |
| **1 MB (File Block)** | 11.77 ms | 3.22 ms | **2.34 ms (428 MB/s)** | **1.4x faster** |

### 2. AES-256-CTR File Downloads & Streaming Throughput
| Chunk Size | TgCrypto CTR | WarpCrypto CTR | **HyperCrypto v0.1.3** |
| :--- | :--- | :--- | :--- |
| **64 KB (Chunk)** | 63.0 MB/s | 968.3 MB/s | **1,110.0 MB/s (1.11 GB/s)** |
| **512 KB (TG Part)** | 68.6 MB/s | 903.4 MB/s | **973.4 MB/s** |
| **1 MB (Large Part)** | 68.7 MB/s | 648.4 MB/s | **711.1 MB/s** |
| **10 MB (Media)** | 67.4 MB/s | 406.0 MB/s | **640.4 MB/s** |

### 3. MTProto 2.0 KDF & End-to-End Packets
| Operation | Python / TgCrypto | WarpCrypto | **HyperCrypto v0.1.3** |
| :--- | :--- | :--- | :--- |
| **MTProto 2.0 KDF** | 6,730 ns | 759.3 ns | **467.9 ns (kdf_into) / 561 ns (kdf)** |
| **Pack Message** | Not Supported | 2.86 µs | **1.45 µs (2.0x faster)** |
| **Unpack Message** | Not Supported | 2.49 µs | **1.41 µs (1.8x faster)** |

## License

MIT License. Copyright (c) 2026 alreadydead0.

