KRANSX
import secrets
from kransx import open_data, seal
key = secrets.token_bytes(32)
sealed = seal(b"hello world", key, aad=b"record-42")
assert open_data(sealed, key, aad=b"record-42") == b"hello world"
KRANSX picks the smallest of Zstandard, LZMA-6, and raw for every payload, then encrypts the winner with AES-256-GCM-SIV. Fixed cost: 29 bytes per envelope (1 suite + 12 nonce + 16 tag). Wrong key, wrong associated data, wrong dictionary, or modified bytes fail with cryptography.exceptions.InvalidTag. Malformed envelopes fail with ValueError before anything decrypts.
Installation
pip install kransx
Development setup:
uv sync --locked --extra dev
Requires Python 3.10+, cryptography >= 42, zstandard >= 0.22.
Measured behavior
Each line below is decided by a checked-in command that exits non-zero when broken.
| Behavior | Evidence | Command |
|---|---|---|
| Sealed output never exceeds the best single codec plus 29 bytes | 8 corpora, worst margin 0 | kransx bench |
| Overhead is exactly 29 bytes, empty to 1 MB | 8 sizes, all raw suite | kransx bench |
| Small JSON records seal 45% smaller with a trained dictionary | ratio 0.552 vs 0.85 gate, 5,000 records | uv run python bench/bench_claim_c1_dict.py |
| Tamper at any envelope offset is rejected | tamper and failure matrix, exact exceptions | uv run pytest -q (71 tests) |
Python API
| Method | Functionality |
|---|---|
seal |
Compresses the payload with the codec tournament, then encrypts the winner into a 29-byte-overhead envelope. |
open_data |
Authenticates the envelope, decrypts it, and decompresses the payload without exceeding max_output_size. |
train_dict |
Learns a Zstandard dictionary from sample payloads so small, similar messages compress smaller. |
save_dict / load_dict |
Writes a trained dictionary to disk and reads it back for reuse across runs. |
compress=True runs the tournament and keeps the strictly smallest payload. Raw wins every tie, so incompressible input grows by exactly the 29-byte floor and nothing more. max_output_size caps decompressed output. Structural problems raise ValueError. Authentication problems raise InvalidTag and release no plaintext.
Shared dictionaries are non-secret compression aids for similar payloads:
from kransx import train_dict
dictionary = train_dict([b'{"user":1,"action":"login"}'] * 300)
sealed = seal(b'{"user":1,"action":"login"}', key, dict_obj=dictionary)
assert open_data(sealed, key, dict_obj=dictionary) == b'{"user":1,"action":"login"}'
A mismatched dictionary fails authentication before decompression starts.
CLI
kransx keygen key.bin
kransx seal plain.bin sealed.bin --key-file key.bin --aad 7265636f72642d3432
kransx open sealed.bin restored.bin --key-file key.bin --aad 7265636f72642d3432
kransx train 'samples/*.json' --output model.dict
kransx seal plain.bin out.bin --key-file key.bin --dict model.dict
kransx open out.bin restored.bin --key-file key.bin --dict model.dict --max-output-size 1048576
kransx bench
--aadtakes hex-encoded bytes.--max-output-sizecaps plaintext size on open.- Output files are created exclusively and never overwritten.
benchreruns the A+B claim gates and fails non-zero on any regression.
Design
Envelope layout: suite (1) | nonce (12) | ciphertext | tag (16).
| Suite | Payload | Authenticated associated data |
|---|---|---|
0x21 |
Zstandard frame | suite + dictionary binding + aad |
0x22 |
raw bytes | suite + aad |
0x23 |
LZMA bytes (preset 6) | suite + no-dictionary binding + aad |
The dictionary binding is SHA-256 over the dictionary bytes, or over a fixed constant when no dictionary is used. Keys are 32 random bytes expanded through HKDF-SHA-256 to the AEAD key. Every seal generates a fresh 12-byte nonce. Opening checks size and suite first, authenticates second, and only then decompresses under the output cap: single Zstandard frame or a bounded LZMA stream, trailing bytes rejected either way.
Security
This library is the envelope only. Key generation, distribution, storage, rotation, and bounding encrypted-input size stay with the caller.
- Keys must be 32 uniformly random bytes. Passwords are not valid keys.
- Nonces come from
os.urandom(12)per seal. AES-GCM-SIV tolerates reuse better than most modes, but do not reuse them. - Compression oracles. Sealed size reveals which suite won. Never compress secrets mixed with attacker-controlled input without application-level separation. Pass
compress=Falsewhen in doubt. - Resource limits.
max_output_sizebounds decompressed output. For untrusted input, also cap the encrypted bytes before callingopen_data.
This is an implementation with conformance vectors and tamper coverage, not an external audit.
Development
uv sync --locked --extra dev
uv run ruff check .
uv run mypy kransx
uv run pytest -q
Layout: kransx/ holds seal, open, dicts, cli. tests/ holds conformance vectors, tamper checks, resource limits. bench/ holds the claim gates and their result snapshots.
License
MIT — see LICENSE.
Changelog
See CHANGELOG.md.
Metadata
Release files for kransx 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kransx-0.2.1.tar.gz | 15.3 kB | Without provenance | Details for kransx-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kransx-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for kransx-0.2.1-py3-none-any.whl |
Total release size: 25.2 kB
Release files / kransx-0.2.1.tar.gz
| Download URL | kransx-0.2.1.tar.gz |
|---|---|
| Size | 15.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
66f45593cd3b4edefc2a3e6ee3e46178a372fea03ea97b5a1a5b923ca39bb0c0
|
|
BLAKE2b-256 checksum How to use checksums |
981976333b2549dea3b83ebd4f24747a7be086bb9a3a384203c7fdcb444fa42c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / kransx-0.2.1-py3-none-any.whl
| Download URL | kransx-0.2.1-py3-none-any.whl |
|---|---|
| Size | 9.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
622ee6eae2e997e171746fcf77348ccf0628900c6840dd5adb38fda6d38d799c
|
|
BLAKE2b-256 checksum How to use checksums |
76af72a1d68aae365502b0856e3acafca314e4d079539743d15b318e8c140f5e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for kransx 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.