Metadata-Version: 2.4
Name: zxtx
Version: 0.2.0
Summary: ZXTX file format support.
Home-page: https://github.com/voyager-2021/zxtx
Author: voyager-2021
Author-email: voyager-2019@outlook.com
License: MIT
Project-URL: Documentation, https://github.com/voyager-2021/zxtx#readme
Project-URL: Source, https://github.com/voyager-2021/zxtx
Project-URL: Issues, https://github.com/voyager-2021/zxtx/issues
Keywords: compression,encryption,file-format,zxtx,cryptography
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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: Topic :: File Formats
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=45.0.1
Requires-Dist: brotli>=1.1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.3.5; extra == "dev"
Requires-Dist: black>=25.1.0; extra == "dev"
Requires-Dist: mypy>=1.15.0; extra == "dev"
Requires-Dist: isort>=6.0.1; extra == "dev"
Requires-Dist: pydocstyle>=6.3.0; extra == "dev"
Requires-Dist: pylint>=3.3.7; extra == "dev"
Requires-Dist: bandit>=1.8.3; extra == "dev"
Requires-Dist: safety>=3.5.1; extra == "dev"
Requires-Dist: flake8>=7.2.0; extra == "dev"
Requires-Dist: tox>=4.26.0; extra == "dev"
Requires-Dist: coverage>=7.8.1; extra == "dev"
Requires-Dist: pytest-cov>=6.1.1; extra == "dev"
Requires-Dist: pre-commit>=4.2.0; extra == "dev"
Requires-Dist: twine>=6.0.1; extra == "dev"
Requires-Dist: build>=1.2.2.post1; extra == "dev"
Provides-Extra: opt
Requires-Dist: rich>=14.0.0; extra == "opt"
Provides-Extra: docs
Requires-Dist: sphinx>=8.2.3; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=3.0.2; extra == "docs"
Requires-Dist: sphinx-autobuild>=2024.10.3; extra == "docs"
Dynamic: license-file

# ZXTX

[![Test status](https://github.com/voyager-2021/zxtx/actions/workflows/tests.yml/badge.svg)](https://github.com/voyager-2021/zxtx/actions/workflows/tests.yml)

**ZXTX** is a secure, compressed, and verifiable file format for structured text and binary data. It supports optional encryption, compression, and cryptographic signing, making it ideal for transmitting sensitive files safely.

> Built in Python. Powered by `cryptography`.

## Features

- **AES-256-CTR + HMAC** authenticated encryption
- **LZMA** and **Zlib** compression support
- **Ed25519** and **RSA** signing and verification
- **Structured file format** with typed headers and bodies
- **Command-line interface (CLI)** for reading, writing, and inspecting `.zxtx` files

## Installation

```bash
pip install zxtx
```

Or with [PDM](https://pdm.fming.dev):

```bash
pdm add zxtx
```

## Usage

### Writing a ZXTX file

```bash
zxtx write input.txt output.zxtx --cipher aes256_gcm --compression zlib --private-key mykey.pem --certificate mycert.pem
```

### Reading a ZXTX file

```bash
zxtx read example.zxtx output.txt --private-key mykey.pem --public-key pubkey.pem
```

### Dumping metadata

```bash
zxtx dump example.zxtx --public-key pubkey.pem
```

### Streaming (stdin/stdout)

ZXTX supports streaming via `-` for stdin/stdout, enabling pipe chains:

```bash
# Encrypt from stdin, write to file
echo "secret data" | zxtx write - output.zxtx --cipher aes256_gcm

# Read from file, write to stdout
zxtx read input.zxtx - > output.txt

# Full pipe chain: encrypt, then decrypt
cat data.txt | zxtx write - - --cipher aes256_gcm | zxtx read - - > decrypted.txt
```

### Signature Verification

Verify signatures during read operations:

```bash
zxtx read signed.zxtx output.txt --verify --certificate cert.pem
```

### Interactive Password Prompt

If a private key is password-protected and no password is provided, ZXTX will prompt interactively:

```bash
zxtx read encrypted.zxtx output.txt --private-key mykey.pem
# Prompts: Enter private key password (or press Enter for none):
```

### Progress Bars

When writing to files in an interactive terminal, ZXTX displays progress bars:

```bash
zxtx write largefile.bin output.zxtx --compression lzma
# Shows: Writing ZXTX file [████████████] 100%
```

---

## Supported Methods

### Cipher Methods
- `none`
- `aes256_gcm`
- `chacha20_poly1305`

### Compression Methods
- `none`
- `zlib`
- `lzma`
- `brotli`

## Format Specification

The ZXTX file format is formally documented in [`SPECIFICATION.md`](https://github.com/voyager-2021/zxtx/blob/master/SPECIFICATION.md). It defines:

- Magic header
- Versioning
- Field layout
- Signature embedding, etc

## Security Notes

- ZXTX uses AEAD (authenticated encryption) to prevent tampering.
- Private keys can be password-encrypted.
- Signature verification ensures authenticity.
- Don't share your private key. Use a certificate for signing and a public key for verification.

## Python API

### Basic File Operations

```python
from zxtx.highlevel import open

with open("file.zxtx", password=b"secret", public_key=b"...") as f:
    data = f.read_bytes()
```

### Streaming API

Stream data without loading entire files into memory:

```python
from zxtx.highlevel import read_stream, write_stream, read_stdin, write_stdout

# Read from any binary stream
with open("input.zxtx", "rb") as f:
    data = read_stream(f, private_key=private_key)

# Write to any binary stream
with open("output.zxtx", "wb") as f:
    write_stream(b"secret data", f, cipher=CIPHER_METHOD.AES256_GCM, public_key=public_key)

# Convenience functions for stdin/stdout
data = read_stdin(private_key=private_key)
write_stdout(b"data", cipher=CIPHER_METHOD.AES256_GCM, public_key=public_key)
```

### Chunked Streaming for Large Files

Process large files in chunks to minimize memory usage:

```python
from zxtx.highlevel import read_stream_chunked, write_stream_chunked

# Stream large file with progress callback
with open("large_input.bin", "rb") as infile, open("output.zxtx", "wb") as outfile:
    def progress(current, total):
        print(f"Processed: {current}/{total} bytes")

    write_stream_chunked(
        infile, outfile,
        compression=COMPRESSION_METHOD.ZLIB,
        chunk_size=1024*1024,  # 1MB chunks
        progress_callback=progress
    )

# Read back with chunked streaming
with open("output.zxtx", "rb") as infile, open("recovered.bin", "wb") as outfile:
    read_stream_chunked(infile, outfile, private_key=private_key)
```

See the `zxtx.highlevel` module for full API details.

## License

#### [`MIT License`](https://github.com/voyager-2021/zxtx/blob/master/LICENSE) – Copyright (c) 2025 voyager-2021 (ZXTX)
