python -m qeltrix_v6 pack input.txt output.qltx --passphrase mysecretpassword

# With options:
python -m qeltrix_v6 pack input.bin output.qltx \
    --passphrase mysecretpassword \
    --cipher chacha \
    --block-size 512 \
    --workers 8

Qeltrix V6 Pack
  Input:      myfile.c (5,189 bytes)
  Output:     myfile.qltx
  Cipher:     AES-256-GCM
  Block size: 1,048,576 bytes
  Workers:    4

[INFO] Packing 5,189 bytes -> 1 blocks
  [████████████████████] 100% (1/1 blocks)

✓ Done in 0.047s
  Blocks:     1
  Original:   5,189 bytes
  Container:  2,047 bytes (0.39x overhead)
  Speed:      0.1 MB/s

python -m qeltrix_v6 unpack output.qltx recovered.txt --passphrase mysecretpassword

# Skip integrity checks for speed (not recommended):
python -m qeltrix_v6 unpack output.qltx recovered.txt \
    --passphrase mysecretpassword \
    --no-verify

Qeltrix V6 Unpack
  Container: myfile.qltx (2,047 bytes)
  Output:    recovered.txt
  Verify:    Yes
  Workers:   4

[INFO] Unpacking 1 blocks -> 5,189 bytes
  [████████████████████] 100% (1/1 blocks)

✓ Done in 0.000s
  Blocks:    1
  Original:  5,189 bytes
  Speed:     0.0 MB/s
  Integrity: ✓ OK

# Extract bytes 0–99 (first 100 bytes)
python -m qeltrix_v6 seek myfile.qltx \
    --offset 0 --length 100 \
    --passphrase mysecretpassword \
    --output chunk.bin

# Extract from the middle — bytes 5000–5499
python -m qeltrix_v6 seek myfile.qltx \
    --offset 5000 --length 500 \
    --passphrase mysecretpassword \
    --output middle.bin

# Print hex if no --output specified
python -m qeltrix_v6 seek myfile.qltx \
    --offset 0 --length 64 \
    --passphrase mysecretpassword

python -m qeltrix_v6 serve myfile.qltx --port 7621 --passphrase mysecretpassword

# All options:
python -m qeltrix_v6 serve myfile.qltx \
    --host 0.0.0.0 \
    --port 7621 \
    --passphrase mysecretpassword \
    --workers 4

# Download the complete decrypted file
Invoke-WebRequest -Uri http://localhost:7621/ -OutFile received_file.txt

# Verify it matches original
Get-Content received_file.txt

# Get first 100 bytes only
Invoke-WebRequest -Uri http://localhost:7621/ `
    -Headers @{ Range = "bytes=0-99" } `
    -OutFile first100.bin

# Get bytes 500 to 999
Invoke-WebRequest -Uri http://localhost:7621/ `
    -Headers @{ Range = "bytes=500-999" } `
    -OutFile middle.bin

# Get last 200 bytes
Invoke-WebRequest -Uri http://localhost:7621/ `
    -Headers @{ Range = "bytes=-200" } `
    -OutFile last200.bin

# Full download
curl http://localhost:7621/ -o received.txt

# Range request
curl http://localhost:7621/ -H "Range: bytes=0-99" -o chunk.bin

server {
    listen 443 ssl;
    server_name files.yourdomain.com;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:7621;
        proxy_set_header Range $http_range;
    }
}

python -m qeltrix_v6 gateway --port 7620 --passphrase mysecretpassword

$bytes = [System.IO.File]::ReadAllBytes("$PWD\secret.txt")
$client = New-Object System.Net.Sockets.TcpClient("127.0.0.1", 7620)
$stream = $client.GetStream()
$stream.Write($bytes, 0, $bytes.Length)
$stream.Flush()

# Signal end-of-send so gateway flushes and responds
$client.Client.Shutdown([System.Net.Sockets.SocketShutdown]::Send)

# Read back the encrypted V6 stream
$ms = New-Object System.IO.MemoryStream
$buf = New-Object byte[] 4096
do { $r = $stream.Read($buf,0,$buf.Length); if($r -gt 0){$ms.Write($buf,0,$r)} } while ($r -gt 0)
$client.Close()

[System.IO.File]::WriteAllBytes("$PWD\encrypted.qltx", $ms.ToArray())
python -m qeltrix_v6 unpack encrypted.qltx recovered.txt --passphrase mysecretpassword

Stats: 1 connections, 118 bytes in, 669 bytes out

python -m qeltrix_v6 info myfile.qltx

Qeltrix V6 Container Info
  File:           myfile.qltx
  File size:      669 bytes
  Version:        6
  Flags:          0x02
  Cipher:         AES256-GCM
  Block size:     1,048,576 bytes (1024 KB)
  Total blocks:   1
  Original size:  118 bytes
  Footer offset:  493
  Footer size:    176 bytes
  Overhead:       466.9%

from qeltrix_v6 import (
    pack, unpack,
    CIPHER_AES256_GCM, CIPHER_CHACHA20_POLY1305
)
from qeltrix_v6.crypto import random_master_key

# Generate a random 32-byte master key
mk = random_master_key()

# Pack a file
result = pack(
    "input.txt",          # source file path
    "output.qltx",        # destination container path
    mk,                    # 32-byte master key
    block_size=1 << 20,    # 1 MB blocks (default)
    cipher_id=CIPHER_AES256_GCM,
    workers=4,
    progress_cb=lambda done, total: print(f"{done}/{total}")
)

print(result.total_blocks)    # int
print(result.original_size)   # int bytes
print(result.elapsed_s)       # float seconds

result = unpack(
    "output.qltx",    # container path
    "recovered.txt",  # output path
    mk,                # same 32-byte master key
    no_verify=False,   # True skips integrity checks
    workers=4
)

print(result.integrity_ok)    # True = all blocks verified
print(result.original_size)   # int bytes
print(result.elapsed_s)

# pack() also accepts raw bytes or a file-like object as source
data = b"Hello, encrypted world!"
result = pack(data, "output.qltx", mk)

# Or a BytesIO stream
import io
stream = io.BytesIO(b"stream data")
result = pack(stream, "output.qltx", mk)

from qeltrix_v6 import seek_extract

# Extract 500 bytes starting at offset 1000
data = seek_extract(
    "bigfile.qltx",
    seek_offset=1000,
    seek_len=500,
    master_key=mk,
    no_verify=False,
    workers=4
)

print(len(data))   # 500
print(data[:32])   # first 32 bytes of the extracted slice

# Serve a specific second of a video stored as .qltx
# Video: 30 fps, 1920x1080, ~4 MB/s bitrate

BYTES_PER_SECOND = 4_000_000
timestamp_seconds = 120  # seek to 2 minutes

chunk = seek_extract(
    "movie.qltx",
    seek_offset=timestamp_seconds * BYTES_PER_SECOND,
    seek_len=BYTES_PER_SECOND,   # 1 second of video
    master_key=mk
)
# chunk contains exactly 1 second of decrypted video data
# only the 1-4 blocks covering that range were decrypted

from qeltrix_v6 import GatewayServer, CIPHER_AES256_GCM
from qeltrix_v6.crypto import random_master_key
import time

mk = random_master_key()

gw = GatewayServer(
    mk,
    listen_host="0.0.0.0",
    listen_port=7620,
    cipher_id=CIPHER_AES256_GCM,
    workers=4,
    dest_host=None,    # None = reflect mode
    dest_port=None,
)

gw.start(blocking=False)   # runs in background thread

# Your application runs here...
try:
    while True:
        time.sleep(5)
        s = gw.stats
        print(s['connections'], s['bytes_in'], s['bytes_out'])
except KeyboardInterrupt:
    gw.stop()

gw = GatewayServer(
    mk,
    listen_port=7620,
    dest_host="storage-server.internal",  # forward here
    dest_port=7622,
)
gw.start(blocking=True)   # blocks until Ctrl+C

from qeltrix_v6 import StreamPacker
import io

# Encrypt a stream to a buffer (no file I/O)
packer = StreamPacker(mk, block_size=1 << 20, cipher_id=CIPHER_AES256_GCM)

source = io.BytesIO(b"my data stream")
output = io.BytesIO()

index = packer.pack_stream(
    source,
    lambda chunk: output.write(chunk),
    total_size=None
)

encrypted_bytes = output.getvalue()
print(len(encrypted_bytes), "bytes encrypted")

from qeltrix_v6 import HttpStreamGateway

# Download a URL and save it as an encrypted V6 container
gw = HttpStreamGateway(
    mk,
    url="https://example.com/data.bin",
    block_size=1 << 20,
    cipher_id=CIPHER_AES256_GCM,
)
bytes_written = gw.stream_to_file("encrypted_download.qltx")
print(bytes_written, "bytes in container")

from qeltrix_v6 import SeekServer
from qeltrix_v6.crypto import random_master_key
import time

mk = random_master_key()

srv = SeekServer(
    "bigfile.qltx",    # path to .qltx container
    mk,                  # master key
    host="0.0.0.0",
    port=7621,
    workers=4
)

srv.start(blocking=False)   # background thread

# Server runs; any HTTP client can now GET / with Range headers
try:
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    srv.stop()

# Use seek_extract directly — no HTTP server needed
from qeltrix_v6 import seek_extract

# Read bytes 0-1023 of the original file
chunk = seek_extract("bigfile.qltx", 0, 1024, mk)

# Read a "frame" at position 4096
frame = seek_extract("bigfile.qltx", 4096, 512, mk)

from qeltrix_v6 import pack, SeekServer
from qeltrix_v6.crypto import random_master_key
import time

mk = random_master_key()

# 1. Encrypt the file
pack("video.mp4", "video.qltx", mk, block_size=1 << 20)

# 2. Serve it — any media player with the URL can now seek
srv = SeekServer("video.qltx", mk, port=7621)
srv.start(blocking=False)
print("Serving at http://localhost:7621/")

# Media player hits: GET / Range: bytes=X-Y
# SeekServer decrypts only those blocks and returns plaintext
while True: time.sleep(1)

from qeltrix_v6.crypto import (
    random_master_key, random_key, random_iv,
    random_salt, random_bytes
)

mk   = random_master_key()  # 32 bytes — root key
key  = random_key()          # 32 bytes — AES/ChaCha key
iv   = random_iv()           # 12 bytes — GCM/ChaCha nonce
salt = random_salt()         # 32 bytes — HKDF salt

from qeltrix_v6.crypto import derive_cdk, sha256, CIPHER_AES256_GCM

block_data = b"raw block content"
block_hash = sha256(block_data)
salt       = random_salt()

# CDK is bound to: master key + block position + content hash + salt
cdk = derive_cdk(
    master_key=mk,
    block_index=0,
    block_data_hash=block_hash,
    salt=salt,
    cipher_id=CIPHER_AES256_GCM
)
# cdk is 32 bytes, unique to this block's content AND position

from qeltrix_v6.crypto import encrypt_block, decrypt_block, CIPHER_AES256_GCM

plaintext  = b"secret data"
iv         = random_iv()
ciphertext = encrypt_block(plaintext, cdk, iv, CIPHER_AES256_GCM, aad=b"context")

# Decrypt
recovered = decrypt_block(ciphertext, cdk, iv, CIPHER_AES256_GCM, aad=b"context")
assert recovered == plaintext

from qeltrix_v6.crypto import wrap_master_key, unwrap_master_key

# Wrap MK with a passphrase for storage
wrapped_mk, iv, salt = wrap_master_key(mk, passphrase=b"mypassphrase")

# Recover MK
recovered_mk = unwrap_master_key(wrapped_mk, b"mypassphrase", iv, salt)
assert recovered_mk == mk

# Note: CLI uses a HARDCODED salt for PBKDF2 (PoC limitation)
# For production: generate random salt per container

from qeltrix_v6.container import DEFAULT_BLOCK_SIZE, MAX_WORKERS

DEFAULT_BLOCK_SIZE = 1 << 20   # 1,048,576 bytes (1 MB) — default block size for all operations
MAX_WORKERS        = min(os.cpu_count() or 4, 16)   # thread pool cap, auto-detected at import

from qeltrix_v6.container import BlockIndexEntry

# One entry per block in the QLTXFOOT VFS index.
# Used by seek_extract() to find exactly which blocks cover a byte range.
@dataclass
class BlockIndexEntry:
    block_index:      int    # 0-based block number
    original_offset:  int    # byte offset of this block in the ORIGINAL file
    original_size:    int    # plaintext size of this block (varies for last block)
    container_offset: int    # byte offset of this block in the .qltx CONTAINER
    container_size:   int    # total bytes this block occupies in the container
                              # (prefix 28 + v6c_iv 12 + enc_v6c N + payload)
    block_hash:       bytes  # SHA-256 of original (pre-compression) block data, 32 bytes
    iv:               bytes  # 12-byte nonce used to encrypt the block payload
    salt:             bytes  # 32-byte random HKDF salt used for CDK derivation
    cipher_id:        int    # 0 = AES-256-GCM, 1 = ChaCha20-Poly1305

from qeltrix_v6.container import V6PackResult   # also: from qeltrix_v6 import V6PackResult

# Returned by pack()
@dataclass
class V6PackResult:
    container_path: str    # output .qltx file path
    total_blocks:   int    # number of blocks written
    original_size:  int    # original file size in bytes
    block_size:     int    # block size used (bytes)
    cipher_id:      int    # cipher used (0 or 1)
    elapsed_s:      float  # wall-clock seconds for entire pack operation

# Usage:
r = pack("file.txt", "file.qltx", mk)
print(r.total_blocks, r.original_size, r.elapsed_s)

from qeltrix_v6.container import V6UnpackResult   # also: from qeltrix_v6 import V6UnpackResult

# Returned by unpack()
@dataclass
class V6UnpackResult:
    output_path:   str    # path of the recovered file
    total_blocks:  int    # number of blocks decrypted
    original_size: int    # recovered file size in bytes
    elapsed_s:     float  # wall-clock seconds
    integrity_ok:  bool   # True if all block SHA-256 hashes verified correctly
                           # False signals container tampering or wrong passphrase

# Usage:
r = unpack("file.qltx", "recovered.txt", mk)
if not r.integrity_ok:
    raise RuntimeError("Container tampered!")

from qeltrix_v6.container import _pack_one_block

# Signature:
def _pack_one_block(block_index, raw_data, master_key, cipher_id) -> dict:

# Steps performed:
#  1. SHA-256(raw_data)              → block_hash
#  2. zlib.compress(raw_data, 6)     → compressed
#  3. random_salt() + random_iv()    → per-block entropy
#  4. derive_cdk(mk, idx, hash, salt) → CDK
#  5. permute_block(compressed, hash) → permuted  [C lib]
#  6. AEAD encrypt(permuted, CDK, iv, aad=pack(">Q", block_index)) → payload
#  7. wrap_cdk(CDK, mk)              → (wrapped_cdk 48b, cdk_iv 12b)
#  8. make_v6c(...)                  → v6c_raw  [C lib]
#  9. encrypt_v6c_metadata(v6c_raw, mk) → (enc_v6c, v6c_iv)

# Returns dict with keys:
# "block_index", "v6c_iv", "enc_v6c", "payload",
# "block_hash", "iv", "salt", "cipher_id", "orig_sz", "comp_sz"

from qeltrix_v6.container import _unpack_one_block

# Signature:
def _unpack_one_block(block_index, enc_v6c, v6c_iv, payload, master_key, no_verify)     -> tuple[int, bytes]:

# Steps performed (exact reverse of _pack_one_block):
#  1. decrypt_v6c_metadata(enc_v6c, mk, v6c_iv)   → v6c_raw
#  2. qltx_read_v6c(v6c_raw)  → block_hash, iv, salt, cdk_blob, cipher_id
#  3. unwrap_cdk(cdk_blob[12:60], mk, cdk_blob[:12]) → CDK
#  4. AEAD decrypt(payload, CDK, iv, aad=pack(">Q", block_index)) → permuted
#  5. unpermute_block(permuted, block_hash) → compressed
#  6. zlib.decompress(compressed) → raw_data
#  7. if not no_verify: assert SHA-256(raw_data) == block_hash

# Returns: (block_index: int, raw_data: bytes)
# Raises ValueError on bad V6-C magic or integrity failure

from qeltrix_v6.container import _serialize_footer, _parse_footer, _read_container_index

# Serialize list[BlockIndexEntry] → bytes  (QLTXFOOT magic + count + hash + entries)
# Layout: b"QLTXFOOT" (8) + entry_count uint64 (8) + SHA-256 of entries (32) + entries
# Each entry: 128 bytes from C struct qltx_index_entry via qltx_write_index_entry()
footer_bytes = _serialize_footer(entries)   # list[BlockIndexEntry] → bytes

# Parse QLTXFOOT bytes back into list[BlockIndexEntry]
entries = _parse_footer(footer_bytes)        # bytes → list[BlockIndexEntry]
# Raises ValueError if magic != b"QLTXFOOT" or data is truncated

# High-level: read header dict + full index from a .qltx file in one call
# Returns (header_info: dict, entries: list[BlockIndexEntry])
hdr, entries = _read_container_index("myfile.qltx")

# hdr dict keys:
# "version", "flags", "cipher_default", "block_size",
# "total_blocks", "original_size", "footer_offset", "footer_size"

# Example: check original size without decrypting anything
hdr, _ = _read_container_index("secret.qltx")
print("Original size:", hdr["original_size"], "bytes")

from qeltrix_v6.crypto import encrypt_v6c_metadata, decrypt_v6c_metadata

# Encrypt a V6-C metadata bytes blob with the MK
# Returns (encrypted_metadata: bytes, iv: bytes)
enc_meta, meta_iv = encrypt_v6c_metadata(v6c_raw_bytes, mk)
# Uses AES-256-GCM with aad=b"V6C-METADATA" internally

# Decrypt it back
v6c_raw = decrypt_v6c_metadata(enc_meta, mk, meta_iv)

from qeltrix_v6.crypto import wrap_cdk, unwrap_cdk

# Wrap CDK with MK — returns (wrapped_cdk: bytes, iv: bytes)
# wrapped_cdk is 48 bytes (32-byte key + 16-byte GCM tag)
wrapped_cdk, cdk_iv = wrap_cdk(cdk, mk)
# aad=b"V6C-CDK-WRAP" used internally

# Recover CDK
cdk = unwrap_cdk(wrapped_cdk, mk, cdk_iv)

from qeltrix_v6.crypto import sha256, sha256_file, hash_footer_entries

# SHA-256 of bytes → 32 bytes
h = sha256(b"data")

# Streaming SHA-256 of a file (avoids loading whole file into RAM)
h = sha256_file("bigfile.bin", chunk_size=1 << 20)

# SHA-256 of all footer index entries concatenated
# Used internally to verify footer integrity
footer_hash = hash_footer_entries([entry1_bytes, entry2_bytes])

from qeltrix_v6.crypto import (
    CIPHER_AES256_GCM,        # = 0
    CIPHER_CHACHA20_POLY1305, # = 1
    CIPHER_NAMES,             # = {0: "AES256-GCM", 1: "ChaCha20-Poly1305"}
    AES_KEY_SIZE,             # = 32
    AES_IV_SIZE,              # = 12
    CHACHA_KEY_SIZE,          # = 32
    CHACHA_IV_SIZE,           # = 12
    SALT_SIZE,                # = 32
    MASTER_KEY_SIZE,          # = 32
)

from qeltrix_v6 import FLAG_NO_VERIFY, FLAG_STREAMING

FLAG_NO_VERIFY = 0x01  # Skip per-block hash checks on unpack
FLAG_STREAMING = 0x02  # Set in container header when created by gateway/StreamPacker
# Gateway always sets FLAG_STREAMING. info command shows Flags: 0x02.

from qeltrix_v6 import GatewayServer, CIPHER_AES256_GCM

gw = GatewayServer(
    master_key=mk,              # 32-byte MK — required
    listen_host="0.0.0.0",      # bind address
    listen_port=7620,            # listen port
    block_size=1 << 20,          # 1 MB blocks (default)
    cipher_id=CIPHER_AES256_GCM, # or CIPHER_CHACHA20_POLY1305
    workers=4,                   # ThreadPoolExecutor workers per connection
    dest_host=None,              # None = reflect; str = forward to this host
    dest_port=None,              # forward port (required if dest_host set)
)

gw.start(blocking=False)   # blocking=True blocks thread until stop()
gw.stop()                  # sets _running=False; does a brief self-connect to unblock accept()

# Live stats dict — updated per connection
s = gw.stats
# s["connections"]  int  — total connections accepted since start
# s["bytes_in"]     int  — total raw plaintext bytes received
# s["bytes_out"]    int  — total encrypted V6 bytes sent
# s["blocks"]       int  — total V6 blocks produced

from qeltrix_v6 import StreamPacker
import io

packer = StreamPacker(
    master_key=mk,
    block_size=1 << 20,
    cipher_id=0,     # CIPHER_AES256_GCM
    workers=4,
    no_verify=False, # if True, sets FLAG_NO_VERIFY in header
)

# Stream source bytes → dest_write callback → valid .qltx bytes emitted
buf = io.BytesIO()
index_entries = packer.pack_stream(
    source=io.BytesIO(b"data to encrypt"),
    dest_write=buf.write,     # any callable(bytes) — socket.sendall, file.write, etc.
    total_size=None,           # int or None; used for progress_cb denominator
    progress_cb=None           # optional callable(blocks_done, total_blocks)
)
# Returns list[BlockIndexEntry] — the VFS index

# After pack_stream, patch the header with correct footer_offset / total_blocks
# (required when buf is seekable; skip for pure streaming sockets)
packer.patch_header(buf, total_size=15)
# Rewrites first N bytes of buf with correct header in place

# Inspect state after pack_stream:
packer._block_index      # int: total blocks written
packer._footer_offset    # int: byte offset of QLTXFOOT in container
packer._footer_size      # int: size of footer
packer._container_offset # int: current write position
packer._index            # list[BlockIndexEntry]: built index

import socket, io

dest = socket.create_connection(("storage-server", 7622))
packer = StreamPacker(mk)
source = io.BytesIO(b"payload")

packer.pack_stream(source, dest.sendall)
# Note: patch_header not possible on a socket (not seekable)
# For socket destinations, header footer_offset will be 0 in PoC.
dest.close()

from qeltrix_v6 import HttpStreamGateway

gw = HttpStreamGateway(
    master_key=mk,
    url="https://example.com/dataset.bin",
    block_size=1 << 20,
    cipher_id=0,   # CIPHER_AES256_GCM
    workers=4,
)

# Download and save as .qltx (returns bytes written)
n = gw.stream_to_file(
    "output.qltx",
    progress_cb=lambda done, total: print(f"{done}/{total}")
)
print(n, "bytes written")

# If Content-Length header is present in HTTP response, total_size is
# passed to StreamPacker for progress reporting. Otherwise total=0.

from qeltrix_v6 import SeekServer

srv = SeekServer(
    container_path="bigfile.qltx",  # .qltx file path
    master_key=mk,                   # 32-byte MK
    host="0.0.0.0",
    port=7621,
    workers=4
)
# __init__ immediately calls _read_container_index() and caches:
# srv._header    — dict with version, flags, block_size, original_size, etc.
# srv._index     — list[BlockIndexEntry]
# srv._entry_map — dict[block_index -> BlockIndexEntry]

srv.start(blocking=False)  # background thread
srv.stop()                 # sets _running=False; accept() exits on next 1s timeout

# HTTP request handling:
# GET /  (no Range)  → unpack() full container to tmp file → serve 200 OK
# GET /  Range: bytes=X-Y  → seek_extract(X, Y-X+1) → serve 206 Partial Content
# GET /  Range: bytes=-N   → serve last N bytes (suffix range)

from qeltrix_v6.gateway import _SocketStream

# Python backend (default) — use for all normal cases
stream = _SocketStream(sock)          # sock is a socket.socket
stream = _SocketStream(fd_int)        # int fd — wrapped via socket.fromfd()

# C backend — only for known-length streams, maximum throughput
# blocks until exactly n bytes arrive; no partial-read or EOF handling
lib = _clib.get_lib()
stream = _SocketStream(raw_fd, lib=lib, use_c=True)

# Use as a regular readable stream
packer.pack_stream(stream, dest_write)

# Called in a daemon thread per accepted TCP connection.
# Signature: _handle_client(self, client_sock, ip: str, port: int)
#
# Flow:
#  1. Read all incoming raw bytes from client_sock (recv loop, 30s timeout)
#  2. Accumulate chunks → raw_data bytes; update stats["bytes_in"]
#  3. Build BytesIO buffer, create StreamPacker
#  4. StreamPacker.pack_stream(BytesIO(raw_data), buf.write, total_size)
#  5. StreamPacker.patch_header(buf, total_size)  — fix footer_offset in header
#  6a. If dest_host set: socket.create_connection(dest_host, dest_port)
#      sendall(container); update stats["bytes_out"]
#  6b. If no dest_host: client_sock.sendall(container)  — reflect mode
#  7. Update stats["blocks"] += packer._block_index
#  8. Close client_sock in finally block

# Called in a daemon thread per accepted HTTP connection.
# Signature: _handle_http(self, conn: socket.socket, addr)
#
# Flow:
#  1. Recv until b"\r\n\r\n" found — accumulates full HTTP headers
#  2. Parse first line (e.g. "GET / HTTP/1.1") and header dict
#  3a. If Range header present:
#      → qltx_parse_range_header(range_val) → (seek_start, seek_end)
#      → Handle suffix range: bytes=-N  means last N bytes
#      → seek_extract(container, seek_start, seek_len, mk)
#      → Send HTTP/1.1 206 Partial Content + Content-Range header + data
#  3b. If no Range header:
#      → unpack(container, tmp_file, mk)
#      → Read tmp_file, send HTTP/1.1 200 OK + full content
#      → Delete tmp_file (tempfile.NamedTemporaryFile)
#  4. Close conn in finally block

# Response headers sent:
# 206: Content-Type, Content-Length, Content-Range, Accept-Ranges, Connection
# 200: Content-Type, Content-Length, Accept-Ranges, Connection

# Called by pack_stream() to write one completed block to dest_write.
# Signature: _emit_block(self, result: dict, dest_write: callable)
#
# Steps:
#  1. Unpack result dict: block_index, v6c_iv, enc_v6c, payload, hash, iv, salt, cipher_id, orig_sz
#  2. Compute v6c_size_field = len(v6c_iv) + len(enc_v6c)  = 12 + N
#  3. make_block_prefix(bidx, v6c_size_field, len(payload)) → 28-byte prefix
#  4. Concatenate: prefix + v6c_iv + enc_v6c + payload → data bytes
#  5. dest_write(data) — socket.sendall, file.write, BytesIO.write, etc.
#  6. Append BlockIndexEntry to self._index
#  7. Advance self._container_offset by len(data)
#
# Called in-order by _flush_pending() inside the ThreadPoolExecutor context.

from qeltrix_v6._clib import get_lib, c_version

# Load and return the ctypes CDLL (singleton — loaded once)
lib = get_lib()

# Version string from the C library
print(c_version())   # e.g. "6.0.0"

# Library search order (auto-detected by _find_lib()):
# Windows:  qeltrix_v6.dll  next to package dir, then ../c_lib/
# Linux:    libqeltrix_v6.so  next to package dir, then ../c_lib/
# macOS:    libqeltrix_v6.dylib  next to package dir, then ../c_lib/

from qeltrix_v6._clib import block_count, block_range, seek_blocks

# How many blocks does a file of file_size bytes need?
n = block_count(file_size=10_000_000, block_size=1 << 20)  # → 10

# Byte range of block N in the original file
# Returns (offset: int, size: int)
off, sz = block_range(block_index=2, file_size=10_000_000, block_size=1 << 20)
# off=2097152, sz=1048576

# Which block indices cover a byte range seek?
# Returns list[int] of block indices needed
blocks = seek_blocks(
    seek_offset=5_000_000, seek_len=500_000,
    file_size=10_000_000,   block_size=1 << 20
)  # → [4] — only block 4 needed

from qeltrix_v6._clib import (
    make_header, make_block_prefix, parse_block_prefix,
    header_size, v6c_size, index_entry_size, block_prefix_size
)

# Write a QLTX file header (returns bytes of size header_size())
hdr = make_header(
    block_size=1 << 20,
    total_blocks=10,
    original_file_size=10_000_000,
    footer_offset=10_500_000,
    footer_size=2048,
    flags=0,
    cipher_default=0,
    encrypted_mk=None,  # bytes or None (zeroed if None)
    mk_iv=None,
    mk_salt=None
)

# Write a 28-byte block prefix (magic + block_index + v6c_size + payload_size)
prefix = make_block_prefix(block_index=0, v6c_size=200, payload_size=50000)

# Parse a 28-byte block prefix back
# Returns (block_index: int, v6c_size: int, payload_size: int)
bidx, v6c_sz, payload_sz = parse_block_prefix(prefix_bytes)

# Size constants (from C struct definitions)
header_size()       # int — QLTX header bytes
v6c_size()          # int — V6-C metadata struct bytes
index_entry_size()  # int — one footer index entry bytes (128 bytes)
block_prefix_size() # int — block prefix bytes (28)

from qeltrix_v6._clib import permute_block, unpermute_block

# Deterministic byte-level permutation keyed to seed (block_hash)
# Applied to compressed data before AES-GCM encryption
permuted   = permute_block(data, seed)    # seed = SHA-256 of original block
original   = unpermute_block(permuted, seed)
# Both implemented in C for speed. Returns bytes of same length as input.

from qeltrix_v6._clib import make_v6c

# Build a V6-C metadata struct (encrypted per-block metadata)
# Returns bytes of size v6c_size()
v6c_bytes = make_v6c(
    block_index=0,
    original_size=1048576,    # plaintext block size
    compressed_size=800000,   # after zlib.compress()
    data_hash=block_hash,      # SHA-256 of original (32 bytes)
    iv=iv,                      # 12-byte nonce (stored in 16-byte field)
    salt=salt,                  # 32-byte HKDF salt
    encrypted_cdk=cdk_blob,   # 64-byte blob: [cdk_iv 12][wrapped_cdk 48][padding 4]
    cipher_id=0                 # 0=AES-256-GCM, 1=ChaCha20-Poly1305
)
# This bytes object is then passed to encrypt_v6c_metadata(v6c_bytes, mk)
# before being written to the container.

# Internal layout of the cdk_blob (64 bytes total):
# [0:12]  cdk_iv       — IV used to AES-GCM wrap the CDK
# [12:60] wrapped_cdk  — AES-GCM(CDK, MK, cdk_iv) = 32 + 16 tag bytes
# [60:64] padding      — zeroed

from qeltrix_v6._clib import _bytes_ptr

# Cast a Python bytes object to a ctypes uint8* pointer
# Required to pass bytes to C functions that expect uint8_t*
ptr = _bytes_ptr(b"raw bytes")
# ctypes.POINTER(ctypes.c_uint8)

# Used internally in every _clib wrapper:
lib.qltx_permute_block(_bytes_ptr(data), len(data), out, _bytes_ptr(seed))

from qeltrix_v6.cli import _mk_from_passphrase

# Derive a 32-byte master key from a passphrase
mk = _mk_from_passphrase("mysecretpassword")

# Equivalent to:
import hashlib
mk = hashlib.pbkdf2_hmac(
    "sha256",
    "mysecretpassword".encode(),
    b"QeltrixV6Salt",   # ← hardcoded PoC salt — see Security Notes
    200_000             # ← 200,000 PBKDF2 iterations
)

from qeltrix_v6.cli import _progress

# Signature: _progress(done: int, total: int) -> None
# Prints:  [████████████████████] 100% (10/10 blocks)

# Use it as progress_cb= in pack() / unpack():
pack("file.txt", "file.qltx", mk, progress_cb=_progress)

# Or write your own:
def my_progress(done, total):
    print(f"Block {done}/{total} done")

pack("file.txt", "file.qltx", mk, progress_cb=my_progress)

from qeltrix_v6.cli import cmd_pack, cmd_unpack, cmd_seek, cmd_info
import argparse

# Call cmd_pack programmatically
ns = argparse.Namespace(
    input="file.txt",
    output="file.qltx",
    passphrase="secret",
    cipher="aes",
    block_size=1024,   # KB
    workers=4
)
cmd_pack(ns)

# Call cmd_info programmatically
cmd_info(argparse.Namespace(input="file.qltx"))

# __main__.py — invoked by `python -m qeltrix_v6`
from .cli import main
main()

# main() builds the argparse parser with all subcommands
# and dispatches to cmd_pack / cmd_unpack / etc.
# Can also be called directly:
from qeltrix_v6.cli import main
main()  # reads sys.argv

Sender:    python -m qeltrix_v6 pack file.pdf file.qltx --passphrase secret
           [share file.qltx via email / USB / cloud storage]
           [share passphrase via Signal / in person]

Receiver:  python -m qeltrix_v6 unpack file.qltx recovered.pdf --passphrase secret

# Get only the first 1 MB of a large encrypted file
Invoke-WebRequest -Uri http://localhost:7621/ `
    -Headers @{ Range = "bytes=0-1048575" } `
    -OutFile first_mb.bin

# Skip to byte 50,000,000 (e.g. seek in a video)
Invoke-WebRequest -Uri http://localhost:7621/ `
    -Headers @{ Range = "bytes=50000000-51048575" } `
    -OutFile video_chunk.bin

# CURRENT (PoC) — hardcoded salt, same passphrase = same MK always
return hashlib.pbkdf2_hmac("sha256", passphrase.encode(), b"QeltrixV6Salt", 200_000)

# PRODUCTION FIX — random salt per container, stored in header
salt = os.urandom(32)
return hashlib.pbkdf2_hmac("sha256", passphrase.encode(), salt, 200_000), salt

from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey
from cryptography.hazmat.primitives.kdf.hkdf import HKDF
from cryptography.hazmat.primitives import hashes

# Node A generates keypair, sends public key to Node B
priv_a = X25519PrivateKey.generate()
pub_a  = priv_a.public_key()

# Node B generates keypair, sends public key to Node A
priv_b = X25519PrivateKey.generate()
pub_b  = priv_b.public_key()

# Both independently derive the same shared secret
shared_a = priv_a.exchange(pub_b)
shared_b = priv_b.exchange(pub_a)

# Derive identical MK on both sides — MK never on the wire
mk_a = HKDF(hashes.SHA256(), 32, None, b"QeltrixV6-MK").derive(shared_a)
mk_b = HKDF(hashes.SHA256(), 32, None, b"QeltrixV6-MK").derive(shared_b)
# mk_a == mk_b  (identical, without ever being transmitted)