Morphball: Secure Archive Manager in Rust

Morphball is a Rust archive manager with a 7z-style CLI and an interactive TUI. It supports .zip, .7z, and .tar.gz / .tgz, with zip-slip path checks on extract.

---

Architecture & Stack

• morphball-core: Library for packing, extraction, listing, and optional self-healing reserves.
• morphball: 7z-styled CLI with colorized progress indicators.
• morphball-tui: Dual-pane interactive file explorer and archive utility.
• Supported Formats: .zip, .7z (LZMA), and .tar.gz / .tgz.

---

Features

• Unix-Philosophic: Modular crates with focused responsibilities.
• Standard Compatibility: Supports 7z-style single-character flags (a, x, l).
• Path Safety: Hardened against classic zip-slip / path-traversal entries.
• Password Support: ZIP (legacy ZipCrypto today; AES planned) and 7z AES.
• Optional Reserves: Self-healing trailers only when MORPHBALL_RESERVES=1 (off by default for interop).

---

Installation

1. Add the Crateria package repo (once per machine)

Debian / Ubuntu / Pop!_OS

sudo mkdir -p /etc/apt/keyrings
sudo curl -fsSL https://crateria.github.io/packages/apt/crateria-keyring.gpg \
  -o /etc/apt/keyrings/crateria.gpg
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/crateria.gpg] https://crateria.github.io/packages/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/crateria.list
sudo apt update

Fedora / RHEL

sudo curl -fsSL https://crateria.github.io/packages/rpm/crateria.repo \
  -o /etc/yum.repos.d/crateria.repo

2. Install morphball

# Debian / Ubuntu / Pop
sudo apt install morphball

# Fedora
sudo dnf install morphball

Cargo

cargo install --git https://github.com/crateria/morphball.git --bin morphball
cargo install --git https://github.com/crateria/morphball.git --bin morphball-tui

---

CLI Usage (7z-Style)

1. Add / Pack Files (a)

Pack a file or folder into an archive:

morphball a <source_folder_or_file> <output_archive.7z>

• Securely prompt for password (preferred):

  morphball a source.txt secure.7z -P

• Avoid putting passwords on the command line (-p) — they leak via process lists and shell history.

2. Extract / Unpack Files (x)

Extract an archive into a destination folder:

morphball x <archive_file> [destination_folder]

(If no destination is specified, it extracts to the current directory).

• Extract password-protected archive:

  morphball x secure.7z -P

3. List Archive Contents (l)

View files and directories contained in an archive without extracting:

morphball l <archive_file>

Optional self-healing reserves

MORPHBALL_RESERVES=1 morphball a ./src backup.zip
morphball doctor backup.zip

Self-extracting artifacts

SFX auto-unpack is disabled by default. To run an SFX binary’s embedded payload:

MORPHBALL_SFX_AUTO=1 ./my-chozo-artifact

Payload extracts into ./morphball-sfx-<pid>/ (not the raw CWD root).

---

Interactive TUI Usage

morphball-tui
# or: morphball tui

• Tab: Switch panes.
• Up / Down: Select items.
• C: Compress the selected folder/file.
• X: Extract the selected archive.
• Q / Esc: Quit.

---

License

Licensed under the Apache License, Version 2.0. Copyright 2026 crateria.