Skip to main content

KRANSX

PyPI Python 3.10+ License: MIT

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
  • --aad takes hex-encoded bytes.
  • --max-output-size caps plaintext size on open.
  • Output files are created exclusively and never overwritten.
  • bench reruns 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=False when in doubt.
  • Resource limits. max_output_size bounds decompressed output. For untrusted input, also cap the encrypted bytes before calling open_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)

Source distribution for kransx 0.2.1
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)

Table of built distributions (wheels) for kransx 0.2.1
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page