arctgz ·

arctgz is a safety‑first Rust library for the arctgz archive format.
It provides a complete, cross‑platform lifecycle for projects: scaffold, configure, compile (with integrity verification and optional encryption), extract, verify, delta patch, and execute post‑extraction recipes.
Table of Contents
- Installation
- Quick Start
- API Reference
- Type Reference
- File Formats
- Security
- Environment Variables
- Testing
- Contributing
- License
Installation
The library is not yet published on crates.io. To use it, add the Git repository as a dependency in your Cargo.toml:
[]
= { = "https://github.com/mroczect/arctgz.git", = "v0.8.0" }
Always pin to a specific tag (like v0.8.0) to avoid unexpected breaking changes.
Quick Start
use ;
use Path;
For encryption, signatures, delta patching, and recipes, see the detailed sections below.
API Reference
All public functions reside in the crate root (arctgz::).
Initialisation & Configuration
init
Creates a new arctgz project at project_path.
- Creates the directory (and parents) if needed.
- Creates an empty
include/subdirectory. - Writes a default
arctgz.initfile atomically. force– iftrue, allows initialisation into a non‑empty directory. An existingarctgz.initstill causesAlreadyInitialized.- Security – the canonicalised path must lie under the user’s home directory. No filesystem changes occur before validation.
load_config
Reads and validates the arctgz.init file from a project directory.
Returns ConfigNotFound if missing, ConfigLoadError for I/O or JSON issues, or ConfigValidation if the config fails validation.
save_config
Atomically writes a validated configuration back to arctgz.init (temp file + rename).
Automatically calls config.validate() before writing.
Archive Operations
compile
Compiles the project into an .artgz archive.
Behaviour:
- Loads the project configuration.
- Collects files from
include/using glob patterns (e.g.**/*.rs). Empty directories matching patterns are preserved. - Recursively walks the
include/directory; symbolic links are rejected. - Hashes every file in parallel (SHA‑512) using
rayon. - Builds a
manifest.jsonentry with size, hash, and directory flags. - Optionally signs the manifest with an Ed25519 private key (the signature is stored as a hex string in the manifest).
- Compresses the tar stream with the configured compression (
GziporZstd). - If encryption is enabled (
Encryption::Aes256Gcm), encrypts the whole archive after compression. - Writes atomically via a temporary file.
output_path – if None, defaults to <project_path>/archive.artgz.
force – overwrite an existing output file.
private_key – 32‑byte Ed25519 secret key; if Some, the manifest will be signed.
password – must be Some if config.encryption == Aes256Gcm.
extract
Extracts and verifies an archive.
- Automatically detects compression (gzip/zstd) and encryption (AES‑256‑GCM magic bytes).
- If encrypted, the archive is decrypted on‑the‑fly to a temporary file.
- Verifies the Ed25519 signature if a public key is supplied.
- Validates every file’s SHA‑512 hash and size against the manifest.
- Rejects unsafe paths (absolute,
.., empty,.). - Cleans up partially written files on hash mismatch.
forcecontrols overwriting of existing files.
verify
Standalone integrity check. Reads the archive, verifies every file’s hash and size, ensures manifest consistency, checks for unsafe paths, and optionally verifies a signature and decrypts. No files are written.
Delta Patching
diff
Computes a binary delta between two archives. Ignores metadata files (arctgz.init, recipe.json).
Returns an ArctgzDelta containing the minimal set of Add, Modify, and Delete operations.
patch
Applies a previously computed delta to the base archive, producing a new archive identical to the original target.
- Copies unchanged files from the base.
- Takes modified or added files from the target.
- Validates integrity of both source archives before writing.
- Optionally signs the resulting manifest.
Recipe Management
load_recipe
Loads and validates recipe.json from a project directory. Returns None if the file is absent.
extract_recipe
Extracts and validates the embedded recipe.json from an archive. Handles all compression and encryption transparently.
execute_recipe
Runs the steps of a recipe inside output_dir. Supported steps: Copy, MkDir, Chmod (Unix only, error on other platforms), Remove.
- All paths are validated against traversal (absolute,
.., empty,.). forcecontrols whether existing files/directories are overwritten.
Type Reference
ArctgzConfig
Serialised with #[serde(deny_unknown_fields)] – unknown keys cause an error.
ArctgzManifest
Embedded in every archive as manifest.json.
FileEntry
ArctgzRecipe
Serialised with deny_unknown_fields.
RecipeStep
Tagged with "action" in JSON.
Compression
Encryption
ArctgzDelta
DeltaOp
Tagged with "op" in JSON.
ArctgzError
All errors implement Display with human‑readable messages.
File Formats
Project Configuration (arctgz.init)
include– array of glob patterns relative to theinclude/directory.compression–"gzip"or"zstd".encryption–"None"or"Aes256Gcm".- All fields are required; unknown fields cause an error.
Recipe File (recipe.json)
- Steps are executed in order.
chmodis only available on Unix; on other platforms it returns an error.
Delta File (ArctgzDelta JSON)
Security
- Path confinement:
initensures projects are created inside the home directory. - No side effects before validation: directory creation and file writes only happen after all checks pass.
- Atomic writes: configuration, archives, and temporary files use
create_new(true)or temp+rename patterns. - Archive integrity: SHA‑512 hashes are verified for every file (and file size) during
extractandverify. - Ed25519 signatures: optional manifest signing with 32‑byte keys; verification on extract/verify.
- AES‑256‑GCM encryption: optional encryption of the entire archive with a password; key derived via Argon2.
- Path traversal prevention:
extract,verify, and recipe steps reject absolute paths,.., empty strings, and.. - Symlink rejection: symbolic links are never included in archives.
- Strict JSON validation: unknown fields in configuration and recipe files are rejected.
Environment Variables
HOME(Unix) /USERPROFILE(Windows) – used byinitfor home directory confinement.
Testing
Run all tests (unit + integration) with:
CI runs formatting, linting, build, and tests on Linux, macOS, and Windows (including 32‑bit Linux).
Contributing
Please read CONTRIBUTING for guidelines on code style, commit messages, pull request process, and more.
License
This project is licensed under the MIT License.