BaseFWX is a hybrid post-quantum + AEAD encryption toolkit for files and media. It ships in three implementations (Python, C++, Java) that share the same on-disk and on-wire formats, so a file you encrypt in one binds out the other two without conversion.

Repository policy:

• main is the release branch; DEV is the integration branch.

• It stays a monorepo. There are no language-specific long-lived branches.

• Shared format and security changes have to keep Python / C++ / Java parity in one PR.

• Website: https://basefwx.fixcraft.jp

• Documentation: https://basefwx.fixcraft.jp/docs/CLI

• Source code: https://github.com/F1xGOD/basefwx

• Contributing: https://basefwx.fixcraft.jp/docs/CONTRIBUTING

• Bug reports: https://github.com/F1xGOD/basefwx/issues

• Report a security vulnerability: https://basefwx.fixcraft.jp/docs/SECURITY_MODEL

What's in the box:

• AES-256-GCM payloads with optional ML-KEM-768 master-key wrapping
• Password-based encryption via Argon2id (recommended) or PBKDF2
• fwxAES file format with an optional normalize wrapper that hides bytes in zero-width Unicode markers
• A packetized live-stream API so fwxAES works inside ffmpeg/SIP/transport pipes
• b512 / pb512 reversible encodings and file modes
• kFM media-carrier codecs: embed bytes in PNG or WAV files, strict decode on the way back
• jMG media cipher for images and audio. Video is temporarily disabled by default; set BASEFWX_ENABLE_JMG_VIDEO=1 to opt in.
• C++ and Java libraries + CLIs that read and write the same formats as the Python module

Quick Start

pip install basefwx
python -m basefwx cryptin aes-light file.bin -p "password" --strip
python -m basefwx cryptin aes-light file.bin.fwx -p "password"
python -m basefwx n10-enc "hello"
python -m basefwx n10-dec "<digits>"
python -m basefwx kFMe photo.png -o photo.wav            # image/media -> audio carrier
python -m basefwx kFMe track.mp3 -o track.png --bw       # audio -> image carrier
python -m basefwx kFMd photo.wav -o photo-restored.png   # strict decode
python -m basefwx kFMd track.png -o track-restored.mp3
python -m basefwx cryptin fwxaes video.mp4 -p "password"            # Python default: no-archive
python -m basefwx cryptin fwxaes video.mp4 -p "password" --archive  # exact-restore trailer

Notes:

• kFMd only decodes BaseFWX carriers; it refuses plain WAV/PNG/MP3/M4A files.
• kFAe / kFAd remain available as deprecated aliases to kFMe / kFMd.
• Release support policy is single-version: only the latest release is maintained; all older releases are immediately unsupported.
• Optional kFM/kFA acceleration:
  • BASEFWX_KFM_ACCEL=auto|cuda|cpu (default auto)
  • BASEFWX_KFM_ACCEL_MIN_BYTES=<bytes> (default 1048576, auto mode threshold)
• CLI progress now includes live system telemetry (CPU/GPU/RAM/I/O/TEMP when available). Disable with BASEFWX_PROGRESS_TELEMETRY=0.
• Python n10 was optimized for large payloads, but compiled runtimes (C++/Java) are still expected to benchmark faster for very large text workloads.
• C++/Java CLI global flags: --no-log (suppress non-essential logs) and --verbose (show hardware routing reasons).
• jMG video is disabled by default in Python/C++/Java; set BASEFWX_ENABLE_JMG_VIDEO=1 to re-enable temporarily.
• Canonical release assets are architecture-qualified only; alias artifacts without arch suffixes are intentionally not published.
• Every GitHub release includes detached signatures, checksum files, and release-manifest.json.

Python API quick refs:

from basefwx import n10encode, n10decode, n10encode_bytes, n10decode_bytes
from basefwx import kFMe, kFMd
from basefwx import LiveEncryptor, LiveDecryptor, jMGe, jMGd

digits = n10encode("hello")
text = n10decode(digits)
blob_digits = n10encode_bytes(b"\x00\x01\x02")
blob = n10decode_bytes(blob_digits)

carrier = kFMe("input.mp3", output="input.png", bw_mode=True)
restored = kFMd("input.png", output="restored.mp3")

# jMG Python default is no-archive (smaller, non-byte-identical restore)
jMGe("clip.m4a", "password", output="clip.small.m4a")
jMGe("cover.png", "password", output="cover.exact.png", archive_original=True)
jMGd("clip.small.m4a", "password", output="clip.out.m4a")

# Live packetized stream encryption/decryption
enc = LiveEncryptor("password", use_master=False)
dec = LiveDecryptor("password", use_master=False)
wire = [enc.start(), enc.update(b"chunk-1"), enc.update(b"chunk-2"), enc.finalize()]
plain_chunks = []
for packet in wire:
    plain_chunks.extend(dec.update(packet))
dec.finalize()

# ffmpeg pipe helpers for live media transport
from basefwx import fwxAES_live_encrypt_ffmpeg, fwxAES_live_decrypt_ffmpeg
fwxAES_live_encrypt_ffmpeg(
    ["ffmpeg", "-hide_banner", "-loglevel", "error", "-i", "input.m4a", "-f", "matroska", "-c", "copy", "-"],
    "stream.live.fwx",
    "password",
    use_master=False,
)
fwxAES_live_decrypt_ffmpeg(
    "stream.live.fwx",
    ["ffmpeg", "-hide_banner", "-loglevel", "error", "-y", "-f", "matroska", "-i", "-", "-c", "copy", "restored.mkv"],
    "password",
    use_master=False,
)

Hardware acceleration (Python jMG):

• BASEFWX_HWACCEL=auto (default), nvenc, qsv, vaapi, or off
• BASEFWX_HWACCEL_STRICT=1 to fail instead of CPU fallback when requested accel is unavailable

Optional extras:

pip install basefwx[argon2]

Documentation

• Docs home (HTML)
• CLI and usage
• Security model
• Testing and benchmarks
• Contributing and code of conduct
• Java module
• Compatibility matrix

License

See https://basefwx.fixcraft.jp/LICENCE.