Metadata-Version: 2.4
Name: qeltrix_v6
Version: 0.1.0
Summary: A useful paacakge for  ultra high file encryption and  routing
Home-page: https://github.com/Qeltrix/Qeltrix-v6
Author: hejhdiss
Author-email: hejhdiss@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: Other/Proprietary License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: cryptography
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Qeltrix V6 — Network-Native Encrypted Streaming Container

**Author:** Muhammed Shafin P ([@hejhdiss](https://github.com/hejhdiss))  
**License:** CC BY-SA 4.0  
**Architecture:** C shared library (`.so`/`.dll`) + Python `cryptography` library

> ⚠️ **PROOF-OF-CONCEPT ONLY.** Not for production/security-critical use without independent cryptographic audit.
>
>Created fully with  Claude Sonnet 4.6.

---

## What is Qeltrix V6?

V6 is the network-native evolution of the Qeltrix encrypted archiving system. It turns any data stream into a **live, seekable, encrypted V6 container** — without needing the entire file first.

Key capabilities:
- **On-the-fly encryption** as data arrives from any source
- **HTTP Range Request** support — seek into encrypted files without full download
- **Parallel processing** via `ThreadPoolExecutor` (cross-platform, including Windows)
- **Per-block integrity** via SHA-256 + AEAD authentication tags
- **Dual-layer key security** — CDK wrapped in MK, V6-C metadata also encrypted
- **Two AEAD ciphers:** AES-256-GCM and ChaCha20-Poly1305
- **Full Windows support** — `.dll` built with MinGW, tested on Windows PowerShell

---

## Architecture

```
┌──────────────────────────────────────────────────────────┐
│                    Qeltrix V6 System                     │
│                                                          │
│  ┌─────────────────────┐    ┌──────────────────────────┐ │
│  │  C Shared Library   │    │  Python (cryptography)   │ │
│  │  libqeltrix_v6.so   │    │                          │ │
│  │  qeltrix_v6.dll     │    │  ● AES-256-GCM           │ │
│  │                     │    │  ● ChaCha20-Poly1305      │ │
│  │  ● Block framing    │◄──►│  ● HKDF-SHA256 (CDK)     │ │
│  │  ● Permutation      │    │  ● SHA-256 hashing       │ │
│  │  ● Header/footer    │    │  ● Master key wrapping   │ │
│  │  ● TCP networking   │    │  ● V6-C metadata crypto  │ │
│  │  ● HTTP parsing     │    │                          │ │
│  │  ● Seek math        │    │                          │ │
│  └─────────────────────┘    └──────────────────────────┘ │
│                                                          │
│  ┌───────────────┐  ┌───────────────┐  ┌──────────────┐  │
│  │ pack/unpack   │  │ GatewayServer │  │  SeekServer  │  │
│  │ container.py  │  │ gateway.py    │  │ (HTTP+Range) │  │
│  └───────────────┘  └───────────────┘  └──────────────┘  │
└──────────────────────────────────────────────────────────┘
```

### V6 Container Layout
```
[V6Header 416 bytes]
  ├── magic: "QLTX", version: 6
  ├── block_size, total_blocks, original_file_size
  └── footer_offset, footer_size

[Block 0]
  ├── prefix (28 bytes): magic + block_index + v6c_size + payload_size
  ├── v6c_iv (12 bytes)
  ├── encrypted V6-C metadata  ← Layer 2: whole metadata encrypted with MK
  │     └── contains IV, salt, encrypted_CDK  ← Layer 1: CDK encrypted with MK
  └── encrypted payload  ← AEAD encrypted with CDK (AES-GCM or ChaCha20)

[Block 1] ... [Block N]

[Footer]
  ├── magic: "QLTXFOOT", block_count, footer_hash
  └── BlockIndexEntry × N  (original_offset, container_offset, hash, …)
```

---

## Build

### Linux / macOS
```bash
cd c_lib
make
cp libqeltrix_v6.so ../python/qeltrix_v6/
```

### Windows (MinGW / Git Bash)
```bash
cd c_lib
make                           # produces qeltrix_v6.dll
copy qeltrix_v6.dll ..\python\qeltrix_v6\
```

**Requirements:**
- Python 3.11+
- `pip install cryptography`
- GCC (Linux/macOS) or MinGW `x86_64-w64-mingw32-gcc` (Windows)

---

## Python API

```python
import qeltrix_v6 as qltx
from qeltrix_v6.crypto import random_master_key, CIPHER_AES256_GCM, CIPHER_CHACHA20_POLY1305

# ── Key generation ─────────────────────────────────────────────
mk = random_master_key()   # 32 secure random bytes

# Or derive from a passphrase:
import hashlib
mk = hashlib.pbkdf2_hmac("sha256", b"my-passphrase", b"salt", 200_000)

# ── Pack ───────────────────────────────────────────────────────
result = qltx.pack(
    "input.bin",                    # file path, bytes, or file-like
    "output.qltx",
    mk,
    block_size=1024*1024,           # 1 MB blocks (default)
    cipher_id=CIPHER_AES256_GCM,    # or CIPHER_CHACHA20_POLY1305
    workers=4,
)
print(f"{result.total_blocks} blocks, {result.elapsed_s:.2f}s")

# ── Unpack ─────────────────────────────────────────────────────
result = qltx.unpack("output.qltx", "recovered.bin", mk, workers=4)
print(f"Integrity: {'OK' if result.integrity_ok else 'FAILED'}")

# ── Seek (partial extraction, no full download needed) ─────────
data = qltx.seek_extract(
    "output.qltx",
    seek_offset=1_000_000,
    seek_len=500_000,
    master_key=mk,
)
# Only the blocks that contain those bytes are decrypted.

# ── Stream packing (live / gateway core) ───────────────────────
from qeltrix_v6.gateway import StreamPacker
import io

packer = StreamPacker(mk, block_size=256*1024, cipher_id=CIPHER_CHACHA20_POLY1305)
out = io.BytesIO()
packer.pack_stream(io.BytesIO(raw_data), out.write, total_size=len(raw_data))
packer.patch_header(out, total_size=len(raw_data))   # fix header if buf is seekable
container = out.getvalue()

# ── GatewayServer ──────────────────────────────────────────────
# Receives raw TCP data, encrypts on-the-fly, sends V6 stream back
gw = qltx.GatewayServer(
    mk,
    listen_host="0.0.0.0", listen_port=7620,
    cipher_id=CIPHER_AES256_GCM,
    workers=4,
    dest_host=None,   # None = reflect V6 stream back to sender
)
gw.start()   # non-blocking thread

# ── SeekServer (HTTP + Range Requests) ─────────────────────────
srv = qltx.SeekServer("output.qltx", mk, host="0.0.0.0", port=7621, workers=4)
srv.start()
# Clients can now do:
#   GET http://localhost:7621/  Range: bytes=0-1048575
# and receive exactly those bytes from the original file,
# with only the needed blocks decrypted.
```

---

## CLI

```bash
cd python

# Pack a file
python -m qeltrix_v6 pack  input.bin output.qltx --passphrase secret

# Unpack
python -m qeltrix_v6 unpack output.qltx recovered.bin --passphrase secret

# Seek — extract byte range without unpacking the whole file
python -m qeltrix_v6 seek output.qltx --offset 1000000 --length 500000 \
    --passphrase secret --output extracted.bin

# Gateway server — encrypts all incoming connections on-the-fly
python -m qeltrix_v6 gateway --port 7620 --passphrase secret

# Gateway with downstream routing
python -m qeltrix_v6 gateway --port 7620 --passphrase secret \
    --dest-host storage.example.com --dest-port 9000

# HTTP Seek server with Range Request support
python -m qeltrix_v6 serve output.qltx --port 7621 --passphrase secret

# Container info (no passphrase needed)
python -m qeltrix_v6 info output.qltx

# Options
--cipher aes|chacha    Cipher (default: aes = AES-256-GCM)
--block-size N         Block size in KB (default: 1024 = 1 MB)
--workers N            Parallel workers (default: 4)
--no-verify            Skip per-block integrity checks (faster)
```

---

## Running Tests

```bash
# From the project root (qeltrix_v6/)
python tests\test_all.py      # Windows
python tests/test_all.py      # Linux / macOS
```

Expected output:
```
============================================================
Qeltrix V6 Test Suite
============================================================
[C Library]
  ✓ version string  ✓ block count  ✓ block range  ...
[Cryptography]
  ✓ AES-256-GCM  ✓ ChaCha20-Poly1305  ✓ HKDF  ...
[Pack / Unpack]
  ✓ pack small file  ✓ unpack + verify integrity
  ✓ ChaCha20 roundtrip  ✓ seek extraction  ...
============================================================
Results: 20/20 passed — All tests passed!
```

---

## Windows Notes

### Why `ThreadPoolExecutor` instead of `ProcessPoolExecutor`

On Linux/macOS, `ProcessPoolExecutor` uses `os.fork()` — the child process inherits memory directly. On Windows there is no `fork`, so Python uses **spawn**: it starts a brand-new Python interpreter and re-imports your module from scratch in every worker. This causes the "bootstrapping phase" error if the module creates an executor at import time.

`ThreadPoolExecutor` avoids this completely — threads share process memory, no re-import needed. Crypto operations with the `cryptography` library release the GIL during computation, so threads still run in parallel for I/O and crypto.

### Why `if __name__ == '__main__':` in test_all.py

Even with `ThreadPoolExecutor`, this guard is best practice on Windows for any script that uses concurrency. All test logic lives inside `run_tests()`, only called when the script is the entry point.

---

## Platform Support

| Platform | Library        | Build command                  |
|----------|---------------|-------------------------------|
| Linux    | `.so`         | `make` in `c_lib/`            |
| macOS    | `.dylib`      | `make` in `c_lib/`            |
| Windows  | `.dll`        | `make` in `c_lib/` (MinGW)   |

---

## Cryptographic Design (V6cs Mode)

```
Master Key (MK)  ←  32 secure random bytes
        │
        ├─ HKDF(MK, block_index, block_hash, salt) → CDK
        │     Unique per block, bound to content AND position
        │
        ├─ AES-GCM(MK, CDK) → Encrypted CDK        [Layer 1]
        │     Stored in V6-C metadata block
        │
        └─ AES-GCM(MK, V6-C metadata) → Encrypted metadata  [Layer 2]
              Attacker without MK cannot read per-block keys

Block payload:
  CDK + random IV → AES-256-GCM or ChaCha20-Poly1305
  AAD = big-endian block_index  (binds ciphertext to position)
```

---

## File Structure

```
qeltrix_v6/
├── c_lib/
│   ├── qeltrix_v6.c          ← C core (permutation, framing, TCP I/O)
│   └── Makefile
├── python/
│   └── qeltrix_v6/
│       ├── __init__.py       ← Public API
│       ├── __main__.py       ← python -m qeltrix_v6
│       ├── _clib.py          ← ctypes bindings to C library
│       ├── crypto.py         ← All crypto (cryptography library)
│       ├── container.py      ← Pack / Unpack / Seek
│       ├── gateway.py        ← GatewayServer / SeekServer / StreamPacker
│       ├── cli.py            ← CLI argument parsing
│       └── qeltrix_v6.dll    ← Windows: copy built DLL here
│           libqeltrix_v6.so  ← Linux: copy built .so here
├── tests/
    ├── test_all.py           ← 20 tests, run from project root
    ├── test_network.py       ← 14 tests, run from project root

```
